create-cmp-cli 0.23.0 → 0.24.0

package/template/qa/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/template/qa/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/template/qa/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