wdi-method 0.3.0

package/kit/.constitution/document/ux-guide.md

@@ -0,0 +1,99 @@
+---
+status: Accepted
+---
+
+# UX Guide
+
+**Loaded when:** running `bmad-ux`, or placing its output
+
+`bmad-ux` produces two documents that belong to **two different layers**. That split is the whole
+reason this guide exists: everything else follows from getting it right.
+
+## Two outputs, two layers
+
+| Output | Home | Layer | Answers |
+|---|---|---|---|
+| `EXPERIENCE.md` | `.what/<pc>/04-usecases/` | Promise | What the user experiences, and what they can get done |
+| `DESIGN.md` | `.how/<pc>/01-ux/` | Build | Screens, states, components, and how they are put together |
+
+The test is the usual one. If a sentence would still be true after a full redesign, it is experience
+and belongs in `.what/`. If it names a layout, a component, or a token, it is design.
+
+Getting this backwards is expensive in a specific way: a `DESIGN.md` filed under `.what/` makes the
+promise layer freeze around one visual solution, and every later redesign then reads as a broken
+promise.
+
+## The landing zone
+
+`bmad-ux` is a **class B** skill: it writes to a neutral landing zone at `_bmad-output/ux/`, and
+`wdi-ux` — which is what dispatched it — lands the output from there.
+
+- Output MUST land in `_bmad-output/ux/` first. A UX run MUST NOT write directly into `.what/` or
+  `.how/`.
+- Landing MUST go through `wdi-ux`, which owns `.what/<pc>/04-usecases/` and `.how/<pc>/01-ux/`. No
+  other skill MAY land these files.
+- Nothing is placed until the run is finalised. Half-placed UX output is worse than unplaced output,
+  because it looks distributed.
+- A run MAY finish before there is a `<pc>` to place it into — the slicing is born at the **tail of
+  G2**, and a UX run belongs to G2 itself. The output then waits in `_bmad-output/ux/`, and `wdi-ux` lands it once
+  the component exists. Waiting is the correct state; a home MUST NOT be invented to end it.
+
+`doc_standards` on `bmad-ux` runs `bmad-review` over both documents **at finalize** — that is, before
+`wdi-ux` lands them. Reviewing afterwards would mean reviewing two files that no longer sit together.
+
+## Registry consequences
+
+Placement is not finished when the files have moved.
+
+- **Every screen in `DESIGN.md` MUST be registered as an `LC` of type `ui-screen`** in
+  `.control/registry/components.yaml`, with its `container`. A screen that exists in the design and not
+  in the registry is a change nothing will trace, and V12 catches it **at wave close**.
+- A composite that is reused across screens is an `LC` of type `ui-composite`, not a screen.
+- Tokens and base components — colour, type scale, spacing, buttons, inputs — MUST go to
+  `.how/_platform/design-system.md`, not into any one component's `01-ux/`. They cross Product
+  Components by definition.
+
+Registry conversion is part of placement, not a follow-up.
+
+## Vocabulary
+
+Every user-facing noun in either document MUST already exist in `.control/product-glossary.md`, used
+verbatim. A new domain noun introduced by a UX run MUST be added through `wdi-blueprint` intent
+`catalog` in the same pass, which owns the glossary.
+
+This is where vocabulary drift usually enters the corpus: UX writes the words the user actually sees,
+and those words are the ones that stick. When the SRS says `Anggota` and the screen says `Pengguna`,
+the screen wins in practice and the corpus starts lying.
+
+## What UX does not decide
+
+- **Requirements.** A UX run that discovers a needed capability has found an `FR`, and it MUST go to
+  the PRD through `wdi-product` intent `update` before it is designed.
+- **Behaviour.** How the system responds belongs to `SRS-<pc>.md`. `EXPERIENCE.md` says what the user
+  perceives, not what the system does internally.
+- **Architecture.** A UX need that forces a technology choice MUST become a `DEC-`, not a note in
+  `DESIGN.md`.
+
+## Passing G2
+
+`DESIGN.md` is an **attachment** at G2, not the document being read. What the Product Owner actually
+reads is `prd.md` and `EXPERIENCE.md` — and G2 gets 45 minutes, twice any other gate, precisely
+because it decides two things: what is built, and how it feels to use.
+
+The gate question that catches a weak `EXPERIENCE.md` is checklist item 4: *can I retell the main UX
+flow in five sentences without opening the document?* An experience that cannot be retold has not
+been decided, only drawn.
+
+Every `[ASSUMPTION]` left in either document at finalize MUST be registered through `wdi-question`
+before the gate opens.
+
+## Rules
+
+- You MUST NOT edit content while placing it. If the content needs changing to fit its new home, that
+  is a UX revision, and it goes back through `bmad-ux`.
+- `EXPERIENCE.md` MUST reference use cases by ID where the chain matters. A journey that maps to no
+  `UC` is either a missing use case or a promise nobody made.
+- Durable UX decisions — why a pattern was chosen, what was rejected — belong in a `DEC-` or in the
+  run's addendum, not as prose inside `DESIGN.md`.
+- The UX run folder in `_bmad-output/ux/` MUST NOT be deleted after placement. Intent *update* reads
+  it again.

package/kit/.constitution/language-guide.md

@@ -0,0 +1,69 @@
+---
+status: Accepted
+---
+
+# Language Guide
+
+**Loaded when:** naming anything — a code identifier, a database field, a file, a folder.
+
+Which language a name is written in, and nothing else. Case style → `codebase/conventions-guide.md`;
+legal characters → `structure-guide.md`; the right domain word → `.control/product-glossary.md`.
+
+## Code MUST be English
+
+Identifiers, code files and folders, database schema (tables, columns, indexes, constraints, enum
+values, migrations), and machine-facing keys (API routes and fields, config keys, environment
+variables, event names, CSS classes, design tokens). An identifier sits between English keywords and
+English error messages, and a second language there is where misreadings happen.
+
+Prose **inside** code — comments, commit messages, log messages — is not a name and is not governed
+here.
+
+**One exception:** an Indonesian administrative or legal thing — `kelurahan`, `npwp`. All three MUST
+hold: it already has an entry in `.control/product-glossary.md`; only the domain noun is Indonesian
+(`kelurahanCode`, MUST NOT be `kodeKelurahan`); one ASCII spelling in schema, API, and code alike. An
+English word being longer or less familiar does not qualify.
+
+## Visitor-facing URL paths MUST be English
+
+The path a person types or copies is a name. One exception: `/bisnis` and `/{code}/bisnis` — that
+surface is named in Indonesian in the product, and `/business` would be a second name for the same
+thing.
+
+## Two settings, and everything else is not a choice
+
+The product picks two things, both in `.control/registry/index.yaml` under `policy:`, and both
+defaulting to English:
+
+| Setting | Governs |
+|---|---|
+| `doc_language` | The **prose** of working documents in `.what/` · `.how/` · `.control/` |
+| `doc_filename_language` | The **slug** part of a document filename |
+
+Nothing else about language is a setting, and a skill MUST NOT ask:
+
+- **Method terminology** — `DEC` `SRS` `SDD` `UC` `FR` `AD`, the gate names, the values of `mode` and
+  `risk_accepted`. One thing, one name, in every repo the method is installed in.
+- **Machine-facing markers** — `[NEEDS CONFIRMATION]` `[MISSING]` `[ASSUMED]` `[PARTIAL]`, and the
+  `yes`/`no` in a `critical` column. They are matched by scripts, which makes them keys rather than
+  prose, and the rule above on registry values already covers keys.
+- **Code identifiers, database columns, config keys** — §Code MUST be English, above.
+
+**A corpus written before these settings existed MUST NOT be migrated for them.** The readers accept
+both languages — `validate.py` matches `yes|ya`, and V23's keyword set is the union of both — so an
+existing document keeps working and a new one is written in the chosen language. Rewriting a hundred
+documents so a regex looks tidier is a cost with no buyer.
+
+## Document filenames — the slug follows the setting
+
+Three parts are **not** free, because the method reads them: layer and slot folder names, document code
+prefixes (`DEC-`, `FR-`), and a `YYYY-MM-DD` prefix. Those are always English and always as written.
+The slug after the code follows `doc_filename_language`.
+
+Files under `.constitution/` MUST be English whatever the settings say — they are agent instructions,
+and they travel to every repo through the `wdi-method` package.
+
+## A wrong name MUST NOT be fixed inside an unrelated change
+
+A rename reaches the schema, the API, and every caller. It gets a change of its own, or a ratified
+row in `codebase/brownfield-guide.md`. A **new** name MUST NOT copy a wrong neighbour.

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

@@ -0,0 +1,169 @@
+---
+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. Three files in this folder: this one for orientation, `artifact-map.md` for *"where does this
+file go"*, `rationale.md` for *"why is it like this"* — open that 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 wave | 10' |
+
+**Only G4 changes shape.** The other four are always the same, whatever the settings — and 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 | `wdi-ux` | with G2 |
+| 3 | Birth the components, set `mode` and `risk_accepted` | `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 | Build | `wdi-build` — opens the wave, runs `bmad-spec`, ships each story, closes the wave | **G5** |
+
+After step 6 the next component enters at **step 5**, not at the beginning. Steps 0–4 happen once in the
+life of the product.
+
+`SPEC.md` and story files are **not read by humans**. The human review surface stops at the PRD, `.what/`,
+and `.how/`.
+
+## 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: `bmad-build` directly. It **stops and becomes a wave `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` |
+| You do not know where you are | `wdi-help` |
+
+## Fifteen 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 wave 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-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` + stories | `bmad-spec` | `wdi-build` |
+| Code | `bmad-build` · `bmad-build-auto` | `wdi-build` |
+| Retrospective | `bmad-retrospective` | `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/` |
+| 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 wave 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 | Two different CLI families, and never the family that wrote the code |
+
+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/artifact-map.md

@@ -0,0 +1,155 @@
+---
+status: Reference
+---
+
+# Artifact Map — what exists, where, and who owns it
+
+**Opened when:** someone asks *"where does this file go"*, or *"does this document exist at my `mode`"*.
+
+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.
+
+It answers three questions and nothing else: which files exist at each `mode`, who owns each one, and how
+the units of work line up. The **rules** about depth live in `document/delivery-flow-guide.md`; what is
+here is the map.
+
+## The one thing to read first
+
+Nine things exist at **every** `mode`, including `catalog`, because they belong to the blueprint at G3 and
+the depth knob does not reach the blueprint:
+
+> the use case list · the API list · the table list with its key columns · the screen list · the domain
+> model · the actor list · the spine `AD-N` · C4 L1 + L2 + L3 · cross-component business rules
+
+That is why nobody needs a fifth mode. The request behind wanting one is almost always *"I need at minimum
+the use cases, the API, and the database"* — and all three are already in `catalog`.
+
+## What each mode gives you, cumulatively
+
+| `mode` | What you hold |
+|---|---|
+| `catalog` | The nine above. **Zero extra files per component** |
+| `outline` | + `Decision Summary` · the `LC` list per component · full flows for at most 3 use cases · local business rules |
+| `guarded` | + `Failure Behaviour` for every boundary · `Inherited Constraints` · third-party integration documents · boundary `LC` registered |
+| `deep` | + ABCE robustness analysis · five-lane contract spec per endpoint · data dictionary per column · flow diagrams · state machines · branch scenarios · every `critical` use case gets a full flow |
+
+Marks used below: **always** = present at all four modes, born at G1, G2, or G3 · ✓ = written at that mode
+· skeleton = the file exists carrying headings and frontmatter · — = not written at all.
+
+## `.what/`
+
+| File | Holds | Born | `catalog` | `outline` | `guarded` | `deep` |
+|---|---|---|---|---|---|---|
+| `_product-brief/brief.md` | Problem, users, measure of success, non-goals | G1 | always | always | always | always |
+| `_product-brief/addendum.md` | Depth that does not fit the brief's narrative | G1 | always | always | always | always |
+| `_prd/<initiative>/prd.md` | `CAP` · `FR` · `NFR` · `UJ` · one proof of done per `FR` | G2 | always | always | always | always |
+| `_prd/<initiative>/addendum.md` | Rejected alternatives, option matrices, sizing | G2 | always | always | always | always |
+| `<pc>/04-usecases/EXPERIENCE.md` | The user-facing journey | G2, optional | optional | optional | optional | optional |
+| `business-rules.md` | `BR-N` binding more than one component | G3 | always | always | always | always |
+| **`<pc>/SRS-<pc>.md`** | § Actor Register · **§ UC Catalogue — this is the use case list** · Constraints · Non-Goals · Prerequisite · Assumptions/Risks/TBC | G3 | **always** | always | always | always |
+| `<pc>/03-domain/domain-model.md` | Entities · relations · columns | G3 | always | always | always | always |
+| `<pc>/02-rules/rules-<pc>.md` | Rules binding only this component | G4 | — | ✓ | ✓ | ✓ |
+| `<pc>/04-usecases/UC-<n>-<slug>.md` | One full flow, at most eight steps | G4 | — | max **3** | max **3** | every `critical` UC |
+| `<pc>/03-domain/state-machines.md` | The lifecycle of each multi-state entity | G4 | — | — | — | ✓ |
+| `<pc>/05-scenarios/SCN-<nn>-<slug>.md` | A branch that does not fit its use case file | G4 | — | — | — | ✓ |
+
+**So `SRS-<pc>.md` exists at `mode: catalog`.** It carries the actor list and the use case catalogue. What
+is absent there is the `UC-<n>-<slug>.md` files — the step-by-step flows.
+
+Repealed: `<pc>/01-requirements/` (permanently empty; `FR` live in the PRD and the SRS cites them) and
+`<pc>/supplements/` (existed for `ANX-`).
+
+## `.how/`
+
+| File | Holds | Born | `catalog` | `outline` | `guarded` | `deep` |
+|---|---|---|---|---|---|---|
+| `_platform/ARCHITECTURE-SPINE.md` | `AD-N` — Binds · Prevents · Rule. Invariants only | G3 | always | always | always | always |
+| `_platform/c4-l1-system-context.md` | System, outside actors, outside systems | G3 | always | always | always | always |
+| `_platform/c4-l2-containers.md` | Containers, their technology, their relations, and the PC × container matrix. **Owns the container list** | G3 | always | always | always | always |
+| `_platform/c4-l3-<container>.md` | One file per `built: true` container holding more than one Product Component | G3 | always | always | always | always |
+| **`_platform/inventory-db.md`** | **Table list**: `No` · table · owning component · what it holds · **key columns** | G3 | **always** | always | always | always |
+| **`_platform/inventory-api.md`** | **Endpoint list**: `No` · method · path · owning component · description · status | G3 | **always** | always | always | always |
+| **`_platform/inventory-screen.md`** | **Screen list**: `No` · screen · route · owning component · actor · `UC` served | G3 | **always** | always | always | always |
+| `_platform/cross-cutting.md` | One error envelope for the whole product, and the rest of what is shared | G3 | always | always | always | always |
+| `_platform/design-system.md` | Tokens and base elements | G2, optional | optional | optional | optional | optional |
+| `<pc>/SDD-<pc>.md` § Decision Summary | What this component is built as, and the costliest choices reversed | G4 | skeleton | ✓ | ✓ | ✓ |
+| `<pc>/SDD-<pc>.md` § Structure | The `LC` list and their dependency direction | G4 | skeleton | ✓ | ✓ | ✓ |
+| `<pc>/SDD-<pc>.md` § Inherited Constraints | The `AD-N` binding this component, quoted not paraphrased | G4 | — | — | ✓ | ✓ |
+| **`<pc>/SDD-<pc>.md` § Failure Behaviour** | Per boundary: the other side slow, absent, or lying | G4 | — | — | **✓ every boundary** | ✓ |
+| `<pc>/SDD-<pc>.md` § Robustness Analysis | ABCE per `critical` use case | G4 | — | — | — | ✓ |
+| `<pc>/03-integrations/<name>.md` | A third party: who owns it, and what happens when they change it | G4 | — | — | ✓ if any | ✓ |
+| `<pc>/02-contracts/00-inventory.md` | This component's endpoints, stably numbered | G4 | — | — | — | ✓ |
+| `<pc>/02-contracts/<nn>-<resource>.md` | One endpoint, five lanes: auth · validation · error · rate limit · idempotency | G4 | — | — | — | ✓ |
+| `<pc>/04-components/<name>.md` | Services and jobs | G4 | — | — | — | ✓ |
+| `<pc>/05-model/data-model.md` | Component ERD + **data dictionary per column** | G4 | — | — | — | ✓ |
+| `<pc>/06-flows/<nn>-<flow>.md` | Sequence diagram, only for money, irreversible state, or a third party | G4 | — | — | — | ✓ |
+| `<pc>/01-ux/<screen>.md` | Screens and composites, **field detail per form** | G4 | — | — | — | ✓, or earlier via `wdi-ux` |
+
+Repealed: `_platform/architecture/` (one file does not earn a folder) and `<pc>/supplements/`.
+
+## Registry and derived files
+
+| File | Holds | Present at |
+|---|---|---|
+| `.control/registry/requirements.yaml` | `BG` · `CAP` · `FR` · `NFR` · `UJ` | every mode |
+| `.control/registry/usecases.yaml` | `UC-N` with `critical` and the `FR` it satisfies | every mode |
+| `.control/registry/components.yaml` → `product_components` | Component · `mode` · `risk_accepted` · `risk_note` · `owns` · `g4_passed` | every mode |
+| `.control/registry/components.yaml` → `containers` | The containers from C4 L2 | every mode |
+| `.control/registry/components.yaml` → `platform_owns` | Entities no Product Component's promise explains. `_platform` is not a component and has no `mode` | every mode |
+| `.control/registry/components.yaml` → `logical_components` | `LC` | boundary from `guarded`; boundary + control at `deep` |
+| `.control/registry/decisions.yaml` · `waves.yaml` · `defects.yaml` · `risks.yaml` · `index.yaml` | Decisions · work · defects · risks · the global `mode` and gate map | every mode |
+| `.control/generated/blueprint.md` | **The one-page roll-up reviewed at G3** | every mode |
+| `.control/generated/decisions.md` | The flat index of every `DEC-` | every mode |
+| `.control/generated/estimate.md` | The candidate task table | every mode |
+| `.control/generated/rtm` · `status` · `dag` · `components` · `risks` | Traceability and progress | every mode |
+
+## Who owns each file
+
+A skill lands the output of the layer it owns, and landing is part of producing it — never a follow-up
+someone else performs. `document/corpus-guide.md` holds the binding version of this table.
+
+| Owner | Writes |
+|---|---|
+| `wdi-init` | The registry scaffold, `mode`, `risk_accepted`, component birth, the `SRS`/`SDD` skeletons, the two structure maps |
+| `wdi-problem` | `.what/_product-brief/` |
+| `wdi-product` | `.what/_prd/<initiative>/` |
+| `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` | `waves.yaml` · `_bmad-output/specs/` · `src/` · `web/` · `.control/reports/RTR-<wave>.md` |
+| `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` |
+| `wdi-report` | `.control/reports/<period>.md` |
+| a script | everything in `.control/generated/`, and the three inventories once code exists |
+
+Four skills write **no file at all**, and that is deliberate: `wdi-reconcile`, `wdi-help`,
+`wdi-report` intent `dispatch`, and `wdi-review` apart from one frontmatter block. What reports MUST NOT
+also change things — otherwise there is nothing left to check with.
+
+## How the units of work line up
+
+`FR` is a **promise** and permanent; a wave is a **unit of work** and temporary; `SPEC.md` is the machine
+contract for one wave; a story is one piece one builder takes to a green PR.
+
+One wave = one `SPEC` = one tracker Task, and Epic = Product Component, Sub-task = story. **`FR` is not a
+Task** — it travels as a label, because one `FR` can be delivered by stories in two waves and one story can
+satisfy part of two `FR`.
+
+The binding version of all of this, including why a wave MAY cross components and what has to be true
+first, is in `document/delivery-flow-guide.md`. It is not restated here.
+
+## What needs no template, and why
+
+Stated so the next completeness audit does not report it again:
+
+| File | Why it has no template |
+|---|---|
+| `.control/generated/*` | Script output. Its shape is code, not a template |
+| `.control/reports/<period>.md` | Rendered by `timeline.py` |
+| `.control/project-non-technical-log.md` | States its own entry shape in its own header, and there is exactly one such file |
+| `SPEC.md` · story files | They belong to `bmad-spec`. WDI does not write their shape, and MUST NOT |
+| Registry `*.yaml` | Their shape is the comment block at the head of each file, plus the validator |
+
+Everything else in this map has a template in `document/templates/` — 27 of them, and every row above is
+covered by one.

package/kit/.constitution/method/portability.md

@@ -0,0 +1,91 @@
+---
+status: Reference
+---
+
+# Portability — what is method, what is product
+
+**Opened when:** carrying a method change into the WDI Method package, or installing
+the method in a product repo.
+
+This file **explains**. It does not bind. Installing is the act, and that act lives in
+the WDI Method package README plus `wdi-method` (`install` · `update` · `promote` ·
+`verify`). Where this file and that README disagree, the README wins and the
+disagreement is a defect.
+
+It exists so that "promote the method, leave the product" is not a fresh re-reading of
+fifty files every time.
+
+## The seam
+
+Most of `.constitution/` is portable as it stands. A handful name **this product**, and in most of
+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 |
+| `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.
+
+## What does NOT travel
+
+| Stays behind | Why |
+|---|---|
+| `.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 |
+| `_bmad-output/` | Run workspace |
+| The `bmad-*` skills themselves | BMad's, installed by BMad. Only `_bmad/custom/*.toml` is ours |
+
+## What travels beside `.constitution/`
+
+The method is not `.constitution/` alone. Three sets move together, and carrying one without the
+others leaves a method that cannot run:
+
+| Set | Note |
+|---|---|
+| `.constitution/` | Minus the product articles; `promote` / `install` handle the seam |
+| `.claude/skills/wdi-*/` (and `.agents/skills/wdi-*/` when those agents are selected) | Every wrapper. A wrapper without its guide, or a guide without its wrapper, is half a method |
+| `_bmad/custom/*.toml` | The one most likely to be forgotten. `*.user.toml` stays behind |
+| `AGENTS.md` | The routing table is the method; from `## Code` down is the product. `install` / `update` MUST NOT overwrite an existing `AGENTS.md` |
+
+## Two directions
+
+```
+a product repo with a newer working copy of the method
+        --promote-->
+WDI Method (this package)
+        --install / update-->
+product repos
+```
+
+- **Promote** copies the method *up* once it has settled in a working copy.
+- **Install / update** copies that snapshot *out* to a repo that consumes it.
+- Do not run `update` against a repo you are about to promote from — that would overwrite the newer copy.
+- There is no SHA lock and no per-file increment. The snapshot is the unit. The package version on npm / GitHub is the name of that snapshot.
+
+## Installing in a fresh repo
+
+BMad first (`npx bmad-method install`), then WDI Method. There is no numbered install runbook:
+the steps that a runbook used to carry are now `wdi-init` intent `setup`. The order the acts come in:
+
+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.
+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
+   slot through the skill that owns it; everything else goes to `_bmad-output/prior-knowledge/`.
+   `corpus-guide.md` owns that test.
+7. Then G1 — which confirms `product.name` and writes the brief under that name.
+
+**Two things a fresh install MUST NOT do:**
+
+- Set `mode` and `risk_accepted` before the components exist. They are per-component fields, and the
+  components are born at the tail of G2.
+- Fill `.control/generated/` by hand. It is script output, and a hand-written table there is the one
+  lie no validator catches.