create-cmp-cli 0.22.0 → 0.24.0

package/template/qa/lib/agent-hold.mjs

@@ -0,0 +1,234 @@
+// agent-hold.mjs — "an agent is working in this tree right now."
+//
+// TWO PROBLEMS, ONE MISSING FACT. Both were reported from payment-blueprint's
+// adoption on 2026-09-04, and both are the same absence:
+//
+//   1. LIVENESS. There was no way to answer "is the agent working, or wedged?"
+//      without filesystem archaeology. The lead architect guessed twice with two
+//      separately broken instruments — a `find` that excluded `build/` (the only
+//      directory a proof run writes to) and a `find -newermt` that reported zero
+//      writes in 45 minutes while `ls -lT` showed one at 10 — and on the first
+//      guess killed a healthy agent mid-proof. An instrument that cannot see the
+//      thing it exists to detect is worse than no instrument: it is confidently
+//      wrong, which is the same failure class GATE-RULES Rule 1 exists for.
+//
+//   2. FALSE ALARMS. The Stop hook fires identically whether a receipt is stale
+//      because nobody ran the lane or because a subagent is mid-commit on a
+//      half-adopted port. It fired ~15 times in one evening while the correct
+//      action every time was to WAIT. Anthropic's tool-design guidance is
+//      explicit that an error must communicate "specific and actionable
+//      improvements"; an alarm whose advice is wrong every time it fires trains
+//      its reader to ignore it, which is strictly worse than silence.
+//
+// WHAT THIS IS NOT. It is not a lock — nothing waits on it, nothing is excluded
+// by it. It is not a second journal: the flight recorder still owns lane history
+// that belongs in the repo. It is a DECLARATION with an expiry, in the same
+// ephemeral, gitignored, hash-excluded family as qa/.plan.json and
+// qa/.request.json — because a fact about who is typing must never be able to
+// invalidate a receipt.
+//
+// A HOLD CHANGES THE ADVICE, NEVER THE VERDICT. The Stop hook still refuses:
+// no receipt yet means not done, and a file an agent writes about itself must
+// never be able to end a turn — that would be turning the gate off by writing a
+// file, which is the attack the whole harness exists to refuse. This follows the
+// precedent already set for a lane in flight (qa/receipt-check.mjs): same
+// refusal, different instruction. "Run the lane" is wrong advice when the tree
+// is mid-edit and would not compile, and a gate that tells you to do the thing
+// you are already doing trains you to stop reading it.
+//
+// THE ASYMMETRY THAT KEEPS IT HONEST. A hold EXPLAINS the absence of fresh
+// evidence. It never explains CONTRADICTING evidence. A red receipt, a forged
+// receipt, a skipped device tier: for those the hold is not the reason and
+// saying so would mislead. Only two refusals are explicable by a hold — "no
+// receipt yet" and "the tree moved since a PASSing receipt" — exactly the two
+// states a working agent legitimately produces, and nothing else.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/agent-hold.mjs in the
+// create-cmp repo. The copy in a generated project's qa/lib/ is vendored
+// byte-identical at scaffold time — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Ephemeral, gitignored, and excluded from the receipt's hashed input surface
+ * (qa/lib/inputs-hash.mjs EXCLUDED_PREFIXES) — the same family as .plan.json.
+ */
+export const HOLD_REL = "qa/.agent-hold.json";
+
+/**
+ * A heartbeat older than this is a crashed writer, not a live agent. The same
+ * bound every other marker consumer in this lane applies (qa/lib/plan.mjs), for
+ * the same reason: a process that dies leaves its file behind, so freshness —
+ * never presence — is what makes a marker mean anything.
+ */
+export const HEARTBEAT_FRESH_MS = 5 * 60 * 1000;
+
+/**
+ * A hold this old is a wedge, not work. Past the ceiling the hook resumes
+ * blocking even while heartbeats keep arriving: an agent that has held the tree
+ * for three quarters of an hour is exactly the case the human needed to see, and
+ * a heartbeat proves the process is alive, never that it is making progress.
+ */
+export const HOLD_CEILING_MS = 45 * 60 * 1000;
+
+const MAX_TEXT = 200;
+
+const clip = (s, n = MAX_TEXT) => (typeof s === "string" ? s.trim().slice(0, n) : "");
+
+/** Fail-soft like every other status reader here: unreadable reads as absent. */
+export function readHold(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, ...HOLD_REL.split("/")), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(root, value) {
+  try {
+    const p = path.join(root, ...HOLD_REL.split("/"));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(value, null, 2)}\n`);
+    return { ok: true, hold: value };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Claim the tree. `holder` is a name a human will read in an alarm — an agent
+ * or session label, not a UUID: Anthropic's tool guidance is that agents (and
+ * the people reading after them) do far better with natural-language
+ * identifiers than with opaque ids, and this string's whole job is to be read
+ * at 3am by someone deciding whether to kill a process.
+ */
+export function claimHold(root, { holder, note = "", now = Date.now() } = {}) {
+  const name = clip(holder, 80) || "an agent";
+  const existing = readHold(root);
+  const at = existing && assessHold(existing, now).held ? existing.at : new Date(now).toISOString();
+  return writeJson(root, {
+    holder: name,
+    note: clip(note),
+    at,
+    heartbeatAt: new Date(now).toISOString(),
+  });
+}
+
+/**
+ * Still here, still working. Optionally re-states what "here" means — an agent
+ * that only says "alive" is barely better than the `find` that started this.
+ */
+export function beatHold(root, { note, now = Date.now() } = {}) {
+  const existing = readHold(root);
+  if (!existing) return { ok: false, error: "no hold to beat — claim one first" };
+  return writeJson(root, {
+    ...existing,
+    note: note === undefined ? existing.note : clip(note),
+    heartbeatAt: new Date(now).toISOString(),
+  });
+}
+
+export function releaseHold(root) {
+  try {
+    fs.rmSync(path.join(root, ...HOLD_REL.split("/")), { force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Is a hold in force, and what does it say?
+ *
+ * Every negative branch names WHY, because this feeds an alarm's text: "no
+ * agent holds the tree" and "an agent claimed it 50 minutes ago and is past the
+ * ceiling" call for opposite actions by the human reading them.
+ *
+ * @param {object|null} hold
+ * @param {number} now
+ * @returns {{held: boolean, reason: string, holder?: string, note?: string,
+ *            heldMs?: number, sinceBeatMs?: number, expired?: boolean}}
+ */
+export function assessHold(hold, now = Date.now()) {
+  if (!hold || typeof hold !== "object") return { held: false, reason: "no agent holds the tree" };
+  const at = Date.parse(hold.at);
+  const beat = Date.parse(hold.heartbeatAt ?? hold.at);
+  if (Number.isNaN(at) || Number.isNaN(beat)) return { held: false, reason: "the hold file has no readable timestamp" };
+
+  const heldMs = Math.max(0, now - at);
+  const sinceBeatMs = Math.max(0, now - beat);
+  const holder = clip(hold.holder, 80) || "an agent";
+  const note = clip(hold.note);
+  const base = { holder, note, heldMs, sinceBeatMs };
+
+  if (sinceBeatMs > HEARTBEAT_FRESH_MS) {
+    return {
+      ...base,
+      held: false,
+      expired: true,
+      reason: `${holder} last checked in ${formatAge(sinceBeatMs)} — that is a crashed writer, not a live agent`,
+    };
+  }
+  if (heldMs > HOLD_CEILING_MS) {
+    return {
+      ...base,
+      held: false,
+      expired: true,
+      reason: `${holder} has held the tree for ${formatAge(heldMs)}, past the ${formatAge(HOLD_CEILING_MS)} ceiling — a heartbeat proves the process is alive, not that it is progressing`,
+    };
+  }
+  return { ...base, held: true, reason: `${holder} has held the tree for ${formatAge(heldMs)}` };
+}
+
+/**
+ * The ONE line an alarm prints instead of demanding a lane run. It says who,
+ * since when, what they said they were doing, and what the reader should do —
+ * "specific and actionable", which the alarm it replaces was not.
+ */
+export function describeHold(assessment) {
+  if (!assessment?.held) return null;
+  const what = assessment.note ? ` (${assessment.note})` : "";
+  return (
+    `${assessment.holder} has held this tree for ${formatAge(assessment.heldMs)}${what} — staleness is expected while it works. ` +
+    `Wait for it rather than starting a lane on a half-edited tree; \`node qa/plan.mjs --release\` if it is gone.`
+  );
+}
+
+/**
+ * Does a hold EXPLAIN this refusal? (It never lifts it — see the header.)
+ *
+ * The whitelist is the safety property, and it is deliberately two entries
+ * long. A hold explains why fresh evidence is ABSENT — no receipt yet, or the
+ * tree has moved under one — because those are the two states a working agent
+ * legitimately produces. It never explains a receipt that says something is
+ * wrong: for a FAIL, a forgery, a skipped device tier or an unreadable surface
+ * the hold is simply not the cause, and offering it as one would send the
+ * reader to wait for an agent when the actual problem is a red test. Inverting
+ * this to a blacklist would mean every refusal added later is treated as
+ * agent-explicable by default, which is how an alarm starts lying.
+ *
+ * @param {{valid: boolean, reason?: string}} result
+ * @param {object|null} receipt
+ * @returns {boolean}
+ */
+export function holdExplains(result, receipt) {
+  if (!result || result.valid) return false;
+  // No receipt at all: the agent has not finished enough to run the lane.
+  if (receipt === null || receipt === undefined) return true;
+  // The tree moved under a receipt that itself PASSED — the signature of an
+  // agent mid-edit. A receipt that was not a PASS is contradicting evidence and
+  // is never excused, whatever moved since.
+  return receipt.verdict === "PASS" && /^source changed since the receipt/.test(String(result.reason ?? ""));
+}
+
+/** "40s" / "12 min" / "1h 5m" — freshness a human can weigh at a glance. */
+export function formatAge(ms) {
+  if (!(ms >= 0)) return "an unknown time";
+  if (ms < 90_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 90 * 60_000) return `${Math.round(ms / 60_000)} min`;
+  const h = Math.floor(ms / 3_600_000);
+  return `${h}h ${Math.round((ms - h * 3_600_000) / 60_000)}m`;
+}

package/template/qa/lib/evidence-badge.mjs

@@ -149,10 +149,10 @@ export function updateReadmeBadge(root) {
   // The same rule for the two other receipts qa/receipt-check.mjs refuses as
   // done-evidence: smoke (Rule 0 — proves the framework, never the change) and
   // nightly (proves the harness and the tree's invariants). Both derive no
-  // rung, and a smoke run — scripts/framework-check.mjs runs one on every
-  // scaffold — was rewriting a true L1 badge to "rung unrecorded". Found on
-  // 2026-09-03 by deriving the affected filter on a fresh app: README.md was
-  // the dirty file. Receipts predating `stage` are read by profile.
+  // rung, and a smoke run — qa/framework-check.mjs runs several, and restores
+  // this file afterwards — was rewriting a true L1 badge to "rung unrecorded".
+  // Found on 2026-09-03 by deriving the affected filter on a fresh app:
+  // README.md was the dirty file. Receipts predating `stage` are read by profile.
   const stage = receipt && (typeof receipt.stage === "string" ? receipt.stage : receipt.profile);
   if (stage === "smoke" || stage === "nightly") {
     return { changed: false, reason: `${stage} run — refused as done-evidence, so the badge is left as it stands` };

package/template/qa/lib/framework-check.mjs

@@ -0,0 +1,397 @@
+// framework-check.mjs (lib) — Rule 0's instrument, aimed at an app's OWN tree.
+//
+// GATE-RULES Rule 0 says: before any real work is pointed at the harness, prove
+// the FRAMEWORK returns — a deterministic PASS and a deterministic FAIL, fast,
+// through the real lane machinery, with a bound short enough that a hang is
+// obvious rather than patient.
+//
+// create-cmp's own `scripts/framework-check.mjs` proves that for the ENGINE: it
+// stamps a scratch app and reads the lane it just shipped. That script has never
+// existed inside a generated project, and it never can — it needs `bin/create-
+// cmp.mjs` and a tree to stamp. Meanwhile the lane that DOES ship names it four
+// times (verify.mjs, steps-cmp.mjs, evidence-badge.mjs, USAGE.md), pointing every
+// adopter at a path they do not have.
+//
+// That dangling reference has a measured cost. payment-blueprint read those
+// comments, could not find the file, and hand-built its own copy with nine
+// plants; then, months later, briefed a whole wave to prove new gates by hand —
+// plant, `./gradlew`, confirm red, revert, build again, 30–60 s per cycle — and
+// burned ~38 minutes reproducing exactly what the missing instrument does in
+// seconds. Their own diagnosis was "I failed to check what already existed". The
+// truer reading is narrower and is ours: the harness advertised a tool it never
+// handed over, so there was nothing in their tree to find.
+//
+// This module is the half of that instrument an app can run against itself. The
+// plants are DERIVED from the tree rather than hardcoded, because an adopted
+// project is not a stamped Compose app: it may have no `specs/`, no `qa/e2e/`,
+// no Kotlin test source at all. A plant whose target is absent is reported as
+// unavailable WITH ITS REASON and does not silently vanish — a framework check
+// that skips everything and prints PASS is the failure this exists to refuse.
+//
+// Pure by construction: every function here takes data and returns data. The IO
+// — reading the tree, writing the plant, running the lane, reverting in a
+// `finally` — lives in the runner (qa/framework-check.mjs), so the decisions
+// this file makes are unit-testable without a scaffold.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/framework-check.mjs in the
+// create-cmp repo. The copy in a generated project's qa/lib/ is vendored
+// byte-identical at scaffold time — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+
+/**
+ * Per-direction bound. Rule 0's whole claim is about SPEED of refusal, so the
+ * default is small on purpose: the smoke profile is every pure-Node gate and no
+ * Gradle, which returns in around a second on a real tree. A direction that
+ * does not return inside the bound is killed and reported as a hang — the bound
+ * IS the assertion, never a courtesy timeout waited out.
+ */
+export const DEFAULT_BOUND_MS = 10_000;
+
+/**
+ * Every plant this instrument knows how to make. The kinds are named so tests
+ * (and a report) can talk about them without matching prose.
+ */
+export const PLANT_KINDS = Object.freeze({
+  ORPHANED_CITATION: "orphaned-citation",
+  UNBOUND_CITATION: "unbound-citation",
+  TIER_UNMET: "tier-unmet",
+  FEATURE_WITHOUT_FLOW: "feature-without-flow",
+  NESTED_FLOW: "flow-the-lane-never-runs",
+  NARROWED_SURFACE: "narrowed-surface",
+  EDITED_LANE: "edited-lane",
+});
+
+/**
+ * The plants that need nothing but a lane. `harnessIntegrity` reads the machine-
+ * owned region, which exists in every project that has a lane at all — so these
+ * two are the floor. If even these cannot run, the tree has no harness to check
+ * and the instrument must say so rather than report a vacuous PASS.
+ */
+export const FLOOR_KINDS = Object.freeze([PLANT_KINDS.NARROWED_SURFACE, PLANT_KINDS.EDITED_LANE]);
+
+/** A clause id at the head of a spec list item: `- **HOME-02** — …`. */
+const CLAUSE_RE = /^-\s+\*\*([A-Z][A-Z0-9]*-\d{2,})\*\*/m;
+
+/** `# SPEC: HOME-02` in a flow file — the citation an e2e journey carries. */
+const FLOW_CITATION_RE = /^#\s*SPEC:\s*([A-Z][A-Z0-9]*-\d{2,})/m;
+
+/**
+ * The first clause id in a spec, or null. Used to pick something real to plant
+ * against: a clause that already exists and is already cited is the only kind
+ * whose removal proves a gate READS, rather than proving a gate rejects garbage.
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function firstClauseId(text) {
+  if (typeof text !== "string") return null;
+  const m = text.match(CLAUSE_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * The clause a flow cites, or null.
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function flowCitation(text) {
+  if (typeof text !== "string") return null;
+  const m = text.match(FLOW_CITATION_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * The clause-id PREFIX ("HOME" from "HOME-02"), used to mint planted ids that
+ * cannot collide with a real clause: a spec's own family with a number far above
+ * anything hand-authored.
+ * @param {string} clause
+ * @returns {string}
+ */
+export function clauseFamily(clause) {
+  const m = String(clause ?? "").match(/^([A-Z][A-Z0-9]*)-/);
+  return m ? m[1] : "SPEC";
+}
+
+/**
+ * Decide which plants this tree can support, and say WHY each unavailable one
+ * is unavailable.
+ *
+ * @param {{specs?: Array<{rel: string, text: string}>,
+ *          flows?: Array<{rel: string, text: string}>,
+ *          harnessLib?: string[],
+ *          testDir?: string|null}} tree
+ * @returns {{plants: Array<{kind: string, label: string, step: string,
+ *            names: string[], target: object}>,
+ *           unavailable: Array<{kind: string, reason: string}>}}
+ */
+export function selectPlants(tree) {
+  const specs = Array.isArray(tree?.specs) ? tree.specs : [];
+  const flows = Array.isArray(tree?.flows) ? tree.flows : [];
+  const harnessLib = Array.isArray(tree?.harnessLib) ? tree.harnessLib : [];
+  const testDir = tree?.testDir ?? null;
+
+  const plants = [];
+  const unavailable = [];
+  const skip = (kind, reason) => unavailable.push({ kind, reason });
+
+  // ── Spec-derived plants ──────────────────────────────────────────────────
+  const spec = specs.find((s) => firstClauseId(s?.text));
+  const clause = spec ? firstClauseId(spec.text) : null;
+
+  if (!spec) {
+    const why = specs.length
+      ? `no clause of the form "- **ID-NN**" in ${specs.length} spec file(s)`
+      : "no spec files — nothing declares behavior to plant against";
+    for (const kind of [PLANT_KINDS.ORPHANED_CITATION, PLANT_KINDS.UNBOUND_CITATION, PLANT_KINDS.TIER_UNMET]) skip(kind, why);
+  } else {
+    // Renaming a live clause orphans every citation of it: specCoverage must
+    // name the id it can no longer find.
+    plants.push({
+      kind: PLANT_KINDS.ORPHANED_CITATION,
+      label: "orphaned citation",
+      step: "specCoverage",
+      names: [clause],
+      target: { spec: spec.rel, clause },
+    });
+
+    const family = clauseFamily(clause);
+    // A tag on a CLASS with no test inside the binding window: the clause
+    // exists, the tag exists, and nothing runs. The two remaining spec plants
+    // need somewhere to put that Kotlin, so they hang on a test source dir.
+    if (!testDir) {
+      const why = "no Kotlin test source directory — a planted citation has nowhere to live";
+      skip(PLANT_KINDS.UNBOUND_CITATION, why);
+      skip(PLANT_KINDS.TIER_UNMET, why);
+    } else {
+      plants.push({
+        kind: PLANT_KINDS.UNBOUND_CITATION,
+        label: "unbound citation",
+        step: "specCoverage",
+        names: [`${family}-99`],
+        target: { spec: spec.rel, clause: `${family}-99`, testDir },
+      });
+      plants.push({
+        kind: PLANT_KINDS.TIER_UNMET,
+        label: "tier unmet",
+        step: "specCoverage",
+        names: [`${family}-98`],
+        target: { spec: spec.rel, clause: `${family}-98`, testDir },
+      });
+    }
+  }
+
+  // ── Flow-derived plants ──────────────────────────────────────────────────
+  // Both strip EVERY citation from every flow, not just one line. e2eCoverage
+  // asks whether a screen feature has any device journey at all, so removing a
+  // single `# SPEC:` from a flow that carries several leaves the feature
+  // covered and the gate — correctly — green. A plant that does not actually
+  // produce the violation is worse than no plant: it reads as a calibrated
+  // gate while proving nothing.
+  const citingFlows = flows.filter((f) => flowCitation(f?.text));
+  if (!citingFlows.length) {
+    const why = flows.length
+      ? `no "# SPEC:" citation in ${flows.length} flow file(s) — e2eCoverage has nothing to lose`
+      : "no qa/e2e flows — this project declares no device journeys";
+    skip(PLANT_KINDS.FEATURE_WITHOUT_FLOW, why);
+    skip(PLANT_KINDS.NESTED_FLOW, why);
+  } else {
+    const rels = citingFlows.map((f) => f.rel);
+    // A real feature with a screen and a spec and no device journey at all.
+    plants.push({
+      kind: PLANT_KINDS.FEATURE_WITHOUT_FLOW,
+      label: "feature without a flow",
+      step: "e2eCoverage",
+      names: [],
+      // FAIL BY NAME, without knowing this project's feature names: the gate
+      // must name the feature it caught, in the [brackets] its reason uses.
+      reasonPattern: String.raw`\[[^\]\s]+\]`,
+      target: { flows: rels },
+    });
+    // The citations move into a subdirectory Maestro's directory run never
+    // executes. The tags exist, the YAML is real, and nothing runs it — which
+    // must read exactly like having no journey.
+    plants.push({
+      kind: PLANT_KINDS.NESTED_FLOW,
+      label: "flow the lane never runs",
+      step: "e2eCoverage",
+      names: [],
+      reasonPattern: String.raw`\[[^\]\s]+\]`,
+      target: { flows: rels, nestInto: "qa/e2e/wip" },
+    });
+  }
+
+  // ── Region plants — the floor ────────────────────────────────────────────
+  // A narrowed declaration un-attests a whole layer while every checker stays
+  // intact (payment-blueprint's planted proof); an edited lane cannot vouch for
+  // its own verdict. Both are read by harnessIntegrity, which needs only a lane.
+  plants.push({
+    kind: PLANT_KINDS.NARROWED_SURFACE,
+    label: "narrowed surface declaration",
+    step: "harnessIntegrity",
+    names: ["unrecorded"],
+    hookPattern: "harnessIntegrity|vouch",
+    target: { declaration: "qa/verified-surface.json" },
+  });
+
+  const spine = harnessLib.find((rel) => rel.endsWith("/spec-coverage.mjs")) ?? harnessLib[0] ?? null;
+  if (!spine) {
+    skip(PLANT_KINDS.EDITED_LANE, "no machine-owned lane files found under qa/lib — there is no region to edit");
+  } else {
+    plants.push({
+      kind: PLANT_KINDS.EDITED_LANE,
+      label: "edited lane cannot vouch",
+      step: "harnessIntegrity",
+      names: ["modified"],
+      hookPattern: "harnessIntegrity|vouch",
+      target: { file: spine },
+    });
+  }
+
+  return { plants, unavailable };
+}
+
+/**
+ * Is this set of plants enough to make a claim at all?
+ *
+ * The refusal is the point. An instrument that finds nothing to plant and
+ * prints PASS has proven that it ran, not that the framework returns — the
+ * "green with gaps" the harness exists to refuse, applied to itself.
+ *
+ * @param {Array<{kind: string}>} plants
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function assessCoverage(plants) {
+  const kinds = new Set((plants ?? []).map((p) => p?.kind));
+  const missingFloor = FLOOR_KINDS.filter((k) => !kinds.has(k));
+  if (missingFloor.length === FLOOR_KINDS.length) {
+    return {
+      ok: false,
+      reason:
+        "no plant could be made at all — this tree has no machine-owned lane to check. " +
+        "Run this from a project root whose qa/lib/ carries the vendored harness.",
+    };
+  }
+  if (missingFloor.length) {
+    return { ok: false, reason: `the region plants are the floor and ${missingFloor.join(", ")} could not be made` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Judge one planted run. Every branch here is a distinct framework defect and
+ * says which one it is: a hang, a lane that produced no receipt, a guard that
+ * did not fail, or a guard that failed WITHOUT NAMING what it caught.
+ *
+ * "FAIL BY NAME" is not decoration. A gate that fails with a generic message
+ * costs the reader the diagnosis every time it fires, and — worse — cannot be
+ * told apart from a gate failing for an unrelated reason, which is how a
+ * calibration passes on a gate that was never actually read.
+ *
+ * @param {{hung?: boolean, ms?: number, exit?: number|null,
+ *          receipt?: {verdict?: string, steps?: Array<object>}|null,
+ *          stderr?: string}} run
+ * @param {{label: string, step: string, names?: string[]}} plant
+ * @param {number} boundMs
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function assessPlantRun(run, plant, boundMs) {
+  const label = plant?.label ?? "(unnamed plant)";
+  if (run?.hung) {
+    return { ok: false, reason: `"${label}" did not return inside ${boundMs}ms — the framework HANGS on a failing input` };
+  }
+  const receipt = run?.receipt;
+  if (!receipt) {
+    const tail = String(run?.stderr ?? "").slice(-600);
+    return { ok: false, reason: `"${label}" returned no receipt (exit ${run?.exit ?? "?"})${tail ? `:\n${tail}` : ""}` };
+  }
+  const row = (receipt.steps ?? []).find((s) => s?.name === plant.step);
+  if (receipt.verdict !== "FAIL" || !row || row.verdict !== "FAIL") {
+    return {
+      ok: false,
+      reason: `planted "${label}" and the lane said ${receipt.verdict} (${plant.step}: ${row ? row.verdict : "no row"}) — the guard did not FAIL BY NAME`,
+    };
+  }
+  const reason = String(row.reason ?? "");
+  for (const name of plant.names ?? []) {
+    if (!reason.includes(name)) {
+      return { ok: false, reason: `${plant.step} FAILed on "${label}" but did not NAME ${name}:\n${reason}` };
+    }
+  }
+  // Some gates name something the selector cannot know in advance — a feature
+  // this project happens to have. The pattern is how those still assert FAIL BY
+  // NAME instead of settling for "it went red".
+  if (plant.reasonPattern && !new RegExp(plant.reasonPattern).test(reason)) {
+    return { ok: false, reason: `${plant.step} FAILed on "${label}" but named nothing matching /${plant.reasonPattern}/:\n${reason}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Judge the baseline (and the post-revert re-run): a tree that cannot go green
+ * on its own has nothing to plant against, and every FAIL below would be
+ * unattributable.
+ *
+ * @param {{hung?: boolean, receipt?: object|null, exit?: number|null, stderr?: string}} run
+ * @param {string} phase  "baseline" or "revert"
+ * @param {number} boundMs
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function assessGreenRun(run, phase, boundMs) {
+  if (run?.hung) {
+    return { ok: false, reason: `the ${phase} run did not return inside ${boundMs}ms — the framework HANGS on a passing input` };
+  }
+  if (!run?.receipt) {
+    const tail = String(run?.stderr ?? "").slice(-600);
+    return { ok: false, reason: `the ${phase} run returned no receipt (exit ${run?.exit ?? "?"})${tail ? `:\n${tail}` : ""}` };
+  }
+  if (run.receipt.verdict !== "PASS") {
+    const bad = (run.receipt.steps ?? [])
+      .filter((s) => s?.verdict === "FAIL" || s?.verdict === "ERROR")
+      .map((s) => `${s.name}: ${String(s.reason ?? "").split("\n")[0]}`)
+      .join("; ");
+    const suffix =
+      phase === "revert"
+        ? " — the plants were not the only cause, or a revert did not restore the tree"
+        : " — fix the tree before calibrating anything against it";
+    return { ok: false, reason: `the ${phase} run is ${run.receipt.verdict} (${bad || "no failing row named"})${suffix}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Rule 1's stated bound, made checkable.
+ *
+ * Rule 1 says a calibration is "four steps, seconds each". That sentence has
+ * always been prose, and prose does not refuse: payment-blueprint calibrated
+ * through a 30–60 s composite Gradle build, which violated the rule on its own
+ * terms from the first cycle, and nothing noticed for three occurrences. The
+ * cost is not the single cycle — it is per-instance cost times every instance,
+ * which is how 38 minutes disappears into something that looks like rigour.
+ *
+ * A calibration cycle slower than this is not wrong, but it is a finding: it
+ * means the plant is being run through the wrong instrument, and the report
+ * must say so while the choice is still cheap to change.
+ */
+export const CALIBRATION_BUDGET_MS = 5_000;
+
+/**
+ * @param {Array<{label: string, ms: number}>} cycles
+ * @param {number} [budgetMs]
+ * @returns {{withinBudget: boolean, slowest: {label: string, ms: number}|null,
+ *            totalMs: number, note: string|null}}
+ */
+export function assessCalibrationCost(cycles, budgetMs = CALIBRATION_BUDGET_MS) {
+  const rows = Array.isArray(cycles) ? cycles.filter((c) => Number.isFinite(c?.ms)) : [];
+  const totalMs = rows.reduce((n, c) => n + c.ms, 0);
+  if (!rows.length) return { withinBudget: true, slowest: null, totalMs: 0, note: null };
+  const slowest = rows.reduce((a, b) => (b.ms > a.ms ? b : a));
+  if (slowest.ms <= budgetMs) return { withinBudget: true, slowest, totalMs, note: null };
+  return {
+    withinBudget: false,
+    slowest,
+    totalMs,
+    note:
+      `slowest calibration cycle "${slowest.label}" took ${slowest.ms}ms against a ${budgetMs}ms budget. ` +
+      `GATE-RULES Rule 1 calls a calibration "four steps, seconds each" — a cycle past that is being run ` +
+      `through the wrong instrument, and the cost is paid on every plant forever.`,
+  };
+}