vault-lint

# 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