@misterhuydo/cairn-mcp 1.18.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 |
@@ -236,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 |