create-cmp-cli 0.10.1 → 0.12.0

package/template/docs/TESTING.md

@@ -9,6 +9,7 @@ copy their shape.
 | Conformance gates (ARCH clauses) | `composeApp/src/desktopTest/…/conformance` | same task |
 | Screen behavior — Compose UI Test (spec-cited) | `composeApp/src/desktopTest/…/presentation` | same task |
 | Golden trees (structure) | `qa/golden/` + `HomeGoldenTreeTest` | same task |
+| Instrumented behavior (platform facts) | `composeApp/src/androidInstrumentedTest` | `./gradlew :composeApp:connectedDebugAndroidTest` (device attached) |
 <!-- >>> cmp:feature e2e -->
 | E2E smoke (few) | `qa/e2e/*.yaml` (Maestro) | `maestro test qa/e2e/smoke.yaml` |
 <!-- <<< cmp:feature e2e -->
@@ -47,6 +48,82 @@ Every durable test cites the spec clause it verifies (`// SPEC: HOME-02` — see
 Never delete, weaken, or `@Ignore` a failing test to get green. Fix the behavior — or if the
 test is genuinely wrong, change it and say so explicitly in your PR/summary.
 
+## The instrumented tier — platform behavior
+
+This seam exists because platform behavior escapes every desktop tier. Alarms,
+notifications, lock-screen/full-screen intents, notification channels, PendingIntent
+identity, audio routing, process death, and runtime permissions are OS facts:
+`desktopTest` runs on a JVM, golden trees pin structure, the conformance suite is static,
+and the E2E smoke taps UI without asserting anything about the shade or the alarm table.
+A feature whose whole point is "the phone alerts" can ship fully green from every other
+tier and never alert — that class of defect escaped to production repeatedly before this
+tier existed. When your feature touches alarms, notifications, or locks, its behavior
+test lives here.
+
+**What belongs here:** claims only the OS can witness — a notification actually reached
+the shade, a channel holds the importance the feature needs, N logical alarms occupy N
+PendingIntent slots, the alert path plays with `USAGE_ALARM` on a silenced ringer, the
+app survives process death, a permission-gated path degrades correctly.
+
+**What does not:** logic (→ `commonTest`), rendered structure (→ golden trees),
+architecture rules (→ conformance), UI journeys (→ E2E flows). If a JVM test can prove
+it, a JVM test is where it goes — this tier is the most expensive seat in the house.
+
+**Cost model:** needs a device/emulator, so it runs at checkpoint cadence — the lane's
+`androidChecks` step (`connectedDebugAndroidTest`) SKIPs honestly when no device is
+attached and runs in `local`/`ci` when one is, with the `release` profile adding the
+release-APK smoke on top. It is not an inner-loop tier; don't reach for it per-edit.
+
+**The helpers** (`androidInstrumentedTest/…/testing/`), small and composable — see
+`PlatformBehaviorSeamTest` for the exemplar shape:
+
+- `NotificationAsserts` — bounded-poll wait for a posted notification (id/tag or
+  predicate), channel-exists with an importance floor, full-screen-intent capability
+  (API-aware).
+- `AlarmAsserts` — the OS alarm table (`dumpsys alarm`) parsed per-package;
+  alarm-registered and N-distinct-alarms assertions (the PendingIntent-identity
+  collision, caught mechanically).
+- `SystemState` — snapshot/restore of ringer mode and DND so audio-routing claims are
+  testable; its header is honest about what instrumentation cannot control (OEM sound
+  policy, "a human heard it") — those stay a documented manual tier.
+
+### Runtime state control — put the system into the state the claim is about
+
+The observation helpers above answer "what did the OS do?"; this organ family answers
+the prior question — "can the test even reach the state the claim is about?" Most
+unprovable mobile claims are unprovable exactly because the state is hard to reach: you
+would have to wait hours for Doze, ship to a user who denies the permission, drop the
+network by hand, or hope the OS reclaims your process while you watch. Each organ
+reaches one such state on demand — emulator-only (every entry point SKIPs on a real
+device), root-free on stock user-build images (every shell command verified from the
+shell uid), and bracket-shaped (`withX { }` — snapshot, act, restore in `finally`) so
+organs compose:
+
+- `TimeWarp` — the device clock and time zone ("the 08:00 alarm actually arrives", DST).
+- `DozeControl` — forced light/deep idle; composed with TimeWarp it proves
+  `setExactAndAllowWhileIdle` does what its name promises (the flagship exemplar in
+  `RuntimeStateSeamTest`).
+- `PermissionControl` — the denied state (the fresh-install default) as a test input;
+  one-way grants. Its header documents the trap that shapes it: revoking a held runtime
+  permission kills the holding process — this seam's own process.
+- `ProcessControl` — real OS-driven activity destruction and saved-state rebuild
+  (don't-keep-activities — flipped live via the same binder call the Developer-options
+  toggle uses, because `settings put global always_finish_activities` alone is read only
+  at boot; verified on API 35); honest about why in-process "kill my own process" is
+  structurally impossible under instrumentation.
+- `NetworkControl` — offline (airplane mode) and per-transport wifi/data brackets; the
+  path to proving `core/connectivity/NetworkMonitor` tracks the world.
+- `ConfigControl` — dark mode, font scale, per-app locale (API 33+); configuration
+  change as the other state-loss lever.
+
+What device-state control cannot reproduce, honestly: the path INTO a state (real Doze's
+descent ladder and maintenance windows — forced idle teleports and holds), OEM policy
+(battery managers, sound routing, skinned lock screens), app-standby buckets, real-network
+character (bandwidth, captive portals, flaky RSSI — emulator transports are the host's
+connection wearing costumes), true cold-process start under instrumentation, and anything
+whose proof is a human's senses. Each organ's header states its own gaps; a green test is
+evidence for exactly the state the organ produced, nothing wider.
+
 <!-- >>> cmp:feature e2e -->
 ## E2E
 
@@ -70,3 +147,91 @@ asserts are for static post-navigation elements only.
 attached. It writes the evidence receipt to `qa/evidence/latest.json`; **commit the receipt
 with your change.** SKIPped steps are recorded honestly — green-with-gaps is visible, never
 silent.
+
+**`--fast` is the lane's inner loop.** `node qa/verify.mjs --fast` runs the resolved
+profile minus the device/release tier (`releaseBuild`, `tokenDrift`, `e2eSmoke`,
+`androidChecks`, `releaseSmoke`) — unconditionally, device attached or not. It exists
+because device/release evidence is the scarce, slow tier (R8 compile, emulator, Maestro,
+instrumented runner): batch it at the checkpoint, don't pay for it on every small edit.
+The rest of the profile runs cheaply, three ways:
+
+- **Unchanged pure-Node steps are reused, not re-run.** `specCoverage`, `approvals`,
+  `componentStories`, `reachability`, and `archDoc` are pure functions of files on disk;
+  a fast run reuses each one's last PASS when a content hash of its declared inputs is
+  unchanged, shown as `⚡ name: CACHED (unchanged since …)`. Only a PASS is ever reused —
+  a FAIL or SKIP always re-runs — and the cache
+  (`composeApp/build/.cmp-step-cache.json`) is a gitignored cache, never evidence: the
+  full lane never reads it (it always executes every step; it only writes entries so the
+  next fast run benefits).
+- **Gradle's up-to-date checks stand.** The full lane forces test execution with
+  `--rerun` (evidence integrity — a receipt must attest tests that ran). A fast receipt
+  is already declared non-evidence, so fast mode omits the flag and unchanged test tasks
+  cost nothing.
+- **Unit tests are scoped to the change.** Changed `.kt` files (git diff + untracked)
+  map to `--tests "*<feature>*"` filters, reported honestly in the step line and the
+  receipt. Broad-impact changes — build files, DI, theme/tokens, shared components,
+  `qa/` itself, anything outside `composeApp/src` — disable filtering and run the whole
+  suite, as does any uncertain case (no git, unmappable change): fail open, never fail
+  silent. A filtered fast run can miss a cross-feature regression by design; the full,
+  unfiltered suite at the checkpoint is what decides done.
+
+A fast run is mechanically unable to claim done — its receipt records `"mode": "fast"`,
+derives **no** evidence rung, and `qa/receipt-check.mjs` (the Stop hook, CI, pre-push)
+refuses it by name. Iterate on `--fast`; run the full lane once, deliberately, when the
+change is done.
+
+**Watch mode makes the inner loop resident.** `node qa/watch.mjs` watches
+`composeApp/src`, `specs/`, and `qa/` and re-runs `node qa/verify.mjs --fast` (as a
+subprocess — it inherits every fast-mode economy above for free) on every save, debounced
+so a multi-file save storm triggers one run and changes landing mid-run coalesce into
+exactly one follow-up. Each run re-prints the step table with any failing step's reason
+verbatim — the errors-on-save loop an IDE gives a human, for the agent. What it is **not**:
+evidence. It runs the fast tier only, so nothing it produces can satisfy the done-gate,
+and every run says so in a standing footer; the checkpoint remains one deliberate full
+`node qa/verify.mjs` run. Coordination: it never launches while a verify lane
+(`.cmp-lane-in-progress`) or a preview-daemon render (`.cmp-render-in-progress`) holds the
+project — it waits and coalesces, so watch mode, the preview daemon, and the lane can all
+be resident on one project without two Gradle invocations ever colliding. `--once` runs a
+single coordinated pass for scripting; `--json` emits one JSON object per run for
+programmatic consumption.
+
+## One device, one driver
+
+The machine typically has ONE Android device/emulator, and it is the scarcest, slowest,
+most fragile resource the harness touches — two concurrent drivers produce wedged adbd,
+`device offline` while `adb devices` looks fine, crossed app state, and false reds that
+have nothing to do with the app. So device evidence is **batched, never an inner loop**:
+the lane sequences its device steps (`tokenDrift` live tier, `e2eSmoke`, `androidChecks`,
+`releaseSmoke`) once, last — don't hand-run `connectedDebugAndroidTest`, `maestro test`,
+or `adb install` mid-task to "check something".
+
+Mechanically, the first device step takes a **machine-global lease** on the device's adb
+serial (`<os tmpdir>/create-cmp/device-leases/<serial>.json` — `qa/lib/device-lease.mjs`
+documents the contract), held until the lane exits. It is machine-global on purpose: two
+different projects (a scratch app in /tmp, the real one) share the same emulator, and
+per-project markers cannot see each other.
+
+**Contention is a SKIP, never a FAIL** — nothing is broken; another run legitimately holds
+the device, and the reason names it: `held by "verify lane e2eSmoke" (pid 4711,
+/tmp/scratch-x, 2m ago)`. A SKIPped device step does not buy its rung, so contention
+visibly *lowers* the evidence level (L2 falls back to L1) instead of corrupting the run —
+re-run when the holder finishes to earn the full rung. To see who holds a device:
+`cat "${TMPDIR:-/tmp}/create-cmp/device-leases/<serial>.json"`. A crashed holder never
+wedges the machine: a lease whose pid is dead, or older than 30 minutes, is silently
+reclaimed by the next run. The live inspector tier (`connect_live`,
+`navigate_and_inspect`) checks the same lease and refuses to drive a leased device by
+naming the holder instead of failing with a mysterious transport error.
+
+## The evidence ladder
+
+Every PASS receipt names its rung (`evidenceLevel` in the receipt; derived by
+`qa/lib/evidence-level.mjs` from which steps actually ran and PASSed — never declared, and
+a SKIPped step never buys a rung: an unsigned-keystore `releaseSmoke` SKIP is not L3). The
+rung is the coarse grade; the per-step list stays the fine print. A FAILed lane has no rung.
+
+| Rung | What it proves | What it does NOT prove |
+|---|---|---|
+| **L0 scaffold** | Stamp-time green: the build compiles and the unit tests pass. | Nothing about conformance, rendered structure, a11y, or the release variant — and nothing on a device. |
+| **L1 desktop** | Full static + JVM evidence: build, unit tests, conformance, golden trees, a11y, release COMPILE, and the pure-Node gates. | That the app runs on a device at all — no APK was installed or driven; platform behavior (alarms, notifications) is invisible from this rung. |
+| **L2 device** | L1 plus executed on-device evidence: the debug APK installed and driven (`e2eSmoke`), instrumented platform assertions (`androidChecks`), and/or live token drift. | That the release variant behaves (R8 differs from debug — that is L3's job), nor that alarms/notifications actually land unless an instrumented behavior test asserts them. |
+| **L3 release** | L2 plus `releaseSmoke` PASSed: the signed release APK installed and driven on a device. | Real-backend behavior (the emulator/dev backend is a documented tier boundary — see the instrumented-tier section) and store-review compliance. |

package/template/gradle/libs.versions.toml

@@ -22,6 +22,14 @@ compose-hot-reload = "1.1.1"
 coil = "3.1.0"
 androidx-core = "1.15.0"
 androidx-activity = "1.10.1"
+# ── Android instrumentation tier (androidInstrumentedTest). The alarm table, the
+# ── notification shade, channels, and audio routing are OS facts no JVM test can see —
+# ── this tier is the only evidence that crosses the process boundary onto a real device.
+androidx-test-runner = "1.6.2"
+androidx-test-core = "1.6.1"
+androidx-test-ext-junit = "1.2.1"
+androidx-uiautomator = "2.3.0"
+junit4 = "4.13.2"
 
 [libraries]
 # Compose Multiplatform
@@ -82,6 +90,13 @@ androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidx
 androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activity" }
 android-desugar-jdk = { module = "com.android.tools:desugar_jdk_libs", version = "2.1.3" }
 
+# Android instrumentation (androidInstrumentedTest — the on-device behavior tier)
+androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" }
+androidx-test-core = { module = "androidx.test:core", version.ref = "androidx-test-core" }
+androidx-test-ext-junit = { module = "androidx.test.ext:junit", version.ref = "androidx-test-ext-junit" }
+androidx-uiautomator = { module = "androidx.test.uiautomator:uiautomator", version.ref = "androidx-uiautomator" }
+junit4 = { module = "junit:junit", version.ref = "junit4" }
+
 # Test
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
 koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }

package/template/manifest.json

@@ -30,6 +30,7 @@
     "composeApp/src/androidMain/kotlin",
     "composeApp/src/androidDebug/kotlin",
     "composeApp/src/androidRelease/kotlin",
+    "composeApp/src/androidInstrumentedTest/kotlin",
     "composeApp/src/iosMain/kotlin",
     "composeApp/src/desktopMain/kotlin"
   ],

package/template/qa/approve.mjs

@@ -9,8 +9,25 @@
 //   node qa/approve.mjs --accept-defaults   express lane (GENESIS-FLOW-DESIGN.md §2): approves
 //                                            every currently-resolvable, not-yet-approved
 //                                            artifact, each stamped "defaults-accepted"
-//   node qa/approve.mjs --reopen <artifact> moves an approved artifact back to "reopened" for
-//                                            redesign (refuses anything not currently approved)
+//   node qa/approve.mjs --reopen <artifact> --reason "…"
+//                                            moves an approved artifact back to "reopened" for
+//                                            redesign (refuses anything not currently approved).
+//                                            --reason is REQUIRED — a reopen walks back a
+//                                            signature, and the signer must be able to read why
+//                                            from the ledger itself (2026-07-28 flow audit)
+//   node qa/approve.mjs --reopen-feature <name> --reason "…"
+//                                            one recorded change, not N reopen commands: reopens
+//                                            the brief + its spec + its design + every artifact
+//                                            the brief declares in `touches` (each only if
+//                                            currently approved), all under one reason
+//   node qa/approve.mjs --log               the journal — every approve/reopen/accept with
+//                                            when, which surface, and why (newest last)
+//   node qa/approve.mjs --accept <name>     the HUMAN's bookend on a feature brief
+//                                            (feature-brief:<name>) — refused until the feature
+//                                            is provenDone (every live clause cited + receipt
+//                                            PASS + receipt attests this tree). There is no
+//                                            --deliver: doneness is DERIVED, never claimed
+//                                            (CHANGE-FLOW-DESIGN.md §2).
 //
 // This file has NO logic of its own — every decision (the registry, hashing,
 // state, the transitions) lives in qa/lib/approvals.mjs. That's deliberate: the
@@ -22,12 +39,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
+  acceptFeature,
   approveAllDefaults,
   approveArtifact,
   getApprovalStatuses,
+  getFeatureBoard,
   isPackageResolvable,
   listGovernedArtifacts,
+  readJournal,
   reopenArtifact,
+  reopenFeature,
 } from "./lib/approvals.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -52,22 +73,44 @@ function printStatus() {
     // approvable — approval over an unresolved file set is refused.
     const hashInfo =
       s.status === "reopened"
-        ? `reopened at ${s.reopenedAt} (was approved ${shortHash(s.storedHash)})`
+        ? `reopened at ${s.reopenedAt} (was approved ${shortHash(s.storedHash)})${s.reason ? ` — ${s.reason}` : ""}`
         : s.status === "changed-since-approval"
           ? s.resolvable
             ? `approved ${shortHash(s.storedHash)} -> now ${shortHash(s.hash)}`
             : `approved ${shortHash(s.storedHash)} -> unresolvable (${s.fileCount} of expected files resolved)`
           : s.status === "approved"
-            ? shortHash(s.hash)
+            ? // storedHash is the signature; s.hash is the live recompute. They
+              // agree except on a legacy raw-bytes row, where printing the live
+              // value would name a hash nobody signed.
+              `${shortHash(s.storedHash) || shortHash(s.hash)}${
+                s.hashBasis === "raw-bytes" ? ", signed pre-strip — bytes unchanged since" : ""
+              }`
             : s.resolvable
               ? `would approve at ${shortHash(s.hash)}`
               : `unresolvable (${s.fileCount} of expected files resolved) — not approvable`;
     const modeInfo = s.mode ? ` [${s.mode}]` : "";
-    console.log(`${mark} ${s.id}: ${s.status} (${hashInfo})${modeInfo} — ${s.label}`);
+    // A feature brief's acceptance lives on the ledger row, never in the doc
+    // (the signed bytes must not move when the human accepts).
+    const lifecycle = s.accepted ? ` · accepted ${s.acceptedAt}` : "";
+    console.log(`${mark} ${s.id}: ${s.status} (${hashInfo})${modeInfo}${lifecycle} — ${s.label}`);
     if (s.missing.length > 0) {
       console.log(`    missing: ${s.missing.join(", ")}`);
     }
   }
+
+  // Per-feature DERIVED doneness + next step — the same getFeatureBoard the
+  // console renders, so --status and the console never tell different
+  // stories. The next step names its owner: a signature HANDS OFF, it never
+  // commands — the agent drafts/builds/proves, the human signs/accepts.
+  const { features } = getFeatureBoard(ROOT);
+  if (features.length > 0) {
+    console.log("\nFeatures (doneness is derived, never claimed):");
+    for (const f of features) {
+      const mark = f.provenDone ? "✓" : "…";
+      console.log(`  ${mark} ${f.name}: ${f.doneReason}${f.blockError ? ` — BLOCK ERROR: ${f.blockError}` : ""}`);
+      console.log(`      next → ${f.nextStep.label}${f.nextStep.owner ? ` · ${f.nextStep.owner}` : ""}`);
+    }
+  }
 }
 
 if (args.includes("--status")) {
@@ -102,27 +145,92 @@ if (args.includes("--accept-defaults")) {
   process.exit(0);
 }
 
+// --reason is shared by --reopen and --reopen-feature: one plain sentence for
+// the human who signed, recorded on the ledger row AND the journal. The library
+// refuses without it; parsing it here just makes the usage line honest.
+const reasonFlagIdx = args.indexOf("--reason");
+const reason = reasonFlagIdx !== -1 ? args[reasonFlagIdx + 1] : undefined;
+
+if (args.includes("--log")) {
+  const events = readJournal(ROOT);
+  if (events.length === 0) {
+    console.log("No journal yet (qa/approvals.log.jsonl) — it starts recording with the next approve/reopen/accept.");
+    process.exit(0);
+  }
+  console.log("Governance journal (oldest first):\n");
+  for (const e of events) {
+    const mark = e.verb === "approve" ? "✓" : e.verb === "reopen" ? "↺" : e.verb === "accept" ? "◆" : "·";
+    const bits = [e.via ? `via ${e.via}` : null, e.mode ? `[${e.mode}]` : null, e.feature ? `feature ${e.feature}` : null]
+      .filter(Boolean)
+      .join(" · ");
+    console.log(`${mark} ${e.at}  ${e.verb} ${e.artifact}${bits ? ` (${bits})` : ""}${e.reason ? ` — ${e.reason}` : ""}`);
+  }
+  process.exit(0);
+}
+
 const reopenFlagIdx = args.indexOf("--reopen");
 if (reopenFlagIdx !== -1) {
   refuseIfUnresolvable();
   const artifactId = args[reopenFlagIdx + 1];
-  if (!artifactId) {
-    console.error("usage: node qa/approve.mjs --reopen <artifact>");
+  if (!artifactId || artifactId === "--reason") {
+    console.error('usage: node qa/approve.mjs --reopen <artifact> --reason "why, in one sentence"');
+    process.exit(1);
+  }
+  const result = reopenArtifact(ROOT, artifactId, { reason, via: "cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`↺ reopened ${result.artifact} for redesign — at ${result.reopenedAt}\n  reason: ${reason.trim()}`);
+  process.exit(0);
+}
+
+// One recorded change, not N reopen commands (2026-07-28 flow audit, fix 4):
+// the brief is the container the human thinks in — reopen its whole declared
+// set under one reason, each journal event grouped by the feature's name.
+const reopenFeatureFlagIdx = args.indexOf("--reopen-feature");
+if (reopenFeatureFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const name = args[reopenFeatureFlagIdx + 1];
+  if (!name || name === "--reason") {
+    console.error('usage: node qa/approve.mjs --reopen-feature <name> --reason "why, in one sentence"');
+    process.exit(1);
+  }
+  const result = reopenFeature(ROOT, name, { reason, via: "cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`↺ reopened feature "${result.feature}" as one change — reason: ${reason.trim()}`);
+  for (const id of result.reopened) console.log(`  ↺ ${id}`);
+  for (const s of result.skipped) console.log(`  → skipped ${s.id} (${s.status})`);
+  process.exit(0);
+}
+
+// The human's bookend: --accept takes the brief NAME, not the full artifact
+// id — the docs/features/<name>.md filename is what a human knows. The library
+// refuses until the feature is provenDone; there is no agent claim in between.
+const acceptFlagIdx = args.indexOf("--accept");
+if (acceptFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const name = args[acceptFlagIdx + 1];
+  if (!name) {
+    console.error("usage: node qa/approve.mjs --accept <name>   (the brief's name — docs/features/<name>.md)");
     process.exit(1);
   }
-  const result = reopenArtifact(ROOT, artifactId);
+  const result = acceptFeature(ROOT, name, { via: "cli" });
   if (!result.ok) {
     console.error(`error: ${result.reason}`);
     process.exit(1);
   }
-  console.log(`↺ reopened ${result.artifact} for redesign — at ${result.reopenedAt}`);
+  console.log(`✓ accepted ${result.artifact} at ${result.acceptedAt} — the feature's card closes; the brief is its doc-of-record.`);
   process.exit(0);
 }
 
 if (args.length === 0) {
   const ids = listGovernedArtifacts(ROOT).map((a) => a.id);
   console.error(
-    "usage: node qa/approve.mjs <artifact> | --status | --accept-defaults | --reopen <artifact>\n" +
+    'usage: node qa/approve.mjs <artifact> | --status | --log | --accept-defaults | --reopen <artifact> --reason "…" | --reopen-feature <name> --reason "…" | --accept <name>\n' +
       `  valid artifacts: ${ids.length > 0 ? ids.join(", ") : "(none resolved in this project)"}`,
   );
   process.exit(1);
@@ -131,7 +239,7 @@ if (args.length === 0) {
 refuseIfUnresolvable();
 
 const artifactId = args[0];
-const result = approveArtifact(ROOT, artifactId);
+const result = approveArtifact(ROOT, artifactId, { via: "cli" });
 if (!result.ok) {
   console.error(`error: ${result.reason}`);
   process.exit(1);

package/template/qa/evidence/schema.json

@@ -6,7 +6,11 @@
   "required": ["schema", "profile", "verdict", "commit", "steps", "artifacts", "toolVersions", "generatedAt"],
   "properties": {
     "schema": { "const": "cmp-evidence/1" },
-    "profile": { "enum": ["scaffold", "local", "ci"] },
+    "profile": { "enum": ["scaffold", "local", "ci", "release"] },
+    "mode": {
+      "enum": ["full", "fast"],
+      "description": "How the lane was run. \"full\" is the done-gate. \"fast\" (verify --fast) excluded the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke): an inner-loop signal whose receipt derives no evidence rung and is REFUSED by qa/receipt-check.mjs — it can never satisfy done. Absent on receipts predating the flag — treated as full."
+    },
     "verdict": { "enum": ["PASS", "FAIL"] },
     "commit": {
       "type": "object",
@@ -32,13 +36,27 @@
         "required": ["name", "verdict", "durationMs"],
         "properties": {
           "name": { "type": "string" },
-          "verdict": { "enum": ["PASS", "FAIL", "SKIP"] },
+          "verdict": {
+            "enum": ["PASS", "FAIL", "SKIP", "CACHED"],
+            "description": "CACHED appears ONLY on mode:\"fast\" receipts: a pure-Node step's last PASS reused because its content-hashed input set is unchanged (qa/lib/step-cache.mjs). Counts as PASS for the lane verdict but stays visibly distinct — the full lane never consults the cache, so a full receipt never carries it."
+          },
           "reason": { "type": "string" },
+          "note": { "type": "string", "description": "Honest fine print on a non-FAIL step (fast mode): which unit-test filter ran, or when a CACHED verdict was originally earned." },
           "durationMs": { "type": "number" },
           "details": { "type": "object" }
         }
       }
     },
+    "evidenceLevel": {
+      "type": ["object", "null"],
+      "description": "The evidence ladder rung (qa/lib/evidence-level.mjs), DERIVED from which steps actually ran and PASSed — never declared. L0 scaffold / L1 desktop / L2 device / L3 release; a SKIPped step never upgrades a rung. null when the lane FAILed (a failed lane has no rung). Absent on receipts predating the ladder.",
+      "required": ["rung", "name", "satisfiedBy"],
+      "properties": {
+        "rung": { "enum": ["L0", "L1", "L2", "L3"] },
+        "name": { "enum": ["scaffold", "desktop", "device", "release"] },
+        "satisfiedBy": { "type": "array", "items": { "type": "string" }, "description": "The PASSed step names the rung counts as its evidence, in lane order" }
+      }
+    },
     "artifacts": {
       "type": "array",
       "items": {

package/template/qa/lib/affected-tests.mjs

@@ -0,0 +1,147 @@
+// affected-tests.mjs — FAST-MODE-ONLY scoping of the unit-test suite to the
+// tests plausibly affected by the working-tree change.
+//
+// The full lane always runs the whole suite; this module exists so the inner
+// loop (`verify --fast`) doesn't pay for every test on a one-file edit. Its
+// honesty contract:
+//
+//   - FALSE NEGATIVES ARE ACCEPTABLE HERE — AND ONLY HERE. A filtered fast
+//     run can miss a cross-feature regression; that is tolerable purely
+//     because the full, unfiltered suite runs at the checkpoint (the full
+//     lane), where done is actually decided. No other gate gets this license.
+//   - FAIL OPEN, NEVER FAIL SILENT. No git, a failed git command, an unmapped
+//     change, a broad-impact change — every uncertain case runs EVERYTHING,
+//     and the caller reports which case it was in the step's output and the
+//     receipt, so a filtered run can never be mistaken for the full suite.
+//   - The BLAST-RADIUS ESCAPE HATCH is mandatory: some paths fan out too
+//     widely to subset safely (build files rewire compilation, DI rewires
+//     object graphs, theme/tokens and shared components render into every
+//     screen, qa/ is the harness judging itself, and anything outside
+//     composeApp/src is by definition not a scoped source edit). Any one such
+//     change disables filtering for the run.
+//
+// Pure functions over path lists — git access is injected/separate so the
+// engine suite can test every branch with no repo state.
+
+import { execSync } from "node:child_process";
+import path from "node:path";
+
+/**
+ * Lane OUTPUTS, excluded from the changed-set before any classification.
+ * The receipt (qa/evidence/) and hashed artifacts (qa-artifacts/) change on
+ * every lane run by design; counting them as "changes" would make the qa/**
+ * escape hatch self-triggering forever — run N's receipt forcing run N+1 to
+ * the full suite, permanently. They cannot affect a test outcome (the same
+ * principle as inputs-hash.mjs's EXCLUDED_PREFIXES: lane outputs are not
+ * verdict inputs).
+ */
+export const LANE_OUTPUT_PREFIXES = ["qa/evidence", "qa-artifacts"];
+
+function isLaneOutput(p) {
+  return LANE_OUTPUT_PREFIXES.some((prefix) => p === prefix || p.startsWith(`${prefix}/`));
+}
+
+/**
+ * The mandatory blast-radius escape hatch: paths whose change fans out too
+ * widely to subset the suite safely. Returns the human-readable category when
+ * `p` is broad-impact, else null. Checked in order; the first match names the
+ * reason.
+ * @param {string} p POSIX relpath from the project root
+ * @returns {string|null}
+ */
+export function broadImpactReason(p) {
+  if (p.endsWith(".gradle.kts") || p === "gradle.properties" || p === "gradle/libs.versions.toml") {
+    return "build files rewire compilation";
+  }
+  if (/(^|\/)di\//.test(p)) return "DI rewires the object graph";
+  if (/(^|\/)theme\//.test(p)) return "theme/tokens render into every screen";
+  if (p.includes("presentation/components/")) return "shared components render into every screen";
+  if (p === "qa" || p.startsWith("qa/")) return "qa/ is the harness itself";
+  if (!p.startsWith("composeApp/src/")) return "outside composeApp/src";
+  return null;
+}
+
+/**
+ * Derive the fast-mode unit-test filter from a list of changed paths.
+ *
+ * Mapping (deliberately simple and defensible): each changed `.kt` file under
+ * composeApp/src contributes its package's last segment — the parent
+ * directory name (`…/presentation/home/HomeViewModel.kt` → `home`, which the
+ * template's package-mirrors-path conformance makes a package segment) — and
+ * the union becomes Gradle `--tests "*<seg>*"` patterns matched against test
+ * class FQNs. Coarse on purpose: `*home*` runs every test whose FQN mentions
+ * the feature, which over-selects a little and under-maintains nothing.
+ *
+ * @param {string[]} changedPaths relpaths (either separator style) — tracked
+ *   diffs plus untracked files, as from changedWorkingTreePaths()
+ * @returns {{mode: "filtered", patterns: string[], sourcePaths: string[]} |
+ *   {mode: "all", reason: string, patterns: [], sourcePaths: string[]}}
+ *   mode "all" ALWAYS carries the honest reason to report.
+ */
+export function deriveAffectedFilter(changedPaths) {
+  const paths = [...new Set((changedPaths ?? [])
+    .filter((p) => typeof p === "string" && p.length > 0)
+    .map((p) => p.split(path.sep).join("/")))]
+    .filter((p) => !isLaneOutput(p))
+    .sort();
+
+  if (paths.length === 0) {
+    return { mode: "all", reason: "no working-tree changes to scope by", patterns: [], sourcePaths: [] };
+  }
+
+  for (const p of paths) {
+    const broad = broadImpactReason(p);
+    if (broad) {
+      return { mode: "all", reason: `broad-impact change — ${broad} (${p})`, patterns: [], sourcePaths: paths };
+    }
+  }
+
+  // Every remaining path is a scoped file under composeApp/src. Only .kt
+  // files map to test patterns; a change that maps to nothing (resources,
+  // manifests) falls open to the full suite below.
+  const ktPaths = paths.filter((p) => p.endsWith(".kt"));
+  const segments = new Set();
+  for (const p of ktPaths) {
+    const seg = path.posix.basename(path.posix.dirname(p));
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(seg)) segments.add(seg);
+  }
+
+  if (segments.size === 0) {
+    return { mode: "all", reason: "changed files map to no test filter", patterns: [], sourcePaths: paths };
+  }
+
+  return {
+    mode: "filtered",
+    patterns: [...segments].sort().map((s) => `*${s}*`),
+    sourcePaths: ktPaths,
+  };
+}
+
+function defaultRunGit(args, root) {
+  try {
+    return execSync(`git ${args}`, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The working-tree change: tracked files differing from HEAD (staged or not)
+ * plus untracked-but-not-ignored files — the same "what will this commit
+ * touch" surface inputs-hash.mjs hashes.
+ *
+ * Returns null when git is unavailable or either command fails — the caller
+ * MUST treat null as "run everything" (fail open) and say so (never fail
+ * silent).
+ *
+ * @param {string} root project root
+ * @param {(args: string, root: string) => string|null} [runGit] injectable for tests
+ * @returns {string[]|null}
+ */
+export function changedWorkingTreePaths(root, runGit = defaultRunGit) {
+  const diff = runGit("diff --name-only HEAD", root);
+  const untracked = runGit("ls-files --others --exclude-standard", root);
+  if (diff === null || untracked === null) return null;
+  const lines = (out) => out.replace(/\n+$/, "").split("\n").filter(Boolean);
+  return [...new Set([...lines(diff), ...lines(untracked)])];
+}