feat: Implement Evolution Engine V1 — autonomous code self-repair pipeline

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers

[AndrosEt]

Summary

This PR delivers the complete Evolution Engine V1 implementation: a self-purifying autonomous pipeline that reads an evolution.yml config, observes live evidence, lets an Actor LLM propose a minimal unified diff, has an independent Judge LLM audit it, and automatically opens a GitHub PR — all via the GitHub REST API, with no local git or gh CLI required.

---

What's Included

Core Pipeline (src/)

Module	Role
observer.py	Collects evidence from local files, shell scripts, and remote URLs into a structured bundle
actor.py	Calls LLM #1 with evidence + mission + principles; extracts a fenced unified diff
judge.py	Calls LLM #2 in a completely fresh, isolated session; returns structured JSON verdict (PASS/FAIL, overall_score, confidence, top_risks)
router.py	On PASS: creates branch, commits patch, opens PR via GitHub REST API; on FAIL: logs and exits cleanly
hard_stops.py	Persistent circuit breaker — halts on budget cap, consecutive failures, or daily iteration limits
llm.py	Unified LLM client supporting OpenAI-compatible providers; Actor/Judge isolation enforced at runtime
github_client.py	Pure HTTP GitHub integration; includes _normalize_diff() to rewrite incorrect LLM-generated hunk headers
config_loader.py	YAML config validation with human-readable error messages (no raw Python tracebacks)
history.py	Append-only JSONL audit trail (evolution_history.jsonl)
cli.py	evolve run / validate / reset commands

Key Design Decisions

Actor / Judge isolation is a hard requirement. The two LLMs run in completely separate sessions. The Judge receives only: mission, principles, evidence, and the final patch text — never the Actor's reasoning chain. Enforced at runtime.

Patch header normalization. LLMs occasionally emit incorrect or placeholder @@ hunk headers (wrong line counts, literal placeholders). _normalize_diff() recounts source/target lines from the actual diff body and rewrites every header before parsing, making the pipeline robust to LLM output variance.

Hard Stops (circuit breaker). State is persisted to .evolution_state.json. A triggered hard stop blocks all subsequent runs until explicitly reset with evolve reset, preventing runaway API spend or spam PRs.

Tests (tests/)

• test_v1.py — 45 unit/integration tests covering the full acceptance checklist:
  • Config validation error messages
  • Actor/Judge session isolation
  • Budget / consecutive-failure / daily-iteration hard stops
  • Hard stop persistence and evolve reset
  • FAIL verdict → no PR created
  • Judge returning invalid JSON → no crash, recorded as parse_error
• test_prd_11.py — End-to-end real-world scenario: Actor must autonomously infer a rate-limit fix from raw events alone, without any pre-fed diagnostics hints; Judge must pass based on event evidence only.

Examples & Docs

• examples/evolution.yml — reference config for a rate-limit auto-remediation mission
• examples/dashboard/metrics.json — sample evidence file (raw events, no diagnostics scaffolding in the stripped variant)
• examples/prompts/ — Actor and Judge system prompt templates
• README.md / README.zh.md — full documentation in English and Chinese
• CONTRACT_metrics_schema.md — schema contract for the metrics evidence format

---

How to Test

git clone <repo>&&cd evolution-engine
python3 -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"# Unit tests (no API keys needed)
pytest tests/test_v1.py -v
# Real-world end-to-end test (requires .env with ACTOR_* / JUDGE_* / GITHUB_*)
cp examples/.env.example examples/.env # fill in your keys
python tests/test_prd_11.py --verbose

---

Checklist

• All 45 unit tests pass
• Config validation produces human-readable errors (no raw tracebacks)
• Actor/Judge isolation verified via log output and JSONL history
• Hard stop persistence tested (halt survives process restart)
• evolve reset correctly clears halt state
• FAIL verdict produces no branch / no PR on GitHub
• Invalid Judge JSON handled gracefully
• _normalize_diff() covers both placeholder and wrong-count hunk headers