harness-evolver 4.0.3 → 4.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-evolver",
   "description": "LangSmith-native autonomous agent optimization — evolves LLM agent code using multi-agent proposers, LangSmith experiments, and git worktrees",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "author": {
     "name": "Raphael Valdetaro"
   },

package/README.md

@@ -67,8 +67,8 @@ claude
 <td>Proposers modify your actual agent code — not a wrapper. Each candidate works in an isolated git worktree. Winners are merged automatically.</td>
 </tr>
 <tr>
-<td><b>5 Adaptive Proposers</b></td>
-<td>Each iteration spawns 5 parallel agents: exploit, explore, crossover, and 2 failure-targeted. Strategies adapt based on per-task analysis. Quality-diversity selection preserves per-task champions.</td>
+<td><b>Self-Organizing Proposers</b></td>
+<td>Each iteration generates dynamic investigation lenses from failure data, architecture analysis, production traces, and evolution memory. Proposers self-organize their approach — no fixed strategies. They can self-abstain when their contribution would be redundant. Inspired by <a href="https://arxiv.org/abs/2603.28990">Dochkina (2026)</a>.</td>
 </tr>
 <tr>
 <td><b>Agent-Based Evaluation</b></td>
@@ -88,7 +88,7 @@ claude
 </tr>
 <tr>
 <td><b>Evolution Memory</b></td>
-<td>Cross-iteration memory consolidation inspired by Claude Code's autoDream. Tracks which strategies win, which failures recur, and promotes insights after 2+ occurrences.</td>
+<td>Cross-iteration memory consolidation inspired by Claude Code's autoDream. Tracks which approaches win, which failures recur, and promotes insights after 2+ occurrences.</td>
 </tr>
 <tr>
 <td><b>Smart Gating</b></td>
@@ -107,7 +107,7 @@ claude
 | Command | What it does |
 |---|---|
 | `/evolver:setup` | Explore project, configure LangSmith (dataset, evaluators), run baseline |
-| `/evolver:evolve` | Run the optimization loop (5 parallel proposers in worktrees) |
+| `/evolver:evolve` | Run the optimization loop (dynamic self-organizing proposers in worktrees) |
 | `/evolver:status` | Show progress, scores, history |
 | `/evolver:deploy` | Tag, push, clean up temporary files |
 
@@ -117,7 +117,7 @@ claude
 
 | Agent | Role | Color |
 |---|---|---|
-| **Proposer** | Modifies agent code in isolated worktrees based on trace analysis | Green |
+| **Proposer** | Self-organizing — investigates a data-driven lens, decides own approach, may abstain | Green |
 | **Evaluator** | LLM-as-judge — reads outputs via langsmith-cli, scores correctness | Yellow |
 | **Architect** | ULTRAPLAN mode — deep topology analysis with Opus model | Blue |
 | **Critic** | Active — detects gaming AND implements stricter evaluators | Red |
@@ -134,10 +134,10 @@ claude
   +- 0.5  Validate state (skeptical memory — check .evolver.json vs LangSmith)
   +- 1.   Read state (.evolver.json + LangSmith experiments)
   +- 1.5  Gather trace insights (cluster errors, tokens, latency)
-  +- 1.8  Analyze per-task failures (adaptive briefings)
-  +- 1.8a Synthesize strategy document (coordinator synthesis)
+  +- 1.8  Analyze per-task failures
+  +- 1.8a Synthesize strategy document + dynamic lenses (investigation questions)
   +- 1.9  Prepare shared proposer context (KV cache-optimized prefix)
-  +- 2.   Spawn 5 proposers in parallel (each in a git worktree)
+  +- 2.   Spawn N self-organizing proposers in parallel (each in a git worktree)
   +- 3.   Run target for each candidate (code-based evaluators)
   +- 3.5  Spawn evaluator agent (LLM-as-judge via langsmith-cli)
   +- 4.   Compare experiments -> select winner + per-task champion
@@ -165,7 +165,7 @@ Skills (markdown)
   └── /evolver:deploy   → tags and pushes
 
 Agents (markdown)
-  ├── Proposer (x5)     → modifies code in isolated git worktrees
+  ├── Proposer (xN)     → self-organizing, lens-driven, isolated git worktrees
   ├── Evaluator          → LLM-as-judge via langsmith-cli
   ├── Critic             → detects gaming + implements stricter evaluators
   ├── Architect          → ULTRAPLAN deep analysis (opus model)
@@ -182,7 +182,7 @@ Tools (Python + langsmith SDK)
   ├── iteration_gate.py     → three-gate iteration triggers
   ├── regression_tracker.py → tracks regressions, adds guard examples
   ├── consolidate.py        → cross-iteration memory consolidation
-  ├── synthesize_strategy.py→ generates strategy document for proposers
+  ├── synthesize_strategy.py→ generates strategy document + investigation lenses
   ├── add_evaluator.py      → programmatically adds evaluators
   └── adversarial_inject.py → detects memorization, injects adversarial tests
 ```
@@ -217,6 +217,7 @@ LangSmith traces **any** AI framework. The evolver works with all of them:
 ## References
 
 - [Meta-Harness: End-to-End Optimization of Model Harnesses](https://arxiv.org/abs/2603.28052) — Lee et al., 2026
+- [Drop the Hierarchy and Roles: How Self-Organizing LLM Agents Outperform Designed Structures](https://arxiv.org/abs/2603.28990) — Dochkina, 2026
 - [Darwin Godel Machine](https://sakana.ai/dgm/) — Sakana AI
 - [AlphaEvolve](https://deepmind.google/blog/alphaevolve/) — DeepMind
 - [LangSmith Evaluation](https://docs.smith.langchain.com/evaluation) — LangChain

package/agents/evolver-proposer.md

@@ -1,75 +1,56 @@
 ---
 name: evolver-proposer
 description: |
-  Use this agent to propose improvements to an LLM agent's code.
-  Works in an isolated git worktree — modifies real code, not a harness wrapper.
-  Spawned by the evolve skill with a strategy (exploit/explore/crossover/failure-targeted).
+  Self-organizing agent optimizer. Investigates a data-driven lens (question),
+  decides its own approach, and modifies real code in an isolated git worktree.
+  May self-abstain if it cannot add meaningful value.
 tools: Read, Write, Edit, Bash, Glob, Grep
 color: green
 permissionMode: acceptEdits
 ---
 
-# Evolver — Proposer Agent (v3)
+# Evolver — Self-Organizing Proposer (v4)
 
-You are an LLM agent optimizer. Your job is to modify the user's actual agent code to improve its performance on the evaluation dataset. You work in an **isolated git worktree** — you can modify any file freely without affecting the main branch.
+You are an LLM agent optimizer. Your job is to improve the user's agent code to score higher on the evaluation dataset. You work in an **isolated git worktree** — you can modify any file freely without affecting the main branch.
 
 ## Bootstrap
 
-Your prompt contains `<files_to_read>` and `<context>` blocks. You MUST:
+Your prompt contains `<files_to_read>`, `<context>`, and `<lens>` blocks. You MUST:
 1. Read every file listed in `<files_to_read>` using the Read tool
 2. Parse the `<context>` block for current scores, failing examples, and framework info
-3. Read the `<strategy>` block for your assigned approach
+3. Read the `<lens>` block — this is your investigation starting point
 
 ## Turn Budget
 
-You have a maximum of **16 turns** to complete your proposal. Budget them:
-- Turns 1-3: Orient (read files, understand codebase)
-- Turns 4-6: Diagnose (read insights, identify targets)
-- Turns 7-12: Implement (make changes, consult docs)
-- Turns 13-14: Test (verify changes don't break the entry point)
-- Turns 15-16: Commit and document
+You have a maximum of **16 turns**. You decide how to allocate them. General guidance:
+- Spend early turns reading context and investigating your lens question
+- Spend middle turns implementing changes and consulting documentation
+- Reserve final turns for committing and writing proposal.md
 
 **If you're past turn 12 and haven't started implementing**, simplify your approach. A small, focused change that works is better than an ambitious change that's incomplete.
 
 **Context management**: After turn 8, avoid re-reading files you've already read. Reference your earlier analysis instead of re-running Glob/Grep searches.
 
-## Strategy Injection
+## Lens Protocol
 
-Your prompt contains a `<strategy>` block. Follow it:
-- **exploitation**: Conservative fix on current best. Focus on specific failing examples.
-- **exploration**: Bold, fundamentally different approach. Change algorithms, prompts, routing.
-- **crossover**: Combine strengths from previous iterations. Check git log for recent changes.
-- **failure-targeted**: Fix SPECIFIC failing examples listed in the strategy. Analyze WHY they fail.
-- **creative**: Try something unexpected — different libraries, architecture, algorithms.
-- **efficiency**: Same quality but fewer tokens, faster latency, simpler code.
+Your prompt contains a `<lens>` block with an **investigation question**. This is your starting point, not your mandate.
 
-If no strategy block is present, default to exploitation.
+1. **Investigate** — dig into the data relevant to the lens question (trace insights, failing examples, code)
+2. **Hypothesize** — form your own theory about what to change
+3. **Decide** — choose your approach freely. You may end up solving something completely different from what the lens asks. That's fine.
+4. **Implement or Abstain** — if you can add meaningful value, implement and commit. If not, abstain.
 
-## Your Workflow
-
-### Phase 1: Orient
-
-Read .evolver.json to understand:
-- What framework is this? (LangGraph, CrewAI, OpenAI SDK, etc.)
-- What's the entry point?
-- What evaluators are active? (correctness, conciseness, latency, etc.)
-- What's the current best score?
+You are NOT constrained to the lens topic. The lens gives you a starting perspective. Your actual approach is yours to decide.
 
-### Phase 2: Diagnose
+## Your Workflow
 
-Read trace_insights.json and best_results.json to understand:
-- Which examples are failing and why?
-- What error patterns exist?
-- Are there token/latency issues?
+There are no fixed phases. Use your judgment to allocate turns. A typical flow:
 
-If production_seed.json exists, read it to understand real-world usage:
-- What do real user inputs look like?
-- What are the common error patterns in production?
-- Which query types get the most traffic?
+**Orient** — Read .evolver.json, strategy.md, evolution_memory.md. Understand the framework, entry point, evaluators, current score, and what has been tried before.
 
-### Phase 3: Propose Changes
+**Investigate** — Read trace_insights.json and best_results.json. Understand which examples fail and why. If production_seed.json exists, understand real-world usage patterns. Focus on data relevant to your lens question.
 
-Based on your strategy and diagnosis, modify the code:
+**Decide** — Based on investigation, decide what to change. Consider:
 - **Prompts**: system prompts, few-shot examples, output format instructions
 - **Routing**: how queries are dispatched to different handlers
 - **Tools**: tool definitions, tool selection logic
@@ -77,7 +58,23 @@ Based on your strategy and diagnosis, modify the code:
 - **Error handling**: retry logic, fallback strategies, timeout handling
 - **Model selection**: which model for which task
 
-### Phase 3.5: Consult Documentation (MANDATORY)
+## Self-Abstention
+
+If after investigating your lens you conclude you cannot add meaningful value, you may **abstain**. This is a valued contribution — it saves evaluation tokens and signals confidence that the current code handles the lens topic adequately.
+
+To abstain, skip implementation and write only a `proposal.md`:
+
+```
+## ABSTAIN
+- **Lens**: {the question you investigated}
+- **Finding**: {what you discovered during investigation}
+- **Reason**: {why you're abstaining}
+- **Suggested focus**: {optional — what future iterations should look at}
+```
+
+Then end with the return protocol using `ABSTAIN` as your approach.
+
+### Consult Documentation (MANDATORY)
 
 **Before writing ANY code**, you MUST consult Context7 for every library you'll be modifying or using. This is NOT optional.
 
@@ -106,7 +103,7 @@ Ask about the SPECIFIC API you're going to use or change.
 
 **If Context7 MCP is not available:** Note in proposal.md "API patterns not verified against current docs — verify before deploying."
 
-### Phase 4: Commit and Document
+### Commit and Document
 
 1. **Commit all changes** with a descriptive message:
    ```bash
@@ -143,7 +140,7 @@ Prioritize changes that fix real production failures over synthetic test failure
 ## Rules
 
 1. **Read before writing** — understand the code before changing it
-2. **Minimal changes** — change only what's needed for your strategy
+2. **Focused changes** — change what's needed based on your investigation. Don't scatter changes across unrelated files.
 3. **Don't break the interface** — the agent must still be runnable with the same command
 4. **Commit your changes** — uncommitted changes are lost when the worktree is cleaned up
 5. **Write proposal.md** — the evolve skill reads this to understand what you did
@@ -153,8 +150,9 @@ Prioritize changes that fix real production failures over synthetic test failure
 When done, end your response with:
 
 ## PROPOSAL COMPLETE
-- **Version**: v{NNN}{suffix}
-- **Strategy**: {strategy}
+- **Version**: v{NNN}-{id}
+- **Lens**: {the investigation question}
+- **Approach**: {what you chose to do and why — free text, your own words}
 - **Changes**: {brief list of files changed}
 - **Expected impact**: {which evaluators/examples should improve}
 - **Files modified**: {count}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-evolver",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "description": "LangSmith-native autonomous agent optimization for Claude Code",
   "author": "Raphael Valdetaro",
   "license": "MIT",

package/skills/evolve/SKILL.md

@@ -175,7 +175,7 @@ fi
 ```
 
 If `best_results.json` exists, parse it to find failing examples (score < 0.7). Group by metadata or error pattern.
-Generate adaptive briefings for Candidates D and E (same logic as v2).
+This failure data feeds into `synthesize_strategy.py` which generates targeted lenses for proposers.
 If no best_results.json (first iteration without baseline), all proposers work from code analysis only — no failure data available.
 
 ### 1.8a. Synthesize Strategy
@@ -189,17 +189,18 @@ $EVOLVER_PY $TOOLS/synthesize_strategy.py \
     --best-results best_results.json \
     --evolution-memory evolution_memory.json \
     --production-seed production_seed.json \
-    --output strategy.md 2>/dev/null
+    --output strategy.md \
+    --lenses lenses.json 2>/dev/null
 ```
 
-The `strategy.md` file is included in the proposer `<files_to_read>` block via the shared context (Step 1.9). It synthesizes trace analysis, evolution memory, and production data into an actionable document. Proposers also receive `production_seed.json` directly for access to raw production traces.
+The `strategy.md` file is included in the proposer `<files_to_read>` block via the shared context (Step 1.9). The `lenses.json` file contains dynamically generated investigation questions — one per proposer. Each lens directs a proposer's attention to a different aspect of the problem (failure cluster, architecture, production data, evolution memory, or open investigation).
 
 ### 1.9. Prepare Shared Proposer Context
 
-Build the shared context that ALL proposers will receive as an identical prefix. This enables KV cache sharing — spawning 5 proposers costs barely more than 1.
+Build the shared context that ALL proposers will receive as an identical prefix. This enables KV cache sharing — spawning N proposers costs barely more than 1.
 
 ```bash
-# Build shared context block (identical for all 5 proposers)
+# Build shared context block (identical for all proposers)
 SHARED_FILES_BLOCK="<files_to_read>
 - .evolver.json
 - strategy.md (if exists)
@@ -223,13 +224,19 @@ You are working in an isolated git worktree — modify any file freely.
 </objective>"
 ```
 
-**CRITICAL for cache sharing**: The `<objective>`, `<files_to_read>`, and `<context>` blocks MUST be byte-identical across all 5 proposer prompts. Only the `<strategy>` block differs. Place the strategy block LAST in the prompt so the shared prefix is maximized.
+**CRITICAL for cache sharing**: The `<objective>`, `<files_to_read>`, and `<context>` blocks MUST be byte-identical across all proposer prompts. Only the `<lens>` block differs. Place the lens block LAST in the prompt so the shared prefix is maximized.
 
-### 2. Spawn 5 Proposers in Parallel
+### 2. Spawn Proposers in Parallel (Dynamic Lenses)
 
-Each proposer receives the IDENTICAL prefix (objective + files + context) followed by its unique strategy suffix.
+Read `lenses.json` to get the list of investigation lenses:
 
-**All 5 candidates** — `run_in_background: true, isolation: "worktree"`:
+```bash
+LENS_COUNT=$(python3 -c "import json; print(json.load(open('lenses.json'))['lens_count'])")
+```
+
+Each proposer receives the IDENTICAL prefix (objective + files + context) followed by its unique lens.
+
+**For each lens** — `run_in_background: true, isolation: "worktree"`:
 
 The prompt for EACH proposer follows this structure:
 ```
@@ -239,66 +246,54 @@ The prompt for EACH proposer follows this structure:
 
 {SHARED_CONTEXT_BLOCK}
 
-<strategy>
-{UNIQUE PER CANDIDATE — see below}
-</strategy>
-
-<output>
-1. Modify the code to improve performance
-2. Commit your changes with a descriptive message
-3. Write proposal.md explaining what you changed and why
-</output>
-```
+<lens>
+Investigation question: {lens.question}
 
-**Candidate A strategy block:**
-```
-APPROACH: exploitation
-Make targeted improvements to the current best version.
-Focus on the specific failures identified in the results.
-```
+This is your STARTING POINT, not your mandate. Investigate, form your
+own hypothesis, and implement whatever you conclude will help most.
+You may solve something entirely different — that's fine.
+If you cannot add meaningful value, ABSTAIN.
 
-**Candidate B strategy block:**
-```
-APPROACH: exploration
-Try a fundamentally different approach. Change algorithms, prompts, routing, architecture.
-Don't be afraid to make big changes — this worktree is disposable.
-```
+Source: {lens.source}
+</lens>
 
-**Candidate C strategy block:**
-```
-APPROACH: crossover
-Combine strengths from previous iterations. Check git log for what was tried.
-Recent changes: {git_log_last_5}
+<output>
+1. Investigate the lens question
+2. Decide your approach (or abstain)
+3. If proceeding: modify code, commit, write proposal.md
+4. proposal.md must include: what you chose to do, why, how it relates to the lens
+</output>
 ```
 
-**Candidate D strategy block:**
-```
-APPROACH: {failure_targeted_or_creative}
-{adaptive_briefing_d}
-```
+For each lens in `lenses.json`, spawn one proposer agent:
 
-**Candidate E strategy block:**
 ```
-APPROACH: {failure_targeted_or_efficiency}
-{adaptive_briefing_e}
+Agent(
+  subagent_type: "evolver-proposer",
+  description: "Proposer {lens.id}: {lens.source} lens",
+  isolation: "worktree",
+  run_in_background: true,
+  prompt: {SHARED_PREFIX + LENS_BLOCK above, with lens fields filled in}
+)
 ```
 
-Wait for all 5 to complete.
+Wait for all proposers to complete.
 
 **Stuck proposer detection**: If any proposer hasn't completed after 10 minutes, it may be stuck in a loop. The Claude Code runtime handles this via the agent's turn limit. If a proposer returns without committing changes, skip it — don't retry.
 
-After all proposers complete, check which ones actually committed:
+After all proposers complete, check which ones committed and which abstained:
 
 ```bash
 for WORKTREE in {worktree_paths}; do
-    CHANGES=$(cd "$WORKTREE" && git log --oneline -1 --since="10 minutes ago" 2>/dev/null | wc -l)
-    if [ "$CHANGES" -eq 0 ]; then
+    if [ -f "$WORKTREE/proposal.md" ] && grep -q "## ABSTAIN" "$WORKTREE/proposal.md" 2>/dev/null; then
+        echo "Proposer in $WORKTREE abstained — skipping evaluation"
+    elif [ $(cd "$WORKTREE" && git log --oneline -1 --since="10 minutes ago" 2>/dev/null | wc -l) -eq 0 ]; then
         echo "Proposer in $WORKTREE made no commits — skipping"
     fi
 done
 ```
 
-Only run evaluation (Step 3) for proposers that committed changes.
+Only run evaluation (Step 3) for proposers that committed changes (not abstained, not stuck).
 
 ### 3. Run Target for Each Candidate
 
@@ -308,7 +303,7 @@ For each worktree that has changes (proposer committed something):
 $EVOLVER_PY $TOOLS/run_eval.py \
     --config .evolver.json \
     --worktree-path {worktree_path} \
-    --experiment-prefix v{NNN}{suffix} \
+    --experiment-prefix v{NNN}-{lens_id} \
     --timeout 120
 ```
 
@@ -339,11 +334,7 @@ Agent(
   prompt: |
     <experiment>
     Evaluate the following experiments (one per candidate):
-    - {experiment_name_a}
-    - {experiment_name_b}
-    - {experiment_name_c}
-    - {experiment_name_d}
-    - {experiment_name_e}
+    {list all experiment names from proposers that committed changes — skip abstained}
     </experiment>
 
     <evaluators>
@@ -370,14 +361,14 @@ Wait for the evaluator agent to complete before proceeding.
 
 ```bash
 $EVOLVER_PY $TOOLS/read_results.py \
-    --experiments "v{NNN}a,v{NNN}b,v{NNN}c,v{NNN}d,v{NNN}e" \
+    --experiments "{comma-separated list of experiment names from non-abstained proposers}" \
     --config .evolver.json \
     --output comparison.json
 ```
 
 Parse `comparison.json`:
 - `comparison.winner` — highest combined score
-- `comparison.champion` — per-task champion (for next crossover)
+- `comparison.champion` — per-task champion (for next iteration's context)
 - `comparison.all_candidates` — all scores for reporting
 
 ### 5. Merge Winner
@@ -389,7 +380,7 @@ If the winner scored higher than the current best:
 WINNER_BRANCH={winning_worktree_branch}
 
 # Merge into main
-git merge $WINNER_BRANCH --no-edit -m "evolve: merge v{NNN}{suffix} (score: {score})"
+git merge $WINNER_BRANCH --no-edit -m "evolve: merge v{NNN}-{lens_id} (score: {score})"
 ```
 
 Update `.evolver.json`:
@@ -409,14 +400,14 @@ json.dump(c, open('.evolver.json', 'w'), indent=2)
 
 Report ALL candidates:
 ```
-Iteration {i}/{N} — 5 candidates evaluated:
-  v{NNN}a (exploit):     {score_a} — {summary}
-  v{NNN}b (explore):     {score_b} — {summary}
-  v{NNN}c (crossover):   {score_c} — {summary}
-  v{NNN}d ({strategy}):  {score_d} — {summary}
-  v{NNN}e ({strategy}):  {score_e} — {summary}
+Iteration {i}/{N} — {lens_count} lenses, {evaluated_count} candidates evaluated ({abstained_count} abstained):
+  {For each proposer, read proposal.md and extract the Approach field}
+  v{NNN}-1 ({approach from proposal.md}):  {score} — {summary}
+  v{NNN}-2 ({approach from proposal.md}):  {score} — {summary}
+  v{NNN}-3 (ABSTAINED):                    --    — {reason from proposal.md}
+  ...
 
-  Winner: v{NNN}{suffix} ({score}) — merged into main
+  Winner: v{NNN}-{id} ({score}) — merged into main
   Per-task champion: {champion} (beats winner on {N} tasks)
 ```
 

package/tools/consolidate.py

@@ -94,24 +94,16 @@ def consolidate(orientation, signals, existing_memory=None):
     """Phase 3: Merge signals into consolidated memory."""
     insights = []
 
-    # Strategy effectiveness
+    # Winning approach tracking (from comparison data)
     winning = signals.get("winning_strategies", [])
-    strategy_map = {"a": "exploit", "b": "explore", "c": "crossover", "d": "failure-targeted-1", "e": "failure-targeted-2"}
-    win_counts = {}
-    for w in winning:
-        exp = w.get("experiment", "")
-        if exp:
-            suffix = exp[-1]
-            name = strategy_map.get(suffix, suffix)
-            win_counts[name] = win_counts.get(name, 0) + 1
-
-    if win_counts:
-        best_strategy = max(win_counts, key=win_counts.get)
+    if winning:
+        win_count = len(winning)
+        best_score = max(w.get("score", 0) for w in winning)
         insights.append({
             "type": "strategy_effectiveness",
-            "insight": f"Most winning strategy: {best_strategy} ({win_counts[best_strategy]} wins)",
-            "recurrence": win_counts[best_strategy],
-            "data": win_counts,
+            "insight": f"Best candidate score: {best_score:.3f} across {win_count} iterations",
+            "recurrence": win_count,
+            "data": {"win_count": win_count, "best_score": best_score},
         })
 
     # Recurring failures (only promote if seen 2+ times)

package/tools/synthesize_strategy.py

@@ -1,10 +1,15 @@
 #!/usr/bin/env python3
-"""Synthesize evolution strategy document from trace analysis.
+"""Synthesize evolution strategy document and investigation lenses.
 
 Reads trace_insights.json, best_results.json, evolution_memory.json,
 and production_seed.json to produce a targeted strategy document with
 specific file paths and concrete change recommendations for proposers.
 
+When --lenses is specified, also generates a lenses.json file containing
+investigation questions derived from failure clusters, architecture issues,
+production data, and evolution memory. Each lens becomes a focused brief
+for one proposer agent.
+
 Usage:
     python3 synthesize_strategy.py \
         --config .evolver.json \
@@ -12,7 +17,8 @@ Usage:
         --best-results best_results.json \
         --evolution-memory evolution_memory.json \
         --production-seed production_seed.json \
-        --output strategy.md
+        --output strategy.md \
+        --lenses lenses.json
 """
 
 import argparse
@@ -120,6 +126,118 @@ def synthesize(config, insights, results, memory, production=None):
     return strategy
 
 
+def generate_lenses(strategy, config, insights, results, memory, production, max_lenses=5):
+    """Generate investigation lenses from available data sources."""
+    lenses = []
+    lens_id = 0
+
+    # Failure cluster lenses (one per distinct cluster, max 3)
+    for cluster in strategy.get("failure_clusters", [])[:3]:
+        lens_id += 1
+        desc = cluster["description"]
+        severity = cluster["severity"]
+        examples = []
+        for ex in strategy.get("failing_examples", []):
+            if ex.get("error") and cluster.get("type", "") in str(ex.get("error", "")):
+                examples.append(ex["example_id"])
+        if not examples:
+            examples = [ex["example_id"] for ex in strategy.get("failing_examples", [])[:3]]
+        lenses.append({
+            "id": lens_id,
+            "question": f"{desc} — what code change would fix this?",
+            "source": "failure_cluster",
+            "severity": severity,
+            "context": {"examples": examples[:5]},
+        })
+
+    # Architecture lens from trace insights
+    if insights:
+        for issue in insights.get("top_issues", []):
+            if issue.get("severity") == "high" and issue.get("type") in (
+                "architecture", "routing", "topology", "structure",
+            ):
+                lens_id += 1
+                lenses.append({
+                    "id": lens_id,
+                    "question": f"Architectural issue: {issue['description']} — what structural change would help?",
+                    "source": "architecture",
+                    "severity": "high",
+                    "context": {"issue_type": issue["type"]},
+                })
+                break  # at most 1 architecture lens
+
+    # Production lens
+    if production:
+        prod_issues = []
+        neg = production.get("negative_feedback_inputs", [])
+        if neg:
+            prod_issues.append(f"Users gave negative feedback on {len(neg)} queries")
+        errors = production.get("error_patterns", production.get("errors", []))
+        if errors and isinstance(errors, list) and len(errors) > 0:
+            prod_issues.append(f"Production errors: {str(errors[0])[:100]}")
+        slow = production.get("slow_queries", [])
+        if slow:
+            prod_issues.append(f"{len(slow)} slow queries detected")
+        if prod_issues:
+            lens_id += 1
+            lenses.append({
+                "id": lens_id,
+                "question": f"Production data shows: {'; '.join(prod_issues)}. How should the agent handle these real-world patterns?",
+                "source": "production",
+                "severity": "high",
+                "context": {},
+            })
+
+    # Evolution memory lens — winning patterns
+    if memory:
+        for insight in memory.get("insights", []):
+            if insight.get("type") == "strategy_effectiveness" and insight.get("recurrence", 0) >= 2:
+                lens_id += 1
+                lenses.append({
+                    "id": lens_id,
+                    "question": f"{insight['insight']} — what further improvements in this direction are possible?",
+                    "source": "evolution_memory",
+                    "severity": "medium",
+                    "context": {"recurrence": insight["recurrence"]},
+                })
+                break  # at most 1 memory lens
+
+    # Evolution memory lens — persistent failures
+    if memory:
+        for insight in memory.get("insights", []):
+            if insight.get("type") == "recurring_failure" and insight.get("recurrence", 0) >= 3:
+                lens_id += 1
+                lenses.append({
+                    "id": lens_id,
+                    "question": f"{insight['insight']} — this has persisted {insight['recurrence']} iterations. Why?",
+                    "source": "persistent_failure",
+                    "severity": "critical",
+                    "context": {"recurrence": insight["recurrence"]},
+                })
+                break  # at most 1 persistent failure lens
+
+    # Open lens (always included)
+    lens_id += 1
+    lenses.append({
+        "id": lens_id,
+        "question": "Open investigation — read all context and investigate what stands out most to you.",
+        "source": "open",
+        "severity": "medium",
+        "context": {},
+    })
+
+    # Sort by severity, take top max_lenses
+    severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+    lenses.sort(key=lambda l: severity_order.get(l["severity"], 2))
+    lenses = lenses[:max_lenses]
+
+    # Reassign sequential IDs after sorting/truncating
+    for i, lens in enumerate(lenses):
+        lens["id"] = i + 1
+
+    return lenses
+
+
 def format_strategy_md(strategy, config):
     """Format strategy as markdown document."""
     lines = [
@@ -197,6 +315,7 @@ def main():
     parser.add_argument("--evolution-memory", default="evolution_memory.json")
     parser.add_argument("--production-seed", default="production_seed.json")
     parser.add_argument("--output", default="strategy.md")
+    parser.add_argument("--lenses", default=None, help="Output path for lenses JSON")
     args = parser.parse_args()
 
     with open(args.config) as f:
@@ -217,6 +336,23 @@ def main():
     with open(json_path, "w") as f:
         json.dump(strategy, f, indent=2)
 
+    # Generate lenses if requested
+    if args.lenses:
+        max_proposers = config.get("max_proposers", 5)
+        lens_list = generate_lenses(
+            strategy, config, insights, results, memory, production,
+            max_lenses=max_proposers,
+        )
+        from datetime import datetime, timezone
+        lenses_output = {
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "lens_count": len(lens_list),
+            "lenses": lens_list,
+        }
+        with open(args.lenses, "w") as f:
+            json.dump(lenses_output, f, indent=2)
+        print(f"Generated {len(lens_list)} lenses → {args.lenses}", file=sys.stderr)
+
     print(md)