qualia-framework 3.2.0 → 3.3.0

package/templates/projects/voice-agent.md

@@ -0,0 +1,55 @@
+# Project Template: Voice Agent
+
+Typical phase structure for a phone agent, VAPI bot, Retell agent, or call handling system.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Next.js 16 + Supabase + Retell AI / ElevenLabs / VAPI + Telnyx (phone numbers) + Vercel
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Webhook endpoint for voice provider, Supabase wired, base call logging working.
+
+**Typical success criteria:**
+1. Webhook endpoint deployed and reachable
+2. Supabase schema for `calls`, `transcripts`, `contacts` exists
+3. Provider credentials configured (`RETELL_API_KEY`, `ELEVENLABS_API_KEY`, `TELNYX_API_KEY`)
+
+### Phase 2: Agent Configuration
+
+**Goal:** Voice agent answers calls with correct prompt and voice.
+
+**Requirements covered:** Provider agent setup, system prompt, voice selection, greeting.
+
+### Phase 3: Call Flow
+
+**Goal:** Agent handles conversation, captures data, transfers when needed.
+
+**Requirements covered:** Conversation state, data capture (name, email, appointment), transfer to human.
+
+### Phase 4: Integrations
+
+**Goal:** Post-call actions fire — CRM sync, Slack notification, email confirmation.
+
+**Requirements covered:** CRM webhook, Slack bot, transactional email.
+
+### Phase 5: Polish & Monitoring
+
+**Goal:** Low latency, graceful errors, call quality monitoring, cost tracking.
+
+**Requirements covered:** Latency optimization, silent call recovery, cost per call tracking, dashboard.
+
+## Common Requirements Categories
+
+- **CALL** — call handling and routing
+- **CONV** — conversation flow
+- **INTG** — external integrations (CRM, Slack, email)
+- **MON** — monitoring and cost tracking
+- **PROV** — voice provider configuration
+
+## Research Flags
+
+- **Provider choice** (Retell vs VAPI vs ElevenLabs direct) → `/qualia-research 1` to compare for this specific use case
+- **Telephony setup** (DIDs, porting, SIP) → `/qualia-discuss` to lock decisions before wiring
+- **Prompt engineering for voice** → `/qualia-research` for the agent config phase

package/templates/projects/website.md

@@ -0,0 +1,58 @@
+# Project Template: Website / Web App
+
+Typical phase structure for a client website, SaaS landing page, dashboard, or marketing site.
+
+**Default depth:** `standard` (5-8 phases)
+**Typical stack:** Next.js 16 + React 19 + TypeScript + Supabase + Vercel
+
+## Typical Phases
+
+### Phase 1: Foundation
+
+**Goal:** Project skeleton exists on Vercel with Supabase wired, auth working, and base layout rendering.
+
+**Requirements covered:** Auth (sign up / log in / log out / session persistence), base layout, deploy pipeline.
+
+**Typical success criteria:**
+1. Site loads on Vercel preview URL
+2. User can sign up with email + password
+3. User can log in and stay logged in across refresh
+4. Base layout renders with nav + footer
+
+### Phase 2: Core Feature (primary)
+
+**Goal:** The main value-delivering feature works end-to-end.
+
+**Requirements covered:** Primary user capability (depends on project — posting, booking, searching, etc.)
+
+### Phase 3: Core Feature (secondary)
+
+**Goal:** Supporting features that make the primary feature usable.
+
+**Requirements covered:** Profile, settings, admin panel, etc.
+
+### Phase 4: Content & Marketing
+
+**Goal:** Marketing pages, copy, images, SEO meta tags.
+
+**Requirements covered:** Homepage hero, features section, pricing, about, contact.
+
+### Phase 5: Polish & Launch
+
+**Goal:** Site is production-ready.
+
+**Requirements covered:** Responsive (mobile / tablet / desktop), animations, error states, empty states, a11y, SEO, analytics.
+
+## Common Requirements Categories
+
+- **AUTH** — authentication and sessions
+- **PROF** — user profiles
+- **CONT** — content / primary feature
+- **ADMIN** — admin panel
+- **MARK** — marketing pages
+- **SEO** — SEO, sitemaps, analytics
+
+## Research Flags
+
+- **Niche domain integrations** (e.g., legal compliance, medical records, financial regulations) → run `/qualia-research N` before planning that phase
+- **Complex auth** (SSO, multi-tenant, RBAC) → run `/qualia-discuss N` first

package/templates/requirements.md

@@ -0,0 +1,69 @@
+# Requirements: {Project Name}
+
+**Defined:** {date}
+**Core Value:** {from PROJECT.md — the one thing that must work}
+
+## v1 Requirements
+
+Initial release scope. Each maps to one roadmap phase.
+
+### {Category 1}
+
+- [ ] **{CAT}-01**: {user-centric, testable, atomic capability}
+- [ ] **{CAT}-02**: {capability}
+- [ ] **{CAT}-03**: {capability}
+
+### {Category 2}
+
+- [ ] **{CAT}-01**: {capability}
+- [ ] **{CAT}-02**: {capability}
+
+## v2 Requirements
+
+Acknowledged but deferred to a future release. Not in current roadmap.
+
+### {Category}
+
+- **{CAT}-01**: {capability}
+- **{CAT}-02**: {capability}
+
+## Out of Scope
+
+Explicit exclusions with reasoning. Prevents scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| {feature} | {why excluded} |
+
+## Traceability
+
+Which phases cover which requirements. Populated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| {CAT}-01 | Phase {N} | Pending |
+
+**Coverage:**
+- v1 requirements: {X} total
+- Mapped to phases: {Y}
+- Unmapped: {Z}
+
+---
+
+## Requirement Quality Rules
+
+1. **ID format:** `{CATEGORY}-{NUMBER}` — `AUTH-01`, `CONT-02`, `SOCIAL-03`
+2. **User-centric:** "User can X" — not "System does Y"
+3. **Atomic:** One capability per requirement — not "User can login and manage profile"
+4. **Testable:** "User can reset password via email link" — not "handle password reset"
+5. **Independent:** Minimal dependencies on other requirements
+
+## Status Values
+
+- **Pending** — not started
+- **In Progress** — phase is active
+- **Complete** — requirement verified
+- **Blocked** — waiting on external factor
+
+---
+*Last updated: {date}*

package/templates/research-project/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Standard Architecture
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| {name} | {what it owns} | {how it's usually built} |
+
+### Data Flow
+
+```
+[User Action]
+    ↓
+[Component] → [Handler] → [Service] → [Data Store]
+    ↓              ↓           ↓            ↓
+[Response] ← [Transform] ← [Query] ← [Database]
+```
+
+### Key Flows
+
+1. **{flow name}:** {how data moves}
+2. **{flow name}:** {how data moves}
+
+## Recommended Project Structure
+
+```
+src/
+├── {folder}/           # {purpose}
+├── {folder}/           # {purpose}
+└── {folder}/           # {purpose}
+```
+
+**Structure rationale:**
+- **{folder}/:** {why organized this way}
+
+## Suggested Build Order
+
+Phases should follow this dependency order:
+
+1. **{component}** — foundation, no dependencies
+2. **{component}** — depends on 1
+3. **{component}** — depends on 1, 2
+
+## Anti-Patterns
+
+### {Name}
+
+**What people do:** {the mistake}
+**Why it's wrong:** {the problem}
+**Do this instead:** {correct approach}
+
+## Integration Points
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| {service} | {how to connect} | {gotchas} |
+
+## Sources
+
+- {architecture references}
+- {official documentation}
+
+---
+*Architecture research for: {domain}*

package/templates/research-project/FEATURES.md

@@ -0,0 +1,60 @@
+# Feature Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features users assume exist. Missing these = product feels incomplete.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| {feature} | {user expectation} | LOW/MEDIUM/HIGH | {implementation notes} |
+
+### Differentiators (Competitive Advantage)
+
+Features that set the product apart. Not required, but valuable.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| {feature} | {why it matters} | LOW/MEDIUM/HIGH | {notes} |
+
+### Anti-Features (Seem Good, Aren't)
+
+Features that seem good but create problems — often requested, rarely right.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| {feature} | {surface appeal} | {actual problems} | {better approach} |
+
+## MVP Recommendation
+
+### Launch With (v1)
+
+- {feature} — {why essential}
+- {feature} — {why essential}
+
+### Add After Validation (v1.x)
+
+- {feature} — {trigger}
+
+### Defer (v2+)
+
+- {feature} — {why defer}
+
+## Feature Dependencies
+
+- **{Feature A}** requires **{Feature B}** — {why}
+- **{Feature C}** enhances **{Feature A}** — {how}
+
+## Sources
+
+- {competitor products analyzed}
+- {user research referenced}
+- {industry standards}
+
+---
+*Feature research for: {domain}*

package/templates/research-project/PITFALLS.md

@@ -0,0 +1,73 @@
+# Pitfalls Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Critical Pitfalls
+
+### {Pitfall Name}
+
+**What goes wrong:** {the failure mode}
+**Why it happens:** {root cause}
+**How to avoid:** {specific prevention strategy}
+**Warning signs:** {how to detect early}
+**Phase to address:** Phase {N}
+
+---
+
+### {Pitfall Name}
+
+**What goes wrong:** {failure mode}
+**Why it happens:** {root cause}
+**How to avoid:** {prevention}
+**Warning signs:** {detection}
+**Phase to address:** Phase {N}
+
+---
+
+## Technical Debt Patterns
+
+Shortcuts that seem reasonable but create long-term problems.
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| {shortcut} | {benefit} | {cost} | {conditions, or "never"} |
+
+## Performance Traps
+
+Patterns that work at small scale but fail as usage grows.
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| {trap} | {how you notice} | {how to avoid} | {scale threshold} |
+
+## Security Mistakes
+
+Domain-specific security issues beyond general web security.
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| {mistake} | {what could happen} | {how to avoid} |
+
+## "Looks Done But Isn't" Checklist
+
+Things that appear complete but are missing critical pieces.
+
+- [ ] **{Feature}:** Often missing {thing} — verify {check}
+- [ ] **{Feature}:** Often missing {thing} — verify {check}
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| {pitfall} | Phase {X} | {how to verify prevention} |
+
+## Sources
+
+- {post-mortems referenced}
+- {community discussions}
+- {official "gotchas" documentation}
+
+---
+*Pitfalls research for: {domain}*

package/templates/research-project/STACK.md

@@ -0,0 +1,51 @@
+# Stack Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| {name} | {version} | {what it does} | {why experts use it for this domain} |
+| {name} | {version} | {what it does} | {why} |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| {name} | {version} | {what it does} | {specific use case} |
+
+## Installation
+
+```bash
+npm install {core packages}
+npm install -D {dev dependencies}
+```
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| {our choice} | {other option} | {conditions} |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| {technology} | {specific problem} | {recommended alternative} |
+
+## Version Compatibility
+
+Known compatibility constraints between the recommended packages.
+
+## Sources
+
+- {Context7 library ID} — {topics fetched}
+- {Official docs URL} — {what was verified}
+
+---
+*Stack research for: {domain}*

package/templates/research-project/SUMMARY.md

@@ -0,0 +1,86 @@
+# Research Summary
+
+**Project:** {name}
+**Domain:** {inferred domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Executive Summary
+
+{2-3 paragraph overview — what type of product this is, recommended approach, key risks}
+
+## Key Findings
+
+### Recommended Stack
+
+**Core:**
+- {tech}: {purpose} — {why}
+- {tech}: {purpose} — {why}
+
+### Table Stakes Features
+
+- {feature} — users expect this
+- {feature} — users expect this
+
+### Differentiators
+
+- {feature}
+- {feature}
+
+### Critical Pitfalls
+
+1. **{pitfall}** — {how to avoid}
+2. **{pitfall}** — {how to avoid}
+3. **{pitfall}** — {how to avoid}
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+### Phase 1: {Name}
+**Rationale:** {why this comes first}
+**Delivers:** {what this phase produces}
+**Addresses:** {features from FEATURES.md}
+**Avoids:** {pitfall from PITFALLS.md}
+
+### Phase 2: {Name}
+**Rationale:** {why this order}
+**Delivers:** {what this phase produces}
+
+### Phase Ordering Rationale
+
+- {why this order based on dependencies}
+- {why this grouping based on architecture patterns}
+
+### Research Flags
+
+Phases likely needing deeper research during `/qualia-plan`:
+- **Phase {X}:** {reason}
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | {HIGH/MEDIUM/LOW} | {reason} |
+| Features | {HIGH/MEDIUM/LOW} | {reason} |
+| Architecture | {HIGH/MEDIUM/LOW} | {reason} |
+| Pitfalls | {HIGH/MEDIUM/LOW} | {reason} |
+
+**Overall confidence:** {HIGH/MEDIUM/LOW}
+
+### Gaps to Address
+
+{Areas where research was inconclusive — handle during planning}
+
+- {gap}: {handling}
+
+## Sources
+
+**Primary (HIGH confidence):**
+- {Context7 library ID} — {topics}
+
+**Secondary (MEDIUM confidence):**
+- {source} — {finding}
+
+---
+*Ready for roadmap: yes*

package/templates/roadmap.md

@@ -0,0 +1,71 @@
+# Roadmap: {Project Name}
+
+**Created:** {date}
+**Total phases:** {N}
+**v1 requirements:** {X} covered
+
+## Phases
+
+| # | Phase | Goal | Requirements | Status |
+|---|-------|------|--------------|--------|
+| 1 | {name} | {one-sentence goal} | {REQ-IDs} | ready |
+| 2 | {name} | {goal} | {REQ-IDs} | — |
+| 3 | {name} | {goal} | {REQ-IDs} | — |
+
+## Phase Details
+
+### Phase 1: {Name}
+
+**Goal:** {what must be TRUE when this phase is done}
+
+**Requirements covered:**
+- {REQ-ID}: {description}
+- {REQ-ID}: {description}
+
+**Success criteria** (observable user behaviors):
+1. {user can do X}
+2. {user can do Y}
+3. {user can do Z}
+
+**Depends on:** none (or: Phase {N})
+
+---
+
+### Phase 2: {Name}
+
+**Goal:** {goal}
+
+**Requirements covered:**
+- {REQ-ID}: {description}
+
+**Success criteria:**
+1. {criterion}
+2. {criterion}
+
+**Depends on:** Phase 1
+
+---
+
+{... continue for all phases ...}
+
+## Coverage Verification
+
+All v1 requirements must map to exactly one phase. Unmapped requirements = roadmap gap.
+
+| Requirement | Phase | Covered? |
+|-------------|-------|----------|
+| {REQ-ID} | Phase {N} | ✓ |
+
+**Coverage:** {X}/{Y} v1 requirements mapped ({100% expected})
+
+---
+
+## Rules
+
+1. **Feature phases only.** No "review" / "deploy" / "handoff" phases — those are driven by `/qualia-polish` → `/qualia-ship` → `/qualia-handoff` after all feature phases verify.
+2. **Each requirement maps to exactly one phase.** If a requirement spans phases, it's too big — split it.
+3. **Phases are independently verifiable.** A phase completes when its success criteria are observable in a running app.
+4. **Order by dependency, not priority.** Phase 2 should depend on Phase 1's outputs.
+
+---
+*Last updated: {date}*

package/tests/bin.test.sh

@@ -139,7 +139,7 @@ cat > "$TMP/.claude/.qualia-config.json" <<'EOF'
   "code": "QS-FAWZI-01",
   "installed_by": "Fawzi Goussous",
   "role": "OWNER",
-  "version": "3.1.0",
+  "version": "2.8.1",
   "installed_at": "2026-04-10"
 }
 EOF
@@ -423,7 +423,7 @@ cat > "$TMP/.claude/.qualia-config.json" <<'EOF'
   "code": "QS-FAWZI-01",
   "installed_by": "Fawzi Goussous",
   "role": "OWNER",
-  "version": "3.1.0",
+  "version": "2.8.1",
   "installed_at": "2026-04-10"
 }
 EOF
@@ -476,10 +476,10 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 7 hooks installed (block-env-edit.js retired in v3.2.0)
+# 31. All 8 hooks installed
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 7 ]; then
-  pass "7 hooks installed in hooks/"
+if [ "$HOOK_COUNT" -eq 8 ]; then
+  pass "8 hooks installed in hooks/"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi
@@ -494,7 +494,21 @@ else
   fail_case "settings.json contents"
 fi
 
-# 33. Lowercase code works (resolveTeamCode normalizes)
+# 33. settings.json contains all 8 hooks wired correctly
+if grep -q 'block-env-edit.js' "$TMP/.claude/settings.json" \
+   && grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'migration-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-push.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-deploy-gate.js' "$TMP/.claude/settings.json" \
+   && grep -q 'auto-update.js' "$TMP/.claude/settings.json" \
+   && grep -q 'session-start.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 8 hooks wired"
+else
+  fail_case "settings.json missing hooks"
+fi
+
+# 34. Lowercase code works (resolveTeamCode normalizes)
 TMP=$(mktmp)
 echo "qs-fawzi-01" | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/out.log" 2>&1
 EXIT=$?