cool-workflow 0.1.81 → 0.1.83

package/docs/contract-migration-tooling.7.md

@@ -1,23 +1,24 @@
 # Contract Migration Tooling
 
-CW v0.1.36 makes schema migration a first-class, declared subsystem. Before
-v0.1.36 migration was ad-hoc and run-state-only: `RUN_STATE_MIGRATIONS` was an
-inline step array walked by `migrateRunState`, with no declared `up`-transform
-registry, no recorded compatibility PROOF, no round-trip/non-destruction
-guarantee, and NOTHING covering the workflow-app schema (an old app schema was
-flatly rejected, never migrated). v0.1.36 adds a declared registry, per-edge
-compatibility proofs, fail-closed reachability, and a round-trip prover — reusing
-the existing `migrateRunState` transform (no logic forked).
+CW v0.1.36 makes schema migration a named, declared part of the system. Before
+v0.1.36 migration was done one step at a time and only on run-state:
+`RUN_STATE_MIGRATIONS` was an inline step array walked by `migrateRunState`,
+with no declared `up`-transform registry, no kept compatibility PROOF, no
+round-trip/non-destruction guarantee, and NOTHING covering the workflow-app
+schema (an old app schema was turned away flatly, never migrated). v0.1.36 adds
+a declared registry, per-edge compatibility proofs, fail-closed reachability,
+and a round-trip prover — using again the existing `migrateRunState` transform
+(no logic forked).
 
 ## The declared registry
 
-`migration list` is the single declared source for "what versions exist and how
-to advance them": one `MigrationContract` per schema (`run-state`,
+`migration list` is the one declared source for "what versions exist and how
+to move them forward": one `MigrationContract` per schema (`run-state`,
 `workflow-app`), each with `currentVersion`, `minVersion`, and an array of
 `MigrationEdge { from, to, description, proof }`. The run-state edges ARE
-`RUN_STATE_MIGRATIONS` (the transform is not duplicated). Each edge carries a
-mechanically-checkable `MigrationCompatibilityProof` — the invariant it preserves
-(`addsDefaulted`, `dropsNothing`), as data, not prose.
+`RUN_STATE_MIGRATIONS` (the transform is not copied). Each edge carries a
+machine-checkable `MigrationCompatibilityProof` — the invariant it keeps
+(`addsDefaulted`, `dropsNothing`), as data, not as words.
 
 ```text
 migration list [--json]
@@ -25,20 +26,21 @@ migration list [--json]
 
 ## Fail closed on reachability
 
-Before transforming, the chain `detected -> current` is resolved. If a contract's
-detected version is below `minVersion`, above `currentVersion`, or has no chained
-path, the verdict is `unsupported` with a named reason and NO write — never a
-best-effort partial migration. (An older workflow-app, for which no edge exists
-yet, fails closed with a precise reason instead of being silently accepted.)
+Before transforming, the chain `detected -> current` is worked out. If a
+contract's detected version is below `minVersion`, above `currentVersion`, or
+has no chained path, the verdict is `unsupported` with a named reason and NO
+write — never a part-way migration that does its best. (An older workflow-app,
+for which no edge exists yet, fails closed with an exact reason in place of
+being taken in quietly.)
 
 ```text
 migration check <target> [--contract run-state|workflow-app] [--json]
 ```
 
 `<target>` is a run id (resolves to `.cw/runs/<id>/state.json`) or a path to a
-`state.json` / app manifest. The verdict reports `status`
+`state.json` / app manifest. The verdict gives the `status`
 (`current|migrated|normalized|unsupported`), the detected/current versions, the
-resolved `chain`, the change count, and any errors.
+resolved `chain`, the count of changes, and any errors.
 
 ## Round-trip / non-destruction proof
 
@@ -46,33 +48,34 @@ resolved `chain`, the change count, and any errors.
 migration prove <target> [--contract run-state|workflow-app] [--json]
 ```
 
-`migration prove` runs the chain and PROVES four properties, emitting a
+`migration prove` runs the chain and PROVES four properties, putting out a
 deterministic, sha256-fingerprinted `MigrationProof`:
 
 - **validatesAtCurrent** — the result validates at `currentVersion`.
-- **appendOnly** — every source record/key survives into the output (recursive);
-  nothing is destroyed.
-- **idempotent** — re-running migration on the output yields no further change.
-- **sourceImmutable** — `sourceHash == resultHash`-of-source: the original
+- **appendOnly** — every source record/key lives on into the output (recursive);
+  nothing is lost.
+- **idempotent** — running migration again on the output gives no further change.
+- **sourceImmutable** — `sourceHash == resultHash`-of-source: the first
   snapshot is byte-unchanged (`migrateRunState` clones; the source `state.json` is
-  never mutated).
+  never changed).
 
-`pass` is the conjunction. An `unsupported` verdict never transforms and never
-claims a positive proof.
+`pass` is true when all of these are true. An `unsupported` verdict never
+transforms and never claims a good proof.
 
 ## Append-only proof storage
 
-`migration prove` persists the `MigrationProof` beside the target under
-`migration/<fingerprint>.json` — a NEW file, never overwriting `state.json` or the
-source manifest. Re-deriving from disk reproduces the same fingerprint.
+`migration prove` keeps the `MigrationProof` next to the target under
+`migration/<fingerprint>.json` — a NEW file, never writing over `state.json` or
+the source manifest. Working it out again from disk gives back the same
+fingerprint.
 
 ## Surfaces & Compatibility
 
 `migration.list`/`check`/`prove` are declared `surface: "both"`, so
-`cw migration <verb> --json` and the `cw_migration_*` MCP tools render one core
-(`src/contract-migration.ts`). Additive: the run-state and workflow-app schema
-versions and `migrateRunState` are unchanged; the registry declares and proves
-over the existing transform. Pre-0.1.36 runs and apps load unchanged.
+`cw migration <verb> --json` and the `cw_migration_*` MCP tools draw from one
+core (`src/contract-migration.ts`). It only adds: the run-state and workflow-app
+schema versions and `migrateRunState` are unchanged; the registry declares and
+proves over the existing transform. Pre-0.1.36 runs and apps load unchanged.
 
 ## See Also
 
@@ -81,7 +84,7 @@ cli-mcp-parity(7)
 
 ## Control-Plane Scheduling (v0.1.37)
 
-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).
+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) for more.
 
 ## Agent Delegation Drive (v0.1.38)
 
@@ -101,19 +104,19 @@ 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 agent shape that makes sense (alt keys + prose), CW works out 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)
 
-Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+Hard gate stopping 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 validate the committed blob (`git show HEAD:<path>`) in place of the changeable working tree — getting rid of false-red/false-green from working-tree writes 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 way in to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
-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).
+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) on top.
 0.1.51
 
 0.1.76
@@ -126,6 +129,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 the contract-migration subsystem in v0.1.81._
+_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/control-plane-scheduling.7.md

@@ -2,24 +2,24 @@
 
 CW v0.1.37 adds Control-Plane Scheduling: a scheduling-policy layer over the
 v0.1.28 Run Registry queue. Before v0.1.37 the queue had ORDER (priority,
-`enqueuedAt`) but no policy — nothing limited how many runs were in flight, nothing
-retried a transient failure with backoff, and nothing bounded retries
-(`queue drain` would re-hand the same failing entry forever). v0.1.37 layers
-policy-as-data over the existing queue (no queue file duplicated): priority +
-readiness selection, a hard concurrency ceiling, leases, retry with computed
-backoff, and a fail-closed park state. The verbs use a distinct `sched` namespace,
-separate from the unrelated wall-clock `schedule` (loop/cron) scheduler.
-
-The core (`src/scheduling.ts`) is pure and deterministic — every function takes an
-injected `now`; "CW records readiness/order/leases, the host still executes the
+`enqueuedAt`) but no policy — nothing kept down how many runs were in flight, nothing
+tried again after a short-lived failure with backoff, and nothing put a limit on retries
+(`queue drain` would hand out the same failing entry again and again, for ever). v0.1.37 puts
+policy-as-data over the queue that is already there (no queue file is copied): priority +
+readiness selection, a hard concurrency ceiling, leases, retry with worked-out
+backoff, and a fail-closed park state. The verbs use their own `sched` namespace,
+apart from the unrelated wall-clock `schedule` (loop/cron) scheduler.
+
+The core (`src/scheduling.ts`) is pure and deterministic — every function is given an
+injected `now`; "CW writes down readiness/order/leases, the host still runs the
 workers."
 
 ## Policy as data
 
 `SchedulingPolicy` is a plain, diffable file under `$CW_HOME/registry/
-scheduling-policy.json`, defaulting to conservative fail-closed values when
-absent: `maxConcurrent 1`, `maxAttempts 3`, `leaseTtlMs 300000`, backoff
-`baseMs 1000 * factor 2 ^ (attempts-1)` capped at `60000` (no jitter).
+scheduling-policy.json`. When it is not there, it takes safe fail-closed values:
+`maxConcurrent 1`, `maxAttempts 3`, `leaseTtlMs 300000`, backoff
+`baseMs 1000 * factor 2 ^ (attempts-1)` with a top of `60000` (no jitter).
 
 ```text
 sched policy show [--json]
@@ -34,36 +34,36 @@ ready --lease--> leased --complete--> drained
    |__reset________/
 ```
 
-- **`sched plan`** — READ-ONLY: the would-be lease plan for the current
-  queue+policy+now, deterministic and replayable, without mutating. Payload-
+- **`sched plan`** — READ-ONLY: the lease plan that would be used for the current
+  queue+policy+now, deterministic and able to be run again, with no changes made. Payload-
   identical across CLI and MCP.
-- **`sched lease`** — claim eligible entries (priority order via `compareQueue`,
-  skipping anything not yet eligible / parked / leased) as `leased` with a
+- **`sched lease`** — take eligible entries (priority order via `compareQueue`,
+  jumping over anything not yet eligible / parked / leased) as `leased` with a
   `leaseId` and `leaseExpiresAt`. The **concurrency ceiling is a hard limit** —
-  leasing stops at `maxConcurrent`; over-limit entries stay `ready`.
-- **`sched complete <leaseId>`** — terminal success (`drained`).
-- **`sched release <leaseId> [--failed]`** — failed releases count an attempt
-  (retry/backoff or park); a clean release returns the entry to `ready`.
-- **`sched reclaim`** — an EXPIRED lease (the host died) is reclaimable and counts
-  one failed attempt — recorded, not silently reset.
+  leasing stops at `maxConcurrent`; entries over the limit stay `ready`.
+- **`sched complete <leaseId>`** — end success (`drained`).
+- **`sched release <leaseId> [--failed]`** — failed releases count as an attempt
+  (retry/backoff or park); a clean release sends the entry back to `ready`.
+- **`sched reclaim`** — an EXPIRED lease (the host died) can be reclaimed and counts
+  as one failed attempt — written down, not quietly reset.
 - **`sched reset <id>`** — operator recovery: a parked entry back to `ready`.
 
 ## Fail closed
 
-- **Concurrency is a hard ceiling** — never exceeded; `sched plan`/`lease` stop at
+- **Concurrency is a hard ceiling** — never gone past; `sched plan`/`lease` stop at
   `maxConcurrent` in-flight leases.
 - **Park past budget** — when `attempts >= maxAttempts` the entry becomes `parked`
-  with a `parkedReason` and is NEVER re-selected. `sched reset` is the only way
-  back. The queue can never re-hand a failing entry forever.
-- **Backoff is deterministic** — a pure curve, no randomness; a retried entry sets
-  `nextEligibleAt` and is skipped until then.
+  with a `parkedReason` and is NEVER picked again. `sched reset` is the only way
+  back. The queue can never hand out a failing entry for ever.
+- **Backoff is deterministic** — a pure curve, nothing random; a retried entry sets
+  `nextEligibleAt` and is jumped over until then.
 
 ## Compatibility
 
-Additive: `RunQueueEntry` gains optional `attempts`/`leaseId`/`leaseExpiresAt`/
+Additive: `RunQueueEntry` gets the optional `attempts`/`leaseId`/`leaseExpiresAt`/
 `nextEligibleAt`/`parkedReason` and two statuses (`leased`/`parked`); a pre-0.1.37
-`queue.json` loads unchanged (no scheduling fields = a plain ordered queue). The
-existing `queue add|list|drain|show` verbs are unchanged. No new database, no
+`queue.json` loads with no change (no scheduling fields = a plain ordered queue). The
+`queue add|list|drain|show` verbs that are already there do not change. No new database, no
 daemon-owned state.
 
 ## See Also
@@ -72,35 +72,35 @@ run-registry-control-plane(7), cli-mcp-parity(7), release-and-migration(7)
 
 ## Agent Delegation Drive (v0.1.38)
 
-spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+start an outside agent process for each worker, take in result.md + attestation, and drive plan->dispatch->fulfill->accept->commit by itself
 
 ## 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: shut the audit skeleton, free the bulk that can be built again, give proof of it
 
 ## Durable State & Locking (v0.1.40)
 
-atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+atomic temp->rename writes + fsync-durability for the authoritative stores; portable stale-stealing file lock that puts the cross-process read-modify-write stores in order, one at a time
 
 ## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
 
-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)
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); the orchestrator god-object is broken up into per-domain operation modules (pure loadRun->delegate router)
 
 ## 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 in findings/evidence from any reasonable agent shape (alt keys + prose), CW works out grounded evidence by itself, give a warning on empty capture — this shuts 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 stops 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>`) in place of the mutable working tree — taking away false-red/false-green that came 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)
 
-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).
+Migration DAG with edges that can go both ways (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).
 0.1.51
 
 0.1.76
@@ -113,6 +113,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, Map and Assess results that can be used again, wrapper metrics that can be measured, 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 the control-plane scheduling surface in v0.1.81._
+_No change in behavior in v0.1.82 (schedule/run ids are now deterministic-but-unique through a monotonic counter + pid in place of Math.random; ids stay collision-free)._
+
+## 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/coordinator-blackboard.7.md

@@ -7,15 +7,15 @@ CW v0.1.25 adds `blackboard summarize <run-id>` (MCP: `cw_blackboard_summarize`)
 a deterministic blackboard digest with topic rollups, thread summaries,
 unresolved questions, conflicts, decisions, artifacts, adopted and missing
 evidence, policy violations, judge rationale, recent changes, and high-signal
-records. The digest is a derived userland index: it preserves links back to
-source messages, contexts, artifacts, snapshots, coordinator decisions, and
-audit events, and never deletes raw records. See
+records. The digest is a worked-out index made from other records: it keeps
+links back to source messages, contexts, artifacts, snapshots, coordinator
+decisions, and audit events, and never deletes raw records. See
 [state-explosion-management.7.md](state-explosion-management.7.md).
 
-This release defines stable primitives for shared context, messages, artifact
-indexing, snapshots, and coordinator decisions. It does not implement debate,
-judge, map-reduce, swarm, committee, or synthesis topologies yet. Those
-topologies should consume this substrate later.
+This release gives fixed building blocks for shared context, messages, artifact
+indexing, snapshots, and coordinator decisions. It does not yet build debate,
+judge, map-reduce, swarm, committee, or synthesis topologies. Those topologies
+are meant to use this base later.
 
 ## State Model
 
@@ -44,14 +44,14 @@ Runtime objects are:
 - `BlackboardSnapshot`
 - `CoordinatorDecision`
 
-Every record carries schema version, stable id, timestamps, author/source,
+Every record has schema version, stable id, timestamps, author/source,
 scope, status, parent references, tags, metadata, and links back to workflow,
 multi-agent, worker, task, candidate, verifier, commit, audit, and evidence
-records where applicable.
+records when they apply.
 
 ## Storage Layout
 
-CW mirrors blackboard state to durable local files:
+CW copies blackboard state to local files that last:
 
 ```text
 .cw/runs/<run-id>/blackboard/
@@ -64,13 +64,13 @@ CW mirrors blackboard state to durable local files:
   decisions/<decision-id>.json
 ```
 
-`messages.jsonl` is append-friendly. `index.json` is regenerated
-deterministically from run state. CW does not store secrets or raw environment
+`messages.jsonl` is good for adding to the end. `index.json` is made again the
+same way from run state each time. CW does not keep secrets or raw environment
 values in blackboard metadata.
 
 ## Context Semantics
 
-Shared context supports:
+Shared context takes these kinds:
 
 - `fact`
 - `constraint`
@@ -78,12 +78,12 @@ Shared context supports:
 - `question`
 - `decision`
 
-Context updates do not silently overwrite older records. If a new update has
+Context updates do not quietly write over older records. If a new update has
 the same topic, kind, and key as an active context record but a different value,
 CW marks the records `conflicting` and records a `CoordinatorDecision`.
 
-Use `--supersedes <context-id>` to intentionally replace older context. The
-older record is marked `superseded`, and the new record links to it.
+Use `--supersedes <context-id>` when you mean to take the place of older context.
+The older record is marked `superseded`, and the new record links to it.
 
 ## Artifact Index
 
@@ -91,15 +91,15 @@ older record is marked `superseded`, and the new record links to it.
 locators, generated artifacts, reports, commit snapshots, and external paths.
 
 Artifact refs include kind, path or locator, owner, source, provenance,
-evidence refs, checksum when the path is a readable file, and trust audit links.
-Existing `StateArtifact` records remain valid; blackboard refs bridge them into
-shared coordination state instead of replacing them.
+evidence refs, checksum when the path is a file that can be read, and trust audit
+links. Existing `StateArtifact` records stay good; blackboard refs join them into
+shared coordination state and do not take their place.
 
 ## Multi-Agent Integration
 
 `MultiAgentRun`, groups, roles, memberships, fanout, and fanin can link to a
 blackboard id and topic ids. Worker manifests for blackboard-enabled work
-include:
+have:
 
 ```json
 {
@@ -112,8 +112,8 @@ include:
 }
 ```
 
-Accepted worker output can publish result summaries and artifacts into the
-blackboard. Fanin can require indexed blackboard evidence and fails closed when
+Accepted worker output can put result summaries and artifacts into the
+blackboard. Fanin can ask for indexed blackboard evidence and fails closed when
 required role memberships have no blackboard message or artifact refs.
 
 ## CLI
@@ -133,12 +133,12 @@ node scripts/cw.js coordinator summary <run-id>
 node scripts/cw.js coordinator decision <run-id> --kind conflict-resolution --outcome accepted --reason "..."
 ```
 
-The CLI is JSON-friendly by default for focused blackboard and coordinator
+The CLI gives JSON by default for focused blackboard and coordinator
 commands.
 
 ## MCP Parity
 
-MCP exposes matching tools:
+MCP gives the same tools:
 
 ```text
 cw_blackboard_summary
@@ -155,14 +155,14 @@ cw_coordinator_summary
 cw_coordinator_decision
 ```
 
-There is no intentional CLI-only behavior for core blackboard operations.
+There is no CLI-only behavior on purpose for core blackboard operations.
 
 ## Operator UX
 
-`status`, `report --show`, and graph output include a Blackboard / Coordinator
+`status`, `report --show`, and graph output have a Blackboard / Coordinator
 panel. It shows topics, message counts, open questions, conflicts, missing
-evidence, artifact counts, snapshot paths, ready-for-fanin state, and next
-recommended action.
+evidence, artifact counts, snapshot paths, ready-for-fanin state, and the next
+suggested action.
 
 Use:
 
@@ -177,7 +177,7 @@ node scripts/cw.js audit provenance <run-id>
 ## Migration
 
 Older v0.1.17 and earlier runs normalize with empty blackboard state and a
-`.cw/runs/<run-id>/blackboard/` path. Unknown user data is preserved.
+`.cw/runs/<run-id>/blackboard/` path. User data that is not known is kept.
 
-Newer unsupported run-state schemas still fail closed.
+Newer run-state schemas that are not supported still fail closed.
 0.1.51

package/docs/dogfood-one-real-repo.7.md

@@ -1,9 +1,9 @@
 # Dogfood One Real Repo
 
-CW v0.1.16 proves the release workflow against the real Cool Workflow
-repository. The proof uses the canonical `release-cut` app, records isolated
-worker outputs, scores a release candidate, selects it only with verifier
-evidence, creates a verifier-gated CW state commit, and renders trust audit
+CW v0.1.16 tests the release workflow against the real Cool Workflow
+repository. The test uses the canonical `release-cut` app, keeps a record of
+separate worker outputs, scores a release candidate, picks it only with verifier
+evidence, makes a verifier-gated CW state commit, and shows trust audit
 provenance.
 
 ## Dry-Run Command
@@ -15,7 +15,7 @@ cd plugins/cool-workflow
 npm run dogfood:release
 ```
 
-The command targets the repository two directories above the package, uses
+The command points at the repository two directories above the package, uses
 `release-cut`, sets `version=0.1.18`, `previousVersion=0.1.17`, the current git
 branch, and `dryRun=true`. It writes a machine-readable summary to:
 
@@ -23,13 +23,13 @@ branch, and `dryRun=true`. It writes a machine-readable summary to:
 .cw/runs/<run-id>/dogfood-summary.json
 ```
 
-The summary includes the run id, report path, audit summary path, provenance
+The summary has the run id, report path, audit summary path, provenance
 counts, worker ids, candidate id, score id, selection id, commit or checkpoint
 id, command log paths, and the release verdict.
 
 ## Real Evidence
 
-The full dry-run collects real repository evidence from:
+The full dry-run gets real repository evidence from:
 
 ```bash
 git status --short --branch
@@ -44,8 +44,8 @@ npm run release:check
 npm pack --dry-run --json
 ```
 
-Each command log is written under the worker `logs/` directory and cited in the
-worker `cw:result` evidence array. The release verdict worker carries the full
+Each command log is written under the worker `logs/` directory and named in the
+worker `cw:result` evidence array. The release verdict worker takes the full
 set of command locators into the release candidate, score, selection, and
 commit/checkpoint provenance.
 
@@ -72,14 +72,14 @@ node scripts/cw.js audit provenance <run-id> --candidate dogfood-release-0.1.18
 node scripts/cw.js audit provenance <run-id> --commit <commit-id>
 ```
 
-The report answers why the candidate is trusted by showing sandbox profiles,
-host attestations, evidence provenance, candidate scoring, acceptance rationale,
+The report tells why the candidate is trusted by showing sandbox profiles,
+host attestations, evidence provenance, candidate scoring, acceptance reasons,
 and the verifier-gated commit.
 
-The dogfood command remains a local release-engineering script rather than a new
-MCP tool because it composes existing first-class CW capabilities: `release-cut`
+The dogfood command stays a local release-engineering script and not a new
+MCP tool because it is built from existing first-class CW capabilities: `release-cut`
 planning, dispatch, worker manifests/output, candidate scoring/selection,
-commits, reports, and audit/provenance. MCP parity is preserved for the
+commits, reports, and audit/provenance. MCP parity is kept for the
 inspectable state through the existing worker, candidate, commit, operator
 report, and audit tools.
 
@@ -91,14 +91,14 @@ report, and audit tools.
 node test/dogfood-release-smoke.js
 ```
 
-The smoke test executes `scripts/dogfood-release.js --smoke --json`. It still
+The smoke test runs `scripts/dogfood-release.js --smoke --json`. It still
 uses the real repository, `release-cut`, worker manifests, trust audit records,
 candidate scoring, selection, verifier-gated commit, and a report, but keeps the
-command set smaller to avoid recursive release checking.
+command set smaller so it does not do recursive release checking.
 
 ## Promote To Real Release Actions
 
-Dry-run mode never creates tags, pushes, publishes packages, or mutates a
+Dry-run mode never makes tags, pushes, puts out packages, or changes a
 marketplace. Real actions are separate maintainer commands after the dogfood
 run passes:
 
@@ -110,42 +110,42 @@ git tag v0.1.18
 git push origin main --tags
 ```
 
-Package publish and plugin marketplace updates should be separate visible
-steps. If future execute flags are used, they must be explicit, for example
-`--execute --tag --confirm-release-actions=0.1.18`. The script refuses tag,
-push, or publish flags in dry-run mode and refuses execute mode without the
+Package publish and plugin marketplace updates should be separate, clear
+steps. If execute flags are used later, they must be stated openly, for example
+`--execute --tag --confirm-release-actions=0.1.18`. The script says no to tag,
+push, or publish flags in dry-run mode and says no to execute mode without the
 target-version confirmation.
 
 ## Safety Gates
 
-The dogfood command holds the candidate and writes an explicit checkpoint if
-any evidence command fails, version sync is incomplete, release docs are
-missing, audit records are unavailable, or verifier evidence is absent. A
-selected candidate requires score evidence and a verified verifier node; a
-verifier-gated commit requires the selected candidate, score, evidence, sandbox
-profile, worker, and acceptance rationale.
+The dogfood command holds the candidate and writes a clear checkpoint if
+any evidence command fails, version sync is not complete, release docs are
+missing, audit records are not there, or verifier evidence is not present. A
+selected candidate needs score evidence and a verified verifier node; a
+verifier-gated commit needs the selected candidate, score, evidence, sandbox
+profile, worker, and acceptance reasons.
 
-This is intentionally boring release engineering: local-first, inspectable,
+This is release engineering made dull on purpose: local-first, inspectable,
 scriptable, and fail-closed.
 
 ## Architecture-Review Agent-Delegation Dogfood (v0.1.38)
 
 `scripts/dogfood-architecture-review.js` dogfoods the v0.1.38 Agent Delegation
-Drive: the `architecture-review` app driven end-to-end by the `agent` backend,
-with zero hand-written `result.md`.
+Drive: the `architecture-review` app driven from end to end by the `agent` backend,
+with no hand-written `result.md` at all.
 
-It splits into two halves, exactly like the release dogfood above:
+It is cut into two halves, just like the release dogfood above:
 
 - **`--smoke` (CI-verifiable).** A hermetic STUB agent (no live binary, no second
   repo, no network, no model SDK) drives the real app to a committed audited
-  report. `node scripts/dogfood-architecture-review.js --smoke --json` emits
+  report. `node scripts/dogfood-architecture-review.js --smoke --json` gives back
   `{ ok: true, mode: "smoke" }` with a `reportPath` and `auditSummaryPath` that
-  exist, the Verdict node accepted, and `audit.byKind["worker.agent-delegation"]
-  >= 1`. This is asserted under `npm test` (`test/dogfood-release-smoke.js`).
+  are there, the Verdict node accepted, and `audit.byKind["worker.agent-delegation"]
+  >= 1`. This is checked under `npm test` (`test/dogfood-release-smoke.js`).
 
-- **Live full-drive (MAINTAINER-RUN, OUT OF CI).** With a REAL configured agent
+- **Live full-drive (MAINTAINER-RUN, OUT OF CI).** With a REAL set-up agent
   (`CW_AGENT_COMMAND`, e.g. `claude -p {{input}}` / `codex exec`, or
-  `--agent-command`) against ONE real external repository:
+  `--agent-command`) against ONE real outside repository:
 
   ```bash
   CW_AGENT_COMMAND="claude -p {{input}}" \
@@ -154,15 +154,15 @@ It splits into two halves, exactly like the release dogfood above:
   ```
 
   This drives plan → dispatch → agent-fulfill → accept/verify → commit for every
-  worker the planner emits, produces the committed audited risk report, and writes
-  a `docs/dogfood/architecture-review-<repo>.md` provenance note recording the repo
-  name and the agent-REPORTED model id. It depends on a live external agent binary
+  worker the planner emits, makes the committed audited risk report, and writes
+  a `docs/dogfood/architecture-review-<repo>.md` provenance note that keeps the repo
+  name and the agent-REPORTED model id. It needs a live outside agent binary
   and a second repository, which CI cannot have (CI is node/npm/git-only and
-  hermetic), so it is **explicitly OUT of CI** — a maintainer bar run out-of-band,
-  exactly like the "Promote To Real Release Actions" above. The CI/release gate is
-  strictly the stub `--smoke` path.
+  hermetic), so it is **explicitly OUT of CI** — a maintainer step run out-of-band,
+  just like the "Promote To Real Release Actions" above. The CI/release gate is
+  only the stub `--smoke` path.
 
-  The model runs in the external agent's process, never inside CW: this script
-  spawns the agent and records its attested output; it imports no model SDK and
+  The model runs in the outside agent's process, never inside CW: this script
+  starts the agent and records its attested output; it brings in no model SDK and
   holds no API key.
 0.1.51