cool-workflow 0.1.82 → 0.1.83

package/docs/multi-agent-operator-ux.7.md

@@ -1,37 +1,37 @@
 # Multi-Agent Operator UX
 
-CW v0.1.21 makes multi-agent operator inspection first-class. The feature is a
-read-only userland view over existing run state. It does not create a hidden
-dashboard database and does not infer success when evidence, dependency, or
-lifecycle state is ambiguous.
-CW v0.1.22 adds trust panels to the same operator path so role policy,
+CW v0.1.21 makes multi-agent operator inspection a first-class part. The feature is a
+read-only userland view of the run state you already have. It does not make a hidden
+dashboard database, and it does not guess success when evidence, dependency, or
+lifecycle state is not clear.
+CW v0.1.22 adds trust panels to the same operator path, so role policy,
 permission decisions, blackboard write audit, message provenance, judge
-rationale, panel decisions, and policy violations are visible beside topology
+rationale, panel decisions, and policy violations are seen next to topology
 and evidence state.
 CW v0.1.24 uses the same operator-derived graph, dependency, failure, evidence,
 trust, and report views as replay comparison inputs for the Multi-Agent Eval &
 Replay Harness.
-CW v0.1.25 layers State Explosion Management on top of these operator views: when
-a run grows large, `summary show`, `multi-agent summarize`, and
-`multi-agent graph --view compact` collapse high-volume records into synthetic
-summary nodes while preserving the critical path, failures, missing evidence,
+CW v0.1.25 puts State Explosion Management on top of these operator views: when
+a run gets large, `summary show`, `multi-agent summarize`, and
+`multi-agent graph --view compact` fold high-volume records into made-up
+summary nodes, while keeping the critical path, failures, missing evidence,
 policy violations, and judge rationale. See
 [state-explosion-management.7.md](state-explosion-management.7.md).
 
 CW v0.1.26 adds the `Adoption Rationale` panel and the `multi-agent reasoning`
-view, which explains *why* each evidence item was adopted. Reasoning steps are on
-the critical path and are never collapsed by compaction. See
+view, which makes clear *why* each evidence item was adopted. Reasoning steps are on
+the critical path and are never folded away by compaction. See
 [evidence-adoption-reasoning-chain.7.md](evidence-adoption-reasoning-chain.7.md).
 
 CW v0.1.27 adds an additive evidence `disposition` (`adopted` | `inspectable` |
 `blocking`) and an `inspectableEvidence` list. The raw `status` (the adoption
-state) is unchanged; `disposition` is the operator-facing reading of it. Before a
-verifier-gated commit, a missing/pending row genuinely blocks. After a
-verifier-gated commit the selected path is decided, so missing/pending evidence
+state) is not changed; `disposition` is how the operator reads it. Before a
+verifier-gated commit, a missing/pending row truly blocks. After a
+verifier-gated commit the selected path is fixed, so missing/pending evidence
 for sibling roles that were never driven as separate workers — for example
 undriven judge-panel judges — is inspectable operator state, not a hidden
 failure. The `multi-agent status` "Missing Evidence" header and the `status`
-panel report the blocking-vs-inspectable split so the operator is not misled.
+panel show the blocking-vs-inspectable split so the operator is not given the wrong idea.
 
 The model is derived from:
 
@@ -47,7 +47,7 @@ The model is derived from:
 
 ## Operator Commands
 
-Use the normal status and report commands for the broad view:
+Use the normal status and report commands for the wide view:
 
 ```bash
 node scripts/cw.js status <run-id>
@@ -55,7 +55,7 @@ node scripts/cw.js graph <run-id>
 node scripts/cw.js report <run-id> --show
 ```
 
-Use the focused multi-agent views when the operator needs the process table:
+Use the focused multi-agent views when the operator needs the process table.
 
 ```bash
 node scripts/cw.js multi-agent status <run-id>
@@ -65,7 +65,7 @@ node scripts/cw.js multi-agent failures <run-id>
 node scripts/cw.js multi-agent evidence <run-id>
 ```
 
-Every focused command supports deterministic JSON:
+Every focused command can give deterministic JSON:
 
 ```bash
 node scripts/cw.js multi-agent status <run-id> --json
@@ -87,7 +87,7 @@ Next Action
 
 ## Graph
 
-`multi-agent graph` shows the topology-backed agent graph plus downstream
+`multi-agent graph` shows the topology-backed agent graph and the downstream
 acceptance records:
 
 - MultiAgentRun, topology run, roles, groups, memberships, fanout, and fanin
@@ -96,7 +96,7 @@ acceptance records:
   decisions
 - candidates, score records, selections, verifier-gated commits, and feedback
 
-Edges are labeled when the label carries operational meaning:
+Edges are labeled when the label gives operational meaning:
 
 ```text
 owns
@@ -115,12 +115,12 @@ commits
 
 Direction follows the dependency or evidence flow. For example, a membership
 depends on a task and worker, worker output reports into the membership,
-blackboard artifacts are cited by fanin, scores evaluate candidates, selections
-choose scored candidates, and commits record the selected verifier-gated result.
+blackboard artifacts are cited by fanin, scores judge candidates, selections
+pick scored candidates, and commits record the selected verifier-gated result.
 
 ## Failures
 
-`multi-agent failures` merges the records an operator normally has to inspect
+`multi-agent failures` joins the records an operator normally has to look at
 one at a time:
 
 - failed memberships and missing role coverage
@@ -131,14 +131,14 @@ one at a time:
 - score, selection, verifier, and commit-gate gaps
 - ambiguous blocked dependencies
 
-Each row includes the record id, kind, status, owner or role when known, linked
+Each row has the record id, kind, status, owner or role when known, linked
 task/worker/membership/fanin/candidate when known, the exact reason, and the
 next safe command.
 
 ## Evidence Adoption
 
-`multi-agent evidence` explains why a result was accepted or not accepted. Each
-row includes:
+`multi-agent evidence` makes clear why a result was accepted or not accepted. Each
+row has:
 
 - evidence id/ref/path/locator
 - source kind and source id
@@ -149,19 +149,19 @@ row includes:
 - status: `adopted`, `rejected`, `pending`, `superseded`, `conflicting`, or
   `missing`
 
-An accepted path should be traceable like this:
+An accepted path should be possible to trace like this:
 
 ```text
 worker result -> blackboard artifact/message -> fanin -> candidate score
 -> selection -> verifier-gated commit
 ```
 
-When any link is missing, CW reports it as pending or missing and recommends the
-next command rather than assuming the run is healthy.
+When any link is missing, CW reports it as pending or missing and points to the
+next command, instead of taking it for granted that the run is healthy.
 
 ## MCP Parity
 
-MCP hosts can inspect the same derived data:
+MCP hosts can look at the same derived data:
 
 - `cw_multi_agent_status`
 - `cw_multi_agent_graph`
@@ -169,7 +169,7 @@ MCP hosts can inspect the same derived data:
 - `cw_multi_agent_failures`
 - `cw_multi_agent_evidence`
 
-`cw_multi_agent_status` preserves the v0.1.20 host envelope and adds the
+`cw_multi_agent_status` keeps the v0.1.20 host envelope and adds the
 derived operator model under `summaries.multiAgentOperator`.
 
 ## Example Trace
@@ -186,59 +186,59 @@ node scripts/cw.js report "$RUN" --show
 
 The operator can start at an agent membership, follow `depends-on` to its task
 and worker, follow `reports` to the blackboard artifact and fanin, follow
-`scores` to the candidate score, follow `selects` to the selected result, and
+`scores` to the candidate score, follow `selects` to the picked result, and
 follow `commits` to the verifier-gated state commit.
 
 ## Smoke Coverage
 
-`test/multi-agent-operator-ux-smoke.js` creates a deterministic topology-backed
-run with a successful worker evidence path, a failed worker path, blocked fanin
+`test/multi-agent-operator-ux-smoke.js` makes a deterministic topology-backed
+run with a good worker evidence path, a failed worker path, blocked fanin
 evidence, score and selection records, a verifier-gated commit, human CLI
 assertions, JSON CLI assertions, MCP parity assertions, and report assertions.
-It is included in `npm test` and `npm run release:check`.
+It is part of `npm test` and `npm run release:check`.
 ## CLI ↔ MCP Parity (v0.1.27)
 
-Every command and tool referenced above is declared in the v0.1.27 capability
-registry (`src/capability-registry.ts`) and validated by `npm run parity:check`,
-so `cw <cmd> --json` and the matching `cw_<tool>` result render one data source.
+Every command and tool named above is declared in the v0.1.27 capability
+registry (`src/capability-registry.ts`) and checked by `npm run parity:check`,
+so `cw <cmd> --json` and the matching `cw_<tool>` result show one data source.
 See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
 
 ## Run Registry / Control Plane (v0.1.28)
 
-The runs described here are indexed, searchable, resumable, archivable, and
-rerunnable across repos by the v0.1.28 Run Registry / Control Plane, which derives
+The runs talked about here are indexed, searchable, resumable, archivable, and
+rerunnable across repos by the v0.1.28 Run Registry / Control Plane, which makes
 a fingerprinted, fail-closed index over the same per-run `.cw/runs/<id>/state.json`
 source of truth. See [run-registry-control-plane.7.md](run-registry-control-plane.7.md).
 
 ## Execution Backends (v0.1.29)
 
-v0.1.29 lifts execution into a pluggable driver layer: one narrow `ExecutionBackend`
-contract with interchangeable `node`/`bun`/`shell`/`container`/`remote`/`ci`
-drivers, selected by `--backend` (parallel to `--sandbox`) and inspected via
+v0.1.29 moves execution into a pluggable driver layer: one narrow `ExecutionBackend`
+contract with swappable `node`/`bun`/`shell`/`container`/`remote`/`ci`
+drivers, chosen by `--backend` (parallel to `--sandbox`) and looked at through
 `backend list|show|probe`. The result/evidence envelope is schema-identical across
 backends; the backend id + sandbox attestation are recorded as provenance, so this
-surface is unchanged regardless of which backend executed a run. See
+surface stays the same no matter which backend ran a run. See
 [execution-backends.7.md](execution-backends.7.md).
 ## Web / Desktop Workbench (v0.1.30)
 
 v0.1.30 adds the Web / Desktop Workbench: a read-only, localhost-only human
-console that renders this surface (and the other four operator panels — run
+console that shows this surface (and the other four operator panels — run
 graph, blackboard, worker logs, candidate compare, audit timeline) for any run,
-reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR alongside
+reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR next to
 the CLI and MCP that holds no authoritative state and forks no schema: each panel
-equals its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
-re-derives everything from disk. See
+is the same as its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
+makes everything again from disk. See
 [web-desktop-workbench.7.md](web-desktop-workbench.7.md).
 
 ## Observability + Cost Accounting (v0.1.31)
 
 v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
-derive durations, failure/verifier/acceptance rates (with sample counts and
-fail-closed `n/a`), and host-attested token/cost from existing durable run state
-— no metrics database, no collector daemon, no hidden counter. Usage is additive
+work out durations, failure/verifier/acceptance rates (with sample counts and
+fail-closed `n/a`), and host-attested token/cost from the durable run state you
+already have — no metrics database, no collector daemon, no hidden counter. Usage is additive
 and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
 × a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
-verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
+verbs are parity-gated and show read-only in the v0.1.30 Workbench. See
 [observability-cost-accounting.7.md](observability-cost-accounting.7.md).
 
 
@@ -247,11 +247,11 @@ verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
 v0.1.32 adds Team Collaboration: a host-attested actor and append-only
 approvals/rejections/comments/handoffs provenance-linked to a durable target,
 plus a review gate that STACKS ON the verifier gate — required approvals from
-authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
-and never instead of them, failing closed on quorum/authority/self-approval and
+authorized roles, made to happen inside `resolveCommitGate` AFTER the verifier checks
+and never in place of them, failing closed on quorum/authority/self-approval and
 recording who approved the very artifact that shipped. Policy (required approvals,
 authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
-unchanged). The verbs are parity-gated and render read-only in the v0.1.30
+not changed). The verbs are parity-gated and show read-only in the v0.1.30
 Workbench. See [Team Collaboration](team-collaboration.7.md).
 
 ## Release Tooling (v0.1.33)
@@ -260,11 +260,11 @@ the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffo
 
 ## Real Execution Backend Integrations (v0.1.34)
 
-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).
+container/remote/ci backends truly 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 not there to use. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
-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).
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, using again the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
 
 ## Contract Migration Tooling (v0.1.36)
 
@@ -276,11 +276,11 @@ priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed pa
 
 ## Agent Delegation Drive (v0.1.38)
 
-spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+spawn an outside agent process per worker, take result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
 
 ## Run Retention & Provable Reclamation (v0.1.39)
 
-tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, and prove it
 
 ## Durable State & Locking (v0.1.40)
 
@@ -292,15 +292,15 @@ evidence grounding + durable audit append + symlink-hardened containment + deter
 
 ## Robust Result Ingest (v0.1.42)
 
-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
+take findings/evidence from any reasonable agent shape (alt keys + prose), CW works out grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
-Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+Hard gate that blocks empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
 
 ## Release-Gate Determinism & Agents Vendor (v0.1.44)
 
-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.
+Release-readiness checks now check the committed blob (`git show HEAD:<path>`) instead of the changeable working tree — taking away 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 that gives any non-Claude AI agent one common interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -317,7 +317,11 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 
 ## 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.
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, useful background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
-_No changes to the multi-agent operator UX surface in v0.1.81 (the operator-ux module was carved into behavior-preserving siblings; output is byte-identical)._
+_No changes to the multi-agent operator UX surface in v0.1.81 (the operator-ux module was cut into behavior-preserving siblings; output is byte-identical)._
 _No changes in v0.1.82._
+
+## Hardening and Onboarding (v0.1.83)
+
+Loaders fail closed on corrupt state; store writes are made safe under more than one writer; a new cw doctor checks your setup; help lists every command; and the docs are put into Basic English.

package/docs/multi-agent-runtime-core.7.md

@@ -1,21 +1,21 @@
 # Multi-Agent Runtime Core
 
-CW v0.1.17 made multi-agent runtime state first-class. Dispatches and worker
-records still exist, but they now have explicit process-table-style state around
+CW v0.1.17 made multi-agent runtime state a first-class thing. Dispatches and worker
+records are still here, but now they have clear process-table-style state around
 them: `MultiAgentRun`, `AgentRole`, `AgentGroup`, `AgentMembership`,
 `AgentFanout`, and `AgentFanin`.
 
-CW v0.1.18 extends these records with blackboard and topic links so fanout,
-worker manifests, accepted worker output, and fanin evidence can cite the
+CW v0.1.18 adds blackboard and topic links to these records so that fanout,
+worker manifests, accepted worker output, and fanin evidence can point to the
 Coordinator / Blackboard substrate.
 
-This release is the runtime core, not an autonomous scheduler. CW records and
-validates the state model. The agent host still executes agents and enforces
+This release is the runtime core, not a self-acting scheduler. CW keeps and
+checks the state model. The agent host still runs agents and keeps watch over
 OS/process/network/environment controls.
 
 ## State Model
 
-Multi-agent state lives in durable run state:
+Multi-agent state is kept in lasting run state:
 
 ```text
 .cw/runs/<run-id>/state.json
@@ -29,7 +29,7 @@ Multi-agent state lives in durable run state:
     fanins: []
 ```
 
-CW also mirrors records to local JSON files:
+CW also copies records to local JSON files:
 
 ```text
 .cw/runs/<run-id>/multi-agent/
@@ -42,51 +42,51 @@ CW also mirrors records to local JSON files:
   fanins/<fanin-id>.json
 ```
 
-All records carry stable ids, timestamps, schema versions, lifecycle history,
-parent/child links where relevant, and metadata. Records link back to the
-existing workflow run, phase, task, dispatch, worker, result, verifier,
+All records have fixed ids, timestamps, schema versions, lifecycle history,
+parent/child links where they are needed, and metadata. Records link back to the
+present workflow run, phase, task, dispatch, worker, result, verifier,
 candidate, commit, and audit surfaces.
 
 ## Runtime Objects
 
-`MultiAgentRun` is the top-level runtime table entry for coordinated agent work.
+`MultiAgentRun` is the top-level runtime table entry for joined-up agent work.
 Its lifecycle is:
 
 ```text
 planned -> forming -> running -> collecting -> verifying -> completed
 ```
 
-It may also move to `failed` or `cancelled`. Invalid lifecycle transitions fail
+It may also move to `failed` or `cancelled`. Bad lifecycle transitions fail
 closed.
 
-`AgentRole` describes responsibility, required evidence, sandbox profile hints,
-expected artifacts, and fanin obligations.
+`AgentRole` says what the work is, the evidence needed, sandbox profile hints,
+the artifacts looked for, and fanin duties.
 
-`AgentGroup` is a coordinated set of members for a phase or subproblem. Groups
+`AgentGroup` is a joined-up set of members for a phase or part-problem. Groups
 hold role, task, membership, worker, fanout, and fanin ids.
 
-`AgentMembership` binds one role to one task and, once dispatched, one worker.
-A worker can belong to one or more groups only through explicit membership
-records. Duplicate membership for the same group, role, task, and worker fails
+`AgentMembership` ties one role to one task and, once dispatched, one worker.
+A worker can be part of one or more groups only through clear membership
+records. A copy of the same group, role, task, and worker membership fails
 closed.
 
 `AgentFanout` records why work was split, which roles/tasks/workers were
-created or attached, concurrency limits, sandbox profile choices, dispatch ids,
-and the expected return shape.
+made or joined, concurrency limits, sandbox profile choices, dispatch ids,
+and the return shape looked for.
 
-`AgentFanin` records aggregation strategy, required roles, reported members,
-missing members, evidence coverage, blocked reasons, and verifier readiness.
-Fanin does not silently accept missing evidence for required roles.
+`AgentFanin` records the way work is brought together, required roles, members that reported,
+members that are missing, evidence coverage, blocked reasons, and verifier readiness.
+Fanin does not quietly take missing evidence for required roles.
 
 ## Dispatch Integration
 
-Existing dispatch and worker flows remain valid:
+Present dispatch and worker flows are still valid:
 
 ```bash
 node scripts/cw.js dispatch <run-id> --limit 1 --sandbox readonly
 ```
 
-To attach dispatch to explicit multi-agent state:
+To tie dispatch to clear multi-agent state:
 
 ```bash
 node scripts/cw.js multi-agent run <run-id> --id ma-release --objective "release verification"
@@ -128,12 +128,12 @@ Worker manifests then include:
 }
 ```
 
-When CW accepts worker output, it updates linked membership evidence and records
+When CW takes worker output, it updates linked membership evidence and records
 multi-agent trust audit events.
 
 ## Fanin
 
-Collect fanin after worker output:
+Gather fanin after worker output:
 
 ```bash
 node scripts/cw.js multi-agent fanin <run-id> release-fanin \
@@ -143,12 +143,12 @@ node scripts/cw.js multi-agent fanin <run-id> release-fanin \
 ```
 
 If a required role has no membership, or a membership has not reported evidence,
-the fanin record is `blocked` and `verifierReady=false`. This is intentional:
-missing evidence is a state error, not an implicit success.
+the fanin record is `blocked` and `verifierReady=false`. This is done on purpose:
+missing evidence is a state error, not a quiet success.
 
 ## Inspect
 
-Use normal operator commands:
+Use the everyday operator commands:
 
 ```bash
 node scripts/cw.js status <run-id>
@@ -158,7 +158,7 @@ node scripts/cw.js audit summary <run-id>
 node scripts/cw.js audit provenance <run-id>
 ```
 
-Use focused multi-agent commands:
+Use the more pointed multi-agent commands:
 
 ```bash
 node scripts/cw.js multi-agent summary <run-id>
@@ -175,7 +175,7 @@ node scripts/cw.js multi-agent fanin <run-id> <fanin-id>
 
 The status and report Multi-Agent panel shows group status, role coverage,
 membership health, fanout/fanin progress, blocked reasons, and the next
-recommended action.
+suggested action.
 
 ## MCP Parity
 
@@ -192,7 +192,7 @@ cw_multi_agent_fanout_show
 cw_multi_agent_fanin_show
 ```
 
-Safe write tools:
+Safe write tools are:
 
 ```text
 cw_multi_agent_run_create
@@ -204,13 +204,13 @@ cw_multi_agent_fanout_create
 cw_multi_agent_fanin_collect
 ```
 
-There is no MCP-only or CLI-only core model. The dogfood release script remains
-CLI-only because it is a local release-engineering composition of existing CW
+There is no MCP-only or CLI-only core model. The dogfood release script is still
+CLI-only because it is a local release-engineering build made from present CW
 tools, not a new runtime primitive.
 
 ## Compatibility
 
-Older v0.1.16 and earlier run state normalizes with:
+Older v0.1.16 and earlier run state is made regular with:
 
 ```json
 {
@@ -226,6 +226,6 @@ Older v0.1.16 and earlier run state normalizes with:
 }
 ```
 
-Unknown user data is preserved. Fixtures are copied before compatibility tests,
-and fixture files are not mutated.
+User data that is not known is kept safe. Fixtures are copied before compatibility tests,
+and fixture files are not changed.
 0.1.51

package/docs/multi-agent-topologies.7.md

@@ -3,23 +3,23 @@
 CW v0.1.19 adds the first official topology layer on top of the Multi-Agent
 Runtime Core and Coordinator / Blackboard.
 
-Topologies are userland recipes, not hidden automation. Applying a topology
-materializes ordinary CW records: `MultiAgentRun`, roles, groups, fanouts,
+Topologies are userland recipes, not hidden automation. When you apply a
+topology, it makes ordinary CW records: `MultiAgentRun`, roles, groups, fanouts,
 fanins, blackboard topics, messages, coordinator decisions, audit events,
 candidate links, selections, commits, and graph nodes.
 
 ## Official Topologies
 
-- `map-reduce`: creates mapper roles, a reducer role, mapper fanout, mapper
+- `map-reduce`: makes mapper roles, a reducer role, mapper fanout, mapper
   output topics, reducer synthesis topics, and fail-closed fanin readiness.
-- `debate`: creates opposing roles, debate round topics, conflict context,
+- `debate`: makes opposing roles, debate round topics, conflict context,
   coordinator claim decisions, and a final synthesis role.
-- `judge-panel`: creates independent judge roles, a panel chair, judge verdict
+- `judge-panel`: makes free judge roles, a panel chair, judge verdict
   topics, score aggregation expectations, and panel decision provenance.
 
 ## Contract
 
-Each topology definition declares:
+Each topology definition gives:
 
 - roles and groups
 - blackboard topics
@@ -30,14 +30,14 @@ Each topology definition declares:
 - candidate and scoring expectations
 - verifier gates
 
-Durable topology run records live in:
+Lasting topology run records are kept in:
 
 ```text
 .cw/runs/<run-id>/topologies/index.json
 .cw/runs/<run-id>/topologies/runs/<topology-run-id>.json
 ```
 
-The topology record links to the generated multi-agent run, roles, groups,
+The topology record links to the made multi-agent run, roles, groups,
 fanouts, fanins, blackboard topics, messages, coordinator decisions,
 candidates, selections, commits, and trust audit events.
 
@@ -52,7 +52,7 @@ node scripts/cw.js topology summary <run-id>
 node scripts/cw.js topology graph <run-id>
 ```
 
-Apply commands are JSON-first. `summary` and `graph` also support human output
+Apply commands are JSON-first. `summary` and `graph` also give human output
 and `--json`.
 
 ## MCP
@@ -66,38 +66,38 @@ MCP parity tools:
 - `cw_topology_summary`
 - `cw_topology_graph`
 
-There is no topology behavior that is intentionally CLI-only.
+There is no topology behavior that is made CLI-only on purpose.
 
 ## Fail Closed
 
-Topology fanin uses the existing `AgentFanin` checks. Required roles without
+Topology fanin uses the present `AgentFanin` checks. Required roles without
 memberships, memberships without result evidence, and memberships without
-indexed blackboard evidence remain blocked. A topology run can recommend the
-next command, but it does not silently mark missing evidence as complete.
+indexed blackboard evidence stay blocked. A topology run can put forward the
+next command, but it does not quietly mark missing evidence as complete.
 
-For map-reduce, reducer readiness requires mapper evidence and blackboard
+For map-reduce, reducer readiness needs mapper evidence and blackboard
 artifact refs. For debate, synthesis must cite messages, conflict context, and
-coordinator decisions. For judge-panel, no judge output is authoritative until
-fanin and score evidence support a panel decision.
+coordinator decisions. For judge-panel, no judge output has authority until
+fanin and score evidence back a panel decision.
 
 ## Operator UX
 
-`status`, `report --show`, and `graph` include topology progress:
+`status`, `report --show`, and `graph` take in topology progress:
 
 - topology id and topology run id
-- generated multi-agent run and blackboard id
+- made multi-agent run and blackboard id
 - roles, topics, fanouts, and fanins
 - readiness and missing evidence
 - conflicts
 - deterministic next action
 
-Trust audit summaries include topology event counts, and audit provenance can
+Trust audit summaries take in topology event counts, and audit provenance can
 follow worker evidence into blackboard artifacts, fanin, candidate selection,
 commits, and reports.
 
-CW v0.1.22 adds policy-aware topology inspection. Applying a topology records
-role policies, message provenance, blackboard write audit, judge rationale,
-panel decisions, and policy violations through the same trust-audit log used by
-worker sandbox and evidence provenance records. Judge-panel selection now
-requires evidence-backed judge rationale and panel-chair rationale.
+CW v0.1.22 adds policy-aware topology inspection. When you apply a topology, it
+records role policies, message provenance, blackboard write audit, judge
+rationale, panel decisions, and policy violations through the same trust-audit
+log used by worker sandbox and evidence provenance records. Judge-panel
+selection now needs evidence-backed judge rationale and panel-chair rationale.
 0.1.51