qualia-framework-v2 2.6.0 → 2.8.0

package/README.md

@@ -49,10 +49,18 @@ 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
-- **3 rules** — security, frontend, deployment
+- **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)
+- **4 rules** — security, frontend, design-reference, deployment
 - **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
 
+## Supported Platforms
+
+Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Code.
+
+- Every hook and the status line are pure Node.js — no external bash, jq, or GNU coreutils required.
+- Skills are executed by Claude Code's own Bash tool (which Claude Code provides on all platforms, including Windows).
+- Tested on Fedora, EndeavourOS, macOS, and Windows 10/11.
+
 ## Why It Works
 
 ### Goal-Backward Verification
@@ -65,7 +73,7 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-The `settings.json` hooks are real ops engineering, not theoretical:
+All 8 hooks are real ops engineering, not theoretical. Highlights:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
 - **Branch guard** — Role-aware: owner can push to main, employees can't
@@ -94,9 +102,9 @@ 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)
-  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (auto-loaded by skills)
+  ├── 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 (loaded by plan/debug/new)
   ├── rules/           security.md, frontend.md, deployment.md
   ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
   ├── CLAUDE.md        global instructions (role-configured per team member)

package/bin/cli.js

@@ -94,13 +94,21 @@ function cmdUpdate() {
   console.log("");
 
   try {
-    // Pull latest and reinstall with saved code
-    execSync(
-      `npx qualia-framework-v2@latest install <<< "${cfg.code}"`,
-      { stdio: "inherit", shell: true, timeout: 60000 }
-    );
+    const { spawnSync } = require("child_process");
+    const r = spawnSync("npx", ["qualia-framework-v2@latest", "install"], {
+      input: cfg.code + "\n",
+      stdio: ["pipe", "inherit", "inherit"],
+      shell: process.platform === "win32",  // npx is a .cmd shim on Windows — must go through shell
+      timeout: 120000,
+      encoding: "utf8",
+    });
+    if (r.status !== 0) {
+      console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework-v2@latest install`);
+      process.exit(1);
+    }
   } catch (e) {
-    console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework-v2@latest install`);
+    console.log(`  ${RED}✗${RESET} Update failed: ${e.message}`);
+    console.log(`  ${DIM}Run manually:${RESET} npx qualia-framework-v2@latest install`);
     process.exit(1);
   }
 }

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) {
@@ -160,12 +170,11 @@ async function main() {
   // ─── Status line ───────────────────────────────────────
   log(`${WHITE}Status line${RESET}`);
   try {
-    const slDest = path.join(CLAUDE_DIR, "statusline.sh");
-    copy(path.join(FRAMEWORK_DIR, "statusline.sh"), slDest);
-    fs.chmodSync(slDest, 0o755);
-    ok("statusline.sh");
+    const slDest = path.join(CLAUDE_DIR, "bin", "statusline.js");
+    copy(path.join(FRAMEWORK_DIR, "bin", "statusline.js"), slDest);
+    ok("statusline.js");
   } catch (e) {
-    warn(`statusline.sh — ${e.message}`);
+    warn(`statusline.js — ${e.message}`);
   }
 
   // ─── Templates ─────────────────────────────────────────
@@ -214,6 +223,11 @@ async function main() {
     );
     fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
     ok("qualia-ui.js (cosmetics library)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "statusline.js"),
+      path.join(binDest, "statusline.js")
+    );
+    ok("statusline.js (status bar renderer)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -293,7 +307,7 @@ async function main() {
   // Status line
   settings.statusLine = {
     type: "command",
-    command: "~/.claude/statusline.sh",
+    command: `node "${path.join(CLAUDE_DIR, "bin", "statusline.js")}"`,
   };
 
   // Spinner
@@ -331,8 +345,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 +357,7 @@ async function main() {
         hooks: [
           {
             type: "command",
-            command: `${hd}/session-start.sh`,
+            command: nodeCmd("session-start.js"),
             timeout: 5,
           },
         ],
@@ -352,28 +369,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 +401,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,25 +421,13 @@ async function main() {
         hooks: [
           {
             type: "command",
-            command: `${hd}/pre-compact.sh`,
+            command: nodeCmd("pre-compact.js"),
             timeout: 15,
             statusMessage: "◆ Saving state...",
           },
         ],
       },
     ],
-    SubagentStart: [
-      {
-        matcher: ".*",
-        hooks: [
-          {
-            type: "command",
-            command:
-              'echo \'{"additionalContext": "◆ Qualia agent spawned"}\'',
-          },
-        ],
-      },
-    ],
   };
 
   // Permissions
@@ -436,8 +441,6 @@ async function main() {
     ];
   }
 
-  settings.effortLevel = "high";
-
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
   ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
@@ -454,7 +457,7 @@ async function main() {
   console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
   console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
   console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}2${RESET} ${DIM}(state.js, qualia-ui.js)${RESET}`);
+  console.log(`  Scripts:      ${WHITE}3${RESET} ${DIM}(state.js, qualia-ui.js, statusline.js)${RESET}`);
   console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
   console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);

package/bin/qualia-ui.js

@@ -20,7 +20,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const { spawnSync } = require("child_process");
 
 // ─── Colors ──────────────────────────────────────────────
 const TEAL = "\x1b[38;2;0;206;209m";
@@ -64,11 +64,14 @@ const ACTIONS = {
 // ─── State Reading ───────────────────────────────────────
 function readState() {
   try {
-    const out = execSync(`node ${path.join(os.homedir(), ".claude", "bin", "state.js")} check 2>/dev/null`, {
+    const statePath = path.join(os.homedir(), ".claude", "bin", "state.js");
+    const r = spawnSync(process.execPath, [statePath, "check"], {
       encoding: "utf8",
       timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
     });
-    return JSON.parse(out);
+    if (r.status !== 0 || !r.stdout) return null;
+    return JSON.parse(r.stdout);
   } catch {
     return null;
   }

package/bin/statusline.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Qualia status line — teal branded, shows phase + context + git.
+// Pure Node.js port of the original statusline.sh. Cross-platform
+// (Windows/macOS/Linux). No jq, no GNU stat, no /tmp hardcoding.
+//
+// Reads JSON from stdin (Claude Code status line schema), prints
+// two ANSI-formatted lines to stdout. Never throws — every section
+// is wrapped so missing data degrades gracefully.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// ─── Colors (matches bin/qualia-ui.js palette) ───────────
+const TEAL = "\x1b[38;2;0;206;209m";
+const TEAL_GLOW = "\x1b[38;2;0;170;175m";
+const TEAL_DIM = "\x1b[38;2;0;130;135m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const DIM = "\x1b[38;2;80;90;100m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const RESET = "\x1b[0m";
+
+// ─── Read input ──────────────────────────────────────────
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+
+function pick(obj, keypath, fallback) {
+  try {
+    let cur = obj;
+    for (const k of keypath.split(".")) {
+      if (cur == null) return fallback;
+      cur = cur[k];
+    }
+    return cur == null ? fallback : cur;
+  } catch {
+    return fallback;
+  }
+}
+
+const MODEL = String(pick(input, "model.display_name", ""));
+const DIR = String(pick(input, "workspace.current_dir", process.cwd()));
+const PCT_RAW = Number(pick(input, "context_window.used_percentage", 0)) || 0;
+const PCT = Math.floor(PCT_RAW);
+const COST = Number(pick(input, "cost.total_cost_usd", 0)) || 0;
+const DURATION_MS = Number(pick(input, "cost.total_duration_ms", 0)) || 0;
+const AGENT = String(pick(input, "agent.name", "") || "");
+const WORKTREE = String(pick(input, "worktree.name", "") || "");
+
+// ─── Context bar ─────────────────────────────────────────
+let BAR = "";
+let BAR_COLOR = TEAL;
+try {
+  if (PCT >= 80) BAR_COLOR = RED;
+  else if (PCT >= 50) BAR_COLOR = YELLOW;
+  else BAR_COLOR = TEAL;
+
+  const BAR_WIDTH = 10;
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.floor((PCT * BAR_WIDTH) / 100)));
+  const empty = BAR_WIDTH - filled;
+  BAR = "━".repeat(filled) + "╌".repeat(empty);
+} catch {
+  BAR = "╌".repeat(10);
+}
+
+// ─── Git branch (cached, cross-platform) ─────────────────
+let BRANCH = "";
+let CHANGES = 0;
+try {
+  const username = (os.userInfo().username || "anon").replace(/[^a-zA-Z0-9_-]/g, "_");
+  const cacheFile = path.join(os.tmpdir(), `qualia-git-cache-${username}`);
+
+  let fresh = false;
+  try {
+    const st = fs.statSync(cacheFile);
+    if (Date.now() - st.mtimeMs <= 3000) fresh = true;
+  } catch {
+    fresh = false;
+  }
+
+  if (!fresh) {
+    let branch = "";
+    let changes = 0;
+    try {
+      const dirCheck = spawnSync("git", ["rev-parse", "--git-dir"], {
+        cwd: DIR,
+        encoding: "utf8",
+        timeout: 1000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (dirCheck.status === 0) {
+        const br = spawnSync("git", ["branch", "--show-current"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (br.status === 0) branch = (br.stdout || "").trim();
+
+        const st = spawnSync("git", ["status", "--porcelain"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (st.status === 0) {
+          const out = (st.stdout || "").trim();
+          changes = out ? out.split("\n").length : 0;
+        }
+      }
+    } catch {}
+    try {
+      fs.writeFileSync(cacheFile, `${branch}|${changes}`);
+    } catch {}
+  }
+
+  try {
+    const cached = fs.readFileSync(cacheFile, "utf8");
+    const [b, c] = cached.split("|");
+    BRANCH = b || "";
+    CHANGES = parseInt(c, 10) || 0;
+  } catch {}
+} catch {}
+
+// ─── Phase info from .planning/tracking.json ─────────────
+let PHASE_INFO = "";
+try {
+  const trackingPath = path.join(DIR, ".planning", "tracking.json");
+  if (fs.existsSync(trackingPath)) {
+    const tracking = JSON.parse(fs.readFileSync(trackingPath, "utf8"));
+    const phase = Number(tracking.phase || 0) || 0;
+    const total = Number(tracking.total_phases || 0) || 0;
+    const status = String(tracking.status || "");
+    if (total > 0) {
+      const pdone = Math.floor((phase * 100) / total);
+      const pfill = Math.max(0, Math.min(4, Math.floor(pdone / 25)));
+      const pempt = 4 - pfill;
+      const pbar = "●".repeat(pfill) + "○".repeat(pempt);
+      PHASE_INFO = `${TEAL}${pbar}${RESET} ${WHITE}P${phase}/${total}${RESET} ${TEAL_GLOW}${status}${RESET}`;
+    }
+  }
+} catch {}
+
+// ─── Duration ────────────────────────────────────────────
+let DUR = "0s";
+try {
+  if (DURATION_MS >= 60000) {
+    DUR = `${Math.floor(DURATION_MS / 60000)}m`;
+  } else {
+    DUR = `${Math.floor(DURATION_MS / 1000)}s`;
+  }
+} catch {}
+
+// ─── Cost ────────────────────────────────────────────────
+let COST_FMT = "$0.00";
+try {
+  COST_FMT = `$${COST.toFixed(2)}`;
+} catch {}
+
+// ─── Line 1: Project + Git + Agent + Worktree + Phase ────
+let LINE1 = "";
+try {
+  const dirBase = path.basename(DIR) || DIR;
+  LINE1 = `${TEAL}◆${RESET} ${WHITE}${dirBase}${RESET}`;
+  if (BRANCH) {
+    if (CHANGES > 0) {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET} ${YELLOW}~${CHANGES}${RESET}`;
+    } else {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET}`;
+    }
+  }
+  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}`;
+} catch {
+  LINE1 = `${TEAL}◆${RESET} ${WHITE}qualia${RESET}`;
+}
+
+// ─── Line 2: Context bar + Cost + Duration + Model ───────
+let LINE2 = "";
+try {
+  LINE2 =
+    `${BAR_COLOR}${BAR}${RESET} ${DIM}${PCT}%${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${COST_FMT}${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${DUR}${RESET} ` +
+    `${DIM}│${RESET} ${TEAL_DIM}${MODEL}${RESET}`;
+} catch {
+  LINE2 = `${DIM}${PCT}%${RESET}`;
+}
+
+process.stdout.write(LINE1 + "\n");
+process.stdout.write(LINE2 + "\n");

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);