qualia-framework 2.1.0

package/framework/skills/deploy/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: deploy
+description: "Quick deploy, troubleshoot, or rollback Vercel deployments. Use --quick for fast push, --fix for troubleshooting, --preview for staging. For full pipeline with quality gates, use /ship instead."
+tags: [deployment, vercel, ci-cd, production]
+---
+
+# Deploy — Quick Deploy & Troubleshooting
+
+> For the full production pipeline (quality gates, commit, deploy, verify), use `/ship`.
+> This skill handles quick deploys, troubleshooting, and rollbacks.
+
+## Usage
+
+- `/deploy --quick` — Skip tests, just build and push to production
+- `/deploy --preview` — Deploy to preview/staging environment
+- `/deploy --fix` — Troubleshoot a failed deployment
+- `/deploy` — Redirects to `/ship` for full pipeline
+
+## --quick (Fast Deploy)
+
+Skip tests, just build and ship:
+```bash
+npm run build && vercel --prod
+```
+
+---
+
+## --fix (Troubleshoot Failures)
+
+### Build Failures
+
+**Module Not Found:** Check case sensitivity (Linux is case-sensitive). Run `vercel --force` to clear cache.
+
+**Memory Issues:** Add to vercel.json:
+```json
+{ "functions": { "app/api/heavy/route.ts": { "maxDuration": 60, "memory": 3008 } } }
+```
+
+**Build Command Issues:**
+```bash
+vercel --build-env NODE_OPTIONS="--max-old-space-size=4096"
+```
+
+### Environment Variables
+
+```bash
+vercel env ls                 # List all env vars
+vercel env add VAR_NAME       # Add missing var
+vercel env pull .env.local    # Pull to local
+```
+
+**Remember:** `NEXT_PUBLIC_*` for client-side, plain names for server-side only.
+
+### CORS Issues
+Add proper CORS headers in API routes with explicit origin allowlist.
+
+### Function Timeouts
+Increase `maxDuration` in vercel.json (up to 300s on Pro plan).
+
+---
+
+## Rollback
+
+```bash
+vercel ls                     # List deployments
+vercel rollback               # Rollback to previous
+vercel rollback [url]         # Rollback to specific deployment
+```
+
+---
+
+## Domain Management
+
+```bash
+vercel domains add example.com
+vercel domains ls
+vercel certs issue example.com  # Force SSL renewal
+```
+
+DNS: A record `@ → 76.76.21.21`, CNAME `www → cname.vercel-dns.com`
+
+---
+
+## vercel.json Reference
+
+```json
+{
+  "framework": "nextjs",
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "X-Frame-Options", "value": "DENY" },
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" }
+      ]
+    }
+  ],
+  "crons": [{ "path": "/api/cron/daily", "schedule": "0 0 * * *" }]
+}
+```
+
+---
+
+## When Things Go Wrong
+
+### Build Fails Locally
+
+**TypeScript errors:**
+```bash
+npx tsc --noEmit 2>&1 | head -40    # See first errors
+npx tsc --noEmit 2>&1 | grep -c "error TS"  # Count total errors
+```
+- Fix type errors before deploying — Vercel will hit the same failures
+- If errors are in node_modules: `rm -rf node_modules && npm install`
+- If errors are in generated types: `supabase gen types typescript --linked > types/supabase.ts`
+
+**Missing dependencies:**
+```bash
+npm ls 2>&1 | grep "MISSING"        # Find missing deps
+npm install                          # Reinstall all
+rm -rf node_modules/.cache && npm run build  # Clear build cache
+```
+
+**Environment variables not set:**
+```bash
+# Check what the build expects
+grep -r "process.env\." --include="*.ts" --include="*.tsx" -h | grep -oP 'process\.env\.\K[A-Z_]+' | sort -u
+# Compare with what's set
+env | grep -E "^(NEXT_|SUPABASE_|VAPI_)" | cut -d= -f1 | sort
+```
+Fix: Copy from `.env.local` or `vercel env pull .env.local`.
+
+### Build Passes Locally, Fails on Vercel
+
+**Different Node version:**
+```bash
+node -v                              # Local version
+# Check Vercel: Settings → General → Node.js Version
+```
+Fix: Add to `package.json`:
+```json
+{ "engines": { "node": ">=20.0.0" } }
+```
+
+**Missing env vars on Vercel:**
+```bash
+vercel env ls                        # See what's set per environment
+vercel env ls production             # Production-specific
+```
+Fix: `vercel env add VARIABLE_NAME production` — or use Vercel dashboard → Settings → Environment Variables.
+
+Common gotcha: `NEXT_PUBLIC_*` vars must be set at **build time** (not just runtime). If you added one after the last deploy, redeploy.
+
+**Case sensitivity:** Linux (Vercel) is case-sensitive, macOS isn't.
+```bash
+# Find case mismatches in imports
+grep -rn "from ['\"]\./" --include="*.ts" --include="*.tsx" | while read line; do
+  file=$(echo "$line" | grep -oP "from ['\"]\.\/\K[^'\"]+")
+  # Check if the file exists with exact case
+done
+```
+Fix: Rename files to match import casing exactly.
+
+### Deploy Succeeds But Site is Broken
+
+**White screen (client crash):**
+```bash
+# Check Vercel function logs
+vercel logs <deployment-url> --follow
+# Check for hydration errors in browser console
+node ~/.claude/skills/deploy-verify/scripts/check-console-errors.js <url>
+```
+Common causes:
+- `window` or `document` used in server component → wrap in `useEffect` or add `'use client'`
+- Hydration mismatch → check for `Date.now()`, `Math.random()`, or browser-only APIs in SSR
+- Missing `'use client'` directive on component using hooks
+
+**500 errors on API routes:**
+```bash
+vercel logs <deployment-url> 2>&1 | grep -i "error\|500"
+```
+Common causes:
+- Env var exists locally but not on Vercel (`vercel env ls`)
+- API route importing a server-only module incorrectly
+- Database connection string pointing to localhost
+
+**Hydration mismatch:**
+```bash
+# Search for dynamic content rendered during SSR
+grep -rn "Date.now\|Math.random\|window\.\|document\.\|localStorage" --include="*.tsx" --include="*.ts" app/
+```
+Fix: Wrap dynamic content in `useEffect` or use `suppressHydrationWarning` on the specific element (not as a blanket fix).
+
+**Rollback immediately if production is broken:**
+```bash
+vercel rollback --prod               # Instant rollback
+vercel ls | head -5                  # See recent deployments
+vercel inspect <old-deployment-url>  # Check what was different
+```
+
+### Deploy Succeeds But Migrations Weren't Applied
+
+Symptoms: New columns/tables don't exist, API returns "column X does not exist".
+
+```bash
+# Check what migrations are pending
+supabase migration list --project-ref <ref>
+# Push pending migrations
+supabase db push --project-ref <ref>
+# Verify the schema
+supabase db dump --schema public --project-ref <ref> | grep "table_name"
+```
+
+Prevention: Add migration push to your deploy flow:
+```bash
+supabase db push --project-ref <ref> && vercel --prod
+```
+
+### Vercel Rate Limit or Quota Exceeded
+
+Symptoms: `429 Too Many Requests` or deployment stuck in queue.
+
+```bash
+# Check current usage
+vercel teams ls                      # See team/plan info
+# Wait and retry
+sleep 60 && vercel --prod            # Rate limits usually clear in ~60s
+```
+
+If on Hobby plan: max 100 deployments/day. Switch to `--preview` for testing, save `--prod` for real deploys.
+
+If build minutes exhausted: Wait for monthly reset, or upgrade plan.
+
+### Domain DNS Not Propagating
+
+Symptoms: Site works at `*.vercel.app` but not at custom domain.
+
+```bash
+# Check DNS resolution
+dig A yourdomain.com +short           # Should show 76.76.21.21
+dig CNAME www.yourdomain.com +short   # Should show cname.vercel-dns.com
+nslookup yourdomain.com               # Alternative check
+```
+
+**DNS not pointing to Vercel:**
+```bash
+vercel domains inspect yourdomain.com  # Shows expected DNS records
+```
+Fix: Update DNS at your registrar. A record → `76.76.21.21`, CNAME → `cname.vercel-dns.com`.
+
+**SSL not provisioning:**
+```bash
+vercel certs ls                       # Check cert status
+vercel certs issue yourdomain.com     # Force re-issue
+```
+Note: DNS propagation takes 5 min to 48 hours. Check with `dig` — if DNS is correct but SSL isn't ready, wait or force re-issue.
+
+**Temporary workaround while DNS propagates:**
+Share the `*.vercel.app` URL with the client until the custom domain resolves.

package/framework/skills/deploy-verify/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: deploy-verify
+description: Run post-deploy 8-check verification and T+2min canary health check against baseline. Run after vercel --prod deployments to verify.
+user-invocable: true
+---
+
+# Deploy Verification
+
+Production verification suite — 8 checks with retry logic, auto-detection of the current project, and actionable failure remediation.
+
+Invoked automatically after `vercel --prod` (via PostToolUse hook) or manually with `/deploy-verify <URL>`.
+
+## Project Auto-Detection
+
+The skill determines which project is being verified:
+
+1. Read the current working directory name
+2. Match against the project inventory in `~/.claude/knowledge/qualia-context.md`
+3. Extract: project name, Supabase ref (if any), hosting type, known endpoints
+4. If no match: run in generic mode (skip Supabase-specific checks)
+
+This means you don't need to pass a Supabase ref or project name — it's derived from context.
+
+## The 8 Checks
+
+### Check 1: HTTP Status (CRITICAL)
+
+Verify the site loads successfully.
+
+- **Endpoints tested:** Root URL (`/`) and `/api/health` (if it exists)
+- **Retry:** 3 attempts with exponential backoff (5s → 15s → 30s)
+- **Follow redirects** (`-L`) — but log the redirect chain
+- **PASS:** HTTP 200 on root URL
+- **WARN:** HTTP 200 but only after redirect (3xx → 200)
+- **FAIL:** Any non-200 final status, timeout, or connection refused
+- **CRITICAL:** If root URL fails all 3 retries, halt verification — nothing else matters
+
+```bash
+# Core logic
+curl -sL -o /dev/null -w "%{http_code}" --max-time 15 "$URL"
+curl -sL -o /dev/null -w "%{http_code}" --max-time 15 "$URL/api/health"
+```
+
+### Check 2: Auth Flow
+
+Verify authentication is functional (if the project uses auth).
+
+- **Step 1:** Hit a known protected route (e.g., `/dashboard`, `/admin`, `/app`)
+  - Expect: 302/307 redirect to login page OR 401
+  - PASS if redirect target contains `/login`, `/auth`, `/sign-in`
+- **Step 2:** Check Supabase auth health (if project has a Supabase ref)
+  - Query: `https://<ref>.supabase.co/auth/v1/health`
+  - Expect: HTTP 200 with `{"status":"ok"}`
+- **Step 3:** Verify auth callback endpoint exists
+  - Check: `/api/auth/callback`, `/auth/callback`
+  - Expect: non-404 response
+- **PASS:** Protected route redirects correctly AND Supabase auth is healthy
+- **WARN:** Auth callback exists but protected route test is ambiguous
+- **SKIP:** No auth endpoints detected and no Supabase ref (static site)
+- **FAIL:** Supabase auth unhealthy, or protected route returns 500
+
+```bash
+# Supabase auth health
+curl -s "https://${SUPABASE_REF}.supabase.co/auth/v1/health" | jq -r '.status'
+```
+
+### Check 3: Console Errors (Headless Browser)
+
+Detect client-side JavaScript errors using Playwright.
+
+- **How:** Run `scripts/check-console-errors.js` which:
+  1. Launches headless Chromium via Playwright
+  2. Navigates to the URL
+  3. Listens for `console.error` and `pageerror` events
+  4. Waits for `networkidle`
+  5. Returns collected errors
+- **PASS:** Zero console errors
+- **WARN:** Console errors present but all are known benign patterns (e.g., third-party tracking, browser extension noise)
+- **FAIL:** Any console error matching: `TypeError`, `ReferenceError`, `SyntaxError`, `ChunkLoadError`, `Unhandled`, `NEXT_`, `500`, `Internal Server Error`
+- **Fallback:** If Playwright unavailable, fall back to curl-based HTML inspection (check for server error strings in page source — same as the old approach, clearly marked as degraded)
+
+```bash
+node ~/.claude/skills/deploy-verify/scripts/check-console-errors.js "$URL"
+```
+
+### Check 4: API Latency
+
+Measure response times against defined thresholds.
+
+- **Endpoints tested:** At minimum the root URL + one API route (auto-detected or `/api/health`)
+- **Thresholds:**
+  - `< 500ms` → **PASS** (green)
+  - `500ms – 1000ms` → **WARN** (yellow — acceptable but monitor)
+  - `> 1000ms` → **FAIL** (red — too slow for production)
+- **Measurement:** `curl -w "%{time_total}"` — measures full request cycle (DNS + connect + TLS + transfer)
+- **Run 3 times** and report the median to avoid outliers
+
+```bash
+# Measure in ms
+curl -sL -o /dev/null -w "%{time_total}" --max-time 15 "$URL" | awk '{printf "%.0f", $1 * 1000}'
+```
+
+### Check 5: Database Connectivity (NEW)
+
+Verify Supabase is reachable and responding.
+
+- **Requires:** Supabase ref from qualia-context.md
+- **Method:** Use the Supabase REST API to run a simple health query
+  - `GET https://<ref>.supabase.co/rest/v1/?apikey=<anon_key>` — should return non-error
+  - OR use `supabase` CLI: `supabase db execute --project-ref <ref> "SELECT 1"`
+- **PASS:** Query returns successfully
+- **WARN:** Query succeeds but latency > 500ms
+- **FAIL:** Connection refused, timeout, or auth error
+- **SKIP:** Project has no Supabase ref (static site)
+
+```bash
+# CLI approach
+supabase db execute --project-ref "$SUPABASE_REF" "SELECT 1 AS health"
+```
+
+### Check 6: Core Web Vitals (NEW)
+
+Measure LCP, CLS, and INP using Google PageSpeed Insights API.
+
+- **Method:** Run `scripts/check-cwv.js` which calls the PageSpeed Insights API (no key needed for basic usage)
+  - `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<URL>&strategy=mobile`
+- **Metrics and thresholds** (from Google's standards):
+  - **LCP** (Largest Contentful Paint): < 2.5s PASS, 2.5–4s WARN, > 4s FAIL
+  - **CLS** (Cumulative Layout Shift): < 0.1 PASS, 0.1–0.25 WARN, > 0.25 FAIL
+  - **INP** (Interaction to Next Paint): < 200ms PASS, 200–500ms WARN, > 500ms FAIL
+- **PASS:** All three metrics in green
+- **WARN:** Any metric in yellow range
+- **FAIL:** Any metric in red range
+- **Fallback:** If API is unreachable, mark as SKIP with note
+
+```bash
+node ~/.claude/skills/deploy-verify/scripts/check-cwv.js "$URL"
+```
+
+### Check 7: Dependency Services (NEW)
+
+Verify external services the project depends on.
+
+- **Auto-detect dependencies** by reading the project's `.env.local` or `.env` variable names (not values):
+  - `NEXT_PUBLIC_SUPABASE_URL` → Supabase (already checked in #5)
+  - `VAPI_*` → VAPI API health
+  - `OPENROUTER_*` → OpenRouter status
+  - `ELEVEN_LABS_*` → ElevenLabs status
+  - `RETELL_*` → Retell AI status
+  - `STRIPE_*` → Stripe API status
+  - `TELNYX_*` → Telnyx status
+- **Method:** HTTP GET to each service's known status/health endpoint
+- **PASS:** All detected services responding
+- **WARN:** A non-critical service is degraded (e.g., analytics)
+- **FAIL:** A critical dependency is down
+- **SKIP:** No external dependencies detected beyond Supabase
+
+### Check 8: SSL Certificate (NEW)
+
+Verify TLS certificate validity.
+
+- **Method:** `openssl s_client` to inspect the certificate
+- **Check:** Certificate is valid, matches the domain, and has > 30 days until expiry
+- **PASS:** Valid cert, > 30 days remaining
+- **WARN:** Valid cert, 7–30 days remaining
+- **FAIL:** Expired, mismatched domain, or < 7 days remaining
+
+```bash
+echo | openssl s_client -servername "$DOMAIN" -connect "$DOMAIN:443" 2>/dev/null | openssl x509 -noout -dates -checkend 2592000
+```
+
+## Retry Logic
+
+Applied to **every check** (not just HTTP):
+
+| Attempt | Delay Before Retry |
+|---------|-------------------|
+| 1st     | Immediate         |
+| 2nd     | 5 seconds         |
+| 3rd     | 15 seconds        |
+| Final   | 30 seconds        |
+
+- A check only gets status FAIL after **all retries exhausted**
+- Between retries, log: `⟳ Retrying <check> (attempt 2/3, waiting 15s)...`
+- Checks that PASS or WARN on any attempt stop retrying
+
+## Output Format
+
+```
+══════════════════════════════════════════════════════
+  DEPLOY VERIFICATION — projectname
+  URL: https://project.vercel.app
+  Timestamp: 2026-03-04 17:30:42 UTC
+══════════════════════════════════════════════════════
+
+  ✓ PASS  HTTP Status        200 OK (142ms)
+  ✓ PASS  Auth Flow          Protected /dashboard → /login redirect, Supabase auth healthy
+  ⚠ WARN  Console Errors     1 non-critical error (third-party tracking pixel)
+  ✓ PASS  API Latency        Root: 287ms, /api/health: 145ms
+  ✓ PASS  DB Connectivity    Supabase responding (89ms)
+  ⚠ WARN  Core Web Vitals    LCP: 2.1s ✓  CLS: 0.12 ⚠  INP: 95ms ✓
+  ✓ PASS  Dependencies       Stripe ✓  VAPI ✓
+  ✓ PASS  SSL Certificate    Valid, expires in 68 days
+
+──────────────────────────────────────────────────────
+  RESULT: 6 PASS · 2 WARN · 0 FAIL
+  Total verification time: 34.2s
+──────────────────────────────────────────────────────
+```
+
+- Each line shows: status icon, check name (padded), and specific detail
+- Timestamps in UTC
+- Total time measured from start to finish
+
+## When Verification Fails
+
+### Decision Tree
+
+```
+                    ┌─────────────────┐
+                    │  Run 8 Checks   │
+                    └────────┬────────┘
+                             │
+                ┌────────────┴────────────┐
+                │                         │
+          All PASS/WARN              Any FAIL
+                │                         │
+          ✅ Deploy OK           ┌────────┴────────┐
+                                 │                  │
+                           1 FAIL only        2+ FAIL
+                                 │                  │
+                        Investigate &          ROLLBACK
+                        fix specific       immediately
+                        check                   │
+                                          ┌─────┴──────┐
+                                          │            │
+                                    HTTP FAIL    Other FAIL
+                                    (CRITICAL)        │
+                                          │      vercel rollback
+                                    IMMEDIATE        --prod
+                                    ROLLBACK          │
+                                          │      Re-verify
+                                    vercel rollback   previous
+                                      --prod       deployment
+```
+
+### Severity Levels
+
+- **CRITICAL** (immediate rollback): HTTP Status fails (site is down)
+- **HIGH** (rollback if can't fix in 10 min): Auth flow broken, DB connectivity lost
+- **MEDIUM** (investigate, no rollback): Console errors, high latency, SSL warning
+- **LOW** (monitor): CWV warnings, dependency warnings
+
+### Rollback Procedure
+
+```bash
+# 1. Rollback to previous deployment
+vercel rollback --prod
+
+# 2. Re-run verification on rolled-back version
+bash ~/.claude/skills/deploy-verify/scripts/verify.sh <URL>
+
+# 3. Investigate the failed deployment
+vercel inspect <deployment-url>
+vercel logs <deployment-url>
+```
+
+### What to Check Per Failure
+
+| Failed Check        | First Step                                           |
+|---------------------|------------------------------------------------------|
+| HTTP Status         | `vercel logs <url>` — check for build/runtime errors |
+| Auth Flow           | Check Supabase dashboard → Auth → Settings           |
+| Console Errors      | Open browser DevTools → Console, look for the error  |
+| API Latency         | `vercel logs <url>` — check for slow queries         |
+| DB Connectivity     | Supabase dashboard → Database → check if paused      |
+| Core Web Vitals     | PageSpeed Insights → check largest element, layout shifts |
+| Dependencies        | Check service status page for the failing provider   |
+| SSL Certificate     | Vercel dashboard → Domains → check cert status       |
+
+## Scripts
+
+All helper scripts live in `~/.claude/skills/deploy-verify/scripts/`:
+
+| Script                    | Purpose                                    |
+|---------------------------|-------------------------------------------|
+| `verify.sh`              | Main orchestrator — runs all 8 checks      |
+| `check-console-errors.js`| Playwright headless browser console check  |
+| `check-cwv.js`           | PageSpeed Insights API for Core Web Vitals |
+| `project-detect.sh`      | Auto-detect project from cwd               |
+
+## Usage
+
+```bash
+# Auto-detect project, run full verification
+bash ~/.claude/skills/deploy-verify/scripts/verify.sh <URL>
+
+# The skill is also invoked automatically by the PostToolUse hook
+# after any `vercel --prod` command completes
+```
+
+## Pre-Deploy Review Check
+
+Before running the 8 verification checks, read the review file:
+
+1. Check `.planning/REVIEW.md` then `.review/REVIEW.md`
+2. If found: parse frontmatter of the most recent entry
+   - `status: has_blockers` → **WARN** with list of CRITICAL/HIGH findings. Ask user: "Deploy anyway?" or "Fix first?"
+   - `status: clean` → Note "Pre-deploy review: clean" and continue
+3. If not found → **WARN**: "No `/review` found. Consider running `/review` before deploying." (advisory only, not blocking)
+
+Recommended workflow: `/review` → fix findings → `/ship` → (auto-triggers `/deploy-verify`)
+
+## When to Invoke
+
+- Automatically after `vercel --prod` (PostToolUse hook)
+- After any production deployment via `/ship`
+- Manually when you want to verify a live deployment
+- After a rollback to confirm the previous version is healthy
+
+## Canary Monitoring (T+2min Post-Deploy)
+
+After the 8 verification checks pass, a canary check is automatically scheduled to run 120 seconds later. This catches regressions that manifest after CDN propagation and cache warming.
+
+### What It Checks
+
+| Metric | Baseline Source | Regression Threshold |
+|--------|----------------|---------------------|
+| HTTP Status | `canary-baseline.json` | Any status change from baseline |
+| Console Errors | `canary-baseline.json` | Any increase over baseline count |
+| Page Load Time | `canary-baseline.json` | Exceeds 2x baseline time |
+
+### Baseline Management
+
+The baseline is stored per-project at `.planning/canary-baseline.json`. It is auto-created on first deploy-verify run (captures current metrics as the known-good state).
+
+To manually update the baseline (after intentional performance changes):
+
+```bash
+bash ~/.claude/skills/deploy-verify/scripts/canary-check.sh <URL> --update-baseline --project-dir /path/to/project
+```
+
+### Consecutive Failure Policy
+
+A single canary failure produces a warning but no alert. Only 2 or more consecutive failures trigger a regression flag. This prevents false alarms from transient network issues or CDN cache warming.
+
+Consecutive failure state is tracked in `/tmp/.canary-failures-<url-hash>` and resets automatically on any passing canary check.
+
+### Canary Output
+
+```
+──────────────────────────────────────────────────────
+  CANARY CHECK — T+2min post-deploy
+  URL: https://project.vercel.app
+  Baseline: 2026-03-29T12:00:00Z
+──────────────────────────────────────────────────────
+
+  Metric               Baseline     Current      Status
+  ──────────────────── ──────────── ──────────── ────────────
+  HTTP Status          200          200          OK
+  Console Errors       0            0            OK
+  Load Time (ms)       287          312          OK (<574ms)
+
+  CANARY PASS — All metrics within baseline thresholds
+```
+
+### Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `canary-check.sh` | Canary engine — collect metrics, compare to baseline, track failures |
+
+### When Canary Runs
+
+- Automatically: 120s after `verify.sh` completes with 0 failures (background process)
+- Manually: `bash ~/.claude/skills/deploy-verify/scripts/canary-check.sh <URL> --project-dir /path`
+- Baseline update: Add `--update-baseline` flag to capture current state as new baseline