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(decisions): queue item choices without releasing work [B21,B27]
Corey Olson7f0eca7bacd2
diff --git a/docs/api.md b/docs/api.mdindex fe580171..058ae5b3 100644--- a/docs/api.md+++ b/docs/api.md@@ -661,3 +661,7 @@ When `publish.pullRequest` is enabled, `pullboard publish` reconciles the GitHubA board-recorded item merge covers its introduced commits only when its exact submitted commit has that receipt and is an ancestor of the recorded merge. `Pullboard-Companion: #N` is covered only on a board-recorded trunk containing item N's landing. Unreceipted commits, including release bumps and synthetic publication commits, remain unverified. An outside PR is allowed and initially reads `not verified`; the JSON result's `verification[].intake` names the existing `pullboard intake` command that files it for review. Outside intake can cover only its exact accepted head, never its earlier commits by inference.The JSON result includes `verification` entries with PR number, exact head, state, assurance, receipt identities, and any unverified commit IDs. GitHub statuses are shared by PRs with the same head: if an outside or unproven PR shares a commit with a proven proposal, the shared status stays red rather than lending the proposal's green status to it. Publishing observes and posts statuses; it never merges a PR or requires outside authors to use Pullboard.++### Item decision queue++The full and summary board state include `decisionQueue`, the coordinator's open decisions, separate from recent `shouts` and the person's `decisions`/Needs you. Structured item questions retain the ordinary shout fields and add `item` and `options`. The state delta carries this small queue whole, so an answer removes its pending entry. Use the normal authenticated `answer` move to append an answer; a decision passed to the person requires the existing person channel.diff --git a/docs/formats.md b/docs/formats.mdindex 911a951c..cba59cbd 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -652,3 +652,7 @@ its number at landing; no event-log or envelope format changes.With `reviewsFirst` on, ordinary `next` offers an eligible review before a build when outstanding submissions exceed `wipPerReviewer` times the active-reviewer count (or ratio 3 while that numeric control is off). No permanent builder/reviewer seat type or role flag is required. Active reviewers are distinct registered seats with a reservation or verdict inside the flow window; its default is the last hour, and an empty window counts as one reviewer. The window uses the same validated boundaries as `stats --window`; its native duration is the shared `ACTIVE_REVIEWER_WINDOW_MINUTES` constant (60), not the measurement metadata or a new board setting.With numeric `wipPerReviewer` on, a new claim that would exceed that limit is refused as `LINE_WIP_LIMIT`, naming the oldest eligible pending review when there is one. Live claimed items and outstanding submissions count; expired claims do not. The shared pure `lineWipLimit` function computes the total cap without rounding, using at least one observed reviewer. Renewals remain possible. The native claim carries the configured verifier and family policies so its suggested review never relaxes those guards. With `takeoverMinutes` on, a sent-back item's idle interval can end its original builder's first-refusal window early; a live claim is never stolen, and normal claim appends preserve the old history. Disabled controls retain the previous behavior. New claims under these controls carry a true `lineCapacity` argument and the line-capacity engine floor; marker-absent older recorded claims keep their historical meaning during replay.++### Item decision options++A `shout` ordered move may carry `options`, an array of at least two distinct nonempty strings, only with `decision: true` and an item. The move requires the decision-queue engine leaf; older shouts retain their original meaning. The authoritative item event carries `decisionOptions` and `item`; `board_meta` keys `item_decision:<shout-id>` index those options for the open queue. Passing a question to the person copies its original options and item into the new decision index. Answers append ordinary answer events on the item; neither asking nor answering changes the claim or lease.diff --git a/src/api-moves.js b/src/api-moves.jsindex 6b397f10..8fdea451 100644--- a/src/api-moves.js+++ b/src/api-moves.js@@ -23,7 +23,7 @@ const MOVES = {reopen: { item: true, flags: ['note', 'cause'], lists: ['conflict'], booleans: ['withdraw-verdict'] },escalate: { item: true, flags: ['note'] },hold: { positions: ['lane'], flags: ['reason'], booleans: ['off'] },- shout: { positions: ['to', 'text'], optional: ['to'], booleans: ['decision'], flags: ['evidence', 'outcome', 'item', 'commit'] },+ shout: { positions: ['to', 'text'], optional: ['to'], booleans: ['decision'], flags: ['evidence', 'outcome', 'item', 'commit', 'options'] },answer: { item: true, positions: ['text'], flags: ['as', 'implies', 'supersedes'] },pass: { item: true, positions: ['note'] },next: { flags: ['as'], booleans: ['verify', 'build'] },diff --git a/src/api.js b/src/api.jsindex a7d7135d..46b147e2 100644--- a/src/api.js+++ b/src/api.js@@ -485,6 +485,7 @@ function buildLocalBoardState(root, boardId, board, codeIsMain, { previous = nul} });state.agents = state.agents.map((agent) => ({ ...agent, model: agent.agent_model ?? 'unknown', displayName: displayAgentName(agent, config.agents.names) }));state.board = boardId;+ state.decisionQueue = store.openDecisions(board, COORDINATOR);const projectData = {requests: store.openRequests(board),personRequests: personRequestStatuses(board),@@ -556,7 +557,7 @@ function snapshotEntry(revision, state, preparedFlow, { inputs = null, itemMeta}/** State fields every delta carries whole: this request's unread count and flow, and the small Needs-you lists. */-const DELTA_WHOLE = new Set(['unseen', 'proofStats', 'decisions', 'holds', 'requests', 'personRequests']);+const DELTA_WHOLE = new Set(['unseen', 'proofStats', 'decisions', 'decisionQueue', 'holds', 'requests', 'personRequests']);/** The state lists a delta merges entry by entry, and the field that names each entry. */const DELTA_KEYS = Object.freeze({ items: 'id', shouts: 'shout_id', asked: 'shout_id', events: 'event_id', agents: 'agent_id', spec: 'id', practice: 'id', milestones: 'name' });/** How many recent builds of each board a server keeps as possible delta bases. */diff --git a/src/board-query.js b/src/board-query.jsindex 062ddad9..4aa11dec 100644--- a/src/board-query.js+++ b/src/board-query.js@@ -1,3 +1,4 @@+import { projectItemDecisions } from './item-decision-queue.js';import { itemById } from './board-item-read.js';import { itemActivity } from './activity-feed.js';export { itemById };@@ -175,9 +176,9 @@ export function reviewQueue(board) {*/export function openDecisions(board, recipient = null) {if (recipient === null) {- return board.db+ return projectItemDecisions(board, board.db.prepare('SELECT * FROM shout ask WHERE ask.shout_decision = 1 AND NOT EXISTS (SELECT 1 FROM shout reply WHERE reply.shout_answers = ask.shout_id) ORDER BY ask.shout_id')- .all();+ .all());}const recipients = [...new Set(Array.isArray(recipient) ? recipient : [recipient])];if (!recipients.length) return [];diff --git a/src/board.js b/src/board.jsindex 8eb82fd7..3e76c80c 100644--- a/src/board.js+++ b/src/board.js@@ -1,3 +1,4 @@+import { itemDecisionDetail, recordItemDecision } from './item-decision-queue.js';import {focusOrder,focusReasons,@@ -1660,8 +1661,9 @@ export { getItem } from './board-query.js';* @param {{ from: string, to: string, text: string, lanes: string[], item?: number, decision?: boolean, answers?: number | null, evidence?: any, request?: boolean, channel?: 'terminal' | 'view', detail?: object }} message - detail: extra event fields* @returns {number}*/-function insertShout(board, { from, to, text, lanes, item, decision = false, answers = null, evidence = null, request = false, channel = 'terminal', detail = {} }) {+function insertShout(board, { from, to, text, lanes, item, decision = false, answers = null, evidence = null, request = false, channel = 'terminal', detail = {}, options }) {const engine = board.executionEngineVersion ?? ENGINE_VERSION;+ detail = { ...detail, ...itemDecisionDetail(board, { options, decision, item, from }, engine) };if (item !== undefined) {if (engine < ITEM_SHOUT_ENGINE) throw new Refused('ENGINE_VERSION', 'item messages require engine 93; upgrade every linked device before sending one');to = itemShoutTarget(board.db, item);@@ -1719,6 +1721,7 @@ function persistShout(board, { from, to, text, decision = false, answers = null,.run(from, to, text.trim(), now(board), decision ? 1 : 0, answers, evidence?.kind ?? null, evidence ? evidence.outcome.trim() : null, evidence?.item ?? null, evidence?.commit ?? null, request ? 1 : 0, outcome);const id = Number(result.lastInsertRowid);logEvent(board, from, answers === null ? 'shout' : decision ? 'pass' : 'answer', detail.item ?? null, { shout: id, to, decision: Boolean(decision), request: Boolean(request), answers, ...(outcome ? { outcome } : {}), ...(personAnswer ? { channel } : {}), ...detail });+ recordItemDecision(board, id, { decision, answers, detail });return id;}diff --git a/src/cli-main.js b/src/cli-main.jsindex 5f9b3d99..8903d865 100644--- a/src/cli-main.js+++ b/src/cli-main.js@@ -126,6 +126,7 @@ const OPTIONS = {since: { type: 'string' },window: { type: 'string' },decision: { type: 'boolean' },+ options: { type: 'string' },evidence: { type: 'string' },outcome: { type: 'string' },item: { type: 'string' },diff --git a/src/cli.js b/src/cli.jsindex d83617d7..228da34b 100644--- a/src/cli.js+++ b/src/cli.js@@ -1036,7 +1036,7 @@ export function verifiedMergeGroups(root, items, shouts, now) {export function coordinatorDecisionSections(board, ctx) {const shouts = store.decisionAndEvidenceShouts(board);const openDecisions = store.openDecisions(board, COORDINATOR).map((ask) => ({- id: ask.shout_id, asker: ask.shout_from, question: ask.shout_text, at: ask.shout_at, age: span(ctx, ask.shout_at),+ id: ask.shout_id, asker: ask.shout_from, question: ask.shout_text, ...(ask.options ? { options: ask.options, item: ask.item } : {}), at: ask.shout_at, age: span(ctx, ask.shout_at),}));const answers = new Map(store.decisionAnswers(board).map(answer => [answer.shout_answers, answer]));const recentAnswers = shouts.filter((ask) => ask.shout_decision).flatMap((ask) => {diff --git a/src/commands/decisions.js b/src/commands/decisions.jsindex 38ea3d4e..b507c681 100644--- a/src/commands/decisions.js+++ b/src/commands/decisions.js@@ -20,6 +20,6 @@ export function run(io, { values }) {});io.result?.({ decisions: asks });if (!asks.length) io.say('no open decisions');- for (const ask of asks) io.say(`#${ask.shout_id} ${agentDisplayName(agents, ctx.config, ask.shout_from)} -> ${agentDisplayName(agents, ctx.config, ask.shout_to)}, ${span(ctx, ask.shout_at)} ago: ${firstLine(ask.shout_text)}`);+ for (const ask of asks) io.say(`#${ask.shout_id} ${agentDisplayName(agents, ctx.config, ask.shout_from)} -> ${agentDisplayName(agents, ctx.config, ask.shout_to)}, ${span(ctx, ask.shout_at)} ago: ${firstLine(ask.shout_text)}${ask.options ? '\n' + ask.options.map((option, index) => ` ${index + 1}. ${option}`).join('\n') : ''}`);return 0;}diff --git a/src/commands/shout.js b/src/commands/shout.jsindex e2b07fab..5d24479d 100644--- a/src/commands/shout.js+++ b/src/commands/shout.js@@ -1,3 +1,4 @@+import { Refused } from '../refused.js';/** The pullboard shout command, in its own module so an item adding another command never edits these lines. */import * as store from '../board.js';import {@@ -20,12 +21,17 @@ import {export async function run(io, { first, second, rest, values }) {const act = (work) => actOn(io, work);return act(async (ctx, board, me) => {+ let options;+ if (values.options !== undefined) {+ try { options = JSON.parse(values.options); }+ catch { throw new Refused('BAD_DECISION_OPTIONS', 'give --options as a JSON array of distinct choices'); }+ }const evidence = values.evidence === undefined ? null : evidenceFrom(ctx, values);const recipients = ['all', 'person', ...laneNames(ctx.config), ...board.db.prepare('SELECT agent_id FROM agent').all().map((agent) => agent.agent_id)];const hasRecipient = first && recipients.includes(first) && (values.item === undefined || second !== undefined);const to = values.item !== undefined ? `item:${values.item}` : hasRecipient ? first : values.decision ? (me.id === COORDINATOR ? 'person' : COORDINATOR) : first ?? '';const text = [hasRecipient ? second : first, ...(hasRecipient ? rest : [second, ...rest])].filter(Boolean).join(' ');- const id = await ordered(ctx, board, 'shout', [{ from: personShout(io, me) ? store.PERSON : me.id, to, text, ...(values.item !== undefined ? { item: Number(values.item) } : {}), lanes: laneNames(ctx.config), decision: Boolean(values.decision), evidence }]);+ const id = await ordered(ctx, board, 'shout', [{ from: personShout(io, me) ? store.PERSON : me.id, to, text, ...(values.item !== undefined ? { item: Number(values.item) } : {}), lanes: laneNames(ctx.config), decision: Boolean(values.decision), ...(options !== undefined ? { options } : {}), evidence }]);io.result?.({ id, decision: Boolean(values.decision) });const agents = store.listAgents(board);const recipient = agents.some((agent) => agent.agent_id === to) ? agentDisplayName(agents, ctx.config, to) : to;diff --git a/src/decision-queue-engine.js b/src/decision-queue-engine.jsnew file mode 100644index 00000000..bb98b250--- /dev/null+++ b/src/decision-queue-engine.js@@ -0,0 +1,3 @@+/** Explicit item-decision options retain their meaning when ordered moves replay [B21,B27,H16]. */+import { unassignedEngine } from './engine-next.js';+export const DECISION_QUEUE_ENGINE = unassignedEngine();diff --git a/src/help.js b/src/help.jsindex 93f31957..b62cbfcf 100644--- a/src/help.js+++ b/src/help.js@@ -152,6 +152,7 @@ Workpullboard shout --item <id> <text> message the item builder, reviewer and coordinatorA seat shout to all reaches only coordinator and person; their broadcasts reach everyone.pullboard shout [<to>] <text> --decision ask for a decision; defaults to your coordinator or the person+ pullboard shout coordinator <question> --item <id> --decision --options '["first","second"]'pullboard shout <to> <text> --evidence attempt|receipt --outcome <word> --item <id> --commit <rev>pullboard answer <shout-id> <text> [--as person] [--implies <ids>] [--supersedes <answer-id>]answer your decision; person mode is main-checkout onlydiff --git a/src/item-decision-queue.js b/src/item-decision-queue.jsnew file mode 100644index 00000000..f161cda4--- /dev/null+++ b/src/item-decision-queue.js@@ -0,0 +1,41 @@+/** Structured choices on the existing append-only decision/answer stream [B21,B27]. */+import { DECISION_QUEUE_ENGINE } from './decision-queue-engine.js';+import { Refused } from './refused.js';+import { itemShoutReader, shoutItemId } from './shout-audience.js';++/** Validate new decision metadata before any message is persisted, without changing legacy shouts. */+export function itemDecisionDetail(board, message, engine) {+ const { options, decision, item, from } = message;+ if (options === undefined) return {};+ if (engine < DECISION_QUEUE_ENGINE) throw new Refused('ENGINE_VERSION', 'upgrade Pullboard before asking an item decision with options');+ if (!decision || !Number.isSafeInteger(item) || item <= 0 || !Array.isArray(options) || options.length < 2+ || options.some(option => typeof option !== 'string' || !option.trim())+ || new Set(options.map(option => option.trim())).size !== options.length) {+ throw new Refused('BAD_DECISION_OPTIONS', 'ask an item decision with at least two distinct nonempty options: pullboard shout coordinator "<question>" --item <id> --decision --options \'["first","second"]\'');+ }+ if (!itemShoutReader(board.db, item, from)) throw new Refused('NOT_YOUR_ITEM_DECISION', 'ask a decision on an item you build or review, or ask the coordinator for a cross-item decision');+ return { decisionOptions: options.map(option => option.trim()) };+}++/** Save a query index alongside its authoritative event; passing up preserves the original options. */+export function recordItemDecision(board, id, { decision, answers, detail }) {+ if (!decision) return;+ let record = detail.decisionOptions ? { item: detail.item, options: detail.decisionOptions } : null;+ if (!record && answers !== null) {+ const original = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get(`item_decision:${answers}`);+ if (original) record = JSON.parse(original.meta_value);+ }+ if (record) board.db.prepare('INSERT INTO board_meta (meta_key,meta_value) VALUES (?,?)').run(`item_decision:${id}`, JSON.stringify(record));+}++/** Read metadata in one indexed batch; ordinary legacy decisions retain their original shape. */+export function projectItemDecisions(board, asks) {+ if (!asks.length) return asks;+ const keys = asks.map(ask => `item_decision:${ask.shout_id}`);+ const rows = board.db.prepare(`SELECT meta_key,meta_value FROM board_meta WHERE meta_key IN (${keys.map(() => '?').join(',')})`).all(...keys);+ const records = new Map(rows.map(row => [row.meta_key, JSON.parse(row.meta_value)]));+ return asks.map(ask => {+ const record = records.get(`item_decision:${ask.shout_id}`);+ return record ? { ...ask, item: record.item ?? shoutItemId(ask.shout_to), options: record.options } : ask;+ });+}diff --git a/src/moves/shout.js b/src/moves/shout.jsindex 52421427..10ef1d40 100644--- a/src/moves/shout.js+++ b/src/moves/shout.js@@ -1,3 +1,4 @@+import { DECISION_QUEUE_ENGINE } from '../decision-queue-engine.js';import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';/** Routing metadata owned by shout, discovered without a shared registry edit [C7,V4,H16]. */import { ITEM_SHOUT_ENGINE } from '../item-shout-engine.js';@@ -6,6 +7,7 @@ import { BOARD_SENTINEL_ENGINE } from '../sentinel-engine.js';/** Preserve this operation's historical first-matching engine conditions [H16]. */function minimumEngine(args, board, at) {+ if (args[0]?.options !== undefined) return DECISION_QUEUE_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return RIGOR_AUTO_ENGINE;if (args[0]?.item !== undefined) return ITEM_SHOUT_ENGINE;if (args[0]?.landingFence !== undefined) return LANDING_LEASE_ENGINE;@@ -21,6 +23,8 @@ export default Object.freeze({ operation: "shout", order: 23, engine: 1,nextSteps: Object.freeze({"B26_PERSON_CHANNEL": "record it as the person through pullboard view or the person's own terminal","B26_PERSON_DECISION": "ask your coordinator: pullboard shout coordinator \"<question>\" --decision",+ "BAD_DECISION_OPTIONS": "ask an item decision with --decision --item <id> --options '[\"first\",\"second\"]'",+ "NOT_YOUR_ITEM_DECISION": "ask on an item you build or review, or ask the coordinator for a cross-item decision","BAD_EVIDENCE": "pass the evidence fields the message names, then retry","BAD_REQUEST": "send the request body the message names as an application/json object","COORDINATOR_ONLY": "ask the coordinator to do it: pullboard shout coordinator \"<what you need>\"",diff --git a/test/decision-queue.test.js b/test/decision-queue.test.jsindex 480c3906..073fa1c6 100644--- a/test/decision-queue.test.js+++ b/test/decision-queue.test.js@@ -1,6 +1,13 @@/** Public real-CLI/SQLite decision queue, claim retention and person boundary [B7,B21,B26,B27]. */import assert from 'node:assert/strict';import { test } from 'node:test';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import * as store from '../src/board.js';+import { prepareEngineMove, applyEngineMove } from '../src/engine.js';+import { exportBoard, importBoard } from '../src/exchange.js';+import { DECISION_QUEUE_ENGINE } from '../src/decision-queue-engine.js';import { createE2eHelpers } from './e2e-helpers.js';/** Run an authenticated private-board CLI command and decode its public response. */@@ -68,3 +75,44 @@ test('a decision asked on an item is answered from the queue and recorded on theassert.equal(document(box, box.repo, 'resume').needsYou.some(row => row.id === passed.id), false);assert.ok(document(box, box.web, 'inbox').shouts.some(row => /Person answered/.test(row.shout_text)));});+++test('item decision options replay exactly and never acquire legacy engine authority [B21,H3,H16]', (t) => {+ const directory = mkdtempSync(join(tmpdir(), 'pullboard-decision-queue-'));+ const source = store.openBoard(join(directory, 'source.sqlite'));+ const replica = store.openBoard(join(directory, 'replica.sqlite'));+ const restored = store.openBoard(join(directory, 'restored.sqlite'));+ t.after(() => {+ for (const board of [source, replica, restored]) store.closeBoard(board);+ rmSync(directory, { recursive: true, force: true });+ });+ store.register(source, { lane: 'coordinator', path: '/decision-root' });+ store.register(source, { lane: 'web', path: '/decision-root/web-1' });+ store.register(source, { lane: 'web', path: '/decision-root/web-2' });+ const id = store.addItem(source, { by: 'coordinator', lane: 'web', title: 'Replica choice' });+ store.claim(source, id, { agentId: 'web-1', lane: 'web', leaseMs: 7_200_000,+ freeze: () => ({ text: '{"rows":[]}', digest: 'd'.repeat(64) }) });+ importBoard(replica, exportBoard(source));+ const message = { from: 'web-1', to: 'coordinator', item: id, text: 'Which shape?', decision: true,+ options: ['Small', 'Shared'], lanes: ['coordinator', 'web'] };+ const move = prepareEngineMove(source, 'shout', [message], { id: 'item-decision', actor: 'web-1' });+ const at = new Date().toISOString();+ assert.throws(() => applyEngineMove(replica, { ...move, engine: DECISION_QUEUE_ENGINE - 1 }, { sequence: 1, at }), /RELAY_MOVE/);+ assert.deepEqual(store.openDecisions(replica), [], 'a legacy engine cannot silently discard the options');+ const answer = applyEngineMove(replica, move, { sequence: 1, at });+ assert.ok(answer);+ assert.deepEqual(store.openDecisions(replica, 'coordinator').map(row => ({ item: row.item, options: row.options })),+ [{ item: id, options: ['Small', 'Shared'] }]);+ importBoard(restored, exportBoard(replica));+ assert.deepEqual(store.openDecisions(restored), store.openDecisions(replica), 'snapshot restores the exact pending choices');+ const before = store.events(replica).length;+ for (const options of [[], ['Only'], ['Same', 'Same'], ['A', ' '], 'not an array']) {+ assert.throws(() => store.shout(replica, { ...message, options }), /BAD_DECISION_OPTIONS/);+ }+ assert.throws(() => store.shout(replica, { ...message, from: 'web-2' }), /NOT_YOUR_ITEM_DECISION/);+ assert.equal(store.events(replica).length, before, 'refused choices append no successful decision');+ const legacy = prepareEngineMove(replica, 'shout', [{ from: 'web-1', to: 'coordinator', text: 'Old question',+ decision: true, lanes: ['coordinator', 'web'] }], { id: 'legacy-decision', actor: 'web-1' });+ applyEngineMove(replica, { ...legacy, engine: 1 }, { sequence: 2, at });+ assert.equal(store.openDecisions(replica).find(row => row.shout_text === 'Old question').options, undefined);+});