cool-workflow 0.1.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (193) hide show
  1. package/.claude-plugin/plugin.json +20 -0
  2. package/.codex-plugin/mcp.json +10 -0
  3. package/.codex-plugin/plugin.json +38 -0
  4. package/.mcp.json +10 -0
  5. package/LICENSE +24 -0
  6. package/README.md +638 -0
  7. package/apps/architecture-review/app.json +51 -0
  8. package/apps/architecture-review/workflow.js +116 -0
  9. package/apps/end-to-end-golden-path/app.json +30 -0
  10. package/apps/end-to-end-golden-path/workflow.js +33 -0
  11. package/apps/pr-review-fix-ci/app.json +59 -0
  12. package/apps/pr-review-fix-ci/workflow.js +90 -0
  13. package/apps/release-cut/app.json +54 -0
  14. package/apps/release-cut/workflow.js +82 -0
  15. package/apps/research-synthesis/app.json +50 -0
  16. package/apps/research-synthesis/workflow.js +76 -0
  17. package/apps/workflow-app-framework-demo/app.json +29 -0
  18. package/apps/workflow-app-framework-demo/workflow.js +44 -0
  19. package/dist/agent-config.js +223 -0
  20. package/dist/candidate-scoring.js +715 -0
  21. package/dist/capability-core.js +630 -0
  22. package/dist/capability-dispatcher.js +86 -0
  23. package/dist/capability-registry.js +523 -0
  24. package/dist/cli.js +1276 -0
  25. package/dist/collaboration.js +727 -0
  26. package/dist/commit.js +570 -0
  27. package/dist/contract-migration.js +234 -0
  28. package/dist/coordinator.js +1163 -0
  29. package/dist/daemon.js +44 -0
  30. package/dist/dispatch.js +201 -0
  31. package/dist/drive.js +503 -0
  32. package/dist/error-feedback.js +415 -0
  33. package/dist/evidence-grounding.js +179 -0
  34. package/dist/evidence-reasoning.js +733 -0
  35. package/dist/execution-backend.js +1279 -0
  36. package/dist/harness.js +61 -0
  37. package/dist/mcp-server.js +1615 -0
  38. package/dist/multi-agent-eval.js +857 -0
  39. package/dist/multi-agent-host.js +764 -0
  40. package/dist/multi-agent-operator-ux.js +537 -0
  41. package/dist/multi-agent-trust.js +366 -0
  42. package/dist/multi-agent.js +1173 -0
  43. package/dist/node-snapshot.js +270 -0
  44. package/dist/observability.js +922 -0
  45. package/dist/operator-ux.js +971 -0
  46. package/dist/orchestrator/audit-operations.js +182 -0
  47. package/dist/orchestrator/candidate-operations.js +117 -0
  48. package/dist/orchestrator/cli-options.js +288 -0
  49. package/dist/orchestrator/collaboration-operations.js +86 -0
  50. package/dist/orchestrator/feedback-operations.js +81 -0
  51. package/dist/orchestrator/host-operations.js +78 -0
  52. package/dist/orchestrator/lifecycle-operations.js +462 -0
  53. package/dist/orchestrator/migration-operations.js +44 -0
  54. package/dist/orchestrator/multi-agent-operations.js +362 -0
  55. package/dist/orchestrator/report.js +369 -0
  56. package/dist/orchestrator/topology-operations.js +84 -0
  57. package/dist/orchestrator.js +874 -0
  58. package/dist/pipeline-contract.js +92 -0
  59. package/dist/pipeline-runner.js +285 -0
  60. package/dist/reclamation.js +882 -0
  61. package/dist/result-normalize.js +194 -0
  62. package/dist/run-export.js +64 -0
  63. package/dist/run-registry.js +1347 -0
  64. package/dist/run-state-schema.js +67 -0
  65. package/dist/sandbox-profile.js +471 -0
  66. package/dist/scheduler.js +266 -0
  67. package/dist/scheduling.js +184 -0
  68. package/dist/schema-validate.js +98 -0
  69. package/dist/state-explosion.js +1213 -0
  70. package/dist/state-migrations.js +463 -0
  71. package/dist/state-node.js +301 -0
  72. package/dist/state.js +308 -0
  73. package/dist/telemetry-attestation.js +156 -0
  74. package/dist/telemetry-ledger.js +145 -0
  75. package/dist/topology.js +527 -0
  76. package/dist/triggers.js +159 -0
  77. package/dist/trust-audit.js +475 -0
  78. package/dist/types/blackboard.js +2 -0
  79. package/dist/types/boundary.js +29 -0
  80. package/dist/types/candidate.js +2 -0
  81. package/dist/types/collaboration.js +2 -0
  82. package/dist/types/core.js +2 -0
  83. package/dist/types/drive.js +10 -0
  84. package/dist/types/error-feedback.js +2 -0
  85. package/dist/types/evidence-reasoning.js +2 -0
  86. package/dist/types/execution-backend.js +2 -0
  87. package/dist/types/multi-agent.js +2 -0
  88. package/dist/types/observability.js +2 -0
  89. package/dist/types/pipeline.js +2 -0
  90. package/dist/types/reclamation.js +8 -0
  91. package/dist/types/result.js +2 -0
  92. package/dist/types/run-registry.js +2 -0
  93. package/dist/types/run.js +2 -0
  94. package/dist/types/sandbox.js +2 -0
  95. package/dist/types/schedule.js +2 -0
  96. package/dist/types/state-node.js +2 -0
  97. package/dist/types/topology.js +2 -0
  98. package/dist/types/trust.js +2 -0
  99. package/dist/types/workbench.js +2 -0
  100. package/dist/types/worker.js +2 -0
  101. package/dist/types/workflow-app.js +2 -0
  102. package/dist/types.js +43 -0
  103. package/dist/verifier-registry.js +46 -0
  104. package/dist/verifier.js +78 -0
  105. package/dist/version.js +8 -0
  106. package/dist/workbench-host.js +172 -0
  107. package/dist/workbench.js +190 -0
  108. package/dist/worker-isolation.js +1028 -0
  109. package/dist/workflow-api.js +98 -0
  110. package/dist/workflow-app-framework.js +626 -0
  111. package/docs/agent-delegation-drive.7.md +190 -0
  112. package/docs/agent-framework.md +176 -0
  113. package/docs/candidate-scoring.7.md +106 -0
  114. package/docs/canonical-workflow-apps.7.md +137 -0
  115. package/docs/capability-topology-registry.7.md +168 -0
  116. package/docs/cli-mcp-parity.7.md +373 -0
  117. package/docs/contract-migration-tooling.7.md +123 -0
  118. package/docs/control-plane-scheduling.7.md +110 -0
  119. package/docs/coordinator-blackboard.7.md +183 -0
  120. package/docs/dogfood/architecture-review-cool-workflow.md +16 -0
  121. package/docs/dogfood-one-real-repo.7.md +168 -0
  122. package/docs/durable-state-and-locking.7.md +107 -0
  123. package/docs/end-to-end-golden-path.7.md +117 -0
  124. package/docs/error-feedback.7.md +153 -0
  125. package/docs/evidence-adoption-reasoning-chain.7.md +270 -0
  126. package/docs/execution-backends.7.md +300 -0
  127. package/docs/getting-started.md +99 -0
  128. package/docs/index.md +41 -0
  129. package/docs/mcp-app-surface.7.md +235 -0
  130. package/docs/multi-agent-cli-mcp-surface.7.md +265 -0
  131. package/docs/multi-agent-eval-replay-harness.7.md +302 -0
  132. package/docs/multi-agent-operator-ux.7.md +314 -0
  133. package/docs/multi-agent-runtime-core.7.md +231 -0
  134. package/docs/multi-agent-topologies.7.md +103 -0
  135. package/docs/multi-agent-trust-policy-audit.7.md +154 -0
  136. package/docs/node-snapshot-diff-replay.7.md +135 -0
  137. package/docs/observability-cost-accounting.7.md +194 -0
  138. package/docs/operator-ux.7.md +180 -0
  139. package/docs/pipeline-runner.7.md +136 -0
  140. package/docs/project-index.md +261 -0
  141. package/docs/real-execution-backends.7.md +142 -0
  142. package/docs/release-and-migration.7.md +280 -0
  143. package/docs/release-tooling.7.md +159 -0
  144. package/docs/routines.md +48 -0
  145. package/docs/run-registry-control-plane.7.md +312 -0
  146. package/docs/run-retention-reclamation.7.md +191 -0
  147. package/docs/sandbox-profiles.7.md +137 -0
  148. package/docs/scheduled-tasks.md +80 -0
  149. package/docs/security-trust-hardening.7.md +117 -0
  150. package/docs/state-explosion-management.7.md +264 -0
  151. package/docs/state-node.7.md +96 -0
  152. package/docs/team-collaboration.7.md +207 -0
  153. package/docs/unix-principles.md +192 -0
  154. package/docs/verifier-gated-commit.7.md +140 -0
  155. package/docs/web-desktop-workbench.7.md +215 -0
  156. package/docs/worker-isolation.7.md +167 -0
  157. package/docs/workflow-app-framework.7.md +274 -0
  158. package/manifest/README.md +43 -0
  159. package/manifest/plugin.manifest.json +316 -0
  160. package/manifest/pricing.policy.json +14 -0
  161. package/package.json +79 -0
  162. package/scripts/agents/claude-p-agent.js +104 -0
  163. package/scripts/agents/claude-p-agent.sh +9 -0
  164. package/scripts/agents/cw-attest-keygen.js +55 -0
  165. package/scripts/agents/cw-attest-wrap.js +143 -0
  166. package/scripts/block-unapproved-tag.sh +39 -0
  167. package/scripts/bump-version.js +249 -0
  168. package/scripts/canonical-apps.js +171 -0
  169. package/scripts/cw.js +4 -0
  170. package/scripts/dist-drift-check.js +79 -0
  171. package/scripts/dogfood-architecture-review.js +237 -0
  172. package/scripts/dogfood-release.js +624 -0
  173. package/scripts/forward-ref-docs.js +73 -0
  174. package/scripts/gen-manifests.js +232 -0
  175. package/scripts/golden-path.js +300 -0
  176. package/scripts/mcp-server.js +4 -0
  177. package/scripts/new-feature.js +121 -0
  178. package/scripts/parity-check.js +213 -0
  179. package/scripts/release-check.js +118 -0
  180. package/scripts/release-flow.js +272 -0
  181. package/scripts/release-gate.sh +85 -0
  182. package/scripts/sync-project-index.js +387 -0
  183. package/scripts/validate-run-state-schema.js +126 -0
  184. package/scripts/verify-container-selfref.js +64 -0
  185. package/scripts/version-sync-check.js +237 -0
  186. package/skills/cool-workflow/SKILL.md +162 -0
  187. package/skills/cool-workflow/references/commands.md +282 -0
  188. package/tsconfig.json +16 -0
  189. package/ui/workbench/app.css +76 -0
  190. package/ui/workbench/app.js +159 -0
  191. package/ui/workbench/index.html +32 -0
  192. package/workflows/architecture-review.workflow.js +84 -0
  193. package/workflows/research-synthesis.workflow.js +47 -0
@@ -0,0 +1,314 @@
1
+ # Multi-Agent Operator UX
2
+
3
+ CW v0.1.21 makes multi-agent operator inspection first-class. The feature is a
4
+ read-only userland view over existing run state. It does not create a hidden
5
+ dashboard database and does not infer success when evidence, dependency, or
6
+ lifecycle state is ambiguous.
7
+ CW v0.1.22 adds trust panels to the same operator path so role policy,
8
+ permission decisions, blackboard write audit, message provenance, judge
9
+ rationale, panel decisions, and policy violations are visible beside topology
10
+ and evidence state.
11
+ CW v0.1.24 uses the same operator-derived graph, dependency, failure, evidence,
12
+ trust, and report views as replay comparison inputs for the Multi-Agent Eval &
13
+ Replay Harness.
14
+ CW v0.1.25 layers State Explosion Management on top of these operator views: when
15
+ a run grows large, `summary show`, `multi-agent summarize`, and
16
+ `multi-agent graph --view compact` collapse high-volume records into synthetic
17
+ summary nodes while preserving the critical path, failures, missing evidence,
18
+ policy violations, and judge rationale. See
19
+ [state-explosion-management.7.md](state-explosion-management.7.md).
20
+
21
+ CW v0.1.26 adds the `Adoption Rationale` panel and the `multi-agent reasoning`
22
+ view, which explains *why* each evidence item was adopted. Reasoning steps are on
23
+ the critical path and are never collapsed by compaction. See
24
+ [evidence-adoption-reasoning-chain.7.md](evidence-adoption-reasoning-chain.7.md).
25
+
26
+ CW v0.1.27 adds an additive evidence `disposition` (`adopted` | `inspectable` |
27
+ `blocking`) and an `inspectableEvidence` list. The raw `status` (the adoption
28
+ state) is unchanged; `disposition` is the operator-facing reading of it. Before a
29
+ verifier-gated commit, a missing/pending row genuinely blocks. After a
30
+ verifier-gated commit the selected path is decided, so missing/pending evidence
31
+ for sibling roles that were never driven as separate workers — for example
32
+ undriven judge-panel judges — is inspectable operator state, not a hidden
33
+ failure. The `multi-agent status` "Missing Evidence" header and the `status`
34
+ panel report the blocking-vs-inspectable split so the operator is not misled.
35
+
36
+ The model is derived from:
37
+
38
+ - `WorkflowRun` tasks, dispatches, workers, nodes, feedback, candidates,
39
+ selections, commits, and report paths
40
+ - multi-agent runs, roles, groups, memberships, fanouts, and fanins
41
+ - topology runs and their missing evidence/conflict records
42
+ - blackboard topics, messages, contexts, artifacts, snapshots, and coordinator
43
+ decisions
44
+ - candidate score files, trust audit events, and verifier-gated commit records
45
+ - role policy, blackboard provenance, judge rationale, panel decisions, and
46
+ policy violation audit records
47
+
48
+ ## Operator Commands
49
+
50
+ Use the normal status and report commands for the broad view:
51
+
52
+ ```bash
53
+ node scripts/cw.js status <run-id>
54
+ node scripts/cw.js graph <run-id>
55
+ node scripts/cw.js report <run-id> --show
56
+ ```
57
+
58
+ Use the focused multi-agent views when the operator needs the process table:
59
+
60
+ ```bash
61
+ node scripts/cw.js multi-agent status <run-id>
62
+ node scripts/cw.js multi-agent graph <run-id>
63
+ node scripts/cw.js multi-agent dependencies <run-id>
64
+ node scripts/cw.js multi-agent failures <run-id>
65
+ node scripts/cw.js multi-agent evidence <run-id>
66
+ ```
67
+
68
+ Every focused command supports deterministic JSON:
69
+
70
+ ```bash
71
+ node scripts/cw.js multi-agent status <run-id> --json
72
+ node scripts/cw.js multi-agent dependencies <run-id> --json
73
+ node scripts/cw.js multi-agent failures <run-id> --format json
74
+ node scripts/cw.js multi-agent evidence <run-id> --json
75
+ ```
76
+
77
+ The compact human output uses six stable panels:
78
+
79
+ ```text
80
+ Agent Graph
81
+ Dependencies
82
+ Failed / Blocked Agents
83
+ Adopted Evidence
84
+ Missing Evidence
85
+ Next Action
86
+ ```
87
+
88
+ ## Graph
89
+
90
+ `multi-agent graph` shows the topology-backed agent graph plus downstream
91
+ acceptance records:
92
+
93
+ - MultiAgentRun, topology run, roles, groups, memberships, fanout, and fanin
94
+ - tasks, dispatches, workers, result nodes, and verifier gates
95
+ - blackboard topics, messages, artifacts, contexts, snapshots, and coordinator
96
+ decisions
97
+ - candidates, score records, selections, verifier-gated commits, and feedback
98
+
99
+ Edges are labeled when the label carries operational meaning:
100
+
101
+ ```text
102
+ owns
103
+ depends-on
104
+ dispatches
105
+ reports
106
+ cites
107
+ adopted-by
108
+ rejected-by
109
+ blocks
110
+ scores
111
+ selects
112
+ gates
113
+ commits
114
+ ```
115
+
116
+ Direction follows the dependency or evidence flow. For example, a membership
117
+ depends on a task and worker, worker output reports into the membership,
118
+ blackboard artifacts are cited by fanin, scores evaluate candidates, selections
119
+ choose scored candidates, and commits record the selected verifier-gated result.
120
+
121
+ ## Failures
122
+
123
+ `multi-agent failures` merges the records an operator normally has to inspect
124
+ one at a time:
125
+
126
+ - failed memberships and missing role coverage
127
+ - missing worker output and failed or rejected workers
128
+ - open feedback, including sandbox-policy failures
129
+ - fanin blocked reasons and missing blackboard evidence
130
+ - rejected or failed candidates
131
+ - score, selection, verifier, and commit-gate gaps
132
+ - ambiguous blocked dependencies
133
+
134
+ Each row includes the record id, kind, status, owner or role when known, linked
135
+ task/worker/membership/fanin/candidate when known, the exact reason, and the
136
+ next safe command.
137
+
138
+ ## Evidence Adoption
139
+
140
+ `multi-agent evidence` explains why a result was accepted or not accepted. Each
141
+ row includes:
142
+
143
+ - evidence id/ref/path/locator
144
+ - source kind and source id
145
+ - adopted-by ids and rejected-by ids
146
+ - pending consumers
147
+ - candidate, score, selection, and commit links
148
+ - provenance or trust source when available
149
+ - status: `adopted`, `rejected`, `pending`, `superseded`, `conflicting`, or
150
+ `missing`
151
+
152
+ An accepted path should be traceable like this:
153
+
154
+ ```text
155
+ worker result -> blackboard artifact/message -> fanin -> candidate score
156
+ -> selection -> verifier-gated commit
157
+ ```
158
+
159
+ When any link is missing, CW reports it as pending or missing and recommends the
160
+ next command rather than assuming the run is healthy.
161
+
162
+ ## MCP Parity
163
+
164
+ MCP hosts can inspect the same derived data:
165
+
166
+ - `cw_multi_agent_status`
167
+ - `cw_multi_agent_graph`
168
+ - `cw_multi_agent_dependencies`
169
+ - `cw_multi_agent_failures`
170
+ - `cw_multi_agent_evidence`
171
+
172
+ `cw_multi_agent_status` preserves the v0.1.20 host envelope and adds the
173
+ derived operator model under `summaries.multiAgentOperator`.
174
+
175
+ ## Example Trace
176
+
177
+ ```bash
178
+ node scripts/cw.js multi-agent graph "$RUN"
179
+ node scripts/cw.js multi-agent dependencies "$RUN" --json
180
+ node scripts/cw.js multi-agent failures "$RUN"
181
+ node scripts/cw.js multi-agent evidence "$RUN"
182
+ node scripts/cw.js audit provenance "$RUN" --candidate "$CANDIDATE"
183
+ node scripts/cw.js commit "$RUN" --selection "$SELECTION" --reason "verified winner"
184
+ node scripts/cw.js report "$RUN" --show
185
+ ```
186
+
187
+ The operator can start at an agent membership, follow `depends-on` to its task
188
+ and worker, follow `reports` to the blackboard artifact and fanin, follow
189
+ `scores` to the candidate score, follow `selects` to the selected result, and
190
+ follow `commits` to the verifier-gated state commit.
191
+
192
+ ## Smoke Coverage
193
+
194
+ `test/multi-agent-operator-ux-smoke.js` creates a deterministic topology-backed
195
+ run with a successful worker evidence path, a failed worker path, blocked fanin
196
+ evidence, score and selection records, a verifier-gated commit, human CLI
197
+ assertions, JSON CLI assertions, MCP parity assertions, and report assertions.
198
+ It is included in `npm test` and `npm run release:check`.
199
+ ## CLI ↔ MCP Parity (v0.1.27)
200
+
201
+ Every command and tool referenced above is declared in the v0.1.27 capability
202
+ registry (`src/capability-registry.ts`) and validated by `npm run parity:check`,
203
+ so `cw <cmd> --json` and the matching `cw_<tool>` result render one data source.
204
+ See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
205
+
206
+ ## Run Registry / Control Plane (v0.1.28)
207
+
208
+ The runs described here are indexed, searchable, resumable, archivable, and
209
+ rerunnable across repos by the v0.1.28 Run Registry / Control Plane, which derives
210
+ a fingerprinted, fail-closed index over the same per-run `.cw/runs/<id>/state.json`
211
+ source of truth. See [run-registry-control-plane.7.md](run-registry-control-plane.7.md).
212
+
213
+ ## Execution Backends (v0.1.29)
214
+
215
+ v0.1.29 lifts execution into a pluggable driver layer: one narrow `ExecutionBackend`
216
+ contract with interchangeable `node`/`bun`/`shell`/`container`/`remote`/`ci`
217
+ drivers, selected by `--backend` (parallel to `--sandbox`) and inspected via
218
+ `backend list|show|probe`. The result/evidence envelope is schema-identical across
219
+ backends; the backend id + sandbox attestation are recorded as provenance, so this
220
+ surface is unchanged regardless of which backend executed a run. See
221
+ [execution-backends.7.md](execution-backends.7.md).
222
+ ## Web / Desktop Workbench (v0.1.30)
223
+
224
+ v0.1.30 adds the Web / Desktop Workbench: a read-only, localhost-only human
225
+ console that renders this surface (and the other four operator panels — run
226
+ graph, blackboard, worker logs, candidate compare, audit timeline) for any run,
227
+ reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR alongside
228
+ the CLI and MCP that holds no authoritative state and forks no schema: each panel
229
+ equals its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
230
+ re-derives everything from disk. See
231
+ [web-desktop-workbench.7.md](web-desktop-workbench.7.md).
232
+
233
+ ## Observability + Cost Accounting (v0.1.31)
234
+
235
+ v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
236
+ derive durations, failure/verifier/acceptance rates (with sample counts and
237
+ fail-closed `n/a`), and host-attested token/cost from existing durable run state
238
+ — no metrics database, no collector daemon, no hidden counter. Usage is additive
239
+ and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
240
+ × a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
241
+ verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
242
+ [observability-cost-accounting.7.md](observability-cost-accounting.7.md).
243
+
244
+
245
+ ## Team Collaboration (v0.1.32)
246
+
247
+ v0.1.32 adds Team Collaboration: a host-attested actor and append-only
248
+ approvals/rejections/comments/handoffs provenance-linked to a durable target,
249
+ plus a review gate that STACKS ON the verifier gate — required approvals from
250
+ authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
251
+ and never instead of them, failing closed on quorum/authority/self-approval and
252
+ recording who approved the very artifact that shipped. Policy (required approvals,
253
+ authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
254
+ unchanged). The verbs are parity-gated and render read-only in the v0.1.30
255
+ Workbench. See [Team Collaboration](team-collaboration.7.md).
256
+
257
+ ## Release Tooling (v0.1.33)
258
+
259
+ the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
260
+
261
+ ## Real Execution Backend Integrations (v0.1.34)
262
+
263
+ container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
264
+
265
+ ## Node Snapshot / Diff / Replay (v0.1.35)
266
+
267
+ per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
268
+
269
+ ## Contract Migration Tooling (v0.1.36)
270
+
271
+ first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
272
+
273
+ ## Control-Plane Scheduling (v0.1.37)
274
+
275
+ priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
276
+
277
+ ## Agent Delegation Drive (v0.1.38)
278
+
279
+ spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
280
+
281
+ ## Run Retention & Provable Reclamation (v0.1.39)
282
+
283
+ tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
284
+
285
+ ## Durable State & Locking (v0.1.40)
286
+
287
+ atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
288
+
289
+ ## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
290
+
291
+ evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
292
+
293
+ ## Robust Result Ingest (v0.1.42)
294
+
295
+ capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
296
+
297
+ ## No-False-Green Gate & Launch Prep (v0.1.43)
298
+
299
+ Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
300
+
301
+ ## Release-Gate Determinism & Agents Vendor (v0.1.44)
302
+
303
+ Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
304
+
305
+ ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
306
+
307
+ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
308
+ 0.1.51
309
+
310
+ 0.1.76
311
+
312
+ 0.1.77
313
+
314
+ 0.1.78
@@ -0,0 +1,231 @@
1
+ # Multi-Agent Runtime Core
2
+
3
+ CW v0.1.17 made multi-agent runtime state first-class. Dispatches and worker
4
+ records still exist, but they now have explicit process-table-style state around
5
+ them: `MultiAgentRun`, `AgentRole`, `AgentGroup`, `AgentMembership`,
6
+ `AgentFanout`, and `AgentFanin`.
7
+
8
+ CW v0.1.18 extends these records with blackboard and topic links so fanout,
9
+ worker manifests, accepted worker output, and fanin evidence can cite the
10
+ Coordinator / Blackboard substrate.
11
+
12
+ This release is the runtime core, not an autonomous scheduler. CW records and
13
+ validates the state model. The agent host still executes agents and enforces
14
+ OS/process/network/environment controls.
15
+
16
+ ## State Model
17
+
18
+ Multi-agent state lives in durable run state:
19
+
20
+ ```text
21
+ .cw/runs/<run-id>/state.json
22
+ multiAgent:
23
+ schemaVersion: 1
24
+ runs: []
25
+ roles: []
26
+ groups: []
27
+ memberships: []
28
+ fanouts: []
29
+ fanins: []
30
+ ```
31
+
32
+ CW also mirrors records to local JSON files:
33
+
34
+ ```text
35
+ .cw/runs/<run-id>/multi-agent/
36
+ index.json
37
+ runs/<multi-agent-run-id>.json
38
+ roles/<role-id>.json
39
+ groups/<group-id>.json
40
+ memberships/<membership-id>.json
41
+ fanouts/<fanout-id>.json
42
+ fanins/<fanin-id>.json
43
+ ```
44
+
45
+ All records carry stable ids, timestamps, schema versions, lifecycle history,
46
+ parent/child links where relevant, and metadata. Records link back to the
47
+ existing workflow run, phase, task, dispatch, worker, result, verifier,
48
+ candidate, commit, and audit surfaces.
49
+
50
+ ## Runtime Objects
51
+
52
+ `MultiAgentRun` is the top-level runtime table entry for coordinated agent work.
53
+ Its lifecycle is:
54
+
55
+ ```text
56
+ planned -> forming -> running -> collecting -> verifying -> completed
57
+ ```
58
+
59
+ It may also move to `failed` or `cancelled`. Invalid lifecycle transitions fail
60
+ closed.
61
+
62
+ `AgentRole` describes responsibility, required evidence, sandbox profile hints,
63
+ expected artifacts, and fanin obligations.
64
+
65
+ `AgentGroup` is a coordinated set of members for a phase or subproblem. Groups
66
+ hold role, task, membership, worker, fanout, and fanin ids.
67
+
68
+ `AgentMembership` binds one role to one task and, once dispatched, one worker.
69
+ A worker can belong to one or more groups only through explicit membership
70
+ records. Duplicate membership for the same group, role, task, and worker fails
71
+ closed.
72
+
73
+ `AgentFanout` records why work was split, which roles/tasks/workers were
74
+ created or attached, concurrency limits, sandbox profile choices, dispatch ids,
75
+ and the expected return shape.
76
+
77
+ `AgentFanin` records aggregation strategy, required roles, reported members,
78
+ missing members, evidence coverage, blocked reasons, and verifier readiness.
79
+ Fanin does not silently accept missing evidence for required roles.
80
+
81
+ ## Dispatch Integration
82
+
83
+ Existing dispatch and worker flows remain valid:
84
+
85
+ ```bash
86
+ node scripts/cw.js dispatch <run-id> --limit 1 --sandbox readonly
87
+ ```
88
+
89
+ To attach dispatch to explicit multi-agent state:
90
+
91
+ ```bash
92
+ node scripts/cw.js multi-agent run <run-id> --id ma-release --objective "release verification"
93
+ node scripts/cw.js multi-agent role <run-id> verifier \
94
+ --multi-agent-run ma-release \
95
+ --responsibility "verify release evidence" \
96
+ --required-evidence "release-check log"
97
+ node scripts/cw.js multi-agent group <run-id> release-group \
98
+ --multi-agent-run ma-release \
99
+ --phase "Verify" \
100
+ --task verify:package
101
+ node scripts/cw.js multi-agent fanout <run-id> release-fanout \
102
+ --group release-group \
103
+ --reason "split release verification" \
104
+ --role verifier \
105
+ --task verify:package \
106
+ --limit 1 \
107
+ --sandbox-choice verifier=readonly
108
+ node scripts/cw.js dispatch <run-id> \
109
+ --limit 1 \
110
+ --sandbox readonly \
111
+ --multi-agent-run ma-release \
112
+ --multi-agent-group release-group \
113
+ --multi-agent-role verifier \
114
+ --multi-agent-fanout release-fanout
115
+ ```
116
+
117
+ Worker manifests then include:
118
+
119
+ ```json
120
+ {
121
+ "multiAgent": {
122
+ "runId": "ma-release",
123
+ "groupId": "release-group",
124
+ "roleId": "verifier",
125
+ "membershipId": "membership-id",
126
+ "fanoutId": "release-fanout"
127
+ }
128
+ }
129
+ ```
130
+
131
+ When CW accepts worker output, it updates linked membership evidence and records
132
+ multi-agent trust audit events.
133
+
134
+ ## Fanin
135
+
136
+ Collect fanin after worker output:
137
+
138
+ ```bash
139
+ node scripts/cw.js multi-agent fanin <run-id> release-fanin \
140
+ --group release-group \
141
+ --fanout release-fanout \
142
+ --required-role verifier
143
+ ```
144
+
145
+ If a required role has no membership, or a membership has not reported evidence,
146
+ the fanin record is `blocked` and `verifierReady=false`. This is intentional:
147
+ missing evidence is a state error, not an implicit success.
148
+
149
+ ## Inspect
150
+
151
+ Use normal operator commands:
152
+
153
+ ```bash
154
+ node scripts/cw.js status <run-id>
155
+ node scripts/cw.js graph <run-id>
156
+ node scripts/cw.js report <run-id> --show
157
+ node scripts/cw.js audit summary <run-id>
158
+ node scripts/cw.js audit provenance <run-id>
159
+ ```
160
+
161
+ Use focused multi-agent commands:
162
+
163
+ ```bash
164
+ node scripts/cw.js multi-agent summary <run-id>
165
+ node scripts/cw.js multi-agent summary <run-id> --json
166
+ node scripts/cw.js multi-agent graph <run-id>
167
+ node scripts/cw.js multi-agent graph <run-id> --json
168
+ node scripts/cw.js multi-agent show <run-id> <multi-agent-run-id>
169
+ node scripts/cw.js multi-agent role <run-id> <role-id>
170
+ node scripts/cw.js multi-agent group <run-id> <group-id>
171
+ node scripts/cw.js multi-agent membership <run-id> <membership-id>
172
+ node scripts/cw.js multi-agent fanout <run-id> <fanout-id>
173
+ node scripts/cw.js multi-agent fanin <run-id> <fanin-id>
174
+ ```
175
+
176
+ The status and report Multi-Agent panel shows group status, role coverage,
177
+ membership health, fanout/fanin progress, blocked reasons, and the next
178
+ recommended action.
179
+
180
+ ## MCP Parity
181
+
182
+ MCP read/inspect tools:
183
+
184
+ ```text
185
+ cw_multi_agent_summary
186
+ cw_multi_agent_graph
187
+ cw_multi_agent_run_show
188
+ cw_multi_agent_role_show
189
+ cw_multi_agent_group_show
190
+ cw_multi_agent_membership_show
191
+ cw_multi_agent_fanout_show
192
+ cw_multi_agent_fanin_show
193
+ ```
194
+
195
+ Safe write tools:
196
+
197
+ ```text
198
+ cw_multi_agent_run_create
199
+ cw_multi_agent_run_transition
200
+ cw_multi_agent_role_create
201
+ cw_multi_agent_group_create
202
+ cw_multi_agent_membership_create
203
+ cw_multi_agent_fanout_create
204
+ cw_multi_agent_fanin_collect
205
+ ```
206
+
207
+ There is no MCP-only or CLI-only core model. The dogfood release script remains
208
+ CLI-only because it is a local release-engineering composition of existing CW
209
+ tools, not a new runtime primitive.
210
+
211
+ ## Compatibility
212
+
213
+ Older v0.1.16 and earlier run state normalizes with:
214
+
215
+ ```json
216
+ {
217
+ "multiAgent": {
218
+ "schemaVersion": 1,
219
+ "runs": [],
220
+ "roles": [],
221
+ "groups": [],
222
+ "memberships": [],
223
+ "fanouts": [],
224
+ "fanins": []
225
+ }
226
+ }
227
+ ```
228
+
229
+ Unknown user data is preserved. Fixtures are copied before compatibility tests,
230
+ and fixture files are not mutated.
231
+ 0.1.51
@@ -0,0 +1,103 @@
1
+ # Multi-Agent Topologies
2
+
3
+ CW v0.1.19 adds the first official topology layer on top of the Multi-Agent
4
+ Runtime Core and Coordinator / Blackboard.
5
+
6
+ Topologies are userland recipes, not hidden automation. Applying a topology
7
+ materializes ordinary CW records: `MultiAgentRun`, roles, groups, fanouts,
8
+ fanins, blackboard topics, messages, coordinator decisions, audit events,
9
+ candidate links, selections, commits, and graph nodes.
10
+
11
+ ## Official Topologies
12
+
13
+ - `map-reduce`: creates mapper roles, a reducer role, mapper fanout, mapper
14
+ output topics, reducer synthesis topics, and fail-closed fanin readiness.
15
+ - `debate`: creates opposing roles, debate round topics, conflict context,
16
+ coordinator claim decisions, and a final synthesis role.
17
+ - `judge-panel`: creates independent judge roles, a panel chair, judge verdict
18
+ topics, score aggregation expectations, and panel decision provenance.
19
+
20
+ ## Contract
21
+
22
+ Each topology definition declares:
23
+
24
+ - roles and groups
25
+ - blackboard topics
26
+ - phases
27
+ - fanout and fanin strategy
28
+ - required evidence
29
+ - coordinator decision kinds
30
+ - candidate and scoring expectations
31
+ - verifier gates
32
+
33
+ Durable topology run records live in:
34
+
35
+ ```text
36
+ .cw/runs/<run-id>/topologies/index.json
37
+ .cw/runs/<run-id>/topologies/runs/<topology-run-id>.json
38
+ ```
39
+
40
+ The topology record links to the generated multi-agent run, roles, groups,
41
+ fanouts, fanins, blackboard topics, messages, coordinator decisions,
42
+ candidates, selections, commits, and trust audit events.
43
+
44
+ ## CLI
45
+
46
+ ```bash
47
+ node scripts/cw.js topology list
48
+ node scripts/cw.js topology show map-reduce
49
+ node scripts/cw.js topology validate map-reduce
50
+ node scripts/cw.js topology apply <run-id> map-reduce --task map:server-api --mapper-count 2
51
+ node scripts/cw.js topology summary <run-id>
52
+ node scripts/cw.js topology graph <run-id>
53
+ ```
54
+
55
+ Apply commands are JSON-first. `summary` and `graph` also support human output
56
+ and `--json`.
57
+
58
+ ## MCP
59
+
60
+ MCP parity tools:
61
+
62
+ - `cw_topology_list`
63
+ - `cw_topology_show`
64
+ - `cw_topology_validate`
65
+ - `cw_topology_apply`
66
+ - `cw_topology_summary`
67
+ - `cw_topology_graph`
68
+
69
+ There is no topology behavior that is intentionally CLI-only.
70
+
71
+ ## Fail Closed
72
+
73
+ Topology fanin uses the existing `AgentFanin` checks. Required roles without
74
+ memberships, memberships without result evidence, and memberships without
75
+ indexed blackboard evidence remain blocked. A topology run can recommend the
76
+ next command, but it does not silently mark missing evidence as complete.
77
+
78
+ For map-reduce, reducer readiness requires mapper evidence and blackboard
79
+ artifact refs. For debate, synthesis must cite messages, conflict context, and
80
+ coordinator decisions. For judge-panel, no judge output is authoritative until
81
+ fanin and score evidence support a panel decision.
82
+
83
+ ## Operator UX
84
+
85
+ `status`, `report --show`, and `graph` include topology progress:
86
+
87
+ - topology id and topology run id
88
+ - generated multi-agent run and blackboard id
89
+ - roles, topics, fanouts, and fanins
90
+ - readiness and missing evidence
91
+ - conflicts
92
+ - deterministic next action
93
+
94
+ Trust audit summaries include topology event counts, and audit provenance can
95
+ follow worker evidence into blackboard artifacts, fanin, candidate selection,
96
+ commits, and reports.
97
+
98
+ CW v0.1.22 adds policy-aware topology inspection. Applying a topology records
99
+ role policies, message provenance, blackboard write audit, judge rationale,
100
+ panel decisions, and policy violations through the same trust-audit log used by
101
+ worker sandbox and evidence provenance records. Judge-panel selection now
102
+ requires evidence-backed judge rationale and panel-chair rationale.
103
+ 0.1.51