create-cmp-cli 0.20.0 → 0.22.0

package/packages/harness/src/lib/steps-cmp.mjs

@@ -21,17 +21,21 @@ import fs from "node:fs";
 import path from "node:path";
 import { compareTokenDrift } from "./token-drift.mjs";
 import { evaluateApprovalsGate } from "./approvals.mjs";
-import { TIERS_SATISFYING, clauseTierCoverage, scanCitations, scanSpecClauses, walkFiles } from "./spec-coverage.mjs";
+import { E2E_FLOW_DIR, TIERS_SATISFYING, clauseTierCoverage, listFlowFiles, scanCitations, scanSpecClauses, walkFiles } from "./spec-coverage.mjs";
 import { evaluateComponentStoryParity } from "./component-stories.mjs";
 import { evaluateReachability } from "./reachability.mjs";
+import { evaluateE2eCoverage } from "./e2e-coverage.mjs";
 import { memoizeStep } from "./step-cache.mjs";
 import { changedWorkingTreePaths, deriveAffectedFilter } from "./affected-tests.mjs";
 import { acquireDeviceLease, releaseDeviceLease, formatHolder } from "./device-lease.mjs";
 import { ARCH_DOC_REL_PATH, SECTION_IDS, regenerateArchDoc } from "./arch-doc.mjs";
 import { DETERMINISM_TIMEZONES, compareOutcomes, parseJUnitOutcomes } from "./determinism.mjs";
 import { evaluateAuditCadence } from "./audit-cadence.mjs";
-import { androidChecksOutcome } from "./step-outcomes.mjs";
+import { androidChecksOutcome, deviceLogIncidents, maestroOutcome, parseMaestroJunit } from "./step-outcomes.mjs";
+import { ensureDevice, releaseDevice } from "./device-provider.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
@@ -113,6 +117,33 @@ function deviceAttached() {
 // honest and visible is exactly why SKIP is the right verdict.
 let laneDeviceLease = null;
 
+// ── The lane's device (qa/lib/device-provider.mjs) ──────────────────────────
+// Provisioned ONCE per run by the first device step that needs it: an attached
+// device is used as-is; with none attached the lane boots a headless emulator
+// (bounded) and shuts it down in the runner's finally. A device that cannot
+// be provisioned is an ERROR row — "could not check" — never a SKIP that
+// reads as an honest gap and is then ignored forever (2026-09-03: the whole
+// tier had SKIPped on every receipt anyone looked at). The one SKIP left is
+// the explicit opt-out CMP_DEVICE=none, marked skipKind "environment" so the
+// receipt check refuses it as done-evidence.
+let laneDevice = null;
+
+function deviceRow(stepName, d) {
+  if (d.optOut) return { name: stepName, verdict: "SKIP", skipKind: "environment", reason: d.reason, durationMs: 0 };
+  return { name: stepName, verdict: "ERROR", reason: `could not provision a device: ${d.reason}`, durationMs: 0 };
+}
+
+/** null when the lane has a device; otherwise the row the step returns verbatim. */
+function ensureLaneDevice(stepName) {
+  if (!laneDevice) {
+    laneDevice = ensureDevice({ sh, log: (line) => console.error(`· ${line}`) });
+    if (laneDevice.ok && laneDevice.booted) {
+      console.error(`· booted ${laneDevice.avd} headless (${laneDevice.serial}) in ${Math.round(laneDevice.bootMs / 1000)} s — shut down when the lane exits (CMP_KEEP_DEVICE=1 keeps it)`);
+    }
+  }
+  return laneDevice.ok ? null : deviceRow(stepName, laneDevice);
+}
+
 /** Serials of devices currently in `device` state (same parse as deviceAttached). */
 function attachedDeviceSerials() {
   const res = sh("adb devices", { timeout: 10_000 });
@@ -148,6 +179,7 @@ function leaseDeviceForStep(stepName) {
       return {
         name: stepName,
         verdict: "SKIP",
+        skipKind: "environment",
         reason: `${serials.length} devices attached (${serials.join(", ")}) — the lane cannot tell which one it would drive, so it leases none rather than guessing. Set ANDROID_SERIAL to the device this lane should own, or detach the extras.`,
         durationMs: 0,
       };
@@ -158,6 +190,7 @@ function leaseDeviceForStep(stepName) {
     return {
       name: stepName,
       verdict: "SKIP",
+      skipKind: "environment",
       reason: `device ${serial} is held by ${formatHolder(res.heldBy)} — device evidence is batched, not concurrent; wait for it or run once when it finishes`,
       durationMs: 0,
     };
@@ -381,6 +414,16 @@ function stepReachability() {
 // (regenerateArchDoc); this step only adds the name/duration bookkeeping every
 // step in this file carries, plus wording the FAIL reason for an AI
 // collaborator (name the stale/missing section, name the fix command).
+// Every real feature has a device journey (qa/lib/e2e-coverage.mjs): a screen
+// plus a spec means at least one live clause cited from a flow the lane runs.
+// Pure Node. This is the gate that makes "write the Maestro flow" a lane
+// verdict instead of a habit (Karel, 2026-09-03).
+function stepE2eCoverage() {
+  const started = Date.now();
+  const { verdict, reason, details } = evaluateE2eCoverage(ROOT);
+  return { name: "e2eCoverage", verdict, reason, durationMs: Date.now() - started, details };
+}
+
 function stepArchDoc() {
   const started = Date.now();
   const elapsed = () => Date.now() - started;
@@ -787,14 +830,8 @@ function stepTokenDrift() {
   const started = Date.now();
   const elapsed = () => Date.now() - started;
 
-  if (!deviceAttached()) {
-    return {
-      name: "tokenDrift",
-      verdict: "SKIP",
-      reason: "no Android device/emulator attached (adb) — runtime token drift needs the live inspector tier",
-      durationMs: elapsed(),
-    };
-  }
+  const device = ensureLaneDevice("tokenDrift");
+  if (device) return { ...device, durationMs: elapsed() };
 
   const unreachable = () => ({
     name: "tokenDrift",
@@ -868,15 +905,17 @@ function maestroAvailable() {
 // The e2e guard trio, shared by every step that drives the smoke flow on a device.
 // Returns null when the harness is fully available, else the SKIP result for [name].
 function maestroGuards(name) {
-  if (!fs.existsSync(path.join(ROOT, "qa/e2e"))) {
-    return { name, verdict: "SKIP", reason: "e2e harness not included in this project (--no-e2e)", durationMs: 0 };
+  if (!fs.existsSync(path.join(ROOT, E2E_FLOW_DIR))) {
+    return { name, verdict: "SKIP", skipKind: "structure", reason: "e2e harness not included in this project (--no-e2e)", durationMs: 0 };
   }
-  if (!deviceAttached()) {
-    return { name, verdict: "SKIP", reason: "no Android device/emulator attached (adb)", durationMs: 0 };
+  if (listFlowFiles(ROOT).length === 0) {
+    return { name, verdict: "SKIP", skipKind: "structure", reason: `${E2E_FLOW_DIR}/ holds no flows (*.yaml) — nothing to drive`, durationMs: 0 };
   }
   if (!maestroAvailable()) {
-    return { name, verdict: "SKIP", reason: "maestro CLI not installed — curl -fsSL https://get.maestro.mobile.dev | bash", durationMs: 0 };
+    return { name, verdict: "SKIP", skipKind: "environment", reason: "maestro CLI not installed — curl -fsSL https://get.maestro.mobile.dev | bash", durationMs: 0 };
   }
+  const device = ensureLaneDevice(name);
+  if (device) return device;
   return null;
 }
 
@@ -895,32 +934,59 @@ function maestroGuards(name) {
 // hide_error_dialogs suppresses the OS dialog, NEVER the underlying event — so after the
 // run we grep the device log for ANR/crash lines the dialog would have shown, and FAIL on
 // them. The eyes must report what automation stability had to hide.
+// EVERY flow runs (2026-09-03). This used to run qa/e2e/smoke.yaml by name
+// while spec coverage counted a citation from ANY yaml under qa/e2e — four
+// hand-written per-feature flows on the showcase satisfied clauses without
+// ever executing. The directory runs in ONE Maestro session (one driver
+// start-up, per-flow rows from the JUnit report); listFlowFiles is the same
+// list the coverage scan reads, so cited ⊆ executed holds by construction.
+/** Driver start-up plus three minutes per flow: the Maestro run's own bound, whatever the journal says. */
+const E2E_RUN_BOUND_MS = (flowCount) => 120_000 + 180_000 * Math.max(1, flowCount);
+
 function runMaestroSmoke(name, priorDurationMs) {
+  const flows = listFlowFiles(ROOT);
+  const report = path.join(ROOT, "qa-artifacts", `maestro-${name}.xml`);
+  fs.mkdirSync(path.dirname(report), { recursive: true });
+  fs.rmSync(report, { force: true });
   const prevHideErrorDialogs = sh("adb shell settings get global hide_error_dialogs").out.trim();
   sh("adb shell settings put global hide_error_dialogs 1");
   sh("adb logcat -c"); // clear so the post-run dump only reflects this run
   try {
-    const res = sh("maestro test qa/e2e/smoke.yaml", { env: { ...process.env, MAESTRO_DRIVER_STARTUP_TIMEOUT: "120000" } });
-    if (!res.ok) {
-      return {
-        name,
-        verdict: "FAIL",
-        reason: `Maestro smoke failed (flow cites the SHELL spec clauses it proves):\n${res.out.split("\n").slice(-15).join("\n")}`,
-        durationMs: priorDurationMs + res.durationMs,
-      };
+    // Bounded on its own, not only by the step deadline: a FIRST run has no
+    // journal, so its deadline is the 30-minute ceiling — and on 2026-09-03
+    // Maestro selected the device and then sat, driver never started, app
+    // never in the foreground, under another lane's build load. Two
+    // minutes of driver start-up plus three per flow is generous for a
+    // healthy device; past it the run is killed and the row reads ERROR
+    // (StepTimeout), which is what "did not get to check" should say.
+    const runBoundMs = E2E_RUN_BOUND_MS(flows.length);
+    const res = sh(`maestro test ${E2E_FLOW_DIR} --format junit --output "${report}"`, { env: { ...process.env, MAESTRO_DRIVER_STARTUP_TIMEOUT: "120000" }, timeout: runBoundMs });
+    let xml = null;
+    try {
+      xml = fs.readFileSync(report, "utf8");
+    } catch {
+      xml = null;
+    }
+    const outcome = maestroOutcome(res, parseMaestroJunit(xml), flows);
+    if (outcome.verdict !== "PASS") {
+      return { name, verdict: outcome.verdict, reason: outcome.reason, durationMs: priorDurationMs + res.durationMs, details: outcome.details };
     }
+    // The post-run sweep is scoped to THIS app's process(es): the flows' own
+    // appId lines say which. Another app misbehaving on a shared emulator is
+    // not this lane's red (deviceLogIncidents).
+    const appIds = [...new Set(flows.map((rel) => (fs.readFileSync(path.join(ROOT, rel), "utf8").match(/^appId:\s*(\S+)/m) || [])[1]).filter(Boolean))];
     const anrDump = sh("adb logcat -d -b system,crash,main");
-    const anrRe = /ANR in |FATAL EXCEPTION/i;
-    if (anrDump.ok && anrRe.test(anrDump.out)) {
-      const anrLines = anrDump.out.split("\n").filter((l) => anrRe.test(l)).slice(0, 10).join("\n");
+    const incidents = anrDump.ok ? deviceLogIncidents(anrDump.out, appIds) : { lines: [], scoped: appIds.length > 0 };
+    if (incidents.lines.length) {
       return {
         name,
         verdict: "FAIL",
-        reason: `Maestro smoke passed, but the device log shows an ANR/crash during the run (hide_error_dialogs only suppresses the OS dialog, never the underlying event):\n${anrLines}`,
+        reason: `Maestro flows passed, but the device log shows an ANR/crash in ${incidents.scoped ? appIds.join(", ") : "some process (no appId known to scope by)"} during the run (hide_error_dialogs only suppresses the OS dialog, never the underlying event):\n${incidents.lines.slice(0, 10).join("\n")}`,
         durationMs: priorDurationMs + res.durationMs,
+        details: outcome.details,
       };
     }
-    return { name, verdict: "PASS", durationMs: priorDurationMs + res.durationMs };
+    return { name, verdict: "PASS", durationMs: priorDurationMs + res.durationMs, note: `${flows.length} flow${flows.length === 1 ? "" : "s"}`, details: outcome.details, ...(outcome.reason ? { reason: outcome.reason } : {}) };
   } finally {
     if (prevHideErrorDialogs && prevHideErrorDialogs !== "null") {
       sh(`adb shell settings put global hide_error_dialogs ${prevHideErrorDialogs}`);
@@ -966,18 +1032,13 @@ function stepAndroidChecks() {
     return {
       name: "androidChecks",
       verdict: "SKIP",
+      skipKind: "structure",
       reason: "no instrumented tests (composeApp/src/androidInstrumentedTest has no Kotlin sources)",
       durationMs: Date.now() - started,
     };
   }
-  if (!deviceAttached()) {
-    return {
-      name: "androidChecks",
-      verdict: "SKIP",
-      reason: "no Android device/emulator attached (adb) — instrumented behavior needs the real process boundary",
-      durationMs: Date.now() - started,
-    };
-  }
+  const device = ensureLaneDevice("androidChecks");
+  if (device) return { ...device, durationMs: Date.now() - started };
   // Machine-global lease before the first device touch (contention = SKIP).
   const leaseSkip = leaseDeviceForStep("androidChecks");
   if (leaseSkip) return { ...leaseSkip, durationMs: Date.now() - started };
@@ -1152,6 +1213,7 @@ const MEMOIZED_STEP_INPUTS = {
   approvals: ["qa/approvals.json", "specs", "docs/features", "docs/ARCHITECTURE.md", "composeApp/src"],
   componentStories: ["composeApp/src"],
   reachability: ["composeApp/src", "docs/features"],
+  e2eCoverage: ["composeApp/src", "docs/features", "specs", "qa/e2e"],
   archDoc: ["docs/ARCHITECTURE.md", "docs/adr", "specs", "composeApp/src"],
 };
 
@@ -1171,12 +1233,13 @@ const stepSpecCoverageMemo = memoized("specCoverage", stepSpecCoverage);
 const stepApprovalsMemo = memoized("approvals", stepApprovals);
 const stepComponentStoriesMemo = memoized("componentStories", stepComponentStories);
 const stepReachabilityMemo = memoized("reachability", stepReachability);
+const stepE2eCoverageMemo = memoized("e2eCoverage", stepE2eCoverage);
 const stepArchDocMemo = memoized("archDoc", stepArchDoc);
 
 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],
+  scaffold: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepE2eCoverageMemo, 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
@@ -1185,7 +1248,7 @@ const stepsForProfile = {
   // 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],
+  smoke: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepE2eCoverageMemo, stepArchDocMemo, stepSchemaHistory],
   local: [
     // First, always: every verdict below is only worth what the lane issuing
     // it is worth.
@@ -1194,6 +1257,7 @@ const stepsForProfile = {
     stepApprovalsMemo,
     stepComponentStoriesMemo,
     stepReachabilityMemo,
+    stepE2eCoverageMemo,
     stepArchDocMemo,
     stepSchemaHistory,
     stepBuild,
@@ -1246,13 +1310,35 @@ stepsForProfile.release = [...stepsForProfile.ci, stepAuditCadence, stepReleaseS
 // nightly (evidence-economics S6 / proposal P4): the stage for proofs whose cost
 // scales with the SUITE rather than with the change — the determinism probe
 // today (forced on above; `--determinism` is implied), and the place any
-// future mutation / load / chaos step lands, so the placement decision is made
+// future load / chaos step lands, so the placement decision is made
 // once instead of per expensive step. It proves the harness and the tree's
 // invariants, not a change: qa/receipt-check.mjs refuses its receipt as
 // done-evidence, exactly as it refuses --fast. Same step set as ci on purpose —
 // 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", "e2eCoverage", "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,
@@ -1275,10 +1361,18 @@ 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: () => {
       if (laneDeviceLease) releaseDeviceLease(laneDeviceLease);
+      // The emulator this lane booted goes down with the lane; an attached
+      // device is never touched (device-provider.mjs).
+      const down = releaseDevice(laneDevice, { sh });
+      if (down.shutdown) console.error(`· shut down ${laneDevice.avd} (${laneDevice.serial})`);
     },
   };
 }

package/packages/harness/src/receipt-check.mjs

@@ -108,6 +108,31 @@ function evaluate() {
       profile: receipt.profile,
     };
   }
+  // The device tier must have RUN (2026-09-03). The lane boots a headless
+  // emulator itself, so e2eSmoke/androidChecks only SKIP for two kinds of
+  // reason: the project's own structure (no qa/e2e harness, no instrumented
+  // sources — honest, allowed) or the ENVIRONMENT (CMP_DEVICE=none, maestro
+  // not installed, a lease held elsewhere, an ambiguous serial). The second
+  // kind is a gap a human can close, and a change is not done while it stands.
+  // Receipts predating `skipKind` are read by their reason text.
+  const DEVICE_TIER = ["e2eSmoke", "androidChecks"];
+  const envSkipped = (Array.isArray(receipt.steps) ? receipt.steps : []).filter(
+    (s) =>
+      s &&
+      DEVICE_TIER.includes(s.name) &&
+      s.verdict === "SKIP" &&
+      (s.skipKind === "environment" ||
+        (!s.skipKind && /no Android device|maestro CLI not installed|is held by|devices attached|CMP_DEVICE=none/.test(String(s.reason ?? "")))),
+  );
+  if (envSkipped.length) {
+    return {
+      valid: false,
+      reason:
+        `the device tier did not run — ${envSkipped.map((s) => `${s.name}: ${String(s.reason ?? "").split("\n")[0]}`).join("; ")}. ` +
+        "The lane boots a headless emulator itself (set CMP_AVD if it cannot choose one); fix the cause and run `node qa/verify.mjs` again before finishing",
+      profile: receipt.profile,
+    };
+  }
   // A surface this project cannot resolve is a REFUSAL with an explanation,
   // never an unhandled stack trace: this runs as the Stop hook on every turn
   // end, and a crash there reads as a broken harness rather than as the

package/packages/harness/src/scaffold-feature.mjs

@@ -315,6 +315,55 @@ const ALL_FILES = [
   { from: path.join(ROOT, `specs/${SOURCE_f}.spec.md`), to: path.join(ROOT, `specs/${f}.spec.md`), isDefaultSpec: true, presets: ["feature", "screen"] },
 ];
 
+// The feature's Maestro flow (2026-09-03): every feature with a screen gets
+// qa/e2e/<feature>.yaml, because the lane now runs EVERY flow in that
+// directory and a feature with no flow has no device-tier journey by
+// construction. It is a SKELETON that passes — launch + shell — with the
+// feature's screen id and its spec clauses named as the work to do; it cites
+// nothing (a citation it has not earned would read as coverage). Demand comes
+// from the spec: a clause marked `[tier: e2e]` fails specCoverage until a
+// flow cites them. Written only when the project carries the e2e harness.
+const E2E_FLOW_PATH = path.join(ROOT, "qa", "e2e", `${f}.yaml`);
+const WRITE_E2E_FLOW = ["feature", "screen"].includes(preset) && fs.existsSync(path.join(ROOT, "qa", "e2e")) && !fs.existsSync(E2E_FLOW_PATH);
+function e2eFlowSkeleton() {
+  const appId = (() => {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(ROOT, "create-cmp.json"), "utf8"));
+      if (typeof cfg.package === "string" && cfg.package) return cfg.package;
+    } catch {
+      /* fall through to the smoke flow's own appId */
+    }
+    try {
+      const m = fs.readFileSync(path.join(ROOT, "qa", "e2e", "smoke.yaml"), "utf8").match(/^appId:\s*(\S+)/m);
+      if (m) return m[1];
+    } catch {
+      /* no smoke flow */
+    }
+    return "__PACKAGE__";
+  })();
+  return `# E2E flow — ${f}. Maestro. The lane runs every flow in qa/e2e/ (e2eSmoke).
+#
+# SKELETON stamped by qa/scaffold-feature.mjs: it launches the app and proves the
+# shell, then stops. Make it the ${f} journey:
+#   1. navigate to the screen (its title carries testTag "${f}_title");
+#   2. assert the behaviour the clauses in specs/${f}.spec.md promise — one
+#      "# SPEC: ${F_UPPER}-NN" line above the steps that prove each clause;
+#   3. mark clauses only a device can observe "[tier: e2e]" in the spec — until a
+#      flow cites them, specCoverage FAILs by name, which is the point.
+# Selectors by testTag (id:), never display text. After any interaction that
+# triggers async state, assert with extendedWaitUntil (see smoke.yaml's SETTLE RULE).
+appId: ${appId}
+---
+- launchApp:
+    clearState: true
+- extendedWaitUntil:
+    visible:
+      id: "app_bottom_nav"
+    timeout: 60000
+# TODO(${f}): navigate to ${f} and assertVisible id: "${f}_title", then the ${F_UPPER}-NN journeys.
+`;
+}
+
 const FILES = ALL_FILES.filter((file) => file.presets.includes(preset));
 
 // Golden baseline: NOT copied (a feature's golden tree is captured fresh via
@@ -689,6 +738,12 @@ for (const file of FILES) {
   fs.writeFileSync(file.to, contents);
   filesWritten += 1;
 }
+if (WRITE_E2E_FLOW) {
+  fs.mkdirSync(path.dirname(E2E_FLOW_PATH), { recursive: true });
+  fs.writeFileSync(E2E_FLOW_PATH, e2eFlowSkeleton());
+  console.log(`  wrote ${path.relative(ROOT, E2E_FLOW_PATH)} — the feature's Maestro flow (skeleton; the lane runs it)`);
+  console.log(`  NOTE: the lane's e2eCoverage gate FAILs for ${f} until that flow is the journey and cites a ${F_UPPER}-NN clause it proves — that is the point.`);
+}
 
 let injectionsApplied = 0;
 for (const result of fileResults) {

package/packages/harness/src/verify.mjs

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

package/packages/receipts/src/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/src/commands/upgrade.mjs

@@ -41,7 +41,7 @@ import { flagBool } from "../lib/args.mjs";
 import { colors, ok, warn, fail, step } from "../lib/log.mjs";
 import { consent } from "../bootstrap/exec.mjs";
 import { loadRegistry, latestSet, getSet } from "../lib/registry.mjs";
-import { planUpgrade, BACKUP_SUFFIX } from "../lib/upgrade.mjs";
+import { planUpgrade, BACKUP_SUFFIX, sidecarDroppedLines, staleBackupPaths } from "../lib/upgrade.mjs";
 import { writeHarnessLock, checkHarnessIntegrity, describeIntegrity } from "../../packages/harness/src/lib/harness-lock.mjs";
 import { LOCAL_PATCH_PATH, stampBaseWith } from "../lib/harness-upgrade.mjs";
 import { buildTokenMap } from "../lib/tokens.mjs";
@@ -383,11 +383,25 @@ async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRo
   const actionable = plan.entries.filter(
     (e) => e.write !== null || e.sidecar !== null || e.remove
   );
+  removeStaleBackups(projectDir);
   const result = applyHarnessPlan(projectDir, actionable);
   for (const f of result.written) ok(`wrote ${f} ${colors.dim(`(backup: ${f}${BACKUP_SUFFIX})`)}`);
   for (const f of result.created) ok(`created ${f}`);
   for (const f of result.deleted) ok(`deleted ${f} ${colors.dim(`(backup: ${f}${BACKUP_SUFFIX})`)}`);
-  for (const f of result.sidecars) warn(`conflict sidecar ${f} — resolve by hand, then delete it`);
+  for (const f of result.sidecars) {
+    warn(`conflict sidecar ${f} — resolve by hand, then delete it`);
+    // Name what taking the sidecar would DROP, so the obvious resolution is
+    // never a silent loss (the showcase's signing-key ignores, three upgrades running).
+    let dropped = [];
+    try {
+      dropped = sidecarDroppedLines(fs.readFileSync(path.join(projectDir, f), "utf8"), fs.readFileSync(path.join(projectDir, f + SIDECAR_SUFFIX), "utf8"));
+    } catch {
+      dropped = [];
+    }
+    if (dropped.length) {
+      warn(`  the sidecar lacks ${dropped.length} line${dropped.length === 1 ? "" : "s"} your ${f} has — taking it as-is would drop: ${dropped.slice(0, 4).join("  |  ")}${dropped.length > 4 ? "  |  …" : ""}`);
+    }
+  }
 
   // ── Re-lock the lane ──────────────────────────────────────────────────────
   // The machine-owned region always lands on the new engine's content, whether
@@ -576,6 +590,7 @@ export async function runUpgrade(flags, positional) {
     { path: wrapperPropsPath, content: plan.newWrapperPropertiesContent },
     { path: buildGradlePath, content: plan.newBuildGradleContent },
   ];
+  removeStaleBackups(projectDir);
   for (const w of writes) {
     if (w.content === null) continue;
     fs.copyFileSync(w.path, w.path + BACKUP_SUFFIX);
@@ -602,3 +617,17 @@ export async function runUpgrade(flags, positional) {
   );
   process.exit(0);
 }
+
+
+/** Backups an EARLIER upgrade left (gitignored *.bak-upgrade) go before this one writes its own. */
+function removeStaleBackups(projectDir) {
+  const stale = staleBackupPaths(projectDir);
+  for (const rel of stale) {
+    try {
+      fs.rmSync(path.join(projectDir, rel), { force: true });
+    } catch {
+      /* a backup that cannot be removed is left, and named below either way */
+    }
+  }
+  if (stale.length) ok(`removed ${stale.length} stale *${BACKUP_SUFFIX} file${stale.length === 1 ? "" : "s"} from earlier upgrades`);
+}

package/src/lib/tabs.mjs

@@ -155,10 +155,25 @@ ${entries}
  * the static template file for the default tabs.
  * @param {ReturnType<typeof tabInfos>} infos
  */
+const HOME_ITEM_BLOCK = `
+
+# 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`;
+
 export function renderSmokeYaml(infos) {
   const [first, ...rest] = infos;
   const lines = [];
-  lines.push(`# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02.
+  // The exemplar tab (`home`, HomeScreen over the stub repository) carries the
+  // one device-proven HOME clause a fresh scaffold needs to pass e2eCoverage:
+  // after loading, the first item's row is on screen. Emitted only for that
+  // tab — a placeholder tab has no clauses to prove.
+  const homeBlock = (tab) => (tab.slug === "home" ? HOME_ITEM_BLOCK : "");
+  lines.push(`# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02${infos.some((t) => t.slug === "home") ? ", 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),
@@ -188,7 +203,7 @@ appId: __PACKAGE__
       id: "${first.slug}_title"
     timeout: 60000
 - assertVisible:
-    id: "app_bottom_nav"`);
+    id: "app_bottom_nav"${homeBlock(first)}`);
 
   rest.forEach((tab, i) => {
     lines.push("");
@@ -198,7 +213,7 @@ appId: __PACKAGE__
 - assertVisible:
     id: "${tab.slug}_title"
 - assertVisible:
-    id: "app_bottom_nav"`);
+    id: "app_bottom_nav"${homeBlock(tab)}`);
   });
 
   if (rest.length > 0) {