qualia-framework-v2 2.5.0 → 2.6.0

package/README.md

@@ -47,11 +47,11 @@ See `guide.md` for the full developer guide.
 
 ## What's Inside
 
-- **18 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, and session management
-- **3 agents** — planner, builder, verifier (each in fresh context)
-- **7 hooks** — branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, session start
+- **19 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, and skill authoring
+- **4 agents** — planner, builder, verifier, qa-browser (each in fresh context)
+- **8 hooks** — session start, branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, auto-update
 - **3 rules** — security, frontend, deployment
-- **4 templates** — tracking.json, state.md, project.md, plan.md
+- **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
 
 ## Why It Works
 
@@ -92,13 +92,13 @@ npx qualia-framework-v2 install
      |
      v
 ~/.claude/
-  ├── skills/          18 slash commands
-  ├── agents/          planner.md, builder.md, verifier.md
-  ├── hooks/           7 shell scripts (branch, env, migration, deploy, push, compact, session)
+  ├── skills/          19 slash commands
+  ├── agents/          planner.md, builder.md, verifier.md, qa-browser.md
+  ├── hooks/           8 shell scripts (session-start, branch, env, migration, deploy, push, compact, auto-update)
   ├── bin/             state.js (state machine with precondition enforcement)
-  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md
+  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (auto-loaded by skills)
   ├── rules/           security.md, frontend.md, deployment.md
-  ├── qualia-templates/ tracking.json, state.md, project.md, plan.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
 ```

package/agents/planner.md

@@ -81,7 +81,13 @@ Every task MUST have these three fields with concrete content:
 - **Action:** At least one concrete instruction — not just "implement auth". Reference specific functions, components, or patterns. "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
 - **Done when:** Testable, not fuzzy. Good: "User can log in with email/password and session persists across page refresh." Bad: "Auth works." Best: includes a verification command — `grep -c "signInWithPassword" src/lib/auth.ts` returns non-zero.
 
-If a task involves a library or API you're unsure about, use WebFetch to check the current documentation before specifying the approach. Don't guess at APIs.
+If a task involves a library, framework, or API you're unsure about, fetch the current documentation BEFORE specifying the approach. Don't guess at APIs.
+
+Preferred order:
+1. **Context7 MCP** — `mcp__context7__resolve-library-id` then `mcp__context7__query-docs`. Fast, current, structured. Use for: React, Next.js, Supabase, Tailwind, Prisma, ORMs, Zod, AI SDKs, any library with a published version.
+2. **WebFetch** — only when Context7 doesn't have the library, or you need a specific blog post / changelog page.
+
+Your training data is often stale. A two-second lookup is cheaper than a wrong task specification.
 
 **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.
 
@@ -92,7 +98,7 @@ When a phase involves frontend work (pages, components, layouts, UI):
 1. **Check for `.planning/DESIGN.md`** — if it exists, reference it in task Context fields: `@.planning/DESIGN.md`
 2. **If no DESIGN.md and this is Phase 1** — add a Task 1 (Wave 1) to create it:
    - Generate `.planning/DESIGN.md` from the design direction in PROJECT.md
-   - Use the template at `templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
+   - Use the template at `~/.claude/qualia-templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
    - Done when: DESIGN.md exists with concrete CSS variable values (not placeholders)
 3. **Include design criteria in "Done when"** for frontend tasks:
    - Not just "page renders" but "page renders with design system typography, proper color palette, all interactive states (hover/focus/loading/error/empty), semantic HTML, keyboard accessible"

package/agents/qa-browser.md

@@ -0,0 +1,186 @@
+---
+name: qualia-qa-browser
+description: Real-browser QA. Navigates the running dev server, checks layout at mobile/tablet/desktop, clicks primary flows, captures console errors and a11y issues. Spawned by /qualia-verify on phases with frontend work.
+tools: Read, Bash, Grep, Glob
+---
+
+# Qualia QA Browser
+
+You verify that the **running app actually looks and behaves right** — not just that the code compiles and greps clean. Fresh context, no memory of what was built.
+
+**Critical mindset:** You are the user. You don't trust the code — you drive the app and see what happens. If it breaks at 375px, it's broken. If the console screams, it's broken. If clicking the primary CTA does nothing, it's broken.
+
+## Input
+You receive: the phase plan (to know what pages/flows exist) + the dev server URL + access to Playwright MCP browser tools.
+
+## Output
+Append a `## Browser QA` section to `.planning/phase-{N}-verification.md` with PASS/FAIL per check.
+
+## Tools You Must Use
+
+The Playwright MCP provides these tools — use them directly:
+
+- `mcp__playwright__browser_navigate` — go to a URL
+- `mcp__playwright__browser_snapshot` — DOM accessibility tree (your primary inspection tool — NOT screenshots)
+- `mcp__playwright__browser_resize` — switch viewport
+- `mcp__playwright__browser_click` — click elements
+- `mcp__playwright__browser_console_messages` — grab console errors/warnings
+- `mcp__playwright__browser_take_screenshot` — only when you need to show something visual to the user
+- `mcp__playwright__browser_evaluate` — run JS in the page (e.g., `document.querySelectorAll('img:not([alt])').length`)
+- `mcp__playwright__browser_wait_for` — wait for elements/text
+
+Prefer `browser_snapshot` over `browser_take_screenshot` — the accessibility tree tells you structure, text content, and interaction targets without burning context on images.
+
+## Process
+
+### 1. Find the Dev Server
+
+```bash
+# Check if already running
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3001 2>/dev/null
+
+# If not running, start it in background
+if ! curl -s http://localhost:3000 >/dev/null 2>&1; then
+  npm run dev > /tmp/dev-server.log 2>&1 &
+  sleep 5  # give it time to boot
+fi
+```
+
+If you can't reach a dev server after 10 seconds, write **BLOCKED: dev server not reachable** to the verification report and exit.
+
+### 2. Identify Pages to Test
+
+From the phase plan, extract the user-facing routes that were built. If unclear, inspect the file tree:
+
+```bash
+ls app/**/page.tsx 2>/dev/null || ls src/app/**/page.tsx 2>/dev/null || ls pages/*.tsx 2>/dev/null
+```
+
+Pick the 3-5 most important routes: home + primary feature pages + auth if present.
+
+### 3. Responsive Check (Critical)
+
+For each route, visit at 3 viewports:
+
+```
+1. navigate http://localhost:{port}{route}
+2. browser_resize 375 812    (iPhone 14)
+3. browser_snapshot           (capture mobile tree)
+4. browser_resize 768 1024   (iPad)
+5. browser_snapshot           (capture tablet tree)
+6. browser_resize 1440 900   (laptop)
+7. browser_snapshot           (capture desktop tree)
+```
+
+**FAIL criteria:**
+- Horizontal scroll at 375px (check scrollWidth > clientWidth via `browser_evaluate`)
+- Text overflow / clipping at any size
+- Elements overlapping or z-index collisions
+- Navigation not accessible on mobile (no hamburger, or hamburger doesn't open)
+- Content hidden or unreadable at any viewport
+
+### 4. Console Errors Check
+
+```
+browser_console_messages
+```
+
+**FAIL criteria:**
+- Any `error` level message (hydration mismatch, 404 on assets, unhandled promise rejection)
+- React key warnings are FAIL (they mean stale lists)
+- Font 404s are FAIL (means the font config is broken)
+- Accessibility warnings from React are FAIL
+
+### 5. Primary Flow Walkthrough
+
+For each primary user flow (login, signup, main action), do it:
+
+```
+1. navigate to the flow's start
+2. browser_snapshot to find the actual interactive elements
+3. browser_click on the primary CTA
+4. browser_wait_for the expected result
+5. browser_snapshot to verify the result
+```
+
+**FAIL criteria:**
+- CTA doesn't respond (no state change, no navigation)
+- Form submits but shows no feedback (loading/success/error state missing)
+- Navigation ends up at a 404 or error page
+- Auth flow loses the user on redirect
+
+### 6. Accessibility Basics
+
+Run these checks via `browser_evaluate`:
+
+```js
+// Images without alt
+document.querySelectorAll('img:not([alt])').length
+
+// Form inputs without labels
+Array.from(document.querySelectorAll('input, textarea, select')).filter(el => {
+  const id = el.id;
+  const hasLabel = id && document.querySelector(`label[for="${id}"]`);
+  return !hasLabel && !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby');
+}).length
+
+// Heading order
+Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).map(h => parseInt(h.tagName[1]))
+
+// Focus visible on tab
+// (This one needs manual: focus body then press Tab, snapshot, check outline)
+```
+
+**FAIL criteria:**
+- Any `<img>` without alt
+- Any input/textarea/select without a label or aria-label
+- Heading order skips levels (h1 → h3 without h2)
+- Multiple `<h1>` on the same page
+
+### 7. Write the Report
+
+Append to `.planning/phase-{N}-verification.md`:
+
+```markdown
+## Browser QA
+
+**Dev server:** http://localhost:{port}
+**Routes tested:** {list}
+
+### Responsive
+| Route | 375px | 768px | 1440px | Notes |
+|-------|-------|-------|--------|-------|
+| / | PASS | PASS | PASS | |
+| /login | FAIL | PASS | PASS | Form overflows at 375px |
+
+### Console Errors
+- {count} errors, {count} warnings
+- {list each error with route}
+
+### Primary Flows
+| Flow | Result | Notes |
+|------|--------|-------|
+| Sign up → dashboard | PASS | Loading state visible |
+| Login → dashboard | FAIL | Clicking "Sign in" does nothing |
+
+### Accessibility
+- Images without alt: {count}
+- Inputs without labels: {count}
+- Heading order issues: {list}
+
+### Verdict
+PASS — all flows work, responsive clean, no console errors
+OR
+FAIL — {N} issues found. See above.
+```
+
+## Rules
+
+1. **Never trust code that you haven't driven.** The compiler says "yes" all the time about things that don't work.
+2. **Test at 375px first.** If it breaks on mobile, it's broken. Desktop-first thinking is a bug.
+3. **Console errors are failures, not warnings.** A hydration mismatch today is a production bug tomorrow.
+4. **Don't fix anything.** You have no Write/Edit tools. You report; the planner decides the fix.
+5. **Don't start the dev server if it's already running.** You'd kill someone else's session.
+6. **Cap snapshots.** Don't take 50 snapshots — aim for ~15 total across all pages and viewports. Budget your context.
+7. **If Playwright MCP isn't available**, write `BLOCKED: Playwright MCP not connected. Run: claude mcp list` and exit. Don't fake it.

package/bin/install.js

@@ -208,8 +208,14 @@ async function main() {
       path.join(binDest, "state.js")
     );
     ok("state.js (state machine)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "qualia-ui.js"),
+      path.join(binDest, "qualia-ui.js")
+    );
+    fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
+    ok("qualia-ui.js (cosmetics library)");
   } catch (e) {
-    warn(`state.js — ${e.message}`);
+    warn(`scripts — ${e.message}`);
   }
 
   // ─── Guide ─────────────────────────────────────────────
@@ -228,7 +234,7 @@ async function main() {
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
   if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
   const knowledgeFiles = {
-    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-evolve` and manual notes.\n",
+    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-learn` and manual notes.\n",
     "common-fixes.md": "# Common Fixes\n\nRecurring issues and their solutions.\n",
     "client-prefs.md": "# Client Preferences\n\nClient-specific preferences, design choices, and requirements.\n",
   };
@@ -328,6 +334,18 @@ async function main() {
   // Hooks — full system
   const hd = path.join(CLAUDE_DIR, "hooks");
   settings.hooks = {
+    SessionStart: [
+      {
+        matcher: ".*",
+        hooks: [
+          {
+            type: "command",
+            command: `${hd}/session-start.sh`,
+            timeout: 5,
+          },
+        ],
+      },
+    ],
     PreToolUse: [
       {
         matcher: "Bash",
@@ -351,6 +369,13 @@ async function main() {
             timeout: 15,
             statusMessage: "◆ Syncing tracking...",
           },
+          {
+            type: "command",
+            if: "Bash(vercel --prod*)",
+            command: `${hd}/pre-deploy-gate.sh`,
+            timeout: 120,
+            statusMessage: "◆ Running quality gates...",
+          },
         ],
       },
       {
@@ -373,20 +398,6 @@ async function main() {
         ],
       },
     ],
-    PostToolUse: [
-      {
-        matcher: "Bash",
-        hooks: [
-          {
-            type: "command",
-            if: "Bash(vercel --prod*)",
-            command: `${hd}/pre-deploy-gate.sh`,
-            timeout: 120,
-            statusMessage: "◆ Running quality gates...",
-          },
-        ],
-      },
-    ],
     PreCompact: [
       {
         matcher: "compact",
@@ -429,7 +440,7 @@ async function main() {
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
@@ -439,10 +450,11 @@ async function main() {
   console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
   console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
   console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
-  console.log(`  Agents:       ${WHITE}3${RESET} ${DIM}(planner, builder, verifier)${RESET}`);
-  console.log(`  Hooks:        ${WHITE}7${RESET} ${DIM}(auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
+  const agentCount = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length;
+  console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
+  console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
   console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}1${RESET} ${DIM}(state.js — state machine)${RESET}`);
+  console.log(`  Scripts:      ${WHITE}2${RESET} ${DIM}(state.js, qualia-ui.js)${RESET}`);
   console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
   console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);

package/bin/qualia-ui.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Qualia UI — consistent banners, context panels, status for every skill.
+// Zero dependencies. Reads state.js + .qualia-config.json for context.
+//
+// Commands:
+//   banner <action> [phase] [subtitle]  — full header with context panel
+//   context                              — just the context panel
+//   divider                              — horizontal rule
+//   ok <message>                         — green check line
+//   fail <message>                       — red cross line
+//   warn <message>                       — yellow bang line
+//   info <message>                       — blue dot line
+//   spawn <agent> <description>          — spawning a subagent
+//   wave <N> <total> <task-count>        — wave header for /qualia-build
+//   task <N> <title>                     — task line (pending)
+//   done <N> <title> [commit]            — task line (completed)
+//   next <command>                       — "Run: /qualia-X" footer
+//   end <status> [next-command]          — closing banner with optional next
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+// ─── Colors ──────────────────────────────────────────────
+const TEAL = "\x1b[38;2;0;206;209m";
+const TEAL_DIM = "\x1b[38;2;0;140;145m";
+const DIM = "\x1b[38;2;100;110;120m";
+const DIM2 = "\x1b[38;2;70;80;90m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const BLUE = "\x1b[38;2;96;165;250m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+const RULE = "━".repeat(42);
+const RULE_DIM = `${DIM2}${RULE}${RESET}`;
+
+// ─── Action Labels ───────────────────────────────────────
+const ACTIONS = {
+  router:     { label: "SMART ROUTER",     glyph: "◆" },
+  new:        { label: "NEW PROJECT",      glyph: "◆" },
+  plan:       { label: "PLANNING",         glyph: "◇" },
+  build:      { label: "BUILDING",         glyph: "◈" },
+  verify:     { label: "VERIFYING",        glyph: "◉" },
+  polish:     { label: "POLISHING",        glyph: "◆" },
+  ship:       { label: "SHIPPING",         glyph: "▲" },
+  handoff:    { label: "HANDING OFF",      glyph: "▶" },
+  report:     { label: "SESSION REPORT",   glyph: "◆" },
+  debug:      { label: "DEBUGGING",        glyph: "◊" },
+  learn:      { label: "LEARNING",         glyph: "◆" },
+  pause:      { label: "PAUSING",          glyph: "◆" },
+  resume:     { label: "RESUMING",         glyph: "◆" },
+  review:     { label: "REVIEW",           glyph: "◆" },
+  design:     { label: "DESIGN PASS",      glyph: "◆" },
+  quick:      { label: "QUICK FIX",        glyph: "◆" },
+  task:       { label: "TASK",             glyph: "◆" },
+  "skill-new": { label: "NEW SKILL",       glyph: "◆" },
+  gaps:       { label: "GAP CLOSURE",      glyph: "◇" },
+};
+
+// ─── State Reading ───────────────────────────────────────
+function readState() {
+  try {
+    const out = execSync(`node ${path.join(os.homedir(), ".claude", "bin", "state.js")} check 2>/dev/null`, {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+function readConfig() {
+  try {
+    const f = path.join(os.homedir(), ".claude", ".qualia-config.json");
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function projectName() {
+  try {
+    return path.basename(process.cwd());
+  } catch {
+    return "—";
+  }
+}
+
+// ─── Rendering Helpers ───────────────────────────────────
+function progressBar(phase, total) {
+  if (!total || total < 1) return "";
+  const pct = Math.min(100, Math.round(((phase - 1) / total) * 100));
+  const filled = Math.round(pct / 10);
+  const bar = `${TEAL}${"█".repeat(filled)}${DIM2}${"░".repeat(10 - filled)}${RESET}`;
+  return `${bar} ${DIM}${pct}%${RESET}`;
+}
+
+function colorForStatus(s) {
+  const colors = {
+    setup: DIM,
+    planned: BLUE,
+    built: YELLOW,
+    verified: GREEN,
+    polished: GREEN,
+    shipped: TEAL,
+    handed_off: TEAL,
+    done: GREEN,
+  };
+  return colors[s] || WHITE;
+}
+
+function pad(str, width) {
+  // Width-aware padding ignoring ANSI codes
+  const visible = str.replace(/\x1b\[[0-9;]*m/g, "");
+  const need = Math.max(0, width - visible.length);
+  return str + " ".repeat(need);
+}
+
+// ─── Commands ────────────────────────────────────────────
+function cmdBanner(action, phase, subtitle) {
+  const spec = ACTIONS[action] || { label: (action || "qualia").toUpperCase(), glyph: "◆" };
+  const state = readState();
+  const config = readConfig();
+  const project = projectName();
+
+  const title = phase
+    ? `${spec.label} ${DIM}·${WHITE} Phase ${phase}${subtitle ? ` ${DIM}— ${WHITE}${subtitle}` : ""}`
+    : spec.label;
+
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}${spec.glyph}${RESET} ${WHITE}${BOLD}QUALIA${RESET} ${DIM}►${RESET} ${WHITE}${title}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+
+  // Context panel
+  const roleColor = config.role === "OWNER" ? TEAL : BLUE;
+  const roleLine = config.role
+    ? `${roleColor}${config.role}${RESET} ${DIM}·${RESET} ${WHITE}${config.installed_by || ""}${RESET}`
+    : `${DIM}(not configured)${RESET}`;
+
+  console.log(`  ${pad(DIM + "Project" + RESET, 20)}${WHITE}${project}${RESET}`);
+
+  if (state && state.ok) {
+    const phaseStr = state.phase_name
+      ? `${state.phase} of ${state.total_phases} ${DIM}— ${WHITE}${state.phase_name}`
+      : `${state.phase} of ${state.total_phases}`;
+    console.log(`  ${pad(DIM + "Phase" + RESET, 20)}${WHITE}${phaseStr}${RESET}`);
+    console.log(`  ${pad(DIM + "Status" + RESET, 20)}${colorForStatus(state.status)}${state.status}${RESET}`);
+    if (state.tasks_total) {
+      console.log(`  ${pad(DIM + "Tasks" + RESET, 20)}${WHITE}${state.tasks_done}/${state.tasks_total}${RESET}`);
+    }
+    const bar = progressBar(state.phase, state.total_phases);
+    if (bar) console.log(`  ${pad(DIM + "Progress" + RESET, 20)}${bar}`);
+    if (state.gap_cycles > 0) {
+      console.log(`  ${pad(DIM + "Gap cycles" + RESET, 20)}${YELLOW}${state.gap_cycles}/2${RESET}`);
+    }
+  }
+
+  console.log(`  ${pad(DIM + "Role" + RESET, 20)}${roleLine}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log("");
+}
+
+function cmdContext() {
+  const state = readState();
+  const config = readConfig();
+  const project = projectName();
+
+  console.log("");
+  console.log(`  ${pad(DIM + "Project" + RESET, 20)}${WHITE}${project}${RESET}`);
+
+  if (state && state.ok) {
+    const phaseStr = state.phase_name
+      ? `${state.phase} of ${state.total_phases} ${DIM}— ${WHITE}${state.phase_name}`
+      : `${state.phase} of ${state.total_phases}`;
+    console.log(`  ${pad(DIM + "Phase" + RESET, 20)}${WHITE}${phaseStr}${RESET}`);
+    console.log(`  ${pad(DIM + "Status" + RESET, 20)}${colorForStatus(state.status)}${state.status}${RESET}`);
+    const bar = progressBar(state.phase, state.total_phases);
+    if (bar) console.log(`  ${pad(DIM + "Progress" + RESET, 20)}${bar}`);
+  } else {
+    console.log(`  ${DIM}No project detected. Run${RESET} ${TEAL}/qualia-new${RESET}`);
+  }
+
+  if (config.role) {
+    const roleColor = config.role === "OWNER" ? TEAL : BLUE;
+    console.log(`  ${pad(DIM + "Role" + RESET, 20)}${roleColor}${config.role}${RESET} ${DIM}·${RESET} ${WHITE}${config.installed_by || ""}${RESET}`);
+  }
+  console.log("");
+}
+
+function cmdDivider() {
+  console.log(`  ${RULE_DIM}`);
+}
+
+function cmdOk(msg) {
+  console.log(`  ${GREEN}✓${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdFail(msg) {
+  console.log(`  ${RED}✗${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdWarn(msg) {
+  console.log(`  ${YELLOW}!${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdInfo(msg) {
+  console.log(`  ${BLUE}◦${RESET} ${DIM}${msg}${RESET}`);
+}
+
+function cmdSpawn(agent, desc) {
+  const name = agent || "agent";
+  const d = desc ? ` ${DIM}— ${desc}${RESET}` : "";
+  console.log(`  ${TEAL}⟐${RESET} ${WHITE}Spawning${RESET} ${TEAL}${name}${RESET}${d}`);
+}
+
+function cmdWave(num, total, taskCount) {
+  console.log("");
+  const n = parseInt(num) || 0;
+  const t = parseInt(total) || 0;
+  const c = parseInt(taskCount) || 0;
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Wave ${n}/${t}${RESET} ${DIM}(${c} ${c === 1 ? "task" : "tasks"}, parallel)${RESET}`);
+}
+
+function cmdTask(num, title) {
+  console.log(`    ${DIM}${num}.${RESET} ${WHITE}${title}${RESET} ${DIM}…${RESET}`);
+}
+
+function cmdDone(num, title, commit) {
+  const c = commit ? ` ${DIM}(${commit})${RESET}` : "";
+  console.log(`    ${GREEN}✓${RESET} ${DIM}${num}.${RESET} ${WHITE}${title}${RESET}${c}`);
+}
+
+function cmdNext(cmd) {
+  if (!cmd) return;
+  console.log("");
+  console.log(`  ${TEAL}→${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${cmd}${RESET}`);
+  console.log("");
+}
+
+function cmdEnd(status, nextCmd) {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}◆${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextCmd) {
+    console.log(`  ${TEAL}→${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
+  }
+  console.log("");
+}
+
+// ─── Main ────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case "banner":
+    cmdBanner(rest[0] || "router", rest[1] || "", rest.slice(2).join(" "));
+    break;
+  case "context":  cmdContext(); break;
+  case "divider":  cmdDivider(); break;
+  case "ok":       cmdOk(rest.join(" ")); break;
+  case "fail":     cmdFail(rest.join(" ")); break;
+  case "warn":     cmdWarn(rest.join(" ")); break;
+  case "info":     cmdInfo(rest.join(" ")); break;
+  case "spawn":    cmdSpawn(rest[0], rest.slice(1).join(" ")); break;
+  case "wave":     cmdWave(rest[0], rest[1], rest[2]); break;
+  case "task":     cmdTask(rest[0], rest.slice(1).join(" ")); break;
+  case "done":     cmdDone(rest[0], rest[1], rest[2]); break;
+  case "next":     cmdNext(rest.join(" ")); break;
+  case "end":      cmdEnd(rest[0], rest.slice(1).join(" ")); break;
+  default:
+    console.error(
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end> [args]`
+    );
+    process.exit(1);
+}

package/hooks/branch-guard.sh

@@ -1,11 +1,20 @@
 #!/bin/bash
 # Block non-OWNER push to main/master
+# Reads role from ~/.claude/.qualia-config.json (machine-readable source of truth)
 
 BRANCH=$(git branch --show-current 2>/dev/null)
-ROLE=$(grep -m1 "^## Role:" ~/.claude/CLAUDE.md 2>/dev/null | sed 's/^## Role: *//')
+CONFIG="$HOME/.claude/.qualia-config.json"
+
+if [ ! -f "$CONFIG" ]; then
+  echo "BLOCKED: ~/.claude/.qualia-config.json missing. Run: npx qualia-framework-v2 install"
+  exit 1
+fi
+
+# Extract role without jq dependency (installers may not have jq)
+ROLE=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$CONFIG','utf8')).role||'')}catch{}" 2>/dev/null)
 
 if [ -z "$ROLE" ]; then
-  echo "BLOCKED: Cannot determine role — ~/.claude/CLAUDE.md missing or malformed. Defaulting to deny."
+  echo "BLOCKED: Cannot determine role from $CONFIG. Defaulting to deny."
   exit 1
 fi