@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/ship/run-ship-stop-context.ts

@@ -2,9 +2,11 @@ import { stripVTControlCharacters } from 'node:util'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_prior_findings } from '#scripts/review/review-prior-findings'
 import { z } from 'zod'
 import { run_ship_next } from './run-ship-next'
 import { run_ship_probe } from './run-ship-probe'
+import type { StopFinding } from './run-ship-review'
 
 // What a relaunched lane child needs in front of it to fix a stopped ship: the tail of the failed
 // stage's output — a red check, or the High/Medium findings a review stage reports — and the branch's
@@ -14,6 +16,9 @@ import { run_ship_probe } from './run-ship-probe'
 // **Both are bounded**, so a long gate log never becomes the whole prompt. The tail is kept because a
 // check reports its verdict last; the lines left out go to a file whose path and line range the prompt
 // names, so nothing is lost and the session reads only the range it needs.
+//
+// **A review stop also carries the lane's earlier findings on the files it cites** (joshuafolkken/kit#4780),
+// so the fix meets the constraint an earlier round set on the same line rather than breaking it.
 
 const EXCERPT_LINE_LIMIT = 40
 const EXCERPT_LINE_WIDTH = 240
@@ -33,6 +38,7 @@ const stop_context_schema = z
 		omitted: omitted_schema.optional(),
 		changed: z.array(z.string()).readonly().optional(),
 		more_changed: z.number().int(),
+		prior: z.array(z.string()).readonly().optional(),
 	})
 	.strict()
 
@@ -121,8 +127,18 @@ async function changed_of(): Promise<Pick<StopContext, 'changed' | 'more_changed
 	}
 }
 
-async function build(issue: string, output: string): Promise<StopContext> {
-	return { ...(await excerpt_of(issue, output)), ...(await changed_of()) }
+async function build(
+	issue: string,
+	output: string,
+	findings: ReadonlyArray<StopFinding> = [],
+): Promise<StopContext> {
+	const prior = review_prior_findings.on_files(issue, findings)
+
+	return {
+		...(await excerpt_of(issue, output)),
+		...(await changed_of()),
+		...(prior.length > 0 && { prior }),
+	}
 }
 
 function has_excerpt(context: StopContext | undefined): boolean {
@@ -168,17 +184,12 @@ function changed_text(context: StopContext): string {
 	return `Changed files on the branch: ${context.changed.join(', ')}${more}.`
 }
 
-// The block the ship-stop prompt carries between the next command and the closing invocation.
-//
-// **It fits the `budget` the prompt leaves it** — the prompt is one argv element, refused past
-// `MAX_VALUE_LENGTH` (joshuafolkken/kit#3964) — by dropping the excerpt's head first, since a check
-// reports its verdict last; the tail line always stays.
-function describe(
-	issue: string,
-	context: StopContext,
-	budget: number = agent_role_profile.MAX_VALUE_LENGTH,
-): string {
-	const changed = changed_text(context)
+function trailer_text(context: StopContext): string {
+	return [changed_text(context), ...review_prior_findings.fix_lines(context.prior)].join(LINE_BREAK)
+}
+
+function fitted_block(issue: string, context: StopContext, budget: number): string {
+	const changed = trailer_text(context)
 
 	if (!has_excerpt(context)) return changed
 
@@ -193,6 +204,32 @@ function describe(
 	return block
 }
 
+function has_prior(context: StopContext): boolean {
+	return context.prior !== undefined && context.prior.length > 0
+}
+
+// The block the ship-stop prompt carries between the next command and the closing invocation.
+//
+// **It fits the `budget` the prompt leaves it** — the prompt is one argv element, kept within
+// `MAX_VALUE_LENGTH` (joshuafolkken/kit#3964), well under the launch gate's prompt cap — by dropping
+// the excerpt's head first, since a check
+// reports its verdict last; the tail line always stays. Past that, the earlier findings go oldest first.
+function describe(
+	issue: string,
+	context: StopContext,
+	budget: number = agent_role_profile.MAX_VALUE_LENGTH,
+): string {
+	let fitted = context
+	let block = fitted_block(issue, fitted, budget)
+
+	while (block.length > budget && has_prior(fitted)) {
+		fitted = { ...fitted, prior: fitted.prior?.slice(1) }
+		block = fitted_block(issue, fitted, budget)
+	}
+
+	return block
+}
+
 const run_ship_stop_context = {
 	CHANGED_PATH_LIMIT,
 	EXCERPT_LINE_LIMIT,

package/scripts/run/ship/run-ship-stop-text.ts

@@ -1,15 +1,20 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 
 // The text a `josh ship` supervisor records when a stage stops, written and read in one place so the
-// retrospective's per-stage count never drifts from the writer.
-const STOP_PATTERN = /^#\d+ (\S+) failed — /u
+// retrospective's per-stage count never drifts from the writer. The cause rides in parentheses after
+// `failed` (`run-ship-stop-cause.ts`); a text written before it had one reads back with none.
+const STOP_PATTERN = /^#\d+ (?<reason>\S+) failed(?: \((?<cause>\S+)\))? — /u
 
-function format(issue: string, reason: string): string {
-	return `${issue_cite.plain(issue)} ${reason} failed — pnpm josh ship --log ${issue}`
+function format(issue: string, reason: string, cause: string): string {
+	return `${issue_cite.plain(issue)} ${reason} failed (${cause}) — pnpm josh ship --log ${issue}`
 }
 
 function reason_of(text: string): string | undefined {
-	return STOP_PATTERN.exec(text)?.[1]
+	return STOP_PATTERN.exec(text)?.groups?.['reason']
 }
 
-export const run_ship_stop_text = { format, reason_of }
+function cause_of(text: string): string | undefined {
+	return STOP_PATTERN.exec(text)?.groups?.['cause']
+}
+
+export const run_ship_stop_text = { format, reason_of, cause_of }

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

@@ -1,21 +1,31 @@
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
-import { is_merge_conflict } from '#scripts/gh/git-pr-checks-eval'
+import {
+	FAILURE_MESSAGE_PREFIX,
+	FAILURE_REASON_CHECKS,
+	FAILURE_REASON_CONFLICT,
+} from '#scripts/gh/git-pr-checks-eval'
 import { git_command } from '#scripts/git/git-command'
 import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
+import { pre_commit_lint_switch } from '#scripts/hooks/pre-commit-lint-switch'
+import { pre_push_related_switch } from '#scripts/hooks/pre-push-related-switch'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
+import { run_ship_lap } from './run-ship-lap'
 import { run_ship_overlap } from './run-ship-overlap'
 import { run_ship_scoped } from './run-ship-scoped'
+import { run_ship_stop_cause, type Cause } from './run-ship-stop-cause'
 
 // `josh ship` keeps the branch current with the default branch itself: a default branch that moves
 // while the pull request opens and CI runs would otherwise stop the followup as `interrupted`, though
 // merging the default branch again usually resolves it.
 //
-// So the merge happens mechanically: once before the commit (`sync_stage`), and once when
-// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). A conflict only on
-// generated files is regenerated by the merge itself (`main-merge-regenerate.ts`); any other conflict
+// So the merge happens mechanically: before the gate (`sync_stage`), again before the push when the
+// default branch moved since (`catch_up`), and when the followup fails after it moved again
+// (`followup_stage`). A conflict only on
+// the files `main-merge-regenerate.ts` lists is resolved by the merge itself; any other conflict
 // stops the ship as `conflict`, naming the unmerged paths so the resumed session goes straight to them.
 
+const { STEP, timed } = run_ship_lap
 const should_forward_stderr = true
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -26,13 +36,30 @@ const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
 const DEFERRED_PREFIX = 'merge deferred to the followup: '
 const CURRENT_SUFFIX = ' brings nothing in'
 const MERGED_PREFIX = 'merged '
+const MERGED_GATE_NOTE =
+	'the default branch moved since the sync; the tree merged with it fails the gate:'
+const PUSHED_NOTE = 'pushed the merge ahead of the gate, so CI runs beside it'
+const PUSH_FAILED_NOTE =
+	'the push ahead of the gate failed; the commit stage pushes after the gate:'
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
 // `is_skipped` marks a stage that found nothing to do — a review round with nothing to review, a gate
-// that reused a green record — so its few seconds are not timed as a run of it.
+// that reused a green record — so its few seconds are not timed as a run of it. `preconditions` names
+// the kinds of the preconditions a stopped preflight found unmet (`run-ship-preflight.ts`). `cause` is the
+// one a stopped stage tagged its stop with — a review round, or a red gate over a merged tree
+// (`run-ship-stop-cause.ts`). `reason` says why the stage ran or was skipped, written on its event line
+// (`run-ship-review-reason.ts`).
 interface StepResult extends JoshResult {
 	is_skipped?: boolean
+	reason?: string
 	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
+}
+
+// The push of a tree already committed, with no pull request touched.
+function push_argv(title: string): ReadonlyArray<string> {
+	return ['git', '-y', '--skip-commit', '--skip-pr', title]
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -43,7 +70,7 @@ async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
 // changed, and the followup still finds a real conflict on GitHub's side.
 async function merge_outcome(): Promise<MergeOutcome> {
 	try {
-		return await main_merge.merge()
+		return await timed(STEP.MERGE, async () => await main_merge.merge())
 	} catch (error) {
 		return { kind: 'refused', message: error_text.message_of(error) }
 	}
@@ -63,51 +90,161 @@ function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string
 		: `${MERGED_PREFIX}${outcome.branch}`
 }
 
-// A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
-// touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
-// the tree is checked by the gate stage that follows, so the commit never carries
-// an unchecked merge and the gate's record names the merge base the push carries.
-//
+// Uncommitted work is committed locally first, never stashed: the merge guard refuses uncommitted work
+// the default branch also touches, and a merge deferred past it met its conflict only after the gate,
+// both review rounds and CI (joshuafolkken/kit#4708). The commit is not pushed here: a tree the sync
+// leaves unmerged goes out at the commit stage once the gate is green (`push_ahead` pushes a merged
+// one). A refusal left — a fetch that failed — does not stop the ship: the commit stage and the
+// followup merge again.
+// The pre-commit prettier, cspell and eslint are switched off for it: the gate or the scoped pair runs
+// the same checks over this tree before anything is pushed, and the hooks only waited for the core
+// budget to repeat them (joshuafolkken/kit#4985).
+async function commit_locally(title: string, is_dirty: boolean): Promise<JoshResult | undefined> {
+	if (!is_dirty) return undefined
+
+	const commit = await timed(
+		STEP.LOCAL_COMMIT,
+		async () =>
+			await josh_command.josh_run(
+				['git', '-y', '--skip-push', '--skip-pr', title],
+				should_forward_stderr,
+				undefined,
+				{ [pre_commit_lint_switch.SWITCH_ENV_KEY]: 'off' },
+			),
+	)
+
+	return commit.code === SUCCESS_EXIT_CODE ? undefined : commit
+}
+
+// **A merge the sync made is pushed at once onto an open pull request, ahead of the gate**
+// (joshuafolkken/kit#5067): CI and SonarQube start from this push, and pushed after the gate they ran
+// behind it, leaving the followup minutes of waiting. Only the pull request's own branch moves; the
+// merge still needs the gate, the review attest and a green CI, and a red gate stops the ship before
+// the followup as before, the next push replacing the commit. Its pre-push hook runs the related tests
+// (`pre-push-related-switch.ts`), since the gate over this same tree runs the whole suite next. A
+// branch with no open pull request pushes nothing here: CI runs on pull requests only. An unmoved
+// default branch pushes nothing either, so the commit stage stays the one push; a merged one makes it
+// two, and CI and the review bots run again on the second. A failed push stops nothing: the commit
+// stage pushes the gated tree.
+async function push_ahead(title: string): Promise<string> {
+	const push = await timed(
+		STEP.PUSH,
+		async () =>
+			await josh_command.josh_run(push_argv(title), should_forward_stderr, undefined, {
+				[pre_push_related_switch.SWITCH_ENV_KEY]: pre_push_related_switch.SWITCH_ON,
+			}),
+	)
+
+	return push.code === SUCCESS_EXIT_CODE ? PUSHED_NOTE : [PUSH_FAILED_NOTE, push.out].join('\n')
+}
+
+// An unreadable pull request reads as none: the commit stage pushes after the gate either way.
+async function has_open_pull(): Promise<boolean> {
+	try {
+		return (await git_gh_pr_read.pr_get_number(await git_command.branch())) !== undefined
+	} catch {
+		return false
+	}
+}
+
+async function pushed_note(outcome: MergeOutcome, title: string): Promise<string> {
+	if (outcome.kind !== 'merged' || !(await has_open_pull())) return ''
+
+	return await push_ahead(title)
+}
+
+async function waited_note(issue: string): Promise<string> {
+	const overlap = await timed(
+		STEP.OVERLAP_WAIT,
+		async () => await run_ship_overlap.await_overlap(issue),
+	)
+
+	return run_ship_overlap.note(overlap)
+}
+
 // The merge waits first for any lane whose open pull request changes the same paths
 // (`run-ship-overlap.ts`), so it brings that pull request in before the gate rather than meeting it
 // as `DIRTY` after CI.
-async function sync_stage(issue: string): Promise<StepResult> {
-	const waited = run_ship_overlap.note(await run_ship_overlap.await_overlap(issue))
+async function sync_stage(issue: string, title: string, is_dirty: boolean): Promise<StepResult> {
+	const waited = await waited_note(issue)
+	const failed_commit = await commit_locally(title, is_dirty)
+
+	if (failed_commit !== undefined) {
+		const out = [waited, failed_commit.out].filter((line) => line !== '').join('\n')
+
+		return { ...failed_commit, out }
+	}
+
 	const outcome = await merge_outcome()
 
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, waited)
 
-	const out = [waited, sync_note(outcome)].filter((line) => line !== '').join('\n')
+	const pushed = await pushed_note(outcome, title)
+	const out = [waited, sync_note(outcome), pushed].filter((line) => line !== '').join('\n')
 
 	return { code: SUCCESS_EXIT_CODE, out }
 }
 
-// Any read that fails answers "not conflicting": the followup failure then stands as it was.
-async function is_conflicting(): Promise<boolean> {
-	try {
-		const state = await git_gh_pr_read.pr_get_merge_state(await git_command.branch())
+// The tree merged with a default branch that moved is gated before it is pushed: a tree only the
+// combined change breaks — two lanes each growing one document inside its cap — stops here, reproduced
+// locally rather than met on CI's merge ref (joshuafolkken/kit#4825). The push then carries the tree
+// the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
+// Its red is tagged a check, so the stage's infrastructure retry never reads test output as an outage.
+async function gate_merged(): Promise<StepResult | undefined> {
+	const gate = await run_ship_scoped.scoped_gate()
 
-		return is_merge_conflict(state?.merge_state_status)
-	} catch {
-		return false
-	}
+	if (gate.code === SUCCESS_EXIT_CODE) return undefined
+
+	const out = [MERGED_GATE_NOTE, gate.out].filter((line) => line !== '').join('\n')
+
+	return { ...gate, out, cause: run_ship_stop_cause.CAUSE.CHECK }
+}
+
+// Before the commit stage pushes: a default branch that moved since the sync stage is merged again and
+// the merged tree gated, so the stop lands while the lane still waits on the ship. An unmoved one
+// merges nothing and re-runs no gate; a refusal leaves the merge to the followup, as the sync does.
+// A tree with no green gate record is gated whatever the merge answered: a re-run commit stage finds
+// the merge its red gate stopped on already made, and must not push it without a gate.
+async function catch_up(): Promise<StepResult | undefined> {
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
+	if (outcome.kind !== 'merged' && (await run_ship_scoped.is_gate_green())) return undefined
+
+	return await gate_merged()
 }
 
-// The merged tree is gated before it is pushed: the push then carries the tree
-// the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
 async function push_merged(title: string): Promise<StepResult | undefined> {
-	const gate = await run_ship_scoped.scoped_gate()
+	const gate = await gate_merged()
 
-	if (gate.code !== SUCCESS_EXIT_CODE) return gate
+	if (gate !== undefined) return gate
 
-	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+	const push = await josh(push_argv(title))
 
 	return push.code === SUCCESS_EXIT_CODE ? undefined : push
 }
 
+// The followup's reasons a newer base can change: a red check or a conflict.
+const MERGE_FIXABLE_REASONS = [FAILURE_REASON_CHECKS, FAILURE_REASON_CONFLICT]
+
+function names_merge_fixable(text: string | undefined): boolean {
+	if (text?.includes(FAILURE_MESSAGE_PREFIX) !== true) return false
+
+	return MERGE_FIXABLE_REASONS.some((reason) => text.includes(reason))
+}
+
+// Whether the followup failed on the pull request's checks — a red check or a conflict. A refusal
+// before the wait, or a review blocker alone, is not one: its text carries neither reason.
+function is_checks_failure(failed: JoshResult): boolean {
+	return [failed.out, failed.err].some((text) => names_merge_fixable(text))
+}
+
 // The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
+// A followup that failed on the checks merges again whenever the default branch moved since the push,
+// conflicting or not: a red CI on the merge ref is then reproduced by the local gate or cleared by the
+// new push. An unmoved default branch, or any other failure, stands.
 async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
-	if (!(await is_conflicting())) return failed
+	if (!is_checks_failure(failed)) return failed
 
 	const outcome = await merge_outcome()
 
@@ -117,21 +254,62 @@ async function merge_again(title: string, failed: JoshResult): Promise<StepResul
 	return await push_merged(title)
 }
 
-async function followup_stage(
+// Whether the ship waits on the merge alone, for its stage record (`run_ship_stage.mark_merge_waiting`).
+type WaitMark = (is_merge_waiting: boolean) => void
+
+function ignore_wait(): void {
+	// A ship with no stage record has no lane place to free.
+}
+
+// The wait is marked only while `josh followup` runs: the merge again and its gate run unmarked, so a
+// lane gating here still holds its place (joshuafolkken/kit#4466).
+async function marked_followup(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark,
+): Promise<JoshResult> {
+	mark(true)
+
+	try {
+		return await josh(['followup', title, ...notify])
+	} finally {
+		mark(false)
+	}
+}
+
+async function followup_attempt(
 	title: string,
 	notify: ReadonlyArray<string>,
-	retries = 0,
+	mark: WaitMark,
+	retries: number,
 ): Promise<StepResult> {
-	const result = await josh(['followup', title, ...notify])
+	const result = await marked_followup(title, notify, mark)
 
 	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
 
 	const stop = await merge_again(title, result)
 
-	return stop ?? (await followup_stage(title, notify, retries + 1))
+	return stop ?? (await followup_attempt(title, notify, mark, retries + 1))
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark = ignore_wait,
+): Promise<StepResult> {
+	return await followup_attempt(title, notify, mark, 0)
 }
 
-const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
+const run_ship_sync = {
+	CONFLICT_NOTE,
+	MAX_MERGE_RETRIES,
+	MERGED_GATE_NOTE,
+	PUSHED_NOTE,
+	PUSH_FAILED_NOTE,
+	catch_up,
+	followup_stage,
+	sync_stage,
+}
 
-export type { StepResult }
+export type { StepResult, WaitMark }
 export { run_ship_sync }

package/scripts/run/ship/run-ship-synced-scope.ts

@@ -0,0 +1,178 @@
+import { gate_labels } from '#scripts/gate/gate-labels'
+import type { GateTree } from '#scripts/gate/gate-tree'
+import type { MovedParts } from '#scripts/gate/moved-paths'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { since_green } from '#scripts/gate/since-green'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { changed_paths } from '#scripts/git/changed-paths'
+import type { FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+import { run_record_path } from '#scripts/josh/run-record-path'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { test_read_map, type ReadMap } from '#scripts/test/test-read-map'
+import { related_scope } from '#scripts/test/test-related-scope'
+import { test_related_synced, type SyncedSplit } from '#scripts/test/test-related-synced'
+import { whole_suite_files } from '#scripts/test/whole-suite-files'
+
+// **A scoped pair whose records went stale only because a merge with the default branch moved the base
+// re-runs nothing when that merge shares nothing with this branch's change** (joshuafolkken/kit#4985).
+// The sync, the commit stage's catch-up and a lane's own conflict merge each moved the base under a
+// pair green on the branch side, and the pair re-ran over the branch's related set — minutes of core
+// budget for main's files, which main's CI had already verified.
+//
+// **Where the two can meet still runs.** A file both sides changed, a test reaching both a synced module
+// and this branch's change (`test-related-synced.ts`), or a synced module the import graph cannot
+// split keeps the pair running as before, narrowed by the checks themselves (`since-green.ts`). So
+// does, for `lint:related`, any file whose imports reach both sides, and for `test:related` a synced
+// file every test depends on or a non-code file a test reads: `josh test:related` leaves those to the
+// branch's own tests, which a settled record would skip. The
+// gate still runs over the merged tree wherever it ran before (joshuafolkken/kit#4825), and CI runs
+// the whole suite.
+//
+// **Whatever cannot be read settles nothing**: a record that is absent or cannot be compared, a branch
+// side that moved since its record, a merge that changed a check's configuration, or a branch change
+// git cannot read.
+
+interface SyncedCheck {
+	script: string
+	label: string
+	stamp: FileMapStampAccess
+}
+
+const CHECKS: ReadonlyArray<SyncedCheck> = [
+	{
+		script: scoped_green.LINT_SCRIPT,
+		label: gate_labels.LINT_LABEL,
+		stamp: review_stamps.lint_related_stamp,
+	},
+	{
+		script: scoped_green.TEST_SCRIPT,
+		label: gate_labels.UNIT_LABEL,
+		stamp: review_stamps.test_related_stamp,
+	},
+]
+
+function is_sync_only(parts: MovedParts): boolean {
+	return (
+		parts.synced.length > 0 &&
+		parts.changed.every((relative) => run_record_path.is_run_record(relative))
+	)
+}
+
+async function synced_of(
+	check: SyncedCheck,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await since_green.read_moved_parts(check.stamp, check.label, undefined, tree)
+
+	return parts !== undefined && is_sync_only(parts) ? parts.synced : undefined
+}
+
+// What the merge brought in, when every stale record moved by nothing else.
+async function synced_files(
+	checks: ReadonlyArray<SyncedCheck>,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await Promise.all(checks.map(async (check) => await synced_of(check, tree)))
+	const known = parts.filter((synced) => synced !== undefined)
+
+	return known.length > 0 && known.length === parts.length ? [...new Set(known.flat())] : undefined
+}
+
+async function branch_change(): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		return await changed_paths.read_changed_paths(false)
+	} catch {
+		return undefined
+	}
+}
+
+function is_whole_suite(file: string): boolean {
+	return whole_suite_files.WHOLE_SUITE_FILES.has(file)
+}
+
+// A synced file a test can reach with no import the graph splits: one every test depends on, or a
+// non-code file a recorded test reads — every one of them when no map was recorded.
+function is_read_by_tests(map: ReadMap | undefined, file: string): boolean {
+	if (is_whole_suite(file)) return true
+	if (related_scope.is_relatable(file)) return false
+
+	return map === undefined || test_read_map.readers_of(map, file).length > 0
+}
+
+function has_check(checks: ReadonlyArray<SyncedCheck>, script: string): boolean {
+	return checks.some((check) => check.script === script)
+}
+
+// What only one check reads where the two sides meet. `lint:related`'s type-aware rules read every
+// file whose imports reach both, code between included; `test:related` leaves a file the graph
+// cannot split to the branch's own tests (`test-related.ts`), which a settled record would skip.
+function check_overlap(
+	checks: ReadonlyArray<SyncedCheck>,
+	synced: ReadonlyArray<string>,
+	split: SyncedSplit,
+	map: ReadMap | undefined,
+): ReadonlyArray<string> {
+	const meeting = has_check(checks, scoped_green.LINT_SCRIPT) ? split.meeting : []
+	const read = has_check(checks, scoped_green.TEST_SCRIPT)
+		? synced.filter((file) => is_read_by_tests(map, file))
+		: []
+
+	return [...meeting, ...read]
+}
+
+// The synced files and tests where the merge and this branch's change meet.
+async function overlap_of(
+	checks: ReadonlyArray<SyncedCheck>,
+	synced: ReadonlyArray<string>,
+	branch: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> {
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const map = test_read_map.read_map(root)
+	const split = await test_related_synced.split(root, synced, branch, map)
+	const both = synced.filter((file) => branch.includes(file))
+	// Code the graph left unsplit — whole-suite modules included, which it never splits.
+	const unsplit = synced.filter(
+		(file) =>
+			related_scope.is_relatable(file) && !branch.includes(file) && !split.left.includes(file),
+	)
+
+	return [...both, ...split.shared, ...unsplit, ...check_overlap(checks, synced, split, map)]
+}
+
+async function unshared_sync(
+	checks: ReadonlyArray<SyncedCheck>,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const synced = await synced_files(checks, tree)
+	const branch = synced === undefined ? undefined : await branch_change()
+
+	if (synced === undefined || branch === undefined) return undefined
+
+	const overlap = await overlap_of(checks, synced, branch)
+
+	return overlap.length === 0 ? synced : undefined
+}
+
+function reason(scripts: ReadonlyArray<string>, synced: ReadonlyArray<string>): string {
+	return (
+		`scoped pair: ${scripts.join(' and ')} not re-run — the ${String(synced.length)} file(s) ` +
+		"the merge with the default branch brought in share no file or test with this branch's change."
+	)
+}
+
+// The line a settled pair prints, after re-recording each stale check green on this tree so the gate
+// and the brief read it as checked — or `undefined`, and the pair runs as before.
+async function settle(tree: GateTree, scripts: ReadonlyArray<string>): Promise<string | undefined> {
+	const checks = CHECKS.filter((check) => scripts.includes(check.script))
+	const synced = await unshared_sync(checks, tree)
+
+	if (synced === undefined) return undefined
+
+	for (const check of checks) scoped_green.record_green(check.stamp, tree)
+
+	return reason(scripts, synced)
+}
+
+const run_ship_synced_scope = { settle }
+
+export { run_ship_synced_scope }