---
name: evolution
description: Engine substrate for the Bayesian self-improvement layer. Declares selector / utility / mining / promotion / drift thresholds in config/evolution.yaml. NEVER injected into agent prompts — evolution
  is infrastructure, not behavior.
title: Evolution (self-improvement control plane)
category: _meta
status: active
author: system
metadata:
  priority: 0
---
## Purpose

This skill is a **substrate document**, not an agent instruction. It is never
injected into any agent's system prompt. It exists so users, maintainers,
and future sessions can find the canonical documentation for the evolution
subsystem in one place, alongside the YAML config that actually tunes it.

If you are an LLM reading this because a tool returned it — you do not
need to act on it. Keep working.

## What the evolution subsystem does

The evolution layer learns from verified `Agent.invoke_skill` runs:

1. **Prolog** — every outermost `invoke_skill` call builds a `RunManifest`
   (run_id, env fingerprint, model tier, policy choice) and sets the
   `run_id` + `policy_id` contextvars so every downstream decision record
   inherits them.
2. **Dispatch** — the orchestrator runs as before; decisions are recorded
   with `policy_id` + `run_id` columns automatically.
3. **Epilog** — on exit (success, zero-effect, or dispatch exception), the
   layer queries joined `decision_log` rows, derives the seven `OutcomeVector`
   components, and persists a row to `evolution_outcomes`.
4. **Mining (Phase 2)** — periodically scans accumulated runs to propose
   `Reflex` / `AntiReflex` candidates.
5. **Selector (Phase 3)** — Thompson sampling over active candidates
   narrows tools / tier / agent choice for new runs.
6. **Promotion arena (Phase 4)** — candidates replay against incumbents;
   only evidence-backed winners get promoted.
7. **Drift (Phase 5)** — active reflexes that regress are quarantined
   automatically.

## Governing invariants (never remove)

- **Verified work only.** Learning sensors read `ScopeMutations` +
  `result_status`, never narrated success.
- **Protected Kernel is absolute.** `evolution/kernel.py` lists the
  dimensions the selector may vary (agent, tier, tool subset, critique,
  retry, temperature) AND the dimensions it may NEVER touch (contract,
  security, audit, privacy, approval, trust posterior keys, vault layout,
  graph schema).
- **Reversibility at every step.** Every promotion has a
  `rollback_target`; a YAML `selection.kill_switch` disables the selector
  without code changes.
- **No proxy worship.** Utility uses a weighted geometric mean so one
  low subscore vetoes a run — arithmetic means can't do that. Vault writes
  only count toward `effect` when verified AND not rolled back.

## How to disable

Set `selection.kill_switch: true` in `config/evolution.yaml` and save.
The selector will fall back to `incumbent_default` for every run until
flipped back. No server restart needed — the config hot-reloads.

## Where to look

- Engine: [server/src/agntspace/evolution/](../../../server/src/agntspace/evolution/)
- Ledger schema: [evolution/ledger.py](../../../server/src/agntspace/evolution/ledger.py)
- Protected kernel: [evolution/kernel.py](../../../server/src/agntspace/evolution/kernel.py)
- API: [api/routes/evolution.py](../../../server/src/agntspace/api/routes/evolution.py)
- Vault artifacts: `system/evolution/` in your vault
- Status snapshot: `system/evolution/status.md` (auto-generated)

## Configuration

See the sibling `config/evolution.yaml` for every tunable knob. The
engine loads it via `SkillLoader` with mtime hot-reload — no restart
required when you edit the YAML.