The GUIDE's ADR decision log stops at 0008 — three ADRs are missing and nothing notices

[macanderson]

Problem

docs/GUIDE.md §3 "Decision log (ADRs)" is a table that claims to index the
ADRs — "Full text lives in docs/adr/. Every entry below is Accepted." It
stops at 0008. Three Accepted ADRs have no row:

• docs/adr/0009-adopt-standing-decisions-scr-corpus.md
• docs/adr/0010-provenance-attestation.md
• docs/adr/0011-open-frame-kind-vocabulary.md

Each was added in a PR that did not touch the table, and nothing failed. The
anchor line under the table (<a id="adr-0002"></a>…) has the same gap, so an
in-page #adr-0010 link from elsewhere in the GUIDE would silently go nowhere.

An index that is three entries stale is worse than no index: a reader who
checks it and does not find provenance attestation concludes there is no ADR
about provenance attestation.

Why this is the interesting kind of bug

It merges silently and per-PR CI cannot see it. The table is a shared cell —
one file every ADR-adding PR must write — so each author's tree is individually
fine and the omission only exists relative to a directory listing nobody
compares it against. That is the same class as the ADR number collisions being
managed by hand right now (PR #106 and PR #109 both proposed a 0012).

What done looks like

1. Rows for 0009, 0010 and 0011, matching the table's existing voice: plain
   language, one line, what changed and why a reader should care — not the
   ADR's title restated.
2. Their anchors added to the <a id="adr-…"> line.
3. A guard, because step 1 has already been skipped three times and will be
   skipped again. Compare fd -g '[0-9][0-9][0-9][0-9]-*.md' docs/adr/ against
   the rows in the table and fail when they disagree, in both directions — an
   ADR with no row, and a row naming a file that no longer exists. Wire it into
   ci.yml beside the existing advertised artifact URLs point at a host we serve job, and give it a self-test (see The two Python gate scripts have no self-test, so a guard that stops seeing its subject still passes #110, which asks for the same
   discipline for the two existing Python guards).
4. While the guard is being written: it can also catch duplicate ADR
   numbers, which is a live problem — two open PRs each added a 0012 with
   different filenames, so git would have merged both cleanly into a tree with
   two ADR 0012s. A one-line uniqueness assertion on the numeric prefix closes
   that for good and removes the need for manual number allocation.

Files

• docs/GUIDE.md §3 — the table and the anchor line (around the ## 3. Decision log (ADRs) heading).
• docs/adr/ — the source of truth for what rows should exist.
• .github/workflows/ci.yml — where the guard runs.

Verify

With the guard in place: delete a row and confirm CI fails naming the missing
ADR; add a scratch docs/adr/0099-x.md with no row and confirm it fails; create
two files with the same numeric prefix and confirm it fails. Then confirm a
clean tree passes.

Context

Noticed in PR #109 while renumbering its ADR from 0012 to 0013 after a
collision. That PR adds its own row (0013) and leaves the 0009–0011 gap alone,
with an HTML comment in the table pointing here so the jump from 0008 to 0013
does not read as a typo. Filling the gap was left out of #109 deliberately:
the table is a shared cell and several ADR-adding PRs were open at once, so
widening the edit would have manufactured merge conflicts across all of them.

[macanderson]

Folding in #135, filed independently for the same gap and now closed as a duplicate. Two additions from it worth keeping on this issue:

1. The GUIDE contradicts itself, not just the directory. The document opens by promising "every ADR, indexed and summarized". With 0009, 0010 and 0011 absent, that sentence is false — so the fix is not only adding rows but making the promise enforceable, or softening it.

2. This and #123 are one guard. #123 is "two PRs can add the same ADR number and both stay green". Both are invariants over docs/adr/ that nothing checks. A single script reading that directory could settle both in one pass:

• every docs/adr/NNNN-*.md has a row in the GUIDE's table and a matching <a id="adr-NNNN"> anchor;
• no two files share a numeric prefix.

The second half is what would remove the need for the central number allocation being done by hand right now across the open PRs — worth building them together rather than as two scripts.

Note for whoever picks this up: PR #109 adds the row and anchor for 0013 and deliberately does not backfill 0009–0011, because that table is a shared cell and several ADR-adding PRs are open simultaneously. Backfill after those land, or the backfill conflicts with every one of them.