--- name: wiki-lint description: Checks the health of the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references. Use when the user says "lint the wiki", "health-check the wiki", or periodically every 10 sources per the Maintenance Schedule. --- # Wiki Lint **Purpose:** Health-check and maintain the wiki. **Trigger:** User requests a lint, or `tools/wikitool log status` reports the "every 10 sources" threshold reached - `wiki-ingest`'s last step checks it after every publish, so the count is never something an agent has to remember. **Before the first `wikitool` call:** `instructions/session-setup.md`. ## Run checklist Copy this block into your first reply of the pass and tick each line as you reach it. Steps 3-6 are pure judgment: nothing errors when they are skipped, and a pass that quietly ran only its mechanical half looks exactly like a complete one. ```markdown - [ ] 1. Structural scan - [ ] 2. Raw coverage - [ ] 3. Contradictions (judgment) - [ ] 4. Stale claims (judgment) - [ ] 5. Missing pages (judgment) - [ ] 6. Duplicated rules (judgment) - [ ] 7. Repair what is mechanical - [ ] 8. Verify the stack - [ ] 9. Rebuild, write the report, carry its findings out ``` ## Steps 1. **Structural scan.** ```bash tools/wikitool lint ``` No flags: prints the sections that found something, writes the full report to `reports/Lint Report .md`, and names that path. This deterministically finds unreadable frontmatter, broken wikilinks, wikilinks wrapped across a line break, section anchors that name no heading on their page, dangling frontmatter references, orphan pages, catalog drift, missing fields, duplicate titles, titles that are not valid, unique file names on Windows and macOS, filename/title mismatches, broken `raw_files:` references, raw files claimed by more than one source page, invalid type paths, schema failures, citation/frontmatter drift, and edges whose label is missing, not authorised by the source collection, or redundant beside a specific label on the reverse direction, and pages with a section that still holds nothing but its template's `TODO` placeholders. **Do not re-derive any of it by reading pages.** *Unfilled Template Sections* is not mechanical either - do **not** clear it under step 7. Filling a section is authoring from a source (`wiki-manage`, AGENTS.md invariant 3), and deleting its placeholders to quiet the finding leaves the same unwritten page without the marker that made it visible. Retiring the page instead is `instructions/page-lifecycle.md`. Report the pages at step 9. The *Redundant see-also* section is the one that looks mechanical and is not - do **not** clear it under step 7. It names a `see-also` edge standing beside a specific label on the reverse direction, and the obvious repair destroys the thing worth keeping: `xref remove` clears the reference in *both* directions (see `tools/CONTRACT.md`), so removing the weak edge takes the labelled one with it and the pair ends up saying nothing at all. Either relabel the weak edge to something true with `xref add`, which only ever touches the source page, or leave it and report it at step 9. Clearing a batch of these is a planned corpus sweep with its own run, never a reaction inside a lint. **To see more of the report, read the file - never run `lint` again.** A second run costs a budget slot and re-measures a corpus that has not changed. The file at step 9 overwrites this one, so what ships records the wiki's final state rather than its state on arrival. 2. **Raw coverage.** ```bash tools/wikitool sources coverage ``` Flag un-ingested raw files and legacy directory/URL-only source pages as candidates for a future ingest. 3. **Contradictions** (judgment). Look for conflicting claims across pages. Note which is more recent or better supported, and propose a resolution to the user rather than picking one silently. 4. **Stale claims** (judgment). Claims unconfirmed for >6 months, superseded by a newer source, or naming an outdated version. `tools/wikitool search --field 'modified<' --sort modified` finds candidates cheaply. 5. **Missing pages** (judgment). Subjects mentioned across several sources, or with many outbound links, that have no page of their own. 6. **Duplicated rules** (judgment). AGENTS.md invariant 8 is "one rule, one place", and it is deliberately *not* machine-checked - prose duplication is a judgment call. Check whether a normative rule has been restated in a second contract, skill or instruction. If so: decide which location is canonical, and replace the others with a link. Two copies of a rule is how they start disagreeing. 7. **Repair what is mechanical.** A dangling frontmatter reference is either a page that should exist (`tools/wikitool new ...`) or a reference that should not (`tools/wikitool xref remove --a "" --b ""`). A title that changed is `tools/wikitool rename` - see `instructions/page-lifecycle.md`. Never hand-edit a frontmatter array to clear one. 8. **Verify the stack.** ```bash tools/wikitool docs verify tools/wikitool instructions verify ``` `docs verify` catches command/contract drift and ignore rules that would silently un-publish content; `instructions verify` catches a skill copy that drifted from its source and an instruction nothing references. 9. **Rebuild, write the report, carry its findings out.** ```bash tools/wikitool sources rebuild-index tools/wikitool index rebuild tools/wikitool lint ``` Then fill in that report's "Semantic Review" section with the findings from steps 2-6. **The report is gitignored and is not a wiki page.** Its structural half is recomputable; the semantic review is not, so it has to leave `reports/` before the pass ends. Findings that change a page go into the page; a one-line summary of the pass goes into the audit trail: ```bash tools/wikitool log append --op lint --title "" --body "" ``` A pass whose conclusions exist only in `reports/` has lost them. There are no old reports to retire - nothing there was ever committed. ## Decision points - **Publish?** Lint does not auto-publish. Run `tools/wikitool publish` only if asked. - **Bulk fixes touched 10+ files?** Expected for a lint pass: `publish` exits 42. Show the user its output and stop; see `instructions/gates.md`. Consider `--path` batches instead. - **The gate or loop-breaker keeps tripping?** That is a signal to stop and re-plan with the user, not to pass `--override-budget`. A full pass should land in roughly 20-35 calls. ## wikitool commands used `lint`, `search`, `sources coverage`, `xref add`, `xref remove`, `rename`, `new`, `docs verify`, `instructions verify`, `sources rebuild-index`, `index rebuild`, `log append`, `publish` (only if asked) **Deliberately absent:** `rm` - a lint pass never deletes a page, and `instructions/page-lifecycle.md` is where a deletion belongs. `log status` - it decides this skill's *trigger*, but `wiki-ingest`'s last step is what runs it. ## Output A lint report with findings and recommendations, its semantic half carried into the pages and the log. **Example trigger:** "Lint the wiki"