wdi-method 0.5.13 → 0.6.0

package/kit/.constitution/method/document/delivery-flow-guide.md

@@ -4,11 +4,11 @@ status: Accepted
 
 # Delivery Flow Guide
 
-**Loaded when:** opening or closing a gate, opening or closing a wave, setting `mode` or
+**Loaded when:** opening or closing a gate, opening or closing a spec, setting `mode` or
 `risk_accepted`, and any time something already agreed has to change
 
 This is the flow itself: five gates, the one knob that sets document depth, the one field that sets
-review intensity, wave sizing, and what happens when a settled thing has to move. Every other guide
+review intensity, spec sizing, and what happens when a settled thing has to move. Every other guide
 describes one document; this one describes the order they arrive in.
 
 ## Two fields, and the separation between them is the point
@@ -28,6 +28,10 @@ depth you wanted. Recording what is accepted is the entire reason that field exi
 Project size MUST NOT appear as an input anywhere. Size decides how many components there are, not how
 deep each one goes.
 
+All twelve combinations of the two are legal, and what each one costs is laid out side by side in
+`.constitution/method/why/mode-risk-map.md`. It explains and MUST NOT be cited as a rule — this guide is
+where both fields are defined.
+
 ### `mode` — two scopes, and the per-component one wins
 
 | Scope | Where | Means |
@@ -38,9 +42,9 @@ deep each one goes.
 Raising and lowering are both **free and need no justification** — it is a preference, and a preference
 does not have to be defended.
 
-**There is no third scope.** `mode` MUST NOT be overridden per wave or per `SPEC.md`. A wave MAY cross
-several components, so a per-wave override would give one component two different depths depending on
-which wave touched it — while the document is one, and living.
+**There is no third scope.** `mode` MUST NOT be overridden per spec or per `SPEC.md`. A spec MAY cross
+several components, so a per-spec override would give one component two different depths depending on
+which spec touched it — while the document is one, and living.
 
 > Depth belongs to the component, not to the work.
 
@@ -82,36 +86,50 @@ is the lightest.
 
 `structure` and `prose` are the baseline everywhere. What `risk_accepted` decides is what is **added**:
 
-| Value | Lenses on the documents | On the code |
-|---|---|---|
-| `low` | `structure` · `prose` · **`edge-case-hunter`** | a two-reviewer panel is **required** |
-| `medium` | `structure` · `prose` · **`edge-case-hunter`** | — |
-| `high` | `structure` · `prose` | — |
+| Value | First review, and the review before a gate | Every re-review after | On the code |
+|---|---|---|---|
+| `low` | `structure` · `prose` · **`edge-case-hunter`** | `structure` · `prose` | a two-reviewer panel is **required** |
+| `medium` | `structure` · `prose` · **`edge-case-hunter`** | `structure` · `prose` | — |
+| `high` | `structure` · `prose` | `structure` · `prose` | — |
+
+The heavy lens is bought **once per artifact and once per gate**, not once per edit. A re-review MUST put
+it back when the delta touches money, personal data, an irreversible action, or a third party. And a
+review trace has to be fresh **at a gate and at spec close** — between those points a stale trace is
+advisory, not a failure. `wdi-review` owns the mechanics of both, including the one case where re-stamping
+without re-running is allowed: a change to wording only.
 
 Review lenses are decided here and **nowhere else**. They MUST NOT be read off `mode`: one component MAY
 sit at `mode: catalog` and still be reviewed the hardest.
 
 Two things are not free, and `wdi-init` owns the conversation around both: `risk_accepted: high` on a
 component touching money, personal data, an irreversible action, a contractual promise, or an
-un-rollbackable integration requires a `DEC-` of `type: risk-acceptance` with `risk_accepted_by:` pointing
-at it (V23) — and an outside party who will demand the artifacts as a deliverable puts the touched
-component at `mode: deep` and `risk_accepted: low` whatever the global setting says.
+un-rollbackable integration requires a named acceptance in `risk_accepted_by` — a person and a date,
+written beside the risk (`high-risk-named`) — and an outside party who will demand the artifacts as a deliverable puts
+the touched component at `mode: deep` and `risk_accepted: low` whatever the global setting says.
 
 ## Five gates
 
 A gate is named for **what is decided there**, never for the work that precedes it. Owner time is spent at
 these five points only; between them the agents work alone.
 
-| Gate | Decides | How often | Budget | Varies by `mode`? |
-|---|---|---|---|---|
-| **G1 Problem** | What the problem is, whose it is, why it earns work | once | 20' | no |
-| **G2 Product** | What is built, and how it feels to use | once per PRD | 45' | no |
-| **G3 Blueprint** | The whole portrait: which use cases, their entities, tables, endpoints, screens, and the invariants binding them | **once per product** | 45' | no |
-| **G4 Component** | How one Product Component is built, and what the choice costs | **once per Product Component** | 20–30' | **yes — the only one** |
-| **G5 Release** | Whether it is done and proven | once per wave | 10' | flags only |
+| Gate | Decides | How often | Budget | The session itself | Its checklist |
+|---|---|---|---|---|---|
+| **G1 Problem** | What the problem is, whose it is, why it earns work | once | 20' | unchanged | 2 of 7 at `catalog` |
+| **G2 Product** | What is built, and how it feels to use | once per PRD | 45' | unchanged | 3 of 7 at `catalog` |
+| **G3 Blueprint** | The whole portrait: which use cases, their entities, tables, endpoints, screens, and the invariants binding them | **once per product** | 45' | unchanged | 3 of 7 at `catalog` |
+| **G4 Component** | How one Product Component is built, and what the choice costs | **once per Product Component** | 20–30' | **skipped entirely at `catalog`** | 4 of 7, and 30' at `deep` |
+| **G5 Release** | Whether it is done and proven | once per spec | 10' | unchanged | 2 of 7 at `catalog` |
 
-**Only one gate changes shape with `mode`.** That is what makes this holdable in one head: four of the five
-are always the same, whatever the setting.
+Two different things move, and reading them as one is what makes this table easy to get wrong:
+
+- **What a gate decides, how often it runs, and its budget never change.** All five, at every setting.
+- **G4 is the only gate that can disappear.** At `catalog` its session does not happen at all; the other four
+  always run.
+- **Checklist length is the one thing `mode` shortens everywhere.** At `catalog` only the ★ questions are
+  required, at G1 and G5 as much as at G4 — see the checklists below.
+
+That is what makes this holdable in one head: four of the five sessions are always there, and the only
+question is how long their checklist is.
 
 The word "area" is not used anywhere. There is only Product Component.
 
@@ -144,7 +162,7 @@ build. Gating per component means approving seven times, each time seeing a seve
 Two blueprint contents cannot be per component: a per-component DB inventory is a lie because tables are
 shared, and a per-component spine contradicts what a spine is.
 
-**What is reviewed at G3 is the generated roll-up**, `.control/generated/blueprint.md`, not seven files. The
+**What is reviewed at G3 is the generated roll-up**, `.how-rendered/blueprint.md`, not seven files. The
 catalogue, actor list, and domain model stay in their component kernels as their permanent home; the roll-up
 assembles them into one page to read. One fact, one home, one view.
 
@@ -161,8 +179,13 @@ MUST NOT be negotiated.
 
 Each question is answered **yes / no / change**. One "no" on a ★ question holds the gate.
 
-**On `mode: catalog`, only the ★ questions are asked** — fourteen across all five gates. The rest stay here
-as material, and asking them is never wrong; requiring them is.
+**On `mode: catalog`, only the ★ questions are required.** There are fourteen ★ across the five gates, but
+four of them belong to G4 — which `catalog` skips — so what actually gets asked there is **ten**. The rest
+stay here as material, and asking them is never wrong; requiring them is.
+
+Which `mode` the rule reads depends on the gate. **G1 and G2 can only read the global `mode`**, because no
+component exists yet and `risk_accepted` has no value at all until `wdi-init` intent `component` runs at the
+tail of G2. G4 reads the `mode` of the component in front of it.
 
 ### G1 Problem · 20'
 
@@ -186,7 +209,7 @@ as material, and asking them is never wrong; requiring them is.
 
 ### G3 Blueprint · 45'
 
-Read against `.control/generated/blueprint.md`, not against seven files.
+Read against `.how-rendered/blueprint.md`, not against seven files — every one of the seven questions below is answerable from that page.
 
 1. ★ Is every use case title a sentence a user would say, not a system term?
 2. ★ Any `FR` with no use case? (the validator answers this, not an opinion)
@@ -207,93 +230,116 @@ Skipped entirely at `mode: catalog`.
 3. ★ What stops us starting tomorrow? (MUST be empty)
 4. ★ Validators green **and** the review leaving no open finding? (both — one is fact, one is judgement)
 5. Does any choice here lock us to one vendor or technology for more than a year?
-6. From the DAG: which story blocks the most other stories?
+6. From the DAG: which ticket blocks the most other tickets?
 7. Top risk: who owns it, and what is the pivot trigger to turn or give up?
 
 ### G5 Release · 10'
 
-1. ★ Is every RTM row for this wave green?
-2. ★ Is every story's acceptance criteria proven by a test, not by an agent's statement?
+1. ★ Is every RTM row for this spec green?
+2. ★ Is every ticket's acceptance criteria proven by a test, not by an agent's statement?
 3. What was dropped from the plan, and where is it recorded?
 4. Are new risks found while building in the Risk Register?
-5. What one thing made this wave take longer than expected?
+5. What one thing made this spec take longer than expected?
 6. What does the client need to know before this goes live?
 7. What is watched in the first week?
 
-## Units of work — `FR`, wave, `SPEC`, story
+## Units of work — `FR`, spec, `SPEC`, ticket
 
 | Unit | Is | Lifetime |
 |---|---|---|
 | `FR-N` | One **feature** — one promise to a user. Born at G2 | permanent, lives across releases |
-| wave | One **unit of work**. Opens at G4 or G5, closes at G5 | one slice of work |
-| `SPEC.md` | The machine contract for **one wave**. A projection of `.what/` + `.how/`, and MUST NOT contain anything new | one wave |
-| story | One piece taken by one builder to a green PR | one wave |
+| spec | One **unit of work**: the tickets that reach one outcome. Opens at G4 or G5, closes at G5 | one slice of work |
+| `SPEC.md` | The **document** of one spec: a projection of `.what/` + `.how/` that MUST NOT contain anything new. **Not written at size `S`** | one spec |
+| ticket | One **tracer-bullet vertical slice**: complete through every layer, verifiable on its own, sized to one fresh context window, carrying the tickets that block it | one spec |
 
-**One wave = one `SPEC` = one tracker Task.** One to one to one, with no compound joins.
+**One spec = one set of tickets = one parent issue.** One to one to one, with no compound joins. `SPEC.md`
+joins that identity from size `M` up; at `S` there is no document and **the tickets are the contract.**
 
-A wave's scope is flexible and **ideally one `FR`**, because an `FR` is human-testable from birth — it has a
-proof of done. One `FR` MAY span several waves, one wave MAY carry several small neighbouring `FR`, and a
-wave MAY be a standalone slice of one large `FR`.
+A spec's scope is flexible and **ideally one `FR`**, because an `FR` is human-testable from birth — it has a
+proof of done. One `FR` MAY span several specs, one spec MAY carry several small neighbouring `FR`, and a
+spec MAY be a standalone slice of one large `FR`.
 
-A wave MAY cross several Product Components. One condition: **G4 has passed for every component the wave
-touches**, or that component is at `mode: catalog`, whose G4 is skipped by design (V22). That is why G4 and
-the wave are deliberately different units — G4 decides *how one component is built*, a wave decides *which
+A spec MAY cross several Product Components. One condition: **G4 has passed for every component the spec
+touches**, or that component is at `mode: catalog`, whose G4 is skipped by design (`spec-after-g4`). That is why G4 and
+the spec are deliberately different units — G4 decides *how one component is built*, a spec decides *which
 work happens now*.
 
-`SPEC.md` and story files **are not read by humans.** Both are machine contracts, and no review burden MAY
+A ticket is **vertical, never horizontal**: it cuts a narrow but complete path through schema, API, UI, and
+tests, and a finished one is demoable on its own. A slice of one layer is not a ticket. **The one exception
+is a wide refactor** — a mechanical change whose blast radius breaks call sites everywhere at once, where no
+vertical slice can land green. That is sequenced **expand → migrate in batches → contract**, each batch its
+own ticket blocked by the expand, and the contract blocked by every batch.
+
+`SPEC.md` and ticket files **are not read by humans.** Both are machine contracts, and no review burden MAY
 be moved onto them. The human review surface stops at the PRD, `.what/`, and `.how/`.
 
 ### Mapping to a tracker
 
-| Jira | WDI | Lifetime |
+| Tracker | WDI | Lifetime |
 |---|---|---|
-| Epic | Product Component | permanent — an Epic never closes |
-| Task | **wave = `SPEC.md`** | one wave |
-| Sub-task | story | one wave |
+| **Parent issue** | **spec** | one spec |
+| **Issue, carrying native blocking edges** | **ticket** | one spec |
 | Fix Version | release | one release |
-| Label / custom field | the `CAP-N` and `FR-N` the wave satisfies | — |
+| Label / custom field | the `CAP-N` and `FR-N` the spec satisfies | — |
 | — a document, not an issue | `.what/` · `.how/` · `SPEC.md` | — |
 
-**`FR` is not a Task.** It sits at the level of *promise*, not of *work*: one `FR` MAY be delivered by
-stories in two waves, and one story MAY satisfy part of two `FR`. Mapping promise onto work-issue forces a
-1:1 that does not exist, and produces Tasks opened at G2 that hang across releases. `FR` travels as a label
-on the Task.
+A ticket is an **issue**, not a sub-task, because its blocking edges are what make the frontier visible in
+the tracker's own UI — the set of tickets whose blockers are all closed, and therefore takeable now. A
+sub-task cannot carry that relation.
 
-**The corpus stays the source of truth; the tracker is a view.** Story status is read from story-file
-frontmatter, never copied into two places.
+**`FR` is not an issue.** It sits at the level of *promise*, not of *work*: one `FR` MAY be delivered by
+tickets in two specs, and one ticket MAY satisfy part of two `FR`. Mapping promise onto work-issue forces a
+1:1 that does not exist, and produces issues opened at G2 that hang across releases. `FR` travels as a label.
 
-**Parallelism.** Between stories through the `depends_on` and `touches` DAG; between waves through
-`depends_on` at wave level. A wave that declares no dependency runs in parallel.
+**The corpus stays the source of truth; the tracker is a view.** Ticket status is read from **the ticket
+itself**, never copied into two places — and `specs.yaml` holds the **index**, not the bodies: one row per
+ticket with `satisfies`, `blocked_by`, `touches`, and its test names. That is what RTM and the validators
+read; the ticket's prose stays where the tracker put it.
 
-## Wave size, and what it does not decide
+**Two edge fields, and the difference is not cosmetic.** A spec `depends_on` another spec — an ordering
+between units of delivery. A ticket is `blocked_by` other tickets, which is the word the tracker uses for
+the same relation and the field the frontier is read from. `no-cycles` walks both graphs; `parallel-tickets-blocked` reads the ticket one.
+
+**Where a ticket lives, and what it is called.** `{spec_folder}/issues/<NN>-<slug>.md`. Only the root is
+ours: the folder, the numbering from `01` in dependency order, and the file's shape belong to the engine
+that writes them. A ticket's `id` in `specs.yaml` is `<spec-id>-<NN>` — `SPEC-3-01` — because the engine's
+number is unique only inside one spec and the RTM needs a key that is unique across the corpus. `ticket-status-one-home` finds
+the file from the number at the tail of the id.
+
+**Parallelism.** Between tickets through their blocking edges plus the `touches` check; between specs
+through `depends_on` at spec level. A spec that declares no dependency runs in parallel.
+
+## Spec size, and what it does not decide
 
 | Size | Shape | Effect |
 |---|---|---|
-| **S** | ≤3 stories, no new `FR` | G4 and G5 merge into one 20-minute session |
-| **M** | 4–12 stories | as usual |
-| **L** | >12 stories, or a new container | the retrospective runs |
+| **S** | ≤3 tickets, no new `FR` | G4 and G5 merge into one 20-minute session · **`SPEC.md` is not written** — the tickets are the contract |
+| **M** | 4–12 tickets | `SPEC.md` written first, because the seams and the testing decisions have to be settled before tickets are cut |
+| **L** | >12 tickets, or a new container | as `M`. Its one distinct effect was the retrospective, which is retired, and `V19` with it |
 
-Size is recorded in `waves.yaml`. It MAY be raised mid-flight; it MUST NOT be lowered.
+Size is recorded in `specs.yaml`. It MAY be raised mid-flight; it MUST NOT be lowered.
 
-**Size does not choose which gates are active** — that is `mode`'s job. It only governs session merging and
-whether the retrospective is required.
+**Size does not choose which gates are active** — that is `mode`'s job. It decides two things: whether G4
+and G5 merge into one session (`S`), and whether `SPEC.md` is written at all (`M` and up).
 
 **Fast Path** skips every gate. It is available for a fix that changes no `FR`, `UC`, `AD-N`, or domain
-model, is at most one story, and touches no money, personal data, or third-party integration. If an `FR`
-turns out to be touched, work MUST stop and become a wave `S`.
+model, is at most one ticket, and touches no money, personal data, or third-party integration. If an `FR`
+turns out to be touched, work MUST stop and become a spec `S`.
 
-## Story-closing checklist — three items
+## Ticket-closing checklist — three items
 
-Answered as each story finishes, before the next is picked up.
+Answered as each ticket finishes, before the next is picked up.
 
-1. A decision worth remembering? → `wdi-decision`. A story that contradicts an `AD-N` **stops** rather than
+1. Something the next person needs to know? → **into the document that carries it**, and that is almost
+   always where it ends. It reaches `wdi-decision` only when no design document has a home for it —
+   `decision-guide.md` § A decision's first home. A ticket contradicting an `AD-N` **stops** rather than
    closing; that is the one case where recording is mandatory.
 2. A trap for the next agent? → recorded where the next agent will read it.
-3. Test names matching what `waves.yaml` records?
+3. Test names matching what `specs.yaml` records?
 
-Five items left this list and did not disappear — they moved to **wave close**, where the information is
-actually available: `LC` registration (V12), the `touches` check, SPEC companion distillation, and the
-structure-map refresh. Registering an `LC` before a story was `ready-for-dev` demanded the answer at the
+Five items left this list and did not disappear — they moved to **spec close**, where the information is
+actually available: `LC` registration (`lc-registered`), the `touches` check, SPEC companion distillation, and the
+structure-map refresh. Registering an `LC` before a ticket was `ready-for-agent` demanded the answer at the
 moment it was thinnest.
 
 ## When something settled has to change
@@ -301,28 +347,53 @@ moment it was thinnest.
 One trigger: **an artifact other people agreed to needs to change.** Run this matrix and reopen the gates it
 names.
 
+**Reopening a gate means re-deciding, not re-recording.** The column below names the gate whose *decision*
+the change invalidates — the session runs again because the answer might now be different. Where the chain
+changes but the decision does not, the documents are **edited in place** and no gate opens or closes. There
+is no ceremony to perform, and nothing anywhere records that the change arrived late: the commit does that,
+and it does it better than a paragraph.
+
+**A change that arrives during G5 is written as if it had been there from the start.** Present tense, folded
+in, not appended and not annotated — `corpus-guide.md` § The corpus is written in the present tense owns
+that rule and it is not softened here.
+
 | What changes | MUST be re-reviewed | Gate reopened |
 |---|---|---|
 | Business Goal | The whole chain beneath it | G1 |
-| `FR` — its **promise** | Related `UC`, decisions naming it, stories not yet `in-progress`, RTM rows | G2 then G3 |
+| `FR` — its **promise** | Related `UC`, decisions naming it, tickets not yet started, RTM rows | G2 then G3 |
 | `FR` — its **wording** only | Nothing. The skill at work fixes it, one Revision History row per pass | none |
 | `NFR` | Its enforcing decisions and tests | G4 |
-| UX flow | Related use case specifications, stories not yet `in-progress` | G3 |
+| UX flow | Related use case specifications, tickets not yet started | G3 |
 | Business rule | `UC` using it, related tests | G3 for a cross-component rule, G4 for a local one |
-| An `AD-N` | Affected C4 components, stories not yet `in-progress` | G4 |
-| Story acceptance criteria | That story's tests, its RTM row | none — the row going green again is enough |
+| An `AD-N` | Affected C4 components, tickets not yet started | G4 |
+| Ticket acceptance criteria | That ticket's tests, its RTM row | none — the row going green again is enough |
 
 The promise-versus-wording split is owned by `prd-guide.md` and MUST NOT be re-decided here.
 
-- A story already `in-progress` MUST NOT have its contract changed. Stop it, return it to `ready-for-dev`,
-  then change it.
+**Once the owner has decided, the survey is spent.** The agent reads the chain — `BG`, `CAP`, `FR`, `UC`,
+the rules, the `AD-N` — and says **once**, in one place, what the change breaks and what it costs. That is
+the warning, and the owner is entitled to it. When they choose anyway, what the survey found becomes
+**edits**: not findings, not `OQ-` rows, not a review, and not a second pass raising the same conflicts in
+different words. Re-arguing a decision the owner already took is the most expensive thing an agent does in
+this method, and it buys nothing that the first warning did not already buy.
+
+The one thing that still stops rather than warns: a change contradicting an `AD-N`. That is an invariant the
+architecture rests on, `decision-guide.md` owns it, and the stop is a `DEC-` — one page, then proceed.
+
+- A ticket already **started** MUST NOT have its contract changed. Stop it, return it to
+  `ready-for-agent`, then change it.
 - Superseded artifacts are never deleted. Their status becomes `superseded` and points at the replacement.
-- A change that cancels more than 30% of a wave's stories MUST go through `wdi-decision`, which wraps
+- A change that cancels more than 30% of a spec's tickets MUST go through `wdi-decision`, which wraps
   `bmad-correct-course`, rather than being patched.
 
-**A new PRD arriving after G3 amends the blueprint; it does not repeat it.** The new components are born,
-their rows join the catalogue and the three inventories, and **G3 reopens over the delta only**. The
-45-minute session does not run again for one additional initiative.
+**A reopened gate reopens over the DELTA, always.** Never the whole session, and never the whole
+checklist — only the questions the change actually put back in play. The budgets in the gate table are
+for a gate's **first** run; a reopening costs what the delta costs and usually far less.
+
+This was already true for one case and was never generalised: a new PRD arriving after G3 amends the
+blueprint rather than repeating it — the new components are born, their rows join the catalogue and the
+three inventories, and G3 reopens over the delta only. One feature added during G5 is the same shape. It
+puts its own `FR` and `UC` back in play and nothing else, so it costs a few minutes, not ninety.
 
 ## Roles
 
@@ -331,8 +402,8 @@ their rows join the catalogue and the three inventories, and **G3 reopens over t
 | Product Owner | Answers the checklists, decides at the five gates, sets `mode` and `risk_accepted`, owns risk | Write artifacts, read machine contracts |
 | Agent at G1–G3 | Writes the brief, the PRD, and the blueprint | Decide depth or accept risk |
 | Agent at G4 | Writes one component's behaviour and mechanism | Write code |
-| Builder | One story through to a green PR | Change `.what/`, `.how/`, or an `applied` decision |
-| Review panel | Two different CLI families, neither the builder's | Give a final verdict — findings are adjudicated by the coordinator |
+| Builder | One ticket through to a green PR | Change `.what/`, `.how/`, or an `applied` decision |
+| Review panel | Reviews the diff independently of the builder | Give a final verdict — findings are adjudicated by the coordinator |
 
 Panel composition and CLI/model selection are governed by the global Agent Rules and MUST NOT be restated
 here.

package/kit/.constitution/method/document/prd-guide.md

@@ -30,7 +30,7 @@ This is the decision the guide exists for, and the default is **Update**.
 | Situation | What to do |
 |---|---|
 | Behaviour of an existing promise changes | Update |
-| A promise turns out to be wrong and must be withdrawn | Update — and the withdrawal MUST be visible in Revision History, not silently deleted |
+| A promise turns out to be wrong and must be withdrawn | Update — and the withdrawal MUST be visible in Revision History, not silently deleted. This is the one mandated history line in the method, and it survives because it is **business** history read by someone outside the room, not a record that a document changed |
 | A new feature that a reader would expect to find in this PRD | Update |
 | The next release extends what this PRD already promises | Update. A release is never a reason on its own |
 | A functional area a reader would not think to look for here | New PRD |
@@ -92,7 +92,7 @@ carried by:
 | Field | Answers |
 |---|---|
 | `CAP.target_release` | Which release this capability is planned for. **The only place a promise's release is written** |
-| `waves.yaml` `release` | Which release a wave of work belongs to — the execution side |
+| `specs.yaml` `release` | Which release a spec of work belongs to — the execution side |
 
 An `FR` MUST NOT carry a release of its own. It inherits one from its `CAP`, the same way it reaches
 its `BG`: each child names only its parent. A capability whose requirements genuinely land in
@@ -102,30 +102,36 @@ Naming a release in prose as context MAY happen; the registry is what binds.
 
 ## Numbering
 
-`BG-N`, `CAP-N`, `FR-N`, `NFR-N`, and `UJ-N` MUST be allocated from `.control/registry/requirements.yaml`
-and MUST NOT restart at 1. The chain runs `BG → CAP → FR/NFR → UC → DEC → Story → Test`, and each
+`BG-N` is allocated from `.control/registry/goals.yaml`; `CAP-N`, `FR-N`, `NFR-N`, and `UJ-N` from this initiative's own `.control/registry/requirements-<slug>.yaml` — one file, one writer, one gate
+and MUST NOT restart at 1. The chain runs `BG → CAP → FR/NFR → UC → DEC → Ticket → Test`, and each
 child names only its parent:
 
-- Each feature in §4 MUST declare its `CAP-N` and the `BG-N` it serves.
+- Each feature in §3 MUST declare its `CAP-N` and the `BG-N` it serves.
 - Each `FR` MUST declare its `capability`. Its goal is reached *through* the capability and MUST NOT
   be restated on the FR.
 - Each `NFR` attaches to `BG` directly — it does not pass through `CAP`.
 
-V15 checks both links. An FR with no capability is a promise nobody asked for.
+`chain-links` checks both links. An FR with no capability is a promise nobody asked for.
 
-## Proof of done — one, in business language
+## `FR`/`NFR` text lives in the registry, not in this document
+
+The PRD cites `FR-N`/`NFR-N` under each feature's **Realizes:** line. It MUST NOT also write the
+statement, the proof of done, or the enforcer in prose — those fields live on the id's own row in
+`requirements-<slug>.yaml`, and landing them there is part of `wdi-product` producing this PRD, not a
+follow-up. A promise written in both places is one fact with two homes, and the copy a reader trusts
+is whichever they open first.
 
 Every `FR` MUST carry **exactly one** proof of done: a sentence a Product Owner can check without opening
-the code. It is what lets one `FR` become one testable unit of work, and it is why a wave is ideally one
+the code. It is what lets one `FR` become one testable unit of work, and it is why a spec is ideally one
 `FR`.
 
-**The double proof of done is repealed.** Requiring a business sentence *and* a technical restatement
-naming status codes, limits, and payloads meant writing the same acceptance twice, in two vocabularies that
-then drifted. The technical form is represented by the **test name** recorded in `waves.yaml`, where it is
-checked mechanically (V4) instead of read.
+**The double proof of done stays repealed.** A business sentence *and* a technical restatement naming
+status codes, limits, and payloads meant writing the same acceptance twice, in two vocabularies that
+then drifted. The technical form is represented by the **test name** recorded in `specs.yaml`, where it
+is checked mechanically (`ticket-has-test`) instead of read.
 
-A technical detail that genuinely has to be written down belongs in `addendum.md` or in the SDD, not in a
-second proof of done.
+A technical detail that genuinely has to be written down belongs in `addendum.md` or in the SDD, not in
+a second proof of done — and not in this document's prose either.
 
 ## Wording versus promise — two different journeys
 
@@ -148,7 +154,7 @@ gate and then get dropped.
 
 A domain entity MUST have exactly one owner authorised to write it. Usually that is a Product Component,
 declared as `owns:` on its row in `components.yaml`; an `FR` from another PRD that needs to change the entity
-MUST point at the owner's `FR` through `defers_to`, rather than promising to write it itself. V21 checks this.
+MUST point at the owner's `FR` through `defers_to`, rather than promising to write it itself. `entity-one-writer` checks this.
 
 **A few entities belong to no Product Component at all** — a product-wide setting, the trace of one shared
 outbound channel. Those are owned by `_platform` through `platform_owns`, and the test for when that is
@@ -162,12 +168,13 @@ moment it is written — not at the moment the code disagrees.
 
 ## Sections that stop being optional
 
-BMad's Adapt-In Menu is conditional by design. Two clusters MUST always be present here:
+BMad's Adapt-In Menu is conditional by design. Two clusters MUST always be present here, and are in
+the Essential Spine rather than the Adapt-In menu for exactly that reason:
 
-| Cluster | Why it is required |
-|---|---|
-| **Cross-Cutting NFRs** | G2 passes on numbered FR **and NFR**. Each NFR MUST name `enforced_by` — an `AD-N`, a `DEC-`, or a test name. An NFR nothing enforces is decoration (V5) |
-| **Constraints and Guardrails** | A constraint found at G4 costs a decision that one sentence here would have prevented |
+| Cluster | Section | Why it is required |
+|---|---|---|
+| **Cross-Cutting NFRs** | §6 | G2 passes on numbered FR **and NFR**. Each NFR MUST name `enforced_by` — an `AD-N`, a `DEC-`, or a test name. An NFR nothing enforces is decoration (`nfr-has-enforcer`) |
+| **Constraints and Guardrails** | §7 | A constraint found at G4 costs a decision that one sentence here would have prevented |
 
 Constraints MUST state only the delta beyond `.what/_product-brief/brief.md`, and MUST say "none
 beyond the brief" when there is nothing. An absent section reads as "not checked".
@@ -175,6 +182,42 @@ beyond the brief" when there is nothing. An absent section reads as "not checked
 Prerequisites MUST NOT be written as prose. An initiative blocked on another is a `depends_on`
 between `CAP` entries.
 
+## §1 Why This Initiative is a delta
+
+BMad's default §1 Vision writes the product's vision from scratch, in the same 2-3 paragraph shape as
+the brief's own narrative. On the first PRD a product ever gets, that duplicates `Why` in
+`.what/_product-brief/brief.md` almost sentence for sentence — the same defect Executive Summary and
+Vision had against each other inside the brief before they were merged.
+
+§1 states only what THIS initiative changes, adds, or unlocks beyond what the brief's `Why` already
+says. A product with a single initiative MAY reduce this to one sentence pointing back to the brief.
+The full narrative is never written twice.
+
+## Sections dropped from BMad's default, and where each fact actually lives
+
+Four of BMad's default sections carry no content specific to this PRD, or duplicate a fact this method
+already gives a home. Each is dropped rather than left conditional:
+
+| Dropped section | Where the fact lives instead |
+|---|---|
+| Document Purpose | Nowhere — it explained what a PRD is in general, true of every PRD, so it held no information specific to this one |
+| Glossary | `.control/product-glossary.md`. A term this PRD needs that is not there yet goes through `wdi-question` in the same pass — it is never added to a document-local glossary `wdi-blueprint` will not read at G3 |
+| Non-Goals | The product's own Scope Out (`.what/_product-brief/brief.md`), for what the product never does, and §4.2 Out of Scope for MVP, for what this release defers. A third list restating both is the same fact twice |
+| Open Questions | `.control/questions/`, the moment the question is found — not batched into a section read once at Finalize |
+| Assumptions Index | `.control/questions/assumptions.md`, through `wdi-question`, before G2. The inline `[ASSUMPTION]` tag stays as a marker for the conversation that produced it; it is not also an index entry |
+
+A reader who wants all of these assembled with the PRD's own content reads the generated deliverable —
+see below — rather than a hand-maintained index inside this document.
+
+## The generated deliverable
+
+A complete, self-contained copy for a reader who should not need to open the registry or
+`.control/questions/` lives at `.what-rendered/_prd/<slug>/prd.md` — written by `/wdi-report render prd`,
+which runs `validate.py --generate`. It assembles this PRD's own prose verbatim, the
+Vision from the brief's `Why` plus §1's delta, the `FR`/`NFR` rows from `requirements-<slug>.yaml`, the
+Glossary terms this PRD actually uses, Non-Goals from the brief's Scope Out and §4.2, and the open
+rows from `.control/questions/` that cite one of this PRD's ids. Nobody writes to it by hand.
+
 ## What goes to `addendum.md`
 
 `addendum.md` is **not** a change log — Revision History is. It holds depth that belongs downstream

package/kit/.constitution/method/document/sdd-guide.md

@@ -81,8 +81,8 @@ NOT be written at all.
 | Behaviour | How the three move together, per use case | `06-flows/` |
 
 From `guarded` up, every Boundary object MUST correspond to an `LC` in `.control/registry/components.yaml`;
-at `deep`, Control objects too. Registration is checked **when the wave closes** — V12 — not before a story
-is `ready-for-dev`.
+at `deep`, Control objects too. Registration is checked **when the spec closes** — `lc-registered` — not before a ticket
+is picked up.
 
 Flows **into and out of** each boundary MUST be stated, not just the boundary. A boundary listed without its
 direction of call is a name, not a design.
@@ -201,7 +201,8 @@ Only what this component's `mode` demands, and nothing beyond it:
 - At `deep`: Robustness Analysis done; every `critical` use case mirrored at the technical altitude under
   the same ids; contract specs answering all five lanes; the data dictionary present.
 - Always: unresolved `[NEEDS CONFIRMATION]` filed through `wdi-question`, no unresolved `[MISSING]`, and
-  `wdi-review` run with the lens set `risk_accepted` names.
+  `wdi-review` run with the lens set `risk_accepted` names for a gate-opening review — a re-review after
+  the gate runs the lighter set, and `wdi-review` owns which.
 
-The spine comes first and `bmad-spec` comes last. An SDD written before the spine will be rewritten; a SPEC
+The spine comes first and the spec's contract comes last. An SDD written before the spine will be rewritten; a SPEC
 written before the SDD has nothing to project.