@misterhuydo/cairn-mcp 1.17.0 → 1.19.0

package/README.md

@@ -50,10 +50,10 @@ server load.
 | Hook | Trigger | Effect |
 |---|---|---|
 | `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 |
+| `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first. Reported as a permission decision with a one-line reason, **not** as a red hook error: being sent back to re-read a file is a normal step, and the full source rides along out of sight so it does not fill the screen |
 | `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 |
+| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, the roadmap re-surfaced, any git-detected completed phases surfaced for you to confirm, and on a long session one line naming what clearing would cost — 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) |
 
 ---
@@ -83,7 +83,7 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 | `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_checkpoint` | Save session state (auto-handled by hooks). At a stopping point, answer `would_be_lost` — the one part that git and the index cannot recover |
 | `cairn_minify` | Minify a single file on demand (fallback when hooks are not installed) |
 | `cairn_switch` | Switch active project root mid-session (use for maintenance on a sibling service) |
 | `cairn_memo` | Save a preference, decision, or discovery to the project's persistent memory |
@@ -169,24 +169,41 @@ cairn_roadmap { action: "deps_add", from: 2, to: 4 }           → phase 2 block
 cairn_roadmap { action: "publish" }              → (re)write the human-readable ROADMAP.md at the repo root
 ```
 
-The live plan is also projected into a legible **`ROADMAP.md` at the repo root** — a
-human-readable view with checkboxes, per-item status, and a `← current` marker on the
-cursor phase. It refreshes automatically on session activity (the end-of-turn hook and
-the first prompt of a session) as well as on every `cairn_roadmap` call, so a workspace
-that has a roadmap but hasn't touched the roadmap tool this session still shows a
-populated file. It is deterministic (no timestamps, stable ordering, so an unchanged
-plan re-writes byte-identically and leaves clean git diffs), never written as an empty
-placeholder, and written atomically (temp file + rename) so a reader never catches a
-half-written plan.
+The live plan is also projected into a **`ROADMAP.md` at the repo root**, published in
+the **`roadmap/1`** slot format so any cockpit or tool can read it without writing a
+parser per provider. One file carries both halves — two files drift, and the drift is
+invisible:
+
+- **A markdown half for humans:** checkboxes, per-item status, a one-line summary per
+  phase, and a `← current` marker on the cursor phase.
+- **One `roadmap-json` block for consumers**, at the end of the file. It carries stable
+  phase `id`s, `number`, `title`, `status`, `goal`, `blocked_by`, `slices`, the full
+  per-phase `detail` (the body you wrote in `.cairn/roadmap.md`), and `links` — the
+  `[[wikilinks]]` in that body resolved to the memory files behind each phase, so the
+  reasoning is one tap away instead of "go and find it". A link that cannot be resolved
+  is dropped rather than emitted dead.
+
+The first line is the marker that says who generated the file and when
+(`<!-- slot:roadmap format=roadmap/1 provider=cairn generated=… -->`). cairn declares
+the slot in its MCP entry in `~/.claude.json`, so a cockpit does not have to guess.
+
+It refreshes automatically on session activity (the end-of-turn hook and the first
+prompt of a session) as well as on every `cairn_roadmap` call, so a workspace that has a
+roadmap but hasn't touched the roadmap tool this session still shows a populated file.
+Phase `id`s are stable across regenerations (they key off the database row, so renaming
+a phase never changes its id), unknown JSON fields survive a rewrite, an unchanged plan
+re-writes byte-identically (the `generated` stamp is only refreshed when something
+actually changed, so diffs stay clean), nothing is ever written as an empty placeholder,
+and writes are atomic (temp file + rename) so a reader never catches a half-written plan.
 
 An existing `ROADMAP.md` is never destroyed. If the file is there but carries no
 provider marker (hand-written, or from a tool that doesn't stamp its output), cairn
 **adopts** it: the original is renamed to `ROADMAP.bak.md` (or `ROADMAP.bak.2.md`, `.3`,
-… — an existing backup is never overwritten), the generated file records where it came
-from (`migrated-from=ROADMAP.bak.md`), and the result reports `backed_up_to`. If the
-file is stamped by a *different* provider, that's a conflict over who owns the path:
-cairn leaves it completely alone. Any publish that declines returns a `warning` that the
-caller surfaces to you, so a stale plan can't rot in place unnoticed.
+… — an existing backup is never overwritten), the data block records `migrated_from`
+and `migrated`, and the result reports `backed_up_to`. If the file is stamped by a
+*different* provider, that's a conflict over who owns the path: cairn leaves it
+completely alone. Any publish that declines returns a `warning` that the caller surfaces
+to you, so a stale plan can't rot in place unnoticed.
 
 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
@@ -219,6 +236,52 @@ before calling `set_status … done`, so a stray keyword can't silently prune yo
 
 ---
 
+## Stopping points: what clearing would cost
+
+Before `/clear` or `/compact`, the question that actually matters is not *how full
+is the window*. Fullness tells you **when**; it never tells you **which**. What
+decides it is whether the saved state is sufficient — "the slice is three-quarters
+built and the fact that long-press selection has never run on a real handset is
+written down nowhere" is a judgement about the handoff, not about a percentage.
+
+Cairn cannot make that judgement for you. It cannot audit for absence: the gap
+worth reporting is by definition the thing nobody wrote down, and a lazy
+checkpoint looks exactly like a thorough one from the outside. A tool that
+computed this would print "nothing outstanding" on precisely the sessions where
+the most was outstanding. So cairn does the part it can do honestly — it **demands
+the judgement on the way in and carries it across the gap**:
+
+1. **`cairn_checkpoint` asks.** A `would_be_lost` field whose description is the
+   literal question: what would a fresh session not know? Unverified work, a
+   thread you are mid-way through, a decision whose reason never made it into the
+   commit message. A checkpoint that skips it says so in its result rather than
+   passing silently.
+2. **`cairn_resume` carries it back**, near the top of the payload and first in
+   the summary, because everything else resume returns is recoverable from git and
+   the index and this is the only part that is not. It also lands on the first
+   prompt of the next session, since a session picked up after `/clear` rarely
+   opens with the word "resume".
+3. **It ages.** The end-of-turn hook checkpoints every turn, so `session.json`
+   always *looks* fresh while its contents may be hours and several slices stale.
+   The handoff is stamped only when it is actually written, never by the
+   heartbeat that copies it forward, and anything written before commits that
+   have since landed is reported as possibly stale.
+4. **Then, and only then, one line.** When the session transcript crosses a coarse
+   size threshold **and** something is actually at risk, the Stop hook adds a line
+   naming the loss: *"Clearing now would lose: … — last written before the 3
+   commits since."* When the handoff is current it says what clearing costs
+   instead, which is the more useful message and the one that lets you actually
+   clear.
+
+Deliberately not built: no percentage (the transcript keeps growing across a
+compaction while the window resets, so a precise number would claim an accuracy
+it does not have), no transcript parsing (`statSync` only — this runs on every
+single turn), no repeating the line when nothing changed, and no auto-clearing,
+auto-compacting, or filling the field in on your behalf. Same shape as completed-phase
+detection: detect, surface, confirm with the user, never apply.
+
+---
+
 ## Supported languages
 
 | Language | What Cairn extracts |