Soma

Governance framework that makes AI coding agents trustworthy.

Soma makes AI agents trustworthy by providing observably traceable governance — evidence-based rule selection, AST analysis tools, and adaptive rule lifecycle management. Rules that stop proving themselves expire. Rules that keep proving themselves get promoted. Claims that don't match evidence are caught.

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 provides JIT context injection, adaptive rule lifecycle, and pre-commit enforcement hooks to reduce waste. Rules are scored by Wilson-bounded fitness intervals and pruned when they stop proving value.

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 Gemini, Claude Code, Cursor, or Copilot)
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. Set SOMA_WORKSPACE to the governed project (the directory containing .soma/cells/). No API key is needed because the host agent supplies the model.

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

Works with Gemini Antigravity, Claude Code, Cursor, and any MCP-compatible agent.

Capabilities: With SOMA_EXECUTION_ENABLED omitted, the server exposes six read tools and three write tools. Write tools are discoverable but require a receipt. Setting SOMA_EXECUTION_ENABLED=1 additionally exposes six execute tools, which also require receipts.

Receipt flow for write and execute tools:

1. Call soma_request_receipt with the intended tool name in operation and the exact tool arguments in arguments. For soma_report_outcome, those arguments must include a non-empty, retry-stable idempotency_key.
2. Call that tool with the same arguments plus the returned receipt.

Receipts expire after 300 seconds and are single-use. They are bound to the current MCP session, canonical workspace, operation, exact arguments, target-file state, and governance-cell state. If a target file or any cell changes before redemption, request a new receipt. Receipts authorize a specific state-bound operation; they do not authenticate a person. Reusing the same soma_report_outcome idempotency key with the same payload is a no-op; changing the payload for that key fails closed.

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();

CLI Commands

All governance workflows are available via the soma CLI:

# Quick quality check before committing
soma checkpoint

# AST analysis (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/)          18 Rules — inherited defaults      │
│  🔧 AGENT SKILLS (organs/)       15 Skills — complex behaviors       │
│  ⚙️  AUTOMATION (enzymes/)        61 Scripts — task automation        │
├──────────────────────────────────────────────────────────────────────┤
│  🛡️ VERIFICATION                  AST analysis tools                  │
│     Layer 1: AST-based checks (import guards, complexity, coverage)  │
├──────────────────────────────────────────────────────────────────────┤
│  📋 ADAPTIVE RULES (.soma/cells/) → Per-Repo Governance             │
│     Vacuoles · Chloroplasts · Walls · Membranes · Plasmodesmata      │
└──────────────────────────────────────────────────────────────────────┘

📐 Core Rules

The system's foundational rules — 18 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 lifecycle:

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

Lifecycle operators: 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).

Fitness scoring: Wilson-bounded fitness scoring with credible intervals — cells are scored by true positive rate using Wilson score intervals for statistically rigorous confidence bounds. Laplace smoothing (tp + 1) / (triggers + 2) provides the point estimate; Wilson bounds determine promotion and pruning thresholds. The Python SDK and enzymes use the canonical parse_cell_file parser; the dependency-light MCP path uses its documented standard-library frontmatter parser.

Credit assignment: Scope-narrowed credit assignment with per-file conservation — when multiple cells match the same changed file, each cell's fitness signal is weighted by 1/N (where N = matching cells for that file). Fractional credit is stored deterministically rather than randomly rounded. Canonical events are recorded in .soma/evidence/signals.jsonl with credit and provenance metadata.

Structured crossover: Structured field-level rule merging — two high-fitness cells can be crossed to produce offspring with combined hypotheses, max impact weight, merged target paths (union), and reset fitness counters. Lineage tracking records parent IDs, generation number, and creation method.

Tournament selection: Tournament selection for rule competition — random k-sample selection identifies the highest-fitness cell per round. Read-only operation preserves cell state. Handles null fitness, oversized k, and empty cell directories gracefully.

Tiered enforcement: Rules earn their enforcement tier through demonstrated defect prevention — advisory (prompt injection) → mechanical (pre-commit block) → gate (CI block). Enforcement ladder evaluates cell invariants and applies tier-appropriate blocking.

Quorum sensing: Multi-rule consensus for high-confidence decisions — when ≥N cells trigger simultaneously on the same changed files, Soma detects a systemic issue and escalates the review mode to the highest minimum_mode among triggered cells. Quorum events are logged to JSONL for trend analysis.

Gate enforcement DSL: Cells can declare invariants in frontmatter (e.g., import_banned, file_must_exist) that are evaluated against changed files. Violations are enforced according to the cell's enforcement tier: advisory warns without blocking, gate exits non-zero in CI.

Planned features: See ROADMAP.md for upcoming work.

⚙️ Automation Scripts

Soma includes 61 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

⚠ Windows known issues (open): Under Windows PowerShell 5.1, the default for .\install.ps1, the installer writes mojibake into the generated rules (BUG-014); use pwsh to avoid it. Under Git Bash, hooks are not installed when the only python3 on PATH is the Windows Store stub, which is the default with a python.org install. On Windows, the test suite also writes to the real home directory, including tests/test_install_lifecycle.py, the required test for the cross-platform claim (BUG-010, #47). Details and workarounds: Known Issues — Windows.

How Soma Differs

Soma replaces passive prompt files with active lifecycle-managed governance: JIT context loading prevents bloat, adaptive cells trap repo-specific bugs, and AST analysis catches violations deterministically.

For design analysis, see ABSTRACT.md.

Testing & CI

Test Suite

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

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) → claim registry verification
• Windows: PowerShell AST parsing → dry-run install with rule count assertion

Documentation Gating

Every feature claim in this README is tracked in docs/project/CLAIM_REGISTRY.json. A claim can only appear in README when:

1. Its behavioral test suite exists and passes
2. It has a Claim Registry entry with status unlocked
3. The CI gate (enzymes/verify_readme_claims.py) confirms no regressions

Features that are planned but not yet shipped are listed in ROADMAP.md.

Documentation

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

The Bash installer auto-migrates existing .prism/ directories to .soma/. soma init and the PowerShell installer do not perform this migration.

License

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