wdi-method 0.6.6 → 0.6.8

package/README.md

@@ -42,16 +42,26 @@ cd /path/to/your/product-repo
 npx bmad-method install
 ```
 
-**2. mattpocock/skills** — one of the two paths, not both (both leaves every skill twice):
+**2. mattpocock/skills** — **into this repo**, on every agent:
 
 ```bash
-# Claude Code — a managed bundle that updates when its author ships
-claude plugins install mattpocock-skills      # or, inside a session:  /plugin install mattpocock-skills
-
-# Codex, Cursor, OpenCode, other agents — copies the skills into this repo; keep setup-matt-pocock-skills selected
 npx skills@latest add mattpocock/skills
 ```
 
+Take all six the method drives: `to-spec`, `to-tickets`, `implement`, `tdd`, `code-review`, and
+`domain-modeling`. Either install mode works — "copy" or "symlink".
+
+**The Claude Code plugin is not an alternative here, and the reason is mechanical.** `to-spec`,
+`to-tickets` and `implement` ship with `disable-model-invocation: true`, so no skill can invoke them;
+nothing outside the file lifts that flag, and a plugin's files are not this repo's to edit. WDI Method
+strips it from the copies the repo owns — which is what lets `wdi-build` invoke an engine and
+`wdi-autopilot` run an iteration with nobody watching — and re-applies that on every update, because
+`npx skills update` restores the author's file. The installer refuses without the six, and
+`--skip-engines-check` is the escape for CI and for a repo that will never reach G5.
+
+If you also have the plugin installed for your user, the repo's copies are what run; removing the
+plugin keeps `/to-spec` unambiguous.
+
 **You do not need to run `/setup-matt-pocock-skills` to get started.** Step 3 seeds `docs/agents/` with
 the two answers WDI Method actually has a requirement on, so the engines are aligned from the first
 install. Run the setup skill only to *change* something — to point at GitHub or Jira instead of local
@@ -450,6 +460,24 @@ English, whatever the settings say — it travels to every repo through this pac
 
 It prints the version it replaced, what it wrote, what it kept, and what to do next.
 
+### Moving a repo from 0.6.7 or earlier to 0.6.8
+
+Four things change for a repo already running the method. The first is the only one that can stop an
+update, and all four are mechanical.
+
+| What changed | What it means for your repo |
+|---|---|
+| **The engines must be in the repo** | `install` and `update` refuse until `to-spec`, `to-tickets`, `implement`, `tdd`, `code-review` and `domain-modeling` are here — `npx skills@latest add mattpocock/skills`. The Claude Code plugin no longer counts: three of the six ship locked against skill invocation, nothing outside the file unlocks them, and a plugin's files are not yours to edit. `--skip-engines-check` still installs without them |
+| **The engines are invoked, not handed to you** | `wdi-build` calls `to-spec`, `to-tickets`, `implement`, `tdd` and `code-review` itself, so `wdi-autopilot` can finish a spec with nobody watching. Every `update` re-unlocks the repo's copies, because `npx skills update` puts the author's lock back — and `engines-invocable` in `validate.py` goes red when it has |
+| **Thirteen BMad skills are retired at G5, and now enforced** | `bmad-spec`, `bmad-build`, `bmad-build-auto`, `bmad-code-review`, `bmad-retrospective`, `bmad-agent-dev`, `bmad-create-epics-and-stories`, `bmad-create-story`, `bmad-dev-story`, `bmad-dev-auto`, `bmad-quick-dev`, `bmad-sprint-planning`, `bmad-sprint-status`. Each is locked out of model invocation and denied in `.claude/settings.json`; typing the slash command yourself still works. `bmad-skill-register.md` carries the list and the criterion — retired only where this method has a named replacement, which is why `bmad-qa-generate-e2e-tests` and `bmad-checkpoint-preview` are not on it |
+| **A spec has one predefined home** | `.scratch/<spec-id>-<slug>/`, with `SPEC.md` and `issues/<NN>-<slug>.md` inside it. Left free, that folder name gets written a different way in every repo and traces back to nothing. A row in `specs.yaml` is now what makes an effort a spec rather than ad hoc work — the path no longer says |
+
+Run the `wdi-upgrade` skill after updating: it names what is still in the old shape, including a
+`docs/agents/issue-tracker.md` that still carries `/setup-matt-pocock-skills`' own answer, and the spec
+folders that need moving. `npx wdi-method engines` reports the engine state on its own, and
+`npx wdi-method engines --fix` repairs what can be repaired without touching anything you wrote — the
+previous config is kept as `.bak`.
+
 ---
 
 ## Changing the method

package/bin/wdi-method.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import * as p from "@clack/prompts";
 import {
@@ -66,14 +67,65 @@ 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.
+// The engines G5 runs. BMad writes the documents; these cut the work.
+//
+// They are installed IN THE REPO, and a user-level plugin no longer counts. Three reasons, and the
+// third is what forced it: a method whose G5 depends on what the operator happened to install on
+// their laptop behaves differently per machine; `.control/wdi-method.yaml` cannot record a version
+// it does not own; and `to-spec`, `to-tickets` and `implement` ship with
+// `disable-model-invocation: true`, which nothing outside the file can lift — the gate reads the
+// frontmatter and consults no setting, and `skillOverrides` only ever tightens. Owning the file is
+// the only route to an engine a skill can invoke, so owning the file is now the requirement.
+// Upstream ships that route deliberately: the plugin is "subscribe rather than fork", `skills.sh`
+// "copies editable skill files into your project, so you can hack on them and make them your own".
 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";
+// Six, not five. `domain-modeling` is G3's — `wdi-blueprint` invokes it — and it used to be reached
+// by its plugin-namespaced name. With the plugin no longer required that name resolves to nothing,
+// so the skill joins the local install and every reference to it dropped the prefix.
+const ENGINE_SKILLS = ["to-spec", "to-tickets", "implement", "tdd", "code-review", "domain-modeling"];
+// The three that arrive flagged. `tdd`, `code-review` and `domain-modeling` never carried the flag
+// and MUST NOT gain one.
+const ENGINE_FLAGGED = ["to-spec", "to-tickets", "implement"];
+const ENGINE_LOCK = "skills-lock.json";
+const GUARD_MARK = "Driven by `wdi-build` and `wdi-autopilot`";
+const GUARD_LINE = `> **${GUARD_MARK}.** \`wdi-method\` unlocked model invocation for this `
+  + "engine in this repo so those two can drive it unattended. Invoked from anywhere else — a stray "
+  + "session, a subagent that thought this looked relevant — stop and say so: this engine publishes "
+  + "to the tracker and writes code.";
+
+// Every folder a platform reads skills from. One list, because a repo installs the engines wherever
+// `npx skills add` was pointed, and that installer offers symlinks across several of them.
+const SKILL_HOMES = [".claude", ".agents", ".agent", ".cursor", ".codex"];
+
+// BMad skills RETIRED at G5. This array is the single home of that list: `bmad-skill-register.md`
+// carries the same names for a reader, and a test fails when the two disagree.
+//
+// The criterion, and it is why the list is this long and not longer: a BMad skill is retired only
+// where this method has a NAMED replacement for what it produces. `bmad-build` and `bmad-agent-dev`
+// produce code that `implement` produces; `bmad-spec` a contract that `to-spec` produces;
+// `bmad-create-epics-and-stories` an `epics` level this method REPEALED in code, not merely in
+// prose. `bmad-qa-generate-e2e-tests` and `bmad-checkpoint-preview` have no replacement here, so
+// they are NOT retired — banning a capability with nothing in its place is how a method gets
+// worked around instead of followed.
+const BMAD_RETIRED_G5 = [
+  "bmad-spec",
+  "bmad-build",
+  "bmad-build-auto",
+  "bmad-code-review",
+  "bmad-retrospective",
+  "bmad-agent-dev",
+  "bmad-create-epics-and-stories",
+  "bmad-create-story",
+  "bmad-dev-story",
+  "bmad-dev-auto",
+  "bmad-quick-dev",
+  "bmad-sprint-planning",
+  "bmad-sprint-status",
+];
 const REPO_URL = "https://github.com/wiradigitalid/wdi-method";
 const HELP_SKILL = "wdi-help";
 const INIT_SKILL = "wdi-init";
@@ -113,6 +165,7 @@ function usage() {
   install [dir]             first install (TUI unless --yes)
   update  [dir]             update      (TUI unless --yes)
   verify  [dir]
+  engines [dir] [--fix]     report the six engines, their invocation state, and the BMad G5 ban
   promote <live-dir> --rescue   pull a method change back out of a consumer (not the normal flow)
 
   --yes                     non-interactive
@@ -136,6 +189,7 @@ function parseArgs(argv) {
     agents: null,
     skipBmad: false,
     rescue: false,
+    fix: false,
     yes: false,
     product: null,
     client: null,
@@ -156,7 +210,7 @@ function parseArgs(argv) {
     return args;
   }
   const first = rest[0];
-  if (["install", "update", "verify", "promote"].includes(first)) {
+  if (["install", "update", "verify", "promote", "engines"].includes(first)) {
     args.cmd = rest.shift();
   } else if (first.startsWith("-")) {
     args.cmd = "wizard";
@@ -167,6 +221,7 @@ function parseArgs(argv) {
   while (rest.length) {
     const t = rest.shift();
     if (t === "--skip-bmad-check") args.skipBmad = true;
+    else if (t === "--fix") args.fix = true;
     else if (t === "--skip-engines-check") args.skipEngines = true;
     else if (t === "--rescue") args.rescue = true;
     else if (t === "--yes" || t === "-y") args.yes = true;
@@ -293,11 +348,45 @@ 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;
+/** Skill files in the repo, keyed by name, de-duplicated by the file each one REALLY is.
+ *
+ * The de-duplication is the point. `npx skills add` offers "symlink — single source of truth" when
+ * more than one agent is selected, so one SKILL.md is reachable through `.claude/skills/` and
+ * `.agents/skills/` at once. Walking directories would patch it twice — and where the link points
+ * into `node_modules`, patching it at all would edit a dependency.
+ */
+function repoSkillFiles(target, names) {
+  const out = new Map();
+  for (const home of SKILL_HOMES) {
+    for (const name of names) {
+      const file = path.join(target, home, "skills", name, "SKILL.md");
+      if (!fs.existsSync(file)) continue;
+      let real = file;
+      try {
+        real = fs.realpathSync(file);
+      } catch {}
+      if (!out.has(name)) out.set(name, new Map());
+      out.get(name).set(real, file);
+    }
   }
+  return out;
+}
+
+/** The six engines, in the REPO. A user-level plugin is not an answer here — see ENGINE_SKILLS. */
+function enginesReport(target) {
+  const files = repoSkillFiles(target, ENGINE_SKILLS);
+  const missing = ENGINE_SKILLS.filter((n) => !files.has(n));
+  return { files, missing, present: missing.length === 0 };
+}
+
+function enginesPresent(target) {
+  return enginesReport(target).present;
+}
+
+/** Only ever a WARNING. The plugin's copies are namespaced and still flagged, so they can neither be
+ * invoked nor shadow the repo's — but `/to-spec` in the UI becomes ambiguous, and `npx skills
+ * update` run against a plugin-shaped install is one way the flag comes back. */
+function pluginEnginesRegistered() {
   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;
@@ -309,6 +398,149 @@ function enginesPresent(target) {
   }
 }
 
+/** Strip the author's flag, and write one guard line where it stood.
+ *
+ * The flag was the only thing stopping a stray session from publishing tickets. Removing it without
+ * naming who may drive the engine trades a hard gate for nothing, so the two arrive together.
+ * Idempotent by construction: no flag and a guard already present means the file is returned as-is,
+ * which is what keeps a second `update` from stacking a second line.
+ */
+function withInvocationEnabled(text) {
+  let out = text;
+  if (/^disable-model-invocation\s*:.*$/m.test(out)) {
+    out = out.replace(/^disable-model-invocation\s*:.*\r?\n/m, "");
+  }
+  if (!out.includes(GUARD_MARK)) {
+    out = out.replace(/^(---\r?\n[\s\S]*?\r?\n---\r?\n)/, `$1\n${GUARD_LINE}\n`);
+  }
+  return out;
+}
+
+function enableEngineInvocation(target) {
+  const { files } = enginesReport(target);
+  const patched = new Set();
+  for (const name of ENGINE_FLAGGED) {
+    const copies = files.get(name);
+    if (!copies) continue;
+    for (const real of copies.keys()) {
+      const before = fs.readFileSync(real, "utf8");
+      const after = withInvocationEnabled(before);
+      if (after === before) continue;
+      fs.writeFileSync(real, after, "utf8");
+      patched.add(name);
+    }
+  }
+  if (patched.size) {
+    note(`engines invocable: ${[...patched].join(" · ")} — author's flag removed, guard line written`);
+  }
+  return [...patched];
+}
+
+/** The mirror image, pointed at BMad's G5 wrappers: the flag ADDED rather than removed.
+ *
+ * A rule in a document lost this argument for three releases. `bmad-build` sits in the repo's own
+ * skill folder claiming it "implements any user intent, requirement, story, bug fix or change
+ * request", model-invocable, while the sanctioned engines sat in a plugin the model could not call.
+ * The harness rewarded the forbidden path. This is what stops rewarding it — and it leaves the
+ * human route open, because the gate only refuses the Skill tool: `/bmad-build` typed by a person
+ * still runs.
+ */
+function withModelInvocationDisabled(text) {
+  if (/^disable-model-invocation\s*:\s*true/m.test(text)) return text;
+  if (!/^---\r?\n/.test(text)) return text; // no frontmatter of its own: not ours to invent one
+  if (/^disable-model-invocation\s*:/m.test(text)) {
+    return text.replace(/^disable-model-invocation\s*:.*$/m, "disable-model-invocation: true");
+  }
+  return text.replace(/^---\r?\n/, "---\ndisable-model-invocation: true\n");
+}
+
+function retireBmadG5(target) {
+  const files = repoSkillFiles(target, BMAD_RETIRED_G5);
+  const patched = new Set();
+  for (const [name, copies] of files) {
+    for (const real of copies.keys()) {
+      const before = fs.readFileSync(real, "utf8");
+      const after = withModelInvocationDisabled(before);
+      if (after === before) continue;
+      fs.writeFileSync(real, after, "utf8");
+      patched.add(name);
+    }
+  }
+  if (patched.size) {
+    note(`retired at G5: ${patched.size} BMad skill${patched.size === 1 ? "" : "s"} can no longer be `
+         + `model-invoked (a person typing the slash command still can)`);
+  }
+  return [...patched];
+}
+
+/** Second layer, and the only one that survives BMad reinstalling its own wrappers mid-week.
+ *
+ * Merged, never replaced: a product's own permissions are its own. Invalid JSON is reported rather
+ * than repaired — rewriting a settings file nobody can parse is how a repo loses its allowlist.
+ */
+function writeDenyRules(target) {
+  const file = path.join(target, ".claude", "settings.json");
+  let settings = {};
+  if (fs.existsSync(file)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      note(".claude/settings.json is not valid JSON — deny rules NOT written; fix it and re-run");
+      return 0;
+    }
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) return 0;
+  }
+  const perms = settings.permissions && typeof settings.permissions === "object"
+    && !Array.isArray(settings.permissions) ? settings.permissions : {};
+  const deny = Array.isArray(perms.deny) ? perms.deny : [];
+  const want = BMAD_RETIRED_G5.map((n) => `Skill(${n})`);
+  const added = want.filter((rule) => !deny.includes(rule));
+  if (!added.length) return 0;
+  perms.deny = [...deny, ...added];
+  settings.permissions = perms;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  note(`deny rules for ${added.length} retired BMad skill${added.length === 1 ? "" : "s"} `
+       + `→ .claude/settings.json`);
+  return added.length;
+}
+
+/** A trace of what the engines were when the method last looked — not a lockfile.
+ *
+ * `npx skills add` writes its own `skills-lock.json` with a folder hash per skill, and that hash
+ * stops matching the moment the flag is stripped. So the register records the hash of the file the
+ * method actually reads, AFTER the patch. It is informational: `engines-invocable` decides by
+ * looking for the flag, not by comparing hashes, because a legitimate content change MUST NOT read
+ * as a defect.
+ */
+function engineFingerprints(target) {
+  const { files } = enginesReport(target);
+  const out = {};
+  for (const name of ENGINE_SKILLS) {
+    const copies = files.get(name);
+    if (!copies) continue;
+    const [real] = [...copies.keys()].sort();
+    out[name] = createHash("sha256").update(fs.readFileSync(real)).digest("hex").slice(0, 12);
+  }
+  return out;
+}
+
+function engineInvocationState(target) {
+  const { files } = enginesReport(target);
+  const blocked = [];
+  for (const name of ENGINE_FLAGGED) {
+    const copies = files.get(name);
+    if (!copies) continue;
+    for (const real of copies.keys()) {
+      if (/^disable-model-invocation\s*:\s*true/m.test(fs.readFileSync(real, "utf8"))) {
+        blocked.push(name);
+        break;
+      }
+    }
+  }
+  return { blocked };
+}
+
 function bmadMissingMessage() {
   return [
     "BMad Method is not installed in this repo. Install it first, then run this installer again.",
@@ -328,12 +560,18 @@ function bmadMissingMessage() {
 //
 // So it blocks, and `--skip-engines-check` is the escape, exactly as `--skip-bmad-check` is for BMad. The
 // escape matters: CI installs into a bare checkout, and a repo that will never reach G5 is a real case.
-function enginesMissingMessage() {
+function enginesMissingMessage(missing) {
+  const names = (missing && missing.length ? missing : ENGINE_SKILLS).join(" · ");
   return [
-    "The ticket engines are not installed. G5 (wdi-build) and wdi-autopilot need all three.",
+    `The engines are not in this repo. Missing: ${names}`,
+    "",
+    "They MUST be installed INTO the repo, not as a user-level plugin — the method strips",
+    "`disable-model-invocation` from its own copies so `wdi-build` and `wdi-autopilot` can drive",
+    "them, and a plugin's files are not the repo's to edit.",
+    "",
+    `  ${ENGINES_INSTALL_ANY}`,
     "",
-    `  Claude Code:  ${ENGINES_INSTALL}`,
-    `  Other agents: ${ENGINES_INSTALL_ANY}`,
+    `Take all six: ${ENGINE_SKILLS.join(" · ")}. Choose "copy" or "symlink" — either is read.`,
     "",
     "You do NOT need to run the setup skill after this — the installer seeds docs/agents/ already",
     `answered for this method. Run ${ENGINES_SETUP} only to change tracker.`,
@@ -343,6 +581,39 @@ function enginesMissingMessage() {
   ].join("\n");
 }
 
+/** `docs/agents/` is the engines' config, and its PATH is the author's: `to-spec`, `to-tickets`,
+ * `implement` and `triage` read `docs/agents/issue-tracker.md` and `docs/agents/domain.md` and
+ * nowhere else. What the files SAY is this method's, and that is the half that kept going wrong:
+ * a repo that ran `/setup-matt-pocock-skills` carries upstream's answer, which sends every engine to
+ * `.scratch/` with no registry behind it and never mentions `specs.yaml`. Two of four live repos
+ * still had it.
+ *
+ * The installer does not touch a product-owned file, and that rule stays. This is the repair, run
+ * from `wdi-method engines --fix` — by `wdi-init` or `wdi-upgrade`, knowingly — and it keeps the
+ * previous text beside it as `.bak` rather than deleting an answer somebody may have meant.
+ */
+function repairAgentDocs(target) {
+  const dir = path.join(target, "docs", "agents");
+  const fixed = [];
+  for (const name of ["issue-tracker.md", "domain.md"]) {
+    const seed = path.join(ROOT, "scaffold", "docs", "agents", name);
+    if (!fs.existsSync(seed)) continue;
+    const to = path.join(dir, name);
+    if (!fs.existsSync(to)) {
+      copyFile(seed, to);
+      fixed.push(`${name} (seeded)`);
+      continue;
+    }
+    const text = fs.readFileSync(to, "utf8");
+    if (text.includes("seeded by `wdi-method`")) continue;
+    fs.writeFileSync(`${to}.bak`, text, "utf8");
+    copyFile(seed, to);
+    fixed.push(`${name} (was upstream's — previous text kept as ${name}.bak)`);
+  }
+  for (const line of fixed) note(`repaired docs/agents/${line}`);
+  return fixed;
+}
+
 // The product's custom room. Three properties, and all three MUST hold together:
 //   install/update  seeds its content ONLY when absent — never written again after that
 //   promote         SKIPS it entirely, so a product's own rules can never reach the public repo
@@ -889,13 +1160,33 @@ function seedEmptyLayers(target, { first }) {
 function writeStamp(target) {
   const control = path.join(target, ".control");
   if (!fs.existsSync(control)) return;
-  const stamp = [
+  const eng = enginesReport(target);
+  const fp = engineFingerprints(target);
+  const names = Object.keys(fp);
+  const lines = [
     "# Written by wdi-method install/update. A trace, not a lockfile.",
     `wdi_method: ${PKG.version}`,
     `bmad_method: ${readBmadVersion(target) || '""'}`,
-    `installed_at: ${today()}`,
-    "",
-  ].join("\n");
+  ];
+  if (names.length) {
+    const blocked = engineInvocationState(target).blocked;
+    lines.push("engines:");
+    lines.push("  source: local");
+    lines.push("  package: mattpocock/skills");
+    lines.push(`  lock: ${fs.existsSync(path.join(target, ENGINE_LOCK)) ? ENGINE_LOCK : '""'}`);
+    lines.push(`  model_invocation: ${blocked.length ? "blocked" : "enabled"}`);
+    if (eng.missing.length) lines.push(`  missing: [${eng.missing.join(", ")}]`);
+    lines.push("  # sha256 of each SKILL.md AFTER the flag was stripped, first 12. Informational:");
+    lines.push("  # engines-invocable decides by looking for the flag, not by comparing these.");
+    lines.push("  skills:");
+    for (const name of names) lines.push(`    ${name}: ${fp[name]}`);
+  } else {
+    lines.push("engines:");
+    lines.push("  source: none   # none in this repo — G5 cannot run until they are installed");
+  }
+  lines.push(`installed_at: ${today()}`);
+  lines.push("");
+  const stamp = lines.join("\n");
   fs.writeFileSync(path.join(control, "wdi-method.yaml"), stamp, "utf8");
   note("stamped .control/wdi-method.yaml");
 }
@@ -1111,12 +1402,25 @@ 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("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 engReport = enginesReport(target);
+  summaryLine("engines", engReport.present
+    ? `${ENGINE_SKILLS.join(" · ")} — found (in this repo)`
+    : `NOT found: ${engReport.missing.join(" · ")}. G5 (wdi-build) and the Fast Path need them; G1–G4 run without them`);
+  if (!engReport.present) {
+    summaryLine("", `${DIM}·${RESET} into THIS repo: ${DIM}${ENGINES_INSTALL_ANY}${RESET} — a user-level plugin does not count`);
+    summaryLine("", `${DIM}·${RESET} docs/agents/ is already seeded, so ${DIM}${ENGINES_SETUP}${RESET} is not needed · ${ENGINES_REPO}`);
+  } else {
+    const blocked = engineInvocationState(target).blocked;
+    if (blocked.length) {
+      summaryLine("", `${DIM}·${RESET} still flagged, so no skill can invoke ${blocked.join(" · ")} — run ${DIM}npx wdi-method engines --fix${RESET}`);
+    }
+  }
+  // Upstream's own warning: "installing both leaves you with every skill twice." It is survivable —
+  // the plugin's copies are namespaced and still flagged, so they can neither be invoked nor shadow
+  // the repo's — but `/to-spec` in the UI stops being one thing, so it is said out loud.
+  if (pluginEnginesRegistered()) {
+    summaryLine("", `${DIM}·${RESET} the ${ENGINES_PLUGIN} plugin is ALSO installed for this user — the repo's copies are what run;`);
+    summaryLine("", `${DIM}·${RESET} remove the plugin to keep ${DIM}/to-spec${RESET} unambiguous`);
   }
   const pending = first ? [] : pendingUpgrades(target);
   if (pending.length) {
@@ -1215,6 +1519,12 @@ function apply(target, agents,
   setProductIdentity(target, { name: product, client });
   setLanguagePolicy(target, { docLanguage, docFilenameLanguage, chosen: languageChosen });
   upsertAgentFiles(target, agents, product);
+  // Mechanical, idempotent, and re-run on EVERY update because both sides are restored behind our
+  // back: `npx skills update` puts the author's flag back, and BMad's installer rewrites its own
+  // wrappers. A one-time fix would hold for about a week.
+  enableEngineInvocation(target);
+  retireBmadG5(target);
+  writeDenyRules(target);
   writeStamp(target);
   printSummary(target, agents, { first, was, written, skipped, skills, tomls, opencodeCmds });
   printNextSteps({
@@ -1224,6 +1534,52 @@ function apply(target, agents,
   });
 }
 
+function enginesCommand(target, { fix }) {
+  const before = enginesReport(target);
+  console.log("");
+  console.log(`  engines   ${before.present ? "all present" : `MISSING ${before.missing.join(" · ")}`}`);
+  for (const name of ENGINE_SKILLS) {
+    const copies = before.files.get(name);
+    if (!copies) continue;
+    const flagged = [...copies.keys()].some((f) =>
+      /^disable-model-invocation\s*:\s*true/m.test(fs.readFileSync(f, "utf8")));
+    const where = [...copies.values()].map((f) => posixRel(target, f)).join(", ");
+    console.log(`    ${name.padEnd(17)}${flagged ? "flagged — no skill can invoke it" : "invocable"}  ${DIM}${where}${RESET}`);
+  }
+  const banned = repoSkillFiles(target, BMAD_RETIRED_G5);
+  const open = [];
+  for (const [name, copies] of banned) {
+    const shut = [...copies.keys()].every((f) =>
+      /^disable-model-invocation\s*:\s*true/m.test(fs.readFileSync(f, "utf8")));
+    if (!shut) open.push(name);
+  }
+  console.log(`  bmad G5   ${banned.size} installed, ${open.length ? `STILL model-invocable: ${open.join(" · ")}` : "all retired"}`);
+  const tracker = path.join(target, "docs", "agents", "issue-tracker.md");
+  const trackerOwn = fs.existsSync(tracker)
+    && fs.readFileSync(tracker, "utf8").includes("seeded by `wdi-method`");
+  console.log(`  config    docs/agents/issue-tracker.md ${trackerOwn ? "is the method's" : "is NOT the method's — upstream's answer sends the engines to the wrong place"}`);
+  console.log("");
+
+  if (!fix) {
+    if (!before.present || open.length || !trackerOwn
+        || engineInvocationState(target).blocked.length) {
+      console.log(`  ${DIM}to repair what can be repaired:${RESET} npx wdi-method engines --fix`);
+      console.log("");
+    }
+    return;
+  }
+  repairAgentDocs(target);
+  enableEngineInvocation(target);
+  retireBmadG5(target);
+  writeDenyRules(target);
+  writeStamp(target);
+  ok("engines aligned");
+  if (!before.present) {
+    console.log("");
+    console.log(enginesMissingMessage(before.missing));
+  }
+}
+
 function verify(target, agents) {
   requireKit();
   const missing = [];
@@ -1436,8 +1792,11 @@ async function runWizard(pre) {
       : "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})`,
+      ? `Engines (mattpocock/skills, in this repo): all ${ENGINE_SKILLS.length} present`
+      : `Engines: MISSING ${enginesReport(target).missing.join(" · ")} — ${ENGINES_INSTALL_ANY} (${ENGINES_REPO})`,
+    engineInvocationState(target).blocked.length
+      ? `Engine invocation: BLOCKED for ${engineInvocationState(target).blocked.join(" · ")} — npx wdi-method engines --fix`
+      : "Engine invocation: enabled (the author's disable-model-invocation is stripped from the repo's copies)",
     nonempty ? "Folder is not empty (normal for a product repo already under way)" : "Folder is empty",
   ].join("\n");
   p.note(facts, "Detected");
@@ -1582,7 +1941,7 @@ function runNonInteractive(args) {
     die(bmadMissingMessage());
   }
   if (!args.skipEngines && !enginesPresent(target)) {
-    die(enginesMissingMessage());
+    die(enginesMissingMessage(enginesReport(target).missing));
   }
   const existing = readIndexIdentity(target);
   const product = args.product || existing.name;
@@ -1600,7 +1959,7 @@ function runNonInteractive(args) {
 
 async function main() {
   const args = parseArgs(process.argv);
-  if (!["wizard", "install", "update", "verify", "promote"].includes(args.cmd)) {
+  if (!["wizard", "install", "update", "verify", "promote", "engines"].includes(args.cmd)) {
     usage();
     process.exit(2);
   }
@@ -1623,6 +1982,10 @@ async function main() {
     promote(args.dir);
     return;
   }
+  if (args.cmd === "engines") {
+    enginesCommand(requireTarget(args.dir), { fix: Boolean(args.fix) });
+    return;
+  }
   const wantTui = !args.yes && args.cmd !== "verify" && process.stdin.isTTY && process.stdout.isTTY;
   if (wantTui) {
     await runWizard(args);

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

@@ -25,10 +25,13 @@ The repo layout is governed by `corpus-guide.md` and mapped by
 | `.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; MUST be in git, not curated |
+| `.scratch/` | One directory per effort: a spec's `SPEC.md` and its ticket files, and ad hoc work that has no `FR` yet. MUST be in git — the corpus cites into it by path |
 | `.work/` | Scratch; MUST be in git, emptied when a task closes |
 | *(application roots)* | Application code — named and mapped in `.control/structure-codebase.md` |
 
-The method does not use a `docs/` layer for corpus or rules. A leftover `docs/`
+**One exception, and it is not corpus.** `docs/agents/issue-tracker.md` and `docs/agents/domain.md` are the ENGINES' config, and their path belongs to the engines' author — `to-spec`, `to-tickets`, `implement` and `triage` read those two files and nowhere else. What they SAY is this method's, and `wdi-method` seeds both already answered. Neither is corpus, neither is a rule, and nothing else MAY be added beside them.
+
+Otherwise the method does not use a `docs/` layer for corpus or rules. A leftover `docs/`
 folder is inventory to sort, not a second home.
 
 ## Article 4 — Lifecycle

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

@@ -47,12 +47,16 @@ inventory, and putting somebody else's skill in it makes the register a lie.
 
 No → **absorb the discipline and invoke nothing.** Prose we could have written is not an engine.
 
-An engine whose output this corpus keeps is invoked even when it is a **plugin rather than part of this
-package's install** — `mattpocock-skills:domain-modeling` is the case, and `wdi-blueprint` invokes it. Two
-rules make that safe in a repo that does not have it:
-
-- **A missing plugin is a state, not a defect.** Report it once, name the standard the work is still held
-  to, and do the work. You MUST NOT block a gate on it, and you MUST NOT report its absence as a finding.
+An engine whose output this corpus keeps is invoked even though it is **not part of this package's
+install** — `domain-modeling` is the case, and `wdi-blueprint` invokes it. It is one of the six the
+installer requires IN the repo, so it is named without a plugin prefix: a repo may hold the engines as
+its own files or not at all, and `mattpocock-skills:domain-modeling` resolves to nothing in the first
+case. Two rules make the reference safe in a repo that does not have it:
+
+- **A missing engine is a state, not a defect — at G1–G4.** Report it once, name the standard the work
+  is still held to, and do the work. You MUST NOT block one of those gates on it, and you MUST NOT
+  report its absence as a finding. G5 is the exception and always was: `wdi-build` cannot run without
+  the engines, and the installer refuses rather than let that be discovered with a spec already open.
 - **The wrapper carries the standard, never the plugin.** What the engine is invoked *for* MUST be written
   in the wrapping skill as behaviours to verify — so the same bar is met either way, and a run that
   produced none of them is reported as a transcription rather than landed.