wdi-method 0.6.1 → 0.6.4

package/README.md

@@ -25,7 +25,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
-you reach G5, but doing it now means nothing stops you later.
+**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.
 
 **1. BMad Method** — in the product repo, picking the same agents you will give this installer:
 
@@ -44,8 +47,16 @@ claude plugins install mattpocock-skills      # or, inside a session:  /plugin i
 npx skills@latest add mattpocock/skills
 ```
 
-Then, once, inside your agent, run `/setup-matt-pocock-skills`: it asks which issue tracker `to-tickets`
-should publish to (local files, GitHub, Linear, …).
+**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
+markdown — and keep the three invariants the seeded `issue-tracker.md` names.
+
+The seeding exists because the interview's own defaults are wrong here in one specific way: they send every
+engineering skill looking for a root `CONTEXT.md` and `docs/adr/`, and Article 3 says this method has no
+`docs/` layer for corpus or rules — `wdi-reconcile` reports both as findings. A repo that ran the setup
+before installing this package keeps its own file, and the installer names the contradiction rather than
+overwriting it.
 
 **3. WDI Method:**
 
@@ -97,6 +108,36 @@ answers with the gate you are at, not with a menu.
 
 ---
 
+## What to do right after install, and right after update
+
+Two questions, and the honest answer to most of them is *nothing*. `wdi-help` answers them from the
+registry at any time; this table is the same answer written down.
+
+### After `install`
+
+| | |
+|---|---|
+| Engines missing | You never get here — `install` refuses, and names both install paths. Install them, run it again |
+| `/setup-matt-pocock-skills`? | **No.** The installer seeded `docs/agents/` already answered for this method. Run that interview only to *change* tracker |
+| So what is first? | **`wdi-init` intent `setup`** — it sets the global `mode`, and nothing has started until it is |
+| Then? | `wdi-problem` for G1. Or ask `wdi-help`, which reads the registry rather than this table |
+
+### After `update`
+
+| The summary said | Do |
+|---|---|
+| an **`upgrade`** line, naming content still in the old shape | **`wdi-upgrade`, before any other skill.** It moves every sentence into its new home, invents nothing, reports what it could not place, and ends in one commit. `wdi-help` and the validators read the new shape; a corpus half in the old one answers them wrongly |
+| **no** `upgrade` line | Nothing. The update was mechanical and complete — carry on from wherever the gates say you are |
+| `seeded docs/agents/` | Nothing. An older repo just received the engines' config, pre-answered. Read it if you like; do not run the setup interview to redo it |
+| a warning that `domain.md` still points at a root `CONTEXT.md` | Add the correction that warning names to the top of that file. It was written by the setup interview before this package was installed, and it sends every engineering skill at two paths Article 3 forbids |
+| a warning naming a **mandate** and `ad-n` | Only if you run `wdi-autopilot`. Decide whether that mandate should now park `AD-N` contradictions, and edit its `parked` list yourself — `update` never edits an authority you granted |
+
+**`wdi-upgrade` is only ever about corpus content** — a brief, a PRD, an SRS, registry rows in the old
+shape. It is not the answer to a missing engine, a missing tracker config, or anything under
+`.control/memlog/`; each of those is handled by the installer itself or by the skill that owns it.
+
+---
+
 ## How to use it — the walk
 
 A gate is a moment where a human reads **one page** and decides. Between gates the AI works in a
@@ -114,6 +155,16 @@ renders, decide — advance or refine.
 | 6 | `wdi-report` intent `estimate` | `.control/generated/estimate.md` | which candidate row becomes the next spec |
 | 7 | `wdi-build` — for that row | nothing: tickets are machine contracts. You answer `to-tickets`' quiz on granularity and blocking edges | **G5** — is it done and proven? Once per spec |
 | 8 | `wdi-report` intent `progress` | the report it writes | what has moved, what is late, what is proven |
+| 9 | `wdi-autopilot` — when you would rather review the result than walk steps 6–8 yourself | its preflight page, then its final report and ledger | one **mandate**: scope, what stays parked for you, smoke test by the agent or by you, loop interval, expiry |
+
+**Unattended, on request.** `wdi-autopilot` moves owner time from the gates to two points: the mandate before,
+the review after. From the gate you name it runs the same skills, answers what they would have asked, records
+every answer in `.control/memlog/autopilot-<date>.md`, and stops only when every `FR` in scope is closed or the
+mandate expires. It needs three things from the session: permission prompts bypassed (one prompt halts the
+loop), a loop to fire it — `/loop 5m /wdi-autopilot` in Claude Code — and a way past the ticket engines'
+`disable-model-invocation`, which the preflight names: a builder that reads and follows the engine's `SKILL.md`,
+or a copy of the engines inside the repo. The validator `mandate-accept` keeps the one thing the method never
+gives up: a person, dated, at the root of every delegated acceptance.
 
 **Refine, do not advance.** When a page does not convince you, run the same skill again and say what is
 wrong — it updates the document it owns. Nothing downstream exists yet, so nothing breaks. Advancing past a
@@ -282,7 +333,7 @@ which review lenses run, and which review traces a validator will demand.
 
 ---
 
-## Five gates, seventeen skills
+## Five gates, eighteen skills
 
 | Gate | Decides | Skill |
 |---|---|---|
@@ -293,7 +344,7 @@ which review lenses run, and which review traces a validator will demand.
 | **G5 Release** | Whether it is done and proven | `wdi-build` |
 
 Around them: `wdi-init` (scaffold, component birth, depth and risk settings, structure maps),
-`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-explain-to-me`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
+`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-explain-to-me`, `wdi-autopilot`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
 `wdi-systematic-debugging`, and `wdi-upgrade` (moves a corpus written under an older kit into the current
 shape — content moves, nothing is invented).
 
@@ -382,9 +433,9 @@ English, whatever the settings say — it travels to every repo through this pac
 
 | | |
 |---|---|
-| Overwrites | everything in `.constitution/method/` · the seventeen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
+| Overwrites | everything in `.constitution/method/` · the eighteen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
 | Renames | a file whose content needs no judgment to move — `waves.yaml` → `specs.yaml`, the pre-0.5 registry names. Content is never rewritten |
-| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the seventeen. Each removal is printed |
+| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the eighteen. Each removal is printed |
 | Reports | what is still in the OLD shape, as an `upgrade` line — and names `wdi-upgrade` as the next step. The installer does not move content; that is a decision, and the skill's |
 | Keeps | All of `.constitution/project/`, plus your initiative slug and your language choice. A setting somebody already chose is not the installer's to change behind their back |
 | Never resurrects | A folder you retired. On update, absence is treated as a decision |

package/bin/wdi-method.js

@@ -49,6 +49,7 @@ const WDI_SKILLS = [
   "wdi-log",
   "wdi-help",
   "wdi-explain-to-me",
+  "wdi-autopilot",
   "wdi-reconcile",
   "wdi-review",
   "wdi-report",
@@ -122,6 +123,7 @@ function usage() {
   --doc-language <text>            prose of working documents; free text, default English
   --doc-filename-language <text>   slug part of document filenames; free text, default English
   --skip-bmad-check
+  --skip-engines-check      install without to-spec / to-tickets / implement
 
 BMad first, then this package. ${WDI_REPO}
 `);
@@ -165,6 +167,7 @@ function parseArgs(argv) {
   while (rest.length) {
     const t = rest.shift();
     if (t === "--skip-bmad-check") args.skipBmad = 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;
     else if (t === "--agents") {
@@ -317,6 +320,29 @@ function bmadMissingMessage() {
   ].join("\n");
 }
 
+// The engines used to WARN and let the install through, on the reasoning that G1-G4 run without them and
+// a first install has no G5 yet. Both halves are still true, and the reasoning stopped being enough:
+// `wdi-autopilot` needs all three from its first iteration, and a warning inside a forty-line summary is
+// read exactly as often as it is skipped. The failure it was meant to prevent — learning they are missing
+// inside `wdi-build`, with a spec already open — kept happening anyway.
+//
+// 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() {
+  return [
+    "The ticket engines are not installed. G5 (wdi-build) and wdi-autopilot need all three.",
+    "",
+    `  Claude Code:  ${ENGINES_INSTALL}`,
+    `  Other agents: ${ENGINES_INSTALL_ANY}`,
+    "",
+    "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.`,
+    `Source: ${ENGINES_REPO}`,
+    "",
+    "G1-G4 run without them. To install anyway and add them later:  --skip-engines-check",
+  ].join("\n");
+}
+
 // 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
@@ -424,6 +450,117 @@ function splitProductConstitution(file) {
 // 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.
+// `wdi-autopilot` named its ledger for the DAY before 0.6.2 — `autopilot-<YYYY-MM-DD>.md`. The mandate
+// it belongs to is named for the MANDATE now — `autopilot-<DEC-id>.md` — because two mandates opened
+// on the same day would otherwise append to one file and destroy both as a record, and because
+// `mandate-accept` (the validator introduced alongside the rename) looks for the file at that path and
+// nowhere else. This is a pure rename, like `waves.yaml` → `specs.yaml`: the ledger's own content is
+// never touched, only found and moved. Renaming it is what a script can safely do; restructuring its
+// CONTENT into the `## Resume` / `## Decisions` split is not — that has to read git and the registry to
+// know where the run actually stands, so it is the skill's own job on the next iteration it runs, not
+// this installer's.
+// `/setup-matt-pocock-skills` interviews the owner and writes `docs/agents/`. Two of its answers are
+// wrong for a WDI repo, and BOTH repos that ran it had to hand-correct the SAME file afterwards:
+//
+//   - `domain.md` tells agents to read and lazily create a root `CONTEXT.md` and `docs/adr/`. Article 3
+//     says this method has no `docs/` layer for corpus or rules, and `wdi-reconcile` reports both as
+//     findings. The homes already exist: `.control/product-glossary.md`, `.what/`, `.how/`, `DEC-`.
+//   - `issue-tracker.md`'s local-markdown default puts every ticket under `.scratch/<feature>/`, while
+//     `wdi-build` owns tickets at `{spec_folder}/issues/`. Two homes for one ticket set.
+//
+// Seeding them removes the interview for the answers WDI Method actually has a requirement on. Seeded
+// ONCE and never overwritten — after the first install they are the product's, like every other file
+// under a path the product owns. An owner who wants a different tracker re-runs the setup skill; the
+// seeded file says which three invariants have to survive that.
+function seedAgentDocs(target) {
+  const dir = path.join(target, "docs", "agents");
+  let wrote = 0;
+  for (const name of ["domain.md", "issue-tracker.md"]) {
+    const to = path.join(dir, name);
+    if (fs.existsSync(to)) continue;
+    const seed = path.join(ROOT, "scaffold", "docs", "agents", name);
+    if (!fs.existsSync(seed)) continue;
+    copyFile(seed, to);
+    wrote += 1;
+  }
+  if (wrote) {
+    note(`seeded docs/agents/ (${wrote} file${wrote === 1 ? "" : "s"}) — the engines' config, pre-answered`);
+    note("  do NOT run /setup-matt-pocock-skills to redo these; re-run it only to change tracker");
+  }
+  return wrote > 0;
+}
+
+// A repo that ran the setup skill BEFORE installing this package still carries the default `domain.md`,
+// and it is actively misleading: it sends every engineering skill looking for a root `CONTEXT.md` and
+// `docs/adr/`, and tells them to create both lazily. Seeding cannot fix it, because the file already
+// exists and a file under a product-owned path is never overwritten. So it is named instead.
+function warnStaleAgentDocs(target) {
+  const file = path.join(target, "docs", "agents", "domain.md");
+  if (!fs.existsSync(file)) return;
+  const text = fs.readFileSync(file, "utf8");
+  if (!/CONTEXT\.md|docs\/adr/.test(text)) return;
+  // An override note is what both real repos added by hand. Recognising it is what stops this warning
+  // from firing forever on a file somebody already fixed.
+  if (/does not use|MUST NOT be created|no `docs\/` layer/i.test(text)) return;
+  note("docs/agents/domain.md still points agents at a root CONTEXT.md and docs/adr/");
+  note("  Article 3: this method has no `docs/` layer for corpus or rules, and wdi-reconcile");
+  note("  reports both as findings. Say so at the top of that file — the glossary is at");
+  note("  .control/product-glossary.md and a decision is a DEC-, never an ADR");
+}
+
+function migrateAutopilotLedgers(target) {
+  const dir = path.join(target, ".control", "memlog");
+  if (!fs.existsSync(dir)) return;
+  const OLD = /^autopilot-(\d{4}-\d{2}-\d{2})\.md$/;
+  for (const name of fs.readdirSync(dir)) {
+    const m = OLD.exec(name);
+    if (!m) continue;
+    const from = path.join(dir, name);
+    const text = fs.readFileSync(from, "utf8");
+    const artifact = /^artifact:\s*(\S.*)$/m.exec(text)?.[1]?.trim();
+    const id = artifact && /(DEC-\d+)/.exec(artifact)?.[1];
+    if (!id) {
+      note(`.control/memlog/${name} looks like a pre-0.6.2 autopilot ledger, but its \`artifact:\` does`);
+      note(`  not resolve to a DEC- id — rename it to autopilot-<the mandate's DEC- id>.md yourself`);
+      continue;
+    }
+    const to = path.join(dir, `autopilot-${id}.md`);
+    if (fs.existsSync(to)) {
+      note(`BOTH .control/memlog/${name} and autopilot-${id}.md exist — neither was touched`);
+      note(`  the run's ledger is in one of them and I cannot tell which. Merge them, then delete the other`);
+      continue;
+    }
+    mv(from, to);
+    note(`renamed .control/memlog/${name} → autopilot-${id}.md (content unchanged)`);
+    note(`  \`mandate-accept\` looks for a mandate's ledger at this exact path`);
+  }
+}
+
+// A mandate opened before 0.6.2 recorded `parked: []` under the OLD default — full authority, AD-N
+// contradictions included. 0.6.2 changed the DEFAULT for a NEW mandate to park `ad-n`, because
+// decision-guide.md says narrowing an invariant MUST NOT be softened further. A default only applies
+// at the moment a mandate is written, so an EXISTING accepted mandate keeps whatever it already says —
+// silently adding `ad-n` to it would be overwriting a value the owner already chose, which `update`
+// MUST NOT do to anything in the product's own registry. So this only ever WARNS, naming the mandate
+// and the one line that would close the gap, and leaves the decision to whoever reads the summary.
+function warnStaleMandates(target) {
+  const file = path.join(target, ".control", "registry", "decisions.yaml");
+  if (!fs.existsSync(file)) return;
+  const text = fs.readFileSync(file, "utf8");
+  const blocks = text.split(/\n(?=\s*-\s*id:\s*DEC-)/);
+  for (const block of blocks) {
+    if (!/type:\s*mandate/.test(block)) continue;
+    if (!/status:\s*accepted/.test(block)) continue;
+    const id = /id:\s*(DEC-\d+)/.exec(block)?.[1];
+    const parkedLine = /parked:\s*(\[[^\]]*\]|.*)$/m.exec(block)?.[0] || "";
+    const parkedBlockList = /parked:\s*\n((?:\s+-\s*\S.*\n?)*)/.exec(block)?.[1] || "";
+    if (/ad-n/.test(parkedLine) || /ad-n/.test(parkedBlockList)) continue;
+    note(`${id || "a mandate"} predates the \`ad-n\`-parked-by-default protection (0.6.2) — its \`parked\``);
+    note(`  list does not name it, so it still decides an AD-N contradiction on its own`);
+    note(`  add \`ad-n\` to its \`parked\` list in decisions.yaml yourself if you want the new default`);
+  }
+}
+
 function migrateRegistryNames(target) {
   const reg = path.join(target, ".control", "registry");
   const from = path.join(reg, "waves.yaml");
@@ -1026,6 +1163,10 @@ function apply(target, agents,
   // is about to occupy. Running it after would leave two copies of most guides.
   const migrated = migrateToTwoFolders(target);
   migrateRegistryNames(target);
+  migrateAutopilotLedgers(target);
+  warnStaleMandates(target);
+  seedAgentDocs(target);
+  warnStaleAgentDocs(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
@@ -1435,6 +1576,9 @@ function runNonInteractive(args) {
   if (!args.skipBmad && !bmadPresent(target)) {
     die(bmadMissingMessage());
   }
+  if (!args.skipEngines && !enginesPresent(target)) {
+    die(enginesMissingMessage());
+  }
   const existing = readIndexIdentity(target);
   const product = args.product || existing.name;
   const client = args.client ?? existing.client;

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

@@ -29,7 +29,7 @@ Never a rule. When it disagrees with a guide, the guide wins and the disagreemen
 
 | File | Opened when |
 |---|---|
-| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, seventeen skills, WDI ↔ BMad |
+| [`why/README.md`](why/README.md) | You want the whole shape in five minutes — five gates, two settings, eighteen 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 |