wdi-method 0.5.13 → 0.6.0

package/kit/.constitution/method/document/templates/ux.md

@@ -1,77 +1,76 @@
----
-type: ux
-component: '{pc}'
-document: design             # design (.how/<pc>/01-ux/) · experience (.what/<pc>/04-usecases/)
-created: '{YYYY-MM-DD}'
-updated: '{YYYY-MM-DD}'
----
-
-# {DESIGN | EXPERIENCE} — {Product Component}
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     bmad-ux produces TWO documents, and they fall in two different layers. This template covers
-     both; set `document` and keep only that half.
-
-       DESIGN.md      → .how/<pc>/01-ux/          visual: tokens, components, layout
-       EXPERIENCE.md  → .what/<pc>/04-usecases/   behaviour: IA, states, journeys, accessibility
-
-     Keeping them in one file — as most projects do — makes a button-colour change and a flow change
-     look equally weighty. They are not.
-
-     Neither lands by itself. bmad-ux writes to _bmad-output/ux/ and wdi-ux lands it. Base
-     tokens and shared elements do NOT stay per-component; they go to
-     .how/_platform/design-system.md. -->
-
-## DESIGN — visual
-
-<!-- Keep only when document: design. -->
-
-### Tokens
-
-<!-- What is component-specific. Anything reusable MUST be promoted to design-system.md instead —
-     a token defined twice is a token that will diverge. -->
-
-### Screens
-
-<!-- One row per screen. Each MUST be registered as an LC of type ui-screen in components.yaml —
-     wdi-ux does this in the same act as landing the screen, and V12 checks it at wave close. -->
-
-| Screen | LC | Purpose |
-| --- | --- | --- |
-
-### Layout and states
-
-<!-- Per screen: the states it can be in — empty, loading, error, populated. The empty and error
-     states are the ones that get skipped and the ones users hit first. -->
-
----
-
-## EXPERIENCE — behaviour
-
-<!-- Keep only when document: experience. This half is WHAT, not HOW: it says what the user can do
-     and what the system answers, in human language, with no visual detail. -->
-
-### Information architecture
-
-<!-- Top-level surfaces and how someone moves between them. -->
-
-### Journeys
-
-<!-- Reference UJ-N from the PRD rather than restating them; add only what the PRD left implicit —
-     screen order, entry state, what tells the user the value landed. -->
-
-### Behaviour per surface
-
-| Surface | User can | System answers |
-| --- | --- | --- |
-
-### Accessibility
-
-<!-- What MUST hold: contrast, focus order, target size, screen-reader labelling, motion. State the
-     standard being met, not the intention to meet one. -->
-
-### Edge cases
-
-<!-- Real failure moments and what the user does next. One per row; the ones worth writing are the
-     ones a designer would rather not think about. -->
+---
+type: ux
+component: '{pc}'
+document: design             # design (.how/<pc>/01-ux/) · experience (.what/<pc>/04-usecases/)
+created: '{YYYY-MM-DD}'
+---
+
+# {DESIGN | EXPERIENCE} — {Product Component}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     bmad-ux produces TWO documents, and they fall in two different layers. This template covers
+     both; set `document` and keep only that half.
+
+       DESIGN.md      → .how/<pc>/01-ux/          visual: tokens, components, layout
+       EXPERIENCE.md  → .what/<pc>/04-usecases/   behaviour: IA, states, journeys, accessibility
+
+     Keeping them in one file — as most projects do — makes a button-colour change and a flow change
+     look equally weighty. They are not.
+
+     Neither lands by itself. bmad-ux writes to _bmad-output/ux/ and wdi-ux lands it. Base
+     tokens and shared elements do NOT stay per-component; they go to
+     .how/_platform/design-system.md. -->
+
+## DESIGN — visual
+
+<!-- Keep only when document: design. -->
+
+### Tokens
+
+<!-- What is component-specific. Anything reusable MUST be promoted to design-system.md instead —
+     a token defined twice is a token that will diverge. -->
+
+### Screens
+
+<!-- One row per screen. Each MUST be registered as an LC of type ui-screen in components.yaml —
+     wdi-ux does this in the same act as landing the screen, and `lc-registered` checks it at spec close. -->
+
+| Screen | LC | Purpose |
+| --- | --- | --- |
+
+### Layout and states
+
+<!-- Per screen: the states it can be in — empty, loading, error, populated. The empty and error
+     states are the ones that get skipped and the ones users hit first. -->
+
+---
+
+## EXPERIENCE — behaviour
+
+<!-- Keep only when document: experience. This half is WHAT, not HOW: it says what the user can do
+     and what the system answers, in human language, with no visual detail. -->
+
+### Information architecture
+
+<!-- Top-level surfaces and how someone moves between them. -->
+
+### Journeys
+
+<!-- Reference UJ-N from the PRD rather than restating them; add only what the PRD left implicit —
+     screen order, entry state, what tells the user the value landed. -->
+
+### Behaviour per surface
+
+| Surface | User can | System answers |
+| --- | --- | --- |
+
+### Accessibility
+
+<!-- What MUST hold: contrast, focus order, target size, screen-reader labelling, motion. State the
+     standard being met, not the intention to meet one. -->
+
+### Edge cases
+
+<!-- Real failure moments and what the user does next. One per row; the ones worth writing are the
+     ones a designer would rather not think about. -->

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

@@ -1,99 +1,115 @@
----
-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.
+---
+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 MUST NOT wait for a `<pc>`, and MUST NOT be blocked on one.** The order is PRD → UX → **G2**
+  → components, and it is forced: G2 reads `EXPERIENCE.md` (below), while `wdi-init` intent `component`
+  requires G2 passed. Making a run wait for components closes that into a cycle nothing can open.
+- **`design-system.md` lands at G2**, immediately. It crosses components by definition and its path has
+  no `<pc>` in it.
+- **`EXPERIENCE.md` and `DESIGN.md` wait, and only because their paths contain `<pc>`.** That is the one
+  remaining deferral in the flow, and it is not the owner's to remember: `wdi-init` intent `component`
+  lands them in the same act as birthing the components.
+- **A container is not required to land UX.** `.how/<pc>/01-ux/` has no container in its path; only a
+  screen's `LC` row needs one, and that row is registered with `container:` empty and filled at G3 by
+  `wdi-blueprint` intent `platform`, in the same act that registers the containers. `container-built` stays silent on
+  an empty container until the `LC`'s Product Component lists one — the answer is demanded when it
+  exists, not when it is thinnest.
+
+`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 `lc-registered` catches it **at spec 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 use `.control/product-glossary.md` verbatim **where an
+entry exists**. A new domain noun introduced by a UX run MUST be routed to `wdi-question` and listed in
+the run's report.
+
+**It MUST NOT be added to the glossary in the same pass, because it cannot be.** The glossary belongs to
+`wdi-blueprint` intent `catalog`, which needs Product Components, which need G2 passed — and this run is
+what G2 reads. The rule used to say "added in the same pass" and was unsatisfiable at the only moment it
+applied; a UX run failing that check was reporting the method, not the product. `wdi-blueprint` writes
+the entries at G3 and closes those questions there.
+
+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/method/language-guide.md

@@ -55,7 +55,7 @@ Nothing else about language is a setting, and a skill MUST NOT ask:
 - **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
+both languages — `validate.py` matches `yes|ya`, and `high-risk-named`'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.
 

package/kit/.constitution/method/method-glossary.md

@@ -20,7 +20,7 @@ reverse holds too. The test: would this term still apply on a different product?
 | **`.what/`** | What was promised |
 | **`.how/`** | How it is built |
 | **Workspace** | `_bmad-output/` — work in progress, committed but not curated |
-| **Placement test** | Is this file still true after its wave has passed? Yes → corpus. No → workspace |
+| **Placement test** | Is this file still true after its spec has passed? Yes → corpus. No → workspace |
 
 ## Units
 
@@ -29,7 +29,7 @@ reverse holds too. The test: would this term still apply on a different product?
 | **Product Component** (PC) | A domain slice — the box at C4 L3. Lives in `.what/<pc>/` and `.how/<pc>/`, and its `containers:` says where it runs |
 | **Logical Component** (LC) | One addressable unit of build. Registered in `components.yaml` with `type` · `container` · `owner` · `area` |
 | **Container** | Something that **runs its own code or stores its own data** and can be replaced without rebuilding another one. The C4 L2 term, and the value of an LC's `container` field. Two questions decide it and both MUST be yes — `architecture-guide.md` owns the test. Shipping two containers in one release does **not** merge them |
-| **`built`** | A container's one boolean. `true` when we write what is inside it, `false` when we deploy someone else's implementation. It decides whether the container gets an L3, an `LC`, and a heading in the codebase map — V25 checks all three |
+| **`built`** | A container's one boolean. `true` when we write what is inside it, `false` when we deploy someone else's implementation. It decides whether the container gets an L3, an `LC`, and a heading in the codebase map — `container-built` checks all three |
 | **External system** | Something the product talks to whose **runtime we do not deploy**. It belongs at C4 L1, and MUST NOT be a container, an `LC`'s `container`, or a heading in the codebase map. What we lean on it for lives in `cross-cutting.md` or an integration contract |
 | **`_platform`** | **Not a component.** The home for what belongs to no Product Component: the spine, the C4 set, `cross-cutting.md`, the three inventories, and whatever it **owns**. A legitimate value in every position that asks which component owns something — `platform_owns`, an inventory row, an `LC`. Four kinds today: data · endpoint · job · screen. It carries no `mode`, no `risk_accepted`, and no G4 |
 | **Library** | An includable artifact — compiled into or imported by something else, never run on its own. Not a container |
@@ -52,10 +52,10 @@ there is only Product Component.
 | **`mode`** | The one knob for **document depth**, and nothing else. `catalog` · `outline` · `guarded` · `deep`, default `catalog`. Two scopes — global in `index.yaml`, per component in `components.yaml`, and the per-component one wins. **No third scope** |
 | **`risk_accepted`** | The one field for **review intensity**, and nothing else. `low` · `medium` · `high`. It MUST NOT be derived from `mode`, nor `mode` from it |
 | **Blueprint** | The whole-product portrait decided once at G3: one line per use case, table, endpoint, and screen, plus entities, actors, the spine, C4, and cross-component rules. It names a **gate and a skill**, never a document or a folder |
-| **Wave** | One unit of delivered work. Opens at G4 or G5, closes at G5, recorded in `waves.yaml` |
-| **Release** | What a PRD promises. One release MAY span several waves; the relation is data, never inferred from numbering |
-| **Wave size** | `S` ≤3 stories no new FR · `M` 4–12 · `L` >12 or a new container. MAY be raised mid-flight, MUST NOT be lowered. It does **not** choose which gates are active — that is `mode` |
-| **Fast Path** | A fix that skips all gates: ≤1 story, no FR/UC/`AD-N`/domain-model change, no money, personal data, or third-party integration |
+| **Spec** | One unit of delivered work: the tickets that reach one outcome. Opens at G4 or G5, closes at G5, recorded in `specs.yaml`. Its document is `SPEC.md`, **optional at size `S`** — one term, one entry, and the document is named after the unit the way a `DEC-` file is named after its decision |
+| **Release** | What a PRD promises. One release MAY span several specs; the relation is data, never inferred from numbering |
+| **Spec size** | `S` ≤3 tickets no new FR · `M` 4–12 · `L` >12 or a new container. MAY be raised mid-flight, MUST NOT be lowered. It does **not** choose which gates are active — that is `mode`. It decides two things: whether G4 and G5 merge into one session (`S`), and whether `SPEC.md` is written at all (`M` and up) |
+| **Fast Path** | A fix that skips all gates: ≤1 ticket, no FR/UC/`AD-N`/domain-model change, no money, personal data, or third-party integration |
 | **Step** | One of the five points inside `wdi-build`'s ship pipeline — plan · build · panel · publish · CI. It is **not** a gate and not a stage, and the word MUST NOT be used for anything at gate altitude |
 
 ## Artifacts
@@ -72,8 +72,8 @@ there is only Product Component.
 | **`DESIGN.md`** | UX per PC, in `.how/<pc>/01-ux/` |
 | **`EXPERIENCE.md`** | The user-facing journey, in `.what/<pc>/04-usecases/` |
 | **`DEC-`** | One decision worth remembering, numbered globally. Lives in `.control/decisions/`. Recording is **not mandatory**; it freezes at `applied`, not at `accepted` |
-| **SPEC** | The machine contract for **one wave**. A projection of `.what/` + `.how/`, and MUST NOT contain anything new. Not read by humans |
-| **Story** | One unit of build. Status is read from its own frontmatter, never copied elsewhere |
+| **SPEC** | The document of **one spec**: a projection of `.what/` + `.how/` that MUST NOT contain anything new. Not read by humans, and **not written at size `S`** — there the tickets are the contract |
+| **Ticket** | One unit of build: a tracer-bullet vertical slice, complete through every layer, verifiable on its own, sized to one fresh context window. Carries the tickets that **block** it. Status is read from the ticket itself, never copied elsewhere |
 | **Structure map** | `.control/structure-codebase.md` and `structure-document.md` — where things actually are today |
 | **Memlog** | The record of *why* while an artifact was written. Never copied into a document; a source when writing a `DEC-`. It is a **run log**, and it MUST NOT be searched as an index of decisions — `.control/generated/decisions.md` is that |
 
@@ -87,14 +87,14 @@ there is only Product Component.
 | `DEC-` | A decision |
 | `LC-` | A Logical Component |
 | `OQ-` | An open question |
-| `RTR-` | An archived retrospective, in `.control/reports/` |
+| `RTR-` | **Retired.** It was an archived retrospective in `.control/reports/`; the retrospective step and `V19` went together. A frozen `RTR-` file stays where it is |
 | `CAP-` | A capability — the planning unit |
 | `NT-` | A non-technical fact |
 | `BUG-` · `HOT-` | A defect · a hotfix |
-| `V1`–`V25` | Validators. `V10` fell and its number is not reused |
+| `goal-has-fr`–`container-built` | Validators. `V10` fell and its number is not reused |
 
 IDs are allocated **globally** and never restart per document, per component, or per release. The chain
-that must hold end to end: `BG → FR → UC → story → test`.
+that must hold end to end: `BG → FR → UC → ticket → test`.
 
 `ADR-` is **retired**. It was renamed to `DEC-` on 2026-08-18 with the numbers unchanged, so `ADR-004`
 inside a document frozen before that date is an alias for `DEC-004`, and those documents MUST NOT be
@@ -116,10 +116,10 @@ where BMad's own meaning is wider, the narrower one here wins.
 
 | Term | Means |
 |---|---|
-| **Stories mode** | The route this method uses: SRS + SDD + PRD → `SPEC.md` + `stories.yaml` → build |
+| **Stories mode** | **Retired.** It was BMad's route — `SPEC.md` + `stories.yaml` produced by `bmad-spec`. The engine layer below G5 no longer runs it; `bmad-guide.md` says what replaced it |
 | **Skill class** | `A` living document, straight to the corpus · `B` living but wrongly granular, lands neutral then is placed · `C` spent after its work · `D` no artifact |
 | **Companion** | A side file a BMad skill produces next to its main output. The lasting ones are promoted by the distillation table |
-| **Distillation** | Promoting what is durable out of `_bmad-output/` before a wave closes. What is not promoted dies with the folder |
+| **Distillation** | Promoting what is durable out of `_bmad-output/` before a spec closes. What is not promoted dies with the folder |
 | **`persistent_facts`** | Files a skill always reads. Routing alone does not achieve this |
 | **`doc_standards`** | Rule files a skill checks its output against. Facts MUST NOT be installed here, and neither MUST anything at `status: Reference` |
 | **`{project_knowledge}`** | The config variable pointing at `.control/` |
@@ -134,7 +134,7 @@ where BMad's own meaning is wider, the narrower one here wins.
 | `SCP-` | A `DEC-` of `type: course-correction` |
 | `layer:` on a decision | `touches:`, filled from what actually changed |
 | "Stage 1"…"Stage 5" as flow vocabulary | The five gates |
-| `epics.md` · `sprint-status.yaml` · `bmad-sprint-planning` · `bmad-create-epics-and-stories` | The stories route: `SPEC.md` + `stories.yaml`, status in story frontmatter |
+| `epics.md` · `sprint-status.yaml` · `bmad-sprint-planning` · `bmad-create-epics-and-stories` · `stories.yaml` | Tickets, each carrying its own status and its blocking edges |
 | Validator `V10` | Nothing. Its number is not reused |
 | `bmad-help` as the answer to "where am I" | `wdi-help` |
 | The skills `wdi-analysis` · `wdi-architecture` · `wdi-design` · `wdi-glossary` · `wdi-structure` · `wdi-apply` · `wdi-correct-course` · `wdi-wave` · `wdi-ship-story` · `wdi-product-brief` · `wdi-meeting` · `wdi-project-log` | The fifteen in `why/README.md`. `why/rationale.md` says which absorbed which, and why |
@@ -149,14 +149,27 @@ A synonym for a term that already has an entry is drift, and `wdi-reconcile` hun
 | application · app · service, for a deployable | **container** | The term is already defined at C4 L2 and carried by every LC |
 | infrastructure · third-party · dependency, for something inside the boundary | **container** with `built: false` | Calling it something else is how a container ends up with no row, no owner, and no NFR |
 | container, for something whose runtime we do not deploy | **external system** | It has no `built`, no L3, and no heading. Registering it as a container promises a section of the codebase map that will never exist |
-| module · package, for a unit of build | **Logical Component** | `components.yaml` names it, and V12 resolves against that name |
-| epic · sprint, for a batch of work | **wave** | Both belong to the sprint route this method dropped |
+| module · package, for a unit of build | **Logical Component** | `components.yaml` names it, and `lc-registered` resolves against that name |
+| epic · sprint, for a batch of work | **spec** | Both belong to the sprint route this method dropped |
+| **wave**, for a unit of delivered work | **spec** | Retired when the engine layer below G5 changed. See the retired-alias rule below |
+| **story**, for a unit of build | **ticket** | Same retirement. A ticket is a vertical slice that blocks and is blocked; a story was a row in a file BMad owned |
 | area, for a domain slice | **Product Component** | The word "area" is not used anywhere in this method |
 | platform, for a Product Component | **`_platform`**, and only for what is not one | Registering `_platform` as a PC gives it a `mode`, an SRS, and a G4 it has no use for |
 | profile · tier · level, for document depth | **`mode`** | One knob, four values, and no matrix behind it |
 | feature, for a domain slice | **Product Component** | A feature is a promise; a PC is a folder pair with an owner |
 | requirements document | **PRD** or **SRS** | They cut different axes — time versus space — and merging the names merges the documents |
 
+## Retired terms keep their frozen documents
+
+`wave` and `story` are **retired aliases** of `spec` and `ticket`. A `wave` or a `story` appearing in a
+document frozen before the change — a closed `DEC-`, an `RTR-`, minutes, `why/rationale.md`'s record of what
+happened — reads as its replacement, and those documents **MUST NOT be rewritten for the term.** This is the
+same rule Article 6 already applies to `ADR-NNN` → `DEC-NNN`, and for the same reason: a frozen record that
+cites a name is evidence, and rewriting evidence to tidy a vocabulary destroys the thing that made it useful.
+
+What MUST use the new term: every `Accepted` guide, every skill, every registry, and anything written from
+here on.
+
 ## Rules
 
 - A new method term MUST be added here in the same pass it first appears, not defined where it is