cool-workflow 0.2.1 → 0.2.3

package/scripts/purity-gate.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+"use strict";
+
+// purity-gate — fail closed if src/ crosses a layer boundary the rebuild
+// docs claim is enforced, or if src/core/** reads an impure primitive
+// (node:fs/child_process/net/http, process.env, process.cwd(), Date.now(),
+// new Date(), Math.random()), beyond a committed, itemized baseline.
+//
+// Why this exists: docs/rebuild/PLAN.md and AGENTS.md both describe core/
+// as pure (no IO) and shell/ as the only impure layer, and say this is
+// "enforced by a lint rule". No such lint exists anywhere in scripts/ or
+// package.json — only `tsc --noEmit`, which does not check import
+// direction. The one place the rule is already broken is the hub itself:
+// core/capability-table.ts imports ~30 things from ../shell.
+//
+// This is a RATCHET, not a clean-slate rule (matching dist-drift-check.js's
+// and version-sync-check.js's style: node + git only, no new dependency).
+// scripts/purity-baseline.json lists every violation that exists TODAY.
+// The gate fails on:
+//   - a violation NOT in the baseline (a NEW break), and
+//   - a baseline entry that no longer matches reality (STALE — either the
+//     violation was fixed, in which case delete the entry, or the count
+//     changed, in which case update it consciously).
+// Fail-closed both directions, same as dist-drift-check.js's added/changed/
+// removed three-way diff.
+//
+// Layers (by top-level directory under src/):
+//   core/**   -> may only import core/** (+ node:path, node:crypto)
+//   shell/**  -> may import core/** or shell/**
+//   wiring/** -> may import core/**, shell/**, or wiring/** (not yet used;
+//               reserved for the capability-table split)
+//   cli/**    -> may import core/**, shell/**, or cli/** (never mcp/**)
+//   mcp/**    -> may import core/**, shell/**, or mcp/** (never cli/**)
+//
+// Approach: a plain-text specifier scan (import/export-from/require), not a
+// real TS parser — this codebase uses only those three forms, verified
+// against every current violation this baseline lists.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageDir = path.resolve(__dirname, "..");
+const srcDir = path.join(packageDir, "src");
+const baselinePath = path.join(__dirname, "purity-baseline.json");
+
+const CORE_ALLOWED_BUILTINS = new Set(["node:path", "node:crypto"]);
+const IMPURE_PATTERNS = ["process.env", "process.cwd()", "Date.now()", "new Date()", "Math.random()"];
+
+const ALLOWED_TARGET_LAYERS = {
+  core: new Set(["core"]),
+  shell: new Set(["core", "shell"]),
+  wiring: new Set(["core", "shell", "wiring"]),
+  cli: new Set(["core", "shell", "cli"]),
+  mcp: new Set(["core", "shell", "mcp"]),
+  other: new Set(["core", "shell", "wiring", "cli", "mcp", "other"]),
+};
+
+function layerOf(relPath) {
+  if (relPath.startsWith("core/")) return "core";
+  if (relPath.startsWith("shell/")) return "shell";
+  if (relPath.startsWith("wiring/")) return "wiring";
+  if (relPath.startsWith("cli/") || relPath === "cli") return "cli";
+  if (relPath.startsWith("mcp/") || relPath === "mcp-server") return "mcp";
+  return "other";
+}
+
+function listTsFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listTsFiles(full));
+    else if (entry.name.endsWith(".ts")) out.push(full);
+  }
+  return out;
+}
+
+// This codebase's file-header comments routinely quote the EXACT patterns
+// this gate looks for, in prose explaining why a file is pure (e.g. "never
+// a top-level `require(\"node:fs\")`", "no fs, no process.env, no clock").
+// A naive text scan reads those quotes as violations. Strip `//` and
+// `/* */` comments before scanning (string/template literal contents are
+// left untouched, so a real `from "..."` clause is never damaged); newlines
+// are preserved so extractSpecifiers' `(?:^|\n)` anchor still lines up.
+function stripComments(text) {
+  let out = "";
+  let mode = "code"; // "code" | "line" | "block" | quote character
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const c2 = text[i + 1];
+    if (mode === "line") {
+      if (c === "\n") { mode = "code"; out += c; }
+      continue;
+    }
+    if (mode === "block") {
+      if (c === "*" && c2 === "/") { mode = "code"; i++; continue; }
+      if (c === "\n") out += c;
+      continue;
+    }
+    if (mode === '"' || mode === "'" || mode === "`") {
+      out += c;
+      if (c === "\\") { out += c2 ?? ""; i++; continue; }
+      if (c === mode) mode = "code";
+      continue;
+    }
+    if (c === "/" && c2 === "/") { mode = "line"; i++; continue; }
+    if (c === "/" && c2 === "*") { mode = "block"; i++; continue; }
+    if (c === '"' || c === "'" || c === "`") { mode = c; out += c; continue; }
+    out += c;
+  }
+  return out;
+}
+
+// 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.
+function extractSpecifiers(codeText) {
+  const specs = [];
+  const fromRe = /(?:^|\n)\s*(?:import|export)\s[\s\S]*?from\s+["']([^"']+)["']/g;
+  let m;
+  while ((m = fromRe.exec(codeText))) specs.push(m[1]);
+  const requireRe = /require\(\s*["']([^"']+)["']\s*\)/g;
+  while ((m = requireRe.exec(codeText))) specs.push(m[1]);
+  return specs;
+}
+
+function countOccurrences(text, needle) {
+  let count = 0;
+  let index = 0;
+  while ((index = text.indexOf(needle, index)) !== -1) {
+    count += 1;
+    index += needle.length;
+  }
+  return count;
+}
+
+function relSrcPath(absPath) {
+  return path.relative(srcDir, absPath).split(path.sep).join("/");
+}
+
+function scan() {
+  const layerViolations = {}; // relFile -> string[] (specs that cross a disallowed layer)
+  const builtinViolations = {}; // relFile -> string[] (banned node builtins imported from core)
+  const clockEnvCounts = {}; // relFile -> { pattern: count } (core only, count > 0)
+
+  for (const absFile of listTsFiles(srcDir)) {
+    const relFile = relSrcPath(absFile);
+    const fileLayer = layerOf(relFile.replace(/\.ts$/, ""));
+    const text = stripComments(fs.readFileSync(absFile, "utf8"));
+
+    for (const spec of extractSpecifiers(text)) {
+      if (spec.startsWith(".")) {
+        const targetAbs = path.resolve(path.dirname(absFile), spec);
+        const targetRel = relSrcPath(targetAbs);
+        const targetLayer = layerOf(targetRel);
+        if (!ALLOWED_TARGET_LAYERS[fileLayer].has(targetLayer)) {
+          (layerViolations[relFile] = layerViolations[relFile] || []).push(spec);
+        }
+      } else if (spec.startsWith("node:")) {
+        if (fileLayer === "core" && !CORE_ALLOWED_BUILTINS.has(spec)) {
+          (builtinViolations[relFile] = builtinViolations[relFile] || []).push(spec);
+        }
+      }
+      // Bare package specifiers (no "." or "node:" prefix): this package
+      // has zero runtime dependencies, so there are none to check.
+    }
+
+    if (fileLayer === "core") {
+      const counts = {};
+      for (const pattern of IMPURE_PATTERNS) {
+        const n = countOccurrences(text, pattern);
+        if (n > 0) counts[pattern] = n;
+      }
+      if (Object.keys(counts).length > 0) clockEnvCounts[relFile] = counts;
+    }
+  }
+
+  for (const bucket of [layerViolations, builtinViolations]) {
+    for (const file of Object.keys(bucket)) bucket[file] = [...new Set(bucket[file])].sort();
+  }
+  return { layerViolations, builtinViolations, clockEnvCounts };
+}
+
+function sortedKeys(obj) {
+  return Object.keys(obj).sort();
+}
+
+function diffListBuckets(actual, baseline, label, problems) {
+  const files = new Set([...sortedKeys(actual), ...sortedKeys(baseline)]);
+  for (const file of [...files].sort()) {
+    const actualList = actual[file] || [];
+    const baseList = baseline[file] || [];
+    const actualSet = new Set(actualList);
+    const baseSet = new Set(baseList);
+    const added = actualList.filter((s) => !baseSet.has(s));
+    const removed = baseList.filter((s) => !actualSet.has(s));
+    for (const spec of added) problems.push(`NEW ${label}: ${file} imports ${spec} (not in purity-baseline.json)`);
+    for (const spec of removed) problems.push(`STALE ${label} baseline entry: ${file} no longer imports ${spec} — delete it from purity-baseline.json`);
+  }
+}
+
+function diffCountBuckets(actual, baseline, problems) {
+  const files = new Set([...sortedKeys(actual), ...sortedKeys(baseline)]);
+  for (const file of [...files].sort()) {
+    const actualCounts = actual[file] || {};
+    const baseCounts = baseline[file] || {};
+    const patterns = new Set([...Object.keys(actualCounts), ...Object.keys(baseCounts)]);
+    for (const pattern of [...patterns].sort()) {
+      const a = actualCounts[pattern] || 0;
+      const b = baseCounts[pattern] || 0;
+      if (a !== b) {
+        problems.push(`clock/env count drift: ${file} has ${a} occurrence(s) of "${pattern}", purity-baseline.json expects ${b} — update the baseline consciously (this catches new AND removed occurrences)`);
+      }
+    }
+  }
+}
+
+function main() {
+  if (!fs.existsSync(baselinePath)) {
+    process.stderr.write(`purity gate: missing ${path.relative(packageDir, baselinePath)}\n`);
+    process.exit(1);
+  }
+  const baseline = JSON.parse(fs.readFileSync(baselinePath, "utf8"));
+  const actual = scan();
+
+  const problems = [];
+  diffListBuckets(actual.layerViolations, baseline.layerViolations || {}, "layer violation", problems);
+  diffListBuckets(actual.builtinViolations, baseline.builtinViolations || {}, "core builtin violation", problems);
+  diffCountBuckets(actual.clockEnvCounts, baseline.clockEnvCounts || {}, problems);
+
+  if (problems.length > 0) {
+    process.stderr.write(`purity gate: ${problems.length} problem(s)\n`);
+    for (const p of problems) process.stderr.write(`  ${p}\n`);
+    process.exit(1);
+  }
+  process.stdout.write("purity gate: src/ matches the committed baseline (no new core/shell layer breaks, no clock/env drift).\n");
+}
+
+main();

package/scripts/release-check.js

@@ -39,6 +39,7 @@ const checks = [
         "docs/run-retention-reclamation.7.md",
         "docs/durable-state-and-locking.7.md",
         "docs/security-trust-hardening.7.md",
+        "docs/trust-audit-anchor.7.md",
         "../../CHANGELOG.md",
         "../../RELEASE.md"
       ]) {
@@ -58,6 +59,7 @@ const checks = [
   // `dist:check` builds from src/ AND fails closed if the committed dist/ drifted
   // 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: "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"] },
@@ -66,6 +68,11 @@ const checks = [
   // (release-gate.sh) 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
+  // tests above (see test/run-unit.js's header). --skip-tests also skips
+  // this one, matching "tests": ci.yml runs test:unit directly, so this
+  // entry would just repeat it a second time in the release-check pass.
+  { name: "unit tests", command: ["npm", "run", "test:unit"] },
   { name: "canonical apps", command: ["npm", "run", "canonical-apps"] },
   { name: "golden path", command: ["npm", "run", "golden-path"] },
   { name: "CLI MCP parity", command: ["npm", "run", "parity:check"] },
@@ -88,7 +95,7 @@ function main() {
     process.stdout.write(`release:check ${check.name} ... `);
     const started = Date.now();
     try {
-      if (skipTests && check.name === "tests") {
+      if (skipTests && (check.name === "tests" || check.name === "unit tests")) {
         results.push({ name: check.name, ok: true, skipped: true, elapsedMs: 0 });
         process.stdout.write("skipped\n");
         continue;

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")
+);

package/scripts/verify-bump-reproduction.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# verify-bump-reproduction.sh — closes the HEAD~1 verdict-replay bypass.
+#
+# release-gate.yml / npm-publish.yml tolerate a verdict written for the tag
+# commit's PARENT (release-flow.js's cut() reviews content, then adds a
+# mechanical version-bump + the verdict as a NEW child commit that actually
+# gets tagged). A validly-signed verdict at the parent proves someone once
+# approved THAT commit — it does NOT prove the child (the thing actually being
+# tagged) is the deterministic bump cut() would have produced, rather than an
+# attacker's own commit smuggling in arbitrary changes on top of an old,
+# genuinely-approved parent (a real signature on a REPLAYED verdict).
+#
+# This script independently reproduces the bump: checks out the approved
+# parent into a scratch worktree, runs the SAME bump:version/sync:project-index
+# steps cut() runs, stages the SAME way cut() stages (git add -u + the
+# explicit verdict/.sig paths, never -A), and requires the resulting tree to
+# match the ACTUAL tagged commit's tree byte-for-byte. Any difference —
+# anywhere, including a single added file — fails closed.
+#
+# Usage: verify-bump-reproduction.sh <approved-parent-sha> <tagged-sha> <verdict-repo-relative-path> [sig-repo-relative-path]
+#
+# Exit 0: the tagged commit's tree matches the reproduced bump exactly.
+# Exit 1: mismatch, or any step failed (install, bump, sync, worktree, etc).
+set -uo pipefail
+
+# Where THIS SCRIPT ITSELF lives — distinct from REPO_ROOT (the git repo being
+# operated ON, resolved below from the invocation cwd). These coincide in
+# ordinary production use (the script runs from within the same checkout it
+# verifies), but conflating them is wrong: REPO_ROOT could be an ARBITRARY git
+# context (e.g. a test harness's throwaway clone of old history, which never
+# has this script's own sibling files, since they postdate whatever was
+# cloned). Sibling files this script depends on must be found relative to
+# where it is installed, never relative to the repo it happens to be pointed at.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PARENT="${1:-}"
+TAGGED="${2:-}"
+VERDICT_REL="${3:-}"
+SIG_REL="${4:-}"
+if [[ -z "$PARENT" || -z "$TAGGED" || -z "$VERDICT_REL" ]]; then
+  echo "usage: verify-bump-reproduction.sh <parent-sha> <tagged-sha> <verdict-rel-path> [sig-rel-path]" >&2
+  exit 1
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)" || exit 1
+SCRATCH_PARENT="$(mktemp -d)"
+SCRATCH="$SCRATCH_PARENT/wt"
+cleanup() {
+  git -C "$REPO_ROOT" worktree remove --force "$SCRATCH" >/dev/null 2>&1
+  rm -rf "$SCRATCH_PARENT"
+}
+trap cleanup EXIT
+
+if ! git -C "$REPO_ROOT" worktree add --quiet --detach "$SCRATCH" "$PARENT" 2>/dev/null; then
+  echo "verify-bump-reproduction: could not create a scratch worktree at $PARENT" >&2
+  exit 1
+fi
+
+# The target version comes from the TAGGED commit (not the parent, which may
+# still be pre-bump) — read via git plumbing, no separate checkout needed.
+VERSION="$(git -C "$REPO_ROOT" show "$TAGGED:plugins/cool-workflow/package.json" 2>/dev/null | node -e '
+  let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{ try { process.stdout.write(JSON.parse(s).version||""); } catch { process.stdout.write(""); } });
+')"
+if [[ -z "$VERSION" ]]; then
+  echo "verify-bump-reproduction: could not read package.json version from tagged commit $TAGGED" >&2
+  exit 1
+fi
+
+# sync-project-index.js embeds a wall-clock "Generated on <date>" line. Pin it
+# to the TAGGED commit's own committer date (UTC) via a Node --require preload
+# that overrides the global Date constructor (fake-date-for-reproduction.js),
+# NOT an application-level env var: the scratch worktree runs the APPROVED
+# PARENT's OWN checked-out copy of sync-project-index.js, which for every
+# release cut before this mechanism existed has no idea any such env var is
+# meant to be read — an app-level opt-in is a no-op against code that doesn't
+# know to opt in, so it can only ever "work" for releases cut after the
+# mechanism landed (confirmed empirically: re-running an already-shipped
+# release's real approved-parent/tagged pair on a later calendar day produced
+# a tree mismatch whose ONLY diff was that one date line). A global override
+# of the Date constructor, injected before any application code runs, is
+# transparent to the code being executed regardless of which version it is.
+CUT_DATE="$(TZ=UTC git -C "$REPO_ROOT" show -s --format=%cd --date=format-local:%Y-%m-%d "$TAGGED" 2>/dev/null)"
+if [[ -z "$CUT_DATE" ]]; then
+  echo "verify-bump-reproduction: could not read the tagged commit's committer date" >&2
+  exit 1
+fi
+FAKE_DATE_PRELOAD="$SCRIPT_DIR/fake-date-for-reproduction.js"
+
+# Each step's exit code is checked EXPLICITLY and immediately (not via a
+# `cmd1 && cmd2 && cmd3` chain) — a chain's overall success can silently
+# survive an earlier step's failure if a future edit ever loosens it (e.g.
+# `&&` accidentally becoming `;`), which would flip this fail-closed gate to
+# fail-open without changing its outward shape. stdout/stderr from each step
+# are captured (not discarded to /dev/null) so a real failure — a transient
+# npm registry hiccup vs. an actual reproduction mismatch — is distinguishable
+# in the workflow log instead of both collapsing into the same generic message.
+run_step() {
+  local label="$1"
+  shift
+  local out
+  out="$("$@" 2>&1)"
+  local code=$?
+  if [[ $code -ne 0 ]]; then
+    echo "verify-bump-reproduction: $label failed (exit $code):" >&2
+    echo "$out" >&2
+    return 1
+  fi
+  return 0
+}
+
+(
+  cd "$SCRATCH/plugins/cool-workflow" || exit 1
+  export NODE_OPTIONS="--require $FAKE_DATE_PRELOAD"
+  export CW_FAKE_DATE="$CUT_DATE"
+  run_step "npm install" npm install --no-package-lock --ignore-scripts || exit 1
+  run_step "bump:version" npm run bump:version -- "$VERSION" || exit 1
+  run_step "sync:project-index" npm run sync:project-index -- --repo-only || exit 1
+)
+BUMP_STATUS=$?
+if [[ $BUMP_STATUS -ne 0 ]]; then
+  echo "verify-bump-reproduction: reproducing the bump for $PARENT -> v$VERSION failed" >&2
+  exit 1
+fi
+
+mkdir -p "$SCRATCH/.cw-release"
+cp "$REPO_ROOT/$VERDICT_REL" "$SCRATCH/$VERDICT_REL" || exit 1
+if [[ -n "$SIG_REL" && -f "$REPO_ROOT/$SIG_REL" ]]; then
+  cp "$REPO_ROOT/$SIG_REL" "$SCRATCH/$SIG_REL" || exit 1
+fi
+
+# Mirror cut()'s OWN staging exactly (git-add -u + the explicit verdict/.sig
+# paths) — never -A, so an untracked stray left by npm/tooling in the scratch
+# worktree can never silently ride into what we compare.
+git -C "$SCRATCH" add -u
+git -C "$SCRATCH" add -- "$VERDICT_REL"
+if [[ -n "$SIG_REL" && -f "$SCRATCH/$SIG_REL" ]]; then
+  git -C "$SCRATCH" add -- "$SIG_REL"
+fi
+
+EXPECTED_TREE="$(git -C "$SCRATCH" write-tree)"
+ACTUAL_TREE="$(git -C "$REPO_ROOT" rev-parse "$TAGGED^{tree}")"
+
+if [[ "$EXPECTED_TREE" != "$ACTUAL_TREE" ]]; then
+  echo "verify-bump-reproduction: $TAGGED's tree ($ACTUAL_TREE) does not match the deterministic bump reproduced from approved parent $PARENT ($EXPECTED_TREE) — refusing" >&2
+  exit 1
+fi
+
+exit 0

package/scripts/verify-verdict-signature.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+
+// verify-verdict-signature.js — verify an ed25519 signature over a committed
+// release verdict file, against the committed public key
+// (.cw-release/verdict-signing.pub). Portable (node + node:crypto only) so
+// CI (release-gate.yml, npm-publish.yml) and the local block-unapproved-tag.sh
+// hook can all shell out to the SAME check instead of three drifting copies.
+//
+// Exit 0: signature verifies. Exit 1: missing file, unreadable key, or a
+// signature that does not match (tampered verdict, wrong key, hand-written
+// verdict with no real signature). Never throws uncaught — callers rely on
+// the exit code alone, not stderr text.
+//
+// Usage: node verify-verdict-signature.js <verdict-file> <sig-file> <pubkey-file>
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+
+function fail(message) {
+  process.stderr.write(`verify-verdict-signature: ${message}\n`);
+  process.exit(1);
+}
+
+const [, , verdictPath, sigPath, pubkeyPath] = process.argv;
+if (!verdictPath || !sigPath || !pubkeyPath) {
+  process.stderr.write("usage: verify-verdict-signature.js <verdict-file> <sig-file> <pubkey-file>\n");
+  process.exit(2);
+}
+
+let message;
+try {
+  message = fs.readFileSync(verdictPath);
+} catch (error) {
+  fail(`cannot read verdict file ${verdictPath}: ${error.message}`);
+}
+
+let signature;
+try {
+  signature = Buffer.from(fs.readFileSync(sigPath, "utf8").trim(), "base64");
+  if (signature.length === 0) fail(`signature file ${sigPath} is empty`);
+} catch (error) {
+  fail(`cannot read signature file ${sigPath}: ${error.message}`);
+}
+
+let publicKey;
+try {
+  publicKey = crypto.createPublicKey(fs.readFileSync(pubkeyPath, "utf8"));
+} catch (error) {
+  fail(`cannot read public key ${pubkeyPath}: ${error.message}`);
+}
+
+let ok = false;
+try {
+  ok = crypto.verify(null, message, publicKey, signature);
+} catch (error) {
+  fail(`verification error: ${error.message}`);
+}
+
+if (!ok) fail(`signature does not match ${verdictPath} (tampered, wrong key, or not a real signature)`);
+process.exit(0);