Agent UX: pm next ready queue is documented as ranked but is not priority-ordered (no rank/score exposed) #513

Summary

pm next --help describes the output as "the ranked ready and blocked queues" and the recommended item is correctly chosen highest-priority-first (reason: "priority p0 (highest)"). However, the ready[] array in pm next --json is not ordered by priority, matches no other documented field (creation, updated_at, order), and carries no rank/score field — so a JSON-consuming agent cannot trust or reconstruct the ranking.

Repro (pm 2026.7.11)

pm init --yes
pm create task    "OAuth token refresh" --priority 1
pm create bug     "Login fails on Safari" --priority 0
pm create feature "Realtime collaboration" --priority 2
pm create task    "t-a" --priority 3
pm next --json

Observed, stable across repeated calls:

recommended.priority = 0   ("Login fails on Safari")   ✅ correct
ready[] priorities   = [1, 3, 2]                        ❌ not ranked

[1, 3, 2] matches neither priority order (1,2,3), creation order, nor updated_at order (1,2,3). Each ready item has order: null, reasons: null, and no score/rank key.

Why it matters (project management = context management)

• The docs promise a ranked queue; agents reasonably treat ready[0] as the next-best pick.
• This compounds with Agent UX: add atomic select-and-claim (pm next --claim) to close the recommend→claim TOCTOU window for multi-agent fleets #509: in a multi-agent fleet, once the recommended item is claimed, the next agent falls back to ready[0] — which here is p1 over the still-unclaimed... actually p2/p3, so ordering is defensible, but the point is ready[1]=p3 sits above ready[2]=p2, so straightforward iteration picks a lower-priority item before a higher-priority one.
• Agents must re-sort client-side (extra tokens + logic) to recover the intended order, defeating the "answers what to work on in one read" goal.

Suggested fix (either)

1. Sort ready[] by the same ranking used to choose recommended (priority-first, then existing tie-breakers), so ready is a true continuation of the recommendation; or
2. Expose the composite rank/score (and reasons) on each ready item so consumers can sort deterministically without guessing.

Option 1 is the least-surprise fix and makes ready[0] the correct answer after the recommended item is claimed.

Filed while dogfooding the pm fleet. Happy to test a patch.