cool-workflow 0.1.78

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

@@ -0,0 +1,280 @@
+# Release And Migration Discipline
+
+CW v0.1.14 made release checks and durable run-state compatibility explicit.
+
+## 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:
+
+```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
+the normalized/migrated state back to disk.
+
+## State Policy
+
+The current durable run-state schema is `1`, defined by
+`CURRENT_RUN_STATE_SCHEMA_VERSION` in `src/version.ts`.
+
+Loading state follows this order:
+
+```text
+read JSON -> detect schema -> migrate -> normalize -> validate -> report
+```
+
+CW supports legacy run state with no `schemaVersion` as historical 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.
+
+## Dry Run
+
+`state check` is dry-run by default. It reports:
+
+- detected and current schema versions
+- compatibility status: `current`, `migrated`, `normalized`, or `unsupported`
+- whether writing would be required
+- every field CW would add or normalize
+- warnings and errors
+
+## Backward Compatibility Fixtures
+
+Fixture runs live in `test/fixtures/runs/` and cover:
+
+- pre-app/simple run state
+- Sandbox Profiles
+- Workflow App framework metadata
+- End-to-End Golden Path
+- 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.
+
+## Release Check
+
+`npm run release:check` is the release gate for v0.1.14 and later. It runs:
+
+- docs presence checks
+- `npm run build`
+- `npm run check`
+- `npm test`
+- `node test/multi-agent-runtime-core-smoke.js`
+- `node test/coordinator-blackboard-smoke.js`
+- `node test/multi-agent-topologies-smoke.js`
+- `node test/multi-agent-eval-replay-harness-smoke.js`
+- `npm run eval:replay`
+- dogfood release smoke coverage
+- `npm run canonical-apps`
+- `npm run golden-path`
+- `npm run fixture-compat`
+- `npm run version:sync`
+
+The command is dry-run and non-destructive. Tagging, pushing, and publishing
+remain 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.
+
+For v0.1.18, the gate includes Coordinator / Blackboard smoke coverage and
+fixture normalization for empty blackboard state on older runs.
+
+For v0.1.19, the gate includes Multi-Agent Topologies smoke coverage and
+fixture normalization for empty topology state on older runs.
+
+For v0.1.20, the gate includes Multi-Agent CLI + MCP Surface smoke coverage.
+
+For v0.1.21, the gate includes Multi-Agent Operator UX smoke coverage for
+derived graph, dependency, failure, evidence adoption, report, and MCP parity
+views.
+
+For v0.1.22, the gate includes Multi-Agent Trust / Policy / Audit smoke
+coverage for role policy, permission decisions, blackboard write audit, message
+provenance, judge rationale, panel decisions, policy violations, report output,
+audit provenance, and MCP parity.
+
+For v0.1.24, the gate includes Multi-Agent Eval & Replay Harness smoke
+coverage for replay snapshots, isolated replay runs, normalized comparison,
+scoring, fail-closed regression detection, report output, and MCP parity.
+
+For v0.1.25, the gate includes State Explosion Management smoke coverage for
+durable summary records, compact and focused graph views, blackboard digests,
+critical-path preservation, fail-closed stale-summary detection, eval/replay
+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
+empty summary sections).
+
+For v0.1.26, the gate includes Evidence Adoption Reasoning Chain smoke coverage
+for derived, fingerprinted reasoning chains, fail-closed `unexplained` detection,
+reasoning steps exempt from compaction, eval/replay reasoning metrics
+(`reasoning_freshness`, `reasoning_chain_parity`, `reasoning_unexplained_parity`),
+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,
+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,
+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.
+
+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.
+
+## Unsupported Cases
+
+CW does not silently 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.
+## 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
+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).
+
+## Run Registry / Control Plane (v0.1.28)
+
+v0.1.28 adds a derived, rebuildable run registry over the same durable run state.
+No run-state schema change: pre-0.1.28 single-repo runs and existing `.cw/runs/`
+layouts keep working with an empty registry (`registry show` reports `absent`
+until the first `registry refresh`), and the registry, archive/provenance
+overlays, queue, and home discovery set are all derivable files that can be
+deleted and rebuilt from source. See
+[run-registry-control-plane.7.md](run-registry-control-plane.7.md).
+
+## 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
+`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
+[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
+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
+[web-desktop-workbench.7.md](web-desktop-workbench.7.md).
+
+## Observability + Cost Accounting (v0.1.31)
+
+v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
+derive time/duration, failure/verifier/acceptance rates (with sample counts and
+fail-closed `n/a`), and token/cost from existing durable run state — no metrics
+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
+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
+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
+[observability-cost-accounting.7.md](observability-cost-accounting.7.md).
+
+
+## Team Collaboration (v0.1.32)
+
+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
+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
+Workbench. See [Team Collaboration](team-collaboration.7.md).
+
+## Release Tooling (v0.1.33)
+
+the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(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).
+
+## Node Snapshot / Diff / Replay (v0.1.35)
+
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## 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
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking 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.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+0.1.51
+
+0.1.76
+
+0.1.77
+
+0.1.78

package/docs/release-tooling.7.md

@@ -0,0 +1,159 @@
+# Release Tooling
+
+CW v0.1.33 adds Release Tooling: the mechanical, repetitive 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.
+
+The discipline is the same base-system separation used elsewhere: there is one
+source of truth, and the mechanical surfaces are DERIVED from it, fail-closed.
+
+## bump:version
+
+```text
+node scripts/bump-version.js <new-version>
+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
+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.
+
+`version-sync-check.js` reads the expected version from `package.json`, so the
+checker can never drift from the bump source.
+
+## new:feature
+
+```text
+node scripts/new-feature.js <slug> "<Title>" ["summary"]
+```
+
+Scaffolds the per-tag boilerplate: 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.
+
+## forward-ref
+
+```text
+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.
+
+## 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
+are the ones NOT covered by `npm test`: build, type check, `npm test`,
+canonical-apps, golden-path, parity, vendor-manifest drift, and `version:sync`.
+
+## Boundary
+
+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.
+
+## See Also
+
+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).
+
+## Node Snapshot / Diff / Replay (v0.1.35)
+
+per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
+
+## Contract Migration Tooling (v0.1.36)
+
+first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
+
+## Control-Plane Scheduling (v0.1.37)
+
+priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
+
+## Agent Delegation Drive (v0.1.38)
+
+spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
+
+## Run Retention & Provable Reclamation (v0.1.39)
+
+tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
+
+## Durable State & Locking (v0.1.40)
+
+atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
+
+## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
+
+evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
+
+## 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
+
+## No-False-Green Gate & Launch Prep (v0.1.43)
+
+Hard gate blocking 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.
+
+## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
+
+Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
+
+## Multi-platform release flow (`scripts/release-flow.js`)
+
+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
+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.
+
+```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]
+```
+
+The per-platform difference is config, not code — set the reviewer agent:
+
+| Platform | Reviewer config |
+|---|---|
+| Claude    | `CW_AGENT_COMMAND="claude -p {{input}}"` |
+| Codex     | `CW_AGENT_COMMAND="codex exec {{input}}"` |
+| Gemini    | `CW_AGENT_COMMAND="gemini -p {{input}}"` |
+| 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
+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-release/review-<sha>.verdict`) and the tag-push CI backstop are unchanged.
+
+0.1.51
+
+0.1.76
+
+0.1.78

package/docs/routines.md

@@ -0,0 +1,48 @@
+# Routines
+
+CW routines define a trigger, an event payload, match rules, and a generated
+prompt that an agent host can execute.
+
+CW stores routine data in:
+
+```text
+.cw/routines/triggers.json
+.cw/routines/payloads/
+```
+
+## Commands
+
+Create an API trigger:
+
+```bash
+node scripts/cw.js routine create \
+  --kind api \
+  --prompt "Handle this API event."
+```
+
+Create a GitHub trigger:
+
+```bash
+node scripts/cw.js routine create \
+  --kind github \
+  --prompt "Review this GitHub event." \
+  --match '{"action":"opened"}'
+```
+
+Fire a trigger from a payload file:
+
+```bash
+node scripts/cw.js routine fire github payload.json
+```
+
+Inspect events:
+
+```bash
+node scripts/cw.js routine events
+```
+
+## 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.