wdi-method 0.4.5 → 0.5.0

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

@@ -1,145 +1,145 @@
----
-name: wdi-ux
-description: Use when UX is produced or landed — dispatching bmad-ux for a PRD scope, then landing DESIGN.md, EXPERIENCE.md, the design system, and the screen registry into the layers they belong to. Optional, and it rides on G2. Never writes UX content itself.
----
-
-# WDI UX
-
-`bmad-ux` writes the UX. This skill decides whether it should run, hands it the scope, checks what
-came back, and — because `bmad-ux` is **class B** — lands its output into the two layers it splits
-across. No other skill MAY land these files.
-
-Two acts, and a pass MAY do either or both: **run** the UX, and **land** it. They are separated because
-they become possible at different moments. A run belongs to G2, where the PRD is fresh. Landing needs a
-Product Component to land into, and that list is not born until the tail of G2.
-
-You MUST NOT write or edit `DESIGN.md` or `EXPERIENCE.md` yourself. If a check fails, name what is
-missing and re-dispatch — a hand-patched UX document makes the memlog lie about how it got that way.
-The content rules are in `ux-guide.md` and MUST NOT be restated here.
-
-## Inputs
-
-| Source | What it answers |
-|---|---|
-| `.what/_prd/<initiative>/prd.md` | The promises the UX has to make usable — `FR`, `NFR`, `UJ-N` |
-| `.what/_product-brief/brief.md` | The primary user, and the boundary the UX MUST respect |
-| `.constitution/document/ux-guide.md` | The rules the result is checked against |
-| `.constitution/document/templates/ux.md` | The required shape of each half |
-| `.control/registry/components.yaml` | Whether the Product Components and containers a landing needs exist |
-| `.constitution/document/templates/design-system.md` | The shape of the product-level tokens file |
-| `.control/product-glossary.md` | Terms already fixed, so the screens do not invent competing ones |
-| `_bmad-output/ux/` | An earlier run — the input to *land*, and to intent *update* |
-| `.how/_platform/design-system.md` | Tokens and base components already agreed |
-
-## Step 1 — Position
-
-- UX is **optional**. It earns a run when the interface is a substantial part of what the PRD
-  promises; it MUST NOT be run to fill a slot. Say so and stop when a run buys nothing.
-- The order is `wdi-product` → `wdi-ux`. A UX run with no PRD in scope is designing a promise nobody
-  made; route to `wdi-product` first.
-- If the ask is a new capability rather than how an agreed one feels, this is the wrong skill — route
-  to `wdi-product` intent `update`.
-- If the ask is how the system behaves internally, route to `wdi-blueprint` for the catalogue, or
-  `wdi-component` for a full flow.
-
-## Step 2 — Mode
-
-Read `_bmad-output/ux/` and `components.yaml`, then state the mode in one line before acting.
-
-| State | Mode |
-|---|---|
-| No run for this scope | **run** — Step 3, then Step 5 for whatever is landable |
-| A run exists, finalised, nothing landed | **land** — Step 5 only |
-| A run exists and the PRD has changed under it | **run** intent *update*, then Step 5 |
-| A run exists, landed, and a `<pc>` has since been born | **land** — the deferred half, Step 5 |
-
-## Step 3 — Dispatch
-
-Invoke `bmad-ux` with the detected intent. Do not restate the rules to it — they arrive through
-`doc_standards` and `persistent_facts` in `_bmad/custom/bmad-ux.toml`, and a second copy here would
-drift.
-
-State the scope as **one PRD initiative**, and name the input files explicitly; the skill globs its
-own default locations, which this project redirects. A scope spanning several initiatives MUST be
-split into one run each — the run folder is a singleton per scope, and two initiatives in one folder
-cannot be landed separately later.
-
-## Step 4 — Verify
-
-Check what came back against the guide. Report every failure; fix none of them by hand.
-
-| # | Check | Fails when |
-|---|---|---|
-| 1 | Landing zone | Anything was written into `.what/` or `.how/` by the run itself |
-| 2 | Two documents, split correctly | A layout, component, or token sits in `EXPERIENCE.md`; a promise sits first in `DESIGN.md` |
-| 3 | Journeys reference `UJ-N` | The PRD's journeys were restated under new names |
-| 4 | Every screen has an empty and an error state | Only the populated state was designed |
-| 5 | Every user-facing noun is in the glossary | A new noun appeared — route it through `wdi-blueprint`, which owns the glossary, in this pass |
-| 6 | No new capability | The run designed something no `FR` promises — route to `wdi-product`, and MUST NOT land it |
-| 7 | Every `[ASSUMPTION]` filed | An assumption sits in the text with nothing in `.control/questions/` behind it |
-| 8 | Memlog at `.control/memlog/ux.md` | A `.memlog.md` appeared inside the corpus — `--workspace` was used |
-| 9 | `bmad-review` structure + prose ran at finalize | `doc_standards` did not fire |
-
-Check 8 is the one that MUST be fixed immediately rather than reported. A `.memlog.md` inside `.what/`
-or `.how/` is corpus pollution, and V16 rejects it.
-
-## Step 5 — Land, at two speeds
-
-Nothing is landed until the run is finalised. The homes are in `corpus-guide.md`; what is decided
-here is **when each one becomes possible**.
-
-| Output | Lands into | Possible once |
-|---|---|---|
-| Tokens and base components | `.how/_platform/design-system.md` | The run is final — it crosses components by definition |
-| `EXPERIENCE.md` | `.what/<pc>/04-usecases/` | The `<pc>` is registered in `components.yaml` |
-| `DESIGN.md` | `.how/<pc>/01-ux/` | The `<pc>` is registered **and** its container exists |
-| Each screen | an `LC` of type `ui-screen` in `components.yaml` | Same as `DESIGN.md` — an `LC` MUST name its container. Registration is checked at wave close, V12 |
-
-- A half that is not yet landable MUST stay in `_bmad-output/ux/` and be reported as deferred. At G2
-  that is the normal outcome, not a failure: the slicing is born at the tail of G2 and containers at G3.
-- You MUST NOT create a Product Component or a container to make a landing possible. A PC comes from
-  `wdi-init` intent `component` and a container from `wdi-blueprint` intent `platform`.
-- One run MAY land across several Product Components. Split by which `<pc>` the content serves; a
-  screen whose `<pc>` is ambiguous MUST be raised through `wdi-question`, not assigned by guess.
-- Registering the screens is part of landing `DESIGN.md`, in the same act. A screen in `01-ux/`
-  without its `components.yaml` entry has been half-landed, and V12 catches it at a worse moment.
-- `.how/_platform/` otherwise belongs to `wdi-blueprint`. `design-system.md` is the one file in it you
-  own, and it has its own template; you MUST NOT touch any other.
-- The run folder MUST NOT be deleted after landing. Intent *update* reads it again.
-
-## Step 6 — Impact
-
-A landed UX changes what other documents can still claim. Check, and **report** — never edit.
-
-| Found | Where it goes |
-|---|---|
-| A flow the PRD does not promise | `wdi-product` intent `update`, before it is designed |
-| A behaviour the SRS never stated | `wdi-blueprint` for a catalogue line, `wdi-component` for a flow |
-| A pattern that forces a technology choice | `wdi-decision` — a `DEC-`, not a note in `DESIGN.md` |
-| A screen contradicting an `applied` `DEC-` | `wdi-decision` — a new `DEC-`, never an edit to one already applied |
-
-`wdi-reconcile` is the read-only sweep across all layers. Run it rather than reimplementing it.
-
-## Step 7 — Memlog
-
-Everything in a UX pass — the run and the landing — logs to `.control/memlog/ux.md`, through
-`memlog.py --path`. `--workspace` MUST NOT be used.
-
-## Rules
-
-- Content MUST NOT be edited while it is being landed. Splitting one document across the homes its
-  row names is not editing; changing a sentence to fit its new home is, and it goes back through
-  `bmad-ux`.
-- You MUST NOT open G2 on UX that has not been through check 9. Gate time is for deciding.
-- You MUST NOT raise `status:` as part of landing. Status is a stage; the `reviewed:` block is an
-  event, and `wdi-review` writes it.
-- You MUST NOT land anything into a wave that is already closed. The wave is reopened through
-  `wdi-build`, or the gap is filed through `wdi-question`.
-- When the UX concludes the PRD promised something that cannot be made usable, say so and stop. Route
-  to `wdi-product`; do not quietly narrow the promise in `EXPERIENCE.md`.
-
-## Output
-
-A short report: mode taken, scope run, the result of all nine checks naming the failures, what landed
-and where, what was deferred and what has to exist before it can land, screens registered, impact
-found and where it was routed, and open questions raised.
+---
+name: wdi-ux
+description: Use when UX is produced or landed — dispatching bmad-ux for a PRD scope, then landing DESIGN.md, EXPERIENCE.md, the design system, and the screen registry into the layers they belong to. Optional, and it rides on G2. Never writes UX content itself.
+---
+
+# WDI UX
+
+`bmad-ux` writes the UX. This skill decides whether it should run, hands it the scope, checks what
+came back, and — because `bmad-ux` is **class B** — lands its output into the two layers it splits
+across. No other skill MAY land these files.
+
+Two acts, and a pass MAY do either or both: **run** the UX, and **land** it. They are separated because
+they become possible at different moments. A run belongs to G2, where the PRD is fresh. Landing needs a
+Product Component to land into, and that list is not born until the tail of G2.
+
+You MUST NOT write or edit `DESIGN.md` or `EXPERIENCE.md` yourself. If a check fails, name what is
+missing and re-dispatch — a hand-patched UX document makes the memlog lie about how it got that way.
+The content rules are in `ux-guide.md` and MUST NOT be restated here.
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| `.what/_prd/<initiative>/prd.md` | The promises the UX has to make usable — `FR`, `NFR`, `UJ-N` |
+| `.what/_product-brief/brief.md` | The primary user, and the boundary the UX MUST respect |
+| `.constitution/method/document/ux-guide.md` | The rules the result is checked against |
+| `.constitution/method/document/templates/ux.md` | The required shape of each half |
+| `.control/registry/components.yaml` | Whether the Product Components and containers a landing needs exist |
+| `.constitution/method/document/templates/design-system.md` | The shape of the product-level tokens file |
+| `.control/product-glossary.md` | Terms already fixed, so the screens do not invent competing ones |
+| `_bmad-output/ux/` | An earlier run — the input to *land*, and to intent *update* |
+| `.how/_platform/design-system.md` | Tokens and base components already agreed |
+
+## Step 1 — Position
+
+- UX is **optional**. It earns a run when the interface is a substantial part of what the PRD
+  promises; it MUST NOT be run to fill a slot. Say so and stop when a run buys nothing.
+- The order is `wdi-product` → `wdi-ux`. A UX run with no PRD in scope is designing a promise nobody
+  made; route to `wdi-product` first.
+- If the ask is a new capability rather than how an agreed one feels, this is the wrong skill — route
+  to `wdi-product` intent `update`.
+- If the ask is how the system behaves internally, route to `wdi-blueprint` for the catalogue, or
+  `wdi-component` for a full flow.
+
+## Step 2 — Mode
+
+Read `_bmad-output/ux/` and `components.yaml`, then state the mode in one line before acting.
+
+| State | Mode |
+|---|---|
+| No run for this scope | **run** — Step 3, then Step 5 for whatever is landable |
+| A run exists, finalised, nothing landed | **land** — Step 5 only |
+| A run exists and the PRD has changed under it | **run** intent *update*, then Step 5 |
+| A run exists, landed, and a `<pc>` has since been born | **land** — the deferred half, Step 5 |
+
+## Step 3 — Dispatch
+
+Invoke `bmad-ux` with the detected intent. Do not restate the rules to it — they arrive through
+`doc_standards` and `persistent_facts` in `_bmad/custom/bmad-ux.toml`, and a second copy here would
+drift.
+
+State the scope as **one PRD initiative**, and name the input files explicitly; the skill globs its
+own default locations, which this project redirects. A scope spanning several initiatives MUST be
+split into one run each — the run folder is a singleton per scope, and two initiatives in one folder
+cannot be landed separately later.
+
+## Step 4 — Verify
+
+Check what came back against the guide. Report every failure; fix none of them by hand.
+
+| # | Check | Fails when |
+|---|---|---|
+| 1 | Landing zone | Anything was written into `.what/` or `.how/` by the run itself |
+| 2 | Two documents, split correctly | A layout, component, or token sits in `EXPERIENCE.md`; a promise sits first in `DESIGN.md` |
+| 3 | Journeys reference `UJ-N` | The PRD's journeys were restated under new names |
+| 4 | Every screen has an empty and an error state | Only the populated state was designed |
+| 5 | Every user-facing noun is in the glossary | A new noun appeared — route it through `wdi-blueprint`, which owns the glossary, in this pass |
+| 6 | No new capability | The run designed something no `FR` promises — route to `wdi-product`, and MUST NOT land it |
+| 7 | Every `[ASSUMPTION]` filed | An assumption sits in the text with nothing in `.control/questions/` behind it |
+| 8 | Memlog at `.control/memlog/ux.md` | A `.memlog.md` appeared inside the corpus — `--workspace` was used |
+| 9 | `bmad-review` structure + prose ran at finalize | `doc_standards` did not fire |
+
+Check 8 is the one that MUST be fixed immediately rather than reported. A `.memlog.md` inside `.what/`
+or `.how/` is corpus pollution, and V16 rejects it.
+
+## Step 5 — Land, at two speeds
+
+Nothing is landed until the run is finalised. The homes are in `corpus-guide.md`; what is decided
+here is **when each one becomes possible**.
+
+| Output | Lands into | Possible once |
+|---|---|---|
+| Tokens and base components | `.how/_platform/design-system.md` | The run is final — it crosses components by definition |
+| `EXPERIENCE.md` | `.what/<pc>/04-usecases/` | The `<pc>` is registered in `components.yaml` |
+| `DESIGN.md` | `.how/<pc>/01-ux/` | The `<pc>` is registered **and** its container exists |
+| Each screen | an `LC` of type `ui-screen` in `components.yaml` | Same as `DESIGN.md` — an `LC` MUST name its container. Registration is checked at wave close, V12 |
+
+- A half that is not yet landable MUST stay in `_bmad-output/ux/` and be reported as deferred. At G2
+  that is the normal outcome, not a failure: the slicing is born at the tail of G2 and containers at G3.
+- You MUST NOT create a Product Component or a container to make a landing possible. A PC comes from
+  `wdi-init` intent `component` and a container from `wdi-blueprint` intent `platform`.
+- One run MAY land across several Product Components. Split by which `<pc>` the content serves; a
+  screen whose `<pc>` is ambiguous MUST be raised through `wdi-question`, not assigned by guess.
+- Registering the screens is part of landing `DESIGN.md`, in the same act. A screen in `01-ux/`
+  without its `components.yaml` entry has been half-landed, and V12 catches it at a worse moment.
+- `.how/_platform/` otherwise belongs to `wdi-blueprint`. `design-system.md` is the one file in it you
+  own, and it has its own template; you MUST NOT touch any other.
+- The run folder MUST NOT be deleted after landing. Intent *update* reads it again.
+
+## Step 6 — Impact
+
+A landed UX changes what other documents can still claim. Check, and **report** — never edit.
+
+| Found | Where it goes |
+|---|---|
+| A flow the PRD does not promise | `wdi-product` intent `update`, before it is designed |
+| A behaviour the SRS never stated | `wdi-blueprint` for a catalogue line, `wdi-component` for a flow |
+| A pattern that forces a technology choice | `wdi-decision` — a `DEC-`, not a note in `DESIGN.md` |
+| A screen contradicting an `applied` `DEC-` | `wdi-decision` — a new `DEC-`, never an edit to one already applied |
+
+`wdi-reconcile` is the read-only sweep across all layers. Run it rather than reimplementing it.
+
+## Step 7 — Memlog
+
+Everything in a UX pass — the run and the landing — logs to `.control/memlog/ux.md`, through
+`memlog.py --path`. `--workspace` MUST NOT be used.
+
+## Rules
+
+- Content MUST NOT be edited while it is being landed. Splitting one document across the homes its
+  row names is not editing; changing a sentence to fit its new home is, and it goes back through
+  `bmad-ux`.
+- You MUST NOT open G2 on UX that has not been through check 9. Gate time is for deciding.
+- You MUST NOT raise `status:` as part of landing. Status is a stage; the `reviewed:` block is an
+  event, and `wdi-review` writes it.
+- You MUST NOT land anything into a wave that is already closed. The wave is reopened through
+  `wdi-build`, or the gap is filed through `wdi-question`.
+- When the UX concludes the PRD promised something that cannot be made usable, say so and stop. Route
+  to `wdi-product`; do not quietly narrow the promise in `EXPERIENCE.md`.
+
+## Output
+
+A short report: mode taken, scope run, the result of all nine checks naming the failures, what landed
+and where, what was deferred and what has to exist before it can land, screens registered, impact
+found and where it was routed, and open questions raised.

package/kit-overlay/AGENTS.md

@@ -154,31 +154,31 @@ verifies the result, and lands the memlog.
 
 | Task | Load |
 |---|---|
-| Wanting the whole method in five minutes | `.constitution/method/README.md` |
-| About to change a rule, and needing to know what breaks | `.constitution/method/rationale.md` |
-| Asking whether a document exists at this `mode`, or where a file goes | `.constitution/method/artifact-map.md` |
-| Unsure whether a file may exist in this repo | `.constitution/repo-guide.md` |
-| Unsure where a file lives | `.constitution/document/corpus-guide.md` |
-| Unsure what a method term means | `.constitution/method-glossary.md` |
+| Wanting the whole method in five minutes | `.constitution/method/why/README.md` |
+| About to change a rule, and needing to know what breaks | `.constitution/method/why/rationale.md` |
+| Asking whether a document exists at this `mode`, or where a file goes | `.constitution/method/why/artifact-map.md` |
+| Unsure whether a file may exist in this repo | `.constitution/method/repo-guide.md` |
+| Unsure where a file lives | `.constitution/method/document/corpus-guide.md` |
+| Unsure what a method term means | `.constitution/method/method-glossary.md` |
 | Unsure about a domain term | `.control/product-glossary.md` |
 | Looking for a non-technical fact — a domain, an account, a legal entity, a locked date | `.control/project-non-technical-log.md` |
-| Naming anything — a code identifier, a file, a database column | `.constitution/language-guide.md` |
-| Asking "which gate now, what next" | `.constitution/document/delivery-flow-guide.md` · skill `wdi-help` |
-| Setting or changing `mode` or `risk_accepted` | `.constitution/document/delivery-flow-guide.md` · skill `wdi-init` |
-| Invoking a BMad skill | `.constitution/document/bmad-guide.md` · `document/bmad-skill-register.md` |
-| Writing or reviewing a product brief | `.constitution/document/brief-guide.md` |
-| Writing or reviewing a PRD | `.constitution/document/prd-guide.md` |
-| Writing or reviewing UX | `.constitution/document/ux-guide.md` |
-| Writing or reviewing an SRS | `.constitution/document/srs-guide.md` |
-| Writing or reviewing an SDD | `.constitution/document/sdd-guide.md` |
-| Writing the spine, an `AD-N`, C4, or one of the three inventories | `.constitution/document/architecture-guide.md` |
-| Opening, accepting, or applying a `DEC-` | `.constitution/document/decision-guide.md` |
-| Writing or reading a structure map | `.constitution/structure-guide.md` |
+| 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` |
+| 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` |
+| Writing or reviewing an SRS | `.constitution/method/document/srs-guide.md` |
+| Writing or reviewing an SDD | `.constitution/method/document/sdd-guide.md` |
+| Writing the spine, an `AD-N`, C4, or one of the three inventories | `.constitution/method/document/architecture-guide.md` |
+| Opening, accepting, or applying a `DEC-` | `.constitution/method/document/decision-guide.md` |
+| 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/codebase/stack-guide.md` · `conventions-guide.md` · `brownfield-guide.md` |
+| Writing or reviewing code | `.constitution/project/codebase-stack-guide.md` · `conventions-guide.md` · `brownfield-guide.md` |
 
-All three `codebase/*-guide.md` start as `status: Draft`. While they are, their contents MAY be read
+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

package/kit-overlay/README.md

@@ -2,31 +2,37 @@
 status: Reference
 ---
 
-# `.constitution/` — index
+# `.constitution/method/` — index
 
-Method files arrive from the public WDI Method package via `npx wdi-method install`
-or `update`. Load [`constitution.md`](constitution.md) before acting. Guides are
-loaded **lazily** — only when the task matches, and every guide states when on its
-own **Loaded when:** line.
+`.constitution/` holds **exactly two folders**, and the folder is what says who owns a file:
+
+| Folder | Owner | `update` | `promote` |
+|---|---|---|---|
+| `method/` — you are in it | the method | **overwritten** in full | carries it into the package |
+| [`../project/`](../project/) | this product | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
+
+Load [`constitution.md`](constitution.md) and [`../project/constitution.md`](../project/constitution.md)
+before acting: Articles 3, 4, 6, 7 are here, Articles 1, 2, 5 are yours. Guides are loaded **lazily** —
+only when the task matches, and every guide states when on its own **Loaded when:** line.
 
 Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
 `Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
 own, because its frontmatter belongs to the artifact it produces.
 
-A file this product added (one that is not in the snapshot) stays here across `update` and MUST be
-listed from `constitution.md` Article 2 or from `AGENTS.md` routing — this index is overwritten on
-every update.
+**A file this product adds MUST go in [`../project/`](../project/), not here** — anything in `method/`
+is replaced on the next update, without warning, because that is what `method/` means. This index is
+overwritten too.
 
-## `method/` — the explanation, `status: Reference`
+## `why/` — the explanation, `status: Reference`
 
 Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
 
 | File | Opened when |
 |---|---|
-| [`method/README.md`](method/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
-| [`method/artifact-map.md`](method/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
-| [`method/rationale.md`](method/rationale.md) | Before changing a rule, to know what you would break |
-| [`method/portability.md`](method/portability.md) | Which files are the method and which are the product; how promote and install move them |
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
+| [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
+| [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |
+| [`why/portability.md`](why/portability.md) | Which files are the method and which are the product; how promote and install move them |
 
 ## Cross-domain
 
@@ -51,12 +57,13 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 | [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
 | [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
 
-## `codebase/` — code rules
+## Code rules — in the room, not here
 
-All three are written by the **project**, not the kit. While `Draft`, their contents MAY be read as
-guidance but MUST NOT be used to reject a change.
+All three are written by the **product**, so they live in [`../project/`](../project/) and no update
+touches them at any `status:`. While `Draft`, their contents MAY be read as guidance but MUST NOT be
+used to reject a change.
 
-[`stack-guide.md`](codebase/stack-guide.md) · [`conventions-guide.md`](codebase/conventions-guide.md) · [`brownfield-guide.md`](codebase/brownfield-guide.md)
+[`stack-guide.md`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
 
 ## `scripts/`
 

package/kit-overlay/constitution.md

@@ -2,39 +2,15 @@
 status: Accepted
 ---
 
-# Constitution — {product}
+# Constitution — the method's articles
 
-Rewrite Articles 2 and 5 for the product this repo is. Article 1 cites
-`.control/registry/index.yaml` — replace `{product}` there at G1, not here.
-Articles 3, 4, 6, and 7 are the method and travel unchanged.
+Articles 3, 4, 6, and 7. They are the **method's** and arrive from the WDI Method package —
+`update` overwrites this file, so it MUST NOT be edited here.
 
-An agent working here MUST be able to act on the contents of this repo alone.
-
-## Article 1 — Scope
-
-This repo covers the product named at `product.name` in
-`.control/registry/index.yaml`. One product, one repo. A second product MUST
-get a repo of its own.
-
-`product.client` in the same file names the client if there is one, and stays
-empty if there is not. The product brief at G1 uses `product.name` as its
-title. Neither this file nor the brief is a second source of the name.
-
-An agent working here MUST NOT demand that sibling organisation repositories
-be open in the same session.
-
-## Article 2 — Content boundary, `.work/`, and cross-repo references
-
-All three are governed by [`repo-guide.md`](repo-guide.md). Its rules MUST NOT be
-repeated here — one rule, one place.
-
-What is particular to this repo, and therefore lives here:
-
-- Name any extra boundary this product has (a public-repo rule, a ban on `3p.md`,
-  a `.work/` resting state). If there is none, delete this bullet list and the
-  sentence above it.
-- `3p.md` MUST NOT be created in a product repo. Operational engagement memory
-  lives outside.
+This product's own articles — 1 Scope, 2 Content boundary, 5 Method ownership — live in
+[`../project/constitution.md`](../project/constitution.md), which `update` never touches. The
+numbering is shared across the two files and has gaps in each; the numbers are **not** reassigned,
+because a frozen record that cites one MUST NOT be rewritten.
 
 ## Article 3 — Layers
 
@@ -43,13 +19,13 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 
 | Path | Role |
 |---|---|
-| `.constitution/` | Rules — how we work. `method/` holds the non-binding explanation of them |
+| `.constitution/` | Rules — how we work. Exactly two folders: `method/` is the method's and is overwritten by `update`, `project/` is this product's and is never touched. `method/why/` holds the non-binding explanation of the rules |
 | `.control/` | Control — what currently holds and what has been decided |
 | `.what/` | What is promised |
 | `.how/` | How it is built |
 | `_bmad-output/` | Run workspace; committed, not curated |
 | `.work/` | Scratch; committed, emptied when a task closes |
-| *(application roots)* | Application code — name them in this row |
+| *(application roots)* | Application code — named and mapped in `.control/structure-codebase.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.
@@ -73,33 +49,11 @@ so a status there would land in the artifact and mean something else entirely.
 A missing header anywhere else is a **finding**, not an implicit anything.
 
 `Reference` exists so that the *explanation* of a rule can live beside the rule without competing with it —
-`method/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
+`method/why/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
 one wins, and the disagreement MUST be reported as a defect rather than resolved by preferring whichever was
 opened first. A rule MUST NOT be born in a `Reference` file; when one is noticed there, it is stated as a
 finding and written in the guide that owns it.
 
-## Article 5 — The method arrives from WDI Method
-
-This is the **consumer** article. Use it in every product repo.
-
-`.constitution/` guides and templates (except this file's Articles 1, 2, and 5,
-`codebase/*-guide.md`, and any extra file this repo added), the `wdi-*` skills,
-and `_bmad/custom/*.toml` arrive from the public WDI Method package via
-`npx wdi-method install` / `update`.
-
-- A method file MUST NOT be invented or patched here to improve the method. If a
-  rule is wrong, it is fixed in the WDI Method package, then brought here with
-  `update`.
-- `wdi-method update` MUST overwrite method files and MUST NOT touch `.what/`,
-  `.how/`, `.control/` product state, this file's Articles 1–2 and 5,
-  `codebase/*-guide.md` once `Accepted`, extra constitution files this repo
-  added, or `_bmad/custom/*.user.toml`.
-- A rule particular to this repo MUST be written out in full in this file or a
-  sibling, and MUST NOT be replaced by a pointer into another repository.
-
-A prefix in `.claude/skills/` names the **method**, not the owner: `bmad-*` is
-BMad's, `wdi-*` is this method's.
-
 ## Article 6 — Decisions
 
 A decision worth remembering is a `DEC-NNN`. Its shape, the one test that decides whether it is

package/kit-overlay/portability.md

@@ -22,14 +22,14 @@ 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 |
-| `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 |
+| `../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 |
 | `templates/oq.md` | One example of a bad question title | Cosmetic |
 
 Everything else — the five gates, the two fields, the fifteen skills, the templates, `validate.py`,
-`inventory.py`, `method-glossary.md`, and the three files beside this one — carries without edit.
+`inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
 
 ## What does NOT travel
 
@@ -37,7 +37,7 @@ Everything else — the five gates, the two fields, the fifteen skills, the temp
 |---|---|
 | `.control/` | This product's state. A new project scaffolds its own through `wdi-init` intent `setup`, or receives empty stubs on first `install` |
 | `.what/` · `.how/` | This product's promises and build |
-| `.constitution/codebase/*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
+| `.constitution/project/codebase-*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
 | `_bmad-output/` | Run workspace |
 | The `bmad-*` skills themselves | BMad's, installed by BMad. Only `_bmad/custom/*.toml` is ours |
 
@@ -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 `../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