@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/lane/lane-withdraw.ts

@@ -0,0 +1,182 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_label } from '#scripts/run/run-label'
+import { lane_close, type CloseKind } from './lane-close'
+import { lane_preserve, type KeptWork } from './lane-preserve'
+import { lane_reap } from './lane-reap'
+import { lane_registry, type LaneInfo } from './lane-registry'
+
+// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the run
+// for good: the child is stopped, its work stashed, the Issue closed as not planned and the lane closed.
+//
+// **The `withdraw` event is written first, before anything is stopped.** Killing the child alone would
+// let `lane:await` book it stopped and `run:merge` classify it from GitHub — an open issue resumed as an
+// `outage` or parked `needs-decision`. `run:merge` reads the event stream before GitHub, so a child whose
+// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads
+// at that moment, and the race between the kill and the close cannot book it as anything else.
+//
+// **The issue is read again once the child is stopped.** It may merge between the first read and the
+// reap; the reap stopped it, so the second read is final, and an issue it already closed keeps
+// GitHub's close — `run:merge` books a merged close as merged whatever the event stream says.
+//
+// A tree that could not be stashed is left in place with the Issue open: closing the lane would delete
+// the work, and the person decides what to keep.
+
+const WITHDRAW_OCCASION = 'lane withdraw'
+const WITHDRAW_CAUSE = 'a person withdrew it with `lane:withdraw`'
+const CLOSED_STATE = 'CLOSED'
+const CLOSED_KIND = 'closed'
+const NO_LANE_KIND = 'no-lane'
+const UNREADABLE_KIND = 'unreadable'
+
+type Unsaved = Extract<KeptWork, { kind: 'unsaved' }>
+
+interface Withdrawn {
+	kind: 'withdrawn'
+	// How many of the child's processes the withdrawal stopped — 0 for a child that had already ended.
+	reaped: number
+	stash: string | undefined
+	is_closed: boolean
+	// The issue had closed on its own — merged — before the withdrawal reached it, so it was left as is.
+	had_closed: boolean
+	lane: CloseKind
+}
+
+type IssueSettled = Pick<Withdrawn, 'had_closed' | 'is_closed'>
+
+type Refused =
+	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
+type WithdrawOutcome = Withdrawn | Unsaved | Refused
+
+function close_comment(reason: string): string {
+	return [
+		'Withdrawn by a person with `pnpm josh lane:withdraw`.',
+		'Its lane child was stopped and the lane closed.',
+		`- Why: ${reason}`,
+	].join('\n')
+}
+
+async function record_withdraw(issue: string, reason: string): Promise<void> {
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.WITHDRAW,
+		`${issue_cite.plain(issue)} withdrawn by a person: ${reason}`,
+	)
+}
+
+// A closed issue has nothing to withdraw, and an unread one might be: neither writes anything.
+async function refusal_of(issue: string): Promise<Refused | undefined> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	if (read.kind !== 'state') return { kind: UNREADABLE_KIND }
+	if (read.state.state.toUpperCase() === CLOSED_STATE) return { kind: CLOSED_KIND }
+
+	return undefined
+}
+
+async function close_open_issue(issue: string, reason: string): Promise<IssueSettled> {
+	const refusal = await refusal_of(issue)
+
+	// An unread issue may have merged during the reap, so it is left open for a person to close.
+	if (refusal !== undefined) {
+		const is_closed = refusal.kind === CLOSED_KIND
+
+		return { is_closed, had_closed: is_closed }
+	}
+
+	const is_closed = await git_gh_issue_write.issue_close_not_planned(issue, close_comment(reason))
+
+	return { is_closed, had_closed: false }
+}
+
+async function close_issue(
+	issue: string,
+	reason: string,
+	stash: string | undefined,
+): Promise<IssueSettled> {
+	const settled = await close_open_issue(issue, reason)
+
+	if (stash !== undefined) await lane_preserve.announce(issue, stash, WITHDRAW_CAUSE)
+	await run_label.unmark(issue)
+
+	return settled
+}
+
+async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
+	await record_withdraw(lane.issue, reason)
+	const reaped = lane_reap.reap_child(lane.issue).length
+	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, WITHDRAW_OCCASION)
+
+	if (saved.kind === 'unsaved') return saved
+	const settled = await close_issue(lane.issue, reason, saved.stash)
+	const closed = await lane_close.close_lane(lane.issue)
+
+	return { kind: 'withdrawn', reaped, stash: saved.stash, ...settled, lane: closed.kind }
+}
+
+/** Stop `#<N>`'s lane child, stash its work, close the Issue as not planned and close the lane. */
+async function withdraw(issue: string, reason: string): Promise<WithdrawOutcome> {
+	issue_number_shape.require_issue_number(issue)
+	const refusal = await refusal_of(issue)
+
+	if (refusal !== undefined) return refusal
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: NO_LANE_KIND }
+
+	return await stop_and_close(lane, reason)
+}
+
+function stash_sentence(stash: string | undefined): string {
+	if (stash === undefined) return 'The lane held no uncommitted work.'
+
+	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
+}
+
+function withdrawn_text(outcome: Withdrawn, issue: string): string {
+	const cited = session_cite.issue(issue)
+	const stopped = outcome.reaped === 0 ? 'Its child had already ended.' : 'Stopped its child.'
+	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
+	const lane = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+
+	if (outcome.had_closed) return `${head} The Issue had already closed and was left as is.${lane}`
+
+	if (outcome.is_closed) return `${head} The Issue is closed as not planned.${lane}`
+
+	return `${head} The Issue could not be closed — close ${cited} by hand; \`run:merge\` books it withdrawn either way.${lane}`
+}
+
+function unsaved_text(outcome: Unsaved, issue: string): string {
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the Issue is left open and the lane at ${outcome.directory}; \`run:merge\` books it withdrawn.`
+}
+
+function refused_text(outcome: Refused, issue: string): string {
+	const cited = session_cite.issue(issue)
+
+	if (outcome.kind === CLOSED_KIND) {
+		return `${cited} is already closed, so there is nothing to withdraw.`
+	}
+
+	if (outcome.kind === NO_LANE_KIND) {
+		return `No lane is open for ${cited}, so there is no child to withdraw.`
+	}
+
+	return `The state of ${cited} could not be read, so nothing was stopped or closed — try again.`
+}
+
+function describe(outcome: WithdrawOutcome, issue: string): string {
+	if (outcome.kind === 'unsaved') return unsaved_text(outcome, issue)
+
+	return outcome.kind === 'withdrawn'
+		? withdrawn_text(outcome, issue)
+		: refused_text(outcome, issue)
+}
+
+const lane_withdraw = { describe, withdraw }
+
+export type { WithdrawOutcome }
+export { lane_withdraw }

package/scripts/lint/format.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { ESLINT_CACHE_FLAGS, PRETTIER_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { execa } from 'execa'
 
 const COMMAND_NAME = 'format'
 const ARGV_OFFSET = 2
 const FAIL_EXIT_CODE = 1
-const PRETTIER_ARGS = ['exec', 'prettier', '--write', '.'] as const
+const PRETTIER_WRITE_ARGS = ['exec', 'prettier', '--write', '.', ...PRETTIER_CACHE_FLAGS] as const
 const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
 
 async function run_step(args: ReadonlyArray<string>, directory: string): Promise<number> {
@@ -37,7 +37,7 @@ async function run_format(directory: string): Promise<number> {
 	const prettier_exit_code = await run_unless_skipped(
 		'prettier',
 		prettier_reason,
-		PRETTIER_ARGS,
+		PRETTIER_WRITE_ARGS,
 		directory,
 	)
 	if (prettier_exit_code !== 0) return prettier_exit_code
@@ -64,4 +64,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const format = { run, run_format }
 
-export { ESLINT_FIX_ARGS, format }
+export { ESLINT_FIX_ARGS, format, PRETTIER_WRITE_ARGS }

package/scripts/lint/lint-parallel.ts

@@ -1,7 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FILE, ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import {
+	ESLINT_CACHE_FILE,
+	ESLINT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
 import { lane_cache_run } from '#scripts/lane/lane-cache-run'
 import {
 	buffered_process,
@@ -11,7 +15,6 @@ import {
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
 import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
-const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
 // cache flags come from the same constant the ignore rules are asserted against.
 // A copy here would keep writing the old location the day that constant
@@ -23,6 +26,10 @@ const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
 	patterns: [WHOLE_TREE],
 }
 
+// Prettier's cache stays this checkout's own, never shared through `lane_cache_run` as eslint's is:
+// its entries do not survive a move (`josh-command-types.ts` → `GATE_CACHE_SPECS`).
+const PRETTIER_ARGS = ['exec', 'prettier', '--check', WHOLE_TREE, ...PRETTIER_CACHE_FLAGS] as const
+
 // What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
 // (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
 interface EslintRun {
@@ -132,4 +139,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const lint_parallel = { run_lint_checks, run_lint_parallel_checks }
 
-export { ESLINT_ARGS, lint_parallel }
+export { ESLINT_ARGS, lint_parallel, PRETTIER_ARGS }

package/scripts/lint/lint-related-scope.ts

@@ -8,6 +8,7 @@ import {
 import {
 	ESLINT_RELATED_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FLAGS,
+	PRETTIER_RELATED_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
 import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
@@ -94,8 +95,10 @@ function describe_scope(scope: ChangedFileScope, root: string): string {
 	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
 }
 
+// The scoped run's own cache file, for the reason eslint's below gives: prettier too rewrites its
+// cache file whole, so a narrowed run sharing the gate's would discard entries a concurrent gate wrote.
 function prettier_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
-	return [...PRETTIER_ARGS, ...files]
+	return [...PRETTIER_ARGS, ...files, ...PRETTIER_RELATED_CACHE_FLAGS]
 }
 
 // The cache file is this command's own rather than the gate's, because the two run at the same time.

package/scripts/managed-marker/managed-marker-logic.ts

@@ -46,8 +46,7 @@ function apply_marker_for_destination(
 	text: string,
 	package_name: string,
 ): string {
-	if (!is_workflow_destination(destination)) return text
-	if (is_marked(text)) return text
+	if (!is_workflow_destination(destination) || is_marked(text)) return text
 
 	return `${marker_block(package_name)}${text}`
 }

package/scripts/notify/telegram-test.ts

@@ -112,6 +112,14 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 	return { repo_name, issue_title }
 }
 
+// The send behind the command line, for a caller that already holds the values — the `Stop` hook's
+// own confirmation (`stop-actions.ts`). It throws as `telegram_notify.send` does.
+async function send_values(values: CliValues): Promise<void> {
+	const context = await resolve_context(values)
+
+	await telegram_notify.send(telegram_test_logic.build_input({ values, context }))
+}
+
 async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
@@ -122,10 +130,7 @@ async function main(): Promise<void> {
 		return
 	}
 
-	const context = await resolve_context(values)
-	const input = telegram_test_logic.build_input({ values, context })
-
-	await telegram_notify.send(input)
+	await send_values(values)
 }
 
 // **A notification nobody received must not read as success**. This command
@@ -148,6 +153,6 @@ async function run_cli(): Promise<void> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await run_cli()
 
-const telegram_test = { fetch_repo_name, fetch_issue_title, resolve_context, run_cli }
+const telegram_test = { fetch_repo_name, fetch_issue_title, resolve_context, run_cli, send_values }
 
 export { telegram_test }

package/scripts/overrides/lockfile-overrides.ts

@@ -42,9 +42,7 @@ function find_entry_mismatch(
 	specifier: string,
 	override: string | undefined,
 ): Array<SpecifierMismatch> {
-	if (override === undefined) return []
-	if (is_non_registry(specifier)) return []
-	if (specifier === override) return []
+	if (override === undefined || specifier === override || is_non_registry(specifier)) return []
 
 	return [{ importer, name, lockfile_specifier: specifier, override }]
 }

package/scripts/propagate/propagate.ts

@@ -277,8 +277,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 
 	const plan = plan_run(options)
-	if (plan === undefined) return FAILURE_EXIT_CODE
-	if (!(await resolve_publish(plan, options))) return FAILURE_EXIT_CODE
+	if (plan === undefined || !(await resolve_publish(plan, options))) return FAILURE_EXIT_CODE
 
 	return propagate_to_consumers(plan, options.is_dry_run)
 }

package/scripts/release/release-progress.ts

@@ -145,8 +145,9 @@ async function wait_for_github_release(version: string): Promise<boolean> {
 async function wait_for_distribution(version: string): Promise<number> {
 	const manifest = read_manifest(process.cwd())
 
-	if (!(await wait_for_npm(manifest, version))) return FAILURE_EXIT_CODE
-	if (!(await wait_for_github_release(version))) return FAILURE_EXIT_CODE
+	if (!(await wait_for_npm(manifest, version)) || !(await wait_for_github_release(version))) {
+		return FAILURE_EXIT_CODE
+	}
 
 	console.info(complete_line(version))
 

package/scripts/report/report-format-reference.ts

@@ -8,6 +8,7 @@ const REPORT_FORMAT_PATH = 'prompts/collaboration-workflow/report-format.md'
 const SUMMARY_RULES_HEADING = '作業前サマリはいつ・どう出すか'
 const SUMMARY_TEMPLATE_HEADING = '作業前サマリ（セッション向け・`JOSH_SESSION_LANG` の言語）'
 const COMPLETION_REPORT_HEADING = '完了報告（セッション向け）'
+const ACCEPTANCE_MAP_HEADING = 'PR 本文の受け入れ条件の対応表'
 
 // The heading goes in single quotes in the runnable form: the template heading carries backticks,
 // which a double-quoted shell argument would run as a command substitution.
@@ -16,6 +17,7 @@ function pointer(heading: string): string {
 }
 
 const report_format_reference = {
+	ACCEPTANCE_MAP_HEADING,
 	COMPLETION_REPORT_HEADING,
 	pointer,
 	REPORT_FORMAT_PATH,

package/scripts/report/report-lint.ts

@@ -102,8 +102,7 @@ function overview_lines(summary: string): ReadonlyArray<string> {
 function item_sentence(line: string): string {
 	const open = line.indexOf(BOLD_MARKER)
 	const close = open === -1 ? -1 : line.indexOf(BOLD_MARKER, open + BOLD_MARKER.length)
-	const raw =
-		close === -1 ? line.slice(ITEM_LINE_PREFIX.length) : line.slice(close + BOLD_MARKER.length)
+	const raw = line.slice(close === -1 ? ITEM_LINE_PREFIX.length : close + BOLD_MARKER.length)
 
 	return raw.replace(LEADING_LABEL_PUNCTUATION, '').trim()
 }
@@ -199,8 +198,12 @@ function break_condition_count(lines: ReadonlyArray<string>): number {
 }
 
 function case_line_violations(summary: string): ReadonlyArray<string> {
-	if (!has_changes_section(summary)) return []
-	if (changes_region_lines(summary).some((line) => line.includes(CASE_LABEL))) return []
+	if (
+		!has_changes_section(summary) ||
+		changes_region_lines(summary).some((line) => line.includes(CASE_LABEL))
+	) {
+		return []
+	}
 
 	return [`✖ no case tier (${CASE_LABEL}:) in ${CHANGES_LABEL}`]
 }

package/scripts/review/acceptance-map-check.ts

@@ -0,0 +1,61 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { acceptance_map, type Deferral } from './acceptance-map'
+
+// The reads behind `acceptance_map`: the Issue as it reads at the merge, the pull request body, and
+// whether each issue a deferral row names exists. Kept apart so the comparison stays pure.
+
+const ISSUE_SEPARATOR = '#'
+
+// `owner/repo#12` reads that repository's issue; a bare `#12` reads this one's.
+async function is_found(deferral: Deferral): Promise<boolean> {
+	const [repo, number = ''] = deferral.issue.split(ISSUE_SEPARATOR)
+	const read = await git_gh_command.issue_get_body_classified(
+		number,
+		repo === '' ? undefined : repo,
+	)
+
+	return read.kind === 'read'
+}
+
+async function absent_deferrals(
+	deferrals: ReadonlyArray<Deferral>,
+): Promise<ReadonlyArray<string>> {
+	const found = await Promise.all(deferrals.map(async (deferral) => await is_found(deferral)))
+
+	return deferrals
+		.filter((_deferral, index) => found[index] !== true)
+		.map((deferral) => `- \`${deferral.id}\` names ${deferral.issue}`)
+}
+
+function unreadable_message(issue: string): string {
+	return `Issue ${session_cite.issue(issue)} could not be re-read to check its acceptance criteria, so the merge is refused; re-run once it can be.`
+}
+
+// **An Issue that cannot be re-read is a refusal, not a pass** — the criteria it would have named are
+// exactly what this gate exists to see. An Issue with no acceptance section merges as before.
+// `josh ship`'s preflight asks the body it is about to deliver, so a missing table stops it before the
+// review rather than at the merge.
+async function body_refusal(
+	issue: string,
+	pr_body: string | undefined,
+): Promise<string | undefined> {
+	const issue_read = await git_gh_command.issue_get_body_classified(issue)
+
+	if (issue_read.kind !== 'read') return unreadable_message(issue)
+	const criteria = acceptance_map.criteria_of(issue_read.text)
+	const comparison = acceptance_map.compare(criteria, acceptance_map.rows_of(pr_body))
+	const absent = await absent_deferrals(comparison.deferrals)
+
+	if (comparison.missing.length === 0 && absent.length === 0) return undefined
+
+	return acceptance_map.refusal_message(issue, comparison, absent)
+}
+
+async function refusal(issue: string, branch_name: string): Promise<string | undefined> {
+	return await body_refusal(issue, await git_gh_command.pr_get_body(branch_name))
+}
+
+const acceptance_map_check = { body_refusal, refusal }
+
+export { acceptance_map_check }

package/scripts/review/acceptance-map.ts

@@ -0,0 +1,205 @@
+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,
+	rows_of,
+	skeleton,
+}
+
+export type { Criterion, Deferral, MapComparison }
+export { acceptance_map }

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

@@ -330,7 +330,7 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 	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()