validate-staging

# /validate-staging — Staging Validation (Thin Wrapper)

> **v11.0 Architecture**: This command spawns the isolated `validate-phase-agent` via Task(). Validation checks run in isolated context with question batching for manual verification.

<context>
**User Input**: $ARGUMENTS

**Active Feature**: !`ls -td specs/[0-9]*-* 2>/dev/null | head -1 || echo "none"`

**Interaction State**: !`cat specs/*/interaction-state.yaml 2>/dev/null | head -10 || echo "none"`
</context>

<objective>
Spawn isolated validate-phase-agent to validate staging deployment before production.

**Architecture (v11.0 - Phase Isolation):**
```
/validate-staging → Task(validate-phase-agent) → Q&A for manual checks → validation-report.md
```

**Agent responsibilities:**
- Review E2E test results from GitHub Actions
- Review Lighthouse CI performance results
- Test rollback capability
- Generate manual testing checklist from spec.md
- Return questions for user to manually verify in browser
- Create staging-validation-report.md

**Operating constraints:**
- **Manual Gate** — Agent returns questions for human validation
- **Staging Environment** — Validates staging URLs
- **Blocking Conditions** — E2E failures or manual failures block production

**Workflow position**: `implement → optimize → validate → ship → finalize`
</objective>

## Legacy Context (for agent reference)

<legacy_context>
Latest staging deployment: !`gh run list --workflow=deploy-staging.yml --branch=main --limit=1 --json databaseId,headSha,conclusion,status,createdAt,displayTitle 2>/dev/null || echo "[]"`

Vercel CLI installed: !`command -v vercel >/dev/null 2>&1 && echo "✅ Yes" || echo "❌ No"`

GitHub CLI authenticated: !`gh auth status >/dev/null 2>&1 && echo "✅ Yes" || echo "❌ No"`
</legacy_context>

<process>
1. **Detect feature from recent deployment**:
   - Get latest staging deployment from deploy-staging.yml workflow
   - Extract commit SHA, run ID, status, conclusion
   - Parse feature slug from commit message
   - Locate feature directory at specs/$SLUG
   - Verify spec.md exists

2. **Verify deployment status**:

   - Check if deployment is still running (in_progress/queued)
   - If running: Display workflow URL and exit with message to wait
   - Check if deployment failed
   - If failed: Extract failed jobs, display errors, exit with fix message
   - If succeeded: Continue to health checks

3. **Check staging health endpoints**:

   - Test marketing health: `curl https://staging.{domain}.com/health`
   - Test app health: `curl https://app.staging.{domain}.com/health`
   - Test API health: `curl https://api.staging.{domain}.com/api/v1/health/healthz`
   - Expect HTTP 200 for all endpoints
   - If any fail: Prompt user to continue or cancel

4. **Test rollback capability** (CRITICAL):

   - Load current and previous deployment IDs from deployment-metadata.json
   - If first deployment (no previous): Skip test (not a blocker)
   - If previous exists:
     a. Verify Vercel CLI installed
     b. Roll back to previous deployment: `vercel alias set $PREV_ID $STAGING_APP`
     c. Wait 15s for DNS propagation
     d. Verify rollback succeeded (check live URL headers)
     e. Roll forward to current deployment: `vercel alias set $CURRENT_ID $STAGING_APP`
     f. Wait 10s for DNS
     g. Update state.yaml quality gate
   - If rollback fails: BLOCK production deployment

5. **Review E2E test results**:

   - Find E2E job in workflow run
   - Extract conclusion (success/failure)
   - If passed: ✅ Continue
   - If failed:
     a. Extract failure details from logs
     b. Display failure summary
     c. BLOCK production deployment
   - If not run: ⚠️ Warning

6. **Review Lighthouse CI results**:

   - Find Lighthouse job in workflow run
   - Extract conclusion and performance scores
   - If passed: ✅ Continue
   - If failed:
     a. Extract performance warnings
     b. Display targets (Performance >85, Accessibility >95)
     c. Prompt user to continue or cancel (warning, not blocker)
   - If not run: ⚠️ Warning

7. **Generate manual testing checklist**:

   - Read spec.md
   - Extract Acceptance Criteria section (list items)
   - Extract User Flows section (list items)
   - Create checklist at /tmp/staging-validation-checklist-$SLUG.md with:
     - Staging URLs
     - Acceptance criteria checkboxes
     - User flow checkboxes
     - Edge case checks (error states, empty states, loading)
     - Visual validation (design, responsive, animations)
     - Accessibility quick checks
     - Cross-browser testing (optional)
     - Issues section for notes

8. **Guide interactive manual testing**:

   - Display checklist
   - Open checklist in editor (VS Code, vim, nano, or manual)
   - Prompt: "Have you completed manual testing? (y/N)"
   - If N: Save checklist, exit with message to resume later
   - If Y: Continue to issue check
   - Prompt: "Were any issues found? (y/N)"
   - If Y: Capture issue description, set MANUAL_STATUS=failed
   - If N: Set MANUAL_STATUS=passed

9. **Capture discovered gaps** (NEW in v3.0 - Feedback Loop Support):

   - Prompt: "Discover any missing features or endpoints during testing? (y/N)"
   - If Y OR --capture-gaps flag provided:
     a. Launch gap capture wizard (Invoke-GapCaptureWizard.ps1)
     b. For each gap:
     - Collect gap description, source, priority, subsystems
     - Run scope validation algorithm (Invoke-ScopeValidation.ps1)
     - Display validation result (IN_SCOPE ✅ | OUT_OF_SCOPE ❌ | AMBIGUOUS ⚠️)
       c. Generate gaps.md with all discoveries
       d. Generate scope-validation-report.md with validation evidence
       e. For in-scope gaps:
     - Generate supplemental tasks (New-SupplementalTasks.ps1)
     - Append to tasks.md with iteration marker
     - Update state.yaml:
       _ Set phase to "implement"
       _ Increment iteration.current
       _ Populate gaps section
       _ Add supplemental_tasks entry
       f. For out-of-scope gaps:
     - Recommend creating new epic/feature
     - Block from curre