wdi-method 0.5.13 → 0.6.0

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

@@ -0,0 +1,179 @@
+---
+name: wdi-upgrade
+description: Use right after `wdi-method update` moved this repo to a newer method version. Finds every document and registry file still in the OLD shape, re-homes their content into the new one — registry rows out of prose, pointers where copies were, the rendered trees born — and verifies green. Runs once per version jump; safe to re-run.
+---
+
+# WDI Upgrade
+
+`wdi-method update` does the mechanical half of a version jump: it overwrites the kit, renames files whose
+content needs no judgment, seeds what is new, prunes what is retired. It stops exactly where a decision
+about **content** begins — which PRD an `FR` belongs to, whether a sentence in the old brief was an
+assumption or a constraint. Those are this skill's half.
+
+**This is the one skill allowed to edit `brief.md`, `prd.md`, an SRS, an SDD, or a C4 file directly.**
+Every other skill is forbidden, because a hand edit makes the memlog lie about how the document was
+produced. An upgrade produces nothing: it moves sentences that already exist into the home the new
+version gives them, word for word. The memlog stays true, and this skill's report is the record.
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| `.control/wdi-method.yaml` | The version now installed — the shape everything below MUST end in |
+| The `update` run's own output | The `upgrade` line lists what it detected as pending; start there |
+| `.control/registry/` | What is already a row, so nothing is landed twice |
+| `.what/_product-brief/brief.md` · `.what/_prd/*/prd.md` | The two documents whose shape changed most |
+| `.what/<pc>/SRS-<pc>.md` · `.how/<pc>/SDD-<pc>.md` · `.how/_platform/c4-l2-containers.md` | The three that used to carry a copy of a registry table |
+| `.constitution/method/document/templates/` | The target shape of every document above |
+
+## Step 1 — Detect, and show the list before touching anything
+
+Probe each item below; a probe is a file or heading that exists only in the old shape. List every hit
+to the owner as a checklist, in the order below — it is a dependency order, and doing a later item
+before an earlier one lands content in a file that the earlier item is about to change.
+
+| # | Probe | Old shape | New home |
+|---|---|---|---|
+| 1 | `.control/registry/requirements.yaml` exists | one file for `BG` · `CAP` · `FR` · `NFR` · `UJ` | `goals.yaml` (`BG`) · `requirements-<slug>.yaml` per PRD (`CAP` · `FR` · `NFR` · `UJ`) |
+| 2 | `specs.yaml` has `W<n>` ids, or `epics:` / `stories:` keys | pre-rename plan | re-cut through `wdi-build` — **not this skill**; report it and move on |
+| 3 | `brief.md` has `## Executive Summary`, `## Vision`, `## Assumptions`, or `## Prerequisites`; or `## Goals` lists `BG-` statements | 14-section brief | 8 sections: `Why` merges Summary + Vision; Goals is a pointer, its rows in `goals.yaml`; Assumptions → `questions/assumptions.md`; Prerequisites → `questions/external.md` |
+| 4 | any `prd.md` has a section **named** Document Purpose, Glossary, Non-Goals, Open Questions, or Assumptions Index — under whatever number that kit gave it — or `**Proof of done:**` under a feature | 12-section PRD with `FR` blocks | 7 sections; `FR`/`NFR` text → `requirements-<slug>.yaml`, the PRD keeps `Realizes:` ids; Glossary → `product-glossary.md`; §8/§9 → `questions/`; §1 becomes a delta |
+| 5 | any `SRS-<pc>.md` `## UC Catalogue` has `\| UC-` rows | catalogue copied from `usecases.yaml` | one pointer line; the rows live in `usecases.yaml` |
+| 6 | any `SDD-<pc>.md` `## Inherited Constraints` has a `Quoted rule` column, or `> ` blockquote lines under an `**AD-N — …**` heading, or the sentence `Quoted verbatim from` | `AD-N` text copied from the spine, in either of the two shapes SDDs were written in | ids only; the rendered SDD shows the text |
+| 7 | `c4-l2-containers.md` has a `\| Container \| Product Components living in it \|` table | matrix copied from `components.yaml` | one pointer line |
+| 8 | `.control/generated/brief.md`, `blueprint.md`, or `prd-*.md` exist | human pages in the machine folder | `.what-rendered/` · `.how-rendered/` — `render` clears the old ones |
+| 9 | `.what-rendered/` or `.how-rendered/` absent | no reader's tree yet | born by `render` |
+| 10 | any `.md` outside `.constitution/` cites `.control/generated/brief.md`, `blueprint.md`, or `prd-<slug>.md` | a pointer at a page that moved | `.what-rendered/_product-brief/brief.md` · `.how-rendered/blueprint.md` · `.what-rendered/_prd/<slug>/prd.md` — `cites-resolve` fails until it is repointed |
+
+Anything not in the list is not this skill's. A brief that already has `## Why` is done; skip it.
+
+## Step 2 — Registry first
+
+**1 — the requirement split.** A row written under an older kit carries `text:` where a newer one
+carries `title:`; both are the short label, the renderer and `timeline.py` read either, and one MUST
+NOT be copied into the other — that is two homes for one fact. Which PRD a row belongs to is read from
+the rows before it is read from the prose. A `CAP` or `UJ` with a `prd:` field goes to `requirements-<that slug>.yaml`; an `FR`
+follows its `capability:` to that CAP's file; an `NFR` follows its `component:` to the PRD whose CAPs
+own that component — a `BG` is product-level and never decides an NFR's home on its own, so `goal:` is
+only a tie-breaker when that component's CAPs span two PRDs. On a product with exactly **one** PRD every row belongs to that
+PRD by construction — write them all to its file and skip the citation scan. Otherwise, only a row with
+none of those fields falls back to the PRD whose prose cites its id — and an id cited by **two** PRDs
+is reported, not placed. The citation scan still runs on every row as a cross-check: a row whose
+structural home and citing PRD disagree is reported with both names. Write the row, unchanged, into
+its file; `goals:` rows go to `goals.yaml`. A sentence moved into a YAML value keeps its punctuation
+and its markup: when it holds `: ` or `#` or starts with a quote, wrap the value in double quotes or a
+`>-` block — never trade a colon for a dash or strip `**` and backticks to make it a plain scalar. A row with no home is reported by id, not guessed: the
+owner names it. When every row has moved, delete `requirements.yaml`; `id-allocated-once` fails if a
+row was copied instead of moved.
+
+Run `validate.py --check`. Green here means the registry is whole before any document starts pointing
+at it.
+
+## Step 3 — Documents, oldest gate first
+
+**3 — brief.** Merge `## Executive Summary` and `## Vision` into one `## Why`, keeping every sentence
+that says something the other did not. Each `BG-N` statement under `## Goals` MUST already be a row in
+`goals.yaml` (Step 2); replace the list with the pointer line from the template. Each `## Assumptions`
+item becomes a row in `.control/questions/assumptions.md` with `Whose: owner`; each `## Prerequisites`
+item a row in `external.md` — **after** checking that no `OQ-` row already states it, because a brief
+written under an earlier kit usually landed them already and a second row is a copy. A prerequisite
+the brief itself marks satisfied is dropped, not landed as open. A `questions/` table written before
+the `Whose` column existed (`| id | Assumption | Cost if wrong | Taken | By |`) gets the column added —
+header and separator, and an empty cell on every existing row, which the validator counts as
+`unstated`, which is what they are. The rows this skill lands say `owner`. `Cost if wrong` is `—` when
+the source never stated one; it is not invented. An open question the source never marked blocking is
+filed in `assumptions.md`, as the template's three tests say. Delete both sections, and say how many
+items were already rows. Check `## Success Criteria` names one measurable
+figure — if it does not, that is a finding for the owner, not a sentence for this skill to invent.
+
+**4 — each PRD.** Sections are matched **by name, never by number**: the numbers moved between kits
+(one kit numbers Non-Goals §5 and Open Questions §8; an older one numbers Non-Goals §7, MVP Scope §8,
+Open Questions §10), so a step that says "delete §8" deletes MVP Scope on the wrong corpus. Delete
+`Document Purpose`. Every `Glossary` term not yet in `.control/product-glossary.md` is added there,
+verbatim; then delete `Glossary`. Every `Non-Goals` item MUST already be in the brief's Scope Out or
+this PRD's `MVP Scope → Out of Scope` — if neither holds it, add it to the one it belongs to; then
+delete `Non-Goals`. Every `Open Questions` and `Assumptions Index` item becomes a `questions/` row
+(after the same already-a-row check as the brief's); delete both.
+Under each feature, every `FR` block is folded into its row in `requirements-<slug>.yaml` (Step 2)
+before the block goes: the block's description paragraph — the prose between the `#### FR-N` heading
+and the first `**…:**` label — becomes the row's `statement:` when the row has none (the row's `title`
+stays). **This is the one move with no validator behind it**, so count it: blocks with a paragraph
+versus rows that now carry `statement:` MUST match, and Step 5 reports both numbers. A run that deletes
+the blocks and lands zero statements has thrown the requirement's own sentence away; its `**Consequences (testable):**` bullets move verbatim to
+`addendum.md` under `## Technical how — testable consequences per FR`, appended **after** the sections
+already there, one `### FR-N — title` each,
+because `prd-guide.md` repealed the double proof of done and that is where the technical restatement
+lives now; its `**Proof of done:**` is compared with the row's `proof` — when they differ, the
+**registry is kept** (it is the declared SSOT), the PRD's is dropped, and both texts are reported side
+by side for the owner, never merged. Then the block becomes `**Realizes:** FR-a, FR-b, NFR-c`, and a
+`**Functional Requirements:**` label left with nothing under it is deleted — the rendered page rebuilds
+the blocks from the rows. When the deletions are done, **put the surviving `##` sections in the
+template's order and renumber them** — moving a whole section is a move, not an edit, and a file whose
+`## 6` sits above its `## 4` tells the AI reader the numbers lie. The order — 1 Why This Initiative · 2 Target User · 3 Features · 4 MVP Scope · 5 Success
+Metrics · 6 Cross-Cutting NFRs · 7 Constraints and Guardrails — and the `###` beneath them to match
+(`### 8.2` → `### 4.2`). Numbers are not sentences; leaving `## 4. Features` beside `## 8. MVP Scope`
+tells the next reader two sections went missing. A `UJ-N` the prose names that has no row in any requirement file is
+not given one — it is marked with an HTML comment where it stands and reported; `wdi-product`
+allocates ids. A moved sentence that cites a section number (`§ 8`) of a section this step deletes
+keeps the number — it is reported as wording for the owner, not repointed, because its new home is a
+judgment. `## 1. Vision` becomes `## 1. Why This Initiative`: delete only the sentences
+that also appear, word for word, in the brief's `Why`; what remains is left whole under an HTML comment
+saying the new shape wants a delta, because deciding which paraphrases are copies is the owner's. On a
+single-initiative product that is one line pointing at the brief — write it and say so.
+
+**5 — each SRS.** Every `| UC-` row MUST already be in `usecases.yaml` with the same `critical`. A row
+missing there is landed first. Then the table becomes the template's pointer line.
+
+**6 — each SDD.** In `## Inherited Constraints`, drop the `Quoted rule` column; keep `AD` and `How it
+lands here`. In the blockquote shape, drop the `> ` lines and the `Quoted verbatim from` sentence; keep
+the `**AD-N — title**` heading and the landing prose under it, each heading on its own line. An `AD-N`
+cited here that is not in the spine is a finding.
+
+**7 — C4 L2.** Every PC listed in the table MUST have that container in its `containers:`. Then the
+table becomes the pointer line.
+
+**8 — pointers at the moved pages.** Every `.md` that cites `.control/generated/brief.md`,
+`blueprint.md`, or `prd-<slug>.md` **and that `cites-resolve` reads** is repointed to the new path — a
+path substitution, nothing else in the sentence changes. That includes a product's own scratch and
+issue notes. It excludes what the validator excludes: `.control/memlog/`, `.control/decisions/`,
+`.control/reports/`, `questions/answered.md`, and `_bmad-output/` — those describe the past, and a
+path rewritten there falsifies a record; the installer's probe skips them for the same reason.
+
+## Step 4 — Render, then validate
+
+```bash
+uv run .constitution/method/scripts/validate.py --generate
+```
+
+This writes every reader's page into `.what-rendered/` and `.how-rendered/`, and clears the human pages
+that used to sit in `.control/generated/`. Then `--check` MUST be green. Every finding at this point is
+either a row that moved wrong in Step 2 or a pointer that points at nothing — both are this skill's to
+fix before it reports done.
+
+## Step 5 — Report, and commit once
+
+What moved, file by file · what was landed into the registry, by id · what could not be placed and
+needs the owner · the rendered pages now waiting to be read, one per gate · validators green. Then
+**one** commit: `chore(method): upgrade <from> → <to>`. Not one per document — the upgrade is one
+event.
+
+## Rules
+
+- You MUST NOT change a sentence while moving it. Wording that reads wrong in its new home is a
+  finding for the owning skill, later.
+- You MUST NOT invent a home. An `FR` no PRD cites, a Non-Goal neither boundary holds, an `AD-N` not
+  in the spine — each is reported by id and left where it was.
+- You MUST NOT write your findings into the corpus. A registry file carries rows and nothing about
+  the upgrade that produced them; a gap in this skill goes in the Step 5 report. The one exception is
+  the HTML comment the steps above name, placed where the owner will read the document.
+- You MUST NOT re-cut `specs.yaml`. That is `wdi-build`'s, where a human can see it.
+- You MUST NOT touch `.control/decisions/` or `.control/reports/`. A frozen `DEC-` that cites `V26` or
+  `W3` is history; the alias rule in `corpus-guide.md` covers it.
+- Re-running on an upgraded repo MUST find nothing and say so. Every probe in Step 1 is idempotent.
+
+## Output
+
+The Step 1 checklist with each item marked done · skipped (already new shape) · left for the owner, with
+the id list for the last · the registry rows landed · **statements landed / FR blocks that had a
+paragraph** · consequences moved · `questions/` rows added and rows found already present · proof-of-done
+divergences, both texts · the path of every rendered page · the validator result · the commit.

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

@@ -9,9 +9,28 @@ description: Use when UX is produced or landed — dispatching bmad-ux for a PRD
 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.
+**A run needs a PRD and nothing else.** It MUST NOT wait for Product Components, and a skill that made
+it wait would deadlock the whole flow: G2 reads `EXPERIENCE.md` — `ux-guide.md` § Passing G2 — and
+`wdi-init` intent `component` requires **G2 passed**. UX before components is not a preference; it is the
+only order that closes.
+
+    PRD  →  UX runs  →  **G2**  →  components born  →  G3
+
+Two acts: **run** the UX, and **land** it. A run is complete the moment the three documents are written.
+Landing is split by what each half's path actually needs, and only one half waits:
+
+| Lands | Needs | So it lands |
+|---|---|---|
+| `design-system.md` → `.how/_platform/` | nothing but the run being final — it crosses components by definition | **immediately**, at G2 |
+| `EXPERIENCE.md` → `.what/<pc>/04-usecases/` | the `<pc>` in its path to exist | when components are born |
+| `DESIGN.md` → `.how/<pc>/01-ux/` + screen `LC` rows | the same `<pc>`. **Not a container** — see below | when components are born |
+
+**The wait is a path, not a rule**, and it is the only one left: those two paths literally contain
+`<pc>`, so there is nowhere to write them until a `<pc>` exists. Nothing else defers.
+
+**And the wait is not the owner's to remember.** `wdi-init` intent `component` lands whatever is waiting
+in `_bmad-output/ux/` in the same act as birthing the components — one pass, no tracked to-do. Report
+what is waiting and name that act; do not ask the owner to come back.
 
 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.
@@ -81,7 +100,7 @@ Check what came back against the guide. Report every failure; fix none of them b
 | 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.
+or `.how/` is corpus pollution, and `memlog-home` rejects it.
 
 ## Step 5 — Land, at two speeds
 
@@ -92,17 +111,22 @@ here is **when each one becomes possible**.
 |---|---|---|
 | 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.
+| `DESIGN.md` | `.how/<pc>/01-ux/` | The `<pc>` is registered. **The path has no container in it, so none is needed** |
+| Each screen | an `LC` of type `ui-screen` in `components.yaml` | The `<pc>` is registered. `container:` is left **empty** and filled at G3 |
+
+- **Nothing is deferred any more.** A run lands whole, in the pass that produced it. `DESIGN.md`
+  landing was coupled to the container because its screen `LC` rows need one — but the *file's* path,
+  `.how/<pc>/01-ux/`, has no container in it, and the two were never the same requirement.
+- **A screen `LC` is registered now with `container:` empty**, and MUST NOT be given a guessed one. `container-built`
+  is silent on an empty container until the `LC`'s own Product Component lists containers; from that
+  moment it is owed. `wdi-blueprint` intent `platform` fills every one of them in the same act as
+  registering the containers, so the debt closes at G3 without anyone tracking it.
 - 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.
+  without its `components.yaml` entry has been half-landed, and `lc-registered` 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.
@@ -133,7 +157,7 @@ Everything in a UX pass — the run and the landing — logs to `.control/memlog
 - 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
+- You MUST NOT land anything into a spec that is already closed. The spec 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`.

package/kit-overlay/AGENTS.md

@@ -112,7 +112,7 @@ derived from the other: one component MAY be thin on purpose and reviewed the ha
 `.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
+## The five gates and the sixteen skills
 
 | Gate | Decides | Skill |
 |---|---|---|
@@ -137,7 +137,7 @@ verifies the result, and lands the memlog.
   fixed in the WDI Method package, then brought here with `npx wdi-method update`.
 - A file in `_bmad-output/prior-knowledge/` MUST NOT be copied into `.what/` or `.how/`. It enters
   the corpus only through the skill that owns the slot.
-- `.control/generated/` MUST NOT be written by hand — it is the output of `validate.py` and
+- `.control/generated/`, `.what-rendered/`, and `.how-rendered/` MUST NOT be written by hand — they are the output of `validate.py` and
   `timeline.py`.
 - The two structure maps in `.control/` MUST NOT be edited by hand — `wdi-init` intent `structure`
   re-derives them.

package/kit-overlay/README.md

@@ -1,75 +1,76 @@
----
-status: Reference
----
-
-# `.constitution/method/` — index
-
-`.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 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.
-
-## `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 |
-|---|---|
-| [`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
-
-| File | Loaded when |
-|---|---|
-| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
-| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
-| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
-| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
-
-## `document/` — document rules
-
-| File | Governs |
-|---|---|
-| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
-| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
-| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
-| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
-| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
-| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
-| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
-| [`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 |
-
-## Code rules — in the room, not here
-
-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`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
-
-## `scripts/`
-
-`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
-dimension from git history. `inventory.py` — compares the three inventories against the code
-and reports the difference; it MUST NOT patch either side into agreement. It reads no code itself:
-the patterns live in `../project/inventory-readers.py`, because comparing is generic and reading a
-stack is not. That file ships as a skeleton and `wdi-init` intent `readers` writes it for the repo
-in front of it. All three run through `uv run`.
+---
+status: Reference
+---
+
+# `.constitution/method/` — index
+
+`.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 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.
+
+## `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 |
+|---|---|
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, sixteen 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/mode-risk-map.md`](why/mode-risk-map.md) | A `mode` and a `risk_accepted` are set and you want the two side by side — all twelve cells |
+| [`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
+
+| File | Loaded when |
+|---|---|
+| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
+| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
+| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
+| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
+
+## `document/` — document rules
+
+| File | Governs |
+|---|---|
+| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
+| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
+| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
+| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
+| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
+| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
+| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
+| [`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 |
+
+## Code rules — in the room, not here
+
+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`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
+
+## `scripts/`
+
+`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
+dimension from git history. `inventory.py` — compares the three inventories against the code
+and reports the difference; it MUST NOT patch either side into agreement. It reads no code itself:
+the patterns live in `../project/inventory-readers.py`, because comparing is generic and reading a
+stack is not. That file ships as a skeleton and `wdi-init` intent `readers` writes it for the repo
+in front of it. All three run through `uv run`.

package/kit-overlay/constitution.md

@@ -23,6 +23,7 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 | `.control/` | Control — what currently holds and what has been decided |
 | `.what/` | What is promised |
 | `.how/` | How it is built |
+| `.what-rendered/` · `.how-rendered/` | The two above, assembled for a human to read — one page per gate, at the mirror path. Regenerated by `validate.py`, never edited, never read by a skill |
 | `_bmad-output/` | Run workspace; committed, not curated |
 | `.work/` | Scratch; committed, emptied when a task closes |
 | *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |
@@ -49,7 +50,7 @@ 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/why/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
+`method/why/` holds five 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.

package/kit-overlay/portability.md

@@ -28,7 +28,7 @@ them only an *example* does — not a rule.
 | `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`,
+Everything else — the five gates, the two fields, the sixteen skills, the templates, `validate.py`,
 `inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
 
 One half-exception, and it is by design: `inventory.py` is the generic engine and carries whole, but

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "wdi-method",
-  "version": "0.5.13",
-  "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": "^1.7.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.6.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",
+    "!**/__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": "^1.7.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/product-glossary.md

@@ -5,7 +5,7 @@
 The SSOT for **product** vocabulary — what this product talks about. Every term is defined **once**
 here, then used as-is across the corpus.
 
-**Method** vocabulary lives in `.constitution/method-glossary.md` and MUST NOT be redefined here. The
+**Method** vocabulary lives in `.constitution/method/method-glossary.md` and MUST NOT be redefined here. The
 split test: does this term still hold if used in another product? Yes → `method-glossary.md`, no →
 here.
 

package/scaffold/.control/registry/goals.yaml

@@ -0,0 +1,25 @@
+# goals.yaml — SSOT for BG, the product's goals. Nothing else lives here.
+#
+# Keys are English; prose values follow the product's chosen `doc_language`.
+#
+# ONE FILE, ONE WRITER, ONE GATE. This file is `wdi-problem`'s, written at G1 when the brief lands.
+# CAP, FR, NFR, and UJ all belong to an initiative instead, and live in
+# `requirements-<slug>.yaml` — the slug being that PRD's own folder name under `.what/_prd/`.
+# That file is `wdi-product`'s, written at G2.
+#
+# `CAP` is NOT here, and the reason is worth writing down because the opposite was tried first: a
+# capability is declared by a feature, one feature is one capability, and a feature lives in exactly
+# one PRD. The argument for keeping CAP at the product level was that `depends_on` between
+# capabilities crosses initiatives — but that buys nothing, because every validator reads the MERGED
+# view of all requirement files and never opens one by name. A cross-file `depends_on` resolves
+# exactly as well as a same-file one.
+#
+# IDS ARE ALLOCATED ONCE AND THE SEQUENCE IS GLOBAL TO THE PRODUCT. `FR-12` means one thing in this
+# repo no matter which file holds it — that is what lets a ticket say `satisfies: [FR-12]` without
+# also naming the PRD. `id-allocated-once` fails when two files declare the same id.
+
+goals: []
+# - id: BG-1
+#   title: "one line, the outcome the product exists for"
+#   measure: "how you would know it held"
+#   why: "only when the reason is not already carried by the brief's The Problem"

package/scaffold/.control/registry/index.yaml

@@ -16,7 +16,7 @@ product:
 #   guarded  + Failure Behaviour for every boundary, Inherited Constraints, integration documents
 #   deep     + ABCE, a contract spec per endpoint, data dictionary, flow, state machine, scenarios
 # Defaults to `catalog` when this line is absent. A component's own row in components.yaml WINS over this.
-# There is no third scope: `mode` MUST NOT be overridden per wave or per SPEC.md.
+# There is no third scope: `mode` MUST NOT be overridden per spec or per `SPEC.md`.
 mode: catalog
 
 # GATES ALREADY PASSED. Written only by the repo owner's own decision at their own gate, and MUST NOT
@@ -38,9 +38,9 @@ question_budget:
   blocking_per_component: 3
   assumptions_per_gate: 15
 
-wave_sizes:
-  S: { stories: "<=3", note: "no new FR; G4 and G5 merge into one 20-minute session" }
-  M: { stories: "4-12", note: "as usual" }
-  L: { stories: ">12",  note: "or a new container; a retrospective runs" }
+spec_sizes:
+  S: { tickets: "<=3", note: "no new FR; G4 and G5 merge into one session; no SPEC.md is written" }
+  M: { tickets: "4-12", note: "SPEC.md is written first — seams and testing decisions settled before tickets are cut" }
+  L: { tickets: ">12",  note: "or a new container; otherwise as M" }
 
 touches_vocabulary: []