cool-workflow 0.1.86 → 0.1.88

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "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,119 +1,139 @@
+<div align="center">
+
 # Cool Workflow
 
-```text
-══════════════════════════════════════════════════════════════════════
-  auditable agent-workflow control-plane — delegate, don't execute
-  plan → dispatch → record → verify → commit → report
-══════════════════════════════════════════════════════════════════════
-```
+**Get a saved, cited report from your AI agent — not a chat message you lose.**
 
 [![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/cool-workflow?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/cool-workflow)
 [![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads)](https://www.npmjs.com/package/cool-workflow)
+[![provenance](https://img.shields.io/badge/npm-provenance-3178C6?style=flat-square)](https://www.npmjs.com/package/cool-workflow)
 [![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)](../../LICENSE)
+[![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](https://github.com/coo1white/cool-workflow/blob/main/LICENSE)
 ![MCP](https://img.shields.io/badge/MCP-native-8A2BE2?style=flat-square)
 ![runtime](https://img.shields.io/badge/runtime-TypeScript%20%C2%B7%20Node-3178C6?style=flat-square)
 
-**[Start Here](#start-here)** · [Quickstart](#quickstart) · [Developer Loop](#developer-loop) · [Commands](#commands) · [Release History](docs/release-history.md)
+<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cool-workflow-readme-promo.png" alt="Cool Workflow turns AI agent repo questions into saved, cited, tamper-evident reports." width="100%">
 
-Cool Workflow, or CW, is a free-standing agent workflow control-plane put up as a
-TypeScript runtime. It gives a COL-Architecture: Router / Orchestrator,
-Subagent Dispatch, Deterministic Harness, Adversarial Verifier, Git/State
-Commit, and MCP JSON-RPC 2.0 bridge.
+</div>
 
-The way to see it is a base system plus userland apps: CW gives the runtime and
-contracts, while makers write apps they can use again in
-`apps/<app-id>/app.json`. Old `workflows/*.workflow.js` files still
-load as fit-together wrappers.
+> An auditable agent-workflow control-plane — **delegate, don't execute**.
+> `plan → dispatch → record → verify → commit → report`
 
-CW writes down the model workflow loop in a clear way:
+## Install
 
-```text
-interpret -> act -> observe -> adjust -> checkpoint
+```bash
+npm install -g cool-workflow
 ```
 
-These loop stages are kept in `state.json`, task records, reports, and state
-commit snapshots.
-
-CW keeps orchestration state and task queues in files. An agent host does
-the tasks and gives results back to the workflow.
-
-CW keeps to a small set of Unix-based workflow rules: small kernel,
-clear state, pipes that join, workers kept apart, and verifier-gated commits.
-See [docs/unix-principles.md](docs/unix-principles.md).
+What you need: **Node.js v18+** (`node --version`) and one AI agent CLI on your machine
+(`claude`, `codex`, `gemini`, or `opencode`). No agent? `cw demo` still works — CW never runs a model itself.
 
-## Start Here
+## Quick Start (3 steps)
 
-Use the short path first. The long notes below are history and deep reference,
-not the first run.
+### 1. Prove it works (30 seconds, no agent needed)
 
 ```bash
 cw demo tamper
-cw doctor --onramp
-cw quickstart architecture-review --check --repo /path/to/repo \
-  --question "What are the main risks?" --agent-command builtin:claude
-cw quickstart architecture-review --repo /path/to/repo \
-  --question "What are the main risks?" --agent-command builtin:claude --bundle
-cw report verify-bundle report.cwrun.json
+# → VERDICT: tamper-evidence holds ✓
 ```
 
-For source work, keep the loop small:
+### 2. Run a review on your code — one command
 
 ```bash
-npm run build
-node test/<nearest-smoke>.js
-npm run test:fast
+cw -q "What are the main risks here?"
 ```
 
-Run `npm run release:check` only when the batch is ready for the full gate. Start
-with `quickstart` and `report` before the multi-agent pages.
+CW auto-detects the repo (current folder) and your agent (first found on PATH).
+Pick a specific agent with a flag:
 
-For the full capability and release history, see [docs/release-history.md](docs/release-history.md).
-This README tracks CW v0.1.85.
+```bash
+cw -q "What are the security risks?" -claude
+cw -q "What are the security risks?" -codex
+cw -q "What are the security risks?" -deepseek
+```
 
-## Quickstart
+You will see live streaming output as the agent works — no env vars needed.
 
-**30-second proof, no install** — see that a recorded telemetry verdict can't be faked:
+### 3. Open the report
 
 ```bash
-npx cool-workflow demo tamper
-# builds a signed ed25519 ledger, forges it 2 ways, both caught offline
-# -> VERDICT: tamper-evidence holds ✓
+cat .cw/runs/<run-id>/report.md
+# → findings with clickable file.ts:42 pointers for every claim
 ```
 
-**Try a real run** — no clone needed; drive an architecture review with your own agent:
+## What Else Can It Do?
 
 ```bash
-npx cool-workflow quickstart architecture-review --repo /path/to/repo \
-  --question "Is this architecture sound?" --agent-command builtin:claude
+cw version                        # show version
+cw update                         # update to latest release
+cw doctor                         # check your setup
+cw fix                            # show fix commands for setup issues
 ```
 
-Add `--bundle` when the report has to go to someone else; then check the file
-offline with `cw report verify-bundle report.cwrun.json`.
+| Workflow | Does |
+|---|---|
+| `architecture-review` | Map a repo, rank risks, back every claim with evidence |
+| `pr-review-fix-ci` | Review a pull request, suggest fixes, verify CI |
+| `research-synthesis` | Answer a question with fact-backed research |
+| `release-cut` | Run a gated, reviewed release |
+
+**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 keep iterating until a predicate or a token budget says stop) — and re-run fast:
+`cw run <app> --drive --incremental` reuses every step whose inputs didn't change.
 
-CW DELEGATES worker execution to your own agent. With no `--agent-command` (or
-`CW_AGENT_COMMAND`) the drive fails closed (status `blocked`) — it never makes up a
-result. `--agent-command builtin:claude` points to a bundled read-only `claude -p`
-wrapper (needs `claude` on your PATH).
+CW also has an **MCP** surface — **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.
 
-**Re-prove a finished run, offline** (`cw` is the installed bin; or `npx cool-workflow <cmd>`):
+## Can I Trust the Report?
+
+CW does not run the AI model — it keeps the books. The 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 telemetry verify <run-id>                  # re-checks the hash-chained ledger
-cw telemetry verify <run-id> --pubkey pub.pem # also re-runs ed25519 signature checks
-cw audit verify <run-id>                      # re-proves the trust-audit hash chain
+cw demo tamper                              # proves it in 30s — edits a signed result, watch it fail
+cw telemetry verify <run-id>                # checks a real run
+cw audit verify <run-id>                    # re-proves the trust-audit hash chain
 ```
 
-More: `cw quickstart <app> --preview` (read-only dry run), `cw run resume <run-id> --drive`
-(go on with a run that was stopped), `cw run inspect-archive <archive>` (integrity-check a
-portable run archive without bringing it in).
+Give the report to another person — they need nothing but the file:
+
+```bash
+cw -q "…" --bundle                              # seal into one portable file
+cw report verify-bundle report.cwrun.json       # they check it offline
+cw report verify-bundle report.cwrun.json \
+  --require-signatures                          # …and insist the findings are signed
+```
+
+This attests the agent's **signed findings** — not that the report holds nothing else, and not that
+none were left out. CW has no key to sign the rendered report, and a determined re-chainer can drop a
+signed finding entirely — so check the findings you act on against the signed results. For exactly
+what is and is not proven, see the [Trust Model](docs/trust-model.md).
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| No agent found | Run `cw doctor` — it shows which agents are on your machine |
+| `status: blocked` | CW failing closed (it never makes up a result). Set `CW_AGENT_COMMAND=builtin:claude` or pass `-claude`; `cw doctor` names the exact reason |
+| `claude: command not found` | Install Claude Code (`npm install -g @anthropic-ai/claude-code`) and run again |
+| Where is my report? | `<repo>/.cw/runs/<id>/report.md` |
+| Preflight before a spawn | `cw quickstart --check` — a zero-write check |
+
+---
+
+The rest of this README is the **developer / operator reference**: the build loop, repo
+structure, the full command surface, scheduling, and the result-envelope contract.
 
 ## Developer Loop
 
-Use the shortest check that fits the change:
+Use the shortest check that fits the change (from `plugins/cool-workflow/`):
 
 ```bash
+cd plugins/cool-workflow
 npm run build
 node test/<nearest-smoke>.js
 npm run test:fast
@@ -186,6 +206,22 @@ node scripts/cw.js app package architecture-review
 node scripts/cw.js app init my-app --title "My App"
 ```
 
+Compose flows from smaller verified ones (app-authoring surface, `workflow-api.ts`):
+
+- **Sub-workflow nesting** — a task can run a whole child app instead of one agent:
+  `subWorkflow(id, appId, { inputs?, bindResult? })`. The drive plans and drives the
+  child, then binds its report (or verdict result) back as the task's result, so the
+  parent's verifier/schema gate consumes it like any other. Leaf work stays external-agent
+  delegation at every depth; recursion is depth- and cycle-bounded, fail-closed.
+- **Bounded dynamic loops** — converge without unbounded recursion:
+  `loop(name, tasks, { maxRounds, until })` is a per-round template. After each round a
+  named, registered pure predicate (`until: { kind: "predicate", ref }`) decides whether to
+  append another round or stop, hard-capped at `maxRounds`; built-ins `no-new-findings` and
+  `single-round`. Or scale by budget — `until: { kind: "budget-target", target }` keeps
+  going while recorded (attested-only) usage stays under `target`, with the fail-closed
+  `limits.tokenBudget` cap as the absolute backstop. Predicates are registry refs (not
+  closures), so runs replay byte-identically; an unregistered predicate stops fail-closed.
+
 Create a reusable workflow script:
 
 ```bash
@@ -322,6 +358,7 @@ node scripts/cw.js registry refresh --scope home
 node scripts/cw.js run search --app architecture-review --status failed
 node scripts/cw.js run show <run-id>
 node scripts/cw.js run resume <run-id>
+node scripts/cw.js run resume <run-id> --drive --incremental   # re-drive, reusing every step whose inputs are unchanged
 node scripts/cw.js run rerun <failed-run-id> --reason "retry"
 node scripts/cw.js run archive <run-id> --reason "old"
 node scripts/cw.js queue add --app release-cut --priority 10
@@ -425,4 +462,10 @@ Verification and synthesis tasks need a structured result block:
 ```
 ````
 
-v0.1.86
+## 0.1.88 (v0.1.88)
+
+Orchestration-parity for the agent drive — inline `subWorkflow()` nesting, bounded dynamic `loop()` phases (a `predicate` or a `budget-target` token `until`), and `cw run --drive --incremental` step-level resume; the agent now signs its findings (result-bound ed25519) and `cw report verify-bundle --require-signatures` proves offline that every signed finding is in the report unaltered; CLI simplified to 6 commands with agent streaming on by default; path-traversal run ids refused on archive import.
+
+## 0.1.87 (v0.1.87)
+
+npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing

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

package/dist/agent-config.js

@@ -146,6 +146,31 @@ function agentConfigFromArgs(args) {
 // in scripts/agents/builtin-templates.json (vendor name -> wrapper script name).
 // Adding a vendor is a content/distribution step (drop a wrapper + a JSON line),
 // not a kernel edit — keeping CW vendor-agnostic at the source level.
+/** Detect which known agent CLIs are on PATH. Returns the first found, or undefined.
+ *  Skipped when CW_NO_AUTO_AGENT=1 (test sandboxes, CI without real agents). */
+function detectAgentFromPath(env = process.env) {
+    if (env.CW_NO_AUTO_AGENT === "1")
+        return undefined;
+    const known = ["claude", "codex", "gemini", "opencode"];
+    const dirs = (env.PATH || "").split(node_path_1.default.delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? (env.PATHEXT || ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const name of known) {
+        // Also check if the builtin template exists (so we don't suggest an unsupported agent).
+        const templates = builtinAgentTemplates();
+        if (!templates[name])
+            continue;
+        for (const dir of dirs) {
+            for (const ext of exts) {
+                try {
+                    if (node_fs_1.default.statSync(node_path_1.default.join(dir, name + ext)).isFile())
+                        return name;
+                }
+                catch { /* keep looking */ }
+            }
+        }
+    }
+    return undefined;
+}
 function builtinAgentTemplates() {
     const agentsDir = node_path_1.default.join(__dirname, "..", "scripts", "agents");
     const manifest = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(agentsDir, "builtin-templates.json"), "utf8"));
@@ -186,7 +211,23 @@ function resolveAgentConfig(args = {}, env = process.env) {
             : fileCfg && (fileCfg.command || fileCfg.endpoint)
                 ? "file"
                 : "none";
-    return { schemaVersion: 1, command, args: cfgArgs, endpoint, model, timeoutMs, attestPublicKey, requireAttestedTelemetry, source };
+    // Auto-detect: if no agent is configured, check PATH for known agent CLIs and
+    // resolve via builtin:<name>. This makes `cw quickstart` work without
+    // --agent-command on machines where claude/codex/gemini/opencode are installed.
+    let finalCommand = command;
+    let finalSource = source;
+    let finalModel = model;
+    if (!finalCommand && !endpoint) {
+        const detected = detectAgentFromPath(env);
+        if (detected) {
+            finalCommand = expandBuiltinAgentCommand(`builtin:${detected}`);
+            finalSource = "auto";
+            // Store the detected vendor name as the model hint so doctor can show it.
+            if (!finalModel)
+                finalModel = `builtin:${detected}`;
+        }
+    }
+    return { schemaVersion: 1, command: finalCommand, args: cfgArgs, endpoint, model: finalModel, timeoutMs, attestPublicKey, requireAttestedTelemetry, source: finalSource };
 }
 /** True iff a command-template OR endpoint is configured (after resolution). */
 function agentConfigured(args = {}, env = process.env) {

package/dist/capability-core.js

@@ -324,7 +324,8 @@ function reportBundle(runner, runId, args) {
     const verification = (0, run_export_1.verifyReportBundle)(exported.path, {
         pubkey: optionalString(args.pubkey || args.pubKey || args.publicKey),
         extractReportTo: extractReportTo ? node_path_1.default.resolve(base, extractReportTo) : undefined,
-        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs)
+        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs),
+        requireSignatures: Boolean(args["require-signatures"] || args.requireSignatures || args.requireSigs)
     });
     return {
         schemaVersion: 1,
@@ -349,7 +350,8 @@ function runVerifyReportBundle(_runner, args) {
     return (0, run_export_1.verifyReportBundle)(node_path_1.default.resolve(base, archive), {
         pubkey: optionalString(args.pubkey || args.pubKey || args.publicKey),
         extractReportTo: extractReportTo ? node_path_1.default.resolve(base, extractReportTo) : undefined,
-        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs)
+        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs),
+        requireSignatures: Boolean(args["require-signatures"] || args.requireSignatures || args.requireSigs)
     });
 }
 function queueAdd(reg, args) {
@@ -494,7 +496,8 @@ const DRIVE_RUNTIME_KEYS = [
     "agent-model",
     "agentTimeoutMs",
     "agent-timeout-ms",
-    "resume"
+    "resume",
+    "incremental"
 ];
 function planInputsFor(args) {
     const copy = withoutRuntimeKeys(args);
@@ -527,6 +530,7 @@ function runDrive(runner, args) {
     return (0, drive_1.drive)(runner.withBaseDir(target), driveRunId, {
         once: isTrue(args.once),
         now: optionalString(args.now),
+        incremental: isTrue(args.incremental),
         args
     });
 }
@@ -970,7 +974,8 @@ function auditVerify(runner, args) {
 }
 // ---- demo: tamper-evidence (the one-command proof) -------------------------
 // Hermetic, deterministic-shape: builds a real ed25519-signed telemetry ledger,
-// then forges it two ways and shows both tamper-evidence layers catch it. CLI-only
+// then forges it three ways and shows all three tamper-evidence layers (ledger,
+// signature, result) catch it. CLI-only
 // (a human-facing demonstration; the underlying verify is the telemetry.verify verb).
 function demoTamper(_runner, _args = {}) {
     return (0, telemetry_demo_1.runTamperDemo)();

package/dist/capability-registry.js

@@ -53,6 +53,30 @@ const BUILTIN_CAPABILITIES = [
         cli: { path: ["help"], jsonMode: "human" },
         reason: "Human help text. MCP hosts enumerate capabilities via tools/list, not a help command."
     },
+    {
+        capability: "version",
+        summary: "Print the current cool-workflow version.",
+        entry: "CURRENT_COOL_WORKFLOW_VERSION",
+        surface: "cli-only",
+        cli: { path: ["version"], jsonMode: "human" },
+        reason: "Version string — no structured data contract."
+    },
+    {
+        capability: "update",
+        summary: "Update cool-workflow to the latest release via npm.",
+        entry: "npmUpdate",
+        surface: "cli-only",
+        cli: { path: ["update"], jsonMode: "human" },
+        reason: "Self-update via npm — inherently local shell operation, no MCP surface."
+    },
+    {
+        capability: "fix",
+        summary: "Print consolidated fix commands for CW setup issues.",
+        entry: "runDoctor",
+        surface: "cli-only",
+        cli: { path: ["fix"], jsonMode: "human" },
+        reason: "Environment fix commands are local diagnostics, same reasoning as doctor."
+    },
     {
         capability: "list",
         summary: "List bundled CW workflows.",
@@ -61,6 +85,30 @@ const BUILTIN_CAPABILITIES = [
         cli: { path: ["list"], jsonMode: "default" },
         mcp: { tool: "cw_list" }
     },
+    {
+        capability: "info",
+        summary: "Show what a workflow app does: title, description, inputs, sandbox, phases, and a runnable example.",
+        entry: "showApp",
+        surface: "cli-only",
+        cli: { path: ["info"], jsonMode: "flag" },
+        reason: "Human-focused workflow discovery tool (like Homebrew's `brew info`). MCP agents discover workflows via cw_list and cw_app_show tools."
+    },
+    {
+        capability: "search",
+        summary: "Search workflow apps by keyword (title, description, id).",
+        entry: "listApps",
+        surface: "cli-only",
+        cli: { path: ["search"], jsonMode: "flag" },
+        reason: "Human-focused workflow discovery (like Homebrew's `brew search`). MCP agents discover workflows via cw_list tool."
+    },
+    {
+        capability: "man",
+        summary: "Show a man page from docs/ (e.g. cw man release-tooling).",
+        entry: "n/a",
+        surface: "cli-only",
+        cli: { path: ["man"], jsonMode: "human" },
+        reason: "Human documentation viewer. MCP agents read docs/ directly via file tools."
+    },
     {
         capability: "doctor",
         summary: "Diagnose the host for setup problems (Node version, agent backend, agent binary on PATH, git, writable home/repo state) and print an actionable fix per check.",