create-cmp-cli 0.12.0 → 0.13.0

package/template/qa/lib/determinism.mjs

@@ -0,0 +1,179 @@
+// determinism.mjs — the comparison half of the lane's determinism probe.
+//
+// ARCH-13 statically bans ambient time reads (Clock.System, LocalDate.now,
+// TimeZone.currentSystemDefault) in APP code — but a library the app calls
+// can still read the wall clock, and a golden test can still depend on the
+// machine's timezone through a seam the static net cannot see. This project
+// family has already been bitten: a golden tree green at 23:00 and red by
+// morning, because a ViewModel was constructed without its injected clock.
+//
+// The probe (verify.mjs stepDeterminism) runs the JVM test tier TWICE under
+// maximally-shifted timezones and fails iff the two runs' OUTCOMES differ.
+// This module owns the two judgments that make that comparison honest:
+//
+//   - WHAT COUNTS AS AN OUTCOME: a test's verdict (pass/fail/error/skip)
+//     and its failure output — never its duration. Durations are not parsed
+//     at all, so a timing wobble is structurally incapable of tripping the
+//     probe (the brief-level rule "duration is not a difference" is enforced
+//     by construction, not by filtering).
+//
+//   - WHAT THE FAILURE MESSAGE MUST SAY: which test, which lane step owns
+//     it, and the observable difference between the two runs — never a bare
+//     "nondeterministic". A probe whose red is unactionable just teaches
+//     people to turn it off.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The two probe timezones — chosen so the two legs NEVER share a calendar
+ * date, at any instant:
+ *
+ *   Etc/GMT+12 = UTC-12  (POSIX sign convention: Etc/GMT+N means UTC-N)
+ *   Etc/GMT-14 = UTC+14  (the highest real-world offset, Line Islands)
+ *
+ * The offsets are 26 hours apart — more than a full day — so the two legs'
+ * local dates differ at EVERY moment of every day, and any date-derived
+ * value (a "today" default, a day-boundary bucket, a formatted date in a
+ * golden tree) is guaranteed to differ between the legs. A UTC-vs-UTC+14
+ * pair would NOT have this property: those legs share a date for ten hours
+ * of every day, so the probe's power would depend on what time you ran it —
+ * the exact class of flakiness it exists to hunt.
+ */
+export const DETERMINISM_TIMEZONES = [
+  { tz: "Etc/GMT+12", label: "UTC-12" },
+  { tz: "Etc/GMT-14", label: "UTC+14" },
+];
+
+const XML_ENTITIES = { "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&amp;": "&" };
+
+function unescapeXml(s) {
+  return s
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+    .replace(/&(lt|gt|quot|apos|amp);/g, (m) => XML_ENTITIES[m]);
+}
+
+function attr(attrs, name) {
+  const m = attrs.match(new RegExp(`${name}="([^"]*)"`));
+  return m ? unescapeXml(m[1]) : null;
+}
+
+/**
+ * Parse one Gradle JUnit results directory into per-test outcomes.
+ * DELIBERATELY parses only verdict-bearing content: testcase identity,
+ * status, and failure/error text. `time="…"` attributes are never read, so
+ * two runs that differ only in duration produce identical outcome maps.
+ *
+ * @param {string} dir a test-results directory (TEST-*.xml files, flat)
+ * @returns {Record<string, {status: "pass"|"fail"|"error"|"skip", messages: string[]}>}
+ *   keyed by `classname.name`; empty object when the directory is absent
+ *   (the caller decides what an empty leg means — this parser never guesses)
+ */
+export function parseJUnitOutcomes(dir) {
+  const outcomes = {};
+  if (!fs.existsSync(dir)) return outcomes;
+  for (const entry of fs.readdirSync(dir)) {
+    if (!entry.startsWith("TEST-") || !entry.endsWith(".xml")) continue;
+    const xml = fs.readFileSync(path.join(dir, entry), "utf8");
+    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+    for (const m of xml.matchAll(caseRe)) {
+      const attrs = m[1];
+      const body = m[2] ?? "";
+      const classname = attr(attrs, "classname") ?? "";
+      const name = attr(attrs, "name") ?? "";
+      if (!classname && !name) continue;
+      let status = "pass";
+      const messages = [];
+      const childRe = /<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/g;
+      for (const c of body.matchAll(childRe)) {
+        status = c[1] === "error" ? "error" : "fail";
+        const message = attr(c[2], "message");
+        const text = c[3] ? unescapeXml(c[3]).trim() : "";
+        messages.push(message ?? text.split("\n")[0] ?? "");
+      }
+      if (status === "pass" && /<skipped\b/.test(body)) status = "skip";
+      outcomes[`${classname}.${name}`] = { status, messages };
+    }
+  }
+  return outcomes;
+}
+
+/**
+ * Which lane step owns a test class — so the probe's failure message names
+ * the step a reader would re-run, not just a class name. The patterns are
+ * the same filters the lane's own gradleTestStep calls use.
+ * @param {string} classname fully-qualified test class
+ * @returns {"goldenTrees"|"conformance"|"a11y"|"unitTests"}
+ */
+export function laneStepForTestClass(classname) {
+  if (/GoldenTreeTest$/.test(classname)) return "goldenTrees";
+  if (/ArchitectureConformanceTest$/.test(classname)) return "conformance";
+  if (/A11yConformanceTest$/.test(classname)) return "a11y";
+  return "unitTests";
+}
+
+function classnameOf(testId) {
+  // testId is `classname.name`; the class is everything before the last dot
+  // segment that starts the (possibly backticked, space-bearing) test name.
+  // Kotlin test names contain dots rarely but spaces often — the classname
+  // never contains a space, so split at the first segment containing one,
+  // falling back to the last dot.
+  const spaceIdx = testId.indexOf(" ");
+  const scope = spaceIdx === -1 ? testId : testId.slice(0, spaceIdx);
+  const lastDot = scope.lastIndexOf(".");
+  return lastDot === -1 ? testId : testId.slice(0, lastDot);
+}
+
+/**
+ * Compare two legs' outcomes. Returns one entry per observable difference,
+ * each carrying everything the failure message must name: the test, the
+ * owning lane step, and what differed between the legs.
+ *
+ * Kinds:
+ *   verdict-flip           different status (pass/fail/error/skip)
+ *   only-in-one-leg        the test executed in one leg only
+ *   failure-text-changed   failed in BOTH legs, but with different output —
+ *                          a date-dependent assertion message is still a
+ *                          timezone leak even when both legs are red
+ *
+ * @param {Record<string, {status: string, messages: string[]}>} a leg A outcomes
+ * @param {Record<string, {status: string, messages: string[]}>} b leg B outcomes
+ * @param {string} labelA human label for leg A (e.g. "TZ=Etc/GMT+12 (UTC-12)")
+ * @param {string} labelB human label for leg B
+ * @returns {Array<{test: string, step: string, kind: string, detail: string}>}
+ */
+export function compareOutcomes(a, b, labelA, labelB) {
+  const diffs = [];
+  const ids = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  for (const id of ids) {
+    const step = laneStepForTestClass(classnameOf(id));
+    const inA = a[id];
+    const inB = b[id];
+    if (!inA || !inB) {
+      const where = inA ? labelA : labelB;
+      const missing = inA ? labelB : labelA;
+      diffs.push({ test: id, step, kind: "only-in-one-leg", detail: `executed under ${where} but produced no result under ${missing}` });
+      continue;
+    }
+    if (inA.status !== inB.status) {
+      const firstLine = (inA.status === "pass" ? inB : inA).messages[0]?.split("\n")[0] ?? "";
+      diffs.push({
+        test: id,
+        step,
+        kind: "verdict-flip",
+        detail: `${inA.status.toUpperCase()} under ${labelA}, ${inB.status.toUpperCase()} under ${labelB}${firstLine ? `: ${firstLine}` : ""}`,
+      });
+      continue;
+    }
+    if (inA.status !== "pass" && inA.messages.join("\n") !== inB.messages.join("\n")) {
+      diffs.push({
+        test: id,
+        step,
+        kind: "failure-text-changed",
+        detail: `failed under both, with different output — ${labelA}: "${inA.messages[0]?.split("\n")[0] ?? ""}" vs ${labelB}: "${inB.messages[0]?.split("\n")[0] ?? ""}"`,
+      });
+    }
+  }
+  return diffs;
+}

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