create-cmp-cli 0.14.1 → 0.16.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

@@ -537,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;
+}

package/src/lib/minimal.mjs

@@ -0,0 +1,130 @@
+// minimal.mjs — the `--minimal` mode subtraction (LADDER §R3): stamp the app
+// without its verification harness, keeping the eyes.
+//
+// The mode is a FILTER over the one template, never a fork (design invariant:
+// no second artifact to keep green). Three mechanisms, each already owned by
+// the engine, do the whole job:
+//
+//   1. content variance   — `cmp:feature harness` / `!harness` marker blocks
+//                           (CLAUDE.md, AGENTS.md, README, CI workflow, docs),
+//                           stripped by the standard toggle machinery;
+//   2. path subtraction   — manifest `features.harness.paths` for the
+//                           app-owned governance surfaces (specs/, approvals,
+//                           skills, evidence, hooks);
+//   3. lane subtraction   — THIS module, for the machine-owned region: delete
+//                           every machine-owned .mjs EXCEPT the preview
+//                           entry points and their transitive imports.
+//
+// The keep-set is DERIVED by walking import statements from the entry points,
+// never transcribed as a list — a hand-maintained enumeration of qa/lib files
+// is exactly the kind of claim that rots (design invariant 5). What survives
+// in a minimal scaffold is precisely what its own kept scripts can reach.
+//
+// `create-cmp harden` is the inverse: a three-way stamp-merge (base = the
+// minimal stamp, new = the full stamp) that installs the subtraction back —
+// additive, idempotent, never clobbering. See src/commands/harden.mjs.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { listHarnessFiles } from "../../packages/harness/src/lib/harness-region.mjs";
+import { minimalHookSettings } from "./hooks.mjs";
+
+/**
+ * Machine-owned entry points a minimal scaffold keeps: the preview gallery is
+ * the eyes' no-plugin surface (LADDER §R3 keeps previews; the manifest's own
+ * inspector notes already treat it as inspector-owned, not lane-owned).
+ * Entries missing from the tree (e.g. --no-inspector) are skipped.
+ */
+export const MINIMAL_LANE_ENTRY_POINTS = ["qa/preview-gallery.mjs"];
+
+/**
+ * SessionStart context for a minimal scaffold — what is true HERE, and the
+ * one command that adds the rest. No apostrophes: the hook command is
+ * single-quoted for the shell (hooks.mjs enforces this).
+ */
+export const MINIMAL_SESSION_CONTEXT =
+  "This is a create-cmp MINIMAL scaffold: full app architecture with tests, " +
+  "no verification harness. AGENTS.md maps symptoms to commands. Fast signal: " +
+  "./gradlew :composeApp:desktopTest. Headless screen previews: ./gradlew " +
+  ":composeApp:renderScreens then node qa/preview-gallery.mjs. One idempotent " +
+  "command installs the full harness (verify lane, evidence receipts, " +
+  "machine-checked done): npx create-cmp-cli harden.";
+
+// Matches the project's two import forms in lane code: static
+// `from "./lib/x.mjs"` and dynamic `import(new URL("./lib/x.mjs", ...))`.
+// Only ./-relative .mjs specifiers matter — node: and package imports are not
+// files we ship.
+const IMPORT_SPECIFIER_RE = /(?:from\s+|new URL\(\s*)["'](\.\.?\/[^"']+\.mjs)["']/g;
+
+/**
+ * The machine-owned files a minimal scaffold keeps: the entry points plus
+ * their transitive ./-relative imports, resolved against the tree as stamped.
+ * @param {string} projectDir
+ * @returns {Set<string>} project-relative posix paths
+ */
+export function laneKeepSet(projectDir) {
+  const keep = new Set();
+  const queue = MINIMAL_LANE_ENTRY_POINTS.filter((rel) =>
+    fs.existsSync(path.join(projectDir, rel))
+  );
+  while (queue.length > 0) {
+    const rel = queue.pop();
+    if (keep.has(rel)) continue;
+    keep.add(rel);
+    let source;
+    try {
+      source = fs.readFileSync(path.join(projectDir, rel), "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of source.matchAll(IMPORT_SPECIFIER_RE)) {
+      const resolved = path.posix.join(path.posix.dirname(rel), m[1]);
+      if (!keep.has(resolved) && fs.existsSync(path.join(projectDir, resolved))) {
+        queue.push(resolved);
+      }
+    }
+  }
+  return keep;
+}
+
+/**
+ * Delete every machine-owned lane file outside the keep-set.
+ * @param {string} projectDir
+ * @param {(msg:string)=>void} [log]
+ * @returns {string[]} deleted relative paths
+ */
+export function subtractLane(projectDir, log = () => {}) {
+  const keep = laneKeepSet(projectDir);
+  const deleted = [];
+  for (const rel of listHarnessFiles(projectDir)) {
+    if (keep.has(rel)) continue;
+    fs.rmSync(path.join(projectDir, rel));
+    deleted.push(rel);
+  }
+  if (deleted.length > 0) {
+    log(`  removed ${deleted.length} lane file(s) (minimal mode keeps ${[...keep].sort().join(", ") || "none"})`);
+  }
+  return deleted;
+}
+
+/**
+ * Apply minimal mode to a stamped tree: subtract the lane, then rewrite
+ * .claude/settings.json to the derived minimal hook set (enforcement and
+ * lane-advisory hooks gone, SessionStart telling the truth about this
+ * scaffold). Marker stripping and manifest path deletion have already
+ * happened via the standard feature machinery by the time this runs.
+ * @param {string} projectDir
+ * @param {(msg:string)=>void} [log]
+ */
+export function applyMinimalMode(projectDir, log = () => {}) {
+  subtractLane(projectDir, log);
+
+  const settingsPath = path.join(projectDir, ".claude", "settings.json");
+  if (fs.existsSync(settingsPath)) {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    const minimal = minimalHookSettings(settings, { sessionContext: MINIMAL_SESSION_CONTEXT });
+    fs.writeFileSync(settingsPath, JSON.stringify(minimal, null, 2) + "\n");
+    log("  rewrote .claude/settings.json to the advisory-only hook set");
+  }
+}

package/src/lib/toggle.mjs

@@ -86,12 +86,15 @@ export function stripFeatureBlocks(content, disabledFeatures) {
 
 /**
  * Map an engine config object to the set of DISABLED feature names that the
- * manifest understands: ios, firebase, room, e2e, inspector, dev-client.
+ * manifest understands: harness, ios, firebase, room, e2e, inspector,
+ * dev-client. `harness` is the mode split (LADDER §R3): absent means full —
+ * only an explicit `harness: false` (`--minimal`) subtracts it.
  * @param {object} config
  * @returns {Set<string>}
  */
 export function disabledFeaturesFromConfig(config) {
   const disabled = new Set();
+  if (config.harness === false) disabled.add("harness");
   if (!config.platforms?.ios) disabled.add("ios");
   if (!config.firebase?.enabled) disabled.add("firebase");
   if (!config.room) disabled.add("room");

package/src/lib/verify.mjs

@@ -41,8 +41,13 @@ export async function runVerify({ projectDir, manifest, config, dryRun = false }
   const verify = (manifest && manifest.verify) || {};
   const results = [];
 
+  // Minimal mode has no in-app lane to run — its gate is the Gradle tier the
+  // scaffold DOES ship (unit + conformance + golden tests, debug build).
+  const minimal = config?.harness === false;
+  const androidCommand = minimal && verify.androidMinimal ? verify.androidMinimal : verify.android;
+
   const plan = [];
-  if (verify.android) plan.push({ platform: "android", command: verify.android, eligible: true });
+  if (androidCommand) plan.push({ platform: "android", command: androidCommand, eligible: true });
   if (verify.ios) {
     const eligible = isMacOS() && !!config?.platforms?.ios;
     plan.push({ platform: "ios", command: verify.ios, eligible });

package/src/scaffold.mjs

@@ -324,6 +324,7 @@ function writeSpecOfRecord(projectDir, config) {
     bundleId: config.iosBundleId,
     themePrefix: config.themePrefix,
     region: config.region,
+    harness: config.harness !== false,
     platforms: config.platforms,
     firebase: config.firebase,
     room: config.room,
@@ -464,9 +465,25 @@ export async function scaffold(config, opts = {}) {
   if (seeded.length === 0) process.stdout.write("  no configuration deviated from the interview default — nothing to seed\n");
 
   // (e.2) regenerate the architecture doc's derived sections for the tree as
-  // stamped — see regenerateArchDoc above.
+  // stamped — see regenerateArchDoc above. MUST precede the minimal-mode lane
+  // subtraction below: the walker it imports (qa/lib/arch-doc.mjs) is lane
+  // code a minimal scaffold does not keep, and the doc's derived sections
+  // describe composeApp/ (which minimal mode never touches), so regenerating
+  // first is both necessary and correct.
   await regenerateArchDoc(projectDir);
 
+  // (e.3) minimal mode — subtract the machine-owned lane (keeping the preview
+  // entry points + their import closure) and rewrite the hook set to
+  // advisory-only. Marker blocks and manifest paths were already handled by
+  // the standard feature machinery above; this is the part only the engine
+  // can derive. Runs BEFORE writeLaneLock so the lock hashes exactly the
+  // region this app ships.
+  if (config.harness === false) {
+    step("Applying minimal mode (no verification harness)…");
+    const { applyMinimalMode } = await import("./lib/minimal.mjs");
+    applyMinimalMode(projectDir, (m) => process.stdout.write(`${m}\n`));
+  }
+
   // Write local.properties (sdk.dir) so the Gradle build can find the Android
   // SDK even when ANDROID_HOME/ANDROID_SDK_ROOT aren't exported (manifest
   // stampPipeline step 7). Skip silently if no SDK is found and env vars are

package/template/.github/workflows/verify.yml

@@ -1,9 +1,17 @@
 # CI for your Compose Multiplatform app — stamped in by create-cmp.
 #
+# >>> cmp:feature harness
 # What runs on every push/PR: a toolchain report (advisory) and the VERIFY LANE
 # (qa/verify.mjs) — build + unit tests + every other gate this project carries,
 # producing the evidence receipt. Green here = your frozen version set still
 # builds AND the harness's checks pass.
+# <<< cmp:feature harness
+# >>> cmp:feature !harness
+# What runs on every push/PR: a toolchain report (advisory), the JVM test tier
+# (unit + conformance + golden trees), and the Android debug build. This is a
+# minimal scaffold — `npx create-cmp-cli harden` upgrades this workflow to the
+# full verify lane with evidence receipts.
+# <<< cmp:feature !harness
 #
 # iOS: a ready-to-enable macOS job is included (commented out) at the bottom.
 # macOS runners cost ~10x Linux minutes, so it's opt-in.
@@ -36,6 +44,12 @@ jobs:
         continue-on-error: true
         run: npx --yes create-cmp-cli@latest doctor --yes --no-install --no-ios
 
+      # >>> cmp:feature !harness
+      - name: Tests (JVM tier) + debug build
+        run: ./gradlew :composeApp:desktopTest :composeApp:assembleDebug
+      # <<< cmp:feature !harness
+
+      # >>> cmp:feature harness
       # Receipt attests HEAD: the committed evidence receipt (qa/evidence/latest.json)
       # must validly attest the checked-out tree — verdict PASS and the inputs-hash
       # still matching the verified surface — BEFORE we spend a runner re-running the
@@ -62,6 +76,7 @@ jobs:
         with:
           name: verify-evidence
           path: qa/evidence/latest.json
+      # <<< cmp:feature harness
 
   # ── iOS (opt-in) ──────────────────────────────────────────────────────────
   # Uncomment to build the iOS app on every push to main. Uses the exact

package/template/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Mon Jul 06 18:20:40 WAT 2026
+gradle.version=8.11.1

package/template/AGENTS.md

@@ -1,13 +1,62 @@
 # Agent instructions
 
-This repository is agent-first. The full working contract — the definition of done
-(`node qa/verify.mjs` must PASS), the architecture gates, the testing pyramid, and the
-device-free **UI feedback loop** (render every real screen headlessly and see exactly
-what your edit changed) — lives in [CLAUDE.md](./CLAUDE.md).
+<!-- >>> cmp:feature harness -->
+This repository is agent-first, with a verification harness. The working contract — the
+definition of done (`node qa/verify.mjs` must PASS, receipt committed), the architecture
+gates, and the device-free **UI feedback loop** — lives in [CLAUDE.md](./CLAUDE.md).
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+This repository is agent-first. The working guide — the architecture, the commands that
+build and test it, and the device-free **UI feedback loop** — lives in
+[CLAUDE.md](./CLAUDE.md).
+<!-- <<< cmp:feature !harness -->
 
 Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude.
 
-One rule worth knowing before you touch anything: the `.mjs` files directly under `qa/`
-and `qa/lib/` are **machine-owned harness code**, byte-identical in every create-cmp app
-and hash-locked by `qa/harness.lock.json`. Editing them fails the lane's first step. Fix
-the engine upstream instead — see "The lane is not yours to edit" in CLAUDE.md.
+## Stuck? Symptom → command
+
+Every command below runs from the repo root with **nothing to install**: Gradle is
+wrapped, the scripts ship inside this project, and `npx` fetches on demand. The
+create-cmp Claude Code plugin layers better ergonomics over the same capabilities
+(skills, the `cmp-inspector` MCP's structured tools) — an accelerator, never a
+prerequisite.
+
+| Symptom | Run |
+|---|---|
+<!-- >>> cmp:feature harness -->
+| "Did my edit break anything?" | `node qa/verify.mjs --fast` — the inner loop: seconds of JVM-tier signal; never the done-gate |
+| Want that answer on every save | `node qa/watch.mjs` — resident watcher; re-runs the fast tier on save, debounced |
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+| "Did my edit break anything?" | `./gradlew :composeApp:desktopTest` — unit + conformance + golden-tree tests in seconds, no device |
+<!-- <<< cmp:feature !harness -->
+<!-- >>> cmp:feature inspector -->
+| Can't see the UI (no device attached) | `./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs` — every real screen headless: `tree.json` for you to assert on, one gallery page for the human |
+| Need the RUNNING app's real state | `adb forward tcp:9500 tcp:9500`, then `http://127.0.0.1:9500/inspect/remote` — debug builds serve the live semantics tree on loopback |
+<!-- <<< cmp:feature inspector -->
+<!-- >>> cmp:feature harness -->
+| Adding a feature / screen / repository | `node qa/scaffold-feature.mjs <Name>` — clones the tested exemplar through every layer; never freehand the pattern (skills: `add-feature`, `add-screen`, `add-repository`) |
+| A gate failed and looks arbitrary | `node qa/refusal-demo.mjs` — stages canonical violations so each gate names the clause it protects |
+<!-- <<< cmp:feature harness -->
+| 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 |
+<!-- >>> cmp:feature harness -->
+| Ready to claim done | `node qa/verify.mjs` — the full lane, once, deliberately; commit the receipt it writes |
+<!-- <<< cmp:feature harness -->
+
+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>.
+
+<!-- >>> cmp:feature harness -->
+One rule before you edit anything: the `.mjs` files directly under `qa/` and `qa/lib/`
+are **machine-owned** harness code — byte-identical in every create-cmp app and
+hash-locked by `qa/harness.lock.json`. Editing them fails the lane's first step. If the
+lane is wrong, the fix is upstream — see "The lane is not yours to edit" in CLAUDE.md.
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+This is a **minimal scaffold** — no verify lane, receipts, specs, or generators are
+installed. One idempotent command installs the full harness and its machine-checked
+definition of done: `npx create-cmp-cli harden`.
+<!-- <<< cmp:feature !harness -->

package/template/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- >>> cmp:feature harness -->
 # __APP_NAME__ — AI delivery contract
 
 Generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a verification
@@ -422,3 +423,51 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | `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 |
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+# __APP_NAME__ — working guide
+
+Generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) as a **minimal
+scaffold**: the full app architecture and its tests, without the verification harness.
+
+## Build & test
+
+| Command | What |
+|---|---|
+| `./gradlew :composeApp:desktopTest` | Unit + conformance + golden-tree tests (JVM, seconds) |
+| `./gradlew :composeApp:assembleDebug` | Android debug build |
+| `./gradlew :composeApp:installDebug` | Install on the attached device/emulator |
+
+Run `desktopTest` after every change — it carries the architecture gates that keep this
+codebase coherent. Never delete or weaken a failing test to reach green.
+
+## Architecture
+
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) is the working guide: `presentation` →
+`domain` ← `data`; typed errors (`AppResult`, no cross-layer throws); design tokens from
+`presentation/theme/` (no hardcoded values); every screen a `*Screen` composable with a
+tested ViewModel, mirroring the `home` exemplar through every layer.
+<!-- >>> cmp:feature inspector -->
+
+## UI feedback loop — see what you build, without a device
+
+`./gradlew :composeApp:renderScreens` renders every screen in
+`inspector/PreviewRegistry.kt` headlessly (real DI, real theme) to
+`composeApp/build/previews/<id>/{screen.png, tree.json}`; `node qa/preview-gallery.mjs`
+builds one self-contained gallery page. Assert on `tree.json` structure — pixels are for
+humans. Register new screens in the PreviewRegistry.
+
+With a debug build running: `adb forward tcp:9500 tcp:9500`, then
+`http://127.0.0.1:9500/inspect/remote` mirrors the live app with click-to-tap.
+<!-- <<< cmp:feature inspector -->
+
+## What full mode adds
+
+The verification harness: a verify lane (`qa/verify.mjs`) with evidence receipts,
+behavior specs, approval gates, feature generators, and a Stop hook that makes "done"
+machine-checked instead of honor-system. One idempotent command installs it all:
+
+```bash
+npx create-cmp-cli harden
+```
+<!-- <<< cmp:feature !harness -->

package/template/CONTRIBUTING.md

@@ -6,14 +6,27 @@
 2. Make the change — new features mirror the `home` exemplar
    (see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)), with tests at every layer
    (see [`docs/TESTING.md`](./docs/TESTING.md)).
+<!-- >>> cmp:feature harness -->
 3. Run the verify lane: `node qa/verify.mjs`.
 4. Commit **including the updated receipt** (`qa/evidence/latest.json`). A change without a
    PASS receipt is not done — CI re-runs the same lane and will say so.
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+3. Run the tests: `./gradlew :composeApp:desktopTest` must be green (CI re-runs it on
+   every push).
+4. Commit.
+<!-- <<< cmp:feature !harness -->
 5. Open a PR. Keep it one concern; note any intended golden/baseline changes explicitly.
 
 ## Definition of done
 
+<!-- >>> cmp:feature harness -->
 - `node qa/verify.mjs` → **PASS**, receipt committed.
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+- `./gradlew :composeApp:desktopTest` green. (This is a minimal scaffold — the
+  machine-checked definition of done arrives with `npx create-cmp-cli harden`.)
+<!-- <<< cmp:feature !harness -->
 - New behavior has tests; existing tests untouched unless the behavior intentionally changed
   (say so in the PR).
 - No hardcoded design values; testTags on anything E2E needs to reach.