feat: k-branch parallel exploration (closes #14)

[Protocol-zero-0]

Summary

• New Governor.run_once_parallel(goal, k) launches k independent worktrees per round, each running plan → execute → evaluate; the highest-fitness survivor is promoted to evolution/accepted, the rest land in ledger/failed/.
• parallel.k_branches config field (default 1); k=1 delegates to the existing run_once so the v0.2 + phase-2 behavior is byte-for-byte preserved.
• Evaluator role now emits a float fitness; back-compat synthesizes fitness from hard_gates_passed when an older evaluator omits it.
• Per-round cost and tokens are summed across all k branches so hard-stop bookkeeping in _run_loop still ticks correctly.

Test plan

• All 54 existing tests pass (v0.2 + phase 2).
• 13 new tests under tests/test_issue14.py covering:
  • Config defaults / parsing / validation
  • k=1 parity with run_once
  • k>1 fan-out (3 run dirs with full per-branch artifacts)
  • Highest-fitness branch promotion to evolution/accepted
  • Loser ledger demotion (failed/<run_id>-summary.json)
  • All k worktrees cleaned up; experiment branches preserved
  • Cost/tokens summed across k branches
  • Partial scope violation: violator rejected, winner picked from in-scope set
  • All-fail round leaves accepted unchanged
  • End-to-end k=3 over 3 rounds via CLI --loop → 9 runs, 3 accepted, 6 failed summaries

$ PYTHONPATH=. python3 -m pytest tests/ -v
…
============================== 67 passed in 21.42s ==============================

Why

This is the population-level exploration primitive — the kernel can now escape local optima the way FunSearch / AlphaEvolve do: by running siblings in parallel and keeping the best.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds k-branch parallel exploration: a new Governor.run_once_parallel runs k sibling branches per round, ranks them by a new evaluator fitness float, promotes the highest scorer to evolution/accepted, and demotes the rest into ledger/failed/. CLI dispatches to the parallel path whenever parallel.k_branches > 1 (default 1 preserves prior run_once behavior byte-for-byte). The evaluator role and prompt now emit/back-compat-synthesize fitness, and per-round cost/tokens are summed across branches for hard-stop accounting.

Changes:

• New ParallelConfig (parallel.k_branches, default 1) with strict validation; CLI threads it through both single-run and --loop paths.
• New Governor.run_once_parallel and helpers _run_single_branch / _select_winner; evaluator role gains a fitness field with back-compat synthesis from hard_gates_passed.
• 13 new tests in tests/test_issue14.py plus four fixture scripts (per-branch fitness evaluators/executors, unique-marker executor, scope-violator executor) exercising config, k=1 parity, k>1 fan-out, winner promotion, loser demotion, worktree cleanup, cost/token aggregation, partial scope violations, all-fail rounds, and a 3-round CLI integration test.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
evolution_kernel/config.py	Adds ParallelConfig dataclass and _parse_parallel with positive-int validation.
evolution_kernel/governor.py	Adds run_once_parallel, _run_single_branch, _select_winner; duplicates much of run_once to support per-branch decisions, fitness ranking, and aggregated cost/tokens.
evolution_kernel/cli.py	Dispatches to run_once_parallel when cfg.parallel.k_branches > 1 in both single-run and loop paths.
roles/evaluator.py	Documents new fitness field in the prompt and back-compat-derives it from hard_gates_passed when absent.
README.md / README.zh.md	Marks goal-evaluator and k-branch features as ✅ and documents the new parallel: config block.
tests/test_issue14.py	13 tests covering config parsing, k=1 parity, k>1 fan-out, winner/loser handling, cleanup, cost summation, scope violations, all-fail rounds, and CLI loop.
tests/fixtures/evaluator_branch_fitness.py	Reads fitness from EVOLUTION_MARKER.txt; emits hard_gates_passed/fitness/cost/tokens.
tests/fixtures/evaluator_src_fitness.py	Same evaluator pattern but reads src/marker.txt for scope-violation test.
tests/fixtures/executor_branch.py	Writes per-run fitness hint into EVOLUTION_MARKER.txt.
tests/fixtures/executor_oob_for_run.py	Writes out-of-scope file only for the configured violating run_id.
tests/fixtures/executor_unique_marker.py	Produces unique content per run_id so each branch creates a real diff.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.