cool-workflow 0.1.91 → 0.1.93

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

@@ -34,7 +34,7 @@ const { spawn, spawnSync } = require("node:child_process");
 // wrappers instead of carrying a private copy. A drifted inline copy (ASCII
 // hyphens silently became em-dashes here) meant claude was sent a different
 // instruction text than the other providers for the same contract.
-const { buildPrompt, createRenderer } = require("./agent-adapter-core");
+const { buildPrompt, createRenderer, toolLabel, summarizeToolResult } = require("./agent-adapter-core");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -78,17 +78,17 @@ if (!streamEnabled) {
   process.exit(0);
 }
 
-function shortInput(tool, input) {
+// The shared `toolLabel` (from the core) renders `ToolName(basename)` — the Claude-tree label format
+// every vendor uses, so the look can't drift between wrappers.
+function pickInput(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}` : "";
+  return input.file_path || input.path || input.pattern || input.command || input.query || input.url || "";
 }
 
 // The live view (spinner + folding actions on a TTY, plain append-only when piped, silent when
 // CW_AGENT_STREAM=0) + cursor hygiene + an always-on-disk transcript live in the shared core.
 void traceEnabled; // superseded by the renderer (which does its own TTY/stream gating)
-const render = createRenderer({ env: process.env, stderr: process.stderr });
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "claude" });
 const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
 
 // stream-json so claude emits incremental NDJSON events we render live. We CAPTURE claude's
@@ -128,6 +128,13 @@ child.stdout.on("data", (chunk) => {
   }
 });
 
+const toolIds = new Map(); // tool_use id -> tool name, so a later tool_result can name its tool
+function toolResultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((b) => (b && typeof b.text === "string" ? b.text : "")).join("\n");
+  return "";
+}
+
 function renderEvent(ev) {
   if (ev.type === "assistant" && ev.message) {
     if (!model && typeof ev.message.model === "string") model = ev.message.model;
@@ -135,7 +142,17 @@ function renderEvent(ev) {
       if (part.type === "text" && part.text && part.text.trim()) {
         render.text(part.text.trim());
       } else if (part.type === "tool_use") {
-        render.action(`${part.name}${shortInput(part.name, part.input)}`);
+        if (part.id) toolIds.set(part.id, part.name);
+        render.action(toolLabel(part.name, pickInput(part.input)), part.id);
+      }
+    }
+  } else if (ev.type === "user" && ev.message) {
+    // claude runs the tools itself (headless -p) and echoes each result back as a tool_result block;
+    // summarize it into the `⎿` tree line for the tool it belongs to.
+    for (const part of ev.message.content || []) {
+      if (part && part.type === "tool_result") {
+        const name = toolIds.get(part.tool_use_id) || "";
+        render.result(summarizeToolResult(name, toolResultText(part.content), part.is_error), part.is_error, part.tool_use_id);
       }
     }
   } else if (ev.type === "system" && ev.subtype === "post_turn_summary" && ev.status_detail) {

package/scripts/agents/codex-agent.js

@@ -42,7 +42,7 @@ try {
 }
 
 const prompt = buildPrompt(inputPath);
-const render = createRenderer({ env: process.env, stderr: process.stderr });
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "codex" });
 const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
 const state = { provider: "codex", buffer: "", model: undefined, usage: undefined, renderer: render };
 const capturedStdout = [];

package/scripts/agents/gemini-agent.js

@@ -33,7 +33,7 @@ if (!inputPath || !resultPath) {
 }
 
 const prompt = buildPrompt(inputPath);
-const render = createRenderer({ env: process.env, stderr: process.stderr });
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "gemini" });
 const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
 const state = { provider: "gemini", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined, renderer: render };
 let childStderr = "";

package/scripts/agents/opencode-agent.js

@@ -38,7 +38,7 @@ if (!inputPath || !resultPath) {
 }
 
 const prompt = buildPrompt(inputPath);
-const render = createRenderer({ env: process.env, stderr: process.stderr });
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "opencode" });
 const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
 const state = { provider: "opencode", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined, renderer: render };
 let childStderr = "";

package/scripts/architecture-review-fast.js

@@ -38,13 +38,20 @@ function main() {
   const fastModel = stringArg(args.fastModel || args["fast-model"]);
   const strongModel = stringArg(args.strongModel || args["strong-model"]);
   const modelEnv = modelPolicyEnv(fastModel, strongModel);
+  // Opt-in incremental overlay: scope the exported source context to files
+  // changed since REF (e.g. origin/main). The source-context export resolves
+  // the ref, keys its cache separately, and records the base. The fast review
+  // then runs over the narrower context; the scheduled full review stays a
+  // complete audit (see scheduleFullReview).
+  const changedFrom = stringArg(args.changedFrom || args["changed-from"]);
 
   const contextExport = timed(() => exportSourceContext({
     repo,
     profile,
     ref,
     profileFile,
-    cacheDir
+    cacheDir,
+    changedFrom
   }));
   const contextText = contextExport.value;
   assertNonEmptySourceContext(contextText, profile, repo);
@@ -87,7 +94,8 @@ function main() {
     digest,
     profile,
     ref,
-    cacheDir
+    cacheDir,
+    ...(changedFrom ? { changedFrom } : {})
   };
   const fullReviewScheduleRun = truthy(args.scheduleFull || args["schedule-full"])
     ? timed(() => scheduleFullReview(repo, question, args, fastReview, sourceContextMeta))
@@ -101,7 +109,7 @@ function main() {
     fastReview,
     ...(fastModel || strongModel ? { modelPolicy: { ...(fastModel ? { fastModel } : {}), ...(strongModel ? { strongModel } : {}) } } : {}),
     ...(fullReviewSchedule ? { fullReviewSchedule } : {}),
-    ...(includeMetrics ? { metrics: buildMetrics(started, contextText, contextExport.elapsedMs, fastReview, fastReviewRun.elapsedMs, fullReviewScheduleRun?.elapsedMs) } : {})
+    ...(includeMetrics ? { metrics: buildMetrics(started, contextText, contextExport.elapsedMs, fastReview, fastReviewRun.elapsedMs, fullReviewScheduleRun?.elapsedMs, changedFrom) } : {})
   });
 }
 
@@ -119,6 +127,7 @@ function exportSourceContext(options) {
     options.cacheDir
   ];
   if (options.profileFile) argv.push("--profile-file", path.resolve(options.profileFile));
+  if (options.changedFrom) argv.push("--changed-from", options.changedFrom);
   const result = spawnSync(node, argv, {
     cwd: repoRoot,
     encoding: "utf8",
@@ -194,6 +203,9 @@ function scheduleFullReview(repo, question, args, fastReview, sourceContextMeta)
     fastReview?.reportPath ? `Fast review report: ${fastReview.reportPath}.` : "",
     `Fast review status: ${fastReview?.status || "unknown"} (${fastReview?.completedWorkers || 0}/${fastReview?.plannedWorkers || 0} workers completed).`,
     `Source context: ${sourceContextMeta.path} (${sourceContextMeta.digest}, profile ${sourceContextMeta.profile}, ref ${sourceContextMeta.ref}).`,
+    sourceContextMeta.changedFrom
+      ? `Fast review used an incremental overlay (changed-from ${sourceContextMeta.changedFrom}); this full review must audit the complete source, not only the changed files.`
+      : "",
     "Use the completed architecture-review-fast report as the foreground triage result; write the full review report path and digest when the background review finishes."
   ].filter(Boolean).join(" ");
   return runCwJson([
@@ -304,7 +316,7 @@ function timed(fn) {
   return { value, elapsedMs: elapsedMs(started) };
 }
 
-function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview, fastReviewElapsedMs, fullReviewScheduleElapsedMs) {
+function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview, fastReviewElapsedMs, fullReviewScheduleElapsedMs, changedFrom) {
   const steps = Array.isArray(fastReview?.steps) ? fastReview.steps : [];
   const handleKinds = countBy(steps.map((step) => step && step.handleKind).filter(Boolean));
   const actions = countBy(steps.map((step) => step && step.action).filter(Boolean));
@@ -314,7 +326,8 @@ function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview,
     sourceContext: {
       elapsedMs: sourceContextElapsedMs,
       bytes: Buffer.byteLength(contextText, "utf8"),
-      digest: `sha256:${crypto.createHash("sha256").update(contextText, "utf8").digest("hex")}`
+      digest: `sha256:${crypto.createHash("sha256").update(contextText, "utf8").digest("hex")}`,
+      ...(changedFrom ? { changedFrom } : {})
     },
     fastReview: {
       elapsedMs: fastReviewElapsedMs,
@@ -388,6 +401,7 @@ function usage(code) {
     "",
     "options:",
     "  --profile core --ref HEAD --profile-file PATH --cache-dir DIR --context-out PATH",
+    "  --changed-from REF   (incremental overlay: scope context to files changed since REF)",
     "  --fast-model MODEL --strong-model MODEL",
     "  --invariant TEXT --focus TEXT --preview --once",
     "  --schedule-full [--full-delay-minutes N]",

package/scripts/bump-version.js

@@ -143,6 +143,22 @@ function main() {
     note(rel);
   }
 
+  // 5c. Homebrew formula (repo root, not under pluginRoot). Structured surface:
+  //     a git-tag formula with no sha256. Homebrew reads the version from the
+  //     tag, so the ONLY literal that moves is `tag: "v<version>"` (an explicit
+  //     `version` line would be redundant and brew audit rejects it). A targeted
+  //     exact-string swap keeps the file byte-formatting intact;
+  //     version-sync-check.js asserts the tag at HEAD, so it can never drift.
+  const formula = path.join(repoRoot, "Formula", "cool-workflow.rb");
+  if (fs.existsSync(formula)) {
+    const text = fs.readFileSync(formula, "utf8");
+    const updated = text.split(`tag: "v${current}"`).join(`tag: "v${next}"`);
+    if (updated !== text) {
+      fs.writeFileSync(formula, updated);
+      note("Formula/cool-workflow.rb");
+    }
+  }
+
   process.stdout.write(`bump:version ${current} -> ${next}\n`);
   for (const rel of touched) process.stdout.write(`  updated  ${rel}\n`);
 
@@ -167,7 +183,10 @@ function contentSurfaceFiles(next) {
   // All files the version-sync-check script validates for VERSION or vX.Y.Z.
   // Keep in sync with scripts/version-sync-check.js.
   return [
-    { path: "plugins/cool-workflow/README.md", needle: `v${next}`,          desc: "README version tag" },
+    // The npm package README (plugins/cool-workflow/README.md) is GENERATED from the GitHub
+    // README.md by scripts/sync-readme.js and shows the version via the live npm/release shields
+    // badges, not a hand-maintained literal — so it is NOT a version-bump surface. After a bump,
+    // `npm run sync:readme` keeps it byte-identical to the GitHub README (guarded by readme:check).
     { path: "plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md",   needle: next, desc: "multi-agent CLI/MCP surface doc" },
     { path: "plugins/cool-workflow/docs/multi-agent-operator-ux.7.md",       needle: next, desc: "multi-agent operator UX doc" },
     { path: "plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", needle: next, desc: "multi-agent eval/replay doc" },

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.91",
+      "Cool Workflow v0.1.93",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.1.91");
+    assert.equal(summary.version, "0.1.93");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.1.91");
+    assert.equal(shown.app.version, "0.1.93");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.1.91");
+    assert.equal(state.workflow.app.version, "0.1.93");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
 
-const TARGET_VERSION = "0.1.91";
+const TARGET_VERSION = "0.1.93";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.91");
+    assert.equal(appValidation.summary.version, "0.1.93");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.91 end-to-end golden path."
+        "Prove the deterministic v0.1.93 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.91");
+    assert.equal(state.workflow.app.version, "0.1.93");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.91/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.93/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/parity-check.js

@@ -69,7 +69,15 @@ function cliDispatchTokens() {
 }
 
 function cliDispatchSources() {
-  return [cli, path.join(pluginRoot, "dist", "cli", "command-surface.js")].filter((file) => fs.existsSync(file));
+  // The dispatcher + every per-command handler module carved out of it (the
+  // command-surface god-object decomposition). A verb's subcommand `case`s may
+  // live in dist/cli/handlers/<group>.js, so scan those too or their tokens read
+  // as "missing from dist/cli.js".
+  const handlersDir = path.join(pluginRoot, "dist", "cli", "handlers");
+  const handlerFiles = fs.existsSync(handlersDir)
+    ? fs.readdirSync(handlersDir).filter((name) => name.endsWith(".js")).map((name) => path.join(handlersDir, name))
+    : [];
+  return [cli, path.join(pluginRoot, "dist", "cli", "command-surface.js"), ...handlerFiles].filter((file) => fs.existsSync(file));
 }
 
 function cliHelpTokens() {

package/scripts/release-check.js

@@ -74,7 +74,11 @@ const checks = [
   // drifted from a fresh source scan. The teeth-on-the-gate live in
   // test/project-index-sync-smoke.js (run by `npm test`); this entry gives the
   // real-doc check its own visible PASS/FAIL line in the release summary.
-  { name: "project index sync", command: ["npm", "run", "index:check"] }
+  { name: "project index sync", command: ["npm", "run", "index:check"] },
+  // Fail closed if the npm README (plugins/cool-workflow/README.md) has drifted
+  // from the GitHub README.md it is generated from. Keeps the two pages identical
+  // by construction; teeth live in test/readme-sync-smoke.js (run by `npm test`).
+  { name: "readme sync", command: ["npm", "run", "readme:check"] }
 ];
 
 function main() {

package/scripts/sync-readme.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+
+// sync-readme — keep the npm package README in lockstep with the GitHub README.
+//
+// The repo-root README.md is the SINGLE SOURCE OF TRUTH. This generates the npm
+// page (plugins/cool-workflow/README.md) from it, changing ONLY what npm needs to
+// render: relative URLs become absolute, because npm cannot resolve a repo's
+// relative `docs/assets/...` image paths or `](LICENSE)` links the way GitHub can.
+//
+//   <img src="docs/assets/x.svg">  ->  raw.githubusercontent.com/<owner>/<repo>/main/docs/assets/x.svg
+//   ](LICENSE) / ](plugins/...)     ->  github.com/<owner>/<repo>/blob/main/...
+//
+// The text content is otherwise identical, so the two pages can never drift.
+//
+// --check : regenerate in memory, compare to the committed npm README, write
+//           nothing, exit non-zero on drift (the release/CI gate). Mirrors
+//           sync-project-index.js. Fork-safe: the owner/repo in the absolute URLs
+//           is normalized out of the compare, so a fork clone never false-REDs.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+const sourceReadme = path.join(repoRoot, "README.md");
+// CW_README_PATH overrides the npm README that --check compares against (used by
+// the smoke to point --check at a throwaway drifted fixture). Default: the real one.
+const targetReadme = process.env.CW_README_PATH
+  ? path.resolve(process.env.CW_README_PATH)
+  : path.join(pluginRoot, "README.md");
+
+const repoUrl = normalizeGitRemote(git(["config", "--get", "remote.origin.url"]).trim())
+  || "https://github.com/coo1white/cool-workflow";
+const ownerRepo = repoUrl.replace(/^https:\/\/github\.com\//, "");
+const RAW_BASE = `https://raw.githubusercontent.com/${ownerRepo}/main`;
+const BLOB_BASE = `${repoUrl}/blob/main`;
+
+const MARKER =
+  "<!-- 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. -->";
+
+const CHECK = process.argv.includes("--check");
+
+function render() {
+  if (!fs.existsSync(sourceReadme)) {
+    process.stderr.write(`sync-readme FAILED: source ${path.relative(repoRoot, sourceReadme)} does not exist.\n`);
+    process.exit(1);
+  }
+  const source = fs.readFileSync(sourceReadme, "utf8");
+  // NOTE: a relative path must be free of a literal "(", ")", or '"' — the [^)]+ / [^"]+
+  // captures below stop at those. The repo README has none; readme:check catches any drift.
+  const absolutized = source
+    // HTML image sources: <img src="docs/assets/x.svg"> -> raw URL (skip already-absolute / anchors)
+    .replace(/\bsrc="(?!https?:|#|data:)([^"]+)"/g, (_m, rel) => `src="${RAW_BASE}/${rel}"`)
+    // Markdown links: ](LICENSE) / ](plugins/...) -> blob URL (skip absolute / in-page anchors / mailto)
+    .replace(/\]\((?!https?:|#|mailto:)([^)]+)\)/g, (_m, rel) => `](${BLOB_BASE}/${rel})`);
+  return `${MARKER}\n${absolutized}`;
+}
+
+function normalizeForCompare(text) {
+  // Strip the owner/repo from the generated absolute URLs so a fork (whose git
+  // remote differs) does not false-RED against the canonical committed README.
+  // The CONTENT is what this gate guards; the owner/repo is environment-derived.
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(/https:\/\/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/main/g, "<RAW>")
+    .replace(/https:\/\/github\.com\/[^/]+\/[^/]+\/blob\/main/g, "<BLOB>");
+}
+
+function main() {
+  const rendered = render();
+  const rel = path.relative(repoRoot, targetReadme);
+
+  if (CHECK) {
+    if (!fs.existsSync(targetReadme)) {
+      process.stderr.write(`readme check FAILED: ${rel} does not exist.\nRun: (cd plugins/cool-workflow && npm run sync:readme)\n`);
+      process.exit(1);
+    }
+    const committed = normalizeForCompare(fs.readFileSync(targetReadme, "utf8"));
+    const fresh = normalizeForCompare(rendered);
+    if (committed === fresh) {
+      process.stdout.write(`${JSON.stringify({ ok: true, check: true, source: "README.md", doc: rel }, null, 2)}\n`);
+      return;
+    }
+    const a = committed.split("\n");
+    const b = fresh.split("\n");
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i]) i++;
+    process.stderr.write(
+      `readme check FAILED: ${rel} is stale (does not match the GitHub README.md).\n` +
+      `First difference at line ${i + 1}:\n` +
+      `  committed: ${JSON.stringify(a[i] ?? "<missing>")}\n` +
+      `  expected:  ${JSON.stringify(b[i] ?? "<missing>")}\n` +
+      `Regenerate with: (cd plugins/cool-workflow && npm run sync:readme)\n`
+    );
+    process.exit(1);
+  }
+
+  fs.writeFileSync(targetReadme, rendered, "utf8");
+  process.stdout.write(`${JSON.stringify({
+    ok: true,
+    source: "README.md",
+    output: rel,
+    repoUrl
+  }, null, 2)}\n`);
+}
+
+function git(args) {
+  const result = spawnSync("git", args, { cwd: repoRoot, encoding: "utf8" });
+  return result.status === 0 ? result.stdout : "";
+}
+
+function normalizeGitRemote(remote) {
+  if (!remote) return "";
+  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
+  const sshMatch = remote.match(/^git@github\.com:(.+)$/);
+  if (sshMatch) return `https://github.com/${sshMatch[1]}`;
+  return remote;
+}
+
+main();

package/scripts/version-sync-check.js

@@ -92,7 +92,11 @@ function main() {
   checkIncludes("plugins/cool-workflow/dist/mcp-server.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
   checkIncludes("plugins/cool-workflow/dist/workflow-app-framework.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
 
-  checkIncludes("plugins/cool-workflow/README.md", `v${VERSION}`, checks);
+  // The npm package README (plugins/cool-workflow/README.md) is GENERATED from the GitHub
+  // README.md (scripts/sync-readme.js) and conveys the version via the live npm/release shields
+  // badges — not a hand-maintained literal — exactly like the GitHub page. It is no longer
+  // version-pinned here; readme:check guards that the two pages stay identical, and the surfaces
+  // above (version.ts/dist/package.json/manifests/docs) still pin the release.
   checkIncludes("plugins/cool-workflow/docs/index.md", "release and migration", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-topologies.7.md", "Multi-Agent Topologies", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md", VERSION, checks);
@@ -192,6 +196,11 @@ function main() {
   checkIncludes("plugins/cool-workflow/docs/release-and-migration.7.md", VERSION, checks);
   checkIncludes("CHANGELOG.md", `## ${VERSION}`, checks);
   checkIncludes("RELEASE.md", VERSION, checks);
+  // Homebrew formula (repo root): git-tag formula. Homebrew scans the version
+  // from the tag, so the tag is the single version surface to gate (an explicit
+  // `version` line would be redundant and brew audit rejects it). bump-version.js
+  // moves this tag.
+  checkIncludes("Formula/cool-workflow.rb", `tag: "v${VERSION}"`, checks);
   checkIncludes("plugins/cool-workflow/skills/cool-workflow/SKILL.md", "release:check", checks);
 
   process.stdout.write(