@joshuafolkken/kit 1.872.0

package/scripts/run/run-ship-probe.ts

@@ -0,0 +1,103 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { run_hold } from './run-hold'
+import { run_preflight } from './run-preflight'
+import { run_ship_stage, type ShipState } from './run-ship-stage'
+
+// The read side of a resumed `josh ship` (joshuafolkken/kit#2426): the repository's actual state, asked
+// before any stage runs, and where the stage record lives. `run-ship-stage.ts` decides from what this
+// reads; this module only reads.
+//
+// **Every read that cannot complete answers `false`** — "not done yet" — so the stage runs and its own
+// guard answers instead: `git -y` refuses an empty commit, a push of a commit origin already holds
+// changes nothing, and `followup` reads the pull request itself before it merges.
+
+const REPOSITORY_DIRECTORY_INDEX = 1
+const REMOTE_SHA_INDEX = 0
+const REMOTE_FIELD_SEPARATOR = /\s/u
+const HEAD_REFERENCE = 'HEAD'
+
+async function or_false(is_true: () => Promise<boolean>): Promise<boolean> {
+	try {
+		return await is_true()
+	} catch {
+		return false
+	}
+}
+
+// A clean tree whose branch holds commits the default branch does not: the commit stage's output. A
+// dirty tree is uncommitted work, whatever is already committed beneath it.
+async function read_committed(): Promise<boolean> {
+	if (await run_hold.is_tree_dirty()) return false
+
+	const base = await git_command.default_branch_reference()
+
+	return (await git_command.commit_count_beyond(base, HEAD_REFERENCE)) > 0
+}
+
+// Origin's branch tip is this checkout's `HEAD` — the push has nothing left to send.
+async function read_pushed(branch_name: string): Promise<boolean> {
+	const [remote, head] = await Promise.all([
+		git_worktree.ls_remote_branch(branch_name),
+		git_command.head_commit(),
+	])
+
+	return remote.split(REMOTE_FIELD_SEPARATOR)[REMOTE_SHA_INDEX] === head
+}
+
+// The branch's pull request is merged **and** the default branch already holds `HEAD`. A branch whose
+// earlier pull request merged and which has since gained commits still reads `MERGED` from GitHub, and
+// taking that alone would skip the gate, the commit and the merge of the new work. A stale default
+// branch reads as not merged, so `followup` runs and reads the pull request itself.
+async function read_merged(branch_name: string): Promise<boolean> {
+	if ((await run_preflight.read_pr_state(branch_name)) !== run_preflight.MERGED_PR) return false
+
+	const base = await git_command.default_branch_reference()
+
+	return (await git_command.commit_count_beyond(base, HEAD_REFERENCE)) === 0
+}
+
+const NOTHING_DONE: ShipState = { is_committed: false, is_pushed: false, is_merged: false }
+
+async function read_branch_state(branch_name: string): Promise<ShipState> {
+	const [is_committed, is_pushed, is_merged] = await Promise.all([
+		or_false(read_committed),
+		or_false(async () => await read_pushed(branch_name)),
+		or_false(async () => await read_merged(branch_name)),
+	])
+
+	return { is_committed, is_pushed, is_merged }
+}
+
+// A branch that cannot be named leaves nothing to ask about, so it reads as nothing done.
+async function read_state(): Promise<ShipState> {
+	try {
+		return await read_branch_state(await git_command.branch())
+	} catch {
+		return NOTHING_DONE
+	}
+}
+
+// The common git directory every lane of the repository shares — what the stage record, the detached
+// supervisor's log and its pid are keyed on (joshuafolkken/kit#2428) — or `undefined` outside one.
+async function repository_directory(): Promise<string | undefined> {
+	try {
+		const directories = await git_command.git_directories()
+
+		return directories[REPOSITORY_DIRECTORY_INDEX]
+	} catch {
+		return undefined
+	}
+}
+
+// The record's path for this issue, or `undefined` outside a repository — there is nothing to key on,
+// and a ship without a record still resumes from the state alone.
+async function record_target(issue: string): Promise<string | undefined> {
+	const repository = await repository_directory()
+
+	return repository === undefined ? undefined : run_ship_stage.record_path(repository, issue)
+}
+
+const run_ship_probe = { read_state, record_target, repository_directory }
+
+export { run_ship_probe }

package/scripts/run/run-ship-return.ts

@@ -0,0 +1,75 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_relaunch } from '#scripts/lane/lane-relaunch'
+import { run_event_stream } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+import type { Stage } from './run-ship-stage'
+
+// How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
+// ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
+// nobody to read it — this is what gives it one, in two halves:
+//
+// 1. **A `ship-stop` position on the event stream**, naming the issue and the stage. `run:step` maps it to
+//    the command that prints the stopped report, so whoever asks next is pointed at the failure rather
+//    than rebuilding what happened.
+// 2. **In a dispatched lane, a fresh child session relaunched into the lane** — the way the pre-gate cut
+//    relaunches one (`lane-relaunch.ts`) — with the ship-stop prompt, at the implementation phase's
+//    effort because a fix is judgement. It is started before the supervisor exits, so the parent's
+//    liveness poll never sees the lane empty. An OpenAI lane is left to its own supervisor, which starts
+//    no successor without a cut, so its parent books the stop exactly as it books any ended child.
+//
+// A ship run in an agent's own turn is not supervised and hands nothing back: its report is already in
+// front of the agent that ran it.
+
+const OPENAI_PROVIDER = 'openai'
+
+type ReturnOutcome = 'relaunched' | 'recorded'
+
+function stop_text(issue: string, stage: Stage): string {
+	return `#${issue} ${stage} failed — pnpm josh ship --log ${issue}`
+}
+
+function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
+	return lane !== undefined && lane.profile?.provider !== OPENAI_PROVIDER
+}
+
+async function lane_to_relaunch(issue: string): Promise<LaneInfo | undefined> {
+	if (!lane_child_marker.is_child_of(process.cwd())) return undefined
+
+	const lane = await lane_registry.find_open_lane(issue)
+
+	return can_relaunch(lane) ? lane : undefined
+}
+
+function note(text: string): void {
+	process.stderr.write(`${text}\n`)
+}
+
+async function return_control(issue: string, stage: Stage): Promise<ReturnOutcome> {
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STOP, stop_text(issue, stage))
+
+	const lane = await lane_to_relaunch(issue)
+
+	if (lane === undefined) return 'recorded'
+
+	const invocation = lane_child_invocation.ship_stop_invocation(issue)
+	const result = lane_relaunch.relaunch(
+		lane,
+		invocation,
+		agent_role_profile.IMPLEMENTATION_PHASE,
+		note,
+	)
+
+	if (result.kind === 'launched') return 'relaunched'
+
+	note(`the lane child could not be relaunched: ${result.note}`)
+
+	return 'recorded'
+}
+
+const run_ship_return = { return_control, stop_text }
+
+export type { ReturnOutcome }
+export { run_ship_return }

package/scripts/run/run-ship-review-steps.ts

@@ -0,0 +1,227 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { gate_tree } from '#scripts/gate/gate-tree'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch } from './detached-launch'
+import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
+
+// The side effects of `josh ship --review` (joshuafolkken/kit#2427): the round-1 review the chain used
+// to open, launch, join, attest and record across five agent turns, run by the supervisor beside the
+// gate. Each step is the existing command or mechanism, composed rather than cloned:
+//
+// 1. `run:review` starts the gate detached and mints the brief — the nonce `review:attest` checks.
+// 2. the reviewer is launched the way `run:wake` launches a session — `agent_argv` under the reviewer
+//    profile, `detached_launch.launch_attached` to wait for its exit — handed the brief by path.
+// 3. `run:review --join` blocks a verdict over a red gate; `review:attest --check` refuses a review
+//    that read another checkout; `review:record` writes the round the merge gate reads.
+//
+// **Round 1's local fixes and round 2 stay inside the supervisor** (joshuafolkken/kit#2489). A round-1
+// reviewer that fixed its local Mediums in place changed the tree the background gate read, so that
+// join drains the gate rather than judging it — the ship's gate stage re-runs on the fixed tree. After
+// the commit, `round_two_stage` asks `review:round2 --round-1-closed` whether the fix delta owes a
+// second round, and on `required` runs it through the same commands the chain does: the scoped pair
+// `review:brief` requires, `review:brief --round 2`, a fresh reviewer session, attest and record.
+//
+// **A precondition the supervisor can meet itself is met, not stopped on** (joshuafolkken/kit#2500).
+// The scoped pair `run:review` and the local gate refuse without is run in place when this tree has no
+// green record, and a round-1 fix is counted only once that pair is green on the fixed tree.
+//
+// **Every failure returns control to the agent**: a non-zero step, a reviewer that did not finish, an
+// unreadable findings file, a High or an unfixed Medium in round 1, and anything but a clean round 2 —
+// recorded first, because the round was attested, then routed back.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const should_forward_stderr = true
+const RUN_REVIEW = 'run:review'
+const ATTEST_CHECK = ['review:attest', '--check']
+const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed']
+const ROUND_TWO_BRIEF = ['review:brief', '--round', '2']
+const ROUND_TWO_REQUIRED = 'required'
+const BRIEF_PREFIX = 'josh-ship-review-brief-'
+const FINDINGS_PREFIX = 'josh-ship-review-findings-'
+const LOG_PREFIX = 'josh-ship-review-log-'
+const BRIEF_SUFFIX = '.md'
+const FINDINGS_SUFFIX = '.txt'
+const LOG_SUFFIX = '.log'
+const FIXED_JOIN_NOTE =
+	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate stage re-runs it.'
+const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
+
+type Phase = () => Promise<JoshResult>
+type PromptOf = (brief_path: string, findings_path: string) => string
+
+function failure(out: string): JoshResult {
+	return { code: FAILURE_EXIT_CODE, out }
+}
+
+function paths(root: string = PROJECT_ROOT): { brief: string; findings: string; log: string } {
+	return {
+		brief: stamp_file.stamp_path(BRIEF_PREFIX, root, BRIEF_SUFFIX),
+		findings: stamp_file.stamp_path(FINDINGS_PREFIX, root, FINDINGS_SUFFIX),
+		log: stamp_file.stamp_path(LOG_PREFIX, root, LOG_SUFFIX),
+	}
+}
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+function note(text: string): void {
+	process.stderr.write(`${text}\n`)
+}
+
+// Under the reviewer profile — the same model and effort (`JOSH_REVIEWER_*` included) the chain's
+// subagent is given — and waited on, so the join below runs only once the review has finished. Each
+// call is its own process, so round 2 is a fresh session by construction.
+async function run_session(prompt: string, log_path: string): Promise<JoshResult> {
+	const built = agent_argv.resolve_in(prompt, agent_role_profile.REVIEWER, PROJECT_ROOT)
+
+	if (built.kind === 'rejected') return failure(`reviewer profile rejected: ${built.note}`)
+
+	const request = { argv: built.argv, cwd: PROJECT_ROOT, log_path, profile: built.profile }
+	const result = await detached_launch.launch_attached(request, note)
+
+	if (result.kind === 'failed') return failure(`reviewer could not start: ${result.note}`)
+	if (result.exit_code !== SUCCESS_EXIT_CODE) return failure(`reviewer failed — log: ${log_path}`)
+
+	return { code: SUCCESS_EXIT_CODE, out: '' }
+}
+
+// The brief goes to a file and the previous round's findings are removed, so a reviewer that writes
+// nothing reads as unfinished rather than as the last round's verdict.
+async function launch_reviewer(brief: string, prompt_of: PromptOf): Promise<JoshResult> {
+	const target = paths()
+
+	stamp_file.write_text_stamp(target.brief, brief)
+	stamp_file.remove_stamp(target.findings)
+
+	return await run_session(prompt_of(target.brief, target.findings), target.log)
+}
+
+function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
+	return run_ship_review.read_verdict(stamp_file.read_stamp_text(paths().findings))
+}
+
+// A red join blocks unless the reviewer fixed findings in place: the background gate then read the
+// tree before the fixes, so its verdict describes a tree that no longer exists. The join still ran to
+// its end, so the gate stage that follows never races it.
+async function join_gate(): Promise<JoshResult> {
+	const joined = await josh([RUN_REVIEW, '--join'])
+
+	if (joined.code === SUCCESS_EXIT_CODE) return joined
+	if (current_verdict().kind !== run_ship_review.VERDICT.FIXED) return joined
+
+	note(FIXED_JOIN_NOTE)
+
+	return { code: SUCCESS_EXIT_CODE, out: joined.out }
+}
+
+async function record_and_route(
+	issue: string,
+	outcome_of: (verdict: ScoredVerdict) => RoundOutcome,
+): Promise<JoshResult> {
+	const verdict = current_verdict()
+
+	if (verdict.kind === run_ship_review.VERDICT.INVALID) return failure(verdict.note)
+
+	const recorded = await josh(['review:record', '--issue', issue, ...verdict.specs])
+
+	if (recorded.code !== SUCCESS_EXIT_CODE) return recorded
+
+	const outcome = outcome_of(verdict)
+	const out = [...verdict.specs, outcome.note].join('\n')
+
+	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
+}
+
+async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
+	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
+
+	for (const phase of phases) {
+		last = await phase()
+		if (last.code !== SUCCESS_EXIT_CODE) return last
+	}
+
+	return last
+}
+
+// A brief-minting command, then a reviewer handed what it printed.
+function reviewed(open: ReadonlyArray<string>, prompt_of: PromptOf): ReadonlyArray<Phase> {
+	const opened = { brief: '' }
+
+	return [
+		async () => {
+			const result = await josh(open)
+
+			opened.brief = result.out
+
+			return result
+		},
+		async () => await launch_reviewer(opened.brief, prompt_of),
+	]
+}
+
+// The scoped pair's precondition, met by the supervisor itself rather than stopped on
+// (joshuafolkken/kit#2500): only the checks with no green record for this tree run — the same
+// question `review:brief` and the local gate refuse on — so a fresh record costs nothing and a stale
+// or absent one costs a scoped run instead of a stop and a relaunched session. A check that genuinely
+// fails still stops the ship, its output forwarded to the ship log.
+async function scoped_pair(): Promise<JoshResult> {
+	const tree = await gate_tree.read_gate_tree()
+	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
+
+	return await run_phases(scripts.map((script) => async () => await josh([script])))
+}
+
+// Fixes made in place are counted only once the scoped pair is green on the fixed tree. The reviewer is
+// asked to leave it green; this is the check that it did, and a fix it could not get green is routed as
+// the finding it still is — recorded, then stopped before the gate and the commit take it in.
+async function round_one_record(issue: string): Promise<JoshResult> {
+	const is_fixed = current_verdict().kind === run_ship_review.VERDICT.FIXED
+	const checked = is_fixed ? await scoped_pair() : undefined
+	const is_verified = checked === undefined || checked.code === SUCCESS_EXIT_CODE
+
+	return await record_and_route(issue, (verdict) =>
+		is_verified ? run_ship_review.round_one_outcome(verdict) : run_ship_review.UNVERIFIED_OUTCOME,
+	)
+}
+
+// The round-1 review, beside the gate: scoped pair → open → review → join → attest → record, stopping
+// at the first that did not pass.
+async function review_stage(issue: string): Promise<JoshResult> {
+	return await run_phases([
+		scoped_pair,
+		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt),
+		join_gate,
+		async () => await josh(ATTEST_CHECK),
+		async () => await round_one_record(issue),
+	])
+}
+
+// The round-2 verification pass, after the commit so it runs beside CI: due only when the round-1 fix
+// delta says so, then scoped pair → brief → fresh reviewer → attest → record.
+async function round_two_stage(issue: string): Promise<JoshResult> {
+	const decision = await josh(ROUND_TWO_DECISION)
+	const answer = decision.out.trim()
+
+	if (decision.code !== SUCCESS_EXIT_CODE) return decision
+
+	if (answer !== ROUND_TWO_REQUIRED) {
+		return { code: SUCCESS_EXIT_CODE, out: `${answer}\n${ROUND_TWO_SKIPPED_NOTE}` }
+	}
+
+	return await run_phases([
+		scoped_pair,
+		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt),
+		async () => await josh(ATTEST_CHECK),
+		async () => await record_and_route(issue, run_ship_review.round_two_outcome),
+	])
+}
+
+const run_ship_review_steps = { paths, review_stage, round_two_stage }
+
+export { run_ship_review_steps }

package/scripts/run/run-ship-review.ts

@@ -0,0 +1,177 @@
+import { review_finding_ledger } from '#scripts/review/review-finding-ledger'
+import { review_record_cli } from '#scripts/review/review-record-cli'
+
+// The pure half of `josh ship --review` (joshuafolkken/kit#2427): the one-line prompts the supervised
+// reviewers are launched with, the verdict read back off the findings file each writes, and where that
+// verdict routes the ship. Kept apart from the launch and the joins (`run-ship-review-steps.ts`) the way
+// `run-review.ts` is kept apart from `run-review-steps.ts`, so every branch is pinned without a session
+// ever starting.
+//
+// **The reviewer is the one the chain already runs.** Its prompt hands it the brief `run:review`
+// printed — the same level, rubric, checkout and `review:attest` nonce a `/code-review` subagent was
+// given — and asks only that the findings also be written in the `review:record` grammar, so the
+// supervisor records and routes them without an agent reading the prose.
+//
+// **Round 1 fixes what is local; round 2 only reads** (joshuafolkken/kit#2489). The round-1 reviewer
+// applies a Medium whose fix is small and local — the "small, local asks" `chain-rule.md` names — and
+// marks that finding `fixed`, so the supervisor carries the ship through the gate, the commit and a
+// round-2 verification pass instead of handing a lane child back for a fix it could not make. A High is
+// never fixed in place and always blocks, as does a Medium left unfixed. The round-2 reviewer is a fresh
+// session that edits nothing, and anything but a clean or Low-only verdict from it blocks.
+
+const LINE_SEPARATOR = /\r?\n/u
+const HIGH = 'high'
+const MEDIUM = 'medium'
+const FIXED_PREFIX = 'fixed '
+
+const VERDICT = {
+	CLEAN: 'clean',
+	FIXED: 'fixed',
+	BLOCKING: 'blocking',
+	INVALID: 'invalid',
+} as const
+
+type ReviewVerdict =
+	| {
+			kind: typeof VERDICT.CLEAN | typeof VERDICT.FIXED | typeof VERDICT.BLOCKING
+			specs: ReadonlyArray<string>
+	  }
+	| { kind: typeof VERDICT.INVALID; note: string }
+
+type ScoredVerdict = Exclude<ReviewVerdict, { kind: typeof VERDICT.INVALID }>
+
+// Whether a recorded round lets the ship go on, and the line the report closes that round with.
+interface RoundOutcome {
+	is_passing: boolean
+	note: string
+}
+
+interface Finding {
+	spec: string
+	is_fixed: boolean
+}
+
+const MISSING_NOTE = 'the reviewer wrote no findings file — the review did not complete'
+const CLEAN_NOTE = 'review clean or Low-only — recorded; shipping on.'
+const FIXED_NOTE =
+	'review fixes applied in place — recorded; the gate re-runs on the fixed tree and round 2 follows the commit.'
+const BLOCKING_NOTE =
+	'review found High/Medium it did not fix — recorded; fix them, then take the round-2 route (`chain-rule.md`).'
+const UNVERIFIED_OUTCOME: RoundOutcome = {
+	is_passing: false,
+	note: 'review fixes did not pass the scoped checks — recorded as unfixed; fix them, then take the round-2 route (`chain-rule.md`).',
+}
+const ROUND_TWO_CLEAN_NOTE = 'round 2 clean or Low-only — recorded; shipping on.'
+const ROUND_TWO_BLOCKING_NOTE =
+	'round 2 found High/Medium or edited the tree — recorded; round 2 is final: fix, push and gate it, then run followup (`chain-rule.md` step 4).'
+
+function findings_instruction(findings_path: string, fixed_clause: string): string {
+	const categories = review_finding_ledger.CATEGORIES.join(', ')
+
+	return [
+		`Then write every finding to ${findings_path}, one per line as <category>:<severity>:<file>[:<line>]`,
+		`(category one of ${categories}; severity high, medium or low)${fixed_clause},`,
+		'and an empty file when there is none.',
+	].join(' ')
+}
+
+// One line, because `detached_launch` refuses an argument carrying a control character: the multi-line
+// brief travels by path, never inline.
+function reviewer_prompt(brief_path: string, findings_path: string): string {
+	return [
+		`Run a /code-review of this checkout: read the review brief at ${brief_path} and follow it exactly —`,
+		'the level on its first line, the rubric it names, the checkout it pins and its review:attest step.',
+		'Apply a fix only for a Medium finding whose fix is small and local — a one-function refactor, an',
+		'added test, an added guard; never fix a High or a change that reaches beyond one place, and never',
+		'commit, stage or push. After any fix, run `pnpm josh lint:related && pnpm josh test:related` and',
+		'return only once both are green; revert a fix you cannot get green and report that finding unfixed.',
+		findings_instruction(findings_path, `, prefixing a finding you fixed with "${FIXED_PREFIX}"`),
+	].join(' ')
+}
+
+// The round-2 verification pass: a fresh session over the round-1 fix delta, reading only.
+function verification_prompt(brief_path: string, findings_path: string): string {
+	return [
+		`Run a /code-review of this checkout — the round-2 verification pass over the round-1 fixes: read the`,
+		`review brief at ${brief_path} and follow it exactly — the level on its first line, the rubric it`,
+		'names, the checkout it pins and its review:attest step. Do not edit any file.',
+		findings_instruction(findings_path, ''),
+	].join(' ')
+}
+
+function finding_of(line: string): Finding {
+	if (!line.startsWith(FIXED_PREFIX)) return { spec: line, is_fixed: false }
+
+	return { spec: line.slice(FIXED_PREFIX.length).trim(), is_fixed: true }
+}
+
+function spec_findings(text: string): ReadonlyArray<Finding> {
+	return text
+		.split(LINE_SEPARATOR)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+		.map((line) => finding_of(line))
+}
+
+function is_recordable(finding: Finding): boolean {
+	return review_record_cli.parse_finding(finding.spec) !== undefined
+}
+
+// A High blocks whether or not it is marked fixed — it is never fixed in place — and a Medium blocks
+// unless the reviewer fixed it.
+function is_blocking(finding: Finding): boolean {
+	const severity = review_record_cli.parse_finding(finding.spec)?.severity
+
+	return severity === HIGH || (severity === MEDIUM && !finding.is_fixed)
+}
+
+function scored_kind(findings: ReadonlyArray<Finding>): ScoredVerdict['kind'] {
+	if (findings.some((finding) => is_blocking(finding))) return VERDICT.BLOCKING
+
+	return findings.some((finding) => finding.is_fixed) ? VERDICT.FIXED : VERDICT.CLEAN
+}
+
+// Absent means the reviewer never finished; a line outside the grammar means its verdict cannot be
+// recorded — both stop the ship rather than read as clean. The specs are recorded without the `fixed`
+// mark: a fixed finding was still a finding of that round.
+function read_verdict(text: string | undefined): ReviewVerdict {
+	if (text === undefined) return { kind: VERDICT.INVALID, note: MISSING_NOTE }
+
+	const findings = spec_findings(text)
+	const invalid = findings.find((finding) => !is_recordable(finding))
+
+	if (invalid !== undefined) {
+		return { kind: VERDICT.INVALID, note: `unreadable finding: ${invalid.spec}` }
+	}
+
+	return { kind: scored_kind(findings), specs: findings.map((finding) => finding.spec) }
+}
+
+// Round 1 passes clean or with every blocking finding fixed in place; round 2 follows the commit.
+function round_one_outcome(verdict: ScoredVerdict): RoundOutcome {
+	if (verdict.kind === VERDICT.BLOCKING) return { is_passing: false, note: BLOCKING_NOTE }
+
+	return { is_passing: true, note: verdict.kind === VERDICT.FIXED ? FIXED_NOTE : CLEAN_NOTE }
+}
+
+// Round 2 is final and reads only, so it passes clean or Low-only alone — a fix it made would itself be
+// unreviewed.
+function round_two_outcome(verdict: ScoredVerdict): RoundOutcome {
+	const is_passing = verdict.kind === VERDICT.CLEAN
+
+	return { is_passing, note: is_passing ? ROUND_TWO_CLEAN_NOTE : ROUND_TWO_BLOCKING_NOTE }
+}
+
+const run_ship_review = {
+	FIXED_PREFIX,
+	UNVERIFIED_OUTCOME,
+	VERDICT,
+	read_verdict,
+	reviewer_prompt,
+	round_one_outcome,
+	round_two_outcome,
+	verification_prompt,
+}
+
+export type { ReviewVerdict, RoundOutcome, ScoredVerdict }
+export { run_ship_review }