Lint

lint — knowledge-graph health check

Goal

Find the rot that accumulates as a knowledge base grows: dead links, orphans, unindexed pages, unresolved conflicts.

When to run (and when not)

Don't lint routinely after a normal ingest — ingest/query leave the graph integrity-clean by construction (CLAUDE.md §6). Run lint for drift (manual edits/renames/deletes in Obsidian, external or OneDrive/git sync changes) and periodic discovery (emerging gap pages, cross-corpus contradictions, stale claims).

Scope boundary: confidence coverage, staleness scoring, and online-source freshness are not lint's job — they live in the heavier, ~monthly deep-lint. Routine /lint stays cheap and never reads pages for confidence or fetches anything.

Triggers

/lint · /health · /scan · "check my wiki" · "find broken links / orphans / gaps".

Pipeline (read-only until the user approves fixes)

1 — Index consistency (one scripted check)

Run python3 .claude/skills/lint/check-index.py --vault . (exit 0 = the probe ran, findings or none; 2 = broken premise). It compares wiki/index.md with the pages on disk and prints three lists with their counts: unindexed pages (on disk, registered by no - [[…]] entry), dangling index entries (registered, no page on disk) and duplicate entries (the same target registered twice). The rules are deep-lint audit-pools.py's, copied so a reader can check them against it: resolution on the basename with or without .md, index.md and log.md excluded as pages, and a page's frontmatter aliases: counting as a resolution on both sides (one deliberate departure from audit-pools, which aliases the dangling side only). It prints SCANNED: <pages> pages · <entries> index entries as its own positive control (§11): a root it cannot scan ends in PROBE FAILED and exit 2 before any list prints, so a clean result always carries non-zero counts. Copy the three figures into the report — never re-derive them by hand. Shared stems are printed as information, not a finding.

2 — Link health (one shared script — the single source of truth for link rules)

Run python3 .claude/skills/lint/check-links.py (exit 0 = clean, 1 = findings; deep-lint's structural pass uses the same script). It applies the codified rules so scans never re-derive them: code spans / fenced blocks / HTML comments are not links; frontmatter aliases resolve; vault-path and root-doc targets resolve; wiki/log.md is exempt as a source (append-only history); and media embeds ![[name.png|pdf|…]] are checked against assets/ — a missing target is a dead embed, reported separately (they are checked, not skipped). The script prints its scan totals as its own positive control (§11): zero findings with zero links scanned is a broken probe, not a clean vault.

• The same script resolves each page's frontmatter sources: entries against disk and reports dangling sources separately from dead links: one line per page · path, with SOURCES SCANNED: as that arm's control. A URL, prose provenance (email: …, session: …) and an entry that declares its own deletion (path (deleted YYYY-MM-DD)) are counted, never flagged — provenance written as prose is legitimate. An entry the parser could not read prints as (empty or unparsed sources) inside the same block: read it, since it is the parser's own gap detector, not a dangler. A ~- or /-led entry is provenance outside the vault (a run store, a home directory): resolved with expanduser, it prints under OUT-OF-VAULT SOURCES: n present | m missing — a missing one is a finding in that bucket, never a dangling vault path (register entry 2026-09-08).
• The same script reads the frontmatter converted_from: of every raw/**/*.md conversion and lists, under MISSING ORIGINALS:, a local original found neither beside the conversion, nor at its vault path, nor anywhere under raw/ by file name, with CONVERSIONS SCANNED: as that arm's control; a URL or prose value is counted and never resolved, and a stale value whose original survives elsewhere under raw/ is listed apart, never as a finding (register entry 2026-09-09).
• Beside it, python3 .claude/skills/lint/check_flag_admissions.py --vault . (exit 0 = clean, 1 = findings, 2 = premise: not a vault root, or no wiki/sources/) lists every page under wiki/sources/ whose prose or frontmatter comment admits conversion damage — the vocabulary collapsed, lost inter-word spaces, inter-word, space-restored, run-together, run together, verbatim quotation is unavailable, lost every chart, lost every figure, lost every table, charts lost, figures lost — while the page carries no conversion flag: a flagged: line counts only when its own text carries conversion (source conversion suspect …), so a flag about something else never masks an admission. A damage admission belongs in the flag channel (ingest Step 0 scores every file carrying converted_by: and records a suspect one in scope pdf as flagged:), which is the only channel deep-lint reads; the fix for a hit is a flagged: line on the page, never a rewrite of the prose — and the flag's end is ingest 3c's terminal state: a repaired conversion scored clean in sources: plus the dated Provenance sentence, which the probe counts under its RESOLVED: line (an admission that also names a repaired conversion), never as a finding. It prints its own in-memory controls (a page that must fire; its conversion-flagged twin that must not; a twin flagged for something else that must; a resolved twin; a marked twin and a negated twin that must not) and the count scanned (register entry 2026-09-08, ingest Step 0 conversions, and the folds of the same day). A line carrying <!-- lint: not a conversion admission -->, or whose term directly follows a negation (must not be collapsed), is listed under SUPPRESSED: and never counted as a finding (register entry 2026-09-09).
• Every script in this directory refuses, in vault mode, a root that is not a vault (no raw/ + wiki/): one PROBE FAILED: <root> is not a vault root (no raw/ or wiki/) line on stderr and exit 2, so a wrong root can never read as a clean vault scan (the 2026-08-26 standard; the register entry of 2026-09-06 that closed it here; the file-mode forms anomaly-lister --pages and tier-cap-check --verdicts keep their own checks). Every Python script and check-qmd-registry.sh take --vault ROOT; an unknown flag is refused with exit 2, never read as the root.
• Orphans are scripted too: python3 .claude/skills/lint/check-orphans.py --vault . reports a page with no inbound links from any other page as an orphan, exempting index, log, and maps/ pages (Maps of Content are navigational entry points, not orphans). It applies this directory's link rules, prints its own inbound-link control (zero orphans with a zero control is a broken probe, §11), and additionally lists the pages index.md alone reaches — information, not a finding.
• Two further helpers in this directory serve deep-lint and the routing design's verify leg, not routine lint: tier-cap-check.py (§4.6 type caps and boundaries; a documented override on the confidence: line is reported separately, never as a violation) and anomaly-lister.py (page-visible anomalies: open conflict blocks, flagged: lines, thin-page notes, unverified markers). Suite for all three: bash .claude/skills/lint/test_lint_phase2.sh.
• Structure: python3 .claude/skills/lint/check-required-sections.py --vault . lists every page missing a level-2 section its table requires, with each page's depth: beside it; the table covers ## Related for concept, entity and tool, ## Appears in for model and benchmark, ## Summary, ## Key Takeaways and ## Related for source, and ## Sources Used for synthesis and development, exempts maps, and checks no other part of CLAUDE.md §4.3 (register entry 2026-09-03). A research-depth source page carrying the ingest template's ## Citation is judged on ## Related alone (CLAUDE.md §4.3, the research-depth clause of 2026-09-14): the check reads depth: before judging a page's sections, and such a page is a finding only without ## Related.
• Restated rules: python3 .claude/skills/lint/check-tier-vocabulary.py --vault . extracts every caps at / defaults to plus a tier word from CLAUDE.md §4.6 and from each skill's SKILL.md, and lists under MISMATCHES: a skill statement to which §4.6 gives another tier for the same page type (register entry 2026-09-03).
• Register: python3 .claude/skills/lint/check_register.py --vault . lists an entry under ## Open in wiki/developments/known-issues.md whose **Status**: begins closed, fixed or resolved, and two Open entries citing one file:line locator, and prints register-check: n/a when the vault has no register yet (register entry 2026-09-07).
• Each of those three prints its own in-memory control and its scan totals and exits 0 clean, 1 findings, 2 broken premise; they share the suite above.
• Routing (M0, 2026-09-02; residue closed 2026-09-07): every lint check is a script; the agent reads reports and never re-derives a scripted count (orphans became check-orphans.py, Phase 2 of the routing design; Step 1's index-consistency comparison became check-index.py, the last hand comparison in this pipeline).

2b — Pending freshness flags (count only — reconciling them is deep-lint's job)

grep -rl "^flagged:" wiki --include='*.md' | wc -l — with the engine control grep -rl "^confidence:" wiki --include='*.md' | wc -l (must be >0, proving the probe ran). Report the count; at ≥5 flagged pages, suggest running /deep-lint (set by judgement, unmeasured). Never read or resolve the flagged pages here — lint counts, deep-lint reconciles.

2c — Attic-leak check (filenames only — attic contents are never opened)

Live pages must never link into the attic (CLAUDE.md §2.1): Obsidian resolves wikilinks vault-wide, so a surviving [[link]] to an archived note silently reconnects retired material and can pull a query in. List basenames only — find attic -type f -name '*.md', skip MANIFEST.md (the check reads names, never contents; attic absent or empty → report "attic-leak: n/a"). For each basename b, grep live wiki (excluding wiki/log.md, append-only history) for the exact link forms "[[b]]" "[[b|" "[[b#" "/b]]" "/b|" — plain-text mentions ("b (archived)") are the §2.1 sweep style and are NOT findings. Any hit is a leak finding: report it; the fix (owner-confirmed) is re-sweeping to plain text per §2.1, or /attic restore if the page should live again. Control (§11): the same pipeline against one known live page name must return >0 before reporting "no leaks".

2d — qmd registry guard (one scripted check; skipped silently when qmd is dormant)

wiki/log.md must stay out of the semantic index (CLAUDE.md §10) — embeddings key on a file's whole-content hash, so every append re-embeds the whole timeline, and a hit invites an unbounded whole-file read via qmd get. The exclusion lives in ~/.config/qmd/index.yml, outside the vault and outside both git repos, so it can disappear silently. Run sh .claude/skills/lint/check-qmd-registry.sh . and copy its one line into the report verbatim. The script carries its own §11 control (index.md, deliberately kept, must be listed) and reports PROBE FAILED rather than "clean" when its own premise breaks. Exit 1 = finding; the fix is to restore ignore: ["**/log.md"] on the wiki collection and re-run qmd update.