qualia-framework 6.8.0 → 6.9.0

package/CHANGELOG.md

@@ -8,6 +8,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [6.9.0] - 2026-06-13 (employee on-ramps — stack presets, employee-mode install, shared knowledge pull)
+
+Implements Part A of the 2026-06-13 restructure plan: turn the framework from an owner-only tool into something a new employee can take idea→deployed without tribal knowledge. **Additive only** — no skill, agent, hook, or rule was rewritten; these are on-ramps built *around* the existing loop.
+
+### Added — project-type stack presets (`templates/stacks/`)
+- **Four presets matching real Qualia work:** `landing-page` (Next.js SSG, no DB), `full-app` (Next.js + Supabase auth/RLS + Tailwind), `ai-agent` (adds OpenRouter + optional Retell/ElevenLabs/Telnyx voice), `internal-tool` (Supabase portal-style auth). Each preset ships `stack.json`, `env.required.json` (`{name, purpose, howToObtain, ownerIssued}`), `phases.md`, `verify-checklist.md`, and a minimal-but-runnable `scaffold/` (full-app/internal-tool include `lib/supabase` server+client adapters and an RLS-from-first-migration `0001_init.sql`; ai-agent adds a `lib/openrouter` adapter + `app/api/chat` route + `evals/`). `templates/stacks/README.md` documents the contract. This kills the "every project gets identical generic phases / no working skeleton" gaps.
+
+### Changed — `/qualia-new` instantiates a preset
+- Adds one project-type question, then lays down the chosen preset's scaffold, folds `phases.md` into the plan, and copies `env.required.json` to the new project's `.planning/env.required.json`. `--quick` skips it. Existing flow otherwise unchanged.
+
+### Changed — `/qualia-doctor` validates the preset's env + CLI auth
+- Reads `.planning/env.required.json` (fallback `./env.required.json`), checks each var (env or `.env.local`) and CLI logins (`vercel`, `supabase`, `gh`), and prints PASS/FAIL with the exact fix command. For `ownerIssued: true` vars it routes to "ask the OWNER (Fawzi)" instead of a self-serve command.
+
+### Added — two-mode install (OWNER / EMPLOYEE)
+- `npx qualia-framework install` accepts the explicit keyword `EMPLOYEE` at the install-code prompt: installs the full framework with **no team code**, `erp.enabled=false`. OWNER/team-code installs are byte-for-byte unchanged, and a genuinely bogus or empty code is still rejected (no silent self-elevation). `/qualia-report` degrades gracefully when no team code is set — it writes a **local** report file and says so, instead of failing. New `docs/EMPLOYEE-QUICKSTART.md` walks install→doctor→new→build/verify→ship→report with the credential each step needs.
+
+### Added — shared knowledge pull (Part C bridge)
+- On install/update the framework pulls a **read-only** copy of the `qualia-memory` vault's sanitized `wiki/_export/` (configurable via `QUALIA_KNOWLEDGE_SOURCE` / `QUALIA_KNOWLEDGE_SUBPATH`, git URL or local path) into the knowledge dir, skipping gracefully when unavailable. Freshness comes from the vault's nightly ERP-report ingest, not sync infra. The export is financial-data-sanitized at the source (see qualia-memory `scripts/export-team-wiki.py`).
+
+### Fixed — test drift
+- `tests/bin.test.sh` (Codex backup discipline #122/#123) now greps the `backups/` subdir, matching the v6.8.1 `bakPath()` relocation. The behavior was correct; the test path was stale.
+
+## [6.8.1] - 2026-06-10 (installer hygiene — global hook sweep, bin purge, bak routing)
+
+Found via a live audit of an installed `~/.claude`: the retired brain experiment's `brain-inject.js` was still wired under `UserPromptSubmit`, firing a failing node process on every user prompt, and had survived four releases because the settings merge never looked at that event.
+
+### Fixed — installer
+- **Settings hook sweep is now global.** The merge previously only cleaned events present in `qualiaHooks`, so deprecated entries under other events (`UserPromptSubmit`, etc.) were never pruned. The installer now sweeps every hook event for (a) retired Qualia hook commands and (b) `node "<CLAUDE_DIR>/..."` commands whose target file no longer exists, dropping empty blocks/events. User hooks (non-node or outside `CLAUDE_DIR`) are untouched.
+- **`brain-inject.js` added to `DEPRECATED_HOOKS`** — the UserPromptSubmit half of the brain experiment was missing from the v6.8.0 prune list.
+- **`bin/` orphan purge** — `DEPRECATED_BIN` removes the retired `build-brain-index.js`; bin/ previously had no deprecation pass at all.
+- **`.bak` files routed to `backups/`** — `settings.json.bak.*` / `CLAUDE.md.bak.*` no longer accumulate in the `~/.claude` root across reinstalls; all three backup sites now write into a `backups/` subdir via a shared `bakPath()` helper.
+
 ## [6.8.0] - 2026-06-06 (audit remediation — installer, guards, trust-score, polish)
 
 Closes the verified findings from the 2026-06-06 framework audit (4 CRITICAL · 7 HIGH · 33 MEDIUM, adversarially verified). Root cause of most CRITICALs was a stale/incomplete install, not source rot — fixed in the installer so a clean reinstall is complete and correct.

package/bin/install.js

@@ -171,6 +171,95 @@ function copyTreeTransform(src, dest, transform) {
   }
 }
 
+// ─── Shared knowledge pull (read-only mirror of qualia-memory) ───
+// Copy-on-install/update only — NOT a sync engine. Pulls a read-only snapshot
+// of the team's shared knowledge wiki into <home>/knowledge/shared/ so every
+// install ships the same accumulated patterns. Source is configurable:
+//   QUALIA_KNOWLEDGE_SOURCE — a local path OR a git URL (https/ssh/file)
+//   QUALIA_KNOWLEDGE_SUBPATH — subdir inside the source to copy (default wiki/_export)
+// Degrades GRACEFULLY: any failure (no git, no network, missing path, private-
+// repo auth fail) warns and continues. Never throws, never exits the installer.
+//
+// Returns { status, detail } for the caller to log. status is one of:
+//   "copied" | "skipped" | "error" (all non-fatal).
+const DEFAULT_KNOWLEDGE_SUBPATH = "wiki/_export";
+
+function copyTreeReadOnly(src, dest) {
+  // Copy a tree and lock every FILE 0o444 — this mirror is read-only; local
+  // edits belong in the user's own knowledge files, not here. Directories stay
+  // writable (0o755) so the next install/update can replace the mirror cleanly
+  // (deleting an entry needs write on its parent dir, not on the entry).
+  if (!fs.existsSync(src)) return 0;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyTreeReadOnly(s, d);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+      try { fs.chmodSync(d, 0o444); } catch {}
+      count++;
+    }
+  }
+  return count;
+}
+
+function pullSharedKnowledge(knowledgeDest) {
+  const source = (process.env.QUALIA_KNOWLEDGE_SOURCE || "").trim();
+  if (!source) {
+    return { status: "skipped", detail: "QUALIA_KNOWLEDGE_SOURCE not set — shared knowledge pull disabled" };
+  }
+  const subpath = (process.env.QUALIA_KNOWLEDGE_SUBPATH || DEFAULT_KNOWLEDGE_SUBPATH).trim();
+  const sharedDest = path.join(knowledgeDest, "shared");
+  const os = require("os");
+  let tmpClone = null;
+  try {
+    let sourceRoot;
+    const looksGit = /^(https?:\/\/|git@|ssh:\/\/|git:\/\/)/.test(source) || source.endsWith(".git");
+    if (looksGit) {
+      // Shallow clone into a temp dir. spawnSync with argv (no shell) so the
+      // URL can't be misinterpreted. Short timeout — never hang an install.
+      const { spawnSync } = require("child_process");
+      tmpClone = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-knowledge-"));
+      const r = spawnSync("git", ["clone", "--depth", "1", "--quiet", source, tmpClone], {
+        stdio: ["ignore", "ignore", "pipe"],
+        timeout: 30000,
+        encoding: "utf8",
+      });
+      if (r.status !== 0) {
+        const why = (r.stderr || "").trim().split("\n").pop() || `git exited ${r.status}`;
+        return { status: "skipped", detail: `clone failed (${why}) — skipped, continuing` };
+      }
+      sourceRoot = tmpClone;
+    } else {
+      // Local path source.
+      if (!fs.existsSync(source)) {
+        return { status: "skipped", detail: `source path not found: ${source} — skipped, continuing` };
+      }
+      sourceRoot = source;
+    }
+
+    const exportDir = path.join(sourceRoot, subpath);
+    if (!fs.existsSync(exportDir)) {
+      return { status: "skipped", detail: `subpath '${subpath}' absent in source — skipped, continuing` };
+    }
+
+    // Replace the prior mirror wholesale (it's read-only and fully derived).
+    if (fs.existsSync(sharedDest)) {
+      try { fs.rmSync(sharedDest, { recursive: true, force: true }); } catch {}
+    }
+    const n = copyTreeReadOnly(exportDir, sharedDest);
+    return { status: "copied", detail: `${n} file(s) → knowledge/shared/ (read-only mirror)` };
+  } catch (e) {
+    return { status: "error", detail: `${e.message} — skipped, continuing` };
+  } finally {
+    if (tmpClone) { try { fs.rmSync(tmpClone, { recursive: true, force: true }); } catch {} }
+  }
+}
+
 function ensureCodexStatusLineConfig(existing) {
   const statusLine = `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`;
   const colors = "status_line_use_colors = true";
@@ -210,13 +299,22 @@ function ensureCodexStatusLineConfig(existing) {
   return `${next.slice(0, tuiMatch.index)}${tuiBlock}${next.slice(tuiMatch.index + tuiMatch[0].length)}`;
 }
 
+// v6.8.1: .bak files go into a backups/ subdir next to the target instead of
+// littering the target's directory (a dozen settings.json.bak.* files were
+// accumulating in ~/.claude root across reinstalls).
+function bakPath(dest) {
+  const dir = path.join(path.dirname(dest), "backups");
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(dir, `${path.basename(dest)}.bak.${ts}`);
+}
+
 function backupIfDifferent(dest, nextContent, label) {
   if (!fs.existsSync(dest)) return false;
   try {
     const existing = fs.readFileSync(dest, "utf8");
     if (existing === nextContent) return false;
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const bak = `${dest}.bak.${ts}`;
+    const bak = bakPath(dest);
     fs.copyFileSync(dest, bak);
     ok(`Backed up existing ${label} -> ${path.basename(bak)}`);
     return true;
@@ -439,18 +537,42 @@ function askCode() {
       printHeader();
       const line = nextPipedLine();
       // Echo the prompt + answer for log readability.
-      process.stdout.write(`  ${WHITE}Enter install code:${RESET} ${line}\n`);
+      process.stdout.write(`  ${WHITE}Enter install code (or "EMPLOYEE" for no-code install):${RESET} ${line}\n`);
       resolve(String(line || "").trim());
       return;
     }
     const rl = getRl();
     printHeader();
-    rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
+    console.log(`  ${DIM}OWNER / team member? Enter your install code (QS-NAME-##).${RESET}`);
+    console.log(`  ${DIM}New employee without a code? Type ${RESET}${TEAL}EMPLOYEE${RESET}${DIM} to install in employee mode.${RESET}`);
+    console.log("");
+    rl.question(`  ${WHITE}Install code or "EMPLOYEE":${RESET} `, (answer) => {
       resolve(String(answer || "").trim());
     });
   });
 }
 
+// ─── Employee mode (no team code) ────────────────────────
+// A new employee may not have a QS-NAME-## code yet. Typing "EMPLOYEE" at the
+// install-code prompt installs the full framework at the least-privilege role:
+// feature branches only, no main pushes (enforced by branch-guard, which trusts
+// the role bit in the 0o600 config). ERP reporting stays OFF until a real team
+// code is set, so /qualia-report degrades to a local-only report.
+//
+// Defaulting to EMPLOYEE (not OWNER) on a missing/keyword code is the secure
+// failure mode: a bogus code that is NOT the EMPLOYEE keyword is still rejected
+// (see main()), so this can't be used to silently self-elevate.
+const EMPLOYEE_KEYWORDS = new Set(["EMPLOYEE", "EMPLOYEE-MODE", "NO-CODE", "NOCODE"]);
+const EMPLOYEE_MEMBER = {
+  name: "Qualia Employee",
+  role: "EMPLOYEE",
+  description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+};
+
+function isEmployeeKeyword(raw) {
+  return EMPLOYEE_KEYWORDS.has(String(raw || "").trim().toUpperCase());
+}
+
 // ─── Prompt for install target (Claude / Codex / Both) ──
 // Backward-compat: a piped install with only the team code (single stdin
 // line) closes stdin before this prompt; we silently default to "1"
@@ -516,12 +638,24 @@ async function main() {
   }
   const rawCode = await askCode();
   const code = resolveTeamCode(rawCode);
-  const member = code ? TEAM[code] : null;
+  let member = code ? TEAM[code] : null;
+
+  // Employee mode: the user typed the EMPLOYEE keyword instead of a team code.
+  // Synthesize a least-privilege EMPLOYEE member. The team code stays empty,
+  // which keeps ERP reporting off (set later via a real code or set-erp-key).
+  const employeeMode = !member && isEmployeeKeyword(rawCode);
+  if (employeeMode) {
+    member = EMPLOYEE_MEMBER;
+  }
 
   if (!member) {
+    // A genuine bad code (not the EMPLOYEE keyword) is still rejected — typing
+    // garbage must never silently install. This preserves the install-code gate
+    // for team members while only the explicit EMPLOYEE keyword bypasses it.
     console.log("");
     log(`${RED}✗${RESET} Invalid code: "${rawCode}". Get your install code from Fawzi.`);
     log(`${DIM}  Tip: codes use digit zero, not letter O. Format: QS-NAME-##${RESET}`);
+    log(`${DIM}  No code yet? Type ${RESET}${TEAL}EMPLOYEE${RESET}${DIM} to install in employee mode.${RESET}`);
     console.log("");
     process.exit(1);
   }
@@ -530,6 +664,9 @@ async function main() {
   const roleColor = member.role === "OWNER" ? TEAL : GREEN;
   console.log(`  ${GREEN}✓${RESET} ${WHITE}${BOLD}Welcome, ${member.name}${RESET}`);
   console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}`);
+  if (employeeMode) {
+    console.log(`  ${DIM}  Mode:${RESET} ${YELLOW}employee (no team code) — ERP reporting off until a code is set${RESET}`);
+  }
 
   // ─── Ask install target (Claude / Codex / Both) ────────
   const target = await askTarget();
@@ -543,7 +680,7 @@ async function main() {
   if (!installClaude) {
     // Codex-only path: skip the entire Claude install block. Jump straight
     // to the Codex installer + final summary.
-    await installCodex(member, target);
+    await installCodex(member, target, employeeMode);
     return;
   }
 
@@ -683,6 +820,8 @@ async function main() {
     "brain-pre-compact.js",
     "brain-session-end.js",
     "brain-session-start.js",
+    // v6.8.1: the UserPromptSubmit half of the brain experiment was missed.
+    "brain-inject.js",
   ];
   for (const f of DEPRECATED_HOOKS) {
     const p = path.join(hooksDest, f);
@@ -768,6 +907,15 @@ async function main() {
     }
   }
 
+  // ─── Shared knowledge pull (read-only mirror of qualia-memory wiki) ──
+  // Copy-on-install only. Configure with QUALIA_KNOWLEDGE_SOURCE (git URL or
+  // local path). Skips gracefully when unset/unreachable — never blocks install.
+  {
+    const pull = pullSharedKnowledge(knowledgeDest);
+    if (pull.status === "copied") ok(`shared knowledge — ${pull.detail}`);
+    else log(`${DIM}shared knowledge — ${pull.detail}${RESET}`);
+  }
+
   // ─── References (methodology docs loaded by skills at runtime) ────
   printSection("References");
   const refDir = path.join(FRAMEWORK_DIR, "references");
@@ -820,9 +968,8 @@ async function main() {
     if (fs.existsSync(claudeDest)) {
       const existing = fs.readFileSync(claudeDest, "utf8");
       if (existing !== claudeMd) {
-        const ts = new Date().toISOString().replace(/[:.]/g, "-");
-        const bak = `${claudeDest}.bak.${ts}`;
-        try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → ${path.basename(bak)}`); } catch {}
+        const bak = bakPath(claudeDest);
+        try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → backups/${path.basename(bak)}`); } catch {}
       }
     }
     fs.writeFileSync(claudeDest, claudeText(claudeMd), "utf8");
@@ -842,6 +989,14 @@ async function main() {
       try { fs.chmodSync(out, 0o755); } catch {}
       ok(script.label);
     }
+    // v6.8.1: purge retired bin scripts (same belt-and-suspenders as
+    // DEPRECATED_HOOKS — bin/ never had an orphan pass, so the brain
+    // experiment's indexer survived reinstalls).
+    const DEPRECATED_BIN = ["build-brain-index.js"];
+    for (const f of DEPRECATED_BIN) {
+      const p = path.join(binDest, f);
+      try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
+    }
     // Write a minimal root package.json so the installed CLI's `require("../package.json")`
     // resolves post-install (bin/ lives at CLAUDE_DIR/bin, so the parent is CLAUDE_DIR).
     fs.writeFileSync(
@@ -970,15 +1125,19 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   }
 
   // ─── Save config (for update command) ──────────────────
+  // Employee mode (no team code): code is the empty string, and ERP reporting
+  // is disabled by default — there's no team code to attribute reports to, so
+  // /qualia-report degrades to a local-only report. A real team code (or
+  // `qualia-framework set-erp-key`) flips ERP back on later.
   const configFile = path.join(CLAUDE_DIR, ".qualia-config.json");
   const config = {
-    code,
+    code: code || "",
     installed_by: member.name,
     role: member.role,
     version: require("../package.json").version,
     installed_at: new Date().toISOString().split("T")[0],
     erp: {
-      enabled: true,
+      enabled: !employeeMode,
       url: "https://portal.qualiasolutions.net",
       api_key_file: ".erp-api-key",
     },
@@ -1204,6 +1363,35 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     }
   }
 
+  // v6.8.1: sweep ALL hook events for retired Qualia hooks and dead node
+  // paths. The merge above only visits events present in qualiaHooks, so
+  // entries under other events (e.g. the retired brain-inject.js under
+  // UserPromptSubmit) survived every reinstall — firing a failing node
+  // process on each user prompt. Runs after the hooks/ install, so an
+  // existsSync miss means the file is truly gone, not not-yet-copied.
+  const DEPRECATED_HOOK_CMDS = [
+    "brain-inject.js", "build-brain-index.js", "block-env-edit.js",
+    "brain-pre-compact.js", "brain-session-end.js", "brain-session-start.js",
+  ];
+  const isDeadHookCmd = (cmd) => {
+    if (typeof cmd !== "string") return false;
+    if (DEPRECATED_HOOK_CMDS.some((f) => cmd.includes(f))) return true;
+    const m = cmd.match(/^node "([^"]+)"$/);
+    if (m && m[1].startsWith(CLAUDE_DIR + path.sep) && !fs.existsSync(m[1])) return true;
+    return false;
+  };
+  for (const event of Object.keys(settings.hooks)) {
+    const blocks = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const cleaned = [];
+    for (const block of blocks) {
+      if (!block || !Array.isArray(block.hooks)) continue;
+      const kept = block.hooks.filter((h) => !isDeadHookCmd(h && h.command));
+      if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+    }
+    if (cleaned.length > 0) settings.hooks[event] = cleaned;
+    else delete settings.hooks[event];
+  }
+
   // Permissions stay permissive; Qualia policy enforcement happens in hooks so
   // OWNER overrides and EMPLOYEE blocks can share one source of truth. We still
   // seed a scoped baseline allow-list (union-merged, never clobbering user
@@ -1238,9 +1426,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   // configs / custom permissions. Atomic write (tmp + rename) avoids partial
   // writes; the .bak file is the recovery point if the merger ever misbehaves.
   if (fs.existsSync(settingsPath)) {
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const bak = `${settingsPath}.bak.${ts}`;
-    try { fs.copyFileSync(settingsPath, bak); } catch {}
+    try { fs.copyFileSync(settingsPath, bakPath(settingsPath)); } catch {}
   }
   const settingsTmp = `${settingsPath}.tmp.${process.pid}`;
   fs.writeFileSync(settingsTmp, JSON.stringify(settings, null, 2));
@@ -1252,7 +1438,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
 
   // ─── Codex (optional second target) ──────────────────────
   if (installCodexTarget) {
-    await installCodex(member, target);
+    await installCodex(member, target, employeeMode);
   }
 
   // ─── Summary ───────────────────────────────────────────
@@ -1346,7 +1532,7 @@ function printSummary({ member, target, claudeInstalled }) {
 // Claude install. The only thing intentionally not claimed is a Claude-style
 // persistent statusLine setting; Codex exposes hook status messages today, not
 // an equivalent global status-line command.
-async function installCodex(member, target) {
+async function installCodex(member, target, employeeMode = false) {
   console.log("");
   console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Codex${RESET}`);
   console.log(`  ${DIM2}${"─".repeat(40)}${RESET}`);
@@ -1435,7 +1621,9 @@ async function installCodex(member, target) {
       version: require("../package.json").version,
       installed_at: new Date().toISOString().split("T")[0],
       erp: {
-        enabled: true,
+        // Employee mode (no team code) leaves ERP off so /qualia-report
+        // degrades to a local-only report instead of failing.
+        enabled: !employeeMode,
         url: "https://portal.qualiasolutions.net",
         api_key_file: ".erp-api-key",
       },
@@ -1559,6 +1747,13 @@ async function installCodex(member, target) {
         if (!fs.existsSync(out)) copyTextTransform(path.join(knowledgeSrc, file), out, codexText);
       }
     }
+    // Shared knowledge mirror (read-only) — same copy-on-install semantics as
+    // the Claude path. Skips gracefully when QUALIA_KNOWLEDGE_SOURCE is unset.
+    {
+      const pull = pullSharedKnowledge(knowledgeDest);
+      if (pull.status === "copied") ok(`shared knowledge — ${pull.detail}`);
+      else log(`${DIM}shared knowledge — ${pull.detail}${RESET}`);
+    }
     copyTextTransform(path.join(FRAMEWORK_DIR, "guide.md"), path.join(CODEX_DIR, "qualia-guide.md"), codexText);
     ok("templates/ + knowledge/ + references/ + guide");
   } catch (e) {

package/bin/state.js

@@ -729,6 +729,33 @@ function readNextMilestoneNameFromJourney(milestoneNum) {
   }
 }
 
+// A milestone name is a "placeholder" when it's blank or the literal
+// "Milestone N" fallback that close-milestone historically emitted when
+// tracking.json carried no real name. Placeholders must never beat a real
+// name from JOURNEY.md (observed in ERP reports as {"num":"9","name":"Milestone 9"}).
+function isPlaceholderMilestoneName(name, num) {
+  const trimmed = String(name == null ? "" : name).trim();
+  if (!trimmed) return true;
+  return new RegExp(`^Milestone\\s+${num}$`, "i").test(trimmed);
+}
+
+// Resolve the human name for milestone `num`. Preference order:
+//   1. `candidate` (e.g. tracking.json milestone_name) when it's a real name
+//   2. the `## Milestone N · Name` header in JOURNEY.md
+//   3. the "Milestone N" placeholder — last resort only
+function resolveMilestoneName(num, candidate) {
+  const trimmed = String(candidate == null ? "" : candidate).trim();
+  if (!isPlaceholderMilestoneName(trimmed, num)) return trimmed;
+  const fromJourney = readNextMilestoneNameFromJourney(num);
+  if (fromJourney) return fromJourney;
+  return `Milestone ${num}`;
+}
+
+// Normalize a milestone name for dedupe comparisons.
+function normalizeMilestoneName(name) {
+  return String(name == null ? "" : name).trim().toLowerCase();
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -2166,7 +2193,9 @@ function cmdCloseMilestone(opts) {
   }
   ensureLifetime(t);
 
-  const closedMilestone = t.milestone || 1;
+  // parseInt — legacy tracking.json files carry milestone as a string ("9"),
+  // which would corrupt `closedMilestone + 1` ("91") and break num dedupe.
+  const closedMilestone = parseInt(t.milestone, 10) || 1;
   if (
     !opts.force &&
     typeof t.lifetime.last_closed_milestone === "number" &&
@@ -2227,9 +2256,13 @@ function cmdCloseMilestone(opts) {
     0,
     (parseInt(t.lifetime && t.lifetime.tasks_completed) || 0) - priorMilestoneTasks
   );
+  // Resolve the REAL milestone name: non-placeholder tracking.json
+  // milestone_name first, then the JOURNEY.md `## Milestone N · Name` header,
+  // and only as a last resort the "Milestone N" placeholder.
+  const milestoneName = resolveMilestoneName(closedMilestone, t.milestone_name);
   const summary = {
     num: closedMilestone,
-    name: t.milestone_name || `Milestone ${closedMilestone}`,
+    name: milestoneName,
     total_phases: parseInt(t.total_phases) || s.phases.length || 0,
     phases_completed: phasesCompleted,
     tasks_completed: tasksCompletedThisMilestone,
@@ -2237,8 +2270,18 @@ function cmdCloseMilestone(opts) {
     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);
+  // Idempotency + dedupe: update in place when the same milestone number is
+  // already logged (num may be a string in legacy entries), OR when the same
+  // real name is already logged under a different num (renumbering drift —
+  // observed as duplicate names in ERP session_reports.milestones).
+  let existing = t.milestones.findIndex(
+    (m) => m && parseInt(m.num, 10) === closedMilestone
+  );
+  if (existing < 0 && !isPlaceholderMilestoneName(milestoneName, closedMilestone)) {
+    existing = t.milestones.findIndex(
+      (m) => m && normalizeMilestoneName(m.name) === normalizeMilestoneName(milestoneName)
+    );
+  }
   if (existing >= 0) {
     t.milestones[existing] = summary;
   } else {
@@ -2533,13 +2576,35 @@ function cmdBackfillMilestones(opts) {
     };
     closedSummaries.push({ num: row.num, name: row.name, phases: phaseCount });
 
-    const existing = t.milestones.findIndex((mm) => mm && mm.num === row.num);
+    // Match by num first (parseInt — legacy entries store num as a string),
+    // then by normalized real name under a different num (renumbering drift).
+    let existing = t.milestones.findIndex(
+      (mm) => mm && parseInt(mm.num, 10) === row.num
+    );
+    if (existing < 0 && !isPlaceholderMilestoneName(row.name, row.num)) {
+      existing = t.milestones.findIndex(
+        (mm) => mm && normalizeMilestoneName(mm.name) === normalizeMilestoneName(row.name)
+      );
+    }
     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 if (
+        isPlaceholderMilestoneName(
+          t.milestones[existing].name,
+          parseInt(t.milestones[existing].num, 10)
+        ) ||
+        parseInt(t.milestones[existing].num, 10) !== row.num
+      ) {
+        // Real close entry but with a placeholder name ("Milestone 9") or a
+        // stale num — repair the identity fields in place, keep the richer
+        // close data (tasks_completed, shipped_url, closed_at).
+        t.milestones[existing].num = row.num;
+        t.milestones[existing].name = row.name;
+        updated++;
       }
     } else {
       t.milestones.push(summary);