@joshuafolkken/kit 1.872.0

package/scripts/git/git-next-issues.ts

@@ -0,0 +1,98 @@
+import { git_gh_command } from './git-gh-command'
+import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
+import { parse_json_array_safe } from './parse-json-array'
+import { open_issue_schema, type OpenIssueData } from './schemas'
+
+// The next-issues display printed when a workflow completes (#821): up to five open issues in
+// priority order, so the user picks the next run from the completion output instead of opening the
+// issue list. Priority is recency — a newer issue usually encodes the most current understanding
+// of the backlog — with the label-based exclusions below.
+//
+// `prioritize` is also the order `epicrun` picks up `auto-ok` issues in (joshuafolkken/kit#906).
+// The two ask one question — which open issue outside an epic is run next — so they share one
+// answer; a second ordering would have the run start something other than what this display, shown
+// at the end of every workflow, has just told the person is next.
+const FETCH_LIMIT = 20
+const DISPLAY_LIMIT = 5
+const HEADER = '🗒 Next issues (newest first):'
+
+// Surfacing an `epic`, an `in-progress` or a `needs-decision` issue as "next" would suggest a run
+// the workflow rules forbid, duplicate, or cannot finish (joshuafolkken/kit#861). The set itself is
+// shared with the `auto-ok` pickup, which asks the same question of the same listing shape.
+function has_excluded_label(issue: OpenIssueData): boolean {
+	return has_any_label(issue.labels, NOT_DIRECTLY_RUNNABLE_LABELS)
+}
+
+// The completed issue is excluded by number, not by state: GitHub applies the `closes #N` side
+// effect asynchronously, so right after the merge it can still be listed as open.
+function is_candidate(issue: OpenIssueData, completed_issue_number: number | undefined): boolean {
+	return issue.number !== completed_issue_number && !has_excluded_label(issue)
+}
+
+// ISO-8601 timestamps compare correctly as strings; the issue number breaks ties because two
+// issues created in one `josh epic` batch can share a timestamp to the second.
+function compare_newest_first(first: OpenIssueData, second: OpenIssueData): number {
+	if (first.createdAt === second.createdAt) return second.number - first.number
+
+	return first.createdAt < second.createdAt ? 1 : -1
+}
+
+// **This display deliberately does not drop a blocked issue, and the `auto-ok` pickup deliberately
+// does.** They share this ordering and differ on the set, which reads as an inconsistency and is not
+// one (joshuafolkken/kit#1005).
+//
+// The display is read by a person, who can see that an issue is blocked, judge that the blocker is
+// nearly done or does not really block it, and start anyway. The pickup feeds an unattended run,
+// which has none of that judgement — so the same row is information to one and an instruction to the
+// other. Filtering here would take the choice away from the only reader equipped to make it, and the
+// blocked issue would simply vanish from the backlog view with nothing said.
+function prioritize(
+	issues: ReadonlyArray<OpenIssueData>,
+	completed_issue_number?: number,
+): Array<OpenIssueData> {
+	return issues
+		.filter((issue) => is_candidate(issue, completed_issue_number))
+		.toSorted(compare_newest_first)
+		.slice(0, DISPLAY_LIMIT)
+}
+
+// Empty input yields no lines at all — a bare header with nothing under it reads as an error.
+function format_lines(issues: ReadonlyArray<OpenIssueData>): Array<string> {
+	if (issues.length === 0) return []
+	const rows = issues.map(
+		(issue, index) => `  ${String(index + 1)}. #${String(issue.number)} ${issue.title}`,
+	)
+
+	return [HEADER, ...rows]
+}
+
+// Returns display lines, or [] when there is nothing to show. Every failure — `gh` unavailable,
+// malformed JSON, an unexpected shape — degrades to [] rather than throwing: this runs after the
+// merge has already succeeded, and a non-zero exit here would make a completed workflow look
+// failed over a purely informational display.
+async function fetch_next_issue_lines(completed_issue_number?: number): Promise<Array<string>> {
+	try {
+		// **`is_capped` is deliberately not read here** (joshuafolkken/kit#1067). The paging is
+		// newest-first and this display keeps only the five newest of the twenty it asks for, so a
+		// listing the page ceiling cut short is a *prefix* of the one it would otherwise have got — the
+		// same five rows, in the same order. There is nothing the truncation hides that this display
+		// would have shown, and a warning above a correct list would be noise at the end of every
+		// completed run.
+		const { json } = await git_gh_command.issue_list_recent(FETCH_LIMIT)
+		if (json === undefined) return []
+
+		return format_lines(
+			prioritize(parse_json_array_safe(json, open_issue_schema), completed_issue_number),
+		)
+	} catch {
+		return []
+	}
+}
+
+const git_next_issues = {
+	prioritize,
+	format_lines,
+	fetch_next_issue_lines,
+}
+
+export { git_next_issues }

package/scripts/git/git-notify.ts

@@ -0,0 +1,104 @@
+type NotifyTarget = 'pr' | 'issue' | 'both'
+
+interface GitNotifyConfig {
+	target: NotifyTarget
+	message: string
+	mentions: Array<string>
+}
+
+const DEFAULT_NOTIFY_MESSAGE = 'Implementation is complete. Please review.'
+
+function parse_notify_target(raw_target: string | undefined): NotifyTarget | undefined {
+	if (raw_target === undefined) return undefined
+	if (raw_target === 'pr') return 'pr'
+	if (raw_target === 'issue') return 'issue'
+	if (raw_target === 'both') return 'both'
+
+	throw new Error(`Invalid notify target: ${raw_target}. Use pr, issue, or both.`)
+}
+
+function split_and_trim(value: string): Array<string> {
+	return value
+		.split(',')
+		.map((item) => item.trim())
+		.filter((item) => item.length > 0)
+}
+
+function normalize_mention(mention: string): string {
+	return mention.startsWith('@') ? mention : `@${mention}`
+}
+
+function parse_notify_mentions(raw_mentions: string | undefined): Array<string> {
+	if (raw_mentions === undefined) return []
+
+	return split_and_trim(raw_mentions).map((mention) => normalize_mention(mention))
+}
+
+// The `\n` escape the inline `--notify-message` form needs is expanded by `cli_body` at the point the
+// flag is read, not here (joshuafolkken/kit#1198). Expanding again would rewrite a literal backslash-n
+// that `--notify-message-file` legitimately carries — a file already holds real newlines, so an
+// escape sequence in one is the author's text rather than a quoting workaround.
+//
+// **Trimming moved up with it, and for the same reason.** This function used to read
+// `raw.trim().replaceAll(…)` — trim first, expand second. Keeping the trim here after the expansion
+// had moved reversed that order, so `--notify-message "…\n"` lost the newline its own escape had just
+// produced. `trim` survives only as the emptiness test, where the whitespace is being counted rather
+// than removed.
+function resolve_notify_message(raw_message: string | undefined): string {
+	if (raw_message === undefined || raw_message.trim().length === 0) return DEFAULT_NOTIFY_MESSAGE
+
+	return raw_message
+}
+
+function build_notify_config(input: {
+	raw_target: string | undefined
+	raw_message: string | undefined
+	raw_mentions: string | undefined
+}): GitNotifyConfig | undefined {
+	const parsed_target = parse_notify_target(input.raw_target)
+	if (parsed_target === undefined) return undefined
+
+	return {
+		target: parsed_target,
+		message: resolve_notify_message(input.raw_message),
+		mentions: parse_notify_mentions(input.raw_mentions),
+	}
+}
+
+// **`notes` is what the run has to say about itself beyond the message it was handed**, and today
+// that is the managed config-file report (joshuafolkken/kit#1592). It is a separate field rather than
+// text folded into `message`, because the message is the person's own completion summary and the
+// notes are the command's — folding them together would leave a caller unable to tell which half it
+// wrote. **A run with nothing to note adds no line at all**, blank separator included, so the
+// ordinary completion report is byte-for-byte what it was.
+// Its own function so the builder below keeps one branch rather than two: the absent case and the
+// empty case are the same answer, and both have to add nothing — the blank separator included.
+function note_section(notes: ReadonlyArray<string> | undefined): Array<string> {
+	if (notes === undefined || notes.length === 0) return []
+
+	return ['', ...notes]
+}
+
+function build_completion_comment_body(input: {
+	message: string
+	issue_number: string | undefined
+	pr_url: string | undefined
+	mentions: Array<string>
+	notes?: ReadonlyArray<string>
+}): string {
+	const base_lines = [`✅ ${input.message}`]
+	const issue_lines = input.issue_number === undefined ? [] : [`Issue: #${input.issue_number}`]
+	const pr_lines = input.pr_url === undefined ? [] : [`PR: ${input.pr_url}`]
+	const note_lines = note_section(input.notes)
+	const mention_lines = input.mentions.length === 0 ? [] : ['', input.mentions.join(' ')]
+
+	return [...base_lines, ...issue_lines, ...pr_lines, ...note_lines, ...mention_lines].join('\n')
+}
+
+const git_notify = {
+	build_notify_config,
+	build_completion_comment_body,
+}
+
+export type { GitNotifyConfig }
+export { git_notify }

package/scripts/git/git-pr-ai-review.ts

@@ -0,0 +1,180 @@
+// cspell:words coderabbit coderabbitai
+import {
+	classify_ai_review_comments,
+	type ClassifiedFinding,
+	type ReviewComment,
+} from './git-ai-review-scan'
+import { git_gh_command } from './git-gh-command'
+import { git_pr_confirmation, has_ignore_reason, type TelegramContext } from './git-pr-confirmation'
+import { parse_json_array_or_undefined } from './parse-json-array'
+import { ai_review_pull_comment_schema } from './schemas'
+
+interface AiReviewPullComment {
+	body?: string | undefined
+	url?: string | undefined
+	author?: { login?: string | undefined } | undefined
+}
+
+// `undefined` when the answer was not a listing at all. `parse_json_array_safe` returned `[]` for
+// that, which this gate reads as "no reviewer left a finding" (joshuafolkken/kit#973).
+function parse_ai_review_comments(
+	raw_json: string | undefined,
+): Array<AiReviewPullComment> | undefined {
+	if (raw_json === undefined) return undefined
+
+	return parse_json_array_or_undefined(raw_json, ai_review_pull_comment_schema)
+}
+
+function to_review_comment(raw: AiReviewPullComment): ReviewComment {
+	return {
+		body: raw.body ?? '',
+		author_login: raw.author?.login ?? '',
+		url: raw.url,
+	}
+}
+
+function format_ai_review_finding(finding: ClassifiedFinding): string {
+	const suffix = finding.url === undefined ? '' : ` — ${finding.url}`
+
+	return `- ${finding.author_login}: ${finding.summary}${suffix}`
+}
+
+// Temporary (kit#753): CodeRabbit findings are surfaced as console info and audit notes for the
+// completion notification instead of blocking the merge. Revert together with kit#752.
+function log_info_findings(infos: ReadonlyArray<ClassifiedFinding>): Array<string> {
+	if (infos.length === 0) return []
+
+	console.warn('⚠ CodeRabbit review is non-blocking (temporary policy — kit#753):')
+
+	for (const info of infos) {
+		console.warn(format_ai_review_finding(info))
+	}
+
+	return infos.map((info) => `CodeRabbit skipped (kit#753): ${info.summary}`)
+}
+
+function build_ai_review_blocker_body(blockers: ReadonlyArray<ClassifiedFinding>): string {
+	const lines = ['AI reviewer findings remain unresolved.', '']
+
+	for (const blocker of blockers) {
+		lines.push(format_ai_review_finding(blocker))
+	}
+
+	return lines.join('\n')
+}
+
+function build_ai_review_ignore_comment(
+	reason: string,
+	blockers: ReadonlyArray<ClassifiedFinding>,
+): string {
+	const lines = [
+		'Some AI reviewer findings were intentionally left unresolved.',
+		`Reason: ${reason.trim()}`,
+		'Affected comments:',
+	]
+
+	for (const blocker of blockers) {
+		lines.push(`- ${blocker.author_login}: ${blocker.summary} (${blocker.url ?? 'no-url'})`)
+	}
+
+	return lines.join('\n')
+}
+
+async function fetch_review_comments(
+	branch_name: string,
+): Promise<Array<ReviewComment> | undefined> {
+	const parsed = parse_ai_review_comments(await git_gh_command.pr_get_comments(branch_name))
+
+	return parsed?.map((comment) => to_review_comment(comment))
+}
+
+async function handle_blockers(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+	context: TelegramContext
+	blockers: ReadonlyArray<ClassifiedFinding>
+}): Promise<void> {
+	const body = build_ai_review_blocker_body(input.blockers)
+
+	if (has_ignore_reason(input.ignore_reason)) {
+		const ignore_comment = build_ai_review_ignore_comment(input.ignore_reason, input.blockers)
+
+		await git_gh_command.pr_comment(input.branch_name, ignore_comment)
+
+		return
+	}
+
+	await git_pr_confirmation.notify_confirmation({ context: input.context, body })
+
+	throw new Error(body)
+}
+
+// A gate that could not be read is not a gate that passed. An unreadable listing is handled exactly
+// like an unresolved finding — the same `confirmation` Telegram, the same non-zero exit — because
+// what it means is the same: nobody has confirmed the reviewers had nothing to say
+// (joshuafolkken/kit#973). An ignore reason still gets past it, for the same reason it gets past a
+// real finding: the person has looked.
+const UNREADABLE_COMMENTS_BODY =
+	'The AI reviewer comments could not be read, so no finding could be ruled out.\n' +
+	'Re-run `pnpm josh followup` once the read succeeds, or pass an ignore reason.'
+
+// The audit note a bypassed run carries into its completion notification. Without it a run that
+// never read the gate reports exactly like one that read it and found nothing.
+const UNREADABLE_COMMENTS_NOTE = 'AI reviewer comments could not be read; the scan was bypassed.'
+
+async function handle_unreadable_comments(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+	context: TelegramContext
+}): Promise<Array<string>> {
+	if (has_ignore_reason(input.ignore_reason)) {
+		await git_gh_command.pr_comment(
+			input.branch_name,
+			`${UNREADABLE_COMMENTS_BODY}\nReason: ${input.ignore_reason.trim()}`,
+		)
+
+		return [UNREADABLE_COMMENTS_NOTE]
+	}
+
+	await git_pr_confirmation.notify_confirmation({
+		context: input.context,
+		body: UNREADABLE_COMMENTS_BODY,
+	})
+
+	throw new Error(UNREADABLE_COMMENTS_BODY)
+}
+
+async function handle_ai_review_findings(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+	context: TelegramContext
+}): Promise<Array<string>> {
+	const review_comments = await fetch_review_comments(input.branch_name)
+
+	if (review_comments === undefined) return await handle_unreadable_comments(input)
+
+	const { blockers, infos } = classify_ai_review_comments(review_comments)
+	const skip_notes = log_info_findings(infos)
+
+	if (blockers.length > 0) await handle_blockers({ ...input, blockers })
+
+	return skip_notes
+}
+
+const git_pr_ai_review = {
+	handle_ai_review_findings,
+	parse_ai_review_comments,
+	to_review_comment,
+	has_ignore_reason,
+}
+
+export {
+	git_pr_ai_review,
+	handle_ai_review_findings,
+	parse_ai_review_comments,
+	to_review_comment,
+	UNREADABLE_COMMENTS_BODY,
+	UNREADABLE_COMMENTS_NOTE,
+}
+
+export { has_ignore_reason, type TelegramContext } from './git-pr-confirmation'

package/scripts/git/git-pr-checks-eval.ts

@@ -0,0 +1,265 @@
+import {
+	CHECK_STATUS_FAIL,
+	CHECK_STATUS_MISSING,
+	CHECK_STATUS_PASS,
+	type PrStateSnapshot,
+	type RollupCheck,
+} from './git-pr-checks-parse'
+
+// cspell:words coderabbit
+// Temporary (kit#753): CodeRabbit is excluded from the default required checks so slow or
+// rate-limited CodeRabbit reviews never block the merge gate. Re-add it via JOSH_REQUIRED_CHECKS
+// to restore the old behavior. Revert once the fresh-context review subagent (kit#752) replaces it.
+const DEFAULT_REQUIRED_CHECKS = ['SonarQube']
+// The single source of the check name every CodeRabbit exemption is keyed on — the merge gate's
+// `is_unstable_only_from_coderabbit`, the look-ahead's `is_awaited_check`, and the fixtures the two
+// are tested from. A second literal spelling of it anywhere is how one of them silently stops
+// matching after CodeRabbit renames its context (joshuafolkken/kit#1217).
+const CODERABBIT_CHECK_NAME = 'CodeRabbit'
+const REQUIRED_CHECKS_ENV_VAR = 'JOSH_REQUIRED_CHECKS'
+
+function parse_required_checks(): ReadonlyArray<string> {
+	const raw = process.env[REQUIRED_CHECKS_ENV_VAR]
+
+	if (!raw) return DEFAULT_REQUIRED_CHECKS
+
+	return raw
+		.split(',')
+		.map((check) => check.trim())
+		.filter((check) => check.length > 0)
+}
+
+const REQUIRED_CHECKS = parse_required_checks()
+const MERGE_STATE_CLEAN = 'CLEAN'
+const MERGE_STATE_UNSTABLE = 'UNSTABLE'
+// What GitHub reports for a pull request that conflicts with its base. It is the one merge state
+// that no amount of waiting resolves, so it ends the wait rather than polling through it.
+const MERGE_STATE_DIRTY = 'DIRTY'
+const REVIEW_CHANGES_REQUESTED = 'CHANGES_REQUESTED'
+// GitHub reports a check-suite job as `<App> / <Job>` (e.g. `CodeRabbit / Review`). A required
+// check name matches that suite when it is the `<App>` segment, so the required-check list stays the
+// bare app name even after the provider renames its job.
+const CHECK_SUITE_SEPARATOR = ' / '
+const FAILURE_MESSAGE_PREFIX = 'PR checks failed'
+const FAILURE_REASON_REVIEW = 'review requested changes'
+const FAILURE_REASON_CHECKS = 'failed checks'
+const FAILURE_REASON_CONFLICT = 'merge conflict'
+
+type PrEvaluation = 'success' | 'pending' | 'failure'
+
+// A required check matches either its exact context name or a check-suite job nested under it
+// (`<required> / <job>`). The separator keeps the prefix anchored, so an unrelated context such as
+// `CodeRabbitNightly` does not satisfy a required `CodeRabbit`.
+function is_required_match(check_name: string, required_name: string): boolean {
+	if (check_name === required_name) return true
+
+	return check_name.startsWith(`${required_name}${CHECK_SUITE_SEPARATOR}`)
+}
+
+function find_required_check(
+	checks: ReadonlyArray<RollupCheck>,
+	required_name: string,
+): RollupCheck | undefined {
+	return checks.find((check) => is_required_match(check.name, required_name))
+}
+
+function read_required_statuses(checks: ReadonlyArray<RollupCheck>): Array<string> {
+	return REQUIRED_CHECKS.map(
+		(name) => find_required_check(checks, name)?.status ?? CHECK_STATUS_MISSING,
+	)
+}
+
+function is_review_blocked(review_decision: string | undefined): boolean {
+	return review_decision === REVIEW_CHANGES_REQUESTED
+}
+
+// **A conflicting pull request ends the wait instead of polling through it**
+// (joshuafolkken/kit#1232). `DIRTY` is not CLEAN, so it used to answer `pending` and run the whole
+// 32-minute budget out on a state that resolves only when a person rebases — ending in a timeout
+// that named no cause. This is also where the conflict diagnosis `pnpm josh git` used to carry
+// landed: that command read `mergeStateStatus` after its own two-minute watch, and now returns as
+// soon as the pull request is open, so the first poll here is what reports a conflict — about ten
+// seconds against that two minutes.
+//
+// **`BLOCKED` is deliberately not here.** GitHub reports it while a required check is merely queued,
+// which is every healthy pull request for its first seconds. The old reader treated it as a conflict
+// safely only because it ran after the checks had settled; there is no equivalent moment on this
+// path, and a green-but-`BLOCKED` pull request (branch protection requiring a review, which this
+// repository does not set) therefore reaches the timeout rather than a named failure.
+function is_merge_conflict(merge_state_status: string | undefined): boolean {
+	return merge_state_status === MERGE_STATE_DIRTY
+}
+
+// A required check whose status is `fail` is by definition a rollup entry that
+// `collect_blocking_failures` already names, so the required list needs no condition of its own
+// here — see `is_blocking_failure`.
+function evaluate_failure_state(input: {
+	review_decision: string | undefined
+	failed_checks: ReadonlyArray<string>
+	merge_state_status: string | undefined
+}): PrEvaluation | undefined {
+	if (
+		is_merge_conflict(input.merge_state_status) ||
+		is_review_blocked(input.review_decision) ||
+		input.failed_checks.length > 0
+	) {
+		return 'failure'
+	}
+
+	return undefined
+}
+
+function is_merge_state_clean(merge_state_status: string | undefined): boolean {
+	return merge_state_status === MERGE_STATE_CLEAN
+}
+
+function is_every_required_passing(statuses: ReadonlyArray<string>): boolean {
+	return statuses.every((status) => status === CHECK_STATUS_PASS)
+}
+
+function is_coderabbit_check(check_name: string): boolean {
+	return is_required_match(check_name, CODERABBIT_CHECK_NAME)
+}
+
+// Temporary (kit#753): a pending or failing CodeRabbit check makes GitHub report UNSTABLE even
+// though CodeRabbit is no longer required. Accept that state only when CodeRabbit checks are the
+// sole non-passing ones — any other non-passing check keeps the gate strict.
+function is_unstable_only_from_coderabbit(snapshot: PrStateSnapshot): boolean {
+	if (snapshot.merge_state_status !== MERGE_STATE_UNSTABLE) return false
+	const non_passing = snapshot.rollup.filter((check) => check.status !== CHECK_STATUS_PASS)
+	if (non_passing.length === 0) return false
+
+	return non_passing.every((check) => is_coderabbit_check(check.name))
+}
+
+function is_required_check(check_name: string): boolean {
+	return REQUIRED_CHECKS.some((required) => is_required_match(check_name, required))
+}
+
+// A failing job outside the required list used to decide nothing: GitHub reports the pull request as
+// UNSTABLE rather than failed, so `evaluate_pr_state` answered `pending` and the wait ran out its
+// whole 32-minute budget before ending in a timeout that never named the cause
+// (joshuafolkken/kit#990). Any failed check therefore ends the wait now — except CodeRabbit's, which
+// kit#753 keeps non-blocking end to end, unless a project has put it back on the required list via
+// `JOSH_REQUIRED_CHECKS`. This only makes the gate report sooner: nothing here can produce
+// `success`, so no failing check gains a path to a merge. What counts as failed is whatever the
+// parser records as `fail` — `cancelled` and `timed_out` among them — which is the rule the required
+// list has always followed; the cost is that a job cancelled and re-run by hand is no longer picked
+// up by a wait already in progress, and `followup` has to be run again.
+function is_blocking_failure(check: RollupCheck): boolean {
+	if (check.status !== CHECK_STATUS_FAIL) return false
+
+	return !is_coderabbit_check(check.name) || is_required_check(check.name)
+}
+
+function collect_blocking_failures(snapshot: PrStateSnapshot): Array<string> {
+	return snapshot.rollup.filter((check) => is_blocking_failure(check)).map((check) => check.name)
+}
+
+function is_mergeable_state(snapshot: PrStateSnapshot): boolean {
+	if (is_merge_state_clean(snapshot.merge_state_status)) return true
+
+	return is_unstable_only_from_coderabbit(snapshot)
+}
+
+// The wait's own error text: naming the checks that failed is what turns a red `followup` into
+// something actionable without opening the pull request (joshuafolkken/kit#990).
+function collect_failure_reasons(snapshot: PrStateSnapshot): Array<string> {
+	const reasons: Array<string> = []
+	if (is_merge_conflict(snapshot.merge_state_status)) reasons.push(FAILURE_REASON_CONFLICT)
+	if (is_review_blocked(snapshot.review_decision)) reasons.push(FAILURE_REASON_REVIEW)
+	const failed = collect_blocking_failures(snapshot)
+	if (failed.length > 0) reasons.push(`${FAILURE_REASON_CHECKS}: ${failed.join(', ')}`)
+
+	return reasons
+}
+
+function describe_pr_failure(snapshot: PrStateSnapshot): string {
+	const reasons = collect_failure_reasons(snapshot)
+	if (reasons.length === 0) return `${FAILURE_MESSAGE_PREFIX}.`
+
+	return `${FAILURE_MESSAGE_PREFIX} (${reasons.join('; ')}).`
+}
+
+function evaluate_pr_state(snapshot: PrStateSnapshot): PrEvaluation {
+	const statuses = read_required_statuses(snapshot.rollup)
+	const failure = evaluate_failure_state({
+		review_decision: snapshot.review_decision,
+		failed_checks: collect_blocking_failures(snapshot),
+		merge_state_status: snapshot.merge_state_status,
+	})
+
+	if (failure !== undefined) return failure
+
+	if (is_mergeable_state(snapshot) && is_every_required_passing(statuses)) {
+		return 'success'
+	}
+
+	return 'pending'
+}
+
+// **When the review listing can still change what this poll concludes.**
+//
+// `evaluate_pr_state` reads `review_decision` in exactly one place — `is_review_blocked`, which
+// produces `failure`. So a poll that answers `pending` without one answers `pending` or `failure`
+// with it, and neither merges: the read buys nothing on that poll. A poll that answers `success` or
+// `failure` without one is a poll that ends the wait, and both need it — `success` because a standing
+// change request must demote it, `failure` because `describe_pr_failure` names the reasons and
+// dropping "review requested changes" from a message that also lists failed checks loses half the
+// diagnosis (joshuafolkken/kit#1043).
+//
+// **This is a freshness rule, not a cache.** Nothing is remembered between polls, which is the one
+// shape that would be wrong here — a stale non-blocking decision is exactly the direction that ships
+// a merge past a change request. The poll that concludes a merge always carries a review decision
+// read in that same poll.
+//
+// **What it costs, stated rather than glossed.** A change request standing on a pull request whose
+// checks never settle used to end the wait on the first poll with `review requested changes`; it now
+// runs the budget out and ends with the wait's own timeout, which names no cause. That run was red
+// either way — the trade only ever moves a red result later, never a green one earlier — but the
+// diagnosis is genuinely worse in that one case.
+function is_review_decision_decisive(snapshot: PrStateSnapshot): boolean {
+	return evaluate_pr_state(snapshot) !== 'pending'
+}
+
+// **Whether GitHub's auto-merge can never fire on this pull request** (joshuafolkken/kit#2497). This is
+// narrower than the merge gate's `failure`: the gate also fails a red check outside the required list
+// (joshuafolkken/kit#990), but auto-merge waits only on the required ones, so such a pull request still
+// lands — reading it as blocked would call a landing flush stuck.
+function is_auto_merge_blocked(snapshot: PrStateSnapshot): boolean {
+	const failed_required = snapshot.rollup.filter(
+		(check) => check.status === CHECK_STATUS_FAIL && is_required_check(check.name),
+	)
+
+	return (
+		evaluate_failure_state({
+			review_decision: snapshot.review_decision,
+			failed_checks: failed_required.map((check) => check.name),
+			merge_state_status: snapshot.merge_state_status,
+		}) !== undefined
+	)
+}
+
+const git_pr_checks_eval = {
+	evaluate_pr_state,
+	is_review_decision_decisive,
+	read_required_statuses,
+	is_coderabbit_check,
+	collect_blocking_failures,
+	describe_pr_failure,
+}
+
+export {
+	git_pr_checks_eval,
+	evaluate_pr_state,
+	is_auto_merge_blocked,
+	is_review_decision_decisive,
+	read_required_statuses,
+	is_coderabbit_check,
+	collect_blocking_failures,
+	describe_pr_failure,
+	REQUIRED_CHECKS,
+	CODERABBIT_CHECK_NAME,
+	is_required_check,
+}
+export type { PrEvaluation }