qualia-framework 3.2.0 → 3.2.1

package/CLAUDE.md

@@ -4,7 +4,7 @@
 Qualia Solutions — Nicosia, Cyprus. Websites, AI agents, voice agents, AI automation.
 
 ## Stack
-Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: VAPI, ElevenLabs, Telnyx, Retell AI. AI: OpenRouter.
+Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLabs, Telnyx. AI: OpenRouter. Compute: Railway (agents/background jobs). See `rules/infrastructure.md` for full details.
 
 ## Role: {{ROLE}}
 {{ROLE_DESCRIPTION}}
@@ -19,6 +19,7 @@ Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: VAPI, ElevenLabs, Te
 - See `rules/security.md` for auth, RLS, Zod, secrets
 - See `rules/frontend.md` for design standards
 - See `rules/deployment.md` for deploy checklist
+- See `rules/infrastructure.md` for services, APIs, GitHub orgs, Vercel teams
 
 ## The Road (how projects flow)
 
@@ -51,9 +52,7 @@ No accumulated garbage. No context rot.
 ## Quality Gates (always active)
 - **Frontend guard:** Read .planning/DESIGN.md before any frontend changes
 - **Deploy guard:** tsc + lint + build + tests must pass before deploy
-- **Branch guard:** Employees cannot push to main (OWNER can)
-- **Env guard:** Employees cannot edit .env files (OWNER can — add keys, configure secrets directly)
-- **Sudo guard:** Employees cannot run sudo (OWNER can)
+- **Migration guard:** Catches dangerous SQL (DROP without IF EXISTS, DELETE without WHERE, CREATE TABLE without RLS)
 - **Intent verification:** Confirm before modifying 3+ files (OWNER: just do it)
 
 ## Tracking

package/README.md

@@ -1,9 +1,11 @@
 # Qualia Framework v3
 
-A prompt orchestration framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
+A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
 It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects.
 
+v3 applies lessons from Anthropic's ["Harness Design for Long-Running Apps"](https://www.anthropic.com/engineering/harness-design-long-running-apps) article: scored evaluator rubrics, verification contracts, smarter guards, hook telemetry, and dynamic team management.
+
 ## Install
 
 ```bash
@@ -17,6 +19,9 @@ Enter your team code when prompted. Get your code from Fawzi.
 npx qualia-framework version    # Check installed version + updates
 npx qualia-framework update     # Update to latest (remembers your code)
 npx qualia-framework uninstall  # Clean removal from ~/.claude/
+npx qualia-framework team list  # Show team members
+npx qualia-framework team add   # Add a team member
+npx qualia-framework traces     # View recent hook telemetry
 ```
 
 ## Usage
@@ -66,7 +71,7 @@ Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Co
 
 ### Goal-Backward Verification
 
-Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. When Claude says "I built the chat component," this catches the cases where it wrote a skeleton with `// TODO` inside.
+Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier scores on 4 dimensions (Correctness, Completeness, Wiring, Quality), each 1-5, with a hard threshold at 3. It doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. The planner generates verification contracts (testable commands) that the verifier executes before ad-hoc checks.
 
 ### Agent Separation
 
@@ -84,7 +89,7 @@ All 8 hooks are real ops engineering, not theoretical. Highlights:
 
 ### Enforced State Machine
 
-Every workflow step calls `state.js` — a Node.js state machine that validates preconditions, updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. You can't build without planning, can't verify without building, and can't loop on gap-closure more than twice before escalating.
+Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. The gap-closure limit is configurable per project (default: 2). A `--force` flag enables recovery after failed builds.
 
 ### Wave-Based Parallelization
 
@@ -106,10 +111,10 @@ npx qualia-framework install
   ├── hooks/           8 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/             state.js (state machine) + qualia-ui.js (cosmetics library)
   ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (loaded by plan/debug/new)
-  ├── rules/           security.md, frontend.md, deployment.md
+  ├── rules/           security.md, frontend.md, design-reference.md, deployment.md
   ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
   ├── CLAUDE.md        global instructions (role-configured per team member)
-  └── statusline.sh    teal-branded 2-line status bar
+  └── statusline.js    teal-branded 2-line status bar
 ```
 
 ## For Qualia Solutions Team

package/agents/planner.md

@@ -91,6 +91,58 @@ Your training data is often stale. A two-second lookup is cheaper than a wrong t
 
 **Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
 
+## Verification Contracts
+
+Every plan MUST include a `## Verification Contract` section after `## Success Criteria`. Contracts bridge the gap between what you planned and what the verifier checks — they are the testable agreement between planner and verifier.
+
+### Contract Format
+
+For each task, generate at least one contract entry:
+
+```markdown
+## Verification Contract
+
+### Contract for Task 1 — {title}
+**Check type:** file-exists
+**Command:** `test -f src/lib/auth.ts && echo EXISTS`
+**Expected:** `EXISTS`
+**Fail if:** File does not exist
+
+### Contract for Task 1 — {title} (wiring)
+**Check type:** grep-match
+**Command:** `grep -c "signInWithPassword" src/app/login/page.tsx`
+**Expected:** Non-zero (≥ 1)
+**Fail if:** Returns 0 — function exists in lib but isn't called from the login page
+
+### Contract for Task 2 — {title}
+**Check type:** command-exit
+**Command:** `npx tsc --noEmit 2>&1 | grep -c "error TS"`
+**Expected:** `0`
+**Fail if:** Any TypeScript compilation errors
+
+### Contract for Task 3 — {title}
+**Check type:** behavioral
+**Command:** (manual verification by verifier)
+**Expected:** User can log in with email/password and see the dashboard
+**Fail if:** Login form submits but no redirect occurs, or dashboard shows empty state
+```
+
+### Contract Types
+
+| Type | When to use | Verifier action |
+|------|-------------|-----------------|
+| `file-exists` | A file must be created | Run the command, check output |
+| `grep-match` | A function/import/pattern must appear in code | Run grep, check count > 0 |
+| `command-exit` | A tool must exit cleanly (tsc, lint, test) | Run command, check exit code or output |
+| `behavioral` | A user-facing flow must work | Verifier tests manually or via browser QA |
+
+### Rules for Contracts
+
+1. **Every task gets at least one contract.** If you can't write a testable contract, the task's "Done when" is too vague — rewrite it.
+2. **Contracts must be copy-pasteable.** The verifier runs them verbatim. No placeholders, no `{variable}` — use actual file paths.
+3. **Include wiring contracts.** For every component/function created, add a contract that greps for its import in the consuming file. This catches the #1 failure mode: code that exists but isn't connected.
+4. **Behavioral contracts are last resort.** Prefer grep-match and command-exit — they're deterministic. Use behavioral only for user-facing flows that can't be verified by grep.
+
 ## Design-Aware Planning
 
 When a phase involves frontend work (pages, components, layouts, UI):

package/agents/verifier.md

@@ -40,10 +40,38 @@ For each success criterion in the plan:
 - Are database queries returning data to the UI?
 - This is where stubs hide.
 
+## Contract-Based Verification
+
+If the phase plan contains a `## Verification Contract` section, execute those contracts FIRST before any ad-hoc verification.
+
+### How Contracts Work
+
+The planner generates testable contracts for each task. Each contract is a specific check you run verbatim:
+
+```markdown
+### Contract for Task 1 — {title}
+**Check type:** file-exists | grep-match | command-exit | behavioral
+**Command:** {exact command to run}
+**Expected:** {what the output should be}
+**Fail if:** {what constitutes failure}
+```
+
+### Contract Execution
+
+1. Read the `## Verification Contract` section from the plan file
+2. For each contract entry, run the **Command** exactly as written
+3. Compare output against **Expected**
+4. Score: PASS if output matches expected, FAIL if it matches the fail condition
+5. Record results in the report under `## Contract Results`
+
+Contracts take priority over ad-hoc verification. If a contract covers a success criterion, use the contract result. Only fall back to the 3-level check (Truths → Artifacts → Wiring) for criteria NOT covered by contracts.
+
+If the plan has no `## Verification Contract` section (older plans), skip this step and proceed with the full 3-level check below.
+
 ## How to Verify
 
 ### 1. Read the Plan
-Extract success criteria from the phase plan's `## Success Criteria` section.
+Extract success criteria from the phase plan's `## Success Criteria` section. Also extract the `## Verification Contract` if present.
 
 ### 2. For Each Criterion, Run the 3-Level Check
 
@@ -111,12 +139,21 @@ gaps: {count of failures}
 
 # Phase {N} Verification
 
-## Results
+## Contract Results (if contracts exist in plan)
+
+| Task | Check | Command | Result | Notes |
+|------|-------|---------|--------|-------|
+| Task 1 | file-exists | `test -f src/lib/auth.ts` | PASS | File exists, 142 lines |
+| Task 2 | grep-match | `grep -c "signIn" src/lib/auth.ts` | PASS | 3 matches |
+
+## Scores
 
-| Criterion | Status | Evidence |
-|-----------|--------|----------|
-| {criterion 1} | PASS | {what you found} |
-| {criterion 2} | FAIL | {what's wrong} |
+| Criterion | Correctness | Completeness | Wiring | Quality | Verdict |
+|-----------|-------------|--------------|--------|---------|---------|
+| {criterion 1} | {1-5} | {1-5} | {1-5} | {1-5} | PASS/FAIL |
+| {criterion 2} | {1-5} | {1-5} | {1-5} | {1-5} | PASS/FAIL |
+
+**Minimum threshold check:** {any score < 3? If YES → FAIL}
 
 ## Code Quality
 - TypeScript: PASS/FAIL
@@ -125,35 +162,107 @@ gaps: {count of failures}
 - Unused imports: {count}
 
 ## Gaps (if any)
-1. {what failed and why}
-2. {what failed and why}
+1. {criterion}: {dimension} scored {score} — {what's wrong, what file, what's needed}
+2. {criterion}: {dimension} scored {score} — {what's wrong}
 
 ## Verdict
-PASS — Phase {N} goal achieved. Proceed to Phase {N+1}.
+PASS — Phase {N} goal achieved. All criteria scored ≥ 3 on all dimensions. Proceed to Phase {N+1}.
 OR
-FAIL — {N} gaps found. Run `/qualia-plan {N} --gaps` to fix.
+FAIL — {N} gaps found. {N} criteria scored below threshold. Run `/qualia-plan {N} --gaps` to fix.
 ```
 
-## Scoring
+## Scoring Rubric
+
+Every success criterion is scored on 4 dimensions, each rated 1-5:
+
+### Correctness (1-5)
+Does it produce the right output?
+- **1** — Crashes, errors, or wrong output
+- **2** — Works for the happy path only; any deviation breaks it
+- **3** — Handles common edge cases (empty input, missing data, basic validation)
+- **4** — Handles most edge cases; error messages are user-friendly
+- **5** — Comprehensive error handling; graceful degradation; defensive coding
+
+### Completeness (1-5)
+Were all contracted requirements met?
+- **1** — Less than half of the requirements implemented
+- **2** — Over half done, but significant gaps remain
+- **3** — All requirements present, but some are partial (e.g., UI exists but missing states)
+- **4** — All requirements fully implemented as specified
+- **5** — All requirements plus defensive coding, edge case coverage, and polish
+
+### Wiring (1-5)
+Is everything connected end-to-end?
+- **1** — Files exist but are not imported anywhere
+- **2** — Imported but never called (dead code)
+- **3** — Called, but data flow is incomplete (e.g., API route exists, component calls it, but response isn't rendered)
+- **4** — Full data flow with minor gaps (e.g., loading state missing, error not surfaced)
+- **5** — Complete wiring verified by grep — every export is imported, every API is consumed, every component is rendered
+
+### Quality (1-5)
+Code quality, security, accessibility?
+- **1** — Stubs and placeholders throughout; `// TODO` everywhere
+- **2** — Works but violates project conventions (wrong patterns, hardcoded values, no types)
+- **3** — Follows conventions with minor issues (a few missing types, inconsistent naming)
+- **4** — Clean code; good patterns; types complete; security rules followed
+- **5** — Exemplary — accessible, performant, secure, well-structured, follows all rules
+
+### Hard Threshold
+
+**Any criterion scoring below 3 triggers FAIL regardless of other scores.**
+
+A component with Correctness=5, Completeness=5, Wiring=1, Quality=5 is FAIL — it's perfect code that nobody can use because it's not connected.
+
+### Phase Verdict
+- **ALL criteria ≥ 3 on all dimensions** → PASS. Phase verified.
+- **ANY criterion < 3 on ANY dimension** → FAIL. List each gap with: what scored low, what file, what's needed. Suggest `/qualia-plan {N} --gaps`.
+
+Never round up. A 2 is not a 3. The goal of verification is to catch the work that LOOKS done but ISN'T.
+
+## Few-Shot Calibration
 
-Each success criterion from the plan gets a verdict:
+Use these examples to calibrate your judgment. Real verification should match this level of rigor.
 
-- **PASS** — All 3 levels check out. File exists, has real implementation (not stubs), and is imported/used by the system.
-- **PARTIAL** — File exists and has real code, but isn't fully wired (e.g., component exists but isn't rendered in any page, API route exists but no client calls it). This is NOT a pass.
-- **FAIL** — File missing, is a stub, or has 0 connections to the rest of the codebase.
+### Example A: PASS — Auth Phase
 
-Phase verdict:
-- **ALL PASS** → Phase verified. Update STATE.md status to "verified".
-- **ANY PARTIAL or FAIL** → Phase has gaps. List each gap with: what's wrong, what file, what's needed. Suggest `/qualia-plan {N} --gaps`.
+Phase goal: "User can sign up, log in, and access protected routes."
 
-Never round up. A PARTIAL is not a PASS. The goal of verification is to catch the work that LOOKS done but ISN'T.
+| Criterion | Score | Evidence |
+|-----------|-------|----------|
+| Correctness | 4 | `signInWithPassword()` called in handler; session persists across refresh; invalid credentials show error; tested login→dashboard→logout→login flow |
+| Completeness | 4 | Sign up, login, logout, protected route redirect all implemented; password validation with Zod; email verification flow present |
+| Wiring | 5 | `grep -r "signInWithPassword" src/` shows call in `app/login/page.tsx`; `grep -r "createClient" src/lib/` shows server client used in middleware; `grep -r "auth.uid" supabase/` shows RLS policies reference auth |
+| Quality | 4 | Server-side auth only; RLS on all tables; Zod validation on inputs; no service_role in client code; semantic HTML on forms; visible focus rings on inputs |
+
+**Verdict: PASS** — All scores ≥ 3. Minimum threshold check: NO scores below 3.
+
+### Example B: FAIL — Chat Component Phase
+
+Phase goal: "Working real-time chat interface with message history."
+
+| Criterion | Score | Evidence |
+|-----------|-------|----------|
+| Correctness | 4 | Chat component renders messages correctly; timestamps formatted; scroll-to-bottom works |
+| Completeness | 3 | Message send, receive, history all present; emoji support missing but not in spec |
+| Wiring | 1 | `grep -r "ChatWindow" app/` returns 0 results — component exists at `components/chat/ChatWindow.tsx` but is NOT rendered in any page. `grep -r "from.*chat" app/` returns 0. The component is an island. |
+| Quality | 3 | Clean code; types present; but no loading state, no error state, no empty state |
+
+**Verdict: FAIL** — Wiring scored 1 (below threshold of 3). The chat component is well-built code that nobody can access because it's not mounted in any route. This is the exact kind of "looks done but isn't" that verification exists to catch.
 
 ## Design Verification (for phases with frontend work)
 
-If the phase involved UI/frontend tasks, add a **Design Quality** section to the report:
+If the phase involved UI/frontend tasks, add a **Design Quality** section to the report.
 
-### Check 1: Design System Compliance
+First, read the project's DESIGN.md:
 ```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN_MD"
+```
+
+If DESIGN.md exists, verify against its specific values. If not, verify against `rules/frontend.md` defaults.
+
+### Check 1: Design System Compliance (DESIGN.md §2, §3, §12)
+```bash
+# Anti-slop detection — run patterns from DESIGN.md §12
 # Generic fonts (should NOT appear)
 grep -rn "font-family.*Inter\|font-family.*Roboto\|font-family.*Arial\|fontFamily.*Inter\|fontFamily.*Roboto" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null
 grep -rn "font-sans\|font-inter" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null
@@ -163,9 +272,30 @@ grep -rn "max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-width.*1280\|max-w-7x
 
 # Hardcoded colors instead of CSS variables (check density)
 grep -rn "color:.*#\|background:.*#\|bg-\[#" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | wc -l
+# If DESIGN.md §2 defines CSS variables and this count > 5 → flag
+
+# Blue-purple gradients (AI slop tell)
+grep -rn "from-blue.*to-purple\|from-purple.*to-blue\|linear-gradient.*blue.*purple" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
 ```
 
-### Check 2: Accessibility Basics
+### Check 2: Typography (DESIGN.md §3)
+```bash
+# Verify project fonts are actually loaded (check layout.tsx or globals.css)
+grep -rn "font-family\|fontFamily\|Google.*Font\|next/font" --include="*.tsx" --include="*.css" app/layout* src/ 2>/dev/null | head -5
+
+# If DESIGN.md specifies a font, grep for it
+# grep -rn "{DESIGN.MD_FONT_NAME}" --include="*.tsx" --include="*.css" app/ 2>/dev/null
+```
+Cross-reference: do the fonts in code match §3 hierarchy table? Are weights correct?
+
+### Check 3: Depth & Elevation (DESIGN.md §6)
+```bash
+# Check for shadow usage (should use CSS variables, not inline rgba)
+grep -rn "box-shadow\|shadow-\[" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -10
+# Verify shadows match the elevation levels from DESIGN.md §6
+```
+
+### Check 4: Accessibility (DESIGN.md §10)
 ```bash
 # Images without alt text
 grep -rn "<img" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "alt="
@@ -179,35 +309,53 @@ grep -rn "outline.*none\|outline-none" --include="*.tsx" --include="*.jsx" --inc
 # Missing lang attribute
 grep -rn "<html" --include="*.tsx" --include="*.jsx" app/ 2>/dev/null | grep -v "lang="
 
-# Heading hierarchy — check for h1 count
+# Heading hierarchy — check for h1 count per page
 grep -rn "<h1\|<H1" --include="*.tsx" --include="*.jsx" app/ 2>/dev/null | wc -l
+
+# Skip link presence
+grep -rn "skip.*main\|sr-only.*focus" --include="*.tsx" app/layout* 2>/dev/null
 ```
 
-### Check 3: Interactive States
+### Check 5: Interactive States
 ```bash
-# Buttons/links without hover/focus styles — spot check
-grep -rn "<button\|<Button\|<a " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | head -5
-# Verify these have hover/focus transitions in their styling
-
 # Loading states — check for skeleton/spinner usage in pages with data fetching
 grep -rn "fetch\|useQuery\|useSWR\|getServerSide\|async.*Component" --include="*.tsx" app/ 2>/dev/null | head -5
 grep -rn "loading\|skeleton\|spinner\|Spinner\|Loading" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
 
 # Empty states — check lists/tables have empty handling
 grep -rn "\.length.*===.*0\|\.length.*>.*0\|isEmpty\|no.*results\|no.*data" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
+
+# Error states — check for error boundaries or error handling
+grep -rn "error\|Error\|catch\|fallback" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
 ```
 
-### Check 4: Responsive
+### Check 6: Responsive (DESIGN.md §8)
 ```bash
 # Check for responsive utilities or media queries
 grep -rn "sm:\|md:\|lg:\|xl:\|@media" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null | wc -l
 # If 0 responsive declarations across multiple components → FAIL
+
+# Check collapsing strategy matches DESIGN.md §8 table
+# Verify navigation has mobile treatment
+grep -rn "hamburger\|mobile.*nav\|drawer\|menu.*toggle\|MenuIcon" --include="*.tsx" app/ components/ 2>/dev/null
+```
+
+### Check 7: Hardening (DESIGN.md §11)
+```bash
+# Check for text overflow handling
+grep -rn "truncate\|overflow.*hidden\|text-ellipsis\|line-clamp" --include="*.tsx" --include="*.css" app/ components/ 2>/dev/null | wc -l
+
+# Check for empty state components
+grep -rn "empty\|Empty\|no.*found\|no.*results" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
 ```
 
 ### Scoring Design
-- 0 generic fonts + 0 hardcoded max-widths + colors via variables = **PASS**
-- Accessibility basics all present = **PASS**
-- States and responsive present = **PASS**
+- 0 generic fonts + 0 hardcoded max-widths + colors via CSS vars = **PASS** (§12)
+- Fonts/weights match DESIGN.md §3 hierarchy = **PASS**
+- Shadows use elevation system from §6 = **PASS**
+- Accessibility checklist from §10 all present = **PASS**
+- States (loading/empty/error) present = **PASS**
+- Responsive declarations present + mobile nav = **PASS** (§8)
 - Any category failing = add to **Gaps** list with specific file:line
 
 ## Rules