wdi-method 0.5.13 → 0.6.0

package/kit/.constitution/method/structure-guide.md

@@ -90,7 +90,7 @@ For the codebase map the distinction is exact and MUST NOT be softened:
 container gets a heading.** Reading it both ways makes the rule unsatisfiable: a `built: false` container
 — a database, a web server — MUST be registered, because it runs inside the boundary and carries NFRs,
 and MUST NOT get a heading, because no code of ours lives there. So the check is **heading = exactly the
-`built: true` containers**, and V25 runs it. `c4-l2-containers.md` still owns the list itself.
+`built: true` containers**, and `container-built` runs it. `c4-l2-containers.md` still owns the list itself.
 
 ### Sections that are not units
 
@@ -136,8 +136,8 @@ A folder with no key file MUST still appear in the tree. Folders are complete; f
   measured, only felt.
 - A map MUST be refreshed when a base folder is born or removed, when a key file moves or is
   renamed, when a project or container is added, or when a key file's role changes.
-- **Wave close** carries this hook — it left the story-closing checklist along with four other items,
-  because a structural change is visible at the end of a wave and guessed at the end of a story.
+- **Spec close** carries this hook — it left the ticket-closing checklist along with four other items,
+  because a structural change is visible at the end of a spec and guessed at the end of a ticket.
 - A map MUST NOT be edited by hand. `wdi-init` intent `structure` re-derives it from the actual tree;
   a hand edit records what someone remembers, and memory is exactly what the map exists to replace.
 - A map whose **Verified** commit is no longer an ancestor of `HEAD` SHOULD be treated as stale, and

package/kit/.constitution/method/why/README.md

@@ -1,169 +1,184 @@
----
-status: Reference
----
-
-# The WDI Method — orientation
-
-**Opened when:** you have never seen this method before, or you have and want the shape back in one reading.
-
-This file **explains**. It does not bind — `../document/*-guide.md` does, and where the two disagree the guide
-wins and the disagreement is a defect to report.
-
-Five minutes. Three files in this folder: this one for orientation, `artifact-map.md` for *"where does this
-file go"*, `rationale.md` for *"why is it like this"* — open that one before changing a rule, so you know
-what you are about to break.
-
-## What the method is
-
-Two methods joined. **WDI** owns the flow, the gates, and the artifacts nobody else writes. **BMad** owns
-the writing skills where it has one. Every BMad skill is invoked through a WDI wrapper, never directly: the
-wrapper is what checks position, verifies the result against the guide, and lands the memlog.
-
-The whole thing rests on one sentence:
-
-> Owner time is spent at five points. Between them, the agents work alone.
-
-## Five gates
-
-A gate is named for **what is decided there**, never for the work before it.
-
-| Gate | Decides | How often | Budget |
-|---|---|---|---|
-| **G1 Problem** | What the problem is, whose it is, why it earns work | once | 20' |
-| **G2 Product** | What is built, and how it feels to use | once per PRD | 45' |
-| **G3 Blueprint** | The whole portrait: which use cases, their entities, tables, endpoints, screens, and the invariants binding them | once per **product** | 45' |
-| **G4 Component** | How one Product Component is built, and what the choice costs | once per **component** | 20–30' |
-| **G5 Release** | Whether it is done and proven | once per wave | 10' |
-
-**Only G4 changes shape.** The other four are always the same, whatever the settings — and that is what lets
-the whole system be held in one head.
-
-## Two settings, and they control different things
-
-| Setting | Where | Controls |
-|---|---|---|
-| `mode` | globally in `index.yaml`, per component in `components.yaml` | **Document depth**, and only that |
-| `risk_accepted` | per component | **Review intensity**, and only that |
-
-`mode` takes `catalog` · `outline` · `guarded` · `deep`, and the default is `catalog`. A component at
-`catalog` **skips G4 entirely** — its control moved to G3, where its use cases, tables, endpoints, screens,
-domain model, and C4 were all approved.
-
-`risk_accepted` takes `low` · `medium` · `high`, and its direction reads off the name: `high` means *"I
-accept a lot of risk here"*, so its review is the lightest.
-
-Keeping them apart is what lets one component be **thin on purpose and reviewed the hardest**. Why that
-matters is in `rationale.md`; what each value demands is in `../document/delivery-flow-guide.md`.
-
-## The run, first time through
-
-| # | Step | Run | Gate |
-|---|---|---|---|
-| 0 | Set up | `wdi-init` intent `setup` — registry scaffolded, global `mode` set, existing documents reported, structure maps derived | — |
-| 1 | Discovery and brief | `wdi-problem` | **G1** |
-| 2 | PRD, one per initiative | `wdi-product` intent `prd` | **G2** |
-| 2b | UX — only when the interface is a large part of the promise | `wdi-ux` | with G2 |
-| 3 | Birth the components, set `mode` and `risk_accepted` | `wdi-init` intent `component` | — (tail of G2) |
-| 4 | Blueprint | `wdi-blueprint` intent `catalog`, then `platform` | **G3** |
-| 5 | One component's depth | `wdi-component` — as deep as its `mode`; **skipped at `catalog`** | **G4** |
-| 6 | Build | `wdi-build` — opens the wave, runs `bmad-spec`, ships each story, closes the wave | **G5** |
-
-After step 6 the next component enters at **step 5**, not at the beginning. Steps 0–4 happen once in the
-life of the product.
-
-`SPEC.md` and story files are **not read by humans**. The human review surface stops at the PRD, `.what/`,
-and `.how/`.
-
-## The run, every time after
-
-| Situation | Run |
-|---|---|
-| The next component is being taken on | `wdi-init` intent `mode` or `risk` if either needs changing → `wdi-component` → **G4** → `wdi-build` → **G5** |
-| That component is at `mode: catalog` | straight to `wdi-build`. G4 is skipped |
-| A promise changes where a PRD already exists | `wdi-product` intent `update` — never a second PRD for the same area |
-| A new initiative with a different reader | `wdi-product` intent `prd` → `wdi-init` intent `component` if it births components |
-| A small fix touching no `FR`, `UC`, `AD-N`, or domain model | Fast Path: `bmad-build` directly. It **stops and becomes a wave `S`** the moment an `FR` is touched |
-| A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, **before** any fix is proposed |
-| A planning assumption turned out void | `wdi-decision` — it wraps `bmad-correct-course`, proposes, and changes nothing itself |
-| An estimate or a task list is needed | `wdi-report` intent `estimate` |
-| You do not know where you are | `wdi-help` |
-
-## Fifteen skills
-
-Named for the **gate they serve**, so *"which skill do I run"* is answered by *"which gate am I at"*.
-
-**Moment-bound** — running them outside their point is wrong:
-
-| Skill | Its moment |
-|---|---|
-| `wdi-init` intent `setup` | before G1, once per project |
-| `wdi-problem` | G1 |
-| `wdi-product` | G2 |
-| `wdi-init` intent `component` | tail of G2, and whenever a new PRD births a component |
-| `wdi-blueprint` | G3 |
-| `wdi-component` | G4 |
-| `wdi-build` | G5, one wave per run |
-
-**Anytime** — run the moment the trigger appears, without waiting for a gate:
-
-| Skill | Its trigger |
-|---|---|
-| `wdi-decision` | A decision worth remembering · a void assumption · an accepted decision to carry into documents |
-| `wdi-question` | Something that cannot be decided now |
-| `wdi-log` | A meeting finished, or a non-technical fact now binds |
-| `wdi-help` | "Where am I, what next" |
-| `wdi-reconcile` | Any time. Read-only — it reports, it never edits |
-| `wdi-review` | Over any document, any time |
-| `wdi-systematic-debugging` | A bug, a failed test, a failed build, unexpected behaviour |
-| `wdi-report` | An estimate at the start · progress periodically · before a client update |
-| `wdi-init` intents `mode` · `risk` · `structure` | Any time |
-| `wdi-ux` | Any time after a PRD exists, if UX is being used |
-
-## Who writes what — WDI and BMad
-
-| Artifact | Written by | Wrapped in |
-|---|---|---|
-| Product brief | `bmad-product-brief` | `wdi-problem` |
-| PRD | `bmad-prd` | `wdi-product` |
-| UX | `bmad-ux` | `wdi-ux` |
-| Spine + C4 | `bmad-architecture` | `wdi-blueprint` |
-| **UC catalogue · actors · entities · business rules** | **nothing in BMad** | `wdi-blueprint` writes it itself |
-| **SRS and all of `.what/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
-| **SDD and all of `.how/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
-| `SPEC.md` + stories | `bmad-spec` | `wdi-build` |
-| Code | `bmad-build` · `bmad-build-auto` | `wdi-build` |
-| Retrospective | `bmad-retrospective` | `wdi-build` |
-| Document review | `bmad-review` | `wdi-review` |
-| Course correction | `bmad-correct-course` | `wdi-decision` |
-
-**The bold rows are why this method exists.** BMad stops at the promise and starts again at the mechanism,
-and every behaviour in between had no author. Three consequences stick to those artifacts and are handled
-deliberately: no `doc_standards` fires a review, no memlog is born on its own, and no template enforces
-itself.
-
-## Where things live
-
-| The thing in your hand | Its folder |
-|---|---|
-| How we work — a rule, a guide, a template | `.constitution/` |
-| What currently holds — a decision, a question, a registry, a map | `.control/` |
-| What is promised — the brief, a PRD, a use case, a business rule | `.what/` |
-| How it is built — the spine, C4, an inventory, an SDD, a contract | `.how/` |
-| A skill run's working output | `_bmad-output/` |
-| Scratch that empties when the task closes | `.work/` |
-| The application | `src/` · `web/` |
-
-The test that settles anything ambiguous: **is this file still correct after its wave has passed?** Yes →
-the corpus. No → `_bmad-output/`. In doubt, `../document/corpus-guide.md`.
-
-## Model choice
-
-| Point | Model |
-|---|---|
-| Decisions — proposing a slicing, wording a `DEC-`, preparing a gate | `opus@high` |
-| Writing, derivation, a review-fix pass | `sonnet@high` |
-| Code review panel | Two different CLI families, and never the family that wrote the code |
-
-In a derivation pass, quality comes from the input rather than the model. Running a "find the gap" lens with
-the most careful model produces the most gaps, and each one becomes an open question — a cost nobody sees
-until the question list has stopped being readable.
+---
+status: Reference
+---
+
+# The WDI Method — orientation
+
+**Opened when:** you have never seen this method before, or you have and want the shape back in one reading.
+
+This file **explains**. It does not bind — `../document/*-guide.md` does, and where the two disagree the guide
+wins and the disagreement is a defect to report.
+
+Five minutes. Four more files sit beside this one: `artifact-map.md` for *"where does this file go"*,
+`mode-risk-map.md` for *"I set a `mode` and a `risk_accepted` — what changes?"*, `portability.md` for which
+files are the method's and which are the product's, and `rationale.md` for *"why is it like this"* — open
+that last one before changing a rule, so you know what you are about to break.
+
+## What the method is
+
+Two methods joined. **WDI** owns the flow, the gates, and the artifacts nobody else writes. **BMad** owns
+the writing skills where it has one. Every BMad skill is invoked through a WDI wrapper, never directly: the
+wrapper is what checks position, verifies the result against the guide, and lands the memlog.
+
+The whole thing rests on one sentence:
+
+> Owner time is spent at five points. Between them, the agents work alone.
+
+## Five gates
+
+A gate is named for **what is decided there**, never for the work before it.
+
+| Gate | Decides | How often | Budget |
+|---|---|---|---|
+| **G1 Problem** | What the problem is, whose it is, why it earns work | once | 20' |
+| **G2 Product** | What is built, and how it feels to use | once per PRD | 45' |
+| **G3 Blueprint** | The whole portrait: which use cases, their entities, tables, endpoints, screens, and the invariants binding them | once per **product** | 45' |
+| **G4 Component** | How one Product Component is built, and what the choice costs | once per **component** | 20–30' |
+| **G5 Release** | Whether it is done and proven | once per spec | 10' |
+
+**Only G4 can disappear.** At `mode: catalog` its session does not happen at all; the other four always run,
+and what each decides never changes. What `mode` does shorten everywhere is the **checklist**: at `catalog`
+only the ★ questions are required, at G1 and G5 as much as at G4. Sessions fixed, checklist elastic — that is
+what lets the whole system be held in one head.
+
+## Two settings, and they control different things
+
+| Setting | Where | Controls |
+|---|---|---|
+| `mode` | globally in `index.yaml`, per component in `components.yaml` | **Document depth**, and only that |
+| `risk_accepted` | per component | **Review intensity**, and only that |
+
+`mode` takes `catalog` · `outline` · `guarded` · `deep`, and the default is `catalog`. A component at
+`catalog` **skips G4 entirely** — its control moved to G3, where its use cases, tables, endpoints, screens,
+domain model, and C4 were all approved.
+
+`risk_accepted` takes `low` · `medium` · `high`, and its direction reads off the name: `high` means *"I
+accept a lot of risk here"*, so its review is the lightest.
+
+Keeping them apart is what lets one component be **thin on purpose and reviewed the hardest**. Why that
+matters is in `rationale.md`; what each value demands is in `../document/delivery-flow-guide.md`.
+
+## The run, first time through
+
+| # | Step | Run | Gate |
+|---|---|---|---|
+| 0 | Set up | `wdi-init` intent `setup` — registry scaffolded, global `mode` set, existing documents reported, structure maps derived | — |
+| 1 | Discovery and brief | `wdi-problem` | **G1** |
+| 2 | PRD, one per initiative | `wdi-product` intent `prd` | **G2** |
+| 2b | UX — only when the interface is a large part of the promise. **Before G2**, because G2 reads its `EXPERIENCE.md` | `wdi-ux` | with **G2** |
+| 3 | Birth the components, set `mode` and `risk_accepted`, and land the waiting UX halves | `wdi-init` intent `component` | — (tail of G2) |
+| 4 | Blueprint | `wdi-blueprint` intent `catalog`, then `platform` | **G3** |
+| 5 | One component's depth | `wdi-component` — as deep as its `mode`; **skipped at `catalog`** | **G4** |
+| 6 | Pick the work | `wdi-report` intent `estimate` — candidate tasks derived from `CAP`/`FR`; one row becomes one spec | — |
+| 7 | Build | `wdi-build` — opens the spec, has the owner run `to-spec` and `to-tickets`, ships each ticket, closes the spec | **G5** |
+
+After step 7 the next component enters at **step 5** (at `mode: catalog`, at step 6), not at the
+beginning. Steps 0–4 happen once in the life of the product.
+
+**What the human reads is one rendered page per gate**: `.what-rendered/_product-brief/brief.md` at G1,
+`.what-rendered/_prd/<slug>/prd.md` at G2, `.how-rendered/blueprint.md` at G3,
+`.how-rendered/<pc>/SDD-<pc>.md` at G4. The working documents under `.what/` and `.how/` point at the
+registry instead of repeating it and are the AI's. `SPEC.md` and ticket files are **not read by humans**.
+
+`to-spec`, `to-tickets`, and `implement` come from [mattpocock/skills](https://github.com/mattpocock/skills):
+in Claude Code `/plugin install mattpocock-skills`; for Codex, Cursor, and other agents
+`npx skills@latest add mattpocock/skills` (copies them into the repo — take `setup-matt-pocock-skills`
+too). Then `/setup-matt-pocock-skills` once, to name the tracker. G1–G4 run without them; `wdi-build`
+and the Fast Path do not.
+
+## The run, every time after
+
+| Situation | Run |
+|---|---|
+| The next component is being taken on | `wdi-init` intent `mode` or `risk` if either needs changing → `wdi-component` → **G4** → `wdi-build` → **G5** |
+| That component is at `mode: catalog` | straight to `wdi-build`. G4 is skipped |
+| A promise changes where a PRD already exists | `wdi-product` intent `update` — never a second PRD for the same area |
+| A new initiative with a different reader | `wdi-product` intent `prd` → `wdi-init` intent `component` if it births components |
+| A small fix touching no `FR`, `UC`, `AD-N`, or domain model | Fast Path: the owner runs `/implement` directly, with no wrapper. It **stops and becomes a spec `S`** the moment an `FR` is touched |
+| A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, **before** any fix is proposed |
+| A planning assumption turned out void | `wdi-decision` — it wraps `bmad-correct-course`, proposes, and changes nothing itself |
+| An estimate or a task list is needed | `wdi-report` intent `estimate` |
+| `wdi-method update` printed an `upgrade` line | `wdi-upgrade`, before any other skill — it moves content into the new shape, never invents it, one commit |
+| You do not know where you are | `wdi-help` |
+
+## Sixteen skills
+
+Named for the **gate they serve**, so *"which skill do I run"* is answered by *"which gate am I at"*.
+
+**Moment-bound** — running them outside their point is wrong:
+
+| Skill | Its moment |
+|---|---|
+| `wdi-init` intent `setup` | before G1, once per project |
+| `wdi-problem` | G1 |
+| `wdi-product` | G2 |
+| `wdi-init` intent `component` | tail of G2, and whenever a new PRD births a component |
+| `wdi-blueprint` | G3 |
+| `wdi-component` | G4 |
+| `wdi-build` | G5, one spec per run |
+
+**Anytime** — run the moment the trigger appears, without waiting for a gate:
+
+| Skill | Its trigger |
+|---|---|
+| `wdi-decision` | A decision worth remembering · a void assumption · an accepted decision to carry into documents |
+| `wdi-question` | Something that cannot be decided now |
+| `wdi-log` | A meeting finished, or a non-technical fact now binds |
+| `wdi-help` | "Where am I, what next" |
+| `wdi-upgrade` | `wdi-method update` just moved the method version, and the summary listed content still in the old shape. Moves it, never invents it; one commit |
+| `wdi-reconcile` | Any time. Read-only — it reports, it never edits |
+| `wdi-review` | Over any document, any time |
+| `wdi-systematic-debugging` | A bug, a failed test, a failed build, unexpected behaviour |
+| `wdi-report` | An estimate at the start · progress periodically · before a client update |
+| `wdi-init` intents `mode` · `risk` · `structure` | Any time |
+| `wdi-ux` | Any time after a PRD exists, if UX is being used |
+
+## Who writes what — WDI and BMad
+
+| Artifact | Written by | Wrapped in |
+|---|---|---|
+| Product brief | `bmad-product-brief` | `wdi-problem` |
+| PRD | `bmad-prd` | `wdi-product` |
+| UX | `bmad-ux` | `wdi-ux` |
+| Spine + C4 | `bmad-architecture` | `wdi-blueprint` |
+| **UC catalogue · actors · entities · business rules** | **nothing in BMad** | `wdi-blueprint` writes it itself |
+| **SRS and all of `.what/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
+| **SDD and all of `.how/<pc>/`** | **nothing in BMad** | `wdi-component` writes it itself |
+| `SPEC.md` + tickets | `to-spec` · `to-tickets` — **not BMad's**, and the owner runs them | `wdi-build` |
+| Code | `implement`, with `tdd` inside it — same | `wdi-build` |
+| Code review | `code-review` — same | `wdi-build` |
+| Document review | `bmad-review` | `wdi-review` |
+| Course correction | `bmad-correct-course` | `wdi-decision` |
+
+**The bold rows are why this method exists.** BMad stops at the promise and starts again at the mechanism,
+and every behaviour in between had no author. Three consequences stick to those artifacts and are handled
+deliberately: no `doc_standards` fires a review, no memlog is born on its own, and no template enforces
+itself.
+
+## Where things live
+
+| The thing in your hand | Its folder |
+|---|---|
+| How we work — a rule, a guide, a template | `.constitution/` |
+| What currently holds — a decision, a question, a registry, a map | `.control/` |
+| What is promised — the brief, a PRD, a use case, a business rule | `.what/` |
+| How it is built — the spine, C4, an inventory, an SDD, a contract | `.how/` |
+| The complete page a human reads at a gate — regenerated, never edited | `.what-rendered/` · `.how-rendered/` |
+| A skill run's working output | `_bmad-output/` |
+| Scratch that empties when the task closes | `.work/` |
+| The application | `src/` · `web/` |
+
+The test that settles anything ambiguous: **is this file still correct after its spec has passed?** Yes →
+the corpus. No → `_bmad-output/`. In doubt, `../document/corpus-guide.md`.
+
+## Model choice
+
+| Point | Model |
+|---|---|
+| Decisions — proposing a slicing, wording a `DEC-`, preparing a gate | `opus@high` |
+| Writing, derivation, a review-fix pass | `sonnet@high` |
+| Code review panel | Reviewers dispatched separately from the builder — the local Agent Rules govern CLI/model pairing |
+
+In a derivation pass, quality comes from the input rather than the model. Running a "find the gap" lens with
+the most careful model produces the most gaps, and each one becomes an open question — a cost nobody sees
+until the question list has stopped being readable.

package/kit/.constitution/method/why/artifact-map.md

@@ -11,7 +11,7 @@ wins and the disagreement is a defect to report.
 
 It answers three questions and nothing else: which files exist at each `mode`, who owns each one, and how
 the units of work line up. The **rules** about depth live in `../document/delivery-flow-guide.md`; what is
-here is the map.
+here is the map. What `mode` and `risk_accepted` do **together**, cell by cell, is in `mode-risk-map.md`.
 
 ## The one thing to read first
 
@@ -91,14 +91,15 @@ Repealed: `_platform/architecture/` (one file does not earn a folder) and `<pc>/
 
 | File | Holds | Present at |
 |---|---|---|
-| `.control/registry/requirements.yaml` | `BG` · `CAP` · `FR` · `NFR` · `UJ` | every mode |
+| `.control/registry/goals.yaml` | `BG` | every mode |
+| `.control/registry/requirements-<slug>.yaml` | `CAP` · `FR` · `NFR` · `UJ`, one file per PRD initiative | every mode |
 | `.control/registry/usecases.yaml` | `UC-N` with `critical` and the `FR` it satisfies | every mode |
 | `.control/registry/components.yaml` → `product_components` | Component · `mode` · `risk_accepted` · `risk_note` · `owns` · `g4_passed` | every mode |
 | `.control/registry/components.yaml` → `containers` | The containers from C4 L2 | every mode |
 | `.control/registry/components.yaml` → `platform_owns` | Entities no Product Component's promise explains. `_platform` is not a component and has no `mode` | every mode |
 | `.control/registry/components.yaml` → `logical_components` | `LC` | boundary from `guarded`; boundary + control at `deep` |
-| `.control/registry/decisions.yaml` · `waves.yaml` · `defects.yaml` · `risks.yaml` · `index.yaml` | Decisions · work · defects · risks · the global `mode` and gate map | every mode |
-| `.control/generated/blueprint.md` | **The one-page roll-up reviewed at G3** | every mode |
+| `.control/registry/decisions.yaml` · `specs.yaml` · `defects.yaml` · `risks.yaml` · `index.yaml` | Decisions · work · defects · risks · the global `mode` and gate map | every mode |
+| `.how-rendered/blueprint.md` | **The one-page roll-up reviewed at G3** | every mode |
 | `.control/generated/decisions.md` | The flat index of every `DEC-` | every mode |
 | `.control/generated/estimate.md` | The candidate task table | every mode |
 | `.control/generated/rtm` · `status` · `dag` · `components` · `risks` | Traceability and progress | every mode |
@@ -116,7 +117,7 @@ someone else performs. `../document/corpus-guide.md` holds the binding version o
 | `wdi-blueprint` | `.what/<pc>/` § Actor Register + § UC Catalogue + `03-domain/domain-model.md` · `.what/business-rules.md` · `.control/product-glossary.md` · all of `.how/_platform/` except `design-system.md` |
 | `wdi-component` | `.what/<pc>/` slots `02`–`05` · `.how/<pc>/` except `01-ux/` |
 | `wdi-ux` | `EXPERIENCE.md` · `.how/<pc>/01-ux/` · `.how/_platform/design-system.md` |
-| `wdi-build` | `waves.yaml` · `_bmad-output/specs/` · `src/` · `web/` · `.control/reports/RTR-<wave>.md` |
+| `wdi-build` | `specs.yaml` · `_bmad-output/specs/` · `src/` · `web/` |
 | `wdi-decision` | `.control/decisions/` · `decisions.yaml`, and at apply time whatever `touches` names — through each file's owner |
 | `wdi-question` | `.control/questions/` |
 | `wdi-log` | `.control/meetings/` · `.control/project-non-technical-log.md` |
@@ -129,14 +130,15 @@ also change things — otherwise there is nothing left to check with.
 
 ## How the units of work line up
 
-`FR` is a **promise** and permanent; a wave is a **unit of work** and temporary; `SPEC.md` is the machine
-contract for one wave; a story is one piece one builder takes to a green PR.
+`FR` is a **promise** and permanent; a spec is a **unit of work** and temporary; `SPEC.md` is the machine
+contract for one spec — written from size `M` up, and at `S` the tickets are the contract; a ticket is one
+vertical slice one builder takes to a green PR.
 
-One wave = one `SPEC` = one tracker Task, and Epic = Product Component, Sub-task = story. **`FR` is not a
-Task** — it travels as a label, because one `FR` can be delivered by stories in two waves and one story can
-satisfy part of two `FR`.
+One spec = one parent issue, and 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. **`FR` is not an issue** — it travels as a label,
+because one `FR` can be delivered by tickets in two specs and one ticket can satisfy part of two `FR`.
 
-The binding version of all of this, including why a wave MAY cross components and what has to be true
+The binding version of all of this, including why a spec MAY cross components and what has to be true
 first, is in `../document/delivery-flow-guide.md`. It is not restated here.
 
 ## What needs no template, and why
@@ -148,8 +150,8 @@ Stated so the next completeness audit does not report it again:
 | `.control/generated/*` | Script output. Its shape is code, not a template |
 | `.control/reports/<period>.md` | Rendered by `timeline.py` |
 | `.control/project-non-technical-log.md` | States its own entry shape in its own header, and there is exactly one such file |
-| `SPEC.md` · story files | They belong to `bmad-spec`. WDI does not write their shape, and MUST NOT |
+| `SPEC.md` · ticket files | Their shape belongs to `to-spec` and `to-tickets`. WDI owns where they land, not how they read |
 | Registry `*.yaml` | Their shape is the comment block at the head of each file, plus the validator |
 
-Everything else in this map has a template in `../document/templates/` — 27 of them, and every row above is
+Everything else in this map has a template in `../document/templates/` — 26 of them, and every row above is
 covered by one.

package/kit/.constitution/method/why/mode-risk-map.md

@@ -0,0 +1,140 @@
+---
+status: Reference
+---
+
+# Mode × Risk Map — what the two settings do together
+
+**Opened when:** a `mode` and a `risk_accepted` have been picked for a component and someone asks
+*"so what actually changes?"* — or the same question before picking.
+
+This file **explains**. It does not bind — `../document/*-guide.md` does, and where the two disagree the
+guide wins and the disagreement is a defect to report.
+
+`../document/delivery-flow-guide.md` defines each field. `artifact-map.md` lists which files exist at each
+`mode`. Neither shows the two fields **side by side**, and that is the only gap this file fills.
+
+## This is not a decision matrix
+
+All twelve combinations are legal, and eleven of them need no justification at all. Reading a column MUST
+NOT be used to derive `mode` from `risk_accepted`, or the reverse: the whole reason they are two fields is
+that documents and reviews are two different mitigations, and a component MAY be **thin on purpose and
+reviewed the hardest**. `rationale.md` holds why.
+
+What the table below gives is **consequence**, not recommendation. Two things in it are not free, and both
+are named in the guide, not here: `risk_accepted: high` on a component whose `risk_note` names money,
+personal data, an irreversible action, a contractual promise, or an un-rollbackable integration needs a
+named acceptance in `risk_accepted_by` (`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`, which is the one cell
+the method assigns rather than offers.
+
+## Axis 1 — what moves when only `mode` moves
+
+Cumulative; each row contains the one above. Full per-file manifest in `artifact-map.md`.
+
+| `mode` | Beyond the blueprint, per component | G4 | `critical` |
+|---|---|---|---|
+| `catalog` | nothing — zero extra files. The SDD stays a skeleton | **skipped entirely** | decides nothing |
+| `outline` | `Decision Summary` · the `LC` list · full flow for at most 3 use cases · local business rules | 20' | decides nothing |
+| `guarded` | + `Failure Behaviour` for every boundary · `Inherited Constraints` · third-party integration documents · boundary `LC` registered | 20' | decides nothing |
+| `deep` | + ABCE robustness analysis · contract spec per endpoint · data dictionary · flow diagrams · state machines · branch scenarios | 30' | **every `critical` UC gets a full flow** |
+
+Untouched at every `mode`: the use case list, the API list, the table list, the screen list, the domain
+model, the actor list, the spine, C4 L1–L3, and cross-component business rules. All nine are blueprint
+content, born at G3, which the depth knob does not reach.
+
+## Axis 2 — what moves when only `risk_accepted` moves
+
+| `risk_accepted` | Lenses on the documents | On the code | `review-trace` trace on the component's docs |
+|---|---|---|---|
+| `low` | structure · prose · **edge-case-hunter** | a **two-reviewer panel is required** | demanded |
+| `medium` | structure · prose · **edge-case-hunter** | — | demanded |
+| `high` | structure · prose | — | not demanded — the risk is already accepted on the record |
+
+**The contract sits outside that last column entirely**, and it is the one artifact this field never
+reaches: it always carries `edge-case-hunter`, and `review-trace` always demands `spec_reviewed` on every spec that
+carries tickets — `high` included. A spec is not a component, so `risk_accepted` has no say over it. It is
+what a builder works from, and a branch missed there surfaces as a bug at G5.
+
+One trace covers the whole spec, never one per ticket. Where `SPEC.md` exists the trace covers it; at size
+`S` there is none, and the trace covers the **ticket set as one artifact**.
+
+## The twelve cells
+
+`g4` = the G4 session · `panel` = the two-reviewer code panel · `review-trace` targets assume the file is born.
+
+| `mode` + `risk_accepted` | Owner time at G4 | Document review | Code | Component trace on | Also |
+|---|---|---|---|---|---|
+| `catalog` + `low` | none — skipped | structure · prose · edge-case-hunter | **panel** | `SRS` only | The cell the split exists for: thin on purpose, reviewed hardest |
+| `catalog` + `medium` | none — skipped | structure · prose · edge-case-hunter | — | `SRS` only | The cheapest cell that still hunts edge cases |
+| `catalog` + `high` | none — skipped | structure · prose | — | nothing | Nothing in the flow asks what is being staked — only `wdi-init`'s disclosure and `high-risk-named` do |
+| `outline` + `low` | 20' | structure · prose · edge-case-hunter | **panel** | `SRS` · `SDD` after G4 | Flows for 3 use cases, checked hard |
+| `outline` + `medium` | 20' | structure · prose · edge-case-hunter | — | `SRS` · `SDD` after G4 | — |
+| `outline` + `high` | 20' | structure · prose | — | nothing | Flows exist; no lens looks for the branch they miss |
+| `guarded` + `low` | 20' | structure · prose · edge-case-hunter | **panel** | `SRS` · `SDD` after G4 | Boundary answers written **and** hunted. The heaviest cell short of `deep` |
+| `guarded` + `medium` | 20' | structure · prose · edge-case-hunter | — | `SRS` · `SDD` after G4 | — |
+| `guarded` + `high` | 20' | structure · prose | — | nothing | Failure behaviour is written and taken at its word |
+| `deep` + `low` | 30' | structure · prose · edge-case-hunter | **panel** | `SRS` · `SDD` after G4 | The floor an outside deliverable is put at. Not a preference there |
+| `deep` + `medium` | 30' | structure · prose · edge-case-hunter | — | `SRS` · `SDD` after G4 | — |
+| `deep` + `high` | 30' | structure · prose | — | nothing | Depth bought, scrutiny declined. Legal, and worth saying out loud once |
+
+**The trace column is scoped to a component's own documents.** The spec's own trace is left out of it
+because it is demanded in **every** cell: `review-trace` asks for `spec_reviewed` carrying `edge-case-hunter` on every
+spec with tickets, whatever `risk_accepted` says. Reading a `nothing` in that column as *"no trace is
+demanded anywhere in this cell"* is the one misreading it invites, and it is wrong.
+
+## Before the components exist — G1 and G2
+
+The question this section exists to answer: *"at G1 and G2, is every combination treated the same?"*
+
+For `risk_accepted`, yes — and not as a policy choice. **The field has no value yet.** It is born per
+component when `wdi-init` intent `component` runs at the **tail of G2**, so nothing before that point can read
+it. One consequence worth knowing: the brief and the PRD are artifacts with no component, so their review is
+`structure · prose` whatever any component is later set to, and no `reviewed:` trace is written on them at all.
+
+For `mode`, almost — and the exception is real:
+
+| At G1 and G2 | Identical at every setting? |
+|---|---|
+| What the gate decides, its budget (20' · 45'), how often it runs | **yes** |
+| The artifacts: `brief.md` · `_product-brief/addendum.md` · `prd.md` · `_prd/<initiative>/addendum.md` | **yes** — `always` at all four modes |
+| Checklist length | **no** — at `catalog` G1 asks 2 of 7 and G2 asks 3 of 7 |
+
+Only the **global** `mode` can be in play there; the per-component one does not exist yet. And among the G2
+questions that stop being required at `catalog` is *"which `FR` touch money, personal data, or the client's
+reputation?"* — which does not open a hole: `wdi-init` intents `mode` and `risk` MUST read the `FR` falling to
+the component and name what is touched before proposing any value. The disclosure moves, it does not vanish.
+
+## Where the two fields actually meet
+
+Four points, and they are the whole reason this file exists. Everywhere else the fields are independent
+and each row above is just its axis restated.
+
+1. **The `SDD` review trace is the one demand that reads both fields.** `review-trace` demands it only when
+   `risk_accepted` is `low` or `medium` **and** `mode` is above `catalog` **and** `g4_passed` is set. At
+   `catalog` the SDD skeleton is its **finished** form, and a trace on thirteen lines of template comments
+   is theater.
+2. **The `SRS` trace reads only risk.** It is demanded at every `mode`, `catalog` included, because the
+   SRS carries the Actor Register and the UC Catalogue — G3 content, born whatever the depth.
+3. **The spine's trace is product-wide.** One component at `low` or `medium` anywhere puts
+   `ARCHITECTURE-SPINE.md` under `review-trace`, however the other components are set.
+4. **`catalog` removes the gate where risk is spoken about.** G4's first ★ question is *"what is being
+   staked in this component — and does `risk_accepted` say so out loud?"* At `catalog` that session does
+   not happen, so the disclosure at `wdi-init` intent `risk` and the `risk_note` it writes are the only
+   place the answer is recorded. That is a consequence, not an argument for raising `mode`: the same
+   answer costs one line in `risk_note` and does not need a document to hold it.
+
+Two more mechanics, neither of which reads `risk_accepted`:
+
+- **`spec-after-g4`** — from `outline` up, a spec MUST NOT touch a component whose `g4_passed` is unset. At `catalog`
+  the check passes by design, because there is no G4 to pass.
+- **G4's second ★ question** — *"which boundary still has no answer for the other side being slow, absent,
+  or lying"* — is asked from `guarded` up. It is the question `guarded` exists to buy.
+
+## Changing a cell later
+
+| Move | Costs | Note |
+|---|---|---|
+| Raising or lowering `mode` | nothing. No justification | Lowering **deletes nothing** — a written file stops being required, and that is all |
+| Raising `mode` on a component whose code already runs | the evidence labels in `sdd-guide.md` | What comes out is an **as-built record**, not a design |
+| Lowering `risk_accepted` toward `low` | a review that now has to actually run | A stale trace MUST be re-earned, never re-dated — except for a wording-only change, which `wdi-review` lets you re-stamp |
+| Raising `risk_accepted` to `high` on a sensitive component | a person and a date in `risk_accepted_by` | `high-risk-named` checks somebody is named, and it discloses rather than vetoes |