cool-workflow 0.1.82 → 0.1.84

package/docs/unix-principles.md

@@ -1,16 +1,16 @@
 # Unix-Inspired Workflow Principles
 
-CW borrows a small set of durable systems ideas and applies them to agent
+CW takes a small group of long-lasting systems ideas and puts them to work in agent
 workflow engineering. These are design principles, not platform claims — but
-they are not optional: this project strictly follows the FreeBSD programming
-philosophy, and §7 below states the binding rules every change is reviewed
-against (mirrored as hard constraints in the repository's `AGENTS.md`).
+they are not a free choice: this project keeps closely to the FreeBSD programming
+way of thought, and §7 below gives the binding rules every change is checked
+against (copied as hard limits in the repository's `AGENTS.md`).
 
 ## 1. Everything Is State
 
-Every meaningful workflow event should be represented as inspectable state.
+Every workflow event with meaning should be kept as state you can look into.
 
-CW already stores:
+CW keeps now:
 
 - workflow runs in `.cw/runs/<run-id>/state.json`
 - task prompts in `.cw/runs/<run-id>/tasks/`
@@ -25,22 +25,22 @@ CW already stores:
 - workflow app identity and version in `.cw/runs/<run-id>/state.json`
 - canonical app matrix run state in temporary `.cw/runs/<run-id>/` workspaces
 - golden path proof artifacts in temporary `.cw/runs/<run-id>/` workspaces
-- operator summaries derived from state without mutating run files
+- operator summaries made from state without changing run files
 - MCP app-surface smoke runs driven through stdio JSON-RPC
 
-The practical rule is:
+The working rule is:
 
 ```text
 prompt, task, dispatch, result, error, verifier decision, schedule, trigger
 = state that can be inspected, replayed, snapshotted, or compared
 ```
 
-This keeps the runtime deterministic and keeps agent work auditable.
+This keeps the runtime fixed and certain, and keeps agent work open to check.
 
 ## 2. Small Kernel, Composable Userland
 
-CW should keep the kernel small. The kernel owns state transitions and stable
-contracts; workflow apps own domain behavior.
+CW should keep the kernel small. The kernel is the owner of state changes and
+fixed contracts; workflow apps are the owners of their field behavior.
 
 Core system calls:
 
@@ -56,8 +56,8 @@ schedule()
 trigger()
 ```
 
-The kernel should avoid hard-coded business logic. New behavior should usually
-enter as:
+The kernel should keep away from hard-coded business logic. New behavior should
+for the most part come in as:
 
 - a workflow app
 - a workflow app manifest under `apps/<app-id>/app.json`
@@ -66,20 +66,20 @@ enter as:
 - a routine trigger
 - an external worker
 
-Workflow App framework v0.1.9 makes this split concrete. The runner is the base
-system. Apps are userland: versioned, validated, inspectable definitions that
-can be listed, shown, validated, initialized, packaged, planned, and reported
-without depending on hidden runner internals.
+Workflow App framework v0.1.9 makes this split solid and clear. The runner is the
+base system. Apps are userland: versioned, checked definitions you can look into,
+that can be listed, shown, validated, initialized, packaged, planned, and reported
+without leaning on hidden runner internals.
 
-The v0.1.12 Operator UX layer is userland over state. It renders `status`,
-`graph`, `report --show`, and resource summaries without owning core
-transitions.
+The v0.1.12 Operator UX layer is userland over state. It puts out `status`,
+`graph`, `report --show`, and resource summaries without being the owner of core
+changes.
 
-The v0.1.13 MCP app surface is the same discipline applied to agent hosts: a
-small JSON tool bridge over the base runtime, old names preserved, read-only
-inspection separated from mutation, and every mutation persisted to the run.
+The v0.1.13 MCP app surface is the same way of work put to agent hosts: a
+small JSON tool bridge over the base runtime, old names kept, read-only
+looking-in kept apart from change, and every change put away into the run.
 
-The v0.1.13 canonical apps are maintained userland:
+The v0.1.13 canonical apps are kept-up userland:
 
 ```text
 architecture-review
@@ -88,18 +88,18 @@ release-cut
 research-synthesis
 ```
 
-They keep domain prompts, inputs, evidence gates, and sandbox hints in app
-directories instead of in runner internals.
+They keep field prompts, inputs, evidence gates, and sandbox hints in app
+directories in place of runner internals.
 
-The v0.1.10 `end-to-end-golden-path` app is intentionally boring userland. It
-has one readonly worker task and exists to prove that the base system pipes are
-connected.
+The v0.1.10 `end-to-end-golden-path` app is by design dull userland. It
+has one readonly worker task and is here to give proof that the base system pipes are
+joined up.
 
 ## 3. Pipelines Over Monoliths
 
-CW favors explicit data flow over hidden orchestration.
+CW is for clear data flow in place of hidden control from above.
 
-The standard pipeline is:
+The normal pipeline is:
 
 ```text
 workflow definition
@@ -114,12 +114,12 @@ workflow definition
 -> report
 ```
 
-Each stage should have a readable artifact. If a stage fails, its error output
-should become input for the next correction step instead of disappearing into a
+Each stage should have an artifact you can read. If a stage has a fault, its error
+output should become input for the next fix step in place of going away into a
 black box.
 
-Operator views follow the same rule: console summaries point to plain files,
-while `--json` and `--format json` preserve scriptable output.
+Operator views keep to the same rule: console summaries point to plain files,
+while `--json` and `--format json` keep output a script can use.
 
 The release golden path is the regression form of this rule:
 
@@ -127,9 +127,9 @@ The release golden path is the regression form of this rule:
 npm run golden-path
 ```
 
-It exercises the public CLI and then inspects state files for app metadata,
+It puts the public CLI to work and then looks into state files for app metadata,
 dispatch, worker manifest, result node, verifier node, candidate score, ranking,
-selection, verifier-gated commit, report, and absence of ErrorFeedback.
+selection, verifier-gated commit, report, and no ErrorFeedback.
 
 The canonical app matrix is the userland regression form:
 
@@ -137,14 +137,14 @@ The canonical app matrix is the userland regression form:
 npm run canonical-apps
 ```
 
-It validates and plans every maintained app without running full workers for
+It checks and plans every kept-up app without running full workers for
 each app.
 
 ## 4. Isolated Workers
 
-Workers should be isolated by scope, state, and output.
+Workers should be kept apart by scope, state, and output.
 
-Useful isolation layers:
+Helpful layers for keeping apart:
 
 - separate task prompts
 - separate result files
@@ -153,35 +153,35 @@ Useful isolation layers:
 - separate score/evidence records for competing candidates
 - named sandbox profiles for read/write/execute/network/env policy
 
-Worker failure should not corrupt the workflow kernel. A failed worker is a
-state transition, not a process-wide failure.
+A worker fault should not damage the workflow kernel. A worker that has failed is a
+state change, not a fault across the whole process.
 
-Sandbox Profiles keep policy explicit. CW stores the profile id and resolved
-policy in durable state, validates paths, and accepts or rejects worker output
-against the write policy. The agent host remains responsible for OS-level file
-access, command execution, network access, and environment filtering.
+Sandbox Profiles keep policy clear. CW keeps the profile id and worked-out
+policy in long-lasting state, checks paths, and takes or turns away worker output
+against the write policy. The agent host is still the one responsible for OS-level file
+access, command running, network access, and environment filtering.
 
 ## 5. Verifier-Gated Commits
 
-CW should not merge every generated answer back into the main workflow state.
-Generated work should pass through evidence and verifier gates first.
+CW should not put every made answer back into the main workflow state.
+Made work should go through evidence and verifier gates first.
 
-The preferred merge rule is:
+The rule for merging we are for is:
 
 ```text
 only verified state becomes committed state
 ```
 
-For competing branches, the shape is:
+For branches against one another, the shape is:
 
 ```text
 candidate workers -> score records -> verifier-gated selection
 -> verifier-gated commit()
 ```
 
-Non-gated snapshots are checkpoints. They are allowed as audit and resume
-records, but reports and commit records must not present them as verifier-gated
-committed state.
+Snapshots with no gate are checkpoints. They are let through as records for check and
+for taking up again, but reports and commit records must not put them forward as
+verifier-gated committed state.
 
 ## 6. Practical Operating Rule
 
@@ -192,49 +192,49 @@ Verifiers decide what may be committed.
 Hosts enforce runtime sandbox policy.
 ```
 
-This keeps CW small, inspectable, and extensible.
+This keeps CW small, open to looking into, and able to be grown.
 
 ## 7. FreeBSD Discipline (Binding Rules)
 
-The principles above descend from one tradition — the FreeBSD school of
-systems engineering — and CW adheres to it strictly. Concretely:
+The principles above come down from one tradition — the FreeBSD school of
+systems engineering — and CW keeps to it strictly. In clear terms:
 
-**POLA — Principle of Least Astonishment.** An existing output, file layout,
-exit code, or flag never changes meaning or bytes underneath an operator. New
-behavior ships behind a new verb/flag or an env toggle, with the prior
-behavior byte-identical by default. (Example: live drive output is additive —
+**POLA — Principle of Least Astonishment.** An output, file layout,
+exit code, or flag that is here now never changes meaning or bytes under an operator. New
+behavior comes out behind a new verb/flag or an env toggle, with the earlier
+behavior byte-identical by default. (Example: live drive output is added on top —
 stderr only, TTY-gated, `CW_NO_STREAM=1` opt-out; the stdout payload and
-evidence digest are unchanged.)
+evidence digest are not changed.)
 
-**Mechanism, not policy.** The kernel provides mechanisms; policy is data in
+**Mechanism, not policy.** The kernel gives mechanisms; policy is data in
 userland. WHICH agent runs is config (`CW_AGENT_COMMAND` / agent-config), not
-code; vendor-specific rendering lives in wrappers under `scripts/agents/`,
-never in core. Core may forward a vendor's stream; it never parses one.
+code; vendor-specific rendering is in wrappers under `scripts/agents/`,
+never in core. Core may send a vendor's stream on; it never reads one apart.
 
 **Rule of Silence.** stdout is data, stderr is diagnostics, and a
-non-interactive run is silent on success. Anything human-friendly is TTY-gated
-and can be disabled; `--json` output is stable and undecorated so it composes
+non-interactive run says nothing on success. Anything friendly to a person is TTY-gated
+and can be turned off; `--json` output is fixed and with nothing added so it goes together
 in pipes.
 
-**Fail closed, conservative defaults.** Unconfigured backends probe as
-`unverified`, unverifiable telemetry is surfaced loudly (or refused in strict
-mode), invalid results park the hop. CW never fabricates a success and never
-falls back silently. Boring correctness beats clever features.
+**Fail closed, conservative defaults.** Backends not yet configured probe as
+`unverified`, telemetry that cannot be verified is made known loudly (or turned away in strict
+mode), results that are not valid park the hop. CW never makes up a success and never
+falls back with no word. Dull right answers beat clever features.
 
 **Tools, not frameworks.** Zero runtime dependencies is a red line. Verbs do
-one thing; composition happens through durable files (`.cw/`) and pipes, not
-hidden in-process coupling.
+one thing; things come together through long-lasting files (`.cw/`) and pipes, not
+hidden joining inside the process.
 
-**Man pages are the contract.** Every shipped capability has a `docs/*.7.md`
-page updated in the same change, and doc-drift guards in the test suite keep
-the documented commands honest. Undocumented behavior is unfinished behavior.
+**Man pages are the contract.** Every capability that ships has a `docs/*.7.md`
+page kept up to date in the same change, and doc-drift guards in the test suite keep
+the documented commands true. Behavior with no docs is behavior not finished.
 
-**style(9) spirit.** One consistent style per layer; a diff matches the file
+**style(9) spirit.** One same style for each layer; a diff is in keeping with the file
 it touches and never reformats code it does not change.
 
-**Release engineering.** Main is -CURRENT; a tag is -RELEASE: it exists only
+**Release engineering.** Main is -CURRENT; a tag is -RELEASE: it is there only
 after the deterministic gate and an independent review pass, and cadence never
-overrides the gate.
+goes over the gate.
 
-A change that violates any rule in this section is rejected in review even if
-the capability it ships is otherwise desirable.
+A change that goes against any rule in this section is turned down in review even if
+the capability it ships is in other ways wanted.

package/docs/vendor-manifest-loadability.7.md

@@ -1,43 +1,43 @@
 # Vendor Manifest Loadability
 
-CW ships one kernel to many AI clients. A single `manifest/plugin.manifest.json`
-generates every vendor's plugin files (Claude, Codex, the `agents` marketplace,
-Gemini, OpenCode) — see `gen-manifests(1)`. Each vendor that exposes the MCP
-server gets a generated `mcp.json` telling that client how to launch it.
+CW ships one kernel to many AI clients. One `manifest/plugin.manifest.json`
+makes the plugin files for every vendor (Claude, Codex, the `agents` marketplace,
+Gemini, OpenCode) — see `gen-manifests(1)`. Each vendor that opens up the MCP
+server gets a made `mcp.json` that tells that client how to start it.
 
 ## The gap this closes
 
-Two gates already guard the manifests, but neither proves a vendor manifest
-actually *boots*:
+Two gates keep watch over the manifests now, but neither one proves a vendor manifest
+truly *boots*:
 
 - `npm run gen:manifests -- --check` diffs the generated bytes against the
-  manifest source. It catches drift, not a wrong-but-consistent command.
+  manifest source. It sees drift, not a wrong-but-consistent command.
 - `parity-check` boots `dist/mcp-server.js` **directly** — it never reads any
   vendor's `mcp.json`, never resolves a `pluginRootVar`.
 
-So a manifest could declare a broken `command`, `args`, or path and every gate
+So a manifest could give a broken `command`, `args`, or path and every gate
 would stay green while no client could load it. Track C ("multi-vendor manifest
-actually loaded by ≥2 real clients") was asserted, not proven.
+actually loaded by ≥2 real clients") was claimed, not proven.
 
 ## The load proof
 
-`npm run manifest:load-check` (the `vendor-manifest-load-smoke`, run automatically
-by `npm test`) closes it. For every vendor in `targets` that declares an `mcp`
+`npm run manifest:load-check` (the `vendor-manifest-load-smoke`, run by itself
+by `npm test`) closes it. For every vendor in `targets` that gives an `mcp`
 output it:
 
 1. reads the generated `mcp.json`;
-2. resolves the server `command` + `args` exactly as that client does —
-   substituting the vendor's `pluginRootVar` (`${CLAUDE_PLUGIN_ROOT}/` for Claude,
-   `./` for the rest) to the real plugin root;
+2. resolves the server `command` + `args` in just the way that client does —
+   putting the vendor's `pluginRootVar` (`${CLAUDE_PLUGIN_ROOT}/` for Claude,
+   `./` for the rest) in place of the real plugin root;
 3. spawns the server with `shell:false` (argv spawn, no shell);
-4. completes a JSON-RPC `initialize` + `tools/list` round-trip.
+4. finishes a JSON-RPC `initialize` + `tools/list` round-trip.
 
-Every vendor launches the same kernel, so the proof asserts they **agree**: one
-`serverInfo.name` and an identical tool count across all of them. A vendor whose
-manifest drifted to an unbootable shape — wrong path, wrong command, bad
-`pluginRootVar` — fails this check instead of shipping a dead plugin.
+Every vendor starts the same kernel, so the proof says they **agree**: one
+`serverInfo.name` and the same tool count across all of them. A vendor whose
+manifest drifted to a shape that will not boot — wrong path, wrong command, bad
+`pluginRootVar` — does not pass this check, so it does not ship a dead plugin.
 
 ## See also
 
-- `gen-manifests(1)` — one source generates every vendor manifest.
+- `gen-manifests(1)` — one source makes every vendor manifest.
 - `cli-mcp-parity(7)` — the CLI ↔ MCP capability-parity gate.

package/docs/verifier-gated-commit.7.md

@@ -2,7 +2,7 @@
 
 ## NAME
 
-Verifier-Gated Commit - commit only state that passed an evidence-backed verifier
+Verifier-Gated Commit - commit only state that got past an evidence-backed verifier
 
 ## SYNOPSIS
 
@@ -25,26 +25,26 @@ commitState(run, {
 
 ## DESCRIPTION
 
-Verifier-Gated Commit is the CW rule that separates committed state from
-ordinary checkpoints:
+Verifier-Gated Commit is the CW rule that keeps committed state apart from
+normal checkpoints:
 
 ```text
 only verified state becomes committed state
 ```
 
-A verifier-gated commit requires one of these inputs:
+A verifier-gated commit needs one of these inputs:
 
 - a `verifier` state node with `verified` status and evidence
 - a verified candidate selection that references such a verifier node
 - a selected candidate whose selection references such a verifier node
 
-The verifier gate is authoritative. Candidate scores are evidence for operator
-choice, not authority to commit state.
+The verifier gate has the final say. Candidate scores are evidence to help the
+operator make a choice. They do not give the right to commit state.
 
 ## CHECKPOINTS
 
-CW still writes internal snapshots for planning, dispatch, result recording, and
-operator checkpoints. These records are checkpoints. They are useful for audit,
+CW still writes inside snapshots for planning, dispatch, result recording, and
+operator checkpoints. These records are checkpoints. They are good for audit,
 resume, and rollback, but they are not verifier-gated committed state.
 
 Checkpoint records have:
@@ -61,7 +61,7 @@ verifier-gated commit state node uses `status: "committed"`.
 
 ## COMMIT RECORDS
 
-A verifier-gated commit records gate metadata in the commit JSON and state node:
+A verifier-gated commit writes gate metadata in the commit JSON and state node:
 
 ```json
 {
@@ -74,7 +74,7 @@ A verifier-gated commit records gate metadata in the commit JSON and state node:
 }
 ```
 
-The `candidateId` and `selectionId` fields are present when the commit promotes
+The `candidateId` and `selectionId` fields are there when the commit promotes
 a candidate or candidate selection. The `evidence` field is copied from the
 verifier node.
 
@@ -88,7 +88,7 @@ verifier node.
 .cw/runs/<run-id>/report.md
 ```
 
-Every blocked commit attempt records an `error` state node and an ErrorFeedback
+Every blocked commit try writes an `error` state node and an ErrorFeedback
 record before the command exits.
 
 ## FAILURE MODES
@@ -114,12 +114,12 @@ commit-selection-not-verified
 commit-verifier-linkage-mismatch
 ```
 
-Use `cw.js feedback list <run-id>` and `cw.js node graph <run-id>` to inspect
+Use `cw.js feedback list <run-id>` and `cw.js node graph <run-id>` to look at
 the failed transition.
 
 ## CANDIDATES
 
-A candidate can become committed state only after selection passes the verifier
+A candidate can become committed state only after selection gets past the verifier
 gate. Rejected, failed, unscored, unselected, or unverified candidates are
 blocked.
 
@@ -131,10 +131,10 @@ candidate record -> score record -> verified selection -> verifier-gated commit
 
 ## COMPATIBILITY
 
-Verifier-Gated Commit is introduced in CW v0.1.7. It adds optional fields to
+Verifier-Gated Commit comes in with CW v0.1.7. It adds optional fields to
 commit records and keeps older run state readable.
 
-Programmatic snapshots that do not request a verifier gate remain checkpoints.
-The CLI `commit` command is stricter: a plain manual commit fails closed unless
+Programmatic snapshots that do not ask for a verifier gate stay checkpoints.
+The CLI `commit` command is more strict: a plain by-hand commit fails closed unless
 the operator passes `--allow-unverified-checkpoint`.
 0.1.51