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(core): persist authorized cross-board decision handoffs [B21,H16]
Corey Olson2cdccbe28adf
diff --git a/docs/api.md b/docs/api.mdindex 34edf335..fdb40f2e 100644--- a/docs/api.md+++ b/docs/api.md@@ -673,3 +673,29 @@ 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.+++### Cross-board decision handoffs++`decisionHandoffs(db, { boardId, authorize })` in `src/decision-handoff.js` is+an I-D persistence port, not an aggregation CLI or a board-name resolver.+Each participant supplies its own SQLite connection, opaque immutable board ID,+and existing authority adapter. Call mutations inside the caller’s ordered+write boundary. No transaction or database connection spans boards.++`deliver(handoff, options)` checks the exact version-1 wire shape and original+option-set digest, then asks `authorize("disclose", handoff)` and, for answers,+`authorize("answer", handoff)`. The adapter must authenticate the requester,+source decision, destination, question, option digest and answer; a supplied+opaque authority value alone grants nothing. Accepted deliveries persist before+returning. Transport retries the returned wire independently at the other board.+Changed correlation or a conflicting answer refuses; late questions preserve+answers. `optionsDigest(options)` hashes a unique option set independent of order.++`query(source, participants, authority)` requires source-board read authority+for the exact namespaced reference and participant set. It returns+`{ complete, agreed, answers }`; callers must not act on an incomplete or+disagreeing result. Each destination contributes at most one answer, and a+query cannot omit a destination already recorded for that source decision.+This contract stores and returns answers to the source/requester’s authorized+query; it does not execute the decision or grant cross-board authority.diff --git a/src/decision-handoff.js b/src/decision-handoff.jsnew file mode 100644index 00000000..23cc1488--- /dev/null+++ b/src/decision-handoff.js@@ -0,0 +1,111 @@+/** Local durable I-D contract; consumers supply their existing authority port and ordered mutation boundary. */+import { createHash } from 'node:crypto';+import { Refused } from './refused.js';++function binding() { return new Refused('DECISION_HANDOFF_BINDING', 'Use the exact versioned handoff, namespaced decision and original option set.'); }+function denied() { return new Refused('DECISION_HANDOFF_AUTH', 'Obtain authority for this exact disclosed question, answer or source query.'); }+function conflict() { return new Refused('DECISION_HANDOFF_CONFLICT', 'Use the recorded handoff and answer; create a new source decision to change its options or outcome.'); }++/** Board identifiers are opaque: only the composition boundary resolves names. */+function identifier(value) { return typeof value === 'string' && value.length > 0 && value.length <= 256; }+function fields(value, names) {+ return value && typeof value === 'object' && !Array.isArray(value)+ && Object.keys(value).sort().join(',') === names.split(',').sort().join(',');+}+function reference(value) {+ if (!fields(value, 'boardId,decisionId') || !identifier(value.boardId) ||+ !(identifier(value.decisionId) || Number.isSafeInteger(value.decisionId) && value.decisionId > 0)) throw binding();+ return { boardId: value.boardId, decisionId: value.decisionId };+}++/** Hash the option set, not its presentation order; ambiguous duplicate options refuse. */+export function optionsDigest(options) {+ if (!Array.isArray(options) || options.length < 1 || options.length > 32 ||+ options.some(option => !identifier(option)) || new Set(options).size !== options.length) throw binding();+ return createHash('sha256').update(JSON.stringify([...options].sort())).digest('hex');+}++/** Snapshot bounded wire data before an asynchronous authority check can yield to its caller. */+function snapshot(input) {+ try {+ const text = JSON.stringify(input);+ if (!text || text.length > 16384) throw binding();+ return JSON.parse(text);+ } catch { throw binding(); }+}+function wire(input, options, local) {+ const value = snapshot(input);+ if (!fields(value, 'version,handoffId,source,destinationBoardId,requester,question,optionsDigest,authority,answer') ||+ value.version !== 1 || !identifier(value.handoffId) || !identifier(value.destinationBoardId) ||+ !identifier(value.requester) || typeof value.question !== 'string' || !value.question || value.question.length > 4096 ||+ value.authority == null || !['string', 'object'].includes(typeof value.authority) ||+ value.optionsDigest !== optionsDigest(options)) throw binding();+ value.source = reference(value.source);+ if (local !== value.source.boardId && local !== value.destinationBoardId) throw binding();+ if (value.answer !== null && (!fields(value.answer, 'boardId,option') ||+ value.answer.boardId !== value.destinationBoardId || !options.includes(value.answer.option))) throw binding();+ return { version: 1, handoffId: value.handoffId, source: value.source,+ destinationBoardId: value.destinationBoardId, requester: value.requester, question: value.question,+ optionsDigest: value.optionsDigest, authority: value.authority,+ answer: value.answer === null ? null : { boardId: value.answer.boardId, option: value.answer.option } };+}+function correlation(value) {+ const { authority, answer, ...body } = value;+ return JSON.stringify(body);+}++/** Each store owns only its supplied SQLite board; delivery is retried independently at the other board. */+export function decisionHandoffs(db, { boardId, authorize }) {+ if (!identifier(boardId) || typeof authorize !== 'function') throw binding();+ db.exec(`CREATE TABLE IF NOT EXISTS decision_handoff_v1 (+ handoff_id TEXT PRIMARY KEY, source_board TEXT NOT NULL, source_decision TEXT NOT NULL,+ destination TEXT NOT NULL, wire TEXT NOT NULL, UNIQUE(source_board,source_decision,destination))`);+ return {+ /** Repeated questions cannot erase answers; a second outcome or changed identity never overwrites the first. */+ async deliver(input, suppliedOptions) {+ const options = snapshot(suppliedOptions);+ const value = wire(input, options, boardId);+ if (!await authorize('disclose', snapshot(value)) ||+ value.answer && !await authorize('answer', snapshot(value))) throw denied();+ db.exec('SAVEPOINT decision_handoff_delivery');+ try {+ const row = db.prepare(`SELECT wire FROM decision_handoff_v1 WHERE handoff_id=? OR+ (source_board=? AND source_decision=? AND destination=?)`)+ .get(value.handoffId, value.source.boardId, JSON.stringify(value.source.decisionId), value.destinationBoardId);+ const prior = row ? JSON.parse(row.wire) : null;+ const sibling = db.prepare('SELECT wire FROM decision_handoff_v1 WHERE source_board=? AND source_decision=? LIMIT 1')+ .get(value.source.boardId, JSON.stringify(value.source.decisionId));+ const first = sibling ? JSON.parse(sibling.wire) : null;+ if (first && ['optionsDigest', 'requester', 'question'].some(key => first[key] !== value[key])) throw conflict();+ if (prior && (correlation(prior) !== correlation(value) ||+ prior.answer && value.answer && JSON.stringify(prior.answer) !== JSON.stringify(value.answer))) throw conflict();+ const result = prior && (prior.answer || !value.answer) ? prior : value;+ if (!prior) db.prepare('INSERT INTO decision_handoff_v1 VALUES(?,?,?,?,?)').run(value.handoffId,+ value.source.boardId, JSON.stringify(value.source.decisionId), value.destinationBoardId, JSON.stringify(result));+ else if (result !== prior) db.prepare('UPDATE decision_handoff_v1 SET wire=? WHERE handoff_id=?')+ .run(JSON.stringify(result), value.handoffId);+ db.exec('RELEASE decision_handoff_delivery');+ return snapshot(result);+ } catch (error) {+ db.exec('ROLLBACK TO decision_handoff_delivery');+ db.exec('RELEASE decision_handoff_delivery');+ throw error;+ }+ },+ /** Query is source-authorized independently of the capabilities used to disclose each destination question. */+ async query(input, requested, authority) {+ const source = reference(snapshot(input)), participants = snapshot(requested);+ if (source.boardId !== boardId || !Array.isArray(participants) || participants.length < 1 || participants.length > 32 ||+ participants.some(participant => !identifier(participant)) || new Set(participants).size !== participants.length) throw binding();+ participants.sort();+ if (!await authorize('read', snapshot({ version: 1, source, participants, authority }))) throw denied();+ const rows = db.prepare('SELECT wire FROM decision_handoff_v1 WHERE source_board=? AND source_decision=? ORDER BY destination')+ .all(source.boardId, JSON.stringify(source.decisionId)).map(row => JSON.parse(row.wire));+ if (rows.some(value => !participants.includes(value.destinationBoardId))) throw binding();+ const answers = rows.filter(value => value.answer).map(value => value.answer);+ const complete = rows.length === participants.length && answers.length === participants.length;+ const sameOptions = rows.every(value => value.optionsDigest === rows[0].optionsDigest);+ return { complete, agreed: complete && sameOptions && new Set(answers.map(answer => answer.option)).size === 1, answers };+ },+ };+}diff --git a/src/next-step-defaults.js b/src/next-step-defaults.jsindex e75f3dca..49905b29 100644--- a/src/next-step-defaults.js+++ b/src/next-step-defaults.js@@ -1,5 +1,8 @@/** General CLI recovery text; operation-owned codes live in src/moves/ [P4,C7]. */export const DEFAULT_NEXT_STEPS = Object.freeze({+ "DECISION_HANDOFF_BINDING": "use the exact versioned handoff, namespaced source decision and original option set",+ "DECISION_HANDOFF_AUTH": "obtain authority for this exact question, answer or source query",+ "DECISION_HANDOFF_CONFLICT": "use the recorded answer or create a new source decision","GIT_SYNC_LOG": "restore the append-only refs/pullboard/board history on origin before running pullboard sync","GIT_SYNC_REMOTE": "restore read/write access to origin, then retry the original command or run pullboard sync; keep its pending sealed move","GIT_SYNC_LOCAL_CHANGED": "run pullboard export to preserve local moves, then ask the coordinator to reconcile the local and remote prefixes before syncing",diff --git a/test/decision-handoff.test.js b/test/decision-handoff.test.jsindex d47eeb51..0af1b7b5 100644--- a/test/decision-handoff.test.js+++ b/test/decision-handoff.test.js@@ -11,7 +11,9 @@ import { test } from 'node:test';/** The fixture capability authenticates the disclosed question, source, destination and option binding. */function signature(value) {const { authority, ...body } = value;- return createHmac('sha256', 'private-fixture-authority').update(JSON.stringify(body)).digest('hex');+ const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object'+ ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, canonical(child)])) : value;+ return createHmac('sha256', 'private-fixture-authority').update(JSON.stringify(canonical(body))).digest('hex');}test('a decision hand-off returns one matching answer to its source board, once [B21,H16]', async t => {@@ -31,13 +33,13 @@ test('a decision hand-off returns one matching answer to its source board, onceconst options = ['ship', 'wait'];const source = { boardId: 'source', decisionId: 17 };/** A separate capability is required for each exact disclosed destination and question. */- function offer(destinationBoardId, handoffId = destinationBoardId) {- const value = { version: 1, handoffId, source, destinationBoardId, requester: 'core-1',+ function offer(destinationBoardId, handoffId = destinationBoardId, ref = source) {+ const value = { version: 1, handoffId, source: ref, destinationBoardId, requester: 'core-1',question: 'Ship the reviewed change?', optionsDigest: optionsDigest(options), authority: '', answer: null };return { ...value, authority: signature(value) };}const signed = value => ({ ...value, authority: signature(value) });- const queryToken = participants => signature({ version: 1, source, participants });+ const queryToken = (participants, ref = source) => signature({ version: 1, source: ref, participants });const original = offer('child');const home = open('source'), away = open('child');await assert.rejects(away.deliver({ ...original, authority: 'forged' }, options), { code: 'DECISION_HANDOFF_AUTH' });@@ -49,6 +51,8 @@ test('a decision hand-off returns one matching answer to its source board, onceawait away.deliver(answered, options);assert.deepEqual(await home.deliver(answered, options), answered);assert.deepEqual(await home.deliver(answered, options), answered, 'an exact answer retry returns the same result');+ assert.deepEqual(await home.deliver(Object.fromEntries(Object.entries(answered).reverse()), options), answered,+ 'wire field order cannot change an idempotent delivery');assert.deepEqual(await home.deliver(original, options), answered, 'a late question cannot erase its answer');assert.deepEqual(await open('source').query(source, ['child'], queryToken(['child'])),{ complete: true, agreed: true, answers: [{ boardId: 'child', option: 'ship' }] }, 'reopening preserves correlation and one answer');@@ -66,6 +70,16 @@ test('a decision hand-off returns one matching answer to its source board, onceassert.equal(joint.complete, true);assert.equal(joint.agreed, false, 'different options never become a joint decision');assert.equal(joint.answers.length, 2);+ await assert.rejects(home.query(source, ['child'], queryToken(['child'])), { code: 'DECISION_HANDOFF_BINDING' },+ 'a caller cannot omit a known dissenting participant');+ const unanimous = { boardId: 'source', decisionId: 18 };+ for (const boardId of ['a', 'b']) {+ const request = offer(boardId, 'joint-' + boardId, unanimous);+ await home.deliver(signed({ ...request, answer: { boardId, option: 'ship' } }), options);+ }+ assert.equal((await home.query(unanimous, ['a', 'b'], queryToken(['a', 'b'], unanimous))).agreed, true);+ const foreign = offer('source', 'foreign-source', { boardId: 'peer', decisionId: 17 });+ assert.equal((await home.deliver(foreign, options)).source.boardId, 'peer', 'equal decision ids on different boards stay distinct');await assert.rejects(home.query(source, ['child'], 'forged'), { code: 'DECISION_HANDOFF_AUTH' });const early = offer('late', 'early-answer');const earlyAnswer = signed({ ...early, answer: { boardId: 'late', option: 'ship' } });