Decision Records (ADRs)¶
This directory houses Architectural Decision Records (ADRs). ADRs explain Why We Chose It.
Naming Convention¶
Every ADR must be numbered sequentially:
ADR-0001-Why-Drupal.md
ADR-0002-Why-GitLab.md
Active candidates (2026-07-07)¶
| ADR | Title | Decision |
|---|---|---|
| ADR-0007 | Operational work System of Record | UNKNOWN — pending RX-BD-001, RX-BD-002 |
| ADR-0008 | Read-only upstream authority location | OPEN — do not standardize directory name yet |
Renumber note: ADR-0007 and ADR-0008 supersede collision files that incorrectly reused ADR-0003/0004 numbers (canonical ADR-0003 = portability; ADR-0004 = ContractPlane service). Second occurrence (2026-07-29): two parallel sessions independently claimed ADR-0018 for unrelated topics (Blu-as-reasoning-engine vs. RFP-serving-authority) on separate branches merged into the same integration branch same-day. Resolved by renumbering the later-merged one to ADR-0021. This is now a recurring failure mode, not a one-off — see the concurrency rule below.
Concurrent Editing Rule¶
ADR-INDEX.md is a shared index — governed by the estate-wide Shared Index Ownership rule in git-discipline.md §8. Concretely for ADRs: check for other open branches touching ADR-INDEX.md before adding a row; large corpus migrations land on one integration branch, not siblings; re-verify the index against origin/main immediately before claiming the next ADR number, not just at session start; on collision the later-merged ADR renumbers and its internal H1 header is fixed to match in the same commit.
Status¶
ADRs must use the standard document frontmatter, typically starting as candidate and eventually moving to approved or canonical. If a decision is reversed, the ADR is marked deprecated.