create-cmp-cli 0.12.0 → 0.14.0

package/packages/harness/src/lib/render.mjs

@@ -0,0 +1,254 @@
+// render.mjs — deterministic SVG wireframe of a CMP inspector tree.
+//
+// The "structural twin" of a pixel preview: every node with a non-zero visual
+// footprint becomes a rect; token-annotated nodes are visually distinct and carry
+// a small chip with their resolved values ("radius 16 · pad 16"); clickable nodes
+// get a distinct outline; testTags render as small mono labels; text nodes show
+// their text. An optional a11y audit result overlays violations in a danger style.
+//
+// SVG is structured TEXT, not pixels — safe for model context, works for ANY
+// source (file / live / uiautomator). Output is fully deterministic: no dates,
+// no randomness; the same tree + opts always yields byte-identical SVG.
+//
+// Pure logic only — no fs, no MCP imports; the server wires file I/O around it.
+
+import { walk } from "./tree.mjs";
+
+const FIT_WIDTH = 740; // target drawing width when no explicit scale is given
+const MARGIN = 16;
+const LEGEND_H = 30;
+const FOOTER_H = 24;
+
+const STYLE = {
+  plain: { fill: "none", stroke: "#9CA3AF", strokeWidth: 1, dash: null },
+  tokenized: { fill: "rgba(0,185,107,0.10)", stroke: "#00B96B", strokeWidth: 1.5, dash: null },
+  clickableStroke: "#2563EB",
+  dangerStroke: "#DC2626",
+  chipFill: "#0A2540",
+  chipText: "#FFFFFF",
+  tagText: "#6B7280",
+  nodeText: "#1A1A1A",
+  footerText: "#6B7280",
+};
+
+/**
+ * Render a tree (full {root} document or bare node) as an SVG wireframe string.
+ *
+ * @param {object} tree
+ * @param {object} [opts]
+ * @param {object} [opts.a11y]     an auditA11y() result — its violations are overlaid
+ *                                 in the danger style (matched to nodes by path).
+ * @param {number} [opts.maxDepth] only draw nodes up to this depth (root = 0).
+ * @param {number} [opts.scale]    explicit px scale; default fits root width to ~740.
+ * @returns {string} the SVG document.
+ */
+export function renderTreeSvg(tree, opts = {}) {
+  const root = tree && tree.root ? tree.root : tree;
+  if (!root || typeof root !== "object") {
+    throw new Error("renderTreeSvg: tree has no root node.");
+  }
+  const schemaVersion = (tree && tree.schemaVersion) ?? 1;
+  const source = (tree && tree.source) ?? "unknown";
+
+  const rootW = boundsDim(root.bounds, "width") || 360;
+  const rootH = boundsDim(root.bounds, "height") || 640;
+  const scale = typeof opts.scale === "number" && opts.scale > 0 ? opts.scale : FIT_WIDTH / rootW;
+  const maxDepth =
+    typeof opts.maxDepth === "number" && opts.maxDepth >= 0 ? opts.maxDepth : Infinity;
+
+  // Violations by node path (danger overlay).
+  const violationsByPath = new Map();
+  if (opts.a11y && Array.isArray(opts.a11y.violations)) {
+    for (const v of opts.a11y.violations) {
+      if (!violationsByPath.has(v.path)) violationsByPath.set(v.path, []);
+      violationsByPath.get(v.path).push(v.rule);
+    }
+  }
+
+  const drawW = rootW * scale;
+  const drawH = rootH * scale;
+  const svgW = Math.ceil(drawW + MARGIN * 2);
+  const svgH = Math.ceil(LEGEND_H + drawH + FOOTER_H + MARGIN * 2);
+  const originX = MARGIN;
+  const originY = LEGEND_H + MARGIN / 2;
+
+  let nodeCount = 0;
+  const body = [];
+
+  for (const { node, path } of walk(root)) {
+    nodeCount++;
+    if (depthOf(path) > maxDepth) continue;
+    const b = node.bounds;
+    const w = boundsDim(b, "width");
+    const h = boundsDim(b, "height");
+    if (!(w > 0 && h > 0)) continue; // zero-footprint nodes have nothing to draw
+
+    const x = originX + (b.x || 0) * scale;
+    const y = originY + (b.y || 0) * scale;
+    const sw = w * scale;
+    const sh = h * scale;
+    const tokenized = node.designToken != null;
+    const clickable = node.clickable === true;
+    const rules = violationsByPath.get(path);
+
+    const base = tokenized ? STYLE.tokenized : STYLE.plain;
+    body.push(
+      `<rect x="${fmt(x)}" y="${fmt(y)}" width="${fmt(sw)}" height="${fmt(sh)}" ` +
+        `fill="${base.fill}" stroke="${base.stroke}" stroke-width="${base.strokeWidth}"` +
+        `${tokenized ? ` class="tokenized"` : ""} data-path="${esc(path)}"/>`
+    );
+    if (clickable) {
+      // Distinct clickable outline, drawn just inside the node rect.
+      body.push(
+        `<rect x="${fmt(x + 1.5)}" y="${fmt(y + 1.5)}" width="${fmt(Math.max(sw - 3, 1))}" ` +
+          `height="${fmt(Math.max(sh - 3, 1))}" fill="none" stroke="${STYLE.clickableStroke}" ` +
+          `stroke-width="2" stroke-dasharray="5 3" class="clickable"/>`
+      );
+    }
+    if (rules && rules.length > 0) {
+      // Danger overlay + rule label for a11y violations.
+      body.push(
+        `<rect x="${fmt(x - 2)}" y="${fmt(y - 2)}" width="${fmt(sw + 4)}" height="${fmt(sh + 4)}" ` +
+          `fill="rgba(220,38,38,0.08)" stroke="${STYLE.dangerStroke}" stroke-width="2" class="a11y-violation"/>`
+      );
+      body.push(
+        `<text x="${fmt(x)}" y="${fmt(y - 4)}" font-family="monospace" font-size="8" ` +
+          `fill="${STYLE.dangerStroke}" class="a11y-label">! ${esc([...rules].sort().join(", "))}</text>`
+      );
+    }
+    if (node.testTag) {
+      body.push(
+        `<text x="${fmt(x + 3)}" y="${fmt(y + 9)}" font-family="monospace" font-size="8" ` +
+          `fill="${STYLE.tagText}" class="test-tag">${esc(node.testTag)}</text>`
+      );
+    }
+    if (node.text) {
+      body.push(
+        `<text x="${fmt(x + 3)}" y="${fmt(y + sh / 2 + 3)}" font-family="sans-serif" font-size="10" ` +
+          `fill="${STYLE.nodeText}" class="node-text">${esc(truncate(node.text, 48))}</text>`
+      );
+    }
+    if (tokenized) {
+      const chip = tokenChip(node.designToken);
+      if (chip) {
+        const chipW = chip.length * 4.6 + 8;
+        const chipY = y + sh - 12;
+        body.push(
+          `<rect x="${fmt(x + 2)}" y="${fmt(chipY)}" width="${fmt(chipW)}" height="11" rx="5" ` +
+            `fill="${STYLE.chipFill}" opacity="0.85" class="token-chip"/>`
+        );
+        body.push(
+          `<text x="${fmt(x + 6)}" y="${fmt(chipY + 8.5)}" font-family="monospace" font-size="7.5" ` +
+            `fill="${STYLE.chipText}" class="token-chip-text">${esc(chip)}</text>`
+        );
+      }
+    }
+  }
+
+  const legend = legendRow(opts.a11y != null);
+  const footer =
+    `<text x="${MARGIN}" y="${svgH - 8}" font-family="monospace" font-size="10" ` +
+    `fill="${STYLE.footerText}" class="footer">${nodeCount} nodes · ${esc(source)} · schemaVersion ${schemaVersion}</text>`;
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">`,
+    `<rect x="0" y="0" width="${svgW}" height="${svgH}" fill="#F7F9FC"/>`,
+    legend,
+    ...body,
+    footer,
+    `</svg>`,
+    ``,
+  ].join("\n");
+}
+
+// --- helpers ----------------------------------------------------------------
+
+// Legend row across the top: what each visual style means.
+function legendRow(withA11y) {
+  const items = [];
+  let x = MARGIN;
+  const y = 8;
+  const swatch = (fill, stroke, dash, label, cls) => {
+    const parts = [
+      `<rect x="${fmt(x)}" y="${y}" width="14" height="10" fill="${fill}" stroke="${stroke}" ` +
+        `stroke-width="1.5"${dash ? ` stroke-dasharray="${dash}"` : ""} class="legend-${cls}"/>`,
+      `<text x="${fmt(x + 18)}" y="${y + 9}" font-family="sans-serif" font-size="9" fill="#1A1A1A">${label}</text>`,
+    ];
+    x += 18 + label.length * 5.2 + 14;
+    items.push(...parts);
+  };
+  swatch("none", STYLE.plain.stroke, null, "node", "node");
+  swatch(STYLE.tokenized.fill, STYLE.tokenized.stroke, null, "tokenized", "tokenized");
+  swatch("none", STYLE.clickableStroke, "5 3", "clickable", "clickable");
+  if (withA11y) swatch("rgba(220,38,38,0.08)", STYLE.dangerStroke, null, "a11y violation", "a11y");
+  return `<g class="legend">${items.join("")}</g>`;
+}
+
+// "radius 16 · pad 16" — compact resolved-values chip, sorted keys for determinism.
+function tokenChip(dt) {
+  if (!dt || !dt.resolved || typeof dt.resolved !== "object") return null;
+  const keys = Object.keys(dt.resolved).sort();
+  if (keys.length === 0) return null;
+  const parts = keys.map((k) => {
+    const v = String(dt.resolved[k]).replace(/(dp|sp)$/i, "");
+    return `${abbrev(k)} ${v}`.trim();
+  });
+  return truncate(parts.join(" · "), 64);
+}
+
+const ABBREV = {
+  padding: "pad",
+  elevation: "elev",
+  fontSize: "font",
+  height: "h",
+  width: "w",
+  statusBarPadding: "statusBar",
+  navBarPadding: "navBar",
+};
+function abbrev(key) {
+  return ABBREV[key] ?? key;
+}
+
+function depthOf(path) {
+  return (path.match(/\.children\[/g) || []).length;
+}
+
+function boundsDim(b, key) {
+  return b && typeof b[key] === "number" ? b[key] : 0;
+}
+
+function fmt(n) {
+  // Fixed one-decimal formatting: deterministic and diff-friendly.
+  return (Math.round(n * 10) / 10).toString();
+}
+
+function truncate(s, max) {
+  const str = String(s);
+  return str.length <= max ? str : str.slice(0, max - 1) + "…";
+}
+
+function esc(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Count the nodes renderTreeSvg would draw as rects (non-zero footprint within
+ * maxDepth) plus the total node count — used by the tool result.
+ */
+export function countRenderable(tree, opts = {}) {
+  const root = tree && tree.root ? tree.root : tree;
+  const maxDepth =
+    typeof opts.maxDepth === "number" && opts.maxDepth >= 0 ? opts.maxDepth : Infinity;
+  let total = 0;
+  let drawn = 0;
+  for (const { node, path } of walk(root)) {
+    total++;
+    if (depthOf(path) > maxDepth) continue;
+    if (boundsDim(node.bounds, "width") > 0 && boundsDim(node.bounds, "height") > 0) drawn++;
+  }
+  return { total, drawn };
+}

package/packages/harness/src/lib/spec-coverage.mjs

@@ -0,0 +1,131 @@
+// spec-coverage.mjs — the clause ↔ citation scan, as a library.
+//
+// Extracted from qa/verify.mjs's stepSpecCoverage so there is exactly ONE
+// definition of "what is a clause" and "what cites it". Two consumers:
+//   - the lane's specCoverage gate (orphans in either direction FAIL)
+//   - feature-brief.mjs's derived doneness (a feature is done when every live
+//     clause in ITS spec is cited and the receipt attests the tree)
+// If these two scanned differently, the Features view and the lane could
+// disagree about the same clause — the exact two-truths problem this file
+// exists to prevent.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** `- **HOME-01** — …` (live) or `- ~~**HOME-01**~~ — …` (withdrawn). */
+export const CLAUSE_LINE_RE = /^-\s+(~~)?\*\*([A-Z][A-Z0-9]*-\d{2,})\*\*/;
+
+const TAG_LINE_RE = /^(?:\/\/|#)\s*SPEC:/;
+const TAG_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
+const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
+
+/** Recursive walk returning files under `dir` ending in one of `exts`. */
+export function walkFiles(dir, exts) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(p, exts));
+    else if (exts.some((ext) => entry.name.endsWith(ext))) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every clause in every specs/*.spec.md.
+ * @param {string} root
+ * @returns {Map<string, {file: string, withdrawn: boolean}>} id -> where/state
+ */
+export function scanSpecClauses(root) {
+  const clauses = new Map();
+  const specsDir = path.join(root, "specs");
+  if (!fs.existsSync(specsDir)) return clauses;
+  for (const f of fs.readdirSync(specsDir).filter((n) => n.endsWith(".spec.md"))) {
+    const abs = path.join(specsDir, f);
+    for (const line of fs.readFileSync(abs, "utf8").split("\n")) {
+      const m = line.match(CLAUSE_LINE_RE);
+      if (!m) continue;
+      clauses.set(m[2], { file: path.relative(root, abs), withdrawn: Boolean(m[1]) });
+    }
+  }
+  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. Each entry carries the citing file's `tier` (see tierForFile).
+ * @param {string} root
+ * @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) => {
+        const trimmed = line.trim();
+        if (!TAG_LINE_RE.test(trimmed)) return;
+        const m = trimmed.match(TAG_IDS_RE);
+        if (!m) return;
+        const ids = m[1]
+          .split(/[,\s]+/)
+          .map((s) => s.trim())
+          .filter((s) => CLAUSE_ID_RE.test(s));
+        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/packages/harness/src/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;
+}