create-cmp-cli 0.14.0 → 0.15.0

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/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.

package/template/README.md

@@ -1,5 +1,6 @@
 # __APP_NAME__
 
+<!-- >>> cmp:feature harness -->
 <!-- cmp:generated evidence -->
 [![No evidence receipt](https://img.shields.io/badge/evidence-none_yet-9E9E9E)](https://github.com/kvdm-co-pilot/create-cmp) — no verify receipt yet. Run `node qa/verify.mjs`.
 <!-- /cmp:generated -->
@@ -9,6 +10,14 @@ A Kotlin / Compose Multiplatform app, generated by
 the architecture, testing conventions, and definition of done are enforced mechanically, not
 by convention. Start with [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md); AI collaborators
 follow the contract in [`CLAUDE.md`](./CLAUDE.md).
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+A Kotlin / Compose Multiplatform app, generated by
+[create-cmp](https://github.com/kvdm-co-pilot/create-cmp) as a **minimal scaffold**: the
+full app architecture with its tests, without the verification harness (one command adds
+it — see "Full mode" below). Start with [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md);
+AI collaborators follow the guide in [`CLAUDE.md`](./CLAUDE.md).
+<!-- <<< cmp:feature !harness -->
 
 ## Quick start
 
@@ -29,8 +38,10 @@ follow the contract in [`CLAUDE.md`](./CLAUDE.md).
 # Unit tests (fast inner loop)
 ./gradlew :composeApp:desktopTest
 
+<!-- >>> cmp:feature harness -->
 # The verify lane — build + tests + every shipped gate, with an evidence receipt
 node qa/verify.mjs
+<!-- <<< cmp:feature harness -->
 ```
 
 <!-- >>> cmp:feature inspector -->
@@ -55,7 +66,9 @@ before shipping — from Claude Code, the `cmp-firebase-connect` skill drives it
 ## Project structure
 
 ```
+<!-- >>> cmp:feature harness -->
 specs/                       behavior specifications — new behavior starts here
+<!-- <<< cmp:feature harness -->
 composeApp/src/commonMain/   shared UI + logic (presentation / domain / data / di)
 composeApp/src/commonTest/   unit tests — exemplar pattern in presentation/home
 composeApp/src/desktopTest/  conformance gates + Compose UI tests + golden trees (JVM tier)
@@ -66,8 +79,10 @@ composeApp/src/iosMain/      iOS actuals · iosApp/ is the Xcode shell
 <!-- >>> cmp:feature dev-client -->
 composeApp/src/desktopMain/  desktop dev-client (see docs/dev-client.md)
 <!-- <<< cmp:feature dev-client -->
+<!-- >>> cmp:feature harness -->
 qa/verify.mjs                the verify lane — this repo's definition of done
 qa/evidence/latest.json      the committed evidence receipt (see CONTRIBUTING.md)
+<!-- <<< cmp:feature harness -->
 <!-- >>> cmp:feature e2e -->
 qa/e2e/                      Maestro E2E flows (device smoke)
 <!-- <<< cmp:feature e2e -->
@@ -82,9 +97,26 @@ docs/                        architecture, testing, ADRs
 | [`docs/TESTING.md`](./docs/TESTING.md) | The test pyramid, conventions, how to run everything |
 | [`docs/adr/`](./docs/adr/) | Architecture decision records |
 | [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Workflow, definition of done, commit style |
+<!-- >>> cmp:feature harness -->
 | [`CLAUDE.md`](./CLAUDE.md) | The AI delivery contract |
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+| [`CLAUDE.md`](./CLAUDE.md) | The AI working guide |
+<!-- <<< cmp:feature !harness -->
 | [`CHANGELOG.md`](./CHANGELOG.md) | Notable changes (Keep a Changelog) |
 
+<!-- >>> cmp:feature !harness -->
+## Full mode
+
+This scaffold is deliberately light: no verify lane, evidence receipts, behavior specs,
+approval gates, or generators. The full harness — a machine-checked definition of done,
+with an audit trail — installs in place, idempotently, with one command:
+
+```bash
+npx create-cmp-cli harden
+```
+<!-- <<< cmp:feature !harness -->
+<!-- >>> cmp:feature harness -->
 ## Verification
 
 Every change must pass the verify lane (`node qa/verify.mjs`) and commit its updated receipt
@@ -115,6 +147,7 @@ in [`.claude/settings.json`](./.claude/settings.json) — nothing else depends o
 CI independently enforces the same "receipt attests HEAD" check on every push
 (`.github/workflows/verify.yml`), so disabling the local hook only trades an immediate
 signal for a later one.
+<!-- <<< cmp:feature harness -->
 
 ---
 

package/template/docs/ARCHITECTURE.md

@@ -1,17 +1,29 @@
 # Architecture
 
+<!-- >>> cmp:feature harness -->
 > **Reading this document.** Every normative sentence below carries a tier tag.
 > `[enforced: CLAUSE-ID]`: a named gate in `node qa/verify.mjs` fails the lane on violation.
 > `[governed]`: the sentence lives inside a hash-bound human approval (`qa/approvals.json`);
 > changing it without re-approval fails the `approvals` gate. `[advisory]`: a documented
 > convention with no mechanical check yet. Every sentence is law, signed intent, or advice —
 > and says which.
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+> **Reading this document.** Every normative sentence below carries a tier tag.
+> `[enforced: CLAUSE-ID]`: a named source-scanning gate in the desktopTest conformance
+> suite fails the tests on violation. `[governed]` / `[advisory]`: conventions this
+> minimal scaffold checks by review, not by machine — the full harness
+> (`npx create-cmp-cli harden`) adds the mechanical gates.
+<!-- <<< cmp:feature !harness -->
 
 ## 1. Purpose & quality goals
 
+<!-- >>> cmp:feature harness -->
 This app's purpose, audience, and shape are recorded in [`specs/intent.md`](../specs/intent.md)
 — the root brief this document, the component registry, and the exemplar feature all trace
-back to. The table below is the default quality-goal set a fresh scaffold ships with. The
+back to.
+<!-- <<< cmp:feature harness -->
+The table below is the default quality-goal set a fresh scaffold ships with. The
 genesis walk's architecture conversation is where a human promotes, demotes, or replaces
 them for this app's actual priorities ("offline matters more than a11y for a field-work
 app").
@@ -423,6 +435,11 @@ demotes to a regular feature. To add a feature, mirror the exemplar exactly:
    empty/content split) (+ test using a fake from `testing/fakes/`).
 4. DI: register in `di/AppModule.kt`.
 5. Navigation: add the route in `presentation/navigation/`.
+<!-- >>> cmp:feature harness -->
 6. Run `node qa/verify.mjs` — done means PASS + committed receipt.
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+6. Run `./gradlew :composeApp:desktopTest` — green is the bar this scaffold can check.
+<!-- <<< cmp:feature !harness -->
 
 Significant decisions get an ADR in [`docs/adr/`](./adr/) — see the template there.

package/template/docs/TESTING.md

@@ -13,12 +13,20 @@ copy their shape.
 <!-- >>> cmp:feature e2e -->
 | E2E smoke (few) | `qa/e2e/*.yaml` (Maestro) | `maestro test qa/e2e/smoke.yaml` |
 <!-- <<< cmp:feature e2e -->
+<!-- >>> cmp:feature harness -->
 | The lane (all of it) | `qa/verify.mjs` | `node qa/verify.mjs` |
 
 Every durable test cites the spec clause it verifies (`// SPEC: HOME-02` — see
 [`specs/`](../specs/README.md)); **new behavior begins as a spec clause.** The lane's
 `specCoverage` step enforces this: it fails on orphan clauses (no citing test) and orphan tags
 (no matching clause, or one citing a withdrawn clause).
+<!-- <<< cmp:feature harness -->
+<!-- >>> cmp:feature !harness -->
+
+Durable tests may cite a spec clause id in a comment (`// SPEC: HOME-02`) — the shipped
+tests do. This minimal scaffold carries no `specs/` directory or coverage gate; both
+arrive with `npx create-cmp-cli harden`.
+<!-- <<< cmp:feature !harness -->
 
 ## Unit conventions
 
@@ -140,6 +148,7 @@ one: a search assert that passed standalone failed in-lane behind a 33s type gap
 asserts are for static post-navigation elements only.
 <!-- <<< cmp:feature e2e -->
 
+<!-- >>> cmp:feature harness -->
 ## The verify lane
 
 `node qa/verify.mjs` is the definition of done: spec coverage → build → unit tests →
@@ -235,3 +244,4 @@ rung is the coarse grade; the per-step list stays the fine print. A FAILed lane
 | **L1 desktop** | Full static + JVM evidence: build, unit tests, conformance, golden trees, a11y, release COMPILE, and the pure-Node gates. | That the app runs on a device at all — no APK was installed or driven; platform behavior (alarms, notifications) is invisible from this rung. |
 | **L2 device** | L1 plus executed on-device evidence: the debug APK installed and driven (`e2eSmoke`), instrumented platform assertions (`androidChecks`), and/or live token drift. | That the release variant behaves (R8 differs from debug — that is L3's job), nor that alarms/notifications actually land unless an instrumented behavior test asserts them. |
 | **L3 release** | L2 plus `releaseSmoke` PASSed: the signed release APK installed and driven on a device. | Real-backend behavior (the emulator/dev backend is a documented tier boundary — see the instrumented-tier section) and store-review compliance. |
+<!-- <<< cmp:feature harness -->

package/template/manifest.json

@@ -57,6 +57,18 @@
     "whenDisabled": "Remove the marker lines AND the body between them."
   },
   "features": {
+    "harness": {
+      "enabledByDefault": true,
+      "paths": [
+        "specs",
+        ".claude/skills",
+        ".githooks",
+        "qa/approvals.json",
+        "qa/comments.json",
+        "qa/evidence"
+      ],
+      "notes": "The verification harness — the mode split (`--minimal` disables it; `create-cmp harden` installs it back). Three mechanisms share the subtraction, each already owned by the engine: (1) the paths above delete the app-owned governance surfaces (specs/, approvals+comments ledgers, evidence, generator skills, the pre-push receipt hook); (2) `cmp:feature harness`/`!harness` marker blocks give CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md, docs/TESTING.md and .github/workflows/verify.yml their two honest renderings from one file; (3) the machine-owned lane region is subtracted by the ENGINE (src/lib/minimal.mjs), which keeps qa/preview-gallery.mjs plus its transitive qa/lib imports — derived from import statements, never listed here, so it cannot rot. .claude/settings.json is rewritten to the advisory-only hook set via the src/lib/hooks.mjs classifier (Stop hook and qa/-referencing nudges are full-mode only). qa/golden/ stays in BOTH modes — the desktopTest golden-tree tests read it and minimal keeps the full JVM test tier. qa/e2e is its own feature and stays orthogonal (Maestro flows run standalone)."
+    },
     "ios": {
       "enabledByDefault": true,
       "paths": [
@@ -113,6 +125,7 @@
   },
   "verify": {
     "android": "node qa/verify.mjs --profile scaffold",
+    "androidMinimal": "./gradlew :composeApp:desktopTest :composeApp:assembleDebug",
     "androidBuildOnly": "./gradlew :composeApp:assembleDebug",
     "androidSmoke": "./gradlew :composeApp:installDebug && maestro test qa/e2e/smoke.yaml",
     "iosLink": "./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64",

package/template/qa/lib/harness-lock.mjs

@@ -8,7 +8,7 @@
 //              Answered LOCALLY, offline, on every lane run. Needs nothing
 //              but the tree and this file.
 //
-//   AUTHENTICITY  "is my lane the real published create-cmp-harness@X?"
+//   AUTHENTICITY  "is my lane the real published @create-cmp/harness@X?"
 //              Answered REMOTELY, on request, by comparing this file's
 //              `sha256` against the published version's — `create-cmp
 //              upgrade --harness` does it, and so can any third party
@@ -61,7 +61,7 @@ export function readHarnessLock(root) {
  * @param {{name?: string, version: string}} harness identity to record
  * @returns {{sha256: string, fileCount: number}}
  */
-export function writeHarnessLock(root, { name = "create-cmp-harness", version }) {
+export function writeHarnessLock(root, { name = "@create-cmp/harness", version }) {
   if (typeof version !== "string" || version.length === 0) {
     throw new Error("writeHarnessLock: a harness version is required");
   }

package/template/qa/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/template/qa/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/template/qa/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);