PR4: LLM roles + multi-round loop + history injection + cost guard

[Protocol-zero-0]

Closes #4. See overall roadmap at #5.

What this PR adds

Built on top of PR #2 (merged main). Four deliverables as specified in Issue #4:

Block 1 — Three roles wired to real LLM / coding agent

• roles/planner.py: calls Anthropic or OpenAI API; produces plan with summary, steps, abort signal
• roles/executor.sh: calls aider or claude-code (configurable); writes executor_output.json
• roles/evaluator.py: calls LLM to judge accept/reject; reports cost_usd + tokens_used

All choices (provider, model, api_key env var, coding tool) are config-driven — nothing hardcoded. Roles read config.json from their run directory (written by governor).

Block 2 — --loop flag (multi-round evolution)

cli.py gains --loop: runs run_once() in a loop until any hard stop triggers. Each iteration saves state atomically, so a crash mid-run leaves the ledger consistent.

Block 3 — History injection

Governor._build_history() scans ledger/runs/*/reflection.json before each run and injects the last N entries into planner_input.json. N is configurable via history.max_entries. Without this, multi-round planner has no memory.

Block 4 — Cost guard

HardStops gains max_total_usd and max_total_tokens (both default 0 = unlimited). HardStopState accumulates cost across rounds. precheck and record_outcome enforce limits alongside existing iteration limits. Evaluator reports per-round cost so kernel can track spend.

New config shape (evolution.yml)

llm:
  provider: anthropic        # anthropic | openai
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY

coding_agent:
  tool: aider                # aider | claude-code

history:
  max_entries: 10

hard_stops:
  max_iterations: 10
  max_consecutive_failures: 3
  max_total_usd: 1.00
  max_total_tokens: 500000

Verification

# All 39 tests pass (19 pre-existing + 20 new)
python3 -m pytest tests/ -v

# Multi-round loop with stub roles
evolution-kernel --config examples/evolution.yml --repo <repo> --ledger /tmp/led --loop

Not in this PR (see roadmap #5)

• Goal evaluator (knows when mission is accomplished) → PR5
• Strategist role → PR5
• k-branch parallel exploration → PR6
• Process sandbox → PR7

[Copilot]

Pull request overview

This PR advances the kernel from a single-run MVP toward a multi-round “evolution runtime” by adding (1) configurable real role implementations (planner/executor/evaluator), (2) a --loop CLI mode to run multiple rounds until hard stops trigger, (3) planner history injection from prior runs, and (4) spend/token hard stops with persisted accumulation across rounds.

Changes:

• Add default roles/ implementations for planner (LLM), executor (coding agent), and evaluator (LLM with cost reporting).
• Add --loop to run repeated Governor.run_once() iterations while persisting hard-stop state across rounds.
• Add history injection into planner_input.json, plus config schema extensions (llm, coding_agent, history, and cost guard fields).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/test_pr4.py	Adds unit/integration coverage for new config fields, cost guard behavior, history injection, and --loop.
roles/planner.py	Implements an LLM-backed planner role reading planner_input.json + config.json and writing plan.json.
roles/executor.sh	Implements executor role that calls Aider/Claude Code based on coding_agent.tool and writes executor_output.json.
roles/evaluator.py	Implements LLM evaluator role that emits accept/reject recommendation plus cost_usd/tokens_used.
examples/evolution.yml	Updates example config with new llm, coding_agent, history, and cost hard-stop fields; points roles to roles/.
evolution_kernel/hard_stops.py	Extends persisted hard-stop state to track cumulative USD and token usage; enforces new limits.
evolution_kernel/governor.py	Injects recent run history into planner_input.json via _build_history().
evolution_kernel/config.py	Adds config dataclasses/parsers for llm, coding_agent, history, and new cost hard-stops.
evolution_kernel/cli.py	Adds --loop mode and wires cost/tokens into persisted hard-stop state updates.

---

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