@misterhuydo/cairn-mcp 1.19.0 → 1.21.0

package/README.md

@@ -53,7 +53,8 @@ server load.
 | `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, 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 |
+| `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 — once the session is genuinely large — a prompt asking whether you want to `/clear` or `/compact`, with a recommendation and the reason. All in one line |
+| `SessionStart[clear]`<br>`SessionStart[compact]` | Right after you `/clear` or `/compact` | The checkpoint is re-injected into the fresh session automatically, so it opens already knowing the open thread and what the last session would have lost. You do not have to type "resume" |
 | `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) |
 
 ---
@@ -174,14 +175,26 @@ the **`roadmap/1`** slot format so any cockpit or tool can read it without writi
 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
+- **A markdown half for readers:** checkboxes, per-item status, a progress bar, one
+  plain sentence per phase, and a `← current` marker on the cursor phase. Written for
+  somebody who has never heard of cairn and is reading the file on GitHub: they should
+  be able to say what the project is working on and what is next. That means no
+  authoring syntax survives into the prose — `[[wikilinks]]` are unwrapped or dropped
+  (they are filenames a reader cannot open) and nothing points at `.cairn/`, which is
+  gitignored and therefore not there for them. `.cairn/roadmap.md` remains the
+  authoring source and stays as detailed as you like; this half is the summary.
+- **One `roadmap-json` block for consumers**, collapsed inside a `<details>` at the end
+  of the file so a reader never scrolls through it, and never removed — a cockpit's
+  per-phase view is rendered from it, and without it that view degrades silently to
+  flat markdown. Collapsing costs nothing: the fence keeps blank lines around it, so it
+  stays a valid CommonMark code block and both line-anchored and AST consumers still
+  find it. 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.
+  per-phase `detail` (the body you wrote in `.cairn/roadmap.md`, verbatim and in full —
+  thinning the prose never thins this), 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
@@ -266,19 +279,53 @@ the judgement on the way in and carries it across the gap**:
    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.
+4. **Then, and only then, it asks.** When the session crosses the threshold **and**
+   something is actually at risk, the Stop hook asks you to choose, with a
+   recommendation and the reason:
+
+   > **Checkpoint + /clear (Recommended)** — I write the handoff now, then you type `/clear`
+   > **Checkpoint + /compact** — I write the handoff now, then you type `/compact`
+   > **Keep going** — decline
+
+   Which one is recommended follows from the handoff, not from fullness. A
+   *current* handoff means the thread survives a hard reset, so `/clear` wins and
+   you get the full window back. A *missing or stale* one means something unwritten
+   is at risk, so `/compact` wins and keeps it reachable. Either choice writes the
+   checkpoint first — including `/clear`, which needs it most, not least.
+
+5. **And it is there afterwards.** `SessionStart[clear|compact]` re-injects the
+   checkpoint into the fresh session, so it opens already knowing where it is. You
+   never have to remember to type "resume", which is exactly the manual step that
+   gets skipped on the sessions where skipping it costs the most.
+
+**Cairn cannot type the command.** No hook output and no tool can trigger a slash
+command, so the agent does the half it can do (the checkpoint, immediately) and you
+type the six characters. Anything that claimed otherwise would leave you waiting for
+something that never happens.
+
+### How the size is measured
+
+Not from file size. No hook input carries token counts, but every hook receives
+`transcript_path`, and the transcript's assistant records carry the usage the API
+actually reported — so cairn tail-reads the last 256 KB and sums the real window
+(input + cache reads + cache creation + output). Measured cost: 6 lines parsed,
+0.5 ms.
+
+v1.19.0 used transcript bytes as the proxy and it was wrong in the one place that
+mattered. Measured on cairn's own session: **3.40 MB of transcript holding 72,285
+tokens of context.** Bytes keep accumulating across a `/compact` while the window
+resets, so a byte threshold is loudest immediately *after* a compaction, when there
+is least reason to speak. Bytes survive now only as a fallback for when no usage
+record is reachable, and when that happens the line says so instead of dressing a
+file size up as a token count.
+
+Deliberately not built: no percentage (the context-window size is not observable
+from a hook, so the denominator would be invented — the absolute count is reported
+instead), no full transcript walk (the tail only; a full walk in this hot path once
+froze every terminal in the cockpit for 4.3 seconds), no counting subagent spend as
+main-thread context, no repeating the prompt 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.
 
 ---