Skip to content

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.

fix(blocks): clear completed moves for their audience [C6,N26]

Corey Olsonca1a4f6542e7
diff --git a/src/blocks.js b/src/blocks.js
index d12402da..d028036b 100644
--- a/src/blocks.js
+++ b/src/blocks.js
@@ -5,6 +5,12 @@ import {
readFileSync,
} from 'node:fs';
import { join } from 'node:path';
+import {
+ createHash,
+ randomUUID,
+} from 'node:crypto';
+import { requirePersonChannel } from './person.js';
+import { repoInfo } from './git.js';
/** The ledger of refusals that stopped someone's command, beside the board in Git's common folder. */
export const BLOCKS_FILE = join('pullboard', 'blocks.jsonl');
@@ -21,7 +27,7 @@ export function recordBlock(commonDir, block) {
const folder = join(commonDir, 'pullboard');
// A repository without a board has no ledger yet; the refusal itself still prints.
if (!existsSync(folder)) return false;
- appendFileSync(join(commonDir, BLOCKS_FILE), JSON.stringify(block) + '\n');
+ appendFileSync(join(commonDir, BLOCKS_FILE), JSON.stringify({ ...block, ...(block.moveKey ? { id: randomUUID() } : {}) }) + '\n');
return true;
}
@@ -36,14 +42,80 @@ export function readBlocks(commonDir, { since } = {}) {
const file = join(commonDir, BLOCKS_FILE);
if (!existsSync(file)) return [];
const from = since ? since.getTime() : -Infinity;
- const blocks = [];
+ const blocks = new Map();
+ let legacy = 0;
for (const line of readFileSync(file, 'utf8').split('\n')) {
if (!line.trim()) continue;
let block;
try { block = JSON.parse(line); } catch { continue; /* A torn line from an interrupted append carries no block. */ }
- if (typeof block?.code === 'string' && Date.parse(block.at) >= from) blocks.push(block);
+ if (block?.kind === 'clear' && Array.isArray(block.ids)) {
+ for (const id of block.ids) {
+ const previous = blocks.get(id);
+ const pending = previous?.moveKeys?.filter(move => !block.moveKeys?.includes(move));
+ if (block.moveKeys && pending?.length) blocks.set(id, { ...previous, moveKeys: pending });
+ else blocks.delete(id);
+ }
+ } else if (typeof block?.code === 'string') blocks.set(block.id ?? `legacy:${legacy++}`, block);
}
- return blocks;
+ return [...blocks.values()].filter(block => Date.parse(block.at) >= from);
+}
+
+/** Hash a local matching key; command text, argument bodies and credentials never enter the ledger. */
+function key(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+
+/** The command branch and its target, excluding prose and option values. */
+export function blockMoveKey(io) {
+ const command = io.relayCommand;
+ if (!command) return null;
+ const name = command.cliOperation;
+ const words = command.positionals ?? [];
+ const branches = new Set(['spec', 'doctrine', 'sentinel', 'runner', 'relay', 'lane', 'milestone', 'hook', 'settings']);
+ const verb = name === 'hold' ? command.values?.off ? 'off' : 'on'
+ : name === 'land' && command.values?.waive !== undefined ? 'waive'
+ : ['verify', 'fact'].includes(name) ? words[1] ?? ''
+ : name === 'check' && words[0] === 'accept' ? 'accept' : branches.has(name) ? words[0] ?? '' : '';
+ const targets = new Set(['answer', 'claim', 'submit', 'verify', 'check', 'show', 'release', 'withdraw', 'merged', 'fact', 'escalate', 'hold', 'shout']);
+ let target = targets.has(name) || /^#?\d+$/u.test(words[0] ?? '') ? words[0] ?? '' : '';
+ if (name === 'check' && verb === 'accept') target = words[1] ?? '';
+ if (name === 'next' && command.values?.verifyId !== undefined) target = String(command.values.verifyId);
+ if (name === 'spec' && ['approve', 'decline'].includes(verb)) {
+ target = [...new Set(words.slice(1).flatMap(word => word.split(/[\s,]+/u)).filter(Boolean))].sort().join(',');
+ } else if (name === 'spec' && verb === 'answer' || name === 'sentinel' || name === 'runner') target = words[1] ?? '';
+ if (/^#?\d+$/u.test(target)) target = String(Number(target.replace(/^#/u, '')));
+ return key({ command: name, verb, item: target });
+}
+
+/** A multirow refusal completes only after every target has its own later successful move. */
+export function blockMoveKeys(io) {
+ const command = io.relayCommand;
+ if (command?.cliOperation === 'spec' && ['approve', 'decline'].includes(command.positionals?.[0])) {
+ return [...new Set(command.positionals.slice(1).flatMap(word => word.split(/[\s,]+/u)).filter(Boolean))]
+ .map(id => blockMoveKey({ relayCommand: { ...command, positionals: [command.positionals[0], id] } }));
+ }
+ const move = blockMoveKey(io);
+ return move ? [move] : [];
+}
+
+/** Agent blocks belong to that checkout's seat; person and coordinator blocks belong to this board. */
+export function blockOwner(audience, info) {
+ return audience === 'agent' ? key({ audience, seat: info.root }) : audience;
+}
+
+/** Record only the matching completed move's clear, leaving later or unrelated blocks intact. */
+export function clearCompletedBlocks(io, now = io.clock?.now?.() ?? new Date()) {
+ let info;
+ try { info = repoInfo(io.cwd); } catch { return; }
+ const moveKeys = blockMoveKeys(io);
+ if (!moveKeys.length) return;
+ const owners = new Set([blockOwner('agent', info)]);
+ if (info.isMain) owners.add('coordinator');
+ try { requirePersonChannel(io.personChannel); owners.add('person'); } catch { /* An agent's success cannot clear a person's block. */ }
+ try {
+ const ids = readBlocks(info.commonDir).filter(block => block.id && (block.moveKeys ?? [block.moveKey]).some(move => moveKeys.includes(move))
+ && owners.has(block.owner) && Date.parse(block.at) <= now.getTime()).map(block => block.id);
+ if (!ids.length) return;
+ appendFileSync(join(info.commonDir, BLOCKS_FILE), JSON.stringify({ kind: 'clear', at: now.toISOString(), ids, moveKeys }) + '\n');
+ } catch (error) { io.err(`pullboard: the move completed, but its earlier block could not be cleared (${error.message})`); }
}
/**
diff --git a/src/cli.js b/src/cli.js
index ce81c431..c6cf931c 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -37,8 +37,9 @@ import {
reviewQueueLine,
refuseNextIdle,
reportBlock,
+ reviewerStartup,
} from './next-steps.js';
-import { reviewerStartup } from './next-steps.js';
+import { clearCompletedBlocks } from './blocks.js';
import { environmentAgent } from './relay-environment.js';
import { judgeTrunkMove } from './verdict-trunk.js';
import * as gateReceipt from './gate-receipt.js';
@@ -430,7 +431,6 @@ function closestHelpCommand(input) {
};
return Object.keys(HELP.commands).sort((a, b) => distance(needle, a) - distance(needle, b) || a.localeCompare(b))[0];
}
-
/** Render one command's usage, one-line flags and a pasteable example from the help declaration. */
function commandHelp(name) {
const entry = HELP.commands[name];
@@ -728,7 +728,6 @@ export function personMode(ctx, me, values) {
}
return true;
}
-
/**
* Refuse a build item in a lane that owns no files, such as review: whoever claims it there can
* commit nothing, so the item strands its builder. A review item, one that waits on the work it
@@ -2376,6 +2375,7 @@ async function runMain(argv, streams) {
if (code === 0) await checkoutSession?.finish?.();
if (sync && code === 0) await retry();
const status = io.exitCode(code);
+ if (status === 0 && !parsed?.values.help && !parsed?.values.version && !parsed?.values['dry-run']) clearCompletedBlocks(io);
io.flush(status);
return status;
} finally {
diff --git a/src/next-steps.js b/src/next-steps.js
index c448c5d7..c1fc3f74 100644
--- a/src/next-steps.js
+++ b/src/next-steps.js
@@ -9,7 +9,12 @@
*/
import { RECORDED_GENERIC_NEXT } from './recorded-refusal.js';
import { Refused } from './refused.js';
-import { recordBlock } from './blocks.js';
+import {
+ blockMoveKey,
+ blockMoveKeys,
+ blockOwner,
+ recordBlock,
+} from './blocks.js';
import { repoInfo } from './git.js';
/** Describe the queue's actual outstanding reviews and submission age [Q1,V15]. */
@@ -751,6 +756,8 @@ export function reportBlock(io, error, { command, info: given, now = io.clock?.n
const block = blockNotice(error, { command, at: now, path: info.root, caller,
by: caller === 'person' ? 'person' : info.isMain ? 'coordinator' : 'agent' });
if (!block) return null;
+ const moveKey = blockMoveKey(io);
+ if (moveKey) Object.assign(block, { moveKey, moveKeys: blockMoveKeys(io), owner: blockOwner(block.audience, info) });
try { recordBlock(info.commonDir, block); }
catch (failure) { io.err(`pullboard: this block was not recorded (${failure.message}); the refusal above still stands`); }
const line = blockLine(block);
diff --git a/test/blocks.test.js b/test/blocks.test.js
index afb004cc..8e604129 100644
--- a/test/blocks.test.js
+++ b/test/blocks.test.js
@@ -11,12 +11,102 @@ import {
reportBlock,
} from '../src/next-steps.js';
import { Refused } from '../src/refused.js';
+import {
+ personBlockWords,
+ readBlocks,
+} from '../src/blocks.js';
import { relayPresentation } from '../src/relay-presentation.js';
import { createE2eHelpers } from './e2e-helpers.js';
const e2e = createE2eHelpers();
after(e2e.cleanup);
+test('a block clears when its audience completes the same move [C6,N26]', async t => {
+ const box = e2e.project();
+ const ask = text => {
+ const result = box.run(box.repo, 'shout', 'person', text, '--decision', '--json');
+ assert.equal(result.code, 0, `${result.err}\n${result.out}`);
+ return JSON.parse(result.out).id;
+ };
+ const first = ask('First choice?');
+ const second = ask('Another choice?');
+ const info = repoInfo(box.repo);
+ box.env.CLAUDECODE = '1';
+ const blocked = box.run(box.repo, 'answer', String(first), 'yes', '--as', 'person');
+ assert.equal(blocked.code, 1, blocked.err);
+ const needs = () => personNeedsState(box.repo).needs.filter(row => row.kind === 'block');
+ assert.equal(needs().length, 1, 'the stopped person move appears in Needs you');
+ const api = await serveApi({ secret: 'blocks-test', runCommand: async () => 0, isMain: true,
+ projects: () => [{ root: box.repo, name: 'blocks-clear', project: '', added: '2026-10-22T00:00:00.000Z' }] });
+ t.after(() => api.close());
+ assert.equal((await apiNeeds(api, box.repo)).blocks.length, 1, 'the API caches the initial block');
+ const wrongActor = box.run(box.repo, 'answer', String(first), 'agent answer');
+ assert.equal(wrongActor.code, 1, wrongActor.err);
+ assert.ok(readBlocks(info.commonDir).some(block => block.owner === 'coordinator'),
+ 'the refused default answer leaves a coordinator-audience block');
+ assert.ok(needs().length > 0, 'a different actor cannot clear the person move');
+ delete box.env.CLAUDECODE;
+ for (const option of ['--help', '--version']) {
+ const informational = box.run(box.repo, 'answer', String(first), option);
+ assert.equal(informational.code, 0, informational.err);
+ assert.ok(needs().length > 0, `${option} does not complete the stopped move`);
+ }
+ const other = box.run(box.repo, 'answer', String(second), 'yes', '--as', 'person');
+ assert.equal(other.code, 0, other.err);
+ assert.ok(needs().length > 0, 'success on another item leaves the first block');
+ const completed = box.run(box.repo, 'answer', String(first), 'yes', '--as', 'person');
+ assert.equal(completed.code, 0, completed.err);
+ assert.deepEqual(needs(), [], 'the matching completed move clears Needs you at once');
+ assert.deepEqual((await apiNeeds(api, box.repo)).blocks, [], 'the clear invalidates the cached API projection');
+ const health = JSON.parse(box.run(box.repo, 'health', '--json').out);
+ assert.deepEqual(health.blocks.codes, [], 'health no longer counts resolved blocks');
+ assert.deepEqual(readBlocks(info.commonDir), [], 'the active ledger view excludes explicit clears');
+
+ const waiting = ask('Still waiting?');
+ box.env.CLAUDECODE = '1';
+ assert.equal(box.run(box.repo, 'answer', String(waiting), 'yes', '--as', 'person').code, 1);
+ delete box.env.CLAUDECODE;
+ assert.equal(personBlockWords(info.commonDir, new Date()).length, 1, 'an unmatched block remains');
+ assert.equal(personBlockWords(info.commonDir, new Date(Date.now() + 86_400_001)).length, 0,
+ 'an unmatched block still expires after 24 hours');
+
+ const specBox = e2e.project();
+ const specInfo = repoInfo(specBox.repo);
+ specBox.env.CLAUDECODE = '1';
+ const blockedSet = specBox.run(specBox.repo, 'spec', 'approve', 'G1,G2');
+ assert.equal(blockedSet.code, 1, blockedSet.err);
+ delete specBox.env.CLAUDECODE;
+ assert.equal(readBlocks(specInfo.commonDir).length, 1, 'the two-row approval is one stopped move');
+ const firstRow = specBox.run(specBox.repo, 'spec', 'approve', 'G1');
+ assert.equal(firstRow.code, 0, `${firstRow.err}\n${firstRow.out}`);
+ assert.equal(readBlocks(specInfo.commonDir).length, 1, 'one completed target leaves the other pending');
+ const secondRow = specBox.run(specBox.repo, 'spec', 'approve', 'G2');
+ assert.equal(secondRow.code, 0, `${secondRow.err}\n${secondRow.out}`);
+ assert.deepEqual(readBlocks(specInfo.commonDir), [], 'separate later successes complete the blocked set');
+});
+
+test('a successful edit clears only its own item [C6]', () => {
+ const box = e2e.project();
+ const add = title => {
+ const result = box.run(box.repo, 'add', 'web', title, '--json');
+ assert.equal(result.code, 0, `${result.err}\n${result.out}`);
+ return JSON.parse(result.out).item.item_id;
+ };
+ const first = add('First item');
+ const second = add('Second item');
+ const info = repoInfo(box.repo);
+ const blocked = box.run(box.repo, 'edit', String(second), '--route', 'not-a-route');
+ assert.equal(blocked.code, 1, blocked.err);
+ const before = readBlocks(info.commonDir);
+ assert.equal(before.length, 1, 'the refused edit is recorded');
+ const unrelated = box.run(box.repo, 'edit', String(first), '--brief', 'First updated');
+ assert.equal(unrelated.code, 0, unrelated.err);
+ assert.equal(readBlocks(info.commonDir).length, 1, 'editing another item leaves the blocked edit');
+ const completed = box.run(box.repo, 'edit', `#${second}`, '--brief', 'Second updated');
+ assert.equal(completed.code, 0, completed.err);
+ assert.deepEqual(readBlocks(info.commonDir), [], 'the same item clears across its accepted #id spelling');
+});
+
/** Needs you as the local API serves it, read in full so every person call is present. */
async function apiNeeds(api, root) {
const headers = { 'x-pullboard-key': 'blocks-test' };