qualia-framework-v2 2.5.0 → 2.7.0

package/bin/qualia-ui.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Qualia UI — consistent banners, context panels, status for every skill.
+// Zero dependencies. Reads state.js + .qualia-config.json for context.
+//
+// Commands:
+//   banner <action> [phase] [subtitle]  — full header with context panel
+//   context                              — just the context panel
+//   divider                              — horizontal rule
+//   ok <message>                         — green check line
+//   fail <message>                       — red cross line
+//   warn <message>                       — yellow bang line
+//   info <message>                       — blue dot line
+//   spawn <agent> <description>          — spawning a subagent
+//   wave <N> <total> <task-count>        — wave header for /qualia-build
+//   task <N> <title>                     — task line (pending)
+//   done <N> <title> [commit]            — task line (completed)
+//   next <command>                       — "Run: /qualia-X" footer
+//   end <status> [next-command]          — closing banner with optional next
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+// ─── Colors ──────────────────────────────────────────────
+const TEAL = "\x1b[38;2;0;206;209m";
+const TEAL_DIM = "\x1b[38;2;0;140;145m";
+const DIM = "\x1b[38;2;100;110;120m";
+const DIM2 = "\x1b[38;2;70;80;90m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const BLUE = "\x1b[38;2;96;165;250m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+const RULE = "━".repeat(42);
+const RULE_DIM = `${DIM2}${RULE}${RESET}`;
+
+// ─── Action Labels ───────────────────────────────────────
+const ACTIONS = {
+  router:     { label: "SMART ROUTER",     glyph: "◆" },
+  new:        { label: "NEW PROJECT",      glyph: "◆" },
+  plan:       { label: "PLANNING",         glyph: "◇" },
+  build:      { label: "BUILDING",         glyph: "◈" },
+  verify:     { label: "VERIFYING",        glyph: "◉" },
+  polish:     { label: "POLISHING",        glyph: "◆" },
+  ship:       { label: "SHIPPING",         glyph: "▲" },
+  handoff:    { label: "HANDING OFF",      glyph: "▶" },
+  report:     { label: "SESSION REPORT",   glyph: "◆" },
+  debug:      { label: "DEBUGGING",        glyph: "◊" },
+  learn:      { label: "LEARNING",         glyph: "◆" },
+  pause:      { label: "PAUSING",          glyph: "◆" },
+  resume:     { label: "RESUMING",         glyph: "◆" },
+  review:     { label: "REVIEW",           glyph: "◆" },
+  design:     { label: "DESIGN PASS",      glyph: "◆" },
+  quick:      { label: "QUICK FIX",        glyph: "◆" },
+  task:       { label: "TASK",             glyph: "◆" },
+  "skill-new": { label: "NEW SKILL",       glyph: "◆" },
+  gaps:       { label: "GAP CLOSURE",      glyph: "◇" },
+};
+
+// ─── State Reading ───────────────────────────────────────
+function readState() {
+  try {
+    const out = execSync(`node ${path.join(os.homedir(), ".claude", "bin", "state.js")} check 2>/dev/null`, {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+function readConfig() {
+  try {
+    const f = path.join(os.homedir(), ".claude", ".qualia-config.json");
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function projectName() {
+  try {
+    return path.basename(process.cwd());
+  } catch {
+    return "—";
+  }
+}
+
+// ─── Rendering Helpers ───────────────────────────────────
+function progressBar(phase, total) {
+  if (!total || total < 1) return "";
+  const pct = Math.min(100, Math.round(((phase - 1) / total) * 100));
+  const filled = Math.round(pct / 10);
+  const bar = `${TEAL}${"█".repeat(filled)}${DIM2}${"░".repeat(10 - filled)}${RESET}`;
+  return `${bar} ${DIM}${pct}%${RESET}`;
+}
+
+function colorForStatus(s) {
+  const colors = {
+    setup: DIM,
+    planned: BLUE,
+    built: YELLOW,
+    verified: GREEN,
+    polished: GREEN,
+    shipped: TEAL,
+    handed_off: TEAL,
+    done: GREEN,
+  };
+  return colors[s] || WHITE;
+}
+
+function pad(str, width) {
+  // Width-aware padding ignoring ANSI codes
+  const visible = str.replace(/\x1b\[[0-9;]*m/g, "");
+  const need = Math.max(0, width - visible.length);
+  return str + " ".repeat(need);
+}
+
+// ─── Commands ────────────────────────────────────────────
+function cmdBanner(action, phase, subtitle) {
+  const spec = ACTIONS[action] || { label: (action || "qualia").toUpperCase(), glyph: "◆" };
+  const state = readState();
+  const config = readConfig();
+  const project = projectName();
+
+  const title = phase
+    ? `${spec.label} ${DIM}·${WHITE} Phase ${phase}${subtitle ? ` ${DIM}— ${WHITE}${subtitle}` : ""}`
+    : spec.label;
+
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}${spec.glyph}${RESET} ${WHITE}${BOLD}QUALIA${RESET} ${DIM}►${RESET} ${WHITE}${title}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+
+  // Context panel
+  const roleColor = config.role === "OWNER" ? TEAL : BLUE;
+  const roleLine = config.role
+    ? `${roleColor}${config.role}${RESET} ${DIM}·${RESET} ${WHITE}${config.installed_by || ""}${RESET}`
+    : `${DIM}(not configured)${RESET}`;
+
+  console.log(`  ${pad(DIM + "Project" + RESET, 20)}${WHITE}${project}${RESET}`);
+
+  if (state && state.ok) {
+    const phaseStr = state.phase_name
+      ? `${state.phase} of ${state.total_phases} ${DIM}— ${WHITE}${state.phase_name}`
+      : `${state.phase} of ${state.total_phases}`;
+    console.log(`  ${pad(DIM + "Phase" + RESET, 20)}${WHITE}${phaseStr}${RESET}`);
+    console.log(`  ${pad(DIM + "Status" + RESET, 20)}${colorForStatus(state.status)}${state.status}${RESET}`);
+    if (state.tasks_total) {
+      console.log(`  ${pad(DIM + "Tasks" + RESET, 20)}${WHITE}${state.tasks_done}/${state.tasks_total}${RESET}`);
+    }
+    const bar = progressBar(state.phase, state.total_phases);
+    if (bar) console.log(`  ${pad(DIM + "Progress" + RESET, 20)}${bar}`);
+    if (state.gap_cycles > 0) {
+      console.log(`  ${pad(DIM + "Gap cycles" + RESET, 20)}${YELLOW}${state.gap_cycles}/2${RESET}`);
+    }
+  }
+
+  console.log(`  ${pad(DIM + "Role" + RESET, 20)}${roleLine}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log("");
+}
+
+function cmdContext() {
+  const state = readState();
+  const config = readConfig();
+  const project = projectName();
+
+  console.log("");
+  console.log(`  ${pad(DIM + "Project" + RESET, 20)}${WHITE}${project}${RESET}`);
+
+  if (state && state.ok) {
+    const phaseStr = state.phase_name
+      ? `${state.phase} of ${state.total_phases} ${DIM}— ${WHITE}${state.phase_name}`
+      : `${state.phase} of ${state.total_phases}`;
+    console.log(`  ${pad(DIM + "Phase" + RESET, 20)}${WHITE}${phaseStr}${RESET}`);
+    console.log(`  ${pad(DIM + "Status" + RESET, 20)}${colorForStatus(state.status)}${state.status}${RESET}`);
+    const bar = progressBar(state.phase, state.total_phases);
+    if (bar) console.log(`  ${pad(DIM + "Progress" + RESET, 20)}${bar}`);
+  } else {
+    console.log(`  ${DIM}No project detected. Run${RESET} ${TEAL}/qualia-new${RESET}`);
+  }
+
+  if (config.role) {
+    const roleColor = config.role === "OWNER" ? TEAL : BLUE;
+    console.log(`  ${pad(DIM + "Role" + RESET, 20)}${roleColor}${config.role}${RESET} ${DIM}·${RESET} ${WHITE}${config.installed_by || ""}${RESET}`);
+  }
+  console.log("");
+}
+
+function cmdDivider() {
+  console.log(`  ${RULE_DIM}`);
+}
+
+function cmdOk(msg) {
+  console.log(`  ${GREEN}✓${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdFail(msg) {
+  console.log(`  ${RED}✗${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdWarn(msg) {
+  console.log(`  ${YELLOW}!${RESET} ${WHITE}${msg}${RESET}`);
+}
+
+function cmdInfo(msg) {
+  console.log(`  ${BLUE}◦${RESET} ${DIM}${msg}${RESET}`);
+}
+
+function cmdSpawn(agent, desc) {
+  const name = agent || "agent";
+  const d = desc ? ` ${DIM}— ${desc}${RESET}` : "";
+  console.log(`  ${TEAL}⟐${RESET} ${WHITE}Spawning${RESET} ${TEAL}${name}${RESET}${d}`);
+}
+
+function cmdWave(num, total, taskCount) {
+  console.log("");
+  const n = parseInt(num) || 0;
+  const t = parseInt(total) || 0;
+  const c = parseInt(taskCount) || 0;
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Wave ${n}/${t}${RESET} ${DIM}(${c} ${c === 1 ? "task" : "tasks"}, parallel)${RESET}`);
+}
+
+function cmdTask(num, title) {
+  console.log(`    ${DIM}${num}.${RESET} ${WHITE}${title}${RESET} ${DIM}…${RESET}`);
+}
+
+function cmdDone(num, title, commit) {
+  const c = commit ? ` ${DIM}(${commit})${RESET}` : "";
+  console.log(`    ${GREEN}✓${RESET} ${DIM}${num}.${RESET} ${WHITE}${title}${RESET}${c}`);
+}
+
+function cmdNext(cmd) {
+  if (!cmd) return;
+  console.log("");
+  console.log(`  ${TEAL}→${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${cmd}${RESET}`);
+  console.log("");
+}
+
+function cmdEnd(status, nextCmd) {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}◆${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextCmd) {
+    console.log(`  ${TEAL}→${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
+  }
+  console.log("");
+}
+
+// ─── Main ────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case "banner":
+    cmdBanner(rest[0] || "router", rest[1] || "", rest.slice(2).join(" "));
+    break;
+  case "context":  cmdContext(); break;
+  case "divider":  cmdDivider(); break;
+  case "ok":       cmdOk(rest.join(" ")); break;
+  case "fail":     cmdFail(rest.join(" ")); break;
+  case "warn":     cmdWarn(rest.join(" ")); break;
+  case "info":     cmdInfo(rest.join(" ")); break;
+  case "spawn":    cmdSpawn(rest[0], rest.slice(1).join(" ")); break;
+  case "wave":     cmdWave(rest[0], rest[1], rest[2]); break;
+  case "task":     cmdTask(rest[0], rest.slice(1).join(" ")); break;
+  case "done":     cmdDone(rest[0], rest[1], rest[2]); break;
+  case "next":     cmdNext(rest.join(" ")); break;
+  case "end":      cmdEnd(rest[0], rest.slice(1).join(" ")); break;
+  default:
+    console.error(
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end> [args]`
+    );
+    process.exit(1);
+}

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