@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,28 +1,34 @@
-#!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { bash_output_cap_reader } from '#scripts/document/bash-output-cap'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { change_base } from '#scripts/git/change-base'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 import { run_ship_review } from '#scripts/run/ship/run-ship-review'
-import { review_attest } from './review-attest'
+import { removed_tests_check } from './removed-tests-check'
+import { review_attest, type ReviewSlot } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 import { review_code_tree } from './review-code-tree'
 import type { DiffParts } from './review-diff-parts'
 import { review_diff_write } from './review-diff-write'
+import { review_interaction } from './review-interaction'
 import { review_level, type ReviewLevel } from './review-level'
+import { review_reviewed_tree } from './review-reviewed-tree'
+import { review_round_one_blobs } from './review-round-one-blobs'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
+import { review_untouched_readers, type ReadersRead } from './review-untouched-readers'
 
 // `josh review:brief` — print the whole `/code-review` invocation, not just the level.
 //
@@ -33,8 +39,8 @@ import { review_tree } from './review-tree'
 // so "still running" is the usual answer at this point), how this project runs its unit tests, and —
 // on round 2 — which files the first round's fixes touched.
 
-const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh review:brief [--round <1|2>] | --level-only [--staged] [--json]'
+const USAGE =
+	'Usage: josh review:brief [--round <1|2>] | --interaction | --level-only [--staged] [--json]'
 
 // The rubric's absolute path, resolved against the kit package rather than the review checkout root.
 // The rubric ships inside the package, so a consumer that keeps no
@@ -54,6 +60,7 @@ const ROUND_FLAG = '--round'
 // paths and nothing else. `--staged` and `--json` are passed straight through, exactly as the old
 // command took them.
 const LEVEL_ONLY_FLAG = '--level-only'
+const INTERACTION_FLAG = '--interaction'
 const LEVEL_KEY = 'level'
 const FIRST_ROUND = 1
 const FAILURE_EXIT_CODE = 1
@@ -95,7 +102,7 @@ function kept_note(taken_at: string): string {
 // **It is written once per run and never retaken**. Overwriting on every
 // round-1 invocation put a wrong `skip` one command away: run a bare `josh review:brief` after round
 // 1's fixes are in and the record is retaken against the fixed tree, the fix delta reads empty, and
-// `josh review:round2 --round-1-closed` fires arm A on unreviewed fix code. Keeping the record the
+// `josh review:round2` on a closed round 1 fires arm A on unreviewed fix code. Keeping the record the
 // run already has removes that path outright — a second round-1 invocation reads it and leaves it
 // alone, so every later reading of the delta is measured from before the fixes.
 //
@@ -132,7 +139,12 @@ function record_round_one(
 			return false
 		}
 
-		review_stamps.round_one_stamp.write(tree, target, base)
+		review_stamps.round_one_stamp.write(
+			tree,
+			target,
+			base,
+			review_round_one_blobs.capture(Object.keys(tree)),
+		)
 
 		return true
 	} catch {
@@ -155,7 +167,7 @@ function record_round_one(
 // **The narrowing is measured from the tree that review was briefed on**, and only when that record
 // was written by the brief the pointer names: one left by an earlier brief is not the tree the
 // finished review read, so the resume reads the whole change instead.
-function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
+function findings_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
 	const { findings } = lane_session_broker.review_paths(PROJECT_ROOT)
 	const briefed = review_stamps.briefed_stamp.read()
 
@@ -170,18 +182,31 @@ function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
 	return is_clean ? briefed : undefined
 }
 
-async function open_contract(): Promise<{
+// **A recorded round narrows first**, from the tree `review:record` wrote it on — a lane's review
+// before the ship writes no findings file, and its fixes are in that tree (joshuafolkken/kit#4620).
+function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
+	return review_reviewed_tree.resume_point(checkout) ?? findings_tree(checkout)
+}
+
+function slot_of(interaction: ReadonlyArray<string> | undefined): ReviewSlot {
+	const { CODE, INTERACTION } = review_attest.REVIEW_SLOT
+
+	return interaction === undefined ? CODE : INTERACTION
+}
+
+async function open_contract(slot: ReviewSlot): Promise<{
 	checkout: ReviewCheckout
 	nonce: string
 	resumed_from: FileMapStamp | undefined
 }> {
 	const checkout = await review_checkout.read_checkout()
 	const resumed_from = attested_tree(checkout)
-
 	// Keyed on the root git just answered with, never on `process.cwd()`: the check made before the
 	// merge asks git the same question, and the two hash different keys the moment one of them runs
 	// from a subdirectory — a mismatch that would drop the guard with nothing printed.
-	return { checkout, nonce: review_attest.record_target(checkout, checkout.root), resumed_from }
+	const nonce = review_attest.record_target(checkout, checkout.root, slot)
+
+	return { checkout, nonce, resumed_from }
 }
 
 // Retaken on every round-1 brief, after the pointer it pairs with. Swallowed:
@@ -202,6 +227,7 @@ interface ComposeRequest {
 	tree: Record<string, string>
 	base: string
 	profile: AgentProfile
+	interaction?: ReadonlyArray<string> | undefined
 }
 
 // **Swallowed, and the brief keeps its target line**: parts that could not be
@@ -221,9 +247,35 @@ async function read_diff(
 	}
 }
 
+// **Swallowed, and the brief omits the list**: `josh ship` and `followup` read the same list again
+// and refuse on a failure, so the merge never rests on this reading.
+async function read_removed_tests(): Promise<ReadonlyArray<string>> {
+	try {
+		return (await removed_tests_check.read()) ?? []
+	} catch {
+		return []
+	}
+}
+
+// **A failure is marked, and the brief says the list could not be read** — never an empty list,
+// which would read as a change with no reader outside it.
+async function read_readers(
+	root: string,
+	base: string,
+	paths: ReadonlyArray<string>,
+): Promise<ReadersRead> {
+	try {
+		return await review_untouched_readers.read({ root, base, paths })
+	} catch {
+		return review_untouched_readers.FAILED_READ
+	}
+}
+
 async function compose_brief(request: ComposeRequest): Promise<string> {
-	const { round, paths, tree, base, profile } = request
-	const contract = await open_contract()
+	const { round, paths, tree, base, profile, interaction } = request
+	const opened = await open_contract(slot_of(interaction))
+	// The interaction review reads the whole change, never a resume's narrowing (joshuafolkken/kit#4276).
+	const contract = interaction === undefined ? opened : { ...opened, resumed_from: undefined }
 	const stamps = {
 		gate: review_stamps.gate_stamp.read(),
 		in_flight: review_stamps.in_flight_stamp.read(),
@@ -245,6 +297,10 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 		rubric_path: RUBRIC_PATH,
 		...contract,
 		diff: await read_diff(contract.checkout.root, base, paths),
+		readers: await read_readers(contract.checkout.root, base, paths),
+		removed_tests: await read_removed_tests(),
+		interaction,
+		high_cited: review_reviewed_tree.high_cited(),
 	})
 }
 
@@ -255,7 +311,7 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 // failure it exists to prevent. Where it cannot be resolved the printed command keeps `change_base`'s
 // answer, which still runs, and the record is written without a base so the next round widens.
 async function read_bases(): Promise<{ base: string; commit: string | undefined }> {
-	const commit = await change_base.resolved()
+	const commit = await change_base.resolved_through_merge()
 
 	return { base: commit ?? (await git_command.change_base()), commit }
 }
@@ -304,6 +360,8 @@ interface ChangeReading {
 	tree: Record<string, string>
 }
 
+type Emit = (text: string) => void
+
 // One reading, used by every half below. Read twice, the level could describe a different change from
 // the digests printed beside it — and it would cost four git spawns to do so.
 async function read_change(): Promise<ChangeReading> {
@@ -325,7 +383,14 @@ async function record_review(
 	record_briefed(round, tree, commit)
 }
 
-async function run_review(round: number, reading: ChangeReading): Promise<number> {
+// An interaction brief records nothing: the round-one and briefed stamps describe `/code-review`'s
+// round, which already ran, and retaking them would move the delta round 2 is measured from.
+async function run_review(
+	round: number,
+	reading: ChangeReading,
+	emit: Emit,
+	interaction?: ReadonlyArray<string>,
+): Promise<number> {
 	const { base, commit, paths, tree } = reading
 	const refusal = scoped_green.refusal_for(tree, commit)
 
@@ -334,27 +399,76 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 
 	if (resolved.kind === 'rejected') return report_error(resolved.note)
 	agent_role_profile.warn_of_default()
-	console.info(await compose_brief({ round, paths, tree, base, profile: resolved.profile }))
-	await record_review(round, tree, commit)
+	const { profile } = resolved
+
+	emit(await compose_brief({ round, paths, tree, base, profile, interaction }))
+	if (interaction === undefined) await record_review(round, tree, commit)
 
 	return 0
 }
 
-async function run(argv: ReadonlyArray<string>): Promise<number> {
-	if (argv[0] === LEVEL_ONLY_FLAG) return await run_level(argv.slice(1))
+// The interaction review's brief (joshuafolkken/kit#4276): `/code-review`'s round-1 brief over the
+// whole change, with the role and the run-tooling paths appended. Not due, it says so and exits 0.
+//
+// **An issue update taken in after round 1's brief refuses it**: this brief is minted on its own slot
+// beside round 1's (joshuafolkken/kit#4672), so it is refused here rather than briefed over an earlier
+// specification round 1 read.
+async function run_interaction(emit: Emit): Promise<number> {
+	const reading = await read_change()
+	const targets = review_interaction.due_paths(reading.paths)
+
+	if (targets.length === 0) {
+		emit(review_interaction.NOT_DUE_LINE)
+
+		return 0
+	}
+
+	const stale = await issue_watch_gate.review_refusal_here()
+
+	if (stale !== undefined) return report_error(stale)
+
+	return await run_review(FIRST_ROUND, reading, emit, targets)
+}
+
+// The scoped-green refusal a brief on this tree would print, read without composing one — so
+// `josh run:review` refuses before it launches anything beside the brief (joshuafolkken/kit#4828).
+async function scoped_refusal(): Promise<string | undefined> {
+	const { tree, commit } = await read_change()
+
+	return scoped_green.refusal_for(tree, commit)
+}
+
+// **A reviewer never mints a brief** (joshuafolkken/kit#5113): every brief takes a fresh nonce and drops
+// the previous one's records, so a reviewer that re-briefs after attesting erases the attestation its
+// supervisor is about to check, and a finished review reads as none. `--level-only` mints nothing.
+const REVIEWER_REFUSAL =
+	'review:brief refused: this is a reviewer session (JOSH_AGENT_ROLE=reviewer). A new brief would drop the attestation this review already left — review the brief you were handed and report.'
+
+async function run_brief(argv: ReadonlyArray<string>, emit: Emit): Promise<number> {
+	if (argv.length === 1 && argv[0] === INTERACTION_FLAG) return await run_interaction(emit)
 
 	const round = parse_round(argv)
 
 	if (round === undefined) return report_error(USAGE)
 
-	return await run_review(round, await read_change())
+	return await run_review(round, await read_change(), emit)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
+// `emit` takes the brief: `josh run:review` writes it to a file, because its two briefs together exceed
+// the Bash output cap (joshuafolkken/kit#4863). `run` prints it.
+async function run_to(argv: ReadonlyArray<string>, emit: Emit): Promise<number> {
+	if (argv[0] === LEVEL_ONLY_FLAG) return await run_level(argv.slice(1))
+	if (agent_session_role.is_reviewer()) return report_error(REVIEWER_REFUSAL)
+
+	return await run_brief(argv, emit)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	return await run_to(argv, console.info)
 }
 
 const review_brief_cli = {
+	attested_tree,
 	FIRST_ROUND,
 	format_reason,
 	KEPT_NOTE_PREFIX,
@@ -363,8 +477,9 @@ const review_brief_cli = {
 	record_round_one,
 	report_error,
 	run,
+	run_to,
+	scoped_refusal,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
+export type { Emit }
 export { review_brief_cli }

package/scripts/review/review-brief-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { review_brief_cli } from './review-brief-cli'
+
+// The `josh review:brief` entry, kept apart from `review-brief-cli.ts` because `run-review-cli.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await review_brief_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/review/review-brief-paths.ts

@@ -0,0 +1,22 @@
+// The path lists a review brief prints.
+
+// Absolute, for the same reason the round-1 target carries `-C`: git prints repository-root-relative
+// paths, and a forked agent sitting in another checkout resolves them against that one — where the
+// same relative path names a different file, or none.
+function format_paths(root: string, paths: ReadonlyArray<string>): string {
+	return paths.map((relative) => `  ${root}/${relative}`).join('\n')
+}
+
+// **A recorded High's fix is round 2's to verify, read whole** (joshuafolkken/kit#4941): `josh ship`
+// reuses the lane's round 1 once only round 2's delta moved, so this pass is the one that reads the fix
+// — and a fix can reach past the hunks the delta shows.
+const HIGH_FIX_LINE =
+	'These files hold the fix of a High round 1 recorded — read each whole, not only its hunks, with the fix sites the finding names:'
+
+function high_fix_lines(root: string, cited: ReadonlyArray<string> = []): ReadonlyArray<string> {
+	return cited.length === 0 ? [] : [`${HIGH_FIX_LINE}\n${format_paths(root, cited)}`]
+}
+
+const review_brief_paths = { format_paths, HIGH_FIX_LINE, high_fix_lines }
+
+export { review_brief_paths }

package/scripts/review/review-brief.ts

@@ -1,7 +1,11 @@
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { removed_tests } from './removed-tests'
+import { review_brief_paths } from './review-brief-paths'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 import { review_diff_parts, type DiffParts } from './review-diff-parts'
+import { review_interaction } from './review-interaction'
+import { review_untouched_readers, type ReadersRead } from './review-untouched-readers'
 
 // The text `josh review:brief` prints — the `/code-review` invocation, composed from what the run
 // already knows.
@@ -19,6 +23,9 @@ import { review_diff_parts, type DiffParts } from './review-diff-parts'
 
 const TEST_COMMAND_LINE =
 	'- The unit suite is `pnpm josh test:unit`. Do not reach for `npx vitest`; it is not how this project runs them.'
+// The self-check's question 2 ("Prose matches the code", `prompts/review.md`) as one command.
+const PROSE_STALE_LINE =
+	'- Self-check 2, prose matches the code: `pnpm josh prose:stale` lists each removed name, command, constant or heading docs, prompts or comments still name.'
 
 // **The checkout block, and why the target below names a path instead of assuming one**.
 // `/code-review` is forked by the harness and inherits the session's
@@ -193,12 +200,7 @@ function gate_line(
 	return NOT_VERIFIED_LINE
 }
 
-// Absolute, for the same reason the round-1 target carries `-C`: git prints repository-root-relative
-// paths, and a forked agent sitting in another checkout resolves them against that one — where the
-// same relative path names a different file, or none.
-function format_paths(root: string, paths: ReadonlyArray<string>): string {
-	return paths.map((relative) => `  ${root}/${relative}`).join('\n')
-}
+const { format_paths, high_fix_lines } = review_brief_paths
 
 // **An empty target has two readings, and only one of them is "nothing changed"**.
 // Since the delta is intersected with the change, round 1's fixes can be
@@ -411,9 +413,20 @@ interface BriefInput {
 	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume.
 	// Absent, round 1 reads the whole change.
 	resumed_from?: FileMapStamp | undefined
+	// The files a recorded High cites (`review_reviewed_tree.high_cited`), named in round 2 as the
+	// High's fix. Absent or empty, no line.
+	high_cited?: ReadonlyArray<string> | undefined
 	// The change written as parts under the Bash output cap. Absent when the
 	// write failed, and the target line alone then names the change.
 	diff?: { parts: DiffParts; cap: number } | undefined
+	// The tests the change removes, listed for the reviewer to account for. Absent or empty, no section.
+	removed_tests?: ReadonlyArray<string> | undefined
+	// The run-tooling paths an interaction review is briefed on (joshuafolkken/kit#4276). Absent, the
+	// brief is `/code-review`'s alone.
+	interaction?: ReadonlyArray<string> | undefined
+	// The readers outside the diff of each exported name it edits (joshuafolkken/kit#4515). A failed
+	// read is printed as one; absent or empty, no section.
+	readers?: ReadersRead | undefined
 }
 
 const SECOND_ROUND = 2
@@ -429,7 +442,10 @@ function round_one_target(input: BriefInput): string {
 function target_block(input: BriefInput): string {
 	if (input.round < SECOND_ROUND) return round_one_target(input)
 
-	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
+	const { root } = input.checkout
+	const block = round_two_block(input.stamps.round_one, input.tree, root, input.base)
+
+	return [block, ...high_fix_lines(root, input.high_cited)].join('\n')
 }
 
 // **Only beside a whole-change target**: each part is a path's diff against
@@ -437,16 +453,30 @@ function target_block(input: BriefInput): string {
 // code that narrowing exists to keep out of scope. Decided by the target actually printed, not by
 // the round: every round that cannot narrow widens through `whole_change_target`, and that round
 // needs the parts as much as a first one does.
-function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
-	const is_whole_change = target.includes(whole_change_target(input.checkout.root, input.base))
+function is_whole_change(input: BriefInput, target: string): boolean {
+	return target.includes(whole_change_target(input.checkout.root, input.base))
+}
 
-	if (!is_whole_change || input.diff === undefined) return []
+function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	if (!is_whole_change(input, target) || input.diff === undefined) return []
 
 	return ['', review_diff_parts.reading_block(input.diff.parts, input.diff.cap)]
 }
 
+// Beside a whole-change target only, for the reason `diff_block` gives: a narrowed round keeps the
+// rest of the change, and so its readers, out of scope.
+function readers_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	if (!is_whole_change(input, target)) return []
+
+	return review_untouched_readers.brief_block(input.readers)
+}
+
 // The level alone on the first line, because the level-only mode's contract — a caller reading the
 // answer with `$(...)` — is the one thing a brief must not break.
+function interaction_block(targets: ReadonlyArray<string> | undefined): ReadonlyArray<string> {
+	return targets === undefined ? [] : ['', review_interaction.brief_block(targets)]
+}
+
 function compose(input: BriefInput): string {
 	const profile = input.profile ?? agent_role_profile.DEFAULT_PROFILES.reviewer
 	const target = target_block(input)
@@ -462,9 +492,13 @@ function compose(input: BriefInput): string {
 		'',
 		gate_line(input.stamps, input.tree, input.base),
 		TEST_COMMAND_LINE,
+		PROSE_STALE_LINE,
 		'',
 		target,
 		...diff_block(input, target),
+		...readers_block(input, target),
+		...removed_tests.brief_block(input.removed_tests ?? []),
+		...interaction_block(input.interaction),
 	].join('\n')
 }
 
@@ -481,6 +515,7 @@ const review_brief = {
 	matching_stamp,
 	no_snapshot_line,
 	NOTHING_LEFT_LINE,
+	PROSE_STALE_LINE,
 	rubric_line,
 	RUBRIC_RELATIVE_PATH,
 	ROUND_TWO_HEADING,

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

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { git_command } from '#scripts/git/git-command'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { comment_ranges, type TypeScriptApi } from './comment-ranges'
 import { review_stamps } from './review-stamps'
 
@@ -26,7 +27,6 @@ const SCRIPT_EXTENSIONS: ReadonlyArray<string> = ['.ts', '.js']
 const SVELTE_EXTENSION = '.svelte'
 const EXCLUDED_PREFIX = '.claude/'
 const TYPESCRIPT_MODULE = 'typescript'
-const PACKAGE_JSON = 'package.json'
 
 function is_svelte(relative: string): boolean {
 	return relative.endsWith(SVELTE_EXTENSION)
@@ -100,20 +100,24 @@ async function record(
 }
 
 // The paths whose code round 1's fixes left as it was — whose difference, if any, is in comments.
-// Nothing qualifies against a record taken on another base, for the reason the round-1 snapshot is
-// refused on one.
+// Against a record taken on another base only `unmoved` qualifies — the paths the move left alone
+// (`review_round_one_blobs.unmoved`), where the carried file is round 1's own and equal code digests
+// still mean a comment-only fix (joshuafolkken/kit#4165).
 function comment_only(
 	snapshot: FileMapStamp | undefined,
 	tree: Record<string, string>,
 	base: string | undefined,
+	unmoved: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> {
-	if (snapshot === undefined || base === undefined || snapshot.base !== base) return []
+	if (snapshot === undefined || base === undefined) return []
+	const is_same_base = snapshot.base === base
 
 	return Object.keys(snapshot.files).filter(
-		(relative) => snapshot.files[relative] === tree[relative],
+		(relative) =>
+			snapshot.files[relative] === tree[relative] && (is_same_base || unmoved.includes(relative)),
 	)
 }
 
-const review_code_tree = { comment_only, read, record, tree_of }
+const review_code_tree = { comment_only, load_typescript, read, record, tree_of }
 
 export { review_code_tree }

package/scripts/review/review-comment-carry.ts

@@ -0,0 +1,47 @@
+import { rmSync } from 'node:fs'
+import path from 'node:path'
+import { error_text } from '#scripts/lib/error-message'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
+import { review_comment_round } from './review-comment-round'
+
+// The carry of the closed issues' comment rounds as its two callers run it — `review:record` outside a
+// lane, and `observations:flush` for the lanes (joshuafolkken/kit#5326) — so both print the same
+// lines. **A carry that fails never fails its caller**: the rounds wait for the next carry, and the
+// carried file is the mark, so nothing is copied twice.
+
+const CARRIED_LINE =
+	'review-finding line(s) recorded on closed issues after their pull requests opened into the ledger.'
+const CARRY_FAILED_LINE =
+	'Could not carry the closed issues’ comment rounds into the ledger; the next carry retries:'
+const UNTRACKED_PREFIX = '?? '
+
+// **A carried file no commit took is discarded before the default branch catches up**: left untracked
+// by a flush that stopped after its carry, it would make git refuse that fast-forward on every later
+// flush. Nothing is lost — the carry regenerates it from the issue's comments.
+function discard_uncommitted(status_output: string, root: string): void {
+	const untracked = status_output.split('\n').filter((line) => line.startsWith(UNTRACKED_PREFIX))
+	const carried = untracked
+		.map((line) => observation_ledger.status_path(line))
+		.filter((file_path) => review_comment_round.is_carried_file(file_path))
+
+	for (const file_path of carried) rmSync(path.join(root, file_path), { force: true })
+}
+
+async function carry_reported(root: string): Promise<void> {
+	try {
+		const count = await review_comment_round.carry(root)
+
+		if (count > 0) console.info(`Carried ${String(count)} ${CARRIED_LINE}`)
+	} catch (error) {
+		console.warn(`${CARRY_FAILED_LINE} ${error_text.message_of(error)}`)
+	}
+}
+
+const review_comment_carry = {
+	CARRIED_LINE,
+	CARRY_FAILED_LINE,
+	carry_reported,
+	discard_uncommitted,
+}
+
+export { review_comment_carry }