v2.0 Phase 3: Variant evolution orchestrator + Scientist + Spawner

[ty13r]

Summary

Phase 3 of v2.0 — the variant evolution orchestrator. This is the wave where atomic evolution actually starts running. One commit, three waves, stacks on Phase 2 (PR #3 / ca7d154).

• Wave 3-1: skillforge/engine/variant_evolution.py — run_variant_evolution(run) reads variant_evolutions rows for the parent run, sorts foundation-first, runs each dimension as a mini-evolution (design focused challenge → spawn N variants → run via Competitor → judging pipeline → pick winner → persist as Variant row → mark VariantEvolution complete), then calls a stub assembly that returns the foundation winner unchanged. Wired into evolution.py::run_evolution as a top-level dispatcher: run.evolution_mode == "atomic" delegates here, falls back to molecular cleanly if no rows exist.
• Wave 3-2: design_variant_challenge(specialization, dimension) added to challenge_designer.py. Single streaming Anthropic call returning ONE focused Challenge per dimension.
• Wave 3-3: spawn_variant_gen0(specialization, dimension, foundation_genome, pop_size) added to spawner.py. Focused mini-SKILL.md generator. For capability tier, the winning foundation is injected into the system prompt so spawned variants are compatible with the foundation's directory layout. Stamps dimension + tier keys into each spawned genome's frontmatter.

Routes wiring

_classify_run_via_taxonomist in routes.py now persists VariantEvolution rows (one per dimension) when the final run mode is atomic, so the orchestrator has work to pick up. The route handler reorders save_run to come before the variant_evolution INSERTs so the FK on parent_run_id resolves.

Stub assembly (Phase 4 will replace)

The Engineer agent's real merge logic is Wave 4-1. Phase 3 ships with a stub that:

• Returns the highest-fitness foundation variant as the composite when one exists.
• Falls back to the highest-fitness capability variant if no foundation dimension was defined.
• Emits assembly_started + assembly_complete events with synergy_ratio: null.

This unblocks the full atomic event sequence (taxonomy_classified → decomposition_complete → variant_evolution_started × N → variant_evolution_complete × N → assembly_started → assembly_complete → evolution_complete) without blocking on Phase 4.

Bug fixes (latent in earlier phases)

Phase 3 surfaced two test-isolation bugs from earlier waves:

1. test_list_family_variants_empty_by_default asserted that fams[0] had zero variants — but Phase 3's happy-path test now persists variants under a fam_phase3 family, polluting the global DB. Pinned the assertion to a known seed family (terraform-module-full) that no other test populates.
2. test_evolve_taxonomist_integration — the mocks bypass the real classify_and_decompose persistence path, so the routes.py downstream code that persists VariantEvolution rows (with FK to skill_families) failed because the mocked family was never inserted. Fix: tests now manually seed the mocked taxonomy + family before the request fires. Mock slugs prefixed with test-fixture- to avoid colliding with the bootstrap loader's testing/unit-tests/python triple.

Quantitative signal

• 81 v2.0 backend tests passing (55 Phase 1 + 18 Phase 2 + 8 Phase 3)
• ruff clean on all Phase 3 files
• Frontend untouched in Phase 3 (Phase 4 / 5 surface the variant breakdown UI)

What's not in this PR

• Real Engineer assembly (Wave 4-1) — composite skill merging with conflict resolution, integration test, refinement pass
• Per-dimension breeding loops — Phase 3 spawns once and picks the winner. Wave 4 will add a multi-generation breeding loop per dimension
• Variant breakdown UI (Phase 5)

Test plan

• uv run pytest tests/test_variant_evolution.py -q — 8/8 green
• uv run pytest tests/test_taxonomist.py tests/test_evolve_taxonomist_integration.py -q — 18/18 green (Phase 2 baseline preserved)
• uv run pytest tests/test_models_v2.py tests/test_db_v2.py tests/test_taxonomy_queries.py tests/test_taxonomy_api.py tests/test_report.py -q — 55/55 green (Phase 1 baseline preserved)
• uv run ruff check skillforge/engine/variant_evolution.py skillforge/engine/evolution.py skillforge/agents/challenge_designer.py skillforge/agents/spawner.py skillforge/api/routes.py tests/test_variant_evolution.py — clean
• Manual end-to-end via the browser (after merge — requires a real dev server + a real /new form submission with evolution_mode: atomic)

Next up

v2.0/phase4-engineer branch — the Engineer agent's real assembly logic, composite skill validation, integration test, and one refinement pass per assembly. Stacks on this PR's main.

🤖 Generated with Claude Code