qualia-framework 4.0.0 → 4.0.5

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;
 }
 
@@ -142,6 +194,7 @@ function ensureLifetime(t) {
   if (typeof t.milestone !== "number") t.milestone = 1;
   if (typeof t.milestone_name !== "string") t.milestone_name = "";
   if (!Array.isArray(t.milestones)) t.milestones = [];
+  if (typeof t.report_seq !== "number") t.report_seq = 0;
   if (!t.lifetime || typeof t.lifetime !== "object") {
     t.lifetime = {
       tasks_completed: 0,
@@ -153,6 +206,26 @@ function ensureLifetime(t) {
   return t;
 }
 
+// Parse JOURNEY.md and extract the human name of the Nth milestone.
+// Matches headers like:
+//   ## Milestone 2 · Core Features
+//   ## Milestone 2 · Core Features     [CURRENT]
+//   ## Milestone 5 · Handoff           [FINAL]
+// Returns "" if JOURNEY.md is absent or the milestone isn't in it.
+function readNextMilestoneNameFromJourney(milestoneNum) {
+  try {
+    const journeyPath = path.join(PLANNING, "JOURNEY.md");
+    if (!fs.existsSync(journeyPath)) return "";
+    const content = fs.readFileSync(journeyPath, "utf8");
+    const re = new RegExp(`^##\\s+Milestone\\s+${milestoneNum}\\s*[·•-]\\s*([^\\n\\[]+)`, "m");
+    const m = content.match(re);
+    if (m && m[1]) return m[1].trim();
+    return "";
+  } catch {
+    return "";
+  }
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -613,14 +686,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));
   }
 
@@ -1078,7 +1162,12 @@ function cmdCloseMilestone(opts) {
   t.lifetime.total_phases += (parseInt(t.total_phases) || 0);
   t.lifetime.last_closed_milestone = closedMilestone;
   t.milestone = closedMilestone + 1;
-  t.milestone_name = ""; // cleared; /qualia-milestone reads next one from JOURNEY.md
+  // Try to pre-populate next milestone's name from JOURNEY.md so the ERP
+  // tree view doesn't show a blank between close-milestone and the next
+  // state.js init --force (which happens in /qualia-milestone step 7).
+  // If JOURNEY.md is missing or unparseable, fall through with blank —
+  // /qualia-milestone will still set it via init --force.
+  t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
   t.last_updated = new Date().toISOString();
 
   writeTracking(t);
@@ -1175,6 +1264,27 @@ function cmdBackfillLifetime(opts) {
   });
 }
 
+// ─── Next Report ID ──────────────────────────────────────
+// Increments report_seq and returns the next QS-REPORT-NN id. Per-project
+// counter (lives in tracking.json). /qualia-report calls this to tag each
+// session report with a stable, human-readable client ID before POSTing
+// to the ERP. If --peek is passed, the next id is returned WITHOUT
+// incrementing — useful for --dry-run previews.
+function cmdNextReportId(opts) {
+  const t = readTracking();
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
+  ensureLifetime(t);
+  const peek = !!opts.peek;
+  const next = (parseInt(t.report_seq) || 0) + 1;
+  const id = `QS-REPORT-${String(next).padStart(2, "0")}`;
+  if (!peek) {
+    t.report_seq = next;
+    t.last_updated = new Date().toISOString();
+    writeTracking(t);
+  }
+  output({ ok: true, action: "next-report-id", report_id: id, report_seq: next, peeked: peek });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -1193,6 +1303,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); });
@@ -1222,11 +1336,14 @@ try {
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;
+    case "next-report-id":
+      cmdNextReportId(opts);
+      break;
     default:
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|next-report-id> [--options]`
         )
       );
   }

package/bin/statusline.js

@@ -154,6 +154,8 @@ try {
 } catch {}
 
 // ─── Phase info from .planning/tracking.json ─────────────
+// Shows: [M{n}·{milestoneName}] P{phase}/{total} T{done}/{total} {status} [!{blockers}]
+// Every segment is optional — missing data is skipped, never rendered as a placeholder.
 let PHASE_INFO = "";
 try {
   const trackingPath = path.join(DIR, ".planning", "tracking.json");
@@ -162,12 +164,46 @@ try {
     const phase = Number(tracking.phase || 0) || 0;
     const total = Number(tracking.total_phases || 0) || 0;
     const status = String(tracking.status || "");
+    const milestone = Number(tracking.milestone || 0) || 0;
+    const milestoneName = String(tracking.milestone_name || "");
+    const tasksDone = Number(tracking.tasks_done || 0) || 0;
+    const tasksTotal = Number(tracking.tasks_total || 0) || 0;
+    const blockers = Array.isArray(tracking.blockers) ? tracking.blockers.length : 0;
+
+    const parts = [];
+
+    // Milestone: M{n}·{shortName}   (short name trimmed to 14 chars)
+    if (milestone > 0) {
+      let mStr = `M${milestone}`;
+      if (milestoneName) {
+        const shortName = milestoneName.length > 14 ? milestoneName.slice(0, 13) + "…" : milestoneName;
+        mStr += `${DIM}·${RESET}${TEAL_GLOW}${shortName}`;
+      }
+      parts.push(`${TEAL}${mStr}${RESET}`);
+    }
+
+    // Phase: P{phase}/{total}
     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}`;
+      parts.push(`${WHITE}P${phase}/${total}${RESET}`);
+    }
+
+    // Tasks within phase: T{done}/{total}
+    if (tasksTotal > 0) {
+      parts.push(`${DIM}T${RESET}${WHITE}${tasksDone}/${tasksTotal}${RESET}`);
+    }
+
+    // Status
+    if (status) {
+      parts.push(`${TEAL_GLOW}${status}${RESET}`);
+    }
+
+    // Blockers — red badge, only when > 0
+    if (blockers > 0) {
+      parts.push(`${RED}!${blockers}${RESET}`);
+    }
+
+    if (parts.length > 0) {
+      PHASE_INFO = parts.join(` ${DIM}·${RESET} `);
     }
   }
 } catch {}
@@ -175,7 +211,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");
@@ -183,36 +222,22 @@ try {
   }
 } catch {}
 
-// ─── Hooks count ─────────────────────────────────────────
-let HOOKS_COUNT = 0;
+// ─── Qualia identity: first name of the installed employee ─────────
+// Read from ~/.claude/.qualia-config.json. Used as the "signature" at the
+// end of line 2. Gracefully degrades to empty string if the config is
+// missing (pre-install, broken install, or running outside a Qualia env).
+let QUALIA_FIRST_NAME = "";
 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;
-            }
-          }
-        }
-      }
+  const configPath = path.join(HOME, ".claude", ".qualia-config.json");
+  if (fs.existsSync(configPath)) {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    const fullName = String(cfg.installed_by || "").trim();
+    if (fullName) {
+      QUALIA_FIRST_NAME = fullName.split(/\s+/)[0] || "";
     }
   }
 } 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 {
@@ -244,13 +269,13 @@ try {
   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 with labels
-  const contextParts = [];
-  if (MEMORY_COUNT > 0) contextParts.push(`${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`);
-  if (HOOKS_COUNT > 0) contextParts.push(`${DIM}hooks${RESET} ${TEAL_GLOW}${HOOKS_COUNT}${RESET}`);
-  if (SKILLS_COUNT > 0) contextParts.push(`${DIM}skills${RESET} ${TEAL_DIM}${SKILLS_COUNT}${RESET}`);
-  if (contextParts.length > 0) {
-    LINE1 += ` ${DIM}│${RESET} ${contextParts.join(` ${DIM}·${RESET} `)}`;
+  // Memory — the one context indicator that's actually project-specific
+  if (MEMORY_COUNT > 0) {
+    LINE1 += ` ${DIM}│${RESET} ${DIM}mem${RESET} ${TEAL}${MEMORY_COUNT}${RESET}`;
+  }
+  // Qualia member signature — end of line 1 so it sits above line 2's model info
+  if (QUALIA_FIRST_NAME) {
+    LINE1 += ` ${DIM}│${RESET} ${TEAL}⬢${RESET} ${TEAL_GLOW}Qualia member${RESET}${DIM}:${RESET} ${WHITE}${QUALIA_FIRST_NAME}${RESET}`;
   }
 } catch {
   LINE1 = `${TEAL}⬢${RESET} ${WHITE}qualia${RESET}`;

package/docs/erp-contract.md

@@ -28,8 +28,16 @@ Upload a session report.
 ```
 Authorization: Bearer <api-key>
 Content-Type: application/json
+Idempotency-Key: <uuid>   # optional; 24h replay window — see below
 ```
 
+**Idempotency-Key behavior (v3.6+):**
+When present, must be a valid UUID. Replays of the same key within 24h return
+the original `report_id` with `Idempotent-Replay: true` response header and
+200 status — no new row is created. Invalid UUID format returns 400.
+Independent of `client_report_id` UPSERT (both can be used together; see
+below).
+
 **Request Body:**
 ```json
 {
@@ -38,7 +46,18 @@ Content-Type: application/json
   "team_id": "qualia-solutions",
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
+  "client_report_id": "QS-REPORT-03",
   "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,
@@ -77,11 +96,27 @@ accept both shapes: if object, use `gap_cycles[String(phase)] || 0`.
 ```json
 {
   "ok": true,
-  "report_id": "rpt_abc123def456",
+  "report_id": "QS-REPORT-03",
   "message": "Report received"
 }
 ```
 
+`report_id` semantics:
+- **v4.0.4+ payloads** (`client_report_id` present): ERP echoes the
+  `client_report_id` string back as `report_id` for display consistency.
+  Example: request sends `client_report_id: "QS-REPORT-03"` → response
+  returns `report_id: "QS-REPORT-03"`.
+- **Legacy payloads** (no `client_report_id`): ERP returns its internal UUID
+  (e.g. `"a5304d8b-a5ac-4e22-b0c0-fed5f50299bb"`) as `report_id`.
+
+**Idempotent UPSERT on retry (v4.0.4+):**
+When BOTH `project_id` and `client_report_id` are present, the ERP treats
+`(project_id, client_report_id)` as a unique key and UPSERTs. Retries after
+a transient failure produce the same row and return the same `report_id`
+— no duplicate. This is stronger than the 24h Idempotency-Key window (which
+is exact-replay only) because `client_report_id` uniqueness is enforced
+permanently.
+
 **Response (401 Unauthorized):**
 ```json
 {
@@ -161,7 +196,15 @@ Authorization: Bearer <api-key>
 - When the API key file is missing or empty, the upload is skipped with a warning.
 - 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.
+- Reports are append-only — no PUT/PATCH/DELETE endpoints exist for
+  external callers. Internal idempotent UPSERT on `(project_id,
+  client_report_id)` retries is the one exception (see "Idempotent UPSERT
+  on retry" above).
+- **`dry_run` retention (v4.0.4+):** The ERP deletes rows where
+  `dry_run = true AND submitted_at < now() - 7 days` via a daily cron at
+  03:00 UTC. Production report views (list, project tree, email digests)
+  exclude `dry_run = true` rows at read time by default. Admins can opt in
+  via `includeDryRun: true` on the server-action readers for diagnostics.
 - `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.
 
@@ -175,6 +218,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. |
@@ -183,6 +228,8 @@ Authorization: Bearer <api-key>
 | 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. |
+| client_report_id | string | recommended (v4.0.4+) | Client-side sequential identifier: `QS-REPORT-01`, `QS-REPORT-02`, … per-project. Stable across retries. Preferred dedupe key over the ERP-generated `report_id`; safe to adopt as the ERP's primary report key. |
+| dry_run | boolean | optional (v4.0.4+) | `true` marks a synthetic ping (from `qualia-framework erp-ping`). Receivers should filter these out of production report views. |
 
 All other fields are optional but recommended for complete reporting.
 

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