@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/gate/gate-static-group.ts

@@ -0,0 +1,60 @@
+import { gate_labels } from './gate-labels'
+import type { GateCheck } from './gate-plan'
+
+// **CI runs the static set as three parallel legs, and each leg is still `josh gate`**
+// (joshuafolkken/kit#5215). One runner ran all seven checks for about four minutes while every unit
+// shard was done in two, so `static-checks` was the merge's critical path. The legs are a matrix over
+// the names below, each running `pnpm josh gate --no-unit --static-group=<name>`, so CI keeps the
+// gate's one definition of every check and its all-failures-in-one-pass summary rather than restating
+// the commands per job. `gate-static-group.test.ts` pins the partition: every static check is in
+// exactly one group, and the workflow's matrix names exactly these groups.
+//
+// The split follows the weights: lint alone (the cold-cache outlier), the type check with the
+// unused-export walk (both build a TypeScript program), and the light rest together.
+const STATIC_GROUP_FLAG_PREFIX = '--static-group='
+
+const STATIC_GROUPS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	lint: [gate_labels.LINT_LABEL],
+	types: [gate_labels.TYPE_CHECK_LABEL, gate_labels.EXPORTS_LABEL],
+	rest: [
+		gate_labels.SPELL_CHECK_LABEL,
+		gate_labels.BEHAVIOR_LABEL,
+		gate_labels.METRICS_LABEL,
+		gate_labels.LOCKFILE_LABEL,
+	],
+}
+
+// The group an argument names, or `undefined` when it is not the flag or names no group — so an
+// unknown group is refused with every other unknown argument.
+function group_of(argument: string): string | undefined {
+	if (!argument.startsWith(STATIC_GROUP_FLAG_PREFIX)) return undefined
+
+	const name = argument.slice(STATIC_GROUP_FLAG_PREFIX.length)
+
+	return Object.hasOwn(STATIC_GROUPS, name) ? name : undefined
+}
+
+function find_group(arguments_: ReadonlyArray<string>): string | undefined {
+	return arguments_.map((argument) => group_of(argument)).find((name) => name !== undefined)
+}
+
+function narrow_checks(
+	checks: ReadonlyArray<GateCheck>,
+	group: string | undefined,
+): ReadonlyArray<GateCheck> {
+	if (group === undefined) return checks
+
+	const labels = STATIC_GROUPS[group] ?? []
+
+	return checks.filter((check) => labels.includes(check.label))
+}
+
+const gate_static_group = {
+	STATIC_GROUPS,
+	STATIC_GROUP_FLAG_PREFIX,
+	find_group,
+	group_of,
+	narrow_checks,
+}
+
+export { gate_static_group }

package/scripts/gate/gate-steps.ts

@@ -1,10 +1,11 @@
+import { gate_labels } from './gate-labels'
 import { gate_plan, type GateCheck, type GatePlan } from './gate-plan'
 import type { GateStep } from './gate-report'
 import { project_checks } from './project-checks'
 import { type_check_step } from './type-check-step'
 
 const JOSH = 'josh'
-const { TYPE_CHECK_LABEL, UNIT_LABEL } = gate_plan
+const { TYPE_CHECK_LABEL, UNIT_LABEL } = gate_labels
 const UNIT_WORKER_FLAG = '--maxWorkers'
 
 function unit_worker_args(check: GateCheck, plan: GatePlan): ReadonlyArray<string> {

package/scripts/gate/gate-tree.ts

@@ -30,9 +30,11 @@ async function read_changed_files(): Promise<Record<string, string>> {
 }
 
 // The resolver lives in `git/change-base.ts`, because the review brief
-// needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits.
+// needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits. It is read
+// through a merge in progress, as the file map is (joshuafolkken/kit#5307): a map measured from the
+// later base beside `HEAD`'s older one would let a re-merged default branch reuse a stale record.
 async function read_base(): Promise<string | undefined> {
-	return await change_base.resolved()
+	return await change_base.resolved_through_merge()
 }
 
 // The two readings are independent, so they are started together rather than one after the other.

package/scripts/gate/hook-gate-reuse.ts

@@ -103,6 +103,12 @@ interface HookReuse {
 	source?: string | undefined
 }
 
+const ARGUMENTS_MISS = 'arguments were passed to the hook'
+
+function force_miss(force_environment: string): string {
+	return `${force_environment} is set`
+}
+
 // The stamp rather than a boolean, for the same reason `gate_skip.gate_reuse` hands one back: the
 // caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
 // printing. A refusal carries its reason instead.
@@ -111,19 +117,30 @@ interface HookReuse {
 // asked for that run rather than for a recorded result about a whole tree, and a hook's own line passes
 // none, so this costs it nothing.
 function hook_reuse(input: HookReuse): GateReuse {
-	if (input.extra_arguments.length > 0) return { miss: 'arguments were passed to the hook' }
-	if (is_force_requested(input.force_env)) return { miss: `${input.force_env} is set` }
+	if (input.extra_arguments.length > 0) return { miss: ARGUMENTS_MISS }
+	if (is_force_requested(input.force_env)) return { miss: force_miss(input.force_env) }
 	if (!input.is_tree_carried) return { miss: input.carry_miss }
 
 	return gate_skip.gate_reuse(input.tree.files, input.tree.base, input.source)
 }
 
+// joshuafolkken/kit#5234: the kind of a refusal `hook_reuse` answered, the hook's own three refusals
+// told apart before the gate's, so a ledger counts each without a second wording of the sentences.
+function miss_kind(miss: string, input: Pick<HookReuse, 'carry_miss' | 'force_env'>): string {
+	if (miss === ARGUMENTS_MISS) return 'arguments'
+	if (miss === force_miss(input.force_env)) return 'forced'
+	if (miss === input.carry_miss) return 'tree-not-carried'
+
+	return gate_skip.miss_kind(miss)
+}
+
 const hook_gate_reuse = {
 	GATE_REUSING_TARGETS,
 	hook_reuse,
 	is_force_requested,
 	is_index_matching_worktree,
 	is_worktree_clean,
+	miss_kind,
 	read_status_lines,
 }
 

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/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.** Nothing here skips a check or
+// **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`
+// 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.
+// 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,15 +94,26 @@ 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.changed_since(stamp, tree).every((relative) => is_overlooked(relative)) &&
 		file_map_stamp.describes_base(stamp, base) &&
 		check.stamp.describes_inputs(stamp)
 	)
@@ -151,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 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,
@@ -177,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
@@ -254,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

@@ -1,5 +1,5 @@
 import type { FileMapStampAccess } from '#scripts/josh/file-map-stamp'
-import { gate_tree } from './gate-tree'
+import { gate_tree, type GateTree } from './gate-tree'
 import { moved_paths, type MovedParts } from './moved-paths'
 import { verification_inputs } from './verification-inputs'
 
@@ -11,7 +11,9 @@ import { verification_inputs } from './verification-inputs'
 // **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.
+// 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
@@ -19,6 +21,9 @@ import { verification_inputs } from './verification-inputs'
 // 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 {
@@ -31,17 +36,19 @@ function is_narrowable(label: string, parts: MovedParts | undefined): parts is M
 
 // 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.
+// 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, await gate_tree.read_gate_tree())
+	const parts = await moved_paths.moved_parts(record, tree ?? (await gate_tree.read_gate_tree()))
 
 	return is_narrowable(label, parts) ? parts : undefined
 }
@@ -51,12 +58,13 @@ 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)
+	const parts = await read_moved_parts(stamp, label, source, tree)
 
 	return parts === undefined ? undefined : moved_paths.union_of(parts)
 }
 
-const since_green = { describe, read_moved, read_moved_parts }
+const since_green = { UNMOVED_REASON, describe, read_moved, read_moved_parts }
 
 export { since_green }

package/scripts/gate/structural-checks.ts

@@ -0,0 +1,96 @@
+import { project_checks } from '#scripts/gate/project-checks'
+import type { ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+
+// The guard tests that judge source text alone, yet run only in `josh test:related` or a detached
+// ship's pre-detach stop: a bare Issue citation, a source with no colocated test and a `gh` spawn
+// outside `gh api` (the static half of the network guard; the calls a test *makes* are observed by
+// `test-network-guard.ts`, which only a run can answer). `josh lint:related` runs them beside its
+// lint, so a between-edits loop meets them in seconds rather than at the ship (joshuafolkken/kit#4643).
+// The targets are the pre-detach stop's too, so the two never drift.
+//
+// `josh exports:unused` stays out: its whole-program type-checker pass is several times the lint's
+// own wall clock. `josh lint:related` runs its narrowed members check after a green lint instead
+// (joshuafolkken/kit#4645).
+//
+// They run in kit alone: the guard tests are kit's own, and a consumer meets the pre-detach static
+// checks there. A change with no `.ts` file in it moves none of their verdicts.
+
+// A present directory need not hold a test the project's Vitest includes — a consumer's own
+// `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
+const GUARD_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+const STRUCTURAL_GUARD_TARGETS: ReadonlyArray<string> = [
+	'scripts/issue/session-cite-scan.test.ts',
+	'tools/test/untested-sources.test.ts',
+	'tools/gh/gh-subcommand-guard.test.ts',
+]
+const STRUCTURAL_LISTS: ReadonlyArray<ReadonlyArray<string>> = [
+	[...GUARD_TEST_COMMAND, ...STRUCTURAL_GUARD_TARGETS],
+]
+const TYPESCRIPT_SUFFIX = '.ts'
+const FAILURE_EXIT_CODE = 1
+
+interface StructuralRun {
+	list: ReadonlyArray<string>
+	result: BufferedProcessResult
+}
+
+// The front of a failed check's heading — `josh lane:value metrics-stops` counts a ship output that
+// carries the metrics totals' one.
+function failure_prefix(list: ReadonlyArray<string>): string {
+	return `✗ ${list.join(' ')} — `
+}
+
+// Each failure is headed by the check's own command and how it ended: a check that failed with no
+// output of its own (`ELIFECYCLE Command failed` alone, or nothing) otherwise names nothing to fix.
+function failure_heading(list: ReadonlyArray<string>, result: BufferedProcessResult): string {
+	const ending =
+		result.exit_code === undefined
+			? 'no exit code (timed out or ended by a signal)'
+			: `exit code ${String(result.exit_code)}`
+
+	return `${failure_prefix(list)}${ending}`
+}
+
+function failure_section(list: ReadonlyArray<string>, result: BufferedProcessResult): string {
+	const parts = [failure_heading(list, result), result.output.trim()]
+
+	return parts.filter((part) => part !== '').join('\n')
+}
+
+// The whole-tree fallback is due as the narrowed run with a source in it is; both stay kit-only.
+function is_due(scope: ChangedFileScope, root: string): boolean {
+	if (!project_checks.is_kit_repository(root)) return false
+
+	return scope.mode === 'all' || scope.files.some((file) => file.endsWith(TYPESCRIPT_SUFFIX))
+}
+
+async function run_in(root: string, list: ReadonlyArray<string>): Promise<StructuralRun> {
+	return { list, result: await buffered_process.run_buffered_process(list, { cwd: root }) }
+}
+
+// All at once and buffered, every failure reported, so one run shows all there is to fix.
+async function run_structural(scope: ChangedFileScope, root: string): Promise<number> {
+	if (!is_due(scope, root)) return 0
+
+	const runs = await Promise.all(STRUCTURAL_LISTS.map(async (list) => await run_in(root, list)))
+	const failed = runs.filter(({ result }) => buffered_process.is_process_failed(result))
+
+	if (failed.length === 0) return 0
+
+	const sections = failed.map(({ list, result }) => failure_section(list, result))
+
+	process.stdout.write(`\n${sections.join('\n\n')}\n`)
+
+	return FAILURE_EXIT_CODE
+}
+
+const structural_checks = {
+	GUARD_TEST_COMMAND,
+	STRUCTURAL_GUARD_TARGETS,
+	failure_prefix,
+	failure_section,
+	run_structural,
+}
+
+export { structural_checks }

package/scripts/gate/verification-gate.ts

@@ -3,7 +3,8 @@ import { fileURLToPath } from 'node:url'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
-import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
@@ -14,6 +15,7 @@ import { gate_plan, type GatePlan } from './gate-plan'
 import { gate_report, type GateStepResult } from './gate-report'
 import { gate_run_steps, type ReusedChecks } from './gate-run-steps'
 import { gate_skip } from './gate-skip'
+import { gate_static_group } from './gate-static-group'
 import { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG } from './gate-steps'
 import { gate_tree, type GateTree } from './gate-tree'
 import { project_checks } from './project-checks'
@@ -168,15 +170,26 @@ async function run_marked_gate<T>(
 // **The free cores do not cap the plan** (joshuafolkken/kit#4167). The unit claim's admission narrows it
 // to the room the outside load leaves, read over its wait rather than once at the gate's start — a
 // width fixed off one busy instant held for the whole suite (`core_admission.is_too_narrow`).
-function announce_gate_plan(is_unit_included: boolean, available_cores: number): GatePlan {
+//
+// A `--static-group` narrows the resolved plan's checks and keeps its concurrency, which the full static
+// set sized: a cap above the narrowed count never binds.
+function announce_gate_plan(
+	is_unit_included: boolean,
+	available_cores: number,
+	static_group?: string,
+): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
 	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
-	const plan = gate_plan.resolve_gate_plan(
+	const resolved = gate_plan.resolve_gate_plan(
 		available_cores,
 		concurrent_runs,
 		is_unit_included,
 		is_kit_repository,
 	)
+	const plan = {
+		...resolved,
+		checks: gate_static_group.narrow_checks(resolved.checks, static_group),
+	}
 
 	process.stdout.write(`${gate_plan.format_gate_plan(plan, available_cores, concurrent_runs)}\n`)
 
@@ -195,6 +208,8 @@ interface GateOptions {
 	// Whether the unit suite is one of this gate's checks. Defaults to true everywhere; only
 	// `--no-unit` turns it off, for the CI job that runs the suite on a runner of its own.
 	is_unit_included?: boolean
+	// The one static group a CI matrix leg runs (`gate-static-group.ts`); set only with the unit suite off.
+	static_group?: string | undefined
 	stamp_path?: string
 	marker_path?: string
 	// The gate log's destination, a parameter for the same reason the two above are: this suite runs
@@ -253,7 +268,10 @@ function scoped_precheck_refusal(tree: GateTree, options: GateOptions): string |
 		return undefined
 	}
 
-	return scoped_green.refusal_for(tree.files, tree.base, options.scoped_sources)
+	return scoped_green.refusal_for(tree.files, tree.base, {
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		...options.scoped_sources,
+	})
 }
 
 // **A partial gate records nothing green, and this is the same rule as the skip one layer out**.
@@ -318,7 +336,7 @@ async function run_checked_gate(
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
 	// unit suite reads the flag as set and reserves nothing.
 	const budget = gate_run_steps.default_budget()
-	const plan = announce_gate_plan(is_unit_included, budget.available_cores)
+	const plan = announce_gate_plan(is_unit_included, budget.available_cores, options.static_group)
 	const reused = await checks_to_reuse(plan, tree, options)
 
 	// **The gate holds the unit-run marker for its whole run, not just its unit step.** The step that
@@ -406,31 +424,48 @@ const ACCEPTED_FLAGS: ReadonlyArray<string> = [VERBOSE_FLAG, gate_skip.FORCE_FLA
 
 // The flags are the caller's, the destinations are the run's, so the two are merged here rather than
 // letting an option override a flag the user typed.
+function unknown_arguments(extra_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	return extra_arguments.filter(
+		(argument) =>
+			!ACCEPTED_FLAGS.includes(argument) && gate_static_group.group_of(argument) === undefined,
+	)
+}
+
+// The shared refusal, plus the arguments it is actually about. Some flags are accepted, so the bare
+// "takes no extra arguments" would send a reader to drop the ones that work. The list is interpolated
+// rather than spelled out here, so adding a flag cannot leave this line stale.
+function write_refusal(unknown: ReadonlyArray<string>): void {
+	const groups = Object.keys(gate_static_group.STATIC_GROUPS).join('|')
+
+	process.stderr.write(
+		`${composite_arguments.format_rejection(GATE_COMMAND, GATE_TARGETS)}\n` +
+			`  refused: ${unknown.join(' ')}\n` +
+			`  accepted here: ${ACCEPTED_FLAGS.join(' ')} ${gate_static_group.STATIC_GROUP_FLAG_PREFIX}<${groups}>\n`,
+	)
+}
+
 async function run_gate_command(
 	extra_arguments: ReadonlyArray<string>,
 	options: GateOptions = {},
 ): Promise<number> {
-	const unknown = extra_arguments.filter((argument) => !ACCEPTED_FLAGS.includes(argument))
+	const unknown = unknown_arguments(extra_arguments)
 
 	if (unknown.length > 0) {
-		// The shared refusal, plus the arguments it is actually about. Some flags are accepted, so the
-		// bare "takes no extra arguments" would send a reader to drop the ones that work. The list is
-		// interpolated rather than spelled out here, so adding a flag cannot leave this line stale.
-		process.stderr.write(
-			`${composite_arguments.format_rejection(GATE_COMMAND, GATE_TARGETS)}\n` +
-				`  refused: ${unknown.join(' ')}\n` +
-				`  accepted here: ${ACCEPTED_FLAGS.join(' ')}\n`,
-		)
+		write_refusal(unknown)
 
 		return USAGE_ERROR_EXIT_CODE
 	}
 
+	// A static group is a part of the static set, so it implies `--no-unit` and every withholding that flag carries.
+	const static_group = gate_static_group.find_group(extra_arguments)
+
 	return await run_verification_gate({
 		is_scoped_enforced: true,
 		...options,
 		is_verbose: extra_arguments.includes(VERBOSE_FLAG),
 		is_forced: extra_arguments.includes(gate_skip.FORCE_FLAG),
-		is_unit_included: !extra_arguments.includes(NO_UNIT_FLAG),
+		is_unit_included: !extra_arguments.includes(NO_UNIT_FLAG) && static_group === undefined,
+		static_group,
 	})
 }
 
@@ -440,7 +475,7 @@ async function run_gate_command(
 // process end on its own, which it can, since every child has already exited by here.
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
-		ledger_path: await lane_ledger.target(),
+		ledger_path: await lane_ledger_write.target(),
 		check_records: check_reuse.DEFAULT_RECORDS,
 	})
 }