checkdocs

Overview ¶

Command checkdocs is the documentation gate (make gate-docs).

The documents in this repository are load-bearing: code cites them instead of repeating an argument, and AGENTS.md sends a reader to them. A link that stops resolving therefore does not only annoy - it quietly removes the reason a piece of code looks the way it does.

What it checks, and why each one has been wrong somewhere before:

• Every relative link between documents resolves, including its anchor. A renamed heading leaves a link that lands at the top of a long page, which reads as "the section is gone".
• Every ADR is in the index, and every index entry has a file. An ADR nobody indexed is one nobody finds; an index entry without a file is a decision that looks recorded and is not.
• Every ADR-xxxx named anywhere in the repository exists, in every kind of file the code citations are read in. Code cites ADR numbers in comments, and a typo there points a reader at nothing.
• Every statement of the Go version agrees with go.mod. It is repeated in thirty places across eight files, and a base image bumped on its own would have the release built by a compiler no gate ever ran.
• Every rule in AGENTS.md, and in a directory's own AGENTS.md, says what checks it, and a gate or CI job it names exists; outside the rule lists the root file explains rather than commands; the headings older text cites keep their words, the rules their numbers, the loop its steps (agents.go).
• Every ADR says where its rule lives now, because an ADR is the record of why and the current rule is in a subject document (agents.go).
• Code cites what keeps resolving: every "file.md §N" exists, and no comment cites a task, an issue, a milestone file or an instruction file; the API description names no internal reference at all (citations.go).
• The support matrix and the workflows agree in both directions, so that support can neither be claimed without a job nor removed by deleting one (see matrix.go).
• The use cases cite personas, deployments and principles that exist, carry the sections that make them checkable, agree with their index, and every UC-… and use case check cited anywhere exists (see usecases.go).
• Every task of a milestone carries checks its `Delivers` line names, and a closed milestone has no Delivers check a use case still lists as unmet (see milestones.go).

An archived readiness record is a snapshot of its task's start, so the link and reference checks pass it by (snapshot).