@joshuafolkken/kit 1.1229.0 → 1.1370.0

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

@@ -4,13 +4,13 @@ import { gate_skip, type GateReuse } from './gate-skip'
 import type { GateTree } from './gate-tree'
 
 // What the two git hooks share when they decline to re-run a check `pnpm josh gate` already passed on
-// this tree (joshuafolkken/kit#1381).
+// this tree.
 //
-// The pre-push hook got this behavior first (joshuafolkken/kit#1334) and the pre-commit type check is
+// The pre-push hook got this behavior first and the pre-commit type check is
 // the second reader of the same record. Everything that is the same in both lives here rather than in
 // each of them: the escape hatch, the pre-filter in front of the record, and the one `git status`
 // reading both narrow themselves from. **The record comparison itself is not here either** — it is
-// `gate_skip.reusable_green_gate`, joshuafolkken/kit#1328's, so a hook cannot answer "is this tree
+// `gate_skip.reusable_green_gate`, so a hook cannot answer "is this tree
 // still the recorded one" differently from the gate printing its answer beside it.
 //
 // **Every condition added here only ever narrows.** The gate's own three — the file map matches, the
@@ -19,7 +19,7 @@ import type { GateTree } from './gate-tree'
 // git operation is about to carry. Where the two can differ, the hook runs the check. Any reading that
 // could not be taken fails the same way: "we could not tell" must never resolve to "no need to check".
 
-// The `josh` targets that decline a check on the strength of this record (joshuafolkken/kit#1786).
+// The `josh` targets that decline a check on the strength of this record.
 //
 // **It is declared beside the mechanism rather than beside the reader.** `josh layers` reports which
 // checks run in more than one layer, and two of the rows it prints are not the repetition they look
@@ -51,13 +51,13 @@ function is_force_requested(force_environment: string): boolean {
 // `undefined` rather than an empty list when the reading failed, so a caller cannot mistake "git said
 // nothing" for "git could not be asked". Every predicate below treats the two differently.
 //
-// **The observation ledger is dropped from the reading, and it is the one line that may be**
-// (joshuafolkken/kit#1756). Lines are appended throughout a run — a review's record lands after its
+// **The observation ledger is dropped from the reading, and it is the one line that may be**.
+// Lines are appended throughout a run — a review's record lands after its
 // gate — and every condition below reads a non-empty status as "this operation carries a tree no
 // check has read". Left in, one ledger line would send every commit and every push in the primary
 // checkout back to the full gate, which is the reuse this module exists to grant. **Dropping it is
 // sound because the ledger is no code any check runs**: `pnpm josh git` stages it with the run's
-// commit only after its grammar has been parsed (joshuafolkken/kit#2763), and the rest of its content
+// commit only after its grammar has been parsed, and the rest of its content
 // is checked by the CI of the pull request that carries it.
 async function read_status_lines(): Promise<ReadonlyArray<string> | undefined> {
 	try {
@@ -93,7 +93,7 @@ interface HookReuse {
 	// The hook-specific narrowing: whether what this git operation carries is the tree the record
 	// describes. `is_worktree_clean` for a push, `is_index_matching_worktree` for a commit.
 	is_tree_carried: boolean
-	// The reason a refusal on that narrowing reports, in the hook's own words (joshuafolkken/kit#3307).
+	// The reason a refusal on that narrowing reports, in the hook's own words.
 	carry_miss: string
 	extra_arguments: ReadonlyArray<string>
 	force_env: string
@@ -105,7 +105,7 @@ interface HookReuse {
 
 // 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 (joshuafolkken/kit#3307).
+// printing. A refusal carries its reason instead.
 //
 // **Any argument at all refuses the reuse**, not only the force flag. A caller who narrowed the run
 // asked for that run rather than for a recorded result about a whole tree, and a hook's own line passes

package/scripts/gate/machine-capacity.ts

@@ -0,0 +1,313 @@
+import { readFile } from 'node:fs/promises'
+import { availableParallelism, cpus, totalmem } from 'node:os'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+
+// What the machine has free right now, read for the core budget's admission.
+//
+// **The budget used to be the core count, and that count is not what is free.** The ledger in
+// `core-budget.ts` admits against `availableParallelism()`, so the load it never sees — Claude sessions,
+// node processes that do not pass through `josh`, the window server — ran on top of a budget already
+// spent. On 2026-10-07, three lanes on the 11-core / 18 GB machine reached a load average of 16.8 with
+// 31% of the CPU in the kernel, compressing and swapping 4.4 GB of memory the ledger never counted.
+//
+// **This is a closed loop, not an open-loop formula.** An open loop would derive a share from the
+// core count up front; this reads what is busy and free at the moment of
+// admission and subtracts only the part the ledger does not already account for.
+//
+// **The busy cores are the CPU-time difference over a short window, not the load average.** The load
+// average trails by a minute, so a gate started just after another one finished would see the finished
+// one's load as external and wait out the decay. `os.cpus()` is one read with no process spawned.
+//
+// **A reading that fails answers undefined, and undefined is the old behavior.** A CI runner or a
+// container — where the host's CPU times are not this process's quota — budgets by the core count and
+// admits without looking at memory, exactly as before.
+//
+// **`run:board` draws its machine gauges from the same reading**, so what the
+// board shows a person is what the gate admits against. The board takes a sample with no window and
+// draws the difference from its previous one. `lane:sample` records the memory half of it, so the
+// lane-limit measurement sets the same figures beside the lane count.
+
+// 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
+const BYTES_PER_MB = 1_048_576
+const KB_PER_MB = 1024
+const PERCENT = 100
+const MEMINFO_PATH = '/proc/meminfo'
+const VMSTAT_PATH = '/proc/vmstat'
+const LINUX_AVAILABLE = /^MemAvailable:\s+(?<kb>\d+) kB/mu
+const LINUX_SWAP_IN = /^pswpin (?<pages>\d+)$/mu
+const LINUX_SWAP_OUT = /^pswpout (?<pages>\d+)$/mu
+const PAGE_SIZE_ARGUMENTS = ['PAGESIZE']
+// The whole memory reading in one `sysctl`, cheap enough for `run:board` to take
+// every second. `kern.memorystatus_level` is the kernel's own memory-pressure figure: the percentage of
+// memory still available, compressible and purgeable pages included — what `os.freemem()` leaves out on
+// macOS, where it reads near zero on a machine with gigabytes to spare. The swapper counters are the
+// pages swapped in and out since boot, `vm_stat`'s `Swapins` / `Swapouts`. The names stay in the output
+// (no `-n`), so a name an older macOS lacks drops only its own line.
+const LEVEL_NAME = 'kern.memorystatus_level'
+const SWAP_IN_NAME = 'vm.compressor.swapper.swapins_total'
+const SWAP_OUT_NAME = 'vm.compressor.swapper.swapouts_total'
+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 SYSCTL_ARGUMENTS = [LEVEL_NAME, SWAP_IN_NAME, SWAP_OUT_NAME, PAGE_SIZE_NAME, PRESSURE_NAME]
+const SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu
+
+interface MachineReading {
+	busy_cores: number | undefined
+	available_mb: number | undefined
+}
+
+// The memory half of a reading. `swapped_mb` is a counter — every page swapped in or out since boot —
+// so a rate is the difference between two readings. `pressure_level` is read on macOS only.
+interface MemoryReading {
+	available_mb: number | undefined
+	swapped_mb: number | undefined
+	pressure_level: number | undefined
+}
+
+// What the ledger's admitted reservations declare — the part of the machine's load already accounted for.
+interface LedgerLoad {
+	cores: number
+	memory_mb: number
+}
+
+interface MachineBudget {
+	cores: number
+	memory_mb: number
+}
+
+interface CpuTimes {
+	busy: number
+	total: number
+}
+
+// One moment of the machine for `run:board`: CPU times and the memory reading, no window waited out.
+interface MachineSample {
+	cpu: CpuTimes
+	memory: MemoryReading
+	total_mb: number
+}
+
+function cpu_times(): CpuTimes {
+	let busy = 0
+	let idle = 0
+
+	for (const { times } of cpus()) {
+		busy += times.user + times.nice + times.sys + times.irq
+		idle += times.idle
+	}
+
+	return { busy, total: busy + idle }
+}
+
+// The busy share of the CPU between two readings, from 0 to 1.
+function busy_share_between(before: CpuTimes, after: CpuTimes): number | undefined {
+	const total = after.total - before.total
+
+	if (total <= 0) return undefined
+
+	return (after.busy - before.busy) / total
+}
+
+function busy_cores_between(before: CpuTimes, after: CpuTimes, cores: number): number | undefined {
+	const share = busy_share_between(before, after)
+
+	return share === undefined ? undefined : share * cores
+}
+
+function sysctl_values(output: string): Map<string, number> {
+	const values = [...output.matchAll(SYSCTL_LINE)].map(
+		(match) => [match.groups?.['name'] ?? '', Number(match.groups?.['value'])] as const,
+	)
+
+	return new Map(values)
+}
+
+// The pages swapped in and out since boot; either count unread leaves the sum unread.
+function swapped_pages(
+	pages_in: number | undefined,
+	pages_out: number | undefined,
+): number | undefined {
+	return pages_in === undefined || pages_out === undefined ? undefined : pages_in + pages_out
+}
+
+function swapped_mb(pages: number | undefined, page_bytes: number | undefined): number | undefined {
+	if (pages === undefined || page_bytes === undefined) return undefined
+
+	return (pages * page_bytes) / BYTES_PER_MB
+}
+
+// What was swapped between two readings of the counter. A counter that went back — a reboot between
+// them — is read as nothing swapped.
+function swapped_between(from: number | undefined, to: number | undefined): number | undefined {
+	if (from === undefined || to === undefined) return undefined
+
+	return Math.max(0, to - from)
+}
+
+// `kern.memorystatus_level: 58` → 58% of physical memory still available, beside the swapped pages.
+function parse_darwin_memory(output: string, total_bytes: number): MemoryReading {
+	const values = sysctl_values(output)
+	const level = values.get(LEVEL_NAME)
+
+	return {
+		available_mb:
+			level === undefined ? undefined : (level / PERCENT) * (total_bytes / BYTES_PER_MB),
+		swapped_mb: swapped_mb(
+			swapped_pages(values.get(SWAP_IN_NAME), values.get(SWAP_OUT_NAME)),
+			values.get(PAGE_SIZE_NAME),
+		),
+		pressure_level: values.get(PRESSURE_NAME),
+	}
+}
+
+function parse_linux_available(meminfo: string): number | undefined {
+	const kb = LINUX_AVAILABLE.exec(meminfo)?.groups?.['kb']
+
+	return kb === undefined ? undefined : Number(kb) / KB_PER_MB
+}
+
+function pages_of(pattern: RegExp, vmstat: string): number | undefined {
+	const pages = pattern.exec(vmstat)?.groups?.['pages']
+
+	return pages === undefined ? undefined : Number(pages)
+}
+
+// `pswpin` and `pswpout` in `/proc/vmstat` are the pages swapped in and out since boot.
+function parse_linux_swapped(vmstat: string, page_bytes: number): number | undefined {
+	const pages = swapped_pages(pages_of(LINUX_SWAP_IN, vmstat), pages_of(LINUX_SWAP_OUT, vmstat))
+
+	return swapped_mb(pages, page_bytes)
+}
+
+async function settled<T>(read: () => Promise<T>): Promise<T | undefined> {
+	try {
+		return await read()
+	} catch {
+		return undefined
+	}
+}
+
+// A name `sysctl` does not know fails the command but still prints the others, so the exit is not read.
+async function read_darwin_memory(): Promise<MemoryReading> {
+	const { stdout } = await execa('sysctl', SYSCTL_ARGUMENTS, {
+		reject: false,
+		timeout: PROBE_TIMEOUT_MS,
+	})
+
+	return parse_darwin_memory(stdout, totalmem())
+}
+
+async function read_page_size(): Promise<string> {
+	const { stdout } = await execa('getconf', PAGE_SIZE_ARGUMENTS, { timeout: PROBE_TIMEOUT_MS })
+
+	return stdout
+}
+
+async function read_linux_memory(): Promise<MemoryReading> {
+	const [meminfo, vmstat, page_size] = await Promise.all([
+		settled(async () => await readFile(MEMINFO_PATH, 'utf8')),
+		settled(async () => await readFile(VMSTAT_PATH, 'utf8')),
+		settled(read_page_size),
+	])
+	const page_bytes = page_size === undefined ? undefined : Number(page_size)
+
+	return {
+		available_mb: meminfo === undefined ? undefined : parse_linux_available(meminfo),
+		swapped_mb:
+			vmstat === undefined || page_bytes === undefined
+				? undefined
+				: parse_linux_swapped(vmstat, page_bytes),
+		pressure_level: undefined,
+	}
+}
+
+const UNREAD_MEMORY: MemoryReading = {
+	available_mb: undefined,
+	swapped_mb: undefined,
+	pressure_level: undefined,
+}
+
+async function read_memory(): Promise<MemoryReading> {
+	if (process.platform === 'darwin') return (await settled(read_darwin_memory)) ?? UNREAD_MEMORY
+
+	return process.platform === 'linux' ? await read_linux_memory() : UNREAD_MEMORY
+}
+
+// A CPU quota narrower than the host makes the host-wide CPU times the wrong machine, so the busy cores
+// are read only where the quota and the host agree.
+function is_unquoted(): boolean {
+	return cpus().length > 0 && cpus().length === availableParallelism()
+}
+
+async function default_sleep(ms: number): Promise<void> {
+	await new Promise<void>((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+async function read_machine(
+	sleep: (ms: number) => Promise<void> = default_sleep,
+): Promise<MachineReading> {
+	const before = cpu_times()
+	const [memory] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)])
+	const busy_cores = is_unquoted()
+		? busy_cores_between(before, cpu_times(), cpus().length)
+		: undefined
+
+	return { busy_cores, available_mb: memory.available_mb }
+}
+
+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.
+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))
+}
+
+// **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.
+// 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 {
+	return {
+		cores: cores - external_cores(reading.busy_cores, ledger.cores),
+		memory_mb:
+			reading.available_mb === undefined ? Infinity : reading.available_mb + ledger.memory_mb,
+	}
+}
+
+const machine_capacity = {
+	BASELINE_CORES,
+	busy_cores_between,
+	busy_share_between,
+	external_cores,
+	machine_budget,
+	parse_darwin_memory,
+	parse_linux_available,
+	parse_linux_swapped,
+	read_machine,
+	read_memory,
+	read_sample,
+	swapped_between,
+}
+
+export type { CpuTimes, LedgerLoad, MachineBudget, MachineReading, MachineSample, MemoryReading }
+export { machine_capacity }

package/scripts/gate/pre-commit-type-check.ts

@@ -9,7 +9,7 @@ import { hook_gate_reuse } from './hook-gate-reuse'
 import { DEFAULT_TYPE_CHECK_ARGS, type_check_step } from './type-check-step'
 
 // The pre-commit hook's type check, which no longer re-runs a project-wide `tsc --noEmit` that a green
-// gate already covers (joshuafolkken/kit#1381).
+// gate already covers.
 //
 // Measured on this repository: `pnpm exec tsc --noEmit` over the whole project takes 3.8–4.4s warm, and
 // `pnpm josh git -y` pays it on every commit — a `fullrun` commits twice — seconds after `pnpm josh
@@ -22,8 +22,8 @@ import { DEFAULT_TYPE_CHECK_ARGS, type_check_step } from './type-check-step'
 // recorded wide one. So they are untouched, and so are `prevent-main-commit` and `secretlint`, which
 // the gate does not run at all and which are therefore duplicates of nothing.
 //
-// **The decision is joshuafolkken/kit#1328's, imported rather than restated** — `hook_gate_reuse`
-// carries what this shares with the pre-push hook (joshuafolkken/kit#1334) and defers the record
+// **The decision is the gate's, imported rather than restated** — `hook_gate_reuse`
+// carries what this shares with the pre-push hook and defers the record
 // comparison itself to `gate_skip.reusable_green_gate`. A hook answering "is this still the recorded
 // tree" differently from the gate beside it would be two commands disagreeing about one tree.
 //
@@ -54,7 +54,7 @@ interface CommitTree extends GateTree {
 }
 
 // **The record says the gate's four checks were green; it does not say *which* type check ran.**
-// `type-check-step.ts` resolves that per project (joshuafolkken/kit#934): a project carrying a
+// `type-check-step.ts` resolves that per project: a project carrying a
 // `josh-app` / `josh-game` shim has the toolkit's `check:ci` as its gate step, and this hook's step is
 // `tsc --noEmit`. Reusing across that difference would skip `tsc --noEmit` on the strength of a
 // different check — a `.ts` file inside the root `tsconfig.json` but outside the one `svelte-check` is

package/scripts/gate/project-checks.ts

@@ -1,6 +1,7 @@
 import { existsSync, globSync, readFileSync } 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'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
@@ -51,6 +52,12 @@ function project_root(directory: string): string {
 	)
 }
 
+// The kit repository itself rather than a consumer of it — the gate's and the detached ship's one
+// answer to whether kit-only checks run.
+function is_kit_repository(directory: string): boolean {
+	return !doctor_consumer.is_kit_consumer(project_root(directory))
+}
+
 function is_ignored(entry: string): boolean {
 	return entry.split(/[/\\]/u).some((part) => IGNORED_DIRS.has(part))
 }
@@ -106,7 +113,7 @@ function is_declared(directory: string, package_name: string): boolean {
 }
 
 // A tool the manifest lists but `node_modules` lacks is a project that has not run `pnpm install`
-// yet — typically right after `josh init` added it (joshuafolkken/kit#2709). Skipping it would pass a
+// yet — typically right after `josh init` added it. Skipping it would pass a
 // check the configuration asks for without running it, so only an undeclared tool is skipped; a
 // declared one is run and fails until it is installed.
 function missing_tool_reason(
@@ -124,7 +131,7 @@ function skip_notice(check: string, reason: string): string {
 }
 
 // Shared by `josh check` and the gate's type-check step, so neither reaches `tsc` on a basic
-// project that has nothing to type-check (joshuafolkken/kit#2709).
+// project that has nothing to type-check.
 function type_check_skip_reason(directory: string): string | undefined {
 	if (!is_basic(directory)) return undefined
 	if (!has_files(directory, TYPE_FILES)) return 'no TypeScript files were found'
@@ -135,7 +142,7 @@ function type_check_skip_reason(directory: string): string | undefined {
 
 // Shared by `josh lint`, `josh lint:related` and `josh format`, so a basic project without Web
 // files — a Python or Rust project, which `josh init` gives no Prettier — is skipped for the same
-// reason by all three (joshuafolkken/kit#2606, joshuafolkken/kit#2709).
+// reason by all three.
 function prettier_skip_reason(directory: string): string | undefined {
 	if (!is_basic(directory)) return undefined
 	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
@@ -144,7 +151,7 @@ function prettier_skip_reason(directory: string): string | undefined {
 }
 
 // Shared by `josh lint`, `josh lint:related` and `josh format`, so a basic project without ESLint
-// is skipped for the same reason by all three (joshuafolkken/kit#2693, joshuafolkken/kit#2709).
+// is skipped for the same reason by all three.
 function eslint_skip_reason(directory: string): string | undefined {
 	if (!is_basic(directory)) return undefined
 	if (!has_files(directory, SCRIPT_FILES)) return 'no JavaScript or TypeScript files were found'
@@ -163,6 +170,7 @@ const project_checks = {
 	has_config,
 	has_files,
 	is_basic,
+	is_kit_repository,
 	prettier_skip_reason,
 	project_root,
 	skip_notice,

package/scripts/gate/scoped-green.ts

@@ -6,22 +6,16 @@ import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_tree, type GateTree } from './gate-tree'
 
 // Whether the two scoped checks have been green on *this exact tree* by the time the review is
-// briefed (joshuafolkken/kit#1511).
+// briefed.
 //
-// **The commands were already shipped; what was missing was when they run.** joshuafolkken/kit#1298
-// and joshuafolkken/kit#1257 gave the run `lint:related` and `test:related`, and
-// joshuafolkken/kit#1383 and joshuafolkken/kit#1246 stopped it re-running the whole gate per edit.
-// None of them says the pair has to have answered before the review starts, and `fullrun #1503` is
-// what that costs: the gate and round 1 were started on a tree neither check had ever read, three
-// findings then arrived on three separate round trips with fourteen edits between them, and the
-// rework ran 282 seconds — 31% of a 905-second run. The same run proves the cheap half: the one call
-// that ran both checks together took 13.8 seconds and produced two of the three findings at once.
+// **It fixes when `lint:related` and `test:related` run.** A gate and a review round started on a
+// 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. That is the boundary
-// joshuafolkken/kit#1420 sits on the far side of: that issue asked to *reuse* a scoped check's result
-// instead of re-running it and was closed as not needed, and this record does not revive it.
+// 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.
 //
 // **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`
@@ -29,8 +23,8 @@ import { gate_tree, type GateTree } from './gate-tree'
 // 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.
 //
-// **It refuses `josh review:brief`, and now the local `josh gate` too, but never CI's**
-// (joshuafolkken/kit#2296). The brief was the first refusal point because it is where `review:attest`
+// **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`
 // mints the nonce a round is counted against, so no countable review round bypasses it. But the gate
 // itself runs *before* the brief, and a run that reached it on a tree the scoped pair had never read
 // paid for the gap anyway — so `verification-gate.ts` reads this same record one step earlier and
@@ -69,7 +63,7 @@ interface ScopedSources {
 	is_unit_skipped?: boolean
 }
 
-// **`test:related` is required only where it can ever answer** (joshuafolkken/kit#3136). In a project
+// **`test:related` is required only where it can ever answer**. In a project
 // whose unit guard skips — vitest absent, or a basic project with no test file — `test:related` runs
 // nothing and so writes no record, and requiring one refused the gate forever with no way through.
 // The guard's own decision is asked rather than re-derived, so the writer and this reader agree; a
@@ -142,7 +136,7 @@ function missing_checks(
 }
 
 // The same answer as `missing_checks`, as the `josh` script names a caller runs rather than the
-// command lines a refusal prints — so the ship supervisor (joshuafolkken/kit#2500) meets the
+// command lines a refusal prints — so the ship supervisor meets the
 // precondition itself by running exactly what the refusal would have asked for.
 function missing_scripts(
 	tree: Record<string, string>,
@@ -230,8 +224,7 @@ interface GreenRecord {
 	// Where the record lands, defaulted by the stamp itself. It exists for the same reason
 	// `record_green` and `gate_skip.reusable_green_gate` take one: without it this function can only
 	// write the real per-checkout record, so a suite exercising it would vouch for the surrounding
-	// run's own tree — the second-writer trap joshuafolkken/kit#1437 and joshuafolkken/kit#1441
-	// closed for the gate and round-1 records.
+	// run's own tree — the second-writer trap the gate and round-1 records close the same way.
 	target?: string
 }
 

package/scripts/gate/type-check-command.ts

@@ -6,8 +6,8 @@ import { project_checks } from './project-checks'
 
 // `josh check` — the project-wide TypeScript check. It used to be a bare `tsc --noEmit` shell entry,
 // so on a basic project with nothing to type-check it failed with `Command "tsc" not found` while
-// the gate, which asks `type_check_skip_reason` first, skipped the same step
-// (joshuafolkken/kit#2709). Both now read that one decision.
+// the gate, which asks `type_check_skip_reason` first, skipped the same step.
+// Both now read that one decision.
 
 const ARGV_OFFSET = 2
 const FAIL_EXIT_CODE = 1

package/scripts/gate/type-check-step.ts

@@ -2,10 +2,10 @@ import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
-// joshuafolkken/kit#934: `josh gate`'s type-check step used to be `tsc --noEmit` for every project.
-// A SvelteKit project type-checks with `svelte-check` behind `svelte-kit sync`, so the fixed step
-// both missed every `.svelte` type error and failed outright on a clean checkout, where `./$types`
-// has not been generated yet.
+// `josh gate`'s type-check step cannot be `tsc --noEmit` for every project. A SvelteKit project
+// type-checks with `svelte-check` behind `svelte-kit sync`, so a fixed `tsc` step would both miss
+// every `.svelte` type error and fail outright on a clean checkout, where `./$types` has not been
+// generated yet.
 //
 // The step is therefore asked of the application layer rather than assumed. Two rules decide it:
 //