@joshuafolkken/kit 1.1514.0 → 1.2114.0

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,87 +15,158 @@ 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'
 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 UNREAD_PERMISSION = 'Could not read the write permission 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(),
+	user: z.looseObject({ login: z.string() }).nullish(),
 })
 
 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
 // 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}"`
+// the run's commit unreviewed. A permission lookup that failed throws instead: the carried file is
+// written once, so a round dropped on a transient failure would never be carried.
+async function is_trusted_comment(comment: IssueComment): Promise<boolean> {
+	const login = comment.user?.login
+	const is_trusted = await gh_author_association.trust_of({
+		login,
+		association: comment.author_association,
+	})
+
+	if (is_trusted === undefined) throw new Error(`${UNREAD_PERMISSION} ${login ?? ''}`)
+
+	return is_trusted
+}
+
+async function lines_of(comments: ReadonlyArray<IssueComment>): Promise<Array<string>> {
+	const rounds = comments.filter((comment) => is_round(comment))
+	const trusted = await Promise.all(
+		rounds.map(async (comment) => await is_trusted_comment(comment)),
+	)
+
+	return rounds
+		.filter((_comment, index) => trusted[index] === true)
+		.flatMap((comment) => (comment.body ?? '').split('\n'))
+		.filter((line) => is_carried_line(line))
+}
+
+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 = 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)
 
@@ -109,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 }

package/scripts/review/review-finding-ledger.ts

@@ -7,9 +7,22 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
 // one commit path, a second line *type* rather than a second ledger.
 
-const FINDING_PREFIX = '- rf:'
+// **The interaction review writes the same grammar under its own prefix** (joshuafolkken/kit#4276), so
+// its round is told apart from `/code-review`'s by the merge gate, and its findings stay out of the
+// `/code-review` tally a reader compares rounds by.
+const PREFIX = { code: '- rf:', interaction: '- ri:' } as const
 const FIELD_SEPARATOR = ' | '
 const FIELD_COUNT = 5
+// **The disposition is a sixth field, written only when given** (joshuafolkken/kit#5286): a line
+// written before it existed keeps its five and reads as a finding with no disposition.
+const DISPOSED_FIELD_COUNT = FIELD_COUNT + 1
+const ISSUE_FIELD_INDEX = FIELD_COUNT - 1
+const SEVERITY_FIELD_INDEX = 1
+// **A code round written to the issue's file opens with a boundary line** (joshuafolkken/kit#5359):
+// the ledger is append-only, so a stopped round's unfixed lines stay, and `josh review:round2` reads
+// only the lines after the issue's last boundary. Its own prefix keeps it out of every `- rf:` reader.
+const ROUND_PREFIX = '- rb:'
+const ROUND_ISSUE_FIELD_INDEX = 1
 
 // The nine review-rubric categories, as slugs (`prompts/review-rubric.md` → "Review categories"). A
 // finding's category must be one of these so the aggregate stays countable rather than free text.
@@ -27,6 +40,12 @@ const CATEGORIES = [
 
 const SEVERITIES = ['high', 'medium', 'low'] as const
 
+// What became of a finding: fixed in this tree, a verified false positive, or left to another issue.
+// Only the first two close it for `josh review:round2`.
+const CLOSING_DISPOSITIONS = ['fixed', 'false-positive'] as const
+const DISPOSITION_PATTERN = /^(?:fixed|false-positive|(?:filed|deferred):#[1-9]\d*)$/u
+const DISPOSITION_SEPARATOR = ' '
+
 // The sentinel a zero-finding round writes, so "a round ran and found nothing" is a recorded line
 // rather than an absent one — the count's denominator survives.
 const NONE = 'none'
@@ -34,11 +53,18 @@ const NO_FILE = '-'
 
 type Category = (typeof CATEGORIES)[number]
 type Severity = (typeof SEVERITIES)[number]
+type LineKind = keyof typeof PREFIX
 
 interface Finding {
 	category: Category
 	severity: Severity
 	file: string
+	disposition?: string
+}
+
+interface DisposedSpec {
+	disposition: string | undefined
+	spec: string
 }
 
 interface CategoryCount {
@@ -61,33 +87,76 @@ function is_valid_file(file: string): boolean {
 	return file.length > 0 && !file.includes(FIELD_SEPARATOR)
 }
 
+function is_disposition(value: string): boolean {
+	return DISPOSITION_PATTERN.test(value)
+}
+
+function is_closing(disposition: string | undefined): boolean {
+	return (CLOSING_DISPOSITIONS as ReadonlyArray<string | undefined>).includes(disposition)
+}
+
+// A positional's leading disposition — `fixed <spec>`, `filed:#12 <spec>` — split from the spec it
+// marks. The token the reviewer already writes before a finding it fixed, so one grammar serves both.
+function split_disposition(positional: string): DisposedSpec {
+	const end = positional.indexOf(DISPOSITION_SEPARATOR)
+	const head = end === -1 ? '' : positional.slice(0, end)
+
+	if (!is_disposition(head)) return { disposition: undefined, spec: positional }
+
+	return { disposition: head, spec: positional.slice(end + DISPOSITION_SEPARATOR.length) }
+}
+
 function issue_field(issue: number): string {
 	return issue_cite.plain(issue)
 }
 
-function line_of(fields: ReadonlyArray<string>): string {
-	return `${FINDING_PREFIX}${fields.join(FIELD_SEPARATOR)}`
+function line_of(fields: ReadonlyArray<string>, kind: LineKind): string {
+	return `${PREFIX[kind]}${fields.join(FIELD_SEPARATOR)}`
 }
 
-function finding_line(finding: Finding, date: string, issue: number): string {
-	return line_of([finding.category, finding.severity, finding.file, date, issue_field(issue)])
+function finding_line(
+	finding: Finding,
+	date: string,
+	issue: number,
+	kind: LineKind = 'code',
+): string {
+	const fields = [finding.category, finding.severity, finding.file, date, issue_field(issue)]
+
+	return line_of(
+		finding.disposition === undefined ? fields : [...fields, finding.disposition],
+		kind,
+	)
 }
 
 // **A zero-finding round records `none`, not nothing.** Reading its absence as "no findings" would
 // merge the round that found nothing with the round nobody recorded, which is the exact confusion the
 // ledger exists to end.
-function zero_round_line(date: string, issue: number): string {
-	return line_of([NONE, NONE, NO_FILE, date, issue_field(issue)])
+function zero_round_line(date: string, issue: number, kind: LineKind = 'code'): string {
+	return line_of([NONE, NONE, NO_FILE, date, issue_field(issue)], kind)
 }
 
-function is_finding_line(line: string): boolean {
-	return line.trimStart().startsWith(FINDING_PREFIX)
+function is_finding_line(line: string, kind: LineKind = 'code'): boolean {
+	return line.trimStart().startsWith(PREFIX[kind])
 }
 
-function category_of(line: string): string | undefined {
-	const fields = line.trimStart().slice(FINDING_PREFIX.length).split(FIELD_SEPARATOR)
+function fields_of(line: string, kind: LineKind = 'code'): ReadonlyArray<string> {
+	return line.trimStart().slice(PREFIX[kind].length).split(FIELD_SEPARATOR)
+}
 
-	return fields.length === FIELD_COUNT ? fields[0] : undefined
+// The line's fields, or `undefined` for a malformed one — five, or six with a disposition.
+function well_formed_fields(
+	line: string,
+	kind: LineKind = 'code',
+): ReadonlyArray<string> | undefined {
+	const fields = fields_of(line, kind)
+
+	return fields.length === FIELD_COUNT || fields.length === DISPOSED_FIELD_COUNT
+		? fields
+		: undefined
+}
+
+function category_of(line: string): string | undefined {
+	return well_formed_fields(line)?.[0]
 }
 
 function increment(counts: Map<string, number>, category: string): void {
@@ -135,20 +204,63 @@ function zero_round_count(content: string): number {
 // The issue a finding line is keyed to — its fifth field, the `#<N>` token — or `undefined` for a
 // non-finding or malformed line. The record check reads this to ask whether a given issue's round was
 // recorded at all.
-function issue_of(line: string): string | undefined {
-	const fields = line.trimStart().slice(FINDING_PREFIX.length).split(FIELD_SEPARATOR)
+function issue_of(line: string, kind: LineKind): string | undefined {
+	return well_formed_fields(line, kind)?.[ISSUE_FIELD_INDEX]
+}
+
+interface DisposedLine {
+	severity: string
+	disposition: string | undefined
+}
+
+// One issue's `- rf:` lines, each with its severity and disposition — `undefined` disposition for a
+// line written without one. `josh review:round2` reads round 1's closure from this.
+function issue_dispositions(content: string, issue: number): ReadonlyArray<DisposedLine> {
+	const target = issue_field(issue)
+
+	return content
+		.split('\n')
+		.filter((line) => is_finding_line(line) && issue_of(line, 'code') === target)
+		.map((line) => well_formed_fields(line) ?? [])
+		.map((fields) => ({
+			severity: fields[SEVERITY_FIELD_INDEX] ?? NONE,
+			disposition: fields[FIELD_COUNT],
+		}))
+}
+
+function round_line(date: string, issue: number): string {
+	return `${ROUND_PREFIX}${[date, issue_field(issue)].join(FIELD_SEPARATOR)}`
+}
+
+function is_round_line(line: string, target: string): boolean {
+	const trimmed = line.trimStart()
+
+	if (!trimmed.startsWith(ROUND_PREFIX)) return false
+
+	const fields = trimmed.slice(ROUND_PREFIX.length).split(FIELD_SEPARATOR)
+
+	return fields[ROUND_ISSUE_FIELD_INDEX] === target
+}
+
+// The content after the issue's last round boundary — the whole content when it has none, as a ledger
+// written before the boundary existed does.
+function latest_round(content: string, issue: number): string {
+	const target = issue_field(issue)
+	const lines = content.split('\n')
 
-	return fields.length === FIELD_COUNT ? fields[FIELD_COUNT - 1] : undefined
+	return lines.slice(lines.findLastIndex((line) => is_round_line(line, target)) + 1).join('\n')
 }
 
 // **A `none` zero-round line counts as recorded, exactly like a real finding line does.** The gate
 // asks whether the round was recorded, not whether it found anything — reading the issue field, which
 // a zero-finding line carries too, is what keeps a clean round's single line from reading as "nobody
 // recorded this".
-function has_issue_record(content: string, issue: number): boolean {
+function has_issue_record(content: string, issue: number, kind: LineKind = 'code'): boolean {
 	const target = issue_field(issue)
 
-	return content.split('\n').some((line) => is_finding_line(line) && issue_of(line) === target)
+	return content
+		.split('\n')
+		.some((line) => is_finding_line(line, kind) && issue_of(line, kind) === target)
 }
 
 const review_finding_ledger = {
@@ -157,13 +269,18 @@ const review_finding_ledger = {
 	finding_line,
 	has_issue_record,
 	is_category,
+	is_closing,
 	is_finding_line,
 	is_severity,
 	is_valid_file,
+	issue_dispositions,
+	latest_round,
+	round_line,
 	SEVERITIES,
+	split_disposition,
 	zero_round_count,
 	zero_round_line,
 }
 
-export type { CategoryCount, Finding }
+export type { CategoryCount, DisposedLine, Finding, LineKind }
 export { review_finding_ledger }

package/scripts/review/review-finding-text.ts

@@ -0,0 +1,43 @@
+// A finding written in the `review:record` grammar with its reason after it — `<spec> — <sentence>` —
+// split into the two halves, the one place both its writers read it: a ship reviewer's findings file
+// (`run-ship-review.ts`) and an agent's own `review:record` round (`review-record-cli.ts`). The spec is
+// what the ledger keeps; the first sentence of the reason is what the durable stop log keeps.
+
+// What a finding line carries after its spec: one sentence saying what is wrong, so a stopped ship's
+// log tells the resumed lane child the defect rather than only its location.
+const DESCRIPTION_SEPARATOR = ' — '
+// Where the spec ends on read: a reviewer that types the dash as `-`, `--` or `–` still ends it there,
+// so its sentence never lands in the ledger's file field.
+const DESCRIPTION_BOUNDARY = / [—–-]{1,2} /u
+// Where a description's first sentence ends, and the cap that keeps a run-on one a line. Japanese
+// sets no space after `。`, so it ends a sentence on its own.
+const SENTENCE_END = /(?<=[.!?])\s|(?<=。)/u
+const SENTENCE_LIMIT = 200
+const ELLIPSIS = '…'
+
+function split_description(unmarked: string): { spec: string; description: string } {
+	const boundary = DESCRIPTION_BOUNDARY.exec(unmarked)
+
+	if (boundary === null) return { spec: unmarked.trim(), description: '' }
+
+	const rest = unmarked.slice(boundary.index + boundary[0].length)
+
+	return { spec: unmarked.slice(0, boundary.index).trim(), description: rest.trim() }
+}
+
+function first_sentence(description: string): string {
+	const [sentence = ''] = description.split(SENTENCE_END, 1)
+
+	if (sentence.length <= SENTENCE_LIMIT) return sentence
+
+	return `${sentence.slice(0, SENTENCE_LIMIT - ELLIPSIS.length)}${ELLIPSIS}`
+}
+
+const review_finding_text = {
+	DESCRIPTION_SEPARATOR,
+	SENTENCE_LIMIT,
+	first_sentence,
+	split_description,
+}
+
+export { review_finding_text }

package/scripts/review/review-interaction.ts

@@ -0,0 +1,105 @@
+import { project_checks } from '#scripts/gate/project-checks'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { session_cite } from '#scripts/issue/session-cite'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_attest, type ReviewSlot } from './review-attest'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// The interaction review — one adversarial pass after `/code-review`, over a change to the run
+// tooling (joshuafolkken/kit#4276).
+//
+// **`/code-review` reads the diff for its own correctness, and the defects came from elsewhere**: most
+// of them were a new mechanism meeting an existing one — a pause meeting the next run, a count meeting
+// the per-second repaint. This pass is given one role, to find the existing features the change
+// breaks, and is due only where those meetings happen: the four directories below, in the kit
+// repository alone — a consumer's own `scripts/run/` is not kit's run tooling.
+//
+// **Its round is its own ledger line, `- ri:`**, so the merge gate tells it apart from `/code-review`'s
+// and `josh followup` refuses a due change that has none. The verdicts mirror `review_record.check`'s:
+// `not-required` covers both a change outside the directories and a checkout that keeps no ledger.
+
+const TARGET_DIRECTORIES = ['scripts/run/', 'scripts/lane/', 'scripts/backlog/', 'scripts/hooks/']
+
+const NOT_DUE_LINE =
+	'Interaction review not due: this is not the kit repository, or the change touches none of scripts/run/, scripts/lane/, scripts/backlog/ or scripts/hooks/.'
+
+const ROLE_LINES = [
+	'## Interaction review',
+	'This pass is not a second `/code-review`: do not hunt for bugs inside the diff — the round before it did. Your role is to find three existing features this change breaks. Check only these three:',
+	'1. Every state, command, label, file or process this change adds or gives a new meaning to — who else reads or writes it? Search the repository outside the diff for each. Where the plan has a `### 影響を受ける既存の利用者` section, check it names them all.',
+	'2. Does each of those readers and writers still behave correctly when the new state or value reaches it (for example, a paused lane counted as running)?',
+	'3. Does the change add heavy or synchronous work to a path called repeatedly — every second, every Bash call, every edit?',
+	"Report each break with the reader's `file:line` and the change's, rated by the rubric's severities; it is disposed of by `prompts/review.md` → \"Interaction review\".",
+]
+
+type InteractionStatus = 'ok' | 'missing' | 'not-required'
+
+function due_paths(
+	paths: ReadonlyArray<string>,
+	checkout: string = process.cwd(),
+): ReadonlyArray<string> {
+	if (!project_checks.is_kit_repository(checkout)) return []
+
+	return paths.filter((file) => TARGET_DIRECTORIES.some((directory) => file.startsWith(directory)))
+}
+
+function brief_block(targets: ReadonlyArray<string>): string {
+	const listed = targets.map((file) => `- ${file}`)
+
+	return [...ROLE_LINES, 'Changed in the run tooling:', ...listed].join('\n')
+}
+
+async function status_of(
+	issue: number,
+	paths: ReadonlyArray<string>,
+	root: string = observation_ledger_home.ledger_root(),
+): Promise<InteractionStatus> {
+	const content = due_paths(paths).length > 0 ? await observation_ledger_home.read(root) : undefined
+
+	if (content === undefined) return 'not-required'
+
+	return review_finding_ledger.has_issue_record(content, issue, 'interaction') ? 'ok' : 'missing'
+}
+
+// The status over this checkout's change — the reading `review:brief` takes.
+async function status(issue: number, root?: string): Promise<InteractionStatus> {
+	return await status_of(issue, await changed_paths.read_changed_paths(false), root)
+}
+
+// **Round 1's slots — the interaction review beside `/code-review`'s where it is due and not yet
+// recorded** (joshuafolkken/kit#4672, joshuafolkken/kit#4802), so it takes round 1's wait and stop.
+// `josh ship` and `josh run:review` both open round 1 from it.
+function round_one_slots(answer: InteractionStatus | undefined): ReadonlyArray<ReviewSlot> {
+	const { CODE, INTERACTION } = review_attest.REVIEW_SLOT
+
+	return answer === 'missing' ? [CODE, INTERACTION] : [CODE]
+}
+
+const MISSING_REASON =
+	'This change touches the run tooling, and no interaction review is recorded for its issue — the pass that looks for the existing features a change breaks, which `/code-review` does not (joshuafolkken/kit#4276).'
+
+const REMEDY =
+	'Run it from `pnpm josh review:brief --interaction`, then record it with `pnpm josh review:record --interaction --issue <N> [<category>:<severity>:<file> ...]` — a clean pass is a call with no findings — and reissue the merge.'
+
+function refusal_message(issue: number): string {
+	return [MISSING_REASON, `Issue: ${session_cite.issue(issue)}`, REMEDY].join('\n')
+}
+
+// The merge gate's half: the refusal for a due change with no recorded pass, else `undefined`.
+async function refusal(issue: number, root?: string): Promise<string | undefined> {
+	return (await status(issue, root)) === 'missing' ? refusal_message(issue) : undefined
+}
+
+const review_interaction = {
+	brief_block,
+	due_paths,
+	NOT_DUE_LINE,
+	refusal,
+	refusal_message,
+	round_one_slots,
+	status,
+	status_of,
+}
+
+export type { InteractionStatus }
+export { review_interaction }

package/scripts/review/review-lane-handover.ts

@@ -0,0 +1,68 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
+import { review_round_reuse, type ReuseAnswer } from './review-round-reuse'
+
+// joshuafolkken/kit#4850: once a lane child has recorded round 1 on a tree `josh ship` reuses, round 2
+// is the ship's. The rule stood in `chain-rule.md` step 0 as prose alone (joshuafolkken/kit#4830), and
+// the next lane reopened `run:review` after reading it, running a round 2 the ship then ran again. So
+// `run:review` refuses that reopen and `review:record` names the ship as the next step.
+//
+// **A round the ship would review again is not handed over**: `review:record --check` then tells the
+// lane to run round 1 itself, so `run:review` stays open for it.
+
+const SHIP_STEP = 'pnpm josh ship --detach --review "<title> #<N>"'
+const NEXT_STEP_LINE = `Next: hand over to \`${SHIP_STEP}\` — round 2 is the ship's; never reopen \`run:review\` (chain-rule.md step 0).`
+
+// A reuse question git could not answer reads as not reused: the lane then reviews the round itself,
+// which costs one review, rather than leaving it to a ship that may review it again detached.
+// The stale read inside it fails open in `review_round_reuse.is_stale_here`, as the ship's probe reads it.
+const UNANSWERED_CAUSE = 'git could not answer the reuse question'
+
+async function answer_here(issue: number): Promise<ReuseAnswer> {
+	try {
+		return await review_round_reuse.answer_here(issue)
+	} catch (error) {
+		error_text.trace_swallowed('review_lane_handover.answer_here', error)
+
+		return { reuse: review_round_reuse.REUSE.AGAIN, cause: UNANSWERED_CAUSE }
+	}
+}
+
+async function is_reused_here(issue: number): Promise<boolean> {
+	const answer = await answer_here(issue)
+
+	return answer.reuse !== review_round_reuse.REUSE.AGAIN
+}
+
+// The mark must name this issue as well as this checkout, so a person's run — or a branch whose issue
+// is not the lane's — is never refused.
+function is_lane_child_of(issue: number): boolean {
+	if (lane_child_marker.marked_issue() !== String(issue)) return false
+
+	return lane_child_marker.is_child_of(PROJECT_ROOT)
+}
+
+// Reuse already requires the recorded round (`review_round_reuse.is_reusable`), so it answers both.
+async function is_handed_over(issue: number): Promise<boolean> {
+	if (!is_lane_child_of(issue)) return false
+
+	return await is_reused_here(issue)
+}
+
+function refusal(issue: number): string {
+	return (
+		`⛔ run:review: round 1 of ${session_cite.issue(issue)} is recorded and josh ship reuses it, and this is a ` +
+		`dispatched lane child (\`${lane_child_marker.KEY}\`), so no brief is minted. ${NEXT_STEP_LINE}`
+	)
+}
+
+const review_lane_handover = {
+	NEXT_STEP_LINE,
+	answer_here,
+	is_handed_over,
+	refusal,
+}
+
+export { review_lane_handover }