@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/review/acceptance-map.ts

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto'
+import { epic_audit_logic } from '#scripts/epic/epic-audit'
+import { markdown_section } from '#scripts/issue/markdown-section'
+import { session_cite } from '#scripts/issue/session-cite'
+import { report_format_reference } from '#scripts/report/report-format-reference'
+
+// A green gate and a clean review say the diff is sound, never that it delivers what the Issue asked
+// for. **This is the seam where each acceptance criterion is checked one by one**: the pull request
+// body carries one row per criterion — met, with its evidence, or deferred to a split-off issue — and
+// `josh followup` re-reads the Issue just before the merge and refuses a criterion with no row.
+//
+// **A criterion is matched by an identifier built from its own text**, so a criterion added or
+// reworded after the body was written has an identifier no row carries, and is refused as unmapped
+// rather than passing on a stale row. The checkbox is stripped first: ticking it changes nothing.
+//
+// The criteria are read through `epic_audit_logic.acceptance_section`, the one place the acceptance
+// headings are defined.
+
+const MAP_HEADING = '## 受け入れ条件の対応'
+const MET = '満たした'
+const DEFERRED = '見送り'
+const PENDING = '未記入'
+const PENDING_SUFFIX = `— ${PENDING}`
+const ID_PREFIX = 'ac-'
+const ID_HEX_LENGTH = 8
+const BACKTICK = '`'
+// A top-level list item only: a nested item is detail under a criterion, not one of its own.
+const CRITERION_PATTERN = /^(?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?(?<text>\S.*)$/u
+// A list item, heading, table row or HTML comment opens a block of its own, never a wrapped line.
+const BLOCK_START_PATTERN = /^\s*(?:(?:[-*+]|\d+\.)\s|#|\||<!--)/u
+// The criterion's text may sit between the identifier and the status for the reader, so the status is
+// the last status word on the line — a criterion quoting the row format stays text.
+const ROW_PATTERN = new RegExp(
+	String.raw`^[-*]\s+${BACKTICK}(?<id>${ID_PREFIX}[0-9a-f]{${String(ID_HEX_LENGTH)}})${BACKTICK}(?:\s.*)?\s(?<kind>${MET}|${DEFERRED}):\s*(?<rest>\S.*)$`,
+	'u',
+)
+// A deferral names the split-off issue first, then why it was deferred.
+const DEFERRAL_PATTERN = /^(?<issue>(?:[\w.-]+\/[\w.-]+)?#\d+)\s+\S/u
+const ROW_FORMAT = `under ${MAP_HEADING}, one line per acceptance criterion: \`- \`<id>\` <criterion> — ${MET}: <test name, file:line or command output>\` or \`- \`<id>\` <criterion> — ${DEFERRED}: #<split-off issue> <reason>\``
+
+interface Criterion {
+	id: string
+	text: string
+}
+
+interface Deferral {
+	id: string
+	issue: string
+}
+
+interface Row {
+	id: string
+	kind: string
+	rest: string
+}
+
+interface MapRows {
+	met: ReadonlySet<string>
+	deferrals: ReadonlyArray<Deferral>
+	ids: ReadonlySet<string>
+}
+
+interface MapComparison {
+	missing: ReadonlyArray<Criterion>
+	deferrals: ReadonlyArray<Deferral>
+	stale: ReadonlyArray<string>
+}
+
+function criterion_id(text: string): string {
+	const normalized = text.replaceAll(/\s+/gu, ' ').trim()
+	const digest = createHash('sha256').update(normalized).digest('hex')
+
+	return `${ID_PREFIX}${digest.slice(0, ID_HEX_LENGTH)}`
+}
+
+function joins(last: string | undefined, line: string): boolean {
+	const is_continuation = line.trim() !== '' && !BLOCK_START_PATTERN.test(line)
+
+	return is_continuation && last !== undefined && CRITERION_PATTERN.test(last)
+}
+
+// A criterion wrapped onto continuation lines is one criterion, hashed whole — rewording any of its
+// lines changes its identifier. A blank line or a nested item ends it.
+function unwrapped(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	const items: Array<string> = []
+
+	for (const line of lines) {
+		items.push(joins(items.at(-1), line) ? `${items.pop() ?? ''} ${line.trim()}` : line)
+	}
+
+	return items
+}
+
+function criteria_of(issue_body: string | undefined): ReadonlyArray<Criterion> {
+	// A list item inside a code fence is an example the Issue quotes, not a criterion. An indented line
+	// outside one is a wrapped criterion's continuation, so it is kept.
+	const lines = markdown_section.fence_free_lines(epic_audit_logic.acceptance_section(issue_body))
+	const texts = unwrapped(lines).map((line) => CRITERION_PATTERN.exec(line)?.groups?.['text'])
+
+	return texts
+		.filter((text): text is string => text !== undefined)
+		.map((text) => ({ id: criterion_id(text), text: text.trim() }))
+}
+
+// A deferral row with no issue or no reason is no row at all, so its criterion reads as unmapped.
+function deferral_of(id: string, rest: string): Deferral | undefined {
+	const issue = DEFERRAL_PATTERN.exec(rest)?.groups?.['issue']
+
+	return issue === undefined ? undefined : { id, issue }
+}
+
+// Every group in `ROW_PATTERN` is mandatory, so a match always carries the name.
+function group(groups: Readonly<Record<string, string>>, name: string): string {
+	return groups[name] ?? ''
+}
+
+// A pending row is no row even when the criterion it quotes carries a status word — otherwise the
+// skeleton's own unfilled row would read as met.
+function row_of(line: string): Row | undefined {
+	const trimmed = line.trim()
+
+	if (trimmed.endsWith(PENDING_SUFFIX)) return undefined
+	const groups = ROW_PATTERN.exec(trimmed)?.groups
+
+	if (groups === undefined) return undefined
+
+	return { id: group(groups, 'id'), kind: group(groups, 'kind'), rest: group(groups, 'rest') }
+}
+
+function rows_of(pr_body = ''): MapRows {
+	const rows = markdown_section
+		.section_lines(pr_body, MAP_HEADING)
+		.map((line) => row_of(line))
+		.filter((row): row is Row => row !== undefined)
+	const met = rows.filter((row) => row.kind === MET).map((row) => row.id)
+	const deferrals = rows
+		.filter((row) => row.kind === DEFERRED)
+		.map((row) => deferral_of(row.id, row.rest))
+		.filter((deferral): deferral is Deferral => deferral !== undefined)
+
+	return { met: new Set(met), deferrals, ids: new Set([...met, ...deferrals.map((row) => row.id)]) }
+}
+
+function compare(criteria: ReadonlyArray<Criterion>, rows: MapRows): MapComparison {
+	const current = new Set(criteria.map((criterion) => criterion.id))
+
+	return {
+		missing: criteria.filter((criterion) => !rows.ids.has(criterion.id)),
+		deferrals: rows.deferrals.filter((deferral) => current.has(deferral.id)),
+		stale: [...rows.ids].filter((id) => !current.has(id)),
+	}
+}
+
+// What `josh pr` writes when the caller's body carries no table: every criterion as a pending row,
+// which the merge refuses until it is filled in.
+function skeleton(issue_body: string | undefined): string | undefined {
+	const criteria = criteria_of(issue_body)
+
+	if (criteria.length === 0) return undefined
+	const rows = criteria.map(
+		(criterion) => `- \`${criterion.id}\` ${criterion.text} ${PENDING_SUFFIX}`,
+	)
+
+	return [MAP_HEADING, '', ...rows].join('\n')
+}
+
+function has_map(pr_body = ''): boolean {
+	return markdown_section.has_unfenced_line(pr_body, MAP_HEADING)
+}
+
+function listed(title: string, lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	return lines.length === 0 ? [] : [title, ...lines.map((line) => `  ${line}`)]
+}
+
+function refusal_message(
+	issue: string,
+	comparison: MapComparison,
+	absent: ReadonlyArray<string>,
+): string {
+	return [
+		`The pull request body does not map every acceptance criterion of ${session_cite.issue(issue)} as it reads now, so the merge is refused.`,
+		...listed(
+			'Criteria with no row (added or reworded since the body was written, or never mapped):',
+			comparison.missing.map((criterion) => `- \`${criterion.id}\` ${criterion.text}`),
+		),
+		...listed('Deferral rows naming an issue that could not be found:', absent),
+		...listed('Rows naming no current criterion:', comparison.stale),
+		`Write ${ROW_FORMAT} — format: ${report_format_reference.pointer(report_format_reference.ACCEPTANCE_MAP_HEADING)}`,
+		'Write it into the `--body-file` before `josh ship`, or update an open PR with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
+	].join('\n')
+}
+
+const acceptance_map = {
+	MAP_HEADING,
+	compare,
+	criteria_of,
+	criterion_id,
+	has_map,
+	refusal_message,
+	ROW_FORMAT,
+	rows_of,
+	skeleton,
+}
+
+export type { Criterion, Deferral, MapComparison }
+export { acceptance_map }

package/scripts/review/removed-tests-check.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+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 { test_declared_logic } from '#scripts/test/test-declared-logic'
+import type { TypeScriptApi } from './comment-ranges'
+import { removed_tests } from './removed-tests'
+import { review_code_tree } from './review-code-tree'
+import { test_titles } from './test-titles'
+
+// The reads behind `removed_tests`: the change base, the test files changed since it, each one's text
+// at the base and in the working tree, and the pull request body. Kept apart so the comparison stays
+// pure.
+//
+// **The base is the tree's, through a merge in progress** (`change_base.resolved_through_merge`): the
+// head side is the work tree, so a stopped merge of the default branch has already removed whatever
+// tests the default branch removed, and measuring from `HEAD`'s older merge-base would list them as
+// this change's own.
+//
+// **A base that cannot be resolved is a refusal, not a pass** — the tests it would have held are
+// exactly what this gate exists to see. A file is read at the base only where the base holds it, so a
+// failed `git show` throws rather than reading as a file that had no tests. TypeScript is an optional
+// peer of this package (`review_code_tree.load_typescript`): a project without it has no titles to
+// compare and merges as before.
+
+const UNREADABLE_MESSAGE =
+	'Merge refused: the change base could not be resolved, so the tests this change removes could not be listed; re-run once `git merge-base` answers.'
+
+function titles_in(api: TypeScriptApi, texts: ReadonlyArray<string>): ReadonlyArray<string> {
+	return texts.flatMap((text) => test_titles.titles_of(api, text))
+}
+
+async function base_texts(
+	base: string,
+	paths: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> {
+	const held = await changed_paths.read_held_at(base, paths)
+
+	return await Promise.all(
+		held.map(async (relative) => await git_command.show_file(`${base}:${relative}`)),
+	)
+}
+
+// A test file the change deleted is absent from the tree, and every title it held reads as gone.
+function tree_texts(root: string, paths: ReadonlyArray<string>): ReadonlyArray<string> {
+	return paths
+		.map((relative) => path.join(root, relative))
+		.filter((absolute) => existsSync(absolute))
+		.map((absolute) => readFileSync(absolute, 'utf8'))
+}
+
+async function read(): Promise<ReadonlyArray<string> | undefined> {
+	const base = await change_base.resolved_through_merge()
+
+	if (base === undefined) return undefined
+	const root = await git_command.repository_root()
+	const api = review_code_tree.load_typescript(root)
+
+	if (api === undefined) return []
+	const changed = await changed_paths.read_changed_since(base)
+	const paths = changed.filter((relative) => test_declared_logic.is_test_file(relative))
+	const before = titles_in(api, await base_texts(base, paths))
+
+	return removed_tests.removed(before, titles_in(api, tree_texts(root, paths)))
+}
+
+// `josh ship`'s preflight asks the body it is about to deliver, so a missing disposition stops it
+// before the review rather than at the merge.
+async function body_refusal(pr_body: string | undefined): Promise<string | undefined> {
+	const removed = await read()
+
+	if (removed === undefined) return UNREADABLE_MESSAGE
+	const left = removed_tests.undisposed(removed, pr_body)
+
+	return left.length === 0 ? undefined : removed_tests.refusal_message(left)
+}
+
+async function refusal(branch_name: string): Promise<string | undefined> {
+	return await body_refusal(await git_gh_command.pr_get_body(branch_name))
+}
+
+const removed_tests_check = { body_refusal, read, refusal, UNREADABLE_MESSAGE }
+
+export { removed_tests_check }

package/scripts/review/removed-tests.ts

@@ -0,0 +1,149 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
+import { report_format_reference } from '#scripts/report/report-format-reference'
+import { test_titles } from './test-titles'
+
+// A test is the record of a behavior, and a change that deletes one with no word of what replaced it
+// loses that behavior silently: the gate stays green and the review reads only what is there
+// (joshuafolkken/kit#4287, after #4171 dropped `lane_thresholds()` with the tests that guarded it).
+// **This is the seam where a deleted test has to be accounted for**: every test the base had and the
+// change no longer has is listed in the review brief, and the merge is refused until the pull request
+// body names, for each, the test that replaced it or the Issue that retired its behavior.
+//
+// **A test that moved is not deleted.** Tests are compared by full name across every changed test
+// file, so one moved to another file keeps its name. One moved under another `describe` keeps its own
+// title, so a gone name is matched against an arrived name with the same title, one for one — a common
+// title such as "returns undefined" deleted under one block is still listed when another block keeps
+// its own copy.
+
+const DISPOSITION_HEADING = '## 消えたテストの処置'
+// The heading as a line of its own, never the mention of it inside a format hint.
+const HEADING_LINE = new RegExp(String.raw`^${DISPOSITION_HEADING}[ \t]*$`, 'mu')
+const REPLACED = '置き換え'
+const RETIRED = '廃止'
+const PENDING_SUFFIX = '— 未記入'
+const BRIEF_HEADING = 'Removed tests'
+// The title runs to the first backtick that a disposition follows, so a title holding backticks of its
+// own — `it('reads the \`.each\` table')` — can still be disposed.
+const ROW_PATTERN = new RegExp(
+	String.raw`^[-*]\s+\x60(?<title>.+?)\x60\s+—\s+(?<kind>${REPLACED}|${RETIRED}):\s*(?<rest>\S.*)$`,
+	'u',
+)
+// A retirement names the Issue that decided it first — an Issue or a plan comment on one — then why.
+const RETIREMENT_PATTERN = /^(?:[\w.-]+\/[\w.-]+)?#\d+\s+\S/u
+const ROW_FORMAT = `under ${DISPOSITION_HEADING}, one line per removed test: \`- \`<test>\` — ${REPLACED}: <the test that guards the behavior now>\` or \`- \`<test>\` — ${RETIRED}: #<Issue that retired the behavior> <reason>\``
+
+function unique(titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	return [...new Set(titles)]
+}
+
+function leaf_counts(titles: ReadonlyArray<string>): Map<string, number> {
+	const counts = new Map<string, number>()
+
+	for (const title of titles) {
+		const leaf = test_titles.leaf_of(title)
+
+		counts.set(leaf, (counts.get(leaf) ?? 0) + 1)
+	}
+
+	return counts
+}
+
+// Spends one arrived name with the same title, so each arrival accounts for one departure only.
+function is_moved(arrived: Map<string, number>, title: string): boolean {
+	const leaf = test_titles.leaf_of(title)
+	const left = arrived.get(leaf) ?? 0
+
+	if (left === 0) return false
+	arrived.set(leaf, left - 1)
+
+	return true
+}
+
+function removed(base: ReadonlyArray<string>, head: ReadonlyArray<string>): ReadonlyArray<string> {
+	const base_names = new Set(base)
+	const head_names = new Set(head)
+	const arrived = leaf_counts(unique(head).filter((title) => !base_names.has(title)))
+
+	return unique(base)
+		.filter((title) => !head_names.has(title))
+		.filter((title) => !is_moved(arrived, title))
+}
+
+// A retirement with no Issue is no row at all, so its test reads as undisposed.
+function is_cited(groups: Readonly<Record<string, string>>): boolean {
+	return groups['kind'] === REPLACED || RETIREMENT_PATTERN.test(groups['rest'] ?? '')
+}
+
+function disposed_title(line: string): string | undefined {
+	const groups = ROW_PATTERN.exec(line.trim())?.groups
+
+	if (groups === undefined || !is_cited(groups)) return undefined
+
+	return groups['title']
+}
+
+function undisposed(removed_titles: ReadonlyArray<string>, pr_body = ''): ReadonlyArray<string> {
+	const disposed = new Set(
+		markdown_section
+			.section_lines(pr_body, DISPOSITION_HEADING)
+			.map((line) => disposed_title(line)),
+	)
+
+	return removed_titles.filter((title) => !disposed.has(title))
+}
+
+function pending_rows(titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	return titles.map((title) => `- \`${title}\` ${PENDING_SUFFIX}`)
+}
+
+function has_row(lines: ReadonlyArray<string>, title: string): boolean {
+	return lines.some((line) => line.trim().startsWith(`- \`${title}\` `))
+}
+
+// The pending rows a body still lacks, put under its disposition heading — added at the end when the
+// body has none — so a run fills them in before `josh ship` rather than meeting them at its preflight
+// (joshuafolkken/kit#4563). A title with any row already, pending or filled, is left as it is.
+function with_pending_rows(body: string, titles: ReadonlyArray<string>): string {
+	const lines = markdown_section.section_lines(body, DISPOSITION_HEADING)
+	const rows = pending_rows(titles.filter((title) => !has_row(lines, title))).join('\n')
+
+	if (rows === '') return body
+	if (!HEADING_LINE.test(body)) return `${body.trimEnd()}\n\n${DISPOSITION_HEADING}\n\n${rows}\n`
+
+	return body.replace(HEADING_LINE, () => `${DISPOSITION_HEADING}\n\n${rows}`)
+}
+
+// Nothing when the change removed no test, so an ordinary brief is not one line longer.
+function brief_block(removed_titles: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (removed_titles.length === 0) return []
+
+	return [
+		'',
+		`${BRIEF_HEADING} — these tests existed at the base and are gone from the change. For each, find the test that guards its behavior now, or the Issue that retired the behavior; a removed test with neither is a finding (missing test). The pull request body must dispose of each ${ROW_FORMAT}, or \`josh followup\` refuses the merge:`,
+		...pending_rows(removed_titles),
+	]
+}
+
+function refusal_message(titles: ReadonlyArray<string>): string {
+	return [
+		`Merge refused: this change removes ${String(titles.length)} test(s) the pull request body does not account for.`,
+		`Put these rows into the body's ${DISPOSITION_HEADING} section, replacing each ending with the test that replaced it or the Issue that retired its behavior:`,
+		DISPOSITION_HEADING,
+		'',
+		...pending_rows(titles),
+		`Write ${ROW_FORMAT} — format: ${report_format_reference.pointer(report_format_reference.REMOVED_TESTS_HEADING)}`,
+		'Write it into the `--body-file` before `josh ship`, or update an open PR with `gh api -X PATCH repos/{owner}/{repo}/pulls/<N> -F body=@<path>`, then re-run.',
+	].join('\n')
+}
+
+const removed_tests = {
+	brief_block,
+	DISPOSITION_HEADING,
+	refusal_message,
+	removed,
+	ROW_FORMAT,
+	undisposed,
+	with_pending_rows,
+}
+
+export { removed_tests }

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

@@ -1,4 +1,3 @@
-#!/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'
@@ -8,21 +7,26 @@ 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 { removed_tests_check } from './removed-tests-check'
 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_interaction } from './review-interaction'
 import { review_level, type ReviewLevel } from './review-level'
+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 +37,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 +58,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
@@ -132,7 +137,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 {
@@ -202,6 +212,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 +232,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()
+	// 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 +282,9 @@ 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,
 	})
 }
 
@@ -325,23 +365,55 @@ 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,
+	interaction?: ReadonlyArray<string>,
+): Promise<number> {
 	const { base, commit, paths, tree } = reading
 	const refusal = scoped_green.refusal_for(tree, commit)
 
 	if (refusal !== undefined) return report_error(refusal)
-	const resolved = agent_role_profile.resolve(agent_role_profile.REVIEWER)
+	const resolved = agent_role_profile.resolve_review(round)
 
 	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
+
+	console.info(await compose_brief({ round, paths, tree, base, profile, interaction }))
+	if (interaction === undefined) await record_review(round, tree, commit)
 
 	return 0
 }
 
+// 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> {
+	const reading = await read_change()
+	const targets = review_interaction.due_paths(reading.paths)
+
+	if (targets.length === 0) {
+		console.info(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, 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()
 
 	const round = parse_round(argv)
 
@@ -350,10 +422,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await run_review(round, await read_change())
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const review_brief_cli = {
 	FIRST_ROUND,
 	format_reason,
@@ -365,6 +433,4 @@ const review_brief_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 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))
+}