An ADR records one architectural decision: the situation that forced it, what was decided, and what that costs. The contract in FEATURE_CONTRACT.md says what a slice must do; these records say why, so a later change can revisit a decision knowingly instead of undoing a deliberate trade-off by accident.
Any pull request that changes FEATURE_CONTRACT.md —
a rule, the required layout, or what npm run verify:features enforces — adds
a new ADR or supersedes an existing one in the same pull request. Changes that
only clarify wording do not need one.
- Copy template.md to
NNNN-short-title.md, using the next free number. Numbers are never reused. - Fill in Context, Decision and Consequences. Link the commits, issues or pull requests the decision rests on; do not state rationale that cannot be traced to one of them.
- Add a row to the index below.
Accepted ADRs are not rewritten. To change a decision, write a new ADR, set the
old one's status to Superseded by NNNN, and update both rows.
| ADR | Decision | Status |
|---|---|---|
| 0001 | One self-contained directory per tool | Accepted |
| 0002 | The tool registry is generated and gitignored | Accepted |
| 0003 | Expected failures are Result values with coded errors |
Accepted |
| 0004 | Fixtures live in the slice; requests are mocked with MSW | Accepted |
| 0005 | Runtime contract states are enforced with a shrinking ledger | Accepted |
| 0006 | Amounts and dates go through core/format |
Accepted |