create-cmp-cli 0.15.0 → 0.17.0

package/README.md

@@ -25,7 +25,10 @@ npm create kmp@latest my-app
 
 Deterministic (stamps a frozen, CI-verified template), non-interactive with flags, exits non-zero
 on failure — and it **builds the app to prove it's green** before reporting success.
-Agent-readable: [llms.txt](./llms.txt) · [options.schema.json](./options.schema.json).
+Agent-readable: [llms.txt](./llms.txt) · [AGENTS.md](./AGENTS.md) · [options.schema.json](./options.schema.json).
+
+**Claude Code users:** `/plugin marketplace add kvdm-co-pilot/create-cmp` →
+`/plugin install create-cmp` — [10 skills + the cmp-inspector MCP server](#the-claude-code-plugin-10-skills).
 
 ## What is this, in plain words
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {

package/packages/harness/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@create-cmp/harness",
-  "version": "0.14.1",
-  "description": "The create-cmp verify lane \u2014 the machine-owned harness code every stamped app carries byte-identical: evidence receipts, spec coverage, approvals, conformance reporting, golden trees, a11y, and the preview/inspector libs. Dependency-free ESM, vendored into each generated project so the lane runs offline with no install step, and content-hashed so a receipt can name the exact lane that issued it.",
+  "version": "0.15.0",
+  "description": "The create-cmp verify lane — the machine-owned harness code every stamped app carries byte-identical: evidence receipts, spec coverage, approvals, conformance reporting, golden trees, a11y, and the preview/inspector libs. Dependency-free ESM, vendored into each generated project so the lane runs offline with no install step, and content-hashed so a receipt can name the exact lane that issued it.",
   "type": "module",
   "main": "src/verify.mjs",
   "exports": {

package/packages/harness/src/lib/walk.mjs

@@ -0,0 +1,277 @@
+// walk.mjs — the walk: where every open change stands, whose turn it is, and
+// what arrives unplanned. docs/features/walk-status.md is the brief of record.
+//
+// A PROJECTION, not new state (D1): everything here re-renders the derivation
+// getFeatureBoard already computes (phase, nextStep with owner, clause
+// coverage, provenDone). No new ledger, nothing agent-declared, nothing to
+// forget to update — if a number here could disagree with the board, this
+// module is wrong.
+//
+// Vocabulary (D2/D3): six stages — Decide · Design · Contract · Build ·
+// Prove · Sign-off — and clauses rendered as PROMISES ("keeping promise 5 of
+// 7"). Mechanically exact: a clause is a behavioral promise, a citing green
+// test is that promise kept, provenDone is all of them kept with the receipt
+// attesting this tree.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { getFeatureBoard, getApprovalStatuses, readJournal } from "./approvals.mjs";
+import { CLAUSE_LINE_RE } from "./spec-coverage.mjs";
+
+/** The six stages, in walk order. `label` is the only user-facing name (D2). */
+export const STAGES = [
+  { key: "decide", label: "Decide" },
+  { key: "design", label: "Design" },
+  { key: "contract", label: "Contract" },
+  { key: "build", label: "Build" },
+  { key: "prove", label: "Prove" },
+  { key: "signoff", label: "Sign-off" },
+];
+
+/** nextStep.key -> the stage that step belongs to. `closed` maps to none. */
+const STEP_STAGE = {
+  "sign-brief": "decide",
+  "re-approve": "decide",
+  design: "design",
+  audit: "design",
+  "sign-design": "design",
+  contract: "contract",
+  "sign-spec": "contract",
+  build: "build",
+  // A sanctioned redesign is promises being re-kept — Build, not a seventh stage.
+  redesign: "build",
+  prove: "prove",
+  accept: "signoff",
+};
+
+/**
+ * A promise's human title: the clause line's own words after the id, first
+ * sentence-ish, capped. "" when the line carries nothing after the id — the
+ * card then falls back to the bare id rather than inventing prose.
+ */
+function promiseTitle(rest) {
+  const cleaned = String(rest ?? "")
+    .replace(/^[\s—:-]+/, "")
+    .replace(/\*\*/g, "")
+    .trim();
+  if (cleaned === "") return "";
+  const cut = cleaned.search(/[.;]\s/);
+  const first = cut === -1 ? cleaned : cleaned.slice(0, cut);
+  return first.length > 110 ? `${first.slice(0, 107)}…` : first;
+}
+
+/**
+ * The spec's promises, in file order: id, title, withdrawn. Reads the spec
+ * directly (same CLAUSE_LINE_RE the coverage gate uses) because the board's
+ * clause list carries ids only — the words are the whole point here (D3).
+ * @returns {Array<{id: string, title: string, withdrawn: boolean}>}
+ */
+export function listPromises(root, specRel) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, specRel), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    const m = line.match(CLAUSE_LINE_RE);
+    if (!m) continue;
+    const rest = line.slice(m[0].length).replace(/^~~/, "");
+    out.push({ id: m[2], title: promiseTitle(rest), withdrawn: Boolean(m[1]) });
+  }
+  return out;
+}
+
+/** The human stops remaining from (and including) the current stage. */
+function remainingStops(stages, currentIdx) {
+  const stops = [];
+  for (let i = Math.max(currentIdx, 0); i < stages.length; i++) {
+    const s = stages[i];
+    if (s.state === "done" || s.state === "skipped") continue;
+    if (s.key === "decide") stops.push("Decide");
+    if (s.key === "design") stops.push("Design sign-off");
+    if (s.key === "contract") stops.push("Contract");
+    if (s.key === "signoff") stops.push("Sign-off");
+  }
+  return stops;
+}
+
+/**
+ * One feature's walk. Stage states are POSITIONAL around the derived current
+ * step: the board's deriveNextStep already resolves every competing condition
+ * (drift outranks acceptance, design before contract, redesign splits by
+ * provenDone) to ONE next act — stages before it are done, after it pending.
+ * Design is `skipped` when the feature honestly has no UI surface (D2).
+ */
+function walkOfFeature(root, f) {
+  const currentKey = STEP_STAGE[f.nextStep?.key] ?? null; // null => closed
+  const currentIdx = currentKey ? STAGES.findIndex((s) => s.key === currentKey) : STAGES.length;
+  const stages = STAGES.map((s, i) => {
+    if (s.key === "design" && f.design === null)
+      return { ...s, state: "skipped", note: "no UI surface" };
+    return { ...s, state: i < currentIdx ? "done" : i === currentIdx ? "current" : "pending" };
+  });
+
+  const promises = listPromises(root, f.specRel).filter((p) => !p.withdrawn);
+  // The promise being kept NOW: first live clause without a citing test —
+  // board clause order, titles from the spec's own words.
+  const citedIds = new Set(f.clauses.filter((c) => c.cited).map((c) => c.id));
+  const current = promises.find((p) => !citedIds.has(p.id)) ?? null;
+
+  // Whose turn (D4): from the board's own owner, never re-derived.
+  const owner = f.nextStep?.owner ?? null;
+  const you =
+    owner === null
+      ? { turn: "none", act: null }
+      : owner === "human"
+        ? { turn: "you", act: f.nextStep.label }
+        : owner.includes("human")
+          ? { turn: "agent", act: f.nextStep.label, then: "your signature" }
+          : { turn: "agent", act: f.nextStep.label };
+
+  return {
+    name: f.name,
+    phase: f.phase,
+    open: f.phase !== "accepted",
+    stages,
+    currentStage: currentKey,
+    promises: { total: f.total, kept: f.covered, current },
+    you,
+    stops: remainingStops(stages, currentIdx),
+    doneReason: f.doneReason,
+  };
+}
+
+/**
+ * Everything the status surfaces render (D5): open walks, plus ARRIVALS (D7)
+ * — governed artifacts drifted or reopened that NO open walk accounts for
+ * (the board's undeclared set, widened to reopens, e.g. a harness upgrade's
+ * rule-change wave). Each arrival carries the journal's last reopen reason so
+ * the surface can say WHY it arrived, not only that it did.
+ * @param {string} root
+ * @returns {{available: boolean, reason?: string, walks: object[], arrivals: object[]}}
+ */
+export function deriveWalks(root) {
+  let board, statuses;
+  try {
+    board = getFeatureBoard(root);
+    statuses = getApprovalStatuses(root);
+  } catch (err) {
+    return { available: false, reason: err?.message ?? String(err), walks: [], arrivals: [] };
+  }
+
+  // Open walks, MOST RECENTLY ACTIVE first (journal recency across the walk's
+  // family) — five features parked at Sign-off must not bury the one being
+  // worked on today (seen on the showcase: bfl-catalog, alphabetical, outshouted
+  // the live navigation-ia walk in the statusline).
+  const journalForOrder = readJournal(root);
+  const lastActivity = (name) => {
+    const family = new Set([`feature-brief:${name}`, `feature-design:${name}`, `feature-spec:${name}`]);
+    for (let i = journalForOrder.length - 1; i >= 0; i--) {
+      if (family.has(journalForOrder[i].artifact)) return i;
+    }
+    return -1;
+  };
+  const walks = board.features
+    .map((f) => walkOfFeature(root, f))
+    .filter((w) => w.open)
+    .sort((a, b) => lastActivity(b.name) - lastActivity(a.name));
+
+  // Ids an open walk accounts for: its own family (brief/design/spec) and its
+  // declared touches. A reopened design mid-walk is that walk's Design stage,
+  // never an arrival (brief, edge cases).
+  const owned = new Set();
+  for (const f of board.features) {
+    if (f.phase === "accepted") continue;
+    owned.add(`feature-brief:${f.name}`);
+    owned.add(`feature-design:${f.name}`);
+    owned.add(`feature-spec:${f.name}`);
+    for (const t of f.touches) owned.add(t.id);
+  }
+  const journal = journalForOrder;
+  const lastReopenReason = (id) => {
+    for (let i = journal.length - 1; i >= 0; i--) {
+      if (journal[i].artifact === id && journal[i].verb === "reopen") return journal[i].reason ?? null;
+    }
+    return null;
+  };
+  const arrivals = statuses
+    .filter((s) => (s.status === "changed-since-approval" || s.status === "reopened") && !owned.has(s.id))
+    .map((s) => ({
+      id: s.id,
+      label: s.label ?? s.id,
+      status: s.status,
+      reason: s.status === "reopened" ? lastReopenReason(s.id) : "changed since its signature",
+    }));
+
+  return { available: true, walks, arrivals };
+}
+
+// ── Renderings — one grammar, four slots (D4) ────────────────────────────────
+
+const bar = (stages) =>
+  stages.map((s) => (s.state === "done" ? "●" : s.state === "current" ? "◐" : s.state === "skipped" ? "·" : "○")).join("");
+
+const stageLabel = (w) => STAGES.find((s) => s.key === w.currentStage)?.label ?? "Closed";
+
+/** The walk whose state is loudest: YOUR TURN beats agent-working. */
+function loudest(walks) {
+  return walks.find((w) => w.you.turn === "you") ?? walks[0] ?? null;
+}
+
+/**
+ * The always-on one-liner (statusline). "" when there is nothing to say — an
+ * ungoverned project's statusline stays silent, never fabricated.
+ */
+export function renderStatusline({ available, walks, arrivals }) {
+  if (!available || walks.length === 0) return "";
+  const w = loudest(walks);
+  const extra = walks.length > 1 ? ` · +${walks.length - 1} walk${walks.length > 2 ? "s" : ""}` : "";
+  const arrived = arrivals.length > 0 ? ` · ▲${arrivals.length} arrived` : "";
+  if (w.you.turn === "you") return `■ YOUR TURN — ${w.name}: ${w.you.act}${extra}${arrived}`;
+  const now =
+    w.currentStage === "build" && w.promises.total > 0
+      ? `keeping promise ${Math.min(w.promises.kept + 1, w.promises.total)}/${w.promises.total}`
+      : stageLabel(w);
+  return `${w.name} ${bar(w.stages)} ${now} · you: nothing${extra}${arrived}`;
+}
+
+/** One walk's full card — the CLI default and the loud stop-card's body. */
+export function renderCard(w) {
+  const line = w.stages
+    .map((s) => `${s.state === "current" ? "▶" : s.state === "done" ? "●" : s.state === "skipped" ? "·" : "○"} ${s.label}${s.state === "skipped" ? ` (${s.note})` : ""}`)
+    .join("  ");
+  const nowLine =
+    w.currentStage === "build" && w.promises.current
+      ? `Now: keeping promise ${Math.min(w.promises.kept + 1, w.promises.total)} of ${w.promises.total} — “${w.promises.current.title || w.promises.current.id}”`
+      : `Now: ${w.you.act ?? w.doneReason}`;
+  const youLine =
+    w.you.turn === "you"
+      ? `■ YOUR TURN: ${w.you.act}`
+      : w.you.turn === "agent"
+        ? `You: nothing needed${w.stops.length ? ` · next stop${w.stops.length > 1 ? "s" : ""} for you: ${w.stops.join(", ")}` : ""}`
+        : "Closed.";
+  return `${w.name} — stage: ${stageLabel(w)}\n${line}\n${nowLine}\n${youLine}`;
+}
+
+/**
+ * The per-prompt context block (UserPromptSubmit --inject): position + the
+ * standing protocol reminders, re-delivered every turn so the narration rules
+ * are decay-proof — re-told, never remembered (D5/D6).
+ */
+export function renderInject({ available, walks, arrivals }) {
+  if (!available || (walks.length === 0 && arrivals.length === 0)) return "";
+  const parts = [];
+  if (walks.length > 0) {
+    parts.push("[walk-status — derived from the ledgers; render this state, never your own memory of it]");
+    for (const w of walks) parts.push(renderCard(w));
+  }
+  for (const a of arrivals)
+    parts.push(`▲ ARRIVED, UNPLANNED — ${a.label} (${a.status}): ${a.reason ?? "no recorded reason"}. Offer: handle now, or after the current walk lands (recommended: after).`);
+  parts.push(
+    "Protocol: speak stages as Decide·Design·Contract·Build·Prove·Sign-off and clauses as promises. Quiet while working (one line per stage transition). At any human gate, render the full stop card (stage, what it is in plain words, exactly what to do, what comes after). Never open a second walk silently.",
+  );
+  return parts.join("\n\n");
+}

package/packages/harness/src/walk-status.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// walk-status.mjs — where every open change stands, whose turn it is, what
+// arrived unplanned. The walk's CLI face (docs/features/walk-status.md D5).
+//
+//   node qa/walk-status.mjs                # full cards, human-readable
+//   node qa/walk-status.mjs --statusline   # the always-on one-liner
+//   node qa/walk-status.mjs --inject       # UserPromptSubmit hook JSON
+//   node qa/walk-status.mjs --json         # the raw derivation
+//
+// FAIL-OPEN BY CONTRACT: this runs inside a statusline and a per-prompt hook.
+// Any failure — broken ledger, non-cmp directory, anything — exits 0 with
+// empty output. A status surface may never block or noise the work it reports
+// on. (The console renders the same derivation with full error honesty; this
+// surface's honesty is silence.)
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+try {
+  const { deriveWalks, renderStatusline, renderCard, renderInject } = await import("./lib/walk.mjs");
+  const data = deriveWalks(ROOT);
+
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+  } else if (args.includes("--statusline")) {
+    const line = renderStatusline(data);
+    if (line !== "") process.stdout.write(`${line}\n`);
+  } else if (args.includes("--inject")) {
+    const ctx = renderInject(data);
+    if (ctx !== "") {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: ctx },
+        }),
+      );
+    }
+  } else {
+    if (!data.available) {
+      process.stdout.write(`walk-status: not derivable — ${data.reason}\n`);
+    } else if (data.walks.length === 0 && data.arrivals.length === 0) {
+      process.stdout.write("No open walks. Every accepted feature's brief is its doc-of-record.\n");
+    } else {
+      for (const w of data.walks) process.stdout.write(`${renderCard(w)}\n\n`);
+      for (const a of data.arrivals)
+        process.stdout.write(`▲ ARRIVED, UNPLANNED — ${a.label} (${a.status}): ${a.reason ?? "no recorded reason"}\n`);
+    }
+  }
+  process.exit(0);
+} catch {
+  process.exit(0); // fail-open: a status surface never blocks the work
+}

package/template/.claude/settings.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"This app is governed by its delivery contract (CLAUDE.md): behavior starts in specs/, done is `node qa/verify.mjs` with a committed receipt, approvals gate signed artifacts. The cmp-inspector MCP tools (preview loop, live tier) are the expected eyes — if they are absent from this session, that is a fault to diagnose (plugin disabled, session predates plugin enablement, or stale plugin copy; see cmp-doctor), not a cue to fall back to screenshots or blind adb.\"}}'"
+            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"This app is governed by its delivery contract (CLAUDE.md): behavior starts in specs/, done is `node qa/verify.mjs` with a committed receipt, approvals gate signed artifacts. The cmp-inspector MCP tools (preview loop, live tier) are the expected eyes \u2014 if they are absent from this session, that is a fault to diagnose (plugin disabled, session predates plugin enablement, or stale plugin copy; see cmp-doctor), not a cue to fall back to screenshots or blind adb.\"}}'"
           }
         ]
       }
@@ -21,11 +21,11 @@
           },
           {
             "type": "command",
-            "command": "grep -qE 'connected[A-Za-z]*AndroidTest|maestro test|adb (-s [^ ]+ )?(install|uninstall)' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: device evidence is lane-owned and batched. node qa/verify.mjs sequences the device steps once, last, under a machine-global per-serial lease (qa/lib/device-lease.mjs) — the one device is scarce, slow, and fragile, so device proof is a checkpoint, never an inner loop. Driving it by hand mid-task risks colliding with a running lane (wedged adbd, device offline, false reds, crossed app state). Ad-hoc debugging stays allowed; batch the evidence into the lane.\"}}' || true"
+            "command": "grep -qE 'connected[A-Za-z]*AndroidTest|maestro test|adb (-s [^ ]+ )?(install|uninstall)' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: device evidence is lane-owned and batched. node qa/verify.mjs sequences the device steps once, last, under a machine-global per-serial lease (qa/lib/device-lease.mjs) \u2014 the one device is scarce, slow, and fragile, so device proof is a checkpoint, never an inner loop. Driving it by hand mid-task risks colliding with a running lane (wedged adbd, device offline, false reds, crossed app state). Ad-hoc debugging stays allowed; batch the evidence into the lane.\"}}' || true"
           },
           {
             "type": "command",
-            "command": "in=$(cat); printf '%s' \"$in\" | grep -qE 'node qa/verify\\.mjs' && ! printf '%s' \"$in\" | grep -q -- '--fast' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: for inner-loop iteration, node qa/verify.mjs --fast skips the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke) and is much quicker. Run the full lane once, deliberately, before reporting work done — never speculatively, and never to re-confirm a result you already have. A --fast receipt never satisfies the done-gate.\"}}' || true"
+            "command": "in=$(cat); printf '%s' \"$in\" | grep -qE 'node qa/verify\\.mjs' && ! printf '%s' \"$in\" | grep -q -- '--fast' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: for inner-loop iteration, node qa/verify.mjs --fast skips the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke) and is much quicker. Run the full lane once, deliberately, before reporting work done \u2014 never speculatively, and never to re-confirm a result you already have. A --fast receipt never satisfies the done-gate.\"}}' || true"
           }
         ]
       }
@@ -34,9 +34,27 @@
       {
         "matcher": "",
         "hooks": [
-          { "type": "command", "command": "node qa/receipt-check.mjs --hook" }
+          {
+            "type": "command",
+            "command": "node qa/receipt-check.mjs --hook"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "test -f qa/walk-status.mjs && node qa/walk-status.mjs --inject || true"
+          }
         ]
       }
     ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "test -f qa/walk-status.mjs && node qa/walk-status.mjs --statusline || true"
   }
 }

package/template/AGENTS.md

@@ -37,6 +37,7 @@ prerequisite.
 <!-- >>> cmp:feature harness -->
 | Adding a feature / screen / repository | `node qa/scaffold-feature.mjs <Name>` — clones the tested exemplar through every layer; never freehand the pattern (skills: `add-feature`, `add-screen`, `add-repository`) |
 | A gate failed and looks arbitrary | `node qa/refusal-demo.mjs` — stages canonical violations so each gate names the clause it protects |
+| Where are we / whose turn is it | `node qa/walk-status.mjs` — every open walk's stage card (Decide·Design·Contract·Build·Prove·Sign-off), whose turn, what arrived unplanned; `--statusline` is the one-liner |
 <!-- <<< cmp:feature harness -->
 | Build broken, toolchain suspect | `npx create-cmp-cli doctor --fix` — diagnoses machine AND project (kotlin↔ksp lockstep, catalog drift); asks before any repair |
 | Dependency versions stale or mismatched | `npx create-cmp-cli upgrade --dry-run` — diff against the next proven-green set before touching anything |

package/template/CLAUDE.md

@@ -304,6 +304,42 @@ stamper clones your pattern in your domain language, and `home` demotes to an or
 feature spec. If the configured exemplar has grown files beyond the canonical 11-file
 shape, the stamper clones the canonical set and warns, listing exactly what it skipped.
 
+
+## The walk — the user always knows where we are and whose turn it is
+
+Every governed change is a **walk** through six stages, spoken ONLY in this vocabulary
+wherever the human reads (chat, cards, commit prose): **Decide · Design · Contract ·
+Build · Prove · Sign-off**. The mapping is mechanical — Decide=the brief, Design=the
+rendered screens, Contract=the spec, Build=code+citing tests, Prove=the lane's receipt,
+Sign-off=acceptance — and spec clauses are spoken as **promises** ("Contract: 7
+promises agreed" · "Build: keeping promise 5 of 7" · "Prove: all promises kept,
+evidence attached"). `node qa/walk-status.mjs` derives the live position; a
+UserPromptSubmit hook injects it every prompt. **Render the injected state — never
+your memory of it.**
+
+**At kickoff** (with the triage restatement): print the itinerary —
+
+    Navigation redesign — the journey (brief lane)
+    Decide → Design → Contract → Build → Prove → Sign-off
+    Stops for you: 3 (Decide — now · Contract · Sign-off). Build and Prove never stop for you.
+    First stop is now: 2 open decisions below.
+
+**While working — quiet:** one line per stage transition, nothing per-file. The
+statusline carries the position continuously; do not repeat it in prose.
+
+**At every human gate — loud:** a full stop card, never a bare question:
+
+    ■ YOUR TURN — <feature> · stage 3 of 6: Contract
+    <what it is, in plain words — two lines maximum>
+    → <exactly what to do: the command, or the studio tab, or "reply approve">
+    After this: <the remaining stages, and which ones stop for the human>
+
+**Arrivals:** work that belongs to no open walk (undeclared drift, a harness
+upgrade's rule-change reopens) is NEVER silently interleaved. Render
+`▲ ARRIVED, UNPLANNED — <what> · now, or after <current walk> lands?` and default to
+after. One walk at a time unless the human chooses otherwise — three unframed
+interleaved walks is precisely the session this rule exists to prevent.
+
 ## Comments — review feedback flows back through the agent
 
 Approvals are binding (they gate the verify lane); **comments are advisory** — a human's

package/template/qa/lib/walk.mjs

@@ -0,0 +1,277 @@
+// walk.mjs — the walk: where every open change stands, whose turn it is, and
+// what arrives unplanned. docs/features/walk-status.md is the brief of record.
+//
+// A PROJECTION, not new state (D1): everything here re-renders the derivation
+// getFeatureBoard already computes (phase, nextStep with owner, clause
+// coverage, provenDone). No new ledger, nothing agent-declared, nothing to
+// forget to update — if a number here could disagree with the board, this
+// module is wrong.
+//
+// Vocabulary (D2/D3): six stages — Decide · Design · Contract · Build ·
+// Prove · Sign-off — and clauses rendered as PROMISES ("keeping promise 5 of
+// 7"). Mechanically exact: a clause is a behavioral promise, a citing green
+// test is that promise kept, provenDone is all of them kept with the receipt
+// attesting this tree.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { getFeatureBoard, getApprovalStatuses, readJournal } from "./approvals.mjs";
+import { CLAUSE_LINE_RE } from "./spec-coverage.mjs";
+
+/** The six stages, in walk order. `label` is the only user-facing name (D2). */
+export const STAGES = [
+  { key: "decide", label: "Decide" },
+  { key: "design", label: "Design" },
+  { key: "contract", label: "Contract" },
+  { key: "build", label: "Build" },
+  { key: "prove", label: "Prove" },
+  { key: "signoff", label: "Sign-off" },
+];
+
+/** nextStep.key -> the stage that step belongs to. `closed` maps to none. */
+const STEP_STAGE = {
+  "sign-brief": "decide",
+  "re-approve": "decide",
+  design: "design",
+  audit: "design",
+  "sign-design": "design",
+  contract: "contract",
+  "sign-spec": "contract",
+  build: "build",
+  // A sanctioned redesign is promises being re-kept — Build, not a seventh stage.
+  redesign: "build",
+  prove: "prove",
+  accept: "signoff",
+};
+
+/**
+ * A promise's human title: the clause line's own words after the id, first
+ * sentence-ish, capped. "" when the line carries nothing after the id — the
+ * card then falls back to the bare id rather than inventing prose.
+ */
+function promiseTitle(rest) {
+  const cleaned = String(rest ?? "")
+    .replace(/^[\s—:-]+/, "")
+    .replace(/\*\*/g, "")
+    .trim();
+  if (cleaned === "") return "";
+  const cut = cleaned.search(/[.;]\s/);
+  const first = cut === -1 ? cleaned : cleaned.slice(0, cut);
+  return first.length > 110 ? `${first.slice(0, 107)}…` : first;
+}
+
+/**
+ * The spec's promises, in file order: id, title, withdrawn. Reads the spec
+ * directly (same CLAUSE_LINE_RE the coverage gate uses) because the board's
+ * clause list carries ids only — the words are the whole point here (D3).
+ * @returns {Array<{id: string, title: string, withdrawn: boolean}>}
+ */
+export function listPromises(root, specRel) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, specRel), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    const m = line.match(CLAUSE_LINE_RE);
+    if (!m) continue;
+    const rest = line.slice(m[0].length).replace(/^~~/, "");
+    out.push({ id: m[2], title: promiseTitle(rest), withdrawn: Boolean(m[1]) });
+  }
+  return out;
+}
+
+/** The human stops remaining from (and including) the current stage. */
+function remainingStops(stages, currentIdx) {
+  const stops = [];
+  for (let i = Math.max(currentIdx, 0); i < stages.length; i++) {
+    const s = stages[i];
+    if (s.state === "done" || s.state === "skipped") continue;
+    if (s.key === "decide") stops.push("Decide");
+    if (s.key === "design") stops.push("Design sign-off");
+    if (s.key === "contract") stops.push("Contract");
+    if (s.key === "signoff") stops.push("Sign-off");
+  }
+  return stops;
+}
+
+/**
+ * One feature's walk. Stage states are POSITIONAL around the derived current
+ * step: the board's deriveNextStep already resolves every competing condition
+ * (drift outranks acceptance, design before contract, redesign splits by
+ * provenDone) to ONE next act — stages before it are done, after it pending.
+ * Design is `skipped` when the feature honestly has no UI surface (D2).
+ */
+function walkOfFeature(root, f) {
+  const currentKey = STEP_STAGE[f.nextStep?.key] ?? null; // null => closed
+  const currentIdx = currentKey ? STAGES.findIndex((s) => s.key === currentKey) : STAGES.length;
+  const stages = STAGES.map((s, i) => {
+    if (s.key === "design" && f.design === null)
+      return { ...s, state: "skipped", note: "no UI surface" };
+    return { ...s, state: i < currentIdx ? "done" : i === currentIdx ? "current" : "pending" };
+  });
+
+  const promises = listPromises(root, f.specRel).filter((p) => !p.withdrawn);
+  // The promise being kept NOW: first live clause without a citing test —
+  // board clause order, titles from the spec's own words.
+  const citedIds = new Set(f.clauses.filter((c) => c.cited).map((c) => c.id));
+  const current = promises.find((p) => !citedIds.has(p.id)) ?? null;
+
+  // Whose turn (D4): from the board's own owner, never re-derived.
+  const owner = f.nextStep?.owner ?? null;
+  const you =
+    owner === null
+      ? { turn: "none", act: null }
+      : owner === "human"
+        ? { turn: "you", act: f.nextStep.label }
+        : owner.includes("human")
+          ? { turn: "agent", act: f.nextStep.label, then: "your signature" }
+          : { turn: "agent", act: f.nextStep.label };
+
+  return {
+    name: f.name,
+    phase: f.phase,
+    open: f.phase !== "accepted",
+    stages,
+    currentStage: currentKey,
+    promises: { total: f.total, kept: f.covered, current },
+    you,
+    stops: remainingStops(stages, currentIdx),
+    doneReason: f.doneReason,
+  };
+}
+
+/**
+ * Everything the status surfaces render (D5): open walks, plus ARRIVALS (D7)
+ * — governed artifacts drifted or reopened that NO open walk accounts for
+ * (the board's undeclared set, widened to reopens, e.g. a harness upgrade's
+ * rule-change wave). Each arrival carries the journal's last reopen reason so
+ * the surface can say WHY it arrived, not only that it did.
+ * @param {string} root
+ * @returns {{available: boolean, reason?: string, walks: object[], arrivals: object[]}}
+ */
+export function deriveWalks(root) {
+  let board, statuses;
+  try {
+    board = getFeatureBoard(root);
+    statuses = getApprovalStatuses(root);
+  } catch (err) {
+    return { available: false, reason: err?.message ?? String(err), walks: [], arrivals: [] };
+  }
+
+  // Open walks, MOST RECENTLY ACTIVE first (journal recency across the walk's
+  // family) — five features parked at Sign-off must not bury the one being
+  // worked on today (seen on the showcase: bfl-catalog, alphabetical, outshouted
+  // the live navigation-ia walk in the statusline).
+  const journalForOrder = readJournal(root);
+  const lastActivity = (name) => {
+    const family = new Set([`feature-brief:${name}`, `feature-design:${name}`, `feature-spec:${name}`]);
+    for (let i = journalForOrder.length - 1; i >= 0; i--) {
+      if (family.has(journalForOrder[i].artifact)) return i;
+    }
+    return -1;
+  };
+  const walks = board.features
+    .map((f) => walkOfFeature(root, f))
+    .filter((w) => w.open)
+    .sort((a, b) => lastActivity(b.name) - lastActivity(a.name));
+
+  // Ids an open walk accounts for: its own family (brief/design/spec) and its
+  // declared touches. A reopened design mid-walk is that walk's Design stage,
+  // never an arrival (brief, edge cases).
+  const owned = new Set();
+  for (const f of board.features) {
+    if (f.phase === "accepted") continue;
+    owned.add(`feature-brief:${f.name}`);
+    owned.add(`feature-design:${f.name}`);
+    owned.add(`feature-spec:${f.name}`);
+    for (const t of f.touches) owned.add(t.id);
+  }
+  const journal = journalForOrder;
+  const lastReopenReason = (id) => {
+    for (let i = journal.length - 1; i >= 0; i--) {
+      if (journal[i].artifact === id && journal[i].verb === "reopen") return journal[i].reason ?? null;
+    }
+    return null;
+  };
+  const arrivals = statuses
+    .filter((s) => (s.status === "changed-since-approval" || s.status === "reopened") && !owned.has(s.id))
+    .map((s) => ({
+      id: s.id,
+      label: s.label ?? s.id,
+      status: s.status,
+      reason: s.status === "reopened" ? lastReopenReason(s.id) : "changed since its signature",
+    }));
+
+  return { available: true, walks, arrivals };
+}
+
+// ── Renderings — one grammar, four slots (D4) ────────────────────────────────
+
+const bar = (stages) =>
+  stages.map((s) => (s.state === "done" ? "●" : s.state === "current" ? "◐" : s.state === "skipped" ? "·" : "○")).join("");
+
+const stageLabel = (w) => STAGES.find((s) => s.key === w.currentStage)?.label ?? "Closed";
+
+/** The walk whose state is loudest: YOUR TURN beats agent-working. */
+function loudest(walks) {
+  return walks.find((w) => w.you.turn === "you") ?? walks[0] ?? null;
+}
+
+/**
+ * The always-on one-liner (statusline). "" when there is nothing to say — an
+ * ungoverned project's statusline stays silent, never fabricated.
+ */
+export function renderStatusline({ available, walks, arrivals }) {
+  if (!available || walks.length === 0) return "";
+  const w = loudest(walks);
+  const extra = walks.length > 1 ? ` · +${walks.length - 1} walk${walks.length > 2 ? "s" : ""}` : "";
+  const arrived = arrivals.length > 0 ? ` · ▲${arrivals.length} arrived` : "";
+  if (w.you.turn === "you") return `■ YOUR TURN — ${w.name}: ${w.you.act}${extra}${arrived}`;
+  const now =
+    w.currentStage === "build" && w.promises.total > 0
+      ? `keeping promise ${Math.min(w.promises.kept + 1, w.promises.total)}/${w.promises.total}`
+      : stageLabel(w);
+  return `${w.name} ${bar(w.stages)} ${now} · you: nothing${extra}${arrived}`;
+}
+
+/** One walk's full card — the CLI default and the loud stop-card's body. */
+export function renderCard(w) {
+  const line = w.stages
+    .map((s) => `${s.state === "current" ? "▶" : s.state === "done" ? "●" : s.state === "skipped" ? "·" : "○"} ${s.label}${s.state === "skipped" ? ` (${s.note})` : ""}`)
+    .join("  ");
+  const nowLine =
+    w.currentStage === "build" && w.promises.current
+      ? `Now: keeping promise ${Math.min(w.promises.kept + 1, w.promises.total)} of ${w.promises.total} — “${w.promises.current.title || w.promises.current.id}”`
+      : `Now: ${w.you.act ?? w.doneReason}`;
+  const youLine =
+    w.you.turn === "you"
+      ? `■ YOUR TURN: ${w.you.act}`
+      : w.you.turn === "agent"
+        ? `You: nothing needed${w.stops.length ? ` · next stop${w.stops.length > 1 ? "s" : ""} for you: ${w.stops.join(", ")}` : ""}`
+        : "Closed.";
+  return `${w.name} — stage: ${stageLabel(w)}\n${line}\n${nowLine}\n${youLine}`;
+}
+
+/**
+ * The per-prompt context block (UserPromptSubmit --inject): position + the
+ * standing protocol reminders, re-delivered every turn so the narration rules
+ * are decay-proof — re-told, never remembered (D5/D6).
+ */
+export function renderInject({ available, walks, arrivals }) {
+  if (!available || (walks.length === 0 && arrivals.length === 0)) return "";
+  const parts = [];
+  if (walks.length > 0) {
+    parts.push("[walk-status — derived from the ledgers; render this state, never your own memory of it]");
+    for (const w of walks) parts.push(renderCard(w));
+  }
+  for (const a of arrivals)
+    parts.push(`▲ ARRIVED, UNPLANNED — ${a.label} (${a.status}): ${a.reason ?? "no recorded reason"}. Offer: handle now, or after the current walk lands (recommended: after).`);
+  parts.push(
+    "Protocol: speak stages as Decide·Design·Contract·Build·Prove·Sign-off and clauses as promises. Quiet while working (one line per stage transition). At any human gate, render the full stop card (stage, what it is in plain words, exactly what to do, what comes after). Never open a second walk silently.",
+  );
+  return parts.join("\n\n");
+}

package/template/qa/walk-status.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// walk-status.mjs — where every open change stands, whose turn it is, what
+// arrived unplanned. The walk's CLI face (docs/features/walk-status.md D5).
+//
+//   node qa/walk-status.mjs                # full cards, human-readable
+//   node qa/walk-status.mjs --statusline   # the always-on one-liner
+//   node qa/walk-status.mjs --inject       # UserPromptSubmit hook JSON
+//   node qa/walk-status.mjs --json         # the raw derivation
+//
+// FAIL-OPEN BY CONTRACT: this runs inside a statusline and a per-prompt hook.
+// Any failure — broken ledger, non-cmp directory, anything — exits 0 with
+// empty output. A status surface may never block or noise the work it reports
+// on. (The console renders the same derivation with full error honesty; this
+// surface's honesty is silence.)
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+try {
+  const { deriveWalks, renderStatusline, renderCard, renderInject } = await import("./lib/walk.mjs");
+  const data = deriveWalks(ROOT);
+
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+  } else if (args.includes("--statusline")) {
+    const line = renderStatusline(data);
+    if (line !== "") process.stdout.write(`${line}\n`);
+  } else if (args.includes("--inject")) {
+    const ctx = renderInject(data);
+    if (ctx !== "") {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: ctx },
+        }),
+      );
+    }
+  } else {
+    if (!data.available) {
+      process.stdout.write(`walk-status: not derivable — ${data.reason}\n`);
+    } else if (data.walks.length === 0 && data.arrivals.length === 0) {
+      process.stdout.write("No open walks. Every accepted feature's brief is its doc-of-record.\n");
+    } else {
+      for (const w of data.walks) process.stdout.write(`${renderCard(w)}\n\n`);
+      for (const a of data.arrivals)
+        process.stdout.write(`▲ ARRIVED, UNPLANNED — ${a.label} (${a.status}): ${a.reason ?? "no recorded reason"}\n`);
+    }
+  }
+  process.exit(0);
+} catch {
+  process.exit(0); // fail-open: a status surface never blocks the work
+}