# optimize

> Metric-driven optimization, interactive batched.

optimize turns “make this number better” into a reproducible hypothesis loop. You define a single scalar metric and a measurement script; the engine — not the LLM — measures every commit and logs a TSV leaderboard, so the result cannot be gamed by a hallucinated number. It pauses for your approval at batch boundaries. At completion it squashes the branch down to baseline..best_commit and ships an MR/PR carrying the leaderboard.

```
protocol_start(protocol_name="optimize")
```

## Steps (7 steps)

1. **setup** — discussion — Interactive metric elicitation: the metric + direction, termination conditions, noise control, batch size, frozen paths. Writes the validated settings to optimize-state.json (the baseline step later adds the measured baseline to it).
2. **metric-script** — implementation — Author the measurement script — prints exactly one float, exit 0, deterministic. Validated by a double-run stability gate before you can advance.
3. **baseline** — implementation — Capture the baseline metric on HEAD; project total cost from real timing.
4. **experimentation** — implementation — The hypothesis loop: one hypothesis = one focused commit. The engine measures each commit. Checkpoints between batches return to discussion for your approval.
5. **synthesis** — documentation — Findings document, plus a non-blocking metric-gaming audit.
6. **code-review** — implementation — Full two-stage gate on the cumulative baseline..best_commit diff.
7. **completion** — discussion — Squash from best_commit; ship the leaderboard as the MR/PR description.

## What makes it distinctive

### Engine-owned measurement

The engine runs the metric script on every commit and writes the TSV leaderboard. The LLM’s reported numbers are untrusted — the leaderboard is the single source of truth, so it cannot be gamed.

### Frozen paths

During experimentation, the metric script and test files are frozen — a hook physically blocks edits to them even in implementation mode. You can’t move the goalposts mid-experiment.

### Batch checkpoints

After each batch of hypotheses the protocol returns DAIC to discussion for your approval before continuing — keeping a human in the loop on an otherwise mechanical loop.

branch: `optimize/ — o-<name>`