verify-phase

<purpose> Verify phase goal achievement through goal-backward analysis. Check that the codebase actually delivers what the phase promised, not just that tasks were completed. This workflow is executed by a verification subagent spawned from execute-phase.md. </purpose> <core_principle> **Task completion ≠ Goal achievement** A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved. Goal-backward verification starts from the outcome and works backwards: 1. What must be TRUE for the goal to be achieved? 2. What must EXIST for those truths to hold? 3. What must be WIRED for those artifacts to function? Then verify each level against the actual codebase. </core_principle> <required_reading> ../../instructions/verification-patterns.instructions.md @.gsd/templates/verification-report.md </required_reading> <process> <step name="load_context" priority="first"> **Gather all verification context:** ```bash # Phase directory (match both zero-padded and unpadded) PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}") PHASE_DIR=$(ls -d .gsd/phases/${PADDED_PHASE}-* .gsd/phases/${PHASE_ARG}-* 2>/dev/null | head -1) # Phase goal from ROADMAP grep -A 5 "Phase ${PHASE_NUM}" .gsd/ROADMAP.md # Requirements mapped to this phase grep -E "^| ${PHASE_NUM}" .gsd/REQUIREMENTS.md 2>/dev/null # All SUMMARY files (claims to verify) ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null # All PLAN files (for must_haves in frontmatter) ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null ``` **Extract phase goal:** Parse ROADMAP.md for this phase's goal/description. This is the outcome to verify, not the tasks. **Extract requirements:** If REQUIREMENTS.md exists, find requirements mapped to this phase. These become additional verification targets. </step> <step name="establish_must_haves"> **Determine what must be verified.** **Option A: Must-haves in PLAN frontmatter** Check if any PLAN.md has `must_haves` in frontmatter: ```bash grep -l "must_haves:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null ``` If found, extract and use: ```yaml must_haves: truths: - "User can see existing messages" - "User can send a message" artifacts: - path: "src/components/Chat.tsx" provides: "Message list rendering" key_links: - from: "Chat.tsx" to: "api/chat" via: "fetch in useEffect" ``` **Option B: Derive from phase goal** If no must_haves in frontmatter, derive using goal-backward process: 1. **State the goal:** Take phase goal from ROADMAP.md 2. **Derive truths:** Ask "What must be TRUE for this goal to be achieved?" - List 3-7 observable behaviors from user perspective - Each truth should be testable by a human using the app 3. **Derive artifacts:** For each truth, ask "What must EXIST?" - Map truths to concrete files (components, routes, schemas) - Be specific: `src/components/Chat.tsx`, not "chat component" 4. **Derive key links:** For each artifact, ask "What must be CONNECTED?" - Identify critical wiring (component calls API, API queries DB) - These are where stubs hide 5. **Document derived must-haves** before proceeding to verification. <!-- Goal-backward derivation expertise is baked into the gsd-verifier agent --> </step> <step name="verify_truths"> **For each observable truth, determine if codebase enables it.** A truth is achievable if the supporting artifacts exist, are substantive, and are wired correctly. **Verification status:** - ✓ VERIFIED: All supporting artifacts pass all checks - ✗ FAILED: One or more supporting artifacts missing, stub, or unwired - ? UNCERTAIN: Can't verify programmatically (needs human) **For each truth:** 1. Identify supporting artifacts (which files make this truth possible?) 2. Check artifact status (see verify_artifacts step) 3. Check wiring status (see verify_wiring step) 4. Determine truth status based on supporting infrastructure **Example:** Truth: "User can see existing messages" Supporting artifacts: - Chat.tsx (renders messages) - /api/chat GET (provides messages) - Message model (defines schema) If Chat.tsx is a stub → Truth FAILED If /api/chat GET returns hardcoded [] → Truth FAILED If Chat.tsx exists, is substantive, calls API, renders response → Truth VERIFIED </step> <step name="verify_artifacts"> **For each required artifact, verify three levels:** ### Level 1: Existence ```bash check_exists() { local path="$1" if [ -f "$path" ]; then echo "EXISTS" elif [ -d "$path" ]; then echo "EXISTS (directory)" else echo "MISSING" fi } ``` If MISSING → artifact fails, record and continue to next artifact. ### Level 2: Substantive Check that the file has real implementation, not a stub. **Line count check:** ```bash check_length() { local path="$1" local min_lines="$2" local lines=$(wc -l < "$path" 2>/dev/null || echo 0) [ "$lines" -ge "$min_lines" ] && echo "SUBSTANTIVE ($lines lines)" || echo "THIN ($lines lines)" } ``` Minimum lines by type: - Component: 15+ lines - API route: 10+ lines - Hook/util: 10+ lines - Schema model: 5+ lines **Stub pattern check:** ```bash check_stubs() { local path="$1" # Universal stub patterns local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented|coming soon" "$path" 2>/dev/null || echo 0) # Empty returns local empty=$(grep -c -E "return null|return undefined|return \{\}|return \[\]" "$path" 2>/dev/null || echo 0) # Placeholder content local placeholder=$(grep -c -E "will be here|placeholder|lorem ipsum" "$path" 2>/dev/null || echo 0) local total=$((stubs + empty + placeholder)) [ "$total" -gt 0 ] && echo "STUB_PATTERNS ($total found)" || echo "NO_STUBS" } ``` **Export check (for components/hooks):** ```bash check_exports() { local path="$1" grep -E "^export (default )?(function|const|class)" "$path" && echo "HAS_EXPORTS" || echo "NO_EXPORTS" } ``` **Combine level 2 results:** - SUBSTANTIVE: Adequate length + no stubs + has exports - STUB: Too short OR has stub patterns OR no exports - PARTIAL: Mixed signals (length OK but has some stubs) ### Level 3: Wired Check that the artifact is connected to the system. **Import check (is it used?):** ```bash check_imported() { local artifact_name="$1" local search_path="${2:-src/}" # Find imports of this artifact local imports=$(grep -r "import.*$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | wc -l) [ "$imports" -gt 0 ] && echo "IMPORTED ($imports times)" || echo "NOT_IMPORTED" } ``` **Usage check (is it called?):** ```bash check_used() { local artifact_name="$1" local search_path="${2:-src/}" # Find usages (function calls, component renders, etc.) local uses=$(grep -r "$artifact_name" "$search_path" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "import" | wc -l) [ "$uses" -gt 0 ] && echo "USED ($uses times)" || echo "NOT_USED" } ``` **Combine level 3 results:** - WIRED: Imported AND used - ORPHANED: Exists but not imported/used - PARTIAL: Imported but not used (or vice versa) ### Final artifact status | Exists | Substantive | Wired | Status | | ------ | ----------- | ----- | ----------- | | ✓ | ✓ | ✓ | ✓ VERIFIED | | ✓ | ✓ | ✗ | ⚠️ ORPHANED | | ✓ | ✗ | - | ✗ STUB | | ✗ | - | - | ✗ MISSING | Record status and evidence for each artifact. </step> <step name="verify_wiring"> **Verify key links between artifacts.** Key links are critical connections. If broken, the goal fails even with all artifacts present. ### Pattern: Component → API Check if component actually calls the API: ```bash verify_component_api_link() { local component="$1" local api_path="$2" # Check for fetch/axios call to the API local has_call=$(grep -E "fetch\(['\"].*$api_path|axios\.(get|post).*$api_path" "$component" 2>/dev/null) if [ -n "$has_call" ]; then # Check if response is used local uses_response=$(grep -A 5 "fetch\|axios" "$component" | grep -E "await|\.then|setData|setState" 2>/dev/null) if [ -n "$uses_response" ]; then echo "WIRED: $component → $api_path (call + response handling)" else echo "PARTIAL: $component → $api_path (call exists but response not used)" fi else echo "NOT_WIRED: $component → $api_path (no call found)" fi } ``` ### Pattern: API → Database Check if API route queries database: ```bash verify_api_db_link() { local route="$1" local model="$2" # Check for Prisma/DB call local has_query=$(grep -E "prisma\.$model|db\.$model|$model\.(find|create|update|delete)" "$route" 2>/dev/null) if [ -n "$has_query" ]; then # Check if result is returned local returns_result=$(grep -E "return.*json.*\w+|res\.json\(\w+" "$route" 2>/dev/null) if [ -n "$returns_result" ]; then echo "WIRED: $route → database ($model)" else echo "PARTIAL: $route → database (query exists but result not returned)" fi else echo "NOT_WIRED: $route → database (no query for $model)" fi } ``` ### Pattern: Form → Handler Check if form submission does something: ```bash verify_form_handler_link() { local component="$1" # Find onSubmit handler local has_handler=$(grep -E "onSubmit=\{|handleSubmit" "$component" 2>/dev/null) if [ -n "$has_handler" ]; then # Check if handler has real implementation local handler_content=$(grep -A 10 "onSubmit.*=" "$component" | grep -E "fetch|axios|mutate|dispatch" 2>/dev/null) if [ -n "$handler_content" ]; then echo "WIRED: form → handler (has API call)" else # Check for stub patterns local is_stub=$(grep -A 5 "onSubmit" "$component" | grep -E "console\.log|preventDefault\(\)$|\{\}" 2>/dev/null) if [ -n "$is_stub" ]; then echo "STUB: form → handler (only logs or empty)" else echo "PARTIAL: form → handler (exists but unclear implementation)" fi fi else echo "NOT_WIRED: form → handler (no onSubmit found)" fi } ``` ### Pattern: State → Render Check if state is actually rendered: ```bash verify_state_render_link() { local component="$1" local state_var="$2" # Check if state variable exists local has_state=$(grep -E "useState.*$state_var|\[$state_var," "$component" 2>/dev/null) if [ -n "$has_state" ]; then # Check if state is used in JSX local renders_state=$(grep -E "\{.*$state_var.*\}|\{$state_var\." "$component" 2>/dev/null) if [ -n "$renders_state" ]; then echo "WIRED: state → render ($state_var displayed)" else echo "NOT_WIRED: state → render ($state_var exists but not displayed)" fi else echo "N/A: state → render (no state var $state_var)" fi } ``` ### Aggregate key link results For each key link in must_haves: - Run appropriate verification function - Record status and evidence - WIRED / PARTIAL / STUB / NOT_WIRED