wdi-method 0.5.14 → 0.6.1

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,185 @@
----
-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 | 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.
+---
+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` |
+
+## Seventeen 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-explain-to-me` | "Brief me so I can decide this" — an open question, a defect, a design fork. Reads everything, writes nothing; the decision then goes to `wdi-decision` or `wdi-question` |
+| `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,27 +117,28 @@ 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` |
 | `wdi-report` | `.control/reports/<period>.md` |
 | a script | everything in `.control/generated/`, and the three inventories once code exists |
 
-Four skills write **no file at all**, and that is deliberate: `wdi-reconcile`, `wdi-help`,
+Five skills write **no file at all**, and that is deliberate: `wdi-reconcile`, `wdi-help`, `wdi-explain-to-me`,
 `wdi-report` intent `dispatch`, and `wdi-review` apart from one frontmatter block. What reports MUST NOT
 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.