Deep Lint

deep-lint — monthly deep maintenance

Goal

Keep the whole knowledge base correct, calibrated, and current in one bundled pass.

When to run

About once a month, or before a milestone (a big query session, an export, enabling qmd). It reads pages and may fetch from the network, so it is heavy — do not run it after every ingest. Routine integrity is /lint's job; deep-lint is the periodic deep clean.

Triggers

/deep-lint · "monthly maintenance" · "deep clean / deep audit the wiki" · "are my sources still current?"

Pipeline (read/scan first; confirm before large changes)

1 — Structural pass (everything lint does)

Routing (M0, scripted at Phase 2, logged framework 2026-09-02; no gate applies to script work): every probe in this step is a script (.claude/skills/lint/*.py, .claude/skills/deep-lint/*.py); the agent reads their reports and never re-derives a count by hand. Three scripts do the mechanical half of this step and print their own §11 controls; read their output, never re-derive it by hand. python3 .claude/skills/deep-lint/sweeps.py --vault . covers the hard-wrap, raw-tag and correction-narrative sweeps below; python3 .claude/skills/deep-lint/prefix-budget.py --vault . --diff-log wiki/log.md covers the prefix reconciliation; python3 .claude/skills/deep-lint/audit-pools.py --vault . --baseline <date> covers the updated: accuracy sweep here and every pool, stratum and sample of Step 3. Exit 0 means the probe ran (findings or none); exit 2 means a premise failed and its line says which. Suite: bash .claude/skills/deep-lint/test_deep_lint_scripts.sh. Run the full lint pipeline: index consistency, link health (dead links, orphans — maps//index/log exempt), unresolved ## Conflicts / Open Questions, and the gap scan. Fix the cheap, unambiguous issues (register unindexed pages, etc.) after the report.

• Customisation sanity (deep-lint only): if CUSTOMISATION.md exists, verify its ## Settings block exists and that its style and role values each name a section defined in the core file (the block-move rule keeps the defaults there; non-default definitions live in CUSTOMISATION-definitions.md, whose pairing lint's 2f — inherited by the structural pass above — already checks; the definitions file is on-demand, so it never counts toward the prefix line below), (knobs live in the body, never the frontmatter — the §13 import strips YAML), that no role line still uses the retired - overrides <feature>: syntax (mechanism retired 2026-08-17 — such a line is inert; flag it for the owner to reword, never rewrite it), and that its loading path is intact: the file carries its CUSTOMISATION-LOADED-v1 marker line and CLAUDE.md still holds the matching @CUSTOMISATION.md import (§13). Its always-on cost rides the prefix-reconciliation line below — one home, not two — and has no size cap: the owner decides what the preference layer is worth, and only they can trim it. Flag any drift for the owner; never rewrite their preferences.
• Attic guard (existence-only): attic/ and attic/MANIFEST.md exist, and the path:attic/ colour group is present (apply-palette.py --check covers it). NEVER open attic contents — the attic is explicit-instruction-only (CLAUDE.md §2.1); this check reads nothing inside it.
• Hard-wrap check: flag wiki pages with suspected mid-sentence hard wraps (a prose line ending in a lowercase word or comma while the next line begins lowercase) — prose is one line per paragraph (CLAUDE.md §1 line discipline; Obsidian renders single newlines as breaks). Skip non-rendered text: frontmatter, code blocks, tables, and HTML-comment interiors. Fix on confirmation.
• Rendering & narrative sweep (two cheap greps): flag (a) raw <tag> tokens in rendered wiki prose outside backticks/comments — Obsidian parses them as HTML (CLAUDE.md §1); (b) correction-narrative phrases in wiki/developments/ (e.g. "owner revision", "no longer", "earlier wording", "was removed") — development docs read forward-facing (CLAUDE.md §12). Fix on confirmation.
• updated: accuracy sweep (one pass over frontmatter + body): for every page with a parseable updated:, flag any YYYY-MM-DD in its body that is later than that field and not in the future. A date can only be written on or after the day it names, so a later body date proves the page was edited after updated: claims — the field understates when the page last changed. This is not cosmetic: Step 3 partitions its entire audit on updated:, so a stale value hides an edited page in the cold tail. Report each as old → latest-body-date; fix on confirmation by setting updated: to that date. Skip wiki/log.md. §11 control before trusting a zero: audit-pools.py runs this sweep and prints its own control (a copy of index.md planted, in memory, at a date derived from the vault's own oldest body date, and caught), so the plant never touches disk. Prevention lives in the updated-stamp.py Stop hook (.claude/hooks/), which is vault-local and never ships; this sweep is the belt that still works on a fresh machine where the hook is absent. Read the №115 context-hook logs where present and compare transcript compaction records with hook events. A compaction without its hook event is a finding; use observed sessions to review the context bands.
• Always-on prefix reconciliation (prefix-budget.py): measure every always-on context layer — wc -c CLAUDE.md · each skill's SKILL.md frontmatter (the ever-loaded name:/description: block between the --- markers), per skill · each .claude/agents/*.md frontmatter, per definition (the harness surfaces every definition's name and description in the system prompt of every session, exactly as it does for skills; measure the whole frontmatter block, the same convention as the skill arm — markers included: two --- lines and their newlines total 8 B. Also measure each user-level skill's and each enabled plugin's skill's SKILL.md frontmatter, per skill, using the configured skill and plugin roots, because both ride every session's skill listing; and measure wc -c CUSTOMISATION.md (§13 imports it on every request) and the count of project-declared MCP servers (.mcp.json / project settings; report 0 declared, not a bare 0 — user-level servers load into the session too and this probe does not see them, so a bare zero would overstate what was checked) — and report the absolute total as ≈ tokens/request (bytes ÷ 4). Report wiki/index.md beside it as entries × bytes-per-entry (grep -c '^- \[\[' and wc -c) and attribute the delta since the last entry to new entries versus densification (the registry-read policy, its growth section). Then reconcile composition — never threshold the total (CLAUDE.md §12: a growth threshold converts sanctioned change into alarm). Diff each layer against the per-file figures in the previous deep-lint entry (grep "prefix budget:" wiki/log.md | tail -1; first run, or first after a format change, = baseline — say so; the agents layer and the declared MCP wording were added 2026-08-28, so the first run after that date is a format baseline for those two fields and cannot diff them; the user-skills and plugin-skills layers were added 2026-09-13, with the same consequence for the first run after that date) and annotate every delta with its cause: new/retired skill or agent definition (sanctioned — §12 logs it) · matches a framework | log entry since the last run (sanctioned) · CUSTOMISATION.md delta (user-space: report the number, never "unexplained" — owner edits need no log) · UNEXPLAINED — the only flag (report-only; trimming is never automatic, §12 governs any cut). Record this run's figures per skill and per definition so the next run can reconcile: prefix budget: CLAUDE.md <N> B · skills <M> B (<name> <n> · …) · agents <A> B (<name> <n> · …) · user-skills <U> B (<name> <n> · …) · plugin-skills <P> B (<plugin>:<skill> <n> · …) · customisation <K> B · MCP <k> declared · total ≈<T> tok/request.

2 — Flag-ledger reconciliation (Tier 2 → Tier 3)

Collect the query-time freshness flags accumulated since the last run — one cheap global grep: grep -rn "^flagged:" wiki --include='*.md' (glob quoted — unquoted it breaks under zsh; verify the probe against a known positive before trusting an empty result, per CLAUDE.md §11). For each flagged page: re-read it, resolve the suspicion (update the page · re-grade its confidence · re-ingest its source via §3.1 tools · or clear a false alarm) — a source conversion suspect flag resolves only by ingest 3c's terminal state (a repaired conversion scored clean joins sources: and the page's ## Summary ends with the dated Provenance sentence); a re-read alone is never that resolution (2026-09-09) —, remove the flagged: line, and list the resolution in the report. The ledger is the run's first LLM-read priority.

• Known-issues register (framework defects): read wiki/developments/known-issues.md — a missing file means nothing has been captured yet (the register is recreated at capture time, not here). For each ## Open entry: verify it is still live against the affected surface (a fix may have shipped unrecorded), move shipped ones to ## Closed as dated one-liners, flag entries older than ~90 days, and list fix candidates in the report ranked by severity × age, each presented as a ready-to-issue instruction naming its design doc where one exists (e.g. "fix the X defects per their design doc under wiki/developments/") — mirroring the ready-to-issue /attic suggestions in Step 4. Fixes themselves stay propose-only under CLAUDE.md §12.
• Spawn-record review (2026-09-06; carries the instrument rule's over-calling guard and the per-call model-and-effort rule's pick guard). Head-side, never routed — the records live outside the vault at ~/.llm-wiki/spawn-records/<run>.jsonl, beyond any lane's grants — and scripted: python3 .claude/skills/deep-lint/spawn-record-review.py (report-only; --json for the structure; PROBE FAILED and exit 2 on a missing records directory or an unreadable routing.json). It reads every record whose run opened on or after this log's last deep-lint | entry (no such entry: the whole history, said once; a resumed run is re-reviewed and labelled; a record with no run-open, the shape an attended session writes, is dated by its earliest lane-open, labelled attended and reviewed like any other), tallies each run's instrument-rule letters, and per lane checks the recorded pick against the line's row_default (older lines re-resolved from today's routing.json and labelled): under default a model or effort below the row default must carry <model> because / effort <x> because in reason; a floor the owner wrote (cheap, fast, cheap-fast) skips that axis and flags a pick above the floor; top flags a pick below a ceiling; under auto (the default preset from 2026-09-08; on a line carrying the wrapper's model_src) a departure from the anchor on either axis in either direction must carry its reason (model_src/effort_src = auto: <reason>, or a non-empty choice_reason), else the finding auto pick without --choice-reason. It lists unclosed lanes, unread applied effort, unknown classes, out-of-set picks and unparsed fields, and cross-checks effort_applied where the wrapper read it. The phrase checks start at the script's RULE_FROM (the ship instant of 2026-09-06, carried by that framework entry's title; the suite asserts the two agree) and the letter check at LETTER_FROM (2026-09-04, the instrument rule's date). Each FINDING line is a known-issues entry, one per run; no lanes this window with the file count is the empty case. Suite: bash .claude/skills/deep-lint/test_deep_lint_scripts.sh (its spawn-record legs plant every branch).
• Routing (parity gate G6a, 2026-09-02). (applies under the multi regime, owner-set or head-resolved for the run under delegation auto; in single the head runs the step itself unless an instrument-rule reason holds — thin-lanes phase 4, 2026-09-04; delegation auto 2026-09-04) The liveness check itself (is each ## Open entry still live against its surface?) runs in a verifier lane with an explicit per-entry claim list and the two §11 controls; the head reads the verdicts, moves entries and keeps the fix-shape review. This routing is set by judgement from the author's own reviews.

3 — Confidence coverage & correctness (per CLAUDE.md §4.6)

audit-pools.py computes this step's pools, strata, cap, tail and sample, and prints the three report lines below verbatim. The judging is routed (Routing note below): two blind gate-judge lanes assign, the head adjudicates and reads in full every disputed page and every page whose tier a lane would raise, re-tiers, and stamps audited:. An absent .claude/agents/ and a log with no dated entry yet are legitimate states that report n/a, not failures.

• Coverage: every non-map page must carry a valid confidence. Cheap check: grep -rL "^confidence:" wiki --include='*.md' then drop map/index/log. Assign any missing ones.
• Correctness — a capped, stratified sample; NEVER the whole changed set. Two pools partition the audit-eligible pages (all of wiki/ except map/index/log), split on the previous run's date (grep "^## \[.*\] deep-lint" wiki/log.md | tail -1). Split on the updated: frontmatter date, never filesystem mtime and never git: cloud sync rewrites mtimes (most pages can disagree with their updated:, some by months) and backups are batched, so many pages share one commit date — while every page carries updated:. The rule therefore has no "mtime/git unavailable" failure mode: it consults neither.
  • Pool A — changed (updated ≥ baseline, plus every flagged: page whatever its updated: — the stratum is defined by the flag, not the window; audit-pools.py lifts such pages out of the tail and prints flagged lifted from below the baseline: n, so a flag written without an updated: bump is still read; the Stop hook now stamps a frontmatter-only flagged: add, change or removal, so the lift is the belt for pages flagged before it — 2026-09-08). Cap: 40 new page reads. Fill in this order:
    1. Always — flagged: pages. Step 2 already read and resolved them, so they count toward the reported total at zero extra cost and never consume the cap.
    2. Always — confidence: authoritative pages, in full. Their high blast radius warrants a complete read; §4.6 lets only that tier exceed the compiled/derived ceiling.
    3. Fill the rest of the cap at random: two-thirds from compiled/derived pages badged high (concept/entity/tool/model/benchmark/synthesis/development — aggregations sitting on the §4.6 ceiling, the badge an edit most easily overstates), one-third from everything else changed (sources and non-high pages — never a zero share: a mis-tiered source propagates into everything compiled from it). Either pool short of its share hands the slack to the other. The two-thirds split is set by judgement, unmeasured; the per-stratum re-tier counts reported below are the measurement that will settle it.
    • Sampling derivation: 40 changed reads plus at most 20 tail reads bounds the combined sample at 60 pages. These compatibility defaults are set by judgement, unmeasured for a new vault; review their affordability from the reported read sizes. Absolute, never a fraction of N — the cost must stop growing with write volume, and the report names the unsampled share.
  • Pool B — the unaudited tail (everything else), ordered least-recently-audited first: sort key audited: where present, else updated: (pre-rule pages, §4.1; an unparseable audited: is ignored and the fallback keys it). Sample up to 20 from the oldest third (the whole tail when it holds < 60 pages). Relative, not a fixed age: a fixed age can select no pages in a young vault. A relative ordering works at every vault age. As audited: coverage grows, the key converges on time since a badge was last checked, rather than time since the page last changed.
  • Reporting is part of the rule, not a courtesy (CLAUDE.md §11 — no silent caps). Print every stratum, empty ones included as 0 of 0; an omitted line reads as "not checked": changed: audited k of N — flagged f (Step 2) · authoritative a of A · compiled/derived-high b of B · other c of C · not audited N−k re-tiers per stratum: flagged f′ · authoritative a′ · compiled/derived-high b′ · other c′ · tail t′ (the ⅔ split's own evidence) tail: sampled j of M least-recently-audited (of T unchanged) audited: coverage n of E eligible pages (x%) — stamped this run: s (the script prints the first three lines and the coverage line up to the percentage; the agent appends — stamped this run: s and the re-tiers per stratum: line, since only it knows what it judged and stamped)
  • When the premise fails (§12 — attack the guard):
    • No baseline (first run, or the log grep finds no prior deep-lint entry) → say so, treat the whole vault as one pool, draw the same stratified sample at the cap. Never "everything", never zero.
    • Zero changed pages → a zero is a claim (§11). Re-run the comparison against a date older than every page; it must return the full audit-eligible count. Control returns 0 too → the date probe is broken: report a probe failure, and state that the changed audit did not run. Control passes → "0 changed" is a real finding, reported as one.
    • Cap ≥ N → audit all N; report audited N of N (under cap — no sampling); no draw, no exclusions.
    • A stratum is empty → contributes 0, its budget flows to the next in fill order, and its line still prints 0 of 0.
    • The always-include strata alone exceed the cap → take them in fill order to the cap, draw nothing from the random pools, and report the overflow (authoritative: 40 of 57 — cap reached, 17 not audited). The cap never silently stretches.
    • A page has no parseable updated: → it belongs to neither pool: list it as unclassifiable and audit it this run: broken frontmatter deserves a read. More than a capful is a Step 1 structural finding, not an audit pool.
  • Prefer reading only frontmatter + the summary unless a fuller read is needed. Keep one consistent standard; on a tie pick the lower tier.
  • Stamp what you check (§4.6 write-time self-audit): every page whose badge this step actually judged — flagged, changed-sample, tail-sample, unclassifiable — gets audited: <today> in the same pass, confirmed and re-tiered alike. Never stamp a page the run did not judge; never mass-backfill.
• Apply the same rule everywhere: peer-reviewed/expert/verified → authoritative; preprint/owner/ official-doc/faithful-summary → high; reputable secondary, or grounding primary only for something adjacent → medium; promo/social/listing/transcript → low; agent-speculative → very-low. Compiled pages cap at high.
• Tier-audit execution (parity gate G1). (applies under the multi regime, owner-set or head-resolved for the run under delegation auto; in single the head runs the step itself unless an instrument-rule reason holds — thin-lanes phase 4, 2026-09-04; delegation auto 2026-09-04) The sample's tier judgements run in two blind gate-judge lanes (opus · max), each given the same fixture copy of the sampled pages with badges, audited: stamps and tier rationale stripped, the rubric (§4.6 plus wiki-confidence-levels.md), one content plant (a page whose evidence the head altered to demand a different tier, with two-sided controls) and the per-page form pNN · tier · rubric ground · evidence; each lane also returns an ## Anomalies list. The head adjudicates: agreement = the tier; a one-step split = the lower tier unless the head's own read of that page settles it (the head reads only the disputed pages); a two-step split or a missed plant = that lane's batch re-judged by a third blind lane. A lane tier that would raise a page's badge is never applied unread: the head reads that page in full first (§4.6, delegation never raises a tier). Before any stamp, the verify leg runs — tier-cap-check.py over every verdict plus a verifier lane over the lanes' claim forms — and the head judges the flagged and authoritative strata itself (the head slice); the log entry names all three as the stamp's basis (design items 3, 4, 9). Stamping (audited:, re-tiers) stays head-side.