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(queue): notify holders when claimed files grow [N2,B7,B13]

Corey Olson941984eeab93
diff --git a/docs/formats.md b/docs/formats.md
index 2a319385..bca6f86f 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -113,7 +113,7 @@ The board file is in the repository's Git common directory at `.git/pullboard/bo
| `row grammar` | `1` | `SPEC_GRAMMAR_VERSION` in `src/spec.js`; optional `<!-- pullboard-grammar N -->` line in either file (absence means the current grammar) | Both files share the version. A declared version must match; an incompatible grammar change requires a coordinated version bump and compatible files. No automatic conversion occurs. |
| `board schema` | `3` | `SCHEMA_VERSION` in `src/board.js`, persisted as `PRAGMA user_version` | On a write open of a board whose version is behind: create missing tables and indexes (version 3 adds the hot-path indexes), add missing columns in place with declared defaults, restore missing or changed triggers, and remove stale machine triggers without replacing rows. Read opens never migrate; a board at the current version whose shape differs is reported once on stderr and left as it is. |
| `event log` | `1` | `EVENT_LOG_VERSION` in `src/board.js`, persisted in `board_meta` as `event_log_version` | Older event-log versions upgrade in place; newer versions are refused with `EVENT_LOG_VERSION`. Preserve event rows when the board schema changes. |
-| `move engine` | `96` | `ENGINE_VERSION` in `src/machine.js`, carried as `engine` in every sealed executable move | Bump when a move's meaning changes, independently of the event log and sealed envelope. A newer engine is refused with `ENGINE_VERSION`, naming both versions and asking you to upgrade Pullboard. |
+| `move engine` | `97` | `ENGINE_VERSION` in `src/machine.js`, carried as `engine` in every sealed executable move | Bump when a move's meaning changes, independently of the event log and sealed envelope. A newer engine is refused with `ENGINE_VERSION`, naming both versions and asking you to upgrade Pullboard. |
<!-- format-versions:end -->
A builder never picks an engine number (#1101). An item that adds a board move adds its own `src/<name>-engine.js` leaf as `export const NAME_ENGINE = unassignedEngine();` (importing `unassignedEngine` from `./engine-next.js`); on its branch the leaf reads as one above the highest landed engine. The landing merge writes the next number into the leaf, in landing order, inside that item's merge commit, and sets the `move engine` row above to the highest landed number. A landed number never changes, so recorded moves replay as they were written. Moves are recorded under landed numbers only: code with an unnumbered engine is for its branch's own tests, and a move it records on a real board before landing may later read under another item's number, so the item lands before its moves are used.
@@ -542,3 +542,11 @@ The engine-68 `recordSpecApprovalBaseline` move carries `{agentId, baseline: {ve
Landing queue grants, first queue entries and releases are shared ordered transitions. New landing-local-heartbeat engine moves leave renewal and repeated-poll events out of history; old engine receipts keep their recorded meaning. `local:landing-lease:<token>` board metadata binds a physical board id, token/generation, process, branch and coordinator lineage to its local deadline. It is excluded from exports, imports and semantic digests and is retained only on the receiving physical board during a same-board relay snapshot restore. A linked foreign holder has no clock-based expiry: release or coordinator takeover fences it; local heartbeat deadlines never authorize another machine to merge.
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.
+
+`FILE_GROWTH_NOTICE_ENGINE` adds atomic notices to an ordered brief edit: newly named
+files on a claimed or submitted item are checked against lease-normalized claimed,
+submitted and accepted-not-landed work. Each distinct holder receives one system
+notice per overlapping item, linked to its item thread; the edit remains allowed.
+Unchanged paths, prose, reordered lists and removals do not resend notices. Older
+recorded edits retain their silent behavior. The unassigned feature leaf receives
+its number at landing; no event-log or envelope format changes.
diff --git a/src/board.js b/src/board.js
index 892fd6c7..24c78f0a 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,4 @@
+import { FILE_GROWTH_NOTICE_ENGINE } from './file-growth-notice-engine.js';
import {
recordBarRevision,
barReadyProblem,
@@ -106,6 +107,7 @@ import {
import {
itemFiles,
itemFileCollisions,
+ addedFileCollisions,
} from './item-files.js';
export { itemFiles };
import { COORDINATOR } from './config.js';
@@ -713,6 +715,7 @@ export function editItem(board, id, { agentId, brief, route, criterion, check, a
...bar,
});
recordBarRevision(board, itemById(board, id), agentId, item, barActor);
+ notifyFileGrowth(board, item, itemById(board, id));
if (pendingRefreeze) {
insertShout(board, {
from: COORDINATOR,
@@ -724,6 +727,27 @@ export function editItem(board, id, { agentId, brief, route, criterion, check, a
});
}
+/** Persist both holder notices with the edit; a fixed system sender also reaches an editing holder's inbox. */
+function notifyFileGrowth(board, before, after) {
+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < FILE_GROWTH_NOTICE_ENGINE
+ || !['claimed', 'submitted'].includes(before.item_status)) return;
+ for (const collision of addedFileCollisions(before, after, listItems(board, { all: true }))) {
+ const recipients = new Map();
+ for (const item of [before, collision.item]) {
+ const holder = item.item_owner || item.item_built_by;
+ const to = holder && board.db.prepare('SELECT 1 FROM agent WHERE agent_id=?').get(holder) ? holder : COORDINATOR;
+ recipients.set(to, [...(recipients.get(to) ?? []), item.item_id]);
+ }
+ const text = `New file overlap: #${after.item_id} grew into #${collision.item.item_id} on ${collision.shared.join(', ')}. Coordinate both items; the edit is retained.`;
+ for (const [to, items] of recipients) {
+ const detail = { changedItem: after.item_id, otherItem: collision.item.item_id, files: collision.shared };
+ const shout = persistShout(board, { from: 'overlap', to, text, detail: { ...detail, item: items[0] } });
+ // One holder may own both items: deliver once while retaining the notice on both item threads.
+ for (const item of items.slice(1)) logEvent(board, 'overlap', 'shout', item, { ...detail, shout, to, text });
+ }
+ }
+}
+
/** Validate an edit without side effects, so a refused change never starts a shell baseline; a bar correction needs a reason [B31]. */
export function validateItemEdit(board, id, { agentId, brief, route, criterion, check, after, reason }) {
const engine = board.executionEngineVersion ?? ENGINE_VERSION;
diff --git a/src/file-growth-notice-engine.js b/src/file-growth-notice-engine.js
new file mode 100644
index 00000000..7a485a0f
--- /dev/null
+++ b/src/file-growth-notice-engine.js
@@ -0,0 +1,3 @@
+/** Ordered file-growth notices preserve historical edit replay [N2,B7,B13,H16]. */
+import { unassignedEngine } from './engine-next.js';
+export const FILE_GROWTH_NOTICE_ENGINE = unassignedEngine();
diff --git a/src/item-files.js b/src/item-files.js
index 8995c331..4828695b 100644
--- a/src/item-files.js
+++ b/src/item-files.js
@@ -12,13 +12,24 @@ export function itemFiles(item) {
return [...new Set([...changed, ...briefFiles(item.item_brief ?? '')])];
}
-/** Name overlaps with current in-flight items; callers supply lease-normalized board records. */
-export function itemFileCollisions(item, items) {
- const files = new Set(briefFiles(item.item_brief ?? ''));
+/** Find shared paths against lease-normalized in-flight items, retaining the existing item order. */
+function fileCollisions(item, files, items) {
if (!files.size) return [];
return items.filter(other => other.item_id !== item.item_id && (other.item_status === 'claimed'
|| other.item_status === 'submitted' || (other.item_status === 'verified' && !other.item_merged_commit)))
.map(other => ({ item: other, shared: itemFiles(other).filter(path => files.has(path)) }))
- .filter(other => other.shared.length)
+ .filter(other => other.shared.length);
+}
+
+/** Name overlaps with current in-flight items; callers supply lease-normalized board records. */
+export function itemFileCollisions(item, items) {
+ return fileCollisions(item, new Set(briefFiles(item.item_brief ?? '')), items)
.map(other => `#${item.item_id} waits for #${other.item.item_id} (${other.item.item_status}) on ${other.shared.join(', ')}`);
}
+
+/** Only newly declared paths can create an edit notice; prose, order and removals are silent. */
+export function addedFileCollisions(before, after, items) {
+ const previous = new Set(briefFiles(before.item_brief ?? ''));
+ const added = new Set(briefFiles(after.item_brief ?? '').filter(path => !previous.has(path)));
+ return fileCollisions(after, added, items).map(other => ({ ...other, shared: other.shared.toSorted() }));
+}
diff --git a/test/file-growth-notice.test.js b/test/file-growth-notice.test.js
new file mode 100644
index 00000000..7bcd6b0d
--- /dev/null
+++ b/test/file-growth-notice.test.js
@@ -0,0 +1,76 @@
+/** @pullboard-test-input source-tree */
+/** Private real-Git/SQLite lifecycle controls; none of these records claims a gate or publication. */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { join } from 'node:path';
+import * as store from '../src/board.js';
+import { applyEngineMove, prepareEngineMove } from '../src/engine.js';
+import { FILE_GROWTH_NOTICE_ENGINE } from '../src/file-growth-notice-engine.js';
+import { exportBoard, importBoard } from '../src/exchange.js';
+import { createE2eHelpers } from './e2e-helpers.js';
+
+const HOUR = 60 * 60 * 1000;
+/** Seed only private claim state, using a real project and its normal board file. */
+function fixture(t, { sameHolder = false, expiredPeer = false } = {}) {
+ const helpers = createE2eHelpers();
+ t.after(helpers.cleanup);
+ const box = helpers.project('true');
+ const board = store.openBoard(join(box.repo, '.git', 'pullboard', 'board.sqlite'));
+ t.after(() => store.closeBoard(board));
+ // This is a board-clock boundary control, not an actual physical lease or elapsed-time claim.
+ let at = Date.parse('2026-10-24T00:00:00Z');
+ board.clock = { now: () => new Date(at) };
+ const left = store.register(board, { lane: 'web', path: join(box.dir, 'left-state'), route: 'strong' });
+ const right = sameHolder ? left : store.register(board, { lane: 'web', path: join(box.dir, 'right-state'), route: 'strong' });
+ /** Keep each fixture's frozen words explicit without claiming a check was executed. */
+ const freeze = item => ({ text: JSON.stringify({ title: item.item_title, criterion: 'private lifecycle state', check: 'true', rows: [] }), digest: `fixture:${item.item_id}` });
+ const a = store.addItem(board, { by: 'coordinator', lane: 'web', title: 'A holds x', brief: 'Files: web/x.js' });
+ const b = store.addItem(board, { by: 'coordinator', lane: 'web', title: 'B holds y', brief: 'Files: web/y.js' });
+ store.claim(board, a, { agentId: left, lane: 'web', leaseMs: HOUR, freeze });
+ if (expiredPeer) at += HOUR;
+ store.claim(board, b, { agentId: right, lane: 'web', leaseMs: HOUR, freeze });
+ return { board, left, right, a, b, at: () => new Date(at).toISOString() };
+}
+
+/** Apply the ordinary versioned edit input, rather than calling a notification helper. */
+function edit(box, brief, engine = undefined) {
+ const move = prepareEngineMove(box.board, 'editItem', [box.b, { agentId: 'coordinator', brief }]);
+ const result = applyEngineMove(box.board, engine === undefined ? move : { ...move, engine }, { sequence: 1, at: box.at() });
+ assert.equal(result.error, undefined, JSON.stringify(result.error));
+}
+
+test('historical brief edits stay silent while current overlap notices survive board export [N2,B7,H16]', t => {
+ const box = fixture(t);
+ edit(box, 'Files: web/y.js, web/x.js', FILE_GROWTH_NOTICE_ENGINE - 1);
+ assert.match(store.getItem(box.board, box.b).item_brief, /web\/x\.js/u, 'legacy edit still takes effect');
+ assert.equal(store.allShouts(box.board).length, 0, 'replaying an older edit does not invent new messages');
+ edit(box, 'Files: web/y.js', FILE_GROWTH_NOTICE_ENGINE - 1);
+ edit(box, 'Files: web/y.js, web/x.js');
+ const notices = store.allShouts(box.board);
+ assert.deepEqual(notices.map(row => row.shout_to).toSorted(), [box.left, box.right].toSorted());
+ edit(box, 'Files: web/y.js, web/x.js');
+ assert.equal(store.allShouts(box.board).length, 2, 'another edit with the same file set does not resend');
+ const copy = store.openBoard(':memory:');
+ t.after(() => store.closeBoard(copy));
+ importBoard(copy, exportBoard(box.board));
+ assert.deepEqual(store.allShouts(copy), notices, 'snapshot transport retains the actual delivered messages');
+ for (const id of [box.a, box.b]) assert.deepEqual(store.itemThread(copy, id), store.itemThread(box.board, id));
+});
+
+test('one holder of both overlapping items gets one message linked to both threads [N2,B7,B13]', t => {
+ const box = fixture(t, { sameHolder: true });
+ edit(box, 'Files: web/y.js, web/x.js');
+ const notices = store.allShouts(box.board);
+ assert.equal(notices.length, 1);
+ assert.equal(notices[0].shout_to, box.left);
+ for (const id of [box.a, box.b]) assert.ok(store.itemThread(box.board, id)
+ .some(event => event.kind === 'shout' && event.detail.shout === notices[0].shout_id));
+});
+
+test('a brief growth does not notify an expired claim as work in flight [N2,B4,N20]', t => {
+ const box = fixture(t, { expiredPeer: true });
+ assert.equal(store.getItem(box.board, box.a).item_status, 'open', 'the existing lease boundary is respected');
+ edit(box, 'Files: web/y.js, web/x.js');
+ assert.match(store.getItem(box.board, box.b).item_brief, /web\/x\.js/u);
+ assert.equal(store.allShouts(box.board).length, 0);
+});