| name | docs-status |
| description | Audit documentation hygiene for the let-go docs/ tree — find stale or unverified docs, dangling or one-sided supersession links, duplicate authoritative-for claims, and docs missing from the README index. Use when asked to check doc freshness, run doc triage, audit docs/, find stale docs, or verify documentation hygiene before a docs PR. |
docs-status — documentation hygiene triage
Drives scripts/docs_status.py, the read-only judgement-layer report over
docs/**/*.md frontmatter. The pre-commit hook and CI floor check keep the
mechanical fields honest (frontmatter present, status:/last-verified:
parseable); this surfaces the judgement layer they leave to a human or
agent. Full reference: docs/docs-status.md.
How to run
From the repository root:
python3 scripts/docs_status.py # text report over docs/
Stdlib-only Python; no install step. Override the scan root with --root
and the thresholds with --stale-days / --human-stale-days.
What the findings mean, and what to do
- stale-last-verified — the doc hasn't been touched in a while. Re-read
it; if still accurate, a trivial edit (or the pre-commit hook) refreshes
last-verified:. Don't bump the date without actually reviewing.
- aged-human-verified — a human vouched once, long ago. Flag it for a
human to re-attest. Do not refresh it yourself.
- supersession — mirror the missing half (
supersedes: ↔
superseded-by:), fix a dangling target, or add the superseded-by:
link a status: superseded doc is missing.
- authoritative-for clashes — two docs claim the same topic. Propose
which one yields, or split the topic. This is a judgement call — surface
it, don't silently rewrite.
- missing-index — add a row to
docs/README.md routing the doc.
The one hard rule
Never write human-verified:. It records that a human reader vouched
for a doc, and is set only by explicit human action — not by this tool, not
by you, even when a human asks you to edit the doc's other fields. A blank
human-verified: is reported only as a count, never as a per-doc task. See
docs/frontmatter-hook.md for why this field is special.
Apply the freshness, status:, and link fixes the way a human reviewer
would — the tool reports; you exercise the judgement.
