sdlc-framework 1.0.0

package/src/workflows/verify-phase.md

@@ -0,0 +1,280 @@
+<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>
+<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>
+<loop_context>
+  expected_phase: VERIFY (active)
+  prior_phase: IMPL ✓
+  next_phase: REVIEW
+</loop_context>
+<process>
+
+<step name="validate_state" priority="first">
+  Read .sdlc/STATE.md.
+
+  CHECK: loop_position must be "IMPL ✓"
+  CHECK: next_required_action must be "/sdlc:verify"
+
+  IF EITHER CHECK FAILS: STOP. Display: "Cannot verify. State requires: {next_required_action}. Run that first."
+
+  Extract current_phase and current_plan from STATE.md.
+
+  WHY: Verifying before implementation is done means testing incomplete code. The results would be meaningless.
+</step>
+
+<step name="load_acceptance_criteria" priority="second">
+  Read the SPEC.md at .sdlc/phases/{current_phase}/{current_plan}-SPEC.md.
+
+  Extract every acceptance criterion. Parse each into:
+  - AC number (e.g., AC-1)
+  - Description (short summary)
+  - GIVEN (precondition)
+  - WHEN (action)
+  - THEN (expected outcome)
+
+  Count total ACs. This is the denominator for the pass rate.
+
+  IF NO ACs FOUND: STOP. Display: "Spec has no acceptance criteria. Run /sdlc:spec to add them."
+
+  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:
+  ```
+  AC Classification:
+  AC-1: {description} → UI_INTERACTION (Playwright)
+  AC-2: {description} → API_ENDPOINT (curl)
+  AC-3: {description} → BUSINESS_LOGIC (test suite)
+  ```
+
+  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.
+</step>
+
+<step name="verify_ui_interactions" priority="fourth">
+  FOR EACH AC classified as UI_INTERACTION:
+
+  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
+
+  B. EXECUTE ACTION (WHEN):
+     Translate the WHEN clause into Playwright MCP actions:
+     - "clicks the submit button" → browser_click with the button selector
+     - "fills in the email field" → browser_fill_form with field and value
+     - "selects 'Admin' from the role dropdown" → browser_select_option
+     - "presses Enter" → browser_press_key with "Enter"
+     - "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.
+     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:
+       - "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
+
+  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.
+</step>
+
+<step name="verify_api_endpoints" priority="fifth">
+  FOR EACH AC classified as API_ENDPOINT:
+
+  A. SET UP PRECONDITION (GIVEN):
+     - Run any required setup commands (seed data, create test user, etc.)
+     - If GIVEN mentions authentication, obtain a token first
+
+  B. EXECUTE REQUEST (WHEN):
+     Translate the WHEN clause into a curl command:
+     ```bash
+     curl -s -w "\n%{http_code}" \
+       -X {METHOD} \
+       -H "Content-Type: application/json" \
+       -H "Authorization: Bearer {token}" \
+       -d '{request_body}' \
+       {base_url}{endpoint}
+     ```
+
+     Capture both response body and status code.
+
+  C. VERIFY RESPONSE (THEN):
+     Check each assertion in the THEN clause:
+     - "returns status 200" → compare HTTP status code
+     - "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}
+     ```
+
+  WHY: API tests are fast and deterministic. They verify the contract between frontend and backend without browser overhead.
+</step>
+
+<step name="verify_cli_behavior" priority="sixth">
+  FOR EACH AC classified as CLI_BEHAVIOR:
+
+  A. SET UP PRECONDITION (GIVEN):
+     - Create any required files, directories, or environment state
+
+  B. EXECUTE COMMAND (WHEN):
+     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
+     - "prints error to stderr" → check stderr content
+
+  D. RECORD RESULT with stdout/stderr as evidence.
+
+  WHY: CLI tools are verified by running them. The evidence is the actual terminal output.
+</step>
+
+<step name="verify_business_logic" priority="seventh">
+  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.)
+
+  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
+
+  C. IF TESTS DO NOT EXIST:
+     Record FAIL: "No test file found for AC-{N}. Implementation must include tests per engineering laws."
+
+  D. CHECK COVERAGE (if tool available):
+     Run coverage report. Check that modified files have adequate coverage.
+
+  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 needing a running server or browser.
+</step>
+
+<step name="generate_verification_report" priority="eighth">
+  Compile all results into a verification report.
+
+  Calculate:
+  - Total ACs: {N}
+  - Passed: {N}
+  - Failed: {N}
+  - Pass rate: {percentage}
+
+  Build the report table:
+  ```
+  | 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 |
+  ```
+
+  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.
+</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"
+
+    Display:
+    ```
+    Verification PASSED: {N}/{N} acceptance criteria met.
+
+    Report: .sdlc/phases/{phase}/{plan}-VERIFY.md
+
+    NEXT ACTION REQUIRED: /sdlc:review
+    Run /sdlc:review for engineering laws compliance check.
+    ```
+
+  IF ANY AC FAILS:
+    Do NOT update loop_position. Keep it at "IMPL ✓".
+    Update next_required_action to "/sdlc:verify" (stay in verify).
+
+    Display:
+    ```
+    Verification FAILED: {passed}/{total} acceptance criteria met.
+
+    Failed ACs:
+    - AC-{N}: {description} — {evidence}
+    - AC-{N}: {description} — {evidence}
+
+    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:
+    - 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.
+</step>
+
+</process>