wdi-method 0.6.7 → 0.6.8

package/kit/.constitution/method/document/bmad-skill-register.md

@@ -26,9 +26,11 @@ method does not invoke, ask `bmad-help`, which reads BMad's own documentation.
 | Course correction | `bmad-correct-course` | `wdi-decision` |
 
 **Everything below G5 left this table.** `SPEC.md`, the tickets, the code, and the code panel are produced
-by `to-spec`, `to-tickets`, `implement`, `tdd`, and `code-review` — engines that are not BMad's, and that
-three of the five carry `disable-model-invocation: true` for, so **the owner runs them and no skill can**.
-`wdi-build` owns that pipeline; `bmad-guide.md` owns the reasoning.
+by `to-spec`, `to-tickets`, `implement`, `tdd`, and `code-review` — engines that are not BMad's. Three of
+the five ship with `disable-model-invocation: true`; `wdi-method` strips it from the copies installed in
+this repo and writes a guard line naming who may drive them, so **`wdi-build` and `wdi-autopilot` invoke
+them directly** and an unattended iteration needs nobody. `wdi-build` owns that pipeline;
+`bmad-guide.md` owns the reasoning.
 
 **The three 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 attach to those artifacts and
@@ -50,15 +52,43 @@ A Fast Path that turns out to touch an `FR` MUST stop and become a spec `S`, whi
 |---|---|
 | `bmad-advanced-elicitation` · `bmad-party-mode` | Thinking aids. They produce no artifact and MUST NOT be treated as authors |
 | `bmad-deep-recon` | Research, before a brief rests on outside data. Its output stays in `_bmad-output/` permanently and MUST NOT be folded into the brief |
+| `bmad-qa-generate-e2e-tests` | Tests for a feature that **already exists**. `tdd` is test-first for work being built, so this has no replacement here and is NOT retired — but what it writes is a test, never a contract, and it MUST NOT be read as one |
+| `bmad-checkpoint-preview` | A human reading aid over a change, the same class as `bmad-advanced-elicitation`. It MUST NOT be counted as the Step 3 panel: that one is a separate dispatch by a different agent |
 | `bmad-help` | Questions about BMad itself. It MUST NOT be used to answer "where am I" — that is `wdi-help` |
 
 ## What is NOT USED, and MUST NOT be
 
+**The criterion, and it binds every row below.** A BMad skill is retired only where this method has a
+**named replacement** for what it produces. Without one it is not retired — it goes in the table above
+instead, as something that may be used but MUST NOT author. Banning a capability with nothing in its
+place is how a method gets worked around rather than followed.
+
+### Retired at G5 — enforced by install and update
+
+**This is enforced, not only stated.** `install` and `update` set `disable-model-invocation: true` on
+every wrapper below and add a `Skill(<name>)` deny rule to `.claude/settings.json`, both re-applied on
+every run because BMad's installer rewrites its own wrappers. A person typing `/bmad-build` still gets
+it: the method retires a default, it does not confiscate a tool. The list lives in
+`bin/wdi-method.js` as `BMAD_RETIRED_G5`, and a test fails when this table and that array disagree.
+
+| Skill | Replaced by | Why |
+|---|---|---|
+| `bmad-spec` | `to-spec` | **Retired.** The contract below G5 is no longer BMad's. Its `_bmad/custom/*.toml` override is withdrawn and `update` removes any still installed |
+| `bmad-build` · `bmad-build-auto` | `implement` · `wdi-autopilot` | **Retired.** `bmad-build` describes itself as implementing "any user intent, requirement, story, bug fix or change request" — the most inviting description in the repo's skill index, for the one thing this method owns most tightly. `bmad-build-auto` is an unattended loop, which is `wdi-autopilot`'s |
+| `bmad-code-review` | `code-review` | **Retired.** The panel at Step 3 is a separate dispatch by a different agent; BMad's own review layers are the builder reviewing itself |
+| `bmad-retrospective` | — | **Retired** with `RTR-` and `V19`. A frozen `RTR-` file stays where it is |
+| `bmad-agent-dev` | `implement` | **Retired.** "Senior software engineer for story execution and code implementation" is `implement`'s sentence |
+| `bmad-create-epics-and-stories` | `to-tickets` | **Retired**, and not merely by preference: the `epics` level between a spec and its tickets is **repealed in code** — `validate.py` reads a flat `tickets:` list. A skill whose only output is a shape nothing reads |
+| `bmad-create-story` · `bmad-dev-story` · `bmad-dev-auto` · `bmad-quick-dev` | `implement` | **Retired.** BMad deprecated all four in favour of `bmad-build`, which is itself retired here. An alias to a retired skill is retired |
+| `bmad-sprint-planning` · `bmad-sprint-status` | the ticket itself | **Retired.** The sprint route keeps status in a hand-edited file; this method reads status from the ticket — `bmad-guide.md` owns the reasoning |
+
+### Not used for other reasons — not enforced, and not G5's
+
+These are outside the enforced list above: nothing locks them, because nothing here replaces them and
+none of them competes for G5's work.
+
 | Skill | Why |
 |---|---|
-| `bmad-spec` · `bmad-build` · `bmad-build-auto` · `bmad-code-review` · `bmad-retrospective` | **Retired.** The engine layer below G5 is no longer BMad's. Their `_bmad/custom/*.toml` overrides are withdrawn and `update` removes any still installed |
-| `bmad-create-epics-and-stories` · `bmad-sprint-planning` · `bmad-sprint-status` | They belong to the sprint route, which keeps status in a hand-edited file. This method reads status from the ticket itself — `bmad-guide.md` owns the reasoning |
-| `bmad-create-story` · `bmad-dev-story` · `bmad-quick-dev` · `bmad-dev-auto` | Deprecated in BMad itself, and their replacements are retired too |
 | `bmad-editorial-review*` · `bmad-review-*` | Shims onto `bmad-review` lenses. Ask for the lens, not the shim |
 | `bmad-document-project` · `bmad-generate-project-context` | Forward to `bmad-project-context`. This repo's agent instructions are maintained by hand |
 | Any skill named as a **gate condition** | A gate is passed by its checklist and its validators, never by a skill having run |

package/kit/.constitution/method/scripts/validate.py

@@ -1490,7 +1490,8 @@ def custom_room_declared(c: Corpus, r: Result) -> None:  # was V27
 #
 # The two rendered trees are DELIBERATELY absent from this list. They are regenerated by this
 # script, so a product that declines to commit derived output is making a choice the method allows.
-COMMITTED_DIRS = (".constitution", ".control", ".what", ".how", "_bmad-output", ".work")
+COMMITTED_DIRS = (".constitution", ".control", ".what", ".how", "_bmad-output", ".work",
+                  ".scratch")
 
 # Probed inside each directory above, and named so that no honest pattern would ever mean to match
 # it. The distinction this draws is the entire point of the check: `.work/upstream/` or
@@ -1548,6 +1549,76 @@ def corpus_in_git(c: Corpus, r: Result) -> None:
                    f"so no clone has what is in it")
 
 
+ENGINE_HOMES = (".claude", ".agents", ".agent", ".cursor", ".codex")
+ENGINE_FLAGGED = ("to-spec", "to-tickets", "implement")
+ENGINE_SKILLS = ENGINE_FLAGGED + ("tdd", "code-review", "domain-modeling")
+FLAG_RE = re.compile(r"^disable-model-invocation\s*:\s*true", re.M)
+
+
+def _engine_files(root: Path, name: str) -> list[Path]:
+    """Every copy of one engine, de-duplicated by what it resolves to.
+
+    `npx skills add` can symlink one SKILL.md into several platform folders, so the same file is
+    reachable under `.claude/skills/` and `.agents/skills/` at once. Reporting it twice would make
+    one finding read as two.
+    """
+    seen: dict[Path, Path] = {}
+    for home in ENGINE_HOMES:
+        path = root / home / "skills" / name / "SKILL.md"
+        if not path.is_file():
+            continue
+        try:
+            seen.setdefault(path.resolve(), path)
+        except OSError:
+            seen.setdefault(path, path)
+    return list(seen.values())
+
+
+def _frontmatter(text: str) -> str:
+    m = FM.match(text)
+    return m.group(1) if m else ""
+
+
+def engines_invocable(c: Corpus, r: Result) -> None:
+    """The three flagged engines MUST be invocable in the repo's own copies.
+
+    `to-spec`, `to-tickets` and `implement` ship with `disable-model-invocation: true`. Nothing
+    outside the file lifts it — Claude Code's gate reads the frontmatter and consults no setting,
+    and `skillOverrides` only ever tightens — so `wdi-method` strips the key from the copies the
+    repo owns and writes one guard line in its place. That is what lets `wdi-build` invoke an engine
+    and `wdi-autopilot` run an iteration with nobody watching.
+
+    Two things put the key back, both routine: `npx skills update`, which restores the author's file
+    byte for byte, and a fresh `npx skills add`. Neither says anything, and the failure surfaces
+    hours later as an unattended run that stalled at Phase 2 with no explanation. This is the check
+    that turns that into a line of output.
+
+    Checked in the FRONTMATTER, not the file: the guard line is prose about the key, and matching
+    the whole file would fail on the fix rather than on the defect.
+
+    A repo with no engines at all is SKIPPED, not failed. `--skip-engines-check` is a supported
+    install — CI, and a repo that will never reach G5 — and a validator that is permanently red
+    there is a validator that gets ignored everywhere else.
+    """
+    installed = {name: _engine_files(c.root, name) for name in ENGINE_SKILLS}
+    if not any(installed.values()):
+        r.skip("engines-invocable", "no engines in this repo — G5 cannot run until they are "
+                            "installed (`npx skills@latest add mattpocock/skills`), and until then "
+                            "there is nothing here to check")
+        return
+    for name in ENGINE_SKILLS:
+        if not installed[name]:
+            r.fail("engines-invocable", name, "is not installed in this repo — G5 needs all six, and "
+                              "a user-level plugin does not count: its files are not this repo's to unlock")
+    for name in ENGINE_FLAGGED:
+        for path in installed[name]:
+            if FLAG_RE.search(_frontmatter(path.read_text(encoding="utf-8", errors="replace"))):
+                r.fail("engines-invocable", name,
+                       f"{path.relative_to(c.root).as_posix()} carries `disable-model-invocation` "
+                       f"again — no skill can invoke it, so wdi-build stops at Phase 2. `npx skills "
+                       f"update` restores it; `npx wdi-method engines --fix` strips it back out")
+
+
 def id_allocated_once(c: Corpus, r: Result) -> None:  # was V28
     """One id, one row — across every file the requirement registry is split into.
 
@@ -1582,7 +1653,7 @@ def run_checks(c: Corpus, asof: dt.date) -> Result:
     # no two copies left to compare.
     # V19 is REPEALED. It checked one line item — an `RTR-` file in .control/reports/ — and the
     # retrospective it archived was the only thing spec size `L` ever decided. Both went together.
-    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, id_allocated_once):
+    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, id_allocated_once):
         fn(c, r)
     plan_dates(c, r, asof)
     return r
@@ -1785,7 +1856,7 @@ def gen_status(c: Corpus, rtm: dict, result: Result) -> dict:
         per_spec.append({"spec": wid, "status": spec.get("status"),
                          "tickets_done": done, "tickets_total": len(items),
                          "work_progress": _pct(done, len(items))})
-    applicable = 26  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
+    applicable = 27  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
     return {
         "promise_progress": _pct(green, len(counted)),
         "rtm_rows": {"green": green, "counted": len(counted),

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

@@ -1,186 +1,192 @@
----
-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` |
-
-## Eighteen 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-autopilot` | "Deliver every `FR` and do not ask me in between." A preflight the owner confirms becomes one `DEC-` of `type: mandate`; a loop then fires the skill, and it runs every other skill, decides what they would have asked, and writes each decision to one ledger the owner reviews in parallel |
-| `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.
+---
+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**.
+
+Six engines come from [mattpocock/skills](https://github.com/mattpocock/skills) — `to-spec`,
+`to-tickets`, `implement`, `tdd`, `code-review`, and `domain-modeling` (that last one is G3's, invoked by
+`wdi-blueprint`). They are installed **into the repo**, on any agent:
+`npx skills@latest add mattpocock/skills`. A user-level plugin does not count, and the reason is
+mechanical: three of the six ship with `disable-model-invocation: true`, nothing outside the file lifts
+it, and a plugin's files are not the repo's to edit. `wdi-method` strips it from the repo's own copies so
+`wdi-build` and `wdi-autopilot` can invoke them, and re-applies that on every update because
+`npx skills update` restores the author's file.
+
+You do NOT need `/setup-matt-pocock-skills`: the installer seeds `docs/agents/` already answered for this
+method. G1–G4 run without the engines; `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` |
+
+## Eighteen 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-autopilot` | "Deliver every `FR` and do not ask me in between." A preflight the owner confirms becomes one `DEC-` of `type: mandate`; a loop then fires the skill, and it runs every other skill, decides what they would have asked, and writes each decision to one ledger the owner reviews in parallel |
+| `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

@@ -117,7 +117,7 @@ someone else performs. `../document/corpus-guide.md` holds the binding version o
 | `wdi-blueprint` | `.what/<pc>/` § Actor Register + § UC Catalogue + `03-domain/domain-model.md` · `.what/business-rules.md` · `.control/product-glossary.md` · all of `.how/_platform/` except `design-system.md` |
 | `wdi-component` | `.what/<pc>/` slots `02`–`05` · `.how/<pc>/` except `01-ux/` |
 | `wdi-ux` | `EXPERIENCE.md` · `.how/<pc>/01-ux/` · `.how/_platform/design-system.md` |
-| `wdi-build` | `specs.yaml` · `_bmad-output/specs/` · `src/` · `web/` |
+| `wdi-build` | `specs.yaml` · `.scratch/<spec-id>-<slug>/` · `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` |