create-cmp-cli 0.14.1 → 0.16.0

package/packages/harness/src/lib/inputs-hash.mjs

@@ -5,7 +5,7 @@
 // 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
+// create-cmp repo (the `@create-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`.

package/packages/harness/src/lib/receipt-validate.mjs

@@ -6,7 +6,7 @@
 // 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
+// create-cmp repo (the `@create-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`.

package/packages/harness/src/receipt-check.mjs

@@ -39,7 +39,7 @@ function readStdinJson() {
 }
 
 // The predicate itself lives in qa/lib/receipt-validate.mjs (vendored from the
-// cmp-receipts package — one definition everywhere a receipt is judged); this
+// @create-cmp/receipts package — one definition everywhere a receipt is judged); this
 // CLI only reads the receipt and frames the exit codes.
 function evaluate() {
   const receipt = readReceipt(ROOT);

package/packages/receipts/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "cmp-receipts",
+  "name": "@create-cmp/receipts",
   "version": "0.1.0",
-  "description": "Validate create-cmp evidence receipts: inputs-hash recompute, receipt-vs-tree binding, freshness, and execution-plausibility. Dependency-free ESM — the single source of truth vendored into every generated project's qa/lib/ and consumed by the hosted receipt check.",
+  "description": "Validate create-cmp evidence receipts: inputs-hash recompute, receipt-vs-tree binding, freshness, and execution-plausibility. Dependency-free ESM \u2014 the single source of truth vendored into every generated project's qa/lib/ and consumed by the hosted receipt check.",
   "type": "module",
   "main": "src/index.mjs",
   "exports": {
@@ -14,7 +14,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18"
@@ -32,5 +33,12 @@
     "type": "git",
     "url": "git+https://github.com/kvdm-co-pilot/create-cmp.git",
     "directory": "packages/receipts"
+  },
+  "homepage": "https://github.com/kvdm-co-pilot/create-cmp/tree/main/packages/receipts#readme",
+  "bugs": {
+    "url": "https://github.com/kvdm-co-pilot/create-cmp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/packages/receipts/src/index.mjs

@@ -1,4 +1,4 @@
-// cmp-receipts — validate create-cmp evidence receipts.
+// @create-cmp/receipts — validate create-cmp evidence receipts.
 // Single source of truth for the inputs-hash algorithm and the receipt
 // predicate; vendored byte-identical into every generated project's qa/lib/
 // and consumed by hosted validators. Dependency-free ESM.

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

@@ -5,7 +5,7 @@
 // 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
+// create-cmp repo (the `@create-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`.

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

@@ -6,7 +6,7 @@
 // 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
+// create-cmp repo (the `@create-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`.

package/src/commands/attach.mjs

@@ -0,0 +1,250 @@
+// `create-cmp attach` — M0a: the agent contract for an EXISTING Compose/KMP
+// repo that create-cmp never scaffolded (docs/features/attach-mode.md is the
+// design of record; LADDER §R5).
+//
+// The honesty constraint IS the design: a foreign repo carries none of the
+// stamped machinery our discovery surfaces normally point at, so attach
+// writes ONLY surfaces that are true in any Compose/KMP repo — the engine's
+// own doctor/upgrade at the toolchain walls, and an advisory SessionStart
+// context that says plainly what is and is not wired here. Previews, the
+// lane, and enforcement are named as NOT wired (M0b's staged scope), never
+// faked. Files are never clobbered: an existing differing file keeps its
+// bytes and our content lands beside it as `*.cmp-new` (the same sidecar
+// convention as `upgrade --harness` and `harden`).
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { colors, ok, warn, fail } from "../lib/log.mjs";
+import { consent } from "../bootstrap/exec.mjs";
+import { sessionStartCommand } from "../lib/hooks.mjs";
+import { SIDECAR_SUFFIX } from "../lib/harness-upgrade.mjs";
+
+const COMPOSE_SIGNALS = [
+  "org.jetbrains.compose",
+  'kotlin("multiplatform")',
+  "org.jetbrains.kotlin.multiplatform",
+  "org.jetbrains.kotlin.plugin.compose",
+];
+
+/** SessionStart context for an attached repo. No apostrophes (shell-quoted). */
+export const ATTACH_SESSION_CONTEXT =
+  "This Compose/KMP repo carries the create-cmp attach surfaces: AGENTS.md maps " +
+  "toolchain walls to zero-consent commands (doctor diagnoses machine AND project, " +
+  "upgrade diffs against a proven-green version set). No verify lane, previews, or " +
+  "inspector are wired here — do not assume create-cmp scaffold machinery exists in " +
+  "this repo. A new app scaffolded with npx create-cmp-cli would carry all of it.";
+
+/** The attach rendering of the symptom table — only rows true in ANY Compose/KMP repo. */
+export function attachAgentsMd() {
+  return `# Agent instructions
+
+This is an existing Compose/KMP repository with the create-cmp **attach surfaces**
+installed: discovery for the walls every KMP build eventually hits. It was NOT
+scaffolded by create-cmp — none of the generated-project machinery (verify lane,
+headless previews, live inspector, generators) is wired here.
+
+## Stuck? Symptom → command
+
+Both commands run from the repo root with nothing to install — \`npx\` fetches on demand.
+
+| Symptom | Run |
+|---|---|
+| Build broken, toolchain suspect | \`npx create-cmp-cli doctor --fix\` — diagnoses machine AND project (kotlin↔ksp lockstep, catalog drift); asks before any repair |
+| Dependency versions stale or mismatched | \`npx create-cmp-cli upgrade --dry-run\` — diff against the next proven-green set before touching anything |
+
+Famous build failures (kotlin↔KSP mismatch, the KSP2/iOS catch-22, \`SDK location not
+found\`, \`No space left on device\`): \`doctor\` diagnoses all of them offline; the worked
+write-ups live upstream at
+<https://github.com/kvdm-co-pilot/create-cmp/tree/main/docs/errors>.
+
+## What is NOT wired here
+
+A create-cmp-scaffolded app additionally carries device-free screen previews (structure
+for the agent, pixels for the human), a live on-device inspector, feature generators,
+and a verify lane with evidence receipts and a machine-checked definition of done. Those
+surfaces presuppose scaffold machinery this repo does not have; attach does not fake
+them. To see the full contract, scaffold with \`npx create-cmp-cli@latest\`.
+`;
+}
+
+function attachSettings() {
+  return (
+    JSON.stringify(
+      {
+        hooks: {
+          SessionStart: [
+            {
+              matcher: "",
+              hooks: [{ type: "command", command: sessionStartCommand(ATTACH_SESSION_CONTEXT) }],
+            },
+          ],
+        },
+      },
+      null,
+      2
+    ) + "\n"
+  );
+}
+
+/**
+ * Classify the target directory. Pure; returns {ok:true} or {ok:false, reason}.
+ */
+export function classifyTarget(projectDir) {
+  if (fs.existsSync(path.join(projectDir, "create-cmp.json"))) {
+    return {
+      ok: false,
+      reason:
+        "this is a create-cmp-stamped app (create-cmp.json present). Attach is for repos " +
+        "create-cmp never scaffolded — use `create-cmp harden` (minimal → full) or " +
+        "`create-cmp upgrade --harness` (refresh) here instead.",
+    };
+  }
+  const hasGradleSettings =
+    fs.existsSync(path.join(projectDir, "settings.gradle.kts")) ||
+    fs.existsSync(path.join(projectDir, "settings.gradle"));
+  if (!hasGradleSettings) {
+    return {
+      ok: false,
+      reason: "no settings.gradle(.kts) — attach targets an existing Gradle Compose/KMP project.",
+    };
+  }
+  // A Compose/KMP signal anywhere in the repo's build files (two levels deep
+  // covers the conventional module layout without a full tree walk).
+  const buildFiles = [];
+  const collect = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === "build" || e.name.startsWith(".")) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory() && depth > 0) collect(abs, depth - 1);
+      else if (/^build\.gradle(\.kts)?$|^libs\.versions\.toml$/.test(e.name)) buildFiles.push(abs);
+    }
+  };
+  collect(projectDir, 2);
+  collect(path.join(projectDir, "gradle"), 1);
+  const signals = buildFiles.some((f) => {
+    try {
+      const src = fs.readFileSync(f, "utf8");
+      return COMPOSE_SIGNALS.some((s) => src.includes(s));
+    } catch {
+      return false;
+    }
+  });
+  if (!signals) {
+    return {
+      ok: false,
+      reason:
+        "no Compose/KMP signal found in the build files (looked for the Compose or Kotlin " +
+        "Multiplatform plugins). Attach only claims to help Compose/KMP repos.",
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Plan (and optionally write) the attach surfaces. Testable core: no exit, no
+ * prompt. Each unit lands as one of: current | written | sidecar.
+ * @param {object} params
+ * @param {string} params.projectDir
+ * @param {boolean} [params.apply=false]
+ * @returns {{units: Array<{relPath:string, action:string}>, notWired: string[]}}
+ */
+export function attachProject({ projectDir, apply = false }) {
+  const target = classifyTarget(projectDir);
+  if (!target.ok) throw new Error(target.reason);
+
+  const files = [
+    { relPath: "AGENTS.md", content: attachAgentsMd() },
+    { relPath: ".claude/settings.json", content: attachSettings() },
+  ];
+  const units = [];
+  for (const { relPath, content } of files) {
+    const abs = path.join(projectDir, relPath);
+    if (fs.existsSync(abs)) {
+      const current = fs.readFileSync(abs, "utf8");
+      if (current === content) {
+        units.push({ relPath, action: "current" });
+        continue;
+      }
+      if (apply) {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs + SIDECAR_SUFFIX, content);
+      }
+      units.push({ relPath, action: "sidecar" });
+      continue;
+    }
+    if (apply) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+    units.push({ relPath, action: "written" });
+  }
+
+  return {
+    units,
+    notWired: [
+      "headless screen previews (PreviewRegistry + renderScreens) — staged M0b, needs a per-repo Gradle wiring design",
+      "live on-device inspector — ships with scaffolded apps; not injectable into a foreign build yet",
+      "verify lane / evidence receipts / enforcement — the lane addresses the stamped layout by name",
+    ],
+  };
+}
+
+/**
+ * `create-cmp attach [dir] [--dry-run] [--yes]`
+ */
+export async function runAttach(flags, positional) {
+  const targetDir =
+    (typeof flags["target-dir"] === "string" && flags["target-dir"]) || positional || ".";
+  const projectDir = path.resolve(targetDir);
+
+  process.stdout.write(
+    `\n${colors.bold("create-cmp attach")} — agent contract for an existing Compose/KMP repo\n` +
+      `  project: ${colors.cyan(projectDir)}\n\n`
+  );
+
+  let plan;
+  try {
+    plan = attachProject({ projectDir, apply: false });
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+
+  for (const u of plan.units) {
+    if (u.action === "current") ok(`${u.relPath} — already current`);
+    if (u.action === "written") process.stdout.write(`  will write ${u.relPath}\n`);
+    if (u.action === "sidecar")
+      warn(`${u.relPath} exists and differs — ours will land as ${u.relPath}${SIDECAR_SUFFIX}`);
+  }
+  process.stdout.write(`\n${colors.bold("Not wired")} (staged, never faked):\n`);
+  for (const n of plan.notWired) process.stdout.write(`  · ${n}\n`);
+
+  const actionable = plan.units.filter((u) => u.action !== "current");
+  if (actionable.length === 0) {
+    ok("\nNothing to do — attach surfaces are current.");
+    process.exit(0);
+  }
+  if (flags["dry-run"] === true) {
+    process.stdout.write(`\n${colors.yellow("Dry run")} — nothing written.\n`);
+    process.exit(0);
+  }
+  const approved = await consent("\nWrite the attach surfaces?", { assumeYes: flags.yes === true });
+  if (!approved) {
+    process.stdout.write(`${colors.yellow("Not applied")} — re-run with --yes to skip the prompt.\n`);
+    process.exit(0);
+  }
+
+  const applied = attachProject({ projectDir, apply: true });
+  for (const u of applied.units) {
+    if (u.action === "written") ok(`wrote ${u.relPath}`);
+    if (u.action === "sidecar") warn(`wrote ${u.relPath}${SIDECAR_SUFFIX} (yours untouched)`);
+  }
+  process.exit(0);
+}

package/src/commands/create.mjs

@@ -74,6 +74,10 @@ function buildConfigFromFlags(flags, positional) {
     region: typeof flags.region === "string" ? flags.region : "us-central1",
     themePrefix:
       typeof flags["theme-prefix"] === "string" ? flags["theme-prefix"] : pascalFromName(name),
+    // `--minimal` is the Act 1 door (LADDER §2): same app, tests, previews and
+    // advisory hooks, without the verify lane / receipts / governance.
+    // `create-cmp harden` installs the subtraction back.
+    harness: !flagBool(flags, "minimal", false),
     platforms: { android: true, ios },
     firebase: {
       enabled: firebase,
@@ -95,7 +99,7 @@ function buildConfigFromFlags(flags, positional) {
   };
 }
 
-async function interactiveConfig(positional) {
+async function interactiveConfig(positional, flags = {}) {
   let prompts;
   try {
     prompts = (await import("prompts")).default;
@@ -157,6 +161,12 @@ async function interactiveConfig(positional) {
 
   const extras = await prompts(
     [
+      {
+        type: "confirm",
+        name: "harness",
+        message: "Verification harness (verify lane, evidence receipts, machine-checked done)?",
+        initial: flags.minimal !== true, // --minimal pre-answers the interview question
+      },
       { type: "confirm", name: "room", message: "Room local cache?", initial: true },
       { type: "confirm", name: "e2e", message: "E2E test harness (Maestro)?", initial: true },
       {
@@ -193,6 +203,7 @@ async function interactiveConfig(positional) {
     iosBundleId: base.package,
     region: base.region,
     themePrefix: pascalFromName(base.appName),
+    harness: extras.harness,
     platforms: { android: true, ios: base.ios },
     firebase: { enabled: base.firebase, auth, firestore, storage, functions, fcm },
     room: extras.room,
@@ -222,7 +233,7 @@ export async function runCreate(flags, positional) {
 
   const config = nonInteractive
     ? buildConfigFromFlags(flags, positional)
-    : await interactiveConfig(positional);
+    : await interactiveConfig(positional, flags);
 
   const verify = flagBool(flags, "verify", true);
 

package/src/commands/harden.mjs

@@ -0,0 +1,263 @@
+// `create-cmp harden` — install the full verification harness into a minimal
+// scaffold. The Act 2 → Act 3 climb (LADDER §R3), in-band, one command.
+//
+// This is deliberately NOT new machinery. `--minimal` subtracts the harness;
+// harden re-derives the subtraction and installs it back through the SAME
+// three-way walk `upgrade --harness` already trusts:
+//
+//   base   = this app's config stamped MINIMAL   (what the app was given)
+//   new    = this app's config stamped FULL      (what full mode gives it)
+//   theirs = the app's working tree today
+//
+// Every base→new difference is, by construction, exactly the harness: the
+// lane region (restored wholesale — decideRegionFile), the governance
+// surfaces (specs/, skills, hooks — "added"), and the mode-variant documents
+// (CLAUDE.md, AGENTS.md, README, CI — "applied" when untouched, three-way
+// merged when the app edited them, `.cmp-new` sidecars when both moved the
+// same lines). Nothing is ever clobbered, and a second run finds everything
+// current — idempotent by the walk's own semantics, not by bookkeeping.
+//
+// One seam the walk deliberately refuses: EXCLUDED_PATTERNS keeps app state
+// (qa/approvals.json, qa/evidence/, qa/golden/) out of upgrades, because
+// overwriting a ledger is never an upgrade. But a MINIMAL app has no ledgers
+// to protect — harden must seed them. So after the walk, anything excluded
+// that exists in the full stamp and is MISSING in the app is copied in:
+// seed-if-absent, never overwrite.
+//
+// Both stamps use the CURRENT engine's template. If the app was stamped by an
+// older engine, app-shaped drift from engine evolution surfaces as merges or
+// sidecars — visible, never silent — and the installed lane is the current
+// one (which is what `upgrade --harness` would land anyway).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { colors, ok, warn, fail, step } from "../lib/log.mjs";
+import { consent } from "../bootstrap/exec.mjs";
+import { buildTokenMap } from "../lib/tokens.mjs";
+import {
+  planHarnessUpgrade,
+  applyHarnessPlan,
+  configFromSpecRecord,
+  stampBaseWith,
+  isExcludedPath,
+  SIDECAR_SUFFIX,
+} from "../lib/harness-upgrade.mjs";
+import { listFiles } from "../lib/fsutil.mjs";
+import {
+  writeHarnessLock,
+  checkHarnessIntegrity,
+  describeIntegrity,
+} from "../../packages/harness/src/lib/harness-lock.mjs";
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** The harness version this engine ships (the lane's own package, not the engine's). */
+function shippedHarnessVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "packages/harness/package.json"), "utf8")
+    ).version;
+  } catch {
+    return null;
+  }
+}
+
+function currentEngineVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * The testable core: plan (and optionally apply) the harness install.
+ * Throws on a hopeless setup; never calls process.exit and never prompts.
+ *
+ * @param {object} params
+ * @param {string} params.projectDir absolute path of the app
+ * @param {string} [params.templateDir] template override (tests)
+ * @param {boolean} [params.apply=false] write changes (false = plan only)
+ * @param {(msg:string)=>void} [params.log]
+ * @returns {Promise<{alreadyFull:boolean, plan?:object, result?:object,
+ *           seeded?:string[], record?:object}>}
+ */
+export async function hardenProject({ projectDir, templateDir, apply = false, log = () => {} }) {
+  const specPath = path.join(projectDir, "create-cmp.json");
+  if (!fs.existsSync(specPath)) {
+    throw new Error(
+      `no create-cmp.json under ${projectDir}.\n` +
+        `\`create-cmp harden\` installs the verification harness into a create-cmp-stamped ` +
+        `project and needs the spec-of-record the stamp wrote. Run it from the project root ` +
+        `or pass --target-dir. (For an app that was never stamped by create-cmp, harden ` +
+        `cannot help yet — that is attach mode's territory.)`
+    );
+  }
+  const record = JSON.parse(fs.readFileSync(specPath, "utf8"));
+
+  // Full already: record says harness and the lane's front door is present.
+  // (A full record with a missing lane is a broken tree harden can heal, so
+  // only the conjunction short-circuits.)
+  if (record.harness !== false && fs.existsSync(path.join(projectDir, "qa", "verify.mjs"))) {
+    return { alreadyFull: true, record };
+  }
+
+  const { scaffold } = await import("../scaffold.mjs");
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "create-cmp-harden-"));
+  try {
+    const baseDir = path.join(tmpRoot, "base");
+    const newDir = path.join(tmpRoot, "new");
+    const baseConfig = { ...configFromSpecRecord(record, baseDir), harness: false };
+    const newConfig = { ...configFromSpecRecord(record, newDir), harness: true };
+
+    log("Stamping this app's config MINIMAL (the walk's base)…");
+    await scaffold(baseConfig, { verify: false, ...(templateDir ? { templateDir } : {}) });
+    log("Stamping this app's config FULL (the walk's target)…");
+    await scaffold(newConfig, { verify: false, ...(templateDir ? { templateDir } : {}) });
+
+    const plan = planHarnessUpgrade({
+      baseDir,
+      newDir,
+      projectDir,
+      stampBase: stampBaseWith(buildTokenMap(configFromSpecRecord(record, projectDir))),
+    });
+
+    // App-state seeds the walk excludes by design: present in the full stamp,
+    // absent in the app → copy. Never touches an existing file.
+    const seedPlan = [];
+    for (const abs of listFiles(newDir)) {
+      const rel = path.relative(newDir, abs).split(path.sep).join("/");
+      if (!isExcludedPath(rel)) continue;
+      if (rel === "create-cmp.json" || rel === "local.properties") continue; // ours below / host-specific
+      if (!fs.existsSync(path.join(projectDir, rel))) seedPlan.push(rel);
+    }
+
+    if (!apply) return { alreadyFull: false, plan, seedPlan, record };
+
+    const actionable = plan.entries.filter(
+      (e) => e.write !== null || e.sidecar !== null || e.remove
+    );
+    const result = applyHarnessPlan(projectDir, actionable);
+
+    const seeded = [];
+    for (const rel of seedPlan) {
+      const target = path.join(projectDir, rel);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(path.join(newDir, rel), target);
+      seeded.push(rel);
+    }
+
+    const harnessVersion = shippedHarnessVersion();
+    if (harnessVersion) writeHarnessLock(projectDir, { version: harnessVersion });
+
+    const updated = { ...record, harness: true, engineVersion: currentEngineVersion() };
+    fs.writeFileSync(specPath, JSON.stringify(updated, null, 2) + "\n");
+
+    return { alreadyFull: false, plan, seedPlan, result, seeded, record: updated };
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}
+
+/**
+ * `create-cmp harden [target-dir] [--dry-run] [--yes] [--verify]`
+ * @param {Record<string,string|boolean>} flags
+ * @param {string|undefined} positional optional target dir
+ */
+export async function runHarden(flags, positional) {
+  const targetDir =
+    (typeof flags["target-dir"] === "string" && flags["target-dir"]) || positional || ".";
+  const projectDir = path.resolve(targetDir);
+
+  process.stdout.write(
+    `\n${colors.bold("create-cmp harden")} — install the full verification harness\n` +
+      `  project: ${colors.cyan(projectDir)}\n\n`
+  );
+
+  let outcome;
+  try {
+    // Plan first (side-effect free) so the consent question shows real content.
+    outcome = await hardenProject({ projectDir, log: (m) => step(m) });
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+
+  if (outcome.alreadyFull) {
+    ok("This app already carries the full harness — nothing to install.");
+    process.stdout.write(
+      colors.dim(
+        `  ${describeIntegrity(checkHarnessIntegrity(projectDir))}\n` +
+          `  To refresh the harness to the current engine: npx create-cmp-cli upgrade --harness\n`
+      )
+    );
+    process.exit(0);
+  }
+
+  const { plan, seedPlan } = outcome;
+  const counts = plan.counts;
+  const installing = plan.entries.filter((e) => e.write !== null || e.remove).length;
+  const conflicts = plan.entries.filter((e) => e.sidecar !== null).map((e) => e.relPath);
+  process.stdout.write(
+    `${colors.bold(String(installing))} file(s) to install/refresh · ` +
+      `${colors.bold(String(seedPlan.length))} app-state seed(s) · ` +
+      `${colors.dim(`already current ${counts.current + counts.unchanged}`)}\n`
+  );
+  for (const f of conflicts) {
+    warn(`edited since stamp — full-mode content will land beside as ${f}${SIDECAR_SUFFIX}`);
+  }
+
+  if (installing === 0 && seedPlan.length === 0 && conflicts.length === 0) {
+    ok("Nothing to do — the tree already matches full mode.");
+    process.exit(0);
+  }
+  if (flags["dry-run"] === true) {
+    for (const e of plan.entries) {
+      if (e.write !== null || e.remove || e.sidecar !== null) process.stdout.write(`    ${e.relPath}\n`);
+    }
+    for (const rel of seedPlan) process.stdout.write(`    ${rel} ${colors.dim("(seed)")}\n`);
+    process.stdout.write(`\n${colors.yellow("Dry run")} — nothing written.\n`);
+    process.exit(0);
+  }
+
+  const approved = await consent(
+    `\nInstall the harness (existing files are backed up; edited files get *${SIDECAR_SUFFIX} sidecars, never clobbered)?`,
+    { assumeYes: flags.yes === true }
+  );
+  if (!approved) {
+    process.stdout.write(`${colors.yellow("Not applied")} — re-run with --yes to skip the prompt.\n`);
+    process.exit(0);
+  }
+
+  let applied;
+  try {
+    applied = await hardenProject({ projectDir, apply: true, log: (m) => step(m) });
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+
+  const r = applied.result;
+  for (const f of r.created) ok(`installed ${f}`);
+  for (const f of r.written) ok(`refreshed ${f}`);
+  for (const f of applied.seeded) ok(`seeded ${f}`);
+  for (const f of r.sidecars) warn(`conflict sidecar ${f} — resolve by hand, then delete it`);
+  ok(`create-cmp.json → harness: true · ${describeIntegrity(checkHarnessIntegrity(projectDir))}`);
+
+  process.stdout.write(
+    `\nProve it: ${colors.bold("node qa/verify.mjs --profile scaffold")}` +
+      colors.dim("  (runs now with --verify)\n")
+  );
+  if (flags.verify === true) {
+    const v = spawnSync("node", ["qa/verify.mjs", "--profile", "scaffold"], {
+      cwd: projectDir,
+      stdio: "inherit",
+    });
+    process.exit(v.status === 0 && r.sidecars.length === 0 ? 0 : 1);
+  }
+  process.exit(r.sidecars.length > 0 ? 1 : 0);
+}