create-cmp-cli 0.11.0 → 0.12.0

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/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)])];
+}

package/template/qa/lib/device-lease.mjs

@@ -0,0 +1,249 @@
+// The machine-global device lease — mutual exclusion for the ONE Android
+// device/emulator a machine typically has.
+//
+// WHY THIS EXISTS: the lane marker (composeApp/build/.cmp-lane-in-progress) is
+// per-PROJECT, but the device is machine-GLOBAL. A scratch app stamped in /tmp
+// and the real app are different roots sharing one emulator: each stamps its
+// own marker, neither sees the other, and two concurrent device drivers produce
+// exactly the observed failure class — wedged adbd, `device offline` while
+// `adb devices` looks fine, crossed app state between sessions, false-red runs.
+// The lease is keyed by the DEVICE (its adb serial), not the project, so the
+// primitive finally matches the scarce resource it protects.
+//
+// ── ON-DISK CONTRACT ────────────────────────────────────────────────────────
+// This exact contract is implemented independently by the create-cmp
+// inspector MCP (inspector/mcp/src/lib/device-lease.mjs in the create-cmp
+// repo — a check-only reader for connect_live / navigate_and_inspect). The two
+// codebases ship separately and cannot import each other, so the contract
+// lives verbatim in BOTH file headers, each pointing at the other. Changing
+// anything below means changing it there too.
+//
+//   Location    <os.tmpdir()>/create-cmp/device-leases/<sanitized-serial>.json
+//               tmpdir on purpose: a lease must never survive a reboot.
+//   Sanitizing  serial chars outside [A-Za-z0-9._-] become "_"
+//               ("emulator-5554"    → emulator-5554.json,
+//                "192.168.1.5:5555" → 192.168.1.5_5555.json).
+//   Shape       { "pid": number, "holder": string, "root": string,
+//                 "serial": string, "acquiredAt": ISO-8601 string }
+//               `holder` is a human/agent-readable label naming WHO is driving
+//               ("verify lane e2eSmoke", "connect_live", "fleet-check scratch
+//               lane"); `root` is the holder's project root.
+//   Staleness   a lease is DEAD (silently reclaimable) when EITHER
+//                 - its pid is not alive — process.kill(pid, 0) throws ESRCH.
+//                   EPERM means the process EXISTS under another user: ALIVE.
+//                 - OR acquiredAt is older than MAX_LEASE_AGE_MS.
+//               An unparseable lease file (torn write from a crashed holder)
+//               counts as dead. Readers treat dead as free; only acquirers
+//               delete/overwrite.
+//   Writes      atomic — temp file in the same directory + rename. After the
+//               rename the acquirer re-reads and confirms its OWN pid is in
+//               the file: two simultaneous renames resolve last-writer-wins,
+//               and the loser reports contention instead of believing it holds
+//               the device.
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Dependency-free Node. Every function takes an optional { dir } override so
+// tests exercise real files in a temp dir without touching the machine's
+// actual leases, and an optional { killImpl } so the EPERM-means-alive branch
+// is testable without a foreign-user process.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// 30 minutes: the longest legitimate single holder is a full release-profile
+// device phase on a cold emulator (installDebug + Maestro smoke +
+// connectedDebugAndroidTest + installRelease + release smoke), observed in the
+// low tens of minutes — a live holder is protected by the pid check anyway, so
+// this cap only decides how long a crashed holder whose pid was RECYCLED by an
+// unrelated long-lived process can wedge the device. 30 min bounds that to
+// roughly one lane-length: long enough never to reclaim under a healthy run,
+// short enough that the machine heals itself within the hour.
+export const MAX_LEASE_AGE_MS = 30 * 60 * 1000;
+
+/** Serial → safe file stem: anything outside [A-Za-z0-9._-] becomes "_". */
+export function sanitizeSerial(serial) {
+  return String(serial).replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/** The machine-global lease directory (override with { dir } in tests only). */
+export function leaseDir(dir) {
+  return dir || path.join(os.tmpdir(), "create-cmp", "device-leases");
+}
+
+/** Absolute path of the lease file for one serial. */
+export function leasePath(serial, { dir } = {}) {
+  return path.join(leaseDir(dir), `${sanitizeSerial(serial)}.json`);
+}
+
+/**
+ * Is a pid alive? ESRCH = no such process → dead. EPERM = the process exists
+ * but belongs to another user → ALIVE (killing rights are not liveness).
+ * Any other error is treated as alive — when in doubt, never steal a lease.
+ */
+export function pidAlive(pid, { killImpl = process.kill.bind(process) } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    killImpl(pid, 0);
+    return true;
+  } catch (err) {
+    return !(err && err.code === "ESRCH");
+  }
+}
+
+function readLeaseFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null; // missing OR unparseable — both mean "no live lease here"
+  }
+}
+
+function describeLease(lease, nowMs) {
+  const acquiredMs = Date.parse(lease.acquiredAt);
+  return {
+    holder: lease.holder ?? "unknown",
+    pid: lease.pid ?? null,
+    root: lease.root ?? null,
+    acquiredAt: lease.acquiredAt ?? null,
+    ageMs: Number.isFinite(acquiredMs) ? Math.max(0, nowMs - acquiredMs) : Number.POSITIVE_INFINITY,
+  };
+}
+
+function leaseDead(lease, nowMs, { killImpl } = {}) {
+  if (!pidAlive(lease.pid, { ...(killImpl ? { killImpl } : {}) })) return true;
+  const acquiredMs = Date.parse(lease.acquiredAt);
+  if (!Number.isFinite(acquiredMs)) return true; // no readable birth time — unverifiable, dead
+  return nowMs - acquiredMs >= MAX_LEASE_AGE_MS;
+}
+
+/** `"verify lane e2eSmoke" (pid 4711, /tmp/scratch-x, 2m ago)` — for reasons/errors. */
+export function formatHolder(heldBy) {
+  if (!heldBy) return "an unknown holder";
+  const age =
+    !Number.isFinite(heldBy.ageMs) ? "age unknown"
+    : heldBy.ageMs < 60_000 ? `${Math.max(1, Math.round(heldBy.ageMs / 1000))}s ago`
+    : `${Math.round(heldBy.ageMs / 60_000)}m ago`;
+  return `"${heldBy.holder}" (pid ${heldBy.pid ?? "?"}, ${heldBy.root ?? "unknown root"}, ${age})`;
+}
+
+/**
+ * Read the live lease on a serial, if any. Dead/stale leases read as null
+ * (free) — reading never deletes; reclaim-by-overwrite is the acquirer's job.
+ *
+ * @returns {{holder,pid,root,acquiredAt,ageMs}|null}
+ */
+export function readDeviceLease(serial, { dir, killImpl, now = Date.now } = {}) {
+  const lease = readLeaseFile(leasePath(serial, { dir }));
+  if (!lease) return null;
+  const nowMs = now();
+  if (leaseDead(lease, nowMs, { killImpl })) return null;
+  return describeLease(lease, nowMs);
+}
+
+/**
+ * Acquire the machine-global lease on one device serial.
+ *
+ * @param {{serial: string, holder: string, root: string, dir?: string,
+ *   killImpl?: Function, now?: () => number}} opts
+ * @returns {{ok: true, handle: {file, serial, pid, acquiredAt}, reclaimed: object|null}
+ *   | {ok: false, heldBy: {holder, pid, root, acquiredAt, ageMs}}}
+ *   `reclaimed` names the dead lease this acquire silently replaced (a crashed
+ *   run must never wedge the machine forever) so the acquiring run can note it
+ *   in its own output.
+ */
+export function acquireDeviceLease({ serial, holder, root, dir, killImpl, now = Date.now } = {}) {
+  if (!serial) throw new Error("acquireDeviceLease: serial is required");
+  const d = leaseDir(dir);
+  fs.mkdirSync(d, { recursive: true });
+  const file = leasePath(serial, { dir });
+  const nowMs = now();
+
+  let reclaimed = null;
+  const existing = readLeaseFile(file);
+  if (existing) {
+    if (!leaseDead(existing, nowMs, { killImpl })) {
+      return { ok: false, heldBy: describeLease(existing, nowMs) };
+    }
+    reclaimed = describeLease(existing, nowMs); // dead — reclaim silently
+  } else if (fs.existsSync(file)) {
+    reclaimed = { holder: "unreadable lease (torn write)", pid: null, root: null, acquiredAt: null, ageMs: Number.POSITIVE_INFINITY };
+  }
+
+  const lease = {
+    pid: process.pid,
+    holder: String(holder || "unknown"),
+    root: String(root || process.cwd()),
+    serial: String(serial),
+    acquiredAt: new Date(nowMs).toISOString(),
+  };
+  // Atomic claim: temp file + rename means no reader ever sees a half-written
+  // lease, and two simultaneous acquirers cannot interleave bytes.
+  const tmp = path.join(d, `.${sanitizeSerial(serial)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(lease, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+
+  // Last-writer-wins detection: both racers reached the rename; whoever's bytes
+  // survived owns the device. Re-read and confirm it is US — the loser reports
+  // contention instead of driving a device someone else holds.
+  const confirm = readLeaseFile(file);
+  if (!confirm || confirm.pid !== lease.pid || confirm.acquiredAt !== lease.acquiredAt || confirm.holder !== lease.holder) {
+    return {
+      ok: false,
+      heldBy: confirm
+        ? describeLease(confirm, now())
+        : { holder: "unknown (lease vanished mid-acquire)", pid: null, root: null, acquiredAt: null, ageMs: Number.POSITIVE_INFINITY },
+    };
+  }
+  return { ok: true, handle: { file, serial: lease.serial, pid: lease.pid, acquiredAt: lease.acquiredAt }, reclaimed };
+}
+
+/**
+ * Release a held lease. Idempotent and safe: missing file is fine, and a file
+ * that no longer carries OUR pid+acquiredAt belongs to a newer holder (they
+ * reclaimed us as stale, or won a race) — another holder's lease is NEVER
+ * deleted.
+ */
+export function releaseDeviceLease(handle) {
+  if (!handle || !handle.file) return;
+  const current = readLeaseFile(handle.file);
+  if (!current) return; // already gone (or unreadable — not provably ours, leave it)
+  if (current.pid !== handle.pid || current.acquiredAt !== handle.acquiredAt) return; // someone else's now
+  try {
+    fs.rmSync(handle.file, { force: true });
+  } catch {
+    /* releasing is best-effort; staleness reclaim is the backstop */
+  }
+}
+
+/**
+ * Run `fn(handle)` under the lease, releasing in a finally. Sync or async fn.
+ * A refused acquire is returned as-is ({ok:false, heldBy}) — the caller decides
+ * what contention means (the verify lane turns it into a SKIP, never a FAIL).
+ */
+export function withDeviceLease(opts, fn) {
+  const res = acquireDeviceLease(opts);
+  if (!res.ok) return res;
+  let out;
+  try {
+    out = fn(res.handle);
+  } catch (err) {
+    releaseDeviceLease(res.handle);
+    throw err;
+  }
+  if (out && typeof out.then === "function") {
+    return out.then(
+      (value) => {
+        releaseDeviceLease(res.handle);
+        return { ok: true, result: value, reclaimed: res.reclaimed };
+      },
+      (err) => {
+        releaseDeviceLease(res.handle);
+        throw err;
+      },
+    );
+  }
+  releaseDeviceLease(res.handle);
+  return { ok: true, result: out, reclaimed: res.reclaimed };
+}

package/template/qa/lib/evidence-level.mjs

@@ -0,0 +1,117 @@
+// The evidence ladder — the receipt's COARSE grade, derived, never declared.
+//
+// Receipts already grade themselves in fine print ("PASS (desktop-only)",
+// "PASS (on-device: e2eSmoke+androidChecks)"). This module names the rungs so
+// every surface that shows a receipt can say the same thing in one word:
+//
+//   L0 "scaffold" — the scaffold profile's checks passed (stamp-time green
+//                   build: build + unit tests + the pure-Node gates).
+//   L1 "desktop"  — full static + JVM evidence: everything L0 proves PLUS
+//                   conformance, golden trees, a11y, and the release COMPILE
+//                   (releaseBuild) — a green lane with no on-device step run.
+//   L2 "device"   — L1 plus at least one on-device EXECUTION step PASSed
+//                   (e2eSmoke, androidChecks, or the live tokenDrift tier).
+//   L3 "release"  — L2 plus releaseSmoke PASSed (the release APK installed
+//                   and driven on a device).
+//
+// HONESTY RULES — the rung must be honest to a fault, it is the vocabulary
+// evidence is sold in:
+//   - A rung is DERIVED from which steps actually ran and PASSED. It is never
+//     declared: the `profile` argument is deliberately NOT part of the
+//     derivation — a requested profile can never buy a rung its steps did not
+//     earn (it is accepted so callers state what was asked for vs. earned).
+//   - A SKIP never upgrades. A SKIPped device step does not count toward L2;
+//     a SKIPped releaseSmoke (e.g. unsigned keystore) is NOT L3. The label
+//     can never overclaim.
+//   - A FAILED lane has no rung: the rung is only computed for a PASS
+//     verdict; the receipt of a FAIL records evidenceLevel null.
+//   - A FAST-MODE lane has no rung either — not even L0. `verify --fast` is
+//     the inner loop, a signal rather than evidence, so a fast receipt must
+//     never be silently reused as if it were a full-lane result: pass the
+//     run's mode and "fast" derives null, always.
+//   - The rung is COARSE by design. The per-step list (and the existing
+//     strength string) stays the fine print alongside it — steps that may
+//     SKIP for honest configuration absence (approvals unreviewed, no
+//     exported schemas) are visible there; only the always-run steps gate
+//     the desktop rungs, and only executed PASSes gate the device rungs.
+
+/** The scaffold profile's step set (verify.mjs stepsForProfile.scaffold). */
+const SCAFFOLD_CORE = [
+  "specCoverage",
+  "approvals",
+  "componentStories",
+  "reachability",
+  "archDoc",
+  "schemaHistory",
+  "build",
+  "unitTests",
+];
+
+/** Steps every PASS must carry to claim even L0 — they run in every profile and never SKIP. */
+const L0_REQUIRED = ["build", "unitTests"];
+
+/**
+ * The steps that distinguish full desktop evidence (L1) from the scaffold
+ * checks. None of these can SKIP — they PASS or FAIL — so "PASSed" is exactly
+ * "ran green".
+ */
+const L1_REQUIRED = ["releaseBuild", "conformance", "goldenTrees", "a11y"];
+
+/** On-device EXECUTION steps — the only steps that can earn L2. */
+const DEVICE_EXECUTION = ["e2eSmoke", "tokenDrift", "androidChecks"];
+
+/** The one step that can lift L2 to L3. */
+const RELEASE_EXECUTION = "releaseSmoke";
+
+const RUNG_NAMES = { L0: "scaffold", L1: "desktop", L2: "device", L3: "release" };
+
+/**
+ * Derive the receipt's evidence rung from the lane's step results.
+ *
+ * @param {Array<{name: string, verdict: string}>} stepResults the lane's steps
+ *   as recorded on the receipt (verdict PASS | FAIL | SKIP per step)
+ * @param {string} [profile] the profile that was REQUESTED — recorded context
+ *   only, never part of the derivation (see honesty rules above)
+ * @param {{mode?: string}} [opts] the run's mode ("full" | "fast"). "fast"
+ *   derives null unconditionally — the inner loop earns no rung (see honesty
+ *   rules above). Absent/other values mean full.
+ * @returns {{rung: "L0"|"L1"|"L2"|"L3", name: string, satisfiedBy: string[]}|null}
+ *   null when any step FAILed (a failed lane has no rung), when the run was
+ *   fast-mode (the inner loop is never evidence), or when even the L0 floor
+ *   was not earned. `satisfiedBy` lists the PASSed steps the rung counts as
+ *   its evidence, in lane order.
+ */
+export function evidenceLevel(stepResults, profile, { mode } = {}) { // eslint-disable-line no-unused-vars
+  if (mode === "fast") return null; // the inner loop derives no rung — ever
+  const steps = Array.isArray(stepResults) ? stepResults.filter((s) => s && typeof s.name === "string") : [];
+  if (steps.some((s) => s.verdict === "FAIL")) return null; // a failed lane has no rung
+  const passed = new Set(steps.filter((s) => s.verdict === "PASS").map((s) => s.name));
+
+  if (!L0_REQUIRED.every((name) => passed.has(name))) return null; // not even a stamp-time green build
+
+  const inLaneOrder = (names) => steps.filter((s) => names.has(s.name) && passed.has(s.name)).map((s) => s.name);
+
+  let rung = "L0";
+  const counted = new Set(SCAFFOLD_CORE);
+
+  if (L1_REQUIRED.every((name) => passed.has(name))) {
+    rung = "L1";
+    for (const name of L1_REQUIRED) counted.add(name);
+
+    // Only an EXECUTED (PASSed) device step lifts to L2 — a SKIP never does.
+    const deviceRan = DEVICE_EXECUTION.some((name) => passed.has(name));
+    if (deviceRan) {
+      rung = "L2";
+      for (const name of DEVICE_EXECUTION) counted.add(name);
+
+      // Only a PASSed releaseSmoke lifts to L3 — a SKIP (unsigned keystore,
+      // no device) never does.
+      if (passed.has(RELEASE_EXECUTION)) {
+        rung = "L3";
+        counted.add(RELEASE_EXECUTION);
+      }
+    }
+  }
+
+  return { rung, name: RUNG_NAMES[rung], satisfiedBy: inLaneOrder(counted) };
+}

package/template/qa/lib/spec-coverage.mjs

@@ -51,17 +51,39 @@ export function scanSpecClauses(root) {
   return clauses;
 }
 
+/**
+ * Which test tier a citing file belongs to, derived from its path. Tiers are
+ * the source-set/harness boundaries that decide what a citation can actually
+ * SEE: commonTest and desktopTest run on the JVM (blind to androidMain code),
+ * androidInstrumentedTest runs on a device, e2e flows drive the installed app.
+ * @param {string} relFile path relative to the project root
+ * @returns {"commonTest"|"desktopTest"|"androidInstrumentedTest"|"e2e"|"other"}
+ */
+export function tierForFile(relFile) {
+  const p = relFile.split(path.sep).join("/");
+  if (p.includes("/androidInstrumentedTest/")) return "androidInstrumentedTest";
+  if (p.includes("/commonTest/")) return "commonTest";
+  if (p.includes("/desktopTest/")) return "desktopTest";
+  if (p.startsWith("qa/e2e/")) return "e2e";
+  return "other";
+}
+
+/** Tiers whose tests run entirely on the host JVM — blind to platform source sets. */
+export const DESKTOP_TIERS = Object.freeze(["commonTest", "desktopTest"]);
+
 /**
  * Every `// SPEC: ID[, ID…]` / `# SPEC: …` citation tag under composeApp/src
- * and qa/e2e.
+ * and qa/e2e. Each entry carries the citing file's `tier` (see tierForFile).
  * @param {string} root
- * @returns {Array<{id: string, file: string, line: number}>}
+ * @returns {Array<{id: string, file: string, line: number, tier: string}>}
  */
 export function scanCitations(root) {
   const tags = [];
   const searchDirs = [path.join(root, "composeApp/src"), path.join(root, "qa/e2e")];
   const files = searchDirs.flatMap((d) => walkFiles(d, [".kt", ".kts", ".yaml", ".yml"]));
   for (const f of files) {
+    const rel = path.relative(root, f);
+    const tier = tierForFile(rel);
     fs.readFileSync(f, "utf8")
       .split("\n")
       .forEach((line, i) => {
@@ -73,8 +95,37 @@ export function scanCitations(root) {
           .split(/[,\s]+/)
           .map((s) => s.trim())
           .filter((s) => CLAUSE_ID_RE.test(s));
-        for (const id of ids) tags.push({ id, file: path.relative(root, f), line: i + 1 });
+        for (const id of ids) tags.push({ id, file: rel, line: i + 1, tier });
       });
   }
   return tags;
 }
+
+/**
+ * Per-clause tier visibility — report data only, never a pass/fail input
+ * (instrument before you police). For each cited clause: which tiers cite it.
+ * `desktopOnly` lists live clauses whose every citation is desktop-tier
+ * (commonTest/desktopTest) — behavior claims no device-tier evidence backs.
+ * `summaryLine` is the one line the lane's specCoverage step (and any other
+ * consumer) can print verbatim; null when nothing is desktop-only.
+ * @param {Map<string, {file: string, withdrawn: boolean}>} clauses from scanSpecClauses
+ * @param {Array<{id: string, tier: string}>} tags from scanCitations
+ * @returns {{tiersByClause: Record<string, string[]>, desktopOnly: string[], summaryLine: string|null}}
+ */
+export function clauseTierCoverage(clauses, tags) {
+  const tiersByClause = {};
+  for (const t of tags) {
+    (tiersByClause[t.id] ??= []).includes(t.tier) || tiersByClause[t.id].push(t.tier);
+  }
+  const desktopOnly = [...clauses.entries()]
+    .filter(([, c]) => !c.withdrawn)
+    .map(([id]) => id)
+    .filter((id) => {
+      const tiers = tiersByClause[id];
+      return tiers && tiers.every((t) => DESKTOP_TIERS.includes(t));
+    });
+  const summaryLine = desktopOnly.length
+    ? `${desktopOnly.length} clause${desktopOnly.length === 1 ? "" : "s"} cited only from desktop-tier tests (${desktopOnly.join(", ")})`
+    : null;
+  return { tiersByClause, desktopOnly, summaryLine };
+}