wdi-method 0.5.13 → 0.6.0

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

@@ -12,22 +12,55 @@ file somewhere this method cannot use.
 
 The per-skill read/write map lives in `bmad-skill-register.md` and MUST NOT be duplicated here.
 
-## Stories mode only
+## Neither of BMad's two routes
 
-BMad offers two routes. We run one.
+BMad offers a sprint route and a stories route. This method ran the stories route, and **now runs
+neither.** The engine layer below G5 is `to-spec`, `to-tickets`, `implement`, `tdd`, and `code-review`;
+`wdi-build` owns the transition and states which BMad engines are retired.
 
-| | Sprint route | **Stories route — ours** |
+What survived the change is the **reason** the sprint route was dropped, because it is the same reason
+`ticket-status-one-home` still exists. That route keeps status in one hand-edited file: two builders running in parallel
+contend for it, and status becomes something a builder declares about itself. Status is read from the
+ticket instead, and it MUST NOT be copied into `specs.yaml`.
+
+| Route | Status home | Why not |
 |---|---|---|
-| Planning artifact | `epics.md` | `.what/<pc>/SRS-<pc>.md` + `SPEC.md` + `stories.yaml` |
-| Status home | `sprint-status.yaml` | Story-file frontmatter |
-| Produced by | `bmad-create-epics-and-stories` · `bmad-sprint-planning` | `bmad-spec` |
+| Sprint | `sprint-status.yaml` | One hand-edited file, contended, self-declared |
+| Stories | story-file frontmatter | Its author, `bmad-spec`, is retired |
+| **Ours** | **the ticket itself** | — |
 
 `bmad-create-epics-and-stories` and `bmad-sprint-planning` are **NOT USED**. Neither MUST be invoked,
 and neither MUST be named as a gate condition.
 
-The sprint route was dropped because it keeps status in a hand-edited file. Two workers running in
-parallel then contend for one file, and status becomes something a worker declares about itself.
-Reading status from story-file frontmatter removes both problems — V18 checks it.
+## When an engine earns being invoked at all
+
+BMad is a **dependency of this package**: the installer checks for it, `--skip-bmad-check` exists to say so
+out loud, and five artifacts here have no other author. Any *further* engine is a different question, and it
+has one test:
+
+> **Does it produce something this corpus keeps?**
+
+Yes → it MAY be wrapped, and the wrapper rule applies: invoked through the WDI skill that owns the artifact,
+which checks position, verifies against the guide, and lands the result in this method's template. A
+non-BMad engine is named in **that skill**, never in `bmad-skill-register.md` — that register is BMad's
+inventory, and putting somebody else's skill in it makes the register a lie.
+
+No → **absorb the discipline and invoke nothing.** Prose we could have written is not an engine.
+
+An engine whose output this corpus keeps is invoked even when it is a **plugin rather than part of this
+package's install** — `mattpocock-skills:domain-modeling` is the case, and `wdi-blueprint` invokes it. Two
+rules make that safe in a repo that does not have it:
+
+- **A missing plugin is a state, not a defect.** Report it once, name the standard the work is still held
+  to, and do the work. You MUST NOT block a gate on it, and you MUST NOT report its absence as a finding.
+- **The wrapper carries the standard, never the plugin.** What the engine is invoked *for* MUST be written
+  in the wrapping skill as behaviours to verify — so the same bar is met either way, and a run that
+  produced none of them is reported as a transcription rather than landed.
+
+An engine's **own** artifacts and tests are a separate matter, and the wrapping skill MUST name every one
+this corpus already has a home for. `wdi-blueprint` names four for `domain-modeling`, one of which —
+`docs/adr/` — is a folder **Article 3 forbids outright**. That is why an engine's write location is pointed
+somewhere safe **before** it runs rather than corrected after.
 
 ## Skill classes
 
@@ -35,7 +68,7 @@ The criterion is **lifetime**, not importance:
 
 | Class | Criterion | Output home |
 |---|---|---|
-| **A** | A living document, still correct after the wave | Straight into `.what/` or `.how/` |
+| **A** | A living document, still correct after the spec has passed | Straight into `.what/` or `.how/` |
 | **B** | Living, but its granularity is not configurable | Neutral `_bmad-output/` → the owner in `corpus-guide.md` lands it |
 | **C** | Ends when its work does | `_bmad-output/`, committed, not curated |
 | **D** | No artifact at all | — |
@@ -88,7 +121,7 @@ BMad skills call `--workspace` by default; the class-A home is reached by instal
 instruction as a `persistent_fact`.
 
 - A class-A or class-B skill MUST use `--path`. `--workspace` MUST NOT be used — it would leave a
-  `.memlog.md` inside `.what/` or `.how/`, which V16 rejects.
+  `.memlog.md` inside `.what/` or `.how/`, which `memlog-home` rejects.
 - Class-C memlogs stay beside their output in `_bmad-output/`.
 - Every memlog MUST carry `artifact:` in its frontmatter, pointing at a file that exists.
 
@@ -121,13 +154,13 @@ to whoever runs the repo and MUST NOT be copied between projects.
 `bmad-deep-recon`, and it runs two lenses: `structure` and `prose`.
 
 Everything else MUST be reviewed by invoking `wdi-review` explicitly — the spine, every SRS, every
-SDD, and every `SPEC.md`. Three lenses never fire on their own anywhere: `adversarial`,
+SDD, and every spec's contract. Three lenses never fire on their own anywhere: `adversarial`,
 `edge-case-hunter`, and `verification-gap`.
 
-**Code review does not use `bmad-review`.** `bmad-code-review` reads its lenses from a bundled copy
-under `review-prompts/`, and each layer ends with an instruction not to invoke any skill. An override
-placed on `bmad-review` is therefore **invisible** to code review. Getting the current lenses onto a
-diff requires calling `bmad-review` by hand.
+**Code review is not `bmad-review`, and it is not BMad's at all any more.** The panel over a diff is
+`code-review`, dispatched by `wdi-build`; it reviews along two axes, Standards and Spec, and both MUST
+run. An override placed on `bmad-review` reaches documents only. Getting a document lens onto a diff
+still requires calling `wdi-review` by hand, and that is a deliberate act, not a default.
 
 ## Renamed and retired
 
@@ -136,6 +169,7 @@ diff requires calling `bmad-review` by hand.
 | `bmad-create-prd` · `bmad-edit-prd` · `bmad-validate-prd` | Shims over `bmad-prd` — use the intent, not the shim |
 | `bmad-create-architecture` | `bmad-architecture` |
 | `bmad-create-epics-and-stories` · `bmad-sprint-planning` | **Not used** — sprint route |
+| `bmad-spec` · `bmad-build` · `bmad-build-auto` · `bmad-code-review` · `bmad-retrospective` | **Retired** — the engine layer below G5 is no longer BMad's. Their `_bmad/custom/*.toml` overrides are withdrawn, and `update` removes any still installed |
 
 Roughly a third of the installed skills are deprecated aliases. `bmad-skill-register.md` is the
 authority on which is which, and it MUST be consulted rather than guessed from a name that looks

package/kit/.constitution/method/document/bmad-skill-register.md

@@ -1,71 +1,74 @@
----
-status: Accepted
----
-
-# BMad Skill Register
-
-**Loaded when:** deciding which BMad skill a piece of work needs, or checking what one writes
-
-This used to be the full catalogue of all 59 installed BMad skills. **That catalogue is retired.** It was a
-copy of somebody else's inventory, it went stale on every BMad update, and nothing in this method read more
-than a dozen of its rows. What binds is the division of labour below; for anything about a BMad skill this
-method does not invoke, ask `bmad-help`, which reads BMad's own documentation.
-
-## Who writes what
-
-| Artifact | Written by | Wrapped in |
-|---|---|---|
-| Product brief | `bmad-product-brief` | `wdi-problem` |
-| PRD | `bmad-prd` | `wdi-product` |
-| UX — `EXPERIENCE.md` + `DESIGN.md` | `bmad-ux` | `wdi-ux` |
-| Architecture spine + the C4 set | `bmad-architecture` | `wdi-blueprint` intent `platform` |
-| **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.yaml` | `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 three 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 attach to those artifacts and
-MUST be handled deliberately rather than discovered: no `doc_standards` fires a review, no memlog is born on
-its own, and no template enforces itself.
-
-## No BMad skill is invoked directly
-
-Every one above has a wrapper, and the wrapper is what checks position, verifies the result against the
-guide, and lands the memlog. Routing past it produces an artifact nothing verifies.
-
-**One exception, and it is narrow:** `bmad-build` MAY be invoked directly on the Fast Path. A Fast Path that
-turns out to touch an `FR` MUST stop and become a wave `S`, which puts it back inside `wdi-build`.
-
-## What is available but writes nothing
-
-| Skill | Use |
-|---|---|
-| `bmad-advanced-elicitation` · `bmad-party-mode` | Thinking aids. They produce no artifact and MUST NOT be treated as authors |
-| `bmad-deep-recon` | Research, before a brief rests on outside data. Its output stays in `_bmad-output/` permanently and MUST NOT be folded into the brief |
-| `bmad-code-review` | The two-reviewer panel over code, dispatched by `wdi-build`. Not for documents |
-| `bmad-help` | Questions about BMad itself. It MUST NOT be used to answer "where am I" — that is `wdi-help` |
-
-## What is NOT USED, and MUST NOT be
-
-| Skill | Why |
-|---|---|
-| `bmad-create-epics-and-stories` · `bmad-sprint-planning` · `bmad-sprint-status` | They belong to the sprint route, which keeps status in a hand-edited file. This method reads status from story-file frontmatter — `bmad-guide.md` owns the reasoning |
-| `bmad-create-story` · `bmad-dev-story` · `bmad-quick-dev` · `bmad-dev-auto` | Deprecated in BMad itself; `bmad-build` and `bmad-build-auto` replace them |
-| `bmad-editorial-review*` · `bmad-review-*` | Shims onto `bmad-review` lenses. Ask for the lens, not the shim |
-| `bmad-document-project` · `bmad-generate-project-context` | Forward to `bmad-project-context`. This repo's agent instructions are maintained by hand |
-| Any skill named as a **gate condition** | A gate is passed by its checklist and its validators, never by a skill having run |
-
-## The class that decides where output lands
-
-`bmad-guide.md` owns the class definitions; what matters here is that **class B** exists because some skills
-write several things at once that belong to different layers. `bmad-ux` is the case: `EXPERIENCE.md` is a
-promise and `DESIGN.md` is a build detail, and no configuration can send them to two places. Its output
-lands in a neutral folder first, and `wdi-ux` places it.
-
-Which skill lands which output is the ownership table in `corpus-guide.md`, and it MUST NOT be duplicated
-here.
+---
+status: Accepted
+---
+
+# BMad Skill Register
+
+**Loaded when:** deciding which BMad skill a piece of work needs, or checking what one writes
+
+This used to be the full catalogue of all 59 installed BMad skills. **That catalogue is retired.** It was a
+copy of somebody else's inventory, it went stale on every BMad update, and nothing in this method read more
+than a dozen of its rows. What binds is the division of labour below; for anything about a BMad skill this
+method does not invoke, ask `bmad-help`, which reads BMad's own documentation.
+
+## Who writes what
+
+| Artifact | Written by | Wrapped in |
+|---|---|---|
+| Product brief | `bmad-product-brief` | `wdi-problem` |
+| PRD | `bmad-prd` | `wdi-product` |
+| UX — `EXPERIENCE.md` + `DESIGN.md` | `bmad-ux` | `wdi-ux` |
+| Architecture spine + the C4 set | `bmad-architecture` | `wdi-blueprint` intent `platform` |
+| **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 |
+| Document review | `bmad-review` | `wdi-review` |
+| Course correction | `bmad-correct-course` | `wdi-decision` |
+
+**Everything below G5 left this table.** `SPEC.md`, the tickets, the code, and the code panel are produced
+by `to-spec`, `to-tickets`, `implement`, `tdd`, and `code-review` — engines that are not BMad's, and that
+three of the five carry `disable-model-invocation: true` for, so **the owner runs them and no skill can**.
+`wdi-build` owns that pipeline; `bmad-guide.md` owns the reasoning.
+
+**The three 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 attach to those artifacts and
+MUST be handled deliberately rather than discovered: no `doc_standards` fires a review, no memlog is born on
+its own, and no template enforces itself.
+
+## No BMad skill is invoked directly
+
+Every one above has a wrapper, and the wrapper is what checks position, verifies the result against the
+guide, and lands the memlog. Routing past it produces an artifact nothing verifies.
+
+**One exception, and it is narrow:** on the Fast Path the owner runs `/implement` directly, with no wrapper.
+A Fast Path that turns out to touch an `FR` MUST stop and become a spec `S`, which puts it back inside
+`wdi-build`.
+
+## What is available but writes nothing
+
+| Skill | Use |
+|---|---|
+| `bmad-advanced-elicitation` · `bmad-party-mode` | Thinking aids. They produce no artifact and MUST NOT be treated as authors |
+| `bmad-deep-recon` | Research, before a brief rests on outside data. Its output stays in `_bmad-output/` permanently and MUST NOT be folded into the brief |
+| `bmad-help` | Questions about BMad itself. It MUST NOT be used to answer "where am I" — that is `wdi-help` |
+
+## What is NOT USED, and MUST NOT be
+
+| Skill | Why |
+|---|---|
+| `bmad-spec` · `bmad-build` · `bmad-build-auto` · `bmad-code-review` · `bmad-retrospective` | **Retired.** The engine layer below G5 is no longer BMad's. Their `_bmad/custom/*.toml` overrides are withdrawn and `update` removes any still installed |
+| `bmad-create-epics-and-stories` · `bmad-sprint-planning` · `bmad-sprint-status` | They belong to the sprint route, which keeps status in a hand-edited file. This method reads status from the ticket itself — `bmad-guide.md` owns the reasoning |
+| `bmad-create-story` · `bmad-dev-story` · `bmad-quick-dev` · `bmad-dev-auto` | Deprecated in BMad itself, and their replacements are retired too |
+| `bmad-editorial-review*` · `bmad-review-*` | Shims onto `bmad-review` lenses. Ask for the lens, not the shim |
+| `bmad-document-project` · `bmad-generate-project-context` | Forward to `bmad-project-context`. This repo's agent instructions are maintained by hand |
+| Any skill named as a **gate condition** | A gate is passed by its checklist and its validators, never by a skill having run |
+
+## The class that decides where output lands
+
+`bmad-guide.md` owns the class definitions; what matters here is that **class B** exists because some skills
+write several things at once that belong to different layers. `bmad-ux` is the case: `EXPERIENCE.md` is a
+promise and `DESIGN.md` is a build detail, and no configuration can send them to two places. Its output
+lands in a neutral folder first, and `wdi-ux` places it.
+
+Which skill lands which output is the ownership table in `corpus-guide.md`, and it MUST NOT be duplicated
+here.

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

@@ -30,14 +30,16 @@ MAY be dropped.
 
 | Section | Why it cannot be dropped |
 |---|---|
-| The Problem | The gate decides on this. Without it there is nothing to approve |
+| Why | The narrative the gate is read against. Without it there is nothing to approve |
+| The Problem | The gate decides on this |
 | Who This Serves | Names who the problem belongs to |
 | Goals | `BG-N` is the first link of the traceability chain; without it the chain has no root |
 | Success Criteria | The measure that makes "done" checkable |
 | Scope In / Scope Out | The boundary the PRD is later held against |
 | Constraints | What design MUST NOT trade away |
-| Assumptions | What the brief would be wrong without |
-| Prerequisites | What blocks work before it starts |
+
+`The Solution` and `What Makes This Different` stay optional — G1's seven questions never ask what is
+being built, only whether the problem is real and worth the cost.
 
 ## Decision rules
 
@@ -46,24 +48,45 @@ MAY be dropped.
   discovery is not finished and the gate MUST NOT open.
 - Every user and stakeholder who touches the product MUST appear in the table, including those who
   never open it — whoever pays for it, approves it, or is accountable for it.
+- **Success Criteria MUST name exactly one measurable figure**, with a timeframe. This is a ★
+  question at G1 and the section most often left as a mission statement instead — check 5 in
+  `wdi-problem` exists because nothing else caught this.
 - Goals MUST be numbered `BG-1`, `BG-2`, … and MUST NOT be numbered `G1`, `G2` — `G1`–`G5` name the
   five gates. `BG` IDs are cited downstream and MUST stay stable once written.
+- **Goals is a pointer, not a list.** The section states `Goals — see goals.yaml → goals:` and
+  nothing more. The statement for each `BG-N`, and an optional `why:` when a goal needs a reason
+  beyond its statement, are authored straight into `.control/registry/goals.yaml` — landing
+  that row is part of producing the brief, done by `wdi-problem` in the same pass, not a follow-up.
+  A goal's text written in this section as well as in the registry is the same fact with two homes,
+  and the copy people read is whichever they open first.
 - Scope Out MUST be written as items. Leaving it to be inferred from absence defeats its only
   purpose, which is naming what someone will otherwise assume is coming.
-- Per-release MVP scope belongs to the PRD, not here. This section states the product boundary.
+- Per-release MVP scope belongs to the PRD, not here. This section states the product boundary — what
+  belongs to the product at all, ever, not what ships first.
 
-## The three product-level sections
+## Constraints — the one product-level section still authored here
 
-BMad has no home for these; they exist because of that gap, and each has a rule about where it goes
-when it stops being a statement.
+BMad has no home for a product-wide constraint; this section exists because of that gap.
 
 | Section | Boundary | When it moves |
 |---|---|---|
 | Constraints | What is fixed before design starts. Technical constraints that only shape implementation belong in `addendum.md` | A constraint that emerges from a design decision becomes `AD-N` in the spine and MUST NOT be appended here later |
-| Assumptions | What is believed but unverified, stated so it could be proven false | An assumption that starts to wobble MUST become a row in `.control/registry/risks.yaml` with an owner |
-| Prerequisites | What MUST exist or be granted before work can start | Any prerequisite not yet satisfied MUST have a row in `.control/questions/external.md` naming who is being waited on and by when |
 
-An assumption nobody would act differently about is not worth listing.
+## No Assumptions or Prerequisites section
+
+Both are dropped from the brief entirely — they were the two sections with no home anywhere else in
+the corpus, and now they do:
+
+- An assumption goes through `wdi-question` into `.control/questions/assumptions.md`. State it so it
+  could be proven false; one that starts to wobble MUST become a row in
+  `.control/registry/risks.yaml` with an owner. An assumption nobody would act differently about is
+  not worth listing.
+- A prerequisite goes through `wdi-question` into `.control/questions/external.md`, naming who is
+  being waited on and by when.
+
+Neither is restated in the brief itself — the brief citing a row it does not own is exactly the second
+copy this section used to be. A reader who wants both assembled with everything else reads the
+generated deliverable, `.what-rendered/_product-brief/brief.md`, which renders the open rows from both files.
 
 ## No Product Component list
 
@@ -89,6 +112,14 @@ from, and every later gate inherits the guess.
 - The brief MUST have been through `bmad-review` lenses structure + prose before it reaches the
   gate. Gate time is for deciding, not for catching mistakes. This one fires on its own — it is the
   *Polish* step of `bmad-product-brief`, driven by `doc_standards`, and nobody invokes it. Verifying
-  that it actually ran is check 9 in `wdi-problem`.
+  that it actually ran is check 11 in `wdi-problem`.
 - Invoke through `wdi-problem`, not `bmad-product-brief` directly — the wrapper is what checks the
   rules on this page.
+
+## The generated deliverable
+
+A complete, self-contained copy for a reader who should not need to open the registry lives at
+`.what-rendered/_product-brief/brief.md` — written by `/wdi-report render brief`, which runs
+`validate.py --generate`. It assembles this document's own sections verbatim, the goals rendered from
+`goals.yaml`, and the open rows from `assumptions.md` and `external.md`. Nobody writes to it by
+hand — it is regenerated, never hand-patched, the same as `blueprint.md` and `decisions.md`.

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

@@ -23,12 +23,37 @@ be copied into this file.
 | `.what/` | What is promised | Living, amended | BMad class A + us |
 | `.how/` | How it is built | Living, amended | BMad class A + us |
 | `_bmad-output/` | Work in progress | Ends when the work does | BMad class B and C |
+| `.what-rendered/` · `.how-rendered/` | The same promise and shape, **assembled for a human to read** | Regenerated on every `render`; never edited | `validate.py --generate`, and nobody else |
 
 `.control/` is the value of `{project_knowledge}` in BMad's configuration. There is no `docs/`.
 
+### Two audiences, two trees
+
+`.what/` and `.how/` are the **working** trees: prose that cannot be a row, pointers to the registry for
+everything that can. They are what an agent reads and what a skill writes. They are deliberately thin
+for a human — `Goals` is one line, an `FR` is an id — because completeness is not their job.
+
+`.what-rendered/` and `.how-rendered/` are the **reader's** trees. Every file in them sits at the mirror
+path of the working document it projects — `.what-rendered/<pc>/SRS-<pc>.md` is
+`.what/<pc>/SRS-<pc>.md` with every pointer opened: the goal statements, the UC rows, the
+`AD-N` text, the open questions, all pulled in from their own homes. That is what a gate reads, and
+what a client receives.
+
+Three rules keep the two trees honest:
+
+- **A skill MUST NOT read a `-rendered` file as input.** It is output. The working document and the
+  registry are the source, and a skill that read the projection would be reading its own echo — a
+  `kit-integrity` test fails when any `SKILL.md` lists one in its `Inputs`.
+- **Nobody edits a `-rendered` file.** A defect seen there is a defect in the working document or the
+  registry, and that is where it is fixed. The next `render` overwrites the page.
+- **Every gate reads one rendered page, and that page MUST answer the gate's seven questions.** G1
+  reads `.what-rendered/_product-brief/brief.md`; G2 `.what-rendered/_prd/<slug>/prd.md`; G3
+  `.how-rendered/blueprint.md`; G4 `.how-rendered/<pc>/SDD-<pc>.md`. A question that cannot be
+  answered from the page is a gap in the page, not a reason to open a working file.
+
 ## The placement test
 
-One question decides everything: **is this file still correct after its wave has passed?**
+One question decides everything: **is this file still correct after its spec has passed?**
 
 Yes → the corpus. No → `_bmad-output/`.
 
@@ -60,9 +85,8 @@ part of producing it — never a follow-up someone else performs.
 | `DESIGN.md` | `.how/<pc>/01-ux/` | `wdi-ux` |
 | tokens and base components | `.how/_platform/design-system.md` | `wdi-ux` |
 | each screen in `DESIGN.md` | an `LC` of type `ui-screen` in `components.yaml` | `wdi-ux` |
-| `RETROSPECTIVE.md` | `RTR-<wave>.md` in `.control/reports/` | `wdi-build`, at wave close |
-| `test-summary.md` | test names → `waves.yaml` | `wdi-build` |
-| `stack.md` · `conventions.md` · `brownfield.md` | merged into `.constitution/project/codebase-*-guide.md` | `wdi-build`, at wave close |
+| The names of the tests a ticket went green on | the ticket's `tests` in `specs.yaml` | `wdi-build` |
+| What the spec settled about the stack, the conventions, or the brownfield reality | merged into `.constitution/project/codebase-*-guide.md` | `wdi-build`, at spec close |
 | A sprint change proposal | a `DEC-` of `type: course-correction` | `wdi-decision` |
 | The registry rows and skeletons a new PC needs | `components.yaml` · `.what/<pc>/` · `.how/<pc>/` | `wdi-init` intent `component` |
 | `platform_owns` — an entity no component's promise explains | `components.yaml`, plus its description in `cross-cutting.md` | `wdi-blueprint` |
@@ -73,13 +97,13 @@ part of producing it — never a follow-up someone else performs.
 
 - A skill MUST NOT write into a layer it does not own.
 - Registry conversion is part of landing, not a follow-up. A screen that lands in `01-ux/` without its
-  `components.yaml` entry has been half-landed, and V12 catches it **at wave close** — which is the
+  `components.yaml` entry has been half-landed, and `lc-registered` catches it **at spec close** — which is the
   right moment to be caught, and a bad moment to be surprised.
 - Content MUST NOT be edited while it is being landed. If it has to change to fit its new home, that is a
   separate act — say so and stop. Splitting one output across the homes its row names is not editing.
 - The C4 set's target files already exist and are **living**. Their owner MUST amend, MUST NOT overwrite; when
   the incoming set contradicts an annotation already there, it MUST stop and report the finding.
-- Nothing MAY be landed into a wave that is already closed. The wave is reopened through `wdi-build`, or the
+- Nothing MAY be landed into a spec that is already closed. The spec is reopened through `wdi-build`, or the
   gap is recorded as an open question.
 - An output with **no row** in this table MUST NOT be given a guessed home. It stays in `_bmad-output/`, and
   `wdi-reconcile` reports it — an output with no home is a gap in the method, and MUST surface as one.
@@ -168,7 +192,7 @@ would have to be withdrawn for the entity to stop being needed. Two examples of
 
 **One guard, and it is what stops this becoming a drawer:** everything `_platform` owns — in any position —
 MUST be described under `## Platform-owned` in `cross-cutting.md`, with its kind and the shape every toucher
-obeys. A platform that owns something documents it. V21 checks it, and skips only while that section has not
+obeys. A platform that owns something documents it. `entity-one-writer` checks it, and skips only while that section has not
 been born at G3.
 
 That guard is the whole reason `_platform` can be a general answer rather than an escape hatch: reaching for
@@ -187,6 +211,117 @@ judgements — so both are declared in that inventory's own frontmatter (`platfo
 survive every re-derivation. Putting either outside the file means the next derivation silently deletes the
 owner's decision.
 
+## A derived fact has exactly one home
+
+`why/rationale.md` has always carried this as principle 5 — *what can be derived is not written by hand.*
+It was never written as a rule anywhere, and that file binds nothing by its own terms. So it bound nothing,
+and only one field was ever actually protected: ticket status, by `ticket-status-one-home`.
+
+**A document MUST NOT state a fact that a registry, a generated file, or git already holds.** It cites the
+id and lets the reader follow it. The list is short and it is closed:
+
+| Never stated in prose | Where it lives |
+|---|---|
+| `mode` · `risk_accepted` · `g4_passed` | `components.yaml` |
+| Which `DEC-` bind this document — **including "none yet"** | `.control/generated/decisions.md` |
+| A count of `UC`, `FR`, `CAP`, or containers | the registry that holds them |
+| Which slots or files exist, and which are still empty | `.control/structure-document.md`, derived |
+| Whether an `OQ-` is open or answered | `.control/questions/` |
+| When the document last changed | git |
+
+**The remedy is DELETION, never correction.** This is the part that costs a corpus real time to learn: a
+restated fact that is corrected becomes a *second* stale fact, on a slower clock than the first. One SRS in a
+real repo carried three claims about its own `mode` on one page — the value, a correction block below it
+fixing an older value, and the slot list — and not one of the three was right. Correcting any of them would
+have added a fourth. Deleting all three ends it.
+
+A negative claim is the worst case and the easiest to miss, because it looks like diligence: *"No applied
+`DEC-` binds this component yet"* is true the day it is written and silently false forever after.
+
+**What is NOT a derived fact**, and MUST still be written where it belongs: a judgement the pattern cannot
+recompute (the paragraph above owns that), an `AD-N` citation — the spine's `binds:` is authored, not
+derived — and the *reason* something is the way it is, which no registry holds.
+
+## A pass writes one artifact
+
+When a skill is writing or updating an artifact, **that artifact is the pass.** Hunting the rest of the
+corpus for things that disagree with it is not part of writing it, and MUST NOT be folded in: it is
+`wdi-reconcile`'s job, it runs at a gate, and `wdi-review` § Stale is not a finding decides what is even
+worth reporting when it does.
+
+Where a contradiction surfaces anyway — and it will, because writing a document is how you notice — there
+are exactly two outcomes:
+
+| The other document is | Do |
+|---|---|
+| **Load-bearing wrong** — a reader would make the wrong repair | Say it in **one line** in the output, naming the file and the edit it needs |
+| Anything else | Nothing. Not a line, not an `OQ-`, not a `DEC-` |
+
+It MUST NOT become an open question, and it MUST NOT become a decision. A contradiction between two
+documents is an **edit** waiting for whoever owns the file — never a thing to be adjudicated.
+
+**This binds hardest at G1 and G2.** A brief is being formed; a PRD is being written. There is barely a
+corpus to be consistent with yet, and a pass that spends its budget looking for one is spending it on
+nothing.
+
+## One decided change is one edit pass
+
+Once the owner has decided, the chain is **applied**, not surveyed. The agent already knows what the
+change reaches — `touches:` names it, the ownership table in this file names who lands each part, and the
+RTM names the rows that move. It edits all of them in **one pass** and reports once.
+
+What MUST NOT happen: checking one document, reporting, waiting, checking the next; re-deriving the same
+relations in a later pass; or asking the owner to confirm the same decision at each file it touches. The
+documents are split for reading, not to be walked one at a time — and walking them is where the time and
+the tokens actually go.
+
+## The corpus is written in the present tense
+
+A design document states **what is true now**: the latest state of the design, and what still has to be
+reached. It does not state how it got there. This governs `.what/<pc>/`, `.how/`, and
+`.constitution/project/`.
+
+### Two kinds of history, and only one is worth writing
+
+Most history is not useful. What is useful is the current state — and the rare piece of history that
+**stops the same mistake happening twice**. One question separates them:
+
+> **Would someone about to make a change be saved by this line?**
+
+| Kind | Example | Where it goes |
+|---|---|---|
+| **Business or technical** — the mistake could recur | *"Files are removed before the record, and that left a document pointing at a deleted image"* | A `DEC-`, `why/`, or `answered.md`. Rarely, and only when it earns it |
+| **Document history** — a document said something else last week | *"This section was rewritten"* · *"withdrawn because a later pass found it wrong"* · *"this used to read X"* | **Nowhere.** git holds it, and git holds it better |
+
+The second kind is what fills a corpus and buys nothing. It arrives as a correction block, a
+`## Provenance` note, a document's own change log, a note about a conflict that has already been
+**resolved**, or a *"considered and rejected"* aside about the method itself. All of it MUST NOT be
+written in the three layers above.
+
+**And no step demands the first kind either.** History is never a checklist item, never a gate condition,
+and never a blocking finding. It is written when someone judges it worth writing, and skipping it is
+**not** a gap — nothing in this method MAY report a missing history line as a defect. That is the whole
+difference between a record and a ritual.
+
+**A mid-flight change lands as if it had been there from the start.** An idea arriving during G5 is
+written in the present tense — not appended, not annotated, not marked as late. The commit is that
+record, and it is a better one than a paragraph.
+
+**What this rule does NOT cut:**
+
+- **The PRD's Revision History.** Its reader is outside the room, and `prd-guide.md` already demands the
+  business form of it: *state what the promise now is, not which section was edited.*
+- **`.control/questions/answered.md`.** This is the clearest case of history that pays: it is what stops
+  the same question being asked again in three months.
+- **`ratified_by:`** on a room guide — evidence the rule is real, not a record that it changed.
+- **`why/`** and `.control/decisions/`, whose job is exactly the first kind.
+- **`superseded`** pointing at its replacement. A reader following an old id needs the pointer.
+
+Real cost of getting this wrong, from one repo: a codebase conventions guide — the file a developer opens
+to learn how to write code here — spent a quarter of its length explaining when it had been filled, why it
+was not a `DEC-`, and which alternative had been rejected. Not one line of that would save the next reader
+from anything.
+
 ## Two axes inside `.what/`
 
 | | `_prd/<initiative>/` | `<pc>/` |
@@ -198,7 +333,7 @@ owner's decision.
 Both are living. What separates them is **promise versus behaviour**, not lifetime. One functional area MAY
 span several components, and one component MAY serve several PRDs, so neither can absorb the other.
 
-**Time is not a folder axis.** Release lives in `CAP.target_release` and in `waves.yaml`.
+**Time is not a folder axis.** Release lives in `CAP.target_release` and in `specs.yaml`.
 
 ## Slot numbering means two different things
 
@@ -225,11 +360,11 @@ cites them. `supplements/` beside either kernel is repealed with the `ANX-` conc
 
 | Code | Is |
 |---|---|
-| `BG-` `CAP-` `FR-` `NFR-` `UJ-` `UC-` | The traceability chain, allocated from `requirements.yaml` and `usecases.yaml` |
+| `BG-` `CAP-` `FR-` `NFR-` `UJ-` `UC-` | The traceability chain. `BG` from `goals.yaml`; `CAP`/`FR`/`NFR`/`UJ` from that initiative's `requirements-<slug>.yaml`; `UC` from `usecases.yaml` |
 | `AD-` | An invariant in the architecture spine — a living rule, edited in place |
 | `DEC-` | A decision — an event, frozen when `applied`, only superseded |
 | `LC-` | A Logical Component |
-| `OQ-` `RTR-` | An open question · an archived retrospective |
+| `OQ-` | An open question. `RTR-` was the archived retrospective and is **retired** — a frozen `RTR-` file stays where it is |
 | `BUG-` `HOT-` | A defect · a hotfix |
 | `NT-` | A non-technical fact |
 
@@ -278,7 +413,7 @@ it there, then `promote`. Using this room to bypass the package is how a method
 with nobody deciding it, and **an empty room is a valid state**: filling it so that it gets used is the
 very failure this rule prevents.
 
-Frontmatter is required and **V27** checks it: `scope: project` · a one-line `purpose:`. A file MAY
+Frontmatter is required and **`custom-room-declared`** checks it: `scope: project` · a one-line `purpose:`. A file MAY
 narrow or add with nothing further; to **contradict** a generic rule it MUST name that rule in
 `overrides:` and carry `decision:` naming the `DEC-` that decided it. A method that can be contradicted
 without a decision stops being trustworthy in the next repo.