From e9f38d6fe14a4ec5138238a5e6c52de204e163bf Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Nov 2026 16:39:43 +0800 Subject: [PATCH] Review a pull request's final head in full and count review rounds per PR (GST-2673) (#4360) * Count review rounds per pull request across /ship runs (GST-2673) /ship's two-round review cap was counted inside each run, so a pull request shipped many times was reviewed again at every head. Step 1 now reads the rounds the PR body's receipt history records, passes them to the review plan, and sends later heads to the scoped re-check, with a lane or Captain round grant for an extra round. Adds the no-loss replay preregistration. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Cap full review rounds per pull request and keep fix-checks to each run The plan counts a PR's earlier full rounds (--prior-full) against the cap of two, as the approved plan says, and prints every earlier round as pr_rounds=. Renames the troubleshooting anchor to pr-round-cap, lists as a reviewed placeholder, and leaves ship/DRIVER.md at its size cap. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Point the ship driver's review pass at Step 9's plan flags, which carry the PR round count Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Give a pull request's final head a full review and make the diff-only re-check advice only (GST-2673) A scoped re-check that reads only what changed since the last reviewed head caught 22 of 24 planted faults but none of 8 real faults that full rounds had caught, so it no longer carries a /ship receipt. A later head whose own lines changed now gets a fresh full review, the PR's last before merge; a PR already at two full rounds gets one read-only full review with no fix round, whose blocker goes to the lane's Captain. carry prints RECHECK: advisory and refuses --recheck. The drift threshold, the re-check blocker count and the design-change grant kind are removed with the route they fed. Repins lib/review-depth.ts and ship/sections/review-army.md under replay GST-2673 (docs/evals/pr-round-count-results.md; deterministic grid against main: 196,608 of 196,608 plans identical with no prior rounds). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Keep a review round grant usable through its fix round and after a read-only review A grant now holds after the fix round's commits move HEAD past it, counts only the rounds earlier heads spent, and a receipt written without a run keeps other runs' stubs. Review-Finding: p1/specialist-batched#1 reader=state-machines Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/red-team#3 reader=red-team Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Count every review round at a granted head again, so a grant can't reset the count Reverts the history change that skipped rounds recorded at a round grant's head: the run that hit the cap is recorded at that same head, so skipping it wiped the count. A grant recorded after a read-only review still doesn't buy a fix round (fails closed). Review-Finding: p2/adversarial-native#1 reader=adversarial-native Review-Finding: p2/outside-voice#1 reader=outside-voice Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- bin/gstack-approvals | 28 ++++- bin/gstack-no-stop | 2 +- bin/gstack-review-plan | 29 ++++- bin/gstack-ship-receipt | 110 ++++++++++++++--- changelog.d/count-review-rounds-per-pr.md | 1 + crew/docs/captain.md | 3 + crew/lib/ship-recheck.ts | 41 ++----- crew/test/ship-recheck.test.ts | 59 +++------ docs/evals/pr-round-count-prereg.md | 75 +++++++++++ docs/evals/pr-round-count-results.md | 50 ++++++++ docs/inventory/evidence.json | 3 +- docs/review-policy.md | 64 +++++++++- docs/ship-policy.md | 15 ++- docs/troubleshooting.md | 58 ++++++--- lib/factory-scorecard.ts | 11 +- lib/headless-artifacts.ts | 7 +- lib/plan-record.ts | 2 +- lib/pr-review-history.ts | 108 ++++++++++++++++ lib/redact-patterns.ts | 5 +- lib/review-depth.ts | 35 +++++- lib/review-round-grant.ts | 43 +++++++ lib/review-scope.ts | 4 + lib/ship-preflight.ts | 10 +- lib/ship-receipt.ts | 23 ++-- ship/DRIVER.md | 2 +- ship/DRIVER.md.tmpl | 2 +- ship/sections/pr-body.md | 2 +- ship/sections/pr-body.md.tmpl | 2 +- ship/sections/review-army.md | 7 +- ship/sections/review-army.md.tmpl | 7 +- test/factory-scorecard.test.ts | 10 +- .../files/lib/review-depth.ts.json | 2 +- .../files/ship/sections/review-army.md.json | 2 +- .../review-pins/replays/GST-2673.json | 1 + test/helpers/placeholder-allowlist.ts | 1 + test/pr-review-history.test.ts | 116 ++++++++++++++++++ test/pr-round-cli.test.ts | 109 ++++++++++++++++ test/review-plan-pr-rounds.test.ts | 78 ++++++++++++ test/review-round-grant.test.ts | 32 +++++ test/ship-preflight.test.ts | 15 +++ test/ship-receipt-carry-mixed.test.ts | 21 ++-- .../ship/count-review-rounds-per-pr.json | 4 + 42 files changed, 1024 insertions(+), 175 deletions(-) create mode 100644 changelog.d/count-review-rounds-per-pr.md create mode 100644 docs/evals/pr-round-count-prereg.md create mode 100644 docs/evals/pr-round-count-results.md create mode 100644 lib/pr-review-history.ts create mode 100644 lib/review-round-grant.ts create mode 100644 test/fixtures/review-pins/replays/GST-2673.json create mode 100644 test/pr-review-history.test.ts create mode 100644 test/pr-round-cli.test.ts create mode 100644 test/review-plan-pr-rounds.test.ts create mode 100644 test/review-round-grant.test.ts create mode 100644 test/size-ledger/ship/count-review-rounds-per-pr.json diff --git a/bin/gstack-approvals b/bin/gstack-approvals index 2cf9ff732..d76c0a4a3 100755 --- a/bin/gstack-approvals +++ b/bin/gstack-approvals @@ -13,6 +13,7 @@ * gstack-approvals gate --finding --gate-id --head --reason --words --by [--json] * gstack-approvals dispositions [--branch ] * gstack-approvals lane-exception --head --files --reason --words --by [--json] + * gstack-approvals round-grant --pr --head --kind extra-round --reason --by [--words ] [--json] * gstack-approvals list [--json] [--branch ] * gstack-approvals sync [--branch ] * gstack-approvals path [--branch ] @@ -32,6 +33,7 @@ import { GSTACK_ACTOR, openShipRun, RULED_NOTE_SCOPE, ruledNoteRow, ruledNotes, import { resultLine } from '../lib/result-codes'; import { parsePlanLine, publicPlanLine, resolvePlan } from '../lib/plan-record'; import { TEST_LANE_EXCEPTION_SCOPE, testLaneExceptionRow } from '../lib/test-lane-exception'; +import { REVIEW_ROUND_GRANT_SCOPE, reviewRoundGrantRow, ROUND_GRANT_KINDS, type RoundGrantKind } from '../lib/review-round-grant'; import { GATE_DISPOSITION_SCOPE, GATE_SOURCE, gateDispositionRow, gateDispositions, gateDispositionText, ONE_LINE, recordGateDisposition, validGateId } from '../lib/gate-dispositions'; const HELP = `gstack-approvals — the per-thread approval record (capy/skill/gstack/captain.md) @@ -54,6 +56,12 @@ const HELP = `gstack-approvals — the per-thread approval record (capy/skill/gs finish prints it, and the receipt, PR body and READY carry it; refused while any worktree holds an open /ship run on the branch; the lander accepts each one with gstack-ship-queue land|verify --accept-gate-disposition dispositions the "Gate disposition: …" lines the Pre-Landing Review and the PR body carry + round-grant --pr --head --kind extra-round --reason + --by [--words ] + a review round the PR's R51 count would not plan (docs/review-policy.md#rounds-per-pull-request): extra-round is + one round with its fix round past the cap of 2, instead of the read-only final review; it binds + that head of that PR only and is spent by the round; the lane or its Captain records it, never the owner, and + --by is recorded, not enforced; refused inside this checkout's open /ship run, so a run never grants itself lane-exception --head --files --reason --words --by the owner's grant that a CI-carried lane counts although exactly those files are in no run's tree.json @@ -80,7 +88,7 @@ Example: ${exitTableHelp()}`; -const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan', '--stack', '--finding', '--reason', '--head', '--files', '--plan', '--gate-id']); +const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan', '--stack', '--finding', '--reason', '--head', '--files', '--plan', '--gate-id', '--pr', '--kind']); function parse(args: string[]): { flags: Record; bools: Set; error?: string } { const flags: Record = {}; @@ -157,9 +165,22 @@ function main(argv: string[]): number { const json = bools.has('--json'); const recorded = (where: StoreLocation) => `${where.file}${where.mirror ? ` mirror=${where.mirror}` : ''}`; - if (cmd === 'add' || cmd === 'import' || cmd === 'rule' || cmd === 'lane-exception' || cmd === 'gate') { + if (cmd === 'add' || cmd === 'import' || cmd === 'rule' || cmd === 'lane-exception' || cmd === 'gate' || cmd === 'round-grant') { let rows; - if (cmd === 'lane-exception') { + if (cmd === 'round-grant') { + const invalid = (message: string) => fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message }); + const pr = (flags['--pr'] ?? '').trim(), kind = (flags['--kind'] ?? '').trim() as RoundGrantKind, reason = (flags['--reason'] ?? '').trim(), by = (flags['--by'] ?? '').trim(); + if (!/^[1-9]\d*$/.test(pr) || !ROUND_GRANT_KINDS.includes(kind)) return invalid(`round-grant needs --pr and --kind ${ROUND_GRANT_KINDS.join('|')}`); + if (!reason || /[\x00-\x1f\x7f]/.test(reason)) return invalid('round-grant needs --reason '); + const head = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${flags['--head'] ?? ''}^{commit}`], { encoding: 'utf8', timeout: 10_000 }); + if (!flags['--head'] || head.status !== 0) return invalid('round-grant needs --head '); + if (!by || GSTACK_ACTOR.test(by)) return invalid('round-grant needs --by : gstack never grants itself a round'); + const open = openShipRun(process.cwd()); + if (open) return invalid(`/ship run ${open} is open on this checkout: a round grant is the lane's or its Captain's, never the run's own; record it from the lane after the run stops`); + const built = buildRow({ ...reviewRoundGrantRow(head.stdout.trim(), Number(pr), kind, reason), words: flags['--words'] ?? reason, by, date: flags['--date'] }, loc.branch); + if ('code' in built) return fail(cmd, built); + rows = [built]; + } else if (cmd === 'lane-exception') { const invalid = (message: string) => fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message }); const files = [...new Set((flags['--files'] ?? '').split(',').map(f => f.trim().replace(/^(\.\/)+/, '')).filter(Boolean))].sort(); const reason = (flags['--reason'] ?? '').trim(); @@ -205,6 +226,7 @@ function main(argv: string[]): number { if (RULED_NOTE_SCOPE.test(flags['--scope'] ?? '')) return fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message: 'a ruled_note scope is recorded with gstack-approvals rule' }); if (GATE_DISPOSITION_SCOPE.test(flags['--scope'] ?? '') || (flags['--source'] ?? '').trim() === GATE_SOURCE) return fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message: 'a gate_disposition scope is recorded with gstack-approvals gate' }); if (TEST_LANE_EXCEPTION_SCOPE.test(flags['--scope'] ?? '')) return fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message: 'a test_lane_exception scope is recorded with gstack-approvals lane-exception' }); + if (REVIEW_ROUND_GRANT_SCOPE.test(flags['--scope'] ?? '')) return fail(cmd, { code: 'APPROVAL_RECORD_INVALID', message: 'a review_round_grant scope is recorded with gstack-approvals round-grant' }); const built = buildRow({ ask: flags['--ask'] ?? '', words: flags['--words'] ?? '', by: flags['--by'] ?? '', scope: flags['--scope'] ?? '', pending: flags['--pending'], outcome: flags['--outcome'], date: flags['--date'], source: flags['--source'] }, loc.branch); if ('code' in built) return fail(cmd, built); rows = [built]; diff --git a/bin/gstack-no-stop b/bin/gstack-no-stop index 9477de839..9ab8e2d22 100755 --- a/bin/gstack-no-stop +++ b/bin/gstack-no-stop @@ -29,7 +29,7 @@ const HELP = `gstack-no-stop — record one of the five no-stop defaults (docs/r finding takes the printed GATE_DISPOSITION: kept reason instead of open pregate-flake-rerun one rerun of a failed pregate case at the same tree (rule 16): green is flaky, red is real stamp-only-carry carry refused a head whose change is a version stamp (--range-base the receipt head, - --base origin/): take the carry's RECHECK: route instead of Steps 2-16 + --base origin/): go on to Steps 2-16 without waiting; the plan reviews HEAD in full autoplan-regate gstack-autoplan records it; import --from /no-stop.json adds it here Step 19's receipt write adds --no-stop @ when list shows records. --range-base: the commit the fix or change is measured from (round 2's PASS_HEAD for scoped-fix-check, which must be diff --git a/bin/gstack-review-plan b/bin/gstack-review-plan index f50c342af..e5bee0122 100755 --- a/bin/gstack-review-plan +++ b/bin/gstack-review-plan @@ -25,6 +25,7 @@ import * as path from 'node:path'; import { spawnSync } from 'node:child_process'; import { baseContainsHead } from '../lib/default-base'; import { locate, readRecord } from '../lib/approval-record'; +import { reviewRoundGrants } from '../lib/review-round-grant'; import { EXIT, exitTableHelp } from '../lib/headless-artifacts'; import { resultLine } from '../lib/result-codes'; import { runScriptSync } from '../lib/script-invocation'; @@ -96,7 +97,16 @@ const HELP = `gstack-review-plan — the review depth of the next /ship step (do line-exact) and docs (docsChangeSince, the receipt's classifier), with no executable, symlink or gitlink mode and no gate-scan tag in the range, are no gate-class edit: done, or targeted when a docs claim needs the targeted read on a targeted-class diff (GST-1702) - --pr the PR whose platform review counts under review.platform on (default: this branch's PR) + --pr the PR whose platform review counts under review.platform on (default: this branch's PR); with + --round-grant, the PR the grant must name + --prior-rounds R51 rounds earlier /ship runs on this PR already spent, fix-checks included (printed as pr_rounds=) + --prior-full the full rounds among them: with this run's full passes they count against the cap of 2, so pass 1 + of a PR with 2 is one read-only full review (no fix round; a blocker is NEXT: stop (PR_ROUND_CAP) + for the lane's Captain to decide, never the owner). + Both come from the PR_REVIEW_FLAGS: line gstack-ship-preflight prints (gstack-ship-receipt history) + (docs/review-policy.md#rounds-per-pull-request; GST-2673) + --round-grant a review round grant at HEAD, recorded with gstack-approvals round-grant by the lane or its Captain: + one more round for the PR at this head; any other row is refused (exit 3) --declare-risk risk classes the lane declares for the diff (comma list of ${RISK_CLASSES.join(', ')}): they join the detected classes and only raise the depth; RISK_DECLARED: prints both (GST-1129) --fix-check-prompt print the fix-check reviewer's prompt from --fix-list, --hunks, --tests and --callers files @@ -171,6 +181,18 @@ function main(): number { if (logged && logged.status !== 0) { process.stderr.write(`gstack-review-plan: --grant ${grant}: gstack-review-read exited ${logged.status}, so whether a fix-check already spent this grant is unknown; no plan is safer than a fix-check the grant may not buy\n`); return EXIT.fail; } if (logged && row && (logged.stdout ?? '').split('\n---CONFIG---')[0]!.split('\n').some(l => { try { const v = JSON.parse(l); return v?.skill === 'review-fix-check' && Date.parse(v.timestamp) > Date.parse(row.recorded_at); } catch { return false; } })) { process.stderr.write(`gstack-review-plan: --grant ${grant}: a fix-check was logged after this grant was recorded, so the grant already bought a link of the fix-check chain; the stop at --range-base ${rangeBase} needs a new grant recorded after the last fix-check (gstack-approvals add --ask '... (review_loop_grant ${passHead!.slice(0, 12)})')\n`); return EXIT.refused; } } + const priorRounds = Number(flag('--prior-rounds') ?? '0'); + const priorFull = Number(flag('--prior-full') ?? '0'); + if (![priorRounds, priorFull].every(n => Number.isInteger(n) && n >= 0)) { process.stderr.write('gstack-review-plan: --prior-rounds and --prior-full need integers >= 0 (PR_REVIEW_FLAGS: from gstack-ship-preflight)\n'); return EXIT.usage; } + const roundGrant = flag('--round-grant'); + if (has('--round-grant')) { + const at = git(['rev-parse', 'HEAD'])?.trim(); + const loc = locate({ cwd: root, env: process.env }); + const g = reviewRoundGrants('file' in loc ? readRecord(loc).rows : []).find(x => x.approval === roundGrant); + const pr = flag('--pr'); + const atOrBefore = !!g && !!at && (g.head === at || git(['merge-base', '--is-ancestor', g.head, at]) !== null); + if (!roundGrant || !g || !atOrBefore || (pr !== undefined && String(g.pr) !== pr)) { process.stderr.write(`gstack-review-plan: --round-grant ${roundGrant ?? ''}: no approved review_round_grant row ${roundGrant ?? ''} naming HEAD ${(at ?? 'unknown').slice(0, 12)} or a commit before it${pr ? ` and PR #${pr}` : ''} in this branch's approval record; record one with gstack-approvals round-grant (docs/troubleshooting.md#pr-round-cap)\n`); return EXIT.refused; } + } const collected = collectLive(root, base); if (collected.errors.length) { for (const e of collected.errors) process.stderr.write(`gstack-review-plan: git could not list the diff (${e.input}: ${e.detail}); fix: ${e.repair}; no plan is safer than a plan for an empty diff\n`); @@ -254,8 +276,9 @@ function main(): number { const plan = planReview({ ...collected, ...exclusionInput, ...riskPaths, declared: declared as RiskClass[], shape: { panel: review.panel, readerModel: review.reader_model, platform: review.platform, head, platformReview: platform?.ok ? platform.review : null }, scope, gateTagged, targeted: { classes: targeted.classes, ran }, numbers: scanNumbers(kept(added)), force, gated: list('--gated'), floor, tiers: auditEffort !== 'host', criticalFound: has('--critical-found'), adversarialRan: has('--adversarial-ran'), reviewedNumbers: flag('--reviewed-numbers'), - history: { fullPasses: pass, last, fixedBlocking: has('--fixed-blocking'), fixedBelow: (has('--fixed-below') || (postReview && pass > 0)) && last !== 'fix-check', blockingOpen: has('--blocking-open'), touchedGate: has('--touched-gate') || (!carried && (!!fixRange?.touched_gate || (postReview && pass > 0))), pass1Depth, rangeRuntimeLines: fixRange?.runtime_lines, granted: grant, fixChecks: has('--fix-checks') ? fixChecks : undefined, postReview, chained: inLoopLink }, + history: { priorRounds, priorFull, ...(roundGrant ? { roundGrant } : {}), fullPasses: pass, last, fixedBlocking: has('--fixed-blocking'), fixedBelow: (has('--fixed-below') || (postReview && pass > 0)) && last !== 'fix-check', blockingOpen: has('--blocking-open'), touchedGate: has('--touched-gate') || (!carried && (!!fixRange?.touched_gate || (postReview && pass > 0))), pass1Depth, rangeRuntimeLines: fixRange?.runtime_lines, granted: grant, fixChecks: has('--fix-checks') ? fixChecks : undefined, postReview, chained: inLoopLink }, }); + if (plan.next.reason.startsWith('PR_ROUND_CAP')) plan.next.reason += `: gstack-approvals round-grant --pr ${flag('--pr') ?? ''} --head ${head} --kind extra-round --reason "" --by , then rerun gstack-ship-preflight and pass the --round-grant id its PR_REVIEW_FLAGS: line prints; the grant buys one round at ${head.slice(0, 12)} and is then spent (docs/troubleshooting.md#pr-round-cap)`; if (carried) plan.next.reason = `the edits after the last fix-check ${fixCheckAt!.slice(0, 12)} are ${carried.paths.length ? `${carried.verdict === 'plain' ? 'plain docs' : `docs (${carried.paths.join(', ')})`}${carried.stamps.length ? ' and release stamps' : ''}` : 'release stamps'} (docsChangeSince), no gate-class edit (GST-1702): ${plan.next.reason}`; else if (postReview && pass > 0) plan.next.reason = `edits after the review bound (Step 16 stage 2.1) plan as a fix to a gate-class path, never a note: ${plan.next.reason}`; const ranArg = flag('--targeted-ran'); @@ -285,7 +308,7 @@ function main(): number { if (platform) out.push(platform.ok ? `PLATFORM_REVIEW: ${platform.review.id} reviewer=${platform.review.reviewer} head=${platform.review.head}` : `PLATFORM_REVIEW: none (${platform.reason})`); if (fixRange) out.push(`FIX_RANGE: ${fixRange.runtime_lines === null ? `unread (${fixRange.error})` : `runtime_lines=${fixRange.runtime_lines}`} base=${fixRange.base}`); if (targetedDeltaOut) out.push(`TARGETED_DELTA: range_base=${targetedDeltaOut.range_base} paths=${targetedDeltaOut.paths.join(',')} classes=${classList(targetedDeltaOut.classes)}`); - out.push(reviewPlanLine(plan, pass + (plan.next.step === 'full' || plan.next.step === 'scoped' ? 1 : 0)), `NEXT: ${plan.next.step} (${plan.next.reason})`); + out.push(reviewPlanLine(plan, pass + (plan.next.step === 'full' || plan.next.step === 'scoped' ? 1 : 0), priorRounds), `NEXT: ${plan.next.step} (${plan.next.reason})`); for (const e of plan.errors) out.push(`DEPTH_ERROR: ${e.code} input=${e.input} detail=${e.detail}; fix: ${e.repair}${e.result ? ` (${e.result})` : ''}`); for (const d of plan.dispatches) { const key = d.name.split(' ')[0]; diff --git a/bin/gstack-ship-receipt b/bin/gstack-ship-receipt index 5709d718e..6977267aa 100755 --- a/bin/gstack-ship-receipt +++ b/bin/gstack-ship-receipt @@ -15,6 +15,8 @@ * gstack-ship-receipt census --repo --since [--cohort ] [--limit ] [--json] * gstack-ship-receipt carry (--pr [--repo ] | --body ) [--base ] [--head ] [--pregate ] [--dry-run] [--out ] [--json] * gstack-ship-receipt docs-caps [--base ] [--policy ] [--json] + * gstack-ship-receipt history (--pr [--repo ] | --body ) [--head ] [--json] + * gstack-ship-receipt stub (--pr [--repo ] | --body ) --run [--head ] [--review-loop ] [--void] * * `write` validates against `gstack-artifact schema ship-receipt`, prints the * fenced block (and SHIP_RECEIPT: on stderr), writes it to --out, @@ -51,7 +53,7 @@ import { } from '../lib/ship-receipt'; import { checkDocsCaps, docsCapLine, docsExceptionLine, parseReceiptDocs } from '../lib/ship-receipt-docs'; import { comparePath, contextPacket, PACKET_SECTION_CAP, readScopedReview, touchedPaths } from '../lib/ship-patch'; -import { planRecheck, readRecheck, recheckPacket, recheckRecordTemplate } from '../crew/lib/ship-recheck'; +import { planRecheck, recheckPacket } from '../crew/lib/ship-recheck'; import { carryExcludeBinds, deeper, depthBelow, exceptionHead, exceptionLoopProblem, exceptionProblems, parseReviewLoopException, parseReviewTargeted, plainDocsSince, platformReceiptDepth, receiptExclude, receiptReviewAtHead, receiptTargetedAtHead, reviewLoopExceptionLine, targetedClassesSince, writeExcludeBinds } from '../lib/ship-receipt-depth'; import { RISK_CLASSES, type RiskClass } from '../lib/review-risk'; import { checkReceiptProse, proseLine } from '../lib/ship-receipt-prose'; @@ -60,6 +62,8 @@ import { readPause, receiptBaseRed } from '../lib/base-red'; import { readRuledNotes, ruledNoteText } from '../lib/ruled-notes'; import { appliedGateDispositions, gateDispositionText } from '../lib/gate-dispositions'; import { laneExceptionBodyLines } from '../lib/test-lane-exception'; +import { historyLine, placeRunEntry, prReviewHistory, reviewRoute, runStub } from '../lib/pr-review-history'; +import { grantAt, readReviewRoundGrants } from '../lib/review-round-grant'; import { readMechanicalLines } from '../lib/ship-mechanical'; import { isRegistryUnavailable, loadRegistryFromBase } from '../lib/regen'; @@ -86,8 +90,19 @@ const HELP = `gstack-ship-receipt — the \`\`\`gstack-ship-receipt\`\`\` block RECEIPT_CARRY_TREE_MISMATCH / RECEIPT_CARRY_REFUSED leave the body unchanged (exit 3); a receipt that records a pregate needs --pregate current for HEAD (RECEIPT_CARRY_PREGATE_STALE); a product change on linear history whose range-diff is within the re-check cap prints - RECHECK: eligible … packet=: one reader reads it, then --recheck (J1); + RECHECK: advisory … packet=: one reader may read it for advice; it never carries + the receipt, so the head that merges runs /ship (J1, GST-2673); needs git >= 2.39 (RECEIPT_GIT_TOO_OLD) + history --pr [--repo ] | --body [--head ] + R51 per pull request (docs/review-policy.md#rounds-per-pull-request): sums the review rounds + the receipt and its runs block record across every head and /ship run, and prints + PR_REVIEW_HISTORY:, PR_REVIEW_FLAGS: (what Step 9 passes to every gstack-review-plan call) and + PR_REVIEW_ROUTE: first|final|read-only (why); a PR body gh cannot read prints source=unavailable + with its cause and fix on stderr (exit 1), and the plan then counts as it did before + stub --pr | --body --run [--head ] [--review-loop ] [--void] + Step 9: record this /ship run's rounds so far in the runs block before its receipt exists, so a + run that stops still counts; the run's receipt write (same --run) replaces it; --void marks an + infrastructure failure that counts nothing docs-caps [--base ] /ship Step 14.5: one DOCS_CAP: / ok|over line per docs.caps entry of the reviewed policy (origin/'s .gstack/ship-policy.json; --policy reads that file instead); any over (or absent) file exits 1 (DOCS_AUDIT_BLOCKED) @@ -338,7 +353,7 @@ function cmdWrite(rest: string[], json: boolean): number { policy: flag(rest, '--policy') ?? tree?.policy, queue_mode: flag(rest, '--queue-mode'), preregistration: flag(rest, '--preregistration'), history: flag(rest, '--history'), ...pregate, issues: issuesFile ? receiptIssuesFrom(issuesFile) : undefined, approval: approval.kind === 'ok' ? approval.approval : undefined, review_loop: reviewLoop, ...(docs?.ok ? { docs: docs.docs } : {}), ...product, - gstack_version: installedGstackVersion(), review_depth: reviewDepth, review_loop_exception: loopException?.ok ? loopException.exception : undefined, ruled_notes: ruledNotes.length ? ruledNotes : undefined, gate_dispositions: gateDispositions, mechanical: mechanical.length ? mechanical : undefined, review_targeted: targeted?.ok ? targeted.targeted : undefined, + gstack_version: installedGstackVersion(), review_depth: reviewDepth, review_loop_exception: loopException?.ok ? loopException.exception : undefined, review_round_grants: roundGrantsFor(repoRoot, flag(rest, '--pr')), ruled_notes: ruledNotes.length ? ruledNotes : undefined, gate_dispositions: gateDispositions, mechanical: mechanical.length ? mechanical : undefined, review_targeted: targeted?.ok ? targeted.targeted : undefined, design: review.frontend ? { mode: 'static', reason: 'no preview declared' } : undefined, base_red: pause ? receiptBaseRed(pause) : undefined, review_exclude: receiptExclude(review.exclude), @@ -657,6 +672,7 @@ function cmdCarry(rest: string[], json: boolean): number { if ((pr === undefined) === (bodyFile === undefined)) { process.stderr.write(`gstack-ship-receipt carry: pass --pr or --body , not both\n${HELP}\n`); return EXIT.usage; } const repoRoot = git(['rev-parse', '--show-toplevel']); if (!repoRoot) { process.stderr.write('gstack-ship-receipt carry: run it inside the git checkout whose head carries the receipt\n'); return EXIT.usage; } + if (rest.includes('--recheck')) { process.stderr.write('gstack-ship-receipt carry: --recheck is gone: a scoped re-check is advice only and never carries a receipt (GST-2673); run /ship on HEAD for the merge head\'s full review (docs/review-policy.md#rounds-per-pull-request)\n'); return EXIT.refused; } const head = (flag(rest, '--head') ?? git(['rev-parse', 'HEAD'], repoRoot))?.toLowerCase(); if (!head || !/^[0-9a-f]{40,64}$/.test(head)) { process.stderr.write('gstack-ship-receipt carry: cannot resolve HEAD\n'); return EXIT.usage; } const refused = (code: 'QUEUE_RECEIPT_MISSING' | 'QUEUE_RECEIPT_CONDITIONAL' | 'RECEIPT_CARRY_REFUSED' | 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_SCOPED_REVIEW' | 'RECEIPT_CARRY_TREE_MISMATCH' | 'RECEIPT_GIT_TOO_OLD' | 'RECEIPT_CARRY_PREGATE_STALE', message: string) => { @@ -724,7 +740,6 @@ function cmdCarry(rest: string[], json: boolean): number { const retarget = reviewedBase !== base.replace(/^origin\//, ''); let plan: ReturnType; let scopedDryRun: string | undefined; - let recheck: string | undefined; if (!ancestor) { // Rewritten history: the receipt follows only onto a tree it already covers, with the product diff it recorded. const recorded = receipt.product_patch_id !== undefined ? (receipt.product_patch_id === 'none' ? '' : receipt.product_patch_id) : fromKnown ? productPatchAgainstBase(repoRoot, rules, baseRef, from) : { error: 'the receipt records no product patch-id and its head is not in this clone' }; @@ -852,7 +867,7 @@ function cmdCarry(rest: string[], json: boolean): number { // Evidence for the record, never the decision: a slow range-diff is reported unavailable rather than waited for. const rangeRaw = spawnSync('git', ['range-diff', '--no-color', `${rangeBase}..${from}`, `${headBase}..${head}`], { cwd: repoRoot, encoding: 'utf8', timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }); const rangeDiff = rangeRaw.status === 0 ? (rangeRaw.stdout.trim().split('\n').slice(0, 20).join('\n') || '(empty: identical ranges)') : `unavailable: ${(rangeRaw.stderr ?? '').trim().split('\n')[0] || (rangeRaw.signal ? `range-diff killed by ${rangeRaw.signal} after 15 s` : 'range-diff failed')}`; - // J1: a bounded product change since the reviewed head gets one reader on the range-diff instead of a full /ship (crew/lib/ship-recheck.ts). + // J1: a bounded product change since the reviewed head gets an advisory packet for one reader; it never carries (crew/lib/ship-recheck.ts, GST-2673). if (changedProduct.length) { const named = changedProduct.filter(p => !p.startsWith('(') && !p.includes(' (')); const inter = named.length ? spawnSync('git', ['diff', '--no-color', '--no-ext-diff', from, head, '--', ...named.map(p => `:(literal)${p}`)], { cwd: repoRoot, encoding: 'utf8', timeout: 30_000, maxBuffer: 64 * 1024 * 1024 }) : null; @@ -863,23 +878,18 @@ function cmdCarry(rest: string[], json: boolean): number { const context = contextPaths.length ? contextPacket(repoRoot, { reviewedBase: rangeBase, reviewed: from, currentBase: headBase, current: head }, contextPaths) : undefined; const bound = context ? { rangeBase, context: context.text } : {}; const r = planRecheck({ code: 'RECEIPT_CARRY_PRODUCT_CHANGED', ancestor, retarget, rangeDiff: fullRange, unnamedPaths: named.length !== changedProduct.length, legacy: !receipt.review_depth, walkCut, contextPaths: contextPaths.length, context, binary }); - const record = flag(rest, '--recheck'); if (!r.ok) process.stderr.write(`RECHECK: not eligible (${r.reason}); run /ship on ${head.slice(0, 12)}\n`); - else if (record) { - const read = readRecheck(record, { from, head, sha256: r.sha256, ...bound }); - if (!read.ok) return refused('RECEIPT_CARRY_REFUSED', `--recheck: ${read.message}`); - recheck = `scoped re-check by ${read.record.reader} (range-diff ${r.lines} lines${context ? `; base context moved in ${contextPaths.join(', ')}; range_base ${rangeBase.slice(0, 12)}` : ''})`; - } else { + else { let where = 'not written (dry run)'; if (!rest.includes('--dry-run')) { const packet = path.resolve(repoRoot, git(['rev-parse', '--git-path', `gstack/recheck-${head.slice(0, 12)}.md`], repoRoot) ?? `.git/gstack/recheck-${head.slice(0, 12)}.md`); try { fs.mkdirSync(path.dirname(packet), { recursive: true }); fs.writeFileSync(packet, recheckPacket({ from, head, plan: r, rangeDiff: fullRange!, ...bound })); where = packet; } catch (e) { where = `unwritable: ${(e as Error).message.split('\n')[0]}`; } } - process.stderr.write(`RECHECK: eligible range_diff_lines=${r.lines} range_diff_sha256=${r.sha256} packet=${where}; one reader reads it, then carry --recheck (${recheckRecordTemplate({ from, head, sha256: r.sha256, ...bound })}); a blocking finding means /ship on ${head.slice(0, 12)}\n`); + process.stderr.write(`RECHECK: advisory range_diff_lines=${r.lines} range_diff_sha256=${r.sha256} packet=${where}; one reader may read it for advice, but it never carries the receipt (GST-2673): run /ship on ${head.slice(0, 12)} for the merge head's full review (docs/review-policy.md#rounds-per-pull-request)\n`); } } - plan = planCarry({ from, head, changed, productPatchId: { from: reviewed as string, head: current as string }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff, ...(retarget ? { retargetedFrom: reviewedBase } : {}), ...(stackParent ? { stackParent } : {}), ...(scopedReview ? { scopedReview } : {}), ...(stampedRows.length ? { stampedRows } : {}), ...(recheck ? { recheck } : {}) }); + plan = planCarry({ from, head, changed, productPatchId: { from: reviewed as string, head: current as string }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff, ...(retarget ? { retargetedFrom: reviewedBase } : {}), ...(stackParent ? { stackParent } : {}), ...(scopedReview ? { scopedReview } : {}), ...(stampedRows.length ? { stampedRows } : {}) }); } if (!plan.ok) return refused(plan.code, plan.message); // Eligibility is not publication: a receipt that recorded a pregate is rebound only with a pregate current for HEAD, @@ -908,8 +918,6 @@ function cmdCarry(rest: string[], json: boolean): number { if (review.exclude.state === 'refused') return refused('RECEIPT_CARRY_REFUSED', `${review.exclude.lines.join('; ')}; run /ship on ${head.slice(0, 12)} once the base policy reads`); const digest = review.exclude.state === 'active' ? review.exclude.record.digest : 'none'; if (!carryExcludeBinds(review.exclude, receipt)) return refused('RECEIPT_CARRY_REFUSED', `review_exclude changed: recorded=${receipt.review_exclude?.digest ?? 'none'} now=${digest} source=${review.exclude.state === 'active' ? review.exclude.record.source : `${base} (no review_exclude_paths)`}; the receipt's digest is the --review-exclude argument write was given, and it names another selection than HEAD ${head.slice(0, 12)} has under the base policy and the two give the PR's files different selections (carry compares those, not the review ledger), so carry does not apply; run /ship on ${head.slice(0, 12)}`); - const riskOf = (d: { class: string; risk?: readonly string[] }) => `${d.class}:${[...(d.risk ?? [])].sort().join(',')}`; - if (recheck && riskOf(now) !== riskOf(receipt.review_depth)) return refused('RECEIPT_CARRY_REFUSED', `HEAD ${head.slice(0, 12)} is risk class ${riskOf(now)}, not the reviewed ${riskOf(receipt.review_depth)}, so a scoped re-check cannot stand in for review; run /ship on ${head.slice(0, 12)}`); if (depthBelow(receipt.review_depth.depth, now.depth)) return refused('RECEIPT_CARRY_REFUSED', `HEAD ${head.slice(0, 12)} needs ${now.depth} review depth (${now.reasons.join(', ')}), above the receipt's ${receipt.review_depth.depth}; run /ship on ${head.slice(0, 12)}`); depthField = { review_depth: { ...now, depth: deeper(receipt.review_depth.depth, now.depth) }, review_exclude: receiptExclude(review.exclude) }; } @@ -1008,6 +1016,76 @@ function cmdDocsCaps(rest: string[], json: boolean): number { return EXIT.fail; } +/** The round grants the branch's approval record holds for this PR (the receipt's review_round_grants). */ +function roundGrantsFor(repoRoot: string | undefined, pr: string | undefined): ShipReceipt['review_round_grants'] { + if (!repoRoot || !pr) return undefined; + const grants = readReviewRoundGrants(repoRoot).filter(g => String(g.pr) === pr); + return grants.length ? grants : undefined; +} + +/** The PR body from --body or gh, or why it cannot be read. */ +function readBody(rest: string[]): { ok: true; body: string; pr?: string } | { ok: false; why: string; fix: string } { + const bodyFile = flag(rest, '--body'); + if (bodyFile) { + try { return { ok: true, body: fs.readFileSync(bodyFile, 'utf8') }; } catch (e) { return { ok: false, why: `${bodyFile} is unreadable (${(e as Error).message.split('\n')[0]})`, fix: 'pass a readable --body file' }; } + } + const pr = flag(rest, '--pr'); + if (!pr || !/^[1-9]\d*$/.test(pr)) return { ok: false, why: '--pr or --body is required', fix: 'pass the open PR number' }; + const repo = flag(rest, '--repo'); + const r = gh(['pr', 'view', pr, ...(repo ? ['--repo', repo] : []), '--json', 'body']); + if (!r.ok) return { ok: false, why: `gh pr view ${pr} failed: ${r.err.split('\n')[0]}`, fix: 'check gh auth status and the PR number, then rerun' }; + try { return { ok: true, body: JSON.parse(r.out).body ?? '', pr }; } catch { return { ok: false, why: 'gh returned no JSON body', fix: 'rerun; check gh auth status' }; } +} + +function postBody(rest: string[], pr: string | undefined, body: string): string | null { + const bodyFile = flag(rest, '--body'); + if (bodyFile) { fs.writeFileSync(bodyFile, body); return null; } + const repo = flag(rest, '--repo'); + const tmp = path.join(fs.mkdtempSync(path.join(process.env.TMPDIR ?? '/tmp', 'gstack-runs-')), 'body.md'); + fs.writeFileSync(tmp, body, { mode: 0o600 }); + const edit = gh(['pr', 'edit', pr!, ...(repo ? ['--repo', repo] : []), '--body-file', tmp]); + fs.rmSync(path.dirname(tmp), { recursive: true, force: true }); + return edit.ok ? null : `gh pr edit failed: ${edit.err}`; +} + +/** R51 per pull request: the rounds the PR body records, and what the next head gets (GST-2673). */ +function cmdHistory(rest: string[], json: boolean): number { + const pr = flag(rest, '--pr') ?? '?'; + const read = readBody(rest); + if (!read.ok) { + process.stderr.write(`gstack-ship-receipt history: ${read.why}; fix: ${read.fix}; until then the review plan counts this run's rounds only\n`); + process.stdout.write(json ? JSON.stringify({ pr, source: 'unavailable', why: read.why }) + '\n' : `PR_REVIEW_HISTORY: pr=#${pr} source=unavailable\n`); + return EXIT.fail; + } + const repoRoot = git(['rev-parse', '--show-toplevel']); + const head = (flag(rest, '--head') ?? (repoRoot ? git(['rev-parse', 'HEAD'], repoRoot) : undefined))?.toLowerCase(); + const h = prReviewHistory(read.body); + const grant = repoRoot && head && /^\d+$/.test(pr) ? grantAt(readReviewRoundGrants(repoRoot), Number(pr), head) : undefined; + const route = reviewRoute(h, { grant: grant?.approval }); + const flagsLine = `PR_REVIEW_FLAGS: --prior-rounds ${h.rounds} --prior-full ${h.full}${grant ? ` --round-grant ${grant.approval}` : ''}`; + if (json) { process.stdout.write(JSON.stringify({ pr, ...h, grant: grant ?? null, route }) + '\n'); return EXIT.ok; } + process.stdout.write(`${historyLine(pr, h)}\n${flagsLine}\nPR_REVIEW_ROUTE: ${route.route} (${route.reason})\n`); + return EXIT.ok; +} + +/** Step 9: this run's rounds so far, recorded before its receipt exists (a started stub), or voided. */ +function cmdStub(rest: string[]): number { + const run = flag(rest, '--run'); + if (!run || !/^[\w.:-]{1,120}$/.test(run)) { process.stderr.write('gstack-ship-receipt stub: --run is required\n'); return EXIT.usage; } + const read = readBody(rest); + if (!read.ok) { process.stderr.write(`gstack-ship-receipt stub: ${read.why}; fix: ${read.fix}\n`); return EXIT.fail; } + let loop: ReturnType; + try { loop = flag(rest, '--review-loop') !== undefined ? parseReviewLoop(jsonArg(flag(rest, '--review-loop'))) : { passes: 1, blocking_found: 0, deferred: 0, rounds: 1 }; } catch (e) { process.stderr.write(`gstack-ship-receipt stub: --review-loop: ${(e as Error).message}\n`); return EXIT.usage; } + if (!loop) { process.stderr.write('gstack-ship-receipt stub: --review-loop needs {passes, blocking_found, deferred[, fix_checks, rounds, scoped]}\n'); return EXIT.usage; } + const head = (flag(rest, '--head') ?? git(['rev-parse', 'HEAD']))?.toLowerCase(); + if (!head || !/^[0-9a-f]{40,64}$/.test(head)) { process.stderr.write('gstack-ship-receipt stub: cannot resolve HEAD\n'); return EXIT.usage; } + const status = rest.includes('--void') ? 'voided' : 'started'; + const err = postBody(rest, read.pr, placeRunEntry(read.body, runStub({ head, run, status, loop }))); + if (err) { process.stderr.write(`gstack-ship-receipt stub: ${err}; the run is not recorded\n`); return EXIT.fail; } + process.stdout.write(`RUN_STUB: run=${run} status=${status} rounds=${loop.rounds ?? loop.passes + (loop.fix_checks ?? 0)} head=${head.slice(0, 12)}\n`); + return EXIT.ok; +} + function main(argv: string[]): number { const [cmd, ...rest] = argv; const json = rest.includes('--json'); @@ -1018,6 +1096,8 @@ function main(argv: string[]): number { if (cmd === 'census') return cmdCensus(rest, json); if (cmd === 'carry') return cmdCarry(rest, json); if (cmd === 'docs-caps') return cmdDocsCaps(rest, json); + if (cmd === 'history') return cmdHistory(rest, json); + if (cmd === 'stub') return cmdStub(rest); process.stderr.write(`gstack-ship-receipt: unknown command ${cmd}\n${HELP}\n`); return EXIT.usage; } diff --git a/changelog.d/count-review-rounds-per-pr.md b/changelog.d/count-review-rounds-per-pr.md new file mode 100644 index 000000000..5fb3fa1c8 --- /dev/null +++ b/changelog.d/count-review-rounds-per-pr.md @@ -0,0 +1 @@ +- **`/ship` now counts review rounds per pull request, and the head that merges always gets a full review.** gstack's two-round review cap (R51) was counted inside each `/ship` run, so a PR shipped five times could be reviewed ten times. `/ship` Step 1 now reads the PR body's receipt history (`gstack-ship-receipt history`), prints `PR_REVIEW_HISTORY:` and `PR_REVIEW_ROUTE:`, and passes the earlier rounds to `gstack-review-plan` (`--prior-rounds`, and `--prior-full` for the full rounds the cap counts). A new head whose own lines changed gets a fresh full review, the PR's last before merge; a PR already at two full rounds gets one read-only full review with no fix round, whose blocker goes to the lane's Captain. A scoped re-check of only what changed is now advice only: `carry` prints `RECHECK: advisory` and refuses `--recheck`, because in the replay a diff-only re-check caught none of 8 real faults that full rounds had caught (docs/evals/pr-round-count-results.md). A run that stops before its receipt still counts (`gstack-ship-receipt stub`), and the lane or Captain can buy one more round with `gstack-approvals round-grant --kind extra-round`; gstack cannot grant itself one. See docs/review-policy.md#rounds-per-pull-request. diff --git a/crew/docs/captain.md b/crew/docs/captain.md index 64ff032b3..83d81079d 100644 --- a/crew/docs/captain.md +++ b/crew/docs/captain.md @@ -668,6 +668,9 @@ case-kind change, closing a contribution without landing it, and anything destru Standing spend is the commonest standing approval: `SPEND` in CREW.md names what the owner pre-approved (train gates, screens, bisects, the backstop, focused paid cases) with the owner's date and words and the cap per rerun; anything over the cap is a fresh ask. +A review round past a PR's two (`PR_ROUND_CAP`) is the lane's or the controller's call, recorded +with `gstack-approvals round-grant`, never an owner ask +([rounds per pull request](../../docs/review-policy.md#rounds-per-pull-request)). **B. The plan ask** ([template](../../captain/templates/plan-ask.md)): before → after, why it matters, what caused this work, the big decisions, and what we need from you in the ask diff --git a/crew/lib/ship-recheck.ts b/crew/lib/ship-recheck.ts index 37a14814e..6e088d9a2 100644 --- a/crew/lib/ship-recheck.ts +++ b/crew/lib/ship-recheck.ts @@ -1,9 +1,9 @@ /** * J1 (GSTA-258 plan H, relabeled J1): a scoped re-check after a refused receipt carry. When `gstack-ship-receipt carry` refuses - * because the product patch changed since the reviewed head, and the change is bounded, one reader reads `git range-diff` of - * the reviewed range against the current one instead of a full second /ship (gbrain-evals #246/#247: about 100k credits per - * full rerun; #300's scoped reader: about 300). A clean verdict bound to that exact range-diff rebinds the receipt; the carry's - * later checks still refuse a deeper review depth or a changed risk class, which need the full /ship. + * because the product patch changed since the reviewed head, and the change is bounded, carry writes a packet of `git + * range-diff` of the reviewed range against the current one, which one reader may read for advice. Since GST-2673 the read + * never rebinds the receipt: a packet-only reader caught 0 of 8 real faults that full rounds had caught (22 of 24 seeded ones; + * docs/evals/pr-round-count-prereg.md), so the head that merges gets /ship's full review. * * Qualifies: RECEIPT_CARRY_PRODUCT_CHANGED on linear history (the receipt's head is an ancestor of HEAD) against the same base. * Does not qualify: RECEIPT_CARRY_TREE_MISMATCH (rewritten history: the reviewed commits are gone, so there is no range to @@ -14,11 +14,9 @@ * their inputs repaired, not a review). * * Moved base context composes (GST-1561, founderstar#563): the context paths' scoped-review sections (lib/ship-patch.ts contextPacket) - * join the range-diff in the one packet, the caps count both, the verdict binds both, and the record also names range_base, the - * commit the reviewed range starts from. + * join the range-diff in the one packet, and the caps count both. */ import { createHash } from 'node:crypto'; -import * as fs from 'node:fs'; export const RECHECK_RANGE_DIFF_CAP = 400; /** The packet's byte cap: 400 lines of unbounded width (a minified bundle) would not bound the one reader's input. */ @@ -62,36 +60,17 @@ export function planRecheck(i: RecheckInput): RecheckPlan { return { ok: true, lines, sha256: sha(text) }; } -/** What range_diff_sha256 binds: the range-diff, then any moved base context's scoped-review sections. */ +/** What the RECHECK line's range_diff_sha256 names: the range-diff, then any moved base context's scoped-review sections. */ const packetMaterial = (rangeDiff: string, context?: string) => (context ? `${rangeDiff.trim()}\n\n${context.trim()}` : rangeDiff.trim()); -/** The clean record a reader writes; range_base only when base context composes into the packet. */ -export const recheckRecordTemplate = (o: { from: string; head: string; sha256: string; rangeBase?: string }) => - JSON.stringify({ from: o.from, head: o.head, ...(o.rangeBase ? { range_base: o.rangeBase } : {}), range_diff_sha256: o.sha256, reader: '', verdict: 'clean' }); - -/** The packet the one reader reads: what to judge, the record to write, then the range-diff verbatim and any moved base context. */ +/** The packet an advisory reader reads: what to judge, that it carries nothing, then the range-diff verbatim and any moved base context. */ export function recheckPacket(o: { from: string; head: string; plan: Extract; rangeDiff: string; context?: string; rangeBase?: string }): string { return [ - `# Scoped re-check: the product patch changed since the reviewed head\n`, + `# Scoped re-check (advice only): the product patch changed since the reviewed head\n`, `reviewed ${o.from}${o.context ? ` (range_base ${o.rangeBase})` : ''}; current ${o.head}. Below is \`git range-diff\` of the reviewed range against the current one, then the diff of the changed product paths between the two heads${o.context ? ', then the hunks where base context moved next to the reviewed ones' : ''} (${o.plan.lines} lines).`, 'Review only what changed between the two ranges, against the blocking floor: would fail a test, break production, or lose data or secrets.', - `Reply NO FINDINGS, or one finding per line with path:line, Severity and Blocks. A clean reply is recorded as ${recheckRecordTemplate({ ...o, sha256: o.plan.sha256 })}.`, - 'A blocking finding means the full /ship on the current head.\n', + 'Reply NO FINDINGS, or one finding per line with path:line, Severity and Blocks.', + 'This read is advice for the lane only. It never carries the receipt: the head that merges still gets a full review from /ship (GST-2673; docs/review-policy.md#rounds-per-pull-request).\n', '```diff', o.rangeDiff.trim(), '```', '', ...(o.context ? [o.context.trim(), ''] : []), ].join('\n'); } - -export interface RecheckRecord { from: string; head: string; range_base?: string; range_diff_sha256: string; reader: string; verdict: 'clean' } - -/** A clean re-check record bound to this carry's from, head and range-diff, or why it does not stand. */ -export function readRecheck(file: string, bind: { from: string; head: string; sha256: string; rangeBase?: string }): { ok: true; record: RecheckRecord } | { ok: false; message: string } { - let v: Record; - try { v = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return { ok: false, message: `${file} is not readable JSON (${(e as Error).message.split('\n')[0]})` }; } - if (!v || typeof v !== 'object') return { ok: false, message: `${file} is not a JSON object` }; - if (v.verdict !== 'clean') return { ok: false, message: `the re-check is ${JSON.stringify(v.verdict)}, not clean: run /ship on ${bind.head.slice(0, 12)}` }; - if (typeof v.reader !== 'string' || !v.reader.trim()) return { ok: false, message: 'the re-check names no reader' }; - for (const [k, want] of [['from', bind.from], ['head', bind.head], ['range_diff_sha256', bind.sha256], ...(bind.rangeBase ? [['range_base', bind.rangeBase] as const] : [])] as const) { - if (v[k] !== want) return { ok: false, message: `the re-check is for ${k} ${String(v[k] ?? 'none').slice(0, 12)}, not ${want.slice(0, 12)}` }; - } - return { ok: true, record: v as unknown as RecheckRecord }; -} diff --git a/crew/test/ship-recheck.test.ts b/crew/test/ship-recheck.test.ts index 8106281bf..fe1565a6a 100644 --- a/crew/test/ship-recheck.test.ts +++ b/crew/test/ship-recheck.test.ts @@ -1,9 +1,9 @@ /** - * J1 (GSTA-258 L4): a scoped re-check after a refused receipt carry. Each refusal reason that does or does not qualify, - * the record binding, and the carry end to end: a bounded product change prints RECHECK: eligible and writes the packet, - * a clean record bound to that packet carries the receipt with the reader named, and a changed risk class, a legacy - * receipt and more paths than the walk names never take the re-check (the /ship p1 red-team and security findings). - * Moved base context joins the packet instead (GST-1561; test/ship-receipt-carry-mixed.test.ts). + * J1 (GSTA-258 L4), advice only since GST-2673: a scoped re-check packet after a refused receipt carry. Each refusal + * reason that does or does not qualify, and the carry end to end: a bounded product change prints RECHECK: advisory and + * writes the packet, and no re-check record carries the receipt, because a diff-only re-check caught 0 of 8 real faults + * full rounds had caught; a legacy receipt and more paths than the walk names get no packet. Moved base context joins + * the packet (GST-1561; test/ship-receipt-carry-mixed.test.ts). */ import { afterEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; @@ -11,7 +11,7 @@ import * as os from 'node:os'; import * as path from 'node:path'; import { EXIT } from '../../lib/headless-artifacts'; import { extractReceipt, placeReceipt } from '../../lib/ship-receipt'; -import { planRecheck, readRecheck, RECHECK_PACKET_BYTES, RECHECK_RANGE_DIFF_CAP } from '../lib/ship-recheck'; +import { planRecheck, RECHECK_PACKET_BYTES, RECHECK_RANGE_DIFF_CAP } from '../lib/ship-recheck'; import { cleanup, makeFixtureRepo, runBin, type FixtureRepo } from '../../test/helpers/restamp-fixture'; const repos: FixtureRepo[] = []; @@ -46,20 +46,6 @@ describe('planRecheck: which refusals qualify', () => { }); }); -describe('readRecheck binds to from, head and the range-diff', () => { - test('only a clean record for this exact range-diff stands', () => { - const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'recheck-')); - const bind = { from: 'a'.repeat(40), head: 'b'.repeat(40), sha256: 'c'.repeat(64) }; - const write = (o: object) => { const f = path.join(dir, `${Math.random()}.json`); fs.writeFileSync(f, JSON.stringify(o)); return f; }; - const good = { from: bind.from, head: bind.head, range_diff_sha256: bind.sha256, reader: 'anthropic/claude-opus-5-5', verdict: 'clean' }; - expect(readRecheck(write(good), bind).ok).toBe(true); - expect(readRecheck(write({ ...good, verdict: 'blocking' }), bind)).toMatchObject({ ok: false, message: expect.stringContaining('not clean') }); - expect(readRecheck(write({ ...good, range_diff_sha256: 'd'.repeat(64) }), bind)).toMatchObject({ ok: false, message: expect.stringContaining('range_diff_sha256') }); - expect(readRecheck(write({ ...good, reader: '' }), bind)).toMatchObject({ ok: false, message: 'the re-check names no reader' }); - fs.rmSync(dir, { recursive: true, force: true }); - }); -}); - /** A branch reviewed at one commit, with a receipt written by gstack-ship-receipt write (so it records review_depth). */ function reviewed(files: Record = { 'src/app.ts': 'export const a = 2;\n' }) { const repo = makeFixtureRepo({ prefix: 'ship-recheck-' }); repos.push(repo); @@ -83,10 +69,10 @@ function reviewed(files: Record = { 'src/app.ts': 'export const }; return { repo, from, body, env, commit }; } -const eligible = (err: string) => /^RECHECK: eligible range_diff_lines=(\d+) range_diff_sha256=([0-9a-f]{64}) packet=(\S+);/m.exec(err); +const eligible = (err: string) => /^RECHECK: advisory range_diff_lines=(\d+) range_diff_sha256=([0-9a-f]{64}) packet=(\S+);/m.exec(err); describe('carry with a scoped re-check (CLI)', () => { - test('a bounded product change prints RECHECK: eligible, keeps the refusal, and a clean record carries with the reader named', () => { + test('a bounded product change prints RECHECK: advisory and keeps the refusal; a clean record bound to the packet carries nothing', () => { const { repo, from, body, env, commit } = reviewed(); const head = commit({ 'src/app.ts': 'export const a = 3;\n' }, 'fix: a=3'); const refused = runBin(repo, 'gstack-ship-receipt', ['carry', '--body', body], env); @@ -94,33 +80,16 @@ describe('carry with a scoped re-check (CLI)', () => { expect(refused.out.trim().split('\n')[0]).toBe('CARRY: refused (RECEIPT_CARRY_PRODUCT_CHANGED)'); const m = eligible(refused.err); expect(m).not.toBeNull(); + expect(refused.err).toContain('it never carries the receipt (GST-2673)'); expect(fs.readFileSync(m![3]!, 'utf8')).toContain('export const a = 3;'); + expect(fs.readFileSync(m![3]!, 'utf8')).toContain('advice only'); + const before = fs.readFileSync(body, 'utf8'); const record = path.join(repo.root, 'recheck.json'); fs.writeFileSync(record, JSON.stringify({ from, head, range_diff_sha256: m![2], reader: 'anthropic/claude-opus-5-5', verdict: 'clean' })); const carried = runBin(repo, 'gstack-ship-receipt', ['carry', '--body', body, '--recheck', record, '--out', path.join(repo.root, 'run')], env); - expect([carried.status, carried.err.slice(0, 400)]).toEqual([EXIT.ok, expect.any(String)]); - expect(carried.out.trim().split('\n')[0]).toBe(`CARRY: carried from ${from.slice(0, 12)} to ${head.slice(0, 12)} (scoped re-check by anthropic/claude-opus-5-5 (range-diff ${m![1]} lines))`); - expect(extractReceipt(fs.readFileSync(body, 'utf8')).receipt).toMatchObject({ head, carry: { from } }); - const stale = path.join(repo.root, 'stale.json'); - fs.writeFileSync(stale, JSON.stringify({ from: head, head, range_diff_sha256: 'f'.repeat(64), reader: 'x', verdict: 'clean' })); - commit({ 'src/app.ts': 'export const a = 4;\n' }, 'fix: a=4'); - const bad = runBin(repo, 'gstack-ship-receipt', ['carry', '--body', body, '--recheck', stale], env); - expect([bad.status, bad.out.trim().split('\n')[0]]).toEqual([EXIT.refused, 'CARRY: refused (RECEIPT_CARRY_REFUSED)']); - }, 60_000); - - test('a clean re-check cannot carry across a changed risk class', () => { - const { repo, from, body, env, commit } = reviewed(); - const before = extractReceipt(fs.readFileSync(body, 'utf8')).receipt!.review_depth!; - const head = commit({ 'src/app.ts': 'export const a = 3;\n', 'src/billing.ts': 'export function charge(cents: number) { return stripe.charges.create({ amount: cents }); }\n' }, 'feat: billing'); - const refused = runBin(repo, 'gstack-ship-receipt', ['carry', '--body', body], env); - const m = eligible(refused.err); - expect(m).not.toBeNull(); - const record = path.join(repo.root, 'recheck.json'); - fs.writeFileSync(record, JSON.stringify({ from, head, range_diff_sha256: m![2], reader: 'x', verdict: 'clean' })); - const r = runBin(repo, 'gstack-ship-receipt', ['carry', '--body', body, '--recheck', record], env); - expect(r.status).toBe(EXIT.refused); - expect(r.err).toMatch(/risk class|review depth/); - expect(before.risk ?? []).not.toContain('money'); + expect(carried.status).toBe(EXIT.refused); + expect(carried.err).toContain('--recheck is gone'); + expect(fs.readFileSync(body, 'utf8')).toBe(before); }, 60_000); test('a legacy receipt, more changed paths than the walk names, and moved base context print RECHECK: not eligible', () => { diff --git a/docs/evals/pr-round-count-prereg.md b/docs/evals/pr-round-count-prereg.md new file mode 100644 index 000000000..16bb40028 --- /dev/null +++ b/docs/evals/pr-round-count-prereg.md @@ -0,0 +1,75 @@ +# Prereg: does a scoped re-check reader lose blockers that a full round would catch? (GST-2673) + +Status: locked 2026-11-13, before any paid call. Owner: GStack Minder (GSTA-36). Runs once, on the branch that adds +the per-PR round count ([review-policy.md](../review-policy.md#rounds-per-pull-request)), before that branch merges. + +## Question +Once a pull request has had a full review round, design A sends each new head to one scoped re-check reader that +sees only what changed since the last reviewed head (the [carry re-check](../troubleshooting.md#receipt-carry-recheck) +packet), instead of a fresh full round. Does that reader still find the blocking faults that review fixes create +after round 1, and stay quiet on heads that had none? + +Where the evidence comes from: one crew working on an internal product had three heavily reviewed PRs whose later +rounds raised dozens of findings. A small share led to a real code fix, and most of those repaired a fault created +after round 2 inside the diff since the previous head, which is the scoped reader's range. One more fault, a race a +round-1 fix created, sat outside that range. That crew, its product and its repository are not named here; its +packets and labels stay private, and this repository reports only aggregates. + +## The decision this changes (R97) +If the scoped reader keeps the blockers (Part 2's bars met), later heads go to the scoped re-check by default and +this branch merges as built. If it loses them, the branch does not merge as built: later heads keep a full round +(the count and stop rule stay, the re-check route is narrowed or widened first) and the loss is reported. Part 1 +decides the drift threshold the router ships with. + +## Part 1: free deterministic replay (no model calls) +Over every PR body with receipts in gstack and in the source crew's repository (read only), run the new counter +and router (`lib/pr-review-history.ts`, `reviewRoute`) head by head and record: +1. Route labels for every later head: re-check eligible, re-check refused (with carry's reason), re-check found a + blocker then a full /ship ran, a run stopped with no receipt, or the lane ignored the route. +2. Rounds: on PRs with three or more /ship runs, at most two full rounds planned; on one-run PRs, no plan change. +3. Drift: how often `PR_DRIFT_LINES` (400) fires and at which head. If a value between 200 and 800 would send the + known out-of-range fault to a full round without firing on more than a quarter of the multi-head PRs, that value + replaces 400 before Part 2 runs, and the change is recorded in the results. +4. Coverage, scored on each labelled fault's cause line: whether that line sits inside the packet design A builds. + +## Part 2: paid scoped-reader replay (no-loss) +**Cases.** 48 packets, each the packet `gstack-ship-receipt carry` writes (`crew/lib/ship-recheck.ts` +`recheckPacket`, the text on this branch) for one later head: +- 32 positives: every in-range fix-made fault from the source sample (fewer than ten), plus faults seeded into fix + ranges of gstack's own public PRs to make 32. A seeded fault is one edit in a later head's own range, of a class + a test would catch or production would feel (an inverted condition, an off-by-one, a dropped error path, a wrong + variable, a missing await, a lost write). A separate subagent seeds them; each label (path, line, cause, and + two to four cause words) is written and committed to the private label file before any reader runs. +- 16 controls: later heads whose round found only notes, from the source sample and from gstack's PRs. +- The out-of-range race is a known miss: listed in the results, not scored. + +**Reader.** The lane model, Claude Opus 5.5, through the Messages API with the packet as the whole prompt and no +tool or repository access, plus one fixed output line: "List each blocking finding on its own line as BLOCKING: +: , then the record." This reads less than a real reader, which can open files, so a loss here +is an upper bound on the real one. A model refusal is a result, never a swap (R95). + +**Kind and trials.** `behavior`: 3 independent trials per packet. A positive passes when at least 2 of 3 trials +list a BLOCKING line within 3 lines of the labelled line in the labelled path, carrying at least one of its cause +words. A control fails when at least 2 of 3 trials list any BLOCKING line. Matching is a script, not a judge. + +**Bars, fixed now.** +1. Recall on the 32 positives at least 0.85, reported with its 95% Wilson interval. The smallest difference this size + can tell apart from the bar is about 0.15. +2. At most 2 of 16 controls fail, with the 95% interval of the control failure rate. +3. Paired, on the real faults: each fault's scoped-reader result beside the later full round that found it (a full + round found every one, by construction), with the paired difference and its 95% interval. No bar: too few faults. + +**Verdict.** Both bars met: KEEP the scoped re-check as the default for later heads. Recall below the bar or more +than 2 controls failing: FIX-METHOD (widen the packet or send those heads to a full round), after one "Why null?" +cycle (did the reader read the range, do the faults fit it, is n enough, does a full round see what it missed). + +**Reruns.** None, except the one AGENTS.md allows: a red case may be rerun once at the same packet as a new panel +of 3; a pass is green with a flaky note and a red is real. Harness and infrastructure failures never rerun. + +**Budget.** 144 dispatches at about $1 each, capped at $160 including any rerun. A cap stop ends the run +incomplete with every finished case reported. + +## After merge (separate brief) +A free 7-day before-and-after on full rounds per PR, re-checks per PR and /ship runs per PR (with each window's daily +spread), and a paid escape audit on merged PRs whose later code only re-checks read, under its own prereg. The +ledger row is `ship-review-panel` in `docs/inventory/evidence.json`; measure by 2026-12-08. diff --git a/docs/evals/pr-round-count-results.md b/docs/evals/pr-round-count-results.md new file mode 100644 index 000000000..575a19498 --- /dev/null +++ b/docs/evals/pr-round-count-results.md @@ -0,0 +1,50 @@ +# Per-PR review rounds replay: results (GST-2673) + +We learned that a reviewer shown only the diff since the last reviewed head catches planted one-line bugs but missed +every real fault that later full review rounds had caught. You should give a pull request's final head a full review +before it merges, and treat a diff-only re-check as advice: that is what gstack's /ship now does. + +Preregistration: [pr-round-count-prereg.md](pr-round-count-prereg.md), locked 2026-11-13 before any paid call. All +figures below are counts with 95% Wilson intervals. + +## What worked + +- **Counting rounds per pull request works.** The counter reads the receipt history the PR body already keeps. Over + 306 gstack PRs with receipts it changed no plan (none had three or more /ship runs, 295 had one). In the other + crew's sample of 88 PRs, 2 had three or more runs and both had gone past two rounds, which is the case the stop rule + is for. +- **The re-check reader finds planted bugs and stays quiet on clean heads.** On gstack's own PRs it found 22 of 24 + seeded faults (0.92, 0.74 to 0.98) and flagged no blocker on 12 clean heads (0 of 12, 0 to 0.24). + +## What didn't + +- **It missed all 8 real faults.** Another crew's internal product supplied 8 faults that review fixes had created + after round 1 and a later full round had caught. The re-check reader found 0 of 8 (0 to 0.32). Paired against the + full round that found each one (8 of 8 by construction), the difference is -1.00 (-1.00 to -0.68). It wrote no + finding on 34 of 36 reads, so the scorer is not the cause. The other 2 reads, both on one fault, named the right + file and fault 14 lines from the labelled line, outside the preregistered 3-line window; read leniently that is 1 of + 8 (0.02 to 0.47). It flagged none of 3 clean heads from that sample. +- **Bar 1 failed.** Recall over all 32 positives was 22 of 32 (0.69, 0.51 to 0.82), under the 0.85 bar. Bar 2 held: + 0 of 15 controls failed (0 to 0.20). The preregistered verdict is FIX-METHOD. +- **Why null?** The reader did read the range. The real faults sit in it, but each is wrong only against code, data + or deployment order outside the diff (a migration that sorts before the backfill it depends on, a sign-in id + compared against the wrong field), while every seeded fault is visible on its changed line. The 8 faults come from + 3 PRs, so they are not independent draws; even counting each PR as one draw, missing all of them at a true recall of + 0.85 has odds of about 1 in 300. The reader had no repository access, as preregistered, so a reader that can open + files may do better; that is not measured. + +## What changed + +The count and the stop at two full rounds stay. A head whose own added and removed lines are byte-identical to the +reviewed head's keeps its receipt, as before. Any other head gets a fresh full review, the PR's last before merge; a +PR already at two full rounds gets one read-only full review with no fix round. The scoped re-check still writes its +packet, but it never carries a receipt, and that also changes the carry re-check that was already on main +([rounds per pull request](../review-policy.md#rounds-per-pull-request)). The drift threshold Part 1 was to tune is +gone with the re-check route: it never fired on either sample. + +## Departures from the preregistration + +- 15 controls ran, not 16: the other crew's sample had 3 clean later heads, not 4. +- The private leg ran twice. The first run's scorer dropped findings written in bold, and its raw output was deleted + before that was noticed, so it could not be rescored. The prereg forbids rerunning a harness failure; the rerun, + with the repaired scorer, is the one reported above. diff --git a/docs/inventory/evidence.json b/docs/inventory/evidence.json index cc04c39ce..45c1a315a 100644 --- a/docs/inventory/evidence.json +++ b/docs/inventory/evidence.json @@ -590,7 +590,8 @@ "seed": "GEVA-2, 2026-11-02: ship: review panel (specialist, adversarial, targeted, outside voice, red team): untested (unfair test: none arm on the SDK stub; arms from different harnesses and gstack versions; cohort mined from gstack's own catches)", "aliases": [ "ship: review panel (specialist, adversarial, targeted, outside voice, red team)" - ] + ], + "note": "GST-2673 adds the per-PR round count to Step 9 (docs/review-policy.md#rounds-per-pull-request); its replay (docs/evals/pr-round-count-prereg.md) found a diff-only re-check caught 0 of 8 real faults, so re-checks are advice only and the merge head gets a full review. Owner GStack Minder (GSTA-36); measure by 2026-12-08" }, "ship-docs-audit": { "status": "untested", diff --git a/docs/review-policy.md b/docs/review-policy.md index 792067d24..4d760c563 100644 --- a/docs/review-policy.md +++ b/docs/review-policy.md @@ -110,6 +110,9 @@ incomplete coverage, which blocks until the reviewer is rerun. including a grant for a stop head before `--range-base` (an earlier /ship). A fix-check never earns another, so the grant cannot repeat, and a stop after the granted fix-check still goes to the owner. The cap approves nothing. + This cap counts rounds inside one run. Across heads and runs the PR's own + count applies ([rounds per pull request](#rounds-per-pull-request)), and an + extra round there is the lane's or Captain's grant, never an owner ask. Edits that /ship Step 16 later finds after the review bound are a new stop: a new grant at a stop head after the last fix-check's commit, passed as `gstack-review-plan --post-review --last fix-check --range-base @@ -128,6 +131,65 @@ incomplete coverage, which blocks until the reviewer is rerun. symlink or gitlink file in that range, or a commit the gate scan tags there (a `[skip ci]` message), still stops. + +### Rounds per pull request (R51, GST-2673) + +The two-round cap is per pull request, counted across every head, every `/ship` +run and every reader. Each run used to start its own count, so a PR pushed five +times could be reviewed ten times. The count now lives where every host can read +it: the PR body, which already keeps each run's `review_loop` in the receipt and +the `gstack-receipt-runs` block. + +The PR's last review before merge is a full review of its final head. A scoped +re-check that reads only what changed since the last reviewed head is advice +only: it never carries a receipt and is not one of the two rounds. In the replay +behind this rule ([prereg](evals/pr-round-count-prereg.md)), a diff-only re-check +caught 22 of 24 planted faults but none of 8 real faults that full rounds had +caught on another crew's PRs. + +1. **Count.** `gstack-ship-receipt history --pr ` adds up the rounds the body + records (full passes, scoped passes and fix-checks; a run listed twice counts + once) and prints `PR_REVIEW_HISTORY:`, the flag line `PR_REVIEW_FLAGS: + --prior-rounds --prior-full ` and `PR_REVIEW_ROUTE:`. + `/ship` Step 1 prints all three. A re-check that carried a receipt before + this rule adds no round. +2. **Runs that stop count too.** After each Step 9 pass, `gstack-ship-receipt + stub --pr --run --review-loop ` writes a `status: started` + entry, so a run that stops before its receipt still counts. The run's receipt + write (same `--run`) replaces its stub; `--void` marks a stub that reviewed + nothing. +3. **Route.** A head whose own added and removed lines match the reviewed head's + byte for byte (a base merge, tests, release metadata) keeps its receipt through + carry, as before. Any other new head runs `/ship` Steps 2-16, and + `PR_REVIEW_ROUTE:` names the review it gets: `first` on a PR with no full + round, `final` after one (a fresh full review of this head, the PR's last + before merge), and `read-only` after two. Carry may still print `RECHECK: + advisory … packet=`: one reader may read that packet for advice, but + its verdict never rebinds the receipt, and `carry --recheck` is refused + ([scoped re-check](troubleshooting.md#receipt-carry-recheck)). +4. **Stop rule.** `gstack-review-plan --prior-full ` adds the PR's earlier + full rounds to this run's full passes; fix-checks stay the in-run table's + call, and `--prior-rounds` is printed as `pr_rounds=`. A full pass past two + stops with `PR_ROUND_CAP` and prints the exact `gstack-approvals + round-grant` command; a below-floor fix at the cap finishes with its notes + listed. The stop is the lane's or Captain's call, never an owner ask + ([troubleshooting](troubleshooting.md#pr-round-cap)). +5. **Read-only final review.** A PR that already had two full rounds and whose + own code changed since still gets one full review of its final head. It has + no fix round: below-floor findings ship as notes, and a blocker (open or + fixed) or a gate-class edit stops with `PR_ROUND_CAP` for the lane's Captain + to decide: ship with the note, record a round grant, or park. The count does + not reopen. +6. **Round grant.** `gstack-approvals round-grant --pr --head --kind + extra-round --reason --by ` records one grant for one + head: one round past the cap, with its fix round, instead of the read-only + review. Step 1's `PR_REVIEW_FLAGS:` then adds `--round-grant `, which + raises that run's cap by one round, and the plan refuses a grant for another + head or PR. The plan keeps the grant after the fix round's commits move HEAD + past it. gstack never grants itself a round: `--by gstack` and a grant + from inside an open `/ship` run are refused, and `add` refuses the scope. + The receipt lists grants under `review_round_grants`. + ### Transitions @@ -205,7 +267,7 @@ stop goes to the owner as before. Every other stop still stops. | `scoped-fix-check` | Round 2 stops for a fix whose range since round 2's `PASS_HEAD` is docs class only, or only raises timeout values. `--range-base` must be the commit the newest review-log pass row read. One per branch: the ledger keeps every record, so a later /ship on the branch stops for the owner. | It records the standing grant in the approval record (`by: gstack no-stop default (K1)`) and prints `GRANT:`. `gstack-review-plan --grant` plans the one scoped fix-check. A blocking finding there goes to the owner. | | `test-timeout-fix` | Every changed line is in a test file and only raises a timeout value: the value of a timeout key (`timeout: 5_000`, `setDefaultTimeout(5_000)`, `--timeout=5000`) or bun's and jest's trailing per-test argument, only on the line that opens the test call itself (`test('…', () => {…}, 30_000);`, likewise `it(` and `describe(`). A multi-line test's closing `}, 30_000);` does not qualify and stops for the owner. A line with `expect`, `assert` or a comparison never qualifies. | The gate scan's relaxation finding takes the printed `GATE_DISPOSITION: kept` reason instead of `open`. | | `pregate-flake-rerun` | One rerun of a failed pregate case at the same tree (CREW rule 16). One per branch. | Green counts as flaky. Red again is a real failure. | -| `stamp-only-carry` | A refused carry, where the receipt head merged into the base (base side on conflict) differs from HEAD only in a version stamp: `VERSION`, the `"version"` line of `package.json`, `CHANGELOG.md`, the agents digest or `changelog.d/` fragments. | Take the carry's `RECHECK:` route instead of running Steps 2–16 again. | +| `stamp-only-carry` | A refused carry, where the receipt head merged into the base (base side on conflict) differs from HEAD only in a version stamp: `VERSION`, the `"version"` line of `package.json`, `CHANGELOG.md`, the agents digest or `changelog.d/` fragments. | Go on to Steps 2–16 without waiting for a Captain: the plan reviews HEAD in full, since a re-check no longer carries a receipt ([rounds per pull request](#rounds-per-pull-request)). | | `autoplan-regate` | An edit to the plan file made after the owner's answer, or after the revise that took their changes, while the reviewed plan itself is unchanged. The edit only adds lines, all inside the plan's `## ELI5` section (an added `## ELI5` heading opens one), and no added line holds a number or a word for spend, cost, budget, price, cap, credits, limit, max, arm, model, judge, verdict, threshold, bar, trial, sample, stop rule, paid or eval. A removed or reworded line, or a line added anywhere else, goes to the owner. The carry exports the reviewed plan, so the added explanation is never built. | `gstack-autoplan` carries the owner's words (`reason=no-stop autoplan-regate: …`) and writes `/no-stop.json`. `gstack-no-stop import` adds it to the branch's ledger. | The ledger is one JSON array per branch under the checkout's git directory diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 07dc2ac73..2291a418c 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -2262,20 +2262,19 @@ changes is [`RECEIPT_CARRY_REFUSED`](troubleshooting.md#receipt-carry-refused). A `RECEIPT_CARRY_PRODUCT_CHANGED` on linear history against the reviewed base whose range-diff, plus the diff of the changed product paths, is at most 400 lines and 64 KB, with no binary path and a receipt that -records its review depth, also prints `RECHECK: eligible … packet=`: one reader on that -packet and `carry --recheck ` rebind the receipt instead of a -full second /ship, unless HEAD needs a deeper review depth or another risk -class ([scoped re-check](troubleshooting.md#receipt-carry-recheck), J1). +records its review depth, also prints `RECHECK: advisory … packet=`: one reader may read +that packet for advice, but it never rebinds the receipt, so the head runs /ship and its plan +reviews HEAD in full ([scoped re-check](troubleshooting.md#receipt-carry-recheck), J1; advice +only since GST-2673, [rounds per pull request](review-policy.md#rounds-per-pull-request)). **Changed and context paths together (GST-1561).** When the base also moved context next to reviewed hunks in other paths, the scoped review and J1 compose -into one bounded re-check instead of refusing each other (founderstar#563 hit +into one bounded advisory packet instead of refusing each other (founderstar#563 hit this on every rules-number PR). The one packet holds the range-diff and the changed paths' diff, then the scoped-review sections of the context paths. The 400-line and 64 KB caps count the whole packet, and `range_diff_sha256` binds -all of it. The record also names `range_base`, the commit the reviewed range -starts from (the fork point, or a landed stack parent), and the carry reason -logs the context paths and that `range_base`. A context section with over 200 +all of it. The packet also names `range_base`, the commit the reviewed range +starts from (the fork point, or a landed stack parent). A context section with over 200 of the branch's own +/- lines, or a packet over the caps, prints `RECHECK: not eligible ()` and stays `RECEIPT_CARRY_PRODUCT_CHANGED`. A changed path alone, or context paths alone, keep the routes above, and their output is unchanged. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 50c43ef6a..84064e69a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7127,34 +7127,52 @@ In /ship Step 1, `gstack-ship-preflight` prints the route as `NEXT: carry route (Step 1.4)`. -### Scoped re-check after `RECEIPT_CARRY_PRODUCT_CHANGED` (J1) +### Scoped re-check after `RECEIPT_CARRY_PRODUCT_CHANGED` (J1, advice only) **Meaning.** The product diff changed since the receipt's head, so the receipt -can't carry as it is. When the history is linear, the base is the one the -receipt was reviewed against, and `git range-diff` of the reviewed range -against the current one is at most 400 lines (`RECHECK_RANGE_DIFF_CAP` in -`crew/lib/ship-recheck.ts`), carry also prints `RECHECK: eligible -range_diff_lines=N range_diff_sha256= packet=`: one reader on that -range-diff can clear it instead of a full second /ship. A rebased branch +can't carry. When the history is linear, the base is the one the receipt was +reviewed against, and `git range-diff` of the reviewed range against the +current one is at most 400 lines (`RECHECK_RANGE_DIFF_CAP` in +`crew/lib/ship-recheck.ts`), carry also prints `RECHECK: advisory +range_diff_lines=N range_diff_sha256= packet=`: one reader may read +that range-diff for advice, but it never carries the receipt. A rebased branch (`RECEIPT_CARRY_TREE_MISMATCH`), a retargeted stack, a receipt with no `review_depth`, more than 20 changed product paths, a binary path, a moved base context section with over 200 of the branch's own +/- lines, an empty or unreadable range-diff and a packet over 400 lines or 64 KB print `RECHECK: not eligible ()` instead. When base context also moved next to reviewed hunks in other paths, their -scoped-review sections join the same packet (GST-1561): the caps count the -whole packet, `range_diff_sha256` binds all of it, and the RECHECK line's record -adds `"range_base"`. +scoped-review sections join the same packet (GST-1561), the caps count the +whole packet, and the packet names its `range_base`. -**Fix.** Dispatch one reader on the packet (`.git/gstack/recheck-.md`; -`--dry-run` writes none). When it comes back clean, write -`{"from":"","head":"","range_diff_sha256":"","reader":"","verdict":"clean"}` -(plus `"range_base"` when the line's record names one; a record without it then -refuses) and rerun `gstack-ship-receipt carry ... --recheck `. The carry -reason records the reader and the range-diff size, and with moved context the -context paths and `range_base`. Carry still refuses when -HEAD needs a deeper review depth or a different risk class than the receipt -recorded; that, or a blocking finding, means /ship on the new head. In /ship -Step 1, `gstack-ship-preflight` prints this as `NEXT: carry route (Step 1.4, J1)`. +**Fix.** Run /ship on HEAD: its review plan gives the PR's final head a full +review ([rounds per pull request](review-policy.md#rounds-per-pull-request)). +The packet (`.git/gstack/recheck-.md`; `--dry-run` writes none) is +advice for that run, never a substitute: in the replay behind this rule a +diff-only re-check caught none of 8 real faults that full rounds had caught +(GST-2673). `carry --recheck` is refused. In /ship Step 1, +`gstack-ship-preflight` sends this head to Steps 2-16. + + +### `PR_ROUND_CAP` + +**Meaning.** `gstack-review-plan --prior-full ` found that this pull +request already had its two full review rounds (R51), counted across every head and +`/ship` run from the PR body's receipt history, so it planned no new round with a fix +round. A PR at the cap whose own code changed gets one read-only full review of its +final head; this stop then means that review found a blocker or a gate-class edit. +`/ship` Step 1 prints the count as `PR_REVIEW_HISTORY:` and passes it on from +`PR_REVIEW_FLAGS:`. A fix below the blocking floor finishes with its notes +listed instead of stopping. + +**Fix.** The lane's Captain decides. Ship with the open notes listed, or, when a finding above the floor is +open in this PR's own change or the design changed, have the lane or Captain +record one round with the command the `NEXT:` line prints, +`gstack-approvals round-grant --pr --head --kind extra-round --reason + --by `, then rerun `gstack-ship-preflight`: its +`PR_REVIEW_FLAGS:` line adds `--round-grant ` for the plan. +The grant names one head; a new push needs a new grant. This is not an owner +ask, and gstack cannot grant itself one (`--by gstack` is refused) +([review-policy.md](review-policy.md#rounds-per-pull-request)). ### `RECEIPT_PROSE_MISMATCH` diff --git a/lib/factory-scorecard.ts b/lib/factory-scorecard.ts index 80514f523..689e60870 100644 --- a/lib/factory-scorecard.ts +++ b/lib/factory-scorecard.ts @@ -36,6 +36,8 @@ import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; +import { prReviewHistory } from './pr-review-history'; +import { extractReceipt } from './ship-receipt'; import { GH_CLIENT, createdFilter, downloadRunArtifacts, filesUnder, historyFetcher, listWorkflowRuns, readFlakeLedgerDir, reuseChecker, unavailableReason, type GhClient, @@ -181,7 +183,7 @@ export function readMergedPrs(source: ScorecardSource, o: ScorecardOptions, w: S const author = String(pr.user?.login ?? ''); const association = String(pr.author_association ?? 'NONE'); const comments = readComments(source, o.repo, Number(pr.number), { readyMarker: o.readyMarker, passMarker: o.passMarker, mergedAt }); - const bodyPasses = passCount(String(pr.body ?? ''), o.passMarker); + const bodyPasses = receiptRounds(String(pr.body ?? '')) ?? passCount(String(pr.body ?? ''), o.passMarker); out.push({ number: Number(pr.number), author, association, title: String(pr.title ?? ''), crew: crewLogins ? crewLogins.has(author.toLowerCase()) : CREW_ASSOCIATIONS.has(association), createdAt: String(pr.created_at), mergedAt, readyAt: comments.readyAt, commentCostUsd: comments.costUsd, @@ -193,6 +195,13 @@ export function readMergedPrs(source: ScorecardSource, o: ScorecardOptions, w: S return out.sort((a, b) => a.mergedAt.localeCompare(b.mergedAt)); } +/** R51 rounds summed across a PR body's receipt and its runs block (GST-2673), null when no receipt records a review run. */ +export function receiptRounds(body: string): number | null { + if (!extractReceipt(body).found) return null; + const h = prReviewHistory(body); + return h.runs + h.stubs > 0 ? h.rounds : null; +} + /** The largest pass count the marker captures in a text, null when it never matches. */ export function passCount(text: string, marker: RegExp): number | null { let max: number | null = null; diff --git a/lib/headless-artifacts.ts b/lib/headless-artifacts.ts index 8436de110..e9fab0982 100644 --- a/lib/headless-artifacts.ts +++ b/lib/headless-artifacts.ts @@ -117,7 +117,7 @@ export interface ShipReceipt { // Related open PRs by other authors (Lane D): `supersedes` / `credit` only on the owner's confirmation. issues?: { fixes: number[]; refs: number[]; flakes: Array<{ issue: number; run: string }>; related?: Array<{ pr: number; repo?: string; author: string; closes: number[]; supersedes?: boolean; credit?: boolean }> }; /** Harness lane E: the review loop's counters (gstack-review-scope summary) and the carry record when the receipt followed a head whose product diff was unchanged (gstack-ship-receipt carry). */ - review_loop?: { passes: number; blocking_found: number; deferred: number; noted?: number; fixed?: number; scope?: string; fix_checks?: number; rounds?: number; dispatches?: Record; est_input_tokens?: number; unrecorded?: number; ledgers_read?: number; unbound?: number }; + review_loop?: { passes: number; blocking_found: number; deferred: number; noted?: number; fixed?: number; scope?: string; fix_checks?: number; rounds?: number; scoped?: number; dispatches?: Record; est_input_tokens?: number; unrecorded?: number; ledgers_read?: number; unbound?: number }; carry?: { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[]; trees?: string[]; ancestry?: 'linear' | 'rewritten' }; /** The reviewed head's tree and its product patch-id against the base (gstack-ship-receipt write; carry rebinds both): what a carry across rewritten history compares. */ head_tree?: string; product_patch_id?: string; @@ -126,6 +126,8 @@ export interface ShipReceipt { review_depth?: { depth: 'platform' | 'light' | 'standard' | 'full'; class: 'docs' | 'tests' | 'code' | 'gate'; runtime_lines: number; rules: string; base: string; registry: string | null; gate_scan: { tagged: number | null; head: string }; reasons: string[]; risk?: string[]; mode?: 'lean' | 'panel' | 'platform'; platform_review?: { id: string; head: string; reviewer: string }; declared?: string[]; detected?: string[] }; /** The owner's acceptance of a stop after a fix-check edit under frozen scope (#3559); the PR body repeats it word for word. */ review_loop_exception?: { accepted_by: string; date: string; via: string; reason: string; fix_check?: { head: string; findings: number; files?: string[] }; second_pass?: { head: string; deferred: string[] } }; + /** Review round grants the lane or its Captain recorded for this PR (gstack-approvals round-grant, lib/review-round-grant.ts; GST-2673): never the owner's, so never in review_loop_exception. */ + review_round_grants?: Array<{ kind: 'extra-round'; head: string; pr: number; by: string; reason: string; at: string; approval: string }>; /** The owner's rulings that a finding ships as a disclosed note (gstack-approvals rule, lib/ruled-notes.ts); the PR body lists each one word for word (GST-1537). */ ruled_notes?: Array<{ finding: string; head: string; by: string; reason: string; at: string; approval: string }>; /** The owner's dispositions of gate findings (gstack-approvals gate, lib/gate-dispositions.ts); the PR body lists each one word for word (GST-2491). */ @@ -269,7 +271,7 @@ export const ARTIFACT_SCHEMAS = { thread: str, tree: { enum: ['same-modulo-stamps', 'changed', 'not-compared'] }, gate_reuse: str, policy: str, queue_mode: str, preregistration: str, history: str, pregate: { ...str, description: 'pass|warn|requires-remote cleared … @ from pregate.json, current for this head' }, requires_remote: strList, approval: { type: 'object', description: 'approval classes: { source, status: checked|unavailable, classes: [{ class, scope, effects, citation: verified|unverified, approved_by, date, via, binding, evidence }], report_only }' }, - review_loop: { type: 'object', required: ['passes', 'blocking_found', 'deferred'], properties: { passes: { type: 'integer', minimum: 0 }, blocking_found: { type: 'integer', minimum: 0 }, deferred: { type: 'integer', minimum: 0 }, noted: { type: 'integer', minimum: 0 }, fixed: { type: 'integer', minimum: 0 }, scope: str, fix_checks: { type: 'integer', minimum: 0 }, rounds: { type: 'integer', minimum: 0 }, dispatches: { type: 'object', description: 'reviewer dispatches by role' }, est_input_tokens: { type: 'integer', minimum: 0 }, unrecorded: { type: 'integer', minimum: 0 }, ledgers_read: { type: 'integer', minimum: 0 }, unbound: { type: 'integer', minimum: 0, description: 'rows, ledger ids or fix trailers gstack-review-scope summary could not bind (GST-1168)' } } }, + review_loop: { type: 'object', required: ['passes', 'blocking_found', 'deferred'], properties: { passes: { type: 'integer', minimum: 0 }, blocking_found: { type: 'integer', minimum: 0 }, deferred: { type: 'integer', minimum: 0 }, noted: { type: 'integer', minimum: 0 }, fixed: { type: 'integer', minimum: 0 }, scope: str, fix_checks: { type: 'integer', minimum: 0 }, rounds: { type: 'integer', minimum: 0 }, scoped: { type: 'integer', minimum: 0, description: 'passes that were scoped repeats (GST-2673): a round, not a full round' }, dispatches: { type: 'object', description: 'reviewer dispatches by role' }, est_input_tokens: { type: 'integer', minimum: 0 }, unrecorded: { type: 'integer', minimum: 0 }, ledgers_read: { type: 'integer', minimum: 0 }, unbound: { type: 'integer', minimum: 0, description: 'rows, ledger ids or fix trailers gstack-review-scope summary could not bind (GST-1168)' } } }, carry: { type: 'object', required: ['from', 'reason', 'product_patch_id'], properties: { from: str, reason: str, product_patch_id: str, changed_paths: strList, merge_commits: { type: 'integer', minimum: 0 }, range_diff: str, covers: strList, reruns: strList, trees: strList, ancestry: { enum: ['linear', 'rewritten'] } } }, head_tree: str, product_patch_id: str, gstack_version: str, base_red: { type: 'object', required: ['cases', 'files', 'base', 'lane', 'expires_at'], properties: { cases: strList, files: strList, base: str, lane: str, expires_at: str } }, @@ -278,6 +280,7 @@ export const ARTIFACT_SCHEMAS = { review_targeted: { type: 'object', required: ['classes', 'rules', 'brief_sha', 'product_patch_id', 'status', 'findings', 'raised_by'], properties: { classes: { type: 'array', items: { enum: ['money', 'gate', 'auth', 'secret'] } }, rules: str, brief_sha: str, product_patch_id: str, status: { enum: ['done', 'failed', 'not-run'] }, findings: { type: 'integer', minimum: 0 }, raised_by: str } }, review_exclude: { type: 'object', required: ['source', 'patterns', 'applied', 'excluded', 'excluded_bytes', 'kept', 'gate_tagged', 'patterns_sha256', 'list_sha256', 'digest'], properties: { source: str, patterns: strList, applied: strList, excluded: { type: 'integer', minimum: 0 }, excluded_bytes: { type: 'integer', minimum: 0 }, kept: { type: 'integer', minimum: 0 }, gate_tagged: strList, patterns_sha256: str, list_sha256: str, digest: str } }, review_loop_exception: { type: 'object', required: ['accepted_by', 'date', 'via', 'reason'], properties: { accepted_by: str, date: str, via: str, reason: str, fix_check: { type: 'object', required: ['head', 'findings'], properties: { head: str, findings: { type: 'integer', minimum: 0 }, files: strList } }, second_pass: { type: 'object', required: ['head', 'deferred'], properties: { head: str, deferred: strList } } } }, + review_round_grants: { type: 'array', items: { type: 'object', required: ['kind', 'head', 'pr', 'by', 'reason', 'at', 'approval'], properties: { kind: { enum: ['extra-round'] }, head: str, pr: { type: 'integer', minimum: 1 }, by: str, reason: str, at: str, approval: str } } }, ruled_notes: { type: 'array', items: { type: 'object', required: ['finding', 'head', 'by', 'reason', 'at', 'approval'], properties: { finding: str, head: str, by: str, reason: str, at: str, approval: str } } }, gate_dispositions: { type: 'array', items: { type: 'object', required: ['finding', 'gate_id', 'head', 'by', 'reason', 'words', 'at', 'approval'], properties: { finding: str, gate_id: str, head: str, by: str, reason: str, words: str, at: str, approval: str } } }, mechanical: strList, diff --git a/lib/plan-record.ts b/lib/plan-record.ts index 279dc9865..db95a7107 100644 --- a/lib/plan-record.ts +++ b/lib/plan-record.ts @@ -42,7 +42,7 @@ export interface PlanRecord { line: string; state: 'approved' | 'exempt'; ref?: export interface PlanFailure { code: ResultCodeName; message: string; fix: string } export type PlanResolution = { ok: true; record: PlanRecord; summary: string } | { ok: false; failure: PlanFailure }; -const NOT_PLAN_ROW = /\b(ruled_note|gate_disposition|review_loop_grant|review_loop_exception|test_lane_exception)\b/; +const NOT_PLAN_ROW = /\b(ruled_note|gate_disposition|review_loop_grant|review_loop_exception|review_round_grant|test_lane_exception)\b/; const ROW_ID = /^a-[0-9a-f]{12}$/; const RECORD_ID = /^r-[0-9a-f]{12}$/; const LOCAL_SOURCE = 'state-root config'; diff --git a/lib/pr-review-history.ts b/lib/pr-review-history.ts new file mode 100644 index 000000000..9fc080992 --- /dev/null +++ b/lib/pr-review-history.ts @@ -0,0 +1,108 @@ +/** + * pr-review-history — R51 per pull request (GST-2673, docs/review-policy.md#rounds-per-pull-request). gstack caps a + * PR at two review rounds across every head, /ship run and reader, but each /ship run starts its own count, so a PR + * pushed N times could get 2N rounds. The PR body already keeps every run's review loop (the receipt plus the + * gstack-receipt-runs block, lib/ship-receipt.ts), on GitHub, where every host reads it the same way: this module adds + * it up, records runs that stop before their receipt (a started stub), and says what review the next head gets. The + * PR's last review before merge is a full review of its final head: a diff-only re-check caught 0 of 8 real faults + * that full rounds had caught (GST-2673), so a re-check is advice only and never carries a receipt. + */ +import type { ShipReceipt } from './headless-artifacts'; +import { withAgentNotes, splitAgentNotes } from './agent-notes'; +import { extractReceipt, receiptRun, receiptRuns, RECEIPT_RUNS_KEPT, RUNS_FENCE, RUNS_RE, type ReceiptRun } from './ship-receipt'; +import { FULL_PASS_CAP } from './review-depth'; + +export interface PrReviewHistory { + /** /ship runs that reviewed (stubs and carries excluded). */ + runs: number; + /** R51 rounds: full and scoped passes plus fix-checks, every run and started stub. */ + rounds: number; + full: number; + scoped: number; + fix_checks: number; + /** Scoped re-checks that carried the receipt to a new head before GST-2673 made them advice only. */ + rechecks: number; + /** Runs that started and wrote no receipt yet. */ + stubs: number; + heads: number; + first_full: string | null; + last_full: string | null; + source: 'pr-body'; +} + +const roundsOf = (l: ReceiptRun['review_loop']) => (l ? (l.rounds ?? (l.passes ?? 0) + (l.fix_checks ?? 0)) : 0); + +/** Every entry the body records, oldest first: the runs block, then the current receipt. */ +function entries(body: string): ReceiptRun[] { + const current = extractReceipt(body).receipt; + return [...receiptRuns(body), ...(current && typeof current.head === 'string' ? [receiptRun(current)] : [])]; +} + +export function prReviewHistory(body: string): PrReviewHistory { + const all = entries(body); + const reviewed = new Map(); + const ordered: Array = []; + all.forEach((e, i) => { + if (e.status || e.carry_kind || e.carried_from) { ordered.push(e); return; } + const key = e.run ? `run:${e.run}` : `#${i}`; + if (!reviewed.has(key)) ordered.push(key); + reviewed.set(key, e); + }); + const h: PrReviewHistory = { runs: 0, rounds: 0, full: 0, scoped: 0, fix_checks: 0, rechecks: 0, stubs: 0, heads: new Set(all.map(e => e.head)).size, first_full: null, last_full: null, source: 'pr-body' }; + for (const item of ordered) { + const e = typeof item === 'string' ? reviewed.get(item)! : item; + if (e.status === 'voided') continue; + if (e.carry_kind === 'recheck') { h.rechecks++; continue; } + if (e.carry_kind || e.carried_from) continue; + const l = e.review_loop; + const scoped = l?.scoped ?? 0, full = Math.max(0, (l?.passes ?? 0) - scoped); + h.rounds += roundsOf(l); h.scoped += scoped; h.full += full; h.fix_checks += l?.fix_checks ?? 0; + if (e.status === 'started') h.stubs++; else h.runs++; + if (full > 0) { h.first_full ??= e.head; h.last_full = e.head; } + } + return h; +} + +/** + * Put one entry in the runs block: a stub replaces the same run's earlier stub, and any other entry is appended. + * The receipt, when there is one, is unchanged; a body without one gets the block in its Agent notes section. + */ +export function placeRunEntry(body: string, entry: ReceiptRun): string { + const runs = receiptRuns(body).filter(r => !(entry.status && r.status && r.run === entry.run)); + const kept = [...runs, JSON.parse(JSON.stringify(entry)) as ReceiptRun].slice(-RECEIPT_RUNS_KEPT); + const block = '```' + RUNS_FENCE + '\n' + kept.map(r => JSON.stringify(r)).join('\n') + '\n```\n'; + if (RUNS_RE.test(body)) return body.replace(RUNS_RE, () => block); + if (extractReceipt(body).found) { + const end = /```gstack-ship-receipt[ \t]*\r?\n[\s\S]*?\r?\n```[ \t]*(?:\r?\n|$)/.exec(body)!; + const at = end.index + end[0].length; + return body.slice(0, at) + '\n' + block + body.slice(at); + } + const notes = (splitAgentNotes(body).notes ?? '').trim(); + return withAgentNotes(body.replace(/^\s+/, ''), (notes ? notes + '\n\n' : '') + block); +} + +/** A started (or voided) stub for a /ship run that has not written its receipt yet. */ +export const runStub = (o: { head: string; run: string; status: 'started' | 'voided'; loop: NonNullable }): ReceiptRun => + ({ head: o.head, run: o.run, status: o.status, review_loop: o.loop }); + +export type Route = { route: 'first' | 'final' | 'read-only'; reason: string }; + +/** + * What review a head of the PR gets when carry can't keep its receipt (the PR's own lines changed; a head that only + * merges in the base keeps it). Before any full round: the first review, as today. Below the cap: a fresh full review + * of this head, the PR's last before merge. At the cap: one read-only full review of the final head, with no fix round, + * whose blocker goes to the lane's Captain as a decision; an extra-round grant at this head buys a fix round instead. + * A scoped re-check is advice only and never stands in (GST-2673). + */ +export function reviewRoute(h: Pick, o: { grant?: string } = {}): Route { + if (!h.full) return { route: 'first', reason: 'no full review round on this PR yet' }; + if (h.full < FULL_PASS_CAP) return { route: 'final', reason: `the PR had ${h.full} full review round${h.full === 1 ? '' : 's'}; this head gets a fresh full review, the PR's round ${h.full + 1} of ${FULL_PASS_CAP} and its last before merge (R51)` }; + if (o.grant && h.full === FULL_PASS_CAP) return { route: 'final', reason: `the PR had ${h.full} full review rounds; round grant ${o.grant} buys one more at this head, with its fix round` }; + return { route: 'read-only', reason: `the PR had ${h.full} full review rounds; this head gets one read-only full review: no fix round, a blocker goes to the lane's Captain as a decision, and the count does not reopen (R51)` }; +} + +const s12 = (s: string | null) => (s ? s.slice(0, 12) : 'none'); + +export function historyLine(pr: string, h: PrReviewHistory): string { + return `PR_REVIEW_HISTORY: pr=#${pr} rounds=${h.rounds} cap=${FULL_PASS_CAP} full=${h.full} scoped=${h.scoped} fix_checks=${h.fix_checks} rechecks=${h.rechecks} runs=${h.runs} stubs=${h.stubs} heads_reviewed=${h.heads} first_full=${s12(h.first_full)} last_full=${s12(h.last_full)} source=${h.source}`; +} diff --git a/lib/redact-patterns.ts b/lib/redact-patterns.ts index 10536ed74..e951c24bf 100644 --- a/lib/redact-patterns.ts +++ b/lib/redact-patterns.ts @@ -420,13 +420,14 @@ export function isCiRunIdentifier(span: string, match: RegExpExecArray): boolean /** * The owner's grant of one scoped fix-check is recorded as `review_loop_grant `, and an accepted stop as - * `review_loop_exception ` (docs/review-policy.md). About one 12-character sha in 300 is all digits + * `review_loop_exception ` (docs/review-policy.md), and a lane's review round grant as `review_round_grant ` + * or `review_round_grant at ` (GST-2673). About one 12-character sha in 300 is all digits * (`367120488513`), and pii.phone.e164 read it as a phone number, so gstack-approvals refused the owner's grant * (APPROVAL_RECORD_SECRET; Free Tests 41667825418, 41766865679). Only the position decides: a digits-only span right * after one of those two tokens and a space, `=` or `:`. The same digits anywhere else, or a number with a `+`, * spaces or dashes after the token, still report. */ -const REVIEW_LOOP_SHA_BEFORE = /\breview_loop_(?:grant|exception)(?:[ \t]+|[ \t]*[:=][ \t]*)$/; +const REVIEW_LOOP_SHA_BEFORE = /\breview_(?:loop_(?:grant|exception)|round_grant(?:[ \t]+extra-round[ \t]+at)?)(?:[ \t]+|[ \t]*[:=][ \t]*)$/; function isReviewLoopSha(span: string, match: RegExpExecArray): boolean { if (!/^\d+$/.test(span)) return false; const input = match.input ?? ""; diff --git a/lib/review-depth.ts b/lib/review-depth.ts index 352beca11..dd2c2ca29 100644 --- a/lib/review-depth.ts +++ b/lib/review-depth.ts @@ -388,6 +388,12 @@ export interface History { postReview?: boolean; /** In the loop, the CLI bound `granted` to the last fix-check's own stop head, its commit (--range-base): a new grant, never the previous link's. */ chained?: boolean; + /** R51 rounds earlier /ship runs on this PR already spent, fix-checks and scoped passes included (--prior-rounds; GST-2673): printed as pr_rounds=. */ + priorRounds?: number; + /** The full review rounds among them (--prior-full): the PR cap compares these plus this run's full passes with FULL_PASS_CAP, so a run's own fix rounds stay as the in-run table plans them. */ + priorFull?: number; + /** The lane's or Captain's recorded round grant at this head (--round-grant): one more round for the PR, never the owner's. */ + roundGrant?: string; } export interface NextStep { step: Step; reason: string } @@ -407,7 +413,7 @@ export interface NextStep { step: Step; reason: string } * loop, a grant the CLI bound to the last fix-check's own stop head (`chained`) adds one more the same way (GST-1681). */ export function nextStep(h: History, depth?: Depth): NextStep { - const n = h.lean ? leanStep(h, depth) : loopStep(h, depth); + const n = prCapped(h, h.lean ? leanStep(h, depth) : loopStep(h, depth)); if (n.step !== 'stop') return n; if (h.gate && !h.adversarialRan) return { step: 'voices', reason: `gate class: Step 11's ${h.lean ? 'one reader' : 'voices (adversarial, outside, targeted)'} run${h.lean ? 's' : ''} before the owner's exit, then ask again with --adversarial-ran (${n.reason})` }; const afterFixCheck = h.last === 'fix-check' && h.fullPasses === FULL_PASS_CAP - 1 && h.fixChecks === 1; @@ -417,6 +423,29 @@ export function nextStep(h: History, depth?: Depth): NextStep { return n; } +/** + * R51 per pull request (GST-2673, docs/review-policy.md#rounds-per-pull-request): the rounds earlier /ship runs on this + * PR spent count against FULL_PASS_CAP with this run's, and a recorded round grant at this head adds one. At the cap a + * below-floor fix ships as notes and anything else stops with PR_ROUND_CAP for the lane or its Captain, never the owner. + * A PR already at the cap gets one read-only full review of this head: no fix round, the count does not reopen, and a + * blocker stops with PR_ROUND_CAP as the lane's Captain's decision. + */ +function prCapped(h: History, n: NextStep): NextStep { + const prior = h.priorFull ?? 0; + const cap = FULL_PASS_CAP + (h.roundGrant ? 1 : 0); + if (prior >= cap) { + if (h.last === 'none') return n.step === 'full' || n.step === 'scoped' ? { step: 'full', reason: `read-only final review (R51): this PR already had ${prior} full review rounds on earlier heads, so this head gets one full review with no fix round; a blocker goes to the lane's Captain as a decision and the count does not reopen` } : n; + if (n.step === 'done') return n; + if (!h.fixedBlocking && !h.blockingOpen && !h.touchedGate && n.step !== 'stop') return { step: 'done', reason: `read-only final review done (R51): its below-floor findings ship as notes in the PR body and receipt, with no fix round` }; + return { step: 'stop', reason: `PR_ROUND_CAP: the read-only final review of a PR that already had ${prior} full review rounds found a blocker; the lane's Captain decides (ship with the note, a round grant, or park), not an owner ask` }; + } + if (!prior || (n.step !== 'full' && n.step !== 'scoped')) return n; + const used = prior + h.fullPasses; + if (used < cap) return { ...n, reason: `${n.reason}; this PR already had ${prior} full review round${prior === 1 ? '' : 's'} on earlier heads, so this is its full round ${used + 1} of ${cap}${used + 1 === cap ? ', the last' : ''}` }; + if (h.last !== 'none' && !h.fixedBlocking && !h.blockingOpen && !h.touchedGate) return { step: 'done', reason: `PR round cap ${cap} reached (${prior} on earlier heads): the below-floor fixes ship as notes in the PR body and receipt` }; + return { step: 'stop', reason: `PR_ROUND_CAP: this PR already had ${used} full review round${used === 1 ? '' : 's'} across its heads and /ship runs${h.roundGrant ? ` (round grant ${h.roundGrant} included)` : ''}; another needs a reason the lane or its Captain records with gstack-approvals round-grant, not an owner ask` }; +} + /** * R65's lean table (GSTA-258): pass 1 is the one reviewer; any fix on a risk-class diff, and a fixed blocker or a gate-class * edit on any diff, earns one scoped fix-check (round 2, the cap); below-floor fixes on a light diff ship as notes. After the @@ -713,8 +742,8 @@ function leanPlan(i: PlanInput, c: ClassResult, depth: DepthResult, next: NextSt return plan(next, 'lean'); } -export function reviewPlanLine(p: ReviewPlan, pass: number): string { - return `REVIEW_PLAN: class=${p.class} pass=${pass} next=${p.next.step} dispatches=${p.dispatches.length} numbers=${p.numbers.publishes ? `yes(${p.numbers.claims})` : 'no'} fingerprint=${p.numbers.fingerprint} reason=${JSON.stringify(p.next.reason)}`; +export function reviewPlanLine(p: ReviewPlan, pass: number, priorRounds = 0): string { + return `REVIEW_PLAN: class=${p.class} pass=${pass}${priorRounds ? ` pr_rounds=${priorRounds}` : ''} next=${p.next.step} dispatches=${p.dispatches.length} numbers=${p.numbers.publishes ? `yes(${p.numbers.claims})` : 'no'} fingerprint=${p.numbers.fingerprint} reason=${JSON.stringify(p.next.reason)}`; } export function reviewDepthLine(p: ReviewPlan): string { diff --git a/lib/review-round-grant.ts b/lib/review-round-grant.ts new file mode 100644 index 000000000..12f36710e --- /dev/null +++ b/lib/review-round-grant.ts @@ -0,0 +1,43 @@ +/** + * Review round grants (GST-2673, docs/review-policy.md#rounds-per-pull-request): a reason the lane or its Captain + * records when a PR needs a review round its R51 count would not plan. kind=extra-round: one round, with its fix + * round, past the PR's cap of two. It binds one head of one PR and is spent by the round it buys. It is recorded with gstack-approvals round-grant, + * is never an owner ask and never a plan approval (lib/plan-record.ts NOT_PLAN_ROW). --by is recorded, not enforced. + */ +import { locate, readRecord, type ApprovalRow, type Env } from './approval-record'; +import { GSTACK_ACTOR } from './ruled-notes'; + +export const ROUND_GRANT_KINDS = ['extra-round'] as const; +export type RoundGrantKind = (typeof ROUND_GRANT_KINDS)[number]; +export interface ReviewRoundGrant { kind: RoundGrantKind; head: string; pr: number; by: string; reason: string; at: string; approval: string } + +const SCOPE = /^review_round_grant ([0-9a-f]{40}) pr=([1-9]\d*) kind=(extra-round)$/; +const ASK = /^review_round_grant (extra-round) at ([0-9a-f]{40}) for pr ([1-9]\d*): (\S(?:.*\S)?)$/; +export const REVIEW_ROUND_GRANT_SCOPE = /^\s*review_round_grant\b/; + +export const reviewRoundGrantRow = (head: string, pr: number, kind: RoundGrantKind, reason: string) => + ({ scope: `review_round_grant ${head} pr=${pr} kind=${kind}`, ask: `review_round_grant ${kind} at ${head} for pr ${pr}: ${reason}` }); + +export function reviewRoundGrants(rows: readonly ApprovalRow[]): ReviewRoundGrant[] { + const out: ReviewRoundGrant[] = []; + for (const r of rows) { + const s = SCOPE.exec(r.scope), a = ASK.exec(r.ask); + if (r.outcome !== 'approved' || !s || !a || GSTACK_ACTOR.test(r.by)) continue; + if (a[1] !== s[3] || a[2] !== s[1] || a[3] !== s[2]) continue; + out.push({ kind: s[3] as RoundGrantKind, head: s[1]!, pr: Number(s[2]), by: r.by, reason: a[4]!, at: r.recorded_at, approval: r.id }); + } + return out; +} + +export function readReviewRoundGrants(cwd: string, env: Env = process.env): ReviewRoundGrant[] { + const loc = locate({ cwd, env }); + return 'code' in loc ? [] : reviewRoundGrants(readRecord(loc).rows); +} + +/** The newest grant for this PR at exactly this head. */ +export const grantAt = (grants: readonly ReviewRoundGrant[], pr: number, head: string) => + [...grants].reverse().find(g => g.pr === pr && g.head === head.toLowerCase()); + +/** The text after "Review round grant: " in the PR body. */ +export const reviewRoundGrantText = (g: ReviewRoundGrant) => + `${g.kind} at ${g.head.slice(0, 12)} for PR #${g.pr} recorded by ${g.by} at ${g.at}: ${g.reason} (approval ${g.approval})`; diff --git a/lib/review-scope.ts b/lib/review-scope.ts index 45182e86e..9fa10e476 100644 --- a/lib/review-scope.ts +++ b/lib/review-scope.ts @@ -281,6 +281,8 @@ export interface ReviewLoopSummary { passes: number; blocking_found: number; deferred: number; noted: number; fixed: number; scope: ReviewScopePolicy | 'unknown'; /** One-reviewer re-checks of a fix (docs/review-policy.md#transitions); never passes. */ fix_checks?: number; + /** Passes that were scoped repeats (`"scope":"scoped"` rows): rounds, not full rounds (GST-2673). */ + scoped?: number; /** Review rounds (R51): passes plus fix-checks; the loop caps them at 2. */ rounds?: number; /** Reviewer dispatches of this invocation by role (specialist, red-team, adversarial-native, outside-voice, fix-check, targeted). */ @@ -488,6 +490,8 @@ export function summarizeReviewLoop(rows: readonly Record[], since: const fixChecks = Math.max(rowFixChecks, fixCheckStarts.length); if (fixChecks) out.fix_checks = fixChecks; out.rounds = passes.length + fixChecks; + const scopedPasses = passes.filter(r => r.scope === 'scoped').length; + if (scopedPasses) out.scoped = scopedPasses; const byRole: Record = {}; let bytes = 0; let measured = false; for (const row of rows.filter(r => inRun(r) && DISPATCH_SKILLS.includes(r.skill))) { diff --git a/lib/ship-preflight.ts b/lib/ship-preflight.ts index 5f99780ff..d02666477 100644 --- a/lib/ship-preflight.ts +++ b/lib/ship-preflight.ts @@ -96,14 +96,16 @@ function integrate(cwd: string, base: string, run: string | undefined, r: Report const carry = bin(cwd, 'gstack-ship-receipt', ['carry', '--pr', n, '--base', base, '--dry-run'], 120_000); const line = (carry.stdout.match(/^CARRY: .*$/m) ?? [`CARRY: check failed (${firstLine(carry.stderr)})`])[0]; r.add(`PR: #${n}`).add(line); + // R51 per pull request (GST-2673): the rounds earlier heads spent, which Step 9 passes to every plan, and the review this + // head gets: a product change runs Steps 2-16, whose plan is the merge head's full review; a re-check never carries. + const hist = bin(cwd, 'gstack-ship-receipt', ['history', '--pr', n], 120_000); + const histLines = hist.stdout.split('\n').filter(l => /^PR_REVIEW_(HISTORY|FLAGS|ROUTE): /.test(l)); + histLines.forEach(l => r.add(l)); + if (hist.status !== 0 || !histLines.some(l => l.startsWith('PR_REVIEW_FLAGS: '))) r.add('PR_REVIEW_FLAGS: --prior-rounds 0').add(`PR_REVIEW_ROUTE: first (history unavailable: ${firstLine(hist.stderr) || `gstack-ship-receipt history exit ${hist.status}`}; the plan counts this run's rounds only)`); if (line.startsWith('CARRY: would carry')) { r.next(`carry route (Step 1.4): fix what the base merge broke (CHANGELOG, size caps), commit, gstack-ship-release push --branch ${branch} --early, gstack-ci-carry wait --base ${base} (CI_CARRY: none is not a stop), gstack-pregate --allow-repo-commands, then gstack-ship-receipt carry --pr ${n} --base ${base} --pregate .gstack/tmp/pregate.json`); return false; } - if (line === 'CARRY: refused (RECEIPT_CARRY_PRODUCT_CHANGED)' && /^RECHECK: eligible /m.test(carry.stderr ?? '')) { - r.next(`carry route (Step 1.4, J1): the product changed since the receipt within the scoped re-check cap: gstack-ship-receipt carry --pr ${n} --base ${base} writes the re-check packet; one reader reads it; gstack-pregate --allow-repo-commands, then carry again with --recheck --pregate .gstack/tmp/pregate.json; a blocking finding runs Steps 2-16`); - return false; - } if (line === 'CARRY: refused (RECEIPT_CARRY_SCOPED_REVIEW)') { r.next(`carry route (Step 1.4): the base edited context next to reviewed hunks: fix what the base merge broke (CHANGELOG, size caps), commit and push; then gstack-ship-receipt carry --pr ${n} --base ${base} writes the packet for that head; one fix-check reviewer reads it; gstack-pregate --allow-repo-commands, then carry again with --scoped-review --pregate .gstack/tmp/pregate.json; a blocking finding runs Steps 2-16`); return false; diff --git a/lib/ship-receipt.ts b/lib/ship-receipt.ts index 67339df38..34cdfe13d 100644 --- a/lib/ship-receipt.ts +++ b/lib/ship-receipt.ts @@ -24,7 +24,7 @@ const KEY_ORDER: Array = [ 'schema_version', 'pr', 'head', 'version', 'base', 'gated_tree', 'predecessor', 'tree', 'gate_reuse', 'gate', 'ci', 'ci_carried', 'spend_usd', 'session_kind', 'artifacts_consumed', 'run', 'thread', 'policy', 'queue_mode', 'preregistration', 'history', 'head_tree', 'product_patch_id', 'gstack_version', 'review_depth', 'pregate', 'requires_remote', 'issues', 'approval', 'docs', 'review_loop', - 'review_loop_exception', 'ruled_notes', 'gate_dispositions', 'mechanical', 'review_targeted', 'design', 'review_exclude', 'carry', 'base_red', 'flaky_exception', 'no_stop', + 'review_loop_exception', 'review_round_grants', 'ruled_notes', 'gate_dispositions', 'mechanical', 'review_targeted', 'design', 'review_exclude', 'carry', 'base_red', 'flaky_exception', 'no_stop', ]; /** Keys in the fixed order so identifiers lead; undefined values are dropped. */ @@ -125,15 +125,22 @@ export function bindReceipt(body: string, pr: string | undefined, accepted: read */ export const RUNS_FENCE = 'gstack-receipt-runs'; export const RECEIPT_RUNS_KEPT = 30; -const RUNS_RE = /```gstack-receipt-runs[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*(?:\r?\n|$)/; -export type ReceiptRun = Pick & { depth?: string; carried_from?: string }; +export const RUNS_RE = /```gstack-receipt-runs[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*(?:\r?\n|$)/; +/** + * carry_kind (GST-2673): `recheck` when the latest carry hop was a scoped re-check (old receipts only: a re-check no longer + * carries), `carry` for any other hop. status: a /ship run that + * started and wrote no receipt yet (`started`, its counters so far) or ended on an infrastructure failure (`voided`). + */ +export type ReceiptRun = Pick & { depth?: string; carried_from?: string; carry_kind?: 'carry' | 'recheck'; status?: 'started' | 'voided' }; export function receiptRuns(body: string): ReceiptRun[] { const m = RUNS_RE.exec(receiptSource(body)); return m ? m[1]!.split('\n').flatMap(l => { try { const o = JSON.parse(l); return o && typeof o.head === 'string' ? [o as ReceiptRun] : []; } catch { return []; } }) : []; } export function receiptRun(r: ShipReceipt): ReceiptRun { const { head, version, gstack_version, run, review_loop, review_loop_exception } = r; - return JSON.parse(JSON.stringify({ head, version, gstack_version, run, review_loop, review_loop_exception, depth: r.review_depth?.depth, carried_from: r.carry?.from })); + const hop = r.carry ? r.carry.reason.split(' + ').pop()! : undefined; + const carry_kind = hop === undefined ? undefined : hop.includes('scoped re-check by ') ? 'recheck' : 'carry'; + return JSON.parse(JSON.stringify({ head, version, gstack_version, run, review_loop, review_loop_exception, depth: r.review_depth?.depth, carried_from: r.carry?.from, carry_kind })); } /** Every receipt and runs block with the blank lines after it. */ @@ -151,7 +158,7 @@ const STRIP_RE = /```gstack-(?:ship-receipt|receipt-runs)[ \t]*\r?\n[\s\S]*?\r?\ export function placeReceipt(body: string, receipt: ShipReceipt): string { const ex = extractReceipt(body); const prior = ex.receipt; - const runs = receiptRuns(body); + const runs = receiptRuns(body).filter(r => !r.status || !!receipt.carry || receipt.run === undefined || r.run !== receipt.run); if (prior && typeof prior.head === 'string' && JSON.stringify(prior) !== JSON.stringify(receipt)) runs.push(receiptRun(prior)); const kept = runs.slice(-RECEIPT_RUNS_KEPT); const block = renderReceiptBlock(receipt) + (kept.length ? '\n```' + RUNS_FENCE + '\n' + kept.map(r => JSON.stringify(r)).join('\n') + '\n```\n' : ''); @@ -272,8 +279,6 @@ export interface CarryPlanInput { scopedReview?: string; /** Stamp files the branch changed as product whose only change since the reviewed head is a stamp on the branch's own rows, the base untouched, and without which the two product patches match (GST-980). */ stampedRows?: string[]; - /** A clean scoped re-check of the range-diff since the reviewed head (crew/lib/ship-recheck.ts, J1): the carry reason it adds. */ - recheck?: string; } export interface CarryRecord { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[]; trees?: string[]; ancestry?: 'linear' | 'rewritten' } export type CarryPlan = { ok: true; carry: CarryRecord } | { ok: false; code: 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_REFUSED' | 'RECEIPT_CARRY_TREE_MISMATCH'; message: string }; @@ -342,14 +347,13 @@ export function classifyCarryPath(rel: string, extra: { metadata?: readonly stri * branch's own rows in a stamp file the branch also changed as product (`stampedRows`, GST-980). */ export function planCarry(input: CarryPlanInput): CarryPlan { - if (input.productPatchId.from !== input.productPatchId.head && !input.recheck && (input.changedProduct.length || (!input.scopedReview && !input.stampedRows?.length))) { + if (input.productPatchId.from !== input.productPatchId.head && (input.changedProduct.length || (!input.scopedReview && !input.stampedRows?.length))) { const named = input.changedProduct.slice(0, CARRY_NAMED_PATHS); return { ok: false, code: 'RECEIPT_CARRY_PRODUCT_CHANGED', message: `product diff changed between ${input.from.slice(0, 12)} and ${input.head.slice(0, 12)}: ${named.join(', ') || 'patch-id differs'}${input.changedProduct.length > named.length ? ` (+${input.changedProduct.length - named.length} more)` : ''}` }; } const parent = input.retargetedFrom ?? input.stackParent?.slice(0, 12); const reasons: string[] = parent ? [`stack parent ${parent} landed`] : []; if (input.mergeCommits > 0) reasons.push(input.mergeCommits === 1 ? 'base merge' : `${input.mergeCommits} base merges`); - if (input.recheck && input.productPatchId.from !== input.productPatchId.head) reasons.push(input.recheck); if (input.scopedReview && input.productPatchId.from !== input.productPatchId.head) reasons.push(input.scopedReview); if (input.stampedRows?.length && input.productPatchId.from !== input.productPatchId.head) reasons.push(`a stamp on the branch's own rows (${input.stampedRows.join(', ')})`); if (input.testPatchId.from !== input.testPatchId.head) reasons.push('test-only change'); @@ -488,6 +492,7 @@ export function parseReviewLoop(value: unknown): ReviewLoopReceipt | undefined { if (typeof v.scope === 'string') out.scope = v.scope.slice(0, 20); if (n('fix_checks') !== undefined) out.fix_checks = n('fix_checks'); if (n('rounds') !== undefined) out.rounds = n('rounds'); + if (n('scoped')) out.scoped = n('scoped'); if (n('est_input_tokens') !== undefined) out.est_input_tokens = n('est_input_tokens'); if (n('unrecorded')) out.unrecorded = n('unrecorded'); if (n('ledgers_read')) out.ledgers_read = n('ledgers_read'); diff --git a/ship/DRIVER.md b/ship/DRIVER.md index effbebd92..e50f772b8 100644 --- a/ship/DRIVER.md +++ b/ship/DRIVER.md @@ -45,7 +45,7 @@ end with `gstack-ship-parts next --run --phase --room <32000 - i **One program per pass.** Each review pass, Step 11 and the Step 14.5 audit is one program, and the parent makes no other call while it runs: (1) `gstack-review-dispatch pass`: `gstack-review-plan --base ` -with the pass's flags, then its staged manifest (Step 14.5: one reader, `docs`); (2) `gstack-review-log --start +with Step 9's plan flags, then its staged manifest (Step 14.5: one reader, `docs`); (2) `gstack-review-log --start ` once per row the step logs; (3) `BEFORE`; (4) `sent` (`BRIEF_MISMATCH` voids it), then one subagent per reader on its rendered file; (5) a poll until every reader settles (status `done` or `failed`, or a final summary; a fresh `idle` diff --git a/ship/DRIVER.md.tmpl b/ship/DRIVER.md.tmpl index f14197dd3..72a39e0c7 100644 --- a/ship/DRIVER.md.tmpl +++ b/ship/DRIVER.md.tmpl @@ -43,7 +43,7 @@ end with `gstack-ship-parts next --run --phase --room <32000 - i **One program per pass.** Each review pass, Step 11 and the Step 14.5 audit is one program, and the parent makes no other call while it runs: (1) `gstack-review-dispatch pass`: `gstack-review-plan --base ` -with the pass's flags, then its staged manifest (Step 14.5: one reader, `docs`); (2) `gstack-review-log --start +with Step 9's plan flags, then its staged manifest (Step 14.5: one reader, `docs`); (2) `gstack-review-log --start ` once per row the step logs; (3) `BEFORE`; (4) `sent` (`BRIEF_MISMATCH` voids it), then one subagent per reader on its rendered file; (5) a poll until every reader settles (status `done` or `failed`, or a final summary; a fresh `idle` diff --git a/ship/sections/pr-body.md b/ship/sections/pr-body.md index 39d72452f..18d7e926c 100644 --- a/ship/sections/pr-body.md +++ b/ship/sections/pr-body.md @@ -247,7 +247,7 @@ per-lane counts (`{"":{"pass":N,"fail":N,"skip":N}}`) to rm -f .gstack/tmp/review-loop.json NS=$(~/.claude/skills/gstack/bin/gstack-no-stop list | sed -n 's/^NO_STOP_FILE: //p'); [ -s "$NS" ] || NS= ~/.claude/skills/gstack/bin/gstack-review-scope summary --since "$REVIEW_SINCE" --no-ledger --out .gstack/tmp/review-loop.json && -~/.claude/skills/gstack/bin/gstack-ship-receipt write --pr --base --gate @.gstack/tmp/ship-gate.json --pregate .gstack/tmp/pregate.json --issues @.gstack/tmp/issues.json --review-loop @.gstack/tmp/review-loop.json --docs @.gstack/tmp/docs-audit.json $([ -s .gstack/tmp/targeted.json ] && echo --review-targeted @.gstack/tmp/targeted.json) ${NS:+--no-stop "@$NS"} --body "$PR_BODY_FILE" +~/.claude/skills/gstack/bin/gstack-ship-receipt write --pr --run --base --gate @.gstack/tmp/ship-gate.json --pregate .gstack/tmp/pregate.json --issues @.gstack/tmp/issues.json --review-loop @.gstack/tmp/review-loop.json --docs @.gstack/tmp/docs-audit.json $([ -s .gstack/tmp/targeted.json ] && echo --review-targeted @.gstack/tmp/targeted.json) ${NS:+--no-stop "@$NS"} --body "$PR_BODY_FILE" ``` If write refuses `review_targeted` for a docs claim added after the read, or after a granted fix round (add its `--grant`), rerun Step 9's plan with `--range-base diff --git a/ship/sections/pr-body.md.tmpl b/ship/sections/pr-body.md.tmpl index 4fe6e0d5d..af7ed820e 100644 --- a/ship/sections/pr-body.md.tmpl +++ b/ship/sections/pr-body.md.tmpl @@ -230,7 +230,7 @@ per-lane counts (`{"":{"pass":N,"fail":N,"skip":N}}`) to rm -f .gstack/tmp/review-loop.json NS=$(~/.claude/skills/gstack/bin/gstack-no-stop list | sed -n 's/^NO_STOP_FILE: //p'); [ -s "$NS" ] || NS= ~/.claude/skills/gstack/bin/gstack-review-scope summary --since "$REVIEW_SINCE" --no-ledger --out .gstack/tmp/review-loop.json && -~/.claude/skills/gstack/bin/gstack-ship-receipt write --pr --base --gate @.gstack/tmp/ship-gate.json --pregate .gstack/tmp/pregate.json --issues @.gstack/tmp/issues.json --review-loop @.gstack/tmp/review-loop.json --docs @.gstack/tmp/docs-audit.json $([ -s .gstack/tmp/targeted.json ] && echo --review-targeted @.gstack/tmp/targeted.json) ${NS:+--no-stop "@$NS"} --body "$PR_BODY_FILE" +~/.claude/skills/gstack/bin/gstack-ship-receipt write --pr --run --base --gate @.gstack/tmp/ship-gate.json --pregate .gstack/tmp/pregate.json --issues @.gstack/tmp/issues.json --review-loop @.gstack/tmp/review-loop.json --docs @.gstack/tmp/docs-audit.json $([ -s .gstack/tmp/targeted.json ] && echo --review-targeted @.gstack/tmp/targeted.json) ${NS:+--no-stop "@$NS"} --body "$PR_BODY_FILE" ``` If write refuses `review_targeted` for a docs claim added after the read, or after a granted fix round (add its `--grant`), rerun Step 9's plan with `--range-base diff --git a/ship/sections/review-army.md b/ship/sections/review-army.md index 5c06bf264..add34ef9f 100644 --- a/ship/sections/review-army.md +++ b/ship/sections/review-army.md @@ -17,7 +17,8 @@ Finish the complete review and QA before applying any fix in Step 9.4. **Review plan.** Pass 1 runs `~/.claude/skills/gstack/bin/gstack-review-plan --base `, plus `--depth-floor ` on every plan run when the /ship prompt -gave `--depth-floor ` (it only raises); add `--declare-risk ` when the diff touches a risk +gave `--depth-floor ` (it only raises), and Step 1's `PR_REVIEW_FLAGS:` on every plan run (the PR's +earlier rounds and a round grant; past two the plan is one read-only full review, and `PR_ROUND_CAP` stops for the lane, never the owner); add `--declare-risk ` when the diff touches a risk class the plan's `REVIEW_DEPTH:` misses (spend it reserves or binds: `money`), and give Step 16's receipt write the same flag; a repeat uses the plan run that picked it. A `scoped` repeat is a full pass on the range: its `fix-check` is decision 3.5's @@ -821,7 +822,9 @@ finding makes that PR a draft. ### Decide whether to repeat Step 9 -After persistence, record missing output, CYCLES and fixes in the invocation record. +After persistence, record missing output, CYCLES and fixes in the invocation record. With a PR open, run +`gstack-review-scope summary --since "$REVIEW_SINCE" --no-ledger --out .gstack/tmp/review-loop.json && gstack-ship-receipt stub --pr --run --review-loop @.gstack/tmp/review-loop.json` +so a run that stops still counts its rounds (Step 19's write, same `--run`, replaces it). Decision 1 always applies first. Then, under `frozen`, run `gstack-review-plan --base --pass $PASS --last full` with each flag that holds (`--fixed-blocking`, `--fixed-below`, `--blocking-open`, `--touched-gate` for a fix to an item 2.5 path, `--critical-found` when this pass diff --git a/ship/sections/review-army.md.tmpl b/ship/sections/review-army.md.tmpl index d7e7f6ec6..24800f01a 100644 --- a/ship/sections/review-army.md.tmpl +++ b/ship/sections/review-army.md.tmpl @@ -15,7 +15,8 @@ Finish the complete review and QA before applying any fix in Step 9.4. **Review plan.** Pass 1 runs `~/.claude/skills/gstack/bin/gstack-review-plan --base `, plus `--depth-floor ` on every plan run when the /ship prompt -gave `--depth-floor ` (it only raises); add `--declare-risk ` when the diff touches a risk +gave `--depth-floor ` (it only raises), and Step 1's `PR_REVIEW_FLAGS:` on every plan run (the PR's +earlier rounds and a round grant; past two the plan is one read-only full review, and `PR_ROUND_CAP` stops for the lane, never the owner); add `--declare-risk ` when the diff touches a risk class the plan's `REVIEW_DEPTH:` misses (spend it reserves or binds: `money`), and give Step 16's receipt write the same flag; a repeat uses the plan run that picked it. A `scoped` repeat is a full pass on the range: its `fix-check` is decision 3.5's @@ -231,7 +232,9 @@ finding makes that PR a draft. ### Decide whether to repeat Step 9 -After persistence, record missing output, CYCLES and fixes in the invocation record. +After persistence, record missing output, CYCLES and fixes in the invocation record. With a PR open, run +`gstack-review-scope summary --since "$REVIEW_SINCE" --no-ledger --out .gstack/tmp/review-loop.json && gstack-ship-receipt stub --pr --run --review-loop @.gstack/tmp/review-loop.json` +so a run that stops still counts its rounds (Step 19's write, same `--run`, replaces it). Decision 1 always applies first. Then, under `frozen`, run `gstack-review-plan --base --pass $PASS --last full` with each flag that holds (`--fixed-blocking`, `--fixed-below`, `--blocking-open`, `--touched-gate` for a fix to an item 2.5 path, `--critical-found` when this pass diff --git a/test/factory-scorecard.test.ts b/test/factory-scorecard.test.ts index bb26faac3..6cbb33d9f 100644 --- a/test/factory-scorecard.test.ts +++ b/test/factory-scorecard.test.ts @@ -11,7 +11,7 @@ import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { - BENCHMARKS, DEFAULTS, classifyGate, collectScorecard, fixtureSource, flakeRecords, fmtHours, gateOutcome, inWindow, passCount, percentile, readComments, renderCsv, + BENCHMARKS, DEFAULTS, classifyGate, collectScorecard, fixtureSource, flakeRecords, fmtHours, gateOutcome, inWindow, passCount, percentile, readComments, receiptRounds, renderCsv, renderMarkdown, scorecardRows, searchRange, verdictCost, type FixtureFile, type ScorecardOptions, } from '../lib/factory-scorecard'; @@ -346,6 +346,14 @@ describe('factory-scorecard: pieces', () => { expect(passCount('no count here', new RegExp(DEFAULTS.passMarker, 'm'))).toBeNull(); }); + // Value: protects=a PR shipped three times at two rounds each reports 6 rounds, not the largest run's 2 (GST-2673); fails_when=the scorecard takes the max again; why_new=R51 counts per PR; seam=none; no_claim=bodies without a receipt, which keep the marker's max + test('receiptRounds sums R51 rounds across the receipt and its runs', () => { + const run = (c: string, id: string) => JSON.stringify({ head: c.repeat(40), run: id, review_loop: { passes: 1, blocking_found: 0, deferred: 0, fix_checks: 1, rounds: 2 } }); + const body = '```gstack-ship-receipt\n' + JSON.stringify({ schema_version: 1, ...JSON.parse(run('c', 'r3')) }) + '\n```\n\n```gstack-receipt-runs\n' + run('a', 'r1') + '\n' + run('b', 'r2') + '\n```\n'; + expect(receiptRounds(body)).toBe(6); + expect(receiptRounds('passes=2')).toBeNull(); + }); + test('verdict cost reads collector-outcomes.json and ignores an unreadable one; flake records skip torn lines and unknown rerun cost', () => { const dir = scratch(); fs.mkdirSync(path.join(dir, 'a', 'paid-report'), { recursive: true }); diff --git a/test/fixtures/review-pins/files/lib/review-depth.ts.json b/test/fixtures/review-pins/files/lib/review-depth.ts.json index 9a556d9b5..08524f6d6 100644 --- a/test/fixtures/review-pins/files/lib/review-depth.ts.json +++ b/test/fixtures/review-pins/files/lib/review-depth.ts.json @@ -1 +1 @@ -{"sha":"057c5f84b5227d6ad8c6010447875ac9f031e35a4e6ef1aaaf17726cdd797ae6","replay":"GST-2547"} +{"sha":"554bb5187acbe3eee749d765fd6abf3ee6122a542530bfedc3450504f7a0cd49","replay":"GST-2673"} diff --git a/test/fixtures/review-pins/files/ship/sections/review-army.md.json b/test/fixtures/review-pins/files/ship/sections/review-army.md.json index 99d8f1ea2..205237247 100644 --- a/test/fixtures/review-pins/files/ship/sections/review-army.md.json +++ b/test/fixtures/review-pins/files/ship/sections/review-army.md.json @@ -1 +1 @@ -{"sha":"346dfea9dcc2e28cd0c9dbfb9f1207798a93a3cecbd913d12e16557a32b0f3fc","replay":"GST-2073"} +{"sha":"41631ea2501711a8a32b3d266540afa52b142a10b37af88980b3186e92340517","replay":"GST-2673"} diff --git a/test/fixtures/review-pins/replays/GST-2673.json b/test/fixtures/review-pins/replays/GST-2673.json new file mode 100644 index 000000000..ce566c27c --- /dev/null +++ b/test/fixtures/review-pins/replays/GST-2673.json @@ -0,0 +1 @@ +{"replay":"GST-2673","justification":"GST-2673 (R51 per pull request). Paid no-loss replay (docs/evals/pr-round-count-prereg.md, results in docs/evals/pr-round-count-results.md): a diff-only scoped re-check found 22 of 24 seeded faults but 0 of 8 real ones, so bar 1 failed (FIX-METHOD) and the re-check no longer stands in for a review; these bytes give the merge head a full review instead. Deterministic no-loss replay, no paid run, old lib/review-depth.ts from origin/main 3c15b7210 against the new one: nextStep over 196,608 History cases with no prior rounds, 196,608 identical. With --prior-full 1 to 3, with and without a round grant (122,880 cases): pass 1 is a full pass in every case, and the 14,528 lighter steps are each a review step past the PR's two full rounds (three with a grant), which R51 caps, ending done with notes or PR_ROUND_CAP for the lane. ship/sections/review-army.md adds Step 1's PR_REVIEW_FLAGS to every plan run and the run stub; no reviewer brief, checklist or finding rule changes."} diff --git a/test/helpers/placeholder-allowlist.ts b/test/helpers/placeholder-allowlist.ts index 5bee10db2..974049129 100644 --- a/test/helpers/placeholder-allowlist.ts +++ b/test/helpers/placeholder-allowlist.ts @@ -66,6 +66,7 @@ export const IDENTIFIER_PLACEHOLDERS: Record = { '': { grammar: NUM, what: 'GitHub Actions run id' }, '': { grammar: NUM, what: 'process id printed by an earlier block' }, '': { grammar: ID, what: 'run id printed by Setup' }, + '': { grammar: ID, what: "the /ship run id Step 1's gstack-ship-preflight --run took" }, '': { grammar: ID, what: 'run id printed by Setup' }, '': { grammar: oneOf('ceo', 'design', 'dx', 'eng'), what: 'autoplan phase' }, '': { grammar: /^[A-Z]$/, what: 'variant letter' }, diff --git a/test/pr-review-history.test.ts b/test/pr-review-history.test.ts new file mode 100644 index 000000000..102c63ab0 --- /dev/null +++ b/test/pr-review-history.test.ts @@ -0,0 +1,116 @@ +/** + * GST-2673: /ship counts review rounds per pull request, across every head and /ship run, from the receipt and the + * receipt-runs history the PR body already keeps (docs/review-policy.md#rounds-per-pull-request). + */ +import { describe, expect, test } from 'bun:test'; +import { historyLine, placeRunEntry, prReviewHistory, reviewRoute } from '../lib/pr-review-history'; +import { orderReceipt, placeReceipt, receiptRun, receiptRuns } from '../lib/ship-receipt'; +import type { ShipReceipt } from '../lib/headless-artifacts'; + +const sha = (c: string) => c.repeat(40); +const loop = (l: Partial>) => ({ passes: 1, blocking_found: 0, deferred: 0, ...l }); +const receipt = (head: string, l: Partial> = {}, extra: Partial = {}): ShipReceipt => + orderReceipt({ schema_version: 1, head, base: 'main', version: '1.0.0.0', review_loop: loop(l), ...extra }); +const carried = (r: ShipReceipt, head: string, reason: string): ShipReceipt => + orderReceipt({ ...r, head, carry: { from: r.carry?.from ?? r.head, reason, product_patch_id: 'x', changed_paths: [], merge_commits: 0, range_diff: '', covers: [], reruns: [] } }); + +describe('prReviewHistory', () => { + test('a body with no receipt has no history', () => { + expect(prReviewHistory('## Summary\nprose\n')).toMatchObject({ rounds: 0, full: 0, runs: 0, first_full: null, source: 'pr-body' }); + }); + + test('rounds follow R51 (passes plus fix-checks) summed across /ship runs, not the largest run', () => { + let body = placeReceipt('', receipt(sha('a'), { passes: 1, fix_checks: 1, rounds: 2 }, { run: 'r1' })); + body = placeReceipt(body, receipt(sha('b'), { passes: 1, fix_checks: 1, rounds: 2 }, { run: 'r2' })); + const h = prReviewHistory(body); + expect(h).toMatchObject({ runs: 2, rounds: 4, full: 2, fix_checks: 2, first_full: sha('a'), last_full: sha('b') }); + }); + + test('a scoped pass 2 is a round but not a full round', () => { + const h = prReviewHistory(placeReceipt('', receipt(sha('a'), { passes: 2, scoped: 1, rounds: 2 }))); + expect(h).toMatchObject({ rounds: 2, full: 1, scoped: 1 }); + }); + + test('a carried receipt repeats its run\'s loop and adds no round; a re-check carry counts as a re-check', () => { + const r1 = receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' }); + let body = placeReceipt('', r1); + const c1 = carried(r1, sha('b'), 'scoped re-check by anthropic/claude-opus-5-5 (range-diff 40 lines)'); + body = placeReceipt(body, c1); + body = placeReceipt(body, carried(c1, sha('c'), 'test-only change')); + expect(receiptRuns(body).map(r => r.carry_kind ?? 'run')).toEqual(['run', 'recheck']); + expect(prReviewHistory(body)).toMatchObject({ rounds: 1, full: 1, rechecks: 1, runs: 1, heads: 3 }); + }); + + test('the same run written twice counts once', () => { + let body = placeReceipt('', receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' })); + body = placeReceipt(body, receipt(sha('b'), { passes: 1, rounds: 1 }, { run: 'r1' })); + expect(prReviewHistory(body)).toMatchObject({ rounds: 1, runs: 1 }); + }); + + test('a started stub counts its rounds so far until its run writes a receipt, which replaces it', () => { + let body = placeReceipt('', receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' })); + body = placeRunEntry(body, { head: sha('b'), run: 'r2', status: 'started', review_loop: loop({ passes: 1, rounds: 1 }) }); + expect(prReviewHistory(body)).toMatchObject({ rounds: 2, stubs: 1 }); + body = placeRunEntry(body, { head: sha('b'), run: 'r2', status: 'started', review_loop: loop({ passes: 1, fix_checks: 1, rounds: 2 }) }); + expect(receiptRuns(body).filter(r => r.status === 'started').length).toBe(1); + expect(prReviewHistory(body).rounds).toBe(3); + body = placeReceipt(body, receipt(sha('c'), { passes: 1, fix_checks: 1, rounds: 2 }, { run: 'r2' })); + expect(receiptRuns(body).some(r => r.status === 'started')).toBe(false); + expect(prReviewHistory(body)).toMatchObject({ rounds: 3, stubs: 0, runs: 2 }); + }); + + test('a voided stub (an infrastructure failure) counts nothing', () => { + let body = placeReceipt('', receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' })); + body = placeRunEntry(body, { head: sha('b'), run: 'r2', status: 'voided', review_loop: loop({ passes: 1, rounds: 1 }) }); + expect(prReviewHistory(body).rounds).toBe(1); + }); + + test('a receipt written without a run keeps the stubs of other runs', () => { + let body = placeReceipt('', receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' })); + body = placeRunEntry(body, { head: sha('b'), run: 'r2', status: 'started', review_loop: loop({ passes: 1, rounds: 1 }) }); + body = placeReceipt(body, receipt(sha('c'), { passes: 1, rounds: 1 })); + expect(prReviewHistory(body)).toMatchObject({ stubs: 1, full: 3 }); + }); + + test('a stub lands in a body with no receipt yet, inside the Agent notes section', () => { + const body = placeRunEntry('## Summary\nprose\n', { head: sha('a'), run: 'r1', status: 'started', review_loop: loop({ passes: 1, rounds: 1 }) }); + expect(body.startsWith('## Summary\nprose\n')).toBe(true); + expect(prReviewHistory(body)).toMatchObject({ rounds: 1, stubs: 1 }); + }); + + test('receiptRun records the carry kind of the latest hop only', () => { + const r1 = receipt(sha('a')); + expect(receiptRun(carried(r1, sha('b'), 'test-only change + scoped re-check by x (range-diff 3 lines)')).carry_kind).toBe('recheck'); + expect(receiptRun(carried(r1, sha('b'), 'scoped re-check by x (range-diff 3 lines) + base merge')).carry_kind).toBe('carry'); + expect(receiptRun(r1).carry_kind).toBeUndefined(); + }); +}); + +describe('route (F1: the merge head gets a full review; a re-check is advice only)', () => { + test('no prior full round: the first full round, as today', () => { + expect(reviewRoute({ full: 0 })).toMatchObject({ route: 'first' }); + }); + + test('after one full round a new head gets a fresh full review, its last before merge, never the re-check', () => { + expect(reviewRoute({ full: 1 })).toMatchObject({ route: 'final', reason: expect.stringContaining('round 2 of 2') }); + }); + + test('at the cap a new head gets one read-only full review; an extra-round grant buys a round with its fix round', () => { + expect(reviewRoute({ full: 2 })).toMatchObject({ route: 'read-only', reason: expect.stringContaining('no fix round') }); + expect(reviewRoute({ full: 3 }).route).toBe('read-only'); + expect(reviewRoute({ full: 2 }, { grant: 'a-1' })).toMatchObject({ route: 'final', reason: expect.stringContaining('a-1') }); + expect(reviewRoute({ full: 3 }, { grant: 'a-1' }).route).toBe('read-only'); + }); + + test('a re-check carry from an old receipt adds no full round, so it never moves the route', () => { + const r1 = receipt(sha('a'), { passes: 1, rounds: 1 }, { run: 'r1' }); + const body = placeReceipt(placeReceipt('', r1), carried(r1, sha('b'), 'scoped re-check by x (range-diff 3 lines)')); + expect(reviewRoute(prReviewHistory(body)).route).toBe('final'); + }); + + test('the history line carries no drift or re-check-blocker fields', () => { + const line = historyLine('7', prReviewHistory(placeReceipt('', receipt(sha('a'), { passes: 1, rounds: 1 })))); + expect(line).toStartWith('PR_REVIEW_HISTORY: pr=#7 rounds=1 cap=2 full=1 '); + expect(line).not.toMatch(/drift|recheck_blocked/); + }); +}); diff --git a/test/pr-round-cli.test.ts b/test/pr-round-cli.test.ts new file mode 100644 index 000000000..e54622cc1 --- /dev/null +++ b/test/pr-round-cli.test.ts @@ -0,0 +1,109 @@ +/** + * GST-2673 CLI seams: gstack-review-plan --prior-rounds / --round-grant, gstack-approvals round-grant, and + * gstack-ship-receipt history / stub over a PR body file. + */ +import { afterEach, describe, expect, test } from 'bun:test'; +import { spawnSync } from 'node:child_process'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; + +const BIN = (n: string) => path.join(import.meta.dir, '..', 'bin', n); +const dirs: string[] = []; +afterEach(() => { while (dirs.length) fs.rmSync(dirs.pop()!, { recursive: true, force: true }); }); +const tmp = (p: string) => { const d = fs.mkdtempSync(path.join(os.tmpdir(), p)); dirs.push(d); return d; }; + +function repo() { + const dir = tmp('pr-rounds-'), state = tmp('pr-rounds-state-'); + const git = (...a: string[]) => spawnSync('git', a, { cwd: dir, encoding: 'utf8', timeout: 10_000 }); + git('init', '-q', '-b', 'main'); git('config', 'user.email', 't@t'); git('config', 'user.name', 't'); git('config', 'commit.gpgsign', 'false'); + fs.writeFileSync(path.join(dir, 'README.md'), '# x\n'); git('add', '.'); git('commit', '-qm', 'base'); + git('checkout', '-qb', 'feat'); + fs.mkdirSync(path.join(dir, 'src')); fs.writeFileSync(path.join(dir, 'src', 'a.ts'), 'export const a = 1;\n'); git('add', '.'); git('commit', '-qm', 'feat'); + const env = { ...process.env, GSTACK_STATE_ROOT: state, GSTACK_APPROVALS_MIRROR: '0', GSTACK_CAPY: '' }; + const run = (bin: string, args: string[]) => spawnSync(BIN(bin), args, { cwd: dir, encoding: 'utf8', timeout: 60_000, env }); + return { dir, head: git('rev-parse', 'HEAD').stdout.trim(), run }; +} + +describe('gstack-review-plan with the PR round count', () => { + test('two prior full rounds plan one read-only full review of HEAD; a grant at HEAD plans a round with its fix round', () => { + const r = repo(); + const ro = r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-rounds', '2', '--prior-full', '2', '--pr', '5']); + expect(ro.status).toBe(0); + expect(ro.stdout).toMatch(/REVIEW_PLAN: class=\S+ pass=1 pr_rounds=2 next=full /); + expect(ro.stdout).toContain('read-only final review (R51)'); + expect(ro.stdout).not.toContain('for the owner'); + const granted = r.run('gstack-approvals', ['round-grant', '--pr', '5', '--head', r.head, '--kind', 'extra-round', '--reason', 'the design changed after round 2', '--by', 'captain:test']); + expect(granted.status).toBe(0); + const id = /APPROVAL_RECORDED: (a-[0-9a-f]{12})/.exec(granted.stdout)?.[1]; + expect(id).toBeDefined(); + const full = r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-rounds', '2', '--prior-full', '2', '--pr', '5', '--round-grant', id!]); + expect(full.stdout).toContain('next=full'); + expect(full.stdout).toContain('round 3 of 3'); + expect(r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-rounds', '2', '--prior-full', '2', '--pr', '6', '--round-grant', id!]).status).toBe(3); + expect(r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-full', 'x']).status).toBe(2); + }); + + test('a grant still plans after the fix round commits on top of its head, and never for a head off the branch', () => { + const r = repo(); + const id = /APPROVAL_RECORDED: (a-[0-9a-f]{12})/.exec(r.run('gstack-approvals', ['round-grant', '--pr', '5', '--head', r.head, '--kind', 'extra-round', '--reason', 'the design changed after round 2', '--by', 'captain:test']).stdout)?.[1]; + expect(id).toBeDefined(); + const git = (...a: string[]) => spawnSync('git', a, { cwd: r.dir, encoding: 'utf8', timeout: 10_000 }); + fs.writeFileSync(path.join(r.dir, 'src', 'a.ts'), 'export const a = 2;\n'); git('commit', '-qam', 'fix'); + const decide = r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-rounds', '2', '--prior-full', '2', '--pr', '5', '--round-grant', id!, '--pass', '2', '--last', 'full', '--fixed-below', '--range-base', r.head]); + expect(decide.status).toBe(0); + git('checkout', '-q', 'main'); git('checkout', '-qb', 'other'); fs.writeFileSync(path.join(r.dir, 'b.ts'), 'export const b = 1;\n'); git('add', '.'); git('commit', '-qm', 'other'); + expect(r.run('gstack-review-plan', ['--base', 'main', '--gate-tagged', '0', '--prior-rounds', '2', '--prior-full', '2', '--pr', '5', '--round-grant', id!]).status).toBe(3); + }); +}); + +describe('gstack-approvals round-grant', () => { + test('gstack cannot grant itself a round, and add refuses the scope', () => { + const r = repo(); + expect(r.run('gstack-approvals', ['round-grant', '--pr', '5', '--head', r.head, '--kind', 'extra-round', '--reason', 'x', '--by', 'gstack']).status).toBe(2); + expect(r.run('gstack-approvals', ['round-grant', '--pr', '5', '--head', r.head, '--kind', 'more', '--reason', 'x', '--by', 'lane']).status).toBe(2); + expect(r.run('gstack-approvals', ['add', '--ask', 'a', '--words', 'w', '--by', 'b', '--scope', `review_round_grant ${r.head} pr=5 kind=extra-round`]).status).toBe(2); + }); +}); + +describe('gstack-ship-receipt history and stub', () => { + test('history prints the rounds, the flags Step 9 passes and the route; a stub counts until the run writes its receipt', () => { + const r = repo(); + const loop = { passes: 1, blocking_found: 0, deferred: 0, rounds: 1 }; + const body = path.join(r.dir, 'body.md'); + fs.writeFileSync(body, '## Summary\nprose\n\n```gstack-ship-receipt\n' + JSON.stringify({ schema_version: 1, head: 'a'.repeat(40), run: 'r1', review_loop: loop }) + '\n```\n'); + const h = r.run('gstack-ship-receipt', ['history', '--body', body, '--pr', '5']); + expect(h.status).toBe(0); + expect(h.stdout).toMatch(/^PR_REVIEW_HISTORY: pr=#5 rounds=1 cap=2 full=1 /m); + expect(h.stdout).toContain('PR_REVIEW_FLAGS: --prior-rounds 1 --prior-full 1\n'); + expect(h.stdout).toMatch(/^PR_REVIEW_ROUTE: final \(the PR had 1 full review round; this head gets a fresh full review/m); + expect(h.stdout).not.toMatch(/drift|recheck_blocked/); + const s = r.run('gstack-ship-receipt', ['stub', '--body', body, '--run', 'r2', '--review-loop', JSON.stringify({ ...loop, fix_checks: 1, rounds: 2 })]); + expect(s.stdout).toContain('RUN_STUB: run=r2 status=started rounds=2'); + const after = r.run('gstack-ship-receipt', ['history', '--body', body, '--pr', '5']).stdout; + expect(after).toContain('PR_REVIEW_FLAGS: --prior-rounds 3 --prior-full 2\n'); + expect(after).toMatch(/^PR_REVIEW_ROUTE: read-only \(.*no fix round/m); + expect(fs.readFileSync(body, 'utf8').startsWith('## Summary\nprose\n')).toBe(true); + expect(r.run('gstack-ship-receipt', ['stub', '--body', body]).status).toBe(2); + }); + + test('an unreadable PR body prints source=unavailable and its fix', () => { + const r = repo(); + const h = r.run('gstack-ship-receipt', ['history', '--body', path.join(r.dir, 'missing.md')]); + expect(h.status).toBe(1); + expect(h.stdout).toContain('source=unavailable'); + expect(h.stderr).toContain('fix:'); + }); +}); + +describe('a scoped re-check is advice only (G1)', () => { + test('carry refuses --recheck: no re-check record carries a receipt', () => { + const r = repo(); + const body = path.join(r.dir, 'body.md'); + fs.writeFileSync(body, '## Summary\n'); + const c = r.run('gstack-ship-receipt', ['carry', '--body', body, '--recheck', path.join(r.dir, 'r.json')]); + expect(c.status).toBe(3); + expect(c.stderr).toContain('--recheck is gone: a scoped re-check is advice only and never carries a receipt'); + expect(fs.readFileSync(body, 'utf8')).toBe('## Summary\n'); + }); +}); diff --git a/test/review-plan-pr-rounds.test.ts b/test/review-plan-pr-rounds.test.ts new file mode 100644 index 000000000..66355c3d9 --- /dev/null +++ b/test/review-plan-pr-rounds.test.ts @@ -0,0 +1,78 @@ +/** + * GST-2673: the review plan caps full review rounds per pull request (R51) with the full rounds earlier /ship runs on the + * PR already spent (--prior-full from PR_REVIEW_FLAGS), prints every earlier round as pr_rounds= (--prior-rounds), and + * a recorded round grant buys one more full round at its head. + */ +import { describe, expect, test } from 'bun:test'; +import { FULL_PASS_CAP, nextStep, type History } from '../lib/review-depth'; + +const h = (x: Partial): History => ({ fullPasses: 0, last: 'none', ...x }); + +describe('PR round cap', () => { + test('no prior rounds leaves the plan as today', () => { + expect(nextStep(h({})).step).toBe('full'); + expect(nextStep(h({ lean: true })).step).toBe('full'); + expect(nextStep(h({ priorRounds: 0, priorFull: 0, fullPasses: 1, last: 'full', fixedBlocking: true }), 'standard').reason).not.toContain('PR_ROUND_CAP'); + }); + + // Value: protects=the plan's d3a case: a run of a full pass plus a scoped pass 2 leaves the next head one full round; + // fails_when=the cap counts scoped passes or fix-checks as full rounds; seam=nextStep; no_claim=preflight's re-check route + test('one prior full round (two rounds with a scoped pass 2): pass 1 is the PR\'s second and last full round, in both tables', () => { + for (const lean of [false, true]) { + const n = nextStep(h({ priorRounds: 2, priorFull: 1, lean })); + expect(n.step).toBe('full'); + expect(n.reason).toContain('full round 2 of 2, the last'); + } + }); + + test('one prior full round: after pass 1, a below-floor fix keeps its in-run fix-check and a fixed blocker stops for the lane, not the owner', () => { + expect(nextStep(h({ priorFull: 1, fullPasses: 1, last: 'full', fixedBelow: true }), 'standard').step).toBe('fix-check'); + const stop = nextStep(h({ priorFull: 1, fullPasses: 1, last: 'full', fixedBlocking: true }), 'standard'); + expect(stop.step).toBe('stop'); + expect(stop.reason).toStartWith('PR_ROUND_CAP'); + expect(stop.reason).not.toContain('for the owner'); + }); + + test('a fix-check stays the in-run table\'s call: lean\'s one fix-check after a fixed blocker still runs', () => { + expect(nextStep(h({ priorFull: 1, fullPasses: 1, last: 'full', fixedBlocking: true, lean: true }), 'standard').step).toBe('fix-check'); + }); + + // Value: protects=F1's past-cap case: a PR with two full rounds whose own code changed gets one read-only full review of + // the merge head; fails_when=a third /ship run gets a fix round without a grant, or the merge head goes unreviewed; + // seam=nextStep; no_claim=the CLI's pr_rounds= print (pr-round-cli) + test('two prior full rounds: pass 1 is one read-only full review with no fix round, in both tables', () => { + for (const lean of [false, true]) { + const n = nextStep(h({ priorRounds: 4, priorFull: FULL_PASS_CAP, lean })); + expect(n.step).toBe('full'); + expect(n.reason).toStartWith('read-only final review (R51): this PR already had 2 full review rounds'); + } + }); + + test('after the read-only review: below-floor findings ship as notes, a blocker stops for the lane\'s Captain', () => { + for (const lean of [false, true]) { + expect(nextStep(h({ priorFull: 2, fullPasses: 1, last: 'full', lean })).step).toBe('done'); + expect(nextStep(h({ priorFull: 2, fullPasses: 1, last: 'full', fixedBelow: true, lean }), 'standard')).toMatchObject({ step: 'done', reason: expect.stringContaining('no fix round') }); + for (const x of [{ blockingOpen: true }, { fixedBlocking: true }, { touchedGate: true, fixedBelow: true }]) { + const stop = nextStep(h({ priorFull: 3, fullPasses: 1, last: 'full', lean, ...x }), 'standard'); + expect(stop.step).toBe('stop'); + expect(stop.reason).toStartWith('PR_ROUND_CAP: the read-only final review'); + expect(stop.reason).toContain("lane's Captain"); + } + } + }); + + test('a round grant buys one more full round at its head, never two', () => { + expect(nextStep(h({ priorFull: 2, roundGrant: 'a-1' })).step).toBe('full'); + expect(nextStep(h({ priorFull: 3, roundGrant: 'a-1' }))).toMatchObject({ step: 'full', reason: expect.stringContaining('read-only final review') }); + expect(nextStep(h({ priorFull: 2, roundGrant: 'a-1', fullPasses: 1, last: 'full', fixedBlocking: true }), 'standard').reason).toStartWith('PR_ROUND_CAP'); + }); + + test('gate class still runs Step 11\'s voices before the PR cap stop', () => { + expect(nextStep(h({ priorFull: 2, fullPasses: 1, last: 'full', blockingOpen: true, gate: true, adversarialRan: false }), 'standard').step).toBe('voices'); + }); + + test('a blocking finding still open keeps today\'s stop', () => { + const n = nextStep(h({ priorFull: 1, fullPasses: 1, last: 'full', blockingOpen: true }), 'standard'); + expect(n.step).toBe('stop'); + }); +}); diff --git a/test/review-round-grant.test.ts b/test/review-round-grant.test.ts new file mode 100644 index 000000000..913318f70 --- /dev/null +++ b/test/review-round-grant.test.ts @@ -0,0 +1,32 @@ +/** + * GST-2673: a review round grant is a reason the lane or its Captain records in the approvals path; it is never an + * owner ask, never a plan approval, and it binds one head of one PR. + */ +import { describe, expect, test } from 'bun:test'; +import { grantAt, reviewRoundGrantRow, reviewRoundGrants, reviewRoundGrantText, REVIEW_ROUND_GRANT_SCOPE } from '../lib/review-round-grant'; +import type { ApprovalRow } from '../lib/approval-record'; + +const head = '1'.repeat(40); +const row = (o: Partial): ApprovalRow => ({ id: 'a-000000000001', date: '2026-11-14', recorded_at: '2026-11-14T00:00:00Z', words: 'w', by: 'captain:GStack Minder', pending: 'none', outcome: 'approved', source: 'manual', branch: 'b', ...reviewRoundGrantRow(head, 12, 'extra-round', 'the design changed after round 2'), ...o } as ApprovalRow); + +describe('review round grants', () => { + test('the row round-trips with kind, head, PR and reason', () => { + const [g] = reviewRoundGrants([row({})]); + expect(g).toMatchObject({ kind: 'extra-round', head, pr: 12, reason: 'the design changed after round 2', approval: 'a-000000000001' }); + expect(REVIEW_ROUND_GRANT_SCOPE.test(row({}).scope)).toBe(true); + expect(reviewRoundGrantText(g!)).toContain('extra-round at 111111111111 for PR #12'); + }); + + test('only an approved row that gstack did not write counts, and it binds only its head and PR', () => { + expect(reviewRoundGrants([row({ outcome: 'pending' as any })])).toEqual([]); + expect(reviewRoundGrants([row({ by: 'gstack' })])).toEqual([]); + const gs = reviewRoundGrants([row({})]); + expect(grantAt(gs, 12, head)).toBeDefined(); + expect(grantAt(gs, 13, head)).toBeUndefined(); + expect(grantAt(gs, 12, '2'.repeat(40))).toBeUndefined(); + }); + + test('a mismatched ask and scope is no grant', () => { + expect(reviewRoundGrants([row({ ask: 'review_round_grant extra-round at ' + '2'.repeat(40) + ' for pr 12: x' })])).toEqual([]); + }); +}); diff --git a/test/ship-preflight.test.ts b/test/ship-preflight.test.ts index 8957772e8..6c7741dca 100644 --- a/test/ship-preflight.test.ts +++ b/test/ship-preflight.test.ts @@ -253,6 +253,21 @@ describe('gstack-ship-preflight', () => { expect(r.stdout).toContain('NEXT: Step 4'); }); + // Value: protects=preflight prints the PR's review rounds from its body and the flags Step 9 passes to every plan (GST-2673); fails_when=a second /ship run on a PR starts its round count at zero; + // why_new=R51 counted per run, so a PR pushed N times got 2N rounds; seam=gh, gstack-ship-receipt history; no_claim=carry's own refusal of --recheck (pr-round-cli, ship-recheck) + test('an open PR prints PR_REVIEW_HISTORY and the --prior-rounds flags from its body', () => { + const f = fx(); + const run = (head: string, id: string) => ({ head, run: id, review_loop: { passes: 1, blocking_found: 0, deferred: 0, fix_checks: 1, rounds: 2 } }); + const body = '## Summary\n\n```gstack-ship-receipt\n' + JSON.stringify({ schema_version: 1, ...run('b'.repeat(40), 'r2') }) + '\n```\n\n```gstack-receipt-runs\n' + JSON.stringify(run('a'.repeat(40), 'r1')) + '\n```\n'; + fs.writeFileSync(path.join(f.root, 'body.json'), JSON.stringify({ body })); + f.gh(`case "$*" in *"pr view"*) cat '${path.join(f.root, 'body.json')}';; *) echo 7;; esac`); + const r = f.run(PREFLIGHT, ['--base', 'main']); + expect(lineOf(r.stdout, 'PR_REVIEW_HISTORY')).toMatch(/^PR_REVIEW_HISTORY: pr=#7 rounds=4 cap=2 full=2 /); + expect(lineOf(r.stdout, 'PR_REVIEW_FLAGS')).toBe('PR_REVIEW_FLAGS: --prior-rounds 4 --prior-full 2'); + expect(lineOf(r.stdout, 'PR_REVIEW_ROUTE')).toMatch(/^PR_REVIEW_ROUTE: read-only \(the PR had 2 full review rounds; this head gets one read-only full review/); + expect(r.stdout).not.toMatch(/--recheck|drift_lines|recheck_blocked/); + }); + // Value: protects=the branch name reaches gh as one argv item, never through a shell; fails_when=a branch named with $(...) runs a command on the shipper's machine; // why_new=GSTA-167 /ship review of #3633 (security, CRITICAL); seam=gh; no_claim=gh's own handling of the name test('a branch name with shell syntax is never executed', () => { diff --git a/test/ship-receipt-carry-mixed.test.ts b/test/ship-receipt-carry-mixed.test.ts index c0cfa8485..07409bec3 100644 --- a/test/ship-receipt-carry-mixed.test.ts +++ b/test/ship-receipt-carry-mixed.test.ts @@ -66,7 +66,7 @@ function founderstar(resolvedSave = 84, baseBlock = 0) { } const scopedPacket = (err: string) => /one fix-check reviewer reads (\S+), then rerun carry/.exec(err)?.[1]; -const eligible = (err: string) => /^RECHECK: eligible range_diff_lines=(\d+) range_diff_sha256=([0-9a-f]{64}) packet=(\S+);/m.exec(err); +const eligible = (err: string) => /^RECHECK: advisory range_diff_lines=(\d+) range_diff_sha256=([0-9a-f]{64}) packet=(\S+);/m.exec(err); const recordAt = (f: ShipFx, name: string, v: object) => { const file = path.join(f.root, name); fs.writeFileSync(file, JSON.stringify(v)); return file; }; describe('a base-side removed line next to byte-identical added lines (GST-1561 ask 2)', () => { @@ -136,26 +136,19 @@ describe('carry: a changed path plus context paths compose into one bounded re-c return { ...x, head: x.f.git('rev-parse', 'HEAD').stdout.trim() }; }; - test('one packet holds the range-diff and the context hunks, bound to range_base; a clean record carries', () => { + test('one advisory packet holds the range-diff and the context hunks, bound to range_base; no record carries (GST-2673)', () => { const { f, from, head, reviewedBase, carry, body } = composed(); const ask = carry(); expect([ask.status, ask.stdout.trim().split('\n')[0]], ask.stderr).toEqual([EXIT.refused, 'CARRY: refused (RECEIPT_CARRY_PRODUCT_CHANGED)']); const m = eligible(ask.stderr); expect(m, ask.stderr).not.toBeNull(); - const rangeBase = /"range_base":"([0-9a-f]{40,64})"/.exec(ask.stderr)?.[1]; - expect(rangeBase).toBe(reviewedBase); const text = fs.readFileSync(m![3]!, 'utf8'); for (const s of ['var score0 := 2', 'was_vesting_clear', 'moved by the base', 'const SAVE_VERSION := 83', `range_base ${reviewedBase}`]) expect(text).toContain(s); - const record = { from, head, range_base: rangeBase, range_diff_sha256: m![2], reader: READER, verdict: 'clean' }; - const noBase = carry(['--recheck', recordAt(f, 'nobase.json', { ...record, range_base: undefined })]); - expect([noBase.status, noBase.stdout.includes('RECEIPT_CARRY_REFUSED'), noBase.stderr.includes('range_base')]).toEqual([EXIT.refused, true, true]); - const ok = carry(['--recheck', recordAt(f, 'recheck.json', record)]); - expect([ok.status, ok.stderr.slice(0, 600)]).toEqual([EXIT.ok, expect.any(String)]); - expect(ok.stdout).toContain(`scoped re-check by ${READER}`); - const reason = extractReceipt(fs.readFileSync(body, 'utf8')).receipt!.carry!.reason; - expect(reason).toContain(`scoped re-check by ${READER}`); - expect(reason).toContain(VESTING); - expect(reason).toContain(`range_base ${reviewedBase.slice(0, 12)}`); + const before = fs.readFileSync(body, 'utf8'); + const record = { from, head, range_base: reviewedBase, range_diff_sha256: m![2], reader: READER, verdict: 'clean' }; + const r = carry(['--recheck', recordAt(f, 'recheck.json', record)]); + expect([r.status, r.stderr.includes('--recheck is gone')]).toEqual([EXIT.refused, true]); + expect(fs.readFileSync(body, 'utf8')).toBe(before); }); test('past the size cap it refuses as before: RECEIPT_CARRY_PRODUCT_CHANGED, re-check not eligible', () => { diff --git a/test/size-ledger/ship/count-review-rounds-per-pr.json b/test/size-ledger/ship/count-review-rounds-per-pr.json new file mode 100644 index 000000000..312721105 --- /dev/null +++ b/test/size-ledger/ship/count-review-rounds-per-pr.json @@ -0,0 +1,4 @@ +{ + "bytes": 529, + "why": "GST-2673 F1+G1: a PR past two full rounds gets one read-only full review (review-army plan sentence)" +}