Problem
docs/adr/NNNN-*.md sequential numbering has a structural race across the org's heavily concurrent-agent development model. In LineageWeave alone, a series of pessimistic-review passes across ~30 open PRs found ADR numbers 0119 through 0155+ independently claimed by dozens of different in-flight branches simultaneously — e.g. number 0119 alone was claimed by at least 5 separate branches, 0123 by 5+, 0131 by 4+.
Each collision has so far been fixed per-PR (scan main + every open branch for the next free number, rename, push) — but this is whack-a-mole: the scan-then-rename gap is itself a TOCTOU race (another branch can claim the same "next free" number in the interval between scan and commit), and every new PR pays the same full-repo scan cost to rediscover the same contested range. With ~50 concurrent branches this consumes real, repeated agent effort for no lasting fix — the collision just resurfaces for the next branch.
Proposed direction (not a decision — needs org input)
- New ADRs: switch from sequential numbers to date+slug filenames (
docs/adr/2026-08-23-<topic-slug>.md). This is structurally collision-proof — no coordination/reservation step needed, and the rare case of two branches choosing an identical slug on the same day is itself a signal they made the same decision, which surfaces naturally at merge time rather than needing prevention.
- Existing numbered ADRs (0002–0118+ on
main): leave as-is. A mass rename would break every in-code/in-doc "ADR NNNN" cross-reference across the whole tree for marginal benefit.
- Interim mitigation if an immediate numbering-scheme change isn't feasible: move collision detection from N agents each pre-scanning ~50 branches to a single point at actual merge time (which is naturally serialized — merges happen one at a time). Whatever process actually performs merges could add one check: does this PR's new ADR path already exist on the target branch post-merge? If so, rename to the next free number as part of the merge step and note it in the merge commit. This is strictly cheaper than the current per-PR full-branch-scan approach and needs no new infrastructure — it's the same repair the ad hoc
codex/fix-*-adr-collision branches already do, just moved earlier/centralized.
Evidence
Collisions found and fixed (each independently, via full branch scans) across LineageWeave PRs during today's review passes:
This is not a one-off; it recurs on nearly every PR that adds a new ADR right now.
Scope
This affects any ContextualWisdomLab repo using sequential ADR numbering with this level of concurrent-branch activity, not just LineageWeave — raising centrally rather than fixing unilaterally per-repo.
Surfaced via cross-session coordination between two Claude Code sessions working the LineageWeave PR queue (2026-08-23) — proposal direction co-developed with the "lineageweave wiring completion" session, which independently reached the same date+slug conclusion and proposed the merge-time-single-point mitigation.
Problem
docs/adr/NNNN-*.mdsequential numbering has a structural race across the org's heavily concurrent-agent development model. In LineageWeave alone, a series of pessimistic-review passes across ~30 open PRs found ADR numbers 0119 through 0155+ independently claimed by dozens of different in-flight branches simultaneously — e.g. number 0119 alone was claimed by at least 5 separate branches, 0123 by 5+, 0131 by 4+.Each collision has so far been fixed per-PR (scan
main+ every open branch for the next free number, rename, push) — but this is whack-a-mole: the scan-then-rename gap is itself a TOCTOU race (another branch can claim the same "next free" number in the interval between scan and commit), and every new PR pays the same full-repo scan cost to rediscover the same contested range. With ~50 concurrent branches this consumes real, repeated agent effort for no lasting fix — the collision just resurfaces for the next branch.Proposed direction (not a decision — needs org input)
docs/adr/2026-08-23-<topic-slug>.md). This is structurally collision-proof — no coordination/reservation step needed, and the rare case of two branches choosing an identical slug on the same day is itself a signal they made the same decision, which surfaces naturally at merge time rather than needing prevention.main): leave as-is. A mass rename would break every in-code/in-doc "ADR NNNN" cross-reference across the whole tree for marginal benefit.codex/fix-*-adr-collisionbranches already do, just moved earlier/centralized.Evidence
Collisions found and fixed (each independently, via full branch scans) across LineageWeave PRs during today's review passes:
This is not a one-off; it recurs on nearly every PR that adds a new ADR right now.
Scope
This affects any ContextualWisdomLab repo using sequential ADR numbering with this level of concurrent-branch activity, not just LineageWeave — raising centrally rather than fixing unilaterally per-repo.
Surfaced via cross-session coordination between two Claude Code sessions working the LineageWeave PR queue (2026-08-23) — proposal direction co-developed with the "lineageweave wiring completion" session, which independently reached the same date+slug conclusion and proposed the merge-time-single-point mitigation.