Historical snapshot: this README preserves a prior approved state for orientation only. Live debt, active work, and current execution order live in
tasks/backlog/andHANDOFF.md.
Cerberus is a defensive code-quality and security firewall — it does not orchestrate agents (which is what LangGraph or CrewAI do), but rather validates, secures, and protects the code that humans and AI agents generate.
It acts as an automated, zero-trust gatekeeper that audits every single change before it is committed. Think of it as a relentless reviewer that:
- ✅ Validates that code works — catching silent runtime failures and dead code.
- ✅ Guarantees documentation and clarity — enforcing strict explanations for every change.
- ✅ Prevents bad coding habits — blocking patterns that lead to technical debt.
- ✅ Keeps projects synchronized — automatically propagating protocol updates across all satellite projects.
- ✅ Monitors tokenomics — tracking AI usage and execution costs locally.
Every time a change is saved or committed, Cerberus executes a 17-dimension runtime model: 15 repository gate domains and 2 runtime hook domains. The historical Dxx ids remain as runtime aliases, while the semantic truth is normalized through canonical domains with 1:1 coverage against GS.
| Runtime ID | Public Domain | Channel | Canonical Domain | Canonical Title | What it enforces |
|---|---|---|---|---|---|
D1 |
Integrity | gate |
CD01 |
Repository Integrity & Surface Hygiene | No ghost files, undeclared active artifacts, or dirty active surface. |
D2 |
Completeness | gate |
CD02 |
Completeness & State Continuity | No incomplete operational contract, unresolved TODO debt, or broken continuity checkpoints. |
D3 |
Dead Code | gate |
CD04 |
Code Vitality & Dead Surface | No inert executable paths, dead definitions, or unused imports. |
D4 |
Anti-Spaghetti | gate |
CD05 |
Structural Simplicity & Blast Radius | Complexity ceilings, fan-in control, and anti-spaghetti structure. |
D5 |
Angry Path | gate |
CD06 |
Failure Handling & Recovery Paths | Visible recovery paths, propagated failures, and actionable error handling. |
D6 |
Anti-Slop | gate |
CD07 |
Boundary Hygiene & Anti-Theater | Boundary hygiene, anti-slop enforcement, and justified exclusions. |
D7 |
Data Security | gate |
CD08 |
Runtime & Data Security | Secrets, dangerous operations, and runtime-risky code paths. |
D8 |
Adversarial Coverage | gate |
CD09 |
Coverage Adequacy | Active logic must have discriminative coverage and negative-path pressure. |
D9 |
Test Purity | gate |
CD10 |
Test Falsifiability & Assertion Quality | No fake tests, dishonest assertions, or theater that passes for the wrong reasons. |
D10 |
Tokenomics | gate |
CD11 |
Context Efficiency & Tokenomics | Context hygiene, compression discipline, and local token metering. |
D11 |
Dependency Security | gate |
CD12 |
Dependency & Supply-Chain Posture | CVEs, yanked packages, stale dependencies, and supply-chain posture. |
D12 |
Drift Protection | gate |
CD14 |
Federation Drift & Version Parity | Core-to-satellite sync, version adoption, and federation parity. |
D13 |
Observability & Evidence Telemetry | hook |
CD15 |
Observability & Evidence Telemetry | Runtime signals, decision logs, token traces, and post-run evidence telemetry. |
D14 |
Discourse Rigor | hook |
CD16 |
Discourse Rigor & Evidence Quality | Clarity, ambiguity control, and evidence-backed agent discourse. |
D15 |
Agent Security | gate |
CD17 |
Agent Boundary Security | Prompt-injection, prompt leakage, jailbreaks, and agent trust-boundary defense. |
D16 |
Legibility & Causal Explainability | gate |
CD03 |
Legibility & Causal Explainability | Module docstrings, documentation density, and inspectable causal readability. |
D17 |
Knowledge Canonicalization & Ingestion | gate |
CD13 |
Knowledge Canonicalization & Ingestion | Canonical GS ingestion, principle integrity, and normalized satellite learnings. |
Dcomp |
Structural Simplicity & Complexity | gate |
CD05 |
Structural Simplicity & Blast Radius | Unused imports and hand-rolled standard library patterns. |
Validation debt remains a cross-domain metadata axis, not the semantic identity of a runtime domain. Cerberus still tracks it through offline/reporting tooling such as scripts/satellite_validation_debt.py, scripts/postmortem_validation_analysis.py, and scripts/audit_d13_validation_debt.py.
| System | Role | Integration with Cerberus |
|---|---|---|
| LangGraph | Orchestrates agent flows. | Cerberus validates the source code that LangGraph outputs. |
| CrewAI | Coordinates agent teams. | Cerberus audits the decisions and files created by the team. |
| MCP | Protocol standard for tools. | Cerberus protects MCP connections against silent failures and drift. |
| Your Workspace | The active repository you edit. | Cerberus hooks automatically run on every save/commit. |
Cerberus does not compete with orchestration systems; it protects them. While they build and automate, Cerberus is the immune system preventing failures from ever reaching production.
python scripts/Full_dimensions_audit.py .This runs the full suite of verifications and outputs:
- ✅ APPROVED — everything complies, you are safe to commit.
- ❌ REJECTED — violations detected; shows exactly what and where to fix.
python scripts/protocol_cli propagate --applyEnsures all active satellite projects adopt the same versioned standards as the core.
python scripts/protocol_cli check --incremental --preset coreAudits only the staged files and runs only the tests affected by local changes in under 3 seconds.
python scripts/protocol_cli distribution --output dist/Cerberus_Distribution --force --zipBuilds a portable snapshot with launchers, live metadata, and a manifest that can be copied or zipped for real deployment.
python scripts/protocol_cli.py dashboard --port 5055Opens the local control plane for registry state, backlog, evidence, graph summaries, and the curated command dock.
- Snapshot version: v0.6.
- Snapshot verdict: APPROVED at the time this snapshot was recorded.
- Fast lane:
scripts/run_compliance_tests.py --preset fastwas validated end-to-end and skipped the heavy Full dimensions and permission-audit steps. - Ecosystem note: the external project registry is retained as historical metadata; active supervision is handled through live backlog and handoff notes.
- Debt note: this document is not the live debt ledger; consult
tasks/backlog/for current work. - Cleanup note:
deprecated/was reduced to archive material and minimal metadata.
- PLAN.md — Completed and upcoming sprints.
- STATE.md — Living roadmap, latest changes, and next session details.
- AUDIT_TRAIL.md — Append-only chronological session retrospective.
- docs/architecture/LOCAL_LLM_WORKSTATION_BOOTSTRAP.md — Canonical prep for the new local LLM workstation and its validation boundary.
- scripts/local_llm_workstation_check.py — Executable verifier for the future Ollama/Open WebUI bootstrap.
- VibeCoding_GoldenStandard — Canonical rules catalog (independent repository).
- Clone this repository and navigate to the root directory.
- Install requirements:
pip install -r requirements.txt
- Execute the initial audit:
python scripts/Full_dimensions_audit.py . - Git Hooks: Once installed, pre-commit and pre-push hooks will validate your work automatically.
Does Cerberus block my workflow? No. It only blocks code that is guaranteed to cause failures later (incomplete logic, raw swallow exceptions, unverified imports). It is an immune system, not a bottleneck.
Can I bypass a validation?
Exceptions can be documented as justified exemptions in docs/rules.md, subject to Full dimensions review.
Last Update: June 2026 Maintainer: Luis Casarin Repository: lcasarin-maker/Coder_Cerberus