sdlc-framework 1.0.0

package/src/references/loop-phases.md

@@ -0,0 +1,331 @@
+# SDLC Loop Phases Reference
+
+This document explains the five phases of the SDLC loop for developers who are new to structured development lifecycles. It covers what each phase does, what it produces, how phases connect, and why closing the loop matters.
+
+---
+
+## The Big Picture
+
+The SDLC loop is five phases that every piece of work goes through:
+
+```
+SPEC ──▶ IMPLEMENT ──▶ VERIFY ──▶ REVIEW ──▶ CLOSE
+  ▲                                              │
+  └──────────────────────────────────────────────┘
+                    (next iteration)
+```
+
+Each phase has a specific job. Skipping a phase creates problems that compound over time. The loop closes when all five phases complete successfully, and then a new loop begins for the next piece of work.
+
+---
+
+## Phase 1: SPEC (Specification)
+
+### What It Does
+
+The spec phase answers: **What are we building, and why?**
+
+Before writing any code, the spec phase:
+1. Clarifies requirements by asking questions (no guessing)
+2. Defines acceptance criteria in testable BDD format
+3. Breaks the work into discrete tasks
+4. Identifies which tasks can run in parallel
+5. Draws boundaries (what NOT to change)
+
+### What It Produces
+
+A spec document (SPEC.md) containing:
+- Clear objective (goal, purpose, output)
+- Clarification audit trail (questions asked, answers received)
+- Numbered acceptance criteria (AC-1, AC-2, etc.)
+- Task list with dependencies
+- Task dependency graph
+- Boundary definitions
+
+### Why It Exists
+
+Without a spec, the developer starts coding based on assumptions. Assumptions are often wrong. The developer builds the wrong thing, discovers this during review, and starts over. A spec that takes 15 minutes to write saves hours of rework.
+
+### Common Mistakes
+
+- **Skipping clarification:** "I know what they want" — you probably do not.
+- **Vague acceptance criteria:** "It should work" is not testable. "Given X, When Y, Then Z" is.
+- **Missing boundaries:** Without a "do not touch" list, developers refactor code they should not.
+
+---
+
+## Phase 2: IMPLEMENT (Implementation)
+
+### What It Does
+
+The implementation phase answers: **How do we build it?**
+
+Using the spec as a blueprint:
+1. Analyzes the task dependency graph
+2. Groups independent tasks into parallel waves
+3. Assigns tasks to sub-agents (or executes inline for simple work)
+4. Executes tasks wave by wave, integrating outputs between waves
+5. Marks each task as done in the spec
+
+### What It Produces
+
+- Working code that implements all tasks in the spec
+- Updated spec with completed task checkmarks
+- Any decisions made during implementation (recorded in the spec or state file)
+
+### Why It Exists
+
+Implementation without a spec is random typing. Implementation with a spec is directed construction. The spec tells the developer exactly which files to create, what each function should do, and how to verify completion. No time is wasted deciding what to build next.
+
+### Common Mistakes
+
+- **Going beyond the spec:** "While I'm here, I'll also add..." — YAGNI. Build what is in the spec.
+- **Ignoring the dependency graph:** Starting tasks whose dependencies are not complete leads to rework.
+- **Not recording decisions:** Decisions made during implementation that are not in the spec must be recorded. Otherwise, the reviewer does not understand why something was built a certain way.
+
+---
+
+## Phase 3: VERIFY (Verification)
+
+### What It Does
+
+The verification phase answers: **Does it actually work?**
+
+For each acceptance criterion in the spec:
+1. Set up the preconditions (the "Given")
+2. Perform the action (the "When")
+3. Check the result (the "Then")
+4. Collect evidence (screenshots, test output, API responses)
+
+### What It Produces
+
+- Pass/fail status for each acceptance criterion
+- Evidence for each check (screenshots, test output)
+- List of any criteria that failed and why
+
+### Why It Exists
+
+Code that compiles is not code that works. The implementation phase produces code that the developer believes is correct. The verification phase proves it. Every acceptance criterion gets checked. No assumptions. No "it probably works."
+
+### Verification Methods
+
+| Work Type | Primary Verification | Fallback |
+|-----------|---------------------|----------|
+| UI features | Playwright MCP (navigate, interact, screenshot) | Manual browser testing |
+| API endpoints | Playwright `browser_evaluate` with fetch, or curl | Integration tests |
+| Business logic | Unit test runner (npm test) | Manual function calls |
+| Refactors | Existing test suite (all tests still pass) | Before/after behavior comparison |
+| Bug fixes | Reproduce the bug, verify it is gone | Regression test |
+
+### Common Mistakes
+
+- **Only testing the happy path:** If AC-1 passes but AC-3 (the error case) was skipped, verification is incomplete.
+- **Verifying in the wrong environment:** Testing against a mock database when the AC specifies "real data." Use the environment the spec defines.
+- **Not collecting evidence:** Without screenshots or test output, the reviewer has no proof. Verification without evidence is just another assumption.
+
+---
+
+## Phase 4: REVIEW (Code Review)
+
+### What It Does
+
+The review phase answers: **Is the code good enough?**
+
+Every file created or modified during implementation is reviewed against the engineering laws:
+1. SOLID — proper structure and separation
+2. DRY — no duplicate logic
+3. YAGNI — nothing beyond the spec
+4. Clean Code — small functions, shallow nesting
+5. Security — no hardcoded secrets, input validation
+6. Testing — every behavior has a test
+7. Naming — descriptive, consistent names
+8. Error Handling — no empty catches, domain-specific exceptions
+
+### What It Produces
+
+A review document (REVIEW.md) containing:
+- List of files reviewed
+- Findings with severity (error, warning, info)
+- For each finding: file, line numbers, law violated, description, suggested fix
+- Overall assessment and blocking status
+
+### Why It Exists
+
+Verification proves the code works. Review proves the code is maintainable. Code that works but violates engineering laws creates technical debt. Technical debt compounds. A 5-minute shortcut today becomes a 5-hour debugging session next month.
+
+### What Blocks Closure
+
+Findings at `error` severity block loop closure. The developer must fix the issues and re-run the review. Findings at `warning` severity are reported but do not block. Findings at `info` severity are noted.
+
+### Common Mistakes
+
+- **Treating warnings as ignorable:** Warnings are "fix this soon." Not fixing them means they accumulate until the codebase is drowning in minor issues.
+- **Fixing symptoms, not causes:** A reviewer says "this function is too long." The developer splits it into two functions that are both still too long. Fix the root cause — extract meaningful helper functions.
+- **Arguing with the law:** "But my 60-line function is readable!" The law says 40 lines. Refactor.
+
+---
+
+## Phase 5: CLOSE (Loop Closure)
+
+### What It Does
+
+The close phase answers: **Are we done, and what did we learn?**
+
+Loop closure:
+1. Confirms all acceptance criteria passed
+2. Confirms all error-severity review findings are resolved
+3. Produces a summary document with deliverables, results, and lessons learned
+4. Updates the roadmap and state files
+5. Sets the next action for the next loop iteration
+
+### What It Produces
+
+A summary document (SUMMARY.md) containing:
+- Deliverables (what was built)
+- Acceptance criteria results (pass/fail with evidence)
+- Deviations from the spec (planned vs actual)
+- Decisions made during implementation
+- Engineering laws review results
+- Files modified
+- Lessons learned
+
+### Why It Exists
+
+Without closure, work is "sort of done." Is it done-done? Did everything pass? Were there deviations? Nobody knows because nobody wrote it down. Closure creates a clear record that this work is complete, what was delivered, and what to work on next.
+
+### Closure Checklist
+
+The loop cannot close unless:
+- [ ] All acceptance criteria have a pass/fail status
+- [ ] All `error` severity findings are resolved
+- [ ] A summary document is written
+- [ ] The state file is updated with the next action
+- [ ] The roadmap is updated to reflect progress
+
+### Common Mistakes
+
+- **Skipping lessons learned:** "We'll remember." You will not. Write it down.
+- **Leaving the next action empty:** The next developer (or the next session) opens the project and does not know what to do. Every close must set the next action.
+- **Closing with unresolved blockers:** If there is a blocker, the loop does not close. Address it or defer it explicitly.
+
+---
+
+## How Phases Connect
+
+Each phase consumes the output of the previous phase:
+
+```
+SPEC produces → spec document
+  ↓
+IMPLEMENT consumes spec → produces working code
+  ↓
+VERIFY consumes acceptance criteria → produces pass/fail evidence
+  ↓
+REVIEW consumes code changes → produces findings
+  ↓
+CLOSE consumes all outputs → produces summary + next action
+```
+
+If a phase fails, it loops back:
+- **Verify fails:** Go back to IMPLEMENT. Fix the code. Re-verify.
+- **Review fails:** Go back to IMPLEMENT. Fix the findings. Re-review.
+- **Spec is incomplete:** Stay in SPEC. Ask more questions. Update the spec.
+
+The loop never skips forward. You cannot review before verifying. You cannot close before reviewing.
+
+---
+
+## What "Closing the Loop" Means
+
+Closing the loop means all five phases completed successfully for one unit of work (one plan). The result is:
+- Working, verified code
+- No error-severity engineering law violations
+- A complete audit trail (spec, review, summary)
+- A clear next action for the next iteration
+
+When the loop closes, the system resets for the next plan. The state file updates. The roadmap advances. The developer knows exactly what to do next.
+
+---
+
+## With Loop vs Without Loop
+
+### Without a Loop (Ad-Hoc Development)
+
+1. Developer gets a vague request: "Add user search."
+2. Starts coding immediately. Guesses at requirements.
+3. Builds search with filters, sorting, and pagination (nobody asked for pagination).
+4. Does not write tests ("I'll add them later").
+5. Discovers the stakeholder wanted search by name only, not the full-featured search.
+6. Reworks half the code. Still no tests.
+7. Ships with a hardcoded API key in the config.
+8. Next developer opens the codebase: "What was built? Is it done? What do I work on next?"
+
+**Result:** Wrong thing built, no tests, security issue, no documentation, confused team.
+
+### With a Loop (SDLC)
+
+1. Developer gets the request: "Add user search."
+2. **SPEC:** Asks clarifying questions. "Search by what fields? How should results be sorted? Any pagination needed?" Stakeholder says: "Just name search, alphabetical, no pagination."
+3. **IMPLEMENT:** Builds exactly what the spec says. Name search, alphabetical sort, no pagination.
+4. **VERIFY:** Tests that search by name works, results are sorted, and error case (no results) is handled.
+5. **REVIEW:** Code checked against engineering laws. One warning for a vague variable name. Fixed.
+6. **CLOSE:** Summary written. Tests pass. No pagination to rip out later. Next action set.
+
+**Result:** Right thing built, tested, reviewed, documented, clear path forward.
+
+---
+
+## Visual Diagrams
+
+### Single Loop Iteration
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    ONE LOOP                          │
+│                                                     │
+│  ┌──────┐   ┌──────────┐   ┌────────┐   ┌────────┐│   ┌───────┐
+│  │ SPEC │──▶│IMPLEMENT │──▶│ VERIFY │──▶│ REVIEW ││──▶│ CLOSE │
+│  └──────┘   └──────────┘   └────────┘   └────────┘│   └───────┘
+│      │            ▲             │             │     │       │
+│      │            │             │             │     │       │
+│      │            └─────────────┘             │     │       │
+│      │            (verify fails → re-impl)    │     │       │
+│      │                                        │     │       │
+│      │            ▲                           │     │       │
+│      │            └───────────────────────────┘     │       │
+│      │            (review fails → re-impl)          │       │
+│      │                                              │       │
+└──────│──────────────────────────────────────────────┘       │
+       │                                                      │
+       └──────────────────────────────────────────────────────┘
+                         (next plan)
+```
+
+### Multiple Loops in a Phase
+
+```
+Phase 1: Authentication
+├── Loop 1: Spec → Impl → Verify → Review → Close (user login)
+├── Loop 2: Spec → Impl → Verify → Review → Close (password reset)
+└── Loop 3: Spec → Impl → Verify → Review → Close (session management)
+
+Phase 2: User Management
+├── Loop 4: Spec → Impl → Verify → Review → Close (CRUD operations)
+├── Loop 5: Spec → Impl → Verify → Review → Close (role-based access)
+└── Loop 6: Spec → Impl → Verify → Review → Close (user search)
+```
+
+### Milestone Progression
+
+```
+Milestone 1: MVP
+├── Phase 1 ── Loop 1 ── Loop 2 ── Loop 3
+├── Phase 2 ── Loop 4 ── Loop 5
+└── Phase 3 ── Loop 6 ── Loop 7 ── Loop 8
+
+Milestone 2: v1.0
+├── Phase 4 ── Loop 9 ── Loop 10
+└── Phase 5 ── Loop 11
+```
+
+Each loop is one complete iteration of SPEC → IMPLEMENT → VERIFY → REVIEW → CLOSE.

package/src/references/playwright-testing.md

@@ -0,0 +1,298 @@
+# Playwright MCP Verification Reference
+
+This document explains how to use Playwright MCP tools for verification during the `/sdlc:verify` phase. It covers the available tools, how to translate acceptance criteria into Playwright sequences, and common pitfalls.
+
+---
+
+## Available MCP Tools
+
+The SDLC framework uses Playwright through the Model Context Protocol (MCP). These are the tools available for browser-based verification.
+
+### Navigation
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_navigate` | Go to a URL | `url` — the full URL to navigate to |
+| `browser_navigate_back` | Go back one page | (none) |
+| `browser_tabs` | List open tabs | (none) |
+
+### Interaction
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_click` | Click an element | `element` — description or selector of what to click |
+| `browser_fill_form` | Fill a form field | `element` — the field, `value` — what to type |
+| `browser_type` | Type text (character by character) | `text` — the text to type |
+| `browser_press_key` | Press a keyboard key | `key` — the key name (Enter, Tab, Escape, etc.) |
+| `browser_select_option` | Select from a dropdown | `element` — the dropdown, `value` — the option |
+| `browser_hover` | Hover over an element | `element` — what to hover over |
+| `browser_drag` | Drag an element | `startElement`, `endElement` |
+| `browser_file_upload` | Upload a file | `element` — the file input, `paths` — file paths |
+
+### Observation
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_snapshot` | Get the current page accessibility tree (like a text representation of the page) | (none) |
+| `browser_take_screenshot` | Capture a screenshot | (none) |
+| `browser_console_messages` | Get browser console output | (none) |
+| `browser_network_requests` | Get network request log | (none) |
+
+### Control
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_wait_for` | Wait for a condition | `condition` — what to wait for |
+| `browser_handle_dialog` | Accept or dismiss a dialog | `action` — accept or dismiss |
+| `browser_evaluate` | Run JavaScript in the page | `code` — JavaScript to execute |
+| `browser_run_code` | Run JavaScript for complex automation | `code` — JavaScript code |
+| `browser_resize` | Resize the browser window | `width`, `height` |
+| `browser_close` | Close the browser | (none) |
+| `browser_install` | Install browser binaries | (none) |
+
+---
+
+## Translating BDD Criteria to Playwright Sequences
+
+Each acceptance criterion in BDD format (Given/When/Then) maps directly to a sequence of Playwright MCP tool calls.
+
+### The Pattern
+
+```
+Given → Setup (navigate, fill prerequisites)
+When  → Action (click, type, submit)
+Then  → Assert (snapshot + verify content, screenshot for evidence)
+```
+
+### Example 1: Login Form
+
+**Acceptance Criterion:**
+```
+AC-1: Successful login
+Given a registered user with email "alice@example.com" and password "secure123"
+When the user navigates to /login and submits valid credentials
+Then the user is redirected to /dashboard and sees "Welcome, Alice"
+```
+
+**Playwright Sequence:**
+
+```
+1. browser_navigate → url: "http://localhost:3000/login"
+2. browser_snapshot → verify login form is visible
+3. browser_fill_form → element: "email input", value: "alice@example.com"
+4. browser_fill_form → element: "password input", value: "secure123"
+5. browser_click → element: "Login button"
+6. browser_wait_for → condition: "navigation to /dashboard"
+7. browser_snapshot → verify page contains "Welcome, Alice"
+8. browser_take_screenshot → evidence for review
+```
+
+### Example 2: Form Validation
+
+**Acceptance Criterion:**
+```
+AC-2: Email validation error
+Given an empty login form
+When the user submits without entering an email
+Then an error message "Email is required" appears below the email field
+```
+
+**Playwright Sequence:**
+
+```
+1. browser_navigate → url: "http://localhost:3000/login"
+2. browser_click → element: "Login button" (submit empty form)
+3. browser_snapshot → verify error message "Email is required" is visible
+4. browser_take_screenshot → evidence
+```
+
+### Example 3: API Response Verification
+
+**Acceptance Criterion:**
+```
+AC-3: User list API returns paginated results
+Given the database has 50 users
+When a GET request is made to /api/users?page=1&limit=10
+Then the response contains 10 users and a total count of 50
+```
+
+**Playwright Sequence:**
+
+```
+1. browser_evaluate → code: `fetch('/api/users?page=1&limit=10').then(r => r.json())`
+2. Verify the result contains 10 items and totalCount === 50
+```
+
+Alternatively, use `browser_network_requests` after navigating to a page that triggers the API call.
+
+---
+
+## Screenshot Evidence Collection
+
+Screenshots provide visual proof that acceptance criteria passed. They are stored alongside the review and summary documents.
+
+### Best Practices
+
+- **Take screenshots after assertions, not before.** The screenshot should show the passing state.
+- **Name screenshots descriptively.** Use the AC number: `AC-001-login-success.png`.
+- **Capture the relevant viewport.** Use `browser_resize` to set a consistent viewport before screenshots.
+- **Include error states.** If testing error handling, screenshot the error message.
+
+### Standard Viewport Sizes
+
+| Device | Width | Height |
+|--------|-------|--------|
+| Desktop | 1280 | 720 |
+| Tablet | 768 | 1024 |
+| Mobile | 375 | 667 |
+
+Use `browser_resize` to set the viewport before taking screenshots for responsive testing.
+
+---
+
+## Handling Dynamic Content
+
+Web applications often have content that changes: loading spinners, animations, data that loads asynchronously.
+
+### Loading States
+
+Use `browser_wait_for` to wait for content to appear before asserting:
+
+```
+1. browser_navigate → url: "http://localhost:3000/dashboard"
+2. browser_wait_for → condition: "Loading spinner disappears"
+3. browser_wait_for → condition: "User list is visible"
+4. browser_snapshot → verify content
+```
+
+### Animations
+
+Animations can cause flaky assertions if the snapshot captures a mid-animation state:
+
+- Wait for animations to complete before taking snapshots.
+- Use `browser_evaluate` to check CSS animation state if needed:
+  ```javascript
+  document.querySelector('.modal').getAnimations().every(a => a.playState === 'finished')
+  ```
+
+### Asynchronous Data
+
+Data loaded via API calls may not be present immediately after navigation:
+
+```
+1. browser_navigate → url: "http://localhost:3000/users"
+2. browser_wait_for → condition: "Table contains user rows"
+3. browser_snapshot → verify data
+```
+
+### Time-Dependent Content
+
+Timestamps, "5 minutes ago" labels, and countdown timers change between test runs:
+
+- Assert on stable parts of the content (user name, status) rather than volatile parts (timestamps).
+- Use `browser_evaluate` to freeze time if needed: `Date.now = () => 1700000000000`.
+
+---
+
+## Fallback Verification (Non-UI Work)
+
+Not all specs produce UI changes. For backend, library, or CLI work, use alternative verification methods.
+
+### Test Runner Verification
+
+For specs that produce testable code, run the test suite:
+
+```bash
+npm test -- --grep "UserService"
+```
+
+Verify that:
+- All tests pass.
+- New tests exist for new behavior.
+- No existing tests broke.
+
+### API Verification with curl
+
+For API endpoints without a frontend:
+
+```bash
+# Test endpoint exists and returns correct status
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/api/health
+
+# Test response body
+curl -s http://localhost:3000/api/users/1 | jq '.name'
+```
+
+### CLI Verification
+
+For CLI tools:
+
+```bash
+# Test command exists and runs
+node dist/cli.js --help
+
+# Test specific behavior
+node dist/cli.js create-user --name Alice --email alice@example.com
+echo $?  # verify exit code
+```
+
+### File System Verification
+
+For specs that generate files:
+
+```bash
+# Verify file exists
+test -f dist/output.json && echo "exists"
+
+# Verify file content
+cat dist/output.json | jq '.version'
+```
+
+---
+
+## Common Pitfalls and Solutions
+
+### Pitfall 1: Element Not Found
+
+**Problem:** `browser_click` or `browser_fill_form` cannot find the element.
+**Cause:** The element has not loaded yet, or the selector is wrong.
+**Solution:** Use `browser_snapshot` first to see the accessibility tree. Find the element's actual label or description, then use that in the tool call. Use `browser_wait_for` if the element loads asynchronously.
+
+### Pitfall 2: Navigation Timing
+
+**Problem:** Asserting on a page before navigation completes.
+**Cause:** `browser_click` on a link triggers navigation, but the new page is not ready yet.
+**Solution:** After clicking a navigation link, use `browser_wait_for` with a condition that indicates the new page loaded (specific text, specific element).
+
+### Pitfall 3: Stale State
+
+**Problem:** Previous test's state affects current test.
+**Cause:** Browser session persists between verifications. A logged-in user from AC-1 is still logged in for AC-2.
+**Solution:** Either use the persisted state intentionally (if AC-2 requires login) or navigate to a logout endpoint / clear cookies before the next AC.
+
+### Pitfall 4: Form Auto-Complete
+
+**Problem:** Browser auto-fills form fields with previous values.
+**Cause:** Browser remembers form submissions.
+**Solution:** Clear the field before filling: use `browser_click` on the field, then `browser_press_key` with Ctrl+A, then type the new value. Or use `browser_evaluate` to set the value directly.
+
+### Pitfall 5: Pop-ups and Dialogs
+
+**Problem:** An unexpected dialog (alert, confirm, prompt) blocks interaction.
+**Cause:** JavaScript `alert()`, `confirm()`, or `prompt()` calls.
+**Solution:** Use `browser_handle_dialog` with `action: "accept"` or `action: "dismiss"` before the action that triggers the dialog. Set up the dialog handler proactively.
+
+### Pitfall 6: Iframes
+
+**Problem:** Cannot interact with content inside an iframe.
+**Cause:** MCP tools operate on the main frame by default.
+**Solution:** Use `browser_evaluate` to access iframe content:
+```javascript
+document.querySelector('iframe').contentDocument.querySelector('button').click()
+```
+
+### Pitfall 7: Screenshot Shows Blank Page
+
+**Problem:** Screenshot is empty or shows a loading state.
+**Cause:** Screenshot taken before page finished rendering.
+**Solution:** Always use `browser_wait_for` before `browser_take_screenshot`. Wait for specific content, not just page load.