qualia-framework 2.6.0 → 3.2.0

package/bin/statusline.js

@@ -0,0 +1,252 @@
+#!/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");
+const HOME = os.homedir();
+
+// ─── 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 {}
+
+// ─── Memory count ────────────────────────────────────────
+let MEMORY_COUNT = 0;
+try {
+  const dirKey = DIR.replace(/\//g, "-");
+  const memDir = path.join(HOME, ".claude", "projects", dirKey, "memory");
+  if (fs.existsSync(memDir)) {
+    const files = fs.readdirSync(memDir).filter(f => f.endsWith(".md") && f !== "MEMORY.md");
+    MEMORY_COUNT = files.length;
+  }
+} catch {}
+
+// ─── Hooks count ─────────────────────────────────────────
+let HOOKS_COUNT = 0;
+try {
+  const settingsPath = path.join(HOME, ".claude", "settings.json");
+  if (fs.existsSync(settingsPath)) {
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    if (settings.hooks) {
+      for (const event of Object.values(settings.hooks)) {
+        if (Array.isArray(event)) {
+          for (const matcher of event) {
+            if (matcher.hooks && Array.isArray(matcher.hooks)) {
+              HOOKS_COUNT += matcher.hooks.length;
+            }
+          }
+        }
+      }
+    }
+  }
+} catch {}
+
+// ─── Skills count ────────────────────────────────────────
+let SKILLS_COUNT = 0;
+try {
+  const skillsDir = path.join(HOME, ".claude", "skills");
+  if (fs.existsSync(skillsDir)) {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    SKILLS_COUNT = entries.filter(e => e.isDirectory() || e.name.endsWith(".md")).length;
+  }
+} 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 + Memory + Hooks ──
+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}`;
+  // Memory, hooks, skills — context indicators
+  const contextParts = [];
+  if (MEMORY_COUNT > 0) contextParts.push(`${TEAL}⊙${RESET}${DIM}${MEMORY_COUNT}${RESET}`);
+  if (HOOKS_COUNT > 0) contextParts.push(`${TEAL_GLOW}⚙${RESET}${DIM}${HOOKS_COUNT}${RESET}`);
+  if (SKILLS_COUNT > 0) contextParts.push(`${TEAL_DIM}✦${RESET}${DIM}${SKILLS_COUNT}${RESET}`);
+  if (contextParts.length > 0) {
+    LINE1 += ` ${DIM}│${RESET} ${contextParts.join(` ${DIM}·${RESET} `)}`;
+  }
+} 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/guide.md

@@ -0,0 +1,63 @@
+# Qualia Developer Guide
+
+> Follow the road. Type the commands. The framework handles the rest.
+
+## The Road
+
+```
+/qualia-new          ← Set up project (once)
+     ↓
+For each phase:
+  /qualia-plan       ← Plan it (planner agent)
+  /qualia-build      ← Build it (builder subagents)
+  /qualia-verify     ← Verify it works (verifier agent)
+     ↓
+/qualia-polish       ← Design pass
+/qualia-ship         ← Deploy to production
+/qualia-handoff      ← Deliver to client
+     ↓
+Done.
+```
+
+## The 10 Commands
+
+| When | Command | What it does |
+|------|---------|-------------|
+| Starting | `/qualia-new` | Set up project from scratch |
+| Building | `/qualia-plan` | Plan the current phase |
+| | `/qualia-build` | Build it (parallel tasks) |
+| | `/qualia-verify` | Check it actually works |
+| Quick fix | `/qualia-quick` | Skip planning, just do it |
+| Finishing | `/qualia-polish` | Design and UX pass |
+| | `/qualia-ship` | Deploy to production |
+| | `/qualia-handoff` | Deliver to client |
+| Reporting | `/qualia-report` | Log what you did (mandatory) |
+| **Lost?** | **`/qualia`** | **Tells you the exact next command** |
+
+## Rules
+
+1. **Feature branches only** — never push to main
+2. **Read before write** — don't edit files you haven't read
+3. **MVP first** — build what's asked, nothing extra
+4. **`/qualia` is your friend** — lost? type it
+
+## When You're Stuck
+
+```
+/qualia       ← "what's next?"
+```
+
+If that doesn't help, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
+
+## Session Start / End
+
+**Start:** Claude loads your project context automatically.
+**End:** Run `/qualia-report` — this is mandatory before clock-out.
+
+## How It Works (you don't need to know this, but if curious)
+
+- **Context isolation:** Each task runs in a fresh AI brain. Task 50 gets the same quality as Task 1.
+- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work.
+- **Plans are prompts:** The plan file IS what the builder reads. No translation loss.
+- **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
+- **tracking.json:** Updated on every push. The ERP reads it automatically.

package/hooks/auto-update.js

@@ -0,0 +1,139 @@
+#!/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 _traceStart = Date.now();
+
+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;
+
+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 traceFile = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(traceFile, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+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) {
+      _trace("auto-update", "allow", { reason: "recently-checked" });
+      process.exit(0);
+    }
+  }
+
+  // Already updating
+  if (fs.existsSync(LOCK_FILE)) {
+    _trace("auto-update", "allow", { reason: "already-updating" });
+    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 {
+    _trace("auto-update", "allow", { reason: "config-unreadable" });
+    process.exit(0);
+  }
+  if (!cfg.code || !cfg.version) {
+    _trace("auto-update", "allow", { reason: "config-incomplete" });
+    process.exit(0);
+  }
+
+  // Fork the check-and-update into a detached background process so the hook
+  // returns immediately and Claude Code is never blocked.
+  //
+  // OWNER: silent auto-install (unchanged behavior).
+  // EMPLOYEE: write a sticky notification file — session-start.js renders a
+  // banner every session until they run the update manually. Fawzi (OWNER)
+  // never sees the banner because his framework auto-updates ahead of it.
+  const script = `
+    const fs = require("fs");
+    const path = require("path");
+    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 NOTIF_FILE = path.join(CLAUDE_DIR, ".qualia-update-available.json");
+    const cfg = ${JSON.stringify(cfg)};
+    try {
+      fs.writeFileSync(LOCK_FILE, String(process.pid));
+      const r = spawnSync("npm", ["view", "qualia-framework", "version"], {
+        encoding: "utf8",
+        timeout: 15000,
+        shell: process.platform === "win32",
+      });
+      const latest = ((r.stdout || "").trim());
+      if (!latest) { try { fs.unlinkSync(LOCK_FILE); } catch {} process.exit(0); }
+      const cmp = (a, b) => {
+        const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+        for (let i = 0; i < 3; i++) {
+          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) {
+        if (cfg.role === "OWNER") {
+          // Silent auto-install for OWNER — no notification banner ever shown.
+          spawnSync("npx", ["qualia-framework@latest", "install"], {
+            input: cfg.code + "\\n",
+            timeout: 120000,
+            stdio: ["pipe", "ignore", "ignore"],
+            shell: process.platform === "win32",
+          });
+          try { fs.unlinkSync(NOTIF_FILE); } catch {}
+        } else {
+          // EMPLOYEE: write sticky notification. session-start.js will render
+          // a visible banner every session until the employee runs the update.
+          try {
+            fs.writeFileSync(NOTIF_FILE, JSON.stringify({
+              current: cfg.version,
+              latest: latest,
+              detected_at: new Date().toISOString(),
+            }, null, 2));
+          } catch {}
+        }
+      } else {
+        // Already up to date — clear any stale notification file.
+        try { fs.unlinkSync(NOTIF_FILE); } catch {}
+      }
+    } catch {}
+    try { fs.unlinkSync(LOCK_FILE); } catch {}
+  `;
+
+  const child = spawn(process.execPath, ["-e", script], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+} catch {
+  // Silent — never block the tool call
+}
+
+_trace("auto-update", "allow", { reason: "check-spawned" });
+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 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);