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.

feat(shout): accept coordination-only seat reports [B7,A2,N19]

Corey Olson8a3ac1e29c85
diff --git a/docs/formats.md b/docs/formats.md
index f9b7a373..d7d7e31c 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -526,4 +526,4 @@ Engine 68 retains the existing validated verifier note in new acceptance-event d
The engine-68 `recordSpecApprovalBaseline` move carries `{agentId, baseline: {version: 1, file, anchor, rows: [{id, text, source}]}}`. `anchor` is the current commit or `null` before the first commit; exact source rows also cover uncommitted initial requirements. Only the authenticated coordinator may establish the snapshot; a person uses the main checkout’s coordinator path. Lane commands never seed or replace it. The first snapshot is indexed under `board_meta.spec_approval_baseline` with a `spec_approval_baseline` event. Replay writes metadata only, never checkout files. Sender attribution is authenticated normally, older engines refuse the new move, and later bootstrap attempts cannot replace or expand the original snapshot. No local sidecar establishes shared approval authority. The metadata snapshot must agree with its single original coordinator event; a partial restore with either half missing or changed is invalid. A malformed stored marker remains in place with an invalid-baseline diagnostic; it is not treated as an absent migration baseline or reseeded by later commands. Board imports remain trusted recovery operations; agreement of these records is a consistency check, not cryptographic authentication of an imported history.
-Engine 93 adds item-addressed shouts. A shout move's optional `item` names an existing item; its event belongs to that item and includes the message text. Its canonical `shout_to` is `item:<id>`, read by the item's current builder and reviewer and the coordinator. Inbox, resume and seat watch use the same audience; an explicit seat or lane destination with `--item` still uses the item's audience. An item decision is answerable by its current participants or coordinator; replies stay in its thread and audience. The coordinator can still pass it to the person through the existing decision flow. Only the coordinator and person can broadcast `all`; recorded older-engine broadcasts retain their meaning. Main-checkout watch remains the person's board-wide observer. A joined seat's default watch filters shouts to its own address, lane, items and `all`, while ordinary lifecycle events remain visible.
+Engine 93 adds item-addressed shouts. A shout move's optional `item` names an existing item; its event belongs to that item and includes the message text. Its canonical `shout_to` is `item:<id>`, read by the item's current builder and reviewer and the coordinator. Inbox, resume and seat watch use the same audience; an explicit seat or lane destination with `--item` still uses the item's audience. An item decision is answerable by its current participants or coordinator; replies stay in its thread and audience. The coordinator can still pass it to the person through the existing decision flow. A registered seat's shout to `all` is accepted and stored at reserved address `coordinator+person`, read only by coordination audiences. The plus sign cannot occur in valid lane names or their derived seat ids. Coordinator and person broadcasts retain `all` and reach everyone; recorded older-engine `all` rows retain their original global meaning without a retrospective sender filter. Main-checkout watch remains the person's board-wide observer. A joined seat's default watch filters shouts to its own address, lane, items and `all`, while ordinary lifecycle events remain visible.
diff --git a/src/board.js b/src/board.js
index e32ce322..84c69b5c 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,5 +1,6 @@
import { ITEM_SHOUT_ENGINE } from './item-shout-engine.js';
import {
+ COORDINATION_SHOUT,
itemShoutTarget,
itemShoutReader,
shoutItemId,
@@ -1898,10 +1899,9 @@ function insertShout(board, { from, to, text, lanes, item, decision = false, ans
to = itemShoutTarget(board.db, item);
detail = { ...detail, item, text: text.trim() };
}
- if (engine >= ITEM_SHOUT_ENGINE && to === 'all' && from !== COORDINATOR && from !== PERSON
- && board.db.prepare('SELECT 1 FROM agent WHERE agent_id = ?').get(from)) {
- throw new Refused('BROADCAST_FORBIDDEN', 'only the coordinator or person broadcasts; address an item with pullboard shout --item <id> \"text\", or name a seat');
- }
+ const coordinationOnly = engine >= ITEM_SHOUT_ENGINE && to === 'all' && from !== COORDINATOR && from !== PERSON
+ && Boolean(board.db.prepare('SELECT 1 FROM agent WHERE agent_id = ?').get(from));
+ if (coordinationOnly) to = COORDINATION_SHOUT;
if (!text.trim()) throw new Refused('EMPTY_SHOUT', 'a shout needs text');
if (to === from) throw new Refused('SELF_SHOUT', `a shout cannot be addressed to its sender ${from}; name another agent, a lane or all`);
if (request && (from !== 'person' || to !== COORDINATOR || decision || answers !== null)) {
@@ -1910,7 +1910,7 @@ function insertShout(board, { from, to, text, lanes, item, decision = false, ans
const ask = answers === null ? null : getShout(board, answers);
const isAgent = board.db.prepare('SELECT 1 FROM agent WHERE agent_id = ?').get(to);
const requestReply = ask?.shout_request && to === ask.shout_from;
- if (item === undefined && to !== 'all' && to !== PERSON && !lanes.includes(to) && !isAgent && !requestReply) {
+ if (item === undefined && !coordinationOnly && to !== 'all' && to !== PERSON && !lanes.includes(to) && !isAgent && !requestReply) {
throw new Refused('NO_READER', `nobody reads "${to}": name a lane, an agent or all`);
}
if (to === PERSON && decision && from !== COORDINATOR) {
@@ -2016,7 +2016,7 @@ export function passDecision(board, id, { agentId, note, lanes }) {
return atomic(board, () => {
if (agentId !== COORDINATOR) throw new Refused('COORDINATOR_ONLY', 'only the coordinator can pass a decision up');
const ask = getShout(board, id);
- if (!ask.shout_decision || (ask.shout_to !== COORDINATOR && shoutItemId(ask.shout_to) === null)) throw new Refused('NOT_COORDINATOR_DECISION', `shout #${id} is not a decision waiting for the coordinator`);
+ if (!ask.shout_decision || (ask.shout_to !== COORDINATOR && ask.shout_to !== COORDINATION_SHOUT && shoutItemId(ask.shout_to) === null)) throw new Refused('NOT_COORDINATOR_DECISION', `shout #${id} is not a decision waiting for the coordinator`);
if (board.db.prepare('SELECT 1 FROM shout WHERE shout_answers = ?').get(id)) throw new Refused('ALREADY_ANSWERED', `shout #${id} already has an answer`);
const text = `Passed up from ${ask.shout_from}: ${ask.shout_text}\nCoordinator note: ${String(note ?? '').trim()}`;
if (!String(note ?? '').trim()) throw new Refused('EMPTY_NOTE', 'include a note with the reason for passing this decision');
@@ -2048,6 +2048,7 @@ export function answerDecision(board, id, { agentId, text, lanes, asPerson = fal
const caller = personAnswer ? null : board.db.prepare('SELECT agent_lane FROM agent WHERE agent_id = ?').get(agentId);
const addressedItem = shoutItemId(ask.shout_to);
const ownsDecision = ask.shout_to === agentId || ask.shout_to === caller?.agent_lane
+ || (ask.shout_to === COORDINATION_SHOUT && agentId === COORDINATOR)
|| (addressedItem !== null && itemShoutReader(board.db, addressedItem, agentId));
if (!ownsDecision && !personAnswer) {
const lane = caller?.agent_lane ? `your ${caller.agent_lane} lane` : 'a lane you do not belong to';
@@ -2127,6 +2128,7 @@ export function openDecisions(board, recipient = null) {
const recipients = [...new Set(Array.isArray(recipient) ? recipient : [recipient])];
if (!recipients.length) return [];
return openDecisions(board).filter((ask) => recipients.includes(ask.shout_to)
+ || (ask.shout_to === COORDINATION_SHOUT && recipients.includes(COORDINATOR))
|| (shoutItemId(ask.shout_to) !== null && recipients.some((agent) => itemShoutReader(board.db, shoutItemId(ask.shout_to), agent))));
}
diff --git a/src/help.js b/src/help.js
index 4ecd7615..fc7cbd33 100644
--- a/src/help.js
+++ b/src/help.js
@@ -132,6 +132,7 @@ Work
any --note can be --note-file <file>, which keeps quotes, $ and backticks intact
pullboard shout <lane|agent|person|all> <text> pullboard inbox
pullboard shout --item <id> <text> message the item builder, reviewer and coordinator
+ A 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 <to> <text> --evidence attempt|receipt --outcome <word> --item <id> --commit <rev>
pullboard answer <shout-id> <text> [--as person] [--implies <ids>] [--supersedes <answer-id>]
diff --git a/src/item-shout-engine.js b/src/item-shout-engine.js
index 2ca8b4d2..fa16be70 100644
--- a/src/item-shout-engine.js
+++ b/src/item-shout-engine.js
@@ -1,2 +1,2 @@
-/** The engine where item shouts reach their participants and agent broadcasts are refused [B7,N19]. */
+/** The engine where item shouts reach their participants and agent reports to all reach only coordination [B7,N19]. */
export const ITEM_SHOUT_ENGINE = 93;
diff --git a/src/next-steps.js b/src/next-steps.js
index eb6f8e4c..36bbce0c 100644
--- a/src/next-steps.js
+++ b/src/next-steps.js
@@ -285,7 +285,6 @@ export const NEXT_STEPS = Object.freeze({
NO_FIT_PROPOSALS: 'have a seat record proposals with pullboard blueprint fit <name or file> <target> keep|adapt|drop|answer',
EMPTY_NOTE: 'say why: pullboard pass <id> --note "<reason>"',
BAD_SHOUT_ITEM: 'name an existing positive item: pullboard shout --item <id> "<text>"',
- BROADCAST_FORBIDDEN: 'address the people on an item: pullboard shout --item <id> "<text>"',
EMPTY_SHOUT: 'give the shout text: pullboard shout <to> "<text>"',
EMPTY_SIGNERS: 'restore the signer list from Git: git restore --source=HEAD -- .pullboard/signers',
ENGINE_VERSION: 'upgrade Pullboard: npm install -g pullboard@latest',
diff --git a/src/shout-audience.js b/src/shout-audience.js
index 7a347463..dc90de4e 100644
--- a/src/shout-audience.js
+++ b/src/shout-audience.js
@@ -1,6 +1,9 @@
/** Shared item-message addressing for the board's inbox, resume and live watch [B7,N19,A2]. */
import { Refused } from './refused.js';
+/** Reserved engine-93 address: '+' is forbidden in lane names and their derived seat ids. */
+export const COORDINATION_SHOUT = 'coordinator+person';
+
/** Validate an explicit item address against this board before writing its message. */
export function itemShoutTarget(db, value) {
if (!Number.isSafeInteger(value) || value < 1) throw new Refused('BAD_SHOUT_ITEM', 'an item message needs an existing positive item id; run pullboard shout --item <id> "text"');
@@ -24,6 +27,7 @@ export function itemShoutReader(db, id, agent) {
/** Match one live shout against an explicit seat or lane audience, including its item roles. */
export function shoutMatchesAudience(db, to, audience) {
+ if (to === COORDINATION_SHOUT) return audience.has('coordinator') || audience.has('person');
if (audience.has(to)) return true;
const item = shoutItemId(to);
if (item === null) return false;
@@ -32,5 +36,5 @@ export function shoutMatchesAudience(db, to, audience) {
/** Existing four inbox parameters stay cursor, seat, lane, seat; indexed parameters reuse the seat identity. */
export const UNREAD_SHOUT_SQL = `FROM shout WHERE shout_id > ?1 AND shout_from != ?2 AND
- (shout_to IN ('all', ?3, ?4) OR EXISTS (SELECT 1 FROM item WHERE shout_to = 'item:' || item_id AND
+ (shout_to IN ('all', ?3, ?4) OR (shout_to = '${COORDINATION_SHOUT}' AND ?2 IN ('coordinator', 'person')) OR EXISTS (SELECT 1 FROM item WHERE shout_to = 'item:' || item_id AND
(?2 = 'coordinator' OR COALESCE(item_owner, item_built_by) = ?2 OR COALESCE(item_review_by, item_verified_by) = ?2)))`;
diff --git a/test/board.test.js b/test/board.test.js
index 92abbce3..44c3beca 100644
--- a/test/board.test.js
+++ b/test/board.test.js
@@ -569,7 +569,9 @@ test('shouts reach a lane, an agent or all; inbox marks them read [B7]', () => {
const lanes = ['coordinator', 'web', 'api'];
store.shout(board, { from: 'coordinator', to: 'web', text: 'web: rebase', lanes });
store.shout(board, { from: 'api-1', to: 'web-2', text: 'web-2: schema changed', lanes });
- assert.throws(() => store.shout(board, { from: 'web-1', to: 'all', text: 'all: gate is slow', lanes }), /BROADCAST_FORBIDDEN/);
+ const report = store.shout(board, { from: 'web-1', to: 'all', text: 'all: gate is slow', lanes });
+ assert.equal(store.getShout(board, report).shout_to, 'coordinator+person');
+ assert.ok(store.inbox(board, 'coordinator').some(shout => shout.shout_id === report));
store.shout(board, { from: 'coordinator', to: 'all', text: 'all: gate is slow', lanes });
assert.throws(() => store.shout(board, { from: 'web-1', to: 'nobody', text: 'x', lanes }), /NO_READER/);
assert.equal(store.unreadCount(board, 'web-2'), 3);
diff --git a/test/engine.test.js b/test/engine.test.js
index a08932a7..09720b2f 100644
--- a/test/engine.test.js
+++ b/test/engine.test.js
@@ -694,4 +694,14 @@ test('engine 93 item messages replay and older broadcasts keep their recorded me
assert.deepEqual(first, second);
assert.equal(store.getShout(one, first.result).shout_to, `item:${item}`);
assert.equal(store.getShout(two, second.result).shout_to, `item:${item}`);
+ const report = prepareEngineMove(one, 'shout', [{ from: 'web-1', to: 'all', text: 'new private report', lanes: ['web'] }]);
+ const reports = copies.map(board => applyEngineMove(board, report, { sequence: 3, at: CLAIM_AT }));
+ assert.deepEqual(reports[0], reports[1]);
+ for (const [index, board] of copies.entries()) {
+ assert.equal(store.getShout(board, reports[index].result).shout_to, 'coordinator+person');
+ assert.equal(store.inbox(board, 'web-2').some(shout => shout.shout_text === 'new private report'), false);
+ assert.equal(store.inbox(board, 'coordinator').some(shout => shout.shout_text === 'new private report'), true);
+ assert.equal(store.recentShouts(board).find(shout => shout.shout_text === 'old broadcast').shout_to, 'all',
+ 'recorded old broadcast remains global, rather than being reinterpreted by its sender');
+ }
});
diff --git a/test/relay-mint.test.js b/test/relay-mint.test.js
index a7950c86..dec00e3b 100644
--- a/test/relay-mint.test.js
+++ b/test/relay-mint.test.js
@@ -113,7 +113,7 @@ test('an agent in its worktree cannot mint a relay token [H2,V1,E3,E5,P6]', asyn
const reviewer = await created(box.root, 'Reviewer Seat');
const child = await created(builder.path, 'Child Seat');
const grandchild = await created(child.path, 'Grandchild Seat');
- const prelinkedActs = await box.cliAt(prelinked.document.path, 'shout', 'coordinator', 'a seat from before the link keeps building');
+ const prelinkedActs = await box.cliAt(prelinked.document.path, 'shout', 'all', 'a seat from before the link keeps building');
assert.equal(prelinkedActs.code, 0, prelinkedActs.failure ?? 'an existing seat keeps working after the link');
const boardCopy = join(mkdtempSync(join(tmpdir(), 'pullboard-mint-board-')), 'board.sqlite');
@@ -206,7 +206,7 @@ test('an agent in its worktree cannot mint a relay token [H2,V1,E3,E5,P6]', asyn
assert.equal(premint.status, 201, 'the machine credential first-mints a never-issued name');
const skipped = await created(box.root, 'After Premint');
assert.notEqual(skipped.id, target, 'the pre-minted name is skipped, not upgraded');
- const claimed = await box.cliAt(manualRoot, 'shout', 'coordinator', 'manual seat still builds');
+ const claimed = await box.cliAt(manualRoot, 'shout', 'all', 'manual seat still builds');
assert.equal(claimed.code, 0, claimed.failure ?? 'the build-only seat keeps acting under its own token');
});
diff --git a/test/relay-sealed.test.js b/test/relay-sealed.test.js
index 4cbccc00..c47eb0ec 100644
--- a/test/relay-sealed.test.js
+++ b/test/relay-sealed.test.js
@@ -234,7 +234,7 @@ test('sealed agent shout cannot answer a person decision on either independent c
from: 'remote-1', to: 'coordinator', text: 'Forged approval', answers: question, lanes: [lane],
}]);
ordinary = prepareEngineMove(source, 'shout', [{
- from: 'remote-1', to: 'coordinator', text: 'Ordinary agent observation', lanes: [lane],
+ from: 'remote-1', to: 'all', text: 'Ordinary agent observation', lanes: [lane],
}]);
answer = prepareEngineMove(source, 'answerDecision', [question, {
agentId: 'coordinator', asPerson: true, text: 'Approved by the person', lanes: [lane],
@@ -440,7 +440,7 @@ test('two real clients refuse forged relay actors and person-only requests while
{ version: 1, type: 'person-request', id: 'forged-person-request', move: { verb: 'shout', args: { to: 'coordinator', text: 'forged person request' } } },
prepareEngineMove(source, 'recordRowDecisions', [{ agentId: 'remote-1', channel: 'view', decisions: [] }]),
prepareEngineMove(source, 'appendFact', [1, { agentId: 'coordinator', kind: 'note', text: 'forged fact' }]),
- prepareEngineMove(source, 'shout', [{ from: 'remote-1', to: 'coordinator', text: 'valid remote observation', lanes: [lane] }]),
+ prepareEngineMove(source, 'shout', [{ from: 'remote-1', to: 'all', text: 'valid remote observation', lanes: [lane] }]),
];
document = JSON.parse(JSON.stringify(exportBoard(source)));
} finally { store.closeBoard(source); }