---
name: wiki-lint
description: Health-check the LLM wiki - broken links, orphan pages, uncovered raw files, stale claims, duplicated rules, missing cross-references, confidence decay. 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:** [session-setup.md](../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. Refresh confidence and 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 <YYYY-MM-DD>.md`, and names that path. This deterministically finds
   unreadable frontmatter, broken wikilinks, dangling frontmatter references, orphan pages,
   catalog drift, missing fields, duplicate titles, 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.
   **Do not re-derive any of it by reading pages.**

   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](../../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<<date>' --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 "<Page>" --b "<Missing>"`). A title that changed is
   `tools/wikitool rename` - see [page-lifecycle.md](../page-lifecycle.md). Never hand-edit a
   frontmatter array to clear one.

8. **Refresh confidence and verify the stack.**

   ```bash
   tools/wikitool confidence decay --apply
   tools/wikitool docs verify
   tools/wikitool instructions verify
   ```

   If decay reports pages with no `confidence_base`, run
   `tools/wikitool confidence init-base --apply` first. `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 "<date>" --body "<summary>"
   ```

   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 [gates.md](../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`,
`confidence decay --apply`, `confidence init-base --apply`, `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
[page-lifecycle.md](../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"