wdi-method 0.5.14 → 0.6.1

package/kit/skills/wdi-decision/SKILL.md

@@ -1,183 +1,187 @@
----
-name: wdi-decision
-description: Use when a decision worth remembering has been made, when one has to be carried into the documents it governs, or when a planning assumption turns out to be void. Three intents — open, accept, apply. Wraps bmad-correct-course. Produces a globally numbered DEC-.
----
-
-# WDI Decision
-
-Free of stage and free of role: a decision MAY be made at any point by anyone. What is fixed is where its
-output lives — `.control/decisions/DEC-NNN-<slug>.md`, numbered globally from `decisions.yaml`.
-
-Three intents, because deciding, ratifying, and rewriting the documents are three different acts and merging
-them means documents change before anyone approved the change.
-
-| Intent | Does | Who |
-|---|---|---|
-| `open` | Writes a `DEC-` at `status: draft`. Also the entry point for a void planning assumption, which is where `bmad-correct-course` is dispatched | anyone |
-| `accept` | Raises `draft` → `accepted` | **the Product Owner only** |
-| `apply` | Dispatches the owner of every document the decision reaches, checks what came back, fills `touches`, raises `applied` | anyone |
-
-Applying is what **freezes** a decision, not accepting. `decision-guide.md` owns the full ladder and this skill
-MUST NOT restate it.
-
-## The one test, before anything is written
-
-> **If someone asks in three months why it is like this, is the answer readable from the code?**
-
-Yes → it MUST NOT be recorded. No → record it.
-
-**Recording is not mandatory**, and a decision nobody recorded is normal rather than negligence. You MUST NOT
-log it as debt or backfill it later from memory. One case stays mandatory: a decision that **contradicts or
-changes an `AD-N`**.
-
-The old name ADR forced the wrong question — *"is this architectural?"* — and that question threw away exactly
-the decisions most worth keeping, the ones that sound small.
-
-## Intent `open`
-
-### Inputs
-
-Any of these, alone or together: minutes in `.control/meetings/`, an answered question in
-`.control/questions/`, a review or debugging finding, a memlog in `.control/memlog/`, a `wdi-reconcile` conflict.
-
-The memlog is the richest source and the most often forgotten. It is the record of *why* — read it before
-writing the Why section rather than reconstructing the reasoning from the outcome.
-
-### What it writes
-
-Three sections, always: **Decision** (one sentence, present tense, quotable) · **Why** · **Cost** (what becomes
-harder). Alternatives, a reversal trigger, and Trace are required only when the decision reaches a Product
-Component whose `risk_accepted` is `low`; elsewhere an empty one MUST be dropped rather than left as a heading.
-
-Frontmatter carries `touches: []` — empty until applied — and `type:` when it is useful. There is no `layer:`
-and no `component:`; both were classifications demanded before anything was known.
-
-A `DEC-` MUST NOT hold an open question. Those go to `wdi-question`.
-
-### A void planning assumption
-
-This is the same intent, with one extra step in front. The trigger is one thing: **a planning assumption turned
-out to be void.** It usually surfaces while building, but its impact reaches back into G2, G3, and G4.
-
-Three things it is **not**:
-
-| Ask | Route |
-|---|---|
-| Something is broken and the cause is unknown | `wdi-systematic-debugging` **first**. A correction built on a guessed cause corrects the wrong thing |
-| A decision exists and documents must follow | intent `apply`. There is no plan to re-cut |
-| Scope grows without invalidating anything | `wdi-product` intent `update`, then the normal flow |
-
-State the void assumption in **one line** before dispatching. A correction whose trigger cannot be stated in one
-line is a re-plan, and it belongs upstream.
-
-Then dispatch `bmad-correct-course`. Do not restate the rules to it — they arrive through `persistent_facts` in
-`_bmad/custom/bmad-correct-course.toml`, including the ban on direct edits. Name the corpus files in scope
-explicitly; it globs its own defaults, which this project does not use.
-
-**Its impact analysis is incomplete by construction** — it knows a PRD, epics, and stories, and it cannot see
-`.what/<pc>/`, `.how/`, `.control/`, or `.constitution/`. Every one of these MUST be checked here:
-
-| Layer | What to look for |
-|---|---|
-| `.what/_prd/` | The `FR`/`NFR` that no longer holds, and every one depending on it |
-| `.what/<pc>/` | Use cases realising those `FR`, business rules, state lifecycles that lose a state |
-| `.how/_platform/` | An `AD-N` the correction breaks, a container the C4 set no longer describes, an inventory row with nothing behind it |
-| `.how/<pc>/` | Contracts, flows, and Failure Behaviour written against the old promise |
-| `SPEC.md` | What the wave projected — a SPEC MUST NOT be edited to match; it is re-derived |
-| `waves.yaml` | The wave's size, and whether the correction changes it |
-| Story files | Which stories are `in-progress`, and which are not yet started |
-
-The result is a `DEC-` of **`type: course-correction`**. The `SCP-` code is retired — a course correction is a
-decision, and no second code names the same thing.
-
-A correction cancelling more than **30%** of a wave's stories MUST NOT be handled as a patch. Say so, and let
-the wave be re-cut through `wdi-build`.
-
-A story already `in-progress` MUST NOT have its contract changed. Report it; stopping it and returning it to
-`ready-for-dev` is the coordinator's act.
-
-## Intent `accept`
-
-Only the Product Owner MAY raise a `DEC-` to `accepted`. **An agent MUST NOT accept its own.** When work is
-blocked waiting on one, the block is reported, never resolved by self-approval.
-
-An `accepted` `DEC-` that is still unapplied MAY be corrected in place, with the correction recorded in the
-memlog. Nothing has been built on it, so there is no divergent record to preserve.
-
-## Intent `apply`
-
-**You apply nothing yourself.** Every artifact has an owner, and the owner writes it. A hand-edit here produces
-a change with no author, no input trail, and nothing that verifies it.
-
-Exactly one `DEC-`, at `status: accepted`. You MUST NOT apply one in any other status.
-
-### Step 1 — List the targets before touching one
-
-Name every document the decision reaches, and the skill that owns each, **before** anything is dispatched. A
-list assembled while editing is a list that grows to fit what was already done.
-
-| Target | Dispatch |
-|---|---|
-| `.what/_product-brief/` | `wdi-problem` |
-| `.what/_prd/<initiative>/` | `wdi-product` intent `update` |
-| `.what/<pc>/` § Actor Register · § UC Catalogue · `03-domain/domain-model.md` | `wdi-blueprint` intent `catalog` |
-| `.what/business-rules.md` · `.control/product-glossary.md` | `wdi-blueprint` intent `catalog` |
-| `.how/_platform/` — spine, C4, `cross-cutting.md`, the three inventories | `wdi-blueprint` intent `platform` |
-| `.what/<pc>/` slots `02`–`05` — full flows, local rules, lifecycles, scenarios | `wdi-component` intent `behaviour` |
-| `.how/<pc>/` minus `01-ux/` | `wdi-component` intent `design` |
-| `EXPERIENCE.md` · `.how/<pc>/01-ux/` · `design-system.md` | `wdi-ux` |
-| `components.yaml` — a PC born or changed · `mode` · `risk_accepted` · the two structure maps | `wdi-init`, by intent |
-| `waves.yaml`, or anything inside an open wave | `wdi-build` |
-| `.control/questions/` | `wdi-question` |
-| `.control/project-non-technical-log.md` · `.control/meetings/` | `wdi-log` |
-
-A target with **no row here** MUST be reported as a gap in the method, not given a plausible owner.
-
-Apply in layer order — **`.what/` before `.how/`** — so the lower layer is written against the promise it is
-supposed to serve, not against the one it is about to replace. The retired `layer:` field used to declare that
-order in advance; it is now simply the order.
-
-### Step 2 — Dispatch, one owner at a time
-
-Hand each owner the `DEC-` id and the exact change its layer has to carry. You MUST NOT restate the decision in
-your own words; **quote it.** A paraphrase drifts, and the drift is invisible because both texts read reasonably.
-
-Each owner keeps its own rules — its review, its memlog, its registry entry. You MUST NOT ask an owner to skip
-any of them because the change is small.
-
-### Step 3 — Name the gates
-
-Run the change-control matrix in `delivery-flow-guide.md` and **report** which gates it names. You MUST NOT
-reopen a gate yourself, and you MUST NOT treat a green application as a gate that has already passed.
-
-### Step 4 — Close the trail
-
-- Fill `touches:` with the files that were **actually** changed, in the `DEC-` and in `decisions.yaml`. Raise
-  `status: applied`. **From that point the file MUST NOT be edited** — not the Decision, not the Cost, not a
-  typo in the Why. Documents cite it now.
-- V8 checks that an `applied` decision names a non-empty `touches`.
-- Regenerate `.control/generated/decisions.md` with `validate.py --generate`. That table is how a decision is
-  found now; searching the memlog for decisions is retired, and the memlog is a run log again.
-- Report what changed, and what the decision implied but was **not** changed.
-
-## Rules
-
-- You MUST NOT widen scope beyond the decision. A neighbouring paragraph that now looks wrong is a finding to
-  report, not a change to make.
-- You MUST NOT introduce a new domain noun. If the decision requires one, it goes through `wdi-blueprint` first.
-- If applying would contradict another `applied` decision, you MUST stop and report the conflict. Two applied
-  decisions that disagree is work for intent `open`, not something to resolve by preferring the newer one.
-- If the decision is unapplicable as written — the document it names no longer exists, or the change was already
-  made differently — you MUST report that instead of improvising.
-- You MUST NOT apply into a wave that is already closed.
-- `AD-N` is a different thing: a living rule with Binds · Prevents · Rule, edited in place. You MUST NOT convert
-  one into the other.
-- A decision that emerged from a failed third fix attempt MUST say so in Why. That is the signal
-  `wdi-systematic-debugging` exists to raise, and burying it wastes the finding.
-
-## Output
-
-Intent taken. For `open`: the decision in one sentence, its three required sections, and — for a correction —
-the void assumption in one line plus what the scan found that `bmad-correct-course` could not see. For `apply`:
-every target with its owner, what each owner changed, what was reported instead of changed and why, the gates the
-matrix names, and whether `touches` and `applied` were filled.
+---
+name: wdi-decision
+description: Use when a decision worth remembering has been made, when one has to be carried into the documents it governs, or when a planning assumption turns out to be void. Three intents — open, accept, apply. Wraps bmad-correct-course. Produces a globally numbered DEC-.
+---
+
+# WDI Decision
+
+Free of stage and free of role: a decision MAY be made at any point by anyone. What is fixed is where its
+output lives — `.control/decisions/DEC-NNN-<slug>.md`, numbered globally from `decisions.yaml`.
+
+Three intents, because deciding, ratifying, and rewriting the documents are three different acts and merging
+them means documents change before anyone approved the change.
+
+| Intent | Does | Who |
+|---|---|---|
+| `open` | Writes a `DEC-` at `status: draft`. Also the entry point for a void planning assumption, which is where `bmad-correct-course` is dispatched | anyone |
+| `accept` | Raises `draft` → `accepted` | **the Product Owner only** |
+| `apply` | Dispatches the owner of every document the decision reaches, checks what came back, fills `touches`, raises `applied` | anyone |
+
+Applying is what **freezes** a decision, not accepting. `decision-guide.md` owns the full ladder and this skill
+MUST NOT restate it.
+
+## The one test, before anything is written
+
+> **If someone asks in three months why it is like this, is the answer readable from the code?**
+
+Yes → it MUST NOT be recorded. No → record it.
+
+**Recording is not mandatory**, and a decision nobody recorded is normal rather than negligence. You MUST NOT
+log it as debt or backfill it later from memory. One case stays mandatory: a decision that **contradicts or
+changes an `AD-N`**.
+
+The old name ADR forced the wrong question — *"is this architectural?"* — and that question threw away exactly
+the decisions most worth keeping, the ones that sound small.
+
+## Intent `open`
+
+### Inputs
+
+Any of these, alone or together: minutes in `.control/meetings/`, an answered question in
+`.control/questions/`, a review or debugging finding, a memlog in `.control/memlog/`, a `wdi-reconcile` conflict.
+
+The memlog is the richest source and the most often forgotten. It is the record of *why* — read it before
+writing the Why section rather than reconstructing the reasoning from the outcome.
+
+### What it writes
+
+Three sections, always: **Decision** (one sentence, present tense, quotable) · **Why** · **Cost** (what becomes
+harder). Alternatives, a reversal trigger, and Trace are required only when the decision reaches a Product
+Component whose `risk_accepted` is `low`; elsewhere an empty one MUST be dropped rather than left as a heading.
+
+Frontmatter carries `touches: []` — empty until applied — and `type:` when it is useful. There is no `layer:`
+and no `component:`; both were classifications demanded before anything was known.
+
+A `DEC-` MUST NOT hold an open question. Those go to `wdi-question`.
+
+### A void planning assumption
+
+This is the same intent, with one extra step in front. The trigger is one thing: **a planning assumption turned
+out to be void.** It usually surfaces while building, but its impact reaches back into G2, G3, and G4.
+
+Three things it is **not**:
+
+| Ask | Route |
+|---|---|
+| Something is broken and the cause is unknown | `wdi-systematic-debugging` **first**. A correction built on a guessed cause corrects the wrong thing |
+| A decision exists and documents must follow | intent `apply`. There is no plan to re-cut |
+| Scope grows without invalidating anything | `wdi-product` intent `update`, then the normal flow |
+
+State the void assumption in **one line** before dispatching. A correction whose trigger cannot be stated in one
+line is a re-plan, and it belongs upstream.
+
+Then dispatch `bmad-correct-course`. Do not restate the rules to it — they arrive through `persistent_facts` in
+`_bmad/custom/bmad-correct-course.toml`, including the ban on direct edits. Name the corpus files in scope
+explicitly; it globs its own defaults, which this project does not use.
+
+**Its impact analysis is incomplete by construction** — it knows a PRD and BMad's own planning shapes, and it cannot see
+`.what/<pc>/`, `.how/`, `.control/`, or `.constitution/`. Every one of these MUST be checked here:
+
+| Layer | What to look for |
+|---|---|
+| `.what/_prd/` | The `FR`/`NFR` that no longer holds, and every one depending on it |
+| `.what/<pc>/` | Use cases realising those `FR`, business rules, state lifecycles that lose a state |
+| `.how/_platform/` | An `AD-N` the correction breaks, a container the C4 set no longer describes, an inventory row with nothing behind it |
+| `.how/<pc>/` | Contracts, flows, and Failure Behaviour written against the old promise |
+| the contract | What the spec projected — it MUST NOT be edited to match; it is re-cut |
+| `specs.yaml` | The spec's size, and whether the correction changes it |
+| Ticket files | Which tickets are in progress, and which have not been picked up |
+
+The result is a `DEC-` of **`type: course-correction`**. The `SCP-` code is retired — a course correction is a
+decision, and no second code names the same thing.
+
+A correction cancelling more than **30%** of a spec's tickets MUST NOT be handled as a patch. Say so, and let
+the spec be re-cut through `wdi-build`.
+
+A ticket already in progress MUST NOT have what it asks for changed underneath it. Report it; stopping it and
+returning it to `ready-for-agent` is the coordinator's act.
+
+## Intent `accept`
+
+Only the Product Owner MAY raise a `DEC-` to `accepted`. **An agent MUST NOT accept its own.** When work is
+blocked waiting on one, the block is reported, never resolved by self-approval.
+
+An `accepted` `DEC-` that is still unapplied MAY be corrected in place, with the correction recorded in the
+memlog. Nothing has been built on it, so there is no divergent record to preserve.
+
+## Intent `apply`
+
+**You apply nothing yourself.** Every artifact has an owner, and the owner writes it. A hand-edit here produces
+a change with no author, no input trail, and nothing that verifies it.
+
+Exactly one `DEC-`, at `status: accepted`. You MUST NOT apply one in any other status.
+
+### Step 1 — List the targets before touching one
+
+Name every document the decision reaches, and the skill that owns each, **before** anything is dispatched. A
+list assembled while editing is a list that grows to fit what was already done.
+
+| Target | Dispatch |
+|---|---|
+| `.what/_product-brief/` | `wdi-problem` |
+| `.what/_prd/<initiative>/` | `wdi-product` intent `update` |
+| `.what/<pc>/` § Actor Register · § UC Catalogue · `03-domain/domain-model.md` | `wdi-blueprint` intent `catalog` |
+| `.what/business-rules.md` · `.control/product-glossary.md` | `wdi-blueprint` intent `catalog` |
+| `.how/_platform/` — spine, C4, `cross-cutting.md`, the three inventories | `wdi-blueprint` intent `platform` |
+| `.what/<pc>/` slots `02`–`05` — full flows, local rules, lifecycles, scenarios | `wdi-component` intent `behaviour` |
+| `.how/<pc>/` minus `01-ux/` | `wdi-component` intent `design` |
+| `EXPERIENCE.md` · `.how/<pc>/01-ux/` · `design-system.md` | `wdi-ux` |
+| `components.yaml` — a PC born or changed · `mode` · `risk_accepted` · the two structure maps | `wdi-init`, by intent |
+| `specs.yaml`, or anything inside an open spec | `wdi-build` |
+| `.control/questions/` | `wdi-question` |
+| `.control/project-non-technical-log.md` · `.control/meetings/` | `wdi-log` |
+
+A target with **no row here** MUST be reported as a gap in the method, not given a plausible owner.
+
+Apply in layer order — **`.what/` before `.how/`** — so the lower layer is written against the promise it is
+supposed to serve, not against the one it is about to replace. The retired `layer:` field used to declare that
+order in advance; it is now simply the order.
+
+### Step 2 — Dispatch, one owner at a time
+
+Hand each owner the `DEC-` id and the exact change its layer has to carry. You MUST NOT restate the decision in
+your own words; **quote it.** A paraphrase drifts, and the drift is invisible because both texts read reasonably.
+
+Each owner keeps its own rules — its review, its memlog, its registry entry. You MUST NOT ask an owner to skip
+any of them because the change is small.
+
+### Step 3 — Name the gates
+
+Run the change-control matrix in `delivery-flow-guide.md` and **report** which gates it names. You MUST NOT
+reopen a gate yourself, and you MUST NOT treat a green application as a gate that has already passed.
+
+### Step 4 — Close the trail
+
+- Fill `touches:` with the files that were **actually** changed, in the `DEC-` and in `decisions.yaml`. Raise
+  `status: applied`. **From that point the file MUST NOT be edited** — not the Decision, not the Cost, not a
+  typo in the Why. Documents cite it now.
+- `applied-dec-touches` checks that an `applied` decision names a non-empty `touches`.
+- Regenerate `.control/generated/decisions.md` with `validate.py --generate`. That table is how a decision is
+  found now; searching the memlog for decisions is retired, and the memlog is a run log again.
+- Report what changed, and what the decision implied but was **not** changed.
+
+## Rules
+
+- You MUST NOT widen scope beyond the decision. A neighbouring paragraph that now looks wrong is a finding to
+  report, not a change to make.
+- You MUST NOT introduce a new domain noun. If the decision requires one, it goes through `wdi-blueprint` first.
+- If applying would contradict another `applied` decision, you MUST stop and report the conflict. Two applied
+  decisions that disagree is work for intent `open`, not something to resolve by preferring the newer one.
+- If the decision is unapplicable as written — the document it names no longer exists, or the change was already
+  made differently — you MUST report that instead of improvising.
+- **Apply the whole chain in one pass.** `touches:` names what the decision reaches and the ownership
+  table names who lands each part. Edit all of them, then report once. Checking one file, reporting,
+  waiting, then checking the next is where the time goes — `corpus-guide.md` § One decided change is one
+  edit pass owns the rule.
+- You MUST NOT apply into a spec that is already closed.
+- `AD-N` is a different thing: a living rule with Binds · Prevents · Rule, edited in place. You MUST NOT convert
+  one into the other.
+- A decision that emerged from a failed third fix attempt MUST say so in Why. That is the signal
+  `wdi-systematic-debugging` exists to raise, and burying it wastes the finding.
+
+## Output
+
+Intent taken. For `open`: the decision in one sentence, its three required sections, and — for a correction —
+the void assumption in one line plus what the scan found that `bmad-correct-course` could not see. For `apply`:
+every target with its owner, what each owner changed, what was reported instead of changed and why, the gates the
+matrix names, and whether `touches` and `applied` were filled.

package/kit/skills/wdi-explain-to-me/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: wdi-explain-to-me
+description: Use when the owner has to decide something — an open question, a defect, a design fork, a failing validator, a vague worry — and wants the reading done for them. Investigates, then briefs in six fixed sections, in the owner's language. Writes no file; the decision itself goes to wdi-decision or wdi-question.
+disable-model-invocation: true
+---
+
+# WDI Explain To Me
+
+The owner names a problem. The result is a **decision briefing**: everything needed to decide, with the
+agent doing all of the reading and the owner doing only the deciding.
+
+`disable-model-invocation: true` is deliberate. A briefing is written for a person who has to choose;
+a skill that wants one has nothing to choose, and would only be reading its own summary back.
+
+Four asks look alike from the outside and are four skills:
+
+| Ask | Skill |
+|---|---|
+| "Where am I, what next" | `wdi-help` — position and routing, under fifteen lines |
+| "Brief me so I can decide this" | **this skill** — investigation, then a briefing |
+| "Record what was decided" | `wdi-decision` |
+| "This cannot be decided now" | `wdi-question` |
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| The topic argument | An id (`OQ-12`, `DEC-007`, a defect row, a validator name), a file path, or a sentence |
+| `.control/registry/*.yaml` · `.control/generated/status` | What the registry says holds today, and which validators are red |
+| `.control/questions/` · `.control/decisions/` | Whether this was asked or decided before, and what is already settled |
+| The working documents in `.what/` and `.how/` | The promise and the mechanism the topic touches |
+| `validate.py` output · tests · git history · the code | What actually holds, as opposed to what a document claims |
+
+## Step 1 — Investigate
+
+When the topic is too vague to investigate, ask **one** narrowing question first — one, not a list. A
+briefing on the wrong topic wastes the owner's five minutes.
+
+Then read the sources that bear on the topic before writing a word: files, registries, validator or test
+output, git history. Run what can be run. Done when every claim the briefing will make traces to
+something read or executed in this session, with its `file:line` in hand.
+
+## Step 2 — Brief
+
+**Language.** Write in the language the owner is using in the conversation. When that is unclear, use
+`policy.doc_language` from `.control/registry/index.yaml`. Method terminology — ids, gate names, the
+values of `mode` and `risk_accepted`, validator names — stays English as `language-guide.md` requires;
+those are keys, not prose.
+
+**Six sections, fixed in number, order, and meaning.** The headings are given here in English; render
+each one in the briefing's language and keep its slot. A briefing that drops, merges, or reorders a
+section has changed what the owner can compare it against.
+
+1. **Topic** — what kind of thing this is (an `OQ-`? a defect? a design fork? stale prose?) and the one
+   decision it asks for. Two or three sentences.
+2. **Background** — how it came to exist and what is already settled. Plain language; gloss any term of
+   art in half a sentence where it first appears.
+3. **Problem Analysis** — what is actually wrong and why, with evidence. Put a `file:line` citation
+   beside each claim; the reader MAY verify, but MUST NOT need to.
+4. **Solution Design** — 2–4 options. For each: what changes, what it costs, what breaks or is lost, and
+   the size of the work. An option whose downside is missing has not been analysed.
+5. **Recommendation** — exactly one, with its reason and the single condition that would flip it.
+6. **What Helps You Decide** — the facts worth weighing against each other, then a verdict on the
+   owner's own eyes: either state that this briefing is sufficient, or name the exact file, section, or
+   screen the owner MUST look at themselves and what to look for there. Reserve that second verdict for
+   judgement only the owner can make — taste, risk appetite, a promise to a stakeholder — never for
+   legwork the investigation could have done.
+
+Done when the owner could decide from the briefing alone, or knows exactly what to open and why.
+
+## Rules
+
+- Reading time MUST stay under five minutes; push detail into citations, not prose.
+- A claim without a source read this session MUST NOT appear in the briefing. Memory is not a source.
+- This skill writes **no file** and MUST NOT edit anything. The briefing lives in the conversation. It
+  MUST NOT open a `DEC-`, file an `OQ-`, or patch the corpus on the way — a briefing that also changes
+  things leaves nothing to decide against.
+- You MUST NOT run other skills on the owner's behalf. Name the skill; let them invoke it.
+
+## Output
+
+The six sections, then one line naming where the decision goes once it is made: `wdi-decision` intent
+`open` when it is worth remembering, the owning document directly when it is not, or `wdi-question`
+when it turns out it cannot be decided yet.

package/kit/skills/wdi-help/SKILL.md

@@ -18,10 +18,10 @@ about BMad itself.
 
 | Source | What it answers |
 |---|---|
-| `.control/generated/status` | Which wave is open, which stories sit at which status, which validators are red |
+| `.control/generated/status` | Which spec is open, how many of its tickets are done, which validators are red |
 | `.control/registry/index.yaml` | The global `mode`, and the gate map |
 | `.control/registry/components.yaml` | Per-component `mode`, `risk_accepted`, and `g4_passed` |
-| `.control/registry/waves.yaml` | Wave → release, size, `depends_on` |
+| `.control/registry/specs.yaml` | Spec → release, size, `depends_on`, and its ticket index |
 | `.constitution/method/document/delivery-flow-guide.md` | The five gates and their checklists |
 | `.constitution/method/why/README.md` | The whole shape, when the caller has never seen the method |
 
@@ -48,21 +48,23 @@ mis-route in this flow, because every other gate is the same for every component
 
 | State | Next |
 |---|---|
+| `wdi-method update` just ran and its summary printed an `upgrade` line | `wdi-upgrade` — **before anything else**. Content is still in the old shape, and every skill below reads the new one |
 | No registry, or no global `mode` set | `wdi-init` intent `setup` — nothing has started |
 | No `.what/_product-brief/brief.md` | `wdi-problem` — G1 has not started |
 | A brief exists, and no PRD covers the area in play | `wdi-product` intent `prd` |
 | A PRD covers it but the promise has moved | `wdi-product` intent `update` — never a second PRD for the same area |
 | Only the **wording** of an `FR` is wrong | Nobody. Whichever skill is at work fixes it directly; putting it behind a gate is how three earlier corrections were dropped |
-| A PRD exists and the interface is a large part of what it promises | `wdi-ux` — optional, and it lands nothing until a `<pc>` exists |
+| A PRD exists and the interface is a large part of what it promises | `wdi-ux` — optional, and it runs **before G2**, which reads its `EXPERIENCE.md`. It needs no Product Component: `design-system.md` lands at once, and the two `<pc>`-scoped halves land when `wdi-init` intent `component` runs |
 | A PRD exists, no `product_components` yet | `wdi-init` intent `component` — the slicing is born here, at the tail of G2 |
 | Components exist, `mode` or `risk_accepted` unset | `wdi-init` intents `mode` and `risk` — both are the owner's, and G4 cannot be read without them |
 | Components exist, no UC catalogue or no spine | `wdi-blueprint` — intent `catalog` first, then `platform` |
-| The blueprint is complete and G3 has not been held | The gate. Read `.control/generated/blueprint.md`, not seven files |
+| The blueprint is complete and G3 has not been held | The gate. Read `.how-rendered/blueprint.md`, not seven files |
 | G3 passed, a component at `outline`/`guarded`/`deep` has no depth | `wdi-component` |
 | G3 passed, the component is at `mode: catalog` | `wdi-build` — G4 is skipped by design |
-| Depth done and G4 passed for every component the work touches | `wdi-build` — it opens the wave, runs `bmad-spec`, ships each story, closes the wave |
-| 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 |
+| Depth done and G4 passed for every component the work touches | `wdi-build` — it opens the spec, has the owner run `to-spec` and `to-tickets`, ships each ticket, closes the spec |
+| A small fix touching no `FR`, `UC`, `AD-N`, or domain model | Fast Path: the owner runs `/implement` directly. It stops and becomes a spec `S` the moment an `FR` is touched |
 | A planning assumption turned out void | `wdi-decision` intent `open` — it proposes, and changes nothing |
+| The owner has to decide something and wants the reading done first | `wdi-explain-to-me` — it briefs, and changes nothing; the decision then goes to `wdi-decision` or `wdi-question` |
 | An accepted `DEC-` has not reached its documents | `wdi-decision` intent `apply` |
 | A bug, a failing test, unexpected behaviour | `wdi-systematic-debugging`, before any fix is proposed |
 | Numbers are wanted before the work is committed | `wdi-report` intent `estimate` |
@@ -92,7 +94,7 @@ it claims, or when one of its eight required sections is missing outright.
 - When the caller has never seen this method, point at `.constitution/method/why/README.md` rather than
   paraphrasing it here.
 
-## When there is no wave open
+## When there is no spec open
 
 Say so plainly, then route by the table above. An artifact a later gate produces MUST NOT be reported as
 missing — that is not a gap, it is the plan.

package/kit/skills/wdi-init/SKILL.md

@@ -15,7 +15,7 @@ of where things are, a reader that can see this product's code.
 | `component` | Propose the slicing from the brief plus every PRD · birth what is accepted: registry row plus `SRS`/`SDD` skeletons · propose `mode`, `risk_accepted`, `risk_note`, `owns` | **G2 passed** | each time a component is born |
 | `mode` | Change `mode` — global in `index.yaml`, or one component in `components.yaml`. Guided | — | any time |
 | `risk` | Set or review one component's `risk_accepted`, with disclosure of what it touches | the component exists | any time, usually before G4 |
-| `structure` | Re-derive `.control/structure-codebase.md` and `structure-document.md` from the tree on disk | — | when folders change, and at wave close |
+| `structure` | Re-derive `.control/structure-codebase.md` and `structure-document.md` from the tree on disk | — | when folders change, and at spec close |
 | `readers` | Write `.constitution/project/inventory-readers.py` for **this** repo's stack, then prove it by running the engine | code exists | once, and again when the code's shape moves |
 
 ## Two boundaries
@@ -67,8 +67,9 @@ to its component, however platform-shaped the table looks.
 ## Intents `mode` and `risk` — disclose, then propose
 
 `mode` controls **document depth** and nothing else. `risk_accepted` controls **review intensity** and
-nothing else. Their definitions live in `delivery-flow-guide.md`. What this skill owns is the
-conversation around changing them.
+nothing else. Their definitions live in `delivery-flow-guide.md`, and what the two chosen together cost is
+laid out cell by cell in `.constitution/method/why/mode-risk-map.md` — show it when the owner asks what a
+combination buys. What this skill owns is the conversation around changing them.
 
 **You do not judge. You disclose, then propose.** Read the `FR` that fall to the component, then name
 what it touches:
@@ -81,15 +82,28 @@ what it touches:
 
 Only after that do you propose `mode` and `risk_accepted`.
 
+**Land whatever UX is waiting, in this same act.** A UX run at G2 leaves `EXPERIENCE.md` and `DESIGN.md`
+in `_bmad-output/ux/` because their paths contain `<pc>` and there was no `<pc>` yet. Birthing the
+components is the moment that ends. Landing goes through `wdi-ux` — it owns those two paths and no other
+skill MAY write them — but it is dispatched from here rather than left for the owner to remember. It is
+the only deferral left in the flow, and this is where it closes.
+
+**Containers MAY be registered here when they are genuinely already known** — an app, an API, a database
+the product plainly has. Then a screen `LC` gets its container the moment it is born and there is no debt
+at all. They MUST NOT be guessed to achieve that: `wdi-blueprint` intent `platform` owns the real answer
+at G3, and a container invented here is data C4 then has to unpick. Where you are unsure, leave them and
+let G3 fill both the containers and the empty `LC` rows in one act.
+
 Raising or lowering `mode` is **free and needs no justification** — it is a preference, and a preference
 does not have to be defended. Setting `mode: catalog` on a sensitive component requires nothing, as long
 as its review stays hard; that combination is the one the split exists to make sayable.
 
 Two things are not free:
 
-- **`risk_accepted: high` on a component that touches any of the five** requires a `DEC-` of
-  `type: risk-acceptance`, and `risk_accepted_by:` pointing at it. V23 checks this. On a component that
-  touches none of them, `high` is free.
+- **`risk_accepted: high` on a component that touches any of the five** requires a named acceptance in
+  `risk_accepted_by` — **a person and a date is enough**, written here in `components.yaml` beside the
+  risk itself rather than as a separate file. A `DEC-` id is still accepted and still has to resolve.
+  `high-risk-named` checks this. On a component that touches none of them, `high` is free.
 - **An outside party who will demand the artifacts as a deliverable** — a regulator, an auditor, a
   client through a contract — puts the touched component at `mode: deep` and `risk_accepted: low`,
   whatever the global setting says. That floor MUST NOT be traded against a preference: the risk there