qualia-framework 3.2.0 → 3.3.0

package/skills/qualia-research/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: qualia-research
+description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+---
+
+# /qualia-research — Per-Phase Deep Research
+
+Runs targeted research on a domain, library, or integration that a specific phase depends on. Distinct from `/qualia-new` research (which covers 4 dimensions project-wide) — this one is narrow and phase-scoped.
+
+## When to Use
+
+- A phase touches a library you've never used
+- A phase integrates with a niche API (FHIR, legal forms, payment gateways)
+- SUMMARY.md marked this phase as a "Research flag"
+- You're about to plan and realize you don't know the current best practice
+
+## Usage
+
+`/qualia-research {N}` — research the current phase or phase N
+
+## Process
+
+### 1. Determine Phase
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Use phase N from args, or current phase from STATE.md.
+
+### 2. Load Context
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/phase-{N}-context.md 2>/dev/null  # if /qualia-discuss was run first
+```
+
+Identify what this phase needs to know.
+
+### 3. Ask the User What to Research
+
+Inline free text:
+
+**"I'm about to research Phase {N}: {phase name}. What specifically do you want me to dig into? Library, domain, integration, pattern?"**
+
+Wait for their answer. Their answer defines the research question.
+
+### 4. Spawn the Researcher
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/qualia-researcher.md
+
+<dimension>phase-specific</dimension>
+
+<question>
+{user's research question}
+</question>
+
+<phase_context>
+Phase: {N}
+Goal: {phase goal from ROADMAP.md}
+Requirements: {REQ-IDs covered by this phase}
+</phase_context>
+
+<project_context>
+{PROJECT.md summary}
+</project_context>
+
+<output_path>
+.planning/phase-{N}-research.md
+</output_path>
+
+Research using Context7 first, then WebFetch, then WebSearch. Be specific and concrete.
+Include: recommendation, rationale, version numbers (if applicable), code examples,
+alternatives considered, what to avoid, sources.
+", subagent_type="qualia-researcher", description="Phase {N} research")
+```
+
+### 5. Review Output
+
+Read `.planning/phase-{N}-research.md`. Present the key findings:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Research complete"
+```
+
+Show:
+- Recommendation
+- Confidence
+- Top 3 key findings
+- Sources used
+
+### 6. User Confirms or Asks More
+
+- header: "Enough?"
+- question: "Is this enough research, or should I dig deeper?"
+- options:
+  - "Enough" — Move to planning
+  - "Dig deeper" — I have more questions
+
+If "Dig deeper" — ask what they want, re-spawn the researcher with additional questions.
+
+### 7. Commit
+
+```bash
+git add .planning/phase-{N}-research.md
+git commit -m "docs(phase-{N}): research findings"
+```
+
+### 8. Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
+```
+
+## Rules
+
+1. **One research session per run.** Don't try to research phases 1 through 5 in one call.
+2. **Must produce a file.** The research is worthless if it only lives in conversation context.
+3. **Honor locked decisions from phase-{N}-context.md.** Don't research alternatives to something already locked.
+4. **Context7 first.** Always try Context7 MCP before WebFetch — it's fastest and most current for known libraries.

package/skills/qualia-review/SKILL.md

@@ -1,76 +1,161 @@
 ---
 name: qualia-review
-description: "Production audit and code review. General review, --web for web app audit, --ai for AI/voice agent audit. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+description: "Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
 ---
 
 # /qualia-review — Production Audit
 
-Deep review with severity-scored findings. Different from `/qualia-verify` (which checks phase goals). This checks production readiness.
+Runs real diagnostic commands and scores every finding. Not a checklist — an executable audit.
 
 ## Usage
 
-- `/qualia-review` — General code review
-- `/qualia-review --web` — Web app production audit
-- `/qualia-review --ai` — AI/voice agent audit
+- `/qualia-review` — Full audit (security + quality + performance)
+- `/qualia-review --web` — Adds web-specific checks (headers, CORS, vitals)
+- `/qualia-review --ai` — Adds AI/voice agent checks (prompt safety, latency)
 
-## General Review (default)
+## Process
 
 ```bash
 node ~/.claude/bin/qualia-ui.js banner review
 ```
 
-Spawn parallel agents analyzing:
+### 0. Load Context
 
-1. **Code Quality** — Clean code, TypeScript strictness, naming, readability
-2. **Security** — OWASP top 10, auth server-side, RLS policies, secrets scan
-3. **Architecture** — Component boundaries, coupling, API contracts
-4. **Performance** — N+1 queries, bundle size, caching, render performance
-5. **Test Coverage** — Gaps, edge cases, test quality
+```bash
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+```
 
-## --web (Web App Audit)
+Detect project shape:
+```bash
+ls package.json next.config.* tsconfig.json supabase/ app/ src/ 2>/dev/null
+```
 
-Full production readiness for Next.js + Supabase + Vercel:
+### 1. Security Scan
 
-**Security:** No secrets in code, HTTPS, CORS restricted, CSP headers, rate limiting, npm audit clean.
+Run every command. Record each finding with severity.
 
-**Performance:** Core Web Vitals (LCP < 2.5s, CLS < 0.1), image optimization, bundle analysis, query performance.
+```bash
+# CRITICAL: service_role in client code
+grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\."
 
-**Reliability:** Error boundaries, API error handling, graceful degradation, health check endpoint.
+# CRITICAL: hardcoded secrets
+grep -rn "sk_live\|sk_test\|SUPABASE_SERVICE_ROLE\|eyJhbGciOi" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.env"
 
-**Observability:** Error tracking (Sentry), structured logging, uptime monitoring, analytics.
+# CRITICAL: dangerous patterns
+grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ 2>/dev/null | grep -v node_modules
 
-## --ai (AI/Voice Agent Audit)
+# CRITICAL: .env files tracked in git
+git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample"
 
-Auto-detect stack (VAPI, ElevenLabs, Retell, OpenAI, Anthropic, pgvector).
+# HIGH: API routes without auth
+for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
+  grep -qL "getUser\|getSession\|auth()\|createClient" "$f" && echo "UNPROTECTED: $f"
+done
 
-**Prompt Safety:** System prompts not exposed, injection defenses, no eval() on AI output, token limits.
+# HIGH: API routes without input validation
+for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
+  grep -L "z\.\|zod\|Zod\|parse\|safeParse" "$f" 2>/dev/null
+done
 
-**Conversation Flow:** Off-topic handling, context window management, error recovery, human handoff.
+# HIGH: client-side database mutations
+grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
 
-**Voice (if detected):** Latency < 500ms, interruption handling, silence timeout, webhook security.
+# MEDIUM: npm vulnerabilities
+npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
+```
 
-**RAG (if detected):** Embedding consistency, chunk size, retrieval relevance, index refresh.
+### 2. Code Quality Scan
 
-**Resilience:** Provider failover, timeout handling, cost monitoring, streaming error recovery.
+```bash
+# TypeScript errors (HIGH if >0)
+npx tsc --noEmit 2>&1 | grep -c "error TS"
 
-## Output
+# 'any' type usage (MEDIUM — count)
+grep -rn ": any\| as any" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | wc -l
 
-Every finding:
-- **What** — description
-- **Where** — `file:line`
-- **Fix** — concrete suggestion
-- **Severity** — CRITICAL / HIGH / MEDIUM / LOW
+# Empty catch blocks (HIGH)
+grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | head -10
 
-Write to `.planning/REVIEW.md`. CRITICAL or HIGH findings are deploy blockers — `/qualia-ship` checks for them.
+# TODO/FIXME left in code (LOW — count)
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | wc -l
 
+# console.log in production code (LOW — count)
+grep -rn "console\.log" --include="*.ts" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v node_modules | wc -l
 ```
-⬢ Review Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Critical:  {N}
-  High:      {N}
-  Medium:    {N}
-  Low:       {N}
-
-  {If blockers: Fix CRITICAL/HIGH before /qualia-ship}
-  {If clean: Ready to ship}
+
+### 3. Performance Scan
+
+```bash
+# Build output — route sizes and first load JS
+npx next build 2>&1 | grep -E "Route|First Load|shared by all|○|●|ƒ|λ" | tail -25
+
+# Heavy files (>300 lines often means split needed)
+find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
+
+# Missing next/image (MEDIUM)
+grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
+
+# Client component ratio
+echo "use client: $(grep -rl "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l)"
+echo "total tsx: $(find app/ components/ src/ -name '*.tsx' 2>/dev/null | wc -l)"
+
+# Sequential data fetching (HIGH)
+grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -10
 ```
+
+### 4. Score and Report
+
+Write to `.planning/REVIEW.md`:
+
+```markdown
+# Production Review — {YYYY-MM-DD}
+
+## Summary
+| Category | Critical | High | Medium | Low | Score |
+|----------|----------|------|--------|-----|-------|
+| Security | {n} | {n} | {n} | {n} | {1-5} |
+| Quality  | {n} | {n} | {n} | {n} | {1-5} |
+| Perf     | {n} | {n} | {n} | {n} | {1-5} |
+| **Total** | {n} | {n} | {n} | {n} | **{avg}/5** |
+
+## Findings
+
+### CRITICAL
+- **{title}** — `{file}:{line}` — {what's wrong} — Fix: {how}
+
+### HIGH
+- ...
+
+### MEDIUM
+- ...
+
+### LOW
+- ...
+
+## Verdict
+{PASS: no critical/high | FAIL: N blockers — fix before /qualia-ship}
+```
+
+**Scoring:**
+- 5 = zero high/critical, fewer than 3 medium
+- 4 = zero critical, 1 high or fewer than 5 medium
+- 3 = zero critical, 2-3 high
+- 2 = 1 critical or 4+ high
+- 1 = multiple critical
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Security: {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js info "Quality:  {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js info "Perf:     {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js end "REVIEW: {PASS|FAIL}" "{next command}"
+```
+
+## Rules
+
+1. **Run every command.** Don't skip scans because "the code looks clean."
+2. **Every finding gets a severity.** No prose — CRITICAL/HIGH/MEDIUM/LOW.
+3. **Every finding gets a fix suggestion.** Not just "this is bad" — say what to do.
+4. **Review detects. It does NOT fix.** This is an audit, not a refactor. Tell the user what to fix.
+5. **CRITICAL or HIGH = deploy blocker.** `/qualia-ship` checks for these.

package/skills/qualia-test/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: qualia-test
+description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+---
+
+# /qualia-test — Test Generator
+
+Generate tests for client project code. Detect framework, classify targets, write tests, run them.
+
+## Usage
+
+- `/qualia-test` — Generate tests for recently changed files
+- `/qualia-test {file}` — Generate tests for a specific file
+- `/qualia-test --run` — Run existing tests and report
+- `/qualia-test --coverage` — Run with coverage report
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner test
+```
+
+### 1. Detect Test Framework
+
+```bash
+node -e "
+const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));
+const d={...p.dependencies,...p.devDependencies};
+console.log(JSON.stringify({
+  vitest: !!d.vitest,
+  jest: !!d.jest,
+  playwright: !!d['@playwright/test'],
+  testing_library: !!d['@testing-library/react']
+}))
+"
+```
+
+If no test framework found, install vitest (lighter than jest for Next.js/Vite):
+
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
+```
+
+Add to `vitest.config.ts` if it doesn't exist:
+```typescript
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+  },
+})
+```
+
+### 2. Find Targets
+
+If specific file given → use that.
+If `--run` → skip to step 4.
+Otherwise find recently changed untested files:
+
+```bash
+# Files changed in last 5 commits that don't have tests
+git diff --name-only HEAD~5 --diff-filter=AM -- '*.ts' '*.tsx' 2>/dev/null | grep -v "test\|spec\|__test__\|\.d\.ts" | head -10
+```
+
+### 3. Generate Tests
+
+For each target file, classify it and generate the appropriate test:
+
+**API route** (`app/api/**/route.ts`):
+- Test each exported handler (GET, POST, PUT, DELETE)
+- Test with valid input → expected response
+- Test with invalid input → 400 error
+- Test without auth → 401 (if auth is required)
+
+**Server action** (has `"use server"`):
+- Test each exported function
+- Test with valid args → expected result
+- Test with invalid args → error handling
+
+**React component** (`*.tsx` with JSX):
+- Test rendering without crashing
+- Test interactive elements (clicks, form submissions)
+- Test loading, error, and empty states if they exist
+- Test accessibility (role, aria-label presence)
+
+**Utility function** (`lib/*.ts`, `utils/*.ts`):
+- Test each exported function with normal input
+- Test edge cases: empty, null, undefined, boundary values
+- Test error cases: invalid input, missing data
+
+Write test file next to the source: `{file}.test.ts` or `{file}.test.tsx`.
+
+### 4. Run Tests
+
+```bash
+# Vitest
+npx vitest run --reporter=verbose 2>&1 | tail -30
+
+# Or Jest
+npx jest --verbose 2>&1 | tail -30
+
+# Coverage (if --coverage flag)
+npx vitest run --coverage 2>&1 | tail -30
+```
+
+### 5. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
+node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
+node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
+```
+
+If any tests fail, show the failures and offer to fix them.
+
+### 6. Commit
+
+```bash
+git add {test files}
+git commit -m "test: add tests for {files}"
+```
+
+## Rules
+
+1. **Test behavior, not implementation.** Don't test internal state — test what the user/caller sees.
+2. **No snapshot tests.** They're brittle and meaningless.
+3. **No mocking unless necessary.** Test real behavior. Mock only external services (APIs, databases).
+4. **Each test file is self-contained.** No shared mutable state between tests.
+5. **Name tests as sentences.** `it("returns 401 when user is not authenticated")` not `it("test auth")`.

package/skills/qualia-verify/SKILL.md

@@ -33,7 +33,7 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 Agent(prompt="
 Read your role: @agents/verifier.md
 
-Phase plan with success criteria:
+Phase plan with success criteria AND verification contracts:
 @.planning/phase-{N}-plan.md
 
 {If re-verification: Previous verification with gaps:}