qualia-framework 3.3.2 → 3.6.0

package/bin/statusline.js

@@ -93,35 +93,55 @@ try {
     let branch = "";
     let changes = 0;
     try {
-      const dirCheck = spawnSync("git", ["rev-parse", "--git-dir"], {
+      // Single git spawn: `status -b --porcelain=v1` returns branch on the
+      // first line (`## branch.name...`) and one change per subsequent line.
+      // Three separate git spawns cost ~450ms on Windows; this collapses to one.
+      const st = spawnSync("git", ["status", "-b", "--porcelain=v1"], {
         cwd: DIR,
         encoding: "utf8",
         timeout: 1000,
         stdio: ["ignore", "pipe", "ignore"],
+        shell: process.platform === "win32",
       });
-      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;
+      if (st.status === 0) {
+        const lines = (st.stdout || "").split("\n");
+        const header = lines[0] || "";
+        if (header.startsWith("## ")) {
+          // Possible forms:
+          //   "## main"
+          //   "## main...origin/main"
+          //   "## main...origin/main [ahead 1, behind 2]"
+          //   "## HEAD (no branch)"  ← detached
+          //   "## No commits yet on main"
+          let raw = header.slice(3);
+          const ellipsisIdx = raw.indexOf("...");
+          if (ellipsisIdx !== -1) raw = raw.slice(0, ellipsisIdx);
+          // Strip any trailing "[ahead/behind]" annotation that survived
+          raw = raw.replace(/\s*\[.*\]\s*$/, "").trim();
+          if (raw === "HEAD (no branch)") {
+            branch = "HEAD";
+          } else if (raw.startsWith("No commits yet on ")) {
+            branch = raw.slice("No commits yet on ".length).trim();
+          } else {
+            branch = raw;
+          }
+        }
+        // Count change lines: every non-empty line after the header
+        for (let i = 1; i < lines.length; i++) {
+          if (lines[i].length > 0) changes++;
         }
       }
     } catch {}
     try {
-      fs.writeFileSync(cacheFile, `${branch}|${changes}`);
+      // Atomic write: tmp + rename so concurrent prompts can't observe
+      // a half-written cache file. Same pattern as state.js atomicWrite.
+      const tmp = `${cacheFile}.tmp.${process.pid}`;
+      fs.writeFileSync(tmp, `${branch}|${changes}`);
+      try {
+        fs.renameSync(tmp, cacheFile);
+      } catch {
+        try { fs.unlinkSync(tmp); } catch {}
+      }
     } catch {}
   }
 

package/docs/erp-contract.md

@@ -34,7 +34,11 @@ Content-Type: application/json
 ```json
 {
   "project": "client-project-name",
+  "project_id": "qs-acme-portal",
+  "team_id": "qualia-solutions",
+  "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
+  "milestone": 2,
   "phase": 2,
   "phase_name": "Authentication & Dashboard",
   "total_phases": 4,
@@ -43,8 +47,19 @@ Content-Type: application/json
   "tasks_total": 5,
   "verification": "pass",
   "gap_cycles": 0,
+  "build_count": 12,
+  "deploy_count": 3,
   "deployed_url": "https://client.vercel.app",
+  "lifetime": {
+    "tasks_completed": 23,
+    "phases_completed": 8,
+    "milestones_completed": 1,
+    "total_phases": 8,
+    "last_closed_milestone": 1
+  },
+  "session_started_at": "2026-04-12T13:45:00Z",
   "session_duration_minutes": 45,
+  "last_pushed_at": "2026-04-12T14:25:00Z",
   "commits": ["abc1234", "def5678"],
   "notes": "Completed auth flow, dashboard layout, and API routes.",
   "submitted_by": "Fawzi Goussous",
@@ -52,6 +67,12 @@ Content-Type: application/json
 }
 ```
 
+**`gap_cycles` polymorphism (v3.5+):** in `tracking.json` (the file the ERP
+reads from git for passive monitoring) `gap_cycles` is an OBJECT keyed by
+phase number — `{"1": 0, "2": 1}`. In the POST `/api/v1/reports` body,
+`/qualia-report` flattens to a NUMBER for the current phase. Receivers must
+accept both shapes: if object, use `gap_cycles[String(phase)] || 0`.
+
 **Response (200 OK):**
 ```json
 {
@@ -119,10 +140,17 @@ Authorization: Bearer <api-key>
   "ok": true,
   "tracking": {
     "project": "client-project-name",
+    "milestone": 2,
     "phase": 2,
     "total_phases": 4,
     "status": "built",
-    "last_updated": "2026-04-12T14:30:00Z"
+    "last_updated": "2026-04-12T14:30:00Z",
+    "lifetime": {
+      "tasks_completed": 23,
+      "phases_completed": 8,
+      "milestones_completed": 1,
+      "total_phases": 8
+    }
   }
 }
 ```
@@ -134,6 +162,8 @@ Authorization: Bearer <api-key>
 - Network failures are non-blocking — the report is saved locally regardless.
 - The ERP reads `tracking.json` directly from git for real-time status (no API call needed for passive monitoring).
 - Reports are append-only — no update or delete endpoints exist.
+- `tracking.json` includes `milestone` and `lifetime` fields (added in v3.4). These survive across milestone resets and `state.js init` calls. For aggregate reporting, use `lifetime.total_phases` + current `total_phases` for the grand total across all milestones.
+- Backward compatibility: if `lifetime` is absent in tracking.json, treat all counters as 0 and `milestone` as 1.
 
 ## Required Fields
 
@@ -144,6 +174,15 @@ Authorization: Bearer <api-key>
 | status | string | yes | Current status (setup, planned, built, verified, etc.) |
 | submitted_by | string | yes | Team member name |
 | submitted_at | string | yes | ISO 8601 timestamp |
+| milestone | number | recommended | Current milestone number (1-indexed) |
+| lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases, last_closed_milestone |
+| project_id | string | recommended (v3.6+) | Stable per-project identifier — preferred dedupe key over `project` slug. Survives directory renames. |
+| team_id | string | recommended (v3.6+) | Installation's team identifier. Composite `(team_id, project_id)` is the canonical project key. |
+| git_remote | string | optional (v3.6+) | e.g. `github.com/QualiasolutionsCY/foo`. Lets the ERP correlate tracking with the source repo. |
+| session_started_at | string | optional (v3.6+) | ISO 8601 — when the current Claude Code session began. |
+| last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |
+| build_count | number | optional (v3.6+) | Lifetime build counter. |
+| deploy_count | number | optional (v3.6+) | Lifetime deploy counter. |
 
 All other fields are optional but recommended for complete reporting.
 

package/hooks/auto-update.js

@@ -6,7 +6,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { spawn, spawnSync } = require("child_process");
+const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
@@ -14,6 +14,7 @@ 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 NOTIF_FILE = path.join(CLAUDE_DIR, ".qualia-update-available.json");
 const MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 function _trace(hookName, result, extra) {
@@ -48,9 +49,6 @@ try {
     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 {
@@ -64,76 +62,62 @@ try {
     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)};
+  // Synchronously fetch the latest version from npm. Tight timeout so the hook
+  // never blocks Claude Code for long. The cache timestamp is written ONLY if
+  // this fetch succeeds — otherwise the next session retries (no 24h blackout
+  // when the network is unreachable).
+  let latest = "";
+  try {
+    fs.writeFileSync(LOCK_FILE, String(process.pid));
+    const r = spawnSync("npm", ["view", "qualia-framework", "version"], {
+      encoding: "utf8",
+      timeout: 3000,
+      shell: process.platform === "win32",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    latest = ((r.stdout || "").trim());
+  } catch {}
+  try { fs.unlinkSync(LOCK_FILE); } catch {}
+
+  if (!latest) {
+    // Fetch failed — leave cache untouched so the next call retries.
+    _trace("auto-update", "allow", { reason: "npm-fetch-failed" });
+    process.exit(0);
+  }
+
+  // Successful fetch — debounce future checks for 24h.
+  fs.writeFileSync(CACHE_FILE, String(Math.floor(Date.now() / 1000)));
+
+  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) {
+    // Update available — write a sticky notification file for ALL roles.
+    // session-start.js renders a banner every session until the user runs
+    // `npx qualia-framework update` manually. We do NOT auto-install during
+    // a live Claude Code session because install rewrites ~/.claude/settings.json
+    // and can corrupt the running session.
     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 {}
-      }
+      fs.writeFileSync(NOTIF_FILE, JSON.stringify({
+        current: cfg.version,
+        latest: latest,
+        detected_at: new Date().toISOString(),
+      }, null, 2));
     } catch {}
-    try { fs.unlinkSync(LOCK_FILE); } catch {}
-  `;
-
-  const child = spawn(process.execPath, ["-e", script], {
-    detached: true,
-    stdio: "ignore",
-  });
-  child.unref();
+    _trace("auto-update", "allow", { reason: "notification-written", current: cfg.version, latest });
+  } else {
+    // Already up to date — clear any stale notification file.
+    try { fs.unlinkSync(NOTIF_FILE); } catch {}
+    _trace("auto-update", "allow", { reason: "up-to-date", version: cfg.version });
+  }
 } catch {
   // Silent — never block the tool call
 }
 
-_trace("auto-update", "allow", { reason: "check-spawned" });
 process.exit(0);

package/hooks/branch-guard.js

@@ -2,7 +2,7 @@
 // ~/.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.
+// Exits 2 to BLOCK (Claude Code hook protocol). Exits 0 to allow.
 // Cross-platform (Windows/macOS/Linux).
 
 const fs = require("fs");
@@ -30,8 +30,17 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-function fail(msg) {
+function fail(msg, extraLines) {
+  // Claude Code surfaces stderr in hook block reasons — write there primarily.
+  // Also mirror to stdout so downstream tooling that scrapes stdout still sees it.
+  console.error(msg);
   console.log(msg);
+  if (Array.isArray(extraLines)) {
+    for (const line of extraLines) {
+      console.error(line);
+      console.log(line);
+    }
+  }
   _trace("branch-guard", "block", { reason: msg });
   process.exit(2);
 }
@@ -48,19 +57,68 @@ if (!role) {
   fail(`BLOCKED: Cannot determine role from ${CONFIG}. Defaulting to deny.`);
 }
 
+// Read Claude Code hook payload from stdin (if any). Contains tool_input.command
+// with the actual `git push ...` invocation. Parsing this lets us catch refspec
+// bypasses like `git push origin feature/x:main` that --show-current would miss.
+let pushCommand = "";
+try {
+  const raw = fs.readFileSync(0, "utf8");
+  if (raw && raw.trim()) {
+    const payload = JSON.parse(raw);
+    pushCommand = (payload && payload.tool_input && payload.tool_input.command) || "";
+  }
+} catch {
+  // No stdin or non-JSON stdin — fall through to branch check.
+}
+
+// Tokenize the push command and detect refspecs targeting main/master.
+// Refspec forms: <src>:<dst>, :<dst> (delete), +<src>:<dst> (force).
+// We only flag explicit <src>:<dst> refspecs here; bare branch pushes
+// (e.g. `git push origin main` from a non-main branch) are uncommon and
+// handled by the --show-current fallback below when applicable.
+function refspecTargetsProtected(cmd) {
+  if (!cmd || typeof cmd !== "string") return null;
+  const tokens = cmd.split(/\s+/).filter(Boolean);
+  const pushIdx = tokens.indexOf("push");
+  if (pushIdx === -1) return null;
+
+  for (let i = pushIdx + 1; i < tokens.length; i++) {
+    let tok = tokens[i];
+    if (tok.startsWith("-")) continue;
+    if (tok.startsWith("+")) tok = tok.slice(1);
+    tok = tok.replace(/^['"]|['"]$/g, "");
+
+    if (tok.includes(":")) {
+      const parts = tok.split(":");
+      const dst = parts[parts.length - 1].replace(/^refs\/heads\//, "");
+      if (dst === "main" || dst === "master") return dst;
+    }
+  }
+  return null;
+}
+
+const refspecTarget = refspecTargetsProtected(pushCommand);
+if (refspecTarget && role !== "OWNER") {
+  fail(
+    `BLOCKED: Employees cannot push to ${refspecTarget}. Create a feature branch first.`,
+    ["Run: git checkout -b feature/your-feature-name"]
+  );
+}
+
 // 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,
+  shell: process.platform === "win32",
 });
 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");
-    _trace("branch-guard", "block", { reason: `non-owner push to ${branch}` });
-    process.exit(2);
+    fail(
+      `BLOCKED: Employees cannot push to ${branch}. Create a feature branch first.`,
+      ["Run: git checkout -b feature/your-feature-name"]
+    );
   }
 }
 

package/hooks/migration-guard.js

@@ -8,10 +8,29 @@ const fs = require("fs");
 
 const _traceStart = Date.now();
 
+// Read JSON tool input from stdin with a safety timeout.
+// On Windows, fs.readFileSync(0) can hang if stdin isn't closed by the host.
+// We loop fs.readSync with a 1s deadline; if no data arrives, treat as empty.
 function readInput() {
+  const deadline = Date.now() + 1000;
+  const buf = Buffer.alloc(65536);
+  let data = "";
   try {
-    const raw = fs.readFileSync(0, "utf8");
-    return JSON.parse(raw);
+    while (Date.now() < deadline) {
+      let n = 0;
+      try {
+        n = fs.readSync(0, buf, 0, buf.length, null);
+      } catch (e) {
+        // EAGAIN/EWOULDBLOCK: no data yet, retry until deadline
+        if (e && (e.code === "EAGAIN" || e.code === "EWOULDBLOCK")) continue;
+        // Any other read error: bail
+        break;
+      }
+      if (n === 0) break; // EOF
+      data += buf.slice(0, n).toString("utf8");
+    }
+    if (!data) return {};
+    return JSON.parse(data);
   } catch {
     return {};
   }
@@ -20,7 +39,14 @@ function readInput() {
 const input = readInput();
 const ti = input.tool_input || {};
 const file = String(ti.file_path || "").replace(/\\/g, "/");
-const content = String(ti.content || ti.new_string || "");
+
+// For Edit tool calls, dangerous SQL might live in old_string OR new_string.
+// Concatenate both sides of the delta plus any full content payload so we
+// scan everything that could reach disk.
+const content = [ti.old_string, ti.new_string, ti.content]
+  .filter((v) => v != null)
+  .map((v) => String(v))
+  .join("\n");
 
 function _trace(hookName, result, extra) {
   try {
@@ -40,31 +66,80 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-// Only inspect migration/SQL files
-if (!/migration|migrate|\.sql$/i.test(file)) {
+// Only inspect SQL files or files that live inside a migrations/ directory.
+// Prior regex was over-broad (matched MigrationModal.tsx, migrations.md, etc.).
+if (!/(^|\/)migrations?\//i.test(file) && !/\.sql$/i.test(file)) {
   _trace("migration-guard", "allow", { reason: "non-migration file" });
   process.exit(0);
 }
 
+// Strip SQL comments before pattern matching so rolled-back/explanatory
+// statements inside `-- ...` line comments or `/* ... */` block comments
+// don't trigger false positives.
+function stripSqlComments(src) {
+  // Remove /* ... */ block comments (non-greedy, multi-line).
+  let out = src.replace(/\/\*[\s\S]*?\*\//g, "");
+  // Remove -- line comments (to end of line).
+  out = out.replace(/--[^\n\r]*/g, "");
+  return out;
+}
+
+const scan = stripSqlComments(content);
+
 const errors = [];
 
 // DROP TABLE without IF EXISTS
-if (/DROP\s+TABLE/i.test(content) && !/IF\s+EXISTS/i.test(content)) {
+if (/DROP\s+TABLE/i.test(scan) && !/IF\s+EXISTS/i.test(scan)) {
   errors.push("DROP TABLE without IF EXISTS");
 }
 
+// DROP DATABASE — almost never appropriate in app migrations
+if (/DROP\s+DATABASE/i.test(scan)) {
+  errors.push("DROP DATABASE detected — refuse unless explicitly approved");
+}
+
+// DROP SCHEMA — destructive, especially with CASCADE
+if (/DROP\s+SCHEMA/i.test(scan)) {
+  errors.push("DROP SCHEMA detected — refuse unless explicitly approved");
+}
+
+// ALTER TABLE ... DROP COLUMN — destructive schema change
+if (/ALTER\s+TABLE\s+[^;]*\bDROP\s+COLUMN\b/i.test(scan)) {
+  errors.push("ALTER TABLE ... DROP COLUMN is destructive");
+}
+
 // DELETE without WHERE
-if (/DELETE\s+FROM/i.test(content) && !/WHERE/i.test(content)) {
+if (/DELETE\s+FROM/i.test(scan) && !/WHERE/i.test(scan)) {
   errors.push("DELETE FROM without WHERE clause");
 }
 
+// UPDATE without WHERE — affects every row
+if (/\bUPDATE\s+\w+(?:\.\w+)?\s+SET\b/i.test(scan) && !/WHERE/i.test(scan)) {
+  errors.push("UPDATE without WHERE clause — affects every row");
+}
+
 // TRUNCATE (almost always wrong in migrations)
-if (/TRUNCATE/i.test(content)) {
+if (/TRUNCATE/i.test(scan)) {
   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)) {
+// GRANT ... TO PUBLIC — privilege leak
+if (/GRANT\s+[^;]*\bTO\s+PUBLIC\b/i.test(scan)) {
+  errors.push("GRANT ... TO PUBLIC detected — privilege leak");
+}
+
+// CREATE TABLE without RLS — but skip TEMP/TEMPORARY tables and partitions.
+// Strategy: enumerate CREATE TABLE statements, drop the ones that don't need RLS,
+// then if any "real" CREATE TABLE remains, require ENABLE ROW LEVEL SECURITY.
+const createTableMatches = scan.match(/CREATE\s+(?:(?:GLOBAL|LOCAL)\s+)?(?:TEMP|TEMPORARY|UNLOGGED)?\s*TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[^;]*/gi) || [];
+const realCreateTables = createTableMatches.filter((stmt) => {
+  // Skip TEMP/TEMPORARY tables — they're session-scoped, no RLS needed.
+  if (/CREATE\s+(?:(?:GLOBAL|LOCAL)\s+)?(?:TEMP|TEMPORARY)\b/i.test(stmt)) return false;
+  // Skip partition tables — RLS lives on the parent table.
+  if (/\bPARTITION\s+OF\b/i.test(stmt)) return false;
+  return true;
+});
+if (realCreateTables.length > 0 && !/ENABLE\s+ROW\s+LEVEL\s+SECURITY/i.test(scan)) {
   errors.push("CREATE TABLE without ENABLE ROW LEVEL SECURITY");
 }
 

package/hooks/pre-compact.js

@@ -11,24 +11,48 @@ const _traceStart = Date.now();
 
 const STATE_FILE = path.join(".planning", "STATE.md");
 
+let _commitStatus = null;
+let _commitReason = "no-state-file";
+
 try {
   if (fs.existsSync(STATE_FILE)) {
     console.log("QUALIA: Saving state before compaction...");
+    _commitReason = "state-clean";
     // Check if STATE.md has uncommitted changes
     const diff = spawnSync("git", ["diff", "--name-only", STATE_FILE], {
       encoding: "utf8",
       timeout: 3000,
+      shell: process.platform === "win32",
     });
     if ((diff.stdout || "").includes("STATE.md")) {
-      spawnSync("git", ["add", STATE_FILE], { timeout: 3000 });
-      spawnSync("git", ["commit", "-m", "state: pre-compaction save"], {
+      const addRes = spawnSync("git", ["add", STATE_FILE], {
+        timeout: 3000,
+        shell: process.platform === "win32",
+      });
+      // Bypass user pre-commit hooks and commit signing so the auto-save
+      // never fails silently and STATE.md is always persisted before
+      // context compaction. Attribute to the framework bot, not the user.
+      const commitRes = spawnSync("git", [
+        "commit",
+        "--no-verify",
+        "--no-gpg-sign",
+        "--author=Qualia Framework <bot@qualia.solutions>",
+        "-m", "state: pre-compaction save",
+      ], {
         timeout: 5000,
-        stdio: "ignore",
+        stdio: ["ignore", "ignore", "pipe"],
+        encoding: "utf8",
+        shell: process.platform === "win32",
       });
+      _commitStatus = commitRes.status;
+      _commitReason = addRes.status === 0 && commitRes.status === 0
+        ? "committed"
+        : "commit-failed";
     }
   }
 } catch {
   // Silent — never block compaction
+  _commitReason = "exception";
 }
 
 function _trace(hookName, result, extra) {
@@ -48,5 +72,5 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-_trace("pre-compact", "allow");
+_trace("pre-compact", "allow", { commit_status: _commitStatus, commit_reason: _commitReason });
 process.exit(0);