@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/followup/git-followup-workflow.ts

@@ -2,16 +2,14 @@
 import { parseArgs } from 'node:util'
 import { git_branch } from '#scripts/git/git-branch'
 import { git_error } from '#scripts/git/git-error'
-import { issue_number_shape } from '#scripts/issue/issue-number-shape'
-import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { cli_body } from '#scripts/josh/cli-body'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
 import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
-import { review_attest } from '#scripts/review/review-attest'
-import { review_record } from '#scripts/review/review-record'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
 import { parse_issue_number_from_text } from './followup-issue-number'
+import { followup_review_gates } from './followup-review-gates'
 import { git_followup_finish } from './git-followup-finish'
 import { git_followup_flush } from './git-followup-flush'
 import { git_followup_merged, type MergePlan } from './git-followup-merged'
@@ -121,66 +119,7 @@ function is_merge_resolved(values: CliArguments['values']): boolean {
 	return values['no-merge'] !== true
 }
 
-// `/code-review` is forked by the harness and inherits the *session's* working directory, so a run
-// implementing in a lane can be reviewed against a different tree entirely — one holding the
-// previous child's already-merged code. That review finds nothing wrong and says so, and the run
-// would read the silence as a clean round. **This is the seam where that is caught**: a merge is
-// refused unless the review attested the checkout it was briefed on.
-//
-// **Absence is a refusal, not a pass.** The defect produces *no* signal, so a check that only
-// compared two present records would answer `ok` in exactly the state it exists to catch.
-//
-// **Scoped to a checkout that actually briefed a review.** `review_attest.check` answers
-// `not-required` where no `josh review:brief` was run here inside a run's lifetime, so a project or
-// a flow that does not use the brief merges exactly as it did before.
-//
-// The direction is deliberate: a wrongly-refused merge costs one re-run of the review, and a wrongly
-// allowed one ships a diff nobody read. Thrown rather than reported, so no `completion` Telegram is
-// sent and nothing merges — `git_pr_followup.run` is never reached.
-// `ok` means the guard was satisfied and `not-required` means it never applied to this checkout —
-// both let the merge proceed, so the two gates below read the verdict through one predicate rather
-// than repeating the pair of statuses.
-function is_merge_permitted(status: string): boolean {
-	return status === 'ok' || status === 'not-required'
-}
-
-function is_valid_issue(issue_number: string | undefined): issue_number is string {
-	return issue_number !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
-}
-
-async function assert_review_attested(should_merge: boolean): Promise<void> {
-	if (!should_merge) return
-
-	const verdict = await review_attest.check_here()
-
-	if (!is_merge_permitted(verdict.status)) throw new Error(review_attest.refusal_message(verdict))
-
-	const refusal = await issue_watch_gate.review_refusal_here()
-
-	if (refusal !== undefined) throw new Error(refusal)
-}
-
-// Recording a review round as a prose request leaves the recurrence ledger blind whenever it is
-// skipped. **This is the seam where it is a gate instead**: a merge is refused unless the round left
-// a `- rf:` line for its issue, a zero-finding `none` line included.
-//
-// **Absence is a refusal, `missing` exactly as `assert_review_attested`'s is** — the defect this
-// exists for produces *no* line, so silence must not read as success. A checkout that keeps no ledger
-// answers `not-required` and merges as before, and a run whose issue the followup cannot identify has
-// no key to check, so it carries on rather than blocking on missing information.
-async function assert_review_recorded(
-	should_merge: boolean,
-	issue_number: string | undefined,
-): Promise<void> {
-	if (!should_merge || !is_valid_issue(issue_number)) return
-
-	const issue = Number(issue_number)
-	const verdict = await review_record.check(issue)
-
-	if (is_merge_permitted(verdict.status)) return
-
-	throw new Error(review_record.refusal_message(issue))
-}
+const { assert_review_attested, assert_review_recorded, is_valid_issue } = followup_review_gates
 
 // A runtime change merges only with its acceptance criteria run for real and
 // recorded in the pull request body — `live_evidence` carries the why. `exempt` (no runtime path
@@ -210,6 +149,20 @@ async function assert_acceptance_mapped(
 	if (refusal !== undefined) throw new Error(refusal)
 }
 
+// Every test the change removes is disposed of in the pull request body — `removed_tests` carries the
+// why. It reads this checkout's diff, which `assert_live_evidence` has already refused to read for a
+// branch other than the one checked out.
+async function assert_removed_tests_disposed(
+	should_merge: boolean,
+	branch_name: string,
+): Promise<void> {
+	if (!should_merge) return
+
+	const refusal = await removed_tests_check.refusal(branch_name)
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
 // Every pre-merge refusal, in order — each one throws, so nothing merges past the first that fails.
 async function assert_merge_gates(
 	should_merge: boolean,
@@ -220,6 +173,7 @@ async function assert_merge_gates(
 	await assert_review_recorded(should_merge, issue_number)
 	await assert_live_evidence(should_merge, branch_name)
 	await assert_acceptance_mapped(should_merge, issue_number, branch_name)
+	await assert_removed_tests_disposed(should_merge, branch_name)
 }
 
 // After the gates, before the CI wait: a line appended since the run's commit rides the pull request
@@ -280,8 +234,7 @@ try {
 const git_followup_workflow = {
 	assert_acceptance_mapped,
 	assert_live_evidence,
-	assert_review_attested,
-	assert_review_recorded,
+	assert_removed_tests_disposed,
 	parse_issue_number_from_text,
 	prepare_merge,
 	resolve_branch_name,

package/scripts/followup/git-pr-followup-wrapup.ts

@@ -1,5 +1,8 @@
 import { epic_close } from '#scripts/epic/epic-close'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks'
+import { git_pr_merge_checked, type WaitForGreen } from '#scripts/gh/git-pr-merge-checked'
+import { issue_body_or_comment } from '#scripts/issue/issue-body-or-comment'
 import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
 import { git_followup_cleanup } from './git-followup-cleanup'
@@ -40,6 +43,10 @@ interface WrapupInput {
 	// already on the issue does not post it twice (`git-followup-merged.ts`).
 	is_merged?: boolean | undefined
 	is_completion_recorded?: boolean | undefined
+	// The snapshot the merge gate passed, whose head the merge names, and the wait to go back to when
+	// that head moved before the merge (`git-pr-merge-checked.ts`, #4036).
+	checked?: PrStateSnapshot | undefined
+	wait_for_green: WaitForGreen
 }
 
 function build_notify_body(input: {
@@ -57,12 +64,6 @@ function build_notify_body(input: {
 	})
 }
 
-function is_blank_issue_body(body: string | undefined): boolean {
-	if (body === undefined) return true
-
-	return body.trim().length === 0
-}
-
 async function post_notify_issue(input: {
 	issue_number: string | undefined
 	body: string
@@ -71,12 +72,7 @@ async function post_notify_issue(input: {
 		throw new Error('Issue number is required for issue notification.')
 	}
 
-	const current_body = await git_gh_command.issue_get_body(input.issue_number)
-	const should_edit_body = current_body !== undefined && is_blank_issue_body(current_body)
-
-	await (should_edit_body
-		? git_gh_command.issue_edit_body(input.issue_number, input.body)
-		: git_gh_command.issue_comment(input.issue_number, input.body))
+	await issue_body_or_comment.post(input.issue_number, input.body)
 }
 
 function should_notify_pr(target: GitNotifyConfig['target']): boolean {
@@ -239,7 +235,7 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {
 	if (input.should_merge && input.is_merged !== true) {
 		await issue_watch_gate.assert_read_here()
-		await git_gh_command.pr_merge(input.branch_name)
+		await git_pr_merge_checked.merge_checked(input)
 		lap(log, STAGE.merge)
 	}
 
@@ -256,7 +252,6 @@ export {
 	git_pr_followup_wrapup,
 	post_notify_issue,
 	post_completion_notification,
-	is_blank_issue_body,
 	build_notify_body,
 }
 export type { WrapupInput }

package/scripts/followup/git-pr-followup.ts

@@ -1,7 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr_ai_review, type TelegramContext } from '#scripts/gh/git-pr-ai-review'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks'
 import { git_pr_coderabbit } from '#scripts/gh/git-pr-coderabbit'
 import { git_pr_managed_config } from '#scripts/gh/git-pr-managed-config'
+import type { WaitForGreen } from '#scripts/gh/git-pr-merge-checked'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
 import type { GitNotifyConfig } from '#scripts/notify/git-notify'
@@ -11,6 +13,7 @@ import {
 	type TelegramTaskType,
 } from '#scripts/notify/telegram-notify'
 import { followup_checks_event } from './followup-checks-event'
+import { followup_coderabbit_wait } from './followup-coderabbit-wait'
 import { git_followup_merged } from './git-followup-merged'
 import { git_followup_pending } from './git-followup-pending'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
@@ -226,22 +229,45 @@ async function run_comment_scans(
 // different destinations: every note reaches the completion notification, and this one alone also
 // reaches the completion report posted to the Issue. Returning it twice is
 // what lets `run_stages` hand each destination what belongs to it without re-deriving the answer.
+//
+// **The snapshot travels on to the merge**, which names its head, and the same wait is what the merge
+// goes back to when that head moved before it (#4036).
+interface ReviewChecks {
+	notes: Array<string>
+	managed: Array<string>
+	snapshot?: PrStateSnapshot
+}
+
+function wait_for_green_of(
+	input: FollowupInput,
+	context: TelegramContext,
+	issue_number: string | undefined,
+	log: StageLog,
+): WaitForGreen {
+	return async function wait_for_green(): Promise<PrStateSnapshot> {
+		return await run_checks({
+			branch_name: input.branch_name,
+			is_skip_watch: input.is_skip_watch,
+			observe: followup_coderabbit_wait.both(
+				followup_checks_event.observer_of(issue_number, context.pr_url),
+				followup_coderabbit_wait.observer_of(log.coderabbit),
+			),
+		})
+	}
+}
+
 async function run_review_checks(
 	input: FollowupInput,
 	context: TelegramContext,
 	log: StageLog,
 	issue_number: string | undefined,
-): Promise<{ notes: Array<string>; managed: Array<string> }> {
+): Promise<ReviewChecks> {
 	if (input.is_merged === true) return { notes: [], managed: [] }
 
 	const managed = await git_pr_managed_config.handle_managed_config_changes({
 		should_merge: input.should_merge,
 	})
-	const snapshot = await run_checks({
-		branch_name: input.branch_name,
-		is_skip_watch: input.is_skip_watch,
-		observe: followup_checks_event.observer_of(issue_number, context.pr_url),
-	})
+	const snapshot = await wait_for_green_of(input, context, issue_number, log)()
 
 	lap(log, STAGE.checks_wait)
 	const check_notes = read_coderabbit_skip_notes(snapshot)
@@ -249,7 +275,7 @@ async function run_review_checks(
 	log_skip_notes(check_notes)
 	const scan_notes = await run_comment_scans(input, context, log)
 
-	return { notes: [...managed, ...check_notes, ...scan_notes], managed }
+	return { notes: [...managed, ...check_notes, ...scan_notes], managed, snapshot }
 }
 
 // **A tail re-run after a merge does not report twice**: where the issue
@@ -296,6 +322,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 			managed_notes: checks.managed,
 			is_merged: input.is_merged,
 			is_completion_recorded,
+			checked: checks.snapshot,
+			wait_for_green: wait_for_green_of(input, context, issue_number, log),
 		},
 		log,
 	)
@@ -319,7 +347,7 @@ async function run(input: FollowupInput): Promise<string | undefined> {
 		throw error
 	} finally {
 		git_followup_stages.print_stages(log)
-		await git_followup_stages.record_ci_wait(log)
+		await git_followup_stages.record_waits(log)
 	}
 }
 

package/scripts/fresh-machine/fresh-machine-cli.ts

@@ -24,7 +24,7 @@ const USAGE =
 	'Usage: josh fresh:run <pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list'
 // The scratch directory kit's distributed `.gitignore` already ignores, so a log is never committed
 // from kit or from a consumer toolkit.
-const DEFAULT_LOG_DIRECTORY = '.claude/tmp/fresh-machine'
+const DEFAULT_LOG_DIRECTORY = '.josh/tmp/fresh-machine'
 const NO_GITHUB_TOKEN =
 	'This scenario uses GitHub and `gh auth token` printed no token. Run `gh auth login` on this machine first.'
 const NO_CLAUDE_TOKEN = `This scenario uses Claude Code and neither the macOS keychain nor ${claude_token.VARIABLE} holds a token. ${claude_token.SETUP_HINT}`

package/scripts/fresh-machine/fresh-machine-run.ts

@@ -4,13 +4,14 @@ import {
 	mkdirSync,
 	mkdtempSync,
 	readdirSync,
-	readFileSync,
 	rmSync,
 	writeFileSync,
 } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { package_manifest } from '#scripts/lib/package-manifest'
+import { npm_registry } from '#scripts/version/npm-registry'
 import { execa, type Options } from 'execa'
 import { z } from 'zod'
 import { fresh_machine_docker, type ContainerRun } from './fresh-machine-docker'
@@ -133,19 +134,18 @@ async function pack(pack_directory: string, write: Write): Promise<string> {
 }
 
 function package_name(): string {
-	const manifest = readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8')
-
-	return MANIFEST_SCHEMA.parse(JSON.parse(manifest)).name
+	return package_manifest.read_manifest(PROJECT_ROOT, MANIFEST_SCHEMA).name
 }
 
 // The published version is always written out in the log and the install command, so a run can be
 // repeated against the same release; without `--package-version` it is the registry's latest.
-async function published_version(requested: string | undefined): Promise<string> {
+function published_version(requested: string | undefined): string {
 	if (requested !== undefined) return requested
 
-	const { stdout } = await execa(PNPM, ['view', package_name(), 'version'], { cwd: PROJECT_ROOT })
+	const answer = npm_registry.view(package_name(), 'version')
+	if (answer.exit_code !== 0) throw new Error('the registry did not answer the latest version')
 
-	return stdout.trim()
+	return answer.stdout.trim()
 }
 
 async function container_run(
@@ -163,7 +163,7 @@ async function container_run(
 		seed_directory: staged.seed_directory,
 		pack_directory: staged.pack_directory,
 		tarball: is_tarball ? await pack(staged.pack_directory, write) : undefined,
-		package_version: is_tarball ? undefined : await published_version(request.package_version),
+		package_version: is_tarball ? undefined : published_version(request.package_version),
 		secret_names: Object.keys(request.secrets),
 	}
 }

package/scripts/fresh-machine/specs/kit-test-backlogrun.json

@@ -12,7 +12,7 @@
 		"printf '{ \"private\": true }\\n' > package.json",
 		"cp \"$PACKAGE_TARBALL\" . && pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver \"./$(basename \"$PACKAGE_TARBALL\")\"",
 		"pnpm exec josh start --yes --github",
-		"gh label list --limit 100 --json name --jq '.[].name' > \"$HOME/labels.txt\"; grep -xE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\"; test \"$(grep -cxE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\")\" -eq 6",
+		"gh label list --limit 100 --json name --jq '.[].name' > \"$HOME/labels.txt\"; grep -xE 'auto-ok|needs-decision|needs-human-review|already-done|bug' \"$HOME/labels.txt\"; test \"$(grep -cxE 'auto-ok|needs-decision|needs-human-review|already-done|bug' \"$HOME/labels.txt\")\" -eq 5",
 		"curl -fsSL https://claude.ai/install.sh | bash && export PATH=\"$HOME/.local/bin:$PATH\" && claude --version",
 		"gh issue create --title 'Add a heading to index.html' --body 'Add an h2 under the h1.' --label auto-ok --label run:lane",
 		"timeout 60 pnpm josh backlogrun > \"$HOME/backlogrun.out\" 2>&1; cat \"$HOME/backlogrun.out\"; grep -q '^backlogrun: started' \"$HOME/backlogrun.out\"",

package/scripts/gate/busy-average.ts

@@ -0,0 +1,58 @@
+import type { MachineReading } from './machine-capacity'
+
+// **The busy cores a waiting claim admits against are the mean of its last few seconds of readings**
+// (joshuafolkken/kit#4238). One reading covers a 250 ms window, and a CPU near saturation swings across
+// the threshold from one window to the next, so a claim judged on each reading alone would be admitted
+// on a dip into load that is still there. A claim's readings are its own: each poll of one wait adds
+// one, and its first poll judges on the one it has.
+//
+// **What is averaged is the load outside the ledger, each sample against the ledger of its own
+// moment.** Averaging the raw busy cores and subtracting the ledger of now would count a claim released
+// inside the window as external load: its cores would linger in the mean after leaving the ledger.
+
+// Long enough to hold about ten polls of a waiting claim, short enough that a CPU freed a moment ago is
+// admitted against within seconds.
+const AVERAGE_WINDOW_MS = 3000
+
+interface BusySample {
+	at: number
+	external_cores: number
+}
+
+// The samples still inside the window once `reading` taken at `now`, against a ledger holding
+// `ledger_cores`, is added. An unread reading adds nothing: where the machine cannot be read, nothing
+// is averaged.
+function with_reading(
+	samples: ReadonlyArray<BusySample>,
+	reading: MachineReading,
+	ledger_cores: number,
+	now: number,
+): Array<BusySample> {
+	const kept = samples.filter((sample) => now - sample.at < AVERAGE_WINDOW_MS)
+	const { busy_cores } = reading
+
+	if (busy_cores === undefined) return kept
+
+	return [...kept, { at: now, external_cores: Math.max(0, busy_cores - ledger_cores) }]
+}
+
+// `reading` with its busy cores replaced by the mean load outside the ledger on top of the ledger's
+// `ledger_cores` now, or unchanged when none were read.
+function averaged(
+	reading: MachineReading,
+	samples: ReadonlyArray<BusySample>,
+	ledger_cores: number,
+): MachineReading {
+	if (reading.busy_cores === undefined || samples.length === 0) return reading
+
+	let total = 0
+
+	for (const sample of samples) total += sample.external_cores
+
+	return { ...reading, busy_cores: ledger_cores + total / samples.length }
+}
+
+const busy_average = { AVERAGE_WINDOW_MS, averaged, with_reading }
+
+export type { BusySample }
+export { busy_average }

package/scripts/gate/check-cpu.ts

@@ -0,0 +1,60 @@
+import {
+	run_board_usage_rusage,
+	type RusageReader,
+} from '#scripts/run/board/run-board-usage-rusage'
+
+// **The CPU a check's process tree spent, read off the gate's own reaped-children time**
+// (joshuafolkken/kit#4362). Each check is a `pnpm josh <target>` child that waits for its tool before it
+// exits, so once the gate has reaped it the whole tree's CPU sits in the gate's `proc_pid_rusage`
+// child times (`run-board-usage-rusage.ts`, shared rather than read twice). The reader folds the
+// gate's own time in, so `process.cpuUsage()` takes it back out, and each finished check takes the
+// growth since the previous one finished.
+//
+// **A reading is an attribution, not an isolation**: any other child the gate reaped in between — a
+// `ps` sample, a git call — lands on the next check that finishes, and two checks reaped in one tick
+// split their CPU unevenly. Both are small beside a check's tools. Off macOS, or without `node:ffi`,
+// there is no reader and every check records none.
+
+const US_PER_MS = 1000
+
+// The CPU milliseconds spent by the children reaped since the previous call, `undefined` where the
+// gate's own usage cannot be read.
+type CheckCpu = () => number | undefined
+
+function own_cpu_ms(): number {
+	const usage = process.cpuUsage()
+
+	return (usage.user + usage.system) / US_PER_MS
+}
+
+function reaped_cpu_ms(read: RusageReader | undefined, pid: number): number | undefined {
+	const reading = read?.(pid)
+
+	return reading === undefined ? undefined : reading.cpu_ms - own_cpu_ms()
+}
+
+// One gate's reader, its baseline taken now — before any check is reaped.
+function check_cpu_reader(
+	read: RusageReader | undefined = run_board_usage_rusage.rusage_reader(
+		process.platform,
+		run_board_usage_rusage.load_builtin,
+	),
+	pid: number = process.pid,
+): CheckCpu {
+	const previous = { reaped_ms: reaped_cpu_ms(read, pid) }
+
+	return function since_previous(): number | undefined {
+		const reaped_ms = reaped_cpu_ms(read, pid)
+		const before = previous.reaped_ms
+
+		previous.reaped_ms = reaped_ms
+		if (reaped_ms === undefined || before === undefined) return undefined
+
+		return Math.max(0, reaped_ms - before)
+	}
+}
+
+const check_cpu = { check_cpu_reader }
+
+export type { CheckCpu }
+export { check_cpu }

package/scripts/gate/check-inputs.ts

@@ -1,85 +1,24 @@
 import path from 'node:path'
-import { lint_related_scope } from '#scripts/lint/lint-related-scope'
-import { gate_plan } from './gate-plan'
-
-// Which paths each gate check reads, so a gate re-run reuses a check none of whose inputs moved
-// (`check-reuse.ts`). **A check with no scope here always runs**: `cspell` reads every
-// text file, the unit suite reads documents and fixtures as well as code, `behavior` reads a transcript
-// outside the tree and `metrics` reads whatever it measures. Naming a scope for any of them would be a
-// guess, and a wrong guess is a check reported green without having run.
-//
-// **The scopes over-approximate, never under**: a path in doubt is an input. `check` and `exports`
-// read source modules and the JSON they import. `lint` is prettier plus eslint, so its inputs are those
-// sources plus every file prettier formats — the extensions `lint:related` already selects, less what
-// prettier's own ignore files leave out (`.claude/**/*.md`). Prettier answers that itself through
-// `getFileInfo`, so the two ignore files stay the single source.
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { test_related } from '#scripts/test/test-related'
+import {
+	verification_inputs,
+	type InputDeclaration,
+	type PrettierIgnored,
+} from './verification-inputs'
+
+// The file-level answer of a check's declaration (`verification-inputs.ts`): whether any of the paths
+// that moved is one the check reads, so a gate re-run reuses a check none of whose inputs moved
+// (`check-reuse.ts`). It lives apart from the declarations because following imports reads the
+// test-read map (`test-related.ts`), whose own since-green narrowing reads the declarations.
 //
-// **A configuration file is an input of every scoped check**: a manifest or lock file moves the
-// installed toolchain, and an ignore or editor file moves what prettier reads.
-
-const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
-	'.ts',
-	'.tsx',
-	'.mts',
-	'.cts',
-	'.js',
-	'.jsx',
-	'.mjs',
-	'.cjs',
-	'.svelte',
-	'.vue',
-	'.json',
-	'.jsonc',
-])
-
-const GIT_IGNORE = '.gitignore'
-const PRETTIER_IGNORE = '.prettierignore'
-const PRETTIER_IGNORE_FILES = [GIT_IGNORE, PRETTIER_IGNORE] as const
-
-const CONFIG_FILES: ReadonlySet<string> = new Set([
-	'package.json',
-	'pnpm-lock.yaml',
-	'pnpm-workspace.yaml',
-	'package-lock.json',
-	'yarn.lock',
-	'bun.lock',
-	'bun.lockb',
-	'.npmrc',
-	'.editorconfig',
-	...PRETTIER_IGNORE_FILES,
-])
-
-const PRETTIER_CONFIG_PREFIX = '.prettierrc'
-
-// Whether prettier would leave `relative` out; `false` when prettier cannot be asked, which keeps the
-// path an input.
-type PrettierIgnored = (relative: string) => Promise<boolean>
-
-type InputTest = (relative: string, is_ignored: PrettierIgnored) => Promise<boolean>
-
-function is_config(relative: string): boolean {
-	const name = path.basename(relative)
-
-	return CONFIG_FILES.has(name) || name.startsWith(PRETTIER_CONFIG_PREFIX)
-}
-
-function is_source(relative: string): boolean {
-	return SOURCE_EXTENSIONS.has(path.extname(relative))
-}
-
-async function is_lint_input(relative: string, is_ignored: PrettierIgnored): Promise<boolean> {
-	if (is_source(relative)) return true
-	if (!lint_related_scope.is_lintable(relative)) return false
-
-	return !(await is_ignored(relative))
-}
-
-async function is_source_input(relative: string): Promise<boolean> {
-	return is_source(relative)
-}
+// **The unit step's inputs are the test-read map's, not a guess** (joshuafolkken/kit#4314): it is
+// reusable only when `josh test:related` would run no test for what moved — every moved file one no
+// recorded test reads. No map, or one recorded on a tree git can no longer diff against, reaches every
+// test, so the step runs.
 
 function prettier_ignored(root: string): PrettierIgnored {
-	const ignore_path = PRETTIER_IGNORE_FILES.map((name) => path.join(root, name))
+	const ignore_path = verification_inputs.PRETTIER_IGNORE_FILES.map((name) => path.join(root, name))
 
 	return async function is_ignored(relative: string): Promise<boolean> {
 		try {
@@ -95,35 +34,40 @@ function prettier_ignored(root: string): PrettierIgnored {
 	}
 }
 
-const SCOPES: ReadonlyMap<string, InputTest> = new Map([
-	[gate_plan.LINT_LABEL, is_lint_input],
-	[gate_plan.TYPE_CHECK_LABEL, is_source_input],
-	[gate_plan.EXPORTS_LABEL, is_source_input],
-])
+async function reads_any(
+	declaration: InputDeclaration,
+	paths: ReadonlyArray<string>,
+	is_ignored: PrettierIgnored,
+	root: string,
+): Promise<boolean> {
+	if (declaration.reads === 'recorded') return await test_related.reaches_tests(root, paths)
+
+	const { is_input } = declaration
 
-function is_scoped(label: string): boolean {
-	return SCOPES.has(label)
+	if (is_input === undefined) return true
+
+	const answers = await Promise.all(
+		paths.map(async (relative) => await is_input(relative, is_ignored)),
+	)
+
+	return answers.includes(true)
 }
 
-// Whether any of `paths` (repository-root relative) is an input of the check `label`. An unscoped
+// Whether any of `paths` (repository-root relative) is an input of the check `label`. An undeclared
 // check answers `true` for every set of paths, so the only way to reuse it is never.
 async function touches_inputs(
 	label: string,
 	paths: ReadonlyArray<string>,
 	is_ignored: PrettierIgnored,
+	root: string = PROJECT_ROOT,
 ): Promise<boolean> {
-	const scope = SCOPES.get(label)
+	const declaration = verification_inputs.declaration_of(label)
 
-	if (scope === undefined || paths.some((relative) => is_config(relative))) return true
+	if (declaration === undefined || verification_inputs.configures(label, paths)) return true
 
-	const answers = await Promise.all(
-		paths.map(async (relative) => await scope(relative, is_ignored)),
-	)
-
-	return answers.includes(true)
+	return await reads_any(declaration, paths, is_ignored, root)
 }
 
-const check_inputs = { is_scoped, prettier_ignored, touches_inputs }
+const check_inputs = { prettier_ignored, touches_inputs }
 
-export type { PrettierIgnored }
 export { check_inputs }