create-cmp-cli 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.19.0",
+  "version": "0.21.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/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/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/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/packages/harness/src/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);
       }

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) {
@@ -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/harness/src/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/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

@@ -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/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");
 }