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): one decision list across a project's repos [N34]
Corey Olsonbb774972702f
diff --git a/docs/api.md b/docs/api.mdindex 3c1e99b5..da9098f6 100644--- a/docs/api.md+++ b/docs/api.md@@ -6,6 +6,8 @@ The API version is independent of the package version. Its contract is stable wiDecision shouts without a recipient go to the agent's coordinator, or to `person` when sent by the coordinator. An agent may answer a decision sent to its own lane; the reply names that agent and goes to the original asker. An agent in another lane gets `NOT_YOUR_DECISION`. `pullboard pass <shout-id> <note>` is for coordinators: it forwards an open coordinator decision to the person with the original question and note. From the main checkout, `pullboard decisions` and `pullboard answer <shout-id> <text>` default to the coordinator; use `--as person` to select the person's queue or answer a person-addressed decision. Person mode is accepted only in the main checkout. An answer in person mode cannot answer a coordinator-addressed decision, and a coordinator-default answer cannot impersonate the person; the refusal prints the command to retry. A person answer is delivered to the original asker. An agent worktree cannot select person mode.+In a repo whose `pullboard.json` names a `project`, `pullboard decisions --as person` lists the open person decisions of every registered repo of that project, each named `repo#id`, and `pullboard answer repo#id <text> --as person` answers one on its own board, so the decision closes there and nowhere else. Its JSON carries `project` and each decision's `repo`; a repo whose board cannot be read is named in `unreadable` and the others still list. `GET /api/v1/decisions?board=<id>` returns the same list from the local API: `{version, project, decisions}` for the project of the named registered board, with each decision's `board` id and `repo`; without a project it lists that board alone. Answer through that board's `moves` path.+A successful command returns the fields listed below. `version` is always the number `1`. The catalog lists required top-level fields; nested objects and arrays are command data, and optional top-level fields may be added.`pullboard settings` reads machine-wide settings from the OS account's `~/.pullboard/settings.json`; the gate queue database is beside it. This location does not follow `HOME` or `PULLBOARD_HOME`, so agents with private board homes still share one machine gate limit. Set `PULLBOARD_MACHINE_HOME` to an explicit directory only when a separate private machine settings and gate pool is intended; tests use this override. `pullboard settings gateSlots <n>` changes the gate queue capacity, which defaults to `2`. Raising gate or browser capacity takes effect immediately, even with holders and waiters: settings and the durable queue limit change under the same lock, and existing waiters observe the new limit. Lowering capacity is refused while that resource has holders or waiters; the refusal names its live holders and leaves their leases, settings and queue order intact. Retry the decrease after the resource becomes idle.diff --git a/src/api-http.js b/src/api-http.jsindex 127aad29..545ae8cb 100644--- a/src/api-http.js+++ b/src/api-http.js@@ -253,6 +253,11 @@ export function createApiHandler(adapter, { pollMs = 200, tagState = false } = {if (typeof adapter.settings !== 'function') throw new Refused('SETTINGS_NOT_AVAILABLE', 'read machine and repository settings from the local API');return json(res, 200, await adapter.settings(url.searchParams.get('board'), who));}+ if (url.pathname === '/api/v1/decisions') {+ if (req.method !== 'GET') throw new Refused('READ_ONLY', "list decisions with GET; answer one through its own board's moves path");+ if (typeof adapter.decisions !== 'function') throw new Refused('DECISIONS_NOT_AVAILABLE', "this API adapter does not list a project's decisions; read each board's state, which carries its own");+ return json(res, 200, await adapter.decisions(url.searchParams.get('board'), who));+ }if (req.method === 'GET' && url.pathname === '/api/v1/boards') {const listing = await adapter.boards(who);return json(res, 200, Array.isArray(listing) ? { boards: listing } : listing);diff --git a/src/api.js b/src/api.jsindex f64867ac..8f25de06 100644--- a/src/api.js+++ b/src/api.js@@ -758,6 +758,32 @@ export function apiBoardListing(projects = listApiProjects, isMain) {return { boards, warnings };}+/**+ * Every open person decision of the project the named board belongs to, each with its board id+ * and repo; a board outside any project lists alone. An unreadable member is named, not fatal [N34].+ *+ * @param {string | null} selected a registered board id+ * @param {() => { root: string, name: string, project: string }[]} projects+ * @param {boolean | undefined} isMain+ * @returns {{ version: 1, project: string, decisions: object[], unreadable: string[] }}+ */+function projectDecisionListing(selected, projects, isMain) {+ if (!selected) throw new Refused('BAD_REQUEST', 'name a registered board with ?board=<id> from GET /api/v1/boards');+ const home = findBoard(selected, projects, isMain);+ const members = home.project ? projects().filter((entry) => entry.project === home.project) : [home];+ const decisions = [];+ const unreadable = [];+ for (const member of members) {+ try {+ withReadBoard(member.root, (board) => {+ const id = store.boardId(board);+ for (const ask of store.openDecisions(board, store.PERSON)) decisions.push({ ...ask, board: id, repo: member.name });+ }, isMain);+ } catch { unreadable.push(member.name); }+ }+ return { version: 1, project: home.project ?? '', decisions, unreadable };+}+/** Resolve only registered boards, so a request cannot open an arbitrary path on the machine. */function findBoard(id, projects, isMain) {// Each request resolves its board, so this opens boards read-only and stops at the match (#1040).@@ -1152,6 +1178,7 @@ export function createLocalApiHandler({ secret, getPort, runCommand, projects =},settings: (selected) => settingsInventory(settingsScope.projects(), selected),boards: () => withGitReadFacts(() => apiBoardListing(apiProjects, codeIsMain)),+ decisions: (selected) => withGitReadFacts(() => projectDecisionListing(selected, apiProjects, codeIsMain)),board: (id) => withGitReadFacts(() => findBoard(id, apiProjects, codeIsMain)),state: (board, who, seen, options) => withGitReadFacts(() => localState(board, seen, options).state),stateJson: (board, who, seen, options) => withGitReadFacts(() => {diff --git a/src/commands/answer.js b/src/commands/answer.jsindex 26809178..a8902341 100644--- a/src/commands/answer.js+++ b/src/commands/answer.js@@ -1,5 +1,10 @@/** The pullboard answer command, in its own module so an item adding another command never edits these lines. */+import { basename } from 'node:path';import * as store from '../board.js';+import {+ projectSiblings,+ resolveSibling,+} from '../project-decisions.js';import {parseImplies,} from '../implies.js';@@ -11,6 +16,7 @@ import {} from '../person.js';import {actOn,+ context,agentDisplayName,idArg,ordered,@@ -19,6 +25,18 @@ import {/** Run `pullboard answer` and return its exit code. */export async function run(io, { first, second, rest, values }) {+ const reference = /^(.+)#([1-9]\d*)$/u.exec(first ?? '');+ if (reference) {+ // repo#id names a decision on another repo of this project; the answer runs on that repo's own board [N34].+ const ctx = context(io);+ const here = ctx.config.name ?? basename(ctx.info.root);+ if (reference[1] !== here) {+ const sibling = resolveSibling(reference[1], projectSiblings(ctx.info.root, ctx.config));+ const there = Object.create(io, { cwd: { value: sibling.root } });+ return run(there, { first: reference[2], second, rest, values });+ }+ return run(io, { first: reference[2], second, rest, values });+ }const act = (work) => actOn(io, work);return act(async (ctx, board, me) => {const asPerson = personMode(ctx, me, values);diff --git a/src/commands/decisions.js b/src/commands/decisions.jsindex 38ea3d4e..caad0d9c 100644--- a/src/commands/decisions.js+++ b/src/commands/decisions.js@@ -1,5 +1,10 @@/** The pullboard decisions command, in its own module so an item adding another command never edits these lines. */+import { basename } from 'node:path';import * as store from '../board.js';+import {+ projectPersonDecisions,+ projectSiblings,+} from '../project-decisions.js';import {agentDisplayName,context,@@ -10,14 +15,31 @@ import {withBoardRead,} from '../cli.js';-/** Run `pullboard decisions` and return its exit code. */+/**+ * Run `pullboard decisions` and return its exit code. As the person, a repo that belongs to a+ * project lists every sibling repo's open decisions too, each named repo#id so `pullboard answer+ * repo#id` closes it on its own board [N34].+ */export function run(io, { values }) {const ctx = context(io);- const { asks, agents } = withBoardRead(ctx, (board) => {+ const siblings = projectSiblings(ctx.info.root, ctx.config);+ const { asks, agents, project, asPerson } = withBoardRead(ctx, (board) => {const me = whoAmI(ctx, board);const asPerson = personMode(ctx, me, values);- return { asks: store.openDecisions(board, asPerson ? 'person' : [me.id, me.lane]), agents: store.listAgents(board) };+ if (asPerson && siblings.length) {+ return { project: projectPersonDecisions(ctx.info.root, ctx.config.name ?? basename(ctx.info.root), board, siblings), asPerson };+ }+ return { asks: store.openDecisions(board, asPerson ? 'person' : [me.id, me.lane]), agents: store.listAgents(board), asPerson };});+ if (project) {+ io.result?.({ project: ctx.config.project, decisions: project.decisions.map((entry) => entry.ask), ...(project.unreadable.length ? { unreadable: project.unreadable } : {}) });+ if (!project.decisions.length) io.say('no open decisions');+ for (const { ask, repo, agents: repoAgents, config } of project.decisions) {+ io.say(`${repo}#${ask.shout_id} ${agentDisplayName(repoAgents, config ?? ctx.config, ask.shout_from)} -> ${agentDisplayName(repoAgents, config ?? ctx.config, ask.shout_to)}, ${span(ctx, ask.shout_at)} ago: ${firstLine(ask.shout_text)}`);+ }+ for (const name of project.unreadable) io.err(`could not read ${name}'s board; its decisions are not listed`);+ return 0;+ }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)}`);diff --git a/src/help.js b/src/help.jsindex d0c4f44a..6640a9d5 100644--- a/src/help.js+++ b/src/help.js@@ -167,14 +167,16 @@ WorkInbox combines direct coordination with item/dependency, file and cited-row activity; other lane activity is summarized.pullboard shout [<to>] <text> --decision ask for a decision; defaults to your coordinator or the personpullboard shout <to> <text> --evidence attempt|receipt --outcome <word> --item <id> --commit <rev>- pullboard answer <shout-id> <text> [--as person]+ pullboard answer <shout-id|repo#id> <text> [--as person]answer your decision; person mode is main-checkout only+ repo#id answers a sibling repo's decision on its own boardOther options: [--implies <ids>] [--supersedes <answer-id>][--origin person-relayed|agent|inherited] [--rationale <why>]--supersedes tells the items an earlier answer implied; only the personsupersedes the person's answerpullboard pass <shout-id> <note> coordinator passes a decision to the personpullboard decisions [--as person] shouts waiting for you; main checkout defaults to coordinator+ as the person, a project's repos list together as repo#idpullboard watch [--to <agent|lane|all>] [--kinds <kinds>] [--item <id>] [--since <sequence>] [--json][--work <lane>] [--review-wait <minutes>]follow the board's live events, one line each as it happens, with or without the viewdiff --git a/src/project-decisions.js b/src/project-decisions.jsnew file mode 100644index 00000000..045d29b3--- /dev/null+++ b/src/project-decisions.js@@ -0,0 +1,80 @@+/**+ * One decision list across a project's repos [N34]. A project is the set of registered repos whose+ * pullboard.json names the same non-empty "project"; each repo keeps its own board, so this only+ * reads the sibling boards and never writes one.+ */+import {+ basename,+ join,+ resolve,+} from 'node:path';+import * as store from './board.js';+import { loadConfig } from './config.js';+import { repoInfo } from './git.js';+import { listApiProjects } from './projects.js';+import { Refused } from './refused.js';++/**+ * The other registered repos of this config's project, in registry order.+ *+ * @param {string} root this repo's root+ * @param {{ project?: string }} config this repo's config+ * @param {() => { root: string, name: string, project: string }[]} [projects] the registry reader+ * @returns {{ root: string, name: string }[]} empty when the config names no project+ */+export function projectSiblings(root, config, projects = listApiProjects) {+ if (!config?.project) return [];+ const here = resolve(root);+ return projects()+ .filter((entry) => entry.project === config.project && resolve(entry.root) !== here)+ .map((entry) => ({ root: resolve(entry.root), name: entry.name ?? basename(entry.root) }));+}++/**+ * Resolve the repo part of a repo#id reference to a sibling of this project. A name that matches+ * more than one sibling, or none, refuses with the next step, because answering the wrong board+ * would close somebody else's decision.+ *+ * @param {string} repo a registered name or folder name+ * @param {{ root: string, name: string }[]} siblings+ * @returns {{ root: string, name: string }}+ */+export function resolveSibling(repo, siblings) {+ const found = siblings.filter((entry) => entry.name === repo || basename(entry.root) === repo);+ if (found.length === 1) return found[0];+ throw new Refused(found.length ? 'REPO_AMBIGUOUS' : 'NO_REPO',+ `${found.length ? 'more than one' : 'no'} repo of this project is named ${repo}; run pullboard decisions --as person to see each repo's name`);+}++/**+ * Every open person decision of this repo and of each sibling repo, as `{ ask, repo, root, agents, config }` with the repo also on the ask. A+ * sibling that cannot be read is skipped and named in `unreadable`, so one broken repo never hides+ * the others' questions.+ *+ * @param {string} root this repo's root+ * @param {string} repo the name this repo goes by+ * @param {any} board this repo's open board+ * @param {{ root: string, name: string }[]} siblings+ * @param {(root: string) => any} [configFor] reads a sibling's config; tests may replace it+ * @returns {{ decisions: any[], unreadable: string[] }}+ */+export function projectPersonDecisions(root, repo, board, siblings, configFor = loadConfig) {+ const decisions = store.openDecisions(board, store.PERSON).map((ask) => ({ ask: { ...ask, repo }, repo, root, agents: store.listAgents(board), config: null }));+ const unreadable = [];+ for (const sibling of siblings) {+ let other = null;+ try {+ other = store.openBoardForRead(join(repoInfo(sibling.root).commonDir, 'pullboard', 'board.sqlite'));+ if (!other) throw new Refused('NO_BOARD', 'no board here');+ const agents = store.listAgents(other);+ let config = null;+ try { config = configFor(sibling.root); } catch { /* names fall back to this repo's settings */ }+ for (const ask of store.openDecisions(other, store.PERSON)) decisions.push({ ask: { ...ask, repo: sibling.name }, repo: sibling.name, root: sibling.root, agents, config });+ } catch {+ unreadable.push(sibling.name);+ } finally {+ try { other?.db.close(); } catch { /* the read is already done */ }+ }+ }+ return { decisions, unreadable };+}diff --git a/test/team.test.js b/test/team.test.jsindex 3a2516ce..471288f6 100644--- a/test/team.test.js+++ b/test/team.test.js@@ -872,3 +872,69 @@ test('a landing lease renewal or waiter poll writes no board event [Q1,Q2,Q3]',assert.equal(state.holder, null);assert.equal(state.line.length, 1, 'suppressing polling events does not discard the waiting command');});++/** Initialise a second repo in the first one's sandbox, so both register in the same machine home. */+function siblingRepo(box, name, project) {+ const repo = join(box.dir, name);+ mkdirSync(repo);+ box.git(repo, 'init', '-q', '-b', 'main');+ assert.equal(box.run(repo, 'init').code, 0);+ return { repo, project };+}++/** Put a repo into a named project under its own name, committed so the board reads it. */+function nameRepo(box, repo, name, project) {+ const file = join(repo, 'pullboard.json');+ const config = JSON.parse(readFileSync(file, 'utf8'));+ writeFileSync(file, JSON.stringify({ ...config, name, project }, null, 2));+ box.git(repo, 'add', '-A');+ box.git(repo, 'commit', '-q', '-m', 'chore: name the repo');+}++test("one decision list across a project's repos [N34]", { timeout: 180_000 }, async t => { // budget: hang ceiling for three real repos' CLI runs and one view process; not a speed target.+ const box = helpers.project();+ const other = siblingRepo(box, 'repo-b').repo;+ const lone = siblingRepo(box, 'repo-c').repo;+ nameRepo(box, box.repo, 'alpha', 'shop');+ nameRepo(box, other, 'beta', 'shop');+ nameRepo(box, lone, 'gamma', 'elsewhere');+ const ask = (root, text) => {+ const asked = box.run(root, 'shout', 'person', text, '--decision');+ assert.equal(asked.code, 0, asked.err);+ return Number(/as #(\d+)/.exec(asked.out)?.[1]);+ };+ const alphaId = ask(box.repo, 'Ship alpha?');+ const betaId = ask(other, 'Ship beta?');+ ask(lone, 'Ship gamma?');+ const listed = () => JSON.parse(box.run(box.repo, 'decisions', '--as', 'person', '--json').out);++ // The person sees both repos of the project, each with its repo, and not another project's.+ const text = box.run(box.repo, 'decisions', '--as', 'person');+ assert.equal(text.code, 0, text.err);+ assert.match(text.out, new RegExp(`alpha#${alphaId} .*Ship alpha\\?`));+ assert.match(text.out, new RegExp(`beta#${betaId} .*Ship beta\\?`));+ assert.doesNotMatch(text.out, /gamma|Ship gamma/);+ const both = listed();+ assert.deepEqual(both.decisions.map(({ repo, shout_id: id }) => `${repo}#${id}`).sort(), [`alpha#${alphaId}`, `beta#${betaId}`].sort());++ // The local API lists the same decisions, each with its board and repo.+ const view = await helpers.startView(box, box.repo);+ t.after(view.stop);+ const headers = { 'x-pullboard-key': view.key };+ const boards = (await (await fetchFresh(`${view.base}/api/v1/boards`, { headers })).json()).boards;+ const alphaBoard = boards.find(entry => entry.root === box.repo);+ const betaBoard = boards.find(entry => entry.root === other);+ const api = await (await fetchFresh(`${view.base}/api/v1/decisions?board=${alphaBoard.id}`, { headers })).json();+ assert.equal(api.project, 'shop');+ assert.deepEqual(api.decisions.map(({ board, repo }) => `${repo}:${board}`).sort(), [`alpha:${alphaBoard.id}`, `beta:${betaBoard.id}`].sort());++ // Answering from the first repo closes the decision on the second repo's own board, and nowhere else.+ const answered = box.run(box.repo, 'answer', `beta#${betaId}`, 'Yes, ship it.', '--as', 'person');+ assert.equal(answered.code, 0, answered.err);+ assert.deepEqual(withBoard(other, board => store.openDecisions(board, store.PERSON)), []);+ assert.equal(withBoard(box.repo, board => store.openDecisions(board, store.PERSON)).length, 1);+ assert.deepEqual(listed().decisions.map(({ repo }) => repo), ['alpha']);+ const unknown = box.run(box.repo, 'answer', 'nowhere#1', 'x', '--as', 'person');+ assert.notEqual(unknown.code, 0);+ assert.match(unknown.err, /NO_REPO/);+});