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(item-notes): carry typed conversation in context [B29,B31,N14,H16]

Corey Olson8c32055b38c2
diff --git a/docs/api.md b/docs/api.md
index fe580171..ecac946a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -265,7 +265,7 @@ Starting with engine 50, the second REJECT verdict since an item's latest route
## Item threads
-`pullboard fact <id> <kind> "<text>"` appends a fact to an existing item. The observation kinds are `capture`, `measurement`, `note` and `diff`; any registered agent may append them. The judgement kinds are `decision`, `rejection`, `supersession` and `root-cause`; only the item's live lease holder or the coordinator may append them. An expired lease gives no judgement permission. Facts do not change the item's status or its claim.
+`pullboard fact <id> <kind> "<text>"` appends a fact to an existing item. The observation kinds are `capture`, `measurement`, `note`, `diff`, `question`, `answer`, `plan` and `risk`; any registered agent may append them. Typed conversation notes stay on the item thread, without creating a shout or an approval decision. Builder and reviewer read them with `show`; the runner also includes that item’s stamped facts in its context pack. Generic `answer` notes are observations; `--answers` remains reserved for the existing `bar-answer` workflow. The judgement kinds are `decision`, `rejection`, `supersession` and `root-cause`; only the item's live lease holder or the coordinator may append them. An expired lease gives no judgement permission. Facts do not change the item's status or its claim.
The result is `{version: 1, item: <item-id>, fact: {...}}`. A fact has `id` (stable string identity), `eventId` (board-local event sequence), `kind`, exact `text`, `by` (registered author), `at` (UTC timestamp), `ref` and `supersedes`. The board supplies identity, author and time. `ref` and `supersedes` are `null` when omitted.
diff --git a/docs/formats.md b/docs/formats.md
index 911a951c..3af9a913 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -475,7 +475,7 @@ An engine-10 `reopen` of a verified item adds `supersedes` with the earlier acce
A `reopen` with `withdrawVerdict: true` records `withdrawnVerdict: {verdictId, acceptEventId}` for the exact current acceptance withdrawn by its accepting reviewer or the coordinator, and `supersedes` names that same accept event. The original verdict row and accept event remain immutable; history derives their withdrawn state from this binding, without rewriting earlier records or reviving an older acceptance. A later fresh acceptance can become current. This flag requires the verdict-withdraw feature engine; ordinary reopen records and older recorded moves keep their original meaning.
-Item facts use the existing append-only `event` table and event-log version 1. A `fact` event's actor and timestamp stamp its author and time; its detail carries a stable string `id`, typed `kind`, exact `text`, optional `ref` binding or `null`, and superseded fact id or `null`. Allowed kinds are `capture`, `measurement`, `note`, `diff`, `decision`, `rejection`, `supersession` and `root-cause`. Judgement kinds and any correction using `supersedes` require the item's live holder or the coordinator. A correction must refer to a fact on the same item; it adds a new event and preserves every earlier fact.
+Item facts use the existing append-only `event` table and event-log version 1. A `fact` event's actor and timestamp stamp its author and time; its detail carries a stable string `id`, typed `kind`, exact `text`, optional `ref` binding or `null`, and superseded fact id or `null`. Allowed kinds are `capture`, `measurement`, `note`, `diff`, `decision`, `rejection`, `supersession` and `root-cause`. The item-notes engine adds observation kinds `question`, `answer`, `plan` and `risk`; earlier engine receipts retain their original allowed labels. These facts carry the same id, author, timestamp and exact text and never create shout records or signed approval authority. Judgement kinds and any correction using `supersedes` require the item's live holder or the coordinator. A correction must refer to a fact on the same item; it adds a new event and preserves every earlier fact.
A binding is `{path, start, end, commit}`: a relative repository path, a positive ascending inclusive line range and a full 40-character hexadecimal commit id. It identifies code without storing source or requiring Git on a replica. Fact ids are generated UUIDs locally. A sealed `appendFact` operation uses its executable move id as its fact id, so replicas keep corrections bound to the same fact even when local event sequence ids differ. Native export/import retains these event rows without a separate fact table or schema upgrade.
diff --git a/src/board.js b/src/board.js
index 8eb82fd7..a8b1e2d7 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,4 @@
+import { requireFactKind } from './item-notes.js';
import {
focusOrder,
focusReasons,
@@ -1884,8 +1885,7 @@ export { unreadCount } from './board-query.js';
export { events } from './board-query.js';
-/** Fact labels distinguish observations from judgements reserved to an item's live holder [B29,B30]. */
-export const FACT_KINDS = Object.freeze(['capture', 'measurement', 'note', 'diff', 'decision', 'rejection', 'supersession', 'root-cause', 'bar-check', 'bar-answer']);
+export { FACT_KINDS } from './item-notes.js';
const FACT_JUDGEMENTS = new Set(['decision', 'rejection', 'supersession', 'root-cause']);
export { factReference };
@@ -1900,7 +1900,7 @@ export function appendFact(board, id, { agentId, kind, text, ref = null, superse
return atomic(board, () => {
const item = current(board, itemById(board, id));
if (!board.db.prepare('SELECT 1 FROM agent WHERE agent_id = ?').get(agentId)) throw new Refused('NO_AGENT', `no registered agent ${agentId}; join a worktree before appending a fact`);
- if (!FACT_KINDS.includes(kind)) throw new Refused('BAD_FACT_KIND', `unknown fact kind ${String(kind)}; use ${FACT_KINDS.join(', ')}`);
+ requireFactKind(board, kind);
if (typeof text !== 'string' || !text.trim()) throw new Refused('EMPTY_FACT', 'a fact needs nonempty text; supply the observation or judgement');
const barFields = barCheckFactFields(board, item, { agentId, kind, text, answers, supersedes });
if ((FACT_JUDGEMENTS.has(kind) || supersedes !== null) && agentId !== COORDINATOR && (!isHeld(board, item) || item.item_owner !== agentId)) {
diff --git a/src/help.js b/src/help.js
index 93f31957..39736efb 100644
--- a/src/help.js
+++ b/src/help.js
@@ -119,7 +119,7 @@ Work
pullboard show <id> [--history] an item, the criterion frozen at claim, its verdicts: the latest in full,
earlier ones as one line; --history prints every note in full
pullboard fact <id> <kind> <text> [--answers <bar-check-fact-id>] [--supersedes <fact-id>] [--ref path:lines@full-sha] [--implies <ids>]
- append observations, bar-check notes and peer answers, or holder/coordinator judgements
+ append item notes (question, answer, plan, risk), evidence or authorised judgements
a bar-answer uses --answers to name the bar-check fact it reviewed
--implies 12,13: each named item gets a fact citing this decision,
and is told again when the decision is superseded
diff --git a/src/item-notes-engine.js b/src/item-notes-engine.js
new file mode 100644
index 00000000..89f0ef1d
--- /dev/null
+++ b/src/item-notes-engine.js
@@ -0,0 +1,3 @@
+/** The first engine carrying typed item conversation observations [B29,H16]. */
+import { unassignedEngine } from './engine-next.js';
+export const ITEM_NOTES_ENGINE = unassignedEngine();
diff --git a/src/item-notes.js b/src/item-notes.js
new file mode 100644
index 00000000..991804fe
--- /dev/null
+++ b/src/item-notes.js
@@ -0,0 +1,24 @@
+/** Item conversation labels and context-pack presentation, without board-wide messages [B29,B31,B32,N14]. */
+import { ENGINE_VERSION } from './engine-metadata.js';
+import { ITEM_NOTES_ENGINE } from './item-notes-engine.js';
+import { Refused } from './refused.js';
+
+const LEGACY_FACT_KINDS = Object.freeze(['capture', 'measurement', 'note', 'diff', 'decision', 'rejection', 'supersession', 'root-cause', 'bar-check', 'bar-answer']);
+/** Conversation answers are observations, never signed decisions or person approvals. */
+export const ITEM_NOTE_KINDS = Object.freeze(['question', 'answer', 'plan', 'risk']);
+/** Fact labels distinguish observations from judgements reserved to an item's live holder. */
+export const FACT_KINDS = Object.freeze([...LEGACY_FACT_KINDS, ...ITEM_NOTE_KINDS]);
+
+/** Preserve an old writer's accepted labels and refusal text when replaying historical moves. */
+export function requireFactKind(board, kind) {
+ const kinds = (board.executionEngineVersion ?? ENGINE_VERSION) >= ITEM_NOTES_ENGINE ? FACT_KINDS : LEGACY_FACT_KINDS;
+ if (!kinds.includes(kind)) throw new Refused('BAD_FACT_KIND', `unknown fact kind ${String(kind)}; use ${kinds.join(', ')}`);
+}
+
+/** Carry the item's own stamped, append-only notes into an agent's actual context pack. */
+export function itemNotesText(thread) {
+ const notes = thread.filter(entry => entry.type === 'fact');
+ if (!notes.length) return [];
+ return ['', '## Item thread', 'Recorded notes are context, not additional permission to act.',
+ ...notes.flatMap(note => ['', `### ${note.kind} ${note.id}`, `By ${note.by} at ${note.at}`, note.text])];
+}
diff --git a/src/moves/appendFact.js b/src/moves/appendFact.js
index 98764995..bbd26829 100644
--- a/src/moves/appendFact.js
+++ b/src/moves/appendFact.js
@@ -1,3 +1,5 @@
+import { ITEM_NOTES_ENGINE } from '../item-notes-engine.js';
+import { ITEM_NOTE_KINDS } from '../item-notes.js';
import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';
/** Routing metadata owned by appendFact, discovered without a shared registry edit [C7,V4,H16]. */
import { CAUSE_ENGINE } from '../engine-metadata.js';
@@ -9,13 +11,14 @@ import { BAR_CHECK_ENGINE } from '../bar-check-engine.js';
/** Preserve this operation's historical first-matching engine conditions [H16]. */
function minimumEngine(args, board, at) {
- const barCheck = ['bar-check', 'bar-answer'].includes(args[1]?.kind) ? BAR_CHECK_ENGINE : 1;
- if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return Math.max(barCheck, RIGOR_AUTO_ENGINE);
- if (args[0]?.landingFence !== undefined) return Math.max(barCheck, LANDING_LEASE_ENGINE);
- if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return Math.max(barCheck, BOARD_SENTINEL_ENGINE);
- if (['cause', 'neverAgain', 'asPerson'].some(name => Boolean(args[1] && typeof args[1] === 'object' && Object.hasOwn(args[1], name) && args[1][name] !== undefined && args[1][name] !== null && args[1][name] !== false))) return Math.max(barCheck, CAUSE_ENGINE);
- if (carriesImplies('appendFact', args)) return Math.max(barCheck, IMPLIES_ENGINE);
- return barCheck;
+ const floor = Math.max(['bar-check', 'bar-answer'].includes(args[1]?.kind) ? BAR_CHECK_ENGINE : 1,
+ ITEM_NOTE_KINDS.includes(args[1]?.kind) ? ITEM_NOTES_ENGINE : 1);
+ if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return Math.max(floor, RIGOR_AUTO_ENGINE);
+ if (args[0]?.landingFence !== undefined) return Math.max(floor, LANDING_LEASE_ENGINE);
+ if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return Math.max(floor, BOARD_SENTINEL_ENGINE);
+ if (['cause', 'neverAgain', 'asPerson'].some(name => Boolean(args[1] && typeof args[1] === 'object' && Object.hasOwn(args[1], name) && args[1][name] !== undefined && args[1][name] !== null && args[1][name] !== false))) return Math.max(floor, CAUSE_ENGINE);
+ if (carriesImplies('appendFact', args)) return Math.max(floor, IMPLIES_ENGINE);
+ return floor;
}
/** Read precisely the actor argument used by this operation [H2,H16]. */
diff --git a/src/run.js b/src/run.js
index 1255c874..0ac7980f 100644
--- a/src/run.js
+++ b/src/run.js
@@ -1,3 +1,4 @@
+import { itemNotesText } from './item-notes.js';
/**
* `pullboard run` (N14, B15): builds routed items with no one at the keyboard. For each item it may
* take, it writes a context pack (the bar, the cited rows, the brief and the files as they are now),
@@ -159,10 +160,10 @@ function restore(root, start, paths) {
*
* @param {string} root
* @param {any} item
- * @param {{ attempt: number, attempts: number, digest: string, earlier?: string[] }} state
+ * @param {{ attempt: number, attempts: number, digest: string, earlier?: string[], related?: any[], thread?: any[] }} state
* @returns {string}
*/
-export function packText(root, item, { attempt, attempts, digest, earlier = [], related = [] }) {
+export function packText(root, item, { attempt, attempts, digest, earlier = [], related = [], thread = [] }) {
const rows = item.item_frozen ? JSON.parse(item.item_frozen).rows : [];
const config = existsSync(join(root, CONFIG_FILE)) ? loadConfig(root) : {};
const doctrine = loadDoctrine(root, config);
@@ -193,6 +194,7 @@ export function packText(root, item, { attempt, attempts, digest, earlier = [],
'## Brief',
item.item_brief || '(none)',
'',
+ ...itemNotesText(thread),
'## Rules',
`- Change only the files the brief lists${files.length ? `: ${files.join(', ')}` : ''}. Changes anywhere else are reverted.`,
'- Never run git commands; the runner commits your work.',
@@ -332,16 +334,16 @@ async function tryItem(ctx, item, { command, attempts, minutes, deps, me, start,
let digest = '';
let seconds = 0;
for (let attempt = 1; attempt <= attempts; attempt += 1) {
- const { fresh, related } = await deps.withBoard(ctx, async (board) => {
+ const { fresh, related, thread } = await deps.withBoard(ctx, async (board) => {
const options = { agentId: me.id, lane: me.lane, leaseMs: ctx.config.leaseMs, freeze: deps.freezer(ctx) };
if (deps.claim) await deps.claim(ctx, board, [id, options]);
else if (deps.ordered) await deps.ordered(ctx, board, 'claim', [id, options]);
else store.claim(board, id, options);
const claimed = store.getItem(board, id);
- return { fresh: claimed, related: store.relatedItems(board, claimed) };
+ return { fresh: claimed, related: store.relatedItems(board, claimed), thread: store.itemThread(board, id) };
});
const pack = join(packs, `${id}-${tag}-${attempt}.md`);
- writeFileSync(pack, packText(root, fresh, { attempt, attempts, digest, earlier, related }));
+ writeFileSync(pack, packText(root, fresh, { attempt, attempts, digest, earlier, related, thread }));
ctx.io.say(`#${id} attempt ${attempt}/${attempts}: running the ${item.item_route} agent`);
const env = { ...process.env, PULLBOARD_PACK: pack, PULLBOARD_CHECK: item.item_check, PULLBOARD_ITEM: String(id), PULLBOARD_ATTEMPT: String(attempt), PULLBOARD_TIER: item.item_route };
const built = await runCommand(command, { cwd: root, env, timeoutMs: minutes * 60_000, log: join(packs, `${id}-${tag}-${attempt}.log`) });
diff --git a/test/item-notes-engine.test.js b/test/item-notes-engine.test.js
new file mode 100644
index 00000000..b134ec0c
--- /dev/null
+++ b/test/item-notes-engine.test.js
@@ -0,0 +1,88 @@
+/** @pullboard-test-input source-tree */
+/** Typed notes preserve authority and historical replay on real Git and SQLite replicas [B29,B30,B31,H16]. */
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { after, test } from 'node:test';
+import * as store from '../src/board.js';
+import { appliedSequence, applyRelayMove, prepareEngineMove } from '../src/engine.js';
+import { exportBoard, importBoard } from '../src/exchange.js';
+import { ITEM_NOTES_ENGINE } from '../src/item-notes-engine.js';
+import { minimumMoveEngine } from '../src/move-registry.js';
+import { createE2eHelpers } from './e2e-helpers.js';
+
+const helpers = createE2eHelpers();
+after(helpers.cleanup);
+
+/** Seed identical private replicas without a background writer or already-active future receipt. */
+function replicas(t) {
+ const box = helpers.project();
+ const primary = store.openBoard(join(box.dir, 'notes-primary.sqlite'));
+ const peer = store.openBoard(join(box.dir, 'notes-peer.sqlite'));
+ t.after(() => { store.closeBoard(primary); store.closeBoard(peer); });
+ store.register(primary, { lane: 'coordinator', path: box.repo });
+ store.register(primary, { lane: 'web', path: box.web });
+ const id = store.addItem(primary, { by: 'coordinator', lane: 'web', title: 'Versioned conversation' });
+ importBoard(peer, exportBoard(primary));
+ return { boards: [primary, peer], id };
+}
+
+/** Deliver the exact move identity and ordered timestamp through the public authenticated replay entry. */
+function deliver(board, move) {
+ return applyRelayMove(board, move, { sequence: appliedSequence(board) + 1,
+ at: '2026-10-25T00:00:00Z', kind: 'move', sender: { kind: 'agent', agent: 'web-1', userId: 'fixture' } });
+}
+
+test('typed conversation notes keep exact replica identity and an explicit historical engine floor [B29,B31,H16]', t => {
+ const { boards, id } = replicas(t);
+ const [primary, peer] = boards;
+ const legacy = { ...prepareEngineMove(primary, 'appendFact', [id,
+ { agentId: 'web-1', kind: 'note', text: 'An ordinary historical observation' }], { id: 'legacy-note' }), engine: ITEM_NOTES_ENGINE - 1 };
+ const original = boards.map(board => deliver(board, legacy));
+ assert.deepEqual(original[0], original[1]);
+ assert.equal(original[0].error, undefined);
+ const first = prepareEngineMove(primary, 'appendFact', [id,
+ { agentId: 'web-1', kind: 'question', text: 'What stays byte-for-byte?\n<exact content>' }], { id: 'typed-question' });
+ assert.equal(minimumMoveEngine('appendFact', first.args), ITEM_NOTES_ENGINE);
+ const before = boards.map(board => store.itemThread(board, id));
+ for (const board of boards) assert.throws(() => deliver(board, { ...first, engine: ITEM_NOTES_ENGINE - 1 }),
+ /RELAY_MOVE.*introduced in engine/u);
+ assert.deepEqual(boards.map(board => store.itemThread(board, id)), before, 'refusal leaves both threads unchanged');
+ for (const kind of ['question', 'answer', 'plan', 'risk']) {
+ const move = kind === 'question' ? first : prepareEngineMove(primary, 'appendFact', [id,
+ { agentId: 'web-1', kind, text: `Exact ${kind} observation` }], { id: `typed-${kind}` });
+ const outcomes = boards.map(board => deliver(board, move));
+ assert.deepEqual(outcomes[0], outcomes[1]);
+ assert.equal(outcomes[0].error, undefined);
+ }
+ assert.deepEqual(store.itemThread(primary, id), store.itemThread(peer, id));
+ assert.deepEqual(store.allShouts(primary), []);
+ assert.deepEqual(store.allShouts(peer), []);
+ for (const [index, board] of boards.entries()) assert.deepEqual(applyRelayMove(board, legacy,
+ { sequence: 1, at: '2026-10-25T00:00:00Z', kind: 'move', sender: { kind: 'agent', agent: 'web-1', userId: 'fixture' } }), original[index],
+ 'an acknowledged historical note remains replayable after the new floor');
+});
+
+test('conversation answers do not acquire judgment or person authority [B29,B30,H16]', t => {
+ const { boards, id } = replicas(t);
+ const board = boards[0];
+ const old = board.executionEngineVersion;
+ try {
+ board.executionEngineVersion = ITEM_NOTES_ENGINE - 1;
+ assert.throws(() => store.appendFact(board, id, { agentId: 'web-1', kind: 'answer', text: 'New label under old writer' }),
+ { code: 'BAD_FACT_KIND' });
+ } finally { board.executionEngineVersion = old; }
+ const before = store.itemThread(board, id);
+ assert.throws(() => store.appendFact(board, id, { agentId: 'web-1', kind: 'decision', text: 'A nonholder cannot decide' }),
+ { code: 'FACT_JUDGEMENT' });
+ assert.throws(() => store.appendFact(board, id, { agentId: 'web-1', kind: 'answer', text: 'I am not the person', asPerson: true }),
+ { code: 'RIGOR_PERSON_ONLY' });
+ assert.deepEqual(store.itemThread(board, id), before, 'authority refusals cannot append a partial note');
+ const beforeItem = store.getItem(board, id);
+ const answer = store.appendFact(board, id, { agentId: 'web-1', kind: 'answer', text: 'An attributed observation' });
+ assert.equal(answer.by, 'web-1');
+ const afterItem = store.getItem(board, id);
+ for (const field of ['item_status', 'item_owner', 'item_lease_until', 'item_frozen_digest']) {
+ assert.deepEqual(afterItem[field], beforeItem[field], `a conversation answer preserves ${field}`);
+ }
+ assert.deepEqual(store.openDecisions(board), []);
+});