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(references): validate brief links and retain replay [C7,H16]

Corey Olson53ef56b43f11
diff --git a/src/board.js b/src/board.js
index 01fd2f8c..87bd78cf 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,4 +1,6 @@
import { foreignBlockers } from './cross-repo-dependencies.js';
+import { REFERENCE_ENGINE } from './reference-engine.js';
+import { validateReferenceTargets } from './reference-lines.js';
import {
dependencyValues,
validateNativeDependencies,
@@ -661,15 +663,16 @@ function checkRoute(route) {
*
* @param {{ brief: string, route: string, criterion: string, check: string }} item
*/
-function checkRouted({ brief, route, criterion, check }) {
+function checkRouted({ brief, route, criterion, check }, engine = ENGINE_VERSION) {
if (brief.length > BRIEF_LIMIT) {
throw new Refused('BRIEF_TOO_LONG', `the brief is ${brief.length} characters; keep it under ${BRIEF_LIMIT} and point to longer docs by path`);
}
refuseMaskedExit(check);
if (route === 'strong') return;
- const sections = briefSections(brief);
+ const referenceOptions = { references: engine >= REFERENCE_ENGINE };
+ const sections = briefSections(brief, referenceOptions);
const missing = [
- ...(briefFiles(brief).length ? [] : ['a brief with a Files: section naming the paths to touch']),
+ ...(briefFiles(brief, referenceOptions).length ? [] : ['a brief with a Files: section naming the paths to touch']),
...(sections.test?.length ? [] : ['a Test: section saying what the test asserts']),
...(criterion.trim() ? [] : ['--criterion, saying when it is done']),
...(check.trim() ? [] : ['--check, the command that proves it']),
@@ -752,7 +755,9 @@ export function validateItemAddition(board, { by, lane, title, criterion = '', p
const cleanTitle = title.trim();
if (!cleanTitle) throw new Refused('NO_TITLE', 'an item needs a title');
checkRoute(route);
- checkRouted({ brief: brief.trim(), route, criterion, check: command });
+ const engine = board.executionEngineVersion ?? ENGINE_VERSION;
+ if (engine >= REFERENCE_ENGINE) validateReferenceTargets(brief);
+ checkRouted({ brief: brief.trim(), route, criterion, check: command }, engine);
if (parentId !== null) {
const parent = itemById(board, parentId);
if (parent.item_lane !== lane) {
@@ -884,7 +889,8 @@ export function validateItemEdit(board, id, { agentId, brief, route, criterion,
if (moved.length && item.item_status !== 'open' && (routeChanged || !correctionWhileClaimed)) {
throw new Refused('HELD', `item #${id} is ${item.item_status}; change its route, criterion or check only while it is open`);
}
- checkRouted({ brief: next.item_brief, route: next.item_route, criterion: next.item_criterion, check: next.item_check });
+ if (brief !== undefined && engine >= REFERENCE_ENGINE) validateReferenceTargets(brief);
+ checkRouted({ brief: next.item_brief, route: next.item_route, criterion: next.item_criterion, check: next.item_check }, engine);
const unfreeze = next.item_criterion !== item.item_criterion || next.item_check !== item.item_check;
return { item, next, command, unfreeze, bar: barCorrectionFields(board, item, next, { reason }) };
}
diff --git a/src/brief.js b/src/brief.js
index b07f24cb..3c66c266 100644
--- a/src/brief.js
+++ b/src/brief.js
@@ -5,6 +5,7 @@
*/
const LABEL_RE = /^(files|change|test|out of scope)\s*:\s*(.*)$/i;
+const REFERENCE_LABEL_RE = /^(files|change|test|out of scope|reference)\s*:\s*(.*)$/i;
/** Remove closed parenthetical notes while leaving an unmatched note visible to path checks.
*
@@ -39,18 +40,22 @@ function withoutParentheticalNotes(text) {
* The brief split into its labelled sections, each a list of non-empty lines without bullets.
*
* @param {string} brief
+ * @param {{ references?: boolean }} [options] Preserve the old section grammar during historical replay.
* @returns {Record<string, string[]>}
*/
-export function briefSections(brief) {
+export function briefSections(brief, { references = true } = {}) {
/** @type {Record<string, string[]>} */
const sections = {};
let current = '';
for (const raw of brief.split('\n')) {
const line = raw.trim();
- const label = LABEL_RE.exec(line);
+ const label = (references ? REFERENCE_LABEL_RE : LABEL_RE).exec(line);
if (label) {
current = label[1].toLowerCase();
- sections[current] = label[2].trim() ? [label[2].trim()] : [];
+ if (current === 'reference') {
+ sections.reference ??= [];
+ if (label[2].trim()) sections.reference.push(label[2].trim());
+ } else sections[current] = label[2].trim() ? [label[2].trim()] : [];
} else if (current && line) {
sections[current].push(line.replace(/^[-*]\s+/, ''));
}
@@ -62,10 +67,11 @@ export function briefSections(brief) {
* The paths a brief's Files section names, without bullets, backticks or trailing notes.
*
* @param {string} brief
+ * @param {{ references?: boolean }} [options] Use the same section grammar as the caller's replay engine.
* @returns {string[]}
*/
-export function briefFiles(brief) {
- return (briefSections(brief).files ?? [])
+export function briefFiles(brief, options) {
+ return (briefSections(brief, options).files ?? [])
.flatMap((entry) => withoutParentheticalNotes(entry).split(/[,\s]+/))
.map((token) => token.replace(/^[(`'"]+|[)\]'".,;:!?]+$/g, ''))
.filter((token) => !/^[\d.]+$/.test(token)
diff --git a/src/moves/addItem.js b/src/moves/addItem.js
index 0440fecb..b44cef61 100644
--- a/src/moves/addItem.js
+++ b/src/moves/addItem.js
@@ -27,6 +27,7 @@ function actor(move) { return move.args[0]?.by ?? null; }
export default Object.freeze({ operation: "addItem", order: 8, engine: 1,
itemIdFirstArgument: false, minimumEngine, actor,
nextSteps: Object.freeze({
+ "REFERENCE_IS_BOARD": "use --specs for spec rows, --after for item dependencies, or --parent for a parent item",
"BAD_CHECK": "ask your coordinator to set the check: pullboard edit <id> --check \"<command>\"",
"BAD_CHECK_BASELINE": "the coordinator sets the check again: pullboard edit <id> --check \"<command>\"",
"COORDINATOR_CHECK": "ask your coordinator to set the check: pullboard shout coordinator \"please set a check on #<id>\""
diff --git a/src/moves/editItem.js b/src/moves/editItem.js
index b0abca97..97e805e2 100644
--- a/src/moves/editItem.js
+++ b/src/moves/editItem.js
@@ -33,6 +33,7 @@ function actor(move) { return move.args[1]?.agentId ?? null; }
export default Object.freeze({ operation: "editItem", order: 9, engine: 1,
itemIdFirstArgument: true, minimumEngine, actor,
nextSteps: Object.freeze({
+ "REFERENCE_IS_BOARD": "use --specs for spec rows, --after for item dependencies, or --parent for a parent item",
"BAD_CHECK": "ask your coordinator to set the check: pullboard edit <id> --check \"<command>\"",
"BAR_REASON": "say what the old bar got wrong: pullboard edit <id> --reason \"...\"",
"COORDINATOR_CHECK": "ask your coordinator to set the check: pullboard shout coordinator \"please set a check on #<id>\"",
diff --git a/src/reference-engine.js b/src/reference-engine.js
new file mode 100644
index 00000000..e23f32e1
--- /dev/null
+++ b/src/reference-engine.js
@@ -0,0 +1,4 @@
+/** External brief references use their own grammar and validation without rewriting old moves [C7,H16]. */
+import { unassignedEngine } from './engine-next.js';
+
+export const REFERENCE_ENGINE = unassignedEngine();
diff --git a/src/reference-lines.js b/src/reference-lines.js
new file mode 100644
index 00000000..badfb7eb
--- /dev/null
+++ b/src/reference-lines.js
@@ -0,0 +1,22 @@
+/** Read external brief references without treating their private text as work instructions [C7]. */
+import { briefSections } from './brief.js';
+import { Refused } from './refused.js';
+import { ID_RE } from './spec.js';
+
+/** Preserve every reference and distinguish an explicit trailing acknowledgement from an incidental @. */
+export function referenceLines(brief = '') {
+ return (briefSections(brief).reference ?? []).map(text => {
+ const matched = /\s+@([A-Za-z0-9][A-Za-z0-9-]{0,38})$/u.exec(text);
+ return { text, target: matched ? text.slice(0, matched.index).trim() : text.trim(), handle: matched?.[1] ?? null };
+ });
+}
+
+/** A bare board identifier belongs in the typed requirement or dependency fields, never in an external reference. */
+export function validateReferenceTargets(brief) {
+ for (const { target } of referenceLines(brief)) {
+ if (ID_RE.test(target)) throw new Refused('REFERENCE_IS_BOARD', `"${target}" is a spec row; cite it with --specs ${target} so it counts in the bar.`);
+ if (/^(?:[a-z0-9][a-z0-9._-]*#|#)?[1-9]\d*$/iu.test(target)) {
+ throw new Refused('REFERENCE_IS_BOARD', `"${target}" names a board item; use --after ${target.replace(/^#/u, '')} for a dependency or --parent for a parent item.`);
+ }
+ }
+}
diff --git a/test/references.test.js b/test/references.test.js
index 510d53d2..85b632a5 100644
--- a/test/references.test.js
+++ b/test/references.test.js
@@ -2,7 +2,11 @@
/** External references stay distinct from the board's requirement and dependency links [C7]. */
import assert from 'node:assert/strict';
import { test } from 'node:test';
+import { join } from 'node:path';
import { briefSections } from '../src/brief.js';
+import * as store from '../src/board.js';
+import { minimumMoveEngine } from '../src/move-registry.js';
+import { REFERENCE_ENGINE } from '../src/reference-engine.js';
import { createE2eHelpers } from './e2e-helpers.js';
test('reference point 19: repeated external references remain separate labelled brief entries [C7]', () => {
@@ -18,6 +22,25 @@ test('reference point 19: repeated external references remain separate labelled
assert.deepEqual(sections.test, ['node --test test/site.test.js']);
});
+test('historical brief references retain their old routing grammar and replay floor [C7,H16]', t => {
+ const e2e = createE2eHelpers();
+ const box = e2e.project('true');
+ const board = store.openBoard(join(box.repo, '.git/pullboard/board.sqlite'));
+ t.after(() => { store.closeBoard(board); e2e.cleanup(); });
+ const brief = 'Files: web/site.js\nReference: H21';
+ assert.deepEqual(briefSections(brief, { references: false }).files, ['web/site.js', 'Reference: H21']);
+ const addition = { by: 'coordinator', lane: 'web', title: 'Historical reference', brief };
+ assert.equal(minimumMoveEngine('addItem', [addition]), 1, 'unstructured historical text never gains a new replay floor');
+ assert.equal(minimumMoveEngine('editItem', [1, { agentId: 'coordinator', brief }]), 1);
+ board.executionEngineVersion = REFERENCE_ENGINE - 1;
+ const id = store.addItem(board, addition);
+ store.editItem(board, id, { agentId: 'coordinator', brief });
+ delete board.executionEngineVersion;
+ store.editItem(board, id, { agentId: 'coordinator', criterion: 'An unrelated edit preserves legacy text.' });
+ assert.equal(store.getItem(board, id).item_brief, brief);
+ assert.throws(() => store.addItem(board, addition), { code: 'REFERENCE_IS_BOARD' }, 'new moves use the new validation');
+});
+
test('reference point 22: add and edit refuse board-only references with the right flags [C7]', t => {
const e2e = createE2eHelpers();
const box = e2e.project('true');