qualia-framework 3.2.0 → 3.3.0

package/bin/state.js

@@ -9,6 +9,17 @@ const PLANNING = ".planning";
 const STATE_FILE = path.join(PLANNING, "STATE.md");
 const TRACKING_FILE = path.join(PLANNING, "tracking.json");
 
+// ─── Trace ──────────────────────────────────────────────
+function _trace(event, data) {
+  try {
+    const traceDir = path.join(require("os").homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = { hook: event, timestamp: new Date().toISOString(), ...data };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch { /* trace failures must not disrupt state machine */ }
+}
+
 // ─── Arg Parsing ─────────────────────────────────────────
 function parseArgs(argv) {
   const args = {};
@@ -186,6 +197,25 @@ const VALID_FROM = {
   done: ["handed_off"],
 };
 
+// ─── Configurable Gap Cycle Limit ────────────────────────
+function getGapCycleLimit() {
+  // Priority: tracking.json.gap_cycle_limit > PROJECT.md > default (2)
+  try {
+    const t = readTracking();
+    if (t && typeof t.gap_cycle_limit === "number" && t.gap_cycle_limit > 0) {
+      return t.gap_cycle_limit;
+    }
+  } catch {}
+
+  try {
+    const projectMd = fs.readFileSync(path.join(PLANNING, "PROJECT.md"), "utf8");
+    const match = projectMd.match(/^gap_cycle_limit:\s*(\d+)/m);
+    if (match) return parseInt(match[1]);
+  } catch {}
+
+  return 2; // default
+}
+
 function checkPreconditions(current, target, opts) {
   const phase = parseInt(opts.phase) || current.phase;
 
@@ -207,6 +237,14 @@ function checkPreconditions(current, target, opts) {
     const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
     if (!fs.existsSync(planFile))
       return fail("MISSING_FILE", `Plan file not found: ${planFile}`);
+    // Validate plan content (not just existence)
+    const planContent = fs.readFileSync(planFile, "utf8");
+    const taskHeaders = planContent.match(/^## Task \d+/gm);
+    if (!taskHeaders || taskHeaders.length === 0)
+      return fail("INVALID_PLAN", "Plan file has no task headers (expected '## Task N')");
+    const doneWhenCount = (planContent.match(/\*\*Done when:\*\*/g) || []).length;
+    if (doneWhenCount < taskHeaders.length)
+      return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${doneWhenCount} 'Done when:' entries`);
   }
 
   if (target === "verified") {
@@ -228,14 +266,15 @@ function checkPreconditions(current, target, opts) {
       return fail("MISSING_FILE", `Handoff file not found: ${hFile}`);
   }
 
-  // Gap-closure circuit breaker
+  // Gap-closure circuit breaker (configurable limit)
   if (target === "planned" && current.status === "verified") {
     const t = readTracking() || {};
     const cycles = (t.gap_cycles || {})[String(phase)] || 0;
-    if (cycles >= 2) {
+    const limit = getGapCycleLimit();
+    if (cycles >= limit) {
       return fail(
         "GAP_CYCLE_LIMIT",
-        `Phase ${phase} has failed verification ${cycles} times. Escalate to Fawzi or re-plan from scratch.`
+        `Phase ${phase} has failed verification ${cycles} times (limit: ${limit}). Escalate to Fawzi or re-plan from scratch.`
       );
     }
   }
@@ -294,6 +333,7 @@ function cmdCheck(opts) {
     assigned_to: s.assigned_to,
     verification: t.verification || "pending",
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
+    gap_cycle_limit: getGapCycleLimit(),
     tasks_done: t.tasks_done || 0,
     tasks_total: t.tasks_total || 0,
     deployed_url: t.deployed_url || "",
@@ -331,7 +371,6 @@ function cmdTransition(opts) {
 
   // Special: note/activity (no status change)
   if (target === "note" || target === "activity") {
-    const now = new Date().toISOString().split("T")[0];
     if (opts.notes) t.notes = opts.notes;
     t.last_updated = new Date().toISOString();
     writeTracking(t);
@@ -353,7 +392,16 @@ function cmdTransition(opts) {
     target,
     { ...opts, phase }
   );
-  if (!check.ok) return output(check);
+  if (!check.ok) {
+    // Force only bypasses status-ordering errors (PRECONDITION_FAILED, GAP_CYCLE_LIMIT).
+    // Never bypass MISSING_FILE, MISSING_ARG, INVALID_PLAN — those cause broken state.
+    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT"];
+    if (opts.force && forceableErrors.includes(check.error)) {
+      console.error(`WARNING: Forcing transition despite: ${check.message}`);
+    } else {
+      return output(check);
+    }
+  }
 
   const prevStatus = s.status;
 
@@ -432,6 +480,18 @@ function cmdTransition(opts) {
     return output(fail("WRITE_ERROR", e.message));
   }
 
+  // Skill outcome scoring — log transition for analytics
+  _trace("state-transition", {
+    result: "allow",
+    phase: s.phase,
+    status: s.status,
+    previous_status: prevStatus,
+    verification: t.verification,
+    gap_closure: prevStatus === "verified" && target === "planned",
+    duration_ms: 0,
+    extra: { verification: t.verification, gap_closure: prevStatus === "verified" && target === "planned" }
+  });
+
   output({
     ok: true,
     phase: s.phase,
@@ -597,6 +657,137 @@ function cmdFix(opts) {
   });
 }
 
+function cmdValidatePlan(opts) {
+  const phase = parseInt(opts.phase) || 1;
+  const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
+
+  if (!fs.existsSync(planFile)) {
+    return output(fail("MISSING_FILE", `Plan file not found: ${planFile}`));
+  }
+
+  const content = fs.readFileSync(planFile, "utf8");
+  const errors = [];
+
+  // Check frontmatter exists
+  if (!/^---\n/.test(content)) {
+    errors.push("Missing frontmatter (---) at start of file");
+  }
+
+  // Check task count > 0
+  const taskHeaders = content.match(/^## Task \d+/gm);
+  if (!taskHeaders || taskHeaders.length === 0) {
+    errors.push("No task headers found (expected '## Task N — title')");
+  }
+
+  // Check "Done when" exists for each task
+  const taskCount = taskHeaders ? taskHeaders.length : 0;
+  const doneWhenCount = (content.match(/\*\*Done when:\*\*/g) || []).length;
+  if (doneWhenCount < taskCount) {
+    errors.push(
+      `${taskCount} tasks but only ${doneWhenCount} 'Done when:' entries`
+    );
+  }
+
+  // Check Success Criteria section exists
+  if (!/## Success Criteria/m.test(content)) {
+    errors.push("Missing '## Success Criteria' section");
+  }
+
+  // Check goal in frontmatter
+  if (!/^goal:/m.test(content)) {
+    errors.push("Missing 'goal:' in frontmatter");
+  }
+
+  // ─── Verification Contract Validation (non-blocking) ────
+  const warnings = [];
+  const VALID_CHECK_TYPES = ["file-exists", "grep-match", "command-exit", "behavioral"];
+  let contractCount = 0;
+
+  if (/^## Verification Contract/m.test(content)) {
+    // Extract the contract section (from header to next ## or end of file)
+    const contractSectionMatch = content.match(
+      /^## Verification Contract\s*\n([\s\S]+)/m
+    );
+    if (contractSectionMatch) {
+      // Trim at the next ## heading that isn't ### (i.e., a new top-level section)
+      let contractSection = contractSectionMatch[1];
+      const nextH2 = contractSection.search(/\n## (?!#)/);
+      if (nextH2 !== -1) contractSection = contractSection.substring(0, nextH2);
+      // Each contract starts with ### Contract for Task N
+      const contractBlocks = contractSection.match(/^### Contract for Task \d+/gm);
+      contractCount = contractBlocks ? contractBlocks.length : 0;
+
+      if (contractCount === 0) {
+        warnings.push("Verification Contract section exists but contains no contract blocks (expected '### Contract for Task N')");
+      } else {
+        // Split into individual contract blocks for validation
+        const blockSplits = contractSection.split(/^(?=### Contract for Task \d+)/m).filter(Boolean);
+        for (const block of blockSplits) {
+          const taskNumMatch = block.match(/^### Contract for Task (\d+)/);
+          if (!taskNumMatch) continue;
+          const taskNum = taskNumMatch[1];
+
+          const checkTypeMatch = block.match(/\*\*Check type:\*\*\s*(.+)/);
+          const hasCommand = /\*\*Command:\*\*/.test(block);
+          const hasExpected = /\*\*Expected:\*\*/.test(block);
+          const hasFailIf = /\*\*Fail if:\*\*/.test(block);
+
+          if (!checkTypeMatch) {
+            warnings.push(`Contract for Task ${taskNum}: missing 'Check type'`);
+          } else {
+            const checkType = checkTypeMatch[1].trim().toLowerCase();
+            if (!VALID_CHECK_TYPES.includes(checkType)) {
+              warnings.push(
+                `Contract for Task ${taskNum}: invalid check type '${checkType}' (valid: ${VALID_CHECK_TYPES.join(", ")})`
+              );
+            }
+            // behavioral type doesn't require Command or Expected
+            const isBehavioral = checkType === "behavioral";
+            if (!isBehavioral && !hasCommand) {
+              warnings.push(`Contract for Task ${taskNum}: missing 'Command' (required for ${checkType})`);
+            }
+            if (!isBehavioral && !hasExpected) {
+              warnings.push(`Contract for Task ${taskNum}: missing 'Expected' (required for ${checkType})`);
+            }
+          }
+
+          if (!hasFailIf) {
+            warnings.push(`Contract for Task ${taskNum}: missing 'Fail if'`);
+          }
+        }
+      }
+
+      // Warn if contract count < task count
+      if (taskCount > 0 && contractCount > 0 && contractCount < taskCount) {
+        warnings.push(
+          `Only ${contractCount} contract(s) for ${taskCount} task(s) — not all tasks have verification contracts`
+        );
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return output({
+      ok: false,
+      error: "PLAN_VALIDATION_FAILED",
+      phase,
+      errors,
+      warnings: warnings.length > 0 ? warnings : undefined,
+      message: `Plan file has ${errors.length} issue(s)`,
+    });
+  }
+
+  output({
+    ok: true,
+    action: "validate-plan",
+    phase,
+    task_count: taskCount,
+    done_when_count: doneWhenCount,
+    contract_count: contractCount,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -620,11 +811,14 @@ switch (cmd) {
   case "fix":
     cmdFix(opts);
     break;
+  case "validate-plan":
+    cmdValidatePlan(opts);
+    break;
   default:
     output(
       fail(
         "UNKNOWN_COMMAND",
-        `Usage: state.js <check|transition|init|fix> [--options]`
+        `Usage: state.js <check|transition|init|fix|validate-plan> [--options]`
       )
     );
 }

package/bin/statusline.js

@@ -224,11 +224,11 @@ 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
+  // Memory, hooks, skills — context indicators with labels
   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 (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} `)}`;
   }

package/docs/erp-contract.md

@@ -0,0 +1,161 @@
+# ERP API Contract
+
+The Qualia Framework optionally uploads session reports to the company ERP at `https://portal.qualiasolutions.net`. This document specifies the API shape.
+
+## Configuration
+
+Stored in `~/.claude/.qualia-config.json`:
+
+```json
+{
+  "erp": {
+    "enabled": true,
+    "url": "https://portal.qualiasolutions.net",
+    "api_key_file": ".erp-api-key"
+  }
+}
+```
+
+The API key is read from `~/.claude/.erp-api-key` (file mode 0600).
+
+## Endpoints
+
+### POST /api/v1/reports
+
+Upload a session report.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "project": "client-project-name",
+  "client": "Client Name",
+  "phase": 2,
+  "phase_name": "Authentication & Dashboard",
+  "total_phases": 4,
+  "status": "built",
+  "tasks_done": 5,
+  "tasks_total": 5,
+  "verification": "pass",
+  "gap_cycles": 0,
+  "deployed_url": "https://client.vercel.app",
+  "session_duration_minutes": 45,
+  "commits": ["abc1234", "def5678"],
+  "notes": "Completed auth flow, dashboard layout, and API routes.",
+  "submitted_by": "Fawzi Goussous",
+  "submitted_at": "2026-04-12T14:30:00Z"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "report_id": "rpt_abc123def456",
+  "message": "Report received"
+}
+```
+
+**Response (401 Unauthorized):**
+```json
+{
+  "ok": false,
+  "error": "INVALID_API_KEY",
+  "message": "API key is invalid or expired"
+}
+```
+
+**Response (422 Unprocessable Entity):**
+```json
+{
+  "ok": false,
+  "error": "VALIDATION_FAILED",
+  "message": "Missing required field: project"
+}
+```
+
+### GET /api/v1/reports/:project
+
+Retrieve reports for a project.
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "reports": [
+    {
+      "report_id": "rpt_abc123def456",
+      "phase": 2,
+      "status": "built",
+      "submitted_at": "2026-04-12T14:30:00Z",
+      "submitted_by": "Fawzi Goussous"
+    }
+  ]
+}
+```
+
+### GET /api/v1/tracking/:project
+
+Retrieve current tracking state (same shape as tracking.json).
+
+**Headers:**
+```
+Authorization: Bearer <api-key>
+```
+
+**Response (200 OK):**
+```json
+{
+  "ok": true,
+  "tracking": {
+    "project": "client-project-name",
+    "phase": 2,
+    "total_phases": 4,
+    "status": "built",
+    "last_updated": "2026-04-12T14:30:00Z"
+  }
+}
+```
+
+## Behavior
+
+- When `erp.enabled` is `false`, `/qualia-report` skips the upload silently.
+- 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.
+
+## Required Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| project | string | yes | Project slug from tracking.json |
+| phase | number | yes | Current phase number |
+| status | string | yes | Current status (setup, planned, built, verified, etc.) |
+| submitted_by | string | yes | Team member name |
+| submitted_at | string | yes | ISO 8601 timestamp |
+
+All other fields are optional but recommended for complete reporting.
+
+## Rate Limits
+
+- 60 requests per minute per API key
+- Report body max size: 64KB
+- No batch endpoint — one report per request
+
+## Security
+
+- API keys are per-user, not per-project
+- Keys expire after 90 days (re-issue via Fawzi)
+- All traffic is HTTPS-only
+- No PII beyond team member names is transmitted

package/hooks/branch-guard.js

@@ -10,11 +10,30 @@ const path = require("path");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const CONFIG = path.join(os.homedir(), ".claude", ".qualia-config.json");
 
+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 file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 function fail(msg) {
   console.log(msg);
-  process.exit(1);
+  _trace("branch-guard", "block", { reason: msg });
+  process.exit(2);
 }
 
 let role = "";
@@ -40,8 +59,10 @@ 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);
+    _trace("branch-guard", "block", { reason: `non-owner push to ${branch}` });
+    process.exit(2);
   }
 }
 
+_trace("branch-guard", "allow");
 process.exit(0);

package/hooks/migration-guard.js

@@ -6,6 +6,8 @@
 
 const fs = require("fs");
 
+const _traceStart = Date.now();
+
 function readInput() {
   try {
     const raw = fs.readFileSync(0, "utf8");
@@ -20,8 +22,27 @@ const ti = input.tool_input || {};
 const file = String(ti.file_path || "").replace(/\\/g, "/");
 const content = String(ti.content || ti.new_string || "");
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    const path = require("path");
+    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 filePath = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 // Only inspect migration/SQL files
 if (!/migration|migrate|\.sql$/i.test(file)) {
+  _trace("migration-guard", "allow", { reason: "non-migration file" });
   process.exit(0);
 }
 
@@ -54,7 +75,9 @@ if (errors.length > 0) {
   }
   console.log("");
   console.log("Fix these before proceeding. If intentional, ask Fawzi to approve.");
+  _trace("migration-guard", "block", { errors });
   process.exit(2);
 }
 
+_trace("migration-guard", "allow");
 process.exit(0);

package/hooks/pre-compact.js

@@ -7,6 +7,8 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const STATE_FILE = path.join(".planning", "STATE.md");
 
 try {
@@ -29,4 +31,22 @@ try {
   // Silent — never block compaction
 }
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    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 file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-compact", "allow");
 process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -9,6 +9,25 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    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 file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 function runGate(label, cmd, args, { required = true } = {}) {
   const r = spawnSync(cmd, args, {
     stdio: "ignore",
@@ -21,6 +40,7 @@ function runGate(label, cmd, args, { required = true } = {}) {
   }
   if (required) {
     console.log(`BLOCKED: ${label} errors. Fix before deploying.`);
+    _trace("pre-deploy-gate", "block", { gate: label });
     process.exit(1);
   }
   return false;
@@ -60,10 +80,27 @@ function scanServiceRoleLeaks() {
   const leaks = [];
   for (const root of roots) {
     for (const file of walk(root)) {
+      // --- Path-based skips (no I/O needed) ---
+
       // Skip server-only files (convention: *.server.ts, server/ dirs)
       if (/\.server\.|[\\/]server[\\/]/.test(file)) continue;
+
+      // Skip App Router route handlers (always server-side)
+      if (/[\\/]route\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip middleware (always server-side)
+      if (/[\\/]middleware\.(ts|tsx|js|jsx|mjs)$/.test(file)) continue;
+
+      // Skip files in app/api/ directory (always server-side)
+      if (/[\\/]app[\\/]api[\\/]/.test(file)) continue;
+
+      // --- Content-based checks (requires reading file) ---
       try {
         const content = fs.readFileSync(file, "utf8");
+
+        // Skip files with "use server" directive (Server Actions / Server Components)
+        if (/^["']use server["']/m.test(content)) continue;
+
         if (/service_role/.test(content)) {
           leaks.push(file);
         }
@@ -102,9 +139,11 @@ if (leaks.length > 0) {
   for (const f of leaks.slice(0, 10)) {
     console.log(`  ✗ ${f}`);
   }
+  _trace("pre-deploy-gate", "block", { gate: "security", leaks: leaks.slice(0, 10) });
   process.exit(1);
 }
 console.log("  ✓ Security");
 console.log("⬢ All gates passed.");
 
+_trace("pre-deploy-gate", "allow");
 process.exit(0);

package/hooks/pre-push.js

@@ -8,6 +8,8 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const TRACKING = path.join(".planning", "tracking.json");
 
 try {
@@ -30,4 +32,22 @@ try {
   process.stderr.write(`WARNING: tracking sync failed: ${err.message}\n`);
 }
 
+function _trace(hookName, result, extra) {
+  try {
+    const os = require("os");
+    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 file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("pre-push", "allow");
 process.exit(0);