@misterhuydo/cairn-mcp 1.38.0 → 1.40.0

package/README.md

@@ -196,6 +196,11 @@ cairn_roadmap { action: "focus", id: 3 }          → make phase 3 the current f
 cairn_roadmap { action: "set_status", id: 3, status: "done" }  → ship it
 cairn_roadmap { action: "add", parent: 3, text: "..." }        → ad-hoc sub-task under a phase
 cairn_roadmap { action: "deps_add", from: 2, to: 4 }           → phase 2 blocks phase 4
+cairn_roadmap { action: "reorder", order: "1 -> 8 -> 9 -> 5" } → state the priority order
+cairn_roadmap { action: "reorder", move: 8, before: 5 }        → "do phase 8 before phase 5"
+cairn_roadmap { action: "reorder", decline: true }             → "no stated order, deliberately" — and stop asking
+cairn_roadmap { action: "set_status", id: 3, status: "deferred" } → park it: still in the plan, out of the live set
+cairn_roadmap { action: "deferrable" }           → propose which phases look parked, from the markers already in their titles
 cairn_roadmap { action: "publish" }              → (re)write the human-readable ROADMAP.md at the repo root
 ```
 
@@ -218,7 +223,8 @@ invisible:
   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
+  phase `id`s, `ref` (the name that actually identifies a phase — see below), `number`,
+  `label`, `group`, `title`, `status`, `goal`, `blocked_by`, `slices`, the full
   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
@@ -231,10 +237,20 @@ plan **complete** — `done` and `stale` phases stay in `phases` with their real
 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.
+agent at when you are tracing a bug back to where it came from.
+
+**`shipped_phases` is the shipping log** — every phase ever marked done, newest first,
+read from the same `.cairn/roadmap_completed.md` the reader half's *Recently shipped*
+section is generated from, so the two halves of one file cannot disagree about the same
+fact. (They used to: two real projects published `shipped_phases: []` beside a markdown
+list of six and eight shipped phases, and a consumer taking the JSON at its word saw two
+projects that had shipped nothing.) The markdown shows the most recent few; this carries
+all of them. Entries are identity and provenance only — `id`, `ref`, `number`, `title`,
+`shipped`, `commit`, never `detail` — so a long-lived repo's history cannot bloat the
+file. A phase still in the current plan appears in **both** `phases[]` and here: they are
+two indexes of one plan, the tree and the chronology, joined by `id`. Entries logged
+before the log carried ids publish no `id` and no `ref` rather than a guessed one. The
+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:
 
@@ -249,7 +265,163 @@ Three rules the format leaves implicit, each of which has cost a consumer real t
   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.
+  ambiguous with a broken pointer. A `cursor` you cannot find in `phases[]` is normal
+  and not a dangling pointer — look in `slices[]`, or just follow `cursor_path`.
+- **`number` does not identify a phase; `ref` does.** `number` is the phase number
+  authored in the plan, and it is unique only *within a decision group* — one real plan
+  publishes `number: 1` on forty separate rows. Print or say **`ref`**, which is always
+  present and unique in the document: the project's own name for the phase (`TC-4`)
+  where the titles carry one, otherwise a bare number where that identifies, otherwise
+  a group-qualified one (`roadmap-3`), otherwise the row id. `ref` is a *name* and can
+  lengthen when phases are added elsewhere; `id` stays the stable machine key.
+
+### The priority order
+
+`## Phases` in `.cairn/roadmap.md` says what the phases are. It does not say what order
+to work them in, and **renumbering to express that is destructive** — the file-to-DB
+sync matches rows by phase number, so moving "Phase 8" to "Phase 2" reads as "phase 2's
+text changed" and rewires which row is which.
+
+So the order is its own statement. Author it as an `## Order` section, in the numbers
+the phase headers already use:
+
+```markdown
+## Order
+
+1 -> 8 -> 9 -> 5
+```
+
+or let a working session set it — `cairn_roadmap reorder` takes either the whole list or
+a single relative move, so "do phase 8 before phase 5" mid-session lands in the file and
+in the next publish. A relative move splices against the *effective* order (what was
+stated, then the rest in plan order), so phases the stated list omits keep their place
+instead of being silently demoted.
+
+It publishes as **`order`** — phase ids, most important first — with
+**`order_source: "authored"`**. A partial list is fine; anything it omits follows in plan
+order. Two rules hold it honest:
+
+- **It never contradicts `blocked_by`.** If A is blocked by B, B comes first. An order
+  that disagrees is *repaired* rather than refused (publishing is a background side
+  effect and must not fail) — an unmentioned blocker is pulled in, a late one is pulled
+  forward, and everything the deps do not implicate keeps its stated position. The
+  repair is reported in the `reorder` result, never applied silently.
+- **cairn never publishes an order it worked out itself.** When nothing is stated the
+  `order` key is *absent*, so a consumer is free to derive one and label it as derived.
+  A guessed sequence and a stated one are different claims and must not look alike.
+
+`next` follows the stated order too. A plan that publishes a priority the tool then
+advances past is publishing a decoration.
+
+### Deferred: work that is parked, not in progress
+
+A phase is `deferred` when it is **finished, with a tail somebody deliberately parked**.
+Not `open` — nobody is picking it up. Not `done` — the work is real and the plan should
+still show it.
+
+Without that status, one slice titled `S5 Billing (paid gate)` keeps its whole phase in
+the live set forever, and anything that ranks live phases ranks parked work above
+genuinely open work. Measured on a real plan: four of eleven live phases were live
+*solely* because of one slice whose own title said `(later)` or `(paid gate)`, and the
+phase with two genuinely open slices and nothing blocking it sorted **eighth**.
+
+A phase is deferred either because you said so:
+
+```
+cairn_roadmap { action: "set_status", id: 3, status: "deferred" }
+```
+
+or because **every slice it has left is** — that half is *derived*, not stored, on every
+read, from the same rows everything else already loads. Storing it would mean
+re-deriving on each path that can change a slice, and one missed path leaves a phase
+permanently mis-parked. The rule is exact: a phase with at least one deferred slice and
+no slice still open, in progress or blocked is deferred; a phase whose slices are *all*
+done keeps the status it was given, because whether it is finished is a judgement about
+work outside its slices and cairn does not make it for you.
+
+What parking does, and does not do:
+
+- It **leaves the live set**: out of `next`, out of the published order, out of the
+  `M/N done` denominator (with the exclusion stated on the line, never quiet), and
+  published as `status: "deferred"`.
+- It **stays in the plan**: shown in the tree as `[>]`, published in `phases[]`, *not*
+  pruned from `roadmap.md` and *not* logged to `roadmap_completed.md`. Parked is not
+  shipped. `set_status <id> open` picks it back up.
+- The `## Order` section **still remembers it**, even though it drops out of the
+  published `order` — unparking should not cost you your place in the queue.
+- A blocker that is parked still blocks: `next` refuses to advance past it and says
+  which phase did it. What changes is that the order stops dragging parked work forward.
+
+Plans said this in prose long before there was a status for it. `deferrable` reads those
+markers back:
+
+```
+cairn_roadmap { action: "deferrable" }
+```
+
+It proposes — it never writes. Candidates are titles carrying a parenthetical park
+marker (`(later)`, `(paid gate)`, `(design-later)`, `(on hold)`, …), gated on the
+parenthetical rather than the bare word, because "do this later" appears in half the
+phase titles ever written. Each candidate comes with the consequence that makes it worth
+confirming: which phases would leave the live set, and whether that is because of the
+marker itself or because of what would be left under them. You confirm the ones you
+mean, one `set_status` each.
+
+### Being asked for the order
+
+cairn shipped `order` and `reorder` — documented, with relative moves and cycle repair —
+and two days later `order` was still unset in every project that had one. Not because
+anyone disliked it: because nothing ever mentioned it. **A capability nobody is prompted
+to use is indistinguishable, from the outside, from one that does not exist.**
+
+So plan-*changing* actions — a `sync` that inserted or retired phases, `set_status` to
+`done` or `deferred`, and `reorder` itself — may carry an advisory field:
+
+```json
+"order_advice": {
+  "state": "never_set",
+  "live_phases": 11,
+  "unordered": ["phase-25", "phase-60", "phase-101"],
+  "why": "11 live phases and no stated order, so `next` follows plan number order — the sequence they were written in, which is not a priority; 3 of them are waiting on another phase",
+  "ask": true
+}
+```
+
+Four things about it are deliberate:
+
+- **It never fires on `tree`, `status` or `next`.** The end-of-turn hook calls those
+  after every assistant turn, and a nudge there is noise on a loop — which is precisely
+  how a cursor sat on a finished phase for weeks, on screen the whole time, in a line
+  everybody had stopped reading.
+- **It is advisory.** Never a refusal, never a blocked action, and cairn never writes an
+  order itself. cairn is an MCP server and cannot ask a question; the agent can, and it
+  has the code in front of it, so it brings you a recommendation with reasons rather
+  than a bare "what order?". An order the agent invented would be published as
+  `order_source: "authored"` and shown to you as your own decision.
+- **`why` is generated from the plan, and it is the point.** "No order is set" produces a
+  vague question and a vague answer.
+- **It can go quiet.** "No order has been set" and "we decided not to have one" are
+  different facts. `cairn_roadmap reorder decline: true` records the second in the
+  `## Order` section, in a line you can read and delete, and `ask` goes false. It is not
+  a lock: any later `reorder` replaces it with no ceremony. The decline records the
+  phases live at the time, so a phase *added* later revives the question — and even then
+  the advisory says the decline stands and asks only where the newcomer goes.
+
+A stated order is only reported as `stale` when it **points at something that is not
+there** — a phase that shipped, got parked, or left the plan. Phases it simply does not
+mention are reported in `unordered` and nothing more: *"phase 8 first, sort the rest out
+when we get there"* is a complete answer, and an advisory that treats a partial order as
+unfinished makes stating one a chore nobody completes.
+
+`cursor_advice` is the same shape for the other thing nothing ever said out loud — a
+cursor left on finished (`on_done_phase`), parked (`on_parked_phase`) or removed
+(`dangling`) work, or unset while live phases remain. The cursor is cairn's own state,
+so no consumer can warn about it on cairn's behalf.
+
+Both ride on the **tool result**, not in the published `ROADMAP.md`. A file is read
+continuously by panels and dashboards; an advisory in it would be a permanent nag on a
+screen that cannot act on it. It goes to the one reader who can put the question to a
+person.
 
 The first line is the marker that says who generated the file and when
 (`<!-- slot:roadmap format=roadmap/1 provider=cairn generated=… -->`). cairn declares