create-cmp-cli 0.19.0 → 0.21.0

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) {
@@ -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/template/qa/lib/lane-runner.mjs

@@ -145,6 +145,13 @@ export function runLane(ctx) {
       } catch (err) {
         result = stepErrorResult(name, err, Date.now() - stepStarted);
       }
+      // Layer tag: a pack may mark a step function with the layer of the
+      // stack it proves (`fn.layer = "backend"`). The runner stamps it onto
+      // the row so the receipt carries it and the console can group by it —
+      // a step that set its own `layer` in the result keeps its word.
+      if (result && typeof result === "object" && typeof step.layer === "string" && step.layer && typeof result.layer !== "string") {
+        result.layer = step.layer;
+      }
       results.push(result);
       if (print) {
         print(

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

@@ -32,6 +32,8 @@ import { DETERMINISM_TIMEZONES, compareOutcomes, parseJUnitOutcomes } from "./de
 import { evaluateAuditCadence } from "./audit-cadence.mjs";
 import { androidChecksOutcome } from "./step-outcomes.mjs";
 import { checkHarnessIntegrity, describeIntegrity, LOCK_PATH } from "./harness-lock.mjs";
+import { stepDisplayName } from "./lane-runner.mjs";
+import { CMP_LADDER } from "./evidence-level.mjs";
 
 /**
  * @param {object} ctx
@@ -1177,6 +1179,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.
@@ -1244,6 +1255,28 @@ stepsForProfile.release = [...stepsForProfile.ci, stepAuditCadence, stepReleaseS
 // what differs is what is forced, and what the receipt is allowed to mean.
 stepsForProfile.nightly = [...stepsForProfile.ci];
 
+// Which layer of the stack each step proves — stamped onto the receipt row by
+// the runner (lane-runner.mjs) so the Evidence pane can group by it and a
+// multi-pack lane (a Compose app over a Kotlin backend) reads as one lane
+// with per-layer tallies. Three layers for this pack: `spine` — the harness
+// proving itself and the governed record (integrity, spec coverage,
+// approvals, the architecture doc, the schema history, the audit cadence);
+// `compose` — the JVM tier of the app (build, tests, conformance, goldens,
+// a11y, release compile); `device` — anything that needs an emulator or a
+// physical device. Layer names are free-form strings on the wire; these are
+// this pack's. Derived by NAME after the lists are built so a step listed in
+// two profiles is tagged once, and a step nobody listed is never tagged.
+const SPINE_STEP_NAMES = new Set(["harnessIntegrity", "specCoverage", "approvals", "componentStories", "reachability", "archDoc", "schemaHistory", "auditCadence", "determinism"]);
+function layerForStep(name) {
+  if (DEVICE_STEPS.includes(name)) return "device";
+  if (SPINE_STEP_NAMES.has(name)) return "spine";
+  return "compose";
+}
+for (const fn of new Set(Object.values(stepsForProfile).flat())) {
+  const name = stepDisplayName(fn);
+  if (name) fn.layer = layerForStep(name);
+}
+
 const FAST_EXCLUDED_NAMES = [...DEVICE_STEPS, "releaseBuild"];
 const STEP_FN_BY_NAME = {
   e2eSmoke: stepE2eSmoke,
@@ -1266,6 +1299,10 @@ for (const name of FAST_EXCLUDED_NAMES) {
     FAST_EXCLUDED_NAMES,
     STEP_FN_BY_NAME,
     stepDeterminism,
+    // The ladder this pack's steps can earn (evidence-level.mjs). A pack that
+    // returns none earns no rung — the spine never grades a pack by another
+    // pack's step names.
+    evidenceLadder: CMP_LADDER,
     // The device lease is held to the very end of the run (see the scope
     // decision above); the spine releases it in the runner's finally.
     releaseLease: () => {

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.
@@ -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