create-cmp-cli 0.19.0 → 0.21.0

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.
@@ -31,7 +31,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { computeInputsHash } from "./lib/inputs-hash.mjs";
+import { computeInputsHash, undeclaredTopLevel } from "./lib/inputs-hash.mjs";
 import { evidenceLevel } from "./lib/evidence-level.mjs";
 import { updateReadmeBadge, README_REL_PATH } from "./lib/evidence-badge.mjs";
 import { appendFlightRecord, buildFlightEntry, neverRunTiers, readFlightJournal } from "./lib/flight-recorder.mjs";
@@ -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);
 }
 
@@ -446,7 +450,10 @@ const strengthLabel = onDeviceSteps.length ? `on-device: ${onDeviceSteps.join("+
 // fine print; the rung is added alongside, never in place of it. null on FAIL —
 // a failed lane has no rung. null on a --fast run too: the inner loop is a
 // signal, never evidence, so a fast receipt derives NO rung at all.
-const level = evidenceLevel(steps, profile, { mode });
+// The ladder is the PACK's: a pack that declares none earns no rung (a
+// backend graded by Compose step names was L0 by construction — wrong, not
+// conservative).
+const level = evidenceLevel(steps, profile, { mode, ladder: pack.evidenceLadder ?? null });
 
 // Artifacts: hash whatever the run left under qa-artifacts/ (never committed).
 const artifacts = [];
@@ -490,6 +497,15 @@ function harnessForReceipt() {
 }
 
 const inputs = computeInputsHash(ROOT);
+// What the surface does NOT cover, at the top level. A surface is an allowlist,
+// and a new top-level directory is simply unmatched: no error, silently
+// unattested (payment-blueprint's finding, 2026-09-03). This is a REPORT on the
+// receipt, never a gate — the Compose default deliberately leaves docs/, the
+// README and the wrapper out — so a reader can see the gap and decide.
+const undeclared = undeclaredTopLevel(ROOT);
+if (undeclared.length) {
+  console.log(`  ⓘ inputs: ${undeclared.length} top-level entr${undeclared.length === 1 ? "y is" : "ies are"} outside the verified surface (unattested): ${undeclared.join(", ")}`);
+}
 
 // The receipt. Deterministic key order; ONE volatile timestamp field.
 // commit.sha is the parent HEAD at run time (you cannot know the sha of the
@@ -499,7 +515,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,
@@ -516,6 +532,10 @@ const receipt = {
   inputs: {
     hash: inputs.hash,
     fileCount: inputs.fileCount,
+    // Top-level entries the surface leaves unattested (see above). Absent when
+    // there are none, so a receipt whose surface covers everything keeps its
+    // exact prior shape.
+    ...(undeclared.length ? { undeclared } : {}),
   },
   steps,
   // WHICH LANE issued this verdict. A receipt that cannot name its own harness

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) {
@@ -178,6 +232,33 @@ function resolveSurfaceFiles(root) {
   return collected.filter((relPath) => !isExcluded(relPath));
 }
 
+/**
+ * Top-level entries (first path segment of every file git would commit) that
+ * NO surface entry covers — the files the receipt does not attest. An
+ * allowlist is silent about what it omits: a new top-level directory is simply
+ * unmatched, no error, unattested (payment-blueprint, 2026-09-03). This names
+ * the omission so the receipt can carry it and a reader can decide whether
+ * it belongs in qa/verified-surface.json. Sorted; [] when git is unavailable
+ * (the walk fallback has no notion of "what git sees") or everything is
+ * covered. Lane outputs (EXCLUDED_PREFIXES) are not "undeclared" — they are
+ * excluded by decision.
+ * @param {string} root
+ * @param {string[]} [surface] defaults to resolveVerifiedSurface(root)
+ * @returns {string[]}
+ */
+export function undeclaredTopLevel(root, surface = resolveVerifiedSurface(root)) {
+  const gitFiles = tryGitLsFiles(root);
+  if (!gitFiles) return [];
+  const covered = (relPath) => surface.some((entry) => relPath === entry || relPath.startsWith(`${entry}/`)) || isExcluded(relPath);
+  const out = new Set();
+  for (const raw of gitFiles) {
+    const relPath = raw.split(path.sep).join("/");
+    if (covered(relPath)) continue;
+    out.add(relPath.includes("/") ? relPath.slice(0, relPath.indexOf("/")) : relPath);
+  }
+  return [...out].sort();
+}
+
 /**
  * Compute the sha256 hash of the verified surface for the project rooted at `root`.
  * Deterministic: same tree (same file paths + same file bytes) → same hash.
@@ -189,7 +270,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/evidence/schema.json

@@ -26,7 +26,12 @@
       "required": ["hash", "fileCount"],
       "properties": {
         "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-        "fileCount": { "type": "number" }
+        "fileCount": { "type": "number" },
+        "undeclared": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Top-level entries git would commit that no verified-surface entry covers — unattested by this receipt. A report, never a gate; absent when the surface covers everything."
+        }
       }
     },
     "steps": {

package/template/qa/lib/affected-tests.mjs

@@ -35,7 +35,15 @@ import path from "node:path";
  * principle as inputs-hash.mjs's EXCLUDED_PREFIXES: lane outputs are not
  * verdict inputs).
  */
-export const LANE_OUTPUT_PREFIXES = ["qa/evidence", "qa-artifacts"];
+// qa/flight-recorder.jsonl is a lane output in the strictest sense: the lane
+// appends one line to it AFTER the receipt is written, on every run. It is
+// committed (the journal is the cost record), so after the first run it sits
+// in the changed set as a modified tracked file under qa/ — and qa/** is the
+// "harness itself" escape hatch. Uncounted here, every --fast run after the
+// first fell open to the full suite, visible only in one parenthetical.
+// Found by payment-blueprint's spine adoption (2026-09-03), where the same
+// line also landed in their locked region.
+export const LANE_OUTPUT_PREFIXES = ["qa/evidence", "qa-artifacts", "qa/flight-recorder.jsonl"];
 
 function isLaneOutput(p) {
   return LANE_OUTPUT_PREFIXES.some((prefix) => p === prefix || p.startsWith(`${prefix}/`));

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/evidence-badge.mjs

@@ -146,6 +146,17 @@ export function updateReadmeBadge(root) {
   if (receipt && receipt.mode === "fast") {
     return { changed: false, reason: "fast run — the inner loop bears no evidence, so the badge is left as it stands" };
   }
+  // The same rule for the two other receipts qa/receipt-check.mjs refuses as
+  // done-evidence: smoke (Rule 0 — proves the framework, never the change) and
+  // nightly (proves the harness and the tree's invariants). Both derive no
+  // rung, and a smoke run — scripts/framework-check.mjs runs one on every
+  // scaffold — was rewriting a true L1 badge to "rung unrecorded". Found on
+  // 2026-09-03 by deriving the affected filter on a fresh app: README.md was
+  // the dirty file. Receipts predating `stage` are read by profile.
+  const stage = receipt && (typeof receipt.stage === "string" ? receipt.stage : receipt.profile);
+  if (stage === "smoke" || stage === "nightly") {
+    return { changed: false, reason: `${stage} run — refused as done-evidence, so the badge is left as it stands` };
+  }
 
   const body = `${renderEvidenceBadge(receipt)}\n`;
   const next = readme.replace(

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

@@ -65,6 +65,27 @@ const RELEASE_EXECUTION = "releaseSmoke";
 
 const RUNG_NAMES = { L0: "scaffold", L1: "desktop", L2: "device", L3: "release" };
 
+/**
+ * The Compose Multiplatform pack's ladder — the step names above, as one
+ * object a pack hands to the spine. THE LADDER IS THE PACK'S, NOT THE SPINE'S
+ * (2026-09-03): vendored into a Kotlin backend, these names graded its
+ * strongest run — detekt, Konsist, mutation, gitleaks — as L0 "scaffold" and
+ * made L1 unreachable by construction. A fixed-amount understatement is not
+ * conservative, it is wrong, and receipts are where labels get quoted. So a
+ * pack declares its ladder (`evidenceLadder` on createXSteps' return); a pack
+ * that declares none earns no rung at all, which is the honest grade for a
+ * ladder nobody has calibrated. Every field is a list of step names except
+ * `release`, one name. `names` maps rung → label.
+ */
+export const CMP_LADDER = Object.freeze({
+  scaffoldCore: Object.freeze(SCAFFOLD_CORE),
+  l0Required: Object.freeze(L0_REQUIRED),
+  l1Required: Object.freeze(L1_REQUIRED),
+  deviceExecution: Object.freeze(DEVICE_EXECUTION),
+  release: RELEASE_EXECUTION,
+  names: Object.freeze(RUNG_NAMES),
+});
+
 /**
  * Derive the receipt's evidence rung from the lane's step results.
  *
@@ -81,8 +102,18 @@ const RUNG_NAMES = { L0: "scaffold", L1: "desktop", L2: "device", L3: "release"
  *   was not earned. `satisfiedBy` lists the PASSed steps the rung counts as
  *   its evidence, in lane order.
  */
-export function evidenceLevel(stepResults, profile, { mode } = {}) { // eslint-disable-line no-unused-vars
+export function evidenceLevel(stepResults, profile, { mode, ladder } = {}) { // eslint-disable-line no-unused-vars
   if (mode === "fast") return null; // the inner loop derives no rung — ever
+  // `ladder` absent → the Compose ladder (every caller before packs declared
+  // one). `ladder: null` → the pack declares none: no rung, by decision.
+  if (ladder === null) return null;
+  const L = ladder ?? CMP_LADDER;
+  const SCAFFOLD_CORE = L.scaffoldCore ?? [];
+  const L0_REQUIRED = L.l0Required ?? [];
+  const L1_REQUIRED = L.l1Required ?? [];
+  const DEVICE_EXECUTION = L.deviceExecution ?? [];
+  const RELEASE_EXECUTION = L.release ?? null;
+  const RUNG_NAMES = L.names ?? CMP_LADDER.names;
   const steps = Array.isArray(stepResults) ? stepResults.filter((s) => s && typeof s.name === "string") : [];
   // 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.
@@ -108,7 +139,7 @@ export function evidenceLevel(stepResults, profile, { mode } = {}) { // eslint-d
 
       // Only a PASSed releaseSmoke lifts to L3 — a SKIP (unsigned keystore,
       // no device) never does.
-      if (passed.has(RELEASE_EXECUTION)) {
+      if (RELEASE_EXECUTION && passed.has(RELEASE_EXECUTION)) {
         rung = "L3";
         counted.add(RELEASE_EXECUTION);
       }