qualia-framework 3.4.0 → 3.6.0

package/bin/cli.js

@@ -564,9 +564,19 @@ function cmdMigrate() {
   }
   if (!bashEntry.hooks) bashEntry.hooks = [];
 
+  // Compare by basename, not by absolute-path substring. If the user moved
+  // ~ between OS reinstalls, the OLD path embedded in settings.json no
+  // longer matches the NEW path and migrate would otherwise append a
+  // duplicate entry on every re-run.
+  const extractScriptName = (command) => {
+    const match = command && command.match(/["']([^"']+\.js)["']/);
+    return match ? path.basename(match[1]) : null;
+  };
+
   for (const hookFile of requiredBashHooks) {
     const cmd = nodeCmd(hookFile);
-    const exists = bashEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    const targetName = path.basename(hookFile);
+    const exists = bashEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "pre-deploy-gate.js" ? 180 : 5 };
       if (hookFile === "branch-guard.js") hookDef.if = "Bash(git push*)";
@@ -588,7 +598,8 @@ function cmdMigrate() {
 
   for (const hookFile of requiredEditHooks) {
     const cmd = nodeCmd(hookFile);
-    const exists = editEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    const targetName = path.basename(hookFile);
+    const exists = editEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "migration-guard.js" ? 10 : 5 };
       if (hookFile === "migration-guard.js") hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)";

package/bin/install.js

@@ -497,16 +497,39 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       api_key_file: ".erp-api-key",
     },
   };
-  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+  // mode 0o600: this file holds the role bit (OWNER vs EMPLOYEE) which the
+  // branch-guard hook trusts. Default 0644 would let any local user edit it
+  // and self-elevate.
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(configFile, 0o600); } catch {}
 
   // ─── ERP API key (for report uploads) ──────────────────
+  // Per-user keys, never a hardcoded shared default. Sources, in order:
+  //   1. $QUALIA_ERP_KEY env var at install time (CI / scripted installs)
+  //   2. Existing ~/.claude/.erp-api-key (preserved across re-installs)
+  //   3. Skip — ERP disabled in config until user runs `qualia-framework set-erp-key`
   printSection("ERP Integration");
   const erpKeyFile = path.join(CLAUDE_DIR, ".erp-api-key");
-  if (!fs.existsSync(erpKeyFile)) {
-    fs.writeFileSync(erpKeyFile, "qualia-claude-2026", { mode: 0o600 });
-    ok(".erp-api-key (created)");
+  const envKey = (process.env.QUALIA_ERP_KEY || "").trim();
+  if (envKey) {
+    fs.writeFileSync(erpKeyFile, envKey, { mode: 0o600 });
+    try { fs.chmodSync(erpKeyFile, 0o600); } catch {}
+    ok(".erp-api-key (from $QUALIA_ERP_KEY)");
+  } else if (fs.existsSync(erpKeyFile)) {
+    try { fs.chmodSync(erpKeyFile, 0o600); } catch {}
+    ok(".erp-api-key (existing — preserved)");
   } else {
-    ok(".erp-api-key (exists)");
+    // Disable ERP in the config we just wrote.
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configFile, "utf8"));
+      cfg.erp = { ...(cfg.erp || {}), enabled: false };
+      fs.writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+      try { fs.chmodSync(configFile, 0o600); } catch {}
+    } catch {}
+    log(`${YELLOW}!${RESET} ERP key not configured — reports won't upload until set.`);
+    log(`${DIM}  Set with:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install,${RESET}`);
+    log(`${DIM}  or write the key to:${RESET} ${WHITE}${erpKeyFile}${RESET} ${DIM}(mode 0600).${RESET}`);
+    log(`${DIM}  Get a key from Fawzi.${RESET}`);
   }
 
   // ─── Configure settings.json ───────────────────────────

package/bin/state.js

@@ -8,13 +8,98 @@ const path = require("path");
 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");
+
+// ─── Atomic write (tmp + rename) ─────────────────────────
+// Prevents half-written files when SIGINT, OOM, or AV scanners
+// interrupt mid-write. Same-filesystem rename is atomic on POSIX
+// and best-effort atomic on Windows (NTFS replaces in one syscall).
+function atomicWrite(file, content) {
+  const tmp = `${file}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, content);
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    // Cleanup tmp on failure (Windows EBUSY, EPERM, etc.)
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+// ─── 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.
+function acquireLock(timeoutMs = 5000) {
+  if (!fs.existsSync(PLANNING)) return null; // nothing to lock yet
+  const start = Date.now();
+  const ours = `${process.pid}@${new Date().toISOString()}`;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const fd = fs.openSync(LOCK_FILE, "wx");
+      fs.writeSync(fd, ours);
+      fs.closeSync(fd);
+      return LOCK_FILE;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      // Stale lock? If older than 30s, steal it.
+      try {
+        const stat = fs.statSync(LOCK_FILE);
+        if (Date.now() - stat.mtimeMs > 30_000) {
+          fs.unlinkSync(LOCK_FILE);
+          continue;
+        }
+      } catch {}
+      // Spin-wait briefly. State ops are fast; conflicts rare.
+      const t = Date.now() + 50;
+      while (Date.now() < t) {}
+    }
+  }
+  // Couldn't acquire — proceed unlocked rather than block the user.
+  return null;
+}
+
+function releaseLock(lock) {
+  if (!lock) return;
+  try { fs.unlinkSync(lock); } catch {}
+}
 
 // ─── Trace ──────────────────────────────────────────────
-function _trace(event, data) {
+// Signature normalized: _trace(event, result, data?). Old callers passed
+// (event, data) with `result` as a string in `data` — that produced
+// nonsense JSONL ({0:"a",1:"l",2:"l",...}). Always use the 3-arg form.
+//
+// Log rotation: trace files older than TRACE_RETENTION_DAYS are pruned
+// on every write. Heavy users used to accumulate unbounded MB/day in
+// ~/.claude/.qualia-traces/. The prune is best-effort and never throws.
+const TRACE_RETENTION_DAYS = 30;
+
+function _pruneTraces(traceDir) {
+  try {
+    const cutoff = Date.now() - TRACE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    for (const name of fs.readdirSync(traceDir)) {
+      if (!name.endsWith(".jsonl")) continue;
+      const p = path.join(traceDir, name);
+      try {
+        const stat = fs.statSync(p);
+        if (stat.mtimeMs < cutoff) fs.unlinkSync(p);
+      } catch {}
+    }
+  } catch {}
+}
+
+function _trace(event, result, 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 };
+    // Prune ~1% of the time (cheap on most invocations, bounded over time).
+    if (Math.random() < 0.01) _pruneTraces(traceDir);
+    const entry = {
+      hook: event,
+      result: result || "allow",
+      timestamp: new Date().toISOString(),
+      ...(data && typeof data === "object" ? 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 */ }
@@ -48,7 +133,7 @@ function readTracking() {
 }
 
 function writeTracking(t) {
-  fs.writeFileSync(TRACKING_FILE, JSON.stringify(t, null, 2) + "\n");
+  atomicWrite(TRACKING_FILE, JSON.stringify(t, null, 2) + "\n");
 }
 
 // Ensure lifetime + milestone fields exist (backward compat for old tracking files)
@@ -79,14 +164,17 @@ function parseStateMd(content) {
   if (!content) return null;
   const schema_errors = [];
   const get = (prefix) => {
-    const m = content.match(new RegExp(`^${prefix}:\\s*(.+)$`, "m"));
+    // CRLF tolerance: Windows editors save with `\r\n`. Use `(.+?)\r?$` so
+    // the `\r` is consumed, not captured. `.trim()` is still applied as
+    // belt-and-suspenders for any other trailing whitespace.
+    const m = content.match(new RegExp(`^${prefix}:\\s*(.+?)\\r?$`, "m"));
     return m ? m[1].trim() : "";
   };
   const hasField = (prefix) =>
     new RegExp(`^${prefix}:\\s*`, "m").test(content);
 
   const phaseMatch = content.match(
-    /^Phase:\s*(\d+)\s+of\s+(\d+)\s*[—-]\s*(.+)$/m
+    /^Phase:\s*(\d+)\s+of\s+(\d+)\s*[—-]\s*(.+?)\r?$/m
   );
   if (!phaseMatch) {
     schema_errors.push({
@@ -198,7 +286,7 @@ Last session: ${now}
 Last worked by: ${s.assigned_to}
 Resume: ${s.resume || "—"}
 `;
-  fs.writeFileSync(STATE_FILE, md);
+  atomicWrite(STATE_FILE, md);
 }
 
 // ─── Precondition Checks ─────────────────────────────────
@@ -498,8 +586,17 @@ function cmdTransition(opts) {
   }
 
   if (target === "polished") {
-    if (s.phases[s.phases.length - 1])
-      s.phases[s.phases.length - 1].status = "verified";
+    // Mark every passed phase as polished (polish is a whole-project pass).
+    // Previously only the last roadmap row was touched, and was set to
+    // "verified" — which both lost current-phase context and used the wrong
+    // status string. Now we use "polished" on every row that's already at
+    // verified or polished or completed.
+    for (const p of s.phases) {
+      const st = (p.status || "").toLowerCase();
+      if (st === "verified" || st === "polished" || st === "completed" || st === "complete") {
+        p.status = "polished";
+      }
+    }
   }
 
   if (target === "shipped") {
@@ -512,21 +609,18 @@ function cmdTransition(opts) {
     writeStateMd(s);
     writeTracking(t);
   } catch (e) {
-    // Revert STATE.md on failure
-    if (backupState) fs.writeFileSync(STATE_FILE, backupState);
+    // Revert STATE.md on failure (atomic so the revert itself is safe)
+    if (backupState) atomicWrite(STATE_FILE, backupState);
     return output(fail("WRITE_ERROR", e.message));
   }
 
   // Skill outcome scoring — log transition for analytics
-  _trace("state-transition", {
-    result: "allow",
+  _trace("state-transition", "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({
@@ -544,6 +638,19 @@ function cmdTransition(opts) {
 function cmdInit(opts) {
   if (!opts.project) return output(fail("MISSING_ARG", "--project required"));
 
+  // Refuse to clobber an active project unless --force.
+  // Lifetime preservation runs lower in this fn — but current-phase fields
+  // (phase, status, wave, tasks_done, tasks_total, gap_cycles) ARE wiped
+  // on init, which is a footgun for an in-progress project.
+  if (!opts.force && fs.existsSync(STATE_FILE)) {
+    return output(
+      fail(
+        "ALREADY_INITIALIZED",
+        "Project already initialized at .planning/STATE.md. Use --force to re-initialize (preserves lifetime, resets current phase)."
+      )
+    );
+  }
+
   // Parse phases
   let phases = [];
   if (opts.phases) {
@@ -591,12 +698,29 @@ function cmdInit(opts) {
     resume: "—",
   };
 
-  // Build tracking — current-phase fields reset, lifetime fields preserved
+  // Defensive lifetime hydrate: even if `prevLife.lifetime` is partial (an
+  // older tracking.json missing some keys), the spread would leave gaps that
+  // later `+=` would NaN. Build with safe defaults, then overlay.
+  const defaultLifetime = {
+    tasks_completed: 0,
+    phases_completed: 0,
+    milestones_completed: 0,
+    total_phases: 0,
+    last_closed_milestone: 0,
+  };
+  const lifetime = prevLife
+    ? { ...defaultLifetime, ...(prevLife.lifetime || {}) }
+    : { ...defaultLifetime };
+
+  // Build tracking — current-phase fields reset, lifetime + identity preserved
   const t = {
     project: opts.project,
     client: opts.client || (prevLife ? prevLife.client : ""),
     type: opts.type || (prevLife ? prevLife.type : ""),
     assigned_to: opts.assigned_to || (prevLife ? prevLife.assigned_to : ""),
+    team_id: opts.team_id || (prevLife ? prevLife.team_id || "" : ""),
+    project_id: opts.project_id || (prevLife ? prevLife.project_id || "" : ""),
+    git_remote: opts.git_remote || (prevLife ? prevLife.git_remote || "" : ""),
     milestone: prevLife ? prevLife.milestone : 1,
     phase: 1,
     phase_name: phases[0].name,
@@ -608,16 +732,16 @@ function cmdInit(opts) {
     verification: "pending",
     gap_cycles: {},
     blockers: [],
+    session_started_at: now,
     last_updated: now,
+    last_pushed_at: prevLife ? prevLife.last_pushed_at || "" : "",
     last_commit: prevLife ? prevLife.last_commit : "",
+    build_count: prevLife ? (prevLife.build_count || 0) : 0,
+    deploy_count: prevLife ? (prevLife.deploy_count || 0) : 0,
     deployed_url: prevLife ? prevLife.deployed_url : "",
     notes: "",
-    lifetime: prevLife ? { ...prevLife.lifetime } : {
-      tasks_completed: 0,
-      phases_completed: 0,
-      milestones_completed: 0,
-      total_phases: 0,
-    },
+    submitted_by: opts.assigned_to || (prevLife ? prevLife.submitted_by || "" : ""),
+    lifetime,
   };
   // lifetime.total_phases starts at 0 for new projects. It accumulates only via
   // close-milestone (which adds current total_phases before the next init).
@@ -840,6 +964,10 @@ function cmdValidatePlan(opts) {
 }
 
 // ─── Close Milestone ─────────────────────────────────────
+// Idempotent: a sentinel `lifetime.last_closed_milestone` records the most
+// recently closed milestone so re-running close-milestone (e.g., after a
+// hiccup) does NOT double-count. To re-close a milestone deliberately, pass
+// --force.
 function cmdCloseMilestone(opts) {
   const t = readTracking();
   const s = parseStateMd(readState());
@@ -849,8 +977,22 @@ function cmdCloseMilestone(opts) {
   ensureLifetime(t);
 
   const closedMilestone = t.milestone || 1;
+  if (
+    !opts.force &&
+    typeof t.lifetime.last_closed_milestone === "number" &&
+    t.lifetime.last_closed_milestone >= closedMilestone
+  ) {
+    return output(
+      fail(
+        "ALREADY_CLOSED",
+        `Milestone ${closedMilestone} was already closed (last_closed_milestone=${t.lifetime.last_closed_milestone}). Use --force to close again.`
+      )
+    );
+  }
+
   t.lifetime.milestones_completed += 1;
   t.lifetime.total_phases += (parseInt(t.total_phases) || 0);
+  t.lifetime.last_closed_milestone = closedMilestone;
   t.milestone = closedMilestone + 1;
   t.last_updated = new Date().toISOString();
 
@@ -871,6 +1013,83 @@ function cmdCloseMilestone(opts) {
   });
 }
 
+// ─── Backfill Lifetime ───────────────────────────────────
+// Reconstructs lifetime counters from STATE.md roadmap + plan files.
+// Safe to run multiple times (idempotent — recalculates from source).
+function cmdBackfillLifetime(opts) {
+  const t = readTracking();
+  const s = parseStateMd(readState());
+  if (!t || !s) {
+    return output(fail("NO_PROJECT", "No .planning/ found."));
+  }
+  ensureLifetime(t);
+
+  let phasesCompleted = 0;
+  let tasksCompleted = 0;
+
+  // Count completed phases from roadmap table
+  for (const p of s.phases) {
+    const st = (p.status || "").toLowerCase();
+    if (st === "verified" || st === "completed" || st === "complete") {
+      phasesCompleted++;
+
+      // Count tasks from that phase's plan file
+      const planFile = path.join(PLANNING, `phase-${p.num}-plan.md`);
+      const gapsPlanFile = path.join(PLANNING, `phase-${p.num}-gaps-plan.md`);
+      for (const f of [planFile, gapsPlanFile]) {
+        try {
+          if (fs.existsSync(f)) {
+            const content = fs.readFileSync(f, "utf8");
+            const taskHeaders = content.match(/^## Task \d+/gm);
+            if (taskHeaders) tasksCompleted += taskHeaders.length;
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // Also count the current phase if it's past built (tasks exist but phase not yet verified)
+  const currentStatus = (t.status || "").toLowerCase();
+  if (currentStatus === "built" || currentStatus === "verified") {
+    // Current phase tasks are already in t.tasks_done — add if not already counted
+    const currentPhaseAlreadyCounted = s.phases.some(
+      (p) => p.num === t.phase && ["verified", "completed", "complete"].includes((p.status || "").toLowerCase())
+    );
+    if (!currentPhaseAlreadyCounted && t.tasks_done > 0) {
+      tasksCompleted += t.tasks_done;
+    }
+  }
+
+  const previous = { ...t.lifetime };
+
+  // Use Math.max — backfill must NEVER reduce lifetime counters. If the user
+  // ran close-milestone previously (rolling phases into lifetime) and then
+  // calls backfill, the recomputed value reflects only the current milestone
+  // and would otherwise destroy the historical accumulation.
+  t.lifetime.phases_completed = Math.max(t.lifetime.phases_completed || 0, phasesCompleted);
+  t.lifetime.tasks_completed = Math.max(t.lifetime.tasks_completed || 0, tasksCompleted);
+  // total_phases is accumulated by close-milestone only — backfill leaves it.
+  t.last_updated = new Date().toISOString();
+
+  writeTracking(t);
+
+  _trace("backfill-lifetime", "allow", {
+    previous,
+    computed: t.lifetime,
+    phases_scanned: s.phases.length,
+  });
+
+  output({
+    ok: true,
+    action: "backfill-lifetime",
+    previous,
+    computed: t.lifetime,
+    phases_scanned: s.phases.length,
+    phases_completed: phasesCompleted,
+    tasks_completed: tasksCompleted,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -881,30 +1100,51 @@ function output(obj) {
 const [cmd, ...rest] = process.argv.slice(2);
 const opts = parseArgs(rest);
 
-switch (cmd) {
-  case "check":
-    cmdCheck(opts);
-    break;
-  case "transition":
-    cmdTransition(opts);
-    break;
-  case "init":
-    cmdInit(opts);
-    break;
-  case "fix":
-    cmdFix(opts);
-    break;
-  case "validate-plan":
-    cmdValidatePlan(opts);
-    break;
-  case "close-milestone":
-    cmdCloseMilestone(opts);
-    break;
-  default:
-    output(
-      fail(
-        "UNKNOWN_COMMAND",
-        `Usage: state.js <check|transition|init|fix|validate-plan> [--options]`
-      )
-    );
+// Mutators must hold the .planning/.state.lock for the duration of their
+// dual STATE.md + tracking.json writes. Read commands (check, validate-plan)
+// don't need the lock. The lock is best-effort: if it can't be acquired
+// inside acquireLock's timeout, the command proceeds anyway — we'd rather
+// risk a rare race than hard-block the user.
+const READ_ONLY = new Set(["check", "validate-plan"]);
+let __lock = null;
+if (!READ_ONLY.has(cmd)) {
+  __lock = acquireLock();
+  process.on("exit", () => releaseLock(__lock));
+  process.on("SIGINT", () => { releaseLock(__lock); process.exit(130); });
+  process.on("SIGTERM", () => { releaseLock(__lock); process.exit(143); });
+}
+
+try {
+  switch (cmd) {
+    case "check":
+      cmdCheck(opts);
+      break;
+    case "transition":
+      cmdTransition(opts);
+      break;
+    case "init":
+      cmdInit(opts);
+      break;
+    case "fix":
+      cmdFix(opts);
+      break;
+    case "validate-plan":
+      cmdValidatePlan(opts);
+      break;
+    case "close-milestone":
+      cmdCloseMilestone(opts);
+      break;
+    case "backfill-lifetime":
+      cmdBackfillLifetime(opts);
+      break;
+    default:
+      output(
+        fail(
+          "UNKNOWN_COMMAND",
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime> [--options]`
+        )
+      );
+  }
+} finally {
+  releaseLock(__lock);
 }

package/bin/statusline.js

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

package/docs/erp-contract.md

@@ -34,6 +34,9 @@ Content-Type: application/json
 ```json
 {
   "project": "client-project-name",
+  "project_id": "qs-acme-portal",
+  "team_id": "qualia-solutions",
+  "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
   "milestone": 2,
   "phase": 2,
@@ -44,14 +47,19 @@ Content-Type: application/json
   "tasks_total": 5,
   "verification": "pass",
   "gap_cycles": 0,
+  "build_count": 12,
+  "deploy_count": 3,
   "deployed_url": "https://client.vercel.app",
   "lifetime": {
     "tasks_completed": 23,
     "phases_completed": 8,
     "milestones_completed": 1,
-    "total_phases": 8
+    "total_phases": 8,
+    "last_closed_milestone": 1
   },
+  "session_started_at": "2026-04-12T13:45:00Z",
   "session_duration_minutes": 45,
+  "last_pushed_at": "2026-04-12T14:25:00Z",
   "commits": ["abc1234", "def5678"],
   "notes": "Completed auth flow, dashboard layout, and API routes.",
   "submitted_by": "Fawzi Goussous",
@@ -59,6 +67,12 @@ Content-Type: application/json
 }
 ```
 
+**`gap_cycles` polymorphism (v3.5+):** in `tracking.json` (the file the ERP
+reads from git for passive monitoring) `gap_cycles` is an OBJECT keyed by
+phase number — `{"1": 0, "2": 1}`. In the POST `/api/v1/reports` body,
+`/qualia-report` flattens to a NUMBER for the current phase. Receivers must
+accept both shapes: if object, use `gap_cycles[String(phase)] || 0`.
+
 **Response (200 OK):**
 ```json
 {
@@ -161,7 +175,14 @@ 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) |
-| lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases |
+| lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases, last_closed_milestone |
+| project_id | string | recommended (v3.6+) | Stable per-project identifier — preferred dedupe key over `project` slug. Survives directory renames. |
+| team_id | string | recommended (v3.6+) | Installation's team identifier. Composite `(team_id, project_id)` is the canonical project key. |
+| git_remote | string | optional (v3.6+) | e.g. `github.com/QualiasolutionsCY/foo`. Lets the ERP correlate tracking with the source repo. |
+| session_started_at | string | optional (v3.6+) | ISO 8601 — when the current Claude Code session began. |
+| last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |
+| build_count | number | optional (v3.6+) | Lifetime build counter. |
+| deploy_count | number | optional (v3.6+) | Lifetime deploy counter. |
 
 All other fields are optional but recommended for complete reporting.