vault-lint

What this skill does

# Lint Vault

Run a focused hygiene pass over active vault surface and propose fixes.

Portent reference: `../references/portent-knowledge-base-spec.md`.

## Recency Priority

Work the active surface newest-first, ranked by each object's `updated`
frontmatter date (fall back to file modification time when `updated` is absent).
Concentrate scrutiny on the freshest material — recently-touched objects are
where active thinking lives and where new mismatches, overlaps, and gaps appear.
Long-untouched objects are assumed settled and rank lower, but are never
excluded: they remain valid link targets, merge destinations, and canonical
homes, and still get a structural check (broken links, orphaning).

For this pass, order the issue list newest-first: a fresh file's issue outranks
an older file's equivalent issue when reporting and when choosing what to apply.

## Parameters

- `--scope notes|projects|all` (default: `all`)
- `--mode report|apply` (default: `report`)

## Checks

- **Orphan pages**: No inbound links from active surface
- **Stale pages**: `updated` date threshold + topic inactivity
- **Contradictions**: Conflicting claims across related notes
- **Broken/ambiguous wikilinks**: Invalid or unclear [[links]]
- **Connection candidates**: Notes that should be linked to strengthen the
  knowledge graph over time
- **Missing concepts**: Repeated themes without canonical page
- **Mismatched states**: Project directory location vs Portent metadata and
  active navigation
- **Merge candidates**: Duplicate or overlapping notes, ideas, or projects that
  should probably be one durable item
- **Unbacked synthesis**: Summaries or briefs without links to complete archived
  source records
- **External tag drift**: Clipped source notes missing `external`, or owned
  notes incorrectly tagged `external`
- **Portent object validity**: missing `title`, invalid `type`, invalid
  `status`, malformed `belongs_to`, malformed `related_to`
- **Organized-without-usefulness**: `status: organized` objects without any
  relationship when a Project, Responsibility, Operation, or Topic target is
  obvious
- **Archive visibility drift**: `status: archived` objects still shown in active
  `index.md` views
- **Folder/metadata mismatch**: folder location contradicts type, status, or
  stage; treat as a navigation smell, not automatic truth
- **Custom model drift**: custom types or custom relationships that duplicate
  Portent defaults

## Scope

- **notes/**, **ideas/**, and **projects/** by default (exclude archive/ unless
  explicitly requested)
- Does NOT move files (use `vault-tracker` for lifecycle changes)
- Does NOT delete content
- Does NOT merge files automatically; proposes merge plans for review
- Does NOT add speculative graph links; only high-confidence links are applied

## Workflow

1. Scan scoped directories and build issue list with file references.
2. Classify by severity: info, warning, critical.
3. In `report` mode: list issues and proposed fixes only.
4. In `apply` mode: fix link issues, flag decisions needing manual review.
5. Find connection candidates:
   - unlinked notes sharing a named project, idea, concept, source, or decision
   - notes that explicitly mention another note title or alias without a
     wikilink
   - external source records that support a project, idea, or concept
   - orphan pages with an obvious parent, project, concept, or resource
6. In `apply` mode: add high-confidence contextual links and backlinks.
7. Call out concept-promotion candidates (themes appearing 3+ times).
8. Report idea lifecycle issues:
   - duplicate ideas across `fleeting/`, `incubating/`, `someday/`, `rejected/`
   - stale incubating ideas without next action
   - project-like ideas that may need lifecycle promotion
9. Report merge candidates:
   - exact duplicates or near-duplicates
   - continuation notes that extend the same idea/project
   - split notes whose boundaries are accidental rather than useful
10. Report summaries or research briefs that do not cite complete sources under
    `raw/processed/YYYY-MM-DD/`.
11. Report tag issues:

- likely clipped/source notes missing `external`
- owned ideas, project drafts, or plans incorrectly tagged `external`

12. Report mismatched project states for lifecycle handling.
13. Summarize outcomes.

## Connection Candidate Rubric

Add links to build the knowledge graph when the relationship is concrete and
useful for future navigation.

- **High confidence**: direct title/alias mention, shared source URL, explicit
  parent/child relation, project material linked to its project, research source
  supporting a specific project/idea/concept, or concept page named by the note.
- **Medium confidence**: strong topical overlap or recurring phrase, but the
  relationship label is unclear.
- **Low confidence**: same broad domain, weak semantic similarity, or link would
  be decorative.

Apply-mode link additions must be contextual: add the wikilink near the relevant
claim, heading, source, or `Related` section. If no natural location exists,
report the candidate instead of forcing a link.

Prefer linking over merging when notes are related but distinct. Prefer concept
links over many point-to-point links when a concept page is the better hub.

## Merge Candidate Rubric

- **High confidence**: same title/slug, same source URL, same project or idea
  identity, or one note explicitly says it continues another.
- **Medium confidence**: heavy topical overlap with compatible claims, but
  uncertain destination or lifecycle state.
- **Low confidence**: same broad area but distinct decisions, audiences, or
  implementation paths.

High-confidence candidates may be passed to `vault-ingest`, `vault-tracker`, or
`vault-concepts` for apply-mode merging. Medium/low candidates should stay as
separate notes with proposed links.

## Portent Apply Constraints

In apply mode, Portent fixes are limited to mechanical corrections:

- normalize valid scalar/list YAML shapes
- add missing `title` from H1 when exact
- add `status: organized` only when type and relationships are already clear
- add high-confidence `related_to` links where the object explicitly names the
  target

Do not infer broad relationships or change object type in apply mode unless the
user explicitly requested that conversion.

## Safety

- Report-first by default on all ambiguous issues.
- Never delete content or move files.
- Never collapse distinct ideas just because they share keywords.
- Never add links based only on keyword overlap.
- Never modify raw/, processed/, or assets/.
- Exclude archive/ from automatic scans.

## Output

Return:

- Issue list with severity and file references
- Fixes applied (link corrections only)
- Decisions requiring manual review
- Concept promotion candidates
- Connection candidates and links added
- Mismatched project lifecycle states
- Idea lifecycle issues and duplicate idea candidates
- Merge candidates with target, confidence, and rationale
- Synthesis notes missing archived source links
- External tag drift findings
- Portent object validity, relationship, archive visibility, and custom model
  drift findings