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(needs): a Pullboard block reaches whoever can clear it [C6,N26]
Corey Olsona5a27b5eb160
diff --git a/src/cli.js b/src/cli.jsindex 7a902224..97e5aca5 100644--- a/src/cli.js+++ b/src/cli.js@@ -36,6 +36,7 @@ import {mainLaneWork,reviewQueueLine,refuseNextIdle,+ reportBlock,} from './next-steps.js';import { reviewerStartup } from './next-steps.js';import { environmentAgent } from './relay-environment.js';@@ -2235,6 +2236,7 @@ async function runCommand(argv, io) {if (error instanceof Refused) {io.refusal?.(error);io.err(`pullboard: ${displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);+ noteBlock(io, error, command);return 1;}throw error;@@ -2285,6 +2287,13 @@ function rememberTrunk(io) {if (primary?.branch) trunkRef(info.root, primary.branch);}+/** Record a refusal that stopped a command, aimed at whoever can clear it [C6]. */+function noteBlock(io, error, command) {+ let info;+ try { info = repoInfo(io.cwd); } catch { return; /* Outside a repository there is no board to record on. */ }+ reportBlock(io, error, { command, info, now: io.clock?.now?.() ?? new Date() });+}+/** Run one command and emit its single versioned JSON result when requested (A1). */export async function main(argv, streams) {if (argv[0] === 'serve' && !startupMainTraced) {@@ -2331,6 +2340,7 @@ async function runMain(argv, streams) {if (!(error instanceof Refused)) throw error;io.refusal(error);io.err(`pullboard: ${displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);+ noteBlock(io, error, parsed.positionals[0]);io.flush(1);return 1;}diff --git a/src/commands/health.js b/src/commands/health.jsindex 8a62c18b..1cac784d 100644--- a/src/commands/health.js+++ b/src/commands/health.js@@ -1,4 +1,5 @@/** The pullboard health command, in its own module so an item adding another command never edits these lines. */+import { existsSync } from 'node:fs';import {boardHealth,healthLines,@@ -6,12 +7,70 @@ import {import {context,} from '../cli.js';+import { openBoardReadOnly } from '../board.js';+import { HEALTH_SENTINEL_ENGINE } from '../health-receipts.js';+import { recentBlocks } from '../needs-state.js';+import { rigorReport } from '../rigor.js';/** Run `pullboard health` and return its exit code. */export function run(io) {const ctx = context(io);const report = boardHealth(ctx.file, { root: ctx.info.root, config: ctx.config, now: ctx.clock.now() });+ report.blocks = blockReport(recentBlocks(ctx.info.commonDir, { clock: ctx.clock }), seatsByPath(ctx.file));io.result?.(report);for (const line of healthLines(report)) io.say(line);+ for (const line of blockLines(report.blocks)) io.say(line);return report.stuck.length ? 1 : 0;}++/** Each seat's id by its worktree path, so a block names who was stopped; a missing board names none. */+function seatsByPath(file) {+ if (!existsSync(file)) return new Map();+ const db = openBoardReadOnly(file);+ try { return new Map(db.prepare('SELECT agent_id, agent_path FROM agent').all().map(seat => [seat.agent_path, seat.agent_id])); }+ finally { db.close(); }+}++/**+ * The last day's blocks by code with counts, who was stopped, who can clear them, and a drafted+ * item for each code that repeated. Repeats are judged by Rigor's own repeat detection: each block+ * is read as a sentinel observation of the cause refusal:<CODE>, the shape Rigor already counts,+ * so a block repeats exactly when Rigor would call that cause repeated [D1,C6].+ *+ * @param {any[]} blocks+ * @param {Map<string, string>} seats+ */+export function blockReport(blocks, seats = new Map()) {+ const byCode = new Map();+ for (const block of blocks) {+ const entry = byCode.get(block.code) ?? { code: block.code, count: 0, audience: block.audience, reason: block.reason, step: block.step, commands: [], who: [], last: block.at };+ entry.count += 1;+ entry.last = block.at;+ const who = block.by === 'agent' ? seats.get(block.path) ?? 'an agent' : block.by;+ if (!entry.commands.includes(block.command)) entry.commands.push(block.command);+ if (!entry.who.includes(who)) entry.who.push(who);+ byCode.set(block.code, entry);+ }+ const events = blocks.map(block => ({ event_kind: 'health-failure', event_by: 'sentinel', item_id: null,+ event_detail: JSON.stringify({ cause: `refusal:${block.code}`, engine: HEALTH_SENTINEL_ENGINE }) }));+ const repeated = rigorReport(events, { person: 'person' }).causes.map(cause => cause.key.slice('refusal:'.length));+ const codes = [...byCode.values()].sort((a, b) => b.count - a.count || a.code.localeCompare(b.code));+ const drafts = codes.filter(entry => repeated.includes(entry.code)).map((entry) => {+ const title = `Pullboard blocked ${entry.count} requests in a day with ${entry.code}`;+ const brief = `${entry.commands.join(', ')} stopped ${entry.who.join(', ')}: ${entry.reason}. Step given: ${entry.step}. Make the block unnecessary or clear it on its own.`;+ const quote = (text) => `'${text.replaceAll("'", "'\\''")}'`;+ return { cause: `refusal:${entry.code}`, count: entry.count, lane: 'coordinator', title, brief,+ command: `pullboard add coordinator ${quote(title)} --brief ${quote(brief)}` };+ });+ return { window: '1d', codes, drafts };+}++/** The block report as lines: one per code with its count, then each drafted item; none on a quiet day [C6]. */+export function blockLines({ codes, drafts }) {+ // A quiet day adds nothing, so a clear board still reads as one line.+ if (!codes.length) return [];+ const clears = { person: 'the person', coordinator: 'the coordinator', agent: 'the agent that ran it' };+ return [`blocks in the last day: ${codes.reduce((sum, entry) => sum + entry.count, 0)}`,+ ...codes.map(entry => ` ${entry.code} ${entry.count}x on ${entry.commands.join(', ')}, stopped ${entry.who.join(', ')}; ${clears[entry.audience] ?? 'the agent'} clears it: ${entry.step}`),+ ...drafts.map(draft => ` repeated, draft an item: ${draft.command}`)];+}diff --git a/src/needs-state.js b/src/needs-state.jsindex 6b652f0b..c716bcd6 100644--- a/src/needs-state.js+++ b/src/needs-state.js@@ -16,6 +16,7 @@ import {undraftedRigor,} from './rigor-notices.js';import { personNeeds } from './needs.js';+import { readBlocks } from './refused.js';import { displayAgentName } from './agent-names.js';import {projectSpecApprovals,@@ -37,7 +38,7 @@ export function personNeedsState(root, { board: providedBoard = null, includeRigconst state = projectSpecApprovals(projectFit(pendingFit(info.commonDir), projectRowDecisions(decisions, projectState(root, { board }))), specApprovalState(root, { board, config }));const rows = projectRowDecisions(decisions, { root, spec: loadSpec(root, config).rows, practice: loadDoctrine(root, config).rows });const rigorDrafts = rigorDraftNeeds(rows);- const projected = { ...state, rigorDrafts, sentinelDrafts: sentinelDraftNeeds(sentinels(board)), ...(includeRigorUndrafted+ const projected = { ...state, rigorDrafts, sentinelDrafts: sentinelDraftNeeds(sentinels(board)), blocks: recentBlocks(info.commonDir, board), ...(includeRigorUndrafted? { rigorUndrafted: undraftedRigor(store.events(board), rows, { person: store.PERSON }) } : {}) };return { ...projected, needs: personNeeds(projected) };} finally {@@ -52,7 +53,13 @@ export function personNeedsSummary(root, { board, config }) {const projected = projectSpecApprovals({ ...rows,decisions: store.openDecisions(board, store.PERSON), holds: store.laneHolds(board),agents: store.listAgents(board).map(agent => ({ ...agent, displayName: displayAgentName(agent, config.agents.names) })),- rigorDrafts: rigorDraftNeeds(rows), sentinelDrafts: sentinelDraftNeeds(sentinels(board)),+ rigorDrafts: rigorDraftNeeds(rows), sentinelDrafts: sentinelDraftNeeds(sentinels(board)), blocks: recentBlocks(repoInfo(root).commonDir, board),}, specApprovalState(root, { board, config, spec }));return projected;}++/** The blocks recorded in the last day, by the board's clock, for Needs you and health [C6]. */+export function recentBlocks(commonDir, board) {+ const now = (board?.clock ?? store.systemClock).now();+ return readBlocks(commonDir, { since: new Date(now.getTime() - 86_400_000) });+}diff --git a/src/needs.js b/src/needs.jsindex 08caf81c..2886ba96 100644--- a/src/needs.js+++ b/src/needs.js@@ -5,6 +5,20 @@ export function personNeeds(state) {const agent = state.agents?.find(entry => entry.agent_id === id);return agent?.displayName || (agent ? `${id} (${agent.model || agent.agent_model || 'unknown'})` : id);};+ /**+ * Blocks only the person can clear, one row per rule and command with its plain reason and step,+ * newest first. Inside personNeeds because the page carries this function's source [C6].+ */+ const personBlocks = (blocks) => {+ const found = new Map();+ for (const block of blocks) {+ if (block.audience !== 'person') continue;+ const key = `${block.code} ${block.command}`;+ found.set(key, { kind: 'block', id: `block:${key}`, ref: 'blocked', count: (found.get(key)?.count ?? 0) + 1, at: block.at,+ text: `Pullboard stopped a request that only you can clear: ${block.reason}`, what: block.step });+ }+ return [...found.values()].sort((a, b) => b.at.localeCompare(a.at));+ };const rows = (state.spec ?? []).filter(row => !row.decision);const rigorDrafts = state.rigorDrafts ?? [];const drafts = rows.filter(row => (row.status === 'draft' || row.staleDecision) && !rigorDrafts.some(draft => draft.target === `spec:${row.id}`)).length;@@ -22,7 +36,9 @@ export function personNeeds(state) {text: `${row.id} is agent-approved; ${row.agentApproval.attribution}: ${row.agentApproval.agent}; commit ${row.agentApproval.commit ?? 'not committed'}`,what: 'confirm or decline this row', target: `spec:${row.id}`,actions: [{ verb: 'spec-approve', args: { ids: row.id } }, { verb: 'spec-decline', args: { ids: row.id } }] })),+ ...personBlocks(state.blocks ?? []),...(drafts ? [{ kind: 'draft', id: 'drafts', count: drafts, ref: String(drafts),text: 'draft spec rows to approve or drop' + rows.filter(row => row.staleDecision).map(row => `; ${row.stage}`).join(''), what: 'review in SPEC.md', target: 'tab:spec' }] : []),];}+diff --git a/src/next-steps.js b/src/next-steps.jsindex 3f25d007..298b6806 100644--- a/src/next-steps.js+++ b/src/next-steps.js@@ -8,7 +8,10 @@* every code raised in src/ has a row here.*/import { RECORDED_GENERIC_NEXT } from './recorded-refusal.js';-import { Refused } from './refused.js';+import {+ Refused,+ recordBlock,+} from './refused.js';/** Describe the queue's actual outstanding reviews and submission age [Q1,V15]. */export function reviewQueueLine(ctx, queue, span) {@@ -644,3 +647,80 @@ export function nextStepFor(error, message, options = {}) {return personRequestStep(stepInMessage(message) ?? NEXT_STEPS[code]?? `ask the service owner about refusal code ${code || '(unknown)'}, including the displayed refusal`, options);}++/** Refusals no move recovers from by itself: a typo is not Pullboard blocking anyone. */+const NOT_BLOCKS = new Set(['USAGE', 'UNKNOWN_COMMAND']);++/**+ * Who can take a refusal's step: the person (a person-only move), the coordinator (a step that+ * asks the coordinator), or the agent that ran the command. Read from the code and the same step+ * this catalog gives, so the audience never disagrees with the step shown [P4].+ *+ * @param {string} code+ * @param {string} message+ * @param {string} step+ * @returns {'person'|'coordinator'|'agent'}+ */+export function blockAudience(code, message, step) {+ const words = `${message}\n${step}`;+ if (/_PERSON_ONLY$|^B26_PERSON_CHANNEL$/u.test(code) || /\bonly the person\b|\blet the person act\b|\bbring it to the person\b/iu.test(words)) return 'person';+ if (/^(?:ask (?:the|your) coordinator|the coordinator\b)/iu.test(step) || /^COORDINATOR_ONLY$|_COORDINATOR_ONLY$/u.test(code)) return 'coordinator';+ return 'agent';+}++/** Plain words: no bracketed rule code, no backticks, one line [P4]. */+function plain(text) {+ return String(text).split('\n')[0].replace(/\[[A-Z][A-Z0-9_]*\]\s*/gu, '').replaceAll('`', '').replace(/\s+/gu, ' ').trim();+}++/**+ * One block from a refusal that stopped a command: its code, command, who was stopped, who can+ * clear it, and a plain one-line reason and step. Null for a usage slip, which blocks nobody.+ *+ * @param {{ code?: string, message: string, next?: string }} error+ * @param {{ command: string, by: string, path: string, at: Date, caller?: string }} context+ */+export function blockNotice(error, { command, by, path, at, caller }) {+ const code = typeof error?.code === 'string' ? error.code : 'INTERNAL';+ if (NOT_BLOCKS.has(code)) return null;+ const message = String(error.message).replace(/^\[[A-Z][A-Z0-9_]*\] /u, '');+ const step = plain(nextStepFor(error, message, { caller }));+ const first = plain(message);+ const cut = first.indexOf(step.slice(0, 24));+ const reason = (cut > 0 ? first.slice(0, cut) : first).replace(/[\s;:,.]+$/u, '') || first;+ return { at: at.toISOString(), code, command: `pullboard ${command}`.trim(), by, path,+ audience: blockAudience(code, message, step), reason, step };+}++/**+ * The line a stopped command prints after its refusal, aimed at whoever can take the step. The+ * agent's own step is already the refusal's next line, so only a step for someone else adds one.+ *+ * @param {ReturnType<typeof blockNotice>} block+ * @returns {string | null}+ */+export function blockLine(block) {+ if (block?.audience === 'person') return 'pullboard: only the person can clear this; it is in their Needs you list now';+ if (block?.audience === 'coordinator') return `pullboard: only the coordinator can clear this; tell them: pullboard shout coordinator "blocked by ${block.code} on ${block.command}: ${block.reason.replaceAll('"', "'")}"`;+ return null;+}++/**+ * Record a refusal that stopped a command and print the line aimed at whoever can clear it. A+ * ledger that cannot be written says so; it never hides the refusal it was recording.+ *+ * @param {any} io+ * @param {{ code?: string, message: string, next?: string }} error+ * @param {{ command: string, info: { commonDir: string, root: string, isMain: boolean }, now: Date }} context+ */+export function reportBlock(io, error, { command, info, now }) {+ const caller = io.callerRole?.();+ const block = blockNotice(error, { command, at: now, path: info.root, caller,+ by: caller === 'person' ? 'person' : info.isMain ? 'coordinator' : 'agent' });+ if (!block) return null;+ 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);+ if (line) io.err(line);+ return block;+}diff --git a/src/refused.js b/src/refused.jsindex 388d28eb..18577d73 100644--- a/src/refused.js+++ b/src/refused.js@@ -1,3 +1,6 @@+import { appendFileSync, existsSync, readFileSync } from 'node:fs';+import { join } from 'node:path';+/*** A refused move: a rule said no. The code names the rule; the message says what to do next (P4).*/@@ -14,3 +17,43 @@ export class Refused extends Error {if (typeof next === 'string' && next.trim()) this.next = next.trim();}}++/** 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');++/**+ * Append one block: its code, the command, who was stopped, who can clear it, and the plain reason+ * and step. A ledger beside the board, not a board event, so recording a block never needs the+ * board's lock or changes what the event log replays.+ *+ * @param {string} commonDir+ * @param {{ at: string, code: string, command: string, by: string, path: string, audience: string, reason: string, step: string }} block+ */+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');+ return true;+}++/**+ * The blocks recorded at or after `since`, oldest first. A torn last line from a crash is skipped.+ *+ * @param {string} commonDir+ * @param {{ since?: Date }} [options]+ * @returns {any[]}+ */+export function readBlocks(commonDir, { since } = {}) {+ const file = join(commonDir, BLOCKS_FILE);+ if (!existsSync(file)) return [];+ const from = since ? since.getTime() : -Infinity;+ const blocks = [];+ 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);+ }+ return blocks;+}diff --git a/test/blocks.test.js b/test/blocks.test.jsnew file mode 100644index 00000000..2f1af186--- /dev/null+++ b/test/blocks.test.js@@ -0,0 +1,55 @@+/** A refusal that stops someone reaches whoever can clear it, is recorded, and repeats are counted [C6,N26]. */+import assert from 'node:assert/strict';+import { after, test } from 'node:test';+import { personNeedsState } from '../src/needs-state.js';+import { createE2eHelpers } from './e2e-helpers.js';++const e2e = createE2eHelpers();+after(e2e.cleanup);++test('a Pullboard block reaches whoever can clear it and repeats are counted [C6,N26]', () => {+ const box = e2e.project();++ // A person-only move from an agent's terminal: the person, not the agent, can clear it.+ box.env.CLAUDECODE = '1';+ const person = box.run(box.repo, 'answer', '1', 'yes', '--as', 'person');+ delete box.env.CLAUDECODE;+ assert.equal(person.code, 1, person.err);+ assert.match(person.err, /^pullboard: only the person can clear this; it is in their Needs you list now$/mu);+ const needs = personNeedsState(box.repo).needs.filter(row => row.kind === 'block');+ assert.equal(needs.length, 1, JSON.stringify(needs));+ assert.equal(needs[0].text, 'Pullboard stopped a request that only you can clear: this terminal belongs to an agent');+ assert.match(needs[0].what, /^run pullboard view\b/u);+ assert.doesNotMatch(`${needs[0].text} ${needs[0].what}`, /\[[A-Z][A-Z0-9_]*\]|B26|relay|--/u);++ // An agent's coordinator-only move: the agent is told to take it to the coordinator.+ for (let attempt = 0; attempt < 3; attempt += 1) {+ const held = box.run(box.web, 'hold', 'api', '--reason', 'the api lane waits');+ assert.equal(held.code, 1, held.err);+ assert.match(held.err, /\[COORDINATOR_ONLY\]/u);+ assert.match(held.err, /^pullboard: only the coordinator can clear this; tell them: pullboard shout coordinator "blocked by COORDINATOR_ONLY on pullboard hold: only the coordinator holds a lane"$/mu);+ }+ // An agent's block is not the person's call.+ assert.equal(personNeedsState(box.repo).needs.filter(row => row.kind === 'block').length, 1);++ // Health counts the day's blocks by code and drafts an item for the one that repeated.+ const report = JSON.parse(box.run(box.repo, 'health', '--json').out);+ const byCode = Object.fromEntries(report.blocks.codes.map(entry => [entry.code, entry]));+ assert.equal(byCode.COORDINATOR_ONLY.count, 3);+ assert.deepEqual(byCode.COORDINATOR_ONLY.commands, ['pullboard hold']);+ assert.deepEqual(byCode.COORDINATOR_ONLY.who, ['web-1']);+ assert.equal(byCode.COORDINATOR_ONLY.audience, 'coordinator');+ assert.equal(byCode.B26_PERSON_CHANNEL.count, 1);+ assert.deepEqual(byCode.B26_PERSON_CHANNEL.who, ['coordinator']);+ assert.deepEqual(report.blocks.drafts.map(draft => draft.cause), ['refusal:COORDINATOR_ONLY']);+ const [draft] = report.blocks.drafts;+ assert.equal(draft.title, 'Pullboard blocked 3 requests in a day with COORDINATOR_ONLY');+ const text = box.run(box.repo, 'health').out;+ assert.match(text, /^ {2}COORDINATOR_ONLY 3x on pullboard hold, stopped web-1; the coordinator clears it: ask the coordinator/mu);+ assert.match(text, /^ {2}repeated, draft an item: pullboard add coordinator 'Pullboard blocked 3 requests in a day with COORDINATOR_ONLY'/mu);++ // The drafted item files as it reads.+ const added = box.run(box.repo, 'add', draft.lane, draft.title, '--brief', draft.brief, '--json');+ assert.equal(added.code, 0, added.err);+ assert.equal(JSON.parse(added.out).item.item_title, draft.title);+});