create-cmp-cli 0.13.0 → 0.14.0

package/packages/receipts/src/inputs-hash.mjs

@@ -0,0 +1,194 @@
+// Shared primitive: a content hash of the "verified surface" — every tracked
+// file whose content can change the verify lane's verdict, minus the lane's
+// own outputs. Both qa/verify.mjs (writes inputs.hash into the receipt) and
+// qa/receipt-check.mjs (recomputes it to test validity) import this module so
+// there is exactly one definition of the surface and the algorithm.
+//
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Directories / files INCLUDED in the verified surface (relative to project ROOT).
+// Principle: every tracked file whose content can change the lane's verdict.
+export const VERIFIED_SURFACE = [
+  "composeApp",
+  "specs",
+  "qa",
+  "gradle/libs.versions.toml",
+  "build.gradle.kts",
+  "settings.gradle.kts",
+  "gradle.properties",
+];
+
+// Paths EXCLUDED even though they fall under an included surface dir above.
+// qa/evidence and qa-artifacts are lane OUTPUTS — including them would make
+// the hash depend on the lane's own prior output. qa/comments.json is excluded
+// by this file's own stated principle: comments are explicitly advisory and no
+// lane step reads them, so their content cannot change the verdict — hashing
+// them made resolving a review note invalidate a receipt for a tree whose
+// code had not changed. qa/approvals.log.jsonl (the governance journal) is
+// excluded by the same principle: it is append-only HISTORY of decisions the
+// snapshot (qa/approvals.json) already carries as state — no lane step reads
+// it, so recording who/why must never invalidate a receipt for a tree whose
+// code did not change (the exact failure FI-8 killed for acceptance).
+// qa/flight-recorder.jsonl is a lane OUTPUT in the strictest sense: the lane
+// appends one line to it on every run, after the receipt is written — hashing
+// it would make every run invalidate its own receipt. qa/audits.jsonl (the
+// cmp-audit ledger) is read by exactly one lane step (auditCadence), which is
+// a REPORT and can never change the verdict — and recording an audit is
+// bookkeeping about a commit that already happened, so appending a record
+// must never invalidate a receipt for a tree whose code did not change
+// (approvals.log.jsonl's principle, applied to audits).
+const EXCLUDED_PREFIXES = [
+  "qa/evidence",
+  "qa-artifacts",
+  "qa/comments.json",
+  "qa/approvals.log.jsonl",
+  "qa/flight-recorder.jsonl",
+  "qa/audits.jsonl",
+];
+
+// qa/approvals.json is hashed by PROJECTION, not raw bytes. The approvals gate's
+// verdict depends on exactly three row fields (artifact, status, hash) plus the
+// top-level exemplarFeature (it selects the exemplar artifact's file set).
+// Everything else on a row — approvedAt, mode, via, reopenedAt, accepted,
+// acceptedAt — is ledger bookkeeping that records a decision without gating one.
+// Hashing those bytes meant the human clicking Accept on a provenDone feature
+// instantly invalidated the receipt whose PASS permitted the acceptance.
+// Acceptance is a bookend recorded after proof; it must not destroy it.
+// An unparsable ledger falls back to raw bytes — refusal over fabrication.
+const APPROVALS_PROJECTED_PATH = "qa/approvals.json";
+
+function projectApprovalsBytes(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.toString("utf8"));
+  } catch {
+    return raw;
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.artifacts)) return raw;
+  const rows = parsed.artifacts
+    .filter((a) => a && typeof a === "object")
+    .map((a) => ({ artifact: a.artifact ?? null, status: a.status ?? null, hash: a.hash ?? null }))
+    .sort((a, b) => (String(a.artifact) < String(b.artifact) ? -1 : String(a.artifact) > String(b.artifact) ? 1 : 0));
+  const projection = {};
+  if (typeof parsed.exemplarFeature === "string") projection.exemplarFeature = parsed.exemplarFeature;
+  projection.artifacts = rows;
+  return Buffer.from(`${JSON.stringify(projection)}\n`, "utf8");
+}
+
+function isExcluded(relPath) {
+  return EXCLUDED_PREFIXES.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`));
+}
+
+// The verified surface is the set of files that WILL be committed: tracked files
+// PLUS untracked-but-not-ignored files (`--others --exclude-standard`). A freshly
+// generated feature's files are untracked when the lane runs and the receipt is
+// written, yet they land in the very same commit as the receipt — so they must be
+// hashed, or the committed receipt would never attest its own commit (and CI's
+// receipt-matches-HEAD gate would false-fail on every change). Gitignored scratch
+// (build outputs, qa-artifacts) is still excluded via --exclude-standard.
+function tryGitLsFiles(root) {
+  try {
+    const out = execSync("git ls-files -z --cached --others --exclude-standard", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.split("\0").filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+// Directory names the walk fallback must skip wherever they appear under a
+// surface root. These mirror what the stamped .gitignore excludes: without
+// this, a pre-`git init` hash (walk mode) includes composeApp/build/** and
+// Gradle/Kotlin scratch that the post-`git init` hash (`git ls-files
+// --exclude-standard`) excludes — so the stamp-time PASS receipt would read
+// "INVALID — source changed" the moment the user runs `git init`, even though
+// no source changed. Pre-git and post-git hashes must agree for identical
+// source; that is the invariant the regression test pins.
+const WALK_EXCLUDED_DIRS = new Set(["build", ".gradle", ".kotlin", ".git", ".idea", "node_modules"]);
+// File-level mirror of the same principle (OS/editor junk the .gitignore covers).
+const WALK_EXCLUDED_FILES = new Set([".DS_Store"]);
+const WALK_EXCLUDED_SUFFIXES = [".iml", ".log"];
+
+function walkIncludesFile(name) {
+  if (WALK_EXCLUDED_FILES.has(name)) return false;
+  return !WALK_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+// Dependency-free recursive walk, used when git is unavailable (non-git scaffold).
+function walkAllFiles(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (WALK_EXCLUDED_DIRS.has(entry.name)) continue; // non-source scratch — see note above
+      out.push(...walkAllFiles(p));
+    } else if (entry.isFile() && walkIncludesFile(entry.name)) out.push(p);
+  }
+  return out;
+}
+
+// Resolve the verified surface to a flat, sorted list of paths (relative to
+// root, POSIX-style `/` separators) that currently exist on disk.
+function resolveSurfaceFiles(root) {
+  const gitFiles = tryGitLsFiles(root);
+
+  if (gitFiles) {
+    return gitFiles
+      .map((p) => p.split(path.sep).join("/"))
+      .filter((relPath) => VERIFIED_SURFACE.some((surface) => relPath === surface || relPath.startsWith(`${surface}/`)))
+      .filter((relPath) => !isExcluded(relPath))
+      .filter((relPath) => fs.existsSync(path.join(root, relPath)) && fs.statSync(path.join(root, relPath)).isFile());
+  }
+
+  // Fallback: no git available — walk the surface directories directly so a
+  // non-git scaffold still produces a stable hash.
+  const collected = [];
+  for (const surface of VERIFIED_SURFACE) {
+    const abs = path.join(root, surface);
+    if (!fs.existsSync(abs)) continue;
+    const stat = fs.statSync(abs);
+    if (stat.isFile()) {
+      collected.push(surface);
+    } else if (stat.isDirectory()) {
+      for (const file of walkAllFiles(abs)) {
+        collected.push(path.relative(root, file).split(path.sep).join("/"));
+      }
+    }
+  }
+  return collected.filter((relPath) => !isExcluded(relPath));
+}
+
+/**
+ * Compute the sha256 hash of the verified surface for the project rooted at `root`.
+ * Deterministic: same tree (same file paths + same file bytes) → same hash.
+ * @param {string} root absolute path to the project root
+ * @returns {{ hash: string, fileCount: number }}
+ */
+export function computeInputsHash(root) {
+  // Code-unit sort (default String sort), NOT localeCompare: the hash depends
+  // on iteration order, and ICU collation varies with the machine's locale
+  // (e.g. a da_DK machine orders "aa" after "z"; en orders case-insensitively
+  // where code units do not) — the same tree must hash identically everywhere.
+  const files = [...new Set(resolveSurfaceFiles(root))].sort();
+
+  const overall = createHash("sha256");
+  for (const relPath of files) {
+    const raw = fs.readFileSync(path.join(root, relPath));
+    const bytes = relPath === APPROVALS_PROJECTED_PATH ? projectApprovalsBytes(raw) : raw;
+    const fileSha = createHash("sha256").update(bytes).digest("hex");
+    overall.update(`${relPath}\0${fileSha}\n`);
+  }
+
+  return { hash: overall.digest("hex"), fileCount: files.length };
+}

package/packages/receipts/src/receipt-validate.mjs

@@ -0,0 +1,234 @@
+// The evidence-binding predicate and its service-grade extensions, as pure
+// dependency-free functions. `evaluateReceipt` is the exact predicate the
+// generated project's qa/receipt-check.mjs (and its Stop hook + CI) runs;
+// the additional checks (freshness, execution plausibility, SKIP listing) are
+// consumed by hosted validators that judge a receipt fetched from a repo
+// tarball rather than the working tree.
+//
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/receipt-validate.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { computeInputsHash } from "./inputs-hash.mjs";
+
+/** Where a generated project keeps its committed receipt, relative to root. */
+export const RECEIPT_REL_PATH = "qa/evidence/latest.json";
+
+/**
+ * Read and parse the committed receipt for the project rooted at `root`.
+ * @param {string} root absolute path to the project root
+ * @returns {object|null} the parsed receipt, or null when absent/unparsable
+ */
+export function readReceipt(root, relPath = RECEIPT_REL_PATH) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, relPath), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The core predicate: does this receipt validly attest the tree whose inputs
+ * hash `recompute()` returns? Reasons are the exact refusal strings the
+ * generated project's receipt-check CLI (and Stop hook) prints.
+ *
+ * @param {object} receipt parsed receipt JSON
+ * @param {() => {hash: string, fileCount: number}} recompute lazily invoked —
+ *   never called when the receipt fails structurally first (missing binding,
+ *   FAIL verdict), so callers don't pay for a hash they don't need.
+ * @returns {{valid: boolean, reason: string, profile: (string|undefined), recomputed?: {hash: string, fileCount: number}}}
+ */
+export function evaluateReceipt(receipt, recompute) {
+  const profile = receipt.profile;
+
+  if (!receipt.inputs || typeof receipt.inputs.hash !== "string") {
+    return {
+      valid: false,
+      reason: `receipt predates evidence binding — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  if (receipt.verdict === "FAIL") {
+    return {
+      valid: false,
+      reason: `the committed receipt is a FAIL (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  const recomputed = recompute();
+
+  if (receipt.inputs.hash !== recomputed.hash) {
+    return {
+      valid: false,
+      reason: `source changed since the receipt — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+      recomputed,
+    };
+  }
+
+  if (receipt.verdict !== "PASS") {
+    return {
+      valid: false,
+      reason: `receipt verdict is "${receipt.verdict}", not PASS (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
+}
+
+// ── Service-grade checks (hosted validators; the local predicate above does
+//    not enforce these — the tree it checks is by definition "now") ─────────
+
+/** Default policy for hosted validation. Every knob is overridable. */
+export const DEFAULT_POLICY = {
+  /** A receipt older than this no longer counts as fresh (hosted check only). */
+  maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  /**
+   * Executed (non-SKIP) gates must report at least this much total wall time.
+   * A "PASS" receipt whose executed gates sum to less cannot attest a real
+   * lane run — the tell for replayed/cached or hand-written verdicts
+   * (evidence must attest execution, not results).
+   */
+  minExecutedMs: 5000,
+};
+
+/**
+ * Freshness: is the receipt's generatedAt within maxAgeMs of `now`?
+ * @returns {{ok: boolean, detail: string, ageMs?: number}}
+ */
+export function checkFreshness(receipt, { now = Date.now(), maxAgeMs = DEFAULT_POLICY.maxAgeMs } = {}) {
+  const generatedAt = Date.parse(receipt?.generatedAt ?? "");
+  if (Number.isNaN(generatedAt)) {
+    return { ok: false, detail: "receipt has no parsable generatedAt timestamp" };
+  }
+  const ageMs = now - generatedAt;
+  if (ageMs < -60_000) {
+    // A receipt from the future is a clock lie, not a rounding artifact.
+    return { ok: false, detail: `receipt claims a future generatedAt (${receipt.generatedAt})`, ageMs };
+  }
+  if (ageMs > maxAgeMs) {
+    const days = Math.floor(ageMs / 86_400_000);
+    return { ok: false, detail: `receipt is stale — generated ${days} day(s) ago, older than the ${Math.floor(maxAgeMs / 86_400_000)}-day freshness window`, ageMs };
+  }
+  return { ok: true, detail: `receipt generated ${receipt.generatedAt}`, ageMs };
+}
+
+/**
+ * Execution plausibility: do the executed (non-SKIP) gates report durations a
+ * real lane run could produce? Catches replayed/cached greens and hand-edited
+ * receipts whose numbers were never lived.
+ * @returns {{ok: boolean, detail: string, executedMs?: number, executedSteps?: number}}
+ */
+export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_POLICY.minExecutedMs } = {}) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : null;
+  if (!steps || steps.length === 0) {
+    return { ok: false, detail: "receipt lists no verify-lane steps — nothing was executed" };
+  }
+  const executed = steps.filter((s) => s && s.verdict !== "SKIP");
+  if (executed.length === 0) {
+    return { ok: false, detail: "every step in the receipt is a SKIP — the lane verified nothing" };
+  }
+  let total = 0;
+  for (const step of executed) {
+    if (typeof step.durationMs !== "number" || !Number.isFinite(step.durationMs) || step.durationMs < 0) {
+      return { ok: false, detail: `step "${step.name ?? "?"}" reports an invalid duration (${step.durationMs}) — durations must be real, non-negative numbers` };
+    }
+    total += step.durationMs;
+  }
+  if (total < minExecutedMs) {
+    return {
+      ok: false,
+      detail: `implausibly fast — executed gates report ${total}ms total, below the ${minExecutedMs}ms floor; a receipt this fast cannot attest a real lane run (evidence must attest execution)`,
+      executedMs: total,
+      executedSteps: executed.length,
+    };
+  }
+  return { ok: true, detail: `${executed.length} executed gate(s), ${total}ms total`, executedMs: total, executedSteps: executed.length };
+}
+
+/**
+ * List the SKIPped steps with their honest reasons. SKIPs are reported, not
+ * failed — green-with-gaps must be visible, never silently equated with
+ * fully-verified (or silently punished).
+ * @returns {Array<{name: string, reason: string}>}
+ */
+export function listSkippedSteps(receipt) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : [];
+  return steps
+    .filter((s) => s && s.verdict === "SKIP")
+    .map((s) => ({ name: s.name ?? "?", reason: s.reason ?? "no reason recorded" }));
+}
+
+/**
+ * The hosted composite: validate the receipt found in an extracted repo tree
+ * (e.g. a tarball at a PR's head SHA) with the full service-grade policy.
+ *
+ * @param {object} args
+ * @param {string} args.root absolute path to the extracted tree's project root
+ * @param {number} [args.now] epoch ms, for freshness (defaults to Date.now())
+ * @param {object} [args.policy] overrides for DEFAULT_POLICY
+ * @returns {{
+ *   status: "missing"|"valid"|"invalid",
+ *   reason: string,
+ *   profile?: string,
+ *   checks: Array<{id: string, ok: boolean, detail: string}>,
+ *   skips: Array<{name: string, reason: string}>,
+ * }}
+ */
+export function validateReceiptForTree({ root, now = Date.now(), policy = {} } = {}) {
+  const effective = { ...DEFAULT_POLICY, ...policy };
+  const receipt = readReceipt(root);
+
+  if (receipt === null) {
+    return {
+      status: "missing",
+      reason: `no receipt at ${RECEIPT_REL_PATH} — this repo does not carry the create-cmp evidence harness (that is not a failure)`,
+      checks: [{ id: "receipt-present", ok: false, detail: `no parsable receipt at ${RECEIPT_REL_PATH}` }],
+      skips: [],
+    };
+  }
+
+  const checks = [{ id: "receipt-present", ok: true, detail: RECEIPT_REL_PATH }];
+  const skips = listSkippedSteps(receipt);
+
+  // The core predicate (binding + verdict + hash), verbatim local semantics.
+  const core = evaluateReceipt(receipt, () => computeInputsHash(root));
+  checks.push({ id: "binding-and-hash", ok: core.valid, detail: core.reason });
+
+  // Service-grade extensions run regardless, so a failing receipt reports
+  // every violated rule at once (refusals name what failed, all of it).
+  const freshness = checkFreshness(receipt, { now, maxAgeMs: effective.maxAgeMs });
+  checks.push({ id: "freshness", ok: freshness.ok, detail: freshness.detail });
+
+  const plausibility = checkExecutionPlausibility(receipt, { minExecutedMs: effective.minExecutedMs });
+  checks.push({ id: "execution-plausibility", ok: plausibility.ok, detail: plausibility.detail });
+
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length > 0) {
+    return {
+      status: "invalid",
+      reason: failed.map((c) => c.detail).join("; "),
+      profile: core.profile,
+      checks,
+      skips,
+    };
+  }
+
+  return {
+    status: "valid",
+    reason: core.reason,
+    profile: core.profile,
+    checks,
+    skips,
+  };
+}

package/src/commands/upgrade.mjs

@@ -42,6 +42,8 @@ import { colors, ok, warn, fail, step } from "../lib/log.mjs";
 import { consent } from "../bootstrap/exec.mjs";
 import { loadRegistry, latestSet, getSet } from "../lib/registry.mjs";
 import { planUpgrade, BACKUP_SUFFIX } from "../lib/upgrade.mjs";
+import { writeHarnessLock, checkHarnessIntegrity, describeIntegrity } from "../../packages/harness/src/lib/harness-lock.mjs";
+import { LOCAL_PATCH_PATH } from "../lib/harness-upgrade.mjs";
 import {
   planHarnessUpgrade,
   applyHarnessPlan,
@@ -51,6 +53,52 @@ import {
 
 const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
+/**
+ * The harness version this engine ships. Read from the package that owns the
+ * lane, NOT the engine's own package.json — they version independently, which
+ * is the point: the lane changes far more often than the template's app shape,
+ * and fusing them forced an app-shape merge every time a lane fix shipped.
+ * @returns {string|null} semver, or null when unreadable
+ */
+function shippedHarnessVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "packages/harness/package.json"), "utf8")
+    ).version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Advance create-cmp.json's engineVersion to what this engine just applied.
+ *
+ * Nothing used to do this, and the omission compounded: the next
+ * `upgrade --harness` re-fetched the STALE version as its merge base and
+ * re-presented every conflict already resolved by hand. Fuelled still read
+ * 0.9.0 after being upgraded to 0.13.0.
+ *
+ * Only called when the sweep landed COMPLETELY. With conflicts outstanding the
+ * app is genuinely part-way between two engine versions, and claiming the new
+ * one would be the same lie in the other direction.
+ * @param {string} projectDir
+ * @param {string} version
+ * @returns {boolean} whether the record was updated
+ */
+function writeBackEngineVersion(projectDir, version) {
+  const specPath = path.join(projectDir, "create-cmp.json");
+  try {
+    const record = JSON.parse(fs.readFileSync(specPath, "utf8"));
+    if (record.engineVersion === version) return false;
+    record.engineVersion = version;
+    record.upgradedAt = new Date().toISOString();
+    fs.writeFileSync(specPath, `${JSON.stringify(record, null, 2)}\n`);
+    return true;
+  } catch {
+    return false; // best-effort — never fail an applied upgrade over metadata
+  }
+}
+
 function readIfExists(p) {
   try {
     return fs.readFileSync(p, "utf8");
@@ -158,6 +206,17 @@ function printHarnessReport(plan) {
       `${colors.dim(`unchanged ${c.unchanged} · already current ${c.current} · excluded state/secrets ${c.excluded}`)}\n`
   );
   const groups = [
+    // The machine-owned lane first: it is the bulk of the sweep and the part
+    // that needs no human judgement at all.
+    ["region-clean", "lane refreshed (machine-owned, untouched since install)", ok],
+    ["region-absorbed", "lane refreshed (local edit already carried by the new engine)", ok],
+    ["region-restored", "lane restored (files the app had deleted)", ok],
+    ["region-removed", "lane files retired by the engine", ok],
+    [
+      "region-patched",
+      `lane refreshed, LOCAL FORK preserved (not re-applied — see ${LOCAL_PATCH_PATH})`,
+      warn,
+    ],
     ["applied", "applied (engine changed, app never touched — will take the new content)", ok],
     ["merged", "merged (both changed different regions — both edits survive)", ok],
     ["added", "added (new engine files absent from the app)", ok],
@@ -169,6 +228,9 @@ function printHarnessReport(plan) {
   for (const [bucket, label, log] of groups) {
     const files = list(bucket);
     if (files.length === 0) continue;
+    // `orphaned` needs no action (the app's file is kept as-is), and neither do
+    // the clean lane buckets — they apply themselves. Only a preserved local
+    // fork earns a human's attention among the region buckets.
     if (bucket !== "orphaned") actionable += files.length;
     log(`${colors.bold(String(files.length))} ${label}`);
     for (const f of files) process.stdout.write(`    ${f}\n`);
@@ -309,6 +371,31 @@ async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRo
   for (const f of result.deleted) ok(`deleted ${f} ${colors.dim(`(backup: ${f}${BACKUP_SUFFIX})`)}`);
   for (const f of result.sidecars) warn(`conflict sidecar ${f} — resolve by hand, then delete it`);
 
+  // ── Re-lock the lane ──────────────────────────────────────────────────────
+  // The machine-owned region always lands on the new engine's content, whether
+  // or not app-shaped files conflicted — that is what the two independent
+  // version numbers buy. So the lock is rewritten on its own schedule.
+  const harnessVersion = shippedHarnessVersion();
+  if (harnessVersion) {
+    writeHarnessLock(projectDir, { version: harnessVersion });
+    ok(`lane locked at ${colors.bold(harnessVersion)} — ${describeIntegrity(checkHarnessIntegrity(projectDir))}`);
+  }
+
+  if (result.patched.length > 0) {
+    warn(
+      `${result.patched.length} lane file(s) carried a LOCAL change that the new engine does not. ` +
+        `The lane was refreshed and your edits were preserved — NOT re-applied — in ${LOCAL_PATCH_PATH}.`
+    );
+    for (const f of result.patched) process.stdout.write(`    ${f}\n`);
+    process.stdout.write(
+      colors.dim(
+        `  The diff is against the lane you WERE on, so it may not apply cleanly to the new one —\n` +
+          `  that is the merge this tool declined to do behind your back, not a broken patch.\n` +
+          `  Attempt it with: git apply --reject ${LOCAL_PATCH_PATH}   (or upstream the change)\n`
+      )
+    );
+  }
+
   if (result.backups.length > 0 || result.created.length > 0) {
     process.stdout.write(`\n${colors.bold("To revert")}\n`);
     for (const f of result.backups) {
@@ -326,6 +413,15 @@ async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRo
     );
     return 1;
   }
+  // ── Advance the recorded engine version ───────────────────────────────────
+  // Only now, with nothing conflicted: the sweep landed completely, so the
+  // next upgrade's merge base is genuinely this version. Skipping this is what
+  // made repeat upgrades compound — the base stayed stale and every
+  // already-resolved conflict came back.
+  if (writeBackEngineVersion(projectDir, currentVersion)) {
+    ok(`create-cmp.json engineVersion → ${colors.bold(currentVersion)}`);
+  }
+
   process.stdout.write(
     `\n${colors.green("Applied.")} Prove the build: ${colors.cyan(`create-cmp verify --target-dir ${targetDir}`)}\n`
   );