cool-workflow 0.2.3 → 0.2.4

package/dist/wiring/capability-table/trust-ledger.js

@@ -6,7 +6,7 @@
 // retyped).
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_core_1 = require("./registry-core");
-const io_1 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
 // MILESTONE 8 (ledger, telemetry, trust-audit, tamper/bundle demos) CLI
 // bindings: ledger propose|review|verify|apply|list, telemetry verify,
 // audit verify, demo tamper|bundle, report bundle|verify-bundle. Handler
@@ -80,41 +80,41 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.list").mcp.handler = (args) =
     path: ["telemetry", "verify"],
     jsonMode: "flag",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]) || (0, io_1.optionalArg)(args.options.runId) || (0, io_1.optionalArg)(args.options.run), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]) || (0, cli_args_1.optionalArg)(args.options.runId) || (0, cli_args_1.optionalArg)(args.options.run), "run id");
         const result = loadTelemetryCli().telemetryVerifyCli(runId, args.options);
         return { json: result, text: loadTelemetryDemo().formatTelemetryVerify(result), exitCode: result.verified ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("telemetry.verify").mcp.handler = (args) => loadTelemetryCli().telemetryVerifyCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("telemetry.verify").mcp.handler = (args) => loadTelemetryCli().telemetryVerifyCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.verify", {
     path: ["audit", "verify"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const result = loadAuditCli().auditVerifyCli(runId, args.options);
         return { json: result, exitCode: result.verified ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.verify").mcp.handler = (args) => loadAuditCli().auditVerifyCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.verify").mcp.handler = (args) => loadAuditCli().auditVerifyCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.head", {
     path: ["audit", "head"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         return { json: loadAuditCli().auditHeadCli(runId, args.options) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.head").mcp.handler = (args) => loadAuditCli().auditHeadCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.head").mcp.handler = (args) => loadAuditCli().auditHeadCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("audit.repair", {
     path: ["audit", "repair"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const result = loadAuditCli().auditRepairCli(runId, args.options);
         return { json: result, exitCode: result.outcome === "refused" ? 1 : undefined };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.repair").mcp.handler = (args) => loadAuditCli().auditRepairCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.repair").mcp.handler = (args) => loadAuditCli().auditRepairCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.addCliOnlyCapability)("demo.tamper", "Prove tamper-evidence: build a signed telemetry ledger, forge it, watch verification fail offline.", {
     path: ["demo", "tamper"],
     jsonMode: "flag",
@@ -135,17 +135,17 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("audit.repair").mcp.handler = (args)
     path: ["report", "bundle"],
     jsonMode: "default",
     handler: (args) => {
-        const runId = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id");
+        const runId = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id");
         const result = loadReportCli().reportBundleCli(runId, args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("report.bundle").mcp.handler = (args) => loadReportCli().reportBundleCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("report.bundle").mcp.handler = (args) => loadReportCli().reportBundleCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 (0, registry_core_1.attachCliBinding)("report.verify-bundle", {
     path: ["report", "verify-bundle"],
     jsonMode: "flag",
     handler: (args) => {
-        const archivePath = (0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "bundle path");
+        const archivePath = (0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "bundle path");
         const reportCli = loadReportCli();
         const result = reportCli.reportVerifyBundleCli({ ...args.options, archive: archivePath });
         return { json: result, text: reportCli.formatReportVerifyBundle(result), exitCode: result.ok ? undefined : 1 };

package/dist/wiring/capability-table/workflow-apps.js

@@ -6,7 +6,7 @@
 // sed, not retyped).
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_core_1 = require("./registry-core");
-const io_1 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
 // This whole module is required unconditionally at startup for EVERY
 // command (see wiring/capability-table/index.ts) — loading `next`'s and
 // `app.run`'s shell modules lazily, inside the handler that actually
@@ -44,24 +44,24 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.list").mcp.handler = () => loadW
 (0, registry_core_1.attachCliBinding)("app.show", {
     path: ["app", "show"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadWorkflowAppLoader().showWorkflowApp((0, io_1.required)(args.positionals[0], "workflow app id")) }),
+    handler: (args) => ({ json: loadWorkflowAppLoader().showWorkflowApp((0, cli_args_1.required)(args.positionals[0], "workflow app id")) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("app.show").mcp.handler = (args) => loadWorkflowAppLoader().showWorkflowApp((0, io_1.required)((0, io_1.optionalArg)(args.appId), "workflow app id"));
+registry_core_1.REGISTRY_BY_CAPABILITY.get("app.show").mcp.handler = (args) => loadWorkflowAppLoader().showWorkflowApp((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.appId), "workflow app id"));
 (0, registry_core_1.attachCliBinding)("app.validate", {
     path: ["app", "validate"],
     jsonMode: "default",
     handler: (args) => {
-        const result = loadWorkflowAppLoader().validateWorkflowAppTarget((0, io_1.required)(args.positionals[0], "workflow app path or id"));
+        const result = loadWorkflowAppLoader().validateWorkflowAppTarget((0, cli_args_1.required)(args.positionals[0], "workflow app path or id"));
         return { json: result, exitCode: result.valid ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("app.validate").mcp.handler = (args) => loadWorkflowAppLoader().validateWorkflowAppTarget((0, io_1.required)((0, io_1.optionalArg)(args.target ?? args.appId), "workflow app path or id"));
+registry_core_1.REGISTRY_BY_CAPABILITY.get("app.validate").mcp.handler = (args) => loadWorkflowAppLoader().validateWorkflowAppTarget((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.target ?? args.appId), "workflow app path or id"));
 (0, registry_core_1.attachCliBinding)("app.init", {
     path: ["app", "init"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadWorkflowAppLoader().initWorkflowApp((0, io_1.required)(args.positionals[0], "app id"), args.options) }),
+    handler: (args) => ({ json: loadWorkflowAppLoader().initWorkflowApp((0, cli_args_1.required)(args.positionals[0], "app id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("app.init").mcp.handler = (args) => loadWorkflowAppLoader().initWorkflowApp((0, io_1.required)((0, io_1.optionalArg)(args.appId), "app id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("app.init").mcp.handler = (args) => loadWorkflowAppLoader().initWorkflowApp((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.appId), "app id"), args);
 // `cw init <id>` — the standalone scaffold verb. v2 folds `init` into
 // `app.init` (the old build's legacy `.workflow.js` scaffold is gone), so
 // both surfaces route through initWorkflowApp, same as `cw app init`. The
@@ -71,15 +71,15 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.init").mcp.handler = (args) => l
 (0, registry_core_1.attachCliBinding)("init", {
     path: ["init"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadWorkflowAppLoader().initWorkflowApp((0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "workflow id"), args.options) }),
+    handler: (args) => ({ json: loadWorkflowAppLoader().initWorkflowApp((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "workflow id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("init").mcp.handler = (args) => loadWorkflowAppLoader().initWorkflowApp((0, io_1.required)((0, io_1.optionalArg)(args.workflowId ?? args.appId), "workflow id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("init").mcp.handler = (args) => loadWorkflowAppLoader().initWorkflowApp((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.workflowId ?? args.appId), "workflow id"), args);
 (0, registry_core_1.attachCliBinding)("app.package", {
     path: ["app", "package"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadWorkflowAppLoader().packageWorkflowApp((0, io_1.required)(args.positionals[0], "app id"), args.options) }),
+    handler: (args) => ({ json: loadWorkflowAppLoader().packageWorkflowApp((0, cli_args_1.required)(args.positionals[0], "app id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("app.package").mcp.handler = (args) => loadWorkflowAppLoader().packageWorkflowApp((0, io_1.required)((0, io_1.optionalArg)(args.appId), "app id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("app.package").mcp.handler = (args) => loadWorkflowAppLoader().packageWorkflowApp((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.appId), "app id"), args);
 // `cw app run <app-id>` — plan+drive+report an app in one call. 2-token
 // cli.path found before the ["app"] usage catch-all; `appRunCli` reads the
 // app id from `appId`, so the first positional after "run" is forwarded as
@@ -87,7 +87,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.package").mcp.handler = (args) =
 (0, registry_core_1.attachCliBinding)("app.run", {
     path: ["app", "run"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadAppRunCli().appRunCli({ ...args.options, appId: (0, io_1.required)(args.positionals[0], "app id") }) }),
+    handler: (args) => ({ json: loadAppRunCli().appRunCli({ ...args.options, appId: (0, cli_args_1.required)(args.positionals[0], "app id") }) }),
 });
 // A 1-token `["app"]` row that exists ONLY to own the fixed usage string
 // for an unrecognized `app` subcommand (`app run` is not yet CLI-wired at
@@ -329,7 +329,7 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.package").mcp.handler = (args) =
     path: ["info"],
     jsonMode: "flag",
     handler: (args) => {
-        const appId = (0, io_1.required)(args.positionals[0], "workflow app id");
+        const appId = (0, cli_args_1.required)(args.positionals[0], "workflow app id");
         const data = loadWorkflowAppLoader().showWorkflowApp(appId);
         return { json: data, text: `${(0, help_1.formatInfo)(appId, data)}\n` };
     },
@@ -351,9 +351,9 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.package").mcp.handler = (args) =
 (0, registry_core_1.attachCliBinding)("next", {
     path: ["next"],
     jsonMode: "default",
-    handler: (args) => ({ json: loadStateCli().nextCli((0, io_1.required)((0, io_1.optionalArg)(args.positionals[0]), "run id"), args.options) }),
+    handler: (args) => ({ json: loadStateCli().nextCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.positionals[0]), "run id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("next").mcp.handler = (args) => loadStateCli().nextCli((0, io_1.required)((0, io_1.optionalArg)(args.runId), "run id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("next").mcp.handler = (args) => loadStateCli().nextCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.runId), "run id"), args);
 // `ledger.propose`/`.review`/`.verify`/`.apply`/`.list` are documented
 // payload-probe opt-outs in the old build (each mints a fresh timestamped/
 // digested entry, or reads args that arrive by --file/stdin on the CLI vs

package/docs/agent-delegation-drive.7.md

@@ -421,3 +421,5 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/cli-mcp-parity.7.md

@@ -429,19 +429,22 @@ Parity is checked by `scripts/parity-check.js --check`, run by
 the registry, lists the live CLI commands and MCP tools, and fails closed on any
 of the rules above.
 
-The CLI dispatcher (`src/cli/command-surface.ts`) is being decomposed out of one
-large `switch` into per-command handler modules under `src/cli/handlers/`
-(`handle<Group>(args, runner)`), with `command-surface.ts` left as the thin
-router; shared helpers live in `src/cli/io.ts` (arg/JSON) and `src/cli/format.ts`
-(render). Carved so far: `workbench`, `clones`, `audit`, `worker`, `schedule`, `routine`,
-`sched`, `registry`, `queue`, `history`, `report`, `operator`, `graph`,
-`topology`, `summary`, `multi-agent`, `run`, `approve`, `reject`, `comment`,
-`handoff`, `review`, `blackboard`, `coordinator`, `eval`, `node`, `gc`,
-`telemetry`, `demo`, `feedback`, `metrics`, `migration`, `sandbox`, `backend`,
-`contract`, `candidate`. This is a pure code-move
-— the command surface is unchanged — and the parity scanner reads
-`dist/cli/handlers/*` so a subcommand `case` in a handler module still counts as a
-live CLI token.
+The CLI dispatch surface is table-driven, not a hand-kept `switch`. The source
+tree is small: `src/cli/entry.ts` (process entry), `src/cli/parseargv.ts`
+(argv reading), `src/cli/dispatch.ts` (the one dispatcher), and `src/cli/io.ts`
+(output helpers: `printJson`, `styledHelp`). `dispatch(args)` looks the parsed
+command up in the capability table (`src/core/capability-table.ts`, put
+together from the slices under `src/wiring/capability-table/`) and runs that
+row's `cli.handler` — a new capability is a new table row, never a new `case`.
+The shared arg helpers (`required`, `optionalArg`, `wantsJson`) live in
+`src/core/util/cli-args.ts`, a pure module used by the CLI and MCP sides of
+every wiring slice; they were moved out of `cli/io.ts` because the purity
+gate's layer rule says `wiring/` may not take imports from `cli/`. The parity
+scanner works the same way: `cliDispatchTokens()` gets the live token list
+straight from the registry's CLI capabilities (`cli.caseTokens` when a row
+names more than one first token, else `cli.path`), then makes sure each
+declared path resolves through the live dispatcher — there is no grep over
+built dispatch source.
 
 `test/cli-mcp-parity-smoke.js` proves the contract from end to end. It checks
 registry ⇄ CLI ⇄ MCP coverage (every declared capability is found on its declared
@@ -638,3 +641,5 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/contract-migration-tooling.7.md

@@ -181,3 +181,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/control-plane-scheduling.7.md

@@ -165,3 +165,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/durable-state-and-locking.7.md

@@ -184,3 +184,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/evidence-adoption-reasoning-chain.7.md

@@ -325,3 +325,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/execution-backends.7.md

@@ -355,3 +355,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -331,3 +331,5 @@ The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/multi-agent-eval-replay-harness.7.md

@@ -357,3 +357,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/multi-agent-operator-ux.7.md

@@ -369,3 +369,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/node-snapshot-diff-replay.7.md

@@ -190,3 +190,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/observability-cost-accounting.7.md

@@ -250,3 +250,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-07-10 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-07-11 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.2.3`
-- Source modules: `148`
+- Version: `0.2.4`
+- Source modules: `149`
 - Workflow apps: `8`
 - Docs: `62`
-- Smoke tests: `201`
+- Smoke tests: `204`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -118,6 +118,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [core/types/boundary.ts](../src/core/types/boundary.ts)
 - [core/types/execution-backend.ts](../src/core/types/execution-backend.ts)
 - [core/types/observability.ts](../src/core/types/observability.ts)
+- [core/util/cli-args.ts](../src/core/util/cli-args.ts)
 - [core/util/collate.ts](../src/core/util/collate.ts)
 - [core/util/numeric-flag.ts](../src/core/util/numeric-flag.ts)
 - [mcp/dispatch.ts](../src/mcp/dispatch.ts)
@@ -284,6 +285,7 @@ multi-agent host -> topology -> blackboard/coordinator
 Smoke tests mirror the public contracts. The high-signal suites are:
 
 - [agent-backend-concurrent-user-env-smoke.js](../test/agent-backend-concurrent-user-env-smoke.js)
+- [agent-backend-sandbox-deny-smoke.js](../test/agent-backend-sandbox-deny-smoke.js)
 - [agent-backend-user-env-smoke.js](../test/agent-backend-user-env-smoke.js)
 - [agent-config-atomic-write-smoke.js](../test/agent-config-atomic-write-smoke.js)
 - [agent-delegation-drive-smoke.js](../test/agent-delegation-drive-smoke.js)
@@ -342,6 +344,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [dogfood-release-smoke.js](../test/dogfood-release-smoke.js)
 - [drive-async-real-signal-smoke.js](../test/drive-async-real-signal-smoke.js)
 - [drive-concurrency-flag-smoke.js](../test/drive-concurrency-flag-smoke.js)
+- [drive-concurrent-round-sigkill-smoke.js](../test/drive-concurrent-round-sigkill-smoke.js)
 - [drive-exhaustion-blocked-smoke.js](../test/drive-exhaustion-blocked-smoke.js)
 - [drive-round-cache-serial-smoke.js](../test/drive-round-cache-serial-smoke.js)
 - [durable-atomic-write-smoke.js](../test/durable-atomic-write-smoke.js)
@@ -418,6 +421,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [release-check-skip-smoke.js](../test/release-check-skip-smoke.js)
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-smoke.js)
+- [release-oneclick-smoke.js](../test/release-oneclick-smoke.js)
 - [release-pipeline-hygiene-smoke.js](../test/release-pipeline-hygiene-smoke.js)
 - [release-tooling-smoke.js](../test/release-tooling-smoke.js)
 - [remote-link-archive-smoke.js](../test/remote-link-archive-smoke.js)

package/docs/real-execution-backends.7.md

@@ -197,3 +197,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/release-and-migration.7.md

@@ -337,3 +337,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/release-tooling.7.md

@@ -170,14 +170,32 @@ model you set up does the review. CW starts the agent argv-style (`shell:false`)
 takes on the agent's own credentials, and pulls in no model SDK — the red line.
 
 ```bash
+# the operator's one-command release (scripts/release-oneclick.js — preflight,
+# gated cut, tag-only push, CI wait, npm confirmation, verdict-record PR):
+npm run release -- 0.2.4
 # check only (gate + independent review, no mutation):
 node plugins/cool-workflow/scripts/release-flow.js --check
 # cut a tag once review is green (when --push, also creates the GitHub Release):
 node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 [--push] [--no-release]
+# run ONLY the cut's fail-fast preflight (seconds; used by release-oneclick.js):
+node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 --push --preflight-only
 # backfill / re-create the GitHub Release for an already-pushed tag (no gate/cut):
 node plugins/cool-workflow/scripts/release-flow.js --release --version 0.1.77 [--soft]
 ```
 
+A `--cut` starts with a fail-fast **preflight** (added after the v0.2.3 cut,
+where each of these fired only AFTER the gate/vendor/reviewer had already
+spent real time and tokens): the version flag, the signing key (present AND
+matching the committed `verdict-signing.pub` — once that pubkey is in the
+repo, an unsigned cut is refused up front instead of failing later in CI),
+no pre-existing `vX.Y.Z` tag (local or on origin), a `## X.Y.Z` CHANGELOG
+section, a clean tracked tree, and — for `--push` — HEAD equal to the
+`origin/main` tip (`--allow-stale-head` skips that one check for a
+deliberate re-cut). The push at the end moves ONLY `refs/tags/vX.Y.Z`: the
+verdict commit is a one-hop leaf on the reviewed commit, reachable through
+the tag alone, so main's branch protection is never in the path and no
+stray remote branch is created.
+
 The per-platform difference is config, not code — set the reviewer agent here:
 
 | Platform | Reviewer config |
@@ -300,3 +318,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/run-registry-control-plane.7.md

@@ -480,3 +480,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/run-retention-reclamation.7.md

@@ -107,6 +107,22 @@ scratch dir) is **re-pointed** to the retained `results/<task-id>.md` copy, and
 result-node snapshot is shown to stay `valid` (not `absent`) — so no surviving
 node points to a freed path. Opt out with `--keep-scratch`.
 
+## Commit snapshots — never reconstructable, always downgrades to verify-only
+
+`commitState` embeds the FULL run into `commits/<id>.json` on every commit, so
+these grow unbounded in both count and per-file size with no cap. Reclaiming them
+frees the run's superseded, non-`verifierGated` "checkpoint" commit snapshots —
+the run's LATEST commit and every `verifierGated` commit (the actual
+audit-significant milestones) are always kept. `run.commits`' own lightweight
+metadata (id, `verifierGated`, evidence digests, acceptance rationale — everything
+`extractSkeleton` seals) lives in `state.json`, not the snapshot file, so it stays
+fully intact and queryable regardless. Unlike a node snapshot, a commit snapshot is
+a genuine point-in-time capture with no `ReconstructionRecipe` — reclaiming even
+one downgrades capability to `verify-only`, never `re-runnable-by-reconstruction`.
+Each reclaimed commit's own `StateNode` had its `snapshot` artifact stripped (not
+re-pointed — there is no retained alternative) before the free, so `prepareFree`'s
+dangling-reference proof covers this kind too. Opt out with `--keep-commits`.
+
 ## Orphan runs — a second pure-scratch case, OUTSIDE this transaction
 
 A run directory can also be pure scratch a different way: a process killed or
@@ -131,8 +147,8 @@ class of run; it is left `retained` indefinitely rather than guessed at.
 ## CLI
 
 ```
-cw gc plan   [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--scope repo|home] [--json]
-cw gc run    [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--limit N] [--actor NAME] [--json]
+cw gc plan   [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--keep-commits] [--scope repo|home] [--json]
+cw gc run    [run-id] [--reclaimAfterArchiveDays N] [--keep-scratch] [--keep-snapshots] [--keep-commits] [--limit N] [--actor NAME] [--json]
 cw gc verify <run-id> [--scope repo|home] [--json]
 ```
 
@@ -163,7 +179,8 @@ rule: only ISO timestamps may be now-derived.
 
 Retention/reclamation thresholds extend `RunRegistryPolicy` (alongside
 `archiveOlderThanDays`), never a new policy file: `reclaimAfterArchiveDays`,
-`keepSnapshots`, `keepScratch`, `reclaimStates`, `maxReclaimRuns`, `maxReclaimBytes`.
+`keepSnapshots`, `keepScratch`, `keepCommits`, `reclaimStates`, `maxReclaimRuns`,
+`maxReclaimBytes`.
 Back-compatible defaults reclaim nothing; pre-v0.1.39 runs load unchanged.
 
 ## Compatibility
@@ -269,3 +286,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/state-explosion-management.7.md

@@ -326,3 +326,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/team-collaboration.7.md

@@ -262,3 +262,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/trust-audit-anchor.7.md

@@ -69,3 +69,5 @@ security-trust-hardening(7), cli-mcp-parity(7), report-verifiable-bundle(7)
 0.2.2
 
 0.2.3
+
+0.2.4

package/docs/web-desktop-workbench.7.md

@@ -280,3 +280,5 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4

package/manifest/plugin.manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -63,6 +63,7 @@
     "onramp:check": "node scripts/onramp-check.js --check",
     "version:sync": "node scripts/version-sync-check.js",
     "release:check": "node scripts/release-check.js",
+    "release": "node scripts/release-oneclick.js",
     "test": "node dist/cli.js version > /dev/null && node test/run-all.js --fast --sample 35",
     "test:full": "node dist/cli.js version > /dev/null && node test/run-all.js --sample 55",
     "test:gate": "node dist/cli.js version > /dev/null && node test/run-all.js",

package/scripts/block-unapproved-tag.sh

@@ -30,16 +30,31 @@ fi
 
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
 SHA="$(git -C "$REPO_ROOT" rev-parse HEAD)"
-GATE="$REPO_ROOT/.cw-release/gate-$SHA.ok"
-VERDICT="$REPO_ROOT/.cw-release/review-$SHA.verdict"
+# cut() commits the verdict ON TOP of the reviewed commit, so at tag time the
+# verdict filename is keyed on HEAD~1's sha, not HEAD's — the same
+# HEAD-or-HEAD~1 tolerance release-gate.yml uses. Without this, a manual
+# retag of a cut-produced commit was always blocked (v0.2.3 recovery).
+PARENT="$(git -C "$REPO_ROOT" rev-parse HEAD~1 2>/dev/null || echo none)"
+GATE=""
+VERDICT=""
+for C in "$SHA" "$PARENT"; do
+  [[ "$C" == "none" ]] && continue
+  if [[ -f "$REPO_ROOT/.cw-release/review-$C.verdict" ]]; then
+    GATE="$REPO_ROOT/.cw-release/gate-$C.ok"
+    VERDICT="$REPO_ROOT/.cw-release/review-$C.verdict"
+    break
+  fi
+done
+[[ -z "$VERDICT" ]] && VERDICT="$REPO_ROOT/.cw-release/review-$SHA.verdict"
+[[ -z "$GATE" ]] && GATE="$REPO_ROOT/.cw-release/gate-$SHA.ok"
 
 if [[ ! -f "$GATE" ]]; then
-  echo "BLOCKED: no release-gate pass for HEAD $SHA. Run plugins/cool-workflow/scripts/release-gate.sh first. Tagging without a green gate is forbidden." >&2
+  echo "BLOCKED: no release-gate pass for HEAD $SHA (or its parent). Run plugins/cool-workflow/scripts/release-gate.sh first. Tagging without a green gate is forbidden." >&2
   exit 2
 fi
 
 if [[ ! -f "$VERDICT" ]] || ! grep -q '^APPROVED' "$VERDICT"; then
-  echo "BLOCKED: no APPROVED verdict from the release-reviewer agent for HEAD $SHA. Invoke the 'release-reviewer' subagent and obtain approval. Do not write the verdict file yourself — that is a gaming attempt and will be flagged in CI." >&2
+  echo "BLOCKED: no APPROVED verdict from the release-reviewer agent for HEAD $SHA (or its parent). Invoke the 'release-reviewer' subagent and obtain approval. Do not write the verdict file yourself — that is a gaming attempt and will be flagged in CI." >&2
   exit 2
 fi
 

package/scripts/bump-version.js

@@ -77,12 +77,18 @@ function main() {
 
   const current = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8")).version;
   if (next === current) {
-    // Idempotent: re-running the bump for the same version is a no-op (exit 0)
-    // rather than a hard fail. Required by `release-flow --cut --version X` when
-    // the bump was already landed in a prior PR (e.g. a release-prep PR that
-    // committed the version surfaces, then a follow-up fix on top — cut should
-    // still be able to commit the verdict and tag without re-bumping).
-    process.stdout.write(`bump:version: already at ${next}, no surfaces to update\n`);
+    // Idempotent for the STRUCTURED surfaces: re-running the bump for the same
+    // version skips the writes (exit 0) rather than hard-failing. Required by
+    // `release-flow --cut --version X` when the bump was already landed in a
+    // prior PR — cut should still be able to commit the verdict and tag
+    // without re-bumping. But the CONTENT-surface gate must still run: the
+    // v0.2.3 cut hit exactly this hole — package.json was already bumped, so
+    // this early-exit skipped the content check entirely and `--content`
+    // never filled the missing docs/RELEASE references. Same-version reruns
+    // now gate (or fill) content exactly like a fresh bump does.
+    process.stdout.write(`bump:version: structured surfaces already at ${next}\n`);
+    const sameVersionContent = handleContentSurfaces(current, next);
+    if (!sameVersionContent.ok) fail(sameVersionContent.error);
     process.exit(0);
   }
 
@@ -161,9 +167,11 @@ function main() {
   // and a RegExp string (`0\\.1\\.32`, from `new RegExp(\`...@0\\.1\\.32\`)`).
   // A plain replace silently misses the escaped forms — the exact "escaped-dot"
   // surface that fails version:sync mid-release. Replace all three, most-escaped
-  // first so the forms can never overlap.
-  const esc1 = (v) => v.replace(/\./g, "\\.");
-  const esc2 = (v) => v.replace(/\./g, "\\\\.");
+  // first so the forms can never overlap. No regex is ever built from these —
+  // the forms feed the plain split/join TEXT replacement below (which is also
+  // why split/join, not a regex-escape-shaped replace, builds them).
+  const esc1 = (v) => v.split(".").join("\\.");
+  const esc2 = (v) => v.split(".").join("\\\\.");
   const forms = [[esc2(current), esc2(next)], [esc1(current), esc1(next)], [current, next]];
   for (const rel of targeted) {
     const abs = path.join(pluginRoot, rel);
@@ -261,7 +269,16 @@ function handleContentSurfaces(current, next) {
     const abs = path.join(repoRoot, rel);
     if (!fs.existsSync(abs)) { missing.push({ rel, reason: "file missing" }); continue; }
     const text = fs.readFileSync(abs, "utf8");
-    if (!text.includes(needle)) missing.push({ rel, needle });
+    // Own-line match, not a plain substring: every entry here is a line this
+    // function itself appends (`\n${needle}\n`) when missing, and a bare
+    // version number can otherwise coincidentally already appear in the
+    // doc's unrelated prose (an example command, a cross-reference) without
+    // the real version-history line actually being present. See
+    // version-sync-check.js's checkIncludesOwnLine for the matching CI-side
+    // gate (found live: v0.2.4's bump masked a real missing footer line in
+    // release-tooling.7.md this way).
+    const hasOwnLine = text.split("\n").some((line) => line.trim() === needle);
+    if (!hasOwnLine) missing.push({ rel, needle });
   }
 
   if (missing.length === 0) {