Plan format

# Fix the login bug

- Reproduce the failure locally
- Write a failing test
- Patch the handler

# Ship it

1. Open a PR
2. Wait for CI
3. Merge

# Build and verify

1. compile the binary

   ```ralph-task
   {"id": "build"}
   ```

2. run the integration suite

   ```ralph-task
   {"id": "integration", "after": ["build"]}
   ```

3. run the linters

   ```ralph-task
   {"id": "lint", "after": ["build"]}
   ```

# Ship

1. build the release artifacts
2. Deploy to production [approval]
3. run smoke tests

# Wide refactor

- rename the symbol across every call site

   ```ralph-task
   {"id": "rename-all", "requires": ["native_fanout"]}

Dispatch resolves the binding the step would run on and checks it
**before** allocating a worker, a session, or a dispatch slot. A step
whose requirements the binding cannot meet is moved to
`blocked_capability` with the missing keys recorded as its blocked
reason, rather than being run against a provider that cannot do the work.

The vocabulary is closed — a key outside it is a typo, and a typo cannot
be satisfied by any binding, so it blocks the step rather than passing
silently:

| Key | The binding must… |
|-----|-------------------|
| `native_fanout` | run a whole ready group in one turn (`native_fanout = true`) |
| `resume` | continue a prior session (`supports_resume = true`) |
| `append_system_prompt` | append to the system prompt rather than replace it (`use_append_system_prompt = true`) |

Every key maps to something a binding declares in its config, so the two
cannot drift apart. Steps that declare no `requires` are unaffected.

Unblocking is a plan or configuration change — fix the key, or bind the
project to a provider that has the capability — not something the
supervisor retries its way out of. That is the point: a task that can
never succeed on this binding says so immediately instead of stalling
with no explanation.

## Restricting which provider runs a task

A step can name the providers allowed to run it:

```markdown
# Cross-check

- generate the migration

   ```ralph-task
   {"id": "generate-migration"}

A name matches either the binding **alias** or the provider **type**, because
both are useful restrictions: several aliases can share one type (a
round-robin pool of `claude` bindings), so "any claude" and "this specific
pool member" mean different things.

A task whose resolved provider is outside its list is **not dispatched**, and
the refusal is recorded as a `worker.admission_refused` event naming the
allowed providers. Where the project is bound to a *pool*, dispatch rotates
through it first: a `[claude, codex]` pool can still run a codex-only task, so
the restriction is about the work rather than about which member the rotation
happened to reach.

The task stays `pending` rather than becoming `blocked_capability`, and the
difference from `requires` is deliberate. `providers` names operator
**configuration** — binding the project to an allowed provider fixes it, so a
durable block would leave an operator clearing a state their config edit had
already resolved. `requires` is different: no configuration change makes a
provider gain a capability it does not have, so that one does block.

Unlike `requires`, there is no closed vocabulary here: provider names are
operator-chosen configuration, so an unrecognized name is indistinguishable
from a provider this project simply is not bound to right now. Either way the
task blocks and names the list, which is the actionable report.

## Independence constraints

A step can declare that it must not run on the same provider as another task —
for work whose value depends on *who* did it, like a review of generated code:

```markdown
# Cross-check

- produce the migration

   ```ralph-task
   {"id": "produce"}

**Import validates the references and dispatch enforces the constraint.** Both
halves matter, and the split is worth being precise about, because a
half-implemented guarantee is easy to mistake for a whole one.

What is checked now:

- A reference to a task that does not exist is **rejected**. It could never be
  satisfied or violated, so it would sit in the plan looking like an
  independence guarantee while enforcing nothing — worse than an unenforced
  field, because the plan reads as protected.
- A self-reference is **rejected**. A task cannot run on a provider different
  from its own, so dispatch could only ever block it forever; failing at import
  turns a permanent stall into an authoring error.
- An **empty** entry is rejected, for the same reason as an unknown one: it names
  no task, so it can never be enforced. Skipping it silently would also give you
  no signal that a list entry did nothing.

What dispatch does with it: before a step runs, its peers' RECORDED domains --
what they actually ran on, not what the plan hoped -- are compared against the
domain of the binding this turn would use. A clash ROTATES through the provider
pool rather than blocking, because a pool is a rotation and the next member may
well differ; refusing on the head's identity would make the constraint a coin
flip on cursor position. It is deliberately not a fail-closed `blocked_*` state
either: no operator action is needed and the next dispatch may satisfy it.

An UNCALIBRATED peer does not satisfy the constraint. An empty domain means the
peer has not run yet, or ran on a binding nothing has calibrated -- either way
the domains are not *known* to differ, and a constraint that passes on absence
of evidence enforces nothing while reading as protection. The step defers until
the peer has run on a calibrated binding. Record one with
`radioactive_ralph calibration record`.

## Validation

`internal/plan.Validate` checks the document against the grammar (sibling
heading levels, ambiguous sections) and returns structured errors so a
malformed plan is caught before dispatch, not discovered mid-run.

## From a vague ask to a plan

Turning a free-form prompt into a plan document is the one place a human
ask needs interpretation. Rather than an interactive Q&A flow, a small
team of agents **juxtapose and challenge** each other's read of the draft
until it converges on a plan that covers the work end-to-end
(`internal/genesis`). Headless mode emits the final markdown; the TUI
renders it for review (scroll, or hand off to `$EDITOR`) before it's
accepted. You can also skip this and hand-write the plan directly — the
refined document *is* the plan; there's no separate machine format it
gets compiled into.

## How the orchestrator uses it

The orchestrator (`internal/orch`) computes what's ready from the plan's
AST plus the database's done-state for each step, dispatches ready steps
to agent workers with plan-scoped context, and **verifies** each
completion against the step's acceptance criteria (a command that must
exit 0, a file that must exist, or — absent either — the worker's
evidence output) before marking it done. A worker's own claim of
completion, or its process simply terminating, is never sufficient on its
own.