lint

name	lint
description	Health-check the vault's wiki (Axis 1): report where it bleeds — dangling [[links]], orphan notes nobody links to, stale entity pages left behind by fresher notes, and malformed frontmatter. Runs a deterministic scanner and reads its binary report, then proposes (never silently applies) fixes. Triggered by '/lint', 'lint my vault', 'check my wiki health', 'what links are broken', 'où mon wiki fuit', 'vérifie la santé de mes notes'.
version	1.0.0

lint — wiki-health check ("where is my wiki bleeding?")

The retrieval side of the brain (the RAG) is a versioned, tested engine. The curation side — keeping the wiki itself healthy: links that resolve, notes woven in, entity pages kept fresh — is this skill's job. It is the deterministic half of the Karpathy "LLM-Wiki compile" discipline (see ADR 0033): the scan is exact and fail-loud; the judgment of what to fix is yours (and the user's).

Principle

One promise: an honest, binary health report of the vault, then help acting on it.

• The scan is deterministic (ADR 0009): pure code over the parsed notes, no LLM guessing.
• The fixes are proposed, never silently written (the brain's write posture): surface the problem, suggest the gesture, let the user say yes.

Procedure

1. Run the scanner

From the brain folder:

node scripts/lint-vault.mjs

• Exit 0 = clean (say so plainly, do not invent problems).
• Exit 1 = issues found; the report lists them by category. Read it verbatim.
• To check a different path: node scripts/lint-vault.mjs <vault-dir>.

2. Read the report — four categories

• Dangling links from → [[target]]: a [[link]] whose target note does not exist. Usually a typo, a renamed/moved note, or a note that was meant to be written and never was.
• Orphans: a note with zero inbound links (raw-capture zones daily/, raw-sources/, inbox/ are already excluded — they are legitimately unlinked). An orphan is knowledge that is filed but never woven in, so the wiki (and the RAG's neighbourhood signal) can't reach it.
• Stale entity pages: a curated entity page (type: person|topic|company|project|concept) whose updated: trails the freshest note that cites it by more than the threshold (default 90 days). The world moved on; the canonical page didn't.
• Frontmatter issues: a note missing a required key (type / created / updated / tags), so it indexes and sorts poorly.

3. Propose fixes (never apply silently)

Group the findings and, for the ones worth acting on, suggest the concrete gesture and ask before writing:

• Dangling → fix the target spelling, or create the missing note (offer to synthesize it from the vault, like open-note does), or remove the dead link.
• Orphan → propose where to weave it in: which existing note(s) should gain a [[link]] to it, or which entity/topic page it belongs under.
• Stale entity page → offer to refresh it from the fresher notes that cite it (a Track-C consolidation gesture) and bump updated:.
• Frontmatter → offer to add the missing keys (run date for correct created/updated).

Prioritise: dangling links and frontmatter are cheap, high-signal fixes; orphans and stale pages are judgment calls — present them, don't force them.

Guardrails

• Report first, write never-without-consent. This skill diagnoses; it does not rewrite the vault on its own.
• Trust the exit code. 0 means clean — do not manufacture findings to look useful.
• Do not run git (the auto-commit hook persists any accepted change).
• The scanner is read-only and offline (no network, no LLM): safe to run anytime.

Out of scope

• Bulk auto-fixing the whole vault unattended (a future, explicit gesture).
• Contradiction detection between a note and an entity page's stated fact (needs LLM judgment — a later track).