qualia-framework 3.6.0 → 4.0.3

package/bin/qualia-ui.js

@@ -17,6 +17,9 @@
 //   next <command>                       — "Run: /qualia-X" footer
 //   end <status> [next-command]          — closing banner with optional next
 //   update <current> <latest>            — sticky framework update banner
+//   plan-summary <path/to/plan.md>       — story-file dashboard for a plan
+//   journey-tree [path/to/JOURNEY.md]    — ladder view of all milestones, current highlighted
+//   milestone-complete <num> <name> <next> — celebration banner on milestone close
 
 const fs = require("fs");
 const path = require("path");
@@ -63,6 +66,11 @@ const ACTIONS = {
   welcome:    { label: "WELCOME",          glyph: "⬢" },
   test:       { label: "TESTING",          glyph: "⊡" },
   analytics:  { label: "ANALYTICS",        glyph: "◈" },
+  milestone:  { label: "MILESTONE",        glyph: "◆" },
+  journey:    { label: "JOURNEY",          glyph: "◯" },
+  auto:       { label: "AUTO MODE",        glyph: "⚡" },
+  research:   { label: "RESEARCH",         glyph: "◱" },
+  roadmap:    { label: "ROADMAP",          glyph: "◐" },
 };
 
 // ─── State Reading ───────────────────────────────────────
@@ -259,6 +267,261 @@ function cmdEnd(status, nextCmd) {
   console.log("");
 }
 
+// ─── Journey Tree (the North Star visualization) ────────
+// Renders JOURNEY.md as an ASCII ladder with the current milestone highlighted.
+// Called after /qualia-new to show the full arc, and by /qualia (router) to
+// orient the user on "you are here".
+function cmdJourneyTree(journeyPath) {
+  const p = journeyPath || ".planning/JOURNEY.md";
+  let content = "";
+  try {
+    content = fs.readFileSync(p, "utf8");
+  } catch {
+    console.log(`  ${DIM}No JOURNEY.md at ${p}${RESET}`);
+    return;
+  }
+
+  const state = readState();
+  const currentMilestone = state && state.ok ? (state.milestone || 1) : 1;
+
+  // Parse milestone blocks: "## Milestone N · Name" or "## Milestone N · Handoff"
+  const milestoneRe = /^## Milestone (\d+)\s*·\s*(.+?)\s*(?:\[[^\]]*\])?\r?$/gm;
+  const milestones = [];
+  let m;
+  while ((m = milestoneRe.exec(content)) !== null) {
+    const num = parseInt(m[1]);
+    const name = m[2].trim();
+    // Extract the section body to pull Why-now and phases
+    const startIdx = m.index + m[0].length;
+    const nextMatch = milestoneRe.exec(content);
+    const endIdx = nextMatch ? nextMatch.index : content.length;
+    milestoneRe.lastIndex = startIdx; // rewind for next iteration
+    const body = content.slice(startIdx, endIdx);
+
+    const whyMatch = body.match(/\*\*Why now:\*\*\s*(.+?)\r?$/m);
+    const why = whyMatch ? whyMatch[1].trim() : "";
+
+    const phaseNames = [];
+    const phaseRe = /^\d+\.\s+\*\*([^*]+)\*\*/gm;
+    let pm;
+    while ((pm = phaseRe.exec(body)) !== null) {
+      phaseNames.push(pm[1].trim());
+    }
+
+    milestones.push({ num, name, why, phaseNames });
+    if (nextMatch) milestoneRe.lastIndex = nextMatch.index;
+    else break;
+  }
+
+  if (milestones.length === 0) {
+    console.log(`  ${DIM}JOURNEY.md has no milestones to render${RESET}`);
+    return;
+  }
+
+  // Project name from frontmatter if present
+  const projMatch = content.match(/^project:\s*"?(.+?)"?\s*$/m);
+  const projName = projMatch ? projMatch[1] : projectName();
+
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projName}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log(`  ${DIM}${milestones.length} milestones · currently at M${currentMilestone}${RESET}`);
+  console.log("");
+
+  for (let i = 0; i < milestones.length; i++) {
+    const ms = milestones[i];
+    const isCurrent = ms.num === currentMilestone;
+    const isPast = ms.num < currentMilestone;
+    const isFuture = ms.num > currentMilestone;
+    const isHandoff = /handoff/i.test(ms.name);
+
+    let marker;
+    let labelColor;
+    let connector = "│";
+
+    if (isPast) {
+      marker = `${GREEN}●${RESET}`;
+      labelColor = DIM;
+    } else if (isCurrent) {
+      marker = `${TEAL}${BOLD}◆${RESET}`;
+      labelColor = TEAL + BOLD;
+    } else {
+      marker = `${DIM2}○${RESET}`;
+      labelColor = WHITE;
+    }
+
+    const tag = isCurrent
+      ? ` ${TEAL}${BOLD}[CURRENT]${RESET}`
+      : isPast
+      ? ` ${GREEN}[shipped]${RESET}`
+      : isHandoff
+      ? ` ${DIM2}[FINAL]${RESET}`
+      : "";
+
+    console.log(`  ${marker} ${labelColor}M${ms.num} · ${ms.name}${RESET}${tag}`);
+
+    if (ms.why && (isCurrent || isFuture)) {
+      const shortWhy = ms.why.length > 80 ? ms.why.slice(0, 77) + "…" : ms.why;
+      console.log(`  ${DIM2}│${RESET}   ${DIM}${shortWhy}${RESET}`);
+    }
+
+    if (ms.phaseNames.length > 0 && (isCurrent || isHandoff)) {
+      const phaseList = ms.phaseNames.slice(0, 4).join(` ${DIM2}→${RESET} ${DIM}`);
+      console.log(`  ${DIM2}│${RESET}   ${DIM}${phaseList}${DIM}${ms.phaseNames.length > 4 ? ` +${ms.phaseNames.length - 4}` : ""}${RESET}`);
+    }
+
+    // Connector between milestones (skip after last)
+    if (i < milestones.length - 1) {
+      console.log(`  ${DIM2}│${RESET}`);
+    }
+  }
+  console.log("");
+  console.log(`  ${RULE_DIM}`);
+}
+
+// ─── Milestone Complete (celebration banner) ─────────────
+// Shown at milestone-boundary in auto mode, and by /qualia-milestone manually.
+function cmdMilestoneComplete(num, name, nextName) {
+  console.log("");
+  console.log(`  ${GREEN}${BOLD}◆${RESET} ${WHITE}${BOLD}MILESTONE ${num} SHIPPED${RESET} ${DIM}·${RESET} ${TEAL}${name || ""}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextName) {
+    if (/handoff/i.test(nextName)) {
+      console.log(`  ${DIM}Next${RESET}      ${TEAL}${BOLD}${nextName}${RESET} ${DIM}· the final milestone${RESET}`);
+    } else {
+      console.log(`  ${DIM}Next${RESET}      ${WHITE}${nextName}${RESET}`);
+    }
+  } else {
+    console.log(`  ${GREEN}${BOLD}PROJECT COMPLETE${RESET} ${DIM}· last milestone reached${RESET}`);
+  }
+  console.log(`  ${RULE_DIM}`);
+  console.log("");
+}
+
+// ─── Plan Summary (story-file dashboard) ─────────────────
+// Renders a polished overview of a plan file: phase goal, tasks grouped by wave,
+// persona chips, dependency lines, AC count, validation count. Called by
+// /qualia-plan after the planner and plan-checker finish.
+function cmdPlanSummary(planPath) {
+  if (!planPath) {
+    console.error("Usage: qualia-ui.js plan-summary <path-to-plan.md>");
+    process.exit(1);
+  }
+  let content = "";
+  try {
+    content = fs.readFileSync(planPath, "utf8");
+  } catch (e) {
+    console.error(`Cannot read plan: ${e.message}`);
+    process.exit(1);
+  }
+
+  // ─ Parse frontmatter + phase header ─
+  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  const fm = {};
+  if (fmMatch) {
+    for (const line of fmMatch[1].split("\n")) {
+      const m = line.match(/^(\w+):\s*(.+?)\s*$/);
+      if (m) fm[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    }
+  }
+  const phaseNum = fm.phase || "?";
+  const phaseGoal = fm.goal || "";
+  const phaseTitleMatch = content.match(/^# Phase \d+:?\s*(.+?)\r?$/m);
+  const phaseTitle = phaseTitleMatch ? phaseTitleMatch[1].trim() : `Phase ${phaseNum}`;
+  const whyPhaseMatch = content.match(/^\*\*Why this phase:\*\*\s*(.+?)\r?$/m);
+  const whyPhase = whyPhaseMatch ? whyPhaseMatch[1].trim() : "";
+
+  // ─ Parse tasks ─
+  const taskBlocks = content.split(/^(?=## Task \d+)/m).filter((b) => /^## Task \d+/.test(b));
+  const tasks = taskBlocks.map((block) => {
+    const titleMatch = block.match(/^## Task (\d+)\s*—\s*(.+?)\r?$/m);
+    const wave = parseInt((block.match(/\*\*Wave:\*\*\s*(\d+)/) || [])[1]) || 1;
+    const persona = ((block.match(/\*\*Persona:\*\*\s*(.+?)\r?$/m) || [])[1] || "").trim();
+    const deps = ((block.match(/\*\*Depends on:\*\*\s*(.+?)\r?$/m) || [])[1] || "").trim();
+    const why = ((block.match(/\*\*Why:\*\*\s*([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "").trim().replace(/\s+/g, " ");
+    const acBlock = (block.match(/\*\*Acceptance Criteria:\*\*\s*([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "";
+    const acCount = (acBlock.match(/^[-*]\s+/gm) || []).length;
+    const validationBlock = (block.match(/\*\*Validation:\*\*[^\n]*\n([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "";
+    const validationCount = (validationBlock.match(/^[-*]\s+/gm) || []).length;
+    return {
+      num: titleMatch ? parseInt(titleMatch[1]) : 0,
+      title: titleMatch ? titleMatch[2].trim() : "",
+      wave,
+      persona: (() => {
+        // Strip placeholder syntax ({...}), then only accept the known set
+        const cleaned = persona.replace(/[{}]/g, "").trim().toLowerCase();
+        const valid = ["security", "architect", "ux", "frontend", "backend", "performance"];
+        return valid.includes(cleaned) ? cleaned : "";
+      })(),
+      deps,
+      why,
+      acCount,
+      validationCount,
+    };
+  });
+
+  const contractCount = (content.match(/^### Contract for Task \d+/gm) || []).length;
+  const totalWaves = tasks.length > 0 ? Math.max(...tasks.map((t) => t.wave)) : 0;
+
+  // ─ Render ─
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}▣${RESET} ${WHITE}${BOLD}PLAN${RESET} ${DIM}▸${RESET} ${WHITE}Phase ${phaseNum} — ${phaseTitle}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (phaseGoal) {
+    console.log(`  ${DIM}Goal${RESET}      ${WHITE}${phaseGoal}${RESET}`);
+  }
+  if (whyPhase) {
+    console.log(`  ${DIM}Why${RESET}       ${WHITE}${whyPhase}${RESET}`);
+  }
+  console.log(`  ${DIM}Shape${RESET}     ${TEAL}${tasks.length}${RESET} ${DIM}tasks${RESET} ${DIM}·${RESET} ${TEAL}${totalWaves}${RESET} ${DIM}waves${RESET} ${DIM}·${RESET} ${TEAL}${contractCount}${RESET} ${DIM}contracts${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+
+  // Persona palette
+  const personaColors = {
+    security: RED,
+    architect: BLUE,
+    ux: "\x1b[38;2;255;182;193m",
+    frontend: TEAL,
+    backend: "\x1b[38;2;186;85;211m",
+    performance: YELLOW,
+  };
+
+  for (let w = 1; w <= totalWaves; w++) {
+    const waveTasks = tasks.filter((t) => t.wave === w);
+    if (!waveTasks.length) continue;
+    console.log("");
+    console.log(`  ${TEAL}»${RESET} ${WHITE}${BOLD}Wave ${w}${RESET} ${DIM}(${waveTasks.length} ${waveTasks.length === 1 ? "task" : "tasks"}, parallel)${RESET}`);
+    for (const t of waveTasks) {
+      const personaChip = t.persona
+        ? ` ${(personaColors[t.persona] || DIM)}[${t.persona}]${RESET}`
+        : "";
+      // Only show the dep chip if it names a real task reference.
+      // Suppress blanks, "none", and template placeholders like "{none | Task N}".
+      const depsClean = (t.deps || "").trim();
+      const depsIsReal =
+        depsClean &&
+        !/^none$/i.test(depsClean) &&
+        !/[{}]/.test(depsClean);
+      const depChip = depsIsReal ? ` ${DIM}← ${depsClean}${RESET}` : "";
+      console.log(`    ${DIM}${t.num}.${RESET} ${WHITE}${t.title}${RESET}${personaChip}${depChip}`);
+      // Suppress placeholder Why text (contains {} braces) to keep the
+      // dashboard clean when the planner hasn't filled it in yet.
+      if (t.why && !/[{}]/.test(t.why)) {
+        const shortWhy = t.why.length > 90 ? t.why.slice(0, 87) + "…" : t.why;
+        console.log(`       ${DIM}${shortWhy}${RESET}`);
+      }
+      const metrics = [];
+      if (t.acCount > 0) metrics.push(`${TEAL}${t.acCount}${RESET} ${DIM}AC${RESET}`);
+      if (t.validationCount > 0) metrics.push(`${TEAL}${t.validationCount}${RESET} ${DIM}checks${RESET}`);
+      if (metrics.length) {
+        console.log(`       ${metrics.join(` ${DIM}·${RESET} `)}`);
+      }
+    }
+  }
+  console.log("");
+  console.log(`  ${RULE_DIM}`);
+}
+
 function cmdUpdate(current, latest) {
   if (!current || !latest) return;
   console.log("");
@@ -291,9 +554,12 @@ switch (cmd) {
   case "next":     cmdNext(rest.join(" ")); break;
   case "end":      cmdEnd(rest[0], rest.slice(1).join(" ")); break;
   case "update":   cmdUpdate(rest[0], rest[1]); break;
+  case "plan-summary": cmdPlanSummary(rest[0]); break;
+  case "journey-tree": cmdJourneyTree(rest[0]); break;
+  case "milestone-complete": cmdMilestoneComplete(rest[0], rest[1], rest.slice(2).join(" ")); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update|plan-summary|journey-tree|milestone-complete> [args]`
     );
     process.exit(1);
 }

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;
 }
 
@@ -140,6 +192,8 @@ function writeTracking(t) {
 function ensureLifetime(t) {
   if (!t) return 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 (!t.lifetime || typeof t.lifetime !== "object") {
     t.lifetime = {
       tasks_completed: 0,
@@ -345,9 +399,13 @@ function checkPreconditions(current, target, opts) {
     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')");
+    // Accept either legacy "**Done when:**" or story-file "**Acceptance Criteria:**"
+    // so old in-flight plans don't break on upgrade.
     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`);
+    const acCount = (planContent.match(/\*\*Acceptance Criteria:\*\*/g) || []).length;
+    const anchors = doneWhenCount + acCount;
+    if (anchors < taskHeaders.length)
+      return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${anchors} 'Done when:' or 'Acceptance Criteria:' anchors`);
   }
 
   if (target === "verified") {
@@ -436,6 +494,8 @@ function cmdCheck(opts) {
     status: s.status,
     assigned_to: s.assigned_to,
     milestone: t.milestone || 1,
+    milestone_name: t.milestone_name || "",
+    milestones: t.milestones || [],
     lifetime: t.lifetime,
     verification: t.verification || "pending",
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
@@ -550,6 +610,7 @@ function cmdTransition(opts) {
     t.tasks_done = parseInt(opts.tasks_done) || 0;
     t.tasks_total = parseInt(opts.tasks_total) || 0;
     t.wave = parseInt(opts.wave) || 0;
+    t.build_count = (parseInt(t.build_count) || 0) + 1;
     s.last_activity = `Phase ${phase} built (${t.tasks_done}/${t.tasks_total} tasks)`;
     if (s.phases[phase - 1]) s.phases[phase - 1].status = "built";
   }
@@ -601,16 +662,28 @@ function cmdTransition(opts) {
 
   if (target === "shipped") {
     t.deployed_url = opts.deployed_url || "";
+    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));
   }
 
@@ -712,6 +785,9 @@ function cmdInit(opts) {
     ? { ...defaultLifetime, ...(prevLife.lifetime || {}) }
     : { ...defaultLifetime };
 
+  // Preserve milestones array across re-init (v4: milestone summaries for ERP tree).
+  const prevMilestones = (prevLife && Array.isArray(prevLife.milestones)) ? prevLife.milestones : [];
+
   // Build tracking — current-phase fields reset, lifetime + identity preserved
   const t = {
     project: opts.project,
@@ -722,6 +798,8 @@ function cmdInit(opts) {
     project_id: opts.project_id || (prevLife ? prevLife.project_id || "" : ""),
     git_remote: opts.git_remote || (prevLife ? prevLife.git_remote || "" : ""),
     milestone: prevLife ? prevLife.milestone : 1,
+    milestone_name: opts.milestone_name || (prevLife ? prevLife.milestone_name || "" : ""),
+    milestones: prevMilestones,
     phase: 1,
     phase_name: phases[0].name,
     total_phases: totalPhases,
@@ -854,12 +932,15 @@ function cmdValidatePlan(opts) {
     errors.push("No task headers found (expected '## Task N — title')");
   }
 
-  // Check "Done when" exists for each task
+  // Check "Done when" OR "Acceptance Criteria" anchor exists for each task
+  // (story-file format uses Acceptance Criteria; legacy format uses Done when)
   const taskCount = taskHeaders ? taskHeaders.length : 0;
   const doneWhenCount = (content.match(/\*\*Done when:\*\*/g) || []).length;
-  if (doneWhenCount < taskCount) {
+  const acCount = (content.match(/\*\*Acceptance Criteria:\*\*/g) || []).length;
+  const anchors = doneWhenCount + acCount;
+  if (anchors < taskCount) {
     errors.push(
-      `${taskCount} tasks but only ${doneWhenCount} 'Done when:' entries`
+      `${taskCount} tasks but only ${anchors} 'Done when:' or 'Acceptance Criteria:' anchors`
     );
   }
 
@@ -958,6 +1039,7 @@ function cmdValidatePlan(opts) {
     phase,
     task_count: taskCount,
     done_when_count: doneWhenCount,
+    ac_count: acCount,
     contract_count: contractCount,
     warnings: warnings.length > 0 ? warnings : undefined,
   });
@@ -990,10 +1072,76 @@ function cmdCloseMilestone(opts) {
     );
   }
 
+  // ─── v4 guard rails ─────────────────────────────────────
+  // A milestone is only closable if it actually acted like one:
+  //   (a) all its phases are verified/polished/completed, AND
+  //   (b) it had ≥ 2 phases (so a 1-phase "milestone" is forced back to being a phase).
+  // Both guards are bypassable with --force for retroactive bookkeeping.
+  if (!opts.force) {
+    const totalPhases = parseInt(t.total_phases) || s.phases.length || 0;
+    if (totalPhases < 2) {
+      return output(
+        fail(
+          "MILESTONE_TOO_SMALL",
+          `Milestone ${closedMilestone} has only ${totalPhases} phase(s). A milestone needs ≥ 2 phases OR must be a shipped release gate. Use --force if this is intentional (e.g. a preview/demo milestone).`
+        )
+      );
+    }
+    const unfinished = s.phases.filter((p) => {
+      const st = (p.status || "").toLowerCase();
+      return !(st === "verified" || st === "polished" || st === "completed" || st === "complete");
+    });
+    if (unfinished.length > 0) {
+      return output(
+        fail(
+          "MILESTONE_NOT_READY",
+          `Milestone ${closedMilestone} has ${unfinished.length} unfinished phase(s): ${unfinished.map((p) => `${p.num}:${p.name}`).join(", ")}. Verify them first, or use --force.`
+        )
+      );
+    }
+  }
+
+  // ─── Append a summary to milestones[] so the ERP can render the tree ──
+  // This is the minimal metadata needed to reconstruct "milestone N of the
+  // project contained these phases" without replaying git history.
+  const phasesCompleted = s.phases.filter((p) => {
+    const st = (p.status || "").toLowerCase();
+    return st === "verified" || st === "polished" || st === "completed" || st === "complete";
+  }).length;
+  // tasks_completed for THIS milestone = lifetime.tasks_completed minus the
+  // sum of tasks already counted in prior milestones[] entries. This gives
+  // the correct per-milestone count even though `t.tasks_done` only reflects
+  // the current phase, not the cumulative milestone total.
+  const priorMilestoneTasks = Array.isArray(t.milestones)
+    ? t.milestones.reduce((sum, m) => sum + (parseInt(m && m.tasks_completed) || 0), 0)
+    : 0;
+  const tasksCompletedThisMilestone = Math.max(
+    0,
+    (parseInt(t.lifetime && t.lifetime.tasks_completed) || 0) - priorMilestoneTasks
+  );
+  const summary = {
+    num: closedMilestone,
+    name: t.milestone_name || `Milestone ${closedMilestone}`,
+    total_phases: parseInt(t.total_phases) || s.phases.length || 0,
+    phases_completed: phasesCompleted,
+    tasks_completed: tasksCompletedThisMilestone,
+    shipped_url: t.deployed_url || "",
+    closed_at: new Date().toISOString(),
+  };
+  t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
+  // Idempotency: don't duplicate if the same milestone number is already logged.
+  const existing = t.milestones.findIndex((m) => m && m.num === closedMilestone);
+  if (existing >= 0) {
+    t.milestones[existing] = summary;
+  } else {
+    t.milestones.push(summary);
+  }
+
   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.milestone_name = ""; // cleared; /qualia-milestone reads next one from JOURNEY.md
   t.last_updated = new Date().toISOString();
 
   writeTracking(t);
@@ -1108,6 +1256,10 @@ const opts = parseArgs(rest);
 const READ_ONLY = new Set(["check", "validate-plan"]);
 let __lock = null;
 if (!READ_ONLY.has(cmd)) {
+  // Before acquiring the lock, recover from any journal left by a crashed
+  // previous mutator. Runs for mutators only; read commands should still
+  // return the actual on-disk state even if it's mid-recovery.
+  try { recoverFromJournal(); } catch {}
   __lock = acquireLock();
   process.on("exit", () => releaseLock(__lock));
   process.on("SIGINT", () => { releaseLock(__lock); process.exit(130); });

package/bin/statusline.js

@@ -175,7 +175,10 @@ try {
 // ─── Memory count ────────────────────────────────────────
 let MEMORY_COUNT = 0;
 try {
-  const dirKey = DIR.replace(/\//g, "-");
+  // Claude Code uses a hyphenated encoding of the project directory. Replace
+  // BOTH forward and backward slashes so Windows installs (where DIR contains
+  // `\`) get a correct key and the memory count renders.
+  const dirKey = DIR.replace(/[\/\\]/g, "-");
   const memDir = path.join(HOME, ".claude", "projects", dirKey, "memory");
   if (fs.existsSync(memDir)) {
     const files = fs.readdirSync(memDir).filter(f => f.endsWith(".md") && f !== "MEMORY.md");

package/docs/erp-contract.md

@@ -39,6 +39,16 @@ Content-Type: application/json
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
   "client": "Client Name",
   "milestone": 2,
+  "milestone_name": "Core Product",
+  "milestones": [
+    {
+      "num": 1,
+      "name": "Foundation",
+      "closed_at": "2026-04-10T18:00:00Z",
+      "phases_completed": 3,
+      "tasks_completed": 12
+    }
+  ],
   "phase": 2,
   "phase_name": "Authentication & Dashboard",
   "total_phases": 4,
@@ -175,6 +185,8 @@ Authorization: Bearer <api-key>
 | submitted_by | string | yes | Team member name |
 | submitted_at | string | yes | ISO 8601 timestamp |
 | milestone | number | recommended | Current milestone number (1-indexed) |
+| milestone_name | string | recommended (v4+) | Human name of the current milestone — from JOURNEY.md / tracking.json |
+| milestones | array | recommended (v4+) | Array of closed milestone summaries: `{num, name, closed_at, phases_completed, tasks_completed}`. Renders the journey tree on the ERP. |
 | lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases, last_closed_milestone |
 | project_id | string | recommended (v3.6+) | Stable per-project identifier — preferred dedupe key over `project` slug. Survives directory renames. |
 | team_id | string | recommended (v3.6+) | Installation's team identifier. Composite `(team_id, project_id)` is the canonical project key. |