diff --git a/.claude/rules.lock b/.claude/rules.lock new file mode 100644 index 0000000..2794757 --- /dev/null +++ b/.claude/rules.lock @@ -0,0 +1,3 @@ +[rules.adr-lifecycle] +adopted = "2026-08-04" +hash = "aabd778ef08e" diff --git a/CLAUDE.md b/CLAUDE.md index e558da4..85321b1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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//adr/`) diff --git a/docs/adr/0001-documentation-strategy.md b/docs/adr/0001-documentation-strategy.md index 17279e7..04f76b3 100644 --- a/docs/adr/0001-documentation-strategy.md +++ b/docs/adr/0001-documentation-strategy.md @@ -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.