cool-workflow 0.1.81 → 0.1.83

package/docs/release-and-migration.7.md

@@ -1,36 +1,36 @@
 # Release And Migration Discipline
 
-CW v0.1.14 made release checks and durable run-state compatibility explicit.
+CW v0.1.14 made release checks and durable run-state compatibility clear.
 
 ## Who Is Affected
 
 Maintainers cutting CW releases should use `npm run release:check` from
 `plugins/cool-workflow`. Operators loading old `.cw/runs/<run-id>/state.json`
-files can inspect compatibility with:
+files can check compatibility with:
 
 ```bash
 node scripts/cw.js state check <run-id>
 ```
 
 Use `--state /path/to/state.json` when checking a state file outside the
-current `.cw/runs` tree. Add `--write` only when you deliberately want to write
+current `.cw/runs` tree. Add `--write` only when you truly want to write
 the normalized/migrated state back to disk.
 
 ## State Policy
 
-The current durable run-state schema is `1`, defined by
+The current durable run-state schema is `1`, set by
 `CURRENT_RUN_STATE_SCHEMA_VERSION` in `src/version.ts`.
 
-Loading state follows this order:
+Loading state goes in this order:
 
 ```text
 read JSON -> detect schema -> migrate -> normalize -> validate -> report
 ```
 
-CW supports legacy run state with no `schemaVersion` as historical schema `0`
+CW supports old run state with no `schemaVersion` as past schema `0`
 and migrates it to schema `1`. Schema versions newer than the runtime fail
-closed. Invalid state objects fail closed. Unknown user data is preserved by
-copying and adding required fields instead of rebuilding state from scratch.
+closed. Bad state objects fail closed. Unknown user data is kept by
+copying and adding required fields, not by building state again from the start.
 
 ## Dry Run
 
@@ -38,7 +38,7 @@ copying and adding required fields instead of rebuilding state from scratch.
 
 - detected and current schema versions
 - compatibility status: `current`, `migrated`, `normalized`, or `unsupported`
-- whether writing would be required
+- whether writing would be needed
 - every field CW would add or normalize
 - warnings and errors
 
@@ -53,10 +53,10 @@ Fixture runs live in `test/fixtures/runs/` and cover:
 - Operator UX
 - v0.1.13 MCP/App Surface
 
-`npm run fixture-compat` copies each fixture into a temporary `.cw/runs` tree,
-runs migration, and proves `status`, `graph`, and `report` still operate. The
-fixture files are hashed before and after the test to prove they were not
-mutated.
+`npm run fixture-compat` copies each fixture into a short-term `.cw/runs` tree,
+runs migration, and shows `status`, `graph`, and `report` still work. The
+fixture files are hashed before and after the test to show they were not
+changed.
 
 ## Release Check
 
@@ -78,10 +78,10 @@ mutated.
 - `npm run version:sync`
 
 The command is dry-run and non-destructive. Tagging, pushing, and publishing
-remain manual release actions after the gate passes.
+stay manual release actions after the gate passes.
 
 For v0.1.15, the same gate also includes the Security / Trust Hardening smoke
-test so audit/provenance coverage remains part of release discipline.
+test so audit/provenance coverage stays part of release discipline.
 
 For v0.1.18, the gate includes Coordinator / Blackboard smoke coverage and
 fixture normalization for empty blackboard state on older runs.
@@ -111,7 +111,7 @@ summary metrics (`summary_freshness`, `compact_graph_parity`,
 `blackboard_digest_parity`, `critical_path_parity`, `evidence_digest_parity`,
 `expansion_ref_integrity`), and CLI/MCP parity. Summaries are derived userland
 indexes; raw blackboard, graph, audit, and evidence records are never deleted,
-and migrations remain backward compatible (pre-0.1.25 eval snapshots load with
+and migrations stay backward compatible (pre-0.1.25 eval snapshots load with
 empty summary sections).
 
 For v0.1.26, the gate includes Evidence Adoption Reasoning Chain smoke coverage
@@ -121,40 +121,40 @@ reasoning steps exempt from compaction, eval/replay reasoning metrics
 and CLI/MCP parity. The reasoning chain is derived, never authoritative over raw
 state, and pre-0.1.26 snapshots load with empty reasoning sections.
 
-The host loop must preserve CLI/MCP parity, stable JSON responses,
+The host loop must keep CLI/MCP parity, stable JSON responses,
 blackboard/audit provenance, evidence-required scoring, fail-closed selection,
 and compatibility with the lower-level topology, multi-agent, blackboard, and
 candidate primitives.
 
 For v0.1.16, release discipline adds Dogfood One Real Repo. `npm run
 dogfood:release` runs the canonical `release-cut` app against the real Cool
-Workflow repository in dry-run mode and produces a CW report, audit summary,
+Workflow repository in dry-run mode and makes a CW report, audit summary,
 provenance, release candidate, score, selection, and verifier-gated
 commit/checkpoint. `npm run release:check` includes the dogfood smoke test so
-the wiring stays covered without recursively running the full release gate.
+the wiring stays covered without running the full release gate inside itself.
 
 For v0.1.17, release discipline added Multi-Agent Runtime Core coverage.
 `npm run release:check` runs `test/multi-agent-runtime-core-smoke.js` directly
 and through `npm test`. Older fixture runs normalize with empty multi-agent
 state under `multiAgent` and `.cw/runs/<run-id>/multi-agent/`, while unknown
-user data remains preserved.
+user data stays kept.
 
 ## Unsupported Cases
 
-CW does not silently load:
+CW does not quietly load:
 
 - non-object JSON run state
 - run state with a schema version newer than the runtime
 - run state with a schema version below the supported minimum
 - state that cannot be normalized into the required runtime fields
 
-When compatibility is ambiguous, hold the release and add a fixture or migration
-step before proceeding.
+When compatibility is not clear, hold the release and add a fixture or migration
+step before going on.
 ## v0.1.27 — CLI ↔ MCP Parity
 
 v0.1.27 adds a declared capability registry and a fail-closed `npm run
-parity:check` (wired into `release:check`) guaranteeing the CLI and MCP surfaces
-are two renderings of one data source. No run-state schema change: pre-0.1.27
+parity:check` (wired into `release:check`) that makes sure the CLI and MCP surfaces
+are two views of one data source. No run-state schema change: pre-0.1.27
 runs load unchanged, and every pre-0.1.27 CLI command and MCP tool keeps working.
 See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
 
@@ -172,20 +172,20 @@ deleted and rebuilt from source. See
 
 v0.1.29 lifts execution into a pluggable driver layer: one narrow `ExecutionBackend`
 contract with interchangeable `node`/`bun`/`shell`/`container`/`remote`/`ci`
-drivers, selected by `--backend` (parallel to `--sandbox`) and inspected via
+drivers, picked by `--backend` (parallel to `--sandbox`) and inspected via
 `backend list|show|probe`. The result/evidence envelope is schema-identical across
 backends; the backend id + sandbox attestation are recorded as provenance, so this
-surface is unchanged regardless of which backend executed a run. See
+surface is unchanged no matter which backend executed a run. See
 [execution-backends.7.md](execution-backends.7.md).
 ## Web / Desktop Workbench (v0.1.30)
 
 v0.1.30 adds the Web / Desktop Workbench: a read-only, localhost-only human
 console that renders this surface (and the other four operator panels — run
 graph, blackboard, worker logs, candidate compare, audit timeline) for any run,
-reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR alongside
+reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR next to
 the CLI and MCP that holds no authoritative state and forks no schema: each panel
 equals its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
-re-derives everything from disk. See
+derives everything again from disk. See
 [web-desktop-workbench.7.md](web-desktop-workbench.7.md).
 
 ## Observability + Cost Accounting (v0.1.31)
@@ -197,11 +197,11 @@ database, no collector daemon, no hidden counter. The migration is ADDITIVE and
 backward compatible: an optional, host-attested `UsageRecord` rides on the
 task/worker record via the EXISTING result/worker intake (absent ⇒ `unreported`,
 never 0); `ResultEnvelope` and the run-state schema are unchanged (schema version
-stays 1), so old runs load and report `unreported` cost while still yielding
+stays 1), so old runs load and report `unreported` cost while still giving
 correct time and rate metrics from their recorded timestamps and outcomes. Cost
-is `attested` only from attested usage × a recorded pricing policy; assumed
-pricing is a separate `estimated` figure. Pricing is POLICY supplied as data
-(`--pricing <path>|default`), out of the kernel. The per-run report persists a
+is `attested` only from attested usage × a recorded pricing policy; guessed
+pricing is a separate `estimated` figure. Pricing is POLICY given as data
+(`--pricing <path>|default`), out of the kernel. The per-run report keeps a
 rebuildable, fingerprinted snapshot under `.cw/runs/<id>/metrics/`, and the
 cross-repo summary reports each snapshot's `valid|stale|absent` freshness against
 current source. See
@@ -214,7 +214,7 @@ 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
+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
@@ -226,7 +226,7 @@ the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffo
 
 ## Real Execution Backend Integrations (v0.1.34)
 
-container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
+container/remote/ci backends really run (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is not there. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -262,11 +262,11 @@ capture findings/evidence from any reasonable agent shape (alt keys + prose), CW
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
-Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
+Hard gate that blocks empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
 
 ## Release-Gate Determinism & Agents Vendor (v0.1.44)
 
-Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
+Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) in place 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 that gives any non-Claude AI agent one common interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -287,4 +287,9 @@ Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, dif
 
 ## Migration Compatibility (v0.1.81)
 
-v0.1.81 is additive: every change is a new flag/verb/env (`audit verify`, `run inspect-archive`, `verify-import --strict`, `CW_REQUIRE_ARCHIVE_INTEGRITY`, `quickstart --resume`, `run resume --drive`) or an internal behavior-preserving carve. Run-state schema, existing outputs, files, and exit codes are byte-identical, so runs and archives from prior versions load and verify unchanged. No migration action is required.
+v0.1.81 is additive: every change is a new flag/verb/env (`audit verify`, `run inspect-archive`, `verify-import --strict`, `CW_REQUIRE_ARCHIVE_INTEGRITY`, `quickstart --resume`, `run resume --drive`) or an internal behavior-preserving carve. Run-state schema, existing outputs, files, and exit codes are byte-identical, so runs and archives from earlier versions load and verify unchanged. No migration action is needed.
+_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/release-tooling.7.md

@@ -1,13 +1,13 @@
 # Release Tooling
 
-CW v0.1.33 adds Release Tooling: the mechanical, repetitive part of cutting a tag
+CW v0.1.33 adds Release Tooling: the mechanical, do-it-again part of cutting a tag
 becomes three deterministic scripts plus a de-duplicated release gate. Before
-v0.1.33 a release meant hand-editing the version across ~17 surfaces and recreating
-the same doc/test/CHANGELOG shapes by hand — slow, and the source of stale-version
-gate failures. This release leaves the kernel runtime untouched and moves the toil
-into tooling, so an author spends time on the feature, not the boilerplate.
+v0.1.33 a release meant changing the version by hand across ~17 surfaces and making
+the same doc/test/CHANGELOG shapes by hand — slow, and the cause of stale-version
+gate failures. This release leaves the kernel runtime untouched and moves the hard
+work into tooling, so an author gives time to the feature, not the boilerplate.
 
-The discipline is the same base-system separation used elsewhere: there is one
+The way of working is the same base-system separation used in other places: there is one
 source of truth, and the mechanical surfaces are DERIVED from it, fail-closed.
 
 ## bump:version
@@ -19,16 +19,16 @@ npm run bump:version -- 0.1.33
 
 One command rewrites every STRUCTURED version surface from a single source
 (`package.json`): `package.json`, `package-lock.json`, `src/version.ts`,
-`manifest/plugin.manifest.json` (then `gen:manifests` propagates to the vendor
+`manifest/plugin.manifest.json` (then `gen:manifests` sends it on to the vendor
 manifests), every `apps/*/app.json` (top-level `version` only, never
-`compatibility.minVersion`), and the scripts/tests that hard-code the current
-version as a current-version reference. The version string is swapped with a
-TARGETED `old -> new` replace, so historical references (a prior `minVersion`, a
-`pre-vX` note, a fixed demo version) are preserved. It then rebuilds `dist/`, runs
-`version:sync`, and reports the remaining prose-doc surfaces.
+`compatibility.minVersion`), and the scripts/tests that fix the current
+version in code as a current-version reference. The version string is changed with a
+TARGETED `old -> new` replace, so older references (a past `minVersion`, a
+`pre-vX` note, a fixed demo version) are kept. It then builds `dist/` again, runs
+`version:sync`, and reports the prose-doc surfaces that are left.
 
-`version-sync-check.js` reads the expected version from `package.json`, so the
-checker can never drift from the bump source.
+`version-sync-check.js` reads the looked-for version from `package.json`, so the
+checker can never get out of step with the bump source.
 
 ## new:feature
 
@@ -36,11 +36,11 @@ checker can never drift from the bump source.
 node scripts/new-feature.js <slug> "<Title>" ["summary"]
 ```
 
-Scaffolds the per-tag boilerplate: the `docs/<slug>.7.md` skeleton, a runnable
+Builds the per-tag boilerplate frame: the `docs/<slug>.7.md` skeleton, a runnable
 `test/<slug>-smoke.js` stub, and a `CHANGELOG` entry, then PRINTS the exact
 gate-file edits (capability registry, `version:sync` assertions, the `docs presence`
-list, the `npm test` chain). Gate files are printed, never auto-edited, so a
-scaffold can never silently break a release gate.
+list, the `npm test` chain). Gate files are printed, never changed on their own, so a
+new frame can never quietly break a release gate.
 
 ## forward-ref
 
@@ -48,17 +48,17 @@ scaffold can never silently break a release gate.
 node scripts/forward-ref-docs.js "<Title>" "<summary>"
 ```
 
-Appends a `## <Title> (vX)` forward-reference section to every doc `version:sync`
-requires to carry the current version (the repo's per-release documentation
-pattern). APPEND-ONLY and idempotent: it never rewrites a historical version label
-and re-running for the same version is a no-op.
+Adds a `## <Title> (vX)` forward-reference section at the end of every doc `version:sync`
+needs to carry the current version (the repo's per-release documentation
+pattern). APPEND-ONLY and idempotent: it never rewrites an older version label
+and running it again for the same version does nothing.
 
 ## De-duplicated release:check
 
-`release:check` previously ran `npm test` AND then re-ran ~15 of those same smoke
-tests individually (plus redundant `eval:replay`/`fixture-compat` re-runs). Every
-individual step is already covered by `npm test`, so they were removed — the gate
-keeps full coverage while dropping the duplicate wall time. The steps that remain
+`release:check` before this ran `npm test` AND then ran ~15 of those same smoke
+tests again one by one (plus extra `eval:replay`/`fixture-compat` re-runs). Every
+single step is already covered by `npm test`, so they were taken out — the gate
+keeps full coverage while cutting the doubled wall time. The steps that stay
 are the ones NOT covered by `npm test`: build, type check, `npm test`,
 canonical-apps, golden-path, parity, vendor-manifest drift, and `version:sync`.
 
@@ -66,8 +66,8 @@ canonical-apps, golden-path, parity, vendor-manifest drift, and `version:sync`.
 
 Release Tooling touches only the build/release surfaces. It adds no runtime
 capability, no CLI/MCP verb, and no run-state schema change; the kernel is
-unchanged. Older releases cut by hand remain valid — the scripts only standardize
-the mechanical surfaces a tag must update.
+unchanged. Older releases cut by hand are still good — the scripts only make
+the mechanical surfaces a tag must update the same each time.
 
 ## See Also
 
@@ -75,7 +75,7 @@ cli-mcp-parity(7), release-and-migration(7), dogfood-one-real-repo(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 run (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence next to node and fail-closed refusal when a runtime/endpoint is not there. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -107,7 +107,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 fair agent shape (alt keys + prose), CW works out grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
 
 ## No-False-Green Gate & Launch Prep (v0.1.43)
 
@@ -115,7 +115,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>`) and not the changeable working tree — taking away 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 giving any non-Claude AI agent one shared way in to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -125,19 +125,21 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 
 The gated release ritual — deterministic gate → independent reviewer → verdict →
 (tag) — is now ONE zero-dependency Node orchestrator that runs the same under any
-harness. It does not depend on a host's agent-orchestration primitive; the only
+harness. It does not lean on a host's agent-orchestration primitive; the only
 LLM step (the reviewer) is **delegated** through CW's agent backend, so whichever
-model you configure does the review. CW spawns the agent argv-style (`shell:false`),
-inherits the agent's own credentials, and imports no model SDK — the red line.
+model you set up does the review. CW starts the agent argv-style (`shell:false`),
+takes on the agent's own credentials, and pulls in no model SDK — the red line.
 
 ```bash
 # check only (gate + independent review, no mutation):
 node plugins/cool-workflow/scripts/release-flow.js --check
-# cut a tag once review is green:
-node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 [--push]
+# cut a tag once review is green (when --push, also creates the GitHub Release):
+node plugins/cool-workflow/scripts/release-flow.js --cut --version 0.1.77 [--push] [--no-release]
+# backfill / re-create the GitHub Release for an already-pushed tag (no gate/cut):
+node plugins/cool-workflow/scripts/release-flow.js --release --version 0.1.77 [--soft]
 ```
 
-The per-platform difference is config, not code — set the reviewer agent:
+The per-platform difference is config, not code — set the reviewer agent here:
 
 | Platform | Reviewer config |
 |---|---|
@@ -147,11 +149,39 @@ The per-platform difference is config, not code — set the reviewer agent:
 | OpenCode  | `CW_AGENT_COMMAND="opencode run -m <provider/model> {{input}}"` |
 | DeepSeek  | via OpenCode (`-m deepseek/deepseek-chat`) or `CW_AGENT_ENDPOINT=<deepseek-compatible HTTP agent>` |
 
-`{{input}}` is substituted with the reviewer prompt file path. Gemini and OpenCode
+`{{input}}` is put in place of the reviewer prompt file path. Gemini and OpenCode
 also get generated MCP manifests (`.gemini-plugin/`, `.opencode-plugin/`) so the
-`cw_*` tools are available as MCP tools in those hosts. The verdict path
+`cw_*` tools are there as MCP tools in those hosts. The verdict path
 (`.cw-release/review-<sha>.verdict`) and the tag-push CI backstop are unchanged.
 
+### GitHub Release finishing step
+
+A `--cut --push` ends by creating the **GitHub Release** for the tag, and
+`--release --version x.y.z` creates-or-skips one for an already-pushed tag
+(backfill). The notes body is put together from the `## x.y.z` CHANGELOG section as
+shipped at the tag, the independent reviewer's one-line capability, and a
+"Provenance & audit" footer linking the reviewed commit, the **committed** reviewer
+verdict, the full diff, and the provenance-attested npm version.
+
+This step is **distribution upside, not a correctness gate**: the load-bearing
+artifacts (the tag and the provenance-attested npm publish) are there already when it
+runs. So `gh` is **not** part of the node/git portability floor — it runs
+ONLY in the human `--cut --push` / `--release` paths (never a gate or CI path) and
+is **idempotent** (skips if the Release is there already).
+
+Failure behavior is not the same by mode: in the **`--cut --push` finishing step** an
+absent/unauthenticated/erroring `gh` **skips with a stderr note and never fails the
+cut** (the tag and npm publish stand) — opt out fully with `--no-release`. In the
+clear **`--release` backfill** it **fails closed** (exit 1) with guidance, since
+the operator asked for it straight; add `--soft` to bring `--release` down to the same
+best-effort skip-not-fail behavior.
+
+Honesty: the notes claim the gated flow ("independent release-reviewer, verdict
+above") **only when a committed `APPROVED` verdict is found at the tag**; backfilling
+an ungated tag gives a plain caveat instead and warns on stderr — the notes never
+claim a review that is not there. Test seam: `CW_RELEASE_FLOW_GH_CMD` puts a stub in place of the `gh`
+binary (spawned `shell:false`) so the smoke runs it offline.
+
 0.1.51
 
 0.1.76
@@ -162,6 +192,11 @@ also get generated MCP manifests (`.gemini-plugin/`, `.opencode-plugin/`) so the
 
 ## Fast Architecture Review (v0.1.80)
 
-Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, useful background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
 
 _No changes to the release-flow tooling in v0.1.81; this release was cut through the existing gate->review->tag flow._
+_No changes to the release-tooling contract 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/routines.md

@@ -1,9 +1,9 @@
 # Routines
 
-CW routines define a trigger, an event payload, match rules, and a generated
-prompt that an agent host can execute.
+A CW routine has a trigger, an event payload, match rules, and a prompt it makes
+for an agent host to run.
 
-CW stores routine data in:
+CW keeps routine data in:
 
 ```text
 .cw/routines/triggers.json
@@ -43,9 +43,9 @@ node scripts/cw.js routine events
 
 ## Long Architecture Reviews
 
-Use `architecture-review-fast` for the foreground user path, then schedule the
-full `architecture-review` app as background work when a deep audit should not
-block an interactive session:
+Use `architecture-review-fast` for the foreground user path. Then put the
+full `architecture-review` app in line as background work when a deep look-over
+should not get in the way of a back-and-forth session:
 
 ```bash
 node scripts/architecture-review-fast.js \
@@ -55,17 +55,17 @@ node scripts/architecture-review-fast.js \
   --schedule-full
 ```
 
-The wrapper creates a one-shot reminder schedule whose `workflowId` is
-`architecture-review`. The schedule prompt is policy. CW stores the schedule and
-records due events; the external agent host decides how to run the long review.
-The prompt includes the foreground fast run id, fast report path, source-context
-digest/profile, and asks the background agent to return the full review report
-path and digest.
-The `--metrics` flag is optional and reports foreground elapsed time plus
+The wrapper makes a one-shot reminder schedule whose `workflowId` is
+`architecture-review`. The schedule prompt is policy. CW keeps the schedule and
+notes down due events; the outside agent host says how to run the long review.
+The prompt has in it the foreground fast run id, fast report path, source-context
+digest/profile, and it asks the background agent to give back the full review
+report path and digest.
+The `--metrics` flag is not required and it gives back foreground time used plus
 agent-spawn and result-cache-hit counts for the fast run.
 
 ## Boundary
 
-CW v0.1.1 does not provide managed cloud infrastructure. It provides a local
-routine bridge that can be connected to GitHub Actions, webhooks, cron, or a
-small HTTP adapter in a future release.
+CW v0.1.1 does not give managed cloud infrastructure. It gives a local
+routine bridge that may be joined to GitHub Actions, webhooks, cron, or a
+small HTTP adapter in a later release.