create-cmp-cli 0.16.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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/src/commands/doctor.mjs

@@ -7,11 +7,13 @@
 //                     [--target-dir <dir>] [--fix]
 //
 // --fix applies only SAFE heals (write local.properties from ANDROID_HOME, add
-// ksp.useKSP2=true); everything else prints the exact manual step.
+// ksp.useKSP2=true, wire the walk into .claude/settings.json); everything else
+// prints the exact manual step.
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { flagBool } from "../lib/args.mjs";
 import { colors, ok } from "../lib/log.mjs";
@@ -71,6 +73,65 @@ function freeDiskBytes() {
   }
 }
 
+/** This engine checkout root — the template it ships is the wiring of record. */
+const ENGINE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * The walk wiring the CURRENT engine template declares: the statusLine object
+ * and the UserPromptSubmit hook groups that invoke qa/walk-status.mjs. Read from
+ * template/.claude/settings.json rather than duplicated here, so the heal cannot
+ * drift from what a fresh scaffold gets.
+ * @returns {{statusLine: object|null, promptSubmit: Array|null}}
+ */
+export function templateWalkWiring() {
+  const raw = readIfExists(path.join(ENGINE_ROOT, "template", ".claude", "settings.json"));
+  if (raw === null) return { statusLine: null, promptSubmit: null };
+  try {
+    const t = JSON.parse(raw);
+    const statusLine = invokesWalk(t.statusLine) ? t.statusLine : null;
+    const groups = (t.hooks?.UserPromptSubmit ?? []).filter((g) =>
+      (g?.hooks ?? []).some(invokesWalk)
+    );
+    return { statusLine, promptSubmit: groups.length > 0 ? groups : null };
+  } catch {
+    return { statusLine: null, promptSubmit: null };
+  }
+}
+
+/** Does this settings entry ({type, command}) actually run the walk? */
+function invokesWalk(entry) {
+  return String(entry?.command ?? "").includes("walk-status.mjs");
+}
+
+/**
+ * Is the walk installed, and does .claude/settings.json invoke it? The machinery
+ * and the wiring live in separately-owned files (lane vs app config), so they can
+ * and do come apart — see the walk-wiring finding in project-doctor.mjs.
+ */
+export function gatherWalkInputs(projectDir) {
+  const scriptPresent = fs.existsSync(path.join(projectDir, "qa", "walk-status.mjs"));
+  if (!scriptPresent) return null; // not a walk-carrying lane — nothing to say
+  const raw = readIfExists(path.join(projectDir, ".claude", "settings.json"));
+  if (raw === null) {
+    return { scriptPresent, settingsPresent: false, statusLine: false, promptHook: false };
+  }
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    // Unparseable settings invoke nothing, which is exactly what we report.
+    return { scriptPresent, settingsPresent: true, statusLine: false, promptHook: false };
+  }
+  return {
+    scriptPresent,
+    settingsPresent: true,
+    statusLine: invokesWalk(settings.statusLine),
+    promptHook: (settings.hooks?.UserPromptSubmit ?? []).some((g) =>
+      (g?.hooks ?? []).some(invokesWalk)
+    ),
+  };
+}
+
 /** Gather filesystem/env inputs for the pure diagnosis. */
 export function gatherProjectInputs(projectDir) {
   const toml = readIfExists(path.join(projectDir, "gradle", "libs.versions.toml"));
@@ -112,6 +173,7 @@ export function gatherProjectInputs(projectDir) {
     freeDiskBytes: freeDiskBytes(),
     inspectorHits,
     inspectorCatalog,
+    walk: gatherWalkInputs(projectDir),
   };
 }
 
@@ -146,7 +208,7 @@ function scanInspectorSources(projectDir) {
 }
 
 /** Apply the SAFE auto-heals for --fix. Returns ids of findings it fixed. */
-function applySafeFixes(projectDir, findings, inputs) {
+export function applySafeFixes(projectDir, findings, inputs) {
   const fixed = [];
   for (const f of findings) {
     if (!f.fix || !f.fix.auto || f.level === "ok") continue;
@@ -164,6 +226,43 @@ function applySafeFixes(projectDir, findings, inputs) {
       }
     }
 
+    if (f.id === "walk-wiring") {
+      const { statusLine, promptSubmit } = templateWalkWiring();
+      const target = path.join(projectDir, ".claude", "settings.json");
+      const raw = readIfExists(target);
+      let settings = {};
+      if (raw !== null) {
+        try {
+          settings = JSON.parse(raw);
+        } catch {
+          // Never overwrite settings we could not read — that is the app's file.
+          continue;
+        }
+      }
+      let changed = false;
+      if (statusLine && !invokesWalk(settings.statusLine)) {
+        // Only claim an unclaimed slot: an app that set its OWN status line keeps it.
+        if (!settings.statusLine) {
+          settings.statusLine = statusLine;
+          changed = true;
+        }
+      }
+      if (promptSubmit) {
+        settings.hooks = settings.hooks ?? {};
+        const existing = settings.hooks.UserPromptSubmit ?? [];
+        if (!existing.some((g) => (g?.hooks ?? []).some(invokesWalk))) {
+          settings.hooks.UserPromptSubmit = [...existing, ...promptSubmit];
+          changed = true;
+        }
+      }
+      if (changed) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, `${JSON.stringify(settings, null, 2)}\n`);
+        ok("--fix: wired the walk into .claude/settings.json (statusLine + UserPromptSubmit)");
+        fixed.push(f.id);
+      }
+    }
+
     if (f.id === "ksp2-flag") {
       const target = path.join(projectDir, "gradle.properties");
       const existing = inputs.gradleProperties ?? "";

package/src/lib/hooks.mjs

@@ -42,7 +42,10 @@ export function isEnforcementEvent(event) {
   return ENFORCEMENT_EVENTS.has(event);
 }
 
-/** Does this hook's command presuppose the verify lane (`qa/`)? */
+/**
+ * Does this entry's command presuppose the verify lane (`qa/`)? Takes anything
+ * settings.json can hold a command in — a hook, or the top-level `statusLine`.
+ */
 export function referencesLane(hook) {
   return String(hook?.command ?? "").includes("qa/");
 }
@@ -118,12 +121,20 @@ export function sessionStartCommand(context) {
 
 /**
  * The minimal-mode hook set, DERIVED from the full one rather than kept as a
- * second file to hold in sync (light is a filter, not a fork). Three edits:
+ * second file to hold in sync (light is a filter, not a fork). Four edits:
  *
  *   (a) enforcement goes — the Stop hook is Act 3;
  *   (b) lane-advisory goes — a nudge naming qa/ presupposes the lane;
  *   (c) SessionStart says what is true HERE — `sessionContext` describes what
- *       this scaffold carries and the one command that adds the rest.
+ *       this scaffold carries and the one command that adds the rest;
+ *   (d) a lane-referencing `statusLine` goes. It is not a hook, so the
+ *       classifier above never saw it, and the first cut of the walk shipped a
+ *       minimal scaffold a status line reading `qa/walk-status.mjs` — a file
+ *       minimal deletes. The command is guarded (`test -f … || true`) so it
+ *       printed nothing rather than erroring, which is exactly what made it
+ *       survive review: dead config that fails silently. The lane-reference
+ *       rule is the same one that drops lane-advisory hooks; it just has to be
+ *       applied to every surface that carries a command, not only to `hooks`.
  *
  * @param {object} settings parsed .claude/settings.json content
  * @param {object} opts
@@ -131,7 +142,9 @@ export function sessionStartCommand(context) {
  */
 export function minimalHookSettings(settings, { sessionContext }) {
   const out = filterHooks(settings, (event, hook) => classifyHook(event, hook) !== "advisory");
-  if (!out || typeof out.hooks !== "object" || out.hooks === null) return out;
+  if (!out || typeof out !== "object") return out;
+  if (referencesLane(out.statusLine)) delete out.statusLine;
+  if (typeof out.hooks !== "object" || out.hooks === null) return out;
   for (const group of out.hooks.SessionStart ?? []) {
     if (!Array.isArray(group?.hooks)) continue;
     for (const hook of group.hooks) hook.command = sessionStartCommand(sessionContext);

package/src/lib/project-doctor.mjs

@@ -36,6 +36,10 @@ export const DISK_WARN_BYTES = 3 * GIB;
  * @param {string[]|null} [input.inspectorHits] relative (posix) paths of Kotlin sources that
  *        reference the live-inspector endpoint (`/inspect/` or `InspectorHttpServer`);
  *        null = scan skipped (no composeApp sources), [] = project has no inspector code.
+ * @param {{scriptPresent:boolean, settingsPresent:boolean, statusLine:boolean,
+ *          promptHook:boolean}|null} [input.walk] the walk's wiring: is
+ *        qa/walk-status.mjs installed, and does .claude/settings.json actually
+ *        INVOKE it (statusLine + UserPromptSubmit)? null = skip the check.
  * @param {{catalog:string, theme:string}|null} [input.inspectorCatalog] the stamped
  *        InspectorCatalog.kt content + concatenated theme sources (Tokens.kt/Theme.kt) for
  *        the declared-token drift tripwire; null = skip.
@@ -55,6 +59,7 @@ export function diagnoseProject(input) {
     freeDiskBytes,
     inspectorHits = null,
     inspectorCatalog = null,
+    walk = null,
   } = input;
 
   // --- version catalog ------------------------------------------------------
@@ -313,6 +318,49 @@ export function diagnoseProject(input) {
     }
   }
 
+  // --- the walk: installed but unwired ----------------------------------------
+  // qa/walk-status.mjs is inert on its own. What renders it is .claude/settings.json:
+  // a statusLine (the ambient "where are we") and a UserPromptSubmit hook (the
+  // per-turn position injected into the agent). Both are APP-OWNED config, so an app
+  // that hand-edited settings.json can take the machinery on upgrade and lose the
+  // wiring — and the failure mode is silence, which is precisely the problem the walk
+  // exists to fix. Nothing else in the system can notice, so doctor does.
+  if (walk !== null && walk.scriptPresent) {
+    const missing = [
+      !walk.statusLine ? "no statusLine" : null,
+      !walk.promptHook ? "no UserPromptSubmit hook" : null,
+    ].filter(Boolean);
+    if (missing.length === 0) {
+      findings.push({
+        id: "walk-wiring",
+        level: "ok",
+        title: "The walk is wired",
+        detail:
+          "qa/walk-status.mjs is installed and .claude/settings.json invokes it from both the " +
+          "status line and UserPromptSubmit.",
+      });
+    } else {
+      findings.push({
+        id: "walk-wiring",
+        level: "warn",
+        title: "The walk is installed but not wired up",
+        detail:
+          "qa/walk-status.mjs is present, but " +
+          (walk.settingsPresent
+            ? `.claude/settings.json does not invoke it (${missing.join(", ")}).`
+            : "there is no .claude/settings.json to invoke it from.") +
+          " Nothing will show which stage a feature is at, or tell the agent where it is — " +
+          "the walk runs nowhere. Running node qa/walk-status.mjs by hand still works.",
+        fix: {
+          auto: true,
+          description:
+            "Add the statusLine and UserPromptSubmit entries to .claude/settings.json " +
+            "(copied from the engine template; existing hooks are left untouched).",
+        },
+      });
+    }
+  }
+
   return findings;
 }
 

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
+}