Superseding an ADR is a five-file hand ritual and nothing checks that the two ends of the link agree.

Superseding an ADR is a five-file hand ritual and nothing checks that the two ends of the link agree.

Observed in a managed repository whose stated rule is "never change an ADR, supersede it". Doing that meant, per supersession: a new file, supersedes: in its frontmatter, a Supersedes line in its body, the old file's status and superseded_by fields, and an index README row for both. Three ADRs were superseded this way in one day. Nothing verifies that a superseded_by has a matching supersedes in the named record, or the reverse, so a half-finished supersession reads as a complete one.

The same repository turned up the neighbouring gap in the same sweep: an ADR filed on one day had no row in the ADRs README until the next. The README says the row is a hand edit, and nothing checks it, so an ADR can exist and be invisible to every reader who starts at the index.

Wanted: abcd decide --adr --supersedes adr-N doing all five edits as one operation; and a record-lint row, beside the existing record-provenance rule, that fails when an ADR file has no row in the ADRs README, and when superseded_by and supersedes disagree in either direction. Both are the same class of check the ledger already applies to issues by folder membership; ADRs get it by hand or not at all.

Remedy grounds (2026-09-29)

Why: the ritual is five mechanical edits and the one-way check already exists, so the gap is the writer and the index row. SOTA check: adr-tools supersedes in one command, adr new -s N, which marks the old record superseded and links the new one (https://github.com/npryce/adr-tools, read 2026-09-29), and MADR records it in status as superseded by ADR-NNNN (https://adr.github.io/madr/, read 2026-09-29). Adopted the one-command shape, not the tool, which would add a shell toolchain beside the Go binary.