Governed Agents

Governed Agents

Deterministic verification + reputation scoring for AI sub-agents. Prevents hallucinated success ("I did it!") by verifying claims independently before updating the agent's score.

Pure Python stdlib — zero external dependencies.

Capabilities

Spawns external CLIs (codex, openclaw, git, pytest) and makes HTTP HEAD requests.

When to Use

Use this skill when you need to:

• Spawn sub-agents and verify their output automatically
• Score agent reliability across tasks (EMA-based reputation)
• Detect hallucinated success — agent claims "done" but files are missing or tests fail
• Verify open-ended tasks (research, analysis, strategy) via LLM Council
• Enforce supervision levels based on agent track record

Quick Start

Coding Tasks (Deterministic Verification)

from governed_agents.contract import TaskContract
from governed_agents.orchestrator import GovernedOrchestrator

contract = TaskContract(
    objective="Add JWT auth endpoint",
    acceptance_criteria=["POST /api/auth returns JWT", "Tests pass"],
    required_files=["api/auth.py", "tests/test_auth.py"],
    run_tests="pytest tests/test_auth.py -v",
)

g = GovernedOrchestrator(contract, model="openai/gpt-5.2-codex")
# After agent completes:
result = g.record_success()  # runs gates, updates reputation

Open-Ended Tasks (3-Layer Pipeline + LLM Council)

contract = TaskContract(
    objective="Write architecture decision record for auth module",
    acceptance_criteria=["Trade-offs documented", "Decision stated"],
    verification_mode="council",
    task_type="analysis",
    council_size=3,
)

g = GovernedOrchestrator(contract, model="openai/gpt-5.2-codex")
prompts = g.generate_council_tasks(worker_output)
result = g.record_council_verdict(raw_reviewer_outputs)
# → "Council: 2/3 approved (score=0.67, PASS ✅)"

CLI Spawning (Codex / OpenClaw)

from governed_agents.openclaw_wrapper import spawn_governed

contract = TaskContract(
    objective="Build a REST API for todos",
    acceptance_criteria=["CRUD endpoints work", "Tests pass"],
    required_files=["api.py", "tests/test_api.py"],
)

# Uses Codex 5.3 CLI by default
result = spawn_governed(contract, engine="codex53")
# Or via OpenClaw agent CLI:
result = spawn_governed(contract, engine="openclaw")

Verification Modes

Deterministic (Coding Tasks)

4 gates run automatically — all must pass:

If agent claims SUCCESS but any gate fails → score override to -1.0 (hallucination penalty).

Council (Open-Ended Tasks)

3-layer pipeline with short-circuit:

1. Structural Gate (<1s) — word count, required sections, no empty sections
2. Grounding Gate (5–30s) — URL reachability, citation checks
3. LLM Council (30–120s) — N independent reviewers, majority vote

If Layer 1 fails → no LLM calls, instant result, zero cost.

Reputation System

R(t+1) = (1 − α) · R(t) + α · s(t),   α = 0.3

Supervision Levels

Task-Type Profiles

Pre-configured gate combinations:

Installation

bash install.sh
# → Copies governed_agents/ to $OPENCLAW_WORKSPACE/governed_agents/
# → Runs verification suite (37 tests)

Tests

python3 -m pytest governed_agents/test_verification.py \
                   governed_agents/test_council.py \
                   governed_agents/test_profiles.py -v
# 37 passed