cool-workflow 0.2.3 → 0.2.5

package/scripts/release-flow.js

@@ -15,15 +15,22 @@
 // Modes:
 //   node release-flow.js [--check]                 gate + review, no mutation (default)
 //   node release-flow.js --cut --version x.y.z [--push]
-//                                                  also bump:version, commit verdict, tag,
-//                                                  (push), and — when --push — create the
-//                                                  GitHub Release for the tag (idempotent;
-//                                                  opt out with --no-release)
+//                                                  preflight (fail-fast checks BEFORE the
+//                                                  gate/vendor/reviewer spend anything),
+//                                                  then gate + review, then bump:version,
+//                                                  commit verdict, tag, and — when --push —
+//                                                  push ONLY the tag (refs/tags/vx.y.z; the
+//                                                  verdict commit is a one-hop leaf off the
+//                                                  reviewed main tip, it never lands on a
+//                                                  branch) and create the GitHub Release
+//                                                  (idempotent; opt out with --no-release)
 //   node release-flow.js --release --version x.y.z create-or-skip the GitHub Release for an
 //                                                  already-pushed tag (backfill); no gate/cut.
 //                                                  Fails closed if gh can't create it; add
 //                                                  --soft for best-effort (skip-not-fail).
-// Flags also accepted: --prev-tag <t>, --agent-command "...", --agent-model m, --dry-run
+// Flags also accepted: --prev-tag <t>, --agent-command "...", --agent-model m, --dry-run,
+//   --preflight-only (run the cut preflight and stop — used by release-oneclick.js),
+//   --allow-stale-head (skip the HEAD == origin/main tip check, deliberate re-cuts only)
 //
 // VERDICT CONTRACT (auto-generated by --cut, never write by hand):
 //   Path:  .cw-release/review-<FULLSHA>.verdict
@@ -36,7 +43,7 @@
 //   the verdict file's exact bytes, writing a sidecar
 //   .cw-release/review-<FULLSHA>.verdict.sig (base64 ed25519). Once
 //   .cw-release/verdict-signing.pub is committed to the repo, release-gate.yml,
-//   npm-publish.yml, and block-unapproved-tag.sh all start REQUIRING a valid
+//   npm-publish.yml, and block-unapproved-tag.js all start REQUIRING a valid
 //   signature in addition to the APPROVED text check — closing the gap where
 //   anyone with shell access could hand-write a passing verdict file. Until
 //   that public key is committed, every check stays exactly as before
@@ -44,7 +51,7 @@
 //
 // Test seams (smoke/operator only, never the delegated agent):
 //   CW_RELEASE_FLOW_GATE_CMD  overrides the deterministic gate command
-//     (default: `bash <thisdir>/release-gate.sh`) so the smoke can exercise the
+//     (default: `node <thisdir>/release-gate.js`) so the smoke can exercise the
 //     orchestration layer without re-running the full build/test suite.
 //   CW_RELEASE_FLOW_GH_CMD    overrides the `gh` binary (single executable token,
 //     spawned shell:false) so the smoke can stub GitHub Release calls offline.
@@ -100,15 +107,25 @@ if (top.status !== 0) die("not inside a git work tree");
 const repoRoot = top.stdout.trim();
 
 const HEAD = git(["rev-parse", "HEAD"]).out;
-// Previous tag, excluding any tag that already points at HEAD (so this works
-// whether run before tagging or re-run on a freshly tagged commit — same fix
-// as release-gate.sh).
+
+// ---- release-tag lookup (semver-ordered, NOT git-ancestry-walked) ---------
+// The lookup itself lives in release-tags.js, SHARED with release-gate.js so
+// the two can never drift (the gate used to carry a bash port of it). See
+// that file's header for why this is a semver question, not `git describe`.
+const releaseTags = require("./release-tags.js");
+const parseSemverTag = releaseTags.parseSemverTag;
+const compareSemver = releaseTags.compareSemver;
+const gitTagOut = (args) => git(args).out;
+function listReleaseTagsDesc() {
+  return releaseTags.listReleaseTagsDesc(gitTagOut);
+}
+
+// The most recent ALREADY-RELEASED tag as of right now, excluding any tag
+// that already points at HEAD (so this works whether run before tagging or
+// re-run on a freshly tagged commit).
 function resolvePrevTag() {
   if (prevTagArg) return prevTagArg;
-  const headTags = git(["tag", "--points-at", "HEAD"]).out.split("\n").filter(Boolean);
-  let prev = git(["describe", "--tags", "--abbrev=0"]).out;
-  if (prev && headTags.includes(prev)) prev = git(["describe", "--tags", "--abbrev=0", "HEAD^"]).out;
-  return prev || "";
+  return releaseTags.resolvePrevReleaseTag(gitTagOut);
 }
 const PREV_TAG = resolvePrevTag();
 
@@ -122,7 +139,7 @@ function runGate() {
     // the smoke and operator overrides only, never the delegated agent.
     r = spawnSync(override, { cwd: repoRoot, encoding: "utf8", shell: true, stdio: "inherit" });
   } else {
-    r = spawnSync("bash", [path.join(scriptsDir, "release-gate.sh")], {
+    r = spawnSync(process.execPath, [path.join(scriptsDir, "release-gate.js")], {
       cwd: repoRoot,
       encoding: "utf8",
       stdio: "inherit"
@@ -166,17 +183,28 @@ function runVendorPreflight() {
 }
 
 // ---- 2. independent reviewer, delegated to the configured agent -------------
-// Default reviewer deadline. The zero-trust reviewer re-runs release-gate.sh,
+// Default reviewer deadline. The zero-trust reviewer re-runs release-gate.js,
 // whose sequential test suite alone is ~12 min, then reads + reasons over the
 // diff — so a 10-min default guaranteed a timeout on a real release. 30 min gives
 // headroom; override with CW_AGENT_TIMEOUT_MS (or --agent-timeout-ms).
 const REVIEWER_TIMEOUT_MS = 1800000;
 function reviewerPromptBody() {
   // Reuse the committed reviewer spec as the prompt; strip YAML frontmatter.
+  // Fail closed if the spec is gone or empty: a missing/empty spec used to
+  // yield "", which shipped the reviewer an EMPTY review prompt (only the
+  // candidate context, no instructions) — a review with no rubric is worse
+  // than no review, since it still produces a signable verdict. This project's
+  // rule is to refuse the unverifiable, not fabricate a pass.
   const specPath = path.join(pluginRoot, "agents", "release-reviewer.md");
-  let body = fs.existsSync(specPath) ? fs.readFileSync(specPath, "utf8") : "";
-  body = body.replace(/^---[\s\S]*?---\n/, "");
-  return body.trim();
+  const rel = path.relative(repoRoot, specPath);
+  if (!fs.existsSync(specPath)) {
+    die(`reviewer prompt file is missing at ${rel} — will not run a review with an empty prompt. Restore agents/release-reviewer.md.`);
+  }
+  const body = fs.readFileSync(specPath, "utf8").replace(/^---[\s\S]*?---\n/, "").trim();
+  if (!body) {
+    die(`reviewer prompt file at ${rel} is empty after its header is removed — will not run a review with an empty prompt.`);
+  }
+  return body;
 }
 
 function buildReviewerInput(resultPath) {
@@ -215,11 +243,36 @@ function substitute(arg, map) {
   return arg.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in map ? String(map[k]) : m));
 }
 
+/** True when `line` is a REJECTED verdict line, allowing the markdown
+ *  decoration a reviewer commonly wraps it in (`**REJECTED**`, `REJECTED:`,
+ *  `### REJECTED`, `REJECTED.`) — stripped of leading heading/quote/emphasis
+ *  markers, the line must start with REJECTED not immediately followed by
+ *  another letter (so "REJECTEDLY speaking..." is still correctly NOT a
+ *  rejection marker). Must stay at least as permissive as the APPROVED
+ *  matcher below, or a decorated REJECTED can fall through to it. */
+function isRejectedLine(line) {
+  const stripped = line.trim().replace(/^[#>\s]+/, "").replace(/^[*_]+/, "");
+  return /^REJECTED(?![A-Za-z])/i.test(stripped);
+}
+
 /** Extract verdict lines from agent stdout. Returns the verdict text (first line
  *  must be APPROVED <sha> or REJECTED) or null if no valid verdict found.
  *  Also logs failures to stderr so the operator can inspect. */
 function extractVerdictFromStdout(stdout, resultPath) {
   const lines = stdout.split(/\r?\n/);
+  // Check for REJECTED first, over the WHOLE text, and return right away when
+  // found — do not also look for APPROVED in that case. This is the safe,
+  // fail-closed order (this project's own rule: fail closed, conservatively).
+  // A verbose agent wrapper can echo the required-format example back in its
+  // own output (e.g. a report that quotes the prompt's instructions), so the
+  // exact text "APPROVED <sha>" can show up even when the real verdict is
+  // REJECTED. If BOTH markers are present anywhere in the text, that must
+  // read as REJECTED, never as an approval that then gets a real signature.
+  const rejectedLine = lines.find((line) => isRejectedLine(line));
+  if (rejectedLine) {
+    process.stderr.write(`reviewer REJECTED via stdout — full output:\n${stdout.trim()}\n`);
+    return rejectedLine.trim();
+  }
   const approvedLine = lines.find((line) => /^APPROVED\s+\S+/.test(line.trim()));
   if (approvedLine) {
     const idx = lines.indexOf(approvedLine);
@@ -231,16 +284,25 @@ function extractVerdictFromStdout(stdout, resultPath) {
     say(`reviewer verdict captured from stdout → ${resultPath}`);
     return verdict;
   }
-  const rejectedLine = lines.find((line) => /^REJECTED/i.test(line.trim()));
-  if (rejectedLine) {
-    process.stderr.write(`reviewer REJECTED via stdout — full output:\n${stdout.trim()}\n`);
-    return rejectedLine.trim();
-  }
   // Partial: print the last 20 lines to help the operator diagnose.
   process.stderr.write(`reviewer stdout had no APPROVED/REJECTED line. Last 20 lines:\n${lines.slice(-20).join("\n").trim()}\n`);
   return null;
 }
 
+// The reviewer must never be able to read the verdict signing key or other
+// release secrets. The signing key is the ONLY thing that tells a real
+// reviewer's verdict apart from one an agent fabricated by hand — if the
+// reviewer process itself can read that key, it could sign its own made-up
+// approval, which defeats the whole point of signing. So strip these from
+// the env we hand to the reviewer child process, even though the operator's
+// own shell (this script's own process.env) may have them set.
+const REVIEWER_ENV_DENY = ["CW_RELEASE_VERDICT_PRIVKEY", "CW_AGENT_ATTEST_PRIVKEY", "CW_WORKBENCH_TOKEN"];
+function buildReviewerEnv() {
+  const env = { ...process.env, CW_RELEASE_REVIEW: "1" };
+  for (const key of REVIEWER_ENV_DENY) delete env[key];
+  return env;
+}
+
 function delegateReview(resultPath, inputPath) {
   // Reuse the canonical agent-config resolver (flags > env > file).
   let resolveAgentConfig;
@@ -293,6 +355,13 @@ function delegateReview(resultPath, inputPath) {
     // Capture stdout so agents that print verdicts (rather than writing the
     // result file) are supported. Agents that DO write the file still work:
     // the file takes precedence. stderr goes to the terminal for live output.
+    // A verdict file left over from an earlier run — or planted by anyone with
+    // write access to this checkout — must never survive into a fresh review
+    // round. Delete it (and any .sig sidecar) BEFORE the reviewer runs, so the
+    // "verdict file already exists" check right after spawnSync only ever sees
+    // a file the reviewer wrote THIS round, never a stale or planted one.
+    try { fs.unlinkSync(resultPath); } catch {}
+    try { fs.unlinkSync(`${resultPath}.sig`); } catch {}
     const r = spawnSync(bin, args, {
       cwd: repoRoot,
       // CW_RELEASE_REVIEW=1 is a vendor-agnostic signal that THIS spawn is a
@@ -301,7 +370,9 @@ function delegateReview(resultPath, inputPath) {
       // exec-capable sandbox — a read-only/low-effort reviewer can't execute the
       // gate it judges and degrades to fabricated verdicts. Preflight liveness
       // probes never set it, so they stay fast and read-only.
-      env: { ...process.env, CW_RELEASE_REVIEW: "1" },
+      // buildReviewerEnv() also strips the verdict signing key and other release
+      // secrets from what the reviewer child process can see — see its comment.
+      env: buildReviewerEnv(),
       encoding: "utf8",
       timeout: cfg.timeoutMs || REVIEWER_TIMEOUT_MS,
       shell: false,
@@ -362,7 +433,7 @@ function verifyVerdict(resultPath) {
   const lines = text.split(/\r?\n/);
   const firstLine = lines[0] || "";
   if (firstLine !== `APPROVED ${HEAD}`) {
-    if (firstLine.toUpperCase() !== "REJECTED") {
+    if (!isRejectedLine(firstLine)) {
       const normalized = extractVerdictFromStdout(text, resultPath);
       if (normalized && normalized.split(/\r?\n/)[0] === `APPROVED ${HEAD}`) {
         fs.writeFileSync(resultPath, `${normalized}\n`);
@@ -381,7 +452,11 @@ function resolveVerdictPrivateKey(value) {
   const trimmed = String(value).trim();
   if (trimmed.includes("BEGIN") && trimmed.includes("KEY")) return trimmed;
   if (fs.existsSync(trimmed)) return fs.readFileSync(trimmed, "utf8");
-  die(`CW_RELEASE_VERDICT_PRIVKEY does not point to a readable key file or inline PEM: ${trimmed}`);
+  // NEVER echo the value: if the operator set the var to inline key material
+  // that failed the BEGIN/KEY check (e.g. a raw base64 body), interpolating
+  // `trimmed` here would print the secret to stderr — which the oneclick flow
+  // tees into the operator's release log. Describe it instead.
+  die(`CW_RELEASE_VERDICT_PRIVKEY (length ${trimmed.length}) is neither a readable key file path nor an inline PEM (must contain BEGIN and KEY).`);
 }
 
 /** Called only after verifyVerdict() has confirmed resultPath's bytes are a
@@ -444,10 +519,23 @@ function repoSlug() {
   return m ? { owner: m[1], repo: m[2] } : null;
 }
 
-// The previous release tag relative to a SPECIFIC tag (not HEAD) — for the
-// compare link in the notes.
+// The previous release tag relative to a SPECIFIC target version (not HEAD's
+// ancestry) — for the compare link in the notes. See listReleaseTagsDesc's
+// header comment above for why this is a semver lookup, not `git describe`.
 function prevTagOf(version) {
-  return git(["describe", "--tags", "--abbrev=0", `v${version}^`]).out || "";
+  const target = parseSemverTag(`v${version}`);
+  if (!target) return "";
+  const found = listReleaseTagsDesc().find((t) => compareSemver(t.semver, target) < 0);
+  return found ? found.tag : "";
+}
+
+// Full regex escape (same shape as parity-check.js's helper — scripts stay
+// zero-dependency single files, so it is copied, not required). The version
+// is SEMVER-validated on every path that reaches here, but escaping every
+// metacharacter costs nothing and keeps the RegExp construction safe on its
+// own terms.
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
 // Extract the `## <version>` section body from the CHANGELOG AS SHIPPED AT THE
@@ -456,7 +544,7 @@ function changelogSection(version) {
   const show = git(["show", `v${version}:CHANGELOG.md`]);
   if (show.code !== 0 || !show.out) return "";
   const lines = show.out.split(/\r?\n/);
-  const esc = version.replace(/\./g, "\\.");
+  const esc = escapeRegExp(version);
   const startRe = new RegExp(`^## \\[?${esc}\\b`);
   let start = -1;
   for (let i = 0; i < lines.length; i++) if (startRe.test(lines[i])) { start = i; break; }
@@ -558,10 +646,120 @@ function releaseGitHub(version, { required = false } = {}) {
   return true;
 }
 
+// ---- 2b. cut preflight (fail fast, BEFORE any paid step) --------------------
+// Every check here answers one question: "will this cut die AFTER the gate,
+// the live vendor preflight, and the reviewer have already run?" Each check
+// was a real post-reviewer failure in the v0.2.3 cut (2026-07-10) — a missing
+// --version, an unsigned verdict the CI gate then rejected, a left-over local
+// tag, and a two-hop recovery that broke the HEAD~1 topology rule. All of
+// them are answerable in under a second, so answer them FIRST.
+//
+// Fixture safety: each check is gated on the thing it checks being present
+// (a committed signing pubkey, a CHANGELOG.md, an `origin` remote), so the
+// smoke fixtures — bare repos with none of those — pass through untouched.
+function preflightCut() {
+  say("[0/3] cut preflight");
+  // (a) version — cheap and load-bearing for every later step. Checking it
+  // here (not only inside cut()) is what stops a full gate+reviewer run from
+  // being thrown away over a missing flag.
+  if (!cutVersion || !/^\d+\.\d+\.\d+$/.test(cutVersion)) die("--cut requires --version x.y.z");
+
+  // (b) signing — once .cw-release/verdict-signing.pub is committed, CI's
+  // release-gate REQUIRES a valid signature; a cut without the private key
+  // configured would push an unsigned verdict that fails only in CI. Fail
+  // closed here instead, and also prove the configured key IS the committed
+  // key (a wrong key signs "successfully" and still fails in CI).
+  const pubPath = path.join(repoRoot, ".cw-release", "verdict-signing.pub");
+  if (fs.existsSync(pubPath)) {
+    const raw = process.env.CW_RELEASE_VERDICT_PRIVKEY;
+    if (!raw || !raw.trim()) {
+      die(
+        "verdict-signing.pub is committed, so CI requires a SIGNED verdict — set the private key first",
+        'fix:  export CW_RELEASE_VERDICT_PRIVKEY=~/.cw-keys/verdict-signing.key'
+      );
+    }
+    const pem = resolveVerdictPrivateKey(raw);
+    let key;
+    try {
+      key = crypto.createPrivateKey(pem);
+    } catch (error) {
+      die(`CW_RELEASE_VERDICT_PRIVKEY is not a readable private key: ${error.message}`);
+    }
+    if (key.asymmetricKeyType !== "ed25519") {
+      die(`CW_RELEASE_VERDICT_PRIVKEY is a ${key.asymmetricKeyType || "unknown"} key, not ed25519 — generate one with scripts/verdict-keygen.js`);
+    }
+    const derivedPub = crypto.createPublicKey(key).export({ type: "spki", format: "pem" }).toString().trim();
+    const committedPub = fs.readFileSync(pubPath, "utf8").trim();
+    if (derivedPub !== committedPub) {
+      die("CW_RELEASE_VERDICT_PRIVKEY does not match the committed .cw-release/verdict-signing.pub — wrong key; CI would reject its signature");
+    }
+  }
+
+  // (c) tag must not exist yet — a stale local tag makes cut() die at the very
+  // last step ("tag 'vX.Y.Z' already exists") after everything else has run.
+  if (git(["tag", "-l", `v${cutVersion}`]).out) {
+    die(`tag v${cutVersion} already exists locally — delete it first (git tag -d v${cutVersion}) or pick the next version`);
+  }
+
+  // (d) CHANGELOG must already carry the release section — release notes get
+  // pasted verbatim into the GitHub Release, and bump:version's content gate
+  // would only catch this inside cut(), after the reviewer.
+  const changelogPath = path.join(repoRoot, "CHANGELOG.md");
+  if (fs.existsSync(changelogPath) && !fs.readFileSync(changelogPath, "utf8").includes(`## ${cutVersion}`)) {
+    die(`CHANGELOG.md has no "## ${cutVersion}" section — write the release notes first`);
+  }
+
+  // (e) clean tree (tracked files only — cut()'s `git add -u` can never sweep
+  // an untracked stray in, so untracked files are not a cut hazard).
+  const dirty = git(["status", "--porcelain", "-uno"]).out;
+  if (dirty) die("working tree has tracked modifications — commit or stash them before a cut", dirty);
+
+  // (f) network-dependent checks, only when this cut will actually push and
+  // only when an `origin` remote exists (smoke fixtures have none):
+  if (PUSH && git(["remote"]).out.split("\n").includes("origin")) {
+    // remote tag must not exist (someone/some run already published this version)
+    const remoteTag = git(["ls-remote", "origin", `refs/tags/v${cutVersion}`]);
+    // Fail CLOSED on a failed ls-remote: a non-zero exit (network blip, auth
+    // error) is NOT evidence the tag is absent. Treating it as "no remote tag"
+    // (the old `code === 0 && out` shape) let a transient failure skip the
+    // already-published guard and cut a version that may already exist.
+    if (remoteTag.code !== 0) {
+      die(`could not check origin for tag v${cutVersion} (git ls-remote failed) — refusing to cut blind`, remoteTag.err);
+    }
+    if (remoteTag.out) {
+      die(`tag v${cutVersion} already exists on origin — this version is already published; pick the next version`);
+    }
+    // HEAD must be the current origin/main tip — cutting a stale HEAD publishes
+    // old code (nearly happened on the v0.2.2 cut).
+    if (git(["fetch", "origin", "main", "--quiet"]).code !== 0) {
+      die("git fetch origin main failed — a --push cut needs the network anyway; fix connectivity first");
+    }
+    const mainTip = git(["rev-parse", "origin/main"]).out;
+    if (mainTip !== HEAD && !has("--allow-stale-head")) {
+      die(
+        `HEAD (${HEAD.slice(0, 12)}) is not the origin/main tip (${mainTip.slice(0, 12)}) — a cut must release exactly what main has`,
+        "fix:  git fetch origin main && git checkout -B <branch> origin/main   (or pass --allow-stale-head if this is deliberate)"
+      );
+    }
+  }
+  say("cut preflight OK");
+}
+
 // ---- 3. optional cut (bump + commit verdict + tag + push) ------------------
 function cut(resultPath, capability) {
   if (!cutVersion || !/^\d+\.\d+\.\d+$/.test(cutVersion)) die("--cut requires --version x.y.z");
-  if (DRY_RUN) { say(`[dry-run] would: bump:version ${cutVersion}, commit verdict, tag v${cutVersion}${PUSH ? ", push" : ""}`); return; }
+  // HEAD is captured once at process start (const HEAD) and everything the cut
+  // signs/tags is bound to it. The gate + vendor preflight + the ~30-minute
+  // reviewer all run in the shared checkout in between, and this repo runs
+  // concurrent agent sessions — so re-verify HEAD has not moved before we
+  // commit the verdict onto (and tag) it. Tagging an interloper commit would
+  // publish an immutable vX.Y.Z that CI then rejects (verdict filename != HEAD),
+  // burning the version number. Fail closed and let the operator re-run.
+  const headNow = git(["rev-parse", "HEAD"]).out;
+  if (headNow !== HEAD) {
+    die(`HEAD moved during the release flow (expected ${HEAD.slice(0, 12)}, now ${headNow.slice(0, 12)}) — re-run to restart the flow from the current HEAD`);
+  }
+  if (DRY_RUN) { say(`[dry-run] would: bump:version ${cutVersion}, commit verdict, tag v${cutVersion}${PUSH ? `, push refs/tags/v${cutVersion} (tag only, no branch)` : ""}`); return; }
   const bump = spawnSync("npm", ["run", "bump:version", "--", cutVersion], { cwd: pluginRoot, encoding: "utf8", stdio: "inherit" });
   if (bump.status !== 0) die("bump:version failed");
   // Regenerate the gated project index after the version bump (PR #87 gate).
@@ -575,21 +773,34 @@ function cut(resultPath, capability) {
   // (that tripped pii-redaction-smoke and red-failed release-gate for v0.1.96).
   // `git add -u` touches tracked files only, so no untracked file can be swept in;
   // the verdict (and its .sig sidecar, when verdict signing is configured) are
-  // the only new paths the cut is allowed to add.
-  git(["add", "-u"]);
-  git(["add", "--", path.relative(repoRoot, resultPath)]);
+  // the only new paths the cut is allowed to add. Check every add's exit code:
+  // a swallowed git-add failure (a read-only object store, a locked index) used
+  // to surface only later as a confusing "verdict commit failed" — a cut that
+  // fails to stage the SIGNED verdict must die right here, before the commit.
+  const addTracked = git(["add", "-u"]);
+  if (addTracked.code !== 0) die("git add -u failed while staging the cut", addTracked.err);
+  const addVerdict = git(["add", "--", path.relative(repoRoot, resultPath)]);
+  if (addVerdict.code !== 0) die("git add of the verdict file failed", addVerdict.err);
   const sigPath = `${resultPath}.sig`;
-  if (fs.existsSync(sigPath)) git(["add", "--", path.relative(repoRoot, sigPath)]);
+  if (fs.existsSync(sigPath)) {
+    const addSig = git(["add", "--", path.relative(repoRoot, sigPath)]);
+    if (addSig.code !== 0) die("git add of the verdict signature failed", addSig.err);
+  }
   const commit = git(["commit", "-m", `chore(release): record APPROVED reviewer verdict for v${cutVersion}`]);
   if (commit.code !== 0) die("verdict commit failed", commit.err);
   const tag = git(["tag", "-a", `v${cutVersion}`, "-m", `v${cutVersion}: ${capability || "release"}`]);
   if (tag.code !== 0) die("git tag failed", tag.err);
   if (PUSH) {
-    // Atomic: the verdict commit on HEAD and the tag land together or not at all.
-    // A non-atomic two-push could leave main advanced with no tag, so CI's
-    // release-gate (which fires on the tag) never runs and the release silently stalls.
-    const push = git(["push", "--atomic", "origin", "HEAD", `v${cutVersion}`]);
-    if (push.code !== 0) die("atomic push of HEAD + tag failed (nothing partially pushed)", push.err);
+    // Push ONLY the tag. The verdict commit is a one-hop leaf on the reviewed
+    // main-tip commit, reachable through the tag alone — it does not need to
+    // be on any branch. Pushing HEAD here used to (a) hit main's branch
+    // protection (enforce_admins blocks even the owner's direct push) or
+    // (b) mint a stray remote branch named after whatever branch the cut ran
+    // from. Tags are not protected in this repo, and CI's release-gate checks
+    // the TAG's own history (verdict at HEAD or HEAD~1), so the tag alone is
+    // the complete release artifact — proven live by the v0.2.3 cut.
+    const push = git(["push", "origin", `refs/tags/v${cutVersion}`]);
+    if (push.code !== 0) die("tag push failed (nothing was pushed)", push.err);
   }
   say(`tagged v${cutVersion}${PUSH ? " and pushed" : " (local only; push when ready)"}`);
   // Finishing step: create the GitHub Release for the just-pushed tag. Only when
@@ -614,6 +825,18 @@ function main() {
     return;
   }
 
+  // Fail-fast checks FIRST — nothing below (gate, live vendor calls, the
+  // reviewer) runs until every cheap precondition holds. --preflight-only
+  // lets an orchestrator (release-oneclick.js) run just this step. Without
+  // --cut there is no preflight to run, so answering ok:true would be a
+  // green light with zero checks done — refuse instead.
+  if (has("--preflight-only") && !MODE_CUT) die("--preflight-only requires --cut (there is no preflight to run in check/release mode)");
+  if (MODE_CUT) preflightCut();
+  if (has("--preflight-only")) {
+    process.stdout.write(`${JSON.stringify({ ok: true, mode: "preflight", version: cutVersion || null }, null, 2)}\n`);
+    return;
+  }
+
   const markerDir = path.join(repoRoot, ".cw-release");
   fs.mkdirSync(markerDir, { recursive: true });
   const resultPath = path.join(markerDir, `review-${HEAD}.verdict`);

package/scripts/release-gate.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+"use strict";
+// release-gate.js — deterministic release checks for cool-workflow.
+// Pass = writes .cw-release/gate-<HEAD-sha>.ok
+// This script encodes everything that does NOT need LLM judgment.
+// (Node port of the former release-gate.sh; behavior kept line for line —
+// same six steps, same messages, same exit map: 0 = PASSED, 1 = REJECTED.)
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { resolvePrevReleaseTag } = require("./release-tags.js");
+
+const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+if (top.status !== 0) {
+  process.stderr.write("release-gate: not inside a git work tree\n");
+  process.exit(1);
+}
+const REPO_ROOT = top.stdout.trim();
+
+function gitOut(args) {
+  const r = spawnSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+  return r.status === 0 ? (r.stdout || "").trim() : "";
+}
+
+const SHA = gitOut(["rev-parse", "HEAD"]);
+let FAIL = 0;
+function say(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+function fail(msg) {
+  say(`GATE FAIL: ${msg}`);
+  FAIL = 1;
+}
+
+// Resolve the PREVIOUS release tag by SEMVER ORDER, not ancestry — shared
+// with release-flow.js via release-tags.js (see that file's header for the
+// full story: `git describe --tags` walks ancestry and silently SKIPS the
+// true previous release tag under the tag-only-push design, making the
+// substance/test-evidence/cadence checks below compare against the wrong
+// baseline and pass permanently; ITERATION_LOG cycles 35/36).
+const PREV_TAG = resolvePrevReleaseTag(gitOut);
+
+// An empty PREV_TAG is ambiguous: (a) the genuine first release, so skipping
+// substance/evidence/cadence is right, or (b) tags DO exist but this clone can
+// not see them — a shallow clone hides them in history, and a `git clone
+// --no-tags` / `fetch-tags: false` clone of a long-tagged repo shows 0 local
+// tags too. (a) and (b) look IDENTICAL from local state (both give an empty
+// describe and 0 tags), so we can NOT auto-tell them apart. Fail CLOSED: skip
+// the checks ONLY when the operator positively declares a first release with
+// CW_FIRST_RELEASE=1 (explicit + logged, the same shape the cadence HOTFIX
+// override uses). Otherwise REJECT — a mis-fetched clone must never look like a
+// first release and silently pass. Found by a 2026-07-12 security check; the
+// shallow signal alone closed only half the hole (the `--no-tags` full clone
+// still slipped through).
+if (!PREV_TAG) {
+  const shallow = spawnSync("git", ["rev-parse", "--is-shallow-repository"], { cwd: REPO_ROOT, encoding: "utf8" });
+  const IS_SHALLOW = shallow.status === 0 ? shallow.stdout.trim() : "false";
+  if (IS_SHALLOW === "true") {
+    fail("cannot resolve the previous release tag: this is a shallow git clone (git rev-parse --is-shallow-repository = true), so an older tag may be hidden and substance/test-evidence/cadence cannot be trusted. Fetch full history (actions/checkout with fetch-depth: 0) before running this gate.");
+  } else if (process.env.CW_FIRST_RELEASE === "1") {
+    say("no previous tag; genuine first release declared (CW_FIRST_RELEASE=1) — substance/evidence/cadence will be skipped");
+  } else {
+    fail("cannot resolve the previous release tag on a full (non-shallow) clone. Either tags were not fetched (git clone --no-tags, or actions/checkout fetch-tags: false — fetch tags and re-run), or this is the genuine first release (set CW_FIRST_RELEASE=1 to declare that explicitly). Refusing to silently skip substance/test-evidence/cadence.");
+  }
+}
+const MARKER_DIR = path.join(REPO_ROOT, ".cw-release");
+fs.mkdirSync(MARKER_DIR, { recursive: true });
+
+function runNpm(args, extraEnv) {
+  // stdio ignored on purpose (the old script sent both streams to /dev/null):
+  // the gate's verdict is the exit code; a red step is re-run by hand for detail.
+  const r = spawnSync("npm", args, {
+    cwd: REPO_ROOT,
+    stdio: "ignore",
+    env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+  });
+  return !r.error && r.status === 0;
+}
+
+// --- 1. Build & tests (run, don't trust pasted output) -----------------
+say("[1/6] build");
+if (!runNpm(["run", "--prefix", "plugins/cool-workflow", "build"])) fail("build failed");
+
+say("[2/6] tests");
+if (!runNpm(["run", "test:gate", "--prefix", "plugins/cool-workflow"], { CW_TEST_CONCURRENCY: "1" })) fail("tests failed");
+
+if (PREV_TAG) {
+  const RANGE = `${PREV_TAG}..HEAD`;
+  const changedFiles = gitOut(["diff", "--name-only", RANGE]).split("\n").filter(Boolean);
+
+  // --- 2. Substance: changes must exist outside src/types/ and dist/ ---
+  // The spec (AGENTS.md / reviewer-agent.md Gate 1) is "at least one changed
+  // file outside src/types/ and dist/" — ANY such file (src, scripts, docs,
+  // workflows, tests). Count every changed path that is not under those two
+  // generated/declaration-only trees; declared-but-unread spec accretion is the
+  // reviewer agent's deeper judgment call, not this deterministic floor.
+  say("[3/6] substance (diff outside src/types/ and dist/)");
+  const SUBSTANCE = changedFiles.filter((f) => !/^plugins\/cool-workflow\/(src\/types\/|dist\/)/.test(f)).length;
+  if (!(SUBSTANCE > 0)) fail(`only types/dist changed since ${PREV_TAG} (spec accretion)`);
+
+  // --- 3. Test evidence: test files must have changed ------------------
+  say("[4/6] test evidence");
+  const TESTS_CHANGED = changedFiles.filter((f) => /\.(test|spec)\.|\/tests?\//.test(f)).length;
+  if (!(TESTS_CHANGED > 0)) fail(`zero test changes since ${PREV_TAG}`);
+
+  // --- 4. Cadence: >=4 cycles logged OR >=24h since previous tag, or a recorded HOTFIX ---
+  say("[5/6] cadence");
+  let CYCLES = 0;
+  const logDiff = fs.existsSync(path.join(REPO_ROOT, "ITERATION_LOG.md"))
+    ? gitOut(["diff", RANGE, "--", "ITERATION_LOG.md"]).split("\n")
+    : [];
+  CYCLES = logDiff.filter((line) => /^\+.*\|/.test(line)).length;
+  const PREV_TS = Number(gitOut(["log", "-1", "--format=%ct", PREV_TAG]));
+  const NOW_TS = Math.floor(Date.now() / 1000);
+  const HOURS = Math.floor((NOW_TS - PREV_TS) / 3600);
+  // Hotfix path: an urgent fix may ship inside the cadence window, but ONLY via an
+  // EXPLICIT, RECORDED declaration — a "HOTFIX:" line added to ITERATION_LOG.md in this
+  // release range, carrying a reason. It is committed (auditable in the tag's history)
+  // and echoed here, so the bypass is never silent and a reviewer sees the reason.
+  const hotfixLine = logDiff.find((line) => /^\+.*HOTFIX:/.test(line));
+  const HOTFIX = hotfixLine ? hotfixLine.replace(/^\+\s*/, "") : "";
+  if (CYCLES < 4 && HOURS < 24) {
+    if (HOTFIX) {
+      say(`  cadence bypassed by recorded HOTFIX (${HOURS}h, ${CYCLES} cycle-lines): ${HOTFIX}`);
+    } else {
+      fail(`cadence: only ${CYCLES} cycles logged and ${HOURS}h since ${PREV_TAG} (need >=4 cycles, >=24h, or a recorded 'HOTFIX:' line in ITERATION_LOG.md)`);
+    }
+  }
+} else {
+  say("[3-5/6] no previous tag; substance/evidence/cadence checks skipped");
+}
+
+// --- 5. Branch naming: forbid version-number branches -------------------
+say("[6/6] branch naming");
+// On a normal checkout `git rev-parse --abbrev-ref HEAD` is the branch name. On
+// a DETACHED HEAD it prints the literal string "HEAD" — and the tag-push CI
+// (release-gate.yml) ALWAYS checks out the tag, so HEAD is detached there. A
+// literal "HEAD" can never match the version-branch regex below, so this check
+// would silently pass exactly where it is meant to be the backstop. Handle the
+// detached case explicitly: gather the real candidate ref name(s) — the
+// CI-provided source branch (GITHUB_HEAD_REF for a PR, else GITHUB_REF_NAME),
+// plus every local/remote branch whose tip contains this commit — and judge
+// each one. A truly detached checkout with no resolvable branch (a bare
+// `git checkout <sha>`) has no branch to name, so there is nothing to forbid;
+// that is now an explicit, understood pass, not an accidental regex miss.
+const BRANCH = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
+let candidateBranches = [BRANCH];
+if (BRANCH === "HEAD") {
+  candidateBranches = [];
+  // The CI source branch: a PR run exposes it as GITHUB_HEAD_REF; a plain push
+  // exposes the pushed ref as GITHUB_REF_NAME (a tag on a tag push, which simply
+  // will not match the feat/ regex — harmless to include).
+  for (const envRef of [process.env.GITHUB_HEAD_REF || "", process.env.GITHUB_REF_NAME || ""]) {
+    if (envRef) candidateBranches.push(envRef);
+  }
+  // Every local branch whose tip contains this commit, plus every remote-tracking
+  // branch (with its "<remote>/" prefix stripped so the regex still anchors on
+  // "feat/"). --format avoids the "* " current-branch marker git branch prints.
+  const localC = gitOut(["branch", "--contains", "HEAD", "--format=%(refname:short)"]);
+  const remoteC = gitOut(["branch", "-r", "--contains", "HEAD", "--format=%(refname:short)"])
+    .split("\n")
+    .map((b) => b.replace(/^[^/]+\//, ""))
+    .join("\n");
+  for (const chunk of [localC, remoteC]) {
+    if (chunk) candidateBranches.push(...chunk.split("\n"));
+  }
+}
+for (const B of candidateBranches) {
+  if (!B || B === "HEAD") continue;
+  if (/^feat\/(batch-)?v?[0-9]+/.test(B)) {
+    fail(`branch '${B}' is version-number-driven; name the capability instead`);
+  }
+}
+
+// --- Verdict ------------------------------------------------------------
+if (FAIL !== 0) {
+  fs.rmSync(path.join(MARKER_DIR, `gate-${SHA}.ok`), { force: true });
+  say(`RELEASE GATE: REJECTED (${SHA})`);
+  process.exit(1);
+}
+
+fs.writeFileSync(path.join(MARKER_DIR, `gate-${SHA}.ok`), `${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}\n`);
+say(`RELEASE GATE: PASSED (${SHA}) — next step: release-reviewer agent must record APPROVED`);