sdlcctl 1.7.0

SDLC 6.0.5 CLI Orchestrator with E2E API Testing and OPA Integration

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)

pip install sdlcctl

From Source

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

# 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

# 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

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

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:

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

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:

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

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:

# 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 [e-mail]: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	[e-mail]: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:

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

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:

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

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.

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.

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.

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

# 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

# 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

# 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

# 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

# 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

# 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

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

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

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

# 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

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

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

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

# 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

# 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

# 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

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

Full Configuration Example

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

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

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

Example: Strict Mode (All Warnings → Errors)

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

Example: Lite Tier (Minimal Validation)

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

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:

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

Hook Options

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

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

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:

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:

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

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

Test Coverage Target

• Minimum: 95%+ coverage
• Current: 95.05% (207 tests)

Linting

ruff check .
mypy . --strict

---

Troubleshooting

Common Issues

1. "No docs folder found"

# Solution: Specify custom docs folder
sdlcctl validate --docs documentation

2. "Invalid tier"

# Valid options: lite, standard, professional, enterprise
sdlcctl validate --tier professional

3. Pre-commit hook too slow

# Check performance
time python -m sdlcctl.hooks.pre_commit

# Target: <2 seconds

4. Permission denied on fix

# Check folder permissions
ls -la docs/

# Use sudo if needed (not recommended)
sudo sdlcctl fix --no-interactive

GitHub Integration Issues

5. "Invalid GitHub repository format"

# Valid formats:
sdlcctl init --github owner/repo              # Simple format
sdlcctl init --github https://github.com/owner/repo  # HTTPS URL
sdlcctl init --github [e-mail]:owner/repo.git  # SSH URL

# Invalid examples:
sdlcctl init --github just-a-name            # Missing owner
sdlcctl init --github https://gitlab.com/... # Wrong host

6. "GitHub App not installed"

# Solution: Install the SDLC Orchestrator GitHub App
# Visit: https://github.com/apps/sdlc-orchestrator/installations/new

# Then retry:
sdlcctl init --github owner/repo --tier professional

7. "Clone failed: repository not found"

# Check if repository exists and is accessible
gh repo view owner/repo

# For private repos, ensure GitHub App has access
# Or use --no-clone to link without cloning
sdlcctl init --github owner/repo --no-clone

8. "Directory already exists and is not the same repository"

# The target directory exists but has a different remote
# Options:
#   1. Remove the existing directory
#   2. Use a different path
#   3. Use --no-clone to skip cloning

sdlcctl init --github owner/repo --no-clone --path /new/path

9. "No API token configured"

# Set your API token
export SDLC_API_TOKEN=your-token

# Or pass via environment
SDLC_API_TOKEN=your-token sdlcctl init --github owner/repo

10. "Git is not installed"

# Install git
sudo apt install git      # Ubuntu/Debian
brew install git          # macOS

---

License

Apache-2.0

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Ensure tests pass with 95%+ coverage
4. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

---

Links

• Documentation: SDLC 6.0.5 Framework
• Issues: GitHub Issues
• Changelog: CHANGELOG.md

---

Generated by SDLC Orchestrator Team - Sprint 140