fraim-framework 2.0.67 → 2.0.68

package/dist/registry/workflows/reviewer/review-implementation-vs-design-spec.md

@@ -1,694 +0,0 @@
-# Review Implementation vs Design Spec
-
-## INTENT
-To systematically verify that the implementation matches the approved technical design (RFC), ensuring **completeness**, **correctness**, and **quality** of all technical requirements, test cases, and validation scenarios.
-
-## PRINCIPLES
-- **Completeness First**: Verify ALL RFC components are implemented before checking correctness
-- **Design-Driven Validation**: Every requirement in the RFC must be verified
-- **Test Matrix Compliance**: All test cases from design spec must exist and pass
-- **Architecture Alignment**: Implementation must follow design decisions
-- **Evidence-Based**: All claims must be backed by actual evidence
-- **Gap Identification**: Systematically identify what's missing, not just what exists
-- **Quality Standards**: Code must meet quality, maintainability, and documentation standards
-
-{{include:orchestration/independent-reviewer-guidance.md}}
-
-## REVIEW WORKFLOW
-
-### Step 1: Issue Identification and Evidence Loading
-- Get {issue_number} from context
-
-- Verify issue has `phase:impl` and `status:needs-review` labels
-- Locate RFC: `docs/rfcs/{issue}-*.md`
-- If RFC doesn't exist: ❌ BLOCKER - Cannot review without design spec. Request design phase first.
-- **Determine Issue Type**: Check if this is a bug fix or feature
-  - Check RFC title/description or issue title for "bug", "fix", "error", etc.
-  - Bug fixes require regression tests (see Step 4.4 Regression Test Verification)
-- **Load Implementation Evidence**: Read `docs/evidence/{issue}-implementation-evidence.md`
-  - If evidence doesn't exist: ❌ BLOCKER - Implementation agent must create evidence document first
-  - Review evidence for completeness and quality
-- **Check for Existing Feedback**: Check if `docs/evidence/{issue}-design-reviewer-feedback.md` exists
-  - If exists, this is an iteration (check iteration count)
-  - Track iteration number (max 3 iterations)
-
-### Step 2: RFC Completeness Check
-
-**CRITICAL**: Before checking technical correctness, verify ALL RFC components are addressed.
-
-#### 2.1: Extract Full RFC Scope
-**Read the ENTIRE RFC and extract**:
-- All "Changes" sections (Component Changes, API Changes, Schema Changes, etc.)
-- All new files to be created
-- All existing files to be modified
-- All new endpoints/APIs
-- All configuration changes
-- All test requirements (from Test Matrix)
-- All validation scenarios (from Validation Plan)
-- All risk mitigations
-- All observability requirements
-
-#### 2.2: Create Completeness Checklist
-**Format**:
-```markdown
-## RFC Completeness Checklist
-
-### Part 1: [Component Name from RFC]
-- [ ] File: path/to/file.ts - [description from RFC]
-- [ ] Test: path/to/test.ts - [description from RFC]
-- [ ] Config: .fraim/config.json - [fields from RFC]
-
-### Part 2: [Component Name from RFC]
-- [ ] Endpoint: POST /api/endpoint - [description from RFC]
-- [ ] File: path/to/file.ts - [description from RFC]
-
-### Part 3: [Component Name from RFC]
-...
-
-**Total Items**: X
-```
-
-#### 2.3: Verify Each Item
-**For each checklist item**:
-- ✅ **Implemented**: Point to code/test files/config that implements it
-- ⏸️ **Deferred**: Check if follow-up issue exists and is documented
-- ❌ **Missing**: BLOCKER - must be implemented or explicitly deferred
-
-#### 2.4: Calculate Completeness
-```
-Implemented: X/Y items (Z%)
-Deferred: A items (with follow-up issues #123, #456)
-Missing: B items (BLOCKER if >0 without follow-up issues)
-```
-
-**If completeness <100%**:
-- ❌ REQUEST CHANGES - List all missing items
-- Require either implementation or explicit deferral with follow-up issues
-- Do NOT proceed to correctness checks until completeness is 100%
-
-### Step 3: RFC Analysis (Correctness Check)
-
-**ONLY proceed here if Step 2 shows 100% completeness**
-
-**MUST read and extract:**
-- Technical requirements (API changes, schema changes, etc.)
-- Test Matrix section (unit, integration, E2E tests required)
-- Validation Plan section (all validation scenarios)
-- Architecture decisions (service boundaries, patterns)
-- Risk mitigations (how they were addressed)
-- Observability requirements (logs, metrics, alerts)
-
-**Create a correctness checklist mapping:**
-- List each requirement from RFC
-- List each test case from Test Matrix
-- List each validation scenario from Validation Plan
-- This becomes your correctness review checklist
-
-### Step 4: Implementation Code Review (Correctness Check)
-**For each technical requirement in RFC:**
-- [ ] Verify requirement is implemented in code
-  - Search codebase for implementation
-  - Check file paths match design
-  - Verify code exists and is not just stubbed
-- [ ] Check code follows architecture decisions
-  - Service boundaries match design
-  - Patterns match design (e.g., spike-first, deterministic separation)
-  - No over-engineering beyond design scope
-- [ ] Verify API/schema changes match RFC exactly
-  - Check OpenAPI spec matches (if applicable)
-  - Check database schema matches (if applicable)
-  - Verify field names, types, constraints match
-- [ ] Check error handling matches design
-  - Error responses match design
-  - Error codes match design
-  - Error messages match design
-- [ ] Verify observability (logs, metrics) matches design
-  - Log statements exist where specified
-  - Metrics tracked where specified
-  - Alerts configured where specified
-
-**Document findings:**
-- Create table: Requirement | Status | Evidence Location | Notes
-
-### Step 4: Test Matrix Validation
-**For each test type in RFC Test Matrix:**
-
-#### Unit Tests
-- [ ] **Count Required**: How many unit tests does RFC specify?
-- [ ] **Count Found**: How many unit test files exist? (`test-{issue}-*.ts` or similar)
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- npm run test test-{issue}-*.ts` (or appropriate command)
-- [ ] **Verify Exit Code**: Must be 0 (success), 124 indicates timeout (test hung)
-- [ ] **Check Output**: All tests must pass (not just "some tests pass")
-- [ ] **Document Results**: Include actual test output in review evidence
-
-#### Integration Tests
-- [ ] **Count Required**: How many integration tests does RFC specify?
-- [ ] **Count Found**: How many integration test files exist?
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute integration tests with proper mocks
-- [ ] **Verify Service Interactions**: Check mocks validate service calls match design
-- [ ] **Verify Exit Code**: Must be 0 (success)
-- [ ] **Document Results**: Include actual test output in review evidence
-
-#### E2E Tests
-- [ ] **Count Required**: How many E2E tests does RFC specify?
-- [ ] **Count Found**: How many E2E test files exist?
-- [ ] **Verify Existence**: Check each listed test case exists
-- [ ] **Run Tests**: Execute E2E tests (may require server running)
-- [ ] **Verify End-to-End Flow**: Complete workflow must work
-- [ ] **Verify Exit Code**: Must be 0 (success)
-- [ ] **Document Results**: Include actual test output in review evidence
-
-**If test matrix says "X test cases" but only Y exist:**
-- ❌ BLOCKER: Missing test cases
-- Must identify which tests are missing (list specific test names)
-- Cannot approve until all tests from matrix exist and pass
-
-**Document findings:**
-- Create table: Test Type | Required | Found | Passing | Evidence | Missing Tests
-
-#### Test Quality Validation (Anti-Pattern Detection)
-**🚨 CRITICAL: Verify tests validate runtime behavior, not code structure**
-
-**For each test file found (test-{issue}-*.ts):**
-- [ ] **Check for Static Analysis Anti-Pattern**: Verify tests don't use `fs.readFileSync()` for code structure checks
-  - Check: `grep -E "fs\.readFileSync|readFileSync" test-{issue}-*.ts`
-  - ❌ BLOCKER if found - tests are doing static analysis, not runtime testing
-  - Expected: Tests should execute code, not read source files
-  - Reference: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
-- [ ] **Verify Runtime Behavior Testing**: Check tests actually execute code paths
-  - Review test code to ensure it calls actual functions/services
-  - Verify tests check observable outcomes (API responses, database state, logs)
-  - ❌ BLOCKER if tests only check code structure without execution
-- [ ] **Check for Mock Anti-Pattern**: Verify tests don't mock the core functionality being tested
-  - Check: Are mocks used for dependencies (✅) or for the thing being tested (❌)?
-  - ❌ BLOCKER if core functionality is mocked
-  - Expected: Mock dependencies, test actual implementation
-- [ ] **Verify State Validation**: Check tests validate state changes
-  - Tests should check database state, API responses, or service interactions
-  - ❌ BLOCKER if tests don't validate any state changes
-  - Expected: Tests verify before/after state or observable outcomes
-
-**Document findings:**
-- Create table: Test File | Static Analysis Check | Runtime Behavior | Mock Usage | State Validation | Status
-
-#### Regression Test Verification (For Bug Fixes)
-**If this is a bug fix (check RFC or issue description):**
-- [ ] **Identify Bug**: Understand what the bug was from RFC/issue
-- [ ] **Check for Regression Test**: Verify test file includes regression test for the bug
-  - Check test file for test case that reproduces the bug
-  - Test should be named something like "regression test for bug X" or similar
-- [ ] **Verify Test Pattern**: Regression test must follow correct pattern
-  - ❌ BLOCKER if test passes/fails regardless of bug (wrong pattern)
-  - ✅ CORRECT: Test fails with bug → Test passes with fix
-  - ❌ WRONG: Test passes with bug AND with fix (doesn't reproduce bug)
-  - ❌ WRONG: Test fails with bug AND with fix (environmental issue)
-- [ ] **Verify Test Behavior** (if possible):
-  - Ideally: Revert fix temporarily, run test → should fail
-  - Reapply fix, run test → should pass
-  - If not possible, verify test logic would fail with buggy code
-
-**Document findings:**
-- Bug Fix: ✅ Yes / ❌ No
-- Regression Test: ✅ Found / ❌ Missing
-- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
-- Notes: [Any issues with regression test]
-
-### Step 4.5: Common Error Pattern Checks
-**🚨 CRITICAL: Check for common test and code quality issues**
-
-#### Test Structure Validation
-**For each test file found (test-{issue}-*.ts):**
-- [ ] **BaseTestCase Extension**: Verify test cases extend `BaseTestCase` interface
-  - Check: `grep -E "extends BaseTestCase|interface.*extends BaseTestCase" test-{issue}-*.ts`
-  - ❌ BLOCKER if test cases don't extend BaseTestCase
-  - Expected pattern: `interface MyTestCase extends BaseTestCase { ... }`
-  - All test case objects must use interface that extends BaseTestCase
-- [ ] **Main Function**: Verify test file has `main()` function
-  - Check: `grep -E "async function main\(\)|function main\(\)" test-{issue}-*.ts`
-  - ❌ BLOCKER if main() function missing
-  - Expected pattern: `async function main() { ... runTests(...) }`
-  - Must have `main().catch(console.error)` at end of file
-- [ ] **runTests Usage**: Verify test file uses `runTests()` function
-  - Check: `grep "runTests" test-{issue}-*.ts`
-  - ❌ BLOCKER if runTests() not used
-  - Expected: `runTests(TEST_CASES, runMyTest, 'Test Suite Name')`
-  - Must import runTests from './test-utils' or './test-utils.ts'
-
-**Document findings:**
-- Create table: Test File | BaseTestCase | main() | runTests() | Status
-
-#### Code Quality Check
-- [ ] **Run Code Quality Check**: Execute the code quality script directly from synced location.
-  - Command: `~/.fraim/scripts/code-quality-check.sh pre-pr`
-  - Verify exit code is 0 (success)
-  - Check for critical failures (❌) vs warnings (⚠️)
-  - ❌ BLOCKER if critical checks fail (e.g., `as any` usage, TypeScript errors)
-  - ⚠️ WARNING if warnings exist (document in feedback)
-- [ ] **Review Quality Check Output**: 
-  - Check for `as any` type bypassing in src/
-  - Check TypeScript compilation passes
-  - Check linter passes (warnings acceptable, errors are blockers)
-  - Check all test files referenced in evidence have been executed
-
-**Document findings:**
-- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
-- Critical Issues: [list any critical failures]
-- Warnings: [list any warnings]
-
-#### Evidence File Location Validation
-- [ ] **Check Evidence Files**: Verify evidence files are ONLY in `docs/evidence/` folder
-  - Check: `find . -name "*evidence*.md" -not -path "./docs/evidence/*" -not -path "./.git/*" -not -path "./node_modules/*"`
-  - ❌ BLOCKER if evidence files found outside `docs/evidence/`
-  - Expected: All evidence files should be in `docs/evidence/{issue}-*.md`
-- [ ] **Check for Evidence in Git**: Verify evidence folder is gitignored
-  - Check: `git check-ignore docs/evidence/` should return `docs/evidence/`
-  - ⚠️ WARNING if evidence folder not in .gitignore (should be gitignored)
-- [ ] **Check PR for Evidence Files**: Verify no evidence files committed to repo
-  - Check git status for any files in docs/evidence/
-  - ❌ BLOCKER if evidence files are staged/committed
-
-**Document findings:**
-- Evidence Location Check: ✅ All in docs/evidence/ / ❌ Found outside
-- Git Ignore Check: ✅ Ignored / ⚠️ Not ignored
-- Committed Evidence: ✅ None / ❌ Found in commits
-
-**If any blockers found:**
-- ❌ BLOCKER: Must fix before approval
-- List specific files and issues
-- Cannot approve until all blockers resolved
-
-### Step 5: Validation Plan Execution
-**For each validation scenario in RFC Validation Plan:**
-- [ ] **Scenario Identified**: Map each scenario from validation plan
-- [ ] **Evidence Found**: Check PR evidence for scenario validation
-  - Look in PR comments for evidence
-  - Check for screenshots, curl outputs, test results
-  - Verify evidence shows actual execution (not just "tested")
-- [ ] **Method Verified**: Ensure validation method matches (UI, API, DB, etc.)
-  - If RFC says "API validation", check for curl/Postman results
-  - If RFC says "Browser validation", check for screenshots/recordings
-  - If RFC says "Database validation", check for DB query results
-- [ ] **Result Verified**: Ensure scenario actually passes (not just "tested")
-  - Check evidence shows success, not just attempt
-  - Verify no "pending" or "TODO" markers
-
-**If validation plan has 10 scenarios but only 7 have evidence:**
-- ❌ BLOCKER: Missing validation evidence
-- Must identify which scenarios are missing (list specific scenario names)
-- Cannot approve until all scenarios validated with evidence
-
-**Document findings:**
-- Create table: Scenario | Method | Evidence | Status | Missing Evidence
-
-### Step 6: Architecture Compliance Check
-**Verify implementation matches design:**
-- [ ] Service boundaries match design
-  - Check service files match design boundaries
-  - Verify no cross-boundary violations
-- [ ] Patterns match design (e.g., spike-first, deterministic separation)
-  - Check code follows patterns specified in RFC
-  - Verify no anti-patterns introduced
-- [ ] Dependencies match design
-  - Check package.json matches design dependencies
-  - Verify no unexpected dependencies added
-- [ ] No over-engineering beyond design scope
-  - Check code doesn't add features not in RFC
-  - Verify minimal implementation (not over-engineered)
-
-**Document findings:**
-- List any architecture deviations
-- Note if deviations are acceptable or blockers
-
-### Step 7: Risk Mitigation Verification
-**For each risk in RFC Risks & Mitigations:**
-- [ ] Verify mitigation is implemented
-  - Check code implements mitigation strategy
-  - Verify mitigation code exists and is not just commented
-- [ ] Check mitigation actually addresses the risk
-  - Verify mitigation logic matches risk description
-  - Check mitigation is complete (not partial)
-- [ ] Verify observability for risk detection
-  - Check logs/alerts exist for risk scenarios
-  - Verify monitoring is in place
-
-**Document findings:**
-- Create table: Risk | Mitigation Status | Implementation Location | Notes
-
-### Step 8: Evidence Quality Review
-**Verify PR evidence quality:**
-- [ ] All test outputs included (not just "tests pass")
-  - Check for actual test command output
-  - Verify exit codes shown
-  - Check for test case names and results
-- [ ] All validation scenarios documented with results
-  - Check each scenario has evidence
-  - Verify evidence shows actual execution
-- [ ] No "pending" items that could be validated automatically
-  - Flag any "pending" items that could be tested
-  - Check for "TODO" or "needs manual validation" markers
-- [ ] Build verification included
-  - Check for `npm run build` output
-  - Verify build succeeds
-- [ ] Quality gate results included
-  - Check for quality gate script output
-  - Verify all gates pass (or warnings documented)
-
-**Document findings:**
-- List any evidence quality issues
-- Note if evidence is sufficient or needs improvement
-
-### Step 9: Review Decision and Feedback Creation
-
-**Check Iteration Count:**
-- If `docs/evidence/{issue}-design-reviewer-feedback.md` exists, check iteration number
-- Maximum 3 iterations allowed
-- If iteration 3 and still issues: ❌ REJECT (max iterations reached)
-
-**Options:**
-- ✅ **APPROVE**: All requirements met, tests pass, evidence complete
-- ❌ **REJECT**: Missing requirements, tests fail, or evidence incomplete (after max iterations)
-- ⚠️ **REQUEST CHANGES**: Minor gaps that need addressing (iteration < 3)
-
-**If REQUEST CHANGES (iteration < 3):**
-- **Create Feedback Document**: Create `docs/evidence/{issue}-design-reviewer-feedback.md`
-  - Use template below for feedback structure
-  - List specific blockers with evidence locations
-  - Provide actionable feedback for each issue
-  - Include iteration number
-- Label issue `status:wip` (remove `status:needs-review`)
-- Add PR comment referencing feedback document
-- Implementation agent must address feedback and update evidence
-- Implementation agent re-submits by marking `status:needs-review` again
-
-**If REJECT (max iterations reached):**
-- Create final feedback document with all remaining issues
-- Label issue `status:wip` (remove `status:needs-review`)
-- Add PR comment with final rejection notice
-- Implementation agent must address all issues before re-submission
-
-**If APPROVE:**
-- **Create Summary for Feature Spec Review**: Create `docs/evidence/{issue}-design-review-summary.md`
-  - Summarize what was reviewed and approved
-  - Include key findings and evidence locations
-  - Provide context for feature spec review agent
-- Label issue `status:design-review-passed` (remove `status:needs-review`)
-- Add PR comment confirming design spec compliance
-- Issue ready for Feature Spec Review (next workflow)
-
-## FEEDBACK DOCUMENT TEMPLATE
-
-Create `docs/evidence/{issue}-design-reviewer-feedback.md`:
-
-```markdown
-# Design Review Feedback - Issue #{issue}
-
-## Iteration Information
-- Iteration Number: {1, 2, or 3}
-- Review Date: {date}
-- Reviewer: Design Spec Review Agent
-
-## Review Summary
-- RFC Location: `docs/rfcs/{issue}-*.md`
-- Evidence Reviewed: `docs/evidence/{issue}-implementation-evidence.md`
-- Overall Status: ⚠️ REQUEST CHANGES
-
-## Issues Found
-
-### Critical Blockers (Must Fix)
-1. **Issue Title**
-   - **Location**: `src/file.ts:line`
-   - **Problem**: [Specific problem description]
-   - **Expected**: [What RFC requires]
-   - **Found**: [What implementation has]
-   - **Action Required**: [Specific fix needed]
-
-2. **Issue Title**
-   - [Same structure]
-
-### Missing Requirements
-1. **Requirement Name**
-   - **RFC Section**: [Section reference]
-   - **What's Missing**: [Specific requirement]
-   - **Action Required**: [What needs to be implemented]
-
-### Test Matrix Issues
-1. **Missing Test**: Test case name
-   - **RFC Test Matrix**: [Reference]
-   - **Action Required**: Create test file `test-{issue}-*.ts` with test case
-
-### Test Structure Issues (Common Error Patterns)
-1. **Test Not Extending BaseTestCase**: `test-{issue}-*.ts`
-   - **Problem**: Test case interface doesn't extend BaseTestCase
-   - **Expected**: `interface MyTestCase extends BaseTestCase { ... }`
-   - **Action Required**: Update test case interface to extend BaseTestCase
-
-2. **Missing main() Function**: `test-{issue}-*.ts`
-   - **Problem**: Test file doesn't have main() function
-   - **Expected**: `async function main() { ... runTests(...) }` with `main().catch(console.error)`
-   - **Action Required**: Add main() function that calls runTests()
-
-3. **Not Using runTests()**: `test-{issue}-*.ts`
-   - **Problem**: Test file doesn't use runTests() function
-   - **Expected**: Import runTests from './test-utils' and call it in main()
-   - **Action Required**: Refactor to use runTests() function
-
-### Test Quality Issues (Anti-Patterns)
-1. **Static Analysis Anti-Pattern**: `test-{issue}-*.ts`
-   - **Problem**: Tests use `fs.readFileSync()` to check code structure instead of runtime behavior
-   - **Expected**: Tests should execute code and validate outcomes, not read source files
-   - **Action Required**: Rewrite tests to validate runtime behavior
-   - **Reference**: `retrospectives/issue-723-weak-test-validation-anti-pattern-postmortem.md`
-
-2. **No Runtime Behavior Validation**: `test-{issue}-*.ts`
-   - **Problem**: Tests don't execute actual code paths or validate observable outcomes
-   - **Expected**: Tests should call functions/services and check results
-   - **Action Required**: Add runtime behavior validation to tests
-
-3. **Mocking Core Functionality**: `test-{issue}-*.ts`
-   - **Problem**: Tests mock the thing being tested instead of dependencies
-   - **Expected**: Mock dependencies, test actual implementation
-   - **Action Required**: Refactor mocks to only mock dependencies
-
-4. **No State Validation**: `test-{issue}-*.ts`
-   - **Problem**: Tests don't validate state changes (database, API responses, etc.)
-   - **Expected**: Tests should verify before/after state or observable outcomes
-   - **Action Required**: Add state validation to tests
-
-### Regression Test Issues (For Bug Fixes)
-1. **Missing Regression Test**: `test-{issue}-*.ts`
-   - **Problem**: Bug fix doesn't have regression test
-   - **Expected**: Regression test that fails with bug, passes with fix
-   - **Action Required**: Add regression test following correct pattern
-
-2. **Wrong Regression Test Pattern**: `test-{issue}-*.ts`
-   - **Problem**: Test passes/fails regardless of bug (doesn't reproduce bug)
-   - **Expected**: Test fails with bug → Test passes with fix
-   - **Action Required**: Fix regression test to follow correct pattern
-   - **Reference**: `retrospectives/task-api-calendar-event-id-bug-postmortem.md`
-
-### Code Quality Issues
-1. **Code Quality Check Failed**: [Specific issue]
-   - **Problem**: [What failed - e.g., "as any" usage, TypeScript errors]
-   - **Action Required**: Fix code quality issues and re-run check
-   - **Command**: Run quality check (fetch `scripts/code-quality-check.sh` via `get_fraim_file`)
-
-### Evidence File Location Issues
-1. **Evidence File Outside docs/evidence/**: [File path]
-   - **Problem**: Evidence file found outside `docs/evidence/` folder
-   - **Expected**: All evidence files should be in `docs/evidence/{issue}-*.md`
-   - **Action Required**: Move evidence file to `docs/evidence/` folder
-
-### Validation Plan Issues
-1. **Missing Validation**: Scenario name
-   - **RFC Validation Plan**: [Reference]
-   - **Action Required**: Execute validation and add evidence
-
-### Evidence Quality Issues
-1. **Missing Evidence**: [What's missing]
-   - **Action Required**: [What evidence needs to be added]
-
-## Action Items for Implementation Agent
-- [ ] Fix critical blocker 1
-- [ ] Fix critical blocker 2
-- [ ] Implement missing requirement X
-- [ ] Add missing test case Y
-- [ ] Execute missing validation Z
-- [ ] Update evidence document with fixes
-
-## Next Steps
-1. Implementation agent addresses all feedback items
-2. Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
-3. Implementation agent marks issue `status:needs-review` again
-4. Design review agent will re-review (iteration {next_number})
-```
-
-## SUMMARY DOCUMENT TEMPLATE (For Feature Spec Review)
-
-Create `docs/evidence/{issue}-design-review-summary.md` when approving:
-
-```markdown
-# Design Review Summary - Issue #{issue}
-
-## Review Outcome
-- Status: ✅ APPROVED
-- Iterations: {number} (1-3)
-- RFC Location: `docs/rfcs/{issue}-*.md`
-
-## What Was Reviewed
-- Technical Requirements: X/Y implemented ✅
-- Test Matrix: All test cases exist and pass ✅
-- Validation Plan: All scenarios validated ✅
-- Architecture: Matches design ✅
-- Risk Mitigations: All implemented ✅
-
-## Key Findings
-- All RFC requirements implemented correctly
-- All tests from test matrix exist and pass
-- All validation scenarios executed with evidence
-- Architecture follows design decisions
-- No over-engineering detected
-
-## Evidence Locations
-- Implementation Evidence: `docs/evidence/{issue}-implementation-evidence.md`
-- Test Results: [locations]
-- Validation Evidence: [locations]
-
-## Notes for Feature Spec Review
-- Technical implementation is complete and correct
-- All technical requirements met
-- Ready for functional/user experience validation
-- No technical blockers for feature spec review
-```
-
-## REVIEW EVIDENCE TEMPLATE (PR Comment)
-
-Add this as a PR comment:
-
-```markdown
-# Design Spec Review - Issue #{issue}
-
-## RFC Compliance Summary
-- RFC Location: `docs/rfcs/{issue}-*.md`
-- Technical Requirements: X/Y implemented ✅/❌
-- Test Matrix Compliance: X/Y test types complete ✅/❌
-- Validation Plan Coverage: X/Y scenarios validated ✅/❌
-- Architecture Compliance: ✅/❌
-- Risk Mitigations: X/Y implemented ✅/❌
-
-## Detailed Findings
-
-### Technical Requirements
-| Requirement | Status | Evidence Location | Notes |
-|------------|--------|-------------------|-------|
-| API endpoint X | ✅ | `src/api/...` | Matches RFC |
-| Schema change Y | ❌ | Missing | RFC requires Z field |
-
-### Test Matrix Validation
-| Test Type | Required | Found | Passing | Evidence | Missing Tests |
-|-----------|----------|-------|---------|----------|---------------|
-| Unit Tests | 5 | 5 | ✅ | `test-{issue}.ts` lines 10-50 | None |
-| Integration | 3 | 2 | ❌ | Partial | Missing test for scenario Z |
-| E2E | 1 | 0 | ❌ | Not found | E2E test not implemented |
-
-### Test Quality Validation
-| Test File | Static Analysis | Runtime Behavior | Mock Usage | State Validation | Status |
-|-----------|----------------|-------------------|------------|------------------|--------|
-| test-{issue}.ts | ✅ No fs.readFileSync | ✅ Executes code | ✅ Mocks dependencies | ✅ Validates state | ✅ Pass |
-| test-{issue}-2.ts | ❌ Uses fs.readFileSync | ❌ No execution | ❌ Mocks core | ❌ No validation | ❌ Fail |
-
-### Regression Test Verification (If Bug Fix)
-- Bug Fix: ✅ Yes / ❌ No
-- Regression Test: ✅ Found / ❌ Missing
-- Test Pattern: ✅ Correct (fails with bug, passes with fix) / ❌ Wrong pattern
-- Notes: [Any issues with regression test]
-
-### Validation Plan Coverage
-| Scenario | Method | Evidence | Status | Missing Evidence |
-|----------|--------|----------|--------|------------------|
-| Create operation | API | PR comment | ✅ | None |
-| Update operation | API | Missing | ❌ | No curl output found |
-
-### Architecture Compliance
-- Service Boundaries: ✅ Match design
-- Patterns: ✅ Follow design patterns
-- Dependencies: ⚠️ Extra dependency X added (not in RFC)
-- Over-engineering: ✅ Minimal implementation
-
-### Risk Mitigations
-| Risk | Mitigation Status | Implementation Location | Notes |
-|------|-------------------|-------------------------|-------|
-| Risk X | ✅ Implemented | `src/...` | Matches design |
-| Risk Y | ❌ Missing | N/A | Not implemented |
-
-### Common Error Pattern Checks
-- Test Structure: ✅ All tests extend BaseTestCase / ❌ Issues found
-- Main Functions: ✅ All tests have main() / ❌ Missing in some tests
-- runTests Usage: ✅ All tests use runTests() / ❌ Not used in some tests
-- Code Quality Check: ✅ Passed / ❌ Failed / ⚠️ Warnings
-- Evidence Location: ✅ All in docs/evidence/ / ❌ Found outside
-
-### Evidence Quality
-- Test Outputs: ✅ Complete (all test results included)
-- Validation Evidence: ⚠️ Partial (missing scenario Y evidence)
-- Build Verification: ✅ Included
-- Quality Gate: ✅ Passed
-
-## Decision
-✅ APPROVE / ❌ REJECT / ⚠️ REQUEST CHANGES
-
-## Feedback Document
-- Location: `docs/evidence/{issue}-design-reviewer-feedback.md`
-- Iteration: {1, 2, or 3}
-
-## Blockers (if any)
-1. Missing test case for scenario X (RFC Test Matrix requires it)
-2. Validation scenario Y not executed (RFC Validation Plan requires it)
-3. Technical requirement Z not implemented (RFC Technical Details requires it)
-
-## Next Steps (if REQUEST CHANGES)
-- [ ] Implementation agent addresses feedback in `docs/evidence/{issue}-design-reviewer-feedback.md`
-- [ ] Implementation agent updates `docs/evidence/{issue}-implementation-evidence.md`
-- [ ] Implementation agent marks `status:needs-review` for re-review
-- [ ] Design review agent will re-review (max 3 iterations)
-```
-
-## EXAMPLES
-
-### Good: Complete Review
-```
-Issue #533: Design Spec Review
-✅ RFC Compliance: 15/15 requirements implemented
-✅ Test Matrix: All 8 test cases exist and pass
-✅ Validation Plan: All 5 scenarios validated
-✅ Architecture: Matches design
-✅ Evidence: Complete with test outputs
-Decision: ✅ APPROVE
-```
-
-### Bad: Incomplete Review
-```
-Issue #533: Design Spec Review
-⚠️ RFC Compliance: 12/15 requirements (3 missing)
-❌ Test Matrix: 5/8 test cases exist (3 missing)
-⚠️ Validation Plan: 3/5 scenarios validated (2 missing)
-Decision: ❌ REJECT
-Blockers: Missing tests, missing validations
-```
-
-## INTEGRATION
-
-### Status Label Flow
-```
-phase:impl + status:needs-review
-  ↓ (Design Spec Review)
-status:design-review-passed (or status:wip if rejected)
-  ↓ (Feature Spec Review - next workflow)
-status:feature-review-passed
-```
-
-### After This Review
-- If APPROVE: Issue moves to Feature Spec Review
-- If REJECT: Issue returns to implementation (status:wip)
-- Implementation agent addresses blockers and re-submits