evolve

# ooo evolve - Evolutionary Loop

## Description
Start, monitor, or rewind an evolutionary development loop. The loop iteratively
refines the ontology and acceptance criteria across generations until convergence.

## Flow
```
Gen 1: Seed(O₁) → Execute(all nodes) → Judge → Gate
Gen 2: Wonder(failed nodes) → Reflect(active nodes only) → Execute(active) → Gate(all)
Gen 3: Repeat with a smaller active set; frozen PASS nodes are reverified, not regenerated
...until the outcome gate passes, the working set stagnates, ontology converges,
or max 30 generations is reached
```

## Usage

### Start a new evolutionary loop
```
ooo evolve "build a task management CLI"
```

### Fast mode (ontology-only, no execution)
```
ooo evolve "build a task management CLI" --no-execute
```

### Check lineage status
```
ooo evolve --status <lineage_id>
```

### Record an isolated full-graph benchmark control
Call `ouroboros_evolve_step` for an existing Gen 2+ lineage with
`benchmark_control: true`, `execute: true`, and an explicit clean Git
`project_dir`. Use a distinct clean worktree at the treatment commit. Normal
evolve calls keep `benchmark_control` false and never launch a control arm.

### Rewind to a previous generation
```
ooo evolve --rewind <lineage_id> <generation_number>
```

## Instructions

### Load MCP Tools (Required before Path A/B decision)

The Ouroboros MCP tools are often registered as **deferred tools** that must be explicitly loaded before use. **You MUST perform this step before deciding between Path A and Path B.**

1. Use the active runtime's tool-discovery capability to find and load the evolve MCP tools:
   ```
   tool discovery query: "+ouroboros evolve"
   ```
2. The tools will typically be named with prefix `mcp__plugin_ouroboros_ouroboros__` (e.g., `ouroboros_evolve_step`, `ouroboros_interview`, `ouroboros_generate_seed`). After runtime tool discovery returns, the tools become callable.
3. If the tools are callable — already exposed, or loaded by discovery — proceed to **Path A**. An empty discovery result for already-exposed tools is expected, not a failure. Proceed to **Path B** only if they are genuinely absent (no Ouroboros MCP server).

**IMPORTANT**: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.

**CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"):**
This skill makes `ouroboros_*` MCP calls across multiple turns, and each turn runs
in a fresh tool context. A deferred tool's schema loaded on one turn is NOT
guaranteed to still be loaded on the next. If you call any `ouroboros_*` MCP tool
while its schema is not loaded in the **current** turn, the runtime rejects the
call with **"Invalid tool parameters"** before it ever reaches the server.
Therefore: **immediately before EVERY `ouroboros_*` MCP call in this skill, re-run
the tool-discovery load query for the specific MCP tool or documented tool family
you are about to call**. Use `"+ouroboros evolve"` for `ouroboros_evolve_step`,
`ouroboros_lineage_status`, and the evolve flow's documented tool family;
use `"+ouroboros interview"` before `ouroboros_interview`, `"+ouroboros seed"`
before `ouroboros_generate_seed`, and `"+ouroboros lateral"` before
`ouroboros_lateral_think`. If a load returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), switch to the
documented fallback / Path B instead of retrying the failing call.

### Path A: MCP Available (loaded via runtime tool discovery above)

**Starting a new evolutionary loop:**
1. Parse the user's input as `initial_context`
2. Run the interview: call `ouroboros_interview` with `initial_context`
3. Complete the interview (3+ rounds until ambiguity ≤ 0.2)
4. Generate seed: call `ouroboros_generate_seed` with the `session_id`
5. Call `ouroboros_evolve_step` with:
   - `lineage_id`: new unique ID (e.g., `lin_<seed_id>`)
   - `seed_content`: the generated seed YAML
   - `execute`: `true` (default) for full Execute→Evaluate pipeline,
     `false` for fast ontology-only evolution (no seed execution)
   - `benchmark_control`: `false` (default). Set `true` only for a deliberate
     Gen 2+ full-graph control in an explicit clean Git project/worktree.
6. Check the `action` in the response:
   - `continue` → Inspect `active_ac_indices`, then call `ouroboros_evolve_step`
     again with just `lineage_id`. Only active failed/reopened nodes evolve;
     frozen PASS nodes stay immutable and are boundary-reverified.
   - `ontology_stable` → This is not success. Call `ouroboros_evolve_step`
     again for the same `lineage_id` with `execute: true` so the stable Seed
     goes through Execute→Evaluate. Do not call standalone evaluate or report
     convergence before that step returns `converged`.
   - `converged` → Evolution complete! Display final ontology
   - `stagnated` → Ontology unchanged for 3+ gens. Consider `ouroboros_lateral_think`
   - `exhausted` → Max 30 generations reached. Display best result
   - `failed` → Check error, possibly retry. If the error reports an expired
     lineage owner, first confirm that the prior owner process is dead, then
     make one explicit recovery call with `recover_expired_claim: true`.
     Never set this flag for a merely slow or still-running owner.
7. **Repeat step 6** while action is `continue`. Treat `ontology_stable` as the
   explicit transition above, then process the `execute: true` response using
   step 6. Stop only on `converged`, `stagnated`, `exhausted`, or `failed`.
8. When the loop terminates, display a result summary with next step:
   - `converged`: `◆ Current state → next: Ontology converged! Run ooo evaluate for formal verification`
   - `ontology_stable`: `◆ Current state → next: Run the same lineage with execute=true for Execute→Evaluate; this is not verified convergence y