qualia-framework 2.1.0 → 2.1.3

package/framework/hooks/session-context-loader.sh

@@ -1,28 +1,77 @@
 #!/bin/bash
-# SessionStart hook — provides context for qualia-start skill
-# CLAUDE.md instructs Claude to invoke /qualia-start on every session start
-# This hook just passes along any resume hints
-
+# SessionStart hook — teal-branded session context
+# Shows resume hints to user via stderr, passes context to Claude via JSON stdout
 source "$(dirname "$0")/qualia-colors.sh"
 
 CWD=$(pwd)
 SESSION_DIR="$HOME/.claude/session-env"
 COMPACT_FILE="$SESSION_DIR/pre-compact.json"
-HINTS=""
+PROJECT=$(basename "$CWD")
 
-# Check for handoff file
-[ -f "$CWD/.continue-here.md" ] && HINTS="Handoff file exists — read .continue-here.md. "
+# ─── Visual output (stderr → user sees this) ───
+q_header "SESSION START"
 
-# Check last session
+# Last session info
 if [ -f "$COMPACT_FILE" ]; then
     LAST_PROJECT=$(node -e "try{const d=JSON.parse(require('fs').readFileSync('$COMPACT_FILE','utf8'));process.stdout.write(d.project_name||'')}catch(e){}" 2>/dev/null)
-    [ -n "$LAST_PROJECT" ] && [ "$LAST_PROJECT" != ".claude" ] && HINTS="${HINTS}Last session: ${LAST_PROJECT}. "
+    LAST_BRANCH=$(node -e "try{const d=JSON.parse(require('fs').readFileSync('$COMPACT_FILE','utf8'));process.stdout.write(d.git_branch||'')}catch(e){}" 2>/dev/null)
+    if [ -n "$LAST_PROJECT" ] && [ "$LAST_PROJECT" != ".claude" ]; then
+        q_info "Last session: ${LAST_PROJECT} (${LAST_BRANCH:-no branch})"
+    fi
+fi
+
+# Current project
+q_pass "Project: ${PROJECT}"
+
+# Handoff file
+if [ -f "$CWD/.continue-here.md" ]; then
+    q_warn "Handoff file found — .continue-here.md"
+fi
+
+# Errors / warnings
+ERRORS=0
+
+# Check hooks health
+HOOKS_OK=0
+HOOKS_TOTAL=0
+for h in branch-guard pre-commit confirm-delete migration-validate pre-deploy-gate block-env-edit auto-format session-context-loader retention-cleanup pre-compact save-session-state session-learn notification-speak qualia-colors; do
+    HOOKS_TOTAL=$((HOOKS_TOTAL + 1))
+    [ -f "$HOME/.claude/hooks/${h}.sh" ] && HOOKS_OK=$((HOOKS_OK + 1))
+done
+
+if [ "$HOOKS_OK" -eq "$HOOKS_TOTAL" ]; then
+    q_pass "Hooks: ${HOOKS_OK}/${HOOKS_TOTAL}"
+else
+    q_fail "Hooks: ${HOOKS_OK}/${HOOKS_TOTAL} — $(( HOOKS_TOTAL - HOOKS_OK )) missing"
+    ERRORS=$((ERRORS + 1))
 fi
 
-if [ -n "$HINTS" ]; then
-    printf '{"continue":true,"systemMessage":"%s"}' "$HINTS"
+# Check CLAUDE.md exists
+if [ -f "$HOME/.claude/CLAUDE.md" ]; then
+    ROLE=$(grep -m1 "^## Role:" "$HOME/.claude/CLAUDE.md" 2>/dev/null | sed 's/^## Role: *//')
+    q_pass "Role: ${ROLE:-unknown}"
 else
-    printf '{"continue":true}'
+    q_fail "CLAUDE.md missing — run npx qualia-framework"
+    ERRORS=$((ERRORS + 1))
+fi
+
+# Check settings.json valid
+if [ -f "$HOME/.claude/settings.json" ]; then
+    node -e "JSON.parse(require('fs').readFileSync('$HOME/.claude/settings.json','utf8'))" 2>/dev/null
+    if [ $? -eq 0 ]; then
+        q_pass "Settings: valid"
+    else
+        q_fail "Settings: invalid JSON!"
+        ERRORS=$((ERRORS + 1))
+    fi
 fi
 
+if [ "$ERRORS" -gt 0 ]; then
+    q_warn "${ERRORS} issue(s) — check above"
+fi
+
+q_info "Activating Qualia mode..."
+
+# ─── JSON output (stdout → Claude reads this) ───
+printf '{"continue":true}'
 exit 0

package/framework/hooks/skill-announce.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Announce skill activation in teal — fires on every Skill() invocation
+source "$(dirname "$0")/qualia-colors.sh"
+
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    SKILL_NAME=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_input?.skill||d.tool_input?.name||'')}catch(e){}" 2>/dev/null)
+fi
+
+[ -z "$SKILL_NAME" ] && exit 0
+
+# Clean up skill name for display
+DISPLAY_NAME=$(echo "$SKILL_NAME" | sed 's/-/ /g' | sed 's/qualia //g')
+
+q_header "${DISPLAY_NAME^^} activated"
+
+printf '{"continue":true}'
+exit 0

package/framework/hooks/tool-error-announce.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Announce tool failures in teal+red — fires on PostToolUseFailure
+source "$(dirname "$0")/qualia-colors.sh"
+
+if [ ! -t 0 ]; then
+    INPUT=$(cat)
+    TOOL_NAME=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.tool_name||'')}catch(e){}" 2>/dev/null)
+    ERROR=$(echo "$INPUT" | node -e "try{const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));process.stdout.write(d.error||d.tool_output?.stderr||'')}catch(e){}" 2>/dev/null)
+fi
+
+[ -z "$TOOL_NAME" ] && exit 0
+
+q_header "ERROR"
+q_fail "${TOOL_NAME} failed"
+[ -n "$ERROR" ] && q_info "$(echo "$ERROR" | head -3)"
+
+printf '{"continue":true}'
+exit 0

package/framework/skills/qualia-help/SKILL.md

@@ -60,8 +60,9 @@ Display the command reference. Output only — no analysis, no suggestions, just
 ### Quality & Deployment
 | Skill | Description |
 |-------|-------------|
+| `qualia-production-check` | Final client-handoff audit — 5 agents check UX, auth, backend, perf, completeness |
 | `qualia-audit-milestone` | Verify milestone definition of done |
 | `qualia-plan-milestone-gaps` | Create fix phases from audit gaps |
-| `qualia-review` | Production audit and code review |
+| `qualia-review` | Code review (security, quality, architecture) |
 | `ship` | Full production deployment pipeline |
 | `team` | Agent team orchestration |

package/framework/skills/qualia-production-check/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: qualia-production-check
+description: "Final client-handoff production audit — spawns 5+ specialist agents to check EVERYTHING before handing a project to a client. Frontend, backend, auth, UX, Supabase, silent errors, misconfigs, SEO, performance, accessibility, legal pages, error handling — the works. Use this skill whenever the user says 'production check', 'client ready', 'is it ready', 'final check', 'handoff check', 'production audit', 'ready for client', 'qualia-production-check', 'final audit', 'pre-handoff', or wants to verify a project is truly ready to give to a client."
+---
+
+# Qualia Production Check — Client-Handoff Audit
+
+This is THE final check before handing a project to a client. Not a code review — a **production readiness audit** that checks everything a real user will experience.
+
+Spawns 5 specialist agents in parallel, each checking a different dimension. Then synthesizes into a structured verdict with actionable next steps.
+
+## Usage
+
+- `/qualia-production-check` — Full audit (all 5 dimensions)
+
+## Process
+
+### Step 1: Load Context
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
+cat .planning/REQUIREMENTS.md 2>/dev/null || echo "NO_REQUIREMENTS"
+cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
+```
+
+```bash
+node -e "try{const p=require('./package.json');console.log(JSON.stringify({name:p.name,deps:Object.keys(p.dependencies||{}),devDeps:Object.keys(p.devDependencies||{})}))}catch(e){console.log('{}')}" 2>/dev/null
+```
+
+```bash
+ls -d app/ src/ pages/ components/ lib/ supabase/ public/ 2>/dev/null
+```
+
+Read `~/.claude/rules/security.md` and `~/.claude/rules/frontend.md`.
+
+Detect project type: website, AI agent, voice agent, web app, mobile.
+
+Store all content — inline into agent prompts.
+
+### Step 2: Spawn 5 Agents (parallel, single message)
+
+All agents get PROJECT.md + REQUIREMENTS.md inlined. Every finding must include: **What** | **Where** (file:line) | **Impact on client/users** | **Fix** | **Severity** (BLOCKER / WARNING / INFO).
+
+BLOCKER = client will see this and it's bad. WARNING = should fix but won't break. INFO = nice to have.
+
+#### Agent 1: User Experience & Frontend
+
+```
+Task(
+  prompt="You are auditing the user experience of a production web app that will be handed to a client.
+
+<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
+<rules>{frontend.md}</rules>
+
+Check EVERY page in app/ — open each page.tsx and layout.tsx:
+
+1. **First impression** — Does the homepage look professional? Distinctive design or generic AI slop?
+2. **Navigation** — Can users find everything? Are all nav links working? No dead links?
+3. **Loading states** — Every async operation shows feedback (skeleton, spinner, progress)
+4. **Error states** — What happens when API fails? Network disconnects? Wrong URL?
+5. **Empty states** — What do lists/tables show when empty? Helpful message or just blank?
+6. **Forms** — Validation on submit? Clear error messages? Success feedback? Disabled state while submitting?
+7. **Mobile responsive** — Check for fixed widths, overflow, touch targets too small, text readable
+8. **Typography** — Consistent fonts, readable sizes, proper hierarchy, no tiny gray text
+9. **Images** — Using next/image? Alt text? Proper sizing? Not stretched or pixelated?
+10. **404 page** — Does app/not-found.tsx exist? Is it styled? Does it help the user?
+11. **Favicon & metadata** — Title, description, OG tags, favicon all set?
+12. **Console errors** — Grep for console.log/console.error left in production code
+13. **Accessibility** — Alt text, ARIA labels, keyboard navigation, color contrast
+
+For EVERY finding: What | Where (file:line) | Impact on client | Fix | Severity (BLOCKER/WARNING/INFO)",
+  subagent_type="frontend-agent",
+  description="UX & frontend production audit"
+)
+```
+
+#### Agent 2: Auth, Security & Data Protection
+
+```
+Task(
+  prompt="You are auditing authentication and security for client handoff.
+
+<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
+<rules>{security.md}</rules>
+
+Check:
+
+1. **Auth flow completeness** — Login, signup, logout, password reset ALL work? Email verification?
+2. **Protected routes** — Every dashboard/admin/settings page checks auth? What happens if unauthenticated user visits?
+3. **RLS policies** — EVERY Supabase table has Row Level Security enabled WITH policies. No table left unprotected.
+4. **Service role exposure** — Grep for service_role or SUPABASE_SERVICE_ROLE_KEY in ANY client-side file (app/, components/, src/). Must be ZERO.
+5. **Server-side auth** — All mutations use supabase.auth.getUser() server-side. No client-side mutations with user-supplied IDs.
+6. **Input validation** — All user inputs validated with Zod or equivalent. No raw req.body usage.
+7. **XSS prevention** — No dangerouslySetInnerHTML. No eval(). No user content rendered unsanitized.
+8. **CORS** — Properly restricted, not wildcard '*' in production.
+9. **Rate limiting** — Auth endpoints (login, signup, reset) have rate limiting.
+10. **Secrets in code** — No hardcoded API keys, passwords, tokens in source files.
+11. **Environment variables** — All secrets in env vars. NEXT_PUBLIC_ only for client-safe values.
+12. **Session management** — Tokens expire and refresh properly. Logout clears session.
+
+For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
+  subagent_type="backend-agent",
+  description="Auth & security production audit"
+)
+```
+
+#### Agent 3: Backend, Database & API
+
+```
+Task(
+  prompt="You are auditing the backend and database for production readiness.
+
+<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
+
+Check:
+
+1. **API error handling** — Every API route/server action has try/catch. Errors return proper HTTP status codes with meaningful messages. No stack traces exposed to client.
+2. **Database queries** — N+1 queries (Supabase calls in loops)? Missing indexes on filtered columns? Sequential queries that could be parallel?
+3. **Server actions** — All data mutations use 'use server' actions, not client-side Supabase calls? Each checks auth first?
+4. **Supabase connection** — Using server.ts for mutations, client.ts for reads? Connection pooling configured?
+5. **Migrations** — All migrations applied? Types generated and up to date? Schema matches what code expects?
+6. **Edge functions** — If supabase/functions/ exists: error handling, CORS, timeout protection, proper responses.
+7. **Caching** — revalidatePath/revalidateTag after mutations? SWR/React Query configured with sensible stale times?
+8. **Pagination** — Large data sets paginated? Not loading 10,000 rows into memory?
+9. **File uploads** — If any: size limits, type validation, virus scanning, proper storage?
+10. **Webhooks** — If any: signature verification, idempotency, error handling, retry logic?
+11. **Background jobs** — Long-running operations handled async? Not blocking API responses?
+12. **Monitoring** — Error tracking configured (Sentry or similar)? Logging meaningful events?
+
+For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
+  subagent_type="backend-agent",
+  description="Backend & database production audit"
+)
+```
+
+#### Agent 4: Performance & SEO
+
+```
+Task(
+  prompt="You are auditing performance and SEO for a client-facing production site.
+
+Check:
+
+1. **Build succeeds** — Run npm run build mentally (check for obvious build errors in imports, missing modules)
+2. **Bundle size** — Large library imports without tree-shaking? Barrel exports? Missing dynamic imports for heavy components (charts, editors, maps)?
+3. **Images** — All using next/image? WebP/AVIF format? Proper width/height? Lazy loading below fold?
+4. **Fonts** — Using next/font? No render-blocking external font loads?
+5. **Core Web Vitals** — Largest Contentful Paint risks? Cumulative Layout Shift risks? Large unoptimized images above fold?
+6. **SEO metadata** — Every page has title, description. Root layout has proper metadata. Open Graph tags for social sharing?
+7. **Sitemap** — public/sitemap.xml exists? Lists all public pages?
+8. **Robots.txt** — public/robots.txt exists? Not blocking important pages?
+9. **Structured data** — JSON-LD for business info, breadcrumbs, or relevant schema?
+10. **Canonical URLs** — Proper canonical tags to avoid duplicate content?
+11. **Lighthouse hints** — Server components used where possible? No unnecessary 'use client' directives?
+12. **API latency** — Any obvious slow queries or waterfalls in the data fetching pattern?
+
+For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
+  subagent_type="performance-oracle",
+  description="Performance & SEO production audit"
+)
+```
+
+#### Agent 5: Completeness & Missing Features
+
+```
+Task(
+  prompt="You are checking if a project is COMPLETE — nothing missing that a client would expect.
+
+<planning>{PROJECT.md + REQUIREMENTS.md + ROADMAP.md}</planning>
+
+Check against requirements AND common expectations:
+
+1. **Requirements coverage** — Every requirement in REQUIREMENTS.md marked complete: does the feature ACTUALLY work in code? Grep for routes, components, API endpoints that implement each requirement.
+2. **Missing pages** — Common pages that clients expect: About, Contact, Privacy Policy, Terms of Service, 404, 500 error page. Which are missing?
+3. **Missing functionality** — Based on project type:
+   - Website: contact form works? Newsletter signup? Social links?
+   - Web app: settings page? Profile management? Change password? Delete account?
+   - AI agent: fallback responses? Rate limiting? Usage tracking?
+4. **Email** — If the app sends emails: are they configured? Working? Proper templates? Not going to spam?
+5. **Analytics** — Tracking configured? Google Analytics / Plausible / PostHog?
+6. **Error boundaries** — app/error.tsx exists? Styled? Provides recovery action?
+7. **Loading** — app/loading.tsx or Suspense boundaries on data-fetching pages?
+8. **Favicon & branding** — Custom favicon (not Next.js default)? Proper app title? OG image?
+9. **Legal compliance** — Cookie consent if in EU? Privacy policy if collecting data? Terms if SaaS?
+10. **Mobile** — Site works on mobile? No horizontal scroll? Touch targets adequate?
+11. **Cross-browser** — Any IE/Safari-specific CSS issues? Webkit prefixes needed?
+12. **Deployment config** — Vercel configured? Environment variables set? Domain connected?
+
+For EVERY finding: What | Where | Impact on client | Fix | Severity (BLOCKER/WARNING/INFO)",
+  subagent_type="general-purpose",
+  description="Completeness & missing features audit"
+)
+```
+
+### Step 3: Collect & Score
+
+After all 5 agents return:
+
+1. Deduplicate (same file:line from multiple agents)
+2. Group by severity: BLOCKER → WARNING → INFO
+3. Count totals
+4. Determine verdict:
+   - **READY** — 0 blockers, 0 warnings (or all warnings are cosmetic)
+   - **ALMOST** — 0 blockers, some warnings
+   - **NOT READY** — has blockers
+
+### Step 4: Present Report
+
+Output as direct text (NOT via Bash):
+
+```
+◆ PRODUCTION CHECK — CLIENT HANDOFF AUDIT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Project: {name}
+  Date: {date}
+  Verdict: {READY / ALMOST / NOT READY}
+
+  BLOCKERS: {N}    WARNINGS: {N}    INFO: {N}
+
+── BLOCKERS (must fix before handoff) ────────
+  {If none: "None — no blockers found"}
+
+  1. [{dimension}] {finding}
+     Location: {file:line}
+     Client impact: {what the client/user will experience}
+     Fix: {how to fix}
+
+  2. ...
+
+── WARNINGS (should fix) ────────────────────
+  {findings}
+
+── INFO (nice to have) ──────────────────────
+  {findings}
+
+── DIMENSION SCORES ─────────────────────────
+
+  UX & Frontend     {PASS/ISSUES}  ({N} findings)
+  Auth & Security   {PASS/ISSUES}  ({N} findings)
+  Backend & Data    {PASS/ISSUES}  ({N} findings)
+  Performance & SEO {PASS/ISSUES}  ({N} findings)
+  Completeness      {PASS/ISSUES}  ({N} findings)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 5: Save Report
+
+Write to `.planning/PRODUCTION-CHECK.md`:
+
+```markdown
+---
+date: YYYY-MM-DD HH:MM
+verdict: ready|almost|not_ready
+blockers: N
+warnings: N
+info: N
+dimensions:
+  ux: {pass|issues}
+  security: {pass|issues}
+  backend: {pass|issues}
+  performance: {pass|issues}
+  completeness: {pass|issues}
+---
+
+# Production Check — YYYY-MM-DD
+
+{Full report content}
+```
+
+Commit:
+```bash
+git add .planning/PRODUCTION-CHECK.md && git commit -m "docs: production check ({verdict}, {blockers} blockers)"
+```
+
+### Step 6: Actionable Next Steps
+
+Based on verdict:
+
+**If NOT READY (has blockers):**
+```
+## What's Next?
+
+This project has {N} blockers that clients WILL notice.
+
+1. Fix blockers now — I'll fix them one by one with /qualia-quick
+2. Create a fix milestone — /qualia-new-milestone to plan systematic fixes
+3. See specific blocker — tell me which number to investigate
+```
+
+**If ALMOST (warnings only):**
+```
+## What's Next?
+
+No blockers — the project works. {N} warnings to consider.
+
+1. Fix warnings — I'll handle the quick ones now
+2. Ship as-is — warnings won't break anything for the client
+3. Run /qualia-design — polish the visual design before handoff
+```
+
+**If READY:**
+```
+## What's Next?
+
+✓ Production ready. No blockers, no warnings worth fixing.
+
+1. Ship it — /ship
+2. Run /qualia-design — final visual polish (optional)
+3. Generate handoff docs — project summary for the client
+```
+
+Wait for user to select. Act on their choice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "2.1.0",
+  "version": "2.1.3",
   "description": "Qualia Solutions — Claude Code Framework",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -18,7 +18,12 @@
     "type": "git",
     "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
   },
-  "keywords": ["claude-code", "qualia", "framework", "ai-dev"],
+  "keywords": [
+    "claude-code",
+    "qualia",
+    "framework",
+    "ai-dev"
+  ],
   "author": "Qualia Solutions",
   "license": "UNLICENSED"
 }