sdlc-framework 3.0.0 → 3.1.0

package/README.md

@@ -136,9 +136,10 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 
 - Asks clarification questions (no guessing)
 - Presents options with trade-offs and recommendations
-- Defines BDD acceptance criteria (Given/When/Then)
+- Defines BDD acceptance criteria (Given/When/Then) with **explicit verification types** — each AC declares whether it's tested via Playwright MCP, curl, Bash, test runner, or DB queries
 - Decomposes tasks with dependency graph for parallel execution
-- **Spec integrity review** — checks completeness, consistency, feasibility
+- **Codebase gap analysis** — reads existing code the spec touches, flags missing error handling, edge cases, validation gaps, and integration risks before implementation starts
+- **Spec integrity review** — checks completeness, consistency, feasibility, verification types, and gap analysis (7 checks)
 - **User approval gate** — spec must be explicitly approved before implementation starts
 
 ### IMPLEMENT — Build it
@@ -150,11 +151,14 @@ Follows: reproduce → isolate → root-cause → fix → verify.
 
 ### VERIFY — Test it
 
-- Translates acceptance criteria to automated tests
-- UI: Playwright MCP (navigate, click, assert)
-- API: curl requests with assertions
-- Logic: test suite execution
-- Reports pass/fail per AC with evidence
+- Reads the **declared verification type** from each AC — no keyword guessing
+- **UI_INTERACTION**: Playwright MCP (navigate, click, snapshot, screenshot, fill_form)
+- **API_ENDPOINT**: curl requests with status code and body assertions
+- **CLI_BEHAVIOR**: Bash command execution with stdout/stderr/exit code capture
+- **BUSINESS_LOGIC**: project test runner (bun test, npm test, vitest, jest, pytest)
+- **DATA_INTEGRITY**: database queries via CLI
+- ACs missing a Type field are marked FAIL — never skipped, never guessed
+- Reports pass/fail per AC with concrete evidence (screenshots, responses, test output)
 
 ### REVIEW — Check it
 
@@ -325,9 +329,15 @@ npx sdlc-framework@latest
 
 ---
 
-## What's New in v3.0.0
+## What's New in v3.1.0
 
-**Fewer commands, faster flow, zero idle time.**
+**Playwright actually works. Specs catch gaps before implementation.**
+
+- **Explicit verification types on every AC** — Each acceptance criterion now declares a `Type` field (`UI_INTERACTION`, `API_ENDPOINT`, `CLI_BEHAVIOR`, `BUSINESS_LOGIC`, `DATA_INTEGRITY`). The verify phase reads this field directly instead of guessing from keywords. Playwright MCP is now reliably invoked for UI acceptance criteria.
+- **Codebase gap analysis** — New mandatory step in `/sdlc:spec` reads existing code the spec touches and flags missing error handling, edge cases, validation gaps, integration risks, and untested paths. Gaps become new ACs and task updates before implementation starts.
+- **7 integrity checks** (up from 5) — Spec integrity review now validates verification type correctness and gap analysis completion.
+
+### Previous: v3.0.0
 
 - **Research merged into Discuss** — `/sdlc:discuss` now spawns research subagents inline when unknowns are detected. No separate `/sdlc:research` command needed. One entry point for all pre-spec discovery.
 - **Transition absorbed into Close** — `/sdlc:close` handles phase transitions inline when the last plan completes. Phase completeness verification, PROJECT.md updates, git commits — all automatic. No separate `/sdlc:transition` command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-framework",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Structured Development Lifecycle - A closed-loop AI-assisted development framework for Claude Code",
   "bin": {
     "sdlc-framework": "bin/install.js"

package/src/commands/spec.md

@@ -78,16 +78,18 @@ Step-by-step:
    - Option C (do nothing / defer): description, risk of deferring.
    Ask the user to choose before proceeding.
 
-5. **Define acceptance criteria in BDD format**
-   Write Given/When/Then scenarios for each user-facing behavior:
+5. **Define acceptance criteria in BDD format with verification type**
+   Write Given/When/Then scenarios for each user-facing behavior. Every AC MUST include a `Type` field that declares how the verify phase will test it:
    ```
    AC-1: [Short title]
+   Type: [UI_INTERACTION | API_ENDPOINT | CLI_BEHAVIOR | BUSINESS_LOGIC | DATA_INTEGRITY]
    Given [precondition]
    When [action]
    Then [expected outcome]
    ```
+   The Type field is mandatory — it tells `/sdlc:verify` whether to use Playwright MCP, curl, Bash, the test runner, or DB queries. Without it, the AC will be skipped during verification.
    Include happy path, error cases, and edge cases.
-   Present acceptance criteria to the user and ask: "Do these cover all cases? Anything to add or change?"
+   Present acceptance criteria with their types to the user and ask: "Do these cover all cases? Are the verification types correct?"
 
 6. **Break into tasks with dependency analysis**
    - List every discrete task needed to implement the spec.
@@ -106,7 +108,16 @@ Step-by-step:
    - What is OUT of scope.
    - What is DEFERRED to a future plan.
 
-8. **Write SPEC.md**
+8. **Codebase gap analysis — MANDATORY**
+   Read every file listed in the task breakdown. Review existing code for:
+   - Missing error handling that the spec should cover.
+   - Untested code paths that need new ACs.
+   - Edge cases the existing code handles but the spec does not mention.
+   - Integration risks (callers of modified functions, shared state, exports).
+   - Validation gaps at system boundaries.
+   Present a gap report to the user. Add new ACs (with verification_type) and update tasks for every gap found.
+
+9. **Write SPEC.md**
    Create .sdlc/specs/SPEC-<plan-id>.md with:
    ```
    # Spec: <title>
@@ -123,42 +134,48 @@ Step-by-step:
    ## Engineering Constraints (from LAWS.md)
    ```
 
-9. **Spec integrity review — MANDATORY, DO NOT SKIP**
-   You MUST print a full integrity review table with ✓/✗ for EACH check:
-   - CHECK 1 — COMPLETENESS: every task has name, action, files, verification, done criteria, complexity. Every AC has numbered GIVEN/WHEN/THEN with specific values.
-   - CHECK 2 — CONSISTENCY: no orphan tasks (every task → AC), no orphan ACs (every AC → task), no boundary violations, no DAG cycles, no shared-file parallel writes.
-   - CHECK 3 — CONTRADICTIONS: no conflicting ACs for same input, no conflicting task actions on same function, no task contradicting boundary, no AC contradicting PROJECT.md constraints.
-   - CHECK 4 — FEASIBILITY: task count 2-5, estimated change under ~300 lines, all referenced files exist.
-   - CHECK 5 — DEPENDENCY GRAPH: every task in exactly one wave, ordering matches dependencies, independent tasks parallelized, dependent tasks sequenced.
-   - Print the full review table with all results. Fix any failures before proceeding.
-
-10. **User approval gate** (BLOCKING — cannot proceed without approval)
+10. **Spec integrity review — MANDATORY, DO NOT SKIP**
+    You MUST print a full integrity review table with ✓/✗ for EACH check:
+    - CHECK 1 — COMPLETENESS: every task has name, action, files, verification, done criteria, complexity. Every AC has numbered Type/GIVEN/WHEN/THEN with specific values.
+    - CHECK 2 — CONSISTENCY: no orphan tasks (every task → AC), no orphan ACs (every AC → task), no boundary violations, no DAG cycles, no shared-file parallel writes.
+    - CHECK 3 — CONTRADICTIONS: no conflicting ACs for same input, no conflicting task actions on same function, no task contradicting boundary, no AC contradicting PROJECT.md constraints.
+    - CHECK 4 — FEASIBILITY: task count 2-5, estimated change under ~300 lines, all referenced files exist.
+    - CHECK 5 — DEPENDENCY GRAPH: every task in exactly one wave, ordering matches dependencies, independent tasks parallelized, dependent tasks sequenced.
+    - CHECK 6 — VERIFICATION TYPES: every AC has a valid Type field (UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, DATA_INTEGRITY). Type matches AC content.
+    - CHECK 7 — GAP ANALYSIS: codebase gap analysis was performed, gaps were reported, and findings were incorporated into ACs/tasks.
+    - Print the full review table with all results. Fix any failures before proceeding.
+
+11. **User approval gate** (BLOCKING — cannot proceed without approval)
     - Present full spec summary AND integrity review results to user
     - User options: APPROVE (proceed), REVISE (change and re-review), REJECT (discard)
     - If REVISE: apply changes, re-run ALL integrity checks, re-present
     - If REJECT: delete spec, stop
     - If APPROVE: proceed to update state
 
-11. **Update STATE.md**
+12. **Update STATE.md**
     - Set `current_plan: <plan-id>`
     - Set `spec_path: .sdlc/phases/{phase}/{plan}-SPEC.md`
     - Set `loop_position: SPEC ✓`
     - Set `next_required_action: /sdlc:impl`
 
-12. **Output confirmation**
-    - Print spec summary: objective, number of ACs, number of tasks, execution waves.
+13. **Output confirmation**
+    - Print spec summary: objective, number of ACs (with verification type breakdown), number of tasks, execution waves.
     - End with auto-advance directive to /sdlc:impl
 </process>
 
 <success_criteria>
 - [ ] At least 2 clarification questions asked before writing the spec
 - [ ] Every design decision presented with trade-offs and user confirmation
-- [ ] Acceptance criteria written in BDD format (Given/When/Then)
+- [ ] Acceptance criteria written in BDD format (Given/When/Then) with mandatory Type field
+- [ ] Every AC has a verification_type: UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, or DATA_INTEGRITY
+- [ ] Verification types match AC content (UI ACs test browser state, API ACs test endpoints, etc.)
 - [ ] Acceptance criteria cover happy path, error cases, and edge cases
 - [ ] Tasks broken into dependency graph with execution waves
 - [ ] Each task identifies files to create/modify and complexity
 - [ ] Boundaries section explicitly states in-scope, out-of-scope, and deferred items
-- [ ] Spec integrity review passed (completeness, consistency, feasibility)
+- [ ] Codebase gap analysis performed — existing code reviewed for missing logic, edge cases, and integration risks
+- [ ] Gap analysis findings incorporated into ACs and tasks (no silent gaps)
+- [ ] Spec integrity review passed (completeness, consistency, feasibility, verification types, gap analysis)
 - [ ] User explicitly approved the spec (APPROVE response received)
 - [ ] SPEC.md created at .sdlc/phases/{phase}/{plan}-SPEC.md
 - [ ] STATE.md updated with current_plan, spec_path, loop_position: SPEC ✓

package/src/commands/verify.md

@@ -49,18 +49,18 @@ Step-by-step:
    - Read SPEC.md. Extract all acceptance criteria (AC-1, AC-2, ...).
    - Read IMPL.md for the list of modified files and build status.
 
-2. **Classify each acceptance criterion by verification type**
-   For each AC, determine the appropriate test strategy:
-
-   | Work Type | Verification Method | Tools Used |
-   |-----------|-------------------|------------|
-   | UI/Frontend | Playwright MCP browser automation | browser_navigate, browser_click, browser_snapshot, browser_fill_form |
-   | REST API | HTTP requests via curl or fetch | Bash (curl commands) |
-   | GraphQL API | GraphQL queries via HTTP | Bash (curl commands) |
-   | CLI tool | Shell command execution | Bash |
-   | Business logic | Test runner (jest, vitest, pytest, etc.) | Bash (npm test, etc.) |
-   | Database | Query verification | Bash (database CLI tools) |
-   | File output | File content inspection | Read, Grep |
+2. **Read verification types from SPEC.md — DO NOT GUESS**
+   Each AC in the SPEC.md has a declared `Type` field. Read it directly. Do NOT infer or guess the type from keywords.
+
+   | AC Type (from SPEC.md) | Verification Tool | Actions |
+   |------------------------|------------------|---------|
+   | UI_INTERACTION | Playwright MCP | browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot |
+   | API_ENDPOINT | Bash curl | HTTP requests, response parsing |
+   | CLI_BEHAVIOR | Bash | Shell commands, stdout/stderr/exit code capture |
+   | BUSINESS_LOGIC | Test runner | bun test, npm test, vitest, jest, pytest |
+   | DATA_INTEGRITY | DB CLI | Database queries via Bash |
+
+   If any AC is missing its Type field, mark it FAIL immediately — do not skip it or guess.
 
 3. **Execute UI verifications (Playwright MCP)**
    For each UI acceptance criterion:
@@ -142,8 +142,13 @@ Step-by-step:
 
 <success_criteria>
 - [ ] Every acceptance criterion from SPEC.md has a corresponding verification
-- [ ] Correct verification type selected per AC (UI uses Playwright, API uses curl, etc.)
-- [ ] UI tests use Playwright MCP tools (navigate, snapshot, click, fill_form, screenshot)
+- [ ] Verification type READ from each AC's Type field — not guessed from keywords
+- [ ] ACs with Type: UI_INTERACTION verified using Playwright MCP tools (navigate, snapshot, click, fill_form, screenshot)
+- [ ] ACs with Type: API_ENDPOINT verified using curl commands
+- [ ] ACs with Type: CLI_BEHAVIOR verified using Bash command execution
+- [ ] ACs with Type: BUSINESS_LOGIC verified using the project test runner
+- [ ] ACs with Type: DATA_INTEGRITY verified using database queries
+- [ ] ACs missing a Type field marked FAIL — not skipped, not guessed
 - [ ] Each verification produces concrete evidence (screenshots, response bodies, test output)
 - [ ] VERIFY-<plan-id>.md created with per-AC pass/fail results
 - [ ] Failed ACs include: expected vs actual, root cause analysis, suggested fix, files to modify

package/src/workflows/spec-phase.md

@@ -141,39 +141,91 @@
 </step>
 
 <step name="write_acceptance_criteria" priority="fifth">
-  For each piece of observable behavior, write a BDD acceptance criterion:
+  For each piece of observable behavior, write a BDD acceptance criterion.
 
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  EVERY AC MUST INCLUDE A verification_type FIELD.                   ║
+  ║  This field is NOT optional. It is NOT inferred. It is DECLARED.    ║
+  ║  The verify phase reads this field to select the correct tool.      ║
+  ║  Without it, the AC will NOT be verified — it will be SKIPPED.      ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  FORMAT — every AC must follow this exact structure:
   ```
   AC-{N}: {short description}
+  Type: {verification_type}
   GIVEN {initial state or precondition}
   WHEN {action or trigger}
   THEN {expected outcome}
   ```
 
+  VERIFICATION TYPE — choose exactly ONE per AC:
+
+  | Type | When to Use | Verify Phase Tool |
+  |------|-------------|-------------------|
+  | UI_INTERACTION | The AC involves a browser, page, form, button, visual element, navigation, rendering, modal, dropdown, or any user-facing screen | Playwright MCP (browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot) |
+  | API_ENDPOINT | The AC involves an HTTP endpoint, request/response, status code, JSON body, REST or GraphQL call | Bash curl commands |
+  | CLI_BEHAVIOR | The AC involves a terminal command, stdout/stderr, exit code, file system output | Bash command execution |
+  | BUSINESS_LOGIC | The AC involves a function return value, calculation, transformation, validation rule, or internal behavior with no UI/API surface | Project test runner (bun test, npm test, vitest, jest, pytest) |
+  | DATA_INTEGRITY | The AC involves a database record, migration, schema constraint, or data consistency | Database CLI queries via Bash |
+
+  DECISION RULES for choosing the type:
+  1. If the user interacts with a browser to trigger the behavior → UI_INTERACTION
+  2. If the behavior is triggered by an HTTP request (even if there is also a UI) → choose based on WHAT the AC is testing:
+     - Testing the visual result in the browser → UI_INTERACTION
+     - Testing the API contract (status code, response body) → API_ENDPOINT
+  3. If the AC tests internal logic that has no user-facing surface → BUSINESS_LOGIC
+  4. If the AC tests a CLI tool or script → CLI_BEHAVIOR
+  5. If the AC tests data persistence or schema → DATA_INTEGRITY
+  6. When in doubt, prefer UI_INTERACTION — Playwright is the primary UAT tool
+
   Rules for writing good ACs:
   - Each AC tests ONE behavior (not multiple things)
   - The GIVEN sets up a specific, reproducible state
   - The WHEN is a single action (not a sequence)
   - The THEN is observable and verifiable (not "works correctly" — specify WHAT is correct)
   - Include at least one AC for the "happy path" and one for an error/edge case
+  - The verification_type MUST match the nature of the test — do NOT default everything to BUSINESS_LOGIC
 
-  Example (good):
+  Example (good — UI):
   ```
   AC-1: User login with valid credentials
+  Type: UI_INTERACTION
   GIVEN a registered user with email "test@example.com" and password "ValidPass123"
   WHEN the user submits the login form with those credentials
-  THEN a JWT token is returned with status 200 and the response body contains { "token": "<jwt>" }
+  THEN the browser redirects to /dashboard and displays "Welcome back" in the header
+  ```
+
+  Example (good — API):
+  ```
+  AC-2: Login API returns JWT token
+  Type: API_ENDPOINT
+  GIVEN a registered user with email "test@example.com" and password "ValidPass123"
+  WHEN a POST request is sent to /api/auth/login with { "email": "test@example.com", "password": "ValidPass123" }
+  THEN the response has status 200 and body contains { "token": "<jwt>" }
+  ```
+
+  Example (good — CLI):
+  ```
+  AC-3: Install command copies files to target
+  Type: CLI_BEHAVIOR
+  GIVEN an empty target directory at /tmp/test-install
+  WHEN the user runs "node bin/install.js --local --target /tmp/test-install"
+  THEN the directory /tmp/test-install/commands/sdlc/ contains 12 command files and exit code is 0
   ```
 
-  Example (bad — too vague):
+  Example (bad — missing Type):
   ```
   AC-1: Login works
   GIVEN a user
   WHEN they log in
   THEN it works
   ```
+  This AC is INVALID: no Type field, vague GIVEN/WHEN/THEN, untestable.
 
-  WHY: The verify phase translates ACs directly into test actions. Vague ACs produce vague tests that pass even when the code is broken. Specific ACs catch real bugs.
+  Present ACs to user with their types and ask: "Do these cover all cases? Are the verification types correct?"
+
+  WHY: The verify phase reads the Type field to select Playwright MCP, curl, Bash, or the test runner. Without an explicit type, the verify phase guesses based on keywords — and guesses wrong. This field is the contract between spec and verify. It MUST be present on every AC.
 </step>
 
 <step name="define_boundaries" priority="sixth">
@@ -196,7 +248,114 @@
   WHY: Without boundaries, sub-agents during implementation will "helpfully" refactor nearby code, breaking things outside the spec scope. Boundaries are guardrails.
 </step>
 
-<step name="write_spec_file" priority="seventh">
+<step name="codebase_gap_analysis" priority="seventh">
+  ╔══════════════════════════════════════════════════════════════════════╗
+  ║  THIS STEP IS MANDATORY. DO NOT SKIP. DO NOT ABBREVIATE.           ║
+  ║  Review the EXISTING code that this spec touches BEFORE writing     ║
+  ║  the spec file. Gaps found here become new ACs or task updates.     ║
+  ╚══════════════════════════════════════════════════════════════════════╝
+
+  PURPOSE: Catch missing logic, incomplete requirements, and hidden dependencies
+  by reading the actual code BEFORE implementation begins. A spec written without
+  reading the code it modifies will miss error handling, edge cases, validation,
+  and integration points that only the code reveals.
+
+  PROCEDURE:
+
+  1. IDENTIFY FILES TO REVIEW:
+     Collect every file path listed in the tasks from step "task_decomposition":
+     - Files to modify (existing code that will change)
+     - Files adjacent to modified files (same directory — they may share types, imports, or patterns)
+     - Test files for modified files (if they exist)
+     Do NOT review files listed in Boundaries/DO NOT CHANGE.
+
+  2. READ EACH FILE and check for these gap categories:
+
+     A. MISSING ERROR HANDLING:
+        - Does the code handle null/undefined returns from functions the spec will call?
+        - Are there try/catch blocks around operations that can fail (network, file I/O, DB)?
+        - Does the code validate input at system boundaries (controllers, API handlers)?
+        - Are there error paths that the spec's ACs do not cover?
+        → If gaps found: create new ACs with Type: BUSINESS_LOGIC or Type: API_ENDPOINT for each uncovered error path.
+
+     B. INCOMPLETE EDGE CASES:
+        - Empty arrays, empty strings, zero values — does the code handle them?
+        - Concurrent access — can two users hit this code path simultaneously?
+        - Partial failures — what happens if step 2 of 3 fails?
+        - Boundary values — maximum lengths, integer overflow, special characters?
+        → If gaps found: add edge case ACs or expand THEN clauses in existing ACs.
+
+     C. MISSING VALIDATION:
+        - Are there function parameters that accept any value but should be constrained?
+        - Are there user inputs that reach business logic without sanitization?
+        - Are there type assertions or casts that assume a shape without checking?
+        → If gaps found: add validation tasks or expand existing tasks to include validation.
+
+     D. INTEGRATION RISKS:
+        - Does the modified code export types/functions used by OTHER files not in the spec?
+        - Will changing a function signature break its callers?
+        - Are there shared state or singleton patterns that could cause side effects?
+        - Does the code depend on environment variables, config, or feature flags not mentioned in the spec?
+        → If gaps found: add integration ACs or expand Boundaries to protect callers.
+
+     E. UNTESTED PATHS:
+        - Read existing test files for the modified code.
+        - Are there public methods with zero test coverage?
+        - Are there conditional branches (if/else, switch) where only one branch is tested?
+        - Does the spec add new behavior that existing tests do not cover?
+        → If gaps found: add BUSINESS_LOGIC ACs for untested paths, or add test tasks.
+
+     F. PATTERN VIOLATIONS:
+        - Does the existing code follow patterns (error handling, naming, structure) that the spec's tasks should also follow?
+        - Are there established abstractions (base classes, utilities, factories) that the spec should reuse instead of reinventing?
+        → If gaps found: update tasks to reference existing patterns. Add to Required Patterns section.
+
+  3. COMPILE GAP REPORT:
+     Present findings to the user in this format:
+     ```
+     ══════════════════════════════════════════════
+     CODEBASE GAP ANALYSIS
+     ══════════════════════════════════════════════
+     Files reviewed: {N}
+
+     Gaps found: {N}
+
+     GAP-1: {category} — {file}:{line range}
+       Problem: {what is missing or incomplete}
+       Impact: {what could go wrong during implementation or in production}
+       Recommendation: {add AC / expand task / add to boundaries}
+
+     GAP-2: ...
+
+     New ACs to add: {N}
+     Tasks to update: {N}
+     Boundaries to add: {N}
+
+     No gaps found in: {list categories with no issues}
+     ══════════════════════════════════════════════
+     ```
+
+  4. APPLY FIXES:
+     For each gap:
+     - If it requires a new AC → add the AC with the correct verification_type to the AC list
+     - If it requires expanding an existing task → update the task's action and done criteria
+     - If it reveals an out-of-scope dependency → add to Boundaries
+     - If it reveals a required pattern → add to Required Patterns
+
+     Do NOT silently absorb gaps. Every gap MUST appear in the report and result in a spec change.
+
+  5. RE-PRESENT UPDATED ACs AND TASKS:
+     After applying fixes, show the user the updated AC list and any changed tasks.
+     Ask: "I found {N} gaps in the existing code. Here are the additions. Do these look right?"
+
+  WHY: Specs written in a vacuum miss what the code actually does. A login spec might
+  forget rate limiting because the spec author did not read the auth middleware. A form
+  spec might miss accessibility because the spec author did not see the existing aria
+  patterns. This step forces the spec to account for reality — not just intent. It is
+  the difference between a spec that sounds right and a spec that IS right.
+</step>
+
+<step name="write_spec_file" priority="eighth">
   Write the spec to: .sdlc/phases/{phase-dir}/{plan-number}-SPEC.md
 
   Format:
@@ -245,12 +404,16 @@
   ## Acceptance Criteria
 
   AC-1: {description}
+  Type: {UI_INTERACTION | API_ENDPOINT | CLI_BEHAVIOR | BUSINESS_LOGIC | DATA_INTEGRITY}
   GIVEN {precondition}
   WHEN {action}
   THEN {outcome}
 
   AC-2: ...
 
+  ## Codebase Gap Analysis
+  {Summary of gaps found in existing code, with GAP-N references to ACs/tasks they generated}
+
   ## Boundaries
   - DO NOT modify: {files/modules}
   - DO NOT implement: {out-of-scope features}
@@ -267,7 +430,7 @@
   WHY: The YAML frontmatter is machine-readable — the impl phase parses it to build the execution plan. The markdown body is human-readable — developers can review it. Both are needed.
 </step>
 
-<step name="spec_integrity_review" priority="eighth">
+<step name="spec_integrity_review" priority="ninth">
   ╔══════════════════════════════════════════════════════════════════════╗
   ║  THIS STEP IS MANDATORY. DO NOT SKIP. DO NOT ABBREVIATE.           ║
   ║  You MUST print the full integrity review table before proceeding.  ║
@@ -286,6 +449,7 @@
   - [ ] complexity (LOW/MEDIUM/HIGH)
   For each AC, verify it has ALL of these (print each):
   - [ ] AC number (AC-1, AC-2, etc.)
+  - [ ] Type field with valid verification_type (UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, or DATA_INTEGRITY)
   - [ ] GIVEN with specific precondition (not "given the system is running")
   - [ ] WHEN with specific action (not "when the user does something")
   - [ ] THEN with specific observable outcome (not "then it works correctly")
@@ -321,11 +485,26 @@
   - [ ] Independent tasks (no shared files, no shared types) are correctly parallelized
   - [ ] Dependent tasks (shared files, shared types/interfaces) are correctly sequenced
 
+  CHECK 6 — VERIFICATION TYPE VALIDITY:
+  - [ ] Every AC has a Type field (no AC without a Type)
+  - [ ] Every Type is one of: UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, DATA_INTEGRITY
+  - [ ] Type matches the AC content (UI ACs reference browser/page/form elements, API ACs reference endpoints/status codes, etc.)
+  - [ ] ACs with Type: UI_INTERACTION have THEN clauses that reference observable browser state (page content, URL, visible elements) — not internal state
+  - [ ] ACs with Type: API_ENDPOINT have WHEN clauses that specify HTTP method and endpoint path
+  - [ ] ACs with Type: CLI_BEHAVIOR have WHEN clauses that specify the exact command to run
+
+  CHECK 7 — CODEBASE GAP ANALYSIS COMPLETED:
+  - [ ] The codebase_gap_analysis step was executed (not skipped)
+  - [ ] Files listed in tasks were read and reviewed for gaps
+  - [ ] Gap report was presented to user
+  - [ ] Any gaps found resulted in new ACs or updated tasks (no silent absorption)
+  - [ ] Codebase Gap Analysis section exists in the spec file
+
   IF ANY CHECK ITEM FAILS:
   1. List all failures with specific descriptions
   2. Propose a fix for each failure
   3. Apply all fixes to the SPEC.md
-  4. Re-run ALL five checks on the updated spec
+  4. Re-run ALL seven checks on the updated spec
   5. Repeat until all checks pass
 
   PRINT the full integrity review report:
@@ -333,17 +512,29 @@
   ══════════════════════════════════════════════
   SPEC INTEGRITY REVIEW
   ══════════════════════════════════════════════
-  Completeness:      {✓ or ✗} — {details}
-  Consistency:       {✓ or ✗} — {details}
-  Contradictions:    {✓ or ✗} — {details or "none found"}
-  Feasibility:       {✓ or ✗} — {details}
-  Dependency Graph:  {✓ or ✗} — {details}
+  Completeness:        {✓ or ✗} — {details}
+  Consistency:         {✓ or ✗} — {details}
+  Contradictions:      {✓ or ✗} — {details or "none found"}
+  Feasibility:         {✓ or ✗} — {details}
+  Dependency Graph:    {✓ or ✗} — {details}
+  Verification Types:  {✓ or ✗} — {details}
+  Gap Analysis:        {✓ or ✗} — {details}
 
   Tasks: {N} fully defined
-  ACs: {N} with specific Given/When/Then
+  ACs: {N} with specific Given/When/Then and verification_type
   Waves: {N} parallel execution groups
   Estimated scope: ~{N} lines across {N} files
 
+  Verification type breakdown:
+  - UI_INTERACTION: {N} ACs (Playwright MCP)
+  - API_ENDPOINT: {N} ACs (curl)
+  - CLI_BEHAVIOR: {N} ACs (Bash)
+  - BUSINESS_LOGIC: {N} ACs (test runner)
+  - DATA_INTEGRITY: {N} ACs (DB queries)
+
+  Codebase gaps found: {N}
+  {if any: list each gap and the AC/task it generated}
+
   Contradictions found: {N}
   {if any: list each contradiction and how it was resolved}
 
@@ -352,10 +543,10 @@
   ══════════════════════════════════════════════
   ```
 
-  WHY: A spec with contradictions produces agents that build conflicting code. A spec with orphan ACs means untested features. A spec with invalid dependencies means agents wait forever or overwrite each other. This review catches all of these. It costs 30 seconds now and saves hours of debugging later.
+  WHY: A spec with contradictions produces agents that build conflicting code. A spec with orphan ACs means untested features. A spec with invalid dependencies means agents wait forever or overwrite each other. A spec without verification types means the verify phase guesses and skips Playwright. A spec without gap analysis means missing logic ships undetected. This review catches all of these.
 </step>
 
-<step name="user_approval_gate" priority="ninth">
+<step name="user_approval_gate" priority="tenth">
   THIS IS A BLOCKING GATE. The spec does NOT proceed without explicit user approval.
 
   Present the complete spec summary to the user:
@@ -409,7 +600,7 @@
   WHY: Implementation is expensive. Building the wrong thing wastes hours. A 30-second review of the spec catches misunderstandings before they become code. The user MUST see and approve the plan before sub-agents start writing code.
 </step>
 
-<step name="update_state" priority="tenth">
+<step name="update_state" priority="eleventh">
   ONLY REACHED AFTER USER APPROVES THE SPEC.
 
   Update .sdlc/STATE.md:

package/src/workflows/verify-phase.md

@@ -45,38 +45,43 @@
   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.)
+<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." ║
+  ╚══════════════════════════════════════════════════════════════════════╝
 
-  TYPE: API_ENDPOINT
-  Indicators: mentions endpoint, request, response, status code, JSON body, header, GET/POST/PUT/DELETE
-  Method: Bash curl commands
+  For each AC extracted in the previous step, read its declared Type field.
 
-  TYPE: CLI_BEHAVIOR
-  Indicators: mentions command, terminal, output, exit code, stderr, stdout, flag, argument
-  Method: Bash command execution
+  VALID TYPES AND THEIR VERIFICATION TOOLS:
 
-  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 | 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 |
 
-  TYPE: DATA_INTEGRITY
-  Indicators: mentions database, record, row, column, migration, schema, constraint
-  Method: Database queries via Bash or ORM commands
+  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. Do NOT skip the AC silently.
+  4. Include this failure in the verification report.
+  5. The overall verification FAILS if any AC is missing its Type.
 
-  Present classification to proceed:
+  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})
+  AC-3: {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, prevents misclassification, and ensures Playwright MCP is actually invoked for UI acceptance criteria. This is the contract between spec and verify — the spec says WHAT tool to use, the verify phase USES that tool.
 </step>
 
 <step name="verify_ui_interactions" priority="fourth">