qualia-framework 4.3.0 → 4.5.0

package/bin/slop-detect.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * slop-detect — Standalone anti-pattern scanner for Qualia projects.
+ *
+ * Usage:
+ *   node bin/slop-detect.mjs                       # scan whole repo (default globs)
+ *   node bin/slop-detect.mjs path/to/file.tsx      # scan one file
+ *   node bin/slop-detect.mjs src/components/       # scan a directory
+ *   node bin/slop-detect.mjs --json                # machine-readable output
+ *   node bin/slop-detect.mjs --severity=critical   # only critical findings
+ *
+ * Exit codes:
+ *   0  no critical findings
+ *   1  one or more critical findings
+ *   2  invocation error
+ *
+ * Builder agents call this BEFORE commit. A non-zero exit blocks the commit.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, extname, relative, resolve } from "node:path";
+import { argv, exit, cwd } from "node:process";
+
+// ── Severity rubric (from rules/grounding.md) ─────────────────────────
+const CRITICAL = "critical";
+const HIGH = "high";
+const MEDIUM = "medium";
+const LOW = "low";
+
+// ── Anti-patterns ─────────────────────────────────────────────────────
+// Each rule: { id, severity, label, fileGlob, pattern, allow?, fix }
+const RULES = [
+  // ── CRITICAL: absolute bans (block commit) ──────────────────────────
+  {
+    id: "ABS-FONT",
+    severity: CRITICAL,
+    label: "Banned font (Inter/Roboto/Arial/system-ui/Space Grotesk)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(font-family|fontFamily)[^;{,]*(['"`])(Inter|Roboto|Arial|Helvetica|system-ui|Space\s*Grotesk)\b/i,
+    allow: /Inter\s*Display|Inter\s*Tight/,
+    fix: "Replace with a distinctive font (Fraunces, Geist, Söhne, JetBrains Mono, etc). See DESIGN.md §3.",
+  },
+  {
+    id: "ABS-PURPLE-GRAD",
+    severity: CRITICAL,
+    label: "Purple-blue gradient (the #1 AI-design tell)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(from-(blue|indigo|violet)-\d+\s+to-(purple|violet|fuchsia|pink)-\d+|from-(purple|violet|fuchsia|pink)-\d+\s+to-(blue|indigo|violet)-\d+|linear-gradient[^;]*(blue|indigo)[^;]*(purple|violet|fuchsia)|linear-gradient[^;]*(purple|violet|fuchsia)[^;]*(blue|indigo))/i,
+    fix: "Use one solid brand accent color. Emphasis via weight or size, not gradient text/bg.",
+  },
+  {
+    id: "ABS-GRADIENT-TEXT",
+    severity: CRITICAL,
+    label: "Gradient text (background-clip: text)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss|html|svelte|vue|astro)$/,
+    pattern: /(background-clip\s*:\s*text|bg-clip-text|-webkit-background-clip\s*:\s*text)/i,
+    fix: "Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.",
+  },
+  {
+    id: "ABS-PURE-BLACK-WHITE",
+    severity: CRITICAL,
+    label: "Pure #000 or #fff (untuned, generic)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /#(000000|FFFFFF|000|FFF)\b/,
+    allow: /shadow|outline|currentColor|var\(/i,
+    fix: "Tint every neutral toward brand hue. Use OKLCH with chroma 0.005-0.015. See design-laws.md §1.",
+  },
+  {
+    id: "ABS-HEX-IN-JSX",
+    severity: CRITICAL,
+    label: "Hardcoded hex color in JSX/TSX (use design tokens)",
+    fileGlob: /\.(tsx|jsx)$/,
+    pattern: /style=\{[^}]*['"]#[0-9a-fA-F]{3,8}['"]/,
+    fix: "Move color to a CSS custom property in DESIGN.md tokens. Reference via var(--name).",
+  },
+  {
+    id: "ABS-SIDE-STRIPE",
+    severity: CRITICAL,
+    label: "Side-stripe border (decorative border-left ≥2px)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /border-(left|right)\s*:\s*\d+(px|rem)\s+solid|border-l-(2|4|8)|border-r-(2|4|8)/,
+    allow: /focus|active|outline/,
+    fix: "Use full borders, background tints, leading icons, or nothing. See design-laws.md §8.",
+  },
+
+  // ── HIGH: strong tells ───────────────────────────────────────────────
+  {
+    id: "HI-MAX-W-CAP",
+    severity: HIGH,
+    label: "Hardcoded max-width container (no fluid full-width)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /(max-w-7xl|max-w-\[1200|max-w-\[1280|max-w-\[1440|max-width\s*:\s*1200|max-width\s*:\s*1280)/,
+    fix: "Use fluid padding: clamp(1rem, 5vw, 4rem). Cap content via max-width: 65ch on prose only.",
+  },
+  {
+    id: "HI-OUTLINE-NONE",
+    severity: HIGH,
+    label: "outline:none without focus replacement (a11y violation)",
+    fileGlob: /\.(tsx|jsx|ts|js|css|scss)$/,
+    pattern: /outline\s*:\s*none|outline-none/,
+    allow: /focus-visible|focus:ring|focus:outline/,
+    fix: "Replace with a visible focus ring: 2px offset, contrasting color. See design-laws.md §accessibility.",
+  },
+  {
+    id: "HI-IMG-NO-ALT",
+    severity: HIGH,
+    label: "<img> without alt attribute",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: /<img\s+(?![^>]*\balt=)[^>]*>/,
+    fix: "Every image needs alt text. Decorative: alt=\"\" + aria-hidden=\"true\". Meaningful: describe it.",
+  },
+  {
+    id: "HI-GENERIC-CTA",
+    severity: HIGH,
+    label: "Generic CTA copy (Get Started / Learn More / Click Here)",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro|md)$/,
+    pattern: />\s*(Get Started|Learn More|Click Here|Welcome to|Read More|Find Out More)\s*</i,
+    fix: "Name the action: 'Download invoice', 'Continue setup', 'Try the demo'.",
+  },
+  {
+    id: "HI-EM-DASH",
+    severity: HIGH,
+    label: "Em dash in user-facing copy (— or '--')",
+    // Scope: shipped UI files only. Markdown / docs prose is allowed em-dashes.
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: />\s*[^<]*[—][^<]*</,
+    fix: "Use commas, colons, semicolons, periods, or parentheses. See design-laws.md §7.",
+  },
+
+  // ── MEDIUM: noisy signals ────────────────────────────────────────────
+  {
+    id: "MED-CARD-GRID-3",
+    severity: MEDIUM,
+    label: "Three/four-column card grid (likely identical-card slop)",
+    fileGlob: /\.(tsx|jsx|html|svelte|vue|astro)$/,
+    pattern: /(grid-cols-3|grid-cols-4|grid-template-columns\s*:\s*repeat\(\s*[34]\s*,)/,
+    fix: "Vary card sizes and content shapes. Identical cards in a grid is the AI default hero pattern.",
+  },
+  {
+    id: "MED-GLASSMORPHISM",
+    severity: MEDIUM,
+    label: "Glassmorphism (backdrop-blur on multiple surfaces — likely default)",
+    fileGlob: /\.(tsx|jsx|css|scss)$/,
+    pattern: /(backdrop-blur|backdrop-filter\s*:\s*blur)/,
+    fix: "Glass effects are rare and purposeful, or nothing. Don't use them as default decoration.",
+  },
+  {
+    id: "MED-CONTAINER-DEPTH",
+    severity: MEDIUM,
+    label: "Possible container-depth >2 (card on card on pill)",
+    fileGlob: /\.(tsx|jsx)$/,
+    pattern: /<div[^>]*className="[^"]*\b(card|panel|surface)[^"]*"[^>]*>\s*<div[^>]*className="[^"]*\b(card|panel|surface)/,
+    fix: "Container depth max 2. Flatten nested cards into a single container with content.",
+  },
+  {
+    id: "MED-ANIMATE-LAYOUT",
+    severity: MEDIUM,
+    label: "Animating layout properties (causes reflow, jank)",
+    fileGlob: /\.(tsx|jsx|css|scss)$/,
+    pattern: /transition\s*:\s*(width|height|top|left|right|bottom|margin|padding)\s/,
+    fix: "Animate transform and opacity only. Layout properties trigger reflow.",
+  },
+  {
+    id: "MED-BOUNCE-EASING",
+    severity: MEDIUM,
+    label: "Bounce/elastic easing (banned per design-laws.md §6)",
+    fileGlob: /\.(tsx|jsx|css|scss|js|ts)$/,
+    pattern: /(bounce|elastic|backIn|backOut|cubic-bezier\([^)]*1\.\d+)/i,
+    fix: "Ease out with exponential curves: cubic-bezier(0.22, 1, 0.36, 1) or (0.16, 1, 0.3, 1).",
+  },
+
+  // ── LOW: cleanup ─────────────────────────────────────────────────────
+  {
+    id: "LOW-CONSOLE-LOG",
+    severity: LOW,
+    label: "console.log in production code",
+    fileGlob: /\.(tsx|jsx|ts|js)$/,
+    pattern: /console\.(log|debug)\(/,
+    allow: /\/\/\s*(debug|todo)|test\.|spec\./i,
+    fix: "Remove or replace with a proper logger.",
+  },
+];
+
+// ── File walker ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set([
+  "node_modules", ".next", "dist", "build", ".git", ".turbo",
+  "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
+  ".planning", ".qa-screenshots",
+]);
+
+function* walk(dir) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    if (name.startsWith(".") && !["src", "app", "components", "lib"].includes(name)) {
+      // skip dotfiles except known source dirs
+      if (SKIP_DIRS.has(name)) continue;
+    }
+    const path = join(dir, name);
+    let st;
+    try { st = statSync(path); } catch { continue; }
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue;
+      yield* walk(path);
+    } else if (st.isFile()) {
+      yield path;
+    }
+  }
+}
+
+// ── Scanner ───────────────────────────────────────────────────────────
+function scanFile(path) {
+  const findings = [];
+  let content;
+  try { content = readFileSync(path, "utf8"); } catch { return findings; }
+  const lines = content.split("\n");
+
+  for (const rule of RULES) {
+    if (!rule.fileGlob.test(path)) continue;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!rule.pattern.test(line)) continue;
+      if (rule.allow && rule.allow.test(line)) continue;
+      findings.push({
+        rule: rule.id,
+        severity: rule.severity,
+        label: rule.label,
+        file: path,
+        line: i + 1,
+        snippet: line.trim().slice(0, 120),
+        fix: rule.fix,
+      });
+    }
+  }
+  return findings;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { paths: [], json: false, severity: null, help: false };
+  for (const a of argv.slice(2)) {
+    if (a === "--json") args.json = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a.startsWith("--severity=")) args.severity = a.split("=")[1];
+    else if (a.startsWith("--")) {
+      console.error(`Unknown flag: ${a}`);
+      exit(2);
+    } else args.paths.push(a);
+  }
+  return args;
+}
+
+function help() {
+  console.log(`slop-detect — Qualia anti-pattern scanner
+
+Usage:
+  slop-detect [path ...] [--json] [--severity=critical|high|medium|low]
+
+Examples:
+  slop-detect                              # scan whole repo
+  slop-detect src/components/Button.tsx    # scan one file
+  slop-detect app/                         # scan a directory
+  slop-detect --severity=critical          # only critical findings
+  slop-detect --json > slop.json           # machine-readable
+
+Exit codes:
+  0  no critical findings
+  1  one or more critical findings
+  2  invocation error
+`);
+}
+
+function severityOrder(s) { return { critical: 4, high: 3, medium: 2, low: 1 }[s] || 0; }
+function severityColor(s) { return { critical: "\x1b[31m", high: "\x1b[33m", medium: "\x1b[36m", low: "\x1b[37m" }[s] || ""; }
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+
+function main() {
+  const args = parseArgs(argv);
+  if (args.help) { help(); exit(0); }
+
+  const targets = args.paths.length ? args.paths.map(p => resolve(p)) : ["app", "components", "src", "lib", "pages"]
+    .map(d => resolve(cwd(), d))
+    .filter(d => existsSync(d));
+
+  if (targets.length === 0) targets.push(resolve(cwd()));
+
+  // Collect files
+  const files = [];
+  for (const t of targets) {
+    let st;
+    try { st = statSync(t); } catch {
+      console.error(`Path does not exist: ${t}`);
+      exit(2);
+    }
+    if (st.isFile()) files.push(t);
+    else for (const f of walk(t)) files.push(f);
+  }
+
+  // Scan
+  const findings = [];
+  for (const f of files) findings.push(...scanFile(f));
+
+  // Filter by severity
+  const minSev = args.severity ? severityOrder(args.severity) : 1;
+  const filtered = findings.filter(f => severityOrder(f.severity) >= minSev);
+
+  // Output
+  if (args.json) {
+    console.log(JSON.stringify({
+      scanned_files: files.length,
+      total_findings: filtered.length,
+      by_severity: {
+        critical: filtered.filter(f => f.severity === CRITICAL).length,
+        high: filtered.filter(f => f.severity === HIGH).length,
+        medium: filtered.filter(f => f.severity === MEDIUM).length,
+        low: filtered.filter(f => f.severity === LOW).length,
+      },
+      findings: filtered,
+    }, null, 2));
+  } else {
+    if (filtered.length === 0) {
+      console.log(`${BOLD}\x1b[32m✓ no slop detected${RESET}  (${files.length} files scanned)`);
+    } else {
+      // Group by severity, sorted highest first
+      const bySev = {};
+      for (const f of filtered) (bySev[f.severity] ||= []).push(f);
+      const order = ["critical", "high", "medium", "low"];
+      for (const sev of order) {
+        const items = bySev[sev];
+        if (!items) continue;
+        const color = severityColor(sev);
+        console.log(`\n${color}${BOLD}${sev.toUpperCase()}${RESET}  ${items.length} finding${items.length === 1 ? "" : "s"}`);
+        console.log(`${DIM}${"─".repeat(60)}${RESET}`);
+        for (const f of items) {
+          const rel = relative(cwd(), f.file);
+          console.log(`${color}●${RESET} ${BOLD}${rel}:${f.line}${RESET}  ${DIM}[${f.rule}]${RESET}`);
+          console.log(`  ${f.label}`);
+          console.log(`  ${DIM}${f.snippet}${RESET}`);
+          console.log(`  ${color}→${RESET} ${f.fix}`);
+          console.log();
+        }
+      }
+      const crit = (bySev.critical || []).length;
+      const total = filtered.length;
+      console.log(`${BOLD}${total}${RESET} total · ${BOLD}${crit}${RESET} critical · ${files.length} files scanned`);
+      if (crit > 0) console.log(`${severityColor("critical")}${BOLD}commit blocked${RESET} — fix critical findings first`);
+    }
+  }
+
+  // Exit code
+  const criticalCount = filtered.filter(f => f.severity === CRITICAL).length;
+  exit(criticalCount > 0 ? 1 : 0);
+}
+
+main();

package/bin/state.js

@@ -104,11 +104,14 @@ function acquireLock(timeoutMs = 5000) {
       sleepSync(50);
     }
   }
-  // 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;
+  const waited = Date.now() - start;
+  try { _trace("state-lock", "timeout", { waited_ms: waited }); } catch {}
+  const err = new Error(
+    `Could not acquire ${LOCK_FILE} after ${waited}ms. Another state mutation may still be running.`
+  );
+  err.code = "STATE_LOCK_TIMEOUT";
+  err.waited_ms = waited;
+  throw err;
 }
 
 function releaseLock(lock) {
@@ -1264,6 +1267,186 @@ function cmdBackfillLifetime(opts) {
   });
 }
 
+// ─── Backfill Milestones from JOURNEY.md ─────────────────
+// Reconstructs the milestones[] array + lifetime counters from the
+// "Milestone arc" table in .planning/JOURNEY.md. Required when a project
+// pre-dates v4 milestone bookkeeping (or had its tracking.json reset)
+// but JOURNEY.md captures the historical arc. Idempotent — only adds
+// missing milestones or overwrites entries flagged backfilled:true.
+//
+// JOURNEY.md table format expected:
+//   | # | Milestone | Status | Phases | Closed |
+//   | 1 | Name      | CLOSED | 1–13   | YYYY-MM-DD |
+//   | 5 | Name      | OPEN   | rolling| —      |
+//
+// Phase counting handles ranges (`1–13` → 13), comma lists (`14, 15, 16.1–16.6` → 8),
+// and "rolling" / "—" / "-" → 0.
+function cmdBackfillMilestones(opts) {
+  const t = readTracking();
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
+  ensureLifetime(t);
+
+  const journeyPath = path.join(PLANNING, "JOURNEY.md");
+  if (!fs.existsSync(journeyPath)) {
+    return output(fail("NO_JOURNEY", "JOURNEY.md not found. Cannot backfill without milestone history source."));
+  }
+
+  const content = fs.readFileSync(journeyPath, "utf8");
+
+  // Parse the milestone arc table. Each row must have 5 columns:
+  // num | name | status | phases | closed
+  const rows = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(
+      /^\|\s*(\d+)\s*\|\s*([^|]+?)\s*\|\s*(CLOSED|OPEN|CURRENT)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/i
+    );
+    if (m) {
+      rows.push({
+        num: parseInt(m[1], 10),
+        name: m[2].trim(),
+        status: m[3].trim().toUpperCase(),
+        phasesStr: m[4].trim(),
+        closedStr: m[5].trim(),
+      });
+    }
+  }
+
+  if (rows.length === 0) {
+    return output(
+      fail(
+        "NO_MILESTONE_TABLE",
+        "No milestone arc table found in JOURNEY.md. Expected `| # | Milestone | Status | Phases | Closed |` header followed by rows."
+      )
+    );
+  }
+
+  // Count phases from a phasesStr.
+  // "1–13" → 13. "14, 15, 16.1–16.6" → 8. "19–25" → 7. "rolling" / "—" / "-" → 0.
+  const countPhases = (s) => {
+    if (!s) return 0;
+    const lower = s.toLowerCase();
+    if (lower === "—" || lower === "-" || lower === "rolling" || lower === "n/a") return 0;
+    let count = 0;
+    for (const seg of s.split(",")) {
+      const trimmed = seg.trim();
+      if (!trimmed || trimmed === "—" || trimmed === "-") continue;
+      // Match X–Y or X-Y where X/Y can be "13" or "16.6"
+      const range = trimmed.match(/^(\d+(?:\.\d+)?)\s*[–-]\s*(\d+(?:\.\d+)?)$/);
+      if (range) {
+        const startStr = range[1];
+        const endStr = range[2];
+        // Sub-phase range like "16.1–16.6" → count by sub-index difference + 1
+        if (startStr.includes(".") && endStr.includes(".")) {
+          const startSub = parseInt(startStr.split(".")[1], 10);
+          const endSub = parseInt(endStr.split(".")[1], 10);
+          count += Math.max(0, endSub - startSub + 1);
+        } else {
+          const start = parseInt(startStr, 10);
+          const end = parseInt(endStr, 10);
+          count += Math.max(0, end - start + 1);
+        }
+      } else {
+        // Single phase like "14" or "17.1"
+        count += 1;
+      }
+    }
+    return count;
+  };
+
+  const closed = rows.filter((r) => r.status === "CLOSED").sort((a, b) => a.num - b.num);
+  const openRow = rows.find((r) => r.status === "OPEN" || r.status === "CURRENT");
+
+  t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
+  let added = 0;
+  let updated = 0;
+  let totalClosedPhases = 0;
+  const closedSummaries = [];
+
+  for (const row of closed) {
+    const phaseCount = countPhases(row.phasesStr);
+    totalClosedPhases += phaseCount;
+
+    const dateMatch = row.closedStr.match(/\d{4}-\d{2}-\d{2}/);
+    const closedAt = dateMatch ? `${dateMatch[0]}T00:00:00.000Z` : "";
+
+    const summary = {
+      num: row.num,
+      name: row.name,
+      total_phases: phaseCount,
+      phases_completed: phaseCount,
+      tasks_completed: 0, // unknown for historical backfill
+      shipped_url: "",
+      closed_at: closedAt,
+      backfilled: true,
+    };
+    closedSummaries.push({ num: row.num, name: row.name, phases: phaseCount });
+
+    const existing = t.milestones.findIndex((mm) => mm && mm.num === row.num);
+    if (existing >= 0) {
+      // Don't override entries that came from real /qualia-milestone close
+      // (they have richer data). Only overwrite previously-backfilled entries.
+      if (t.milestones[existing].backfilled) {
+        t.milestones[existing] = summary;
+        updated++;
+      }
+    } else {
+      t.milestones.push(summary);
+      added++;
+    }
+  }
+
+  // Stable order by milestone number.
+  t.milestones.sort((a, b) => (a.num || 0) - (b.num || 0));
+
+  const lastClosed = closed.length > 0 ? closed[closed.length - 1].num : 0;
+
+  // Math.max — never reduce lifetime counters. Preserves real /qualia-milestone
+  // history if a project was partly closed properly and partly backfilled.
+  t.lifetime.milestones_completed = Math.max(
+    t.lifetime.milestones_completed || 0,
+    closed.length
+  );
+  t.lifetime.last_closed_milestone = Math.max(
+    t.lifetime.last_closed_milestone || 0,
+    lastClosed
+  );
+  t.lifetime.total_phases = Math.max(
+    t.lifetime.total_phases || 0,
+    totalClosedPhases
+  );
+
+  // Set current milestone — prefer the OPEN row; otherwise next-after-last-closed.
+  if (openRow) {
+    t.milestone = openRow.num;
+    t.milestone_name = openRow.name;
+  } else if (lastClosed > 0) {
+    t.milestone = lastClosed + 1;
+    t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
+  }
+
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+
+  _trace("backfill-milestones", "allow", {
+    added,
+    updated,
+    closed_count: closed.length,
+    total_phases: totalClosedPhases,
+    lifetime: t.lifetime,
+  });
+
+  output({
+    ok: true,
+    action: "backfill-milestones",
+    added,
+    updated,
+    closed: closedSummaries,
+    open_milestone: openRow ? { num: openRow.num, name: openRow.name } : null,
+    lifetime: t.lifetime,
+  });
+}
+
 // ─── Next Report ID ──────────────────────────────────────
 // Increments report_seq and returns the next QS-REPORT-NN id. Per-project
 // counter (lives in tracking.json). /qualia-report calls this to tag each
@@ -1297,9 +1480,8 @@ const opts = parseArgs(rest);
 
 // 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.
+// don't need the lock. A lock timeout is a hard failure for mutators; racing
+// state writes are worse than asking the user to retry.
 const READ_ONLY = new Set(["check", "validate-plan"]);
 let __lock = null;
 if (!READ_ONLY.has(cmd)) {
@@ -1307,7 +1489,11 @@ if (!READ_ONLY.has(cmd)) {
   // 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();
+  try {
+    __lock = acquireLock();
+  } catch (err) {
+    output(fail(err.code || "STATE_LOCK_ERROR", err.message));
+  }
   process.on("exit", () => releaseLock(__lock));
   process.on("SIGINT", () => { releaseLock(__lock); process.exit(130); });
   process.on("SIGTERM", () => { releaseLock(__lock); process.exit(143); });
@@ -1336,6 +1522,9 @@ try {
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;
+    case "backfill-milestones":
+      cmdBackfillMilestones(opts);
+      break;
     case "next-report-id":
       cmdNextReportId(opts);
       break;
@@ -1343,7 +1532,7 @@ try {
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|next-report-id> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|backfill-milestones|next-report-id> [--options]`
         )
       );
   }