# 0026. Wiki pages carry a freshness header

- **Status:** Accepted
- **Date:** 2026-08-08

## Context

[ADR 0021](0021-documentation-set-and-workflow.md) introduced the LLM wiki and a weekly documentation review.
`docs/DOCUMENTATION.md` carries one date for the whole set, which says nothing about any single page: a page
written three weeks ago against since-changed code looks exactly like one verified this morning.

With twenty-one pages the weekly lint therefore means "re-read everything" — a task that gets skipped by the
second week, after which the wiki is quietly wrong. That is the failure mode Rule 0 exists to prevent, and
the set had no signal for it.

## Decision

**Every page under `docs/wiki/` carries a header naming the source it covers and the commit it was last
verified against, and `bin/wiki-stale` reports the pages the code has outgrown.**

```markdown
<!--
	covers: models services modules/admin
	verified: <short sha>
-->
```

- `covers:` is a space-separated list of pathspecs relative to the repository root. Directories where the
  page is about a directory, files where it is about specific files. Every path must exist.
- `verified:` is set to `HEAD` **after** re-reading the page against the code, never as a formality.
- `bin/wiki-stale` runs `git diff --name-only <verified>..HEAD -- <covers>` per page and prints `ok`,
  `STALE` (with commit and file counts) or `BROKEN` (missing or unusable header). It exits non-zero when
  anything needs work.
- It runs at task close ([WORKFLOW.md](../WORKFLOW.md#5-closing-the-task)) and is the **first step** of the
  weekly review — the pages it reports as `ok` are not re-read.

The initial `verified:` value is `54fd0a6`, the documentation commit of the last full review.

## Alternatives

- **A date instead of a commit.** Cheap to write and impossible to check: a date cannot be diffed against the
  code. A commit-ish can.
- **One `covers:` per page pointing at a top-level directory only.** Simpler, but `models/` alone is
  sixty-four files and would make every domain page perpetually stale — the report has to stay quiet enough
  to be believed.
- **Deriving coverage automatically** from the file paths each page cites. Tempting, and wrong: a page is
  also stale when a *new* file appears in a directory it describes, which no citation can express.
- **Doing nothing and trusting the weekly read.** This is what was in place; it does not survive contact with
  a twenty-one page wiki.

## Consequences

- The weekly review starts from a list of three pages instead of a stack of twenty-one.
- [`wiki/GOTCHAS.md`](../wiki/GOTCHAS.md) is cross-cutting, so its `covers:` is broad and it will report
  stale often. That is correct: it is the page most likely to rot.
- The headers are maintenance of their own. A page whose subject moves needs its `covers:` corrected, and
  nothing detects a `covers:` that has become too narrow — only a `BROKEN` one.
- `verified:` can be bumped without doing the reading. The script measures whether a page *should* have been
  checked, not whether it was.