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): record opt-in ordering and review scarcity [N2,B13,H16]
Corey Olsonb0e4b66ddbb3
diff --git a/docs/formats.md b/docs/formats.mdindex 8b7855c1..88125f49 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -532,10 +532,11 @@ The engine-68 `recordSpecApprovalBaseline` move carries `{agentId, baseline: {ve## Recorded board line settings-`pullboard settings line --json` reads six board-owned controller inputs. All default to `false` (off), independently of machine `gate.queue` or `pullboard.json`. `pullboard settings line <name> <on|off|number> --reason "why" --window '{"windowMinutes":60,"activeReviewers":2}'` records a coordinator-owned `setLineSetting` move. The window is a nonempty object of named finite nonnegative numbers, with `null` retaining an unknown measurement. A nonempty reason is required.+`pullboard settings line --json` reads seven board-owned controller inputs. All default to `false` (off), independently of machine `gate.queue` or `pullboard.json`. `pullboard settings line <name> <on|off|number> --reason "why" --window '{"windowMinutes":60,"activeReviewers":2}'` records a coordinator-owned `setLineSetting` move. The window is a nonempty object of named finite nonnegative numbers, with `null` retaining an unknown measurement. A nonempty reason is required.| Setting | Enabled values | Off || --- | --- | --- |+| `order` | `true` (`on`) | `false` || `reviewsFirst` | `true` (`on`) | `false` || `wipPerReviewer` | 1.5 through 3 | `false` || `barReady` | `true` (`on`) | `false` |@@ -543,4 +544,4 @@ The engine-68 `recordSpecApprovalBaseline` move carries `{agentId, baseline: {ve| `landingBatchSize` | whole numbers 1 through 8 | `false` || `landingCadenceMinutes` | whole minutes 5 through 30 | `false` |-These are recorded inputs only (#1096); this step does not enforce queue, takeover or landing behavior. The move carries `{agentId,key,value,reason,window}`; its native `line_setting` event carries `{key,value,reason,window}` with the board's actor and time outside that detail. Latest values live under `board_meta` keys `line_setting:<name>`, and ordered engine replay updates them and appends the same evidence. The unassigned `LINE_SETTINGS_ENGINE` leaf receives its permanent number at landing. Older engine records cannot request this new operation. Range, unknown-key, missing-reason and invalid-window refusals have named codes. The existing settings API reports each input as `scope: "board"`, key `line.<name>`, with off as its default and the board SQLite file as its source; it does not expose reason text or evidence payloads through that inventory.+`order` opts into next ordering: a builder’s own send-back, scarce review eligibility, release, downstream demand, signed-bar readiness, then coordinator rank. The readiness tier stays inert until the signed-readiness predicate is available (#1110); it never guesses a sign-off from prose. The other inputs retain their separate meanings; `reviewsFirst` selects review versus build and does not turn ordering on. Takeover and landing behavior are separate changes. The move carries `{agentId,key,value,reason,window}`; its native `line_setting` event carries `{key,value,reason,window}` with the board's actor and time outside that detail. Latest values live under `board_meta` keys `line_setting:<name>`, and ordered engine replay updates them and appends the same evidence. The unassigned `LINE_SETTINGS_ENGINE` leaf receives its permanent number at landing. Older engine records cannot request this new operation. Range, unknown-key, missing-reason and invalid-window refusals have named codes. The existing settings API reports each input as `scope: "board"`, key `line.<name>`, with off as its default and the board SQLite file as its source; it does not expose reason text or evidence payloads through that inventory.diff --git a/src/board.js b/src/board.jsindex 11780ec4..93b11185 100644--- a/src/board.js+++ b/src/board.js@@ -1,3 +1,9 @@+import {+ lineOrderEnabled,+ lineBuildOrder,+ reviewerScarcity,+ barReadyForOrder,+} from './line-order.js';export { lineSettings, setLineSetting } from './line-settings.js';import { recordVerdict } from './verdict-assurance.js';import { logEvent } from './board-event-log.js';@@ -2264,15 +2270,16 @@ function milestoneRanks(board, priority) {}/** Make the shared build-queue comparator once: milestone, explicit rank, route, recent files, then oldest. */-export function buildOrder(board, { warm = [] } = {}) {+export function buildOrder(board, { warm = [], agentId, readiness = barReadyForOrder } = {}) {const milestonePriority = milestonePriorities(board);const rank = milestoneRanks(board, milestonePriority);const recent = new Set(warm);const shared = (entry) => itemFiles(entry).filter((path) => recent.has(path)).length;- return (first, second) => milestonePriority(first) - milestonePriority(second)+ const fallback = (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;+ return lineOrderEnabled(board) ? lineBuildOrder({ agentId, release: milestonePriority, rank, items: listItems(board, { all: true }), ready: item => readiness(board, item), fallback }) : fallback;}/**@@ -2318,8 +2325,12 @@ export function nextFor(board, { agentId, lane, verify = false, policy = 'any',if (heldByMe) return { item: heldByMe, reasons: [] };const milestonePriority = milestonePriorities(board);const rank = milestoneRanks(board, milestonePriority);- candidates.sort((first, second) => milestonePriority(first.entry) - milestonePriority(second.entry)- || rank(first.entry) - rank(second.entry));+ const scarcity = lineOrderEnabled(board) ? reviewerScarcity(board, candidates.map(candidate => candidate.entry), (entry, reviewer) =>+ Object.values(reviewerChecks(board, { agentId: reviewer, policy, familyPolicy })).every(guard => !guard(entry))) : null;+ const lineCompare = scarcity ? buildOrder(board, { agentId }) : null;+ candidates.sort((first, second) => (scarcity ? scarcity.get(first.entry.item_id) - scarcity.get(second.entry.item_id)+ || lineCompare(first.entry, second.entry) : milestonePriority(first.entry) - milestonePriority(second.entry)+ || rank(first.entry) - rank(second.entry)));const item = candidates.find((candidate) => !candidate.holder && !candidate.cooldown)?.entry;if (item) return { item, reasons: [] };const held = candidates.filter((candidate) => candidate.holder && candidate.holder !== agentId)@@ -2340,7 +2351,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 });+ const compare = buildOrder(board, { warm, agentId });const inFlight = listItems(board, { all: true });const recent = new Set(warm);const mainRed = new Set(priority);@@ -2350,7 +2361,7 @@ export function nextFor(board, { agentId, lane, verify = false, policy = 'any',.map((entry, order) => ({ entry, order, shared: itemFiles(entry).filter((path) => recent.has(path)) })).sort((first, second) => compare(first.entry, second.entry));// Move only evidenced reworks ahead of their own tier; with no evidence, normal order is exact.- for (const route of ROUTES) {+ for (const route of lineOrderEnabled(board) ? [] : ROUTES) {const routeTier = ROUTES.indexOf(route);const selected = mine.findIndex(({ entry }) => tier(entry) === routeTier && mainRed.has(entry.item_id));const firstTierItem = mine.findIndex(({ entry }) => tier(entry) === routeTier);diff --git a/src/engine.js b/src/engine.jsindex b630eb15..4035674c 100644--- a/src/engine.js+++ b/src/engine.js@@ -69,6 +69,7 @@ import { requireCoordinatorHold } from './coordinator-hold.js';import { LANDING_ENVIRONMENT_ENGINE } from './landing-environment-engine.js';import { carriesLandingEnvironment } from './execution-environment.js';import { LANDING_LEASE_ENGINE } from './landing-lease-engine.js';+import { LINE_ORDER_ENGINE } from './line-order-engine.js';import { LINE_SETTINGS_ENGINE } from './line-settings-engine.js';const ITEM_ID_FIRST_ARGUMENT = new Set(['acceptCheck', 'editItem', 'escalate', 'recordAttempt', 'claim', 'release', 'submit', 'reserveReview', 'verify', 'merged', 'withdraw', 'refreeze', 'reopen', 'appendFact']);@@ -91,6 +92,7 @@ const OPERATION_ENGINE = Object.freeze({ setLineSetting: LINE_SETTINGS_ENGINE, d/** Dependency edits, causes, sealed reviews, submission proofs, trunk conflicts, health observations and milestone targets retain distinct recorded engine meanings. */function minimumOperationEngine(operation, args, board, at) {+ if (operation === 'setLineSetting' && args[0]?.key === 'order') return LINE_ORDER_ENGINE;if (operation === 'recordLandingTestDefect' || operation === 'verify' && args[1]?.environment !== undefined|| operation === 'recordGateRun' && Object.hasOwn(args[0]?.receipt ?? {}, 'environment')|| operation === 'recordLandingBatch' && carriesLandingEnvironment(args[0]?.batch)) return LANDING_ENVIRONMENT_ENGINE;diff --git a/src/help.js b/src/help.jsindex 139ed415..5a6919b4 100644--- a/src/help.js+++ b/src/help.js@@ -25,7 +25,7 @@ Set upin a linked main checkout it also takes the board's coordinator herepullboard resources local resource holders and their FIFO queuespullboard settings line [<name> <on|off|number> --reason "why" --window <json>] read or record board controller inputs; all off by default, no queue enforcement- names: reviewsFirst, wipPerReviewer (1.5-3), barReady, takeoverMinutes (15-60), landingBatchSize (1-8), landingCadenceMinutes (5-30)+ names: order, reviewsFirst, wipPerReviewer (1.5-3), barReady, takeoverMinutes (15-60), landingBatchSize (1-8), landingCadenceMinutes (5-30)pullboard settings [gateSlots <n> | browserSlots <n>] view or set machine capacity (gate default 2; browser default 1)browser-free check slots are opt-in: gate.browserFreeChecks in ~/.pullboard/settings.json (default false)a test file takes a browser slot only if it launches Chrome: gate.browserByLaunch (default false)diff --git a/src/line-order-engine.js b/src/line-order-engine.jsnew file mode 100644index 00000000..8df49923--- /dev/null+++ b/src/line-order-engine.js@@ -0,0 +1,3 @@+/** Opt-in queue ordering gets its permanent replay engine number at landing [N2,H16]. */+import { unassignedEngine } from './engine-next.js';+export const LINE_ORDER_ENGINE = unassignedEngine();diff --git a/src/line-order.js b/src/line-order.jsnew file mode 100644index 00000000..b190c29e--- /dev/null+++ b/src/line-order.js@@ -0,0 +1,41 @@+/** Opt-in queue ordering reads recorded board policy and the same review guards as actual reservation [N2,B13,H16]. */+import { ENGINE_VERSION } from './machine.js';+import { LINE_ORDER_ENGINE } from './line-order-engine.js';+import { lineSettings } from './line-settings.js';+import { listAgents } from './seats.js';++/** Old recorded moves retain their previous ordering even when replayed beside newer policy records. */+export function lineOrderEnabled(board) {+ return (board.executionEngineVersion ?? ENGINE_VERSION) >= LINE_ORDER_ENGINE && lineSettings(board).order === true;+}++/** Construct one snapshot of downstream demand; closed and withdrawn followers cannot manufacture priority. */+export function waitedOnItems(items) {+ const wanted = new Set();+ for (const item of items) {+ if (['withdrawn', 'verified'].includes(item.item_status)) continue;+ for (const id of (item.item_after ?? '').split(',').filter(Boolean)) wanted.add(Number(id));+ }+ return wanted;+}++/** Count potential reviewers through the actual reservation guards, rather than inventing a parallel lineage rule. */+export function reviewerScarcity(board, items, eligible) {+ const agents = listAgents(board);+ return new Map(items.map(item => [item.item_id, agents.filter(agent => eligible(item, agent.agent_id)).length]));+}++/** Order unfinished work by release, downstream demand, readiness and finally the coordinator's explicit rank. */+export function lineBuildOrder({ agentId, release, rank, items, ready = () => false, fallback }) {+ const wanted = waitedOnItems(items);+ /** A returned item still names the builder whose work must be finished before starting fresh work. */+ const returning = item => item.item_verdict === 'REJECT' && item.item_built_by === agentId;+ return (first, second) => Number(returning(second)) - Number(returning(first))+ || release(first) - release(second)+ || Number(wanted.has(second.item_id)) - Number(wanted.has(first.item_id))+ || Number(ready(second)) - Number(ready(first))+ || rank(first) - rank(second) || fallback(first, second);+}++/** Signed bar readiness is deliberately inert until #1110 supplies its authoritative predicate; no records are inferred. */+export function barReadyForOrder(_board, _item) { return false; }diff --git a/src/line-settings.js b/src/line-settings.jsindex 43b171f5..79e74853 100644--- a/src/line-settings.js+++ b/src/line-settings.js@@ -5,6 +5,7 @@ import {LINE_SETTING_DEFINITIONS,validateLineSetting,} from './queue-settings.js';+import { LINE_ORDER_ENGINE } from './line-order-engine.js';import { LINE_SETTINGS_ENGINE } from './line-settings-engine.js';import { Refused } from './refused.js';@@ -38,7 +39,8 @@ function windowNumbers(value) {/** Change one board input atomically with its reason and measured window, so ordered replay makes the same event. */export function setLineSetting(board, { agentId, key, value, reason, window } = {}) {if (agentId !== 'coordinator') throw new Refused('COORDINATOR_ONLY', 'ask the coordinator to record a line setting with its reason and window numbers');- if ((board.executionEngineVersion ?? LINE_SETTINGS_ENGINE) < LINE_SETTINGS_ENGINE) throw new Refused('ENGINE_VERSION', 'upgrade Pullboard before recording or replaying board line settings');+ const required = key === 'order' ? LINE_ORDER_ENGINE : LINE_SETTINGS_ENGINE;+ if ((board.executionEngineVersion ?? required) < required) throw new Refused('ENGINE_VERSION', 'upgrade Pullboard before recording or replaying board line settings');validateLineSetting(key, value);if (typeof reason !== 'string' || !reason.trim()) throw new Refused('LINE_SETTING_REASON', 'give the reason for this change with --reason "what the measured window shows"');const change = { key, value, reason: reason.trim(), window: windowNumbers(window) };diff --git a/src/queue-settings.js b/src/queue-settings.jsindex 941df18a..224aed95 100644--- a/src/queue-settings.js+++ b/src/queue-settings.js@@ -88,6 +88,7 @@ export function gateQueueSettings() {/** Board-owned controller inputs; false means off, independently of machine gate settings. */export const LINE_SETTING_DEFINITIONS = Object.freeze({+ order: Object.freeze({ type: 'boolean' }),reviewsFirst: Object.freeze({ type: 'boolean' }),wipPerReviewer: Object.freeze({ type: 'number', min: 1.5, max: 3, integer: false }),barReady: Object.freeze({ type: 'boolean' }),diff --git a/test/line-settings.test.js b/test/line-settings.test.jsindex ced5c715..0fb3ca53 100644--- a/test/line-settings.test.js+++ b/test/line-settings.test.js@@ -66,7 +66,7 @@ test('the settings inventory exposes board line values and defaults without audi} finally {for (const [key, value] of Object.entries(previous)) { if (value === undefined) delete process.env[key]; else process.env[key] = value; }}- assert.equal(rows.length, 6);+ assert.equal(rows.length, 7);assert.deepEqual(rows.find(row => row.key === 'line.wipPerReviewer'), { key: 'line.wipPerReviewer', scope: 'board',board: store.boardId(board), root: box.repo, value: 2, default: false,source: join(box.repo, '.git', 'pullboard', 'board.sqlite'), origin: 'configured' });diff --git a/test/next-order.test.js b/test/next-order.test.jsindex 12468495..00eab50f 100644--- a/test/next-order.test.js+++ b/test/next-order.test.js@@ -711,5 +711,9 @@ test('line order sends a send-back home first and gives the scarcest review firsranked.order(true);assert.equal(store.nextFor(ranked.board, { agentId: ranked.builder, lane: 'core' }).item.item_id, dependency, 'being waited on precedes ready-bar and coordinator rank');store.withdraw(ranked.board, dependency, { agentId: 'coordinator', reason: 'private selection control: remove the prerequisite' });- assert.equal(store.nextFor(ranked.board, { agentId: ranked.builder, lane: 'core' }).item.item_id, ready, 'a ready bar precedes the coordinator rank among otherwise tied available items');+ assert.equal(store.nextFor(ranked.board, { agentId: ranked.builder, lane: 'core' }).item.item_id, ordinary, 'the signed-readiness tier is inert until its authoritative predicate lands');+ const readiness = (_board, item) => item.item_id === ready;+ const withSignedReadiness = [ordinary, ready].map(id => store.getItem(ranked.board, id))+ .sort(store.buildOrder(ranked.board, { agentId: ranked.builder, readiness }));+ assert.equal(withSignedReadiness[0].item_id, ready, 'the injected readiness predicate precedes coordinator rank without manufacturing signed records');});diff --git a/test/settings.test.js b/test/settings.test.jsindex 07b14f2c..b7cab7d7 100644--- a/test/settings.test.js+++ b/test/settings.test.js@@ -85,7 +85,7 @@ test('a line setting change is a recorded move with its reason and its range [R1'--window', JSON.stringify(numbers), '--json');assert.equal(changed.code, 0, `a board setting change succeeds: ${changed.err}${changed.out}`);assert.equal(initial.code, 0, initial.err);- const defaults = { reviewsFirst: false, wipPerReviewer: false, barReady: false, takeoverMinutes: false,+ const defaults = { order: false, reviewsFirst: false, wipPerReviewer: false, barReady: false, takeoverMinutes: false,landingBatchSize: false, landingCadenceMinutes: false };assert.deepEqual(JSON.parse(initial.out).lineSettings, defaults, 'all line controls start off, not silently enabled by a machine file');assert.equal(JSON.parse(changed.out).lineSettings.reviewsFirst, true);@@ -97,7 +97,7 @@ test('a line setting change is a recorded move with its reason and its range [R1assert.deepEqual(JSON.parse(first.event_detail), { key: 'reviewsFirst', value: true,reason: 'Review waiting exceeds the target', window: numbers, model: 'unknown' });assert.equal(first.event_by, 'coordinator');- const values = [['reviewsFirst', false], ['wipPerReviewer', 1.5], ['wipPerReviewer', 3], ['barReady', true],+ const values = [['order', true], ['order', false], ['reviewsFirst', false], ['wipPerReviewer', 1.5], ['wipPerReviewer', 3], ['barReady', true],['takeoverMinutes', 15], ['takeoverMinutes', 60], ['landingBatchSize', 1], ['landingBatchSize', 8],['landingCadenceMinutes', 5], ['landingCadenceMinutes', 30]];let sequence = appliedSequence(board);@@ -114,7 +114,7 @@ test('a line setting change is a recorded move with its reason and its range [R1}for (const [key, value] of [['wipPerReviewer', 1.49], ['wipPerReviewer', 3.01], ['takeoverMinutes', 14],['takeoverMinutes', 61], ['landingBatchSize', 0], ['landingBatchSize', 9], ['landingBatchSize', 1.5],- ['landingCadenceMinutes', 4], ['landingCadenceMinutes', 31], ['reviewsFirst', 1]]) {+ ['landingCadenceMinutes', 4], ['landingCadenceMinutes', 31], ['reviewsFirst', 1], ['order', 1]]) {const before = store.events(board).length;assert.throws(() => store.setLineSetting(board, { agentId: 'coordinator', key, value, reason: 'Invalid limit', window: numbers }), /LINE_SETTING_RANGE/u);assert.equal(store.events(board).length, before, 'a refused value appends no successful setting event');