English · Features · Quick Start · The Problem · Architecture · API · Multi-Lang

---

The Problem

AI agents suffer from Context Drift, Illusion of Completion, and Quality Degradation:

❌ Mark tasks DONE but leave empty pass statements
❌ Skip critical error handling
❌ Generate unstyled "developer art" UIs  
❌ Write superficial tests with no real assertions
❌ No accountability — human must review everything manually

The Solution

Verdict is a programmatic gatekeeper that sits between the AI agent and your codebase. Every task must pass all three gates before being marked complete:

Agent Writes Code → AST Audit → UI Validation → 95% Coverage + 80% Mutation → ✅ COMPLETED

---

Features

🔬 AST Audit Detects `pass`, `# TODO`, missing try-except, missing docstrings	🎨 UI Dictatorship Enforces glassmorphism, neon accents, custom stylesheets — rejects defaults	🧪 Mutation Testing 80%+ mutation score required — tests must catch injected bugs	📊 95% Coverage Strict line coverage gate — no untested code allowed
🌐 Multi-Language JS, TS, Go, Rust, Java, Kotlin, React — not just Python	🔄 REST API Any agent can call Verdict via HTTP — no MCP required	🐳 Docker Ready One command: docker-compose up	⚡ VS Code Ext Ctrl+Shift+V to audit right from your editor
🔗 GitHub Actions Zero-config CI/CD — runs on every push and PR	📸 Git Snapshots Auto-rollback on test failure — never lose working code	🧩 Dependency DAG Tasks can't start until dependencies are complete	📜 Plan Integrity SHA-256 hash chain prevents plan tampering

---

Quick Start

1. Install

pip install verdict-mcp
# OR from source:
git clone https://github.com/Zubair-z/VERDICT-MCP.git
cd VERDICT-MCP
pip install -r requirements.txt

2. Scaffold a project

verdict init myproject
cd myproject

This creates: plan.md + auth_handler.py + db_handler.py + tests/test_auth_handler.py

3. Run as MCP Server (for AI agents)

python -m verdict_mcp

4. Run as REST API (for any HTTP client)

python -m verdict_mcp.api_server
# → http://localhost:8000
curl http://localhost:8000/health

5. Run full validation pipeline

curl -X POST http://localhost:8000/pipeline/run \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "TASK_001",
    "source_files": ["auth_handler.py"],
    "test_file": "tests/test_auth_handler.py",
    "target_file": "auth_handler.py",
    "ui_file": "main_window.py"
  }'

---

Architecture

graph LR
    A[AI Agent] -->|MCP / HTTP| B{Verdict}
    B --> C[AST Auditor]
    B --> D[UI Enforcer]
    B --> E[Test Runner]
    C --> F[pass/TODO/err/docstring checks]
    D --> G[glassmorphism/neon/layout]
    E --> H[pytest + coverage + mutation]
    F & G & H --> I{TASK COMPLETED?}
    I -->|Yes| J[Git Snapshot]
    I -->|No| A

---

API Endpoints

Method	Path	Description
GET	/health	Server health
POST	/plan/init	Initialize plan
GET	/plan/summary	Get task states
GET	/plan/task/{id}	Task details
POST	/audit	AST audit files
GET	/ui/style-guide	Design tokens
POST	/ui/validate	Validate UI
POST	/tests/run	Coverage + mutation
GET	/coverage	Coverage report
POST	/pipeline/run	Full lifecycle

---

Multi-Language Support

Language	Extensions	Checks Applied
Python	.py	Full AST audit (pass, TODO, try-except, docstrings)
JavaScript	.js	TODO, empty functions, missing try-catch
TypeScript	.ts	TODO, empty functions, missing try-catch
React	.jsx, .tsx	TODO, empty components, missing error handling
Go	.go	TODO, empty funcs, missing error handling
Rust	.rs	TODO, empty fn, missing error handling
Java	.java	TODO, empty methods, missing try-catch
Kotlin	.kt	TODO, empty fun, missing error handling

---

CLI Commands

# Scaffold a new project
verdict init myproject

# Run Verdict checks on current project
verdict verify

# Start MCP server
python -m verdict_mcp

# Start REST API
python -m verdict_mcp.api_server

# Run tests locally
python -m pytest tests/ -v --cov=verdict_mcp --cov-report=term-missing

---

Docker

# Start REST API
docker-compose up verdict-mcp

# Start MCP stdio mode
docker-compose up verdict-mcp-stdio

---

VS Code Extension

1. Copy .vscode-extension/ folder to ~/.vscode/extensions/verdict-mcp/
2. Restart VS Code
3. Open a Python file → press Ctrl+Shift+V
4. Or enable auto-audit on save in settings

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

🐛 Report Bug · ✨ Request Feature · 🧑‍💻 Contribute

---