create-cmp-cli 0.23.0 → 0.25.0

package/template/qa/receipt-check.mjs

@@ -21,6 +21,11 @@ import { fileURLToPath } from "node:url";
 
 import { computeInputsHash } from "./lib/inputs-hash.mjs";
 import { evaluateReceipt, readReceipt } from "./lib/receipt-validate.mjs";
+import { readHold, assessHold, describeHold, holdExplains } from "./lib/agent-hold.mjs";
+import { LANE_MARKER_STALE_MS, laneMarkerPath } from "./lib/lane-markers.mjs";
+import { resolveHarnessManifest } from "./lib/harness-manifest.mjs";
+import { loadProfileSync } from "./lib/profile-loader.mjs";
+import { evidenceLadderFor } from "./lib/evidence-ladder.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -29,9 +34,8 @@ const asHook = args.includes("--hook");
 const asJson = args.includes("--json");
 
 // The lane's own in-flight marker (verify.mjs stamps it, rewriting it at each
-// step start with the step name and index). Mirrors qa/watch.mjs's bound.
-const LANE_MARKER_REL = ["composeApp", "build", ".cmp-lane-in-progress"];
-const LANE_MARKER_STALE_MS = 30 * 60 * 1000;
+// step start with the step name and index) — qa/lib/lane-markers.mjs, one
+// path and one bound for every reader.
 
 /**
  * The full check running RIGHT NOW, or null. The gate must still refuse — a
@@ -43,7 +47,7 @@ const LANE_MARKER_STALE_MS = 30 * 60 * 1000;
  */
 function laneInFlight() {
   try {
-    const p = path.join(ROOT, ...LANE_MARKER_REL);
+    const p = laneMarkerPath(ROOT);
     const st = fs.statSync(p);
     if (Date.now() - st.mtimeMs >= LANE_MARKER_STALE_MS) return null;
     // Content is a bonus, never a requirement: legacy markers hold "pid iso".
@@ -72,7 +76,7 @@ function readStdinJson() {
 }
 
 // The predicate itself lives in qa/lib/receipt-validate.mjs (vendored from the
-// @create-cmp/receipts package — one definition everywhere a receipt is judged); this
+// prooflane-receipts package — one definition everywhere a receipt is judged); this
 // CLI only reads the receipt and frames the exit codes.
 function evaluate() {
   const receipt = readReceipt(ROOT);
@@ -108,28 +112,61 @@ function evaluate() {
       profile: receipt.profile,
     };
   }
-  // The device tier must have RUN (2026-09-03). The lane boots a headless
-  // emulator itself, so e2eSmoke/androidChecks only SKIP for two kinds of
-  // reason: the project's own structure (no qa/e2e harness, no instrumented
-  // sources — honest, allowed) or the ENVIRONMENT (CMP_DEVICE=none, maestro
-  // not installed, a lease held elsewhere, an ambiguous serial). The second
-  // kind is a gap a human can close, and a change is not done while it stands.
-  // Receipts predating `skipKind` are read by their reason text.
-  const DEVICE_TIER = ["e2eSmoke", "androidChecks"];
-  const envSkipped = (Array.isArray(receipt.steps) ? receipt.steps : []).filter(
-    (s) =>
-      s &&
-      DEVICE_TIER.includes(s.name) &&
-      s.verdict === "SKIP" &&
-      (s.skipKind === "environment" ||
-        (!s.skipKind && /no Android device|maestro CLI not installed|is held by|devices attached|CMP_DEVICE=none/.test(String(s.reason ?? "")))),
-  );
+  // A step that COULD have run and did not is a gap a human can close, and a
+  // change is not done while it stands (2026-09-03). The lane boots its own
+  // device, so an environment SKIP — no device, a tool not installed, a lease
+  // held elsewhere — is never the project's honest structure; a `structure`
+  // SKIP (this project has no such tier at all) is, and is allowed.
+  //
+  // Stage 0 PR 6c: this used to test `["e2eSmoke", "androidChecks"]` by name
+  // and match Android reason text. On any other stack it therefore checked
+  // nothing — the one gate that refuses "done" over a tier that never ran,
+  // silently inert. `skipKind` is the stack-free signal and every current
+  // receipt carries it, so the rule is now: ANY step that skipped for an
+  // environmental reason blocks done, whatever it is called.
+  //
+  // Receipts predating `skipKind` (0.19.0 and earlier) are still read by their
+  // reason text, and THAT list is the profile's — read from the ladder's
+  // execution tier when the profile is loadable, and simply not applied when
+  // it is not. A legacy fallback that guessed would be worse than none.
+  //
+  // THE LADDER IS RESOLVED, NOT SPELLED. This used to read `profile.ladder`
+  // directly, which is one of the two places a profile may declare its rungs;
+  // qa/verify.mjs read the other, and nothing reconciled them. It goes
+  // through qa/lib/evidence-ladder.mjs now, so this reader and the lane can
+  // never be looking at different declarations of the same thing.
+  //
+  // NO PACK IS PASSED, AND THAT IS THE POINT. Getting the pack's spelling means
+  // calling `steps(ctx)`, and this file is the Stop hook: a done-gate that
+  // starts a lane to answer a legacy-compat question is not a gate, it is a
+  // second lane. So a profile that declares its ladder ONLY on the pack gives
+  // this reader nothing and gets no legacy fallback — the same honest silence
+  // as a profile with no ladder at all, and the reason the top-level spelling
+  // is the one `harness init` seeds and the one the resolver prefers.
+  const legacyPatterns = /no Android device|maestro CLI not installed|is held by|devices attached|CMP_DEVICE=none/;
+  let legacyNames = null;
+  try {
+    const manifest = resolveHarnessManifest(ROOT);
+    if (manifest.ok) {
+      const loaded = loadProfileSync(ROOT, manifest.manifest.profile);
+      const resolved = evidenceLadderFor(loaded.ok ? loaded.profile : null);
+      const ladder = resolved.ok ? resolved.ladder : null;
+      if (ladder && Array.isArray(ladder.deviceExecution)) legacyNames = ladder.deviceExecution;
+    }
+  } catch {
+    // The Stop hook never crashes over a legacy-compat lookup.
+  }
+  const envSkipped = (Array.isArray(receipt.steps) ? receipt.steps : []).filter((s) => {
+    if (!s || s.verdict !== "SKIP") return false;
+    if (s.skipKind) return s.skipKind === "environment";
+    return Boolean(legacyNames && legacyNames.includes(s.name) && legacyPatterns.test(String(s.reason ?? "")));
+  });
   if (envSkipped.length) {
     return {
       valid: false,
       reason:
-        `the device tier did not run — ${envSkipped.map((s) => `${s.name}: ${String(s.reason ?? "").split("\n")[0]}`).join("; ")}. ` +
-        "The lane boots a headless emulator itself (set CMP_AVD if it cannot choose one); fix the cause and run `node qa/verify.mjs` again before finishing",
+        `a tier did not run — ${envSkipped.map((s) => `${s.name}: ${String(s.reason ?? "").split("\n")[0]}`).join("; ")}. ` +
+        "Those steps skipped for an environmental reason, not because this project lacks them; fix the cause and run `node qa/verify.mjs` again before finishing",
       profile: receipt.profile,
     };
   }
@@ -151,9 +188,21 @@ function evaluate() {
   // Surface the receipt's evidence rung (the ladder — qa/lib/evidence-level.mjs)
   // alongside the verdict: the rung is the receipt's own derived field, read
   // verbatim, never recomputed here. Older receipts without it stay valid.
+  //
+  // AND THE PACK WITH IT, ALWAYS — the two are set in the same breath because
+  // NORTH-STAR.md §6.5 requires that every surface showing a rung shows the
+  // pack, and §8.9 is why: one pack's L2 and another pack's L2 are different
+  // claims. This CLI printed the rung alone, which left every reader of the
+  // done-gate exactly where that rule says they must not be. Only the pack's
+  // ID is carried: it is the part that carries the meaning, and `pack.version`
+  // on a receipt is today the harness lock's number rather than the profile's
+  // (docs/adr/0008), so a surface that leaned on it would be repeating a
+  // borrowed fact.
   const level = receipt.evidenceLevel;
   if (level && typeof level === "object" && typeof level.rung === "string") {
     result.evidenceLevel = level;
+    const id = receipt.pack && typeof receipt.pack.id === "string" ? receipt.pack.id.trim() : "";
+    result.packId = id || null;
   }
   return result;
 }
@@ -175,12 +224,24 @@ if (asHook) {
     // INSTRUCTION: "run the lane" is wrong advice when one is already running,
     // and a gate that tells you to do the thing you are doing trains you to
     // stop reading it.
+    //
+    // An agent HOLDING the tree is the same shape of correction one level out:
+    // a lane in flight explains a receipt that is about to arrive, a hold
+    // explains a tree that is mid-edit and would not compile if you ran one.
+    // Reported ~15 false alarms in one evening at payment-blueprint, every one
+    // of which should have said "wait". It only ever changes the instruction —
+    // and only for the two refusals a working agent legitimately causes
+    // (holdExplains), never for a FAIL, a forgery or a skipped device tier,
+    // where the hold is not the cause and offering it would misdirect.
     const flight = laneInFlight();
+    const hold = holdExplains(result, readReceipt(ROOT)) ? assessHold(readHold(ROOT)) : null;
     const act = flight
       ? `A full check is ALREADY RUNNING${flight.step ? ` (${flight.step}${flight.index && flight.total ? `, step ${flight.index} of ${flight.total}` : ""})` : ""} — ` +
         `wait for it to finish and commit its receipt. Do NOT start a second one; two lanes fight over the same build directory.`
-      : "Run `node qa/verify.mjs` (it checks every promise and writes the receipt), " +
-        "commit the receipt, or see README §Verification enforcement to bypass.";
+      : hold?.held
+        ? describeHold(hold)
+        : "Run `node qa/verify.mjs` (it checks every promise and writes the receipt), " +
+          "commit the receipt, or see README §Verification enforcement to bypass.";
     process.stderr.write(
       `■ Prove — not done: the promises are not yet checked against this tree. ${result.reason}. ${act}\n`,
     );
@@ -189,7 +250,15 @@ if (asHook) {
   process.exit(0);
 }
 
-const rungSuffix = result.evidenceLevel ? ` — evidence ${result.evidenceLevel.rung} · ${result.evidenceLevel.name}` : "";
+// The rung NEVER travels alone (see evaluate() above): a rung is a claim in one
+// pack's vocabulary, so the pack is named beside it, and a receipt that names no
+// pack is SAID to name none rather than being rendered as if the omission did
+// not matter. A rung whose pack is unknown is comparable to nothing, and that is
+// a fact about the evidence, not a formatting detail to be tidied away.
+const rungSuffix = result.evidenceLevel
+  ? ` — evidence ${result.evidenceLevel.rung} · ${result.evidenceLevel.name}` +
+    (result.packId ? ` · pack ${result.packId}` : " · pack UNNAMED (this rung is comparable to nothing)")
+  : "";
 
 if (asJson) {
   console.log(JSON.stringify(result, null, 2));

package/template/qa/record-audit.mjs

@@ -29,7 +29,7 @@ const USAGE = `node qa/record-audit.mjs <subsystem> [--by <who-or-what>]
 Appends one audit record (subsystem, HEAD sha, ISO timestamp, recorder) to
 ${AUDITS_REL_PATH}. The verify lane's release profile reports which
 subsystems changed since their last record. Subsystems are derived from the
-tree: the immediate package directories under the androidMain Kotlin source
+tree: the immediate package directories under the platform source set
 root ("${ROOT_SUBSYSTEM}" for files directly at the package root).
 
   --list        print the derived subsystems and their audit status

package/template/qa/scaffold-feature.mjs

@@ -181,10 +181,18 @@ try {
 } catch {
   approvalsLib = null;
 }
+// The exemplar's shape and names are the cmp profile's (Stage 0 PR 5 —
+// qa/lib/profiles/cmp/artifacts.mjs); this stamper is that profile's tool.
+let profileLib = null;
+try {
+  profileLib = await import("./lib/profiles/cmp/artifacts.mjs");
+} catch {
+  profileLib = null;
+}
 
 function resolveSourceNames() {
-  if (approvalsLib && typeof approvalsLib.resolveExemplarNames === "function") {
-    return approvalsLib.resolveExemplarNames(ROOT);
+  if (profileLib && typeof profileLib.resolveExemplarNames === "function") {
+    return profileLib.resolveExemplarNames(ROOT);
   }
   return { f: "home", F: "Home", F_UPPER: "HOME", E: "Item" };
 }

package/template/qa/verified-surface.json

@@ -0,0 +1,17 @@
+{
+  "surface": [
+    "composeApp",
+    "specs",
+    "qa",
+    "gradle/libs.versions.toml",
+    "build.gradle.kts",
+    "settings.gradle.kts",
+    "gradle.properties"
+  ],
+  "ignore": [
+    "composeApp/build",
+    ".gradle",
+    ".kotlin",
+    ".idea"
+  ]
+}