create-cmp-cli 0.11.0 → 0.13.0

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-badge.mjs

@@ -0,0 +1,158 @@
+// The README's evidence badge — the evidence ladder, rendered where a human
+// actually looks (roadmap §10 item 2: "render the rung in the console and
+// README badge").
+//
+// The console already shows the rung (rail foot, Evidence section, receipt
+// timeline). The README is the surface a human meets FIRST, and the one that
+// travels — into a GitHub repo page, a PR, a screenshot in a deck. That makes
+// it the surface where an overclaim does the most damage, so the badge obeys
+// one rule above all others:
+//
+//   **The badge is a statement about a specific commit, never about "now".**
+//
+// A badge that says "L2 device" says nothing about whether the code has moved
+// since. So it never renders a bare rung: it renders the rung AND the commit
+// it was attested against AND the date. That sentence stays true forever — a
+// reader can see at a glance whether the sha still matches what they are
+// looking at. Everything else follows from the same rule: no receipt says so,
+// a FAIL says so, and a --fast run (which the ladder deliberately grants no
+// rung) says so rather than borrowing the last good one.
+//
+// Written by the lane AFTER the receipt (it is an output derived from the
+// receipt, never a gate), and committed alongside it.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const README_REL_PATH = "README.md";
+export const BADGE_SECTION_ID = "evidence";
+
+const MARKER_RE = new RegExp(
+  `<!-- cmp:generated ${BADGE_SECTION_ID} -->\\n([\\s\\S]*?)<!-- /cmp:generated -->`
+);
+
+/** Shields.io colours, one per rung — the ladder read at a glance. */
+const RUNG_COLOR = {
+  L0: "9E9E9E", // scaffold — grey: a green build, nothing proven about behavior
+  L1: "42A5F5", // desktop — blue
+  L2: "26A69A", // device — teal
+  L3: "43A047", // release — green: the strongest rung this harness can attest
+};
+
+/** shields.io escaping: `-` → `--`, `_` → `__`, space → `_`. */
+function shieldEscape(s) {
+  return String(s).replace(/-/g, "--").replace(/_/g, "__").replace(/ /g, "_");
+}
+
+/**
+ * The badge body for a receipt — Markdown, no trailing newline handling (the
+ * caller frames it). Pure: every degraded state has its own honest rendering
+ * and NONE of them fall back to a rung.
+ *
+ * @param {object|null} receipt parsed qa/evidence/latest.json, or null
+ * @returns {string} Markdown
+ */
+export function renderEvidenceBadge(receipt) {
+  const link = "https://github.com/kvdm-co-pilot/create-cmp";
+  const badge = (label, message, color, title) =>
+    `[![${title}](https://img.shields.io/badge/${shieldEscape(label)}-${shieldEscape(message)}-${color})](${link})`;
+
+  if (!receipt || typeof receipt !== "object") {
+    return `${badge("evidence", "none yet", "9E9E9E", "No evidence receipt")} — no verify receipt yet. Run \`node qa/verify.mjs\`.`;
+  }
+
+  const verdict = typeof receipt.verdict === "string" ? receipt.verdict : "?";
+  const mode = receipt.mode === "fast" ? "fast" : "full";
+  const sha = typeof receipt.commit?.sha === "string" ? receipt.commit.sha.slice(0, 7) : null;
+  const dirty = Array.isArray(receipt.commit?.dirty) ? receipt.commit.dirty.length : 0;
+  const when = typeof receipt.generatedAt === "string" ? receipt.generatedAt.slice(0, 10) : null;
+
+  // Provenance is not decoration — it is what keeps the sentence true later.
+  const at = sha ? ` at \`${sha}\`` : "";
+  const on = when ? ` on ${when}` : "";
+  const uncommitted =
+    dirty > 0
+      ? ` The tree had ${dirty} uncommitted file${dirty === 1 ? "" : "s"} at attestation, so this describes that run, not that commit.`
+      : "";
+
+  if (verdict !== "PASS") {
+    return `${badge("evidence", `lane ${verdict}`, "E53935", `Verify lane ${verdict}`)} — the last lane run${at}${on} did not pass. No rung is earned by a failed lane.${uncommitted}`;
+  }
+
+  if (mode === "fast") {
+    // The inner loop is a signal, never evidence. Borrowing the previous
+    // full run's rung here is exactly the lie the ladder exists to prevent.
+    return `${badge("evidence", "fast run, no rung", "9E9E9E", "Fast run — no evidence rung")} — the last run${at}${on} was \`--fast\`: the device and release tiers were skipped, so it earns no rung.${uncommitted} Run \`node qa/verify.mjs\` for evidence.`;
+  }
+
+  const level = receipt.evidenceLevel;
+  if (!level || typeof level.rung !== "string" || typeof level.name !== "string") {
+    return `${badge("evidence", `PASS, rung unrecorded`, "9E9E9E", "Lane PASS, no rung recorded")} — the lane passed${at}${on} but the receipt records no evidence rung.`;
+  }
+
+  const color = RUNG_COLOR[level.rung] || "9E9E9E";
+  const satisfied = Array.isArray(level.satisfiedBy) && level.satisfiedBy.length
+    ? ` Earned by: ${level.satisfiedBy.map((s) => `\`${s}\``).join(", ")}.`
+    : "";
+  return (
+    `${badge("evidence", `${level.rung} ${level.name}`, color, `Evidence ${level.rung} — ${level.name}`)}` +
+    ` — the verify lane passed${at}${on} at rung **${level.rung} · ${level.name}**.` +
+    `${satisfied}${uncommitted}` +
+    ` The rung describes that run; it says nothing about changes made since.`
+  );
+}
+
+/**
+ * Read the project's receipt and rewrite README.md's `cmp:generated evidence`
+ * block from it. Never creates the marker — a project that removed the block
+ * has opted out, and that is honoured silently.
+ *
+ * NOTE the asymmetry with renderEvidenceBadge above: the RENDERER is total —
+ * every receipt, including a `--fast` one, has an honest rendering. The WRITER
+ * is selective: a fast receipt is not written to the README at all. Two
+ * reasons, and the second is the load-bearing one:
+ *   1. The badge reports EVIDENCE. A fast run produces none, so it has nothing
+ *      to say — and overwriting a true statement about a real full-lane run
+ *      with "no rung" loses information rather than adding honesty.
+ *   2. `qa/watch.mjs` runs the fast lane on every save. A writer that fired
+ *      there would rewrite README.md on every keystroke-to-save cycle, putting
+ *      a permanently-dirty file in the inner loop. A recorder must not disturb
+ *      what it records.
+ * The badge therefore always describes the last run that could BEAR evidence,
+ * and says so by naming that run's commit and date.
+ *
+ * @param {string} root project root
+ * @returns {{changed: boolean, reason?: string}}
+ */
+export function updateReadmeBadge(root) {
+  const readmePath = path.join(root, README_REL_PATH);
+  let readme;
+  try {
+    readme = fs.readFileSync(readmePath, "utf8");
+  } catch {
+    return { changed: false, reason: `${README_REL_PATH} not found` };
+  }
+  if (!MARKER_RE.test(readme)) {
+    return { changed: false, reason: `${README_REL_PATH} has no cmp:generated ${BADGE_SECTION_ID} block` };
+  }
+
+  let receipt = null;
+  try {
+    receipt = JSON.parse(fs.readFileSync(path.join(root, "qa", "evidence", "latest.json"), "utf8"));
+  } catch {
+    receipt = null; // no receipt / unreadable → the "none yet" rendering, never a guess
+  }
+
+  if (receipt && receipt.mode === "fast") {
+    return { changed: false, reason: "fast run — the inner loop bears no evidence, so the badge is left as it stands" };
+  }
+
+  const body = `${renderEvidenceBadge(receipt)}\n`;
+  const next = readme.replace(
+    MARKER_RE,
+    () => `<!-- cmp:generated ${BADGE_SECTION_ID} -->\n${body}<!-- /cmp:generated -->`
+  );
+  if (next === readme) return { changed: false };
+  fs.writeFileSync(readmePath, next);
+  return { changed: true };
+}

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