feat(loop): execution-grounded Max-Mode candidate selection (ADR 0064)

[mabry1985]

The board-side (P2) realization of protoAgent ADR 0064 (coder: execution-grounded code-solve).

Problem

Max-Mode (max_mode_n > 1) builds a feature N ways in parallel, then _judge_candidates picks the winner with an LLM judge of the diffs ("Which candidate best satisfies the acceptance criteria? Reply with the number"). That's the exact judge-of-code ceiling ADR 0064 targets — a judge rewards plausible-looking code and can't catch subtle wrongness; only running the candidates discriminates.

Change

New _select_candidate: when a pre-PR gate (local_gate_cmd) is configured, prefer candidates whose gate actually passes — run the candidates, don't just judge them. The existing _judge_candidates then only:

• breaks ties among the passing set (quality among the correct), or
• decides when no gate is configured, or when none pass (judge the diffs, as before).

With no local_gate_cmd, behavior is unchanged (straight to the judge) — so this is purely additive and opt-in via the gate you already configure.

No cross-plugin import / substrate mismatch: the board's own worktree + local_gate_cmd are the verifier substrate (board candidates are worktree diffs, not module strings), so it realizes ADR 0064's principle natively rather than calling protoAgent's coder_solve.

Tests

_select_candidate + _candidate_diff_indices; _dispatch_max_mode calls it. 5 new tests (prefer passing gate; judge only among passing; fall back when none pass; no-gate uses judge and never runs the gate; None when no diff). 201 pass, ruff check + format clean. Version 0.24.0 → 0.25.0 (lockstep).

Implements protoLabsAI/protoAgent#1440 P2.

🤖 Generated with Claude Code

[protoquinn]

👀 Quinn is reviewing — verdict (PASS / WARN / FAIL) + findings to follow.

[protoquinn]

QA Audit — PR #59 | feat(loop): execution-grounded Max-Mode candidate selection (ADR 0064)

VERDICT: WARN (non-blocking — CI still running)

---

CI Status

• test: queued

Diff Review

• New _select_candidate in loop.py: execution-grounded selection — prefers candidates whose local_gate_cmd actually passes, delegating to the LLM judge only for tie-breaking, fallback, or when no gate is configured. Clean additive change; no-gate path is an early return to _judge_candidates preserving exact existing behavior.
• New _candidate_diff_indices helper: best-effort cheap name-only diff check (stage_all + git diff --cached --name-only). Correctly used as a pre-filter before running the gate.
• _dispatch_max_mode updated: _judge_candidates → _select_candidate. Docstring updated to reflect ADR 0064.
• Version bump 0.24.0 → 0.25.0, README docs updated with execution-grounded config note.

Observations

• LOW: clawpatch structural review unavailable (HTTP 500 — repo not in cache). Manual review only; no cross-file bugs detected from diff.
• LOW: _candidate_diff_indices calls stage_all on every candidate worktree and never unstages. Harmless in practice (losers are reaped, winner is promoted), but a comment noting the intentional leak would help future readers.
• LOW: _run_local_gate is gathered concurrently — if a gate hangs, all candidates wait. The existing coder_timeout watchdog may cover this, but worth confirming _run_local_gate has its own timeout.
• INFO: Index remapping in the tie-break path (passing[j]) is correct — _judge_candidates returns an index into the sublist, and passing[j] recovers the original worktree index.

— Quinn, QA Engineer

[protoquinn]

Submitted COMMENT review on protoLabsAI/projectBoard-plugin#59.