@joshuafolkken/kit 1.872.0

package/scripts/review/review-findings-cli.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger, type CategoryCount } from './review-finding-ledger'
+
+// `josh review:findings` — the reader over the review-finding ledger (joshuafolkken/kit#2325). It
+// prints each recurring category's count, most frequent first, and the number of rounds that recorded
+// zero findings — the denominator that tells a genuinely quiet category apart from one nobody looked
+// at. The write half is `pnpm josh review:record`; both read one grammar from `review-finding-ledger`.
+
+const NO_FINDINGS = 'no review findings recorded yet'
+
+function count_line(entry: CategoryCount): string {
+	return `  ${entry.category}: ${String(entry.count)}`
+}
+
+function zero_line(zero_rounds: number): string {
+	return `zero-finding rounds recorded: ${String(zero_rounds)}`
+}
+
+function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number): string {
+	if (counts.length === 0) {
+		return zero_rounds === 0 ? NO_FINDINGS : zero_line(zero_rounds)
+	}
+
+	const body = counts.map((entry) => count_line(entry)).join('\n')
+
+	return `findings by category:\n${body}\n${zero_line(zero_rounds)}`
+}
+
+async function read_ledger(ledger_path: string): Promise<string> {
+	try {
+		return await readFile(ledger_path, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+async function run(ledger_path: string = observation_ledger_home.ledger_path()): Promise<number> {
+	const content = await read_ledger(ledger_path)
+	const counts = review_finding_ledger.category_counts(content)
+
+	console.info(format_report(counts, review_finding_ledger.zero_round_count(content)))
+
+	return 0
+}
+
+async function main(): Promise<void> {
+	process.exitCode = await run()
+}
+
+const review_findings_cli = { NO_FINDINGS, format_report, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { review_findings_cli }

package/scripts/review/review-level.ts

@@ -0,0 +1,86 @@
+// Which `/code-review` level a change is reviewed at, decided from the changed paths alone
+// (joshuafolkken/kit#966).
+//
+// **The decision takes no judgement.** "This one is small" is a judgement made under cost pressure,
+// and cost pressure resolves it toward "small" exactly when a defect is most likely to be shipped —
+// the same reason the cross-package interrupt removed its own "does this block?" evaluation. So the
+// input is the list of changed paths and nothing else.
+
+type ReviewLevel = 'low' | 'medium'
+
+const DEFAULT_LEVEL: ReviewLevel = 'medium'
+const REDUCED_LEVEL: ReviewLevel = 'low'
+
+// Paths that neither execute, nor instruct, nor ship. A defect in one of these cannot change what
+// any program does, cannot change what an agent does, and cannot reach a consumer — the three ways
+// a defect in this repository escapes. Everything else, including every markdown file not named
+// here, is reviewed at the default level.
+//
+// **Being distributed is disqualifying on its own**, which is why `.vscode/**`, `.gitattributes`
+// and `.prettierignore` are *not* here despite looking inert: `package.json`'s `files` ships all
+// three, and `josh init` / `josh sync` write them into every consumer project. Keeping them out is
+// the same criterion that keeps documentation out, applied consistently.
+//
+// **Documentation is deliberately absent from this list**, which is the opposite of what the
+// "Non-runtime updates" testing exception does with it, and the difference is not an oversight.
+// That exception is about whether an automated test could have caught the defect; this is about
+// whether a human reading the diff is the only thing that can. Measured on this epic:
+// joshuafolkken/kit#963 and #965 were both documentation-only by that classification, and a
+// `medium` review found ten real defects in each — dangling pointers into sections that had been
+// removed, and citations naming the wrong file, in artifacts distributed to every consumer. No test
+// covered them, because prose is what they were.
+const INERT_PATHS: ReadonlyArray<string> = [
+	'.editorconfig',
+	'.gitignore',
+	'CHANGELOG.md',
+	'LICENSE',
+]
+
+// No directory is inert today. The constant stays because the check reads it, and because the next
+// candidate will arrive as a directory — but an empty list is the honest answer right now.
+const INERT_PREFIXES: ReadonlyArray<string> = []
+const INERT_SUFFIXES: ReadonlyArray<string> = ['.code-workspace']
+
+function is_inert(path: string): boolean {
+	const normalized = path.trim()
+
+	return (
+		INERT_PATHS.includes(normalized) ||
+		INERT_PREFIXES.some((prefix) => normalized.startsWith(prefix)) ||
+		INERT_SUFFIXES.some((suffix) => normalized.endsWith(suffix))
+	)
+}
+
+// The reduced level applies only when **every** changed path is inert. One executable or
+// instruction file in the diff and the whole change is reviewed at the default level: a review
+// reads the change, not a subset of it, so a per-file level would mean reviewing part of a diff.
+//
+// An empty diff also takes the default. There is nothing to review, so the level does not matter —
+// and answering `low` to "no files changed" would let a caller that failed to read the diff receive
+// a reduced level as though it had.
+function level_for(paths: ReadonlyArray<string>): ReviewLevel {
+	const changed = paths.map((path) => path.trim()).filter((path) => path !== '')
+
+	if (changed.length === 0) return DEFAULT_LEVEL
+
+	return changed.every((path) => is_inert(path)) ? REDUCED_LEVEL : DEFAULT_LEVEL
+}
+
+// The paths that forced the default level, so the answer can say why rather than only what.
+function deciding_paths(paths: ReadonlyArray<string>): Array<string> {
+	return paths.map((path) => path.trim()).filter((path) => path !== '' && !is_inert(path))
+}
+
+const review_level = {
+	DEFAULT_LEVEL,
+	REDUCED_LEVEL,
+	INERT_PATHS,
+	INERT_PREFIXES,
+	INERT_SUFFIXES,
+	is_inert,
+	level_for,
+	deciding_paths,
+}
+
+export type { ReviewLevel }
+export { review_level }

package/scripts/review/review-record-cli.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env tsx
+import { appendFile, mkdir } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger, type Finding } from './review-finding-ledger'
+import { review_record, type RecordVerdict } from './review-record'
+
+// `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
+// `/code-review` round's findings (joshuafolkken/kit#2325). It appends a `- rf:` line per finding to
+// the observation ledger, which `pnpm josh observations:flush` then commits like any other ledger
+// change. **A call with no findings is a zero-finding round, and it still writes one line** — so the
+// round that found nothing is recorded rather than mistaken for a round nobody reviewed.
+//
+// `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
+// merges (joshuafolkken/kit#2343): `ok` / `not-required` exit zero, `missing` exits non-zero so the
+// merge is refused until the round is recorded. It mirrors `josh review:attest --check`.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const DATE_END = 10
+const USAGE =
+	'Usage: josh review:record --issue <N> [<category>:<severity>:<file> ...] | josh review:record --check --issue <N>'
+const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
+const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
+const NOT_REQUIRED_LINE =
+	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
+const ISSUE_PATTERN = /^[1-9]\d*$/u
+const OPTIONS = { issue: { type: 'string' }, check: { type: 'boolean' } } as const
+
+interface Request {
+	issue: number
+	findings: ReadonlyArray<Finding>
+}
+
+interface Parsed {
+	check: boolean
+	issue: string | undefined
+	positionals: ReadonlyArray<string>
+}
+
+// A finding spec is `<category>:<severity>:<file>`; the file field keeps any `:line` a citation
+// carries, so only the first two colons separate fields.
+function to_finding(category: string, severity: string, file: string): Finding | undefined {
+	if (!review_finding_ledger.is_category(category)) return undefined
+	if (!review_finding_ledger.is_severity(severity)) return undefined
+
+	return review_finding_ledger.is_valid_file(file) ? { category, severity, file } : undefined
+}
+
+function parse_finding(spec: string): Finding | undefined {
+	const first = spec.indexOf(':')
+	const second = spec.indexOf(':', first + 1)
+
+	if (first === -1 || second === -1) return undefined
+
+	return to_finding(spec.slice(0, first), spec.slice(first + 1, second), spec.slice(second + 1))
+}
+
+function parse_findings(specs: ReadonlyArray<string>): ReadonlyArray<Finding> | undefined {
+	const findings: Array<Finding> = []
+
+	for (const spec of specs) {
+		const finding = parse_finding(spec)
+
+		if (finding === undefined) return undefined
+
+		findings.push(finding)
+	}
+
+	return findings
+}
+
+function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
+	try {
+		const parsed = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			strict: true,
+			allowPositionals: true,
+		})
+
+		return {
+			check: parsed.values.check === true,
+			issue: parsed.values.issue,
+			positionals: parsed.positionals,
+		}
+	} catch {
+		return undefined
+	}
+}
+
+function to_request(parsed: Parsed): Request | undefined {
+	const { issue } = parsed
+
+	if (issue === undefined || !ISSUE_PATTERN.test(issue)) return undefined
+
+	const findings = parse_findings(parsed.positionals)
+
+	return findings === undefined ? undefined : { issue: Number(issue), findings }
+}
+
+function today(now: Date): string {
+	return now.toISOString().slice(0, DATE_END)
+}
+
+function build_lines(request: Request, date: string): ReadonlyArray<string> {
+	if (request.findings.length === 0) {
+		return [review_finding_ledger.zero_round_line(date, request.issue)]
+	}
+
+	return request.findings.map((finding) =>
+		review_finding_ledger.finding_line(finding, date, request.issue),
+	)
+}
+
+function confirmation(count: number, ledger_path: string): string {
+	return `Recorded ${String(count)} review-finding line(s) in ${ledger_path}.`
+}
+
+function check_line(verdict: RecordVerdict): string {
+	return verdict.status === 'ok' ? RECORDED_LINE : NOT_REQUIRED_LINE
+}
+
+async function run_check(issue: string | undefined, ledger_path: string): Promise<number> {
+	if (issue === undefined || !ISSUE_PATTERN.test(issue)) {
+		console.error(CHECK_USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const verdict = await review_record.check(Number(issue), ledger_path)
+
+	if (verdict.status === 'ok' || verdict.status === 'not-required') {
+		console.info(check_line(verdict))
+
+		return 0
+	}
+
+	console.error(review_record.refusal_message(Number(issue)))
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run_record(parsed: Parsed, now: Date, ledger_path: string): Promise<number> {
+	const request = to_request(parsed)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const lines = build_lines(request, today(now))
+
+	// A consumer that does not keep the observation ledger has no `docs/` at its root, so the append
+	// below would fail with ENOENT and leave the merge gate unsatisfiable (joshuafolkken/kit#2402).
+	// Creating the parent first is the one write path that can bring the ledger into existence there.
+	await mkdir(path.dirname(ledger_path), { recursive: true })
+	await appendFile(ledger_path, `${lines.join('\n')}\n`, 'utf8')
+	console.info(confirmation(lines.length, ledger_path))
+
+	return 0
+}
+
+// **The default is the primary checkout's ledger, even inside a lane** (joshuafolkken/kit#2419). A line
+// appended to a lane's own copy never reached the default branch — the lane's flush is refused and
+// `lane:close` does not carry the file — while `--check` read that same copy and let the merge through.
+async function run(
+	argv: ReadonlyArray<string>,
+	now: Date,
+	ledger_path: string = observation_ledger_home.ledger_path(),
+): Promise<number> {
+	const parsed = parse_argv(argv)
+
+	if (parsed === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (parsed.check) return await run_check(parsed.issue, ledger_path)
+
+	return await run_record(parsed, now, ledger_path)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv, new Date())
+}
+
+const review_record_cli = { USAGE, build_lines, parse_finding, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { review_record_cli }

package/scripts/review/review-record.ts

@@ -0,0 +1,74 @@
+import { readFile } from 'node:fs/promises'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// The gate that refuses a merge until the `/code-review` round was recorded (joshuafolkken/kit#2343).
+//
+// **The instruction was prose, and prose failed.** `review:record` is the one write path for a
+// round's findings (joshuafolkken/kit#2325), but nothing enforced the call — so across eleven merges
+// after the instruction landed, it was never run once, and the recurrence ledger stayed blind. This
+// module is the mechanical counterpart to `review-attest`'s `--check`, keyed on the issue rather than
+// on a checkout: a round that left no `- rf:` line for its issue is treated as no review at all.
+//
+// **The three verdicts mirror the attestation gate's, and for the same reason.**
+//
+// - **`ok`** — the ledger holds at least one finding line for the issue, a zero-finding `none` line
+//   included. The round was recorded; the merge proceeds.
+// - **`missing`** — the ledger is present but carries no line for the issue. Absence is a refusal, not
+//   a pass: the defect this gate exists for produced *no* line, so reading silence as success would
+//   leave the hole open in the one shape it takes.
+// - **`not-required`** — the ledger file itself is absent. A consumer repository that does not keep
+//   the observation ledger never ran `review:record`, and blocking its merges would refuse the
+//   population this gate is not about. So a missing file carries on, exactly as `review-attest`'s
+//   `not-required` does for a checkout that briefed no review.
+
+type RecordStatus = 'ok' | 'missing' | 'not-required'
+
+interface RecordVerdict {
+	status: RecordStatus
+	issue?: number
+}
+
+// `undefined` for both "the file is absent" and "the file could not be read" — they are the same
+// answer here, a ledger this checkout does not keep, and the caller turns that into `not-required`.
+async function read_ledger(ledger_path: string): Promise<string | undefined> {
+	try {
+		return await readFile(ledger_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+// The default is the primary checkout's ledger, the one `review:record` writes from a lane
+// (joshuafolkken/kit#2419) — a cwd-relative default read the lane's copy, so the followup gate refused
+// every round recorded from a lane (joshuafolkken/kit#2431).
+async function check(
+	issue: number,
+	ledger_path: string = observation_ledger_home.ledger_path(),
+): Promise<RecordVerdict> {
+	const content = await read_ledger(ledger_path)
+
+	if (content === undefined) return { status: 'not-required' }
+	if (review_finding_ledger.has_issue_record(content, issue)) return { status: 'ok', issue }
+
+	return { status: 'missing', issue }
+}
+
+const MISSING_REASON =
+	'No review round is recorded for this issue, so there is no evidence `/code-review` ran. A round whose findings are never recorded leaves the recurrence ledger blind, which is indistinguishable from a round nobody reviewed — so an unrecorded round is refused (joshuafolkken/kit#2343).'
+
+const REMEDY =
+	'Record the round with `pnpm josh review:record --issue <N> [<category>:<severity>:<file> ...]` — a clean round is a call with no findings, which records one zero-finding line — then reissue the merge.'
+
+function refusal_message(issue: number): string {
+	return [MISSING_REASON, `Issue: #${String(issue)}`, REMEDY].join('\n')
+}
+
+const review_record = {
+	MISSING_REASON,
+	check,
+	refusal_message,
+}
+
+export type { RecordVerdict }
+export { review_record }

package/scripts/review/review-round2-cli.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { change_base } from '#scripts/git/change-base'
+import { path_decision } from '#scripts/josh/path-decision'
+import { review_round2 } from './review-round2'
+import { review_stamps } from './review-stamps'
+import { review_tree } from './review-tree'
+
+// `josh review:round2` — say whether the second review round is due (joshuafolkken/kit#1433).
+//
+// A command rather than a paragraph in `prompts/review.md`, for the reason `josh review:level` is a
+// command: a rule an agent applies from memory is a rule an agent can talk
+// itself out of, and this one is argued against every time it is reached, because the round it asks
+// for costs a forked agent and a few minutes. The question and the evidence behind the answer are in
+// `review-round2.ts`; everything here is the invocation.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh review:round2 [--round-1-closed] [--json]'
+const JSON_KEY = 'round2'
+const FAILURE_EXIT_CODE = 1
+
+// The one input no command can read for itself, so the caller states it: every round-1 High/Medium
+// finding closed, by a fix in this working tree or as a verified false positive, and none was filed
+// or deferred. Spelled out rather than shortened to `--closed`, because a flag whose meaning has to
+// be recalled is one that gets passed on the wrong run.
+const CLOSED_FLAG = '--round-1-closed'
+const KNOWN_FLAGS: ReadonlyArray<string> = [CLOSED_FLAG, path_decision.JSON_FLAG]
+
+interface Options {
+	is_round_one_closed: boolean
+	is_json: boolean
+}
+
+// `undefined` on anything unrecognized rather than a default, through the contract
+// `path_decision.has_unknown_flag` states once for every mechanically-decided command: a misspelled
+// `--round1-closed` that silently answered `required` would be harmless, but a parser that guesses
+// is what makes the difference a matter of which flag was fumbled.
+function parse_options(argv: ReadonlyArray<string>): Options | undefined {
+	if (path_decision.has_unknown_flag(argv, KNOWN_FLAGS)) return undefined
+
+	return {
+		is_round_one_closed: argv.includes(CLOSED_FLAG),
+		is_json: argv.includes(path_decision.JSON_FLAG),
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const options = parse_options(argv)
+
+	if (options === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const { verdict, reason } = review_round2.decide({
+		// The commit the tree below is a diff against, so the snapshot can be refused when it was taken
+		// against a different one — and the resolved commit rather than `git_command.change_base`, whose
+		// fallback is a ref name that moves and would compare equal to itself
+		// (joshuafolkken/kit#1537).
+		base: await change_base.resolved(),
+		is_round_one_closed: options.is_round_one_closed,
+		snapshot: review_stamps.round_one_stamp.read(),
+		// No paths argument: `read_changed_tree` reads them itself, from the one definition of
+		// "changed" `josh review:level` and `josh review:brief` all decide from.
+		// Passing our own reading would be a second definition, which is the drift that module exists
+		// to prevent.
+		tree: await review_tree.read_changed_tree(),
+	})
+
+	path_decision.print_decision(JSON_KEY, verdict, reason, options.is_json)
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const review_round2_cli = { CLOSED_FLAG, JSON_KEY, KNOWN_FLAGS, main, parse_options, run, USAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { review_round2_cli }

package/scripts/review/review-round2.ts

@@ -0,0 +1,139 @@
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { path_decision } from '#scripts/josh/path-decision'
+import { review_level } from './review-level'
+
+// Whether the second review round runs at all (joshuafolkken/kit#1433).
+//
+// **Every previous measure narrowed round 2; this one asks whether it is due.** joshuafolkken/kit#1219
+// redefined its question, joshuafolkken/kit#1241 carried that question into the forked agent, and
+// `prompts/review.md` → "The narrowing is real in scope and does not show in the wall clock" recorded
+// that neither moved the wall clock. Those records answer "narrow round 2"; none of them answers "do
+// not run it", because none measured a run that skipped one.
+//
+// **The two arms are the two states in which joshuafolkken/kit#1222's reason does not arise.** That
+// issue's conclusion is that round 2 exists because round 1's *fix code* is unreviewed, and that this
+// is structural. Arm A applies where there is no fix code — the findings closed without an edit — so
+// the premise is absent rather than overridden. Arm B applies where the fix code neither executes,
+// nor instructs, nor ships, which is `review-level.ts`'s inert set: the same three ways a defect in
+// this repository escapes, read here for the fix delta instead of the whole change.
+//
+// **The wider line the issue proposed — "the fix delta touches no runtime code path" — is not
+// adopted**, and the evidence against it is already in this directory. `review-level.ts` records that
+// joshuafolkken/kit#963 and #965 were documentation-only diffs in which a `medium` review found ten
+// real defects each — dangling pointers and citations naming the wrong file, in artifacts distributed
+// to every consumer — that no test covered. A prompt fix and a test fix are exactly where the review
+// is the only detector, so exempting them would remove the round in the case it earns its keep.
+
+type RoundTwoVerdict = 'required' | 'skip'
+
+const REQUIRED_VERDICT: RoundTwoVerdict = 'required'
+const SKIPPED_VERDICT: RoundTwoVerdict = 'skip'
+
+// **The default is `required`, and every uncertainty resolves to it.** A command that answered `skip`
+// on a missing record would be the cheapest possible run and the most dangerous — the direction
+// `review-brief.ts` already takes when it widens a round-2 target it cannot name.
+const OPEN_FINDING_REASON =
+	'the caller did not assert that every round-1 High/Medium finding closed, so the pass that verifies them is due'
+const NO_SNAPSHOT_REASON =
+	'no round-1 snapshot was recorded, so the fix delta cannot be named — the round runs rather than assuming it is empty'
+const EMPTY_DELTA_REASON_PREFIX =
+	'the fix delta is empty: round 1 wrote no fix code, so there is no unreviewed fix for a verification pass to read'
+const INERT_DELTA_REASON_PREFIX =
+	'every path round 1 fixed is inert — it neither executes, nor instructs, nor ships'
+const BASE_MOVED_REASON =
+	'the change base moved since round 1 was recorded, so the two file maps do not cover the same set of paths and their difference is not the fix delta — the round runs rather than reading that difference as one'
+
+interface RoundTwoInput {
+	// **The commit the tree above is a diff against** (joshuafolkken/kit#1537). This decision reads the
+	// same digest comparison the brief's round-2 target does, so it inherits the same failure: taken
+	// against two different bases, the two maps do not cover the same set of paths, and an empty or
+	// inert-looking delta is then no evidence at all about what round 1 fixed. Here that evidence buys
+	// a `skip`, which is worse than a mistargeted read — nothing gets read at all.
+	// `undefined` where it could not be resolved to a commit, which is refused exactly like a mismatch.
+	base: string | undefined
+	// Asserted by the caller from round 1's own output, because no command can read a review's
+	// findings. It is a report of a fact already written down, not a judgement made under cost
+	// pressure — and its absence is the safe answer, so a caller that forgets it pays a round.
+	is_round_one_closed: boolean
+	snapshot: FileMapStamp | undefined
+	tree: Record<string, string>
+}
+
+interface RoundTwoDecision {
+	verdict: RoundTwoVerdict
+	reason: string
+	// The paths round 1's fixes changed. Returned even on `required` so the caller can name them, and
+	// on a `skip` so the record the run leaves behind says what went unreviewed.
+	delta: ReadonlyArray<string>
+}
+
+// **The snapshot's own timestamp travels with the answer**, the way `review-brief.ts` prints it
+// beside a round-2 target. An empty delta used to have two readings — round 1 wrote no fix code, or
+// the record was retaken after the fixes by a bare `josh review:brief` — and the digests cannot tell
+// them apart, so joshuafolkken/kit#1441 closed the second one at the source: the record is written
+// once per run and kept thereafter, which leaves "round 1 wrote no fix code" as the only reading of
+// an empty delta. The timestamp stays in the reason because a record can still **outlive** its run —
+// `josh followup` is what clears it — and a delta measured from an earlier run's record is wider
+// rather than narrower, which a reader can only see from when that record was taken.
+function empty_reason(taken_at: string): string {
+	return `${EMPTY_DELTA_REASON_PREFIX} (round 1 was recorded at ${taken_at})`
+}
+
+// **Every path, not `format_path_list`'s first five.** This sentence is what the run quotes into the
+// `## Round 2 skipped` comment, and the whole purpose of that record is to attribute a defect found
+// later to the delta that went unreviewed — which a list ending in `+3 more` cannot do. The
+// truncation exists to keep a large diff's reason readable; arm B's delta is inert-only, so there is
+// no large diff here to keep readable.
+function inert_reason(delta: ReadonlyArray<string>): string {
+	return `${INERT_DELTA_REASON_PREFIX}: ${delta.join(', ')}`
+}
+
+// The `required` side keeps the truncation: nothing is recorded from it, and a reason naming every
+// path of a hundred-file change would bury the answer it exists to explain.
+function live_reason(deciding: ReadonlyArray<string>): string {
+	return `round 1's fixes touched paths that execute, instruct or ship: ${path_decision.format_path_list(deciding)}`
+}
+
+function verdict_for_delta(
+	delta: ReadonlyArray<string>,
+	taken_at: string,
+): { verdict: RoundTwoVerdict; reason: string } {
+	if (delta.length === 0) return { verdict: SKIPPED_VERDICT, reason: empty_reason(taken_at) }
+
+	const deciding = delta.filter((relative) => !review_level.is_inert(relative))
+
+	if (deciding.length === 0) return { verdict: SKIPPED_VERDICT, reason: inert_reason(delta) }
+
+	return { verdict: REQUIRED_VERDICT, reason: live_reason(deciding) }
+}
+
+function required(reason: string): RoundTwoDecision {
+	return { verdict: REQUIRED_VERDICT, reason, delta: [] }
+}
+
+function decide(input: RoundTwoInput): RoundTwoDecision {
+	if (!input.is_round_one_closed) return required(OPEN_FINDING_REASON)
+	if (input.snapshot === undefined) return required(NO_SNAPSHOT_REASON)
+	if (!file_map_stamp.describes_base(input.snapshot, input.base)) return required(BASE_MOVED_REASON)
+
+	const delta = file_map_stamp.changed_since(input.snapshot, input.tree)
+
+	return { ...verdict_for_delta(delta, input.snapshot.taken_at), delta }
+}
+
+const review_round2 = {
+	BASE_MOVED_REASON,
+	decide,
+	EMPTY_DELTA_REASON_PREFIX,
+	empty_reason,
+	INERT_DELTA_REASON_PREFIX,
+	inert_reason,
+	live_reason,
+	NO_SNAPSHOT_REASON,
+	OPEN_FINDING_REASON,
+	REQUIRED_VERDICT,
+	SKIPPED_VERDICT,
+	verdict_for_delta,
+}
+
+export { review_round2 }