Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(queue): the queue orders itself by unblocks and effort [N22,B13]
Corey Olsonbb1962fabb38
diff --git a/docs/api.md b/docs/api.mdindex 7993d6d6..2d8d458b 100644--- a/docs/api.md+++ b/docs/api.md@@ -100,6 +100,9 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec| `milestone add` | `version:number`, `milestone:object` || `milestone items` | `version:number`, `milestone:object` || `milestone order` | `version:number`, `milestone:object` |+| `milestone pin` | `version:number`, `milestone:object` |+| `milestone sink` | `version:number`, `milestone:object` |+| `milestone lift` | `version:number`, `milestone:object` || `milestone move` | `version:number`, `milestone:object` || `milestone edit` | `version:number`, `milestone:object` || `milestone remove` | `version:number`, `milestone:object` |@@ -613,6 +616,8 @@ When the runner's own resource pool refuses the run's setup, the run fails at onAgents and the coordinator can set explicit item ranks with `milestone order <name> <ids>` (comma-separated ids from that milestone). It replaces that milestone’s `order` list in board metadata; other items stay unranked. `next` compares milestone, explicit rank, then its existing route/recent-file/age tie-breaks. A never-ranked board keeps its existing order. Removing an item drops its rank; adding it again leaves it unranked. This does not change newcomer help or person flows.+`queue` and `next` order each milestone's unranked items by themselves (#1017). An item's unblock count is the unfinished items that wait on it, directly or through others; its effort is its route (light 1, mid 2, strong 3); its score is (unblocks + 1) / effort. Ready items that unblock others alternate with quick wins (light or mid items that unblock nothing) while both last, the rest of the ready work follows by score, and each route with ready work gets an item near the top. Blocked items follow in the order their blockers clear, then held items. `next` takes its own route first within that order. The coordinator overrides the order with `milestone pin <name> <ids> --reason "<why>"` (above the computed order, after any `milestone order` ranks) or `milestone sink <name> <ids> --reason "<why>"` (below it), and `milestone lift <name> <ids>` removes either; an override stays through every re-rank until lifted. Pins extend the milestone's `order`, sinks are its `sunk` list, and each reason is in its `reasons` map by item id. Each `queue` item carries `unblocks:number`, `effort:number` and `why:string`, and text `queue` prints them under the item.+`resume` on the coordinator seat includes `rigor: {undrafted: [...]}`, naming each repeated cause that has no live or approved proved draft. Each entry retains the ordinary Rigor cause key, item evidence and commits. The text resume names the proof-bearing `pullboard rigor draft` command. Declined repeats stay quiet until a new item repeats them. `needsYou` may contain an individual `kind: "rigor-draft"` call with `cause`, `evidence`, `proof`, a qualified spec or doctrine `target`, and `what: "Approve or Decline"`. An ordinary draft remains in the existing aggregate count; a Rigor draft is not counted twice. These fields add no person permission: the existing person-only approval and decline channels still apply.Automatic evidence-only calls additionally carry `unproved: true`, `proof: null`, `materialized` and `collision`. Before materialization, `what` asks the coordinator to run `spec apply`; the browser labels the advice unproved and does not open a nonexistent file row. After materialization, the person uses the existing exact-row approval/decline path. A pending automatic proposal also satisfies the `undrafted` obligation. An unanswered automatic proposal appears once in each digest after the board's landing cadence (one day by default). No automatic proposal establishes a proved remedy or grants person authority.diff --git a/docs/formats.md b/docs/formats.mdindex 30e0ae3f..e40e928a 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -525,6 +525,8 @@ A person waiver records its identity, named test, expiry, reason and person chanEngine 34 adds the agent/coordinator `orderMilestoneItems` move, carrying a milestone name and its ordered subset of item ids. Earlier engines refuse it before changing the board or replay cursor. Ranked item ids stay with their milestone in its `order` metadata; old entries without it keep their prior queue order. Recorded next/reserve moves below engine 34 retain their original ordering even when later metadata contains ranks. The stable minimum is `MILESTONE_RANK_ENGINE` (34); engine slots 25 through 33 belong to their separately allocated train items.+`WORK_ORDER_ENGINE` lets the coordinator's `orderMilestoneItems` carry `place` (`pin`, `sink` or `lift`) and, for a pin or sink, a `reason`. A pin appends its ids to the milestone's `order`, a sink to its `sunk` list, and both record the reason under each id in its `reasons` map; a lift removes the ids from all three. Earlier engines refuse a move with `place`. From this engine on, next and reserve moves order unranked items by the computed queue order (unblock count, effort, readiness), sunk items last; recorded moves below it keep their milestone, rank, route and age order.+Engine 43 (`RIGOR_NOTICE_ENGINE`) posts one coordinator shout and one typed `rigor-notice` receipt when a reject, reopen or person never-again fact makes a cause repeat. Both are part of that move’s transaction. Recorded engines through 42 retain their original event streams. A person’s exact row-decision receipt for a typed Rigor source silences that repeat until a new item repeats it; later commits on an already known item do not override the decline.A proved Rigor draft carries `source: rigor:<percent-encoded JSON>` with `version: 1`, its `key`, `evidence` (`items`, `occurrences`, `neverAgain`) and `proof` (`check`, `red`, `green`). The proof contains actual full commits, executed exit statuses and problem counts. The existing spec and doctrine row grammar reads this field; prose mentioning Rigor is not a typed source. The person uses ordinary Approve or Decline, and the coordinator applies the approved row without a new build item.diff --git a/src/board.js b/src/board.jsindex 79f49d64..eb5787bd 100644--- a/src/board.js+++ b/src/board.js@@ -211,6 +211,10 @@ import {} from './rigor-notices.js';import { RIGOR_NOTICE_ENGINE } from './rigor-source.js';import { RIGOR_AUTO_ENGINE } from './rigor-auto-engine.js';+import {+ milestoneRanks,+ workOrderCompare,+} from './work-order.js';import {deriveRigorCause,recordAutomaticRigorDrafts,@@ -1909,28 +1913,16 @@ function postRigorNotices(board, trigger) {}-/** Explicit item ranks belong to the same first unfinished milestone as its priority [N2,B13]. */-function milestoneRanks(board, priority) {- if ((board.executionEngineVersion ?? ENGINE_VERSION) < MILESTONE_RANK_ENGINE) return () => 0;- const ranks = new Map();- for (const [index, milestone] of milestones(board).entries()) {- for (const [rank, id] of (milestone.order ?? []).entries()) {- if (milestone.items.includes(id) && priority({ item_id: id }) === index && !ranks.has(id)) ranks.set(id, rank);- }- }- return entry => ranks.get(entry.item_id) ?? Number.MAX_SAFE_INTEGER;-}--/** Make the shared build-queue comparator once: milestone, explicit rank, route, recent files, then oldest. */-export function buildOrder(board, { warm = [], agentId, readiness = barReadyForOrder } = {}) {- const milestonePriority = milestonePriorities(board);+/** Make the shared build-queue comparator once: milestone, explicit rank, then the self-ordered queue (#1017; older engines: route, recent files, oldest). */+export function buildOrder(board, { warm = [], agentId, readiness = barReadyForOrder, tierFirst = false, priority } = {}) {+ const milestonePriority = priority ?? milestonePriorities(board);const rank = milestoneRanks(board, milestonePriority);const recent = new Set(warm);const shared = (entry) => itemFiles(entry).filter((path) => recent.has(path)).length;- const fallback = (first, second) => milestonePriority(first) - milestonePriority(second)+ const fallback = workOrderCompare(board, { priority: milestonePriority, rank, shared, tierFirst }) ?? ((first, second) => milestonePriority(first) - milestonePriority(second)|| rank(first) - rank(second)|| ROUTES.indexOf(second.item_route) - ROUTES.indexOf(first.item_route)- || shared(second) - shared(first) || first.item_id - second.item_id;+ || shared(second) - shared(first) || first.item_id - second.item_id);return lineOrderEnabled(board) ? lineBuildOrder({ agentId, release: milestonePriority, rank, items: listItems(board, { all: true }), ready: item => readiness(board, item), fallback }) : fallback;}@@ -2003,7 +1995,7 @@ export function nextFor(board, { agentId, lane, verify = false, policy = 'any',const hold = laneHold(board, name);if (hold) { selectedLanes.delete(name); reasons.push(`${hold.hold_by} holds the ${name} lane: ${hold.hold_reason}`); }}- const compare = buildOrder(board, { warm, agentId });+ const compare = buildOrder(board, { warm, agentId, tierFirst: true });const inFlight = listItems(board, { all: true });const recent = new Set(warm);const mainRed = new Set(priority);diff --git a/src/commands/milestone.js b/src/commands/milestone.jsindex 54a1a65c..7151c24a 100644--- a/src/commands/milestone.js+++ b/src/commands/milestone.js@@ -40,6 +40,13 @@ export async function run(io, { first, second, rest, values }) {}name = second;await ordered(ctx, board, 'orderMilestoneItems', [name, { agentId: me.id, items: ids(rest[0]) }]);+ } else if (['pin', 'sink', 'lift'].includes(first)) {+ if (!second || rest.length !== 1 || !rest[0].trim() || ['items', 'note', 'before', 'name', 'add', 'remove', 'target'].some((key) => values[key] !== undefined)+ || (first === 'lift') !== (values.reason === undefined)) {+ throw new Refused('USAGE', first === 'lift' ? 'pullboard milestone lift <name> <ids>' : `pullboard milestone ${first} <name> <ids> --reason "<why>"`);+ }+ name = second;+ await ordered(ctx, board, 'orderMilestoneItems', [name, { agentId: me.id, items: ids(rest[0]), place: first, ...(first === 'lift' ? {} : { reason: values.reason }) }]);} else if (first === 'move') {if (!second || rest.length || !values.before || values.items !== undefined || values.note !== undefined || values.name !== undefined || values.add !== undefined || values.remove !== undefined) {throw new Refused('USAGE', 'pullboard milestone move <name> --before <other>');@@ -73,7 +80,7 @@ export async function run(io, { first, second, rest, values }) {await ordered(ctx, board, 'removeMilestone', [name, { agentId: me.id }]);entry = { name };} else {- throw new Refused('USAGE', 'use pullboard milestone add, items, order, move, edit, ship or remove');+ throw new Refused('USAGE', 'use pullboard milestone add, items, order, pin, sink, lift, move, edit, ship or remove');}entry ??= store.milestones(board).find((value) => value.name === name);io.result?.({ milestone: entry });diff --git a/src/help.js b/src/help.jsindex 0bf71342..16d740bc 100644--- a/src/help.js+++ b/src/help.js@@ -89,12 +89,15 @@ Work$PULLBOARD_ATTEMPT, $PULLBOARD_TIER); green work is submitted, red escalated[--agent-light "..."] [--agent-mid "..."] [--agent-strong "..."] a command per tierpullboard list [lane] [--all] [--route light|mid|strong] open and active items; --all adds closed ones- pullboard queue the work queue in pull order: releases, then route, lane, holder and waits+ pullboard queue the work queue in pull order: releases, then route, lane, holder, waits,+ and each item's unblock count, effort and why it sits therepullboard roadmap ordered milestones, N/M landed, targets, and each item as landed,accepted or its statuspullboard milestone add <name> [--note ...] [--items 1,2,3] create a milestone and optionally add itemspullboard milestone items <name> --add|--remove ids append or remove item referencespullboard milestone order <name> <ids> rank these items within their milestone (agents)+ pullboard milestone pin|sink <name> <ids> --reason "<why>" hold items above or below the queue's own order+ pullboard milestone lift <name> <ids> return pinned or sunk items to the queue's orderpullboard milestone move <name> --before <other> reorder a milestonepullboard milestone edit <name> [--name <new>] [--note <text>] [--target <date and time>|none]rename, update a note, or set the target a milestone ships by@@ -310,6 +313,9 @@ const HELP_EXAMPLES = {'lane add': 'pullboard lane add web --owns apps/web/', lane: 'pullboard lane add web --owns apps/web/',queue: 'pullboard queue', roadmap: 'pullboard roadmap', rigor: 'pullboard rigor', 'rigor quality': 'pullboard rigor quality --rule silent-catch', 'rigor draft': 'pullboard rigor draft "refusal:MERGE_LOST" "Merges keep every hunk" --check "node bin/checks/merges.js" --red 0123456 --green 89abcde', milestone: 'pullboard milestone add "0.7.0" --items 12,13','milestone order': 'pullboard milestone order "0.7.0" 13,12',+ 'milestone pin': 'pullboard milestone pin "0.7.0" 13 --reason "the release notes need it first"',+ 'milestone sink': 'pullboard milestone sink "0.7.0" 12 --reason "waits on a design answer"',+ 'milestone lift': 'pullboard milestone lift "0.7.0" 12,13',runner: 'pullboard runner add studio --slots 2 --browser 1', 'runner add': 'pullboard runner add studio --slots 2 --browser 1',edit: 'pullboard edit 12 --brief "Add the upload page"', release: 'pullboard release 12',land: 'pullboard land --max 4',diff --git a/src/json.js b/src/json.jsindex a2ca0c7a..7a3c1c8a 100644--- a/src/json.js+++ b/src/json.js@@ -36,6 +36,9 @@ export const JSON_SHAPES = {'milestone add': shape({ milestone: 'object' }),'milestone items': shape({ milestone: 'object' }),'milestone order': shape({ milestone: 'object' }),+ 'milestone pin': shape({ milestone: 'object' }),+ 'milestone sink': shape({ milestone: 'object' }),+ 'milestone lift': shape({ milestone: 'object' }),'milestone move': shape({ milestone: 'object' }),'milestone edit': shape({ milestone: 'object' }),'milestone remove': shape({ milestone: 'object' }),diff --git a/src/milestones.js b/src/milestones.jsindex 45939e96..8c9f8e15 100644--- a/src/milestones.js+++ b/src/milestones.js@@ -16,6 +16,7 @@ import {} from './machine.js';export { WITHDRAW_MILESTONE_ENGINE };import { Refused } from './refused.js';+import { WORK_ORDER_ENGINE } from './work-order-engine.js';import {atomic,itemById,@@ -227,15 +228,22 @@ export function editMilestoneItems(board, name, { agentId, add = [], remove = []entries[index] = { ...current, items: nextItems,...((board.executionEngineVersion ?? ENGINE_VERSION) >= MILESTONE_RANK_ENGINE && current.order? { order: current.order.filter(id => nextItems.includes(id)) } : {}) };+ if (engineOf(board) >= WORK_ORDER_ENGINE && (current.sunk || current.reasons)) {+ entries[index] = withOverrides(entries[index], entries[index].order ?? [], (current.sunk ?? []).filter(id => nextItems.includes(id)));+ }saveMilestones(board, entries);logEvent(board, agentId, 'milestone_items', null, { name, add: additions, remove: removals });return nextItems;});}-/** Replace this milestone's explicit ranks; omitted items retain the ordinary queue order [N2,B13]. */-export function orderMilestoneItems(board, name, { agentId, items }) {+/**+ * Replace this milestone's explicit ranks; omitted items retain the ordinary queue order [N2,B13]. With `place`,+ * the coordinator pins, sinks or lifts items instead (#1017).+ */+export function orderMilestoneItems(board, name, { agentId, items, place, reason }) {if ((board.executionEngineVersion ?? ENGINE_VERSION) < MILESTONE_RANK_ENGINE) throw new Refused('ENGINE_VERSION', 'milestone order requires engine 34; upgrade Pullboard before ranking work');+ if (place !== undefined) return overrideMilestoneItems(board, name, { agentId, items, place, reason });if (agentId !== COORDINATOR && (agentId === PERSON || !board.db.prepare('SELECT 1 FROM agent WHERE agent_id = ?').get(agentId))) {throw new Refused('NO_AGENT', 'milestone order is an agent or coordinator move; join an agent worktree or ask the coordinator');}@@ -247,12 +255,55 @@ export function orderMilestoneItems(board, name, { agentId, items }) {if (index < 0) throw new Refused('NO_MILESTONE', `no milestone named ${name}; list them with pullboard roadmap`);if (order.some(id => !entries[index].items.includes(id))) throw new Refused('MILESTONE_ITEMS', 'rank only items in this milestone; read pullboard roadmap and retry');entries[index] = { ...entries[index], order };+ if (engineOf(board) >= WORK_ORDER_ENGINE) entries[index] = withOverrides(entries[index], order, (entries[index].sunk ?? []).filter(id => !order.includes(id)));saveMilestones(board, entries);logEvent(board, agentId, 'milestone_order', null, { name, items: order });return order;});}+/** A milestone with these pins and sinks, keeping reasons only for items still pinned or sunk. */+function withOverrides(entry, order, sunk) {+ const kept = new Set([...order, ...sunk].map(String));+ const reasons = Object.fromEntries(Object.entries(entry.reasons ?? {}).filter(([id]) => kept.has(id)));+ const { sunk: _sunk, reasons: _reasons, ...rest } = entry;+ return { ...rest, order, ...(sunk.length ? { sunk } : {}), ...(Object.keys(reasons).length ? { reasons } : {}) };+}++/**+ * The coordinator pins items above the queue's computed order, sinks them below it, or lifts either, each pin+ * and sink with its reason (#1017) [N22,B13]. An override stays through every re-rank until it is lifted.+ *+ * @param {any} board+ * @param {string} name+ * @param {{ agentId: string, items: unknown[], place: unknown, reason?: unknown }} change+ * @returns {{ order: (number | string)[], sunk: (number | string)[] }}+ */+function overrideMilestoneItems(board, name, { agentId, items, place, reason }) {+ if (engineOf(board) < WORK_ORDER_ENGINE) throw new Refused('ENGINE_VERSION', 'pinning and sinking queue items needs a newer engine; upgrade Pullboard before overriding the queue');+ requireCoordinator(agentId);+ if (!['pin', 'sink', 'lift'].includes(place)) throw new Refused('MILESTONE_PLACE', 'an override is pin, sink or lift: pullboard milestone pin <name> <ids> --reason "<why>"');+ const ids = normalizeMilestoneItems(items);+ if (!ids.length) throw new Refused('MILESTONE_ITEMS', `name the item ids: pullboard milestone ${place} <name> 1,2`);+ const text = typeof reason === 'string' ? reason.trim() : '';+ if (place !== 'lift' && !text) throw new Refused('MILESTONE_REASON', `say why: pullboard milestone ${place} ${name} ${ids.join(',')} --reason "<why>"`);+ return atomic(board, () => {+ const entries = milestones(board);+ const index = entries.findIndex(entry => entry.name === name);+ if (index < 0) throw new Refused('NO_MILESTONE', `no milestone named ${name}; list them with pullboard roadmap`);+ const current = entries[index];+ if (ids.some(id => !current.items.includes(id))) throw new Refused('MILESTONE_ITEMS', 'override only items in this milestone; read pullboard roadmap and retry');+ const order = [...(current.order ?? []).filter(id => !ids.includes(id)), ...(place === 'pin' ? ids : [])];+ const sunk = [...(current.sunk ?? []).filter(id => !ids.includes(id)), ...(place === 'sink' ? ids : [])];+ const reasons = { ...Object.fromEntries(Object.entries(current.reasons ?? {}).filter(([id]) => !ids.map(String).includes(id))),+ ...(place === 'lift' ? {} : Object.fromEntries(ids.map(id => [String(id), text]))) };+ entries[index] = withOverrides({ ...current, reasons }, order, sunk);+ saveMilestones(board, entries);+ logEvent(board, agentId, 'milestone_order', null, { name, items: ids, place, ...(text && place !== 'lift' ? { reason: text } : {}) });+ return { order, sunk };+ });+}+/** Move a milestone before another while retaining all item and note data. */export function moveMilestone(board, name, { agentId, before }) {requireCoordinator(agentId);diff --git a/src/moves/orderMilestoneItems.js b/src/moves/orderMilestoneItems.jsindex a53df9d4..382d0dd8 100644--- a/src/moves/orderMilestoneItems.js+++ b/src/moves/orderMilestoneItems.js@@ -3,9 +3,11 @@ import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';import { MILESTONE_RANK_ENGINE } from '../engine-metadata.js';import { LANDING_LEASE_ENGINE } from '../landing-lease-engine.js';import { BOARD_SENTINEL_ENGINE } from '../sentinel-engine.js';+import { WORK_ORDER_ENGINE } from '../work-order-engine.js';/** Preserve this operation's historical first-matching engine conditions [H16]. */function minimumEngine(args, board, at) {+ if (args[1]?.place !== undefined) return WORK_ORDER_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return RIGOR_AUTO_ENGINE;if (args[0]?.landingFence !== undefined) return LANDING_LEASE_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return BOARD_SENTINEL_ENGINE;@@ -18,8 +20,11 @@ function actor(move) { return move.args[1]?.agentId ?? null; }export default Object.freeze({ operation: "orderMilestoneItems", order: 32, engine: MILESTONE_RANK_ENGINE,itemIdFirstArgument: false, minimumEngine, actor,nextSteps: Object.freeze({+ "COORDINATOR_ONLY": "ask the coordinator to do it: pullboard shout coordinator \"<what you need>\"","ENGINE_VERSION": "upgrade Pullboard: npm install -g pullboard@latest","MILESTONE_ITEMS": "list item ids once each: pullboard milestone add <name> --items 1,2",+ "MILESTONE_PLACE": "pin, sink or lift: pullboard milestone pin <name> <ids> --reason \"<why>\"",+ "MILESTONE_REASON": "say why the item moves: pullboard milestone sink <name> <ids> --reason \"<why>\"","NO_AGENT": "create and join a lane worktree: pullboard worktree <lane> --model \"<model name>\"","NO_MILESTONE": "name a milestone from pullboard roadmap"}) });diff --git a/src/queue.js b/src/queue.jsindex 3da07237..c2e1ab34 100644--- a/src/queue.js+++ b/src/queue.js@@ -3,11 +3,16 @@* breakpoint with its landed count, then its pullable items in the order next serves them, each with* its route, lane, status, holder and what it waits on; a closing line names the item each route would* get from next now. The order is the board's own buildOrder, never a second copy, so the queue and- * next cannot disagree. It is for agents and coordinators; the person reads the Roadmap instead.+ * next cannot disagree. Each item also shows its unblock count, effort and why it sits where it does (#1017).+ * It is for agents and coordinators; the person reads the Roadmap instead.*/import { itemAuthorProblem } from './item-authors.js';import { Refused } from './refused.js';import { itemFileCollisions } from './item-files.js';+import {+ milestoneRanks,+ queueReasons,+} from './work-order.js';import {buildOrder,canTake,@@ -54,20 +59,22 @@ function waitsOf(board, item, inFlight) {* no release after them, and the first item each route would pull now.** @param {any} board- * @returns {{ releases: { name: string, landed: number, total: number, items: any[] }[], unreleased: any[], first: Record<string, number | null> }}+ * @returns {{ releases: { name: string, landed: number, total: number, items: any[] }[], unreleased: any[], first: Record<string, number | null> }} each item with its unblocks, effort and why*/export function workQueue(board, reviewer = null) {const now = board.clock.now().getTime();const release = milestonePriorities(board);const planned = roadmap(board, (reference) => ({ id: reference, title: reference, status: 'unavailable' }));- const items = listItems(board).filter(item => !reviewer || item.item_status !== 'submitted' || !itemAuthorProblem(board, item, reviewer)).sort(buildOrder(board));+ const items = listItems(board).filter(item => !reviewer || item.item_status !== 'submitted' || !itemAuthorProblem(board, item, reviewer)).sort(buildOrder(board, { priority: release }));const inFlight = listItems(board, { all: true });+ const reasons = queueReasons(board, { priority: release, rank: milestoneRanks(board, release) });const entry = (item) => ({ id: item.item_id, title: item.item_title, route: item.item_route, lane: item.item_lane,- status: item.item_status, holder: holderOf(item, now), waits: waitsOf(board, item, inFlight) });+ status: item.item_status, holder: holderOf(item, now), waits: waitsOf(board, item, inFlight), ...reasons(item) });const releases = planned.map((milestone, index) => ({ name: milestone.name, landed: milestone.landed, total: milestone.total, shipped: Boolean(milestone.shipped),items: items.filter((item) => release(item) === index).map(entry) })).filter((milestone) => !milestone.shipped || milestone.items.length);const unreleased = items.filter((item) => release(item) >= planned.length).map(entry);- const pullable = items.filter((item) => item.item_status === 'open' && !waitsOf(board, item, inFlight).length);+ // next takes its own route first (B13), so each route's first item comes from that same order.+ const pullable = items.filter((item) => item.item_status === 'open' && !waitsOf(board, item, inFlight).length).sort(buildOrder(board, { tierFirst: true, priority: release }));const first = Object.fromEntries([...ROUTES].reverse().map((route) => [route, pullable.find((item) => canTake(route, item.item_route))?.item_id ?? null]));return { releases: releases.map(({ shipped, ...milestone }) => milestone), unreleased, first };}@@ -83,6 +90,7 @@ export function sayQueue(io, queue) {const line = (item) => {const who = item.holder ? ` · ${item.holder}` : '';io.say(` ${++rank}. #${item.id} ${item.route} ${item.lane} ${item.status}${who}: ${item.title}`);+ io.say(` unblocks ${item.unblocks} · effort ${item.effort} · ${item.why}`);if (item.waits.length) io.say(` waits on ${item.waits.join('; ')}`);};for (const release of queue.releases) {diff --git a/src/templates.js b/src/templates.jsindex 9c89cbf6..6bfbe61d 100644--- a/src/templates.js+++ b/src/templates.js@@ -140,7 +140,7 @@ When a reject names a structured cause, add \`--cause <key>\` (\`test:<file>::<t6. A reject reopens the item. Fix it, commit, claim, submit again; the same head is refused. If you cannot get an item green, do not force it: \`pullboard escalate <id> --note "what you tried and how it failed"\` hands it one tier up.7. Your lane is done when its items are verified, not when they are submitted. After your last submit, keep running \`pullboard next --wait 9\`: a rejected item comes back to your lane.-The coordinator merges verified items into the main line; builders never merge. When a release ships, the coordinator runs \`pullboard milestone ship <name>\`: it records main's commit and moves the items that have not landed into the next milestone. \`pullboard health\` lists every stuck item: a lapsed claim, a review nobody took, accepted work that never landed, an old hold, an unanswered decision. Each line says why, since when, the next step and who takes it; run it at the start of a session and take the steps that name you.+The coordinator merges verified items into the main line; builders never merge. When a release ships, the coordinator runs \`pullboard milestone ship <name>\`: it records main's commit and moves the items that have not landed into the next milestone. The queue orders itself by what each item unblocks and what it costs; the coordinator holds an item above that order with \`pullboard milestone pin <name> <ids> --reason "<why>"\`, below it with \`pullboard milestone sink <name> <ids> --reason "<why>"\`, and returns it with \`pullboard milestone lift <name> <ids>\`. \`pullboard health\` lists every stuck item: a lapsed claim, a review nobody took, accepted work that never landed, an old hold, an unanswered decision. Each line says why, since when, the next step and who takes it; run it at the start of a session and take the steps that name you.For recurring checks, \`pullboard sentinels\` lists this board's watches, their approvals and their latest results. Propose one with \`pullboard sentinel propose <name> --check "<command>" --every hourly --owner coordinator\`; a proposal does not run until the person approves its exact command, directory and schedule. Only the person runs \`pullboard sentinel approve <name>\` or \`pullboard sentinel decline <name> --reason "<why>"\` from their own terminal or Pullboard View. Agents never approve their own proposals; send the decision to the coordinator.diff --git a/src/work-order-engine.js b/src/work-order-engine.jsnew file mode 100644index 00000000..7a3bd448--- /dev/null+++ b/src/work-order-engine.js@@ -0,0 +1,3 @@+import { unassignedEngine } from './engine-next.js';+/** The queue orders itself, and coordinator pins and sinks carry reasons, from this replay engine on [N22,B13,H16]. */+export const WORK_ORDER_ENGINE = unassignedEngine();diff --git a/src/work-order.js b/src/work-order.jsnew file mode 100644index 00000000..0ee5882e--- /dev/null+++ b/src/work-order.js@@ -0,0 +1,214 @@+/**+ * The queue orders itself (#1017) [N22,B13]. Within each release, an item's unblock count (unfinished items that+ * wait on it, directly or through others) and effort (its route: light 1, mid 2, strong 3) give a score of+ * (unblocks + 1) / effort. Ready items that unblock others alternate with quick wins (light or mid, unblocking+ * nothing) at the top; the rest of the ready work follows by score so effort levels stay mixed; every route with+ * ready work gets an item near the top; blocked items follow in the order their blockers clear, and held items+ * last. The coordinator's pins sit above that order and its sinks below it, each with its reason, until lifted.+ *+ * Pure reads over the board, so pullboard queue, next and health share one order. Recorded moves below+ * WORK_ORDER_ENGINE keep their old milestone, rank, route and age order.+ */+import {+ ENGINE_VERSION,+ MILESTONE_RANK_ENGINE,+} from './machine.js';+import { WORK_ORDER_ENGINE } from './work-order-engine.js';+import { milestones } from './board-read-auxiliary.js';+import { listItems } from './board-query.js';+import { ROUTES } from './route-escalation.js';++/** Effort per route: what one item of that route costs to build. */+export const EFFORT = Object.freeze({ light: 1, mid: 2, strong: 3 });++/** Explicit item ranks belong to the same first unfinished milestone as its priority [N2,B13]. */+export function milestoneRanks(board, priority) {+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < MILESTONE_RANK_ENGINE) return () => 0;+ const ranks = new Map();+ for (const [index, milestone] of milestones(board).entries()) {+ for (const [rank, id] of (milestone.order ?? []).entries()) {+ if (milestone.items.includes(id) && priority({ item_id: id }) === index && !ranks.has(id)) ranks.set(id, rank);+ }+ }+ return entry => ranks.get(entry.item_id) ?? Number.MAX_SAFE_INTEGER;+}++/** True when this board's moves run at or above the self-ordering engine. */+export function workOrderActive(board) {+ return (board.executionEngineVersion ?? ENGINE_VERSION) >= WORK_ORDER_ENGINE;+}++/** The item numbers an item waits on, as recorded. */+function afterIds(item) {+ return item.item_after ? item.item_after.split(',').map(Number) : [];+}++/**+ * The coordinator's overrides for each item in the first unfinished milestone that lists it: its pin reason or+ * its sink reason. A pin with no reason is an older milestone order.+ *+ * @param {any} board+ * @param {(entry: any) => number} priority+ * @returns {{ sunk: Set<number>, reasons: Map<number, string> }}+ */+export function milestoneOverrides(board, priority) {+ const sunk = new Set();+ const reasons = new Map();+ for (const [index, milestone] of milestones(board).entries()) {+ for (const id of milestone.sunk ?? []) if (priority({ item_id: id }) === index) sunk.add(id);+ for (const [id, reason] of Object.entries(milestone.reasons ?? {})) if (priority({ item_id: Number(id) }) === index && !reasons.has(Number(id))) reasons.set(Number(id), reason);+ }+ return { sunk, reasons };+}++/**+ * Each unfinished item's unblock count: the unfinished items that wait on it, directly or through others.+ *+ * @param {any[]} unfinished+ * @returns {Map<number, number>}+ */+export function unblockCounts(unfinished) {+ const waiters = new Map();+ for (const item of unfinished) for (const id of afterIds(item)) waiters.set(id, [...(waiters.get(id) ?? []), item.item_id]);+ const counts = new Map();+ for (const item of unfinished) {+ const seen = new Set();+ const stack = [...(waiters.get(item.item_id) ?? [])];+ while (stack.length) {+ const id = stack.pop();+ if (seen.has(id) || id === item.item_id) continue;+ seen.add(id);+ stack.push(...(waiters.get(id) ?? []));+ }+ counts.set(item.item_id, seen.size);+ }+ return counts;+}++/**+ * How many blockers deep an item sits: 0 when everything it waits on is verified, as next requires. A withdrawn+ * blocker never clears, so it counts as one level. A cycle counts once.+ *+ * @param {Map<number, any>} open unfinished items by id+ * @param {Set<number>} withdrawn+ * @returns {(item: any) => number}+ */+function blockerDepth(open, withdrawn) {+ const depths = new Map();+ const depth = (item, visiting = new Set()) => {+ if (depths.has(item.item_id)) return depths.get(item.item_id);+ if (visiting.has(item.item_id)) return 0;+ visiting.add(item.item_id);+ const blockers = afterIds(item).map((id) => open.get(id)).filter(Boolean);+ const never = afterIds(item).some((id) => withdrawn.has(id));+ const value = blockers.length || never ? 1 + Math.max(0, ...blockers.map((blocker) => depth(blocker, visiting))) : 0;+ depths.set(item.item_id, value);+ return value;+ };+ return (item) => depth(item);+}++/** Interleave unblockers and quick wins while both last; the rest of the ready work follows by score. */+function readySequence(ready, byScore) {+ const unblockers = ready.filter((entry) => entry.unblocks > 0).sort(byScore);+ const quick = ready.filter((entry) => entry.unblocks === 0 && entry.item.item_route !== 'strong').sort(byScore);+ const zipped = [];+ const pairs = Math.min(unblockers.length, quick.length);+ for (let index = 0; index < pairs; index++) zipped.push(unblockers[index], quick[index]);+ const rest = ready.filter((entry) => !zipped.includes(entry)).sort(byScore);+ return routesNearTop([...zipped, ...rest]);+}++/** Lift each route's best ready item into the top, so no route with ready work waits behind the others. */+function routesNearTop(sequence) {+ const routes = [...new Set(sequence.map((entry) => entry.item.item_route))];+ const head = sequence.slice(0, routes.length);+ for (const route of routes) {+ if (head.some((entry) => entry.item.item_route === route)) continue;+ head.push(sequence.find((entry) => entry.item.item_route === route));+ }+ return [...head, ...sequence.filter((entry) => !head.includes(entry))];+}++/** Why an item sits where it does, in the queue's words. */+function whyOf(entry) {+ if (entry.kind === 'held') return 'held by the coordinator';+ if (entry.kind === 'blocked') return `blocked: ${entry.depth === 1 ? 'rises when its blocker lands' : `${entry.depth} blockers deep`}`;+ if (entry.unblocks > 0) return `ready and unblocks ${entry.unblocks}`;+ if (entry.item.item_route !== 'strong') return 'ready quick win';+ return 'ready work by score';+}++/**+ * The computed order of every unfinished item, release by release.+ *+ * @param {any} board+ * @param {{ priority: (entry: any) => number, shared?: (entry: any) => number }} options+ * @returns {Map<number, { position: number, unblocks: number, effort: number, score: number, why: string }>}+ */+export function computedOrder(board, { priority, shared = () => 0 }) {+ // Only unfinished items and withdrawn ids matter, so a large board's finished history is never read.+ const unfinished = listItems(board);+ const withdrawn = new Set(board.db.prepare("SELECT item_id FROM item WHERE item_status = 'withdrawn'").all().map((row) => row.item_id));+ const counts = unblockCounts(unfinished);+ const depthOf = blockerDepth(new Map(unfinished.map((item) => [item.item_id, item])), withdrawn);+ const entries = unfinished.map((item) => {+ const unblocks = counts.get(item.item_id) ?? 0;+ const effort = EFFORT[item.item_route] ?? EFFORT.strong;+ const depth = depthOf(item);+ return { item, unblocks, effort, score: (unblocks + 1) / effort, depth,+ kind: item.item_hold_reason ? 'held' : depth ? 'blocked' : 'ready', release: priority(item) };+ });+ const byScore = (first, second) => second.score - first.score || shared(second.item) - shared(first.item) || first.item.item_id - second.item.item_id;+ const order = new Map();+ for (const release of [...new Set(entries.map((entry) => entry.release))].sort((a, b) => a - b)) {+ const group = entries.filter((entry) => entry.release === release);+ const blocked = group.filter((entry) => entry.kind === 'blocked').sort((first, second) => first.depth - second.depth || byScore(first, second));+ const held = group.filter((entry) => entry.kind === 'held').sort(byScore);+ [...readySequence(group.filter((entry) => entry.kind === 'ready'), byScore), ...blocked, ...held].forEach((entry, position) => {+ order.set(entry.item.item_id, { position, unblocks: entry.unblocks, effort: entry.effort, score: entry.score, why: whyOf(entry) });+ });+ }+ return order;+}++/**+ * The self-ordering comparator for buildOrder: release, coordinator pin, coordinator sink, then the computed+ * order. With `tierFirst`, next's own route comes before the computed order, so an agent claims its tier first+ * (B13). Null below WORK_ORDER_ENGINE, where buildOrder keeps its recorded order.+ *+ * @param {any} board+ * @param {{ priority: (entry: any) => number, rank: (entry: any) => number, shared: (entry: any) => number, tierFirst?: boolean }} options+ * @returns {((first: any, second: any) => number) | null}+ */+export function workOrderCompare(board, { priority, rank, shared, tierFirst = false }) {+ if (!workOrderActive(board)) return null;+ const order = computedOrder(board, { priority, shared });+ const { sunk } = milestoneOverrides(board, priority);+ const position = (entry) => order.get(entry.item_id)?.position ?? Number.MAX_SAFE_INTEGER;+ return (first, second) => priority(first) - priority(second)+ || rank(first) - rank(second)+ || Number(sunk.has(first.item_id)) - Number(sunk.has(second.item_id))+ || (tierFirst ? ROUTES.indexOf(second.item_route) - ROUTES.indexOf(first.item_route) : 0)+ || position(first) - position(second)+ || first.item_id - second.item_id;+}++/**+ * Each item's place in the queue as pullable work explains it: unblock count, effort and why it sits there.+ *+ * @param {any} board+ * @param {{ priority: (entry: any) => number, rank: (entry: any) => number }} options+ * @returns {(item: any) => { unblocks: number, effort: number, why: string }}+ */+export function queueReasons(board, { priority, rank }) {+ const order = computedOrder(board, { priority });+ const { sunk, reasons } = milestoneOverrides(board, priority);+ return (item) => {+ const computed = order.get(item.item_id) ?? { unblocks: 0, effort: EFFORT[item.item_route] ?? EFFORT.strong, why: 'finished' };+ const reason = reasons.get(item.item_id);+ const why = rank(item) !== Number.MAX_SAFE_INTEGER ? `pinned by the coordinator: ${reason ?? 'milestone order'}`+ : sunk.has(item.item_id) ? `sunk by the coordinator: ${reason ?? 'no reason recorded'}` : computed.why;+ return { unblocks: computed.unblocks, effort: computed.effort, why };+ };+}diff --git a/test/api-catalog.test.js b/test/api-catalog.test.jsindex 909035f8..5bde6aac 100644--- a/test/api-catalog.test.js+++ b/test/api-catalog.test.js@@ -738,6 +738,10 @@ catalogCase('[A1] catalog commands keep their real repository exercises', asyncawait json(source, source.repo, 'milestone', ['items', 'Catalog', '--remove', String(catalog.item_id)], 'items');await json(source, source.repo, 'milestone', ['items', 'Catalog', '--add', String(catalog.item_id)], 'items');await json(source, source.repo, 'milestone', ['order', 'Catalog', String(catalog.item_id)], 'order');+ await json(source, source.repo, 'milestone', ['pin', 'Catalog', String(catalog.item_id), '--reason', 'Catalog coverage first'], 'pin');+ const sunk = await json(source, source.repo, 'milestone', ['sink', 'Catalog', String(catalog.item_id), '--reason', 'Catalog coverage last'], 'sink');+ assert.deepEqual([sunk.milestone.sunk, sunk.milestone.reasons[String(catalog.item_id)]], [[catalog.item_id], 'Catalog coverage last'], 'a sink records the item and its reason');+ assert.equal((await json(source, source.repo, 'milestone', ['lift', 'Catalog', String(catalog.item_id)], 'lift')).milestone.sunk, undefined, 'a lift returns the item to the computed order');await json(source, source.repo, 'milestone', ['add', 'Later'], 'add');await json(source, source.repo, 'milestone', ['move', 'Later', '--before', 'Catalog'], 'move');await json(source, source.repo, 'milestone', ['edit', 'Catalog', '--name', 'Release', '--note', 'Catalog coverage'], 'edit');diff --git a/test/move-registry-baseline.json b/test/move-registry-baseline.jsonindex 29ae5911..bb5f65ee 100644--- a/test/move-registry-baseline.json+++ b/test/move-registry-baseline.json@@ -6671,6 +6671,8 @@"MILESTONE_NAME": "pullboard milestone add <name>","MILESTONE_NOTE": "pass the note text: --note \"<text>\"","MILESTONE_ORDER": "move it before a different milestone; see pullboard roadmap",+ "MILESTONE_PLACE": "pin, sink or lift: pullboard milestone pin <name> <ids> --reason \"<why>\"",+ "MILESTONE_REASON": "say why the item moves: pullboard milestone sink <name> <ids> --reason \"<why>\"","MILESTONE_SHIPPED": "add the item to the next milestone instead: pullboard milestone items <next> --add <id>","MILESTONE_TARGET": "pass a date and time: pullboard milestone edit <name> --target 2026-10-20T18:00Z","MISSING_SIGNATURE": "have the person repeat approval for the named row: pullboard spec approve <id>",@@ -7403,7 +7405,7 @@},{"meta_key": "relay_engine_version",- "meta_value": "106"+ "meta_value": "107"},{"meta_key": "relay_receipt_registry-snapshot-2",diff --git a/test/next-order.test.js b/test/next-order.test.jsindex 2cab5155..d73e4ba6 100644--- a/test/next-order.test.js+++ b/test/next-order.test.js@@ -343,20 +343,23 @@ test('pullboard queue lists releases as breakpoints and items in pull order [N2,const lines = text.out.trim().split('\n');const at = (pattern) => lines.findIndex((line) => pattern.test(line));assert.ok(at(/^current: 0\/4 landed$/u) === 0, `the first release is a breakpoint with its landed count:\n${text.out}`);- const order = [ranked, oldest, claimed, waiting].map((id) => at(new RegExp(`^ \\d+\\. #${id} `, 'u')));- assert.deepEqual([...order].sort((a, b) => a - b), order, `items follow next's order: rank, then route, then age:\n${text.out}`);+ // The claimed item unblocks the waiting one, so the self-ordered queue (#1017) puts it above the unranked one-off.+ const order = [ranked, claimed, oldest, waiting].map((id) => at(new RegExp(`^ \\d+\\. #${id} `, 'u')));+ assert.deepEqual([...order].sort((a, b) => a - b), order, `items follow next's order: rank, then the computed order:\n${text.out}`);assert.ok(order[0] > 0 && at(/^later: 0\/1 landed$/u) > order[3], 'the later release is its own breakpoint after the current one');assert.ok(at(new RegExp(`^ \\d+\\. #${later} `, 'u')) > at(/^later: /u));assert.ok(at(/^in no release$/u) > at(new RegExp(`#${later} `, 'u')) && at(new RegExp(`#${loose} `, 'u')) > at(/^in no release$/u));assert.match(lines[order[0]], new RegExp(`#${ranked} mid api open: Ranked mid API work$`, 'u'), 'each item shows its route, lane and status');- assert.match(lines[order[2]], new RegExp(`#${claimed} strong web claimed · ${holder.agent}: `, 'u'), 'a claimed item names its holder');- assert.match(lines[order[3] + 1], new RegExp(`^ waits on #${claimed} \\(claimed\\)$`, 'u'), 'an item names what it waits on');+ assert.match(lines[order[1]], new RegExp(`#${claimed} strong web claimed · ${holder.agent}: `, 'u'), 'a claimed item names its holder');+ assert.match(lines[order[1] + 1], /^ unblocks 1 · effort 3 · ready and unblocks 1$/u, 'an item shows its unblock count, effort and why');+ assert.match(lines[order[3] + 2], new RegExp(`^ waits on #${claimed} \\(claimed\\)$`, 'u'), 'an item names what it waits on');const document = box.json(box.run(box.repo, 'queue', '--json'));assert.deepEqual(document.releases.map((release) => [release.name, release.landed, release.total, release.items.map((item) => item.id)]),- [['current', 0, 4, [ranked, oldest, claimed, waiting]], ['later', 0, 1, [later]]]);+ [['current', 0, 4, [ranked, claimed, oldest, waiting]], ['later', 0, 1, [later]]]);assert.deepEqual(document.unreleased.map((item) => item.id), [loose]);- assert.deepEqual(document.releases[0].items[2], { id: claimed, title: 'Claimed strong work', route: 'strong', lane: 'web', status: 'claimed', holder: holder.agent, waits: [] });+ assert.deepEqual(document.releases[0].items[1], { id: claimed, title: 'Claimed strong work', route: 'strong', lane: 'web', status: 'claimed', holder: holder.agent, waits: [],+ unblocks: 1, effort: 3, why: 'ready and unblocks 1' });});test('the queue names the first item each route would pull [N2,B13]', (t) => {diff --git a/test/queue-order.test.js b/test/queue-order.test.jsindex 4bfcce04..bf9125de 100644--- a/test/queue-order.test.js+++ b/test/queue-order.test.js@@ -4,7 +4,26 @@ import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { test } from 'node:test';-import { addItem, addMilestone, closeBoard, openBoard } from '../src/board.js';+import {+ addItem,+ addMilestone,+ buildOrder,+ claim,+ closeBoard,+ getItem,+ nextFor,+ openBoard,+ orderMilestoneItems,+ register,+ verify,+} from '../src/board.js';+import {+ sayQueue,+ workQueue,+} from '../src/queue.js';+import { prepareEngineMove } from '../src/engine.js';+import { submitFixture } from './board-submit-fixture.js';+import { WORK_ORDER_ENGINE } from '../src/work-order-engine.js';import { runFixtureGit } from './fixture-child.js';import { captureReleaseQueue, localReleaseRank } from '../src/release-queue.js';import { orderedWaiters } from '../src/queue-order.js';@@ -68,3 +87,82 @@ test('a run from a private clone keeps its release rank [C7,O5]', () => {assert.equal(captureReleaseQueue(dir, current), undefined, 'a directory with no board keeps its queue position');} finally { rmSync(dir, { recursive: true, force: true }); }});++test('the queue ranks unblockers and quick wins first and keeps coordinator overrides [N22,B13]', (t) => {+ const board = openBoard(':memory:');+ t.after(() => closeBoard(board));+ register(board, { lane: 'coordinator', path: '/coordinator' });+ const strong = register(board, { lane: 'core', path: '/strong', route: 'strong' });+ const mid = register(board, { lane: 'core', path: '/mid', route: 'mid' });+ const light = register(board, { lane: 'core', path: '/light', route: 'light' });+ const reviewer = register(board, { lane: 'review', path: '/reviewer', route: 'strong' });+ /** Add one core item on a route, waiting on the given items. */+ const add = (title, route, after = []) => addItem(board, { by: 'coordinator', lane: 'core', title, route, after,+ ...(route === 'strong' ? {} : { criterion: 'the item can be built and checked from its brief', check: 'true', brief: `Files: src/fixture-${title.toLowerCase().replace(/\W+/gu, '-')}.js\nTest: the queue order` }) });+ const strongOneOff = add('Strong one-off', 'strong');+ const lateStrong = add('Later strong one-off', 'strong');+ const lightOneOff = add('Light one-off', 'light');+ const midOneOff = add('Mid one-off', 'mid');+ const keystone = add('Keystone that 21 items wait on', 'strong');+ const midUnblocker = add('Mid unblocker', 'mid');+ const blocked = add('Blocked behind the mid unblocker', 'mid', [midUnblocker]);+ const waiting = Array.from({ length: 21 }, (_, index) => add(`Waits on the keystone ${index + 1}`, 'strong', [keystone]));+ addMilestone(board, { agentId: 'coordinator', name: 'now', items: [strongOneOff, lateStrong, lightOneOff, midOneOff, keystone, midUnblocker, blocked] });+ addMilestone(board, { agentId: 'coordinator', name: 'later', items: waiting });+ /** The milestone's items in queue order, and the queue rows by id. */+ const queue = () => {+ const shown = workQueue(board);+ return { ids: shown.releases[0].items.map((item) => item.id), rows: new Map(shown.releases[0].items.map((item) => [item.id, item])), shown };+ };+ /** Accept one item through the ordinary claim, submit and verify moves. */+ const land = (id, number) => {+ const builder = getItem(board, id).item_route === 'strong' ? strong : getItem(board, id).item_route === 'mid' ? mid : light;+ claim(board, id, { agentId: builder, lane: 'core', leaseMs: 3_600_000, freeze: (item) => ({ text: item.item_title, digest: `digest:${item.item_title}` }) });+ const commit = String(number).repeat(40);+ submitFixture(board, id, { agentId: builder, commit, tree: commit });+ verify(board, id, { agentId: reviewer, decision: 'ACCEPT', policy: 'any', head: commit, digest: getItem(board, id).item_frozen_digest,+ note: 'Synthetic accepted lifecycle record; no gate execution claimed.' });+ };++ let { ids, rows, shown } = queue();+ assert.deepEqual(ids, [keystone, lightOneOff, midUnblocker, midOneOff, strongOneOff, lateStrong, blocked],+ 'unblockers and quick wins alternate at the top, ready work follows by score, blocked work comes last');+ assert.equal(ids[0], keystone, 'the item 21 others wait on ranks first');+ assert.ok(ids.indexOf(lightOneOff) < ids.indexOf(strongOneOff), 'a light one-off ranks above a strong one-off');+ assert.deepEqual([rows.get(keystone).unblocks, rows.get(keystone).effort], [21, 3]);+ assert.deepEqual([rows.get(lightOneOff).unblocks, rows.get(lightOneOff).effort], [0, 1]);+ assert.match(rows.get(keystone).why, /unblocks 21/u);+ assert.match(rows.get(lightOneOff).why, /quick win/u);+ assert.match(rows.get(blocked).why, /blocked/u);+ const lines = [];+ sayQueue({ say: (text) => lines.push(text) }, shown);+ assert.ok(lines.some((line) => /unblocks 21 · effort 3 · /u.test(line)), `pullboard queue prints each item's unblock count, effort and why:\n${lines.join('\n')}`);+ assert.deepEqual([strong, mid, light].map((agentId) => nextFor(board, { agentId, lane: 'core' }).item.item_id), [keystone, midUnblocker, lightOneOff],+ 'next follows the computed order within each route, its own tier first');++ land(midUnblocker, 1);+ ({ ids } = queue());+ assert.ok(ids.indexOf(blocked) < ids.indexOf(strongOneOff), 'a blocked item rises above ready strong work once its blocker lands');+ assert.equal(nextFor(board, { agentId: mid, lane: 'core' }).item.item_id, midOneOff, 'the freed quick win joins the mid route in score order');++ orderMilestoneItems(board, 'now', { agentId: 'coordinator', items: [lateStrong], place: 'pin', reason: 'the release notes need it first' });+ orderMilestoneItems(board, 'now', { agentId: 'coordinator', items: [keystone], place: 'sink', reason: 'waits on a design answer' });+ ({ ids, rows } = queue());+ assert.equal(ids[0], lateStrong, 'a pinned item sits above the computed order');+ assert.equal(ids.at(-1), keystone, 'a sunk item sits below the computed order');+ assert.match(rows.get(lateStrong).why, /pinned by the coordinator: the release notes need it first/u);+ assert.match(rows.get(keystone).why, /sunk by the coordinator: waits on a design answer/u);+ assert.equal(nextFor(board, { agentId: strong, lane: 'core' }).item.item_id, lateStrong, 'next serves the pin');+ assert.throws(() => orderMilestoneItems(board, 'now', { agentId: strong, items: [strongOneOff], place: 'pin', reason: 'mine first' }), { code: 'COORDINATOR_ONLY' });+ assert.throws(() => orderMilestoneItems(board, 'now', { agentId: 'coordinator', items: [strongOneOff], place: 'pin' }), { code: 'MILESTONE_REASON' });+ assert.equal(prepareEngineMove(board, 'orderMilestoneItems', ['now', { agentId: 'coordinator', items: [strongOneOff], place: 'pin', reason: 'r' }]).engine >= WORK_ORDER_ENGINE, true);++ land(lightOneOff, 2);+ ({ ids } = queue());+ assert.deepEqual([ids[0], ids.at(-1)], [lateStrong, keystone], 'overrides survive a re-rank');+ orderMilestoneItems(board, 'now', { agentId: 'coordinator', items: [lateStrong, keystone], place: 'lift' });+ ({ ids, rows } = queue());+ assert.equal(ids[0], keystone, 'a lifted override returns to the computed order');+ assert.doesNotMatch(rows.get(lateStrong).why, /pinned/u);+ assert.deepEqual(ids, [...ids].sort((a, b) => buildOrder(board)(getItem(board, a), getItem(board, b))), 'the queue is the board\'s own build order');+});