ADR 0186: ADR number uniqueness is gate-enforced, with an in-flight collision scan

Status: accepted

The record discipline allocates numbers at authoring time: list _adr/, take the highest number, add one. In the worktree workflow that allocation happens in isolation — so two in-flight efforts that each write an ADR both pick the same next number. The resulting records are different files with different slugs. Nothing in the machinery could see that state:

• The fleet collision scan is path-keyed — it intersects the fork diffs' changed paths, and two records sharing a number never share a path.
• The merge is clean. discern update brings the first-landed record into the second effort's tree without a conflict, and discern done passed with both 0184-*.md files sitting side by side.
• The only safeguard was the convention "whoever lands second renumbers," recorded nowhere a tool could act on it.

July 2026 made the race concrete: two parallel unlanded branches each carried an ADR numbered 0184, with more efforts in flight around them. A number that gets cited — in commit messages, code comments, map pages — becomes costlier to renumber the longer the duplicate lives, so the defect wants catching at two moments: the instant both claims exist anywhere (advisory), and the instant both records reach one tree (hard).

The gate holds ADR-number uniqueness tree-wide, and status warns number-keyed while the collision is still in flight.

• discern done runs an adr_numbers precondition beside the other shipped-artifact checks: a number claimed by more than one record file anywhere under the map's _adr/ tree — _superseded/ included, because a retired record keeps its number — fails the gate with a diagnostic naming each contested number and its claimants. The check is tree-wide, not branch-relative: a duplicate is wrong wherever it came from, and any branch can carry the renumber. It fires at exactly the right moment — the first done after discern update brings the rival record in — and makes the landed duplicate impossible.
• discern status scans every [repository].branch_prefix branch — worktree-backed and unlanded alike, since the second claimant is often a parked branch with no worktree — for record files their fork diffs add, groups them by number, and surfaces contested numbers as data.adr_collisions with one advisory hint. The fleet view carries every contested number; a worktree's local view carries only the collisions its own branch is party to. Each branch costs one merge-base plus one pathspec-scoped diff.
• One module (src/lib/adr_numbers.ts) defines what counts as a record file and how its number reads; both consumers share it, so they cannot drift on the definition.
• The bundled write-adr skill tells authors the picked number may be contested in flight and that whoever lands second takes the next free number — no fighting for a specific one.

• "Second lander renumbers" is now a mechanism, not a memory: update brings the rival record in, done refuses, the diagnostic says which files are in contention and what to do.
• The advisory scan shortens the expensive window — a renumber before anything cites the number is a file rename; the hint fires while that is still true.
• A project adopting discern with historical duplicate numbers is blocked at its first gate run until it renumbers once. Deliberate: the discipline ships as "a number identifies one decision forever," and a tree violating it should not pass.
• The gate pays one directory walk of _adr/ per run; status pays a scoped diff per in-flight branch. Projects without an _adr/ tree pay a single failed stat.
• The in-flight scan cannot see a collision with a record that landed on the trunk after a branch forked; the gate's tree-wide check covers that case on the branch's next update.

• Extend the path-keyed fleet collision scan. Rejected: it can never intersect two different filenames. Number-keying is the point — this is an instance of the "same logical resource, different path" class the path scan is structurally blind to.
• Central number reservation — an index entry or counter file every new record must touch, making the collision a textual merge conflict. Rejected: it turns every pair of concurrent ADRs into a guaranteed conflict to hand-resolve, moves allocation into merge machinery, and still needs a tree-level guard for the hand-edited case.
• A branch-relative check (fail only duplicates the branch introduced, never-loosen style). Rejected: it lets a duplicate that reaches the trunk persist forever. Tree-wide with a clear renumber remedy keeps the invariant honest everywhere.
• Advisory only, no gate stage. Rejected: a hint can be missed; the invariant the discipline promises ("never reuse a number") deserves the same enforcement as every other shipped-artifact precondition.