qualia-framework 4.0.0 → 4.0.3

package/CLAUDE.md

@@ -23,25 +23,37 @@ Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLab
 
 ## The Road (how projects flow)
 
+v4 hierarchy: **Project → Journey → Milestones (2–5, Handoff always last) → Phases (2–5 tasks each) → Tasks (one commit, one verification contract).**
+
 ```
-/qualia-new → set up project
+/qualia-new        → kickoff + parallel research + JOURNEY.md (all milestones upfront)
+                     add --auto to chain the whole road end-to-end
      ↓
-For each phase:
-  /qualia-plan  → plan the phase (planner agent, fresh context)
-  /qualia-build → build it (builder subagents per task, fresh context each)
-  /qualia-verify → verify it works (verifier agent, goal-backward checks)
+For each milestone, for each phase:
+  /qualia-plan     → plan the phase (planner + plan-checker revision loop, fresh context)
+  /qualia-build    → build it (builder subagents per task, wave-based parallel)
+  /qualia-verify   → goal-backward check (verifier agent, fresh context)
      ↓
-/qualia-polish → design/UX pass
-/qualia-ship   → deploy to production
-/qualia-handoff → deliver to client
+/qualia-milestone  → close milestone, archive artifacts, prep next (human gate)
+     ↓ (repeat for each milestone until Handoff)
+Final milestone = Handoff:
+  /qualia-polish   → design/UX pass (Phase 1 of Handoff)
+  (content + SEO)  → Phase 2
+  (final QA)       → Phase 3
+  /qualia-ship     → deploy to production (quality gates → deploy → verify)
+  /qualia-handoff  → 4 deliverables: credentials, doc, final update, report
      ↓
 Done.
 
-Lost? → /qualia (tells you exactly what's next)
-Quick fix? → /qualia-quick (skip planning for small tasks)
-End of day? → /qualia-report (mandatory before clock-out)
+Lost?        → /qualia        (state router — tells you the next command)
+Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
+Quick fix?   → /qualia-quick  (skip planning for small tasks)
+Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
+End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
 ```
 
+**Human gates:** journey approval after `/qualia-new`, then one at each milestone boundary via `/qualia-milestone`. `--auto` runs everything between gates automatically.
+
 ## Context Isolation
 Every task runs in a fresh subagent context. Task 50 gets the same quality as Task 1.
 - Planner gets: PROJECT.md + phase requirements

package/agents/plan-checker.md

@@ -34,7 +34,7 @@ Plan must have YAML frontmatter with:
 
 **FAIL if:** frontmatter missing, incomplete, or `goal` differs from ROADMAP.md.
 
-### Rule 2: Every task has the 6 mandatory story-file fields
+### Rule 2: Every task has the 7 mandatory story-file fields
 
 Each `## Task N — title` block must include ALL of these:
 

package/bin/cli.js

@@ -126,18 +126,23 @@ function cmdUpdate() {
 // non-Qualia entries in settings.json (other hooks, user env vars, etc.).
 // --yes / -y skips the confirmation prompt for scripted use.
 
-// 8 Qualia hook filenames — only these are removed from ~/.claude/hooks/,
-// any other hooks the user dropped in there are left alone.
+// Current Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// any other hooks the user dropped in there are left alone. The LEGACY set
+// lists hooks that were shipped by older framework versions but have since
+// been removed; uninstall still tries to clean them so old installs get a
+// clean removal.
 const QUALIA_HOOK_FILES = [
   "session-start.js",
   "auto-update.js",
   "branch-guard.js",
   "pre-push.js",
-  "block-env-edit.js",
   "migration-guard.js",
   "pre-deploy-gate.js",
   "pre-compact.js",
 ];
+const QUALIA_LEGACY_HOOK_FILES = [
+  "block-env-edit.js", // removed in v3.2.0
+];
 
 // 4 Qualia agents — only these are removed.
 const QUALIA_AGENT_FILES = ["planner.md", "builder.md", "verifier.md", "qa-browser.md"];
@@ -210,14 +215,14 @@ function cleanSettingsJson(counters) {
   };
 
   if (settings.hooks && typeof settings.hooks === "object") {
-    for (const key of ["SessionStart", "PreToolUse", "PreCompact"]) {
-      if (settings.hooks[key]) {
-        const cleaned = filterHookArray(settings.hooks[key]);
-        if (cleaned && cleaned.length > 0) {
-          settings.hooks[key] = cleaned;
-        } else {
-          delete settings.hooks[key];
-        }
+    // Iterate every hook event key, not a hardcoded subset — future hook
+    // events added by Claude Code or the framework get cleaned automatically.
+    for (const key of Object.keys(settings.hooks)) {
+      const cleaned = filterHookArray(settings.hooks[key]);
+      if (cleaned && cleaned.length > 0) {
+        settings.hooks[key] = cleaned;
+      } else {
+        delete settings.hooks[key];
       }
     }
     // If hooks is now empty, remove it entirely.
@@ -305,8 +310,8 @@ async function cmdUninstall() {
     safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
   }
 
-  // Hooks — only the 8 Qualia ones.
-  for (const f of QUALIA_HOOK_FILES) {
+  // Hooks — current set plus any legacy hook filenames from older versions.
+  for (const f of [...QUALIA_HOOK_FILES, ...QUALIA_LEGACY_HOOK_FILES]) {
     safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
   }
 

package/bin/install.js

@@ -599,16 +599,23 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   // bash/Git Bash requirement on Windows.
   const hd = path.join(CLAUDE_DIR, "hooks");
   const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
-  settings.hooks = {
+  const QUALIA_HOOK_SET = new Set([
+    "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
+    "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
+  ]);
+  const isQualiaHookCmd = (cmd) => {
+    if (typeof cmd !== "string") return false;
+    for (const h of QUALIA_HOOK_SET) if (cmd.includes(h)) return true;
+    return false;
+  };
+
+  // Our canonical hook definitions, grouped per event/matcher.
+  const qualiaHooks = {
     SessionStart: [
       {
         matcher: ".*",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("session-start.js"),
-            timeout: 5,
-          },
+          { type: "command", command: nodeCmd("session-start.js"), timeout: 5 },
         ],
       },
     ],
@@ -616,44 +623,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "Bash",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("auto-update.js"),
-            timeout: 5,
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("branch-guard.js"),
-            timeout: 5,
-            statusMessage: "⬢ Checking branch permissions...",
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("pre-push.js"),
-            timeout: 15,
-            statusMessage: "⬢ Syncing tracking...",
-          },
-          {
-            type: "command",
-            if: "Bash(vercel --prod*)",
-            command: nodeCmd("pre-deploy-gate.js"),
-            timeout: 180,
-            statusMessage: "⬢ Running quality gates...",
-          },
+          { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
+          { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
         ],
       },
       {
         matcher: "Edit|Write",
         hooks: [
-          {
-            type: "command",
-            if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
-            command: nodeCmd("migration-guard.js"),
-            timeout: 10,
-            statusMessage: "⬢ Checking migration safety...",
-          },
+          { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
     ],
@@ -661,17 +640,27 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "compact",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("pre-compact.js"),
-            timeout: 15,
-            statusMessage: "⬢ Saving state...",
-          },
+          { type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." },
         ],
       },
     ],
   };
 
+  // Merge user hooks: strip Qualia-owned commands, preserve everything else.
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+  for (const event of Object.keys(qualiaHooks)) {
+    const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    // Remove Qualia-owned command entries from each matcher block, drop empty blocks.
+    const cleaned = [];
+    for (const block of existing) {
+      if (!block || !Array.isArray(block.hooks)) continue;
+      const kept = block.hooks.filter((h) => !isQualiaHookCmd(h && h.command));
+      if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+    }
+    // Append our canonical blocks after the preserved user ones.
+    settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
+  }
+
   // Permissions — no restrictions on env files or branches.
   // Everyone can read/write .env, push to main.
   if (!settings.permissions) settings.permissions = {};

package/bin/qualia-ui.js

@@ -320,10 +320,10 @@ function cmdJourneyTree(journeyPath) {
 
   // Project name from frontmatter if present
   const projMatch = content.match(/^project:\s*"?(.+?)"?\s*$/m);
-  const projectName = projMatch ? projMatch[1] : projectName();
+  const projName = projMatch ? projMatch[1] : projectName();
 
   console.log("");
-  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projectName}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projName}${RESET}`);
   console.log(`  ${RULE_DIM}`);
   console.log(`  ${DIM}${milestones.length} milestones · currently at M${currentMilestone}${RESET}`);
   console.log("");

package/bin/state.js

@@ -9,6 +9,7 @@ const PLANNING = ".planning";
 const STATE_FILE = path.join(PLANNING, "STATE.md");
 const TRACKING_FILE = path.join(PLANNING, "tracking.json");
 const LOCK_FILE = path.join(PLANNING, ".state.lock");
+const JOURNAL_FILE = path.join(PLANNING, ".state.journal");
 
 // ─── Atomic write (tmp + rename) ─────────────────────────
 // Prevents half-written files when SIGINT, OOM, or AV scanners
@@ -26,10 +27,60 @@ function atomicWrite(file, content) {
   }
 }
 
+// ─── Write-ahead journal (two-file crash recovery) ──────
+// STATE.md + tracking.json are written back-to-back. A SIGKILL or power
+// loss between the two renames can leave the pair inconsistent. The
+// journal captures the pre-write snapshot; if a journal is still present
+// on next startup, we know the previous mutator crashed mid-write and
+// restore both files to the pre-transaction state.
+function writeJournal(preState, preTracking) {
+  if (!fs.existsSync(PLANNING)) return;
+  const payload = JSON.stringify({
+    ts: new Date().toISOString(),
+    pid: process.pid,
+    state: preState != null ? preState : null,
+    tracking: preTracking != null ? preTracking : null,
+  });
+  atomicWrite(JOURNAL_FILE, payload);
+}
+function clearJournal() {
+  try { fs.unlinkSync(JOURNAL_FILE); } catch {}
+}
+function recoverFromJournal() {
+  if (!fs.existsSync(JOURNAL_FILE)) return false;
+  try {
+    const raw = fs.readFileSync(JOURNAL_FILE, "utf8");
+    const j = JSON.parse(raw);
+    if (j.state != null) atomicWrite(STATE_FILE, j.state);
+    if (j.tracking != null) atomicWrite(TRACKING_FILE, j.tracking);
+    clearJournal();
+    try { _trace("state-journal", "recover", { from_pid: j.pid, journal_ts: j.ts }); } catch {}
+    return true;
+  } catch {
+    // Corrupt journal — best effort: remove so we don't loop on recovery.
+    clearJournal();
+    return false;
+  }
+}
+
 // ─── Exclusive lock ──────────────────────────────────────
 // Prevents two concurrent state.js mutations from racing on the dual
 // STATE.md + tracking.json write. Read commands (check, validate-plan)
 // don't take the lock — only mutators do.
+
+// Synchronous sleep without CPU spin. Atomics.wait on a zero-initialized
+// SharedArrayBuffer blocks until the timeout elapses and yields the CPU.
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    // SharedArrayBuffer unavailable (extremely old runtimes) — last-resort
+    // tight loop, bounded to the requested duration.
+    const t = Date.now() + ms;
+    while (Date.now() < t) {}
+  }
+}
+
 function acquireLock(timeoutMs = 5000) {
   if (!fs.existsSync(PLANNING)) return null; // nothing to lock yet
   const start = Date.now();
@@ -50,12 +101,13 @@ function acquireLock(timeoutMs = 5000) {
           continue;
         }
       } catch {}
-      // Spin-wait briefly. State ops are fast; conflicts rare.
-      const t = Date.now() + 50;
-      while (Date.now() < t) {}
+      sleepSync(50);
     }
   }
-  // Couldn't acquire — proceed unlocked rather than block the user.
+  // Couldn't acquire inside the budget — proceed unlocked rather than
+  // hard-block the user. Surface this in analytics so repeated contention
+  // is visible instead of silent.
+  try { _trace("state-lock", "fallthrough", { waited_ms: Date.now() - start }); } catch {}
   return null;
 }
 
@@ -613,14 +665,25 @@ function cmdTransition(opts) {
     t.deploy_count = (parseInt(t.deploy_count) || 0) + 1;
   }
 
-  // Write both files
+  // Write both files. We write a journal snapshot of the pre-transition
+  // STATE.md + tracking.json first; if the process dies between the two
+  // real writes, the next invocation will see the journal and restore both
+  // files to the pre-transition state. Each individual write is torn-write
+  // safe (tmp + rename); the journal closes the gap between the two.
   const backupState = readState();
+  const backupTracking = (() => {
+    try { return fs.readFileSync(TRACKING_FILE, "utf8"); } catch { return null; }
+  })();
   try {
+    writeJournal(backupState, backupTracking);
     writeStateMd(s);
     writeTracking(t);
+    clearJournal();
   } catch (e) {
-    // Revert STATE.md on failure (atomic so the revert itself is safe)
-    if (backupState) atomicWrite(STATE_FILE, backupState);
+    // Revert whichever file is out of sync with pre-transition state.
+    try { if (backupState) atomicWrite(STATE_FILE, backupState); } catch {}
+    try { if (backupTracking) atomicWrite(TRACKING_FILE, backupTracking); } catch {}
+    clearJournal();
     return output(fail("WRITE_ERROR", e.message));
   }
 
@@ -1193,6 +1256,10 @@ const opts = parseArgs(rest);
 const READ_ONLY = new Set(["check", "validate-plan"]);
 let __lock = null;
 if (!READ_ONLY.has(cmd)) {
+  // Before acquiring the lock, recover from any journal left by a crashed
+  // previous mutator. Runs for mutators only; read commands should still
+  // return the actual on-disk state even if it's mid-recovery.
+  try { recoverFromJournal(); } catch {}
   __lock = acquireLock();
   process.on("exit", () => releaseLock(__lock));
   process.on("SIGINT", () => { releaseLock(__lock); process.exit(130); });

package/bin/statusline.js

@@ -175,7 +175,10 @@ try {
 // ─── Memory count ────────────────────────────────────────
 let MEMORY_COUNT = 0;
 try {
-  const dirKey = DIR.replace(/\//g, "-");
+  // Claude Code uses a hyphenated encoding of the project directory. Replace
+  // BOTH forward and backward slashes so Windows installs (where DIR contains
+  // `\`) get a correct key and the memory count renders.
+  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");

package/docs/erp-contract.md

@@ -39,6 +39,16 @@ Content-Type: application/json
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
   "milestone": 2,
+  "milestone_name": "Core Product",
+  "milestones": [
+    {
+      "num": 1,
+      "name": "Foundation",
+      "closed_at": "2026-04-10T18:00:00Z",
+      "phases_completed": 3,
+      "tasks_completed": 12
+    }
+  ],
   "phase": 2,
   "phase_name": "Authentication & Dashboard",
   "total_phases": 4,
@@ -175,6 +185,8 @@ Authorization: Bearer <api-key>
 | submitted_by | string | yes | Team member name |
 | submitted_at | string | yes | ISO 8601 timestamp |
 | milestone | number | recommended | Current milestone number (1-indexed) |
+| milestone_name | string | recommended (v4+) | Human name of the current milestone — from JOURNEY.md / tracking.json |
+| milestones | array | recommended (v4+) | Array of closed milestone summaries: `{num, name, closed_at, phases_completed, tasks_completed}`. Renders the journey tree on the ERP. |
 | 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. |

package/guide.md

@@ -43,7 +43,7 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 
 **Plus one halt case:** if a phase fails verification beyond the gap-cycle limit (default 2), the chain stops and asks for human intervention.
 
-## The 10 Commands
+## The Road Commands
 
 | When | Command | What it does |
 |------|---------|-------------|

package/hooks/migration-guard.js

@@ -11,6 +11,10 @@ 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.
+// Between EAGAIN retries we sleep via Atomics.wait to avoid CPU-burning spin.
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch {}
+}
 function readInput() {
   const deadline = Date.now() + 1000;
   const buf = Buffer.alloc(65536);
@@ -21,8 +25,8 @@ function readInput() {
       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;
+        // EAGAIN/EWOULDBLOCK: no data yet. Sleep 1ms and retry until deadline.
+        if (e && (e.code === "EAGAIN" || e.code === "EWOULDBLOCK")) { sleepSync(1); continue; }
         // Any other read error: bail
         break;
       }
@@ -108,14 +112,24 @@ 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(scan) && !/WHERE/i.test(scan)) {
-  errors.push("DELETE FROM without WHERE clause");
+// DELETE / UPDATE without WHERE — check per-statement, not file-global.
+// Previously a file containing "DELETE FROM foo;" followed by any later
+// "... WHERE ..." (in a SELECT, JOIN, etc.) would pass the check.
+function splitStatements(src) {
+  return src.split(/;/g).map((s) => s.trim()).filter(Boolean);
 }
-
-// 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");
+const statements = splitStatements(scan);
+for (const stmt of statements) {
+  if (/^\s*DELETE\s+FROM\b/i.test(stmt) && !/\bWHERE\b/i.test(stmt)) {
+    errors.push("DELETE FROM without WHERE clause");
+    break;
+  }
+}
+for (const stmt of statements) {
+  if (/^\s*UPDATE\s+\w+(?:\.\w+)?\s+SET\b/i.test(stmt) && !/\bWHERE\b/i.test(stmt)) {
+    errors.push("UPDATE without WHERE clause — affects every row");
+    break;
+  }
 }
 
 // TRUNCATE (almost always wrong in migrations)

package/hooks/pre-compact.js

@@ -2,17 +2,44 @@
 // ~/.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).
+//
+// BY DEFAULT this commit uses --no-verify + --no-gpg-sign. The auto-save is a
+// framework bot commit, and pre-commit hooks that run full test suites would
+// routinely fail (context compaction happens at any moment) and lose the
+// STATE.md snapshot. But compliance-sensitive projects can opt into strict
+// mode via ~/.claude/.qualia-config.json:
+//
+//   {
+//     "pre_compact": {
+//       "respect_user_hooks": true,
+//       "respect_gpg_signing": true
+//     }
+//   }
+//
+// When either is true, the corresponding --no-* flag is dropped.
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
 const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
 const STATE_FILE = path.join(".planning", "STATE.md");
+const CONFIG_FILE = path.join(os.homedir(), ".claude", ".qualia-config.json");
+
+function readCompactConfig() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    return cfg.pre_compact || {};
+  } catch {
+    return {};
+  }
+}
 
 let _commitStatus = null;
 let _commitReason = "no-state-file";
+let _commitFlags = null;
 
 try {
   if (fs.existsSync(STATE_FILE)) {
@@ -29,16 +56,17 @@ try {
         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",
-      ], {
+      const cfg = readCompactConfig();
+      const commitArgs = ["commit"];
+      if (!cfg.respect_user_hooks) commitArgs.push("--no-verify");
+      if (!cfg.respect_gpg_signing) commitArgs.push("--no-gpg-sign");
+      commitArgs.push("--author=Qualia Framework <bot@qualia.solutions>");
+      commitArgs.push("-m", "state: pre-compaction save");
+      _commitFlags = {
+        no_verify: !cfg.respect_user_hooks,
+        no_gpg_sign: !cfg.respect_gpg_signing,
+      };
+      const commitRes = spawnSync("git", commitArgs, {
         timeout: 5000,
         stdio: ["ignore", "ignore", "pipe"],
         encoding: "utf8",
@@ -72,5 +100,5 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-_trace("pre-compact", "allow", { commit_status: _commitStatus, commit_reason: _commitReason });
+_trace("pre-compact", "allow", { commit_status: _commitStatus, commit_reason: _commitReason, commit_flags: _commitFlags });
 process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -2,8 +2,7 @@
 // ~/.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 (preserved for test compatibility; Claude Code's hook
-// protocol formally uses exit 2, but the framework's existing tests assert on 1).
+// Exits 2 to BLOCK deploy (Claude Code PreToolUse hook contract).
 // Exits 0 to allow.
 // Cross-platform (Windows/macOS/Linux). No `grep` or `find` — pure Node.
 
@@ -43,7 +42,7 @@ function runGate(label, cmd, args, { required = true } = {}) {
   if (required) {
     console.error(`BLOCKED: ${label} errors. Fix before deploying.`);
     _trace("pre-deploy-gate", "block", { gate: label });
-    process.exit(1);
+    process.exit(2);
   }
   return false;
 }
@@ -180,7 +179,7 @@ if (leaks.length > 0) {
     console.error(`  ✗ ${f}`);
   }
   _trace("pre-deploy-gate", "block", { gate: "security", leaks: leaks.slice(0, 10) });
-  process.exit(1);
+  process.exit(2);
 }
 console.log("  ✓ Security");
 console.log("⬢ All gates passed.");

package/hooks/pre-push.js

@@ -85,9 +85,12 @@ function commitStamp() {
     "-m", `chore(track): ERP sync ${now}`,
   ]);
   if (commit.status !== 0) {
-    // If commit failed (e.g., empty diff because git's auto-CRLF normalized
-    // the only change to nothing), restore the file to keep the working tree
-    // clean and move on. Not fatal.
+    // Commit failed (e.g., empty diff because git's auto-CRLF normalized the
+    // only change to nothing, or branch is in a detached/conflicted state).
+    // Unstage tracking.json and restore the working tree copy so the user's
+    // next manual commit isn't polluted by our aborted stamp.
+    try { git(["reset", "HEAD", "--", TRACKING]); } catch {}
+    try { if (raw != null) atomicWrite(TRACKING, raw); } catch {}
     return { skipped: "git-commit-failed", error: (commit.stderr || commit.stdout || "").trim() };
   }
   return { committed: true, sha: lastCommit, ts: now };

package/hooks/session-start.js

@@ -52,6 +52,14 @@ function getNextCommand() {
   }
 }
 
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 function fallbackText() {
   // If qualia-ui.js is missing, emit plain text. Keeps the session informative
   // even on a broken install.
@@ -121,14 +129,6 @@ try {
   // Deliberately silent — hook must never fail
 }
 
-function readConfig() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
-  } catch {
-    return {};
-  }
-}
-
 function _trace(hookName, result, extra) {
   try {
     const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");

package/package.json

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