Skip to content

docs(adr): adopt append-only ADR lifecycle #198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
haribo merged 1 commit into from
Aug 12, 2026
Merged

docs(adr): adopt append-only ADR lifecycle #198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .claude/rules.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[rules.adr-lifecycle]
adopted = "2026-08-04"
hash = "aabd778ef08e"
3 changes: 3 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ This file takes precedence over auto-memory. If an auto-memory entry contradicts
- Code is never source of truth — code/design disagreement = code is the bug, or design needs an explicit amendment, never both silently
- If design is silent on a needed behavior: write design first, then code
- Group docs by single coherent concern — broad-keyword grab-bags (security, utils) are forbidden
- ADR lifecycle: never delete an ADR; a reversal is a **new** ADR, and both sides carry the link — `Superseded by ADR-NNN` on the old, `Supersedes ADR-MMM` on the new. A one-sided link is how the chain rots
- An ADR whose decision no longer applies, with no replacement, is marked `Deprecated` — never edited away or moved
- In-place edits only for corrections of form and for clarifications that do not change the decision

## Design & ADRs (`docs/design/`, `docs/adr/`, `docs/<crate>/adr/`)

Expand Down
14 changes: 10 additions & 4 deletions docs/adr/0001-documentation-strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,17 @@ A new technical doc must pass the severe 4-point test (§ 4).

### 4. Lifecycle and ownership

**ADR lifecycle** — editable. Edits go in place; the doc always shows the current
decision. Git log captures history (no revision section inside the ADR). Status:
**ADR lifecycle** — append-only. An accepted ADR is immutable: in-place edits only
for corrections of form and for clarifications that do not change the decision.
A reversal is a new ADR; the old one keeps its body, and both sides carry the
link. An ADR is never deleted, nor moved to another directory. Status:
- `Active` — current decision.
- `Superseded by ADR-XYZ` — only for major reversals. For clarifications or scope
tweaks, edit in place.
- `Superseded by ADR-XYZ` — replaced; the new record carries `Supersedes ADR-ABC`
back to this one. One-sided links rot: mark both.
- `Deprecated` — no longer applies, and nothing replaced it.

Applies from the merge of this change. Records written earlier were maintained
under an editable policy and may have been amended in place.

**Design lifecycle** — synchronous with code (per `CLAUDE.md`): a change
introducing user-facing behavior updates `docs/design/` in the same diff.
Expand Down
Loading