@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/review/review-reviewed-tree.ts

@@ -0,0 +1,307 @@
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { moved_paths, type MovedParts } from '#scripts/gate/moved-paths'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { release_approval_prune } from '#scripts/release/release-approval-prune'
+import { test_declared_logic } from '#scripts/test/test-declared-logic'
+import { review_attest } from './review-attest'
+import { review_checkout, type ReviewCheckout } from './review-checkout'
+import { review_round_one_blobs } from './review-round-one-blobs'
+import { review_round2 } from './review-round2'
+import { review_stamps } from './review-stamps'
+
+// The tree a recorded `/code-review` round stands for: the changed files as they were when
+// `review:record` wrote the round, its fixes included (joshuafolkken/kit#4620). A lane reviews before
+// `josh ship`, so the ship's round 1 asks this record whether the tree moved since: unmoved, the
+// recorded round is the ship's; moved only where round 2 reads, it is still the ship's and round 2
+// reads the delta (joshuafolkken/kit#4878); else round 1 reads the delta from here.
+//
+// **Taken at the record, not the brief**. A round that fixed findings approved its own edits, so the
+// briefed tree is not what its verdict covers: a file reverted to the briefed bytes would drop out of a
+// delta measured from there with its finding back in it.
+
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/u
+// No file's digest: a path recorded with it never matches the tree, whether the change holds it or not.
+const UNSETTLED_DIGEST = 'unsettled'
+
+// **A file a recorded High cites is recorded as unsettled**: a High is never fixed in place, so the
+// round's verdict does not stand for that file. Its digest matches no tree, so it always reads as moved
+// — the tree is never held, and round 2 reads its fix where its delta holds it (joshuafolkken/kit#4941);
+// anywhere else round 1 reads it again rather than passing over the finding it still holds. A file
+// outside the change (a reader the change broke) is recorded too: left out, it would be absent on both
+// sides and read as unmoved.
+function settled_files(
+	files: Record<string, string>,
+	unsettled: ReadonlyArray<string>,
+): Record<string, string> {
+	const cited = unsettled.map((file): [string, string] => [
+		file.replace(LINE_SUFFIX, ''),
+		UNSETTLED_DIGEST,
+	])
+
+	return { ...files, ...Object.fromEntries(cited) }
+}
+
+// Swallowed: no record re-runs the ship's round 1 over the whole change — wider, never narrower. The
+// blobs let a sync's change to a covered document carry onto the new base (`carried_paths`).
+async function record(unsettled: ReadonlyArray<string> = []): Promise<void> {
+	try {
+		const { files, base } = await gate_tree.read_gate_tree()
+		const blobs = review_round_one_blobs.capture(Object.keys(files))
+
+		review_stamps.reviewed_stamp.write(settled_files(files, unsettled), undefined, base, blobs)
+	} catch {
+		/* no record widens the next round rather than narrowing it */
+	}
+}
+
+// An empty tree or an unresolved base is git not answering, never "nothing moved".
+//
+// **A base the ship's sync moved is unmoved for every path the default branch left alone**
+// (joshuafolkken/kit#4829): with every recorded digest matching, only a synced path the round covers
+// changes what it read — unless round 2 would not execute it and main alone moved it
+// (joshuafolkken/kit#4984). Main's other paths are the scoped pair's, the gate's and CI's to check.
+//
+// **A `josh metrics` approval the branch rewrote is no move** (joshuafolkken/kit#4788): the ship's
+// pre-detach re-record writes it after `review:record`, and it is data `josh metrics` derives and the
+// gate's own metrics step checks, never what the round reviewed. An approval a recorded High cites
+// stays unsettled, so it still reads as moved.
+function is_rerecorded_approval(stamp: FileMapStamp, path: string): boolean {
+	return release_approval_prune.is_approval(path) && stamp.files[path] !== UNSETTLED_DIGEST
+}
+
+// **A test added or edited since the record is no move** (joshuafolkken/kit#4874): `chain-rule.md`
+// step 0 pins each `test:pinned` unpinned place after `review:record`, and a test changes no runtime
+// the round's verdict covers; round 2 still reads the test delta (`review-round2.ts` keeps tests live).
+// A test removed since, or one a recorded High cites, still reads as moved.
+function is_pinning_test(stamp: FileMapStamp, tree: GateTree, path: string): boolean {
+	const is_settled = Object.hasOwn(tree.files, path) && stamp.files[path] !== UNSETTLED_DIGEST
+
+	return is_settled && test_declared_logic.is_test_file(path)
+}
+
+function is_no_move(stamp: FileMapStamp, tree: GateTree, path: string): boolean {
+	return is_rerecorded_approval(stamp, path) || is_pinning_test(stamp, tree, path)
+}
+
+// How the tree stands against the record: `held` — nothing the round read moved; `delta` — every move
+// is one round 2 reads (joshuafolkken/kit#4878); `unsettled` — any other move, or git did not answer.
+const MOVEMENT = { DELTA: 'delta', HELD: 'held', UNSETTLED: 'unsettled' } as const
+
+type Movement = (typeof MOVEMENT)[keyof typeof MOVEMENT]
+
+// The movement, and on `unsettled` the condition that decided it, with the path that met it where one
+// did — printed by `review:record --check` so a lane reads why the ship reviews round 1 again
+// (joshuafolkken/kit#4941).
+interface Standing {
+	movement: Movement
+	cause?: string
+}
+
+const CAUSE = {
+	NO_RECORD: 'no reviewed tree was recorded',
+	SKIPPED:
+		'a move round 2 would not read — documentation, a prompt, an inert path, a revert to the briefed bytes, or a file outside the change',
+	SYNCED: 'the default branch changed a file the round covers',
+	UNFIXED:
+		"a file a recorded High cites still holds its round-1 brief bytes, so no fix is in round 2's delta",
+	UNATTESTED: 'the round was not attested on this branch',
+	UNREAD: 'git did not answer',
+} as const
+
+function unsettled_by(cause: string, path?: string): Standing {
+	return { movement: MOVEMENT.UNSETTLED, cause: path === undefined ? cause : `${cause}: ${path}` }
+}
+
+// **A covered file only the default branch moved is no move where round 2 would not execute it**
+// (joshuafolkken/kit#4984): documentation, a prompt or an inert path — a generated usage heading main
+// rewrote beside the lane's own. Its recorded blob carried onto the new base reproduces the file now
+// only where main's change is all that moved it (`review-round-one-blobs.ts`); a lane edit since the
+// record, a carry git cannot make, or a path a recorded High cites stays moved.
+function is_carry_candidate(stamp: FileMapStamp, path: string): boolean {
+	const is_settled = Object.hasOwn(stamp.files, path) && stamp.files[path] !== UNSETTLED_DIGEST
+
+	return is_settled && review_round2.is_unexecuted(path, [])
+}
+
+function carried_paths(stamp: FileMapStamp, tree: GateTree, parts: MovedParts): Array<string> {
+	const candidates = parts.synced.filter((path) => is_carry_candidate(stamp, path))
+	const { blobs, base: from } = stamp
+	const delta =
+		candidates.length === 0
+			? undefined
+			: review_round_one_blobs.carried_delta({ blobs, from, to: tree.base, paths: candidates })
+
+	return delta === undefined ? [] : candidates.filter((path) => !delta.includes(path))
+}
+
+function moved_files(stamp: FileMapStamp, tree: GateTree, parts: MovedParts): Array<string> {
+	return parts.changed.filter((path) => !is_no_move(stamp, tree, path))
+}
+
+// **Round 2 reads a move only where its own delta holds it**: it diffs from the round-1 brief's stamp
+// (`briefed`) and passes over documentation, prompts and inert paths (`review-round2.ts`), so a file
+// reverted to the briefed bytes, or one round 2 skips, would ship unread. A path a recorded High cites
+// is read there too — its fix is the delta round 2 verifies, and its brief names the file as a High's
+// fix (`review-brief.ts`). A default-branch change to a covered file is outside round 2's carried delta.
+function is_read_by_round_two(
+	path: string,
+	tree: GateTree,
+	briefed: FileMapStamp | undefined,
+): boolean {
+	if (review_round2.is_unexecuted(path, [])) return false
+
+	return briefed?.files[path] !== tree.files[path]
+}
+
+// An unread High-cited file round 2 would execute is one whose fix has not landed, not a revert.
+function unread_cause(stamp: FileMapStamp, path: string): string {
+	const is_cited = stamp.files[path] === UNSETTLED_DIGEST
+
+	return is_cited && !review_round2.is_unexecuted(path, []) ? CAUSE.UNFIXED : CAUSE.SKIPPED
+}
+
+function moved_standing(
+	stamp: FileMapStamp,
+	moved: ReadonlyArray<string>,
+	tree: GateTree,
+	briefed: FileMapStamp | undefined,
+): Standing {
+	if (moved.length === 0) return { movement: MOVEMENT.HELD }
+
+	const unread = moved.find((path) => !is_read_by_round_two(path, tree, briefed))
+
+	if (unread === undefined) return { movement: MOVEMENT.DELTA }
+
+	return unsettled_by(unread_cause(stamp, unread), unread)
+}
+
+async function standing(
+	stamp: FileMapStamp,
+	tree: GateTree,
+	briefed?: FileMapStamp,
+): Promise<Standing> {
+	const parts = await moved_paths.moved_parts(stamp, tree)
+
+	if (parts === undefined) return unsettled_by(CAUSE.UNREAD)
+
+	const carried = carried_paths(stamp, tree, parts)
+	const synced = parts.synced.find(
+		(path) => Object.hasOwn(stamp.files, path) && !carried.includes(path),
+	)
+
+	if (synced !== undefined) return unsettled_by(CAUSE.SYNCED, synced)
+
+	const moved = moved_files(stamp, tree, parts).filter((path) => !carried.includes(path))
+
+	return moved_standing(stamp, moved, tree, briefed)
+}
+
+async function movement(
+	stamp: FileMapStamp,
+	tree: GateTree,
+	briefed?: FileMapStamp,
+): Promise<Movement> {
+	const answer = await standing(stamp, tree, briefed)
+
+	return answer.movement
+}
+
+async function is_unmoved(stamp: FileMapStamp, tree: GateTree): Promise<boolean> {
+	return (await movement(stamp, tree)) === MOVEMENT.HELD
+}
+
+// **Only a review attested on this branch is reused**, as `resume_point` narrows from no other: the
+// reuse skips the ship's own `review:attest --check`, so a round recorded over a review that read
+// another checkout, or never finished, would otherwise ship unreviewed.
+async function standing_here(): Promise<Standing> {
+	const stamp = review_stamps.reviewed_stamp.read()
+
+	if (stamp === undefined) return unsettled_by(CAUSE.NO_RECORD)
+
+	const checkout = await review_checkout.read_checkout()
+
+	if (!review_attest.is_attested_on(checkout, checkout.root)) return unsettled_by(CAUSE.UNATTESTED)
+
+	const tree = await gate_tree.read_gate_tree()
+
+	return await standing(stamp, tree, review_stamps.round_one_stamp.read())
+}
+
+// The files a recorded High cites — the ones the round-2 brief names as a High's fix to read whole.
+function high_cited(): ReadonlyArray<string> {
+	const files = review_stamps.reviewed_stamp.read()?.files ?? {}
+
+	return Object.keys(files).filter((path) => files[path] === UNSETTLED_DIGEST)
+}
+
+// The record a resumed brief narrows from: written after the brief the pointer names, whose review was
+// attested on this branch. Asked before the next brief mints its pointer, which this record then
+// predates — so it narrows one round, never two.
+function resume_point(checkout: ReviewCheckout): FileMapStamp | undefined {
+	const stamp = review_stamps.reviewed_stamp.read()
+
+	if (stamp === undefined || !review_attest.is_briefed_since(stamp.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	return review_attest.is_attested_on(checkout, checkout.root) ? stamp : undefined
+}
+
+// **A ship's round 1 that stopped on a finding stays its round 1 however the tree moves since**: the
+// tree moves by the fix, and the fix delta is round 2's to verify (joshuafolkken/kit#2964). Reviewed
+// as round 1 again, every stop would cost one more review and one more chance to stop. The marker
+// names the issue, so a checkout that ships another issue next never reuses this one's round.
+const STOPPED_PREFIX = 'josh-review-round1-stopped-'
+
+function stopped_path(): string {
+	return stamp_file.stamp_path(STOPPED_PREFIX, PROJECT_ROOT)
+}
+
+// Written when the ship's round 1 stops on a finding, removed when it ends any other way. A write the
+// temp directory refuses is swallowed: no marker re-runs round 1 — wider, never narrower.
+function mark_stopped(issue: number, is_stopped: boolean): void {
+	if (!is_stopped) {
+		stamp_file.remove_stamp(stopped_path())
+
+		return
+	}
+
+	try {
+		stamp_file.write_text_stamp(stopped_path(), String(issue))
+	} catch {
+		/* no marker reviews round 1 again rather than passing over it */
+	}
+}
+
+function is_stopped_on(issue: number): boolean {
+	return stamp_file.read_stamp_text(stopped_path()) === String(issue)
+}
+
+// The ship drops both records when the issue changed after the recorded round's brief: that round never
+// read the new specification, so the next one reviews the whole change.
+function discard(): void {
+	try {
+		review_stamps.reviewed_stamp.remove()
+		stamp_file.remove_stamp(stopped_path())
+	} catch {
+		/* the temp directory refused the removal; nothing else here can */
+	}
+}
+
+const review_reviewed_tree = {
+	MOVEMENT,
+	discard,
+	high_cited,
+	is_stopped_on,
+	is_unmoved,
+	mark_stopped,
+	movement,
+	record,
+	resume_point,
+	standing_here,
+}
+
+export type { Movement, Standing }
+export { review_reviewed_tree }

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,11 +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_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'
 
@@ -18,42 +24,82 @@ 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 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]),
 	}
 }
 
-// Only the paths the code record covers are re-read, so a run without one parses nothing.
+// 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. **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 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)
+	return review_code_tree
+		.comment_only(snapshot, tree, base, unmoved)
+		.filter((path) => !cited.has(path))
 }
 
 // The carry over every path changed now, not only round 1's: a file the fix added after the merge is
@@ -82,34 +128,48 @@ function print(answer: RoundTwoAnswer, is_json: boolean): void {
 	path_decision.print_decision(review_round2.JSON_KEY, answer.verdict, answer.reason, is_json)
 }
 
-async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const options = parse_options(argv)
-
-	if (options === undefined) {
-		console.error(USAGE)
-
-		return FAILURE_EXIT_CODE
-	}
+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()
+	// 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()
-	const decision = review_round2.decide({
+
+	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(),
 		tree,
 	})
+}
+
+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
 }
 
@@ -118,11 +178,13 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const review_round2_cli = {
-	CLOSED_FLAG,
 	carried_reader,
 	parse_options,
 	print,
 	read_comment_only,
+	RECORD_FLAG,
+	RETIRED_CLOSED_FLAG,
+	RETIRED_CLOSED_LINE,
 	run,
 }