cool-workflow 0.1.82 → 0.1.83

package/docs/source-context-profiles.7.md

@@ -2,12 +2,12 @@
 
 CW keeps source-context slimming out of the runtime kernel. The profile is policy
 data in `manifest/source-context-profiles.json`; `scripts/source-context.js` is a
-small mechanism that reads a git ref and writes JSONL to stdout.
+small part that reads a git ref and writes JSONL to stdout.
 
 ## Core Profile
 
 The default `core` profile is the project memory for AI source imports. It keeps
-runtime source and app/userland entrypoints, and leaves generated artifacts,
+runtime source and app/userland entrypoints, and leaves made artifacts,
 tests, docs, release records, and long logs as manifest-only records.
 
 Included:
@@ -30,26 +30,26 @@ Excluded from exported content:
 - `CHANGELOG.md`
 - `ITERATION_LOG.md`
 
-Exclusion does not delete files and does not change release behavior. `dist/`
-remains a committed release artifact until the release contract is explicitly
+Leaving a file out does not delete it and does not change release behavior. `dist/`
+stays a committed release artifact till the release contract is clearly
 changed.
 
 ## Narrow Profiles
 
-Use a narrower opt-in profile when the question is already scoped:
+Use a narrower opt-in profile when the question is already scoped down:
 
 - `runtime`: the full `src/**` runtime kernel plus package and TypeScript
   metadata.
 - `mcp`: capability core/registry, CLI routing, MCP server, MCP launcher scripts,
   and shared types.
-- `workflow-apps`: canonical apps plus the Workflow App framework and app
+- `workflow-apps`: the true apps plus the Workflow App framework and app
   planning/orchestration surface.
 - `release`: release flow, gates, manifest/version tooling, package metadata, and
   release-tooling docs.
-- `agent-wrappers`: external agent wrappers, agent config, execution backend,
+- `agent-wrappers`: outside agent wrappers, agent config, execution backend,
   drive loop, and agent-delegation docs.
 
-The narrow profiles are policy data only. Selecting one changes only the JSONL
+The narrow profiles are policy data only. Picking one changes only the JSONL
 context pack; it does not change runtime behavior, release contents, or the
 default `core` profile.
 
@@ -73,35 +73,35 @@ node scripts/source-context.js export --profile core --ref HEAD --repo-root /pat
 `export` emits only included text files and adds `content`. Both commands use
 stdout for JSONL data only. Diagnostics and refusal messages go to stderr.
 
-`--changed-from REF` is opt-in diff-aware mode. It filters `manifest` and
-`export` to paths changed between the resolved base commit and `--ref`, then
-applies the selected profile include/exclude rules. Deleted files are omitted
-because there is no blob at the target ref. Records include `changedFrom` with
-the resolved base commit. Empty diffs are valid and emit empty JSONL.
+`--changed-from REF` is opt-in diff-aware mode. It cuts `manifest` and
+`export` down to paths changed between the resolved base commit and `--ref`, then
+applies the selected profile include/exclude rules. Deleted files are left out
+because there is no blob at the target ref. Records take in `changedFrom` with
+the resolved base commit. Empty diffs are good and emit empty JSONL.
 
 `export --cache-dir DIR` is opt-in. The cache key is the resolved git commit SHA
-plus a digest of the selected source profile, so changing either the ref or the
-include/exclude policy produces a different JSONL cache file. Cache hits write the
-same JSONL bytes to stdout and stay silent on stderr. Corrupt or mismatched cache
-records fail closed instead of falling back silently. Diff-aware exports include
+plus a digest of the selected source profile, so changing the ref or the
+include/exclude policy makes a different JSONL cache file. Cache hits write the
+same JSONL bytes to stdout and stay quiet on stderr. Broken or wrong cache
+records fail closed in place of falling back without a word. Diff-aware exports take in
 the resolved `--changed-from` commit in the cache key, so full and changed exports
 do not share cache files.
 
-`--repo-root DIR` is also opt-in; when omitted, the script keeps its historical
+`--repo-root DIR` is opt-in too; when left out, the script keeps its past
 default and reads the Cool Workflow repository root.
 
 ## Verification
 
 The smoke test checks that:
 
-- the profile includes and excludes exactly the remembered paths;
+- the profile takes in and leaves out the very same remembered paths;
 - `dist/`, tests, docs, release records, and long logs are manifest-only;
-- exported records are parseable JSONL with content and sha256;
-- narrow profiles are slimmer than `core` and include/exclude their intended
-  surfaces;
-- `--changed-from` emits only changed current-ref files, still honors excludes,
-  and caches separately from full exports;
-- cached exports are byte-identical to uncached exports and corrupt cache hits
+- exported records are JSONL that parses with content and sha256;
+- narrow profiles are slimmer than `core` and include/exclude the surfaces they
+  are meant to;
+- `--changed-from` emits only changed current-ref files, still keeps its excludes,
+  and caches apart from full exports;
+- cached exports are byte-identical to uncached exports and broken cache hits
   fail closed;
 - the `core` profile stays under its `maxLines` guard.
 
@@ -113,7 +113,7 @@ node test/source-context-profile-smoke.js
 
 ## FreeBSD Discipline
 
-This feature is opt-in and does not alter existing CLI output. It is mechanism,
+This feature is opt-in and does not change present CLI output. It is mechanism,
 not policy: profile selection lives in data, and vendor prompt/stream behavior
-stays in wrappers. It fails closed on invalid profiles, unknown refs, binary
-included files, and line-count drift past the configured guard.
+stays in wrappers. It fails closed on bad profiles, unknown refs, binary
+included files, and line-count drift past the set guard.

package/docs/state-explosion-management.7.md

@@ -1,30 +1,30 @@
 # State Explosion Management
 
-CW v0.1.25 adds State Explosion Management. As multi-agent collaboration grows,
-blackboard and graph output can become too large to read. This release adds a
-first-class summarization and compaction layer that makes complex runs
-understandable without hiding source truth.
+CW v0.1.25 adds State Explosion Management. When multi-agent work grows,
+blackboard and graph output can get too big to read. This release adds a
+first-class summarization and compaction layer that makes hard runs
+clear to read without hiding source truth.
 
 CW v0.1.26 builds on this layer with the Evidence Adoption Reasoning Chain, which
-reuses the same derived, fingerprinted, fail-closed discipline and whose
-reasoning steps are exempt from the compaction described here. See
+reuses the same derived, fingerprinted, fail-closed way of working and whose
+reasoning steps are free from the compaction talked about here. See
 [evidence-adoption-reasoning-chain.7.md](evidence-adoption-reasoning-chain.7.md).
 
-The design follows a base-system observability philosophy:
+The design keeps to a base-system observability way of thinking:
 
 - raw state is the source of truth
-- summaries are derived userland indexes, never replacements for source records
+- summaries are derived userland indexes, never a substitute for source records
 - plain files, stable JSON, deterministic output
-- small composable commands and readable console views with full
-  machine-readable output available
-- fail closed when a summary is stale, incomplete, ambiguous, or loses
+- small composable commands and readable console views, with full
+  machine-readable output ready to use
+- fail closed when a summary is stale, not complete, not clear, or loses
   provenance
 - backward compatible; no hidden daemon; no lossy deletion of blackboard,
   graph, audit, or evidence records
 
 ## Derived summary model
 
-Summary records are durable, versioned, and provenance-backed. Each carries
+Summary records are durable, versioned, and backed by provenance. Each one carries
 `schemaVersion`, `runId`, a summary `id`, a `scope`
 (`run`, `topology`, `multi-agent-run`, `group`, `role`, `membership`, `fanout`,
 `fanin`, `blackboard`, `topic`, `evidence`, `trust`, or `eval`),
@@ -43,14 +43,14 @@ Record types:
 
 Summaries are written under `.cw/runs/<run-id>/summaries/` as plain JSON. Raw
 blackboard messages, graph nodes, graph edges, audit events, evidence refs, and
-eval artifacts are never deleted or overwritten.
+eval artifacts are never deleted or written over.
 
 Within a single summary build, CW shares the derived full operator graph,
 operator status, blackboard digest, state-size record, and graph view records
-through a short-lived in-memory context. This avoids rebuilding the same graph
-for `summary refresh`, `summary show`, and the top-level state-explosion report.
-It is not a daemon or persistent cache: the next command re-reads run state from
-disk, recomputes source fingerprints, and still fails closed on stale summaries.
+through a short-lived in-memory context. This way it does not build the same graph
+again for `summary refresh`, `summary show`, and the top-level state-explosion report.
+It is not a daemon or persistent cache: the next command reads run state from
+disk again, works out source fingerprints again, and still fails closed on stale summaries.
 
 ## Blackboard summarization
 
@@ -58,28 +58,28 @@ disk, recomputes source fingerprints, and still fails closed on stale summaries.
 deterministic structural digest with topic rollups, message thread summaries,
 unresolved questions, conflicts, decisions, artifacts, adopted evidence,
 missing evidence, policy violations, judge rationale, recent changes, and
-high-signal records. Every entry preserves links back to source messages,
+high-signal records. Every entry keeps links back to source messages,
 contexts, artifacts, snapshots, coordinator decisions, and audit events, plus an
 expansion command for the raw records. Structural summaries exist without any
-LLM output; any semantic summary must be explicit, provenance-backed, and
-evidence-linked.
+LLM output; any semantic summary must be clear, backed by provenance, and
+linked to evidence.
 
 ## Graph compaction
 
 `multi-agent graph <run-id> --view <view>` produces compact graph views.
 Supported views: `full`, `compact`, `critical-path`, `failures`, `evidence`,
 `trust`, `topology`, `blackboard`, `candidate`, and `commit-gate`. Use
-`--focus <id>` and `--depth <n>` to center the view on a node and its
-neighborhood.
+`--focus <id>` and `--depth <n>` to put the view on a node and the
+nodes near it.
 
-Compact views collapse high-volume groups, topics, fanouts, fanins, message
+Compact views fold high-volume groups, topics, fanouts, fanins, message
 clusters, and evidence chains into synthetic summary nodes. Each synthetic node
-exposes `collapsedNodeCount`, `collapsedEdgeCount`, `sourceIds`,
+shows `collapsedNodeCount`, `collapsedEdgeCount`, `sourceIds`,
 `dominantStatus`, an optional `blockedReason`, and an `expansionCommand`.
 
-The critical path is always preserved, and failures, blocked records,
+The critical path is always kept, and failures, blocked records,
 conflicts, missing evidence, policy violations, and judge rationale are never
-collapsed.
+folded.
 
 ## CLI
 
@@ -98,11 +98,11 @@ Every command supports deterministic JSON with `--json` or `--format json`.
 Human output is organized into stable panels: State Size, Compact Graph,
 Blackboard Digest, Critical Path, Failures / Blockers, Evidence Digest,
 Trust / Policy Digest, Hidden Source Records, Expansion Commands, and Next
-Action. JSON output is never silently compacted; compaction is applied only to
-human views or when a compact view is explicitly requested.
+Action. JSON output is never quietly compacted; compaction is used only on
+human views or when a compact view is clearly asked for.
 
-When thresholds are exceeded, human output automatically shows compact
-summaries and tells the operator how to inspect the full data, for example:
+When thresholds are gone past, human output by itself shows compact
+summaries and tells the operator how to look at the full data, for example:
 
 ```text
 Graph compacted: 420 nodes collapsed into 18 summary nodes
@@ -122,7 +122,7 @@ MCP responses include source refs and expansion hints.
 
 ## Eval / replay integration
 
-Eval snapshots include summary artifacts, and replay comparison treats them as
+Eval snapshots take in summary artifacts, and replay comparison treats them as
 regression-gated. Metrics: `summary_freshness`, `compact_graph_parity`,
 `blackboard_digest_parity`, `critical_path_parity`, `evidence_digest_parity`,
 and `expansion_ref_integrity`. The eval gate fails closed on stale summaries,
@@ -133,36 +133,36 @@ summary/report mismatch.
 ## Trust and audit
 
 Summary generation is recorded in the trust-audit log. `summary refresh` records
-a `summary.refresh` event noting who or what generated the summary, which scopes
-were summarized, how many records were included and omitted, whether the summary
+a `summary.refresh` event noting who or what made the summary, which scopes
+were summarized, how many records were put in and left out, whether the summary
 is deterministic, the source fingerprint, and whether it is stale. `summary
-show` records a `summary.stale` event when the persisted fingerprint no longer
-matches current source state. Audit metadata never stores secrets or large raw
+show` records a `summary.stale` event when the kept fingerprint no longer
+matches current source state. Audit metadata never keeps secrets or large raw
 message bodies.
 
 ## Freshness and fail-closed behavior
 
-`summary show` recomputes the current source fingerprint and compares it to the
-persisted record. If they differ, the report status is `stale`, stale scopes are
+`summary show` works out the current source fingerprint again and compares it to the
+kept record. If they are not the same, the report status is `stale`, stale scopes are
 listed, and the next action is `summary refresh`. This keeps derived indexes
-honest: a summary is never trusted once its source records change.
+true: a summary is never trusted once its source records change.
 
 ## Migration
 
 Pre-0.1.25 runs have no `summaries/` directory; `summary show` reports `absent`
-and recommends `summary refresh`. Pre-0.1.25 eval snapshots load with empty
-summary sections, so existing fixtures and replays remain backward compatible.
+and tells you to use `summary refresh`. Pre-0.1.25 eval snapshots load with empty
+summary sections, so existing fixtures and replays stay backward compatible.
 Newer unsupported run-state schemas still fail closed.
 ## CLI ↔ MCP Parity (v0.1.27)
 
-Every command and tool referenced above is declared in the v0.1.27 capability
-registry (`src/capability-registry.ts`) and validated by `npm run parity:check`,
-so `cw <cmd> --json` and the matching `cw_<tool>` result render one data source.
+Every command and tool named above is declared in the v0.1.27 capability
+registry (`src/capability-registry.ts`) and checked by `npm run parity:check`,
+so `cw <cmd> --json` and the matching `cw_<tool>` result show one data source.
 See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
 
 ## Run Registry / Control Plane (v0.1.28)
 
-The runs described here are indexed, searchable, resumable, archivable, and
+The runs talked about here are indexed, searchable, resumable, archivable, and
 rerunnable across repos by the v0.1.28 Run Registry / Control Plane, which derives
 a fingerprinted, fail-closed index over the same per-run `.cw/runs/<id>/state.json`
 source of truth. See [run-registry-control-plane.7.md](run-registry-control-plane.7.md).
@@ -170,21 +170,21 @@ source of truth. See [run-registry-control-plane.7.md](run-registry-control-plan
 ## Execution Backends (v0.1.29)
 
 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
+contract with swappable `node`/`bun`/`shell`/`container`/`remote`/`ci`
+drivers, picked by `--backend` (parallel to `--sandbox`) and looked at through
 `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 stays the same no matter which backend ran 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
+console that shows 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)
@@ -195,7 +195,7 @@ fail-closed `n/a`), and host-attested token/cost from existing durable run state
 — no metrics database, no collector daemon, no hidden counter. Usage is additive
 and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
 × a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
-verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
+verbs are parity-gated and show read-only in the v0.1.30 Workbench. See
 [observability-cost-accounting.7.md](observability-cost-accounting.7.md).
 
 
@@ -205,10 +205,10 @@ 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
+not changed). The verbs are parity-gated and show read-only in the v0.1.30
 Workbench. See [Team Collaboration](team-collaboration.7.md).
 
 ## Release Tooling (v0.1.33)
@@ -217,7 +217,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 to use. See real-execution-backends(7).
 
 ## Node Snapshot / Diff / Replay (v0.1.35)
 
@@ -249,15 +249,15 @@ 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 derives 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)
 
-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 check the committed blob (`git show HEAD:<path>`) instead of 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 common interface to CW.
 
 ## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
 
@@ -274,7 +274,11 @@ Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.4
 
 ## Fast Architecture Review (v0.1.80)
 
-Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, 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 state-explosion management surface in v0.1.81 (the module was carved into behavior-preserving siblings; output is byte-identical)._
+_No changes to the state-explosion management surface in v0.1.81 (the module was cut into behavior-preserving siblings; output is byte-identical)._
 _No changes in v0.1.82._
+
+## Hardening and Onboarding (v0.1.83)
+
+Loaders fail closed on corrupt state; store writes are made safe under more than one writer; a new cw doctor checks your setup; help lists every command; and the docs are put into Basic English.

package/docs/state-node.7.md

@@ -29,17 +29,17 @@ const verified = transitionStateNode(result, { status: "verified", loopStage: "a
 
 ## DESCRIPTION
 
-`StateNode` is the small runtime object used to represent meaningful CW transitions as JSON. It is not a workflow app model and does not encode domain behavior.
+`StateNode` is the small runtime object used to show important CW transitions as JSON. It is not a workflow app model and it does not hold domain behavior.
 
-The kernel owns node creation, explicit status transitions, artifact paths, contract validation, and structured errors. Workflow apps own prompts, phase order, and domain-specific interpretation.
+The kernel owns node creation, clear status transitions, artifact paths, contract checks, and structured errors. Workflow apps own prompts, phase order, and the reading of domain-specific meaning.
 
-CW writes node JSON artifacts under:
+CW writes node JSON artifacts in:
 
 ```text
 .cw/runs/<run-id>/nodes/
 ```
 
-The normal flow is:
+The common flow is:
 
 ```text
 input node -> task node -> dispatch node -> result node -> verifier node -> commit/report node
@@ -51,11 +51,11 @@ Every `StateNode` includes `schemaVersion`, `id`, `kind`, `status`, `loopStage`,
 
 Every `PipelineContract` includes `schemaVersion`, `id`, `title`, `stages`, optional input/output schemas, artifact/evidence/failure/commit policies, and compatibility bounds.
 
-Each stage declares accepted input node kinds and statuses, produced output kind, required artifacts, required evidence, verifier gate, and retry/failure behavior.
+Each stage names the input node kinds and statuses it takes, the output kind it makes, required artifacts, required evidence, verifier gate, and retry/failure behavior.
 
 ## FAILURE MODES
 
-Contract failures are raised as `PipelineContractError`. Each error carries a structured `StateNodeError` with:
+Contract failures come up as `PipelineContractError`. Each error carries a structured `StateNodeError` with:
 
 - `code`
 - `message`
@@ -65,7 +65,7 @@ Contract failures are raised as `PipelineContractError`. Each error carries a st
 - optional `retryable`
 - optional `details`
 
-Illegal status transitions fail before mutating the node. Missing artifacts and missing evidence fail with locatable error records suitable for saving into a failure node.
+Illegal status transitions fail before they change the node. Missing artifacts and missing evidence fail with error records you can locate, ready for saving into a failure node.
 
 Commit status is verifier-gated. A node cannot transition into `committed` unless it is already `verified`.
 
@@ -73,7 +73,7 @@ Commit status is verifier-gated. A node cannot transition into `committed` unles
 
 `schemaVersion` is required on both nodes and contracts. The current schema is `1`.
 
-New fields should be optional unless the runtime cannot proceed without them. Older run state without `nodes` or `contracts` remains readable; those arrays are initialized when loaded.
+New fields should be optional unless the runtime cannot go on without them. Older run state without `nodes` or `contracts` can still be read; those arrays are set up when loaded.
 
 ## EXAMPLES