# Verified Spec-Driven Development (VSDD)

## The Fusion: VDD x TDD x SDD for AI-Native Engineering

### Overview

VSDD is the unified software engineering methodology used for all forage development. It fuses three paradigms into a single AI-orchestrated pipeline:

- **Spec-Driven Development (SDD):** Define the contract before writing a single line of implementation. Specs are the source of truth.
- **Test-Driven Development (TDD):** Tests are written before code. Red -> Green -> Refactor. No code exists without a failing test that demanded it.
- **Verification-Driven Development (VDD):** Subject all surviving code to adversarial refinement until a hyper-critical reviewer is forced to hallucinate flaws.

### The Toolchain

| Role | Entity | Function |
|------|--------|----------|
| The Architect | Human Developer | Strategic vision, domain expertise, acceptance authority |
| The Builder | Claude | Spec authorship, test generation, code implementation, refactoring |
| The Adversary | External reviewer | Hyper-critical reviewer with zero patience |

### The Pipeline

#### Phase 1 - Spec Crystallization

Nothing gets built until the contract is airtight.

**Step 1a: Behavioral Specification**
- Behavioral Contract: preconditions, postconditions, invariants
- Interface Definition: input types, output types, error types
- Edge Case Catalog: exhaustive boundary conditions and failure modes
- Non-Functional Requirements: performance, memory, security

**Step 1b: Verification Architecture**
- Provable Properties Catalog: which invariants must be formally verified
- Purity Boundary Map: deterministic pure core vs effectful shell
- Property Specifications: formal property definitions where applicable

**Step 1c: Spec Review Gate**
- Reviewed by both human and adversary before any tests

#### Phase 2 - Test-First Implementation (The TDD Core)

Red -> Green -> Refactor, enforced by AI.

**Step 2a: Test Suite Generation**
- Unit tests per behavioral contract item
- Edge case tests from the catalog
- Integration tests for system context
- Property-based tests for invariants

**The Red Gate:** All tests must fail before implementation begins.
> **Enforcement note (from Review 002):** When writing tests alongside templates and routes,
> use stub handlers returning 501 to verify tests fail before implementing the real logic.
> This prevents false confidence from tests that were never red.

**Step 2b: Minimal Implementation**
1. Pick the next failing test
2. Write the smallest implementation that makes it pass
3. Run the full suite - nothing else should break
4. Repeat

**Step 2c: Refactor**
After all tests green, refactor for clarity and performance.

#### Phase 3 - Adversarial Refinement

The code survived testing. Now it faces the gauntlet.

Reviews: spec fidelity, test quality, code quality, security surface, spec gaps.

#### Phase 4 - Feedback Integration Loop

Critique feeds back through the pipeline:
- Spec-level flaws -> Phase 1
- Test-level flaws -> Phase 2a
- Implementation flaws -> Phase 2c
- New edge cases -> Spec update -> new tests -> fix

#### Phase 5 - Formal Hardening

- Fuzz testing on the pure core
- Security static analysis (cargo-audit, clippy)
- Mutation testing where applicable

#### Phase 6 - Convergence

Done when:
- Adversary critiques are nitpicks, not real issues
- No meaningful untested scenarios remain
- Implementation matches spec completely
- Security analysis is clean

### Core Principles

1. **Spec Supremacy**: The spec is the highest authority below the human developer
2. **Verification-First Architecture**: Pure core, effectful shell - designed from Phase 1
3. **Red Before Green**: No implementation without a failing test
4. **Anti-Slop Bias**: First "correct" version assumed to contain hidden debt
5. **Minimal Implementation**: Three similar lines > premature abstraction

### Applying VSDD in This Project

Each feature follows this flow:

1. Create spec in `specs/features/<feature-name>.md`
2. Spec review with human
3. Write failing tests in appropriate crate
4. Implement minimally in pure core (`forage-core`)
5. Wire up in effectful shell (`forage-server`, `forage-db`)
6. Adversarial review
7. Iterate until convergence