@misterhuydo/cairn-mcp 1.40.0 → 1.41.0

package/README.md

@@ -297,18 +297,44 @@ in the next publish. A relative move splices against the *effective* order (what
 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 publishes as a **`priority` integer on each phase** — `1` first, contiguous `1..N`,
+**absent where unset**. A partial list is fine; anything it omits follows in plan order.
+
+A list is the right way to *say* an order and a number is the right way to *publish* one,
+which is why the two halves differ. Three things follow from putting the number on the
+phase:
+
+- **It cannot go stale.** An array beside the plan keeps pointing at work that shipped,
+  got parked or left it. A number on the phase leaves *with* the phase — there is nothing
+  to dangle, which is why `order_advice` has no `stale` state.
+- **cairn owns compaction.** Priority is *sequence*, not identity: nothing resolves
+  against it, so cairn renumbers it freely and there are never gaps, decimals or ties.
+  (Renumbering a phase **number** is forbidden for exactly the opposite reason — the
+  file-to-DB sync matches rows by it.)
+- **Optional is what keeps it honest.** One real plan has 70 live phases and nobody has
+  ranked any of them; presenting file order as priority would assert a considered ranking
+  that does not exist. Both halves say how many are actually prioritised.
+
+`priority` and `number` are never the same field, and the trap is real: stating an order
+today can need `[11, 12, 5, 16]`, where `5` is TC-3 because TC-3 is *phase number* 5. A
+priority of `3` meaning "third" and a phase number of `5` meaning "TC-3" must not share a
+key. Slices carry no priority — a consumer does not sort slices across phases.
+
+The top-level **`order`** array and **`order_source: "authored"`** are still published
+alongside, naming the same sequence, so a consumer can switch its sort before the array
+is removed in a later release.
+
+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.
+- **cairn never publishes an order it worked out itself.** When nothing is stated *no
+  phase carries a `priority`*, 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.
@@ -407,11 +433,12 @@ Four things about it are deliberate:
   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.
+A stated order is never reported as needing attention. There is nothing to report:
+publishing the order as a `priority` on each phase means it leaves with the phase, so it
+cannot point at work that shipped or got parked. 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