qualia-framework 2.5.1 → 3.1.0

package/framework/qualia-framework/references/completion-checklists.md

@@ -1,359 +0,0 @@
-# Qualia Project Completion Checklists
-
-> **Every project must pass ALL items in its checklist before being considered complete.**
-> Copy the relevant checklist into your project's root as `COMPLETION_CHECKLIST.md` and check items off as you go.
-> Manager reviews the checklist before sign-off.
-
----
-
-## Universal Checklist (ALL project types)
-
-### 1. Client & Requirements
-
-- [ ] All features from the project brief are implemented
-- [ ] Client has reviewed and approved the work
-- [ ] No outstanding client feedback unaddressed
-- [ ] Project brief saved in `Knowledge Base/[client]/PROJECT_BRIEF.md`
-
-### 2. Code Quality
-
-- [ ] `npx tsc --noEmit` passes with zero errors
-- [ ] `npm run lint` passes with zero warnings
-- [ ] `npm run build` completes successfully
-- [ ] No `console.log` statements left in production code
-- [ ] No `TODO` or `FIXME` comments left unresolved
-- [ ] No commented-out code blocks
-- [ ] CLAUDE.md is complete and accurate (stack, structure, commands, env vars)
-- [ ] README.md has setup instructions
-
-### 3. Security
-
-- [ ] No API keys or secrets hardcoded in source code
-- [ ] No `.env` files committed to git (`git log --all --full-history -- "*.env*"` returns nothing)
-- [ ] `.env.example` exists with all required variable names (no values)
-- [ ] All environment variables set in deployment platform (Vercel/Cloudflare)
-- [ ] No `eval()` or `dangerouslySetInnerHTML` used
-- [ ] Server-side auth checks on all mutations (never trust client)
-- [ ] CORS configured correctly (not `*` in production)
-
-### 4. Database (if applicable)
-
-- [ ] RLS (Row Level Security) enabled on EVERY table
-- [ ] RLS policies written and tested for each table
-- [ ] No `service_role` key used in client-side code
-- [ ] Supabase client created from `lib/supabase/server.ts` for mutations
-- [ ] TypeScript types generated from database schema
-- [ ] Migrations committed to `supabase/migrations/`
-- [ ] Indexes on frequently queried columns
-
-### 5. Testing
-
-- [ ] Manual testing of all features completed
-- [ ] All forms validate correctly (invalid input rejected, valid input accepted)
-- [ ] Error states tested (network failure, invalid data, unauthorized access)
-- [ ] Mobile responsive tested on real device or DevTools
-- [ ] Cross-browser tested (Chrome + Safari minimum)
-
-### 6. Performance
-
-- [ ] `npm run build` bundle size reasonable (no massive chunks)
-- [ ] Images optimized (WebP/AVIF, proper sizing, lazy loading)
-- [ ] No N+1 database queries
-- [ ] API responses under 500ms for key endpoints
-- [ ] Fonts loaded efficiently (next/font or font-display: swap)
-
-### 7. Deployment
-
-- [ ] Project deployed to production (`vercel --prod` or `wrangler deploy`)
-- [ ] Custom domain configured (if applicable)
-- [ ] SSL certificate active and valid
-- [ ] **HTTP 200** — Homepage loads: `curl -s -o /dev/null -w "%{http_code}" <URL>`
-- [ ] **Auth flow** — Login/signup works end-to-end
-- [ ] **Console clean** — No JavaScript errors in browser DevTools
-- [ ] **Latency** — Key pages load under 3 seconds on mobile
-- [ ] Project added to UptimeRobot monitoring
-
-### 8. Handoff
-
-- [ ] Client walkthrough/demo completed
-- [ ] Client has access to all necessary accounts
-- [ ] Documentation provided (how to use, how to update)
-- [ ] Project registered in Qualia ERP (portal.qualiasolutions.net)
-- [ ] Qualia context file updated (`~/.claude/knowledge/qualia-context.md`)
-
----
-
-## Website-Specific Checklist
-
-> Applies to: Marketing websites, landing pages, portfolio sites
-> Stack: React + Vite + Tailwind OR Next.js
-
-### SEO
-
-- [ ] Page titles set on every page (`<title>` or metadata)
-- [ ] Meta descriptions set on every page (150-160 chars)
-- [ ] Open Graph tags set (og:title, og:description, og:image)
-- [ ] Favicon added (multiple sizes: 16x16, 32x32, apple-touch-icon)
-- [ ] `robots.txt` exists and allows crawling
-- [ ] `sitemap.xml` exists (or auto-generated)
-- [ ] JSON-LD structured data on homepage (Organization or LocalBusiness)
-- [ ] Heading hierarchy correct (single H1 per page, H2s, H3s in order)
-- [ ] All images have `alt` text
-- [ ] No broken links (test all navigation + footer links)
-
-### Responsive Design
-
-- [ ] Mobile (375px): All content readable, no horizontal scroll
-- [ ] Tablet (768px): Layout adjusts properly
-- [ ] Desktop (1280px): Content doesn't stretch beyond max-width
-- [ ] Touch targets minimum 44x44px on mobile
-- [ ] Font sizes readable without zooming on mobile (min 16px body)
-
-### Visual Quality
-
-- [ ] Distinctive fonts loaded (not Inter/Arial/system default)
-- [ ] Brand colors applied consistently
-- [ ] Hover effects on all interactive elements
-- [ ] Animations are smooth (no jank, no layout shift)
-- [ ] Dark mode works (if applicable)
-- [ ] No orphaned text (single words on a line in headings)
-
-### Accessibility
-
-- [ ] Keyboard navigation works (Tab through all interactive elements)
-- [ ] Focus indicators visible on all interactive elements
-- [ ] Color contrast ratio minimum 4.5:1 for body text
-- [ ] Forms have associated labels
-- [ ] Skip-to-content link exists
-
----
-
-## Platform with LLM Checklist
-
-> Applies to: SaaS apps, dashboards, internal tools with AI/LLM integration
-> Stack: Next.js + Supabase + AI SDK (Gemini/OpenAI/Anthropic)
-
-### AI Safety & Prompt Security
-
-- [ ] System prompt NOT exposed to users (not in client bundle, not in API response)
-- [ ] User input sanitized before injection into prompts
-- [ ] No `eval()` or dynamic code execution from AI output
-- [ ] AI output validated/sanitized before rendering (no raw HTML)
-- [ ] Token limits enforced on AI calls (`maxTokens` set)
-- [ ] Rate limiting on AI endpoints (per-user, per-minute)
-- [ ] Cost monitoring configured (track token usage, set alerts)
-
-### AI Functionality
-
-- [ ] AI responses stream correctly (no buffering, smooth display)
-- [ ] Error handling for AI provider failures (timeout, rate limit, quota)
-- [ ] Fallback behavior when AI is unavailable
-- [ ] Conversation context managed properly (not exceeding window)
-- [ ] AI tools/functions validated before execution
-
-### Platform Features
-
-- [ ] Authentication working (login, signup, logout, password reset)
-- [ ] Authorization checked server-side on every mutation
-- [ ] Multi-tenancy isolation (users can only see their own data)
-- [ ] Server Actions return `ActionResult { success, error?, data? }`
-- [ ] Zod validation on all server action inputs
-- [ ] Cache invalidation after mutations
-- [ ] Loading states on all async operations
-- [ ] Error boundaries on all pages
-- [ ] 404 page exists
-
----
-
-## AI Agent Checklist
-
-> Applies to: Chat agents, AI personas, WhatsApp bots, web chatbots
-> Stack: Next.js + AI SDK + Supabase
-
-### AI Configuration
-
-- [ ] System prompt written and tested
-- [ ] AI provider configured (API key server-side only)
-- [ ] Chat endpoint working (`/api/chat` or similar)
-- [ ] Streaming responses working
-- [ ] Temperature and model settings appropriate for use case
-
-### AI Safety (CRITICAL)
-
-- [ ] System prompt not exposed in client-side code
-- [ ] No prompt injection vulnerabilities (test with adversarial inputs)
-- [ ] `service_role` key NOT imported in any client component: `grep -r "service_role" app/ components/ src/`
-- [ ] AI output sanitized before display
-- [ ] Rate limiting on chat endpoint (per-user)
-- [ ] `maxTokens` set on all AI calls
-- [ ] Token budget monitoring in place
-
-### Conversation Quality
-
-- [ ] Agent stays in character / on topic
-- [ ] Graceful handling of off-topic inputs
-- [ ] Clear fallback responses for edge cases ("I can't help with that")
-- [ ] Context window management (conversation doesn't exceed limits)
-- [ ] Conversation history stored (if required)
-
-### Integrations (if applicable)
-
-- [ ] WhatsApp webhook verified and secure
-- [ ] Webhook idempotency (duplicate messages handled)
-- [ ] External API calls have timeout protection
-- [ ] Error handling for third-party API failures
-
-### Monitoring
-
-- [ ] Error tracking configured (Sentry or logging)
-- [ ] Token usage tracked and alerted
-- [ ] Conversation logs stored for debugging
-- [ ] Uptime monitoring active
-
----
-
-## Voice Agent Checklist
-
-> Applies to: Phone bots, voice assistants, IVR systems
-> Stack: VAPI/Retell + Cloudflare Workers/Vercel + Supabase
-
-### Voice Configuration
-
-- [ ] VAPI assistant created and configured
-- [ ] Voice provider selected and tested (Cartesia/ElevenLabs)
-- [ ] STT provider configured (Gladia/Deepgram)
-- [ ] LLM provider configured (Gemini/Claude/OpenAI)
-- [ ] System prompt written for voice (concise, conversational)
-- [ ] First message configured and sounds natural
-- [ ] End-call message configured
-
-### Voice UX
-
-- [ ] Responses are SHORT (1-2 sentences max per turn)
-- [ ] Agent confirms important info back to caller (dates, names, numbers)
-- [ ] Interruption handling works (caller can cut in)
-- [ ] Silence detection and timeout configured
-- [ ] Escape route available ("say 'operator' for a human")
-- [ ] Agent handles "I don't understand" gracefully
-
-### Webhook & Tools
-
-- [ ] Webhook endpoint deployed and accessible
-- [ ] Webhook signature verification implemented (`x-vapi-signature` check)
-- [ ] All tools defined, implemented, and tested
-- [ ] Tool input validation with Zod
-- [ ] Error handling for each tool (graceful degradation)
-- [ ] Call logs stored in database
-
-### Testing
-
-- [ ] Test call from VAPI dashboard successful
-- [ ] Real phone call tested (if phone number configured)
-- [ ] Edge cases tested (invalid dates, unavailable slots, etc.)
-- [ ] Error scenarios tested (tool fails, API timeout)
-- [ ] Multi-language tested (if applicable)
-
-### Performance
-
-- [ ] First response latency under 500ms
-- [ ] Webhook response time under 300ms
-- [ ] No audio gaps or awkward silences during tool execution
-- [ ] Edge function cold start acceptable
-
-### Deployment
-
-- [ ] Cloudflare Worker deployed to production (or Vercel/Supabase)
-- [ ] VAPI assistant updated with production webhook URL
-- [ ] Phone number connected (if applicable)
-- [ ] Webhook secrets set in production environment
-- [ ] Final production test call successful
-
----
-
-## Mobile App Checklist
-
-> Applies to: iOS/Android apps
-> Stack: React Native + Expo + Supabase
-
-### App Basics
-
-- [ ] App icon designed and configured (all required sizes)
-- [ ] Splash screen configured
-- [ ] App name and bundle identifier set
-- [ ] Version number set correctly
-
-### Functionality
-
-- [ ] All screens implemented per requirements
-- [ ] Navigation flows work correctly (forward, back, deep links)
-- [ ] Forms validate correctly with error messages
-- [ ] Pull-to-refresh on list screens
-- [ ] Loading states on all async operations
-- [ ] Empty states on all list screens
-- [ ] Error handling with user-friendly messages
-
-### Mobile-Specific
-
-- [ ] Works on iOS (test on real device or simulator)
-- [ ] Works on Android (test on real device or emulator)
-- [ ] Keyboard handling correct (doesn't cover inputs)
-- [ ] Safe area insets respected (notch, home indicator)
-- [ ] Dark mode supported (if applicable)
-- [ ] Orientation handling (portrait-only or both)
-- [ ] Offline behavior defined (graceful degradation or offline-first)
-
-### Push Notifications (if applicable)
-
-- [ ] FCM configured for Android
-- [ ] APNs configured for iOS
-- [ ] Device token registration working
-- [ ] Test notification received on real device
-- [ ] Notification tap opens correct screen
-
-### Security
-
-- [ ] Sensitive data stored in SecureStore (not AsyncStorage)
-- [ ] API keys not in client bundle
-- [ ] Auth tokens have refresh logic
-- [ ] Certificate pinning (if handling sensitive data)
-
-### Store Submission
-
-- [ ] App Store screenshots prepared (all required sizes)
-- [ ] Play Store screenshots prepared
-- [ ] App description written
-- [ ] Privacy policy URL provided
-- [ ] EAS Build configured and tested
-- [ ] Test build distributed to client for approval
-- [ ] Final build submitted to stores
-
-### i18n & RTL (if applicable)
-
-- [ ] All strings use message keys (no hardcoded text)
-- [ ] Arabic text renders correctly (RTL layout)
-- [ ] Icons flip correctly in RTL mode
-- [ ] Western numerals (0-9) used everywhere (not Eastern Arabic)
-- [ ] Date/time formatting locale-aware
-
----
-
-## How to Use These Checklists
-
-1. **At project start:** Copy the Universal Checklist + your project-type checklist into `COMPLETION_CHECKLIST.md` in your project root
-2. **During development:** Check items off as you complete them
-3. **Before shipping:** All items must be checked. Run `/review` for automated verification
-4. **Manager review:** Fawzi reviews the checklist, signs off or returns with feedback
-5. **After launch:** Keep the checklist in the repo as a record of what was verified
-
-### Severity Guide
-
-If an item can't be checked off, document WHY in the Notes section:
-
-- **Blocker** — Must fix before launch (security, broken features)
-- **Accepted Risk** — Acknowledged by Fawzi, documented, will fix later
-- **N/A** — Doesn't apply to this project (e.g., no database = skip DB section)
-
----
-
-_Last updated: 2026-03-23_
-_Version: 1.0_

package/framework/qualia-framework/references/continuation-format.md

@@ -1,249 +0,0 @@
-# Continuation Format
-
-Standard format for presenting next steps after completing a command or workflow.
-
-## Core Structure
-
-```
----
-
-## ▶ Next Up
-
-**{identifier}: {name}** — {one-line description}
-
-`{command to copy-paste}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `{alternative option 1}` — description
-- `{alternative option 2}` — description
-
----
-```
-
-## Format Rules
-
-1. **Always show what it is** — name + description, never just a command path
-2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
-3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
-4. **`/clear` explanation** — always include, keeps it concise but explains why
-5. **"Also available" not "Other options"** — sounds more app-like
-6. **Visual separators** — `---` above and below to make it stand out
-
-## Variants
-
-### Execute Next Plan
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-
-`/qualia:execute-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review plan before executing
-- `/qualia:list-phase-assumptions 2` — check assumptions
-
----
-```
-
-### Execute Final Plan in Phase
-
-Add note that this is the last plan and what comes after:
-
-```
----
-
-## ▶ Next Up
-
-**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
-<sub>Final plan in Phase 2</sub>
-
-`/qualia:execute-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**After this completes:**
-- Phase 2 → Phase 3 transition
-- Next: **Phase 3: Core Features** — User dashboard and settings
-
----
-```
-
-### Plan a Phase
-
-```
----
-
-## ▶ Next Up
-
-**Phase 2: Authentication** — JWT login flow with refresh tokens
-
-`/qualia:plan-phase 2`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia:discuss-phase 2` — gather context first
-- `/qualia:research-phase 2` — investigate unknowns
-- Review roadmap
-
----
-```
-
-### Phase Complete, Ready for Next
-
-Show completion status before next action:
-
-```
----
-
-## ✓ Phase 2 Complete
-
-3/3 plans executed
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-`/qualia:plan-phase 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia:discuss-phase 3` — gather context first
-- `/qualia:research-phase 3` — investigate unknowns
-- Review what Phase 2 built
-
----
-```
-
-### Multiple Equal Options
-
-When there's no clear primary action:
-
-```
----
-
-## ▶ Next Up
-
-**Phase 3: Core Features** — User dashboard, settings, and data export
-
-**To plan directly:** `/qualia:plan-phase 3`
-
-**To discuss context first:** `/qualia:discuss-phase 3`
-
-**To research unknowns:** `/qualia:research-phase 3`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-### Milestone Complete
-
-```
----
-
-## 🎉 Milestone v1.0 Complete
-
-All 4 phases shipped
-
-## ▶ Next Up
-
-**Start v1.1** — questioning → research → requirements → roadmap
-
-`/qualia:new-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-## Pulling Context
-
-### For phases (from ROADMAP.md):
-
-```markdown
-### Phase 2: Authentication
-**Goal**: JWT login flow with refresh tokens
-```
-
-Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
-
-### For plans (from ROADMAP.md):
-
-```markdown
-Plans:
-- [ ] 02-03: Add refresh token rotation
-```
-
-Or from PLAN.md `<objective>`:
-
-```xml
-<objective>
-Add refresh token rotation with sliding expiry window.
-
-Purpose: Extend session lifetime without compromising security.
-</objective>
-```
-
-Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
-
-## Anti-Patterns
-
-### Don't: Command-only (no context)
-
-```
-## To Continue
-
-Run `/clear`, then paste:
-/qualia:execute-phase 2
-```
-
-User has no idea what 02-03 is about.
-
-### Don't: Missing /clear explanation
-
-```
-`/qualia:plan-phase 3`
-
-Run /clear first.
-```
-
-Doesn't explain why. User might skip it.
-
-### Don't: "Other options" language
-
-```
-Other options:
-- Review roadmap
-```
-
-Sounds like an afterthought. Use "Also available:" instead.
-
-### Don't: Fenced code blocks for commands
-
-```
-```
-/qualia:plan-phase 3
-```
-```
-
-Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/framework/qualia-framework/references/continuation-prompt.md

@@ -1,97 +0,0 @@
-# Checkpoint Continuation Prompt Template
-
-Template for spawning a fresh agent to continue execution after a checkpoint pause.
-
-**Why fresh agent:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
-
-## Template
-
-```markdown
-<objective>
-Continue executing plan {plan_id} from task {resume_task_number}: {resume_task_name}.
-Previous tasks are already committed. Do NOT re-execute them.
-</objective>
-
-<completed_work>
-## Tasks Already Done
-
-{completed_tasks_table}
-
-These tasks have been committed. Verify their commits exist before continuing:
-```bash
-git log --oneline --all --grep="{plan_id}" | head -10
-```
-</completed_work>
-
-<checkpoint_resolution>
-## Checkpoint Resolution
-
-**Checkpoint type:** {checkpoint_type}
-**User response:** {user_response}
-
-{resume_instructions}
-</checkpoint_resolution>
-
-<resume_from>
-## Resume Point
-
-**Task:** {resume_task_number} — {resume_task_name}
-**Plan path:** {plan_path}
-
-Read the full plan for context, but only execute from task {resume_task_number} onward.
-Follow the same execution rules: per-task commits, deviation handling, verification.
-</resume_from>
-
-<context>
-{state_content}
-{config_content}
-</context>
-
-<success_criteria>
-- [ ] Previous commits verified (not re-executed)
-- [ ] Remaining tasks executed from task {resume_task_number}
-- [ ] Each task committed individually
-- [ ] SUMMARY.md created covering ALL tasks (including pre-checkpoint)
-- [ ] STATE.md updated with final position
-</success_criteria>
-```
-
-## Resume Instructions by Checkpoint Type
-
-### checkpoint:human-verify
-```
-The user has verified the previous work.
-- "approved" → Continue to next task normally.
-- Issue description → Fix the reported issue in the current task context before proceeding.
-```
-
-### checkpoint:decision
-```
-The user selected an option for the decision point.
-- Apply the user's choice: {user_response}
-- This may affect how remaining tasks are implemented.
-- Document the decision in SUMMARY.md under "Decisions Made".
-```
-
-### checkpoint:human-action
-```
-The user completed a manual action (e.g., authentication, external config).
-- "done" → Verify the action succeeded (run verification command if specified).
-- If verification fails, inform user and wait for retry.
-- If verification passes, continue to next task.
-```
-
-## Variables
-
-| Variable | Source | Description |
-|----------|--------|-------------|
-| `{plan_id}` | Plan frontmatter | e.g., "03-02" |
-| `{resume_task_number}` | Checkpoint return | Task number to resume from |
-| `{resume_task_name}` | Checkpoint return | Name of the resume task |
-| `{completed_tasks_table}` | Checkpoint return | Markdown table of done tasks with commit hashes |
-| `{checkpoint_type}` | Plan XML | human-verify, decision, or human-action |
-| `{user_response}` | User input | What the user provided at the checkpoint |
-| `{resume_instructions}` | This template | Type-specific instructions from above |
-| `{plan_path}` | Phase directory | Path to the PLAN.md file |
-| `{state_content}` | STATE.md | Inlined project state |
-| `{config_content}` | config.json | Inlined project config |