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): pullboard queue shows the work queue in pull order [N2,B13]
Corey Olson70ccae735515
diff --git a/docs/api.md b/docs/api.mdindex 29c648ff..ec881a86 100644--- a/docs/api.md+++ b/docs/api.md@@ -86,6 +86,7 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec| `runner` | `version:number`, `runner:object` || `relay` | `version:number`, `linked:boolean`, `board:string`, `url:string`, `link:string`, `sequence:number`, `behind:number`, `recovery:object` || `list` | `version:number`, `items:array` |+| `queue` | `version:number`, `releases:array`, `unreleased:array`, `first:object` || `roadmap` | `version:number`, `milestones:array` || `milestone add` | `version:number`, `milestone:object` || `milestone items` | `version:number`, `milestone:object` |@@ -376,6 +377,8 @@ The local board state and events responses include `eventLogVersion`, which idenThe coordinator maintains the roadmap with `milestone add <name> [--note ...] [--items 1,2,3]`, `milestone items <name> --add|--remove ids`, `milestone move <name> --before <other>`, `milestone edit <name> [--name <new>] [--note <text>] [--target <date and time>|none]`, `milestone ship <name> [--next <name>]`, and `milestone remove <name>`. A milestone stores its name, optional note, optional target, its shipment once shipped, and ordered item ids in `board_meta`; removing a milestone leaves its items untouched. A target is stored as ISO time; `--target none` clears it. A `repo#id` reference uses a registered repo's display name (or its folder name) before `#`; its status is read from that board when the repo is registered on this machine.An item counts as done only once it has landed on main: it is verified and its merge commit is recorded. `pullboard roadmap` prints milestones in order as `N/M landed`, with the target, `past target` for an unshipped milestone whose target has passed, or the commit it shipped at, and each item as `landed`, `accepted` (verified, not landed) or its status. Its JSON results and API state use `{ name, note, target, pastTarget, shipped, items: [{ id, title, status, state }], landed, done, total, withdrawn }` for each milestone: `target` is ISO text or `null`, `shipped` is `{ commit, at, by }` or `null`, `state` is `landed`, `accepted` or the status, and `done` equals `landed`. Each milestone also carries `summary: { total, left, landed, landing, review, building, held, waiting, needsYou, pace: { last6h, last2h, last24h }, estimate, window, reason }`. Withdrawn members are omitted from milestone `items` and `total` and counted separately in `withdrawn`; remaining work precedes verified items, preserving order within each group. The summary also excludes withdrawn work from its `total`, `left`, six state counts and `needsYou`. The six summary state counts are exclusive and sum to summary `total`: landed, accepted but not landed, submitted, live claimed, held, then waiting (including expired claims and unresolved references), in that order of precedence. `left` is total minus landed. Holds include item and lane holds. `needsYou` contains local milestone item ids linked to unanswered person decisions by typed item evidence or explicit local `#N` tokens in the question; repo-qualified and URL references do not link local items. Pace counts this board's distinct currently landed items at the first merged event for their current merge commit, with windows excluding the exact lower boundary and excluding future events.++`pullboard queue` prints the work queue agents pull from, top to bottom, for agents and coordinators. Each unshipped release is a breakpoint line, `name: N/M landed` as the roadmap counts it, followed by its open, claimed and submitted items in the order `pullboard next` serves them (the board's one build order: release, rank, route, then age). Each item shows its route, lane, status and holder (the builder while claimed, the reviewer while a submitted item is reserved), and a `waits on` line names unverified items it comes after, an item hold or a lane hold. Work in no release follows under `in no release`. The closing line, `next now: strong → #N, mid → #N, light → #N`, names the first item each route would get: open, waiting on nothing, at or below that route. `--json` prints `{ releases: [{ name, landed, total, items }], unreleased, first }`, where each item is `{ id, title, route, lane, status, holder, waits }` and `first` maps each route to an item id or `null`. The person never needs it; the view's Roadmap shows only what is next and what ships in each release.`pace.last6h`, `pace.last2h` and `pace.last24h` count landings in the last six, two and 24 hours.For an unshipped milestone with at least three landings in six hours, `window` is `"6h"` and `estimate` is `{ low, high }` hours: divide `left` by each of the six-hour and two-hour hourly rates, sort the bounds and round them to the nearest half hour; a zero two-hour rate uses the six-hour rate for both bounds.With fewer than three landings in six hours but at least three in 24 hours, `window` is `"24h"` and both estimate bounds use the 24-hour hourly rate, rounded to the nearest half hour.diff --git a/src/board.js b/src/board.jsindex 6069b002..fae82160 100644--- a/src/board.js+++ b/src/board.js@@ -2231,7 +2231,7 @@ function postRigorNotices(board, trigger) {* @param {any} board* @returns {(entry: any) => number}*/-function milestonePriorities(board) {+export function milestonePriorities(board) {if ((board.executionEngineVersion ?? ENGINE_VERSION) < 8) return () => 0;const ordered = milestones(board);const items = new Map(listItems(board, { all: true }).map((entry) => [entry.item_id, entry]));diff --git a/src/cli.js b/src/cli.jsindex 55218aa0..973f631c 100644--- a/src/cli.js+++ b/src/cli.js@@ -306,6 +306,7 @@ import {registeredProjectRootsSnapshot,} from './projects.js';import * as roadmapView from './roadmap.js';+import * as queueView from './queue.js';import {rigorLines,rigorReport,@@ -2419,6 +2420,13 @@ function readCommands(io, { first, second, rest, values }) {else filtered.forEach((item) => io.say(itemLine(item, (id) => agentDisplayName(agents, ctx.config, id), merging.has(item.item_id))));return 0;},+ queue: () => {+ if (first || second || rest.length) throw new Refused('USAGE', 'pullboard queue takes no arguments');+ const queue = withBoard(context(io), (board) => queueView.workQueue(board));+ io.result?.(queue);+ queueView.sayQueue(io, queue);+ return 0;+ },roadmap: () => {if (first || second || rest.length) throw new Refused('USAGE', 'pullboard roadmap takes no arguments');const ctx = context(io);diff --git a/src/help.js b/src/help.jsindex e127d77f..b320d8af 100644--- a/src/help.js+++ b/src/help.js@@ -74,6 +74,7 @@ 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 waitspullboard 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 items@@ -256,7 +257,7 @@ const HELP_EXAMPLES = {status: 'pullboard status', view: 'pullboard view', digest: 'pullboard digest --out briefing.md', mcp: 'pullboard mcp', stats: 'pullboard stats --since 2026-10-08', log: 'pullboard log 12', ledger: 'pullboard ledger',relay: 'pullboard relay on --all', 'relay recover': 'pullboard relay recover --skip 12','lane add': 'pullboard lane add web --owns apps/web/', lane: 'pullboard lane add web --owns apps/web/',- roadmap: 'pullboard roadmap', rigor: 'pullboard rigor', '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',+ queue: 'pullboard queue', roadmap: 'pullboard roadmap', rigor: 'pullboard rigor', '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',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',diff --git a/src/json.js b/src/json.jsindex 252043b7..96941525 100644--- a/src/json.js+++ b/src/json.js@@ -29,6 +29,7 @@ export const JSON_SHAPES = {runner: shape({ runner: 'object' }),relay: shape({ linked: 'boolean', board: 'string', url: 'string', link: 'string', sequence: 'number', behind: 'number', recovery: 'object' }),list: shape({ items: 'array' }),+ queue: shape({ releases: 'array', unreleased: 'array', first: 'object' }),roadmap: shape({ milestones: 'array' }),'milestone add': shape({ milestone: 'object' }),'milestone items': shape({ milestone: 'object' }),diff --git a/src/queue.js b/src/queue.jsnew file mode 100644index 00000000..79cba514--- /dev/null+++ b/src/queue.js@@ -0,0 +1,93 @@+/**+ * pullboard queue (#797): the work queue agents pull from, top to bottom. Each unshipped release is a+ * 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.+ */+import {+ buildOrder,+ canTake,+ itemById,+ laneHold,+ listItems,+ milestonePriorities,+ roadmap,+ ROUTES,+} from './board.js';++/**+ * Who holds an item now: its builder while claimed, its reviewer while a submitted item is reserved.+ *+ * @param {any} item+ * @param {number} now+ * @returns {string | null}+ */+function holderOf(item, now) {+ if (item.item_status === 'claimed') return item.item_owner;+ if (item.item_status === 'submitted' && item.item_review_by && Date.parse(item.item_review_until) > now) return item.item_review_by;+ return null;+}++/**+ * What an item waits on before an agent can take it: unverified items it comes after, and a hold.+ *+ * @param {any} board+ * @param {any} item+ * @returns {string[]}+ */+function waitsOf(board, item) {+ const after = (item.item_after ? item.item_after.split(',').map(Number) : [])+ .map((id) => itemById(board, id))+ .filter((before) => before && before.item_status !== 'verified')+ .map((before) => `#${before.item_id} (${before.item_status})`);+ const lane = laneHold(board, item.item_lane);+ return [...after, ...(item.item_hold_reason ? [`held: ${item.item_hold_reason}`] : []), ...(lane ? [`${item.item_lane} lane held: ${lane.hold_reason}`] : [])];+}++/**+ * The queue as one document: releases in roadmap order with their items in pull order, the work in+ * 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> }}+ */+export function workQueue(board) {+ 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).sort(buildOrder(board));+ 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) });+ 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).length);+ 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 };+}++/**+ * Print the queue: a breakpoint line per release, its items numbered in pull order, then the routes.+ *+ * @param {{ say: (text: string) => void }} io+ * @param {ReturnType<typeof workQueue>} queue+ */+export function sayQueue(io, queue) {+ let rank = 0;+ const line = (item) => {+ const who = item.holder ? ` · ${item.holder}` : '';+ io.say(` ${++rank}. #${item.id} ${item.route} ${item.lane} ${item.status}${who}: ${item.title}`);+ if (item.waits.length) io.say(` waits on ${item.waits.join('; ')}`);+ };+ for (const release of queue.releases) {+ io.say(`${release.name}: ${release.landed}/${release.total} landed`);+ release.items.forEach(line);+ }+ if (queue.unreleased.length) {+ io.say('in no release');+ queue.unreleased.forEach(line);+ }+ if (!queue.releases.length && !queue.unreleased.length) io.say('nothing in the queue');+ io.say(`next now: ${Object.entries(queue.first).map(([route, id]) => `${route} → ${id === null ? 'nothing' : `#${id}`}`).join(', ')}`);+}diff --git a/test/api.test.js b/test/api.test.jsindex 2fa7ef62..aa120ad9 100644--- a/test/api.test.js+++ b/test/api.test.js@@ -1005,6 +1005,7 @@ test('[A1] every catalog command and subcommand has a real CLI exercise', () =>assert.deepEqual(landing.landed, []);assert.deepEqual(landing.items, []);json(source, source.repo, 'roadmap');+ json(source, source.repo, 'queue');json(source, source.repo, 'rigor');json(source, source.repo, 'milestone', ['add', 'Catalog', '--items', String(catalog.item_id)], 'add');json(source, source.repo, 'milestone', ['items', 'Catalog', '--remove', String(catalog.item_id)], 'items');diff --git a/test/next-order.test.js b/test/next-order.test.jsindex ed4c287f..12de446a 100644--- a/test/next-order.test.js+++ b/test/next-order.test.js@@ -299,6 +299,61 @@ test('next follows the rank the coordinator set inside a milestone [N2,B13]', (tassert.doesNotMatch(JSON.stringify(beginner.overview ?? beginner), /milestone order|rank the queue/iu, 'newcomer help does not gain scheduling words');});+test('pullboard queue lists releases as breakpoints and items in pull order [N2,B13]', (t) => {+ const box = crossLaneFixture(t);+ const holder = box.seat('queue-holder', 'web', box.session);+ const oldest = box.add('web', 'Oldest unranked strong work');+ const ranked = box.add('api', 'Ranked mid API work', 'mid');+ const claimed = box.add('web', 'Claimed strong work');+ const waiting = box.add('web', 'Work after the claimed item');+ const later = box.add('api', 'Later release work');+ const loose = box.add('web', 'Work in no release');+ box.json(box.run(box.repo, 'milestone', 'add', 'current', '--items', `${oldest},${ranked},${claimed},${waiting}`, '--json'));+ box.milestone('later', later);+ box.json(box.run(box.repo, 'milestone', 'order', 'current', `${ranked}`, '--json'));+ box.json(box.run(box.repo, 'edit', String(waiting), '--after', String(claimed), '--json'));+ box.json(box.runAs(box.session, holder.root, 'claim', String(claimed), '--json'));++ const text = box.run(box.repo, 'queue');+ assert.equal(text.code, 0, text.out + text.err);+ 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}`);+ 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');++ 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]]]);+ 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: [] });+});++test('the queue names the first item each route would pull [N2,B13]', (t) => {+ const box = crossLaneFixture(t);+ const strongWork = box.add('web', 'Strong release work');+ const midWork = box.add('api', 'Mid release work', 'mid');+ const lightWork = box.add('api', 'Light release work', 'light');+ box.json(box.run(box.repo, 'milestone', 'add', 'current', '--items', `${lightWork},${midWork},${strongWork}`, '--json'));+ const document = box.json(box.run(box.repo, 'queue', '--json'));+ assert.deepEqual(document.first, { strong: strongWork, mid: midWork, light: lightWork }, 'each route gets the top item at or below it, its own tier first');+ const text = box.run(box.repo, 'queue');+ assert.match(text.out.trim().split('\n').at(-1), new RegExp(`^next now: strong → #${strongWork}, mid → #${midWork}, light → #${lightWork}$`, 'u'));+ // The queue's answer is what next actually serves each route.+ for (const [route, lane, id] of [['light', 'api', lightWork], ['mid', 'api', midWork], ['strong', 'web', strongWork]]) {+ const seat = box.seat(`queue-${route}`, lane, `queue-${route}-session`, route);+ const next = box.json(box.runAs(`queue-${route}-session`, seat.root, 'next', '--build', '--json'));+ assert.equal(next.item.item_id, id, `a ${route} agent's next is the queue's ${route} item`);+ }+ assert.match(box.run(box.repo, 'queue').out.trim().split('\n').at(-1), /^next now: strong → nothing, mid → nothing, light → nothing$/u, 'claimed work leaves the routes nothing to pull');+});+test('an unranked item follows the ranked ones [N2,B13]', (t) => {const { board, builder } = boardFixture();t.after(() => store.closeBoard(board));