wdi-method 0.6.8 → 0.6.15

package/README.md

@@ -29,11 +29,10 @@ page it is on.
 
 ## Install
 
-Three steps, in this order. The first is required before step 3 will run; the second can wait until
-**Both are required, and the installer refuses without either.** BMad has always been checked; the ticket
-engines are checked too, because every repo that learned they were missing learned it inside `wdi-build`
-with a spec already open. `--skip-engines-check` is the escape for the two cases that earn it: CI, and a
-repo that will never reach G5.
+Three steps, in this order, and **step 3 refuses until steps 1 and 2 are done** — through the TUI and
+through `--yes` alike. BMad has always been checked; the engines are checked too, because every repo that
+learned they were missing learned it inside `wdi-build` with a spec already open. `--skip-engines-check`
+is the escape for the two cases that earn it: CI, and a repo that will never reach G5.
 
 **1. BMad Method** — in the product repo, picking the same agents you will give this installer:
 

package/bin/wdi-method.js

@@ -1234,6 +1234,78 @@ function setLanguagePolicy(target, { docLanguage, docFilenameLanguage, chosen })
 // move, because moving it takes a decision about meaning: which PRD an `FR` belongs to, whether a
 // sentence was an assumption or a constraint. The `wdi-upgrade` skill does that half. This only
 // DETECTS it, cheaply, so the summary can say how much is waiting and where.
+/** Specs whose folder is not where the convention puts it — and that are still WORK.
+ *
+ * A closed spec is exempt, and one measured repo is why: ten closed specs, none open. Reporting all
+ * ten would ask somebody to move ten folders of finished work and repoint every cite into them, for
+ * nothing — `spec_folder` still resolves, and a closed spec's ticket file is already allowed to be
+ * gone. The same exemption `ticket-status-one-home` grants, for the same reason: the convention binds
+ * work, not the record of work that is done.
+ *
+ * Scanned line by line rather than parsed: this installer has no YAML reader, and both the flat
+ * `specs:` shape and the pre-rename `waves:` one open a row the same way.
+ */
+function specsOutsideScratch(text) {
+  const out = [];
+  let id = "";
+  let status = "";
+  let folder = "";
+  const flush = () => {
+    if (id && folder && status !== "closed" && !folder.startsWith(".scratch/")) out.push(id);
+    id = "";
+    status = "";
+    folder = "";
+  };
+  for (const line of text.split(/\r?\n/)) {
+    const row = /^\s{2}-\s+id:\s*(\S+)/.exec(line);
+    if (row) {
+      flush();
+      id = row[1].replace(/['"]/g, "");
+      continue;
+    }
+    if (!id) continue;
+    const st = /^\s+status:\s*(\S+)/.exec(line);
+    if (st && !status) status = st[1].replace(/['"]/g, "");
+    const sf = /^\s+spec_folder:\s*(\S+)/.exec(line);
+    if (sf && !folder) folder = sf[1].replace(/['"]/g, "");
+  }
+  flush();
+  return out;
+}
+
+/** Specs still in the pre-rename plan shape that are NOT closed — the ones with work left in them.
+ *
+ * Same scanner shape as `specsOutsideScratch`, and the same exemption for the same reason: the
+ * convention binds work, not the record of work that is done.
+ */
+function specsInLegacyShape(text) {
+  const out = [];
+  let id = "";
+  let status = "";
+  let legacy = false;
+  const flush = () => {
+    if (id && legacy && status !== "closed") out.push(id);
+    id = "";
+    status = "";
+    legacy = false;
+  };
+  for (const line of text.split(/\r?\n/)) {
+    const row = /^\s{2}-\s+id:\s*(\S+)/.exec(line);
+    if (row) {
+      flush();
+      id = row[1].replace(/['"]/g, "");
+      if (/^W\d+$/.test(id)) legacy = true;
+      continue;
+    }
+    if (!id) continue;
+    const st = /^\s+status:\s*(\S+)/.exec(line);
+    if (st && !status) status = st[1].replace(/['"]/g, "");
+    if (/^\s+(epics|stories):/.test(line)) legacy = true;
+  }
+  flush();
+  return out;
+}
+
 function pendingUpgrades(target) {
   const has = (...p) => fs.existsSync(path.join(target, ...p));
   const read = (...p) => (has(...p) ? fs.readFileSync(path.join(target, ...p), "utf8") : "");
@@ -1247,7 +1319,32 @@ function pendingUpgrades(target) {
   };
   const items = [];
   if (has(".control", "registry", "requirements.yaml")) items.push("requirements.yaml → goals.yaml + requirements-<slug>.yaml");
-  if (/^\s*-\s*id:\s*W\d+|^\s*(epics|stories):/m.test(read(".control", "registry", "specs.yaml"))) items.push("specs.yaml rows still W<n>/epics/stories (wdi-build re-cuts)");
+  // The file the engines actually read. `/setup-matt-pocock-skills` writes its own answer here — no
+  // `specs.yaml`, no predefined path — and `seedAgentDocs` will not overwrite a file the product owns,
+  // so without this probe the repo never learns why its tickets scatter.
+  if (has("docs", "agents", "issue-tracker.md")
+      && !read("docs", "agents", "issue-tracker.md").includes("seeded by `wdi-method`")) {
+    items.push("docs/agents/issue-tracker.md is not the method's answer (npx wdi-method engines --fix)");
+  }
+  const strays = specsOutsideScratch(read(".control", "registry", "specs.yaml"));
+  if (strays.length) {
+    items.push(`spec_folder outside .scratch/<spec-id>-<slug>/ on ${strays.join(", ")} `
+               + `(the folder moves, then its cites)`);
+  }
+  // Reported only where it is still WORK. A closed pre-rename wave is read correctly (0.6.7 taught
+  // `Corpus.tickets()` to flatten `epics`/`stories` in memory), its `W<n>` id is a retired alias by
+  // design, and its ticket files are already allowed to be gone. Nothing there is waiting to move.
+  //
+  // Until 0.6.11 this fired on every legacy row and pointed at `wdi-build` to "re-cut" it. That
+  // instruction outlived the design it came from: `wdi-build` Phase 2 invokes `to-spec`/`to-tickets`
+  // to write a NEW contract and publish new tickets, and has no mode that converts an old wave.
+  // Three repos carrying twenty, forty-five and ten closed legacy rows were each told to run a skill
+  // that would answer "not mine" and stop.
+  const legacyOpen = specsInLegacyShape(read(".control", "registry", "specs.yaml"));
+  if (legacyOpen.length) {
+    items.push(`${legacyOpen.join(", ")} still in the W<n>/epics/stories shape and not closed `
+               + `(flattened into tickets, id kept as its retired alias)`);
+  }
   if (/^## (Executive Summary|Vision|Assumptions|Prerequisites)\s*$/m.test(read(".what", "_product-brief", "brief.md"))) items.push("brief.md in the 14-section shape");
   // Sections by NAME: the numbers moved between kits (Non-Goals was §7 in one, §5 in the next).
   if (anyIn(".what/_prd", "prd.md", /^## (\d+\.\s*)?(Document Purpose|Glossary|Non-Goals|Open Questions|Assumptions Index)\b|\*\*Proof of done:\*\*/m)) items.push("a prd.md in the 12-section shape, or with FR blocks");
@@ -1807,6 +1904,17 @@ async function runWizard(pre) {
     process.exit(1);
   }
 
+  // Step 2, refused in step 2's place. This used to be a line in the Detected note and nothing more,
+  // so an interactive install or update sailed past a repo with no engines in it — the same repo the
+  // `--yes` path refuses. The order matters as much as the stop: BMad is step 1, so a repo missing
+  // both is told about BMad first rather than sent to install the second thing.
+  const engineGate = enginesReport(target);
+  if (!engineGate.present && !pre.skipEngines) {
+    p.note(enginesMissingMessage(engineGate.missing), "Engines next");
+    p.outro("Install them into this repo, then run this again: npx wdi-method");
+    process.exit(1);
+  }
+
   let first = !hasWdi;
   if (hasWdi) {
     const update = cancelIf(

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

@@ -63,6 +63,41 @@ decision or a PRD MAY point into it. Research, brainstorming, forge, and PRFAQ r
 A run folder MUST NOT be deleted **while anything still needs it** — the `update` intents re-read the original
 inputs in place. "Never deleted" is not the rule; the rule is a **retirement condition**, and it is below.
 
+### A withdrawn promise STAYS in the registry
+
+A `BG` · `CAP` · `FR` · `NFR` · `UC` the product stops promising is marked, never deleted:
+
+```yaml
+  - id: CAP-8
+    title: "Publish an order as a public page"
+    status: withdrawn
+    withdrawn_by: DEC-026
+```
+
+**Why the row stays.** One repo deleted two withdrawn capabilities and paid for it in twelve
+`refs-resolve` findings: eight `DEC-` rows still named them in `serves:`, and six of those eight
+genuinely served them at the time. The other repair — editing those decisions — is refused by the
+section above: a `DEC-` is a record of what happened, and a retired name inside one is a fact about
+the past.
+
+**So a withdrawn row is read two ways, and both matter.** It is still **defined**: every old
+reference resolves, and `id-allocated-once` still refuses the number to anything else — an id is
+allocated once, withdrawal included. It is no longer **promised**: no `UC` is owed, no ticket, no RTM
+row, and `promise_progress` is not dragged down by something nobody promises any more.
+
+**Two rules keep it honest**, and `withdrawn-recorded` is what enforces both:
+
+- `withdrawn_by` MUST name a `DEC-` that exists. Retiring an id is decision-worthy on this method's
+  own terms — the **ID chain** row under § *Landing that MUST be confirmed first* says so outright —
+  and without the pointer `withdrawn` is only a word that quiets a validator.
+- A live row MUST NOT hang off a withdrawn one. An `FR` under a withdrawn `CAP` still promises
+  something whose capability nobody promises: withdraw it too, or move it under something live.
+  Withdrawal that takes half a chain with it silently is worse than the deletion it replaced, because
+  deletion at least went red.
+
+`wdi-product` owns the edit, because it owns the row. The withdrawal itself goes through
+`wdi-decision` first — the `DEC-` is what `withdrawn_by` points at.
+
 ## Who lands what
 
 There is no separate placement skill. A skill lands the output of the layer **it owns**, and the landing is

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

@@ -1,183 +1,184 @@
----
-status: Accepted
----
-
-# Method Glossary
-
-**Loaded when:** a method term is unclear, and before coining a new one.
-
-The words this method uses for **itself**. What the product is about belongs to
-`.control/product-glossary.md` instead. A term defined here MUST NOT be redefined there, and the
-reverse holds too. The test: would this term still apply on a different product? Yes → here.
-
-## Layers
-
-| Term | Means |
-|---|---|
-| **Corpus** | The four layers below. `_bmad-output/` is not part of it |
-| **`.constitution/`** | How we work. Rules. Rarely changes |
-| **`.control/`** | What currently holds and what has been decided. Facts. Changes often. Equals `{project_knowledge}` |
-| **`.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 spec has passed? Yes → corpus. No → workspace |
-
-## Units
-
-| Term | Means |
-|---|---|
-| **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 — `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 |
-| **Slot** | A numbered sub-folder of a PC. `.what/<pc>/` 02–05 is reading order; `.how/<pc>/` 01–06 is ABCE classification. The two numberings do **not** mean the same thing |
-| **Kernel** | The `SRS-<pc>.md` or `SDD-<pc>.md` file itself. Content SHOULD stay in it until it grows past roughly 400 lines — a suggestion, not a threshold |
-
-A PC is not a container: a container runs, a PC is a domain. One container holds several PCs, and
-one PC may appear in more than one container. Because they cross, neither list implies the other, and
-the crossing MUST be written down rather than inferred — that is the PC × container matrix at C4 L2,
-rendered from each PC's `containers:`.
-
-## Flow
-
-There is no "stage". The five gates are the only flow vocabulary, and the word **area** is not used at all —
-there is only Product Component.
-
-| Term | Means |
-|---|---|
-| **Gate** | One of five decision points: G1 Problem · G2 Product · G3 Blueprint · G4 Component · G5 Release. Named after what is decided there, not after the work before it |
-| **`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 |
-| **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
-
-| Term | Means |
-|---|---|
-| **Brief** | One problem, one user, one measure. Singleton, spans releases |
-| **PRD** | What is promised for **one initiative**, across every release it touches. FR and NFR numbered from the registry |
-| **SRS** | Per PC: what the system must do. `.what/` — slices space, while the PRD slices initiative. It **exists at every `mode`**, carrying the actor list and the use case catalogue |
-| **SDD** | Per PC: how it is built. `.how/`. At `mode: catalog` it is a skeleton, and that is a finished state |
-| **Inventory** | One of three living registers at product level — tables, endpoints, screens. Written as a plan when there is no code, **derived** from code once there is |
-| **Architecture spine** | `ARCHITECTURE-SPINE.md` — invariants as `AD-N`, each carrying Binds · Prevents · Rule. It constrains; it does not describe |
-| **C4** | L1 system context · L2 containers · L3 components, one file per container. L1+L2 together are what other methods call the HLD |
-| **`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 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 |
-| **Mandate** | A `DEC-` of `type: mandate`: the owner's one dated, expiring delegation that lets `wdi-autopilot` decide what the skills would otherwise have asked. Its parameters live on its registry row only; every decision taken under it is a row in the ledger, `.control/memlog/autopilot-<date>.md` |
-| **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 |
-
-## Identifiers
-
-| Code | For |
-|---|---|
-| `BG-` · `FR-` · `NFR-` · `UJ-` | Business goal · functional requirement · non-functional requirement · user journey |
-| `UC-` | Use case |
-| `AD-` | An invariant in the architecture spine |
-| `DEC-` | A decision |
-| `LC-` | A Logical Component |
-| `OQ-` | An open question |
-| `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 |
-| `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 → 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
-rewritten for the prefix.
-
-## Registry and generated
-
-| Term | Means |
-|---|---|
-| **Registry** | `.control/registry/` — the source of truth for IDs and plans. Written through `wdi-*` skills |
-| **Generated** | `.control/generated/` — derived from the registry. Written by the generator only, by hand **never** |
-| **RTM** | Requirements traceability matrix. Generated, never hand-maintained |
-| **Validator** | A script that answers what can be counted. It does not replace a gate checklist, which answers what must be judged |
-
-## BMad terms
-
-BMad terms live in a WDI glossary because WDI runs on BMad. Each is defined **as WDI uses it**;
-where BMad's own meaning is wider, the narrower one here wins.
-
-| Term | Means |
-|---|---|
-| **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 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/` |
-| **`_bmad/custom/`** | Where every BMad override lives. `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on update |
-
-## Retired — MUST NOT be used as current
-
-| Retired | Instead |
-|---|---|
-| `ADR-` | `DEC-` — same numbers, new prefix |
-| `ANX-`, and the annex concept | Nothing. Zero annexes were ever born |
-| `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` · `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 eighteen in `why/README.md`. `why/rationale.md` says which absorbed which, and why |
-| An Indonesian synonym for a `mode` value — *ringkas*, *terjaga*, *katalog* as prose | The English value, used as written: `catalog` · `outline` · `guarded` · `deep` |
-
-## Synonyms that MUST NOT be coined
-
-A synonym for a term that already has an entry is drift, and `wdi-reconcile` hunts for it.
-
-| Do not say | Say | Because |
-|---|---|---|
-| 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 `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
-  used. Adding one is a change to the **method itself** — `wdi-blueprint` MAY propose it and MUST NOT
-  write it, because a method term binds every project the method is installed in.
-- One term MUST NOT have two entries. Two meanings mean two terms.
-- A domain term MUST go to `.control/product-glossary.md` instead. If it is unclear which, ask whether the
-  term would survive being applied to a different product: yes → here, no → there.
-- Common technical terms stay in English when the industry name is the one that matches the code,
-  the error message, or the reader's expectation.
+---
+status: Accepted
+---
+
+# Method Glossary
+
+**Loaded when:** a method term is unclear, and before coining a new one.
+
+The words this method uses for **itself**. What the product is about belongs to
+`.control/product-glossary.md` instead. A term defined here MUST NOT be redefined there, and the
+reverse holds too. The test: would this term still apply on a different product? Yes → here.
+
+## Layers
+
+| Term | Means |
+|---|---|
+| **Corpus** | The four layers below. `_bmad-output/` is not part of it |
+| **`.constitution/`** | How we work. Rules. Rarely changes |
+| **`.control/`** | What currently holds and what has been decided. Facts. Changes often. Equals `{project_knowledge}` |
+| **`.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 spec has passed? Yes → corpus. No → workspace |
+
+## Units
+
+| Term | Means |
+|---|---|
+| **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 — `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 |
+| **Slot** | A numbered sub-folder of a PC. `.what/<pc>/` 02–05 is reading order; `.how/<pc>/` 01–06 is ABCE classification. The two numberings do **not** mean the same thing |
+| **Kernel** | The `SRS-<pc>.md` or `SDD-<pc>.md` file itself. Content SHOULD stay in it until it grows past roughly 400 lines — a suggestion, not a threshold |
+
+A PC is not a container: a container runs, a PC is a domain. One container holds several PCs, and
+one PC may appear in more than one container. Because they cross, neither list implies the other, and
+the crossing MUST be written down rather than inferred — that is the PC × container matrix at C4 L2,
+rendered from each PC's `containers:`.
+
+## Flow
+
+There is no "stage". The five gates are the only flow vocabulary, and the word **area** is not used at all —
+there is only Product Component.
+
+| Term | Means |
+|---|---|
+| **Gate** | One of five decision points: G1 Problem · G2 Product · G3 Blueprint · G4 Component · G5 Release. Named after what is decided there, not after the work before it |
+| **`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 |
+| **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
+
+| Term | Means |
+|---|---|
+| **Brief** | One problem, one user, one measure. Singleton, spans releases |
+| **PRD** | What is promised for **one initiative**, across every release it touches. FR and NFR numbered from the registry |
+| **SRS** | Per PC: what the system must do. `.what/` — slices space, while the PRD slices initiative. It **exists at every `mode`**, carrying the actor list and the use case catalogue |
+| **SDD** | Per PC: how it is built. `.how/`. At `mode: catalog` it is a skeleton, and that is a finished state |
+| **Inventory** | One of three living registers at product level — tables, endpoints, screens. Written as a plan when there is no code, **derived** from code once there is |
+| **Architecture spine** | `ARCHITECTURE-SPINE.md` — invariants as `AD-N`, each carrying Binds · Prevents · Rule. It constrains; it does not describe |
+| **C4** | L1 system context · L2 containers · L3 components, one file per container. L1+L2 together are what other methods call the HLD |
+| **`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 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 |
+| **Mandate** | A `DEC-` of `type: mandate`: the owner's one dated, expiring delegation that lets `wdi-autopilot` decide what the skills would otherwise have asked. Its parameters live on its registry row only; every decision taken under it is a row in the ledger, `.control/memlog/autopilot-<date>.md` |
+| **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 |
+
+## Identifiers
+
+| Code | For |
+|---|---|
+| `BG-` · `FR-` · `NFR-` · `UJ-` | Business goal · functional requirement · non-functional requirement · user journey |
+| `UC-` | Use case |
+| `AD-` | An invariant in the architecture spine |
+| `DEC-` | A decision |
+| `LC-` | A Logical Component |
+| `OQ-` | An open question |
+| `status: withdrawn` | On a `BG` · `CAP` · `FR` · `NFR` · `UC` row: the product stopped promising it, and the row stays so every old reference still resolves and its id is never reused. It names the `DEC-` that withdrew it in `withdrawn_by`. Still **defined**, no longer **promised** — `corpus-guide.md` owns the rule |
+| `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 |
+| `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 → 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
+rewritten for the prefix.
+
+## Registry and generated
+
+| Term | Means |
+|---|---|
+| **Registry** | `.control/registry/` — the source of truth for IDs and plans. Written through `wdi-*` skills |
+| **Generated** | `.control/generated/` — derived from the registry. Written by the generator only, by hand **never** |
+| **RTM** | Requirements traceability matrix. Generated, never hand-maintained |
+| **Validator** | A script that answers what can be counted. It does not replace a gate checklist, which answers what must be judged |
+
+## BMad terms
+
+BMad terms live in a WDI glossary because WDI runs on BMad. Each is defined **as WDI uses it**;
+where BMad's own meaning is wider, the narrower one here wins.
+
+| Term | Means |
+|---|---|
+| **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 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/` |
+| **`_bmad/custom/`** | Where every BMad override lives. `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on update |
+
+## Retired — MUST NOT be used as current
+
+| Retired | Instead |
+|---|---|
+| `ADR-` | `DEC-` — same numbers, new prefix |
+| `ANX-`, and the annex concept | Nothing. Zero annexes were ever born |
+| `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` · `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 eighteen in `why/README.md`. `why/rationale.md` says which absorbed which, and why |
+| An Indonesian synonym for a `mode` value — *ringkas*, *terjaga*, *katalog* as prose | The English value, used as written: `catalog` · `outline` · `guarded` · `deep` |
+
+## Synonyms that MUST NOT be coined
+
+A synonym for a term that already has an entry is drift, and `wdi-reconcile` hunts for it.
+
+| Do not say | Say | Because |
+|---|---|---|
+| 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 `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
+  used. Adding one is a change to the **method itself** — `wdi-blueprint` MAY propose it and MUST NOT
+  write it, because a method term binds every project the method is installed in.
+- One term MUST NOT have two entries. Two meanings mean two terms.
+- A domain term MUST go to `.control/product-glossary.md` instead. If it is unclear which, ask whether the
+  term would survive being applied to a different product: yes → here, no → there.
+- Common technical terms stay in English when the industry name is the one that matches the code,
+  the error message, or the reader's expectation.

package/kit/.constitution/method/scripts/validate.py

@@ -185,6 +185,27 @@ def git(root: Path, *args: str) -> str | None:
 REQUIREMENT_KEYS = ("goals", "capabilities", "functional", "nonfunctional", "journeys")
 
 
+def is_withdrawn(row: dict) -> bool:
+    """`status: withdrawn` — the product stopped promising this, and the row STAYED.
+
+    Deleting it is what a repo used to do, and the cost was measured: two capabilities withdrawn by
+    decision, their rows removed, and twelve `refs-resolve` findings — eight `DEC-` rows still named
+    them, six of which genuinely served them at the time. `corpus-guide.md` forbids the other repair:
+    a retired name in a record of what happened is a fact about the past, and a `DEC-` is exactly
+    that record.
+
+    So a withdrawn row is read TWO ways. It is still **defined** — every old reference resolves and
+    `id-allocated-once` still refuses the number to anyone else. It is no longer **promised** — no UC
+    is owed, no ticket, no RTM row, and `promise_progress` is not dragged down by something nobody
+    promises.
+    """
+    return str(row.get("status") or "").strip().lower() == "withdrawn"
+
+
+def promised(items: list[dict]) -> list[dict]:
+    return [row for row in items if not is_withdrawn(row)]
+
+
 @dataclass
 class Corpus:
     root: Path
@@ -253,23 +274,23 @@ class Corpus:
     # --- shortcuts used repeatedly
     @property
     def goals(self) -> list[dict]:
-        return rows(self.requirements, "goals")
+        return promised(rows(self.requirements, "goals"))
 
     @property
     def caps(self) -> list[dict]:
-        return rows(self.requirements, "capabilities")
+        return promised(rows(self.requirements, "capabilities"))
 
     @property
     def frs(self) -> list[dict]:
-        return rows(self.requirements, "functional")
+        return promised(rows(self.requirements, "functional"))
 
     @property
     def nfrs(self) -> list[dict]:
-        return rows(self.requirements, "nonfunctional")
+        return promised(rows(self.requirements, "nonfunctional"))
 
     @property
     def ucs(self) -> list[dict]:
-        return rows(self.usecases, "usecases")
+        return promised(rows(self.usecases, "usecases"))
 
     @property
     def decs(self) -> list[dict]:
@@ -282,6 +303,15 @@ class Corpus:
             return own
         return str(self.index.get("mode") or "").strip() or "catalog"
 
+    @property
+    def withdrawn_rows(self) -> list[dict]:
+        """Every withdrawn requirement row, with the key it came from — the id side of the split."""
+        out = []
+        for key in REQUIREMENT_KEYS:
+            out += [(key, row) for row in rows(self.requirements, key) if is_withdrawn(row)]
+        out += [("usecases", row) for row in rows(self.usecases, "usecases") if is_withdrawn(row)]
+        return [row for _, row in out]
+
     @property
     def lcs(self) -> list[dict]:
         return rows(self.components, "logical_components")
@@ -341,6 +371,18 @@ def _legacy_tickets(spec: dict) -> list[dict]:
     yet scheduled, and a closed wave has nothing left to schedule.
     """
     sid = str(spec.get("id") or "")
+
+    def scoped(raw: str) -> str:
+        """`W7-S2` under wave `W7` stays `W7-S2`, not `W7-W7-S2`.
+
+        The prefix exists so two waves both naming a story `"1"` cannot collide into one node. A
+        story already scoped to its wave has nothing to collide with, and prefixing it again produces
+        an id that matches no file, no memlog line, and nothing a person would search for. Measured on
+        a live repo whose RTM read `W7-W7-S2`.
+        """
+        sub = str(raw)
+        return sub if sid and sub.startswith(f"{sid}-") else f"{sid}-{sub}"
+
     out = []
     for epic in spec.get("epics") or []:
         if not isinstance(epic, dict):
@@ -349,8 +391,8 @@ def _legacy_tickets(spec: dict) -> list[dict]:
             if not isinstance(story, dict):
                 continue
             ticket = {k: v for k, v in story.items() if k not in ("id", "depends_on")}
-            ticket["id"] = f"{sid}-{story.get('id')}"
-            ticket["blocked_by"] = [f"{sid}-{d}" for d in (story.get("depends_on") or [])]
+            ticket["id"] = scoped(story.get("id"))
+            ticket["blocked_by"] = [scoped(d) for d in (story.get("depends_on") or [])]
             # The story's OWN id is kept because the file on disk is named after it, not after the
             # synthesized ticket id — see `_ticket_files`.
             ticket["_legacy_story_id"] = str(story.get("id") or "")
@@ -461,6 +503,8 @@ def refs_resolve(c: Corpus, r: Result) -> None:  # was V6
         defined.add(str(spec.get("id")))
     for _, ticket in c.tickets():
         defined.add(str(ticket.get("id")))
+    # Withdrawn, therefore still defined. This is the whole point of keeping the row.
+    defined |= {str(row.get("id")) for row in c.withdrawn_rows if row.get("id") is not None}
 
     refs: list[tuple[str, str]] = []
     for cap in c.caps:
@@ -482,9 +526,21 @@ def refs_resolve(c: Corpus, r: Result) -> None:  # was V6
         refs += [(str(ticket.get("id")), u) for u in listy(ticket, "satisfies")]
         refs += [(str(ticket.get("id")), b) for b in listy(ticket, "blocked_by")]
 
+    # A promise's id going missing has one likely cause and one wrong-looking-obvious repair. The
+    # cause: the row was DELETED when the product stopped promising it. The wrong repair: edit the
+    # reference — which `corpus-guide.md` refuses, because a `DEC-` records what happened and it did
+    # serve that promise at the time. One repo carried twelve of these before anyone worked out that
+    # the row was meant to stay, so the route travels with the finding.
+    promise_id = re.compile(r"^(BG|CAP|FR|NFR|UC)-\d+$")
     for owner, target in sorted(set(refs)):
         if target and target not in defined:
-            r.fail("refs-resolve", owner, f"points to `{target}` which does not exist in any registry")
+            hint = ""
+            if promise_id.match(target):
+                hint = (" — if it was withdrawn, the row STAYS with `status: withdrawn` and a "
+                        "`withdrawn_by`, and deleting it is what broke this reference (corpus-guide.md). "
+                        "Editing the reference instead rewrites a record of the past")
+            r.fail("refs-resolve", owner,
+                   f"points to `{target}` which does not exist in any registry{hint}")
 
 
 def _cycles(graph: dict[str, list[str]]) -> list[str]:
@@ -1619,6 +1675,47 @@ def engines_invocable(c: Corpus, r: Result) -> None:
                        f"update` restores it; `npx wdi-method engines --fix` strips it back out")
 
 
+def withdrawn_recorded(c: Corpus, r: Result) -> None:
+    """Two things, and without either one `withdrawn` is just a word that quiets a validator.
+
+    **It names the decision.** Withdrawing a promise is decision-worthy on the method's own terms —
+    `corpus-guide.md` lists "no `BG`/`CAP`/`FR`/`NFR`/`UC`/`LC` id is born, renamed, or retired" as a
+    test for whether something is a `DEC-`. So `withdrawn_by` MUST name one that exists.
+
+    **It does not orphan what is left.** A live `FR` whose capability is withdrawn still promises
+    something whose capability nobody promises any more. Withdrawal that takes half a chain with it
+    silently is worse than the deletion this replaced, because at least deletion went red.
+    """
+    dec_ids = {str(d.get("id")) for d in c.decs}
+    for row in c.withdrawn_rows:
+        rid = str(row.get("id") or "")
+        by = str(row.get("withdrawn_by") or "").strip()
+        if not by:
+            r.fail("withdrawn-recorded", rid, "is `status: withdrawn` and names no `withdrawn_by`. "
+                            "Withdrawing a promise is a decision — name the `DEC-` that took it, or the "
+                            "word is only silencing a validator")
+        elif by not in dec_ids:
+            r.fail("withdrawn-recorded", rid, f"names `withdrawn_by: {by}`, which is not a decision in "
+                            f"`decisions.yaml`")
+
+    withdrawn_ids = {str(row.get("id")) for row in c.withdrawn_rows}
+    if not withdrawn_ids:
+        return
+    for row, parent_key, what in ([(x, "goal", "goal") for x in c.caps]
+                                  + [(x, "capability", "capability") for x in c.frs]
+                                  + [(x, "capability", "capability") for x in c.nfrs]):
+        parent = str(row.get(parent_key) or "").strip()
+        if parent and parent in withdrawn_ids:
+            r.fail("withdrawn-recorded", str(row.get("id")),
+                   f"is live, and the {what} it hangs off (`{parent}`) is withdrawn. Withdraw this row "
+                   f"too, or move it under something still promised")
+    for uc in c.ucs:
+        for fr in listy(uc, "satisfies"):
+            if fr in withdrawn_ids:
+                r.fail("withdrawn-recorded", str(uc.get("id")),
+                       f"is live and satisfies `{fr}`, which is withdrawn")
+
+
 def id_allocated_once(c: Corpus, r: Result) -> None:  # was V28
     """One id, one row — across every file the requirement registry is split into.
 
@@ -1653,7 +1750,7 @@ def run_checks(c: Corpus, asof: dt.date) -> Result:
     # no two copies left to compare.
     # V19 is REPEALED. It checked one line item — an `RTR-` file in .control/reports/ — and the
     # retrospective it archived was the only thing spec size `L` ever decided. Both went together.
-    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, id_allocated_once):
+    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, withdrawn_recorded, id_allocated_once):
         fn(c, r)
     plan_dates(c, r, asof)
     return r
@@ -1856,7 +1953,7 @@ def gen_status(c: Corpus, rtm: dict, result: Result) -> dict:
         per_spec.append({"spec": wid, "status": spec.get("status"),
                          "tickets_done": done, "tickets_total": len(items),
                          "work_progress": _pct(done, len(items))})
-    applicable = 27  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
+    applicable = 28  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
     return {
         "promise_progress": _pct(green, len(counted)),
         "rtm_rows": {"green": green, "counted": len(counted),

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

@@ -119,6 +119,28 @@ A changed promise changes what other documents can still claim. Check, and **rep
 Then run the change-control matrix in `delivery-flow-guide.md` and **report** which gates reopen. You MUST
 NOT reopen one yourself.
 
+### Withdrawing a promise — the row stays
+
+A `BG` · `CAP` · `FR` · `NFR` the product stops promising is **marked, never deleted**. Deleting it is
+how a repo ended up with twelve `refs-resolve` findings: two capabilities were withdrawn by decision,
+their rows removed, and eight `DEC-` rows still named them — six of the eight having genuinely served
+them at the time, which `corpus-guide.md` forbids editing away.
+
+1. The withdrawal is a **decision first**. Route to `wdi-decision`; you MUST NOT withdraw a promise on
+   your own authority, and `withdrawn_by` needs that `DEC-` id to point at.
+2. Then mark the row, in place, in its own `requirements-<slug>.yaml`:
+   `status: withdrawn` and `withdrawn_by: DEC-NNN`. Everything else on the row is left as it was — it
+   is a record of what was promised, not a draft.
+3. Withdraw **down the chain in the same pass**: an `FR` under a withdrawn `CAP`, an `NFR` under it,
+   a `UC` satisfying a withdrawn `FR`. `withdrawn-recorded` reports a live row left hanging off a
+   withdrawn one, and that finding is the whole point — a half-withdrawn chain still promises half of
+   something.
+4. The id is **spent**. `id-allocated-once` counts a withdrawn row, so the number is never handed to
+   anything else.
+
+What you MUST NOT do: delete the row, renumber around the gap, or edit a `DEC-` that served it.
+`corpus-guide.md` § *A withdrawn promise STAYS in the registry* owns the rule.
+
 ## Rules
 
 - You MUST NOT write a second PRD for an area that already has one. The reader test decides, and its answer

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

@@ -43,7 +43,7 @@ before an earlier one lands content in a file that the earlier item is about to
 | # | 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 |
+| 2 | a spec with a `W<n>` id, or carrying `epics:` / `stories:`, that is **not `closed`** | pre-rename plan | flattened in place — **this skill's**, and § *The pre-rename plan* below is the mapping. A `closed` spec is left alone: `Corpus.tickets()` reads it correctly and its ticket files are already allowed to be gone |
 | 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` |
@@ -53,7 +53,8 @@ before an earlier one lands content in a file that the earlier item is about to
 | 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 |
 | 11 | `docs/agents/issue-tracker.md` does not contain the words `seeded by ``wdi-method``` | the engines' config as `/setup-matt-pocock-skills` wrote it: everything in `.scratch/` with no registry behind it, `specs.yaml` never mentioned | the method's own answer. **`npx wdi-method engines --fix`** rewrites it and keeps the old text as `issue-tracker.md.bak`. Two of four live repos still had upstream's, which is why their tickets landed wherever the engine guessed |
-| 12 | any `spec_folder` in `specs.yaml` is outside `.scratch/`, or its leaf does not begin with the spec's own id | spec folders under `_bmad-output/specs/`, leaf named freely — four repos wrote it four ways, one of them all four inside itself | `.scratch/<spec-id>-<slug>/`. Move the directory, rewrite the `spec_folder` row, then repoint every cite — `cites-resolve` is red until you do, and it is how you find them all |
+| 12 | a spec that is **not `closed`** has a `spec_folder` outside `.scratch/`, or a leaf that does not begin with its own id | spec folders under `_bmad-output/specs/`, leaf named freely — four repos wrote it four ways, one of them all four inside itself | `.scratch/<spec-id>-<slug>/`. Move the directory, rewrite the `spec_folder` row, then repoint every cite — `cites-resolve` is red until you do, and it is how you find them all. **A `closed` spec is left alone**: its folder is a record, moving it churns finished work, and its ticket files are already allowed to be gone |
+| 13 | `validate.py` reports `refs-resolve` on a `BG-` · `CAP-` · `FR-` · `NFR-` · `UC-` id — the finding itself is the probe | the row was **deleted** when the product stopped promising it, leaving every `DEC-` that served it pointing at nothing | the row comes BACK, marked `status: withdrawn` with `withdrawn_by` naming the decision that took it. Recover its text from git rather than retyping it — `git log -S"id: CAP-8" -- .control/registry/` finds the commit that held it. You MUST NOT edit the references instead: a `DEC-` records what happened, and it did serve that promise at the time. `corpus-guide.md` § *A withdrawn promise STAYS in the registry* owns the rule, `wdi-product` the procedure |
 
 Items 11 and 12 are the engines' half of a version jump, and they come FIRST when both are hit:
 item 11 writes where a spec's files belong, item 12 moves them there. Doing 12 first means moving
@@ -81,6 +82,25 @@ and its markup: when it holds `: ` or `#` or starts with a quote, wrap the value
 owner names it. When every row has moved, delete `requirements.yaml`; `id-allocated-once` fails if a
 row was copied instead of moved.
 
+**2 — the pre-rename plan.** A spec still shaped `epics: → stories:` is flattened into the one
+`tickets:` list the validator reads. Every part of this is a mapping; nothing here is a judgment, and
+nothing is invented:
+
+| Old | New |
+|---|---|
+| `waves:` as the file's top-level key | `specs:`. The rows below it do not otherwise change shape from this rename alone |
+| the spec's `W<n>` id | **unchanged.** It is a retired alias, and every memlog, `DEC-`, report and RTM row that names it MUST keep resolving. Renaming it to `SPEC-<n>` is the one thing this step MUST NOT do |
+| `epics:` → `stories:` nesting | one flat `tickets:` list, in the order the stories appear, epic by epic. The `epics` level is repealed: it grouped rows and bought nothing |
+| a story's own id (`"1"`, `"1-2"`) | `<spec-id>-<NN>`, renumbered from `01` in dependency order — `W3-01`, `W3-02`. A story id only ever promised uniqueness inside one epic, and this method keys tickets globally |
+| `depends_on: ["1-1"]` on a story | `blocked_by: [W3-01]` — the same edge, the new key, pointing at the new id |
+| `{spec_folder}/stories/1-2-<slug>.md` | `{spec_folder}/issues/<NN>-<slug>.md`, the `<NN>` matching the ticket's new id. `git mv`, so the file's history follows it |
+| a story's `touches:` | kept as `touches:`. A story never carried `component:`, and this step MUST NOT invent one — `wdi-init` owns that field |
+
+Two things stay untouched even here. The **status** of each ticket is read from its file and MUST NOT
+be copied into `specs.yaml` — `ticket-status-one-home` is what refuses that. And a `closed` spec is
+skipped whole: `validate.py` already flattens it in memory on every run, so rewriting the file changes
+no reading and only churns the record of finished work.
+
 Run `validate.py --check`. Green here means the registry is whole before any document starts pointing
 at it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdi-method",
-  "version": "0.6.8",
+  "version": "0.6.15",
   "description": "WDI Method — software delivery method that wraps BMad",
   "type": "module",
   "bin": {