@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/review/comment-ranges.ts

@@ -0,0 +1,199 @@
+import type ts from 'typescript'
+
+// The text of a source file with its comments taken out, so two versions that differ only in comments
+// read as the same text.
+//
+// **Every range comes from the TypeScript parser, never from a pattern.** A `//` inside a regular
+// expression or a template literal is code, and a hand-written scanner that took it for a comment
+// would strip a real edit and call the fix comment-only — the one wrong answer that buys a `skip`.
+// Driven by the parse tree, a range is only ever read from the trivia before a token.
+//
+// **What it cannot read, it does not strip**: a file that does not parse answers `undefined`, and a
+// comment the walk does not reach stays in the text. Both resolve to "the code changed", which costs a
+// round rather than skipping one.
+
+type TypeScriptApi = typeof ts
+type Range = readonly [number, number]
+
+// A comment's own opening — the shebang is trivia to the parser too, but it decides how the file is
+// executed, so it stays.
+const COMMENT_OPENINGS: ReadonlyArray<string> = ['//', '/*']
+// A private-use character, which no source file this reads holds.
+const MARK = ''
+const LINE_BREAK = '\n'
+const SEPARATOR = ' '
+// Script blocks are parsed; style blocks are left whole, so `<!--` in a stylesheet is never read as
+// a markup comment.
+const RAW_BLOCK = /<(?<tag>script|style)\b[^>]*>(?<body>[\s\S]*?)<\/\k<tag>>/gu
+const SCRIPT_TAG = 'script'
+const MARKUP_COMMENT = /<!--[\s\S]*?-->/gu
+const VIRTUAL_FILE_NAME = 'fix-delta.ts'
+// A comment a tool reads is code: a fix that silences lint, the type check or coverage, or changes
+// what a bundler or the type checker reads, does it by adding one — the edit only the review sees.
+// JSDoc type tags count too, since a checked `.js` file takes its types from them — any tag carrying a
+// `{…}` type expression, plus the type tags that carry none. Matching too much only costs a round.
+const DIRECTIVE_MARKERS: ReadonlyArray<string> = [
+	'///',
+	'@ts-',
+	'eslint',
+	'jshint',
+	'global ',
+	'globals ',
+	'prettier-ignore',
+	'svelte-ignore',
+	'cspell',
+	'v8 ignore',
+	'c8 ignore',
+	'istanbul ignore',
+	'__PURE__',
+	'__NO_SIDE_EFFECTS__',
+	'@vite-ignore',
+	'webpack',
+	'@jsx',
+	'@vitest-environment',
+]
+const JSDOC_TYPE_TAG =
+	/@(?:type|typedef|param|returns?|template|satisfies|import|callback|overload|enum|this)\b/u
+const JSDOC_TYPE_EXPRESSION = /@\w+\s*\{/u
+
+function is_directive(text: string, range: Range): boolean {
+	const comment = text.slice(range[0], range[1])
+
+	if (JSDOC_TYPE_TAG.test(comment) || JSDOC_TYPE_EXPRESSION.test(comment)) return true
+
+	return DIRECTIVE_MARKERS.some((marker) => comment.includes(marker))
+}
+
+function is_comment(text: string, range: Range): boolean {
+	return COMMENT_OPENINGS.some((opening) => text.startsWith(opening, range[0]))
+}
+
+function trivia_at(api: TypeScriptApi, text: string, position: number): Array<Range> {
+	const found = [
+		...(api.getLeadingCommentRanges(text, position) ?? []),
+		...(api.getTrailingCommentRanges(text, position) ?? []),
+	]
+
+	return found.map((range): Range => [range.pos, range.end])
+}
+
+// **JSDoc nodes are not descended into**: their children sit inside the comment, and a `//` there
+// would read as a line comment running past the `*/` into the code that follows it.
+function collect(
+	api: TypeScriptApi,
+	node: ts.Node,
+	source: ts.SourceFile,
+	into: Array<Range>,
+): void {
+	if (api.isJSDoc(node)) return
+
+	into.push(...trivia_at(api, source.text, node.pos))
+
+	for (const child of node.getChildren(source)) collect(api, child, source, into)
+}
+
+// Parsed as TypeScript whatever the extension, because a `.js` file is valid TypeScript syntax and JSX
+// is not — JSX text holding `//` is exactly what a trivia read would mistake for a comment, and here
+// it is a parse error instead.
+function script_ranges(api: TypeScriptApi, text: string): Array<Range> | undefined {
+	const source = api.createSourceFile(VIRTUAL_FILE_NAME, text, api.ScriptTarget.Latest, false)
+	const diagnostics = (source as ts.SourceFile & { parseDiagnostics?: ReadonlyArray<unknown> })
+		.parseDiagnostics
+
+	if (diagnostics === undefined || diagnostics.length > 0) return undefined
+	const ranges: Array<Range> = []
+
+	collect(api, source, source, ranges)
+
+	return ranges.filter((range) => is_comment(text, range))
+}
+
+function shifted(ranges: ReadonlyArray<Range>, offset: number): Array<Range> {
+	return ranges.map((range): Range => [range[0] + offset, range[1] + offset])
+}
+
+function is_inside(blocks: ReadonlyArray<Range>, index: number): boolean {
+	return blocks.some((block) => index >= block[0] && index < block[1])
+}
+
+function markup_ranges(text: string, blocks: ReadonlyArray<Range>): Array<Range> {
+	return [...text.matchAll(MARKUP_COMMENT)]
+		.filter((match) => !is_inside(blocks, match.index))
+		.map((match): Range => [match.index, match.index + match[0].length])
+}
+
+function block_ranges(api: TypeScriptApi, match: RegExpExecArray): Array<Range> | undefined {
+	if (match.groups?.['tag'] !== SCRIPT_TAG) return []
+	const body = match.groups['body'] ?? ''
+	const ranges = script_ranges(api, body)
+
+	return ranges && shifted(ranges, match.index + match[0].indexOf(body))
+}
+
+function svelte_ranges(api: TypeScriptApi, text: string): Array<Range> | undefined {
+	const matches = [...text.matchAll(RAW_BLOCK)]
+	const scripts = matches.map((match) => block_ranges(api, match))
+
+	if (scripts.includes(undefined)) return undefined
+	const blocks = matches.map((match): Range => [match.index, match.index + match[0].length])
+
+	return [...scripts.flatMap((ranges) => ranges ?? []), ...markup_ranges(text, blocks)]
+}
+
+// A comment spanning lines is a line terminator to the program — `return` followed by one returns
+// nothing — so its break is kept, and a one-line comment in its place cannot strip to the same text.
+function mark_for(text: string, start: number, end: number): string {
+	return text.slice(start, end).includes(LINE_BREAK) ? `${MARK}${LINE_BREAK}${MARK}` : MARK
+}
+
+function marked(text: string, ranges: ReadonlyArray<Range>): string {
+	const ordered = ranges.toSorted((left, right) => left[0] - right[0])
+	let result = ''
+	let cursor = 0
+
+	for (const [start, end] of ordered) {
+		if (start < cursor) continue
+		result += `${text.slice(cursor, start)}${mark_for(text, start, end)}`
+		cursor = end
+	}
+
+	return `${result}${text.slice(cursor)}`
+}
+
+// A comment is whitespace to the program, so it becomes one space, and a line it alone occupied goes
+// away. Indentation and lines without a comment are kept byte for byte — a blank line in a template
+// literal is data.
+function normalized_line(line: string): Array<string> {
+	if (!line.includes(MARK)) return [line]
+	const indentation = line.slice(0, line.length - line.trimStart().length)
+	const words = line
+		.split(MARK)
+		.map((part) => part.trim())
+		.filter((part) => part !== '')
+
+	return words.length === 0 ? [] : [`${indentation}${words.join(SEPARATOR)}`]
+}
+
+function without(text: string, ranges: ReadonlyArray<Range>): string {
+	return marked(text, ranges)
+		.split(LINE_BREAK)
+		.flatMap((line) => normalized_line(line))
+		.join(LINE_BREAK)
+}
+
+function strip(api: TypeScriptApi, text: string, is_svelte: boolean): string | undefined {
+	const ranges = is_svelte ? svelte_ranges(api, text) : script_ranges(api, text)
+
+	return (
+		ranges &&
+		without(
+			text,
+			ranges.filter((range) => !is_directive(text, range)),
+		)
+	)
+}
+
+const comment_ranges = { strip }
+
+export { comment_ranges }
+export type { TypeScriptApi }

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { review_attest, type AttestVerdict } from './review-attest'
 import { review_checkout } from './review-checkout'
 
@@ -51,6 +52,22 @@ async function run_attest(nonce: string): Promise<number> {
 	return FAILURE_EXIT_CODE
 }
 
+// An attested review still describes the issue as it read it: a person's update it has not taken in,
+// or one taken in after the brief, makes its verdict stale (`issue-watch-gate.ts`).
+async function report_issue_watch(verdict: AttestVerdict): Promise<number> {
+	const refusal = await issue_watch_gate.review_refusal_here()
+
+	if (refusal !== undefined) {
+		console.error(refusal)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(attested_line(verdict))
+
+	return 0
+}
+
 // **`check_here`, not `check`** — the pointer is keyed on the repository root, and `check`'s default
 // is `PROJECT_ROOT`, which is `process.cwd()`. Run from a subdirectory, or from the session checkout
 // rather than the lane's, the two hash different keys: no pointer is found, the command prints "no
@@ -65,15 +82,13 @@ async function run_check(): Promise<number> {
 		return 0
 	}
 
-	if (verdict.status === 'ok') {
-		console.info(attested_line(verdict))
+	if (verdict.status !== 'ok') {
+		console.error(review_attest.refusal_message(verdict))
 
-		return 0
+		return FAILURE_EXIT_CODE
 	}
 
-	console.error(review_attest.refusal_message(verdict))
-
-	return FAILURE_EXIT_CODE
+	return await report_issue_watch(verdict)
 }
 
 // Anything unrecognized is a usage error rather than a default. A misspelled flag that fell through

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

@@ -12,11 +12,12 @@ 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 { openai_review_broker } from '#scripts/lane/openai-review-broker'
+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 { 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_level, type ReviewLevel } from './review-level'
@@ -112,13 +113,15 @@ function kept_note(taken_at: string): string {
 // `change_base`, and `change_base` is recomputed on every invocation — so without the commit it was
 // measured against, round 2 cannot tell a fix from a base that moved under it, and reports the
 // difference between two incomparable sets as round 1's fixes.
+// **Answers whether it wrote**, because the comment-free code record is taken only at that moment: a
+// code record retaken over a kept snapshot would describe the fixed tree, the exact retake above.
 function record_round_one(
 	round: number,
 	tree: Record<string, string>,
 	base: string | undefined,
 	target?: string,
-): void {
-	if (round !== FIRST_ROUND) return
+): boolean {
+	if (round !== FIRST_ROUND) return false
 
 	try {
 		const recorded = review_stamps.round_one_stamp.read(target)
@@ -126,12 +129,15 @@ function record_round_one(
 		if (recorded !== undefined) {
 			console.error(kept_note(recorded.taken_at))
 
-			return
+			return false
 		}
 
 		review_stamps.round_one_stamp.write(tree, target, base)
+
+		return true
 	} catch {
 		/* no record widens the next round rather than narrowing it */
+		return false
 	}
 }
 
@@ -150,7 +156,7 @@ function record_round_one(
 // 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 {
-	const { findings } = openai_review_broker.review_paths(PROJECT_ROOT)
+	const { findings } = lane_session_broker.review_paths(PROJECT_ROOT)
 	const briefed = review_stamps.briefed_stamp.read()
 
 	if (briefed === undefined || !review_attest.is_briefed_since(briefed.taken_at, checkout.root)) {
@@ -308,6 +314,17 @@ async function read_change(): Promise<ChangeReading> {
 	return { base, commit, paths, tree }
 }
 
+async function record_review(
+	round: number,
+	tree: Record<string, string>,
+	commit: string | undefined,
+): Promise<void> {
+	const is_snapshot_written = record_round_one(round, tree, commit)
+
+	if (is_snapshot_written) await review_code_tree.record(Object.keys(tree), commit)
+	record_briefed(round, tree, commit)
+}
+
 async function run_review(round: number, reading: ChangeReading): Promise<number> {
 	const { base, commit, paths, tree } = reading
 	const refusal = scoped_green.refusal_for(tree, commit)
@@ -318,8 +335,7 @@ 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 }))
-	record_round_one(round, tree, commit)
-	record_briefed(round, tree, commit)
+	await record_review(round, tree, commit)
 
 	return 0
 }
@@ -343,6 +359,7 @@ const review_brief_cli = {
 	format_reason,
 	KEPT_NOTE_PREFIX,
 	parse_round,
+	record_review,
 	record_round_one,
 	report_error,
 	run,

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

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+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 { comment_ranges, type TypeScriptApi } from './comment-ranges'
+import { review_stamps } from './review-stamps'
+
+// The second map round 1 records beside `review-tree.ts`'s: for each source file, the digest of its
+// text with the comments taken out (joshuafolkken/kit#3826).
+//
+// **Why a second record rather than a second reading of the first.** The round-1 snapshot holds
+// digests, not text, so after the fixes nothing can say what a changed `.ts` file used to contain. A
+// comment-free digest taken at the same moment is what lets round 2 tell "only the comments changed"
+// from "the code changed" — equal digests mean equal code.
+//
+// **`.claude/` is outside it**: the decision on joshuafolkken/kit#3787 left `.claude/**` reviewed in
+// full, comments included.
+//
+// **TypeScript is resolved from the project, and its absence records nothing.** It is an optional peer
+// of this package, and a missing map is a comment-only arm that never fires — a round run, never one
+// skipped.
+
+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)
+}
+
+function is_source(relative: string): boolean {
+	if (relative.startsWith(EXCLUDED_PREFIX)) return false
+
+	return is_svelte(relative) || SCRIPT_EXTENSIONS.some((extension) => relative.endsWith(extension))
+}
+
+function load_typescript(root: string): TypeScriptApi | undefined {
+	try {
+		return createRequire(path.join(root, PACKAGE_JSON))(TYPESCRIPT_MODULE) as TypeScriptApi
+	} catch {
+		return undefined
+	}
+}
+
+function code_digest(api: TypeScriptApi, root: string, relative: string): string | undefined {
+	try {
+		const code = comment_ranges.strip(
+			api,
+			readFileSync(path.join(root, relative), 'utf8'),
+			is_svelte(relative),
+		)
+
+		return code === undefined ? undefined : stamp_file.digest(code)
+	} catch {
+		return undefined
+	}
+}
+
+// A path that is deleted, does not parse, or is not a source file has no entry — and a path with no
+// entry is never comment-only.
+function tree_of(
+	root: string,
+	paths: ReadonlyArray<string>,
+	api: TypeScriptApi | undefined = load_typescript(root),
+): Record<string, string> {
+	if (api === undefined) return {}
+	const entries = paths
+		.filter((relative) => is_source(relative))
+		.flatMap((relative) => {
+			const digest = code_digest(api, root, relative)
+
+			return digest === undefined ? [] : [[relative, digest] as const]
+		})
+
+	return Object.fromEntries(entries)
+}
+
+async function read(paths: ReadonlyArray<string>, root?: string): Promise<Record<string, string>> {
+	return tree_of(root ?? (await git_command.repository_root()), paths)
+}
+
+// Written only in the same brief that wrote the round-1 snapshot, so the two describe one moment. A
+// failure removes any earlier record rather than leaving one from another moment beside the new
+// snapshot.
+async function record(
+	paths: ReadonlyArray<string>,
+	base: string | undefined,
+	target?: string,
+	root?: string,
+): Promise<void> {
+	try {
+		review_stamps.round_one_code_stamp.write(await read(paths, root), target, base)
+	} catch {
+		review_stamps.clear_round_one_code(target)
+	}
+}
+
+// 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.
+function comment_only(
+	snapshot: FileMapStamp | undefined,
+	tree: Record<string, string>,
+	base: string | undefined,
+): ReadonlyArray<string> {
+	if (snapshot === undefined || base === undefined || snapshot.base !== base) return []
+
+	return Object.keys(snapshot.files).filter(
+		(relative) => snapshot.files[relative] === tree[relative],
+	)
+}
+
+const review_code_tree = { comment_only, read, record, tree_of }
+
+export { review_code_tree }

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

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs'
+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 { z } from 'zod'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// A review round recorded after its pull request opened (`josh review:record --comment`), and how its
+// lines reach the ledger's readers (joshuafolkken/kit#3811). The round is posted on the issue because
+// 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
+// `<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.
+
+const COMMENT_HEADING_MARK = '### '
+const COMMENT_TITLE = 'Review round recorded after the pull request opened'
+const COMMENT_HEADING = `${COMMENT_HEADING_MARK}${COMMENT_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 CARRIED_SUFFIX = '-comment-rounds'
+// 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'
+const UNNAMED_REPOSITORY = 'Could not name this repository from `git remote`.'
+const UNREAD_SEARCH = 'Could not read the search for closed issues with a comment round.'
+const UNREAD_COMMENTS = 'Could not read the comments of'
+
+const search_item_schema = z.object({ number: z.number() })
+const search_schema = z.object({ items: z.array(search_item_schema) })
+const comment_schema = z.object({
+	body: z.string().nullish(),
+	author_association: z.string().nullish(),
+})
+
+type IssueComment = z.infer<typeof comment_schema>
+
+function body_of(lines: ReadonlyArray<string>): string {
+	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
+}
+
+// The ledger lines of every comment round among one issue's comments, oldest first; any other
+// comment, one that only quotes the heading among them, carries none — nor does one whose author
+// cannot write to the repository: anyone can comment on a public issue, and the carried lines ride
+// the run's commit unreviewed.
+function lines_of(comments: ReadonlyArray<IssueComment>): Array<string> {
+	return comments
+		.filter((comment) => gh_author_association.is_trusted(comment.author_association))
+		.map((comment) => comment.body ?? '')
+		.filter((body) => body.startsWith(COMMENT_HEADING))
+		.flatMap((body) => body.split('\n'))
+		.filter((line) => review_finding_ledger.is_finding_line(line))
+}
+
+function search_path(repo: string): string {
+	const query = `repo:${repo} is:issue is:closed in:comments "${COMMENT_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 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)
+
+	return page.items.map((item) => item.number)
+}
+
+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> {
+	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 = lines_of(parse_json_array_safe(raw, comment_schema))
+
+	await observation_ledger_home.append(carried_path(issue, root), lines)
+
+	return lines.length
+}
+
+// Copies every closed issue's comment rounds not yet in the ledger, and answers how many lines.
+async function carry(root: string): Promise<number> {
+	const issues = await closed_issues()
+	const pending = issues.filter((issue) => !existsSync(carried_path(issue, root)))
+	const counts = await Promise.all(pending.map(async (issue) => await carry_issue(issue, root)))
+
+	return counts.reduce((total, count) => total + count, 0)
+}
+
+const review_comment_round = { body_of, carried_path, carry, lines_of }
+
+export { review_comment_round }

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

@@ -4,6 +4,7 @@ import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_comment_round } from './review-comment-round'
 import { review_finding_ledger, type Finding } from './review-finding-ledger'
 import { review_record, type RecordVerdict } from './review-record'
 
@@ -16,7 +17,8 @@ import { review_record, type RecordVerdict } from './review-record'
 // **`--comment` records a round that ran after the pull request opened**: the same lines go to the
 // issue as a comment and nothing is appended. A line written to the tree then has no commit of the
 // run's left to ride, so `pnpm josh followup` would push it onto the open pull request and its CI
-// would start over.
+// would start over. The next round recorded to the ledger carries it there once the issue is closed
+// (`review-comment-round.ts`).
 //
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
 // merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
@@ -31,10 +33,10 @@ const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
-const COMMENT_HEADING = '### Review round recorded after the pull request opened'
-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 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 round retries:'
 const OPTIONS = {
 	issue: { type: 'string' },
 	check: { type: 'boolean' },
@@ -161,15 +163,14 @@ async function run_check(issue: string | undefined, root: string): Promise<numbe
 	return FAILURE_EXIT_CODE
 }
 
-function comment_body(lines: ReadonlyArray<string>): string {
-	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
-}
-
 // **A comment that could not be posted fails the record**: it is the round's only copy, so a
 // swallowed refusal would read as a recorded round that exists nowhere.
 async function post_comment(issue: number, lines: ReadonlyArray<string>): Promise<number> {
 	try {
-		const url = await git_gh_issue_write.issue_comment(String(issue), comment_body(lines))
+		const url = await git_gh_issue_write.issue_comment(
+			String(issue),
+			review_comment_round.body_of(lines),
+		)
 
 		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
 
@@ -181,8 +182,35 @@ async function post_comment(issue: number, lines: ReadonlyArray<string>): Promis
 	}
 }
 
+// The closed issues' comment rounds ride this round's commit (`review-comment-round.ts`). **A carry
+// that fails never fails the record**: this round is recorded, and the comment rounds wait for the
+// next run's.
+async function carry_comment_rounds(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 instanceof Error ? error.message : String(error)}`)
+	}
+}
+
 // The round lands in its own issue's file, so two lanes recording at once
 // write two files, and their pull requests never conflict on the ledger.
+async function append_round(
+	issue: number,
+	lines: ReadonlyArray<string>,
+	root: string,
+): Promise<number> {
+	const ledger_path = observation_ledger_home.issue_path(issue, root)
+
+	await observation_ledger_home.append(ledger_path, lines)
+	console.info(confirmation(lines.length, ledger_path))
+	await carry_comment_rounds(root)
+
+	return 0
+}
+
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
 	const request = to_request(parsed)
 
@@ -196,12 +224,7 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 
 	if (parsed.comment) return await post_comment(request.issue, lines)
 
-	const ledger_path = observation_ledger_home.issue_path(request.issue, root)
-
-	await observation_ledger_home.append(ledger_path, lines)
-	console.info(confirmation(lines.length, ledger_path))
-
-	return 0
+	return await append_round(request.issue, lines, root)
 }
 
 // **The default is the work tree the command runs in, a lane's inside a lane**.
@@ -232,7 +255,6 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const review_record_cli = {
 	accepted_values,
 	build_lines,
-	comment_body,
 	parse_finding,
 	run,
 	usage_text,