Skip to content

About

Zero-Dependency Spec-Driven Development (SDD) Harness, Static AST Drift Detector & MCP Guardrail for Autonomous AI Coding Agents

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

5 Commits

Folders and files

Repository files navigation


CI Tests Python Dependencies MCP Native License: MIT Benni OS


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.


Conductor SDD Static AST Drift Engine Demo

⚑ Why conductor-sdd?

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:

  1. Silent Public API & Signature Breakage: Unguarded edits drop required parameters, rename public methods, or leave half-written syntax errors behind.
  2. Test Tampering ("Fake Green CI"): When a refactor breaks existing tests, agents frequently delete assert or pytest.raises statements instead of fixing the underlying bug.
  3. Out-of-Scope File Mutations & Forbidden Dependencies: Without cryptographic scope boundaries, agents touch protected config/auth files or pull in banned/unpinned packages.
  4. 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.


πŸ† Architectural Benchmark: Top 5 Global Incumbents vs conductor-sdd

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 ⚠️ Repo map only ❌ Runtime schemas βœ… Pure AST SDD-001..009
Verification LLM Cost ⚠️ Prompt-driven ⚠️ Prompt-driven ⚠️ Agent-driven ⚠️ Agent-driven ⚠️ Eval-driven βœ… $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 ⚠️ Checkpoints in IDE ⚠️ Git auto-commit ❌ No βœ… Sub-5ms Local Snapshot
Native MCP Guardrail ❌ Slash commands ❌ Slash commands ⚠️ MCP Client ❌ No ⚠️ Tool wrappers βœ… Built-in JSON-RPC 2.0 stdio

πŸ—οΈ Architecture

  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.


πŸš€ 60-Second Quickstart

1. Install

git clone https://github.com/Benni-OS/conductor-sdd.git
cd conductor-sdd
pip install -e .

2. Lock Baseline & Verify After Every Agent Turn

# 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 --strict

When 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 rollback

Key CLI Commands

conductor 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

πŸ›‘οΈ Deterministic Anti-Drift Rules (SDD-001 .. SDD-009)

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) βœ”

πŸ“Š Reproducible Drift Benchmark

Verify detection recall and scan latency across 6 real-world AI coding failure modes locally:

conductor bench

Measured 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

πŸ”Œ Native MCP Integration (Claude Code / Cursor / Antigravity)

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 β€” Validate conductor.spec.yaml schema invariants
  • conductor_lock_baseline β€” Generate/refresh .conductor/lock.json AST + SHA-256 lock
  • conductor_verify_drift β€” Run SDD-001..009 deterministic drift verification
  • conductor_create_checkpoint β€” Snapshot pre-edit state atomically
  • conductor_rollback β€” Revert drifted changes cleanly

πŸ“ Project Structure

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

🌐 The Benni OS Open-Source Ecosystem

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 GitHub Stars
benni-inference-engine High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs GitHub Stars
agent-eval-harness Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness GitHub Stars
agent-code-sandbox Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents GitHub Stars
agent-deep-research Autonomous Multi-Source Deep Research & Evidence Synthesis Engine GitHub Stars
agent-browser-mesh Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler GitHub Stars
agent-intent-compiler Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents GitHub Stars
agent-token-optimizer Sub-Millisecond Context Compression & Semantic Deduplication Engine GitHub Stars
bio-sync-operator-os Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface GitHub Stars
agent-cyber-sentinel Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction GitHub Stars
agent-run-ledger Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine GitHub Stars
reality-lock Cryptographic State Verification & Invariant Proof Engine for Agents GitHub Stars
agent-memory-mesh Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine GitHub Stars
benni-operator-gateway Human-in-the-Loop Approval & Policy Enforcement Gateway GitHub Stars
mcp-forge Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling GitHub Stars
benni-nexus Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub GitHub Stars
community-autopilot Autonomous GitHub Community Triaging & PR Feedback Agent GitHub Stars

πŸ›οΈ Commercial & Sovereign Architecture

Need autonomous multi-agent swarm orchestration, Spec-Driven Governance at enterprise scale, or deep technical blueprints?


πŸ“„ License & Provenance

  • 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

About

Zero-Dependency Spec-Driven Development (SDD) Harness, Static AST Drift Detector & MCP Guardrail for Autonomous AI Coding Agents

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages