Status
Accepted (2026-07-09).
Context
The ADR corpus had mixed stability tiers — long-term invariants alongside current strategies alongside migration-period mechanisms. When merged, ADRs and architecture tests protected temporary policies as permanent dogma, growing shallow modules and blocking evolution.
Decision
Introduce a five-tier taxonomy (Constitution, Strategy, Migration, Historical, Reference) and a rule-priority order: latest Accepted/Revised ADR → Constitution invariants → a superseding ADR → current architecture docs/migration matrix → historical ADRs. Numbering is category-segmented (00xx–07xx, 99xx for superseded).
Two principles follow. Architecture tests protect invariants, not implementation: keep tests guarding interfaces, seams, and invariants; delete tests that force a file shape or treat a compat adapter/allowlist as a success state. Migration rules must be deletable: every Migration-tier rule declares an owner, scope, expiration, delete condition, current blocker, and whether its test is a ratchet or permanent gate. A migration rule with no delete condition lives only in temporary planning, never in an ADR.
Consequences
ADRs return to being decision records rather than rule-stacking. The unified-aggregate, AOT-generator, and deep-module refactors are no longer reverse-constrained by migration specs. The cost is short-term doc debt as old tests and guides are revised.
See also
Reviewers trace every catalog entry to the executable invariant and its regression test before accepting a lifecycle change.