@misterhuydo/cairn-mcp 1.10.0 → 1.14.0

package/README.md

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