Skip to content

Commit dfb0916

Browse files
committed
docs(adr): ADR-0027 also covers pre-implementation scoping notes
The scoping workflow (#42/#43 synthesis) flagged #79's open question: does docs/plans/ cover non-milestone design notes, or only per-milestone plans? Broaden the category to both — a milestone plan OR a scoping note for not-yet-scheduled work (e.g. the Phase-3 privsep scoping note from #43). A scoping note is non-authoritative from the start (records a constraint set + options, never a decision). Banner template gains a scopes/tracked-in variant and an ADRs/RFCs-or-tracking-issue pointer. CLAUDE.md's Plan bullet updated to match. Claude-Session: https://claude.ai/code/session_01BRMdwxsqYQPbjrWB1Cek6o Signed-off-by: Gonzalo Fleming <gonzafg2@gmail.com>
1 parent 8c7caca commit dfb0916

2 files changed

Lines changed: 13 additions & 11 deletions

File tree

‎CLAUDE.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,12 @@ authoritative reference; the operative rules a reviewer applies:
9797
docs, tests. When unsure which lane a change belongs in, open an issue and
9898
ask.
9999
- **Plan** ([`docs/plans/`](docs/plans/)) — a mutable, **non-authoritative**
100-
design note accompanying a milestone's implementation ([ADR-0027](docs/adr/0027-docs-plans-governance-category.md)).
101-
Post-merge the code, ADRs, and RFCs are authoritative, never the plan.
102-
Every plan carries a dated `Governance status` banner pointing at the
103-
ADRs/RFCs that hold its locked-in decisions, and **a plan is never the
104-
sole record of a locked-in decision** (that always goes to an ADR/RFC).
100+
design note: a milestone plan, or a scoping note for future work
101+
([ADR-0027](docs/adr/0027-docs-plans-governance-category.md)). The code,
102+
ADRs, and RFCs are authoritative, never the plan. Every plan carries a
103+
dated `Governance status` banner pointing at the ADRs/RFCs (or tracking
104+
issue) that hold its decisions, and **a plan is never the sole record of
105+
a locked-in decision** (that always goes to an ADR/RFC).
105106

106107
## Contribution conventions
107108

‎docs/adr/0027-docs-plans-governance-category.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,19 @@
1919

2020
## Decision
2121

22-
`docs/plans/` is a **fourth document category**: **mutable, non-authoritative design notes that accompany a milestone's implementation**. Its contract:
22+
`docs/plans/` is a **fourth document category**: **mutable, non-authoritative design notes**. These are either *milestone plans* that accompany an implementation (the M4/M5 plans) or *pre-implementation scoping notes* that capture the constraint set and options for future work before it is scheduled (e.g. a Phase-3 privilege-separation scoping note; issue #79 asked whether the lane covers such non-milestone notes — it does). Its contract:
2323

24-
1. **Non-authoritative after merge.** A plan guides the work while it is written and merged alongside it, but once the milestone lands the *code, ADRs, and RFCs* are authoritative — not the plan. A plan is retained for its design rationale, not as a source of truth for what the system does.
24+
1. **Non-authoritative after merge.** A note guides the work while it is written and merged alongside it, but once the work lands the *code, ADRs, and RFCs* are authoritative — not the note. A scoping note for not-yet-scheduled work is non-authoritative from the start: it records a constraint set and options, never a decision. A note is retained for its design rationale, not as a source of truth for what the system does.
2525

26-
2. **A mandatory, dated `Governance status` banner** heads every file in `docs/plans/`, in the same spirit as ADR-0015's errata banners. It states: the date, that the file is non-authoritative post-merge, which milestone it guided, and **which ADRs/RFCs hold the locked-in decisions**. Template:
26+
2. **A mandatory, dated `Governance status` banner** heads every file in `docs/plans/`, in the same spirit as ADR-0015's errata banners. It states: the date, that the file is non-authoritative, what it guides or scopes, and **which ADRs/RFCs (and/or tracking issue) hold the authoritative decisions**. Template:
2727

2828
```
2929
<!--
3030
Governance status (YYYY-MM-DD):
31-
Non-authoritative design note (ADR-0027). Guided <milestone> (PR #NN).
32-
Locked-in decisions live in ADRs/RFCs: <list>. This file is retained
33-
for rationale and is not a source of truth post-merge.
31+
Non-authoritative design note (ADR-0027). <Guided <milestone> (PR #NN)
32+
| Scopes <future work>; tracked in #NN>.
33+
Authoritative decisions live in ADRs/RFCs: <list, or "none yet">.
34+
This file is retained for rationale and is not a source of truth.
3435
-->
3536
```
3637

0 commit comments

Comments
 (0)