cool-workflow 0.2.2 → 0.2.4

package/scripts/release-oneclick.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+"use strict";
+
+// release-oneclick.js — the operator's ONE command for a full release.
+//
+//   npm run release -- X.Y.Z
+//   node scripts/release-oneclick.js X.Y.Z [--dry-run]
+//
+// This is a pure orchestrator over EXISTING tools (release-flow.js,
+// bump-version.js, sync-project-index.js, gh, git) — it adds no new release
+// logic of its own, only sequencing, resumability, and fail-fast checks.
+//
+// The two-step release model this implements:
+//   1. Ask the agent to "prepare release X.Y.Z" — it drafts the CHANGELOG
+//      entry and opens/merges the version-bump PR. This step never touches
+//      CW_RELEASE_VERDICT_PRIVKEY.
+//   2. The OPERATOR runs this script, in a shell where
+//      CW_RELEASE_VERDICT_PRIVKEY is set. Nothing in this file reads that
+//      env var directly — it is forwarded to `release-flow.js`'s existing
+//      signVerdictIfConfigured(), unchanged.
+//
+// Stages (each is idempotent — probes current state before acting, so a
+// re-run after a failure resumes rather than repeats):
+//   0. preflight   — release-flow.js --cut --preflight-only (fail in seconds,
+//                    before the gate/vendor-preflight/reviewer spend anything)
+//   1. bump PR     — only if package.json is not already at the target
+//                    version; skipped when the agent's prep PR already landed
+//   2. cut         — release-flow.js --cut --version X --push (gate, live
+//                    vendor preflight, reviewer, sign, tag-only push, Release)
+//   3. record+wait — PR landing the verdict+.sig onto main (informational,
+//                    no gate implications) + poll release-gate/npm-publish +
+//                    confirm `npm view` shows the new version
+//
+// Resume: when the vX.Y.Z tag already exists (local or on origin), the cut
+// already happened — stages 0-2 are skipped and the run goes STRAIGHT to
+// stage 3. This is what makes a re-run after a stage-3 death (a red CI run,
+// a network drop, a Ctrl-C mid-wait) pick the release back up instead of
+// being refused by the preflight's own already-tagged check. Every wait has
+// a hard deadline and dies loudly after repeated gh/git failures — a hung
+// wait is indistinguishable from a dead release otherwise.
+//
+// Test seam: CW_ONECLICK_GH_CMD / CW_ONECLICK_GIT_CMD override the gh/git
+// binaries (single executable token, spawned shell:false) for smoke stubs.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const scriptsDir = __dirname;
+const pluginRoot = path.resolve(scriptsDir, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+
+const argv = process.argv.slice(2);
+const DRY_RUN = argv.includes("--dry-run");
+const version = argv.find((a) => /^\d+\.\d+\.\d+$/.test(a));
+
+const GIT_BIN = (process.env.CW_ONECLICK_GIT_CMD || "git").trim();
+const GH_BIN = (process.env.CW_ONECLICK_GH_CMD || "gh").trim();
+
+function die(msg, extra) {
+  process.stderr.write(`release-oneclick: ${msg}\n`);
+  if (extra) process.stderr.write(`${extra}\n`);
+  process.exit(1);
+}
+function say(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+function stage(n, label) {
+  say(`\n[${n}/4] ${label}`);
+}
+function git(args, opts = {}) {
+  const r = spawnSync(GIT_BIN, args, { cwd: repoRoot, encoding: "utf8", shell: false, ...opts });
+  return { code: r.status, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+// Like git(), but stdout is returned VERBATIM — no trim. The record stage
+// copies verdict/.sig bytes out of the tag commit, and those bytes must stay
+// exactly what was signed (a trimmed copy next to the same .sig could never
+// verify again).
+function gitRaw(args, opts = {}) {
+  const r = spawnSync(GIT_BIN, args, { cwd: repoRoot, encoding: "buffer", shell: false, ...opts });
+  return { code: r.status, out: r.stdout || Buffer.alloc(0), err: (r.stderr || "").toString().trim() };
+}
+function gh(args, opts = {}) {
+  const r = spawnSync(GH_BIN, args, { cwd: repoRoot, encoding: "utf8", shell: false, ...opts });
+  return { code: r.status, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+// Shared poll helper: every wait in this script has a hard deadline (a wait
+// that can spin forever hides a dead release) and dies after too many gh/git
+// failures in a row (an expired auth or dead network must surface, not hang).
+function poll({ label, timeoutMs, intervalMs, probe }) {
+  const deadline = Date.now() + timeoutMs;
+  let consecutiveErrors = 0;
+  for (;;) {
+    const r = probe();
+    if (r && r.done) return r.value;
+    consecutiveErrors = r && r.error ? consecutiveErrors + 1 : 0;
+    if (consecutiveErrors >= 10) die(`${label}: 10 gh/git probes in a row failed — check network/auth and re-run to resume.`);
+    if (Date.now() > deadline) die(`${label}: still not done after ${Math.round(timeoutMs / 60000)} minutes — inspect manually, then re-run to resume.`);
+    sleep(intervalMs);
+  }
+}
+
+if (!version) {
+  die("usage: node scripts/release-oneclick.js X.Y.Z [--dry-run]");
+}
+
+// ---- resume detection (before anything else) --------------------------------
+// After a successful cut, the vX.Y.Z tag exists — release-flow's preflight
+// would then (correctly, for a FRESH cut) refuse to run. But a re-run of THIS
+// script after a stage-3 failure (a red CI run, a network drop, a Ctrl-C
+// during the wait) must not be told "pick the next version": the release is
+// mid-flight, not done. So: tag already cut -> skip straight to stage 3.
+function alreadyCut() {
+  if (git(["tag", "-l", `v${version}`]).out) return true;
+  if (DRY_RUN) return false; // offline decision only in dry-run
+  const remote = git(["ls-remote", "origin", `refs/tags/v${version}`]);
+  return remote.code === 0 && Boolean(remote.out);
+}
+
+// ---- stage 0: preflight -----------------------------------------------------
+function runPreflight() {
+  stage(0, "preflight");
+  const args = ["scripts/release-flow.js", "--cut", "--version", version, "--push", "--preflight-only"];
+  const r = spawnSync("node", args, { cwd: pluginRoot, encoding: "utf8", stdio: "inherit" });
+  if (r.status !== 0) {
+    die("preflight failed — fix the issue above before re-running (nothing was done yet).");
+  }
+  if (gh(["--version"]).code !== 0) die("gh CLI not found — required for the bump/verdict PRs and the GitHub Release.");
+  if (gh(["auth", "status"]).code !== 0) die("gh is not authenticated — run `gh auth login` first.");
+  say("preflight OK");
+}
+
+// ---- stage 1: bump PR (skipped if already at target version) ---------------
+function currentPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+function runBumpStage() {
+  stage(1, "version bump");
+  if (currentPackageVersion() === version) {
+    say(`package.json already at ${version} — assuming the prep PR already landed, skipping.`);
+    return;
+  }
+  if (DRY_RUN) {
+    say(`[dry-run] would: branch off origin/main, bump:version -- ${version} --content, sync:project-index, open + auto-merge a bump PR.`);
+    return;
+  }
+
+  const fetch = git(["fetch", "origin", "main", "--quiet"]);
+  if (fetch.code !== 0) die("git fetch origin main failed — the bump branch must start from the REAL main tip", fetch.err);
+  const branch = `release/v${version}-bump`;
+  const co = git(["checkout", "-B", branch, "origin/main"]);
+  if (co.code !== 0) die("could not branch from origin/main for the bump PR", co.err);
+
+  const bump = spawnSync("npm", ["run", "bump:version", "--", version, "--content"], { cwd: pluginRoot, stdio: "inherit" });
+  if (bump.status !== 0) die("bump:version --content failed");
+
+  const sync = spawnSync("npm", ["run", "sync:project-index", "--", "--repo-only"], { cwd: pluginRoot, stdio: "inherit" });
+  if (sync.status !== 0) die("sync:project-index failed");
+
+  // tsc's incremental cache can ship a stale dist/version.js after a version
+  // edit (documented gotcha) — force a clean rebuild before committing.
+  fs.rmSync(path.join(pluginRoot, ".cache"), { recursive: true, force: true });
+  const build = spawnSync("npm", ["run", "build"], { cwd: pluginRoot, stdio: "inherit" });
+  if (build.status !== 0) die("npm run build failed after bump");
+
+  const logPath = path.join(repoRoot, "ITERATION_LOG.md");
+  const log = fs.readFileSync(logPath, "utf8");
+  const entry = [
+    "# CW Iteration Log",
+    "",
+    `## Batch — v${version} version bump (Unreleased)`,
+    "",
+    `> Release prep for v${version}: bump every structured surface with`,
+    `> \`bump:version -- ${version} --content\` and fill the gated content`,
+    "> surfaces (CHANGELOG.md, RELEASE.md, docs version lists). The bump",
+    "> lands as its own PR before the cut so the cut's own bump:version step",
+    "> is a no-op. No behavior change; the version constant is the only src",
+    "> edit. Generated by release-oneclick.js's bump stage.",
+    "",
+    "| cycle | goal | files | tests | gate | tagged |",
+    "|-------|------|-------|-------|------|--------|",
+    `| - | Bump to v${version} across all structured + content surfaces via release-oneclick.js. | ` +
+      "package.json + lockfile + manifests + src/core/version.ts + matching dist/**, CHANGELOG.md, RELEASE.md, docs/*.7.md version lists. | " +
+      "Full local gate before PR. | BUILD OK; content-surface gate OK. | no (bump PR; the tag comes from release-flow --cut) |"
+  ].join("\n");
+  fs.writeFileSync(logPath, `${entry}\n\n${log.replace(/^# CW Iteration Log\n\n?/, "")}`);
+
+  // Tracked files only — NEVER `git add -A` here. Everything the bump stage
+  // touches is already tracked (bump surfaces, docs appends, ITERATION_LOG,
+  // dist), and an untracked stray (a scratch file, a reviewer transcript with
+  // the operator's home path) must not ride into a PR onto main — the exact
+  // incident cut()'s staging comment documents from v0.1.96.
+  git(["add", "-u"], { cwd: repoRoot });
+  const commit = git(["commit", "-m", `chore(release): bump version to ${version}`], { cwd: repoRoot });
+  if (commit.code !== 0) die("bump commit failed", commit.err);
+
+  // --force-with-lease: a prior run may have pushed this branch and then died
+  // before the PR merged; the re-run rebuilds the branch from origin/main with
+  // a new sha, and a plain push would be rejected non-fast-forward. The lease
+  // keeps this safe: it only replaces the remote branch we saw at fetch time.
+  const push = git(["push", "-u", "--force-with-lease", "origin", branch], { cwd: repoRoot });
+  if (push.code !== 0) die("bump branch push failed", push.err);
+
+  const pr = gh(["pr", "create", "--base", "main", "--head", branch, "--title", `chore(release): bump version to ${version}`, "--body", "Automated version bump ahead of the gated cut. Generated by release-oneclick.js."]);
+  if (pr.code !== 0) die("gh pr create failed for the bump PR", pr.err);
+  say(pr.out);
+
+  const merge = gh(["pr", "merge", branch, "--auto", "--squash"]);
+  if (merge.code !== 0) die("gh pr merge --auto failed for the bump PR", merge.err);
+
+  say("waiting for the bump PR to merge...");
+  poll({
+    label: "bump PR merge wait",
+    timeoutMs: 30 * 60 * 1000,
+    intervalMs: 15000,
+    probe: () => {
+      const view = gh(["pr", "view", branch, "--json", "state"]);
+      if (view.code !== 0) return { error: true };
+      let state;
+      try {
+        state = JSON.parse(view.out).state;
+      } catch {
+        return { error: true };
+      }
+      if (state === "MERGED") return { done: true };
+      if (state === "CLOSED") die("the bump PR was closed without merging");
+      return {};
+    }
+  });
+  say("bump PR merged.");
+}
+
+// ---- stage 2: cut ------------------------------------------------------------
+function runCutStage() {
+  stage(2, "cut (gate + vendor preflight + reviewer + sign + tag + push)");
+  if (DRY_RUN) {
+    say(`[dry-run] would: node scripts/release-flow.js --cut --version ${version} --push`);
+    return;
+  }
+  git(["fetch", "origin", "main", "--quiet"], { cwd: repoRoot });
+  const co = git(["checkout", "-B", `release/v${version}-cut`, "origin/main"], { cwd: repoRoot });
+  if (co.code !== 0) die("could not branch from origin/main for the cut", co.err);
+
+  const r = spawnSync("node", ["scripts/release-flow.js", "--cut", "--version", version, "--push"], {
+    cwd: pluginRoot,
+    encoding: "utf8",
+    stdio: "inherit"
+  });
+  if (r.status !== 0) die("cut failed — see the release-flow.js output above.");
+  say("cut complete: tag pushed, GitHub Release created.");
+}
+
+// ---- stage 3: record on main + wait for CI + confirm npm -------------------
+function verdictPaths() {
+  const dir = path.join(repoRoot, ".cw-release");
+  const tagCommit = git(["rev-parse", `v${version}^{commit}`]).out;
+  const reviewedParent = git(["rev-parse", `v${version}~1`]).out;
+  // cut() commits the verdict directly on the reviewed parent, so the
+  // filename is keyed on THAT sha, not the tag commit's own sha.
+  const verdict = path.join(dir, `review-${reviewedParent}.verdict`);
+  const sig = `${verdict}.sig`;
+  return { tagCommit, reviewedParent, verdict, sig, dir };
+}
+
+function runRecordAndWaitStage() {
+  stage(3, "record on main + wait for CI + confirm npm");
+  if (DRY_RUN) {
+    say("[dry-run] would: open a PR landing the verdict+.sig onto main, then poll release-gate/npm-publish/npm view.");
+    return;
+  }
+
+  const { tagCommit, reviewedParent, verdict, sig } = verdictPaths();
+  const relVerdict = path.relative(repoRoot, verdict);
+  const relSig = path.relative(repoRoot, sig);
+  // Byte-exact copies from the TAG commit — the .sig was made over the
+  // verdict file's exact bytes, so a trimmed/normalized copy on main could
+  // never verify against the same signature again.
+  const verdictBytes = gitRaw(["show", `${tagCommit}:${relVerdict}`], { cwd: repoRoot });
+  if (verdictBytes.code === 0) {
+    const fetch = git(["fetch", "origin", "main", "--quiet"], { cwd: repoRoot });
+    if (fetch.code !== 0) {
+      say(`WARN: git fetch failed (${fetch.err}) — skipping the main-record PR (informational only).`);
+    } else {
+      const branch = `release/v${version}-record`;
+      const co = git(["checkout", "-B", branch, "origin/main"], { cwd: repoRoot });
+      if (co.code === 0) {
+        fs.mkdirSync(path.dirname(verdict), { recursive: true });
+        fs.writeFileSync(verdict, verdictBytes.out);
+        const sigBytes = gitRaw(["show", `${tagCommit}:${relSig}`], { cwd: repoRoot });
+        if (sigBytes.code === 0) fs.writeFileSync(sig, sigBytes.out);
+        git(["add", "--", relVerdict], { cwd: repoRoot });
+        if (fs.existsSync(sig)) git(["add", "--", relSig], { cwd: repoRoot });
+        const status = git(["status", "--porcelain"], { cwd: repoRoot });
+        if (status.out) {
+          const commit = git(["commit", "-m", `chore(release): record the v${version} reviewer verdict on main`], { cwd: repoRoot });
+          if (commit.code === 0) {
+            git(["push", "-u", "--force-with-lease", "origin", branch], { cwd: repoRoot });
+            const pr = gh(["pr", "create", "--base", "main", "--head", branch, "--title", `chore(release): record the v${version} reviewer verdict on main`, "--body", `Informational — lands the tagged v${version} verdict + signature onto main for the repo's own audit trail. No gate implications (main's required checks don't include release-gate). Reviewed commit: ${reviewedParent}.`]);
+            if (pr.code === 0) {
+              say(pr.out);
+              gh(["pr", "merge", branch, "--auto", "--squash"]);
+            } else {
+              say(`WARN: could not open the record PR (${pr.err}) — continuing, this is informational only.`);
+            }
+          }
+        } else {
+          say("main already has this verdict recorded — nothing to do.");
+        }
+      }
+    }
+  } else {
+    say(`WARN: no verdict at ${relVerdict} in the tag commit — skipping the main-record PR (informational only, not release-blocking).`);
+  }
+
+  say(`waiting for release-gate on tag v${version}...`);
+  const gateRunId = poll({
+    label: "release-gate wait",
+    timeoutMs: 45 * 60 * 1000,
+    intervalMs: 20000,
+    probe: () => {
+      const list = gh(["run", "list", "--workflow", "release-gate", "--limit", "10", "--json", "databaseId,headBranch,status,conclusion"]);
+      if (list.code !== 0) return { error: true };
+      let runs;
+      try {
+        runs = JSON.parse(list.out);
+      } catch {
+        return { error: true };
+      }
+      const gateRun = runs.find((r) => r.headBranch === `v${version}`);
+      if (gateRun && gateRun.status === "completed") {
+        if (gateRun.conclusion === "success") return { done: true, value: gateRun.databaseId };
+        die(`release-gate FAILED — inspect: gh run view ${gateRun.databaseId} --log-failed`);
+      }
+      return {};
+    }
+  });
+  say(`release-gate: SUCCESS (run ${gateRunId})`);
+
+  // npm-publish is created only AFTER release-gate completes (workflow_run
+  // trigger), so the run to wait for may not exist yet — and the newest
+  // completed npm-publish run at this moment is usually the PREVIOUS
+  // release's. Only accept a run created at-or-after the moment the gate
+  // finished (small clock-skew allowance), and keep waiting until that run
+  // exists and completes.
+  say("waiting for npm-publish...");
+  const gateDoneMs = Date.now();
+  poll({
+    label: "npm-publish wait",
+    timeoutMs: 30 * 60 * 1000,
+    intervalMs: 20000,
+    probe: () => {
+      const list = gh(["run", "list", "--workflow", "npm-publish", "--limit", "5", "--json", "databaseId,status,conclusion,createdAt"]);
+      if (list.code !== 0) return { error: true };
+      let runs;
+      try {
+        runs = JSON.parse(list.out);
+      } catch {
+        return { error: true };
+      }
+      const fresh = runs
+        .filter((r) => Date.parse(r.createdAt) >= gateDoneMs - 120000)
+        .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))[0];
+      if (fresh && fresh.status === "completed") {
+        if (fresh.conclusion === "success") return { done: true };
+        die(`npm-publish FAILED (conclusion: ${fresh.conclusion}) — inspect: gh run view ${fresh.databaseId} --log-failed`);
+      }
+      return {};
+    }
+  });
+  say("npm-publish: SUCCESS");
+
+  say("confirming npm...");
+  poll({
+    label: "npm registry confirmation",
+    timeoutMs: 10 * 60 * 1000,
+    intervalMs: 15000,
+    probe: () => {
+      const view = spawnSync("npm", ["view", "cool-workflow", "version"], { encoding: "utf8" });
+      if (view.status !== 0) return { error: true };
+      return view.stdout.trim() === version ? { done: true } : {};
+    }
+  });
+  say(`npm view cool-workflow version -> ${version} — confirmed live.`);
+  const releaseUrl = gh(["release", "view", `v${version}`, "--json", "url", "--jq", ".url"]);
+  say(`\nRELEASE COMPLETE: v${version}`);
+  if (releaseUrl.code === 0) say(`GitHub Release: ${releaseUrl.out}`);
+  say(`npm:            https://www.npmjs.com/package/cool-workflow/v/${version}`);
+}
+
+if (alreadyCut()) {
+  say(`tag v${version} already exists — the cut already happened; resuming at stage 3 (CI wait + record + confirm).`);
+  if (DRY_RUN) {
+    say("[dry-run] would resume at stage 3: record PR + wait for release-gate/npm-publish + npm view confirmation.");
+  } else {
+    runRecordAndWaitStage();
+  }
+} else {
+  runPreflight();
+  runBumpStage();
+  runCutStage();
+  runRecordAndWaitStage();
+}

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