create-cmp-cli 0.21.0 → 0.22.0

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

@@ -21,16 +21,18 @@ 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";
@@ -115,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 });
@@ -150,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,
       };
@@ -160,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,
     };
@@ -383,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;
@@ -789,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",
@@ -870,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;
 }
 
@@ -897,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}`);
@@ -968,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 };
@@ -1154,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"],
 };
 
@@ -1173,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
@@ -1187,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.
@@ -1196,6 +1257,7 @@ const stepsForProfile = {
     stepApprovalsMemo,
     stepComponentStoriesMemo,
     stepReachabilityMemo,
+    stepE2eCoverageMemo,
     stepArchDocMemo,
     stepSchemaHistory,
     stepBuild,
@@ -1248,7 +1310,7 @@ 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 —
@@ -1266,7 +1328,7 @@ stepsForProfile.nightly = [...stepsForProfile.ci];
 // physical device. Layer names are free-form strings on the wire; these are
 // this pack's. Derived by NAME after the lists are built so a step listed in
 // two profiles is tagged once, and a step nobody listed is never tagged.
-const SPINE_STEP_NAMES = new Set(["harnessIntegrity", "specCoverage", "approvals", "componentStories", "reachability", "archDoc", "schemaHistory", "auditCadence", "determinism"]);
+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";
@@ -1307,6 +1369,10 @@ for (const name of FAST_EXCLUDED_NAMES) {
     // 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/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) {

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"