# SDLC Orchestration System Specification

## Overview

A deterministic, adaptive software development lifecycle system that enforces enterprise-grade development practices through structured artifacts, state management, and intelligent orchestration.

**Core Principles:**
1. Every command produces a concrete artifact at a deterministic location
2. Git is the source of truth for all SDLC state
3. A classifier engine recursively determines the next required action
4. All work happens on branches until verified and approved
5. The system is self-documenting and auditable

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           SDLC Orchestration System                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Claude    │───▶│  Classifier │───▶│  SDLC CLI   │───▶│    Git      │  │
│  │  Commands   │    │   Engine    │    │    Tool     │    │  Structure  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
│         │                  │                  │                  │          │
│         │                  │                  │                  │          │
│         ▼                  ▼                  ▼                  ▼          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        .sdlc/ Directory                              │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │   │
│  │  │ roadmap/ │ │features/ │ │patterns/ │ │ audits/  │ │ state/   │  │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Git Structure (Source of Truth)

All SDLC artifacts live in `.sdlc/` at the repository root:

```
.sdlc/
├── state.yaml                    # Global SDLC state (current phase, active work)
├── config.yaml                   # Project SDLC configuration
│
├── roadmap/                      # Strategic planning artifacts
│   ├── index.md                  # Roadmap overview with links
│   ├── v1.0/
│   │   ├── roadmap.md            # Version roadmap document
│   │   ├── milestones.md         # Milestone definitions
│   │   └── releases.md           # Release schedule
│   └── backlog.md                # Unprioritized ideas
│
├── features/                     # Feature development artifacts
│   ├── index.md                  # Feature registry with status
│   └── {feature-slug}/
│       ├── manifest.yaml         # Feature metadata and state machine
│       ├── spec.md               # Canonical specification (immutable after approval)
│       ├── design.md             # Architecture/design decisions
│       ├── tasks.md              # Implementation task breakdown
│       ├── qa-plan.md            # QA verification flow
│       ├── qa-results.md         # QA execution results
│       ├── review.md             # Code review findings
│       ├── audit.md              # Post-implementation audit
│       └── changelog.md          # Feature development history
│
├── patterns/                     # Elevated patterns (canonical references)
│   ├── index.md                  # Pattern catalog
│   └── {pattern-slug}/
│       ├── pattern.md            # Pattern specification
│       ├── examples.md           # Code examples
│       ├── violations.md         # Known violations to fix
│       └── adoption.md           # Adoption tracking
│
├── audits/                       # Codebase-wide audits
│   ├── index.md                  # Audit history
│   └── {audit-date}-{type}.md    # Individual audit reports
│
├── branches/                     # Branch lifecycle tracking
│   ├── index.md                  # Active branches
│   └── {branch-name}.yaml        # Branch state and checklist
│
└── archives/                     # Completed features (moved after release)
    └── {feature-slug}/           # Same structure as features/
```

---

## State Machine

### Global States

```yaml
# .sdlc/state.yaml
version: 1
project:
  name: "project-name"
  current_roadmap: "v1.0"

active_work:
  features:
    - slug: "auth"
      branch: "feature/auth"
      phase: "implementation"

  patterns:
    - slug: "error-handling"
      phase: "elevation"

  audits:
    - type: "api-consistency"
      phase: "remediation"

blocked: []

last_updated: "2024-01-15T10:30:00Z"
last_action: "task-complete"
last_actor: "claude"
```

### Feature Lifecycle Phases

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Feature Lifecycle State Machine                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│  │  DRAFT   │───▶│SPECIFIED │───▶│ PLANNED  │───▶│ READY    │             │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘             │
│       │               │               │               │                    │
│       │ spec.md       │ design.md     │ tasks.md      │ branch created     │
│       │ created       │ approved      │ qa-plan.md    │ all prereqs met    │
│       │               │               │ approved      │                    │
│       ▼               ▼               ▼               ▼                    │
│                                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│  │IMPLEMENT │───▶│ REVIEW   │───▶│  AUDIT   │───▶│    QA    │             │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘             │
│       │               │               │               │                    │
│       │ tasks done    │ review.md     │ audit.md      │ qa-results.md      │
│       │               │ all PASS      │ all PASS      │ all PASS           │
│       ▼               ▼               ▼               ▼                    │
│                                                                             │
│  ┌──────────┐    ┌──────────┐                                              │
│  │  MERGE   │───▶│ RELEASED │                                              │
│  └──────────┘    └──────────┘                                              │
│       │               │                                                    │
│       │ PR merged     │ archived                                           │
│       │ main updated  │                                                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Feature Manifest (State Tracking)

```yaml
# .sdlc/features/auth/manifest.yaml
slug: "auth"
title: "User Authentication System"
created: "2024-01-10T09:00:00Z"
branch: "feature/auth"
roadmap_ref: "v1.0/M2"

phase: "implementation"
phase_history:
  - phase: "draft"
    entered: "2024-01-10T09:00:00Z"
    exited: "2024-01-10T14:00:00Z"
  - phase: "specified"
    entered: "2024-01-10T14:00:00Z"
    exited: "2024-01-11T10:00:00Z"
  - phase: "planned"
    entered: "2024-01-11T10:00:00Z"
    exited: "2024-01-11T16:00:00Z"
  - phase: "ready"
    entered: "2024-01-11T16:00:00Z"
    exited: "2024-01-12T09:00:00Z"
  - phase: "implementation"
    entered: "2024-01-12T09:00:00Z"
    exited: null

artifacts:
  spec:
    status: "approved"
    path: "spec.md"
    approved_by: "user"
    approved_at: "2024-01-10T14:00:00Z"
  design:
    status: "approved"
    path: "design.md"
    approved_by: "user"
    approved_at: "2024-01-11T10:00:00Z"
  tasks:
    status: "approved"
    path: "tasks.md"
    total: 8
    completed: 5
    in_progress: 1
    blocked: 0
  qa_plan:
    status: "approved"
    path: "qa-plan.md"
    checkpoints: 12
  review:
    status: "pending"
    path: "review.md"
  audit:
    status: "pending"
    path: "audit.md"
  qa_results:
    status: "pending"
    path: "qa-results.md"

blockers: []
dependencies:
  features: []
  patterns: ["error-handling"]
```

---

## Classifier Engine

The classifier is a deterministic rules engine that evaluates current state and determines the next required action.

### Classifier Interface

```
Input:  Current state (.sdlc/state.yaml + feature manifests)
Output: Next action (command + target + context)
```

### Classification Rules (Priority Order)

```yaml
# Classifier decision tree (evaluated top-to-bottom, first match wins)

rules:
  # ============================================
  # BLOCKERS (highest priority)
  # ============================================
  - id: "blocked-dependency"
    condition: "feature.blockers.length > 0"
    action: "BLOCKED"
    message: "Feature blocked by: {blockers}"
    next_command: null

  # ============================================
  # PHASE: DRAFT → SPECIFIED
  # ============================================
  - id: "needs-spec"
    condition: "feature.phase == 'draft' AND NOT exists(spec.md)"
    action: "CREATE_SPEC"
    next_command: "/spec-feature {feature}"
    output_path: ".sdlc/features/{feature}/spec.md"

  - id: "spec-needs-approval"
    condition: "feature.phase == 'draft' AND spec.status == 'draft'"
    action: "AWAIT_APPROVAL"
    message: "Spec requires user approval"
    next_command: null

  - id: "spec-approved"
    condition: "feature.phase == 'draft' AND spec.status == 'approved'"
    action: "TRANSITION"
    transition_to: "specified"

  # ============================================
  # PHASE: SPECIFIED → PLANNED
  # ============================================
  - id: "needs-design"
    condition: "feature.phase == 'specified' AND NOT exists(design.md)"
    action: "CREATE_DESIGN"
    next_command: "/design-feature {feature}"
    output_path: ".sdlc/features/{feature}/design.md"

  - id: "needs-tasks"
    condition: "feature.phase == 'specified' AND design.status == 'approved' AND NOT exists(tasks.md)"
    action: "CREATE_TASKS"
    next_command: "/breakdown-feature {feature}"
    output_path: ".sdlc/features/{feature}/tasks.md"

  - id: "needs-qa-plan"
    condition: "feature.phase == 'specified' AND tasks.status == 'approved' AND NOT exists(qa-plan.md)"
    action: "CREATE_QA_PLAN"
    next_command: "/create-qa-plan {feature}"
    output_path: ".sdlc/features/{feature}/qa-plan.md"

  - id: "planning-complete"
    condition: "feature.phase == 'specified' AND qa_plan.status == 'approved'"
    action: "TRANSITION"
    transition_to: "planned"

  # ============================================
  # PHASE: PLANNED → READY
  # ============================================
  - id: "needs-branch"
    condition: "feature.phase == 'planned' AND NOT branch_exists(feature.branch)"
    action: "CREATE_BRANCH"
    next_command: "/create-branch {feature}"

  - id: "check-dependencies"
    condition: "feature.phase == 'planned' AND has_unmet_dependencies(feature)"
    action: "BLOCKED"
    message: "Dependencies not met: {unmet_deps}"

  - id: "ready-to-implement"
    condition: "feature.phase == 'planned' AND branch_exists AND dependencies_met"
    action: "TRANSITION"
    transition_to: "ready"

  # ============================================
  # PHASE: READY → IMPLEMENTATION
  # ============================================
  - id: "start-implementation"
    condition: "feature.phase == 'ready'"
    action: "TRANSITION"
    transition_to: "implementation"

  # ============================================
  # PHASE: IMPLEMENTATION
  # ============================================
  - id: "implement-next-task"
    condition: "feature.phase == 'implementation' AND has_pending_tasks()"
    action: "IMPLEMENT_TASK"
    next_command: "/implement-task {feature} {next_task_id}"

  - id: "implementation-complete"
    condition: "feature.phase == 'implementation' AND all_tasks_complete()"
    action: "TRANSITION"
    transition_to: "review"

  # ============================================
  # PHASE: REVIEW
  # ============================================
  - id: "needs-review"
    condition: "feature.phase == 'review' AND review.status == 'pending'"
    action: "REVIEW_CODE"
    next_command: "/review-feature {feature}"
    output_path: ".sdlc/features/{feature}/review.md"

  - id: "review-has-issues"
    condition: "feature.phase == 'review' AND review.status == 'needs_fix'"
    action: "FIX_REVIEW_ISSUES"
    next_command: "/fix-review-issues {feature}"

  - id: "review-passed"
    condition: "feature.phase == 'review' AND review.status == 'passed'"
    action: "TRANSITION"
    transition_to: "audit"

  # ============================================
  # PHASE: AUDIT
  # ============================================
  - id: "needs-audit"
    condition: "feature.phase == 'audit' AND audit.status == 'pending'"
    action: "AUDIT_CODE"
    next_command: "/audit-feature {feature}"
    output_path: ".sdlc/features/{feature}/audit.md"

  - id: "audit-has-issues"
    condition: "feature.phase == 'audit' AND audit.status == 'needs_remediation'"
    action: "REMEDIATE_AUDIT"
    next_command: "/remediate-audit {feature}"

  - id: "audit-passed"
    condition: "feature.phase == 'audit' AND audit.status == 'passed'"
    action: "TRANSITION"
    transition_to: "qa"

  # ============================================
  # PHASE: QA
  # ============================================
  - id: "needs-qa"
    condition: "feature.phase == 'qa' AND qa_results.status == 'pending'"
    action: "RUN_QA"
    next_command: "/run-qa {feature}"
    output_path: ".sdlc/features/{feature}/qa-results.md"

  - id: "qa-has-failures"
    condition: "feature.phase == 'qa' AND qa_results.status == 'failed'"
    action: "FIX_QA_FAILURES"
    next_command: "/fix-qa-failures {feature}"

  - id: "qa-passed"
    condition: "feature.phase == 'qa' AND qa_results.status == 'passed'"
    action: "TRANSITION"
    transition_to: "merge"

  # ============================================
  # PHASE: MERGE
  # ============================================
  - id: "needs-merge"
    condition: "feature.phase == 'merge'"
    action: "MERGE_FEATURE"
    next_command: "/merge-feature {feature}"

  # ============================================
  # PHASE: RELEASED
  # ============================================
  - id: "archive-feature"
    condition: "feature.phase == 'released'"
    action: "ARCHIVE"
    next_command: "/archive-feature {feature}"

  # ============================================
  # PATTERN LIFECYCLE
  # ============================================
  - id: "pattern-needs-elevation"
    condition: "pattern.phase == 'identified'"
    action: "ELEVATE_PATTERN"
    next_command: "/elevate-pattern {pattern}"
    output_path: ".sdlc/patterns/{pattern}/pattern.md"

  - id: "pattern-needs-examples"
    condition: "pattern.phase == 'documented' AND NOT exists(examples.md)"
    action: "ADD_EXAMPLES"
    next_command: "/add-pattern-examples {pattern}"

  - id: "pattern-needs-adoption"
    condition: "pattern.phase == 'documented' AND examples.status == 'complete'"
    action: "FIND_VIOLATIONS"
    next_command: "/find-pattern-violations {pattern}"
    output_path: ".sdlc/patterns/{pattern}/violations.md"

  - id: "pattern-has-violations"
    condition: "pattern.violations.count > 0"
    action: "FIX_VIOLATIONS"
    next_command: "/fix-pattern-violations {pattern}"

  # ============================================
  # DEFAULT
  # ============================================
  - id: "nothing-to-do"
    condition: "true"
    action: "IDLE"
    message: "No actionable work found"
```

### Classifier Output Format

```yaml
# Classifier response
classification:
  timestamp: "2024-01-15T10:30:00Z"
  context:
    feature: "auth"
    current_phase: "implementation"

  evaluation:
    rule_matched: "implement-next-task"
    conditions_checked:
      - "feature.phase == 'implementation'" : true
      - "has_pending_tasks()" : true

  decision:
    action: "IMPLEMENT_TASK"
    command: "/implement-task auth task-004"
    output_path: ".sdlc/features/auth/tasks.md"

  context_for_command:
    feature_slug: "auth"
    task_id: "task-004"
    task_title: "Implement JWT token validation"
    task_spec: |
      Validate JWT tokens on protected endpoints...
    patterns_to_follow:
      - "error-handling"
    related_files:
      - "internal/auth/jwt.go"
      - "internal/middleware/auth.go"
```

---

## SDLC CLI Tool

### Command Reference

```bash
# ============================================
# INITIALIZATION
# ============================================
sdlc init                              # Initialize .sdlc/ structure
sdlc config set <key> <value>          # Configure project settings

# ============================================
# ROADMAP MANAGEMENT
# ============================================
sdlc roadmap create <version>          # Create new roadmap version
sdlc roadmap list                      # List all roadmap versions
sdlc roadmap show <version>            # Display roadmap
sdlc roadmap set-active <version>      # Set active roadmap version

# ============================================
# FEATURE MANAGEMENT
# ============================================
sdlc feature create <slug>             # Create new feature
sdlc feature list                      # List all features with status
sdlc feature show <slug>               # Show feature details
sdlc feature status <slug>             # Show feature phase and progress
sdlc feature transition <slug> <phase> # Manually transition phase
sdlc feature block <slug> <reason>     # Mark feature as blocked
sdlc feature unblock <slug>            # Remove blocker

# ============================================
# ARTIFACT MANAGEMENT
# ============================================
sdlc artifact create <feature> <type>  # Create artifact file
sdlc artifact approve <feature> <type> # Mark artifact as approved
sdlc artifact reject <feature> <type>  # Mark artifact as rejected
sdlc artifact status <feature>         # Show all artifact statuses

# ============================================
# TASK MANAGEMENT
# ============================================
sdlc task list <feature>               # List tasks for feature
sdlc task start <feature> <task-id>    # Mark task as in-progress
sdlc task complete <feature> <task-id> # Mark task as complete
sdlc task block <feature> <task-id>    # Mark task as blocked
sdlc task add <feature> <title>        # Add new task

# ============================================
# BRANCH MANAGEMENT
# ============================================
sdlc branch create <feature>           # Create feature branch
sdlc branch status <feature>           # Show branch checklist
sdlc branch sync <feature>             # Sync branch with main

# ============================================
# PATTERN MANAGEMENT
# ============================================
sdlc pattern create <slug>             # Create new pattern
sdlc pattern list                      # List all patterns
sdlc pattern show <slug>               # Show pattern details
sdlc pattern adopt <slug>              # Start adoption campaign

# ============================================
# AUDIT MANAGEMENT
# ============================================
sdlc audit create <type>               # Create new audit
sdlc audit list                        # List all audits
sdlc audit show <id>                   # Show audit details

# ============================================
# STATE & CLASSIFICATION
# ============================================
sdlc state                             # Show current global state
sdlc next                              # Run classifier, show next action
sdlc next --execute                    # Run classifier and execute action
sdlc next --for <feature>              # Classify for specific feature
sdlc history                           # Show action history

# ============================================
# QUERIES
# ============================================
sdlc query blocked                     # List all blocked items
sdlc query ready                       # List items ready for work
sdlc query needs-approval              # List items awaiting approval
sdlc query in-progress                 # List items in progress
```

### CLI Output Format

```bash
$ sdlc next --for auth

┌─────────────────────────────────────────────────────────────────┐
│ SDLC Classifier Result                                          │
├─────────────────────────────────────────────────────────────────┤
│ Feature: auth                                                   │
│ Current Phase: implementation                                   │
│ Tasks: 5/8 complete, 1 in-progress, 2 pending                   │
├─────────────────────────────────────────────────────────────────┤
│ NEXT ACTION: IMPLEMENT_TASK                                     │
│                                                                 │
│ Command: /implement-task auth task-004                          │
│ Task: Implement JWT token validation                            │
│ Output: .sdlc/features/auth/tasks.md (updated)                  │
│                                                                 │
│ Context provided to command:                                    │
│ - Task specification                                            │
│ - Required patterns: error-handling                             │
│ - Related files: internal/auth/jwt.go                           │
└─────────────────────────────────────────────────────────────────┘

Run with --execute to execute this action.
```

---

## Command Specifications

Every command MUST:
1. Read context from SDLC structure
2. Produce a concrete artifact
3. Write artifact to the correct location
4. Update manifest/state
5. Return structured output

### Command Catalog

#### Phase: Planning

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/plan-roadmap` | Version, goals | `.sdlc/roadmap/{version}/roadmap.md` | Roadmap document |
| `/spec-feature` | Feature slug | `.sdlc/features/{slug}/spec.md` | Specification |
| `/design-feature` | Feature slug | `.sdlc/features/{slug}/design.md` | Design document |
| `/breakdown-feature` | Feature slug | `.sdlc/features/{slug}/tasks.md` | Task breakdown |
| `/create-qa-plan` | Feature slug | `.sdlc/features/{slug}/qa-plan.md` | QA verification plan |

#### Phase: Implementation

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/create-branch` | Feature slug | `.sdlc/branches/{branch}.yaml` | Branch tracking |
| `/implement-task` | Feature, task ID | `.sdlc/features/{slug}/tasks.md` | Task completion |
| `/implement-feature` | Feature slug | `.sdlc/features/{slug}/tasks.md` | All tasks (orchestrated) |

#### Phase: Quality

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/review-feature` | Feature slug | `.sdlc/features/{slug}/review.md` | Review findings |
| `/fix-review-issues` | Feature slug | `.sdlc/features/{slug}/review.md` | Updated findings |
| `/audit-feature` | Feature slug | `.sdlc/features/{slug}/audit.md` | Audit findings |
| `/remediate-audit` | Feature slug | `.sdlc/features/{slug}/audit.md` | Updated findings |
| `/run-qa` | Feature slug | `.sdlc/features/{slug}/qa-results.md` | QA results |
| `/fix-qa-failures` | Feature slug | `.sdlc/features/{slug}/qa-results.md` | Updated results |

#### Phase: Release

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/merge-feature` | Feature slug | Git merge + manifest update | Merged branch |
| `/archive-feature` | Feature slug | `.sdlc/archives/{slug}/` | Archived feature |

#### Patterns

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/identify-pattern` | Pattern description | `.sdlc/patterns/{slug}/pattern.md` | Pattern draft |
| `/elevate-pattern` | Pattern slug | `.sdlc/patterns/{slug}/pattern.md` | Elevated pattern |
| `/add-pattern-examples` | Pattern slug | `.sdlc/patterns/{slug}/examples.md` | Code examples |
| `/find-pattern-violations` | Pattern slug | `.sdlc/patterns/{slug}/violations.md` | Violation list |
| `/fix-pattern-violations` | Pattern slug | `.sdlc/patterns/{slug}/adoption.md` | Adoption progress |

#### Orchestration

| Command | Input | Output Location | Output Type |
|---------|-------|-----------------|-------------|
| `/next` | Optional: feature | Classifier output | Next action |
| `/deliver` | Feature slug | Orchestrates full delivery | Full feature delivery |

---

## Document Specifications

### spec.md (Feature Specification)

```markdown
---
feature: auth
version: 1
status: approved
approved_by: user
approved_at: 2024-01-10T14:00:00Z
---

# Feature: User Authentication System

## Overview
[2-3 sentence summary of what this feature does]

## Problem Statement
[What problem does this solve? Why is it needed?]

## User Stories
- As a [user type], I want to [action] so that [benefit]
- ...

## Acceptance Criteria
- [ ] AC1: Users can register with email and password
- [ ] AC2: Users can log in with valid credentials
- [ ] AC3: Invalid credentials return appropriate error
- [ ] AC4: Sessions expire after 24 hours
- ...

## Non-Functional Requirements
- Performance: Login < 200ms p99
- Security: Passwords hashed with bcrypt, cost 12
- Availability: 99.9% uptime

## Out of Scope
- Social login (future feature)
- MFA (future feature)

## Dependencies
- Database provisioning (complete)
- Error handling pattern (in progress)

## Open Questions
[Any unresolved questions - must be empty before approval]
```

### tasks.md (Task Breakdown)

```markdown
---
feature: auth
version: 1
total_tasks: 8
completed: 5
in_progress: 1
blocked: 0
pending: 2
---

# Task Breakdown: User Authentication

## Summary
| Status | Count |
|--------|-------|
| ✓ Complete | 5 |
| → In Progress | 1 |
| ○ Pending | 2 |
| ✗ Blocked | 0 |

## Tasks

### task-001: Create User domain model ✓
- **Status:** complete
- **Completed:** 2024-01-12T10:00:00Z
- **Files:** `internal/domain/user.go`
- **Patterns:** error-handling
- **Notes:** Added validation for email format

### task-002: Create UserRepository interface ✓
- **Status:** complete
- **Completed:** 2024-01-12T11:00:00Z
- **Files:** `internal/port/user_repository.go`

### task-003: Implement PostgreSQL UserRepository ✓
- **Status:** complete
- **Completed:** 2024-01-12T14:00:00Z
- **Files:** `internal/adapter/postgres/user_repo.go`
- **Tests:** `internal/adapter/postgres/user_repo_test.go`

### task-004: Implement JWT token validation →
- **Status:** in_progress
- **Started:** 2024-01-12T15:00:00Z
- **Spec:** |
    Implement JWT token validation middleware:
    - Parse Authorization header (Bearer token)
    - Validate token signature using project secret
    - Extract claims and attach to context
    - Return 401 for invalid/expired tokens
- **Files:**
    - `internal/auth/jwt.go`
    - `internal/middleware/auth.go`
- **Patterns:** error-handling
- **Depends on:** task-001, task-002

### task-005: Implement login endpoint ○
- **Status:** pending
- **Spec:** |
    POST /api/v1/auth/login
    - Accept email + password
    - Validate credentials
    - Return JWT token on success
    - Return 401 on failure
- **Depends on:** task-003, task-004

### task-006: Implement register endpoint ○
- **Status:** pending
- **Spec:** |
    POST /api/v1/auth/register
    - Accept email + password
    - Validate email format and password strength
    - Hash password with bcrypt
    - Create user record
    - Return 201 on success
- **Depends on:** task-003

### task-007: Add authentication tests ✓
- **Status:** complete
- **Completed:** 2024-01-12T16:00:00Z
- **Files:** `internal/auth/*_test.go`

### task-008: Update API documentation ✓
- **Status:** complete
- **Completed:** 2024-01-12T16:30:00Z
- **Files:** `docs/api/auth.md`
```

### qa-plan.md (QA Verification Plan)

```markdown
---
feature: auth
version: 1
checkpoints: 12
categories:
  - functional: 6
  - security: 4
  - performance: 2
---

# QA Verification Plan: User Authentication

## Functional Tests

### QA-001: User Registration Happy Path
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. POST /api/v1/auth/register with valid email and password
  2. Verify response status 201
  3. Verify response contains user ID
  4. Verify user exists in database
  5. Verify password is hashed (not plaintext)
- **Expected:** User created successfully

### QA-002: User Registration - Invalid Email
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. POST /api/v1/auth/register with invalid email format
  2. Verify response status 400
  3. Verify error message indicates email format issue
- **Expected:** Validation error returned

### QA-003: User Login Happy Path
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. Create test user
  2. POST /api/v1/auth/login with correct credentials
  3. Verify response status 200
  4. Verify response contains valid JWT token
  5. Verify token contains correct claims
- **Expected:** Valid JWT returned

### QA-004: User Login - Invalid Password
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. Create test user
  2. POST /api/v1/auth/login with wrong password
  3. Verify response status 401
  4. Verify error message is generic (not revealing which field is wrong)
- **Expected:** Authentication error, no information leakage

### QA-005: Protected Endpoint - Valid Token
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. Obtain valid JWT token
  2. Access protected endpoint with token in Authorization header
  3. Verify response status 200
  4. Verify user context is available
- **Expected:** Access granted

### QA-006: Protected Endpoint - Expired Token
- **Category:** functional
- **Priority:** P0
- **Steps:**
  1. Generate expired JWT token
  2. Access protected endpoint with expired token
  3. Verify response status 401
  4. Verify error indicates token expiration
- **Expected:** Access denied with clear message

## Security Tests

### QA-007: SQL Injection Prevention
- **Category:** security
- **Priority:** P0
- **Steps:**
  1. Attempt login with SQL injection payloads
  2. Verify no SQL errors exposed
  3. Verify queries are parameterized (code review)
- **Expected:** All inputs sanitized

### QA-008: Password Storage Security
- **Category:** security
- **Priority:** P0
- **Steps:**
  1. Create user
  2. Examine database record
  3. Verify password is bcrypt hashed
  4. Verify cost factor >= 12
- **Expected:** Passwords securely hashed

### QA-009: Token Secret Security
- **Category:** security
- **Priority:** P0
- **Steps:**
  1. Verify JWT secret loaded from environment
  2. Verify secret not logged
  3. Verify secret not in code
- **Expected:** Secret properly managed

### QA-010: Brute Force Protection
- **Category:** security
- **Priority:** P1
- **Steps:**
  1. Attempt 10 failed logins rapidly
  2. Verify rate limiting kicks in
  3. Verify appropriate error returned
- **Expected:** Rate limiting active

## Performance Tests

### QA-011: Login Latency
- **Category:** performance
- **Priority:** P1
- **Steps:**
  1. Run 100 login requests
  2. Measure p50, p90, p99 latency
- **Expected:** p99 < 200ms

### QA-012: Token Validation Latency
- **Category:** performance
- **Priority:** P1
- **Steps:**
  1. Run 1000 authenticated requests
  2. Measure validation overhead
- **Expected:** < 5ms overhead
```

### review.md (Code Review Findings)

```markdown
---
feature: auth
version: 1
reviewed_at: 2024-01-13T10:00:00Z
status: needs_fix
findings:
  blocker: 0
  critical: 1
  warning: 3
  suggestion: 2
---

# Code Review: User Authentication

## Summary

| Severity | Count | Status |
|----------|-------|--------|
| Blocker | 0 | - |
| Critical | 1 | ✗ Open |
| Warning | 3 | ✗ Open |
| Suggestion | 2 | ✗ Open |

**Verdict:** NEEDS_FIX

## Findings

### CRITICAL-001: Missing error context in JWT validation
- **File:** `internal/auth/jwt.go:45`
- **Status:** open
- **Issue:** Error returned without context, making debugging difficult
- **Code:**
  ```go
  // Current
  return nil, err

  // Should be
  return nil, fmt.Errorf("validate jwt token: %w", err)
  ```
- **Fix Applied:** [ ]

### WARNING-001: Inconsistent error handling in login handler
- **File:** `internal/handlers/auth.go:67`
- **Status:** open
- **Issue:** Uses `api.WriteError` instead of `api.WriteUnauthorized`
- **Pattern:** error-handling
- **Fix Applied:** [ ]

### WARNING-002: Missing table-driven tests for token validation
- **File:** `internal/auth/jwt_test.go`
- **Status:** open
- **Issue:** Tests cover happy path but miss edge cases
- **Missing cases:**
  - Empty token
  - Malformed token
  - Token with invalid signature
  - Token with missing claims
- **Fix Applied:** [ ]

### WARNING-003: Hardcoded token expiration
- **File:** `internal/auth/jwt.go:23`
- **Status:** open
- **Issue:** Token expiration hardcoded to 24h, should be configurable
- **Fix Applied:** [ ]

### SUGGESTION-001: Consider extracting JWT config
- **File:** `internal/auth/jwt.go`
- **Status:** open
- **Issue:** JWT configuration inline, could be cleaner as config struct
- **Fix Applied:** [ ]

### SUGGESTION-002: Add structured logging for auth events
- **File:** `internal/handlers/auth.go`
- **Status:** open
- **Issue:** No logging for login attempts (success/failure)
- **Fix Applied:** [ ]

## What's Good

- Clean separation between domain and handler layers
- Proper use of context for request scoping
- Good test coverage for happy paths
- Consistent API response format
```

### audit.md (Post-Implementation Audit)

```markdown
---
feature: auth
version: 1
audited_at: 2024-01-13T14:00:00Z
status: needs_remediation
categories:
  - pattern_compliance
  - security
  - performance
  - documentation
findings:
  critical: 0
  high: 2
  medium: 3
  low: 1
---

# Audit Report: User Authentication

## Summary

| Category | Status | Issues |
|----------|--------|--------|
| Pattern Compliance | ⚠️ | 2 issues |
| Security | ✓ | 0 issues |
| Performance | ⚠️ | 1 issue |
| Documentation | ⚠️ | 2 issues |

**Verdict:** NEEDS_REMEDIATION

## Pattern Compliance

### HIGH-001: Logging pattern not followed
- **Pattern:** logging-standards
- **Files:**
  - `internal/handlers/auth.go` - No structured logging
  - `internal/auth/jwt.go` - No trace ID propagation
- **Required:** All handlers must log with trace ID and structured fields
- **Remediation:** Apply logging pattern to all auth files
- **Remediated:** [ ]

### HIGH-002: Error handling inconsistent
- **Pattern:** error-handling
- **Files:**
  - `internal/auth/jwt.go:45` - Missing error context
  - `internal/auth/jwt.go:67` - Missing error context
- **Required:** All errors wrapped with context
- **Remediation:** Add error wrapping
- **Remediated:** [ ]

## Security

No issues found. ✓

## Performance

### MEDIUM-001: Database connection not pooled efficiently
- **File:** `internal/adapter/postgres/user_repo.go`
- **Issue:** Each query creates new connection
- **Impact:** Higher latency under load
- **Remediation:** Use connection pool from injected DB
- **Remediated:** [ ]

## Documentation

### MEDIUM-002: API documentation incomplete
- **File:** `docs/api/auth.md`
- **Missing:**
  - Error response examples
  - Rate limiting documentation
- **Remediation:** Add missing sections
- **Remediated:** [ ]

### LOW-001: Code comments sparse
- **Files:** Various
- **Issue:** Complex logic not commented
- **Remediation:** Add comments for non-obvious code
- **Remediated:** [ ]

## Recommendations

1. Run `/fix-pattern-violations logging-standards` on auth module
2. Run `/fix-pattern-violations error-handling` on auth module
3. Update API documentation
```

### pattern.md (Pattern Specification)

```markdown
---
pattern: error-handling
version: 2
status: elevated
created: 2024-01-05T09:00:00Z
elevated: 2024-01-10T14:00:00Z
adoption:
  total_files: 45
  compliant: 38
  violations: 7
---

# Pattern: Error Handling

## Overview

All errors in {{PROJECT_NAME}} must be wrapped with context, use sentinel errors for known conditions, and propagate correctly through the hexagonal architecture.

## The Pattern

### 1. Error Wrapping

Always wrap errors with context using `fmt.Errorf` with `%w`:

```go
// ✓ GOOD
result, err := repo.FindByID(ctx, id)
if err != nil {
    return nil, fmt.Errorf("find user by id %s: %w", id, err)
}

// ✗ BAD
result, err := repo.FindByID(ctx, id)
if err != nil {
    return nil, err  // Lost context!
}
```

### 2. Sentinel Errors

Define sentinel errors in `internal/domain/errors.go`:

```go
var (
    ErrNotFound       = errors.New("not found")
    ErrAlreadyExists  = errors.New("already exists")
    ErrInvalidInput   = errors.New("invalid input")
    ErrUnauthorized   = errors.New("unauthorized")
    ErrForbidden      = errors.New("forbidden")
)
```

### 3. Error Checking

Use `errors.Is` for sentinel errors:

```go
if errors.Is(err, domain.ErrNotFound) {
    api.WriteNotFound(w, "user not found")
    return
}
```

### 4. Handler Error Responses

Use appropriate response helpers:

```go
// ✓ GOOD
api.WriteNotFound(w, "user not found")
api.WriteBadRequest(w, "invalid email format")
api.WriteUnauthorized(w, "invalid credentials")

// ✗ BAD
api.WriteError(w, http.StatusNotFound, "NOT_FOUND", "user not found")
```

### 5. Never Swallow Errors

```go
// ✗ NEVER DO THIS
result, _ := something()

// ✓ ALWAYS HANDLE
result, err := something()
if err != nil {
    // handle it
}
```

## Detection Rules

```go
// Violations to detect:
// 1. Bare error returns: `return nil, err` without wrapping
// 2. Ignored errors: `_, _ = something()` or `_ = err`
// 3. Direct status codes: `api.WriteError(w, 404, ...)` instead of helpers
// 4. errors.New in handlers (should use domain errors)
```

## Adoption Status

| Status | Files |
|--------|-------|
| Compliant | 38 |
| Violations | 7 |
| **Total** | 45 |

### Known Violations

See `.sdlc/patterns/error-handling/violations.md` for current violation list.
```

---

## Driver / Orchestrator

The driver is a simple loop that uses the classifier to determine and execute the next action.

### Driver Pseudocode

```python
def drive(target: str = None, max_iterations: int = 100):
    """
    Main driver loop that advances SDLC state.

    Args:
        target: Optional specific feature/pattern to focus on
        max_iterations: Safety limit to prevent infinite loops
    """
    iteration = 0

    while iteration < max_iterations:
        iteration += 1

        # 1. Run classifier
        classification = sdlc_cli("next", target)

        # 2. Check for terminal states
        if classification.action == "IDLE":
            log("No actionable work found")
            break

        if classification.action == "BLOCKED":
            log(f"Blocked: {classification.message}")
            prompt_user_for_resolution()
            continue

        if classification.action == "AWAIT_APPROVAL":
            log(f"Awaiting approval: {classification.message}")
            approval = prompt_user_for_approval()
            if approval:
                sdlc_cli("artifact", "approve", classification.artifact)
            continue

        # 3. Execute action
        log(f"Executing: {classification.command}")
        result = execute_claude_command(classification.command)

        # 4. Verify output was produced
        if not verify_output_exists(classification.output_path):
            log(f"ERROR: Expected output not found at {classification.output_path}")
            prompt_user_for_intervention()
            continue

        # 5. Update state
        sdlc_cli("state", "record-action", classification.action)

        # 6. Handle transitions
        if classification.action == "TRANSITION":
            sdlc_cli("feature", "transition", target, classification.transition_to)

        # 7. Loop continues with next classification

    if iteration >= max_iterations:
        log("WARNING: Max iterations reached, stopping driver")
```

### Claude Command: `/next`

```markdown
---
description: Determine and optionally execute the next SDLC action
argument-hint: <feature-slug> or "all" for global next action
allowed-tools: Bash, Read, Write, Edit
---

Determine what needs to happen next for: $ARGUMENTS

## Instructions

1. Run the classifier:
   ```bash
   sdlc next --for $ARGUMENTS
   ```

2. Parse the classifier output

3. If action is AWAIT_APPROVAL:
   - Show what needs approval
   - Ask user to approve/reject
   - Record decision with `sdlc artifact approve/reject`

4. If action is BLOCKED:
   - Show the blocker
   - Ask user how to resolve

5. If action is a command:
   - Show the recommended command
   - Ask user: "Execute this? (y/n)"
   - If yes, execute and verify output

6. After execution:
   - Verify output file exists at expected location
   - Update state: `sdlc state record-action <action>`
   - Run classifier again to show next step

## Output Format

```markdown
## SDLC Status: {feature}

**Phase:** {current_phase}
**Progress:** {tasks_complete}/{tasks_total} tasks

### Next Action: {action}

**Command:** `{command}`
**Output:** `{output_path}`
**Context:**
{context_summary}

---

Execute this action? (y/n)
```
```

---

## Enterprise Considerations

### Audit Trail

Every action is logged:

```yaml
# .sdlc/state.yaml (history section)
history:
  - timestamp: "2024-01-15T10:30:00Z"
    action: "IMPLEMENT_TASK"
    feature: "auth"
    task: "task-004"
    actor: "claude"
    result: "success"
    output: ".sdlc/features/auth/tasks.md"

  - timestamp: "2024-01-15T10:35:00Z"
    action: "TRANSITION"
    feature: "auth"
    from_phase: "implementation"
    to_phase: "review"
    actor: "classifier"
```

### Compliance Gates

Define required approvals:

```yaml
# .sdlc/config.yaml
compliance:
  spec_approval:
    required: true
    approvers: ["user", "tech-lead"]

  design_approval:
    required: true
    approvers: ["user", "architect"]

  merge_approval:
    required: true
    approvers: ["user"]
    checks:
      - "all_tasks_complete"
      - "review_passed"
      - "audit_passed"
      - "qa_passed"
```

### Metrics

Track development velocity:

```yaml
# .sdlc/metrics.yaml
features:
  auth:
    cycle_time_days: 5
    phases:
      draft_to_specified: 0.5
      specified_to_planned: 1.0
      planned_to_ready: 0.5
      ready_to_implementation: 3.0
      implementation_to_review: 0.5
      review_to_audit: 0.25
      audit_to_qa: 0.25
      qa_to_merge: 0.25
    review_iterations: 2
    audit_iterations: 1
    qa_iterations: 1
```

### Rollback Support

Every phase transition is reversible:

```bash
# Rollback feature to previous phase
sdlc feature rollback auth --to implementation

# This:
# 1. Updates manifest phase
# 2. Clears artifacts for phases after target
# 3. Records rollback in history
```

---

## rdev API Surface

Every classifier rule maps to an API-addressable state. The API provides full visibility and control over the SDLC workflow.

### Core Principle

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           API-First SDLC                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   External Driver (CI, UI, Bot)                                             │
│          │                                                                  │
│          ▼                                                                  │
│   ┌─────────────┐                                                           │
│   │  rdev API   │◀──── GET  /sdlc/next         "What needs to happen?"     │
│   │             │◀──── GET  /sdlc/blocked      "What's stuck?"              │
│   │             │◀──── POST /sdlc/resolve      "Here's the answer"          │
│   │             │◀──── POST /sdlc/execute      "Do it"                      │
│   │             │◀──── POST /sdlc/commit       "Save it"                    │
│   └─────────────┘                                                           │
│          │                                                                  │
│          ▼                                                                  │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                    │
│   │ Classifier  │───▶│  Executor   │───▶│    Git      │                    │
│   │   Engine    │    │  (Claude)   │    │  (.sdlc/)   │                    │
│   └─────────────┘    └─────────────┘    └─────────────┘                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### API Endpoints

#### State & Classification

```
GET /projects/{project}/sdlc/state
```
Returns current SDLC state for the project.

```json
{
  "project": "my-project",
  "current_roadmap": "v1.0",
  "active_features": [
    {
      "slug": "auth",
      "phase": "implementation",
      "branch": "feature/auth",
      "tasks_complete": 5,
      "tasks_total": 8,
      "blocked": false
    }
  ],
  "active_patterns": [],
  "blocked_items": []
}
```

---

```
GET /projects/{project}/sdlc/next
GET /projects/{project}/sdlc/next?feature={slug}
```
Run classifier and return the next required action.

```json
{
  "classification": {
    "rule_id": "implement-next-task",
    "action": "IMPLEMENT_TASK",
    "feature": "auth",
    "task_id": "task-004"
  },
  "instruction": {
    "summary": "Implement JWT token validation",
    "command": "/implement-task auth task-004",
    "output_path": ".sdlc/features/auth/tasks.md",
    "context": {
      "task_spec": "Implement JWT token validation middleware...",
      "patterns_required": ["error-handling"],
      "related_files": ["internal/auth/jwt.go"]
    }
  },
  "execute_url": "/projects/my-project/sdlc/execute",
  "can_auto_execute": true
}
```

---

```
GET /projects/{project}/sdlc/blocked
```
Returns all blocked items with resolution instructions.

```json
{
  "blocked": [
    {
      "type": "feature",
      "slug": "auth",
      "rule_id": "spec-needs-approval",
      "blocked_reason": "Specification requires user approval",
      "resolution": {
        "action": "APPROVE_ARTIFACT",
        "instruction": "Review the specification and approve or request changes",
        "artifact_path": ".sdlc/features/auth/spec.md",
        "resolve_url": "/projects/my-project/sdlc/features/auth/artifacts/spec/approve",
        "options": ["approve", "reject", "request_changes"]
      }
    },
    {
      "type": "feature",
      "slug": "payment",
      "rule_id": "blocked-dependency",
      "blocked_reason": "Depends on feature 'auth' which is not complete",
      "resolution": {
        "action": "COMPLETE_DEPENDENCY",
        "instruction": "Complete the 'auth' feature first",
        "dependency": "auth",
        "dependency_phase": "implementation",
        "unblock_url": null
      }
    },
    {
      "type": "feature",
      "slug": "notifications",
      "rule_id": "design-decision-needed",
      "blocked_reason": "Design decision required: Choose notification transport",
      "resolution": {
        "action": "ANSWER_QUESTION",
        "instruction": "Answer the design question in the design document",
        "question": "Which notification transport should we use?",
        "options": ["websocket", "sse", "polling"],
        "answer_path": ".sdlc/features/notifications/design.md",
        "answer_section": "## Open Questions",
        "resolve_url": "/projects/my-project/sdlc/features/notifications/resolve"
      }
    }
  ]
}
```

#### Execution

```
POST /projects/{project}/sdlc/execute
```
Execute the next classified action. Returns execution result and new state.

Request:
```json
{
  "feature": "auth",
  "action": "IMPLEMENT_TASK",
  "task_id": "task-004",
  "auto_commit": true
}
```

Response:
```json
{
  "execution": {
    "status": "success",
    "action": "IMPLEMENT_TASK",
    "duration_ms": 45000,
    "output_path": ".sdlc/features/auth/tasks.md",
    "files_modified": [
      "internal/auth/jwt.go",
      "internal/middleware/auth.go",
      ".sdlc/features/auth/tasks.md"
    ],
    "commit": {
      "sha": "abc123",
      "message": "feat(auth): implement JWT token validation [task-004]"
    }
  },
  "next": {
    "action": "IMPLEMENT_TASK",
    "task_id": "task-005",
    "summary": "Implement login endpoint"
  }
}
```

---

```
POST /projects/{project}/sdlc/resolve
```
Resolve a blocked item by providing the required input.

Request:
```json
{
  "feature": "notifications",
  "resolution_type": "ANSWER_QUESTION",
  "question_id": "notification-transport",
  "answer": "websocket",
  "rationale": "WebSocket provides real-time bidirectional communication needed for instant notifications",
  "auto_commit": true
}
```

Response:
```json
{
  "resolution": {
    "status": "resolved",
    "file_updated": ".sdlc/features/notifications/design.md",
    "commit": {
      "sha": "def456",
      "message": "docs(notifications): resolve design decision - use websocket transport"
    }
  },
  "unblocked": true,
  "next": {
    "action": "CREATE_TASKS",
    "command": "/breakdown-feature notifications"
  }
}
```

#### Feature Management

```
POST /projects/{project}/sdlc/features
```
Create a new feature.

Request:
```json
{
  "slug": "auth",
  "title": "User Authentication System",
  "roadmap_ref": "v1.0/M2",
  "description": "Implement user registration, login, and session management"
}
```

---

```
GET /projects/{project}/sdlc/features/{slug}
```
Get feature details including all artifacts and current state.

```json
{
  "slug": "auth",
  "title": "User Authentication System",
  "phase": "implementation",
  "branch": "feature/auth",
  "created": "2024-01-10T09:00:00Z",
  "artifacts": {
    "spec": {
      "status": "approved",
      "path": ".sdlc/features/auth/spec.md",
      "url": "/projects/my-project/files/.sdlc/features/auth/spec.md"
    },
    "design": {
      "status": "approved",
      "path": ".sdlc/features/auth/design.md"
    },
    "tasks": {
      "status": "in_progress",
      "path": ".sdlc/features/auth/tasks.md",
      "summary": {
        "total": 8,
        "complete": 5,
        "in_progress": 1,
        "pending": 2
      }
    },
    "qa_plan": {
      "status": "approved",
      "checkpoints": 12
    },
    "review": {
      "status": "pending"
    },
    "audit": {
      "status": "pending"
    },
    "qa_results": {
      "status": "pending"
    }
  },
  "next_action": {
    "action": "IMPLEMENT_TASK",
    "task_id": "task-004"
  }
}
```

---

```
POST /projects/{project}/sdlc/features/{slug}/transition
```
Manually transition a feature to a new phase (with validation).

Request:
```json
{
  "to_phase": "review",
  "force": false
}
```

Response:
```json
{
  "transition": {
    "from": "implementation",
    "to": "review",
    "status": "success"
  }
}
```

Or if validation fails:
```json
{
  "transition": {
    "from": "implementation",
    "to": "review",
    "status": "blocked",
    "reason": "Cannot transition: 2 tasks still pending",
    "blockers": [
      {"task_id": "task-007", "title": "Add authentication tests"},
      {"task_id": "task-008", "title": "Update API documentation"}
    ]
  }
}
```

#### Artifact Management

```
GET /projects/{project}/sdlc/features/{slug}/artifacts/{type}
```
Get artifact content.

```json
{
  "artifact": {
    "type": "spec",
    "status": "approved",
    "path": ".sdlc/features/auth/spec.md",
    "content": "# Feature: User Authentication...",
    "approved_by": "user",
    "approved_at": "2024-01-10T14:00:00Z"
  }
}
```

---

```
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}
```
Create or update an artifact.

Request:
```json
{
  "content": "# Feature: User Authentication\n\n## Overview\n...",
  "auto_commit": true,
  "commit_message": "docs(auth): update specification"
}
```

---

```
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}/approve
```
Approve an artifact.

Request:
```json
{
  "approved_by": "user",
  "comments": "Looks good, approved for implementation"
}
```

---

```
POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}/reject
```
Reject an artifact with feedback.

Request:
```json
{
  "rejected_by": "user",
  "reason": "Missing acceptance criteria for error cases",
  "required_changes": [
    "Add AC for invalid email format",
    "Add AC for password requirements"
  ]
}
```

#### Task Management

```
GET /projects/{project}/sdlc/features/{slug}/tasks
```
List all tasks for a feature.

```json
{
  "tasks": [
    {
      "id": "task-001",
      "title": "Create User domain model",
      "status": "complete",
      "completed_at": "2024-01-12T10:00:00Z"
    },
    {
      "id": "task-004",
      "title": "Implement JWT token validation",
      "status": "in_progress",
      "started_at": "2024-01-12T15:00:00Z",
      "spec": "Implement JWT token validation middleware..."
    },
    {
      "id": "task-005",
      "title": "Implement login endpoint",
      "status": "pending",
      "depends_on": ["task-003", "task-004"]
    }
  ]
}
```

---

```
POST /projects/{project}/sdlc/features/{slug}/tasks/{task_id}/start
POST /projects/{project}/sdlc/features/{slug}/tasks/{task_id}/complete
POST /projects/{project}/sdlc/features/{slug}/tasks/{task_id}/block
```
Update task status.

#### Pattern Management

```
GET /projects/{project}/sdlc/patterns
GET /projects/{project}/sdlc/patterns/{slug}
POST /projects/{project}/sdlc/patterns
POST /projects/{project}/sdlc/patterns/{slug}/violations
POST /projects/{project}/sdlc/patterns/{slug}/adopt
```

#### Git Operations

```
POST /projects/{project}/sdlc/commit
```
Commit current SDLC changes.

Request:
```json
{
  "message": "docs(auth): complete task-004 specification",
  "files": [".sdlc/features/auth/tasks.md"]
}
```

---

```
POST /projects/{project}/sdlc/branches
```
Create a feature branch.

Request:
```json
{
  "feature": "auth",
  "base": "main"
}
```

---

```
POST /projects/{project}/sdlc/branches/{branch}/sync
```
Sync feature branch with main.

---

```
POST /projects/{project}/sdlc/merge
```
Merge a completed feature.

Request:
```json
{
  "feature": "auth",
  "strategy": "squash",
  "delete_branch": true
}
```

### Classifier Rule → API Mapping

Every classifier rule has a corresponding API interaction:

| Rule ID | Action | API Endpoint | Method |
|---------|--------|--------------|--------|
| `needs-spec` | CREATE_SPEC | `/sdlc/execute` | POST |
| `spec-needs-approval` | AWAIT_APPROVAL | `/sdlc/features/{slug}/artifacts/spec/approve` | POST |
| `needs-design` | CREATE_DESIGN | `/sdlc/execute` | POST |
| `design-decision-needed` | ANSWER_QUESTION | `/sdlc/resolve` | POST |
| `needs-tasks` | CREATE_TASKS | `/sdlc/execute` | POST |
| `needs-qa-plan` | CREATE_QA_PLAN | `/sdlc/execute` | POST |
| `needs-branch` | CREATE_BRANCH | `/sdlc/branches` | POST |
| `blocked-dependency` | BLOCKED | `/sdlc/blocked` | GET (info only) |
| `implement-next-task` | IMPLEMENT_TASK | `/sdlc/execute` | POST |
| `implementation-complete` | TRANSITION | `/sdlc/features/{slug}/transition` | POST |
| `needs-review` | REVIEW_CODE | `/sdlc/execute` | POST |
| `review-has-issues` | FIX_ISSUES | `/sdlc/execute` | POST |
| `review-passed` | TRANSITION | `/sdlc/features/{slug}/transition` | POST |
| `needs-audit` | AUDIT_CODE | `/sdlc/execute` | POST |
| `audit-has-issues` | REMEDIATE | `/sdlc/execute` | POST |
| `needs-qa` | RUN_QA | `/sdlc/execute` | POST |
| `qa-has-failures` | FIX_FAILURES | `/sdlc/execute` | POST |
| `needs-merge` | MERGE | `/sdlc/merge` | POST |

### Blocking Resolution Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Blocking Resolution Flow                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. GET /sdlc/blocked                                                       │
│     ↓                                                                       │
│     Returns: {                                                              │
│       "blocked_reason": "Design decision required",                         │
│       "question": "Which auth provider?",                                   │
│       "options": ["jwt", "oauth", "session"],                              │
│       "answer_path": ".sdlc/features/auth/design.md",                      │
│       "resolve_url": "/sdlc/features/auth/resolve"                         │
│     }                                                                       │
│                                                                             │
│  2. POST /sdlc/features/auth/resolve                                        │
│     Body: {                                                                 │
│       "question_id": "auth-provider",                                       │
│       "answer": "jwt",                                                      │
│       "rationale": "Stateless, works well with microservices"              │
│     }                                                                       │
│     ↓                                                                       │
│     System: Writes answer to design.md                                      │
│                                                                             │
│  3. POST /sdlc/commit                                                       │
│     Body: { "message": "docs(auth): decide on JWT provider" }              │
│     ↓                                                                       │
│     System: Commits the change                                              │
│                                                                             │
│  4. GET /sdlc/next?feature=auth                                            │
│     ↓                                                                       │
│     Returns: Next action (no longer blocked)                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Driver Loop (External Orchestrator)

```python
# Example driver that uses the API
import requests

BASE = "https://rdev.example.com/projects/my-project"

def drive_feature(feature_slug):
    while True:
        # 1. Check for blockers
        blocked = requests.get(f"{BASE}/sdlc/blocked").json()
        feature_blockers = [b for b in blocked["blocked"] if b["slug"] == feature_slug]

        if feature_blockers:
            blocker = feature_blockers[0]
            if blocker["resolution"]["action"] == "ANSWER_QUESTION":
                # Present to user, get answer
                answer = prompt_user(blocker["resolution"]["question"],
                                    blocker["resolution"]["options"])
                # Resolve it
                requests.post(blocker["resolution"]["resolve_url"], json={
                    "answer": answer,
                    "auto_commit": True
                })
                continue
            elif blocker["resolution"]["action"] == "APPROVE_ARTIFACT":
                # Show artifact, get approval
                artifact = requests.get(f"{BASE}/sdlc/features/{feature_slug}/artifacts/{blocker['artifact']}").json()
                if prompt_user_approval(artifact["content"]):
                    requests.post(blocker["resolution"]["resolve_url"], json={
                        "approved_by": "user"
                    })
                continue
            else:
                print(f"Blocked: {blocker['blocked_reason']}")
                break

        # 2. Get next action
        next_action = requests.get(f"{BASE}/sdlc/next?feature={feature_slug}").json()

        if next_action["classification"]["action"] == "IDLE":
            print("Feature complete!")
            break

        # 3. Execute it
        result = requests.post(f"{BASE}/sdlc/execute", json={
            "feature": feature_slug,
            "action": next_action["classification"]["action"],
            "auto_commit": True
        }).json()

        print(f"Executed: {result['execution']['action']}")
```

## Implementation Phases

### Phase 1: Core API Endpoints
1. `/sdlc/state` - GET current state
2. `/sdlc/features` - CRUD features
3. `/sdlc/features/{slug}/artifacts` - CRUD artifacts
4. `/sdlc/commit` - Commit changes

### Phase 2: Classifier & Execution
1. `/sdlc/next` - Run classifier
2. `/sdlc/execute` - Execute actions
3. `/sdlc/blocked` - List blockers
4. `/sdlc/resolve` - Resolve blockers

### Phase 3: Git Integration
1. `/sdlc/branches` - Branch management
2. `/sdlc/merge` - Merge features
3. Branch protection integration

### Phase 4: Task Execution
1. Claude command integration
2. Task status tracking
3. File modification tracking

### Phase 5: Full Workflow
1. Review/Audit/QA flows
2. Pattern management
3. Metrics and reporting

---

## Success Criteria

1. **Deterministic:** Same state always produces same next action
2. **Auditable:** Every action recorded with timestamp and actor
3. **Recoverable:** Can rollback any phase, can resume from any state
4. **Complete:** No work can be "lost" - everything has a place
5. **Enforceable:** Cannot merge without completing all gates
6. **Adaptive:** Rules can be customized per project
7. **Observable:** Current state always queryable
8. **Integrated:** Works seamlessly with Claude commands

---

## Appendix: File Templates

### .sdlc/config.yaml

```yaml
version: 1
project:
  name: "{{PROJECT_NAME}}"
  type: "composable-monorepo"

branches:
  main: "main"
  feature_prefix: "feature/"

phases:
  enabled:
    - draft
    - specified
    - planned
    - ready
    - implementation
    - review
    - audit
    - qa
    - merge
    - released

  required_artifacts:
    specified: ["spec"]
    planned: ["spec", "design", "tasks", "qa_plan"]
    review: ["review"]
    audit: ["audit"]
    qa: ["qa_results"]

compliance:
  require_approvals: true
  require_branch: true
  require_qa: true

patterns:
  auto_enforce:
    - error-handling
    - logging-standards
```

### .sdlc/state.yaml (Initial)

```yaml
version: 1
project:
  name: "{{PROJECT_NAME}}"
  current_roadmap: null

active_work:
  features: []
  patterns: []
  audits: []

blocked: []

last_updated: null
last_action: null
last_actor: null

history: []
```
