@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/gate/machine-capacity.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { availableParallelism, cpus, totalmem } from 'node:os'
+import { availableParallelism, cpus, loadavg, totalmem } from 'node:os'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
@@ -32,12 +32,12 @@ import { execa } from 'execa'
 // The window the busy cores are measured over: long enough that one scheduler tick does not dominate it,
 // short enough that a solo admission is not visibly delayed.
 const SAMPLE_WINDOW_MS = 250
-// **The background a developer machine always carries, which the gate's weights were measured beside.**
-// On 2026-10-07 the 11-core machine idled at about 1.5 cores outside `josh` — Claude sessions 0.55, the
-// window server 0.47, a browser 0.5. The solo gate's weights sum to exactly the core count and were
-// measured with that load present, so only what exceeds it is load the budget must give way to;
-// counting the baseline would defer a solo gate's unit suite on every run.
-const BASELINE_CORES = 2
+// **Run-queue load outside the ledger past this many times the cores holds the first waiter too**
+// (joshuafolkken/kit#4361). The first waiter ignores outside load (joshuafolkken/kit#4313), and lanes took
+// the 11-core machine to a load average of 25–34. Twice the cores is loose on purpose: the one-core
+// editor load #4313 stopped holding a solo gate stays far below it, so neither its starvation nor the
+// lanes' speed comes back, while a machine whose queue beyond the ledger passes two per core waits.
+const OVERLOAD_FACTOR = 2
 const BYTES_PER_MB = 1_048_576
 const KB_PER_MB = 1024
 const PERCENT = 100
@@ -62,7 +62,10 @@ const PAGE_SIZE_NAME = 'hw.pagesize'
 // The kernel's memory-pressure verdict — 1 normal, 2 warning, 4 critical — the one Activity Monitor
 // colors its "memory pressure" graph by.
 const PRESSURE_NAME = 'kern.memorystatus_vm_pressure_level'
-const PRESSURE_WARNING = 2
+// **Only critical holds; warning is sticky** (joshuafolkken/kit#4199). On macOS the verdict can stay at
+// warning for hours after the pressure passed, so a hold on warning never lifts. What is pressured right
+// now shows in the free figure and the swap and compressor traffic; the verdict adds only critical.
+const PRESSURE_HOLD = 4
 // The swap traffic across one window that reads as pressure — 64 MB a second paged to disk. A machine
 // that swapped once still pages a few megabytes back in as old pages are touched.
 const SWAP_PRESSURE_MB = 16
@@ -81,10 +84,13 @@ const SYSCTL_ARGUMENTS = [
 const SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu
 
 // `memory_pressured` says why `available_mb` read none, so a claim that waits can name the pressure.
+// `run_queue` is the one-minute load average: the busy cores stop at the core count, so only the queue
+// tells a machine at twice its cores from one at once (`is_overloaded`).
 interface MachineReading {
 	busy_cores: number | undefined
 	available_mb: number | undefined
 	memory_pressured?: boolean | undefined
+	run_queue?: number | undefined
 }
 
 // The memory half of a reading. `swapped_mb` is a counter — every page swapped in or out since boot —
@@ -103,10 +109,15 @@ interface LedgerLoad {
 	memory_mb: number
 }
 
+// `busy_excess` is the measured cores beyond what the ledger declares — what `cores` gave up to load the
+// ledger does not hold, so a claim that waits on it can name the CPU as saturated. `is_overloaded` lifts
+// the first waiter's exemption from that load (`core_admission.is_admitted`).
 interface MachineBudget {
 	cores: number
 	memory_mb: number
 	memory_pressured?: boolean | undefined
+	busy_excess?: number | undefined
+	is_overloaded?: boolean | undefined
 }
 
 interface CpuTimes {
@@ -287,22 +298,23 @@ function moved_over(from: number | undefined, to: number | undefined, limit: num
 
 function is_pressured(before: MemoryReading, after: MemoryReading): boolean {
 	return (
-		(after.pressure_level ?? 0) >= PRESSURE_WARNING ||
+		(after.pressure_level ?? 0) >= PRESSURE_HOLD ||
 		moved_over(before.swapped_mb, after.swapped_mb, SWAP_PRESSURE_MB) ||
 		moved_over(before.compressed_mb, after.compressed_mb, COMPRESSION_PRESSURE_MB)
 	)
 }
 
-// **Memory under compression and swap pressure has nothing free to admit against.** The level counts
-// compressible pages as available, so on 2026-10-16 it read 5.4 GB free while the compressor held
-// 5.9 GB and compressed and decompressed about 3.3 GB every three seconds, and 5.2 GB of reservations
-// were admitted on top. A reading the kernel calls pressured, or one with swap or compressor traffic
-// across the window, answers no free memory: what the ledger holds keeps running and a heavy claim waits
-// for the pressure to pass.
-function pressured_available(before: MemoryReading, after: MemoryReading): number | undefined {
+// **Only a reading the kernel calls critical has nothing free to admit against.** Swap and compressor
+// traffic across the window used to answer no free memory too (joshuafolkken/kit#3943), but this machine
+// swaps out 0.4–1.3 TB a day as a matter of course, so that traffic held about a third of every wait
+// with memory to spare (joshuafolkken/kit#4313). A claim now waits on memory only when the free figure
+// falls short of what it declares; the traffic still names the wait as pressure (`memory_pressured`),
+// and holds a claim past the shortfall that running alone or the wait cap would otherwise start
+// (`core_admission.is_swap_held`, joshuafolkken/kit#4451).
+function pressured_available(after: MemoryReading): number | undefined {
 	if (after.available_mb === undefined) return undefined
 
-	return is_pressured(before, after) ? 0 : after.available_mb
+	return (after.pressure_level ?? 0) >= PRESSURE_HOLD ? 0 : after.available_mb
 }
 
 // Memory is read at both ends of the window, so the swap counter's difference is the activity during it.
@@ -312,13 +324,13 @@ async function read_machine(
 	const before = cpu_times()
 	const [memory_before] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)])
 	const memory_after = await read_memory()
-	const busy_cores = is_unquoted()
-		? busy_cores_between(before, cpu_times(), cpus().length)
-		: undefined
+	const is_host = is_unquoted()
+	const busy_cores = is_host ? busy_cores_between(before, cpu_times(), cpus().length) : undefined
 
 	return {
 		busy_cores,
-		available_mb: pressured_available(memory_before, memory_after),
+		run_queue: is_host ? loadavg()[0] : undefined,
+		available_mb: pressured_available(memory_after),
 		memory_pressured: is_pressured(memory_before, memory_after),
 	}
 }
@@ -327,31 +339,52 @@ async function read_sample(): Promise<MachineSample> {
 	return { cpu: cpu_times(), memory: await read_memory(), total_mb: totalmem() / BYTES_PER_MB }
 }
 
-// The busy cores the ledger does not account for, beyond the baseline the weights were measured beside,
-// in whole cores — the budget is in whole cores, and a fraction of a core is not a core to give up.
+// The busy cores the ledger does not account for, in whole cores — the budget is in whole cores, and a
+// fraction of a core is not a core to give up.
+//
+// **Every busy core counts, the background included** (joshuafolkken/kit#4238). A baseline of two cores
+// used to be exempt, so with 10 cores reserved and all 11 busy the reading saw no excess and admitted
+// another claim onto a saturated CPU.
 function external_cores(busy_cores: number | undefined, ledger_cores: number): number {
 	if (busy_cores === undefined) return 0
 
-	return Math.floor(Math.max(0, busy_cores - ledger_cores - BASELINE_CORES))
+	return Math.floor(Math.max(0, busy_cores - ledger_cores))
 }
 
-// **The budget the ledger admits against: what is free plus what the ledger itself already holds.**
-// The admitted reservations' load is inside the reading, and the admission walk counts their declared
-// weight again, so it is added back — what is subtracted is only the load from outside the ledger. The
-// caller passes every admitted claim's cores but only the memory of claims past
-// `core_admission.RAMP_UP_MS`, whose tools have had time to allocate.
+// The run queue beyond what the ledger declares, past `OVERLOAD_FACTOR` times the cores. The ledger's own
+// claims running past their weight count as outside load. The load average trails by a minute, so a
+// first waiter held here waits out the decay — only at a load already this far past the machine. A queue
+// that could not be read, and Windows' constant zero, never hold.
+function is_overloaded(
+	run_queue: number | undefined,
+	ledger_cores: number,
+	cores: number,
+): boolean {
+	if (run_queue === undefined) return false
+
+	return run_queue - ledger_cores > cores * OVERLOAD_FACTOR
+}
+
+// **The budget the ledger admits against: `cores − max(ledger, busy)` free, plus what the ledger itself
+// already holds.** The admission walk counts the ledger's declared weight again, so it is added back —
+// what is subtracted is only the busy load beyond it. A claim admitted moments ago is not busy yet, and
+// the ledger's declared cores cover it. The caller passes every admitted claim's cores but only the
+// memory of claims past `core_admission.RAMP_UP_MS`, whose tools have had time to allocate.
 // Memory that could not be read is no limit at all, the behavior before memory was read.
 function machine_budget(cores: number, reading: MachineReading, ledger: LedgerLoad): MachineBudget {
+	const busy_excess = external_cores(reading.busy_cores, ledger.cores)
+
 	return {
-		cores: cores - external_cores(reading.busy_cores, ledger.cores),
+		cores: Math.max(0, cores - busy_excess),
 		memory_mb:
 			reading.available_mb === undefined ? Infinity : reading.available_mb + ledger.memory_mb,
 		memory_pressured: reading.memory_pressured,
+		busy_excess,
+		is_overloaded: is_overloaded(reading.run_queue, ledger.cores, cores),
 	}
 }
 
 const machine_capacity = {
-	BASELINE_CORES,
 	busy_cores_between,
 	busy_share_between,
 	COMPRESSION_PRESSURE_MB,
@@ -360,6 +393,7 @@ const machine_capacity = {
 	parse_darwin_memory,
 	parse_linux_available,
 	parse_linux_swapped,
+	PRESSURE_HOLD,
 	pressured_available,
 	read_machine,
 	read_memory,

package/scripts/gate/metrics-totals.ts

@@ -0,0 +1,59 @@
+import { buffered_process } from '#scripts/lib/buffered-process'
+import { release_approval_prune } from '#scripts/release/release-approval-prune'
+import { project_checks } from './project-checks'
+
+// kit's metrics ratchet totals (`josh metrics --totals-only`), brought forward from the detached
+// `josh ship`'s pre-detach checks to the implementation loop: a feature grows a total almost every
+// time, and a growth first met at the pre-detach stop costs a ship re-run beside the
+// `josh metrics --accept` (joshuafolkken/kit#4594). `josh lint:related` reports it as a notice, never a
+// failure, so a total that grows again within the loop does not demand an accept per edit; the
+// pre-detach check stays the stop. A consumer's kit has no `josh metrics`, so it runs in kit alone.
+
+const METRICS_TOTALS_COMMAND: ReadonlyArray<string> = ['josh', 'metrics', '--totals-only']
+// The form ship runs before the detach and before each scoped pair: it also re-records a growth the
+// branch's approval names (joshuafolkken/kit#4716).
+const METRICS_RERECORD_COMMAND: ReadonlyArray<string> = [...METRICS_TOTALS_COMMAND, '--rerecord']
+// Neutral on the cause: a growth and a run that never finished both stop the pre-detach check.
+const NOTICE_HEADING =
+	'⚠ josh metrics --totals-only did not pass — settle it before `josh ship`, or the pre-detach check stops the ship (a total the branch approval names is re-recorded there):'
+
+async function growth_notice(directory: string): Promise<string | undefined> {
+	if (!project_checks.is_kit_repository(directory)) return undefined
+
+	const result = await buffered_process.run_buffered_process(METRICS_TOTALS_COMMAND, {
+		cwd: directory,
+	})
+
+	if (!buffered_process.is_process_failed(result)) return undefined
+
+	return `${NOTICE_HEADING}\n${result.output.trim()}`
+}
+
+function carries_approval(files: Readonly<Record<string, string>>): boolean {
+	return Object.keys(files).some((file) => release_approval_prune.is_approval(file))
+}
+
+// Re-records the branch's approval before a scoped pair reads the tree, so a review fix that grows a
+// named total again does not stop the gate after it (joshuafolkken/kit#4716). It runs only where the
+// changed tree carries an approval, and answers whether it ran; its verdict is left to the gate's own
+// metrics step.
+async function rerecord(
+	directory: string,
+	files: Readonly<Record<string, string>>,
+): Promise<boolean> {
+	if (!project_checks.is_kit_repository(directory) || !carries_approval(files)) return false
+
+	await buffered_process.run_buffered_process(METRICS_RERECORD_COMMAND, { cwd: directory })
+
+	return true
+}
+
+const metrics_totals = {
+	METRICS_RERECORD_COMMAND,
+	METRICS_TOTALS_COMMAND,
+	NOTICE_HEADING,
+	growth_notice,
+	rerecord,
+}
+
+export { metrics_totals }

package/scripts/gate/moved-paths.ts

@@ -0,0 +1,67 @@
+import { git_spawn } from '#scripts/git/git-spawn'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import type { GateTree } from './gate-tree'
+
+// Every path whose content can differ from the tree a green record was taken on — the one reading the
+// gate's per-check reuse (`check-reuse.ts`) and the scoped checks' since-green narrowing
+// (`since-green.ts`) both act on, so the two can never disagree about what moved.
+//
+// **What moved is the union of two diffs**. The changed-file map is a diff against the merge base, so a
+// path absent from both maps holds the merge base's content — and the base's own diff
+// (`git diff <recorded> <current>`) names every path that content moved for, which is what a main sync
+// brought in. A path in either map whose digest differs is the other half
+// (`file_map_stamp.changed_since`).
+
+const NAME_SEPARATOR = '\0'
+const BASE_DIFF = ['diff', '--name-only', '--no-renames', '-z'] as const
+
+async function base_diff(from: string, to: string): Promise<ReadonlyArray<string> | undefined> {
+	if (from === to) return []
+
+	try {
+		const names = await git_spawn.read([...BASE_DIFF, from, to])
+
+		return names.split(NAME_SEPARATOR).filter((name) => name !== '')
+	} catch {
+		return undefined
+	}
+}
+
+// The two diffs apart: `synced` is what a main sync brought in, `changed` the paths whose digest moved.
+// A path can be in both.
+interface MovedParts {
+	changed: ReadonlyArray<string>
+	synced: ReadonlyArray<string>
+}
+
+// `undefined` when the record cannot be compared: no base on either side, or a tree map that came back
+// empty — also what `gate-tree.ts` answers when git could not be read, so it describes no tree.
+async function moved_parts(stamp: FileMapStamp, tree: GateTree): Promise<MovedParts | undefined> {
+	const is_unread = Object.keys(tree.files).length === 0
+
+	if (is_unread || stamp.base === undefined || tree.base === undefined) return undefined
+
+	const synced = await base_diff(stamp.base, tree.base)
+
+	if (synced === undefined) return undefined
+
+	return { changed: file_map_stamp.changed_since(stamp, tree.files), synced }
+}
+
+function union_of(parts: MovedParts): ReadonlyArray<string> {
+	return [...new Set([...parts.changed, ...parts.synced])]
+}
+
+async function moved_since(
+	stamp: FileMapStamp,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await moved_parts(stamp, tree)
+
+	return parts === undefined ? undefined : union_of(parts)
+}
+
+const moved_paths = { moved_parts, moved_since, union_of }
+
+export type { MovedParts }
+export { moved_paths }

package/scripts/gate/project-checks.ts

@@ -1,4 +1,4 @@
-import { existsSync, globSync, readFileSync } from 'node:fs'
+import { existsSync, globSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
@@ -6,10 +6,10 @@ import { own_formatter } from '#scripts/init/own-formatter'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { NOT_USED_MARKER, SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
 
-const PACKAGE_JSON = 'package.json'
 const IGNORED_DIRS = new Set([
 	'node_modules',
 	'.git',
@@ -48,7 +48,7 @@ const object_schema = z.record(z.string(), z.unknown())
 function project_root(directory: string): string {
 	return (
 		ancestor_directories.nearest(directory, (candidate) =>
-			existsSync(path.join(candidate, PACKAGE_JSON)),
+			existsSync(package_manifest.manifest_path(candidate)),
 		) ?? directory
 	)
 }
@@ -86,16 +86,9 @@ function is_basic_manifest(manifest: unknown): boolean {
 	return project_profile.parse_profile(josh['profile']) === 'basic'
 }
 
-// The try covers the read alone — a missing or unreadable manifest — since the parse already answers
-// `undefined` for text that is not JSON.
+// A missing, unreadable or non-JSON manifest answers `undefined`; the shape is each caller's question.
 function read_manifest(directory: string): unknown {
-	try {
-		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
-
-		return json_value.parse_or_undefined(readFileSync(manifest_path, 'utf8'))
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(project_root(directory), z.unknown())
 }
 
 function is_basic(directory: string): boolean {

package/scripts/gate/scoped-green.ts

@@ -1,6 +1,6 @@
 import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
 import { hook_decision } from '#scripts/josh/hook-decision'
-import { review_brief } from '#scripts/review/review-brief'
+import { run_record_path } from '#scripts/josh/run-record-path'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_tree, type GateTree } from './gate-tree'
@@ -12,16 +12,20 @@ import { gate_tree, type GateTree } from './gate-tree'
 // tree neither check has read return their findings one round trip at a time; one call running both
 // checks first returns most of them at once.
 //
-// **It fixes when the checks run, never whether they run, and never what they check.** Nothing here
-// skips a check, narrows one, or reinterprets its output — a green record buys ordering and nothing
-// else, and `josh gate` still runs its four checks exactly as before. It never *reuses* a scoped
-// check's result in place of re-running it.
+// **It fixes when the checks run, and only one writer decides whether.** Nothing here skips a check or
+// reinterprets its output, and `josh gate` still runs its four checks exactly as before. The one other
+// reader is the checks' own re-run, which narrows to what moved since this record (`since-green.ts`).
+// The one writer without a run behind it is `josh ship`'s scoped pair after a merge with the default
+// branch that shares nothing with the branch (`run-ship-synced-scope.ts`, joshuafolkken/kit#4985).
 //
 // **The judgement is the gate's own, not a second one.** "There is a record and nothing it covers has
-// moved" is `review_brief.matching_stamp` plus the base equality `gate_skip.reusable_green_gate`
-// already compares, over the same `FileMapStamp` shape written to the same kind of file. A second
-// definition of "this tree is unchanged" is the clone `CLAUDE.md` prohibits, and it is exactly where
-// two commands would start disagreeing about one working tree.
+// moved" is `file_map_stamp.changed_since` plus the base equality `gate_skip.reusable_green_gate`
+// already compares and the inputs fingerprint each record carries (`verification-inputs.ts`), over the
+// same `FileMapStamp` shape written to the same kind of file. A second definition of "this tree is
+// unchanged" is the clone `CLAUDE.md` prohibits, and it is exactly where two commands would start
+// disagreeing about one working tree. The one deliberate difference: this reader ignores josh's own
+// `.josh/` run records, while the gate's own reuse (`gate_skip` via `review_brief.matching_stamp`)
+// does not — safe, because the gate still lints and tests those records.
 //
 // **It refuses `josh review:brief`, and now the local `josh gate` too, but never CI's**.
 // The brief was the first refusal point because it is where `review:attest`
@@ -56,11 +60,13 @@ interface ScopedCheck {
 // The record paths, overridable so a test can plant one without overwriting the record a real run in
 // this checkout relies on — the same reason `gate_skip.reusable_green_gate` takes a `source`.
 // `is_unit_skipped` is overridable for the same reason, so a suite running in a checkout with vitest
-// can stand in for a project without one.
+// can stand in for a project without one. `is_lane_child` is the gate's answer for a dispatched lane
+// child, absent for every other caller.
 interface ScopedSources {
 	lint?: string
 	test?: string
 	is_unit_skipped?: boolean
+	is_lane_child?: boolean
 }
 
 // **`test:related` is required only where it can ever answer**. In a project
@@ -88,14 +94,29 @@ function checks_of(sources: ScopedSources): ReadonlyArray<ScopedCheck> {
 		: [lint, test]
 }
 
+// **A record josh itself keeps under `.josh/` does not unseat a green record** (joshuafolkken/kit#4905):
+// `metrics --accept` and the ship's own approval re-record write there after the pair passed, and the
+// preflight re-ran both checks over nothing but that bookkeeping. The gate still lints and tests the
+// whole change, and a later scoped run reads such a file as moved since its record.
+
 // **An unreadable record reads as an absent one, and that is the safe direction.** `read` swallows a
 // malformed or foreign file and answers `undefined`, so the two cases are indistinguishable here —
 // and the consequence of treating one as the other is a single 14-second scoped run, against the
 // alternative of briefing a review on a tree nothing has checked.
-function describes_tree(check: ScopedCheck, tree: Record<string, string>, base: string): boolean {
-	const stamp = review_brief.matching_stamp(check.stamp.read(check.source), tree)
+function describes_tree(
+	check: ScopedCheck,
+	tree: Record<string, string>,
+	base: string,
+	is_overlooked: (relative: string) => boolean = run_record_path.is_run_record,
+): boolean {
+	const stamp = check.stamp.read(check.source)
 
-	return stamp !== undefined && file_map_stamp.describes_base(stamp, base)
+	return (
+		stamp !== undefined &&
+		file_map_stamp.changed_since(stamp, tree).every((relative) => is_overlooked(relative)) &&
+		file_map_stamp.describes_base(stamp, base) &&
+		check.stamp.describes_inputs(stamp)
+	)
 }
 
 // **Whether there is a tree to speak about at all**, asked once and used from both ends: the reader
@@ -147,25 +168,60 @@ function missing_scripts(
 	return stale_checks(tree, base, sources).map((check) => check.script)
 }
 
+// The scripts whose green record still describes this tree, which `check:related` need not run again
+// (joshuafolkken/kit#5156). A tree with no answer reuses nothing, never reading silence as green. A
+// moved `.josh/` record counts here: the gate is not behind `check:related` to lint and test it.
+function overlooks_nothing(): boolean {
+	return false
+}
+
+function green_scripts(
+	tree: Record<string, string>,
+	base: string | undefined,
+	sources: ScopedSources = {},
+): ReadonlyArray<string> {
+	if (!is_answerable(tree, base)) return []
+
+	return checks_of(sources)
+		.filter((check) => describes_tree(check, tree, base, overlooks_nothing))
+		.map((check) => check.script)
+}
+
 const REFUSAL_HEADLINE = '⛔ scoped checks not green on this tree'
 
 // **The way out travels with the refusal.** A message saying only "not verified" leaves the caller
 // holding the same question and no sanctioned answer, which is how the checks ended up after the
 // review in the first place. So the text names the one command that closes it, what it costs, and
-// that reissuing this call is the expected next move.
-function refusal(missing: ReadonlyArray<string>): string {
+// the expected next move: reissuing this call, or for a lane child's gate, handing over to ship.
+const REISSUE_STEP = 'and reissue this command.'
+
+// joshuafolkken/kit#4776: a lane child that reissued the gate here ran it in the foreground for three
+// minutes before `ship`, which runs its own gate beside the review, so that green was never used.
+const LANE_CHILD_STEP =
+	'then hand over to `pnpm josh ship --detach --review "<title> #<N>"` rather than reissuing the ' +
+	'gate — this is a dispatched lane child, and ship runs the gate beside the review ' +
+	'(`.claude/skills/workflow-commands/chain-rule.md` step 0).'
+
+function refusal(missing: ReadonlyArray<string>, next_step: string): string {
 	return (
 		`${REFUSAL_HEADLINE}: ${missing.join(' and ')} ` +
 		'have not passed on the files this branch changed. The gate and review round 1 start together, ' +
 		'so a brief composed now describes a tree neither check has read — joshuafolkken/kit#1503 spent ' +
 		'282 seconds, 31% of the run, picking up one lint rule and one failing test at a time after its ' +
 		'review had already started. Run them in one call — ' +
-		`\`${LINT_COMMAND} && ${TEST_COMMAND}\`, measured at 13.8 seconds — and reissue this command. ` +
-		'The record fixes when the checks run and never whether they run: nothing is skipped, narrowed ' +
-		'or reused because of it. `prompts/review.md` → "The scoped checks answer on the last edit".'
+		`\`${LINT_COMMAND} && ${TEST_COMMAND}\`, measured at 13.8 seconds — ${next_step} ` +
+		'The record fixes when the checks run: only a merge with the default branch sharing nothing ' +
+		"with this branch's change is recorded without a run. " +
+		'`.claude/skills/workflow-commands/chain-rule.md` → "Orchestration facts single-sourced here".'
 	)
 }
 
+// **Only the gate's pre-check sets `is_lane_child`**: a lane child refused at `josh run:review` reissues
+// it as chain-rule step 0 says, so `review:brief`'s callers keep the reissue wording.
+function next_step_of(sources: ScopedSources): string {
+	return sources.is_lane_child === true ? LANE_CHILD_STEP : REISSUE_STEP
+}
+
 function refusal_for(
 	tree: Record<string, string>,
 	base: string | undefined,
@@ -173,7 +229,7 @@ function refusal_for(
 ): string | undefined {
 	const missing = missing_checks(tree, base, sources)
 
-	return missing.length === 0 ? undefined : refusal(missing)
+	return missing.length === 0 ? undefined : refusal(missing, next_step_of(sources))
 }
 
 // **A record is written only by a bare invocation, and any argument at all withholds it.** A path
@@ -250,6 +306,7 @@ const scoped_green = {
 	SWITCH_ENV_KEY,
 	TEST_COMMAND,
 	TEST_SCRIPT,
+	green_scripts,
 	is_recordable_scope,
 	is_unmoved,
 	missing_checks,

package/scripts/gate/since-green.ts

@@ -0,0 +1,70 @@
+import type { FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+import { gate_tree, type GateTree } from './gate-tree'
+import { moved_paths, type MovedParts } from './moved-paths'
+import { verification_inputs } from './verification-inputs'
+
+// **A scoped check re-run reads only what moved since its last green run on this checkout**
+// (joshuafolkken/kit#4393). A lane's ship retry — after a review fix or a preflight stop — re-ran
+// `josh lint:related` and `josh test:related` (the gate's unit step too) over the whole branch diff,
+// though everything outside the fix had been green on the tree before it.
+//
+// **The check is no weaker.** The green record (`scoped-green.ts`) vouches that the check passed over
+// the branch diff of the tree it names; what moved since is every path whose content can differ from
+// that tree (`moved-paths.ts`), a main sync's own changes included. A record written by a narrowed run
+// vouches for the same thing, by the same argument one run earlier — except a bare `josh test:related`
+// over a file every test imports, which ran only its direct importers, so the gate's unit leg never
+// narrows by it while the branch changes one (`is_green_narrowable` in `test-related.ts`, #5122).
+//
+// **Whatever cannot be narrowed answers `undefined`**, and the caller reads the whole branch change as
+// before: no record, one that cannot be compared, one written under other tools or environment, or a
+// moved file the check's declaration names a configuration — a file green under the old configuration
+// says nothing under the new one. An empty list is
+// the positive fact that nothing moved: the gate's unit step on the tree the preflight just passed.
+
+// Why a command that found nothing moved ran nothing, in the words both scoped commands print.
+const UNMOVED_REASON = 'nothing moved since its last green run on this checkout'
+
+// The narrowing line each command prints before it runs, so a since-green run is never read as one
+// over the whole branch.
+function describe(label: string, moved: ReadonlyArray<string>): string {
+	return `${label}: reading only the ${String(moved.length)} file(s) changed since its last green run on this checkout.`
+}
+
+function is_narrowable(label: string, parts: MovedParts | undefined): parts is MovedParts {
+	return parts !== undefined && !verification_inputs.configures(label, moved_paths.union_of(parts))
+}
+
+// What moved with a main sync's part kept apart, for a caller that records how much of its input the
+// sync brought in (`josh test:related`, joshuafolkken/kit#4465). `label` names the gate check whose
+// declaration (`verification-inputs.ts`) the record vouches for. `tree` is the caller's own reading of
+// the gate tree, so a run that also records its green tree reads it once (joshuafolkken/kit#4655).
+async function read_moved_parts(
+	stamp: FileMapStampAccess,
+	label: string,
+	source?: string,
+	tree?: GateTree,
+): Promise<MovedParts | undefined> {
+	const record = stamp.read(source)
+
+	if (record === undefined || !stamp.describes_inputs(record)) return undefined
+
+	const parts = await moved_paths.moved_parts(record, tree ?? (await gate_tree.read_gate_tree()))
+
+	return is_narrowable(label, parts) ? parts : undefined
+}
+
+// Repository-root-relative paths, or `undefined` when the caller has to read the whole branch change.
+async function read_moved(
+	stamp: FileMapStampAccess,
+	label: string,
+	source?: string,
+	tree?: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await read_moved_parts(stamp, label, source, tree)
+
+	return parts === undefined ? undefined : moved_paths.union_of(parts)
+}
+
+const since_green = { UNMOVED_REASON, describe, read_moved, read_moved_parts }
+
+export { since_green }