112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# 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
|