create-cmp-cli 0.18.0 → 0.20.0

package/packages/receipts/src/index.mjs

@@ -13,4 +13,5 @@ export {
   checkExecutionPlausibility,
   listSkippedSteps,
   validateReceiptForTree,
+  checkLaneVouching,
 } from "./receipt-validate.mjs";

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

@@ -17,8 +17,19 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-// Directories / files INCLUDED in the verified surface (relative to project ROOT).
+// Directories / files included in the verified surface (relative to project ROOT).
 // Principle: every tracked file whose content can change the lane's verdict.
+//
+// THIS IS A DEFAULT, NOT A LAW (evidence-economics S8, 2026-09-03). It is the
+// surface of a Compose Multiplatform app, and it used to be hardcoded inside
+// this module — which is the SPINE, shared by every adopter. A repo whose code
+// lives in services/ or src/ that vendored this file had its verified surface
+// silently shrink to whatever happened to match: no error, no failed step, a
+// receipt that still validated and still looked identical, and a hash that had
+// quietly stopped covering the application. A gate that attests less while
+// looking the same is the worst failure this harness can have, so the surface
+// is now resolved per project (see resolveVerifiedSurface) and an empty one is
+// refused rather than hashed.
 export const VERIFIED_SURFACE = [
   "composeApp",
   "specs",
@@ -57,6 +68,7 @@ export const VERIFIED_SURFACE = [
 const EXCLUDED_PREFIXES = [
   "qa/.plan.json",
   "qa/.request.json",
+  "qa/.plan-history.jsonl",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",
@@ -146,9 +158,52 @@ function walkAllFiles(dir) {
   return out;
 }
 
+/** Where a project may declare its own verified surface (see resolveVerifiedSurface). */
+export const SURFACE_CONFIG_REL = "qa/verified-surface.json";
+
+/**
+ * The surface THIS project attests — its own declaration when it has one, the
+ * Compose Multiplatform default otherwise.
+ *
+ * Read from a file rather than passed as an argument on purpose: qa/verify.mjs
+ * (which writes inputs.hash) and qa/receipt-check.mjs (which recomputes it)
+ * must never disagree about what was hashed, and two call sites taking a
+ * parameter is two places to get it wrong. The file lives under qa/, so it is
+ * itself inside the surface — changing the definition invalidates receipts,
+ * which is correct: the tree's coverage changed.
+ *
+ * Shape: {"surface": ["services", "docs", "build-logic", ".github", "qa"]}.
+ * Malformed or empty content is REFUSED, never silently defaulted — a project
+ * that tried to declare a surface and failed must not fall back to a smaller
+ * one behind the operator's back.
+ *
+ * @param {string} root project root
+ * @returns {string[]} surface entries, relative to root
+ */
+export function resolveVerifiedSurface(root) {
+  const p = path.join(root, SURFACE_CONFIG_REL);
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch {
+    return VERIFIED_SURFACE; // no declaration — the CMP default, unchanged
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${SURFACE_CONFIG_REL} is not valid JSON (${err.message}) — refusing to hash a surface this project failed to declare.`);
+  }
+  const list = parsed && Array.isArray(parsed.surface) ? parsed.surface.filter((x) => typeof x === "string" && x.trim() !== "") : null;
+  if (!list || list.length === 0) {
+    throw new Error(`${SURFACE_CONFIG_REL} declares no surface — expected {"surface": ["dir", …]}. Refusing to hash nothing.`);
+  }
+  return list;
+}
+
 // Resolve the verified surface to a flat, sorted list of paths (relative to
 // root, POSIX-style `/` separators) that currently exist on disk.
-function resolveSurfaceFiles(root) {
+function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
   const gitFiles = tryGitLsFiles(root);
 
   if (gitFiles) {
@@ -188,7 +243,20 @@ export function computeInputsHash(root) {
   // on iteration order, and ICU collation varies with the machine's locale
   // (e.g. a da_DK machine orders "aa" after "z"; en orders case-insensitively
   // where code units do not) — the same tree must hash identically everywhere.
-  const files = [...new Set(resolveSurfaceFiles(root))].sort();
+  const surface = resolveVerifiedSurface(root);
+  const files = [...new Set(resolveSurfaceFiles(root, surface))].sort();
+
+  // A surface that matches NOTHING is a misconfiguration, not a valid hash.
+  // Hashing zero files yields a stable, confident-looking digest that attests
+  // the empty set — the silent shrink this whole change exists to prevent, in
+  // its most extreme form. Refuse, and name what was looked for.
+  if (files.length === 0) {
+    throw new Error(
+      `the verified surface matched no files under ${root} — nothing would be attested. ` +
+        `Surface: ${surface.join(", ")}. ` +
+        `A project whose code lives elsewhere declares its own in ${SURFACE_CONFIG_REL}: {"surface": ["services", "qa", …]}.`,
+    );
+  }
 
   const overall = createHash("sha256");
   for (const relPath of files) {

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

@@ -45,6 +45,51 @@ export function readReceipt(root, relPath = RECEIPT_REL_PATH) {
  *   FAIL verdict), so callers don't pay for a hash they don't need.
  * @returns {{valid: boolean, reason: string, profile: (string|undefined), recomputed?: {hash: string, fileCount: number}}}
  */
+/**
+ * Does this receipt's own row-level evidence support its PASS?
+ *
+ * The receipt is necessarily excluded from the inputs hash it carries — a file
+ * cannot hash itself — so steps[] is the only thing between this gate and a text
+ * editor, and the top-level verdict is the most editable field on it.
+ *
+ * Two failures this catches, both observed downstream (payment-blueprint F2/F3):
+ * a receipt whose verdict was hand-edited from FAIL to PASS while its rows still
+ * said otherwise, and a lane made green by DELETING harness.lock.json, which
+ * downgraded harnessIntegrity from FAIL to SKIP and took the lane's verdict with
+ * it — a lane vouching for a tree with nothing vouching for the lane.
+ *
+ * @param {{verdict?: string, steps?: Array<{name?: string, verdict?: string}>}} receipt
+ * @returns {{ok: boolean, detail: string}}
+ */
+export function checkLaneVouching(receipt) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : null;
+  if (!steps || steps.length === 0) {
+    return { ok: false, detail: "receipt lists no verify-lane steps — a PASS over nothing attests nothing" };
+  }
+  const failed = steps.filter((s) => s && (s.verdict === "FAIL" || s.verdict === "ERROR"));
+  if (failed.length > 0) {
+    const names = failed.map((s) => `${s.name ?? "?"} (${s.verdict})`).join(", ");
+    return {
+      ok: false,
+      detail: `the receipt's verdict is PASS but ${failed.length} step(s) did not pass: ${names} — the row is the more specific truth`,
+    };
+  }
+  const integrity = steps.find((s) => s && s.name === "harnessIntegrity");
+  if (!integrity) {
+    return {
+      ok: false,
+      detail: "receipt has no harnessIntegrity row — nothing vouches that the lane's own code is the code that ran",
+    };
+  }
+  if (integrity.verdict !== "PASS") {
+    return {
+      ok: false,
+      detail: `harnessIntegrity is ${integrity.verdict}, not PASS — the lane did not vouch for itself, so its PASS over the tree cannot be trusted`,
+    };
+  }
+  return { ok: true, detail: "lane vouched for itself (harnessIntegrity PASS, no failing rows)" };
+}
+
 export function evaluateReceipt(receipt, recompute) {
   const profile = receipt.profile;
 
@@ -83,6 +128,13 @@ export function evaluateReceipt(receipt, recompute) {
     };
   }
 
+  // Did the lane vouch for ITSELF? See checkLaneVouching — the top-level verdict
+  // is the most editable field on a file the hash cannot cover.
+  const vouching = checkLaneVouching(receipt);
+  if (!vouching.ok) {
+    return { valid: false, reason: `${vouching.detail} (attesting profile: ${profile ?? "unknown"})`, profile, recomputed };
+  }
+
   return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
 }
 
@@ -134,7 +186,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/template/CLAUDE.md

@@ -4,6 +4,13 @@
 Generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a verification
 harness. Every AI session in this repo works under this contract.
 
+**Principles** (the full form, with the episode behind each, is create-cmp's
+`docs/PRINCIPLES.md`): derived, never claimed · prove the instrument before you read it · the
+layer you changed cannot certify itself · proof costs what the change costs and never runs
+silent · never wait on nothing · a signature binds content, a decision is closed · one record,
+read first. These govern every rule below; when a rule below and a principle disagree, the
+principle wins and the rule is the bug.
+
 ## Definition of done
 
 Done means `node qa/verify.mjs` reports PASS and the receipt it writes
@@ -38,6 +45,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 +104,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 +219,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:
@@ -330,12 +365,21 @@ steps you just printed:
 node qa/plan.mjs --set "sign the brief | draft screens | agree the promises | build | full check | your sign-off" --title "navigation redesign"
 ```
 
+**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. 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.
-The chain gates nothing; the walk stays the truth for doneness.
+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
@@ -481,6 +525,8 @@ 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 smoke` | The smallest end-to-end lane: every pure-Node gate, no Gradle, no device — seconds. Proves the framework *returns*, never the change (its receipt is refused as done-evidence). Run it first in any repo whose harness is new or freshly upgraded |
+| `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/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -119,7 +119,6 @@ class ArchitectureConformanceTest {
         )
     }
 
-    // SPEC: ARCH-04
     // Component-derived tags (component-system-deep-dive.md §6.4) count as tag provenance:
     // a screen built entirely from registry components (ScreenColumn/AppHeader/
     // ContentStateContainer/…) is automation-reachable through the tags THOSE components
@@ -138,6 +137,7 @@ class ArchitectureConformanceTest {
         return text.contains("testTag") || (importsComponents && screenTagArgument.containsMatchIn(text))
     }
 
+    // SPEC: ARCH-04
     @Test
     fun `ARCH-04 every feature composable file is automation-reachable - literal testTag or screenTag provenance`() {
         // Scoped by CONTENT (contains @Composable), not by *Screen.kt filename: real apps

package/template/gitignore

@@ -41,3 +41,6 @@ xcuserdata/
 # 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

@@ -134,7 +134,13 @@ function refuseIfUnresolvable() {
 
 if (args.includes("--accept-defaults")) {
   refuseIfUnresolvable();
-  const { approved, skipped } = approveAllDefaults(ROOT);
+  const expressAsIdx = args.indexOf("--as");
+  const expressSigner = expressAsIdx >= 0 ? args[expressAsIdx + 1] : undefined;
+  if (!expressSigner || expressSigner.startsWith("--")) {
+    console.error('--accept-defaults needs a signer: node qa/approve.mjs --accept-defaults --as "Your Name <you@example.com>"');
+    process.exit(1);
+  }
+  const { approved, skipped } = approveAllDefaults(ROOT, expressSigner);
   for (const id of approved) {
     console.log(`✓ approved ${id} [defaults-accepted]`);
   }
@@ -201,9 +207,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);
 }
 
@@ -239,7 +252,22 @@ if (args.length === 0) {
 refuseIfUnresolvable();
 
 const artifactId = args[0];
-const result = approveArtifact(ROOT, artifactId, { via: "cli" });
+// The signer is REQUIRED, not optional: see approveArtifact's refusal. Parsed
+// here rather than defaulted from git config on purpose — `git config user.name`
+// is whatever the machine says, and an agent running on a developer's laptop
+// would sign with that developer's name. An approval must be typed by whoever
+// is answerable for it.
+const asIndex = args.indexOf("--as");
+const approvedBy = asIndex >= 0 ? args[asIndex + 1] : undefined;
+if (!approvedBy || approvedBy.startsWith("--")) {
+  console.error(
+    'approve needs a signer: node qa/approve.mjs <artifact> --as "Your Name <you@example.com>"\n' +
+      "An approval is a signature on a hash; a row that records no signer cannot tell a human's\n" +
+      "sign-off from an agent's.",
+  );
+  process.exit(1);
+}
+const result = approveArtifact(ROOT, artifactId, { via: "cli", approvedBy });
 if (!result.ok) {
   console.error(`error: ${result.reason}`);
   process.exit(1);

package/template/qa/lib/approvals.mjs

@@ -781,6 +781,7 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
       hash: recomputed.hash,
       storedHash: storedRecord.hash ?? null,
       approvedAt: storedRecord.approvedAt ?? null,
+      approvedBy: storedRecord.approvedBy ?? null,
       fileCount: recomputed.fileCount,
       missing: recomputed.missing,
       resolvable,
@@ -801,6 +802,7 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
       hash: recomputed.hash,
       storedHash: null,
       approvedAt: null,
+      approvedBy: null,
       fileCount: recomputed.fileCount,
       missing: recomputed.missing,
       resolvable,
@@ -834,6 +836,10 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
     hash: recomputed.hash,
     storedHash: storedRecord.hash,
     approvedAt: storedRecord.approvedAt,
+    // WHO signed. Null on rows written before signers were recorded; the gate
+    // treats a signed-by-nobody approval as FAIL, because that row cannot tell
+    // a human's sign-off from an agent's.
+    approvedBy: storedRecord.approvedBy ?? null,
     fileCount: recomputed.fileCount,
     missing: recomputed.missing,
     resolvable,
@@ -920,7 +926,23 @@ export function approveArtifact(root, artifactId, options = {}) {
   const state = loadApprovals(root);
   const others = state.artifacts.filter((a) => a.artifact !== artifactId);
   const approvedAt = new Date().toISOString();
-  const record = { artifact: artifactId, status: "approved", hash: resolved.hash, approvedAt };
+  if (!options.approvedBy || !String(options.approvedBy).trim()) {
+    return {
+      ok: false,
+      reason:
+        `cannot approve "${artifactId}" — no signer was given. An approval is a person's ` +
+        "signature on a hash; a row that records no signer cannot distinguish a human's sign-off " +
+        "from an agent's, and an agent that invalidates an approval can clear it by re-approving. " +
+        "Pass the signer: `node qa/approve.mjs <artifact> --as \"Name <email>\"`.",
+    };
+  }
+  const record = {
+    artifact: artifactId,
+    status: "approved",
+    hash: resolved.hash,
+    approvedAt,
+    approvedBy: String(options.approvedBy).trim(),
+  };
   if (options.mode) record.mode = options.mode;
   if (options.via) record.via = options.via;
   others.push(record);
@@ -929,10 +951,11 @@ export function approveArtifact(root, artifactId, options = {}) {
     verb: "approve",
     artifact: artifactId,
     hash: resolved.hash,
+    approvedBy: String(options.approvedBy).trim(),
     ...(options.via ? { via: options.via } : {}),
     ...(options.mode ? { mode: options.mode } : {}),
   });
-  return { ok: true, artifact: artifactId, hash: resolved.hash, approvedAt, ...(options.mode ? { mode: options.mode } : {}) };
+  return { ok: true, artifact: artifactId, hash: resolved.hash, approvedAt, approvedBy: record.approvedBy, ...(options.mode ? { mode: options.mode } : {}) };
 }
 
 /**
@@ -945,7 +968,7 @@ export function approveArtifact(root, artifactId, options = {}) {
  * @param {string} root
  * @returns {{ok: true, approved: string[], skipped: Array<{id: string, reason: string}>}}
  */
-export function approveAllDefaults(root) {
+export function approveAllDefaults(root, approvedBy) {
   const registry = listGovernedArtifacts(root);
   const state = loadApprovals(root);
   const byId = new Map(state.artifacts.map((a) => [a.artifact, a]));
@@ -954,7 +977,7 @@ export function approveAllDefaults(root) {
   for (const artifact of registry) {
     const live = resolveArtifactStatus(root, artifact, byId.get(artifact.id));
     if (live.status === "approved") continue; // already settled — never overwritten by the express lane
-    const result = approveArtifact(root, artifact.id, { mode: "defaults-accepted" });
+    const result = approveArtifact(root, artifact.id, { mode: "defaults-accepted", approvedBy });
     if (result.ok) approved.push(artifact.id);
     else skipped.push({ id: artifact.id, reason: result.reason });
   }
@@ -1066,13 +1089,33 @@ export function reopenFeature(root, name, options = {}) {
   // 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}`);
-  const set = [briefId, ...specIds, `${FEATURE_DESIGN_PREFIX}${name}`, ...(derived ? derived.touches : [])];
+  // 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;
@@ -1081,15 +1124,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 ─────────────────────────────────────────────────────
@@ -1117,6 +1166,21 @@ export function evaluateApprovalsGate(root) {
   const statuses = getApprovalStatuses(root);
   const mismatched = statuses.filter((s) => s.status === "changed-since-approval");
   const pending = statuses.filter((s) => s.status === "unreviewed" || s.status === "reopened");
+  // An "approved" row with no signer attests nothing about WHO signed, which is
+  // the one fact an approval exists to record. It cannot distinguish a human's
+  // sign-off from an agent's, and an agent that invalidates an approval can
+  // clear it by re-approving — the gate then guards only against accident, not
+  // against the population it is pointed at. Rows written before signers were
+  // recorded land here; the fix is one re-approval each, and the message says so.
+  const unsigned = statuses.filter((s) => s.status === "approved" && !s.approvedBy);
+
+  if (unsigned.length > 0) {
+    const lines = ["Approval recorded without a signer — re-approve to say who signed:"];
+    for (const s of unsigned) {
+      lines.push(`  [${s.id}] ${s.label} — approved ${shortHash(s.storedHash)} by nobody. Re-approve: node qa/approve.mjs ${s.id} --as "Your Name <you@example.com>"`);
+    }
+    return { verdict: "FAIL", reason: lines.join("\n"), statuses };
+  }
 
   if (mismatched.length > 0) {
     const lines = ["Approval invalidated — a governed artifact changed after sign-off:"];

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/flight-recorder.mjs

@@ -93,7 +93,14 @@ export function buildFlightEntry({ profile, mode, verdict, evidenceLevel, steps,
     verdict,
     evidenceRung: evidenceLevel?.rung ?? null,
     durationMs,
-    steps: stepList.map((s) => ({ name: s.name, verdict: s.verdict })),
+    // durationMs per step (additive, schema id unchanged — old entries stay
+    // readable): the source for the lane's own "usually ~Ns" narration
+    // (drive-narration N4). Quoted from the journal, never from memory.
+    steps: stepList.map((s) => ({
+      name: s.name,
+      verdict: s.verdict,
+      ...(typeof s.durationMs === "number" && s.durationMs >= 0 ? { durationMs: s.durationMs } : {}),
+    })),
     // SKIP reasons verbatim — the journal's core signal (see file header).
     skips: stepList.filter((s) => s.verdict === "SKIP").map((s) => ({ step: s.name, reason: s.reason ?? "" })),
     deviceSteps: Array.isArray(onDeviceSteps) ? onDeviceSteps : [],
@@ -198,7 +205,15 @@ export function summarizeFlightJournal(entries, { now = new Date() } = {}) {
       // JSON-array key: reasons are arbitrary text, so a delimiter-joined
       // string key would be ambiguous — and ambiguity here merges two
       // different problems into one count.
-      const key = JSON.stringify([s.step ?? "?", s.reason ?? ""]);
+      //
+      // Grouped on the reason's FIRST LINE, which is exactly what the report
+      // prints. Several gates (approvals above all) end their reason with a
+      // variable list of artifact names, so keying on the whole string split
+      // ONE recurring reason into seven near-identical rows carrying the same
+      // visible text — a count the reader had to add up by eye. The detail is
+      // not lost: the verbatim reasons are still in the journal, which is the
+      // artifact that owes verbatim. The REPORT owes legibility.
+      const key = JSON.stringify([s.step ?? "?", (s.reason ?? "").split("\n")[0]]);
       skipGroups.set(key, (skipGroups.get(key) ?? 0) + 1);
     }
   }
@@ -258,6 +273,36 @@ export function summarizeFlightJournal(entries, { now = new Date() } = {}) {
   };
 }
 
+/**
+ * Steps that SKIPped in THIS run and have skipped in EVERY recorded full run —
+ * a tier that has never executed on this machine.
+ *
+ * A single SKIP is a fact; skipping every recorded run is a different fact,
+ * and only the journal can tell them apart. maestro was never installed on one
+ * machine, so e2eSmoke skipped on all 37 recorded runs while the lane said
+ * PASS each time — the end-to-end flow had never run once, and nothing said so.
+ *
+ * Needs a journal long enough to mean something: below `floor` recorded runs
+ * carrying the step, "every time" is a coincidence, not a pattern.
+ *
+ * @param {Array<{name: string, verdict: string, reason?: string}>} steps this run's results
+ * @param {object[]} entries parsed journal entries (any mode; fast runs are ignored)
+ * @param {{floor?: number}} [opts]
+ * @returns {Array<{name: string, runs: number, reason: string}>}
+ */
+export function neverRunTiers(steps, entries, { floor = 3 } = {}) {
+  const full = (Array.isArray(entries) ? entries : []).filter((e) => e && e.mode !== "fast" && Array.isArray(e.steps));
+  const out = [];
+  for (const st of (Array.isArray(steps) ? steps : []).filter((x) => x && x.verdict === "SKIP")) {
+    const seen = full.filter((e) => e.steps.some((s) => s && s.name === st.name));
+    // "Ran" means produced a verdict about the tree: PASS or FAIL. An ERROR
+    // tried and could not; it is not evidence that the tier works here.
+    const ran = seen.filter((e) => e.steps.some((s) => s && s.name === st.name && (s.verdict === "PASS" || s.verdict === "FAIL")));
+    if (seen.length >= floor && ran.length === 0) out.push({ name: st.name, runs: seen.length, reason: st.reason ?? "" });
+  }
+  return out;
+}
+
 /**
  * Render the summary as the plain-text report a human reads in ten seconds.
  * Every line is a recorded fact; the honesty notes (short journal, single