cool-workflow 0.1.81 → 0.1.83

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,8 +110,13 @@ 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.

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