create-cmp-cli 0.23.0 → 0.24.0

package/packages/harness/src/plan.mjs

@@ -10,6 +10,17 @@
 //   node qa/plan.mjs --done                            # close the chain
 //   node qa/plan.mjs --clear                           # a landed request leaves no stale windshield
 //
+//   node qa/plan.mjs --hold "adopting the ports" [--as <name>]   # I am working in this tree
+//   node qa/plan.mjs --beat ["what I am on now"]                 # still here (every few minutes)
+//   node qa/plan.mjs --release                                   # done, or gone
+//
+// The hold is LIVENESS, not a lock: nothing waits on it and it gates nothing.
+// It exists so "is the agent working or wedged?" is `tail` on a file instead of
+// filesystem archaeology — the question that got a healthy agent killed
+// mid-proof on 2026-09-04 — and so the Stop hook can say "wait for it" instead
+// of "run the lane" at a tree that would not compile. A heartbeat older than
+// five minutes is a crashed writer; a hold older than the ceiling is a wedge.
+//
 // Unlike walk-status (a fail-open status surface), this CLI is a WRITER the
 // agent invokes deliberately: bad input gets a refusal and exit 1, because a
 // silently-dropped declaration would leave the surfaces lying about position.
@@ -18,6 +29,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { deriveChain, markStep, readPlan, renderChain, setPlan, clearPlan } from "./lib/plan.mjs";
+import { assessHold, beatHold, claimHold, describeHold, readHold, releaseHold } from "./lib/agent-hold.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const args = process.argv.slice(2);
@@ -37,7 +49,24 @@ function out(result) {
   process.exit(0);
 }
 
-if (args.includes("--set")) {
+function holdOut(result) {
+  if (!result.ok) {
+    process.stderr.write(`plan: ${result.error}\n`);
+    process.exit(1);
+  }
+  const line = describeHold(assessHold(readHold(ROOT)));
+  process.stdout.write(`${line ?? "No agent holds this tree."}\n`);
+  process.exit(0);
+}
+
+if (args.includes("--hold")) {
+  holdOut(claimHold(ROOT, { holder: valueOf("--as") ?? process.env.CMP_AGENT ?? "an agent", note: valueOf("--hold") ?? "" }));
+} else if (args.includes("--beat")) {
+  const note = valueOf("--beat");
+  holdOut(beatHold(ROOT, note === null ? {} : { note }));
+} else if (args.includes("--release")) {
+  holdOut(releaseHold(ROOT));
+} else if (args.includes("--set")) {
   const spec = valueOf("--set");
   if (spec === null) {
     process.stderr.write('plan: --set needs a value: --set "step | step | …"\n');

package/packages/harness/src/receipt-check.mjs

@@ -21,6 +21,7 @@ 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";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -175,12 +176,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`,
     );

package/packages/harness/src/verify.mjs

@@ -104,7 +104,7 @@ Profiles:
   smoke     the smallest end-to-end lane: every pure-Node gate through the real
             runner, receipt and journal — no Gradle, no device. Seconds. Proves the
             FRAMEWORK returns, both ways; never the change (its receipt is refused
-            as done-evidence). Driven by scripts/framework-check.mjs.
+            as done-evidence). Driven by qa/framework-check.mjs.
   scaffold  spec coverage + build + unit tests (what \`create-cmp --verify\`
             proves at stamp time)
   local     everything; device-dependent steps SKIP when no device is

package/packages/receipts/src/inputs-hash.mjs

@@ -69,6 +69,11 @@ const EXCLUDED_PREFIXES = [
   "qa/.plan.json",
   "qa/.request.json",
   "qa/.plan-history.jsonl",
+  // Who is typing right now (qa/lib/agent-hold.mjs). A liveness declaration
+  // that could invalidate a receipt would mean an agent saying "I am here"
+  // un-proves the tree — the exact inversion this family of exclusions exists
+  // to prevent.
+  "qa/.agent-hold.json",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",

package/template/gitignore

@@ -44,6 +44,7 @@ qa/.plan.json
 # The closed-chain trail (drive-narration N5): local because it carries raw
 # human prompts — the committed journal for lane runs stays qa/flight-recorder.jsonl.
 qa/.plan-history.jsonl
+qa/.agent-hold.json
 
 # Android signing. The keystore IS the app's identity on Android — it cannot be reissued —
 # and keystore.properties holds its passwords. Never committed, never in a sidecar diff.

package/template/qa/approve.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 // The approvals CLI — thin shell over qa/lib/approvals.mjs.
 //
-//   node qa/approve.mjs <artifact>          records approval (recomputes the artifact's
-//                                            hash now, stamps the time, writes qa/approvals.json)
+//   node qa/approve.mjs <artifact> [<artifact> …]
+//                                            records approval (recomputes each artifact's
+//                                            hash now, stamps the time, writes qa/approvals.json).
+//                                            Sign every pending artifact in ONE command: each
+//                                            signature moves the receipt's input hash, so N
+//                                            separate signings cost N lane re-runs.
 //   node qa/approve.mjs --status            lists every governed artifact + live state
 //                                            (unreviewed / approved / changed-since-approval /
 //                                            reopened, + mode when set) + short hash
@@ -251,7 +255,27 @@ if (args.length === 0) {
 
 refuseIfUnresolvable();
 
-const artifactId = args[0];
+// EVERY artifact named in one command — one write, one invalidation.
+//
+// A signature changes qa/approvals.json's `status`, which the approvals gate
+// reads, so it legitimately moves the receipt's input hash. Signed one at a
+// time AFTER a green lane, that means N signatures invalidate the receipt N
+// times and cost N lane re-runs and N bookkeeping commits. Measured in
+// payment-blueprint's log on 2026-09-04: of 21 commits in one session, 8 were
+// "sign the approval" / "bind the receipt" with no product content, and every
+// code change cost two to three commits. It compounds as a repo accumulates
+// governed artifacts, which is what makes a session start fast and grind later.
+//
+// Two halves to the fix: sign them together (here), and sign BEFORE the final
+// lane run so the receipt you keep is already the one that covers the
+// signatures. `--reopen-feature` established the idiom — one recorded change,
+// not N commands.
+const artifactIds = args.filter((a, i) => !a.startsWith("--") && (i === 0 || !args[i - 1].startsWith("--")));
+// An unrecognised flag must still be REFUSED by name, never silently skipped:
+// filtering flags out is how `node qa/approve.mjs --delivr meal` would quietly
+// approve nothing and exit 0. Falling back to the first argument reproduces the
+// exact refusal an unknown verb has always produced.
+if (artifactIds.length === 0) artifactIds.push(args[0]);
 // The signer is REQUIRED, not optional: see approveArtifact's refusal. Parsed
 // here rather than defaulted from git config on purpose — `git config user.name`
 // is whatever the machine says, and an agent running on a developer's laptop
@@ -267,9 +291,14 @@ if (!approvedBy || approvedBy.startsWith("--")) {
   );
   process.exit(1);
 }
-const result = approveArtifact(ROOT, artifactId, { via: "cli", approvedBy });
-if (!result.ok) {
-  console.error(`error: ${result.reason}`);
-  process.exit(1);
+const results = artifactIds.map((id) => ({ id, result: approveArtifact(ROOT, id, { via: "cli", approvedBy }) }));
+const failed = results.filter((r) => !r.result.ok);
+for (const { id, result } of results) {
+  if (result.ok) console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);
+  else console.error(`error: ${id}: ${result.reason}`);
+}
+if (results.length > 1) {
+  const signed = results.length - failed.length;
+  console.log(`\n${signed} signature${signed === 1 ? "" : "s"} in one write. Run the lane AFTER signing, not before — a signature moves the receipt's input hash, so signing after a green run costs you that run.`);
 }
-console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);
+if (failed.length) process.exit(1);