qualia-framework 3.2.0 → 3.2.1

package/bin/statusline.js

@@ -224,11 +224,11 @@ try {
   if (AGENT) LINE1 += ` ${DIM}│${RESET} ${TEAL}⚡${AGENT}${RESET}`;
   if (WORKTREE) LINE1 += ` ${DIM}│${RESET} ${TEAL_DIM}⎇ ${WORKTREE}${RESET}`;
   if (PHASE_INFO) LINE1 += ` ${DIM}│${RESET} ${PHASE_INFO}`;
-  // Memory, hooks, skills — context indicators
+  // Memory, hooks, skills — context indicators with labels
   const contextParts = [];
-  if (MEMORY_COUNT > 0) contextParts.push(`${TEAL}⊙${RESET}${DIM}${MEMORY_COUNT}${RESET}`);
-  if (HOOKS_COUNT > 0) contextParts.push(`${TEAL_GLOW}⚙${RESET}${DIM}${HOOKS_COUNT}${RESET}`);
-  if (SKILLS_COUNT > 0) contextParts.push(`${TEAL_DIM}✦${RESET}${DIM}${SKILLS_COUNT}${RESET}`);
+  if (MEMORY_COUNT > 0) contextParts.push(`${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`);
+  if (HOOKS_COUNT > 0) contextParts.push(`${DIM}hooks${RESET} ${TEAL_GLOW}${HOOKS_COUNT}${RESET}`);
+  if (SKILLS_COUNT > 0) contextParts.push(`${DIM}skills${RESET} ${TEAL_DIM}${SKILLS_COUNT}${RESET}`);
   if (contextParts.length > 0) {
     LINE1 += ` ${DIM}│${RESET} ${contextParts.join(` ${DIM}·${RESET} `)}`;
   }

package/docs/erp-contract.md

@@ -0,0 +1,161 @@
+# ERP API Contract
+
+The Qualia Framework optionally uploads session reports to the company ERP at `https://portal.qualiasolutions.net`. This document specifies the API shape.
+
+## Configuration
+
+Stored in `~/.claude/.qualia-config.json`:
+
+```json
+{
+  "erp": {
+    "enabled": true,
+    "url": "https://portal.qualiasolutions.net",
+    "api_key_file": ".erp-api-key"
+  }
+}
+```
+
+The API key is read from `~/.claude/.erp-api-key` (file mode 0600).
+
+## Endpoints
+
+### POST /api/v1/reports
+
+Upload a session report.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "project": "client-project-name",
+  "client": "Client Name",
+  "phase": 2,
+  "phase_name": "Authentication & Dashboard",
+  "total_phases": 4,
+  "status": "built",
+  "tasks_done": 5,
+  "tasks_total": 5,
+  "verification": "pass",
+  "gap_cycles": 0,
+  "deployed_url": "https://client.vercel.app",
+  "session_duration_minutes": 45,
+  "commits": ["abc1234", "def5678"],
+  "notes": "Completed auth flow, dashboard layout, and API routes.",
+  "submitted_by": "Fawzi Goussous",
+  "submitted_at": "2026-04-12T14:30:00Z"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "report_id": "rpt_abc123def456",
+  "message": "Report received"
+}
+```
+
+**Response (401 Unauthorized):**
+```json
+{
+  "ok": false,
+  "error": "INVALID_API_KEY",
+  "message": "API key is invalid or expired"
+}
+```
+
+**Response (422 Unprocessable Entity):**
+```json
+{
+  "ok": false,
+  "error": "VALIDATION_FAILED",
+  "message": "Missing required field: project"
+}
+```
+
+### GET /api/v1/reports/:project
+
+Retrieve reports for a project.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "reports": [
+    {
+      "report_id": "rpt_abc123def456",
+      "phase": 2,
+      "status": "built",
+      "submitted_at": "2026-04-12T14:30:00Z",
+      "submitted_by": "Fawzi Goussous"
+    }
+  ]
+}
+```
+
+### GET /api/v1/tracking/:project
+
+Retrieve current tracking state (same shape as tracking.json).
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "tracking": {
+    "project": "client-project-name",
+    "phase": 2,
+    "total_phases": 4,
+    "status": "built",
+    "last_updated": "2026-04-12T14:30:00Z"
+  }
+}
+```
+
+## Behavior
+
+- When `erp.enabled` is `false`, `/qualia-report` skips the upload silently.
+- When the API key file is missing or empty, the upload is skipped with a warning.
+- Network failures are non-blocking — the report is saved locally regardless.
+- The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
+- Reports are append-only — no update or delete endpoints exist.
+
+## Required Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| project | string | yes | Project slug from tracking.json |
+| phase | number | yes | Current phase number |
+| status | string | yes | Current status (setup, planned, built, verified, etc.) |
+| submitted_by | string | yes | Team member name |
+| submitted_at | string | yes | ISO 8601 timestamp |
+
+All other fields are optional but recommended for complete reporting.
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Report body max size: 64KB
+- No batch endpoint — one report per request
+
+## Security
+
+- API keys are per-user, not per-project
+- Keys expire after 90 days (re-issue via Fawzi)
+- All traffic is HTTPS-only
+- No PII beyond team member names is transmitted

package/hooks/branch-guard.js

@@ -10,11 +10,30 @@ const path = require("path");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const CONFIG = path.join(os.homedir(), ".claude", ".qualia-config.json");
 
+function _trace(hookName, result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 function fail(msg) {
   console.log(msg);
-  process.exit(1);
+  _trace("branch-guard", "block", { reason: msg });
+  process.exit(2);
 }
 
 let role = "";
@@ -40,8 +59,10 @@ if (branch === "main" || branch === "master") {
   if (role !== "OWNER") {
     console.log(`BLOCKED: Employees cannot push to ${branch}. Create a feature branch first.`);
     console.log("Run: git checkout -b feature/your-feature-name");
-    process.exit(1);
+    _trace("branch-guard", "block", { reason: `non-owner push to ${branch}` });
+    process.exit(2);
   }
 }
 
+_trace("branch-guard", "allow");
 process.exit(0);

package/hooks/migration-guard.js

@@ -6,6 +6,8 @@
 
 const fs = require("fs");
 
+const _traceStart = Date.now();
+
 function readInput() {
   try {
     const raw = fs.readFileSync(0, "utf8");
@@ -20,8 +22,27 @@ const ti = input.tool_input || {};
 const file = String(ti.file_path || "").replace(/\\/g, "/");
 const content = String(ti.content || ti.new_string || "");
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const path = require("path");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const filePath = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 // Only inspect migration/SQL files
 if (!/migration|migrate|\.sql$/i.test(file)) {
+  _trace("migration-guard", "allow", { reason: "non-migration file" });
   process.exit(0);
 }
 
@@ -54,7 +75,9 @@ if (errors.length > 0) {
   }
   console.log("");
   console.log("Fix these before proceeding. If intentional, ask Fawzi to approve.");
+  _trace("migration-guard", "block", { errors });
   process.exit(2);
 }
 
+_trace("migration-guard", "allow");
 process.exit(0);

package/hooks/pre-compact.js

@@ -7,6 +7,8 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const STATE_FILE = path.join(".planning", "STATE.md");
 
 try {
@@ -29,4 +31,22 @@ try {
   // Silent — never block compaction
 }
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-compact", "allow");
 process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -9,6 +9,25 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 function runGate(label, cmd, args, { required = true } = {}) {
   const r = spawnSync(cmd, args, {
     stdio: "ignore",
@@ -21,6 +40,7 @@ function runGate(label, cmd, args, { required = true } = {}) {
   }
   if (required) {
     console.log(`BLOCKED: ${label} errors. Fix before deploying.`);
+    _trace("pre-deploy-gate", "block", { gate: label });
     process.exit(1);
   }
   return false;
@@ -60,10 +80,27 @@ function scanServiceRoleLeaks() {
   const leaks = [];
   for (const root of roots) {
     for (const file of walk(root)) {
+      // --- Path-based skips (no I/O needed) ---
+
       // Skip server-only files (convention: *.server.ts, server/ dirs)
       if (/\.server\.|[\\/]server[\\/]/.test(file)) continue;
+
+      // Skip App Router route handlers (always server-side)
+      if (/[\\/]route\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip middleware (always server-side)
+      if (/[\\/]middleware\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip files in app/api/ directory (always server-side)
+      if (/[\\/]app[\\/]api[\\/]/.test(file)) continue;
+
+      // --- Content-based checks (requires reading file) ---
       try {
         const content = fs.readFileSync(file, "utf8");
+
+        // Skip files with "use server" directive (Server Actions / Server Components)
+        if (/^["']use server["']/m.test(content)) continue;
+
         if (/service_role/.test(content)) {
           leaks.push(file);
         }
@@ -102,9 +139,11 @@ if (leaks.length > 0) {
   for (const f of leaks.slice(0, 10)) {
     console.log(`  ✗ ${f}`);
   }
+  _trace("pre-deploy-gate", "block", { gate: "security", leaks: leaks.slice(0, 10) });
   process.exit(1);
 }
 console.log("  ✓ Security");
 console.log("⬢ All gates passed.");
 
+_trace("pre-deploy-gate", "allow");
 process.exit(0);

package/hooks/pre-push.js

@@ -8,6 +8,8 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const TRACKING = path.join(".planning", "tracking.json");
 
 try {
@@ -30,4 +32,22 @@ try {
   process.stderr.write(`WARNING: tracking sync failed: ${err.message}\n`);
 }
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-push", "allow");
 process.exit(0);

package/hooks/session-start.js

@@ -18,6 +18,7 @@ const HOME = os.homedir();
 const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
+const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
 
 function runUi(...args) {
   if (!fs.existsSync(UI)) return;
@@ -45,46 +46,6 @@ function getNextCommand() {
   }
 }
 
-function maybeShowUpdateBanner() {
-  // Sticky framework update notification for EMPLOYEEs. Populated by
-  // auto-update.js when it detects a newer qualia-framework version on npm.
-  // OWNER auto-updates silently, so this file is never created for Fawzi.
-  try {
-    const notifFile = path.join(HOME, ".claude", ".qualia-update-available.json");
-    if (!fs.existsSync(notifFile)) return;
-
-    const cfg = readConfig();
-    // Belt-and-suspenders: even if a stale notification exists, OWNER never sees it.
-    if (cfg.role === "OWNER") {
-      try { fs.unlinkSync(notifFile); } catch {}
-      return;
-    }
-
-    const notif = JSON.parse(fs.readFileSync(notifFile, "utf8"));
-
-    // If the user has already updated (cfg.version >= notif.latest), clear the file.
-    if (cfg.version && notif.latest) {
-      const cmp = (a, b) => {
-        const pa = String(a).split(".").map(Number);
-        const pb = String(b).split(".").map(Number);
-        for (let i = 0; i < 3; i++) {
-          if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-          if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-        }
-        return 0;
-      };
-      if (cmp(cfg.version, notif.latest) >= 0) {
-        try { fs.unlinkSync(notifFile); } catch {}
-        return;
-      }
-    }
-
-    runUi("update", notif.current || cfg.version || "?", notif.latest || "?");
-  } catch {
-    // Never fail the session start.
-  }
-}
-
 function fallbackText() {
   // If qualia-ui.js is missing, emit plain text. Keeps the session informative
   // even on a broken install.
@@ -105,10 +66,22 @@ function fallbackText() {
   }
 }
 
+function maybeRenderUpdateBanner() {
+  // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
+  // version is detected; we render it every session until the user actually
+  // runs `npx qualia-framework@latest install`. The file is cleared by
+  // auto-update.js once the install completes or the version catches up.
+  if (!fs.existsSync(NOTIF_FILE) || !fs.existsSync(UI)) return;
+  try {
+    const notif = JSON.parse(fs.readFileSync(NOTIF_FILE, "utf8"));
+    if (notif && notif.current && notif.latest) {
+      runUi("update", notif.current, notif.latest);
+    }
+  } catch {}
+}
+
 try {
-  // Sticky update notification — shown before anything else every session
-  // until the employee runs `npx qualia-framework@latest install`.
-  maybeShowUpdateBanner();
+  maybeRenderUpdateBanner();
 
   if (!fs.existsSync(UI)) {
     fallbackText();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -19,11 +19,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/QualiasolutionsCY/qualia-framework.git"
+    "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
   },
-  "homepage": "https://github.com/QualiasolutionsCY/qualia-framework#readme",
+  "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
   "scripts": {
-    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh && bash tests/bin.test.sh && bash tests/statusline.test.sh"
+    "test": "node --test tests/runner.js"
   },
   "files": [
     "bin/",
@@ -33,6 +33,7 @@
     "skills/",
     "templates/",
     "tests/",
+    "docs/",
     "CLAUDE.md",
     "guide.md"
   ],

package/rules/infrastructure.md

@@ -0,0 +1,87 @@
+---
+globs: ["*.env*", "vercel.json", "next.config.*", "supabase/**", "railway.*"]
+---
+
+# Infrastructure & Services
+
+Standard services across all Qualia projects. Use these unless the project explicitly specifies otherwise.
+
+## Database: Supabase (every project)
+- Every project uses Supabase for auth, database, and storage
+- **CLI:** `npx supabase` — migrations, type generation, local dev
+- **MCP:** Supabase MCP server is available in Claude Code for direct database operations
+- Always enable RLS on every table (see `rules/security.md`)
+- Use `lib/supabase/server.ts` for server-side, `lib/supabase/client.ts` for client-side
+- Run `npx supabase gen types` after schema changes
+- Migrations go in `supabase/migrations/` — never edit production directly
+
+## AI Models: OpenRouter (every project)
+- Use OpenRouter API for all LLM calls — it routes to the best-suited model per task
+- API key env var: `OPENROUTER_API_KEY`
+- Don't have a key? Ask Fawzi for one
+- Never hardcode a specific model provider (OpenAI, Anthropic, etc.) directly — always go through OpenRouter
+- Exception: if a client specifically requires a direct provider integration
+
+## Voice AI: Retell AI + ElevenLabs
+- **Retell AI** — primary voice agent platform. API key: `RETELL_API_KEY`
+- **ElevenLabs** — voice synthesis, cloning, streaming. API key: `ELEVENLABS_API_KEY`
+- **Telnyx** — telephony/SIP for voice agent phone numbers. API key: `TELNYX_API_KEY`
+- For new voice projects, default to Retell AI + ElevenLabs unless client specifies otherwise
+
+## Compute: Vercel + Railway
+- **Vercel** — primary hosting for all Next.js projects. Deploy via CLI only (see below)
+- **Railway** — secondary compute for long-running agents, background jobs, and agentic workloads that exceed Vercel's function timeout
+- **Railway CLI:** `railway` — deploy, logs, env management
+- **Railway MCP:** Railway MCP server is available in Claude Code for project management
+- Railway projects use Nixpacks (auto-detected) — check for `railway.json` or `railway.toml`
+
+## MCP Servers (available in Claude Code)
+- **Supabase MCP** — database queries, table management, migrations from within Claude Code
+- **Railway MCP** — project deployment, logs, environment variables from within Claude Code
+- **next-devtools MCP** — runtime error visibility for Next.js 16+ dev servers (optional, added by framework install)
+
+## CLIs (must be installed)
+- `npx supabase` — Supabase CLI (database, migrations, types)
+- `railway` — Railway CLI (deploy, logs, env)
+- `vercel` — Vercel CLI (deploy, env, link)
+- `gh` — GitHub CLI (PRs, issues, repos)
+
+## GitHub Organizations
+- **QualiasolutionsCY** — primary org for all Qualia Solutions projects
+- **SakaniQualia** — org for Sakani-related projects (real estate platform)
+- All repos are private by default
+- Branch protection: main/master require PR reviews (enforced by framework guards)
+
+## Vercel Teams (admin knowledge)
+- Qualia operates across **3 Vercel teams** — projects are distributed across them
+- Check which team a project belongs to before deploying: `vercel whoami` and `vercel link`
+- If a project isn't linked, link it first: `vercel link`
+
+## Deployment Rules
+- **NO auto-deploys from GitHub pushes** — all Vercel projects have GitHub integration auto-deploy DISABLED
+- Deploys happen ONLY via `vercel --prod` through the CLI (or `/qualia-ship`)
+- This is intentional — we control when things go live, not git push triggers
+- If you find a project with auto-deploy enabled, disable it: Vercel Dashboard → Project Settings → Git → Disable "Automatic Deployments"
+
+## Required Environment Variables (typical project)
+
+```bash
+# Supabase (every project)
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+SUPABASE_SERVICE_ROLE_KEY=          # NEVER in client code
+
+# AI (if applicable)
+OPENROUTER_API_KEY=                 # ask Fawzi if you don't have one
+
+# Voice (if applicable)
+RETELL_API_KEY=
+ELEVENLABS_API_KEY=
+TELNYX_API_KEY=
+
+# Deployment
+VERCEL_ORG_ID=                      # from vercel link
+VERCEL_PROJECT_ID=                  # from vercel link
+```
+
+Always use `vercel env pull` to sync env vars locally. Never create `.env` manually from scratch.

package/skills/qualia/SKILL.md

@@ -47,6 +47,7 @@ Use the state.js JSON output plus gathered context:
 | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
 | `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
 | `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+| `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
 
 **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
 

package/skills/qualia-build/SKILL.md

@@ -21,6 +21,24 @@ cat .planning/phase-{N}-plan.md
 
 Parse: tasks, waves, file references.
 
+### 1b. Create Recovery Point
+
+Before executing any tasks, tag current HEAD for rollback:
+
+```bash
+git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
+```
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
+```
+
+If a wave fails and the user needs to roll back:
+```bash
+git reset --hard pre-build-phase-{N}
+node ~/.claude/bin/state.js transition --to planned --force
+```
+
 ### 2. Execute Waves
 
 ```bash