create-cmp-cli 0.19.0 → 0.20.0

package/package.json

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

package/packages/harness/src/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]`);
   }
@@ -246,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/packages/harness/src/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 });
   }
@@ -1143,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/packages/harness/src/lib/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",
@@ -147,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) {
@@ -189,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/harness/src/lib/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 };
 }
 

package/packages/harness/src/lib/spec-coverage.mjs

@@ -30,6 +30,78 @@ export const TIERS_SATISFYING = Object.freeze({
 });
 
 const TAG_LINE_RE = /^(?:\/\/|#)\s*SPEC:/;
+
+// A citation is a claim that a TEST covers a clause, so it has to sit on one.
+// Counting the tag wherever it appears makes a red specCoverage curable with a
+// comment and zero assertions — the one escape this gate exists to close. It is
+// not hypothetical: payment-blueprint hit a citation that had drifted onto a
+// class declaration, where it counted for the whole file while testing nothing.
+//
+// So a tag counts only when a test declaration follows it within
+// BINDING_WINDOW non-blank lines. The window is small enough that the tag must
+// be attached to the test, and loose enough for the @DisplayName / annotation
+// stack that idiomatically sits between them.
+export const BINDING_WINDOW = 5;
+
+// Kotlin @Test, a backticked test function, and the node:test / Maestro-adjacent
+// `test(` / `it(` call forms. Deliberately syntactic: a citation's binding must
+// be readable without compiling anything.
+const TEST_DECL_RE = /@Test\b|\bfun\s+`[^`]+`\s*\(|\b(?:test|it)\s*\(/;
+
+// A tag whose first meaningful line declares a TYPE is documenting that type,
+// not claiming a test — and it must be refused structurally rather than by
+// distance, because a short class body puts a real @Test inside the window and
+// would otherwise launder the citation. This is exactly payment-blueprint's
+// drift: `// SPEC: PP-07` sat on `class PaymentWorkerTest`, three properties
+// above a genuine @Test, and vouched for the whole file.
+const TYPE_DECL_RE = /^(?:@\w+\s+)*(?:public\s+|internal\s+|private\s+|abstract\s+|open\s+|sealed\s+|data\s+|enum\s+)*(?:class|object|interface)\b/;
+
+// A YAML flow's own shape counts as its test: a Maestro file IS the test, so a
+// tag in one binds to the flow rather than to a declaration inside it.
+const FLOW_EXTS = [".yaml", ".yml"];
+
+/**
+ * Does a test declaration follow `index` within BINDING_WINDOW non-blank lines,
+ * skipping block-comment bodies (a tag inside one is documentation, not a claim)?
+ * @param {string[]} lines
+ * @param {number} index line the tag sits on
+ * @returns {boolean}
+ */
+export function citationIsBound(lines, index) {
+  let seen = 0;
+  let inBlockComment = false;
+  for (let i = index + 1; i < lines.length && seen < BINDING_WINDOW; i += 1) {
+    const line = lines[i].trim();
+    if (line === "") continue;
+    if (inBlockComment) {
+      if (line.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) inBlockComment = true;
+      continue;
+    }
+    if (line.startsWith("//") || line.startsWith("*")) continue;
+    seen += 1;
+    // The FIRST meaningful line decides whether this tag is on a test at all.
+    if (seen === 1 && TYPE_DECL_RE.test(line)) return false;
+    if (TEST_DECL_RE.test(line)) return true;
+  }
+  return false;
+}
+
+/** Is this tag inside a block comment that began earlier in the file? */
+function insideBlockComment(lines, index) {
+  let open = false;
+  for (let i = 0; i < index; i += 1) {
+    const line = lines[i];
+    for (let c = 0; c < line.length - 1; c += 1) {
+      if (!open && line[c] === "/" && line[c + 1] === "*") open = true;
+      else if (open && line[c] === "*" && line[c + 1] === "/") open = false;
+    }
+  }
+  return open;
+}
 const TAG_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
 const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
 
@@ -105,11 +177,14 @@ export function scanCitations(root) {
     const tier = tierForFile(rel);
     fs.readFileSync(f, "utf8")
       .split("\n")
-      .forEach((line, i) => {
+      .forEach((line, i, lines) => {
         const trimmed = line.trim();
         if (!TAG_LINE_RE.test(trimmed)) return;
         const m = trimmed.match(TAG_IDS_RE);
         if (!m) return;
+        // A flow file IS its test; anything else must have a test under the tag.
+        const isFlow = FLOW_EXTS.some((ext) => rel.endsWith(ext));
+        if (!isFlow && (insideBlockComment(lines, i) || !citationIsBound(lines, i))) return;
         const ids = m[1]
           .split(/[,\s]+/)
           .map((s) => s.trim())

package/packages/harness/src/lib/steps-cmp.mjs

@@ -1177,6 +1177,15 @@ const stepsForProfile = {
   // scaffold: what `create-cmp --verify` proves at stamp time — specCoverage,
   // the full JVM tier (unit + conformance + golden + UI tests) plus the Android build.
   scaffold: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory, stepBuild, stepUnitTests],
+  // smoke (docs/GATE-RULES.md Rule 0, docs/PRINCIPLES.md #2): the smallest
+  // end-to-end lane — every pure-Node step through the REAL runner, marker,
+  // receipt and journal, and NO Gradle, no device, no network. Its job is to
+  // prove the framework RETURNS, fast, in both directions, before any real
+  // work is pointed at it. scripts/framework-check.mjs drives it: PASS on a
+  // fresh scaffold, then FAIL BY NAME on one planted spec edit, each bounded
+  // in seconds. Its receipt is refused as done-evidence (qa/receipt-check.mjs)
+  // exactly like --fast: it proves the instrument, never the change.
+  smoke: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory],
   local: [
     // First, always: every verdict below is only worth what the lane issuing
     // it is worth.

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

@@ -512,7 +512,7 @@ export function renderInject(data) {
   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: open every reply with the chat header line above, verbatim. Speak stages as Decide·Design·Contract·Build·Prove·Sign-off — with their plain-words gloss on first mention — and clauses as promises. Declare the chain at kickoff and advance it as you go; if the studio line above says DOWN or not running, restore it (preview tool) or surface it before proceeding. Quiet between headers (one line per stage transition). At any human gate, render the full stop card: stage, what it is in plain words, then the easiest act first (the studio console when it is up; the CLI as fallback), then what comes after. Quote the lane's cost only from the measured figure in the card — never estimate it. Never open a second walk silently.",
+    "Protocol: open every reply with the chat header line above, verbatim. Speak stages as Decide·Design·Contract·Build·Prove·Sign-off — with their plain-words gloss on first mention — and clauses as promises. Declare the chain at kickoff and advance it as you go; if the studio line above says DOWN or not running, restore it (preview tool) or surface it before proceeding. Quiet between headers (one line per stage transition). At any human gate, render the full stop card: stage, what it is in plain words, then the easiest act first (the studio console when it is up; the CLI as fallback), then what comes after. Quote the lane's cost only from the measured figure in the card — never estimate it. Never open a second walk silently. Principles that bind THIS turn (docs/PRINCIPLES.md): derived, never claimed — name the command behind any claim; the layer you changed cannot certify itself — run its consumers, stamp a fresh app for a template or harness change; never wait on nothing — every wait is bounded, and if you are blocked, say on what and stop.",
   );
   return parts.join("\n\n");
 }

package/packages/harness/src/receipt-check.mjs

@@ -99,7 +99,30 @@ function evaluate() {
       profile: receipt.profile,
     };
   }
-  const result = evaluateReceipt(receipt, () => computeInputsHash(ROOT));
+  // smoke (GATE-RULES Rule 0) runs no Gradle: it proves the framework returns,
+  // never that the change is good. Refused like --fast, for the same reason.
+  if (receipt.stage === "smoke" || receipt.profile === "smoke") {
+    return {
+      valid: false,
+      reason: "the last verify run was the smoke profile (the framework check — no build, no tests; it proves the instrument, not this change); run the change-stage lane (`node qa/verify.mjs`) before finishing",
+      profile: receipt.profile,
+    };
+  }
+  // A surface this project cannot resolve is a REFUSAL with an explanation,
+  // never an unhandled stack trace: this runs as the Stop hook on every turn
+  // end, and a crash there reads as a broken harness rather than as the
+  // misconfiguration it is. (evidence-economics S8 follow-up: computeInputsHash
+  // now throws rather than returning a confident hash of the empty set.)
+  let result;
+  try {
+    result = evaluateReceipt(receipt, () => computeInputsHash(ROOT));
+  } catch (err) {
+    return {
+      valid: false,
+      reason: `cannot verify this receipt — ${err && err.message ? err.message : String(err)}`,
+      profile: receipt.profile,
+    };
+  }
   // Surface the receipt's evidence rung (the ladder — qa/lib/evidence-level.mjs)
   // alongside the verdict: the rung is the receipt's own derived field, read
   // verbatim, never recomputed here. Older receipts without it stay valid.

package/packages/harness/src/verify.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // The verify lane — this project's single verification gate.
 //
-//   node qa/verify.mjs [--profile scaffold|local|ci|nightly|release] [--fast] [--json]
+//   node qa/verify.mjs [--profile smoke|scaffold|local|ci|nightly|release] [--fast] [--json]
 //
 // Runs every verification step this project carries, aggregates a typed
 // PASS/FAIL verdict, and writes the evidence receipt to qa/evidence/latest.json.
@@ -51,7 +51,7 @@ const ARTIFACTS_DIR = path.join(ROOT, "qa-artifacts");
 // killed). Same refusal-over-fabrication stance as qa/approve.mjs, which
 // refuses an unknown artifact by name rather than guessing: an unknown
 // argument here is refused by name, not swallowed into "run everything".
-const USAGE = `node qa/verify.mjs [--profile scaffold|local|ci|nightly|release] [--fast] [--json] [--help]
+const USAGE = `node qa/verify.mjs [--profile smoke|scaffold|local|ci|nightly|release] [--fast] [--json] [--help]
 
 The verify lane — this project's single verification gate. Runs every
 verification step this project carries, aggregates a typed PASS/FAIL
@@ -59,7 +59,7 @@ verdict, and writes the evidence receipt to qa/evidence/latest.json (commit
 it with your change — see CLAUDE.md). Exit code: 0 = PASS, 1 = FAIL.
 
 Flags:
-  --profile <scaffold|local|ci|nightly|release>
+  --profile <smoke|scaffold|local|ci|nightly|release>
                                  which step set to run (default: local)
   --fast                         INNER LOOP ONLY — run the resolved profile
                                   minus the device/release tier (releaseBuild,
@@ -101,6 +101,10 @@ Flags:
                                   running anything
 
 Profiles:
+  smoke     the smallest end-to-end lane: every pure-Node gate through the real
+            runner, receipt and journal — no Gradle, no device. Seconds. Proves the
+            FRAMEWORK returns, both ways; never the change (its receipt is refused
+            as done-evidence). Driven by scripts/framework-check.mjs.
   scaffold  spec coverage + build + unit tests (what \`create-cmp --verify\`
             proves at stamp time)
   local     everything; device-dependent steps SKIP when no device is
@@ -321,7 +325,7 @@ const { stepsForProfile, DEVICE_STEPS, FAST_EXCLUDED_NAMES, STEP_FN_BY_NAME } =
 
 
 if (!stepsForProfile[profile]) {
-  console.error(`Unknown profile "${profile}" — use scaffold | local | ci | nightly | release.`);
+  console.error(`Unknown profile "${profile}" — use smoke | scaffold | local | ci | nightly | release.`);
   process.exit(2);
 }
 
@@ -499,7 +503,7 @@ const inputs = computeInputsHash(ROOT);
 // more than its stage allows. scaffold → scaffold, local → change (per commit),
 // ci → merge, nightly → nightly (proves the harness, never a change), release →
 // release. Receipts predating this field are read as their profile's stage.
-const STAGE_OF_PROFILE = { scaffold: "scaffold", local: "change", ci: "merge", nightly: "nightly", release: "release" };
+const STAGE_OF_PROFILE = { smoke: "smoke", scaffold: "scaffold", local: "change", ci: "merge", nightly: "nightly", release: "release" };
 const receipt = {
   schema: "cmp-evidence/1",
   profile,

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",
@@ -147,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) {
@@ -189,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 };
 }
 

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
@@ -518,6 +525,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 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 |

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/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]`);
   }
@@ -246,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 });
   }
@@ -1143,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/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",
@@ -147,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) {
@@ -189,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/template/qa/lib/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 };
 }
 

package/template/qa/lib/spec-coverage.mjs

@@ -30,6 +30,78 @@ export const TIERS_SATISFYING = Object.freeze({
 });
 
 const TAG_LINE_RE = /^(?:\/\/|#)\s*SPEC:/;
+
+// A citation is a claim that a TEST covers a clause, so it has to sit on one.
+// Counting the tag wherever it appears makes a red specCoverage curable with a
+// comment and zero assertions — the one escape this gate exists to close. It is
+// not hypothetical: payment-blueprint hit a citation that had drifted onto a
+// class declaration, where it counted for the whole file while testing nothing.
+//
+// So a tag counts only when a test declaration follows it within
+// BINDING_WINDOW non-blank lines. The window is small enough that the tag must
+// be attached to the test, and loose enough for the @DisplayName / annotation
+// stack that idiomatically sits between them.
+export const BINDING_WINDOW = 5;
+
+// Kotlin @Test, a backticked test function, and the node:test / Maestro-adjacent
+// `test(` / `it(` call forms. Deliberately syntactic: a citation's binding must
+// be readable without compiling anything.
+const TEST_DECL_RE = /@Test\b|\bfun\s+`[^`]+`\s*\(|\b(?:test|it)\s*\(/;
+
+// A tag whose first meaningful line declares a TYPE is documenting that type,
+// not claiming a test — and it must be refused structurally rather than by
+// distance, because a short class body puts a real @Test inside the window and
+// would otherwise launder the citation. This is exactly payment-blueprint's
+// drift: `// SPEC: PP-07` sat on `class PaymentWorkerTest`, three properties
+// above a genuine @Test, and vouched for the whole file.
+const TYPE_DECL_RE = /^(?:@\w+\s+)*(?:public\s+|internal\s+|private\s+|abstract\s+|open\s+|sealed\s+|data\s+|enum\s+)*(?:class|object|interface)\b/;
+
+// A YAML flow's own shape counts as its test: a Maestro file IS the test, so a
+// tag in one binds to the flow rather than to a declaration inside it.
+const FLOW_EXTS = [".yaml", ".yml"];
+
+/**
+ * Does a test declaration follow `index` within BINDING_WINDOW non-blank lines,
+ * skipping block-comment bodies (a tag inside one is documentation, not a claim)?
+ * @param {string[]} lines
+ * @param {number} index line the tag sits on
+ * @returns {boolean}
+ */
+export function citationIsBound(lines, index) {
+  let seen = 0;
+  let inBlockComment = false;
+  for (let i = index + 1; i < lines.length && seen < BINDING_WINDOW; i += 1) {
+    const line = lines[i].trim();
+    if (line === "") continue;
+    if (inBlockComment) {
+      if (line.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) inBlockComment = true;
+      continue;
+    }
+    if (line.startsWith("//") || line.startsWith("*")) continue;
+    seen += 1;
+    // The FIRST meaningful line decides whether this tag is on a test at all.
+    if (seen === 1 && TYPE_DECL_RE.test(line)) return false;
+    if (TEST_DECL_RE.test(line)) return true;
+  }
+  return false;
+}
+
+/** Is this tag inside a block comment that began earlier in the file? */
+function insideBlockComment(lines, index) {
+  let open = false;
+  for (let i = 0; i < index; i += 1) {
+    const line = lines[i];
+    for (let c = 0; c < line.length - 1; c += 1) {
+      if (!open && line[c] === "/" && line[c + 1] === "*") open = true;
+      else if (open && line[c] === "*" && line[c + 1] === "/") open = false;
+    }
+  }
+  return open;
+}
 const TAG_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
 const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
 
@@ -105,11 +177,14 @@ export function scanCitations(root) {
     const tier = tierForFile(rel);
     fs.readFileSync(f, "utf8")
       .split("\n")
-      .forEach((line, i) => {
+      .forEach((line, i, lines) => {
         const trimmed = line.trim();
         if (!TAG_LINE_RE.test(trimmed)) return;
         const m = trimmed.match(TAG_IDS_RE);
         if (!m) return;
+        // A flow file IS its test; anything else must have a test under the tag.
+        const isFlow = FLOW_EXTS.some((ext) => rel.endsWith(ext));
+        if (!isFlow && (insideBlockComment(lines, i) || !citationIsBound(lines, i))) return;
         const ids = m[1]
           .split(/[,\s]+/)
           .map((s) => s.trim())

package/template/qa/lib/steps-cmp.mjs

@@ -1177,6 +1177,15 @@ const stepsForProfile = {
   // scaffold: what `create-cmp --verify` proves at stamp time — specCoverage,
   // the full JVM tier (unit + conformance + golden + UI tests) plus the Android build.
   scaffold: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory, stepBuild, stepUnitTests],
+  // smoke (docs/GATE-RULES.md Rule 0, docs/PRINCIPLES.md #2): the smallest
+  // end-to-end lane — every pure-Node step through the REAL runner, marker,
+  // receipt and journal, and NO Gradle, no device, no network. Its job is to
+  // prove the framework RETURNS, fast, in both directions, before any real
+  // work is pointed at it. scripts/framework-check.mjs drives it: PASS on a
+  // fresh scaffold, then FAIL BY NAME on one planted spec edit, each bounded
+  // in seconds. Its receipt is refused as done-evidence (qa/receipt-check.mjs)
+  // exactly like --fast: it proves the instrument, never the change.
+  smoke: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory],
   local: [
     // First, always: every verdict below is only worth what the lane issuing
     // it is worth.

package/template/qa/lib/walk.mjs

@@ -512,7 +512,7 @@ export function renderInject(data) {
   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: open every reply with the chat header line above, verbatim. Speak stages as Decide·Design·Contract·Build·Prove·Sign-off — with their plain-words gloss on first mention — and clauses as promises. Declare the chain at kickoff and advance it as you go; if the studio line above says DOWN or not running, restore it (preview tool) or surface it before proceeding. Quiet between headers (one line per stage transition). At any human gate, render the full stop card: stage, what it is in plain words, then the easiest act first (the studio console when it is up; the CLI as fallback), then what comes after. Quote the lane's cost only from the measured figure in the card — never estimate it. Never open a second walk silently.",
+    "Protocol: open every reply with the chat header line above, verbatim. Speak stages as Decide·Design·Contract·Build·Prove·Sign-off — with their plain-words gloss on first mention — and clauses as promises. Declare the chain at kickoff and advance it as you go; if the studio line above says DOWN or not running, restore it (preview tool) or surface it before proceeding. Quiet between headers (one line per stage transition). At any human gate, render the full stop card: stage, what it is in plain words, then the easiest act first (the studio console when it is up; the CLI as fallback), then what comes after. Quote the lane's cost only from the measured figure in the card — never estimate it. Never open a second walk silently. Principles that bind THIS turn (docs/PRINCIPLES.md): derived, never claimed — name the command behind any claim; the layer you changed cannot certify itself — run its consumers, stamp a fresh app for a template or harness change; never wait on nothing — every wait is bounded, and if you are blocked, say on what and stop.",
   );
   return parts.join("\n\n");
 }

package/template/qa/receipt-check.mjs

@@ -99,7 +99,30 @@ function evaluate() {
       profile: receipt.profile,
     };
   }
-  const result = evaluateReceipt(receipt, () => computeInputsHash(ROOT));
+  // smoke (GATE-RULES Rule 0) runs no Gradle: it proves the framework returns,
+  // never that the change is good. Refused like --fast, for the same reason.
+  if (receipt.stage === "smoke" || receipt.profile === "smoke") {
+    return {
+      valid: false,
+      reason: "the last verify run was the smoke profile (the framework check — no build, no tests; it proves the instrument, not this change); run the change-stage lane (`node qa/verify.mjs`) before finishing",
+      profile: receipt.profile,
+    };
+  }
+  // A surface this project cannot resolve is a REFUSAL with an explanation,
+  // never an unhandled stack trace: this runs as the Stop hook on every turn
+  // end, and a crash there reads as a broken harness rather than as the
+  // misconfiguration it is. (evidence-economics S8 follow-up: computeInputsHash
+  // now throws rather than returning a confident hash of the empty set.)
+  let result;
+  try {
+    result = evaluateReceipt(receipt, () => computeInputsHash(ROOT));
+  } catch (err) {
+    return {
+      valid: false,
+      reason: `cannot verify this receipt — ${err && err.message ? err.message : String(err)}`,
+      profile: receipt.profile,
+    };
+  }
   // Surface the receipt's evidence rung (the ladder — qa/lib/evidence-level.mjs)
   // alongside the verdict: the rung is the receipt's own derived field, read
   // verbatim, never recomputed here. Older receipts without it stay valid.

package/template/qa/verify.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // The verify lane — this project's single verification gate.
 //
-//   node qa/verify.mjs [--profile scaffold|local|ci|nightly|release] [--fast] [--json]
+//   node qa/verify.mjs [--profile smoke|scaffold|local|ci|nightly|release] [--fast] [--json]
 //
 // Runs every verification step this project carries, aggregates a typed
 // PASS/FAIL verdict, and writes the evidence receipt to qa/evidence/latest.json.
@@ -51,7 +51,7 @@ const ARTIFACTS_DIR = path.join(ROOT, "qa-artifacts");
 // killed). Same refusal-over-fabrication stance as qa/approve.mjs, which
 // refuses an unknown artifact by name rather than guessing: an unknown
 // argument here is refused by name, not swallowed into "run everything".
-const USAGE = `node qa/verify.mjs [--profile scaffold|local|ci|nightly|release] [--fast] [--json] [--help]
+const USAGE = `node qa/verify.mjs [--profile smoke|scaffold|local|ci|nightly|release] [--fast] [--json] [--help]
 
 The verify lane — this project's single verification gate. Runs every
 verification step this project carries, aggregates a typed PASS/FAIL
@@ -59,7 +59,7 @@ verdict, and writes the evidence receipt to qa/evidence/latest.json (commit
 it with your change — see CLAUDE.md). Exit code: 0 = PASS, 1 = FAIL.
 
 Flags:
-  --profile <scaffold|local|ci|nightly|release>
+  --profile <smoke|scaffold|local|ci|nightly|release>
                                  which step set to run (default: local)
   --fast                         INNER LOOP ONLY — run the resolved profile
                                   minus the device/release tier (releaseBuild,
@@ -101,6 +101,10 @@ Flags:
                                   running anything
 
 Profiles:
+  smoke     the smallest end-to-end lane: every pure-Node gate through the real
+            runner, receipt and journal — no Gradle, no device. Seconds. Proves the
+            FRAMEWORK returns, both ways; never the change (its receipt is refused
+            as done-evidence). Driven by scripts/framework-check.mjs.
   scaffold  spec coverage + build + unit tests (what \`create-cmp --verify\`
             proves at stamp time)
   local     everything; device-dependent steps SKIP when no device is
@@ -321,7 +325,7 @@ const { stepsForProfile, DEVICE_STEPS, FAST_EXCLUDED_NAMES, STEP_FN_BY_NAME } =
 
 
 if (!stepsForProfile[profile]) {
-  console.error(`Unknown profile "${profile}" — use scaffold | local | ci | nightly | release.`);
+  console.error(`Unknown profile "${profile}" — use smoke | scaffold | local | ci | nightly | release.`);
   process.exit(2);
 }
 
@@ -499,7 +503,7 @@ const inputs = computeInputsHash(ROOT);
 // more than its stage allows. scaffold → scaffold, local → change (per commit),
 // ci → merge, nightly → nightly (proves the harness, never a change), release →
 // release. Receipts predating this field are read as their profile's stage.
-const STAGE_OF_PROFILE = { scaffold: "scaffold", local: "change", ci: "merge", nightly: "nightly", release: "release" };
+const STAGE_OF_PROFILE = { smoke: "smoke", scaffold: "scaffold", local: "change", ci: "merge", nightly: "nightly", release: "release" };
 const receipt = {
   schema: "cmp-evidence/1",
   profile,