qualia-framework 2.6.0 → 3.2.0

package/framework/skills/deploy/SKILL.md

@@ -1,261 +0,0 @@
----
-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

@@ -1,377 +0,0 @@
----
-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