grade-iterate

1# Phase 3 — Grade → Iterate (the bounded loop)
2 
3This is the plugin's **loop**: CMA's `outcome` primitive self-grades the agent's
4work in an isolated context and feeds failing verdicts back for the next attempt.
5It is **always bounded** by `max_iterations` (1..20) — never "improve forever".
6 
7See [`../../references/loops-and-workflows.md`](../../references/loops-and-workflows.md)
8and the outcome section of
9[`../../references/cma-primitives.md`](../../references/cma-primitives.md).
10 
11## Workflow
12 
131. **Define the outcome.**
14   ```bash
15   python3 scripts/outcome_builder.py \
16     --sheet ./my-agent/build-sheet.json --max-iterations 5 \
17     --out ./my-agent/payloads/outcome.json
18   ```
19   The **rubric is required**; `max_iterations` is clamped to 1..20. Send the
20   payload as a `user.define_outcome` event (append to the running session).
212. **Read every verdict first.**
22   ```bash
23   python3 scripts/verdict_reader.py --result ./my-agent/last-verdict.json
24   ```
25   Tables the rubric outcome and recommends: **SHIP** (`satisfied`), **SHARPEN**
26   then re-run (`needs_revision`), **ESCALATE** (`max_iterations_reached` /
27   `failed`), **RESUME** (`interrupted`). With ≤1 iteration left it flips to
28   "make the single highest-value fix or escalate now".
293. **Loop invariant.** Each iteration must move ≥1 rubric line fail→pass, or the
30   run halts at the cap and escalates. Don't burn the budget on cosmetic edits.
314. **Once a version passes, run held-back eval.**
32   ```bash
33…