docs: ADR numbering discipline — assign numbers at merge-to-main

Codifies the fix for the ADR-0042 cross-branch collision (resolved this
merge by renumbering the website ADR to 0044): ADR numbers are assigned
when a branch merges to main, not at creation. On a branch, draft under
a placeholder (ADR-XXXX title / draft-<slug>.md filename); main's
docs/adr/README.md is the single source of truth for the next free
number.

- ADR-0000: new "Numbering discipline" section.
- CLAUDE.md: pointer to it from the documentation-discipline note.
This commit is contained in:
claude@clouddev1
2026-06-09 20:30:36 +00:00
parent 40de389bcb
commit 9e774b2dfa
2 changed files with 24 additions and 1 deletions
@@ -38,6 +38,26 @@ The index lists ADRs in numerical order. Each entry shows the
number, title, and — where relevant — status annotations such as
"Superseded by ADR-NNNN" or "Deprecated".
## Numbering discipline
ADR numbers are a single global sequence, so two branches can each grab
"the next number" independently and collide on merge. (This happened when
the `website` branch's ADR-0042 met `main`'s ADR-0042, resolved by
renumbering the former to ADR-0044.) To prevent it:
**Assign an ADR's number at merge-to-`main`, not at creation.** While the
work lives on a non-`main` branch, draft the ADR under a placeholder — an
`ADR-XXXX` title and a `draft-<slug>.md` filename — and reference it that
way from any plan or notes. Give it the next free number only when the
branch merges to `main`, renaming the file and updating its references in
the same step.
A number is "taken" only once it appears in `main`'s `docs/adr/README.md`,
which is the single source of truth for the next free number — never
compute "next" from a feature branch. A branch that genuinely needs a real
number up front may instead reserve one by landing a stub index entry on
`main` first, but placeholder-until-merge is the default.
## Out-of-scope discipline
ADRs (and the plans they spawn) lean heavily on "out of scope" language.