0029. The ADR index is generated from each file's own header, not hand-maintained

Status: Accepted · Date: 2026-10-26 · Design section: —

Decided: Generate docs/adr/README.md's index table from a Decided:/Status: line in each ADR's own header (internal/tools/adrindex) instead of a shared, hand-edited table

Context

Every agent working on a different unit adds its own ADR, and every one of those PRs also touched the same two lines of docs/adr/README.md -- the table's header row's neighbor. With agents landing in parallel, this file conflicted five times in a row; one of those conflicts was resolved wrong and briefly duplicated a row. index_test.go's TestIndexMatchesFiles caught staleness after the fact, but it could not prevent the conflict itself: two agents each adding a row at the bottom of the same file still collide textually even when their rows don't overlap.

Decision

Each ADR file now carries a Decided: <one-line summary> line immediately after its existing Status: ... · Date: ... · Design section: ... line (the line README.md's table already carried, moved rather than duplicated). internal/tools/adrindex (new, mirroring internal/tools/synccrds's existing command-per-generated-artifact pattern) reads every docs/adr/NNNN-*.md file, pulls its Decided: text and the first clause of its Status: line, and overwrites docs/adr/README.md's table with the result, sorted by number. make adr-index runs it; the preamble prose above the table is a constant in the generator, not read back from the file, so the whole output is reproducible from the ADR files alone.

This moves the only file every agent used to share into N independent files, each owned by whoever wrote that ADR. Two agents adding ADRs in the same window now touch disjoint files -- NNNN-title.md and MMMM-title.md -- and README.md is never hand-edited at all, so there is nothing left for them to conflict on.

docs/adr/index_test.go (TestIndexMatchesFiles, and TestNumbersAreContiguous before it) is deleted, not kept alongside the generator. Both tests existed to catch a hand-maintained table drifting from the files on disk; once the table is generated from those same files, that drift is no longer possible by construction, and internal/tools/adrindex's own TestGenerateIndexIsCurrent (go test ./internal/tools/adrindex/...) already is the CI check that regenerating changes nothing -- the same drift-detection shape dist/chart's CRD sync already uses. A test that can no longer fail for the reason it was written is deleted, not kept as a second implementation of the same check (ponytail: deletion beats addition).

Three ADRs (0002, 0018, 0020, 0021) had a Status: header that did not say "amended" even though README.md's table did -- the amendment was recorded in an ## Amendment (or, for 0020, ## Resolved gap) section instead of in the header. Their Status: lines were corrected to match what README.md already recorded, since the generator has no source for that fact other than the header line itself.

Consequences

• 0000-template.md now documents the Decided: line for new ADRs; an ADR without one fails adrindex loudly (TestGenerateIndexIsCurrent catches it the same way a missing chart file would).
• Not built here: any change to an ADR's ## Context/## Decision/ ## Consequences content -- only the header line each one already had moved, and the Status: line correction above.