@misterhuydo/cairn-mcp 1.12.0 → 1.14.0

package/README.md

@@ -33,10 +33,15 @@ Restart Claude Code once after running this — required for the MCP server to l
 ## Upgrade
 
 ```bash
-npm install -g @misterhuydo/cairn-mcp
+npm install -g @misterhuydo/cairn-mcp@latest
+cairn install
 ```
 
-No need to re-run `cairn install` — hooks and MCP config carry over between versions.
+Updating the package replaces only the binary. Re-run `cairn install` to re-sync the
+hook set — a release that adds new hooks (e.g. the roadmap-capture hooks) won't wire
+them otherwise. It's idempotent and additive, so your MCP config and any existing
+hooks are preserved. Restart Claude Code once afterward so the new hooks and MCP
+server load.
 
 ---
 
@@ -46,7 +51,9 @@ No need to re-run `cairn install` — hooks and MCP config carry over between ve
 |---|---|---|
 | `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline with **line numbers** to save tokens |
 | `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first |
-| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, and the roadmap re-surfaced — all confirmed in one line |
+| `PostToolUse[ExitPlanMode]` | A plan is approved | The plan is parsed into `### Phase N` entries in `.cairn/roadmap.md`, synced, and the cursor activated |
+| `PostToolUse[TodoWrite]` | The todo list changes | Todos mirror onto the roadmap as sub-tasks under the current phase (or seed root phases if none exist) |
+| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, the roadmap re-surfaced, and any git-detected completed phases surfaced for you to confirm — all in one line |
 | `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume`. Memory restored from `.cairn/memory/` if the Claude store is empty (new machine / fresh clone) |
 
 ---
@@ -74,6 +81,7 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 | `cairn_code_graph` | Dependency health — instability, cycles, load-bearing modules |
 | `cairn_security` | Scan for XSS, SQLi, hardcoded secrets, weak crypto, and more |
 | `cairn_todos` | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them |
+| `cairn_roadmap` | The active project plan: phases authored in `.cairn/roadmap.md`, with a cursor, dependencies, and auto-pruning of shipped phases into `.cairn/roadmap_completed.md` |
 | `cairn_bundle` | Minified source snapshot (auto-handled by hooks) |
 | `cairn_checkpoint` | Save session state (auto-handled by hooks) |
 | `cairn_minify` | Minify a single file on demand (fallback when hooks are not installed) |
@@ -133,6 +141,64 @@ Stats are included automatically in `cairn_maintain` (`todos_found`) and `cairn_
 
 ---
 
+## Roadmap
+
+TODOs are a long-tail backlog; the **roadmap** is the active plan. It's a first-class
+document at `.cairn/roadmap.md` (not a memory) — a `## Phases` section of
+`### Phase N: title` blocks, plus whatever overview prose you like:
+
+```markdown
+## Phases
+
+### Phase 1: Decouple roadmap from memory
+Move phases out of decision memos into this file.
+
+### Phase 2: Completed log
+Prune shipped phases, append them to roadmap_completed.md.
+```
+
+`cairn_roadmap` reads that file and tracks it:
+
+```
+cairn_roadmap { action: "tree" }                  → render the plan (auto-syncs roadmap.md)
+cairn_roadmap { action: "next" }                  → advance the cursor to the next actionable phase
+cairn_roadmap { action: "focus", id: 3 }          → make phase 3 the current focus
+cairn_roadmap { action: "set_status", id: 3, status: "done" }  → ship it
+cairn_roadmap { action: "add", parent: 3, text: "..." }        → ad-hoc sub-task under a phase
+cairn_roadmap { action: "deps_add", from: 2, to: 4 }           → phase 2 blocks phase 4
+```
+
+Editing `roadmap.md` *is* editing the plan — read actions re-seed from it, and the
+end-of-turn hook folds in any hand-edits. Marking a phase **done** prunes it from
+`roadmap.md` and appends it to the append-only `.cairn/roadmap_completed.md`, so the
+file always shows only what's next. The shipped phase stays in the database (counted
+in the `M/N done` rollup, recoverable) but is hidden from the tree.
+
+If a project still has its roadmap in the old `decision_production_roadmap.md` memo,
+the first roadmap read migrates it automatically: the content moves to
+`.cairn/roadmap.md` and the memo (plus its index entry) is removed from the memory
+store. Content is preserved verbatim; the migration is one-time and idempotent.
+
+### Automatic capture
+
+You don't have to register phases by hand. Two `PostToolUse` hooks fold work into
+the roadmap mechanically:
+
+- **Approve a plan** (Claude's plan mode → `ExitPlanMode`) and its steps are parsed
+  into `### Phase N` entries in `roadmap.md`. Headings become phases; failing that, a
+  top-level numbered list; failing that, the whole plan becomes one phase. Duplicate
+  titles are skipped, and the cursor activates so the roadmap surfaces immediately.
+- **Write a todo list** (`TodoWrite`) and the items mirror onto the roadmap — as
+  ad-hoc sub-tasks under the current phase, or as seed root phases when no roadmap
+  exists yet. A sub-task that's already `done` is never downgraded.
+
+Completion is **proposed, never auto-applied**. The end-of-turn hook inspects new git
+commits; when a commit references a phase (explicit `phase N`, or a strong overlap
+with the phase title) the candidate is surfaced for you to confirm — Claude asks
+before calling `set_status … done`, so a stray keyword can't silently prune your plan.
+
+---
+
 ## Supported languages
 
 | Language | What Cairn extracts |

package/bin/cairn-cli.js

@@ -10,6 +10,9 @@ import { checkpoint } from '../src/tools/checkpoint.js';
 import { findCairnDir, getTempPath, loadMap, saveMap, validateMap, OUTLINE_THRESHOLD } from '../src/tools/minifyMap.js';
 import { generateOutline } from '../src/bundler/outliner.js';
 import { claudeSlug } from '../src/graph/cwd.js';
+import { syncRoadmapFromFile, ROADMAP_GROUP } from '../src/tools/roadmapFile.js';
+import { mergePlanPhases, syncTodosToRoadmap, detectDonePhases } from '../src/tools/roadmapCapture.js';
+import { findNextActionable, activatePhase } from '../src/tools/roadmap.js';
 
 const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python', 'sql']);
 
@@ -149,9 +152,12 @@ async function roadmapView(cairnDir) {
       const anyInProg = live.some(p => p.status === 'in_progress');
       const rootStatus = allDone ? 'done' : (anyInProg ? 'in_progress' : 'open');
       const doneCount = live.filter(p => p.status === 'done').length;
-      lines.push(`${STATUS_BOX[rootStatus]} Decision: ${decisionName} (${doneCount}/${live.length} done)`);
+      const header = decisionName === ROADMAP_GROUP ? 'Roadmap' : `Decision: ${decisionName}`;
+      lines.push(`${STATUS_BOX[rootStatus]} ${header} (${doneCount}/${live.length} done)`);
       for (const p of phases) {
         if (p.status === 'stale') continue;
+        // Shipped roadmap phases are kept (counted above) but hidden — show only what's next.
+        if (decisionName === ROADMAP_GROUP && p.status === 'done') continue;
         const arrow = cursorId === p.id ? ' →' : '';
         lines.push(`  ${STATUS_BOX[p.status] || '[?]'}${arrow} Phase ${p.phase_number}: ${p.text}`);
         visitSubtree(p.id, 2);
@@ -186,8 +192,12 @@ async function roadmapView(cairnDir) {
 
     let memoLines = null;
     if (advanced && rootDecision != null && rootPhaseNum != null) {
-      const memoPath = path.join(cairnDir, 'memory', `decision_${slugify(rootDecision)}.md`);
-      const section = extractPhaseSection(memoPath, rootPhaseNum);
+      // The phase body lives in roadmap.md for the roadmap group; legacy decision-grouped
+      // phases still read from their decision memo.
+      const sourcePath = rootDecision === ROADMAP_GROUP
+        ? path.join(cairnDir, 'roadmap.md')
+        : path.join(cairnDir, 'memory', `decision_${slugify(rootDecision)}.md`);
+      const section = extractPhaseSection(sourcePath, rootPhaseNum);
       if (section) memoLines = section.split('\n');
     }
     return { active: true, currentLabel, treeLines: lines, advanced, memoLines };
@@ -407,6 +417,74 @@ if (subcommand === '--version' || subcommand === '-v') {
     process.exit(2);
   });
 
+} else if (subcommand === 'roadmap-capture') {
+  // PostToolUse[ExitPlanMode|TodoWrite] hook. Mechanically folds approved plans
+  // and the live todo list into the roadmap so it stays current without Claude
+  // having to remember to call cairn_roadmap.
+  //   ExitPlanMode → parse plan markdown into `### Phase N` entries in roadmap.md,
+  //                  sync to DB, and set the cursor if none is active.
+  //   TodoWrite    → mirror todos as sub-tasks under the cursor phase (or seed
+  //                  root phases when no roadmap exists yet).
+  let stdinData = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { stdinData += chunk; });
+  process.stdin.on('end', async () => {
+    let input;
+    try { input = JSON.parse(stdinData); } catch { process.exit(0); }
+    const toolName = input?.tool_name || '';
+    const toolInput = input?.tool_input || {};
+
+    const cwd = process.cwd();
+    const cairnDir = path.join(cwd, '.cairn');
+    if (!fs.existsSync(cairnDir)) process.exit(0);
+    const dbPath = path.join(cairnDir, 'index.db');
+    if (!fs.existsSync(dbPath)) process.exit(0);
+
+    let DatabaseSync;
+    try { ({ DatabaseSync } = await import('node:sqlite')); } catch { process.exit(0); }
+
+    const isPlan = /exit.?plan.?mode/i.test(toolName);
+    const isTodo = /todo.?write/i.test(toolName);
+    if (!isPlan && !isTodo) process.exit(0);
+
+    let message = null;
+    let db;
+    try {
+      if (isPlan) {
+        const plan = toolInput.plan;
+        if (typeof plan !== 'string' || !plan.trim()) process.exit(0);
+        const res = mergePlanPhases(plan);
+        db = new DatabaseSync(dbPath);
+        syncRoadmapFromFile(db);
+        // Activate the roadmap if nothing is focused yet, so the Stop hook surfaces it.
+        const cursor = db.prepare('SELECT phase_id FROM main.roadmap_cursor WHERE singleton = 1').get()?.phase_id ?? null;
+        if (cursor == null) {
+          const next = findNextActionable(db, null);
+          if (next.id != null) activatePhase(db, next.id);
+        }
+        if (res.added.length > 0) {
+          message = `[cairn] roadmap: captured ${res.added.length} phase(s) from plan${res.skipped.length ? ` (${res.skipped.length} already present)` : ''}.`;
+        }
+      } else if (isTodo) {
+        db = new DatabaseSync(dbPath);
+        const res = syncTodosToRoadmap(db, toolInput.todos);
+        if (res.seeded) {
+          message = `[cairn] roadmap: seeded ${res.seeded} phase(s) from todos.`;
+        } else if (res.inserted > 0) {
+          message = `[cairn] roadmap: linked ${res.inserted} new sub-task(s) to the current phase.`;
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`[cairn] roadmap-capture skipped: ${e.message}\n`);
+      try { db?.close(); } catch {}
+      process.exit(0);
+    }
+    try { db?.close(); } catch {}
+
+    if (message) process.stdout.write(JSON.stringify({ systemMessage: message }));
+    process.exit(0);
+  });
+
 } else if (subcommand === 'validate-map') {
   // Clean up stale entries and reset per-session readCounts.
   // Called by cairn_resume at session start.
@@ -476,7 +554,23 @@ if (subcommand === '--version' || subcommand === '-v') {
     if (n > 0) seg.push(`memory backed up (${n})`);
   } catch {}
 
-  // 3. roadmap re-surface (read-only; content changes happen via cairn_roadmap)
+  // 3. roadmap re-surface. First fold any hand-edits to .cairn/roadmap.md into the DB
+  //    so the heartbeat reflects the file even when no cairn_roadmap call was made.
+  //    Then detect phases that look shipped from new commits — proposed, NOT applied:
+  //    surfaced below so Claude confirms with the user before marking done.
+  let doneCandidates = [];
+  try {
+    const dbPath = path.join(cairnDir, 'index.db');
+    if (fs.existsSync(dbPath)) {
+      const { DatabaseSync } = await import('node:sqlite');
+      const wdb = new DatabaseSync(dbPath);
+      try {
+        syncRoadmapFromFile(wdb);
+        try { doneCandidates = detectDonePhases(wdb, cwd).candidates; } catch {}
+      } finally { wdb.close(); }
+    }
+  } catch {}
+
   let additionalContext = '';
   try {
     const rv = await roadmapView(cairnDir);
@@ -484,7 +578,7 @@ if (subcommand === '--version' || subcommand === '-v') {
       seg.push(`roadmap ${rv.advanced ? 'updated' : 'on track'}: ${rv.currentLabel}`);
       const ctx = ['[cairn] Production roadmap (→ = cursor / current phase):', ...rv.treeLines.map(l => '  ' + l)];
       if (rv.memoLines) {
-        ctx.push('', '── Decision memo (current phase) ──', ...rv.memoLines,
+        ctx.push('', '── Current phase detail (from roadmap.md) ──', ...rv.memoLines,
                  '── (re-read after each phase to confirm direction) ──');
       }
       ctx.push('', 'Keep this current via cairn_roadmap on MATERIAL change (phase done / blocked / new) — not every turn.');
@@ -492,6 +586,18 @@ if (subcommand === '--version' || subcommand === '-v') {
     }
   } catch {}
 
+  // Surface git-detected completion candidates for user confirmation (never auto-applied).
+  if (doneCandidates.length > 0) {
+    seg.push(`${doneCandidates.length} phase(s) may be done — confirm with user`);
+    const lines = ['', '[cairn] Possible COMPLETED phase(s) detected from recent commits —',
+      'CONFIRM WITH THE USER before marking done; do NOT mark done unilaterally:'];
+    for (const c of doneCandidates) {
+      lines.push(`  • Phase ${c.phase_number}: ${c.text} (commit ${c.commit}, ${c.confidence})` +
+        ` → if confirmed: cairn_roadmap set_status ${c.phase_id} done`);
+    }
+    additionalContext = additionalContext ? additionalContext + '\n' + lines.join('\n') : lines.join('\n').trimStart();
+  }
+
   if (seg.length === 0) process.exit(0);
   const out = { systemMessage: `[cairn] ${seg.join(' · ')}` };
   if (additionalContext) out.additionalContext = additionalContext;
@@ -692,6 +798,8 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Read]     -> cairn minify                   (compress source files for reading)');
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
+  console.log('  PostToolUse[ExitPlanMode] -> cairn roadmap-capture      (approved plan -> roadmap phases)');
+  console.log('  PostToolUse[TodoWrite]    -> cairn roadmap-capture      (todos -> roadmap sub-tasks)');
   console.log('  Stop                 -> cairn session-tick             (checkpoint + memory backup + roadmap, surfaced)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   console.log('  UserPromptSubmit     -> cairn memory-restore            (restore .cairn/memory -> Claude store if empty)');
@@ -713,13 +821,15 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Read]     -> cairn minify                   (compress source files for reading)');
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
+  console.log('  PostToolUse[ExitPlanMode] -> cairn roadmap-capture      (approved plan -> roadmap phases)');
+  console.log('  PostToolUse[TodoWrite]    -> cairn roadmap-capture      (todos -> roadmap sub-tasks)');
   console.log('  Stop                 -> cairn session-tick             (checkpoint + memory backup + roadmap, surfaced)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   console.log('  UserPromptSubmit     -> cairn memory-restore            (restore .cairn/memory -> Claude store if empty)');
   process.exit(0);
 
 } else {
-  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | session-tick | resume-hint | roadmap-hint | memory-restore>');
+  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | session-tick | resume-hint | roadmap-hint | roadmap-capture | memory-restore>');
   process.exit(1);
 }
 
@@ -778,11 +888,18 @@ function applyHooks(settingsDir, isGlobal) {
   }
   settings.hooks.UserPromptSubmit = submitHooks;
 
-  // PostToolUse: drop the legacy forward-sync hook entirely. The Stop-hook backup
-  // (session-tick) now captures Claude auto-memory writes into .cairn/memory.
-  const cleanedPost = stripHooks(settings.hooks.PostToolUse, isLegacyMemoryScript);
-  if (cleanedPost.length > 0) settings.hooks.PostToolUse = cleanedPost;
-  else delete settings.hooks.PostToolUse;
+  // PostToolUse: drop the legacy forward-sync hook (the session-tick backup now
+  // captures Claude auto-memory writes), then ensure roadmap-capture fires on
+  // ExitPlanMode (plan → phases) and TodoWrite (todos → sub-tasks).
+  let postHooks = stripHooks(settings.hooks.PostToolUse, isLegacyMemoryScript);
+  const ensurePost = (matcher) => {
+    if (!postHooks.some(h => h.matcher === matcher && h.hooks?.some(hh => hh.command === 'cairn roadmap-capture'))) {
+      postHooks.push({ matcher, hooks: [{ type: 'command', command: 'cairn roadmap-capture' }] });
+    }
+  };
+  ensurePost('ExitPlanMode');
+  ensurePost('TodoWrite');
+  settings.hooks.PostToolUse = postHooks;
 
   if (isGlobal) {
     // Remove obsolete deployed sync scripts from prior installs.

package/index.js

@@ -263,7 +263,7 @@ Use to: get a project-wide bird's-eye view, triage code quality, find where to l
     },
     {
       name: 'cairn_todos',
-      description: 'Long-tail backlog: scanned TODO/FIXME/HACK/XXX comments + manual notes. Stats are included in cairn_maintain and cairn_resume reports. For active multi-phase plans (with cursor + decision-memo references) use cairn_roadmap instead.',
+      description: 'Long-tail backlog: scanned TODO/FIXME/HACK/XXX comments + manual notes. Stats are included in cairn_maintain and cairn_resume reports. For the active multi-phase plan (authored in .cairn/roadmap.md, with a cursor + deps) use cairn_roadmap instead.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -283,14 +283,14 @@ Use to: get a project-wide bird's-eye view, triage code quality, find where to l
     },
     {
       name: 'cairn_roadmap',
-      description: 'Active project plan: phases with status + decision-memo backing + cursor + dep graph. Phases are AUTHORED in decision memos via a `## Phases` section (### Phase 1: title, ### Phase 2: ...) — saving a decision memo via cairn_memo auto-seeds them here. Edit the memo to revise the plan; phases re-sync (existing preserved, removed marked stale, added appended; the response includes inserted_phases / updated_phases / staled_phases arrays so the diff is visible). Sub-tasks under a phase are ad-hoc via add --parent. Inter-phase deps via deps_add — `next` will skip dep-blocked phases and explain in the reason. The Stop hook re-prints this tree after every assistant turn while a cursor is set, and injects the current phase memo section on cursor advance.',
+      description: 'Active project plan: phases with status + cursor + dep graph. Phases are AUTHORED in the first-class document .cairn/roadmap.md (NOT in memory) via a `## Phases` section (### Phase 1: title, ### Phase 2: ...). Read actions (tree/status/next/sync) re-seed from that file, so editing roadmap.md IS editing the plan (existing phases preserved, removed marked stale, added appended). Marking a phase done prunes it from roadmap.md and appends it to .cairn/roadmap_completed.md (append-only log); the done row stays in the DB but is hidden from the tree, so the plan always shows what is next. Sub-tasks under a phase are ad-hoc via add --parent. Inter-phase deps via deps_add — `next` will skip dep-blocked phases and explain in the reason. The Stop hook re-prints this tree after every assistant turn while a cursor is set.',
       inputSchema: {
         type: 'object',
         properties: {
           action: {
             type: 'string',
-            enum: ['tree', 'status', 'focus', 'next', 'set_status', 'add', 'deps_add', 'deps_remove', 'deps_list'],
-            description: 'tree: render roadmap grouped by decision (M/N done rollup; stale hidden by default — pass show_stale: true to view; pass decision: <name> to filter) | status: one-line summary | focus <id>: move cursor, mark in_progress, propagate up (warns if dep-blocked but does not refuse) | next: DFS-advance cursor to next actionable phase (skips stale + dep-blocked, returns reason) | set_status <id> <status>: open|in_progress|done|blocked|stale (done auto-advances cursor) | add <parent> <text>: ad-hoc sub-task under an existing phase | deps_add <from> <to>: declare phase <from> blocks phase <to> (cycle-checked) | deps_remove <from> <to> | deps_list [<id>]: list edges (or just edges touching <id>)',
+            enum: ['tree', 'status', 'sync', 'focus', 'next', 'set_status', 'add', 'deps_add', 'deps_remove', 'deps_list'],
+            description: 'tree: render the roadmap (M/N done rollup; stale + shipped-done hidden by default — pass show_stale: true for stale) | status: one-line summary | sync: re-seed from .cairn/roadmap.md (also runs automatically on tree/status/next) | focus <id>: move cursor, mark in_progress, propagate up (warns if dep-blocked but does not refuse) | next: DFS-advance cursor to next actionable phase (skips stale + dep-blocked, returns reason) | set_status <id> <status>: open|in_progress|done|blocked|stale (done auto-advances cursor; a done roadmap phase is pruned from roadmap.md + logged to roadmap_completed.md) | add <parent> <text>: ad-hoc sub-task under an existing phase | deps_add <from> <to>: declare phase <from> blocks phase <to> (cycle-checked) | deps_remove <from> <to> | deps_list [<id>]: list edges (or just edges touching <id>)',
           },
           id:         { type: 'number',  description: 'Phase ID (focus, set_status, deps_list)' },
           status:     { type: 'string',  enum: ['open', 'in_progress', 'done', 'blocked', 'stale'], description: 'New status (set_status)' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",

package/src/tools/memo.js

@@ -106,7 +106,10 @@ export function syncPhasesToRoadmap(db, decisionName, phases) {
     }
   }
   for (const [num, row] of existingByNum) {
-    if (!seenNums.has(num) && row.status !== 'stale') {
+    // A phase dropped from the source is staled — UNLESS it already shipped (done).
+    // Shipped phases are pruned from roadmap.md on completion, so their absence is
+    // expected; they stay 'done' (archived, counted in rollups), never re-staled.
+    if (!seenNums.has(num) && row.status !== 'stale' && row.status !== 'done') {
       markStale.run(row.id);
       staledPhases.push({ id: row.id, phase_number: num });
     }
@@ -229,14 +232,6 @@ export function memo(db, { action, name, type, content, description = '', origin
     const filePath = path.join(memoryDir, removed.file);
     if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
     writeIndex(memoryDir, entries);
-    // If this was a decision memo, mark all its roadmap phases as stale (preserve history).
-    if (removed.type === 'decision' && db) {
-      try {
-        db.prepare(
-          "UPDATE main.roadmap_phases SET status = 'stale' WHERE decision_name = ? AND status != 'stale'"
-        ).run(removed.name);
-      } catch {}
-    }
     return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, name }, null, 2) }] };
   }
 
@@ -277,18 +272,10 @@ export function memo(db, { action, name, type, content, description = '', origin
   else entries.push(entry);
   writeIndex(memoryDir, entries);
 
-  // Decision memos with a `## Phases` section seed/update the project roadmap.
-  let phaseSync = null;
-  if (type === 'decision' && db) {
-    try {
-      const phases = parsePhases(content);
-      if (phases.length > 0) {
-        phaseSync = syncPhasesToRoadmap(db, name, phases);
-      }
-    } catch (e) {
-      process.stderr.write(`[cairn] phase sync failed for ${name}: ${e.message}\n`);
-    }
-  }
+  // NOTE: roadmap phases are NOT seeded from memos. The production roadmap is a
+  // first-class document at .cairn/roadmap.md (see roadmapFile.js / cairn_roadmap);
+  // decision memos are pure semantic memory. parsePhases/syncPhasesToRoadmap are
+  // still exported here because roadmapFile.js reuses them to seed from that file.
 
   return {
     content: [{
@@ -299,7 +286,6 @@ export function memo(db, { action, name, type, content, description = '', origin
         type,
         file: filePath,
         action: isUpdate ? 'updated' : 'created',
-        ...(phaseSync ? { phase_sync: phaseSync } : {}),
       }, null, 2),
     }],
   };

package/src/tools/resume.js

@@ -10,6 +10,8 @@ import { incrementalMaintain } from './maintain.js';
 import { loadMap, saveMap, validateMap } from './minifyMap.js';
 import { loadIndexEntries, loadPreferenceMemories } from './memo.js';
 import { detectRelocation, repairRelocation } from './relocate.js';
+import { roadmap as roadmapDispatch } from './roadmap.js';
+import { roadmapPath } from './roadmapFile.js';
 
 export async function resume(db) {
   const cairnDir = getCairnDir();
@@ -132,56 +134,46 @@ export async function resume(db) {
     // todos table not yet present in older indexes; ignore
   }
 
-  // Roadmap surfacing: render compact tree if a cursor is set or any todo is nested.
+  // Roadmap surfacing — seed from .cairn/roadmap.md and report the live plan so the
+  // agent always knows a roadmap exists, where it lives, and what the current phase is.
+  // Pre-v1.13 this read the legacy todos / roadmap_cursor.todo_id model and silently
+  // surfaced nothing once phases moved to the roadmap_phases table — agents went
+  // hunting for a roadmap that was right there. We now reuse the canonical roadmap
+  // dispatcher (which seeds from the file) so there is zero rendering drift.
   let roadmap = null;
   try {
-    const cursorRow = db.prepare('SELECT todo_id FROM main.roadmap_cursor WHERE singleton = 1').get();
-    const cursorId = cursorRow?.todo_id ?? null;
-    const hasNested = db.prepare('SELECT 1 FROM main.todos WHERE parent_id IS NOT NULL LIMIT 1').get();
-    if (cursorId != null || hasNested) {
-      const all = db.prepare(
-        'SELECT id, parent_id, position, status, text FROM main.todos ORDER BY IFNULL(parent_id, -1), position, id'
-      ).all();
-      const STATUS_BOX = { open: '[ ]', in_progress: '[~]', done: '[x]', blocked: '[!]' };
-      const childrenByParent = new Map();
-      for (const t of all) {
-        const key = t.parent_id ?? null;
-        if (!childrenByParent.has(key)) childrenByParent.set(key, []);
-        childrenByParent.get(key).push(t);
-      }
-      const lines = [];
-      const visit = (parentId, depth) => {
-        for (const t of childrenByParent.get(parentId) || []) {
-          const arrow = cursorId === t.id ? ' →' : '';
-          lines.push(`${'  '.repeat(depth)}${STATUS_BOX[t.status] || '[?]'}${arrow} ${t.text} (id:${t.id})`);
-          visit(t.id, depth + 1);
-        }
-      };
-      visit(null, 0);
-      const cursorFull = cursorId ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(cursorId) : null;
+    const hasRoadmapFile = fs.existsSync(roadmapPath());
+    const status = JSON.parse(roadmapDispatch(db, { action: 'status' }).content[0].text);
+    if (hasRoadmapFile || status.decisions_total > 0) {
+      const tree = roadmapDispatch(db, { action: 'tree', compact: true }).content[0].text;
       roadmap = {
-        tree: lines.join('\n'),
-        cursor: cursorFull ? { id: cursorFull.id, text: cursorFull.text } : null,
+        file: path.relative(getProjectRoot(), roadmapPath()).replace(/\\/g, '/'),
+        current: status.current,            // "<decision> / Phase N (text)" or null
+        decisions_in_flight: status.decisions_in_flight,
+        tree,
       };
     }
   } catch {
-    // roadmap_cursor table missing on very old indexes; ignore
+    // roadmap_phases table missing on very old indexes; ignore
   }
 
-  // Build human-readable resume summary
-  const changedSummary = changed.length > 0
-    ? changed.slice(0, 10).map(c => `${c.change}: ${path.relative(getProjectRoot(), c.file).replace(/\\/g, '/')}`).join(', ')
-    : 'none';
+  // Build a tight one-line headline. Detailed data (changed files, notes, memory
+  // index) ships as structured fields below — the summary points at them, it does
+  // not re-serialize them, so the resume payload stays small.
+  const roadmapSummary = roadmap
+    ? (roadmap.current
+        ? `Roadmap (${roadmap.file}) — current: ${roadmap.current}`
+        : `Roadmap (${roadmap.file}) — no cursor set (call cairn_roadmap next)`)
+    : '';
 
   const resumeSummary = [
     `Last session: ${session.message}`,
     relocation ? `Project relocated from ${relocation.oldRoot} → repaired automatically.` : '',
-    changed.length > 0 ? `Files changed since checkpoint: ${changedSummary}` : 'No files changed since checkpoint.',
-    subSchemas.length > 0 ? `Federated sub-indexes: ${subSchemas.length}` : '',
-    openTodos > 0 ? `Open todos: ${openTodos}` : '',
-    roadmap?.cursor ? `Roadmap cursor → (id:${roadmap.cursor.id}) ${roadmap.cursor.text}` : '',
-    session.notes?.length > 0 ? `Notes: ${session.notes.map(n => (n && typeof n === 'object' && n.ref) ? `${n.description} (see: ${n.ref})` : String(n)).join(' | ')}` : '',
-  ].filter(Boolean).join(' ');
+    roadmapSummary,
+    changed.length > 0 ? `${changed.length} file(s) changed since checkpoint` : 'No files changed since checkpoint',
+    openTodos > 0 ? `${openTodos} open todo(s)` : '',
+    subSchemas.length > 0 ? `${subSchemas.length} sub-index(es)` : '',
+  ].filter(Boolean).join(' · ');
 
   let gitignoreHint = null;
   try {