cool-workflow 0.1.96 → 0.1.98

package/docs/designs/handoff-ledger.md

@@ -0,0 +1,145 @@
+# Design — Cross-agent handoff ledger
+
+Status: DRAFT / proposal. Nothing here is built yet. This file ships no
+behavior, no new command, no man-page contract, and changes no existing
+output. It exists so two people (the operator and the reviewer agent) can
+agree on the shape before any code is written.
+
+North Star track: **Track B** (portable, verifiable state — the same
+`run export` → `run restore` recovery story, now used as the channel
+between two agents).
+
+## Goal
+
+Two agents work on two repositories:
+
+- one agent scoped to repo **A** (for example `cool-workflow`),
+- one agent scoped to repo **B** (for example `chime`).
+
+The operator wants them to "share data, review each other, and each be
+able to raise a pull request to the other". In plain terms:
+
+- each side can hand the other a **change proposal**, and
+- each side can hand the other a **review verdict** on a diff or PR,
+- with saved, inspectable, fail-closed state — never a fabricated hand-off.
+
+## The hard constraint (why the obvious design does not work)
+
+The first idea is a shared local folder (for example `~/.chime/handoff/`)
+that both agents read and append to. That only works when both agents run
+on **one machine** with **one filesystem**.
+
+In the operator's setup the two agents run as **two separate cloud
+sessions**. Each session is a fresh, throwaway VM. Two facts follow, and
+the design must respect both:
+
+1. **No shared filesystem.** A file the B-agent writes to `~/.chime/handoff/`
+   in its VM is invisible to the A-agent's VM, and is gone when the session
+   ends. A local folder cannot be the channel.
+2. **Single-repo scope.** Each session's GitHub reach is scoped to one repo
+   at launch (A-agent → repo A, B-agent → repo B). The A-agent cannot read
+   repo B through its GitHub tools, and the reverse is also true. Scope is
+   fixed at launch and cannot be widened mid-session.
+
+The only medium both sessions can durably reach is **git / GitHub**. So the
+ledger is a set of committed files, not a local folder — and the scope wall
+means the hand-off still needs either a shared repo or a human relay for the
+cross-repo step. This document is honest about that; it does not pretend the
+wall is not there.
+
+## What we reuse (no new trust machinery)
+
+CW already has the parts this needs. The design adds a thin verb layer over
+them; it invents no new crypto and no new state format.
+
+- `run export` produces a **verifiable bundle** (file digests, telemetry
+  ledger, trust-audit hash chains).
+- `run restore` **imports fail-closed**: it inspects first, refuses a corrupt
+  or tampered bundle without writing anything, and exits non-zero when the
+  chain does not verify. (`run import` is the exit-0 sibling; the hand-off
+  path must use the fail-closed `restore` contract.)
+- `report verify` checks a run's evidence and citations.
+
+A hand-off entry is therefore just a CW bundle. The receiving side trusts it
+the same way it trusts any restored run: by verification, not by good faith.
+
+## Two verbs
+
+Both live under a single new `cw ledger` verb, so the existing surface is
+untouched and the new behavior is opt-in (POLA). (The name `handoff` was already
+taken by an unrelated collaboration primitive — ownership transfer of a run/task
+— so the cross-agent verb is `ledger`, not `handoff`.) Stage 1 ships as
+`cw ledger propose|review|verify`; see
+[cross-agent-ledger](../cross-agent-ledger.7.md) for the contract.
+
+- **`propose`** — the read-only side writes a structured *change proposal*
+  (title, rationale, target files, suggested diff) as a ledger entry. It does
+  **not** mutate the other repo. The write-capable side picks the entry up,
+  verifies it, and turns it into a **real GitHub pull request**.
+- **`review`** — the reviewing side writes a structured *review verdict*
+  (`APPROVED` / `REJECTED`, findings, the diff or PR it judged) as a ledger
+  entry. The other side surfaces it and can act on it.
+
+This keeps a read-only agent honest: it emits proposals and verdicts as
+**data**, and the write-capable side is the only one that opens PRs. Neither
+side has to be trusted to have mutated the other's code.
+
+## Transports (how an entry actually crosses)
+
+The verbs above produce and consume entries; the transport is how an entry
+moves from one VM to the other. Two are in scope, smallest first.
+
+- **T1 — Human relay (MVP, works today, zero infra).** The producing side
+  prints the entry (a verifiable bundle, or its safe text form) to stdout;
+  the operator carries it to the other session; the consuming side verifies
+  it fail-closed and acts (opens the PR, or records the verdict). This is
+  exactly the loop the operator is already running by hand. It needs no new
+  code beyond a stable print/parse shape.
+- **T2 — Git-as-ledger.** Each entry is committed to a repo under a known
+  path (for example `handoff/<from>-<to>/<id>.bundle`). Because scope is
+  single-repo, this needs one of:
+  - **T2a — a shared handoff repo** both agents are scoped to (cleanest, but
+    the operator must create it and launch both sessions against it), or
+  - **T2b — each side writes to its own repo** and a bridge (the operator, or
+    a scheduled job that *is* scoped to both) moves entries across. The
+    cross-repo read cannot be automatic inside a single scoped session — this
+    is the scope wall, stated plainly, not a gap to be quietly filled.
+
+## Fail-closed rules (non-negotiable)
+
+- An entry that does not verify is **refused**, never acted on. No PR is
+  opened, no verdict is recorded, and the refusal is explicit on stderr with
+  a non-zero exit — the same contract as `run restore`.
+- A proposal is a **suggestion only**. It never edits the target repo by
+  itself; a human-or-agent on the write side always makes the real PR, so the
+  read-only vow of the proposing side holds.
+- stdout stays data (the entry / the machine result); stderr stays
+  diagnostics; a piped run is silent on success. `--json` is stable and
+  decoration-free.
+
+## Non-goals / POLA
+
+- No existing command, output byte, exit code, or file layout changes.
+- No new runtime dependency (zero-dependency red line holds).
+- No vendor-specific logic in core; the verbs move opaque bundles.
+- Nothing ships until its own cycle lands with a test that fails before and
+  passes after, and a `docs/*.7.md` contract page — this design file is not
+  that contract and claims no shipped behavior.
+
+## Suggested rollout (each stage its own reviewed cycle)
+
+0. **This design doc** (no behavior). ← you are here.
+1. **T1 human-relay shape** — a stable, documented print/parse form for a
+   proposal and a verdict, plus a smoke that round-trips one of each and
+   proves a tampered entry is refused.
+2. **`cw ledger propose` / `review`** over `run export` / `restore`, with the
+   fail-closed refusal test.
+3. **T2 git-ledger** (shared-repo first), then optionally a scoped bridge job
+   for T2b.
+
+## Open decisions for the operator
+
+- T2a (shared handoff repo) or T2b (own repos + bridge)? T2a is simpler and
+  should be the default unless a shared repo is not acceptable.
+- Should a verdict be able to **block** a PR merge on the other side, or only
+  advise? Advise-only is the safer default and matches "review as data".

package/docs/doctor.7.md

@@ -0,0 +1,97 @@
+# DOCTOR(7)
+
+## NAME
+
+`cw doctor` — check the setup and name all problems with their fixes
+
+## SYNOPSIS
+
+```text
+node dist/cli.js doctor
+node dist/cli.js doctor --json
+node dist/cli.js doctor --fix
+node dist/cli.js doctor --onramp
+node dist/cli.js doctor --onramp --changed-from origin/main
+```
+
+## DESCRIPTION
+
+`cw doctor` is a read-only check of your CW setup, based on `brew doctor`. It
+probes your machine and says what is wrong and what to do about it — before a
+run fails with a strange error.
+
+The command never makes any file; it only reads. Running it changes nothing on
+disk.
+
+It gives back a report with one line for every check. Each check has a status
+(`ok`, `warn`, or `fail`) and a clear note. Checks that are not `ok` carry a
+`fix` line with the right command or step to put things right.
+
+If any check has status `fail`, the command exits with code 1 (non-zero). A
+`warn` (for example, no agent yet — demos and previews still work) does not
+make the exit fail.
+
+## CHECKS
+
+The command runs six checks in order:
+
+**node**
+: The Node.js version. CW needs v18 or higher. A `fail` here stops everything.
+
+**agent**
+: The AI agent backend. CW can auto-detect agents (Claude, Codex, Gemini,
+OpenCode) or take one from `CW_AGENT_COMMAND` / `--agent-command`. Without one,
+real runs report `status: blocked`, but `demo` and `--preview` still work.
+
+**agent-binary**
+: When the agent is set by a command name (not auto or HTTP), this check sees if
+the binary is on `$PATH`. Missing here gives a `warn` — the run will get a clear
+error later, but CW will not guess at a different agent.
+
+**git**
+: The `git` command. CW uses it for commit place of origin. A `warn` here means
+commit roots will be recorded as absent; no other part of a run needs git.
+
+**home-registry**
+: The cross-repo run index at `$CW_HOME` (default `$HOME/.local/state/cool-workflow`).
+This location must be writable. A `fail` here blocks discovery across repos.
+
+**repo-state**
+: The per-repo run store under `<cwd>/.cw`. Must be writable. A `warn` here
+means runs stay in-memory only — you can use `--cwd PATH` to point at another
+writable root.
+
+## OPTIONS
+
+`--json`
+: Give back the full report as a stable JSON object. Good for scripts.
+
+`--fix`
+: Give back only the fix commands for every non-ok check. Same as running `cw fix`
+by itself.
+
+`--onramp`
+: Add a quick-start guide to the human output, with recommended checks and a
+three-step path to your first report.
+
+`--changed-from <ref>`
+: When used with `--onramp`, make the quick-start checks cover only files changed
+since `<ref>` (a Git branch, tag, or commit). Good for CI and code reading.
+
+## FILES
+
+```text
+src/doctor.ts
+dist/doctor.js
+```
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | All checks ok (may have warnings) |
+| 1 | One or more checks have status `fail` |
+
+## SEE ALSO
+
+cw fix — the same checks, but gives back only the fix commands

package/docs/durable-state-and-locking.7.md

@@ -152,3 +152,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/evidence-adoption-reasoning-chain.7.md

@@ -313,3 +313,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/execution-backends.7.md

@@ -343,3 +343,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/fix.7.md

@@ -0,0 +1,44 @@
+# FIX(7)
+
+## NAME
+
+`cw fix` — give back the fix commands for all setup problems
+
+## SYNOPSIS
+
+```text
+node dist/cli.js fix
+node dist/cli.js fix --json
+```
+
+## DESCRIPTION
+
+`cw fix` runs the same setup checks as `cw doctor`, but gives back only the
+fix commands — one numbered step for every check that has a problem. No
+running check detail, no status glyphs; just the directions you need to put
+things right.
+
+When the output is empty ("No fixes needed."), the setup is clean and nothing
+needs doing.
+
+Like `cw doctor`, the command only reads — it never makes a file or does a
+fix on its own. You are meant to run the fix commands yourself.
+
+If any check has status `fail`, the command exits with code 1.
+
+## OPTIONS
+
+`--json`
+: Give back the full doctor report as a stable JSON object, with the same shape
+as `cw doctor --json`. The `checks` array carries every fix string.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | No fixes needed — all checks ok or only warnings |
+| 1 | One or more checks have status `fail` |
+
+## SEE ALSO
+
+cw doctor — the full setup check with detail for every check

package/docs/handoff-setup.md

@@ -0,0 +1,120 @@
+# Handoff ledger — shared-repo setup (T2a)
+
+How to stand up the shared repo that carries `cw ledger` entries between two
+agents scoped to two separate repos (e.g. `cool-workflow` and `chime`), each
+running in its own cloud session. The verbs are documented in
+[cross-agent-ledger](cross-agent-ledger.7.md); this is the operator runbook.
+
+Examples are portable — replace `<owner>`, `<src-repo>`, and the paths with your
+own, and keep tokens in environment variables, never in files or commit text.
+
+## What only the operator can do
+
+- A cool-workflow-scoped web session cannot create the shared repo — the GitHub
+  integration returns `403 Resource not accessible by integration` for any repo
+  outside its scope. Create it yourself.
+- Scoping the two agent environments (or granting them git credentials) is a
+  Claude Code web-UI step; it cannot be done from inside a session.
+
+## Choosing a host: GitHub vs self-hosted (Gitea)
+
+The transport is git-host-agnostic — the kernel has no git logic, so any git
+remote works. The choice is about reachability and operations, not code.
+
+| | GitHub (private repo) | Self-hosted Gitea (your VPS) |
+|---|---|---|
+| Reachability from cloud sessions | github.com is in the default **Trusted** allowlist — works with no network-policy change | Your VPS host is **not** in the default allowlist — the environment's network access must be configured to permit it |
+| Scope wall | The GitHub MCP scope is per-repo; the ledger uses plain git (not MCP) so it works, but it runs against the grain of the scoping model | Not a GitHub repo at all, so the GitHub scope wall does not apply |
+| Limits / quota | Disable Actions on this repo (it needs no CI) so it burns no minutes; git push/pull is not API-rate-limited; ledger traffic is tiny | Fully self-controlled, unlimited |
+| Operations | Managed, backed up, zero maintenance | You run it: uptime, backups, TLS cert, patching |
+| Data location | GitHub's servers (private) | Your own hardware |
+
+**Recommendation.** Start on **GitHub private** — it is reachable out of the box
+and the quota worry is practically moot for tiny ledger traffic. Move to **Gitea**
+if you want full self-hosting AND have confirmed the cloud environment can reach
+your VPS through its network policy (the deciding prerequisite). Migrating later
+is only a change of git remote — no code change.
+
+## GitHub private — setup
+
+1. **Token.** GitHub → Settings → Developer settings → Personal access tokens →
+   Fine-grained. Repository access: only `<owner>/handoff`. Permissions:
+   Contents = Read and write. Copy the token.
+2. **Repo.** Create `<owner>/handoff`, private, initialized with a README. In
+   Settings → Actions → General, disable Actions (no CI needed → no minutes).
+3. **Environments.** In each agent environment (both the `cool-workflow` and the
+   `chime` environment), add an environment variable `GH_TOKEN=<token>` (`.env`
+   format, no quotes). A new session is required for it to take effect.
+4. **Optional** — put the clone in each environment's setup script so the ledger
+   is present at session start:
+   ```bash
+   #!/bin/bash
+   git clone https://oauth2:${GH_TOKEN}@github.com/<owner>/handoff.git /home/user/handoff || true
+   ```
+
+## Gitea (self-hosted) — setup
+
+Same shape, two extra prerequisites:
+
+1. Serve Gitea over HTTPS with a valid certificate (e.g. Let's Encrypt) so the
+   cloud VM's git can verify it.
+2. Configure the agent environment's **network access** to permit your VPS host —
+   the default Trusted allowlist does not include it. If the loop cannot reach
+   the VPS, it cannot run.
+3. Create a Gitea access token, store it as an environment variable, and clone
+   with an authenticated remote (`https://<user>:${GIT_TOKEN}@<vps-host>/<owner>/handoff.git`).
+
+## Directory convention
+
+Entries live under `ledger/` in the shared repo, one file per entry named by its
+id:
+
+```
+handoff/
+  ledger/
+    ldg-1de7c92172af1871.json
+    ldg-2315e4b33b9a812f.json
+```
+
+## The loop
+
+Producing side (propose a change, hand it over):
+
+```bash
+entry=$(cw ledger propose --from cool-workflow --to chime \
+  --title "Add retry" --rationale "flaky net" \
+  --files src/net.ts --diff "$(git -C <src-repo> diff)")
+id=$(printf '%s' "$entry" | jq -r .id)
+printf '%s\n' "$entry" > /home/user/handoff/ledger/$id.json
+git -C /home/user/handoff add ledger/$id.json
+git -C /home/user/handoff commit -m "propose $id"
+git -C /home/user/handoff push
+```
+
+Note the single `cw ledger propose` call captured into `$entry` — calling it
+twice would mint two different entries (each carries a fresh `createdAt`).
+
+Consuming side (verify the inbox, then act or review back):
+
+```bash
+git -C /home/user/handoff pull
+cw ledger list --dir /home/user/handoff/ledger && echo "inbox verified — safe to act"
+
+# hand a verdict back:
+entry=$(cw ledger review --from chime --to cool-workflow \
+  --target ldg-1de7c92172af1871 --verdict approved --findings "tests pass,scope ok")
+id=$(printf '%s' "$entry" | jq -r .id)
+printf '%s\n' "$entry" > /home/user/handoff/ledger/$id.json
+git -C /home/user/handoff add ledger/$id.json
+git -C /home/user/handoff commit -m "review $id"
+git -C /home/user/handoff push
+```
+
+## Notes
+
+- Keep private code out of a **public** handoff repo: omit `--diff` and reference
+  a commit/branch in the private source repo instead, so only metadata + a
+  pointer is exposed. On a private handoff repo, full diffs are fine.
+- The other side may build entries without `cw` as long as they match the
+  digest/id rules in [cross-agent-ledger](cross-agent-ledger.7.md); otherwise
+  `cw ledger verify` refuses them with `ledger-digest-mismatch`.

package/docs/init.7.md

@@ -0,0 +1,62 @@
+# INIT(7)
+
+## NAME
+
+`cw init` — scaffold a new workflow definition from nothing
+
+## SYNOPSIS
+
+```text
+node dist/cli.js init <workflow-id> [--title TITLE] [--output PATH] [--force]
+```
+
+## DESCRIPTION
+
+`cw init` makes a new workflow definition file — a `.workflow.js` file filled
+with a simple template. The template has a basic run shape: one step with a
+sandbox profile, one evidence gate, and the hooks you need to add your own
+steps.
+
+This is how you start a new workflow app from zero. After `init`, you have a
+real file you can edit to make your own run shape.
+
+The workflow id you give is turned into a safe file name (spaces become dashes,
+special signs are taken out). By default, the file is written to the current
+working directory, but you can point it somewhere else with `--output`.
+
+If a file of that name is already there, the command refuses to overwrite it
+unless you pass `--force`.
+
+## OPTIONS
+
+`--title TITLE`
+: A human name for the workflow. If not given, a title is made from the id.
+
+`--output PATH`
+: Where to write the workflow file. Default is `<id>.workflow.js` in the
+current directory.
+
+`--force`
+: Overwrite an existing file. Without this flag, the command fails if the
+file already exists.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Workflow file written |
+| 1 | Missing workflow id, invalid id, or file exists without `--force` |
+
+## FILES
+
+```text
+src/orchestrator.ts (init method)
+src/workflow-app-framework.ts (template renderer)
+```
+
+## SEE ALSO
+
+cw list — see all workflow apps you have
+cw info <id> — read the shape of a workflow app
+workflow-app-framework.7.md — the full framework for writing workflow apps
+pipeline-verbs.7.md — plan, dispatch, result (the pipeline engine)

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -319,3 +319,7 @@ The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/multi-agent-eval-replay-harness.7.md

@@ -345,3 +345,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/multi-agent-operator-ux.7.md

@@ -357,3 +357,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/node-snapshot-diff-replay.7.md

@@ -178,3 +178,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/observability-cost-accounting.7.md

@@ -237,3 +237,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.95
 
 0.1.96
+
+0.1.97
+
+0.1.98

package/docs/pipeline-verbs.7.md

@@ -0,0 +1,93 @@
+# PIPELINE-VERBS(7)
+
+## NAME
+
+`cw plan`, `cw dispatch`, `cw result` — the three core pipeline engine verbs
+
+## SYNOPSIS
+
+```text
+node dist/cli.js plan <workflow-id> [--question Q] [--repo PATH] [--sandbox PROFILE]
+node dist/cli.js dispatch <run-id> [--sandbox PROFILE]
+node dist/cli.js result <run-id> <task-id> <result-file>
+```
+
+## DESCRIPTION
+
+These three verbs are the engine that drives every CW run. A run goes through
+three stages: plan (get ready), dispatch (hand out work), and result (take work
+back). Together they make the CW pipeline loop — a worker gets a task, does it,
+and hands in a result file; CW checks the result and moves the run forward.
+
+None of these verbs starts or stops the agent host. They give the control-plane
+data that the host reads and acts on. The host keeps its own loop: call
+`dispatch`, give the task to an agent, get back a result file, call `result`.
+
+## PLAN
+
+`cw plan <workflow-id>` makes a new run and gives back its canonical plan
+summary in JSON. The plan has the run id, the first task (or tasks) to do,
+the sandbox profile, and the state of the run.
+
+The workflow id names a workflow app that gives the run its shape: inputs,
+steps, evidence gates, and sandbox policy. Use `cw list` to see the workflow
+apps you have.
+
+The plan output is stable JSON, good for scripts and the agent host.
+
+Options:
+: `--question`, `--repo`, `--sandbox` — the same inputs the workflow app
+expects. Different apps take different inputs; see `cw info <workflow-id>`
+for the list.
+
+## DISPATCH
+
+`cw dispatch <run-id>` makes the next task ready for a worker. It gives back
+a dispatch manifest in JSON: the task id, the prompt, the sandbox profile, and
+the input and output paths the worker should use.
+
+The dispatch picks the next runnable task in the pipeline. If no task is ready
+— for example, all tasks are done or waiting on evidence — the dispatch payload
+says so, and the host should wait or check the run status.
+
+Options:
+: `--sandbox PROFILE` — pick a sandbox profile for the worker. The default is
+the one the workflow app asked for.
+
+## RESULT
+
+`cw result <run-id> <task-id> <result-file>` records a worker's result against
+a task. The result file is a Markdown file the agent wrote — it must have a
+`cw:result` JSON fence with the agent's `findings` and `evidence`.
+
+CW accepts the result, checks it, and advances the run pipeline. If the result
+is bad (missing, broken, or the evidence does not check out), CW rejects it and
+gives back an error feedback record. The host can then try again or give the
+task a different agent.
+
+After `result`, the run may be done or have more tasks waiting. Check with
+`cw status <run-id>` or `cw next <run-id>`.
+
+## FILES
+
+```text
+.cw/runs/<run-id>/state.json
+.cw/runs/<run-id>/dispatches/<dispatch-id>.json
+.cw/runs/<run-id>/tasks/<task-id>.json
+.cw/runs/<run-id>/results/<task-id>.md
+.cw/runs/<run-id>/workers/<worker-id>/worker.json
+```
+
+## PIPELINE FLOW
+
+```text
+plan -> dispatch -> [agent does work] -> result -> [dispatch...] -> done
+                                        └─ rejected -> feedback -> retry
+```
+
+## SEE ALSO
+
+cw init — make a new workflow definition from nothing
+cw status — see the current state of a run
+cw next — find the next action for a run
+pipeline-runner.7.md — the full pipeline engine detail