create-cmp-cli 0.11.0 → 0.13.0

package/src/lib/harness-upgrade.mjs

@@ -0,0 +1,364 @@
+// Core logic for `create-cmp upgrade --harness`: refresh the ENGINE-OWNED
+// files of a stamped app after the engine improved.
+//
+// WHY: `create-cmp` stamps an app from template/ and walks away. When the
+// engine later fixes a stamped file (a verify-lane bug, a Gradle wiring fix,
+// a new hook), apps stamped from the OLD engine never receive it — the dead
+// androidDebug/AndroidManifest.xml fixed at engine commit b972c19 was carried
+// by every app this template ever stamped. This module closes that gap with a
+// three-way merge, exactly like dpkg conffile handling or a Yeoman
+// regeneration:
+//
+//   base   = what the engine WOULD have stamped at the version this app was
+//            stamped from (old template + CURRENT stamp pipeline — see below)
+//   new    = what the CURRENT engine stamps
+//   theirs = the app's working tree today
+//
+// Both base and new are produced by stamping with the app's OWN recorded
+// config (create-cmp.json), so tokens (package, app name, theme prefix)
+// resolve identically and every base→new diff is pure engine change.
+//
+// NOTE on the base approximation: base is "old template + current pipeline".
+// When the stamp PIPELINE itself changed between versions (tokenization,
+// marker stripping), base can differ from what the old engine literally
+// produced. This is deliberate — running old engine code against a current
+// config is strictly worse — and only affects files whose tokenization
+// changed; those surface as conflicts rather than silent clobbers.
+//
+// App-authored files (the app's own feature screens) appear in neither base
+// nor new, so they are INVISIBLE to this sweep — by design. The sweep only
+// ever considers paths the engine stamped at one version or the other.
+//
+// Pure decision logic lives here so tests can drive it with in-memory/temp
+// fixtures and zero npm network access; CLI + npm-pack orchestration lives in
+// src/commands/upgrade.mjs. No dependencies beyond the Node stdlib (git is
+// already a hard requirement of this repo).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { listFiles } from "./fsutil.mjs";
+import { isBinaryPath } from "./tokens.mjs";
+import { BACKUP_SUFFIX } from "./upgrade.mjs";
+
+/** Sidecar suffix for the new engine content beside a conflicted file. */
+export const SIDECAR_SUFFIX = ".cmp-new";
+
+/**
+ * Hard exclusion list — the app's own state, or its secrets, that the engine
+ * also seeds. A diff here is noise or danger, never an upgrade. Matched
+ * against the project-relative path (posix separators):
+ *   - a bare name (no `/`) matches that basename at ANY depth — this is what
+ *     keeps `keystore.properties` and `google-services.json` excluded wherever
+ *     they live (e.g. composeApp/google-services.json), because those files
+ *     must never be read, written, or printed by this code;
+ *   - `dir/**` matches everything under `dir` (root-anchored);
+ *   - `**` + `/dir/` + `**` matches everything under a `dir` segment at any depth;
+ *   - `**` + `/name` matches that basename at any depth.
+ */
+export const EXCLUDED_PATTERNS = [
+  "create-cmp.json",
+  "qa/evidence/**",
+  "qa/approvals.json",
+  "qa/comments.json",
+  "qa/golden/**",
+  ".git/**",
+  "build/**",
+  "**/build/**",
+  ".gradle/**",
+  "local.properties",
+  "keystore.properties",
+  "google-services.json",
+  "**/GoogleService-Info.plist",
+];
+
+/**
+ * Does one exclusion pattern match a project-relative posix path?
+ * @param {string} relPath project-relative path, "/"-separated
+ * @param {string} pattern one of EXCLUDED_PATTERNS (see grammar above)
+ * @returns {boolean}
+ */
+export function matchesPattern(relPath, pattern) {
+  if (pattern.endsWith("/**")) {
+    const dir = pattern.slice(0, -3);
+    if (dir.startsWith("**/")) {
+      // "**/build/**": any DIRECTORY segment equal to the name.
+      const seg = dir.slice(3);
+      return relPath.split("/").slice(0, -1).includes(seg);
+    }
+    return relPath === dir || relPath.startsWith(dir + "/");
+  }
+  if (pattern.startsWith("**/")) {
+    const name = pattern.slice(3);
+    return relPath === name || relPath.endsWith("/" + name);
+  }
+  if (!pattern.includes("/")) {
+    // Bare name: basename match at any depth (never risk touching a nested
+    // secret because it wasn't at the root).
+    return relPath === pattern || relPath.endsWith("/" + pattern);
+  }
+  return relPath === pattern;
+}
+
+/**
+ * Is this project-relative path on the hard exclusion list?
+ * Checked BEFORE any file content is read — excluded files (state, secrets)
+ * are never opened by this module.
+ * @param {string} relPath project-relative path, "/"-separated
+ * @returns {boolean}
+ */
+export function isExcludedPath(relPath) {
+  return EXCLUDED_PATTERNS.some((p) => matchesPattern(relPath, p));
+}
+
+/**
+ * Three-way merge via `git merge-file -p --diff3 <theirs> <base> <new>`.
+ * The three sides are written to temp files; git's exit code is 0 for a clean
+ * merge, >0 for the number of conflicts, <0 / spawn error for trouble — both
+ * of the latter are treated as a conflict (the caller then writes a sidecar
+ * instead of touching the app's file, so "treat as conflict" is always safe).
+ * @param {Buffer} theirs the app's current content
+ * @param {Buffer} base the old engine's stamped content
+ * @param {Buffer} next the current engine's stamped content
+ * @returns {{clean: boolean, content: Buffer|null}} merged content when clean
+ */
+export function mergeThreeWay(theirs, base, next) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cmp-harness-merge-"));
+  try {
+    const t = path.join(dir, "theirs");
+    const b = path.join(dir, "base");
+    const n = path.join(dir, "new");
+    fs.writeFileSync(t, theirs);
+    fs.writeFileSync(b, base);
+    fs.writeFileSync(n, next);
+    const r = spawnSync("git", ["merge-file", "-p", "--diff3", t, b, n], {
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.error || r.status === null || r.status !== 0) {
+      return { clean: false, content: null };
+    }
+    return { clean: true, content: r.stdout };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The decision table — one file, three sides, one verdict. Buckets:
+ *   unchanged   engine never changed it (base == new)         → silent
+ *   current     app already matches the new engine            → silent
+ *   applied     app never touched it, engine changed it       → write new
+ *   merged      both changed, three-way merge is clean        → write merged
+ *   conflicted  both changed the same region (or binary, or the app deleted
+ *               a file the engine changed) → NEVER clobber: leave the app's
+ *               file byte-for-byte alone, emit a `.cmp-new` sidecar with the
+ *               new engine's content
+ *   added       new engine file absent from the app           → write new
+ *   removed     engine deleted it and the app never touched it → delete
+ *   orphaned    engine deleted it but the app modified it     → keep, report
+ *
+ * Binary files (isBinaryPath) never three-way merge: replace when the app
+ * never touched them, otherwise conflicted.
+ *
+ * @param {object} params
+ * @param {string} params.relPath project-relative path (for binary sniffing)
+ * @param {Buffer|null} params.base old engine's content (null = not stamped then)
+ * @param {Buffer|null} params.next current engine's content (null = engine deleted it)
+ * @param {Buffer|null} params.theirs the app's content (null = absent in the app)
+ * @param {(theirs:Buffer, base:Buffer, next:Buffer)=>{clean:boolean,content:Buffer|null}} [params.merge]
+ *        three-way merge fn, injectable for tests (default: git merge-file)
+ * @returns {{bucket:string, write:Buffer|null, sidecar:Buffer|null, remove:boolean}|null}
+ *        null when the path is in neither base nor new (app-authored — invisible)
+ */
+export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay }) {
+  const none = (bucket) => ({ bucket, write: null, sidecar: null, remove: false });
+  const write = (bucket, content) => ({ bucket, write: content, sidecar: null, remove: false });
+  const conflict = () => ({ bucket: "conflicted", write: null, sidecar: next, remove: false });
+  const eq = (a, b) => a !== null && b !== null && a.equals(b);
+
+  if (base !== null && next !== null) {
+    if (eq(base, next)) return none("unchanged"); // engine never changed it
+    // Engine changed it:
+    if (theirs === null) return conflict(); // app deleted it — never resurrect silently
+    if (eq(theirs, next)) return none("current"); // already up to date
+    if (eq(theirs, base)) return write("applied", next); // app never touched it
+    // All three differ:
+    if (isBinaryPath(relPath)) return conflict(); // binaries never merge
+    const m = merge(theirs, base, next);
+    if (m.clean && m.content !== null) {
+      // A merge that reproduces the app's file byte-for-byte means the app
+      // already carries the engine change (e.g. a previous --harness run) —
+      // report current, keep re-runs idempotent and quiet.
+      if (m.content.equals(theirs)) return none("current");
+      return write("merged", m.content);
+    }
+    return conflict();
+  }
+
+  if (base === null && next !== null) {
+    // New engine file.
+    if (theirs === null) return write("added", next);
+    if (eq(theirs, next)) return none("current");
+    return conflict(); // the app already has something different there
+  }
+
+  if (base !== null && next === null) {
+    // Engine deleted it.
+    if (theirs === null) return none("current"); // already gone
+    if (eq(theirs, base)) return { bucket: "removed", write: null, sidecar: null, remove: true };
+    return none("orphaned"); // app modified it — keep it, report it
+  }
+
+  return null; // in neither base nor new: app-authored, invisible to the sweep
+}
+
+function readIfPresent(dir, relPath) {
+  try {
+    return fs.readFileSync(path.join(dir, relPath));
+  } catch {
+    return null;
+  }
+}
+
+function toRel(root, abs) {
+  return path.relative(root, abs).split(path.sep).join("/");
+}
+
+/**
+ * Walk base ∪ new, classify every path through the decision table, and return
+ * the full plan. Excluded paths are counted WITHOUT ever reading their
+ * content (state files and secrets stay unopened). Reads the three trees but
+ * never writes anything — applying is applyHarnessPlan's job.
+ * @param {object} params
+ * @param {string} params.baseDir stamped tree of the old engine
+ * @param {string} params.newDir stamped tree of the current engine
+ * @param {string} params.projectDir the app's working tree
+ * @param {Function} [params.merge] three-way merge fn, injectable for tests
+ * @returns {{entries: Array<{relPath:string, bucket:string, write?:Buffer|null,
+ *            sidecar?:Buffer|null, remove?:boolean}>,
+ *            counts: Record<string, number>}}
+ */
+export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay }) {
+  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));
+
+  const counts = {
+    excluded: 0,
+    unchanged: 0,
+    current: 0,
+    applied: 0,
+    merged: 0,
+    conflicted: 0,
+    added: 0,
+    removed: 0,
+    orphaned: 0,
+  };
+  const entries = [];
+  for (const relPath of [...rels].sort()) {
+    if (isExcludedPath(relPath)) {
+      counts.excluded += 1;
+      entries.push({ relPath, bucket: "excluded", write: null, sidecar: null, remove: false });
+      continue;
+    }
+    const decision = decideFile({
+      relPath,
+      base: readIfPresent(baseDir, relPath),
+      next: readIfPresent(newDir, relPath),
+      theirs: readIfPresent(projectDir, relPath),
+      merge,
+    });
+    if (decision === null) continue;
+    counts[decision.bucket] += 1;
+    entries.push({ relPath, ...decision });
+  }
+  return { entries, counts };
+}
+
+/**
+ * Apply a plan to the app's working tree. Every file that gets written over
+ * or deleted is backed up first as `<file>${BACKUP_SUFFIX}` (same suffix as
+ * the version-catalog upgrade path, so one revert story covers both modes).
+ * Conflicted entries never touch the app's file — only the `.cmp-new` sidecar
+ * is written. Returns what happened so the CLI can print revert commands.
+ * @param {string} projectDir
+ * @param {Array<{relPath:string, bucket:string, write:Buffer|null, sidecar:Buffer|null, remove:boolean}>} entries
+ * @returns {{written:string[], created:string[], deleted:string[],
+ *            sidecars:string[], backups:string[]}}
+ *   written  rel paths overwritten (backup exists)
+ *   created  rel paths newly created (no previous content, no backup)
+ *   deleted  rel paths removed (backup exists)
+ *   sidecars rel paths of `.cmp-new` files written beside conflicts
+ *   backups  rel paths that have a `${BACKUP_SUFFIX}` copy
+ */
+export function applyHarnessPlan(projectDir, entries) {
+  const written = [];
+  const created = [];
+  const deleted = [];
+  const sidecars = [];
+  const backups = [];
+  for (const e of entries) {
+    const abs = path.join(projectDir, e.relPath);
+    if (e.sidecar !== null && e.sidecar !== undefined) {
+      const sidecarPath = abs + SIDECAR_SUFFIX;
+      fs.mkdirSync(path.dirname(sidecarPath), { recursive: true });
+      fs.writeFileSync(sidecarPath, e.sidecar);
+      sidecars.push(e.relPath + SIDECAR_SUFFIX);
+      continue;
+    }
+    if (e.remove) {
+      fs.copyFileSync(abs, abs + BACKUP_SUFFIX);
+      backups.push(e.relPath);
+      fs.rmSync(abs);
+      deleted.push(e.relPath);
+      continue;
+    }
+    if (e.write !== null && e.write !== undefined) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      if (fs.existsSync(abs)) {
+        fs.copyFileSync(abs, abs + BACKUP_SUFFIX);
+        backups.push(e.relPath);
+        fs.writeFileSync(abs, e.write);
+        written.push(e.relPath);
+      } else {
+        fs.writeFileSync(abs, e.write);
+        created.push(e.relPath);
+      }
+    }
+  }
+  return { written, created, deleted, sidecars, backups };
+}
+
+/**
+ * Reconstruct the engine config from a parsed create-cmp.json record.
+ * Key names differ slightly (record: name/bundleId ↔ config:
+ * appName/iosBundleId). Fields the record predates default to
+ * "feature absent" — a record written before a toggle existed describes an
+ * app whose tree does NOT carry that feature, so stamping without it mirrors
+ * the app best.
+ * @param {object} record parsed create-cmp.json
+ * @param {string} targetDir where the reconstructed stamp should land
+ * @returns {object} engine config (options.schema.json shape)
+ */
+export function configFromSpecRecord(record, targetDir) {
+  return {
+    appName: record.name,
+    package: record.package,
+    iosBundleId: record.bundleId,
+    region: record.region ?? "us-central1",
+    themePrefix: record.themePrefix,
+    platforms: record.platforms ?? { android: true, ios: true },
+    firebase: record.firebase ?? { enabled: false },
+    room: record.room ?? false,
+    e2e: record.e2e ?? false,
+    inspector: record.inspector ?? false,
+    devClient: record.devClient ?? false,
+    tabs: record.tabs ?? [
+      { label: "Home", icon: "home" },
+      { label: "Profile", icon: "person" },
+    ],
+    targetDir,
+  };
+}

package/src/lib/package-name.mjs

@@ -0,0 +1,72 @@
+// Semantic validation for the `package` option, beyond what the JSON-schema
+// pattern in options.schema.json can express.
+//
+// The pattern already enforces the SHAPE of a reverse-DNS id (lowercase start,
+// at least two segments, no digit-leading segments). What it cannot encode is
+// that every segment also has to be a legal *Java identifier*: the value
+// becomes the Android namespace and the Kotlin package, and AGP rejects a
+// reserved word outright —
+//
+//   Namespace 'com.final.proof' is not a valid Java package name as 'final'
+//   is a Java keyword
+//
+// Observed for real: `--package com.final.proof` was accepted, stamped a full
+// project, and only failed at the first Gradle configure — late, and as a raw
+// Gradle stack rather than an input error. Refuse it at the door instead, and
+// name the offending segment.
+
+// Java SE reserved words (JLS §3.9), plus the three reserved literals and the
+// lone underscore (reserved since Java 9). `var`/`yield`/`record`/`sealed` and
+// friends are contextual, not reserved — they are legal package segments, so
+// they are deliberately absent.
+export const JAVA_KEYWORDS = new Set([
+  "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
+  "class", "const", "continue", "default", "do", "double", "else", "enum",
+  "extends", "final", "finally", "float", "for", "goto", "if", "implements",
+  "import", "instanceof", "int", "interface", "long", "native", "new",
+  "package", "private", "protected", "public", "return", "short", "static",
+  "strictfp", "super", "switch", "synchronized", "this", "throw", "throws",
+  "transient", "try", "void", "volatile", "while",
+  // reserved literals
+  "true", "false", "null",
+  // reserved identifier (Java 9+)
+  "_",
+]);
+
+/**
+ * Segments of `pkg` that cannot be Java identifiers.
+ * @param {string} pkg
+ * @returns {string[]} offending segments, in source order (may repeat)
+ */
+export function reservedSegments(pkg) {
+  if (typeof pkg !== "string" || pkg.length === 0) return [];
+  return pkg.split(".").filter((seg) => JAVA_KEYWORDS.has(seg));
+}
+
+/**
+ * Validate the package id's segments. Same error shape as schema.mjs's
+ * validate(), so callers can merge the two lists and format them together.
+ * @param {string} pkg
+ * @param {string} [path] error path label
+ * @returns {{ valid: boolean, errors: Array<{path: string, message: string}> }}
+ */
+export function validatePackageName(pkg, path = "package") {
+  const bad = reservedSegments(pkg);
+  if (bad.length === 0) return { valid: true, errors: [] };
+  const uniq = [...new Set(bad)];
+  const which = uniq.map((s) => `'${s}'`).join(", ");
+  const lead = uniq.length > 1
+    ? `segments ${which} are Java keywords and cannot be package segments`
+    : `segment ${which} is a Java keyword and cannot be a package segment`;
+  return {
+    valid: false,
+    errors: [
+      {
+        path,
+        message:
+          `${lead} — Gradle will refuse the namespace. Rename it ` +
+          `(e.g. com.final.proof \u2192 com.finalproof).`,
+      },
+    ],
+  };
+}

package/src/scaffold.mjs

@@ -18,6 +18,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { validate, formatErrors } from "./lib/schema.mjs";
+import { validatePackageName } from "./lib/package-name.mjs";
 import { buildTokenMap, replaceTokens, replacePathTokens, isBinaryPath, slugifyAppName } from "./lib/tokens.mjs";
 import { renamePackageDirs } from "./lib/rename.mjs";
 import {
@@ -51,8 +52,12 @@ export function loadSchema(opts = {}) {
  */
 export function validateConfig(config, opts = {}) {
   const schema = loadSchema(opts);
-  const { valid, errors } = validate(config, schema);
-  if (!valid) {
+  const { errors } = validate(config, schema);
+  // The schema pattern proves the SHAPE of the package id; this proves its
+  // segments are legal Java identifiers. Merged into one list so a config with
+  // both problems reports both at once.
+  errors.push(...validatePackageName(config?.package).errors);
+  if (errors.length > 0) {
     const err = new Error(`Invalid config:\n${formatErrors(errors)}`);
     err.validationErrors = errors;
     throw err;

package/template/.claude/settings.json

@@ -1,5 +1,35 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"This app is governed by its delivery contract (CLAUDE.md): behavior starts in specs/, done is `node qa/verify.mjs` with a committed receipt, approvals gate signed artifacts. The cmp-inspector MCP tools (preview loop, live tier) are the expected eyes — if they are absent from this session, that is a fault to diagnose (plugin disabled, session predates plugin enablement, or stale plugin copy; see cmp-doctor), not a cue to fall back to screenshots or blind adb.\"}}'"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "grep -qE 'screencap|uiautomator dump' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: raw pixels/blind taps lose structure. If cmp-inspector is connected, inspect_tree reads the semantic tree and navigate_and_inspect gives verified taps; if its tools are missing, diagnose first (cmp-doctor, Inspector MCP section).\"}}' || true"
+          },
+          {
+            "type": "command",
+            "command": "grep -qE 'connected[A-Za-z]*AndroidTest|maestro test|adb (-s [^ ]+ )?(install|uninstall)' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: device evidence is lane-owned and batched. node qa/verify.mjs sequences the device steps once, last, under a machine-global per-serial lease (qa/lib/device-lease.mjs) — the one device is scarce, slow, and fragile, so device proof is a checkpoint, never an inner loop. Driving it by hand mid-task risks colliding with a running lane (wedged adbd, device offline, false reds, crossed app state). Ad-hoc debugging stays allowed; batch the evidence into the lane.\"}}' || true"
+          },
+          {
+            "type": "command",
+            "command": "in=$(cat); printf '%s' \"$in\" | grep -qE 'node qa/verify\\.mjs' && ! printf '%s' \"$in\" | grep -q -- '--fast' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: for inner-loop iteration, node qa/verify.mjs --fast skips the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke) and is much quicker. Run the full lane once, deliberately, before reporting work done — never speculatively, and never to re-confirm a result you already have. A --fast receipt never satisfies the done-gate.\"}}' || true"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "",

package/template/CLAUDE.md

@@ -15,7 +15,10 @@ tests, and gates the whole tree to produce the receipt, so it is slow by design;
 after every edit wastes the minutes it takes. Iterate on the fast tier, and run the lane
 once — when you believe the change is done.
 
-- **Inner loop — run continuously (seconds):** the preview loop (below) for UI, and
+- **Inner loop — run continuously (seconds):** the preview loop (below) for UI;
+  `node qa/watch.mjs` for verification — a resident watcher that re-runs the fast tier
+  (`node qa/verify.mjs --fast`) on every save and re-prints the step table, so the
+  did-I-break-anything signal is free the way an IDE's errors-on-save are free; and
   `./gradlew :composeApp:desktopTest` for the unit tests your change touches. This is where
   you catch your own mistakes.
 - **Checkpoint — run once, at done:** `node qa/verify.mjs`. It writes the receipt; commit
@@ -85,9 +88,25 @@ the tree. The governed `architecture` artifact (below) hashes the document along
 - Never delete, weaken, or `@Ignore` a failing test to reach green. Fix the behavior — or,
   if the test itself is wrong, say so in your summary and justify the change.
 
+**Platform behavior tests live in `composeApp/src/androidInstrumentedTest`** — when a
+feature touches alarms, notifications, lock-screen intents, or audio routing, its behavior
+test goes there, because no desktop tier can see those OS facts. Assertion helpers:
+`NotificationAsserts`, `AlarmAsserts`, `SystemState`. **Runtime state control** — put the
+device into the state your claim is about, instead of waiting for it: `TimeWarp` (clock,
+timezone), `DozeControl` (forced idle), `PermissionControl`, `ProcessControl`,
+`NetworkControl`, `ConfigControl` (dark mode, font scale, per-app locale). They compose —
+the exemplar proves an `allowWhileIdle` alarm delivers from inside forced deep idle by
+nesting a clock warp in a Doze bracket. Exemplars: `PlatformBehaviorSeamTest`,
+`RuntimeStateSeamTest`. Each organ's header states what it does NOT reproduce; read it
+before claiming more than it proves. The lane's `androidChecks` step runs them when a
+device is attached; see `docs/TESTING.md`.
+
 ## Evidence
 
 `node qa/verify.mjs` writes `qa/evidence/latest.json` (schema: `qa/evidence/schema.json`).
+Each PASS receipt names its **evidence rung** (L0 scaffold / L1 desktop / L2 device /
+L3 release), derived from which steps actually ran and passed — never declared, and a
+SKIPped step never upgrades it (see `docs/TESTING.md` §"The evidence ladder").
 Commit it with your change; git history is the audit ledger. Binary artifacts under
 `qa-artifacts/` are hashed into the receipt, never committed. The studio console's Evidence
 page reconstructs the full audit trail from the git log of `latest.json` — every commit is
@@ -305,16 +324,35 @@ and tells you what your edit changed.
 3. `preview_diff { screen }` proves the change in one call: `proven-clean` /
    `changed-with-regressions` / `no-change`. No snapshot bookkeeping.
 
-**Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
-`composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
-`node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
+**If the tools are missing:** capability absence is a fault to diagnose and report — never
+a silent fallback. If ToolSearch finds no `cmp-inspector` tools, STOP and tell the human
+which it is: the plugin is disabled (`enabledPlugins` in `~/.claude/settings.json` or the
+project settings); the session predates the plugin's enablement (MCP servers attach at
+session start — restart the session; no in-session retry will surface them); or the plugin
+copy is stale/broken (run cmp-doctor's inspector-MCP check group). Report before degrading.
+
+**Degraded path** — for environments where the plugin is genuinely unavailable (CI, other
+agents), and only after the fault is reported: `./gradlew :composeApp:renderScreens` renders
+every screen to `composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>`
+for one); `node qa/preview-gallery.mjs` builds a self-contained gallery page from the
+output. What this loses: on-save re-render, changed-screen attribution, compile errors
+in-band, and the `preview_diff` change proof — structured feedback replaced by pixels.
 
 **Live tier — the human's live device view (standing step).** Whenever `connect_live`
 succeeds, OFFER the `remoteUrl` it returns (`http://127.0.0.1:9500/inspect/remote`) to the
 human — every time, not as a maybe. It is a self-contained browser page that mirrors the
 running app (~700ms refresh) with click-to-tap driving the real device: they watch and drive
-the actual app while you assert on the tree (`navigate_and_inspect` / `prove_change` /
-`db_query`). It is also the right way for a human to *watch* an e2e run.
+the actual app while you assert on the tree (`navigate_and_inspect` — its before/after delta
+is the change proof live — and `inspect_tree`). It is also the right way for a human to
+*watch* an e2e run.
+
+Asserting persisted state: `db_query` reads bounded rows from the running app's database;
+use it when a flow's proof is a row existing (or not) after an action, instead of shelling
+into sqlite or trusting the UI.
+
+When the app crashes or misbehaves on device: `runtime_crashes` returns persisted crashes
+with cause attribution and `runtime_logs` bounded structured logcat for the app's pid; use
+these before hand-grepping `adb logcat`.
 
 Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature` and
 `add-screen` stampers auto-register stamped screens at the `// cmp:anchor preview-registry`
@@ -342,8 +380,15 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | Command | What |
 |---|---|
 | `node qa/verify.mjs` | The verify lane (profile `local`) — the done checkpoint, run once |
+| `node qa/verify.mjs --fast` | **Inner loop — NOT the done-gate**: skips the device/release tier (`releaseBuild`, `tokenDrift`, `e2eSmoke`, `androidChecks`, `releaseSmoke`), reuses unchanged pure-Node step results (`CACHED`, content-hashed inputs), and scopes unit tests to the working-tree change (broad-impact changes — build files, DI, theme, shared components, `qa/` — run the full suite). Its receipt records `"mode": "fast"`, earns no evidence rung, and the Stop hook refuses it — run the full lane once at done |
+| `node qa/watch.mjs` | **Resident inner loop — never a gate**: watches `composeApp/src`, `specs/`, `qa/` and re-runs `node qa/verify.mjs --fast` on save (debounced — a save storm is one run; defers while a verify lane or a preview render holds the project). `--once` for a single pass, `--json` for line-per-run output. The done-gate stays one deliberate full `node qa/verify.mjs` run |
 | `./gradlew :composeApp:desktopTest` | Unit tests only (fast inner loop) |
 | `node qa/setup-hooks.mjs` | Enable the pre-push receipt gate (one-time, after `git init`) |
 | `./gradlew :composeApp:assembleDebug` | Android debug build |
 | `./gradlew :composeApp:assembleRelease` | Android release build — R8 + `lintVital`, the variant the lane's `releaseBuild` step proves. Produces an **unsigned** APK; signing needs a keystore, which is yours to create and keep out of the repo. |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |
+| `./gradlew :composeApp:connectedDebugAndroidTest` | Instrumented behavior tests on the attached device (the lane's `androidChecks` step) |
+| `node qa/verify.mjs --profile release` | Ship-time lane: everything `ci` proves plus the audit-cadence report (`auditCadence` — which androidMain subsystems changed since their last recorded `cmp-audit`; a nudge, never a gate) and the release-APK Maestro smoke (`releaseSmoke`) |
+| `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 |

package/template/README.md

@@ -1,5 +1,9 @@
 # __APP_NAME__
 
+<!-- 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 -->
+
 A Kotlin / Compose Multiplatform app, generated by
 [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a **verification harness**:
 the architecture, testing conventions, and definition of done are enforced mechanically, not