wdi-method 0.6.2 → 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

package/bin/wdi-method.js

@@ -123,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}
 `);
@@ -166,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") {
@@ -318,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
@@ -425,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");
@@ -1027,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
@@ -1436,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/skills/wdi-autopilot/SKILL.md

@@ -105,6 +105,14 @@ Open with three reads, in this order:
 2. **Reconcile `## Resume` against git.** Compare the run branch HEAD with the commit Resume names. A
    difference is work that landed before the last iteration died — rebuild Resume from what git shows
    **before** starting anything new. Trusting a stale Resume is how a merged ticket gets implemented twice.
+
+   **A ledger with no `## Resume` heading at all is the same case, one step further back.** It is a
+   pre-0.6.2 ledger — a flat table with nothing else — and `update` only ever renames the file, never
+   restructures its content, because that restructuring needs exactly this read. Heal it once, here,
+   before touching anything else: wrap the existing table under a `## Decisions` heading if it is not
+   already, then **build a fresh `## Resume`** the same way as a stale one above — from the mandate row,
+   `.control/generated/status`, and the run branch's actual HEAD, never from the table's last row read as
+   prose. The table's own rows are untouched; only the missing head is added.
 3. `.control/generated/status`, the mandate row, and **the ledger's `## Resume` only** — see § The ledger
    for why that is a section and not a file.
 
@@ -330,6 +338,7 @@ When § The work table reaches § Finish:
 - A mandate accepted by delegation, or with no `expires`
 - Deciding something the mandate parks, or parking something the mandate did not
 - A decision taken and not written to the ledger
+- A pre-0.6.2 ledger left un-healed — no `## Resume` wrapped and rebuilt on first touch
 - Reading the whole ledger when the run is alive — `## Resume` is what an iteration loads
 - A `## Resume` that restates a decision, or repeats what the registry already answers
 - A ledger cell longer than a line, instead of a pointer to a companion document

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

@@ -49,6 +49,10 @@ mis-route in this flow, because every other gate is the same for every component
 | State | Next |
 |---|---|
 | `wdi-method update` just ran and its summary printed an `upgrade` line | `wdi-upgrade` — **before anything else**. Content is still in the old shape, and every skill below reads the new one |
+| `wdi-method update` just ran and printed **no** `upgrade` line | Nothing. The update was mechanical and complete; carry on from wherever the gates say you are |
+| `wdi-method install` just ran, first time in this repo | `wdi-init` intent `setup` — the global `mode`, and nothing has started until it is set |
+| Someone asks whether to run `/setup-matt-pocock-skills` | **No**, unless they are changing tracker. `install` and `update` seed `docs/agents/` already answered for this method; re-running the interview restores defaults that contradict Article 3 |
+| The installer refused, naming the ticket engines | Not a skill. Install them — `/plugin install mattpocock-skills`, or `npx skills@latest add mattpocock/skills` — then run the installer again |
 | No registry, or no global `mode` set | `wdi-init` intent `setup` — nothing has started |
 | No `.what/_product-brief/brief.md` | `wdi-problem` — G1 has not started |
 | A brief exists, and no PRD covers the area in play | `wdi-product` intent `prd` |
@@ -87,6 +91,10 @@ it claims, or when one of its eight required sections is missing outright.
   as blocking a design gate; `assumptions.md` holds nothing.
 - You MUST NOT invent progress. If `.control/generated/status` is missing or stale, say so and name
   `validate.py --generate`.
+- You MUST NOT route anyone to `/setup-matt-pocock-skills` to *finish an install*. The installer seeds
+  `docs/agents/` pre-answered, and that interview's own defaults send every engineering skill looking for a
+  root `CONTEXT.md` and `docs/adr/` — which Article 3 forbids and `wdi-reconcile` reports. It is for
+  changing tracker, and nothing else.
 - You MUST NOT run other skills on the user's behalf. Name the skill; let them invoke it. The one skill that
   runs others is `wdi-autopilot`, and only under a mandate the owner accepted — that is what the mandate is.
 - When the next step is blocked by a decision rather than by work, route to `wdi-question` or

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

@@ -10,6 +10,14 @@ content needs no judgment, seeds what is new, prunes what is retired. It stops e
 about **content** begins — which PRD an `FR` belongs to, whether a sentence in the old brief was an
 assumption or a constraint. Those are this skill's half.
 
+**This skill's content is `.what/` and `.how/`** — the corpus a human reads. It does NOT cover
+`.control/memlog/` or a registry row: an autopilot ledger's filename is `update`'s own mechanical rename
+(the same way `waves.yaml` became `specs.yaml`), a stale mandate setting is a printed warning at `update`
+time because overwriting it would be overwriting a value the owner already chose, and a ledger's internal
+shape is healed by `wdi-autopilot` itself on its next run, because only it can read git and the registry to
+know where that run actually stands. Route those three there; this skill's report would have nothing to say
+about any of them.
+
 **This is the one skill allowed to edit `brief.md`, `prd.md`, an SRS, an SDD, or a C4 file directly.**
 Every other skill is forbidden, because a hand edit makes the memlog lie about how the document was
 produced. An upgrade produces nothing: it moves sentences that already exist into the home the new

package/kit-overlay/AGENTS.md

@@ -154,6 +154,9 @@ verifies the result, and lands the memlog.
   not diligence.
 - `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on every BMad update;
   customise through `_bmad/custom/`.
+- `CONTEXT.md`, `CONTEXT-MAP.md`, and `docs/adr/` MUST NOT be created. `docs/agents/domain.md` is the
+  engines' config and says so too: the vocabulary is `.control/product-glossary.md`, domain knowledge is
+  `.what/`, design is `.how/`, and a decision is a `DEC-` — never an ADR. Article 3 owns the rule.
 
 ## Routing — load a guide when the task matches
 
@@ -184,6 +187,7 @@ verifies the result, and lands the memlog.
 | Looking for where code lives, or placing new code | `.control/structure-codebase.md` |
 | Looking for where a document lives | `.control/structure-document.md` |
 | Writing or reviewing code | `.constitution/project/codebase-stack-guide.md` · `.constitution/project/codebase-conventions-guide.md` · `.constitution/project/codebase-brownfield-guide.md` |
+| Running `to-spec`, `to-tickets`, `implement`, or `triage` | `docs/agents/issue-tracker.md` · `docs/agents/domain.md` — the engines' own config, seeded by `wdi-method` already answered for this method |
 
 All three `.constitution/project/codebase-*-guide.md` start as `status: Draft`. While they are, their contents MAY be read
 as guidance but MUST NOT be used to reject a change.

package/package.json

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

package/scaffold/docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+**This repo does not use `CONTEXT.md`, `CONTEXT-MAP.md`, or `docs/adr/`, and none of them MUST be
+created.** WDI Method already owns every home they would occupy, and a second home for the same fact is
+drift rather than tidiness. `.constitution/method/constitution.md` Article 3 states it outright: this
+method has no `docs/` layer for corpus or rules, and `wdi-reconcile` reports a root `CONTEXT.md` or a
+`docs/adr/` as a finding against that article.
+
+This file is seeded by `wdi-method` so the answer is right from the first install. `/setup-matt-pocock-skills`
+would otherwise write its own default here — one that points at exactly the two paths above — and every
+repo that ran it has had to hand-correct this file afterwards.
+
+## Where each thing actually lives
+
+| Looking for | Read |
+|---|---|
+| What a domain term means | `.control/product-glossary.md` |
+| What is promised — a capability, an `FR`, a use case, a business rule | `.what/` |
+| How it is built — the spine, C4, an inventory, an SDD, a contract | `.how/` |
+| Why it is like this — a decision worth remembering | `.control/decisions/`, indexed by the generated decision table under `.control/generated/` |
+| An architectural invariant | an `AD-N` in the architecture spine, under `.how/_platform/` |
+| Which contexts exist and what each owns | `.control/registry/components.yaml` |
+| Where code lives | `.control/structure-codebase.md` |
+| Where documents live | `.control/structure-document.md` |
+
+`AGENTS.md` § *The thing in your hand → its folder* is the short version of this table and is the
+authority. Where this file and `AGENTS.md` disagree, `AGENTS.md` wins.
+
+## A decision is a `DEC-`, never an ADR
+
+`decision-guide.md` owns the shape, the one test that decides whether a decision is recorded at all, and
+the `draft → accepted → applied` ladder. An ADR file under `docs/adr/` MUST NOT be written in its place:
+the numbering is global and lives in `.control/registry/decisions.yaml`, and a decision recorded outside
+it is invisible to `refs-resolve`, to the RTM, and to the generated decision table.

package/scaffold/docs/agents/issue-tracker.md

@@ -0,0 +1,43 @@
+# Issue tracker
+
+Where issues live for this repo, and what `to-spec`, `to-tickets`, and `triage` read and write.
+
+This file is seeded by `wdi-method`. It is the product's from here on: change the tracker whenever you
+like, but keep the three invariants below, because `wdi-build` and the validators read them.
+
+## Two places, and they are not the same place
+
+| | Owned by | Lives at |
+|---|---|---|
+| **A spec's tickets** — the work behind an `FR` | `wdi-build`, at G5 | `{spec_folder}/issues/<NN>-<slug>.md`, `spec_folder` from `.control/registry/specs.yaml` |
+| **Ad hoc work** — a quick bug report, a small idea, engineering-skill scratch | this file's convention | `.scratch/<slug>/` |
+
+`.scratch/` MUST NOT become a second place to plan a feature that already has an `FR`. The moment ad hoc
+work turns out to touch an `FR`, it stops and becomes a spec through `wdi-build` — the Fast Path rule in
+`delivery-flow-guide.md` owns that boundary.
+
+## The three invariants
+
+Whatever tracker this repo uses — local markdown, GitHub, GitLab, Jira — these MUST hold:
+
+1. **One parent per spec, one issue per ticket.** A ticket is an issue, never a sub-task: only an issue
+   carries native blocking edges, and the frontier is read from them.
+2. **Status lives on the ticket itself and nowhere else.** A `**Status:**` line near the top of the
+   ticket file, or `status:` in its frontmatter. `ticket-status-one-home` reads it there, and copying it
+   into `specs.yaml` is what that validator exists to refuse.
+3. **Every ticket names what it `satisfies`** — the `UC` or `FR` behind it. Without it the chain
+   `FR → UC → ticket → test` breaks and the RTM cannot say which promise went green.
+
+## Conventions — local markdown
+
+- One effort per directory: `.scratch/<slug>/`
+- One file per ticket at `.scratch/<slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single
+  combined file
+- Blocking edges as a `Blocked by: NN, NN` line near the top
+- Comments append at the bottom under a `## Comments` heading
+
+## Switching to a real tracker
+
+Re-run `/setup-matt-pocock-skills` and pick it, then keep the three invariants above. The mapping WDI
+Method expects is in `delivery-flow-guide.md` § *Mapping to a tracker*: parent issue is the spec, issue is
+the ticket, Fix Version is the release, and the `CAP`/`FR` travel as labels.