create-cmp-cli 0.24.0 → 0.25.0

package/packages/receipts/src/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 `@create-cmp/receipts` package). The copy in a generated
+// create-cmp repo (the `prooflane-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`.
@@ -74,20 +74,31 @@ export function checkLaneVouching(receipt) {
       detail: `the receipt's verdict is PASS but ${failed.length} step(s) did not pass: ${names} — the row is the more specific truth`,
     };
   }
-  const integrity = steps.find((s) => s && s.name === "harnessIntegrity");
+  // THE ROW THAT VOUCHES IS THE ROW CARRYING THE VOUCHING DATA, not the row with
+  // a particular name. This found a step named exactly `harnessIntegrity` — a
+  // name the cmp pack chose, that `REQUIRED_EXPORTS` never mentions, and that a
+  // profile author has no way to discover. A green lane whose self-vouching step
+  // was spelled `harness_integrity` minted receipts that were invalid FOREVER,
+  // in every reader, and the refusal accused the lane of not vouching for
+  // itself. The `harness` object on a step row is what the schema already
+  // documents as the integrity check's own findings, so it is the honest key.
+  // The name is kept as a fallback for receipts written before rows carried it.
+  const integrity = steps.find((s) => s && s.harness && typeof s.harness === "object") ?? steps.find((s) => s && s.name === "harnessIntegrity");
   if (!integrity) {
     return {
       ok: false,
-      detail: "receipt has no harnessIntegrity row — nothing vouches that the lane's own code is the code that ran",
+      detail:
+        "no step on this receipt vouches for the lane — no row carries a `harness` object and none is named harnessIntegrity, " +
+        "so nothing attests that the lane's own code is the code that ran",
     };
   }
   if (integrity.verdict !== "PASS") {
     return {
       ok: false,
-      detail: `harnessIntegrity is ${integrity.verdict}, not PASS — the lane did not vouch for itself, so its PASS over the tree cannot be trusted`,
+      detail: `${integrity.name ?? "the integrity step"} is ${integrity.verdict}, not PASS — the lane did not vouch for itself, so its PASS over the tree cannot be trusted`,
     };
   }
-  return { ok: true, detail: "lane vouched for itself (harnessIntegrity PASS, no failing rows)" };
+  return { ok: true, detail: `lane vouched for itself (${integrity.name ?? "integrity step"} PASS, no failing rows)` };
 }
 
 export function evaluateReceipt(receipt, recompute) {
@@ -101,6 +112,33 @@ export function evaluateReceipt(receipt, recompute) {
     };
   }
 
+  // WHICH PACK GRADED THIS — ADR-0011. §8.9's comparability rule rests entirely
+  // on this field ("a `cmp` L2 and any other pack's L2 are different claims"),
+  // and until now no predicate read it: remove `pack` and a receipt kept its
+  // rung while losing the only thing that says what the rung is a rung OF.
+  //
+  // REFUSED, not flagged, and the cost is known. A receipt written before the
+  // field existed (2026-09-04) is refused too, because nothing in a receipt can
+  // tell "never had one" from "had one, and it was removed" — and of those two
+  // errors, accepting tampering is the one a predicate exists to prevent. The
+  // remedy is the one the binding check above already offers for the same class
+  // of staleness, and costs the same: re-run the lane.
+  //
+  // This is deliberately NOT the ADR-0007 case. There a label moved and no
+  // assertion changed, so invalidating old receipts would have been pure loss.
+  // Here the receipt is genuinely missing the field that makes its rung mean
+  // something — it is not being punished for a name, it is being asked for a
+  // claim it never made.
+  if (!receipt.pack || typeof receipt.pack.id !== "string" || receipt.pack.id.length === 0) {
+    return {
+      valid: false,
+      reason:
+        `receipt names no step pack — re-run the lane (attesting profile: ${profile ?? "unknown"}). ` +
+        `A rung is comparable only within its pack, so a receipt that does not name one cannot be compared to any other`,
+      profile,
+    };
+  }
+
   if (receipt.verdict === "FAIL") {
     return {
       valid: false,
@@ -146,12 +184,33 @@ export const DEFAULT_POLICY = {
   /** A receipt older than this no longer counts as fresh (hosted check only). */
   maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 days
   /**
-   * Executed (non-SKIP) gates must report at least this much total wall time.
-   * A "PASS" receipt whose executed gates sum to less cannot attest a real
-   * lane run — the tell for replayed/cached or hand-written verdicts
-   * (evidence must attest execution, not results).
+   * An absolute wall-time floor for executed (non-SKIP) gates. `null` — OFF by
+   * default, and that is a decision rather than an omission.
+   *
+   * This was 5000, with the reasoning that a PASS receipt summing to less
+   * cannot attest a real lane run: the tell for a replayed/cached green or a
+   * hand-written verdict. That reasoning holds for a Gradle lane and is FALSE
+   * for a Go service, a Rust crate, a Python package or a TypeScript library,
+   * whose lanes honestly finish in hundreds of milliseconds. Those adopters
+   * were told their evidence was fabricated — the one accusation this product
+   * cannot afford to make wrongly.
+   *
+   * The number was not the defect. ONE receipt carries nothing that could
+   * justify any number: no start time, no top-level duration, no baseline —
+   * `generatedAt` is a timestamp, not an interval — so nothing on it can be
+   * cross-checked against anything else on it. A floor is therefore a fact
+   * about the STACK, and this module does not know the stack. It is the
+   * notary's to set, from data the notary has and the receipt does not: a
+   * lane that has taken thirty seconds every day for a month and today claims
+   * forty-two milliseconds is a real finding, and it is a finding about a
+   * HISTORY, not about a receipt.
+   *
+   * What is lost, said plainly: a hand-written receipt claiming small
+   * durations is no longer refused here. It was never much of a defence — a
+   * forger types a larger number — and every stack-independent check that
+   * does catch fabrication is untouched below.
    */
-  minExecutedMs: 5000,
+  minExecutedMs: null,
 };
 
 /**
@@ -176,9 +235,15 @@ export function checkFreshness(receipt, { now = Date.now(), maxAgeMs = DEFAULT_P
 }
 
 /**
- * Execution plausibility: do the executed (non-SKIP) gates report durations a
- * real lane run could produce? Catches replayed/cached greens and hand-edited
- * receipts whose numbers were never lived.
+ * Execution plausibility: did this lane execute anything, and are its numbers
+ * real numbers?
+ *
+ * Three refusals, all stack-independent and all about the SHAPE of the
+ * evidence rather than its size: a receipt with no steps, a receipt whose every
+ * step is a SKIP or an ERROR (neither measured anything), and a step whose
+ * duration is not a finite non-negative number. An absolute wall-time floor is
+ * a fourth check and is OFF unless a caller sets `minExecutedMs` — see
+ * DEFAULT_POLICY for why a default one is a claim about the stack.
  * @returns {{ok: boolean, detail: string, executedMs?: number, executedSteps?: number}}
  */
 export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_POLICY.minExecutedMs } = {}) {
@@ -200,10 +265,13 @@ export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_PO
     }
     total += step.durationMs;
   }
-  if (total < minExecutedMs) {
+  // Applied only when a caller supplies one. The message attributes the floor
+  // to whoever set it and states the measurement, rather than asserting that a
+  // fast receipt cannot be real — which this module has no way to know.
+  if (typeof minExecutedMs === "number" && minExecutedMs > 0 && total < minExecutedMs) {
     return {
       ok: false,
-      detail: `implausibly fast — executed gates report ${total}ms total, below the ${minExecutedMs}ms floor; a receipt this fast cannot attest a real lane run (evidence must attest execution)`,
+      detail: `executed gates report ${total}ms total, below this validator's configured ${minExecutedMs}ms floor — for a fast stack that may be honest, so treat it as a finding to explain rather than proof of fabrication`,
       executedMs: total,
       executedSteps: executed.length,
     };
@@ -247,7 +315,7 @@ export function validateReceiptForTree({ root, now = Date.now(), policy = {} } =
   if (receipt === null) {
     return {
       status: "missing",
-      reason: `no receipt at ${RECEIPT_REL_PATH} — this repo does not carry the create-cmp evidence harness (that is not a failure)`,
+      reason: `no receipt at ${RECEIPT_REL_PATH} — this repo does not carry the prooflane evidence harness (that is not a failure)`,
       checks: [{ id: "receipt-present", ok: false, detail: `no parsable receipt at ${RECEIPT_REL_PATH}` }],
       skips: [],
     };

package/src/commands/attach.mjs

@@ -19,6 +19,12 @@ import { colors, ok, warn, fail } from "../lib/log.mjs";
 import { consent } from "../bootstrap/exec.mjs";
 import { sessionStartCommand } from "../lib/hooks.mjs";
 import { SIDECAR_SUFFIX } from "../lib/harness-upgrade.mjs";
+import {
+  MANIFEST_REL_PATH,
+  PROFILE_ID_RE,
+  manifestFor,
+  manifestProblems,
+} from "../../packages/harness/src/lib/harness-manifest.mjs";
 
 const COMPOSE_SIGNALS = [
   "org.jetbrains.compose",
@@ -155,7 +161,7 @@ export function classifyTarget(projectDir) {
  * @param {boolean} [params.apply=false]
  * @returns {{units: Array<{relPath:string, action:string}>, notWired: string[]}}
  */
-export function attachProject({ projectDir, apply = false }) {
+export function attachProject({ projectDir, apply = false, manifest = null }) {
   const target = classifyTarget(projectDir);
   if (!target.ok) throw new Error(target.reason);
 
@@ -163,6 +169,17 @@ export function attachProject({ projectDir, apply = false }) {
     { relPath: "AGENTS.md", content: attachAgentsMd() },
     { relPath: ".claude/settings.json", content: attachSettings() },
   ];
+  // The harness manifest — WHICH STACK PROFILE this repo uses, and where its
+  // specs, sources and receipt live. The lane refuses to run without one and
+  // there is no default (decision 3, 2026-09-04), so for a repo create-cmp
+  // never stamped this is the interview's output, landed as one more unit.
+  // Only ever offered when the caller resolved one: a manifest already on disk
+  // is the repo's own declaration and is never touched here.
+  if (manifest) {
+    const problems = manifestProblems(manifest);
+    if (problems.length) throw new Error(`refusing to write an invalid manifest: ${problems.join("; ")}`);
+    files.push({ relPath: MANIFEST_REL_PATH, content: `${JSON.stringify(manifest, null, 2)}\n` });
+  }
   const units = [];
   for (const { relPath, content } of files) {
     const abs = path.join(projectDir, relPath);
@@ -191,11 +208,109 @@ export function attachProject({ projectDir, apply = false }) {
     notWired: [
       "headless screen previews (PreviewRegistry + renderScreens) — staged M0b, needs a per-repo Gradle wiring design",
       "live on-device inspector — ships with scaffolded apps; not injectable into a foreign build yet",
-      "verify lane / evidence receipts / enforcement — the lane addresses the stamped layout by name",
+      "verify lane / evidence receipts / enforcement — the manifest above tells the lane which profile and where things live; vendoring the lane itself into a foreign repo is the next M0b step",
     ],
   };
 }
 
+/**
+ * A manifest from flags alone — the non-interactive path (`--yes`). Pure:
+ * returns null when no `--profile` was given, otherwise the manifest with its
+ * problems (empty when valid) so the caller decides how to refuse.
+ * @param {object} flags
+ * @returns {{manifest: object, problems: string[]} | null}
+ */
+export function manifestFromFlags(flags) {
+  if (typeof flags.profile !== "string") return null;
+  const layout = {};
+  if (typeof flags.specs === "string") layout.specs = flags.specs;
+  if (typeof flags.receipt === "string") layout.receipt = flags.receipt;
+  if (typeof flags["citation-roots"] === "string") {
+    const roots = flags["citation-roots"]
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    // An empty value is "no override", never an empty list — the lane would
+    // refuse `citationRoots: []` and the user would have to decode why.
+    if (roots.length) layout.citationRoots = roots;
+  }
+  const manifest = manifestFor(flags.profile, layout);
+  return { manifest, problems: manifestProblems(manifest) };
+}
+
+/**
+ * The manifest interview — the questions a foreign repo has to answer before
+ * the lane can know what a step or a test root is here. Four questions, each
+ * with a default a Compose/KMP repo would accept unchanged; a backend types
+ * its own. Validated to the same contract the lane applies before it is
+ * written, so the interview can never produce a manifest the lane refuses.
+ */
+async function interviewManifest() {
+  let prompts;
+  try {
+    prompts = (await import("prompts")).default;
+  } catch {
+    process.stderr.write(
+      "The manifest interview needs the 'prompts' package. Re-run with --yes --profile <id> [--specs <dir>] [--citation-roots a,b] [--receipt <path>] for non-interactive use.\n"
+    );
+    process.exit(1);
+  }
+  const onCancel = () => {
+    process.stdout.write("Cancelled — no manifest written.\n");
+    process.exit(1);
+  };
+  const a = await prompts(
+    [
+      {
+        type: "text",
+        name: "profile",
+        message: "Stack profile id (a directory under qa/lib/profiles/)",
+        initial: "cmp",
+        validate: (v) => (PROFILE_ID_RE.test(String(v).trim()) ? true : `must match ${PROFILE_ID_RE}`),
+      },
+      { type: "text", name: "specs", message: "Where do specs live?", initial: "specs" },
+      { type: "text", name: "citationRoots", message: "Source roots the lane scans for SPEC: citations (comma-separated)", initial: "composeApp/src, qa/e2e" },
+      { type: "text", name: "receipt", message: "Where should the receipt be written?", initial: "qa/evidence/latest.json" },
+    ],
+    { onCancel }
+  );
+  return manifestFor(String(a.profile).trim(), {
+    specs: String(a.specs).trim(),
+    citationRoots: String(a.citationRoots)
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+    receipt: String(a.receipt).trim(),
+  });
+}
+
+/**
+ * Resolve the manifest `attach` should land, if any: none when one is already
+ * on disk (never overwritten here — valid or not, it is the repo's own
+ * declaration; a malformed one is the lane's refusal to explain); from flags
+ * when `--profile` is given; from the interview otherwise; and a refusal when
+ * `--yes` forbids asking and no flags answer.
+ */
+async function manifestForAttach(projectDir, flags) {
+  if (fs.existsSync(path.join(projectDir, ...MANIFEST_REL_PATH.split("/")))) return null;
+  const fromFlags = manifestFromFlags(flags);
+  if (fromFlags) {
+    if (fromFlags.problems.length) {
+      fail(`the manifest from your flags is invalid: ${fromFlags.problems.join("; ")}`);
+      process.exit(1);
+    }
+    return fromFlags.manifest;
+  }
+  if (flags.yes === true) {
+    fail(
+      `${MANIFEST_REL_PATH} is missing and --yes forbids asking. Pass --profile <id> ` +
+        `[--specs <dir>] [--citation-roots a,b] [--receipt <path>], or run without --yes to be asked.`
+    );
+    process.exit(1);
+  }
+  return interviewManifest();
+}
+
 /**
  * `create-cmp attach [dir] [--dry-run] [--yes]`
  */
@@ -209,9 +324,18 @@ export async function runAttach(flags, positional) {
       `  project: ${colors.cyan(projectDir)}\n\n`
   );
 
+  // Classify BEFORE asking anything: a stamped app or a non-Gradle tree is
+  // refused with its reason, not interviewed and then refused.
+  const target = classifyTarget(projectDir);
+  if (!target.ok) {
+    fail(target.reason);
+    process.exit(1);
+  }
+  const manifest = await manifestForAttach(projectDir, flags);
+
   let plan;
   try {
-    plan = attachProject({ projectDir, apply: false });
+    plan = attachProject({ projectDir, apply: false, manifest });
   } catch (e) {
     fail(e.message);
     process.exit(1);
@@ -241,7 +365,7 @@ export async function runAttach(flags, positional) {
     process.exit(0);
   }
 
-  const applied = attachProject({ projectDir, apply: true });
+  const applied = attachProject({ projectDir, apply: true, manifest });
   for (const u of applied.units) {
     if (u.action === "written") ok(`wrote ${u.relPath}`);
     if (u.action === "sidecar") warn(`wrote ${u.relPath}${SIDECAR_SUFFIX} (yours untouched)`);

package/src/commands/harden.mjs

@@ -52,6 +52,7 @@ import {
   checkHarnessIntegrity,
   describeIntegrity,
 } from "../../packages/harness/src/lib/harness-lock.mjs";
+import { writeHarnessSource, HARNESS_PKG_NAME } from "../../packages/harness/src/lib/harness-source.mjs";
 
 const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -152,7 +153,12 @@ export async function hardenProject({ projectDir, templateDir, apply = false, lo
     }
 
     const harnessVersion = shippedHarnessVersion();
-    if (harnessVersion) writeHarnessLock(projectDir, { version: harnessVersion });
+    if (harnessVersion) {
+      // Same ordering as the stamp: the record is inside the region the lock
+      // hashes, so it exists first (ADR-0008).
+      writeHarnessSource(projectDir, { name: HARNESS_PKG_NAME, version: harnessVersion, source: "local" });
+      writeHarnessLock(projectDir, { version: harnessVersion });
+    }
 
     const updated = { ...record, harness: true, engineVersion: currentEngineVersion() };
     fs.writeFileSync(specPath, JSON.stringify(updated, null, 2) + "\n");

package/src/commands/upgrade.mjs

@@ -43,6 +43,7 @@ import { consent } from "../bootstrap/exec.mjs";
 import { loadRegistry, latestSet, getSet } from "../lib/registry.mjs";
 import { planUpgrade, BACKUP_SUFFIX, sidecarDroppedLines, staleBackupPaths } from "../lib/upgrade.mjs";
 import { writeHarnessLock, checkHarnessIntegrity, describeIntegrity } from "../../packages/harness/src/lib/harness-lock.mjs";
+import { writeHarnessSource, HARNESS_PKG_NAME } from "../../packages/harness/src/lib/harness-source.mjs";
 import { LOCAL_PATCH_PATH, stampBaseWith } from "../lib/harness-upgrade.mjs";
 import { buildTokenMap } from "../lib/tokens.mjs";
 import {
@@ -409,6 +410,12 @@ async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRo
   // version numbers buy. So the lock is rewritten on its own schedule.
   const harnessVersion = shippedHarnessVersion();
   if (harnessVersion) {
+    // The provenance record first: it is inside the region the lock hashes, and
+    // rewriting it is what makes a version-only upgrade visible in the TREE
+    // rather than only in a number (ADR-0008 / Stage 1 criterion D). Without
+    // this a stamped app upgraded here moved its lock's `version` and not one
+    // digest — the shape the criterion forbids.
+    writeHarnessSource(projectDir, { name: HARNESS_PKG_NAME, version: harnessVersion, source: "local" });
     writeHarnessLock(projectDir, { version: harnessVersion });
     ok(`lane locked at ${colors.bold(harnessVersion)} — ${describeIntegrity(checkHarnessIntegrity(projectDir))}`);
   }

package/src/lib/minimal.mjs

@@ -25,6 +25,7 @@
 // additive, idempotent, never clobbering. See src/commands/harden.mjs.
 
 import fs from "node:fs";
+import { HARNESS_DECLARATIONS, HARNESS_GENERATED } from "../../packages/harness/src/lib/harness-region.mjs";
 import path from "node:path";
 
 import { listHarnessFiles } from "../../packages/harness/src/lib/harness-region.mjs";
@@ -59,12 +60,33 @@ const IMPORT_SPECIFIER_RE = /(?:from\s+|new URL\(\s*)["'](\.\.?\/[^"']+\.mjs)["'
 
 /**
  * The machine-owned files a minimal scaffold keeps: the entry points plus
- * their transitive ./-relative imports, resolved against the tree as stamped.
+ * their transitive ./-relative imports, resolved against the tree as stamped —
+ * PLUS the region members that are not modules and therefore cannot be reached
+ * by any import closure.
+ *
+ * That last clause is not a special case, it is the shape of the region: it
+ * holds code AND the files the lane reads about itself (the two declarations)
+ * and the record of which harness it carries (`qa/harness-source.json`,
+ * ADR-0008). A closure walk can only ever see the code half, so deriving the
+ * keep-set from imports alone quietly proposes deleting the other half — and
+ * the file it would delete is the one that says what this lane IS.
+ *
  * @param {string} projectDir
  * @returns {Set<string>} project-relative posix paths
  */
 export function laneKeepSet(projectDir) {
   const keep = new Set();
+  // The declarations are gated on presence; the generated record is NOT, and
+  // the asymmetry is the point. `qa/harness-source.json` is written at STAMP
+  // time, so it is absent from the template this set is usually derived against
+  // and present in every stamped tree — gating it on presence would produce a
+  // keep-set that is right about the template and wrong about the app, which is
+  // the only tree the answer is ever used on. A name kept but absent costs
+  // nothing: the set decides what NOT to delete.
+  for (const rel of HARNESS_DECLARATIONS) {
+    if (fs.existsSync(path.join(projectDir, ...rel.split("/")))) keep.add(rel);
+  }
+  for (const rel of HARNESS_GENERATED) keep.add(rel);
   const queue = MINIMAL_LANE_ENTRY_POINTS.filter((rel) =>
     fs.existsSync(path.join(projectDir, rel))
   );

package/src/scaffold.mjs

@@ -22,6 +22,7 @@ import { validatePackageName } from "./lib/package-name.mjs";
 import { buildTokenMap, replaceTokens, replacePathTokens, isBinaryPath, slugifyAppName } from "./lib/tokens.mjs";
 import { isHarnessFile, listHarnessFiles } from "../packages/harness/src/lib/harness-region.mjs";
 import { writeHarnessLock } from "../packages/harness/src/lib/harness-lock.mjs";
+import { writeHarnessSource, HARNESS_PKG_NAME } from "../packages/harness/src/lib/harness-source.mjs";
 import { renamePackageDirs } from "./lib/rename.mjs";
 import {
   stripFeatureBlocks,
@@ -305,6 +306,13 @@ function writeLaneLock(projectDir) {
   // it would attest nothing while creating the very qa/ directory the strip
   // just removed.
   if (listHarnessFiles(projectDir).length === 0) return;
+  // PROVENANCE BEFORE THE LOCK (ADR-0008). The record is inside the region, so
+  // it must exist before the region is hashed. A stamped app's lane bytes were
+  // COPIED FROM A PATH ON THIS MACHINE — the template inside whichever
+  // create-cmp is installed here — which is `local` exactly as the enum defines
+  // it, and is true however create-cmp itself arrived. Calling it `registry`
+  // because the scaffolder came from npx would name the wrong artifact.
+  writeHarnessSource(projectDir, { name: HARNESS_PKG_NAME, version, source: "local" });
   writeHarnessLock(projectDir, { version });
 }
 

package/template/.claude/settings.json

@@ -6,7 +6,7 @@
         "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 \u2014 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.\"}}'"
+            "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 receipt that attests this tree (commit it with the change), approvals gate signed artifacts. The cmp-inspector MCP tools (preview loop, live tier) are the expected eyes \u2014 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.\"}}'"
           }
         ]
       }
@@ -21,7 +21,7 @@
           },
           {
             "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) \u2014 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"
+            "command": "grep -qE 'connected[A-Za-z]*AndroidTest|maestro test|adb (-s [^ ]+ )?(install|uninstall)|emulator (-avd|@)|:composeApp:installDebug' && 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/profiles/cmp/device-lease.mjs) \u2014 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",

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

@@ -15,7 +15,7 @@ description: >-
 
 > Spec-first, deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs`) does the
 > mechanical work — copy the exemplar file set, whole-word identifier rename, anchor
-> injection into the three shared files. You (the AI) only refine spec wording and adapt the
+> injection into the three shared files (four when the inspector shipped — the preview registry too). You (the AI) only refine spec wording and adapt the
 > 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`.
 
@@ -126,7 +126,7 @@ Then adapt the generated code to match:
   registry vocabulary** (`ScreenColumn`/`AppHeader`/`ContentStateContainer`/`ListItemCard`,
   `presentation/components/*.kt`) — adapt the content shape inside `ContentStateContainer`'s
   trailing slot, don't hand-roll a new header/loading state/list row on top of it. If the
-  feature's data genuinely needs a component the nine don't cover, propose the addition to the
+  feature's data genuinely needs a component the registry doesn't cover, propose the addition to the
   human explicitly (a new file is a registry change — it invalidates the `components` approval).
 - Update the copied tests (`<Feature>ViewModelTest.kt`, `<Feature>ScreenTest.kt`) to match
   whatever you changed. The gate (step 6) will tell you exactly what you missed — a compile
@@ -152,12 +152,16 @@ copy-paste artifact. Commit it alongside the feature.
 
 ### 6. Gate
 
+**Before the lane — the device journey.** The stamper wrote `qa/e2e/<feature>.yaml` as a placeholder and
+said so; the lane's `e2eCoverage` gate FAILs until that flow is a real journey citing a `<FEATURE>-NN`
+clause it proves. That red is the gate working, not a bug — make the flow real first.
+
 ```
 node qa/verify.mjs
 ```
 
 This must PASS. It proves: the spec's seven clauses are all bound to a citing test
-(`specCoverage`), the build compiles, unit tests pass (ViewModel + UseCase + Repository +
+(`specCoverage`), the device journey cites a clause it proves (`e2eCoverage`), the build compiles, unit tests pass (ViewModel + UseCase + Repository +
 fakes), architecture conformance holds (`presentation` doesn't import `data`, the new
 `*Screen.kt` is automation-reachable — a literal `testTag` or `screenTag =` wiring into a
 registry component — the new `*ViewModel.kt` has a matching test, and it references no

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

@@ -3,7 +3,7 @@ name: add-repository
 description: >-
   Add a data/domain slice ONLY — model, repository interface + impl, use case, and a
   hand-written fake — to this Compose Multiplatform app, cloned deterministically from the
-  `home` exemplar's data layer. No screen, no ViewModel, no nav route, no spec clauses. Use this
+  project's configured exemplar feature's data layer (`qa/approvals.json`'s `exemplarFeature` — `home` by default). No screen, no ViewModel, no nav route, no spec clauses. Use this
   when the user wants to "add a repository", "add a data source", "model a new entity", "new
   entity with a repository", or names a domain noun they want backed by data before any UI exists
   (e.g. "add a Tag repository", "I need a data source for Bookmarks"). Works with NO create-cmp
@@ -14,7 +14,7 @@ description: >-
 # add-repository — stamp a data/domain slice only
 
 > Deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs --preset repository`)
-> does the mechanical work — copy the `home` exemplar's data/domain files, whole-word identifier
+> does the mechanical work — copy the exemplar's data/domain files, whole-word identifier
 > rename, DI injection for the repository + use case only. You (the AI) only customize the
 > entity's fields and its sample data. You are not done until `node qa/verify.mjs` PASSes and the
 > receipt is committed — see this project's `CLAUDE.md`.

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

@@ -3,7 +3,7 @@ name: add-screen
 description: >-
   Add a presentation-only slice — Screen + ViewModel + tests + golden tree + spec + nav route —
   for an EXISTING entity/repository in this Compose Multiplatform app, cloned deterministically
-  from the `home` exemplar's presentation layer. Requires the entity's data layer (model,
+  from the project's configured exemplar feature's presentation layer (`qa/approvals.json`'s `exemplarFeature` — `home` by default). Requires the entity's data layer (model,
   repository, use case, fake) to already exist. Use this when the user wants to "add a screen",
   "add a screen for an existing entity", "add a screen backed by a repository I already have",
   "put a UI on this data", or names an existing domain noun they want a screen for (e.g. "add a
@@ -86,7 +86,7 @@ failure.
 
 ### 4. Refine the spec, then the behavior
 
-Rewrite the clause prose in `specs/<feature>.spec.md` for the entity's real behavior — the six
+Rewrite the clause prose in `specs/<feature>.spec.md` for the entity's real behavior — the seven
 clause **ids stay fixed** (specCoverage binds tests to ids, not prose). Propose the rewritten
 clauses to the human; get them confirmed before moving on.
 
@@ -114,12 +114,16 @@ it alongside the feature.
 
 ### 6. Gate
 
+**Before the lane — the device journey.** The stamper wrote `qa/e2e/<feature>.yaml` as a placeholder and
+said so; the lane's `e2eCoverage` gate FAILs until that flow is a real journey citing a `<FEATURE>-NN`
+clause it proves. That red is the gate working, not a bug — make the flow real first.
+
 ```
 node qa/verify.mjs
 ```
 
-This must PASS. It proves: the spec's six clauses are all bound to a citing test
-(specCoverage — `<FEATURE>-01..07` newly bound), the build compiles, unit tests pass, architecture
+This must PASS. It proves: the spec's seven clauses are all bound to a citing test
+(specCoverage — `<FEATURE>-01..07` newly bound), the device journey cites a clause it proves (e2eCoverage), the build compiles, unit tests pass, architecture
 conformance holds (the screen is automation-reachable via a literal `testTag` or `screenTag =`
 wiring into a registry component, and references no `CircularProgressIndicator`/
 `LinearProgressIndicator` directly), the golden tree matches, and accessibility holds. **Not done

package/template/.githooks/pre-push

@@ -13,6 +13,15 @@ if [ ! -f qa/receipt-check.mjs ]; then
   exit 0 # not a create-cmp project layout — nothing to gate
 fi
 
+# First the half nothing else checks: the receipt must be IN the commit being
+# pushed, not merely on disk. receipt-check reads the working tree by hash and
+# has no opinion about git; this line is what makes "committed receipt" true.
+if ! git ls-files --error-unmatch qa/evidence/latest.json >/dev/null 2>&1 || ! git diff --quiet HEAD -- qa/evidence/latest.json; then
+  echo ""
+  echo "✗ pre-push blocked — qa/evidence/latest.json is not committed (or differs from HEAD)."
+  echo "  Commit the receipt with your change, then push again."
+  exit 1
+fi
 if node qa/receipt-check.mjs; then
   exit 0
 fi