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(spec): a lane drafts a row on the board and cites it [S1,B26]
Corey Olson9f17f37a3038
diff --git a/docs/formats.md b/docs/formats.mdindex 2cc7b87f..5fe9ef0d 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` | `2` | `SCHEMA_VERSION` in `src/board.js`, persisted as `PRAGMA user_version` | Create missing tables and indexes, add missing columns in place with declared defaults, restore missing or changed triggers, and remove stale machine triggers without replacing rows. || `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` | `52` | `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` | `55` | `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 -->Pullboard 0.6.1 released engine 1. Engine 2 records a fresh explicit-build claim's skipped-review snapshot. Pullboard 0.8.1 released engine 3, including lane-sensitive graft refusals and authenticated relay senders. Engine 4 adds captured background-baseline completions through `completeCheckBaseline`; released engine-3 clients stop with `ENGINE_VERSION` before interpreting this new operation or advancing their replay cursor. Engine 5 requires a one-line reason when releasing a review and gives that reviewer a one-hour cooldown for the current submission. Each sealed move replays under its recorded engine version: engines 1 through 4 retain the original release event and review-reservation behavior. Engine 5 retains support for older moves, including engine-4 baseline completions. Pullboard 0.8.3 released engine 6, adding board-scoped machine credentials and permitting machine execution only for one exact, earlier authenticated phone request, including its payload digest. Engine 7 adds ordered item holds through `holdItem` and `releaseItemHold`; engine-6 clients stop with `ENGINE_VERSION` before interpreting either operation or advancing their replay cursor. Engine 8, shared by the 0.8.5 move changes, retains merged-item exception notes, selects the next review in roadmap order, and adds coordinator-only `reopen` for a submission returned without a verdict; engine-7 clients stop with `ENGINE_VERSION` before interpreting this new operation or advancing their replay cursor. Recorded engines 1 through 7 retain their original tier-first review selection. Engine 8 also adds durable refusal recovery for blocked relay positions; each explicit skip publishes the readable prefix even when another unsupported record follows. Engine 8 also permits coordinator criterion/check edits on a live claim as pending corrections; the holder cannot renew or submit until a refreeze adopts the correction while preserving the claim. Older request receipts retain their recorded engine semantics. Upgrade every linked device before using the new moves. Each release shares one engine bump across its changed moves. Engine 8 also retains declared model labels on registration and records each registered agent move's model snapshot; engines 1 through 7 retain their original registration and event details without these model fields. Pullboard 0.8.8 released engine 9, which allows resubmitting the same rejected commit after a corrected criterion is refrozen, but only when the rejection names a different frozen digest. Engine 8 retains its HEAD_NOT_NEW refusal and prior submit-event detail. Engine-9 submit events add `criterionDigest`, and engine-8 boards replay with the original refusal and event history.@@ -148,6 +148,8 @@ Engine 42 adds ordered `recordHealthFindings` observations. A scan retains its bEngine 52 reopens an accepted item that conflicts with the trunk for a main merge. A `reopen` move may carry `conflict: {files, trunk}`: the files that conflict, and the full trunk commit they conflict with. The CLI takes one exact path per `--conflict <file>` flag and splits or trims nothing inside it, so a path with spaces or commas is named as Git reports it in `git merge-tree --write-tree --name-only -z`; `files` holds those exact paths, nonempty and without NUL. The CLI fills `trunk` from Git and refuses `NOT_CONFLICTING` when the accepted commit merges cleanly, or `CONFLICT_FILES` when a named file is not one Git reports as conflicting. The board refuses `NOT_ACCEPTED` unless the item is verified with an accept at its commit, and `BAD_CONFLICT` for a malformed conflict. A conflict needs no note and no landing failure; the event records `supersedes`, the accept it sets aside, `conflict`, and `cause: "refusal:MERGE_CONFLICT"`, never `landingFailure`, so rigor counts it as a merge conflict and never as a failing test. The item reads `needs main merge` until its next verdict, and the re-review checks the frozen check at the new head. A `reopen` move carrying `conflict` requires engine 52, and older engines refuse it with `RELAY_MOVE` before changing their board or cursor; a board replaying an older engine refuses it with `ENGINE_VERSION`. Moves recorded under engines 51 and earlier replay unchanged. The unlanded feature’s previous allocations were 36 and 47; it moved to 52 after the trunk reached engine 50 and milestone withdrawal was allocated engine 51, preserving every landed feature’s engine.+Engine 55 (`ROW_DRAFT_ENGINE`) adds `draftSpecRow`: an agent in a lane worktree records a drafted spec row on the board, since SPEC.md is the coordinator's file and a lane cannot write it. The move carries `row: {id, text, gate, tier, section}`; the sender plans the id across SPEC.md, the doctrine file and the board's earlier drafts, and the board refuses `ROW_ID_TAKEN` for an id it already holds. Until spec apply writes it, the commit-msg hook and `spec check` read a board draft as a draft row, so a lane cites the returned id at once and its worktree stays clean. The coordinator's `spec apply` writes each pending board draft into SPEC.md at its own id, and the person approves it there as before; a draft counts as applied once SPEC.md has its id. A move carrying `draftSpecRow` requires engine 55, and older engines refuse it before changing their board or cursor. Engines 53 and 54 are allocated to other changes.+The CLI declares its engine in every relay request's `X-Pullboard-Engine` header.A linked board requires at least engine 48 after issuing any agent token or machine credential, includingrevoked or expired ones; before engine 48 these minimums were 3 and 6. The minimum survives reopening the auth database;@@ -370,6 +372,7 @@ The `event` table is a SQLite schema object governed by `SCHEMA_VERSION`; its ap| `pass` | coordinator | `shout`, `to`, `decision`, `request`, `answers` || `answer` | answerer | `shout`, `to`, `decision`, `request`, `answers`, `outcome`, `channel`, engine-20 `implies`, `supersedes` || `row_decision` | person | `record`, `channel` |+| `row_draft` | builder | engine-55 `row` || `row_apply` | coordinator | `events` |<!-- events:end -->diff --git a/docs/formats.test.js b/docs/formats.test.jsindex 64eb8a9a..0c136ce0 100644--- a/docs/formats.test.js+++ b/docs/formats.test.js@@ -37,6 +37,7 @@ import {recordAttempt,recordRowDecisions,applyRowDecisions,+ draftSpecRow,refreeze,register,release,@@ -272,6 +273,7 @@ function recordEventContract() {answerDecision(board, request, { agentId: coordinator, text: 'done', lanes: ['docs', 'tests'] });const decisions = recordRowDecisions(board, { agentId: PERSON, channel: 'terminal', decisions: [{ kind: 'spec', file: 'SPEC.md', id: 'A1', source: '- A1 [draft] Exact row.', replacement: '- A1 [approved] Exact row.', text: 'Exact row.', decision: 'approve', reason: '' }] });applyRowDecisions(board, { agentId: coordinator, events: decisions.map((record) => record.event) });+ draftSpecRow(board, { agentId: builder, row: { id: 'A2', text: 'A lane drafted row.', gate: 'review', tier: 'must', section: 'A · Fixture' } });const freeze = (digest) => () => ({ text: `criterion-${digest}`, digest });const first = addItem(board, { by: coordinator, lane: 'docs', title: 'Accepted example', criterion: 'Initial', specIds: ['A1'], route: 'strong' });const fact = appendFact(board, first, { agentId: builder, kind: 'note', text: 'Captured evidence', ref: 'docs/formats.md:1-3@' + 'a'.repeat(40) });diff --git a/src/board.js b/src/board.jsindex 33deecc8..eebdd087 100644--- a/src/board.js+++ b/src/board.js@@ -2551,6 +2551,8 @@ export function milestones(board) {}}+// A lane agent's drafted rows live in row-drafts.js (#878); exported here so the engine dispatches them.+export { draftSpecRow, rowDrafts } from './row-drafts.js';// The roadmap's moves live in milestones.js; the board keeps exporting them so the engine replays them.export { addMilestone, canonicalMilestoneTarget, editMilestone, editMilestoneItems, orderMilestoneItems, moveMilestone, removeMilestone, roadmap, shipMilestone } from './milestones.js';diff --git a/src/cli.js b/src/cli.jsindex 1596cc27..faaebf93 100644--- a/src/cli.js+++ b/src/cli.js@@ -103,6 +103,7 @@ import {withGateSlot,} from './gate.js';import { draftRow } from './spec-draft.js';+import { pendingRowDrafts, withRowDrafts } from './row-drafts.js';import { gateWaitReporter } from './gate-wait.js';import {checkNeedsBrowser,@@ -3985,6 +3986,13 @@ async function specCommand(io, { first, second, rest, values }) {}if (values.source !== undefined) throw new Refused('FLAG_NOT_ALLOWED', 'spec draft --source belongs to --doctrine; use both when proposing a ruling');const tier = values.aim ? 'aim' : 'must';+ if (!ctx.info.isMain) {+ // A lane cannot write SPEC.md, so its draft is recorded on the board and cited at once; spec apply writes it (#878).+ const entry = await withBoard(ctx, async (board) => ordered(ctx, board, 'draftSpecRow', [{ agentId: store.agentAt(board, ctx.info.root)?.agent_id, row: draftRow(ctx.info.root, ctx.config, { target: 'spec', text: second.trim(), gate: values.gate?.trim() ?? 'review', tier, section: values.section, taken: store.rowDrafts(board).map((draft) => draft.id), write: false }).row }]));+ io.result?.({ id: entry.id, row: entry });+ io.say(entry.id);+ return 0;+ }const { id, row } = draftRow(ctx.info.root, ctx.config, { target: 'spec', text: second.trim(), gate: values.gate?.trim() ?? 'review', tier, section: values.section });io.result?.({ id, row });io.say(id);@@ -4037,6 +4045,9 @@ async function specCommand(io, { first, second, rest, values }) {return withBoard(ctx, async (board) => {const me = whoAmI(ctx, board);if (!ctx.info.isMain || me.id !== COORDINATOR) throw new Refused('COORDINATOR_ONLY', 'only the coordinator applies row decisions; ask your coordinator to run pullboard spec apply');+ // A lane's board drafts (#878) reach SPEC.md as draft rows at their own ids; the person approves them there as before.+ const drafted = pendingRowDrafts(loadSpec(ctx.info.root, ctx.config), store.rowDrafts(board)).map((draft) => draftRow(ctx.info.root, ctx.config, { target: 'spec', text: draft.text, gate: draft.gate, tier: draft.tier, section: /^(.*?)\d+$/u.exec(draft.id)[1], id: draft.id }));+ drafted.forEach((row) => io.say(`${row.file}: ${row.id} drafted from a lane, for the person to approve`));const plan = planRowApply(ctx.info.root, ctx.config, store.rowDecisions(board));writeRowApply(ctx.info.root, plan);let applied;@@ -4044,7 +4055,7 @@ async function specCommand(io, { first, second, rest, values }) {catch (error) { restoreRowApply(ctx.info.root, plan); throw error; }io.result?.({ applied, files: plan.files.map((file) => file.file) });applied.forEach((record) => io.say(`${record.file}: ${record.id} ${record.decision === 'approve' ? 'approved' : 'wont'}${record.reason ? `: ${record.reason}` : ''}`));- if (!applied.length) io.say('no pending row decisions');+ if (!applied.length && !drafted.length) io.say('no pending row decisions');else io.say('stage and commit the changed row files and any .pullboard/signoffs.jsonl receipts');return 0;});@@ -4103,7 +4114,7 @@ async function specCommand(io, { first, second, rest, values }) {findings.forEach((finding) => messages.push(`${name}:${finding.line} ${finding.id ?? ''} ${finding.level}: ${finding.message}`.replace(' ', ' ')));const history = parsed === practice ? doctrineHistory(ctx.info.root, name) : committedIds(ctx.info.root, name);const cited = name === ctx.config.spec ? citations(ctx, history) : new Map();- const lost = permanenceProblems(parsed === practice ? practice.repo : parsed, { committed: history.ids, cited });+ const lost = permanenceProblems(parsed === practice ? practice.repo : name === ctx.config.spec ? withRowDrafts(parsed, hookRead(ctx, (board) => store.rowDrafts(board))) : parsed, { committed: history.ids, cited });if (name === ctx.config.spec) {const answered = handAnsweredQuestions(previousSources.get(name) ?? [], parsed.rows, () => hookRead(ctx, (board) => store.rowDecisions(board)) ?? []);lost.push(...answered.map((id) => ({ id, message: io.guidance(`pending question answered by hand; ask the person to run pullboard spec answer ${id} "<choice or text>" and restore the pending row`) })));@@ -4275,7 +4286,7 @@ async function hookCommand(io, { first, second }) {problems = preCommitProblems({ root: info.root, isMain: info.isMain || landing, config: ctx.config, agent, boardFile: ctx.file, preMergeHook: first === 'pre-merge-commit', onNotice: (message) => io.err(`pullboard pre-commit: warning: ${message}`) });} else if (first === 'commit-msg') {const message = readFileSync(second ?? '', 'utf8');- const spec = loadSpec(info.root, ctx.config);+ const spec = withRowDrafts(loadSpec(info.root, ctx.config), hookRead(ctx, (board) => store.rowDrafts(board)));commitCitationWarnings(message, { spec, doctrine: ctx.doctrine }).forEach((warning) => io.say(`pullboard commit-msg: warning: ${warning}`));problems = commitMsgProblems(message, { rules: ctx.config.commits, spec, doctrine: ctx.doctrine });diff --git a/src/engine.js b/src/engine.jsindex 258951d3..2713c542 100644--- a/src/engine.js+++ b/src/engine.js@@ -20,13 +20,7 @@ import {} from './trunk-conflict.js';import { CHECK_ACCEPT_ENGINE } from './check-accept.js';import { HEALTH_SENTINEL_ENGINE } from './health-receipts.js';-import {- CAUSE_ENGINE,- ENGINE_VERSION,- VERIFIER_STANDING_ENGINE,- VERDICT_REVIEW_ENGINE,- MILESTONE_RANK_ENGINE,-} from './machine.js';+import { CAUSE_ENGINE, ENGINE_VERSION, VERIFIER_STANDING_ENGINE, VERDICT_REVIEW_ENGINE, MILESTONE_RANK_ENGINE, ROW_DRAFT_ENGINE } from './machine.js';import {MILESTONE_SHIP_ENGINE,canonicalMilestoneTarget,@@ -54,13 +48,13 @@ export const ENGINE_OPERATIONS = Object.freeze(['claim', 'release', 'submit', 'reserveReview', 'reserveNextReview', 'verify', 'merged','withdraw', 'refreeze', 'reopen', 'shout', 'passDecision', 'answerDecision', 'holdLane', 'releaseLane', 'holdItem', 'releaseItemHold','addMilestone', 'editMilestoneItems', 'orderMilestoneItems', 'moveMilestone', 'editMilestone', 'removeMilestone', 'shipMilestone',- 'recordRowDecisions', 'applyRowDecisions', 'appendFact',+ 'recordRowDecisions', 'applyRowDecisions', 'draftSpecRow', 'appendFact','recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'finishLandingBatch', 'acceptCheck','recordHealthFindings',]);/** Engine version at which each ordered operation first has stable replay semantics. */-const OPERATION_ENGINE = Object.freeze({ orderMilestoneItems: MILESTONE_RANK_ENGINE, reopen: 8, recordLandingBatch: 8, recordLandingWaiver: 8, recordLandingFlake: 8, finishLandingBatch: 8, acceptCheck: CHECK_ACCEPT_ENGINE,+const OPERATION_ENGINE = Object.freeze({ draftSpecRow: ROW_DRAFT_ENGINE, orderMilestoneItems: MILESTONE_RANK_ENGINE, reopen: 8, recordLandingBatch: 8, recordLandingWaiver: 8, recordLandingFlake: 8, finishLandingBatch: 8, acceptCheck: CHECK_ACCEPT_ENGINE,shipMilestone: MILESTONE_SHIP_ENGINE });/** Dependency edits, causes, sealed reviews, submission proofs, trunk conflicts, health observations and milestone targets retain distinct recorded engine meanings. */diff --git a/src/machine.js b/src/machine.jsindex 9d29f219..c6241dd2 100644--- a/src/machine.js+++ b/src/machine.js@@ -17,8 +17,12 @@ export const WITHDRAW_MILESTONE_ENGINE = 51;/** First engine that automatically escalates an item's second rejection at its current route [B15]. */export const AUTO_ESCALATE_ENGINE = 50;+/** The first engine that records a spec row a lane agent drafts on the board, not in SPEC.md (#878). */+export const ROW_DRAFT_ENGINE = 55;+/** Executable move semantics, carried by every sealed move and retained during replay [H16]. */export const ENGINE_VERSION = Math.max(+ ROW_DRAFT_ENGINE,AUTO_ESCALATE_ENGINE,RIGOR_NOTICE_ENGINE,WITHDRAW_MILESTONE_ENGINE,diff --git a/src/next-steps.js b/src/next-steps.jsindex dda6b97e..34c2ccb1 100644--- a/src/next-steps.js+++ b/src/next-steps.js@@ -495,6 +495,8 @@ export const NEXT_STEPS = Object.freeze({RUNNER_TOOLING_SECRET: 'restore a trusted Pullboard installation before transferring runner tooling',ROUTE: 'take an item your route covers: pullboard next',ROW_DECISION: 'pullboard spec approve <ids>, or pullboard spec decline <ids>',+ ROW_DRAFT: 'pullboard spec draft "<text>" from an agent seat; the person approves the returned id',+ ROW_ID_TAKEN: 'pullboard spec draft "<text>" again for the next free id',SEAL_AUTH_FAILED: 'fetch the board again, or pair this device again: pullboard relay on --all',SEAL_BINDING: 'upgrade Pullboard on this device, then retry',SEAL_CRYPTO: 'use Node 22 or newer, or a browser on a secure (https) page',diff --git a/src/relay-sender.js b/src/relay-sender.jsindex b8bf218d..410fa0ae 100644--- a/src/relay-sender.js+++ b/src/relay-sender.js@@ -12,7 +12,7 @@ export function relayMoveActor(move) {if (move.operation === 'recordHealthFindings') return args[0]?.agentId ?? null;if (['holdLane', 'releaseLane'].includes(move.operation) && args[1]?.asPerson) return 'person';if (move.operation === 'release') return args[1] ?? null;- if (['reserveNextReview', 'addMilestone', 'recordRowDecisions', 'applyRowDecisions', 'recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'finishLandingBatch'].includes(move.operation)) return args[0]?.agentId ?? null;+ if (['reserveNextReview', 'addMilestone', 'recordRowDecisions', 'applyRowDecisions', 'draftSpecRow', 'recordLandingBatch', 'recordLandingWaiver', 'recordLandingFlake', 'finishLandingBatch'].includes(move.operation)) return args[0]?.agentId ?? null;if (['acceptCheck', 'completeCheckBaseline', 'appendFact', 'editItem', 'escalate', 'recordAttempt', 'claim', 'submit', 'reserveReview', 'verify', 'merged', 'withdraw', 'refreeze','passDecision', 'answerDecision', 'holdLane', 'releaseLane', 'holdItem', 'releaseItemHold', 'reopen', 'editMilestoneItems', 'orderMilestoneItems', 'moveMilestone', 'editMilestone', 'removeMilestone', 'shipMilestone'].includes(move.operation)) return args[1]?.agentId ?? null;return null;diff --git a/src/row-drafts.js b/src/row-drafts.jsnew file mode 100644index 00000000..1004cc59--- /dev/null+++ b/src/row-drafts.js@@ -0,0 +1,52 @@+/**+ * Spec rows an agent drafts from a lane worktree (#878). SPEC.md is the coordinator's file, so a lane+ * cannot write it: the draft is recorded on the board instead, where it replays and travels over the+ * relay like any recorded move. Every reader that asks whether a cited id is live counts a board draft+ * as a draft row, so the lane cites the returned id at once and its worktree stays clean. The+ * coordinator's spec apply writes the drafts into SPEC.md, and the person approves them there as before.+ * A draft counts as applied once SPEC.md has its id, so applying needs no second move.+ */+import { atomic, logEvent, PERSON } from './board.js';+import { Refused } from './refused.js';++/** The board's recorded row drafts, oldest first. */+export function rowDrafts(board) {+ const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('row_drafts');+ return row ? JSON.parse(row.meta_value) : [];+}++/**+ * Record one drafted spec row on the board. The sender plans the id across SPEC.md, the doctrine file+ * and the board's drafts; the board refuses an id it already holds.+ *+ * @param {any} board+ * @param {{ agentId: string, row: { id: string, text: string, gate: string, tier: string, section: string } }} move+ */+export function draftSpecRow(board, { agentId, row }) {+ if (!agentId || agentId === PERSON) throw new Refused('ROW_DRAFT', 'an agent drafts a row and the person approves it; run pullboard spec draft "<text>" from an agent seat');+ if (!row || !/^[A-Z][A-Z0-9]*\d+$/u.test(String(row.id)) || ['text', 'gate', 'tier', 'section'].some((key) => typeof row[key] !== 'string' || !row[key].trim() || /[\r\n|]/u.test(row[key]))) {+ throw new Refused('ROW_DRAFT', 'a drafted row needs its id and a one-line text, gate, tier and section; run pullboard spec draft "<text>"');+ }+ return atomic(board, () => {+ const current = rowDrafts(board);+ if (current.some((draft) => draft.id === row.id)) throw new Refused('ROW_ID_TAKEN', `${row.id} is already drafted on this board; run pullboard spec draft again for the next free id`);+ logEvent(board, agentId, 'row_draft', null, { row });+ const entry = { id: row.id, text: row.text, gate: row.gate, tier: row.tier, section: row.section, by: agentId, event: board.lastEvent.event_id, at: board.lastEvent.event_at };+ board.db.prepare('INSERT INTO board_meta(meta_key,meta_value) VALUES (?,?) ON CONFLICT(meta_key) DO UPDATE SET meta_value=excluded.meta_value')+ .run('row_drafts', JSON.stringify([...current, entry]));+ return entry;+ });+}++/** Board drafts that SPEC.md does not have yet, for spec apply to write. */+export function pendingRowDrafts(spec, drafts) {+ const present = new Set(spec.rows.map((row) => row.id));+ return drafts.filter((draft) => !present.has(draft.id));+}++/** A parsed spec with the board's pending drafts added as draft rows, for readers deciding whether an id is live. */+export function withRowDrafts(spec, drafts) {+ const pending = pendingRowDrafts(spec, drafts ?? []);+ if (!pending.length) return spec;+ return { ...spec, rows: [...spec.rows, ...pending.map((draft) => ({ id: draft.id, status: 'draft', tier: draft.tier, text: draft.text, gate: draft.gate, section: draft.section, line: 0, fields: [] }))] };+}diff --git a/src/spec-draft.js b/src/spec-draft.jsindex d4258a32..d6ac8c40 100644--- a/src/spec-draft.js+++ b/src/spec-draft.js@@ -31,10 +31,10 @@ function prefixedSections(parsed) {** @param {string} root* @param {any} config- * @param {{ target: 'spec' | 'doctrine', text: string, gate: string, tier?: string, section?: string, fields?: string[] }} draft+ * @param {{ target: 'spec' | 'doctrine', text: string, gate: string, tier?: string, section?: string, fields?: string[], id?: string, taken?: string[], write?: boolean }} draft* @returns {{ id: string, file: string, line: string, row: { id: string, status: string, tier: string, text: string, gate: string, section: string } }}*/-export function draftRow(root, config, { target, text, gate, tier = 'must', section: requested, fields = [] }) {+export function draftRow(root, config, { target, text, gate, tier = 'must', section: requested, fields = [], id: fixed, taken = [], write = true }) {const spec = loadSpec(root, config);const practice = loadDoctrine(root, config);const parsed = target === 'doctrine' ? practice.repo : spec;@@ -49,8 +49,10 @@ export function draftRow(root, config, { target, text, gate, tier = 'must', sect: 'add a section heading with an id prefix such as G · Goals'}`);const malformed = [[spec.file, spec.problems], [practice.repo.file, practice.repo.problems]].find(([, problems]) => problems.length);if (malformed) throw new Refused('SPEC_INVALID', `fix the unparsed row in ${malformed[0]} before drafting; an existing id may be ambiguous`);- const id = nextRowId(section.prefix, [...spec.rows, ...practice.repo.rows]);+ // A board draft holds an id too (#878), so a new id skips them; spec apply writes a board draft at its own id.+ const id = fixed ?? nextRowId(section.prefix, [...spec.rows, ...practice.repo.rows, ...taken.map((taken) => ({ id: taken }))]);const line = [`- ${id} [draft, ${tier}] ${text} | gate: ${gate}`, ...fields].join(' | ');+ if (!write) return { id, file: name, line, row: { id, status: 'draft', tier, text, gate, section: section.name, prefix: section.prefix } };const source = readFileSync(parsed.file, 'utf8');const after = insertSectionRows(source, parsed, section, [line]);writeRowApply(root, { records: [], files: [{ file: name, before: source, after }], signoffs: { before: null, receipts: [] } });diff --git a/test/hooks.test.js b/test/hooks.test.jsindex eab71bba..8456094c 100644--- a/test/hooks.test.js+++ b/test/hooks.test.js@@ -253,3 +253,33 @@ test('a spec-less feature commit is told a path that works [S1,B26]', () => {assert.doesNotMatch(advice.join('\n'), /\[G1(?:,G2)?\]/u, 'a fenced example is never suggested as a citation');}});++test('a lane agent drafts a row and cites it without leaving its lane [S1,B26]', () => {+ const box = e2e.project('pullboard spec check');+ assert.equal(box.run(box.repo, 'add', 'web', 'Show the list', '--criterion', 'web/list.html exists').code, 0);+ const claimed = box.run(box.web, 'claim', '1');+ assert.equal(claimed.code, 0, claimed.out + claimed.err);+ const drafted = box.run(box.web, 'spec', 'draft', 'A person sees their list');+ assert.equal(drafted.code, 0, drafted.out + drafted.err);+ const id = drafted.out.trim().split('\n').at(-1);+ assert.match(id, /^G\d+$/u, `spec draft prints the new id: ${drafted.out}`);+ assert.equal(box.tryGit(box.web, 'status', '--porcelain').stdout, '', 'drafting from the lane leaves its worktree clean');+ mkdirSync(join(box.web, 'web'), { recursive: true });+ writeFileSync(join(box.web, 'web', 'list.html'), '<ul></ul>\n');+ box.git(box.web, 'add', 'web/list.html');+ const commit = box.tryGit(box.web, 'commit', '-q', '-m', `feat(web): show the list [${id}]`);+ assert.equal(commit.status, 0, `the lane cites its drafted row in a feature commit: ${commit.stderr}`);+ const submitted = box.run(box.web, 'submit', '1');+ assert.equal(submitted.code, 0, `the lane submits with the gate pullboard spec check: ${submitted.out}${submitted.err}`);++ // The coordinator's spec apply writes the board draft into SPEC.md as a draft row, and the person approves it there.+ const row = () => readFileSync(join(box.repo, 'SPEC.md'), 'utf8').split('\n').find((line) => line.startsWith(`- ${id} `));+ assert.equal(row(), undefined, 'until apply, SPEC.md does not hold the lane draft');+ const applied = box.run(box.repo, 'spec', 'apply');+ assert.equal(applied.code, 0, applied.out + applied.err);+ assert.match(applied.out, new RegExp(`${id} drafted from a lane, for the person to approve`, 'u'));+ assert.equal(row(), `- ${id} [draft, must] A person sees their list | gate: review`, 'spec apply writes the draft at its own id');+ assert.equal(box.run(box.repo, 'spec', 'approve', id).code, 0, 'the person approves the drafted row as before');+ assert.equal(box.run(box.repo, 'spec', 'apply').code, 0);+ assert.match(row(), /\[approved, must\]/u, 'the approved row is applied');+});