cool-workflow 0.2.4 → 0.2.5

package/scripts/fake-date-for-reproduction.js

@@ -1,7 +1,7 @@
 "use strict";
 
 // fake-date-for-reproduction.js — a Node `--require` preload used ONLY by
-// verify-bump-reproduction.sh. It pins `new Date()` (no-args construction)
+// verify-bump-reproduction.js. It pins `new Date()` (no-args construction)
 // and `Date.now()` to a fixed instant, read from CW_FAKE_DATE (an ISO date or
 // YYYY-MM-DD string). `new Date(explicit args)` is left untouched.
 //

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.2.4");
+    assert.equal(appValidation.summary.version, "0.2.5");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.2.4 end-to-end golden path."
+        "Prove the deterministic v0.2.5 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.2.4");
+    assert.equal(state.workflow.app.version, "0.2.5");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.4/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.5/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/lang-policy-check.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+"use strict";
+// lang-policy-check.js — this project is written in JavaScript and
+// TypeScript only (AGENTS.md hard rule, 2026-07-13). Every git-tracked file
+// must be JS/TS, a recognized non-code file (docs, data, config, binary
+// asset), or one of the explicit, path-scoped exceptions below — a real
+// non-JS/TS file the project genuinely needs. Fail closed: an unrecognized
+// extension/basename is a hard stop, forcing a deliberate choice (write it
+// in JS/TS, or add a new exception here with a reason) instead of a silent
+// pass. Mechanism only; the allowlists ARE the policy, kept as plain data
+// in this one file — no separate config to drift from it.
+
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+
+const CODE_EXTENSIONS = new Set(["js", "mjs", "cjs", "ts", "tsx", "jsx"]);
+
+// Real, needed files this project cannot write in JS/TS -- the exact same
+// set already carved out of GitHub's Languages stats in .gitattributes, for
+// the same reasons (see that file's comments). Scoped to an EXACT path,
+// never a whole directory, so a new file dropped in the same folder does
+// NOT silently inherit the exception.
+const EXCEPT_PATHS = new Set([
+  "Formula/cool-workflow.rb", // Homebrew formula must be Ruby
+  "plugins/cool-workflow/ui/workbench/index.html", // served from disk by design
+  "plugins/cool-workflow/ui/workbench/app.css" // served from disk by design
+]);
+
+// Not "code" at all -- docs, data, config, and binary assets. Fine
+// anywhere in the tree; this policy is only about what the project is
+// WRITTEN in, not about every file it ships or tracks.
+const NON_CODE_EXTENSIONS = new Set([
+  "md", "mdc", "txt", "json", "jsonl", "yml", "yaml", "toml",
+  "verdict", "sig", "pub", "tape",
+  "svg", "png", "jpg", "jpeg", "gif", "webp", "ico", "pdf",
+  "woff", "woff2", "gz", "tgz", "zip", "lock"
+]);
+// Extensionless / dotfile basenames that are also not code.
+const NON_CODE_BASENAMES = new Set([
+  "LICENSE", ".gitignore", ".gitattributes", ".editorconfig", ".windsurfrules", ".npmrc", ".nvmrc"
+]);
+
+// `EXCEPT_PATHS` are written repo-root-relative, so tracked files must be
+// resolved the same way regardless of the invocation cwd (this runs both as
+// `npm run lang:check` from plugins/cool-workflow/ AND from release-check.js
+// at various cwds) -- resolve the real top-level first, never trust the
+// invocation cwd to already BE it.
+function trackedFiles() {
+  const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+  return execFileSync("git", ["-C", repoRoot, "ls-files"], { encoding: "utf8" })
+    .split("\n")
+    .filter(Boolean);
+}
+
+function classify(file) {
+  if (EXCEPT_PATHS.has(file)) return { ok: true };
+  const base = path.basename(file);
+  if (NON_CODE_BASENAMES.has(base)) return { ok: true };
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return { ok: false, ext: null };
+  const ext = base.slice(dot + 1).toLowerCase();
+  if (CODE_EXTENSIONS.has(ext) || NON_CODE_EXTENSIONS.has(ext)) return { ok: true };
+  return { ok: false, ext };
+}
+
+const files = trackedFiles();
+const violations = [];
+for (const file of files) {
+  const result = classify(file);
+  if (!result.ok) violations.push({ file, ext: result.ext });
+}
+
+if (violations.length > 0) {
+  process.stderr.write("lang-policy-check: this project is JavaScript/TypeScript only. Unrecognized file(s):\n");
+  for (const v of violations) {
+    process.stderr.write(`  - ${v.file}${v.ext ? ` (.${v.ext})` : " (no extension)"}\n`);
+  }
+  process.stderr.write("Write it in JavaScript/TypeScript, or add a scoped, reasoned exception to scripts/lang-policy-check.js.\n");
+  process.exit(1);
+}
+
+process.stdout.write(`lang-policy-check: ${files.length} tracked files, all JS/TS or an allowed non-code/exception file.\n`);

package/scripts/purity-gate.js

@@ -112,8 +112,12 @@ function stripComments(text) {
 
 // Every `from "spec"` (import or export-from, type or value — a type-only
 // import still names a module, so it counts the same way a real dependency
-// scan would) plus every `require("spec")`. Non-greedy across `from` finds
-// each import's own clause without needing a real parser.
+// scan would) plus every `require("spec")` and every dynamic `import("spec")`.
+// Non-greedy across `from` finds each import's own clause without needing a
+// real parser. The dynamic-import form matters because a core/ file could
+// otherwise smuggle in an impure or cross-layer module through
+// `await import("node:fs")` — the one import shape the static and require
+// scans did not see, so the ratchet was blind to it.
 function extractSpecifiers(codeText) {
   const specs = [];
   const fromRe = /(?:^|\n)\s*(?:import|export)\s[\s\S]*?from\s+["']([^"']+)["']/g;
@@ -121,6 +125,8 @@ function extractSpecifiers(codeText) {
   while ((m = fromRe.exec(codeText))) specs.push(m[1]);
   const requireRe = /require\(\s*["']([^"']+)["']\s*\)/g;
   while ((m = requireRe.exec(codeText))) specs.push(m[1]);
+  const dynamicImportRe = /import\(\s*["']([^"']+)["']\s*\)/g;
+  while ((m = dynamicImportRe.exec(codeText))) specs.push(m[1]);
   return specs;
 }
 
@@ -236,4 +242,11 @@ function main() {
   process.stdout.write("purity gate: src/ matches the committed baseline (no new core/shell layer breaks, no clock/env drift).\n");
 }
 
-main();
+// Run the gate only when invoked directly (node scripts/purity-gate.js). When
+// required by a test, expose the internal helpers so the specifier scan can be
+// unit-checked without shelling out or writing into the real src/ tree.
+if (require.main === module) {
+  main();
+}
+
+module.exports = { stripComments, extractSpecifiers, layerOf, scan };

package/scripts/release-check.js

@@ -60,12 +60,13 @@ const checks = [
   // from that fresh build — strictly stronger than a bare `npm run build`.
   { name: "dist freshness", command: ["npm", "run", "dist:check"] },
   { name: "core/shell purity", command: ["npm", "run", "purity:check"] },
+  { name: "language policy (JS/TS only)", command: ["npm", "run", "lang:check"] },
   { name: "type check", command: ["npm", "run", "check"] },
   { name: "onramp contract", command: ["npm", "run", "onramp:check"] },
   { name: "run-state schema consistency", command: ["node", "scripts/validate-run-state-schema.js"] },
   // Every test path uses --concurrency auto by default (parallel, race-free:
   // each smoke runs in a private cwd + state roots). The release tag-gate
-  // (release-gate.sh) forces CW_TEST_CONCURRENCY=1 to stay sequential as the
+  // (release-gate.js) forces CW_TEST_CONCURRENCY=1 to stay sequential as the
   // deterministic backstop.
   { name: "tests", command: ["npm", "run", "test:ci"] },
   // Pure core/ unit tests (test/*.test.js) — a separate suite from the smoke

package/scripts/release-flow.js

@@ -43,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
@@ -51,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.
@@ -107,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();
 
@@ -129,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"
@@ -173,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) {
@@ -222,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);
@@ -238,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;
@@ -300,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
@@ -308,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,
@@ -369,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`);
@@ -388,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
@@ -451,10 +519,14 @@ 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
@@ -647,7 +719,14 @@ function preflightCut() {
   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}`]);
-    if (remoteTag.code === 0 && remoteTag.out) {
+    // 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
@@ -669,6 +748,17 @@ function preflightCut() {
 // ---- 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");
+  // 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");
@@ -683,11 +773,19 @@ 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"}`]);

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`);