Metadata-Version: 2.4
Name: sdd-plus
Version: 0.3.0
Summary: Specification-Driven Development Extended - LLM-agnostic spec-first governance framework with role enforcement, telemetry, and GitHub integration
Project-URL: Homepage, https://github.com/oskcorps-sys/sdd-plus
Project-URL: Repository, https://github.com/oskcorps-sys/sdd-plus
Project-URL: Issues, https://github.com/oskcorps-sys/sdd-plus/issues
Project-URL: Changelog, https://github.com/oskcorps-sys/sdd-plus/blob/master/CHANGELOG.md
Author-email: Oscar Franco <oscar@regusense.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,development-framework,github,llm-agnostic,orchestration,sdd,spec-driven
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic-yaml>=0.11.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pip-audit>=2.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-watch>=4.2.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: radon>=6.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# SDD+ - Specification-Driven Development Extended

[![Python 3.13+](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-261%20passing-brightgreen.svg)](https://github.com/oskcorps-sys/sdd-plus/actions)
[![Coverage](https://img.shields.io/badge/Coverage-91%25-brightgreen.svg)](#test-coverage)
[![Code Quality](https://img.shields.io/badge/Complexity-A%2FB-brightgreen.svg)](#code-quality)

LLM-agnostic spec-first governance framework for AI-assisted development, with independent audit gates, role-based file enforcement, telemetry, and a web dashboard.

**Core principle**: Specifications are binding. Code follows spec, not vice versa. Audit is independent and impartial.

**LLM-agnostic**: SDD+ doesn't care what AI (or human) executes each role. Use Claude, GPT-4, Gemini, Llama, Ollama, or manual review. Bring your own executor.

---

## Install

```bash
pip install sdd-plus
```

Requires Python 3.13+.

## Quick Start

```bash
# Initialize a new SDD+ project
sdd init

# Check current phase and state
sdd status

# Transition state (as auditor or implementer, with any executor)
sdd transition REFINED --role auditor --executor claude
sdd transition IMPLEMENTING --role implementer --executor gpt-4

# Run the 4-step audit loop (executor is whoever runs the audit)
sdd audit --role auditor --executor claude --auto-approve

# Advance to next phase (auditor only, after COMPLETED)
sdd new-phase --role auditor

# Install the pre-commit enforcement hook
sdd install-hooks --role implementer

# Check file patterns against role rules (dry-run)
sdd check-patterns --role implementer --files src/foo.py

# View telemetry
sdd metrics show --phase 4

# Launch the web dashboard
sdd dashboard --port 8888
```

---

## What It Does

SDD+ enforces a spec-first workflow with pluggable executors:

1. **State Machine** - 6-state lifecycle: DRAFT -> REFINED -> LOCKED -> IMPLEMENTING -> AUDITING -> COMPLETED
2. **Role Enforcement** - `AGENTS.yaml` declares which files each role (implementer/auditor) may touch. A git pre-commit hook enforces it.
3. **Audit Loop** - 4-step automated audit: pytest, coverage >= 85%, spec conformance, contract conformance.
4. **Telemetry** - Every transition and audit is logged to `.sdd-metrics/` as JSONL.
5. **Dashboard** - `sdd dashboard` serves a read-only web UI showing project state, audit history, and metrics.

---

## Architecture

```
project/
  AGENTS.yaml                  # Authority matrix (role -> file patterns)
  sdd/
    artifacts/                 # Specs, contracts, audits, state snapshot
      STATE_SNAPSHOT.yaml
      PHASE_N_SPEC.yaml
      PHASE_N_CONTRACT.yaml
      PHASE_N_AUDIT.yaml
    handoffs/                  # Phase transition summaries
    state_machine/             # 6-state machine + transitions
    schemas/                   # Pydantic v2 models
    validators/                # Contract + state validators
    enforcement.py             # File-pattern denylist enforcement
    git_integration.py         # Git helpers (branch, commit, clean check)
    telemetry.py               # JSONL event emitter + query
    web/                       # FastAPI + Jinja2 dashboard
    cli/                       # Typer CLI commands
  tests/                       # 244+ tests, >= 85% coverage
  .sdd-metrics/                # Telemetry JSONL (gitignored)
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `sdd init` | Initialize SDD+ in a directory |
| `sdd status` | Show current phase and state |
| `sdd validate` | Validate contract and state artifacts |
| `sdd transition STATE --role ROLE [--executor E]` | Advance the state machine |
| `sdd new-phase --role auditor` | Start next phase after COMPLETED |
| `sdd audit --role auditor [--executor E]` | Run 4-step audit loop |
| `sdd install-hooks --role ROLE` | Install git pre-commit hook |
| `sdd check-patterns --role ROLE` | Dry-run file enforcement check |
| `sdd metrics show` | Display telemetry records |
| `sdd dashboard` | Launch web dashboard |
| `sdd projects list/add/remove` | Manage workspace projects |

---

## Phases Completed

| Phase | Title | Tests | Coverage |
|-------|-------|-------|----------|
| 0-2 | Schemas + State Machine + CLI | 64 | 85%+ |
| 3 | Agent Harness (AGENTS.yaml, audit loop) | 118 | 92% |
| 4 | Harness Closure (enforcement + git hooks) | 190 | 92.1% |
| 5 | Telemetry & Metrics | 225 | 91.7% |
| 6 | Web Dashboard | 244 | 91.6% |
| 7 | PyPI Packaging | 244+ | 91%+ |

---

## Development

```bash
# Clone and install in dev mode
git clone https://github.com/oscarfrancodev/sdd-plus.git
cd sdd-plus
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=sdd --cov-report=html
```

---

## License

MIT - see [LICENSE](LICENSE).

---

**Built by Oscar Franco (ReguSense). LLM-agnostic by design.**
