cool-workflow 0.1.78

package/docs/team-collaboration.7.md

@@ -0,0 +1,207 @@
+# Team Collaboration
+
+CW v0.1.32 adds Team Collaboration: a host-attested actor, append-only approvals,
+rejections, comments, and handoffs, and a review gate that STACKS ON the verifier
+gate. Before v0.1.32 there was no review/approval/comment/handoff/identity concept
+anywhere; the foundations already existed — trust-audit recorded every decision
+with an `actor`, candidate selection carried `selectedBy`, role policies existed,
+and commits were verifier-gated. This release adds the human-decision layer ON TOP
+of those mechanisms, without changing them and without taking ownership of source
+truth.
+
+The design follows the same base-system discipline as
+[Security / Trust Hardening](security-trust-hardening.7.md) and the
+[Verifier-Gated Commit](verifier-gated-commit.7.md):
+
+- the per-run `.cw/runs/<id>/state.json` is the SINGLE source of truth
+- collaboration records are an APPEND-ONLY log, never mutated in place
+- identity is ATTESTED provenance, never authenticated; CW is not an auth server
+- the review gate is POLICY layered on the verifier MECHANISM — never a bypass
+- fail closed: missing authority, ambiguous role, or self-approval is a denial
+- policy (required approvals, authorized roles, self-approval) is data, not kernel
+- backward compatible; every collaboration field is additive and optional
+
+## Identity is attested, not authenticated
+
+An `Actor` is host-attested provenance, not an authenticated principal. CW records
+WHO acted; it does not verify a password, a token, or a signature — that is a host
+trust-boundary concern. `normalizeActor` maps an actor input to one of three
+provenances: `host-attested` (the host vouched, `--attested`), `operator-recorded`
+(supplied unverified), or `unattributed` (no identity supplied). An absent identity
+becomes the explicit `unattributed` actor — `{ kind: "unattributed", id:
+"unattributed", attested: false }` — never a fabricated one. Spoofing is recorded
+honestly as whatever provenance the host attested, not hidden. This extends the
+existing trust-audit `actor` string and the v0.1.29/v0.1.31 attestation pattern.
+
+## Approvals and rejections are append-only and provenance-linked
+
+`approve` and `reject` append an `ApprovalRecord` to `run.collaboration.approvals`.
+Each record carries the actor, the decision, the durable target it attaches to, an
+optional rationale, the role the actor claims, and `auditEventIds` linking it to a
+`collaboration.approval`/`collaboration.rejection` event in the trust-audit log —
+exactly as `candidate.selection` records both a `CandidateSelection` and an audit
+event. The approved artifact (candidate/commit/selection) is NEVER edited in place:
+"who approved what" is a provenance link, not a field overwrite. A correction is a
+NEW record carrying `supersedes` (git-style); the superseded record stays in the
+log, no longer counts, and the original is unchanged.
+
+A target is one of `run | task | candidate | selection | commit | node`. "Who
+approved which candidate/commit" is answered by filtering the append-only records
+by target.
+
+## The review gate stacks on the verifier gate
+
+The verifier-gated commit is the MECHANISM (see
+[Verifier-Gated Commit](verifier-gated-commit.7.md)): `resolveCommitGate` accepts a
+commit only when a verified verifier node, a scored+verified candidate, and a
+complete acceptance rationale are present. A review gate is POLICY layered on top.
+`reviewGateErrors` runs INSIDE `resolveCommitGate`, AFTER the verifier checks, and
+can only ADD errors — required approvals from authorized roles — never remove the
+verifier's. The same call guards candidate selection in `selectCandidate`.
+
+Data flow for a gated commit:
+
+1. `resolveCommitGate` resolves the candidate/selection and runs every verifier
+   check; if any fail the commit is blocked as before.
+2. If a `ReviewGatePolicy` applies to `commit` (or `selection`), `reviewGateErrors`
+   derives the review state over the approvals targeting the commit AND its
+   underlying selection/candidate (you approve the candidate; the commit honors it).
+3. If the review state is not `approved`, a single `review-gate-missing-approvals`
+   StateNodeError is appended, listing exactly which approvals are missing.
+   `commitState` throws `CommitGateError`, recorded as append-only feedback.
+4. Only when BOTH gates pass is the commit written — and it is stamped with a
+   `CommitReviewProvenance` recording WHO approved the very artifact that shipped.
+
+Because the review errors are appended after the verifier errors and never replace
+them, an approval can never turn an unverified result into a committed one: an
+approved-but-unverified candidate is still blocked by the verifier gate.
+
+## Fail closed on authority and quorum
+
+`deriveReviewState` is a pure, deterministic projection of the append-only records
+plus a policy. It counts ONLY approvals that are, all at once: from an attested
+identity (when `requireAttestedActor`), from a role in `authorizedRoles` (or `*`),
+and not a self-approval (when `allowSelfApproval` is false; "self" is the
+candidate's producing worker and its selector). Distinct counted approvers must
+reach `requiredApprovals`. Anything short is not auto-passed; the status is:
+
+- `approved` — requirement met (or the target is not gated)
+- `pending` — gated, no blocking reject, fewer than required counted approvals
+- `blocked` — recorded approvals exist but none count (authority/self)
+- `unattributed` — the only recorded approvals are from unattributed actors
+- `rejected` — an authorized, attested reject is a blocking veto
+
+Every disqualified approval is surfaced with its reason (`unattributed`,
+`unauthorized-role`, `self-approval`, `superseded`), so a reader can audit why an
+approval did not count. A target requiring N approvals with fewer recorded is
+BLOCKED, and the block records exactly what is missing.
+
+## Comments and handoffs are state, not chat
+
+A `comment` appends a `CommentRecord` to a durable target with an actor, a thread
+id, and an audit link; threads are ordered by `createdAt` and never edited in
+place. A `handoff` appends a `HandoffRecord` — an explicit ownership transfer with
+a from-actor, a to-actor, and a reason — and the current owner of a run/task is
+DERIVED from the latest handoff, never an overwritten field. There is no side
+channel: the collaboration IS the durable, inspectable state, consistent with CW's
+no-hidden-dashboard-database rule.
+
+## Policy as data, kept out of the kernel
+
+`review policy <run-id>` writes a `ReviewGatePolicy` to `run.collaboration.policy`:
+`requiredApprovals` (0 = no gate), `authorizedRoles` (`*` = any), `allowSelfApproval`,
+`requireAttestedActor`, and `appliesTo` (target kinds). The default — absent policy
+or `requiredApprovals: 0` — requires no approvals, so pre-v0.1.32 runs and any run
+without a policy behave exactly as before. The policy is data; the kernel only
+enforces the mechanism.
+
+## One source, every surface
+
+Each collaboration verb is declared once in `src/capability-registry.ts`, so
+`cw <cmd> --json` is schema-identical to `cw_<cmd>` and passes the parity gate. The
+read-only `review status` and `comment list` are byte-for-byte identical across CLI
+and MCP (the payload-identity probe strips only ISO timestamps; the only
+now-derived field in a review report is `generatedAt`). The v0.1.30 Workbench
+renders the review timeline and per-target approval state read-only as a sixth
+panel, embedding the `review status` payload verbatim. The v0.1.31 metrics report
+adds derived approval-rate, time-to-approval, handoff-count, and reviewer-count,
+all from recorded timestamps — deterministic over a fixed snapshot.
+
+## Commands
+
+```
+cw review policy <run-id> --requiredApprovals N --authorizedRoles a,b --appliesTo commit,selection [--allowSelfApproval] [--requireAttestedActor]
+cw approve <kind> <run-id> <target-id> --actor <id> --role <role> --attested [--rationale <text>]
+cw reject  <kind> <run-id> <target-id> --actor <id> --role <role> --attested [--rationale <text>]
+cw comment add <kind> <run-id> <target-id> --actor <id> --body <text>
+cw comment list <run-id> [--json]
+cw handoff <kind> <run-id> [target-id] --from <id> --to <id> --reason <text>
+cw review status <run-id> [--json]
+```
+
+`<kind>` is one of `run | task | candidate | selection | commit | node`. Approve a
+candidate (or selection), then commit `--candidate`/`--selection`; the commit gate
+honors the candidate's approvals and records who approved the shipped commit.
+
+CW is the base system. Workflow apps are userland. Collaboration adds the human
+decision as durable, attested, append-only state — never a hidden dashboard, never
+a bypass of the verifier gate.
+
+## 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/unix-principles.md

@@ -0,0 +1,192 @@
+# Unix-Inspired Workflow Principles
+
+CW borrows a small set of durable systems ideas and applies them to agent
+workflow engineering. These are design principles, not platform claims.
+
+## 1. Everything Is State
+
+Every meaningful workflow event should be represented as inspectable state.
+
+CW already stores:
+
+- workflow runs in `.cw/runs/<run-id>/state.json`
+- task prompts in `.cw/runs/<run-id>/tasks/`
+- dispatch manifests in `.cw/runs/<run-id>/dispatches/`
+- result envelopes in `.cw/runs/<run-id>/results/`
+- state snapshots in `.cw/runs/<run-id>/commits/`
+- schedules in `.cw/schedules/tasks.json`
+- routine trigger events in `.cw/routines/`
+- candidate scoring records in `.cw/runs/<run-id>/candidates/`
+- commit gate failures in `.cw/runs/<run-id>/feedback/`
+- sandbox profile selections in worker, dispatch, feedback, and report state
+- 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
+- MCP app-surface smoke runs driven through stdio JSON-RPC
+
+The practical 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.
+
+## 2. Small Kernel, Composable Userland
+
+CW should keep the kernel small. The kernel owns state transitions and stable
+contracts; workflow apps own domain behavior.
+
+Core system calls:
+
+```text
+plan()
+dispatch()
+recordResult()
+verify()
+commit()
+report()
+sandbox()
+schedule()
+trigger()
+```
+
+The kernel should avoid hard-coded business logic. New behavior should usually
+enter as:
+
+- a workflow app
+- a workflow app manifest under `apps/<app-id>/app.json`
+- a verifier
+- a scheduler policy
+- 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.
+
+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.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 canonical apps are maintained userland:
+
+```text
+architecture-review
+pr-review-fix-ci
+release-cut
+research-synthesis
+```
+
+They keep domain prompts, inputs, evidence gates, and sandbox hints in app
+directories instead of in 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.
+
+## 3. Pipelines Over Monoliths
+
+CW favors explicit data flow over hidden orchestration.
+
+The standard pipeline is:
+
+```text
+workflow definition
+-> app contract validation
+-> validated input
+-> task files
+-> dispatch manifest
+-> worker result
+-> result envelope
+-> verifier gate
+-> verifier-gated commit or explicit checkpoint
+-> 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
+black box.
+
+Operator views follow the same rule: console summaries point to plain files,
+while `--json` and `--format json` preserve scriptable output.
+
+The release golden path is the regression form of this rule:
+
+```text
+npm run golden-path
+```
+
+It exercises the public CLI and then inspects state files for app metadata,
+dispatch, worker manifest, result node, verifier node, candidate score, ranking,
+selection, verifier-gated commit, report, and absence of ErrorFeedback.
+
+The canonical app matrix is the userland regression form:
+
+```text
+npm run canonical-apps
+```
+
+It validates and plans every maintained app without running full workers for
+each app.
+
+## 4. Isolated Workers
+
+Workers should be isolated by scope, state, and output.
+
+Useful isolation layers:
+
+- separate task prompts
+- separate result files
+- separate run directories
+- separate workspace or sandbox directories for risky work
+- 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.
+
+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.
+
+## 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.
+
+The preferred merge rule is:
+
+```text
+only verified state becomes committed state
+```
+
+For competing branches, 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.
+
+## 6. Practical Operating Rule
+
+```text
+The kernel provides deterministic pipes.
+Workers explore in isolation.
+Verifiers decide what may be committed.
+Hosts enforce runtime sandbox policy.
+```
+
+This keeps CW small, inspectable, and extensible.

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

@@ -0,0 +1,140 @@
+# VERIFIER-GATED-COMMIT(7)
+
+## NAME
+
+Verifier-Gated Commit - commit only state that passed an evidence-backed verifier
+
+## SYNOPSIS
+
+```text
+node dist/cli.js commit <run-id> --verifier <node-id> --reason "verified result"
+node dist/cli.js commit <run-id> --candidate <candidate-id> --reason "promote selected candidate"
+node dist/cli.js commit <run-id> --selection <selection-id> --reason "promote selected candidate"
+node dist/cli.js commit <run-id> --allow-unverified-checkpoint --reason "operator checkpoint"
+```
+
+```ts
+import { commitState } from "./commit";
+
+commitState(run, {
+  reason: "verified result",
+  verifierNodeId: `${run.id}:verifier:task-one`,
+  verifierGated: true
+});
+```
+
+## DESCRIPTION
+
+Verifier-Gated Commit is the CW rule that separates committed state from
+ordinary checkpoints:
+
+```text
+only verified state becomes committed state
+```
+
+A verifier-gated commit requires 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.
+
+## CHECKPOINTS
+
+CW still writes internal snapshots for planning, dispatch, result recording, and
+operator checkpoints. These records are checkpoints. They are useful for audit,
+resume, and rollback, but they are not verifier-gated committed state.
+
+Checkpoint records have:
+
+```json
+{
+  "verifierGated": false,
+  "checkpoint": true
+}
+```
+
+Checkpoint state nodes use `kind: "commit"` and `status: "completed"`. A
+verifier-gated commit state node uses `status: "committed"`.
+
+## COMMIT RECORDS
+
+A verifier-gated commit records gate metadata in the commit JSON and state node:
+
+```json
+{
+  "verifierGated": true,
+  "checkpoint": false,
+  "verifierNodeId": "run:verifier:task",
+  "candidateId": "candidate-one",
+  "selectionId": "selection-candidate-one-...",
+  "evidence": []
+}
+```
+
+The `candidateId` and `selectionId` fields are present when the commit promotes
+a candidate or candidate selection. The `evidence` field is copied from the
+verifier node.
+
+## FILES
+
+```text
+.cw/runs/<run-id>/state.json
+.cw/runs/<run-id>/commits/<commit-id>.json
+.cw/runs/<run-id>/nodes/<commit-node-id>.json
+.cw/runs/<run-id>/feedback/<feedback-id>.json
+.cw/runs/<run-id>/report.md
+```
+
+Every blocked commit attempt records an `error` state node and an ErrorFeedback
+record before the command exits.
+
+## FAILURE MODES
+
+The commit gate fails closed.
+
+Common feedback codes:
+
+```text
+commit-verifier-required
+commit-verifier-not-found
+commit-verifier-wrong-kind
+commit-verifier-not-verified
+commit-verifier-missing-evidence
+commit-candidate-not-found
+commit-candidate-not-selectable
+commit-candidate-unscored
+commit-candidate-not-verified
+commit-candidate-selection-missing
+commit-selection-not-found
+commit-selection-node-missing
+commit-selection-not-verified
+commit-verifier-linkage-mismatch
+```
+
+Use `cw.js feedback list <run-id>` and `cw.js node graph <run-id>` to inspect
+the failed transition.
+
+## CANDIDATES
+
+A candidate can become committed state only after selection passes the verifier
+gate. Rejected, failed, unscored, unselected, or unverified candidates are
+blocked.
+
+The normal candidate path is:
+
+```text
+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
+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
+the operator passes `--allow-unverified-checkpoint`.
+0.1.51