cool-workflow 0.1.78 → 0.1.80

package/docs/unix-principles.md

@@ -1,7 +1,10 @@
 # Unix-Inspired Workflow Principles
 
 CW borrows a small set of durable systems ideas and applies them to agent
-workflow engineering. These are design principles, not platform claims.
+workflow engineering. These are design principles, not platform claims — but
+they are not optional: this project strictly follows the FreeBSD programming
+philosophy, and §7 below states the binding rules every change is reviewed
+against (mirrored as hard constraints in the repository's `AGENTS.md`).
 
 ## 1. Everything Is State
 
@@ -190,3 +193,48 @@ Hosts enforce runtime sandbox policy.
 ```
 
 This keeps CW small, inspectable, and extensible.
+
+## 7. FreeBSD Discipline (Binding Rules)
+
+The principles above descend from one tradition — the FreeBSD school of
+systems engineering — and CW adheres to it strictly. Concretely:
+
+**POLA — Principle of Least Astonishment.** An existing output, file layout,
+exit code, or flag never changes meaning or bytes underneath an operator. New
+behavior ships behind a new verb/flag or an env toggle, with the prior
+behavior byte-identical by default. (Example: live drive output is additive —
+stderr only, TTY-gated, `CW_NO_STREAM=1` opt-out; the stdout payload and
+evidence digest are unchanged.)
+
+**Mechanism, not policy.** The kernel provides mechanisms; policy is data in
+userland. WHICH agent runs is config (`CW_AGENT_COMMAND` / agent-config), not
+code; vendor-specific rendering lives in wrappers under `scripts/agents/`,
+never in core. Core may forward a vendor's stream; it never parses one.
+
+**Rule of Silence.** stdout is data, stderr is diagnostics, and a
+non-interactive run is silent on success. Anything human-friendly is TTY-gated
+and can be disabled; `--json` output is stable and undecorated so it composes
+in pipes.
+
+**Fail closed, conservative defaults.** Unconfigured backends probe as
+`unverified`, unverifiable telemetry is surfaced loudly (or refused in strict
+mode), invalid results park the hop. CW never fabricates a success and never
+falls back silently. Boring correctness beats clever features.
+
+**Tools, not frameworks.** Zero runtime dependencies is a red line. Verbs do
+one thing; composition happens through durable files (`.cw/`) and pipes, not
+hidden in-process coupling.
+
+**Man pages are the contract.** Every shipped capability has a `docs/*.7.md`
+page updated in the same change, and doc-drift guards in the test suite keep
+the documented commands honest. Undocumented behavior is unfinished behavior.
+
+**style(9) spirit.** One consistent style per layer; a diff matches the file
+it touches and never reformats code it does not change.
+
+**Release engineering.** Main is -CURRENT; a tag is -RELEASE: it exists only
+after the deterministic gate and an independent review pass, and cadence never
+overrides the gate.
+
+A change that violates any rule in this section is rejected in review even if
+the capability it ships is otherwise desirable.

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

@@ -213,3 +213,9 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 0.1.77
 
 0.1.78
+
+0.1.79
+
+## Fast Architecture Review (v0.1.80)
+
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.

package/manifest/plugin.manifest.json

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

package/manifest/source-context-profiles.json

@@ -0,0 +1,142 @@
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "core": {
+      "description": "Default AI source context: runtime source, apps, package metadata, and agent wrappers; generated artifacts, tests, docs, release records, and long logs are manifest-only.",
+      "maxLines": 50000,
+      "include": [
+        "plugins/cool-workflow/src/**",
+        "plugins/cool-workflow/apps/**",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/tsconfig.json",
+        "plugins/cool-workflow/scripts/cw.js",
+        "plugins/cool-workflow/scripts/mcp-server.js",
+        "plugins/cool-workflow/scripts/agents/**"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "plugins/cool-workflow/docs/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    },
+    "runtime": {
+      "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
+      "maxLines": 40000,
+      "include": [
+        "plugins/cool-workflow/src/**",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/tsconfig.json"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "plugins/cool-workflow/docs/**",
+        "plugins/cool-workflow/apps/**",
+        "plugins/cool-workflow/scripts/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    },
+    "mcp": {
+      "description": "MCP and CLI surface context for capability registry, MCP server, CLI routing, and MCP launcher wrappers.",
+      "maxLines": 18000,
+      "include": [
+        "plugins/cool-workflow/src/capability-core.ts",
+        "plugins/cool-workflow/src/capability-registry.ts",
+        "plugins/cool-workflow/src/cli.ts",
+        "plugins/cool-workflow/src/mcp-server.ts",
+        "plugins/cool-workflow/src/types/**",
+        "plugins/cool-workflow/scripts/cw.js",
+        "plugins/cool-workflow/scripts/mcp-server.js",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/tsconfig.json"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "plugins/cool-workflow/docs/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    },
+    "workflow-apps": {
+      "description": "Workflow App framework and canonical app context without the full runtime kernel.",
+      "maxLines": 18000,
+      "include": [
+        "plugins/cool-workflow/apps/**",
+        "plugins/cool-workflow/src/workflow-app-framework.ts",
+        "plugins/cool-workflow/src/orchestrator.ts",
+        "plugins/cool-workflow/src/orchestrator/**",
+        "plugins/cool-workflow/src/types/workflow-app.ts",
+        "plugins/cool-workflow/src/types/run.ts",
+        "plugins/cool-workflow/scripts/canonical-apps.js",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/tsconfig.json"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "plugins/cool-workflow/docs/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    },
+    "release": {
+      "description": "Release-engineering context for gates, release flow, version sync, manifests, and package metadata.",
+      "maxLines": 12000,
+      "include": [
+        "AGENTS.md",
+        "plugins/cool-workflow/scripts/release-flow.js",
+        "plugins/cool-workflow/scripts/release-gate.sh",
+        "plugins/cool-workflow/scripts/dogfood-release.js",
+        "plugins/cool-workflow/scripts/gen-manifests.js",
+        "plugins/cool-workflow/scripts/version-sync-check.js",
+        "plugins/cool-workflow/scripts/bump-version.js",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/manifest/**",
+        "plugins/cool-workflow/docs/release-tooling.7.md"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    },
+    "agent-wrappers": {
+      "description": "External agent delegation wrappers and neutral backend configuration context.",
+      "maxLines": 14000,
+      "include": [
+        "plugins/cool-workflow/scripts/agents/**",
+        "plugins/cool-workflow/scripts/architecture-review-fast.js",
+        "plugins/cool-workflow/src/agent-config.ts",
+        "plugins/cool-workflow/src/execution-backend.ts",
+        "plugins/cool-workflow/src/drive.ts",
+        "plugins/cool-workflow/src/types/execution-backend.ts",
+        "plugins/cool-workflow/src/types/drive.ts",
+        "plugins/cool-workflow/package.json",
+        "plugins/cool-workflow/docs/agent-delegation-drive.7.md"
+      ],
+      "exclude": [
+        "plugins/cool-workflow/dist/**",
+        "plugins/cool-workflow/test/**",
+        "docs/assets/**",
+        ".cw-release/**",
+        "CHANGELOG.md",
+        "ITERATION_LOG.md"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -56,6 +56,7 @@
     "release:check": "node scripts/release-check.js",
     "test": "node dist/cli.js list && node test/run-all.js",
     "test:fast": "npm run build --if-present && node dist/cli.js list && node test/run-all.js --concurrency auto",
+    "test:coverage": "node dist/cli.js list && node scripts/coverage-gate.js",
     "eval:replay": "tsc -p tsconfig.json && node test/multi-agent-eval-replay-harness-smoke.js",
     "ci": "npm run build && npm run check && npm run test && npm run release:check",
     "validate:schema": "node scripts/validate-run-state-schema.js"

package/scripts/agents/claude-p-agent.js

@@ -5,27 +5,30 @@
 //
 // This is a CONFIG, NOT a CW dependency: CW spawns it out-of-process (argv-style,
 // shell:false, cwd = the target repo) and records its attested output; the model
-// runs in claude's process, never in CW. Node port of claude-p-agent.sh (which now
-// delegates here) so the documented onboarding path is portable (node-only repo
-// convention, Windows included).
+// runs in claude's process, never in CW.
 //
 // It fulfills ONE worker: read the worker's input.md ({{input}}), delegate the
 // analysis to headless claude READ-ONLY, persist claude's final markdown to the
-// worker's result.md ({{result}}), and forward claude's JSON (model + usage) on
-// stdout so CW records the agent-REPORTED model and token usage as provenance.
+// worker's result.md ({{result}}), and forward claude's JSON on STDOUT so CW
+// records the agent-reported provenance.
 //
-// READ-ONLY by design: claude gets NO Write tool. The architecture-review app
-// declares the `readonly` sandbox profile — the agent must not touch the repo.
-// This wrapper (the transport) writes the single result.md artifact itself, so
-// the worker completes WITHOUT granting the model file-write access.
+// LIVE OUTPUT (Unix discipline): default output is the legacy `--output-format
+// json` contract, forwarded verbatim on stdout. Set CW_AGENT_STREAM=1 to opt in
+// to claude `stream-json`; only then does this wrapper render a human-readable
+// trace to stderr, and only when stderr is a TTY. Diagnostics stay off stdout,
+// and vendor-specific stream parsing lives HERE in the wrapper (policy), not in
+// CW's core (which only forwards, never parses).
 //
-// Point CW at it (from plugins/cool-workflow/):
+// READ-ONLY by design: claude gets NO Write tool; the architecture-review app
+// declares the `readonly` sandbox profile. This wrapper (the transport) writes
+// the single result.md artifact itself, so the worker completes without granting
+// the model file-write access.
+//
+// Point CW at it (from plugins/cool-workflow/), or use the `builtin:claude` alias:
 //   CW_AGENT_COMMAND="node $(pwd)/scripts/agents/claude-p-agent.js {{input}} {{result}}"
-// or per-invocation:
-//   --agent-command "node $(pwd)/scripts/agents/claude-p-agent.js {{input}} {{result}}"
 
 const fs = require("node:fs");
-const { spawnSync } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -63,42 +66,125 @@ HARD RULES (the result is REJECTED otherwise):
 - "classification", if present, MUST be one of: real, conditional, non-issue, unknown.
 - Any finding with "severity" P0, P1, or P2 MUST include a NON-EMPTY "evidence" array.
 - The top-level "evidence" array MUST be NON-EMPTY with REAL file:line locators from this repo.
-- If you have no structured findings, use "findings": [] (empty) — never omit a finding's id.
-`;
+- If you have no structured findings, use "findings": [] (empty) — never omit a finding's id.`;
 
 const prompt = `${fs.readFileSync(inputPath, "utf8")}\n${CONTRACT}`;
+const streamEnabled = process.env.CW_AGENT_STREAM === "1" && process.env.CW_NO_STREAM !== "1";
+const traceEnabled = streamEnabled && Boolean(process.stderr.isTTY);
 
-// Read-only analysis: NO Write tool, so claude cannot touch the repo. This wrapper
-// (the transport) persists claude's final markdown to the worker's result.md.
-// --output-format json so CW can read the agent-REPORTED model + usage from stdout
-// (the attested model; CW never uses CW_AGENT_MODEL as the attested model).
-const child = spawnSync("claude", ["-p", prompt, "--output-format", "json", "--allowedTools", "Read,Grep,Glob,Bash"], {
-  encoding: "utf8",
-  maxBuffer: 32 * 1024 * 1024,
-  shell: false
-});
-if (child.error) {
-  process.stderr.write(`claude spawn failed: ${child.error.message}\n`);
-  process.exit(1);
+if (!streamEnabled) {
+  // Legacy default: --output-format json and verbatim stdout forwarding. This is
+  // the public wrapper contract existing users already scripted against.
+  const child = spawnSync("claude", ["-p", prompt, "--output-format", "json", "--allowedTools", "Read,Grep,Glob,Bash"], {
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    shell: false
+  });
+  if (child.error) {
+    process.stderr.write(`claude spawn failed: ${child.error.message}\n`);
+    process.exit(1);
+  }
+  if (child.status !== 0) {
+    process.stderr.write(String(child.stderr || `claude exited ${child.status}`));
+    process.exit(child.status === null ? 1 : child.status);
+  }
+
+  const out = String(child.stdout || "");
+  let parsed;
+  try {
+    parsed = JSON.parse(out);
+  } catch (error) {
+    process.stderr.write(`claude output was not JSON: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  fs.writeFileSync(resultPath, String(parsed.result || ""), "utf8");
+  process.stdout.write(out);
+  process.exit(0);
 }
-if (child.status !== 0) {
-  process.stderr.write(String(child.stderr || `claude exited ${child.status}`));
-  process.exit(child.status === null ? 1 : child.status);
+
+// Live trace → stderr only. Concise; one line per meaningful event.
+function trace(line) {
+  if (!traceEnabled) return;
+  process.stderr.write(`${line}\n`);
+}
+function shortInput(tool, input) {
+  if (!input || typeof input !== "object") return "";
+  const v = input.file_path || input.path || input.pattern || input.command || input.query || input.url || "";
+  const s = String(v).replace(/\s+/g, " ").trim();
+  return s ? ` ${s.length > 80 ? s.slice(0, 77) + "…" : s}` : "";
 }
 
-const out = String(child.stdout || "");
-let parsed;
-try {
-  parsed = JSON.parse(out);
-} catch (error) {
-  // Fail closed: no parsable agent JSON ⇒ no result.md ⇒ CW records a failed hop.
-  process.stderr.write(`claude output was not JSON: ${error.message}\n`);
-  process.exit(1);
+// stream-json so claude emits incremental NDJSON events we can render live, while
+// we reconstruct the single {model, usage, result} object CW consumes on stdout.
+const child = spawn(
+  "claude",
+  ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob,Bash"],
+  { stdio: ["ignore", "pipe", "inherit"] } // claude's own stderr → straight through
+);
+
+let model;
+let usage;
+let resultText;
+let buf = "";
+
+trace("● claude: reading the repo (read-only)…");
+
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue; // not a complete JSON line; ignore (defensive)
+    }
+    renderEvent(ev);
+  }
+});
+
+function renderEvent(ev) {
+  if (ev.type === "assistant" && ev.message) {
+    if (!model && typeof ev.message.model === "string") model = ev.message.model;
+    for (const part of ev.message.content || []) {
+      if (part.type === "text" && part.text && part.text.trim()) {
+        trace(`  ${part.text.trim().replace(/\n+/g, "\n  ")}`);
+      } else if (part.type === "tool_use") {
+        trace(`  → ${part.name}${shortInput(part.name, part.input)}`);
+      }
+    }
+  } else if (ev.type === "system" && ev.subtype === "post_turn_summary" && ev.status_detail) {
+    trace(`  · ${ev.status_detail}`);
+  } else if (ev.type === "result") {
+    if (typeof ev.result === "string") resultText = ev.result;
+    if (ev.usage && typeof ev.usage === "object") usage = ev.usage;
+    if (ev.is_error) trace("  ✗ claude reported an error result");
+  }
 }
 
-// Persist the AGENT's final markdown to the worker's result.md for CW's separate
-// acceptance layer. CW is only the transport; the content is the agent's.
-fs.writeFileSync(resultPath, String(parsed.result || ""), "utf8");
+child.on("error", (err) => {
+  process.stderr.write(`claude spawn failed: ${err.message}\n`);
+  process.exit(1);
+});
 
-// Hand the agent's JSON (model + usage + result) back to CW on stdout.
-process.stdout.write(out);
+child.on("close", (code) => {
+  if (code !== 0) {
+    process.stderr.write(`claude exited ${code === null ? "(timeout/killed)" : code}\n`);
+    process.exit(code === null ? 1 : code);
+  }
+  if (typeof resultText !== "string") {
+    // Fail closed: no result event ⇒ no result.md ⇒ CW records a failed hop.
+    process.stderr.write("claude produced no result event — refusing to fabricate a result\n");
+    process.exit(1);
+  }
+  // Persist the AGENT's final markdown to the worker's result.md (CW is transport).
+  fs.writeFileSync(resultPath, resultText, "utf8");
+  trace("● done — result captured");
+  // The single JSON CW consumes on STDOUT (data channel): model + usage + result.
+  process.stdout.write(JSON.stringify({ model, usage, result: resultText }));
+});