qualia-framework 3.1.0 → 3.2.0

package/hooks/auto-update.js

@@ -66,6 +66,11 @@ try {
 
   // Fork the check-and-update into a detached background process so the hook
   // returns immediately and Claude Code is never blocked.
+  //
+  // OWNER: silent auto-install (unchanged behavior).
+  // EMPLOYEE: write a sticky notification file — session-start.js renders a
+  // banner every session until they run the update manually. Fawzi (OWNER)
+  // never sees the banner because his framework auto-updates ahead of it.
   const script = `
     const fs = require("fs");
     const path = require("path");
@@ -73,6 +78,7 @@ try {
     const CLAUDE_DIR = ${JSON.stringify(CLAUDE_DIR)};
     const LOCK_FILE = ${JSON.stringify(LOCK_FILE)};
     const CONFIG_FILE = ${JSON.stringify(CONFIG_FILE)};
+    const NOTIF_FILE = path.join(CLAUDE_DIR, ".qualia-update-available.json");
     const cfg = ${JSON.stringify(cfg)};
     try {
       fs.writeFileSync(LOCK_FILE, String(process.pid));
@@ -82,7 +88,7 @@ try {
         shell: process.platform === "win32",
       });
       const latest = ((r.stdout || "").trim());
-      if (!latest) { fs.unlinkSync(LOCK_FILE); process.exit(0); }
+      if (!latest) { try { fs.unlinkSync(LOCK_FILE); } catch {} process.exit(0); }
       const cmp = (a, b) => {
         const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
         for (let i = 0; i < 3; i++) {
@@ -92,13 +98,29 @@ try {
         return 0;
       };
       if (cmp(latest, cfg.version) > 0) {
-        // Silent update — pipe the install code via stdin
-        const child = spawnSync("npx", ["qualia-framework@latest", "install"], {
-          input: cfg.code + "\\n",
-          timeout: 120000,
-          stdio: ["pipe", "ignore", "ignore"],
-          shell: process.platform === "win32",
-        });
+        if (cfg.role === "OWNER") {
+          // Silent auto-install for OWNER — no notification banner ever shown.
+          spawnSync("npx", ["qualia-framework@latest", "install"], {
+            input: cfg.code + "\\n",
+            timeout: 120000,
+            stdio: ["pipe", "ignore", "ignore"],
+            shell: process.platform === "win32",
+          });
+          try { fs.unlinkSync(NOTIF_FILE); } catch {}
+        } else {
+          // EMPLOYEE: write sticky notification. session-start.js will render
+          // a visible banner every session until the employee runs the update.
+          try {
+            fs.writeFileSync(NOTIF_FILE, JSON.stringify({
+              current: cfg.version,
+              latest: latest,
+              detected_at: new Date().toISOString(),
+            }, null, 2));
+          } catch {}
+        }
+      } else {
+        // Already up to date — clear any stale notification file.
+        try { fs.unlinkSync(NOTIF_FILE); } catch {}
       }
     } catch {}
     try { fs.unlinkSync(LOCK_FILE); } catch {}

package/hooks/branch-guard.js

@@ -10,30 +10,11 @@ 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);
-  _trace("branch-guard", "block", { reason: msg });
-  process.exit(2);
+  process.exit(1);
 }
 
 let role = "";
@@ -59,10 +40,8 @@ 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");
-    _trace("branch-guard", "block", { reason: `non-owner push to ${branch}` });
-    process.exit(2);
+    process.exit(1);
   }
 }
 
-_trace("branch-guard", "allow");
 process.exit(0);

package/hooks/migration-guard.js

@@ -6,8 +6,6 @@
 
 const fs = require("fs");
 
-const _traceStart = Date.now();
-
 function readInput() {
   try {
     const raw = fs.readFileSync(0, "utf8");
@@ -22,27 +20,8 @@ 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);
 }
 
@@ -75,9 +54,7 @@ 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,8 +7,6 @@ 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 {
@@ -31,22 +29,4 @@ 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,25 +9,6 @@ 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",
@@ -40,7 +21,6 @@ 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;
@@ -80,27 +60,10 @@ 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);
         }
@@ -139,11 +102,9 @@ 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,8 +8,6 @@ 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 {
@@ -32,22 +30,4 @@ 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

@@ -45,6 +45,46 @@ 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.
@@ -66,6 +106,10 @@ function fallbackText() {
 }
 
 try {
+  // Sticky update notification — shown before anything else every session
+  // until the employee runs `npx qualia-framework@latest install`.
+  maybeShowUpdateBanner();
+
   if (!fs.existsSync(UI)) {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "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/Qualiasolutions/qualia-framework.git"
+    "url": "git+https://github.com/QualiasolutionsCY/qualia-framework.git"
   },
-  "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
+  "homepage": "https://github.com/QualiasolutionsCY/qualia-framework#readme",
   "scripts": {
-    "test": "node --test tests/runner.js"
+    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh && bash tests/bin.test.sh && bash tests/statusline.test.sh"
   },
   "files": [
     "bin/",
@@ -33,7 +33,6 @@
     "skills/",
     "templates/",
     "tests/",
-    "docs/",
     "CLAUDE.md",
     "guide.md"
   ],

package/skills/qualia/SKILL.md

@@ -47,7 +47,6 @@ 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,24 +21,6 @@ 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

package/skills/qualia-design/SKILL.md

@@ -25,7 +25,7 @@ node ~/.claude/bin/qualia-ui.js banner design
 cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
 ```
 
-If DESIGN.md exists → it is law. Use exact values from sections 1-9 (Visual Theme, Color Palette, Typography, Components, Layout, Depth, Do's/Don'ts, Responsive, Agent Prompt Guide). If not → use Qualia defaults from `rules/frontend.md`: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
+If DESIGN.md exists → use it. If not → use Qualia defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
 
 ### 2. Find Target Files
 
@@ -41,25 +41,19 @@ Evaluate each file on: AI slop detection, visual hierarchy, typography, color, s
 
 ### 4. Fix Everything
 
-Use exact values from DESIGN.md when available. Sections map to fixes:
+**Typography:** Replace generic fonts (Inter, Arial) with distinctive ones. Proper type scale, line-height 1.5-1.7 body.
 
-**Typography (§3):** Apply fonts from hierarchy table. Replace any generic fonts (Inter, Arial) with project fonts. Use exact weights, sizes, letter-spacing from the table. Body line-height 1.5-1.7.
+**Color:** Cohesive palette from DESIGN.md or brand. Sharp accent for CTAs. WCAG AA contrast.
 
-**Color (§2):** Apply palette from CSS variables. Replace scattered hex values with `var(--color-*)`. Verify contrast ratios listed in DESIGN.md.
+**Layout:** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
 
-**Components (§4):** Match button, card, input, badge specs exactly — padding, radius, shadow, hover states.
+**Spacing:** Consistent scale (8px grid). Generous whitespace between sections, tight within groups.
 
-**Layout (§5):** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. Apply spacing scale. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+**Motion:** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
 
-**Depth (§6):** Apply shadow levels from elevation table. Use brand-tinted shadows, not neutral gray.
+**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on interactive elements.
 
-**Motion (§Motion):** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
-
-**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on every interactive element.
-
-**Responsive (§8):** Apply collapsing strategy from table. Mobile-first. Touch targets 44x44px min. No horizontal scroll.
-
-**Anti-Slop (§12):** Run grep patterns from the detection table. Every match = mandatory fix.
+**Responsive:** Mobile-first. Touch targets 44x44px min. Stack on mobile, expand on desktop. No horizontal scroll.
 
 **Kill:** Card grids → varied layouts. Generic heroes → distinctive. Blue-purple gradients → brand colors. Static pages → purposeful motion. Fixed widths → fluid.
 

package/skills/qualia-learn/SKILL.md

@@ -46,40 +46,17 @@ What did you learn?
 3. Client preference — client-specific requirement
 ```
 
-### 2. Check for Duplicates
-
-Before saving, check if a similar entry already exists:
-
-```bash
-# Search for the title (case-insensitive substring match)
-grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
-```
-
-If a near-match exists (title is similar to an existing entry):
-- Show the existing entry to the user
-- Ask: "A similar entry exists. Update it, create a new one, or skip?"
-- If update: replace the existing entry. If new: append. If skip: done.
-
-### 3. Format Entry
-
-Each entry gets a unique ID and ISO timestamp for dedup and ordering:
+### 2. Format Entry
 
 ```markdown
-
----
-
-### {Title}
-**ID:** {random 8-char hex, e.g. a3f7c1e9}
-**Date:** {ISO 8601, e.g. 2026-04-11}
+### {Title} ({date})
 **Project:** {current project name or "general"}
 **Context:** {brief context — what you were building when you learned this}
 
 {The learning — be specific enough that future-you understands without context}
 ```
 
-### 4. Append to Knowledge File
-
-Append-only — never overwrite the file, always add at the end:
+### 3. Append to Knowledge File
 
 ```bash
 # Append to the right file
@@ -90,7 +67,7 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 - Fix → `~/.claude/knowledge/common-fixes.md`
 - Client pref → `~/.claude/knowledge/client-prefs.md`
 
-### 5. Confirm
+### 4. Confirm
 
 ```
 ⬢ Saved to {file}