create-cmp-cli 0.20.0 → 0.22.0

package/src/lib/upgrade.mjs

@@ -6,6 +6,8 @@
 
 import { parseVersions, updateTomlValues, upsertProperty, parseProperties } from "./toml.mjs";
 
+import { execFileSync } from "node:child_process";
+
 export const BACKUP_SUFFIX = ".bak-upgrade";
 
 /** Marker comment the golden template ships in libs.versions.toml. */
@@ -201,3 +203,51 @@ export function planUpgrade({ tomlContent, gradlePropertiesContent, wrapperPrope
     fromOurTemplate: looksLikeOurTemplate(tomlContent),
   };
 }
+
+// ── Two upgrade courtesies the showcase asked for (2026-09-03) ──────────────
+/**
+ * Lines of YOUR file a conflict sidecar does not carry — what "take the
+ * sidecar" would silently drop. Third consecutive upgrade on the showcase:
+ * the .gitignore sidecar lacked the four signing-key ignores, and an agent
+ * resolving by taking the sidecar would leave the keystore one `git add -A`
+ * from a public repo. Blank and comment lines are not content.
+ * @param {string} yours
+ * @param {string} sidecar
+ * @returns {string[]}
+ */
+export function sidecarDroppedLines(yours, sidecar) {
+  const content = (text) =>
+    String(text ?? "")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"));
+  const have = new Set(content(sidecar));
+  return [...new Set(content(yours).filter((l) => !have.has(l)))];
+}
+
+/**
+ * Backups (*BACKUP_SUFFIX) left by EARLIER upgrades — gitignored, so git sees
+ * them as ignored-untracked. One set per upgrade accumulated and nothing
+ * cleaned them (the showcase carried 0.19.0's and 0.20.0's). Returns root-
+ * relative paths; [] when git is unavailable (then nothing is touched).
+ * @param {string} projectDir
+ * @param {{runGit?: (args: string[], cwd: string) => string|null}} [deps]
+ * @returns {string[]}
+ */
+export function staleBackupPaths(projectDir, { runGit } = {}) {
+  const git =
+    runGit ??
+    ((args, cwd) => {
+      try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+      } catch {
+        return null;
+      }
+    });
+  const out = git(["ls-files", "-z", "--others", "--ignored", "--exclude-standard"], projectDir);
+  if (out === null) return [];
+  return out
+    .split("\0")
+    .filter((p) => p.endsWith(BACKUP_SUFFIX))
+    .sort();
+}

package/template/.github/workflows/verify.yml

@@ -64,7 +64,16 @@ jobs:
       # verdict and an evidence receipt. If the build step fails after a
       # dependency bump, remember: Kotlin / KSP / Compose / Room / AGP move as
       # ONE set (see the comments in gradle/libs.versions.toml).
+      # CMP_DEVICE=none is the ONE explicit opt-out of the device tier: this
+      # hosted runner has no emulator, so e2eSmoke/androidChecks SKIP with that
+      # reason on the merge-stage receipt (visible, never silent). The lane boots
+      # a headless emulator itself everywhere else — locally that is the
+      # change-stage gate, and qa/receipt-check.mjs refuses a receipt whose
+      # device tier was opted out. To prove L2 here too, drop the variable and
+      # boot an emulator first (e.g. reactivecircus/android-emulator-runner).
       - name: Verify lane
+        env:
+          CMP_DEVICE: none
         run: node qa/verify.mjs --profile ci
 
       # The receipt this run produced, kept as a build artifact. The receipt

package/template/gitignore

@@ -44,3 +44,12 @@ qa/.plan.json
 # The closed-chain trail (drive-narration N5): local because it carries raw
 # human prompts — the committed journal for lane runs stays qa/flight-recorder.jsonl.
 qa/.plan-history.jsonl
+
+# Android signing. The keystore IS the app's identity on Android — it cannot be reissued —
+# and keystore.properties holds its passwords. Never committed, never in a sidecar diff.
+# (create-cmp-showcase, 2026-09-03: three consecutive upgrades' .gitignore sidecars lacked
+# these four lines, leaving the key one `git add -A` from a public repo.)
+keystore.properties
+keystore/
+*.jks
+*.keystore

package/template/qa/e2e/README.md

@@ -13,14 +13,33 @@ curl -fsSL "https://get.maestro.mobile.dev" | bash   # Apache-2.0, free CLI
 ## Run
 
 ```bash
-# Android: emulator/device attached, debug build installed
+# The lane runs EVERY flow in this directory (e2eSmoke), on the DEBUG build, and
+# boots a headless emulator itself when nothing is attached:
+node qa/verify.mjs
+
+# By hand, one flow, against whatever is installed:
 ./gradlew :composeApp:installDebug
 maestro test qa/e2e/smoke.yaml
-
-# The verify lane runs this automatically when maestro + a device are present:
-node qa/verify.mjs
 ```
 
+- **Every top-level `*.yaml` here runs**, in one Maestro session; the receipt's e2eSmoke row
+  lists each flow's result (`details.results`). A flow in a subfolder does not run and does
+  not count as coverage — the executed list and the coverage scan read the same list.
+- **The device**: an attached device is used as-is. With none attached the lane boots an
+  emulator headless — `CMP_AVD`, else the doctor's `cmp_pixel`, else the only AVD — waits
+  (bounded, 4 min) and shuts it down when the lane exits (`CMP_KEEP_DEVICE=1` keeps it up).
+  A device that cannot be provisioned is an ERROR row and the lane FAILs. `CMP_DEVICE=none`
+  is the one explicit opt-out; a receipt carrying it is refused as done-evidence.
+- **Per feature**: `qa/scaffold-feature.mjs` stamps `qa/e2e/<feature>.yaml` — a passing
+  skeleton (launch + shell) naming the screen id and the clauses to prove. It cites nothing
+  until you make it the journey. Mark clauses only a device can observe `[tier: e2e]` in
+  the spec; specCoverage then fails by name until a flow cites them.
+- **The gate**: `e2eCoverage` (pure Node, every profile). A feature with a screen and a spec
+  must have at least one live clause cited from a flow here — so a stamped skeleton FAILs the
+  lane by name until it is the journey. A screen with no spec is a placeholder (reported);
+  a screen declared `{ "unrouted": true }` in its brief is exempt. A `screens: true` brief is
+  likewise not done until one of its clauses is proven by a flow.
+
 ## Conventions
 
 - **Selectors by testTag** (`id:` — TestTagAutomation surfaces tags as resource-ids on

package/template/qa/e2e/smoke.yaml

@@ -1,4 +1,4 @@
-# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02.
+# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02, HOME-02.
 #
 # Proves the real app boots on a device/emulator and the bottom-nav shell works.
 # Selectors go by testTag (surfaced as resource-ids on Android via TestTagAutomation),
@@ -30,6 +30,14 @@ appId: __PACKAGE__
 - assertVisible:
     id: "app_bottom_nav"
 
+# SPEC: HOME-02 — when loading completes, the items are listed: the first item's row
+# is on screen (the exemplar's device journey; the lane's e2eCoverage gate asks every
+# feature with a screen and a spec for at least one clause proven by a flow).
+- extendedWaitUntil:
+    visible:
+      id: "home_item_1"
+    timeout: 30000
+
 # SPEC: SHELL-02 — switching tabs keeps the shell
 - tapOn:
     id: "nav_profile"

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/device-provider.mjs

@@ -0,0 +1,153 @@
+// device-provider.mjs — the lane provisions its own device.
+//
+// Until 2026-09-03 every device-tier step (tokenDrift, e2eSmoke, androidChecks,
+// releaseSmoke) SKIPped with "no Android device/emulator attached" and the
+// receipt earned L1 with three visible gaps. Visible, and universally ignored:
+// the showcase's latest receipt had e2eSmoke SKIP, four hand-written flows had
+// never been executed by any gate, and 0.21.0 was published on a fleet check
+// with the whole tier SKIPped. Karel: "they can be run headlessly and should
+// not take too long." Measured: emulator boot 36 s, e2eSmoke 109 s,
+// androidChecks 64 s. So the full lane boots a headless emulator itself when
+// nothing is attached, drives it, and shuts it down when the lane exits.
+//
+// Rules, each bounded (PRINCIPLES #5 — never wait on nothing):
+//   - an attached device (adb `device` state) is used as-is, never rebooted;
+//   - CMP_DEVICE=none is the ONE explicit opt-out (CI runners without KVM);
+//     the step rows say so, and qa/receipt-check.mjs refuses such a receipt
+//     as done-evidence at the change stage — an opt-out is visible, never done;
+//   - the AVD is CMP_AVD, else the doctor's `cmp_pixel`, else the only AVD;
+//     several AVDs and no way to choose is a refusal naming them (per-app AVD
+//     isolation: a lane must never guess another app's emulator);
+//   - boot is bounded (BOOT_BOUND_MS); past it the emulator is killed and the
+//     step rows read ERROR "could not provision a device", which FAILs the
+//     lane — a device that never comes up is a failure to test, not a SKIP.
+//
+// Pure where it can be: every subprocess goes through the injected `sh`
+// (the lane's own, so step deadlines apply) and the emulator spawn through
+// `spawnImpl`, so the whole decision tree is unit-tested without an SDK.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** How long a headless boot may take before it is killed and reported. */
+export const BOOT_BOUND_MS = 240_000;
+/** The AVD cmp-doctor creates (src/bootstrap/checks.mjs); preferred when present. */
+export const PREFERRED_AVD = "cmp_pixel";
+/** Headless, deterministic, no snapshot: every lane boots the same cold device. */
+export const HEADLESS_ARGS = Object.freeze(["-no-window", "-no-audio", "-no-boot-anim", "-no-snapshot", "-gpu", "swiftshader_indirect"]);
+const POLL_MS = 3000;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Serials in `device` state from `adb devices` output. */
+export function parseAdbDevices(out) {
+  return String(out ?? "")
+    .split("\n")
+    .slice(1)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => l.split(/\s+/))
+    .filter(([, state]) => state === "device")
+    .map(([serial]) => serial);
+}
+
+/** The emulator binary: SDK roots first, then PATH. */
+export function emulatorBinary({ env = process.env, exists = fs.existsSync, home = os.homedir() } = {}) {
+  const roots = [env.ANDROID_HOME, env.ANDROID_SDK_ROOT, path.join(home, "Library", "Android", "sdk"), path.join(home, "Android", "Sdk")].filter(Boolean);
+  for (const root of roots) {
+    const bin = path.join(root, "emulator", "emulator");
+    if (exists(bin)) return bin;
+  }
+  return "emulator";
+}
+
+/**
+ * Which AVD to boot. Never a guess between several: another app's emulator
+ * carries another app's state, and a lane driving it crosses sessions.
+ * @param {string[]} listed `emulator -list-avds` lines
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ok: true, avd: string} | {ok: false, reason: string}}
+ */
+export function chooseAvd(listed, env = process.env) {
+  const avds = listed.map((l) => l.trim()).filter((l) => l && !l.startsWith("INFO") && !l.startsWith("WARNING"));
+  if (env.CMP_AVD) {
+    if (avds.includes(env.CMP_AVD)) return { ok: true, avd: env.CMP_AVD };
+    return { ok: false, reason: `CMP_AVD=${env.CMP_AVD} is not an AVD on this machine (have: ${avds.join(", ") || "none"})` };
+  }
+  if (avds.includes(PREFERRED_AVD)) return { ok: true, avd: PREFERRED_AVD };
+  if (avds.length === 1) return { ok: true, avd: avds[0] };
+  if (avds.length === 0) return { ok: false, reason: `no AVD on this machine — run the cmp-doctor skill (it creates ${PREFERRED_AVD}) or set CMP_AVD` };
+  return { ok: false, reason: `${avds.length} AVDs and no ${PREFERRED_AVD} (${avds.join(", ")}) — set CMP_AVD to the one this app owns; the lane will not guess between apps' emulators` };
+}
+
+/**
+ * Ensure a device is attached, booting a headless emulator when none is.
+ * @param {{
+ *   sh: (cmd: string, opts?: object) => {ok: boolean, out: string},
+ *   env?: NodeJS.ProcessEnv, spawnImpl?: typeof spawn, sleep?: (ms: number) => void,
+ *   now?: () => number, log?: (line: string) => void, bootBoundMs?: number,
+ *   exists?: (p: string) => boolean, kill?: (pid: number) => void,
+ * }} deps
+ * @returns {{ok: true, serial: string, booted: boolean, avd?: string, pid?: number, bootMs?: number}
+ *         | {ok: false, optOut?: boolean, reason: string}}
+ */
+export function ensureDevice({ sh, env = process.env, spawnImpl = spawn, sleep = sleepSync, now = Date.now, log = () => {}, bootBoundMs = BOOT_BOUND_MS, exists = fs.existsSync, kill = (pid) => process.kill(pid) } = {}) {
+  if (env.CMP_DEVICE === "none") {
+    return { ok: false, optOut: true, reason: "device tier disabled by CMP_DEVICE=none (the one explicit opt-out; a receipt carrying it is never done-evidence)" };
+  }
+  const attached = parseAdbDevices(sh("adb devices", { timeout: 10_000 }).out);
+  if (attached.length > 0) return { ok: true, serial: attached[0], booted: false };
+
+  const bin = emulatorBinary({ env, exists });
+  const listing = sh(`"${bin}" -list-avds`, { timeout: 30_000 });
+  if (!listing.ok) {
+    return { ok: false, reason: `no device attached and the emulator binary could not list AVDs (${bin}) — install the Android emulator (cmp-doctor) or attach a device` };
+  }
+  const choice = chooseAvd(listing.out.split("\n"), env);
+  if (!choice.ok) return { ok: false, reason: `no device attached and ${choice.reason}` };
+
+  log(`no device attached — booting ${choice.avd} headless (bound ${Math.round(bootBoundMs / 1000)} s)`);
+  const started = now();
+  let child;
+  try {
+    child = spawnImpl(bin, ["-avd", choice.avd, ...HEADLESS_ARGS], { detached: true, stdio: "ignore" });
+    if (typeof child.unref === "function") child.unref();
+  } catch (err) {
+    return { ok: false, reason: `could not start the emulator (${err && err.message ? err.message : String(err)})` };
+  }
+  let serial = null;
+  while (now() - started < bootBoundMs) {
+    sleep(POLL_MS);
+    const serials = parseAdbDevices(sh("adb devices", { timeout: 10_000 }).out);
+    if (serials.length === 0) continue;
+    serial = serials[0];
+    const booted = sh(`adb -s ${serial} shell getprop sys.boot_completed`, { timeout: 10_000 });
+    if (booted.ok && booted.out.trim() === "1") {
+      return { ok: true, serial, booted: true, avd: choice.avd, pid: child.pid, bootMs: now() - started };
+    }
+  }
+  // Past the bound: kill what we started, and say so. A device that never
+  // comes up is a failure to test — the step rows read ERROR, the lane FAILs.
+  if (serial) sh(`adb -s ${serial} emu kill`, { timeout: 15_000 });
+  try {
+    if (child.pid) kill(child.pid);
+  } catch {
+    /* already gone */
+  }
+  return { ok: false, reason: `emulator ${choice.avd} did not reach boot_completed within ${Math.round(bootBoundMs / 1000)} s (killed) — boot it by hand once to see why, or set CMP_AVD to a lighter AVD` };
+}
+
+/**
+ * Shut down the emulator THIS lane booted; an attached device is left alone.
+ * CMP_KEEP_DEVICE=1 keeps a booted one up for the next run (saves the boot).
+ */
+export function releaseDevice(handle, { sh, env = process.env } = {}) {
+  if (!handle || !handle.ok || !handle.booted) return { shutdown: false };
+  if (env.CMP_KEEP_DEVICE === "1") return { shutdown: false, kept: true };
+  sh(`adb -s ${handle.serial} emu kill`, { timeout: 15_000 });
+  return { shutdown: true };
+}

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

@@ -0,0 +1,60 @@
+// e2e-coverage.mjs — every real feature with a screen has a device journey.
+//
+// The question (Karel, 2026-09-03): "is anything forcing e2e maestro tests to be
+// written when we implement a feature?" Before this gate: no. A feature's flow
+// was stamped as a skeleton that cites nothing, every clause could be proven by
+// JVM tests alone, and a UI feature reached "done" with zero device evidence.
+//
+// The rule: a feature is REAL when it has a screen (presentation/<f>/*Screen.kt
+// — reachability's definition) AND a spec (specs/<f>.spec.md). A real feature
+// must have at least one live clause cited from a flow under qa/e2e — a flow
+// that the lane RUNS (spec-coverage's listFlowFiles is the one list). A
+// placeholder screen without a spec is not yet real (CHANGE-FLOW-DESIGN:
+// "placeholder tabs earn a brief only when they become real") — reported, not
+// failed. A screen declared `{ "unrouted": true }` in its brief has no journey
+// to walk — exempt, by the same declare-not-gate mechanism reachability uses.
+//
+// Pure Node, milliseconds. FAILs by name with the file to write.
+
+import fs from "node:fs";
+import path from "node:path";
+import { evaluateReachability } from "./reachability.mjs";
+import { E2E_FLOW_DIR, scanCitations, scanSpecClauses } from "./spec-coverage.mjs";
+
+/**
+ * @param {string} root
+ * @returns {{verdict: "PASS"|"FAIL"|"SKIP", reason?: string, details: {features: Array<{name: string, spec: string|null, liveClauses: number, e2eCited: string[], status: "covered"|"uncovered"|"unspecified"|"unrouted"}>}}}
+ */
+export function evaluateE2eCoverage(root) {
+  if (!fs.existsSync(path.join(root, E2E_FLOW_DIR))) {
+    return { verdict: "SKIP", reason: `e2e harness not included in this project (no ${E2E_FLOW_DIR}/)`, details: { features: [] } };
+  }
+  const reach = evaluateReachability(root);
+  const screenFeatures = reach.details && Array.isArray(reach.details.features) ? reach.details.features : [];
+  if (screenFeatures.length === 0) {
+    return { verdict: "SKIP", reason: reach.reason ?? "no presentation/<feature> directory has a *Screen.kt file — nothing to cover", details: { features: [] } };
+  }
+  const clauses = scanSpecClauses(root);
+  const e2eTags = scanCitations(root).filter((t) => t.tier === "e2e");
+  const features = screenFeatures.map((f) => {
+    const specRel = `specs/${f.name}.spec.md`;
+    const spec = fs.existsSync(path.join(root, specRel)) ? specRel : null;
+    if (f.unrouted) return { name: f.name, spec, liveClauses: 0, e2eCited: [], status: "unrouted" };
+    if (!spec) return { name: f.name, spec: null, liveClauses: 0, e2eCited: [], status: "unspecified" };
+    const live = [...clauses.entries()].filter(([, c]) => c.file.split(path.sep).join("/") === specRel && !c.withdrawn).map(([id]) => id);
+    const e2eCited = [...new Set(e2eTags.filter((t) => live.includes(t.id)).map((t) => t.id))].sort();
+    return { name: f.name, spec, liveClauses: live.length, e2eCited, status: e2eCited.length ? "covered" : "uncovered" };
+  });
+  const uncovered = features.filter((f) => f.status === "uncovered");
+  if (uncovered.length === 0) return { verdict: "PASS", details: { features } };
+  const lines = [
+    `${uncovered.length} feature${uncovered.length === 1 ? " has" : "s have"} a screen and a spec but no device journey — no flow under ${E2E_FLOW_DIR}/ cites any of their clauses:`,
+    ...uncovered.map((f) =>
+      f.liveClauses === 0
+        ? `  [${f.name}] ${f.spec} has no live clauses — promise the behaviour there first, then prove one clause in ${E2E_FLOW_DIR}/${f.name}.yaml (# SPEC: <ID> above the steps)`
+        : `  [${f.name}] ${f.spec} has ${f.liveClauses} live clause${f.liveClauses === 1 ? "" : "s"} — write the journey in ${E2E_FLOW_DIR}/${f.name}.yaml and cite the clause(s) it proves (# SPEC: <ID> above the steps)`,
+    ),
+    "A UI feature is proven on a device, not only on the JVM. Declare { \"unrouted\": true } in its brief only if the screen is intentionally not reachable yet.",
+  ];
+  return { verdict: "FAIL", reason: lines.join("\n"), details: { features } };
+}

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

@@ -41,6 +41,7 @@ const SCAFFOLD_CORE = [
   "approvals",
   "componentStories",
   "reachability",
+  "e2eCoverage",
   "archDoc",
   "schemaHistory",
   "build",
@@ -65,6 +66,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, 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 +103,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 +140,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/template/qa/lib/feature-brief.mjs

@@ -334,15 +334,24 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
   const specRels = specNames.map((n) => `specs/${n}.spec.md`);
   const specExists = specRels.every((rel) => fs.existsSync(path.join(root, rel)));
   const specRel = specRels.join(" + ");
-  const citedIds = new Set((pre.citations ?? scanCitations(root)).map((t) => t.id));
+  const citations = pre.citations ?? scanCitations(root);
+  const citedIds = new Set(citations.map((t) => t.id));
+  // Which clauses a DEVICE journey proves: citations from qa/e2e flows (tier
+  // "e2e" — spec-coverage's tierForFile). A UI feature (screens: true) is not
+  // done until at least one of its live clauses is cited from a flow: JVM
+  // tests prove logic and structure, the flow proves the journey on a device.
+  const e2eCitedIds = new Set(citations.filter((t) => t.tier === "e2e").map((t) => t.id));
   const clauses = specRels
     .flatMap((rel) => clausesOfSpec(root, rel))
-    .map((c) => ({ ...c, cited: citedIds.has(c.id) }));
+    .map((c) => ({ ...c, cited: citedIds.has(c.id), e2eCited: e2eCitedIds.has(c.id) }));
   const live = clauses.filter((c) => !c.withdrawn);
   const covered = live.filter((c) => c.cited).length;
+  const e2eCovered = live.filter((c) => c.e2eCited).length;
+  const needsJourney = block.screens === true && block.unrouted !== true;
 
   const receipt = pre.receipt ?? receiptAttestation(root);
-  const provenDone = live.length > 0 && covered === live.length && receipt.verdict === "PASS" && receipt.attestsTree;
+  const provenDone =
+    live.length > 0 && covered === live.length && (!needsJourney || e2eCovered > 0) && receipt.verdict === "PASS" && receipt.attestsTree;
 
   return {
     name: brief.name,
@@ -361,6 +370,8 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
     specExists,
     clauses,
     covered,
+    e2eCovered,
+    needsJourney,
     total: live.length,
     receipt,
     provenDone,
@@ -372,6 +383,8 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
         ? `no spec yet (${specRel}) — behavior starts as clauses there`
         : live.length === 0
           ? `${specRel} has no live clauses — nothing is promised yet`
+          : needsJourney && covered === live.length && e2eCovered === 0
+            ? `${covered}/${live.length} clauses cited, but none from a qa/e2e flow — a UI feature is proven on a device: write the journey in qa/e2e/${brief.name}.yaml and cite the clause it proves`
           : covered < live.length
             ? `${covered}/${live.length} clauses cited — ${live.length - covered} promise(s) have no citing test`
             : !receipt.present

package/template/qa/lib/harness-lock.mjs

@@ -134,7 +134,12 @@ export function checkHarnessIntegrity(root) {
  */
 export function describeIntegrity(r) {
   if (r.status === "intact") {
-    return `${r.name ?? "harness"} ${r.version ?? "?"} — ${r.fileCount} files verified`;
+    // The region digest rides beside the version: two lanes can carry the same
+    // package version with different content (create-cmp-showcase, 2026-09-03 —
+    // seven files changed, "0.16.0" on both receipts), and a receipt must name
+    // WHICH lane produced it in words a human reads, not only in the lock file.
+    const region = typeof r.sha256 === "string" && r.sha256 ? ` (region ${r.sha256.slice(0, 8)})` : "";
+    return `${r.name ?? "harness"} ${r.version ?? "?"}${region} — ${r.fileCount} files verified`;
   }
   if (r.status === "unlocked") {
     return `no ${LOCK_PATH} — this app's lane version is unrecorded`;

package/template/qa/lib/inputs-hash.mjs

@@ -232,6 +232,33 @@ function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
   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.

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/spec-coverage.mjs

@@ -58,7 +58,29 @@ const TYPE_DECL_RE = /^(?:@\w+\s+)*(?:public\s+|internal\s+|private\s+|abstract\
 
 // 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"];
+export const FLOW_EXTS = [".yaml", ".yml"];
+/** Where Maestro flows live. The lane runs this DIRECTORY (every top-level flow). */
+export const E2E_FLOW_DIR = "qa/e2e";
+
+/**
+ * The flows the lane executes: top-level `*.yaml`/`*.yml` under qa/e2e, sorted,
+ * root-relative. ONE list serves two readers — the e2eSmoke step (what runs)
+ * and scanCitations (what may count as coverage) — so a citation can only
+ * ever come from a flow that executes. Before 2026-09-03 the step ran ONE
+ * file by name (smoke.yaml) while the scan walked the whole directory: four
+ * hand-written flows on the showcase satisfied clauses without ever running.
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function listFlowFiles(root) {
+  const dir = path.join(root, E2E_FLOW_DIR);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && FLOW_EXTS.some((ext) => e.name.endsWith(ext)))
+    .map((e) => `${E2E_FLOW_DIR}/${e.name}`)
+    .sort();
+}
 
 /**
  * Does a test declaration follow `index` within BINDING_WINDOW non-blank lines,
@@ -170,8 +192,10 @@ export const DESKTOP_TIERS = Object.freeze(["commonTest", "desktopTest"]);
  */
 export function scanCitations(root) {
   const tags = [];
-  const searchDirs = [path.join(root, "composeApp/src"), path.join(root, "qa/e2e")];
-  const files = searchDirs.flatMap((d) => walkFiles(d, [".kt", ".kts", ".yaml", ".yml"]));
+  // Kotlin sources anywhere under composeApp/src; flows ONLY from the list the
+  // lane runs (listFlowFiles) — a flow in a subfolder, or a yaml under
+  // composeApp/src, is not executed by e2eSmoke and therefore proves nothing.
+  const files = [...walkFiles(path.join(root, "composeApp/src"), [".kt", ".kts"]), ...listFlowFiles(root).map((rel) => path.join(root, rel))];
   for (const f of files) {
     const rel = path.relative(root, f);
     const tier = tierForFile(rel);