ci(docs): nothing enforces that the two ADR indexes agree with the ADR files

[DecisionNerd]

Problem

This repository keeps two ADR indexes and requires both to be updated. Nothing enforces it, and they have already drifted.

docs/engineering/adrs/README.md states the rule:

Until bodies move under this folder, add new ADR markdown under docs/adr/ and update both

Both indexes are hand-maintained tables. There is no test comparing them against each other or against the ADR files on disk.

How it was found

ADR 0033 merged today in PR #1383, which updated docs/adr/README.md and not docs/engineering/adrs/README.md. Nothing failed. The omission surfaced only because a later agent happened to read the second README while adding ADR 0034, and repaired both.

That is the same class of defect as the stale crate inventories repaired in #1373: a hand-maintained list that has to agree with reality, with no mechanism making it agree. Those inventories had drifted silently for three crates and were caught only by an unrelated investigation.

Requirements

• Add a fail-closed check that the set of ADR files under docs/adr/ matches both index tables, by number and by filename.
• Catch the three ways they can disagree: a file present in neither index, a file present in one index only, and an index row naming a file that does not exist.
• Wire it into whichever policy suite already runs this kind of inventory check, rather than creating a new gate. scripts/ci/test-crate-publish-plan.py is the recent precedent for this pattern, added by fix(release): three crates are in the publish plan but missing from every release inventory #1373.
• Fix any drift the check reveals beyond the 0033 row already repaired.

Acceptance criteria

• A test fails when an ADR file is missing from either index.
• A test fails when an index row names a file that does not exist.
• The test is proven to fail closed by removing an entry and observing the failure, not merely by passing.
• Both indexes agree with the ADR directory at the time this lands.
• The check runs in an existing suite; no new standalone gate.

Non-goals

• Moving ADR bodies under the second directory. The path coordination question is separate and this issue takes no position on it.
• Changing ADR numbering or content.
• Validating ADR body structure, status fields or supersession links. Worth considering later; this issue is about the indexes agreeing with the filesystem.

Relationships

Found while adding ADR 0034 under #858. Same class as #1373, which repaired stale hand-maintained release inventories and added the divergence test that now protects them.

[DecisionNerd]

Scope correction: there are three hand-maintained ADR indexes, not two, and the third pair was the stalest.

I verified this directly on main. Both docs-site/scripts/sync-content.mjs and docs-site/astro.config.mjs enumerate ADRs by hand, twenty-eight entries each, and neither contained 0033 at the time of checking. The ADR cleanup in PR #1394 found they were also missing 0022, 0028, 0029 and 0030.

So the drift was worse than this issue records. Counting the two markdown indexes and the two docs-site files, ADR 0033 was absent from three of four places it should have appeared, hours after it merged, and nothing failed.

That widens what this gate must cover. The check has to reconcile the ADR directory against all four:

File	Role
docs/adr/README.md	primary index table
docs/engineering/adrs/README.md	engineering log, with a status column
docs-site/scripts/sync-content.mjs	publication allowlist
docs-site/astro.config.mjs	site sidebar

The last two matter more than they look. They are not documentation of the index; they are what the docs build consumes. PR #1394 had to regenerate both as a hard requirement, because moving a superseded record out of docs/adr/ would otherwise have broken the build outright.

Three additional failure modes to catch, beyond the three this issue already lists: a record present in some indexes but not others; a record in the active directory that the docs-site allowlist omits, which silently drops it from the published site; and a superseded record still listed as active.

Prefer generating over checking where possible. Two of the four are machine-consumed configuration and could be derived from the directory rather than maintained by hand, which removes the drift rather than detecting it. The two markdown tables carry human-written descriptions and need a check instead.

PR #1394 leaves all four consistent, so this gate starts from a clean state.