cool-workflow 0.1.81 → 0.1.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.81",
+  "version": "0.1.83",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -14,7 +14,7 @@
   "bugs": {
     "url": "https://github.com/coo1white/cool-workflow/issues"
   },
-  "description": "Auditable workflow control-plane and orchestration runtime: TypeScript dispatch, evidence-gated verification, state commits, scheduling, routines, multi-agent coordination, and MCP. Delegates execution to external agents — never runs models.",
+  "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "type": "commonjs",
   "license": "BSD-2-Clause",
   "author": {
@@ -51,6 +51,7 @@
     "forward-ref": "node scripts/forward-ref-docs.js",
     "verify:container": "node scripts/verify-container-selfref.js",
     "gen:manifests": "node scripts/gen-manifests.js",
+    "gen:parity": "node scripts/gen-parity-doc.js",
     "manifest:load-check": "node test/vendor-manifest-load-smoke.js",
     "parity:check": "node scripts/parity-check.js --check",
     "version:sync": "node scripts/version-sync-check.js",

package/scripts/canonical-apps.js

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

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+
+// Batch delegate child (extracted from execution-backend/agent.ts so it is a
+// real, greppable, lint-able file instead of an embedded `node -e` template
+// string — F11). Spawned via `node <this-path>` (shell:false) by
+// runAgentBatchOutcomes.
+//
+// Reads jobs JSON on stdin, spawns ALL concurrently (shell:false, inherited env —
+// the agent's own credentials resolve; CW never reads them), per-job SIGTERM at
+// timeoutMs + SIGKILL at +5s, caps each captured stdout at 32MB, and prints the
+// outcome array when every job has settled. stderr is drained (a full pipe must
+// never wedge a child). A kill yields exitCode null — the no-exit-code refusal.
+//
+// THE RED LINE: this child only `spawn`s the operator-resolved agent binary with
+// shell:false. It imports NO model SDK and reads NO credentials. Behavior MUST
+// stay byte-identical to the previous embedded string.
+
+const { spawn } = require("node:child_process");
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (d) => (raw += d));
+process.stdin.on("end", () => {
+  const jobs = JSON.parse(raw);
+  if (!jobs.length) { process.stdout.write("[]"); return; }
+  const out = new Array(jobs.length);
+  let pending = jobs.length;
+  const CAP = 32 * 1024 * 1024;
+  jobs.forEach((job, i) => {
+    let stdout = "";
+    let settled = false;
+    const settle = (o) => {
+      if (settled) return;
+      settled = true;
+      out[i] = o;
+      if (--pending === 0) process.stdout.write(JSON.stringify(out));
+    };
+    let child;
+    try {
+      child = spawn(job.binary, job.args, { cwd: job.cwd, env: process.env, shell: false });
+    } catch (error) {
+      settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout: "" });
+      return;
+    }
+    const term = setTimeout(() => { try { child.kill("SIGTERM"); } catch {} }, job.timeoutMs);
+    const kill = setTimeout(() => { try { child.kill("SIGKILL"); } catch {} }, job.timeoutMs + 5000);
+    child.stdout.on("data", (d) => { if (stdout.length < CAP) stdout += d; });
+    child.stderr.on("data", () => {});
+    child.on("error", (error) => {
+      clearTimeout(term); clearTimeout(kill);
+      settle({ spawnError: String((error && error.message) || error), exitCode: null, stdout });
+    });
+    child.on("close", (code) => {
+      clearTimeout(term); clearTimeout(kill);
+      settle({ exitCode: typeof code === "number" ? code : null, stdout });
+    });
+  });
+});

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+"use strict";
+
+// HTTP delegate child (extracted from execution-backend.ts so it is a real,
+// greppable, lint-able file instead of an embedded `node -e` template string —
+// F11). Spawned via `node <this-path>` (shell:false) by runHttpDelegation.
+//
+// A self-contained Node child that performs the remote/CI delegation: it reads a
+// JSON job on stdin, POSTs it to the endpoint, optionally polls a returned jobId,
+// and prints `{ exitCode, stdout }` (or `{ error }`) on stdout. Node-only (global
+// fetch, node >=18), so the driver stays portable and synchronous from CW's view.
+//
+// THE RED LINE: this child speaks ONLY plain HTTP to an operator-configured
+// endpoint. It imports NO model SDK, holds NO API key, and constructs NO model
+// API request. Behavior MUST stay byte-identical to the previous embedded string.
+
+(async () => {
+  const read = () => new Promise((res) => { let b = ""; process.stdin.on("data", (c) => (b += c)); process.stdin.on("end", () => res(b)); });
+  try {
+    const job = JSON.parse((await read()) || "{}");
+    const endpoint = process.env.CW_DELEGATE_ENDPOINT;
+    if (!endpoint) throw new Error("no endpoint");
+    const post = await fetch(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(job) });
+    if (!post.ok) throw new Error("runner responded " + post.status);
+    let data = await post.json();
+    // Poll a returned jobId until the runner reports done.
+    let guard = 0;
+    while (data && data.jobId && data.done !== true && guard++ < 600) {
+      await new Promise((r) => setTimeout(r, 1000));
+      const poll = await fetch(endpoint + (endpoint.includes("?") ? "&" : "?") + "jobId=" + encodeURIComponent(data.jobId));
+      if (!poll.ok) throw new Error("poll responded " + poll.status);
+      data = await poll.json();
+    }
+    if (typeof data.exitCode !== "number") throw new Error("runner did not report an exitCode");
+    process.stdout.write(JSON.stringify({ exitCode: data.exitCode, stdout: String(data.stdout || "") }));
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ error: e && e.message ? e.message : String(e) }));
+  }
+})();

package/scripts/dogfood-release.js

@@ -5,7 +5,7 @@ const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
-const TARGET_VERSION = "0.1.81";
+const TARGET_VERSION = "0.1.83";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/gen-parity-doc.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+"use strict";
+
+// gen-parity-doc.js — generate the CLI<->MCP parity matrix, counts, and the
+// surface-specific (cli-only / projected) enumerations in
+// docs/cli-mcp-parity.7.md DIRECTLY from the capability registry (the single
+// source of truth). The matrix declares itself "machine-complete by design", so
+// it must BE machine-generated — a hand-maintained table drifts (it did: 132
+// rows vs a 190-capability registry). Mechanism, not policy.
+//
+//   node scripts/gen-parity-doc.js            # rewrite the generated regions
+//   node scripts/gen-parity-doc.js --check    # fail closed if the doc drifted
+//
+// Idempotent: re-running with no registry change is a no-op. Only the four
+// marker-delimited regions are touched; all surrounding prose (incl. the Basic
+// English narrative and version trailers) is preserved byte-for-byte.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const DOC = path.join(pluginRoot, "docs", "cli-mcp-parity.7.md");
+const CHECK = process.argv.includes("--check");
+
+const { CAPABILITY_REGISTRY } = require(path.join(pluginRoot, "dist", "capability-registry.js"));
+
+const NUM_WORDS = ["Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten", "Eleven", "Twelve"];
+const numWord = (n) => NUM_WORDS[n] || String(n);
+
+function cliCommand(cap) {
+  return cap.cli ? `cw ${cap.cli.path.join(" ")}` : "—";
+}
+function cliDisplay(cap) {
+  // Human form used in the prose bullets (e.g. "schedule daemon", "demo tamper").
+  return cap.cli ? cap.cli.path.join(" ") : cap.capability;
+}
+function mcpTool(cap) {
+  return cap.mcp ? cap.mcp.tool : "—";
+}
+function payload(cap) {
+  if (cap.surface !== "both") return cap.surface;
+  return cap.payloadIdentical === false ? "projected" : "identical";
+}
+
+function buildCount() {
+  const caps = CAPABILITY_REGISTRY.length;
+  const tools = CAPABILITY_REGISTRY.filter((c) => c.mcp && c.mcp.tool).length;
+  return `machine-complete by design: ${caps} capabilities, ${tools} MCP tools.`;
+}
+
+function buildTable() {
+  const lines = [
+    "| Capability | CLI command | MCP tool | Core entry | Surface | Payload |",
+    "| --- | --- | --- | --- | --- | --- |"
+  ];
+  for (const cap of CAPABILITY_REGISTRY) {
+    lines.push(`| \`${cap.capability}\` | \`${cliCommand(cap)}\` | \`${mcpTool(cap)}\` | \`${cap.entry}\` | ${payload(cap) === "cli-only" || cap.surface !== "both" ? cap.surface : "both"} | ${payload(cap)} |`);
+  }
+  return lines.join("\n");
+}
+
+function buildCliOnly() {
+  const caps = CAPABILITY_REGISTRY.filter((c) => c.surface === "cli-only");
+  const head = `${numWord(caps.length)} ${caps.length === 1 ? "capability is" : "capabilities are"} CLI-only:`;
+  const bullets = caps.map((c) => `- \`${cliDisplay(c)}\` — ${c.reason || "(reason recorded in the registry)"}`);
+  return [head, "", ...bullets].join("\n");
+}
+
+function buildProjected() {
+  const caps = CAPABILITY_REGISTRY.filter((c) => c.surface === "both" && c.payloadIdentical === false);
+  const head = `${numWord(caps.length)} ${caps.length === 1 ? "capability is" : "capabilities are"} payload-divergent on purpose (\`projected\`):`;
+  const bullets = caps.map((c) => `- \`${c.capability}\` — ${c.reason || "(reason recorded in the registry)"}`);
+  return [head, "", ...bullets].join("\n");
+}
+
+const REGIONS = {
+  count: buildCount(),
+  table: buildTable(),
+  cliOnly: buildCliOnly(),
+  projected: buildProjected()
+};
+
+function replaceRegion(text, name, body) {
+  const begin = `<!-- gen:parity:${name} -->`;
+  const end = `<!-- /gen:parity:${name} -->`;
+  const re = new RegExp(`${begin}[\\s\\S]*?${end}`);
+  if (!re.test(text)) {
+    throw new Error(`marker ${begin} … ${end} not found in cli-mcp-parity.7.md — add the markers once, then re-run.`);
+  }
+  return text.replace(re, `${begin}\n${body}\n${end}`);
+}
+
+const original = fs.readFileSync(DOC, "utf8");
+let next = original;
+for (const [name, body] of Object.entries(REGIONS)) next = replaceRegion(next, name, body);
+
+if (CHECK) {
+  if (next !== original) {
+    process.stderr.write("gen-parity-doc: docs/cli-mcp-parity.7.md is OUT OF SYNC with the capability registry. Run `node scripts/gen-parity-doc.js` and commit.\n");
+    process.exit(1);
+  }
+  process.stdout.write("gen-parity-doc: cli-mcp-parity.7.md in sync with the registry.\n");
+} else {
+  if (next !== original) fs.writeFileSync(DOC, next);
+  process.stdout.write(`gen-parity-doc: ${next !== original ? "updated" : "unchanged"} — ${CAPABILITY_REGISTRY.length} capabilities, ${CAPABILITY_REGISTRY.filter((c) => c.mcp).length} MCP tools.\n`);
+}

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

package/scripts/release-flow.js

@@ -15,14 +15,28 @@
 // Modes:
 //   node release-flow.js [--check]                 gate + review, no mutation (default)
 //   node release-flow.js --cut --version x.y.z [--push]
-//                                                  also bump:version, commit verdict, tag, (push)
+//                                                  also bump:version, commit verdict, tag,
+//                                                  (push), and — when --push — create the
+//                                                  GitHub Release for the tag (idempotent;
+//                                                  opt out with --no-release)
+//   node release-flow.js --release --version x.y.z create-or-skip the GitHub Release for an
+//                                                  already-pushed tag (backfill); no gate/cut.
+//                                                  Fails closed if gh can't create it; add
+//                                                  --soft for best-effort (skip-not-fail).
 // Flags also accepted: --prev-tag <t>, --agent-command "...", --agent-model m, --dry-run
 //
-// Test seam: CW_RELEASE_FLOW_GATE_CMD overrides the deterministic gate command
-// (default: `bash <thisdir>/release-gate.sh`) so the smoke can exercise the
-// orchestration layer without re-running the full build/test suite.
+// 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
+//     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.
 //
-// Zero dependency: node + git only.
+// Zero dependency for the gated flow: node + git only. The GitHub Release step
+// additionally uses `gh` WHEN PRESENT; it lives ONLY in the human --cut --push /
+// --release paths (never a gate/CI path) and SKIPS — never fails the cut — when gh
+// is absent. A Release is distribution upside layered on the already-pushed tag and
+// the provenance-attested npm publish, not a correctness gate.
 
 const fs = require("node:fs");
 const path = require("node:path");
@@ -41,8 +55,11 @@ const val = (f) => {
   return i >= 0 ? argv[i + 1] : undefined;
 };
 const MODE_CUT = has("--cut");
+const MODE_RELEASE = has("--release");
 const DRY_RUN = has("--dry-run");
 const PUSH = has("--push");
+const NO_RELEASE = has("--no-release");
+const SOFT = has("--soft");
 const cutVersion = val("--version");
 const prevTagArg = val("--prev-tag");
 
@@ -223,6 +240,148 @@ function verifyVerdict(resultPath) {
   return cap;
 }
 
+// ---- 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
+// part of the node/git portability floor — it runs ONLY in the human --cut --push
+// / --release paths (never a gate/CI path), and an absent/erroring gh SKIPS with a
+// stderr note rather than failing the cut. Test seam: CW_RELEASE_FLOW_GH_CMD swaps
+// the `gh` binary for a stub (single executable token; always spawned shell:false).
+const GH_BIN = (process.env.CW_RELEASE_FLOW_GH_CMD || "gh").trim();
+
+function gh(args, opts = {}) {
+  // shell:false is AFTER the spread so no caller can override the red line.
+  return spawnSync(GH_BIN, args, { cwd: repoRoot, encoding: "utf8", ...opts, shell: false });
+}
+
+// gh present AND authenticated. Absent/unauth → false (caller skips, not fails).
+function ghReady() {
+  const v = gh(["--version"]);
+  if (v.error || v.status !== 0) return false;
+  const auth = gh(["auth", "status"]);
+  return !auth.error && auth.status === 0;
+}
+
+function repoSlug() {
+  const url = git(["remote", "get-url", "origin"]).out;
+  const m = url.match(/github\.com[:/]+([^/]+?)\/(.+?)(?:\.git)?$/);
+  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.
+function prevTagOf(version) {
+  return git(["describe", "--tags", "--abbrev=0", `v${version}^`]).out || "";
+}
+
+// Extract the `## <version>` section body from the CHANGELOG AS SHIPPED AT THE
+// TAG (git show), so the notes reflect what that tag actually carried.
+function changelogSection(version) {
+  const show = git(["show", `v${version}:CHANGELOG.md`]);
+  if (show.code !== 0 || !show.out) return "";
+  const lines = show.out.split(/\r?\n/);
+  const esc = version.replace(/\./g, "\\.");
+  const startRe = new RegExp(`^## \\[?${esc}\\b`);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) if (startRe.test(lines[i])) { start = i; break; }
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) if (/^## /.test(lines[i])) { end = i; break; }
+  return lines.slice(start + 1, end).join("\n").trim();
+}
+
+// Resolve the reviewed content commit + capability from the COMMITTED verdict at
+// the tag, mirroring release-gate.yml's HEAD-or-HEAD~1 tolerance: the verdict is
+// named for the reviewed content commit, which is the tag commit or its parent.
+function verdictForTag(version) {
+  const tagCommit = git(["rev-list", "-n1", `v${version}`]).out;
+  const parent = git(["rev-parse", `v${version}^`]).out;
+  for (const sha of [tagCommit, parent].filter(Boolean)) {
+    const rel = `.cw-release/review-${sha}.verdict`;
+    const show = git(["show", `v${version}:${rel}`]);
+    if (show.code === 0 && /^APPROVED /.test(show.out)) {
+      const cap = (show.out.split(/\r?\n/)[1] || "").trim();
+      return { contentSha: sha, capability: cap, verdictRel: rel };
+    }
+  }
+  return { contentSha: "", capability: "", verdictRel: "" };
+}
+
+// Pure: assemble the release-notes markdown from already-gathered inputs. No I/O,
+// so the smoke can assert the rendered notes (capability headline, CHANGELOG body,
+// provenance footer links) without touching git or the network.
+function buildReleaseNotes({ version, capability, changelog, slug, contentSha, verdictRel, prevTag }) {
+  const base = slug ? `https://github.com/${slug.owner}/${slug.repo}` : "";
+  const out = [];
+  if (capability) out.push(`> ${capability}`, "");
+  if (changelog) out.push(changelog, "");
+  out.push("---", "", "### Provenance & audit", "");
+  if (base && contentSha) out.push(`- **Reviewed commit:** [\`${contentSha.slice(0, 12)}\`](${base}/commit/${contentSha})`);
+  if (base && verdictRel) out.push(`- **Independent reviewer verdict (committed):** [\`${verdictRel}\`](${base}/blob/v${version}/${verdictRel})`);
+  if (base && prevTag) out.push(`- **Full diff:** [\`${prevTag}...v${version}\`](${base}/compare/${prevTag}...v${version})`);
+  out.push(`- **npm (provenance-attested):** [\`cool-workflow@${version}\`](https://www.npmjs.com/package/cool-workflow/v/${version})`);
+  // The gated-flow claim is made ONLY when a committed reviewer verdict actually
+  // backs it — otherwise the notes would assert a review that is not there
+  // (a false-green CW exists to prevent). Backfilled/ungated tags get an honest
+  // caveat instead.
+  if (verdictRel) {
+    out.push("", "_Released through the gated flow: deterministic gate → independent release-reviewer (verdict above) → provenance-attested npm publish._");
+  } else {
+    out.push("", "_Backfilled Release: no committed reviewer verdict was found at this tag, so these notes make no gated-review claim — integrity rests on the provenance-attested npm publish above._");
+  }
+  return `${out.join("\n").trim()}\n`;
+}
+
+// Create-or-skip the GitHub Release for an already-pushed tag. `required` (the
+// standalone --release mode) → an absent/failed gh is an ERROR; otherwise (the
+// cut finishing step) → skip-with-note and DO NOT fail the cut.
+function releaseGitHub(version, { required = false } = {}) {
+  if (!/^\d+\.\d+\.\d+$/.test(version || "")) die("release requires a x.y.z version");
+  const tag = `v${version}`;
+  if (git(["rev-parse", "-q", "--verify", `refs/tags/${tag}`]).code !== 0) {
+    const msg = `tag ${tag} not found locally — push the tag before creating its Release.`;
+    if (required) die(msg);
+    process.stderr.write(`release-flow: note: ${msg} skipping Release.\n`);
+    return false;
+  }
+  if (!ghReady()) {
+    const msg = `gh CLI not available/authenticated — cannot create GitHub Release ${tag}. Create it later: gh release create ${tag} --notes-file <notes> --verify-tag`;
+    if (required) die(msg);
+    process.stderr.write(`release-flow: note: ${msg}\n`);
+    return false;
+  }
+  if (gh(["release", "view", tag]).status === 0) {
+    say(`GitHub Release ${tag} already exists — skipping (idempotent).`);
+    return true;
+  }
+  const { contentSha, capability, verdictRel } = verdictForTag(version);
+  if (!verdictRel) {
+    process.stderr.write(`release-flow: note: no committed APPROVED verdict found at ${tag} — the Release notes will make NO gated-review claim (backfilling an ungated tag).\n`);
+  }
+  const notes = buildReleaseNotes({
+    version,
+    capability,
+    changelog: changelogSection(version),
+    slug: repoSlug(),
+    contentSha,
+    verdictRel,
+    prevTag: prevTagOf(version)
+  });
+  const notesPath = path.join(repoRoot, ".cw-release", `release-notes-${version}.md`);
+  fs.mkdirSync(path.dirname(notesPath), { recursive: true });
+  fs.writeFileSync(notesPath, notes);
+  if (DRY_RUN) { say(`[dry-run] would: gh release create ${tag} --notes-file ${notesPath} --verify-tag`); return true; }
+  const r = gh(["release", "create", tag, "--title", tag, "--notes-file", notesPath, "--verify-tag"], { stdio: "inherit" });
+  if (r.status !== 0) {
+    const msg = `gh release create failed for ${tag} — notes saved at ${notesPath}; the tag and npm publish are unaffected.`;
+    if (required) die(msg);
+    process.stderr.write(`release-flow: note: ${msg}\n`);
+    return false;
+  }
+  say(`created GitHub Release ${tag}.`);
+  return true;
+}
+
 // ---- 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");
@@ -241,11 +400,28 @@ function cut(resultPath, capability) {
     git(["push", "origin", `v${cutVersion}`]);
   }
   say(`tagged v${cutVersion}${PUSH ? " and pushed" : " (local only; push when ready)"}`);
+  // Finishing step: create the GitHub Release for the just-pushed tag. Only when
+  // pushed (the remote tag must exist) and not opted out; never fails the cut.
+  if (PUSH && !NO_RELEASE) releaseGitHub(cutVersion, { required: false });
 }
 
 // ---- main ------------------------------------------------------------------
 function main() {
   if (!HEAD) die("could not resolve HEAD");
+
+  // Standalone backfill: create-or-skip the GitHub Release for an already-pushed
+  // tag. No gate, no review, no mutation of tracked files — just GitHub.
+  if (MODE_RELEASE) {
+    const version = cutVersion;
+    if (!version || !/^\d+\.\d+\.\d+$/.test(version)) die("--release requires --version x.y.z");
+    // Default: fail closed if gh can't create the Release (the operator asked for
+    // it directly). --soft downgrades to best-effort (skip-not-fail), the same
+    // semantics the --cut --push finishing step uses.
+    const created = releaseGitHub(version, { required: !SOFT });
+    process.stdout.write(`${JSON.stringify({ ok: true, mode: "release", version, soft: SOFT, created }, null, 2)}\n`);
+    return;
+  }
+
   const markerDir = path.join(repoRoot, ".cw-release");
   fs.mkdirSync(markerDir, { recursive: true });
   const resultPath = path.join(markerDir, `review-${HEAD}.verdict`);

package/dist/verifier-registry.js

@@ -1,46 +0,0 @@
-"use strict";
-// Verifier Registry — open pluggability for commit-gate verifiers.
-//
-// BSD discipline (mechanism separate from policy):
-//  - MECHANISM: a Map<string, Verifier> with register + resolve.
-//  - POLICY: which verifiers exist is declared via registerVerifier() at load time.
-//  - FAIL CLOSED: unknown verifier id → named refusal.
-//  - COMPOSABLE: multiple verifiers can be chained; each runs in registration order.
-//
-// From v0.1.58: the built-in verifier (validateResultEnvelope, validateRunGates,
-// hasGroundedEvidence) remains the default. Registered verifiers run BEFORE the
-// default — they can block or add evidence but cannot override the default gate.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerVerifier = registerVerifier;
-exports.getVerifier = getVerifier;
-exports.listVerifiers = listVerifiers;
-exports.runAllVerifiers = runAllVerifiers;
-const _verifierRegistry = new Map();
-function registerVerifier(verifier) {
-    _verifierRegistry.set(verifier.id, verifier);
-}
-function getVerifier(id) {
-    return _verifierRegistry.get(id);
-}
-function listVerifiers() {
-    return [..._verifierRegistry.values()];
-}
-/** Run all registered verifiers against a run. Returns the aggregated verdict:
- *  "pass" if all pass, "block" if any block (first block reason wins). */
-async function runAllVerifiers(input) {
-    const reasons = [];
-    const evidence = [];
-    for (const verifier of _verifierRegistry.values()) {
-        const result = await verifier.verify(input);
-        if (result.evidence)
-            evidence.push(...result.evidence);
-        if (result.verdict === "block") {
-            reasons.push(`[${verifier.id}] ${result.reason || "blocked by verifier"}`);
-        }
-        else if (result.verdict === "warn") {
-            reasons.push(`[${verifier.id}] warn: ${result.reason || "warning"}`);
-        }
-    }
-    const blocked = reasons.some((r) => !r.includes("warn:"));
-    return { verdict: blocked ? "block" : "pass", reasons, evidence };
-}