create-cmp-cli 0.12.0 → 0.14.0

package/template/README.md

@@ -1,5 +1,9 @@
 # __APP_NAME__
 
+<!-- cmp:generated evidence -->
+[![No evidence receipt](https://img.shields.io/badge/evidence-none_yet-9E9E9E)](https://github.com/kvdm-co-pilot/create-cmp) — no verify receipt yet. Run `node qa/verify.mjs`.
+<!-- /cmp:generated -->
+
 A Kotlin / Compose Multiplatform app, generated by
 [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a **verification harness**:
 the architecture, testing conventions, and definition of done are enforced mechanically, not

package/template/gitignore

@@ -26,3 +26,11 @@ iosApp/*.xcworkspace/
 iosApp/build/
 xcuserdata/
 *.xcuserstate
+
+# `create-cmp upgrade`'s pre-write backups. In a git repo the previous commit IS
+# the backup, so these are redundant the moment they are created — and committing
+# them alongside the upgrade puts a stale copy of every touched file in history.
+# Kept on disk (an upgrade run in a dirty or non-git tree still needs them),
+# ignored by git. Delete them once you have reviewed the upgrade's diff.
+*.bak-upgrade
+*.cmp-new

package/template/qa/lib/audit-cadence.mjs

@@ -0,0 +1,290 @@
+// audit-cadence.mjs — the mechanical nudge that keeps cmp-audit from
+// depending on someone remembering.
+//
+// The adversarial platform-semantics audit (the cmp-audit skill) found six
+// latent defects on its first real outing — and it only ran because a human
+// happened to ask. This module is the cheapest honest replacement for that
+// memory: the release profile's receipt lists which androidMain subsystems
+// changed since their last RECORDED audit, so the ship-time surface itself
+// says "these platform seams moved and nobody has interrogated them since".
+//
+// It is a REPORT, never a gate. Audit debt is a judgment call (a one-line
+// rename is not six latent defects), so this file computes facts and the
+// human decides — a FAIL here would train people to game the ledger, which
+// would destroy the only thing it has: honesty.
+//
+// The ledger (qa/audits.jsonl) is append-only, one JSON object per line:
+// subsystem, the commit sha the audit ran against, an ISO timestamp, and who
+// or what recorded it. Recording is a CLAIM — "this subsystem, as of this
+// commit, was audited" — so recordAudit() derives the sha from HEAD itself
+// and refuses to record when the subsystem's files differ from HEAD: a
+// record claiming a commit the audited bytes did not match would be the
+// exact dishonesty the whole harness exists to prevent.
+//
+// "Subsystem" is DERIVED, never configured: the immediate package directory
+// under the app's androidMain Kotlin source root (the root is resolved from
+// the android namespace in composeApp/build.gradle.kts). This template is
+// stamped into apps whose package names it cannot know; deriving from the
+// tree is the only definition that survives that. Kotlin files sitting
+// directly at the package root belong to no package directory and are
+// reported under the literal name "(root)" rather than invented into one.
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export const AUDITS_REL_PATH = "qa/audits.jsonl";
+export const AUDIT_RECORD_SCHEMA = "cmp-audit-record/1";
+
+/** The pseudo-subsystem for Kotlin files directly at the androidMain package root. */
+export const ROOT_SUBSYSTEM = "(root)";
+
+function tryGit(root, cmd) {
+  try {
+    return execSync(`git ${cmd}`, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function tryGitLines(root, cmd) {
+  try {
+    const out = execSync(`git ${cmd}`, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.replace(/\n+$/, "").split("\n").filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the androidMain Kotlin package root for this app, relative to the
+ * project root — derived from the android `namespace` (falling back to
+ * `applicationId`) in composeApp/build.gradle.kts, never hardcoded.
+ * @param {string} root project root (absolute)
+ * @returns {{ok: true, rel: string}|{ok: false, reason: string}}
+ */
+export function androidMainPackageRoot(root) {
+  let gradle;
+  try {
+    gradle = fs.readFileSync(path.join(root, "composeApp", "build.gradle.kts"), "utf8");
+  } catch {
+    return { ok: false, reason: "composeApp/build.gradle.kts not readable — cannot derive the app package" };
+  }
+  const pkg = gradle.match(/namespace\s*=\s*"([^"]+)"/)?.[1] ?? gradle.match(/applicationId\s*=\s*"([^"]+)"/)?.[1];
+  if (!pkg) {
+    return { ok: false, reason: "no android namespace/applicationId in composeApp/build.gradle.kts — cannot derive the app package" };
+  }
+  const rel = path.posix.join("composeApp/src/androidMain/kotlin", ...pkg.split("."));
+  if (!fs.existsSync(path.join(root, rel))) {
+    return { ok: false, reason: `androidMain has no Kotlin sources under the app package (${rel} absent)` };
+  }
+  return { ok: true, rel };
+}
+
+/**
+ * List this app's androidMain subsystems: the immediate directories under
+ * the package root (sorted), plus ROOT_SUBSYSTEM when Kotlin files sit
+ * directly at the root.
+ * @param {string} root project root (absolute)
+ * @param {string} pkgRootRel from androidMainPackageRoot()
+ * @returns {string[]}
+ */
+export function listSubsystems(root, pkgRootRel) {
+  const abs = path.join(root, pkgRootRel);
+  let entries;
+  try {
+    entries = fs.readdirSync(abs, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const names = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  if (entries.some((e) => e.isFile() && e.name.endsWith(".kt"))) names.push(ROOT_SUBSYSTEM);
+  return names;
+}
+
+/**
+ * Read the audit ledger. Absent is the honest "no audit ever recorded"
+ * state; malformed lines are counted, never silently dropped — the report
+ * says how many records it could not read instead of under-counting audits.
+ * @param {string} root project root (absolute)
+ * @returns {{entries: Array<{subsystem: string, sha: string, at: string, by: string}>, malformed: number}}
+ */
+export function readAuditLedger(root) {
+  const p = path.join(root, AUDITS_REL_PATH);
+  if (!fs.existsSync(p)) return { entries: [], malformed: 0 };
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch {
+    return { entries: [], malformed: 0 };
+  }
+  const entries = [];
+  let malformed = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e === "object" && typeof e.subsystem === "string" && typeof e.sha === "string") entries.push(e);
+      else malformed += 1;
+    } catch {
+      malformed += 1;
+    }
+  }
+  return { entries, malformed };
+}
+
+/**
+ * Record an audit claim: append {subsystem, sha: HEAD, at, by} to the
+ * ledger. Honesty guards, each a refusal rather than a fabrication:
+ *   - no git HEAD → refused (a claim about no commit is not a claim);
+ *   - unknown subsystem → refused, naming the derived ones;
+ *   - the subsystem's files differ from HEAD → refused (the record would
+ *     claim HEAD while the audited bytes are something else — commit first).
+ * @param {string} root project root (absolute)
+ * @param {{subsystem: string, by?: string}} claim
+ * @returns {{ok: true, sha: string, entry: object}|{ok: false, reason: string}}
+ */
+export function recordAudit(root, { subsystem, by }) {
+  const sha = tryGit(root, "rev-parse HEAD");
+  if (!sha) {
+    return { ok: false, reason: "no git history — an audit record is a claim about a specific commit, and there is none to claim against. Commit first." };
+  }
+  const pkgRoot = androidMainPackageRoot(root);
+  if (!pkgRoot.ok) return { ok: false, reason: pkgRoot.reason };
+  const known = listSubsystems(root, pkgRoot.rel);
+  if (!known.includes(subsystem)) {
+    return { ok: false, reason: `unknown subsystem "${subsystem}" — derived subsystems under ${pkgRoot.rel}: ${known.join(", ") || "(none)"}` };
+  }
+  const scope = subsystem === ROOT_SUBSYSTEM ? pkgRoot.rel : path.posix.join(pkgRoot.rel, subsystem);
+  const dirty = tryGitLines(root, `status --porcelain -- "${scope}"`) ?? [];
+  // For "(root)" the porcelain scope is the whole package root; narrow to
+  // files directly at the root so a dirty subsystem dir doesn't block a
+  // root-level record it has nothing to do with.
+  const relevantDirty =
+    subsystem === ROOT_SUBSYSTEM
+      ? dirty.filter((l) => {
+          const rel = l.slice(3).trim();
+          return path.posix.dirname(rel) === pkgRoot.rel;
+        })
+      : dirty;
+  if (relevantDirty.length > 0) {
+    return {
+      ok: false,
+      reason: `uncommitted changes under ${scope} — the record would claim commit ${sha.slice(0, 7)} but the audited files are not that commit. Commit (or revert) first, then record.`,
+    };
+  }
+  const entry = {
+    schema: AUDIT_RECORD_SCHEMA,
+    subsystem,
+    sha,
+    at: new Date().toISOString(),
+    by: by || tryGit(root, "config user.name") || "unknown",
+  };
+  const p = path.join(root, AUDITS_REL_PATH);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, `${JSON.stringify(entry)}\n`);
+  return { ok: true, sha, entry };
+}
+
+/**
+ * The report itself: for every derived subsystem, what the ledger claims
+ * and what git says moved since that claim.
+ *
+ * Statuses, each phrased so the receipt can print the line verbatim:
+ *   never-audited   no ledger entry — says exactly that, implies no staleness
+ *   changed         androidMain files under it changed between the audited
+ *                   sha and HEAD (committed changes only — sha vs HEAD is
+ *                   the honest comparison; the working tree is not history)
+ *   unchanged       no committed change since the audited sha
+ *   unknown-commit  the ledger names a sha this repo's history does not
+ *                   contain — drift cannot be measured, and the report says
+ *                   so instead of guessing
+ *
+ * @param {string} root project root (absolute)
+ * @returns {{ok: false, reason: string}|{ok: true, packageRoot: string,
+ *   subsystems: Array<{name: string, status: string, audit: object|null, changedFiles: number}>,
+ *   lines: string[], summary: string, malformed: number}}
+ */
+export function evaluateAuditCadence(root) {
+  if (!tryGit(root, "rev-parse HEAD")) {
+    // No git history: "changed since the last audit" has no meaning yet.
+    // Report NOTHING rather than guessing — an invented staleness signal
+    // would be worse than none.
+    return { ok: false, reason: "no git history — changed-since-audit cannot be measured" };
+  }
+  const pkgRoot = androidMainPackageRoot(root);
+  if (!pkgRoot.ok) return { ok: false, reason: pkgRoot.reason };
+  const subsystems = listSubsystems(root, pkgRoot.rel);
+  if (subsystems.length === 0) {
+    return { ok: false, reason: `no subsystems under ${pkgRoot.rel} — nothing to report` };
+  }
+
+  const { entries, malformed } = readAuditLedger(root);
+  // Last entry per subsystem wins: the ledger is append-only, so file order
+  // IS chronological order — trusted over the `at` timestamps, which are
+  // claims a machine's clock made, not facts git can vouch for.
+  const latest = new Map();
+  for (const e of entries) latest.set(e.subsystem, e);
+
+  const gitTop = tryGit(root, "rev-parse --show-toplevel");
+  // Realpath both sides before re-anchoring diff paths: git reports the
+  // toplevel with symlinks resolved (macOS: /var/… vs /private/var/…), and a
+  // mismatch here would silently mis-attribute every changed file.
+  let rootReal = root;
+  try {
+    rootReal = fs.realpathSync(root);
+  } catch {
+    rootReal = root;
+  }
+  const results = [];
+  const lines = [];
+  for (const name of subsystems) {
+    const audit = latest.get(name) ?? null;
+    if (!audit) {
+      results.push({ name, status: "never-audited", audit: null, changedFiles: 0 });
+      lines.push(`no audit recorded for ${name} — when it gets one (cmp-audit ${name}), record it: node qa/record-audit.mjs ${JSON.stringify(name)}`);
+      continue;
+    }
+    // A ledger sha is a CLAIM read from a file — validate its shape before it
+    // touches a shell, and resolve it against history before trusting it.
+    const shaShapeOk = typeof audit.sha === "string" && /^[0-9a-f]{4,40}$/i.test(audit.sha);
+    const shaKnown = shaShapeOk && Boolean(tryGit(root, `rev-parse --verify --quiet "${audit.sha}^{commit}"`));
+    if (!shaKnown) {
+      results.push({ name, status: "unknown-commit", audit, changedFiles: 0 });
+      lines.push(`${name}: last audit (${fmtWhen(audit)}) was recorded against ${audit.sha.slice(0, 12)}, which is not in this repo's history — drift since it cannot be measured`);
+      continue;
+    }
+    const scope = name === ROOT_SUBSYSTEM ? pkgRoot.rel : path.posix.join(pkgRoot.rel, name);
+    const changedRaw = tryGitLines(root, `diff --name-only ${audit.sha} HEAD -- "${scope}"`) ?? [];
+    // Diff paths come back relative to the git toplevel, which may sit above
+    // the project root; re-anchor before subsystem attribution.
+    const changed = changedRaw
+      .map((rel) => (gitTop ? path.relative(rootReal, path.resolve(gitTop, rel)).split(path.sep).join("/") : rel))
+      .filter((rel) => (name === ROOT_SUBSYSTEM ? path.posix.dirname(rel) === pkgRoot.rel : true));
+    if (changed.length > 0) {
+      results.push({ name, status: "changed", audit, changedFiles: changed.length });
+      lines.push(
+        `${name}: ${changed.length} androidMain file(s) changed since its last recorded audit (${audit.sha.slice(0, 7)}, ${fmtWhen(audit)}) — audit it (cmp-audit ${name}), then record: node qa/record-audit.mjs ${JSON.stringify(name)}`,
+      );
+    } else {
+      results.push({ name, status: "unchanged", audit, changedFiles: 0 });
+    }
+  }
+
+  const changedCount = results.filter((r) => r.status === "changed").length;
+  const neverCount = results.filter((r) => r.status === "never-audited").length;
+  const unchangedCount = results.filter((r) => r.status === "unchanged").length;
+  if (unchangedCount > 0) {
+    lines.push(`${unchangedCount} subsystem(s) unchanged since their last recorded audit: ${results.filter((r) => r.status === "unchanged").map((r) => r.name).join(", ")}`);
+  }
+  if (malformed > 0) {
+    lines.push(`${malformed} ledger line(s) in ${AUDITS_REL_PATH} could not be parsed and are not counted`);
+  }
+  const summary = `${changedCount} changed since audit · ${neverCount} never audited · ${unchangedCount} unchanged`;
+
+  return { ok: true, packageRoot: pkgRoot.rel, subsystems: results, lines, summary, malformed };
+}
+
+function fmtWhen(audit) {
+  return typeof audit.at === "string" ? audit.at.slice(0, 10) : "undated";
+}

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