cool-workflow 0.1.81 → 0.1.83

package/docs/multi-agent-trust-policy-audit.7.md

@@ -1,15 +1,15 @@
 # Multi-Agent Trust / Policy / Audit
 
-CW v0.1.22 extends the existing trust-audit layer with first-class
-multi-agent policy, provenance, blackboard write audit, and judge rationale.
-It does not introduce a second audit subsystem.
-CW v0.1.24 includes these trust projections in eval/replay comparison so
-missing provenance, changed policy violations, or missing judge rationale fail
-the regression gate.
+CW v0.1.22 adds to the trust-audit layer that is already there. It gives
+first-class multi-agent policy, provenance, blackboard write audit, and judge
+rationale. It does not add a second audit subsystem.
+CW v0.1.24 puts these trust projections into eval/replay comparison, so
+missing provenance, changed policy violations, or missing judge rationale make
+the regression gate fail.
 
 ## Model
 
-Multi-agent trust state is plain JSON attached to existing records:
+Multi-agent trust state is plain JSON joined to records that are already there:
 
 - `AgentRole.policy`
 - `AgentGroup.policy`
@@ -18,7 +18,7 @@ Multi-agent trust state is plain JSON attached to existing records:
 - candidate score and selection audit links
 - append-friendly trust events in `.cw/runs/<run-id>/audit/events.jsonl`
 
-Policies describe explicit authority:
+Policies say clearly what is let through:
 
 - allowed blackboard topic ids
 - allowed write operations: `message`, `context`, `artifact`, `snapshot`,
@@ -30,11 +30,11 @@ Policies describe explicit authority:
 - denied operations and reasons
 
 Missing policy, missing role authority, out-of-scope topics, missing evidence,
-or missing judge rationale fail closed and create audit records.
+or missing judge rationale fail closed and make audit records.
 
 ## Audit Events
 
-The existing audit log records multi-agent dimensions with stable ids:
+The audit log that is already there keeps multi-agent dimensions with stable ids:
 
 - `multi-agent.role-policy`
 - `multi-agent.permission`
@@ -44,19 +44,19 @@ The existing audit log records multi-agent dimensions with stable ids:
 - `judge.panel-decision`
 - `policy.violation`
 
-Events carry ids such as `multiAgentRunId`, `agentRoleId`, `agentGroupId`,
+Events hold ids such as `multiAgentRunId`, `agentRoleId`, `agentGroupId`,
 `agentMembershipId`, `agentFanoutId`, `agentFaninId`, blackboard record ids,
 candidate/score/selection/commit ids, topology ids, `sandboxProfileId`, and
-`policyRef` when relevant.
+`policyRef` when they have a part to play.
 
-Audit events do not copy large blackboard bodies. Message provenance stores
-author kind/id, role/group/membership/worker ids when known, source, linked
-evidence refs, parent message ids, topic scope, a body hash, and a short
+Audit events do not copy large blackboard bodies. Message provenance keeps
+author kind/id, role/group/membership/worker ids when these are known, source,
+linked evidence refs, parent message ids, topic scope, a body hash, and a short
 summary.
 
 ## Blackboard Writes
 
-Every blackboard write is audited:
+Every blackboard write goes through audit:
 
 - topic create/update
 - message post
@@ -66,24 +66,24 @@ Every blackboard write is audited:
 - coordinator decision
 
 The audit record says who wrote, under which role or membership, which policy
-allowed or denied it, what evidence was cited, what record changed, and whether
-the write was accepted, denied, superseded, conflicting, or blocked.
+let it through or said no to it, what evidence was given, what record changed,
+and if the write was accepted, denied, superseded, conflicting, or blocked.
 
-Denied writes are rejected before state mutation and are visible through
-`policy.violation` and `blackboard.write` audit projections.
+Denied writes are turned away before state mutation, and you can see them
+through `policy.violation` and `blackboard.write` audit projections.
 
 ## Judge Rationale
 
-Judge-panel scoring requires evidence and rationale. Panel selection requires
-score evidence and chair rationale. Accepted judge and panel records cite the
-score, candidate, evidence refs, role policy, and parent audit events.
+Judge-panel scoring needs evidence and rationale. Panel selection needs
+score evidence and chair rationale. Accepted judge and panel records point to
+the score, candidate, evidence refs, role policy, and parent audit events.
 
 Missing rationale or evidence blocks score, selection, fanin readiness, and
-verifier-gated commit readiness where those gates depend on judge evidence.
+verifier-gated commit readiness where those gates lean on judge evidence.
 
 ## CLI
 
-Existing commands remain compatible:
+The commands that are already there still work the same way:
 
 ```bash
 node scripts/cw.js audit summary <run-id>
@@ -104,7 +104,7 @@ node scripts/cw.js audit judge <run-id>
 
 Use `--json` or `--format json` for deterministic machine output.
 
-Human output includes stable panels:
+Human output has stable panels:
 
 - Multi-Agent Trust
 - Role Policies
@@ -117,7 +117,7 @@ Human output includes stable panels:
 
 ## Verify (fail-closed)
 
-`audit summary` embeds an `integrity` field but is a *reader* — it always exits 0,
+`audit summary` puts in an `integrity` field but is a *reader* — it always exits 0,
 so it cannot gate a script. `audit verify` is the gate:
 
 ```bash
@@ -125,9 +125,9 @@ node scripts/cw.js audit verify <run-id>        # exit 1 if the chain is forged
 node scripts/cw.js audit verify <run-id> --json
 ```
 
-It re-proves the run's trust-audit hash chain offline: it recomputes every event
-hash from genesis, checks `prevEventHash` linkage, and catches the unchained-event
-forgery (an `eventHash`-less line slipped into a chained log to be waved through as
+It proves the run's trust-audit hash chain again offline: it works out every event
+hash from genesis, checks `prevEventHash` linkage, and finds the unchained-event
+forgery (an `eventHash`-less line put into a chained log to be waved through as
 "legacy"). The JSON reports `present`, `verified`, `eventCount`, `chained`,
 `unchained`, `corruptLines`, and `failedChecks[]`.
 
@@ -135,9 +135,9 @@ Exit-code contract (the peer of `telemetry verify`):
 
 - ANY **unverified** chain exits **1** — forged / edited / truncated / unchained-injected,
   *and* a fully-corrupt log (every line unparseable, which reports `present:false` but
-  `verified:false`). The gate keys on `verified`, not `present`, so the most severe
-  tamper — garbling the whole log — cannot escape by looking "absent". So
-  `cw audit verify <run> && deploy` stops on tampering.
+  `verified:false`). The gate keys on `verified`, not `present`, so the worst kind of
+  tamper — making a mess of the whole log — cannot get away by looking "absent". So
+  `cw audit verify <run> && deploy` stops when there is tampering.
 - Only a truly **absent / empty** chain is `verified:true` / exit **0** — a run with
   no audit log (or a blank one) has nothing to prove (no false-red).
 
@@ -151,10 +151,10 @@ MCP parity tools:
 - `cw_audit_blackboard`
 - `cw_audit_judge`
 
-The older audit tools remain available:
+The older audit tools are still there to use:
 
 - `cw_audit_summary`
-- `cw_audit_verify` — fail-closed re-prove of the trust-audit hash chain (peer of `cw_telemetry_verify`)
+- `cw_audit_verify` — fail-closed proof again of the trust-audit hash chain (peer of `cw_telemetry_verify`)
 - `cw_audit_worker`
 - `cw_audit_provenance`
 - `cw_audit_attest`
@@ -163,9 +163,9 @@ The older audit tools remain available:
 ## Operator Questions
 
 The combined `multi-agent status`, `multi-agent evidence`, `report --show`,
-`audit summary`, and `audit provenance` views answer:
+`audit summary`, and `audit provenance` views give the answers to:
 
-- Which role was allowed to do this?
+- Which role was let to do this?
 - Which blackboard message came from which role, member, or worker?
 - Which write was denied and why?
 - Which judge rationale was accepted?
@@ -173,7 +173,7 @@ The combined `multi-agent status`, `multi-agent evidence`, `report --show`,
 
 ## Regression
 
-`test/multi-agent-trust-policy-audit-smoke.js` creates a judge-panel run with
+`test/multi-agent-trust-policy-audit-smoke.js` makes a judge-panel run with
 allowed and denied blackboard writes, message provenance, role/membership/worker
 links, accepted judge rationale, missing-rationale and missing-evidence failure
 paths, CLI output assertions, MCP parity assertions, report assertions, and

package/docs/node-snapshot-diff-replay.7.md

@@ -2,42 +2,42 @@
 
 CW v0.1.35 adds Node Snapshot / Diff / Replay: per-NODE granularity over the
 v0.1.23 eval/replay harness. Before v0.1.35 the harness worked only at RUN/SUITE
-granularity — `createMultiAgentReplaySnapshot(run)` captured a whole run; there
-was no way to snapshot, fingerprint, diff, or replay a single `StateNode`. This
-release adds that, reusing the harness's normalize/stable-stringify discipline and
+granularity — `createMultiAgentReplaySnapshot(run)` took a picture of a whole run;
+there was no way to snapshot, fingerprint, diff, or replay a single `StateNode`. This
+release adds that. It reuses the harness's normalize/stable-stringify way of working and
 the v0.1.25 fingerprint/freshness pattern — without forking `StateNode`, the eval
 harness, or the run-state schema (all additive).
 
-The discipline is the same base-system separation used elsewhere: the mechanism
+This keeps the same base-system split used in other places: the mechanism
 captures/diffs/replays one node by id; nothing decides which node "matters".
 
 ## Snapshot — derived + fingerprinted
 
 A `NodeSnapshot` is a DERIVED projection of one `StateNode`: its body is normalized
-(timestamps/paths stripped via the eval harness's `normalizeValue`), so it is
+(timestamps/paths taken out via the eval harness's `normalizeValue`), so it is
 byte-stable across captures of the same logical state. It carries a
 `sourceFingerprint` — sha256 over the RAW node (`id:status:updatedAt` + artifact
-and evidence ids/paths) — so any transition flips it.
+and evidence ids/paths) — so any change to the state turns it over.
 
 ```text
 node snapshot <run-id> <node-id> [--json]
 ```
 
-Persisted under `<run>/nodes/snapshots/<node-id>/<snapshot-id>.json`; the source
+Kept under `<run>/nodes/snapshots/<node-id>/<snapshot-id>.json`; the source
 `<run>/nodes/<id>.json` stays the truth. The `snapshot-id` is content-addressed
-(`snap-<node>-<fingerprint>`), so re-snapshotting an unchanged node is idempotent.
+(`snap-<node>-<fingerprint>`), so taking a new snapshot of an unchanged node is idempotent.
 
 ## Freshness — fail closed on drift
 
-Every load recomputes the fingerprint from the current source and emits a
+Every load works out the fingerprint again from the current source and gives a
 freshness verdict:
 
 - `valid` — source matches the snapshot.
-- `stale` — the source node changed since capture.
+- `stale` — the source node changed after capture.
 - `absent` — the node, or a referenced artifact path, is gone/unreadable.
 
 `stale` and `absent` both REFUSE diff/replay with a structured `NodeSnapshotError`
-naming the divergence — never a silent stale replay, never a best-effort partial.
+naming the divergence — never a quiet stale replay, never a best-effort partial.
 
 ## Diff — stable + structural
 
@@ -46,7 +46,7 @@ node diff <run-id> <baseline-snapshot-id> <candidate-snapshot-id> [--json]
 ```
 
 Per-section (`status`/`inputs`/`outputs`/`artifacts`/`evidence`/`errors`/`links`/
-`metadata`) `added|removed|changed|same`, ordered deterministically by the same
+`metadata`) `added|removed|changed|same`, put in order deterministically by the same
 `stableStringify` the eval comparison uses. Byte-identical across repeated runs.
 
 ## Replay — isolated + deterministic
@@ -55,10 +55,10 @@ Per-section (`status`/`inputs`/`outputs`/`artifacts`/`evidence`/`errors`/`links`
 node replay <run-id> <snapshot-id> [--json]
 ```
 
-Reconstructs the normalized node from the snapshot with `now` INJECTED — no
+Builds the normalized node again from the snapshot with `now` INJECTED — no
 ambient `new Date()` in the deterministic payload. The result carries an
 `outputFingerprint` over the normalized body, so two replays of one snapshot are
-byte-identical (only `replayedAt`/`replayId`, which are now-derived, differ).
+byte-identical (only `replayedAt`/`replayId`, which come from now, are different).
 Replaying a `stale`/`absent` snapshot fails closed.
 
 ## Verify — replay vs source
@@ -67,7 +67,7 @@ Replaying a `stale`/`absent` snapshot fails closed.
 node verify <run-id> <replay-id> [--json]
 ```
 
-Compares a replay to a FRESH snapshot of the source node and emits a pass/fail
+Compares a replay to a FRESH snapshot of the source node and gives a pass/fail
 verdict plus findings in the eval harness's `severity/category/reason/baselineRef/
 replayRef` shape.
 
@@ -77,9 +77,9 @@ replayRef` shape.
 capability registry as `surface: "both"`, so `cw node <verb> --json` and the
 `cw_node_*` MCP tools render one core (`src/node-snapshot.ts`). Additive: no change
 to `StateNode`, `STATE_NODE_SCHEMA_VERSION`, the run-state schema, the pipeline
-contract, or existing eval-suite artifacts; pre-0.1.35 runs and snapshots stay
-loadable. Exporting the previously-private eval-harness helpers
-(`normalizeValue`/`stableStringify`/`lines`) and `fingerprintStrings` is purely
+contract, or existing eval-suite artifacts; pre-0.1.35 runs and snapshots can still
+be loaded. Making the once-private eval-harness helpers
+(`normalizeValue`/`stableStringify`/`lines`) and `fingerprintStrings` public is purely
 additive and changes no behavior.
 
 ## See Also
@@ -113,7 +113,7 @@ 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
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW works out grounded evidence by itself, gives a warning on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
@@ -121,7 +121,7 @@ Hard gate blocking empty-capture verifier-gated commits, plus quickstart and lau
 
 ## 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 mutable working tree — getting rid of false-red/false-green from working-tree writes that happen at the same time (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)
 
@@ -138,6 +138,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, wrapper metrics you can measure, a background full-review handoff you can act on, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
 _No changes to node-snapshot diff/replay in v0.1.81._
+_No change in behavior in v0.1.82 (the node projection field set was brought together into one source of truth; snapshot/replay digests are byte-identical)._
+
+## 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/observability-cost-accounting.7.md

@@ -3,28 +3,28 @@
 CW v0.1.31 adds Observability + Cost Accounting: time/duration, failure rate,
 verifier pass rate, candidate acceptance rate, and token/cost — all DERIVED from
 the run state CW already keeps. Before v0.1.31 there was no metrics module and no
-token or cost field anywhere; run state already carried `createdAt`/`updatedAt`/
+token or cost field anywhere; run state already had `createdAt`/`updatedAt`/
 `completedAt`/`dispatchedAt` and outcome statuses on tasks, workers, verifier
-nodes, candidates, memberships, and feedback. This release projects those into a
-report — and adds an additive, host-attested usage record so cost can be
-accounted honestly — without changing the `ResultEnvelope` schema and without
-taking ownership of source truth.
+nodes, candidates, memberships, and feedback. This release turns those into a
+report — and adds an added-on, host-attested usage record so cost can be
+worked out in an honest way — without changing the `ResultEnvelope` schema and without
+taking over the source truth.
 
-The design follows the same base-system observability philosophy as
+The design keeps to the same base-system observability idea as
 [State Explosion Management](state-explosion-management.7.md) and the
 [Run Registry / Control Plane](run-registry-control-plane.7.md):
 
 - the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
-- metrics are a DERIVED projection of source records, never a separate database
+- metrics are a DERIVED view of source records, never a separate database
 - no telemetry pipeline, no background collector daemon, no hidden counters
 - plain files, stable JSON, deterministic output
-- fail closed: a rate over zero samples is `n/a`, never a fabricated 0%/100%
-- cost is ATTESTED, never measured or fabricated; absent usage is `unreported`
-- backward compatible; usage/cost fields are additive and optional
+- fail closed: a rate over zero samples is `n/a`, never a made-up 0%/100%
+- cost is ATTESTED, never measured or made up; missing usage is `unreported`
+- backward compatible; usage/cost fields are added-on and optional
 
 ## Derived, not a telemetry pipeline
 
-Every number is a projection of existing durable state:
+Every number comes from durable state that is already there:
 
 - durations come from recorded timestamps — `dispatchedAt`→`completedAt` for
   tasks, `createdAt`→worker output `recordedAt` for workers, `createdAt`→
@@ -34,31 +34,31 @@ Every number is a projection of existing durable state:
   total of those samples;
 - the verifier pass rate counts `verifier` state nodes whose status is a pass
   (`verified`/`committed`) against decided gates (pass + `failed`/`rejected`/
-  `blocked`); pending/running gates are undecided and excluded;
+  `blocked`); pending/running gates are not yet decided and left out;
 - the candidate acceptance rate counts `selected`/`verified` candidates over all
   candidate records.
 
 There is no metrics store. `deriveMetricsReport(run, { now, policy })` is a PURE
 function of one run's state, an injected `now`, and an optional pricing policy.
-The only now-derived field is `generatedAt`; durations are computed from recorded
+The only now-derived field is `generatedAt`; durations are worked out from recorded
 timestamps, so a report over a fixed snapshot is byte-reproducible (eval/replay
-agnostic). The per-run report is persisted as a rebuildable, fingerprinted
+agnostic). The per-run report is kept as a rebuildable, fingerprinted
 snapshot under `.cw/runs/<id>/metrics/metrics-report.json`; the cross-repo
 summary reports each run's snapshot freshness as `valid|stale|absent` against
-current source — fail closed, exactly like the registry.
+current source — fail closed, just like the registry.
 
 ## A counter you cannot trust is worse than none
 
 Each rate is a `RateMetric` carrying `state` (`ok`/`n/a`), `count`, `total`,
 `rate`, and per-bucket sample counts. Over zero samples the state is `n/a` and
-`count`/`rate` are `null` — never `0`. No divide-by-zero, no partial-data rate
-presented as complete. Sample counts and buckets accompany every rate so a reader
-can audit the numerator and denominator.
+`count`/`rate` are `null` — never `0`. No divide-by-zero, and no part-data rate
+shown as if it were complete. Sample counts and buckets come with every rate so a reader
+can check the numerator and denominator.
 
 ## Cost is attested, never measured or fabricated
 
 CW does not call the model; the host/worker does. Token usage is recorded as
-HOST-ATTESTED provenance — a `UsageRecord` accepted on the existing intake path
+HOST-ATTESTED provenance — a `UsageRecord` taken in on the existing intake path
 and stored on the task or worker record (never on `ResultEnvelope`):
 
 ```
@@ -68,15 +68,15 @@ cw result <run-id> <task-id> <file> \
 cw worker output <run-id> <worker-id> <file> --usage-input-tokens N --usage-output-tokens M --usage-model ID
 ```
 
-CW records what the host attests, verbatim, and synthesizes nothing. When the
-host reports no usage the value is an explicit `unreported` — never `0`, never a
-silent guess. The report surfaces `usage.coverage` (the fraction of work units
-carrying attested usage) and `usage.unreportedUnits` so the gap is visible.
+CW records what the host attests, word for word, and makes up nothing. When the
+host reports no usage the value is a clear `unreported` — never `0`, never a
+quiet guess. The report shows `usage.coverage` (the part of work units
+carrying attested usage) and `usage.unreportedUnits` so the gap can be seen.
 
-A monetary figure is `attested` ONLY when derived from attested usage × a
+A money figure is `attested` ONLY when it comes from attested usage × a
 recorded pricing policy with an EXACT model match. When a model is priced by the
-policy's `defaultPrice` fallback, that portion is a SEPARATE `estimated` figure
-and the cost `state` becomes `estimated`; the two USD figures are never conflated
+policy's `defaultPrice` fallback, that part is a SEPARATE `estimated` figure
+and the cost `state` becomes `estimated`; the two USD figures are never mixed
 into one. Cost states:
 
 - `attested` — every attested model exact-matched a policy entry;
@@ -87,23 +87,23 @@ into one. Cost states:
 ## Mechanism vs policy: pricing is data
 
 The runtime is MECHANISM: it records attested usage and derives rates/durations.
-The pricing table is POLICY — supplied as DATA (`CostPolicy`), not baked into the
-kernel. The same attested usage yields different cost reports under different
+The pricing table is POLICY — given as DATA (`CostPolicy`), not built into the
+kernel. The same attested usage gives different cost reports under different
 pricing without touching the runtime. A bundled EXAMPLE policy lives at
-`manifest/pricing.policy.json` (USD per 1e6 tokens, an editable starting point —
+`manifest/pricing.policy.json` (USD per 1e6 tokens, a starting point you can edit —
 not a live price feed); pass `--pricing <path>` to use your own, or
-`--pricing default` for the bundled example. With no policy supplied, cost is
+`--pricing default` for the bundled example. With no policy given, cost is
 `unpriced`/`unreported`, never guessed.
 
 ## One source, every surface
 
 The metrics verbs are declared once in `src/capability-registry.ts`, so the CLI
-and MCP surfaces are two renderings of one core (`src/observability.ts`) and pass
+and MCP surfaces are two views of one core (`src/observability.ts`) and pass
 the v0.1.27 parity gate — `cw <cmd> --json` is byte-identical to `cw_<tool>`
 (durations are integers from recorded timestamps; only the ISO `generatedAt` is
-now-derived and neutralized by the parity probe). The v0.1.30 Workbench renders a
+now-derived and made neutral by the parity probe). The v0.1.30 Workbench renders a
 read-only metrics panel from the same payload, showing coverage and
-`unreported`/`n/a` honestly — it shows nothing the CLI/MCP cannot.
+`unreported`/`n/a` in an honest way — it shows nothing the CLI/MCP cannot.
 
 ## Commands
 
@@ -112,11 +112,11 @@ read-only metrics panel from the same payload, showing coverage and
   the canonical payload; `--pricing <path>|default` to price attested usage.
 - `cw metrics summary` — the cross-repo rollup over the v0.1.28 run registry:
   pooled rates, summed attested usage/cost with coverage, and per-app and
-  per-backend breakdowns. `--scope repo|home`; unreadable runs are counted
-  (`unreadableRuns`), never silently dropped.
+  per-backend breakdowns. `--scope repo|home`; runs that cannot be read are counted
+  (`unreadableRuns`), never quietly dropped.
 
-MCP hosts call `cw_metrics_show` and `cw_metrics_summary` with the identical
-payloads. Old runs load and report `unreported` cost while still yielding correct
+MCP hosts call `cw_metrics_show` and `cw_metrics_summary` with the same
+payloads. Old runs load and report `unreported` cost while still giving correct
 time and rate metrics from their existing timestamps and outcomes.
 
 This document targets CW 0.1.31.
@@ -127,8 +127,8 @@ This document targets CW 0.1.31.
 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 hold 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
@@ -136,11 +136,11 @@ Workbench. See [Team Collaboration](team-collaboration.7.md).
 
 ## Release Tooling (v0.1.33)
 
-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).
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a release gate that drops repeats. See release-tooling(7).
 
 ## 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 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 cannot be reached. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -172,7 +172,7 @@ 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
+capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, give a warning on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
@@ -180,7 +180,7 @@ Hard gate blocking empty-capture verifier-gated commits, plus quickstart and lau
 
 ## 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 validate the committed blob (`git show HEAD:<path>`) instead of the mutable 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 giving any non-Claude AI agent one common interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -197,6 +197,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, background full-review handoff you can act on, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
-_No changes to the observability + cost-accounting surface in v0.1.81 (the observability module was carved into behavior-preserving siblings; output is byte-identical)._
+_No changes to the observability + cost-accounting surface in v0.1.81 (the observability module was split 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.