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
fix(core): replay the named board line controls [R1,R2,A1]
Corey Olsondf87ed114691
diff --git a/docs/formats.md b/docs/formats.mdindex 7e872b62..3d583450 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -534,7 +534,7 @@ The engine-68 `recordSpecApprovalBaseline` move carries `{agentId, baseline: {ve`pullboard flow replay --json` reads only event ids, kinds, times, item ids and seat ids from the board. The result includes `history: { version: 1, events: [...] }`; each event has only `event_id`, `event_kind`, `event_at`, `item_id` and `event_by`. No title, description, message, path, commit or event-detail JSON is fetched or exported. Save that history object as JSON and pass it with `--history <file>` to replay the same input on another board.-The default policy, `{"order":"recorded"}`, keeps recorded stage starts, durations and seat concurrency, reproducing complete measured cycles. `--policy <file>` accepts an explicit item-id order (a partial list prioritizes those ids), plus optional positive integer `settings.buildWip`, `settings.reviewWip` and `settings.landingWip`. These are hypothetical replay limits, not changes to the live board or machine. Unspecified limits come from observed concurrent stage intervals; recorded seat identities and their observed concurrency remain fixed. A different order or limit schedules ready work without preemption, retaining item arrivals and every measured build/review/landing interval. Recorded policy has exact observed start constraints; alternate policy has none of the observed queue delays.+The default policy, `{"order":"recorded"}`, keeps recorded stage starts, durations and seat concurrency, reproducing complete measured cycles. `--policy <file>` accepts an explicit item-id order (a partial list prioritizes those ids) and the board's `settings.reviewsFirst`, `wipPerReviewer`, `landingBatchSize` and `landingCadenceMinutes`, with the same ranges and off values as `settings line`. `barReady` and `takeoverMinutes` are refused by name as “not modelled by replay”, even when off. Internal stage capacities are not public setting names. Explicit controls are scheduling predictions, never live setting writes. WIP uses the ceiling of the ratio times distinct observed reviewer seats, bounded further by each recorded seat's observed concurrency. Reviews-first prioritizes ready reviews without preemption. Landing batches take at most the requested number of ready items; the next batch waits for prior completion and the requested start-to-start cadence. Off or unspecified controls retain observed capacities without adding a batch/cadence restriction. Every prediction retains recorded arrivals, seats and work intervals; those intervals include observed waiting and are not CPU measurements.`replay` reports landing order, each first-claim-to-landed time, and stage quartiles in minutes using the existing flow-window convention (fast/slow quarters use the sorted sample at floor(n/4) and floor(3n/4), with the middle pair averaged for an even median). These counterfactual predictions are not timings measured under an alternate live queue. Landing intervals are the recorded accept-to-merged spans, including observed waiting, not an estimate of CPU work. Incomplete, abandoned or missing-boundary cycles appear in `unmeasured`; they never become zero-duration work. Rejected complete attempts retain their actual builder/reviewer seats and durations. No wall clock or random values enter the replay result.diff --git a/src/flow-replay.js b/src/flow-replay.jsindex e7c7e903..1d853865 100644--- a/src/flow-replay.js+++ b/src/flow-replay.js@@ -6,7 +6,7 @@ import {} from './flow-replay-history.js';const MINUTE = 60_000;-const SETTINGS = { buildWip: 'build', reviewWip: 'review', landingWip: 'landing' };+const RANGES = { wipPerReviewer: [1.5, 3, false], landingBatchSize: [1, 8, true], landingCadenceMinutes: [5, 30, true] };/** Accept only hypothetical replay limits, never writing machine or board settings. */function replayPolicy(input, observations) {@@ -18,14 +18,24 @@ function replayPolicy(input, observations) {|| new Set(order).size !== order.length || order.some(id => !observations.items.some(item => item.id === id)))) {throw new Refused('USAGE', 'replay order is recorded or a list of distinct measured item ids');}- const limits = source.settings ?? {};- if (!limits || typeof limits !== 'object' || Array.isArray(limits)- || Object.entries(limits).some(([key, value]) => !Object.hasOwn(SETTINGS, key) || !Number.isSafeInteger(value) || value < 1)) {- throw new Refused('USAGE', 'replay settings accept positive buildWip, reviewWip and landingWip limits only');+ const settings = source.settings ?? {};+ if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Refused('USAGE', 'replay settings must be a board line-settings object');+ for (const [key, value] of Object.entries(settings)) {+ if (['barReady', 'takeoverMinutes'].includes(key)) throw new Refused('USAGE', `${key} is not modelled by replay`);+ if (key === 'reviewsFirst' && typeof value === 'boolean') continue;+ const range = RANGES[key];+ if (!range || value !== false && (typeof value !== 'number' || !Number.isFinite(value)+ || value < range[0] || value > range[1] || range[2] && !Number.isSafeInteger(value))) {+ throw new Refused('USAGE', `replay ${key} must use its supported board line-setting range; read pullboard settings line`);+ }+ }+ const reviewers = new Set(observations.tasks.filter(task => task.stage === 'review').map(task => task.by)).size;+ const capacity = { ...observations.stages };+ if (settings.wipPerReviewer !== undefined && settings.wipPerReviewer !== false) {+ capacity.build = capacity.review = Math.max(1, Math.ceil(settings.wipPerReviewer * reviewers));}- const settings = Object.fromEntries(Object.entries(SETTINGS).map(([key, stage]) => [key, limits[key] ?? observations.stages[stage]]));- const recorded = order === 'recorded' && Object.entries(SETTINGS).every(([key, stage]) => settings[key] === observations.stages[stage]);- return { order, settings, recorded };+ return { order, settings: { ...settings }, capacity, reviewers, recorded: order === 'recorded' && !Object.keys(settings).length };+}/** Match the existing flow window's quartile convention, retaining nulls when no interval is measured. */@@ -43,26 +53,42 @@ function schedule(observations, policy) {const completed = new Map(), running = [];const arrival = new Map(observations.items.map(item => [item.id, item.arrival]));const rank = new Map((Array.isArray(policy.order) ? policy.order : []).map((id, index) => [id, index]));- const capacity = Object.fromEntries(Object.entries(SETTINGS).map(([key, stage]) => [stage, policy.settings[key]]));- let now = observations.origin;+ const capacity = policy.capacity;+ const batchSize = policy.settings.landingBatchSize || Infinity;+ const cadence = (policy.settings.landingCadenceMinutes || 0) * MINUTE;+ const batched = !policy.recorded && (batchSize !== Infinity || cadence > 0);+ let now = observations.origin, batch = new Set(), batchStarted = -Infinity, batchFinished = -Infinity;/** A measured task starts after arrival, its prior stage and the seat's recorded availability. */const readyAt = task => Math.max(arrival.get(task.item), observations.resources.get(task.by).available,task.prior ? completed.get(task.prior.id)?.end ?? Infinity : -Infinity, policy.recorded ? task.start : -Infinity);/** Recorded decisions preserve their exact start constraints; counterfactual order selects among ready tasks. */const compare = (a, b) => policy.recorded ? a.start - b.start || a.id - b.id :- (rank.get(a.item) ?? Infinity) - (rank.get(b.item) ?? Infinity) || arrival.get(a.item) - arrival.get(b.item) || a.item - b.item || a.id - b.id;+ (policy.settings.reviewsFirst ? Number(b.stage === 'review') - Number(a.stage === 'review') : 0)+ || (rank.get(a.item) ?? Infinity) - (rank.get(b.item) ?? Infinity) || arrival.get(a.item) - arrival.get(b.item) || a.item - b.item || a.id - b.id;while (pending.size || running.length) {for (let i = running.length - 1; i >= 0; i -= 1) {if (running[i].end <= now) { const row = running.splice(i, 1)[0]; completed.set(row.task.id, row); }}+ if (batched && !batch.size && now >= Math.max(batchStarted + cadence, batchFinished)) {+ const ready = [...pending.values()].filter(task => task.stage === 'landing' && readyAt(task) <= now).sort(compare).slice(0, batchSize);+ if (ready.length) { batch = new Set(ready.map(task => task.id)); batchStarted = now; }+ }for (const task of [...pending.values()].sort(compare)) {+ if (batched && task.stage === 'landing' && !batch.has(task.id)) continue;if (readyAt(task) > now || running.filter(row => row.task.stage === task.stage).length >= capacity[task.stage]|| running.filter(row => row.task.by === task.by).length >= observations.resources.get(task.by).capacity) continue;pending.delete(task.id);running.push({ task, start: now, end: now + task.duration });}+ if (batched && batch.size && [...batch].every(id => completed.has(id))) {+ batchFinished = Math.max(...[...batch].map(id => completed.get(id).end));+ batch.clear();+ continue;+ }if (!pending.size && !running.length) break;- const next = Math.min(...running.map(row => row.end), ...[...pending.values()].map(readyAt).filter(at => at > now));+ const batchAt = batched && !batch.size && [...pending.values()].some(task => task.stage === 'landing' && readyAt(task) <= now)+ ? Math.max(batchStarted + cadence, batchFinished) : Infinity;+ const next = Math.min(...running.map(row => row.end), ...[...pending.values()].map(readyAt).filter(at => at > now), batchAt > now ? batchAt : Infinity);if (!Number.isFinite(next)) throw new Refused('USAGE', 'replay history has an unschedulable dependency; export a complete lifecycle history');now = next;}@@ -91,7 +117,9 @@ export function replayFlow(events, inputPolicy) {return { history, replay: { mode: policy.recorded ? 'recorded' : 'predicted', policy: { order: policy.order, settings: policy.settings },items, landingOrder, stages, unmeasured: observations.unmeasured,assumptions: ['Recorded lifecycle intervals are retained, not interpreted as CPU time.',- 'Seat identities and their observed concurrency are fixed; WIP limits are hypothetical replay inputs only.',+ 'Seat identities and their observed concurrency are fixed; modelled board controls change scheduling only.',+ `WIP uses ceil(ratio times ${policy.reviewers} distinct observed reviewer seats), not an invented workforce.`,+ 'Landing batches contain ready items only; the next batch waits for prior completion and its start-to-start cadence.','Predicted queue times are not timings measured by running an alternate live policy.','Incomplete or abandoned attempts remain unmeasured, never zero-duration work.'] } };}diff --git a/src/help.js b/src/help.jsindex 0bc8d448..c4ad9a94 100644--- a/src/help.js+++ b/src/help.js@@ -169,7 +169,7 @@ CoordinatorReceiptspullboard flow replay [--history <json>] [--policy <json>] reproduce recorded flow or predict another item order and WIP limits- --json includes text-free structural history; policy order is recorded or item ids, settings are buildWip/reviewWip/landingWip+ --json includes text-free structural history; policy order is recorded or item ids, settings use modelled board line-control names (unsupported names are refused)pullboard stats [--since <date> | --window <duration>] proof numbers from the event log; --json for sites and tools--window 6h (also 30m or 1d): landed-item stage quartiles, tails and excess over targets;includes all attempts and sent-back idle; missing intervals stay unmeasured;diff --git a/test/flow-replay-policy.test.js b/test/flow-replay-policy.test.jsindex 0149f3dd..054ab067 100644--- a/test/flow-replay-policy.test.js+++ b/test/flow-replay-policy.test.js@@ -49,7 +49,7 @@ test('recorded landing ties follow event order and hypothetical WIP does not man[1, 'reserve', 2, 'review-1'], [2, 'accept', 2, 'review-1'], [2, 'reserve', 1, 'review-1'],[3, 'accept', 1, 'review-1'], [5, 'merged', 2, 'coordinator'], [5, 'merged', 1, 'coordinator']]);assert.deepEqual(replayFlow(input).replay.landingOrder, [2, 1]);- const changed = replayFlow(input, { order: [1, 2], settings: { reviewWip: 2 } });+ const changed = replayFlow(input, { order: [1, 2], settings: { wipPerReviewer: 2 } });assert.equal(changed.replay.items.find(item => item.id === 2).stages.reviewWait, 1,'the one observed reviewer still reviews one item at a time even when global review WIP is two');});@@ -103,3 +103,53 @@ test('replay accepts modelled board controls and explicitly refuses unmodelled c'internal limits are not accepted as public board settings');}});+++/** Build canonical public lifecycle rows from independently specified recorded stage boundaries. */+function parallelHistory() {+ const rows = [];+ for (let id = 1; id <= 4; id += 1) {+ rows.push([0, 'add', id, 'coordinator'], [0, 'claim', id, `builder-${id}`],+ [4, 'submit', id, `builder-${id}`], [3 + id, 'reserve', id, 'reviewer'],+ [4 + id, 'accept', id, 'reviewer'], [9, 'merged', id, 'coordinator']);+ }+ return rows.sort((a, b) => a[0] - b[0]).map(([minute, kind, item, by], index) =>+ ({ event_id: index + 1, event_at: new Date(BASE + minute * 60_000).toISOString(), event_kind: kind, item_id: item, event_by: by }));+}++test('board reviewer ratio bounds starts while fixed reviewer capacity preserves work [R1,R2]', () => {+ const input = parallelHistory();+ const low = replayFlow(input, { settings: { wipPerReviewer: 1.5 } });+ const high = replayFlow(input, { settings: { wipPerReviewer: 3 } });+ assert.equal(low.replay.items[2].claimAt, new Date(BASE + 4 * 60_000).toISOString());+ assert.equal(high.replay.items[2].claimAt, new Date(BASE).toISOString());+ for (const result of [low, high]) {+ assert.equal(result.replay.stages.build.medianMinutes, 4);+ assert.equal(result.replay.stages.review.medianMinutes, 1);+ }+});++test('board replay controls validate their named ranges and keep off values explicit [R1,R2,A1]', () => {+ for (const [key, values] of Object.entries({ wipPerReviewer: [1, 3.1, '2'],+ landingBatchSize: [0, 9, 1.5], landingCadenceMinutes: [4, 31, 5.5], reviewsFirst: [1, 'true'] })) {+ for (const value of values) assert.throws(() => replayFlow(rework(), { settings: { [key]: value } }), /USAGE/u);+ }+ const settings = { reviewsFirst: false, wipPerReviewer: false, landingBatchSize: false, landingCadenceMinutes: false };+ assert.deepEqual(replayFlow(rework(), { settings }).replay.policy.settings, settings);+});+++test('reviews-first changes a ready shared seat without preempting recorded work [R1,R2]', () => {+ const rows = [[0, 'add', 1, 'coordinator'], [0, 'claim', 1, 'builder'],+ [1, 'submit', 1, 'builder'], [1, 'reserve', 1, 'shared'], [1, 'add', 2, 'coordinator'],+ [2, 'accept', 1, 'shared'], [2, 'claim', 2, 'shared'], [3, 'submit', 2, 'shared'],+ [3, 'reserve', 2, 'reviewer'], [3, 'merged', 1, 'coordinator'],+ [4, 'accept', 2, 'reviewer'], [5, 'merged', 2, 'coordinator']];+ const events = rows.map(([minute, kind, item, by], index) => ({ event_id: index + 1,+ event_at: new Date(BASE + minute * 60_000).toISOString(), event_kind: kind, item_id: item, event_by: by }));+ const buildsFirst = replayFlow(events, { order: [2, 1], settings: { reviewsFirst: false } });+ const reviewsFirst = replayFlow(events, { order: [2, 1], settings: { reviewsFirst: true } });+ assert.equal(buildsFirst.replay.items[0].stages.reviewWait, 1);+ assert.equal(reviewsFirst.replay.items[0].stages.reviewWait, 0);+ assert.equal(reviewsFirst.replay.items[1].claimAt, new Date(BASE + 2 * 60_000).toISOString());+});diff --git a/test/flow-replay.test.js b/test/flow-replay.test.jsindex 4a4dfd6c..e5afdaa9 100644--- a/test/flow-replay.test.js+++ b/test/flow-replay.test.js@@ -68,15 +68,15 @@ test('the replay bench reproduces a recorded history and is deterministic [R1,R2const history = join(root, 'history.json');const policy = join(root, 'policy.json');writeFileSync(history, JSON.stringify(recorded.history));- writeFileSync(policy, JSON.stringify({ order: [1, 2], settings: { buildWip: 1, reviewWip: 1, landingWip: 1 } }));+ writeFileSync(policy, JSON.stringify({ order: [1, 2], settings: { wipPerReviewer: 1.5, landingBatchSize: 1, landingCadenceMinutes: 5 } }));const counterfactual = await run(root, 'flow', 'replay', '--history', history, '--policy', policy, '--json');assert.equal(counterfactual.code, 0, counterfactual.stderr + counterfactual.stdout);const changed = JSON.parse(counterfactual.stdout);- assert.deepEqual(changed.replay.landingOrder, [1, 2]);- assert.deepEqual(changed.replay.items.map(item => [item.id, item.cycleMinutes]), [[1, 11], [2, 9]]);+ assert.deepEqual(changed.replay.landingOrder, [2, 1]);+ assert.deepEqual(changed.replay.items.map(item => [item.id, item.cycleMinutes]), [[1, 12], [2, 6]]);assert.deepEqual(changed.replay.stages.build, { count: 2, fastQuarterMinutes: 2, medianMinutes: 3.5, slowQuarterMinutes: 5, worstMinutes: 5 });assert.deepEqual(changed.replay.stages.review, { count: 2, fastQuarterMinutes: 1, medianMinutes: 1.5, slowQuarterMinutes: 2, worstMinutes: 2 });- assert.deepEqual(changed.replay.stages.mergeWait, { count: 2, fastQuarterMinutes: 4, medianMinutes: 5, slowQuarterMinutes: 6, worstMinutes: 6 });+ assert.deepEqual(changed.replay.stages.mergeWait, { count: 2, fastQuarterMinutes: 3, medianMinutes: 4, slowQuarterMinutes: 5, worstMinutes: 5 });assert.equal((await run(root, 'flow', 'replay', '--history', history, '--policy', policy, '--json')).stdout,counterfactual.stdout, 'same structural input and policy produce byte-identical JSON');});