Skip to main content
Glama

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.


⚡ 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.


Related MCP server: AI Knowledge Center MCP

🏆 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

Available Tools

5 tools
conductor_create_checkpointA

Create an atomic SHA-256 verified workspace snapshot before risky edits.

Inputs: root, label.

conductor_lock_baselineC

Compute SHA-256 and AST symbol baseline hashes into .conductor/lock.json.

Inputs: root.

conductor_rollbackC

Verify stored SHA-256 hashes and roll back workspace to a clean checkpoint.

Inputs: root, dry_run, checkpoint_id.

conductor_validate_specB

Validate conductor.spec.yaml schema and invariants before AI coding execution.

Inputs: root, spec_path.

conductor_verify_driftC

Run static AST drift detection against spec invariants and baseline lock.

Inputs: root, strict.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a clearly distinct phase of the spec-driven development lifecycle: validate, lock, drift verification, checkpoint creation, and rollback. Actions are semantically different (schema validation vs. hashing vs. comparison vs. snapshotting vs. restoration), so misselection is unlikely.

    Naming Consistency5/5

    All tool names share the conductor_ prefix followed by a predictable verb_noun pattern (validate_spec, lock_baseline, verify_drift, create_checkpoint, rollback). The lone nounless 'rollback' is a minor deviation but remains clear and consistent with the set.

    Tool Count5/5

    Five tools is a tight, well-scoped set that maps directly to the workflow: validate → lock → verify → checkpoint → rollback. No redundant or filler tools; each earns its place.

    Completeness4/5

    The surface covers the core safety loop for spec-driven coding, including validation, baseline locking, drift detection, and rollback. Minor gaps exist, such as listing/inspecting existing checkpoints or modifying the spec itself, which agents would have to work around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local MCP server for AI agents and vibe coding safety: deterministic risk checks (payments, auth, database, secrets, infrastructure), sessions, checkpoints, policy inspection, and fix prompts. Runs over stdio against a local git repository; no language model judges risk.
      8
      Apache 2.0
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables agents and MCP-compliant clients to run multi-language code in a deterministic, zero-dependency sandbox where AST security analysis blocks dangerous syscalls and isolated execution telemetry is captured. It exposes this through JSON-RPC 2.0 stdio, letting frameworks like LangGraph, CrewAI, Cursor, and Claude Desktop validate and execute agent-generated code safely.
      -