@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,6 +1,7 @@
 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'
@@ -15,7 +16,7 @@ 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 { removed_tests_check } from './removed-tests-check'
-import { review_attest } from './review-attest'
+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'
@@ -23,6 +24,7 @@ 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'
@@ -100,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.
 //
@@ -165,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()
 
@@ -180,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:
@@ -258,7 +273,7 @@ async function read_readers(
 
 async function compose_brief(request: ComposeRequest): Promise<string> {
 	const { round, paths, tree, base, profile, interaction } = request
-	const opened = await open_contract()
+	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 = {
@@ -285,6 +300,7 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 		readers: await read_readers(contract.checkout.root, base, paths),
 		removed_tests: await read_removed_tests(),
 		interaction,
+		high_cited: review_reviewed_tree.high_cited(),
 	})
 }
 
@@ -295,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 }
 }
@@ -344,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> {
@@ -370,6 +388,7 @@ async function record_review(
 async function run_review(
 	round: number,
 	reading: ChangeReading,
+	emit: Emit,
 	interaction?: ReadonlyArray<string>,
 ): Promise<number> {
 	const { base, commit, paths, tree } = reading
@@ -382,7 +401,7 @@ async function run_review(
 	agent_role_profile.warn_of_default()
 	const { profile } = resolved
 
-	console.info(await compose_brief({ round, paths, tree, base, profile, interaction }))
+	emit(await compose_brief({ round, paths, tree, base, profile, interaction }))
 	if (interaction === undefined) await record_review(round, tree, commit)
 
 	return 0
@@ -391,15 +410,15 @@ async function run_review(
 // 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**: minting this brief moves the pointer
-// `josh followup` measures that update against (`issue-watch-gate.ts`), so a round 1 that read the
-// earlier specification would merge without that refusal.
-async function run_interaction(): Promise<number> {
+// **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) {
-		console.info(review_interaction.NOT_DUE_LINE)
+		emit(review_interaction.NOT_DUE_LINE)
 
 		return 0
 	}
@@ -408,21 +427,48 @@ async function run_interaction(): Promise<number> {
 
 	if (stale !== undefined) return report_error(stale)
 
-	return await run_review(FIRST_ROUND, reading, targets)
+	return await run_review(FIRST_ROUND, reading, emit, targets)
 }
 
-async function run(argv: ReadonlyArray<string>): Promise<number> {
-	if (argv[0] === LEVEL_ONLY_FLAG) return await run_level(argv.slice(1))
-	if (argv.length === 1 && argv[0] === INTERACTION_FLAG) return await run_interaction()
+// 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)
+}
+
+// `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,
@@ -431,6 +477,9 @@ const review_brief_cli = {
 	record_round_one,
 	report_error,
 	run,
+	run_to,
+	scoped_refusal,
 }
 
+export type { Emit }
 export { review_brief_cli }

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,6 +1,7 @@
 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'
@@ -22,6 +23,9 @@ import { review_untouched_readers, type ReadersRead } from './review-untouched-r
 
 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
@@ -196,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
@@ -414,6 +413,9 @@ 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
@@ -440,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
@@ -487,6 +492,7 @@ function compose(input: BriefInput): string {
 		'',
 		gate_line(input.stamps, input.tree, input.base),
 		TEST_COMMAND_LINE,
+		PROSE_STALE_LINE,
 		'',
 		target,
 		...diff_block(input, target),
@@ -509,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-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 }

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

@@ -1,10 +1,12 @@
 import { existsSync } from 'node:fs'
+import path from 'node:path'
 import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { parse_json, parse_json_array_safe } from '#scripts/git/parse-json-array'
 import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { observation_ledger_line } from '#scripts/observations/observation-ledger-line'
 import { z } from 'zod'
 import { review_finding_ledger } from './review-finding-ledger'
 
@@ -13,20 +15,30 @@ import { review_finding_ledger } from './review-finding-ledger'
 // a ledger line written then would be pushed onto the open pull request and restart its CI — and so
 // nothing that reads the ledger (`review:findings`, the retrospective) ever saw it.
 //
-// **The next run that records a round carries it.** Once an issue is closed no round is added to it,
-// so `review:record` copies each closed issue's comment rounds not yet carried into
+// **The next run outside a lane that records a round carries it, or the next flush.** Once an issue
+// is closed no round is added to it, so `review:record` copies each closed issue's comment rounds not yet carried into
 // `<issue>-comment-rounds.md` in the ledger, and the lines ride that run's own commit: the ledger stays
 // the one place a reader looks, and no push restarts any CI. **The file is the carried mark** — an
-// issue whose file exists is never read again, and two lanes carrying one issue write the same file,
-// so their pull requests merge to the same lines.
+// issue whose file exists is never read again. **A lane child carries none** (joshuafolkken/kit#5326):
+// parallel lanes each wrote the same file and waited and conflicted on it, so `observations:flush`
+// carries for them on the default branch (`review-comment-carry.ts`).
+//
+// **An observation-ledger line written while the pull request is open rides the same carry**
+// (joshuafolkken/kit#5197): `followup` reruns a CI job red only outside the change during its CI wait,
+// after the ledger's last commit, so the sighting is posted under its own heading and carried with the
+// rounds.
 
 const COMMENT_HEADING_MARK = '### '
 const COMMENT_TITLE = 'Review round recorded after the pull request opened'
-const COMMENT_HEADING = `${COMMENT_HEADING_MARK}${COMMENT_TITLE}`
+const OBSERVATION_TITLE = 'Observation recorded while the pull request was open'
+const COMMENT_TITLES = [COMMENT_TITLE, OBSERVATION_TITLE]
+const COMMENT_HEADINGS = COMMENT_TITLES.map((title) => `${COMMENT_HEADING_MARK}${title}`)
 const COMMENT_NOTE =
 	'Kept here rather than in the observation ledger: a line appended after the commit would be pushed onto the open pull request and restart its CI.'
 const CODE_FENCE = '```'
+const OBSERVATION_LINE_MARK = '- k:'
 const CARRIED_SUFFIX = '-comment-rounds'
+const CARRIED_FILE_PATTERN = new RegExp(String.raw`^\d+${CARRIED_SUFFIX}\.md$`, 'u')
 // One page of the newest closed issues: an issue leaves the search's interest once carried, so the
 // ones still to carry are the recently closed.
 const PER_PAGE = '100'
@@ -45,8 +57,33 @@ const comment_schema = z.object({
 
 type IssueComment = z.infer<typeof comment_schema>
 
+function body_under(title: string, lines: ReadonlyArray<string>): string {
+	const heading = `${COMMENT_HEADING_MARK}${title}`
+
+	return [heading, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
+}
+
 function body_of(lines: ReadonlyArray<string>): string {
-	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
+	return body_under(COMMENT_TITLE, lines)
+}
+
+function observation_body_of(lines: ReadonlyArray<string>): string {
+	return body_under(OBSERVATION_TITLE, lines)
+}
+
+function is_carried_line(line: string): boolean {
+	if (review_finding_ledger.is_finding_line(line)) return true
+
+	return (
+		line.startsWith(OBSERVATION_LINE_MARK) &&
+		observation_ledger_line.line_reason(line) === undefined
+	)
+}
+
+function is_round(comment: IssueComment): boolean {
+	const body = comment.body ?? ''
+
+	return COMMENT_HEADINGS.some((heading) => body.startsWith(heading))
 }
 
 // The ledger lines of every comment round among one issue's comments, oldest first; any other
@@ -67,7 +104,7 @@ async function is_trusted_comment(comment: IssueComment): Promise<boolean> {
 }
 
 async function lines_of(comments: ReadonlyArray<IssueComment>): Promise<Array<string>> {
-	const rounds = comments.filter((comment) => (comment.body ?? '').startsWith(COMMENT_HEADING))
+	const rounds = comments.filter((comment) => is_round(comment))
 	const trusted = await Promise.all(
 		rounds.map(async (comment) => await is_trusted_comment(comment)),
 	)
@@ -75,43 +112,61 @@ async function lines_of(comments: ReadonlyArray<IssueComment>): Promise<Array<st
 	return rounds
 		.filter((_comment, index) => trusted[index] === true)
 		.flatMap((comment) => (comment.body ?? '').split('\n'))
-		.filter((line) => review_finding_ledger.is_finding_line(line))
+		.filter((line) => is_carried_line(line))
 }
 
-function search_path(repo: string): string {
-	const query = `repo:${repo} is:issue is:closed in:comments "${COMMENT_TITLE}"`
+function search_path(repo: string, title: string): string {
+	const query = `repo:${repo} is:issue is:closed in:comments "${title}"`
 	const parameters = new URLSearchParams({ q: query, sort: 'updated', per_page: PER_PAGE })
 
 	return `search/issues?${parameters.toString()}`
 }
 
-// The closed issues whose comments name a comment round; a repository that cannot be named or a
-// search that cannot be read throws, so the run says so rather than carrying nothing in silence.
+async function search(repo: string, title: string): Promise<ReadonlyArray<number>> {
+	const raw = await git_gh_exec.exec_gh_api({ path: search_path(repo, title) })
+	const page = parse_json.parse_json_object_or_undefined(raw, search_schema)
+
+	if (page === undefined) throw new Error(UNREAD_SEARCH)
+
+	return page.items.map((item) => item.number)
+}
+
+// The closed issues whose comments name a comment round of either heading; a repository that cannot be
+// named or a search that cannot be read throws, so the run says so rather than carrying nothing in
+// silence.
 async function closed_issues(): Promise<ReadonlyArray<number>> {
 	const repo = session_cite.session_repo()
 
 	if (repo === undefined) throw new Error(UNNAMED_REPOSITORY)
 
-	const raw = await git_gh_exec.exec_gh_api({ path: search_path(repo) })
-	const page = parse_json.parse_json_object_or_undefined(raw, search_schema)
-
-	if (page === undefined) throw new Error(UNREAD_SEARCH)
+	const pages = await Promise.all(COMMENT_TITLES.map(async (title) => await search(repo, title)))
 
-	return page.items.map((item) => item.number)
+	return [...new Set(pages.flat())]
 }
 
 function carried_path(issue: number, root: string): string {
 	return observation_ledger_home.file_path(`${String(issue)}${CARRIED_SUFFIX}`, root)
 }
 
-// An issue whose comments could not be read writes no file, so the next run reads it again, and
-// throws so this one says so.
-async function carry_issue(issue: number, root: string): Promise<number> {
+// A path this carry writes, told by its file name alone so a git status path answers it too.
+function is_carried_file(file_path: string): boolean {
+	return CARRIED_FILE_PATTERN.test(path.basename(file_path))
+}
+
+// One issue's comment-round lines. Comments that could not be read throw, so no caller reads an
+// unread issue as one without a round.
+async function issue_lines(issue: number): Promise<Array<string>> {
 	const raw = await git_gh_issue_read.issue_list_comments(String(issue))
 
 	if (raw === undefined) throw new Error(`${UNREAD_COMMENTS} ${session_cite.issue(issue)}`)
 
-	const lines = await lines_of(parse_json_array_safe(raw, comment_schema))
+	return await lines_of(parse_json_array_safe(raw, comment_schema))
+}
+
+// An issue whose comments could not be read writes no file, so the next run reads it again, and
+// throws so this one says so.
+async function carry_issue(issue: number, root: string): Promise<number> {
+	const lines = await issue_lines(issue)
 
 	await observation_ledger_home.append(carried_path(issue, root), lines)
 
@@ -127,6 +182,14 @@ async function carry(root: string): Promise<number> {
 	return counts.reduce((total, count) => total + count, 0)
 }
 
-const review_comment_round = { body_of, carried_path, carry, lines_of }
+const review_comment_round = {
+	body_of,
+	carried_path,
+	carry,
+	is_carried_file,
+	issue_lines,
+	lines_of,
+	observation_body_of,
+}
 
 export { review_comment_round }