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 adaptive 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. 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 ~4,380 tokens/turn idle overhead. Rules that stop proving themselves expire and are pruned. Rules that keep proving themselves get promoted. Claims that don't match evidence are caught.

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 (Python 3.9+)
pip install -e .

# Or install from PyPI
pip install soma-governance

# 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-governance');
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 eliminates the "trust the agent" problem through deterministic tooling and adversarial information asymmetry. Layer 1 executes ungameable AST-based verification (persistence checks, call graph analysis, mutation testing, branch coverage, import guards), while Layer 2 deploys information-partitioned agents evaluated by a deterministic set-algebra arbiter. Execution logs are independently audited via the Transcript Verifier.

For full architectural details and formal mechanism design analysis, see MECHANISM_DESIGN.md.

🛡️ 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

Soma includes 87 task-specific scripts driving rule lifecycles, verification, and evidence pipelines. 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

Soma replaces passive prompt files with active evolutionary governance: JIT context loading prevents bloat, adaptive cells trap repo-specific bugs, and two-layer verification eliminates self-grading.

For academic research analysis and empirical findings, see ABSTRACT.md.

Metrics

• Total System Idle Overhead: ~4,380 tokens/turn
• 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,278 tests across 30+ test files

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

Design Principles

Soma is built on empirical grounding, adversarial convergence, continuous validation, and hypothesis-driven governance. See PHYLOGENY.md for foundational design principles and evolutionary narrative.

Testing & CI

Test Suite

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

The test suite contains 1,278 tests across 30+ test files covering rule validation, Bayesian fitness scoring, AST invariants, and two-layer verification. See CONTRIBUTING.md for test guidelines and execution instructions.

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: soma init --yes and run soma genesis on your repository
• 🔌 MCP Server: Add Soma to your agent's MCP config — zero API key needed
• 📦 Use the SDK: pip install soma-governance or npm install soma-governance
• 🔮 NL Rule Creation: cell_create.sh --from-description "your concern here"
• 📊 Report Card: soma report 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.