@misterhuydo/cairn-mcp 1.37.0 → 1.38.0

package/README.md

@@ -552,6 +552,44 @@ failed on a change that was entirely intended. It now asserts a *ratio*: the pre
 stay under half the payload. The invariant was never a particular length, it was that one
 channel stays a preview while the other carries everything.
 
+**v1.38.0 adds the other half of the question.** Everything above is retrospective.
+`would_be_lost` asks what a fresh session would not *know*, and every example in it is
+something that already happened. So a restored session inherited the whole of what the
+last one learned and nothing of what it was going to do with it — thorough notes, a
+legible thread, and an agent that still opened with "what now?" to a user who had
+answered that an hour earlier.
+
+`cairn_checkpoint` now takes **`next_step`**, carried by exactly the same rules as the
+handoff: the heartbeat copies it forward but never restamps it, it ages against commits,
+and it is delivered in full on restore, directly under the handoff. It asks for the
+*reason* as well as the action, because the action alone already survives in the roadmap
+and the message field — what does not survive is why that action was next rather than the
+alternatives, and an agent that inherits only "run the Windows fixtures" will happily do
+it in the wrong order or redo the deliberation that chose it.
+
+Staleness means something sharper on this half. A stale handoff is still *true*: what was
+learned stays learned, and later commits only mean it may be incomplete. A stale next step
+may be actively *false* — commits landing after "next I will run the fixtures" are quite
+often that step being done, so the warning says **verify before acting on it** rather than
+"may be stale". A restored agent acting confidently on a completed instruction is worse
+than one told nothing.
+
+The 90% gate now demands both halves, and only the missing one. Asking for a handoff that
+is already current invites it to be rewritten, and a rewrite restamps `at` — which is how
+a thorough answer gets replaced by a hurried one at the worst possible moment.
+
+**And when nothing forward is registered anywhere, the gate says so.** If the roadmap has
+no cursor and no open phase, then after the reset there is nothing outside the discarded
+conversation that says what comes next, and the gate suggests registering the phase. This
+is not cairn inferring the plan — that remains the thing it cannot see and must not guess.
+It reports an *observed absence*: the plan points at nothing. Absence is observable,
+content is not, and that distinction is the only reason this arm is allowed to exist. When
+the roadmap cannot be read at all — no index, no sqlite — it stays silent rather than
+claiming a bare plan it never saw, the same honest-absence rule the commit counter uses.
+
+The probe is deliberately not the roadmap renderer: it is two cheap queries, run only when
+the gate is actually crossing, so the every-prompt path opens no database at all.
+
 It needs no rate limit: it self-extinguishes. The moment the handoff is written the
 demand returns null, and it speaks again only if later commits make that answer stale.
 Crossing is remembered in `.cairn/.handoff-gate` and forgotten when usage drops back