jordan 62460bf098 feat: complete template upgrade - chassis framework, UI library, auth, app-nextjs, OpenAPI, and cookbook

Weeks 1-7 of the template upgrade plan:
- pkg/api: typed HTTPError with sentinels, Wrap/WrapMiddleware, Bind, health probes, OpenAPI schema/param builders
- skeleton/packages: ui (design tokens, components), layout (DashboardShell), auth (AuthProvider, ProtectedRoute), api-client
- skeleton/pkg: httperror, app/handler, app/bind, app/health, auth (JWT/API key middleware)
- components/app-nextjs: Next.js 14 App Router template with dashboard, server actions, auth
- cookbooks/feature-development.md with test and validation scripts
- Handler tests for components, project management, and woodpecker webhook
- 3 rounds of code review fixes applied

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-02 00:46:51 -07:00

67 KiB

Raw Blame History

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:

Every command produces a concrete artifact at a deterministic location
Git is the source of truth for all SDLC state
A classifier engine recursively determines the next required action
All work happens on branches until verified and approved
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

# .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)

# .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)

# 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

# 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

# ============================================
# 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

$ 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:

Read context from SDLC structure
Produce a concrete artifact
Write artifact to the correct location
Update manifest/state
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)

---
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)

---
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)

---
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)

---
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: [ ]

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)

---
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:

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:

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

4. Handler Error Responses

Use appropriate response helpers:

// ✓ 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

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

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

Detection Rules

// 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`

---
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

Parse the classifier output
If action is AWAIT_APPROVAL:
- Show what needs approval
- Ask user to approve/reject
- Record decision with sdlc artifact approve/reject
If action is BLOCKED:
- Show the blocker
- Ask user how to resolve
If action is a command:
- Show the recommended command
- Ask user: "Execute this? (y/n)"
- If yes, execute and verify output
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

## 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:

# .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:

# .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:

# 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.

{
  "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.

{
  "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.

{
  "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:

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

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

{
  "to_phase": "review",
  "force": false
}

Response:

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

Or if validation fails:

{
  "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.

{
  "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:

{
  "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:

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

POST /projects/{project}/sdlc/features/{slug}/artifacts/{type}/reject

Reject an artifact with feedback.

Request:

{
  "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.

{
  "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:

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

POST /projects/{project}/sdlc/branches

Create a feature branch.

Request:

{
  "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:

{
  "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)

# 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

/sdlc/state - GET current state
/sdlc/features - CRUD features
/sdlc/features/{slug}/artifacts - CRUD artifacts
/sdlc/commit - Commit changes

Phase 2: Classifier & Execution

/sdlc/next - Run classifier
/sdlc/execute - Execute actions
/sdlc/blocked - List blockers
/sdlc/resolve - Resolve blockers

Phase 3: Git Integration

/sdlc/branches - Branch management
/sdlc/merge - Merge features
Branch protection integration

Phase 4: Task Execution

Claude command integration
Task status tracking
File modification tracking

Phase 5: Full Workflow

Review/Audit/QA flows
Pattern management
Metrics and reporting

Success Criteria

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

Appendix: File Templates

.sdlc/config.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)

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: []

67 KiB Raw Blame History

SDLC Orchestration System Specification

Overview

Architecture

Git Structure (Source of Truth)

State Machine

Global States

Feature Lifecycle Phases

Feature Manifest (State Tracking)

Classifier Engine

Classifier Interface

Classification Rules (Priority Order)

Classifier Output Format

SDLC CLI Tool

Command Reference

CLI Output Format

Command Specifications

Command Catalog

Phase: Planning

Phase: Implementation

Phase: Quality

Phase: Release

Patterns

Orchestration

Document Specifications

spec.md (Feature Specification)

tasks.md (Task Breakdown)

qa-plan.md (QA Verification Plan)

review.md (Code Review Findings)

WARNING-001: Inconsistent error handling in login handler

WARNING-002: Missing table-driven tests for token validation

WARNING-003: Hardcoded token expiration

SUGGESTION-001: Consider extracting JWT config

SUGGESTION-002: Add structured logging for auth events

What's Good

pattern.md (Pattern Specification)

2. Sentinel Errors

3. Error Checking

4. Handler Error Responses

5. Never Swallow Errors

Detection Rules

Adoption Status

Known Violations

Claude Command: /next

Output Format

Compliance Gates

Metrics

Rollback Support

rdev API Surface

Core Principle

API Endpoints

State & Classification

Execution

Feature Management

Artifact Management

Task Management

Pattern Management

Git Operations

Classifier Rule → API Mapping

Blocking Resolution Flow

Driver Loop (External Orchestrator)

Implementation Phases

Phase 1: Core API Endpoints

Phase 2: Classifier & Execution

Phase 3: Git Integration

Phase 4: Task Execution

Phase 5: Full Workflow

Success Criteria

Appendix: File Templates

.sdlc/config.yaml

.sdlc/state.yaml (Initial)

67 KiB

Raw Blame History

Claude Command: `/next`