diff --git a/CLAUDE.md b/CLAUDE.md index 60e3b903..864e9a6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -197,6 +197,13 @@ spec than any English description of it. "Yes", "do it", "go", "ship it" are execution triggers. Do not re-summarise the plan. The context is loaded; the word is just the go signal. +### 5.6 Verification process +The path from invariant or hazard to passing test is described in +`docs/verification.md`. Acceptance criteria live in RFC §5; +`docs/rfcs/README.md` defines the maturity stages an RFC moves +through. The shortest version of the rule: *if a criterion cannot be +turned into a test, the RFC has a gap.* + --- ## 6. Code quality diff --git a/docs/rfcs/0001-template-miner.md b/docs/rfcs/0001-template-miner.md index 1f16f143..9ad340b5 100644 --- a/docs/rfcs/0001-template-miner.md +++ b/docs/rfcs/0001-template-miner.md @@ -1,7 +1,7 @@ --- rfc: 0001 title: Template miner (Drain-derived online log parsing) -status: draft +status: drafted author: Jens Holdgaard Pedersen drafting-assistance: Claude created: 2026-04-24 diff --git a/docs/rfcs/0002-query-dsl.md b/docs/rfcs/0002-query-dsl.md index 942029b7..d2501e4c 100644 --- a/docs/rfcs/0002-query-dsl.md +++ b/docs/rfcs/0002-query-dsl.md @@ -1,7 +1,7 @@ --- rfc: 0002 title: Query DSL — prior decision (borrow from OTTL or distance?) and candidate designs -status: draft +status: drafted author: Jens Holdgaard Pedersen drafting-assistance: Claude created: 2026-04-24 diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md index 8dd090c7..5b1da34a 100644 --- a/docs/rfcs/README.md +++ b/docs/rfcs/README.md @@ -32,7 +32,7 @@ When in doubt, assume RFC. --- rfc: NNNN title: Short descriptive title -status: draft | accepted | rejected | superseded +status: drafted | specified | red | green | validated | accepted | rejected | superseded author: Name drafting-assistance: Claude # omit if no LLM drafted created: YYYY-MM-DD @@ -41,6 +41,11 @@ superseded-by: — # or RFC NNNN --- ``` +The maturity stages (`drafted` through `validated`) are gates an RFC +moves through before it becomes binding; `accepted` is the terminal +post-maintainer-signoff state; `rejected` and `superseded` are the +off-ramps. See `docs/verification.md` §3. + ## Required sections Every RFC has at least: @@ -51,9 +56,17 @@ Every RFC has at least: produce the same implementation. 4. **Alternatives considered** — one paragraph each. "I have not heard of it" is not acceptable. -5. **Testing strategy** — mapped to `CLAUDE.md` §6.2. -6. **Open questions** — everything unresolved, as a checklist. -7. **References** — paper citations, related RFCs, `CLAUDE.md` +5. **Acceptance criteria** — normative scenarios, one per invariant + or hazard the RFC touches. Format: structured prose with + `Given / When / Then / And` leading clauses; each scenario carries + an id of the form `H1.1`, `§3.4.2`, or `RFC.`, referenced + from the test code so the mapping is greppable. See + `docs/verification.md` §2. +6. **Testing strategy** — mapped to `CLAUDE.md` §6.2; references the + §5 scenario ids and names the technique (`proptest`, corpus, + `criterion`) for each. +7. **Open questions** — everything unresolved, as a checklist. +8. **References** — paper citations, related RFCs, `CLAUDE.md` sections constrained. Additional sections are welcome when they clarify. Do not pad for the @@ -61,14 +74,32 @@ sake of the template. ## Lifecycle -1. **Draft** — PR opened with status `draft`. Discussion happens in PR - review. The RFC is not yet binding. -2. **Accepted** — maintainer approval, status flipped to `accepted` in - the same or a follow-up PR. Implementation may begin. -3. **Superseded** — a later RFC replaces part or all of this one. Both - frontmatters are updated. The superseded RFC is not deleted. -4. **Rejected** — closed PR or status flipped to `rejected`. The file - is kept for the record. +The five-stage maturity model. An RFC moves through these stages +before becoming binding; the `status:` frontmatter field tracks the +current stage so reviewers and tooling see it without reading the +body. + +1. **Drafted** — PR opened with status `drafted`. Sections §§1–4 and + §§7–8 are filled. Discussion happens in PR review. +2. **Specified** — §5 acceptance criteria are written, every + invariant and hazard the RFC touches has at least one scenario, + and review has confirmed the criteria are testable in principle. +3. **Red** — test stubs exist and fail. Implementation may begin. +4. **Green** — all acceptance criteria pass; unit + property + corpus + tests green. +5. **Validated** — thesis-gates in `docs/benchmarks.md` §7 pass on + representative corpora. Maintainer flips status to `accepted`. + +A regression detected after `Validated` either reopens the RFC (if a +criterion is invalidated) or spawns a tuning RFC per `benchmarks.md` +§7 (if a thesis-gate degrades). See `docs/verification.md` §3. + +Two terminals reachable from any stage: + +- **Superseded** — a later RFC replaces part or all of this one. + Both frontmatters are updated. The superseded RFC is not deleted. +- **Rejected** — closed PR or status flipped to `rejected`. The + file is kept for the record. ## Diagrams