cool-workflow 0.2.2 → 0.2.3

package/docs/workflow-app-framework.7.md

@@ -16,13 +16,13 @@ const {
 ```
 
 ```bash
-node scripts/cw.js app list
-node scripts/cw.js app show workflow-app-framework-demo
-node scripts/cw.js app validate apps/workflow-app-framework-demo/app.json
-node scripts/cw.js app show architecture-review
+cw app list
+cw app show workflow-app-framework-demo
+cw app validate apps/workflow-app-framework-demo/app.json
+cw app show architecture-review
 npm run canonical-apps
-node scripts/cw.js app init my-app --title "My App"
-node scripts/cw.js plan my-app --question "What should happen?"
+cw app init my-app --title "My App"
+cw plan my-app --question "What should happen?"
 ```
 
 ## Description
@@ -170,7 +170,7 @@ App loading fails closed. CW checks:
 - sandbox profile references on the app, workflow, and tasks
 - compatibility limits against the current CW runtime
 
-`cw.js app validate` prints a structured result. Apps that are not valid return nonzero:
+`cw app validate` prints a structured result. Apps that are not valid return nonzero:
 
 ```json
 {
@@ -190,14 +190,14 @@ CW does not quietly change broken apps into workflows that can run.
 ## CLI
 
 ```bash
-node scripts/cw.js app list
-node scripts/cw.js app show <app-id>
-node scripts/cw.js app validate <path-or-app-id>
-node scripts/cw.js app init <app-id> --title "Title"
-node scripts/cw.js app package <app-id> --output app.cwapp.json
+cw app list
+cw app show <app-id>
+cw app validate <path-or-app-id>
+cw app init <app-id> --title "Title"
+cw app package <app-id> --output app.cwapp.json
 ```
 
-`cw.js list`, `cw.js init`, and `cw.js plan` still work the same way. `list` shows
+`cw list`, `cw init`, and `cw plan` still work the same way. `list` shows
 legacy workflow files and first-class app directories. `plan` takes either
 kind by id.
 

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.2.2",
+    "version": "0.2.3",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -75,7 +75,7 @@
     "validate:schema": "node scripts/validate-run-state-schema.js"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.1.1",
     "typescript": "^5.9.0"
   },
   "keywords": [

package/scripts/agents/claude-p-agent.js

@@ -50,7 +50,7 @@ const traceEnabled = streamEnabled && Boolean(process.stderr.isTTY);
 if (!streamEnabled) {
   // Legacy default: --output-format json and verbatim stdout forwarding. This is
   // the public wrapper contract existing users already scripted against.
-  const child = spawnSync("claude", ["-p", prompt, "--output-format", "json", "--allowedTools", "Read,Grep,Glob,Bash"], {
+  const child = spawnSync("claude", ["-p", prompt, "--output-format", "json", "--allowedTools", "Read,Grep,Glob"], {
     encoding: "utf8",
     maxBuffer: 32 * 1024 * 1024,
     shell: false
@@ -100,7 +100,7 @@ const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
 // non-zero exit.
 const child = spawn(
   "claude",
-  ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob,Bash"],
+  ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob"],
   { stdio: ["ignore", "pipe", "pipe"] }
 );
 

package/scripts/block-unapproved-tag.sh

@@ -4,6 +4,9 @@
 # require BOTH markers for the current HEAD sha:
 #   .cw-release/gate-<sha>.ok        (written by release-gate.sh)
 #   .cw-release/review-<sha>.verdict (written by the release-reviewer agent, must contain APPROVED)
+# If .cw-release/verdict-signing.pub is committed (scripts/verdict-keygen.js),
+# also requires a valid ed25519 signature on the verdict (its .sig sidecar) —
+# opt-in, backward compatible with repos that haven't set up signing yet.
 # Exit 2 blocks the tool call; stderr is fed back to the agent.
 set -uo pipefail
 
@@ -16,8 +19,12 @@ INPUT="$(cat)"
 CMD="$(printf '%s' "$INPUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(s)?.tool_input?.command||""))}catch{process.stdout.write("")}})' 2>/dev/null)"
 [[ -z "$CMD" ]] && exit 0
 
-# Only care about tag creation / tag push
-if ! printf '%s' "$CMD" | grep -qE 'git\s+tag\s+(-a\s+)?v|git\s+push\b.*(--tags|refs/tags)'; then
+# Only care about tag creation / tag push. Widened from the original pattern,
+# which missed the single most natural bypass form: `git push origin v0.2.3`
+# (a bare tag-shaped ref, no --tags flag and no refs/tags/ prefix) matched
+# neither side of the old alternation. Also now tolerates a global flag before
+# the tag subcommand (`git -C dir tag ...`) and the `--annotate` long form.
+if ! printf '%s' "$CMD" | grep -qE 'git(\s+-[A-Za-z]+\s+\S+)*\s+tag\s+(-a\s+|--annotate\s+)?v[0-9]|git\s+push\b.*(--tags|refs/tags|[[:space:]]v[0-9])'; then
   exit 0
 fi
 
@@ -36,4 +43,18 @@ if [[ ! -f "$VERDICT" ]] || ! grep -q '^APPROVED' "$VERDICT"; then
   exit 2
 fi
 
+# Once .cw-release/verdict-signing.pub is committed (see scripts/verdict-keygen.js),
+# also require a valid ed25519 signature on the verdict — closing the gap this grep
+# alone can't: a plain APPROVED text match can't tell a real reviewer verdict from
+# one typed by hand. Absent that public key, this block is a no-op (unchanged,
+# grep-only behavior).
+PUBKEY="$REPO_ROOT/.cw-release/verdict-signing.pub"
+if [[ -f "$PUBKEY" ]]; then
+  SIG="$VERDICT.sig"
+  if [[ ! -f "$SIG" ]] || ! node "$REPO_ROOT/plugins/cool-workflow/scripts/verify-verdict-signature.js" "$VERDICT" "$SIG" "$PUBKEY" >/dev/null 2>&1; then
+    echo "BLOCKED: verdict for HEAD $SHA has no valid signature, but verdict-signing.pub is committed so one is required. Do not hand-write or hand-sign a verdict — obtain a real reviewer approval via release-flow.js with CW_RELEASE_VERDICT_PRIVKEY set." >&2
+    exit 2
+  fi
+fi
+
 exit 0

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.2.2",
+      "Cool Workflow v0.2.3",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.2.2");
+    assert.equal(summary.version, "0.2.3");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.2.2");
+    assert.equal(shown.app.version, "0.2.3");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.2.2");
+    assert.equal(state.workflow.app.version, "0.2.3");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/children/batch-delegate-child.js

@@ -8,7 +8,8 @@
 //
 // Reads jobs JSON on stdin, spawns ALL concurrently (shell:false, inherited env —
 // the agent's own credentials resolve; CW never reads them), per-job SIGTERM at
-// timeoutMs + SIGKILL at +5s, caps each captured stdout at 32MB. Streams ONE
+// timeoutMs + SIGKILL at +5s, caps each captured stdout at 32MB RAW and each
+// written NDJSON line at 33MB SERIALIZED (see LINE_CAP below). Streams ONE
 // NDJSON line per job — `{i, spawnError?, exitCode, stdout}\n` — the INSTANT
 // that job settles (not once at the end): the parent's spawnSync call has its
 // own combined-output cap, so writing incrementally means a job whose line
@@ -21,6 +22,34 @@
 //
 // THE RED LINE: this child only `spawn`s the operator-resolved agent binary with
 // shell:false. It imports NO model SDK and reads NO credentials.
+//
+// A direct kill of THIS process (e.g. the parent's spawnSync `timeout` option,
+// or a signal that reaches this child but not the grandchildren it spawned)
+// used to orphan every still-running job -- no SIGINT/SIGTERM handler existed
+// here, so the kernel default (instant termination) left them running with no
+// one left to reap them. Now the first stop signal forwards SIGTERM to every
+// still-tracked child (same escalation shape the per-job timeout below
+// already uses) and lets each one's own `close` handler settle it normally;
+// a second signal escalates straight to SIGKILL and exits immediately.
+const children = new Set();
+function killAllChildren(signal) {
+  for (const child of children) {
+    try { child.kill(signal); } catch {}
+  }
+}
+let stopSignalReceived = false;
+function onStopSignal(signal) {
+  if (stopSignalReceived) {
+    killAllChildren("SIGKILL");
+    process.exit(signal === "SIGINT" ? 130 : 143);
+    return;
+  }
+  stopSignalReceived = true;
+  killAllChildren("SIGTERM");
+  setTimeout(() => killAllChildren("SIGKILL"), 5000).unref();
+}
+process.on("SIGINT", () => onStopSignal("SIGINT"));
+process.on("SIGTERM", () => onStopSignal("SIGTERM"));
 
 const { spawn } = require("node:child_process");
 let raw = "";
@@ -37,6 +66,16 @@ process.stdin.on("end", () => {
   }
   if (!jobs.length) { process.stdout.write("[]"); return; }
   const CAP = 32 * 1024 * 1024;
+  // The parent (runAgentBatchOutcomes) grants maxBuffer = 34MB PER JOB for
+  // the COMBINED NDJSON stream it captures from this child. CAP above bounds
+  // each job's RAW stdout bytes, but the line written by settle() is the
+  // ESCAPED serialization — JSON escaping grows bytes (quotes and
+  // backslashes 2x, control chars up to 6x as \uXXXX), so a raw-capped
+  // stdout could still serialize into a line far past the parent's per-job
+  // budget, push the combined stream over maxBuffer, and ENOBUFS the WHOLE
+  // batch. LINE_CAP bounds the SERIALIZED line itself, held under the
+  // parent's 34MB per-job grant with a small safety margin.
+  const LINE_CAP = 33 * 1024 * 1024;
   jobs.forEach((job, i) => {
     let stdout = "";
     let stdoutBytes = 0;
@@ -45,7 +84,15 @@ process.stdin.on("end", () => {
     const settle = (o) => {
       if (settled) return;
       settled = true;
-      process.stdout.write(JSON.stringify({ i, ...o }) + "\n");
+      let line = JSON.stringify({ i, ...o }) + "\n";
+      const lineBytes = Buffer.byteLength(line);
+      if (lineBytes > LINE_CAP) {
+        // Same fail-closed shape as the raw-cap path in the close handler
+        // below: capped output is never evidence, so drop it entirely and
+        // name the cap — never ship a line the parent's buffer cannot hold.
+        line = JSON.stringify({ i, spawnError: `serialized stdout line exceeded ${LINE_CAP} byte cap (${lineBytes} bytes)`, exitCode: null, stdout: "" }) + "\n";
+      }
+      process.stdout.write(line);
     };
     let child;
     try {
@@ -54,6 +101,7 @@ process.stdin.on("end", () => {
       settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout: "" });
       return;
     }
+    children.add(child);
     const term = setTimeout(() => { try { child.kill("SIGTERM"); } catch {} }, job.timeoutMs);
     const kill = setTimeout(() => { try { child.kill("SIGKILL"); } catch {} }, job.timeoutMs + 5000);
     child.stdout.on("data", (d) => {
@@ -71,10 +119,12 @@ process.stdin.on("end", () => {
     child.stderr.on("data", () => {});
     child.on("error", (error) => {
       clearTimeout(term); clearTimeout(kill);
+      children.delete(child);
       settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout });
     });
     child.on("close", (code) => {
       clearTimeout(term); clearTimeout(kill);
+      children.delete(child);
       if (stdoutTruncated) {
         settle({ spawnError: `stdout exceeded ${CAP} byte cap (${stdoutBytes} bytes)`, exitCode: null, stdout: "" });
         return;

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/shell/orchestrator.js");
 
-const TARGET_VERSION = "0.2.2";
+const TARGET_VERSION = "0.2.3";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

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

@@ -0,0 +1,44 @@
+"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)
+// 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.
+//
+// WHY a runtime-level override, not an application-level env var: the
+// scratch worktree checks out the APPROVED PARENT commit and runs ITS OWN
+// copy of bump-version.js/sync-project-index.js — which, for every commit
+// that predates this mechanism (i.e. every real release ever cut so far),
+// has no idea any such override exists. An app-level env var a script has to
+// explicitly read is a no-op against code that doesn't know to read it — it
+// can only ever help releases cut AFTER the mechanism itself lands, making
+// "reproduce a past release" true only by calendar coincidence (confirmed:
+// re-running v0.2.0's real approved-parent/tagged pair on a day other than
+// its actual cut day fails with a date-only diff in project-index.md).
+// Intercepting the Date GLOBAL, before any application code runs, works
+// identically regardless of which script version executes — old or new.
+//
+// Usage: NODE_OPTIONS="--require /path/to/this/file.js" CW_FAKE_DATE=2026-07-05 <command>
+
+const pinned = process.env.CW_FAKE_DATE;
+if (pinned) {
+  const fixedMs = new Date(pinned).getTime();
+  if (Number.isNaN(fixedMs)) {
+    process.stderr.write(`fake-date-for-reproduction: CW_FAKE_DATE is not a valid date: ${pinned}\n`);
+    process.exit(1);
+  }
+  const RealDate = Date;
+  class FakeDate extends RealDate {
+    constructor(...args) {
+      if (args.length === 0) {
+        super(fixedMs);
+      } else {
+        super(...args);
+      }
+    }
+    static now() {
+      return fixedMs;
+    }
+  }
+  global.Date = FakeDate;
+}

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.2");
+    assert.equal(appValidation.summary.version, "0.2.3");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.2.2 end-to-end golden path."
+        "Prove the deterministic v0.2.3 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.2");
+    assert.equal(state.workflow.app.version, "0.2.3");
     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\.2/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.3/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/purity-baseline.json

@@ -37,6 +37,9 @@
     "core/capability-table.ts": [
       "../wiring/capability-table"
     ],
+    "wiring/capability-table/basics.ts": [
+      "../../cli/io"
+    ],
     "wiring/capability-table/exec-backend.ts": [
       "../../cli/io"
     ],

package/scripts/release-flow.js

@@ -31,6 +31,17 @@
 //   Both release-flow.js --cut and CI's release-gate.yml verify this exact path and
 //   format. The file MUST be committed to the tag's history.
 //
+// VERDICT SIGNING (optional, opt-in — see scripts/verdict-keygen.js):
+//   Set CW_RELEASE_VERDICT_PRIVKEY (a path or inline PEM) and this script signs
+//   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
+//   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
+//   (grep-only) — this is inert by default, never a silent behavior change.
+//
 // 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
@@ -48,6 +59,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const https = require("node:https");
 const http = require("node:http");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 
 const scriptsDir = __dirname;
@@ -364,6 +376,46 @@ function verifyVerdict(resultPath) {
   return cap;
 }
 
+// ---- verdict signing (optional, opt-in — see the header comment) -----------
+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}`);
+}
+
+/** Called only after verifyVerdict() has confirmed resultPath's bytes are a
+ *  genuine "APPROVED <HEAD>" verdict. A no-op unless CW_RELEASE_VERDICT_PRIVKEY
+ *  is set. When it IS set, a signing failure fails closed (die()) rather than
+ *  silently emitting an unsigned verdict — an operator who deliberately
+ *  configured a signing key should never end up with the same on-disk state
+ *  as one who didn't. */
+function signVerdictIfConfigured(resultPath) {
+  const raw = process.env.CW_RELEASE_VERDICT_PRIVKEY;
+  if (!raw || !raw.trim()) return;
+  const pem = resolveVerdictPrivateKey(raw);
+  const sigPath = `${resultPath}.sig`;
+  try {
+    const key = crypto.createPrivateKey(pem);
+    // crypto.sign(null, ...) does NOT throw for an RSA or EC key — it silently
+    // signs with that algorithm's own default digest, producing a
+    // syntactically valid signature that can never verify against the
+    // committed ed25519 public key. Catching that here, at signing time,
+    // means a misconfigured key dies closed locally instead of only being
+    // caught later by CI (or not at all, if the repo hasn't committed
+    // verdict-signing.pub yet).
+    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 message = fs.readFileSync(resultPath);
+    const signature = crypto.sign(null, message, key).toString("base64");
+    fs.writeFileSync(sigPath, `${signature}\n`);
+  } catch (error) {
+    die(`failed to sign the verdict with CW_RELEASE_VERDICT_PRIVKEY: ${error.message}`);
+  }
+  say(`verdict signed → ${path.relative(repoRoot, sigPath)}`);
+}
+
 // ---- GitHub Release (optional, presentation/distribution) ------------------
 // NOT a correctness gate: the load-bearing artifacts (the tag + the
 // provenance-attested npm publish) already exist when this runs. So `gh` is NOT
@@ -522,9 +574,12 @@ function cut(resultPath, capability) {
   // operator's local home path) must never ride into the immutable tag commit
   // (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 is the single new path the cut is allowed to add.
+  // 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)]);
+  const sigPath = `${resultPath}.sig`;
+  if (fs.existsSync(sigPath)) git(["add", "--", path.relative(repoRoot, sigPath)]);
   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"}`]);
@@ -569,6 +624,7 @@ function main() {
   fs.writeFileSync(inputPath, buildReviewerInput(resultPath));
   delegateReview(resultPath, inputPath);
   const capability = verifyVerdict(resultPath);
+  signVerdictIfConfigured(resultPath);
 
   if (MODE_CUT) cut(resultPath, capability);
 

package/scripts/verdict-keygen.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+
+// verdict-keygen.js — generate the ed25519 keypair for release-verdict
+// signing. Same pattern as scripts/agents/cw-attest-keygen.js (that keypair
+// signs AGENT USAGE telemetry; this one signs the RELEASE VERDICT — kept as
+// two separate trust domains with two separate keypairs, never shared).
+//
+// The PRIVATE key stays with whoever runs `release-flow.js --cut`/`--check`
+// (CW_RELEASE_VERDICT_PRIVKEY) and NEVER gets committed. The PUBLIC key is
+// committed to the repo at .cw-release/verdict-signing.pub so CI's
+// release-gate.yml, npm-publish.yml, and the local block-unapproved-tag.sh
+// hook can all verify a committed verdict without holding any secret.
+//
+// Verification is opt-in and backward compatible: as long as
+// .cw-release/verdict-signing.pub is absent, every verifier falls back to the
+// original `grep -q '^APPROVED'` check. Once the public key is committed,
+// every verifier starts requiring a valid signature too.
+//
+// Usage:
+//   node verdict-keygen.js [--out-dir DIR]   # writes verdict-signing.key + .pub
+//   node verdict-keygen.js --print           # print both PEMs to stdout, write nothing
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : fallback;
+}
+
+// .cw-release/ lives at the REPO ROOT, not necessarily at process.cwd() —
+// this script is documented to be run from plugins/cool-workflow (RELEASE.md's
+// checklist cwd), where a bare ".cw-release/verdict-signing.pub" would
+// silently resolve under plugins/cool-workflow/.cw-release/ instead, a path no
+// verifier ever looks at. Resolve the real root so the printed command is
+// correct regardless of where this script was invoked from.
+function repoRootPubkeyPath() {
+  const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const root = r.status === 0 ? r.stdout.trim() : undefined;
+  return root ? path.join(root, ".cw-release", "verdict-signing.pub") : ".cw-release/verdict-signing.pub";
+}
+
+const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+const privatePem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+
+if (process.argv.includes("--print")) {
+  process.stdout.write(`# PRIVATE (release operator — CW_RELEASE_VERDICT_PRIVKEY, never commit)\n${privatePem}\n# PUBLIC (commit as .cw-release/verdict-signing.pub)\n${publicPem}\n`);
+  process.exit(0);
+}
+
+const outDir = path.resolve(arg("--out-dir", process.cwd()));
+const keyPath = path.join(outDir, "verdict-signing.key");
+const pubPath = path.join(outDir, "verdict-signing.pub");
+fs.mkdirSync(outDir, { recursive: true });
+// Private key: owner-only perms (0600). NEVER commit this file.
+fs.writeFileSync(keyPath, privatePem, { mode: 0o600 });
+fs.writeFileSync(pubPath, publicPem);
+
+process.stdout.write(
+  [
+    `Wrote ed25519 keypair:`,
+    `  private (operator, keep off the repo): ${keyPath}   (chmod 0600)`,
+    `  public  (commit to the repo):          ${pubPath}`,
+    ``,
+    `Release operator (local machine, never committed):`,
+    `  export CW_RELEASE_VERDICT_PRIVKEY="${keyPath}"`,
+    ``,
+    `Repo (commit this so CI/hook can verify — path is repo-root-anchored,`,
+    `correct no matter which directory you run this from):`,
+    `  cp "${pubPath}" "${repoRootPubkeyPath()}"`,
+    `  git -C "$(git rev-parse --show-toplevel)" add .cw-release/verdict-signing.pub`,
+    `  git -C "$(git rev-parse --show-toplevel)" commit -m "chore: add release-verdict signing public key"`,
+    ``,
+    `Once .cw-release/verdict-signing.pub is committed, release-gate.yml, npm-publish.yml,`,
+    `and block-unapproved-tag.sh all start REQUIRING a valid signature on top of the`,
+    `existing APPROVED text check — an unsigned or hand-written verdict fails closed.`,
+    ``
+  ].join("\n")
+);