cool-workflow 0.1.78

package/docs/agent-delegation-drive.7.md

@@ -0,0 +1,190 @@
+# Agent Delegation Drive
+
+CW v0.1.38 adds Agent Delegation Drive: a way to run a natural-language-prompt
+workflow **end-to-end by DELEGATING each worker to an EXTERNAL agent process**
+(`claude -p` headless, `codex exec`, or a configured HTTP agent endpoint),
+capturing each worker's `result.md` plus an attestation of which agent/model
+produced it. It turns the `architecture-review` app into CW's first turnkey,
+evidence-audited product: point CW at a repo, get an audited risk report — with
+no human hand-writing any `result.md`.
+
+Before v0.1.38, CW could `plan` a workflow, isolate workers, and accept their
+output, but **nothing spawned the agent that wrote each `result.md`**. Running
+`architecture-review` end-to-end meant an operator hand-writing all 14 worker
+result files out-of-band, with no recorded attestation of which agent/model
+produced each. The new `agent` backend + `run --drive` loop close that last mile.
+
+## The red line — delegate, do not internalize
+
+CW **DELEGATES, IT DOES NOT BECOME THE EXECUTOR.** The `agent` backend does the
+same thing the `container`/`remote`/`ci` backends do: it `spawnSync`s an
+out-of-process child (the agent CLI, argv-style, `shell:false`) or POSTs to a
+configured endpoint, then records a `BackendExecutionHandle` (`kind: "process"`)
++ a `SandboxAttestation` + the canonical result envelope. **The model runs in the
+agent's process, never inside CW.** CW imports no model SDK, holds no API key,
+constructs no chat/completions request, and calls no model HTTP API. Any API key
+flows from the agent's *own* inherited env; CW never reads or records it. Adding a
+provider SDK to `package.json` would lose the neutral-audit moat and is the red
+line.
+
+## Operator-chosen model is policy; agent-reported model is the attestation
+
+Any model id CW passes **into** the agent invocation (`CW_AGENT_MODEL`
+interpolated into `{{model}}`) is **policy-as-data the operator chose**. It is
+recorded only as part of the secret-stripped command-template/args provenance and
+is **never** the source of the attested `UsageRecord.model`. The recorded/attested
+model id comes solely from what the external agent reports back in its output. If
+the agent reports no model, CW records `unreported` — it never backfills from
+`CW_AGENT_MODEL`. A configured `CW_AGENT_MODEL` that differs from the agent's
+reported model does not overwrite the host-reported model id.
+
+## Two layers, never conflated
+
+1. **Backend evidence triple.** `runAgentProcess` records the agent CHILD's
+   `command` + `exitCode` + `sha256(stdout)` — the identical mechanism
+   `runContainer`/`runHttpDelegation` use. This triple is byte-stable in SHAPE
+   across `node`/`container`/`remote`/`ci`/`agent`. It NEVER reads, parses, or
+   hashes a `result.md`.
+2. **`result.md` acceptance.** The worker's `result.md` `cw:result` envelope is
+   accepted in a SEPARATE layer (`recordWorkerOutput`), which validates it, copies
+   it into `resultsDir`, runs the verifier gate, and records trust-audit +
+   provenance — unchanged by this feature.
+
+The agent handle (`kind: "process"`), the agent-reported model id, the prompt
+digest, the secret-stripped args, and the result digest live in `provenance` and
+the `worker.agent-delegation` trust-audit event — **never in `evidence`**.
+
+## The drive lifecycle
+
+`run --drive` is a thin orchestrator over the EXISTING verbs + the v0.1.37
+scheduler. For each worker the planner emits, in deterministic phase/dispatch
+order:
+
+```
+plan -> dispatch -> agent-fulfill (agent backend) -> recordWorkerOutput/verify -> commit
+```
+
+- **dispatch** allocates the worker scope (`input.md` + manifest; the worker's own
+  sandbox profile, e.g. `readonly`).
+- **agent-fulfill** delegates the worker to the `agent` backend out-of-process; the
+  agent reads the input/manifest and writes `result.md`; CW captures the child's
+  evidence triple + reported model.
+- **accept** records + verifies `result.md`; the agent-hop attestation is folded
+  into the result node's metadata (so the v0.1.35 replay engine covers it).
+- **commit** is verifier-gated on the Verdict node once every worker completes.
+
+The Verdict `artifact` node is fulfilled through the SAME agent backend — it is a
+worker scope with a `result.md` like any other. `--drive --once` advances exactly
+one deterministic step (injected `now`); bare `--drive` runs to completion or to a
+parked/blocked stop. `run drive <run-id>` (no `--step`) is the read-only,
+deterministic preview of the next step.
+
+## Fail closed — probe vs refusal vs park
+
+- **Probe.** `backend probe agent` reports `readiness: "ready"` iff a
+  command-template/endpoint is configured; otherwise `readiness: "unverified"`,
+  `ready: false`, with a non-empty reason — byte-identical in shape to
+  `backend probe remote` unconfigured. It is NEVER a hard `refused`/`unavailable`.
+- **runBackend.** Unconfigured execution (no command-template AND no endpoint)
+  returns a `delegation-target-missing` refusal — never a fabricated `completed`.
+- **Failed hop.** A spawned agent that exits non-zero, returns no exit code,
+  produces no `result.md`, or produces a `result.md` that fails validation yields a
+  `refused`/`failed` envelope (or a rejected accept) — never a fabricated
+  completion.
+- **Park.** In the drive loop, a worker whose agent hop keeps failing exhausts its
+  scheduling retry budget and lands **parked** (reuse v0.1.37 `retryOrPark`) — the
+  drive stops; it is never silently re-driven forever.
+
+## Replay determinism (bound to node-snapshot)
+
+The attested record (model id, prompt digest, args, result digest, exit) is plain
+data folded into the snapshotted node body. Replaying a recorded drive run via
+`snapshotNode`/`replayNodeSnapshot`/`verifyNodeReplay` reproduces the SAME
+audit/provenance graph and the same recorded digests, **without re-spawning the
+agent or re-reading the live `result.md`** — even with the agent binary
+unavailable. Two replays with different injected `now` are byte-identical in body
++ `sourceFingerprint`/`outputFingerprint`.
+
+## Vendor neutrality + durable config
+
+WHICH agent (claude / codex / ollama / an HTTP endpoint) is **policy expressed as
+DATA** — a command-template and/or endpoint resolved flags > env
+(`CW_AGENT_COMMAND` / `CW_AGENT_ENDPOINT` / `CW_AGENT_MODEL`) > a durable
+`$CW_HOME/agent-config.json`. claude / codex / ollama are CONFIGS, never CW
+dependencies. No secrets are written into the config or `.cw/`: it holds a
+command-template + endpoint + operator-chosen model only; recorded command/args
+are secret-stripped.
+
+## CLI
+
+```text
+# configure the agent (policy as data; no API key is ever written)
+# the bundled wrapper feeds input.md to headless claude READ-ONLY, persists
+# result.md itself, and forwards claude's JSON (model+usage) for provenance.
+# A bare "claude -p" or "claude -p {{input}}" does NOT complete a worker:
+# headless claude gets no prompt content / cannot write result.md without it.
+node dist/cli.js backend agent config set --agent-command "node $(pwd)/scripts/agents/claude-p-agent.js {{input}} {{result}}" --agent-model claude-opus-4-8
+node dist/cli.js backend agent config            # show the effective config (secret-stripped)
+node dist/cli.js backend probe agent --json      # ready iff configured, else unverified
+
+# drive a real repo end-to-end (zero hand-written result.md)
+node dist/cli.js run architecture-review --drive --repo /path/to/repo --question "Is the design sound?"
+node dist/cli.js run architecture-review --drive --once --repo /path/to/repo --question "..."   # one step
+node dist/cli.js run drive <run-id> --json       # read-only preview of the next step
+```
+
+`{{manifest}}`, `{{input}}`, `{{result}}`, `{{workerDir}}`, `{{model}}`, and
+`{{prompt}}` are substituted into DISCRETE argv elements (never a shell-interpreted
+string). Each verb is declared once in `capability-registry.ts`, so `cw <cmd>
+--json` is byte-identical to the matching `cw_<tool>` MCP tool for the read-only
+preview/config-show verbs.
+
+## Compatibility
+
+Agent Delegation Drive is introduced in CW v0.1.38. Adding the `agent` row leaves
+`node`/`bun`/`shell`/`container`/`remote`/`ci` byte-identical; `backendIds()`
+simply grows by one to the sorted 7-row set
+`["agent","bun","ci","container","node","remote","shell"]`. A run driven manually
+(plan → dispatch → `worker output` → commit) still works unchanged. Fields are
+additive and optional; older run state loads unchanged. No `.cw/` layout change.
+
+## See Also
+
+execution-backends(7), real-execution-backends(7), node-snapshot-diff-replay(7),
+control-plane-scheduling(7), dogfood-one-real-repo(7), cli-mcp-parity(7),
+observability-cost-accounting(7)
+
+## 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/agent-framework.md

@@ -0,0 +1,176 @@
+# Workflow App framework
+
+CW is designed as an independent agent workflow control-plane.
+
+The goal is to make agent development feel like building inside a platform
+ecosystem. CW provides the runtime, contracts, storage, CLI, MCP bridge, and
+package structure. Developers write workflow apps against those contracts.
+
+The framework is guided by five practical systems principles: small kernel, explicit
+state, composable pipes, isolated workers, and verifier-gated commits. See
+[unix-principles.md](unix-principles.md).
+
+## Platform Contract
+
+Every CW workflow follows this loop:
+
+```text
+interpret -> act -> observe -> adjust -> checkpoint
+```
+
+The loop maps to concrete framework operations:
+
+| Loop stage | framework operation | Responsibility |
+| --- | --- | --- |
+| Interpret | `plan()` | Load workflow, validate inputs, generate tasks |
+| Act | `dispatch()` | Move runnable tasks from pending to running |
+| Observe | `recordResult()` | Read Markdown/JSON-RPC result evidence |
+| Adjust | verifier gates | Validate evidence and choose the next phase |
+| Checkpoint | `commitState()` | Snapshot state after important transitions |
+
+The v0.1.12 operator UX layer renders read-only summaries over run state:
+human `status`, graph maps, report summaries, resource summaries, and
+deterministic next-step recommendations. Scripts can keep using `--json` or
+`--format json`.
+
+The v0.1.13 MCP app surface exposes the same runtime operations to agent hosts
+with stable JSON tools: app run, dispatch, worker inspection/output, candidate
+scoring/selection, sandbox profile resolution, verifier-gated commit, and
+operator status/graph/report summaries.
+
+The v0.1.13 canonical app matrix validates and plans the maintained userland
+apps with public CLI commands:
+
+```bash
+npm run canonical-apps
+```
+
+The golden path runs the full integration chain end to end:
+
+```bash
+npm run golden-path
+```
+
+It validates an app, plans a run, dispatches a readonly worker, accepts a
+worker-local `cw:result`, scores and selects a candidate, creates a
+verifier-gated commit, and renders a report. See
+[end-to-end-golden-path.7.md](end-to-end-golden-path.7.md).
+
+## Developer Contract
+
+A workflow app defines:
+
+- `id`, `title`, and `summary`
+- `schemaVersion`, app `version`, compatibility, and metadata when using the
+  first-class Workflow App framework contract
+- required and repeated inputs
+- phase order
+- agent tasks
+- artifact tasks
+- concurrency limits
+- evidence requirements
+- sandbox profile hints
+
+Example:
+
+```js
+const {
+  defineWorkflowApp,
+  workflow,
+  phase,
+  agent,
+  artifact,
+  input
+} = require("../dist/workflow-app-framework");
+
+const inputs = [input("repo", { type: "path", required: true })];
+
+module.exports = defineWorkflowApp({
+  schemaVersion: 1,
+  id: "example-review",
+  title: "Example Review",
+  summary: "Review a repository with evidence.",
+  version: "0.1.0",
+  inputs,
+  sandboxProfiles: ["readonly"],
+  compatibility: {
+    minVersion: "0.1.9"
+  },
+  workflow: workflow({
+    id: "example-review",
+    title: "Example Review",
+    inputs,
+    sandboxProfiles: ["readonly"],
+    phases: [
+      phase("Map", [
+        agent("map:system", "Map the system boundaries.", {
+          sandboxProfileId: "readonly"
+        })
+      ]),
+      phase("Verdict", [
+        artifact("verdict", "Write the final evidence-backed verdict.", {
+          requiresEvidence: true,
+          sandboxProfileId: "readonly"
+        })
+      ])
+    ]
+  })
+});
+```
+
+Legacy `module.exports = ({ workflow, phase, agent, artifact }) => workflow(...)`
+files remain loadable. CW wraps them as compatibility apps with version `0.0.0`
+so workflow files still plan and dispatch. When a canonical app owns the public
+id, compatibility wrappers use explicit ids such as `legacy-research-synthesis`.
+
+## Language Contract
+
+The CW platform is TypeScript:
+
+```text
+src/*.ts -> dist/*.js
+```
+
+Workflow apps are JavaScript modules:
+
+```text
+workflows/*.workflow.js
+apps/<app-id>/app.json
+apps/<app-id>/workflow.js
+```
+
+This is intentional. The runtime is strongly typed for maintainability, while
+workflow scripts can run without `ts-node`.
+
+See [workflow-app-framework.7.md](workflow-app-framework.7.md) for the full app contract,
+validation rules, CLI commands, MCP tools, and state/report fields.
+See [mcp-app-surface.7.md](mcp-app-surface.7.md) for the agent-host runtime
+surface over MCP.
+See [operator-ux.7.md](operator-ux.7.md) for the operator inspection surface.
+See [canonical-workflow-apps.7.md](canonical-workflow-apps.7.md) for the
+official app matrix.
+See [end-to-end-golden-path.7.md](end-to-end-golden-path.7.md) for the
+deterministic release proof that those pieces connect.
+
+## Evidence Contract
+
+Verification and verdict tasks should return:
+
+````text
+```cw:result
+{
+  "summary": "short summary",
+  "findings": [],
+  "evidence": ["/absolute/path/file.ts:42"]
+}
+```
+````
+
+CW rejects high-priority findings without evidence. This keeps agent work closer
+to inspectable engineering output than unconstrained conversation.
+
+## Boundary
+
+CW is an independent workflow control-plane by COOLWHITE LLC. It implements dynamic workflows,
+scheduled tasks, local scheduling, routine triggers, state checkpoints, and
+multi-agent verification.

package/docs/candidate-scoring.7.md

@@ -0,0 +1,106 @@
+# CANDIDATE-SCORING(7)
+
+## NAME
+
+Candidate Scoring - inspectable decision support for competing CW outputs
+
+## SYNOPSIS
+
+```ts
+import {
+  registerCandidate,
+  scoreCandidate,
+  rankCandidates,
+  selectCandidate
+} from "./candidate-scoring";
+
+registerCandidate(run, { workerId, taskId, resultNodeId, verifierNodeId });
+scoreCandidate(run, candidateId, {
+  scorer: "verifier",
+  criteria: { correctness: 4, evidence: 4, fit: 2 },
+  maxTotal: 10,
+  evidence: [{ id: "score:evidence", source: "test", locator: "test/file.js:1" }]
+});
+rankCandidates(run);
+selectCandidate(run, candidateId);
+```
+
+```text
+node dist/cli.js candidate register <run-id> --worker <worker-id>
+node dist/cli.js candidate score <run-id> <candidate-id> --criterion correctness=4 --evidence path:line
+node dist/cli.js candidate rank <run-id>
+node dist/cli.js candidate select <run-id> <candidate-id>
+```
+
+## DESCRIPTION
+
+Candidate Scoring is the small decision-support layer between isolated worker
+outputs, result nodes, verifier evidence, candidate scores, selected winners,
+ErrorFeedback, and commit/report.
+
+It does not merge code, replace verifier judgment, spawn workers, or provide a
+domain-specific ranking policy. A score is evidence, not authority.
+
+The normal flow is:
+
+```text
+worker output -> candidate record -> score record -> ranking
+-> verifier-gated selection -> checkpoint/report
+```
+
+Each step writes plain JSON. Rejected and failed candidates remain inspectable.
+
+## FILES
+
+```text
+.cw/runs/<run-id>/candidates/index.json
+.cw/runs/<run-id>/candidates/ranking.json
+.cw/runs/<run-id>/candidates/<candidate-id>/candidate.json
+.cw/runs/<run-id>/candidates/<candidate-id>/scores/<score-id>.json
+.cw/runs/<run-id>/candidates/selections/<selection-id>.json
+.cw/runs/<run-id>/nodes/
+.cw/runs/<run-id>/feedback/
+.cw/runs/<run-id>/report.md
+```
+
+Candidate records point at existing worker, result, verifier, and artifact
+paths. They do not copy large worker outputs by default.
+
+## SELECTION GATE
+
+Selection is conservative by default:
+
+- score records require evidence
+- selection requires a linked verifier node with `verified` status
+- selection failures become ErrorFeedback records
+- rejected candidates remain on disk
+
+Operators can record an unverified selection only with an explicit option. That
+records selection state but does not turn the candidate into committed state.
+
+Committed state has a stricter rule. A candidate can be promoted by
+`cw.js commit --candidate` or `cw.js commit --selection` only when it has score
+evidence, a verified selection, and a linked verifier node with evidence.
+Rejected, failed, unscored, unselected, and unverified candidates are blocked
+and produce ErrorFeedback.
+
+## FAILURE MODES
+
+Missing score evidence fails scoring and records feedback.
+
+Selecting a failed or rejected candidate fails and records feedback.
+
+Selecting without a verified verifier node fails unless explicitly allowed.
+
+Tie-breaking is predictable: higher normalized score wins; equal scores use the
+configured tie breaker, defaulting to earlier candidate creation time.
+
+## COMPATIBILITY
+
+Candidate Scoring is introduced in CW v0.1.6. It adds optional candidate paths
+and arrays to run state. Older runs remain readable because missing candidate
+fields are initialized when state loads.
+
+Existing workflow, worker, feedback, node, contract, result, commit, and report
+commands remain compatible.
+0.1.51

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

@@ -0,0 +1,137 @@
+# 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
+directory:
+
+```text
+apps/<app-id>/app.json
+apps/<app-id>/workflow.js
+```
+
+The runner remains the base system. Canonical apps carry domain behavior:
+inputs, phases, task prompts, evidence gates, sandbox profile hints, and app
+metadata.
+
+## Apps
+
+`architecture-review`
+
+Map a repository architecture, assess risks, verify important findings, and
+synthesize an evidence-backed verdict.
+
+```bash
+node scripts/cw.js plan architecture-review \
+  --repo /path/to/repo \
+  --question "Is this architecture sound?" \
+  --invariant "public API stays stable" \
+  --focus "runtime"
+```
+
+`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.
+
+```bash
+node scripts/cw.js plan pr-review-fix-ci \
+  --repo /path/to/repo \
+  --pr 123 \
+  --base main \
+  --ci "unit-tests" \
+  --mode review
+```
+
+`release-cut`
+
+Prepare a release with checklist discipline: version checks, changelog, tests,
+packaging, release notes, and final verification.
+
+```bash
+node scripts/cw.js plan release-cut \
+  --repo /path/to/repo \
+  --version 0.1.13 \
+  --previousVersion 0.1.11 \
+  --dryRun true
+```
+
+`research-synthesis`
+
+Split a research question into claims, investigate sources, cross-check
+evidence, verify claims, and synthesize a concise answer.
+
+```bash
+node scripts/cw.js plan research-synthesis \
+  --cwd /tmp/research-run \
+  --question "What does the evidence support?" \
+  --source "official-docs" \
+  --scope "local sources first" \
+  --freshness "as of today"
+```
+
+## Validation Matrix
+
+Run the canonical app matrix from the plugin root:
+
+```bash
+cd plugins/cool-workflow
+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
+evidence-required verification or synthesis/verdict tasks, checks sandbox
+profile hints, checks unique task ids, and checks duplicate ids do not break
+discovery.
+
+`npm test` includes `test/canonical-workflow-apps-smoke.js`, which repeats the
+same core assertions against generated `dist/`.
+
+## Framework Pressure
+
+The apps intentionally stress different parts of the Workflow App framework:
+
+- declared 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
+- deterministic planning into temporary workspaces
+- 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
+compatibility ids:
+
+```text
+legacy-architecture-review
+legacy-research-synthesis
+```
+
+The public `architecture-review` and `research-synthesis` ids are now owned 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 golden-path` remains 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.
+
+Use the Operator UX commands to inspect any canonical app run:
+
+```bash
+node scripts/cw.js status <run-id>
+node scripts/cw.js graph <run-id>
+node scripts/cw.js report <run-id> --summary
+```
+0.1.51