wdi-method 0.5.13 → 0.6.0

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

@@ -1,99 +1,164 @@
 ---
 name: wdi-build
-description: Use at G5 Release — one wave from open to closed in one supervised run. Opens the wave, runs bmad-spec, ships every story to a green PR through a five-step pipeline, then closes the wave. One invocation, not four.
+description: Use at G5 Release — one spec from open to closed in one supervised run. Opens the spec, hands the owner to-spec and to-tickets, ships every ticket to a green PR through a five-step pipeline, then closes the spec. One invocation, not four.
 ---
 
 # WDI Build
 
-One unit of work, one invocation. A wave used to need four calls — open it, run `bmad-spec`, ship each story,
-close it — and three of those were bookkeeping. They are all in here now, because a unit of work that needs
-four invocations gets three of them skipped.
+One unit of work, one invocation. A spec used to need four calls — open it, produce the contract, ship each
+ticket, close it — and three of those were bookkeeping. They are all in here now, because a unit of work that
+needs four invocations gets three of them skipped.
 
-**REQUIRED SUB-SKILL:** MUST dispatch, wait, and escalate through `orchestration`. Worker CLI/model/effort MUST
-come from the Orca Agent Dispatch tables in the user's Agent Rules; this skill MUST NOT restate them.
+**The engine layer below this gate is not BMad's.** `to-spec`, `to-tickets`, and `implement` produce the
+contract, the tickets, and the code; `tdd` and `code-review` do the work inside them. `bmad-spec`,
+`bmad-build`, `bmad-build-auto`, and `bmad-code-review` are **retired** and MUST NOT be invoked.
 
-The coordinator (this session) holds every judge call, the registries, and every remote git action. Dispatched
-workers hold the spec and the code.
+**Three of those engines are human-invoked.** `to-spec`, `to-tickets`, and `implement` carry
+`disable-model-invocation: true`, so this skill CANNOT invoke them and MUST NOT claim to. It states the command
+for the owner to run, waits, then verifies the result and lands it. That is not a workaround: the points where
+those engines need a human are the gates, and owner time is what a gate is for.
+
+**No orchestration tool is required, and this skill MUST NOT name one.** How the work is carried out is the
+session's own arrangement: an orchestration skill, this CLI's native subagent tooling, or the coordinator doing
+a step itself. Which CLI, which model, and which effort staff a step come from the local Agent Rules, and MUST
+NOT be restated here. Every rule below holds whatever the mechanism — they are about the artifact and who
+judges it, not about how an agent is launched.
+
+Two roles exist regardless. The **coordinator** — this session — holds every judge call, the registries, and
+every remote git action. The **builder** of a step holds the spec and the code.
+
+When the coordinator is also the builder, the separation the pipeline rests on is absent. That MUST be reported
+as absent rather than worked around: a step judged by whoever wrote it is a self-report. One consequence is
+hard — see Step 3: at `risk_accepted: low` the panel requires reviewers who are not the builder, and a session
+that cannot provide them is **blocked**, not excused.
 
 ## Precondition, and the one that is easy to miss
 
 | Check | When it fails |
 |---|---|
-| Every component this wave touches has passed G4, **or** sits at `mode: catalog` | Route to `wdi-component`. V22 checks it, and `catalog` skipping G4 is by design, not an exception |
+| Every component this spec touches has passed G4, **or** sits at `mode: catalog` | Route to `wdi-component`. `spec-after-g4` checks it, and `catalog` skipping G4 is by design, not an exception |
 | An isolated worktree | Isolate first. MUST NOT run in a shared checkout |
-| Every `prd` slug names a real `.what/_prd/<initiative>/` folder | A wave without a promise covering it is a wave nobody agreed to (V17) |
+| Every `prd` slug names a real `.what/_prd/<initiative>/` folder | A spec without a promise covering it is a spec nobody agreed to (`spec-names-release-prd`) |
 
 The repo commits straight to `main` and opens a PR only when asked. **Invoking this skill is that ask**, for
-this wave only; it MUST NOT be read as standing permission for the next change.
+this spec only; it MUST NOT be read as standing permission for the next change.
 
-## Phase 1 — Open the wave
+## Phase 1 — Open the spec
 
-Record it in `.control/registry/waves.yaml`:
+Record it in `.control/registry/specs.yaml`. The frame opens here; the `tickets` rows land in Phase 2, because
+that is where they are born.
 
 | Field | Rule |
 |---|---|
-| `id` | `W<N>`, monotonic, never reused |
-| `release` | MUST be stated. The release↔wave cadence is situational and MUST NOT be inferred from numbering (V17) |
-| `prd` | MUST be stated: which initiative PRDs this wave delivers against. MUST NOT be derived from `release` |
-| `fr` | The `FR` this wave satisfies. Ideally one — an `FR` is human-testable from birth |
+| `id` | `SPEC-<N>`, monotonic, never reused. A `W<N>` id in a frozen record is a **retired alias** and MUST NOT be rewritten |
+| `release` | MUST be stated. The release↔spec cadence is situational and MUST NOT be inferred from numbering (`spec-names-release-prd`) |
+| `prd` | MUST be stated: which initiative PRDs this spec delivers against. MUST NOT be derived from `release` |
+| `fr` | The `FR` this spec satisfies. Ideally one — an `FR` is human-testable from birth |
 | `size` | `S` · `M` · `L`. MAY be raised mid-flight; MUST NOT be lowered |
-| `depends_on` | At **wave** level. A wave declaring none runs in parallel with its neighbours |
-| `spec_folder` | One per wave, not one per wave × component |
-| `epics` → `stories` | With `satisfies: [UC]`, `depends_on`, `touches`, and test names |
-
-Story **status** MUST NOT be copied into `waves.yaml`. It is read from story-file frontmatter when
-`.control/generated/` regenerates (V18). Two homes for one fact is how registries start lying.
-
-Size does not choose which gates are active — that is `mode`'s job. It governs session merging (`S` merges G4
-and G5 into one 20-minute session) and whether the retrospective runs (`L`).
-
-## Phase 2 — The SPEC
-
-Dispatch `bmad-spec` for the wave, slug `w<N>-<slug>`. **One wave = one `SPEC` = one tracker Task**, with no
-compound joins.
-
-`SPEC.md` is a **projection** of `.what/` + `.how/` onto this wave and MUST NOT introduce anything new. When it
-needs something that is not in either, the gap is upstream: route to `wdi-component` or `wdi-blueprint`, and do
-not let the SPEC invent it.
-
-`SPEC.md` and story files **are not read by humans.** Both are machine contracts, and no review burden MAY be
-moved onto them. `wdi-review` MAY still be dispatched over the SPEC; its trace lands on the wave in
-`waves.yaml`, because `bmad-spec` is the sole author of the file and overwrites hand edits.
-
-## Phase 3 — Ship each story
-
-Steps 1–2 run `bmad-build-auto` under **folder+id dispatch**: the coordinator supplies `spec_folder` and
-`story_id`, and the worker resolves everything else from `{spec_folder}/stories.yaml` and `SPEC.md`.
+| `depends_on` | At **spec** level. A spec declaring none runs in parallel with its neighbours |
+| `spec_folder` | One per spec, not one per spec × component |
+| `tickets` | Flat, one row per ticket: `id` · `component` · `satisfies: [UC]` · `blocked_by` · `touches` · test names |
+| a ticket `id` | `<spec-id>-<NN>` — `SPEC-3-01`. The engine numbers its files from `01` per feature, which is unique only inside one spec; the RTM needs a key that is unique across the corpus |
+
+**`tickets` is an index, not a store.** The ticket's prose lives where the tracker put it; the row carries only
+what RTM and the validators read. And ticket **status** MUST NOT be copied here — it is read from the ticket
+itself when `.control/generated/` regenerates (`ticket-status-one-home`). Two homes for one fact is how registries start lying.
+
+`ticket-status-one-home` finds the file at `{spec_folder}/issues/<NN>-*.md`, from the number at the tail of the id, and reads its
+status from either a `**Status:**` body line — what the engine writes, because a ticket file is a tracker
+payload and trackers do not read YAML — or `status:` in frontmatter.
+
+The `epics` nesting is **repealed**. A ticket names its `component` directly; an intermediate level that only
+grouped rows bought nothing and cost a lookup.
+
+Size does not choose which gates are active — that is `mode`'s job. It decides two things: session merging
+(`S` merges G4 and G5 into one 20-minute session) and whether `SPEC.md` is written at all.
+
+## Phase 2 — The contract, and the tickets
+
+Two engines, and **the owner runs both.** State the command, wait, then verify and land.
+
+| Size | What the owner runs | What lands |
+|---|---|---|
+| `M` · `L` | `/to-spec`, then `/to-tickets` | `SPEC.md` in `spec_folder` · ticket files · the `tickets` index rows |
+| `S` | `/to-tickets` only | ticket files · the `tickets` index rows. **No `SPEC.md`** |
+
+At `S` the tickets **are** the contract. `to-tickets` accepts a conversation directly, so a middle document
+buys nothing there. From `M` up it is written first, because two things have to be settled **before** tickets
+are cut and neither survives being decided afterwards: the **seams** the feature will be tested at — fewest
+possible, highest possible, agreed with the owner — and the **testing decisions**, which say what a good test
+is here and name the prior art.
+
+### What you verify before landing anything
+
+- **Nothing new.** `SPEC.md` is a **projection** of `.what/` + `.how/`. It MAY restate a promise in its own
+  words — a machine contract is more useful self-contained — but **every restatement MUST refer to the live
+  corpus document it came from.** A reference that does not resolve is not a wording problem: the gap is
+  upstream. Route to `wdi-component` or `wdi-blueprint`, and do not let the contract invent it.
+- **Every user story resolves to an id.** A user story with no `FR` or `UC` behind it is a **new promise**,
+  and a new promise is `wdi-product`'s, never a spec's.
+- **Every ticket names what it satisfies.** No `satisfies`, no landing: without it the chain
+  `FR → UC → ticket → test` breaks and RTM cannot say which promise went green. This is the one field
+  `to-tickets` does not ask for on its own, so it is the one most likely to be missing.
+- **Every ticket is vertical.** A slice of one layer is not a ticket. The exception is a wide refactor,
+  sequenced expand → migrate in batches → contract; `delivery-flow-guide.md` owns that rule.
+- **Ticket files land under `spec_folder`.** Their **shape** is the engine's — one file per ticket, numbered
+  in dependency order, blocking edges declared — and only the root is ours, because `to-tickets` states its
+  own location is tracker-specific and configured. A ticket at the repo root, or under `docs/` or
+  `.scratch/`, is drift: Article 3 names every layer this method has and those are not among them.
+
+`SPEC.md` and ticket files **are not read by humans.** Both are machine contracts, and no review burden MAY be
+moved onto them. `wdi-review` MAY still be dispatched over the contract; its trace lands on the spec in
+`specs.yaml` — and where there is no `SPEC.md`, one trace covers the **ticket set as one artifact**, never one
+review per ticket.
+
+## Phase 3 — Ship each ticket
+
+Work the **frontier**: the tickets whose blockers are all closed. A ticket whose `blocked_by` is not yet
+satisfied MUST NOT be started, however ready it looks.
 
 | # | Step | Engine | Exit condition |
 |---|---|---|---|
-| 1 | Plan | `bmad-build-auto` + `Halt after planning.` | Spec frontmatter reads `status: ready-for-dev` |
-| 2 | Build | `bmad-build-auto` given the spec path | Spec frontmatter reads `status: done` |
-| 3 | Panel | `bmad-code-review` | Panel adjudicated, zero unresolved must-fix |
-| 4 | Publish | — | Branch pushed, PR open, story-closing checklist answered |
+| 1 | Encode | `/tdd` | **Failing tests exist that encode this ticket's acceptance criteria** |
+| 2 | Build | `/implement` — the owner runs it; it uses `/tdd` at the agreed seams | Those tests green, typecheck clean, full suite green once |
+| 3 | Panel | `code-review`, as a **separate** dispatch | Panel adjudicated, zero unresolved must-fix |
+| 4 | Publish | — | Branch pushed, PR open, ticket-closing checklist answered |
 | 5 | CI | — | All checks conclude green on the pushed head SHA |
 
+**Step 1 is the change that matters most.** It used to be a plan, judged from a frontmatter field a builder
+wrote about itself. Now it is a **failing test suite** — the acceptance criteria, encoded, and demonstrably
+red. That is evidence rather than a claim, and it is what `ticket-has-test` and G5's ★2 have always been asking for:
+*acceptance criteria proven by a test, not by an agent's statement.* Under TDD the test exists **before** the
+code, so the proof is not retrofitted.
+
 ### Engine rules
 
-- MUST judge a step from the spec's frontmatter `status`. A worker's chat report MUST NOT settle it.
-- Every step MUST go to a **fresh** worker, and a fix round MUST NOT go back to the worker that produced the
-  code. The spec carries everything the next worker needs, and inherited context is how a step stops judging
-  the artifact on its own merits.
-- MUST launch every worker with its Unattended flag, and MUST confirm each started from observed activity —
-  never from a readiness match alone.
-- MUST NOT dispatch to a CLI that cannot spawn subagents. `blocked / no subagents` is a CLI capability failure,
-  not a story failure: re-dispatch the same step on the other CLI in that row.
+- **MUST judge Steps 1 and 2 from the test suite**, not from a report and not from a status field. Red at the
+  right assertions closes Step 1; green with a clean typecheck closes Step 2. A builder's chat report MUST NOT
+  settle either.
+- Ticket **status** is read from the ticket itself. It MUST NOT be copied into `specs.yaml` (`ticket-status-one-home`).
+- Every step MUST start from a **fresh context**, and a fix round MUST NOT go back to whoever produced the
+  code. The ticket carries everything the next builder needs, and inherited context is how a step stops judging
+  the artifact on its own merits. Where one session runs consecutive steps itself, it MUST re-read the artifact
+  rather than trust what it remembers writing.
+- A step handed to a separate agent MUST be launched so it cannot sit waiting for input nobody will give, and
+  its start MUST be confirmed from observed activity — never from a readiness match alone.
+- A step that fails because the agent could not spawn what it needed is a **capability** failure, not a ticket
+  failure. MUST retry it somewhere that can, and MUST NOT record it against the ticket.
 - MUST NOT reorder or drop a step. A step with nothing to do MUST be reported as such, not skipped silently.
-- A spec already at `status: blocked` MUST be repaired and its status reset before re-dispatch.
+- A ticket returned by the panel MUST have its acceptance criteria amended and its status reset before it is
+  picked up again — see Step 3.
 
-### What every worker brief MUST carry
+### What every builder brief MUST carry
 
-Three rules this corpus adds. All three MUST be stated in the dispatch of any step that writes code.
+Three rules this corpus adds, and `/implement` knows none of them. All three MUST reach whoever writes code in
+this spec — in the dispatch when a step is dispatched, and in the session's own working instructions when it
+is not.
 
 - **Debugging is conditional, never a phase.** When a test or build fails and the cause is not known, the
-  worker MUST run `wdi-systematic-debugging` before proposing any fix. A third failed fix attempt is the signal
+  builder MUST run `wdi-systematic-debugging` before proposing any fix. A third failed fix attempt is the signal
   to escalate, not to try a fourth.
-- **The corpus is not the worker's to change.** A worker MUST NOT edit `.what/`, `.how/`, or an `applied`
+- **The corpus is not the builder's to change.** A builder MUST NOT edit `.what/`, `.how/`, or an `applied`
   `DEC-`. A deviation from the SDD or an `AD-N` is **reported**, and it becomes a `DEC-` through
   `wdi-decision` — never absorbed as a code patch.
 - **Verification is run, not assumed.** The commands are this product's, and they live in
@@ -101,38 +166,52 @@ Three rules this corpus adds. All three MUST be stated in the dispatch of any st
   the directory it runs from. A skill MUST NOT carry one product's build line. A green registry workflow
   MUST NOT be reported as proof the code compiles; they answer different questions.
 
-### Step 1 — plan
+### Step 1 — encode the acceptance criteria as failing tests
 
-- MUST include `Halt after planning.` Without it the worker runs straight through implementation and Step 2
-  loses its gate.
-- Validation is not a separate step. Step-02's READY-FOR-DEVELOPMENT gate verifies the spec, repairs it once,
-  and re-verifies. MUST NOT wrap a second validation loop around it.
-- `blocked / spec failed ready-for-development standard` means that repair did not converge. MUST escalate the
-  failing criteria; MUST NOT hand-patch the spec into a pass.
-- `blocked / intent gap` MUST reach the owner with the worker's unanswered questions verbatim.
+- The tests MUST be written **at the seams the spec agreed** — existing seams preferred, highest possible,
+  fewest possible. Inventing a new seam here, after the agreement, is a finding: it means Step 1 is redesigning
+  what Phase 2 settled.
+- Every acceptance criterion MUST have at least one test. A criterion no test can express is not an acceptance
+  criterion — it goes back to the ticket, or to the owner as an intent gap.
+- The tests MUST be **seen red, at the right assertions.** A test that passes before the code exists is testing
+  nothing, and a suite that fails for the wrong reason — an import error, a missing fixture — has not encoded
+  anything yet.
+- A test MUST NOT assert a literal where the behaviour is what matters. The panel treats that as a test that
+  cannot fail, and returns it.
 
 ### Step 2 — build
 
-- MUST dispatch with the spec file path and the three brief rules above. The worker commits locally and **never
-  pushes**.
-- `blocked / review repair loop exceeded 5 iterations` means its internal loop did not converge. MUST escalate;
-  MUST NOT re-dispatch for a sixth.
-- On `blocked / intent gap` the worker has reverted the code and saved a patch file. MUST retrieve that patch
-  path from the triage log before escalating — the work is recoverable, and losing it costs the whole step.
+- The owner runs `/implement`, and it MUST be given the ticket and the three brief rules above.
+- It commits to the current branch and **never pushes**. That is its own behaviour and it is what we want; the
+  coordinator is the hand that pushes.
+- **`/implement` calls `/code-review` itself, and that call does NOT satisfy Step 3.** It is the builder
+  reviewing its own work — self-review by construction. Step 3 stands as a separate dispatch regardless of what
+  ran inside Step 2.
+- The full suite MUST be run green once at the end, not only the tests this ticket touched. A ticket that
+  passes its own tests and breaks a neighbour's has not finished.
+- Where the work turns out to need something the ticket does not authorise, it stops and reaches the owner with
+  the question verbatim. The builder MUST NOT widen its own scope.
 
 ### Step 3 — panel, then judge
 
 Panel composition follows `risk_accepted`: at `low` a two-reviewer panel is **required** on the code; at
 `medium` and `high` it is available and SHOULD be used when the diff touches money, personal data, or a third
-party. The Agent Rules `bmad-code-review panel` section defines the pairing, and it MUST be followed exactly —
-the worker's own review layers are same-family by construction and never satisfy it.
+party. The local Agent Rules govern which CLIs and models staff the panel. **A reviewer MUST be a different
+agent from the builder** — the builder's own review layers, `/implement`'s internal `/code-review` included,
+are self-review by construction and never satisfy the panel. This is the one separation in the pipeline that
+MUST NOT be collapsed: where the session cannot provide it and `risk_accepted` is `low`, the ticket is blocked
+and the owner MUST be told, because the field they set is what makes the panel required.
+
+`code-review` reviews along two axes — **Standards**, against this repo's documented conventions, and
+**Spec**, against what the ticket asked for. Both MUST run. Reporting one axis as the panel is reporting half
+a review.
 
 - MUST adjudicate every contested finding by reading the cited lines. Votes MUST NOT settle a finding. A finding
   neither reviewer can locate in the diff is dismissed with that reason stated.
 
 **MUST return to Step 2:**
 
-- Breaks a story AC, or contradicts the SPEC, the SDD, an `AD-N`, or an `applied` `DEC-`
+- Breaks a ticket's acceptance criterion, or contradicts the contract, the SDD, an `AD-N`, or an `applied` `DEC-`
 - Wrong behaviour, crash, or data loss reachable from the running app
 - Corpus drift: an `LC` touched but not registered, a contract changed in code but not in `02-contracts/`, a
   screen added without its `01-ux/` entry
@@ -142,25 +221,45 @@ the worker's own review layers are same-family by construction and never satisfy
   claims to cover
 
 **MUST record as follow-up and MUST NOT return to Step 2:** style or naming with no behaviour delta · a
-refactor outside this story's scope · a pre-existing defect this story did not touch · a speculative risk with
-no reachable path.
+refactor outside this ticket's scope · a pre-existing defect this ticket did not touch · a speculative risk
+with no reachable path.
 
-A must-fix MUST return as a **spec amendment**, never a chat instruction: amend the sections outside
-`<intent-contract>`, append a `## Spec Change Log` entry naming the finding, reset `status` to `ready-for-dev`,
-then re-dispatch. Content inside `<intent-contract>` is the owner's alone; a must-fix rooted there is an intent
-gap and goes to the owner.
+A must-fix MUST return as a **ticket amendment**, never a chat instruction: amend what the ticket asks for,
+note the finding that caused it, reset the ticket's status to `ready-for-agent`, then pick it up again. **What
+a ticket `satisfies` is not amendable here** — that is the promise, and a must-fix rooted in the promise is an
+intent gap that goes to the owner through `wdi-product`. Changing the `FR` a ticket serves in order to make the
+code pass is how a corpus starts agreeing with whatever was built.
 
 Cap: **2 return trips.** MUST re-run the whole panel after each fix round — a fix introduces defects. On hitting
 the cap MUST escalate and MUST NOT open a PR carrying an unresolved must-fix.
 
-### Step 4 — story-closing checklist, then push and PR
+### When the code turns out to be right and the document wrong
+
+This is normal during G5 and it is **not drift**. Building a thing is how you find out what the thing is.
+
+The builder still MUST NOT edit `.what/`, `.how/`, or an `applied` `DEC-` to make its own code fit — that is
+the corpus learning to agree with whatever was built, and it is a different failure. What happens instead:
 
-The checklist is **three items** now, and it MUST be answered before the PR opens:
+1. **Say it once.** Name what the code does, which promise it contradicts, and what that costs. One place,
+   one time. An `AD-N` is the one contradiction that **stops** — `decision-guide.md` owns it.
+2. **The owner decides.** If they adopt the code, that survey is spent.
+3. **The owning skill edits**, in the present tense, as if the design had always said this — `wdi-product`
+   for an `FR`, `wdi-component` for behaviour or design, `wdi-blueprint` for a cross-component rule.
 
-1. A decision worth remembering? → `wdi-decision`. A story contradicting an `AD-N` **stops** rather than
-   closing.
+What MUST NOT happen after step 2: raising the same conflict again in a later pass, opening an `OQ-` for it,
+dispatching a review over it, or writing anywhere in the corpus that the change arrived late. The commit is
+that record. `corpus-guide.md` § The corpus is written in the present tense is the binding rule.
+
+### Step 4 — ticket-closing checklist, then push and PR
+
+The checklist is **three items**, and it MUST be answered before the PR opens:
+
+1. Something the next person needs to know? → **into the document that carries it**, and that is almost
+   always where it ends. It reaches `wdi-decision` only when no design document has a home for it —
+   `decision-guide.md` § A decision's first home. A ticket contradicting an `AD-N` **stops** rather than
+   closing; that is the one case where recording is mandatory.
 2. A trap for the next agent? → recorded where the next agent will read it.
-3. Test names matching what `waves.yaml` records?
+3. Test names matching what `specs.yaml` records?
 
 The five items that left this list moved to Phase 4, where the information actually exists.
 
@@ -174,63 +273,75 @@ The five items that left this list moved to Phase 4, where the information actua
 - MUST wait for every check to conclude, then confirm the checks belong to the **pushed head SHA**. A green
   report from a stale run is a false report.
 - `korpus.yml` validates the corpus, not the code. Build and test evidence comes from Step 2's own runs.
-- Classify each failure before acting: a defect from this change → Step 2, with `wdi-systematic-debugging` when
+- Classify each failure before acting: a defect from this change → Step 1 if the test was missing, Step 2 if
+  the code was wrong, with `wdi-systematic-debugging` when
   the cause is unknown · infrastructure or flake → re-run **once**, and MUST NOT patch code to mask it; a second
   identical failure is a defect · a guard failure → fix the content.
 - Cap: 2 return trips. On hitting the cap MUST report red honestly rather than keep pushing.
 
-### Parallel stories
+### Parallel tickets
 
-Stories without a `depends_on` path between them MAY run at once, but four conditions MUST hold: each worker in
-its own worktree; V11 green for every pair released together; the first story of an epic already `done` so later
-stories inherit its code map; and no shared registry write in flight.
+Tickets with no blocking edge between them MAY run at once — that is what the frontier is — but four
+conditions MUST hold: each concurrent builder in its own worktree; `parallel-tickets-blocked` green for every pair released together;
+the first ticket that establishes a component's shape already closed, so later tickets inherit its code map;
+and no shared registry write in flight.
+
+**A wide refactor is the exception, and it inverts the rule.** Its batches MUST run in sequence, not in
+parallel, because each keeps CI green only while the expand still stands. Where even a batch cannot stay green
+alone, they share an integration branch and green is promised only at the final integrate-and-verify ticket.
 
 The pattern that MUST be preferred: run the biggest blocker alone first, let its shape decisions land, then fan
 out.
 
-## Phase 4 — Close the wave
+## Phase 4 — Close the spec
 
-Run in this order and stop at the first failure:
+**Six steps.** Run in this order and stop at the first failure.
 
-1. **Registry catch-up.** Every `LC` the wave's design named is registered in `components.yaml`, and every
-   `touches` value resolves — V12. This is the moment those questions have answers.
+1. **Registry catch-up.** Every `LC` the spec's design named is registered in `components.yaml`, and every
+   `touches` value resolves — `lc-registered`. This is the moment those questions have answers.
 2. **Inventories refreshed from code.** Run `.constitution/method/scripts/inventory.py`. The plan-versus-reality
    difference is reported as a finding; it MUST NOT be patched into agreement by hand.
 3. **Structure maps refreshed** through `wdi-init` intent `structure`, if a base folder was born or removed or a
    key file moved.
 4. **Distillation.** Every applicable row of the ownership table in `corpus-guide.md` has been landed by its
-   owner. Anything durable in the spec folder leaves it now, or dies with it.
-5. **Retrospective.** On wave `L`, dispatch `bmad-retrospective` and archive `RETROSPECTIVE.md` as
-   `RTR-<wave>.md` in `.control/reports/`. On `S` and `M` it is advisory — V19 says so, and skipping it MUST be
-   stated rather than silent.
-6. **RTM green.** Every traceability row for this wave is closed. New risks are in the risk register with an
+   owner. Anything durable in the spec folder leaves it now, or dies with it — **the ticket files included.**
+   Their prose is working output; what survives is the index in `specs.yaml` and whatever the checklist routed.
+5. **RTM green.** Every traceability row for this spec is closed. New risks are in the risk register with an
    owner.
-7. Mark the wave `status: closed` in `waves.yaml`.
+6. Mark the spec `status: closed` in `specs.yaml`.
+
+The retrospective step is **repealed**, and `RTR-` with it. It was the only thing size `L` decided, and the
+only thing `V19` checked.
 
-- You MUST NOT close a wave with an open distillation row. The whole point of an ephemeral working layer is that
+- You MUST NOT close a spec with an open distillation row. The whole point of an ephemeral working layer is that
   durable truth leaves it first.
-- You MUST NOT reopen a closed wave to add scope. Scope arriving late opens a new wave, or goes through
+- You MUST NOT reopen a closed spec to add scope. Scope arriving late opens a new spec, or goes through
   `wdi-decision` if it invalidates what is already planned.
-- A change invalidating more than 30% of a wave's stories MUST go through `wdi-decision`, not a patch to
-  `waves.yaml`.
+- A change invalidating more than 30% of a spec's tickets MUST go through `wdi-decision`, not a patch to
+  `specs.yaml`.
 - Fast Path work is recorded as `fastpath` with no gates. If an `FR` turns out to be touched, the work MUST stop
-  and be raised to a wave `S`.
+  and be raised to a spec `S`.
 
 ## Red Flags — STOP
 
 - "One reviewer approved, good enough"
-- Judging a step from a chat report instead of the spec's frontmatter `status`
-- Dispatching Step 1 without `Halt after planning.`
-- Editing content inside `<intent-contract>` on the owner's behalf
-- A worker editing `.what/`, `.how/`, or an `applied` `DEC-` to make its code fit
+- Judging Step 1 or Step 2 from a report instead of from the test suite
+- **Counting `/implement`'s own `/code-review` as the panel** — that is the builder reviewing itself
+- Writing `SPEC.md` at size `S`, or skipping it at `M` and up
+- Landing a ticket with no `satisfies` — the RTM chain breaks silently and nothing else notices
+- Amending what a ticket `satisfies` to make a must-fix go away
+- A ticket that slices one layer instead of cutting through all of them, outside a wide refactor
+- Running a wide refactor's batches in parallel
+- Claiming this skill invoked `to-spec`, `to-tickets`, or `implement` — it cannot; the owner runs them
+- A builder editing `.what/`, `.how/`, or an `applied` `DEC-` to make its code fit
 - Fixing a failing test without knowing why it failed
-- Opening a PR with an unresolved must-fix, or before the story-closing checklist is answered
+- Opening a PR with an unresolved must-fix, or before the ticket-closing checklist is answered
 - Editing a guard, a test, or an assertion to turn something green
 - Reporting green without checking the head SHA, or reading green `korpus.yml` as a passing build
-- A reviewer from the same CLI family as the builder
-- Dispatching a worker without its Unattended flag
-- Closing the wave without the registry catch-up in Phase 4 — that is where five checklist items now live
-- Letting `SPEC.md` state something `.what/` and `.how/` do not
+- Leaving a dispatched step able to stall on a question nobody is there to answer
+- Naming an orchestration tool as this skill's requirement, or restating a CLI/model mapping the Agent Rules own
+- Closing the spec without the registry catch-up in Phase 4 — that is where five checklist items now live
+- Letting the contract state something `.what/` and `.how/` do not, or restate it without a reference
 
 **Each of these means: stop, return to the step or phase that owns it, or escalate to the owner.**
 
@@ -238,9 +349,9 @@ Run in this order and stop at the first failure:
 
 MUST follow the Agent Rules `Answer Closing` block, carrying these additions:
 
-- **what was done** — wave, `FR` satisfied, every story with its branch and PR URL, what the code now does
+- **what was done** — spec, `FR` satisfied, every ticket with its branch and PR URL, what the code now does
 - **what blocked it** — every step that looped, every dismissed finding and why, anything left red, and every
   Phase 4 item that did not pass
-- **what comes next** — every finding recorded as follow-up, every entry in a spec's `deferred` list, every
-  story-closing item routed to another skill, and the plan-versus-code inventory differences. A follow-up absent
-  here is a lost finding.
+- **what comes next** — every finding recorded as follow-up, every entry in a contract's `deferred` list, every
+  ticket-closing item routed to another skill, and the plan-versus-code inventory differences. A follow-up
+  absent here is a lost finding.

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

@@ -18,7 +18,7 @@ shape with `mode`, and the only one that runs more than once for a reason other
 This table said `outline` → `behaviour` only until 2026-08-18. It contradicted **Step 4 of this same
 skill**, which starts `Decision Summary` and `Structure` "from `outline`", and it contradicted
 `delivery-flow-guide.md`, which owns the mapping and lists both for `outline`. Read literally, it would
-have left every `outline` component with an SDD that is a template skeleton forever — and V13 would have
+have left every `outline` component with an SDD that is a template skeleton forever — and `review-trace` would have
 been right to keep flagging it.
 
 Read the component's `mode` from its row in `components.yaml`, falling back to `mode:` in `index.yaml`. Read
@@ -67,7 +67,7 @@ None of these are yours to create.
 | Its `mode` is not `catalog` | Stop. G4 is skipped, and the work goes straight to `wdi-build` |
 | G3 has passed | Route to `wdi-blueprint`. Depth written against a moving portrait is rewritten |
 | The spine exists and its `AD-N` are readable | Route to `wdi-blueprint`. You MUST NOT write the spine |
-| For `design`: the container this component runs in is registered | Route to `wdi-blueprint`. An `LC` MUST name its container |
+| For `design`: the container this component runs in is registered | Route to `wdi-blueprint`. G3 has passed by now, so the answer exists — an `LC` written here MUST carry it. Only a screen `LC` born at G2 is allowed an empty one, and G3 fills it |
 
 ## Step 3 — Intent `behaviour`
 
@@ -112,7 +112,7 @@ Write in this order, stopping at whatever the `mode` does not reach:
    a reason where one does not apply. The data model carries a dictionary beside its diagram.
 
 From `guarded` up, every Boundary object MUST become an `LC` in `components.yaml`; at `deep`, Control objects
-too. Registration is checked **when the wave closes** — V12 — not before a story is `ready-for-dev`. You MUST
+too. Registration is checked **when the spec closes** — `lc-registered` — not before a ticket is picked up. You MUST
 NOT register a `container`, and you MUST NOT register `ui-screen` or `ui-composite`.
 
 ## Step 5 — Evidence, and the as-built case
@@ -154,13 +154,15 @@ You MUST NOT open G4 on depth that has not been through it.
 
 ## Rules
 
-- A decision taken while writing MUST go to `wdi-decision`, never into the document as a parenthetical. There
-  is no memlog here to catch it.
+- A decision taken while writing is **written into the document as its own content**, stated as what now
+  holds. Never as a parenthetical aside — there is no memlog here to catch one. It goes to `wdi-decision`
+  only when no design document has a home for it, or it touches an `AD-N`; `decision-guide.md` § A
+  decision's first home owns that split.
 - You MUST NOT write into `.what/_prd/`, `.what/business-rules.md`, `.how/_platform/`, or `.how/<pc>/01-ux/`.
 - You MUST NOT raise `status:`. Status is a stage; the `reviewed:` block is an event.
 - You MUST NOT lower or raise the component's `mode` to fit what you want to write. That is `wdi-init`, and it
   is the owner's call.
-- `bmad-spec` runs **after** this, never before, and it MUST NOT introduce anything these documents do not say.
+- The spec's contract is cut **after** this, never before, and it MUST NOT introduce anything these documents do not say.
 - Memlog: `.control/memlog/<pc>.md`, through `memlog.py --path`. `--workspace` MUST NOT be used.
 - Questions arrive as **one** ranked batch at the gate, not as they surface.