create-cmp-cli 0.12.0 → 0.13.0

package/src/lib/harness-upgrade.mjs

@@ -0,0 +1,364 @@
+// Core logic for `create-cmp upgrade --harness`: refresh the ENGINE-OWNED
+// files of a stamped app after the engine improved.
+//
+// WHY: `create-cmp` stamps an app from template/ and walks away. When the
+// engine later fixes a stamped file (a verify-lane bug, a Gradle wiring fix,
+// a new hook), apps stamped from the OLD engine never receive it — the dead
+// androidDebug/AndroidManifest.xml fixed at engine commit b972c19 was carried
+// by every app this template ever stamped. This module closes that gap with a
+// three-way merge, exactly like dpkg conffile handling or a Yeoman
+// regeneration:
+//
+//   base   = what the engine WOULD have stamped at the version this app was
+//            stamped from (old template + CURRENT stamp pipeline — see below)
+//   new    = what the CURRENT engine stamps
+//   theirs = the app's working tree today
+//
+// Both base and new are produced by stamping with the app's OWN recorded
+// config (create-cmp.json), so tokens (package, app name, theme prefix)
+// resolve identically and every base→new diff is pure engine change.
+//
+// NOTE on the base approximation: base is "old template + current pipeline".
+// When the stamp PIPELINE itself changed between versions (tokenization,
+// marker stripping), base can differ from what the old engine literally
+// produced. This is deliberate — running old engine code against a current
+// config is strictly worse — and only affects files whose tokenization
+// changed; those surface as conflicts rather than silent clobbers.
+//
+// App-authored files (the app's own feature screens) appear in neither base
+// nor new, so they are INVISIBLE to this sweep — by design. The sweep only
+// ever considers paths the engine stamped at one version or the other.
+//
+// Pure decision logic lives here so tests can drive it with in-memory/temp
+// fixtures and zero npm network access; CLI + npm-pack orchestration lives in
+// src/commands/upgrade.mjs. No dependencies beyond the Node stdlib (git is
+// already a hard requirement of this repo).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { listFiles } from "./fsutil.mjs";
+import { isBinaryPath } from "./tokens.mjs";
+import { BACKUP_SUFFIX } from "./upgrade.mjs";
+
+/** Sidecar suffix for the new engine content beside a conflicted file. */
+export const SIDECAR_SUFFIX = ".cmp-new";
+
+/**
+ * Hard exclusion list — the app's own state, or its secrets, that the engine
+ * also seeds. A diff here is noise or danger, never an upgrade. Matched
+ * against the project-relative path (posix separators):
+ *   - a bare name (no `/`) matches that basename at ANY depth — this is what
+ *     keeps `keystore.properties` and `google-services.json` excluded wherever
+ *     they live (e.g. composeApp/google-services.json), because those files
+ *     must never be read, written, or printed by this code;
+ *   - `dir/**` matches everything under `dir` (root-anchored);
+ *   - `**` + `/dir/` + `**` matches everything under a `dir` segment at any depth;
+ *   - `**` + `/name` matches that basename at any depth.
+ */
+export const EXCLUDED_PATTERNS = [
+  "create-cmp.json",
+  "qa/evidence/**",
+  "qa/approvals.json",
+  "qa/comments.json",
+  "qa/golden/**",
+  ".git/**",
+  "build/**",
+  "**/build/**",
+  ".gradle/**",
+  "local.properties",
+  "keystore.properties",
+  "google-services.json",
+  "**/GoogleService-Info.plist",
+];
+
+/**
+ * Does one exclusion pattern match a project-relative posix path?
+ * @param {string} relPath project-relative path, "/"-separated
+ * @param {string} pattern one of EXCLUDED_PATTERNS (see grammar above)
+ * @returns {boolean}
+ */
+export function matchesPattern(relPath, pattern) {
+  if (pattern.endsWith("/**")) {
+    const dir = pattern.slice(0, -3);
+    if (dir.startsWith("**/")) {
+      // "**/build/**": any DIRECTORY segment equal to the name.
+      const seg = dir.slice(3);
+      return relPath.split("/").slice(0, -1).includes(seg);
+    }
+    return relPath === dir || relPath.startsWith(dir + "/");
+  }
+  if (pattern.startsWith("**/")) {
+    const name = pattern.slice(3);
+    return relPath === name || relPath.endsWith("/" + name);
+  }
+  if (!pattern.includes("/")) {
+    // Bare name: basename match at any depth (never risk touching a nested
+    // secret because it wasn't at the root).
+    return relPath === pattern || relPath.endsWith("/" + pattern);
+  }
+  return relPath === pattern;
+}
+
+/**
+ * Is this project-relative path on the hard exclusion list?
+ * Checked BEFORE any file content is read — excluded files (state, secrets)
+ * are never opened by this module.
+ * @param {string} relPath project-relative path, "/"-separated
+ * @returns {boolean}
+ */
+export function isExcludedPath(relPath) {
+  return EXCLUDED_PATTERNS.some((p) => matchesPattern(relPath, p));
+}
+
+/**
+ * Three-way merge via `git merge-file -p --diff3 <theirs> <base> <new>`.
+ * The three sides are written to temp files; git's exit code is 0 for a clean
+ * merge, >0 for the number of conflicts, <0 / spawn error for trouble — both
+ * of the latter are treated as a conflict (the caller then writes a sidecar
+ * instead of touching the app's file, so "treat as conflict" is always safe).
+ * @param {Buffer} theirs the app's current content
+ * @param {Buffer} base the old engine's stamped content
+ * @param {Buffer} next the current engine's stamped content
+ * @returns {{clean: boolean, content: Buffer|null}} merged content when clean
+ */
+export function mergeThreeWay(theirs, base, next) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cmp-harness-merge-"));
+  try {
+    const t = path.join(dir, "theirs");
+    const b = path.join(dir, "base");
+    const n = path.join(dir, "new");
+    fs.writeFileSync(t, theirs);
+    fs.writeFileSync(b, base);
+    fs.writeFileSync(n, next);
+    const r = spawnSync("git", ["merge-file", "-p", "--diff3", t, b, n], {
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.error || r.status === null || r.status !== 0) {
+      return { clean: false, content: null };
+    }
+    return { clean: true, content: r.stdout };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The decision table — one file, three sides, one verdict. Buckets:
+ *   unchanged   engine never changed it (base == new)         → silent
+ *   current     app already matches the new engine            → silent
+ *   applied     app never touched it, engine changed it       → write new
+ *   merged      both changed, three-way merge is clean        → write merged
+ *   conflicted  both changed the same region (or binary, or the app deleted
+ *               a file the engine changed) → NEVER clobber: leave the app's
+ *               file byte-for-byte alone, emit a `.cmp-new` sidecar with the
+ *               new engine's content
+ *   added       new engine file absent from the app           → write new
+ *   removed     engine deleted it and the app never touched it → delete
+ *   orphaned    engine deleted it but the app modified it     → keep, report
+ *
+ * Binary files (isBinaryPath) never three-way merge: replace when the app
+ * never touched them, otherwise conflicted.
+ *
+ * @param {object} params
+ * @param {string} params.relPath project-relative path (for binary sniffing)
+ * @param {Buffer|null} params.base old engine's content (null = not stamped then)
+ * @param {Buffer|null} params.next current engine's content (null = engine deleted it)
+ * @param {Buffer|null} params.theirs the app's content (null = absent in the app)
+ * @param {(theirs:Buffer, base:Buffer, next:Buffer)=>{clean:boolean,content:Buffer|null}} [params.merge]
+ *        three-way merge fn, injectable for tests (default: git merge-file)
+ * @returns {{bucket:string, write:Buffer|null, sidecar:Buffer|null, remove:boolean}|null}
+ *        null when the path is in neither base nor new (app-authored — invisible)
+ */
+export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay }) {
+  const none = (bucket) => ({ bucket, write: null, sidecar: null, remove: false });
+  const write = (bucket, content) => ({ bucket, write: content, sidecar: null, remove: false });
+  const conflict = () => ({ bucket: "conflicted", write: null, sidecar: next, remove: false });
+  const eq = (a, b) => a !== null && b !== null && a.equals(b);
+
+  if (base !== null && next !== null) {
+    if (eq(base, next)) return none("unchanged"); // engine never changed it
+    // Engine changed it:
+    if (theirs === null) return conflict(); // app deleted it — never resurrect silently
+    if (eq(theirs, next)) return none("current"); // already up to date
+    if (eq(theirs, base)) return write("applied", next); // app never touched it
+    // All three differ:
+    if (isBinaryPath(relPath)) return conflict(); // binaries never merge
+    const m = merge(theirs, base, next);
+    if (m.clean && m.content !== null) {
+      // A merge that reproduces the app's file byte-for-byte means the app
+      // already carries the engine change (e.g. a previous --harness run) —
+      // report current, keep re-runs idempotent and quiet.
+      if (m.content.equals(theirs)) return none("current");
+      return write("merged", m.content);
+    }
+    return conflict();
+  }
+
+  if (base === null && next !== null) {
+    // New engine file.
+    if (theirs === null) return write("added", next);
+    if (eq(theirs, next)) return none("current");
+    return conflict(); // the app already has something different there
+  }
+
+  if (base !== null && next === null) {
+    // Engine deleted it.
+    if (theirs === null) return none("current"); // already gone
+    if (eq(theirs, base)) return { bucket: "removed", write: null, sidecar: null, remove: true };
+    return none("orphaned"); // app modified it — keep it, report it
+  }
+
+  return null; // in neither base nor new: app-authored, invisible to the sweep
+}
+
+function readIfPresent(dir, relPath) {
+  try {
+    return fs.readFileSync(path.join(dir, relPath));
+  } catch {
+    return null;
+  }
+}
+
+function toRel(root, abs) {
+  return path.relative(root, abs).split(path.sep).join("/");
+}
+
+/**
+ * Walk base ∪ new, classify every path through the decision table, and return
+ * the full plan. Excluded paths are counted WITHOUT ever reading their
+ * content (state files and secrets stay unopened). Reads the three trees but
+ * never writes anything — applying is applyHarnessPlan's job.
+ * @param {object} params
+ * @param {string} params.baseDir stamped tree of the old engine
+ * @param {string} params.newDir stamped tree of the current engine
+ * @param {string} params.projectDir the app's working tree
+ * @param {Function} [params.merge] three-way merge fn, injectable for tests
+ * @returns {{entries: Array<{relPath:string, bucket:string, write?:Buffer|null,
+ *            sidecar?:Buffer|null, remove?:boolean}>,
+ *            counts: Record<string, number>}}
+ */
+export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay }) {
+  const rels = new Set();
+  for (const f of listFiles(baseDir)) rels.add(toRel(baseDir, f));
+  for (const f of listFiles(newDir)) rels.add(toRel(newDir, f));
+
+  const counts = {
+    excluded: 0,
+    unchanged: 0,
+    current: 0,
+    applied: 0,
+    merged: 0,
+    conflicted: 0,
+    added: 0,
+    removed: 0,
+    orphaned: 0,
+  };
+  const entries = [];
+  for (const relPath of [...rels].sort()) {
+    if (isExcludedPath(relPath)) {
+      counts.excluded += 1;
+      entries.push({ relPath, bucket: "excluded", write: null, sidecar: null, remove: false });
+      continue;
+    }
+    const decision = decideFile({
+      relPath,
+      base: readIfPresent(baseDir, relPath),
+      next: readIfPresent(newDir, relPath),
+      theirs: readIfPresent(projectDir, relPath),
+      merge,
+    });
+    if (decision === null) continue;
+    counts[decision.bucket] += 1;
+    entries.push({ relPath, ...decision });
+  }
+  return { entries, counts };
+}
+
+/**
+ * Apply a plan to the app's working tree. Every file that gets written over
+ * or deleted is backed up first as `<file>${BACKUP_SUFFIX}` (same suffix as
+ * the version-catalog upgrade path, so one revert story covers both modes).
+ * Conflicted entries never touch the app's file — only the `.cmp-new` sidecar
+ * is written. Returns what happened so the CLI can print revert commands.
+ * @param {string} projectDir
+ * @param {Array<{relPath:string, bucket:string, write:Buffer|null, sidecar:Buffer|null, remove:boolean}>} entries
+ * @returns {{written:string[], created:string[], deleted:string[],
+ *            sidecars:string[], backups:string[]}}
+ *   written  rel paths overwritten (backup exists)
+ *   created  rel paths newly created (no previous content, no backup)
+ *   deleted  rel paths removed (backup exists)
+ *   sidecars rel paths of `.cmp-new` files written beside conflicts
+ *   backups  rel paths that have a `${BACKUP_SUFFIX}` copy
+ */
+export function applyHarnessPlan(projectDir, entries) {
+  const written = [];
+  const created = [];
+  const deleted = [];
+  const sidecars = [];
+  const backups = [];
+  for (const e of entries) {
+    const abs = path.join(projectDir, e.relPath);
+    if (e.sidecar !== null && e.sidecar !== undefined) {
+      const sidecarPath = abs + SIDECAR_SUFFIX;
+      fs.mkdirSync(path.dirname(sidecarPath), { recursive: true });
+      fs.writeFileSync(sidecarPath, e.sidecar);
+      sidecars.push(e.relPath + SIDECAR_SUFFIX);
+      continue;
+    }
+    if (e.remove) {
+      fs.copyFileSync(abs, abs + BACKUP_SUFFIX);
+      backups.push(e.relPath);
+      fs.rmSync(abs);
+      deleted.push(e.relPath);
+      continue;
+    }
+    if (e.write !== null && e.write !== undefined) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      if (fs.existsSync(abs)) {
+        fs.copyFileSync(abs, abs + BACKUP_SUFFIX);
+        backups.push(e.relPath);
+        fs.writeFileSync(abs, e.write);
+        written.push(e.relPath);
+      } else {
+        fs.writeFileSync(abs, e.write);
+        created.push(e.relPath);
+      }
+    }
+  }
+  return { written, created, deleted, sidecars, backups };
+}
+
+/**
+ * Reconstruct the engine config from a parsed create-cmp.json record.
+ * Key names differ slightly (record: name/bundleId ↔ config:
+ * appName/iosBundleId). Fields the record predates default to
+ * "feature absent" — a record written before a toggle existed describes an
+ * app whose tree does NOT carry that feature, so stamping without it mirrors
+ * the app best.
+ * @param {object} record parsed create-cmp.json
+ * @param {string} targetDir where the reconstructed stamp should land
+ * @returns {object} engine config (options.schema.json shape)
+ */
+export function configFromSpecRecord(record, targetDir) {
+  return {
+    appName: record.name,
+    package: record.package,
+    iosBundleId: record.bundleId,
+    region: record.region ?? "us-central1",
+    themePrefix: record.themePrefix,
+    platforms: record.platforms ?? { android: true, ios: true },
+    firebase: record.firebase ?? { enabled: false },
+    room: record.room ?? false,
+    e2e: record.e2e ?? false,
+    inspector: record.inspector ?? false,
+    devClient: record.devClient ?? false,
+    tabs: record.tabs ?? [
+      { label: "Home", icon: "home" },
+      { label: "Profile", icon: "person" },
+    ],
+    targetDir,
+  };
+}

package/template/CLAUDE.md

@@ -388,4 +388,7 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | `./gradlew :composeApp:assembleRelease` | Android release build — R8 + `lintVital`, the variant the lane's `releaseBuild` step proves. Produces an **unsigned** APK; signing needs a keystore, which is yours to create and keep out of the repo. |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |
 | `./gradlew :composeApp:connectedDebugAndroidTest` | Instrumented behavior tests on the attached device (the lane's `androidChecks` step) |
-| `node qa/verify.mjs --profile release` | Ship-time lane: everything `ci` proves plus the release-APK Maestro smoke (`releaseSmoke`) |
+| `node qa/verify.mjs --profile release` | Ship-time lane: everything `ci` proves plus the audit-cadence report (`auditCadence` — which androidMain subsystems changed since their last recorded `cmp-audit`; a nudge, never a gate) and the release-APK Maestro smoke (`releaseSmoke`) |
+| `node qa/verify.mjs --determinism` | Timezone determinism probe, alone: runs the JVM test tier twice under UTC-12 and UTC+14 and FAILs naming any test whose outcome differs — the dynamic net behind ARCH-13's static one. Opt-in inside a lane via `--profile ci --determinism`; never with `--fast`; writes no receipt on its own |
+| `node qa/record-audit.mjs <subsystem>` | Record that a `cmp-audit` of an androidMain subsystem happened (appends subsystem + HEAD sha + timestamp to `qa/audits.jsonl`; refuses dirty/unknown targets). `--list` shows every derived subsystem and its audit status |
+| `node qa/retrospective.mjs` | How this project actually uses its harness, from `qa/flight-recorder.jsonl` (appended by every lane run): fast vs full ratio, verbatim SKIP reasons grouped, whether the device tier is ever reached, longest stretch with no full lane. States only what the journal recorded |

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