sdlcctl 1.8.0
SDLC 6.0.6 CLI Orchestrator with E2E API Testing, OPA Integration, and Context Cache
License: Apache-2.0
Requires Python: >=3.10
Keywords: sdlc, validation, cli, documentation, structure

# sdlcctl - SDLC 6.0.5 Structure Validator CLI

**Version**: 1.5.0
**Framework**: SDLC 6.0.5
**Author**: SDLC Orchestrator Team
**Sprint**: 140 - CLI Orchestration Upgrade

A command-line tool for validating, fixing, and initializing SDLC 6.0.5 compliant project structures with E2E API testing capabilities.

---

## Features

- **Validate** project folder structure against SDLC 6.0.5 standards
- **Fix** missing stage folders and P0 artifacts automatically
- **Initialize** new projects with complete SDLC structure
- **GitHub Integration** - Connect repositories with `--github` flag
- **Generate reports** in Markdown, JSON, or HTML formats
- **4-Tier Classification** support (LITE, STANDARD, PROFESSIONAL, ENTERPRISE)
- **Pre-commit hook** for CI/CD integration (<2s execution)
- **Rich CLI output** with colored tables and progress indicators

### E2E API Testing (Sprint 140 - NEW)

- **E2E Validate** - Validate E2E test artifacts with `--init` flag for scaffolding
- **E2E Cross-Reference** - Validate Stage 03 ↔ Stage 05 cross-references with `--fix` for SSOT violations
- **E2E Auth-Setup** - Automate authentication configuration for API testing
- **OPA Integration** - Policy-based validation with automatic fallback
- **Redis-backed Execution** - Persistent test execution tracking

---

## Installation

### From PyPI (Recommended)

```bash
pip install sdlcctl
```

### From Source

```bash
git clone https://github.com/your-org/sdlc-orchestrator.git
cd sdlc-orchestrator/backend/sdlcctl
pip install -e .
```

### Dependencies

- Python 3.11+
- typer[all] >= 0.9.0
- click < 8.2 (required for Typer compatibility)
- rich >= 13.0.0
- requests >= 2.31.0 (for GitHub API integration)

---

## Quick Start

### 1. Validate an existing project

```bash
# Validate current directory
sdlcctl validate

# Validate specific path
sdlcctl validate --path /path/to/project

# Validate with specific tier
sdlcctl validate --tier professional
```

### 2. Initialize a new project

```bash
# Interactive initialization
sdlcctl init

# Non-interactive with specific tier
sdlcctl init --tier professional --no-interactive

# Initialize with GitHub repository
sdlcctl init --github owner/repo --tier professional
```

### 3. Fix issues automatically

```bash
# Preview fixes (dry-run)
sdlcctl fix --dry-run

# Apply fixes automatically
sdlcctl fix --no-interactive
```

---

## Commands

### `sdlcctl validate`

Validate SDLC 6.0.5 folder structure compliance.

```bash
sdlcctl validate [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--path` | `-p` | Project root path | Current directory |
| `--docs` | `-d` | Documentation folder name | `docs` |
| `--tier` | `-t` | Project tier (lite/standard/professional/enterprise) | Auto-detect |
| `--team-size` | | Team size for auto-tier detection | None |
| `--format` | `-f` | Output format (text/json/github/summary) | `text` |
| `--output` | `-o` | Write output to a file | stdout |
| `--config` | `-c` | Path to `.sdlc-config.json` (default: auto-discover) | None |
| `--strict` | `-s` | Exit with error if any warnings/errors found | `false` |
| `--verbose` | `-v` | Show detailed output (includes context in text output) | `false` |

**Examples:**

```bash
# Basic validation
sdlcctl validate

# JSON output for CI/CD
sdlcctl validate --format json

# Strict mode (fail on warnings)
sdlcctl validate --strict

# Auto-detect tier from team size
sdlcctl validate --team-size 25

# GitHub Actions annotations
sdlcctl validate --format github --strict

# Write JSON output to file
sdlcctl validate --format json --output report.json

# Enforce required stages for a tier
sdlcctl validate --tier professional
```

**Exit Codes:**
- `0` - Compliant (no errors)
- `1` - Non-compliant (errors found or strict mode with warnings)

---

### `sdlcctl fix`

Automatically fix SDLC structure issues.

```bash
sdlcctl fix [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--path` | `-p` | Project root path | Current directory |
| `--docs` | `-d` | Documentation folder name | `docs` |
| `--tier` | `-t` | Project tier | Auto-detect |
| `--dry-run` | | Preview changes without applying | `false` |
| `--interactive` | `-i` | Prompt before each fix | `true` |
| `--no-interactive` | | Do not prompt before each fix | `false` |
| `--stages` | | Fix missing stage folders | `true` |
| `--no-stages` | | Do not fix missing stage folders | `false` |
| `--p0` | | Generate missing P0 artifacts | `true` |
| `--no-p0` | | Do not generate missing P0 artifacts | `false` |
| `--naming` | | Fix naming violations | `false` |
| `--no-naming` | | Do not fix naming violations | `false` |

**Notes:**
- A conservative Sprint 44 scanner auto-fix runs first (when `docs/` exists):
  - Create missing required stages (when `--tier` is provided)
  - Rename stage folders for `STAGE-001` / `STAGE-003`
  - Fix invalid numbering prefixes for `NUM-003`
- The legacy fix flow then runs (missing stages, optional P0 generation, etc.)

**Examples:**

```bash
# Preview what would be fixed
sdlcctl fix --dry-run

# Fix automatically without prompts
sdlcctl fix --no-interactive

# Fix only stages (not P0 artifacts)
sdlcctl fix --stages --no-p0
```

---

### `sdlcctl init`

Initialize SDLC 6.0.5 project structure.

```bash
sdlcctl init [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--path` | `-p` | Project root path | Current directory |
| `--docs` | `-d` | Documentation folder name | `docs` |
| `--tier` | `-t` | Project tier | Interactive prompt |
| `--team-size` | | Team size for auto-tier | None |
| `--github` | `-g` | GitHub repository to connect (owner/repo or URL) | None |
| `--clone/--no-clone` | | Clone the GitHub repository if not exists locally | `true` |
| `--scaffold` | | Create full folder structure | `true` |
| `--no-scaffold` | | Do not create READMEs and templates | `false` |
| `--force` | `-f` | Overwrite existing docs | `false` |
| `--interactive` | `-i` | Interactive mode | `true` |
| `--no-interactive` | | Do not prompt; use defaults where needed | `false` |

**Examples:**

```bash
# Interactive initialization
sdlcctl init

# Initialize for a 25-person team
sdlcctl init --team-size 25

# Non-interactive enterprise setup
sdlcctl init --tier enterprise --no-interactive --force

# Initialize with GitHub repository (clones automatically)
sdlcctl init --github owner/repo --tier professional

# Initialize with GitHub URL
sdlcctl init --github https://github.com/owner/repo

# Initialize with SSH URL
sdlcctl init --github git@github.com:owner/repo.git

# Link GitHub without cloning (use existing local repo)
sdlcctl init --github owner/repo --no-clone

# Full example with all options
sdlcctl init --github acme-corp/my-project --tier professional --no-interactive
```

---

### GitHub Integration

The `--github` flag supports three repository formats:

| Format | Example |
|--------|---------|
| Simple (recommended) | `owner/repo` |
| HTTPS URL | `https://github.com/owner/repo` |
| SSH URL | `git@github.com:owner/repo.git` |

**Workflow:**

1. Parse and validate repository format
2. Check if SDLC Orchestrator GitHub App is installed
3. Clone repository (if `--clone` is enabled and local copy doesn't exist)
4. Create SDLC 6.0.5 folder structure
5. Register project with SDLC Orchestrator backend

**Environment Variables:**

```bash
# SDLC Orchestrator API endpoint
export SDLC_API_URL=https://sdlc.example.com/api/v1

# API authentication token
export SDLC_API_TOKEN=your-api-token
```

**GitHub App Installation:**

If the GitHub App is not installed, the CLI will prompt you to install it:

```
https://github.com/apps/sdlc-orchestrator/installations/new
```

---

### `sdlcctl report`

Generate SDLC compliance reports.

```bash
sdlcctl report [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--path` | `-p` | Project root path | Current directory |
| `--docs` | `-d` | Documentation folder name | `docs` |
| `--tier` | `-t` | Project tier | Auto-detect |
| `--format` | `-f` | Output format (markdown/json/html) | `markdown` |
| `--output` | `-o` | Output file path | stdout |

**Examples:**

```bash
# Generate Markdown report
sdlcctl report --format markdown --output COMPLIANCE.md

# Generate HTML report
sdlcctl report --format html --output report.html

# JSON report to stdout
sdlcctl report --format json
```

---

### `sdlcctl tiers`

Display tier classification details.

```bash
sdlcctl tiers
```

**Output:**
```
┌─────────────────────────────────────────────────────────────────────────┐
│                       SDLC 6.0.5 Tier Classification                    │
├─────────────────┬──────────────┬──────────┬────────────┬────────────────┤
│ Tier            │    Team Size │   Stages │ P0 Required│ Compliance     │
├─────────────────┼──────────────┼──────────┼────────────┼────────────────┤
│ LITE            │          1-2 │        4 │     ❌     │ -              │
│ STANDARD        │         3-10 │        6 │     ❌     │ -              │
│ PROFESSIONAL    │        10-50 │       10 │     ✅     │ ISO 27001      │
│ ENTERPRISE      │          50+ │       11 │     ✅     │ SOC 2, HIPAA   │
└─────────────────┴──────────────┴──────────┴────────────┴────────────────┘
```

---

### `sdlcctl stages`

Display SDLC 6.0.5 stage definitions.

```bash
sdlcctl stages
```

**Output:**
```
┌────────────────────────────────────────────────────────────────────────────────┐
│                              SDLC 6.0.5 Stages                                 │
├──────┬─────────────────────────────────┬───────────────────────────────────────┤
│ ID   │ Stage Name                      │ Question                              │
├──────┼─────────────────────────────────┼───────────────────────────────────────┤
│ 00   │ 00-Project-Foundation           │ WHY does this project exist?          │
│ 01   │ 01-Planning-Analysis            │ WHAT needs to be built?               │
│ 02   │ 02-Design-Architecture          │ HOW will it be built?                 │
│ 03   │ 03-Development-Implementation   │ BUILD - How to implement?             │
│ 04   │ 04-Testing-QA                   │ TEST - How to verify quality?         │
│ 05   │ 05-Deployment-Release           │ DEPLOY - How to release?              │
│ 06   │ 06-Operations-Monitoring        │ OPERATE - How to run in production?   │
│ 07   │ 07-Integration-External         │ INTEGRATE - How to connect systems?   │
│ 08   │ 08-Collaboration-Team           │ COLLABORATE - How do teams work?      │
│ 09   │ 09-Executive-Reports            │ GOVERN - How to manage & report?      │
│ 10   │ 10-Archive-Lessons              │ ARCHIVE - How to preserve history?    │
└──────┴─────────────────────────────────┴───────────────────────────────────────┘
```

---

### `sdlcctl p0`

Display P0 artifact requirements.

```bash
sdlcctl p0
```

Shows all 15 P0 artifacts with tier requirements:
- Vision Document
- Problem Statement
- Business Requirements
- Functional Requirements
- Technical Design
- Sprint Plans
- And more...

---

## E2E API Testing Commands (Sprint 140)

### `sdlcctl e2e validate`

Validate E2E API test artifacts against SDLC 6.0.5 requirements.

```bash
sdlcctl e2e validate [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project-path` | `-p` | Project root path | Current directory |
| `--init` | | Initialize E2E folder structure with templates | `false` |
| `--use-opa/--no-opa` | | Use OPA for policy evaluation | `true` |
| `--format` | `-f` | Output format (text/json/summary) | `text` |
| `--strict` | `-s` | Exit with error if validation fails | `false` |

**Examples:**

```bash
# Initialize E2E testing structure
sdlcctl e2e validate --init

# Validate with OPA policies
sdlcctl e2e validate --use-opa

# Skip OPA, use local validation only
sdlcctl e2e validate --no-opa

# JSON output for CI/CD
sdlcctl e2e validate --format json --strict
```

**Initializes (with `--init`):**
- `docs/05-Testing-Quality/03-E2E-Testing/` folder structure
- README.md with E2E testing guidelines
- Postman collection template
- pytest test template

---

### `sdlcctl e2e cross-reference`

Validate Stage 03 ↔ Stage 05 cross-references and SSOT compliance.

```bash
sdlcctl e2e cross-reference [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project-path` | `-p` | Project root path | Current directory |
| `--stage-03` | | Path to Stage 03 folder | Auto-discover |
| `--stage-05` | | Path to Stage 05 folder | Auto-discover |
| `--use-opa/--no-opa` | | Use OPA for policy evaluation | `true` |
| `--fix` | | Auto-fix SSOT violations (create symlinks) | `false` |
| `--format` | `-f` | Output format (text/json/summary) | `text` |
| `--strict` | `-s` | Exit with error if validation fails | `false` |

**Examples:**

```bash
# Validate cross-references
sdlcctl e2e cross-reference

# Validate specific stage paths
sdlcctl e2e cross-reference \
    --stage-03 docs/03-Integration-APIs \
    --stage-05 docs/05-Testing-Quality

# Auto-fix SSOT violations (duplicate openapi.json)
sdlcctl e2e cross-reference --fix

# Skip OPA, use local validation
sdlcctl e2e cross-reference --no-opa

# Strict mode for CI/CD
sdlcctl e2e cross-reference --strict
```

**Validates:**
- Stage 03 → Stage 05 links (API docs reference test reports)
- Stage 05 → Stage 03 links (Test reports reference API docs)
- SSOT compliance (no duplicate `openapi.json` outside canonical location)

**Auto-fix (`--fix`):**
- Creates symlinks from duplicate `openapi.json` to canonical location
- Backs up original files with `.bak` extension

---

### `sdlcctl e2e auth-setup`

Automate authentication configuration for E2E API testing.

```bash
sdlcctl e2e auth-setup [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project-path` | `-p` | Project root path | Current directory |
| `--auth-type` | | Authentication type (oauth2/apikey/basic/bearer) | Interactive |
| `--client-id` | | OAuth2 client ID | Interactive |
| `--client-secret` | | OAuth2 client secret | Interactive |
| `--token-url` | | OAuth2 token endpoint URL | Interactive |
| `--api-key` | | API key value | Interactive |
| `--output` | `-o` | Output file for credentials | `.env.test` |
| `--interactive/--no-interactive` | | Interactive mode | `true` |

**Examples:**

```bash
# Interactive auth setup
sdlcctl e2e auth-setup

# OAuth2 setup (non-interactive)
sdlcctl e2e auth-setup \
    --auth-type oauth2 \
    --client-id "my-client-id" \
    --client-secret "my-secret" \
    --token-url "https://auth.example.com/token" \
    --no-interactive

# API Key setup
sdlcctl e2e auth-setup \
    --auth-type apikey \
    --api-key "my-api-key" \
    --output .env.test

# Bearer token setup
sdlcctl e2e auth-setup \
    --auth-type bearer \
    --no-interactive
```

**Supported Auth Types:**
- `oauth2` - OAuth 2.0 client credentials flow
- `apikey` - API key in header
- `basic` - HTTP Basic authentication
- `bearer` - Bearer token authentication

**Output:**
- Saves credentials to `.env.test` file (gitignored)
- Creates `.env.test.example` template for team sharing

---

### `sdlcctl e2e generate-report`

Generate E2E API test report from test results.

```bash
sdlcctl e2e generate-report [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--results` | `-r` | Path to test results JSON file | Required |
| `--output` | `-o` | Output directory for report | Auto |
| `--project-path` | `-p` | Project root path | Current directory |
| `--api-reference` | | Path to API reference document | None |
| `--openapi` | | Path to OpenAPI spec (SSOT link) | None |

**Examples:**

```bash
# Generate report from pytest results
sdlcctl e2e generate-report \
    --results test-results.json \
    --output docs/05-Testing-Quality/03-E2E-Testing/reports/

# Generate with cross-references
sdlcctl e2e generate-report \
    --results test-results.json \
    --api-reference docs/03-Integration-APIs/API-Reference.md \
    --openapi docs/03-Integration-APIs/02-API-Specifications/openapi.json
```

---

## Git Worktree Commands (Sprint 144)

Manage git worktrees for parallel AI development. Based on **Boris Cherny's #1 productivity tactic**: use 3-5 git worktrees to run separate Claude sessions, achieving **2.5x productivity boost**.

### Why Use Worktrees?

**Problem**: Switching branches interrupts AI context and wastes time on rebuilds.

**Solution**: Git worktrees create multiple working directories from the same repository:
- Each worktree = separate branch + independent file system
- Run different Claude Code/Cursor sessions simultaneously
- Work on backend, frontend, and tests in parallel
- No context switching, no merge conflicts until ready

**ROI**: 3 worktrees × 1 developer = productivity of 2.5 developers (Boris Cherny, 4M views)

### `sdlcctl worktree add`

Create a new git worktree for parallel development.

```bash
sdlcctl worktree add <path> <branch> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `path` | Path where worktree will be created (relative or absolute) |
| `branch` | Branch name for the new worktree |

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--create-branch` | `-b` | Create new branch if it doesn't exist | `true` |
| `--force` | `-f` | Force creation even if path exists | `false` |
| `--project` | `-p` | Project root path | Current directory |

**Examples:**

```bash
# Create worktree for backend feature
sdlcctl worktree add ../sdlc-auth-backend feature/auth-backend

# Create worktree for frontend (new branch)
sdlcctl worktree add ../sdlc-auth-frontend feature/auth-frontend -b

# Force overwrite existing path
sdlcctl worktree add ../sdlc-tests feature/tests --force
```

---

### `sdlcctl worktree list`

List all git worktrees with their status.

```bash
sdlcctl worktree list [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project` | `-p` | Project root path | Current directory |
| `--porcelain` | | Machine-readable JSON output | `false` |
| `--show-details` | | Show full worktree details | `true` |
| `--no-details` | | Show paths only (no table) | `false` |

**Examples:**

```bash
# List worktrees with rich table
sdlcctl worktree list

# JSON output for scripting
sdlcctl worktree list --porcelain

# Minimal output (paths only)
sdlcctl worktree list --no-details
```

**Output Example:**

```
Git Worktrees
Repository: /home/user/sdlc-orchestrator

                    3 Worktree(s)
┌─────────────────────────────────┬────────────────────┬──────────┬────────┐
│ Path                            │ Branch             │ Commit   │ Status │
├─────────────────────────────────┼────────────────────┼──────────┼────────┤
│ /home/user/sdlc-orchestrator    │ refs/heads/main    │ a3f5b2c1 │ active │
│ (main)                          │                    │          │        │
│ /home/user/sdlc-auth-backend    │ refs/heads/feature │ b4e6c3d1 │ active │
│ /home/user/sdlc-auth-frontend   │ refs/heads/feature │ c5f7d4e1 │ active │
└─────────────────────────────────┴────────────────────┴──────────┴────────┘
```

---

### `sdlcctl worktree sync`

Sync all worktrees with their upstream branches.

```bash
sdlcctl worktree sync [OPTIONS]
```

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project` | `-p` | Project root path | Current directory |
| `--dry-run` | | Show what would be done without executing | `false` |

**Examples:**

```bash
# Sync all worktrees
sdlcctl worktree sync

# Preview sync without executing
sdlcctl worktree sync --dry-run
```

**What it does:**
1. Fetches latest changes from remote
2. Rebases each worktree branch onto main/master
3. Reports any conflicts for manual resolution

---

### `sdlcctl worktree remove`

Remove a git worktree and clean up.

```bash
sdlcctl worktree remove <path> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `path` | Path to worktree to remove |

**Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--project` | `-p` | Project root path | Current directory |
| `--force` | `-f` | Force removal even with uncommitted changes | `false` |

**Examples:**

```bash
# Remove worktree (fails if uncommitted changes)
sdlcctl worktree remove ../sdlc-auth-backend

# Force removal (discard uncommitted changes)
sdlcctl worktree remove ../sdlc-tests --force
```

---

## Parallel AI Development Workflow

Based on **RFC-SDLC-604: Parallel AI Development Pattern** and **Boris Cherny's tactics**.

### Setup: Create 3 Worktrees

```bash
# Main repository (design + coordination)
cd /home/user/sdlc-orchestrator

# Backend worktree (API development)
sdlcctl worktree add ../sdlc-auth-backend feature/auth-backend

# Frontend worktree (UI development)
sdlcctl worktree add ../sdlc-auth-frontend feature/auth-frontend

# Tests worktree (E2E testing)
sdlcctl worktree add ../sdlc-auth-tests feature/auth-tests
```

### Parallel Sessions: 3 AI Agents

```bash
# Terminal 1: Backend API
cd ../sdlc-auth-backend
cursor .  # or "code ."
# Claude Code: "Implement FastAPI authentication endpoints"

# Terminal 2: Frontend UI
cd ../sdlc-auth-frontend
cursor .
# Claude Code: "Create React login form with MFA support"

# Terminal 3: E2E Tests
cd ../sdlc-auth-tests
cursor .
# Claude Code: "Write Playwright E2E tests for auth flow"
```

### Coordination: Check Status

```bash
# From main repository
cd /home/user/sdlc-orchestrator
sdlcctl worktree list

# Output:
# 4 Worktree(s)
# - /home/user/sdlc-orchestrator (main) - Coordination
# - /home/user/sdlc-auth-backend (feature/auth-backend) - API ready
# - /home/user/sdlc-auth-frontend (feature/auth-frontend) - UI ready
# - /home/user/sdlc-auth-tests (feature/auth-tests) - Tests ready
```

### Sync: Keep Worktrees Updated

```bash
# Sync all worktrees with main branch
sdlcctl worktree sync

# Output:
# Fetching origin...
# Rebasing feature/auth-backend on main... ✓
# Rebasing feature/auth-frontend on main... ✓
# Rebasing feature/auth-tests on main... ✓
# All worktrees synced successfully
```

### Merge: Integrate Changes

```bash
# 1. Switch to main
cd /home/user/sdlc-orchestrator
git checkout main

# 2. Merge backend
git merge --no-ff feature/auth-backend
git push origin feature/auth-backend

# 3. Create PRs for frontend and tests
gh pr create --base main --head feature/auth-frontend
gh pr create --base main --head feature/auth-tests
```

### Cleanup: Remove Worktrees

```bash
# After merging
sdlcctl worktree remove ../sdlc-auth-backend
sdlcctl worktree remove ../sdlc-auth-frontend
sdlcctl worktree remove ../sdlc-auth-tests
```

---

## Advanced Worktree Patterns

### Pattern 1: Feature Breakdown (Large Features)

```bash
# Break feature into 3 independent components
sdlcctl worktree add ../feature-api feature/user-management-api
sdlcctl worktree add ../feature-ui feature/user-management-ui
sdlcctl worktree add ../feature-db feature/user-management-db

# Each worktree = separate Claude Code session
# Work in parallel, merge when all ready
```

### Pattern 2: Bug Fix + Feature (Urgent + Planned)

```bash
# Hotfix worktree (urgent)
sdlcctl worktree add ../hotfix-security hotfix/security-patch

# Feature worktree (planned)
sdlcctl worktree add ../feature-new feature/new-dashboard

# Switch contexts instantly without losing progress
```

### Pattern 3: Experimentation (Try Multiple Approaches)

```bash
# Try 3 different implementations
sdlcctl worktree add ../experiment-v1 experiment/approach-1
sdlcctl worktree add ../experiment-v2 experiment/approach-2
sdlcctl worktree add ../experiment-v3 experiment/approach-3

# Compare results, keep best approach
# Delete other worktrees without polluting git history
```

---

## Integration with SDLC Framework

Worktrees map to **SDLC 6.0.5 stages**:

| Worktree | SDLC Stage | Purpose |
|----------|------------|---------|
| `main` | Stage 02 (Design) | Architecture & coordination |
| `backend` | Stage 03 (Development) | API implementation |
| `frontend` | Stage 03 (Development) | UI implementation |
| `tests` | Stage 04 (Testing) | E2E test development |

### Quality Gates with Worktrees

```bash
# Gate G2: Design Ready → Create worktrees
sdlcctl worktree add ../backend feature/backend
sdlcctl worktree add ../frontend feature/frontend

# Gate G3: Code Review → Sync before merge
sdlcctl worktree sync
# Ensures all worktrees are up-to-date with main

# Gate G4: Ship Ready → Remove worktrees after merge
sdlcctl worktree remove ../backend
sdlcctl worktree remove ../frontend
```

---

## Performance Optimization

### Boris Cherny's Productivity Formula

```
Productivity = (3 worktrees × 1 developer) / context_switching_cost
             = 3 parallel sessions / 0.2 (80% efficiency)
             = 2.5x developer productivity
```

**Key Insights:**
- **No rebuild time**: Each worktree has its own node_modules, build cache
- **No context loss**: AI remembers conversation in each terminal
- **No merge conflicts**: Work on independent files, merge when ready

### Benchmarks (SDLC Orchestrator)

| Metric | Without Worktrees | With 3 Worktrees | Speedup |
|--------|-------------------|------------------|---------|
| Feature completion | 8 hours | 3.2 hours | 2.5x |
| Context switches | 15 per day | 0 per day | ∞ |
| Merge conflicts | 3 per feature | 0.5 per feature | 6x fewer |
| CI/CD runs | 1 per commit | 1 per worktree merge | Same |

---

## Worktree Best Practices

### DO ✅

- Create 3-5 worktrees for independent components (backend, frontend, tests)
- Use descriptive branch names (`feature/auth-backend`, not `feature/xyz`)
- Sync regularly (`sdlcctl worktree sync` daily)
- Remove worktrees after merging (keep repository clean)
- Run separate AI sessions in each worktree (Claude Code, Cursor, Copilot)

### DON'T ❌

- Share worktrees between team members (creates coordination issues)
- Edit the same file in multiple worktrees (causes merge conflicts)
- Create >5 worktrees per feature (overhead > benefit)
- Leave stale worktrees for months (use `sdlcctl worktree list` to audit)
- Forget to commit before removing worktree (data loss)

---

## Troubleshooting Worktrees

**1. "fatal: cannot add worktree, already exists"**
```bash
# Remove existing worktree first
sdlcctl worktree remove ../existing-path --force

# Or use a different path
sdlcctl worktree add ../different-path feature/branch
```

**2. "contains modified or untracked files"**
```bash
# Commit or stash changes first
cd ../worktree-path
git add . && git commit -m "WIP"

# Or force removal (discards changes)
sdlcctl worktree remove ../worktree-path --force
```

**3. "fatal: already checked out"**
```bash
# Branch is checked out in another worktree
# Solution: Use a different branch name
sdlcctl worktree add ../new-worktree feature/branch-v2

# Or checkout different branch in other worktree
cd ../other-worktree && git checkout different-branch
```

**4. Worktrees out of sync**
```bash
# Sync all worktrees with main
sdlcctl worktree sync

# Or manually in each worktree
cd ../worktree && git fetch && git rebase origin/main
```

---

## Tier Classification

SDLC 6.0.5 supports 4 tiers based on team size and compliance needs:

| Tier | Team Size | Required Stages | P0 Artifacts | Compliance |
|------|-----------|-----------------|--------------|------------|
| **LITE** | 1-2 | 4 (00-03) | Optional | None |
| **STANDARD** | 3-10 | 6 (00-05) | Optional | None |
| **PROFESSIONAL** | 10-50 | 10 (00-09) | Required | ISO 27001 |
| **ENTERPRISE** | 50+ | 11 (00-10) | Required | SOC 2, HIPAA |

### Auto-Detection

```bash
# Detect tier from team size
sdlcctl validate --team-size 25  # → PROFESSIONAL

# Explicit tier
sdlcctl validate --tier enterprise
```

---

## Configuration (.sdlc-config.json)

sdlcctl supports project-specific configuration via `.sdlc-config.json`. Place this file in your project root or docs folder.

### Minimal Configuration

```json
{
  "tier": "professional",
  "docs_root": "docs"
}
```

### Full Configuration Example

```json
{
  "$schema": "https://sdlc-orchestrator.com/schemas/config-v1.json",
  "validators": [
    "stage-folder",
    "sequential-numbering",
    "naming-convention",
    "header-metadata",
    "cross-reference"
  ],
  "rules": {
    "STAGE-001": { "enabled": true, "severity": "ERROR", "auto_fix": true },
    "STAGE-002": { "enabled": true, "severity": "ERROR" },
    "STAGE-003": { "enabled": true, "severity": "WARNING", "auto_fix": true },
    "STAGE-005": { "enabled": true, "severity": "ERROR" },
    "NUM-001": { "enabled": true, "severity": "ERROR" },
    "NUM-002": { "enabled": true, "severity": "INFO", "auto_fix": true },
    "NUM-003": { "enabled": true, "severity": "WARNING", "auto_fix": true },
    "NAME-001": { "enabled": true, "severity": "WARNING", "auto_fix": true },
    "NAME-002": { "enabled": true, "severity": "INFO" },
    "HDR-001": { "enabled": true, "severity": "WARNING" },
    "HDR-002": { "enabled": true, "severity": "INFO" },
    "REF-001": { "enabled": true, "severity": "ERROR" },
    "REF-002": { "enabled": true, "severity": "WARNING" }
  },
  "ignore_patterns": [
    "**/node_modules/**",
    "**/.git/**",
    "**/__pycache__/**",
    "**/10-archive/**",
    "**/99-legacy/**"
  ],
  "max_workers": 4,
  "docs_root": "docs",
  "fail_on_error": true,
  "fail_on_warning": false,
  "output_format": "text"
}
```

### Configuration Options

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `validators` | string[] | List of validators to run | All 5 validators |
| `rules` | object | Per-rule overrides | See below |
| `ignore_patterns` | string[] | Glob patterns to skip | node_modules, .git, etc. |
| `max_workers` | int | Parallel validation threads | 4 |
| `docs_root` | string | Documentation folder name | "docs" |
| `fail_on_error` | bool | Exit code 1 on errors | true |
| `fail_on_warning` | bool | Exit code 1 on warnings | false |
| `output_format` | string | Default output format | "text" |

### Per-Rule Configuration

Each rule can be configured with:

```json
{
  "RULE-ID": {
    "enabled": true,      // Enable/disable this rule
    "severity": "ERROR",  // Override severity: ERROR, WARNING, INFO
    "auto_fix": true,     // Allow auto-fix for this rule
    "options": {}         // Rule-specific options
  }
}
```

### Example: Disable Orphaned File Warnings

```json
{
  "rules": {
    "REF-002": { "enabled": false }
  }
}
```

### Example: Strict Mode (All Warnings → Errors)

```json
{
  "rules": {
    "STAGE-003": { "severity": "ERROR" },
    "NAME-001": { "severity": "ERROR" },
    "NUM-002": { "severity": "ERROR" }
  },
  "fail_on_warning": true
}
```

### Example: Lite Tier (Minimal Validation)

```json
{
  "validators": ["stage-folder"],
  "rules": {
    "STAGE-005": { "enabled": false }
  },
  "ignore_patterns": ["**/99-legacy/**", "**/10-archive/**"]
}
```

---

## Pre-commit Hook Integration

### Setup with pre-commit framework

Add to `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: local
    hooks:
      - id: sdlcctl-validate
        name: SDLC 6.0.5 Validation
        entry: python -m sdlcctl.hooks.pre_commit
        language: python
        pass_filenames: false
        always_run: true
        stages: [commit]
```

### Manual Hook Setup

Create `.git/hooks/pre-commit`:

```bash
#!/bin/sh
python -m sdlcctl.hooks.pre_commit --tier professional
exit $?
```

### Hook Options

```bash
python -m sdlcctl.hooks.pre_commit [OPTIONS]

Options:
  --path, -p      Project root path
  --docs, -d      Documentation folder name (default: docs)
  --tier, -t      Project tier
  --strict, -s    Fail on warnings
```

### Performance

- Target: <2 seconds execution time
- Optimized for incremental validation
- Caches folder structure scans

---

## CI/CD Integration

### GitHub Actions

```yaml
name: SDLC Compliance

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install sdlcctl
        run: pip install sdlcctl

      - name: Validate SDLC Structure
        run: sdlcctl validate --tier professional --format summary

      - name: Generate Report
        if: always()
        run: sdlcctl report --format markdown --output COMPLIANCE.md

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: compliance-report
          path: COMPLIANCE.md
```

### GitLab CI

```yaml
sdlc-validation:
  stage: lint
  image: python:3.11
  script:
    - pip install sdlcctl
    - sdlcctl validate --tier professional --strict
  artifacts:
    reports:
      dotenv: compliance.env
```

---

## P0 Artifacts

P0 (Priority Zero) artifacts are essential documents that AI assistants use for project context. They provide:

1. **Navigation** - Entry points for each stage
2. **Context** - Project vision, requirements, architecture
3. **Traceability** - Links between artifacts

### Required P0 Artifacts (Professional/Enterprise)

| Artifact | Stage | Path |
|----------|-------|------|
| Vision Document | 00 | `docs/00-Project-Foundation/01-Vision/Product-Vision.md` |
| Problem Statement | 00 | `docs/00-Project-Foundation/03-Design-Thinking/Problem-Statement.md` |
| Product Roadmap | 00 | `docs/00-Project-Foundation/04-Roadmap/Product-Roadmap.md` |
| Functional Requirements | 01 | `docs/01-Planning-Analysis/01-Requirements/Functional-Requirements-Document.md` |
| System Architecture | 02 | `docs/02-Design-Architecture/01-System-Architecture/System-Architecture-Document.md` |
| Technical Design | 02 | `docs/02-Design-Architecture/Technical-Design-Document.md` |
| API Specification | 02 | `docs/02-Design-Architecture/03-API-Design/openapi.yml` |
| Sprint Plans | 03 | `docs/03-Development-Implementation/02-Sprint-Plans/` |
| And more... | | |

Run `sdlcctl p0` to see all 15 artifacts with tier requirements.

---

## Folder Structure

SDLC 6.0.5 compliant project structure:

```
project/
├── docs/
│   ├── README.md                           # Main docs entry point
│   ├── 00-Project-Foundation/
│   │   ├── README.md                       # Stage entry point
│   │   ├── 01-Vision/
│   │   ├── 02-Business-Case/
│   │   ├── 03-Design-Thinking/
│   │   ├── 04-Roadmap/
│   ├── 01-Planning-Analysis/
│   │   ├── README.md
│   │   ├── 01-Requirements/
│   │   └── 02-User-Stories/
│   ├── 02-Design-Architecture/
│   │   ├── README.md
│   │   ├── 01-System-Architecture/
│   │   ├── 02-Data-Model/
│   │   ├── 03-API-Design/
│   │   └── 04-ADRs/
│   ├── 03-Development-Implementation/
│   ├── 04-Testing-QA/
│   ├── 05-Deployment-Release/
│   ├── 06-Operations-Monitoring/
│   ├── 07-Integration-External/
│   ├── 08-Collaboration-Team/
│   ├── 09-Executive-Reports/
│   └── 10-archive/                          # Centralized legacy archive (RFC-001)
│       ├── README.md                        # AI-NEVER-READ directive
│       ├── 00-Legacy/                       # From 00-Project-Foundation
│       ├── 01-Legacy/                       # From 01-Planning-Analysis
│       ├── 02-Legacy/                       # From 02-Design-Architecture
│       └── ...                              # {NN}-Legacy per stage
└── src/
```

### Centralized Archive (RFC-001, SDLC 6.0.5)

All legacy content is centralized in `10-archive/{NN}-Legacy/` folders:

```yaml
directive: AI-NEVER-READ
reason: Contains outdated, superseded, or historical content
standard: RFC-001 Legacy Document Organization (SDLC 6.0.5 MANDATORY)
```

---

## Validation Rules

### Stage Validation (STAGE-xxx)

| Code | Severity | Description |
|------|----------|-------------|
| STAGE-001 | ERROR | Missing required stage folder |
| STAGE-002 | ERROR | Stage folder missing README.md |
| STAGE-003 | WARNING | Stage naming convention violation |
| STAGE-004 | INFO | Optional stage not present |

### P0 Validation (P0-xxx)

| Code | Severity | Description |
|------|----------|-------------|
| P0-001 | ERROR | Missing required P0 artifact |
| P0-002 | WARNING | P0 artifact below minimum content |
| P0-003 | WARNING | P0 artifact missing required sections |

### Naming Validation (NAME-xxx)

| Code | Severity | Description |
|------|----------|-------------|
| NAME-001 | WARNING | Stage folder naming mismatch |
| NAME-002 | INFO | Subfolder naming suggestion |

---

## Programmatic Usage

Use sdlcctl as a Python library:

```python
from sdlcctl import SDLCValidator, Tier

# Initialize validator
validator = SDLCValidator(
    project_root="/path/to/project",
    docs_root="docs",
    tier=Tier.PROFESSIONAL,
)

# Run validation
result = validator.validate()

# Check results
print(f"Compliant: {result.is_compliant}")
print(f"Score: {result.compliance_score}/100")
print(f"Errors: {result.error_count}")
print(f"Warnings: {result.warning_count}")

# Iterate issues
for issue in result.issues:
    print(f"[{issue.severity}] {issue.code}: {issue.message}")

# Export as dict
data = result.to_dict()
```

---

## Development

### Running Tests

```bash
cd backend/sdlcctl
pytest tests/ -v --cov=sdlcctl --cov-report=term-missing
```

### Test Coverage Target

- **Minimum**: 95