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(core): landing headers fill ids, then +N, rows in a trailer [C7]
Corey Olsone0f9c1f90cd5
diff --git a/docs/lifecycle.md b/docs/lifecycle.mdindex 0a57e5f9..a15dbc6c 100644--- a/docs/lifecycle.md+++ b/docs/lifecycle.md@@ -232,13 +232,13 @@ Each move checks its guards in this order and refuses with the first one that do| AGENT_GRANT_ITEM | an item mutation belongs to the current claim or review grant (accept result) | finish or release the claim, then claim the intended item; use shout for coordination || AGENT_GRANT_LANE | an item mutation stays inside the unclaimed seat lane (accept result) | join a seat in the intended lane or ask its owner to make the item change || VERDICT_ENVIRONMENT | optional recorded verdict environment contains exact platform, architecture and Node version (accept result) | run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment |-| LAND_HEADER | a displayed merge command fits the commit-header limit (accept result) | shorten the item title or cited rows so the merge header fits |+| LAND_HEADER | a displayed merge command carries a landing message that passes its own check (accept result) | shout the coordinator the item id; landing writes the message, so the item itself needs no change || ENGINE_VERSION | a verdict that implies items replays only under engine 20 or later (accept result) | upgrade Pullboard on every linked device before using --implies || AGENT_GRANT_EXPIRED | an item mutation has a live claim or review grant (reject result) | claim the intended item, or shout the coordinator if its claim is unavailable || AGENT_GRANT_ITEM | an item mutation belongs to the current claim or review grant (reject result) | finish or release the claim, then claim the intended item; use shout for coordination || AGENT_GRANT_LANE | an item mutation stays inside the unclaimed seat lane (reject result) | join a seat in the intended lane or ask its owner to make the item change || VERDICT_ENVIRONMENT | optional recorded verdict environment contains exact platform, architecture and Node version (reject result) | run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment |-| LAND_HEADER | a displayed merge command fits the commit-header limit (reject result) | shorten the item title or cited rows so the merge header fits |+| LAND_HEADER | a displayed merge command carries a landing message that passes its own check (reject result) | shout the coordinator the item id; landing writes the message, so the item itself needs no change || ENGINE_VERSION | a verdict that implies items replays only under engine 20 or later (reject result) | upgrade Pullboard on every linked device before using --implies || NOT_YOURS | the automatic escalation is authorized as the coordinator or item holder (reject result) | ask the coordinator to inspect the item and its route || CLOSED | the rejected item remains open or claimed when automatic escalation starts (reject result) | pullboard show <id>, then ask the coordinator to inspect its current state |diff --git a/src/cli.js b/src/cli.jsindex b488ab1b..c23109be 100644--- a/src/cli.js+++ b/src/cli.js@@ -386,7 +386,7 @@ import { unlinkedRelayProjects } from './relay-setup.js';import {accountedFailures,landingRemote,- landingSubject,+ landingMessage,waivedFailures,waiverLine,} from './land.js';@@ -1443,15 +1443,19 @@ export async function addBlueprint(ctx, board, me, blueprint, { report = true, r* @param {any} info* @param {any} item* @param {string} [commit] - The exact checked composition the acceptance authorizes.+ * @param {{ spec?: any }} [options] - The spec the trailer's rows are ordered by.* @returns {string}*/-export function landNext(info, item, commit = item.item_commit) {+export function landNext(info, item, commit = item.item_commit, { spec = null } = {}) {const mainRoot = primaryCheckoutRoot(info);const branch = mainCheckout(info.root)?.branch ?? '';const remote = landingRemote(info.root, branch);+ // The hand merge writes the same generated message as pullboard land: the trailers are one paragraph.+ const message = landingMessage(item, { spec });+ const trailers = `"$(printf '%s\\n' ${message.trailers.split('\n').map(shellWord).join(' ')})"`;const command = remote? 'pullboard land'- : `git merge --no-ff ${commit} -m ${shellWord(landingSubject(item))} && pullboard merged ${item.item_id} HEAD`;+ : `git merge --no-ff ${commit} -m ${shellWord(message.header)} -m ${trailers} && pullboard merged ${item.item_id} HEAD`;if (!mainRoot) return `next: could not safely locate the primary checkout; run from the main checkout: ${command}`;if (remote) return `next: the coordinator lands it: ${cdTo(mainRoot)} ${command}`;return `next: this repo has no remote for pullboard land to push to, so the coordinator merges it on ${branch.replace(/^refs\/heads\//u, '') || 'the trunk'}: ${cdTo(mainRoot)} ${command}`;diff --git a/src/commands/verify.js b/src/commands/verify.jsindex dadb12df..c3016b1a 100644--- a/src/commands/verify.js+++ b/src/commands/verify.js@@ -1,6 +1,7 @@import { outsideVerdict } from '../outside-verify.js';/** The pullboard verify command, in its own module so an item adding another command never edits these lines. */import * as store from '../board.js';+import { loadSpec } from '../spec.js';import {agentApprovalLine,itemAgentApprovals,@@ -220,7 +221,7 @@ export async function verifyHere(ctx, id, { second, values }) {ctx.io.say(result.decision === 'ACCEPT'? `verified #${id}: ${result.reason}${result.check === 'none' ? '; no frozen check ran' : ''}${approvalRows.length ? `; ${agentApprovalLine(approvalRows)}` : ''}${verifiedTiming}`: `rejected #${id}: ${result.reason}; it is open again for rework`);- if (accepted) ctx.io.say(landNext(ctx.info, accepted, acceptedLandingCommit));+ if (accepted) ctx.io.say(landNext(ctx.info, accepted, acceptedLandingCommit, { spec: loadSpec(ctx.info.root, ctx.config) }));return 0;}diff --git a/src/commit-message.js b/src/commit-message.jsnew file mode 100644index 00000000..e5761eaf--- /dev/null+++ b/src/commit-message.js@@ -0,0 +1,176 @@+/** The one builder and parser for generated commit messages: header, ids that fit, then +N, and the Pullboard trailers (RFC 0005) [C7]. */++/** A commit header's length limit, which the commit hook also enforces by default. */+export const HEADER_LIMIT = 72;++/** Trailer keys this format writes, in the order they appear. */+export const ITEM_TRAILER = 'Pullboard-Item';+export const ROWS_TRAILER = 'Pullboard-Rows';++const HEADER_RE = /^([a-z]+)(?:\(([a-z0-9._/-]+)\))?(!)?: (.*)$/u;+const MORE_RE = /^\+([1-9]\d*)$/u;+const TRAILER_RE = /^([A-Za-z][A-Za-z0-9-]*): (.*)$/u;++/**+ * Clean a title into a lower-case header subject: emoji, line breaks and bracketed text go, so a+ * title can never forge or break the id brackets that follow it.+ *+ * @param {string} title+ * @returns {string[]} The title's words.+ */+function titleWords(title) {+ return String(title ?? '').toLowerCase()+ .replace(/[\p{Extended_Pictographic}︎️]/gu, '')+ .replace(/[\r\n]+/gu, ' ')+ .replace(/\[[^\]]*\]/gu, '')+ .replace(/[[\]]/gu, '')+ .trim().split(/\s+/u).filter(Boolean);+}++/**+ * The bracket suffix for a header with `room` characters left: every id when they all fit, else the+ * first ids that fit and `+N` for the rest. `[+N]` alone always fits, because the title left room for it.+ *+ * @param {string[]} rows+ * @param {number} room+ * @returns {string} The suffix with its leading space, or '' when there are no rows.+ */+function bracket(rows, room) {+ if (!rows.length) return '';+ const all = ` [${rows.join(',')}]`;+ if (all.length <= room) return all;+ let shown = 0;+ while (shown < rows.length - 1 && ` [${[...rows.slice(0, shown + 1), `+${rows.length - shown - 1}`].join(',')}]`.length <= room) shown += 1;+ return ` [${[...rows.slice(0, shown), `+${rows.length - shown}`].join(',')}]`;+}++/**+ * Build a commit message from board facts. The title keeps priority: it takes the header up to the+ * room a `[+N]` needs, then the rows fill what is left. It never refuses for how many rows an item+ * cites: every row is in the `Pullboard-Rows` trailer whatever the header shows.+ *+ * @param {{ type: string, scope?: string, title: string, item?: number | null, rows?: string[], fallback?: string, body?: string }} message+ * rows must already be in spec order; fallback is the subject when no title word fits.+ * @returns {{ header: string, body: string, trailers: string, message: string }}+ */+export function buildCommitMessage({ type, scope = '', title, item = null, rows = [], fallback = '', body = '' }) {+ const prefix = `${type}${scope ? `(${scope})` : ''}: `;+ const reserve = rows.length ? ` [+${rows.length}]`.length : 0;+ const budget = HEADER_LIMIT - prefix.length - reserve;+ let subject = '';+ for (const word of titleWords(title)) {+ const next = subject ? `${subject} ${word}` : word;+ if (next.length > budget) break;+ subject = next;+ }+ subject = subject.replace(/\.+$/u, '');+ if (!subject) subject = (fallback || (item ? `item ${item}` : 'update')).slice(0, Math.max(1, budget));+ const head = `${prefix}${subject}`;+ const header = `${head}${bracket(rows, HEADER_LIMIT - head.length)}`;+ const trailers = [+ ...(item ? [`${ITEM_TRAILER}: #${item}`] : []),+ ...(rows.length ? [`${ROWS_TRAILER}: ${rows.join(',')}`] : []),+ ].join('\n');+ const text = String(body ?? '').trim();+ return { header, body: text, trailers, message: [header, text, trailers].filter(Boolean).join('\n\n') };+}++/**+ * The ids a header's closing brackets show, and how many more its `+N` stands for. A header with no+ * brackets shows none. Both the strict landing form `[A1,A2,+3]` and a hand-written `[A1, A2]` read.+ *+ * @param {string} header+ * @returns {{ shown: string[], more: number, rest: string }} rest is the header without its brackets.+ */+export function headerRows(header) {+ const match = /\s*\[([A-Za-z0-9:.,\s+]+)\]\s*$/u.exec(header);+ if (!match) return { shown: [], more: 0, rest: header };+ const parts = match[1].split(',').map((id) => id.trim()).filter(Boolean);+ const plus = parts.length && MORE_RE.exec(parts.at(-1));+ const shown = plus ? parts.slice(0, -1) : parts;+ if (shown.some((id) => id.startsWith('+'))) return { shown: [], more: 0, rest: header };+ return { shown, more: plus ? Number(plus[1]) : 0, rest: header.slice(0, match.index) };+}++/**+ * Parse a commit message into its header parts and trailers: the exact inverse of+ * buildCommitMessage. Trailers are read only from the last paragraph, and only when every line of it+ * is a `Key: value` trailer, so text after the trailers leaves the message with none.+ *+ * @param {string} message+ * @returns {{ header: string, type: string | null, scope: string, breaking: boolean, title: string,+ * shown: string[], more: number, body: string, trailers: { key: string, value: string }[],+ * item: number | null, rows: string[] | null }}+ */+export function parseCommitMessage(message) {+ const text = String(message ?? '').replace(/\r\n/gu, '\n').replace(/\s+$/u, '');+ const [header = '', ...restLines] = text.split('\n');+ const paragraphs = restLines.join('\n').split(/\n{2,}/u).map((part) => part.replace(/^\n+|\n+$/gu, '')).filter(Boolean);+ const last = paragraphs.at(-1) ?? '';+ const lines = last.split('\n');+ const isTrailers = Boolean(last) && lines.every((line) => TRAILER_RE.test(line));+ const trailers = isTrailers ? lines.map((line) => { const [, key, value] = TRAILER_RE.exec(line); return { key, value: value.trim() }; }) : [];+ const body = (isTrailers ? paragraphs.slice(0, -1) : paragraphs).join('\n\n');+ const itemValue = trailers.find((entry) => entry.key === ITEM_TRAILER)?.value;+ const rowsValue = trailers.find((entry) => entry.key === ROWS_TRAILER)?.value;+ const typed = HEADER_RE.exec(header);+ const { shown, more, rest } = headerRows(header);+ const subject = typed ? HEADER_RE.exec(rest)?.[4] ?? '' : rest;+ return {+ header,+ type: typed ? typed[1] : null,+ scope: typed?.[2] ?? '',+ breaking: Boolean(typed?.[3]),+ title: subject,+ shown,+ more,+ body,+ trailers,+ item: itemValue && /^#[1-9]\d*$/u.test(itemValue) ? Number(itemValue.slice(1)) : null,+ rows: rowsValue === undefined ? null : rowsValue.split(',').filter(Boolean),+ };+}++/**+ * Every way a generated message differs from what the board says it must carry: the header limit,+ * the item trailer, the rows trailer and the header's ids being the first rows plus `+N` for the rest.+ * A landing checks every message with this before its first merge.+ *+ * @param {string} message+ * @param {{ item: number, rows: string[] }} expected - rows in spec order.+ * @returns {string[]}+ */+export function commitMessageProblems(message, { item, rows }) {+ const parsed = parseCommitMessage(message);+ const problems = [];+ if (parsed.header.length > HEADER_LIMIT) problems.push(`its header has ${parsed.header.length} characters, over ${HEADER_LIMIT}`);+ if (!parsed.type) problems.push('its header has no type(scope): prefix');+ if (parsed.item !== item) problems.push(`its ${ITEM_TRAILER} trailer is not #${item}`);+ const written = parsed.rows ?? [];+ if (written.join(',') !== rows.join(',')) problems.push(`its ${ROWS_TRAILER} trailer is not ${rows.join(',') || 'absent'}`);+ if (!rows.length && parsed.rows !== null) problems.push(`an item that cites no rows has no ${ROWS_TRAILER} trailer`);+ const prefix = rows.slice(0, parsed.shown.length);+ if (prefix.join(',') !== parsed.shown.join(',') || parsed.shown.length + parsed.more !== rows.length) {+ problems.push('its header ids are not the first rows followed by +N for the rest');+ }+ return problems;+}++/**+ * Order cited rows as the spec lists them; doctrine and unknown ids follow in citation order, so+ * the same cited set always writes the same trailer.+ *+ * @param {string[]} ids+ * @param {{ rows: { id: string }[] } | null} spec+ * @returns {string[]}+ */+export function specOrder(ids, spec) {+ const unique = [...new Set(ids.map((id) => String(id).trim()).filter(Boolean))];+ if (!spec?.rows?.length) return unique;+ const position = new Map();+ spec.rows.forEach((row, index) => { if (!position.has(row.id)) position.set(row.id, index); });+ return unique+ .map((id, index) => ({ id, index, at: position.get(id) ?? Infinity }))+ .sort((left, right) => left.at - right.at || left.index - right.index)+ .map((entry) => entry.id);+}diff --git a/src/land.js b/src/land.jsindex a6cf97e5..7a1ff13f 100644--- a/src/land.js+++ b/src/land.js@@ -64,6 +64,12 @@ import { runLandingWorker } from './landing-worker.js';import { runLandingCandidateWorker } from './landing-candidates.js';import { inheritedGateSlot } from './resources.js';import { Refused } from './refused.js';+import {+ buildCommitMessage,+ commitMessageProblems,+ specOrder,+} from './commit-message.js';+import { loadSpec } from './spec.js';import { requireLandingHost } from './landing-host.js';import {environmentLabel,@@ -155,23 +161,68 @@ export function landingFailures(output, root, { excludeCancelled = false } = {})/** The merge header type an item with no spec rows takes from its lane; any other lane lands as chore. */const LANE_MERGE_TYPES = Object.freeze({ docs: 'docs', test: 'test' });-/** Produce a hook-valid lower-case merge subject at a word boundary [R3]. */-export function landingSubject(item) {- const suffix = item.item_spec_ids ? ` [${item.item_spec_ids.split(/[\s,]+/u).filter(Boolean).join(',')}]` : '';+/**+ * The rows a landing names: the item's final frozen set when it has one, since a refreeze after the+ * claim is what the verdict checked, else its cited ids; in spec order when the spec is at hand.+ *+ * @param {any} item+ * @param {{ rows: { id: string }[] } | null} [spec]+ * @returns {string[]}+ */+export function landingRows(item, spec = null) {+ let frozen = null;+ try { frozen = item.item_frozen ? JSON.parse(item.item_frozen) : null; } catch { frozen = null; }+ const ids = Array.isArray(frozen?.rows)+ ? frozen.rows.map((row) => row.id)+ : String(item.item_spec_ids ?? '').split(/[\s,]+/u);+ return specOrder(ids.filter(Boolean), spec);+}++/**+ * The whole landing message from board state through the shared builder [B3,R3]: header+ * `<type>(merge): <title> [<rows that fit>,+N]`, then `Pullboard-Item` and `Pullboard-Rows` as the+ * last paragraph. It never refuses for how many rows an item cites.+ *+ * @param {any} item+ * @param {{ spec?: { rows: { id: string }[] } | null }} [options]+ * @returns {{ header: string, body: string, trailers: string, message: string, rows: string[] }}+ */+export function landingMessage(item, { spec = null } = {}) {+ const rows = landingRows(item, spec);// An item with no rows cites none, so its merge header names its lane's type: docs or test; anything else is chore (B3).- const type = item.item_spec_ids ? 'chore' : (LANE_MERGE_TYPES[item.item_lane] ?? 'chore');- const prefix = `${type}(merge): `;- const budget = 72 - prefix.length - suffix.length;- if (budget < 1) throw new Refused('LAND_HEADER', `item #${item.item_id} cites too many rows for a merge header; shorten its cited set before landing`);- const words = item.item_title.toLowerCase().replace(/[\p{Extended_Pictographic}\u200d\uFE0E\uFE0F]/gu, '').replace(/[\r\n]+/gu, ' ').replace(/\[[^\]]*\]/gu, '').trim().split(/\s+/u);- let subject = '';- for (const word of words) {- if ((subject ? `${subject} ${word}` : word).length > budget) break;- subject = subject ? `${subject} ${word}` : word;+ const type = rows.length ? 'chore' : (LANE_MERGE_TYPES[item.item_lane] ?? 'chore');+ return { ...buildCommitMessage({ type, scope: 'merge', title: item.item_title, item: item.item_id, rows }), rows };+}++/** Produce a hook-valid lower-case merge header at a word boundary [R3]. */+export function landingSubject(item, options = {}) {+ return landingMessage(item, options).header;+}++/**+ * Check every item's landing message before the first merge of a batch [B3,R3]. The builder+ * writes them, so a problem here is a Pullboard defect, never something an item's citations fix.+ *+ * @param {any[]} items+ * @param {{ rows: { id: string }[] } | null} spec+ * @returns {Map<number, ReturnType<typeof landingMessage>>}+ */+export function checkLandingMessages(items, spec) {+ const messages = new Map();+ for (const item of items) {+ const built = landingMessage(item, { spec });+ const problems = commitMessageProblems(built.message, { item: item.item_id, rows: built.rows });+ if (problems.length) {+ throw new Refused('LAND_HEADER', `the landing message for #${item.item_id} fails its own check (${problems.join('; ')}); nothing merged; shout the coordinator: pullboard shout coordinator "#${item.item_id} landing message fails its check"`);+ }+ messages.set(item.item_id, built);}- if (!subject) subject = `item ${item.item_id}`.length <= budget ? `item ${item.item_id}` : String(item.item_id);- if (subject.length > budget) throw new Refused('LAND_HEADER', `item #${item.item_id} has no title word that fits its merge header; shorten its cited set before landing`);- return `${prefix}${subject.replace(/\.$/u, '')}${suffix}`;+ return messages;+}++/** The trunk spec a landing orders rows by, or none when the repo has no spec file. */+function landingSpec(root, config) {+ return config?.spec ? loadSpec(root, config) : null;}/** Keep the submitted identity and, when different, its sealed checked composition. */@@ -255,6 +306,8 @@ async function mergeGroup(state, items) {const { batch } = state;if (!isClean(batch.root) || untracked(batch.root).length) throw new Refused('LAND_DIRTY', 'the landing worktree has unfinished edits; inspect its recorded path before adopting');git(batch.root, ['checkout', '--detach', batch.base]);+ // Every message is built and checked before the first merge, so a bad one cannot land half a batch.+ const messages = checkLandingMessages(items.map((entry) => store.getItem(state.board, entry.id ?? entry.item_id)), landingSpec(batch.root, state.config));const merged = [];const conflicts = [];const resolutions = [];@@ -266,17 +319,19 @@ async function mergeGroup(state, items) {if (checked !== (entry.reviewedCommit ?? entry.commit ?? item.item_commit)) throw new Refused('LAND_ITEM_MOVED', `item #${item.item_id} was re-reviewed; rebuild its landing from the checked commit`);const stale = verdictProjector(state.root, state.board, { main: batch.base }).state(item);if (stale) throw staleVerdictRefusal(item, stale);- // The body is the item trailer alone: the subject carries the title, and no lane branch is named [B3,R3].+ // The body is the trailer paragraph alone: the header carries the title, and no lane branch is named [B3,R3].// merge.log is switched off on this call, so a local Git config cannot append a shortlog to the body.const trunk = headCommit(batch.root);- const result = tryGit(batch.root, ['-c', 'merge.log=false', 'merge', '--no-ff', '--no-log', checked, '-m', landingSubject(item), '-m', `Pullboard-Item: #${item.item_id}`]);+ const message = messages.get(item.item_id);+ const result = tryGit(batch.root, ['-c', 'merge.log=false', 'merge', '--no-ff', '--no-log', checked, '-m', message.header, '-m', message.trailers]);if (result.status !== 0) {const files = tryGit(batch.root, ['diff', '--name-only', '--diff-filter=U']).stdout.split('\n').filter(Boolean);if (!files.length) throw new Refused('LAND_MERGE', `merge of #${item.item_id} failed outside a conflict: ${result.stderr || result.stdout}; inspect ${batch.root} and its hooks before adopting`);const resolved = resolveMechanicalMerge(batch.root, files);if (resolved) {git(batch.root, ['add', '--', ...files]);- git(batch.root, ['commit', '--no-edit']);+ // The message is written again, so Git's conflict notes can never follow the trailers.+ git(batch.root, ['commit', '-m', message.header, '-m', message.trailers]);resolutions.push({ id: item.item_id, files, entries: resolved });state.say(`mechanical merge #${item.item_id}: ${files.join(', ')}`);} else {@@ -1306,6 +1361,7 @@ export async function runLandingBatch({ root, board, config, write, say, owner,}const selected = candidates(board, root, trunk.commit, maximum);if (!dryRun) for (const item of selected.ready) requireOutsideOwner(board, item);+ checkLandingMessages(selected.ready, landingSpec(root, config));const stale = selected.blocked.find(item => item.code === 'STALE_VERDICT');if (!selected.ready.length && stale) throw staleVerdictRefusal({ item_id: stale.id }, stale);if (dryRun) {diff --git a/src/machine.js b/src/machine.jsindex 254c7ad0..0e172bbd 100644--- a/src/machine.js+++ b/src/machine.js@@ -194,13 +194,13 @@ export const MOVES = [{verb: 'accept', from: ['submitted', 'verified'], to: 'verified', by: ['agent', 'coordinator'], refuse: 'NOT_SUBMITTED',guards: ['coordinatorSaysAs', 'joined', 'itemExists', IN_STATE, 'atSubmittedCommit', 'notMerged', 'verdictReviewRecorded', 'reviewTreeCurrent', 'notBuilder', 'routeAllows', 'policyAllows', 'familyAllows', 'reviewFree', 'criterionUnchanged', 'reasonIsMet', 'trunkMergeClean', 'noUnverifiedStack', 'queuedItemLease', 'itemCheckGreen', 'proofRecorded', 'proofNoted'],- alsoRefuses: [...AGENT_GRANT_REFUSALS, { code: 'VERDICT_ENVIRONMENT', rule: 'optional recorded verdict environment contains exact platform, architecture and Node version', next: 'run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment' }, { code: 'LAND_HEADER', rule: 'a displayed merge command fits the commit-header limit', next: 'shorten the item title or cited rows so the merge header fits' }, { code: 'ENGINE_VERSION', rule: 'a verdict that implies items replays only under engine 20 or later', next: 'upgrade Pullboard on every linked device before using --implies' }],+ alsoRefuses: [...AGENT_GRANT_REFUSALS, { code: 'VERDICT_ENVIRONMENT', rule: 'optional recorded verdict environment contains exact platform, architecture and Node version', next: 'run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment' }, { code: 'LAND_HEADER', rule: 'a displayed merge command carries a landing message that passes its own check', next: 'shout the coordinator the item id; landing writes the message, so the item itself needs no change' }, { code: 'ENGINE_VERSION', rule: 'a verdict that implies items replays only under engine 20 or later', next: 'upgrade Pullboard on every linked device before using --implies' }],sets: ['item_verified_by'], command: 'pullboard verify <id> accept --note "..."',},{verb: 'reject', from: ['submitted', 'verified'], to: 'open', by: ['agent', 'coordinator'], refuse: 'NOT_SUBMITTED',guards: ['coordinatorSaysAs', 'joined', 'itemExists', IN_STATE, 'atSubmittedCommit', 'notMerged', 'verdictReviewRecorded', 'reviewTreeCurrent', 'notBuilder', 'routeAllows', 'policyAllows', 'familyAllows', 'reviewFree', 'criterionUnchanged', 'reasonCoded', 'noteGiven', 'causeWellFormed'],- alsoRefuses: [...AGENT_GRANT_REFUSALS, { code: 'VERDICT_ENVIRONMENT', rule: 'optional recorded verdict environment contains exact platform, architecture and Node version', next: 'run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment' }, { code: 'LAND_HEADER', rule: 'a displayed merge command fits the commit-header limit', next: 'shorten the item title or cited rows so the merge header fits' }, { code: 'ENGINE_VERSION', rule: 'a verdict that implies items replays only under engine 20 or later', next: 'upgrade Pullboard on every linked device before using --implies' }, { code: 'NOT_YOURS', rule: 'the automatic escalation is authorized as the coordinator or item holder', next: 'ask the coordinator to inspect the item and its route' }, { code: 'CLOSED', rule: 'the rejected item remains open or claimed when automatic escalation starts', next: 'pullboard show <id>, then ask the coordinator to inspect its current state' }],+ alsoRefuses: [...AGENT_GRANT_REFUSALS, { code: 'VERDICT_ENVIRONMENT', rule: 'optional recorded verdict environment contains exact platform, architecture and Node version', next: 'run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment' }, { code: 'LAND_HEADER', rule: 'a displayed merge command carries a landing message that passes its own check', next: 'shout the coordinator the item id; landing writes the message, so the item itself needs no change' }, { code: 'ENGINE_VERSION', rule: 'a verdict that implies items replays only under engine 20 or later', next: 'upgrade Pullboard on every linked device before using --implies' }, { code: 'NOT_YOURS', rule: 'the automatic escalation is authorized as the coordinator or item holder', next: 'ask the coordinator to inspect the item and its route' }, { code: 'CLOSED', rule: 'the rejected item remains open or claimed when automatic escalation starts', next: 'pullboard show <id>, then ask the coordinator to inspect its current state' }],command: 'pullboard verify <id> reject --reason CODE --note "..."',},{diff --git a/src/moves/verify.js b/src/moves/verify.jsindex 44116bef..05845f19 100644--- a/src/moves/verify.js+++ b/src/moves/verify.js@@ -57,7 +57,7 @@ export default Object.freeze({ operation: "verify", order: 18, engine: 1,"GUARD_CANNOT_FAIL": "reject: the check does not test the guard; ask for one that fails with the guard reverted: pullboard verify <id> reject --reason TEST_FAILURE --note \"<what the check missed>\"","GUARD_NOT_FOUND": "reject: the named guard is not in the submitted commit; fix the guard line in the criterion with the coordinator: pullboard shout coordinator --decision \"<id> guard does not match the commit\"","ITEM_LEASE_LOST": "read pullboard show <id>; if the item is free, claim it again for a build or reserve it with pullboard next --verify <id> for a review, then retry",- "LAND_HEADER": "shorten the item's cited rows (pullboard edit <id>), then pullboard land",+ "LAND_HEADER": "shout the coordinator: pullboard shout coordinator \"#<id> landing message fails its check\"","MAIN_IS_COORDINATOR": "use an independent agent checkout for agent work, or run person-only actions from the main checkout as the coordinator","MERGE_CHECK_FAILED": "use Git 2.38 or newer (git --version), then retry","MERGE_CONFLICT": "merge main into your branch, resolve the conflicts, commit, and run the command again",diff --git a/src/spec.js b/src/spec.jsindex 0a3c7e39..14c4fee1 100644--- a/src/spec.js+++ b/src/spec.js@@ -26,6 +26,7 @@ import {} from './config.js';import { cleanGitEnvironment } from './git.js';import { Refused } from './refused.js';+import { headerRows } from './commit-message.js';import {parseRowVerification,rowVerificationFormatProblems,@@ -572,15 +573,14 @@ export function signOff(root, spec, { ids, by, on, note = '', commit = '' }) {}/**- * Spec ids cited at the end of a commit header: `feat(x): subject [G1.2,K3]`.+ * Spec ids cited at the end of a commit header: `feat(x): subject [G1.2,K3]`. A landing header's+ * `+N` stands for rows only its trailer names, so it is not an id; the shared parser reads both.** @param {string} header* @returns {string[]}*/export function citedIds(header) {- const match = /\[([A-Za-z0-9:.,\s]+)\]\s*$/.exec(header);- if (!match) return [];- return match[1].split(',').map((id) => id.trim()).filter(Boolean);+ return headerRows(header).shown;}/**diff --git a/test/commit-message.test.js b/test/commit-message.test.jsnew file mode 100644index 00000000..67a0e655--- /dev/null+++ b/test/commit-message.test.js@@ -0,0 +1,116 @@+/** The shared commit-message builder and parser: ids fill what fits, then +N, with every row in a trailer (RFC 0005) [C7,B3,R3]. */+import assert from 'node:assert/strict';+import { test } from 'node:test';+import {+ HEADER_LIMIT,+ buildCommitMessage,+ commitMessageProblems,+ headerRows,+ parseCommitMessage,+ specOrder,+} from '../src/commit-message.js';+import { checkLandingMessages, landingMessage, landingRows } from '../src/land.js';+import { citedIds, parseSpec } from '../src/spec.js';++/** Row ids A1..An, the shape a long cited set takes. */+const rowsUpTo = (count, letter = 'A') => Array.from({ length: count }, (_, index) => `${letter}${index + 1}`);++/** Parse a built message and build it again from the parse: both directions must be exact. */+function roundTrip(input) {+ const built = buildCommitMessage(input);+ const parsed = parseCommitMessage(built.message);+ assert.equal(parsed.header, built.header);+ assert.equal(parsed.type, input.type);+ assert.equal(parsed.scope, input.scope);+ assert.equal(parsed.item, input.item);+ assert.deepEqual(parsed.rows, input.rows.length ? input.rows : null, 'Pullboard-Rows carries every row, or is absent');+ assert.deepEqual(parsed.shown, input.rows.slice(0, parsed.shown.length), 'the header shows the first rows');+ assert.equal(parsed.shown.length + parsed.more, input.rows.length, '+N counts exactly the rows the header leaves out');+ const again = buildCommitMessage({ type: parsed.type, scope: parsed.scope, title: parsed.title, item: parsed.item, rows: parsed.rows ?? [] });+ assert.equal(again.message, built.message, 'building from the parse writes the same bytes');+ assert.deepEqual(commitMessageProblems(built.message, { item: input.item, rows: input.rows }), []);+ assert.ok(built.header.length <= HEADER_LIMIT, built.header);+ assert.deepEqual(parsed.trailers.map((entry) => entry.key), ['Pullboard-Item', ...(input.rows.length ? ['Pullboard-Rows'] : [])], 'the trailers come in the fixed order');+ assert.ok(built.message.endsWith(built.trailers), 'the trailers are the last paragraph');+ return { built, parsed };+}++test('one row: the header shows it and the trailers name the item then the row [C7,B3,R3]', () => {+ const { built } = roundTrip({ type: 'feat', scope: 'merge', title: 'Person-only moves are signed', item: 408, rows: ['E22'] });+ assert.equal(built.message, 'feat(merge): person-only moves are signed [E22]\n\nPullboard-Item: #408\nPullboard-Rows: E22');+});++test('many consecutive rows fill the header, then +N stands for the rest [C7,B3,R3]', () => {+ const twelve = roundTrip({ type: 'chore', scope: 'merge', title: 'Land the batch', item: 7, rows: rowsUpTo(12) });+ assert.equal(twelve.built.header, 'chore(merge): land the batch [A1,A2,A3,A4,A5,A6,A7,A8,A9,A10,A11,A12]', 'every row shows when they all fit');+ const twenty = roundTrip({ type: 'chore', scope: 'merge', title: 'Land the batch', item: 7, rows: rowsUpTo(20) });+ assert.equal(twenty.built.header, 'chore(merge): land the batch [A1,A2,A3,A4,A5,A6,A7,A8,A9,A10,A11,+9]');+ assert.equal(twenty.parsed.more, 9);+ // The ids fill what fits: one more shown id would cross the limit.+ const longer = `chore(merge): land the batch [${[...rowsUpTo(12), '+8'].join(',')}]`;+ assert.ok(longer.length > HEADER_LIMIT, longer);+});++test('scattered ids land in spec order, doctrine rows after the spec rows [C7,B3,R3]', () => {+ const spec = parseSpec('# Spec\n\n## A\n- A2 [approved, must] Two.\n## C\n- C7 [approved, must] Seven.\n## M\n- M3 [approved, must] Three.\n## Z\n- Z9 [approved, must] Nine.\n');+ const rows = specOrder(['Z9', 'doctrine:PB1', 'A2', 'M3', 'C7', 'A2'], spec);+ assert.deepEqual(rows, ['A2', 'C7', 'M3', 'Z9', 'doctrine:PB1'], 'spec order, duplicates once, doctrine last');+ const { built } = roundTrip({ type: 'chore', scope: 'merge', title: 'Scattered rows land', item: 9, rows });+ assert.equal(built.message, 'chore(merge): scattered rows land [A2,C7,M3,Z9,doctrine:PB1]\n\nPullboard-Item: #9\nPullboard-Rows: A2,C7,M3,Z9,doctrine:PB1');+});++test('36 rows never refuse: the header keeps the title and the trailer keeps all 36 [C7,B3,R3]', () => {+ const rows = rowsUpTo(36);+ const { built, parsed } = roundTrip({ type: 'docs', scope: 'merge', title: 'Update the handbook', item: 1326, rows });+ assert.equal(built.header, 'docs(merge): update the handbook [A1,A2,A3,A4,A5,A6,A7,A8,A9,A10,+26]');+ assert.equal(built.trailers, `Pullboard-Item: #1326\nPullboard-Rows: ${rows.join(',')}`);+ assert.equal(parsed.rows.length, 36);+ // The title keeps priority: a title that needs the whole header still lands, showing only +N.+ const long = roundTrip({ type: 'chore', scope: 'merge', title: 'A VERY LONG TITLE '.repeat(10), item: 91, rows });+ assert.equal(long.built.header, 'chore(merge): a very long title a very long title a very long [+36]');+});++test('no rows: no brackets and no Pullboard-Rows trailer [C7,B3,R3]', () => {+ const { built, parsed } = roundTrip({ type: 'test', scope: 'merge', title: 'Every test run an agent starts goes through the runner pool', item: 1219, rows: [] });+ assert.equal(built.message, 'test(merge): every test run an agent starts goes through the runner pool\n\nPullboard-Item: #1219');+ assert.equal(parsed.rows, null);+ assert.deepEqual(parsed.shown, []);+});++test('the parser reads trailers only as the last paragraph and +N is never an id [C7,B3,R3]', () => {+ const parsed = parseCommitMessage('fix(core): read the rows [A1,A2,+3]\n\nWhy it matters.\n\nPullboard-Item: #12\nPullboard-Rows: A1,A2,A3,A4,A5\n');+ assert.deepEqual({ type: parsed.type, scope: parsed.scope, title: parsed.title, shown: parsed.shown, more: parsed.more, body: parsed.body, item: parsed.item, rows: parsed.rows },+ { type: 'fix', scope: 'core', title: 'read the rows', shown: ['A1', 'A2'], more: 3, body: 'Why it matters.', item: 12, rows: ['A1', 'A2', 'A3', 'A4', 'A5'] });+ const trailing = parseCommitMessage('fix(core): read the rows [A1]\n\nPullboard-Item: #12\n\ntext after the trailers');+ assert.equal(trailing.item, null, 'text after the trailers leaves the message with none');+ assert.deepEqual(citedIds('chore(merge): land it [A1,A2,+34]'), ['A1', 'A2']);+ assert.deepEqual(citedIds('chore(merge): land it [+36]'), []);+ assert.deepEqual(citedIds('feat(web): add the page [G1, K1.2]'), ['G1', 'K1.2'], 'a hand-written header still reads');+ assert.deepEqual(headerRows('fix: handle [x] in the middle of text'), { shown: [], more: 0, rest: 'fix: handle [x] in the middle of text' });+ assert.deepEqual(commitMessageProblems('chore(merge): land it [A2,+1]\n\nPullboard-Item: #3\nPullboard-Rows: A1,A2', { item: 3, rows: ['A1', 'A2'] }),+ ['its header ids are not the first rows followed by +N for the rest']);+});++test('a landing names the refrozen rows in spec order, and a batch checks every message before merging [C7,B3,R3]', () => {+ const spec = parseSpec('# Spec\n\n## A\n- A1 [approved, must] One.\n- A2 [approved, must] Two.\n- A3 [approved, must] Three.\n');+ const claimed = { item_id: 5, item_lane: 'core', item_title: 'Refrozen rows', item_spec_ids: 'A3,A1',+ item_frozen: JSON.stringify({ title: 'Refrozen rows', criterion: 'c', rows: [{ id: 'A3' }, { id: 'A1' }] }) };+ assert.deepEqual(landingRows(claimed, spec), ['A1', 'A3']);+ // A refreeze after the claim replaced the frozen set: the landing writes the final frozen rows.+ const refrozen = { ...claimed, item_frozen: JSON.stringify({ title: 'Refrozen rows', criterion: 'c2', rows: [{ id: 'A3' }, { id: 'A2' }, { id: 'A1' }] }) };+ assert.equal(landingMessage(refrozen, { spec }).message, 'chore(merge): refrozen rows [A1,A2,A3]\n\nPullboard-Item: #5\nPullboard-Rows: A1,A2,A3');+ const none = { item_id: 6, item_lane: 'docs', item_title: 'No rows', item_spec_ids: '', item_frozen: JSON.stringify({ rows: [] }) };+ assert.equal(landingMessage(none, { spec }).message, 'docs(merge): no rows\n\nPullboard-Item: #6');+ const many = { item_id: 8, item_lane: 'core', item_title: 'Many rows', item_spec_ids: rowsUpTo(36).join(',') };+ assert.equal(landingMessage(many).rows.length, 36, 'no citation count refuses');+ const checked = checkLandingMessages([refrozen, none, many], spec);+ assert.deepEqual([...checked.keys()], [5, 6, 8]);+ // A malformed row id (never written by the spec) fails the check for the whole batch, naming the item.+ const broken = { ...many, item_id: 9, item_spec_ids: '', item_frozen: JSON.stringify({ rows: [{ id: 'A1' }, { id: 'A2,A3' }] }) };+ assert.throws(() => checkLandingMessages([refrozen, broken], spec), (error) => {+ assert.equal(error.code, 'LAND_HEADER');+ assert.match(error.message, /#9/u);+ assert.doesNotMatch(error.message, /shorten|cut|remove|fewer|cited set/iu, 'no refusal advises removing citations');+ return true;+ });+});diff --git a/test/land-next.test.js b/test/land-next.test.jsindex a4d97dfb..2faefe9e 100644--- a/test/land-next.test.js+++ b/test/land-next.test.js@@ -13,6 +13,9 @@ const { project, commitFile } = e2e;/** Escape literal text, such as a sandbox path, for a regular expression. */const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');+/** The trailer paragraph a hand merge writes for an item citing G1, as the accept prints it [B3]. */+const trailerArg = (id) => `-m "$(printf '%s\\n' 'Pullboard-Item: #${id}' 'Pullboard-Rows: G1')"`;+/** File, build, submit and accept one web item through the real CLI and hooks, returning the accept output. */function acceptedItem(box, file, { beforeVerify = () => {} } = {}) {const added = box.run(box.repo, 'add', 'web', `Write ${file}`, '--specs', 'G1', '--criterion', `${file} exists`, '--check', `test -f ${file}`, '--json');@@ -52,7 +55,7 @@ test('an accept says how to land, and a dry run catches a missing origin [I1,B3]// Clause 1, repo without a remote: the accept prints the exact git merge command for this repo.const first = acceptedItem(box, 'web/first.txt');- const merge = new RegExp(`^next: this repo has no remote for pullboard land to push to, so the coordinator merges it on main: (cd ${literal(box.repo)} && git merge --no-ff ${first.commit} -m 'chore\\(merge\\): write web/first\\.txt \\[G1\\]' && pullboard merged ${first.id} HEAD)$`, 'mu');+ const merge = new RegExp(`^next: this repo has no remote for pullboard land to push to, so the coordinator merges it on main: (cd ${literal(box.repo)} && git merge --no-ff ${first.commit} -m 'chore\\(merge\\): write web/first\\.txt \\[G1\\]' ${literal(trailerArg(first.id))} && pullboard merged ${first.id} HEAD)$`, 'mu');const printed = merge.exec(first.out);assert.ok(printed, `the accept names the hand merge for a repo without origin:\n${first.out}`);@@ -67,6 +70,8 @@ test('an accept says how to land, and a dry run catches a missing origin [I1,B3]const ran = spawnSync('/bin/sh', ['-c', printed[1]], { cwd: box.dir, env: box.env, encoding: 'utf8' });assert.equal(ran.status, 0, `${ran.stdout}${ran.stderr}`);assert.equal(box.tryGit(box.repo, 'merge-base', '--is-ancestor', first.commit, 'main').status, 0, 'main now carries the accepted commit');+ assert.equal(box.git(box.repo, 'log', '-1', '--format=%B', 'main'), `chore(merge): write web/first.txt [G1]\n\nPullboard-Item: #${first.id}\nPullboard-Rows: G1`,+ 'the hand merge writes the generated header and the trailers as its last paragraph');const shown = JSON.parse(box.run(box.repo, 'show', String(first.id), '--json').out);assert.equal(shown.item_merged_commit, box.git(box.repo, 'rev-parse', 'main'));@@ -85,7 +90,7 @@ test('an accept says how to land, and a dry run catches a missing origin [I1,B3]test('an accept names the primary checkout when Git metadata is stored separately [I1,B3]', () => {const box = withReviewer(project(undefined, undefined, { separateGitDir: true }));const accepted = acceptedItem(box, 'web/separate.txt');- const merge = new RegExp(`^next: this repo has no remote for pullboard land to push to, so the coordinator merges it on main: (cd ${literal(box.repo)} && git merge --no-ff ${accepted.commit} -m 'chore\\(merge\\): write web/separate\\.txt \\[G1\\]' && pullboard merged ${accepted.id} HEAD)$`, 'mu');+ const merge = new RegExp(`^next: this repo has no remote for pullboard land to push to, so the coordinator merges it on main: (cd ${literal(box.repo)} && git merge --no-ff ${accepted.commit} -m 'chore\\(merge\\): write web/separate\\.txt \\[G1\\]' ${literal(trailerArg(accepted.id))} && pullboard merged ${accepted.id} HEAD)$`, 'mu');const printed = merge.exec(accepted.out);assert.ok(printed, `the accept names the actual primary checkout for separate Git metadata:\n${accepted.out}`);@@ -97,7 +102,7 @@ test('an accept names the primary checkout when Git metadata is stored separatelconst fallback = acceptedItem(unregistered, 'web/fallback.txt', {beforeVerify: () => rmSync(join(unregistered.env.PULLBOARD_HOME, 'projects.json'), { force: true }),});- const mergeCommand = `git merge --no-ff ${fallback.commit} -m 'chore(merge): write web/fallback.txt [G1]' && pullboard merged ${fallback.id} HEAD`;+ const mergeCommand = `git merge --no-ff ${fallback.commit} -m 'chore(merge): write web/fallback.txt [G1]' ${trailerArg(fallback.id)} && pullboard merged ${fallback.id} HEAD`;assert.ok(fallback.out.includes(`next: could not safely locate the primary checkout; run from the main checkout: ${mergeCommand}`), fallback.out);assert.doesNotMatch(fallback.out, /\bcd\s/u, 'an unvalidated path is never guessed');const ranFallback = spawnSync('/bin/sh', ['-c', mergeCommand], { cwd: unregistered.repo, env: unregistered.env, encoding: 'utf8' });diff --git a/test/move-registry-baseline.json b/test/move-registry-baseline.jsonindex f5815f79..ead9759e 100644--- a/test/move-registry-baseline.json+++ b/test/move-registry-baseline.json@@ -6719,7 +6719,7 @@"LAND_DIRTY": "inspect the landing worktree, commit or remove its edits, then pullboard land --adopt","LAND_FLAKE": "fix the flaky test, or ask the person for a waiver: pullboard land --waive <test> --until <date> --reason \"why\"","LAND_HOST_NOT_JOINED": "on the matching machine, run pullboard settings landing.pool on, then pullboard land",- "LAND_HEADER": "shorten the item's cited rows (pullboard edit <id>), then pullboard land",+ "LAND_HEADER": "shout the coordinator: pullboard shout coordinator \"#<id> landing message fails its check\"","LAND_INTERACTION": "read the batch's failing tests, then land the items in separate batches","LAND_ITEM_MOVED": "rebuild the batch from current verified work: pullboard land","LAND_MERGE": "inspect the landing worktree and its hooks, then pullboard land --adopt",