@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-issues/scripts/review-verdict.mjs

@@ -0,0 +1,509 @@
+#!/usr/bin/env node
+// Decide what follows a resolve-issues review round, from the reviewer's result file
+// alone, so a P2 can never send a PR back for fixes and a P3 is ignored: never deferred,
+// never filed, never checked.
+//
+//   review-verdict.mjs --review <run>/reviews/<unit>-r<N>.json --head <sha> [--base <ref>] [--decision <id>] [--exit-verdict]
+//   review-verdict.mjs --carry --review <run>/reviews/<unit>-r<N+1>.json --head <sha> --base <ref>
+//
+// --carry: a HEAD pushed after a passing review (a CI fix or a base update) gets no
+// reviewer. Run it in the unit's review clone with --head fetched. It writes the carry
+// record for --head, a skip with `carry: "after-pass"` that carries round N's approval and
+// records --head's merge-base and patch identity (so a later tier can anchor on it), and
+// exits 0; then run github-reviews.mjs merge and this verdict on it as on any round. Round N
+// is always the file just before it, and no later round may exist. It refuses (exit 3) when
+// round N did not pass: incomplete, a P0/P1 open, or a GitHub re-review awaited. Only a P0/P1
+// fix is reviewed. The verdict refuses a carry whose round is not its file's number.
+//
+// A skip record (`tier: "skip"`, written by better-review's rereview-scope.mjs
+// --write-skip) is not taken on its word: each skip back to the last real review must
+// carry the record just before it (same unit, previous round, complete, no open P0/P1,
+// same fixRound), walked by filename; and with --base, the scope script is run again
+// against the prior round and must still pick `skip` for --head. A carry record needs no
+// rerun: the chain alone shows the approval it carries.
+//
+// Prints a JSON verdict. The verdict is in the output (`verdict`: pass, fix, handback, wait,
+// decide, or review-again), and the exit code is 0 whenever the script ran and decided; 2 when
+// it could not (bad command, unreadable file). --exit-verdict restores the old verdict exit
+// codes below for one release (DEPRECATED: read `verdict` instead). Old exit codes:
+//   0  pass: no P0/P1 on --head (or a confirmed skip); record `reviewedHead`; ready
+//      once CI is green
+//   1  fix: the printed `fixBrief` file holds the P0/P1 findings only; it is
+//      the fix worker's whole finding list. `action` says how to fix, from a
+//      comparison with the previous round's file (`<unit>-r<N-1>.json` beside
+//      it, or --prior):
+//        fix         first blocking round: fix each finding's rule at its one
+//                    owner and close every row in its paths
+//        test-first  a P0/P1 came back after a fix: name the rule it breaks,
+//                    list every path that can break it, test each path, see
+//                    the tests fail, then fix until all pass, with the
+//                    escalation model
+//        one-by-one  only new P0/P1, introduced by the last fix: one finding
+//                    per fix worker, in turn, the smallest change that closes
+//                    every row at the rule's owner
+//   5  wait: no P0/P1 is open, but a GitHub reviewer whose changes request a fix brief
+//      already carried has not re-reviewed (`awaiting`, from github-reviews.mjs merge);
+//      request their re-review and run the merge and this verdict again when it lands
+//   6  decide: a recurring spec finding came back with the same trigger and the same open
+//      paths, so implementer and reviewer read the requirement differently
+//      (`reason: "spec-question"`). The printed `decide` file (`<unit>-r<N>.decide.json`)
+//      holds the question; answer it in the plan's `decisions` (`answers` names the file),
+//      then run this verdict again with --decision <that entry's id>: it writes a test-first
+//      fix brief that carries the decision. A changed trigger or new open paths is an
+//      incomplete fix, fixed test-first, never a question
+//   4  hand back: stop fixing. Two fix rounds passed without a new low of open P0/P1 path
+//      rows (`reason: "not-converging"`, read from every `<unit>-r<K>.json` before this one);
+//      hand back the PR and open findings
+//   2  bad command or unreadable file (still 2 without --exit-verdict)
+//   3  review-again: incomplete review (unfinished passes, an unresolved execution incident,
+//      no checks run, a P2 with neither a follow-up URL nor a dropbox id, a bad finding (a P0/P1
+//      needs trigger, rule, and paths with an open row), or another
+//      HEAD); finish the review after resolving any execution incident
+// Completion is checked first; the reviewer's verdict is ignored and only
+// P0/P1 findings decide whether a completed review needs product fixes. `gh-review-<n>` and
+// `gh-comment-<n>` findings come from github-reviews.mjs merge and block like the reviewer's,
+// on a skip record too, which carries only the reviewer's approval.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+import { execFileSync } from 'node:child_process'
+
+import { prPatchFingerprint, prPatchId, rereviewScope } from '../../better-review/scripts/rereview-scope.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { reviewCompletionProblems, reviewTier } from '../../engineering-runtime/scripts/review-completion.mjs'
+
+export const REVIEW_VERSION = 1
+export const BLOCKING = Object.freeze(['P0', 'P1'])
+export const DEFERRABLE = Object.freeze(['P2'])
+// Read and ignored: no dropbox entry, no follow-up issue, never in `deferred`.
+export const SKIPPED = Object.freeze(['P3'])
+// Fixes converge while the open P0/P1 path rows keep reaching new lows; STALLED_ROUNDS fix
+// rounds without a new low are not converging: stop and hand back. No fixed round cap.
+export const STALLED_ROUNDS = 2
+
+export class ReviewVerdictError extends Error {}
+
+// The reviewer, not the orchestrator, fixes an incomplete review.
+export class ReviewIncomplete extends ReviewVerdictError {}
+
+
+const isText = (value) => typeof value === 'string' && value.trim() !== ''
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const hasFixRound = (review) => Object.hasOwn(review ?? {}, 'fixRound')
+const isCounter = (value) => Number.isSafeInteger(value) && value >= 1
+// github-reviews.mjs merge owns these ids; only they may ride on a skip record.
+const GITHUB_ID = /^gh-(?:review|comment)-\d+$/
+// A skip record that carries a passing review to a HEAD pushed after it, whatever changed.
+export const AFTER_PASS = 'after-pass'
+const isCarry = (review) => reviewTier(review) === 'skip' && review?.carry === AFTER_PASS
+// A blocking finding names its rule and every path that must hold it, at least one open; a P0/P1
+// with every row closed is resolved and belongs out of the file. Checked on the current review
+// only, so earlier records written without the fields stay readable as priors.
+function blockingShapeProblems(f, label) {
+  const problems = []
+  if (!isText(f?.trigger)) problems.push(`${label} (P0/P1) has no trigger`)
+  if (!isText(f?.rule)) problems.push(`${label} (P0/P1) has no rule`)
+  if (!Array.isArray(f?.paths) || f.paths.length === 0) return [...problems, `${label} (P0/P1) has no paths rows`]
+  for (const [j, row] of f.paths.entries()) {
+    if (!isText(row?.path)) problems.push(`${label}.paths[${j}] has no path`)
+    if (!['open', 'closed'].includes(row?.status)) problems.push(`${label}.paths[${j}] status is ${JSON.stringify(row?.status)}, expected open or closed`)
+    else if (row.status === 'closed' && !isText(row?.evidence)) problems.push(`${label}.paths[${j}] is closed without evidence`)
+  }
+  if (!f.paths.some((row) => row?.status === 'open')) problems.push(`${label} (P0/P1) has no open paths row; a resolved finding is left out of the file`)
+  return problems
+}
+
+function checkReview(review, head, { requireCompletion = true, requireRulePaths = false } = {}) {
+  const problems = requireCompletion ? reviewCompletionProblems(review) : []
+  if (review?.version !== REVIEW_VERSION) problems.push(`review version is ${JSON.stringify(review?.version)}, expected ${REVIEW_VERSION}`)
+  if (!isText(review?.unit)) problems.push('review has no unit')
+  if (!isCounter(review?.round)) problems.push('review has no round (a safe integer from 1)')
+  if (hasFixRound(review) && (!isCounter(review.fixRound) || review.fixRound > review.round)) {
+    problems.push('review fixRound must be a positive safe integer no greater than round')
+  }
+  if (review?.head !== head) problems.push(`review is of HEAD ${JSON.stringify(review?.head)}, not ${head}`)
+
+  const findings = Array.isArray(review?.findings) ? review.findings : null
+  if (!findings) problems.push('review has no findings array (use [] for none)')
+  const ids = new Set()
+  for (const [i, f] of (findings ?? []).entries()) {
+    if (SKIPPED.includes(f?.severity)) continue
+    const label = isText(f?.id) ? f.id : `findings[${i}]`
+    if (!isText(f?.id)) problems.push(`${label} has no id`)
+    else if (ids.has(f.id)) problems.push(`duplicate finding id ${f.id}`)
+    else ids.add(f.id)
+    if (![...BLOCKING, ...DEFERRABLE].includes(f?.severity)) problems.push(`${label} has severity ${JSON.stringify(f?.severity)}, expected P0-P3`)
+    if (!isText(f?.summary)) problems.push(`${label} has no summary`)
+    if (requireRulePaths && BLOCKING.includes(f?.severity)) problems.push(...blockingShapeProblems(f, label))
+  }
+  return problems
+}
+
+// Blocking finding ids from the previous round's file, or null when there is none.
+function priorBlockingIds(prior) {
+  if (!isRecord(prior) || !Array.isArray(prior.findings)) return null
+  return new Set(prior.findings.filter((f) => BLOCKING.includes(f?.severity) && isText(f?.id)).map((f) => f.id))
+}
+
+// New counters need an identified immediate predecessor, not caller-authored cap relief.
+// Legacy records keep their attempt-based accounting, including when used as a prior.
+function effectiveFixRound(review, prior) {
+  if (!isCounter(review?.round)) throw new ReviewIncomplete('review round must be a positive safe integer')
+  const fixRound = hasFixRound(review) ? review.fixRound : review.round
+  if (!isCounter(fixRound) || fixRound > review.round) {
+    throw new ReviewIncomplete('review fixRound must be a positive safe integer no greater than round')
+  }
+  if (!hasFixRound(review) && !hasFixRound(prior)) return fixRound
+  if (prior === null || prior === undefined) {
+    if (fixRound !== review.round) throw new ReviewIncomplete('review fixRound cannot be lower than round without a prior review')
+    return fixRound
+  }
+  const problems = checkReview(prior, prior?.head, { requireCompletion: reviewTier(review) !== 'full' })
+  if (!isText(prior?.head)) problems.push('prior review has no HEAD')
+  if (prior?.unit !== review.unit) problems.push('prior review unit does not match current review')
+  if (prior?.round !== review.round - 1) problems.push('prior review round must immediately precede current round')
+  if (problems.length) throw new ReviewIncomplete(`invalid prior review for fixRound:\n- ${problems.join('\n- ')}`)
+  if (reviewCompletionProblems(prior).length > 0) {
+    const currentProblems = reviewCompletionProblems(review, { requirePasses: true })
+    if (currentProblems.length) throw new ReviewIncomplete(`full retry must complete every pass:\n- ${currentProblems.join('\n- ')}`)
+  }
+  const priorRound = hasFixRound(prior) ? prior.fixRound : prior.round
+  const expected = priorRound + (reviewCompletionProblems(prior).length === 0 && priorBlockingIds(prior).size > 0 ? 1 : 0)
+  if (fixRound !== expected) throw new ReviewIncomplete(`review fixRound is ${fixRound}, expected ${expected} from prior review`)
+  return expected
+}
+
+const openPaths = (f) => (Array.isArray(f?.paths) ? f.paths : []).filter((row) => row?.status === 'open').map((row) => String(row.path)).sort().join('\n')
+function sameOpenPaths(finding, prior) {
+  const before = prior.findings.find((f) => f?.id === finding.id)
+  return openPaths(before) === openPaths(finding)
+}
+const squash = (text) => String(text ?? '').trim().replace(/\s+/g, ' ')
+function sameTrigger(finding, prior) {
+  const before = prior.findings.find((f) => f?.id === finding.id)
+  return squash(before?.trigger) === squash(finding.trigger)
+}
+// What the decide file asks: the finding's requirement as the reviewer reads it.
+const questionOf = ({ id, summary, rule, trigger, specReference, requestedAction }) => ({ id, summary, rule, trigger, specReference, requestedAction })
+
+// The work a fix still owes: open path rows across P0/P1 findings.
+export function openBlockingRows(review) {
+  return (Array.isArray(review?.findings) ? review.findings : [])
+    .filter((f) => BLOCKING.includes(f?.severity))
+    .reduce((n, f) => n + (Array.isArray(f.paths) ? f.paths.filter((row) => row?.status === 'open').length : 0), 0)
+}
+
+// Rounds since the last new low of open P0/P1 path rows, over this blocking loop: the completed
+// records after the last completed pass, oldest first, ending with `review`. Incomplete records
+// are passed over, never counted as progress; a record with a P0/P1 that has no `paths` (legacy)
+// cannot be measured and is left out. Lows only fall and never go below 0, so a loop that hands
+// back at 2 rounds without a new low always ends, whatever the counts do between lows.
+export function roundsWithoutNewLow(review, history = []) {
+  const done = [...history, review].filter((r) => isRecord(r) && Array.isArray(r.findings) && reviewCompletionProblems(r).length === 0)
+  const lastPass = done.findLastIndex((r) => !r.findings.some((f) => BLOCKING.includes(f?.severity)))
+  const loop = done.slice(lastPass + 1).filter((r) => r.findings.every((f) => !BLOCKING.includes(f?.severity) || Array.isArray(f.paths)))
+  let low = Infinity
+  let since = 0
+  for (const r of loop) {
+    const rows = openBlockingRows(r)
+    if (rows < low) { low = rows; since = 0 } else since++
+  }
+  return since
+}
+
+// How to act on a blocking round. better-review keeps a still-open finding's id across
+// rounds, so a shared id means the last fix did not resolve it.
+// `history` is every record before `prior`, oldest first, or a function that reads them; it is
+// read only after the counters check out.
+// `decision` is the id of the plan's `decisions` entry that answered this round's question:
+// the fix it starts is new work, so this verdict skips the stall guard; later rounds count as usual.
+export function fixAction(review, blocking, prior = null, history = [], { decision = null } = {}) {
+  effectiveFixRound(review, prior)
+  const earlier = typeof history === 'function' ? history() : history
+  if (!decision && roundsWithoutNewLow(review, [...earlier, prior]) >= STALLED_ROUNDS) return { verdict: 'handback', reason: 'not-converging' }
+  const before = review.round > 1 && reviewCompletionProblems(prior).length === 0 ? priorBlockingIds(prior) : null
+  if (!before || before.size === 0) return { verdict: 'fix', action: 'fix', recurring: [], introduced: [] }
+  const recurring = blocking.filter((f) => before.has(f.id)).map((f) => f.id)
+  const introduced = blocking.filter((f) => !before.has(f.id)).map((f) => f.id)
+  // A recurring spec finding is a question only when nothing about it moved: the same trigger
+  // fails on the same open paths, so the fix and the review read the requirement differently.
+  // A new trigger on the same line, or new open paths, is an incomplete fix.
+  const questions = blocking.filter((f) => before.has(f.id) && f.pass === 'spec' && sameOpenPaths(f, prior) && sameTrigger(f, prior))
+  if (questions.length && !decision) return { verdict: 'decide', reason: 'spec-question', question: questions.map(questionOf), recurring, introduced }
+  if (questions.length) return { verdict: 'fix', action: 'test-first', decision, recurring, introduced }
+  if (recurring.length > 0) return { verdict: 'fix', action: 'test-first', recurring, introduced }
+  return { verdict: 'fix', action: 'one-by-one', recurring, introduced }
+}
+
+// One link of a skip chain: `link` must carry the record just before it, which is
+// complete, of the same unit and the previous round, and left no P0/P1 open.
+function skipLinkProblems(link, before) {
+  if (!isRecord(before)) return ['the review it carries is missing']
+  const problems = reviewCompletionProblems(before, { requirePasses: true }).map((p) => `the review it carries: ${p}`)
+  if (link.carriedFrom !== before.head) problems.push(`it carries ${JSON.stringify(link.carriedFrom)}, but the review before it is of ${JSON.stringify(before.head)}`)
+  if (before.unit !== link.unit) problems.push('its unit differs from the review it carries')
+  if (before.round !== link.round - 1) problems.push('its round does not follow the review it carries')
+  if (!Array.isArray(before.findings)) problems.push('the review it carries has no findings array')
+  else if (before.findings.some((f) => BLOCKING.includes(f?.severity))) problems.push('the review it carries has an open P0/P1')
+  const beforeFixRound = hasFixRound(before) ? before.fixRound : before.round
+  if (link.fixRound !== beforeFixRound) problems.push(`its fixRound is ${JSON.stringify(link.fixRound)}, expected ${beforeFixRound}`)
+  return problems
+}
+
+// A skip carries an approval only when every link back to a real review holds, and the
+// scope script, rerun now, still picks skip. `chain` is the previous record, then the
+// ones before it, newest first; `confirmSkip()` returns the rerun's { tier, reasons }.
+function checkSkip(review, chain, confirmSkip) {
+  let link = review
+  for (const [i, before] of [...chain, undefined].entries()) {
+    if (i > 0) {
+      const own = checkReview(link, link.head)
+      if (own.length) throw new ReviewIncomplete(`skip chain: round ${link.round} is not a valid record; spawn the reviewer:\n- ${own.join('\n- ')}`)
+    }
+    const problems = skipLinkProblems(link, before)
+    if (problems.length) throw new ReviewIncomplete(`skip record does not hold: round ${link.round}: ${problems.join('; ')}; spawn the reviewer`)
+    if (reviewTier(before) !== 'skip') break
+    link = before
+  }
+  if (isCarry(review)) return
+  if (typeof confirmSkip !== 'function') throw new ReviewVerdictError('--base is required to confirm a skip record')
+  const rerun = confirmSkip()
+  if (rerun?.tier !== 'skip') {
+    throw new ReviewIncomplete(`skip record does not hold: the scope script picks ${JSON.stringify(rerun?.tier)} for this HEAD; spawn the reviewer${rerun?.reasons?.length ? `:\n- ${rerun.reasons.join('\n- ')}` : ''}`)
+  }
+}
+
+export function reviewVerdict(review, head, prior = null, { confirmSkip, earlier = [], history = [], decision = null } = {}) {
+  if (!isText(head)) throw new ReviewVerdictError('--head is required')
+  const problems = checkReview(review, head, { requireRulePaths: true })
+  if (problems.length) throw new ReviewIncomplete(`incomplete review; spawn the reviewer again only after resolving any execution incident:\n- ${problems.join('\n- ')}`)
+  const skip = reviewTier(review) === 'skip'
+  if (skip) checkSkip(review, [prior, ...earlier], confirmSkip)
+
+  const fixRound = effectiveFixRound(review, prior)
+  const blocking = review.findings.filter((f) => BLOCKING.includes(f.severity))
+  const deferred = review.findings
+    .filter((f) => DEFERRABLE.includes(f.severity))
+    .map(({ id, severity, summary, followUpUrl, dropboxId }) => ({ id, severity, summary, followUpUrl, dropboxId }))
+  const awaiting = Array.isArray(review.external?.awaiting) ? review.external.awaiting : []
+  const base = { unit: review.unit, round: review.round, fixRound, head, commands: review.commands, deferred, ...(awaiting.length ? { awaiting } : {}) }
+  const skipped = skip ? { tier: 'skip', carriedFrom: review.carriedFrom } : {}
+  if (blocking.length === 0) {
+    return awaiting.length ? { verdict: 'wait', ...base, ...skipped } : { verdict: 'pass', reviewedHead: head, ...base, ...skipped }
+  }
+  if (skip && blocking.some((f) => !GITHUB_ID.test(String(f.id)))) throw new ReviewIncomplete('a skip record cannot hold findings; spawn the reviewer')
+  return { ...fixAction(review, blocking, prior, history, { decision }), ...base, fix: blocking }
+}
+
+// The record --carry writes for `head`: the previous round's approval, carried with no
+// reviewer. The previous round must have passed: complete, every pass done, no P0/P1, and no
+// GitHub re-review awaited.
+// `identity` is --head's { mergeBase, patchId, patchFingerprint }.
+export function carryRecord(prior, head, identity = {}) {
+  if (!isText(head)) throw new ReviewVerdictError('--head is required')
+  if (!isRecord(prior)) throw new ReviewIncomplete('no previous round to carry; spawn the reviewer')
+  const problems = [...new Set([...checkReview(prior, prior.head), ...reviewCompletionProblems(prior, { requirePasses: true })])]
+  if (!isText(prior.head)) problems.push('it has no head')
+  if (prior.complete !== true) problems.push('it is not marked complete')
+  if (Array.isArray(prior.findings) && prior.findings.some((f) => BLOCKING.includes(f?.severity))) problems.push('it has an open P0/P1')
+  if (Array.isArray(prior.external?.awaiting) && prior.external.awaiting.length > 0) problems.push('it awaits a GitHub re-review')
+  if (prior.head === head) problems.push(`it is already of ${head}`)
+  if (problems.length) throw new ReviewIncomplete(`round ${prior.round} did not pass, so ${head} cannot carry it; review it:\n- ${problems.join('\n- ')}`)
+  return {
+    version: prior.version,
+    unit: prior.unit,
+    round: prior.round + 1,
+    fixRound: hasFixRound(prior) ? prior.fixRound : prior.round,
+    head,
+    ...identity,
+    tier: 'skip',
+    carry: AFTER_PASS,
+    carriedFrom: prior.head,
+    ...(Number.isInteger(prior.fixLinesSinceFull) ? { fixLinesSinceFull: prior.fixLinesSinceFull } : {}),
+    oversize: false,
+    complete: true,
+    passes: prior.passes,
+    commands: [],
+    sweeps: prior.sweeps ?? [],
+    boundaries: prior.boundaries ?? [],
+    findings: [],
+  }
+}
+
+const INSTRUCTIONS = {
+  'fix': 'Fix only these findings. For each, fix its `rule` at the one place every path passes through, never by copying a guard to each path, and close every row in its `paths`.',
+  'test-first': 'The findings listed in `recurring` survived a fix: the last fix closed one path and missed others. For each, before changing code: name the rule the bug breaks; list every code path that can break it, including the trigger of this finding id in each earlier round\'s review file beside this one; write a test per path from its trigger and run them: see it fail on each open path. Then fix the rule at its one owner, the place every path passes through, not path by path, until every test passes. "Fixed" is every path\'s test passing. Fix the rest as usual.',
+  'one-by-one': 'The last fix introduced these findings. Fix them one at a time, one fix worker each, with the smallest change that closes every row of its `paths` at the rule\'s owner; touch nothing else.',
+}
+
+// The fix worker's brief carries only P0/P1 findings; P2/P3 never reach it.
+export function fixBriefOf(result) {
+  const fixRound = hasFixRound(result) ? result.fixRound : result.round
+  if (!isCounter(result.round) || !isCounter(fixRound) || fixRound > result.round) {
+    throw new ReviewIncomplete('fix brief round and fixRound must be positive safe integers with fixRound no greater than round')
+  }
+  return {
+    unit: result.unit,
+    round: result.round,
+    fixRound,
+    head: result.head,
+    action: result.action,
+    instruction: `${INSTRUCTIONS[result.action]}${result.decision ? ` Decision ${result.decision} in the plan's \`decisions\` settles what the recurring spec finding requires: fix it as that decision reads.` : ''} Every other finding is out of scope: a P2 is deferred to the dropbox or a follow-up issue, and a P3 is skipped.`,
+    ...(result.decision ? { decision: result.decision } : {}),
+    recurring: result.recurring,
+    fix: result.fix,
+  }
+}
+
+const USAGE = 'usage: review-verdict.mjs --review <reviews/<unit>-r<N>.json> --head <sha> [--prior <reviews/<unit>-r<N-1>.json>] [--base <ref> (required for a scope-script skip record)] [--decision <decisions id>]\n       review-verdict.mjs --carry --review <reviews/<unit>-r<N+1>.json> --head <sha> --base <ref>'
+
+const ROUND_FILE = /^(.*-r)(\d+)\.json$/
+// The round a review file's name gives it, or null when the name has none.
+const roundOfFile = (path) => { const m = basename(path).match(ROUND_FILE); return m ? Number(m[2]) : null }
+
+function parseArgs(argv) {
+  const opts = {}
+  for (let i = 0; i < argv.length; i += 2) {
+    if (argv[i] === '--carry') { opts.carry = true; i--; continue }
+    if (argv[i] === '--exit-verdict') { opts.exitVerdict = true; i--; continue }
+    if (argv[i] === '--json') { i--; continue } // the output is always JSON
+    if (!argv[i]?.startsWith('--') || argv[i + 1] === undefined) throw new ReviewVerdictError(USAGE)
+    opts[argv[i].slice(2)] = argv[i + 1]
+  }
+  if (!opts.review || !opts.head) throw new ReviewVerdictError(USAGE)
+  return opts
+}
+
+function readJson(path) {
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (error) {
+    throw new ReviewVerdictError(`cannot read ${path}: ${error.message}`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new ReviewIncomplete(`incomplete review; spawn the reviewer again:\n- ${path} is not JSON: ${error.message}`)
+  }
+}
+
+// The records before a skip prior, newest first, by filename, back to the first non-skip.
+// A chain that cannot be walked stays short, and the skip check then fails closed.
+function readEarlier(opts, prior) {
+  const path = opts.prior ?? opts.review
+  const m = basename(path).match(/^(.*-r)(\d+)\.json$/)
+  if (!m) return []
+  const out = []
+  let current = prior
+  let n = Number(m[2]) - (opts.prior ? 1 : 2)
+  while (reviewTier(current) === 'skip' && n >= 1) {
+    try { current = JSON.parse(readFileSync(join(dirname(path), `${m[1]}${n}.json`), 'utf8')) } catch { break }
+    out.push(current)
+    n--
+  }
+  return out
+}
+
+// Legacy unreadable priors remain optional. New counters must not silently discard
+// a supplied or malformed prior; a missing inferred file still means no evidence.
+function readPrior(opts, review) {
+  let path = opts.prior
+  if (!path) {
+    const m = basename(opts.review).match(/^(.*-r)(\d+)\.json$/)
+    if (!m || Number(m[2]) < 2) return null
+    path = join(dirname(opts.review), `${m[1]}${Number(m[2]) - 1}.json`)
+  }
+  try {
+    const prior = JSON.parse(readFileSync(path, 'utf8'))
+    if (hasFixRound(review) && !isRecord(prior)) throw new ReviewIncomplete('prior review must be an object')
+    return prior
+  } catch (error) {
+    if (hasFixRound(review) && (opts.prior || error.code !== 'ENOENT')) {
+      throw new ReviewIncomplete(`cannot use prior review for fixRound at ${path}: ${error.message}`)
+    }
+    return null
+  }
+}
+
+// Every record before the prior, oldest first, for the stall guard: `<unit>-r1.json` up to the
+// one before the prior, beside the prior (or the review). Fails closed: the guard cannot be
+// skipped by a missing file or a name it cannot number.
+function readHistory(opts, review) {
+  const from = opts.prior ?? opts.review
+  const m = basename(from).match(/^(.*-r)(\d+)\.json$/)
+  const last = m && Number(m[2]) - (opts.prior ? 1 : 2)
+  if (!m) {
+    if (isCounter(review?.round) && review.round >= 3) {
+      throw new ReviewIncomplete(`cannot number earlier reviews from ${from}; name review files <unit>-r<N>.json so the stall guard can read every round`)
+    }
+    return []
+  }
+  const out = []
+  for (let n = 1; n <= last; n++) {
+    const path = join(dirname(from), `${m[1]}${m[2].startsWith('0') ? String(n).padStart(m[2].length, '0') : n}.json`)
+    try { out.push(JSON.parse(readFileSync(path, 'utf8'))) } catch (error) {
+      throw new ReviewIncomplete(`cannot read earlier review ${path} for the stall guard: ${error.message}`)
+    }
+  }
+  return out
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseArgs(process.argv.slice(2))
+    if (opts.carry) {
+      const n = roundOfFile(opts.review)
+      if (n === null || n < 2) throw new ReviewVerdictError(`--carry needs --review named <unit>-r<N>.json with N from 2: ${opts.review}`)
+      if (opts.prior) throw new ReviewVerdictError('--carry always carries the round just before --review; drop --prior')
+      if (!opts.base) throw new ReviewVerdictError('--carry needs --base <review base> to record the merge-base')
+      if (existsSync(opts.review)) throw new ReviewVerdictError(`${opts.review} exists; carry writes a new round`)
+      const stem = basename(opts.review).match(ROUND_FILE)[1]
+      const later = readdirSync(dirname(opts.review)).find((name) => name.startsWith(stem) && roundOfFile(name) > n)
+      if (later) throw new ReviewVerdictError(`${later} exists; carry only the newest round`)
+      const prior = readPrior(opts, { fixRound: 1 })
+      if (isRecord(prior) && prior.round !== n - 1) throw new ReviewIncomplete(`the round before ${basename(opts.review)} records round ${prior.round}, not ${n - 1}; review it`)
+      carryRecord(prior, opts.head) // refuse a round that did not pass before touching git
+      const git = (args) => execFileSync('git', args, { encoding: 'utf8' }).trim()
+      let identity
+      try {
+        const mergeBase = git(['merge-base', opts.base, opts.head])
+        identity = { mergeBase, patchId: prPatchId(mergeBase, opts.head), patchFingerprint: prPatchFingerprint(mergeBase, opts.head) }
+      } catch (error) {
+        throw new ReviewVerdictError(`cannot read ${opts.head} against ${opts.base} here; run --carry in the unit's review clone with both fetched: ${String(error.stderr || error.message).trim()}`)
+      }
+      const record = carryRecord(prior, opts.head, identity)
+      writeFileSync(opts.review, `${JSON.stringify(record, null, 2)}\n`)
+      process.stdout.write(`${JSON.stringify({ carried: opts.review, round: record.round, carriedFrom: record.carriedFrom, head: record.head }, null, 2)}\n`)
+    } else {
+      const review = readJson(opts.review)
+      const n = roundOfFile(opts.review)
+      if (isCarry(review) && n !== review.round) throw new ReviewIncomplete(`carry record ${opts.review} records round ${JSON.stringify(review.round)}, not its file's ${n}; review it`)
+      const prior = readPrior(opts, review)
+      const confirmSkip = opts.base ? () => rereviewScope({ prior, base: opts.base, head: opts.head }) : undefined
+      const earlier = reviewTier(review) === 'skip' ? readEarlier(opts, prior) : []
+      const history = () => readHistory(opts, review)
+      const result = reviewVerdict(review, opts.head, prior, { confirmSkip, earlier, history, decision: opts.decision ?? null })
+      if (result.verdict === 'fix') {
+        result.fixBrief = join(dirname(opts.review), `${basename(opts.review, '.json')}.fix.json`)
+        writeFileSync(result.fixBrief, `${JSON.stringify(fixBriefOf(result), null, 2)}\n`)
+      }
+      if (result.verdict === 'decide') {
+        result.decide = join(dirname(opts.review), `${basename(opts.review, '.json')}.decide.json`)
+        writeFileSync(result.decide, `${JSON.stringify({ unit: result.unit, round: result.round, head: result.head, reason: result.reason, question: result.question }, null, 2)}\n`)
+      }
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+      process.exitCode = opts.exitVerdict ? { pass: 0, fix: 1, handback: 4, wait: 5, decide: 6 }[result.verdict] : 0
+    }
+  } catch (error) {
+    if (error instanceof ReviewIncomplete) {
+      // An incomplete review is an answer (review again), not a failure of the script.
+      process.stdout.write(`${JSON.stringify({ verdict: 'review-again', reason: error.message }, null, 2)}\n`)
+      process.exitCode = process.argv.includes('--exit-verdict') ? 3 : 0
+    } else {
+      process.stderr.write(`${error instanceof ReviewVerdictError ? error.message : error.stack}\n`)
+      process.exitCode = 2
+    }
+  }
+}