Ouro Loop

61.1 Overview and Motivation

The name "Ouro" derives from the Ouroboros — the ancient symbol of a serpent consuming its own tail — and serves as a fitting metaphor for a system designed to let AI coding agents consume their own errors and iterate autonomously. Ouro Loop, published in March 2026 by the independent researcher VictorVVedtion, formalizes a concept the author terms Bounded Autonomy: the principle that granting an agent maximal creative freedom requires first establishing inviolable constraints. The project's tagline captures this philosophy succinctly: "To grant an entity absolute autonomy, you must first bind it with absolute constraints."

Ouro Loop occupies a distinctive position in the landscape of LLM-powered evolutionary systems surveyed in this book. It is not an AI agent, nor an evolutionary search engine, nor an LLM orchestrator. Rather, it is a methodology and runtime framework that wraps around existing AI coding agents — Claude Code, Cursor, Aider, Codex CLI — and imposes structure on their autonomous operation. The system directly extends Andrej Karpathy's autoresearch paradigm from ML experiment loops to general software engineering, adopting the same tripartite file structure (program.md, framework.py, prepare.py) while adding verification gates, self-reflective logging, and runtime enforcement mechanisms absent from the original.

61.1.1 The Problem: Pathological Agent Behaviors

The author identifies four pathological behaviors exhibited by unbound AI coding agents operating in what has been termed the "vibe coding" era:

Pathology	Description	Ouro Loop Countermeasure
Hallucination	Referencing files, APIs, and modules that do not exist	EXIST verification gate
Regression	Breaking established architectural patterns and constraints	RELEVANCE gate + DANGER ZONE enforcement
Symptom-chasing	Repeatedly editing the same file without addressing root causes	ROOT_CAUSE gate + hot-file tracking
Context decay	Forgetting critical constraints during long sessions	RECALL gate + recall hook on context compression

Existing mitigation strategies fall into two extremes. Human-in-the-loop approaches require constant developer supervision, negating the autonomous value of the agent. Instruction-only guardrails — static files such as .cursorrules or CLAUDE.md — define behavioral expectations that the agent may ignore, forget, or misinterpret during extended sessions. Neither extreme produces reliable overnight autonomous development.

61.1.2 The Ouroboros Contract

The author articulates the theoretical foundation in a companion manifesto titled "The Ouroboros Contract," which proposes the framework of Precision Autonomy:

By explicitly defining the 20 things an agent can never do (the BOUND), you implicitly authorize it to autonomously do the 10,000 things required to solve the problem. The constraint space defines the creative space.

This positions Ouro Loop against three alternative paradigms for agent control:

Paradigm	Mechanism	Failure Mode
Allowlisting	Specify everything the agent can do	Does not scale to open-ended tasks
Instruction-following	Describe desired behaviors in natural language	Brittle; agent can misinterpret or forget
Constraint-based (Ouro Loop)	Define hard boundaries; everything else is permitted	Requires well-specified constraints; non-spatial constraints remain compliance-based

It is important to note that the constraint-based paradigm as implemented in Ouro Loop achieves different enforcement strengths for different constraint types. Spatial constraints (DANGER ZONES) are hard-enforced via runtime hooks, but behavioral (NEVER DO) and invariant (IRON LAWS) constraints are checked through self-assessment and automated verification — a distinction elaborated in Section 61.3.1.

61.2 Architecture

Ouro Loop is architecturally minimalist. The entire system consists of three Python/Markdown files, five shell-script hooks, and a set of module documentation files. This minimalism is deliberate — the framework adds negligible overhead (~50–200ms per operation) and has zero external dependencies beyond the Python 3.10+ standard library.

61.2.1 Three-File Architecture

Each file maps directly to the autoresearch paradigm. program.md contains the methodology the agent follows (analogous to autoresearch's experiment strategy). framework.py is the runtime the agent interacts with via CLI (analogous to train.py). prepare.py handles initialization and is read-only after setup (analogous to autoresearch's prepare.py). The key extension is the addition of the .ouro/ state directory and the BOUND definition in CLAUDE.md, neither of which have autoresearch equivalents.

61.2.2 The Six-Stage Loop

The core execution model is a six-stage state machine that the agent traverses for each phase of work:

The six stages serve distinct purposes. BOUND (Stage 0) is the only human-authored stage — the developer defines DANGER ZONES (protected files), NEVER DO rules (absolute prohibitions), and IRON LAWS (invariants). Stages 1–5 are autonomous. MAP requires the agent to answer six mandatory questions about the problem space before writing any code. PLAN decomposes the task by severity (CRITICAL → HIGH → MEDIUM → LOW), with each phase targeting 100–300 lines of change. BUILD follows a RED → GREEN → REFACTOR → COMMIT cycle. VERIFY runs three layers of checks. LOOP feeds discoveries back into the plan and advances to the next phase. The agent only escalates to human review when changes touch a DANGER ZONE or when three or more consecutive retries fail.

61.2.3 Hook-Based Runtime Enforcement

The critical architectural innovation distinguishing Ouro Loop from instruction-based guardrails is the use of Claude Code's hook system for runtime constraint enforcement. Five shell-script hooks intercept tool calls at the platform level, operating below the agent's reasoning layer:

Hook	Event	Action	Enforcement Level
bound-guard.sh	PreToolUse: Edit/Write	Parse CLAUDE.md DANGER ZONES; match against target file	Hard block (exit 2)
root-cause-tracker.sh	PostToolUse: Edit/Write	Track per-file edit count; warn at 3+, strong warn at 5+	Advisory (warning only)
drift-detector.sh	PreToolUse: Edit/Write	Count distinct directories touched; warn at 5+	Advisory (warning only)
momentum-gate.sh	PostToolUse: Edit/Write/Read	Track read/write ratio; warn at 3:1+	Advisory (warning only)
recall-gate.sh	PreCompact	Re-inject BOUND into context before compression	Context preservation

The bound-guard.sh hook is the only hard-blocking mechanism. When the agent attempts to edit a file within a DANGER ZONE, the hook returns exit 2 — a Claude Code convention for irrecoverable blocking. No amount of prompt injection, reasoning error, or context confusion can override this exit code within Claude Code. The remaining four hooks provide advisory signals — warnings that the agent should heed but that do not prevent the tool operation from completing.

Agent portability and enforcement scope. This hook-based enforcement architecture is tightly coupled to Claude Code's specific hook mechanism. The following table summarizes the enforcement characteristics across different agent integrations:

Agent	Methodology (program.md)	CLI State (framework.py)	Hard DANGER ZONE Block	Advisory Hooks	PreCompact Recall
Claude Code	Full	Full	Yes (exit 2)	Yes (all 4)	Yes
Cursor	Via .cursorrules	Via terminal	No equivalent hook mechanism	No	No
Aider	Via instructions	Via terminal	No equivalent hook mechanism	No	No
Codex CLI	Via file read	Via shell	No equivalent hook mechanism	No	No

For non-Claude-Code agents, Ouro Loop functions as a pure methodology framework: the agent follows program.md instructions and uses framework.py CLI commands, but DANGER ZONE enforcement relies on the agent's compliance with self-assessment checks rather than on hard runtime blocking. The claim of "agent-agnosticism" is therefore accurate at the methodology layer but not at the enforcement layer. This is a significant distinction — the strongest safety guarantee (non-bypassable DANGER ZONE blocking) is currently Claude Code-specific.

The recall-gate.sh hook deserves special attention. It fires on the PreCompact event — triggered before Claude Code compresses its context window — and re-injects the BOUND constraints. This directly addresses constraint amnesia, a failure mode where the agent forgets its safety boundaries during long sessions as earlier context is summarized or dropped. This mechanism is also Claude Code-specific; other agents lack an equivalent pre-compression event.

61.3 Core Mechanisms

61.3.1 Mechanism 1: The Three-Layer BOUND

The BOUND is defined in three complementary layers, each targeting a different class of constraint. This structure is defined by the developer in CLAUDE.md and parsed by framework.py's dual-strategy extraction algorithm.

Layer A — DANGER ZONES (Spatial Constraints) protect files and directories where modifications carry outsized risk. The agent may read these files but cannot edit them without explicit human approval. Examples from the source material's blockchain case study include consensus/ (PBFT consensus protocol) and migrations/ (irreversible database schema changes).

Layer B — NEVER DO (Behavioral Constraints) are absolute prohibitions. These are not enforced by hooks (since they are semantic rather than file-based) but are checked during the VERIFY stage's self-assessment layer. Examples: "Never use float for monetary values — always Decimal" and "Never commit without running the test suite."

Layer C — IRON LAWS (Invariant Constraints) are properties that must always hold, verifiable through automated checks. Examples: "SysErr rate in consensus is 0.00%" and "Test coverage for payment module never drops below 90%."

The enforcement characteristics differ substantially by layer, and this distinction is critical for understanding Ouro Loop's actual safety guarantees:

Layer	Type	Enforcement Mechanism	Enforcement Strength	Recovery on Violation
DANGER ZONES	Spatial	Hard-block via bound-guard.sh hook	Non-bypassable (Claude Code only)	Human approval required
NEVER DO	Behavioral	Self-assessment in VERIFY Layer 2	Compliance-based (agent must detect own violations)	Agent self-corrects
IRON LAWS	Invariant	Automated verification in VERIFY Layer 1 (where machine-checkable) + self-assessment	Mixed: machine-checkable invariants are strong; semantic invariants are compliance-based	Agent must restore invariant

This enforcement hierarchy means that DANGER ZONE protection is the system's strongest guarantee, while NEVER DO and some IRON LAW constraints ultimately depend on the quality of the agent's self-assessment — the same fundamental limitation Ouro Loop criticizes in vanilla instruction files, albeit more structured and systematically scheduled.

61.3.2 Mechanism 2: Five Verification Gates

Layer 1 of the VERIFY stage runs five automated gates, each designed to detect a specific pathological behavior. The gates are implemented in framework.py and invoked via the CLI (python framework.py verify). Each gate returns a status of PASS, WARN, FAIL, or SKIP.

We introduce the following notation for the formal treatment. Let $S$ denote the current project state (encompassing the file tree, git history, and .ouro/ persistent state). Define the gate set $G = \{g_1, g_2, g_3, g_4, g_5\}$ where each gate maps the project state to a severity level:

The overall Layer 1 verdict $V_1$ is computed by strict precedence:

where SKIP is treated as PASS for aggregation purposes. Note that this aggregation rule is conjunctive — a single FAIL from any gate fails the entire layer. The FAIL verdict triggers the remediation protocol (Section 61.3.5); WARN produces advisory alerts but does not block phase advancement.

The five gates and their detection logic (described here as the methodology specifies them; see the code note below for implementation status):

Gate 1 — EXIST (Anti-Hallucination): Verifies that CLAUDE.md exists and that key referenced files are present. If BOUND was expected (from the initialization snapshot in .ouro/state.json) but CLAUDE.md is now missing, the gate returns FAIL rather than WARN — distinguishing between "never had constraints" and "lost constraints."

Gate 2 — RELEVANCE (Anti-Drift): Uses git status --short to enumerate changed files and cross-references them against DANGER ZONES. Returns WARN if any changed file overlaps with a DANGER ZONE, PASS otherwise. Provides a structured list of changed files and DANGER ZONE overlaps for downstream analysis.

Gate 3 — ROOT_CAUSE (Anti-Symptom-Chasing): Uses git log --name-only -10 to identify frequently edited files. A file edited $k \geq 3$ times in the last 10 commits is flagged as a "hot file." The threshold of 3 is a design choice documented in program.md; the author does not provide empirical calibration data for this value, though the blockchain case study shows the gate activating correctly at this threshold.

Gate 4 — RECALL (Anti-Context-Decay): Verifies that the BOUND section remains parseable and that DANGER ZONES and IRON LAWS are still present and complete. Returns WARN if the BOUND is incomplete or missing, indicating potential context decay.

Gate 5 — MOMENTUM (Anti-Analysis-Paralysis): Tracks recent commit frequency. Returns WARN if the agent has produced zero or one commit recently, indicating potential stall in a read-only analysis loop without producing output.

# PSEUDOCODE: Illustrative reconstruction of the verification engine logic
# Based on the documented methodology in program.md and the CLI interface
# described in the repository README. NOT a verbatim excerpt from framework.py.
#
# The actual implementation in framework.py (~47 KB) contains additional
# error handling, CLI argument parsing, and edge-case logic not shown here.

import subprocess
import json
from collections import Counter
from typing import Literal

GateStatus = Literal["PASS", "WARN", "FAIL", "SKIP"]

def run_gate_exist(state: dict, claude_md_path: str) -> tuple[GateStatus, str]:
    """Gate 1: EXIST — anti-hallucination check.

    Distinguishes 'BOUND never defined' (WARN) from 'BOUND was defined
    but CLAUDE.md is now missing' (FAIL), using the bound_defined flag
    persisted in .ouro/state.json during initialization.
    """
    import os
    if not os.path.exists(claude_md_path):
        if state.get("bound_defined", False):
            return ("FAIL", "CLAUDE.md expected but missing — BOUND lost")
        return ("WARN", "No CLAUDE.md found — operating without BOUND")
    return ("PASS", "CLAUDE.md exists, BOUND present")

def run_gate_root_cause(threshold: int = 3) -> tuple[GateStatus, str]:
    """Gate 3: ROOT_CAUSE — anti-symptom-chasing via hot-file detection.

    Scans the last 10 commits for files edited >= threshold times.
    The threshold of 3 is a methodology-prescribed default; the author
    does not report calibration experiments for this value.
    """
    result = subprocess.run(
        ["git", "log", "--name-only", "-10", "--pretty=format:"],
        capture_output=True, text=True, timeout=10
    )
    files = [f for f in result.stdout.strip().split("\n") if f.strip()]
    counts = Counter(files)
    hot_files = {f: c for f, c in counts.items() if c >= threshold}
    if hot_files:
        detail = ", ".join(f"{f} ({c}x)" for f, c in hot_files.items())
        return ("WARN", f"Hot files: {detail}")
    return ("PASS", "No hot files detected")

def compute_overall_verdict(
    gate_results: dict[str, tuple[GateStatus, str]]
) -> Literal["PASS", "WARN", "FAIL"]:
    """Aggregate gate results into overall Layer 1 verdict.

    Uses strict precedence: FAIL > WARN > PASS.
    SKIP is treated as PASS for aggregation.
    """
    statuses = [status for status, _ in gate_results.values()]
    if "FAIL" in statuses:
        return "FAIL"
    if "WARN" in statuses:
        return "WARN"
    return "PASS"

61.3.3 Mechanism 3: Three-Layer Reflective Logging

Every verification result is logged as a structured JSONL entry in .ouro/reflective-log.jsonl with three layers of increasing abstraction, designed for fast LLM parsing at the start of each iteration:

Layer 1 — WHAT (Facts): Raw verification output including stage, phase number, verdict, individual gate results, list of changed files, DANGER ZONE contacts, and BOUND violation count.

Layer 2 — WHY (Decisions): Contextual metadata including complexity classification, the reason for that classification, review trigger reasons, BOUND state summary, and freeform notes.

Layer 3 — PATTERN (Self-Awareness): Computed behavioral signals including consecutive failure count, stuck-loop detection, velocity trend (ACCELERATING / STABLE / DECELERATING), retry rate, hot file list, and drift signal.

Each entry also generates pre-computed actionable alerts — short strings the agent can act on without parsing raw data:

# PSEUDOCODE: Illustrative reconstruction of alert generation logic
# Based on the documented alert format in program.md and the three-layer
# reflective log specification. NOT a verbatim excerpt from framework.py.

def generate_alerts(pattern: dict) -> list[str]:
    """Generate actionable alerts from pattern detection layer.

    Each alert is a short, agent-parseable string prefixed with '>>'
    that enables the LLM to act on behavioral signals without
    parsing the full JSONL log structure.
    """
    alerts = []

    if pattern.get("drift_signal"):
        alerts.append(">> DRIFT: working in DANGER ZONE — extra caution required")

    hot_files = pattern.get("hot_files", [])
    if hot_files:
        files_str = ", ".join(hot_files)
        alerts.append(f">> HOT FILES: {files_str} — possible symptom-chasing")

    velocity = pattern.get("velocity_trend", "STABLE")
    if velocity == "DECELERATING":
        alerts.append(">> SLOWING: pass rate declining — reassess approach")

    if pattern.get("consecutive_failures", 0) >= 3:
        alerts.append(">> STUCK: 3+ consecutive failures — step back and re-examine")

    if pattern.get("stuck_loop"):
        alerts.append(">> LOOP DETECTED: same stage failing repeatedly — "
                       "try fundamentally different approach")

    return alerts

The log is capped at 30 entries via a rolling window, preventing unbounded growth while maintaining sufficient history for pattern detection. The JSONL format (one JSON object per line) enables simple append-only writes and efficient tail reads.

61.3.4 Mechanism 4: Pattern Detection Engine

The pattern detection system analyzes the agent's behavioral history to identify recurring problems. It operates on the reflective log entries and computes six signals. We define notation precisely before presenting the detection logic.

Notation. Let $E = (e_1, e_2, \ldots, e_n)$ denote the ordered sequence of reflective log entries, where $n \leq 30$ (the rolling window cap). Each entry $e_i$ has a verdict $v(e_i) \in \{\text{PASS}, \text{WARN}, \text{FAIL}, \text{RETRY}\}$ and a stage label $s(e_i)$. Define the pass indicator $\mathbb{1}_P(e_i) = 1$ if $v(e_i) = \text{PASS}$, and $0$ otherwise.

Consecutive failures: Define $c_{\text{fail}}$ as the length of the longest suffix of $E$ consisting entirely of entries with $v(e_i) \in \{\text{FAIL}, \text{RETRY}\}$. An alert fires when $c_{\text{fail}} \geq 2$.

Stuck loop: Detects when the same stage fails three or more times in a row. Formally, a stuck loop is declared when $c_{\text{fail}} \geq 3$ and all entries in the failing suffix share the same stage: $s(e_{n-2}) = s(e_{n-1}) = s(e_n)$, each with $v(e_i) \in \{\text{FAIL}, \text{RETRY}\}$. This indicates a fundamental approach problem rather than a transient error. The threshold of 3 is prescribed by the methodology as a heuristic balance: too low would trigger false step-backs on transient failures; too high would allow excessive wasted iterations before escalation. The author does not report empirical sensitivity analysis for this value.

Velocity trend: Compares pass rates between the first and second halves of recent history. This requires at least six log entries ($n \geq 6$) for meaningful analysis. Split $E$ into two halves:

The pass rate for each half is:

The velocity trend is classified as:

where $\delta = 0.3$. The choice of $\delta = 0.3$ (rather than, say, $\delta = 0.2$) is a design decision documented in the source material as intended to "reduce false positives from natural variation." This is a reasonable heuristic: with $|H| \approx 3\text{–}15$ entries per half, a threshold of 0.2 would be triggered by a single additional pass/fail flip (e.g., going from 1/3 PASS to 2/3 PASS), while 0.3 requires a more substantial shift. However, this threshold has not been empirically calibrated against labeled datasets of genuine trend changes versus noise — it remains a methodology-prescribed default, not an empirically validated operating point.

Hot files: Files edited $k \geq 3$ times in the last 10 commits, sourced from the ROOT_CAUSE gate.

Drift signal: Boolean flag set when any changed file appears in the DANGER ZONE list, sourced from the RELEVANCE gate.

Retry rate: The fraction of RETRY verdicts in the last $\min(5, n)$ entries, reported as a continuous metric in $[0, 1]$ without a fixed alert threshold.

61.3.5 Mechanism 5: Autonomous Remediation Protocol

When verification fails, Ouro Loop's remediation protocol determines the appropriate action without human intervention — unless the failure touches a DANGER ZONE. The protocol is defined in modules/remediation.md and structured as a decision tree the agent follows:

# PSEUDOCODE: Illustrative reconstruction of the remediation decision tree
# Based on the specification in modules/remediation.md and program.md.
# NOT a verbatim excerpt from the repository.
#
# The actual remediation protocol is defined as natural-language instructions
# in modules/remediation.md; the agent follows this as a decision procedure
# rather than executing it as Python code.

def remediate(
    failed_gate: str,
    danger_zone_contact: bool,
    consecutive_failures: int
) -> str:
    """Determine remediation action based on failure type.

    The protocol enforces a strict escalation hierarchy:
    1. DANGER ZONE contact → always requires human review
    2. 3+ consecutive failures → architectural step-back
    3. Gate-specific strategies → targeted fix attempts
    """

    # Hard stop: DANGER ZONE contact requires human
    if danger_zone_contact:
        return "STOP: report to human for review"

    # 3-failure step-back rule: fundamental reassessment
    # This threshold is a methodology-prescribed heuristic.
    if consecutive_failures >= 3:
        return "STEP_BACK: revert to last known good state, re-examine architecture"

    # Gate-specific remediation strategies
    remediation_map = {
        "EXIST":      "Remove hallucinated reference, find correct file/API",
        "RELEVANCE":  "Stash out-of-scope changes, return to current plan",
        "ROOT_CAUSE": "Revert to last good commit, try different approach",
        "RECALL":     "Re-read CLAUDE.md BOUND section, summarize constraints",
        "MOMENTUM":   "Stop analyzing — write something concrete, iterate on it",
    }

    return remediation_map.get(failed_gate, "Consult remediation.md playbook")

# After every remediation, the agent produces a structured report:
# [REMEDIATED] gate=ROOT_CAUSE action=revert_and_retry
#   was: editing src/payments/calc.py for the 4th time (same TypeError)
#   did: reverted to commit a1b2c3d, re-analyzed from scratch
#   now: trying middleware pattern instead
#   bound: no DANGER ZONE touched, no IRON LAW affected

The 3-failure step-back rule is particularly significant. When three consecutive remediation attempts fail, the agent is instructed to stop fixing symptoms and re-examine the architecture. In the documented blockchain case study (Section 61.4), this rule activated and led the agent to discover that the root cause was architectural (a single-node HTTP bottleneck) rather than code-level.

61.3.6 Mechanism 6: CLAUDE.md Dual-Strategy Parser

The BOUND constraints are extracted from CLAUDE.md by a dual-strategy parser in framework.py. The primary strategy uses regex-based parsing of standard section headers (### DANGER ZONES, ### NEVER DO, ### IRON LAWS), extracting backtick-wrapped paths from DANGER ZONES and list items from the other sections. If primary extraction finds nothing but BOUND markers are present, the parser falls back to heuristic mode — scanning for path-like strings near "DANGER" keywords, lines starting with "Never"/"Do not", and lines containing "must"/"always" near backtick-wrapped code.

The DANGER ZONE matcher uses path-segment-aware comparison rather than simple substring matching. Both the target file path and the zone pattern are split into path segments, and the matcher checks for contiguous subsequence matching. This prevents false positives: zone auth/ matches auth/login.py but not unauthorized.py.

61.3.7 Mechanism 7: Complexity Routing

During the PLAN stage, tasks are classified into one of four complexity levels based on six signals. This classification determines the level of formality required:

Signal	Trivial	Simple	Complex	Architectural
Max lines changed	20	100	500	Unlimited
Max files touched	1	3	10	Unlimited
Phase count	0	2	5	Unlimited
DANGER ZONE relation	Not touched	Adjacent	Inside	Modifies IRON LAW
Risk level	None	Low	Medium	High
Dependencies	None	Known	Unknown	External

The aggregation rule for complexity classification is not formally specified in the source material beyond the signal matrix above. The methodology instructs the agent to assess these signals and route the task accordingly — the classification is performed by the agent's own judgment rather than by a deterministic algorithm in framework.py. Trivial and simple tasks execute directly without phase decomposition. Complex and architectural tasks require decomposition into independently verifiable phases ordered by severity, each targeting 100–300 lines of change.

61.4 Key Results and Evaluation

Ouro Loop's results are documented through detailed session logs rather than standardized benchmarks — an important methodological caveat that limits the strength of evidence available. The project provides two real session logs in examples/ demonstrating the framework's operation on production codebases.

61.4.1 Blockchain L1: Consensus Performance Investigation

The primary case study involves an AI agent using Ouro Loop to investigate precommit latency spikes on a 4-validator PBFT blockchain — from 4ms baseline to 200ms under transaction load. The full session log is available at examples/blockchain-l1/session-log.md in the repository.

Key behavioral observations from the session:

• The agent tested 5 hypotheses and performed 4 autonomous remediations
• The ROOT_CAUSE gate fired 4 times, correctly identifying symptom-level fixes
• After 3 consecutive failed hypotheses, the 3-failure step-back rule activated, prompting architectural re-examination
• The root cause was architectural — a single-node HTTP bottleneck causing consensus-wide delays — not a code-level bug
• The agent caught its own flawed experiment: it identified that it was running 4× full stress instead of 1× distributed before drawing incorrect conclusions

Reported performance improvements (from the session log; single run, no statistical replication):

Metric	Before	After	Delta
Precommit latency (under load)	100–200ms	4ms	−98%
Block time (under load)	111–200ms	52–57ms	−53%
TPS variance	40.6%	1.6%	−96%
SysErr rate	0.00%	0.00%	= (IRON LAW maintained)
Blocks/sec (soak load)	~8.0	~18.5	+131%

61.4.2 Consumer Product: Lint Remediation

A simpler session demonstrating the ROOT_CAUSE gate's value in a React/Next.js codebase. The agent initially attempted to suppress ESLint errors (a classic symptom-fix). The ROOT_CAUSE gate identified this pattern and pushed the agent toward genuine solutions: replacing <img> with Next.js <Image>, properly handling useEffect state patterns, and using framework-appropriate patterns instead of lint suppression.

61.4.3 Evaluation Limitations and Missing Evidence

The evidence presented in Sections 61.4.1–50.4.2 demonstrates the framework's operational flow and illustrates how the verification gates and remediation protocol function in practice. However, it does not constitute a rigorous evaluation of the framework's efficacy. The following table summarizes the evaluation status:

Evaluation Dimension	Status	What Would Be Needed
Controlled comparison	Not provided	Same agent + task with and without Ouro Loop, multiple runs
Statistical replication	Not provided	Repeated runs with variance reporting; n ≥ 5 per condition
Gate accuracy	Anecdotal only	False-positive and false-negative rates for each gate across diverse tasks
DANGER ZONE blocking	Verified via test suite (507 tests)	Adversarial testing with prompt injection attempts
Remediation success rate	4/4 in blockchain case study	Rates across multiple codebases, tasks, and agent models
Token/time overhead	Author-estimated ranges	Measured overhead per phase with confidence intervals
Cross-agent comparison	Not provided	Same tasks evaluated with Claude Code vs Cursor vs Aider
BOUND quality sensitivity	Not studied	Performance under well-specified vs. poorly-specified BOUNDs

Provenance summary: The blockchain performance numbers come from a single session log provided by the author. They are not independently verified, averaged across multiple runs, or compared against a control group without Ouro Loop. The lint remediation case study is qualitative. Both sessions demonstrate the framework's operational mechanics (gate firing, remediation triggering, step-back activation) but do not isolate the framework's causal contribution to outcomes — the same skilled agent might have reached similar conclusions without the framework, albeit perhaps less efficiently or safely.

61.4.4 Framework Metrics

Metric	Value	Source
Test suite	507 tests passing	Repository CI badge
Codebase size	~91 KB across 3 Python files	Repository
External dependencies	Zero	Repository (pure stdlib)
Hook enforcement	Verified exit 2 hard-block	Repository tests
Reflective log format	JSONL, 30-entry rolling window	Repository
Results audit trail	TSV format	Repository
Python version	3.10+ (match/case, union types)	Repository

61.5 Implementation Details

61.5.1 State Management

The agent's position in the loop is persisted in .ouro/state.json using atomic writes via os.replace() with a fallback to shutil.move() for cross-device scenarios (Docker volumes, NFS mounts). The state tracks the project name, current stage, current phase number, total phases, BOUND definition status, and a history array of past stage/phase/verdict/timestamp tuples.

# PSEUDOCODE: Illustrative reconstruction of state management logic
# Based on the documented state.json schema and atomic-write pattern
# described in the repository. NOT a verbatim excerpt from framework.py.
#
# The actual implementation uses argparse for CLI integration and
# includes additional validation, error handling, and migration logic.

import os
import json
import shutil
from datetime import datetime, timezone

OURO_DIR = ".ouro"
STATE_FILE = os.path.join(OURO_DIR, "state.json")

def load_state() -> dict:
    """Load current loop state with default fallback.

    Returns the persisted state from .ouro/state.json, or a
    default state dict if the file does not exist (e.g., first run
    before initialization via prepare.py).
    """
    if not os.path.exists(STATE_FILE):
        return {
            "project_name": "",
            "current_stage": "BOUND",
            "current_phase": 0,
            "total_phases": 0,
            "bound_defined": False,
            "history": [],
            "updated_at": datetime.now(timezone.utc).isoformat()
        }
    with open(STATE_FILE, "r") as f:
        return json.load(f)

def save_state(state: dict) -> None:
    """Atomic state write via os.replace with cross-device fallback.

    Writes to a temporary file first, then atomically replaces the
    target. The os.replace() call is atomic on POSIX when source
    and target are on the same filesystem. The shutil.move() fallback
    handles cross-device scenarios (e.g., Docker bind mounts, NFS)
    but is NOT atomic — a crash during move could lose state.
    """
    state["updated_at"] = datetime.now(timezone.utc).isoformat()
    tmp_path = STATE_FILE + ".tmp"
    with open(tmp_path, "w") as f:
        json.dump(state, f, indent=2)
    try:
        os.replace(tmp_path, STATE_FILE)  # atomic on same filesystem
    except OSError:
        shutil.move(tmp_path, STATE_FILE)  # fallback for cross-device

61.5.2 Framework Overhead

Ouro Loop adds negligible compute overhead to the underlying agent's operation. The framework itself makes no LLM calls — all API costs are incurred by the wrapping agent (Claude Code, Cursor, etc.). The following overhead estimates are author-provided and have not been independently benchmarked:

Component	Latency (author-estimated)	Notes
framework.py CLI command	~50ms	State JSON read/write + git subprocess
Verification gates (all 5)	~200ms total	Each gate runs git with 10s timeout
Reflective log write	~10ms	JSONL append + trim to 30 entries
Hook evaluation	~100ms per hook	Shell script: CLAUDE.md parsing
State management	~5ms	JSON read/write with atomic replace

61.5.3 Estimated LLM Costs

Since Ouro Loop does not call LLMs directly, API costs depend entirely on the wrapping agent. The following are author-provided estimates based on Claude Sonnet pricing at time of publication:

Scenario	Est. Tokens	Est. Cost (Claude Sonnet)
program.md initial read	~4,000	~$0.01
Per-phase MAP+PLAN+BUILD cycle	10,000–50,000	$0.10–$0.50
Remediation cycle (on failure)	5,000–15,000	$0.05–$0.15
Full overnight session (10 phases)	200,000–500,000	$2–$5

The Sentinel 24/7 review module, which runs continuous Claude Code sessions using claude-opus-4-6 with up to 200 turns per session and 120-minute timeouts, carries a substantially higher cost: an estimated $50–$200 per day depending on project size, partition count, and finding density. This is a significant operational expense that must be budgeted for production use.

Provenance note: These cost estimates are provided by the author in the repository documentation. Actual costs will vary based on model pricing changes, token efficiency, and the specific agent used.

61.5.4 Reproducibility

The framework is available via pip install ouro-loop and is MIT-licensed with zero external dependencies. The minimal reproduction sequence is:

# Installation and initialization
# from repo: README.md — quickstart section

# Step 1: Install
pip install ouro-loop

# Step 2: Scan project structure
python -m prepare scan /path/to/project

# Step 3: Initialize .ouro/ state directory
python -m prepare init /path/to/project

# Step 4: Generate CLAUDE.md template
python -m prepare template claude /path/to/project

# Step 5: Edit CLAUDE.md with real BOUND constraints
# (human defines DANGER ZONES, NEVER DO, IRON LAWS)

# Step 6: Point AI agent at program.md
# "Read program.md and CLAUDE.md. Start the Ouro Loop for: [task]"

Key reproducibility limitations:

• LLM dependency: Results depend on the specific model used by the underlying agent. Different models produce different remediation strategies and code generation quality.
• Non-determinism: LLM-based code generation is stochastic; identical setups will produce different session trajectories.
• BOUND quality dependency: The framework's effectiveness depends heavily on the quality of the human-authored BOUND constraints. Poorly specified constraints lead to poor outcomes.
• Qualitative measurement: The core value proposition (overnight autonomous development without breakage) is measured through session logs, not standardized benchmarks.
• Enforcement portability: The hard-enforcement mechanism (hook-based DANGER ZONE blocking) is reproducible only with Claude Code; other agent integrations provide the methodology but not the runtime enforcement.

61.5.5 Sentinel: 24/7 Code Review Daemon

The sentinel.py module (~30 KB) implements a continuous, unattended code review daemon. It auto-discovers build/test/lint commands from 10+ project types, groups project directories into risk-scored partitions (cross-referenced against DANGER ZONES), and launches Claude Code sessions in a loop to scan for issues.

The Sentinel runner architecture ensures persistent operation through terminal closures and sleep/wake cycles:

• make sentinel-start launches via nohup with disown
• SIGHUP is absorbed by nohup on terminal close
• macOS launchd (PID 1) adopts the orphaned process
• The sentinel survives sleep/wake cycles as a launchd child

Sentinel maintains its own state directory (.ouro/sentinel/) with configuration, partition definitions, findings in JSONL format, iteration logs, a suppression store for confirmed false positives, and a learnings.md file that accumulates patterns across sessions — the system's only form of cross-session learning.

61.6 Relationship to Iterative Self-Repair and the Ouroboros Metaphor

61.6.1 The Self-Referential Cycle in Ouro Loop

The ouroboros metaphor — a self-referential cycle where a system's output feeds back as its input — manifests in Ouro Loop at multiple levels. At the micro level, each BUILD → VERIFY → REMEDIATE cycle consumes the agent's own errors as input for the next iteration. At the meso level, the LOOP stage feeds discoveries from completed phases back into the plan and potentially into the BOUND itself. At the macro level, the Sentinel module's learnings.md accumulates cross-session insights that inform future review sessions.

This self-referential structure can be described as an iterative map. Let $C_t$ denote the codebase state at iteration $t$, $B$ the BOUND constraints (approximately fixed within a session), and $f_\theta$ the LLM-based agent with parameters $\theta$ (frozen, since no fine-tuning occurs). The Ouro Loop iteration is:

where $V_1(C_t, B)$ is the Layer 1 verification verdict (Section 61.3.2), $L_t$ is the reflective log at time $t$, $g_{\text{fail}}$ is the specific failed gate, and $R(\cdot, \cdot)$ is the remediation function (Section 61.3.5). The reflective log update is:

where $\text{trim}_{30}$ retains only the 30 most recent entries. The $\text{pattern}(L_t)$ term encodes the six behavioral signals from Section 61.3.4, creating the self-referential loop: the agent's past behavior (encoded in $L_t$) influences its future actions through pattern detection and alert generation.

61.6.2 Distinguishing Iterative Self-Repair from Evolutionary Search

While the Ouro Loop's iterative structure shares surface-level similarities with evolutionary systems surveyed in earlier chapters, it is important to be precise about what is and is not analogous:

Property	Evolutionary Systems (e.g., FunSearch, AlphaEvolve)	Ouro Loop
Population	Maintains a population of candidate solutions	No population. Single codebase, single agent
Selection	Fitness-based selection from population	No selection. Binary pass/fail verification
Variation operators	Mutation, crossover, recombination	No structured variation. Agent generates fixes via general-purpose reasoning
Fitness function	Scalar or multi-objective fitness score	No fitness function. Multi-gate verification with categorical outcomes
Iteration	Generate → evaluate → select cycle	BUILD → VERIFY → REMEDIATE cycle (structurally similar)
Self-improvement	Population improves over generations	LOOP stage feeds discoveries back into plan
Escape from local optima	Population diversity, mutation, island migration	3-failure step-back rule forces different approaches
Long-term memory	Skill libraries, knowledge archives	Sentinel's learnings.md (rudimentary analog)

The Ouro Loop is more accurately characterized as an iterative self-repair loop with structured verification than as an evolutionary system. It lacks the defining features of evolutionary computation: a population of competing solutions, fitness-proportional selection, and stochastic variation operators. The self-referential feedback through reflective logging provides behavioral adaptation within a session but does not implement the kind of open-ended search that characterizes true evolutionary processes.

Where the analogy does hold is in the meta-structure: both evolutionary systems and Ouro Loop implement a generate-evaluate-iterate cycle where the evaluation signal guides subsequent generation. The 3-failure step-back rule serves a function loosely analogous to diversity mechanisms in evolutionary search — forcing the agent to abandon a stagnant approach — but without the population-level mechanisms that make evolutionary search effective at exploring large solution spaces. The Sentinel's learnings.md is a rudimentary analog to the skill libraries and knowledge archives of more sophisticated evolutionary platforms, but it accumulates free-text patterns rather than structured, reusable solution components.

61.6.3 Persistent Agent State and Context Decay

A central design challenge for long-running autonomous agents is context decay — the gradual loss of critical information as the LLM's context window fills and older content is summarized or dropped. Ouro Loop addresses this through three complementary mechanisms:

1. The RECALL verification gate periodically checks whether the agent can still parse and reference its BOUND constraints
2. The recall-gate.sh PreCompact hook re-injects the BOUND section into context immediately before the agent's context window is compressed (Claude Code-specific)
3. Explicit program.md instructions direct the agent to run the RECALL gate and re-read CLAUDE.md every 5 phases or approximately 30 minutes

The combination of verification (detecting decay), injection (preventing decay during compression), and scheduled re-reads (proactively refreshing constraints) represents a defense-in-depth approach to context management. The PreCompact hook is particularly notable as an architectural solution — it leverages the agent platform's own lifecycle events to solve a fundamental limitation of transformer-based LLMs. However, this mechanism is available only in Claude Code; agents without a pre-compression event must rely solely on the RECALL gate and scheduled re-reads, which are compliance-based rather than enforcement-based.

61.7 Comparative Analysis

Ouro Loop occupies a distinctive position in the landscape of LLM-powered autonomous systems. It is not an agent, not a search algorithm, and not an evaluation framework — it is a methodology wrapper that makes existing agents safer. This distinction shapes every comparison.

System	Approach	Enforcement	Self-Repair	Memory
Ouro Loop	Bounded autonomy + methodology	Runtime hooks (hard block for spatial constraints; advisory for behavioral/invariant)	Autonomous remediation with playbook	Reflective log + pattern detection
autoresearch	Metric-driven experiment loop	Budget constraint (5 min)	Auto-revert on metric regression	None (stateless between runs)
.cursorrules	Static instruction file	None (compliance-based)	None	None
CLAUDE.md (vanilla)	Static instruction file	None (agent compliance)	None	None
Devin	Full autonomous agent	Proprietary (details undisclosed)	Built-in (proprietary)	Session memory (proprietary)
SWE-Agent	Issue resolution agent	Test suite pass/fail	Retry with feedback	Episode memory

Comparative caveat: Comparisons with Devin and SWE-Agent are based on publicly available documentation and published papers; internal enforcement mechanisms of proprietary systems cannot be verified.

61.7.1 Comparison with autoresearch

The most direct comparison is with Karpathy's autoresearch, which Ouro Loop explicitly extends. Both share the three-file architecture and the philosophy of human-authored methodology with agent-executed iteration. The key differences are:

Dimension	autoresearch	Ouro Loop
Domain	ML experiments	General software engineering
Constraint type	Budget (5-minute training)	Multi-layer BOUND (spatial + behavioral + invariant)
Success metric	Single scalar (val_bpb)	Multi-gate verification + self-assessment
On failure	Auto-revert, next experiment	Structured remediation by gate type
Context awareness	None	Three-layer reflective log + pattern detection
Long-term memory	None	Sentinel learnings.md
Human programs	program.md only	program.md + CLAUDE.md (boundaries)

The principal advance is the move from a single-scalar constraint (training budget) to a multi-dimensional constraint system (DANGER ZONES + NEVER DO + IRON LAWS), combined with runtime enforcement that operates below the agent's reasoning layer for spatial constraints. Autoresearch trusts the agent to respect the budget; Ouro Loop makes it impossible to violate spatial constraints when running under Claude Code, while relying on structured self-assessment for non-spatial constraints.

61.7.2 Comparison with Evolutionary Systems

Relative to the evolutionary algorithm discovery systems surveyed in earlier chapters (FunSearch, AlphaEvolve, OpenEvolve, GEPA), Ouro Loop operates at a fundamentally different level of abstraction. Those systems evolve programs or heuristics through population-based search with fitness evaluation. Ouro Loop does not maintain a population, does not have a fitness function, and does not perform selection or crossover. Instead, it structures the single-agent development process with safety constraints and verification gates.

As discussed in Section 61.6.2, the iterative BUILD → VERIFY → REMEDIATE cycle shares structural similarity with the generate → evaluate → select cycle of evolutionary systems, but the absence of populations, selection pressure, and variation operators means Ouro Loop does not implement evolutionary search in the technical sense. The Sentinel's cross-session learnings.md is a rudimentary analog to the skill libraries and knowledge archives of more sophisticated evolutionary platforms, but it accumulates unstructured text rather than indexed, reusable solution components.

61.8 Limitations and Discussion

61.8.1 Fundamental Limitations

No learning in the ML sense. The agent's underlying LLM is not fine-tuned. All "learning" is purely in-context — the reflective log provides behavioral pattern memory, but this is bounded by the 30-entry window and does not persist across sessions (except via Sentinel's learnings.md).

Session-bounded memory. The main loop's reflective log is per-session. New sessions start fresh and must read state.json to resume. There is no mechanism for transferring remediation patterns across sessions or projects.

Human-dependent BOUND quality. The framework's effectiveness depends critically on the quality of human-authored constraints. Poorly specified DANGER ZONES, incomplete NEVER DO rules, or unverifiable IRON LAWS undermine the entire system. The author estimates 15–30 minutes for initial BOUND definition, but this requires domain expertise about which files and invariants are critical.

Qualitative evaluation only. Results are presented through session logs rather than standardized benchmarks. There is no controlled study comparing agent performance with and without Ouro Loop, no statistical replication, and no third-party validation of the reported improvements (see Section 61.4.3 for the full evaluation gap analysis).

Single-agent design. The framework is designed for one agent operating on one codebase. How BOUND would work with multiple agents operating on different parts of the codebase simultaneously is an open question.

61.8.2 Enforcement Gaps: Hard vs. Soft Constraints

The distinction between enforcement levels is the most important nuance for users evaluating Ouro Loop's safety properties. The system provides three distinct enforcement tiers:

Tier	Constraint Type	Enforcement Mechanism	Can Agent Bypass?	Scope
Tier 1: Hard-enforced	DANGER ZONES (spatial)	bound-guard.sh hook → exit 2	No (Claude Code); Yes (other agents)	File/directory write protection
Tier 2: Machine-checked	IRON LAWS (where automatable)	Test suite, coverage tools, linters invoked in VERIFY L1	Only if agent skips the VERIFY stage	Verifiable invariants (e.g., coverage thresholds)
Tier 3: Self-assessed	NEVER DO + semantic IRON LAWS	Agent self-assessment in VERIFY L2	Yes (agent may fail to detect own violations)	Behavioral rules, semantic invariants

Tier 3 constraints face the same fundamental weakness as instruction-only guardrails: they depend on the agent's ability to detect its own violations. Ouro Loop structures and schedules self-assessment more rigorously than vanilla instruction files (it runs at defined intervals, with explicit checklists, and results are logged), but the underlying enforcement gap remains. A sufficiently complex behavioral constraint may be violated without the agent realizing it during self-assessment.

This means that claims about "inviolable constraints" or "absolute boundaries" in the Ouro Loop documentation apply fully only to Tier 1 (DANGER ZONE blocking on Claude Code). Users deploying Ouro Loop for safety-critical domains should understand that NEVER DO rules and many IRON LAWS are advisory rather than enforced, and should design their constraints to maximize the proportion that can be machine-checked (Tier 2) rather than relying on self-assessment (Tier 3).

61.8.3 Open Research Questions

• Semi-automatic BOUND derivation: Could DANGER ZONES be inferred from production incident history, git blame patterns, or code complexity metrics?
• Cross-project transfer: Could remediation patterns learned on one project be distilled into reusable playbooks for similar project types?
• Hook ecosystem portability: The current 5 hooks target Claude Code specifically. Extending hard enforcement to other agents (Cursor, Aider) requires agent-specific hook mechanisms that may not exist. This is the primary barrier to true agent-agnosticism at the enforcement layer.
• Quantitative evaluation: A controlled study with multiple agents, tasks, and BOUND configurations would be valuable for establishing the framework's empirical contribution beyond qualitative session logs. Key metrics would include gate false-positive/false-negative rates, remediation success rates, and time/token overhead under controlled conditions.
• Scaling to multi-agent: Conflict resolution when multiple agents share a codebase with overlapping DANGER ZONES is unexplored territory.
• Threshold calibration: The current thresholds (3-edit hot-file detection, 0.3 velocity-trend swing, 3-failure step-back) are methodology-prescribed heuristics. Empirical calibration across diverse projects would strengthen the framework's operational robustness.

61.9 Summary