@misterhuydo/cairn-mcp 1.30.0 → 1.31.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.