cool-workflow 0.2.3 → 0.2.5

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
@@ -18,10 +18,13 @@ const io_1 = require("../../cli/io");
 // cli/parseargv.ts) even though dispatchTable now handles it as a real
 // row — a known, preserved wart.
 // ---------------------------------------------------------------------
-const ledger_cli_1 = require("../../shell/ledger-cli");
 // This file is required at startup for every command. Loading these shell
 // modules only when their handler runs, not at import time, keeps that
-// load cost out of commands that never touch telemetry/audit/demo/report.
+// load cost out of commands that never touch ledger/telemetry/audit/demo/
+// report.
+function loadLedgerCli() {
+    return require("../../shell/ledger-cli");
+}
 function loadTelemetryCli() {
     return require("../../shell/telemetry-cli");
 }
@@ -40,81 +43,120 @@ function loadReportCli() {
 (0, registry_core_1.attachCliBinding)("ledger.propose", {
     path: ["ledger", "propose"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, ledger_cli_1.ledgerProposeCli)(args.options) }),
+    handler: (args) => ({ json: loadLedgerCli().ledgerProposeCli(args.options) }),
+    // UI/UX fix: `cw help ledger` used to list only the one-line summary for
+    // each row, so a first-run user had no way to learn these flags without
+    // reading source. Real flag names verified against ledgerProposeCli's
+    // required()/stringOption() calls above.
+    flags: [
+        { name: "--from AGENT/REPO", summary: "Who is making the change." },
+        { name: "--to AGENT/REPO", summary: "Who should get the change." },
+        { name: "--title TEXT", summary: "A short name for the change." },
+        { name: "--rationale TEXT", summary: "Why the change should happen." },
+        { name: "--files LIST", summary: "The files the change touches, as a comma list." },
+        { name: "--diff PATCH", summary: "The change as one diff file." },
+    ],
+    // ledgerProposeCli reads exactly from/to/title/rationale/files/diff
+    // (shell/ledger-cli.ts) — the list above is complete, so the dispatcher
+    // may warn about an unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.propose").mcp.handler = (args) => (0, ledger_cli_1.ledgerProposeMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.propose").mcp.handler = (args) => loadLedgerCli().ledgerProposeMcp(args);
 (0, registry_core_1.attachCliBinding)("ledger.review", {
     path: ["ledger", "review"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, ledger_cli_1.ledgerReviewCli)(args.options) }),
+    handler: (args) => ({ json: loadLedgerCli().ledgerReviewCli(args.options) }),
+    // Real flag names verified against ledgerReviewCli's required()/
+    // stringOption() calls above — NOT the same flag set as ledger propose
+    // (this row needs --target/--verdict/--findings, not --title/
+    // --rationale/--diff).
+    flags: [
+        { name: "--from AGENT/REPO", summary: "Who is doing the review." },
+        { name: "--to AGENT/REPO", summary: "Who made the change being reviewed." },
+        { name: "--target ID", summary: "The id of the proposal or PR to review." },
+        { name: "--verdict approved|rejected", summary: "The result of the review." },
+        { name: "--findings TEXT", summary: "Notes on what the review found." },
+    ],
+    // ledgerReviewCli reads exactly from/to/target/verdict/findings
+    // (shell/ledger-cli.ts) — the list above is complete, so the dispatcher
+    // may warn about an unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.review").mcp.handler = (args) => (0, ledger_cli_1.ledgerReviewMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.review").mcp.handler = (args) => loadLedgerCli().ledgerReviewMcp(args);
 (0, registry_core_1.attachCliBinding)("ledger.verify", {
     path: ["ledger", "verify"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerVerifyCli)(args.options);
+        const result = loadLedgerCli().ledgerVerifyCli(args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.verify").mcp.handler = (args) => (0, ledger_cli_1.ledgerVerifyEntry)(args.entry);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.verify").mcp.handler = (args) => loadLedgerCli().ledgerVerifyEntry(args.entry);
 (0, registry_core_1.attachCliBinding)("ledger.apply", {
     path: ["ledger", "apply"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerApplyCli)(args.options);
+        const result = loadLedgerCli().ledgerApplyCli(args.options);
         return { json: result, exitCode: result.ok ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.apply").mcp.handler = (args) => (0, ledger_cli_1.ledgerApplyEntry)(args.entry);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.apply").mcp.handler = (args) => loadLedgerCli().ledgerApplyEntry(args.entry);
 (0, registry_core_1.attachCliBinding)("ledger.list", {
     path: ["ledger", "list"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, ledger_cli_1.ledgerListCli)(args.options);
+        const result = loadLedgerCli().ledgerListCli(args.options);
         return { json: result, exitCode: result.allOk ? undefined : 1 };
     },
+    // UI/UX fix: `--dir` here named the ledger directory, while the global
+    // front door (cli/entry.ts) treats `--dir` as an alias of `--repo` for
+    // every command — one flag, two meanings. `--ledger-dir` is the
+    // unambiguous spelling; `--dir` stays as the legacy alias, byte-compat.
+    flags: [
+        { name: "--ledger-dir DIR", summary: "The ledger directory to read. Give it more than once to union-verify mirrors." },
+        { name: "--dir DIR", summary: "Old name for --ledger-dir (also the global --repo alias; kept working)." },
+    ],
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.list").mcp.handler = (args) => (0, ledger_cli_1.ledgerListMcp)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("ledger.list").mcp.handler = (args) => loadLedgerCli().ledgerListMcp(args);
 (0, registry_core_1.attachCliBinding)("telemetry.verify", {
     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 +177,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

@@ -125,6 +125,19 @@ exactly one fixed step (injected `now`); bare `--drive` runs to the end or to a
 parked/blocked stop. `run drive <run-id>` (no `--step`) is the read-only, fixed
 preview of the next step.
 
+## Concurrent rounds (`--concurrency N`)
+
+`--drive --concurrency N` (or an auto-width parallel phase) runs a whole round's
+tasks in ONE window instead of one at a time. CW dispatches the round's tasks,
+collects every agent outcome concurrently, then settles + accepts them in
+DETERMINISTIC batch (task-id) order — so the wall-clock drops but the recorded
+state, reports, and exit codes are byte-identical to a serial run. Both agent
+shapes get real concurrency: a **CLI-binary** agent (`CW_AGENT_COMMAND`) runs
+all children at once through the batch delegate child, and an **HTTP-endpoint**
+agent (`CW_AGENT_ENDPOINT`) POSTs all N delegations at once through the HTTP
+batch delegate child. A cache-hit task still settles on the serial path inside
+the same round. An unconfigured agent still refuses (it is never a fake pass).
+
 ## Fail closed — probe vs refusal vs park
 
 - **Probe.** `backend probe agent` reports `readiness: "ready"` iff a
@@ -421,3 +434,7 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

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

@@ -74,6 +74,29 @@ show/validate/apply/summary/graph, sandbox show/validate/choose/resolve, state
 summary refresh/show, `plan`, `approve`, `reject`, `comment.add`, `handoff`, and
 `review.policy`.
 
+## MCP Tool Hints and Version Negotiation
+
+A `tools/list` entry may carry the standard MCP `annotations` field with
+two behavior hints:
+
+- `readOnlyHint: true` — the tool only reads; it makes no change on disk.
+- `destructiveHint: true` (with `readOnlyHint: false`) — the tool deletes
+  stored data (the gc / delete sweeps: `cw_gc_run`, `cw_orphans_gc`,
+  `cw_clones_gc`, `cw_schedule_delete`, `cw_routine_delete`).
+
+The hints come from one side table (`MCP_TOOL_ANNOTATIONS` in
+`src/core/capability-data.ts`), and a tool goes in only after its handler
+was read and checked by hand — a wrong "read-only" mark on a writing tool
+would be a safety bug, so a tool we are not certain about carries no
+`annotations` field at all. Absent beats wrong. The field is additive: a
+client that does not know it simply does not read it.
+
+The MCP `initialize` reply also negotiates the protocol version now: a
+client that asks for a supported version gets that version echoed back,
+and any other request falls back to the newest supported entry (see
+`SUPPORTED_PROTOCOL_VERSIONS` in `src/mcp/server.ts`). With today's
+one-entry list the reply bytes are unchanged.
+
 ## The Parity Matrix
 
 The matrix below is made from the live registry — one row per capability,
@@ -429,19 +452,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 +664,7 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

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

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

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

@@ -66,6 +66,40 @@ Additive: `RunQueueEntry` gets the optional `attempts`/`leaseId`/`leaseExpiresAt
 `queue add|list|drain|show` verbs that are already there do not change. No new database, no
 daemon-owned state.
 
+## Scheduled Tasks In Practice
+
+CW scheduled tasks give looping prompts, cron-like schedules, one-shot
+reminders, expiration, jitter, and clear completion. Schedules live in
+`.cw/schedules/tasks.json`.
+
+```bash
+# a /loop-ready schedule (cw loop is the short form of schedule create --kind loop)
+cw loop --intervalMinutes 30 --prompt "Check this workflow and continue if work is due."
+
+# a cron schedule
+cw schedule create --kind cron --cron "*/15 * * * *" --prompt "Run the due workflow scan."
+
+# a one-shot reminder
+cw schedule create --kind reminder --delayMinutes 60 --prompt "Remind me to inspect the report."
+
+# list, inspect, and manage
+cw schedule list
+cw schedule due
+cw schedule complete <schedule-id>
+cw schedule pause <schedule-id> / resume <schedule-id> / run-now <schedule-id>
+cw schedule history <schedule-id>
+cw schedule delete <schedule-id>
+
+# the local daemon: one sweep, or a loop
+cw schedule daemon --once
+cw schedule daemon --intervalSeconds 60
+```
+
+Notes: time is measured to the minute; expiration defaults to 7 days;
+`jitterSeconds` can put space between runs. CW does not start the daemon by
+default — use `schedule daemon`, cron, or another overseer to call
+`schedule due` and run due prompts.
+
 ## See Also
 
 run-registry-control-plane(7), cli-mcp-parity(7), release-and-migration(7)
@@ -165,3 +199,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.2.2
 
 0.2.3
+
+0.2.4
+
+0.2.5

package/docs/cross-agent-ledger.7.md

@@ -3,8 +3,15 @@
 CW adds `cw ledger` — a way for two agents scoped to two separate repos to hand
 each other a CHANGE PROPOSAL or a REVIEW VERDICT as verifiable data, not chat.
 One side proposes or reviews; the other side verifies the entry fail-closed and
-turns a proposal into a real pull request. Design notes:
-[handoff-ledger](designs/handoff-ledger.md).
+turns a proposal into a real pull request.
+
+Design note (why not a shared folder): the obvious first design — a shared
+local directory both agents read and append to — only works when both agents
+run on ONE machine with ONE filesystem. Two agents scoped to two repos (or two
+machines) need a transport both can already reach, with saved, inspectable,
+fail-closed state — never a fabricated hand-off. That is why an entry is a
+self-verifying file in a git repo both sides can push and pull, and why the
+kernel holds no git logic at all.
 
 Each entry is a self-contained JSON object that carries its own sha256 content
 digest. The producing side prints one; it reaches the other session by human
@@ -51,13 +58,18 @@ cw ledger review  --from <a> --to <b> --target <proposal-id|pr-ref> \
                   --verdict <approved|rejected> [--findings "a,b"]
 cw ledger verify  [--file <path>]        # else reads the entry from stdin
 cw ledger apply   [--file <path>]        # verify a proposal, then print its diff
-cw ledger list    --dir <ledger-dir> [--dir <mirror-2> ...]   # verify a dir (or union of mirrors)
+cw ledger list    --ledger-dir <ledger-dir> [--ledger-dir <mirror-2> ...]   # verify a dir (or union of mirrors)
 ```
 
 All write JSON to stdout (stdout is data). `propose` and `review` print a sealed
 entry; `verify` prints a check report; `apply` prints a verify-plus-diff report;
 `list` prints a per-entry report over a directory.
 
+`--ledger-dir` is the preferred spelling for `list`: the CLI front door
+treats `--dir` as a global alias of `--repo` on every command, so the old
+`--dir` made one flag mean two things here. `--dir` keeps working
+unchanged as the legacy alias; when both are given, `--ledger-dir` wins.
+
 ## Applying a proposal — fail-closed
 
 A proposal carries a `suggestedDiff`, but a proposal never mutates the target
@@ -131,12 +143,12 @@ on the mirror-union output and on the `cw_ledger_list` MCP tool.
 
 ### Mirrors — union-verifying several directories
 
-`--dir` is repeatable. With two or more, `cw ledger list` **union-verifies** the
+`--ledger-dir` (and the legacy `--dir`) is repeatable. With two or more, `cw ledger list` **union-verifies** the
 directories as mirrors of one ledger (e.g. the same handoff repo cloned from a
 GitHub remote and one or more self-hosted Gitea remotes in different places):
 
 ```
-cw ledger list --dir gh/ledger --dir gitea-eu/ledger --dir gitea-asia/ledger
+cw ledger list --ledger-dir gh/ledger --ledger-dir gitea-eu/ledger --ledger-dir gitea-asia/ledger
 ```
 
 The union is **conflict-free by construction**: entries are immutable and
@@ -146,10 +158,10 @@ across mirrors** — a tampered entry in ANY mirror sets `allOk:false` and exits
 `1`. This is for redundancy and reachability, not load: the ledger's traffic is
 tiny; multiple hosts guard against one being down or unreachable.
 
-A single `--dir` keeps the original single-directory output (a `dir` field, no
+A single directory flag keeps the original single-directory output (a `dir` field, no
 `dirs`); two or more switch to the union shape (`dirs` plus a per-entry `dirs`).
 The transport stays git-host-agnostic — adding a mirror is one more clone + one
-more `--dir`, no code change.
+more `--ledger-dir`, no code change.
 
 ## Entry shape
 
@@ -214,4 +226,4 @@ cw ledger verify --file verdict.json
 Stage 1 shipped the CLI verbs (human relay). Stage 2 adds the MCP surface and
 the git-as-ledger transport (`cw ledger list` over a shared repo). Still open:
 the operator creates the shared handoff repo and scopes both agent environments
-into it. See [handoff-ledger](designs/handoff-ledger.md).
+into it. Setup runbook: [handoff-setup](handoff-setup.md).

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

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

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

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

package/docs/execution-backends.7.md

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

package/docs/fix.7.md

@@ -8,7 +8,6 @@
 
 ```text
 node dist/cli.js fix
-node dist/cli.js fix --json
 ```
 
 ## DESCRIPTION
@@ -28,9 +27,10 @@ If any check has status `fail`, the command exits with code 1.
 
 ## OPTIONS
 
-`--json`
-: Give back the full doctor report as a stable JSON object, with the same shape
-as `cw doctor --json`. The `checks` array carries every fix string.
+`cw fix` takes no options of its own; its output is always the plain fix-command
+text (a `--json` flag is silently ignored — this byte behavior is pinned by
+`v2/conformance/cases/report-fix.case.js`). For a machine-readable report of the
+same checks, use `cw doctor --json`: its `checks` array carries every fix string.
 
 ## EXIT CODES