qualia-framework-v2 2.10.0 → 3.0.0

package/bin/state.js

@@ -186,6 +186,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 +226,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 +255,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 +322,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 +360,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 +381,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;
 
@@ -597,6 +634,66 @@ 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");
+  }
+
+  if (errors.length > 0) {
+    return output({
+      ok: false,
+      error: "PLAN_VALIDATION_FAILED",
+      phase,
+      errors,
+      message: `Plan file has ${errors.length} issue(s)`,
+    });
+  }
+
+  output({
+    ok: true,
+    action: "validate-plan",
+    phase,
+    task_count: taskCount,
+    done_when_count: doneWhenCount,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -620,11 +717,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/hooks/auto-update.js

@@ -8,23 +8,43 @@ const path = require("path");
 const os = require("os");
 const { spawn, spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const CACHE_FILE = path.join(CLAUDE_DIR, ".qualia-last-update-check");
 const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
 const LOCK_FILE = path.join(CLAUDE_DIR, ".qualia-updating");
 const MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
+function _trace(hookName, result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const traceFile = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(traceFile, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 try {
   // Fast path: recently checked
   if (fs.existsSync(CACHE_FILE)) {
     const last = Number(fs.readFileSync(CACHE_FILE, "utf8")) || 0;
     if (Date.now() - last * 1000 < MAX_AGE_MS) {
+      _trace("auto-update", "allow", { reason: "recently-checked" });
       process.exit(0);
     }
   }
 
   // Already updating
   if (fs.existsSync(LOCK_FILE)) {
+    _trace("auto-update", "allow", { reason: "already-updating" });
     process.exit(0);
   }
 
@@ -36,9 +56,13 @@ try {
   try {
     cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
   } catch {
+    _trace("auto-update", "allow", { reason: "config-unreadable" });
+    process.exit(0);
+  }
+  if (!cfg.code || !cfg.version) {
+    _trace("auto-update", "allow", { reason: "config-incomplete" });
     process.exit(0);
   }
-  if (!cfg.code || !cfg.version) process.exit(0);
 
   // Fork the check-and-update into a detached background process so the hook
   // returns immediately and Claude Code is never blocked.
@@ -58,7 +82,7 @@ try {
         shell: process.platform === "win32",
       });
       const latest = ((r.stdout || "").trim());
-      if (!latest) { fs.unlinkSync(LOCK_FILE); return; }
+      if (!latest) { fs.unlinkSync(LOCK_FILE); 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++) {
@@ -89,4 +113,5 @@ try {
   // Silent — never block the tool call
 }
 
+_trace("auto-update", "allow", { reason: "check-spawned" });
 process.exit(0);

package/hooks/block-env-edit.js

@@ -6,6 +6,8 @@
 
 const fs = require("fs");
 
+const _traceStart = Date.now();
+
 function readInput() {
   try {
     const raw = fs.readFileSync(0, "utf8");
@@ -22,9 +24,29 @@ const file = (input.tool_input && (input.tool_input.file_path || input.tool_inpu
 // Normalize separators so Windows paths (C:\project\.env.local) also match.
 const normalized = String(file).replace(/\\/g, "/");
 
+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 file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
 if (/\.env(\.|$)/.test(normalized)) {
   console.log("BLOCKED: Cannot edit environment files. Ask Fawzi to update secrets.");
+  _trace("block-env-edit", "block", { file: normalized });
   process.exit(2);
 }
 
+_trace("block-env-edit", "allow");
 process.exit(0);

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

package/hooks/session-start.js

@@ -12,6 +12,8 @@ const path = require("path");
 const os = require("os");
 const { spawnSync } = require("child_process");
 
+const _traceStart = Date.now();
+
 const HOME = os.homedir();
 const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
@@ -81,4 +83,21 @@ try {
   // Deliberately silent — hook must never fail
 }
 
+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 {}
+}
+
+_trace("session-start", "allow");
 process.exit(0);

package/package.json

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

package/skills/qualia/SKILL.md

@@ -47,6 +47,7 @@ Use the state.js JSON output plus gathered context:
 | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
 | `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
 | `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+| `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
 
 **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
 

package/skills/qualia-build/SKILL.md

@@ -21,6 +21,24 @@ cat .planning/phase-{N}-plan.md
 
 Parse: tasks, waves, file references.
 
+### 1b. Create Recovery Point
+
+Before executing any tasks, tag current HEAD for rollback:
+
+```bash
+git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
+```
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
+```
+
+If a wave fails and the user needs to roll back:
+```bash
+git reset --hard pre-build-phase-{N}
+node ~/.claude/bin/state.js transition --to planned --force
+```
+
 ### 2. Execute Waves
 
 ```bash

package/skills/qualia-learn/SKILL.md

@@ -46,17 +46,40 @@ What did you learn?
 3. Client preference — client-specific requirement
 ```
 
-### 2. Format Entry
+### 2. Check for Duplicates
+
+Before saving, check if a similar entry already exists:
+
+```bash
+# Search for the title (case-insensitive substring match)
+grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+```
+
+If a near-match exists (title is similar to an existing entry):
+- Show the existing entry to the user
+- Ask: "A similar entry exists. Update it, create a new one, or skip?"
+- If update: replace the existing entry. If new: append. If skip: done.
+
+### 3. Format Entry
+
+Each entry gets a unique ID and ISO timestamp for dedup and ordering:
 
 ```markdown
-### {Title} ({date})
+
+---
+
+### {Title}
+**ID:** {random 8-char hex, e.g. a3f7c1e9}
+**Date:** {ISO 8601, e.g. 2026-04-11}
 **Project:** {current project name or "general"}
 **Context:** {brief context — what you were building when you learned this}
 
 {The learning — be specific enough that future-you understands without context}
 ```
 
-### 3. Append to Knowledge File
+### 4. Append to Knowledge File
+
+Append-only — never overwrite the file, always add at the end:
 
 ```bash
 # Append to the right file
@@ -67,7 +90,7 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 - Fix → `~/.claude/knowledge/common-fixes.md`
 - Client pref → `~/.claude/knowledge/client-prefs.md`
 
-### 4. Confirm
+### 5. Confirm
 
 ```
 ⬢ Saved to {file}