sdlc-framework 1.0.0

package/src/references/engineering-laws.md

@@ -0,0 +1,374 @@
+# Engineering Laws Reference
+
+This document provides a deep dive into each engineering law enforced by the SDLC framework. It is loaded via `@references/engineering-laws.md` when reviewing code or when a developer needs to understand why a law exists and how it applies to AI-assisted development.
+
+---
+
+## SOLID Principles
+
+### Plain English
+
+SOLID is five rules for organizing code so it stays flexible as it grows:
+
+1. **Single Responsibility (S):** Each piece of code does one thing. A user service handles user logic. It does not also send emails.
+2. **Open/Closed (O):** Add new behavior by writing new code, not by editing existing code. Use interfaces, plugins, or strategy patterns.
+3. **Liskov Substitution (L):** Any implementation of an interface can replace any other without breaking the system.
+4. **Interface Segregation (I):** Do not force code to depend on methods it does not use. Keep interfaces small and focused.
+5. **Dependency Inversion (D):** High-level code depends on abstractions (interfaces), not on low-level details (concrete classes).
+
+### How It Applies to AI-Assisted Development
+
+AI code generators tend to produce "complete" solutions in a single file. They pack everything together because they optimize for generating a working answer in one shot. This naturally violates Single Responsibility — the AI does not have an incentive to split code across files.
+
+AI also tends to create concrete implementations rather than abstractions. When you ask "build a user service," the AI writes `new PostgresRepository()` directly, violating Dependency Inversion. It does not know your project has an injection system.
+
+### Common AI-Generated Violations
+
+**God service pattern:**
+AI generates a service that handles authentication, profile updates, email notifications, and audit logging all in one class. Each method works, but the class has 400 lines and 6 different reasons to change.
+
+**Concrete coupling:**
+```typescript
+// AI writes this because it is "complete" and works immediately
+class OrderService {
+  private db = new PostgresClient('postgres://localhost:5432/orders')
+  private emailer = new SendGridClient('sg-api-key-here')
+}
+```
+Two SOLID violations (concrete dependencies) plus a security violation (hardcoded credentials) in two lines.
+
+**Fat interfaces:**
+AI creates one interface with every possible method, then forces all implementations to stub out methods they do not need.
+
+### How the Reviewer Detects Violations
+
+- Counts methods per class. More than 7-8 methods suggests multiple responsibilities.
+- Searches for `new` keyword inside service classes — concrete instantiation signals dependency inversion violations.
+- Checks that every interface has multiple implementations or is designed for future replacement.
+- Verifies that interface methods are all used by at least one consumer.
+
+### Real-World Consequences
+
+A monolithic service cannot be tested in isolation. To test user creation, you need a real database, a real email provider, and a real audit log. Tests become slow, flaky, and expensive. Developers stop writing them. Bugs ship. Eventually, the team says "we need to rewrite" and the cycle restarts — 3 months of work lost.
+
+---
+
+## DRY (Don't Repeat Yourself)
+
+### Plain English
+
+Every piece of knowledge should exist in exactly one place. If you need the same logic in two places, extract it into a shared function and call it from both places. Duplication is not just about identical code — it is about identical concepts.
+
+### How It Applies to AI-Assisted Development
+
+AI has no memory across prompts (unless explicitly given context). If you ask it to build Feature A and later ask it to build Feature B, it will write fresh implementations of shared logic — validation, formatting, error handling — even if identical code already exists.
+
+This is the single most common issue with AI-generated code: it works, but it duplicates existing patterns because the AI did not search the codebase first.
+
+### Common AI-Generated Violations
+
+**Duplicate validation logic:**
+The AI writes email validation in the user controller, then writes it again in the contact form handler, then again in the newsletter signup. Three identical regex checks in three files.
+
+**Duplicate error response formatting:**
+Every controller method manually constructs `{ status: 'error', message: err.message, code: 400 }` instead of using the existing error response factory.
+
+**Duplicate type definitions:**
+The AI defines `interface User { id: string; name: string; email: string }` in three different files because each prompt started fresh.
+
+### How the Reviewer Detects Violations
+
+- Searches for identical or near-identical code blocks across files.
+- Checks if new utility functions duplicate existing ones in `src/common/utils/`.
+- Looks for inline implementations of logic that exists in a shared library.
+- Verifies that type definitions are imported from canonical sources, not redefined.
+
+### Real-World Consequences
+
+When a validation rule changes (email regex updated for new TLD), the developer fixes one copy and misses the others. Users see inconsistent behavior — "my email works on the signup page but not on the contact form." Debugging takes hours because the developer assumes there is one validation function, not three.
+
+---
+
+## YAGNI (You Ain't Gonna Need It)
+
+### Plain English
+
+Do not build things you do not need right now. If the spec says "users can log in with email and password," do not build OAuth, SAML, magic links, and biometric auth "for the future." Build email/password. When the spec says "add OAuth," build OAuth then.
+
+### How It Applies to AI-Assisted Development
+
+AI optimizes for impressiveness. Ask it to build a REST endpoint and it will add pagination, filtering, sorting, caching, rate limiting, and webhook support — even if you asked for a simple GET endpoint. The AI is trying to be helpful, but it is building infrastructure you did not ask for.
+
+This extra code looks professional but it has real costs: it must be tested, maintained, and documented. It creates surface area for bugs. It confuses developers who wonder "is the caching layer required? Can I remove it?"
+
+### Common AI-Generated Violations
+
+**Premature abstraction layers:**
+Spec says "store users in PostgreSQL." AI builds a generic repository pattern with adapters for five databases, a caching layer with Redis, and a query builder abstraction.
+
+**Configuration nobody asked for:**
+Spec says "send welcome email." AI adds configurable email templates, A/B testing support, scheduled sending, and retry queues.
+
+**Plugin architecture for a single use case:**
+Spec says "validate input." AI builds a pluggable validation framework with custom rule registration, async validators, and i18n error messages.
+
+### How the Reviewer Detects Violations
+
+- Maps every file, function, and class back to a task in the spec. Anything that cannot be traced to a spec task is YAGNI.
+- Looks for abstract base classes with only one concrete implementation.
+- Checks for configuration options that are not used or tested.
+- Identifies "framework code" (event buses, plugin registries, middleware chains) when the spec asked for specific behavior.
+
+### Real-World Consequences
+
+Extra code is not free. A pagination system nobody uses still needs tests (which nobody writes because nobody uses it). When the real pagination requirement arrives months later, it has different needs than what was pre-built. Now the developer must either force-fit the new requirement into the old abstraction or rip out the old code and write it properly. Either way, the pre-built code wasted time twice — once to write, once to remove.
+
+---
+
+## Clean Code
+
+### Plain English
+
+Code should be small, simple, and obvious. Functions should be short (max 40 lines), take few arguments (max 3), and have shallow nesting (max 3 levels). If you need a comment to explain what code does, the code is too complex — simplify it.
+
+### How It Applies to AI-Assisted Development
+
+AI generates code in large blocks. It does not naturally refactor long functions into smaller helpers because it writes code in a single pass. A 100-line function with 5 levels of nesting is common in AI output because the AI is solving the problem, not crafting maintainable code.
+
+AI also tends to use complex expressions (nested ternaries, long chains of method calls) because they are more token-efficient than explicit if/else blocks.
+
+### Common AI-Generated Violations
+
+**Functions that are too long:**
+AI writes a single function that reads a file, parses it, validates it, transforms it, and writes the output. Each step is correct, but the function is 80 lines with no helper extraction.
+
+**Deep nesting:**
+```typescript
+if (user) {
+  if (user.isActive) {
+    if (user.hasPermission('admin')) {
+      if (request.isValid) {
+        // actual logic buried 4 levels deep
+      }
+    }
+  }
+}
+```
+
+**Nested ternaries:**
+```typescript
+const label = status === 'active' ? 'Active' : status === 'pending' ? 'Pending' : status === 'suspended' ? 'Suspended' : 'Unknown'
+```
+
+### How the Reviewer Detects Violations
+
+- Counts lines per function. Any function over 40 lines is flagged.
+- Counts parameters per function. More than 3 triggers a "group into object" suggestion.
+- Measures nesting depth. More than 3 levels triggers a "use guard clauses" suggestion.
+- Searches for nested ternary operators.
+- Looks for comments that explain "what" instead of "why."
+
+### Real-World Consequences
+
+A 100-line function cannot be partially tested. You test the whole thing or nothing. When a bug is reported, you re-read all 100 lines to understand the flow. When a requirement changes, you must understand all 100 lines to know where to make the change. Small functions with clear names are grep-able, testable, and replaceable.
+
+---
+
+## Security
+
+### Plain English
+
+Never hardcode secrets. Always validate user input. Always use parameterized queries. Always sanitize file paths. Security is not a feature you add — it is a constraint on every feature you build.
+
+### How It Applies to AI-Assisted Development
+
+AI generates examples with placeholder credentials that look like real credentials. `const API_KEY = 'sk-1234'` is meant as a placeholder but gets committed as-is. The AI does not know about your `.env` setup or your secrets manager.
+
+AI also tends to trust input. When generating an endpoint, it reads `req.body.id` and uses it directly in a query without validation. The AI assumes the input is valid because in the prompt, it was.
+
+### Common AI-Generated Violations
+
+**Hardcoded credentials in examples:**
+```typescript
+const stripe = new Stripe('sk_live_actualkey123')
+const db = new Client({ connectionString: 'postgres://admin:password@prod-db:5432' })
+```
+
+**Unvalidated user input:**
+```typescript
+app.get('/file/:path', (req, res) => {
+  res.sendFile(req.params.path) // directory traversal
+})
+```
+
+**String-concatenated SQL:**
+```typescript
+const query = `SELECT * FROM users WHERE name = '${req.body.name}'`
+```
+
+### How the Reviewer Detects Violations
+
+- Searches for patterns that look like API keys, tokens, passwords, or connection strings in source files.
+- Checks that every route handler validates its input before processing.
+- Searches for string interpolation or concatenation in SQL queries.
+- Verifies that file path operations use `path.resolve` and check against a safe base directory.
+- Confirms `.env` files are in `.gitignore`.
+
+### Real-World Consequences
+
+Hardcoded credentials in git history persist forever — even after deletion, they exist in commit history. Automated scanners find them within hours. SQL injection can read, modify, or delete your entire database. Path traversal can expose any file on your server. These are not theoretical risks; they are the most commonly exploited vulnerabilities in web applications.
+
+---
+
+## Testing
+
+### Plain English
+
+If you change how code behaves, you write a test that proves the new behavior works. Every function that could fail should have a test for the success case, the failure case, and the edge cases. Tests are the proof that your code works — without them, you are guessing.
+
+### How It Applies to AI-Assisted Development
+
+AI can write excellent tests — but only if you ask. Left to its own devices, AI generates production code without tests or generates tests that assert nothing meaningful (`expect(result).toBeDefined()`). The SDLC framework makes testing a hard requirement, not an afterthought.
+
+AI-generated tests also tend to test implementation rather than behavior. They mock internals and assert on internal method calls instead of testing observable outcomes. This makes tests brittle — any refactor breaks them even if behavior is preserved.
+
+### Common AI-Generated Violations
+
+**Tests that assert existence, not correctness:**
+```typescript
+test('creates user', () => {
+  const user = createUser({ name: 'Alice' })
+  expect(user).toBeDefined() // proves nothing about correctness
+})
+```
+
+**Tests that test implementation:**
+```typescript
+test('creates user', () => {
+  const spy = jest.spyOn(repo, 'save')
+  createUser({ name: 'Alice' })
+  expect(spy).toHaveBeenCalledTimes(1) // tests HOW, not WHAT
+})
+```
+
+**Missing edge case tests:**
+AI writes one happy-path test and considers testing complete. No tests for null input, empty strings, duplicate entries, or concurrent access.
+
+### How the Reviewer Detects Violations
+
+- Checks that every new/modified function has at least one corresponding test.
+- Reads assertions to verify they test specific values, not just existence.
+- Looks for edge case coverage: null, undefined, empty, boundary values.
+- Verifies tests run independently (no shared mutable state).
+- Confirms test names describe scenario and expected outcome.
+
+### Real-World Consequences
+
+Without tests, every code change is a roll of the dice. You modify a utility function and silently break three features that depend on it. You discover the breakage when a user reports it, days later. With tests, the CI pipeline catches it in 30 seconds and tells you exactly which behavior broke and where.
+
+---
+
+## Naming
+
+### Plain English
+
+Names are the most-read documentation in your codebase. A well-named function does not need a comment. Use full words, not abbreviations. Name functions for what they do (verbs), variables for what they hold (nouns), and booleans as yes/no questions (`isValid`, `hasPermission`).
+
+### How It Applies to AI-Assisted Development
+
+AI tends to use short, generic names in generated code: `data`, `result`, `item`, `val`, `cb`. This is because AI training data includes millions of examples with terse naming. The AI optimizes for "plausible code" rather than "code a human will maintain."
+
+AI also inconsistently names the same concept — `user` in one file, `account` in another, `profile` in a third — because each generation is independent.
+
+### Common AI-Generated Violations
+
+**Generic names:**
+```typescript
+function process(data: any) {
+  const result = data.map((item: any) => transform(item))
+  return result.filter((r: any) => r.valid)
+}
+```
+
+**Inconsistent naming:**
+```typescript
+// File A: UserService with getUser()
+// File B: AccountManager with fetchAccount()
+// File C: ProfileHandler with loadProfile()
+// All three refer to the same domain concept
+```
+
+**Abbreviations:**
+```typescript
+const usr = getUsr(req.params.usrId)
+const cfg = loadCfg()
+const btn = doc.querySelector('.btn')
+```
+
+### How the Reviewer Detects Violations
+
+- Searches for common generic names: `data`, `result`, `item`, `temp`, `val`, `cb`, `fn`.
+- Searches for common abbreviations: `usr`, `btn`, `msg`, `cfg`, `ctx`, `req`, `res` (outside of framework conventions).
+- Checks that boolean variables start with `is`, `has`, `can`, `should`, or similar question words.
+- Checks that function names start with verbs.
+- Verifies naming consistency across files for the same domain concept.
+
+### Real-World Consequences
+
+Bad names force every reader to build a mental translation table. "What does `d` mean here? Let me scroll up... it's the database connection." This takes 2-3 seconds per encounter, multiplied by every developer, every time they read the code. Over a year, a poorly named codebase costs the team hundreds of hours of unnecessary mental overhead.
+
+---
+
+## Error Handling
+
+### Plain English
+
+When something goes wrong, your code must either handle it (take corrective action) or report it (log and rethrow). Silently ignoring errors is the worst possible choice — it hides bugs that surface later in harder-to-diagnose ways.
+
+### How It Applies to AI-Assisted Development
+
+AI wraps risky code in try/catch but often leaves the catch block empty or with just a `console.log`. This is because AI training data is full of tutorials and examples that use `catch (e) {}` as a shortcut. The AI does not know that your production system needs proper error reporting.
+
+AI also tends to throw generic `Error` objects instead of domain-specific exceptions. `throw new Error('failed')` tells you nothing about what failed, where, or why.
+
+### Common AI-Generated Violations
+
+**Empty catch blocks:**
+```typescript
+try {
+  await sendEmail(user.email, template)
+} catch (e) {
+  // AI left this empty "to prevent crashes"
+}
+```
+The email silently fails. The user never receives it. Nobody knows.
+
+**Generic errors:**
+```typescript
+if (!user) throw new Error('error')
+if (!order) throw new Error('not found')
+if (!payment) throw new Error('invalid')
+```
+When this hits the error log, the developer sees "error" with no context.
+
+**Swallowed exceptions:**
+```typescript
+try {
+  await processPayment(order)
+} catch (error) {
+  console.log('payment failed') // logged and forgotten
+  return { success: true } // lies to the caller
+}
+```
+
+### How the Reviewer Detects Violations
+
+- Searches for empty catch blocks: `catch` followed by `{}` or just a comment.
+- Searches for `console.log` inside catch blocks without a rethrow.
+- Checks that custom exception classes exist and are used instead of generic `Error`.
+- Verifies that error messages include context (entity ID, operation name, user context).
+- Confirms that catch blocks either handle the error (retry, fallback) or rethrow it.
+
+### Real-World Consequences
+
+A swallowed payment error means a customer is charged but their order is not fulfilled. An empty catch on a database write means data is lost without anyone knowing. A generic error message means the on-call engineer spends 30 minutes figuring out which "not found" error triggered the alert. Proper error handling is the difference between "we fixed it in 5 minutes" and "we lost data and don't know when it started."