Soma

Governance framework that makes AI coding agents trustworthy.

Soma makes AI agents trustworthy not by asking them to behave, but by making misbehavior structurally unprofitable. Built on evidence-based selection, adversarial verification, and incentive-compatible rule evolution, it ensures AI coding agents remain grounded, efficient, and safe — then proves it.

The Problem: Ungoverned AI coding agents waste significant portions of tokens in circular rework loops, hallucinated API calls, and broken assumptions (arXiv:2602.11988, arXiv:2607.27250). Static rule files (.cursorrules, CLAUDE.md) help but never adapt, and the agent can simply ignore them.

The Solution: Soma reduces waste to under 1.0% in governed sessions while adding only ~3,800 idle context tokens (measured at v0.50 baseline, stabilized via JIT Context — down 8.6% from Phase 11 baseline despite adding 7 new enzymes). Rules that stop proving themselves expire and are pruned. Rules that keep proving themselves get promoted. Claims that don't match evidence are caught. This is incentive-compatible governance.

Internal naming convention: Soma uses a biological metaphor internally (genome, enzymes, organs, cells) to model rule evolution — see the codebase for details.

See the NOTICE file for our full local-only Data Privacy Statement.

Quick Start

Install

# Clone
git clone https://github.com/nseney1/Soma-Governance.git && cd Soma-Governance

# Install the CLI
pip install -e .

# Set up governance (auto-detects your platform)
soma init --yes

# See what's active
soma status

# Global install via Makefile (Gemini / Antigravity)
make install

# Shell installer for specific platforms
bash install/install.sh gemini     # Google Gemini
bash install/install.sh copilot    # GitHub Copilot
bash install/install.sh claude     # Claude Code
bash install/install.sh kiro       # AWS Kiro
bash install/install.sh mcp        # Any MCP-compatible agent

MCP Server (Recommended)

Add Soma as an MCP server in your AI agent's config — zero API key needed. The agent is the LLM.

{
  "mcpServers": {
    "soma": {
      "command": "python3",
      "args": ["-m", "soma_mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Works with Gemini Antigravity, Claude Code, Cursor, and any MCP-compatible agent. Tools exposed: soma_create_cell, soma_scan, soma_grade, soma_coverage, soma_fitness, soma_list_cells, soma_report_outcome, soma_propose_change, soma_audit_security, soma_audit_performance, soma_verify_changes, soma_checkpoint.

SDK

pip install soma-governance        # Python
npm install soma-governance        # JavaScript / TypeScript

from soma_sdk import Governance

gov = Governance(project_root='.')
landscape = gov.fitness_landscape(bayesian=True)
coverage = gov.coverage_report()
grade = gov.grade()
gov.signal('wall-gae-truncation', 'tp', metric={'survival_day': 12})

const { Governance } = require('soma-steering');
const gov = new Governance('.');
const grade = await gov.grade();
const entropy = await gov.entropy();

Onboarding

After installation, open your AI assistant in your project and prompt:

Run the genesis organ to inspect this repository and seed governance cells.

Genesis scans your stack (languages, frameworks, dependencies) and creates tailored .soma/cells/ in seconds. Domain templates (templates/) are auto-detected based on your project type.

Natural Language Rule Creation

Create adaptive rules by describing your concern in plain English:

bash enzymes/cell_create.sh --from-description "PPO clip ratio must stay between 0.1 and 0.3"

Works with any AI provider — Gemini, Anthropic, OpenAI — or via MCP stdio (zero API key needed when running inside an AI agent). Set --provider gemini|anthropic|openai|prompt-only or configure SOMA_INFERENCE_PROVIDER in soma.conf.

CLI Commands

All governance workflows are available via the soma CLI:

# Quick quality check before committing
soma checkpoint

# Deterministic verification (Layer 1)
soma verify

# Cell health dashboard
soma oracle --json

# See what cells earned promotion
soma promote --dry-run

Architecture

Soma models governance as a layered system of rules, skills, and automation. Every component maps to a specific role:

┌──────────────────────────────────────────────────────────────────────┐
│  📐 CORE RULES (genome/)          15 Rules — inherited defaults      │
│  🔧 AGENT SKILLS (organs/)       15 Skills — complex behaviors       │
│  ⚙️  AUTOMATION (enzymes/)        58 Scripts — task automation        │
├──────────────────────────────────────────────────────────────────────┤
│  🛡️ REVIEW PROTOCOL              Two-Layer Verification              │
│     Layer 1: Deterministic AST tools (ungameable)                    │
│     Layer 2: Adversarial information-partitioned agents              │
├──────────────────────────────────────────────────────────────────────┤
│  🌲 REVIEW INTENSITY (Global) → Environmental Pressure Levels       │
│     Breeze → Gale → Trident → Maelstrom → Tempest → Supercell       │
│  🔍 ANALYTICAL PRONGS         → Multi-Perspective Analysis          │
│     Spores → Mycelium → Roots → Thorns → Bedrock → Mulch            │
│  📋 ADAPTIVE RULES (.soma/cells/) → Per-Repo Governance             │
│     Vacuoles · Chloroplasts · Walls · Membranes · Plasmodesmata      │
└──────────────────────────────────────────────────────────────────────┘

🛡️ Review Protocol — Two-Layer Verification

Soma's two-layer verification framework eliminates the "trust the agent" problem through deterministic tooling and adversarial information asymmetry.

Layer 1: Deterministic Tools (Ungameable)

AST-based analysis tools that produce objective evidence — no LLM judgment involved:

All tools return ToolEvidence with a boolean verdict — the runner.py orchestrator produces a combined gate verdict.

Layer 2: Adversarial Information-Partitioned Agents

Two agents review the same change but see different information:

┌─────────────────┐     ┌──────────────────┐
│   SPEC AGENT    │     │   CODE AGENT     │
│ Sees: task spec │     │ Sees: code + tests│
│ Predicts: risks │     │ Claims: what holds│
└────────┬────────┘     └────────┬─────────┘
         │                       │
         └───────┐   ┌──────────┘
                 ▼   ▼
         ┌───────────────┐
         │    ARBITER     │
         │ (Set Algebra)  │
         │ 14 Risk Cats   │
         │ SHIP/BLOCK/    │
         │ REVISE         │
         └───────────────┘

• No collusion: Agents can't agree on answers because they don't see the same inputs.
• Deterministic arbiter: Uses pure set intersection/difference over a fixed 14-category risk taxonomy — no LLM in the arbitration loop.
• Verdicts: SHIP (convergence), BLOCK (critical divergence), REVISE (non-critical divergence).

Transcript Verifier

Independently verifies subagent self-reported claims against JSONL transcript evidence:

from immune_system.verification.transcript_verifier import extract_metrics, verify_claim

metrics = extract_metrics("path/to/transcript.jsonl")
result = verify_claim(metrics, claimed_first_pass=True, claimed_tests_passed=45, agent_role="coder")
# → ToolEvidence(verdict=False, detail="Agent claimed first-pass but transcript shows 3 fix cycles")

🛡️ Review Protocol (Review Modes)

When code changes, the system mounts a review response. The intensity scales with risk:

Review Intensity Levels

Analytical Prongs

Note: An escalation sentinel runs dynamically in the PreInvocation lifecycle to evaluate diff sensitivity and auto-escalate the review mode.

📐 Core Rules

The system's foundational rules — 15 rules that define inherited behavior. Always-on rules are loaded every session; conditional rules activate on demand.

🔧 Agent Skills

Complex multi-step behaviors — each skill performs a specialized function.

📋 Adaptive Rules

Adaptive rules are the per-repository governance layer — atomic, dynamically generated invariants that live exclusively inside your repository (.soma/cells/).

Rule Lifecycle

Adaptive rules operate on an evidence-based evolutionary lifecycle:

Generate → Score (Confidence Decay) → Adapt / Crossover → Differentiate → Prune / Retire → Promote
   ↑                                                                                          |
   └──────────────────────── External Fitness Signals (CI/CD, tests, metrics) ────────────────┘

Evolutionary operators: Crossover (merges high-fitness rules), Tournament Selection (diversity-preserving), Differentiation (vacuoles harden into walls), Confidence Decay (confidence decays unless reinforced), Retirement (immediate eviction on excess false positives), Horizontal Transfer (cross-project sharing with probation), Version History (provenance tracking).

Research-grade analysis: Bayesian Fitness (Beta-Binomial posterior with Laplace smoothing), Quorum Sensing (systemic multi-rule triggers), Coverage Maps, Governance Replay ("would today's rules have caught this bug?"), Counterfactual ROI, Adversarial Testing, Entropy Rate (fossilization detection), Report Card (A+ through F).

Tiered enforcement: Rules earn their enforcement tier through demonstrated defect prevention — advisory (prompt injection) → mechanical (pre-commit block at 85%) → gate (runtime assertion at 95%). Escaped Defect Tracking from CI/tests/crashes provides ground truth that breaks the self-evaluation loop.

⚙️ Automation Scripts

58 task-specific scripts that drive the system's operations. See SCRIPTS.md for full documentation.

Configuration

Copy soma.conf.example → soma.conf to customize.

Cross-OS Support

Team Setup

Soma supports team-level governance convergence via shared Git repositories:

bash enzymes/team_sync.sh push    # Sync local rules + metrics
bash enzymes/team_sync.sh pull    # Pull rules from teammates

Configure TEAM_REPO and optionally ORG_REPO in soma.conf for multi-team hierarchies.

How Soma Differs

Recent academic studies (arXiv:2602.11988, arXiv:2607.27250, arXiv:2510.04618) have exposed the critical flaws in standard agentic coding tools and static context files (like AGENTS.md or CLAUDE.md). Soma was explicitly architected to solve the fatal traps identified in this research:

1. The Context Bloat Trap

The Research: Injecting massive repository overviews into the context window does not improve task success, increases inference costs by over 20%, and leads to "brevity bias" or "context collapse" as the agent loses track of details over time. Soma's Solution: JIT (Just-In-Time) Context Loading. Soma does not load a monolithic rulebook. It only loads the specific adaptive rules related to the exact files the agent is currently touching. This keeps the token overhead at a flat ~3,800 idle tokens (measured at v0.50 baseline), preventing context collapse.

2. The Generic Advice Trap

The Research: Context files are largely ignored by LLMs when they contain standard coding practices (which the models already know), and are only useful for "non-standard coding practices" or exact wiring/architectural quirks. Soma's Solution: Repository-Specific Traps. Soma's adaptive rules (Vacuoles, Chloroplasts) don't exist to tell the LLM to "write clean code." They exist exclusively to map traps the base model couldn't possibly know zero-shot (e.g., "The HUD calibration in the renderer is offset by 4px"). If a rule can't prove it caught a specific defect, it is pruned.

3. The "Self-Grading" Trap

The Critique: If an AI agent generates rules and then grades its own rules, isn't that just memory with extra steps? How do we know the rules are working, and it's not just the underlying foundation models getting better? Soma's Solution: Two-Layer Verification. Layer 1 uses deterministic AST tools (mutation testing, call graph analysis, branch coverage, import guards) that produce objective evidence no LLM can game. Layer 2 uses adversarial information-partitioned agents — a Spec Agent and Code Agent that can't collude because they see different inputs — with a deterministic set-algebra Arbiter. The Transcript Verifier independently checks subagent claims against actual execution logs. Additionally, Escaped Defect Tracking hooks into CI/CD exit codes to establish ground truth.

Instead of pleading with the AI in a system prompt to "think step-by-step," Soma acts as an evolutionary governance system. Rules that can't prove themselves die. Agents that refuse to research are blocked. Claims that don't match the tape are caught.

Metrics

• Total System Idle Overhead: ~3,800 tokens/turn (measured at v0.50 baseline — down 8.6% from Phase 11 despite 7 new enzymes)
• Typical Load (genome + 3 matched cells): ~4,013 tokens/turn
• Waste Rate: < 1.0% in governed sessions (via Last Gasp & TTC Oracles)
• Calibrated Token Ratio: 1.35 measured directly against Gemini API
• Verification Framework: 1,162+ tests across 30+ test files

See METRICS.md for a complete system breakdown. See BENCHMARK.md for the standardized governance effectiveness benchmark.

Design Principles

1. Evidence over intuition — Every rule traces back to observed steps wasted. No rule exists "just in case."
2. Accuracy over speed — The agent must never sacrifice correctness to save tokens.
3. Convergence as verification — Independent agents with asymmetric information arriving at the same conclusion is stronger evidence than any single agent's assessment.
4. Rules as a system — Cross-references between rules are intentional. Providence §3 mandates read-before-write; refactoring-pilot operationalizes it as a phased workflow.
5. Continuous validation — Governance is a living system that evolves with each session. TTC Oracles validate actions before they waste context.
6. Installation completeness — Governance installed at partial fidelity provides false assurance. Every installer path must deploy core rules, agent skills, and hooks with the same completeness.
7. Hypothesis-driven governance — Every extension must carry its own falsifiability criteria. Generated rules (Chloroplasts, Vacuoles) must specify what they predict, how to measure it, and when to prune if unvalidated. The scientific method is not just how we evolve the system — it IS the system.
8. Independent validation — Self-evaluated fitness is necessary but not sufficient. Escaped defects from CI, tests, and crashes provide the ground truth that breaks the agent-grades-itself loop.

Testing & CI

Test Suite

make test       # Full validation + pytest
make validate   # Shell syntax, Python compilation, JSON templates
make doctor     # System health check

1,162+ tests across 30+ test files covering:

CI/CD Pipeline

GitHub Actions runs on ubuntu-latest, macos-latest, and windows-latest:

• Linux/macOS: Shell syntax validation → Python compilation → pytest → hardcoded path audit → script count invariant (≥16) → privacy audit → dry-run install sweep (all 5 platforms)
• Windows: PowerShell AST parsing → dry-run install with rule count assertion

Version History

Soma has evolved across 50 measured phases, from manually written logic into a self-adapting governance framework:

Read PHYLOGENY.md for the complete evolutionary narrative.

Documentation

Next Steps

• 🚀 Try Soma: make install and run Genesis on your repository
• 🔌 MCP Server: Add Soma to your agent's MCP config — zero API key needed
• 📦 Use the SDK: pip install soma-steering or npm install soma-steering
• 🔮 NL Rule Creation: cell_create.sh --from-description "your concern here"
• 📊 Report Card: python3 enzymes/immune_grade.py for instant governance health
• 📐 Explore Templates: Browse domain packs in templates/
• 📄 Read the Research: Review the Abstract and Phylogeny
• 🤝 Contribute: See CONTRIBUTING.md

Uninstalling

bash install/uninstall.sh gemini                # Remove Soma files, restore backups
bash install/uninstall.sh gemini --dry-run       # Preview what will be removed
bash install/uninstall.sh gemini --keep-config   # Preserve soma.conf
bash install/uninstall.sh gemini --no-restore    # Skip backup restoration
bash install/uninstall.sh gemini --force         # Skip confirmation prompt
bash install/uninstall.sh gemini --purge-data    # Also remove cells, fitness history

On Windows (PowerShell):

pwsh install\uninstall.ps1 -Platform gemini
pwsh install\uninstall.ps1 -Platform gemini -DryRun

Existing .prism/ directories are auto-migrated to .soma/ on install.

License

Apache 2.0 — Copyright 2026 Nicholas Seney See NOTICE for Data Privacy details.