qualia-framework-v2 2.6.0 → 2.7.0

package/README.md

@@ -49,10 +49,14 @@ See `guide.md` for the full developer guide.
 
 - **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
+- **8 hooks** — session start, branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
 - **3 rules** — security, frontend, deployment
 - **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
 
+## Supported Platforms
+
+Works on **Windows 10/11, macOS, and Linux** (all distros). The only requirement is Node.js 18+. No Git Bash, no WSL, no bash dependency — every hook is pure Node.js.
+
 ## Why It Works
 
 ### Goal-Backward Verification
@@ -94,8 +98,8 @@ npx qualia-framework-v2 install
 ~/.claude/
   ├── 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)
+  ├── 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 (auto-loaded by skills)
   ├── rules/           security.md, frontend.md, deployment.md
   ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md

package/bin/install.js

@@ -146,10 +146,20 @@ async function main() {
   const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
   const hooksDest = path.join(CLAUDE_DIR, "hooks");
   if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
+  // Clean up legacy .sh hooks from previous v2.5/v2.6 installs so no orphans
+  // remain on disk after upgrading to the pure-Node v2.7+ hooks.
+  try {
+    for (const f of fs.readdirSync(hooksDest)) {
+      if (f.endsWith(".sh")) {
+        try { fs.unlinkSync(path.join(hooksDest, f)); } catch {}
+      }
+    }
+  } catch {}
   for (const file of fs.readdirSync(hooksSource)) {
     try {
       const dest = path.join(hooksDest, file);
       copy(path.join(hooksSource, file), dest);
+      // chmod is a no-op on Windows but harmless
       fs.chmodSync(dest, 0o755);
       ok(file);
     } catch (e) {
@@ -331,8 +341,11 @@ async function main() {
     ],
   };
 
-  // Hooks — full system
+  // Hooks — pure Node.js, cross-platform (Windows/macOS/Linux).
+  // Every hook command is `node <absolute-path-to-hook.js>` which avoids the
+  // bash/Git Bash requirement on Windows.
   const hd = path.join(CLAUDE_DIR, "hooks");
+  const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
   settings.hooks = {
     SessionStart: [
       {
@@ -340,7 +353,7 @@ async function main() {
         hooks: [
           {
             type: "command",
-            command: `${hd}/session-start.sh`,
+            command: nodeCmd("session-start.js"),
             timeout: 5,
           },
         ],
@@ -352,28 +365,28 @@ async function main() {
         hooks: [
           {
             type: "command",
-            command: `${hd}/auto-update.sh`,
+            command: nodeCmd("auto-update.js"),
             timeout: 5,
           },
           {
             type: "command",
             if: "Bash(git push*)",
-            command: `${hd}/branch-guard.sh`,
+            command: nodeCmd("branch-guard.js"),
             timeout: 10,
             statusMessage: "◆ Checking branch permissions...",
           },
           {
             type: "command",
             if: "Bash(git push*)",
-            command: `${hd}/pre-push.sh`,
+            command: nodeCmd("pre-push.js"),
             timeout: 15,
             statusMessage: "◆ Syncing tracking...",
           },
           {
             type: "command",
             if: "Bash(vercel --prod*)",
-            command: `${hd}/pre-deploy-gate.sh`,
-            timeout: 120,
+            command: nodeCmd("pre-deploy-gate.js"),
+            timeout: 180,
             statusMessage: "◆ Running quality gates...",
           },
         ],
@@ -384,14 +397,14 @@ async function main() {
           {
             type: "command",
             if: "Edit(*.env*)|Write(*.env*)",
-            command: `${hd}/block-env-edit.sh`,
+            command: nodeCmd("block-env-edit.js"),
             timeout: 5,
             statusMessage: "◆ Checking file permissions...",
           },
           {
             type: "command",
             if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
-            command: `${hd}/migration-guard.sh`,
+            command: nodeCmd("migration-guard.js"),
             timeout: 10,
             statusMessage: "◆ Checking migration safety...",
           },
@@ -404,7 +417,7 @@ async function main() {
         hooks: [
           {
             type: "command",
-            command: `${hd}/pre-compact.sh`,
+            command: nodeCmd("pre-compact.js"),
             timeout: 15,
             statusMessage: "◆ Saving state...",
           },

package/hooks/auto-update.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/auto-update.js — daily silent update check in the background.
+// PreToolUse hook on every Bash tool call. Fast path: single stat() call that
+// returns immediately if last check was <24h ago. Cross-platform.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawn, spawnSync } = require("child_process");
+
+const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+const CACHE_FILE = path.join(CLAUDE_DIR, ".qualia-last-update-check");
+const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
+const LOCK_FILE = path.join(CLAUDE_DIR, ".qualia-updating");
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+try {
+  // Fast path: recently checked
+  if (fs.existsSync(CACHE_FILE)) {
+    const last = Number(fs.readFileSync(CACHE_FILE, "utf8")) || 0;
+    if (Date.now() - last * 1000 < MAX_AGE_MS) {
+      process.exit(0);
+    }
+  }
+
+  // Already updating
+  if (fs.existsSync(LOCK_FILE)) {
+    process.exit(0);
+  }
+
+  // Update cache timestamp immediately to debounce concurrent checks
+  fs.writeFileSync(CACHE_FILE, String(Math.floor(Date.now() / 1000)));
+
+  // Read current config
+  let cfg = {};
+  try {
+    cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    process.exit(0);
+  }
+  if (!cfg.code || !cfg.version) process.exit(0);
+
+  // Fork the check-and-update into a detached background process so the hook
+  // returns immediately and Claude Code is never blocked.
+  const script = `
+    const fs = require("fs");
+    const path = require("path");
+    const { spawnSync } = require("child_process");
+    const CLAUDE_DIR = ${JSON.stringify(CLAUDE_DIR)};
+    const LOCK_FILE = ${JSON.stringify(LOCK_FILE)};
+    const CONFIG_FILE = ${JSON.stringify(CONFIG_FILE)};
+    const cfg = ${JSON.stringify(cfg)};
+    try {
+      fs.writeFileSync(LOCK_FILE, String(process.pid));
+      const r = spawnSync("npm", ["view", "qualia-framework-v2", "version"], {
+        encoding: "utf8",
+        timeout: 15000,
+        shell: process.platform === "win32",
+      });
+      const latest = ((r.stdout || "").trim());
+      if (!latest) { fs.unlinkSync(LOCK_FILE); return; }
+      const cmp = (a, b) => {
+        const pa = a.split(".").map(Number), pb = 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(latest, cfg.version) > 0) {
+        // Silent update — pipe the install code via stdin
+        const child = spawnSync("npx", ["qualia-framework-v2@latest", "install"], {
+          input: cfg.code + "\\n",
+          timeout: 120000,
+          stdio: ["pipe", "ignore", "ignore"],
+          shell: process.platform === "win32",
+        });
+      }
+    } catch {}
+    try { fs.unlinkSync(LOCK_FILE); } catch {}
+  `;
+
+  const child = spawn(process.execPath, ["-e", script], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+} catch {
+  // Silent — never block the tool call
+}
+
+process.exit(0);

package/hooks/block-env-edit.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/block-env-edit.js — prevent editing .env files.
+// PreToolUse hook on Edit/Write tool calls. Reads tool input as JSON on stdin.
+// Exits 2 to BLOCK the tool call. Exits 0 to allow it.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+const file = (input.tool_input && (input.tool_input.file_path || input.tool_input.command)) || "";
+
+// Match .env, .env.local, .env.production, .env.*, etc.
+// Normalize separators so Windows paths (C:\project\.env.local) also match.
+const normalized = String(file).replace(/\\/g, "/");
+
+if (/\.env(\.|$)/.test(normalized)) {
+  console.log("BLOCKED: Cannot edit environment files. Ask Fawzi to update secrets.");
+  process.exit(2);
+}
+
+process.exit(0);

package/hooks/branch-guard.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/branch-guard.js — block non-OWNER push to main/master.
+// PreToolUse hook on `git push*` commands. Reads role from
+// ~/.claude/.qualia-config.json (single source of truth).
+// Exits 1 to BLOCK. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const CONFIG = path.join(os.homedir(), ".claude", ".qualia-config.json");
+
+function fail(msg) {
+  console.log(msg);
+  process.exit(1);
+}
+
+let role = "";
+try {
+  const cfg = JSON.parse(fs.readFileSync(CONFIG, "utf8"));
+  role = cfg.role || "";
+} catch {
+  fail(`BLOCKED: ${CONFIG} missing or unreadable. Run: npx qualia-framework-v2 install`);
+}
+
+if (!role) {
+  fail(`BLOCKED: Cannot determine role from ${CONFIG}. Defaulting to deny.`);
+}
+
+// Ask git for the current branch --show-current. Works identically on Windows/macOS/Linux.
+const r = spawnSync("git", ["branch", "--show-current"], {
+  encoding: "utf8",
+  timeout: 3000,
+});
+const branch = ((r.stdout || "").trim());
+
+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);
+  }
+}
+
+process.exit(0);

package/hooks/migration-guard.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/migration-guard.js — catch dangerous SQL patterns in migrations.
+// PreToolUse hook on Edit/Write tool calls. Reads tool input as JSON on stdin.
+// Exits 2 to BLOCK. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+const ti = input.tool_input || {};
+const file = String(ti.file_path || "").replace(/\\/g, "/");
+const content = String(ti.content || ti.new_string || "");
+
+// Only inspect migration/SQL files
+if (!/migration|migrate|\.sql$/i.test(file)) {
+  process.exit(0);
+}
+
+const errors = [];
+
+// DROP TABLE without IF EXISTS
+if (/DROP\s+TABLE/i.test(content) && !/IF\s+EXISTS/i.test(content)) {
+  errors.push("DROP TABLE without IF EXISTS");
+}
+
+// DELETE without WHERE
+if (/DELETE\s+FROM/i.test(content) && !/WHERE/i.test(content)) {
+  errors.push("DELETE FROM without WHERE clause");
+}
+
+// TRUNCATE (almost always wrong in migrations)
+if (/TRUNCATE/i.test(content)) {
+  errors.push("TRUNCATE detected — are you sure?");
+}
+
+// CREATE TABLE without RLS
+if (/CREATE\s+TABLE/i.test(content) && !/ENABLE\s+ROW\s+LEVEL\s+SECURITY/i.test(content)) {
+  errors.push("CREATE TABLE without ENABLE ROW LEVEL SECURITY");
+}
+
+if (errors.length > 0) {
+  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.");
+  process.exit(2);
+}
+
+process.exit(0);

package/hooks/pre-compact.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-compact.js — commit STATE.md before context compaction.
+// PreCompact hook. Silent on failure — context compaction must never be blocked.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const STATE_FILE = path.join(".planning", "STATE.md");
+
+try {
+  if (fs.existsSync(STATE_FILE)) {
+    console.log("QUALIA: Saving state before compaction...");
+    // Check if STATE.md has uncommitted changes
+    const diff = spawnSync("git", ["diff", "--name-only", STATE_FILE], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    if ((diff.stdout || "").includes("STATE.md")) {
+      spawnSync("git", ["add", STATE_FILE], { timeout: 3000 });
+      spawnSync("git", ["commit", "-m", "state: pre-compaction save"], {
+        timeout: 5000,
+        stdio: "ignore",
+      });
+    }
+  }
+} catch {
+  // Silent — never block compaction
+}
+
+process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-deploy-gate.js — quality gates before production deploy.
+// PreToolUse hook on `vercel --prod*` commands. Runs tsc, lint, tests, build,
+// then scans for service_role leaks in client code.
+// Exits 1 to BLOCK deploy. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux). No `grep` or `find` — pure Node.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function runGate(label, cmd, args, { required = true } = {}) {
+  const r = spawnSync(cmd, args, {
+    stdio: "ignore",
+    timeout: 180000,
+    shell: process.platform === "win32",
+  });
+  if (r.status === 0) {
+    console.log(`  ✓ ${label}`);
+    return true;
+  }
+  if (required) {
+    console.log(`BLOCKED: ${label} errors. Fix before deploying.`);
+    process.exit(1);
+  }
+  return false;
+}
+
+function hasScript(name) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    return pkg.scripts && typeof pkg.scripts[name] === "string";
+  } catch {
+    return false;
+  }
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      walk(full, out);
+    } else if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function scanServiceRoleLeaks() {
+  const roots = ["app", "components", "src", "pages", "lib"];
+  const leaks = [];
+  for (const root of roots) {
+    for (const file of walk(root)) {
+      // Skip server-only files (convention: *.server.ts, server/ dirs)
+      if (/\.server\.|[\\/]server[\\/]/.test(file)) continue;
+      try {
+        const content = fs.readFileSync(file, "utf8");
+        if (/service_role/.test(content)) {
+          leaks.push(file);
+        }
+      } catch {}
+    }
+  }
+  return leaks;
+}
+
+console.log("◆ Pre-deploy gate...");
+
+// TypeScript
+if (fs.existsSync("tsconfig.json")) {
+  runGate("TypeScript", "npx", ["tsc", "--noEmit"]);
+}
+
+// Lint
+if (hasScript("lint")) {
+  runGate("Lint", "npm", ["run", "lint"]);
+}
+
+// Tests
+if (hasScript("test")) {
+  runGate("Tests", "npm", ["test"]);
+}
+
+// Build
+if (hasScript("build")) {
+  runGate("Build", "npm", ["run", "build"]);
+}
+
+// Security: no service_role in client code
+const leaks = scanServiceRoleLeaks();
+if (leaks.length > 0) {
+  console.log("BLOCKED: service_role found in client code. Remove before deploying.");
+  for (const f of leaks.slice(0, 10)) {
+    console.log(`  ✗ ${f}`);
+  }
+  process.exit(1);
+}
+console.log("  ✓ Security");
+console.log("◆ All gates passed.");
+
+process.exit(0);

package/hooks/pre-push.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-push.js — update tracking.json with last commit + timestamp.
+// PreToolUse hook on `git push*` commands. state.js handles phase/status sync;
+// this just stamps the file so the ERP sees fresh commit info on every push.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const TRACKING = path.join(".planning", "tracking.json");
+
+try {
+  if (fs.existsSync(TRACKING)) {
+    const r = spawnSync("git", ["log", "--oneline", "-1", "--format=%h"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    const lastCommit = ((r.stdout || "").trim());
+    const now = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
+    const t = JSON.parse(fs.readFileSync(TRACKING, "utf8"));
+    if (lastCommit) t.last_commit = lastCommit;
+    t.last_updated = now;
+    fs.writeFileSync(TRACKING, JSON.stringify(t, null, 2) + "\n");
+
+    spawnSync("git", ["add", TRACKING], { timeout: 3000 });
+  }
+} catch (err) {
+  process.stderr.write(`WARNING: tracking sync failed: ${err.message}\n`);
+}
+
+process.exit(0);

package/hooks/session-start.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/session-start.js — branded context panel on session start.
+// Cross-platform (Windows/macOS/Linux). Zero shell dependencies.
+//
+// CRITICAL: this hook must NEVER exit non-zero. Claude Code treats any non-zero
+// exit from a SessionStart hook as a "hook error" and shows a red banner. The
+// banner is purely informational — we'd rather render nothing than block a
+// session. Every call is wrapped in try/catch and we always exit 0 at the end.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+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";
+
+function runUi(...args) {
+  if (!fs.existsSync(UI)) return;
+  try {
+    spawnSync(process.execPath, [UI, ...args], {
+      stdio: "inherit",
+      timeout: 3000,
+    });
+  } catch {}
+}
+
+function getNextCommand() {
+  const stateJs = path.join(HOME, ".claude", "bin", "state.js");
+  if (!fs.existsSync(stateJs)) return "";
+  try {
+    const r = spawnSync(process.execPath, [stateJs, "check"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    if (!r.stdout) return "";
+    const j = JSON.parse(r.stdout);
+    return j.next_command || "";
+  } catch {
+    return "";
+  }
+}
+
+function fallbackText() {
+  // If qualia-ui.js is missing, emit plain text. Keeps the session informative
+  // even on a broken install.
+  if (fs.existsSync(STATE_FILE)) {
+    try {
+      const content = fs.readFileSync(STATE_FILE, "utf8");
+      const phase = (content.match(/^Phase:\s*(.+)$/m) || [])[1] || "—";
+      const status = (content.match(/^Status:\s*(.+)$/m) || [])[1] || "—";
+      console.log(`QUALIA: Project loaded. Phase: ${phase.trim()} | Status: ${status.trim()}`);
+      console.log("QUALIA: Run /qualia for next step.");
+    } catch {
+      console.log("QUALIA: Project detected but STATE.md could not be read.");
+    }
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    console.log("QUALIA: Handoff file found. Read .continue-here.md to resume.");
+  } else {
+    console.log("QUALIA: No project detected. Run /qualia-new to start.");
+  }
+}
+
+try {
+  if (!fs.existsSync(UI)) {
+    fallbackText();
+  } else if (fs.existsSync(STATE_FILE)) {
+    runUi("banner", "router");
+    const next = getNextCommand();
+    if (next) runUi("info", `Run ${next} to continue`);
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    runUi("banner", "router");
+    runUi("warn", "Handoff found — read .continue-here.md to resume");
+  } else {
+    runUi("banner", "router");
+    runUi("info", "No project detected. Run /qualia-new to start.");
+  }
+} catch {
+  // Deliberately silent — hook must never fail
+}
+
+process.exit(0);

package/package.json

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

package/tests/hooks.test.sh

@@ -1,10 +1,12 @@
 #!/bin/bash
-# Qualia Framework v2 — Hook Tests
+# Qualia Framework v2 — Hook Tests (cross-platform Node.js hooks)
 # Run: bash tests/hooks.test.sh
 
 PASS=0
 FAIL=0
-HOOKS_DIR="$(dirname "$0")/../hooks"
+# Resolve HOOKS_DIR to an ABSOLUTE path so `cd` inside subshells doesn't break it.
+HOOKS_DIR="$(cd "$(dirname "$0")/../hooks" && pwd)"
+NODE="${NODE:-node}"
 
 assert_exit() {
   local name="$1" expected="$2" actual="$3"
@@ -17,139 +19,189 @@ assert_exit() {
   fi
 }
 
-echo "=== Hook Tests ==="
+echo "=== Hook Tests (Node.js) ==="
 echo ""
 
-# --- block-env-edit.sh ---
+# --- All hooks are syntactically valid Node.js ---
+echo "syntax:"
+for f in "$HOOKS_DIR"/*.js; do
+  if $NODE -c "$f" 2>/dev/null; then
+    echo "  ✓ $(basename "$f")"
+    PASS=$((PASS + 1))
+  else
+    echo "  ✗ $(basename "$f")"
+    FAIL=$((FAIL + 1))
+  fi
+done
+
+# --- block-env-edit.js ---
+echo ""
 echo "block-env-edit:"
 
-echo '{"tool_input":{"file_path":".env.local"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":".env.local"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
 assert_exit "blocks .env.local" 2 $?
 
-echo '{"tool_input":{"file_path":".env.production"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":".env.production"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
 assert_exit "blocks .env.production" 2 $?
 
-echo '{"tool_input":{"file_path":".env"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":".env"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
 assert_exit "blocks .env" 2 $?
 
-echo '{"tool_input":{"file_path":"src/app.tsx"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+# Windows-style path with backslashes (normalized by the hook)
+echo '{"tool_input":{"file_path":"C:\\project\\.env.local"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
+assert_exit "blocks windows .env.local" 2 $?
+
+echo '{"tool_input":{"file_path":"src/app.tsx"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
 assert_exit "allows src/app.tsx" 0 $?
 
-echo '{"tool_input":{"file_path":"components/Footer.tsx"}}' | bash "$HOOKS_DIR/block-env-edit.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"components/Footer.tsx"}}' | $NODE "$HOOKS_DIR/block-env-edit.js" > /dev/null 2>&1
 assert_exit "allows components/Footer.tsx" 0 $?
 
-# --- migration-guard.sh ---
+# --- migration-guard.js ---
 echo ""
 echo "migration-guard:"
 
-echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE users;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "blocks DROP TABLE without IF EXISTS" 2 $?
 
-echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE IF EXISTS old_users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/001.sql","content":"DROP TABLE IF EXISTS old_users;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "allows DROP TABLE IF EXISTS" 0 $?
 
-echo '{"tool_input":{"file_path":"migrations/002.sql","content":"DELETE FROM users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/002.sql","content":"DELETE FROM users;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "blocks DELETE without WHERE" 2 $?
 
-echo '{"tool_input":{"file_path":"migrations/003.sql","content":"TRUNCATE TABLE sessions;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/003.sql","content":"TRUNCATE TABLE sessions;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "blocks TRUNCATE" 2 $?
 
-echo '{"tool_input":{"file_path":"migrations/004.sql","content":"CREATE TABLE users (id uuid);"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/004.sql","content":"CREATE TABLE users (id uuid);"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "blocks CREATE TABLE without RLS" 2 $?
 
-echo '{"tool_input":{"file_path":"migrations/005.sql","content":"ALTER TABLE users ADD COLUMN email text;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"migrations/005.sql","content":"ALTER TABLE users ADD COLUMN email text;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "allows safe ALTER TABLE" 0 $?
 
-echo '{"tool_input":{"file_path":"src/app.tsx","content":"DROP TABLE users;"}}' | bash "$HOOKS_DIR/migration-guard.sh" > /dev/null 2>&1
+echo '{"tool_input":{"file_path":"src/app.tsx","content":"DROP TABLE users;"}}' | $NODE "$HOOKS_DIR/migration-guard.js" > /dev/null 2>&1
 assert_exit "skips non-migration files" 0 $?
 
-# --- branch-guard.sh ---
+# --- branch-guard.js (grep-based — full run needs git + real config) ---
 echo ""
 echo "branch-guard:"
 
-if [ -f "$HOOKS_DIR/branch-guard.sh" ]; then
-  echo "  ✓ branch-guard.sh exists"
+if grep -q '.qualia-config.json' "$HOOKS_DIR/branch-guard.js"; then
+  echo "  ✓ reads role from .qualia-config.json"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ branch-guard.sh missing"
+  echo "  ✗ not reading from .qualia-config.json"
   FAIL=$((FAIL + 1))
 fi
 
-if grep -q 'ROLE' "$HOOKS_DIR/branch-guard.sh"; then
-  echo "  ✓ checks ROLE variable"
+if grep -q 'branch --show-current' "$HOOKS_DIR/branch-guard.js"; then
+  echo "  ✓ checks current git branch"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing ROLE check"
+  echo "  ✗ missing branch check"
   FAIL=$((FAIL + 1))
 fi
 
-if grep -q 'z "$ROLE"' "$HOOKS_DIR/branch-guard.sh"; then
-  echo "  ✓ defaults to deny on missing ROLE"
+if grep -q 'OWNER' "$HOOKS_DIR/branch-guard.js"; then
+  echo "  ✓ enforces OWNER role"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing empty-ROLE deny"
+  echo "  ✗ missing OWNER check"
   FAIL=$((FAIL + 1))
 fi
 
-# --- pre-push.sh ---
+# --- pre-push.js ---
 echo ""
 echo "pre-push:"
 
-if grep -q 'command -v node' "$HOOKS_DIR/pre-push.sh"; then
-  echo "  ✓ checks for node availability"
+if grep -q 'tracking.json' "$HOOKS_DIR/pre-push.js"; then
+  echo "  ✓ updates tracking.json"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing node check"
+  echo "  ✗ missing tracking.json update"
   FAIL=$((FAIL + 1))
 fi
 
-if grep -q 'tracking sync failed' "$HOOKS_DIR/pre-push.sh"; then
-  echo "  ✓ captures tracking sync errors"
+if grep -q 'last_commit' "$HOOKS_DIR/pre-push.js"; then
+  echo "  ✓ stamps last_commit"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing tracking sync error capture"
+  echo "  ✗ missing last_commit stamp"
   FAIL=$((FAIL + 1))
 fi
 
-# --- branch-guard reads from .qualia-config.json ---
-echo ""
-echo "branch-guard config source:"
-
-if grep -q 'qualia-config.json' "$HOOKS_DIR/branch-guard.sh"; then
-  echo "  ✓ reads role from .qualia-config.json"
-  PASS=$((PASS + 1))
-else
-  echo "  ✗ not reading from .qualia-config.json"
-  FAIL=$((FAIL + 1))
-fi
+# Run pre-push.js in a dir with no tracking.json — must exit 0 cleanly
+TMP=$(mktemp -d)
+(cd "$TMP" && $NODE "$HOOKS_DIR/pre-push.js" >/dev/null 2>&1)
+assert_exit "exits 0 with no tracking.json" 0 $?
+rm -rf "$TMP"
 
-# --- pre-deploy-gate.sh ---
+# --- pre-deploy-gate.js ---
 echo ""
 echo "pre-deploy-gate:"
 
-if [ -f "$HOOKS_DIR/pre-deploy-gate.sh" ]; then
-  echo "  ✓ pre-deploy-gate.sh exists"
+if grep -q 'tsc' "$HOOKS_DIR/pre-deploy-gate.js"; then
+  echo "  ✓ runs TypeScript check"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ pre-deploy-gate.sh missing"
+  echo "  ✗ missing TypeScript check"
   FAIL=$((FAIL + 1))
 fi
 
-if grep -q 'tsc --noEmit' "$HOOKS_DIR/pre-deploy-gate.sh"; then
-  echo "  ✓ runs TypeScript check"
+if grep -q 'service_role' "$HOOKS_DIR/pre-deploy-gate.js"; then
+  echo "  ✓ checks for service_role leaks"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing TypeScript check"
+  echo "  ✗ missing service_role check"
   FAIL=$((FAIL + 1))
 fi
 
-if grep -q 'service_role' "$HOOKS_DIR/pre-deploy-gate.sh"; then
-  echo "  ✓ checks for service_role leaks"
+# --- session-start.js — must exit 0 always ---
+echo ""
+echo "session-start:"
+
+TMP=$(mktemp -d)
+(cd "$TMP" && $NODE "$HOOKS_DIR/session-start.js" >/dev/null 2>&1)
+assert_exit "exits 0 with no project" 0 $?
+
+# Simulate a project with STATE.md
+mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/STATE.md" <<'EOF'
+# Project State
+Phase: 1 of 3 — Foundation
+Status: setup
+EOF
+(cd "$TMP" && $NODE "$HOOKS_DIR/session-start.js" >/dev/null 2>&1)
+assert_exit "exits 0 with STATE.md" 0 $?
+rm -rf "$TMP"
+
+# --- pre-compact.js ---
+echo ""
+echo "pre-compact:"
+
+TMP=$(mktemp -d)
+(cd "$TMP" && $NODE "$HOOKS_DIR/pre-compact.js" >/dev/null 2>&1)
+assert_exit "exits 0 with no STATE.md" 0 $?
+rm -rf "$TMP"
+
+# --- auto-update.js ---
+echo ""
+echo "auto-update:"
+
+TMP=$(mktemp -d)
+mkdir -p "$TMP/.claude"
+echo '{"code":"QS-FAWZI-01","version":"99.99.99"}' > "$TMP/.claude/.qualia-config.json"
+HOME="$TMP" $NODE "$HOOKS_DIR/auto-update.js" >/dev/null 2>&1
+assert_exit "exits 0 (fast path)" 0 $?
+# Should now have cache file
+if [ -f "$TMP/.claude/.qualia-last-update-check" ]; then
+  echo "  ✓ writes cache timestamp"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ missing service_role check"
+  echo "  ✗ missing cache timestamp"
   FAIL=$((FAIL + 1))
 fi
+rm -rf "$TMP"
 
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="

package/hooks/auto-update.sh

@@ -1,56 +0,0 @@
-#!/bin/bash
-# Qualia auto-update — checks once per day, updates silently in background
-# Runs as PreToolUse hook. Cached so it's a no-op most of the time.
-
-CLAUDE_DIR="$HOME/.claude"
-CACHE_FILE="$CLAUDE_DIR/.qualia-last-update-check"
-CONFIG_FILE="$CLAUDE_DIR/.qualia-config.json"
-LOCK_FILE="$CLAUDE_DIR/.qualia-updating"
-MAX_AGE=86400  # 24 hours in seconds
-
-# Exit fast if recently checked (most common path — single stat call)
-if [ -f "$CACHE_FILE" ]; then
-  LAST_CHECK=$(cat "$CACHE_FILE" 2>/dev/null || echo 0)
-  NOW=$(date +%s)
-  AGE=$((NOW - LAST_CHECK))
-  if [ "$AGE" -lt "$MAX_AGE" ]; then
-    exit 0
-  fi
-fi
-
-# Exit if already updating
-[ -f "$LOCK_FILE" ] && exit 0
-
-# Update cache timestamp immediately (prevents concurrent checks)
-date +%s > "$CACHE_FILE"
-
-# Run the actual check + update in background so we don't block the user
-(
-  trap 'rm -f "$LOCK_FILE"' EXIT
-  touch "$LOCK_FILE"
-
-  # Get installed version
-  INSTALLED=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$CONFIG_FILE','utf8')).version)}catch{console.log('0.0.0')}" 2>/dev/null)
-  [ -z "$INSTALLED" ] && INSTALLED="0.0.0"
-
-  # Get latest from npm (5s timeout)
-  LATEST=$(npm view qualia-framework-v2 version 2>/dev/null)
-  [ -z "$LATEST" ] && exit 0
-
-  # Compare versions
-  NEEDS_UPDATE=$(node -e "
-    const a='$LATEST'.split('.').map(Number), b='$INSTALLED'.split('.').map(Number);
-    for(let i=0;i<3;i++){if(a[i]>b[i]){console.log('yes');process.exit()}if(a[i]<b[i]){process.exit()}}
-  " 2>/dev/null)
-
-  if [ "$NEEDS_UPDATE" = "yes" ]; then
-    # Get saved install code
-    CODE=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$CONFIG_FILE','utf8')).code)}catch{}" 2>/dev/null)
-    [ -z "$CODE" ] && exit 0
-
-    # Run silent update
-    npx qualia-framework-v2@latest install <<< "$CODE" > /dev/null 2>&1
-  fi
-) &
-
-exit 0

package/hooks/block-env-edit.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-# Prevent Claude from editing .env files
-# Claude Code hooks receive JSON on stdin with tool_input.file_path
-
-INPUT=$(cat)
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.command // ""' 2>/dev/null)
-
-if [[ "$FILE" == *.env* ]] || [[ "$FILE" == *".env.local"* ]] || [[ "$FILE" == *".env.production"* ]]; then
-  echo "BLOCKED: Cannot edit environment files. Ask Fawzi to update secrets."
-  exit 2
-fi

package/hooks/branch-guard.sh

@@ -1,27 +0,0 @@
-#!/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)
-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 from $CONFIG. Defaulting to deny."
-  exit 1
-fi
-
-if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
-  if [[ "$ROLE" != "OWNER" ]]; then
-    echo "BLOCKED: Employees cannot push to $BRANCH. Create a feature branch first."
-    echo "Run: git checkout -b feature/your-feature-name"
-    exit 1
-  fi
-fi

package/hooks/migration-guard.sh

@@ -1,43 +0,0 @@
-#!/bin/bash
-# Catch dangerous SQL patterns in migration files
-# Runs as PreToolUse hook on Write/Edit of migration files
-
-INPUT=$(cat)
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
-CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
-
-# Only check migration/SQL files
-case "$FILE" in
-  *migration*|*migrate*|*.sql) ;;
-  *) exit 0 ;;
-esac
-
-ERRORS=""
-
-# DROP TABLE without safeguards
-if echo "$CONTENT" | grep -qi "DROP TABLE" && ! echo "$CONTENT" | grep -qi "IF EXISTS"; then
-  ERRORS="${ERRORS}\n  ✗ DROP TABLE without IF EXISTS"
-fi
-
-# DELETE without WHERE
-if echo "$CONTENT" | grep -qi "DELETE FROM" && ! echo "$CONTENT" | grep -qi "WHERE"; then
-  ERRORS="${ERRORS}\n  ✗ DELETE FROM without WHERE clause"
-fi
-
-# TRUNCATE (almost always wrong in migrations)
-if echo "$CONTENT" | grep -qi "TRUNCATE"; then
-  ERRORS="${ERRORS}\n  ✗ TRUNCATE detected — are you sure?"
-fi
-
-# CREATE TABLE without RLS
-if echo "$CONTENT" | grep -qi "CREATE TABLE" && ! echo "$CONTENT" | grep -qi "ENABLE ROW LEVEL SECURITY"; then
-  ERRORS="${ERRORS}\n  ✗ CREATE TABLE without ENABLE ROW LEVEL SECURITY"
-fi
-
-if [ -n "$ERRORS" ]; then
-  echo "◆ Migration guard — dangerous patterns found:"
-  echo -e "$ERRORS"
-  echo ""
-  echo "Fix these before proceeding. If intentional, ask Fawzi to approve."
-  exit 2
-fi

package/hooks/pre-compact.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-# Save state before context compression
-
-if [ -f ".planning/STATE.md" ]; then
-  echo "QUALIA: Saving state before compaction..."
-  # State is in git — just ensure it's committed
-  if git diff --name-only .planning/STATE.md 2>/dev/null | grep -q STATE; then
-    git add .planning/STATE.md
-    git commit -m "state: pre-compaction save" 2>/dev/null
-  fi
-fi

package/hooks/pre-deploy-gate.sh

@@ -1,50 +0,0 @@
-#!/bin/bash
-# Quality gates before production deploy
-
-echo "◆ Pre-deploy gate..."
-
-# TypeScript check
-if [ -f "tsconfig.json" ]; then
-  if ! npx tsc --noEmit 2>/dev/null; then
-    echo "BLOCKED: TypeScript errors. Fix before deploying."
-    exit 1
-  fi
-  echo "  ✓ TypeScript"
-fi
-
-# Lint check
-if [ -f "package.json" ] && grep -q '"lint"' package.json; then
-  if ! npm run lint 2>/dev/null; then
-    echo "BLOCKED: Lint errors. Fix before deploying."
-    exit 1
-  fi
-  echo "  ✓ Lint"
-fi
-
-# Test check
-if [ -f "package.json" ] && grep -q '"test"' package.json; then
-  if ! npm test 2>/dev/null; then
-    echo "BLOCKED: Tests failed. Fix before deploying."
-    exit 1
-  fi
-  echo "  ✓ Tests"
-fi
-
-# Build check
-if [ -f "package.json" ] && grep -q '"build"' package.json; then
-  if ! npm run build 2>/dev/null; then
-    echo "BLOCKED: Build failed. Fix before deploying."
-    exit 1
-  fi
-  echo "  ✓ Build"
-fi
-
-# Security: no service_role in client code
-LEAKS=$(grep -r "service_role" app/ components/ src/ 2>/dev/null | grep -v node_modules | grep -v ".server." | wc -l)
-if [ "$LEAKS" -gt 0 ]; then
-  echo "BLOCKED: service_role found in client code. Remove before deploying."
-  exit 1
-fi
-echo "  ✓ Security"
-
-echo "◆ All gates passed."

package/hooks/pre-push.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-# Update tracking.json timestamps before push
-# State.js handles phase/status sync — this just updates commit hash and timestamp
-
-TRACKING=".planning/tracking.json"
-
-if [ -f "$TRACKING" ]; then
-  if ! command -v node &>/dev/null; then
-    echo "WARNING: node not found, skipping tracking sync" >&2
-    exit 0
-  fi
-
-  LAST_COMMIT=$(git log --oneline -1 --format="%h" 2>/dev/null)
-  NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-  node -e "
-    const fs = require('fs');
-    try {
-      const t = JSON.parse(fs.readFileSync('$TRACKING', 'utf8'));
-      t.last_commit = '${LAST_COMMIT}';
-      t.last_updated = '${NOW}';
-      fs.writeFileSync('$TRACKING', JSON.stringify(t, null, 2) + '\n');
-    } catch (e) {
-      process.stderr.write('WARNING: tracking sync failed: ' + e.message + '\n');
-    }
-  "
-  git add "$TRACKING" 2>/dev/null
-fi

package/hooks/session-start.sh

@@ -1,35 +0,0 @@
-#!/bin/bash
-# Qualia session start — show branded context panel on every new session.
-# Delegates to qualia-ui.js so formatting matches the rest of the framework.
-
-UI="$HOME/.claude/bin/qualia-ui.js"
-STATE=".planning/STATE.md"
-
-# Fallback if qualia-ui.js is missing (first install before mirror)
-if [ ! -f "$UI" ]; then
-  if [ -f "$STATE" ]; then
-    PHASE=$(grep "^Phase:" "$STATE" 2>/dev/null | head -1)
-    STATUS=$(grep "^Status:" "$STATE" 2>/dev/null | head -1)
-    echo "QUALIA: Project loaded. $PHASE | $STATUS"
-    echo "QUALIA: Run /qualia for next step."
-  elif [ -f ".continue-here.md" ]; then
-    echo "QUALIA: Handoff file found. Read .continue-here.md to resume."
-  else
-    echo "QUALIA: No project detected. Run /qualia-new to start."
-  fi
-  exit 0
-fi
-
-# Branded banner for every session start
-if [ -f "$STATE" ]; then
-  node "$UI" banner router
-  # Read next command from state.js and suggest it
-  NEXT=$(node "$HOME/.claude/bin/state.js" check 2>/dev/null | node -e "try{let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const j=JSON.parse(d);process.stdout.write(j.next_command||'')})}" 2>/dev/null)
-  [ -n "$NEXT" ] && node "$UI" info "Run $NEXT to continue"
-elif [ -f ".continue-here.md" ]; then
-  node "$UI" banner router
-  node "$UI" warn "Handoff found — read .continue-here.md to resume"
-else
-  node "$UI" banner router
-  node "$UI" info "No project detected. Run /qualia-new to start."
-fi