cool-workflow 0.1.82 → 0.1.84

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

package/docs/durable-state-and-locking.7.md

@@ -1,81 +1,81 @@
 # Durable State & Locking
 
-CW v0.1.40 closes the durability seams its own architecture self-audit found:
+CW v0.1.40 fixes the durability gaps its own architecture self-audit found:
 every authoritative write is now **atomic**, the audit-essential ones are
 **fsync-durable**, and the cross-process read-modify-write stores are
 **lock-serialized**. This is the hardening half of Run Retention & Provable
 Reclamation (v0.1.39) — the reclamation transaction was already write-ahead, but
-the kernel persistence primitive underneath it (`state.ts:writeJson`) was a
-non-atomic in-place `fs.writeFileSync`, the prior verdict's #1 P1. That is now
+the kernel persistence primitive under it (`state.ts:writeJson`) was a
+non-atomic in-place `fs.writeFileSync`, the #1 P1 from the last verdict. That is now
 fixed for the whole control plane, not just the tombstone.
 
 ## Atomic writes — order is the safety property
 
 `writeJson(file, value, { durable? })` writes to a unique temp file and then
 `rename(2)`s it over the target. Because rename is atomic on POSIX, a crash,
-`SIGKILL`, or `ENOSPC` mid-write can never leave a truncated `state.json` that
+`SIGKILL`, or `ENOSPC` part-way through a write can never leave a cut-short `state.json` that
 throws `Invalid JSON` on reload — a reader always sees **EITHER the old bytes OR
-the new bytes**, never a torn file. A failed rename cleans up its temp file, so no
+the new bytes**, never a torn file. A failed rename clears away its temp file, so no
 half-written artifact is ever left behind.
 
-With `{ durable: true }` the file is additionally `fsync`'d (and its directory
-best-effort `fsync`'d) before the write is considered complete, so the bytes
-survive power loss. Durability is reserved for **authoritative** state — `state.json`
+With `{ durable: true }` the file is also `fsync`'d (and its directory
+`fsync`'d as best it can) before the write counts as done, so the bytes
+live through power loss. Durability is kept for **authoritative** state — `state.json`
 (`saveCheckpoint`), the registry overlays (`archive.json`, `provenance.json`, the
 home queue, `repos.json`), the scheduler store, and the reclamation `reclaimed.json`
 — while high-frequency, rebuildable derived writes (node bodies, worker manifests,
-the registry index) stay atomic-but-not-fsync'd so the cheap torn-write fix applies
+the registry index) stay atomic-but-not-fsync'd so the cheap torn-write fix is used
 everywhere without the fsync cost on the hot path.
 
 ## Locking — serialize the cross-process read-modify-write
 
 The home queue (`queueAdd`/`queueDrain`), the archive overlay, the repos registry,
-and the per-run reclamation chain are read-modify-write stores mutated by more than
+and the per-run reclamation chain are read-modify-write stores changed by more than
 one process (the long-running scheduler daemon and the CLI both touch the queue).
-`withFileLock(targetPath, fn)` runs `fn` while holding a portable advisory lock:
+`withFileLock(targetPath, fn)` runs `fn` while it holds a portable advisory lock:
 
-- **Portable** — an `O_EXCL` (`wx`) lockfile beside the target; no native `flock(2)`,
-  so it works identically under CI (node/npm/git only).
-- **Stale-stealing** — a lock older than the steal window (30 s) is reclaimed, so a
-  crashed holder can never wedge a store forever.
+- **Portable** — an `O_EXCL` (`wx`) lockfile next to the target; no native `flock(2)`,
+  so it works the same way under CI (node/npm/git only).
+- **Stale-stealing** — a lock older than the steal window (30 s) is taken back, so a
+  crashed holder can never block a store for good.
 - **Always released** — the lock is removed in a `finally`, even if `fn` throws.
 
 This makes the scheduling kernel's concurrency ceiling hold **across processes**,
-not merely within one: a newly-added queue task can no longer vanish under a
+not just within one: a newly-added queue task can no longer go missing under a
 concurrent drain, and two reclaimers can no longer lose a tombstone
 (freed-without-proof).
 
 ## Reclamation durability (the write-ahead seam, v0.1.40)
 
 The v0.1.39 reclamation transaction proved the *tombstone* crash-safe, but the
-result-node re-point that scratch reclamation depends on lived outside that
-boundary. It is now inside it. `runReclamation` runs, in order:
+result-node re-point that scratch reclamation needs lived outside that
+boundary. It is now inside it. `runReclamation` runs, in this order:
 
 1. extract + seal skeleton — and **refuse** (`skeleton-incomplete`) not only on a
-   missing key but if extraction dropped audit **content** the run actually has
+   missing key but if extraction dropped audit **content** the run truly has
    (a run with commits/evidence must seal them);
 2. under the per-run lock: build the tombstone (reads `prevTombstoneHash`) and
    commit it durably — atomic so the chain read-modify-write can never lose a link;
-3. `prepareFree()` — re-point surviving nodes off the scratch, **durably persist**
-   `state.json`, and **prove** no surviving node references a freed path (and each
+3. `prepareFree()` — re-point living nodes off the scratch, **durably persist**
+   `state.json`, and **prove** no living node points to a freed path (and each
    re-pointed node's `loadNodeSnapshot` stays `valid`), failing closed
-   (`repoint-incomplete`) otherwise;
+   (`repoint-incomplete`) if not;
 4. only then free the bulk bytes.
 
 A crash at any point now leaves EITHER the full run OR a complete tombstone with a
-re-pointed, durably-persisted `state.json` — never a node referencing a freed path,
-and never a tombstone whose capability claim diverges from reality.
+re-pointed, durably-persisted `state.json` — never a node that points to a freed path,
+and never a tombstone whose capability claim is at odds with reality.
 
 ## Compatibility
 
-Additive and invisible to correct single-writer use. No schema change; pre-v0.1.40
+Added on top and unseen by correct single-writer use. No schema change; pre-v0.1.40
 runs and stores load unchanged. Atomicity and locking change only HOW the same
 bytes are written, never WHAT — no audit, commit, or collaboration record is ever
 rewritten.
 
 ## See Also
 
-- `docs/run-retention-reclamation.7.md` — the v0.1.39 reclamation transaction this hardens.
+- `docs/run-retention-reclamation.7.md` — the v0.1.39 reclamation transaction this makes harder.
 - `docs/run-registry-control-plane.7.md` — the registry overlays + home queue now locked.
 - `docs/control-plane-scheduling.7.md` — the concurrency ceiling now held across processes.
 
@@ -85,7 +85,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 sensible agent shape (alt keys + prose), CW works out grounded evidence itself, warn on empty capture — fixes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
@@ -93,7 +93,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 changeable working tree — getting rid of 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)
 
@@ -110,9 +110,17 @@ 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.
 
 ## Deterministic Tombstone Hash (v0.1.81)
 
-The reclamation tombstone's freed-manifest is now path-sorted before it feeds `tombstoneHash`, so the same freed set always yields the same hash regardless of filesystem enumeration order. This removes a non-determinism from the write-ahead chain (v0.1.39/v0.1.40), keeping the per-run tombstone hash-chain replayable and stable across hosts. Atomicity, locking, and the durable re-point seam are unchanged. v0.1.81 also adds import-time refusal (`CW_REQUIRE_ARCHIVE_INTEGRITY=1`) and restore-time trust-audit re-proving — see run-registry-control-plane(7).
+The reclamation tombstone's freed-manifest is now path-sorted before it feeds `tombstoneHash`, so the same freed set always gives the same hash no matter the filesystem enumeration order. This takes a non-determinism out of the write-ahead chain (v0.1.39/v0.1.40), keeping the per-run tombstone hash-chain replayable and steady across hosts. Atomicity, locking, and the durable re-point seam are unchanged. v0.1.81 also adds import-time refusal (`CW_REQUIRE_ARCHIVE_INTEGRITY=1`) and restore-time trust-audit re-proving — see run-registry-control-plane(7).
 _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.
+
+## Privacy Release (v0.1.84)
+
+No other change to this page in v0.1.84.

package/docs/end-to-end-golden-path.7.md

@@ -1,8 +1,8 @@
 # End-to-End Golden Path
 
-Cool Workflow v0.1.10 added a deterministic golden path that proves the base
-system is connected from workflow app planning through verifier-gated commit and
-report generation.
+Cool Workflow v0.1.10 added a deterministic golden path. It proves the base
+system is joined up, from workflow app planning, through verifier-gated commit,
+to report generation.
 
 Run it from the plugin root:
 
@@ -14,13 +14,13 @@ npm run golden-path
 The command uses only Node.js standard library APIs and the public CW CLI. It
 does not use the network, sleeps, hidden daemon state, or real subagents.
 
-v0.1.13 adds `test/mcp-app-surface-smoke.js`, a sibling deterministic proof
+v0.1.13 adds `test/mcp-app-surface-smoke.js`. This is a near deterministic proof
 that drives the same app/worker/candidate/commit/operator chain over MCP stdio
-JSON-RPC instead of direct CLI commands.
+JSON-RPC, in place of direct CLI commands.
 
 ## What It Proves
 
-The runner exercises this chain:
+The runner works through this chain:
 
 ```text
 workflow app -> plan -> dispatch -> isolated worker -> candidate scoring
@@ -28,12 +28,12 @@ workflow app -> plan -> dispatch -> isolated worker -> candidate scoring
 ```
 
 It uses the first-class `end-to-end-golden-path` app in
-`apps/end-to-end-golden-path/`. The app has one phase and one evidence-required
-worker task with the `readonly` sandbox profile.
+`apps/end-to-end-golden-path/`. The app has one phase and one worker task that
+needs evidence, with the `readonly` sandbox profile.
 
 ## CLI Surface
 
-The runner performs the same public commands an operator would use:
+The runner runs the same public commands that an operator would use:
 
 ```bash
 node scripts/cw.js app validate end-to-end-golden-path
@@ -58,13 +58,13 @@ node scripts/cw.js graph <run-id>
 node scripts/cw.js report <run-id> --show
 ```
 
-After dispatch, the script reads the generated worker manifest and writes a
-valid Markdown result to the worker's declared `result.md`. The result contains
+After dispatch, the script reads the worker manifest it made, and writes a
+good Markdown result to the worker's named `result.md`. The result has in it
 a `cw:result` JSON fence with file:line evidence.
 
 ## Files Written
 
-The runner creates a temporary workspace under the OS temp directory:
+The runner makes a temporary workspace under the OS temp directory:
 
 ```text
 <tmp>/
@@ -88,30 +88,30 @@ The runner creates a temporary workspace under the OS temp directory:
     commits/
 ```
 
-By default the workspace is left on disk so the report and state can be
-inspected. Tests run the same script with `--cleanup`.
+By default the workspace is kept on disk, so you can look at the report and
+state. Tests run the same script with `--cleanup`.
 
 ## Invariants
 
-The golden path asserts durable state, not just exit codes:
+The golden path checks durable state, not just exit codes:
 
-- run state includes workflow app id and version metadata
-- MCP hosts can reproduce the flow with `cw_app_run`, `cw_dispatch`,
+- run state has the workflow app id and version metadata in it
+- MCP hosts can do the flow again with `cw_app_run`, `cw_dispatch`,
   `cw_worker_manifest`, `cw_worker_output`, `cw_candidate_score`,
   `cw_candidate_select`, `cw_commit`, and operator summary tools
-- dispatch records a worker id and `readonly` sandbox profile
-- the worker manifest includes resolved sandbox policy data
-- the worker reaches `verified`
-- result and verifier nodes exist
-- the verifier node carries evidence
-- `golden-candidate` reaches `verified` after selection
-- candidate score and ranking files exist
-- the final commit has `verifierGated: true` and `checkpoint: false`
-- the final commit references the selection, candidate, verifier node, and
+- dispatch keeps a record of a worker id and `readonly` sandbox profile
+- the worker manifest has the worked-out sandbox policy data in it
+- the worker gets to `verified`
+- result and verifier nodes are there
+- the verifier node holds evidence
+- `golden-candidate` gets to `verified` after selection
+- candidate score and ranking files are there
+- the last commit has `verifierGated: true` and `checkpoint: false`
+- the last commit points to the selection, candidate, verifier node, and
   evidence
-- the report mentions the workflow app, candidates, and verifier-gated commit
-- operator status, graph, report, and summary commands can inspect the run
-- no ErrorFeedback records are produced
+- the report names the workflow app, candidates, and verifier-gated commit
+- operator status, graph, report, and summary commands can look at the run
+- no ErrorFeedback records are made
 
 If this command fails, one of the base integration contracts is broken.
 0.1.51

package/docs/error-feedback.7.md

@@ -2,7 +2,7 @@
 
 ## NAME
 
-Error Feedback Loop - inspectable diagnostic and correction state for Cool Workflow
+Error Feedback Loop - diagnostic and correction state you can look into for Cool Workflow
 
 ## SYNOPSIS
 
@@ -27,14 +27,14 @@ const resolved = resolveFeedback(run, records[0].id, {
 ## DESCRIPTION
 
 The Error Feedback Loop is the small layer between structured failures and
-operator correction. It records failures as durable JSON, classifies them with
-plain identifiers, creates optional correction tasks, and resolves records only
-after verifier evidence is present.
+operator correction. It keeps failures as long-lasting JSON, gives them plain
+identifiers, makes optional correction tasks, and clears records only after
+verifier evidence is there.
 
-It does not repair code, retry stages, or own domain workflow behavior. Workflow
-apps and operators decide how corrections are applied.
+It does not fix code, do stages again, or own domain workflow behavior. Workflow
+apps and operators say how corrections are put to use.
 
-The loop follows:
+The loop goes like this:
 
 ```text
 error -> classify -> feedback record -> correction task -> verify -> checkpoint
@@ -43,7 +43,7 @@ error -> classify -> feedback record -> correction task -> verify -> checkpoint
 ## FEEDBACK MODEL
 
 Each feedback record is an `ErrorFeedbackRecord` with schema version `1`.
-Important fields are:
+The chief fields are:
 
 - `id`
 - `runId`
@@ -65,11 +65,11 @@ Important fields are:
 - `resolvedByNodeId`
 - `metadata`
 
-The runtime also keeps `run.feedback` in `state.json` for quick inspection.
+The runtime also keeps `run.feedback` in `state.json` for a quick look.
 
 ## FAILURE CLASSIFICATION
 
-Classifications are stable, plain strings:
+Classifications are fixed, plain strings:
 
 ```text
 contract-violation
@@ -83,21 +83,21 @@ runtime-error
 unknown
 ```
 
-Classification is conservative. The feedback loop does not duplicate
-`PipelineContract` validation logic; it classifies structured errors already
-produced by StateNode, PipelineRunner, verifier, or CLI surfaces.
+Classification is careful. The feedback loop does not copy the
+`PipelineContract` validation logic; it gives identifiers to structured errors
+already made by StateNode, PipelineRunner, verifier, or CLI surfaces.
 
 ## CORRECTION TASKS
 
 Correction tasks are normal task Markdown files under the run `tasks/`
-directory. They include the original error, affected node/stage/contract,
-evidence, expected verification command, and retry guidance.
+directory. They take in the first error, the touched node/stage/contract, the
+evidence, the looked-for verification command, and help on doing it again.
 
-Creating a correction task marks the feedback record as `tasked`. It does not
-apply code changes.
+Making a correction task marks the feedback record as `tasked`. It does not
+make code changes.
 
-Resolving feedback requires a node id whose status is `verified` or `committed`.
-Rejected corrections are preserved by setting status to `rejected`.
+To resolve feedback you need a node id whose status is `verified` or `committed`.
+Turned-down corrections are kept by setting status to `rejected`.
 
 ## FILES
 
@@ -111,7 +111,7 @@ Rejected corrections are preserved by setting status to `rejected`.
 
 ## EXAMPLES
 
-Collect failed node errors:
+Get together failed node errors:
 
 ```text
 node dist/cli.js feedback collect <run-id>
@@ -123,7 +123,7 @@ List feedback records:
 node dist/cli.js feedback list <run-id>
 ```
 
-Show one feedback record:
+Give one feedback record:
 
 ```text
 node dist/cli.js feedback show <run-id> <feedback-id>
@@ -135,19 +135,19 @@ Create a correction task:
 node dist/cli.js feedback task <run-id> <feedback-id> --verify "npm test"
 ```
 
-Resolve after a verified node:
+Clear it after a verified node:
 
 ```text
 node dist/cli.js feedback resolve <run-id> <feedback-id> --node <verified-node-id>
 ```
 
-All commands print stable JSON.
+All commands put out fixed JSON.
 
 ## COMPATIBILITY
 
-Error Feedback is introduced in CW v0.1.4. It adds optional `feedback` state and
-`feedbackDir` path metadata. Older runs remain readable; missing fields are
-initialized when the run is loaded.
+Error Feedback comes in with CW v0.1.4. It adds optional `feedback` state and
+`feedbackDir` path metadata. Older runs can still be read; missing fields are
+started up when the run is loaded.
 
-Existing workflow, node, contract, pipeline, and CLI behavior is preserved.
+The workflow, node, contract, pipeline, and CLI behavior you have now is kept.
 0.1.51