feat(loop): wire ADR 0064 P2 board seam — execution-grounded coder.solve()

[mabry1985]

HIGH-RISK — needs human review before merge

This wires the ADR 0064 P2 board seam: the loop's per-feature dispatch composes
the coder plugin's execution-grounded solve() ladder instead of a bare single
delegate_to(acp) shot, when it's safe to do so. Land as DRAFT.

ADR: https://github.com/protoLabsAI/protoAgent/blob/main/docs/adr/0064-coder-execution-grounded-code-solve.md

What landed

• coder_seam.py (new) — a thin adapter, not a reimplementation of the ladder.
  It composes plugins.coder.solve (imported lazily/best-effort — this repo
  carries no hard dependency on the coder plugin, matching the "compose delegates,
  don't reimplement" discipline this repo already follows for the ACP/A2A spawn
  primitive):

  • generate(task, feedback) creates a fresh throwaway worktree per candidate
    (feat-<id>.g<n>) and dispatches the ACP coder into it — the "independent-
    parallel acp attempts" the coder plugin's own generate.py docstring already
    flags as "the P2 path."
  • verify(candidate_wt) runs the configured acceptance-test command in that
    worktree and reports real pass/fail (never an LLM judge).
  • The winning (test-passing) candidate is promoted to the feature's canonical
    worktree/branch (reusing worktree.promote_worktree, the same primitive
    Max-Mode already uses) so the rest of the drive — fixups, the pre-PR local gate,
    open_pr, the CI bounce, tier escalation — is completely unchanged. Every
    other candidate is reaped.
  • A spent budget with no passing candidate raises SolveExhausted (a
    WorktreeError subclass) rather than opening a PR on an unverified partial.

• loop.py — one new branch in _drive's dispatch selection (alongside the
  existing keep_wt / max-mode / plain-single-shot branches):

  elif self._use_coder_solve(feature) and not self._ci_feedback.get(fid):
      wt, branch, result = await coder_seam.dispatch(...)

  SolveExhausted was added to the existing capability failure tuple (next to
  NoChangesError/CoderTimeout) — zero other changes to the escalation/retry
  state machine. This is the composition point the ADR asks for: coder.solve()
  searches within the current model tier; a search that never passes is a
  capability failure for THAT tier, so it climbs the coders-map ladder (or blocks)
  exactly like a no-diff dispatch always has. The tier ladder is untouched.

• store.py — record_gens_spent(fid, n) accumulates coder.solve()'s
  generation cost onto a single, replaced gens:<total> label (called once per
  solve() run, win or lose — a failed search still spent gens); _project now
  surfaces it as gens_spent on every feature so portfolio_rollup (a separate
  plugin) can read cost without raw reads, per the ADR's cost-v1 ethos.

• protoagent.plugin.yaml / README — new config: coder_solve (opt-out valve,
  default on), coder_solve_test_cmd (falls back to local_gate_cmd if blank),
  coder_solve_test_timeout_s, coder_solve_budget, coder_solve_k,
  coder_solve_tree_depth. Version bumped 0.25.0 → 0.26.0 (minor).

The exact seam

ready feature (+ acceptance_criteria) → worktree(s) → coder_seam.dispatch():
    greedy → run acceptance tests in worktree → fail?
      best-of-k into k fresh worktrees → execution-select → fail?
        tree-search refine on failing-test feedback
  → promote the passing candidate's worktree → canonical branch
  → (unchanged) fixups → pre-PR local gate → open_pr → in_review

Honest-degrade behavior (non-regressing by construction)

_use_coder_solve / coder_seam.should_use_solve require all three:

1. the coder plugin is importable (host has it enabled — it ships disabled by
   default, so most repos never reach this at all),
2. the feature carries acceptance_criteria (the Ready gate's existing oracle),
3. a runnable acceptance-test command is configured (coder_solve_test_cmd or
   local_gate_cmd) — without one there is genuinely nothing to execute, and per
   the ADR's no-LLM-judge rule we do not fake grounding with a judge instead.

Missing any of the three → today's single delegate_to(acp) shot runs,
byte-for-byte the same as before this PR. A carried-forward re-dispatch (CI bounce /
goal-fix / gate-fix, signalled by _ci_feedback) also skips the seam — same rule
Max-Mode already follows, since that re-dispatch fixes the existing diff with one
coder rather than fanning out fresh candidates.

Deferred (see ADR + notes)

• Compiling EARS acceptance criteria into generated tests. This is explicitly
  called out in the ADR as the "genuinely new work" and is more than one clean PR.
  The simplest-correct path used here instead: the coder is already prompted
  (_build_prompt) to write tests satisfying the acceptance criteria as part of its
  definition of done; verify() just runs whatever tests exist in the candidate
  worktree via the configured command and gates on the real exit code — honest
  execution, no fabricated grounding, but coarser-grained than a proper EARS→test
  compiler (the Verdict it returns doesn't name individual failing test cases,
  just pass/fail + the raw output tail as feedback).
• The fusion rung (P3) — not wired here; out of scope for P2.
• Candidate worktrees from a crash mid-ladder aren't tracked in _inflight until
  coder_seam.dispatch() returns (same pre-existing limitation Max-Mode's
  _dispatch_max_mode already has) — they self-heal on the next attempt via
  create_worktree's idempotent stale-worktree cleanup, but aren't reaped by the
  health sweep in between. A companion improvement, not blocking for this cut.

How to review / test

1. Read coder_seam.py top-to-bottom — it's the whole seam in one file.
2. loop.py diff: the one added elif branch in _drive's dispatch selection,
   the one line added to the capability tuple, and the new config fields in
   __init__. Everything else is untouched.
3. Tests: pytest tests/test_coder_seam.py — the dispatch decision
   (should_use_solve) and dispatch()'s orchestration (winner promoted, losers
   reaped, gens-spent surfaced, SolveExhausted on exhaustion) with plugins.coder.solve
   injected as fakes (no need for the actual coder plugin repo). pytest tests/test_loop.py -k coder_solve — the honest-degrade matrix at the _drive
   level (coder available+oracle → solve path; missing any gate → single shot;
   SolveExhausted → blocked like a capability failure; CI-bounce → skips the seam).
   pytest tests/test_store.py -k gens_spent — the cost-accounting label.
4. To exercise it live: enable both delegates + coder + project_board, declare
   an acp coder, set project_board.coder_solve_test_cmd (or local_gate_cmd) to
   your repo's real test command, and give a feature acceptance_criteria. Watch
   the loop create feat-<id>.g1, .g2, … candidate worktrees before promoting the
   winner to feat-<id>.

Gate output

$ ruff check .
All checks passed!

$ ruff format --check .
20 files already formatted

$ pytest -q
230 passed, 1 warning in 0.79s

(ruff pinned to 0.15.10 to match .github/workflows/ci.yml.)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com