# EVOLVE — Agent Learning & Governance Extension (Agent Instructions)

> Drop this file into your CLAUDE.md, .cursorrules, copilot-instructions.md, or agent system prompt to make your AI tool EVOLVE-compliant. This document is self-contained — no external files or downloads are required.

**Standard:** EVOLVE v1.0 | **Authors:** itsavibe.ai

> **Prerequisite:** This agent configuration implements the EVOLVE agent learning and governance extension. Your tool MUST already implement the VIBES data standard (see `vibes-agent.md`). EVOLVE builds on VIBES data structures — delegation records, decision records, edge records, and session records. For security attestation, see `verify-agent.md`. For risk scoring, see `prism-agent.md`. For incident response and forensics (which feeds closed-incident reports back into EVOLVE governance signal), see `trace-agent.md`.

## Table of Contents

| § | Section | Anchor |
|---|---|---|
| 1 | What is EVOLVE? | [#1-what-is-evolve](#1-what-is-evolve) |
| 2 | Data Substrate | [#2-data-substrate](#2-data-substrate) |
| 3 | Agent Governance | [#3-agent-governance](#3-agent-governance) |
| 4 | Decision Records | [#4-decision-records](#4-decision-records) |
| 5 | Governance Scenarios | [#5-governance-scenarios](#5-governance-scenarios) |
| 6 | Reinforcement Pipelines (Planned) | [#6-reinforcement-pipelines-planned](#6-reinforcement-pipelines-planned) |
| 7 | Agent Behavior Summary | [#7-agent-behavior-summary](#7-agent-behavior-summary) |
| 8 | Complete Example (Multi-Agent Governance) | [#8-complete-example-multi-agent-governance](#8-complete-example-multi-agent-governance) |

**Deep-load examples:**
- Just the governance chapter: `https://itsavibe.ai/evolve-agent.md#3-agent-governance`
- Just the decision records spec: `https://itsavibe.ai/evolve-agent.md#4-decision-records`

---

## 1. What is EVOLVE?

EVOLVE (Explainable Validated Optimization & Learning Via Execution) transforms passive VIBES audit data into actionable intelligence — from governance frameworks for autonomous agent operations to reinforcement feedback loops that help agents learn from their own history.

Where VIBES records *what happened* and VERIFY proves *it's authentic*, EVOLVE answers: **what can we learn from it?**

EVOLVE applies to any AI agent domain — writing code, managing infrastructure, processing transactions, moderating content, or automating workflows.

---

## 2. Data Substrate

EVOLVE does not define new record types. It defines **policies, automation, and feedback patterns** on top of data that VIBES already captures. The building blocks are:

| Record Type | Source | Purpose in EVOLVE |
|-------------|--------|-------------------|
| `delegation` records | VIBES Low+ | Capture parent/child session relationships, task descriptions, delegated resources. Enable governance chains. |
| `edge` records | VIBES Low+ | Causal relationships between events. Enable provenance DAG queries ("trace every action back to its originating instruction"). |
| `session` records | VIBES Low+ | Session lifecycle with `parent_session_id`, `agent_name`, `agent_type` for multi-agent hierarchies. |
| `decision` records | VIBES Medium+ | Structured capture of alternatives considered, rationale, and confidence. Enable agent self-evaluation. |
| `risk_score` + `risk_factors` | PRISM | Quantified risk per annotation. Feeds feedback loops for risk calibration. |

You MUST already be emitting these record types per the VIBES standard. EVOLVE adds behavioral requirements for how agents use this data.

---

## 3. Agent Governance

### Multi-Agent Delegation Chains

When you spawn sub-agents or are spawned as a sub-agent, you MUST maintain traceable delegation chains:

1. **Orchestrator behavior:** Append a `delegation` record before spawning each sub-agent, with `parent_session_id`, `child_session_id`, `task_description`, `delegated_files`, and `delegation_type`.
2. **Worker behavior:** Include `parent_session_id`, `agent_name`, and `agent_type` in your session start record.
3. **Chain integrity:** Every action taken by a sub-agent MUST be traceable back to the orchestrating decision through the delegation and session records.

### Delegation Record Schema

```json
{"type":"delegation","parent_session_id":"maestro-001","child_session_id":"worker-001","timestamp":"2026-02-03T10:04:00Z","task_description":"Implement authentication module","delegated_files":["src/auth.py","src/middleware/auth.py"],"delegation_type":"task","parent_environment_hash":"e7a3f1b2...","child_environment_hash":"f8a9b0c1..."}
```

| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | Always `"delegation"` |
| `parent_session_id` | Yes | UUID of the orchestrator/parent session |
| `child_session_id` | Yes | UUID of the delegated sub-agent session |
| `timestamp` | Yes | ISO-8601 timestamp (UTC) |
| `task_description` | No | Human-readable description of the delegated task |
| `delegated_files` | No | Array of relative file paths assigned to the sub-agent |
| `delegation_type` | No | One of: `"task"`, `"review"`, `"research"`, `"other"` |
| `parent_environment_hash` | No | References the parent agent's environment entry |
| `child_environment_hash` | No | References the child agent's environment entry |

### Session Record Extensions

```json
{"type":"session","event":"start","session_id":"worker-001","timestamp":"2026-02-03T10:01:30Z","environment_hash":"f8a9b0c1...","assurance_level":"medium","description":"Implement auth","parent_session_id":"maestro-001","agent_name":"worker-auth","agent_type":"worker"}
```

| Field | Required | Description |
|-------|----------|-------------|
| `parent_session_id` | No | UUID of the parent session that delegated this task |
| `agent_name` | No | Human-readable name of the agent (e.g., `"maestro"`, `"worker-auth"`) |
| `agent_type` | No | Role: `"orchestrator"`, `"worker"`, `"reviewer"`, or `"other"` |

---

## 4. Decision Records

You MUST create a decision entry when evaluating multiple approaches. Decision records are mandatory at Medium assurance and above.

### Decision Record Schema

```json
{
  "type": "decision",
  "decision_point": "Choose authentication strategy for the API",
  "options": [
    {
      "id": "jwt",
      "description": "Stateless JWT tokens with RS256 signing",
      "pros": ["No server-side session state", "Scalable across services"],
      "cons": ["Cannot revoke individual tokens", "Larger payload size"]
    },
    {
      "id": "session",
      "description": "Server-side sessions with signed cookies",
      "pros": ["Immediate revocation", "Smaller cookie payload"],
      "cons": ["Requires session store", "Harder to scale horizontally"]
    }
  ],
  "selected": "jwt",
  "rationale": "The API serves multiple microservices; stateless tokens avoid a shared session store dependency.",
  "confidence": "high",
  "created_at": "2026-02-03T10:03:00Z"
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | Always `"decision"` |
| `decision_point` | Yes | Human-readable description of the decision |
| `options` | Yes | Array of alternatives, each with `id`, `description`, `pros`, `cons` |
| `selected` | Yes | The `id` of the chosen option |
| `rationale` | Yes | Explanation of why the selected option was chosen |
| `confidence` | No | `"low"`, `"medium"`, or `"high"` |
| `created_at` | Yes | ISO-8601 timestamp |

### Linking Decisions to Annotations

Include `decision_hash` in annotation records produced as a result of the decision:

```json
{"type":"line","file_path":"src/auth.py","line_start":1,"line_end":45,"decision_hash":"e1f2a3b4...","action":"create",...}
```

---

## 5. Governance Scenarios

EVOLVE governance applies across any domain where autonomous agents operate:

### Security-Sensitive Domains

When agents operate on authentication systems, encryption configurations, or access control policies, you SHOULD enforce:
- Any agent action in security-critical files MUST have a PRISM score below the configured threshold OR require human sign-off.
- Delegation chains for security-sensitive tasks MUST be fully traceable.

### Financial Infrastructure

When agents manage payment processing, transaction routing, or compliance logic:
- Every agent action MUST have a delegation record linking it to an authorizing decision.
- PRISM risk scoring SHOULD be enabled to quantify risk per action.
- High-risk operations (PRISM >= 0.6) SHOULD block without human review.

### Regulatory Compliance

For agents operating in domains governed by the EU AI Act or similar regulations:
- Decision records provide the structured evidence auditors need — who authorized the AI action, what oversight occurred, and the complete decision chain.
- Delegation records provide a chain of custody for every action.

---

## 6. Reinforcement Pipelines (Planned)

Reinforcement pipelines are forward-looking work. The data substrate exists today, but the feedback mechanisms described here are a roadmap for tooling that transforms audit trails into learning signal.

### The Closed Loop

| Stage | Description | Data Source |
|-------|-------------|-------------|
| **Record** | Capture structured audit data during every agent operation | VIBES annotations, decisions, delegations |
| **Analyze** | Correlate outcomes with inputs — which instructions produced first-pass approved results? | Session records, edge records |
| **Score** | PRISM risk scores and review outcomes provide quantitative signal | `risk_score`, `review_status` |
| **Learn** | Aggregated patterns feed back into agent configuration — prioritize low-risk patterns, flag high-rework patterns | Decision records over time |
| **Improve** | Next session benefits from the last — better defaults, calibrated risk awareness | Agent configuration |

### Data Signals for Learning

| Signal | Source | Learning Value |
|--------|--------|---------------|
| `prompt_text` + `prompt_context_files` | VIBES Medium | Correlate instruction patterns with outcome quality |
| `decision_point` + `options` + `selected` | VIBES Medium | Evaluate decision quality over time |
| `risk_score` + `risk_factors` | PRISM | Track whether risk predictions align with actual outcomes |
| `review_status` | Optional annotation field | Primary outcome signal — was the output approved, rejected, or reworked? |
| `delegation` records | VIBES Low | Which delegation strategies produce better results? |

### Feedback Patterns

**Decision Quality Tracking:** Correlate decisions with downstream outcomes (review status, rework frequency). Does the agent's confidence calibration match reality? Are "high confidence" decisions actually more successful?

**Systematic Bias Detection:** When an agent consistently selects the same option type across similar decision points, decision records make that pattern visible. If the agent always favors complexity over simplicity, the structured data reveals it.

**Rationale Auditing:** In regulated domains, auditors can review not just what actions were taken, but why specific approaches were chosen.

---

## 7. Agent Behavior Summary

### At Session Start

1. Read `.ai-audit/config.json` for assurance level and any governance policies.
2. If this is a sub-agent session, include `parent_session_id`, `agent_name`, and `agent_type` in the session start record.

### Before Delegation

1. Append a `delegation` record with parent/child session IDs, task description, and delegated files.
2. Ensure the child agent's environment context is recorded separately in the manifest.

### At Decision Points

1. When evaluating multiple approaches, create a decision manifest entry with all options, pros/cons, rationale, and confidence.
2. Compute the decision hash and include it in resulting annotation records via `decision_hash`.

### Post-Generation

1. Emit edge records linking annotations to their causal context (`caused_by`, `informed_by`).
2. If PRISM is enabled, include `risk_score` and `risk_factors` (computed per `prism-agent.md`).

### At Session End

1. Append a session end record.
2. If operating as a sub-agent, ensure all actions are traceable through the delegation chain.

---

## 8. Complete Example (Multi-Agent Governance)

```jsonl
{"type":"session","event":"start","session_id":"maestro-001","timestamp":"2026-02-03T10:00:00Z","environment_hash":"e7a3f1b2...","assurance_level":"medium","description":"Implement auth module","agent_name":"maestro","agent_type":"orchestrator"}
{"type":"delegation","parent_session_id":"maestro-001","child_session_id":"worker-001","timestamp":"2026-02-03T10:01:00Z","task_description":"Implement auth","delegated_files":["src/auth.py"],"delegation_type":"task","parent_environment_hash":"e7a3f1b2...","child_environment_hash":"f8a9b0c1..."}
{"type":"session","event":"start","session_id":"worker-001","timestamp":"2026-02-03T10:01:30Z","environment_hash":"f8a9b0c1...","assurance_level":"medium","description":"Implement auth","parent_session_id":"maestro-001","agent_name":"worker-auth","agent_type":"worker"}
{"type":"line","file_path":"src/auth.py","line_start":1,"line_end":58,"environment_hash":"f8a9b0c1...","prompt_hash":"b2c3d4e5...","decision_hash":"e1f2a3b4...","action":"create","timestamp":"2026-02-03T10:05:00Z","session_id":"worker-001","assurance_level":"medium","annotation_id":"d5e6f7a8...","risk_score":0.53,"risk_factors":[{"signal":"action_type","value":0.6,"weight":0.15},{"signal":"scope_lines","value":0.72,"weight":0.15},{"signal":"human_review_present","value":1.0,"weight":0.15}]}
{"type":"edge","edge_type":"caused_by","source_ref":"d5e6f7a8...","source_type":"annotation","target_ref":"b2c3d4e5...","target_type":"context","timestamp":"2026-02-03T10:05:01Z","session_id":"worker-001"}
{"type":"session","event":"end","session_id":"worker-001","timestamp":"2026-02-03T10:30:00Z"}
{"type":"session","event":"end","session_id":"maestro-001","timestamp":"2026-02-03T10:35:00Z"}
```

This example shows:
- An orchestrator (`maestro`) delegating to a worker (`worker-auth`)
- The worker creating code with a decision hash linking to its reasoning
- PRISM risk scoring on the annotation (0.53 = Medium band)
- Edge tracking linking the annotation to the prompt that caused it
- Full delegation chain from orchestrator → worker → action