cool-workflow 0.2.4 → 0.2.6

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.6");
 
     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.6 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.6");
     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\.6/);
     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/parity-check.js

@@ -8,9 +8,9 @@
 //
 // FAIL CLOSED ON DRIFT (BSD discipline, same shape as gen-manifests --check):
 //   1. STATIC parity — the declared capability registry must exactly match the
-//      live MCP tool list (tools/list) and the CLI dispatch tokens parsed from
-//      the built CLI dispatch surface. A tool or command on one surface but not
-//      the other, or not declared in src/capability-registry.ts, is release-blocking.
+//      live MCP tool list (tools/list), every declared CLI path must resolve
+//      through the live dispatcher, and real `cw help` must match the declared
+//      help surface. Any gap is release-blocking.
 //   2. PAYLOAD parity — for every capability declared `payloadIdentical`, the
 //      `cw <cmd> --json` payload must equal the `cw_<tool>` MCP result on a real
 //      bootstrap run (whitespace + generation-moment ISO timestamps aside).
@@ -38,7 +38,6 @@ const node = process.execPath;
 const cli = path.join(pluginRoot, "dist", "cli.js");
 const mcpServer = path.join(pluginRoot, "dist", "mcp-server.js");
 const registry = require(path.join(pluginRoot, "dist", "core", "capability-table.js"));
-const { formatHelp } = require(path.join(pluginRoot, "dist", "core", "format", "help.js"));
 const { loadRunFromCwd, saveCheckpoint } = require(path.join(pluginRoot, "dist", "shell", "run-store.js"));
 const { appendRunNode, createStateNode } = require(path.join(pluginRoot, "dist", "core", "state", "state-node.js"));
 
@@ -71,15 +70,6 @@ function liveMcpTools() {
   return JSON.parse(line).result.tools.map((tool) => tool.name);
 }
 
-function cliDispatchTokens() {
-  // v2 dispatch is table-driven (findCapabilityByCliPath over REGISTRY), not a
-  // switch, so the token set is the union of every CLI capability's accepted
-  // first tokens (cli.caseTokens where an alias set is declared, else cli.path).
-  // The reachability check below then proves each declared path resolves through
-  // the live dispatcher — replacing the old `case "x":` dist source-grep.
-  return [...new Set(registry.cliCapabilities().flatMap((cap) => cap.cli.caseTokens ?? cap.cli.path))];
-}
-
 // Old-build top-level verbs kept in the frozen help "More commands" index line
 // but folded in v2 into subcommands / the shell layer: init->app.init,
 // search->run.search (declaredCliHelpTokens collapses both to app/run), and
@@ -87,8 +77,8 @@ function cliDispatchTokens() {
 // discovery text, not dispatch-parity tokens — exclude them.
 const HELP_INDEX_ONLY_TOKENS = new Set(["init", "search", "update"]);
 
-function cliHelpTokens() {
-  const lines = formatHelp().split(/\r?\n/);
+function cliHelpTokens(helpText) {
+  const lines = helpText.split(/\r?\n/);
   const tokens = new Set();
   for (const line of lines) {
     // Command lines start with exactly 2 spaces; examples are 4-space.
@@ -104,6 +94,29 @@ function cliHelpTokens() {
   return [...tokens].sort();
 }
 
+function liveCliHelpTokens() {
+  const helpText = execFileSync(node, [cli, "help", "--no-color"], {
+    cwd: pluginRoot,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" }
+  });
+  return cliHelpTokens(helpText);
+}
+
+/** The CLI dispatcher calls this same lookup. Keep the probe outside the
+ * registry report so the live gate does not compare a token list made from the
+ * registry with another list made from the same registry. */
+function cliReachabilityIssues(table) {
+  const issues = [];
+  for (const cap of table.cliCapabilities()) {
+    const resolved = table.findCapabilityByCliPath(cap.cli.path);
+    if (!resolved || !resolved.cli || typeof resolved.cli.handler !== "function") {
+      issues.push(`${cap.capability}: CLI path ${cap.cli.path.join(" ")} does not resolve through the dispatcher`);
+    }
+  }
+  return issues;
+}
+
 // ---- 2. payload identity ---------------------------------------------------
 // Generation-moment ISO timestamps are presentation metadata, not capability
 // data: the same field carries the wall-clock instant of the render. Neutralize
@@ -907,9 +920,11 @@ async function payloadParity() {
 async function main() {
   const check = process.argv.includes("--check");
   const tools = liveMcpTools();
-  const tokens = cliDispatchTokens();
-  const helpTokens = cliHelpTokens();
-  const report = registry.buildParityReport({ mcpTools: tools, cliTokens: tokens, helpTokens });
+  const helpTokens = liveCliHelpTokens();
+  const report = registry.buildParityReport({ mcpTools: tools, helpTokens });
+  const reachabilityIssues = cliReachabilityIssues(registry);
+  report.registryLint.push(...reachabilityIssues);
+  report.ok = report.ok && reachabilityIssues.length === 0;
   const payload = await payloadParity();
 
   const ok = report.ok && payload.mismatches.length === 0;
@@ -940,13 +955,17 @@ async function main() {
     if (report.payloadProbeInvalidClassifications.length) lines.push(`  - payload probe classifications for invalid capabilities: ${report.payloadProbeInvalidClassifications.join(", ")}`);
     if (report.registryLint.length) lines.push(`  - registry lint: ${report.registryLint.join("; ")}`);
     if (payload.mismatches.length) lines.push(`  - cw --json != cw_<tool> payload for: ${payload.mismatches.join(", ")}`);
-    lines.push("Reconcile src/capability-registry.ts, cli.ts, and mcp-server.ts so both surfaces render one data source.\n");
+    lines.push("Reconcile src/wiring/capability-table, src/cli, and src/mcp so both surfaces render one data source.\n");
     process.stderr.write(lines.join("\n"));
     process.exitCode = 1;
   }
 }
 
-main().catch((error) => {
-  process.stderr.write(`parity-check: ${error instanceof Error ? error.message : String(error)}\n`);
-  process.exitCode = 1;
-});
+module.exports = { cliHelpTokens, cliReachabilityIssues };
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`parity-check: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/purity-baseline.json

@@ -1,8 +1,5 @@
 {
   "builtinViolations": {
-    "core/state/run-paths.ts": [
-      "node:fs"
-    ],
     "core/trust/telemetry-attestation.ts": [
       "node:fs"
     ]

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) {
@@ -208,12 +229,12 @@ function buildReviewerInput(resultPath) {
     "  <one concrete sentence: the user-visible capability this ships>",
     "or:",
     "  REJECTED",
-    "  <numbered gate failures with file:line references>",
+    "  kind: semantic-review",
+    "  1. <a semantic code finding with repo-relative file:line evidence>",
     "",
-    "If your host wrapper asks for Markdown, JSON, or a fenced result block, still put",
-    "the exact APPROVED/REJECTED verdict line above as a standalone line outside any",
-    "prose or code fence. The release tool extracts only strict standalone verdict",
-    "lines; prose such as 'Verdict: APPROVED' is not trusted.",
+    "The control plane already ran the deterministic gate. Do not run it again",
+    "or reject with an unsupported claim that it failed. A rejection without the",
+    "semantic-review form above is invalid reviewer output and remains fail closed.",
     ""
   ].join("\n");
 }
@@ -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 lines.slice(lines.indexOf(rejectedLine)).join("\n").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,
@@ -368,14 +432,19 @@ function verifyVerdict(resultPath) {
   const text = fs.readFileSync(resultPath, "utf8");
   const lines = text.split(/\r?\n/);
   const firstLine = lines[0] || "";
+  if (isRejectedLine(firstLine)) {
+    const rejection = validateSemanticRejection(lines);
+    if (!rejection.ok) {
+      die(`invalid reviewer output — ${rejection.reason}. Release remains blocked; this is not a verified code rejection.`, text.trim());
+    }
+    die("reviewer rejected the release with semantic evidence.", text.trim());
+  }
   if (firstLine !== `APPROVED ${HEAD}`) {
-    if (firstLine.toUpperCase() !== "REJECTED") {
-      const normalized = extractVerdictFromStdout(text, resultPath);
-      if (normalized && normalized.split(/\r?\n/)[0] === `APPROVED ${HEAD}`) {
-        fs.writeFileSync(resultPath, `${normalized}\n`);
-        const normalizedLines = normalized.split(/\r?\n/);
-        return (normalizedLines[1] || "").trim();
-      }
+    const normalized = extractVerdictFromStdout(text, resultPath);
+    if (normalized && normalized.split(/\r?\n/)[0] === `APPROVED ${HEAD}`) {
+      fs.writeFileSync(resultPath, `${normalized}\n`);
+      const normalizedLines = normalized.split(/\r?\n/);
+      return (normalizedLines[1] || "").trim();
     }
     die(`verdict first line must be exactly "APPROVED ${HEAD}" — release blocked.`, text.trim());
   }
@@ -383,12 +452,41 @@ function verifyVerdict(resultPath) {
   return cap;
 }
 
+function validateSemanticRejection(lines) {
+  if (lines[0] !== "REJECTED") {
+    return { ok: false, reason: 'a rejection must start with exact "REJECTED"' };
+  }
+  if (lines[1] !== "kind: semantic-review") {
+    return { ok: false, reason: 'a rejection must declare exact "kind: semantic-review"' };
+  }
+  const findings = lines.slice(2).filter((line) => /^\d+\.\s+/.test(line));
+  if (!findings.length) return { ok: false, reason: "a semantic rejection needs a numbered finding" };
+  for (const finding of findings) {
+    const match = finding.match(/^\d+\.\s+.*?\b([A-Za-z0-9][A-Za-z0-9_./-]*):(\d+)\b/);
+    if (!match) return { ok: false, reason: "each semantic finding needs a repo-relative file:line locator" };
+    const rel = match[1];
+    const line = Number(match[2]);
+    if (rel.startsWith("/") || rel.split("/").includes("..") || !Number.isSafeInteger(line) || line < 1) {
+      return { ok: false, reason: "a semantic finding has an unsafe file:line locator" };
+    }
+    const target = path.join(repoRoot, rel);
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      return { ok: false, reason: `semantic evidence path does not exist: ${rel}` };
+    }
+  }
+  return { ok: true };
+}
+
 // ---- 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}`);
+  // 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 +549,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 +749,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 +778,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 +803,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"}`]);