create-cmp-cli 0.21.0 → 0.23.0

package/template/qa/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/template/qa/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/template/qa/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) {