@joshuafolkken/kit 1.1128.0 → 1.1166.0

package/scripts/delegation/investigation-reads.ts

@@ -55,10 +55,23 @@ const CONTENT_READ_LABELS: ReadonlySet<string> = new Set(
 	CONTENT_READ_COMMANDS.map((command) => time_shell.bash_label(command)),
 )
 
+// **The searches carry no file text, so they are counted in turns rather than files**
+// (joshuafolkken/kit#3139). The file count above never saw a `grep`, yet searches were the commonest
+// exploration turn a lane took — 457 of them in one day, each re-reading the main line's whole context.
+// What a search costs is the turn, so a turn is the unit: parallel searches in one turn 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)),
+)
+
+// The unit the refusal sends the reading to (joshuafolkken/kit#3139): `.claude/agents/investigator.md`,
+// the parent's model at a lowered effort. A consumer receives it through the plugin as `kit:investigator`.
+const INVESTIGATOR_AGENT = 'investigator'
+
 // What the refusal tells the model. It has to name the count, the command and the return shape,
 // because the deny reason is the only text that reaches the model — a run that is refused and told
 // nothing reads it as a broken tool.
-const REASON = `⛔ investigation: ${String(delegation_policy.INVESTIGATION_FILE_THRESHOLD)} files read and not edited since the last delegated unit, so the reading from here goes to a unit of its own. Ask \`pnpm josh delegate investigation\`, then brief a unit with what the main line has already concluded and what is left to find out; it returns the conclusion plus its \`file:line\` citations, never the file text. Keep a read in the main line only where this run will edit that file — an \`Edit\` cannot be issued against text you do not hold. This run's own instructions and the harness's own session files — a backgrounded call's output, a persisted tool result, this session's scratchpad — are never counted, so they are not what took the count here. The rule is \`.claude/skills/workflow-commands/SKILL.md\` → §2b, "The pre-implementation reading".`
+const REASON = `⛔ investigation: ${String(delegation_policy.INVESTIGATION_FILE_THRESHOLD)} files read and not edited, or ${String(delegation_policy.INVESTIGATION_SEARCH_TURN_THRESHOLD)} search turns, since the last delegated unit, so the reading from here goes to a unit of its own (a successful write also starts the search count over). Ask \`pnpm josh delegate investigation\`, then dispatch the \`${INVESTIGATOR_AGENT}\` agent (\`kit:${INVESTIGATOR_AGENT}\` in a consumer) with a brief of what the main line has already concluded and what is left to find out; it returns the conclusion plus its \`file:line\` citations, never the file text. Keep a read in the main line only where this run will edit that file — an \`Edit\` cannot be issued against text you do not hold. This run's own instructions and the harness's own session files — a backgrounded call's output, a persisted tool result, this session's scratchpad — never count toward the files, so they are not what took the file count here; every read-only search turn counts, whatever it names. The rule is \`.claude/skills/workflow-commands/delegation.md\` → "The pre-implementation reading".`
 
 interface ReadTally {
 	// The files read and not since edited, resolved so the two ways a target reaches here compare.
@@ -74,14 +87,18 @@ interface ReadTally {
 	// The first instant the window covers. A refusal recorded before it cannot be checked against a
 	// delegation any more, because the delegation that would re-arm it has scrolled out.
 	window_start_ms: number
+	// The search turns since the last delegation or successful write, and how many of them came after
+	// the instant asked about — the search-side `pending` / `pending_since` (joshuafolkken/kit#3139).
+	searches: number
+	searches_since: number
 	// The files this run has successfully edited within the window, resolved (joshuafolkken/kit#1840).
-	// A re-read of one of them is a read of a file the run edited, which §2b keeps in the main line — so
+	// A re-read of one of them is a read of a file the run edited, which `delegation.md` keeps in the main line — so
 	// it is excluded from the count and from a call's projected growth rather than counted as fresh
 	// investigation.
 	edited: ReadonlySet<string>
 }
 
-// **The run's own instructions are not the Issue's subject, so reading them is not what §2b delegates.**
+// **The run's own instructions are not the Issue's subject, so reading them is not what `delegation.md` delegates.**
 // #1426's rule is about reading to find out how the subject works; `CLAUDE.md`, a `prompts/` topic and
 // a skill file are read to find out what to *do*, they are read by nearly every run, and a unit cannot
 // be sent to read them on the main line's behalf. #1441's own measurement excluded 5 of them by hand
@@ -247,7 +264,7 @@ function is_failed_outcome(span: Span): boolean {
 
 // **Every file the run successfully wrote within the window, resolved** (joshuafolkken/kit#1840). It
 // is the one source of "this run edited that file", shared by the live tally and the replay: a read of
-// a file the run edits is reading §2b keeps in the main line, so it is never counted — whether the read
+// a file the run edits is reading `delegation.md` keeps in the main line, so it is never counted — whether the read
 // came before the edit or after it. A failed edit wrote nothing and so exempts nothing, and a file
 // edited outside the window is unknown rather than assumed: the set is only ever as wide as the tail
 // the hook read, which is the bound joshuafolkken/kit#1764 already holds the accumulation to.
@@ -279,18 +296,65 @@ function add_all(
 // the edit's own span, so a read issued *after* the edit was added and stayed. `sed -i`, `MultiEdit`
 // and `NotebookEdit` need no special case any more — each is a write, so its target is in `edited` and
 // never enters the read count.
-function apply_span(pending: Map<string, number>, span: Span, edited: ReadonlySet<string>): void {
+interface Accumulation {
+	// Read files, keyed by resolved path, valued by the instant each entered.
+	pending: Map<string, number>
+	// Search turns, keyed by message id so a turn's parallel searches count once, valued the same way.
+	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 belongs to no known turn, so it is a turn of its own** — the reading every
+// other turn counter gives `NO_MESSAGE_ID` (`time-round-trips.ts`, `time-bundles.ts`). Keyed by the
+// id, every untagged search would collapse into one entry and the count would never reach its threshold.
+function search_turn_key(searches: ReadonlyMap<string, number>, span: Span): string {
+	if (span.message_id !== time_spans.NO_MESSAGE_ID) return span.message_id
+
+	return `${time_spans.NO_MESSAGE_ID}#${String(searches.size)}`
+}
+
+// **A successful write ends the streak.** The measurement behind the threshold counted searches since
+// the last edit or delegation: a run that has started writing is implementing, and the searches that
+// follow locate the next edit rather than continue an investigation.
+//
+// **Every read-only search counts, whatever it names** (joshuafolkken/kit#3139). The file count can
+// exempt the run's own instructions because a read names each file it reads; a search does not — the
+// targets drop a bare directory, so `grep -rn foo CLAUDE.md scripts` looked like a search of
+// `CLAUDE.md` alone and an exemption let the whole sweep through. `is_bundleable` without `may_write`
+// is the read-only test `is_search_call` asks at the call, so the transcript never counts a search the
+// guard could not have refused.
+function apply_search(searches: Map<string, number>, span: Span): void {
+	if (span.is_writing) {
+		searches.clear()
+
+		return
+	}
+
+	const turn = search_turn_key(searches, span)
+
+	if (is_read_only_search(span) && !searches.has(turn)) searches.set(turn, span.ended_ms)
+}
+
+function apply_span(accumulation: Accumulation, span: Span, edited: ReadonlySet<string>): void {
 	if (DELEGATION_TOOLS.has(span.label)) {
-		pending.clear()
+		accumulation.pending.clear()
+		accumulation.searches.clear()
 
 		return
 	}
 
-	if (!is_content_read(span.label) || is_failed_outcome(span)) return
+	if (is_failed_outcome(span)) return
+
+	apply_search(accumulation.searches, span)
+
+	if (!is_content_read(span.label)) return
 
 	const fresh = subject_targets(span.targets).filter((target) => !edited.has(target))
 
-	add_all(pending, fresh, span.ended_ms)
+	add_all(accumulation.pending, fresh, span.ended_ms)
 }
 
 function last_delegation_ms(spans: ReadonlyArray<Span>): number {
@@ -307,15 +371,17 @@ function pending_after(pending: ReadonlyMap<string, number>, since_ms: number):
 function tally_of(text: string, since_ms: number = hook_decision.NEVER_MS): ReadTally {
 	const { spans, started_ms } = time_spans.parse_timeline(text)
 	const edited = edited_files(spans)
-	const pending = new Map<string, number>()
+	const accumulation: Accumulation = { pending: new Map(), searches: new Map() }
 
-	for (const span of spans) apply_span(pending, span, edited)
+	for (const span of spans) apply_span(accumulation, span, edited)
 
 	return {
-		pending: [...pending.keys()],
-		pending_since: pending_after(pending, since_ms),
+		pending: [...accumulation.pending.keys()],
+		pending_since: pending_after(accumulation.pending, since_ms),
 		reset_ms: last_delegation_ms(spans),
 		window_start_ms: started_ms,
+		searches: accumulation.searches.size,
+		searches_since: pending_after(accumulation.searches, since_ms),
 		edited,
 	}
 }
@@ -347,6 +413,11 @@ function is_at_threshold(pending_count: number): boolean {
 	return pending_count + 1 >= delegation_policy.INVESTIGATION_FILE_THRESHOLD
 }
 
+// The search turn that takes the count up to its threshold is the boundary, as above.
+function is_at_search_threshold(search_count: number): boolean {
+	return search_count + 1 >= delegation_policy.INVESTIGATION_SEARCH_TURN_THRESHOLD
+}
+
 // **One refusal per accumulation, re-armed by a delegation and by nothing else.** A run that reads on
 // regardless is not refused again, so a false positive — three files the run was about to edit — costs
 // one round trip rather than wedging the run. And a run that *does* delegate is refused again as soon
@@ -373,7 +444,7 @@ function is_at_threshold(pending_count: number): boolean {
 //
 // **A delegated unit is not re-armed here because it is not refused at all** (joshuafolkken/kit#1840).
 // The hook counts a unit's reading against the unit (joshuafolkken/kit#1424), and the refusal asks for
-// a dispatch — but a unit is already where §2b sends the reading, and a read-only one (`Explore`,
+// a dispatch — but a unit is already where `delegation.md` sends the reading, and a read-only one (`Explore`,
 // `Plan`) has no `Agent` tool to dispatch with. It was formerly degraded to a single first refusal,
 // which still asked for an action the unit could not take; now the unit short circuit in `should_block`
 // turns it off entirely, so this function is the parent's alone and needs no delegation condition.
@@ -386,7 +457,7 @@ function is_rearmed(tally: ReadTally, refused_at_ms: number): boolean {
 		return true
 	}
 
-	return is_at_threshold(tally.pending_since)
+	return is_at_threshold(tally.pending_since) || is_at_search_threshold(tally.searches_since)
 }
 
 // A transcript under a session's `subagents/` directory is a delegated unit's. The segment is
@@ -403,10 +474,19 @@ function is_unit_run(run: GuardRun | undefined): boolean {
 	return run !== undefined && is_unit_transcript(run.transcript)
 }
 
-function is_refusable_command(call: GuardedCall): boolean {
+function is_read_only_command(call: GuardedCall, labels: ReadonlySet<string>): boolean {
+	if (call.name !== cost_blocks.BASH_TOOL) return false
+
 	const label = time_shell.bash_label(time_shell.bash_command(call.input))
 
-	return CONTENT_READ_LABELS.has(label) && time_batch_guard.is_read_only_call(call)
+	return labels.has(label) && time_batch_guard.is_read_only_call(call)
+}
+
+// **A search is refusable without a subject target**, unlike a read: `grep -rn foo scripts` names a
+// bare directory, which `call_facts` deliberately does not take as a target, and such a sweep is exactly
+// the search this count exists for.
+function is_search_call(call: GuardedCall): boolean {
+	return is_read_only_command(call, SEARCH_LABELS)
 }
 
 // **A `Read` is always safe to refuse; a `Bash` line is refused only where it writes nothing.** This
@@ -427,10 +507,20 @@ function is_refusable_command(call: GuardedCall): boolean {
 // rule being enforced — and a call whose targets could not be read at all, which cannot move the count
 // and so has nothing to be refused for.
 function is_refusable_call(call: GuardedCall): boolean {
+	if (is_search_call(call)) return true
 	if (call_targets(call).length === 0) return false
 	if (READ_TOOLS.has(call.name)) return true
 
-	return call.name === cost_blocks.BASH_TOOL && is_refusable_command(call)
+	return is_read_only_command(call, CONTENT_READ_LABELS)
+}
+
+// A search call grows the search count by its own turn; a read grows the file count only by a file the
+// count does not already hold.
+function is_growing_past_threshold(tally: ReadTally, call: GuardedCall): boolean {
+	if (is_search_call(call)) return is_at_search_threshold(tally.searches)
+	if (!is_at_threshold(tally.pending.length)) return false
+
+	return projected_count(tally.pending, call, tally.edited) > tally.pending.length
 }
 
 function should_block(
@@ -446,15 +536,11 @@ function should_block(
 
 	const tally = tally_of(text, refused_at_ms)
 
-	if (!is_at_threshold(tally.pending.length)) return false
-
-	return (
-		projected_count(tally.pending, call, tally.edited) > tally.pending.length &&
-		is_rearmed(tally, refused_at_ms)
-	)
+	return is_growing_past_threshold(tally, call) && is_rearmed(tally, refused_at_ms)
 }
 
 const investigation_reads = {
+	INVESTIGATOR_AGENT,
 	READ_TOOLS,
 	REASON,
 	is_at_threshold,

package/scripts/discovery/repo-discovery.ts

@@ -59,22 +59,35 @@ function resolve_git_directory(repository_path: string): string | undefined {
 	}
 }
 
-// The `origin` URL a work tree declares, or nothing when it has no `origin`, no readable config, or
-// is not a work tree at all. Every failure reads as "no remote" so one unreadable sibling cannot
-// fail a command whose contract is to report what it could find.
-function read_origin_url(repository_path: string): string | undefined {
+// The work tree's git config text, or nothing when it is unreadable or not a work tree.
+function read_config(repository_path: string): string | undefined {
 	const git_directory = resolve_git_directory(repository_path)
 	if (git_directory === undefined) return undefined
 
 	try {
-		return repo_origin.parse_origin_from_config(
-			readFileSync(path.join(git_directory, GIT_CONFIG), 'utf8'),
-		)
+		return readFileSync(path.join(git_directory, GIT_CONFIG), 'utf8')
 	} catch {
 		return undefined
 	}
 }
 
+// The `origin` URL a work tree declares, or nothing when it has no `origin`, no readable config, or
+// is not a work tree at all. Every failure reads as "no remote" so one unreadable sibling cannot
+// fail a command whose contract is to report what it could find.
+function read_origin_url(repository_path: string): string | undefined {
+	const config = read_config(repository_path)
+
+	return config === undefined ? undefined : repo_origin.parse_origin_from_config(config)
+}
+
+// The `url` of every remote the work tree declares, with the same "unreadable reads as none" contract
+// as `read_origin_url`.
+function read_remote_urls(repository_path: string): Array<string> {
+	const config = read_config(repository_path)
+
+	return config === undefined ? [] : repo_origin.parse_remote_urls_from_config(config)
+}
+
 // Every immediate child directory of `parent`, in name order. An unreadable parent yields nothing
 // rather than throwing: `josh doctor` reports what it could find, and a permission error on the
 // parent is not a broken install.
@@ -158,6 +171,7 @@ const repo_discovery = {
 	OVERRIDE_ENV_KEY,
 	main_worktree,
 	read_origin_url,
+	read_remote_urls,
 	resolve_current_owner,
 	scan_siblings,
 	discover_repositories,

package/scripts/discovery/repo-origin.ts

@@ -26,6 +26,7 @@ const REPO_PATH_SEGMENTS = 2
 const NOT_FOUND = -1
 const SECTION_PREFIX = '['
 const ORIGIN_SECTION = /^\[remote\s+"origin"\]$/u
+const REMOTE_SECTION = /^\[remote\s+"[^"]+"\]$/u
 const URL_KEY = 'url'
 
 // Whether a URL's hostname is GitHub. Exact, with no alias spelling accepted: an alias is a name
@@ -132,6 +133,30 @@ function parse_origin_from_config(content: string): string | undefined {
 		.find((url) => url !== undefined)
 }
 
+// The config's lines grouped by section, each group led by its header. Lines before the first header
+// belong to no section and are dropped.
+function section_groups(lines: ReadonlyArray<string>): Array<Array<string>> {
+	const groups: Array<Array<string>> = []
+
+	for (const line of lines) {
+		if (is_section_header(line)) groups.push([line])
+		else groups.at(-1)?.push(line)
+	}
+
+	return groups
+}
+
+// The `url` of every `[remote "…"]` section, in config order — the candidates `gh` picks its base
+// repository from when it expands the `{owner}` placeholder (joshuafolkken/kit#3188).
+function parse_remote_urls_from_config(content: string): Array<string> {
+	const lines = content.split('\n').map((line) => line.trim())
+
+	return section_groups(lines)
+		.filter((group) => REMOTE_SECTION.test(group[0] ?? ''))
+		.flatMap((group) => group.map((line) => entry_value(line, URL_KEY)))
+		.filter((url) => url !== undefined)
+}
+
 // The `owner/repo` key a discovery map is keyed by. Lowercased, because GitHub resolves owner and
 // repository names case-insensitively: two remotes spelling the same repository differently are the
 // same repository, and keying by the spelling would put both in the map — where an override, which
@@ -146,6 +171,7 @@ const repo_origin = {
 	is_github_ssh_host,
 	parse_origin_from_config,
 	parse_origin_url,
+	parse_remote_urls_from_config,
 	format_identity,
 }
 

package/scripts/discovery/repo-party.ts

@@ -16,6 +16,8 @@ type Party = 'first-party' | 'third-party' | 'unknown'
 const FIRST_PARTY: Party = 'first-party'
 const THIRD_PARTY: Party = 'third-party'
 const UNKNOWN: Party = 'unknown'
+const GH_REPO_ENV_KEY = 'GH_REPO'
+const GH_REPO_PATH_SEGMENTS = 2
 
 // `unknown` is not `third-party`. An owner that cannot be read — no `origin`, an unreadable config —
 // is a "cannot decide", and reading it as third-party would refuse first-party writes whenever the
@@ -40,7 +42,46 @@ function current_owner(repository_path: string = process.cwd()): string | undefi
 	return repo_discovery.resolve_current_owner(repository_path)
 }
 
-const repo_party = { FIRST_PARTY, THIRD_PARTY, UNKNOWN, classify, current_owner, target_owner }
+// 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('/'))]
+}
+
+// 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> {
+	return repo_discovery
+		.read_remote_urls(repository_path)
+		.map((url) => repo_origin.parse_origin_url(url)?.owner)
+}
+
+// Every owner `gh` could expand the `{owner}` placeholder to (joshuafolkken/kit#3188). `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
+// 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.
+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 gh_repo === undefined || gh_repo === ''
+		? remote_owners(repository_path)
+		: gh_repo_owners(gh_repo)
+}
+
+const repo_party = {
+	FIRST_PARTY,
+	THIRD_PARTY,
+	UNKNOWN,
+	classify,
+	current_owner,
+	placeholder_owners,
+	target_owner,
+}
 
 export type { Party }
 export { repo_party }

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

@@ -8,25 +8,19 @@
 // (`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.
+// paragraph is the parent's own), which the worker drops. **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).
+// **The `SKILL.md` sections the `backlogrun` parent never uses.** It edits no rule mid-run (§3, read
+// only on an editing turn). The implementer-only rules it used to skip — the `into` target, the
+// working-tree hold, the Issue's comments — are single rows of §2's table since joshuafolkken/kit#3174,
+// so there is no section of them left to trim.
 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',
 ]
 
@@ -34,10 +28,15 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // 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>()
 
-// **The parent runs the end-of-run retrospective** (`SKILL.md` §2j) when `run:step` prints it, but its
+// **The parent runs the end-of-run retrospective** (`retrospective.md`) when `run:step` prints it, but its
 // manifest names `retrospective.md` only through `backlogrun-steps.md` — one hop further than the
-// derivation follows — so the parent's reach names it (joshuafolkken/kit#3078).
-const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['retrospective.md'])
+// derivation follows — so the parent's reach names it (joshuafolkken/kit#3078). **It polls a
+// delegated unit that went silent** through `backlogrun-recovery.md`, named only from
+// `backlogrun-child.md`, so the reach names that too (joshuafolkken/kit#3175).
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set([
+	'retrospective.md',
+	'backlogrun-recovery.md',
+])
 
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {

package/scripts/document/capped-print.ts

@@ -0,0 +1,74 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { review_diff_parts } from '#scripts/review/review-diff-parts'
+import { bash_output_cap_reader } from './bash-output-cap'
+
+// Prints a command's output whole when it fits under the Bash output cap, and as part files when it
+// does not (joshuafolkken/kit#3143). Past `BASH_MAX_OUTPUT_LENGTH` Claude Code saves the output and
+// hands back a 2 KB preview, and the run spends a turn reading the saved file — 224 overflows and 132
+// re-reads over one day's sessions, `doc:section` and `issue:read` the two most frequent `josh` sources.
+//
+// **The cut is #2963's, not a second one.** The parts come from `review_diff_parts.part_texts`, so each
+// file — header included — fits under the cap and the bodies concatenate back to exactly the output.
+// A reader opens them all with the Read tool in one turn, which is the turn the preview used to cost.
+//
+// **A fresh directory per call**, unlike the review's per-checkout one: a run fetches several sections
+// in one turn, and a shared directory replaced on every call would delete one call's parts while
+// another call's listing still names them.
+
+const DIRECTORY_PREFIX = 'josh-capped-print-'
+const FILE_MODE = 0o600
+const PART_SUFFIX = '.md'
+const LINE_BREAK = '\n'
+// What else shares the Bash result with this output: the launcher line, a script banner, a few
+// stderr lines. Measured at about 80 characters for `pnpm josh doc:section` in kit, so 512 holds the
+// longest heading or issue list with room for a consumer's banner.
+const HEADROOM_CHARS = 512
+
+function write_parts(label: string, text: string, cap: number): Array<string> {
+	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, DIRECTORY_PREFIX))
+
+	return review_diff_parts.part_texts(label, text, cap).map((part, index) => {
+		const file = path.join(directory, `part-${String(index + 1)}${PART_SUFFIX}`)
+
+		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
+
+		return file
+	})
+}
+
+function part_count(count: number): string {
+	return `written as ${String(count)} part file${count === 1 ? '' : 's'} under it`
+}
+
+function listing(text: string, cap: number, files: ReadonlyArray<string>): string {
+	const figures = `${text.length.toLocaleString('en-US')} > ${cap.toLocaleString('en-US')} characters`
+	const lead = `Over the Bash cap (${figures}) — ${part_count(files.length)}, together exactly the output. Read every part with the Read tool, in one turn, not cat:`
+
+	return [lead, ...files.map((file) => `  ${file}`)].join(LINE_BREAK)
+}
+
+// **The budget is the cap less a headroom, not the cap.** The Bash result carries more than this
+// output — `pnpm josh`'s own launcher line, a consumer's script banner, the stderr lines naming a
+// number that did not resolve — so a text measured against the bare cap would overflow by exactly
+// those lines, and cost the re-read this module exists to remove.
+function output_budget(root: string): number {
+	return Math.max(1, bash_output_cap_reader.bash_output_cap(root) - HEADROOM_CHARS)
+}
+
+function capped_print(text: string, label: string, root: string = process.cwd()): void {
+	const budget = output_budget(root)
+
+	if (text.length < budget) {
+		console.info(text)
+
+		return
+	}
+
+	console.info(listing(text, budget, write_parts(label, text, budget)))
+}
+
+const capped_output = { HEADROOM_CHARS, capped_print }
+
+export { capped_output }

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

@@ -65,15 +65,19 @@ function block_ceiling(size: number): number {
 // 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: 36_864 },
+	// joshuafolkken/kit#3173 split the waves and the `epic:bundle` detail into lazily read references.
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 20_480 },
+	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 12_288 },
+	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 12_288 },
 	{ 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: 24_576 },
+	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 12_288 },
+	// joshuafolkken/kit#3176 moved the ledger out of `observation-filing.md`, read only when it appends.
+	{ path: '.claude/skills/workflow-commands/observation-ledger.md', bytes: 12_288 },
 	// `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
@@ -82,34 +86,44 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
-	{ path: 'docs/josh-commands-automation.md', bytes: 155_648 },
+	// joshuafolkken/kit#3175 raised it: the supervisor, provider-table and answer-to-budget prose moved
+	// here out of `backlogrun-steps.md`, so a run reads it only when it asks about those commands.
+	{ path: 'docs/josh-commands-automation.md', bytes: 159_744 },
 	{ path: 'docs/josh-commands.md', bytes: 36_864 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 8192 },
-	// #2662 adds the feature and compatibility declarations to the canonical filing procedure.
-	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 16_384 },
-	{ 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/issue-citation.md', bytes: 4096 },
+	// #3178 left the template and the judgement tables; the epic commands moved to `epic-commands`, the by-hand fallback stayed.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 8192 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 12_288 },
+	// #3177 moved the rationale to `docs/maintainers/output-bounds-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 4096 },
+	// #3178 replaced the review-chain restatement with a pointer to `chain-rule.md`.
+	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/principles.md', bytes: 12_288 },
 	{ 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: 28_672 },
-	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 45_056 },
-	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 20_480 },
+	// #3178 dropped the restatements `report:lint` and `chain-rule.md` already carry.
+	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 16_384 },
+	// #3177 cut it to the four questions; the history and lists moved to `docs/maintainers/residency-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 8192 },
+	// #3186 moved the hook wiring and history to `docs/maintainers/rule-delivery-rationale.md`;
+	// #3179 adds the `index-mutation` / `destructive-command` / `protected-file` entries.
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 8192 },
+	// #3177 moved the measurements and rejected mechanisms to `docs/maintainers/turn-batching-rationale.md`.
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 16_384 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 12_288 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
-	{ path: 'prompts/review-rubric.md', bytes: 20_480 },
-	{ path: 'prompts/review.md', bytes: 20_480 },
+	// #3180 moved the history and the lint-settled proofs to `docs/maintainers/`.
+	{ path: 'prompts/review-rubric.md', bytes: 16_384 },
+	{ path: 'prompts/review.md', bytes: 16_384 },
 	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
-	{ path: 'prompts/testing-guide.md', bytes: 24_576 },
+	{ path: 'prompts/testing-guide.md', bytes: 20_480 },
 ]
 
 // The recorded ceiling for one path, or undefined when it carries no budget entry.

package/scripts/document/document-section-cli.ts

@@ -2,6 +2,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { capped_output } from './capped-print'
 import { document_section } from './document-section'
 import { entry_read_set } from './entry-read-set'
 
@@ -56,12 +57,12 @@ function report_missing(markdown: string, heading: string): number {
 	return FAILURE_EXIT_CODE
 }
 
-function print_section(markdown: string, heading: string): number {
+function print_section(markdown: string, heading: string, root: string): number {
 	const found = document_section.section(markdown, heading)
 
 	if (found === undefined) return report_missing(markdown, heading)
 
-	console.info(found.text)
+	capped_output.capped_print(found.text, heading, root)
 
 	return 0
 }
@@ -87,7 +88,7 @@ function run(argv: ReadonlyArray<string>, root: string = process.cwd()): number
 
 	const markdown = read_named(name, root)
 
-	return markdown === undefined ? FAILURE_EXIT_CODE : print_section(markdown, heading)
+	return markdown === undefined ? FAILURE_EXIT_CODE : print_section(markdown, heading, root)
 }
 
 function main(argv: ReadonlyArray<string>): void {