sdlc-framework 1.0.0

package/src/workflows/review-phase.md

@@ -0,0 +1,337 @@
+<purpose>Perform engineering laws compliance review on all files modified during implementation. Every law configured in LAWS.md is checked at its configured severity. Blockers must be fixed before proceeding to close.</purpose>
+<when_to_use>Run after /sdlc:verify passes. STATE.md must show loop_position = VERIFY ✓ and next_required_action = /sdlc:review.</when_to_use>
+<required_reading>.sdlc/STATE.md, the current SPEC.md (for modified files list), .sdlc/LAWS.md (for law configuration), all modified files</required_reading>
+<loop_context>
+  expected_phase: REVIEW (active)
+  prior_phase: VERIFY ✓
+  next_phase: CLOSE
+</loop_context>
+<process>
+
+<step name="validate_state" priority="first">
+  Read .sdlc/STATE.md.
+
+  CHECK: loop_position must be "VERIFY ✓"
+  CHECK: next_required_action must be "/sdlc:review"
+
+  IF EITHER CHECK FAILS: STOP. Display: "Cannot review. State requires: {next_required_action}. Run that first."
+
+  WHY: Reviewing before verification means reviewing code that might not even work. Fix it first, then review it.
+</step>
+
+<step name="load_review_context" priority="second">
+  Read .sdlc/LAWS.md. Build a lookup of law to severity:
+  ```
+  SOLID: ERROR
+  DRY: ERROR
+  YAGNI: ERROR
+  Clean Code: ERROR
+  Security: ERROR
+  Testing: ERROR
+  Error Handling: ERROR
+  Null Safety: WARN
+  Type Safety: WARN
+  File Size: WARN
+  ```
+
+  Read the SPEC.md. Extract:
+  - files_modified (list of all files changed during implementation)
+  - files_created (list of all new files)
+  - boundaries (what was NOT supposed to change)
+  - acceptance criteria (to verify YAGNI — is all code justified by an AC?)
+
+  Combine files_modified and files_created into a single review list.
+
+  IF the review list is empty: STOP. Display: "No files to review. The spec lists no modified files. Re-run /sdlc:impl to update the file list."
+
+  WHY: The review is only as good as the file list. Missing files means missing violations.
+</step>
+
+<step name="read_all_modified_files" priority="third">
+  Read every file in the review list.
+
+  For each file, note:
+  - Total line count
+  - Language (infer from extension)
+  - Module/directory it belongs to
+
+  IF a file in the list does not exist: Flag as WARNING — "File listed in spec but not found: {path}. It may have been renamed or deleted during implementation."
+
+  WHY: You must read the code to review it. Reading all files upfront provides full context — a violation in file A might be caused by a pattern in file B.
+</step>
+
+<step name="check_solid" priority="fourth">
+  FOR EACH FILE, check SOLID principles. Record findings at the severity configured for SOLID in LAWS.md.
+
+  SINGLE RESPONSIBILITY:
+  - Does the file/class/module do ONE thing?
+  - Red flags: class name contains "And" (e.g., "UserAndPermissionService"), file has multiple unrelated exports, service method that does CRUD + notification + logging
+  - Check: count the number of "reasons to change." If more than one domain concept would cause changes, SRP is violated.
+  - Finding format: "{file}:{line} — SRP violation: {class/function} handles both {responsibility-1} and {responsibility-2}"
+
+  OPEN/CLOSED:
+  - Can the code be extended without modifying existing code?
+  - Red flags: switch/case on type strings that must grow, if/else chains for new variants, hardcoded lists of handlers
+  - Check: look for switch statements or if/else chains that dispatch based on a type or category. These should use polymorphism or strategy pattern.
+  - Finding format: "{file}:{line} — OCP violation: Adding a new {type} requires modifying this {switch/if-chain}"
+
+  LISKOV SUBSTITUTION:
+  - If subtypes exist, are they substitutable for their parent?
+  - Red flags: overridden methods that throw "not implemented", subclass that ignores parent contract
+  - Check: look for class inheritance where child behavior contradicts parent interface
+
+  INTERFACE SEGREGATION:
+  - Are interfaces minimal and focused?
+  - Red flags: interface with 10+ methods, classes that implement interface methods as no-ops
+  - Check: look for large interfaces. If implementors leave methods empty, the interface is too fat.
+
+  DEPENDENCY INVERSION:
+  - Do high-level modules depend on abstractions, not concretions?
+  - Red flags: service directly instantiating another service with `new`, importing concrete database driver in business logic
+  - Check: constructor parameters should be interfaces/abstract classes, not concrete implementations
+
+  WHY: SOLID violations create rigid, fragile code that resists change. Catching them now prevents expensive refactors later.
+</step>
+
+<step name="check_dry" priority="fifth">
+  Search for duplicate logic across ALL modified files AND the broader codebase.
+
+  WITHIN MODIFIED FILES:
+  - Look for 3+ lines of identical or near-identical logic appearing in multiple places
+  - Look for copy-pasted code blocks with only variable names changed
+  - Look for repeated patterns (same sequence of operations)
+
+  ACROSS THE CODEBASE:
+  - For each new function/method created, search the codebase for existing functions that do the same thing
+  - For each utility created, search for existing utilities with similar names or signatures
+  - For each pattern implemented, search for the same pattern elsewhere
+
+  HOW TO SEARCH:
+  - Use Grep to search for key function names, variable names, and distinctive code patterns
+  - Search for imports — if a utility exists but was not imported, DRY is violated
+
+  Finding format: "{file}:{line} — DRY violation: This logic duplicates {other-file}:{line}. Extract to shared utility or reuse existing {function-name}."
+
+  WHY: Duplicate logic means duplicate bugs. Fix one copy, forget the other, ship a regression. DRY is the most common violation and the easiest to prevent.
+</step>
+
+<step name="check_yagni" priority="sixth">
+  Compare every piece of new code against the SPEC acceptance criteria.
+
+  FOR EACH NEW FUNCTION/METHOD/CLASS:
+  - Is it required by at least one AC?
+  - Is it required as infrastructure for an AC (e.g., a utility function used by AC-related code)?
+  - Or is it speculative — "we might need this later"?
+
+  Red flags:
+  - Functions with zero callers (dead code)
+  - Parameters that are always passed the same value (unused flexibility)
+  - Abstract base classes with only one implementation
+  - Configuration options that no AC exercises
+  - "TODO: use this later" comments
+
+  Finding format: "{file}:{line} — YAGNI violation: {function/class} is not required by any AC. Remove or justify."
+
+  WHY: Speculative code has maintenance cost but zero current value. It rots, breaks, and confuses future developers who think it is used.
+</step>
+
+<step name="check_clean_code" priority="seventh">
+  FOR EACH FUNCTION/METHOD in modified files:
+
+  FUNCTION LENGTH:
+  - Count lines (excluding blank lines and comments)
+  - If > 40 lines: BLOCKER (at configured severity)
+  - Finding: "{file}:{line} — Function '{name}' is {N} lines (max 40). Extract helper functions."
+
+  PARAMETER COUNT:
+  - Count parameters in signature
+  - If > 3 parameters: BLOCKER
+  - Finding: "{file}:{line} — Function '{name}' has {N} parameters (max 3). Group into an options/config interface."
+
+  NESTING DEPTH:
+  - Count maximum indentation levels within function body
+  - If > 3 levels: BLOCKER
+  - Finding: "{file}:{line} — Nesting depth {N} (max 3). Use guard clauses and early returns."
+
+  NAMING QUALITY:
+  - Single-letter variables (except loop counters i, j, k): WARNING
+  - Generic names (data, info, result, temp, stuff, thing): WARNING
+  - Abbreviations that are not universally understood: WARNING
+  - Boolean variables not prefixed with is/has/can/should: INFO
+  - Finding: "{file}:{line} — Name '{name}' is unclear. Rename to describe what it does, not what it is."
+
+  CONDITIONAL STYLE:
+  - Nested if/else > 2 levels: recommend guard clauses
+  - Ternary chains (a ? b : c ? d : e): BLOCKER
+  - Nested ternaries: BLOCKER
+  - Finding: "{file}:{line} — Nested conditional. Convert to guard clause with early return."
+
+  WHY: Clean code is readable code. Readable code has fewer bugs, is easier to maintain, and is faster to onboard new developers.
+</step>
+
+<step name="check_security" priority="eighth">
+  FOR EACH FILE in the review list:
+
+  HARDCODED SECRETS:
+  - Search for patterns: API_KEY, SECRET, PASSWORD, TOKEN, PRIVATE_KEY followed by = and a string literal
+  - Search for base64-encoded strings that look like keys (long alphanumeric strings)
+  - Search for URLs with embedded credentials (protocol://user:pass@host)
+  - Finding: "{file}:{line} — SECURITY: Hardcoded secret detected. Move to environment variable."
+
+  SQL INJECTION:
+  - Search for string concatenation or template literals in SQL queries
+  - Patterns: "SELECT ... " + variable, template literal SELECT with interpolated variable
+  - Finding: "{file}:{line} — SECURITY: SQL injection risk. Use parameterized query."
+
+  XSS (Cross-Site Scripting):
+  - Search for user input rendered in HTML without sanitization
+  - Patterns: innerHTML assignment with user data, unsafe HTML rendering with unsanitized data
+  - All user-provided content MUST be sanitized using a dedicated HTML sanitizer library (such as DOMPurify) before rendering
+  - Finding: "{file}:{line} — SECURITY: XSS risk. Sanitize user input with a dedicated sanitizer library before rendering."
+
+  DIRECTORY TRAVERSAL:
+  - Search for file path construction using user input without sanitization
+  - Patterns: path.join(userInput), fs.readFile(userInput)
+  - Finding: "{file}:{line} — SECURITY: Directory traversal risk. Validate and sanitize file path."
+
+  INPUT VALIDATION:
+  - Check system boundary functions (controllers, API handlers, CLI parsers)
+  - Are all inputs validated before processing?
+  - Finding: "{file}:{line} — SECURITY: No input validation at system boundary."
+
+  WHY: Security vulnerabilities are the highest-cost bugs. A single SQL injection or leaked secret can compromise an entire system. Catching these in review is the last line of defense.
+</step>
+
+<step name="check_testing" priority="ninth">
+  FOR EACH NEW BEHAVIOR introduced in modified files:
+
+  CHECK: Does a corresponding test exist?
+  - Search for test files: {filename}.test.{ext}, {filename}.spec.{ext}
+  - Search within test files for test cases that exercise the new behavior
+
+  IF NEW BEHAVIOR HAS NO TEST:
+  - Finding: "{file}:{line} — TESTING: New {function/method/endpoint} has no test. Add test to {expected-test-file}."
+
+  IF TESTS EXIST, check quality:
+  - Are assertions meaningful? (not just "expect(result).toBeDefined()" — that passes for any non-undefined value)
+  - Are edge cases covered? (empty input, null, boundary values)
+  - Are error cases tested? (what happens when it fails)
+  - Finding: "{test-file}:{line} — TESTING: Assertion is too weak. Test the specific expected value, not just existence."
+
+  WHY: Untested code is unverified code. It might work today and break tomorrow with no warning. Tests are the safety net.
+</step>
+
+<step name="check_error_handling" priority="tenth">
+  FOR EACH TRY/CATCH block in modified files:
+
+  EMPTY CATCH BLOCKS:
+  - Pattern: catch block with empty body
+  - This is ALWAYS a BLOCKER regardless of severity config
+  - Finding: "{file}:{line} — ERROR HANDLING: Empty catch block. Log the error or rethrow."
+
+  GENERIC ERROR THROWS:
+  - Pattern: throw new Error("something went wrong")
+  - Should use domain-specific exceptions
+  - Finding: "{file}:{line} — ERROR HANDLING: Generic Error. Use a domain-specific exception class."
+
+  SWALLOWED EXCEPTIONS:
+  - Pattern: catch block that does not log, rethrow, or return an error indicator
+  - Finding: "{file}:{line} — ERROR HANDLING: Exception caught but not logged or rethrown. This hides failures."
+
+  MISSING ERROR HANDLING:
+  - Async operations without try/catch or .catch()
+  - File operations without error handling
+  - Network requests without timeout or error handling
+  - Finding: "{file}:{line} — ERROR HANDLING: No error handling for {operation}. Add try/catch or .catch()."
+
+  WHY: Swallowed exceptions are invisible bugs. The system fails silently, data corrupts quietly, and debugging becomes archaeology.
+</step>
+
+<step name="generate_review_report" priority="eleventh">
+  Compile all findings into REVIEW.md at .sdlc/phases/{current_phase}/{current_plan}-REVIEW.md.
+
+  Format:
+  ```markdown
+  # Review: Plan {plan-number}
+
+  ## Summary
+  - **Blockers**: {count}
+  - **Warnings**: {count}
+  - **Info**: {count}
+  - **Files reviewed**: {count}
+
+  ## Findings by File
+
+  ### {file-path}
+  | # | Law | Severity | Line | Finding |
+  |---|-----|----------|------|---------|
+  | 1 | DRY | ERROR | 42 | Duplicates logic from utils/format.ts:15 |
+  | 2 | Clean Code | ERROR | 78 | Function 'processData' is 67 lines (max 40) |
+  | 3 | Naming | WARN | 12 | Variable 'x' is unclear |
+
+  ### {next-file-path}
+  ...
+
+  ## Blocker Details
+  For each blocker, explain:
+  - What the violation is
+  - Where it is (file:line)
+  - How to fix it (specific, actionable guidance)
+  - What pattern to follow (reference existing code)
+
+  ## Clean Files
+  {List files with zero findings — positive reinforcement}
+  ```
+
+  Map law severity: use the severity from LAWS.md.
+  - ERROR severity law violation maps to BLOCKER
+  - WARN severity law violation maps to WARNING
+  - INFO severity law violation maps to INFO
+
+  WHY: The report is structured for action. Blockers are at the top with fix instructions. The developer knows exactly what to do without re-analyzing the code.
+</step>
+
+<step name="handle_results" priority="twelfth">
+  IF BLOCKERS EXIST (count > 0):
+    Do NOT update loop_position. Keep at "VERIFY ✓".
+    Set next_required_action to "/sdlc:review" (stay in review after fixes).
+
+    Display:
+    ```
+    Review FAILED: {blocker_count} blockers found.
+
+    Blockers:
+    1. {file}:{line} — {finding} — Fix: {how to fix}
+    2. {file}:{line} — {finding} — Fix: {how to fix}
+
+    Warnings: {count} (non-blocking, but should fix)
+    Info: {count}
+
+    Run /sdlc:fix to systematically fix all blockers, then re-review automatically.
+    Report: .sdlc/phases/{phase}/{plan}-REVIEW.md
+    ```
+
+  IF NO BLOCKERS (only warnings and info, or clean):
+    Update .sdlc/STATE.md:
+    - loop_position: REVIEW ✓
+    - next_required_action: /sdlc:close
+    - Add history entry: "{timestamp} | review | Passed. {warn_count} warnings, {info_count} info."
+
+    Display:
+    ```
+    Review PASSED: 0 blockers.
+
+    Warnings: {count} (consider fixing)
+    Info: {count}
+    Files reviewed: {count}
+
+    Report: .sdlc/phases/{phase}/{plan}-REVIEW.md
+
+    NEXT ACTION REQUIRED: /sdlc:close
+    Run /sdlc:close to close this loop.
+    ```
+
+  WHY: Blockers are the gate. They enforce engineering standards. Warnings are advisory — the team can choose to address them. The gate prevents shipping code that violates critical laws.
+</step>
+
+</process>