create-cmp-cli 0.14.0 → 0.15.0

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

package/src/commands/upgrade.mjs

@@ -43,7 +43,8 @@ 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 { LOCAL_PATCH_PATH, stampBaseWith } from "../lib/harness-upgrade.mjs";
+import { buildTokenMap } from "../lib/tokens.mjs";
 import {
   planHarnessUpgrade,
   applyHarnessPlan,
@@ -341,11 +342,28 @@ async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRo
     templateDir: baseTemplateDir,
     verify: false,
   });
-  const plan = planHarnessUpgrade({ baseDir, newDir, projectDir });
+  // Engines before 0.14.0 ran lane code through the token stamper, so an app
+  // stamped by one carries `Fuelled` where the base template says
+  // `__APP_NAME__`. Without this the migration would report the engine's own
+  // substitution as if the app had forked the lane.
+  const plan = planHarnessUpgrade({
+    baseDir,
+    newDir,
+    projectDir,
+    stampBase: stampBaseWith(buildTokenMap(configFromSpecRecord(record, projectDir))),
+  });
 
   const anythingToDo = printHarnessReport(plan);
   if (!anythingToDo) {
     ok("Engine-owned files are fully up to date — nothing to apply.");
+    // Still advance the record. An app that is ALREADY at the new engine is as
+    // upgraded as it can be, and leaving engineVersion stale here would keep
+    // the very defect this write-back exists to fix: the next run would fetch
+    // an obsolete merge base and re-litigate changes that already landed. Not
+    // on a dry run — that promises to write nothing.
+    if (flags["dry-run"] !== true && writeBackEngineVersion(projectDir, currentVersion)) {
+      ok(`create-cmp.json engineVersion → ${colors.bold(currentVersion)}`);
+    }
     return 0;
   }
 

package/src/lib/adr-seed.mjs

@@ -57,6 +57,33 @@ function renderAdr(number, title, body, dateIso) {
 // true, room true, firebase.auth "both") — matching every default seeds
 // nothing beyond the shipped four; only a genuine choice gets a record.
 const DECISION_RULES = [
+  {
+    id: "mode",
+    applies: (config) => config.harness === false,
+    title: () => "Minimal scaffold — verification harness deferred",
+    render: () => ({
+      context:
+        "create-cmp stamps the full verification harness by default: the verify lane " +
+        "(`qa/verify.mjs`) with evidence receipts, behavior specs (`specs/`), approval " +
+        "gates, feature generators, and a Stop hook making the definition of done " +
+        "machine-checked. This app was scaffolded `--minimal` — a deliberate choice to " +
+        "start with the smallest thing that builds green, deferring the harness rather " +
+        "than rejecting it.",
+      decision:
+        "We will start without the verification harness. The app keeps its full " +
+        "architecture, unit/conformance/golden tests (`./gradlew :composeApp:desktopTest`), " +
+        "headless previews, the live inspector, and advisory session hooks; it carries no " +
+        "verify lane, receipts, specs, approvals, generators, or enforcement hooks.",
+      consequences:
+        "- The definition of done is honor-system: green `desktopTest` plus review, with " +
+          "no receipt attesting what actually ran.\n" +
+        "- No spec-first behavior flow and no generators — new features are written by " +
+          "hand against `docs/ARCHITECTURE.md`.\n" +
+        "- Reversing this is one idempotent command, not a re-scope: " +
+          "`npx create-cmp-cli harden` installs the full harness and this ADR is " +
+          "superseded by that act.",
+    }),
+  },
   {
     id: "persistence",
     applies: (config) => config.room === false,

package/src/lib/harness-upgrade.mjs

@@ -40,7 +40,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { listFiles } from "./fsutil.mjs";
-import { isBinaryPath } from "./tokens.mjs";
+import { isBinaryPath, replaceTokens } from "./tokens.mjs";
 import { BACKUP_SUFFIX } from "./upgrade.mjs";
 import { isHarnessFile } from "../../packages/harness/src/lib/harness-region.mjs";
 
@@ -178,6 +178,23 @@ export function mergeThreeWay(theirs, base, next) {
  *        null when the path is in neither base nor new (app-authored — invisible)
  */
 
+
+/**
+ * A `stampBase` function for an app's recorded config — reproduces what a
+ * pre-0.14.0 engine would have written into that app's lane, so a file the
+ * stamper touched is not mistaken for a local edit. Binary-safe: content that
+ * does not round-trip through UTF-8 is returned unchanged.
+ * @param {Array<[string,string]>} tokenMap from buildTokenMap(config)
+ * @returns {(base: Buffer) => Buffer}
+ */
+export function stampBaseWith(tokenMap) {
+  return (base) => {
+    const text = base.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(base)) return base;
+    return Buffer.from(replaceTokens(text, tokenMap), "utf8");
+  };
+}
+
 /** Where a preserved local patch to machine-owned lane code is written. */
 export const LOCAL_PATCH_PATH = "qa/harness-local.patch";
 
@@ -253,7 +270,7 @@ export function diffPatch(base, theirs, relPath) {
  * @param {Function} [params.merge] injectable three-way merge (classifier only)
  * @returns {{bucket:string, write:Buffer|null, sidecar:null, remove:boolean, patch?:string}|null}
  */
-export function decideRegionFile({ relPath, base, next, theirs, merge = mergeThreeWay }) {
+export function decideRegionFile({ relPath, base, next, theirs, merge = mergeThreeWay, stampBase = null }) {
   const eq = (a, b) => a !== null && b !== null && a.equals(b);
   const replace = (bucket, extra = {}) => ({
     bucket,
@@ -274,6 +291,19 @@ export function decideRegionFile({ relPath, base, next, theirs, merge = mergeThr
   if (base === null) return replace("region-patched", { patch: "" }); // no base to diff against
   if (eq(theirs, base)) return replace("region-clean");
 
+  // The app's copy may be what its OWN engine produced rather than what the
+  // base tree holds, because engines before 0.14.0 ran lane code through the
+  // token stamper. Such an app carries `Fuelled` where the base template says
+  // `__APP_NAME__` — a difference the engine created, not the app. Asking
+  // "does this match the base as THIS app would have had it stamped?" is the
+  // accurate form of "did the app never touch it", and it needs no version
+  // comparison: for a 0.14.0+ base there is nothing left to stamp, so the
+  // check simply never fires.
+  if (stampBase !== null) {
+    const asStamped = stampBase(base);
+    if (eq(theirs, asStamped)) return replace("region-clean");
+  }
+
   // The app edited lane code. Is that edit already carried by the new engine?
   // A clean three-way merge landing exactly on `next` means the local change
   // contributed nothing beyond it — the hand-mirror case.
@@ -283,10 +313,10 @@ export function decideRegionFile({ relPath, base, next, theirs, merge = mergeThr
   return replace("region-patched", { patch: diffPatch(base, theirs, relPath) });
 }
 
-export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay }) {
+export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay, stampBase = null }) {
   // Machine-owned lane files answer a different question — see decideRegionFile.
   if (isHarnessFile(relPath) && !(base === null && next === null)) {
-    return decideRegionFile({ relPath, base, next, theirs, merge });
+    return decideRegionFile({ relPath, base, next, theirs, merge, stampBase });
   }
   const none = (bucket) => ({ bucket, write: null, sidecar: null, remove: false });
   const write = (bucket, content) => ({ bucket, write: content, sidecar: null, remove: false });
@@ -355,7 +385,7 @@ function toRel(root, abs) {
  *            sidecar?:Buffer|null, remove?:boolean}>,
  *            counts: Record<string, number>}}
  */
-export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay }) {
+export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay, stampBase = null }) {
   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));
@@ -390,6 +420,7 @@ export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeT
       next: readIfPresent(newDir, relPath),
       theirs: readIfPresent(projectDir, relPath),
       merge,
+      stampBase,
     });
     if (decision === null) continue;
     counts[decision.bucket] = (counts[decision.bucket] ?? 0) + 1;
@@ -506,6 +537,10 @@ export function configFromSpecRecord(record, targetDir) {
     iosBundleId: record.bundleId,
     region: record.region ?? "us-central1",
     themePrefix: record.themePrefix,
+    // Deliberately the OPPOSITE default from the feature toggles below: every
+    // app stamped before the mode split carries the full harness, so an
+    // absent `harness` key means full, not absent.
+    harness: record.harness ?? true,
     platforms: record.platforms ?? { android: true, ios: true },
     firebase: record.firebase ?? { enabled: false },
     room: record.room ?? false,

package/src/lib/hooks.mjs

@@ -0,0 +1,140 @@
+// hooks.mjs — the advisory/enforcement split for a stamped project's hook set.
+//
+// The template's .claude/settings.json is not one thing. It carries three
+// kinds of hook, and telling them apart IS the product's Act 2 / Act 3 line:
+//
+//   ENFORCEMENT — the Stop hook (qa/receipt-check.mjs --hook). It can refuse
+//     to let a session claim "done" without a fresh PASS receipt. It is the
+//     harness's teeth, it presupposes the lane, and it ships only in full
+//     mode. Classified BY EVENT: Stop/SubagentStop are where Claude Code can
+//     block, so any hook registered there is enforcement by construction.
+//
+//   LANE ADVISORY — wall-time nudges whose command text names `qa/` (the
+//     verify-fast reminder, the device-lease reminder). They constrain
+//     nothing, but they presuppose the lane: in a scaffold without qa/ they
+//     would advertise commands the agent cannot run. A discovery surface that
+//     lies is worse than one that is absent, so these ship only where the
+//     lane does. Classified by reference: naming the lane is depending on it.
+//
+//   PORTABLE ADVISORY — everything else that informs (the screenshots-lose-
+//     structure nudge). True in every mode; ships in every mode. An advisory
+//     hook always resolves to permissionDecision "allow" — if a future
+//     PreToolUse hook wanted to DENY, that is an enforcement decision to make
+//     deliberately here, not a string to pattern-match.
+//
+// SessionStart is deliberately exempt from the lane-reference rule, and the
+// distinction is not a special case but the actual difference between the two
+// kinds of hook. A PreToolUse nudge is a fixed instruction that fires at a
+// wall: its command IS the advice, so a command naming qa/ can only be kept
+// or dropped. SessionStart's command is a `printf` of narration that the
+// stamper AUTHORS PER MODE — it is the one hook whose content is a variable,
+// so it is never dropped for describing the full mode's lane; it is rewritten
+// to describe the mode actually being stamped. Dropping it instead (the first
+// cut of this module did) left a minimal scaffold with no opening context at
+// all, which is the silence this whole discovery layer exists to prevent.
+//
+// Every function is pure: settings in, new settings out, input never mutated.
+
+export const ENFORCEMENT_EVENTS = new Set(["Stop", "SubagentStop"]);
+
+/** Events whose hooks can constrain the agent (vs inform it). */
+export function isEnforcementEvent(event) {
+  return ENFORCEMENT_EVENTS.has(event);
+}
+
+/** Does this hook's command presuppose the verify lane (`qa/`)? */
+export function referencesLane(hook) {
+  return String(hook?.command ?? "").includes("qa/");
+}
+
+/**
+ * Events whose hook command is narration the stamper rewrites per mode,
+ * rather than a fixed instruction that fires at a wall. These are never
+ * dropped for naming the lane — they are re-authored. See the header.
+ */
+const REWRITTEN_EVENTS = new Set(["SessionStart"]);
+
+/**
+ * Classify one hook: "enforcement" | "lane-advisory" | "advisory".
+ * @param {string} event the settings.hooks key the hook is registered under
+ * @param {object} hook one entry of a group's `hooks` array
+ */
+export function classifyHook(event, hook) {
+  if (isEnforcementEvent(event)) return "enforcement";
+  if (REWRITTEN_EVENTS.has(event)) return "advisory";
+  if (referencesLane(hook)) return "lane-advisory";
+  return "advisory";
+}
+
+/**
+ * Remove hooks matching `drop(event, hook)`; drop groups and events left
+ * empty, so the result is an honest hook set rather than a skeleton of empty
+ * arrays. Tolerates malformed shapes by passing them through untouched.
+ */
+function filterHooks(settings, drop) {
+  const out = structuredClone(settings);
+  if (!out || typeof out.hooks !== "object" || out.hooks === null) return out;
+  for (const [event, groups] of Object.entries(out.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!Array.isArray(group?.hooks)) continue;
+      group.hooks = group.hooks.filter((h) => !drop(event, h));
+    }
+    out.hooks[event] = groups.filter((g) => !Array.isArray(g?.hooks) || g.hooks.length > 0);
+    if (out.hooks[event].length === 0) delete out.hooks[event];
+  }
+  return out;
+}
+
+/**
+ * The hook set with enforcement removed — advisory hooks (both kinds) pass
+ * through byte-identical. Idempotent; input never mutated.
+ * @param {object} settings parsed .claude/settings.json content
+ */
+export function stripEnforcementHooks(settings) {
+  return filterHooks(settings, (event) => isEnforcementEvent(event));
+}
+
+/**
+ * Build a SessionStart hook command that prints `context` as
+ * additionalContext, in the exact shape the template's own hook uses
+ * (`printf '%s'` around a single-quoted JSON payload). The payload is
+ * single-quoted for the shell, so the copy must carry no apostrophe — that is
+ * a constraint on the author of the copy, enforced here rather than escaped
+ * around, so the stamped command stays trivially auditable.
+ * @param {string} context
+ */
+export function sessionStartCommand(context) {
+  if (context.includes("'")) {
+    throw new Error(
+      "SessionStart context must not contain an apostrophe (the command is single-quoted for the shell) — reword the copy"
+    );
+  }
+  const payload = JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context },
+  });
+  return `printf '%s' '${payload}'`;
+}
+
+/**
+ * The minimal-mode hook set, DERIVED from the full one rather than kept as a
+ * second file to hold in sync (light is a filter, not a fork). Three edits:
+ *
+ *   (a) enforcement goes — the Stop hook is Act 3;
+ *   (b) lane-advisory goes — a nudge naming qa/ presupposes the lane;
+ *   (c) SessionStart says what is true HERE — `sessionContext` describes what
+ *       this scaffold carries and the one command that adds the rest.
+ *
+ * @param {object} settings parsed .claude/settings.json content
+ * @param {object} opts
+ * @param {string} opts.sessionContext additionalContext for the SessionStart hook
+ */
+export function minimalHookSettings(settings, { sessionContext }) {
+  const out = filterHooks(settings, (event, hook) => classifyHook(event, hook) !== "advisory");
+  if (!out || typeof out.hooks !== "object" || out.hooks === null) return out;
+  for (const group of out.hooks.SessionStart ?? []) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const hook of group.hooks) hook.command = sessionStartCommand(sessionContext);
+  }
+  return out;
+}