sdlc-framework 1.0.0

package/src/templates/LAWS.md

@@ -0,0 +1,521 @@
+# Engineering Laws Template
+
+This template defines the engineering laws configuration stored at `.sdlc/LAWS.md`. Laws are enforced during `/sdlc:review`. Violations at the configured severity level block loop closure. This is the backbone of quality enforcement — every line of code passes through these laws before it ships.
+
+---
+
+```markdown
+# Engineering Laws
+
+These laws are enforced at /sdlc:review. Violations at configured severity block loop closure.
+
+## Configuration
+
+| Law | Severity | Description |
+|-----|----------|-------------|
+| SOLID | error | Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion |
+| DRY | error | Don't Repeat Yourself — search before create, no duplicate logic |
+| YAGNI | error | You Ain't Gonna Need It — only build what's in the spec |
+| CLEAN_CODE | error | Max 40 lines/function, max 3 params, max 3 nesting levels |
+| SECURITY | error | No hardcoded secrets, input validation, parameterized queries |
+| TESTING | error | Every behavior change needs tests, meaningful assertions |
+| NAMING | warning | Descriptive names, no abbreviations, self-documenting |
+| ERROR_HANDLING | error | No empty catch, domain-specific exceptions, no swallowed errors |
+
+Severity levels: error (blocks /sdlc:close) | warning (reported, doesn't block) | info (noted only)
+
+---
+
+## SOLID — Structural Integrity
+
+### What It Means
+
+SOLID is five principles that keep code flexible and maintainable. Each class, module, or function should have one reason to change (S), be extendable without editing existing code (O), be replaceable by subtypes without breaking anything (L), not force consumers to depend on methods they do not use (I), and depend on abstractions rather than concrete implementations (D).
+
+### What the Reviewer Checks
+
+- **S — Single Responsibility:** Does each class/module/function do exactly one thing? Does it have exactly one reason to change?
+- **O — Open/Closed:** Can new behavior be added by extending (new class, new handler) rather than modifying existing code?
+- **L — Liskov Substitution:** Can any subclass/implementation replace its parent/interface without the caller knowing?
+- **I — Interface Segregation:** Are interfaces small and focused? Does any consumer import methods it never calls?
+- **D — Dependency Inversion:** Do high-level modules depend on abstractions? Are concrete implementations injected, not instantiated?
+
+### Violations and Fixes
+
+**Violation — God class:**
+```typescript
+// BAD: UserService handles auth, profile, notifications, billing
+class UserService {
+  login() { /* ... */ }
+  updateProfile() { /* ... */ }
+  sendNotification() { /* ... */ }
+  processPayment() { /* ... */ }
+}
+```
+
+**Fix — Split by responsibility:**
+```typescript
+// GOOD: Each service owns one domain
+class AuthService { login() { /* ... */ } }
+class ProfileService { updateProfile() { /* ... */ } }
+class NotificationService { sendNotification() { /* ... */ } }
+class BillingService { processPayment() { /* ... */ } }
+```
+
+**Violation — Concrete dependency:**
+```typescript
+// BAD: Controller creates its own service
+class UserController {
+  private service = new UserService(new PostgresRepo())
+}
+```
+
+**Fix — Inject abstraction:**
+```typescript
+// GOOD: Depend on interface, inject via constructor
+class UserController {
+  constructor(private readonly userService: UserServiceInterface) {}
+}
+```
+
+### Why It Matters
+
+Code that violates SOLID becomes rigid. One change breaks unrelated features. Testing requires mocking the entire world. New developers are afraid to touch anything. Eventually the team rewrites instead of extending, wasting weeks or months.
+
+---
+
+## DRY — No Duplicate Logic
+
+### What It Means
+
+Every piece of knowledge should have a single, authoritative representation in the codebase. Before writing any new code, search for existing implementations. If you find one, use it. If you need a variation, extend the existing code rather than duplicating it.
+
+### What the Reviewer Checks
+
+- Are there two or more functions/methods with the same logic (even if variable names differ)?
+- Is the same validation logic written in multiple places?
+- Are there multiple constants with the same value but different names?
+- Did the developer search for existing helpers/utilities before writing new ones?
+- Are there inline implementations of logic that already exists in a shared utility?
+
+### Violations and Fixes
+
+**Violation — Duplicated validation:**
+```typescript
+// In user.controller.ts
+function validateEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+
+// In contact.controller.ts (same logic, different file)
+function isValidEmail(input: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)
+}
+```
+
+**Fix — Single shared utility:**
+```typescript
+// In src/common/utils/validation.ts
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+
+// Both controllers import from the same source
+import { isValidEmail } from '@/common/utils/validation'
+```
+
+**Violation — Repeated error response shape:**
+```typescript
+// Inline in every controller method
+return { status: 'error', message: err.message, code: 400 }
+```
+
+**Fix — Shared error factory:**
+```typescript
+// In src/common/errors/error-response.ts
+export function createErrorResponse(message: string, code: number): ErrorResponse {
+  return { status: 'error', message, code }
+}
+```
+
+### Why It Matters
+
+Duplicated logic means duplicated bugs. Fix a bug in one place, the copy still has it. Over time, copies diverge — slightly different behavior in different places. Users see inconsistent results. Developers spend hours hunting down "which version is right."
+
+---
+
+## YAGNI — Only Build What Is Specified
+
+### What It Means
+
+Do not build features, abstractions, or infrastructure that are not explicitly required by the current spec. "We might need this later" is not a justification. Build for today's requirements. If tomorrow needs something different, build it tomorrow.
+
+### What the Reviewer Checks
+
+- Does every file, function, and class trace back to a task in the spec?
+- Are there abstract base classes with only one implementation?
+- Are there configuration options nobody asked for?
+- Are there API endpoints not in the spec?
+- Are there database columns not required by any acceptance criterion?
+- Is there "framework code" (plugin systems, event buses, middleware chains) when the spec asked for a simple function?
+
+### Violations and Fixes
+
+**Violation — Premature abstraction:**
+```typescript
+// Spec says "store users in PostgreSQL"
+// Developer builds a generic repository pattern with adapters for
+// PostgreSQL, MongoDB, Redis, and SQLite "just in case"
+interface StorageAdapter<T> { /* ... */ }
+class PostgresAdapter<T> implements StorageAdapter<T> { /* ... */ }
+class MongoAdapter<T> implements StorageAdapter<T> { /* ... */ }
+class RedisAdapter<T> implements StorageAdapter<T> { /* ... */ }
+class SQLiteAdapter<T> implements StorageAdapter<T> { /* ... */ }
+```
+
+**Fix — Build what is needed:**
+```typescript
+// Just the PostgreSQL repository the spec requires
+class UserRepository {
+  async findById(id: string): Promise<User | null> { /* ... */ }
+  async save(user: User): Promise<void> { /* ... */ }
+}
+```
+
+**Violation — Unused configuration:**
+```typescript
+// Spec says nothing about rate limiting
+export const config = {
+  rateLimitEnabled: true,
+  rateLimitWindow: 60000,
+  rateLimitMax: 100,
+}
+```
+
+**Fix — Remove it:**
+```typescript
+// If it is not in the spec, it does not exist
+```
+
+### Why It Matters
+
+Unused code is not free. It must be read, understood, tested, and maintained. It creates false signals ("is this used? I better not delete it"). It adds complexity that slows down the team. The most maintainable code is code that does not exist.
+
+---
+
+## CLEAN_CODE — Readable and Maintainable
+
+### What It Means
+
+Code is read far more often than it is written. Clean code is small functions (max 40 lines), few parameters (max 3), shallow nesting (max 3 levels), and clear flow (guard clauses, early returns). If you need a comment to explain what code does, the code is not clean enough.
+
+### What the Reviewer Checks
+
+- **Function length:** Is any function longer than 40 lines? Count them.
+- **Parameter count:** Does any function take more than 3 parameters? Group into an object.
+- **Nesting depth:** Are there more than 3 levels of indentation? Use guard clauses.
+- **Ternary chains:** Are there nested ternaries? Use if/else.
+- **Comments explaining "what":** Is there a comment that describes what code does (not why)? Rename or restructure instead.
+- **Dead code:** Are there commented-out blocks, unreachable branches, or unused variables?
+
+### Violations and Fixes
+
+**Violation — Deep nesting:**
+```typescript
+function processOrder(order: Order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.payment) {
+        if (order.payment.verified) {
+          // actual logic buried 4 levels deep
+        }
+      }
+    }
+  }
+}
+```
+
+**Fix — Guard clauses:**
+```typescript
+function processOrder(order: Order) {
+  if (!order) return
+  if (order.items.length === 0) return
+  if (!order.payment) return
+  if (!order.payment.verified) return
+
+  // actual logic at top level
+}
+```
+
+**Violation — Too many parameters:**
+```typescript
+function createUser(
+  name: string,
+  email: string,
+  age: number,
+  role: string,
+  department: string,
+  managerId: string,
+) { /* ... */ }
+```
+
+**Fix — Parameter object:**
+```typescript
+interface CreateUserParams {
+  name: string
+  email: string
+  age: number
+  role: string
+  department: string
+  managerId: string
+}
+
+function createUser(params: CreateUserParams) { /* ... */ }
+```
+
+### Why It Matters
+
+Complex code is where bugs hide. Deep nesting makes it impossible to trace execution paths. Long functions do too many things and break in unexpected ways. Too many parameters mean the function has too many responsibilities. Clean code is debuggable code.
+
+---
+
+## SECURITY — No Vulnerabilities
+
+### What It Means
+
+Security is not a feature — it is a constraint on all features. Never hardcode secrets. Always validate input from users, APIs, and files. Use parameterized queries for all database access. Sanitize file paths. Use established security middleware.
+
+### What the Reviewer Checks
+
+- **Hardcoded secrets:** Are there API keys, passwords, tokens, or connection strings in source files?
+- **Input validation:** Is every user-facing input validated at the system boundary (controller, API handler, CLI parser)?
+- **SQL injection:** Are all database queries parameterized? Is any query built with string concatenation?
+- **Path traversal:** Are file paths sanitized? Can a user input `../../etc/passwd`?
+- **Authentication/Authorization:** Are protected routes actually checking credentials? Is there a gap where unauthenticated access is possible?
+- **.env files:** Are `.env` files in `.gitignore`? Are there example `.env.example` files instead?
+- **Dependencies:** Are there known vulnerable dependencies?
+
+### Violations and Fixes
+
+**Violation — Hardcoded secret:**
+```typescript
+const API_KEY = 'sk-1234567890abcdef'
+const dbUrl = 'postgres://admin:password@localhost:5432/mydb'
+```
+
+**Fix — Environment variables:**
+```typescript
+const API_KEY = process.env.API_KEY
+const dbUrl = process.env.DATABASE_URL
+```
+
+**Violation — SQL injection:**
+```typescript
+const query = `SELECT * FROM users WHERE email = '${userInput}'`
+```
+
+**Fix — Parameterized query:**
+```typescript
+const query = 'SELECT * FROM users WHERE email = $1'
+const result = await db.query(query, [userInput])
+```
+
+**Violation — No input validation:**
+```typescript
+app.post('/upload', (req, res) => {
+  const filePath = req.body.path
+  fs.readFile(filePath, (err, data) => { /* ... */ })
+})
+```
+
+**Fix — Path sanitization:**
+```typescript
+app.post('/upload', (req, res) => {
+  const safePath = path.resolve(UPLOAD_DIR, path.basename(req.body.path))
+  if (!safePath.startsWith(UPLOAD_DIR)) {
+    throw new ForbiddenException('Invalid file path')
+  }
+  fs.readFile(safePath, (err, data) => { /* ... */ })
+})
+```
+
+### Why It Matters
+
+Security vulnerabilities are not theoretical. They get exploited. Hardcoded secrets end up in git history and leak. SQL injection lets attackers read your entire database. Path traversal lets attackers read your server's filesystem. One vulnerability can destroy user trust permanently.
+
+---
+
+## TESTING — Every Behavior Has a Test
+
+### What It Means
+
+If you change how code behaves, you write a test that proves the new behavior works. Tests are not optional. They are not "nice to have." They are the proof that your code does what the spec says. Without tests, the verification phase has nothing to verify.
+
+### What the Reviewer Checks
+
+- **Coverage:** Does every new/modified function have at least one test?
+- **Meaningful assertions:** Do tests assert specific outcomes, not just "it didn't crash"?
+- **Edge cases:** Are null, undefined, empty arrays, empty strings, and boundary values tested?
+- **Test isolation:** Does each test run independently? No shared mutable state between tests?
+- **Test naming:** Does each test name describe the scenario and expected outcome?
+- **No implementation testing:** Do tests verify behavior (what), not implementation (how)?
+
+### Violations and Fixes
+
+**Violation — Test that asserts nothing meaningful:**
+```typescript
+test('createUser works', () => {
+  const result = createUser({ name: 'Alice', email: 'a@b.com' })
+  expect(result).toBeDefined()
+})
+```
+
+**Fix — Meaningful assertions:**
+```typescript
+test('createUser returns user with generated ID and provided name', () => {
+  const result = createUser({ name: 'Alice', email: 'a@b.com' })
+  expect(result.id).toMatch(/^[0-9a-f-]{36}$/)
+  expect(result.name).toBe('Alice')
+  expect(result.email).toBe('a@b.com')
+  expect(result.createdAt).toBeInstanceOf(Date)
+})
+```
+
+**Violation — Missing edge case test:**
+```typescript
+// Only tests the happy path
+test('findUser returns user', () => {
+  const user = findUser('existing-id')
+  expect(user.name).toBe('Alice')
+})
+```
+
+**Fix — Test the edges:**
+```typescript
+test('findUser returns user when ID exists', () => {
+  const user = findUser('existing-id')
+  expect(user.name).toBe('Alice')
+})
+
+test('findUser returns null when ID does not exist', () => {
+  const user = findUser('nonexistent-id')
+  expect(user).toBeNull()
+})
+
+test('findUser throws when ID is empty string', () => {
+  expect(() => findUser('')).toThrow(InvalidIdError)
+})
+```
+
+### Why It Matters
+
+Code without tests is code you cannot refactor. You cannot add features confidently because you do not know what you will break. Every change is a gamble. Tests are not about catching bugs today — they are about preventing regressions tomorrow and next month and next year.
+
+---
+
+## NAMING — Self-Documenting Code
+
+### What It Means
+
+Names are the primary documentation of code. A good name tells you what something does without reading the implementation. Use full words, not abbreviations. Name functions for their action, variables for their content, and types for their shape.
+
+### What the Reviewer Checks
+
+- **Abbreviations:** Are there names like `usr`, `btn`, `msg`, `cfg`, `ctx`? Use `user`, `button`, `message`, `config`, `context`.
+- **Vague names:** Are there names like `data`, `result`, `info`, `item`, `temp`, `val`? Use specific names.
+- **Boolean naming:** Do boolean variables read as questions? `isValid`, `hasPermission`, `canEdit` — not `valid`, `permission`, `edit`.
+- **Function naming:** Do functions start with verbs? `calculateTotal`, `validateInput`, `fetchUser` — not `total`, `input`, `user`.
+- **Consistency:** Is the same concept named the same way everywhere? Not `user` in one file and `account` in another for the same entity.
+
+### Violations and Fixes
+
+**Violation — Abbreviations and vague names:**
+```typescript
+function proc(d: any) {
+  const r = d.map((i: any) => i.v * i.q)
+  return r.reduce((a: number, b: number) => a + b, 0)
+}
+```
+
+**Fix — Descriptive names:**
+```typescript
+function calculateOrderTotal(lineItems: LineItem[]): number {
+  const itemTotals = lineItems.map(item => item.price * item.quantity)
+  return itemTotals.reduce((sum, itemTotal) => sum + itemTotal, 0)
+}
+```
+
+### Why It Matters
+
+You read code 10x more than you write it. Every abbreviation costs 2 seconds of mental translation, multiplied by every developer who reads it, multiplied by every time they read it. Over a project's lifetime, bad names cost hundreds of hours.
+
+---
+
+## ERROR_HANDLING — No Silent Failures
+
+### What It Means
+
+When something goes wrong, the code must either handle it properly or tell someone about it. Empty catch blocks are banned — they hide bugs that surface weeks later in production. Use domain-specific exceptions that carry context. Never throw raw `Error` with a generic message.
+
+### What the Reviewer Checks
+
+- **Empty catch blocks:** Is there any `catch (e) {}` or `catch { }` in the codebase? This is unconditionally banned.
+- **Swallowed exceptions:** Is there a catch block that logs but does not rethrow or return an error response?
+- **Generic errors:** Are there `throw new Error('something went wrong')` instead of domain-specific exceptions?
+- **Missing error handling:** Are there async operations without try/catch or .catch()?
+- **Error messages:** Do error messages include enough context to diagnose the problem?
+
+### Violations and Fixes
+
+**Violation — Empty catch block:**
+```typescript
+try {
+  await saveUser(user)
+} catch (e) {
+  // swallowed — user thinks save succeeded
+}
+```
+
+**Fix — Handle or rethrow:**
+```typescript
+try {
+  await saveUser(user)
+} catch (error) {
+  logger.error('Failed to save user', { userId: user.id, error })
+  throw new UserPersistenceError(`Failed to save user ${user.id}`, { cause: error })
+}
+```
+
+**Violation — Generic error:**
+```typescript
+if (!user) {
+  throw new Error('Not found')
+}
+```
+
+**Fix — Domain-specific exception:**
+```typescript
+if (!user) {
+  throw new UserNotFoundError(`User with ID ${userId} does not exist`)
+}
+```
+
+### Why It Matters
+
+Swallowed errors are time bombs. The operation failed, but nothing reported it. Data is silently corrupted. Users see stale information. By the time someone notices, the root cause is buried under layers of subsequent operations. An error that screams immediately saves hours of debugging later.
+```
+
+---
+
+## Field Documentation
+
+### Severity Configuration
+Each law has one of three severity levels:
+- **error** — Violations of this law block `/sdlc:close`. The loop cannot complete until violations are fixed.
+- **warning** — Violations are reported in the review but do not block loop closure. They should be addressed but are not critical.
+- **info** — Violations are noted for awareness. No action required.
+
+Severity can be changed per project to match team standards. For example, a prototype project might set TESTING to `warning` while a production API keeps it at `error`.
+
+### Adding Custom Laws
+Teams can add project-specific laws following the same format: name, severity, description, checks, examples, and rationale. Custom laws participate in the review process identically to built-in laws.

package/src/templates/PROJECT.md

@@ -0,0 +1,112 @@
+# Project Context Template
+
+This template defines the project context document stored at `.sdlc/PROJECT.md`. It is created during `/sdlc:init` and referenced throughout the lifecycle. Every field must be populated — incomplete project context leads to ambiguous specs.
+
+---
+
+```markdown
+# Project: {{PROJECT_NAME}}
+
+## Description
+
+{{PROJECT_DESCRIPTION}}
+
+A 2-3 sentence summary of what this project does, who it serves, and what problem it solves.
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Language | {{LANGUAGE}} | {{VERSION}} |
+| Framework | {{FRAMEWORK}} | {{VERSION}} |
+| Database | {{DATABASE}} | {{VERSION}} |
+| Package Manager | {{PACKAGE_MANAGER}} | {{VERSION}} |
+| Test Runner | {{TEST_RUNNER}} | {{VERSION}} |
+| Linter/Formatter | {{LINTER}} | {{VERSION}} |
+| Build Tool | {{BUILD_TOOL}} | {{VERSION}} |
+
+## Architecture Overview
+
+{{ARCHITECTURE_DESCRIPTION}}
+
+Describe the high-level architecture: monolith, microservices, serverless, etc.
+Include key patterns: MVC, DDD, event-driven, CQRS, etc.
+
+### Directory Structure
+
+```
+{{PROJECT_ROOT}}/
+  src/
+    {{DIRECTORY_LAYOUT}}
+  tests/
+    {{TEST_LAYOUT}}
+```
+
+### Key Boundaries
+
+- **Entry points:** {{ENTRY_POINTS}}
+- **API layer:** {{API_LAYER}}
+- **Business logic:** {{BUSINESS_LOGIC_LAYER}}
+- **Data access:** {{DATA_ACCESS_LAYER}}
+- **External integrations:** {{EXTERNAL_INTEGRATIONS}}
+
+## Requirements
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-001 | {{REQUIREMENT_DESCRIPTION}} | {{high/medium/low}} | {{active/validated/invalidated}} |
+| REQ-002 | {{REQUIREMENT_DESCRIPTION}} | {{high/medium/low}} | {{active/validated/invalidated}} |
+
+### Status Definitions
+
+- **active** — Requirement is current and guides development
+- **validated** — Requirement has been implemented and verified
+- **invalidated** — Requirement was dropped or replaced (include reason)
+
+## Current State
+
+- **Phase:** {{init/active/maintenance}}
+- **Last milestone completed:** {{MILESTONE_NAME or "None"}}
+- **Active milestone:** {{MILESTONE_NAME or "None"}}
+- **Known issues:** {{COUNT or "None"}}
+- **Test coverage:** {{PERCENTAGE or "Unknown"}}
+
+## Constraints
+
+| Constraint | Description | Impact |
+|------------|-------------|--------|
+| {{CONSTRAINT_NAME}} | {{WHAT_AND_WHY}} | {{HOW_IT_AFFECTS_DEVELOPMENT}} |
+
+### Common Constraint Categories
+
+- **Performance:** Response time limits, throughput requirements
+- **Security:** Compliance requirements, data handling rules
+- **Compatibility:** Browser support, API versioning, backward compatibility
+- **Infrastructure:** Hosting limits, budget, CI/CD pipeline constraints
+- **Team:** Skill level, availability, timezone considerations
+```
+
+---
+
+## Field Documentation
+
+### PROJECT_NAME
+The canonical name of the project. Use the name from `package.json`, `Cargo.toml`, or equivalent manifest. If no manifest exists, use the root directory name.
+
+### PROJECT_DESCRIPTION
+Plain English summary. Avoid jargon. A new team member should understand what this project does after reading this field.
+
+### Tech Stack Table
+Every technology the project depends on for development and deployment. Include versions — version mismatches cause subtle bugs that waste hours.
+
+### Architecture Overview
+Not a design doc. A quick orientation so that anyone reading a spec knows where code lives and how layers interact.
+
+### Requirements
+Living document. Requirements move from `active` to `validated` when implemented and verified. They move to `invalidated` when scope changes — never delete them, mark them so there is an audit trail.
+
+### Current State
+Updated at the end of each loop closure. Provides instant orientation for session resume.
+
+### Constraints
+Hard limits that specs must respect. If a spec violates a constraint, the reviewer catches it. Constraints are not negotiable without explicit stakeholder approval.