wdi-method 0.5.0 → 0.5.3

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

@@ -1,203 +1,203 @@
----
-name: wdi-blueprint
-description: Use at G3 Blueprint — the one whole-product portrait, written once. Two intents, catalog and platform. Owns the use case catalogue, actors, domain model, cross-component business rules, the glossary, the spine, C4, cross-cutting, and the three inventories. Never writes a single component's depth.
----
-
-# WDI Blueprint
-
-G3 decides **the whole portrait of the system**: which use cases exist, their entities, their tables, their
-endpoints, their screens, and the invariants that bind everything built from them. Once per product.
-
-Two intents, run in this order:
-
-| Intent | Writes | Wraps |
-|---|---|---|
-| `catalog` | Per `<pc>`: § Actor Register · § UC Catalogue · `03-domain/domain-model.md`. Product level: `.what/business-rules.md` · `.control/product-glossary.md` · `usecases.yaml` | — |
-| `platform` | `.how/_platform/`: the spine · C4 L1/L2/L3 · `cross-cutting.md` · the three inventories. Registry: `containers` | `bmad-architecture` |
-
-**Blueprint content is untouched by `mode` and by `risk_accepted`.** Everything above exists at every mode,
-including `catalog`. That is what keeps the order non-circular: `mode` is first needed at G4.
-
-You MUST NOT write a single component's depth — full UC flows, local rules, failure behaviour, contracts. All
-of that is `wdi-component` at G4. You MUST NOT write a promise; when the blueprint proves a PRD wrong, that is
-`wdi-product`, not a quiet edit here.
-
-## Inputs
-
-| Source | What it answers |
-|---|---|
-| `.what/_product-brief/brief.md` | The problem, the primary user, the boundary the portrait MUST respect |
-| `.what/_prd/*/prd.md` — **every one** | Every promise made: the `FR`/`NFR` the portrait has to cover |
-| `.control/registry/components.yaml` | Which components exist, and their `owns:` |
-| `.control/product-glossary.md` | Terms already fixed |
-| `.control/decisions/` | `accepted` and `applied` decisions an `AD-N` usually sits behind |
-| `src/` · `web/` | What actually runs, when this is not a new project |
-| `.constitution/method/document/srs-guide.md` · `architecture-guide.md` | The rules the result is checked against |
-
-## Step 1 — Position
-
-- The components MUST already exist. If `components.yaml` holds no `product_components`, route to `wdi-init`
-  intent `component` — the slicing is born at the tail of G2, from the brief plus every PRD.
-- `catalog` runs before `platform`. The spine is written against a portrait that exists.
-- If the spine and C4 set already exist, `platform` is an **amendment**, never a create. A second create
-  overwrites what three waves of annotation put there.
-- If the ask is one component's mechanism or its full flows, route to `wdi-component`.
-- If the ask is what the product promises, route to `wdi-product` — an invariant is not a promise.
-
-## Step 2 — Intent `catalog`, in order
-
-The order is binding, and each step is the input to the next. Writing them out of order produces use cases
-whose nouns nobody defined.
-
-1. **Glossary.** Every domain noun, into `.control/product-glossary.md`, alphabetically, each citing the
-   document and section its definition came from. You MUST NOT invent a definition — cite a source, or route
-   the term to `wdi-question`. Two words meaning one thing is **drift**, and it MUST be resolved to one word
-   in the same pass, with the losing synonym corrected in the documents that use it.
-2. **UC Catalogue**, per component. One line per use case: `UC-N` · title · actor · the `FR` it satisfies ·
-   `critical` yes/no. A title MUST be a sentence a user would say, not a system term.
-3. **Actor Register**, per component. It stays in the SRS kernel; it is the SSOT the SDD mirrors.
-4. **Domain model** — entities, relations, columns — into `.what/<pc>/03-domain/domain-model.md`. Conceptual;
-   database column types belong to `.how/`.
-5. **Cross-component business rules** into `.what/business-rules.md`. A rule binding only one component is
-   G4 work and MUST NOT be written here.
-
-`critical` means the use case touches **money, personal data, or an irreversible action**. Nothing else. If
-the count passes a third of a component's use cases, derive it again — `delivery-flow-guide.md` owns the rule
-and it MUST NOT be negotiated.
-
-**A method term MUST NOT be written into `.constitution/method/method-glossary.md`.** A product term binds one
-project; a method term binds every project the method is installed in. Raise it as a proposal, state where it
-appeared and why the existing vocabulary does not cover it, and hand it to the owner.
-
-## Step 3 — Parallel where there is a key, serial where there is not
-
-This is not theory. In the previous run, 41 cross-component business rules from seven parallel agents had to
-be merged and de-duplicated **serially**, because the target file had no key — and that merge was the most
-expensive part of the pass.
-
-> Parallel fan-out is only for output with a natural key. Output that is a shared list with no key MUST be
-> written by one agent that reads the whole input.
-
-| Work | Parallel? | Key |
-|---|---|---|
-| UC catalogue, actors, entities per component | yes | Product Component |
-| Glossary, cross-component business rules, the spine | **no** | there is none |
-| The three inventories | yes, one agent per source | table · endpoint · screen |
-
-Three guards when running parallel: each agent writes only its own keyed file; shared files are written in one
-serial pass afterwards; the owner reviews the merged result, not N agent reports. Open questions from N agents
-arrive as **one** ranked batch.
-
-## Step 4 — Intent `platform`
-
-Dispatch `bmad-architecture` at **initiative** altitude for the spine. Do not restate the rules to it — they
-arrive through `persistent_facts` in `_bmad/custom/bmad-architecture.toml`, which installs
-`architecture-guide.md` there rather than as `doc_standards` deliberately.
-
-Then verify and land:
-
-| # | Check | Fails when |
-|---|---|---|
-| 1 | Home | The spine landed anywhere but `.how/_platform/ARCHITECTURE-SPINE.md` |
-| 2 | Every `AD-N` carries Binds, Prevents, and Rule | One is blank — an `AD-N` with no Prevents is a preference |
-| 3 | Every `AD-N` is an invariant | Breaking it in one component would not break another. It is a seed, and MUST be marked as one |
-| 4 | Stack, tree, and data shapes marked as seeds | Written as contracts, which makes the spine wrong at the first upgrade |
-| 5 | No alternatives or cost in the spine | Those live in the `DEC-` behind it; a second copy drifts |
-| 6 | Nothing but invariants | A statement affecting one component only — that is its SDD |
-| 7 | Memlog at `.control/memlog/spine.md` | A `.memlog.md` appeared inside `.how/` — `--workspace` was used |
-
-Check 7 MUST be fixed immediately. V16 rejects a memlog inside the corpus.
-
-**Land the C4 set by amending, never overwriting.** The files are living and already carry annotations,
-including a pre-method provenance note that MUST survive. When the incoming set contradicts an annotation
-already there, you MUST stop and report it, and MUST NOT resolve it by preferring the newer drawing. Where a
-C4 file and the spine disagree, the spine wins and the disagreement MUST be reported. One
-`c4-l3-<container>.md` per `built: true` container **holding more than one Product Component**. A
-`built: false` container gets no L3 at all, and a one-PC container needs none because the L2 matrix already
-places it. **Not one of the three waits for a wave** — `architecture-guide.md` owns that.
-
-**Register the containers** in `containers:` in `components.yaml`, in the same act as landing the L2. It is
-not a follow-up, and it unblocks everyone else: an `LC` MUST name its container.
-
-Each container MUST carry `built:` — `true` when we write what is inside it, `false` when we deploy
-someone else's implementation. It decides whether the container gets an L3, an `LC`, and a heading in the
-codebase map (V25). Something whose **runtime we do not deploy** is an external system: it belongs at L1,
-and registering it here promises a codebase-map section that will never exist.
-
-**Fill each PC's `containers:` in the same act, and land the matrix at L2** — the registry is the SSOT and
-the L2 table renders it. A PC MUST list every `built: true` container it lives in; listing only the main
-one is the error the matrix exists to catch. Complete for every PC at G3, untouched by `mode`.
-
-You MUST NOT register a
-`product_component` or a `logical_component`.
-
-**Register what `_platform` owns** in the same pass — a domain entity through `platform_owns`, an inventory
-row through that inventory's `platform_rows:`, an `LC` through its `component:`. The test is in
-`corpus-guide.md` and both halves MUST hold. Each one MUST then be described under `## Milik platform` in
-`cross-cutting.md`, in the same act: V21 checks that second half, because owning something without
-documenting it is taking ownership without taking responsibility.
-
-A judgement the pattern cannot derive MUST live in the artifact it governs, not in a script and not in a
-skill: an inventory's `platform_rows:` and `states:` are declared in that inventory's own frontmatter, so
-re-derivation preserves them. Anywhere else, the next run deletes the owner's decision.
-
-`_platform` is **not** a Product Component. You MUST NOT give it a `mode`, a `risk_accepted`, an SRS, or a
-G4, and you MUST NOT move an entity there because its owner is hard to decide.
-
-## Step 5 — The three inventories
-
-They land in `.how/_platform/` with **one owner: this skill.** No negotiation with `wdi-ux`, and no second
-copy inside any SDD.
-
-| State | How each is born |
-|---|---|
-| No code yet | Written as a **plan** — the tables, endpoints, and screens intended. Nothing can be derived, because there is no source |
-| Code exists | **Derived first** by `.constitution/method/scripts/inventory.py` — migrations for tables, route registration for endpoints, pages for screens — then compared with the plan. The difference is a **finding**, not hand work |
-
-An inventory MUST NOT be assembled from a README or from route names that look plausible. Numbers are stable:
-a new row takes the next number, never a renumber.
-
-## Step 6 — The roll-up, and what the owner actually reads
-
-Regenerate `.control/generated/blueprint.md` with `validate.py --generate`. It assembles the UC catalogue, the
-actor lists, the domain model, and the three inventories into **one page**.
-
-**That page is what G3 reviews** — not seven files. The catalogue and actors stay in their component kernels as
-their permanent home; the roll-up is a view. One fact, one home, one view.
-
-You MUST NOT hand-write anything under `.control/generated/`.
-
-## Step 7 — Review and questions
-
-- No `doc_standards` fires for an SRS or for the spine. Dispatch `wdi-review`, which reads the lens set from
-  each component's `risk_accepted`.
-- You MUST NOT open G3 on a portrait that has not been through it.
-- Every unresolved to-be-confirmed MUST be filed through `wdi-question`, in **one** ranked batch — into
-  `assumptions.md` by default, `blocking.md` only through its three tests.
-- A decision surfacing while writing goes to `wdi-decision`, never into the document as a parenthetical.
-- An `AD-N` that reverses or narrows an earlier one MUST go through `wdi-decision` first. Editing an `AD-N` in
-  place is how a reversal happens with nobody deciding it.
-
-## Step 8 — A PRD that arrives after G3
-
-The blueprint is **living and amended**, not repeated. `wdi-init` intent `component` births the new
-components, this skill adds their rows to the catalogue and the three inventories, and **G3 reopens over the
-delta only**. The 45-minute session does not run again for one additional initiative.
-
-## Rules
-
-- You MUST NOT write into `.how/<pc>/`, and `design-system.md` in `_platform/` belongs to `wdi-ux`.
-- You MUST NOT regenerate the C4 set from scratch. The loss of annotations is invisible in a diff that reads
-  as a rewrite.
-- You MUST NOT raise `status:`. Status is a stage; the `reviewed:` block is an event.
-- You MUST NOT write a definition into `.constitution/` at all — not the method glossary, not a guide.
-- When the portrait cannot be drawn because a PRD has not settled what it must cover, say so and stop.
-- Memlog: one per Product Component at `.control/memlog/<pc>.md`, plus `.control/memlog/spine.md` for
-  `platform`, through `memlog.py --path`. `--workspace` MUST NOT be used.
-
-## Output
-
-Intents run · the catalogue and inventories as counts, per component · glossary terms written, proposed, and
-rejected with the rule that rejected each · the `AD-N` that are new or changed · what was amended in the C4
-set and what contradicted it · containers registered · plan-versus-code differences reported · whether the
-roll-up regenerated and `wdi-review` ran · the one ranked batch of questions.
+---
+name: wdi-blueprint
+description: Use at G3 Blueprint — the one whole-product portrait, written once. Two intents, catalog and platform. Owns the use case catalogue, actors, domain model, cross-component business rules, the glossary, the spine, C4, cross-cutting, and the three inventories. Never writes a single component's depth.
+---
+
+# WDI Blueprint
+
+G3 decides **the whole portrait of the system**: which use cases exist, their entities, their tables, their
+endpoints, their screens, and the invariants that bind everything built from them. Once per product.
+
+Two intents, run in this order:
+
+| Intent | Writes | Wraps |
+|---|---|---|
+| `catalog` | Per `<pc>`: § Actor Register · § UC Catalogue · `03-domain/domain-model.md`. Product level: `.what/business-rules.md` · `.control/product-glossary.md` · `usecases.yaml` | — |
+| `platform` | `.how/_platform/`: the spine · C4 L1/L2/L3 · `cross-cutting.md` · the three inventories. Registry: `containers` | `bmad-architecture` |
+
+**Blueprint content is untouched by `mode` and by `risk_accepted`.** Everything above exists at every mode,
+including `catalog`. That is what keeps the order non-circular: `mode` is first needed at G4.
+
+You MUST NOT write a single component's depth — full UC flows, local rules, failure behaviour, contracts. All
+of that is `wdi-component` at G4. You MUST NOT write a promise; when the blueprint proves a PRD wrong, that is
+`wdi-product`, not a quiet edit here.
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| `.what/_product-brief/brief.md` | The problem, the primary user, the boundary the portrait MUST respect |
+| `.what/_prd/*/prd.md` — **every one** | Every promise made: the `FR`/`NFR` the portrait has to cover |
+| `.control/registry/components.yaml` | Which components exist, and their `owns:` |
+| `.control/product-glossary.md` | Terms already fixed |
+| `.control/decisions/` | `accepted` and `applied` decisions an `AD-N` usually sits behind |
+| `src/` · `web/` | What actually runs, when this is not a new project |
+| `.constitution/method/document/srs-guide.md` · `architecture-guide.md` | The rules the result is checked against |
+
+## Step 1 — Position
+
+- The components MUST already exist. If `components.yaml` holds no `product_components`, route to `wdi-init`
+  intent `component` — the slicing is born at the tail of G2, from the brief plus every PRD.
+- `catalog` runs before `platform`. The spine is written against a portrait that exists.
+- If the spine and C4 set already exist, `platform` is an **amendment**, never a create. A second create
+  overwrites what three waves of annotation put there.
+- If the ask is one component's mechanism or its full flows, route to `wdi-component`.
+- If the ask is what the product promises, route to `wdi-product` — an invariant is not a promise.
+
+## Step 2 — Intent `catalog`, in order
+
+The order is binding, and each step is the input to the next. Writing them out of order produces use cases
+whose nouns nobody defined.
+
+1. **Glossary.** Every domain noun, into `.control/product-glossary.md`, alphabetically, each citing the
+   document and section its definition came from. You MUST NOT invent a definition — cite a source, or route
+   the term to `wdi-question`. Two words meaning one thing is **drift**, and it MUST be resolved to one word
+   in the same pass, with the losing synonym corrected in the documents that use it.
+2. **UC Catalogue**, per component. One line per use case: `UC-N` · title · actor · the `FR` it satisfies ·
+   `critical` yes/no. A title MUST be a sentence a user would say, not a system term.
+3. **Actor Register**, per component. It stays in the SRS kernel; it is the SSOT the SDD mirrors.
+4. **Domain model** — entities, relations, columns — into `.what/<pc>/03-domain/domain-model.md`. Conceptual;
+   database column types belong to `.how/`.
+5. **Cross-component business rules** into `.what/business-rules.md`. A rule binding only one component is
+   G4 work and MUST NOT be written here.
+
+`critical` means the use case touches **money, personal data, or an irreversible action**. Nothing else. If
+the count passes a third of a component's use cases, derive it again — `delivery-flow-guide.md` owns the rule
+and it MUST NOT be negotiated.
+
+**A method term MUST NOT be written into `.constitution/method/method-glossary.md`.** A product term binds one
+project; a method term binds every project the method is installed in. Raise it as a proposal, state where it
+appeared and why the existing vocabulary does not cover it, and hand it to the owner.
+
+## Step 3 — Parallel where there is a key, serial where there is not
+
+This is not theory. In the previous run, 41 cross-component business rules from seven parallel agents had to
+be merged and de-duplicated **serially**, because the target file had no key — and that merge was the most
+expensive part of the pass.
+
+> Parallel fan-out is only for output with a natural key. Output that is a shared list with no key MUST be
+> written by one agent that reads the whole input.
+
+| Work | Parallel? | Key |
+|---|---|---|
+| UC catalogue, actors, entities per component | yes | Product Component |
+| Glossary, cross-component business rules, the spine | **no** | there is none |
+| The three inventories | yes, one agent per source | table · endpoint · screen |
+
+Three guards when running parallel: each agent writes only its own keyed file; shared files are written in one
+serial pass afterwards; the owner reviews the merged result, not N agent reports. Open questions from N agents
+arrive as **one** ranked batch.
+
+## Step 4 — Intent `platform`
+
+Dispatch `bmad-architecture` at **initiative** altitude for the spine. Do not restate the rules to it — they
+arrive through `persistent_facts` in `_bmad/custom/bmad-architecture.toml`, which installs
+`architecture-guide.md` there rather than as `doc_standards` deliberately.
+
+Then verify and land:
+
+| # | Check | Fails when |
+|---|---|---|
+| 1 | Home | The spine landed anywhere but `.how/_platform/ARCHITECTURE-SPINE.md` |
+| 2 | Every `AD-N` carries Binds, Prevents, and Rule | One is blank — an `AD-N` with no Prevents is a preference |
+| 3 | Every `AD-N` is an invariant | Breaking it in one component would not break another. It is a seed, and MUST be marked as one |
+| 4 | Stack, tree, and data shapes marked as seeds | Written as contracts, which makes the spine wrong at the first upgrade |
+| 5 | No alternatives or cost in the spine | Those live in the `DEC-` behind it; a second copy drifts |
+| 6 | Nothing but invariants | A statement affecting one component only — that is its SDD |
+| 7 | Memlog at `.control/memlog/spine.md` | A `.memlog.md` appeared inside `.how/` — `--workspace` was used |
+
+Check 7 MUST be fixed immediately. V16 rejects a memlog inside the corpus.
+
+**Land the C4 set by amending, never overwriting.** The files are living and already carry annotations,
+including a pre-method provenance note that MUST survive. When the incoming set contradicts an annotation
+already there, you MUST stop and report it, and MUST NOT resolve it by preferring the newer drawing. Where a
+C4 file and the spine disagree, the spine wins and the disagreement MUST be reported. One
+`c4-l3-<container>.md` per `built: true` container **holding more than one Product Component**. A
+`built: false` container gets no L3 at all, and a one-PC container needs none because the L2 matrix already
+places it. **Not one of the three waits for a wave** — `architecture-guide.md` owns that.
+
+**Register the containers** in `containers:` in `components.yaml`, in the same act as landing the L2. It is
+not a follow-up, and it unblocks everyone else: an `LC` MUST name its container.
+
+Each container MUST carry `built:` — `true` when we write what is inside it, `false` when we deploy
+someone else's implementation. It decides whether the container gets an L3, an `LC`, and a heading in the
+codebase map (V25). Something whose **runtime we do not deploy** is an external system: it belongs at L1,
+and registering it here promises a codebase-map section that will never exist.
+
+**Fill each PC's `containers:` in the same act, and land the matrix at L2** — the registry is the SSOT and
+the L2 table renders it. A PC MUST list every `built: true` container it lives in; listing only the main
+one is the error the matrix exists to catch. Complete for every PC at G3, untouched by `mode`.
+
+You MUST NOT register a
+`product_component` or a `logical_component`.
+
+**Register what `_platform` owns** in the same pass — a domain entity through `platform_owns`, an inventory
+row through that inventory's `platform_rows:`, an `LC` through its `component:`. The test is in
+`corpus-guide.md` and both halves MUST hold. Each one MUST then be described under `## Platform-owned` in
+`cross-cutting.md`, in the same act: V21 checks that second half, because owning something without
+documenting it is taking ownership without taking responsibility.
+
+A judgement the pattern cannot derive MUST live in the artifact it governs, not in a script and not in a
+skill: an inventory's `platform_rows:` and `states:` are declared in that inventory's own frontmatter, so
+re-derivation preserves them. Anywhere else, the next run deletes the owner's decision.
+
+`_platform` is **not** a Product Component. You MUST NOT give it a `mode`, a `risk_accepted`, an SRS, or a
+G4, and you MUST NOT move an entity there because its owner is hard to decide.
+
+## Step 5 — The three inventories
+
+They land in `.how/_platform/` with **one owner: this skill.** No negotiation with `wdi-ux`, and no second
+copy inside any SDD.
+
+| State | How each is born |
+|---|---|
+| No code yet | Written as a **plan** — the tables, endpoints, and screens intended. Nothing can be derived, because there is no source |
+| Code exists | **Derived first** by `.constitution/method/scripts/inventory.py` — migrations for tables, route registration for endpoints, pages for screens — then compared with the plan. The difference is a **finding**, not hand work |
+
+An inventory MUST NOT be assembled from a README or from route names that look plausible. Numbers are stable:
+a new row takes the next number, never a renumber.
+
+## Step 6 — The roll-up, and what the owner actually reads
+
+Regenerate `.control/generated/blueprint.md` with `validate.py --generate`. It assembles the UC catalogue, the
+actor lists, the domain model, and the three inventories into **one page**.
+
+**That page is what G3 reviews** — not seven files. The catalogue and actors stay in their component kernels as
+their permanent home; the roll-up is a view. One fact, one home, one view.
+
+You MUST NOT hand-write anything under `.control/generated/`.
+
+## Step 7 — Review and questions
+
+- No `doc_standards` fires for an SRS or for the spine. Dispatch `wdi-review`, which reads the lens set from
+  each component's `risk_accepted`.
+- You MUST NOT open G3 on a portrait that has not been through it.
+- Every unresolved to-be-confirmed MUST be filed through `wdi-question`, in **one** ranked batch — into
+  `assumptions.md` by default, `blocking.md` only through its three tests.
+- A decision surfacing while writing goes to `wdi-decision`, never into the document as a parenthetical.
+- An `AD-N` that reverses or narrows an earlier one MUST go through `wdi-decision` first. Editing an `AD-N` in
+  place is how a reversal happens with nobody deciding it.
+
+## Step 8 — A PRD that arrives after G3
+
+The blueprint is **living and amended**, not repeated. `wdi-init` intent `component` births the new
+components, this skill adds their rows to the catalogue and the three inventories, and **G3 reopens over the
+delta only**. The 45-minute session does not run again for one additional initiative.
+
+## Rules
+
+- You MUST NOT write into `.how/<pc>/`, and `design-system.md` in `_platform/` belongs to `wdi-ux`.
+- You MUST NOT regenerate the C4 set from scratch. The loss of annotations is invisible in a diff that reads
+  as a rewrite.
+- You MUST NOT raise `status:`. Status is a stage; the `reviewed:` block is an event.
+- You MUST NOT write a definition into `.constitution/` at all — not the method glossary, not a guide.
+- When the portrait cannot be drawn because a PRD has not settled what it must cover, say so and stop.
+- Memlog: one per Product Component at `.control/memlog/<pc>.md`, plus `.control/memlog/spine.md` for
+  `platform`, through `memlog.py --path`. `--workspace` MUST NOT be used.
+
+## Output
+
+Intents run · the catalogue and inventories as counts, per component · glossary terms written, proposed, and
+rejected with the rule that rejected each · the `AD-N` that are new or changed · what was amended in the C4
+set and what contradicted it · containers registered · plan-versus-code differences reported · whether the
+roll-up regenerated and `wdi-review` ran · the one ranked batch of questions.

package/kit-overlay/AGENTS.md

@@ -72,9 +72,9 @@ Read this instead of reasoning about what `.what/` and `.how/` mean.
 
 | The thing in your hand | Its folder |
 |---|---|
-| A rule, a guide, a template — how we work | `.constitution/` |
+| A rule, a guide, a template — how we work | `.constitution/method/` — **overwritten in full by `update`** |
 | A rule that binds **only this product** | `.constitution/project/` — `update` never writes over it, `promote` never publishes it |
-| The explanation of a rule, never a rule itself | `.constitution/method/` |
+| The explanation of a rule, never a rule itself | `.constitution/method/why/` |
 | A decision, an open question, a registry, a structure map, minutes | `.control/` |
 | The brief, a PRD, a use case, a business rule — what is promised | `.what/` |
 | The spine, C4, an inventory, an SDD, a contract — how it is built | `.how/` |
@@ -94,7 +94,7 @@ Read this instead of reasoning about what `.what/` and `.how/` mean.
 | `.work/` | Scratch; emptied when a task closes | Secrets, commercial figures, anything meant as authority |
 
 The placement test: **is this file still correct after its wave has passed?** Yes → the corpus. No →
-`_bmad-output/`. In doubt → `document/corpus-guide.md`.
+`_bmad-output/`. In doubt → `.constitution/method/document/corpus-guide.md`.
 
 The method does not use a `docs/` layer for corpus or rules. A leftover `docs/` folder is inventory
 to sort, not a second home.
@@ -109,7 +109,8 @@ to sort, not a second home.
 Per-component `mode` wins over global, and there is no third scope — `mode` MUST NOT be overridden per
 wave or per `SPEC.md`. A component at `mode: catalog` **skips G4 entirely**. Neither field MUST be
 derived from the other: one component MAY be thin on purpose and reviewed the hardest.
-`document/delivery-flow-guide.md` owns both; `method/rationale.md` says why they are separate.
+`.constitution/method/document/delivery-flow-guide.md` owns both;
+`.constitution/method/why/rationale.md` says why they are separate.
 
 ## The five gates and the fifteen skills
 
@@ -142,9 +143,10 @@ verifies the result, and lands the memlog.
   re-derives them.
 - A `DEC-` with status `applied` MUST NOT be edited, except to record its supersession — status moves
   to `superseded` and names its replacement. A change of mind produces a new `DEC-`.
-- A file in `.constitution/method/` MUST NOT be cited as the reason to reject a change. It is
+- A file in `.constitution/method/why/` MUST NOT be cited as the reason to reject a change. It is
   `status: Reference` — it explains, it does not bind, and where it disagrees with a guide the guide
-  wins and the disagreement is a defect.
+  wins and the disagreement is a defect. This covers `why/` ONLY: a guide in
+  `.constitution/method/document/` is `status: Accepted` and it binds.
 - More than the component's `mode` demands MUST NOT be written. Exceeding the depth the owner set is
   not diligence.
 - `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on every BMad update;
@@ -165,7 +167,7 @@ verifies the result, and lands the memlog.
 | Naming anything — a code identifier, a file, a database column | `.constitution/method/language-guide.md` |
 | Asking "which gate now, what next" | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-help` |
 | Setting or changing `mode` or `risk_accepted` | `.constitution/method/document/delivery-flow-guide.md` · skill `wdi-init` |
-| Invoking a BMad skill | `.constitution/method/document/bmad-guide.md` · `document/bmad-skill-register.md` |
+| Invoking a BMad skill | `.constitution/method/document/bmad-guide.md` · `.constitution/method/document/bmad-skill-register.md` |
 | Writing or reviewing a product brief | `.constitution/method/document/brief-guide.md` |
 | Writing or reviewing a PRD | `.constitution/method/document/prd-guide.md` |
 | Writing or reviewing UX | `.constitution/method/document/ux-guide.md` |
@@ -176,13 +178,15 @@ verifies the result, and lands the memlog.
 | Writing or reading a structure map | `.constitution/method/structure-guide.md` |
 | Looking for where code lives, or placing new code | `.control/structure-codebase.md` |
 | Looking for where a document lives | `.control/structure-document.md` |
-| Writing or reviewing code | `.constitution/project/codebase-stack-guide.md` · `conventions-guide.md` · `brownfield-guide.md` |
+| Writing or reviewing code | `.constitution/project/codebase-stack-guide.md` · `.constitution/project/codebase-conventions-guide.md` · `.constitution/project/codebase-brownfield-guide.md` |
 
 All three `.constitution/project/codebase-*-guide.md` start as `status: Draft`. While they are, their contents MAY be read
 as guidance but MUST NOT be used to reject a change.
 
 The two structure maps MUST NOT be installed as `doc_standards` — they are facts, not standards. Nor
-MUST anything in `.constitution/method/`; `status: Reference` forbids it.
+MUST anything in `.constitution/method/why/`; `status: Reference` forbids it. A guide in
+`.constitution/method/document/` MAY be installed that way, and several already are — see
+`_bmad/custom/bmad-prd.toml`.
 
 ## Bugs, decisions, questions
 

package/kit-overlay/portability.md

@@ -22,7 +22,7 @@ them only an *example* does — not a rule.
 
 | File | What is this product's | What to do when carrying it |
 |---|---|---|
-| `../constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 travel unchanged. `wdi-method promote` already replaces this file with the kit template |
+| `../../project/constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 travel unchanged. `wdi-method promote` already replaces this file with the kit template |
 | `../document/architecture-guide.md` | Seed examples of stack and tree shape | Re-point the examples. Every rule around them travels |
 | `../document/corpus-guide.md` | Worked examples of `_platform` ownership | Re-point the examples. **Keep both kinds**: they teach the trap better than the rule alone |
 | `templates/design-system.md` | The pointer to wherever this project keeps its tokens | Re-point at that project's token file |
@@ -75,7 +75,7 @@ the steps that a runbook used to carry are now `wdi-init` intent `setup`. The or
 
 1. `npx bmad-method install` in the product repo.
 2. `npx wdi-method install` (optionally `--agents …`).
-3. Set `product.name` in `.control/registry/index.yaml`. Rewrite `../constitution.md` Articles 2 and 5.
+3. Set `product.name` in `.control/registry/index.yaml`. Rewrite `../../project/constitution.md` Articles 2 and 5.
 4. Merge the method routing into `AGENTS.md` if that file already existed.
 5. Run `wdi-init` intent `setup`.
 6. Sort what already existed. A file that is already the artifact one slot asks for goes into that

package/kit-overlay/repo-guide.md

@@ -96,6 +96,14 @@ Everything in the room is yours: `project/constitution.md` (Articles 1, 2, 5),
 `project/codebase-*-guide.md` (stack, conventions, brownfield — protected at **any** `status:`,
 including `Draft`, which is when they are actually written), and any rule file you add.
 
+**A file this product adds belongs in `project/`.** `.constitution/` holds two folders and nothing
+else the method knows about, so a loose `.md` at its root is in a state no rule describes: `update`
+leaves it (it is not the method's) and no guide names it. Migration deliberately does NOT move one —
+it may already be pointed at by its current path from `AGENTS.md` or an editor rule the installer
+cannot see — so it prints the filename and leaves the choice to you. Either move it into `project/`
+and fix those pointers, or name it from Article 2 so the next reader knows why it is there. Leaving
+it unnamed is the only wrong answer.
+
 The seam is the **folder**, never a marked region inside a generic file. `AGENTS.md` uses a marked
 block because it is one file with no alternative; `.constitution/` has fifty-odd, and blocks inside
 them would make every update perform surgery in every file. Prose has no merge algebra — only a path

package/package.json

@@ -1,37 +1,43 @@
-{
-  "name": "wdi-method",
-  "version": "0.5.0",
-  "description": "WDI Method — software delivery method that wraps BMad",
-  "type": "module",
-  "bin": {
-    "wdi-method": "bin/wdi-method.js"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "kit/",
-    "kit-overlay/",
-    "scaffold/",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "test": "node --test tests/*.test.mjs",
-    "prepublishOnly": "node --test tests/*.test.mjs"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.11.0"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wiradigitalid/wdi-method.git"
-  },
-  "bugs": {
-    "url": "https://github.com/wiradigitalid/wdi-method/issues"
-  },
-  "homepage": "https://github.com/wiradigitalid/wdi-method#readme"
-}
+{
+  "name": "wdi-method",
+  "version": "0.5.3",
+  "description": "WDI Method — software delivery method that wraps BMad",
+  "type": "module",
+  "bin": {
+    "wdi-method": "bin/wdi-method.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "kit/",
+    "kit-overlay/",
+    "scaffold/",
+    "README.md",
+    "LICENSE",
+    "!**/__pycache__",
+    "!**/*.pyc"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "prepublishOnly": "node --test tests/*.test.mjs",
+    "overlay": "node scripts/apply-overlay.mjs",
+    "pretest": "node scripts/apply-overlay.mjs && node scripts/clean-kit.mjs",
+    "prepack": "node scripts/clean-kit.mjs",
+    "clean": "node scripts/clean-kit.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wiradigitalid/wdi-method.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wiradigitalid/wdi-method/issues"
+  },
+  "homepage": "https://github.com/wiradigitalid/wdi-method#readme"
+}

package/scaffold/.control/questions/blocking.md

@@ -3,7 +3,7 @@
 **Loaded when:** every gate.
 
 Only this file holds a gate. Written through `wdi-question`, never by hand directly; the row shape
-lives in `.constitution/document/templates/questions.md`.
+lives in `.constitution/method/document/templates/questions.md`.
 
 Target **<=3 rows per Product Component**. A question rises to here only through three tests, one is
 enough: