create-cmp-cli 0.10.1 → 0.12.0

package/README.md

@@ -76,7 +76,7 @@ http://127.0.0.1:9500/inspect/remote
 A self-contained page mirrors the running app (~700ms refresh) and **click-to-tap drives the
 real thing** — clicks scale to device pixels and dispatch as taps. This is the "two audiences,
 one app" split at its purest: the human watches and drives real pixels in a browser while the
-agent asserts on the semantics tree (`navigate_and_inspect`, `prove_change`, `db_query`). Use
+agent asserts on the semantics tree (`navigate_and_inspect`, `inspect_tree`, `db_query`). Use
 it to watch an e2e run, demo a feature, or poke at the app without touching the device. No
 install, no CORS, debug builds only — release builds contain none of this code.
 
@@ -161,11 +161,11 @@ Same engine as the CLI, conversational front door. Each skill is a guided flow,
 | `cmp-test` | "Write tests for my app." *Observes* the running app's semantics tree — what's actually on screen, what's tappable, where navigation goes — and derives the regression suite from that. Tests come from rendered reality, not guesses. |
 | `cmp-qa-prep` | "Get my test environment up." Emulator + app install + E2E smoke run, with the gotchas handled. |
 
-Plus the **`cmp-inspector` MCP server** (26 tools) — the machine-readable window into a running
+Plus the **`cmp-inspector` MCP server** (15 tools — deliberately few; two production apps proved a lean surface gets used and a wide one gets ignored) — the machine-readable window into a running
 Compose UI that `cmp-inspect`, `cmp-test`, and the verified dev loop are built on. One tree
 contract, three sources: render a screen headlessly, connect to the live app, or read a device
 via UIAutomator. It also carries the runtime half of the agent's eyes (crashes, logs, DB state —
-`runtime_crashes`, `runtime_logs`, `db_schema`, `db_query`), the human-approval console
+`runtime_crashes`, `runtime_logs`, `db_query`), the human-approval console
 (`approval_status`, §8 below), the console's talk-back channel (`review_comments`,
 `resolve_comment`, §9 below), and the genesis walk's design-language workbench
 (`snapshot_variant`, §8 below).
@@ -313,7 +313,7 @@ scaffolded app carries the whole loop):
 `./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`.
 
 **The verified dev loop (the flagship).** For any UI change: snapshot the live tree → make the
-edit → reload → `prove_change` compares before/after structure, token drift, and a11y, and returns
+edit → reload → `preview_diff` compares before/after structure, token drift, and a11y, and returns
 a verdict. The agent doesn't say "I centered the title" — it shows *"title bounds moved, tokens
 unchanged, no a11y regressions: proven clean."*
 
@@ -338,11 +338,13 @@ standalone gate. All of it works on any KMP project.
   generation and mechanical work to sub-agents with self-contained briefs, then **gates every
   hand-off through the verify lane** before accepting it. Nothing is reported done on prose —
   only on a receipt.
-- **The MCP tools** are how any agent *sees*: `inspect_tree`, `get_node`, `assert_token`,
-  `layout_gaps`, `diff_against_design_system`, `find_drift`, `snapshot_save`, `snapshot_diff`,
-  `audit_a11y`, `connect_live`, `navigate_and_inspect`, `render_tree`, `render_screen`,
-  `prove_change`. Structure in, structure out — never pixels in model context. The same eyes
-  extend to runtime behavior (`runtime_crashes`, `runtime_logs`, `db_schema`, `db_query`), to
+- **The MCP tools** are how any agent *sees*: `inspect_tree` (one tree contract — subtree by
+  `testTag`, wireframe rendering, layout-gap reporting as options), `connect_live`
+  (self-healing: device → forward → health → launch → transport reset), `navigate_and_inspect`,
+  `render_screen`, and the preview loop (`preview`, `preview_status`, `preview_diff`).
+  Structure in, structure out — never pixels in model context. Token drift, a11y, and golden
+  regressions are the verify lane's job, not interactive tools. The same eyes
+  extend to runtime behavior (`runtime_crashes`, `runtime_logs`, `db_query`), to
   the human side of the loop (`approval_status`, blocking on a console decision the same way
   `preview_status` blocks on a render), and to the console's talk-back channel
   (`review_comments`, `resolve_comment` — the agent observes feedback and closes the loop with a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {

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/lib/tabs.mjs

@@ -527,6 +527,8 @@ const PLACEHOLDER_REL =
 const PREVIEW_REGISTRY_REL =
   "composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt";
 const SMOKE_REL = "qa/e2e/smoke.yaml";
+const PROFILE_FEATURE_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/profile";
 
 /**
  * Rewrite every tab-driven surface present in the copied project dir. Runs
@@ -576,4 +578,28 @@ export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
     fs.writeFileSync(smokePath, renderSmokeYaml(infos));
     log(`  tabs → ${SMOKE_REL}`);
   }
+
+  // A shipped default feature the config did NOT ask for must not be left on
+  // disk: rewriteNavHost drops its import and its appTabs() entry, and
+  // renderPreviewRegistryKt drops its preview, so the files would sit there
+  // wired to nothing — dead code the reachability gate (qa/lib/reachability.mjs)
+  // correctly FAILs at `--verify` time. Don't ship what you don't wire.
+  //
+  // `profile` is the only one: it is a self-contained stub screen (one file, no
+  // ViewModel, no spec clauses, no DI entry, no tests), so removing it leaves
+  // nothing dangling.
+  //
+  // `home` is deliberately NEVER stripped, even when it is not a configured tab.
+  // It is the governed EXEMPLAR (`qa/approvals.json`'s exemplarFeature — the file
+  // set `qa/scaffold-feature.mjs` clones and the genesis walk approves), and it
+  // owns `DetailScreen`, which AppNavHost registers as a destination
+  // unconditionally. So it stays both governed and reachable with no tab of its
+  // own — removing it would break the genesis walk and dangle the Detail route.
+  if (!infos.some((t) => t.slug === "profile")) {
+    const profilePath = path.join(projectDir, PROFILE_FEATURE_REL);
+    if (fs.existsSync(profilePath)) {
+      fs.rmSync(profilePath, { recursive: true, force: true });
+      log(`  tabs → removed ${PROFILE_FEATURE_REL} (no profile tab configured)`);
+    }
+  }
 }

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/skills/add-feature/SKILL.md

@@ -19,6 +19,26 @@ description: >-
 > feature to its real shape. You are not done until `node qa/verify.mjs` PASSes and the receipt
 > is committed — see this project's `CLAUDE.md`.
 
+## Step 0 — name the lane, out loud, before anything else
+
+Every post-genesis change enters through one of two lanes (`CLAUDE.md` §"After genesis"),
+and **the human must be told which one this request is taking, in your first reply** — one
+or two plain sentences before any tool runs: what you understood the change to be, which
+lane, and why. Never route silently; the human can overrule the triage in a word.
+
+- **Brief lane** — the request carries decisions a future contributor could plausibly
+  "simplify" away, or blast radius into other governed artifacts. Say so, e.g.: *"This
+  carries real decisions (day-boundary rules, scheduling semantics) — I'll draft a feature
+  brief at `docs/features/<name>.md` with the open decisions for you to close and sign
+  BEFORE I stamp anything."* Only after the brief is signed does this skill's stamping
+  start — and if the feature has a UI surface, the **design gate comes next, before the
+  spec**: draft the screens on stub data, render them, and stop for the human's signature
+  on `feature-design:<name>` (brief → design → spec → build). A human signs rendered
+  screens, never a description of screens.
+- **Direct lane** — an ordinary feature with no decisions worth recording. Say so, e.g.:
+  *"Straightforward slice, no decisions worth a brief — direct lane: spec clauses for your
+  confirmation, then I stamp and prove."* Then continue with Step 1 below.
+
 ## The clone source is configurable
 
 The stamper clones from the project's **configured exemplar** — `qa/approvals.json`'s

package/template/.claude/skills/add-repository/SKILL.md

@@ -24,6 +24,12 @@ to just the 5 data/domain files. Use it when you want the data layer to exist be
 consumes it (e.g. you're modeling several entities up front, or a screen for this entity will
 come later via `add-screen`).
 
+**Name the lane first, out loud.** Before any tool runs, tell the human in a sentence which
+lane this request takes (`CLAUDE.md` §"After genesis"): an entity carrying decisions worth
+recording (data-model semantics, boundary rules) goes through a feature brief
+(`docs/features/<name>.md`, signed before code); an ordinary entity is direct lane — say so,
+then continue here. Never route silently.
+
 ## Why a stamper and not hand-written files
 
 Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs

package/template/.claude/skills/add-screen/SKILL.md

@@ -25,6 +25,12 @@ the 6 presentation+tests+spec files, **composed on top of an entity that already
 `add-repository` or a prior `add-feature` run). If the entity doesn't exist yet, this will refuse
 to stamp anything — see step 2.
 
+**Name the lane first, out loud.** Before any tool runs, tell the human in a sentence which
+lane this request takes (`CLAUDE.md` §"After genesis"): a screen carrying decisions worth
+recording or blast into signed artifacts goes through a feature brief
+(`docs/features/<name>.md`, signed before code); an ordinary screen is direct lane — say
+so, then continue here. Never route silently.
+
 ## Why a stamper and not hand-written files
 
 Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs

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
@@ -111,6 +130,12 @@ a provisional palette carries the build until then).
    the `cmp-new` interview; the seed's placeholder prose is marked unfilled. Its
    `## Glossary` section is lifted verbatim into `docs/ARCHITECTURE.md` §8 — write it there
    in the exact form you want published.
+0.5. **First feature brief** — `docs/features/<exemplar>.md`, drafted from the interview's
+   "first screens" answer the moment intent is signed: the first feature's decisions and
+   their why, signed BEFORE its spec is written. Genesis runs the same decide → contract →
+   build loop as every later change; the app's first feature gets the same decide step
+   every later feature gets. (Express lane: skipped honestly, never fabricated;
+   placeholders earn a brief when they become real.)
 1. **Architecture + structure** — `specs/app-base.spec.md` **and**
    [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) (`cmp:generated` sections stripped
    before hashing, so a mechanical regeneration never invalidates the approval — only an
@@ -131,16 +156,88 @@ a provisional palette carries the build until then).
 6. **Per-feature spec** — `specs/<feature>.spec.md`, one governed artifact per feature,
    added as features land.
 
+### After genesis — every change is the same loop
+
+Genesis governs the app's birth. Everything after runs the SAME loop — decide →
+contract → build → prove → sign — over a subset (`docs/CHANGE-FLOW-DESIGN.md` in the
+create-cmp repo is the doc of record). Two lanes, one triage rule — and **the triage is
+always visible**: your FIRST reply to any change request (new feature, edit, bug fix, copy
+tweak, redesign — every entry point) states in one or two plain sentences what you
+understood the change to be, which lane it takes, and why, before any tool runs. The human
+can overrule the lane in a word; a silent route is a routing error even when the lane was
+right.
+
+**Brief lane** — when the change carries **decisions a future contributor could plausibly
+"simplify" away** ("the day boundary is configurable, default 04:00 — not midnight") OR
+**blast radius into other governed artifacts**. After naming the lane:
+
+| Step | What |
+|---|---|
+| 1 | **Feature brief** — `docs/features/<name>.md`: the decisions with their why, research, rejected options, an **Open decisions** section until the human closes each. Signed BEFORE code. |
+| 2 | **Design** — iff the feature has a UI surface (`"screens": true`, or screen files exist): draft the screens on STUB data, register them in the PreviewRegistry, render, and STOP. The human judges the rendered screens and signs `feature-design:<name>`. Never ask a human to approve a described UI. |
+| 3 | **Contract** — reopen any signed spec the brief amends (`--reopen feature-spec:<surface> --reason "…"`); write the clauses where the behavior lives — about the form that now exists; the human signs |
+| 4 | Build the slice (`add-feature` / preview loop). Declared blast lands "as declared"; re-approve touched visual artifacts on rendered output (wiring the signed screens from stub to real state drifts `feature-design:<name>` — its re-approval is that pass) |
+| 5 | Prove — nothing to do: the lane's gates + receipt ARE the proof |
+| 6 | The human's `--accept` — enabled only at provenDone AND a signed design |
+
+**Direct lane** — everything else (bug fix, copy edit, tweak): confirm in chat, reopen →
+amend clause → re-approve if a signed contract is touched, build, lane once at done.
+Legacy features never get retro-briefs; spikes are ungoverned until they become real.
+
+**A brief's LOCATION is the governance opt-in**: every `docs/features/*.md` is a governed
+`feature-brief:<name>` artifact (hash-bound at signing; `<name>` pairs with
+`specs/<name>.spec.md`). `docs/proposals/` stays ungoverned. The brief carries at most one
+machine-read block, and it **declares — it never gates**:
+
+```json cmp:feature
+{ "touches": ["components", "design-system"], "screens": true }
+```
+
+`touches` is the declared blast radius — the artifact hashes already enforce; declaring
+lets the console show "components re-approval, as planned" instead of an unexplained
+failure, and surface **undeclared blast** when something drifted that no open brief
+accounted for. `screens: true` declares a UI surface: it holds the design gate
+(`feature-design:<name>` — the feature's own `presentation/<name>/*Screen.kt`, signed on
+rendered output) before any screen file exists; once files exist, disk is ground truth
+regardless. Both declare — neither gates.
+
+**Doneness is DERIVED, never claimed.** There is no `--deliver` and no checks block —
+deliberately (they existed and were removed as a weaker parallel truth). A feature is
+`provenDone` when, mechanically: its spec has live clauses **and** every one is cited by a
+test **and** the latest receipt is PASS **and** the receipt's `inputs.hash` attests the
+tree as it stands. `--status` and the console print the same one-line `doneReason` either
+way. What remains for humans is judgment: signing the brief (before code) and accepting
+the feature (after proof — "the proven thing is what I wanted"); `--accept` is refused
+until the derivation holds. Acceptance lives on the ledger row, never in the doc (the
+signed bytes must not move when the human accepts).
+
+| Command | What |
+|---|---|
+| `node qa/approve.mjs feature-brief:<name>` | the human signs the brief (before code) |
+| `node qa/approve.mjs --accept <name>` | the human's bookend; refused until provenDone |
+
+Editing a feature is the same brief **reopened** — `--reopen-feature <name> --reason "…"`
+reopens the brief + its spec + its design + the set it declared, as ONE recorded change;
+re-approval is one walk back. Every reopen **requires a `--reason`** (it walks back a
+signature; the signer reads why from the ledger itself) and is journaled with `via` — the
+append-only journal (`qa/approvals.log.jsonl`, printed by `--log`, shown in the console
+strip's History) is how "what happened while I was away" stays answerable.
+
 | Command | What |
 |---|---|
 | `node qa/approve.mjs --status` | Every governed artifact with live state (`unreviewed` / `approved` / `changed-since-approval` / `reopened`), short hash, mode badge |
 | `node qa/approve.mjs <artifact>` | Record approval — hashes the artifact's files now, stamps the time; also clears a `defaults-accepted` mode |
 | `node qa/approve.mjs --accept-defaults` | **Express lane**: approve every currently-resolvable artifact in one visible act, each stamped `"mode": "defaults-accepted"` — build now, walk the definition later. Unresolvable artifacts are skipped with the standard refusal printed. The ledger never pretends the defaults were designed. |
-| `node qa/approve.mjs --reopen <artifact>` | Move an *approved* artifact (shaped or defaults-accepted) back to `reopened` for deliberate redesign — recorded (`reopenedAt`). Refuses unknown ids and anything not currently approved. |
+| `node qa/approve.mjs --reopen <artifact> --reason "…"` | Move an *approved* artifact (shaped or defaults-accepted) back to `reopened` for deliberate redesign. `--reason` is REQUIRED and recorded (`reopenedAt`, `via`, `reason` — on the row and in the journal). Refuses unknown ids and anything not currently approved. |
+| `node qa/approve.mjs --reopen-feature <name> --reason "…"` | ONE recorded change: reopens the brief + `feature-spec:<name>` + `feature-design:<name>` + every declared `touches` artifact (each only if currently approved), all under one reason. |
+| `node qa/approve.mjs --log` | The governance journal — every approve/reopen/accept with when, which surface (`via`), and why. |
 
 With the create-cmp plugin, the same decisions can be made from the preview console
 (`preview {projectDir}`'s URL) — it calls the same library, so the CLI and the console
-never disagree. An agent blocks on a pending decision with
+never disagree. The console's rail is the human's work queue (colour = something waits
+on them), and a drifted artifact shows, in its own section, exactly **what changed
+against the signed bytes and which files are still exactly as signed**, with re-approval
+in place. An agent blocks on a pending decision with
 `approval_status {waitForDecision:true}`.
 
 The verify lane's `approvals` gate (a step like any other, in every profile) resolves each
@@ -227,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`
@@ -264,7 +380,12 @@ 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 release-APK Maestro smoke (`releaseSmoke`) |

package/template/composeApp/build.gradle.kts

@@ -161,6 +161,24 @@ kotlin {
                 implementation(compose.desktop.currentOs)
             }
         }
+
+        // Android INSTRUMENTATION tier (composeApp/src/androidInstrumentedTest) — the one
+        // evidence tier that crosses the process boundary. Everything else in this build is
+        // JVM-side: desktopTest is a JVM, golden trees are structure, the conformance suite
+        // is static analysis, and the Maestro smoke taps UI without asserting anything about
+        // notifications or alarms. Alarms, notification channels, full-screen intents,
+        // PendingIntent identity, and audio routing are OS facts that only exist on a device
+        // — a fully green desktop lane is compatible with an alerting feature that never
+        // alerts. This source set runs via `:composeApp:connectedDebugAndroidTest` (the
+        // lane's `androidChecks` step; SKIPs honestly when no device is attached).
+        //
+        // Its dependencies are declared through AGP's androidTestImplementation
+        // configuration (the dependencies block at the bottom of this file), not here: the
+        // KMP source-set DSL compiles these sources but does not put the androidx.test
+        // artifacts on their classpath.
+        //
+        // No kotlin-test here: instrumented tests run under JUnit4 (AndroidJUnit4), so they
+        // assert with org.junit.Assert — a second assertion vocabulary buys nothing.
     }
 }
 
@@ -174,6 +192,9 @@ android {
         targetSdk = 35
         versionCode = 1
         versionName = "1.0.0"
+        // Instrumentation entry point for the on-device behavior tier
+        // (composeApp/src/androidInstrumentedTest — see the source-set note above).
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
 
     packaging {
@@ -182,6 +203,20 @@ android {
         }
     }
 
+    // AGP resolves BUILD-TYPE source sets at src/<buildType>/, while the Kotlin
+    // Multiplatform plugin only remaps the `main` one to src/androidMain/. Without this
+    // wiring, src/androidDebug/'s manifest and resources are silently never merged —
+    // dead files that look live: the debug network-security config never applied, and a
+    // permission declared there never reached the APK. Point the debug build type at them
+    // explicitly. Caught when an instrumented test asserted canScheduleExactAlarms() and
+    // found the grant it had declared was absent on the device.
+    sourceSets {
+        getByName("debug") {
+            manifest.srcFile("src/androidDebug/AndroidManifest.xml")
+            res.srcDirs("src/androidDebug/res")
+        }
+    }
+
     buildFeatures {
         buildConfig = true
     }
@@ -202,7 +237,19 @@ android {
         getByName("release") {
             isMinifyEnabled = true
             isShrinkResources = true
+            // Every field debug declares, release must declare too. BuildConfig is generated
+            // PER BUILD TYPE, so a field only debug carries simply does not exist in release —
+            // and `if (!USE_FIREBASE_EMULATORS) return` is a RUNTIME guard that does nothing
+            // for a compile-time symbol. Declaring the flag alone made release the one build
+            // nobody could produce: the code reading the host and ports failed to resolve them.
+            // The values below are never used (the flag is false); they exist so the shape of
+            // BuildConfig is the same in both build types.
             buildConfigField("boolean", "USE_FIREBASE_EMULATORS", "false")
+            buildConfigField("String", "FIREBASE_EMULATOR_HOST", "\"\"")
+            buildConfigField("int", "FIREBASE_AUTH_PORT", "0")
+            buildConfigField("int", "FIREBASE_FIRESTORE_PORT", "0")
+            buildConfigField("int", "FIREBASE_FUNCTIONS_PORT", "0")
+            buildConfigField("int", "FIREBASE_STORAGE_PORT", "0")
             manifestPlaceholders["usesCleartextTraffic"] = "false"
             proguardFiles(
                 getDefaultProguardFile("proguard-android-optimize.txt"),
@@ -226,6 +273,19 @@ android {
         // <<< cmp:feature !firebase
     }
 
+    lint {
+        // ONE disabled check, not the gate. `lintVitalRelease` runs on every release build and
+        // it is worth keeping; what is not worth keeping is a detector that CRASHES on it.
+        // NullSafeMutableLiveData's detector throws IncompatibleClassChangeError against this
+        // Kotlin version (AGP's bug, not ours) and takes the whole release build with it.
+        //
+        // Disabling it costs nothing beyond the crash: an app on this template has no LiveData —
+        // state is Compose + Flow throughout — so the check has nothing to inspect. The blunt
+        // alternatives, `checkReleaseBuilds = false` or `abortOnError = false`, would switch off
+        // every real lint finding to dodge one broken one.
+        disable += "NullSafeMutableLiveData"
+    }
+
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17
@@ -244,6 +304,15 @@ dependencies {
     add("kspDesktop", libs.room.compiler)
     // <<< cmp:feature room
     add("coreLibraryDesugaring", libs.android.desugar.jdk)
+    // The instrumentation tier's runner, JUnit4 harness, and device helpers. Declared
+    // through AGP's own configuration rather than the KMP androidInstrumentedTest
+    // source-set block — the latter compiles the sources but does not put these
+    // artifacts on their classpath.
+    add("androidTestImplementation", libs.androidx.test.runner)
+    add("androidTestImplementation", libs.androidx.test.core)
+    add("androidTestImplementation", libs.androidx.test.ext.junit)
+    add("androidTestImplementation", libs.androidx.uiautomator)
+    add("androidTestImplementation", libs.junit4)
 }
 
 // Pin the generated resources accessor package so `__PACKAGE__.generated.resources.Res`

package/template/composeApp/proguard-rules.pro

@@ -20,6 +20,18 @@
 -keep class dev.gitlive.firebase.** { *; }
 -dontwarn com.google.firebase.**
 
+# GitLive's RemoteConfig module is compiled against kotlinx-datetime's OWN Instant, which
+# this version set no longer has: on Kotlin 2.2 Instant moved into the stdlib as
+# kotlin.time.Instant. R8 hits an unresolvable reference and FAILS the release build.
+#
+# Suppressed rather than resolved, deliberately. The reference lives in
+# FirebaseRemoteConfigInfo, and RemoteConfig is not a service this template wires up, so no
+# code path reaches it. Adding kotlinx-datetime back purely to satisfy a class nobody calls
+# would put two Instant types in the graph — the more expensive mistake. When GitLive ships
+# a build against kotlin.time, delete these two lines; the release build will say if it is time.
+-dontwarn kotlinx.datetime.Instant$Companion
+-dontwarn kotlinx.datetime.Instant
+
 # Coroutines
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}