qualia-framework-v2 2.9.0 → 3.0.0

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);
 }
 
@@ -48,13 +69,15 @@ if (/CREATE\s+TABLE/i.test(content) && !/ENABLE\s+ROW\s+LEVEL\s+SECURITY/i.test(
 }
 
 if (errors.length > 0) {
-  console.log("◆ Migration guard — dangerous patterns found:");
+  console.log("⬢ Migration guard — dangerous patterns found:");
   for (const e of errors) {
     console.log(`  ✗ ${e}`);
   }
   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);
         }
@@ -73,7 +110,7 @@ function scanServiceRoleLeaks() {
   return leaks;
 }
 
-console.log("◆ Pre-deploy gate...");
+console.log("⬢ Pre-deploy gate...");
 
 // TypeScript
 if (fs.existsSync("tsconfig.json")) {
@@ -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.");
+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

@@ -12,6 +12,8 @@ const path = require("path");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const HOME = os.homedir();
 const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
@@ -81,4 +83,21 @@ try {
   // Deliberately silent — hook must never fail
 }
 
+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 {}
+}
+
+_trace("session-start", "allow");
 process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"

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

package/skills/qualia-design/SKILL.md

@@ -73,7 +73,7 @@ git commit -m "style: design transformation"
 ```
 
 ```
-◆ Design Transformation Complete
+⬢ Design Transformation Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Files: {N}
   Changes:

package/skills/qualia-learn/SKILL.md

@@ -46,17 +46,40 @@ What did you learn?
 3. Client preference — client-specific requirement
 ```
 
-### 2. Format Entry
+### 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:
 
 ```markdown
-### {Title} ({date})
+
+---
+
+### {Title}
+**ID:** {random 8-char hex, e.g. a3f7c1e9}
+**Date:** {ISO 8601, e.g. 2026-04-11}
 **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}
 ```
 
-### 3. Append to Knowledge File
+### 4. Append to Knowledge File
+
+Append-only — never overwrite the file, always add at the end:
 
 ```bash
 # Append to the right file
@@ -67,10 +90,10 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 - Fix → `~/.claude/knowledge/common-fixes.md`
 - Client pref → `~/.claude/knowledge/client-prefs.md`
 
-### 4. Confirm
+### 5. Confirm
 
 ```
-◆ Saved to {file}
+⬢ Saved to {file}
   "{title}"
 ```
 

package/skills/qualia-new/SKILL.md

@@ -100,7 +100,7 @@ options:
     description: "Gradients, rounded shapes, vibrant palette"
     preview: |
       ┌──────────────────────────────┐
-      │  ◆ ● ▲ ■  COLORFUL          │
+      │  ⬢ ● ▲ ■  COLORFUL          │
       │                              │
       │  ╭──────╮  ╭──────╮         │
       │  │ Card │  │ Card │         │
@@ -173,7 +173,7 @@ If there's an entry for this client, show it to the user: *"I have notes on {cli
 Present a summary:
 
 ```
-◆ QUALIA ► PROJECT SUMMARY
+⬢ QUALIA ▸ PROJECT SUMMARY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
   Project    {name}