@joshuafolkken/kit 1.872.0

package/scripts/doctor/doctor.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env tsx
+import { readFileSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
+import { security_updates } from '#scripts/security/security-updates'
+import { running_binary } from '#scripts/version/running-binary'
+import { doctor_consumer } from './doctor-consumer'
+import { doctor_io, type GitTopLevel } from './doctor-io'
+import { doctor_logic } from './doctor-logic'
+import { doctor_ports } from './doctor-ports'
+
+const FIX_FLAG = '--fix'
+const PORTS_FLAG = '--ports'
+const UNKNOWN = '(unknown)'
+const NOT_ON_PATH = '(not on PATH)'
+const SELF_DIR = path.dirname(fileURLToPath(import.meta.url))
+// Deliberately smaller than the setting query's budget: the two run back to back, so `doctor`'s
+// worst case is the git probe plus this plus GH_TIMEOUT_MS — 2000 + 3000 + 5000, ten seconds. That
+// keeps a command which made no network calls at all before joshuafolkken/kit#805 prompt enough to
+// stay usable when the network is unreachable.
+const REPO_LOOKUP_TIMEOUT_MS = 3000
+
+// Where the local applicability gates look for the artifacts that decide whether a report applies.
+interface GateScope {
+	root: string
+	boundary: string | undefined
+}
+
+// Which repository-scoped reports this project has a prerequisite for.
+interface ApplicableSettings {
+	security_updates: boolean
+	auto_merge: boolean
+}
+
+interface DoctorContext {
+	running_version: string | undefined
+	running_path: string
+	path_josh: string | undefined
+	global_josh: string | undefined
+}
+
+function gather_context(): DoctorContext {
+	return {
+		running_version: running_binary.read_running_version(SELF_DIR),
+		running_path: running_binary.running_package_directory(SELF_DIR),
+		path_josh: doctor_io.resolve_path_josh(),
+		global_josh: doctor_io.resolve_pnpm_global_josh(),
+	}
+}
+
+function print_report(ctx: DoctorContext): void {
+	console.info('josh doctor')
+	console.info(`  Running:     ${ctx.running_version ?? UNKNOWN}  (${ctx.running_path})`)
+	console.info(`  On PATH:     ${ctx.path_josh ?? NOT_ON_PATH}`)
+	console.info(`  pnpm global: ${ctx.global_josh ?? UNKNOWN}`)
+}
+
+// Remove a confirmed stale kit shim so the pnpm-global josh reclaims PATH precedence. Any other
+// shadowing binary is left in place and reported for manual review.
+function reclaim_shim(path_josh: string, global_josh: string): void {
+	const content = readFileSync(path_josh, 'utf8')
+	const decision = doctor_logic.decide_reclaim(path_josh, global_josh, content)
+
+	if (decision.action !== 'remove' || decision.target === undefined) {
+		console.info(`  ${decision.reason}`)
+
+		return
+	}
+
+	rmSync(decision.target)
+	console.info(`  ✓ ${decision.reason}: ${decision.target}`)
+}
+
+function handle_shadow(ctx: DoctorContext, is_fix: boolean): void {
+	if (ctx.path_josh === undefined || ctx.global_josh === undefined) return
+	console.info('')
+	console.info(doctor_logic.format_shadow_warning(ctx.path_josh, ctx.global_josh))
+	if (is_fix) reclaim_shim(ctx.path_josh, ctx.global_josh)
+}
+
+function report_path_diagnosis(ctx: DoctorContext, is_fix: boolean): void {
+	if (doctor_logic.is_shadowed(ctx.path_josh, ctx.global_josh)) {
+		handle_shadow(ctx, is_fix)
+
+		return
+	}
+
+	console.info('  ✓ no PATH shadowing detected')
+}
+
+// Where a repository-scoped check should look for the artifact that decides whether it applies.
+// An undetermined root still gets gated, against the working directory as the best root available:
+// skipping the gate there would warn about a nonexistent repository from a home directory whenever
+// `git` is missing or refuses the repository. Inside a known repository the search is bounded to its
+// root, so a repository nested under a kit consumer does not inherit the parent's files.
+function resolve_gate_scope(git: GitTopLevel): GateScope | undefined {
+	if (git.state === 'outside') return undefined
+	if (git.state === 'inside') return { root: git.top_level, boundary: git.top_level }
+
+	return { root: PROJECT_ROOT, boundary: undefined }
+}
+
+// Which prerequisites this repository actually has, decided locally so the answer does not depend on
+// `gh` working. The two are independent: a consumer synced before joshuafolkken/kit#834 has the
+// Dependabot config and no auto-merge workflow, and a repository that only ever added an auto-merge
+// workflow of its own has the second prerequisite and not the first.
+function resolve_applicable(scope: GateScope): ApplicableSettings {
+	return {
+		security_updates: doctor_io.has_distributed_dependabot_config(scope.root, scope.boundary),
+		auto_merge: doctor_io.has_auto_merge_workflow(scope.root, scope.boundary),
+	}
+}
+
+// Everything past the gate reports, including a failed lookup: `could not be read` is informative
+// while silence is the false all-clear joshuafolkken/kit#805 exists to remove.
+function report_applicable_settings(
+	applicable: ApplicableSettings,
+	repo: string | undefined,
+): void {
+	if (applicable.security_updates) security_updates.report_security_updates_section(repo)
+	if (applicable.auto_merge) auto_merge_setting.report_auto_merge_section(repo)
+}
+
+// Last, and after the local diagnosis: this is the only part of `doctor` that touches the network,
+// and `doctor` is what a user runs when the install is already broken. Offline or behind a hanging
+// proxy the PATH report and `--fix` must still complete (joshuafolkken/kit#805).
+//
+// Applicability is decided by the artifact rather than by the directory. `doctor` diagnoses the
+// global install and is routinely run from a home directory or from a clone of an unrelated project;
+// each prerequisite only exists where the file that creates it landed, so those files are the gates.
+// Without them the warnings would describe a repository that either does not exist or never consumed
+// kit, and would print enabling commands for someone else's repository. `init` and `sync` always run
+// inside the project they just wrote those files into.
+//
+// The repository name is resolved once, and only when at least one report will use it: `doctor`
+// writes nothing, so the bounded lookup is the right one, and spawning it for a repository with no
+// prerequisite at all would be a network call with nothing to report.
+function report_repository_settings(git: GitTopLevel): void {
+	const scope = resolve_gate_scope(git)
+	if (scope === undefined) return
+	const applicable = resolve_applicable(scope)
+	if (!applicable.security_updates && !applicable.auto_merge) return
+
+	report_applicable_settings(
+		applicable,
+		gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
+	)
+}
+
+// The discovery map, printed for whichever repository `doctor` is standing in. Nothing is printed
+// from outside a repository: discovery is anchored on the current repository's own owner, so without
+// one there is no map to be right or wrong about (joshuafolkken/kit#869).
+function report_repository_map(git: GitTopLevel): void {
+	if (git.state !== 'inside') return
+
+	const map = repo_discovery.discover_repositories(git.top_level)
+
+	console.info('')
+	console.info(doctor_logic.format_repository_map(map))
+}
+
+// Each discovered repository's port seed and the ports it resolves to, and any seed shared by more
+// than one of them (joshuafolkken/kit#1494). Anchored on the same map as `report_repository_map`, so
+// it prints from inside a repository and nowhere else.
+function report_port_seeds(git: GitTopLevel): void {
+	if (git.state !== 'inside') return
+
+	const map = repo_discovery.discover_repositories(git.top_level)
+
+	console.info('')
+	console.info(doctor_ports.report_port_seeds(map))
+}
+
+interface DoctorOptions {
+	is_fix: boolean
+	show_ports: boolean
+}
+
+function parse_options(argv: ReadonlyArray<string>): DoctorOptions {
+	return { is_fix: argv.includes(FIX_FLAG), show_ports: argv.includes(PORTS_FLAG) }
+}
+
+// The consumer checks run against the repository root when inside one, and against the working
+// directory otherwise — the same best-available root the settings gate falls back to.
+function consumer_root(git: GitTopLevel): string {
+	return git.state === 'inside' ? git.top_level : PROJECT_ROOT
+}
+
+// The port seed table is opt-in since joshuafolkken/kit#1930: it discovers every sibling repository
+// and was the slowest, least diagnostic part of the default output. `--ports` brings it back.
+function run_reports(ctx: DoctorContext, git: GitTopLevel, options: DoctorOptions): void {
+	print_report(ctx)
+	report_path_diagnosis(ctx, options.is_fix)
+	doctor_consumer.report_consumer_setup(consumer_root(git))
+	report_repository_map(git)
+	if (options.show_ports) report_port_seeds(git)
+	report_repository_settings(git)
+}
+
+function main(): void {
+	const options = parse_options(process.argv)
+	const ctx = gather_context()
+
+	// Resolved once and shared: `doctor` is what a user runs when things are already broken, and a
+	// second `git rev-parse` would add a second timeout to a command whose whole contract is to stay
+	// responsive when git itself is hanging (joshuafolkken/kit#805).
+	const git = doctor_io.resolve_git_top_level()
+
+	run_reports(ctx, git, options)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+const doctor = {
+	gather_context,
+	print_report,
+	reclaim_shim,
+	handle_shadow,
+	parse_options,
+	consumer_root,
+	run_reports,
+	report_repository_map,
+	report_port_seeds,
+	main,
+}
+
+export type { DoctorContext }
+export { doctor }

package/scripts/document/backlogrun-parent-read-set.ts

@@ -0,0 +1,48 @@
+// What a `backlogrun` parent reads, and what that trims from a full read (joshuafolkken/kit#2256).
+//
+// **The parent is the scheduler, and it never implements.** It reads `backlog:next`, dispatches each
+// child in its own delegated `fullrun` unit, opens lanes, runs the progress watcher and the hand-off,
+// and parks a child that cannot finish (`backlogrun.md` step 1: "Claim nothing at the entry — this
+// parent orchestrates and never implements"). So the `SKILL.md` sections only an *implementing* entry
+// uses are read at the section level rather than whole, exactly as the worker trims its own read
+// (`lane-child-read-set.ts`) — through the shared `read-set-trim`.
+//
+// **This is a different set from the worker's.** The parent keeps §0 (its session-cut / resume
+// paragraph is the parent's own), §2b (the parent's whole job is the epic-child delegation §2b
+// defines), §2c (the parent is the entry that receives an `owner/repo#` prefix), §2e and §2i (the
+// parent files prerequisites and observations for the batch) — all of which the worker drops. What the
+// parent drops is the implementer-only set below. **The parent owns every point-of-use document**, so
+// unlike the worker it drops none of them: the trim is the `SKILL.md` sections alone.
+
+import type { ReadSetCost } from './entry-read-set'
+import { read_set_trim } from './read-set-trim'
+
+const BACKLOGRUN = 'backlogrun'
+
+// **The `SKILL.md` sections the `backlogrun` parent never uses.** The parent has no `new` entry, so it
+// names no `into` target (§2a); it claims no working tree, a dispatched child does that in its own
+// unit (§2f, `backlogrun.md:47-49`); it implements nothing, so it reads no Issue's comments before
+// implementing (§2g); and it edits no rule mid-run (§3, read only on an editing turn).
+const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
+	'2a. The `into <target>` suffix — where the new Issue lands',
+	'2f. The working-tree hold — one run per tree',
+	"2g. An Issue's comments are part of the Issue",
+	'3. What stays resident, and what is read from here',
+]
+
+// The parent runs every point-of-use document itself — child dispatch, lanes, the progress watcher,
+// the park — so it drops none. Named empty so the shared trim reads the same shape as the worker's.
+const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set<string>()
+
+function costed(root: string): ReadSetCost {
+	return read_set_trim.costed(root, {
+		base_entry: BACKLOGRUN,
+		label: BACKLOGRUN,
+		unused_skill_sections: UNUSED_SKILL_SECTIONS,
+		skipped_point_of_use: SKIPPED_POINT_OF_USE,
+	})
+}
+
+const backlogrun_parent_read_set = { BACKLOGRUN, UNUSED_SKILL_SECTIONS, costed }
+
+export { backlogrun_parent_read_set }

package/scripts/document/bash-output-cap.ts

@@ -0,0 +1,45 @@
+// The character cap a Bash result is truncated at, read from the settings file rather than restated
+// (joshuafolkken/kit#1797). Every entry-read document is larger than it, so a `cat` of one hands back
+// a middle-truncated preview and the file is then read a second time — the two wasted requests #1797
+// measured. A number copied into code would be a second declaration of the cap and would drift the
+// first time the settings changed; the harness's own default stands in only where the file declares
+// nothing. Split out of `entry-read-set.ts` in joshuafolkken/kit#2161 to keep that file under its
+// line ceiling.
+
+import path from 'node:path'
+import { document_section } from './document-section'
+
+const SETTINGS_FILE = path.join('.claude', 'settings.json')
+const HARNESS_DEFAULT_CAP_CHARS = 30_000
+const ENV_KEY = 'env'
+const CAP_KEY = 'BASH_MAX_OUTPUT_LENGTH'
+const NONE = 0
+
+function property_of(value: unknown, key: string): unknown {
+	if (typeof value !== 'object' || value === null) return undefined
+
+	return Reflect.get(value, key)
+}
+
+// **Parsed as JSON rather than matched in the raw text.** A regular expression takes the first
+// occurrence anywhere in the file, so a hook command string naming the variable would win over the
+// `env` block — and the report would then mark a file `cat`-able that a `cat` truncates. A file that
+// is missing or does not parse answers `undefined` and falls through to the harness default below.
+function declared_cap(text: string): unknown {
+	try {
+		return property_of(property_of(JSON.parse(text), ENV_KEY), CAP_KEY)
+	} catch {
+		return undefined
+	}
+}
+
+function bash_output_cap(root: string): number {
+	const text = document_section.read_optional(path.join(root, SETTINGS_FILE)) ?? ''
+	const chars = Number(declared_cap(text))
+
+	return Number.isSafeInteger(chars) && chars > NONE ? chars : HARNESS_DEFAULT_CAP_CHARS
+}
+
+const bash_output_cap_reader = { HARNESS_DEFAULT_CAP_CHARS, bash_output_cap }
+
+export { bash_output_cap_reader }

package/scripts/document/document-byte-budget.ts

@@ -0,0 +1,183 @@
+// The byte ceiling for every agent-read document NO entry reads — the fallback budget, a ratchet.
+//
+// **This is now the secondary budget** (joshuafolkken/kit#2257). The primary one is the entry total
+// (`entry-read-budget.ts`): a document a workflow entry reads is held by that entry's total and
+// carries no ceiling here, so neither budget holds it twice. What is left for this list is the
+// documents no entry reads — the reference documents a human browses, drawn by
+// `document-reachability.ts` from `read:set`'s output rather than by a hand-written table.
+//
+// Agent-read documents (`.claude/skills/**/*.md`, `prompts/**/*.md` and `docs/josh-commands.md`) have
+// been shrunk by reduction epics (joshuafolkken/kit#1929, joshuafolkken/kit#1924) only to swell
+// again, because nothing held the reduced size — a PR that adds a few lines at a time goes unseen
+// until the next reduction epic. This list is that hold for the unreached ones:
+// `document-byte-budget.test.ts` fails `pnpm josh gate` when such a document grows past its recorded
+// ceiling, when the list names a file that no longer exists, or when an unreached file has no entry
+// here.
+//
+// THE RECORDED CEILING IS BLOCK-QUANTIZED — this is what stops parallel command-adding lanes from
+// serializing on this file (joshuafolkken/kit#2231). Each entry's `bytes` is not the document's exact
+// size but the smallest multiple of `BLOCK_BYTES` at or above it, and that value IS the ceiling. A
+// document that grows within its current block needs no edit here, so most command-adding PRs leave
+// this file untouched rather than bumping a shared line; a document that crosses a block boundary
+// bumps to the next multiple — the same value from every lane, an identical change git auto-merges,
+// not a hand-picked slack unit two branches fight over. Growth is still bounded: the block is the
+// whole of a document's headroom, so it cannot swell without a visible, deterministic bump in the
+// diff. This replaced the earlier exact-size-plus-512-slack ratchet, whose tight slack forced
+// `docs/josh-commands.md` — pinned at its ceiling — to bump on every command addition, the
+// serialization point #2231 removed. It also retired the bespoke `JOSH_COMMANDS_CEILING_BYTES` hard
+// cap and its per-bump changelog comment: the uniform block ratchet now holds that document like any
+// other, so the second cap was a second line to bump for no added hold.
+//
+// HOW TO RAISE (or LOWER) A CEILING — this file is the only place, on purpose. When the gate reports a
+// document over its ceiling, copy the exact value the message names (the next block multiple) into
+// that document's entry, in the same PR, so the reason for the growth is visible in the diff a
+// reviewer reads. A reduction epic that shrinks a document below a block lowers its entry the same
+// way, to the multiple the stale-ratchet message names. Do NOT widen `BLOCK_BYTES` to dodge a bump —
+// that loosens every ceiling at once, which is the opposite of the ratchet's purpose.
+//
+// It is a list of records rather than a path-keyed object because file paths are not valid object
+// property names under the naming-convention lint rule.
+
+interface DocumentBudget {
+	path: string
+	bytes: number
+}
+
+// The quantization block. A recorded ceiling is a multiple of this, so a document growing within a
+// block needs no edit and one crossing a boundary bumps to the same next multiple from every lane —
+// the property that keeps parallel lanes from conflicting on this file. Kept small enough that the
+// ratchet still holds growth tightly: the block is the entire headroom a document has before its next
+// deterministic bump. Widening it to dodge a bump is the workaround the ratchet exists to forbid, so
+// its value is pinned by a test.
+const BLOCK_BYTES = 4096
+
+// The smallest multiple of `BLOCK_BYTES` at or above `size` — the recorded ceiling for a document of
+// that size. Two lanes that grow the same document into the same block compute the same ceiling, so
+// the edit they both make is identical and merges cleanly; a document growing within its block
+// computes the ceiling it already has, so it needs no edit at all.
+function block_ceiling(size: number): number {
+	return Math.ceil(size / BLOCK_BYTES) * BLOCK_BYTES
+}
+
+// Recorded byte ceiling of each unreached document — the block multiple at or above its size. Must
+// name exactly the documents `document_reachability.unreached_documents()` derives: the test fails on
+// a stale entry (a file that no longer exists or that an entry now reads) and on an un-budgeted
+// unreached file, so the definition cannot rot as documents move on or off the execution path.
+const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
+	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 8192 },
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 32_768 },
+	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/followup-reference.md', bytes: 16_384 },
+	{ path: '.claude/skills/workflow-commands/fullrun-steps.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/into-target.md', bytes: 4096 },
+	{ path: '.claude/skills/workflow-commands/issue-comments.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/issue-fold-existing.md', bytes: 4096 },
+	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 28_672 },
+	// `pre-gate-cut.md` left this per-document budget in joshuafolkken/kit#2289: it became a point-of-use
+	// document, so its bytes are now held by every entry's total read (`entry-read-budget.ts`) and the
+	// two budgets must not hold it twice — the reachability line moved it from `unreached` to
+	// `point-of-use`.
+	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
+	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
+	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
+	{ path: 'docs/josh-commands.md', bytes: 163_840 },
+	{ path: 'prompts/agent-rules.md', bytes: 4096 },
+	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
+	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/consultation-vs-execution.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/cross-repo-epic.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/distributed-docs.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/durable-rules.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/epic-audit.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/epic-bundle.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/latest-first.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/no-clones.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 16_384 },
+	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/proposal-request.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 28_672 },
+	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 57_344 },
+	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/simplicity-first.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/single-source-rules.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 20_480 },
+	{ path: 'prompts/refactoring.md', bytes: 8192 },
+	{ path: 'prompts/review-rubric.md', bytes: 20_480 },
+	{ path: 'prompts/review.md', bytes: 20_480 },
+	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
+	{ path: 'prompts/testing-guide.md', bytes: 20_480 },
+]
+
+// The recorded ceiling for one path, or undefined when it carries no budget entry.
+function recorded_bytes_for(relative_path: string): number | undefined {
+	return DOCUMENT_BYTE_BUDGET.find((entry) => entry.path === relative_path)?.bytes
+}
+
+// The bytes an entry has left before its ceiling — the recorded ceiling minus the document's current
+// size. Negative when the document is already over. `josh bytes` prints it as the headroom before an
+// edit, the same number `josh lines` prints for code lines (joshuafolkken/kit#2176).
+function remaining_bytes(recorded_bytes: number, current_bytes: number): number {
+	return recorded_bytes - current_bytes
+}
+
+// The failure message the size test raises — names the file, its current byte size, its recorded
+// ceiling, and where to raise it (this file), per the acceptance criteria.
+//
+// **It names the exact value to record**: the recorded ceiling is the block multiple at or above the
+// document's size, so the number to write is `block_ceiling(current)` — a reader raising the ceiling
+// copies it rather than computing it by hand. Two lanes that both cross into the same block copy the
+// same value, so the edit they make merges without conflict.
+function over_budget_message(
+	relative_path: string,
+	current_bytes: number,
+	recorded_bytes: number,
+): string {
+	const ceiling = recorded_bytes.toString()
+	const current = current_bytes.toString()
+	const next = block_ceiling(current_bytes).toString()
+	const raise_hint = `raise its recorded size to ${next} in scripts/document/document-byte-budget.ts so the reason shows in the PR diff`
+
+	return `${relative_path} is ${current} bytes, over its ${ceiling}-byte ceiling. Shrink the document, or ${raise_hint}.`
+}
+
+// The failure message the staleness test raises. A recorded ceiling more than a block above the
+// document's actual size is a stale-loose ratchet: the document shrank across a block boundary and
+// its record was never lowered, so the ceiling no longer holds the reduction (the drift
+// joshuafolkken/kit#2125 swept). It names the file, its recorded ceiling, its actual size, and the
+// block multiple to lower the record to.
+function stale_budget_message(
+	relative_path: string,
+	recorded_bytes: number,
+	current_bytes: number,
+): string {
+	const recorded = recorded_bytes.toString()
+	const current = current_bytes.toString()
+	const next = block_ceiling(current_bytes).toString()
+	const lower_hint = `lower its recorded size to ${next} in scripts/document/document-byte-budget.ts so the ratchet holds the reduction`
+
+	return `${relative_path} records ${recorded} bytes but is ${current}, more than a block above actual. ${lower_hint}.`
+}
+
+const document_byte_budget = {
+	DOCUMENT_BYTE_BUDGET,
+	BLOCK_BYTES,
+	block_ceiling,
+	over_budget_message,
+	recorded_bytes_for,
+	remaining_bytes,
+	stale_budget_message,
+}
+
+export type { DocumentBudget }
+export { document_byte_budget }

package/scripts/document/document-byte-check.ts

@@ -0,0 +1,131 @@
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { document_byte_budget } from './document-byte-budget'
+import { document_reachability } from './document-reachability'
+import { entry_read_budget } from './entry-read-budget'
+
+// The byte-ceiling check the gate's `document-byte-budget.test.ts` runs, made reachable on the fast
+// between-edits path — `josh lint:related` calls it over the files it already resolved so a mandated
+// documentation update that grows a document past its ceiling is caught in seconds rather than after
+// the 80–90-second gate (joshuafolkken/kit#2176). The ceiling and its message are
+// `document-byte-budget.ts`'s alone: this adds no budget of its own, so the fast path can never hold
+// a different line from the gate, and widening one can never loosen the other.
+//
+// **It reads no change of its own.** `lint:related` has already resolved which files the change
+// touched; taking that same list keeps the check inside the lint command's git contract — no second
+// reading, and none at all when the caller narrowed by explicit arguments.
+
+const LABEL = 'byte budget'
+
+// The over-ceiling message given a size that is already known — the recorded value and the current
+// size are handed in, so the decision is pure and tested without a filesystem or a budget lookup. A
+// path with no budget entry (`recorded` undefined) is out of scope: the budget names exactly the
+// agent-read documents, and everything else is not this check's to hold.
+function ceiling_message(
+	relative_path: string,
+	current_bytes: number,
+	recorded_bytes: number | undefined,
+): string | undefined {
+	if (recorded_bytes === undefined) return undefined
+	if (current_bytes <= recorded_bytes) return undefined
+
+	return document_byte_budget.over_budget_message(relative_path, current_bytes, recorded_bytes)
+}
+
+// The same decision for an absolute path the caller resolved: its budget looked up by the
+// repository-relative spelling, its size read from disk. A path with no budget entry, or one the
+// tree no longer holds, is not over budget.
+function over_budget_for(root: string, absolute_path: string): string | undefined {
+	const relative_path = path.relative(root, absolute_path)
+	const recorded = document_byte_budget.recorded_bytes_for(relative_path)
+	if (recorded === undefined || !existsSync(absolute_path)) return undefined
+
+	return ceiling_message(relative_path, statSync(absolute_path).size, recorded)
+}
+
+// Every over-ceiling message across the resolved file list, in the order the files came in.
+function over_budget_messages(
+	root: string,
+	absolute_files: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return absolute_files
+		.map((absolute_path) => over_budget_for(root, absolute_path))
+		.filter((message): message is string => message !== undefined)
+}
+
+// The entry-total counterpart: an entry over its recorded ceiling. This is the primary budget
+// (joshuafolkken/kit#2257), so an edit to a covered document — which grows an entry's total, not a
+// per-document ceiling — is caught here on the same fast path. Stale ceilings are left to the gate's
+// `entry-read-budget.test.ts`, exactly as the per-document staleness is: this path blocks growth.
+function entry_over_budget_message(root: string, entry: string): string | undefined {
+	const recorded = entry_read_budget.recorded_bytes_for(entry)
+	if (recorded === undefined) return undefined
+
+	const current = entry_read_budget.entry_total_bytes(root, entry)
+	if (current <= recorded) return undefined
+
+	return entry_read_budget.over_budget_message(entry, current, recorded)
+}
+
+function entry_over_budget_messages(root: string): ReadonlyArray<string> {
+	return entry_read_budget.ENTRY_READ_BUDGET.map((entry) =>
+		entry_over_budget_message(root, entry.entry),
+	).filter((message): message is string => message !== undefined)
+}
+
+// Whether the change touches a document some entry reads. A covered document's edit moves an entry
+// total rather than a per-document ceiling, so the entry check runs only when one is in scope.
+function touches_covered(root: string, absolute_files: ReadonlyArray<string>): boolean {
+	const covered = new Set(document_reachability.covered_documents(root))
+
+	return absolute_files.some((absolute_path) => covered.has(path.relative(root, absolute_path)))
+}
+
+// Prints one labelled line per over-ceiling message and answers non-zero, or stays silent and
+// answers zero when nothing is over budget.
+function report(messages: ReadonlyArray<string>): number {
+	if (messages.length === 0) return 0
+
+	const lines = messages.map((message) => `${LABEL}: ${message}`)
+
+	process.stdout.write(`${lines.join('\n')}\n`)
+
+	return 1
+}
+
+// The check over a resolved change — every over-ceiling document among the files the caller narrowed
+// by, plus the entry totals when the change touches a document some entry reads.
+function check_files(root: string, absolute_files: ReadonlyArray<string>): number {
+	const entry_messages = touches_covered(root, absolute_files)
+		? entry_over_budget_messages(root)
+		: []
+
+	return report([...over_budget_messages(root, absolute_files), ...entry_messages])
+}
+
+// The check the caller runs when its scope widened to the whole tree (`mode === 'all'`) instead of a
+// resolved change. `lint:related`'s own fallback lints a superset of the change, so the byte check
+// widens to the whole budget rather than an empty file list — otherwise the fallback would report
+// success on a tree it never read for bytes, and the green record the caller then writes would vouch
+// for a byte dimension it never checked (joshuafolkken/kit#2176).
+function check_all(root: string): number {
+	const absolute_files = document_byte_budget.DOCUMENT_BYTE_BUDGET.map((entry) =>
+		path.join(root, entry.path),
+	)
+
+	return report([
+		...over_budget_messages(root, absolute_files),
+		...entry_over_budget_messages(root),
+	])
+}
+
+const document_byte_check = {
+	ceiling_message,
+	check_all,
+	check_files,
+	entry_over_budget_messages,
+	over_budget_for,
+	over_budget_messages,
+}
+
+export { document_byte_check }