create-cmp-cli 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.20.0",
+  "version": "0.22.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@create-cmp/harness",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "The create-cmp verify lane — the machine-owned harness code every stamped app carries byte-identical: evidence receipts, spec coverage, approvals, conformance reporting, golden trees, a11y, and the preview/inspector libs. Dependency-free ESM, vendored into each generated project so the lane runs offline with no install step, and content-hashed so a receipt can name the exact lane that issued it.",
   "type": "module",
   "main": "src/verify.mjs",

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/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/packages/harness/src/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/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

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

package/packages/harness/src/lib/step-outcomes.mjs

@@ -121,3 +121,107 @@ export function stepErrorResult(name, err, durationMs) {
       `Nothing here is a claim about your change.`;
   return { name, verdict: "ERROR", reason, durationMs, details: { executed: false, kind: timeout ? "deadline" : "threw" } };
 }
+
+// ── Maestro directory run → per-flow outcome ────────────────────────────────
+/**
+ * Parse Maestro's JUnit report (`maestro test <dir> --format junit --output f`)
+ * into one row per flow. Tolerant: a report that is missing or unparsable
+ * returns null and the caller falls back to the exit code — never a fabricated
+ * per-flow list.
+ * @param {string|null} xml
+ * @returns {Array<{flow: string, ok: boolean, message?: string}>|null}
+ */
+export function parseMaestroJunit(xml) {
+  if (typeof xml !== "string" || !/<testcase\b/.test(xml)) return null;
+  const rows = [];
+  const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+  let m;
+  while ((m = caseRe.exec(xml))) {
+    const attrs = m[1] || "";
+    const body = m[2] || "";
+    const name = (attrs.match(/\bname="([^"]*)"/) || [])[1] ?? (attrs.match(/\bid="([^"]*)"/) || [])[1] ?? "?";
+    const status = (attrs.match(/\bstatus="([^"]*)"/) || [])[1];
+    const failed = /<(failure|error)\b/.test(body) || (status && !/^(SUCCESS|PASSED?|OK)$/i.test(status));
+    const message = failed ? ((body.match(/<(?:failure|error)\b[^>]*message="([^"]*)"/) || [])[1] ?? body.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 300)) : undefined;
+    rows.push(failed ? { flow: name, ok: false, message } : { flow: name, ok: true });
+  }
+  return rows.length ? rows : null;
+}
+
+/**
+ * The e2e step's verdict from the Maestro run: exit code + per-flow report +
+ * the list of flows the directory held. FAIL names every failing flow; a run
+ * whose report lists fewer flows than the directory holds is ERROR — the lane
+ * cannot claim flows it has no row for.
+ * @param {{ok: boolean, out: string}} res
+ * @param {Array<{flow: string, ok: boolean, message?: string}>|null} perFlow
+ * @param {string[]} flows root-relative flow files the directory holds
+ * @returns {{verdict: "PASS"|"FAIL"|"ERROR", reason?: string, details: object}}
+ */
+export function maestroOutcome(res, perFlow, flows) {
+  const details = { flows, results: perFlow ?? undefined };
+  if (perFlow) {
+    const failed = perFlow.filter((r) => !r.ok);
+    if (failed.length) {
+      return {
+        verdict: "FAIL",
+        reason: `Maestro: ${failed.length} of ${perFlow.length} flow${perFlow.length === 1 ? "" : "s"} failed — ${failed.map((r) => `${r.flow}${r.message ? ` (${r.message.split("\n")[0].slice(0, 120)})` : ""}`).join("; ")}`,
+        details,
+      };
+    }
+    if (perFlow.length < flows.length) {
+      return {
+        verdict: "ERROR",
+        reason: `Maestro reported ${perFlow.length} flow${perFlow.length === 1 ? "" : "s"} but ${E2E_DIR_LABEL} holds ${flows.length} — the run did not cover every flow, so no verdict can be claimed for the rest`,
+        details,
+      };
+    }
+    if (!res.ok) {
+      return { verdict: "FAIL", reason: `Maestro exited non-zero with every flow reported green — treat as a run failure:\n${String(res.out).split("\n").slice(-10).join("\n")}`, details };
+    }
+    return { verdict: "PASS", details };
+  }
+  if (!res.ok) {
+    return { verdict: "FAIL", reason: `Maestro failed (no per-flow report was written):\n${String(res.out).split("\n").slice(-15).join("\n")}`, details };
+  }
+  return { verdict: "PASS", reason: "Maestro exited 0 but wrote no per-flow report — verdict from the exit code only", details };
+}
+const E2E_DIR_LABEL = "qa/e2e";
+
+// ── Device-log incidents, scoped to the app under test ──────────────────────
+/**
+ * ANR / fatal-exception lines from `adb logcat -d -b system,crash,main` that
+ * belong to one of `appIds` (an app's process may be `pkg` or `pkg:remote`).
+ * An emulator carries other apps — on 2026-09-03 the first self-booted lane
+ * went red on `ANR in com.karel.bratometer` while driving com.fleet.check —
+ * so an incident in another package is NOT this lane's failure. With no
+ * appIds known the sweep stays unscoped (every incident counts) and says so.
+ * @param {string} log
+ * @param {string[]} appIds
+ * @returns {{lines: string[], scoped: boolean}}
+ */
+export function deviceLogIncidents(log, appIds = []) {
+  const lines = String(log ?? "").split("\n");
+  const ids = appIds.filter((id) => typeof id === "string" && id.trim() && id !== "__PACKAGE__");
+  const scoped = ids.length > 0;
+  const ours = (proc) => !scoped || ids.some((id) => proc === id || proc.startsWith(`${id}:`));
+  const out = [];
+  lines.forEach((line, i) => {
+    const anr = line.match(/ANR in (\S+?)(?:\s|,|$)/);
+    if (anr) {
+      if (ours(anr[1].replace(/[,)]$/, ""))) out.push(line);
+      return;
+    }
+    if (/FATAL EXCEPTION/i.test(line)) {
+      if (!scoped) {
+        out.push(line);
+        return;
+      }
+      // The crash buffer names the process on one of the next few lines.
+      const window = lines.slice(i, i + 8).join("\n");
+      const proc = window.match(/Process:\s*(\S+?)(?:,|\s|$)/);
+      if (proc && ours(proc[1])) out.push(line);
+    }
+  });
+  return { lines: out, scoped };
+}