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(milestone): enforce optional item caps and atomic swaps [N26,H16]
Corey Olsone564275af1b0
diff --git a/src/cli-main.js b/src/cli-main.jsindex bc2553dc..c9c792cf 100644--- a/src/cli-main.js+++ b/src/cli-main.js@@ -111,6 +111,8 @@ const OPTIONS = {next: { type: 'string' },add: { type: 'string' },remove: { type: 'string' },+ swap: { type: 'string' },+ limit: { type: 'string' },name: { type: 'string' },title: { type: 'string' },url: { type: 'string' },diff --git a/src/commands/milestone.js b/src/commands/milestone.jsindex 54a1a65c..44434749 100644--- a/src/commands/milestone.js+++ b/src/commands/milestone.js@@ -18,20 +18,22 @@ export async function run(io, { first, second, rest, values }) {const ids = (text) => (text ?? '').split(',').map((value) => value.trim()).filter(Boolean);let name;let entry;+ if (values.limit !== undefined && first !== 'edit' || values.swap !== undefined && first !== 'items') throw new Refused('USAGE', 'use milestone edit --limit <n>|none, or milestone items --add <id> --swap <id>');if (first === 'add') {if (!second || rest.length || values.before !== undefined || values.add !== undefined || values.remove !== undefined || values.name !== undefined) {throw new Refused('USAGE', 'pullboard milestone add <name> [--note ...] [--items 1,2,3]');}name = await ordered(ctx, board, 'addMilestone', [{ agentId: me.id, name: second, note: values.note ?? null, items: ids(values.items) }]);} else if (first === 'items') {- if (!second || rest.length || Boolean(values.add) === Boolean(values.remove) || values.items !== undefined || values.note !== undefined || values.before !== undefined || values.name !== undefined) {- throw new Refused('USAGE', 'pullboard milestone items <name> --add ids or --remove ids');+ if (!second || rest.length || Boolean(values.add) === Boolean(values.remove) || (values.swap !== undefined && (!values.add || values.remove)) || values.items !== undefined || values.note !== undefined || values.before !== undefined || values.name !== undefined) {+ throw new Refused('USAGE', 'pullboard milestone items <name> --add ids [--swap id] or --remove ids');}name = second;const next = await ordered(ctx, board, 'editMilestoneItems', [name, {agentId: me.id,add: values.add === undefined ? [] : ids(values.add),remove: values.remove === undefined ? [] : ids(values.remove),+ ...(values.swap === undefined ? {} : { swap: ids(values.swap) }),}]);entry = { ...store.milestones(board).find((value) => value.name === name), items: next };} else if (first === 'order') {@@ -48,11 +50,11 @@ export async function run(io, { first, second, rest, values }) {await ordered(ctx, board, 'moveMilestone', [name, { agentId: me.id, before: values.before }]);entry = store.milestones(board).find((value) => value.name === name);} else if (first === 'edit') {- if (!second || rest.length || (values.name === undefined && values.note === undefined && values.target === undefined) || values.items !== undefined || values.before !== undefined || values.add !== undefined || values.remove !== undefined || values.next !== undefined) {- throw new Refused('USAGE', 'pullboard milestone edit <name> [--name <new name>] [--note <text>] [--target <date and time>|none]');+ if (!second || rest.length || (values.name === undefined && values.note === undefined && values.target === undefined && values.limit === undefined) || values.items !== undefined || values.before !== undefined || values.add !== undefined || values.remove !== undefined || values.next !== undefined) {+ throw new Refused('USAGE', 'pullboard milestone edit <name> [--name <new name>] [--note <text>] [--target <date and time>|none] [--limit <n>|none]');}name = second;- entry = await ordered(ctx, board, 'editMilestone', [name, { agentId: me.id, newName: values.name, note: values.note, ...(values.target === undefined ? {} : { target: store.canonicalMilestoneTarget(values.target) }) }]);+ entry = await ordered(ctx, board, 'editMilestone', [name, { agentId: me.id, newName: values.name, note: values.note, ...(values.target === undefined ? {} : { target: store.canonicalMilestoneTarget(values.target) }), ...(values.limit === undefined ? {} : { limit: values.limit }) }]);name = entry.name;} else if (first === 'ship') {if (!second || rest.length || ['items', 'note', 'before', 'name', 'add', 'remove', 'target'].some((key) => values[key] !== undefined)) {diff --git a/src/commands/roadmap.js b/src/commands/roadmap.jsindex cd7663bd..364fd912 100644--- a/src/commands/roadmap.js+++ b/src/commands/roadmap.js@@ -18,7 +18,7 @@ export function run(io, { first, second, rest }) {for (const milestone of milestones) {const when = milestone.shipped ? ` · shipped at ${milestone.shipped.commit.slice(0, 12)} on ${milestone.shipped.at}`: milestone.target ? ` · target ${milestone.target}${milestone.pastTarget ? ', past target' : ''}` : '';- io.say(`${milestone.name}: ${milestone.landed}/${milestone.total} landed${when}`);+ io.say(`${milestone.name}: ${milestone.landed}/${milestone.total} landed${milestone.limit == null ? '' : ` · ${milestone.count}/${milestone.limit} items`}${when}`);if (!milestone.shipped) {const summary = milestone.summary;const estimate = roadmapView.roadmapEstimate(summary);diff --git a/src/help.js b/src/help.jsindex d627754c..e738539d 100644--- a/src/help.js+++ b/src/help.js@@ -94,11 +94,11 @@ Workpullboard roadmap ordered milestones, N/M landed, targets, and each item as landed,accepted or its statuspullboard milestone add <name> [--note ...] [--items 1,2,3] create a milestone and optionally add items- pullboard milestone items <name> --add|--remove ids append or remove item references+ pullboard milestone items <name> --add ids [--swap id] | --remove idspullboard milestone order <name> <ids> rank these items within their milestone (agents)pullboard milestone move <name> --before <other> reorder a milestone- pullboard milestone edit <name> [--name <new>] [--note <text>] [--target <date and time>|none]- rename, update a note, or set the target a milestone ships by+ pullboard milestone edit <name> [--name <new>] [--note <text>] [--target <date and time>|none] [--limit <n>|none]+ rename, update a note, or set a shipping target or item limitpullboard milestone ship <name> [--next <name>] record it shipped at main's commit and moveits unlanded items into the next milestone (or --next)pullboard milestone remove <name> remove a milestone without changing its itemsdiff --git a/src/milestone-limit-engine.js b/src/milestone-limit-engine.jsnew file mode 100644index 00000000..5c3369a6--- /dev/null+++ b/src/milestone-limit-engine.js@@ -0,0 +1,3 @@+import { unassignedEngine } from './engine-next.js';+/** Optional milestone size and atomic swaps retain their receiver meaning on replay [N26,H16]. */+export const MILESTONE_LIMIT_ENGINE = unassignedEngine();diff --git a/src/milestones.js b/src/milestones.jsindex 45939e96..e9c186e2 100644--- a/src/milestones.js+++ b/src/milestones.js@@ -1,3 +1,4 @@+import { MILESTONE_LIMIT_ENGINE } from './milestone-limit-engine.js';import { MILESTONE_SHIP_ENGINE } from './move-engine-constants.js';export { MILESTONE_SHIP_ENGINE };/**@@ -97,6 +98,8 @@ export function roadmap(board, resolveExternal = null) {target,pastTarget: !milestone.shipped && target !== null && Date.parse(target) <= at,shipped: milestone.shipped ?? null,+ count: milestone.items.length,+ limit: milestone.limit ?? null,items: entries,landed,done: landed,@@ -198,16 +201,35 @@ export function addMilestone(board, { agentId, name, note = null, items = [] })});}+/** Validate an optional item cap; null explicitly turns the cap off [N26]. */+function normalizeMilestoneLimit(limit) {+ if (limit === null || limit === 'none') return null;+ const value = typeof limit === 'string' && /^(?:0|[1-9]\d*)$/u.test(limit) ? Number(limit) : limit;+ if (!Number.isSafeInteger(value) || value < 0) throw new Refused('MILESTONE_LIMIT', 'set --limit to a nonnegative integer, or none to turn it off');+ return value;+}++/** Enforce the receiver's cap on new moves, leaving older recorded moves unchanged [H16,N26]. */+function enforceMilestoneLimit(board, milestone, items) {+ if (engineOf(board) < MILESTONE_LIMIT_ENGINE || milestone.limit == null || items.length <= milestone.limit) return;+ const unstarted = milestone.items.filter(id => typeof id === 'number' && itemById(board, id)?.item_status === 'open');+ const candidates = unstarted.length ? unstarted.map(id => `#${id}`).join(', ') : 'none';+ throw new Refused('MILESTONE_LIMIT', `${milestone.name} would have ${items.length} items, above limit ${milestone.limit}; unstarted items that could move out: ${candidates}; use pullboard milestone items ${JSON.stringify(milestone.name)} --add <id> --swap <id>, remove items, or raise --limit`);+}+/**- * Add or remove item references while preserving the remaining order. Shipment is receiver state,- * so a shipped milestone takes no new items even from older clients; removing one is still allowed.+ * Edit membership atomically. A swap removes and adds in one receiver transaction, checked against+ * the final count; historical add/remove moves retain their recorded meaning [N26,H16].*/-export function editMilestoneItems(board, name, { agentId, add = [], remove = [] }) {+export function editMilestoneItems(board, name, { agentId, add = [], remove = [], swap = [] }) {requireCoordinator(agentId);const additions = normalizeMilestoneItems(add);const removals = normalizeMilestoneItems(remove);+ const swaps = normalizeMilestoneItems(swap);+ if (swaps.length && engineOf(board) < MILESTONE_LIMIT_ENGINE) throw new Refused('ENGINE_VERSION', `milestone swap requires engine ${MILESTONE_LIMIT_ENGINE}; upgrade Pullboard before using --swap`);validateLocalMilestoneItems(board, additions);if (additions.length && removals.length) throw new Refused('MILESTONE_ITEMS', 'add or remove milestone items in separate commands');+ if (swaps.length && (!additions.length || removals.length || swaps.length !== 1 || additions.length !== 1)) throw new Refused('MILESTONE_ITEMS', 'swap one item out with --add <id> --swap <id>; use --remove separately');if (!additions.length && !removals.length) throw new Refused('MILESTONE_ITEMS', 'name ids with --add or --remove');return atomic(board, () => {const entries = milestones(board);@@ -215,20 +237,18 @@ export function editMilestoneItems(board, name, { agentId, add = [], remove = []if (index < 0) throw new Refused('NO_MILESTONE', `no milestone named ${name}; list them with pullboard roadmap`);const current = entries[index];if (additions.length && current.shipped) throw shippedRefusal(current);- const nextItems = additions.length- ? [...current.items, ...additions]- : current.items.filter((id) => !removals.some((removeId) => JSON.stringify(removeId) === JSON.stringify(id)));- if (additions.length && new Set(nextItems.map((value) => JSON.stringify(value))).size !== nextItems.length) {- throw new Refused('MILESTONE_ITEMS', 'a milestone cannot list the same item twice; remove duplicate ids and retry');- }- if (removals.some((id) => current.items.every((present) => JSON.stringify(id) !== JSON.stringify(present)))) {- throw new Refused('MILESTONE_ITEMS', 'one or more ids are not in this milestone; read pullboard roadmap and retry');- }+ const removed = [...removals, ...swaps];+ if (removed.some(id => !current.items.includes(id))) throw new Refused('MILESTONE_ITEMS', 'one or more ids are not in this milestone; read pullboard roadmap and retry');+ if (additions.some(id => current.items.includes(id))) throw new Refused('MILESTONE_ITEMS', 'a milestone cannot list the same item twice; remove duplicate ids and retry');+ const nextItems = swaps.length+ ? current.items.map(id => id === swaps[0] ? additions[0] : id)+ : [...current.items.filter(id => !removed.includes(id)), ...additions];+ if (additions.length) enforceMilestoneLimit(board, current, nextItems);entries[index] = { ...current, items: nextItems,...((board.executionEngineVersion ?? ENGINE_VERSION) >= MILESTONE_RANK_ENGINE && current.order- ? { order: current.order.filter(id => nextItems.includes(id)) } : {}) };+ ? { order: current.order.map(id => swaps.includes(id) ? additions[0] : id).filter(id => nextItems.includes(id)) } : {}) };saveMilestones(board, entries);- logEvent(board, agentId, 'milestone_items', null, { name, add: additions, remove: removals });+ logEvent(board, agentId, 'milestone_items', null, { name, add: additions, remove: removals, ...(swaps.length ? { swap: swaps } : {}) });return nextItems;});}@@ -274,15 +294,17 @@ export function moveMilestone(board, name, { agentId, before }) {* Rename a milestone, update its note, or set its target without touching its items. A target is* an engine-45 meaning, so an older engine's edit replays exactly as it did.*/-export function editMilestone(board, name, { agentId, newName, note, target }) {+export function editMilestone(board, name, { agentId, newName, note, target, limit }) {requireCoordinator(agentId);const engine = engineOf(board);+ if (limit !== undefined && engine < MILESTONE_LIMIT_ENGINE) throw new Refused('ENGINE_VERSION', `milestone limit requires engine ${MILESTONE_LIMIT_ENGINE}; upgrade Pullboard before using --limit`);if (target !== undefined && engine < MILESTONE_SHIP_ENGINE) {throw new Refused('ENGINE_VERSION', `a milestone target requires engine ${MILESTONE_SHIP_ENGINE}; this board uses engine ${engine}; upgrade Pullboard before using --target`);}- if (newName === undefined && note === undefined && target === undefined) {+ if (newName === undefined && note === undefined && target === undefined && limit === undefined) {throw new Refused('MILESTONE_EDIT', engine < MILESTONE_SHIP_ENGINE ? 'supply --name or --note to edit a milestone' : 'supply --name, --note or --target to edit a milestone');}+ const limitValue = limit === undefined ? undefined : normalizeMilestoneLimit(limit);const targetValue = target === undefined ? undefined : normalizeMilestoneTarget(target);return atomic(board, () => {const entries = milestones(board);@@ -292,9 +314,13 @@ export function editMilestone(board, name, { agentId, newName, note, target }) {if (renamed !== name && entries.some((entry) => entry.name === renamed)) throw new Refused('MILESTONE_EXISTS', `milestone ${renamed} already exists; choose another name`);entries[index] = { ...entries[index], name: renamed, ...(note === undefined ? {} : { note: normalizeMilestoneText(renamed, note).note }) };if (targetValue !== undefined) entries[index].target = targetValue;+ if (limitValue !== undefined) {+ enforceMilestoneLimit(board, { ...entries[index], limit: limitValue }, entries[index].items);+ entries[index].limit = limitValue;+ }saveMilestones(board, entries);logEvent(board, agentId, 'milestone_edit', null, { before: name, after: renamed, noteChanged: note !== undefined,- ...(targetValue === undefined ? {} : { target: targetValue }) });+ ...(targetValue === undefined ? {} : { target: targetValue }), ...(limitValue === undefined ? {} : { limit: limitValue }) });return entries[index];});}@@ -353,7 +379,11 @@ export function shipMilestone(board, name, { agentId, commit, next }) {}const intoName = into === null ? null : entries[into].name;const at = board.clock.now().toISOString();- if (into !== null) entries[into] = { ...entries[into], items: [...entries[into].items, ...moved.filter((id) => !entries[into].items.includes(id))] };+ if (into !== null) {+ const nextItems = [...entries[into].items, ...moved.filter(id => !entries[into].items.includes(id))];+ enforceMilestoneLimit(board, entries[into], nextItems);+ entries[into] = { ...entries[into], items: nextItems };+ }entries[index] = { ...current, items: current.items.filter(stays), shipped: { commit, at, by: agentId } };saveMilestones(board, entries);logEvent(board, agentId, 'milestone_ship', null, { name, commit, into: intoName, moved, notMoved });diff --git a/src/moves/editMilestone.js b/src/moves/editMilestone.jsindex 169703d5..c19f4af0 100644--- a/src/moves/editMilestone.js+++ b/src/moves/editMilestone.js@@ -1,3 +1,4 @@+import { MILESTONE_LIMIT_ENGINE } from '../milestone-limit-engine.js';import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';/** Routing metadata owned by editMilestone, discovered without a shared registry edit [C7,V4,H16]. */import { LANDING_LEASE_ENGINE } from '../landing-lease-engine.js';@@ -6,6 +7,7 @@ import { BOARD_SENTINEL_ENGINE } from '../sentinel-engine.js';/** Preserve this operation's historical first-matching engine conditions [H16]. */function minimumEngine(args, board, at) {+ if (args[1]?.limit !== undefined) return MILESTONE_LIMIT_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return RIGOR_AUTO_ENGINE;if (args[0]?.landingFence !== undefined) return LANDING_LEASE_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return BOARD_SENTINEL_ENGINE;diff --git a/src/moves/editMilestoneItems.js b/src/moves/editMilestoneItems.jsindex 0ad1ab2d..55179c84 100644--- a/src/moves/editMilestoneItems.js+++ b/src/moves/editMilestoneItems.js@@ -1,3 +1,4 @@+import { MILESTONE_LIMIT_ENGINE } from '../milestone-limit-engine.js';import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';/** Routing metadata owned by editMilestoneItems, discovered without a shared registry edit [C7,V4,H16]. */import { LANDING_LEASE_ENGINE } from '../landing-lease-engine.js';@@ -5,6 +6,7 @@ import { BOARD_SENTINEL_ENGINE } from '../sentinel-engine.js';/** Preserve this operation's historical first-matching engine conditions [H16]. */function minimumEngine(args, board, at) {+ if (Array.isArray(args[1]?.swap) && args[1].swap.length > 0) return MILESTONE_LIMIT_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('conflict:')) return RIGOR_AUTO_ENGINE;if (args[0]?.landingFence !== undefined) return LANDING_LEASE_ENGINE;if (typeof args[1]?.cause === 'string' && args[1].cause.startsWith('sentinel:')) return BOARD_SENTINEL_ENGINE;diff --git a/test/milestone-limit.test.js b/test/milestone-limit.test.jsindex 066e725b..4b06ac1a 100644--- a/test/milestone-limit.test.js+++ b/test/milestone-limit.test.js@@ -94,14 +94,44 @@ test('a milestone with a limit refuses an add past it and accepts a swap', (t) =assert.doesNotMatch(refused.stderr, new RegExp(`#${building}(?:\\D|$)`), 'started work is not offered as a swap candidate');assert.deepEqual(store.milestones(box.board)[0].items, [first, building], 'refusal leaves the milestone unchanged');box.json('milestone', 'items', 'release', '--add', String(incoming), '--swap', String(first));- assert.deepEqual(store.milestones(box.board)[0].items, [building, incoming]);+ assert.deepEqual(store.milestones(box.board)[0].items, [incoming, building]);assert.equal(plan().count, 2);assert.match(box.run('roadmap').stdout, /release: .*2\/2 items/);const invalid = box.run('milestone', 'items', 'release', '--add', String(first), '--swap', '999999');assert.notEqual(invalid.status, 0);- assert.deepEqual(store.milestones(box.board)[0].items, [building, incoming], 'an invalid swap makes neither half of its change');+ assert.deepEqual(store.milestones(box.board)[0].items, [incoming, building], 'an invalid swap makes neither half of its change');box.json('milestone', 'edit', 'release', '--limit', 'none');box.json('milestone', 'items', 'release', '--add', String(first));assert.equal(plan().limit, null);assert.equal(plan().count, 3);});+++test('[N26,H16] caps validate edits, shipment carry and historical replay without partial changes', (t) => {+ const box = fixture(t);+ const first = box.item('First', 'open');+ const second = box.item('Second', 'open');+ box.json('milestone', 'add', 'source', '--items', String(first));+ box.json('milestone', 'add', 'target');+ box.json('milestone', 'edit', 'target', '--limit', '0');+ for (const limit of ['-1', '1.5', 'abc', '9007199254740992']) {+ assert.notEqual(box.run('milestone', 'edit', 'target', '--limit', limit).status, 0, limit);+ assert.equal(store.milestones(box.board)[1].limit, 0);+ }+ const before = store.milestones(box.board);+ assert.notEqual(box.run('milestone', 'ship', 'source', '--next', 'target').status, 0);+ assert.deepEqual(store.milestones(box.board), before, 'a capped carry does not ship or move anything');+ box.json('milestone', 'edit', 'target', '--limit', '1');+ box.json('milestone', 'ship', 'source', '--next', 'target');+ assert.deepEqual(store.milestones(box.board)[1].items, [first]);+ assert.notEqual(box.run('milestone', 'edit', 'target', '--name', 'renamed', '--limit', '0').status, 0);+ assert.equal(store.milestones(box.board)[1].name, 'target', 'invalid cap also rolls back the rename');+ const currentEngine = box.board.executionEngineVersion;+ try {+ box.board.executionEngineVersion = 1;+ store.editMilestoneItems(box.board, 'target', { agentId: 'coordinator', add: [second] });+ assert.deepEqual(store.milestones(box.board)[1].items, [first, second], 'historical uncapped moves replay unchanged');+ assert.throws(() => store.editMilestone(box.board, 'target', { agentId: 'coordinator', limit: 3 }), { code: 'ENGINE_VERSION' });+ assert.throws(() => store.editMilestoneItems(box.board, 'target', { agentId: 'coordinator', add: ['other#1'], swap: [first] }), { code: 'ENGINE_VERSION' });+ } finally { box.board.executionEngineVersion = currentEngine; }+});