cool-workflow 0.2.4 → 0.2.5

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.2.4",
+  "version": "0.2.5",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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/.gemini-plugin/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cool-workflow": {
+      "command": "node",
+      "args": [
+        "./dist/mcp-server.js"
+      ]
+    }
+  }
+}

package/.gemini-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "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.2.5",
+  "author": {
+    "name": "COOLWHITE LLC"
+  },
+  "homepage": "https://github.com/coo1white/cool-workflow",
+  "license": "BSD-2-Clause",
+  "keywords": [
+    "workflow",
+    "control-plane",
+    "dynamic-workflows",
+    "subagents",
+    "orchestration",
+    "agents",
+    "multi-agent",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.gemini-plugin/mcp.json",
+  "interface": {
+    "displayName": "Cool Workflow",
+    "shortDescription": "A workflow control plane you are able to check.",
+    "longDescription": "Cool Workflow (CW) is a workflow control plane and run-time you are able to check. It gives you: a TypeScript COL run-time, Workflow App framework agreements, a Router and Orchestrator, Subagent Dispatch, a same-every-time Harness, a hard-questioning Verifier, Git and State Commit, Sandbox Profiles, time-ordered jobs, jobs that come round again, a high-level Multi-Agent CLI and MCP host face, and an MCP JSON-RPC 2.0 bridge. Builders make workflow apps they are able to use again; CW gives the doing of the work to an outside agent host and keeps a checked, play-again record of state — it never puts a model API inside itself.",
+    "developerName": "COOLWHITE LLC",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "brandColor": "#2563EB",
+    "defaultPrompt": [
+      "Use Cool Workflow to plan this as phases and agents.",
+      "Run the architecture review workflow with CW.",
+      "Create a reusable CW workflow for this task."
+    ]
+  }
+}

package/.opencode-plugin/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cool-workflow": {
+      "command": "node",
+      "args": [
+        "./dist/mcp-server.js"
+      ]
+    }
+  }
+}

package/.opencode-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "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.2.5",
+  "author": {
+    "name": "COOLWHITE LLC"
+  },
+  "homepage": "https://github.com/coo1white/cool-workflow",
+  "license": "BSD-2-Clause",
+  "keywords": [
+    "workflow",
+    "control-plane",
+    "dynamic-workflows",
+    "subagents",
+    "orchestration",
+    "agents",
+    "multi-agent",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.opencode-plugin/mcp.json",
+  "interface": {
+    "displayName": "Cool Workflow",
+    "shortDescription": "A workflow control plane you are able to check.",
+    "longDescription": "Cool Workflow (CW) is a workflow control plane and run-time you are able to check. It gives you: a TypeScript COL run-time, Workflow App framework agreements, a Router and Orchestrator, Subagent Dispatch, a same-every-time Harness, a hard-questioning Verifier, Git and State Commit, Sandbox Profiles, time-ordered jobs, jobs that come round again, a high-level Multi-Agent CLI and MCP host face, and an MCP JSON-RPC 2.0 bridge. Builders make workflow apps they are able to use again; CW gives the doing of the work to an outside agent host and keeps a checked, play-again record of state — it never puts a model API inside itself.",
+    "developerName": "COOLWHITE LLC",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "brandColor": "#2563EB",
+    "defaultPrompt": [
+      "Use Cool Workflow to plan this as phases and agents.",
+      "Run the architecture review workflow with CW.",
+      "Create a reusable CW workflow for this task."
+    ]
+  }
+}

package/README.md

@@ -12,7 +12,7 @@
 [![release](https://img.shields.io/github/v/tag/coo1white/cool-workflow?style=flat-square&label=release&color=brightgreen&sort=semver)](https://github.com/coo1white/cool-workflow/tags)
 [![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](https://github.com/coo1white/cool-workflow/blob/main/LICENSE)
 
-### Get a saved, cited report from your AI agent — not a chat message you lose.
+### Get a saved report from your AI agent, with every claim tied to a line of code — not a chat answer you lose.
 
 <br>
 
@@ -20,9 +20,25 @@
 
 </div>
 
-Point an AI coding agent at a repo (or any folder of docs) and Cool Workflow turns the run into a
-**durable, inspectable workflow**: it plans the work, delegates each task to *your* agent, records and
-verifies every result, then writes a report where every claim is cited to a `file.ts:42`.
+## What is this?
+
+You may already use an AI coding agent — a tool like `claude`, `codex`, or
+`gemini` that reads your code and answers questions about it. The answer comes
+back as a chat message. Chat is easy to lose, and hard to check.
+
+Cool Workflow (`cw`) is a small command-line tool that fixes that. Point it at
+a repo — or any folder of docs — and:
+
+- **It plans the work.** Your question becomes a set of small tasks.
+- **Your agent does the work.** CW never runs a model itself. Your own agent
+  does the reading and the thinking.
+- **It keeps a record.** Every step is saved as plain JSON files on your own
+  disk, under `.cw/`. You can read them, compare them, and pick a run up again
+  later.
+- **It checks the results.** A result with no evidence does not get through —
+  it stops in a clear `unexplained` state instead.
+- **It writes a report.** Every claim points to a real place in your code,
+  like `file.ts:42`. Click it and see for yourself.
 
 > **The model is fuel. CW is the black-box recorder, the dashboard, and the gearbox — never the engine.**
 > It never calls a model API, never holds your keys, and never uploads your code. Your agent spends the
@@ -48,12 +64,16 @@ cw version
 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 tamper` still works — **CW never runs a model itself.**
+**You need:** Node.js v18 or newer, and one agent CLI on your machine —
+`claude`, `codex`, `gemini`, or `opencode`. CW finds them by itself. No agent
+yet? Step 1 below still works — **CW never runs a model itself.**
+
+Not sure what you have? `cw doctor` checks your setup and `cw fix` prints the
+commands that put it right.
 
 ## Quick Start
 
-### 1 · Prove it works — 30 seconds, no agent needed
+### 1 · See it work — 30 seconds, no agent needed
 
 ```bash
 cw demo tamper
@@ -61,25 +81,32 @@ cw demo tamper
 # → VERDICT: tamper-evidence holds ✓
 ```
 
+This is CW's trust check working on itself: it makes a signed record, breaks
+it on purpose in three ways, and catches all three breaks.
+
 ### 2 · Ask a question about your code — one command
 
+Go to any project folder and run:
+
 ```bash
 cw -q "How does auth work end-to-end here?"
 ```
 
-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:
+Any question works — "how does X work", "is it safe to change Y", "what would
+break if Z rotated". CW uses the current repo and the first agent it finds on
+your `PATH`. Want a specific agent? Add a flag (`-claude`, `-codex`, `-gemini`,
+`-opencode`, `-deepseek`). DeepSeek is the one with no auto-detect — it runs
+through `opencode` — so `-deepseek` is the only way to get it. You can
+point CW at any folder, or at a **repo on the web by
+URL** — CW clones it and reviews the copy:
 
 ```bash
 cw -q "What are the security risks?" -dir /path/to/project
 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
-same saved, cited report:
+**Not just code.** Point CW at a folder of docs, notes, or papers and it reads
+them as sources for the same saved report:
 
 ```bash
 cw quickstart research-synthesis --repo /path/to/papers \
@@ -88,41 +115,47 @@ cw quickstart research-synthesis --repo /path/to/papers \
 
 ### 3 · Open the report
 
-The command prints the path. Every finding carries a clickable `file.ts:42` pointer:
+The command prints the path when it is done. Every finding has a clickable
+`file.ts:42` pointer:
 
 ```bash
 cat .cw/runs/<run-id>/report.md
 ```
 
-While it runs you get a calm, Claude-Code-style live view — a compact rolling window of tool calls
-that updates in place instead of an endless wall — and a clean findings table when it's done.
+While it runs you get a calm live view — a small rolling window of tool calls
+that updates in place, not an endless wall of text — and a clean findings
+table at the end.
 
 ---
 
 ## Why Cool Workflow
 
-Most agent tooling runs a whole task as one long prompt, then hands you a chat message. When the work
-is long, parallel, or high-stakes, you can't tell what happened or trust the result. CW treats it as a
-**runtime problem** — and rests on four commitments:
+Most agent tools run a whole task as one long prompt, then hand you a chat
+message. When the work is long, parallel, or high-stakes, you cannot tell what
+happened or trust the result. CW treats that as a **runtime problem** — like an
+operating system keeping processes safe and visible — and rests on four
+commitments:
 
 | Commitment | What it means for you |
 |---|---|
-| **Model as fuel, not engine** | CW never calls a model API. Execution is always delegated to your agent, so the backend is swappable and your credentials and code never leave your machine. |
-| **Evidence-gated decisions** | Every adopted result records its **basis, authority, rationale, and the alternative it beat.** Missing evidence doesn't slip through — it fails closed to a visible `unexplained` state. |
+| **Model as fuel, not engine** | CW never calls a model API. Your agent does all the model work, so you can swap agents freely, and your keys and code never leave your machine. |
+| **Evidence-gated decisions** | Every accepted result records its **basis, authority, rationale, and the option it beat.** Missing evidence does not slip through — the result stops in a visible `unexplained` state. |
 | **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. |
+| **Vendor-neutral by design** | One source-of-truth manifest generates every vendor adapter (Claude, Codex, …) over one shared CLI + MCP runtime, with a fail-closed drift check. No lock-in. |
 
-**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.
+**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 in its own process. It is not a CI
+system or a build tool — it keeps and checks the record of agent work; it does
+not take the place of your tests or your release pipeline. And it is not a big
+framework to build on — it is a small set of commands over plain `.cw/` files
+on your own disk, not a library your code has to wrap itself around.
 
 ## How It Works
 
-CW is a small TypeScript tool with **zero runtime dependencies**. It drives your agent over a repo — or
-any folder — in saved, replayable stages, writing everything to disk as inspectable files. It never
-imports a model SDK or stores an API key.
+CW is a small TypeScript tool with **zero runtime dependencies**. It drives
+your agent over a repo — or any folder — in saved stages that you can replay,
+writing everything to disk as files you can open and read. It never imports a
+model SDK or stores an API key.
 
 <div align="center">
 <img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-pipeline.png" alt="The CW pipeline: ask, plan, dispatch (delegated to your agent), verify (evidence gate, fails closed), commit verified state, and a saved, cited, signed report — every step recorded as durable .cw/ JSON." width="100%">
@@ -137,22 +170,24 @@ ask simple → run simple → verify simple → resume simple
 | Workflow | What it produces |
 |---|---|
 | `architecture-review` | Map a repo, rank risks, and back every claim with `file:line` evidence |
-| `pr-review-fix-ci` | Review a PR or branch, diagnose CI, and propose + verify fixes |
+| `pr-review-fix-ci` | Review a PR or branch, work out why CI fails, and propose + verify fixes |
 | `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.
+Every app writes the same thing: a saved report you can check again offline,
+with every claim tied to its source. 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
 ```
 
-**Multi-agent, when you need it.** Fan work out across agents with built-in topologies, compose flows
-(a task can run a whole child workflow with `subWorkflow`, or a `loop()` phase can iterate until a
-predicate or token budget says stop), and re-run fast — `cw run <app> --drive --incremental` reuses
-every step whose inputs didn't change.
+**Multi-agent, when you need it.** Fan work out across agents with built-in
+topologies (ready-made team shapes), compose flows (a task can run a whole
+child workflow with `subWorkflow`, or a `loop()` phase can go round until a
+condition or a token budget says stop), and re-run fast — `cw run <app>
+--drive --incremental` reuses every step whose inputs did not change.
 
 <div align="center">
 <img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/topologies.svg" alt="Built-in multi-agent topologies: map-reduce (fan out, fold in), debate (argue then draw a verdict), and judge-panel (N independent judges score one candidate)." width="92%">
@@ -160,10 +195,11 @@ every step whose inputs didn't change.
 
 ## Can You Trust the Report?
 
-CW doesn't run the model — it keeps the books. Your agent signs its findings (**ed25519**), and
-`cw report verify-bundle` checks — **offline, with nothing but the public key** — that every signed
-finding is in the report unaltered. Edit a finding, in the report or in the agent's own result, and the
-check fails. CW holds no private key: the agent signs, CW only verifies.
+CW does not run the model — it keeps the books. Your agent signs its findings
+(**ed25519**), and `cw report verify-bundle` checks — **offline, with nothing
+but the public key** — that every signed finding is in the report unaltered.
+Edit a finding, in the report or in the agent's own result, and the check
+fails. CW holds no private key: the agent signs, CW only verifies.
 
 ```bash
 cw demo tamper                                  # proves it in 30s — edits a signed result, watch it fail
@@ -171,14 +207,104 @@ cw -q "…" --bundle                              # seal a run into one portable
 cw report verify-bundle report.cwrun.json       # anyone can re-check it offline, with just the file
 ```
 
-This attests the agent's **signed findings** — not that nothing else was added or that nothing was left
-out. For exactly what is and isn't proven, see the **[Trust Model](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/trust-model.md)**.
+This proves the agent's **signed findings** reached you unaltered — not that
+nothing else was added, and not that nothing was left out. For exactly what is
+and is not proven, see the **[Trust Model](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/trust-model.md)**.
 
 ## Use It From Your Editor
 
-CW exposes the same runtime over **MCP** — **Claude Desktop, Cursor, and VS Code call CW as a tool**, so
-your agent can plan a run, drive it, and verify a report without leaving the editor. CLI and MCP share
-one registry and are parity-checked. See the **[Wiki](https://github.com/coo1white/cool-workflow/wiki)**.
+CW offers the same runtime over **MCP** — a standard way for editors to call
+tools. **Claude Desktop, Cursor, and VS Code call CW as a tool**, so your
+agent can plan a run, drive it, and verify a report without leaving the
+editor. CLI and MCP share one registry and are parity-checked. See the
+**[Wiki](https://github.com/coo1white/cool-workflow/wiki)**.
+
+The MCP server is `scripts/mcp-server.js` inside the installed package. After
+`npm install -g cool-workflow`, its full path is:
+
+```text
+<output of `npm root -g`>/cool-workflow/scripts/mcp-server.js
+```
+
+Put that path in the configs below where you see `/path/from/npm-root-g/…`.
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+The simple way — as a plugin (this wires MCP for you):
+
+```text
+/plugin marketplace add coo1white/cool-workflow
+/plugin install cool-workflow@cool-workflow
+```
+
+Or add only the MCP server, one line in your terminal:
+
+```bash
+claude mcp add cool-workflow -- node "$(npm root -g)/cool-workflow/scripts/mcp-server.js"
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add this to `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`,
+Windows: `%APPDATA%\Claude\`), then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "cool-workflow": {
+      "command": "node",
+      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add the same `mcpServers` block to `~/.cursor/mcp.json`
+(or `.cursor/mcp.json` inside one project):
+
+```json
+{
+  "mcpServers": {
+    "cool-workflow": {
+      "command": "node",
+      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>VS Code</b></summary>
+
+VS Code uses a `servers` key. Add this to `.vscode/mcp.json` in your project
+(or run **MCP: Add Server** from the Command Palette):
+
+```json
+{
+  "servers": {
+    "cool-workflow": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
+    }
+  }
+}
+```
+</details>
+
+Once connected, your agent sees the `cw_*` tools — `cw_plan`, `cw_status`,
+`cw_report`, and the rest — the same registry the CLI uses, parity-checked.
+More on the MCP surface — parity, manifests, vendor targets — is on the wiki
+page **[MCP And Manifests](https://github.com/coo1white/cool-workflow/wiki/MCP-And-Manifests)**.
 
 ## Troubleshooting
 
@@ -188,6 +314,33 @@ one registry and are parity-checked. See the **[Wiki](https://github.com/coo1whi
 | `status: blocked` | Set `CW_AGENT_COMMAND=builtin:claude` or pass `-claude` |
 | `claude: command not found` | Install Claude Code and run again |
 | Where is my report? | `<repo>/.cw/runs/<id>/report.md` |
+| `Missing required input: question` | Add `-q "<question>"` — CW now prints this same `Try:` line for you |
+| Run stopped before the end | `cw quickstart <app> --resume --run <id>` takes it to the end (`cw run resume <id> --drive` does the same) |
+| What flags does a command take? | `cw help doctor`, `cw help quickstart`, `cw help ledger` now list a `Flags` block under the command |
+
+## Repo Map
+
+What every top-level folder and file is for, one line each. Most of these
+places are fixed by a tool, a test, or the release chain — they are where
+they are for a reason.
+
+| Place | What it is |
+|---|---|
+| [`plugins/cool-workflow/`](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/) | The product itself: TypeScript source (`src/`), committed build (`dist/`), tests, scripts, man-page docs, manifests |
+| [`docs/`](https://github.com/coo1white/cool-workflow/blob/main/docs/) | Repo-level docs: wiki source, audits, benchmark notes, the v2 rebuild SPEC, architecture plans |
+| [`v2/conformance/`](https://github.com/coo1white/cool-workflow/blob/main/v2/conformance/) | Black-box conformance suite — pins the shipping CLI's observable behavior byte for byte; CI runs it on every PR |
+| [`eval/`](https://github.com/coo1white/cool-workflow/blob/main/eval/) | Eval cases for the four workflow skills (ci-triage, pr-review, design-qa, deploy-check) |
+| [`examples/`](https://github.com/coo1white/cool-workflow/blob/main/examples/) | Worked examples, e.g. a real published self-audit with line-cited findings |
+| [`scripts/bench/`](https://github.com/coo1white/cool-workflow/blob/main/scripts/bench/) | The benchmark runner (see [docs/benchmark.md](https://github.com/coo1white/cool-workflow/blob/main/docs/benchmark.md)) |
+| [`Formula/`](https://github.com/coo1white/cool-workflow/blob/main/Formula/) | Homebrew formula — `brew` only finds it at this exact path |
+| `.cw-release/` | Append-only release trust records: gate markers, signed reviewer verdicts. Never edit or delete by hand |
+| `.github/` | CI workflows: build/test matrix, conformance, CodeQL, gitleaks, release gate, npm publish |
+| `.claude-plugin/`, `.agents/plugins/` | Plugin/marketplace manifests so LLM clients can discover CW |
+| [`AGENTS.md`](https://github.com/coo1white/cool-workflow/blob/main/AGENTS.md) / [`CLAUDE.md`](https://github.com/coo1white/cool-workflow/blob/main/CLAUDE.md) / [`Codex.md`](https://github.com/coo1white/cool-workflow/blob/main/Codex.md) | The binding rules for coding agents working ON this repo; the agents auto-load these from the root |
+| [`DIRECTION.md`](https://github.com/coo1white/cool-workflow/blob/main/DIRECTION.md) | Where the project goes — and, on purpose, does not go |
+| [`PROJECT_MEMORY.md`](https://github.com/coo1white/cool-workflow/blob/main/PROJECT_MEMORY.md) | Long-term project memory: lessons that must outlive any one session |
+| [`ITERATION_LOG.md`](https://github.com/coo1white/cool-workflow/blob/main/ITERATION_LOG.md) | Append-only development cycle log; the release gate reads it for the cadence check |
+| [`CHANGELOG.md`](https://github.com/coo1white/cool-workflow/blob/main/CHANGELOG.md) / [`RELEASE.md`](https://github.com/coo1white/cool-workflow/blob/main/RELEASE.md) | Release notes (each entry goes into the GitHub Release as-is) / the release runbook |
 
 ## Docs & Wiki
 
@@ -201,7 +354,8 @@ Building on CW? See the [Getting Started doc](https://github.com/coo1white/cool-
 [Project Index](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/project-index.md), and
 [CLI ↔ MCP Parity](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/cli-mcp-parity.7.md).
 
-CW dogfoods its own release process — every cut runs the `release-cut` workflow against this repo.
+CW dogfoods its own release process — it runs its own tool on itself, and
+every cut runs the `release-cut` workflow against this repo.
 
 ## License
 

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.2.4",
+  "version": "0.2.5",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

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.2.4",
+  "version": "0.2.5",
   "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.2.4",
+  "version": "0.2.5",
   "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.2.4",
+  "version": "0.2.5",
   "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.2.4",
+  "version": "0.2.5",
   "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.2.4",
+  "version": "0.2.5",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/cli/dispatch.js

@@ -21,6 +21,7 @@
 // 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.shouldRenderHuman = shouldRenderHuman;
 exports.dispatch = dispatch;
 const help_1 = require("../core/format/help");
 const capability_table_1 = require("../core/capability-table");
@@ -28,18 +29,41 @@ 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 cli_args_1 = require("../core/util/cli-args");
+const global_flags_1 = require("./global-flags");
 function firstPositional(args, index = 0) {
     return args.positionals[index];
 }
+/** The one rendering-mode decision for a `jsonMode: "default"` row's
+ *  OPTIONAL human projection (CliBinding.humanRender): true ONLY when the
+ *  row is "default", the caller did NOT ask for JSON (`--json`/`--format
+ *  json`), the row declares a humanRender, AND stdout is a real TTY.
+ *  Every other combination — every pipe, every script, every conformance
+ *  run — stays byte-identical JSON. Deliberately does NOT read
+ *  FORCE_COLOR/NO_COLOR: color env vars style output, they never pick
+ *  the output mode (cli-color-env pipes with FORCE_COLOR=1 and must stay
+ *  JSON). Pure of the injectable `stream` (default process.stdout),
+ *  following shell/workbench-host.ts's printServeHint pattern. */
+function shouldRenderHuman(jsonMode, options, hasHumanRender, stream = process.stdout) {
+    return jsonMode === "default" && !(0, cli_args_1.wantsJson)(options) && hasHumanRender && Boolean(stream.isTTY);
+}
 /** 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).
+ *     `result.text` when a row has no canonical JSON shape). On a real
+ *     TTY, a row that declares `humanRender` prints that human text
+ *     instead (see shouldRenderHuman above — piped bytes never change).
  *   - `"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, cli_args_1.wantsJson)(options));
+function renderCliResult(result, cli, options) {
+    if (shouldRenderHuman(cli.jsonMode, options, Boolean(cli.humanRender)) && result.json !== undefined) {
+        const human = cli.humanRender(result.json);
+        process.stdout.write(human.endsWith("\n") ? human : `${human}\n`);
+        if (result.exitCode !== undefined)
+            process.exitCode = result.exitCode;
+        return;
+    }
+    const useJson = cli.jsonMode === "default" || (cli.jsonMode === "flag" && (0, cli_args_1.wantsJson)(options));
     if (useJson && result.json !== undefined) {
         (0, io_1.printJson)(result.json);
     }
@@ -75,8 +99,12 @@ async function dispatchTable(args) {
             positionals: args.positionals.slice(consumed),
             options: args.options,
         };
+        // Rows that declare a complete flag list get the TTY-only unknown-flag
+        // warning (one stderr line; stdout and the exit code never change —
+        // see cli/global-flags.ts).
+        (0, global_flags_1.warnUnknownFlags)(row.cli, args.options);
         const result = await row.cli.handler(cliArgs);
-        renderCliResult(result, row.cli.jsonMode, args.options);
+        renderCliResult(result, row.cli, args.options);
         return true;
     }
     return false;