wdi-method 0.6.6 → 0.6.8

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` |