cool-workflow 0.1.98 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "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.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "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.",
   "author": {
     "name": "COOLWHITE LLC"

package/README.md

@@ -1,7 +1,7 @@
 <!-- AUTO-GENERATED from /README.md by scripts/sync-readme.js — edit the root README, then run `npm run sync:readme`. DO NOT edit this file directly. -->
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-hero.png" alt="Cool Workflow — your AI report, already proven. Point your agent at any repo or folder and get a saved, cited report you can re-verify offline." width="100%">
+<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-hero.png" alt="Cool Workflow hero image: the CW name over a line reading ask, plan, dispatch, verify, report — the stages of a saved, cited run." width="100%">
 
 <br><br>
 
@@ -49,7 +49,7 @@ Upgrade later with `brew update && brew upgrade cool-workflow`.
 </details>
 
 **You need:** Node.js v18+ and one agent CLI on your machine — `claude`, `codex`, `gemini`, or
-`opencode` (all auto-detected). No agent yet? `cw demo` still works — **CW never runs a model itself.**
+`opencode` (all auto-detected). No agent yet? `cw demo tamper` still works — **CW never runs a model itself.**
 
 ## Quick Start
 
@@ -64,16 +64,18 @@ cw demo tamper
 ### 2 · Ask a question about your code — one command
 
 ```bash
-cw -q "What are the main risks here?"
+cw -q "How does auth work end-to-end here?"
 ```
 
-CW auto-detects the current repo and the first agent on your `PATH`. Pin a specific one with a flag
-(`-claude`, `-codex`, `-gemini`, `-deepseek`). Point it anywhere — no `cd` required — or review a
-**remote repo by URL** and CW clones, snapshots, and reviews the checkout:
+Any question works, not only a risk audit — architecture questions, "is it safe to change X",
+"what would break if Y rotated" all get a direct, cited answer. CW auto-detects the current repo
+and the first agent on your `PATH`. Pin a specific one with a flag (`-claude`, `-codex`, `-gemini`,
+`-deepseek`). Point it anywhere — no `cd` required — or review a **remote repo by URL** and CW
+clones, snapshots, and reviews the checkout:
 
 ```bash
 cw -q "What are the security risks?" -dir /path/to/project
-cw -q "What are the risks?" --link https://github.com/owner/repo
+cw -q "Is it safe to swap this queue for Redis?" --link https://github.com/owner/repo
 ```
 
 **Not just code.** Aim CW at a folder of docs, notes, or papers and it reads them as sources for the
@@ -110,6 +112,12 @@ is long, parallel, or high-stakes, you can't tell what happened or trust the res
 | **Deterministic, local replay** | Every step is plain JSON under `.cw/runs/<id>/` — read it, diff it, resume it, replay it. No hidden database; the runtime never *guesses* success. |
 | **Vendor-neutral by design** | One source-of-truth manifest generates every vendor adapter (Claude, Codex, …) over a shared CLI + MCP runtime, with a fail-closed drift check. No lock-in, no forked logic. |
 
+**What CW is not.** CW is not the model — it never calls a model API and never holds your keys;
+your agent does that work out of process. It is not a CI system or a build tool — it keeps and
+checks the record of agent work, it does not stand in for your tests or your release pipeline.
+And it is not a big framework to take up — it is a small set of commands over plain `.cw/` files
+on your own disk, not a library your code has to be built around.
+
 ## How It Works
 
 CW is a small TypeScript tool with **zero runtime dependencies**. It drives your agent over a repo — or
@@ -133,6 +141,9 @@ ask simple → run simple → verify simple → resume simple
 | `research-synthesis` | Answer a question over a local folder of files — your docs, notes, or papers |
 | `release-cut` | Run a gated, reviewed release with dry-run evidence |
 
+Every app writes the same thing: a saved, cited report you can re-verify offline. These four are
+the main lanes; `cw app list` shows all eight installed apps.
+
 ```bash
 cw app list            # see everything installed
 cw doctor              # check your setup    →    cw fix   shows the fix commands

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {
@@ -16,7 +16,7 @@
       "name": "question",
       "type": "string",
       "required": true,
-      "description": "Architecture question or decision to review."
+      "description": "Architecture question or decision to review. Every phase scopes its work to this question - not only a fixed risk list."
     },
     {
       "name": "invariant",

package/apps/architecture-review/workflow.js

@@ -8,7 +8,7 @@ module.exports = ({ workflow, phase, parallel, agent, artifact, input }) => {
     input("question", {
       type: "string",
       required: true,
-      description: "Architecture question or decision to review."
+      description: "Architecture question or decision to review. Every phase scopes its work to this question - not only a fixed risk list."
     }),
     input("invariant", {
       type: "string",
@@ -41,54 +41,54 @@ module.exports = ({ workflow, phase, parallel, agent, artifact, input }) => {
         ),
         agent(
           "map:web-client",
-          "Map web/client/UI boundaries, local state, backend dependencies, build/runtime assumptions, and candidate risks in {{repo}}. Focus: {{focus}}. Return exact files and commands that informed the map.",
+          "Map web/client/UI boundaries, local state, backend dependencies, build/runtime assumptions, and candidate risks in {{repo}} as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Return exact files and commands that informed the map.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "map:db-security",
-          "Map database, persistence, migrations, secrets, auth, permissions, and security-sensitive paths in {{repo}}. Return candidate risks with file paths, config names, and uncertainty boundaries.",
+          "Map database, persistence, migrations, secrets, auth, permissions, and security-sensitive paths in {{repo}} as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Return candidate risks with file paths, config names, and uncertainty boundaries.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "map:deploy-config",
-          "Map deployment, CI, package scripts, Docker or compose files, reverse proxies, environment config, supervision, and operational assumptions. Return concrete files and release or runtime risks.",
+          "Map deployment, CI, package scripts, Docker or compose files, reverse proxies, environment config, supervision, and operational assumptions in {{repo}} as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Return concrete files and release or runtime risks.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "map:jobs-operators",
-          "Map background jobs, admin/operator surfaces, queues, scheduled work, generated files, state transitions, and failure recovery paths. Identify missing or non-applicable areas explicitly.",
+          "Map background jobs, admin/operator surfaces, queues, scheduled work, generated files, state transitions, and failure recovery paths in {{repo}} as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Identify missing or non-applicable areas explicitly.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "map:transport-core",
-          "Map protocol, daemon, transport, rendering, networking, worker isolation, or core engine boundaries when present. If absent, explain why with inspected evidence.",
+          "Map protocol, daemon, transport, rendering, networking, worker isolation, or core engine boundaries when present in {{repo}}, as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. If absent, explain why with inspected evidence.",
           { sandboxProfileId: "readonly" }
         )
       ]),
       parallel("Assess", [
         agent(
           "assess:security",
-          "Assess mapper findings through a security lens. Separate real, conditional, non-issue, and unknown risks with evidence, falsifiers, and exact files or config keys.",
+          "Assess mapper findings through a security lens as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Separate real, conditional, non-issue, and unknown risks with evidence, falsifiers, and exact files or config keys.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "assess:data-correctness",
-          "Assess data correctness, schema drift, persistence invariants, concurrency, transactions, cache behavior, and state corruption risks. Tie every important claim to inspected evidence.",
+          "Assess data correctness, schema drift, persistence invariants, concurrency, transactions, cache behavior, and state corruption risks as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Tie every important claim to inspected evidence.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "assess:failure-modes",
-          "Assess startup, shutdown, retries, partial failure, dependency outage, backup/restore, release rollback, and recovery behavior. Identify deterministic commands that could verify the claims.",
+          "Assess startup, shutdown, retries, partial failure, dependency outage, backup/restore, release rollback, and recovery behavior as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Identify deterministic commands that could verify the claims.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "assess:scale-ops",
-          "Assess scale, operational complexity, observability, configuration, packaging, deployment, and maintenance risks. Include exact files, scripts, or missing controls.",
+          "Assess scale, operational complexity, observability, configuration, packaging, deployment, and maintenance risks as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Include exact files, scripts, or missing controls.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
           "assess:maintainability",
-          "Assess module boundaries, ownership clarity, coupling, extensibility, testability, and future change risk. Distinguish architectural risks from style preferences.",
+          "Assess module boundaries, ownership clarity, coupling, extensibility, testability, and future change risk as they relate to {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Distinguish architectural risks from style preferences.",
           { sandboxProfileId: "readonly" }
         ),
         agent(
@@ -100,7 +100,7 @@ module.exports = ({ workflow, phase, parallel, agent, artifact, input }) => {
       phase("Verify", [
         agent(
           "verify:p0-p2-risks",
-          "Re-open evidence for every candidate P0/P1/P2 risk. Confirm real risks, downgrade unsupported concerns, and list exact file paths, commands, logs, or unknowns. The cw:result evidence array must cite durable locators.",
+          "Re-open evidence for every candidate P0/P1/P2 risk found so far, judged against {{question}}. Confirm real risks, downgrade unsupported concerns, and list exact file paths, commands, logs, or unknowns. The cw:result evidence array must cite durable locators.",
           { requiresEvidence: true, sandboxProfileId: "readonly" }
         )
       ]),

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.98",
+  "version": "0.2.1",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/cli/dispatch.js

@@ -0,0 +1,236 @@
+"use strict";
+// cli/dispatch.ts — the generic CLI executor over core/capability-table.ts.
+//
+// MILESTONE 2 (docs/rebuild/PLAN.md build order, step 2; see the Revision note there
+// for why this lands here, right after CLI parsing, instead of late).
+//
+// `dispatch(args)` first tries the CAPABILITY TABLE: it looks up the row
+// whose `cli.path` matches the parsed command (+ enough leading
+// positionals to disambiguate a subcommand, e.g. `sandbox list`), calls
+// its `cli.handler`, and prints the `CliHandlerResult` per the row's
+// `jsonMode`. This is the ONLY code path future milestones touch when
+// they add a capability — as a table row, never a new switch arm here.
+//
+// Everything below `dispatchLegacy` is the milestone-1 carry-over: a
+// small, explicitly-scoped switch for verbs that conformance/cases/
+// cli-argv-parsing.case.js and cli-exit-codes.case.js probe but that do
+// not yet have a real subsystem behind them (see each case's own
+// PLACEHOLDER comment for which future milestone owns it). Per the
+// Revision note in docs/rebuild/PLAN.md, THIS file is never hand-extended again —
+// `dispatchLegacy`'s arms shrink to nothing as later milestones move each
+// one into a real capability-table row; nothing new is ever added here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_COMMANDS = void 0;
+exports.dispatch = dispatch;
+const help_1 = require("../core/format/help");
+const capability_table_1 = require("../core/capability-table");
+const parseargv_1 = require("./parseargv");
+Object.defineProperty(exports, "KNOWN_COMMANDS", { enumerable: true, get: function () { return parseargv_1.KNOWN_COMMANDS; } });
+const io_1 = require("./io");
+const workflow_app_loader_1 = require("../shell/workflow-app-loader");
+function firstPositional(args, index = 0) {
+    return args.positionals[index];
+}
+/** Writes a `CliHandlerResult` to stdout and applies its exit code, per
+ *  the row's `jsonMode`:
+ *   - `"default"` — always prints `result.json` as JSON (falls back to
+ *     `result.text` when a row has no canonical JSON shape).
+ *   - `"flag"` — prints `result.text` normally, `result.json` under
+ *     `--json`/`--format json`.
+ *   - `"human"` — always prints `result.text`; there is no JSON form. */
+function renderCliResult(result, jsonMode, options) {
+    const useJson = jsonMode === "default" || (jsonMode === "flag" && (0, io_1.wantsJson)(options));
+    if (useJson && result.json !== undefined) {
+        (0, io_1.printJson)(result.json);
+    }
+    else if (result.text !== undefined) {
+        process.stdout.write(result.text.endsWith("\n") ? result.text : `${result.text}\n`);
+    }
+    else if (result.json !== undefined) {
+        (0, io_1.printJson)(result.json);
+    }
+    if (result.exitCode !== undefined)
+        process.exitCode = result.exitCode;
+}
+/** Tries the capability table for `args`. Matches the row whose
+ *  `cli.path` is `[command]` or `[command, positionals[0]]` (the only two
+ *  path lengths any milestone-2 row uses); returns true when a table row
+ *  handled the command. */
+function dispatchTable(args) {
+    const candidates = [[args.command]];
+    if (args.positionals.length > 0)
+        candidates.push([args.command, args.positionals[0]]);
+    for (const candidatePath of candidates.slice().reverse()) {
+        const row = (0, capability_table_1.findCapabilityByCliPath)(candidatePath);
+        if (!row || !row.cli)
+            continue;
+        const consumed = candidatePath.length - 1; // path[0] is the command itself, already consumed
+        const cliArgs = {
+            positionals: args.positionals.slice(consumed),
+            options: args.options,
+        };
+        const result = row.cli.handler(cliArgs);
+        renderCliResult(result, row.cli.jsonMode, args.options);
+        return true;
+    }
+    return false;
+}
+// MILESTONE 12 (workflow-apps) — `search` filters the SAME real app
+// discovery `cw app list`/`cw list` use (shell/workflow-app-loader.ts),
+// by id/title/summary, matching `listApps` in the old build.
+function formatSearchResults(keyword, results) {
+    if (results.length === 0) {
+        return `No workflows matched "${keyword}".\n  Tip: cw list for all available workflows.`;
+    }
+    const lines = [`${results.length} workflow${results.length === 1 ? "" : "s"} matching "${keyword}"`];
+    for (const r of results) {
+        lines.push(`  ${r.id} — ${r.title}`);
+        const cut = r.summary.length > 120 ? `${r.summary.slice(0, 119)}…` : r.summary;
+        lines.push(`    ${cut}`);
+    }
+    lines.push("");
+    lines.push("Use cw info <id> for full details.");
+    return lines.join("\n");
+}
+/** The milestone-1 carry-over switch. See file header: never extended
+ *  again — each arm here is replaced by a capability-table row when its
+ *  own build-order milestone lands, not edited in place. */
+function dispatchLegacy(args) {
+    switch (args.command) {
+        case "": {
+            process.stdout.write((0, io_1.styledHelp)());
+            return;
+        }
+        case "help": {
+            const topic = firstPositional(args);
+            if (topic) {
+                process.stdout.write((0, help_1.formatCommandHelp)(topic, parseargv_1.suggestCommand));
+            }
+            else {
+                process.stdout.write((0, io_1.styledHelp)());
+            }
+            return;
+        }
+        // NOTE: "version" is not an arm here — it is a real capability-table
+        // row (core/capability-table.ts) that dispatchTable() above always
+        // matches first, per the Revision note's "table rows, never a new
+        // switch arm" rule. Same for "list", "status", and "sandbox list".
+        // `search` filters the real app discovery by title/summary/id (see
+        // note above); MILESTONE 12.
+        case "search": {
+            const keyword = args.positionals.join(" ");
+            if (!keyword.trim()) {
+                throw new Error('Missing search keyword.\n  Tip: cw search architecture to find workflows about architecture.');
+            }
+            const lower = keyword.toLowerCase();
+            const results = (0, workflow_app_loader_1.listWorkflowApps)()
+                .filter((a) => String(a.title).toLowerCase().includes(lower) ||
+                String(a.summary).toLowerCase().includes(lower) ||
+                String(a.id).toLowerCase().includes(lower))
+                .map((a) => ({ id: String(a.id), title: String(a.title), summary: String(a.summary) }));
+            if ((0, io_1.wantsJson)(args.options)) {
+                (0, io_1.printJson)(results);
+            }
+            else {
+                process.stdout.write(`${formatSearchResults(keyword, results)}\n`);
+            }
+            return;
+        }
+        // NOTE: "plan" and "quickstart" are not arms here any more — both are
+        // now real capability-table rows (core/capability-table.ts, milestone
+        // 6+7) that dispatchTable() above always matches first.
+        // PLACEHOLDER (milestone 3/6, state kernel + pipeline) — real `next`
+        // loads run state and returns dispatchable tasks; this milestone only
+        // reproduces the io.required missing-run-id refusal.
+        case "next": {
+            const runId = (0, io_1.required)((0, io_1.optionalArg)(firstPositional(args)), "run id");
+            throw new Error(`next is not implemented in this milestone (runId=${runId})`);
+        }
+        // MILESTONE 8 — `ledger propose|review|verify|apply|list` are now
+        // real capability-table rows (core/capability-table.ts) that
+        // dispatchTable() above always matches first; this arm is reached
+        // only for an unrecognized subcommand (byte-exact to the old
+        // build's handleLedger default case). NOTE: "ledger" is
+        // intentionally absent from KNOWN_COMMANDS (see cli/parseargv.ts)
+        // even though the dispatcher handles it here — a known, preserved
+        // wart, not a bug.
+        case "ledger": {
+            throw new Error("Usage: cw ledger propose|review|verify|apply|list [options]");
+        }
+        // PLACEHOLDER (milestone 10, scheduling/gc) — real `gc verify` checks
+        // whether a run's disk footprint was actually reclaimed; a run that
+        // was never reclaimed is not a failure (exit 0), which is exactly the
+        // shape this stub reproduces for an unresolvable run id.
+        case "gc": {
+            const sub = firstPositional(args);
+            if (sub === "verify") {
+                const runId = (0, io_1.optionalArg)(firstPositional(args, 1));
+                const payload = {
+                    schemaVersion: 1,
+                    runId: runId ?? null,
+                    reclaimed: false,
+                    verified: false,
+                    tier: "live",
+                    capability: "re-runnable",
+                    chainLength: 0,
+                    checks: [{ name: "located", pass: false, code: "not-reclaimed", detail: "run source not found" }],
+                    nextAction: "node scripts/cw.js registry refresh --scope home",
+                };
+                (0, io_1.printJson)(payload);
+                return;
+            }
+            throw new Error(`gc ${sub ?? ""} is not implemented in this milestone`);
+        }
+        // NOTE: "run" is not an arm here any more — run.drive.step/run.drive
+        // are now real capability-table rows (core/capability-table.ts,
+        // milestone 6+7) that dispatchTable() above always matches first
+        // (their handler reproduces the inspect-archive/restore placeholder
+        // shapes this arm used to own), per the Revision note's "table rows,
+        // never a new switch arm" rule.
+        // NOTE: "sandbox" is not an arm here — sandbox.list/show/validate are
+        // now real capability-table rows (core/capability-table.ts, milestone
+        // 5) that dispatchTable() above always matches first, per the
+        // Revision note's "table rows, never a new switch arm" rule.
+        // NOTE: "topology" is not an arm here any more — topology.list/show/
+        // validate/apply/summary/graph are now real capability-table rows
+        // (core/capability-table.ts, milestone 9) that dispatchTable() above
+        // always matches first, per the Revision note's "table rows, never a
+        // new switch arm" rule.
+        // PLACEHOLDER (milestone 3/4, state kernel + contract-migration) —
+        // real `migration check`/`prove` resolve a run id or file target; the
+        // missing-target refusal is the only shape this milestone reproduces.
+        case "migration": {
+            const sub = firstPositional(args);
+            if (sub === "check" || sub === "prove") {
+                const target = (0, io_1.optionalArg)(firstPositional(args, 1));
+                if (!target) {
+                    throw new Error('Missing target (run-id or state/app file).\n  Tip: find run ids with "cw run list" or create one with "cw quickstart"');
+                }
+                throw new Error(`migration ${sub} is not implemented in this milestone`);
+            }
+            throw new Error(`migration ${sub ?? ""} is not implemented in this milestone`);
+        }
+        // NOTE: "report" is not an arm here any more — report/report.bundle/
+        // report.verify-bundle are now real capability-table rows
+        // (core/capability-table.ts, milestones 8/11) that dispatchTable()
+        // above always matches first, per the Revision note's "table rows,
+        // never a new switch arm" rule.
+        default: {
+            const hint = (0, parseargv_1.suggestCommand)(args.command);
+            const tail = hint ? `. Did you mean: ${hint}?` : "";
+            throw new Error(`Unknown command: ${args.command}${tail}`);
+        }
+    }
+}
+/** Runs one parsed command. Throws on any recoverable failure (the entry
+ *  point's top-level catch turns that into the `cw: <message>` stderr
+ *  shape + exit 1); sets `process.exitCode = 1` directly for the
+ *  fail-closed-but-clean-JSON verbs (never a hard `process.exit`).
+ *
+ *  Tries the capability table FIRST (real rows always win), then falls
+ *  back to the milestone-1 legacy switch for verbs not yet migrated. */
+function dispatch(args) {
+    if (dispatchTable(args))
+        return;
+    dispatchLegacy(args);
+}

package/dist/cli/entry.js

@@ -0,0 +1,120 @@
+"use strict";
+// cli/entry.ts — the real entry point (`cw` / `cool-workflow` binaries).
+//
+// Byte-exact port of the shape of src/cli.ts + the top-of-function part of
+// src/cli/command-surface.ts's `runCli` in the old build: top-level flag
+// redirects, then dispatch (see cli/dispatch.ts), then the top-level
+// catch that turns any thrown error into the fixed `cw: <message>` /
+// `  Try: <hint>` stderr shape.
+//
+// Color: MILESTONE 11 (reporting/observability) wires shell/term.ts's
+// color primitives here — the "Cool Workflow" help header is bolded and
+// the error path is styled (bold "cw:", red message, dim "Try:"), TTY/
+// env-gated exactly as SPEC/reporting-ux.md's "Color rule" describes.
+// Every conformance case still pipes with NO_COLOR=1 by default (lib.js),
+// so byte content there is unaffected; cli-color-env.case.js exercises
+// the FORCE_COLOR/NO_COLOR/CW_NO_COLOR branches explicitly.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryHint = recoveryHint;
+exports.runCli = runCli;
+exports.main = main;
+const parseargv_1 = require("./parseargv");
+const dispatch_1 = require("./dispatch");
+const help_1 = require("../core/format/help");
+const parseargv_2 = require("./parseargv");
+const capability_table_1 = require("../core/capability-table");
+const term_1 = require("../shell/term");
+const io_1 = require("./io");
+/** MILESTONE 2: `version` is now a pure projection of the capability
+ *  table's `version` row — there is exactly one place its print text
+ *  lives (core/capability-table.ts's cli handler), not a second
+ *  hard-coded copy here. `help` has no row of its own (it is cli/
+ *  entry.ts's own top-level redirect, same as milestone 1); its text
+ *  comes from core/format/help.ts either way. */
+function printVersion() {
+    const row = (0, capability_table_1.findCapability)("version");
+    const result = row?.cli?.handler({ positionals: [], options: {} });
+    process.stdout.write(result?.text ?? "");
+}
+/** src/cli.ts:18-29 — map a top-level error message to ONE copy-pasteable
+ *  recovery command. Content-based so it stays correct regardless of which
+ *  call site threw; returns undefined rather than a wrong guess. */
+function recoveryHint(message) {
+    const m = message.toLowerCase();
+    if (m.startsWith("unknown command"))
+        return "cw help";
+    if (m.includes("not configured") || m.includes("agent backend"))
+        return "cw doctor";
+    if (m.includes("missing") && m.includes("repo"))
+        return 'cw -q "<question>" -dir <project-folder>';
+    if (m.includes("app") && (m.includes("not found") || m.includes("not available")))
+        return "cw app list";
+    if (m.includes("run id") || m.includes("run not found"))
+        return "cw run list";
+    return undefined;
+}
+async function runCli(argv = process.argv.slice(2)) {
+    const args = (0, parseargv_1.parseArgv)(argv);
+    // Top-level flags: accept --version / -v / --help / -h before command lookup.
+    // (src/cli/command-surface.ts:46-55)
+    if (args.command?.startsWith("-") || !args.command) {
+        if (args.command === "--version" || args.command === "-v" || args.options.v || args.options.version) {
+            printVersion();
+            return;
+        }
+        if (!args.command || args.command === "--help" || args.command === "-h" || args.options.h || args.options.help) {
+            process.stdout.write((0, io_1.styledHelp)());
+            return;
+        }
+    }
+    // Vendor short flags -> --agent-command (src/cli/command-surface.ts:59-62).
+    if (args.options.claude)
+        args.options["agent-command"] = "builtin:claude";
+    if (args.options.codex)
+        args.options["agent-command"] = "builtin:codex";
+    if (args.options.gemini)
+        args.options["agent-command"] = "builtin:gemini";
+    if (args.options.deepseek)
+        args.options["agent-command"] = "builtin:deepseek";
+    // -dir / --dir / -d is a second name for --repo; an explicit --repo wins
+    // (src/cli/command-surface.ts:65).
+    if (!args.options.repo && args.options.dir)
+        args.options.repo = args.options.dir;
+    // Presentation flags set env vars before any agent spawn
+    // (src/cli/command-surface.ts:73-75).
+    if (args.options.verbose)
+        process.env.CW_VERBOSE = "1";
+    if (args.options["no-color"])
+        process.env.CW_NO_COLOR = "1";
+    if (args.options.full)
+        process.env.CW_OUTPUT = "full";
+    // `cw <verb> --help` / `-h` -> per-command help
+    // (src/cli/command-surface.ts:80-83).
+    if ((args.options.help || args.options.h) && args.command && !args.command.startsWith("-")) {
+        process.stdout.write((0, help_1.formatCommandHelp)(args.command, parseargv_2.suggestCommand));
+        return;
+    }
+    // Bare -q / --question -> redirect to quickstart (src/cli/command-surface.ts:88-93).
+    if (args.command === "-q" || args.command === "--question") {
+        if (!args.options.question && args.positionals[0])
+            args.options.question = args.positionals.shift();
+        args.command = "quickstart";
+    }
+    else if (!args.command && typeof args.options.question === "string") {
+        args.command = "quickstart";
+    }
+    (0, dispatch_1.dispatch)(args);
+}
+/** Top-level run wrapper matching src/cli.ts's catch shape byte-for-byte:
+ *  `cw: <message>\n` then, only when a hint matches, `  Try: <hint>\n` on
+ *  stderr; `process.exitCode = 1` (never a hard `process.exit`). */
+function main(argv = process.argv.slice(2)) {
+    return runCli(argv).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${(0, term_1.bold)("cw:", process.stderr)} ${(0, term_1.red)(message, process.stderr)}\n`);
+        const hint = recoveryHint(message);
+        if (hint)
+            process.stderr.write(`  ${(0, term_1.dim)("Try:", process.stderr)} ${hint}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/cli/io.js

@@ -1,16 +1,33 @@
 "use strict";
-// Shared CLI input/output helpers, extracted from command-surface.ts so the
-// dispatcher and per-command handler modules import ONE copy instead of carrying
-// these in the god-object. Pure + zero-dep: arg coercion + JSON stdout.
+// cli/io.ts — shared CLI input/output helpers.
+//
+// Byte-exact port of src/cli/io.ts in the old build. Pure + zero-dep: arg
+// coercion + JSON stdout. See SPEC/cli-surface.md "Shared io helpers".
+//
+// MILESTONE 11 (reporting/observability) adds `styledHelp` — the one
+// place `formatHelp()`'s plain text gets its "Cool Workflow" header
+// bolded, TTY/env-gated via shell/term.ts's `bold()`. Kept here (not in
+// core/format/help.ts, which stays a pure text generator) since it needs
+// shell/term.ts's env/TTY read.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.styledHelp = styledHelp;
 exports.required = required;
 exports.optionalArg = optionalArg;
 exports.printJson = printJson;
 exports.wantsJson = wantsJson;
+const help_1 = require("../core/format/help");
+const term_1 = require("../shell/term");
+/** Bold ONLY the fixed "Cool Workflow" header line of `formatHelp()`'s
+ *  plain text. */
+function styledHelp() {
+    const text = (0, help_1.formatHelp)();
+    return text.replace(/^Cool Workflow\n/, `${(0, term_1.bold)("Cool Workflow")}\n`);
+}
 /** Require a positional/option value or fail with a copy-pasteable recovery tip. */
 function required(value, label) {
-    if (!value)
+    if (!value) {
         throw new Error(`Missing ${label}.\n  Tip: find run ids with "cw run list" or create one with "cw quickstart"`);
+    }
     return value;
 }
 /** Normalize an optional CLI arg to a trimmed non-empty string, else undefined. */