cool-workflow 0.1.82 → 0.1.84

package/docs/canonical-workflow-apps.7.md

@@ -1,7 +1,7 @@
 # Canonical Workflow Apps
 
-Canonical Workflow Apps are the official CW userland apps maintained with the
-runtime. They are not loose examples. Each one lives in a first-class app
+Canonical Workflow Apps are the official CW userland apps kept up with the
+runtime. They are not loose examples. Each one is in a first-class app
 directory:
 
 ```text
@@ -9,7 +9,7 @@ apps/<app-id>/app.json
 apps/<app-id>/workflow.js
 ```
 
-The runner remains the base system. Canonical apps carry domain behavior:
+The runner is still the base system. Canonical apps add domain behavior:
 inputs, phases, task prompts, evidence gates, sandbox profile hints, and app
 metadata.
 
@@ -17,8 +17,8 @@ metadata.
 
 `architecture-review`
 
-Map a repository architecture, assess risks, verify important findings, and
-synthesize an evidence-backed verdict.
+Map out a repository architecture, weigh the risks, check the important
+findings, and put together an evidence-backed verdict.
 
 ```bash
 node scripts/cw.js plan architecture-review \
@@ -31,10 +31,10 @@ node scripts/cw.js plan architecture-review \
 `architecture-review-fast`
 
 Run a shorter architecture review for a fast first result. The app keeps the
-full `architecture-review` contract available under its original id, but uses two
+full `architecture-review` contract open under its first id, but uses two
 parallel Map workers, two parallel Assess workers, one verifier, and one verdict
-worker. Operators can optionally provide a pinned JSONL source context and route
-mapping/assessment work to a faster model while reserving stronger models for
+worker. Operators may give a pinned JSONL source context and send
+mapping/assessment work to a faster model while keeping stronger models for
 verification and synthesis.
 
 ```bash
@@ -47,29 +47,29 @@ node scripts/architecture-review-fast.js \
   --schedule-full
 ```
 
-The wrapper prepares one cached JSONL source context, passes its sha256 digest to
-the fast app, runs `quickstart architecture-review-fast`, and optionally creates
+The wrapper gets one cached JSONL source context ready, passes its sha256 digest to
+the fast app, runs `quickstart architecture-review-fast`, and may make
 a one-shot background schedule for the full `architecture-review` app. When run
-against an external repo without `--profile` or `--profile-file`, it writes a
-small repo-local `repo` profile covering common tracked text surfaces such as
+against an outside repo without `--profile` or `--profile-file`, it writes a
+small repo-local `repo` profile that covers common tracked text surfaces such as
 README/package metadata, `src/`, `lib/`, `apps/`, `scripts/`, docs, and tests.
-If the selected profile exports zero records, the wrapper fails closed instead of
+If the picked profile sends out zero records, the wrapper fails closed in place of
 passing an empty context digest to the app.
-`--fast-model` and `--strong-model` are userland policy flags; internally they
+`--fast-model` and `--strong-model` are userland policy flags; inside, they
 set the same task-level hints as `CW_ARCHITECTURE_REVIEW_FAST_MODEL` and
 `CW_ARCHITECTURE_REVIEW_STRONG_MODEL`.
-`--metrics` is opt-in; when present the wrapper adds elapsed-time, worker-step,
+`--metrics` is opt-in; when it is there the wrapper adds elapsed-time, worker-step,
 agent-spawn, and result-cache-hit counts to the JSON payload so operators can
-measure foreground wait reductions without changing the default output shape.
+measure foreground wait cuts without changing the default output shape.
 
-For long full reviews, use the existing routine or schedule surfaces to run
-`architecture-review` in the background after the fast report has returned.
+For long full reviews, use the routine or schedule surfaces you have to run
+`architecture-review` in the background after the fast report has come back.
 
 `pr-review-fix-ci`
 
-Review a pull request or branch, inspect CI failures, diagnose actionable
-issues, optionally patch when `--mode fix` is allowed, verify outcomes, and
-summarize with evidence.
+Review a pull request or branch, look at CI failures, work out the issues
+you can act on, patch when `--mode fix` is allowed, check the outcomes, and
+give a short account with evidence.
 
 ```bash
 node scripts/cw.js plan pr-review-fix-ci \
@@ -82,8 +82,8 @@ node scripts/cw.js plan pr-review-fix-ci \
 
 `release-cut`
 
-Prepare a release with checklist discipline: version checks, changelog, tests,
-packaging, release notes, and final verification.
+Get a release ready with checklist discipline: version checks, changelog, tests,
+packaging, release notes, and a last verification.
 
 ```bash
 node scripts/cw.js plan release-cut \
@@ -95,8 +95,8 @@ node scripts/cw.js plan release-cut \
 
 `research-synthesis`
 
-Split a research question into claims, investigate sources, cross-check
-evidence, verify claims, and synthesize a concise answer.
+Break a research question into claims, look into sources, cross-check
+the evidence, check the claims, and put together a short answer.
 
 ```bash
 node scripts/cw.js plan research-synthesis \
@@ -109,7 +109,7 @@ node scripts/cw.js plan research-synthesis \
 
 ## Validation Matrix
 
-Run the canonical app matrix from the plugin root:
+Run the canonical app matrix from the plugin root directory:
 
 ```bash
 cd plugins/cool-workflow
@@ -118,19 +118,19 @@ npm run canonical-apps
 
 The command uses only Node.js standard library APIs and local temporary
 workspaces. It validates each canonical app, shows its app metadata, plans it
-with representative inputs, checks app id/version metadata in run state, checks
+with sample inputs, checks app id/version metadata in run state, checks
 evidence-required verification or synthesis/verdict tasks, checks sandbox
-profile hints, checks unique task ids, and checks duplicate ids do not break
+profile hints, checks unique task ids, and checks that duplicate ids do not break
 discovery.
 
-`npm test` includes `test/canonical-workflow-apps-smoke.js`, which repeats the
-same core assertions against generated `dist/`.
+`npm test` takes in `test/canonical-workflow-apps-smoke.js`, which does the
+same core assertions again against generated `dist/`.
 
 ## Framework Pressure
 
-The apps intentionally stress different parts of the Workflow App framework:
+The apps put weight on different parts of the Workflow App framework on purpose:
 
-- declared required, optional, and repeated inputs
+- named required, optional, and repeated inputs
 - app-directory discovery and app metadata
 - readonly, locked-down, and workspace-write sandbox hints
 - evidence-required verifier, synthesis, summary, and verdict tasks
@@ -138,7 +138,7 @@ The apps intentionally stress different parts of the Workflow App framework:
 - compatibility between canonical app ids and legacy workflow-file wrappers
 
 The legacy `workflows/architecture-review.workflow.js` and
-`workflows/research-synthesis.workflow.js` files remain loadable with explicit
+`workflows/research-synthesis.workflow.js` files can still be loaded with named
 compatibility ids:
 
 ```text
@@ -146,25 +146,25 @@ legacy-architecture-review
 legacy-research-synthesis
 ```
 
-The public `architecture-review` and `research-synthesis` ids are now owned by
+The public `architecture-review` and `research-synthesis` ids are now held by
 the canonical app directories.
 
 ## Relationship To The Golden Path
 
-`npm run canonical-apps` proves the official userland app matrix validates and
-plans correctly. It does not run every worker for every app.
+`npm run canonical-apps` shows that the official userland app matrix validates and
+plans the right way. It does not run every worker for every app.
 
-`npm run golden-path` remains the full integration proof:
+`npm run golden-path` is still the full integration proof:
 
 ```text
 workflow app -> plan -> dispatch -> isolated worker -> candidate scoring
 -> verifier -> gated commit -> report
 ```
 
-Together they keep the kernel small while making the maintained userland boring,
-inspectable, and useful.
+Together they keep the kernel small while making the kept-up userland dull,
+easy to inspect, and useful.
 
-Use the Operator UX commands to inspect any canonical app run:
+Use the Operator UX commands to look at any canonical app run:
 
 ```bash
 node scripts/cw.js status <run-id>

package/docs/capability-topology-registry.7.md

@@ -6,12 +6,12 @@
 
 ## Description
 
-v0.1.53 introduces two open registries that let agents extend CW at runtime
-without manual wiring in multiple files. New capabilities self-register and
-auto-work across CLI, MCP, and Workbench. New topologies self-register and
-auto-appear in `topology list`, `topology validate`, and `topology apply`.
+v0.1.53 adds two open registries. They let agents grow CW at runtime
+with no need to wire things by hand in many files. New capabilities put
+themselves in the registry and then work by themselves across CLI, MCP, and Workbench. New topologies put
+themselves in the registry too and then come up by themselves in `topology list`, `topology validate`, and `topology apply`.
 
-BSD discipline: **mechanism** (Map / pipe) separate from **policy** (entries).
+BSD way: keep **mechanism** (Map / pipe) apart from **policy** (entries).
 Fail-closed on unknown ids.
 
 ## Capability Registry
@@ -53,18 +53,18 @@ registerCapabilityHandler({
 
 ### How it works
 
-1. `registerCapabilityHandler()` stores the handler in a `Map<string, CapabilityHandler>`
-2. CLI: `resolveCliPath(["my", "new-tool"])` resolves the CLI path to the capability id
-3. MCP: `resolveMcpTool("cw_my_new_tool")` resolves the tool name to the capability id
-4. `dispatchCapability(id, args, ctx)` invokes `handler.run(args, ctx)`
-5. Both the CLI and MCP surfaces fall through to the dynamic dispatcher when
-   their hardcoded switch statements don't match an unknown command/tool
+1. `registerCapabilityHandler()` keeps the handler in a `Map<string, CapabilityHandler>`
+2. CLI: `resolveCliPath(["my", "new-tool"])` turns the CLI path into the capability id
+3. MCP: `resolveMcpTool("cw_my_new_tool")` turns the tool name into the capability id
+4. `dispatchCapability(id, args, ctx)` calls `handler.run(args, ctx)`
+5. Both the CLI and MCP surfaces drop through to the dynamic dispatcher when
+   their hardcoded switch statements do not match an unknown command/tool
 
 ### Existing capabilities
 
-All existing 182 capabilities continue to work through their hardcoded switch
+All 182 capabilities that are there now keep working through their hardcoded switch
 cases in `cli.ts` and `mcp-server.ts`. The dynamic dispatch is a **fallback**
-— it only activates for commands/tools not found in the legacy switches.
+— it turns on only for commands/tools not found in the old switches.
 
 ## Topology Registry
 
@@ -143,24 +143,24 @@ registerTopology({
 ### How it works
 
 1. `registerTopology()` stores the definition in a `Map<string, MultiAgentTopologyDefinition>`
-2. `listTopologyDefinitions()` returns official + registered, registered wins on id collision
-3. `getTopologyDefinition(id)` checks registered first, then official
-4. `materializedRoles()` uses `role.count` for replication — no more hardcoded
+2. `listTopologyDefinitions()` gives back official + registered; registered wins when two ids are the same
+3. `getTopologyDefinition(id)` looks at registered first, then official
+4. `materializedRoles()` uses `role.count` to make copies — no more hardcoded
    mapper/judge switch logic
-5. `applyTopology()` works identically for official and registered topologies
+5. `applyTopology()` works the same way for official and registered topologies
 
 ### Data-driven role expansion
 
-Before v0.1.53, `materializedRoles()` hardcoded "mapper" and "judge" role
-expansion. Now it checks `role.count` on each role spec:
-- `role.count > 1`: creates `role-1`, `role-2`, ... `role-N`
-- `role.count` undefined or 1: creates a single role instance
-- For backward compat with official topologies, `mapperCount` and `judgeCount`
-  input overrides still apply
+Before v0.1.53, `materializedRoles()` hardcoded the "mapper" and "judge" role
+expansion. Now it reads `role.count` on each role spec:
+- `role.count > 1`: makes `role-1`, `role-2`, ... `role-N`
+- `role.count` undefined or 1: makes one role instance
+- So that official topologies keep working as before, the `mapperCount` and `judgeCount`
+  input overrides still hold
 
 ## See Also
 
-- `capability-registry.ts` — the single source of truth for all capabilities
+- `capability-registry.ts` — the one true source for all capabilities
 - `capability-dispatcher.ts` — the thin Map-based dispatch pipe
 - `topology.ts` — topology definitions and the registry
 - `types/topology.ts` — topology type definitions