create-cmp-cli 0.17.1 → 0.19.0

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

@@ -19,8 +19,41 @@ import { fileURLToPath } from "node:url";
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const args = process.argv.slice(2);
 
+/**
+ * The hook's stdin, parsed — UserPromptSubmit delivers {prompt, ...} as JSON.
+ * Bounded read, fail-soft: no stdin / non-JSON / no prompt -> null. Only the
+ * --inject path consumes this (the statusline gets no stdin and must not wait
+ * on one).
+ */
+async function readHookStdin() {
+  if (process.stdin.isTTY) return null;
+  try {
+    let raw = "";
+    for await (const chunk of process.stdin) {
+      raw += chunk;
+      if (raw.length > 1_000_000) break; // a prompt is never this — stop reading, keep what we have
+    }
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 try {
   const { deriveWalks, renderStatusline, renderCard, renderInject } = await import("./lib/walk.mjs");
+
+  // Tier 1 of the chain (studio-drive-mode): record the human's own prompt
+  // BEFORE deriving, so this very inject already reflects the new request.
+  // Machinery-owned — the words are the hook's, never the agent's.
+  if (args.includes("--inject")) {
+    const hook = await readHookStdin();
+    if (hook && typeof hook.prompt === "string") {
+      const { recordRequest } = await import("./lib/plan.mjs");
+      recordRequest(ROOT, hook.prompt);
+    }
+  }
+
   const data = deriveWalks(ROOT);
 
   if (args.includes("--json")) {
@@ -43,7 +76,10 @@ try {
     } 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`);
+      const { renderChain } = await import("./lib/plan.mjs");
+      const chainText = renderChain(data.chain);
+      if (chainText !== "") process.stdout.write(`${chainText}\n\n`);
+      for (const w of data.walks) process.stdout.write(`${renderCard(w, data)}\n\n`);
       for (const a of data.arrivals)
         process.stdout.write(`▲ ARRIVED, UNPLANNED — ${a.label} (${a.status}): ${a.reason ?? "no recorded reason"}\n`);
     }

package/packages/receipts/src/inputs-hash.mjs

@@ -48,7 +48,16 @@ export const VERIFIED_SURFACE = [
 // bookkeeping about a commit that already happened, so appending a record
 // must never invalidate a receipt for a tree whose code did not change
 // (approvals.log.jsonl's principle, applied to audits).
+// qa/.request.json and qa/.plan.json are the live chain's EPHEMERAL state
+// (studio-drive-mode): the request file is rewritten on EVERY user prompt by
+// the UserPromptSubmit hook, so hashing either would invalidate the receipt
+// the moment the human speaks. They are also gitignored on fresh scaffolds,
+// but the exclusion here is the load-bearing one — upgraded apps keep their
+// own .gitignore, which never learns new entries.
 const EXCLUDED_PREFIXES = [
+  "qa/.plan.json",
+  "qa/.request.json",
+  "qa/.plan-history.jsonl",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",

package/packages/receipts/src/receipt-validate.mjs

@@ -134,7 +134,10 @@ export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_PO
   if (!steps || steps.length === 0) {
     return { ok: false, detail: "receipt lists no verify-lane steps — nothing was executed" };
   }
-  const executed = steps.filter((s) => s && s.verdict !== "SKIP");
+  // Executed = produced a verdict about the tree. SKIP did not try; ERROR
+  // tried and could not (a deadline, zero tests, a throw) — neither measured
+  // anything, so neither counts toward "this lane verified something".
+  const executed = steps.filter((s) => s && s.verdict !== "SKIP" && s.verdict !== "ERROR");
   if (executed.length === 0) {
     return { ok: false, detail: "every step in the receipt is a SKIP — the lane verified nothing" };
   }

package/src/commands/doctor.mjs

@@ -10,6 +10,7 @@
 // ksp.useKSP2=true, wire the walk into .claude/settings.json); everything else
 // prints the exact manual step.
 
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -132,6 +133,30 @@ export function gatherWalkInputs(projectDir) {
   };
 }
 
+/**
+ * The studio console's registry record for this app, when one exists — a
+ * CROSS-PACKAGE CONTRACT with the inspector's preview-service.mjs
+ * (consoleRegistryPath) and the harness's walk.mjs (consoleState):
+ * sha1(resolved projectDir).slice(0,12) keys `cmp-console-<key>.json` in
+ * os.tmpdir(), fields {pid, url}. pid-liveness only — no HTTP.
+ */
+export function gatherConsoleInputs(projectDir) {
+  try {
+    const key = crypto.createHash("sha1").update(path.resolve(projectDir)).digest("hex").slice(0, 12);
+    const rec = JSON.parse(fs.readFileSync(path.join(os.tmpdir(), `cmp-console-${key}.json`), "utf8"));
+    if (!rec || typeof rec.pid !== "number") return null;
+    let pidAlive = true;
+    try {
+      process.kill(rec.pid, 0);
+    } catch (err) {
+      pidAlive = Boolean(err && err.code === "EPERM");
+    }
+    return { pidAlive, url: typeof rec.url === "string" ? rec.url : null };
+  } catch {
+    return null; // no record — never started, or stopped cleanly
+  }
+}
+
 /** Gather filesystem/env inputs for the pure diagnosis. */
 export function gatherProjectInputs(projectDir) {
   const toml = readIfExists(path.join(projectDir, "gradle", "libs.versions.toml"));
@@ -174,6 +199,7 @@ export function gatherProjectInputs(projectDir) {
     inspectorHits,
     inspectorCatalog,
     walk: gatherWalkInputs(projectDir),
+    consoleRecord: gatherConsoleInputs(projectDir),
   };
 }
 

package/src/lib/project-doctor.mjs

@@ -40,6 +40,10 @@ export const DISK_WARN_BYTES = 3 * GIB;
  *          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 {{pidAlive:boolean, url:(string|null)}|null} [input.consoleRecord] the studio
+ *        console's tmp-dir registry record for this app, when one exists: is its
+ *        process still alive, and at what URL? null = no record (never started, or
+ *        stopped cleanly — nothing to say).
  * @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.
@@ -60,6 +64,7 @@ export function diagnoseProject(input) {
     inspectorHits = null,
     inspectorCatalog = null,
     walk = null,
+    consoleRecord = null,
   } = input;
 
   // --- version catalog ------------------------------------------------------
@@ -361,6 +366,38 @@ export function diagnoseProject(input) {
     }
   }
 
+  // The studio console's liveness (walk-legibility L6c). A registry record with
+  // a dead pid means the console CRASHED — a clean stop removes the record — and
+  // the human's window silently disappeared. The statusline appends "console
+  // down" live; doctor is the once-over that says the same thing with the fix.
+  if (consoleRecord !== null) {
+    if (consoleRecord.pidAlive) {
+      findings.push({
+        id: "console-liveness",
+        level: "ok",
+        title: "The studio console is running",
+        detail: `A console is registered for this app${consoleRecord.url ? ` at ${consoleRecord.url}` : ""} and its process is alive.`,
+      });
+    } else {
+      findings.push({
+        id: "console-liveness",
+        level: "warn",
+        title: "The studio console crashed",
+        detail:
+          "A console registry record exists for this app but its process is gone — the " +
+          "window died without a clean stop, and every surface that leads with the console " +
+          "is now pointing at nothing.",
+        fix: {
+          auto: false,
+          description:
+            "Reconnect the cmp-inspector MCP (it ensures a resident console at session " +
+            "start), call the preview tool, or start one by hand: " +
+            "node inspector/mcp/bin/console.mjs <projectDir> (detached: nohup … &).",
+        },
+      });
+    }
+  }
+
   return findings;
 }
 

package/template/CLAUDE.md

@@ -38,6 +38,13 @@ it; CI still enforces it).
 New behavior begins as a spec clause in `specs/<feature>.spec.md`: Given/When/Then with a
 stable id (see [`specs/README.md`](./specs/README.md)). Propose the clause, get it confirmed,
 then implement. Durable tests cite their clause (`// SPEC: HOME-02`).
+
+**A clause about device behavior must say so.** A citation proves a test *exists*; it cannot
+prove that test could ever *observe* the promise. Add `[tier: device]` (or `[tier: e2e]`)
+after the id when the claim is about OS facts a host JVM cannot see — lifecycle, alarms,
+notifications, permissions, real navigation. `specCoverage` then requires a citation from
+`androidInstrumentedTest` or `qa/e2e` and FAILS without one, rather than accepting a
+desktop test that is structurally blind to the claim.
 [`specs/app-base.spec.md`](./specs/app-base.spec.md) states the architecture and shell
 invariants the conformance gates enforce.
 
@@ -90,8 +97,15 @@ the tree. The governed `architecture` artifact (below) hashes the document along
   if the test itself is wrong, say so in your summary and justify the change.
 
 **Platform behavior tests live in `composeApp/src/androidInstrumentedTest`** — when a
-feature touches alarms, notifications, lock-screen intents, or audio routing, its behavior
-test goes there, because no desktop tier can see those OS facts. Assertion helpers:
+feature touches alarms, notifications, lock-screen intents, audio routing, **or app/process
+lifecycle** (cold start vs warm resume, "once per process start", process death and
+restore, `ON_STOP`/`ON_START`), its behavior test goes there, because no desktop tier can
+see those OS facts. A desktop Compose test has no process lifecycle *at all*, so a claim
+about one is unobservable there by construction — and `ProcessControl` below is the organ
+that puts the device into the state such a claim is about. **Declare it on the clause**:
+`- **MOTION-13** [tier: device] — Given a cold start, …`. The lane's `specCoverage` then
+FAILS unless a test from a tier that can actually see it cites the clause, instead of
+accepting a citation from a tier that cannot. Assertion helpers:
 `NotificationAsserts`, `AlarmAsserts`, `SystemState`. **Runtime state control** — put the
 device into the state your claim is about, instead of waiting for it: `TimeWarp` (clock,
 timezone), `DozeControl` (forced idle), `PermissionControl`, `ProcessControl`,
@@ -198,6 +212,20 @@ understood the change to be, which lane it takes, and why, before any tool runs.
 can overrule the lane in a word; a silent route is a routing error even when the lane was
 right.
 
+**Grill before the brief** (the `grill-me` plugin skill; the rule holds without the plugin):
+on the brief lane, after the triage restatement and before a word of the brief is drafted,
+settle the load-bearing questions. Read what the repo already answers first — a signed brief
+or spec is a CLOSED decision: cite it, never re-ask it. Then ask the frontier of unsettled
+decisions as a numbered list, at most five per round, each with why it matters and a
+recommended answer — and WAIT for the answers before anything else. Stop when no remaining
+question would change the work; three rounds is the ceiling (more means the request needs
+splitting). Answers land in the brief — settled calls become **Decisions** with their why,
+the human's own calls the **Open decisions** section; the brief's signature closes them. The
+direct lane is not grilled (one inline question at most, only when the restatement cannot
+be made unambiguous); a bug fix or an emergency fix, never. While the grill is open, the
+chain's first step reads `settle the open questions` (declare it before the first round;
+re-declare when the answers reshape the steps).
+
 **Brief lane** — when the change carries **decisions a future contributor could plausibly
 "simplify" away** ("the day boundary is configurable, default 04:00 — not midnight") OR
 **blast radius into other governed artifacts**. After naming the lane:
@@ -317,21 +345,56 @@ 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 —
+**At kickoff** (with the triage restatement): print the itinerary — and DECLARE it as
+the live chain, so the studio's Drive strip and the statusline's readers see the same
+steps you just printed:
 
     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:
+```bash
+node qa/plan.mjs --set "sign the brief | draft screens | agree the promises | build | full check | your sign-off" --title "navigation redesign"
+```
 
-    ■ YOUR TURN — <feature> · stage 3 of 6: Contract
+**The chain is an offer, not an announcement** (drive-narration N6): show the declared
+steps in your first reply and invite the reshape in one breath — "say the word and I'll
+reorder" — then start work immediately; the chain gates nothing, so the offer never
+blocks. If the human redirects, re-declare (`--set` again) without ceremony: their
+reshape IS the new chain.
+
+**The chain stays current** — this is part of the contract, not a nicety: advance it
+with `node qa/plan.mjs --step N` as each step lands and `--done` when the request
+lands (closing writes the request's line into the local trail the studio's Recent
+requests fold shows). The current request itself is recorded mechanically (the
+per-prompt hook), the steps are yours to declare, and every surface shows the
+declaration's age — a stale chain reads as stale to the human watching the studio,
+which is worse than no chain. While the full check runs, the chain's observed line
+narrates the lane's own position (step, elapsed, usual cost) — quote THAT, never an
+estimate. The chain gates nothing; the walk stays the truth for doneness.
+
+**The studio is a standing check:** every injected context opens with a `[studio: …]`
+line. If it says DOWN or not running, restore it before proceeding — call the
+cmp-inspector `preview { projectDir }` tool (it starts a detached resident console
+that survives the session) — or, if the tools are absent, tell the human once. A
+missing window is a fault to heal, never something to work silently past.
+
+**While working — the header, then quiet:** open EVERY reply with the walk's one-line
+header — the exact `[chat header]` line the per-prompt inject delivers. Paste it
+verbatim, never compose it: it is the derivation's own string, so it cannot drift, and
+it persists in the transcript, which the statusline beneath the input box never does.
+After the header: one line per stage transition, nothing per-file. Stages carry their
+plain-words gloss on first mention ("Contract — agreeing what it promises"); quote the
+lane's cost only from the measured figure in the injected card, never an estimate.
+
+**At every human gate — loud:** a full stop card, never a bare question — and the
+easiest act leads:
+
+    ■ YOUR TURN — <feature> · stage 3 of 6: Contract — agreeing what it promises
     <what it is, in plain words — two lines maximum>
-    → <exactly what to do: the command, or the studio tab, or "reply approve">
+    → Easiest: the studio console at <url from the injected card> — the row carries the button.
+    → CLI fallback: <the command>   (or "reply approve" when no console is up)
     After this: <the remaining stages, and which ones stop for the human>
 
 **Arrivals:** work that belongs to no open walk (undeclared drift, a harness
@@ -455,6 +518,7 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | `./gradlew :composeApp:assembleRelease` | Android release build — R8 + `lintVital`, the variant the lane's `releaseBuild` step proves. Produces an **unsigned** APK; signing needs a keystore, which is yours to create and keep out of the repo. |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |
 | `./gradlew :composeApp:connectedDebugAndroidTest` | Instrumented behavior tests on the attached device (the lane's `androidChecks` step) |
+| `node qa/verify.mjs --profile nightly` | Scheduled stage: everything `ci` proves with the determinism probe forced on. Proves the harness, never a change — its receipt (`stage: "nightly"`) is refused as done-evidence, exactly like `--fast`. Schedule it; never wait on it |
 | `node qa/verify.mjs --profile release` | Ship-time lane: everything `ci` proves plus the audit-cadence report (`auditCadence` — which androidMain subsystems changed since their last recorded `cmp-audit`; a nudge, never a gate) and the release-APK Maestro smoke (`releaseSmoke`) |
 | `node qa/verify.mjs --determinism` | Timezone determinism probe, alone: runs the JVM test tier twice under UTC-12 and UTC+14 and FAILs naming any test whose outcome differs — the dynamic net behind ARCH-13's static one. Opt-in inside a lane via `--profile ci --determinism`; never with `--fast`; writes no receipt on its own |
 | `node qa/record-audit.mjs <subsystem>` | Record that a `cmp-audit` of an androidMain subsystem happened (appends subsystem + HEAD sha + timestamp to `qa/audits.jsonl`; refuses dirty/unknown targets). `--list` shows every derived subsystem and its audit status |

package/template/gitignore

@@ -34,3 +34,13 @@ xcuserdata/
 # ignored by git. Delete them once you have reviewed the upgrade's diff.
 *.bak-upgrade
 *.cmp-new
+
+# The live chain's ephemeral state (studio-drive-mode): the current request
+# (rewritten by the UserPromptSubmit hook on every prompt) and the agent's
+# declared step plan. Per-session windshield, not project history — and also
+# hard-excluded from the receipt's hashed input surface (qa/lib/inputs-hash.mjs).
+qa/.request.json
+qa/.plan.json
+# The closed-chain trail (drive-narration N5): local because it carries raw
+# human prompts — the committed journal for lane runs stays qa/flight-recorder.jsonl.
+qa/.plan-history.jsonl

package/template/qa/approve.mjs

@@ -201,9 +201,16 @@ if (reopenFeatureFlagIdx !== -1) {
     console.error(`error: ${result.reason}`);
     process.exit(1);
   }
+  const inScope = result.reopened.length + result.skipped.length + (result.stillSigned ?? []).length;
   console.log(`↺ reopened feature "${result.feature}" as one change — reason: ${reason.trim()}`);
+  console.log(`  ${inScope} in scope · ${result.reopened.length} reopened · ${(result.stillSigned ?? []).length} still signed`);
   for (const id of result.reopened) console.log(`  ↺ ${id}`);
   for (const s of result.skipped) console.log(`  → skipped ${s.id} (${s.status})`);
+  // The declared blast radius is reported, not walked back: a signature is
+  // demanded again only if the change actually moves the bytes it covers.
+  for (const t of result.stillSigned ?? []) {
+    console.log(`  ✓ ${t.id} still signed (${t.status}${t.hash ? ` @${t.hash}` : ""}) — re-signature demanded only if it changes; the hash enforces that`);
+  }
   process.exit(0);
 }
 

package/template/qa/lib/approvals.mjs

@@ -1063,13 +1063,36 @@ export function reopenFeature(root, name, options = {}) {
     return { ok: false, reason: `unknown feature "${name}" — known briefs: ${briefs.join(", ") || "(none)"}` };
   }
   const derived = deriveAllFeatures(root).find((d) => d.name === name);
-  const set = [briefId, `feature-spec:${name}`, `${FEATURE_DESIGN_PREFIX}${name}`, ...(derived ? derived.touches : [])];
+  // The spec side of the family follows the brief's own pairing (a multi-spec
+  // brief reopens every spec its promises live in), defaulting to the name.
+  const specIds = (derived?.specNames ?? [name]).map((n) => `feature-spec:${n}`);
+  // WHAT A FEATURE REOPEN WALKS BACK (evidence-economics S5, aligning this
+  // function with CHANGE-FLOW-DESIGN.md §"touches": "hashes enforce,
+  // declaration lets the console tell as-planned from undeclared blast").
+  //
+  //   reopened     the brief, its declared spec(s), and its design when the
+  //                brief declares a UI surface — the documents the change
+  //                will AMEND. Their signatures are walked back on purpose.
+  //   stillSigned  the declared `touches`. Before this, every one of them was
+  //                reopened too, and every one came back byte-identical:
+  //                twelve signatures for zero changes (design-system
+  //                d8fbdce8 → d8fbdce8). An `approved` artifact is, by
+  //                definition, one whose bytes still match what was signed —
+  //                so reopening it re-asks a question the hash has already
+  //                answered. Worse than wasted: it trains the signer to
+  //                approve without reading, the exact habit approvals exist
+  //                to prevent. They stay signed. If the change DOES move one,
+  //                its hash flips it to `changed` and demands a fresh
+  //                signature — the enforcement the doc always assigned to the
+  //                hash, not to this verb.
+  const amendSet = [briefId, ...specIds, ...(derived?.screens ? [`${FEATURE_DESIGN_PREFIX}${name}`] : [])];
+  const touchSet = (derived ? derived.touches : []).filter((id) => !amendSet.includes(id));
   const byId = new Map(getApprovalStatuses(root).map((s) => [s.id, s]));
   const reopened = [];
   const skipped = [];
-  for (const id of [...new Set(set)]) {
+  for (const id of [...new Set(amendSet)]) {
     const live = byId.get(id);
-    if (!live) continue; // declared touch that resolves to no governed artifact — nothing to reopen
+    if (!live) continue; // resolves to no governed artifact — nothing to reopen
     if (live.status !== "approved") {
       skipped.push({ id, status: live.status });
       continue;
@@ -1078,15 +1101,21 @@ export function reopenFeature(root, name, options = {}) {
     if (result.ok) reopened.push(id);
     else skipped.push({ id, status: `refused: ${result.reason}` });
   }
+  const stillSigned = [];
+  for (const id of [...new Set(touchSet)]) {
+    const live = byId.get(id);
+    if (!live) continue;
+    stillSigned.push({ id, status: live.status, hash: typeof live.hash === "string" ? live.hash.slice(0, 8) : null });
+  }
   if (reopened.length === 0) {
     return {
       ok: false,
       reason:
-        `nothing in "${name}"'s set is currently approved — there is no signature to walk back. ` +
-        `Set: ${[...new Set(set)].join(", ")}; states: ${skipped.map((s) => `${s.id}=${s.status}`).join(", ") || "(unresolved)"}`,
+        `nothing in "${name}"'s amend set is currently approved — there is no signature to walk back. ` +
+        `Set: ${[...new Set(amendSet)].join(", ")}; states: ${skipped.map((s) => `${s.id}=${s.status}`).join(", ") || "(unresolved)"}`,
     };
   }
-  return { ok: true, feature: name, reopened, skipped };
+  return { ok: true, feature: name, reopened, skipped, stillSigned };
 }
 
 // ── The verify-lane gate ─────────────────────────────────────────────────────
@@ -1274,7 +1303,12 @@ export function getFeatureBoard(root) {
   // feature-spec:* that is still signed must be reopened and amended, and the
   // step says so by name — that is what the human's signature set in motion.
   const deriveNextStep = (d, phase) => {
-    const specArtifact = byId.get(`feature-spec:${d.name}`);
+    // The brief's PAIRED specs (feature-brief.mjs pairedSpecNames — the one
+    // pairing function): a multi-spec brief waits on ALL of them being
+    // signed, and its contract step names each one still waiting.
+    const specArtifacts = (d.specNames ?? [d.name])
+      .map((n) => byId.get(`feature-spec:${n}`))
+      .filter(Boolean);
     const designArtifact = byId.get(`${FEATURE_DESIGN_PREFIX}${d.name}`) ?? null;
     const declaredSpecAmendments = d.touches
       .filter((id) => id.startsWith("feature-spec:") && byId.get(id)?.status === "approved")
@@ -1343,8 +1377,9 @@ export function getFeatureBoard(root) {
     // phase === "approved": building — which part of the loop is open?
     if (!d.specExists || d.total === 0)
       return { key: "contract", owner: "agent drafts → human signs", label: `contract: write the clauses in ${d.specRel}${amendNote}` };
-    if (specArtifact && specArtifact.status !== "approved")
-      return { key: "sign-spec", owner: "human", label: `sign the contract (feature-spec:${d.name})${amendNote}` };
+    const unsignedSpecs = specArtifacts.filter((a) => a.status !== "approved");
+    if (unsignedSpecs.length > 0)
+      return { key: "sign-spec", owner: "human", label: `sign the contract (${unsignedSpecs.map((a) => a.id).join(", ")})${amendNote}` };
     if (d.covered < d.total)
       return { key: "build", owner: "agent", label: `build & cite: ${d.total - d.covered} clause(s) have no citing test yet` };
     return { key: "prove", owner: "agent", label: "prove: run node qa/verify.mjs so the receipt attests this tree" };

package/template/qa/lib/evidence-level.mjs

@@ -84,7 +84,9 @@ const RUNG_NAMES = { L0: "scaffold", L1: "desktop", L2: "device", L3: "release"
 export function evidenceLevel(stepResults, profile, { mode } = {}) { // eslint-disable-line no-unused-vars
   if (mode === "fast") return null; // the inner loop derives no rung — ever
   const steps = Array.isArray(stepResults) ? stepResults.filter((s) => s && typeof s.name === "string") : [];
-  if (steps.some((s) => s.verdict === "FAIL")) return null; // a failed lane has no rung
+  // A failed lane has no rung — and a lane with a step that could not run
+  // (ERROR) has none either: a rung is evidence, and "could not check" is not.
+  if (steps.some((s) => s.verdict === "FAIL" || s.verdict === "ERROR")) return null;
   const passed = new Set(steps.filter((s) => s.verdict === "PASS").map((s) => s.name));
 
   if (!L0_REQUIRED.every((name) => passed.has(name))) return null; // not even a stamp-time green build

package/template/qa/lib/feature-brief.mjs

@@ -7,8 +7,9 @@
 // docs/features/ is a governed `feature-brief:<name>` artifact, hashed and
 // signed like anything else, approved BEFORE the feature is built. (Harness
 // design standards stay in docs/proposals/ — different directory, different
-// meaning.) `<name>` matches the feature's spec: docs/features/meal.md pairs
-// with specs/meal.spec.md.
+// meaning.) `<name>` pairs with the feature's spec — by default
+// specs/<name>.spec.md, overridable by the brief itself when its promises
+// genuinely live in several spec files (see pairedSpecNames).
 //
 // The brief carries at most ONE machine-read block, and it declares — it never
 // gates:
@@ -163,30 +164,90 @@ export function briefSections(markdown) {
 
 /**
  * A brief's declarations: blast radius (`touches`), UI surface (`screens`),
- * and the reachability exemption (`unrouted` — FI-7's escape hatch: a screen
- * intentionally not wired into the navigation graph yet). A missing block, or
- * one without a field, declares nothing — legal and common. A block that IS
- * present but malformed is surfaced as `error`: a doc that tried to declare
- * and failed should say so, not read as "declares nothing".
+ * the reachability exemption (`unrouted` — FI-7's escape hatch: a screen
+ * intentionally not wired into the navigation graph yet), and the paired
+ * spec files (`specs` — walk-legibility L1: spec NAMES, no path/extension;
+ * `"specs": ["catalog", "entry-editing"]`). A missing block, or one without a
+ * field, declares nothing — legal and common. A block that IS present but
+ * malformed is surfaced as `error`: a doc that tried to declare and failed
+ * should say so, not read as "declares nothing".
  * @param {string} markdown
- * @returns {{touches: string[], screens: boolean, unrouted: boolean, error: (string|null)}}
+ * @returns {{touches: string[], screens: boolean, unrouted: boolean, specs: string[], error: (string|null)}}
  */
 export function parseFeatureBlock(markdown) {
   const m = typeof markdown === "string" ? markdown.match(FEATURE_FENCE_RE) : null;
-  if (!m) return { touches: [], screens: false, unrouted: false, error: null };
+  if (!m) return { touches: [], screens: false, unrouted: false, specs: [], error: null };
   let parsed;
   try {
     parsed = JSON.parse(m[1]);
   } catch (err) {
-    return { touches: [], screens: false, unrouted: false, error: `cmp:feature block is not valid JSON — ${err.message}` };
+    return { touches: [], screens: false, unrouted: false, specs: [], error: `cmp:feature block is not valid JSON — ${err.message}` };
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return { touches: [], screens: false, unrouted: false, error: "cmp:feature must be a JSON object" };
+    return { touches: [], screens: false, unrouted: false, specs: [], error: "cmp:feature must be a JSON object" };
   }
   const touches = Array.isArray(parsed.touches)
     ? parsed.touches.filter((t) => typeof t === "string" && t.trim() !== "")
     : [];
-  return { touches, screens: parsed.screens === true, unrouted: parsed.unrouted === true, error: null };
+  // `specs` entries are normalized to bare names ("specs/catalog.spec.md" and
+  // "catalog" both mean specs/catalog.spec.md) — declaring in either form is
+  // fine; storing one form keeps every consumer's arithmetic identical.
+  const specs = Array.isArray(parsed.specs)
+    ? [
+        ...new Set(
+          parsed.specs
+            .filter((s) => typeof s === "string" && s.trim() !== "")
+            .map((s) => s.trim().replace(/^specs\//, "").replace(/\.spec\.md$/, "")),
+        ),
+      ]
+    : [];
+  return { touches, screens: parsed.screens === true, unrouted: parsed.unrouted === true, specs, error: null };
+}
+
+/**
+ * The spec files a brief's promises live in — THE pairing function
+ * (walk-legibility L1). One definition, consumed by the board derivation, the
+ * walk, and (through them) the console, so no surface can pair differently.
+ * Precedence:
+ *   1. the cmp:feature block's `"specs": [...]` — the explicit declaration
+ *   2. the brief's `**Spec:**` paragraph — every `specs/<name>.spec.md`
+ *      reference in it (the form briefs already carry for human readers)
+ *   3. the filename default: `specs/<name>.spec.md`
+ * Before this existed, a brief whose blast radius genuinely spans two specs
+ * (catalog-and-editing, showcase 2026-08-26) derived as "still awaiting a
+ * contract" forever — a standing false instruction on the primary surface
+ * that invites an agent to write a second definition of signed behavior.
+ * @param {string} markdown the brief's full text
+ * @param {string} name the brief's name (docs/features/<name>.md)
+ * @param {{specs?: string[]}} [block] a parseFeatureBlock result, if the
+ *   caller already has one (avoids re-parsing; same answer either way)
+ * @returns {string[]} spec names, e.g. ["catalog", "entry-editing"]
+ */
+export function pairedSpecNames(markdown, name, block) {
+  const declared = (block ?? parseFeatureBlock(markdown)).specs ?? [];
+  if (declared.length > 0) return declared;
+  const fromHeader = specHeaderNames(markdown);
+  if (fromHeader.length > 0) return fromHeader;
+  return [name];
+}
+
+/**
+ * Every `specs/<name>.spec.md` referenced in the brief's `**Spec:**`
+ * paragraph — the line starting `**Spec:**` through the next blank line, so
+ * later prose that merely MENTIONS a spec path never redirects the pairing.
+ */
+function specHeaderNames(markdown) {
+  if (typeof markdown !== "string") return [];
+  const lines = markdown.split("\n");
+  const start = lines.findIndex((l) => /^\*\*Spec:?\*\*/.test(l.trim()));
+  if (start === -1) return [];
+  const para = [];
+  for (let i = start; i < lines.length && lines[i].trim() !== ""; i++) para.push(lines[i]);
+  const out = [];
+  for (const m of para.join("\n").matchAll(/specs\/([A-Za-z0-9_-]+)\.spec\.md/g)) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
 }
 
 /**
@@ -262,12 +323,21 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
   } catch {
     readable = false;
   }
-  const block = readable ? parseFeatureBlock(markdown) : { touches: [], screens: false, error: `${brief.rel} could not be read` };
+  const block = readable
+    ? parseFeatureBlock(markdown)
+    : { touches: [], screens: false, specs: [], error: `${brief.rel} could not be read` };
 
-  const specRel = `specs/${brief.name}.spec.md`;
-  const specExists = fs.existsSync(path.join(root, specRel));
+  // The paired specs (walk-legibility L1): usually one, by filename; a brief
+  // may name several. Clauses concatenate in declaration order — "done" means
+  // every live clause across ALL of them is cited.
+  const specNames = pairedSpecNames(markdown, brief.name, block);
+  const specRels = specNames.map((n) => `specs/${n}.spec.md`);
+  const specExists = specRels.every((rel) => fs.existsSync(path.join(root, rel)));
+  const specRel = specRels.join(" + ");
   const citedIds = new Set((pre.citations ?? scanCitations(root)).map((t) => t.id));
-  const clauses = clausesOfSpec(root, specRel).map((c) => ({ ...c, cited: citedIds.has(c.id) }));
+  const clauses = specRels
+    .flatMap((rel) => clausesOfSpec(root, rel))
+    .map((c) => ({ ...c, cited: citedIds.has(c.id) }));
   const live = clauses.filter((c) => !c.withdrawn);
   const covered = live.filter((c) => c.cited).length;
 
@@ -286,6 +356,8 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
     // rung's only mechanical signal (see countEdgeCases).
     edgeCases: readable ? countEdgeCases(markdown) : 0,
     specRel,
+    specNames,
+    specRels,
     specExists,
     clauses,
     covered,