@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/delegation/investigation-reads.ts

@@ -2,16 +2,19 @@ import path from 'node:path'
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
 import { capped_print_part } from '#scripts/document/capped-print-part'
+import { changed_paths_sync } from '#scripts/git/changed-paths-sync'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_bundle_call } from '#scripts/time-runtime/time-bundle-call'
+import { time_search_call } from '#scripts/time-runtime/time-search-call'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { time_spans, type Span } from '#scripts/time-runtime/time-spans'
 import { delegation_policy } from './delegation-policy'
 
 // How many files a run has read and not edited since its last delegated unit, counted off the
 // transcript rather than left to the agent's memory, so the threshold fires again on a second
-// accumulation. A delegation clears the set; a read adds to it; an edit exempts its file.
+// accumulation. A delegation clears the set; a read adds to it; an edit exempts its file, as does
+// the branch's own change since its merge base, which an earlier session of the run wrote.
 
 const READ_TOOLS: ReadonlySet<string> = new Set(['Read'])
 // Both spellings of the subagent tool are in use: `Task` (published) and `Agent` (this harness).
@@ -32,12 +35,6 @@ const CONTENT_READ_LABELS: ReadonlySet<string> = new Set(
 	CONTENT_READ_COMMANDS.map((command) => time_shell.bash_label(command)),
 )
 
-// A search carries no file text but costs a turn, so searches count in turns: parallel ones count once.
-const SEARCH_COMMANDS: ReadonlyArray<string> = ['fd', 'find', 'grep', 'rg']
-const SEARCH_LABELS: ReadonlySet<string> = new Set(
-	SEARCH_COMMANDS.map((command) => time_shell.bash_label(command)),
-)
-
 const { INVESTIGATOR_AGENT } = delegation_policy
 
 // The deny reason is the only text that reaches the model, so it names the count, command and return shape.
@@ -55,7 +52,8 @@ interface ReadTally {
 	// The search-side `pending` / `pending_since`, reset by a delegation or a successful write.
 	searches: number
 	searches_since: number
-	// Files successfully edited in the window; a read of one stays in the main line, so it never counts.
+	// Files successfully edited in the window or changed on the branch; a read of one stays in the main
+	// line, so it never counts.
 	edited: ReadonlySet<string>
 }
 
@@ -187,10 +185,6 @@ interface Accumulation {
 	searches: Map<string, number>
 }
 
-function is_read_only_search(span: Span): boolean {
-	return SEARCH_LABELS.has(span.label) && span.is_bundleable && !span.may_write
-}
-
 // A span with no message id is a turn of its own, as in every other turn counter.
 function search_turn_key(searches: ReadonlyMap<string, number>, span: Span): string {
 	if (span.message_id !== time_spans.NO_MESSAGE_ID) return span.message_id
@@ -209,19 +203,27 @@ function apply_search(searches: Map<string, number>, span: Span): void {
 
 	const turn = search_turn_key(searches, span)
 
-	if (is_read_only_search(span) && !searches.has(turn)) searches.set(turn, span.ended_ms)
+	// A search carries no file text but costs a turn, so searches count in turns: parallel ones count once.
+	if (time_search_call.is_read_only_search(span) && !searches.has(turn)) {
+		searches.set(turn, span.ended_ms)
+	}
+}
+
+// A refused dispatch (`investigator-foreground`, `agent-model`) ran no unit, so it resets nothing.
+function is_delegation(span: Span): boolean {
+	return DELEGATION_TOOLS.has(span.label) && !is_failed_outcome(span)
 }
 
 function apply_span(accumulation: Accumulation, span: Span, edited: ReadonlySet<string>): void {
-	if (DELEGATION_TOOLS.has(span.label)) {
+	if (is_failed_outcome(span)) return
+
+	if (is_delegation(span)) {
 		accumulation.pending.clear()
 		accumulation.searches.clear()
 
 		return
 	}
 
-	if (is_failed_outcome(span)) return
-
 	apply_search(accumulation.searches, span)
 
 	if (!is_content_read(span.label)) return
@@ -232,7 +234,7 @@ function apply_span(accumulation: Accumulation, span: Span, edited: ReadonlySet<
 }
 
 function last_delegation_ms(spans: ReadonlyArray<Span>): number {
-	return delegation_instant(spans.findLast((span) => DELEGATION_TOOLS.has(span.label)))
+	return delegation_instant(spans.findLast((span) => is_delegation(span)))
 }
 
 // The window is the tail the hook read; the set clears at every delegation, so the tail suffices.
@@ -240,9 +242,15 @@ function pending_after(pending: ReadonlyMap<string, number>, since_ms: number):
 	return [...pending.values()].filter((at_ms) => at_ms > since_ms).length
 }
 
-function tally_of(text: string, since_ms: number = hook_decision.NEVER_MS): ReadTally {
+// `branch_files` (repository-relative) are the branch's own change since its merge base: an earlier
+// session of this run wrote them, and a resumed session's transcript holds none of those writes.
+function tally_of(
+	text: string,
+	since_ms: number = hook_decision.NEVER_MS,
+	branch_files: ReadonlyArray<string> = [],
+): ReadTally {
 	const { spans, started_ms } = time_spans.parse_timeline(text)
-	const edited = edited_files(spans)
+	const edited = new Set([...edited_files(spans), ...subject_targets(branch_files)])
 	const accumulation: Accumulation = { pending: new Map(), searches: new Map() }
 
 	for (const span of spans) apply_span(accumulation, span, edited)
@@ -313,7 +321,9 @@ function is_read_only_command(call: GuardedCall, labels: ReadonlySet<string>): b
 
 // A search is refusable without a subject target: a bare-directory sweep is what this count is for.
 function is_search_call(call: GuardedCall): boolean {
-	return is_read_only_command(call, SEARCH_LABELS)
+	return time_search_call.is_read_only_search(
+		time_spans.to_tool_call(call.name, call.input, time_spans.NO_MESSAGE_ID),
+	)
 }
 
 // This guard counts reading, so a `Bash` line that also writes is never refused, and neither is a call
@@ -335,6 +345,20 @@ function is_growing_past_threshold(tally: ReadTally, call: GuardedCall): boolean
 	return projected_count(tally.pending, call, tally.edited) > tally.pending.length
 }
 
+function is_blocking(tally: ReadTally, call: GuardedCall, refused_at_ms: number): boolean {
+	return is_growing_past_threshold(tally, call) && is_rearmed(tally, refused_at_ms)
+}
+
+// The branch diff is a git read, so it is asked only of a call the transcript alone would refuse; more
+// edited files can only lower the counts, so a call that passes without it passes with it.
+function is_blocking_past_branch(text: string, call: GuardedCall, refused_at_ms: number): boolean {
+	if (!is_blocking(tally_of(text, refused_at_ms), call, refused_at_ms)) return false
+
+	const branch_files = changed_paths_sync.read_changed_paths()
+
+	return is_blocking(tally_of(text, refused_at_ms, branch_files), call, refused_at_ms)
+}
+
 function should_block(
 	text: string,
 	call: GuardedCall,
@@ -344,9 +368,7 @@ function should_block(
 	// A delegated unit is never refused: the remedy — send the reading to a unit — does not exist inside one.
 	if (!is_refusable_call(call) || is_unit_run(run)) return false
 
-	const tally = tally_of(text, refused_at_ms)
-
-	return is_growing_past_threshold(tally, call) && is_rearmed(tally, refused_at_ms)
+	return is_blocking_past_branch(text, call, refused_at_ms)
 }
 
 const investigation_reads = {

package/scripts/dependabot/dependabot-cooldown.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_content } from '#scripts/sync/file-content'
 import {
 	DEFAULT_RELEASE_AGE_MINUTES,
 	release_window,
@@ -184,7 +185,7 @@ function sync_dependabot_cooldown(root: string): boolean {
 	const existing = readFileSync(config_path, 'utf8')
 	const merged = merge_cooldown(existing, release_window.read_release_window(root))
 	if (merged === existing) return false
-	writeFileSync(config_path, merged)
+	file_content.write_contained(config_path, merged)
 
 	return true
 }

package/scripts/discovery/repo-party.ts

@@ -1,5 +1,6 @@
 import { repo_discovery } from './repo-discovery'
-import { repo_origin } from './repo-origin'
+import { repo_origin, type RepoIdentity } from './repo-origin'
+import { session_owner_pin } from './session-owner-pin'
 
 // **First-party vs third-party, computed rather than judged**. `CLAUDE.md`
 // and `upstream-interrupt.md` both declared the test mechanical — owner equality between the target
@@ -32,45 +33,100 @@ function classify(session_owner: string | undefined, target: string | undefined)
 // The owner half of a `owner/repo` argument, parsed through the remote-URL reader so a `.git` suffix
 // and a malformed form (one segment, three segments) are handled by the one place that already knows
 // them rather than by a second split here.
+function parse_owner_repo(owner_repo: string): RepoIdentity | undefined {
+	return repo_origin.parse_origin_url(`https://${repo_origin.GITHUB_HOST}/${owner_repo}`)
+}
+
 function target_owner(owner_repo: string): string | undefined {
-	return repo_origin.parse_origin_url(`https://${repo_origin.GITHUB_HOST}/${owner_repo}`)?.owner
+	return parse_owner_repo(owner_repo)?.owner
 }
 
-// The owner of the repository the session runs in, read locally from its `origin` — no network call
-// and no authenticated CLI, so the guard that consults it stays synchronous.
+// The owner of the repository the session runs in: the one pinned at session start, else read
+// locally from its `origin` — no network call and no authenticated CLI, so the guard that consults it
+// stays synchronous. The pin is what keeps a mid-session remote rewrite from changing the answer
+// (`session-owner-pin.ts`).
 function current_owner(repository_path: string = process.cwd()): string | undefined {
-	return repo_discovery.resolve_current_owner(repository_path)
+	return (
+		session_owner_pin.pinned(repository_path) ??
+		repo_discovery.resolve_current_owner(repository_path)
+	)
+}
+
+// The repository a `[HOST/]OWNER/REPO` selector names — `GH_REPO`, or `gh`'s `-R` / `--repo` value —
+// read from its last two segments so an optional host prefix is skipped.
+function selector_repository(selector: string): RepoIdentity | undefined {
+	return parse_owner_repo(selector.split('/').slice(-GH_REPO_PATH_SEGMENTS).join('/'))
 }
 
-// The owner `GH_REPO` names, read from its last two segments so an optional host prefix is skipped.
-function gh_repo_owners(gh_repo: string): Array<string | undefined> {
-	return [target_owner(gh_repo.split('/').slice(-GH_REPO_PATH_SEGMENTS).join('/'))]
+function selector_owner(selector: string): string | undefined {
+	return selector_repository(selector)?.owner
 }
 
-// The owner of every remote the work tree declares. A remote whose owner cannot be read stays in the
-// set as `undefined` rather than being dropped: an SSH host alias (`git@github-work:o/r.git`) is one
-// `gh` translates to github.com and may pick, so dropping it would hide the owner `gh` writes to.
-function remote_owners(repository_path: string): Array<string | undefined> {
+// Every remote the work tree declares. A remote that cannot be read stays in the set as `undefined`
+// rather than being dropped: an SSH host alias (`git@github-work:o/r.git`) is one `gh` translates to
+// github.com and may pick, so dropping it would hide the repository `gh` writes to.
+function remote_repositories(repository_path: string): Array<RepoIdentity | undefined> {
 	return repo_discovery
 		.read_remote_urls(repository_path)
-		.map((url) => repo_origin.parse_origin_url(url)?.owner)
+		.map((url) => repo_origin.parse_origin_url(url))
 }
 
-// Every owner `gh` could expand the `{owner}` placeholder to. `GH_REPO`
+// Every repository `gh` could expand the `{owner}/{repo}` placeholders to. `GH_REPO`
 // (`[HOST/]OWNER/REPO`) overrides the remotes outright; otherwise `gh` picks its base repository among
 // the GitHub remotes — `upstream` ahead of `origin`, or a `gh repo set-default` choice — so in a fork
-// checkout it can expand to the upstream owner. Answering the whole candidate set rather than
+// checkout it can expand to the upstream repository. Answering the whole candidate set rather than
 // re-implementing that pick keeps the caller safe whichever remote `gh` chooses. An `undefined` entry
-// is a candidate whose owner could not be read, which the caller must not assume is first-party.
+// is a candidate that could not be read, which the caller must not assume is first-party.
+function placeholder_repositories(
+	repository_path: string,
+	environment: NodeJS.ProcessEnv,
+): Array<RepoIdentity | undefined> {
+	const gh_repo = environment[GH_REPO_ENV_KEY]
+
+	return gh_repo === undefined || gh_repo === ''
+		? remote_repositories(repository_path)
+		: [selector_repository(gh_repo)]
+}
+
 function placeholder_owners(
 	repository_path: string = process.cwd(),
 	environment: NodeJS.ProcessEnv = process.env,
 ): Array<string | undefined> {
-	const gh_repo = environment[GH_REPO_ENV_KEY]
+	return placeholder_repositories(repository_path, environment).map((identity) => identity?.owner)
+}
 
-	return gh_repo === undefined || gh_repo === ''
-		? remote_owners(repository_path)
-		: gh_repo_owners(gh_repo)
+// Two spellings of one repository, compared case-insensitively as GitHub resolves them.
+function is_same_repository(left: RepoIdentity | undefined, right: RepoIdentity): boolean {
+	if (left === undefined || classify(left.owner, right.owner) !== FIRST_PARTY) return false
+
+	return left.repo.toLowerCase() === right.repo.toLowerCase()
+}
+
+// The one repository every candidate names, or nothing when there is none, one is unreadable, or two
+// differ — a fork checkout whose `upstream` `gh` may pick ahead of `origin`.
+function sole_repository(
+	candidates: ReadonlyArray<RepoIdentity | undefined>,
+): RepoIdentity | undefined {
+	const [first, ...rest] = candidates
+	if (first === undefined) return undefined
+
+	return rest.every((candidate) => is_same_repository(candidate, first)) ? first : undefined
+}
+
+// The checkout's own repository: the one `{owner}/{repo}` expands to — where `josh issue:comment`
+// posts. Nothing unless that is one repository whichever candidate `gh` picks, so a spelled-out
+// repository is never read as the one `issue:comment` reaches when it might not be
+// (joshuafolkken/kit#4737).
+function current_repository(
+	repository_path: string = process.cwd(),
+	environment: NodeJS.ProcessEnv = process.env,
+): RepoIdentity | undefined {
+	return sole_repository(placeholder_repositories(repository_path, environment))
+}
+
+// Whether `target` is the checkout's own repository `current_repository` answered.
+function is_own_repository(target: RepoIdentity, own: RepoIdentity | undefined): boolean {
+	return is_same_repository(own, target)
 }
 
 const repo_party = {
@@ -79,7 +135,11 @@ const repo_party = {
 	UNKNOWN,
 	classify,
 	current_owner,
+	current_repository,
+	is_own_repository,
 	placeholder_owners,
+	selector_owner,
+	sole_repository,
 	target_owner,
 }
 

package/scripts/discovery/session-owner-pin.ts

@@ -0,0 +1,51 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { repo_discovery } from './repo-discovery'
+
+// **The session's owner, fixed when the session starts** (joshuafolkken/kit#4659). The first-party
+// test compares a target's owner with the session's, and the session's was read from `origin` on
+// every call — so `git remote set-url origin https://github.com/<other>/x` mid-session made another
+// owner first-party. The session-start hook records the owner once; `repo_party.current_owner`
+// answers the record ahead of the live remote. Only the session's owner is pinned: the `{owner}`
+// placeholder candidates and a selector-less `gh` write still resolve against the live remotes.
+//
+// **Written by the process the session start already runs** (`audit-provision --session-start`), so
+// pinning adds no spawn to the launch, and read as one local file by the hooks that already run — no
+// network call. A checkout with no record (a session the hook did not start) falls back to `origin`.
+//
+// **Per checkout, replaced at every session start.** The record is the stamp `stamp-file.ts` keeps in
+// the temp directory, keyed on the account and the checkout path; a checkout whose origin owner
+// cannot be read at start leaves no record rather than a stale one. A command run outside a session
+// reads the last session's record for that path, which the next session start replaces.
+
+const PIN_PREFIX = 'josh-session-owner-'
+const PIN_SUFFIX = '.txt'
+
+function pin_path(repository_path: string): string {
+	return stamp_file.stamp_path(PIN_PREFIX, repository_path, PIN_SUFFIX)
+}
+
+// Records the checkout's `origin` owner for the session about to run. Never throws: this runs at
+// session start beside the scanner provisioning, and an unwritable temp directory only costs the pin.
+function pin(repository_path: string = process.cwd()): string | undefined {
+	const owner = repo_discovery.resolve_current_owner(repository_path)
+
+	try {
+		if (owner === undefined) stamp_file.remove_stamp(pin_path(repository_path))
+		else stamp_file.write_text_stamp(pin_path(repository_path), owner)
+	} catch {
+		return undefined
+	}
+
+	return owner
+}
+
+// The owner recorded at session start, or `undefined` when the checkout holds no readable record.
+function pinned(repository_path: string = process.cwd()): string | undefined {
+	const text = stamp_file.read_stamp_text(pin_path(repository_path))?.trim()
+
+	return text === '' ? undefined : text
+}
+
+const session_owner_pin = { pin, pin_path, pinned }
+
+export { session_owner_pin }

package/scripts/document/capped-print.ts

@@ -68,6 +68,6 @@ function capped_print(text: string, label: string, root: string = process.cwd())
 	console.info(listing(text, budget, write_parts(label, text, budget)))
 }
 
-const capped_output = { HEADROOM_CHARS, capped_print }
+const capped_output = { HEADROOM_CHARS, capped_print, output_budget }
 
 export { capped_output }

package/scripts/document/command-reference-line-budget.ts

@@ -0,0 +1,42 @@
+// The long-line ceiling of the command reference — one source for `command-reference.test.ts` and the
+// fast `josh lint:related` path (`document-ratchet-check.ts`), so the two can never hold different
+// lines. A reference entry is a short summary; the why behind it lives in the page's maintainer
+// rationale file. The pages once carried 137 lines over 400 characters (joshuafolkken/kit#3868); the
+// ceiling is a ratchet at the long lines left after condensing them, so lowering it is the only way
+// it moves.
+
+// The only files under `docs/` an agent is routed to read — the four command references; the rest of
+// `docs/` is reference a human browses, so the byte budget (`document/document-byte-budget.ts`)
+// covers these alone.
+const COMMAND_REFERENCE_DOCS: ReadonlyArray<string> = [
+	'docs/josh-commands.md',
+	'docs/josh-commands-automation.md',
+	'docs/josh-commands-run.md',
+	'docs/josh-commands-backlog.md',
+]
+const LONG_LINE_CHARACTERS = 400
+const MAX_LONG_LINES = 3
+
+// The lines over the length limit across every page handed in — the ceiling holds the pages
+// together, so one page's cut makes room in another.
+function long_line_count(texts: ReadonlyArray<string>): number {
+	return texts
+		.flatMap((text) => text.split('\n'))
+		.filter((line) => line.length > LONG_LINE_CHARACTERS).length
+}
+
+// The failure for a count over the ceiling, or undefined at or under it.
+function long_line_violation(count: number): string | undefined {
+	if (count <= MAX_LONG_LINES) return undefined
+
+	return `the command reference (${COMMAND_REFERENCE_DOCS.join(', ')}) has ${count.toString()} lines over ${LONG_LINE_CHARACTERS.toString()} characters, over its ceiling of ${MAX_LONG_LINES.toString()}. Shorten the entry — the why belongs in the page's maintainer rationale file.`
+}
+
+const command_reference_line_budget = {
+	COMMAND_REFERENCE_DOCS,
+	long_line_count,
+	long_line_violation,
+	MAX_LONG_LINES,
+}
+
+export { command_reference_line_budget }

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

@@ -73,10 +73,18 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands-automation.md', bytes: 45_056 },
-	{ path: 'docs/josh-commands-run.md', bytes: 69_632 },
-	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
-	{ path: 'docs/josh-commands.md', bytes: 53_248 },
+	// `command:derive`'s usage section (joshuafolkken/kit#4970) crossed the 45056 block.
+	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
+	// The carried `--unpinned-ok` record (joshuafolkken/kit#4775) crossed the 73728 block.
+	// `run:merge`'s withdrawn child (joshuafolkken/kit#4916) crossed the 77824 block.
+	// `lane:plan --probe` and the entry probe (joshuafolkken/kit#5211) crossed the 81920 block.
+	{ path: 'docs/josh-commands-run.md', bytes: 86_016 },
+	// `josh effect:audit` (joshuafolkken/kit#4958) and `issue:priority`'s usage section (joshuafolkken/kit#4960) crossed the 57344 block;
+	// `josh prose:stale` (joshuafolkken/kit#5287) crossed the 61440 block.
+	{ path: 'docs/josh-commands-backlog.md', bytes: 65_536 },
+	// `run:merge` withdrawing a lane closed without a merge (joshuafolkken/kit#4916) crossed the 53248 block;
+	// `gate --static-group` (joshuafolkken/kit#5215) crossed the 57344 block.
+	{ path: 'docs/josh-commands.md', bytes: 61_440 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 4096 },
@@ -84,8 +92,9 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 4096 },
-	// The priority declaration and its criteria (joshuafolkken/kit#4383) crossed the 8192 block.
-	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 12_288 },
+	// The priority declaration and its criteria (joshuafolkken/kit#4383) crossed the 8192 block; the
+	// causing-lane declaration and criteria F / G (joshuafolkken/kit#4749) crossed the 12288 one.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow/lane-instructions.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/measurement.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 8192 },
@@ -103,7 +112,8 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 8192 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
 	{ path: 'prompts/review-rubric.md', bytes: 12_288 },
-	{ path: 'prompts/review.md', bytes: 12_288 },
+	// Self-check 2's `josh prose:stale` pointer (joshuafolkken/kit#5287) crossed the 12288 block.
+	{ path: 'prompts/review.md', bytes: 16_384 },
 	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
 	{ path: 'prompts/testing-guide.md', bytes: 12_288 },
 ]

package/scripts/document/document-checks.ts

@@ -0,0 +1,20 @@
+import { document_byte_check } from './document-byte-check'
+import { document_ratchet_check } from './document-ratchet-check'
+
+// The document checks `josh lint:related` brings forward from the gate's tests, as one call: the
+// byte ceilings (`document-byte-check.ts`) and the ratchets (`document-ratchet-check.ts`). Both run
+// every time, so one edit reports every ceiling it broke in one pass rather than one per run.
+
+const CHECKS = [document_byte_check, document_ratchet_check]
+
+function check_files(root: string, absolute_files: ReadonlyArray<string>): number {
+	return Math.max(...CHECKS.map((check) => check.check_files(root, absolute_files)))
+}
+
+function check_all(root: string): number {
+	return Math.max(...CHECKS.map((check) => check.check_all(root)))
+}
+
+const document_checks = { check_all, check_files }
+
+export { document_checks }

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

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { project_checks } from '#scripts/gate/project-checks'
+import { command_reference_line_budget } from './command-reference-line-budget'
+import { issue_citation_budget } from './issue-citation-budget'
+
+// The two document ratchets the gate's tests hold — the command reference's long-line ceiling
+// (`command-reference.test.ts`) and each agent-read document's issue-citation count
+// (`issue-citation-budget.test.ts`) — made reachable on the fast between-edits path beside
+// `document-byte-check.ts`, so a documentation edit that breaks either surfaces in seconds rather
+// than in a minutes-long `check:related` (joshuafolkken/kit#4986). The ceilings, the counting and the
+// messages are the budget modules' alone; this adds none of its own.
+//
+// It reads no change of its own: `lint:related` hands in the files it already resolved. The citation
+// check holds the documents the budget records; a document with no entry, and the whole-list checks
+// (a stale or a zero entry), stay with the gate's test, which knows the agent-read set.
+//
+// Both ratchets are kit's: the budget records kit's paths, and a consumer's own file at one of them
+// holds its own count, so a consumer root is checked by neither.
+
+const LABEL = 'document ratchet'
+
+function read_text(absolute_path: string): string | undefined {
+	return existsSync(absolute_path) ? readFileSync(absolute_path, 'utf8') : undefined
+}
+
+// The long-line failure across the whole command reference, which the ceiling holds together.
+function long_line_message(root: string): string | undefined {
+	const texts = command_reference_line_budget.COMMAND_REFERENCE_DOCS.map((relative_path) =>
+		read_text(path.join(root, relative_path)),
+	).filter((text): text is string => text !== undefined)
+
+	return command_reference_line_budget.long_line_violation(
+		command_reference_line_budget.long_line_count(texts),
+	)
+}
+
+function touches_command_reference(root: string, absolute_files: ReadonlyArray<string>): boolean {
+	const references = new Set(command_reference_line_budget.COMMAND_REFERENCE_DOCS)
+
+	return absolute_files.some((absolute_path) => references.has(path.relative(root, absolute_path)))
+}
+
+// The citation failure for one file the budget records, or undefined when it holds its count, has no
+// entry, or is gone from the tree.
+function citation_message(root: string, absolute_path: string): string | undefined {
+	const relative_path = path.relative(root, absolute_path)
+	const recorded = issue_citation_budget.recorded_citations_for(relative_path)
+	const text = read_text(absolute_path)
+	if (recorded === 0 || text === undefined) return undefined
+
+	const current = issue_citation_budget.count_citations(text)
+
+	return issue_citation_budget.citation_violation(relative_path, current, recorded)
+}
+
+function citation_messages(
+	root: string,
+	absolute_files: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return absolute_files
+		.map((absolute_path) => citation_message(root, absolute_path))
+		.filter((message): message is string => message !== undefined)
+}
+
+// Prints one labelled line per failure and answers non-zero, or stays silent and answers zero.
+function report(messages: ReadonlyArray<string | undefined>): number {
+	const lines = messages
+		.filter((message): message is string => message !== undefined)
+		.map((message) => `${LABEL}: ${message}`)
+	if (lines.length === 0) return 0
+
+	process.stdout.write(`${lines.join('\n')}\n`)
+
+	return 1
+}
+
+// The check over a resolved change: the long-line ceiling when it touches a command reference page,
+// and the citation count of every changed file the budget records. An unrelated change reads nothing.
+function check_files(root: string, absolute_files: ReadonlyArray<string>): number {
+	if (!project_checks.is_kit_repository(root)) return 0
+	const long_line = touches_command_reference(root, absolute_files)
+		? long_line_message(root)
+		: undefined
+
+	return report([long_line, ...citation_messages(root, absolute_files)])
+}
+
+// The whole-tree fallback: the long-line ceiling and every recorded document, a superset of any change.
+function check_all(root: string): number {
+	if (!project_checks.is_kit_repository(root)) return 0
+	const absolute_files = issue_citation_budget.ISSUE_CITATION_BUDGET.map((entry) =>
+		path.join(root, entry.path),
+	)
+
+	return report([long_line_message(root), ...citation_messages(root, absolute_files)])
+}
+
+const document_ratchet_check = { check_all, check_files }
+
+export { document_ratchet_check }

package/scripts/document/document-section.ts

@@ -262,6 +262,7 @@ function read_optional(file_path: string): string | undefined {
 
 const document_section = {
 	candidates,
+	fenced_flags,
 	headings,
 	read_optional,
 	section,

package/scripts/document/entry-read-budget.ts

@@ -34,6 +34,9 @@ const { block_ceiling } = document_byte_budget
 const { LANE_CHILD } = lane_child_read_set
 const { BACKLOGRUN } = backlogrun_parent_read_set
 const NOTHING = 0
+// The command that re-measures every entry total in seconds, named by the over-budget message so a
+// trim is checked without re-running the whole lint or gate.
+const RECHECK_COMMAND = 'pnpm josh bytes'
 
 interface EntryBudget {
 	entry: string
@@ -46,8 +49,8 @@ interface EntryBudget {
 const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	{ entry: 'kickoff', bytes: 36_864 },
 	{ entry: 'fullrun', bytes: 53_248 },
-	{ entry: 'halfrun', bytes: 49_152 },
-	{ entry: 'prrun', bytes: 53_248 },
+	{ entry: 'halfrun', bytes: 45_056 },
+	{ entry: 'prrun', bytes: 57_344 },
 	{ entry: 'backlogrun', bytes: 81_920 },
 	{ entry: LANE_CHILD, bytes: 45_056 },
 ]
@@ -95,7 +98,7 @@ function over_budget_message(entry: string, current_bytes: number, recorded_byte
 	const next = block_ceiling(current_bytes).toString()
 	const raise_hint = `raise its recorded size to ${next} in scripts/document/entry-read-budget.ts so the reason shows in the PR diff`
 
-	return `entry ${entry} reads ${current_bytes.toString()} bytes, over its ${recorded_bytes.toString()}-byte ceiling. Trim what it reads, or ${raise_hint}.`
+	return `entry ${entry} reads ${current_bytes.toString()} bytes, over its ${recorded_bytes.toString()}-byte ceiling. Trim what it reads, or ${raise_hint}. Recheck with \`${RECHECK_COMMAND}\`.`
 }
 
 // The stale-ratchet message: a recorded ceiling more than a block above the entry's actual total was
@@ -113,6 +116,7 @@ function stale_budget_message(
 
 const entry_read_budget = {
 	ENTRY_READ_BUDGET,
+	RECHECK_COMMAND,
 	entry_total_bytes,
 	over_budget_message,
 	recorded_bytes_for,