@misterhuydo/cairn-mcp 1.30.0 → 1.32.0

package/README.md

@@ -225,6 +225,32 @@ invisible:
   instead of "go and find it". A link that cannot be resolved is dropped rather than
   emitted dead.
 
+The two halves answer different questions and deliberately disagree. The reader half
+hides shipped and abandoned work so what is *next* leads. The JSON half publishes the
+plan **complete** — `done` and `stale` phases stay in `phases` with their real status,
+because a consumer that cannot see finished work will confidently render an incomplete
+plan. A shipped phase also carries `shipped` (the date) and `commit` (short HEAD when it
+was marked done), which is what turns "this was done" into something you can point an
+agent at when you are tracing a bug back to where it came from. Phases from *superseded*
+plans, whose numbers a later plan reclaimed, move to a separate `shipped_phases` array —
+identity and provenance only, no `detail`, so a long-lived repo's history cannot bloat
+the file. That key is always present; its absence means the file predates this.
+
+Three rules the format leaves implicit, each of which has cost a consumer real time:
+
+- **The `roadmap-json` block is terminated by a fence at the start of a line.** Match it
+  that way, not with a naive non-greedy `` ``` ``. This is safe by construction: a
+  newline inside a JSON string is escaped, so an embedded fence can never begin a line
+  and only the real terminator can.
+- **`detail` may itself contain fenced code**, which is exactly why the rule above
+  matters. A consumer that ends the block at the first `` ``` `` it meets can end it
+  *inside* a JSON string and spill ~125KB of machine data onto the page as prose.
+- **`cursor` may name a slice, not a top-level phase.** It is the exact focus. To mark
+  one phase current, use `cursor_phase`, which is always the top-level ancestor and
+  always resolves in `phases`; `cursor_path` is the root-to-focus chain for breadcrumbs.
+  All three are `null` when nothing is active, so "nothing is in progress" is never
+  ambiguous with a broken pointer.
+
 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.
@@ -348,19 +374,37 @@ 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.
 
-**It only speaks at 90% of the window and above.** The window size is not observable
-— no hook input carries it, and the transcript records usage but never a limit — so
-cairn infers the smallest window that could already hold what it has measured.
-Having *seen* 482k tokens proves the window is bigger than 200k, and that is the one
-direction the inference needs to be sound in. A fixed absolute threshold cannot
-serve both sizes: 120,000 tokens is 60% of a 200k window but 12% of a 1M one, which
-is why v1.20.0 announced a stopping point on a session sitting at just over half its
-context. Override with `CAIRN_CONTEXT_HINT_TOKENS` if you want a different bar.
-
-The one case the inference gets wrong: a 1M-window session between roughly 180k and
-196k looks like a nearly-full 200k one, so it may speak once. It corrects itself as
-soon as usage passes 200k, and the no-repeat rule means it says it once, not every
-turn.
+**It only speaks at 90% of the window and above** — and the window is a setting, not
+a measurement. Nothing cairn can read carries it: no hook input has it, the
+transcript records usage but never a limit, and the model id is no help either
+because a `claude-opus-5[1m]` session writes the base `claude-opus-5` into both the
+transcript's `message.model` and `lastModelUsage` in `~/.claude.json`.
+
+Through v1.31.0 cairn guessed the *smallest* window that could hold what it had
+measured, which meant an unmeasured session was assumed to be 200k. That produced a
+guaranteed false-alarm band: on a 1M session, every reading between 180k and 196k
+looked like a nearly-full 200k one. It was measured live at 192,634 tokens, where
+cairn reported **96%** and `/context` said **19%**. The band is structural rather
+than a tuning error — any firing point for a 200k window is a point a 1M session
+also passes through — so no threshold can serve both, and the tie-break has to come
+from outside.
+
+Since v1.32.0 cairn never guesses downward. Unset, it assumes the widest window it
+knows about and stays quiet; the cost of that being wrong is one missed nudge on a
+genuinely full small window, against an interruption at a fifth of capacity that
+teaches you to ignore the line for good. Measurement still raises the floor — having
+*seen* 482k tokens proves the window is bigger than that — it simply can never lower
+it.
+
+If your window really is 200k, say so and both the threshold and the reported
+percentage become exact:
+
+```bash
+export CAIRN_CONTEXT_WINDOW=200000
+```
+
+`CAIRN_CONTEXT_HINT_TOKENS` still overrides the trigger point outright if you want a
+different bar rather than a different window.
 
 Deliberately not built: 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