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): report recorded flow stages and first-try rates [R1,R2]
Corey Olson3ec1b6efad00
diff --git a/src/board.js b/src/board.jsindex 38e71024..5c3482a2 100644--- a/src/board.js+++ b/src/board.js@@ -1128,8 +1128,9 @@ export function release(board, id, agentId, note = '') {* @param {{ agentId: string, commit: string, tree: string, files?: string[], policyCommit?: string, note?: string }} at - `files`: what the* item's own commits changed since its claim; a rework adds to what the first attempt changed.*/-export function submit(board, id, { agentId, commit, tree, files = [], policyCommit = null, note, submissionProof: proof, infra = null }) {+export function submit(board, id, { agentId, commit, tree, files = [], policyCommit = null, note, submissionProof: proof, submissionSize: size, infra = null }) {let recordedProof;+ let recordedSize;if (note !== undefined && (typeof note !== 'string' || !note.trim() || /[\r\n\u2028\u2029]/u.test(note))) {throw new Refused('USAGE', 'a submission note, when present, is one nonempty line');}@@ -1157,6 +1158,7 @@ export function submit(board, id, { agentId, commit, tree, files = [], policyComtreeStillDuringGate: null,submissionProofValid: () => {if ((board.executionEngineVersion ?? ENGINE_VERSION) >= SUBMISSION_PROOF_ENGINE) recordedProof = submissionProof(proof);+ if ((board.executionEngineVersion ?? ENGINE_VERSION) >= FLOW_SIZE_ENGINE) recordedSize = submissionSize(size, commit);return null;},childrenDone: () => {@@ -1197,6 +1199,7 @@ export function submit(board, id, { agentId, commit, tree, files = [], policyCom...(criterionDigest ? { criterionDigest } : {}),...(note === undefined ? {} : { note: note.trim() }),...(recordedProof ? { submissionProof: recordedProof } : {}), ...(infra ? { infra } : {}),+ ...(recordedSize ? { submissionSize: recordedSize } : {}),});});}@@ -2341,3 +2344,5 @@ export function approveOutside(board, id, options) { return applyOutsideApproval/** Tailored inbox activity is the same canonical read projection as other board queries. */export { agentActivity } from './board-query.js';+import { FLOW_SIZE_ENGINE } from './flow-size-engine.js';+import { submissionSize } from './submission-size.js';diff --git a/src/commands/submit.js b/src/commands/submit.jsindex 112325d9..763cda0d 100644--- a/src/commands/submit.js+++ b/src/commands/submit.js@@ -215,6 +215,10 @@ export async function submitHere(ctx, id, infra) {);}const currentTrunk = requireTrunkMerge(root, commit); // The trunk may have moved while the gate ran.+ const measuredLines = changedLines(root, currentTrunk.commit, commit);+ const size = measuredLines === null ? undefined : {+ base: currentTrunk.commit, head: commit, lines: measuredLines, method: SUBMISSION_SIZE_METHOD,+ };if (requireComposition) requireSubmitComposition(root, commit, currentTrunk, acceptedMain.commit);const waivedLines = waived ? waived.map(waiverLine) : [];await withBoard(ctx, async (board) => {@@ -222,11 +226,12 @@ export async function submitHere(ctx, id, infra) {// The waived run is written to the item's thread before the submission, so no waived proof reads as green.if (waived) await ordered(ctx, board, 'appendFact', [id, { agentId: me.id, kind: 'measurement', text: `submission proof at ${commit.slice(0, 12)} was red and is recorded as waived, not green; every failure is covered by a live person waiver:\n${waivedLines.join('\n')}` }]);return await ordered(ctx, board, 'submit', [id, { agentId: me.id, commit, tree: headTree(root) ?? '', files: filesSince(root, id, claimHead, commit), policyCommit: acceptedMain.commit, ...(infraRecord ? { infra: infraRecord } : {}),+ ...(size ? { submissionSize: size } : {}),submissionProof: { version: 1, files: gate.files, full: gate.full, deferred: gate.deferred, reason: gate.reason, ...(gate.deferredFiles ? { deferredFiles: gate.deferredFiles } : {}) },...(gate.deferred ? { note: gate.deferredFiles ? deferredSelectionNote(gate.deferredFiles) : 'full suite deferred to the landing gate' } : {}) }]);});// A large submit still goes through; the note only suggests a chain of smaller items (#1162).- const sizeNote = oversizeNote(changedLines(root, currentTrunk.commit, commit), acceptedMain.config.itemSizeBudget);+ const sizeNote = oversizeNote(measuredLines, acceptedMain.config.itemSizeBudget);if (sizeNote) ctx.io.say(`note: ${sizeNote}`);const report = waived? `submission proof waived, not green: ${waived.length} failure(s), each covered by a live person waiver; the whole output is in ${gate.log}\n${waivedLines.join('\n')}`@@ -240,3 +245,4 @@ export async function submitHere(ctx, id, infra) {export async function run(io, { first, values }) {return submitHere(context(io), idArg(first), values.infra);}+import { SUBMISSION_SIZE_METHOD } from '../submission-size.js';diff --git a/src/engine.js b/src/engine.jsindex e9ebf895..ebb8a67c 100644--- a/src/engine.js+++ b/src/engine.js@@ -3,6 +3,7 @@ import {requireHandoffActive,} from './handoff-state.js';import { manualLandingFailureQuoted } from './manual-landing-failure-quoted.js';+import { submissionSize } from './submission-size.js';import { lineSettings } from './line-settings.js';import { requireOutsideReceipt } from './outside-proof.js';/** Versioned, deterministic replay through the CLI's existing board engine [H3,H16]. */@@ -92,6 +93,7 @@ export function prepareEngineMove(board, operation, args, { id = randomUUID(), aif (operation === 'reopen' && values[1] && typeof values[1] === 'object'&& manualLandingFailureQuoted(values[1].note)) values[1].quotedLandingFailure = true;if (operation === 'submit' && ENGINE_VERSION >= SUBMISSION_PROOF_ENGINE) submissionProof(values[1]?.submissionProof);+ if (operation === 'submit') submissionSize(values[1]?.submissionSize, values[1]?.commit);if (operation === 'claim' && ['wipPerReviewer', 'takeoverMinutes'].some(key => typeof lineSettings(board)[key] === 'number')) {values[1] = { ...values[1], lineCapacity: true };}diff --git a/src/flow-size-engine.js b/src/flow-size-engine.jsnew file mode 100644index 00000000..4bf293e8--- /dev/null+++ b/src/flow-size-engine.js@@ -0,0 +1,3 @@+/** Immutable submit-size observations require replay support before they enter native history [H16,R2]. */+import { unassignedEngine } from './engine-next.js';+export const FLOW_SIZE_ENGINE = unassignedEngine();diff --git a/src/moves/submit.js b/src/moves/submit.jsindex 3600579d..f8256683 100644--- a/src/moves/submit.js+++ b/src/moves/submit.js@@ -1,4 +1,5 @@import { RIGOR_AUTO_ENGINE } from '../rigor-auto-engine.js';+import { FLOW_SIZE_ENGINE } from '../flow-size-engine.js';/** Routing metadata owned by submit, discovered without a shared registry edit [C7,V4,H16]. */import { BAR_READY_ENGINE } from '../bar-ready-engine.js';import { barReadySetting } from '../bar-ready-setting.js';@@ -26,7 +27,8 @@ function existingEngine(args, board, at) {/** Keep outside-source isolation as the original maximum over the older engine rule. */function minimumEngine(args, board, at) {const outside = board && Boolean(outsideSource(board, args[0]));- return Math.max(outside ? OUTSIDE_INTAKE_ENGINE : 1, existingEngine(args, board, at));+ return Math.max(args[1]?.submissionSize !== undefined ? FLOW_SIZE_ENGINE : 1,+ outside ? OUTSIDE_INTAKE_ENGINE : 1, existingEngine(args, board, at));}/** Read precisely the actor argument used by this operation [H2,H16]. */diff --git a/src/proof-counter-read.js b/src/proof-counter-read.jsindex 23b16a23..db89a557 100644--- a/src/proof-counter-read.js+++ b/src/proof-counter-read.js@@ -2,6 +2,7 @@import { barStats } from './bar-corrections.js';import { caughtFrom } from './caught.js';import { decodedProofEvent } from './proof-event-detail.js';+import { proofCounter } from './proof-counters.js';import { currentProofCounters } from './proof-counters.js';import { proofCounterRows } from './proof-counters.js';import { projectFlowStats } from './stats-flow.js';@@ -60,7 +61,7 @@ export function counterProofStats(board, boundary, now) {const creators = items.filter(item => item.creator !== undefined).map(item => ({ event_kind: 'add', item_id: item.id, event_by: item.creator }));const corrections = proofCounterRows(board, 'bar').map(row => decodedProofEvent({ ...row, event_kind: 'edit' }, row.detail));const verdicts = board.db.prepare('SELECT * FROM verdict ORDER BY verdict_id').all();- const flow = { items: items.filter(item => item.id !== null && item.id !== undefined).map(item => item.flow),+ const flow = { reportPolicy: summary.reportVersion === 1 ? proofCounter(board, 'report-policy') : null, items: items.filter(item => item.id !== null && item.id !== undefined).map(item => item.flow),actors: actors.filter(actor => actor.id !== 'clock').map(actor => actor.flow), dailyEvents: proofCounterRows(board, 'daily') };return { ...counts, agentCount: attributed.agents.length, familyCount: attributed.families.length, ...attributed,bars: barStats([...creators, ...corrections], verdicts, boundary), caught: counterCaught(board, boundary),diff --git a/src/proof-counters.js b/src/proof-counters.jsindex f501441b..3f1f5571 100644--- a/src/proof-counters.js+++ b/src/proof-counters.js@@ -1,3 +1,11 @@+import { reportEvent } from './stats-flow-report.js';+import { affectedReportItems } from './stats-flow-report.js';+import { indexReportItem } from './stats-flow-report.js';+import { prepareReportMove } from './stats-flow-report.js';+import { newReportPolicy } from './stats-flow-report.js';+import { advanceReport } from './stats-flow-report.js';+import { recordReport } from './stats-flow-report.js';+import { recordReportPolicy } from './stats-flow-report.js';import { appendRigorCounter } from './rigor-counters.js';import { ensureRigorCounters } from './rigor-counters.js';import { NATIVE_FLAKE_ENGINE } from './flake-engine.js';@@ -59,7 +67,7 @@ export function clearProofCounters(board) {/** Start a bounded all-time aggregate; window-specific contributions live in separate event shards. */function emptySummary() {return { last: 0, submissions: 0, rejections: 0, merged: 0, mergedWithoutAccept: 0,- firstEventAt: null, lastEventAt: null, invalid: false };+ firstEventAt: null, lastEventAt: null, invalid: false, reportVersion: 1 };}/** Advance an item's acceptance audit separately from its flow lifecycle, whose rules differ. */@@ -121,6 +129,16 @@ export function appendProofCounter(board, event) {if (summary.invalid) { put(board, 'summary', summary); return; }if (summary.firstEventAt === null || at < Date.parse(summary.firstEventAt)) summary.firstEventAt = event.event_at;if (summary.lastEventAt === null || at >= Date.parse(summary.lastEventAt)) summary.lastEventAt = event.event_at;+ const reporting = reportEvent(event, detail);+ const reportPolicy = reporting ? proofCounter(board, 'report-policy') ?? newReportPolicy() : null;+ const beforePolicy = reporting ? JSON.stringify(reportPolicy) : null;+ for (const id of reporting ? affectedReportItems(reportPolicy, event, detail) : []) {+ const row = proofCounter(board, `item:${id}`);+ if (!row) continue;+ advanceReport(row.flow, reportPolicy, at);+ put(board, `item:${id}`, row);+ }+ if (reporting) recordReportPolicy(reportPolicy, event, detail, event.item_id == null ? null : proofCounter(board, `item:${event.item_id}`)?.flow);const key = `item:${event.item_id}`;const item = proofCounter(board, key) ?? { id: event.item_id, flow: { id: event.item_id, lane: 'unknown' } };const contribution = countItem(summary, item, event, detail);@@ -130,7 +148,9 @@ export function appendProofCounter(board, event) {if (event.event_kind === 'add' || event.event_kind === 'merged' && item.flow.mergeAt === undefined) {put(board, `daily:${event.event_id}`, { at, kind: event.event_kind === 'add' ? 'added' : 'merged' });}- moveFlowItem(item.flow, event, detail, at);+ if (reporting) { advanceReport(item.flow, reportPolicy, at); prepareReportMove(item.flow, event, detail); }+ if (reporting) moveFlowItem(item.flow, event, detail, at);+ if (reporting) { recordReport(item.flow, event, detail); indexReportItem(reportPolicy, item.flow); }put(board, key, item);} else if (['submit', 'accept', 'reject', 'merged'].includes(event.event_kind)) {// Legacy counts also audit a null item id, while flow deliberately excludes it.@@ -143,6 +163,7 @@ export function appendProofCounter(board, event) {if (keepCatch(event, detail)) {put(board, `catch:${event.event_id}`, { event_id: event.event_id, event_at: event.event_at, event_by: event.event_by, event_kind: event.event_kind, item_id: event.item_id, detail });}+ if (reporting && JSON.stringify(reportPolicy) !== beforePolicy) put(board, 'report-policy', reportPolicy);appendRuleProof(board, event, detail, key => proofCounter(board, key), (key, value) => put(board, key, value));put(board, 'summary', summary);}@@ -169,7 +190,7 @@ export function rebuildProofCounters(board) {export function ensureProofCounters(board) {ensureRigorCounters(board);const summary = proofCounter(board, 'summary');- if (!summary) { rebuildProofCounters(board); return; }+ if (!summary || summary.reportVersion !== 1) { rebuildProofCounters(board); return; }replayProofTail(board, summary.last);}diff --git a/src/stats-flow-report.js b/src/stats-flow-report.jsnew file mode 100644index 00000000..91e8e6e6--- /dev/null+++ b/src/stats-flow-report.js@@ -0,0 +1,189 @@+/** Optional indexed flow-report accounting around the canonical lifecycle reducer [R1,R2]. */+const STAGES = ['ready', 'later', 'build', 'reviewWait', 'review', 'mergeWait', 'rework'];+const BUCKETS = ['under100', '100to300', '300to800', '800plus', 'unknown'];++/** Only lifecycle and recorded policy moves can change report accounting. */+export function reportEvent(event, detail) {+ return ['add', 'edit', 'claim', 'renew', 'submit', 'reserve', 'release', 'accept', 'reject', 'merged', 'reopen', 'refreeze', 'escalate', 'lapse', 'withdraw', 'hold_item', 'unhold_item', 'hold', 'unhold', 'milestone_add', 'milestone_items', 'milestone_moved', 'milestone_edit', 'milestone_remove'].includes(event.event_kind) || event.event_kind === 'line_setting' && detail.key === 'focusMilestone';+}++/** Restore prototype-free maps after JSON decoding so valid names are never inherited keys. */+export function safeReportPolicy(policy) {+ for (const key of ['memberships', 'dependents', 'lanes', 'members', 'open']) {+ if (Object.getPrototypeOf(policy[key]) !== null) policy[key] = Object.assign(Object.create(null), policy[key]);+ }+ return policy;+}++/** Start policy facts reconstructed only from recorded events. */+export function newReportPolicy() { return safeReportPolicy({ focus: null, memberships: {}, heldLanes: [], verified: [], dependents: {}, lanes: {}, members: {}, open: {} }); }++/** Allocate accounting without manufacturing an absent historical start. */+function reportState() { return { totals: Object.fromEntries(STAGES.map(key => [key, 0])), known: false, missing: [], submissions: 0, first: null, deps: [], held: false }; }++/** Keep nested report facts immutable in the reusable prepared snapshot. */+export function frozenReport(value) {+ if (value && typeof value === 'object' && !Object.isFrozen(value)) {+ for (const child of Object.values(value)) frozenReport(child);+ Object.freeze(value);+ }+ return value;+}++/** Classify an observed canonical state; focus affects reporting, never claim authority. */+function stage(item, policy, at) {+ const report = item.report;+ if (!report.known || ['merged', 'withdrawn'].includes(item.state)) return null;+ if (item.state === 'claimed') return Number.isFinite(item.leaseUntil) && item.leaseUntil <= at ? 'rework' : 'build';+ if (item.state === 'submitted') return item.reserve && (!Number.isFinite(item.reserve.until) || item.reserve.until > at) ? 'review' : 'reviewWait';+ if (item.state === 'accepted') return 'mergeWait';+ if (item.state !== 'open') return null;+ if (report.returned) return 'rework';+ const milestone = policy.memberships[item.id];+ return report.held || policy.heldLanes.includes(item.lane) || report.deps.some(id => !policy.verified.includes(id)) ||+ policy.focus && milestone !== policy.focus ? 'later' : 'ready';+}++/** Charge elapsed time, splitting recorded reservation and claim expiry boundaries exactly. */+export function advanceReport(item, policy, at) {+ item.report ??= reportState();+ const report = item.report;+ if (!Number.isFinite(report.at)) { report.at = at; return; }+ const boundaries = [item.leaseUntil, item.reserve?.until].filter(value => Number.isFinite(value) && value > report.at && value < at).sort((a, b) => a - b);+ for (const end of [...boundaries, at]) {+ const key = stage(item, policy, report.at);+ if (key && end >= report.at) report.totals[key] += (end - report.at) / 60_000;+ report.at = end;+ }+}++/** Preserve missing lifecycle boundaries before the canonical transition replaces them. */+export function prepareReportMove(item, event, detail) {+ const report = item.report;+ if (item.state === 'claimed' && Number.isFinite(item.leaseUntil) && item.leaseUntil <= Date.parse(event.event_at)) report.returned = true;+ report.matchingDecision = ['accept', 'reject'].includes(event.event_kind) && item.state === 'submitted' && detail.commit === item.commit;+ if (event.event_kind === 'submit' && item.state !== 'claimed') report.missing.push('build');+ if (['accept', 'reject'].includes(event.event_kind) && detail.commit === item.commit && item.state === 'submitted') {+ if (!item.reserve || Number.isFinite(item.reserve.until) && item.reserve.until < Date.parse(event.event_at)) report.missing.push('review');+ }+ if (event.event_kind === 'merged' && item.state !== 'accepted') report.missing.push('mergeWait');+}++/** Observe metadata alongside, rather than replacing, the existing lifecycle transition. */+export function recordReport(item, event, detail) {+ const report = item.report;+ if (event.event_kind === 'add') { report.known = true; report.deps = detail.after ?? []; }+ if (event.event_kind === 'edit' && Array.isArray(detail.after)) report.deps = detail.after;+ if (event.event_kind === 'hold_item') report.held = true;+ if (event.event_kind === 'unhold_item') report.held = false;+ if (event.event_kind === 'claim') report.returned = false;+ if (['reject', 'reopen', 'refreeze', 'escalate', 'lapse'].includes(event.event_kind) && !(event.event_kind === 'refreeze' && detail.retainedClaim) || event.event_kind === 'release' && !detail.review && item.state === 'open') report.returned = true;+ if (event.event_kind === 'submit') {+ if (!Number.isFinite(item.claimAt)) report.missing.push('build');+ report.submissions += 1;+ const size = detail.submissionSize;+ const validSize = size?.method === 'added-plus-deleted-no-renames' && size.head === detail.commit &&+ /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(size.base ?? '') && /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(size.head ?? '') && Number.isSafeInteger(size.lines) && size.lines >= 0;+ report.first ??= { commit: detail.commit, size: validSize ? size.lines : null, verdict: null };+ }+ if (report.matchingDecision && report.first?.commit === detail.commit && report.first.verdict === null) report.first.verdict = event.event_kind;+}++/** Select only shards whose open interval classification changes with this policy event. */+export function affectedReportItems(policy, event, detail) {+ safeReportPolicy(policy);+ const kind = event.event_kind;+ if (kind === 'refreeze' && detail.retainedClaim) return [];+ let ids = [];+ if (['accept', 'reject', 'merged', 'reopen', 'refreeze', 'escalate', 'lapse'].includes(kind)) ids = policy.dependents[event.item_id] ?? [];+ else if (['hold', 'unhold'].includes(kind)) ids = policy.lanes[detail.lane] ?? [];+ else if (kind === 'line_setting' && detail.key === 'focusMilestone') ids = Object.keys(policy.open).map(Number);+ else if (kind === 'milestone_add') ids = detail.items ?? [];+ else if (kind === 'milestone_items') ids = [...(detail.add ?? []), ...(detail.remove ?? [])];+ else if (kind === 'milestone_moved') ids = [event.item_id];+ else if (['milestone_edit', 'milestone_remove'].includes(kind)) ids = policy.members[detail.before ?? detail.name] ?? [];+ return [...new Set(ids)].filter(id => policy.open[id]);+}++/** Maintain reverse dependency and grouping indexes only for the changed item. */+export function indexReportItem(policy, item) {+ safeReportPolicy(policy);+ const report = item.report;+ const changedDeps = JSON.stringify(report.indexedDeps) !== JSON.stringify(report.deps);+ for (const id of changedDeps ? report.indexedDeps ?? [] : []) policy.dependents[id] = (policy.dependents[id] ?? []).filter(value => value !== item.id);+ for (const id of changedDeps ? report.deps : []) {+ policy.dependents[id] ??= [];+ if (!policy.dependents[id].includes(item.id)) policy.dependents[id].push(item.id);+ }+ report.indexedDeps = [...report.deps];+ if (report.indexedLane !== item.lane) {+ if (report.indexedLane) policy.lanes[report.indexedLane] = (policy.lanes[report.indexedLane] ?? []).filter(id => id !== item.id);+ policy.lanes[item.lane] ??= [];+ if (!policy.lanes[item.lane].includes(item.id)) policy.lanes[item.lane].push(item.id);+ report.indexedLane = item.lane;+ }+ if (item.state === 'open') policy.open[item.id] = true;+ else delete policy.open[item.id];+}++/** Update historical reporting policy after old intervals have been charged. */+export function recordReportPolicy(policy, event, detail, item) {+ safeReportPolicy(policy);+ const kind = event.event_kind;+ if (kind === 'line_setting' && detail.key === 'focusMilestone') policy.focus = detail.value || null;+ if (kind === 'hold' && !policy.heldLanes.includes(detail.lane)) policy.heldLanes.push(detail.lane);+ if (kind === 'unhold') policy.heldLanes = policy.heldLanes.filter(lane => lane !== detail.lane);+ const matching = item?.commit && item.commit === detail.commit;+ if (kind === 'accept' && matching || kind === 'merged') { if (!policy.verified.includes(event.item_id)) policy.verified.push(event.item_id); }+ if (kind === 'reject' && matching || ['reopen', 'refreeze', 'escalate', 'lapse'].includes(kind) && !(kind === 'refreeze' && detail.retainedClaim)) policy.verified = policy.verified.filter(id => id !== event.item_id);+ if (kind === 'milestone_add') for (const id of detail.items ?? []) policy.memberships[id] = detail.name;+ if (kind === 'milestone_items') {+ for (const id of detail.add ?? []) policy.memberships[id] = detail.name;+ for (const id of detail.remove ?? []) if (policy.memberships[id] === detail.name) delete policy.memberships[id];+ }+ if (kind === 'milestone_moved') policy.memberships[event.item_id] = detail.to;+ if (kind === 'milestone_edit') for (const id of Object.keys(policy.memberships)) if (policy.memberships[id] === detail.before) policy.memberships[id] = detail.after;+ if (kind === 'milestone_remove') for (const id of Object.keys(policy.memberships)) if (policy.memberships[id] === detail.name) delete policy.memberships[id];+ if (kind.startsWith('milestone_')) {+ policy.members = Object.create(null);+ for (const [id, name] of Object.entries(policy.memberships)) { policy.members[name] ??= []; policy.members[name].push(Number(id)); }+ }++}++/** Summarize known first decisions without assigning unknown history a zero rate. */+function decisions(rows) {+ const accepted = rows.filter(row => row.report.known && row.report.first?.verdict === 'accept').length;+ const decided = rows.filter(row => row.report.known && ['accept', 'reject'].includes(row.report.first?.verdict)).length;+ return { accepted, decided, rate: decided ? accepted / decided : null, unknown: rows.length - decided };+}++/** Assign exact half-open size buckets from the first captured submission only. */+function bucket(item) {+ const size = item.report.first?.size;+ return !Number.isSafeInteger(size) || size < 0 ? 'unknown' : size < 100 ? 'under100' : size < 300 ? '100to300' : size < 800 ? '300to800' : '800plus';+}++/** Aggregate measured durations and retain a separate count of incomplete histories. */+function aggregate(rows, item = false) {+ const landed = rows.filter(row => row.state === 'merged');+ const stages = Object.fromEntries(STAGES.map(key => {+ const measured = rows.filter(row => row.report.known && !row.report.missing.includes(key));+ return [key, { minutes: item && !measured.length ? null : measured.reduce((sum, row) => sum + row.report.totals[key], 0), unknown: rows.length - measured.length }];+ }));+ return { stages, firstTry: decisions(rows), submissionsPerLanded: !landed.length || landed.some(row => !row.report.known || !row.report.first) ? null : landed.reduce((sum, row) => sum + row.report.submissions, 0) / landed.length,+ sizeBuckets: Object.fromEntries(BUCKETS.map(key => [key, decisions(rows.filter(row => bucket(row) === key))])) };+}++/** Project copies of indexed facts at the observation clock, never mutating durable shards. */+export function projectReport(items, policy, now) {+ if (!policy) return { available: false };+ policy = safeReportPolicy(structuredClone(policy));+ const rows = items.map(item => { const copy = structuredClone(item); advanceReport(copy, policy, now); return copy; });+ /** Group using latest recorded membership and recorded item lanes, not current mutable rows. */+ function groups(key, value) {+ return [...new Set(rows.map(value))].sort().map(name => ({ [key]: name, ...aggregate(rows.filter(row => value(row) === name)) }));+ }+ return { scope: 'all-time', items: rows.map(row => ({ id: row.id, lane: row.lane, milestone: policy.memberships[row.id] ?? null, ...aggregate([row], true) })),+ lanes: groups('lane', row => row.lane), milestones: groups('milestone', row => policy.memberships[row.id] ?? null), overall: aggregate(rows) };+}diff --git a/src/stats-flow.js b/src/stats-flow.jsindex c98baf15..6624b2db 100644--- a/src/stats-flow.js+++ b/src/stats-flow.js@@ -1,3 +1,12 @@+import { reportEvent } from './stats-flow-report.js';+import { affectedReportItems } from './stats-flow-report.js';+import { indexReportItem } from './stats-flow-report.js';+import { prepareReportMove } from './stats-flow-report.js';+import { newReportPolicy } from './stats-flow-report.js';+import { advanceReport } from './stats-flow-report.js';+import { recordReport } from './stats-flow-report.js';+import { recordReportPolicy } from './stats-flow-report.js';+import { projectReport } from './stats-flow-report.js';import { proofEventDetail } from './proof-event-detail.js';import {newWindowTrace,@@ -40,6 +49,7 @@ function expireClaim(item, at) {observeFlowStage(item, null, item.leaseUntil, 'clock');item.state = 'open';item.openAt = item.leaseUntil;+ if (item.report) item.report.returned = true;}}@@ -91,8 +101,10 @@ export function moveFlowItem(item, event, detail, at) {if (item.windowTrace?.cursor?.stage !== 'mergeWait') observeFlowGap(item);observeFlowStage(item, null, at, event.event_by);item.mergeAt ??= at; item.state = 'merged'; break;- case 'reopen':case 'refreeze':+ if (detail.retainedClaim) break;+ // Ordinary refreezes return work; a retained live claim keeps its original build interval.+ case 'reopen':case 'escalate':case 'lapse':observeFlowStage(item, 'sendBackIdle', at, event.event_by);@@ -179,6 +191,7 @@ export function prepareFlowHistory(history, { window = false } = {}) {const items = new Map();const actors = new Map();const dailyEvents = [];+ const reportPolicy = newReportPolicy();for (const event of history) {const detail = proofEventDetail(event);const at = Date.parse(event.event_at);@@ -190,21 +203,30 @@ export function prepareFlowHistory(history, { window = false } = {}) {actor.role = id === 'coordinator' ? 'coordinator' : roleOf(event.event_kind, detail) ?? actor.role;actor.lastAt = at;}+ const reporting = reportEvent(event, detail);+ for (const id of reporting ? affectedReportItems(reportPolicy, event, detail) : []) {+ const affected = items.get(id);+ if (affected) advanceReport(affected, reportPolicy, at);+ }+ if (reporting) recordReportPolicy(reportPolicy, event, detail, items.get(event.item_id));if (event.item_id === null || event.item_id === undefined) continue;if (!items.has(event.item_id)) items.set(event.item_id, { id: event.item_id, lane: 'unknown', ...(window ? { windowTrace: newWindowTrace() } : {}) });const item = items.get(event.item_id);if (event.event_kind === 'add') dailyEvents.push({ at, kind: 'added' });if (event.event_kind === 'merged' && item.mergeAt === undefined) dailyEvents.push({ at, kind: 'merged' });- moveFlowItem(item, event, detail, at);+ if (reporting) { advanceReport(item, reportPolicy, at); prepareReportMove(item, event, detail); }+ if (reporting) moveFlowItem(item, event, detail, at);+ if (reporting) { recordReport(item, event, detail); indexReportItem(reportPolicy, item); }}const frozenItems = [...items.values()].map((item) => Object.freeze({...item,+ ...(item.report ? { report: frozenReport(item.report) } : {}),...(item.windowTrace ? { windowTrace: frozenWindowTrace(item.windowTrace) } : {}),...(item.reserve ? { reserve: Object.freeze({ ...item.reserve }) } : {}),}));const frozenActors = [...actors.values()].map((actor) => Object.freeze({ ...actor }));const frozenDailyEvents = dailyEvents.map((event) => Object.freeze(event));- return Object.freeze({ items: Object.freeze(frozenItems), actors: Object.freeze(frozenActors), dailyEvents: Object.freeze(frozenDailyEvents) });+ return Object.freeze({ reportPolicy: frozenReport(reportPolicy), items: Object.freeze(frozenItems), actors: Object.freeze(frozenActors), dailyEvents: Object.freeze(frozenDailyEvents) });}/** Project current queues and time windows from compiled facts without mutating the cached snapshot. */@@ -252,7 +274,8 @@ export function projectFlowStats(prepared, boundary, now, counts, { windowMinute...projectFlowWindow(prepared, windowMinutes, now),...(executionCapacity ? { executionCapacity } : {}),};- return { ...(window === undefined ? {} : { window }), asOf: new Date(now).toISOString(), stages, queues: queueData.queues, unreviewed: queueData.unreviewed, daily: [...daily.values()].sort((a, b) => a.date.localeCompare(b.date)),+ const report = projectReport(prepared.items, prepared.reportPolicy, now);+ return { report, ...(window === undefined ? {} : { window }), asOf: new Date(now).toISOString(), stages, queues: queueData.queues, unreviewed: queueData.unreviewed, daily: [...daily.values()].sort((a, b) => a.date.localeCompare(b.date)),submitsPerMerged: completedItems ? counts.submissions / completedItems : 0, activeAgents, bottleneck };}@@ -286,6 +309,18 @@ export function flowLines(flow) {lines.push(`per day: ${flow.daily.map(row => `${row.date}: ${row.added} added, ${row.merged} merged`).join('; ') || 'none'}`);lines.push(`${number(flow.submitsPerMerged)} submissions per merged item`);lines.push(`active in the last hour: ${flow.activeAgents.total} agents · roles ${Object.entries(flow.activeAgents.roles).map(([role, count]) => `${role} ${count}`).join(', ')} · lanes ${Object.entries(flow.activeAgents.lanes).map(([lane, count]) => `${lane} ${count}`).join(', ') || 'none'}`);+ if (flow.report?.items) {+ lines.push('flow report (all-time): waiting for an agent; filed for later; building; review; landing; rework');+ const labels = { ready: 'waiting for an agent', later: 'filed for later', build: 'building', reviewWait: 'waiting for review', review: 'reviewing', mergeWait: 'waiting to land', rework: 'rework' };+ for (const [kind, rows] of [['item', flow.report.items], ['lane', flow.report.lanes], ['milestone', flow.report.milestones]]) {+ for (const row of rows) {+ const name = kind === 'item' ? `#${row.id}` : row.lane ?? row.milestone ?? 'unknown';+ lines.push(`${kind} ${name}: ${Object.entries(row.stages).map(([key, value]) => `${labels[key]} ${duration(value.minutes)} (${value.unknown} unknown)`).join(' · ')}`);+ lines.push(` first try ${number(row.firstTry.rate === null ? null : row.firstTry.rate * 100)}% (${row.firstTry.accepted}/${row.firstTry.decided}; ${row.firstTry.unknown} unknown); submissions per landed ${number(row.submissionsPerLanded)}`);+ lines.push(` size buckets: ${Object.entries(row.sizeBuckets).map(([key, value]) => `${key} ${number(value.rate === null ? null : value.rate * 100)}% (${value.accepted}/${value.decided}; ${value.unknown} unknown)`).join(' · ')}`);+ }+ }+ } else lines.push('flow report: unavailable until the next writer rebuilds historical accounting');const bottleneck = flow.bottleneck;lines.push(`bottleneck: ${bottleneck.message}${bottleneck.share === null ? '' : ` (${number(bottleneck.share * 100)}%)`}${bottleneck.lowConfidence ? ' · low confidence' : ''}`);if (bottleneck.recommendation) lines.push(`next: ${bottleneck.recommendation}`);@@ -305,3 +340,4 @@ export function flowAlertLine(flow) {`bottleneck: ${LABELS[bottleneck.stage]} (${number(bottleneck.share * 100)}% of ${duration(bottleneck.totalCycleMinutes)} measured cycle time); next: ${bottleneck.recommendation}`;return `flow: ${thresholds.join('; ')}; ${measured}`;}+import { frozenReport } from './stats-flow-report.js';diff --git a/src/submission-size.js b/src/submission-size.jsnew file mode 100644index 00000000..b2a533f9--- /dev/null+++ b/src/submission-size.js@@ -0,0 +1,18 @@+/** Validate the exact Git comparison observed by a submitting writer; readers never reconstruct it [R1,R2,H16]. */+import { Refused } from './refused.js';++const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;+export const SUBMISSION_SIZE_METHOD = 'added-plus-deleted-no-renames';++/** Normalize optional observational metadata without guessing a missing legacy measurement. */+export function submissionSize(value, commit) {+ if (value === undefined) return undefined;+ if (!value || typeof value !== 'object' || Array.isArray(value)+ || typeof value.base !== 'string' || typeof value.head !== 'string'+ || !COMMIT.test(value.base) || !COMMIT.test(value.head)+ || value.head !== commit || !Number.isSafeInteger(value.lines) || value.lines < 0+ || value.method !== SUBMISSION_SIZE_METHOD) {+ throw new Refused('SUBMISSION_PROOF', 'a submission size needs exact base and submitted head commits, a nonnegative changed-line count and its counting method; rerun submit with the current CLI');+ }+ return { base: value.base, head: value.head, lines: value.lines, method: SUBMISSION_SIZE_METHOD };+}diff --git a/test/flow-report-cache.test.js b/test/flow-report-cache.test.jsnew file mode 100644index 00000000..a1c96207--- /dev/null+++ b/test/flow-report-cache.test.js@@ -0,0 +1,105 @@+/** Report capability migration preserves existing indexed read-only statistics [R1,R2]. */+import assert from 'node:assert/strict';+import { mkdtempSync } from 'node:fs';+import { rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { test } from 'node:test';+import * as store from '../src/board.js';+import { proofStats } from '../src/stats.js';+import { flowStats } from '../src/stats-flow.js';+import { ensureProofCounters } from '../src/proof-counters.js';+import { runFixtureGit } from './fixture-child.js';++/** Construct a native board whose append path maintains current report shards. */+function fixture(t) {+ const root = mkdtempSync(join(tmpdir(), 'pullboard-report-cache-'));+ runFixtureGit(['init', '-q', '-b', 'main'], { cwd: root, stdio: 'pipe' });+ const board = store.openBoard(join(root, '.git', 'board.sqlite'));+ store.register(board, { lane: 'coordinator', path: root });+ store.addItem(board, { by: 'coordinator', lane: 'core', title: 'Known open history' });+ t.after(() => { store.closeBoard(board); rmSync(root, { recursive: true, force: true }); });+ return board;+}++test('flow report indexed projection matches canonical replay without hot raw history reads [R1,R2]', t => {+ const board = fixture(t);+ const now = Date.now() + 60_000;+ const history = store.events(board);+ const stats = proofStats(board, { now });+ assert.deepEqual(stats.flow.report, flowStats(history, null, now, stats).report);+ const prepare = board.db.prepare.bind(board.db);+ const reads = [];+ board.db.prepare = sql => { reads.push(sql); return prepare(sql); };+ t.after(() => { board.db.prepare = prepare; });+ assert.deepEqual(proofStats(board, { now }).flow.report, stats.flow.report);+ assert.ok(!reads.some(sql => /SELECT\s+\*\s+FROM\s+event\b/i.test(sql)), 'current report reads indexed facts, never raw event history');+ assert.equal(proofStats(board, { now, since: '2026-10-01' }).flow.report.scope, 'all-time', 'a date-filtered legacy summary visibly labels the report scope');+});++test('old v2 counters retain fast metrics and explicitly unavailable reports until a writer rebuilds [R1,R2]', t => {+ const board = fixture(t);+ const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('local:proof-stats:v2:summary');+ const summary = JSON.parse(row.meta_value);+ delete summary.data.reportVersion;+ board.db.prepare('UPDATE board_meta SET meta_value=? WHERE meta_key=?').run(JSON.stringify(summary), 'local:proof-stats:v2:summary');+ const prepare = board.db.prepare.bind(board.db);+ const reads = [];+ board.db.prepare = sql => { reads.push(sql); return prepare(sql); };+ const old = proofStats(board);+ assert.deepEqual(old.flow.report, { available: false });+ assert.equal(old.flow.queues.open.size, 1);+ assert.ok(!reads.some(sql => /SELECT\s+\*\s+FROM\s+event\b/i.test(sql)), 'missing optional report capability does not force raw fallback');+ board.db.prepare = prepare;+ const before = store.events(board);+ ensureProofCounters(board);+ assert.ok(proofStats(board).flow.report.items);+ assert.deepEqual(store.events(board), before, 'writer backfill changes only local derived counters');+});++test('retained refreezes keep active build time and prototype-like recorded names remain ordinary groups [R1,R2]', () => {+ const base = Date.parse('2026-10-10T00:00:00Z');+ const commit = 'a'.repeat(40);+ const entries = [+ [0, 'milestone_add', null, { name: '__proto__', items: [1] }],+ [0, 'line_setting', null, { key: 'focusMilestone', value: '__proto__' }],+ [0, 'add', 1, { lane: '__proto__' }],+ [10, 'claim', 1, { leaseUntil: new Date(base + 100 * 60_000).toISOString() }],+ [15, 'refreeze', 1, { retainedClaim: true }],+ [30, 'submit', 1, { commit }],+ ];+ const history = entries.map(([minute, kind, item, detail], index) => ({ event_id: index + 1,+ event_at: new Date(base + minute * 60_000).toISOString(), event_by: 'core-1',+ event_kind: kind, item_id: item, event_detail: JSON.stringify(detail) }));+ const counts = { submissions: 1, rejections: 0, rejectionShare: 0 };+ const during = flowStats(history.slice(0, -1), null, base + 20 * 60_000, counts);+ assert.equal(during.queues.claimed.size, 1, 'a retained native refreeze leaves the same live claim in place');+ const report = flowStats(history, null, base + 30 * 60_000, counts).report;+ assert.deepEqual(report.items[0].stages.build, { minutes: 20, unknown: 0 });+ assert.deepEqual(report.items[0].stages.rework, { minutes: 0, unknown: 0 });+ assert.equal(report.lanes[0].lane, '__proto__');+ assert.equal(report.milestones[0].milestone, '__proto__');+});+++test('an item fact after claim expiry cannot reclassify the preceding active build [R1,R2]', () => {+ const base = Date.parse('2026-10-10T00:00:00Z');+ const entries = [+ [0, 'add', { lane: 'core' }],+ [10, 'claim', { leaseUntil: new Date(base + 20 * 60_000).toISOString() }],+ [30, 'fact', { note: 'Observation after the recorded lease boundary' }],+ [40, 'claim', { leaseUntil: new Date(base + 100 * 60_000).toISOString() }],+ [50, 'submit', { commit: 'b'.repeat(40) }],+ ];+ const history = entries.map(([minute, kind, detail], index) => ({ event_id: index + 1,+ event_at: new Date(base + minute * 60_000).toISOString(), event_by: 'core-1', item_id: 1,+ event_kind: kind, event_detail: JSON.stringify(detail) }));+ const counts = { submissions: 1, rejections: 0, rejectionShare: 0 };+ const observed = flowStats(history.slice(0, 3), null, base + 35 * 60_000, counts);+ assert.equal(observed.queues.open.size, 1, 'clock projection still exposes an expired claim after a non-lifecycle fact');+ assert.deepEqual(observed.report.items[0].stages.build, { minutes: 10, unknown: 0 });+ assert.deepEqual(observed.report.items[0].stages.rework, { minutes: 15, unknown: 0 });+ const completed = flowStats(history, null, base + 50 * 60_000, counts).report.items[0];+ assert.deepEqual(completed.stages.build, { minutes: 20, unknown: 0 });+ assert.deepEqual(completed.stages.rework, { minutes: 20, unknown: 0 });+});diff --git a/test/flow-submit-size.test.js b/test/flow-submit-size.test.jsindex 35d9c45b..54581539 100644--- a/test/flow-submit-size.test.js+++ b/test/flow-submit-size.test.js@@ -5,6 +5,9 @@ import { join } from 'node:path';import { test } from 'node:test';import * as store from '../src/board.js';import { createE2eHelpers } from './e2e-helpers.js';+import { applyEngineMove, applyRelayMove, prepareEngineMove } from '../src/engine.js';+import { exportBoard, importBoard } from '../src/exchange.js';+import { FLOW_SIZE_ENGINE } from '../src/flow-size-engine.js';test('a native submit records its immutable changed-line base and head for flow buckets [R1,R2,V4]', { timeout: 60_000 }, t => {const helpers = createE2eHelpers();@@ -51,3 +54,51 @@ test('a native submit records its immutable changed-line base and head for flow'advancing the trunk leaves the earlier submission measurement unchanged');} finally { store.closeBoard(board); }});++test('submission size replays identically and refuses unsupported or malformed measurements [R1,R2,H16]', t => {+ const helpers = createE2eHelpers();+ t.after(helpers.cleanup);+ const box = helpers.sandbox();+ const source = store.openBoard(join(box.dir, 'source.sqlite'));+ const copies = [];+ t.after(() => { for (const board of [source, ...copies]) store.closeBoard(board); });+ store.register(source, { lane: 'coordinator', path: '/fixture/main' });+ store.register(source, { lane: 'web', path: '/fixture/web' });+ const id = store.addItem(source, { by: 'coordinator', lane: 'web', title: 'Size replay' });+ store.claim(source, id, { agentId: 'web-1', lane: 'web', leaseMs: 3_600_000,+ freeze: () => ({ text: '{"rows":[]}', digest: 'f'.repeat(64) }) });+ const document = exportBoard(source);+ for (let index = 0; index < 4; index += 1) {+ const board = store.openBoard(join(box.dir, `replica-${index}.sqlite`));+ importBoard(board, document);+ copies.push(board);+ }+ const size = { base: 'a'.repeat(40), head: 'b'.repeat(40), lines: 0, method: 'added-plus-deleted-no-renames' };+ const options = { agentId: 'web-1', commit: size.head, tree: 'c'.repeat(40), submissionSize: size,+ submissionProof: { version: 1, files: [], full: false, deferred: true, reason: 'private replay fixture' } };+ const move = prepareEngineMove(source, 'submit', [id, options], { id: 'size-replay', actor: 'web-1' });+ const receipt = { sequence: 1, at: '2026-10-25T06:00:00.000Z', kind: 'move',+ sender: { kind: 'agent', userId: 'fixture', agent: 'web-1' } };+ const first = applyRelayMove(copies[0], move, receipt);+ assert.equal(first.error, undefined);+ assert.deepEqual(applyRelayMove(copies[1], move, receipt), first);+ assert.deepEqual(store.events(copies[0]), store.events(copies[1]));+ assert.deepEqual(JSON.parse(store.events(copies[0]).findLast(event => event.event_kind === 'submit').event_detail).submissionSize, size,+ 'a measured zero remains known, with its exact base and head');+ const before = store.events(copies[2]);+ assert.throws(() => applyEngineMove(copies[2], { ...move, engine: FLOW_SIZE_ENGINE - 1 }, receipt), { code: 'RELAY_MOVE' });+ assert.deepEqual(store.events(copies[2]), before, 'unsupported metadata cannot partially change native history');+ for (const change of [{ lines: -1 }, { lines: 0.5 }, { lines: null }, { lines: Number.MAX_SAFE_INTEGER + 1 },+ { head: 'd'.repeat(40) }, { base: 'missing' }, { method: 'guess' }]) {+ const forged = structuredClone(move);+ Object.assign(forged.args[1].submissionSize, change);+ assert.equal(applyRelayMove(copies[2], forged, receipt).error?.code, 'SUBMISSION_PROOF');+ assert.deepEqual(store.events(copies[2]), before);+ }+ const legacy = structuredClone(move);+ legacy.engine = FLOW_SIZE_ENGINE - 1;+ delete legacy.args[1].submissionSize;+ assert.equal(applyRelayMove(copies[3], legacy, receipt).error, undefined);+ assert.equal(Object.hasOwn(JSON.parse(store.events(copies[3]).findLast(event => event.event_kind === 'submit').event_detail), 'submissionSize'), false,+ 'an older sealed submit remains executable and its missing size remains unknown');+});