@misterhuydo/cairn-mcp 1.8.1 → 1.10.0

package/README.md

@@ -44,7 +44,7 @@ No need to re-run `cairn install` — hooks and MCP config carry over between ve
 
 | Hook | Trigger | Effect |
 |---|---|---|
-| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline to save tokens |
+| `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` |
 | `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume` |
@@ -66,11 +66,11 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 
 | Tool | What it does |
 |---|---|
-| `cairn_maintain` | Full index of the current project |
+| `cairn_maintain` | Full index of the current project. Suggests adding `.cairn/` to `.gitignore` if not already present |
 | `cairn_resume` | Restore last session + re-index only changed files |
-| `cairn_search` | Find classes, functions, components by name or concept |
+| `cairn_search` | Find classes, functions, components by name or concept — results include file path and **line number** |
 | `cairn_describe` | Summarize what a folder or module does |
-| `cairn_outline` | Structural outline + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
+| `cairn_outline` | Structural outline with **line numbers** per symbol + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
 | `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 |

package/bin/cairn-cli.js

@@ -536,6 +536,158 @@ if (subcommand === '--version' || subcommand === '-v') {
   fs.writeFileSync(lockPath, new Date().toISOString(), 'utf8');
   process.exit(0);
 
+} else if (subcommand === 'roadmap-hint') {
+  // Stop hook: print the roadmap tree only when a cursor is set on the new
+  // roadmap_phases table (v1.10.0+). Silent (exit 0) when no .cairn, no DB,
+  // or no cursor. On *cursor advance* (cursor changed since last fire),
+  // also injects the decision memo's section for the new phase, so the
+  // architectural reasoning is in context exactly when needed.
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  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); }
+
+  let db;
+  try { db = new DatabaseSync(dbPath, { readonly: true }); } catch { process.exit(0); }
+
+  const slugify = (n) => n.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+
+  // Extract `### Phase N: ...` section body from a decision memo file.
+  function extractPhaseSection(memoPath, phaseNumber) {
+    if (!fs.existsSync(memoPath)) return null;
+    const raw = fs.readFileSync(memoPath, 'utf8');
+    const lines = raw.split(/\r?\n/);
+    let inPhasesSection = false;
+    let collecting = false;
+    const acc = [];
+    for (const line of lines) {
+      if (/^##\s+Phases\s*$/i.test(line)) { inPhasesSection = true; continue; }
+      if (inPhasesSection && /^##\s+/.test(line) && !/^###/.test(line)) break;
+      if (!inPhasesSection) continue;
+      const m = /^###\s+Phase\s+(\d+)\s*:\s*(.+?)\s*$/.exec(line);
+      if (m) {
+        if (collecting) break;
+        if (parseInt(m[1], 10) === phaseNumber) {
+          acc.push(`### Phase ${m[1]}: ${m[2]}`);
+          collecting = true;
+        }
+        continue;
+      }
+      if (collecting) acc.push(line);
+    }
+    return acc.join('\n').trim() || null;
+  }
+
+  try {
+    const cursorRow = db.prepare("SELECT phase_id FROM roadmap_cursor WHERE singleton = 1").get();
+    const cursorId = cursorRow?.phase_id ?? null;
+    if (cursorId == null) { db.close(); process.exit(0); }
+
+    const all = db.prepare(
+      'SELECT id, decision_name, phase_number, parent_phase_id, text, status, position FROM roadmap_phases ORDER BY decision_name, phase_number, position, id'
+    ).all();
+
+    // Build tree
+    const STATUS_BOX = { open: '[ ]', in_progress: '[~]', done: '[x]', blocked: '[!]', stale: '[s]' };
+    const byParent = new Map();
+    for (const p of all) {
+      const k = p.parent_phase_id ?? 'root';
+      if (!byParent.has(k)) byParent.set(k, []);
+      byParent.get(k).push(p);
+    }
+    for (const arr of byParent.values()) {
+      arr.sort((a, b) => {
+        if (a.decision_name && b.decision_name && a.decision_name !== b.decision_name) {
+          return a.decision_name.localeCompare(b.decision_name);
+        }
+        if (a.phase_number != null && b.phase_number != null) return a.phase_number - b.phase_number;
+        return a.position - b.position || a.id - b.id;
+      });
+    }
+    const roots = byParent.get('root') || [];
+    const decisionRoots = new Map();
+    for (const r of roots) {
+      if (r.decision_name == null) continue;
+      if (!decisionRoots.has(r.decision_name)) decisionRoots.set(r.decision_name, []);
+      decisionRoots.get(r.decision_name).push(r);
+    }
+    const lines = [];
+    const visitSubtree = (parentId, depth) => {
+      for (const p of byParent.get(parentId) || []) {
+        if (p.status === 'stale') continue;
+        const arrow = cursorId === p.id ? ' →' : '';
+        const label = p.phase_number != null ? `Phase ${p.phase_number}: ${p.text}` : p.text;
+        lines.push(`${'  '.repeat(depth)}${STATUS_BOX[p.status] || '[?]'}${arrow} ${label}`);
+        visitSubtree(p.id, depth + 1);
+      }
+    };
+    for (const [decisionName, phases] of decisionRoots) {
+      const live = phases.filter(p => p.status !== 'stale');
+      if (live.length === 0) continue;
+      const allDone = live.every(p => p.status === 'done');
+      const anyInProg = live.some(p => p.status === 'in_progress');
+      const rootStatus = allDone ? 'done' : (anyInProg ? 'in_progress' : 'open');
+      lines.push(`${STATUS_BOX[rootStatus]} Decision: ${decisionName}`);
+      for (const p of phases) {
+        if (p.status === 'stale') continue;
+        const arrow = cursorId === p.id ? ' →' : '';
+        lines.push(`  ${STATUS_BOX[p.status] || '[?]'}${arrow} Phase ${p.phase_number}: ${p.text}`);
+        visitSubtree(p.id, 2);
+      }
+    }
+
+    // Find current node + walk up to its root phase to identify decision/phase
+    const findById = (id) => all.find(p => p.id === id);
+    let cursorNode = findById(cursorId);
+    let rootDecision = cursorNode?.decision_name ?? null;
+    let rootPhaseNum = cursorNode?.phase_number ?? null;
+    let walker = cursorNode;
+    while (walker && walker.parent_phase_id != null) {
+      walker = findById(walker.parent_phase_id);
+      if (!walker) break;
+      rootDecision = walker.decision_name ?? rootDecision;
+      rootPhaseNum = walker.phase_number ?? rootPhaseNum;
+    }
+    db.close();
+
+    // Detect advance via state file
+    const stateFile = path.join(cairnDir, '.last-roadmap-cursor');
+    let lastCursor = null;
+    try { lastCursor = parseInt(fs.readFileSync(stateFile, 'utf8').trim(), 10); } catch {}
+    const advanced = lastCursor !== cursorId;
+    try { fs.writeFileSync(stateFile, String(cursorId), 'utf8'); } catch {}
+
+    const out = [
+      '[cairn] ROADMAP — cursor is active.',
+      ...lines.map(l => '[cairn]   ' + l),
+    ];
+    const currentLabel = cursorNode
+      ? (cursorNode.phase_number != null
+          ? `${cursorNode.decision_name} / Phase ${cursorNode.phase_number} (${cursorNode.text})`
+          : `${rootDecision} / Phase ${rootPhaseNum} → sub: ${cursorNode.text}`)
+      : '(unknown)';
+    out.push(`[cairn] Current: ${currentLabel}`);
+
+    if (advanced && rootDecision != null && rootPhaseNum != null) {
+      const memoPath = path.join(cairnDir, 'memory', `decision_${slugify(rootDecision)}.md`);
+      const section = extractPhaseSection(memoPath, rootPhaseNum);
+      if (section) {
+        out.push('[cairn] ───── Decision memo (current phase) ─────');
+        for (const ln of section.split('\n')) out.push('[cairn] ' + ln);
+        out.push('[cairn] ───── (re-read after each phase to confirm direction) ─────');
+      }
+    }
+
+    out.push('[cairn] Use cairn_roadmap set_status <id> done (auto-advances), focus <id>, or next to move cursor.');
+    process.stdout.write(out.join('\n') + '\n');
+  } catch (e) {
+    try { db?.close(); } catch {}
+    process.stderr.write(`[cairn] roadmap-hint error: ${e.message}\n`);
+  }
+  process.exit(0);
+
 } else if (subcommand === 'install') {
   // One-shot setup: register MCP server in ~/.claude.json + install global hooks.
   const platform = process.platform;
@@ -568,6 +720,7 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
   console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
+  console.log('  Stop                 -> cairn roadmap-hint              (re-print roadmap when cursor is active)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
   console.log('');
@@ -592,6 +745,7 @@ if (subcommand === '--version' || subcommand === '-v') {
     console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   }
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
+  console.log('  Stop                 -> cairn roadmap-hint              (re-print roadmap when cursor is active)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   if (isGlobal) {
     console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
@@ -599,7 +753,7 @@ if (subcommand === '--version' || subcommand === '-v') {
   process.exit(0);
 
 } else {
-  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | resume-hint>');
+  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | resume-hint | roadmap-hint>');
   process.exit(1);
 }
 
@@ -632,8 +786,12 @@ function applyHooks(settingsDir, isGlobal) {
   const stopHooks = settings.hooks.Stop || [];
   if (!stopHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn checkpoint --auto'))) {
     stopHooks.push({ hooks: [{ type: 'command', command: 'cairn checkpoint --auto' }] });
-    settings.hooks.Stop = stopHooks;
   }
+  // Stop: cairn roadmap-hint (silent unless a roadmap_cursor is set)
+  if (!stopHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn roadmap-hint'))) {
+    stopHooks.push({ hooks: [{ type: 'command', command: 'cairn roadmap-hint' }] });
+  }
+  settings.hooks.Stop = stopHooks;
 
   // UserPromptSubmit: cairn resume-hint
   let submitHooks = settings.hooks.UserPromptSubmit || [];

package/index.js

@@ -14,6 +14,7 @@ import { resume }       from './src/tools/resume.js';
 import { minify }       from './src/tools/minify.js';
 import { outlineProject } from './src/tools/outline.js';
 import { todos }        from './src/tools/todos.js';
+import { roadmap }      from './src/tools/roadmap.js';
 import { memo }         from './src/tools/memo.js';
 import { switchProject } from './src/tools/switch.js';
 import { employMemory } from './src/tools/employMemory.js';
@@ -262,7 +263,7 @@ Use to: get a project-wide bird's-eye view, triage code quality, find where to l
     },
     {
       name: 'cairn_todos',
-      description: 'Manage TODO/FIXME/HACK/XXX items. Scans the codebase for TODO-style comments and lets you add your own. Stats are included in cairn_maintain and cairn_resume reports.',
+      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.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -280,6 +281,27 @@ Use to: get a project-wide bird's-eye view, triage code quality, find where to l
         required: ['action'],
       },
     },
+    {
+      name: 'cairn_roadmap',
+      description: 'Active project plan: phases with status + decision-memo backing + cursor. 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). Sub-tasks under a phase are ad-hoc via add --parent. 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.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['tree', 'status', 'focus', 'next', 'set_status', 'add'],
+            description: 'tree: render roadmap grouped by decision | status: one-line summary (decisions in flight + current) | focus <id>: move cursor, mark in_progress, propagate up | next: DFS-advance cursor to next actionable phase (skips stale) | 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 (inherits decision_ref)',
+          },
+          id:         { type: 'number',  description: 'Phase ID (focus, set_status)' },
+          status:     { type: 'string',  enum: ['open', 'in_progress', 'done', 'blocked', 'stale'], description: 'New status (set_status)' },
+          parent:     { type: 'number',  description: 'Parent phase ID (add — required, ad-hoc sub-tasks must hang under an existing phase)' },
+          text:       { type: 'string',  description: 'Sub-task text (add action)' },
+          compact:    { type: 'boolean', description: 'Compact tree render — strips id tags (tree action)' },
+          hide_stale: { type: 'boolean', description: 'Hide stale phases in tree render (tree action)' },
+        },
+        required: ['action'],
+      },
+    },
   ],
 }));
 
@@ -300,6 +322,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case 'cairn_outline':     return outlineProject(db, args);
     case 'cairn_minify':      return minify(db, args);
     case 'cairn_todos':          return await todos(db, args);
+    case 'cairn_roadmap':        return roadmap(db, args);
     case 'cairn_memo':           return memo(db, args);
     case 'cairn_switch':         return switchProject(db, args);
     case 'cairn_employ_memory':  return employMemory(db, args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.8.1",
+  "version": "1.10.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/graph/db.js

@@ -67,9 +67,32 @@ const SCHEMA = `
     kind        TEXT NOT NULL DEFAULT 'TODO',
     text        TEXT NOT NULL,
     status      TEXT NOT NULL DEFAULT 'open',
+    parent_id   INTEGER REFERENCES todos(id) ON DELETE SET NULL,
+    position    INTEGER NOT NULL DEFAULT 0,
     created_at  TEXT NOT NULL DEFAULT (datetime('now')),
     resolved_at TEXT
   );
+
+  CREATE TABLE IF NOT EXISTS roadmap_cursor (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    todo_id   INTEGER REFERENCES todos(id) ON DELETE SET NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS roadmap_phases (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    decision_name   TEXT,
+    phase_number    INTEGER,
+    parent_phase_id INTEGER REFERENCES roadmap_phases(id) ON DELETE CASCADE,
+    text            TEXT NOT NULL,
+    body            TEXT,
+    status          TEXT NOT NULL DEFAULT 'open',
+    position        INTEGER NOT NULL DEFAULT 0,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+    resolved_at     TEXT
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_roadmap_phases_decision_phase
+    ON roadmap_phases(decision_name, phase_number)
+    WHERE decision_name IS NOT NULL AND phase_number IS NOT NULL;
 `;
 
 // Each sub-DB gets its IDs offset by this multiplier to prevent collisions
@@ -190,6 +213,66 @@ export function openDB() {
   db.exec(SCHEMA);
   // Migration: add line column to existing DBs that predate v1.7.0
   try { db.exec('ALTER TABLE main.symbols ADD COLUMN line INTEGER'); } catch {}
+  // Migration: roadmap tree columns on todos (v1.9.0 — kept dormant in v1.10+ for back-compat)
+  // Idempotent — fails silently if present. Columns are no longer read by tools as of v1.10.0,
+  // but kept to avoid destructive ALTER on user data.
+  let addedRoadmapCols = false;
+  try { db.exec('ALTER TABLE main.todos ADD COLUMN parent_id INTEGER REFERENCES todos(id) ON DELETE SET NULL'); addedRoadmapCols = true; } catch {}
+  try { db.exec('ALTER TABLE main.todos ADD COLUMN position INTEGER NOT NULL DEFAULT 0'); addedRoadmapCols = true; } catch {}
+  if (addedRoadmapCols) {
+    db.exec(`
+      UPDATE main.todos AS t
+      SET position = (
+        SELECT rn - 1 FROM (
+          SELECT id, ROW_NUMBER() OVER (
+            PARTITION BY IFNULL(parent_id, -1) ORDER BY id
+          ) AS rn FROM main.todos
+        ) ord WHERE ord.id = t.id
+      )
+    `);
+  }
+  // Migration: roadmap_cursor.phase_id (v1.10.0 — points at roadmap_phases.id)
+  try { db.exec('ALTER TABLE main.roadmap_cursor ADD COLUMN phase_id INTEGER REFERENCES roadmap_phases(id) ON DELETE SET NULL'); } catch {}
+  // Migration: copy any v1.9.0 in-flight roadmap (todos with parent_id) into roadmap_phases
+  // as a synthetic 'legacy_v1_9' decision. Runs once — guarded by checking if any phase exists
+  // under that decision_name.
+  try {
+    const legacyExists = db.prepare(
+      "SELECT 1 FROM main.roadmap_phases WHERE decision_name = 'legacy_v1_9' LIMIT 1"
+    ).get();
+    if (!legacyExists) {
+      const v9Roots = db.prepare(
+        "SELECT id, text, status, position FROM main.todos WHERE parent_id IS NULL AND id IN (SELECT DISTINCT parent_id FROM main.todos WHERE parent_id IS NOT NULL) ORDER BY position, id"
+      ).all();
+      if (v9Roots.length > 0) {
+        const insertPhase = db.prepare(
+          "INSERT INTO main.roadmap_phases (decision_name, phase_number, parent_phase_id, text, status, position) VALUES (?, ?, ?, ?, ?, ?)"
+        );
+        const oldToNew = new Map();
+        let phaseNum = 1;
+        for (const root of v9Roots) {
+          const r = insertPhase.run('legacy_v1_9', phaseNum++, null, root.text, root.status, root.position);
+          oldToNew.set(root.id, r.lastInsertRowid);
+        }
+        // Sub-tasks: keep one level (v1.9.0's nesting was usually one deep)
+        const v9Children = db.prepare(
+          "SELECT id, parent_id, text, status, position FROM main.todos WHERE parent_id IS NOT NULL ORDER BY position, id"
+        ).all();
+        for (const c of v9Children) {
+          const newParent = oldToNew.get(c.parent_id);
+          if (newParent == null) continue;
+          insertPhase.run(null, null, newParent, c.text, c.status, c.position);
+        }
+        // If old cursor pointed at a migrated todo, repoint it to the new phase id.
+        const oldCursor = db.prepare('SELECT todo_id FROM main.roadmap_cursor WHERE singleton = 1').get();
+        if (oldCursor?.todo_id != null && oldToNew.has(oldCursor.todo_id)) {
+          db.prepare('UPDATE main.roadmap_cursor SET phase_id = ? WHERE singleton = 1').run(oldToNew.get(oldCursor.todo_id));
+        }
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`[cairn] v1.9.0→v1.10.0 roadmap migration skipped: ${e.message}\n`);
+  }
   mountParentSubIndexes(db);
   refreshFederatedViews(db);
   return db;

package/src/tools/memo.js

@@ -5,6 +5,103 @@ import { getMemoryDir } from '../graph/cwd.js';
 export const TRANSFERABLE_TYPES = ['preference', 'experience'];
 export const MEMORY_TYPES = ['preference', 'experience', 'decision', 'knowledge'];
 
+// Parse a decision memo's body for a `## Phases` section. Returns
+// [{ phase_number, text, body }, ...]. Returns [] if no Phases section.
+// Phase headers must look like: ### Phase N: title text
+// Body is lines following the header until next ### Phase or ## heading.
+// Duplicate phase_numbers: first wins, subsequent dropped (caller should warn).
+export function parsePhases(content) {
+  if (!content || typeof content !== 'string') return [];
+  const lines = content.split(/\r?\n/);
+  let inPhasesSection = false;
+  let current = null;
+  const phases = [];
+  const seen = new Set();
+
+  for (const line of lines) {
+    // Section heading detection
+    if (/^##\s+Phases\s*$/i.test(line)) { inPhasesSection = true; continue; }
+    if (/^##\s+/.test(line) && !/^###/.test(line)) {
+      // Any other ## heading ends the Phases section
+      if (current) { phases.push(current); current = null; }
+      inPhasesSection = false;
+      continue;
+    }
+    if (!inPhasesSection) continue;
+
+    // Phase header: ### Phase N: title
+    const phaseMatch = /^###\s+Phase\s+(\d+)\s*:\s*(.+?)\s*$/.exec(line);
+    if (phaseMatch) {
+      if (current) phases.push(current);
+      const num = parseInt(phaseMatch[1], 10);
+      const text = phaseMatch[2];
+      if (seen.has(num)) {
+        process.stderr.write(`[cairn] memo phase parser: duplicate Phase ${num} ignored\n`);
+        current = null;
+        continue;
+      }
+      seen.add(num);
+      current = { phase_number: num, text, bodyLines: [] };
+      continue;
+    }
+    // Accumulate body
+    if (current) current.bodyLines.push(line);
+  }
+  if (current) phases.push(current);
+
+  return phases.map(p => ({
+    phase_number: p.phase_number,
+    text: p.text,
+    body: p.bodyLines.join('\n').trim() || null,
+  }));
+}
+
+// Sync parsed phases to roadmap_phases for a given decision.
+// Re-edit semantics:
+//   - Phase present in memo + DB: update text/body, preserve status/position
+//   - Phase added (in memo, not in DB): insert as 'open' with next position
+//   - Phase removed (in DB, not in memo): mark status='stale' (preserve work history)
+// Sub-tasks (parent_phase_id NOT NULL, decision_name NULL) are ad-hoc and
+// untouched by this sync — they live and die with the parent phase via FK cascade.
+export function syncPhasesToRoadmap(db, decisionName, phases) {
+  const existing = db.prepare(
+    'SELECT id, phase_number, status FROM main.roadmap_phases WHERE decision_name = ? ORDER BY phase_number'
+  ).all(decisionName);
+  const existingByNum = new Map(existing.map(p => [p.phase_number, p]));
+  const seenNums = new Set();
+
+  const update = db.prepare(
+    'UPDATE main.roadmap_phases SET text = ?, body = ?, status = CASE WHEN status = ? THEN ? ELSE status END WHERE id = ?'
+  );
+  const insert = db.prepare(
+    'INSERT INTO main.roadmap_phases (decision_name, phase_number, parent_phase_id, text, body, status, position) VALUES (?, ?, NULL, ?, ?, ?, ?)'
+  );
+  const markStale = db.prepare("UPDATE main.roadmap_phases SET status = 'stale' WHERE id = ?");
+
+  for (let i = 0; i < phases.length; i++) {
+    const p = phases[i];
+    seenNums.add(p.phase_number);
+    const existingRow = existingByNum.get(p.phase_number);
+    if (existingRow) {
+      // Re-activate stale phases on re-add (text matched by phase_number, so it's
+      // the "same" phase being restored).
+      update.run(p.text, p.body, 'stale', 'open', existingRow.id);
+    } else {
+      insert.run(decisionName, p.phase_number, p.text, p.body, 'open', i);
+    }
+  }
+  for (const [num, row] of existingByNum) {
+    if (!seenNums.has(num) && row.status !== 'stale') {
+      markStale.run(row.id);
+    }
+  }
+  return {
+    updated: phases.filter(p => existingByNum.has(p.phase_number)).length,
+    inserted: phases.filter(p => !existingByNum.has(p.phase_number)).length,
+    staled: existing.filter(r => !seenNums.has(r.phase_number) && r.status !== 'stale').length,
+  };
+}
+
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
 }
@@ -60,7 +157,7 @@ export function loadPreferenceMemories(memoryDir) {
     .filter(Boolean);
 }
 
-export function memo(_db, { action, name, type, content, description = '', origin }) {
+export function memo(db, { action, name, type, content, description = '', origin }) {
   const memoryDir = getMemoryDir();
 
   if (action === 'list') {
@@ -113,6 +210,14 @@ export function memo(_db, { action, name, type, content, description = '', origi
     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) }] };
   }
 
@@ -153,6 +258,19 @@ export function memo(_db, { action, name, type, content, description = '', origi
   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`);
+    }
+  }
+
   return {
     content: [{
       type: 'text',
@@ -162,6 +280,7 @@ export function memo(_db, { action, name, type, content, description = '', origi
         type,
         file: filePath,
         action: isUpdate ? 'updated' : 'created',
+        ...(phaseSync ? { phase_sync: phaseSync } : {}),
       }, null, 2),
     }],
   };

package/src/tools/resume.js

@@ -127,11 +127,47 @@ export async function resume(db) {
   // Count open todos for status report
   let openTodos = 0;
   try {
-    openTodos = db.prepare('SELECT COUNT(*) AS n FROM main.todos WHERE status = \'open\'').get().n;
+    openTodos = db.prepare("SELECT COUNT(*) AS n FROM main.todos WHERE status IN ('open', 'in_progress')").get().n;
   } catch {
     // todos table not yet present in older indexes; ignore
   }
 
+  // Roadmap surfacing: render compact tree if a cursor is set or any todo is nested.
+  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;
+      roadmap = {
+        tree: lines.join('\n'),
+        cursor: cursorFull ? { id: cursorFull.id, text: cursorFull.text } : null,
+      };
+    }
+  } catch {
+    // roadmap_cursor 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(', ')
@@ -143,6 +179,7 @@ export async function resume(db) {
     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(' ');
 
@@ -170,6 +207,7 @@ export async function resume(db) {
     resume_summary: resumeSummary,
   };
   if (gitignoreHint) result.gitignore_hint = gitignoreHint;
+  if (roadmap) result.roadmap = roadmap;
   if (gitSnapshotNotes.length > 0) {
     result.migrated = `Removed ${gitSnapshotNotes.length} legacy git-snapshot note(s). Original session backed up to session.bak.json.`;
   }

package/src/tools/roadmap.js

@@ -0,0 +1,302 @@
+// cairn_roadmap — active project plan with cursor + decision-memo backed phases.
+// Phases enter the roadmap only via decision memos (see memo.js syncPhasesToRoadmap).
+// Sub-tasks under a phase are ad-hoc, added via `add --parent <phase_id>`.
+
+const STATUS_BOX = {
+  open: '[ ]',
+  in_progress: '[~]',
+  done: '[x]',
+  blocked: '[!]',
+  stale: '[s]',
+};
+
+const VALID_STATUS = new Set(['open', 'in_progress', 'done', 'blocked', 'stale']);
+const ACTIONABLE = new Set(['open', 'in_progress']);
+
+function getCursor(db) {
+  const row = db.prepare('SELECT phase_id FROM main.roadmap_cursor WHERE singleton = 1').get();
+  return row?.phase_id ?? null;
+}
+
+function setCursor(db, phaseId) {
+  db.prepare(
+    'INSERT INTO main.roadmap_cursor (singleton, phase_id) VALUES (1, ?) ON CONFLICT(singleton) DO UPDATE SET phase_id = excluded.phase_id'
+  ).run(phaseId);
+}
+
+function clearCursor(db) {
+  db.prepare('DELETE FROM main.roadmap_cursor WHERE singleton = 1').run();
+}
+
+// Mark ancestor phases (parent chain) as in_progress, but only if currently 'open'.
+function propagateInProgressUp(db, phaseId) {
+  const stmt = db.prepare('SELECT parent_phase_id, status FROM main.roadmap_phases WHERE id = ?');
+  const update = db.prepare("UPDATE main.roadmap_phases SET status = 'in_progress' WHERE id = ? AND status = 'open'");
+  let cur = stmt.get(phaseId);
+  while (cur && cur.parent_phase_id != null) {
+    update.run(cur.parent_phase_id);
+    cur = stmt.get(cur.parent_phase_id);
+  }
+}
+
+// Move cursor to phaseId, promote it to in_progress (if open), propagate up.
+function activatePhase(db, phaseId) {
+  setCursor(db, phaseId);
+  db.prepare("UPDATE main.roadmap_phases SET status = 'in_progress' WHERE id = ? AND status = 'open'").run(phaseId);
+  propagateInProgressUp(db, phaseId);
+}
+
+// Compute a synthetic "decision-root" status from its phases.
+// done if all non-stale phases done; in_progress if any in_progress; blocked if any blocked & no in_progress; stale if all stale; else open.
+function decisionRootStatus(phases) {
+  const live = phases.filter(p => p.status !== 'stale');
+  if (live.length === 0) return 'stale';
+  if (live.every(p => p.status === 'done')) return 'done';
+  if (live.some(p => p.status === 'in_progress')) return 'in_progress';
+  if (live.some(p => p.status === 'blocked') && !live.some(p => p.status === 'in_progress')) return 'blocked';
+  return 'open';
+}
+
+// DFS-advance the cursor to the next actionable phase, skipping stale.
+// Order within a decision: phase_number ascending; within a phase: sub-tasks first
+// (parent_phase_id = phase_id, ordered by position), then next phase_number.
+// Across decisions: by decision_name (stable alphabetical order — could be improved later).
+function findNextActionable(db, fromPhaseId) {
+  const all = db.prepare(
+    'SELECT id, decision_name, phase_number, parent_phase_id, status, position FROM main.roadmap_phases ORDER BY decision_name, phase_number, position, id'
+  ).all();
+  const isLive = (p) => ACTIONABLE.has(p.status);
+
+  // Build a flat DFS order: for each top-level phase (parent_phase_id null), visit its sub-tasks
+  // (parent_phase_id = phase.id) before the next top-level phase.
+  const childrenOf = new Map();
+  for (const p of all) {
+    const key = p.parent_phase_id ?? `root:${p.decision_name}`;
+    if (!childrenOf.has(key)) childrenOf.set(key, []);
+    childrenOf.get(key).push(p);
+  }
+  // Sort each child group
+  for (const arr of childrenOf.values()) {
+    arr.sort((a, b) => {
+      if (a.phase_number != null && b.phase_number != null) return a.phase_number - b.phase_number;
+      return a.position - b.position || a.id - b.id;
+    });
+  }
+
+  const order = [];
+  const decisionsSeen = new Set();
+  for (const p of all) {
+    if (p.parent_phase_id != null) continue;
+    if (decisionsSeen.has(p.decision_name)) continue;
+    decisionsSeen.add(p.decision_name);
+    const stack = [];
+    const phasesInDecision = childrenOf.get(`root:${p.decision_name}`) || [];
+    for (let i = phasesInDecision.length - 1; i >= 0; i--) stack.push(phasesInDecision[i]);
+    while (stack.length) {
+      const node = stack.pop();
+      order.push(node);
+      const kids = childrenOf.get(node.id) || [];
+      for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+    }
+  }
+
+  if (fromPhaseId == null) {
+    return order.find(isLive)?.id ?? null;
+  }
+  const idx = order.findIndex(p => p.id === fromPhaseId);
+  if (idx === -1) return order.find(isLive)?.id ?? null;
+  for (let i = idx + 1; i < order.length; i++) {
+    if (isLive(order[i])) return order[i].id;
+  }
+  return null;
+}
+
+function renderTree(db, { compact = false, hideStale = false } = {}) {
+  const all = db.prepare(
+    'SELECT id, decision_name, phase_number, parent_phase_id, text, status, position FROM main.roadmap_phases ORDER BY decision_name, phase_number, position, id'
+  ).all();
+  if (all.length === 0) return '(no roadmap — write a decision memo with a `## Phases` section)';
+
+  const cursor = getCursor(db);
+  const byParent = new Map();
+  for (const p of all) {
+    const key = p.parent_phase_id ?? 'root';
+    if (!byParent.has(key)) byParent.set(key, []);
+    byParent.get(key).push(p);
+  }
+  for (const arr of byParent.values()) {
+    arr.sort((a, b) => {
+      if (a.decision_name && b.decision_name && a.decision_name !== b.decision_name) {
+        return a.decision_name.localeCompare(b.decision_name);
+      }
+      if (a.phase_number != null && b.phase_number != null) return a.phase_number - b.phase_number;
+      return a.position - b.position || a.id - b.id;
+    });
+  }
+
+  // Group root nodes by decision_name. Roots always have decision_name (they're memo phases).
+  const roots = byParent.get('root') || [];
+  const decisionRoots = new Map();
+  for (const r of roots) {
+    if (r.decision_name == null) continue; // safety: shouldn't happen
+    if (!decisionRoots.has(r.decision_name)) decisionRoots.set(r.decision_name, []);
+    decisionRoots.get(r.decision_name).push(r);
+  }
+
+  const lines = [];
+  const visitSubtree = (parentId, depth) => {
+    const kids = byParent.get(parentId) || [];
+    for (const p of kids) {
+      if (hideStale && p.status === 'stale') continue;
+      const box = STATUS_BOX[p.status] || '[?]';
+      const arrow = cursor === p.id ? ' →' : '';
+      const label = p.phase_number != null ? `Phase ${p.phase_number}: ${p.text}` : p.text;
+      const tag = compact ? '' : ` (id:${p.id})`;
+      lines.push(`${'  '.repeat(depth)}${box}${arrow} ${label}${tag}`);
+      visitSubtree(p.id, depth + 1);
+    }
+  };
+
+  for (const [decisionName, phases] of decisionRoots) {
+    if (hideStale && phases.every(p => p.status === 'stale')) continue;
+    const rootStatus = decisionRootStatus(phases);
+    lines.push(`${STATUS_BOX[rootStatus]} Decision: ${decisionName}`);
+    for (const p of phases) {
+      if (hideStale && p.status === 'stale') continue;
+      const box = STATUS_BOX[p.status] || '[?]';
+      const arrow = cursor === p.id ? ' →' : '';
+      const label = `Phase ${p.phase_number}: ${p.text}`;
+      const tag = compact ? '' : ` (id:${p.id})`;
+      lines.push(`  ${box}${arrow} ${label}${tag}`);
+      visitSubtree(p.id, 2);
+    }
+  }
+  return lines.join('\n');
+}
+
+function statusSummary(db) {
+  const all = db.prepare(
+    "SELECT decision_name, status FROM main.roadmap_phases WHERE parent_phase_id IS NULL"
+  ).all();
+  const byDecision = new Map();
+  for (const p of all) {
+    if (!byDecision.has(p.decision_name)) byDecision.set(p.decision_name, []);
+    byDecision.get(p.decision_name).push(p);
+  }
+  let inFlight = 0;
+  for (const phases of byDecision.values()) {
+    const root = decisionRootStatus(phases);
+    if (root === 'in_progress' || root === 'open') inFlight++;
+  }
+  const cursor = getCursor(db);
+  let currentLabel = null;
+  if (cursor != null) {
+    const cur = db.prepare('SELECT id, decision_name, phase_number, parent_phase_id, text FROM main.roadmap_phases WHERE id = ?').get(cursor);
+    if (cur) {
+      // Walk up to find the root phase if this is a sub-task
+      let rootDecision = cur.decision_name;
+      let rootPhaseNum = cur.phase_number;
+      let walker = cur;
+      while (walker.parent_phase_id != null) {
+        walker = db.prepare('SELECT id, decision_name, phase_number, parent_phase_id FROM main.roadmap_phases WHERE id = ?').get(walker.parent_phase_id);
+        if (!walker) break;
+        rootDecision = walker.decision_name ?? rootDecision;
+        rootPhaseNum = walker.phase_number ?? rootPhaseNum;
+      }
+      currentLabel = cur.phase_number != null
+        ? `${cur.decision_name} / Phase ${cur.phase_number} (${cur.text})`
+        : `${rootDecision} / Phase ${rootPhaseNum} → sub: ${cur.text}`;
+    }
+  }
+  return {
+    decisions_total: byDecision.size,
+    decisions_in_flight: inFlight,
+    cursor_phase_id: cursor,
+    current: currentLabel,
+  };
+}
+
+export function roadmap(db, args = {}) {
+  const action = args.action ?? 'tree';
+  const { id, status, parent, text } = args;
+
+  switch (action) {
+    case 'tree': {
+      const out = renderTree(db, { compact: args.compact === true, hideStale: args.hide_stale === true });
+      const summary = statusSummary(db);
+      const lines = [out, '', summary.current
+        ? `Current: ${summary.current}`
+        : '(no cursor set — call cairn_roadmap focus <id>)'];
+      if (summary.decisions_in_flight > 1) {
+        lines.push(`In flight: ${summary.decisions_in_flight} decisions`);
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+
+    case 'status': {
+      return { content: [{ type: 'text', text: JSON.stringify(statusSummary(db), null, 2) }] };
+    }
+
+    case 'focus': {
+      if (!id) throw new Error('id is required for focus');
+      const phase = db.prepare('SELECT * FROM main.roadmap_phases WHERE id = ?').get(id);
+      if (!phase) throw new Error(`No phase with id ${id}`);
+      if (phase.status === 'stale') throw new Error(`Phase ${id} is stale — restore via decision memo edit`);
+      activatePhase(db, id);
+      const refreshed = db.prepare('SELECT * FROM main.roadmap_phases WHERE id = ?').get(id);
+      return { content: [{ type: 'text', text: JSON.stringify({ focused: refreshed }, null, 2) }] };
+    }
+
+    case 'next': {
+      const cursor = getCursor(db);
+      const next = findNextActionable(db, cursor);
+      if (next == null) {
+        clearCursor(db);
+        return { content: [{ type: 'text', text: JSON.stringify({ cursor: null, message: 'No actionable phases remaining.' }, null, 2) }] };
+      }
+      activatePhase(db, next);
+      const phase = db.prepare('SELECT * FROM main.roadmap_phases WHERE id = ?').get(next);
+      return { content: [{ type: 'text', text: JSON.stringify({ cursor: next, phase }, null, 2) }] };
+    }
+
+    case 'set_status': {
+      if (!id) throw new Error('id is required for set_status');
+      if (!status) throw new Error('status is required for set_status');
+      if (!VALID_STATUS.has(status)) {
+        throw new Error(`Invalid status "${status}". Use: ${[...VALID_STATUS].join(', ')}`);
+      }
+      const resolvedAt = status === 'done' ? "datetime('now')" : 'NULL';
+      const updated = db.prepare(
+        `UPDATE main.roadmap_phases SET status = ?, resolved_at = ${resolvedAt} WHERE id = ?`
+      ).run(status, id);
+      if (updated.changes === 0) throw new Error(`No phase with id ${id}`);
+      // If we just marked the cursor done, auto-advance and activate the new node.
+      let advancedTo = null;
+      if (status === 'done' && getCursor(db) === id) {
+        const next = findNextActionable(db, id);
+        if (next != null) { activatePhase(db, next); advancedTo = next; }
+        else clearCursor(db);
+      }
+      const phase = db.prepare('SELECT * FROM main.roadmap_phases WHERE id = ?').get(id);
+      return { content: [{ type: 'text', text: JSON.stringify({ updated: phase, cursor_advanced_to: advancedTo }, null, 2) }] };
+    }
+
+    case 'add': {
+      if (!text) throw new Error('text is required for add');
+      if (parent == null) throw new Error('parent (phase_id) is required — ad-hoc sub-tasks must hang under an existing phase. For freestanding work use cairn_todos add.');
+      const parentRow = db.prepare('SELECT id, decision_name FROM main.roadmap_phases WHERE id = ?').get(parent);
+      if (!parentRow) throw new Error(`Parent phase ${parent} not found`);
+      const nextPos = db.prepare(
+        'SELECT COALESCE(MAX(position), -1) + 1 AS n FROM main.roadmap_phases WHERE parent_phase_id = ?'
+      ).get(parent).n;
+      const result = db.prepare(
+        'INSERT INTO main.roadmap_phases (decision_name, phase_number, parent_phase_id, text, status, position) VALUES (NULL, NULL, ?, ?, ?, ?)'
+      ).run(parent, text, 'open', nextPos);
+      const inserted = db.prepare('SELECT * FROM main.roadmap_phases WHERE id = ?').get(result.lastInsertRowid);
+      return { content: [{ type: 'text', text: JSON.stringify({ added: inserted, inherits_decision_from: parentRow.decision_name }, null, 2) }] };
+    }
+
+    default:
+      throw new Error(`Unknown action: "${action}". Use tree, status, focus, next, set_status, or add.`);
+  }
+}

package/src/tools/todos.js

@@ -1,6 +1,10 @@
 import { walkRepo } from '../indexer/fileWalker.js';
 import { scanTodos } from '../indexer/todoScanner.js';
 
+// cairn_todos is the long-tail backlog: scanned TODO/FIXME/HACK comments + manual notes.
+// For active multi-phase plans (with status/cursor/decision-memo), use cairn_roadmap instead.
+// The parent_id/position columns added in v1.9.0 are dormant — kept on the table for back-compat
+// but no longer read by tools.
 export async function todos(db, args = {}) {
   const { text, id, status, source } = args;
   const action = args.action ?? 'list';

package/test/roadmap.test.js

@@ -0,0 +1,196 @@
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { DatabaseSync } from 'node:sqlite';
+import { parsePhases, syncPhasesToRoadmap } from '../src/tools/memo.js';
+import { roadmap } from '../src/tools/roadmap.js';
+
+// Build a fresh in-memory DB with the v1.10.0 schema (mirrors db.js SCHEMA, scoped).
+function makeDB() {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE todos (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT, file TEXT, line INTEGER,
+      kind TEXT, text TEXT, status TEXT DEFAULT 'open', parent_id INTEGER, position INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now')), resolved_at TEXT
+    );
+    CREATE TABLE roadmap_cursor (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      todo_id INTEGER, phase_id INTEGER
+    );
+    CREATE TABLE roadmap_phases (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      decision_name TEXT, phase_number INTEGER, parent_phase_id INTEGER REFERENCES roadmap_phases(id) ON DELETE CASCADE,
+      text TEXT NOT NULL, body TEXT, status TEXT DEFAULT 'open', position INTEGER DEFAULT 0,
+      created_at TEXT DEFAULT (datetime('now')), resolved_at TEXT
+    );
+    CREATE UNIQUE INDEX idx_roadmap_phases_decision_phase
+      ON roadmap_phases(decision_name, phase_number)
+      WHERE decision_name IS NOT NULL AND phase_number IS NOT NULL;
+  `);
+  return db;
+}
+
+test('parsePhases extracts ### Phase N: text + body until next ## heading', () => {
+  const memo = `Why explanation.
+
+## Phases
+
+### Phase 1: First
+Body of first.
+Multiple lines.
+
+### Phase 2: Second
+Just one line.
+
+## Tradeoffs
+Should not be parsed.
+`;
+  const phases = parsePhases(memo);
+  assert.equal(phases.length, 2);
+  assert.equal(phases[0].phase_number, 1);
+  assert.equal(phases[0].text, 'First');
+  assert.equal(phases[0].body, 'Body of first.\nMultiple lines.');
+  assert.equal(phases[1].phase_number, 2);
+  assert.equal(phases[1].body, 'Just one line.');
+});
+
+test('parsePhases returns [] when no ## Phases section exists', () => {
+  assert.deepEqual(parsePhases('No phases here.\n\n## Other heading\nstuff'), []);
+});
+
+test('parsePhases ignores duplicate phase numbers (first wins)', () => {
+  const memo = `## Phases\n### Phase 1: A\n### Phase 1: B\n### Phase 2: C\n`;
+  const phases = parsePhases(memo);
+  assert.equal(phases.length, 2);
+  assert.equal(phases[0].text, 'A');
+  assert.equal(phases[1].phase_number, 2);
+});
+
+test('syncPhasesToRoadmap: insert on first, preserve status on update, stale on remove', () => {
+  const db = makeDB();
+  const phases = [
+    { phase_number: 1, text: 'First', body: 'b1' },
+    { phase_number: 2, text: 'Second', body: 'b2' },
+    { phase_number: 3, text: 'Third', body: 'b3' },
+  ];
+  let r = syncPhasesToRoadmap(db, 'demo', phases);
+  assert.deepEqual(r, { updated: 0, inserted: 3, staled: 0 });
+
+  // Mark Phase 2 as in_progress, then re-sync without Phase 1
+  db.prepare("UPDATE roadmap_phases SET status='in_progress' WHERE phase_number=2 AND decision_name='demo'").run();
+  const phases2 = [
+    { phase_number: 2, text: 'Second renamed', body: 'b2-new' },
+    { phase_number: 3, text: 'Third', body: 'b3' },
+    { phase_number: 4, text: 'Fourth', body: 'b4' },
+  ];
+  r = syncPhasesToRoadmap(db, 'demo', phases2);
+  assert.deepEqual(r, { updated: 2, inserted: 1, staled: 1 });
+
+  const all = JSON.parse(JSON.stringify(
+    db.prepare("SELECT phase_number, status, text FROM roadmap_phases WHERE decision_name='demo' ORDER BY phase_number").all()
+  ));
+  assert.deepEqual(all, [
+    { phase_number: 1, status: 'stale', text: 'First' },
+    { phase_number: 2, status: 'in_progress', text: 'Second renamed' },
+    { phase_number: 3, status: 'open', text: 'Third' },
+    { phase_number: 4, status: 'open', text: 'Fourth' },
+  ]);
+});
+
+test('syncPhasesToRoadmap: re-add of stale phase reactivates it to open', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [{ phase_number: 1, text: 'A', body: null }]);
+  db.prepare("UPDATE roadmap_phases SET status='stale' WHERE phase_number=1").run();
+  syncPhasesToRoadmap(db, 'demo', [{ phase_number: 1, text: 'A back', body: null }]);
+  const row = db.prepare("SELECT status, text FROM roadmap_phases WHERE phase_number=1").get();
+  assert.equal(row.status, 'open');
+  assert.equal(row.text, 'A back');
+});
+
+test('roadmap focus: marks phase in_progress + propagates up + sets cursor', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [
+    { phase_number: 1, text: 'A', body: null },
+    { phase_number: 2, text: 'B', body: null },
+  ]);
+  const phase2 = db.prepare("SELECT id FROM roadmap_phases WHERE phase_number=2").get().id;
+  // Add a sub-task under phase 2
+  const sub = JSON.parse(roadmap(db, { action: 'add', parent: phase2, text: 'subtask' }).content[0].text).added.id;
+  roadmap(db, { action: 'focus', id: sub });
+  const subAfter = db.prepare("SELECT status FROM roadmap_phases WHERE id=?").get(sub);
+  const phase2After = db.prepare("SELECT status FROM roadmap_phases WHERE id=?").get(phase2);
+  const cursor = db.prepare('SELECT phase_id FROM roadmap_cursor WHERE singleton=1').get().phase_id;
+  assert.equal(subAfter.status, 'in_progress');
+  assert.equal(phase2After.status, 'in_progress');
+  assert.equal(cursor, sub);
+});
+
+test('roadmap next: DFS-advances skipping stale, never landing on stale', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [
+    { phase_number: 1, text: 'A', body: null },
+    { phase_number: 2, text: 'B', body: null },
+    { phase_number: 3, text: 'C', body: null },
+  ]);
+  db.prepare("UPDATE roadmap_phases SET status='stale' WHERE phase_number=2").run();
+  // Cursor null -> next should land on Phase 1 (first actionable)
+  let next = JSON.parse(roadmap(db, { action: 'next' }).content[0].text);
+  assert.equal(next.phase.phase_number, 1);
+  // From Phase 1 -> next should skip stale Phase 2 and land on Phase 3
+  next = JSON.parse(roadmap(db, { action: 'next' }).content[0].text);
+  assert.equal(next.phase.phase_number, 3);
+});
+
+test('roadmap set_status done auto-advances cursor to next actionable', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [
+    { phase_number: 1, text: 'A', body: null },
+    { phase_number: 2, text: 'B', body: null },
+  ]);
+  const p1 = db.prepare("SELECT id FROM roadmap_phases WHERE phase_number=1").get().id;
+  roadmap(db, { action: 'focus', id: p1 });
+  const r = JSON.parse(roadmap(db, { action: 'set_status', id: p1, status: 'done' }).content[0].text);
+  const p2 = db.prepare("SELECT id FROM roadmap_phases WHERE phase_number=2").get().id;
+  assert.equal(r.cursor_advanced_to, p2);
+  // The new cursor should also be in_progress (activatePhase was called)
+  const p2Status = db.prepare("SELECT status FROM roadmap_phases WHERE id=?").get(p2).status;
+  assert.equal(p2Status, 'in_progress');
+});
+
+test('roadmap add: requires parent phase, inherits decision_name=null on the row', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [{ phase_number: 1, text: 'A', body: null }]);
+  const p1 = db.prepare("SELECT id FROM roadmap_phases WHERE phase_number=1").get().id;
+  // No parent should fail
+  assert.throws(() => roadmap(db, { action: 'add', text: 'orphan' }), /parent.*required/i);
+  // With parent, it inserts with NULL decision_name (sub-task)
+  const r = JSON.parse(roadmap(db, { action: 'add', parent: p1, text: 'sub' }).content[0].text);
+  assert.equal(r.added.parent_phase_id, p1);
+  assert.equal(r.added.decision_name, null);
+  assert.equal(r.added.phase_number, null);
+  assert.equal(r.inherits_decision_from, 'demo');
+});
+
+test('roadmap focus: refuses stale phase', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo', [{ phase_number: 1, text: 'A', body: null }]);
+  const p1 = db.prepare("SELECT id FROM roadmap_phases WHERE phase_number=1").get().id;
+  db.prepare("UPDATE roadmap_phases SET status='stale' WHERE id=?").run(p1);
+  assert.throws(() => roadmap(db, { action: 'focus', id: p1 }), /stale/i);
+});
+
+test('roadmap status: counts decisions in flight + reports current cursor with sub-task root walk', () => {
+  const db = makeDB();
+  syncPhasesToRoadmap(db, 'demo_a', [
+    { phase_number: 1, text: 'A1', body: null },
+    { phase_number: 2, text: 'A2', body: null },
+  ]);
+  syncPhasesToRoadmap(db, 'demo_b', [{ phase_number: 1, text: 'B1', body: null }]);
+  const a2 = db.prepare("SELECT id FROM roadmap_phases WHERE decision_name='demo_a' AND phase_number=2").get().id;
+  const sub = JSON.parse(roadmap(db, { action: 'add', parent: a2, text: 'subA2' }).content[0].text).added.id;
+  roadmap(db, { action: 'focus', id: sub });
+  const status = JSON.parse(roadmap(db, { action: 'status' }).content[0].text);
+  assert.equal(status.decisions_total, 2);
+  assert.equal(status.decisions_in_flight, 2);
+  assert.match(status.current, /demo_a \/ Phase 2 → sub: subA2/);
+});