sdlc-framework 1.0.0 → 1.0.1

package/src/workflows/verify-phase.md

@@ -1,11 +1,23 @@
-<purpose>Verify every acceptance criterion from the spec using automated testing. UI interactions use Playwright MCP, API endpoints use HTTP requests, business logic uses the project test suite. Every AC gets a PASS or FAIL with evidence.</purpose>
+<purpose>Two-phase verification: first test every acceptance criterion using automated tools, then check all modified code against engineering laws. Both gates must pass before closing the loop. UI interactions use Playwright MCP, API endpoints use HTTP requests, business logic uses the project test suite. Engineering laws (SOLID, DRY, YAGNI, Clean Code, Security, Testing, Error Handling) are checked against LAWS.md configured severity. This single step replaces the old separate verify + review commands.</purpose>
 <when_to_use>Run after /sdlc:impl completes. STATE.md must show loop_position = IMPL ✓ and next_required_action = /sdlc:verify.</when_to_use>
-<required_reading>.sdlc/STATE.md, the current SPEC.md (for acceptance criteria), .sdlc/PROJECT.md (for tech stack and test commands)</required_reading>
+<required_reading>.sdlc/STATE.md, the current SPEC.md, .sdlc/PROJECT.md, .sdlc/LAWS.md, all modified files</required_reading>
 <loop_context>
   expected_phase: VERIFY (active)
   prior_phase: IMPL ✓
-  next_phase: REVIEW
+  next_phase: CLOSE
 </loop_context>
+<display_rule>
+  MANDATORY: Display results in two sections in the chat window.
+
+  PHASE 1 — AC Results:
+  | AC | Description | Type | Status | Evidence (1 line) |
+
+  PHASE 2 — Engineering Laws Review:
+  | # | File | Line | Law | Severity | Finding |
+  Blocker count, warning count, verdict.
+
+  Keep it compact (~30-50 lines total). Full VERIFY.md is in the file for audit.
+</display_rule>
 <process>
 
 <step name="validate_state" priority="first">
@@ -38,48 +50,73 @@
   WHY: Without acceptance criteria, there is nothing to verify. The spec must define what "done" looks like.
 </step>
 
-<step name="classify_acceptance_criteria" priority="third">
-  For each AC, classify its verification type based on the GIVEN/WHEN/THEN content:
-
-  TYPE: UI_INTERACTION
-  Indicators: mentions page, form, button, click, navigate, display, render, modal, input field, dropdown
-  Method: Playwright MCP (browser_navigate, browser_snapshot, browser_click, browser_fill_form, etc.)
-
-  TYPE: API_ENDPOINT
-  Indicators: mentions endpoint, request, response, status code, JSON body, header, GET/POST/PUT/DELETE
-  Method: Bash curl commands
-
-  TYPE: CLI_BEHAVIOR
-  Indicators: mentions command, terminal, output, exit code, stderr, stdout, flag, argument
-  Method: Bash command execution
-
-  TYPE: BUSINESS_LOGIC
-  Indicators: mentions function, method, returns, throws, calculates, transforms, validates
-  Method: Run project test suite (npm test, bun test, etc.) or execute specific test files
-
-  TYPE: DATA_INTEGRITY
-  Indicators: mentions database, record, row, column, migration, schema, constraint
-  Method: Database queries via Bash or ORM commands
-
-  Present classification to proceed:
+<step name="read_verification_types" priority="third">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  DO NOT GUESS OR INFER THE VERIFICATION TYPE.                       ║
+  ║  READ the Type field from each AC in the SPEC.md.                   ║
+  ║  The spec phase declared the type. The verify phase USES it.        ║
+  ║  If an AC is missing its Type field, mark it FAIL: "No Type field." ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  For each AC extracted in the previous step, read its declared Type field.
+
+  VALID TYPES AND THEIR VERIFICATION TOOLS:
+
+  | Type | Verification Tool | Action |
+  |------|------------------|--------|
+  | UI_INTERACTION | Playwright MCP | Use browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot |
+  | API_ENDPOINT | Bash curl | Construct and execute HTTP requests, parse response |
+  | CLI_BEHAVIOR | Bash | Run shell commands, capture stdout/stderr/exit code |
+  | BUSINESS_LOGIC | Test runner | Run bun test, npm test, vitest, jest, or pytest |
+  | DATA_INTEGRITY | DB CLI | Execute database queries via Bash |
+
+  MISSING TYPE HANDLING:
+  If an AC does NOT have a Type field:
+  1. Record: "FAIL — AC-{N} is missing its Type field. The spec must declare a verification_type for every AC."
+  2. Do NOT attempt to guess the type from keywords.
+  3. Include this failure in the verification report.
+
+  PLAYWRIGHT MCP PRE-CHECK:
+  If ANY AC has Type: UI_INTERACTION:
+  1. Call mcp__plugin_playwright_playwright__browser_install to ensure a browser is available.
+  2. Call mcp__plugin_playwright_playwright__browser_navigate with a test URL (the app's base URL from PROJECT.md or localhost).
+  3. If navigation fails: record ALL UI_INTERACTION ACs as FAIL with evidence "Playwright MCP unavailable or app not running at {url}."
+  4. If navigation succeeds: call mcp__plugin_playwright_playwright__browser_snapshot to confirm the page loaded.
+
+  Present the type mapping before executing:
   ```
-  AC Classification:
-  AC-1: {description} → UI_INTERACTION (Playwright)
-  AC-2: {description} → API_ENDPOINT (curl)
-  AC-3: {description} → BUSINESS_LOGIC (test suite)
+  Verification Plan:
+  AC-1: {description} → {Type} (tool: {Playwright MCP | curl | Bash | test runner | DB CLI})
+  AC-2: {description} → {Type} (tool: {Playwright MCP | curl | Bash | test runner | DB CLI})
   ```
 
-  WHY: Different AC types need different verification tools. Using curl for a UI test or Playwright for a unit test wastes time and gives unreliable results.
+  WHY: The spec phase explicitly declared how each AC should be verified. Reading the declared type eliminates guessing. The Playwright pre-check catches "MCP not installed" before wasting time on individual AC attempts.
 </step>
 
 <step name="verify_ui_interactions" priority="fourth">
   FOR EACH AC classified as UI_INTERACTION:
 
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  YOU MUST CALL THESE EXACT TOOL NAMES. THIS IS NOT OPTIONAL.       ║
+  ║  mcp__plugin_playwright_playwright__browser_navigate                ║
+  ║  mcp__plugin_playwright_playwright__browser_snapshot                ║
+  ║  mcp__plugin_playwright_playwright__browser_click                   ║
+  ║  mcp__plugin_playwright_playwright__browser_fill_form               ║
+  ║  mcp__plugin_playwright_playwright__browser_take_screenshot         ║
+  ║  mcp__plugin_playwright_playwright__browser_select_option           ║
+  ║  mcp__plugin_playwright_playwright__browser_press_key               ║
+  ║  mcp__plugin_playwright_playwright__browser_hover                   ║
+  ║  mcp__plugin_playwright_playwright__browser_file_upload             ║
+  ║  mcp__plugin_playwright_playwright__browser_console_messages        ║
+  ║  mcp__plugin_playwright_playwright__browser_wait_for                ║
+  ║  DO NOT ask the user to manually test. DO NOT skip UI ACs.         ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
   A. SET UP PRECONDITION (GIVEN):
-     - Use browser_navigate to go to the relevant page
-     - Use browser_snapshot to capture initial state
-     - Verify the GIVEN condition is met in the snapshot
-     - If the GIVEN requires data setup (e.g., "a registered user"), run setup commands first via Bash
+     1. Call browser_navigate to go to the relevant page
+     2. Call browser_snapshot to capture initial state
+     3. Verify the GIVEN condition is met in the snapshot
+     4. If GIVEN requires data setup (e.g., "a registered user"), run setup commands first via Bash
 
   B. EXECUTE ACTION (WHEN):
      Translate the WHEN clause into Playwright MCP actions:
@@ -90,33 +127,31 @@
      - "hovers over the menu" → browser_hover with the menu selector
      - "uploads a file" → browser_file_upload
 
-     Use browser_snapshot BEFORE the action to confirm the element exists.
+     Call browser_snapshot BEFORE the action to confirm the element exists.
      If the element is not found in the snapshot, record FAIL: "Element not found: {selector}"
 
   C. VERIFY OUTCOME (THEN):
-     - Use browser_snapshot AFTER the action
-     - Use browser_take_screenshot for visual evidence
-     - Check the snapshot content against the THEN clause:
+     1. Call browser_snapshot AFTER the action
+     2. Call browser_take_screenshot for visual evidence
+     3. Check the snapshot content against the THEN clause:
        - "displays a success message" → search snapshot for the message text
        - "redirects to /dashboard" → check the current URL in snapshot
        - "shows 3 items in the list" → count matching elements in snapshot
        - "hides the modal" → verify modal is absent from snapshot
+     4. Call browser_console_messages to check for JavaScript errors
 
   D. RECORD RESULT:
-     ```
      AC-{N}: {description}
      Status: PASS | FAIL
      Evidence: {what was observed}
      Screenshot: {if taken}
-     ```
 
   IF AN ACTION FAILS (element not found, page error, timeout):
      - Record FAIL with the specific error
-     - Use browser_console_messages to check for JavaScript errors
      - Include console errors in the evidence
      - Continue to next AC (do not stop on first failure)
 
-  WHY: Playwright MCP replaces manual UAT. Every UI acceptance criterion gets tested programmatically with screenshot evidence, making verification reproducible and auditable.
+  WHY: Playwright MCP replaces manual UAT. Every UI acceptance criterion gets tested programmatically with screenshot evidence.
 </step>
 
 <step name="verify_api_endpoints" priority="fifth">
@@ -136,7 +171,6 @@
        -d '{request_body}' \
        {base_url}{endpoint}
      ```
-
      Capture both response body and status code.
 
   C. VERIFY RESPONSE (THEN):
@@ -145,16 +179,10 @@
      - "response contains { 'token': ... }" → parse JSON and check field existence
      - "response body is an array of 3 items" → parse JSON and check array length
      - "returns error message 'Not found'" → check response body contains string
-     - "sets cookie 'session'" → check response headers
 
-  D. RECORD RESULT:
-     ```
-     AC-{N}: {description}
-     Status: PASS | FAIL
-     Evidence: HTTP {status}, Body: {truncated response}
-     ```
+  D. RECORD RESULT with HTTP status and response body as evidence.
 
-  WHY: API tests are fast and deterministic. They verify the contract between frontend and backend without browser overhead.
+  WHY: API tests are fast and deterministic. They verify the contract between frontend and backend.
 </step>
 
 <step name="verify_cli_behavior" priority="sixth">
@@ -164,13 +192,9 @@
      - Create any required files, directories, or environment state
 
   B. EXECUTE COMMAND (WHEN):
-     Run the command via Bash. Capture:
-     - stdout
-     - stderr
-     - exit code
+     Run the command via Bash. Capture stdout, stderr, exit code.
 
   C. VERIFY OUTPUT (THEN):
-     Check each assertion:
      - "outputs 'Success'" → check stdout contains string
      - "exits with code 0" → check exit code
      - "creates file X" → check file exists
@@ -185,96 +209,260 @@
   FOR EACH AC classified as BUSINESS_LOGIC:
 
   A. CHECK IF TESTS EXIST:
-     Search for test files related to the AC (look for files matching *.test.ts, *.spec.ts, *.test.js, etc.)
+     Search for test files related to the AC (*.test.ts, *.spec.ts, *.test.js, etc.)
 
   B. IF TESTS EXIST:
-     Run the specific test file or test suite:
-     - npm test -- {test-file} (or bun test, vitest, jest, etc.)
-     - Capture output: pass/fail count, error messages
+     Run the specific test file or test suite via Bash. Capture output.
 
   C. IF TESTS DO NOT EXIST:
-     Record FAIL: "No test file found for AC-{N}. Implementation must include tests per engineering laws."
+     Record FAIL: "No test file found for AC-{N}. Implementation must include tests."
 
-  D. CHECK COVERAGE (if tool available):
-     Run coverage report. Check that modified files have adequate coverage.
+  D. RECORD RESULT with test runner output as evidence.
 
-  E. RECORD RESULT:
-     ```
-     AC-{N}: {description}
-     Status: PASS | FAIL
-     Evidence: {test output — pass count, fail count, error messages}
-     Coverage: {percentage for relevant files, if available}
-     ```
+  WHY: Business logic tests are the fastest feedback loop. They catch logic errors without a running server.
+</step>
+
+<step name="compile_ac_results" priority="eighth">
+  Compile all AC results into a table:
+
+  | AC | Description | Type | Status | Evidence |
+  |----|-------------|------|--------|----------|
+  | AC-1 | {desc} | UI | PASS | Screenshot shows success message |
+  | AC-2 | {desc} | API | FAIL | Expected 200, got 404 |
+
+  Calculate: Total ACs, Passed, Failed, Pass rate.
 
-  WHY: Business logic tests are the fastest feedback loop. They catch logic errors without needing a running server or browser.
+  Display the table in chat as "PHASE 1 — Acceptance Criteria".
+
+  WHY: The AC results table gives immediate visibility before proceeding to engineering laws review.
 </step>
 
-<step name="generate_verification_report" priority="eighth">
-  Compile all results into a verification report.
+<step name="check_ac_gate" priority="ninth">
+  IF ANY AC FAILS (pass rate < 100%):
+    Do NOT update loop_position. Keep it at "IMPL ✓".
+    Set next_required_action to "/sdlc:verify" (stay in verify).
+
+    Display:
+    ```
+    PHASE 1 FAILED: {passed}/{total} acceptance criteria met.
+
+    Failed ACs:
+    - AC-{N}: {description} — {evidence}
 
-  Calculate:
+    Fix suggestions:
+    - AC-{N}: {specific suggestion based on the failure}
+
+    Fix the failures and re-run /sdlc:verify.
+    If the spec is wrong (not the code), run /sdlc:spec to update it.
+    ```
+
+    Provide SPECIFIC fix suggestions for each failure:
+    - HTTP 404 → "Check that the route is registered."
+    - Element not found → "Use browser_snapshot to inspect the DOM."
+    - Test fails → "The assertion on line {N} expected {X} but got {Y}."
+    - No tests → "Create test file at {path}."
+
+    Do NOT proceed to engineering laws review. Do NOT auto-advance.
+    STOP HERE.
+
+  IF ALL ACs PASS (pass rate = 100%):
+    Display: "PHASE 1 PASSED: {N}/{N} acceptance criteria met."
+    Proceed to engineering laws review.
+
+  WHY: Code must work before reviewing its quality. Reviewing broken code is pointless.
+</step>
+
+<step name="engineering_laws_review" priority="tenth">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  PHASE 2: ENGINEERING LAWS REVIEW                                   ║
+  ║  All ACs passed. Now check code quality against LAWS.md.            ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  A. LOAD REVIEW CONTEXT:
+     Read .sdlc/LAWS.md. Build a lookup of law → severity (ERROR/WARN/INFO).
+     Read the SPEC.md. Extract files_modified, files_created, boundaries, acceptance criteria.
+     Combine into a review list. Read every file in the list.
+
+     IF review list is empty: skip to generate_final_report with zero findings.
+
+  B. CHECK SOLID PRINCIPLES:
+     FOR EACH FILE:
+     - SRP: Does each class/module/function have one reason to change? Flag mixed concerns.
+     - OCP: Can code be extended without modification? Flag switch/if chains on types.
+     - LSP: Do subtypes honor parent contracts? Flag overrides that change semantics.
+     - ISP: Are interfaces minimal? Flag interfaces with 5+ methods.
+     - DIP: Do high-level modules depend on abstractions? Flag concrete instantiation with `new`.
+     Finding format: "{file}:{line} — {principle} violation: {description}"
+
+  C. CHECK DRY:
+     WITHIN MODIFIED FILES:
+     - 3+ lines of identical or near-identical logic in multiple places
+     - Copy-pasted code with only variable names changed
+     ACROSS THE CODEBASE:
+     - Use Grep to search for existing functions that do the same thing as new code
+     - Search for existing utilities with similar names or signatures
+     Finding format: "{file}:{line} — DRY violation: duplicates {other-file}:{line}"
+
+  D. CHECK YAGNI:
+     FOR EACH NEW FUNCTION/METHOD/CLASS:
+     - Is it required by at least one AC?
+     - Flag: zero-caller functions, single-value params, single-impl abstractions, "TODO: use later"
+     Finding format: "{file}:{line} — YAGNI violation: {function} not required by any AC"
+
+  E. CHECK CLEAN CODE:
+     - Function length > 40 lines → BLOCKER
+     - Parameter count > 3 → BLOCKER
+     - Nesting depth > 3 → BLOCKER
+     - Nested ternaries or ternary chains → BLOCKER
+     - Single-letter variables (except i, j, k) → WARNING
+     - Generic names (data, info, result, temp) → WARNING
+     Finding format: "{file}:{line} — Clean Code: {function} is {N} lines (max 40)"
+
+  F. CHECK SECURITY:
+     - Hardcoded secrets: patterns API_KEY, SECRET, PASSWORD, TOKEN + string literal
+     - SQL injection: string concatenation in SQL queries
+     - XSS: unsanitized user input rendered in HTML
+     - Path traversal: file path construction with user input
+     - Input validation: system boundary functions must validate all inputs
+     Finding format: "{file}:{line} — SECURITY: {vulnerability type}"
+
+  G. CHECK TESTING:
+     FOR EACH NEW BEHAVIOR:
+     - Does a corresponding test exist? Search for *.test.*, *.spec.*
+     - Are assertions meaningful? (not just .toBeDefined())
+     - Are edge cases covered? (empty input, null, boundary values)
+     Finding format: "{file}:{line} — TESTING: no test for {function}"
+
+  H. CHECK ERROR HANDLING:
+     - Empty catch blocks → ALWAYS BLOCKER (regardless of severity config)
+     - Generic throw new Error() → flag for domain-specific exception
+     - Swallowed exceptions (catch without log/rethrow)
+     - Missing error handling on async operations
+     Finding format: "{file}:{line} — ERROR HANDLING: {violation}"
+
+  Map severity from LAWS.md: ERROR → BLOCKER, WARN → WARNING, INFO → INFO.
+
+  WHY: Engineering laws catch structural issues that automated tests miss. A function can pass all ACs and still be a 200-line unmaintainable mess.
+</step>
+
+<step name="generate_final_report" priority="eleventh">
+  Compile both phases into a single VERIFY.md at .sdlc/phases/{current_phase}/{current_plan}-VERIFY.md:
+
+  ```markdown
+  # Verification Report: Plan {plan-number}
+
+  ## Phase 1: Acceptance Criteria
+
+  ### Summary
   - Total ACs: {N}
   - Passed: {N}
   - Failed: {N}
-  - Pass rate: {percentage}
 
-  Build the report table:
-  ```
+  ### Results
   | AC | Description | Type | Status | Evidence |
   |----|-------------|------|--------|----------|
-  | AC-1 | {desc} | UI | PASS | Screenshot shows success message |
-  | AC-2 | {desc} | API | FAIL | Expected 200, got 404 |
-  | AC-3 | {desc} | Logic | PASS | 5/5 tests passed |
+  | AC-1 | {desc} | {type} | PASS/FAIL | {evidence} |
+
+  ## Phase 2: Engineering Laws Review
+
+  ### Summary
+  - **Blockers**: {count}
+  - **Warnings**: {count}
+  - **Info**: {count}
+  - **Files reviewed**: {count}
+
+  ### Findings by File
+
+  #### {file-path}
+  | # | Law | Severity | Line | Finding |
+  |---|-----|----------|------|---------|
+  | 1 | DRY | BLOCKER | 42 | Duplicates logic from utils/format.ts:15 |
+
+  ### Blocker Details
+  For each blocker:
+  - What the violation is
+  - Where: file:line
+  - How to fix (specific, actionable)
+  - Pattern to follow (reference existing code)
+
+  ### Laws Compliance Matrix
+  | Law | Status | Findings |
+  |-----|--------|----------|
+  | SOLID | PASS/FAIL | B-1, W-2 |
+  | DRY | PASS/FAIL | ... |
+
+  ### Clean Files
+  {Files with zero findings}
   ```
 
-  Save report to: .sdlc/phases/{current_phase}/{current_plan}-VERIFY.md
-
-  WHY: The report is the evidence trail. During review and close, we can point to specific pass/fail results. Without evidence, "it works" is just an opinion.
+  WHY: One artifact captures both verification and review. No cross-referencing needed.
 </step>
 
-<step name="handle_results" priority="ninth">
-  IF ALL ACs PASS (pass rate = 100%):
-    Update .sdlc/STATE.md:
-    - loop_position: VERIFY ✓
-    - next_required_action: /sdlc:review
-    - Add history entry: "{timestamp} | verify | All {N} ACs passed"
+<step name="handle_results" priority="twelfth">
+  IF BLOCKERS EXIST (engineering laws violations at BLOCKER severity):
+    Do NOT update loop_position. Keep at "IMPL ✓".
+    Set next_required_action to "/sdlc:fix".
 
     Display:
     ```
-    Verification PASSED: {N}/{N} acceptance criteria met.
+    PHASE 1 PASSED: {N}/{N} ACs met.
+    PHASE 2 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)
 
     Report: .sdlc/phases/{phase}/{plan}-VERIFY.md
 
-    NEXT ACTION REQUIRED: /sdlc:review
-    Run /sdlc:review for engineering laws compliance check.
+    NEXT: /sdlc:fix
     ```
 
-  IF ANY AC FAILS:
-    Do NOT update loop_position. Keep it at "IMPL ✓".
-    Update next_required_action to "/sdlc:verify" (stay in verify).
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:fix in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:fix.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:fix — Run /sdlc:fix to systematically fix all blockers, then re-verify automatically."
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  IF NO BLOCKERS (only warnings and info, or clean):
+    Update .sdlc/STATE.md:
+    - loop_position: VERIFY ✓
+    - next_required_action: /sdlc:close
+    - Add history entry: "{timestamp} | verify | All {N} ACs passed. Review: {warn_count} warnings, {info_count} info."
 
     Display:
     ```
-    Verification FAILED: {passed}/{total} acceptance criteria met.
+    PHASE 1 PASSED: {N}/{N} ACs met.
+    PHASE 2 PASSED: 0 blockers.
 
-    Failed ACs:
-    - AC-{N}: {description} — {evidence}
-    - AC-{N}: {description} — {evidence}
+    Warnings: {count} (consider fixing)
+    Files reviewed: {count}
 
-    Fix suggestions:
-    - AC-{N}: {specific suggestion based on the failure}
+    Report: .sdlc/phases/{phase}/{plan}-VERIFY.md
 
-    Fix the failures and re-run /sdlc:verify.
-    If the spec is wrong (not the code), run /sdlc:spec to update it.
+    NEXT: /sdlc:close
     ```
 
-    Provide SPECIFIC fix suggestions for each failure:
-    - If HTTP 404 → "Check that the route is registered. Look for typos in the endpoint path."
-    - If element not found → "Check that the selector matches the actual DOM. Use browser_snapshot to inspect."
-    - If test fails → "Read the test output carefully. The assertion on line {N} expected {X} but got {Y}."
-    - If no tests exist → "Create test file at {path}. Use existing test patterns from {similar file}."
-
-  WHY: Failing fast with specific guidance prevents the user from wasting time guessing what went wrong. Staying in the verify state prevents advancing with broken code.
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:close in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:close.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:close"
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  WHY: Both gates must pass. ACs ensure the code works. Laws ensure the code is maintainable. Only when both pass does the loop advance to close.
 </step>
 
 </process>

package/src/commands/hotfix.md

@@ -1,99 +0,0 @@
----
-name: sdlc:hotfix
-description: "Emergency fix with minimal ceremony, maximum verification"
-argument-hint: "<critical-issue>"
-allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_close, AskUserQuestion]
----
-
-<objective>
-Emergency fix for critical issues. Minimal ceremony getting to the fix. Maximum verification after the fix. No corners cut on quality — only on planning overhead.
-
-**When to use:** Production is broken. A critical path is failing. Security vulnerability discovered. Something that cannot wait for a full SPEC cycle.
-
-**What it does:**
-1. Skip full spec — create a lightweight inline spec (3 lines).
-2. Fix the issue directly.
-3. Run FULL verification (tests + Playwright).
-4. Run FULL review (engineering laws compliance).
-5. Record as a hotfix with decimal phase numbering (2.1, 2.2, etc.).
-
-**What happens next:** /sdlc:verify to run the full verification suite.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/hotfix.md
-@.sdlc/STATE.md
-@.sdlc/LAWS.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Read .sdlc/STATE.md to get current milestone and phase.
-Read .sdlc/LAWS.md — hotfixes are NOT exempt from engineering laws.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/hotfix.md
-
-Step-by-step:
-
-1. **Pre-flight check**
-   - Verify .sdlc/ exists. If not, tell the user to run /sdlc:init first.
-   - Read .sdlc/STATE.md to get current phase number (e.g., phase 2).
-   - Assign hotfix number: current phase + decimal increment (2.1, 2.2, etc.).
-   - Update STATE.md: set loop_position to HOTFIX, record hotfix number.
-
-2. **Lightweight inline spec (3 lines)**
-   - Line 1: WHAT is broken. (From $ARGUMENTS.)
-   - Line 2: WHERE is the likely location. (Quick search with Grep.)
-   - Line 3: WHAT the fix should achieve. (Expected behavior.)
-   - Record this inline spec in STATE.md under the hotfix entry.
-
-3. **Fix the issue**
-   - Search for the affected code using Grep and Read.
-   - Apply the fix. Follow engineering laws:
-     - DRY: use existing patterns.
-     - Handle edge cases.
-     - Named types for complex objects.
-     - No lint suppression. No non-null assertions.
-     - Max 40 lines per function.
-   - Keep the change surface as small as possible. Fix the issue, nothing more.
-
-4. **Full verification**
-   - Run the entire test suite. Not just affected tests — ALL tests.
-   - For UI-related hotfixes:
-     - Use Playwright to navigate to affected pages.
-     - Verify the fix visually with screenshots.
-     - Check console for errors.
-     - Test the happy path AND edge cases.
-   - If tests fail: fix the test failures before proceeding. Do not skip.
-
-5. **Full review against engineering laws**
-   - Read .sdlc/LAWS.md.
-   - Check every changed line against every applicable law.
-   - Verify: no dead code introduced, no unused imports, no inline complex types.
-   - If any law is violated: fix it. Hotfixes are not exempt.
-
-6. **Record in STATE.md**
-   - Update .sdlc/STATE.md:
-     - Record hotfix number (decimal: 2.1, 2.2, etc.).
-     - Record: issue description, files changed, tests run, verification status.
-     - Set loop_position back to current phase position.
-   - Create .sdlc/hotfixes/HOTFIX-{number}-{timestamp}.md with full details.
-
-7. **Force next action**
-   - Output: "NEXT ACTION REQUIRED: /sdlc:verify — run full verification suite to confirm no regressions."
-</process>
-
-<success_criteria>
-- [ ] Inline spec created (3 lines: what, where, expected behavior)
-- [ ] Fix applied following engineering laws — no exceptions for hotfixes
-- [ ] Full test suite runs and passes
-- [ ] Playwright verification completed for UI-related hotfixes
-- [ ] Engineering laws review passed on all changed code
-- [ ] Hotfix recorded in STATE.md with decimal phase numbering
-- [ ] Hotfix detail file created in .sdlc/hotfixes/
-- [ ] Change surface is minimal — only the fix, nothing extra
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:verify
-</success_criteria>