@misterhuydo/cairn-mcp 1.8.1 → 1.9.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,82 @@ 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 + 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.
+  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); }
+
+  try {
+    const cursorRow = db.prepare(
+      "SELECT todo_id FROM roadmap_cursor WHERE singleton = 1"
+    ).get();
+    const cursorId = cursorRow?.todo_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'
+    ).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);
+    }
+
+    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);
+
+    // 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;
+      }
+      return null;
+    };
+    const cursorNode = all.find(t => t.id === cursorId);
+    const next = findNext(cursorId);
+
+    const out = [
+      '[cairn] ROADMAP — cursor is active. Tree:',
+      ...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);
+    process.stdout.write(out.join('\n') + '\n');
+  } catch {
+    try { db?.close(); } catch {}
+  }
+  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 +644,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 +669,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 +677,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 +710,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

@@ -262,20 +262,23 @@ 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: '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.',
       inputSchema: {
         type: 'object',
         properties: {
           action: {
             type: 'string',
-            enum: ['list', 'add', 'resolve', 'scan'],
-            description: 'list: show todos | add: create a manual todo | resolve: mark done by id | scan: re-scan codebase',
+            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',
           },
-          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)' },
+          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)' },
         },
         required: ['action'],
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.8.1",
+  "version": "1.9.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,16 @@ 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
+  );
 `;
 
 // Each sub-DB gets its IDs offset by this multiplier to prevent collisions
@@ -190,6 +197,24 @@ 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)
+  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 = (
+        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
+      )
+    `);
+  }
   mountParentSubIndexes(db);
   refreshFederatedViews(db);
   return db;

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/todos.js

@@ -1,8 +1,113 @@
 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;
+}
+
 export async function todos(db, args = {}) {
-  const { text, id, status, source } = args;
+  const { text, id, status, source, parent, position } = args;
   const action = args.action ?? 'list';
   const kind = args.kind;
 
@@ -13,9 +118,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 ELSE 1 END, source, file, line';
+      query += ' ORDER BY CASE status WHEN \'open\' THEN 0 WHEN \'in_progress\' THEN 0 ELSE 1 END, source, file, line';
       const rows = db.prepare(query).all(...params);
-      const open = rows.filter(r => r.status === 'open').length;
+      const open = rows.filter(r => r.status === 'open' || r.status === 'in_progress').length;
       const done = rows.filter(r => r.status === 'done').length;
       return {
         content: [{
@@ -25,12 +130,34 @@ 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) VALUES (?, ?, ?)'
-      ).run('manual', todoKind, text);
+        'INSERT INTO main.todos (source, kind, text, parent_id, position) VALUES (?, ?, ?, ?, ?)'
+      ).run('manual', todoKind, text, parentId, pos);
       const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(result.lastInsertRowid);
       return {
         content: [{ type: 'text', text: JSON.stringify({ added: todo }, null, 2) }],
@@ -43,9 +170,63 @@ 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({ resolved: todo }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify({ updated: todo }, null, 2) }],
       };
     }
 
@@ -53,7 +234,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 = \'open\''
+        'SELECT COUNT(*) AS n FROM main.todos WHERE status IN (\'open\', \'in_progress\')'
       ).get().n;
       return {
         content: [{
@@ -64,6 +245,6 @@ export async function todos(db, args = {}) {
     }
 
     default:
-      throw new Error(`Unknown action: "${action}". Use list, add, resolve, or scan.`);
+      throw new Error(`Unknown action: "${action}". Use list, tree, add, resolve, focus, next, set_status, or scan.`);
   }
 }