@robmclarty/volley 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## v0.12.0 — 2026-11-09
+
+### Added
+- **`--effort-ladder low,medium,high` runs each build one effort rung further up, off by default.** Or `VOLLEY_EFFORT_LADDER`, or `effort_ladder` in a config file. Rungs come from `low`, `medium`, `high`, `xhigh`, and `max`, and the top rung repeats. A build climbs only after one that didn't end the run, and it records why: `check_failed`, else `critic_rejected`. Each build prints its rung (`[iter 2] rung medium (climbed: check_failed)`), and each iteration's `summary.json` records `rung`, `climbed` and `effort_ignored`. On `claude_cli` the effort reaches Claude Code as `CLAUDE_CODE_EFFORT_LEVEL`. On `ollama` and `lmstudio`, which ignore effort, the ladder is flat and config warns. A resumed run keeps its ladder and picks up at the rung it had reached.
+- **`--critic-effort` sets the critic's effort on its own.** Or `VOLLEY_CRITIC_EFFORT`, or `critic_effort` in a config file. It takes the same five levels and defaults to `high` once a ladder is set. With neither set, the critic is sent no effort, as before.
+- **`--tester on` writes a failing test from the criteria before the first build, off by default.** Or `VOLLEY_TESTER`, or `tester` in a config file. The tester runs on the critic's seat at the critic's effort; `--tester-model` (or `VOLLEY_TESTER_MODEL`) overrides the model. It writes only tests and fixtures under the gate paths, never `package.json`, a `*.config.*` file or `.github/`, and has no shell. The check must then fail. If it passes, the run ends as `tester_passed_early` (exit 2) with no builder spend. The tester needs a check, and a tester on any provider but `claude_cli` needs the same containment a builder does. Its spend (`tester_cost_usd`) and writes (`tester_changes`) are recorded apart, so its test isn't counted as a builder gate edit, and the critic reviews the tester's test, reporting any problems in an optional `test_findings`.
+- **The tester runs under `volley acp` too.** Its writes go through Zed's approval prompts with their diff, as the builder's do, and a path it may not write is refused before you're asked. A `claude_cli` tester is refused at startup. Round 1 shows the tester's test and the build as two headings.
+- **`volley run --protocol runciter.run/1` lets runciter's `process` kind run volley with no adapter.** volley reads one `RunInput` on stdin, writes exactly one `RunOutput` on stdout, puts `runciter.progress` and `runciter.usage` lines on stderr, and exits 0, 1 or 2 by the protocol's own table. It maps the input as runciter's `volley` kind did: the agent's prompt plus `context.md`, the task's criteria, the check from the stage's `verify`, state under the run directory, and the critic's last feedback as a `critic-feedback.md` artifact. It refuses `--worktree`, `--git`, `--json` and a positional prompt. The README's new "Run volley from runciter" section has an agent-file example and the exit table. `volley run` is now another name for `volley`.
+
+### Changed
+- **Each iteration of a run's trajectory has two more spans.** The flow gained `test` and `work` branches, which pass straight through when the tester is off, so the builder's and the critic's calls, the output, and the exit codes are unchanged; the diagram draws the new branches.
+
+### Internal
+- `keyframes.md` lists `src/protocol/` under M1 (cli), and its C2 constraint now covers the tester. The build's record is in `.plumbbob/builds/2026-11-08-move-1-tester-seat-effort-ladder-and-runciter-run-1/`.
+
+## v0.11.1 — 2026-11-04
+
+### Internal
+- **volley's intent is written down in `keyframes.md`.** It holds four principles, a seven-part map of `src/`, eleven constraints and eight scenarios, each linked to the test or rule that holds it, twelve decisions, one open question and five ideas not yet built. `AGENTS.md` tells agents how to treat each kind of item, and `CLAUDE.md` imports it, so Claude Code reads it.
+- **`pnpm check` checks `keyframes.md` against the repo.** A new `intent` check runs `keyframes check --strict`, from `@robmclarty/keyframes` 0.3.0 as a dev dependency. It fails when a test, rule or path the plan points at is renamed or moved, or when the plan picks up a warning. It's a gate for developing volley and never runs in a volley run.
+- **Agents ask before changing `keyframes.md`.** Claude Code asks before it edits the file or runs a shell command that names it. A pre-commit hook shows a macOS dialog before any commit that changes it can land, whichever agent made the change, and refuses where no dialog can be shown. A clone turns the hook on with `git config core.hooksPath .githooks`.
+- **The published package is unchanged.** No command, flag or output changed since v0.11.0.
+
 ## v0.11.0 — 2026-11-02
 
 ### Added

package/README.md

@@ -101,6 +101,80 @@ workspace filesystem, the critic's feedback, and a failed check's output. Swap t
 the loop optimizes for: `--critic reviewer` (default), `optimizer`,
 `researcher`, or a path to your own system prompt.
 
+### The effort ladder
+
+`--effort-ladder low,medium,high` runs each build one rung further up than the
+last: build 1 at `low`, build 2 at `medium`, and every build from the third on
+at `high`, the top rung repeating to `--max-iterations`. A build climbs only
+because the one before it didn't end the run: its check failed, or the critic
+sent it back. So an easy task converges on a cheap first build, and a hard one
+spends more only after a cheap attempt failed. A rung sets the call's effort,
+never its model, so the seat stays the same seat on every rung; on `claude_cli`
+it reaches Claude Code as `CLAUDE_CODE_EFFORT_LEVEL`. The rungs are `low`,
+`medium`, `high`, `xhigh`, and `max`. `none` is refused, since on `claude_cli`
+it sets nothing and leaves Claude Code at its own default, which can sit above
+`low`.
+
+The critic's effort is set apart, with `--critic-effort`, and defaults to `high`
+once a ladder is set: reading a diff costs far less than writing it, and the
+critic is what makes a cheap build safe. Without a ladder neither seat is sent
+an effort unless `--critic-effort` names one, so a run without either flag makes
+the calls it always has. Each build prints its rung as it opens
+(`[iter 2] rung medium (climbed: check_failed)`), and the run's summaries record
+them (see [Run artifacts](#run-artifacts)).
+
+**The ladder is flat on Ollama and LM Studio.** Their transports drop effort, so
+every rung runs the same there: volley warns when a ladder is set on such a
+builder, marks each iteration `effort_ignored`, and the summary reads
+`ladder_flat: true`. No rung means anything on a local model yet.
+
+### The tester seat
+
+`--tester on` adds a third seat that runs once, before the first build: a
+tester that turns the acceptance criteria into a failing test. A critic can be
+argued with about prose criteria, and a test can't. The tester reads the
+workspace, writes tests and fixtures where the check will pick them up, and
+then the check runs, and must fail on what it wrote. A red check goes on to the
+build, and the builder's prompt names the tester's files and shows the check's
+failure. A check that passes ends the run there, with no build paid for, as
+`tester_passed_early` (exit 2): a test that passes before any work is either
+vacuous or proof the work is already done. Later iterations start at the build,
+with the test already in place. It's off by default.
+
+- **Its seat.** The tester takes the critic's provider, URL, and effort, and the
+  critic's model unless `--tester-model` names one. Its spend is
+  `tester_cost_usd`, apart from the builder's and the critic's, and the cost cap
+  is checked after it: a tester that crosses the cap ends the run before the
+  check and the build.
+- **What it may write.** Only paths a gate pattern matches (`--gate-paths`, or
+  the defaults under [What the builder changed](#what-the-builder-changed)),
+  and never `package.json`, a `*.config.*` file, or anything under `.github/`,
+  since a tester that could rewrite the check's configuration could make its
+  own result red or green. A write anywhere else is refused, naming the path.
+  It has no shell. On `claude_cli` it runs in Claude Code's default permission
+  mode, allowed `Read` anywhere in the build root and one `Edit` rule per test
+  and fixture pattern, with `Bash` and edits to those three kinds of file
+  denied.
+- **It needs a check.** `--tester on` with `--check none`, or with a `--check
+  auto` that finds no checkride, is refused before anything runs, since a test
+  can't go red without a check.
+- **Its test is its own.** Each file the tester wrote is hashed after it runs.
+  A build that leaves one at that hash isn't reported as a gate edit there, and
+  a build that changes it is, as any gate edit is. Under `--git`, a
+  `volley iter 1: test` commit lands before the build's.
+- **The critic reads it too.** Its prompt lists the tester's files and asks
+  whether they test the criteria, and it names any gaps as `test_findings`. A
+  vacuous test doesn't decide the verdict by itself: the critic checks by hand
+  what the test misses.
+
+**It's contained as a builder is.** The check runs what the tester writes, so a
+tester on any provider but `claude_cli` runs only inside the
+[sandbox](#local-builder), unless `--allow-unsandboxed-builder` opts out. A
+`claude_cli` builder stays on the host, so with one, a local tester needs the
+opt-out. A `claude_cli` tester runs under its own permission list, on the host.
+Under [`volley acp`](#run-volley-from-zed) the tester's writes ask as the
+builder's do, in a round of their own, and a `claude_cli` tester is refused.
+
 ### The flow
 
 Under the hood the loop is one [fascicle](https://www.npmjs.com/package/fascicle)
@@ -112,22 +186,33 @@ the guard that decides when the loop stops.
 
 <!-- flow diagram: pnpm diagram -->
 ```text
-volley                                loop: one round per iteration, up to max_iterations
-├─ iteration                          sequence
-│  ├─ build                           open the iteration, run the builder, measure the change
-│  │  └─ builder                      model call: one agentic session in the build root
-│  ├─ verify                          branch: did the build alone cross the cost cap?
-│  │  ├─ then  skip_verify            record the check as skipped and call no critic
+volley                                      loop: one round per iteration, up to max_iterations
+├─ iteration                                sequence
+│  ├─ test                                  branch: does the tester open this iteration? (--tester on, the run's first)
+│  │  ├─ then  sequence
+│  │  │  ├─ write_test                      open the iteration, run the tester, record what it wrote
+│  │  │  │  └─ tester                       model call writing a failing test under the test and fixture gate paths
+│  │  │  └─ red                             branch: did the tester alone cross the cost cap?
+│  │  │     ├─ then  skip_red               record the check as skipped and build nothing
+│  │  │     └─ else  red_check              the check, which must fail on the tester's test
+│  │  └─ else  no_test                      no tester this iteration
+│  ├─ work                                  branch: did the test phase end the run: a green check, or the cost cap?
+│  │  ├─ then  hold                         build nothing, and leave the run to the guard
 │  │  └─ else  sequence
-│  │     ├─ check                     the deterministic gate: checkride, a command, or none
-│  │     └─ critique                  the read-only critic's verdict and feedback
-│  │        └─ critic                 fallback: judge without tools if a critic on any provider but claude_cli keeps dying or runs out of steps
-│  │           ├─ retry               one more try after a stream death, on any provider but claude_cli
-│  │           │  └─ critic_tools     model call with read-only workspace tools
-│  │           └─ pipe                mark the verdict degraded
-│  │              └─ critic_toolless  model call judging from the check output and a file list
-│  └─ record                          archive the iteration and rewrite the run summary
-└─ guard  gate                        stop on approval over a green check, the cost cap, or a gate edit
+│  │     ├─ build                           open the iteration unless the tester did, run the builder, measure the change
+│  │     │  └─ builder                      model call: one agentic session in the build root
+│  │     └─ verify                          branch: did the build alone cross the cost cap?
+│  │        ├─ then  skip_verify            record the check as skipped and call no critic
+│  │        └─ else  sequence
+│  │           ├─ check                     the deterministic gate: checkride, a command, or none
+│  │           └─ critique                  the read-only critic's verdict and feedback
+│  │              └─ critic                 fallback: judge without tools if a critic on any provider but claude_cli keeps dying or runs out of steps
+│  │                 ├─ retry               one more try after a stream death, on any provider but claude_cli
+│  │                 │  └─ critic_tools     model call with read-only workspace tools
+│  │                 └─ pipe                mark the verdict degraded
+│  │                    └─ critic_toolless  model call judging from the check output and a file list
+│  └─ record                                archive the iteration and rewrite the run summary
+└─ guard  gate                              stop on approval over a green check, the cost cap, a gate edit, or a green check before any build
 ```
 
 `pnpm diagram` prints the same tree from a checkout. A test holds this copy and
@@ -189,8 +274,11 @@ volley matrix --builders <models> --critics <models> --config <path>
 volley critique --criteria <criteria> [--baseline <rev>] [options]
 volley acp --builder-provider <name> --builder-model <model> \
   --critic-provider <name> --critic-model <model> [options]
+volley run --protocol runciter.run/1 [options] < run-input.json
 ```
 
+`volley run` is another name for `volley`, with the same options.
+
 | Flag | Default | Description |
 |---|---|---|
 | `--prompt` | (required) | Task prompt. Literal string or `@path/to/file.md`. |
@@ -204,12 +292,16 @@ volley acp --builder-provider <name> --builder-model <model> \
 | `--builder-max-tool-calls` | `1` | Tool calls a tool-loop builder may make per turn, not counting reads (`read_file`, `search_files`, `list_files`); past it, fascicle runs the calls before the first one over, drops the rest, and tells the model which it dropped. Raise it for a model and runtime that return parallel calls well. Or `VOLLEY_BUILDER_MAX_TOOL_CALLS`. Ignored for `claude_cli`. |
 | `--builder-max-output-tokens` | `16384` (ollama, lmstudio), the provider's (openrouter) | Output tokens a tool-loop builder may generate per turn, reasoning included (`num_predict` on Ollama). A turn cut off at it before it calls a tool costs that step, not the session. Or `VOLLEY_BUILDER_MAX_OUTPUT_TOKENS`. Ignored for `claude_cli`. |
 | `--builder-trim-history` | off | Experimental. Above this estimated request size, in tokens, a tool-loop builder's turns send older tool results as one-line stubs (see [Local builder](#local-builder)). Or `VOLLEY_BUILDER_TRIM_HISTORY`. Ignored for `claude_cli`. |
+| `--effort-ladder` | off | Comma-separated builder efforts from `low`, `medium`, `high`, `xhigh`, and `max`: each build runs one rung further up than the last, and the top rung repeats (see [The effort ladder](#the-effort-ladder)). Or `VOLLEY_EFFORT_LADDER`, or `effort_ladder` in a config file. Flat on `ollama` and `lmstudio`, which ignore effort. |
 | `--allow-unsandboxed-builder` | off | Permit a builder other than `claude_cli` to run without a sandbox (see [Local builder](#local-builder)). |
 | `--critic-model` | `opus` | Model for the critic. |
 | `--critic-provider` | `claude_cli` | `claude_cli`, `ollama`, `lmstudio`, or `openrouter` (see [Local critic](#local-critic) and [OpenRouter](#openrouter)). |
 | `--critic-url` | the provider's env var | The critic's model server base URL, for `ollama`, `lmstudio`, or `openrouter` only. |
+| `--critic-effort` | `high` with `--effort-ladder`, else none | The critic's effort on every call, from the same five levels as a rung. Or `VOLLEY_CRITIC_EFFORT`, or `critic_effort` in a config file. Unset with no ladder, the critic is sent no effort, as before. |
 | `--builder-permission-mode` | `acceptEdits` | Or `bypassPermissions` for fully trusted workspaces. |
 | `--critic` | `reviewer` | `reviewer`, `optimizer`, `researcher`, or a prompt file path. |
+| `--tester` | `off` | `on` runs a tester before the first build, which writes a failing test from the criteria; needs a check (see [The tester seat](#the-tester-seat)). Or `VOLLEY_TESTER`, or `tester` in a config file. |
+| `--tester-model` | the critic's | The tester's model, with `--tester on`; refused with it off. Or `VOLLEY_TESTER_MODEL`, or `tester_model` in a config file. |
 | `--max-iterations` | `10` | Hard iteration cap. |
 | `--max-cost-usd` | none | Hard USD ceiling. Set it. |
 | `--git` | off | Commit after each phase (workspace must be a git repo). |
@@ -226,6 +318,7 @@ volley acp --builder-provider <name> --builder-model <model> \
 | `--verbose` | off | Full tool inputs/outputs (truncated at 4000 chars). |
 | `--quiet` | off | Phase transitions, cost lines, and the final summary only. |
 | `--no-thinking` | off | Hide reasoning chunks (still recorded in the trajectory). |
+| `--protocol` | off | `runciter.run/1`: read one `RunInput` on stdin, write one `RunOutput` on stdout, and exit by the protocol's codes (see [Run volley from runciter](#run-volley-from-runciter)). |
 
 Human-readable progress goes to **stderr**; stdout carries machine output
 only, so volley composes under bigger harnesses the same way it composes
@@ -236,8 +329,8 @@ checkride.
 | Code | Meaning |
 |---|---|
 | 0 | Check passed and verdict approved. |
-| 2 | Max iterations reached without success; for `volley critique`, the critic asked for changes or the check failed. |
-| 3 | Builder/provider error. |
+| 2 | Max iterations reached without success; for `volley critique`, the critic asked for changes or the check failed; with `--tester on`, the check passed on the tester's test before any build (`tester_passed_early`). |
+| 3 | Builder, tester or provider error. |
 | 4 | Check pipeline error (broken pipeline, not failing checks). |
 | 5 | Configuration error. |
 | 6 | Critic error (schema validation failed after repair attempts). |
@@ -245,6 +338,9 @@ checkride.
 | 8 | The builder edited the gate and `--fail-on-gate-edit` was set. |
 | 130 | Interrupted (SIGINT); resumable. |
 
+Under `--protocol runciter.run/1` volley exits by the protocol's own table
+instead (see [Run volley from runciter](#run-volley-from-runciter)).
+
 ### Config file
 
 ```ts
@@ -281,7 +377,10 @@ workspace. A run an older volley started keeps its state in the workspace's
 inside it. A run directory with a symbolic link in it is refused, since volley
 never writes one. The resumed run's first builder gets what the last completed
 iteration left it, as it would have without the stop: the critic's feedback,
-the check's output if it failed, and the step-limit note.
+the check's output if it failed, and the step-limit note. The run's effort
+ladder and its critic's effort are recorded in its `config.json`, and its rung
+follows on from the builds the last iteration recorded, so build 3 still runs
+at the third rung with no variable set.
 
 **A resume on the host runs only a config this machine signed.** A resume runs
 what the run's `config.json` says, its check command and its seats included.
@@ -798,8 +897,8 @@ for you ([below](#zed-setup)).
 `--builder-provider`, `--builder-model`, `--critic-provider`, and
 `--critic-model`. A missing one is refused with every missing flag named. The
 rest are optional: `--builder-url`, `--critic-url`, `--builder-max-steps`,
-`--builder-max-tool-calls`, `--builder-max-output-tokens`, `--allow-unsandboxed-builder`, `--critic`, `--check`, `--max-iterations`,
-`--max-cost-usd`, and `--state-dir`.
+`--builder-max-tool-calls`, `--builder-max-output-tokens`, `--allow-unsandboxed-builder`, `--critic`, `--check`, `--tester`,
+`--tester-model`, `--max-iterations`, `--max-cost-usd`, and `--state-dir`.
 
 It refuses these before serving, each with exit 5:
 
@@ -809,9 +908,15 @@ It refuses these before serving, each with exit 5:
 | `--git` | It commits to the open repo after every phase, which no permission prompt covers. |
 | `--json` | Stdout carries the protocol alone. |
 | a `claude_cli` builder | The Claude CLI runs its own tools under its own permission model, so its edits would never reach the editor's prompts. |
+| a `claude_cli` tester | The tester takes the critic's provider, and a Claude CLI tester's writes would never reach the editor's prompts. `VOLLEY_TESTER=on` counts. |
 
 A `claude_cli` critic is allowed: it only reads, and it runs on the host, where
-its login works. The whole config resolves once at startup, so a bad flag or an
+its login works. A tester on any other provider runs in a round of its own
+before the build, headed **Round 1: the tester's test**, and each of its
+writes asks with its diff, as the builder's do; a write it may not make is
+refused before you're asked about it. Its `--check auto` resolves against the
+folder each session opens, so a prompt in a folder with no check fails with
+the reason rather than the startup. The whole config resolves once at startup, so a bad flag or an
 unset `OPENROUTER_API_KEY` exits 5 there, where Zed's agent log shows it, rather
 than failing every prompt.
 
@@ -927,6 +1032,107 @@ Two more round it out. Ask it to run `echo "key=$OPENROUTER_API_KEY"`, and the
 output should be `key=` with nothing after it. And the repository should hold no
 `.volley`.
 
+## Run volley from runciter
+
+`volley run --protocol runciter.run/1` makes volley a run child of runciter,
+the scheduler that runs tasks through pipelines of agents, over the protocol
+runciter's spec defines in its §5.4: one `RunInput` on stdin, exactly one
+`RunOutput` on stdout and nothing else, progress on stderr, and the exit code as
+the verdict. runciter's `process` kind runs it as it would any child that speaks
+the protocol, so runciter needs no adapter of its own for volley. Name the
+command in an agent file's frontmatter:
+
+```markdown
+---
+label: Volley
+runner: process
+command: [volley, run, --protocol, runciter.run/1, --builder-model, sonnet, --max-iterations, "5"]
+---
+You are the build stage. Make the change the task asks for, and leave the tests green.
+```
+
+Only the flag turns protocol mode on. runciter sets `RUNCITER_PROTOCOL` for
+every process under a run, a check that runs `volley` included, so volley
+ignores the variable.
+
+### What it reads
+
+The `RunInput` sets the task. Every other flag in the agent's argv, the seats,
+`--max-iterations`, `--critic`, `--tester` and `--config` among them, applies
+as it does on the command line.
+
+| From the `RunInput` | Becomes |
+|---|---|
+| `agent.prompt`, then the text of `context.md` | The prompt. `context.md` carries the task and, on a retry, the feedback on the last attempt, so a retried task knows why it failed. |
+| `task.criteria` | The criteria. |
+| `workspace.path` | The workspace. |
+| `stage.verify` | The check, read as runciter's own verify reads it, so volley converges on the gate runciter checks afterwards: `none` and a command as they are, and `auto` as `pnpm check` when `package.json` has a `check` script, else no check. A `--check` in the argv wins. |
+| `budget.max_cost_usd` | The cost cap, over any `--max-cost-usd` in the argv, which stands when runciter gives no budget. |
+| `run_dir` and `run_id` | The run's state, at `<run_dir>/volley/<run_id>/`, outside the workspace runciter diffs and verifies. A `--state-dir` or `--run-id` in the argv wins. |
+| `budget.timeout_ms` | Nothing: runciter stops the run itself, with SIGTERM. |
+
+### What it writes
+
+On stdout, one `RunOutput`:
+
+- **`status`** is `passed` when the run succeeded, else `failed`, with a
+  `fail_reason`: `iterations_exhausted` when it ran out of iterations,
+  `cost_cap`, `gate_edit_blocked`, `interrupted`, `builder_error` for a builder's
+  or a tester's error, `check_error`, `critic_error`, and `not_passed` for any
+  other outcome, `tester_passed_early` among them.
+- **`summary`** is a status line, then the critic's last feedback, cut to 4,000
+  characters. **`detail`** is the error's message, when the run ended on one.
+- **`usage`** is the run's totals, its cost marked `estimated`, as Claude Code's
+  cost is.
+- **`data`** is the run's `summary.json` whole, which runciter keeps as the
+  run's `data.json`.
+- **`artifacts`** names `critic-feedback.md`, the critic's last `feedback.md`,
+  which volley copies into `<run_dir>/artifacts/`, following no link in either
+  file's place. **`lessons`** is empty.
+
+On stderr, the run's progress without color, with runciter's typed lines among
+it: a `runciter.progress` line as each phase starts and ends
+(`iteration 2: check failing: test`, with `done` and `total` counting
+iterations), and a `runciter.usage` line as each iteration ends, the run's
+spend so far, and once more after the run, with its tokens.
+
+### Exit codes in protocol mode
+
+The protocol's own table, apart from the [one above](#exit-codes):
+
+| Code | Meaning |
+|---|---|
+| 0 | One `RunOutput` on stdout, whatever the run's outcome, a builder, check or critic error included, so its summary and `data` reach runciter's drawer. |
+| 1 | volley failed and had no `RunOutput` to write. runciter records a `runner_error`. |
+| 2 | Bad input on stdin, a refused flag, or a config error. runciter records a `contract_violation`. |
+
+On 1 and 2, stdout is empty and the last line on stderr is a `StdioFailure`,
+`{ "error": …, "stage"?: … }`, the shape fascicle's `run_stdio` writes, which
+runciter takes as the failure's detail.
+
+### Refusals
+
+Each exits 2 before stdin is read:
+
+| Refused | Why |
+|---|---|
+| `--worktree` | runciter owns the workspace. |
+| `--git` | runciter owns the workspace and what's committed to it. |
+| `--json` | Stdout carries the `RunOutput`. |
+| a positional prompt | The `RunInput` gives the prompt. |
+
+### Conformance
+
+[`test/fixtures/runciter_run_input.json`](test/fixtures/runciter_run_input.json)
+is a complete `RunInput`, every field §5.4 names, and the conformance input
+runciter's planned `runciter-run conform <command>` will drive volley with. Its
+paths are placeholders: a driver points `workspace.path`, `run_dir` and
+`context` at real ones, as volley's own tests do, which parse it
+(`test/unit/protocol.test.ts`) and run it through the CLI
+(`test/integration/protocol_cli.test.ts`). volley's schemas in `src/protocol/`
+are its own copy of runciter's, with no dependency on runciter, so that test
+is what checks the two agree.
+
 ## What the builder changed
 
 A check that exits 0 proves the check passed. It does not prove the builder did
@@ -1000,6 +1206,27 @@ the workspace: `<root>/<run id>/`, where the root is `--state-dir` (or
 - **Pruning.** Nothing prunes old runs. A root volley creates is yours alone
   (0700), since trajectories hold prompts and tool output. A reused `--run-id`
   rotates the earlier run aside to `<run id>.bak.<timestamp>/`.
+- **The effort ladder.** Each `iterations/NNN/summary.json` records `builds`
+  (the builder sessions so far), `rung` (the effort that build ran at, or null
+  with no ladder), `climbed` (`check_failed`, `critic_rejected`, or null when
+  it didn't climb), and `effort_ignored` (its provider dropped the effort), and
+  a seat's record says `effort_ignored` too when its effort was dropped. The
+  run's `summary.json` carries `comparison.rungs`, each iteration's rung in
+  order, and `comparison.ladder_flat`, true when every build ran at one effort,
+  an ignored effort counting as the provider's own
+  ([The effort ladder](#the-effort-ladder)).
+- **The tester.** With `--tester on`, iteration 1's `summary.json` records
+  `tester` (its session, as `builder` and `critic` are), `tester_check` (the
+  check run right after it, which must fail), and `tester_changes` (what it
+  wrote, measured as `changes` is). Every iteration carries `tester_hashes`,
+  each file the tester wrote by its content hash after it ran: a build that
+  leaves one at that hash isn't counted as a gate edit there, and one that
+  changes it is. The critic reads the tester's test too, and its record
+  carries `test_findings` when it found the test wanting. A run that passes
+  its check before any build has a null `builder` and `check`, ends
+  `tester_passed_early`, and says so in `comparison.tester_passed_early`. The
+  run's `summary.json` and its `comparison` carry `tester_cost_usd` beside the
+  other two seats' costs.
 - **Older runs.** An older volley kept the same files in the workspace's
   `.volley/`. `volley resume` still finds such a run there, and resumes it in
   place once you pass `--trust-config`, since an older volley signed nothing