@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/review/review-round-one-blobs.ts

@@ -0,0 +1,221 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { review_tree } from './review-tree'
+
+// Round 1's files as git blobs, so round 2 can still name the fix delta after the change base moved
+// (joshuafolkken/kit#4165).
+//
+// **A lane merges the default branch between the rounds**, which moves the base, and the round-1 file
+// map then covers a different set of paths from the one read now. Its digests cannot be carried onto
+// the new base; blobs can. `capture` writes each round-1 path into the object store — nothing else:
+// no index, no commit, no ref. `carried_delta` then carries each path three ways — the old base, round
+// 1, the new base — and names the paths whose carried content differs from the working tree now. A
+// path the default branch alone changed carries to exactly what the merge left, so it drops out; what
+// is left is round 1's fixes.
+//
+// **Every failure answers `undefined`**, which round 2 reads as the moved-base refusal it gave before:
+// no recorded blobs, a carry that conflicts, or a git that cannot run one of the reads.
+
+// A path the working tree or a commit does not hold.
+const ABSENT = review_tree.ABSENT_DIGEST
+const SUCCESS_EXIT_CODE = 0
+const NUL = '\0'
+const NEWLINE = '\n'
+const TAB = '\t'
+const SPACE = ' '
+const OID_FIELD = 2
+const WRITE_FLAGS: ReadonlyArray<string> = ['-w']
+const READ_FLAGS: ReadonlyArray<string> = []
+
+interface Move {
+	// The base round 1 was read against, and the base now.
+	from: string | undefined
+	to: string | undefined
+	// The paths to read: for a carry, those changed against the base now.
+	paths: ReadonlyArray<string>
+}
+
+interface CarryInput extends Move {
+	// Round 1's blobs, from the snapshot.
+	blobs: Record<string, string> | undefined
+}
+
+interface Carry {
+	blobs: Record<string, string>
+	from: string
+	to: string
+	paths: ReadonlyArray<string>
+}
+
+interface Readings {
+	blobs: Record<string, string>
+	before: Record<string, string>
+	after: Record<string, string>
+	now: Record<string, string>
+}
+
+interface Sides {
+	base: string
+	round_one: string
+	moved: string
+}
+
+// git's paths are root-relative, so every command runs from the root rather than the caller's cwd.
+function repository_root(): string | undefined {
+	return git_spawn_sync.read(['rev-parse', '--show-toplevel'])
+}
+
+function hash_paths(
+	root: string,
+	paths: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): Record<string, string> | undefined {
+	const present = paths.filter((relative) => existsSync(path.join(root, relative)))
+	const output =
+		present.length === 0
+			? ''
+			: git_spawn_sync.read(['hash-object', ...flags, '--', ...present], { cwd: root })
+
+	if (output === undefined) return undefined
+
+	const hashes = output.split(NEWLINE)
+	const hashed = new Map(present.map((relative, index) => [relative, hashes[index] ?? ABSENT]))
+
+	return Object.fromEntries(paths.map((relative) => [relative, hashed.get(relative) ?? ABSENT]))
+}
+
+// `<mode> <type> <oid>\t<path>`.
+function parse_entry(entry: string): [string, string] {
+	const tab = entry.indexOf(TAB)
+
+	return [entry.slice(tab + 1), entry.slice(0, tab).split(SPACE)[OID_FIELD] ?? ABSENT]
+}
+
+function blobs_at(
+	commit: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Record<string, string> | undefined {
+	const result = git_spawn_sync.run(['ls-tree', '-r', '-z', commit, '--', ...paths], { cwd: root })
+
+	if (result.exit_code !== SUCCESS_EXIT_CODE) return undefined
+
+	return Object.fromEntries(
+		result.stdout
+			.split(NUL)
+			.filter((entry) => entry !== '')
+			.map((entry) => parse_entry(entry)),
+	)
+}
+
+// `git merge-file` exits with the number of conflicts, so only a clean merge answers an oid.
+function merged_blob({ base, round_one, moved }: Sides, root: string): string | undefined {
+	if ([base, round_one, moved].includes(ABSENT)) return undefined
+
+	return git_spawn_sync.read(['merge-file', '--object-id', round_one, base, moved], { cwd: root })
+}
+
+function carried_blob(sides: Sides, root: string): string | undefined {
+	if (sides.round_one === sides.base) return sides.moved
+	if (sides.moved === sides.base || sides.moved === sides.round_one) return sides.round_one
+
+	return merged_blob(sides, root)
+}
+
+// A path round 1 did not list was unchanged against its base, so round 1 held the base's blob.
+function sides_of(relative: string, readings: Readings): Sides {
+	const base = readings.before[relative] ?? ABSENT
+
+	return {
+		base,
+		round_one: readings.blobs[relative] ?? base,
+		moved: readings.after[relative] ?? ABSENT,
+	}
+}
+
+function differing(
+	paths: ReadonlyArray<string>,
+	readings: Readings,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	const carried = paths.map((relative) => carried_blob(sides_of(relative, readings), root))
+
+	if (carried.includes(undefined)) return undefined
+
+	return paths.filter((relative, index) => carried[index] !== readings.now[relative])
+}
+
+function read_readings(
+	input: Carry,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Readings | undefined {
+	const before = blobs_at(input.from, paths, root)
+	const after = blobs_at(input.to, paths, root)
+	const now = hash_paths(root, paths, READ_FLAGS)
+
+	if (before === undefined || after === undefined || now === undefined) return undefined
+
+	return { blobs: input.blobs, before, after, now }
+}
+
+// No paths at all is an empty delta: `ls-tree` given none would list the whole tree.
+function delta_of(input: Carry, root: string): ReadonlyArray<string> | undefined {
+	const paths = [...new Set([...Object.keys(input.blobs), ...input.paths])].toSorted(
+		(left, right) => left.localeCompare(right),
+	)
+	const readings = paths.length === 0 ? undefined : read_readings(input, paths, root)
+
+	if (paths.length === 0) return []
+
+	return readings === undefined ? undefined : differing(paths, readings, root)
+}
+
+function carried_delta(input: CarryInput): ReadonlyArray<string> | undefined {
+	const { blobs, from, to } = input
+	const root = repository_root()
+
+	if (root === undefined || blobs === undefined || from === undefined || to === undefined) {
+		return undefined
+	}
+
+	return delta_of({ blobs, from, to, paths: input.paths }, root)
+}
+
+function unmoved_between(
+	from: string,
+	to: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	if (from === to || paths.length === 0) return paths
+	const before = blobs_at(from, paths, root)
+	const after = blobs_at(to, paths, root)
+
+	if (before === undefined || after === undefined) return undefined
+
+	return paths.filter((relative) => (before[relative] ?? ABSENT) === (after[relative] ?? ABSENT))
+}
+
+// The paths the base move left alone: there the carry reproduces round 1's file, so the fix delta on
+// them is round 1 against the working tree, as on an unmoved base. `undefined` when git cannot say.
+function unmoved({ from, to, paths }: Move): ReadonlyArray<string> | undefined {
+	const root = repository_root()
+
+	if (root === undefined || from === undefined || to === undefined) return undefined
+
+	return unmoved_between(from, to, paths, root)
+}
+
+// Each path's blob, written into the object store so a later carry can merge it; `undefined` when git
+// cannot answer, which the record then omits.
+function capture(paths: ReadonlyArray<string>): Record<string, string> | undefined {
+	const root = repository_root()
+
+	return root === undefined ? undefined : hash_paths(root, paths, WRITE_FLAGS)
+}
+
+const review_round_one_blobs = { capture, carried_delta, unmoved }
+
+export { review_round_one_blobs }

package/scripts/review/review-round-one-closure.ts

@@ -0,0 +1,62 @@
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger, type DisposedLine } from './review-finding-ledger'
+
+// Whether round 1's High/Medium findings all closed, read from the issue's own ledger file rather
+// than asserted by the caller (joshuafolkken/kit#5286). Closed means every High/Medium `- rf:` line
+// of the issue carries `fixed` or `false-positive`; a line with no disposition, a filed or deferred
+// one, or no recorded round at all leaves round 1 open, so the answer stays `required`. Only the
+// issue's latest code round is read (joshuafolkken/kit#5359): an earlier round's unfixed lines stay
+// in the append-only ledger after a clean re-run.
+
+const BLOCKING_SEVERITIES: ReadonlySet<string> = new Set(['high', 'medium'])
+const NO_RECORD_REASON =
+	'no round-1 round is recorded in the ledger for this issue, so its findings cannot be read as closed'
+
+const OPEN_REASON_PREFIX =
+	'round 1 left High/Medium findings neither fixed nor a false positive in the ledger'
+const NO_DISPOSITION = 'no disposition'
+
+interface Closure {
+	is_closed: boolean
+	reason: string
+}
+
+const CLOSED: Closure = { is_closed: true, reason: '' }
+
+function is_open(line: DisposedLine): boolean {
+	return (
+		BLOCKING_SEVERITIES.has(line.severity) && !review_finding_ledger.is_closing(line.disposition)
+	)
+}
+
+function open_reason(open: ReadonlyArray<DisposedLine>): string {
+	const dispositions = open.map((line) => line.disposition ?? NO_DISPOSITION).join(', ')
+
+	return `${OPEN_REASON_PREFIX} (${String(open.length)}: ${dispositions}), so the pass that verifies them is due`
+}
+
+function of_content(content: string | undefined, issue: number): Closure {
+	const latest = review_finding_ledger.latest_round(content ?? '', issue)
+	const lines = review_finding_ledger.issue_dispositions(latest, issue)
+
+	if (lines.length === 0) return { is_closed: false, reason: NO_RECORD_REASON }
+
+	const open = lines.filter((line) => is_open(line))
+
+	return open.length === 0 ? CLOSED : { is_closed: false, reason: open_reason(open) }
+}
+
+// `undefined` issue — a branch that names none — has no ledger lines to read, so it is open.
+async function read(
+	issue: number | undefined,
+	root: string = observation_ledger_home.ledger_root(),
+): Promise<Closure> {
+	if (issue === undefined) return { is_closed: false, reason: NO_RECORD_REASON }
+
+	return of_content(await observation_ledger_home.read(root), issue)
+}
+
+const review_round_one_closure = { NO_RECORD_REASON, OPEN_REASON_PREFIX, of_content, read }
+
+export type { Closure }
+export { review_round_one_closure }

package/scripts/review/review-round-reuse.ts

@@ -0,0 +1,106 @@
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
+import { error_text } from '#scripts/lib/error-message'
+import { review_record } from './review-record'
+import { review_reviewed_tree } from './review-reviewed-tree'
+
+// Whether `josh ship` reuses the recorded round 1 rather than reviewing it again — asked by the ship
+// and by `josh review:record --check`, so a lane resuming on an old record reads the ship's own answer
+// rather than mistaking "recorded" for "reused" (joshuafolkken/kit#4763).
+
+// The issue changed after the recorded review was briefed — the refusal `josh followup` would make
+// (joshuafolkken/kit#4221). A read that fails reads as fresh: `josh followup` still refuses a stale
+// review at the merge.
+async function is_stale_here(): Promise<boolean> {
+	try {
+		return (await issue_watch_gate.review_refusal_here()) !== undefined
+	} catch (error) {
+		error_text.trace_swallowed('review_round_reuse.is_stale_here', error)
+
+		return false
+	}
+}
+
+// What the ship does with the recorded round 1: `held` reuses it with nothing left to read; `delta`
+// reuses it and leaves what moved since to round 2; `again` reviews round 1 again.
+const REUSE = { AGAIN: 'again', DELTA: 'delta', HELD: 'held' } as const
+
+type Reuse = (typeof REUSE)[keyof typeof REUSE]
+
+const { MOVEMENT } = review_reviewed_tree
+
+// The reuse, and on `again` why (joshuafolkken/kit#4941): `review:record --check` prints it, so a lane
+// reads which condition re-runs round 1 rather than a list of every condition that could.
+interface ReuseAnswer {
+	reuse: Reuse
+	cause?: string | undefined
+}
+
+const STALE_CAUSE = "the issue changed after the recorded round's brief"
+const UNRECORDED_CAUSE = 'no review round is recorded for this issue'
+
+async function recorded_answer(issue: number): Promise<ReuseAnswer> {
+	const { movement, cause } = await review_reviewed_tree.standing_here()
+
+	if (movement === MOVEMENT.HELD) return { reuse: REUSE.HELD }
+
+	const is_delta = movement === MOVEMENT.DELTA || review_reviewed_tree.is_stopped_on(issue)
+
+	return is_delta ? { reuse: REUSE.DELTA } : { reuse: REUSE.AGAIN, cause }
+}
+
+// **A recorded round 1 is reused while the tree it was recorded on holds still** — a lane's review
+// before the ship (joshuafolkken/kit#4620) — **or once it moved only where round 2 reads**
+// (joshuafolkken/kit#4878): round 2 reads that delta from the round-1 brief's stamp after the commit, so
+// round 1 run again would read it twice. **The ship's own round 1 that stopped on a finding** is reused
+// however the lane's fix moved the tree, for the same reason. A High-cited file's fix is such a move
+// where round 2's delta holds it (joshuafolkken/kit#4941). Any other move — a doc, a revert — is
+// reviewed again, from that record (`review-reviewed-tree.ts`). An issue that changed after that
+// round's brief is never reused: the recorded round never read it, and `josh followup` refuses the merge on it
+// (joshuafolkken/kit#4221).
+async function answer(issue: number, is_stale: boolean): Promise<ReuseAnswer> {
+	if (is_stale) return { reuse: REUSE.AGAIN, cause: STALE_CAUSE }
+
+	const recorded = await review_record.check(issue)
+
+	if (recorded.status !== 'ok') return { reuse: REUSE.AGAIN, cause: UNRECORDED_CAUSE }
+
+	return await recorded_answer(issue)
+}
+
+async function reuse(issue: number, is_stale: boolean): Promise<Reuse> {
+	const reused = await answer(issue, is_stale)
+
+	return reused.reuse
+}
+
+async function is_reusable(issue: number, is_stale: boolean): Promise<boolean> {
+	return (await reuse(issue, is_stale)) !== REUSE.AGAIN
+}
+
+// The ship's own answer for this checkout, asked before the ship runs; a git failure throws.
+async function answer_here(issue: number): Promise<ReuseAnswer> {
+	return await answer(issue, await is_stale_here())
+}
+
+async function reuse_here(issue: number): Promise<Reuse> {
+	const reused = await answer_here(issue)
+
+	return reused.reuse
+}
+
+async function is_reusable_here(issue: number): Promise<boolean> {
+	return (await reuse_here(issue)) !== REUSE.AGAIN
+}
+
+const review_round_reuse = {
+	REUSE,
+	answer,
+	answer_here,
+	is_reusable,
+	is_reusable_here,
+	is_stale_here,
+	reuse_here,
+}
+
+export type { Reuse, ReuseAnswer }
+export { review_round_reuse }

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

@@ -1,9 +1,17 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { change_base } from '#scripts/git/change-base'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { path_decision } from '#scripts/josh/path-decision'
 import { review_code_tree } from './review-code-tree'
-import { review_round2 } from './review-round2'
+import { review_reviewed_tree } from './review-reviewed-tree'
+import { review_round_one_blobs } from './review-round-one-blobs'
+import { review_round_one_closure } from './review-round-one-closure'
+import { review_round2, type RoundTwoAnswer } from './review-round2'
+import { review_round2_skip_comment } from './review-round2-skip-comment'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
 
@@ -16,69 +24,151 @@ import { review_tree } from './review-tree'
 // `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 USAGE = 'Usage: josh review:round2 [--record <N>] [--json]'
 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]
+// **Round 1's closure is read from the ledger, not asserted** (joshuafolkken/kit#5286): the flag that
+// once stated it is refused with the one line that names what replaced it.
+const RETIRED_CLOSED_FLAG = '--round-1-closed'
+const RETIRED_CLOSED_LINE =
+	'--round-1-closed is retired: review:round2 reads round 1’s closure from the dispositions `review:record` keeps in the ledger — record each finding as `fixed <spec>` or `false-positive <spec>`, and pass --record <N> to name the issue.'
+const RECORD_FLAG = '--record'
+// The flag and its issue number.
+const RECORD_ARGUMENT_COUNT = 2
+const KNOWN_FLAGS: ReadonlyArray<string> = [path_decision.JSON_FLAG]
 
 interface Options {
-	is_round_one_closed: boolean
 	is_json: boolean
+	// The issue `--record` names — whose ledger lines are read and where a skip is commented.
+	record: number | undefined
+}
+
+function without_record(argv: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
+	const index = argv.indexOf(RECORD_FLAG)
+
+	if (index === -1) return argv
+
+	const value = argv[index + 1] ?? ''
+
+	return issue_number_shape.is_issue_number(value)
+		? argv.toSpliced(index, RECORD_ARGUMENT_COUNT)
+		: undefined
 }
 
 // `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.
+// `path_decision.has_unknown_flag` states once for every mechanically-decided command: a parser that
+// guesses is what makes the answer 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
+	const rest = without_record(argv)
+
+	if (rest === undefined || path_decision.has_unknown_flag(rest, KNOWN_FLAGS)) return undefined
+
+	const index = argv.indexOf(RECORD_FLAG)
 
 	return {
-		is_round_one_closed: argv.includes(CLOSED_FLAG),
-		is_json: argv.includes(path_decision.JSON_FLAG),
+		is_json: rest.includes(path_decision.JSON_FLAG),
+		record: index === -1 ? undefined : Number(argv[index + 1]),
+	}
+}
+
+// The issue whose ledger lines decide round 1's closure: `--record`'s, else the branch's.
+async function issue_of(options: Options): Promise<number | undefined> {
+	return options.record ?? git_branch.issue_from_branch(await git_command.branch())
+}
+
+async function report_record(issue: number, answer: RoundTwoAnswer): Promise<void> {
+	const recorded = await review_round2_skip_comment.record(issue, answer)
+
+	if (recorded === 'posted' || recorded === 'present') {
+		console.error(`${review_round2_skip_comment.HEADING}: ${recorded} on issue ${String(issue)}`)
+	} else if (recorded !== 'not-skipped') {
+		console.error(`${review_round2_skip_comment.HEADING}: not recorded (${recorded})`)
 	}
 }
 
-// Only the paths the code record covers are re-read, so a run without one parses nothing.
+// Only the paths the code record covers are re-read, so a run without one parses nothing. **A file a
+// recorded High cites is never comment-only** (joshuafolkken/kit#4941): `josh ship` reuses round 1 once
+// that file's fix moved (`review-reviewed-tree.ts`), so a fix written in comments alone is still this
+// round's to verify.
 async function read_comment_only(base: string | undefined): Promise<ReadonlyArray<string>> {
 	const snapshot = review_stamps.round_one_code_stamp.read()
-	const tree = await review_code_tree.read(Object.keys(snapshot?.files ?? {}))
-
-	return review_code_tree.comment_only(snapshot, tree, base)
+	const paths = Object.keys(snapshot?.files ?? {})
+	const tree = await review_code_tree.read(paths)
+	const unmoved = review_round_one_blobs.unmoved({ from: snapshot?.base, to: base, paths })
+	const cited = new Set(review_reviewed_tree.high_cited())
+
+	return review_code_tree
+		.comment_only(snapshot, tree, base, unmoved)
+		.filter((path) => !cited.has(path))
 }
 
-async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const options = parse_options(argv)
+// The carry over every path changed now, not only round 1's: a file the fix added after the merge is
+// in no round-1 record and has to be named all the same.
+function carried_reader(
+	base: string | undefined,
+	tree: Record<string, string>,
+): (snapshot: FileMapStamp) => ReadonlyArray<string> | undefined {
+	return (snapshot) =>
+		review_round_one_blobs.carried_delta({
+			blobs: snapshot.blobs,
+			from: snapshot.base,
+			to: base,
+			paths: Object.keys(tree),
+		})
+}
 
-	if (options === undefined) {
-		console.error(USAGE)
+// `--json` carries the reason code as well, the field `josh ship` records in the lane ledger.
+function print(answer: RoundTwoAnswer, is_json: boolean): void {
+	if (is_json) {
+		console.info(review_round2.to_json(answer))
 
-		return FAILURE_EXIT_CODE
+		return
 	}
 
+	path_decision.print_decision(review_round2.JSON_KEY, answer.verdict, answer.reason, is_json)
+}
+
+function refusal_of(argv: ReadonlyArray<string>): string {
+	return argv.includes(RETIRED_CLOSED_FLAG) ? RETIRED_CLOSED_LINE : USAGE
+}
+
+async function decide_here(options: Options): Promise<RoundTwoAnswer> {
+	const closure = await review_round_one_closure.read(await issue_of(options))
 	// 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.
-	const base = await change_base.resolved()
-	const { verdict, reason } = review_round2.decide({
+	// fallback is a ref name that moves and would compare equal to itself. Read through a merge in
+	// progress, as the changed tree below is.
+	const base = await change_base.resolved_through_merge()
+	// 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.
+	const tree = await review_tree.read_changed_tree()
+
+	return review_round2.decide({
 		base,
+		carried_delta: carried_reader(base, tree),
 		comment_only: await read_comment_only(base),
-		is_round_one_closed: options.is_round_one_closed,
+		is_round_one_closed: closure.is_closed,
+		open_reason: closure.reason,
 		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(),
+		tree,
 	})
+}
 
-	path_decision.print_decision(JSON_KEY, verdict, reason, options.is_json)
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const options = parse_options(argv)
+
+	if (options === undefined) {
+		console.error(refusal_of(argv))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const decision = await decide_here(options)
+
+	print(decision, options.is_json)
+
+	if (options.record !== undefined) await report_record(options.record, decision)
 
 	return 0
 }
@@ -87,7 +177,16 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const review_round2_cli = { CLOSED_FLAG, parse_options, read_comment_only, run }
+const review_round2_cli = {
+	carried_reader,
+	parse_options,
+	print,
+	read_comment_only,
+	RECORD_FLAG,
+	RETIRED_CLOSED_FLAG,
+	RETIRED_CLOSED_LINE,
+	run,
+}
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-round2-skip-comment.ts

@@ -0,0 +1,55 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_read, type IssueComment } from '#scripts/issue/issue-read'
+import { review_round2, type RoundTwoAnswer } from './review-round2'
+
+// `josh review:round2 --record <N>` — the `## Round 2 skipped` comment `prompts/review.md` asks for,
+// written by the command rather than assembled by the run (joshuafolkken/kit#5286). It names the arm
+// that fired and quotes the reason line verbatim, so a defect found later can be traced to the delta
+// that went unreviewed. **A re-run writes nothing twice**: a trusted comment already carrying the same
+// heading and reason line is the record.
+
+const HEADING = '## Round 2 skipped'
+const ARMS: Readonly<Record<string, string>> = {
+	[review_round2.CODE.EMPTY]: 'A — the fix delta is empty',
+	[review_round2.CODE.INERT]: 'B — every fixed path leaves what executes unchanged',
+}
+
+type SkipRecord = 'posted' | 'present' | 'unreadable' | 'failed' | 'not-skipped'
+
+function body_of(answer: RoundTwoAnswer): string {
+	return [
+		HEADING,
+		'',
+		`- arm: ${ARMS[answer.code] ?? answer.code}`,
+		`- reason: ${answer.reason}`,
+	].join('\n')
+}
+
+function is_recorded(comment: IssueComment, body: string): boolean {
+	return comment.is_trusted === true && comment.body.trimStart().startsWith(body)
+}
+
+async function read_comments(issue: number): Promise<ReadonlyArray<IssueComment> | undefined> {
+	return await issue_read.parse_comments(await git_gh_issue_read.issue_list_comments(String(issue)))
+}
+
+// `not-skipped` for a `required` answer: only a skip is recorded. An unreadable listing posts nothing
+// rather than risk the duplicate the record exists to avoid.
+async function record(issue: number, answer: RoundTwoAnswer): Promise<SkipRecord> {
+	if (answer.verdict !== review_round2.SKIPPED_VERDICT) return 'not-skipped'
+
+	const body = body_of(answer)
+	const comments = await read_comments(issue)
+
+	if (comments === undefined) return 'unreadable'
+
+	if (comments.some((comment) => is_recorded(comment, body))) return 'present'
+
+	return (await git_gh_issue_write.issue_try_comment(String(issue), body)) ? 'posted' : 'failed'
+}
+
+const review_round2_skip_comment = { body_of, HEADING, record }
+
+export type { SkipRecord }
+export { review_round2_skip_comment }