phase-enforcement

# Phase Completion Enforcement **Version:** 1.0.0 **Purpose:** Mechanical enforcement of phase completion requirements for /dev:feature **Status:** Production Ready ## Overview This skill provides **mechanical enforcement** (not just prompt-based instructions) for the 8-phase feature development workflow. It prevents: 1. **Claiming completion without proof** - Artifacts must exist 2. **Skipping documentation** - Required files per phase 3. **Ignoring validation criteria** - Phase 1 criteria must map to Phase 7 results 4. **Bypassing retry logic** - Outer loop enforced with state tracking 5. **Shipping without tests** - Phase 6 requires test files 6. **Faking completion when blocked** - Graceful degradation with honest status 7. **Hiding actual results** - Show-your-work requirement 8. **Missing automated checks** - Checkpoint verification at boundaries ## Enforcement Components ### 1. Phase Completion Validator **Script:** `scripts/phase-completion-validator.js` **How it works:** - Runs as PreToolUse hook on TaskUpdate - Detects phase from task subject (e.g., "Phase 3: Planning") - Checks required artifacts exist for that phase - Blocks completion if artifacts missing or empty **Required Artifacts per Phase:** | Phase | Required Artifacts | Custom Checks | |-------|-------------------|---------------| | 1 | requirements.md, validation-criteria.md, iteration-config.json | Config has required fields | | 3 | architecture.md | Plan reviews exist | | 4 | implementation-log.md | Git changes detected | | 5 | reviews/code-review/consolidated.md | Has PASS/FAIL verdict | | 6 | tests/test-plan.md | Test files created | | 7 | validation/result.md | Has PASS/FAIL status + evidence | | 8 | report.md | Phase 7 PASSED | **Usage in orchestrator:** ```markdown Before marking any phase complete: 1. Run checkpoint verification: ```bash ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH} ``` 2. If check passes, mark task complete: ``` TaskUpdate(taskId: X, status: "completed") ``` 3. If check fails, DO NOT mark complete. Fix missing artifacts first. ``` --- ### 2. Outer Loop Enforcer **Script:** `scripts/outer-loop-enforcer.js` **How it works:** - Tracks iteration state in session-meta.json - Blocks Phase 8 unless Phase 7 PASSED - Detects regression (score getting worse) - Handles escalation when max iterations reached **Commands:** ```bash # Start new iteration (call before Phase 3) node outer-loop-enforcer.js start-iteration ${SESSION_PATH} # Record Phase 7 result node outer-loop-enforcer.js record-result ${SESSION_PATH} PASS "All checks passed" 95 # Check if Phase 8 can proceed node outer-loop-enforcer.js check-can-complete ${SESSION_PATH} # Get current status node outer-loop-enforcer.js get-status ${SESSION_PATH} ``` **Session state tracking:** ```json { "outerLoop": { "currentIteration": 2, "maxIterations": 3, "mode": "limited", "phase7Results": [ {"iteration": 1, "status": "FAIL", "reason": "Button color mismatch", "score": 78}, {"iteration": 2, "status": "PASS", "reason": "All checks passed", "score": 94} ] } } ``` **Usage in orchestrator:** ```markdown OUTER LOOP: Before starting Phase 3 1. Start iteration: ```bash node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js start-iteration ${SESSION_PATH} ``` 2. Check exit code: - 0: Proceed with iteration - 2: Max iterations reached, escalate to user OUTER LOOP: After Phase 7 completes 1. Record result: ```bash node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js record-result ${SESSION_PATH} <PASS|FAIL> "reason" [score] ``` 2. If PASS: Proceed to Phase 8 3. If FAIL: Loop back to Phase 3 (start-iteration will be called again) OUTER LOOP: Before Phase 8 1. Verify Phase 7 passed: ```bash node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js check-can-complete ${SESSION_PATH} ``` 2. If exit code 1: BLOCKED - cannot proceed to Phase 8 ``` --- ### 3. Validation Criteria Enforcer **Script:** `scripts/validation-criteria-enforcer.js` **How it works:** - Parses validation-criteria.md from Phase 1 - Parses validation/result.md from Phase 7 - Matches criteria to results using fuzzy matching - Blocks if >20% criteria unaddressed **Usage in orchestrator:** ```markdown PHASE 7: After creating result.md 1. Run criteria enforcer: ```bash node ${PLUGIN_PATH}/scripts/validation-criteria-enforcer.js ${SESSION_PATH} ``` 2. Review generated report: ${SESSION_PATH}/validation/criteria-mapping.md 3. If unaddressed criteria found: - Update result.md to address them - Or document why they couldn't be tested ``` **Output format:** ```markdown # Validation Criteria Mapping Report ## Summary - Total Criteria: 5 - Matched: 4 - Unmatched: 1 - Coverage: 80% ## Criteria Mapping | Line | Criterion | Result | Evidence | |------|-----------|--------|----------| | 12 | "Navigate to test URL" | PASS | screenshot-before.png | | 13 | "Fill email field" | PASS | action-log.md line 5 | | 14 | "Click login button" | PASS | action-log.md line 8 | | 15 | "Redirect to dashboard" | PASS | screenshot-after.png | ## ⚠️ Unaddressed Criteria - Line 16: "Show error for invalid password" ``` --- ### 4. Checkpoint Verifier **Script:** `scripts/checkpoint-verifier.sh` **How it works:** - Bash script for fast automated checks - Runs at phase boundaries - Verifies files exist and have content - Checks git state for implementation phase **Usage:** ```bash # Before completing Phase 4 ./checkpoint-verifier.sh phase4 ${SESSION_PATH} # Before completing Phase 7 ./checkpoint-verifier.sh phase7 ${SESSION_PATH} ``` **Example output:** ``` 📋 Checkpoint Verification: phase4 ───────────────────────────────────── Session: ai-docs/sessions/dev-feature-login-20260204-143022 ✅ Implementation Log: implementation-log.md (1234 bytes) ✅ Code Changes: 8 files with changes ✅ Implementation Log: Has structured progress ───────────────────────────────────── ✅ Checkpoint passed ``` --- ## Integration with /dev:feature ### Phase Transition Protocol **MANDATORY: Before marking ANY phase as completed:** ```markdown <phase_completion_protocol> **Step 1: Run Checkpoint Verification** ```bash ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH} ``` If exit code != 0: STOP. Fix missing artifacts first. **Step 2: Show Evidence Summary** Display 3-5 lines of actual results: ``` ## Phase {N} Evidence - Artifact: ${SESSION_PATH}/{artifact}.md (exists, 1234 bytes) - Key result: {actual output from phase} - Evidence: {file paths to screenshots, logs, etc.} ``` **Step 3: Map to Original Criteria** (for Phase 7) ``` From validation-criteria.md: - [x] Criterion 1 → Verified (evidence file) - [x] Criterion 2 → Verified (screenshot) - [ ] Criterion 3 → Skipped (reason documented) ``` **Step 4: Mark Task Complete** Only if Steps 1-3 pass: ``` TaskUpdate(taskId: X, status: "completed") ``` </phase_completion_protocol> ``` ### Show-Your-Work Requirement **Anti-pattern (BLOCKED):** ```markdown I'll run the tests now. [Task tool call to run tests] Tests passed! Moving to next phase. ``` **Required pattern:** ```markdown Running tests: $ bun test ✓ auth.test.ts (5 tests) ✓ should authenticate valid user (12ms) ✓ should reject invalid password (8ms) ✓ should expire session after timeout (15ms) ✓ should refresh token correctly (10ms) ✓ should logout user (5ms) ✗ payment.test.ts (3 tests) ✓ should process valid payment (20ms) ✓ should reject invalid card (12ms) ✗ should handle timeout (FAILED) Error: Expected timeout after 30s, got success Results: 7 passed, 1 failed The payment timeout test failure needs investigation before Phase 6 can complete. ``` --- ## Graceful Degradation ### Three Completion Statuses **COMPLETE**: All validation criteria passed - All artifacts created - All tests pass - Full validation executed **PARTIAL**: Some validation done, gaps documented - Core functionality verified - Some criteria couldn't be tested (documented why) - Known limitations listed **INCOMPLETE**: Blocked, needs user action - Critical blocker encountered - Cannot proceed without external input - Clear description of what's needed ### Session Status in session-meta.json ```json { "status": "partial", "completedCriteria": ["builds", "type-checks", "login-flow"], "skippedCriteria": [ {"criterion": "full-auth-flow", "reason": "requires running server"}, {"criterion": "token-storage", "reason": "depends on auth flow"} ], "blockers": [] } ``` ### Final Report for PARTIAL Status ```markdown ## Feature Status: PARTIAL ### Completed ✓ - SDK implementation - Type safety - Build verification ### Not Verified ⚠️ - End-to-end authentication (requires running server) - Token storage persistence (depends on auth) ### Recommended Before Production 1. Run integration tests with real server 2. Verify token encryption roundtrip ``` --- --- ### 5. Failure Report Generator **Script:** `scripts/failure-report-generator.js` **How it works:** - Auto-generated when phase completion is blocked - Documents what was expected vs what happened - Lists all attempted approaches and their errors - Provides manual testing steps as fallback - Includes workarounds and suggestions **When generated:** - Phase completion validator blocks a phase - Validation criteria enforcer finds gaps - Outer loop reaches max iterations - Any enforcement script fails **Report structure:** ```markdown # {Phase Name} - Failure Report **Generated:** 2026-02-04T10:30:00Z **Session:** ai-docs/sessions/dev-feature-login-20260204 **Phase:** phase7 ## Expected Artifacts - ❌ `validation/result.md` - ❌ `validation/screenshot-before.png` - ❌ `validation/screenshot-after.png` ## Attempted Approaches ### Attempt 1: browser_test **What was tried:** Chrome MCP navigation to localhost:3000 **Error:** Tool mcp__chrome-devtools__navigate_page not available **Timestamp:** 2026-02-04T10:25:00Z ## Failure Analysis ### Common Failure Reasons - **chrome_mcp_unavailable**: Chrome MCP tools not available or not responding - **server_not_starting**: Dev server fails to start - **page_not_loading**: Test URL not accessible ## Suggestions for Resolution 1. Verify Chrome MCP is properly configured in .claude/settings.json 2. Check if dev server is running: curl http://localhost:3000 3. Try using different browser automation: mcp__claude-in-chrome instead 4. Consider unit tests + manual verification as fallback ## Manual Testing Steps 1. Start dev server: npm run dev (or bun run dev) 2. Open browser to test URL (e.g., http://localhost:3000) 3. Take screenshot of initial state 4. Perform test actions (fill forms, click buttons) 5. Take screenshot of result state 6. Verify expected behavior occurred 7. Document results in validation/result.md ## Workarounds ### If Browser Automation Unavailable 1. Run validation manually in browser 2. Take screenshots with system screenshot tool 3. Save screenshots to `validation/` directory 4. Create `validation/result.md` with manual observations ### Minimal result.md Template [template provided] ## Next Steps 1. **Fix and Retry**: Address the issues above and re-run the phase 2. **Manual Completion**: Follow manual steps and create artifacts manually 3. **Skip with Justification**: Create `phase7-skip-reason.md` explaining why 4. **Escalate to User**: Ask user for guidance via AskUserQuestion ``` **Usage in orchestrator:** When phase completion is blocked: ```markdown 1. Failure report auto-generated at: ${SESSION_PATH}/failures/phase{N}-failure-report.md 2. Read report and either: a. Fix issues and retry b. Follow manual testing steps c. Create skip-reason.md with justification d. Escalate to user with AskUserQuestion 3. If manually completing: - Create required artifacts following templates in report - Re-run phase completion validator ``` --- ## Summary Table | Enforcement | What It Prevents | |-------------|-----------------|