Soma
Production-grade governance framework making AI coding agents trustworthy through observable, self-evolving constraints.
Soma replaces static, unverified prompt rules (.cursorrules, CLAUDE.md) with a closed-loop governance engine: JIT context injection, deterministic AST verification, and Wilson-bounded rule evolution. Rules prove their value or decay to zero.
flowchart LR
A["Agent Action"] --> B["1. JIT Rule Injection<br/><i>Relevant constraints & traps</i>"]
B --> C["Code Generation"]
C --> D["2. Two-Layer Verification<br/><i>Deterministic AST + Adversarial Arbiter</i>"]
D --> E["3. Ambient Telemetry<br/><i>Trigger & outcome signals</i>"]
E --> F["Self-Evolving Lifecycle<br/><i>Rules promote or decay</i>"]
F -.-> B
📖 Documentation Portal & Guides
Explore deep-dive guides for production architecture, workflows, and specifications:
| Guide | Description | Key Focus |
|---|---|---|
| MCP Gateway | Dual-Plane Gateway Architecture | Control vs Execution Plane, receipt security, opt-in projection |
| Verification Pipeline | Two-Layer Verification Engine | Layer 1 AST checks, Layer 2 Adversarial Rebuttal, Gate 4.5 |
| Cell Lifecycle | Evolutionary Rule Management | 5 cell types, Wilson scoring, promotion/demotion, zero-touch decay |
| Skill Graph | Horizontal Agent Collaboration | 15 organs, typed envelopes (<150 tokens), file-buffered handoffs |
| Compatibility | SemVer 2.0 Guarantee | Formal backwards compatibility contracts starting at v1.0.0 |
| Security Policy | Vulnerability Reporting & Scopes | Security tiering, isolation, and responsible disclosure |
Quick Start
pip install soma-governance # Pure Python (3.9+), zero runtime dependencies
soma init --yes # Auto-detects Gemini, Claude Code, Cursor, Copilot
soma status # View active rules and fitness stats
soma verify --layer1-only # Run Layer 1 deterministic AST checks
MCP Server (Recommended)
Add Soma to your agent's configuration (SOMA_WORKSPACE points to your project):
{
"mcpServers": {
"soma": {
"command": "python3",
"args": ["-m", "soma_mcp"],
"env": {
"SOMA_WORKSPACE": "/path/to/project",
"SOMA_EXECUTION_ENABLED": "1"
}
}
}
}
| Tier | Available tools |
|---|---|
| Read (default) | soma_request_receipt, soma_scan, soma_list_cells, soma_grade, soma_coverage, soma_fitness, soma_audit_security, soma_audit_performance, soma_poll_verification, soma_list_rules, soma_rule_fitness |
| Write (default; receipt required) | soma_report_outcome, soma_capture_insight, soma_create_cell, soma_create_rule, soma_handoff |
| Execute (opt-in; receipt required) | soma_propose_change, soma_verify_changes, soma_checkpoint, soma_generate_manifest |
Receipt flow: Call soma_request_receipt with the operation and arguments to obtain a single-use, state-bound token (300s TTL). See MCP Gateway Guide.
SDK
from soma_sdk import Governance
gov = Governance(project_root='.')
print(gov.grade(), gov.fitness_landscape(bayesian=True))
📐 Core Rules
The system's foundational rules — 19 inherited behavioral defaults:
| Rule | Trigger | Purpose |
|---|---|---|
| providence | always_on | Codebase grounding, no hallucinations, diagnose-before-repair |
| cost-optimization | always_on | Token efficiency, diffs-only edits, FPSR metric (>80%) |
| subagent-delegation | always_on | Context protection, concurrency limits, delegation floor |
| architectural-tenets | model_decision | Pragmatism, trade-off analysis, scale-to-zero |
| atomic-workstream-protocol | model_decision | Atomic 2-5 file micro-step decomposition and verification gates |
| polyglot-standards | model_decision | Unified entrypoints (Makefiles), containerization |
| feature-specs | model_decision | PRD structure, acceptance criteria, documentation |
| testing | model_decision | Behavioral testing, sad paths, ast.parse ban |
| documentation | model_decision | ADRs, actionable READMEs, Mermaid diagrams |
| destructive-ops | model_decision | Dry-run mandates for IaC, database mutations, bulk git |
| git-workflow | model_decision | Conventional commits, .gitignore verification |
| desktop-automation | model_decision | PyAutoGUI/xdotool safety, focus verification |
| core-change-protocol | model_decision | Approval gates for genome/enzyme modifications |
| tdd-protocol | model_decision | Test-driven development with sequential phase gates |
| optional-import-guard | model_decision | try/except guards on optional dependencies |
| hgt-resource-consolidation | model_decision | Cross-project rule sharing governance |
| ci-green-before-release | model_decision | Requires green CI before release or deployment |
| gitflow-review-gate | model_decision | Enforces reviewed Gitflow branch transitions |
| no-pre-existing-excuse | model_decision | Requires fixing relevant pre-existing failures instead of dismissing them |
🔧 Agent Skills
15 specialized skills coordinate complex behaviors via typed envelopes and file-buffered handoffs. See the Skill Graph Guide for schemas and coordination workflows.
| Skills | Description |
|---|---|
adaptive-reviewer, staff-review, spec-synthesizer |
Multi-lens adversarial review and actionable plan synthesis |
security-audit, performance-audit, governance-auditor |
Specialized audits for AppSec (OWASP), latency/GC, and invariant compliance |
genesis, incident-debug, post-mortem |
Codebase reconnaissance, systematic incident debugging, blameless post-mortems |
refactoring-pilot, readme-writer, visual-analyst |
Mikado Method refactoring, documentation generation, UI/screen analysis |
session-monitor, session-preflight, domain-researcher |
Real-time waste tracking, environment pre-flight probes, external research |
📋 Adaptive Rules & Verification
Adaptive rules live in .soma/cells/ (wall, membrane, vacuole, chloroplast, plasmodesma). Rules evolve using Wilson-bounded fitness intervals and decay to zero when unreinforced. See the Cell Lifecycle Guide.
All changes are gated by soma verify:
- Layer 1: Deterministic AST analysis (call graph reachability, mutation testing, import guards, branch coverage).
- Layer 2: Adversarial Rebuttal Protocol with Spec Agent prosecution, Code Agent defense, and binding Arbiter verdict (
SHIP/REVISE/BLOCK). See the Verification Pipeline Guide.
⚙️ Core Architecture
- Zero Runtime Dependencies: Pure Python standard library (
dependencies = []). - Scale-to-Zero: Zero daemons, zero background threads, zero persistent idle consumption.
- Local Privacy: Telemetry and evidence remain strictly local in
.soma/evidence/. - Complete script, tool, and module reference catalog is available in SCRIPTS.md.
License & Privacy
Apache 2.0 — Copyright 2026 Nicholas Seney. See NOTICE, PRIVACY.md, and SECURITY.md.
1 maintainer
Metadata
1 maintainer
Release files for soma-governance 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| soma_governance-1.2.0.tar.gz | 419.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| soma_governance-1.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 860.8 kB
Release files / soma_governance-1.2.0.tar.gz
| Download URL | soma_governance-1.2.0.tar.gz |
|---|---|
| Size | 419.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6abb36a3b504b79cffa27c16d1de9c4be977e68d39548d2c25acabcb3482c0f7
|
|
BLAKE2b-256 checksum How to use checksums |
4c354dd2b5c1cceddc72bd4f356d87d7285442af9c1f3d885f545b0054725300
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / soma_governance-1.2.0-py3-none-any.whl
| Download URL | soma_governance-1.2.0-py3-none-any.whl |
|---|---|
| Size | 441.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8aa4ffcf38ba9d9842c8a1118fe4f35631a3423602df2cd3399aca89a57e25bd
|
|
BLAKE2b-256 checksum How to use checksums |
dc899fdea876142c07b5b7b08c9d459da297dc0ca2a2ce91f4c1b40873ab8604
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency log
