Zero-Dependency Spec-Driven Development (SDD) Harness, Static AST Drift Detector & MCP Guardrail for Autonomous AI Coding Agents.
Locks public signatures, enforces task scope, catches silently deleted test assertions, and rolls back broken agent mutations in milliseconds β with zero external dependencies and zero LLM token burn.
AI coding agents (Claude Code, Cursor, Codex CLI, Aider, Cline) ship turn-1 prototypes fast β and silently decay into multi-turn context drift by turn 5:
- Silent Public API & Signature Breakage: Unguarded edits drop required parameters, rename public methods, or leave half-written syntax errors behind.
- Test Tampering ("Fake Green CI"): When a refactor breaks existing tests, agents frequently delete
assertorpytest.raisesstatements instead of fixing the underlying bug. - Out-of-Scope File Mutations & Forbidden Dependencies: Without cryptographic scope boundaries, agents touch protected config/auth files or pull in banned/unpinned packages.
- LLM-as-a-Judge Spec Checkers Burn Tokens & Hallucinate: Asking another LLM whether code still matches a markdown spec is slow, expensive, and non-deterministic.
conductor-sdd replaces probabilistic guesswork with pure Python static AST verification, SHA-256 baseline locking, and atomic workspace rollback.
We compared conductor-sdd against the 5 largest global open-source Spec-Driven Development and coding-agent frameworks representing over 367,000 GitHub stars:
| Feature / Metric | github/spec-kit (149.6k β) |
Fission-AI/OpenSpec (74.7k β) |
cline/cline (71.6k β) |
Aider-AI/aider (50.1k β) |
pydantic/pydantic-ai (21.2k β) |
conductor-sdd (Benni OS) |
|---|---|---|---|---|---|---|
| Static AST Drift Engine | β Markdown templates | β Markdown diffs | β No | β Runtime schemas | β
Pure AST SDD-001..009 |
|
| Verification LLM Cost | β $0.00 (Zero LLM Tokens) | |||||
| Deleted Assertion Guard | β No | β No | β No | β No | β No | β
Deterministic SDD-006 |
| Runtime Dependencies | CLI + Agent Templates | Node.js / npm | VS Code Extension | Heavy Python Stack | Pydantic + Providers | β Zero (Pure Python Stdlib) |
| Atomic SHA-256 Rollback | β Git manual | β Git manual | β No | β Sub-5ms Local Snapshot | ||
| Native MCP Guardrail | β Slash commands | β Slash commands | β No | β Built-in JSON-RPC 2.0 stdio |
Developer / Coding Agents (Claude Code / Cursor / Codex CLI / Antigravity)
β
ββββΊ 1. conductor init βββΊ Declares scope & invariants (conductor.spec.yaml)
ββββΊ 2. conductor lock βββΊ Freezes AST signatures & SHA-256 baseline (.conductor/lock.json)
ββββΊ 3. conductor checkpoint βββΊ Captures immutable pre-edit restore point
β
βΌ (Agent performs multi-turn code mutations)
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CONDUCTOR AST DRIFT ENGINE (SDD-001..009) β
β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββ β
β β Integrity Guards β β AST Signatures β β Quality & Docs β β
β β β’ SDD-001 Syntax βββΊβ β’ SDD-003 Symbols βββΊβ β’ SDD-007 McCabeβ β
β β β’ SDD-002 Protect β β β’ SDD-005 Imports β β β’ SDD-008 Lines β β
β β β’ SDD-004 Scope β β β’ SDD-006 Asserts β β β’ SDD-009 Docs β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββ β
β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββ β
β β Atomic Checkpoint β β Serve & MCP β β Tools & Matrix β β
β β β’ SHA-256 Lock β β β’ JSON-RPC 2.0 β β β’ SDD Doctor β β
β β β’ Sub-5ms Restore β β β’ Telemetry P99 β β β’ 6-Mode Bench β β
β βββββββββββββββββββββ βββββββββββββββββββββ βββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
βββ PASS (0.00% Drift) βββΊ Safe to commit / promote / pass Git hook
βββ DRIFT DETECTED βββΊ Exit code 2 + `conductor rollback`
See docs/ARCHITECTURE.md for the full layer specification.
git clone https://github.com/Benni-OS/conductor-sdd.git
cd conductor-sdd
pip install -e .# Scaffold `conductor.spec.yaml` and `AGENTS.md` inside any Python repository
conductor init --project my-service --allowed src tests --with-agent-rules
# Cryptographically lock all AST symbol signatures and SHA-256 file hashes
conductor lock
# Save an atomic pre-edit rollback checkpoint
conductor checkpoint --label "pre-agent-sprint"
# Verify zero architectural or test-assertion drift
conductor verify --strictWhen an agent silently mutates a locked signature or deletes assertions:
Conductor SDD Verification: DRIFT DETECTED (37.50%)
Files scanned: 8 | Baseline locked: 8 | Elapsed: 4.12ms
[CRITICAL] SDD-003 (src/auth.py::verify_token): Protected symbol signature mutated from `(token: str, secret: str) -> bool` to `(token: str) -> bool`.
-> Fix: Preserve the locked public signature to avoid downstream breakage.
Restore cleanly in one command:
conductor rollbackconductor init --with-agent-rules # Generate conductor.spec.yaml + AGENTS.md rules
conductor lock # Freeze AST signatures & SHA-256 baseline lock
conductor verify --strict --json # Audit AST & scope drift (exit code 2 on violation)
conductor checkpoint --label sprint1 # Create atomic SHA-256 pre-edit restore point
conductor rollback # Restore workspace cleanly from verified checkpoint
conductor bench --json # Run 6-scenario reproducible drift-recall benchmark
conductor doctor # Audit repository readiness for SDD governance
conductor install-hook # Install Git pre-commit anti-drift gate
conductor mcp # Launch native JSON-RPC 2.0 MCP stdio server| Rule ID | Severity | What It Catches | Zero LLM Tokens |
|---|---|---|---|
SDD-001 |
CRITICAL |
Broken Python syntax left behind mid-edit | β |
SDD-002 |
CRITICAL |
Unauthorized edits or deletion of scope.protected_files |
β |
SDD-003 |
CRITICAL |
Deletion, rename, or signature mutation of invariants.protected_symbols |
β |
SDD-004 |
ERROR |
Out-of-scope edits or file creation outside scope.allowed_paths |
β |
SDD-005 |
ERROR |
Injection of banned libraries in invariants.forbidden_imports |
β |
SDD-006 |
ERROR |
Silent deletion of assert / pytest.raises checks to fake green CI |
β |
SDD-007 |
WARNING/ERROR |
McCabe cyclomatic complexity exceeding max_cyclomatic_complexity |
β |
SDD-008 |
WARNING/ERROR |
Oversized modules exceeding max_file_lines |
β |
SDD-009 |
WARNING/ERROR |
Missing docstrings on public classes/functions (when enabled) | β |
Verify detection recall and scan latency across 6 real-world AI coding failure modes locally:
conductor benchMeasured output:
Conductor SDD β Reproducible Agent-Drift Benchmark
========================================================
Catch Recall : 100.0% (6/6 agent failure modes caught)
Avg Latency : ~12.24 ms per full 6-scenario verification pass
[CAUGHT] SCEN-01 | Expected SDD-003 | Got ['SDD-003', 'SDD-009'] β Silent public signature break
[CAUGHT] SCEN-02 | Expected SDD-006 | Got ['SDD-006'] β Silent deletion of unit test assertions
[CAUGHT] SCEN-03 | Expected SDD-005 | Got ['SDD-005'] β Injection of forbidden dependency
[CAUGHT] SCEN-04 | Expected SDD-002 | Got ['SDD-002'] β Unauthorized edit to protected file
[CAUGHT] SCEN-05 | Expected SDD-004 | Got ['SDD-004'] β Out-of-scope file creation
[CAUGHT] SCEN-06 | Expected SDD-001 | Got ['SDD-001'] β Broken syntax introduced mid-edit
Expose conductor-sdd directly as a native Model Context Protocol (MCP) server over stdio so coding agents self-verify before finishing any turn:
{
"mcpServers": {
"conductor-sdd": {
"command": "conductor-mcp",
"args": []
}
}
}Exposed MCP tools:
conductor_validate_specβ Validateconductor.spec.yamlschema invariantsconductor_lock_baselineβ Generate/refresh.conductor/lock.jsonAST + SHA-256 lockconductor_verify_driftβ RunSDD-001..009deterministic drift verificationconductor_create_checkpointβ Snapshot pre-edit state atomicallyconductor_rollbackβ Revert drifted changes cleanly
conductor-sdd/
βββ .github/workflows/ci.yml # Python 3.10 / 3.11 / 3.12 lint, pytest & bench gate
βββ assets/
β βββ demo.gif # Branded terminal animation
βββ conductor_sdd/
β βββ __init__.py # Backwards-compatible public library exports
β βββ cli.py # CLI commands (init, lock, verify, checkpoint, rollback, bench, doctor, mcp)
β βββ core/
β β βββ __init__.py # Core package exports
β β βββ ast_analyzer.py # Zero-dependency AST symbol, complexity & assertion extractor
β β βββ checkpoint.py # Atomic SHA-256 snapshot & rollback engine
β β βββ drift_engine.py # SDD-001..009 deterministic rule evaluator & drift scorer
β β βββ spec.py # Zero-dependency YAML subset parser & spec validator
β βββ serve/
β β βββ __init__.py # Serve package exports
β β βββ mcp_server.py # Native JSON-RPC 2.0 MCP stdio server
β β βββ telemetry.py # AST verify P50/P90/P99 latency & SDD rule hit telemetry
β β βββ health_monitor.py # Spec contract, lock manifest & AST self-test monitor
β βββ tools/
β βββ __init__.py # Tools package exports
β βββ doctor.py # Repository SDD readiness diagnostics & Git hook installer
β βββ benchmarks.py # 6-scenario reproducible agent-drift benchmark suite
β βββ bench_matrix.py # Multi-scale AST lock & verification benchmark matrix
βββ docs/
β βββ ARCHITECTURE.md # Layer-by-layer architectural specification
βββ examples/
β βββ mcp_client_config.json # Ready-to-use MCP client config
β βββ quickstart_guardrail.py # Programmatic Python guardrail example
β βββ checkpoint_rollback_demo.py # Atomic pre-edit checkpoint & rollback demo
βββ scripts/
β βββ benchmark_drift_matrix.py # 5β100 module AST lock & verification matrix runner
β βββ gate_sdd_strict.py # Strict SDD readiness & 100% recall release gate
βββ tests/
β βββ test_ast_analyzer.py # AST symbol, complexity & assertion tests
β βββ test_checkpoint_rollback.py # Atomic snapshot & rollback tests
β βββ test_cli_and_bench.py # CLI & 6-scenario drift benchmark tests
β βββ test_drift_engine.py # SDD-001..009 rule evaluation tests
β βββ test_mcp_server.py # JSON-RPC 2.0 MCP server tests
β βββ test_serve_and_tools.py # Telemetry, health monitor, doctor & bench matrix tests
β βββ test_spec.py # Spec parser & schema validation tests
βββ conductor.spec.yaml # Dogfooded self-verification spec contract
βββ pyproject.toml # Zero-dependency package & entrypoints
conductor-sdd is part of the coordinated Benni Master OS v9.4 open-source infrastructure suite:
| Repository | Focus & Architecture | Stars |
|---|---|---|
conductor-sdd |
Zero-Dependency Spec-Driven Development, Static AST Drift Detector & MCP Guardrail | |
benni-inference-engine |
High-Throughput Sovereign Local Inference for 8GBβ16GB Consumer GPUs | |
agent-eval-harness |
Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness | |
agent-code-sandbox |
Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents | |
agent-deep-research |
Autonomous Multi-Source Deep Research & Evidence Synthesis Engine | |
agent-browser-mesh |
Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler | |
agent-intent-compiler |
Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents | |
agent-token-optimizer |
Sub-Millisecond Context Compression & Semantic Deduplication Engine | |
bio-sync-operator-os |
Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface | |
agent-cyber-sentinel |
Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction | |
agent-run-ledger |
Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine | |
reality-lock |
Cryptographic State Verification & Invariant Proof Engine for Agents | |
agent-memory-mesh |
Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine | |
benni-operator-gateway |
Human-in-the-Loop Approval & Policy Enforcement Gateway | |
mcp-forge |
Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling | |
benni-nexus |
Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub | |
community-autopilot |
Autonomous GitHub Community Triaging & PR Feedback Agent |
Need autonomous multi-agent swarm orchestration, Spec-Driven Governance at enterprise scale, or deep technical blueprints?
- Official Website: https://benni-os.net
- Deep-Dive Architecture Article: Spec-Driven Development (SDD): Eliminating AI Code Drift and Multi-Turn Hallucinations with Formal Consensus
- Operator Mode Playbook: https://benni-os.net/blog/academy.html
- GitHub Organization: https://github.com/Benni-OS
- Maintainer: Benni Alencar
- License: MIT License
- Author: Benni Alencar (
bennialencar@benni-os.net) - Architecture: Benni Master OS v9.4 Tier-0 Governance Standard
conductor-sdd β Deterministic Spec-Driven Development & AST Anti-Drift Harness β’ benni-os.net β’ MIT License