cool-workflow 0.1.78

package/docs/scheduled-tasks.md

@@ -0,0 +1,80 @@
+# Scheduled Tasks
+
+CW scheduled tasks support looping prompts, cron-like schedules, one-shot
+reminders, expiration, jitter, and explicit completion.
+
+CW stores schedules in:
+
+```text
+.cw/schedules/tasks.json
+```
+
+## Commands
+
+Create a `/loop`-compatible schedule:
+
+```bash
+node scripts/cw.js loop \
+  --intervalMinutes 30 \
+  --prompt "Check this workflow and continue if work is due."
+```
+
+Create a loop:
+
+```bash
+node scripts/cw.js schedule create \
+  --kind loop \
+  --intervalMinutes 30 \
+  --prompt "Check this workflow and continue if work is due."
+```
+
+Create a cron schedule:
+
+```bash
+node scripts/cw.js schedule create \
+  --kind cron \
+  --cron "*/15 * * * *" \
+  --prompt "Run the due workflow scan."
+```
+
+Create a reminder:
+
+```bash
+node scripts/cw.js schedule create \
+  --kind reminder \
+  --delayMinutes 60 \
+  --prompt "Remind me to inspect the report."
+```
+
+List and scan:
+
+```bash
+node scripts/cw.js schedule list
+node scripts/cw.js schedule due
+node scripts/cw.js schedule complete <schedule-id>
+node scripts/cw.js schedule pause <schedule-id>
+node scripts/cw.js schedule resume <schedule-id>
+node scripts/cw.js schedule run-now <schedule-id>
+node scripts/cw.js schedule history <schedule-id>
+node scripts/cw.js schedule delete <schedule-id>
+```
+
+Run the local desktop-style daemon once:
+
+```bash
+node scripts/cw.js schedule daemon --once
+```
+
+Run it continuously:
+
+```bash
+node scripts/cw.js schedule daemon --intervalSeconds 60
+```
+
+## Notes
+
+- Resolution is minute-level.
+- Default expiration is 7 days.
+- `jitterSeconds` can spread runs.
+- CW does not start the daemon by default. Use `schedule daemon`, cron, or
+  another supervisor to call `schedule due` and execute due prompts.

package/docs/security-trust-hardening.7.md

@@ -0,0 +1,117 @@
+# Security / Trust Hardening
+
+CW v0.1.15 adds a local trust audit layer for worker sandbox decisions,
+evidence provenance, candidate selection, and verifier-gated commits.
+CW v0.1.22 reuses this same layer for multi-agent role policy, blackboard
+write audit, message provenance, judge rationale, panel decisions, and policy
+violations.
+
+## Audit Records
+
+Every run has an audit directory:
+
+```text
+.cw/runs/<run-id>/audit/
+  events.jsonl
+  index.json
+  summary.json
+```
+
+`events.jsonl` is append-friendly. `index.json` and `summary.json` are
+deterministic inspection files regenerated by CW commands.
+
+Each event records:
+
+- schema version, event id, timestamp, run id, kind, decision, and source
+- actor, worker id, task id, node id, candidate id, score id, selection id, or commit id when relevant
+- sandbox profile id and policy snapshot/reference
+- normalized path, command, network target, or env variable names when relevant
+- evidence references and parent audit event ids
+- feedback ids for denied or failed decisions
+
+Event sources are explicit:
+
+- `cw-validated`: CW checked a policy or gate locally.
+- `host-attested`: the agent host or operator recorded what the host enforced.
+- `operator-recorded`: a human or caller supplied the record.
+- `runtime-derived`: CW derived the event from run state.
+
+CW does not store secrets or raw environment values. Environment audit records
+store names only.
+
+## Enforcement Boundary
+
+CW validates sandbox profiles, normalizes paths, validates worker output
+acceptance, validates command/network/env decisions when asked, and records
+durable feedback for denied worker decisions.
+
+The agent host must still enforce OS-level read isolation, write isolation,
+process execution restrictions, network restrictions, and environment filtering.
+The audit layer makes that boundary inspectable; it is not a kernel.
+
+## CLI
+
+```bash
+node scripts/cw.js audit summary <run-id>
+node scripts/cw.js audit worker <run-id> <worker-id>
+node scripts/cw.js audit provenance <run-id> [--worker ID|--candidate ID|--commit ID]
+node scripts/cw.js audit multi-agent <run-id>
+node scripts/cw.js audit policy <run-id>
+node scripts/cw.js audit role <run-id> <role-id>
+node scripts/cw.js audit blackboard <run-id>
+node scripts/cw.js audit judge <run-id>
+node scripts/cw.js audit attest <run-id> --worker <worker-id> --hostEnforced true
+node scripts/cw.js audit decision <run-id> <worker-id> --path <path>
+node scripts/cw.js audit decision <run-id> <worker-id> --command "npm test"
+node scripts/cw.js audit decision <run-id> <worker-id> --network example.com
+node scripts/cw.js audit decision <run-id> <worker-id> --env SECRET_NAME
+```
+
+Denied audit decisions are written to audit files and linked to feedback/error
+records. Environment values are redacted to names.
+
+## Evidence Provenance
+
+`StateEvidence` remains backward compatible. v0.1.15 adds optional
+`provenance` metadata that can point from:
+
+```text
+worker result -> result node -> verifier node -> candidate -> score -> selection -> commit
+```
+
+Candidate scores, selections, and verifier-gated commits preserve provenance
+links instead of only copying evidence arrays.
+
+## Why Accepted
+
+Selected candidates and verifier-gated commits carry an acceptance rationale:
+
+- selected candidate id
+- score id and score criteria
+- verifier node id
+- evidence count
+- sandbox profile id
+- worker id
+- commit gate result
+- audit event ids
+
+Verifier-gated commits fail closed when the acceptance rationale cannot explain
+the evidence chain.
+
+## MCP
+
+The MCP server exposes matching tools:
+
+- `cw_audit_summary`
+- `cw_audit_worker`
+- `cw_audit_provenance`
+- `cw_audit_multi_agent`
+- `cw_audit_policy`
+- `cw_audit_role`
+- `cw_audit_blackboard`
+- `cw_audit_judge`
+- `cw_audit_attest`
+- `cw_audit_decision`
+
+Existing MCP tool names remain stable.
+0.1.51

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

@@ -0,0 +1,264 @@
+# 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.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
+[evidence-adoption-reasoning-chain.7.md](evidence-adoption-reasoning-chain.7.md).
+
+The design follows a base-system observability philosophy:
+
+- raw state is the source of truth
+- summaries are derived userland indexes, never replacements 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
+  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
+`schemaVersion`, `runId`, a summary `id`, a `scope`
+(`run`, `topology`, `multi-agent-run`, `group`, `role`, `membership`, `fanout`,
+`fanin`, `blackboard`, `topic`, `evidence`, `trust`, or `eval`),
+`sourceRecordIds`, a deterministic `sourceFingerprint`, `includedCount` and
+`omittedCount`, `importantRefs`, `evidenceRefs`, `trustAuditEventRefs`,
+`generatedAt`, a `status` (`valid`, `stale`, or `absent`), a `deterministic`
+flag, and a `nextAction`.
+
+Record types:
+
+- `MultiAgentSummaryIndex` - the index of all summary records for a run
+- `BlackboardSummaryRecord` - the deterministic blackboard digest
+- `GraphSummaryRecord` - a compact or focused graph view
+- `OperatorDigest` - the combined operator-facing digest
+- `StateExplosionReport` - the top-level report with all panels and freshness
+
+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.
+
+## Blackboard summarization
+
+`blackboard summarize <run-id>` (MCP: `cw_blackboard_summarize`) returns a
+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,
+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.
+
+## 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.
+
+Compact views collapse high-volume groups, topics, fanouts, fanins, message
+clusters, and evidence chains into synthetic summary nodes. Each synthetic node
+exposes `collapsedNodeCount`, `collapsedEdgeCount`, `sourceIds`,
+`dominantStatus`, an optional `blockedReason`, and an `expansionCommand`.
+
+The critical path is always preserved, and failures, blocked records,
+conflicts, missing evidence, policy violations, and judge rationale are never
+collapsed.
+
+## CLI
+
+```text
+node scripts/cw.js summary refresh <run-id> [--json] [--view <view> ...]
+node scripts/cw.js summary show <run-id> [--json]
+node scripts/cw.js blackboard summarize <run-id> [--json]
+node scripts/cw.js multi-agent summarize <run-id> [--json]
+node scripts/cw.js multi-agent graph <run-id> --view compact [--json]
+node scripts/cw.js multi-agent graph <run-id> --view critical-path [--json]
+node scripts/cw.js multi-agent graph <run-id> --focus <id> --depth <n> [--json]
+node scripts/cw.js report <run-id> --show
+```
+
+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.
+
+When thresholds are exceeded, human output automatically shows compact
+summaries and tells the operator how to inspect the full data, for example:
+
+```text
+Graph compacted: 420 nodes collapsed into 18 summary nodes
+Use: node scripts/cw.js multi-agent graph <run-id> --view full --json
+Use: node scripts/cw.js blackboard message list <run-id> --topic <topic-id>
+```
+
+## MCP parity
+
+- `cw_summary_refresh`
+- `cw_summary_show`
+- `cw_blackboard_summarize`
+- `cw_multi_agent_summarize`
+- `cw_multi_agent_graph_compact`
+
+MCP responses include source refs and expansion hints.
+
+## Eval / replay integration
+
+Eval snapshots include 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,
+missing source refs, changed compact-graph shape, lost evidence refs, hidden
+policy violations, lost judge rationale, changed critical path, and
+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
+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
+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
+listed, and the next action is `summary refresh`. This keeps derived indexes
+honest: 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.
+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.
+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
+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).
+
+## 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 durations, failure/verifier/acceptance rates (with sample counts and
+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
+[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/state-node.7.md

@@ -0,0 +1,96 @@
+# STATE-NODE(7)
+
+## NAME
+
+StateNode, PipelineContract - inspectable CW runtime state and pipeline ABI
+
+## SYNOPSIS
+
+```ts
+import {
+  assertNodeSatisfiesContract,
+  createStateNode,
+  transitionStateNode
+} from "./state-node";
+import { createDefaultPipelineContract } from "./pipeline-contract";
+
+const contract = createDefaultPipelineContract();
+const result = createStateNode({
+  kind: "result",
+  status: "completed",
+  loopStage: "observe",
+  artifacts: [{ id: "result", kind: "markdown", path: "/repo/.cw/runs/run/results/task.md" }],
+  evidence: [{ id: "result", locator: "/repo/src/file.ts:42" }]
+});
+
+assertNodeSatisfiesContract(result, contract, "verify");
+const verified = transitionStateNode(result, { status: "verified", loopStage: "adjust" });
+```
+
+## 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.
+
+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.
+
+CW writes node JSON artifacts under:
+
+```text
+.cw/runs/<run-id>/nodes/
+```
+
+The normal flow is:
+
+```text
+input node -> task node -> dispatch node -> result node -> verifier node -> commit/report node
+```
+
+## CONTRACT
+
+Every `StateNode` includes `schemaVersion`, `id`, `kind`, `status`, `loopStage`, timestamps, `inputs`, `outputs`, `artifacts`, `evidence`, `errors`, `parents`, `children`, optional `contractId`, and optional `metadata`.
+
+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.
+
+## FAILURE MODES
+
+Contract failures are raised as `PipelineContractError`. Each error carries a structured `StateNodeError` with:
+
+- `code`
+- `message`
+- `at`
+- optional `nodeId`
+- optional `path`
+- 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.
+
+Commit status is verifier-gated. A node cannot transition into `committed` unless it is already `verified`.
+
+## COMPATIBILITY
+
+`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.
+
+## EXAMPLES
+
+Create a failure node:
+
+```ts
+const failed = recordNodeError(node, {
+  code: "missing-required-evidence",
+  message: "Verifier stage requires evidence",
+  path: "/repo/.cw/runs/run/results/task.md",
+  retryable: true
+});
+```
+
+Link a verifier node to a commit node:
+
+```ts
+const [verifier, commit] = linkStateNodes(verifierNode, commitNode);
+```
+0.1.51