cool-workflow 0.1.78

package/skills/cool-workflow/references/commands.md

@@ -0,0 +1,282 @@
+# Cool Workflow — Command & MCP Reference
+
+Full CLI catalog and the matching MCP tool surface. The `SKILL.md` body covers
+the operating loop and the handful of commands you need most; come here when you
+need the exact invocation for a specific capability.
+
+Run CLI commands from the plugin root (`plugins/cool-workflow`) or with the
+absolute plugin script path. Run data is written to `.cw/runs/<run-id>/` under
+`--cwd`, or under `--repo` when `--cwd` is not given.
+
+## Contents
+
+- [Discovery & apps](#discovery--apps)
+- [Plan / dispatch / result / report](#plan--dispatch--result--report)
+- [Topologies](#topologies)
+- [Multi-agent host surface](#multi-agent-host-surface)
+- [Multi-agent low-level state](#multi-agent-low-level-state)
+- [Eval & replay](#eval--replay)
+- [Blackboard & coordinator](#blackboard--coordinator)
+- [Sandbox profiles](#sandbox-profiles)
+- [Commit, state & summaries](#commit-state--summaries)
+- [Scheduling & routines](#scheduling--routines)
+- [Release & maintenance npm scripts](#release--maintenance-npm-scripts)
+- [MCP tools](#mcp-tools)
+
+## Discovery & apps
+
+```bash
+node scripts/cw.js list
+node scripts/cw.js app list
+node scripts/cw.js app show architecture-review
+node scripts/cw.js app show pr-review-fix-ci
+node scripts/cw.js app show release-cut
+node scripts/cw.js app show research-synthesis
+node scripts/cw.js app validate apps/architecture-review/app.json
+node scripts/cw.js app show workflow-app-framework-demo
+node scripts/cw.js app validate apps/workflow-app-framework-demo/app.json
+node scripts/cw.js app validate end-to-end-golden-path
+node scripts/cw.js app package workflow-app-framework-demo
+node scripts/cw.js app init my-app --title "My App"
+node scripts/cw.js init my-workflow --title "My Workflow"
+```
+
+The canonical app ids are `architecture-review`, `pr-review-fix-ci`,
+`release-cut`, and `research-synthesis`. First-class apps live under
+`apps/<app-id>/app.json`; legacy `workflows/*.workflow.js` factories remain valid
+and are wrapped as compatibility apps with explicit `legacy-*` ids.
+
+## Portable release flow (any platform)
+
+```bash
+# Delegate the independent review to the model of this host (Codex shown):
+export CW_AGENT_COMMAND="codex exec {{input}}"
+node plugins/cool-workflow/scripts/release-flow.js --check
+node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 [--push]
+```
+
+One zero-dependency orchestrator runs the gate + independent reviewer under any
+harness; the reviewer is delegated via `CW_AGENT_COMMAND`/`CW_AGENT_ENDPOINT`
+(presets for Claude/Codex/Gemini/OpenCode/DeepSeek in `docs/release-tooling.7.md`).
+
+## Plan / dispatch / result / report
+
+```bash
+node scripts/cw.js plan architecture-review --repo /path/to/repo --question "Is this architecture sound?"
+node scripts/cw.js status <run-id>
+node scripts/cw.js status <run-id> --json
+node scripts/cw.js graph <run-id>
+node scripts/cw.js graph <run-id> --json
+node scripts/cw.js dispatch <run-id> --limit 6
+node scripts/cw.js dispatch <run-id> --sandbox readonly
+node scripts/cw.js result <run-id> <task-id> /path/to/result.md
+node scripts/cw.js report <run-id>
+node scripts/cw.js report <run-id> --show
+```
+
+Operator UX is human-readable by default for `status`, `graph`, report
+`--show`/`--summary`, and resource `summary` commands. Use `--json` or
+`--format json` when scripts or MCP-style integrations need structured output.
+Status recommendations are deterministic hints, not hidden automation.
+
+## Topologies
+
+Official userland recipes on top of the process table and shared coordination
+filesystem. `map-reduce`, `debate`, and `judge-panel` materialize ordinary run,
+role, group, fanout/fanin, blackboard, coordinator, candidate, commit, and audit
+records — deterministic recipes, not hidden autonomous coordination.
+
+```bash
+node scripts/cw.js topology list
+node scripts/cw.js topology show map-reduce
+node scripts/cw.js topology validate map-reduce
+node scripts/cw.js topology apply <run-id> map-reduce --task task-id --mapper-count 2
+node scripts/cw.js topology summary <run-id>
+node scripts/cw.js topology graph <run-id>
+```
+
+## Multi-agent host surface
+
+Prefer this high-level surface (`run -> status -> step -> blackboard -> score ->
+select`) when an agent host needs to drive multi-agent work without manual id
+plumbing. It wraps the topology, multi-agent, blackboard, candidate, commit, and
+audit primitives; it does not replace them.
+
+```bash
+node scripts/cw.js multi-agent run <run-id> --topology judge-panel --task task-id
+node scripts/cw.js multi-agent status <run-id>
+node scripts/cw.js multi-agent step <run-id> --sandbox readonly
+node scripts/cw.js multi-agent blackboard <run-id> summary
+node scripts/cw.js multi-agent score <run-id> candidate-id --criterion correctness=1 --evidence ref
+node scripts/cw.js multi-agent select <run-id> candidate-id --reason "verified winner"
+```
+
+Operator views (who depends on whom, who is blocked, which evidence was adopted):
+
+```bash
+node scripts/cw.js multi-agent summary <run-id>
+node scripts/cw.js multi-agent graph <run-id>
+node scripts/cw.js multi-agent dependencies <run-id>
+node scripts/cw.js multi-agent failures <run-id>
+node scripts/cw.js multi-agent evidence <run-id>
+```
+
+State Explosion Management — when a run grows too large to read, use derived,
+provenance-backed digests (they never delete raw records and fail closed when
+stale; every synthetic node carries source ids and an expansion command):
+
+```bash
+node scripts/cw.js summary refresh <run-id>
+node scripts/cw.js summary show <run-id>
+node scripts/cw.js blackboard summarize <run-id>
+node scripts/cw.js multi-agent summarize <run-id>
+node scripts/cw.js multi-agent graph <run-id> --view compact|critical-path|failures|... [--focus <id>] [--depth <n>]
+```
+
+Trust / Policy / Audit — inspect role authority, message provenance, blackboard
+write decisions, judge rationale, panel decisions, and why a result is trusted
+(missing policy/evidence/provenance/rationale fail closed):
+
+```bash
+node scripts/cw.js audit multi-agent <run-id>
+node scripts/cw.js audit policy <run-id>
+node scripts/cw.js audit role <run-id>
+node scripts/cw.js audit blackboard <run-id>
+node scripts/cw.js audit judge <run-id>
+```
+
+## Multi-agent low-level state
+
+First-class runtime state around dispatches (`MultiAgentRun`, `AgentRole`,
+`AgentGroup`, `AgentMembership`, `AgentFanout`, `AgentFanin`). CW records and
+validates this state; the host still executes agents. Invalid lifecycle
+transitions, duplicate memberships, ambiguous dispatch attachment, and missing
+fanin evidence fail closed.
+
+```bash
+node scripts/cw.js multi-agent run <run-id> --id ma --objective "coordinated work"
+node scripts/cw.js multi-agent role <run-id> role --multi-agent-run ma --responsibility "do work" --required-evidence "result evidence"
+node scripts/cw.js multi-agent group <run-id> group --multi-agent-run ma --task task-id
+node scripts/cw.js multi-agent fanout <run-id> fanout --group group --reason "split work" --role role --task task-id
+node scripts/cw.js dispatch <run-id> --multi-agent-run ma --multi-agent-group group --multi-agent-role role --multi-agent-fanout fanout
+node scripts/cw.js multi-agent fanin <run-id> fanin --group group --fanout fanout --required-role role
+```
+
+## Eval & replay
+
+Use when a topology-backed multi-agent run needs release-gate evidence.
+Artifacts live under `.cw/evals/<suite-id>/` as plain JSON plus `report.md`.
+
+```bash
+node scripts/cw.js eval snapshot <run-id> --id suite-id
+node scripts/cw.js eval replay .cw/evals/suite-id/snapshot.json
+node scripts/cw.js eval compare .cw/evals/suite-id/snapshot.json .cw/evals/suite-id/replay-run.json
+node scripts/cw.js eval score .cw/evals/suite-id/replay-run.json
+node scripts/cw.js eval gate .cw/evals/suite-id
+node scripts/cw.js eval report .cw/evals/suite-id/replay-run.json
+```
+
+## Blackboard & coordinator
+
+The shared coordination substrate: durable blackboards, topics, messages,
+context frames, artifact refs, snapshots, and coordinator decisions under
+`.cw/runs/<run-id>/blackboard/`.
+
+```bash
+node scripts/cw.js blackboard summary <run-id>
+node scripts/cw.js blackboard topic create <run-id> --id topic --title "Shared context"
+node scripts/cw.js blackboard message post <run-id> --topic topic --body "message"
+node scripts/cw.js blackboard context put <run-id> --topic topic --kind fact --key finding --value "evidence-backed fact"
+node scripts/cw.js blackboard artifact add <run-id> --topic topic --path /path/to/result.md --kind worker-result
+node scripts/cw.js blackboard snapshot <run-id>
+node scripts/cw.js coordinator summary <run-id>
+node scripts/cw.js coordinator decision <run-id> --kind conflict-resolution --outcome accepted --reason "evidence supports this"
+```
+
+## Sandbox profiles
+
+Named CW policy contracts describing worker read paths, write paths, command
+policy, network policy, environment exposure, and host enforcement requirements.
+CW enforces profile validation and worker result acceptance; the agent host
+enforces OS/process/network/environment controls.
+
+```bash
+node scripts/cw.js sandbox list
+node scripts/cw.js sandbox show readonly
+node scripts/cw.js sandbox validate ./site-sandbox.json
+node scripts/cw.js worker manifest <run-id> <worker-id>
+```
+
+## Commit, state & summaries
+
+Durable run state lives at `.cw/runs/<run-id>/state.json`. `state check`
+dry-runs migration and normalization; newer unsupported schemas fail closed and
+unknown user data is preserved.
+
+```bash
+node scripts/cw.js commit <run-id> --verifier <node-id> --reason "verified result"
+node scripts/cw.js commit <run-id> --selection <selection-id> --reason "verified winner"
+node scripts/cw.js commit <run-id> --allow-unverified-checkpoint --reason "manual checkpoint"
+node scripts/cw.js worker summary <run-id>
+node scripts/cw.js candidate summary <run-id>
+node scripts/cw.js feedback summary <run-id>
+node scripts/cw.js commit summary <run-id>
+node scripts/cw.js state check <run-id>
+```
+
+## Scheduling & routines
+
+CW supports loop, cron, and reminder schedules in `.cw/schedules/tasks.json`.
+Use `schedule due` to find due work and `schedule complete <id>` after the due
+prompt is handled. `routine create`/`routine fire` handle API/GitHub trigger
+events.
+
+```bash
+node scripts/cw.js loop --intervalMinutes 30 --prompt "Continue this workflow."
+node scripts/cw.js schedule create --kind loop --intervalMinutes 30 --prompt "Continue this workflow."
+node scripts/cw.js schedule due
+node scripts/cw.js schedule daemon --once
+node scripts/cw.js routine create --kind github --prompt "Handle this GitHub event."
+node scripts/cw.js routine fire github payload.json
+```
+
+## Release & maintenance npm scripts
+
+```bash
+npm run canonical-apps   # validate + plan the official app matrix (no network)
+npm run golden-path      # release regression for the full public chain
+npm run dogfood:release  # real-repo release-cut dry-run against this repo
+npm run fixture-compat   # check old run fixtures still load
+npm run eval:replay      # deterministic multi-agent eval/replay harness
+npm run version:sync     # verify version synchronization across surfaces
+npm run release:check    # dry-run release gate (build, types, tests, replay, dogfood)
+```
+
+`golden-path` exercises `workflow app -> plan -> dispatch -> isolated worker ->
+candidate scoring -> verifier -> gated commit -> report`, writing a simulated
+worker `cw:result` and asserting durable state files rather than exit codes.
+`release:check` does not tag, push, publish, or mutate fixtures.
+
+## MCP tools
+
+When an MCP host is available, the same runtime surface is exposed with
+JSON-first tools. **Preserve CLI/MCP parity when extending CW** — every CLI
+capability must have a matching MCP tool and vice versa.
+
+`cw_app_run`, `cw_dispatch`, `cw_worker_manifest`, `cw_worker_output`,
+`cw_candidate_register`, `cw_candidate_score`, `cw_candidate_select`,
+`cw_commit`, `cw_operator_status`, `cw_operator_graph`, `cw_operator_report`,
+`cw_topology_list`, `cw_topology_show`, `cw_topology_validate`,
+`cw_topology_apply`, `cw_topology_summary`, `cw_topology_graph`,
+`cw_multi_agent_summary`, `cw_multi_agent_graph`, `cw_multi_agent_dependencies`,
+`cw_multi_agent_failures`, `cw_multi_agent_evidence`, `cw_multi_agent_run`,
+`cw_multi_agent_status`, `cw_multi_agent_step`, `cw_multi_agent_blackboard`,
+`cw_multi_agent_score`, `cw_multi_agent_select`, `cw_multi_agent_run_create`,
+`cw_multi_agent_role_create`, `cw_multi_agent_group_create`,
+`cw_multi_agent_membership_create`, `cw_multi_agent_fanout_create`,
+`cw_multi_agent_fanin_collect`, `cw_eval_snapshot`, `cw_eval_replay`,
+`cw_eval_compare`, `cw_eval_score`, `cw_eval_gate`, `cw_eval_report`,
+`cw_blackboard_summary`, `cw_blackboard_context_put`,
+`cw_blackboard_artifact_add`, `cw_coordinator_decision`, `cw_summary_refresh`,
+`cw_summary_show`, `cw_blackboard_summarize`, `cw_multi_agent_summarize`, and
+`cw_multi_agent_graph_compact`.

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/ui/workbench/app.css

@@ -0,0 +1,76 @@
+/* Cool Workflow Workbench — static, dependency-light styling.
+   No framework; system fonts only; ~self-contained. */
+:root {
+  --bg: #0f1115;
+  --panel: #171a21;
+  --panel-2: #1d212a;
+  --ink: #e6e8ec;
+  --muted: #8a92a3;
+  --line: #2a2f3a;
+  --accent: #5aa9ff;
+  --present: #3fb950;
+  --absent: #d29922;
+  --bad: #f85149;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  background: var(--bg);
+  color: var(--ink);
+  font-size: 14px;
+}
+header { padding: 14px 20px; border-bottom: 1px solid var(--line); }
+header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+header .muted, .muted { color: var(--muted); font-weight: 400; }
+header .trust { margin: 4px 0 0; font-size: 12px; color: var(--muted); }
+code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+main { display: grid; grid-template-columns: 320px 1fr; height: calc(100vh - 64px); }
+.sidebar { border-right: 1px solid var(--line); overflow-y: auto; padding: 12px; }
+.bar { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+button {
+  background: var(--panel-2); color: var(--ink); border: 1px solid var(--line);
+  border-radius: 6px; padding: 4px 10px; cursor: pointer; font-size: 12px;
+}
+button:hover { border-color: var(--accent); }
+input[type="search"] {
+  width: 100%; background: var(--panel); color: var(--ink);
+  border: 1px solid var(--line); border-radius: 6px; padding: 6px 8px; margin-bottom: 8px;
+}
+.freshness { font-size: 11px; color: var(--muted); margin-bottom: 8px; }
+.run-list { list-style: none; margin: 0; padding: 0; }
+.run-list li {
+  padding: 8px; border: 1px solid var(--line); border-radius: 6px;
+  margin-bottom: 6px; cursor: pointer; background: var(--panel);
+}
+.run-list li:hover { border-color: var(--accent); }
+.run-list li.active { border-color: var(--accent); background: var(--panel-2); }
+.run-list .rid { font-family: ui-monospace, monospace; font-size: 12px; }
+.run-list .meta { color: var(--muted); font-size: 11px; margin-top: 2px; }
+.detail { overflow-y: auto; padding: 16px 20px; }
+.detail .empty { color: var(--muted); }
+.tabs { display: flex; gap: 6px; flex-wrap: wrap; border-bottom: 1px solid var(--line); padding-bottom: 8px; margin-bottom: 12px; }
+.tabs button.tab { background: transparent; border: 1px solid transparent; }
+.tabs button.tab.active { border-color: var(--line); background: var(--panel-2); }
+.panel-card { border: 1px solid var(--line); border-radius: 8px; margin-bottom: 14px; background: var(--panel); }
+.panel-card > .head {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 8px 12px; border-bottom: 1px solid var(--line);
+}
+.panel-card > .head .title { font-weight: 600; }
+.panel-card > .head .src { font-size: 11px; color: var(--muted); font-family: ui-monospace, monospace; }
+.badge { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--line); }
+.badge.present { color: var(--present); border-color: var(--present); }
+.badge.absent { color: var(--absent); border-color: var(--absent); }
+.badge.stale { color: var(--absent); border-color: var(--absent); }
+.badge.valid { color: var(--present); border-color: var(--present); }
+.badge.missing, .badge.bad { color: var(--bad); border-color: var(--bad); }
+pre.json {
+  margin: 0; padding: 12px; overflow-x: auto; font-size: 12px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; line-height: 1.5;
+  color: var(--ink); white-space: pre; max-height: 460px;
+}
+.panel-card .absent-note { padding: 10px 12px; color: var(--absent); font-size: 12px; }
+.kv { display: flex; gap: 16px; flex-wrap: wrap; padding: 8px 12px; font-size: 12px; color: var(--muted); }
+.kv b { color: var(--ink); font-weight: 600; }
+.err { color: var(--bad); }

package/ui/workbench/app.js

@@ -0,0 +1,159 @@
+"use strict";
+// Cool Workflow Workbench UI — vanilla JS, no dependencies.
+//
+// The UI holds NO state of its own and contains NO business logic: it fetches
+// the read-only JSON views from the localhost host and renders them. Every panel
+// is exactly one capability payload; refresh re-derives everything from disk.
+
+const PANEL_GROUPS = [
+  { key: "graph", label: "Run graph", panels: ["operator", "multiAgent", "compact", "criticalPath"] },
+  { key: "blackboard", label: "Blackboard", panels: ["coordinator", "digest", "graph"] },
+  { key: "worker", label: "Worker logs", panels: ["summary"] },
+  { key: "candidate", label: "Candidate compare", panels: ["summary", "reasoning"] },
+  { key: "audit", label: "Audit timeline", panels: ["summary", "multiAgent", "policy", "judge"] },
+  { key: "metrics", label: "Metrics & cost", panels: ["report"] },
+  { key: "collaboration", label: "Review & collaboration", panels: ["review", "comments"] }
+];
+
+const state = { activeRunId: null, activeTab: "graph" };
+
+async function getJson(url) {
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`non-JSON response (${res.status})`);
+  }
+  if (!res.ok) throw new Error(body && body.error ? body.error : `HTTP ${res.status}`);
+  return body;
+}
+
+function el(tag, attrs = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (k === "class") node.className = v;
+    else if (k === "text") node.textContent = v;
+    else node.setAttribute(k, v);
+  }
+  for (const child of [].concat(children)) {
+    if (child) node.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return node;
+}
+
+function freshnessBadge(value) {
+  const v = String(value || "").toLowerCase();
+  return el("span", { class: `badge ${v || "absent"}`, text: value || "unknown" });
+}
+
+async function loadIndex() {
+  const filter = document.getElementById("filter").value.trim();
+  const list = document.getElementById("run-list");
+  list.innerHTML = "";
+  let view;
+  try {
+    view = await getJson(`/api/index${filter ? `?text=${encodeURIComponent(filter)}` : ""}`);
+  } catch (error) {
+    list.appendChild(el("li", { class: "err", text: `failed to load index: ${error.message}` }));
+    return;
+  }
+  const reg = view.registry || {};
+  const fresh = document.getElementById("registry-freshness");
+  fresh.innerHTML = "";
+  fresh.append("registry ", freshnessBadge(reg.freshness), ` · scope ${view.scope}`);
+  const records = (view.runs && view.runs.records) || [];
+  if (!records.length) {
+    list.appendChild(el("li", { class: "muted", text: "no runs indexed in this scope" }));
+    return;
+  }
+  for (const record of records) {
+    const li = el("li", { class: state.activeRunId === record.runId ? "active" : "" }, [
+      el("div", { class: "rid", text: record.runId }),
+      el("div", {
+        class: "meta",
+        text: [record.appId || record.workflowId, record.lifecycle || record.status, record.repo]
+          .filter(Boolean)
+          .join(" · ")
+      })
+    ]);
+    li.addEventListener("click", () => selectRun(record.runId));
+    list.appendChild(li);
+  }
+}
+
+async function selectRun(runId) {
+  state.activeRunId = runId;
+  loadIndex();
+  const detail = document.getElementById("run-panel");
+  detail.innerHTML = "";
+  detail.appendChild(el("p", { class: "muted", text: `loading ${runId}…` }));
+  let view;
+  try {
+    view = await getJson(`/api/run/${encodeURIComponent(runId)}`);
+  } catch (error) {
+    detail.innerHTML = "";
+    detail.appendChild(el("p", { class: "err", text: `failed to load run: ${error.message}` }));
+    return;
+  }
+  renderRun(view);
+}
+
+function renderRun(view) {
+  const detail = document.getElementById("run-panel");
+  detail.innerHTML = "";
+  const header = el("div", { class: "kv" }, [
+    el("span", {}, [el("b", { text: "run " }), document.createTextNode(view.runId)]),
+    el("span", {}, [document.createTextNode("resolved "), freshnessBadge(view.resolved ? "valid" : "missing")])
+  ]);
+  if (view.error) header.appendChild(el("span", { class: "err", text: view.error }));
+  detail.appendChild(header);
+
+  const tabs = el("div", { class: "tabs" });
+  for (const group of PANEL_GROUPS) {
+    const btn = el("button", { class: `tab ${state.activeTab === group.key ? "active" : ""}`, text: group.label });
+    btn.addEventListener("click", () => {
+      state.activeTab = group.key;
+      renderRun(view);
+    });
+    tabs.appendChild(btn);
+  }
+  detail.appendChild(tabs);
+
+  const group = PANEL_GROUPS.find((g) => g.key === state.activeTab) || PANEL_GROUPS[0];
+  const panels = (view.panels && view.panels[group.key]) || {};
+  for (const name of group.panels) {
+    const panel = panels[name];
+    if (panel) detail.appendChild(renderPanel(name, panel));
+  }
+}
+
+function renderPanel(name, panel) {
+  const card = el("div", { class: "panel-card" });
+  const head = el("div", { class: "head" }, [
+    el("span", { class: "title", text: `${name} — ${panel.capability}` }),
+    el("span", { class: `badge ${panel.status}`, text: panel.status })
+  ]);
+  card.appendChild(head);
+  card.appendChild(el("div", { class: "kv" }, [el("span", { class: "src", text: panel.cli }), el("span", { class: "src", text: panel.mcp })]));
+  if (panel.status === "present") {
+    card.appendChild(el("pre", { class: "json", text: JSON.stringify(panel.data, null, 2) }));
+  } else {
+    card.appendChild(el("div", { class: "absent-note", text: `absent — ${panel.error || "source unreadable"}` }));
+  }
+  return card;
+}
+
+document.getElementById("refresh").addEventListener("click", loadIndex);
+document.getElementById("filter").addEventListener("input", debounce(loadIndex, 200));
+
+function debounce(fn, ms) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+
+loadIndex();

package/ui/workbench/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Cool Workflow Workbench</title>
+    <!-- Dependency-light: no framework, no bundler, no network. Static assets
+         only; all data is fetched from the localhost read-only JSON routes. -->
+    <link rel="stylesheet" href="/ui/app.css" />
+  </head>
+  <body>
+    <header>
+      <h1>Cool Workflow <span class="muted">Workbench</span></h1>
+      <p class="trust">read-only · localhost · no hidden dashboard — every view re-derived from <code>.cw/</code> files</p>
+    </header>
+    <main>
+      <section id="index-panel" class="sidebar">
+        <div class="bar">
+          <strong>Runs</strong>
+          <button id="refresh" title="Re-derive from disk">refresh</button>
+        </div>
+        <input id="filter" type="search" placeholder="filter runs (app/status/text)" />
+        <div id="registry-freshness" class="freshness"></div>
+        <ul id="run-list" class="run-list"></ul>
+      </section>
+      <section id="run-panel" class="detail">
+        <p class="empty">Select a run to inspect its graph, blackboard, worker logs, candidate compare, and audit timeline.</p>
+      </section>
+    </main>
+    <script src="/ui/app.js"></script>
+  </body>
+</html>

package/workflows/architecture-review.workflow.js

@@ -0,0 +1,84 @@
+module.exports = ({ workflow, phase, agent, artifact }) =>
+  workflow({
+    id: "legacy-architecture-review",
+    title: "Legacy Architecture Review",
+    summary:
+      "Compatibility workflow-file wrapper for the canonical architecture-review app.",
+    limits: {
+      maxAgents: 40,
+      maxConcurrentAgents: 6
+    },
+    inputs: [
+      { name: "repo", required: true },
+      { name: "question", required: true },
+      { name: "invariant", repeated: true }
+    ],
+    phases: [
+      phase("Map", [
+        agent(
+          "legacy-map:server-api",
+          "Map server/API entrypoints, request flows, service boundaries, auth surfaces, and owned state. Return inspected files, dependencies, invariants, and candidate risks."
+        ),
+        agent(
+          "legacy-map:web-client",
+          "Map web/client/UI boundaries, local state, backend dependencies, build/runtime assumptions, and candidate risks."
+        ),
+        agent(
+          "legacy-map:db-security",
+          "Map database, persistence, migrations, secrets, auth, permissions, and security-sensitive paths. Return candidate risks with evidence."
+        ),
+        agent(
+          "legacy-map:deploy-config",
+          "Map deployment, Docker/compose, CI, reverse proxies, environment config, supervision, and operational assumptions."
+        ),
+        agent(
+          "legacy-map:jobs-operators",
+          "Map background jobs, admin/operator surfaces, queues, scheduled work, and failure recovery paths."
+        ),
+        agent(
+          "legacy-map:transport-core",
+          "Map protocol, daemon, transport, rendering, networking, or core engine boundaries when present; otherwise explain why this scope is not applicable."
+        )
+      ]),
+      phase("Assess", [
+        agent(
+          "legacy-assess:security",
+          "Assess mapper findings through a security lens. Separate real, conditional, non-issue, and unknown risks with evidence and falsifiers."
+        ),
+        agent(
+          "legacy-assess:data-correctness",
+          "Assess data correctness, schema drift, persistence invariants, concurrency, transactions, and state corruption risks."
+        ),
+        agent(
+          "legacy-assess:failure-modes",
+          "Assess startup, shutdown, retries, partial failure, dependency outage, backup/restore, and recovery behavior."
+        ),
+        agent(
+          "legacy-assess:scale-ops",
+          "Assess scale, operational complexity, observability, configuration, deployment, and maintenance risks."
+        ),
+        agent(
+          "legacy-assess:maintainability",
+          "Assess module boundaries, ownership clarity, coupling, extensibility, testability, and future change risk."
+        ),
+        agent(
+          "legacy-assess:domain",
+          "Assess domain-specific risks implied by the repo and user invariants. If the domain includes networking/proxy/tunnel behavior, include anti-censorship and abuse-resistance concerns."
+        )
+      ]),
+      phase("Verify", [
+        agent(
+          "legacy-verify:p0-p2-risks",
+          "Re-open evidence for every candidate P0/P1/P2 risk. Confirm real risks, downgrade unsupported concerns, and list exact files or unknowns.",
+          { requiresEvidence: true }
+        )
+      ]),
+      phase("Verdict", [
+        artifact(
+          "legacy-verdict:synthesis",
+          "Synthesize the architecture verdict: short answer, architecture map, ranked risks, non-issues, recommended changes, and evidence links.",
+          { requiresEvidence: true }
+        )
+      ])
+    ]
+  });