@misterhuydo/cairn-mcp 1.9.0 → 1.10.0

package/bin/cairn-cli.js

@@ -537,9 +537,11 @@ if (subcommand === '--version' || subcommand === '-v') {
   process.exit(0);
 
 } else if (subcommand === 'roadmap-hint') {
-  // Stop hook: print the roadmap tree + cursor only when a cursor is set.
-  // Silent (exit 0) for projects with no .cairn, no DB, or no cursor — so
-  // normal chat is unaffected. Activates the moment cairn_todos focus is called.
+  // 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);
@@ -550,65 +552,139 @@ if (subcommand === '--version' || subcommand === '-v') {
   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 todo_id FROM roadmap_cursor WHERE singleton = 1"
-    ).get();
-    const cursorId = cursorRow?.todo_id ?? null;
+    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, parent_id, position, status, text FROM todos ORDER BY IFNULL(parent_id, -1), position, id'
+      'SELECT id, decision_name, phase_number, parent_phase_id, text, status, position FROM roadmap_phases ORDER BY decision_name, phase_number, position, id'
     ).all();
-    db.close();
 
-    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);
+    // 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 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);
+    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);
       }
     };
-    visit(null, 0);
-
-    // Compute "Next" via DFS: first open child of cursor → next open sibling/uncle.
-    const isOpenish = (s) => s === 'open' || s === 'in_progress';
-    const findNext = (fromId) => {
-      const kids = (childrenByParent.get(fromId) || []).filter(t => isOpenish(t.status));
-      if (kids.length > 0) return kids[0];
-      let curId = fromId;
-      while (curId != null) {
-        const cur = all.find(t => t.id === curId);
-        if (!cur) return null;
-        const siblings = (childrenByParent.get(cur.parent_id ?? null) || [])
-          .filter(t => isOpenish(t.status) && (t.position > cur.position || (t.position === cur.position && t.id > cur.id)));
-        if (siblings.length > 0) return siblings[0];
-        curId = cur.parent_id;
+    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);
       }
-      return null;
-    };
-    const cursorNode = all.find(t => t.id === cursorId);
-    const next = findNext(cursorId);
+    }
+
+    // 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. Tree:',
+      '[cairn] ROADMAP — cursor is active.',
       ...lines.map(l => '[cairn]   ' + l),
-      cursorNode ? `[cairn] Current: (id:${cursorNode.id}) ${cursorNode.text}` : '',
-      next ? `[cairn] Next:    (id:${next.id}) ${next.text}` : '[cairn] Next:    (no open todos remaining)',
-      '[cairn] Use cairn_todos resolve <id> to mark done (auto-advances), focus <id> to move cursor, or next to advance manually.',
-    ].filter(Boolean);
+    ];
+    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 {
+  } catch (e) {
     try { db?.close(); } catch {}
+    process.stderr.write(`[cairn] roadmap-hint error: ${e.message}\n`);
   }
   process.exit(0);
 

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,23 +263,41 @@ 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 and multi-phase roadmaps. Supports a tree of nested phases with a "current cursor" pointer so multi-phase plans survive context drift. Use action=tree to render the roadmap, focus to set the cursor, next to advance. 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: {
           action: {
             type: 'string',
-            enum: ['list', 'tree', 'add', 'resolve', 'focus', 'next', 'set_status', 'scan'],
-            description: 'list: flat list | tree: hierarchical roadmap with cursor | add: create manual todo (use parent + position for nesting) | resolve: mark done | focus: move cursor to id, mark in_progress, propagate up | next: DFS-advance cursor to next open node | set_status: set status to open|in_progress|done|blocked | scan: re-scan codebase',
+            enum: ['list', 'add', 'resolve', 'scan'],
+            description: 'list: show todos | add: create a manual todo | resolve: mark done by id | scan: re-scan codebase',
           },
-          text:     { type: 'string',  description: 'Text for the new todo (add action)' },
-          kind:     { type: 'string',  enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE'], description: 'Kind for new todo (default: TODO)' },
-          id:       { type: 'number',  description: 'Todo ID (resolve, focus, set_status)' },
-          status:   { type: 'string',  enum: ['open', 'in_progress', 'done', 'blocked'], description: 'Filter (list) or new value (set_status)' },
-          source:   { type: 'string',  enum: ['scan', 'manual'], description: 'Filter by source (list action)' },
-          parent:   { type: 'number',  description: 'Parent todo ID for nesting (add action). Omit for root/phase.' },
-          position: { type: 'number',  description: 'Sibling order within parent (add action). Auto-appends if omitted.' },
-          compact:  { type: 'boolean', description: 'Compact tree render — strips id/kind tags (tree action)' },
+          text:   { type: 'string',  description: 'Text for the new todo (add action)' },
+          kind:   { type: 'string',  enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE'], description: 'Kind for new todo (default: TODO)' },
+          id:     { type: 'number',  description: 'Todo ID to resolve (resolve action)' },
+          status: { type: 'string',  enum: ['open', 'done'], description: 'Filter by status (list action)' },
+          source: { type: 'string',  enum: ['scan', 'manual'], description: 'Filter by source (list action)' },
+        },
+        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'],
       },
@@ -303,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.9.0",
+  "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

@@ -77,6 +77,22 @@ const SCHEMA = `
     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
@@ -197,13 +213,13 @@ 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 (idempotent — fails silently if present)
+  // 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) {
-    // Backfill position by id order within each parent group (null parent = root).
-    // ROW_NUMBER() requires SQLite 3.25+, which node:sqlite ships.
     db.exec(`
       UPDATE main.todos AS t
       SET position = (
@@ -215,6 +231,48 @@ export function openDB() {
       )
     `);
   }
+  // 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/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,113 +1,12 @@
 import { walkRepo } from '../indexer/fileWalker.js';
 import { scanTodos } from '../indexer/todoScanner.js';
 
-const STATUS_BOX = {
-  open: '[ ]',
-  in_progress: '[~]',
-  done: '[x]',
-  blocked: '[!]',
-};
-
-const VALID_STATUS = new Set(['open', 'in_progress', 'done', 'blocked']);
-
-function getCursor(db) {
-  const row = db.prepare('SELECT todo_id FROM main.roadmap_cursor WHERE singleton = 1').get();
-  return row?.todo_id ?? null;
-}
-
-function setCursor(db, todoId) {
-  db.prepare('INSERT OR REPLACE INTO main.roadmap_cursor (singleton, todo_id) VALUES (1, ?)').run(todoId);
-}
-
-function clearCursor(db) {
-  db.prepare('DELETE FROM main.roadmap_cursor WHERE singleton = 1').run();
-}
-
-// Mark ancestors as in_progress (only if currently 'open' — don't downgrade done/blocked).
-function propagateInProgressUp(db, todoId) {
-  const stmt = db.prepare('SELECT parent_id, status FROM main.todos WHERE id = ?');
-  const update = db.prepare("UPDATE main.todos SET status = 'in_progress' WHERE id = ? AND status = 'open'");
-  let cur = stmt.get(todoId);
-  while (cur && cur.parent_id != null) {
-    update.run(cur.parent_id);
-    cur = stmt.get(cur.parent_id);
-  }
-}
-
-// DFS-find next actionable node starting at/after `fromId`.
-// Order: first open child → next open sibling → next open uncle (walk up).
-function findNextOpen(db, fromId) {
-  const childOf = (pid) => db.prepare(
-    `SELECT id FROM main.todos
-     WHERE ${pid == null ? 'parent_id IS NULL' : 'parent_id = ?'}
-       AND status IN ('open', 'in_progress')
-     ORDER BY position, id`
-  ).all(...(pid == null ? [] : [pid]));
-
-  if (fromId == null) {
-    const roots = childOf(null);
-    return roots[0]?.id ?? null;
-  }
-
-  const children = childOf(fromId);
-  if (children.length > 0) return children[0].id;
-
-  let curId = fromId;
-  while (curId != null) {
-    const cur = db.prepare('SELECT parent_id, position FROM main.todos WHERE id = ?').get(curId);
-    if (!cur) return null;
-    const sibling = db.prepare(
-      `SELECT id FROM main.todos
-       WHERE ${cur.parent_id == null ? 'parent_id IS NULL' : 'parent_id = ?'}
-         AND (position > ? OR (position = ? AND id > ?))
-         AND status IN ('open', 'in_progress')
-       ORDER BY position, id LIMIT 1`
-    ).get(...(cur.parent_id == null ? [cur.position, cur.position, curId] : [cur.parent_id, cur.position, cur.position, curId]));
-    if (sibling) return sibling.id;
-    curId = cur.parent_id;
-  }
-  return null;
-}
-
-function renderTree(db, { compact = false } = {}) {
-  const all = db.prepare(
-    'SELECT id, parent_id, position, status, kind, text FROM main.todos ORDER BY IFNULL(parent_id, -1), position, id'
-  ).all();
-  if (all.length === 0) return '(no todos)';
-
-  const cursor = getCursor(db);
-  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) => {
-    const kids = childrenByParent.get(parentId) || [];
-    for (const t of kids) {
-      const box = STATUS_BOX[t.status] || '[?]';
-      const arrow = cursor === t.id ? ' →' : '';
-      const tag = compact ? '' : ` (id:${t.id}${t.kind !== 'TODO' ? `, ${t.kind}` : ''})`;
-      lines.push(`${'  '.repeat(depth)}${box}${arrow} ${t.text}${tag}`);
-      visit(t.id, depth + 1);
-    }
-  };
-  visit(null, 0);
-  return lines.join('\n');
-}
-
-function nextPosition(db, parentId) {
-  const row = db.prepare(
-    `SELECT COALESCE(MAX(position), -1) + 1 AS next FROM main.todos
-     WHERE ${parentId == null ? 'parent_id IS NULL' : 'parent_id = ?'}`
-  ).get(...(parentId == null ? [] : [parentId]));
-  return row.next;
-}
-
+// 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, parent, position } = args;
+  const { text, id, status, source } = args;
   const action = args.action ?? 'list';
   const kind = args.kind;
 
@@ -118,9 +17,9 @@ export async function todos(db, args = {}) {
       if (status) { query += ' AND status = ?'; params.push(status); }
       if (source) { query += ' AND source = ?'; params.push(source); }
       if (kind)   { query += ' AND kind = ?';   params.push(kind.toUpperCase()); }
-      query += ' ORDER BY CASE status WHEN \'open\' THEN 0 WHEN \'in_progress\' THEN 0 ELSE 1 END, source, file, line';
+      query += ' ORDER BY CASE status WHEN \'open\' THEN 0 ELSE 1 END, source, file, line';
       const rows = db.prepare(query).all(...params);
-      const open = rows.filter(r => r.status === 'open' || r.status === 'in_progress').length;
+      const open = rows.filter(r => r.status === 'open').length;
       const done = rows.filter(r => r.status === 'done').length;
       return {
         content: [{
@@ -130,34 +29,12 @@ export async function todos(db, args = {}) {
       };
     }
 
-    case 'tree': {
-      const compact = args.compact === true;
-      const tree = renderTree(db, { compact });
-      const cursor = getCursor(db);
-      const cursorRow = cursor ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(cursor) : null;
-      const next = findNextOpen(db, cursor);
-      const nextRow = next ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(next) : null;
-      const summary = [
-        cursorRow ? `Current: (id:${cursorRow.id}) ${cursorRow.text}` : 'Current: (no cursor set)',
-        nextRow && (!cursorRow || nextRow.id !== cursorRow.id) ? `Next: (id:${nextRow.id}) ${nextRow.text}` : '',
-      ].filter(Boolean).join('\n');
-      return {
-        content: [{ type: 'text', text: `${tree}\n\n${summary}` }],
-      };
-    }
-
     case 'add': {
       if (!text) throw new Error('text is required for add action');
       const todoKind = (kind || 'TODO').toUpperCase();
-      const parentId = parent ?? null;
-      if (parentId != null) {
-        const exists = db.prepare('SELECT id FROM main.todos WHERE id = ?').get(parentId);
-        if (!exists) throw new Error(`Parent todo id ${parentId} does not exist`);
-      }
-      const pos = position ?? nextPosition(db, parentId);
       const result = db.prepare(
-        'INSERT INTO main.todos (source, kind, text, parent_id, position) VALUES (?, ?, ?, ?, ?)'
-      ).run('manual', todoKind, text, parentId, pos);
+        'INSERT INTO main.todos (source, kind, text) VALUES (?, ?, ?)'
+      ).run('manual', todoKind, text);
       const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(result.lastInsertRowid);
       return {
         content: [{ type: 'text', text: JSON.stringify({ added: todo }, null, 2) }],
@@ -170,63 +47,9 @@ export async function todos(db, args = {}) {
         'UPDATE main.todos SET status = ?, resolved_at = datetime(\'now\') WHERE id = ?'
       ).run('done', id);
       if (updated.changes === 0) throw new Error(`No todo found with id ${id}`);
-      const cursor = getCursor(db);
-      let advanced = null;
-      if (cursor === id) {
-        const next = findNextOpen(db, id);
-        if (next) { setCursor(db, next); advanced = next; }
-        else clearCursor(db);
-      }
-      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
-      return {
-        content: [{ type: 'text', text: JSON.stringify({ resolved: todo, cursor_advanced_to: advanced }, null, 2) }],
-      };
-    }
-
-    case 'focus': {
-      if (!id) throw new Error('id is required for focus action');
-      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
-      if (!todo) throw new Error(`No todo found with id ${id}`);
-      setCursor(db, id);
-      db.prepare("UPDATE main.todos SET status = 'in_progress' WHERE id = ? AND status = 'open'").run(id);
-      propagateInProgressUp(db, id);
-      const refreshed = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
-      return {
-        content: [{ type: 'text', text: JSON.stringify({ focused: refreshed }, null, 2) }],
-      };
-    }
-
-    case 'next': {
-      const cursor = getCursor(db);
-      const next = findNextOpen(db, cursor);
-      if (next == null) {
-        clearCursor(db);
-        return {
-          content: [{ type: 'text', text: JSON.stringify({ cursor: null, message: 'No open todos remaining.' }, null, 2) }],
-        };
-      }
-      setCursor(db, next);
-      propagateInProgressUp(db, next);
-      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(next);
-      return {
-        content: [{ type: 'text', text: JSON.stringify({ cursor: next, todo }, null, 2) }],
-      };
-    }
-
-    case 'set_status': {
-      if (!id) throw new Error('id is required for set_status action');
-      if (!status) throw new Error('status is required for set_status action');
-      if (!VALID_STATUS.has(status)) {
-        throw new Error(`Invalid status "${status}". Use: open, in_progress, done, blocked`);
-      }
-      const resolvedAt = status === 'done' ? "datetime('now')" : 'NULL';
-      const updated = db.prepare(
-        `UPDATE main.todos SET status = ?, resolved_at = ${resolvedAt} WHERE id = ?`
-      ).run(status, id);
-      if (updated.changes === 0) throw new Error(`No todo found with id ${id}`);
       const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
       return {
-        content: [{ type: 'text', text: JSON.stringify({ updated: todo }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify({ resolved: todo }, null, 2) }],
       };
     }
 
@@ -234,7 +57,7 @@ export async function todos(db, args = {}) {
       const files = await walkRepo(process.cwd());
       const found = await scanTodos(db, files);
       const open = db.prepare(
-        'SELECT COUNT(*) AS n FROM main.todos WHERE status IN (\'open\', \'in_progress\')'
+        'SELECT COUNT(*) AS n FROM main.todos WHERE status = \'open\''
       ).get().n;
       return {
         content: [{
@@ -245,6 +68,6 @@ export async function todos(db, args = {}) {
     }
 
     default:
-      throw new Error(`Unknown action: "${action}". Use list, tree, add, resolve, focus, next, set_status, or scan.`);
+      throw new Error(`Unknown action: "${action}". Use list, add, resolve, or scan.`);
   }
 }

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/);
+});