wdi-method 0.5.13 → 0.6.0

package/bin/wdi-method.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -51,6 +52,7 @@ const WDI_SKILLS = [
   "wdi-review",
   "wdi-report",
   "wdi-systematic-debugging",
+  "wdi-upgrade",
 ];
 
 const PRD_SLUG_PLACEHOLDER = "FILL-initiative-slug";
@@ -62,6 +64,14 @@ const GENERIC_FOLDER_PATTERNS = new Set([
 ]);
 
 const BMAD_INSTALL = `npx bmad-method install`;
+// The ticket engines G5 runs. BMad writes the documents; these cut the work. They are a Claude Code
+// plugin installed per USER, not per repo, so the check reads the plugin registry — and the check
+// warns instead of blocking, because G1–G4 run without them and a first install has no G5 yet.
+const ENGINES_REPO = "https://github.com/mattpocock/skills";
+const ENGINES_PLUGIN = "mattpocock-skills";
+const ENGINES_INSTALL = `/plugin install ${ENGINES_PLUGIN}`;
+const ENGINES_INSTALL_ANY = "npx skills@latest add mattpocock/skills";
+const ENGINES_SETUP = "/setup-matt-pocock-skills";
 const REPO_URL = "https://github.com/wiradigitalid/wdi-method";
 const HELP_SKILL = "wdi-help";
 const INIT_SKILL = "wdi-init";
@@ -279,6 +289,22 @@ function requireTarget(dir) {
   return target;
 }
 
+/** `to-spec` · `to-tickets` · `implement` — present as a user-level plugin, or copied into the repo. */
+function enginesPresent(target) {
+  for (const dir of [".claude", ".agents", ".agent", ".cursor", ".codex"]) {
+    if (fs.existsSync(path.join(target, dir, "skills", "to-tickets", "SKILL.md"))) return true;
+  }
+  const cfg = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+  const registry = path.join(cfg, "plugins", "installed_plugins.json");
+  if (!fs.existsSync(registry)) return false;
+  try {
+    const plugins = JSON.parse(fs.readFileSync(registry, "utf8")).plugins || {};
+    return Object.keys(plugins).some((k) => k.startsWith("mattpocock-skills@"));
+  } catch {
+    return false;
+  }
+}
+
 function bmadMissingMessage() {
   return [
     "BMad Method is not installed in this repo. Install it first, then run this installer again.",
@@ -388,6 +414,60 @@ function splitProductConstitution(file) {
   return { cut, kept, relinked };
 }
 
+// `waves.yaml` holds the PRODUCT's plan, not the package's. When the method retired `wave` for
+// `spec` the registry had to follow, and a rename is the only part of that a tool can safely do:
+// the file MOVES, its content is left exactly as written. Rewriting the rows — `W1` to `SPEC-1`,
+// `epics`/`stories` to `tickets` — is the product's own migration, run by `wdi-build` where a human
+// can see it, because a guess there silently rewrites months of real work.
+//
+// Two refusals matter more than the move. It never writes over an existing `specs.yaml`, and it
+// never deletes a `waves.yaml` whose content has nowhere to go: a half-finished hand migration
+// leaves BOTH files present, and which one is real is not something an installer can know.
+function migrateRegistryNames(target) {
+  const reg = path.join(target, ".control", "registry");
+  const from = path.join(reg, "waves.yaml");
+  const to = path.join(reg, "specs.yaml");
+  if (!fs.existsSync(from)) return false;
+  if (fs.existsSync(to)) {
+    note("BOTH .control/registry/waves.yaml and specs.yaml exist — neither was touched");
+    note("  the plan is in one of them and I cannot tell which. Merge them yourself, then delete waves.yaml");
+    return false;
+  }
+  mv(from, to);
+  note("renamed .control/registry/waves.yaml → specs.yaml (content unchanged)");
+  note("  the rows still say `W<N>` and `epics`/`stories`. Re-cut them through the wdi-build skill");
+  return true;
+}
+
+// The requirement registry split into `goals.yaml` (the product's `BG`, written by `wdi-problem` at
+// G1) plus one `requirements-<slug>.yaml` per PRD (`CAP`, `FR`, `NFR`, `UJ`, written by
+// `wdi-product` at G2). One file, one writer, one gate. What a tool can do here is SEED `goals.yaml`;
+// what it MUST NOT do is move the rows.
+//
+// Splitting the rows needs one fact the registry has never recorded: which PRD an `FR` belongs to.
+// Before the split nothing wrote it down, and deriving it — FR → UC → ticket → spec → `prd:` — only
+// works for FRs that already have tickets. A guess would file a promise under the wrong initiative,
+// which is worse than leaving it where it is. So `requirements.yaml` is left ALONE and still read:
+// `validate.py` unions every requirement file it finds, so a half-split corpus stays green while its
+// owner cuts the rows through the skill that owns each one.
+function seedRequirementSplit(target) {
+  const reg = path.join(target, ".control", "registry");
+  if (!fs.existsSync(reg)) return false;
+  const product = path.join(reg, "goals.yaml");
+  if (fs.existsSync(product)) return false;
+  const seed = path.join(SCAFFOLD, "registry", "goals.yaml");
+  if (!fs.existsSync(seed)) return false;
+  copyFile(seed, product);
+  note("seeded .control/registry/goals.yaml");
+  if (fs.existsSync(path.join(reg, "requirements.yaml"))) {
+    note("  requirements.yaml was left exactly as it is, and is still read — nothing broke");
+    note("  the wdi-upgrade skill moves `goals:` into goals.yaml and cuts `capabilities:`,");
+    note("  `functional:`, `nonfunctional:`, and `journeys:` into requirements-<slug>.yaml per PRD.");
+    note("  <slug> is the PRD's folder name under .what/_prd/");
+  }
+  return true;
+}
+
 function migrateToTwoFolders(target) {
   const c = path.join(target, ".constitution");
   if (!fs.existsSync(c)) return false;          // a first install has nothing to migrate
@@ -601,6 +681,34 @@ function syncTomls(target) {
   return { files: n, slugsKept };
 }
 
+// The same argument pruneRetiredSkills makes, one folder over — with one difference that changes
+// the rule. `wdi-` is this method's namespace, so "a wdi-* folder not in WDI_SKILLS" is safely ours.
+// `_bmad/custom/` is NOT: a product may put its own override there, and `.user.toml` is the
+// product's half of every override by convention. So removal here is by an EXPLICIT list of files
+// this package once shipped and has now withdrawn — never by "absent from the kit".
+//
+// Why remove them at all: an override for a retired engine is worse than no override. It is still
+// installed and still read, and bmad-retrospective.toml instructs an agent to archive an `RTR-`
+// against a validator, V19, that no longer exists.
+const RETIRED_TOMLS = [
+  "bmad-spec.toml", "bmad-build.toml", "bmad-build-auto.toml",
+  "bmad-code-review.toml", "bmad-retrospective.toml",
+];
+
+function pruneRetiredTomls(target) {
+  const dir = path.join(target, "_bmad", "custom");
+  if (!fs.existsSync(dir)) return 0;
+  let removed = 0;
+  for (const name of RETIRED_TOMLS) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    fs.rmSync(file);
+    note(`removed retired override ${name}`);
+    removed += 1;
+  }
+  return removed;
+}
+
 function seedControlIfMissing(target) {
   const control = path.join(target, ".control");
   if (fs.existsSync(control)) {
@@ -688,6 +796,64 @@ function setLanguagePolicy(target, { docLanguage, docFilenameLanguage, chosen })
        `doc_filename_language = ${after.docFilenameLanguage}`);
 }
 
+// After `update`, some of the corpus can still be in the OLD shape — content the installer MUST NOT
+// 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.
+function pendingUpgrades(target) {
+  const has = (...p) => fs.existsSync(path.join(target, ...p));
+  const read = (...p) => (has(...p) ? fs.readFileSync(path.join(target, ...p), "utf8") : "");
+  const anyIn = (dir, glob, re) => {
+    const d = path.join(target, dir);
+    if (!fs.existsSync(d)) return false;
+    return fs.readdirSync(d).some((n) => {
+      const f = path.join(d, n, glob);
+      return fs.existsSync(f) && re.test(fs.readFileSync(f, "utf8"));
+    });
+  };
+  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)");
+  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");
+  const whatDir = path.join(target, ".what");
+  if (fs.existsSync(whatDir)) {
+    for (const pc of fs.readdirSync(whatDir)) {
+      if (pc.startsWith("_")) continue;
+      const srs = read(".what", pc, `SRS-${pc}.md`);
+      if (/^\|\s*UC-\d+\s*\|/m.test(srs)) { items.push("an SRS with a UC Catalogue table (now a pointer)"); break; }
+    }
+  }
+  const howDir = path.join(target, ".how");
+  if (fs.existsSync(howDir)) {
+    for (const pc of fs.readdirSync(howDir)) {
+      if (pc.startsWith("_")) continue;
+      if (/\|\s*Quoted rule\s*\||Quoted verbatim from/.test(read(".how", pc, `SDD-${pc}.md`))) { items.push("an SDD quoting AD-N text (now ids only)"); break; }
+    }
+  }
+  if (/\|\s*Container\s*\|\s*Product Components living in it\s*\|/.test(read(".how", "_platform", "c4-l2-containers.md"))) items.push("c4-l2 with a PC x container table (now a pointer)");
+  if (has(".control", "generated", "brief.md") || has(".control", "generated", "blueprint.md")) items.push("human pages still in .control/generated/ (render clears them)");
+  if (has(".what", "_product-brief", "brief.md") && !has(".what-rendered")) items.push("no .what-rendered/ yet (render creates it)");
+  // Skipped: what the validator never reads (kit copies, rendered output, dependencies) and what it
+  // treats as a record of the PAST — memlog, decisions, reports, _bmad-output. A stale path in a log
+  // is history, not a finding, and repointing it would falsify the record.
+  const SKIP = new Set([".git", "node_modules", "target", ".constitution", ".claude", ".agents", ".agent",
+    ".what-rendered", ".how-rendered", "dist", "build", "memlog", "decisions", "reports", "meetings", "_bmad-output", ".work"]);
+  const OLD_PAGE = /\.control\/generated\/(brief|blueprint|prd-[a-z0-9-]+)\.md/;
+  const citesOldPage = (dir, depth) => {
+    if (depth > 8) return false;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) { if (!SKIP.has(e.name) && citesOldPage(path.join(dir, e.name), depth + 1)) return true; continue; }
+      if (e.name === "answered.md") continue;
+      if (e.name.endsWith(".md") && OLD_PAGE.test(fs.readFileSync(path.join(dir, e.name), "utf8"))) return true;
+    }
+    return false;
+  };
+  if (citesOldPage(target, 0)) items.push("a document cites .control/generated/brief|blueprint|prd-*.md (pages moved to the rendered trees)");
+  return items;
+}
+
 // Read BEFORE writeStamp overwrites it. Without this there is no version transition to print, and
 // an "updated" with no from-to tells the reader nothing they can use.
 function readStampVersion(target) {
@@ -785,9 +951,10 @@ function printSummary(target, agents, { first, was, written, skipped, skills, to
   summaryLine("written", `${written} constitution · ${skills.files} skill files · ${tomls.files} bmad overrides`
     + (opencodeCmds?.written ? ` · ${opencodeCmds.written} opencode commands` : ""));
   if (kept.length) summaryLine("kept", kept.join(" · "));
-  if (skills.removed) {
-    summaryLine("removed", `${skills.removed} retired wrapper${skills.removed === 1 ? "" : "s"}`);
-  }
+  const gone = [];
+  if (skills.removed) gone.push(`${skills.removed} retired wrapper${skills.removed === 1 ? "" : "s"}`);
+  if (tomls.removed) gone.push(`${tomls.removed} retired override${tomls.removed === 1 ? "" : "s"}`);
+  if (gone.length) summaryLine("removed", gone.join(" · "));
   if (first && policy.docLanguage) {
     summaryLine("language", `${policy.docLanguage} · filenames ${policy.docFilenameLanguage}`);
   }
@@ -801,12 +968,27 @@ function printSummary(target, agents, { first, was, written, skipped, skills, to
                         `run the ${INIT_SKILL} skill, intent ${DIM}readers${RESET}, ` +
                         `to write it for this repo's stack`);
   }
-  summaryLine("next", `invoke the ${HELP_SKILL} skill and ask what to do`);
+  summaryLine("engines", enginesPresent(target)
+    ? `to-spec · to-tickets · implement — found (${ENGINES_PLUGIN})`
+    : `to-spec · to-tickets · implement — NOT found. G5 (wdi-build) and the Fast Path need them; G1–G4 run without them`);
+  if (!enginesPresent(target)) {
+    summaryLine("", `${DIM}·${RESET} Claude Code: ${DIM}${ENGINES_INSTALL}${RESET} — other agents: ${DIM}${ENGINES_INSTALL_ANY}${RESET}`);
+    summaryLine("", `${DIM}·${RESET} then ${DIM}${ENGINES_SETUP}${RESET} once, to name the tracker · ${ENGINES_REPO}`);
+  }
+  const pending = first ? [] : pendingUpgrades(target);
+  if (pending.length) {
+    summaryLine("upgrade", `${pending.length} item${pending.length === 1 ? "" : "s"} still in the OLD shape — ` +
+                           `run the ${DIM}wdi-upgrade${RESET} skill; it moves content, never invents it`);
+    for (const item of pending) summaryLine("", `${DIM}·${RESET} ${item}`);
+  }
+  summaryLine("next", pending.length
+    ? `run the ${DIM}wdi-upgrade${RESET} skill first, then ${HELP_SKILL}`
+    : `invoke the ${HELP_SKILL} skill and ask what to do`);
   summaryLine("", REPO_URL);
   console.log(`${DIM}${"─".repeat(62)}${RESET}`);
 }
 
-function printNextSteps({ first, productSet }) {
+function printNextSteps({ first, productSet, upgradePending }) {
   console.log("");
   console.log(first ? "After install:" : "After update:");
   if (first) {
@@ -828,6 +1010,10 @@ function printNextSteps({ first, productSet }) {
     console.log("  1. The <!-- BEGIN:wdi-method --> block in AGENTS.md was replaced. Read the diff.");
     console.log("  2. constitution.md Articles 1-2-5, ## Code, and *.user.toml were not overwritten.");
     console.log("  3. If BMad has new skills, install those first, then run this update again.");
+    if (upgradePending) {
+      console.log("  4. The summary listed an `upgrade` line: run the wdi-upgrade skill before any other skill.");
+      console.log("     It moves content into the new shape and never invents any; one commit.");
+    }
   }
 }
 
@@ -838,6 +1024,8 @@ function apply(target, agents,
   // MUST run before the kit is written: it moves the product's files out of the way of paths the kit
   // is about to occupy. Running it after would leave two copies of most guides.
   const migrated = migrateToTwoFolders(target);
+  migrateRegistryNames(target);
+  seedRequirementSplit(target);
   // The split MUST also be reachable without a migration. 0.5.2 only ran it from inside
   // migrateToTwoFolders, which returns early when the old layout is absent — so a repo that took
   // 0.5.0 or 0.5.1, whose project/constitution.md was moved WHOLE and never split, could never be
@@ -873,6 +1061,7 @@ function apply(target, agents,
     }
   }
   const tomls = syncTomls(target);
+  tomls.removed = pruneRetiredTomls(target);
   note(`bmad custom ${tomls.files} toml → _bmad/custom/`);
   if (first) seedControlIfMissing(target);
   seedEmptyLayers(target, { first });
@@ -884,6 +1073,7 @@ function apply(target, agents,
   printNextSteps({
     first,
     productSet: Boolean(product) && !identityIsPlaceholder(product),
+    upgradePending: !first && pendingUpgrades(target).length > 0,
   });
 }
 
@@ -1098,6 +1288,9 @@ async function runWizard(pre) {
       ? `BMad Method: installed${readBmadVersion(target) ? ` (${readBmadVersion(target)})` : ""}`
       : "BMad Method: not installed",
     hasWdi ? "WDI Method: already present — the installer will offer an update" : "WDI Method: not present",
+    enginesPresent(target)
+      ? "Ticket engines (mattpocock-skills): installed"
+      : `Ticket engines (mattpocock-skills): not found — needed at G5 only; ${ENGINES_INSTALL} (${ENGINES_REPO})`,
     nonempty ? "Folder is not empty (normal for a product repo already under way)" : "Folder is empty",
   ].join("\n");
   p.note(facts, "Detected");

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

@@ -1,75 +1,76 @@
----
-status: Reference
----
-
-# `.constitution/method/` — index
-
-`.constitution/` holds **exactly two folders**, and the folder is what says who owns a file:
-
-| Folder | Owner | `update` | `promote` |
-|---|---|---|---|
-| `method/` — you are in it | the method | **overwritten** in full | carries it into the package |
-| [`../project/`](../project/) | this product | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
-
-Load [`constitution.md`](constitution.md) and [`../project/constitution.md`](../project/constitution.md)
-before acting: Articles 3, 4, 6, 7 are here, Articles 1, 2, 5 are yours. Guides are loaded **lazily** —
-only when the task matches, and every guide states when on its own **Loaded when:** line.
-
-Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
-`Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
-own, because its frontmatter belongs to the artifact it produces.
-
-**A file this product adds MUST go in [`../project/`](../project/), not here** — anything in `method/`
-is replaced on the next update, without warning, because that is what `method/` means. This index is
-overwritten too.
-
-## `why/` — the explanation, `status: Reference`
-
-Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
-
-| File | Opened when |
-|---|---|
-| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
-| [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
-| [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |
-| [`why/portability.md`](why/portability.md) | Which files are the method and which are the product; how promote and install move them |
-
-## Cross-domain
-
-| File | Loaded when |
-|---|---|
-| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
-| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
-| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
-| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
-
-## `document/` — document rules
-
-| File | Governs |
-|---|---|
-| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
-| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
-| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
-| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
-| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
-| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
-| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
-| [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
-| [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
-
-## Code rules — in the room, not here
-
-All three are written by the **product**, so they live in [`../project/`](../project/) and no update
-touches them at any `status:`. While `Draft`, their contents MAY be read as guidance but MUST NOT be
-used to reject a change.
-
-[`stack-guide.md`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
-
-## `scripts/`
-
-`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
-dimension from git history. `inventory.py` — compares the three inventories against the code
-and reports the difference; it MUST NOT patch either side into agreement. It reads no code itself:
-the patterns live in `../project/inventory-readers.py`, because comparing is generic and reading a
-stack is not. That file ships as a skeleton and `wdi-init` intent `readers` writes it for the repo
-in front of it. All three run through `uv run`.
+---
+status: Reference
+---
+
+# `.constitution/method/` — index
+
+`.constitution/` holds **exactly two folders**, and the folder is what says who owns a file:
+
+| Folder | Owner | `update` | `promote` |
+|---|---|---|---|
+| `method/` — you are in it | the method | **overwritten** in full | carries it into the package |
+| [`../project/`](../project/) | this product | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
+
+Load [`constitution.md`](constitution.md) and [`../project/constitution.md`](../project/constitution.md)
+before acting: Articles 3, 4, 6, 7 are here, Articles 1, 2, 5 are yours. Guides are loaded **lazily** —
+only when the task matches, and every guide states when on its own **Loaded when:** line.
+
+Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
+`Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
+own, because its frontmatter belongs to the artifact it produces.
+
+**A file this product adds MUST go in [`../project/`](../project/), not here** — anything in `method/`
+is replaced on the next update, without warning, because that is what `method/` means. This index is
+overwritten too.
+
+## `why/` — the explanation, `status: Reference`
+
+Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
+
+| File | Opened when |
+|---|---|
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, sixteen skills, WDI ↔ BMad |
+| [`why/artifact-map.md`](why/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
+| [`why/mode-risk-map.md`](why/mode-risk-map.md) | A `mode` and a `risk_accepted` are set and you want the two side by side — all twelve cells |
+| [`why/rationale.md`](why/rationale.md) | Before changing a rule, to know what you would break |
+| [`why/portability.md`](why/portability.md) | Which files are the method and which are the product; how promote and install move them |
+
+## Cross-domain
+
+| File | Loaded when |
+|---|---|
+| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
+| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
+| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
+| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
+
+## `document/` — document rules
+
+| File | Governs |
+|---|---|
+| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
+| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
+| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
+| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
+| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
+| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
+| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
+| [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
+| [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
+
+## Code rules — in the room, not here
+
+All three are written by the **product**, so they live in [`../project/`](../project/) and no update
+touches them at any `status:`. While `Draft`, their contents MAY be read as guidance but MUST NOT be
+used to reject a change.
+
+[`stack-guide.md`](../project/codebase-stack-guide.md) · [`conventions-guide.md`](../project/codebase-conventions-guide.md) · [`brownfield-guide.md`](../project/codebase-brownfield-guide.md)
+
+## `scripts/`
+
+`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
+dimension from git history. `inventory.py` — compares the three inventories against the code
+and reports the difference; it MUST NOT patch either side into agreement. It reads no code itself:
+the patterns live in `../project/inventory-readers.py`, because comparing is generic and reading a
+stack is not. That file ships as a skeleton and `wdi-init` intent `readers` writes it for the repo
+in front of it. All three run through `uv run`.

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

@@ -23,6 +23,7 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 | `.control/` | Control — what currently holds and what has been decided |
 | `.what/` | What is promised |
 | `.how/` | How it is built |
+| `.what-rendered/` · `.how-rendered/` | The two above, assembled for a human to read — one page per gate, at the mirror path. Regenerated by `validate.py`, never edited, never read by a skill |
 | `_bmad-output/` | Run workspace; committed, not curated |
 | `.work/` | Scratch; committed, emptied when a task closes |
 | *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |
@@ -49,7 +50,7 @@ so a status there would land in the artifact and mean something else entirely.
 A missing header anywhere else is a **finding**, not an implicit anything.
 
 `Reference` exists so that the *explanation* of a rule can live beside the rule without competing with it —
-`method/why/` holds four such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
+`method/why/` holds five such files. Where a `Reference` file and an `Accepted` one disagree, the `Accepted`
 one wins, and the disagreement MUST be reported as a defect rather than resolved by preferring whichever was
 opened first. A rule MUST NOT be born in a `Reference` file; when one is noticed there, it is stated as a
 finding and written in the guide that owns it.

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

@@ -48,14 +48,14 @@ read in the places where it is right.
 An `AD-N` with no **Prevents** is a preference. Preferences belong in
 `.constitution/project/codebase-conventions-guide.md`, where nothing has to justify itself.
 
-## The spine stops being touched every story
+## The spine stops being touched every ticket
 
 This is the change that ends the tax that was being paid before the information existed.
 
 - **The spine holds invariants and nothing else.** It changes only when an `AD-N` is born or reversed, and
   both are decision events. For a mid-sized product: once at the start, around 6–10 `AD-N`, then almost
   never.
-- **A story MUST NOT touch the spine.** A story that contradicts an `AD-N` **stops** and opens a `DEC-` —
+- **A ticket MUST NOT touch the spine.** A ticket that contradicts an `AD-N` **stops** and opens a `DEC-` —
   the one case where recording a decision is still mandatory.
 - **Editing an `AD-N` MUST NOT quietly reverse it.** A reversal is a decision, and it goes through
   `wdi-decision` first.
@@ -90,7 +90,7 @@ the C4 set describes and the spine forbids. A C4 file MUST NOT be used to justif
 belongs in an `AD-N`.
 
 The C4 set is **living**. It is amended when a container is added or changed — it MUST NOT be regenerated from
-scratch, which would drop the annotations three waves of amendment put there.
+scratch, which would drop the annotations three specs of amendment put there.
 
 ## What counts as a container, and what does not
 
@@ -118,7 +118,7 @@ A container is inside the boundary whether or not we wrote it. `built:` records
 | A heading in `structure-codebase.md` | **Required** | **Never** — no code of ours lives there |
 | Listed in a PC's `containers:` | Yes | **Never** — see the matrix below |
 
-V25 checks all four. This is what makes the class settled rather than re-argued: a database and a web
+`container-built` checks all four. This is what makes the class settled rather than re-argued: a database and a web
 server are containers, they carry NFRs, and they still produce no design artifact of ours.
 
 **What IS ours about a `built: false` container MUST have a home outside the C4 set** — its configuration
@@ -139,7 +139,7 @@ depends on it for lives in `cross-cutting.md` or an integration contract.
 A PC and a container cross, so neither list implies the other — and the crossing is what a builder needs
 first: *which container does this promise live in, and is it more than one?*
 
-- The **SSOT is each PC's `containers:`** in `components.yaml`; C4 L2 renders it, and V25 fails when the
+- The **SSOT is each PC's `containers:`** in `components.yaml`; C4 L2 renders it, and `container-built` fails when the
   two disagree.
 - Complete at **G3** for every PC. It is blueprint content, so `mode` does not touch it.
 - A PC MUST list every `built: true` container it lives in. Listing only the main one is the error the
@@ -152,8 +152,8 @@ first: *which container does this promise live in, and is it more than one?*
 **L2 MUST be complete** — every container, plus the matrix. **L3 exists once per `built: true` container
 holding more than one PC**; a one-PC container needs none because the matrix already places it.
 
-**Not one of the three waits for a wave.** Which container a PC lives in cannot be discovered by a wave,
-because a wave picks its stories from that answer — a wave forced to invent it answers a G3 question with
+**Not one of the three waits for a spec.** Which container a PC lives in cannot be discovered by a spec,
+because a spec picks its tickets from that answer — a spec forced to invent it answers a G3 question with
 a fraction of G3's information.
 
 ## Cross-cutting
@@ -167,7 +167,7 @@ another. One fact, one home.
 **The platform MAY own things, and owning one costs a row here.** `_platform` is a legitimate owner in every
 position that asks which component owns something — a domain entity through `platform_owns`, an inventory row,
 an `LC`. Whatever it owns MUST be described under `## Platform-owned` in this file: what it is, its kind, why
-no component's promise explains it, who touches it, and the shape every toucher obeys. V21 checks that second
+no component's promise explains it, who touches it, and the shape every toucher obeys. `entity-one-writer` checks that second
 half, because a platform that owns something without documenting it has taken ownership without taking
 responsibility.
 
@@ -181,9 +181,9 @@ at every mode.
 
 ## Binding order
 
-Spine first, then the SDD, then `bmad-spec`. An `SDD-<pc>.md` written before the spine will be rewritten,
+Spine first, then the SDD, then the spec's contract. An `SDD-<pc>.md` written before the spine will be rewritten,
 because the constraints it was supposed to inherit did not exist yet. A `SPEC.md` written before the SDD has
-nothing to project. `bmad-spec` MUST keep `AD` ids stable so downstream artifacts can cite them.
+nothing to project. `AD` ids MUST stay stable so downstream artifacts can cite them.
 
 ## Inheritance downward