create-cmp-cli 0.11.0 → 0.13.0

package/template/qa/lib/flight-recorder.mjs

@@ -0,0 +1,332 @@
+// flight-recorder.mjs — the lane's append-only journal of its own runs.
+//
+// The retrospective that reshaped this harness was only possible because
+// session transcripts happened to exist. This module removes the "happened
+// to": every verify-lane run appends one JSON line — profile, mode, verdict,
+// evidence rung, per-step verdicts, every SKIP reason VERBATIM, and every
+// degraded-path activation — so "did this project drift from its tooling?"
+// is answerable mechanically (qa/retrospective.mjs), from the repo alone.
+// The SKIP reasons are the signal that matters: they are where a harness
+// quietly stops being used ("no device attached" forever, "maestro not
+// installed" forever) without any single run ever failing.
+//
+// GROUND RULES, each load-bearing:
+//
+//   - IN-REPO ONLY, NO PHONE-HOME. That is a product constraint, not a
+//     preference: the journal is the app's own artifact, and nothing here
+//     records a machine, a hostname, or a user beyond what git itself
+//     already records (the commit sha).
+//
+//   - THE RECORDER MUST NEVER BREAK THE LANE. A recorder that fails the
+//     thing it observes is worse than no recorder: every write is wrapped,
+//     every failure degrades to {ok: false, reason} for the lane to NOTE in
+//     its own output — never to throw, never to change a verdict.
+//
+//   - THE JOURNAL IS COMMITTED, NOT GITIGNORED — deliberately. The console's
+//     Evidence timeline reconstructs history from the git log of committed
+//     receipts; a gitignored journal could answer nothing about the past on
+//     a fresh clone, which is exactly the question this file exists to
+//     answer. It follows qa/evidence/latest.json's precedent: a lane output
+//     that is committed with the change and EXCLUDED from the receipt's
+//     hashed input surface (qa/lib/inputs-hash.mjs), because a lane output
+//     inside the hash would invalidate the very receipt that produced it.
+//
+//   - THE READER STATES ONLY WHAT THE JOURNAL RECORDED. Summaries are
+//     counts and dates, never extrapolation: a short journal says it is
+//     short, a single full run yields no "stretch" arithmetic, and nothing
+//     here editorializes about the developer — the journal records lane
+//     runs, not people.
+//
+// ONE DELIBERATE GAP, stated because a silent one would be a lie: qa/watch.mjs
+// passes `--no-journal`, so save-triggered fast runs are never journaled. The
+// rule it follows is the same one the README evidence badge follows — THE INNER
+// LOOP DOES NOT WRITE TO COMMITTED FILES. A watcher that appended on every save
+// would add hundreds of lines a day to a committed file, turn the app's history
+// into keystroke noise, and leave a permanently-dirty tree inside the very loop
+// this recorder exists to observe. What survives is every full lane and every
+// deliberate fast run — which is what the retrospective's questions actually
+// rest on (SKIP reasons, degraded paths, the longest stretch with no full
+// lane). renderFlightReport states the gap in its own output.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const FLIGHT_JOURNAL_REL_PATH = "qa/flight-recorder.jsonl";
+export const FLIGHT_SCHEMA = "cmp-flight/1";
+
+// Below this many entries the report carries an explicit shortness note —
+// two entries are two facts, not a trend, and the report must say so rather
+// than let a reader infer a pattern from a journal that cannot support one.
+const SHORT_JOURNAL_FLOOR = 5;
+
+/**
+ * Shape one lane run into a journal entry. Pure — verify.mjs passes what it
+ * already computed for the receipt, so the journal can never disagree with
+ * the receipt about the same run.
+ *
+ * @param {object} run
+ * @param {string} run.profile lane profile (scaffold | local | ci | release)
+ * @param {string} run.mode "full" | "fast"
+ * @param {string} run.verdict "PASS" | "FAIL"
+ * @param {{rung: string}|null} run.evidenceLevel the derived rung (or null —
+ *   fast runs and FAILed lanes carry none, and the journal records that
+ *   honestly rather than borrowing a rung from elsewhere)
+ * @param {Array<{name: string, verdict: string, reason?: string}>} run.steps
+ *   the lane's step results, verbatim
+ * @param {string|null} run.sha parent HEAD at run time (null before git init)
+ * @param {number} run.durationMs wall time of the step loop
+ * @param {string[]} run.onDeviceSteps device-tier steps that actually PASSed
+ *   (verify.mjs's own strength derivation — reused, not recomputed, so the
+ *   two can never drift)
+ * @param {string[]} run.degraded degraded-path activations the lane observed
+ *   (self-heals, fallbacks) — each a short verbatim description
+ * @returns {object} one journal entry (JSON-serializable)
+ */
+export function buildFlightEntry({ profile, mode, verdict, evidenceLevel, steps, sha, durationMs, onDeviceSteps, degraded }) {
+  const stepList = Array.isArray(steps) ? steps.filter((s) => s && typeof s.name === "string") : [];
+  return {
+    schema: FLIGHT_SCHEMA,
+    at: new Date().toISOString(),
+    commit: sha ?? null,
+    profile,
+    mode,
+    verdict,
+    evidenceRung: evidenceLevel?.rung ?? null,
+    durationMs,
+    steps: stepList.map((s) => ({ name: s.name, verdict: s.verdict })),
+    // SKIP reasons verbatim — the journal's core signal (see file header).
+    skips: stepList.filter((s) => s.verdict === "SKIP").map((s) => ({ step: s.name, reason: s.reason ?? "" })),
+    deviceSteps: Array.isArray(onDeviceSteps) ? onDeviceSteps : [],
+    degraded: Array.isArray(degraded) ? degraded : [],
+  };
+}
+
+/**
+ * Append one entry to the journal. NEVER throws — a recorder that breaks the
+ * lane is worse than no recorder (see ground rules). The caller is expected
+ * to surface a failed append in the lane's own output.
+ * @param {string} root project root (absolute)
+ * @param {object} entry a buildFlightEntry() result
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function appendFlightRecord(root, entry) {
+  try {
+    const p = path.join(root, FLIGHT_JOURNAL_REL_PATH);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, `${JSON.stringify(entry)}\n`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Read the journal. Absent is not an error — it is the honest "no flight
+ * data recorded yet" state. Unparsable lines are counted, never silently
+ * dropped into the totals: the report must be able to say "N lines could
+ * not be read" instead of quietly under-counting.
+ * @param {string} root project root (absolute)
+ * @returns {{exists: boolean, entries: object[], malformed: number, error?: string}}
+ */
+export function readFlightJournal(root) {
+  const p = path.join(root, FLIGHT_JOURNAL_REL_PATH);
+  if (!fs.existsSync(p)) return { exists: false, entries: [], malformed: 0 };
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (err) {
+    return { exists: true, entries: [], malformed: 0, error: err?.message ?? String(err) };
+  }
+  const entries = [];
+  let malformed = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object") entries.push(parsed);
+      else malformed += 1;
+    } catch {
+      malformed += 1;
+    }
+  }
+  return { exists: true, entries, malformed };
+}
+
+function countBy(entries, keyFn) {
+  const out = new Map();
+  for (const e of entries) {
+    const k = keyFn(e);
+    if (k === undefined || k === null) continue;
+    out.set(k, (out.get(k) ?? 0) + 1);
+  }
+  return out;
+}
+
+function fmtDay(iso) {
+  return typeof iso === "string" ? iso.slice(0, 10) : "unknown";
+}
+
+function fmtGap(ms) {
+  const days = Math.floor(ms / 86_400_000);
+  const hours = Math.round((ms % 86_400_000) / 3_600_000);
+  if (days > 0) return `${days}d ${hours}h`;
+  const mins = Math.round((ms % 3_600_000) / 60_000);
+  return hours > 0 ? `${hours}h ${mins}m` : `${mins}m`;
+}
+
+/**
+ * Summarize journal entries into the facts the retrospective report prints.
+ * Pure arithmetic over recorded entries — no clock reads except the caller-
+ * supplied `now` (used only for the clearly-labeled "as of" distance to the
+ * last full run), no filesystem, no extrapolation.
+ * @param {object[]} entries parsed journal entries, in append (chronological) order
+ * @param {{now?: Date}} [opts]
+ * @returns {object} summary — see the field-by-field construction below
+ */
+export function summarizeFlightJournal(entries, { now = new Date() } = {}) {
+  const runs = entries.filter((e) => e && typeof e === "object");
+  const byMode = countBy(runs, (e) => e.mode ?? "unknown");
+  const byProfile = countBy(runs, (e) => e.profile ?? "unknown");
+  const byVerdict = countBy(runs, (e) => e.verdict ?? "unknown");
+
+  // SKIP reasons, grouped VERBATIM — the reason string is the key on purpose:
+  // paraphrasing or normalizing would erase exactly the signal the journal
+  // exists to keep (two different reasons are two different problems).
+  const skipGroups = new Map();
+  for (const e of runs) {
+    for (const s of Array.isArray(e.skips) ? e.skips : []) {
+      // JSON-array key: reasons are arbitrary text, so a delimiter-joined
+      // string key would be ambiguous — and ambiguity here merges two
+      // different problems into one count.
+      const key = JSON.stringify([s.step ?? "?", s.reason ?? ""]);
+      skipGroups.set(key, (skipGroups.get(key) ?? 0) + 1);
+    }
+  }
+  const skipReasons = [...skipGroups.entries()]
+    .map(([key, count]) => {
+      const [step, reason] = JSON.parse(key);
+      return { step, reason, count };
+    })
+    .sort((a, b) => b.count - a.count || a.step.localeCompare(b.step));
+
+  const degradedGroups = countBy(
+    runs.flatMap((e) => (Array.isArray(e.degraded) ? e.degraded : [])).map((d) => ({ d })),
+    (x) => x.d,
+  );
+
+  const fullRuns = runs.filter((e) => e.mode === "full");
+  const deviceReached = runs.filter((e) => Array.isArray(e.deviceSteps) && e.deviceSteps.length > 0);
+  const rungOrder = { L0: 0, L1: 1, L2: 2, L3: 3 };
+  const highestRung = runs
+    .map((e) => e.evidenceRung)
+    .filter((r) => typeof r === "string" && r in rungOrder)
+    .sort((a, b) => rungOrder[b] - rungOrder[a])[0] ?? null;
+
+  // Longest stretch with no full lane — only computable BETWEEN two recorded
+  // full runs. One full run is a date, not a stretch; the report says so
+  // instead of inventing a gap against "now" or the journal's edges.
+  let longestFullGap = null;
+  for (let i = 1; i < fullRuns.length; i += 1) {
+    const a = Date.parse(fullRuns[i - 1].at);
+    const b = Date.parse(fullRuns[i].at);
+    if (Number.isNaN(a) || Number.isNaN(b)) continue;
+    const gap = b - a;
+    if (!longestFullGap || gap > longestFullGap.ms) {
+      longestFullGap = { ms: gap, from: fullRuns[i - 1].at, to: fullRuns[i].at };
+    }
+  }
+
+  const lastFull = fullRuns.length ? fullRuns[fullRuns.length - 1].at : null;
+  const lastFullAgoMs = lastFull && !Number.isNaN(Date.parse(lastFull)) ? now.getTime() - Date.parse(lastFull) : null;
+
+  return {
+    total: runs.length,
+    span: runs.length ? { from: runs[0].at, to: runs[runs.length - 1].at } : null,
+    short: runs.length > 0 && runs.length < SHORT_JOURNAL_FLOOR,
+    byMode: Object.fromEntries(byMode),
+    byProfile: Object.fromEntries(byProfile),
+    byVerdict: Object.fromEntries(byVerdict),
+    skipReasons,
+    degraded: [...degradedGroups.entries()].map(([what, count]) => ({ what, count })),
+    fullRuns: {
+      count: fullRuns.length,
+      last: lastFull,
+      lastAgoMs: lastFullAgoMs,
+      longestGap: longestFullGap,
+    },
+    device: { reachedRuns: deviceReached.length, highestRung },
+  };
+}
+
+/**
+ * Render the summary as the plain-text report a human reads in ten seconds.
+ * Every line is a recorded fact; the honesty notes (short journal, single
+ * full run, malformed lines) are part of the report, not caveats around it.
+ * @param {object} summary a summarizeFlightJournal() result
+ * @param {{malformed?: number}} [opts]
+ * @returns {string[]} report lines
+ */
+export function renderFlightReport(summary, { malformed = 0 } = {}) {
+  const lines = [];
+  if (summary.total === 0) {
+    lines.push("flight recorder: journal exists but holds no readable entries");
+    if (malformed > 0) lines.push(`  ${malformed} line(s) could not be parsed`);
+    return lines;
+  }
+
+  lines.push(`flight recorder — ${summary.total} lane run(s) recorded (${fmtDay(summary.span.from)} → ${fmtDay(summary.span.to)})`);
+  if (malformed > 0) lines.push(`  ${malformed} line(s) could not be parsed and are not counted`);
+  if (summary.short) {
+    lines.push(`  only ${summary.total} run(s) recorded — the counts below are individual facts, not a trend`);
+  }
+
+  const modeBits = ["full", "fast"].map((m) => `${summary.byMode[m] ?? 0} ${m}`).join(" · ");
+  lines.push(`modes:    ${modeBits}`);
+  // Disclosure, not a footnote: qa/watch.mjs passes --no-journal, so
+  // save-triggered fast runs are deliberately absent (a committed journal must
+  // not grow by hundreds of lines a day, and the inner loop must not leave the
+  // tree dirty). The fast count is therefore DELIBERATE fast runs only, and
+  // saying so here keeps the ratio from being read as a complete census.
+  lines.push("          (fast = deliberate runs only; qa/watch.mjs save-triggered runs are not journaled)");
+  lines.push(`verdicts: ${Object.entries(summary.byVerdict).map(([v, n]) => `${n} ${v}`).join(" · ")}`);
+  lines.push(`profiles: ${Object.entries(summary.byProfile).map(([p, n]) => `${p} ${n}`).join(" · ")}`);
+
+  if (summary.device.reachedRuns > 0) {
+    lines.push(
+      `device tier: reached in ${summary.device.reachedRuns} of ${summary.total} run(s)${summary.device.highestRung ? ` (highest evidence rung recorded: ${summary.device.highestRung})` : ""}`,
+    );
+  } else {
+    lines.push("device tier: never reached in any recorded run (no device-tier step ever PASSed)");
+  }
+
+  if (summary.fullRuns.count === 0) {
+    lines.push("full lane: never recorded — every recorded run was --fast (the inner loop; no run earned evidence)");
+  } else {
+    if (summary.fullRuns.longestGap) {
+      lines.push(
+        `full lane: longest recorded stretch with no full run: ${fmtGap(summary.fullRuns.longestGap.ms)} (${fmtDay(summary.fullRuns.longestGap.from)} → ${fmtDay(summary.fullRuns.longestGap.to)})`,
+      );
+    } else {
+      lines.push(`full lane: one full run recorded (${fmtDay(summary.fullRuns.last)}) — no stretch to measure between full runs`);
+    }
+    if (summary.fullRuns.lastAgoMs !== null) {
+      lines.push(`  last full lane: ${fmtDay(summary.fullRuns.last)} (${fmtGap(summary.fullRuns.lastAgoMs)} before this report)`);
+    }
+  }
+
+  if (summary.skipReasons.length > 0) {
+    lines.push("skip reasons (verbatim, grouped):");
+    for (const s of summary.skipReasons) {
+      lines.push(`  ${s.count}× [${s.step}] ${s.reason.split("\n")[0]}`);
+    }
+  } else {
+    lines.push("skip reasons: none recorded");
+  }
+
+  if (summary.degraded.length > 0) {
+    lines.push("degraded paths activated:");
+    for (const d of summary.degraded) lines.push(`  ${d.count}× ${d.what}`);
+  }
+
+  return lines;
+}

package/template/qa/lib/inputs-hash.mjs

@@ -40,7 +40,22 @@ export const VERIFIED_SURFACE = [
 // snapshot (qa/approvals.json) already carries as state — no lane step reads
 // it, so recording who/why must never invalidate a receipt for a tree whose
 // code did not change (the exact failure FI-8 killed for acceptance).
-const EXCLUDED_PREFIXES = ["qa/evidence", "qa-artifacts", "qa/comments.json", "qa/approvals.log.jsonl"];
+// qa/flight-recorder.jsonl is a lane OUTPUT in the strictest sense: the lane
+// appends one line to it on every run, after the receipt is written — hashing
+// it would make every run invalidate its own receipt. qa/audits.jsonl (the
+// cmp-audit ledger) is read by exactly one lane step (auditCadence), which is
+// a REPORT and can never change the verdict — and recording an audit is
+// bookkeeping about a commit that already happened, so appending a record
+// must never invalidate a receipt for a tree whose code did not change
+// (approvals.log.jsonl's principle, applied to audits).
+const EXCLUDED_PREFIXES = [
+  "qa/evidence",
+  "qa-artifacts",
+  "qa/comments.json",
+  "qa/approvals.log.jsonl",
+  "qa/flight-recorder.jsonl",
+  "qa/audits.jsonl",
+];
 
 // qa/approvals.json is hashed by PROJECTION, not raw bytes. The approvals gate's
 // verdict depends on exactly three row fields (artifact, status, hash) plus the

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

package/template/qa/lib/step-cache.mjs

@@ -0,0 +1,221 @@
+// step-cache.mjs — fast-mode memoization for the lane's pure-Node steps.
+//
+// The steps this serves (specCoverage, approvals, componentStories,
+// reachability, archDoc) are pure functions of files on disk: no Gradle, no
+// git, no network, no clock in the verdict. For those — and ONLY those — a
+// verdict can be safely reused when a content hash of the step's declared
+// input set is unchanged since the last run that produced it.
+//
+// GROUND RULES, each load-bearing:
+//
+//   - THE CACHE IS A CACHE, NEVER EVIDENCE. It lives in the gitignored build
+//     dir (composeApp/build/.cmp-step-cache.json), must never be committed,
+//     and must never be read by qa/receipt-check.mjs or any other receipt
+//     consumer. Deleting it can only cost time, never correctness.
+//
+//   - THE FULL LANE NEVER READS IT. This is deliberate: it keeps the full
+//     lane's integrity property absolute rather than "absolute unless a cache
+//     says otherwise". A full run WRITES entries (so the next fast run
+//     benefits) but always executes every step itself.
+//
+//   - ONLY A CACHED PASS IS EVER REUSED. A cached FAIL is always re-run so
+//     the failure detail is fresh; a cached SKIP is re-derived (these steps
+//     are cheap enough that only the PASS case is worth reusing, and a SKIP's
+//     reason — e.g. which approvals are pending — must stay current).
+//
+//   - THE DECLARED INPUT SET IS THE WHOLE SAFETY ARGUMENT. A step's inputs
+//     must cover everything it reads; a wrong input set is a silently-stale
+//     gate — the worst possible bug this file could host. Callers over-declare
+//     on purpose (a too-broad set only costs cache misses; a too-narrow one
+//     costs truth). The declarations live next to the steps in qa/verify.mjs.
+//
+//   - THE CACHE MUST NEVER BREAK THE LANE. Missing, corrupt, unreadable,
+//     unwritable — every failure mode degrades to "execute the step", never
+//     to an error and never to a reused verdict.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const STEP_CACHE_REL_PATH = "composeApp/build/.cmp-step-cache.json";
+export const STEP_CACHE_SCHEMA = "cmp-step-cache/1";
+
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+/** Every file under `dir` (recursive), absolute paths. Missing dir → []. */
+function walkAllFiles(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkAllFiles(p));
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Content-hash one step's declared input set: sha256 over the sorted list of
+ * `relpath\0bytes` entries. Deterministic: same paths + same bytes → same
+ * hash, independent of declaration order, walk order, and platform separators.
+ * A file appearing, disappearing, moving, or changing content all change the
+ * hash — which is exactly the set of events that can change a pure-Node
+ * step's verdict.
+ *
+ * @param {string} root project root (absolute)
+ * @param {string[]} inputs paths relative to root — each a file or a
+ *   directory (walked recursively). Missing entries contribute nothing (their
+ *   later appearance changes the hash).
+ * @returns {{hash: string, fileCount: number}}
+ */
+export function computeStepInputsHash(root, inputs) {
+  const relFiles = new Set();
+  for (const rel of inputs ?? []) {
+    const abs = path.join(root, rel);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      continue; // absent input — contributes nothing until it exists
+    }
+    if (stat.isFile()) {
+      relFiles.add(toPosix(rel));
+    } else if (stat.isDirectory()) {
+      for (const f of walkAllFiles(abs)) {
+        relFiles.add(toPosix(path.relative(root, f)));
+      }
+    }
+  }
+  // Code-unit sort (default String sort), same stance as inputs-hash.mjs: the
+  // hash depends on iteration order and must be identical on every machine.
+  const sorted = [...relFiles].sort();
+  const overall = createHash("sha256");
+  for (const rel of sorted) {
+    overall.update(rel);
+    overall.update("\0");
+    overall.update(fs.readFileSync(path.join(root, rel)));
+    overall.update("\n");
+  }
+  return { hash: overall.digest("hex"), fileCount: sorted.length };
+}
+
+/**
+ * Load the cache file. Absent, corrupt, or wrong-schema is TOLERATED and
+ * returns an empty cache — a cache that cannot be read is a cache miss,
+ * never an error (see ground rules).
+ * @param {string} root
+ * @returns {{schema: string, steps: Record<string, {inputsHash: string, verdict: string, at: string}>}}
+ */
+export function loadStepCache(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, STEP_CACHE_REL_PATH), "utf8"));
+    if (!parsed || parsed.schema !== STEP_CACHE_SCHEMA || typeof parsed.steps !== "object" || parsed.steps === null || Array.isArray(parsed.steps)) {
+      return { schema: STEP_CACHE_SCHEMA, steps: {} };
+    }
+    return { schema: STEP_CACHE_SCHEMA, steps: parsed.steps };
+  } catch {
+    return { schema: STEP_CACHE_SCHEMA, steps: {} };
+  }
+}
+
+/**
+ * The reuse decision: return the cached entry iff the step's last EXECUTED
+ * verdict was PASS and its inputs hash exactly matches `inputsHash`. A cached
+ * FAIL or SKIP is never reused (re-run so the detail is fresh); a hash
+ * mismatch is a miss; a malformed entry is a miss.
+ * @param {string} root
+ * @param {string} stepName
+ * @param {string} inputsHash
+ * @returns {{inputsHash: string, verdict: string, at: string}|null}
+ */
+export function lookupCachedPass(root, stepName, inputsHash) {
+  const entry = loadStepCache(root).steps[stepName];
+  if (!entry || typeof entry !== "object") return null;
+  if (entry.verdict !== "PASS") return null; // FAIL/SKIP are never reused
+  if (typeof inputsHash !== "string" || entry.inputsHash !== inputsHash) return null;
+  if (typeof entry.at !== "string") return null;
+  return entry;
+}
+
+/**
+ * Record a step's EXECUTED result (any verdict — the entry always reflects
+ * the last real execution; only lookupCachedPass decides reusability).
+ * Write failures are swallowed: an unwritable cache costs the next run time,
+ * never correctness.
+ * @param {string} root
+ * @param {string} stepName
+ * @param {{inputsHash: string, verdict: string, at?: string}} entry
+ */
+export function writeStepCacheEntry(root, stepName, { inputsHash, verdict, at = new Date().toISOString() }) {
+  try {
+    const cache = loadStepCache(root);
+    cache.steps[stepName] = { inputsHash, verdict, at };
+    const p = path.join(root, STEP_CACHE_REL_PATH);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(cache, null, 2)}\n`);
+  } catch {
+    // never a lane failure — see ground rules
+  }
+}
+
+/**
+ * The one memoization flow, shared by every memoized step so the mode rules
+ * cannot drift per step:
+ *
+ *   fast mode:  hash inputs → cached PASS with matching hash → return a
+ *               CACHED result (verdict "CACHED", distinct from PASS so a fast
+ *               receipt can never be mistaken for a fully-executed one);
+ *               otherwise execute, record, return the real result.
+ *   full mode:  ALWAYS execute — the cache is never consulted (the full
+ *               lane's integrity property stays absolute; see ground rules) —
+ *               then record, so the next fast run benefits.
+ *
+ * Any cache-machinery error (hashing, read, write) degrades to plain
+ * execution.
+ *
+ * @param {object} args
+ * @param {boolean} args.fast whether this is a --fast run
+ * @param {string} args.root project root
+ * @param {string} args.stepName the lane step's name (the cache key)
+ * @param {string[]} args.inputs the step's declared input set (see ground rules)
+ * @param {() => object} args.run the real step function
+ * @returns {object} the step result — either `run()`'s verbatim, or a
+ *   `{name, verdict: "CACHED", note, durationMs, details}` reuse marker
+ */
+export function memoizeStep({ fast, root, stepName, inputs, run }) {
+  const started = Date.now();
+  let inputsHash = null;
+  try {
+    // Hashed BEFORE execution so the recorded entry binds the verdict to the
+    // tree the step actually saw, not to edits made while it ran.
+    inputsHash = computeStepInputsHash(root, inputs).hash;
+  } catch {
+    inputsHash = null;
+  }
+
+  if (fast && inputsHash) {
+    const hit = lookupCachedPass(root, stepName, inputsHash);
+    if (hit) {
+      return {
+        name: stepName,
+        verdict: "CACHED",
+        note: `unchanged since ${hit.at}`,
+        durationMs: Date.now() - started,
+        details: { inputsHash },
+      };
+    }
+  }
+
+  const result = run();
+  if (inputsHash && result && typeof result.verdict === "string") {
+    writeStepCacheEntry(root, stepName, { inputsHash, verdict: result.verdict });
+  }
+  return result;
+}