@joshuafolkken/kit 1.1094.0 → 1.1136.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/SKILL.md\` → §2b, "The pre-implementation reading".`
 
 interface ReadTally {
 	// The files read and not since edited, resolved so the two ways a target reaches here compare.
@@ -74,6 +87,10 @@ 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
 	// it is excluded from the count and from a call's projected growth rather than counted as fresh
@@ -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
@@ -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/doctor/doctor-consumer.ts

@@ -1,10 +1,9 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
-import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
-import { execaSync } from 'execa'
 import { z } from 'zod'
 
 // The consumer-setup checks `josh doctor` runs in a repository that installs kit (joshuafolkken/kit#1930).
@@ -77,11 +76,9 @@ function is_plugin_declared(root: string): boolean {
 // The value of `core.hooksPath`, or undefined when it is unset. A set value is what stops lefthook
 // from installing kit's git hooks — the failure is silent but for one stderr line.
 function configured_hooks_path(root: string): string | undefined {
-	const result = execaSync('git', ['-C', root, 'config', '--get', 'core.hooksPath'], {
-		reject: false,
+	const value = git_spawn_sync.read(['-C', root, 'config', '--get', 'core.hooksPath'], {
 		timeout: GIT_TIMEOUT_MS,
 	})
-	const value = read_spawn_stdout(result).trim()
 
 	return value === '' ? undefined : value
 }
@@ -159,6 +156,7 @@ function report_consumer_setup(root: string): void {
 const doctor_consumer = {
 	claude_md_line,
 	claude_md_state,
+	configured_hooks_path,
 	hooks_path_line,
 	is_kit_consumer,
 	is_plugin_declared,

package/scripts/doctor/doctor-io.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
-import { read_spawn_stderr, read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
@@ -69,18 +70,13 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 // caller's check, because reporting an unknown as a clean result is the false all-clear
 // joshuafolkken/kit#805 exists to remove. See the two classifiers above for what proves what.
 function resolve_git_top_level(): GitTopLevel {
-	const result = execaSync('git', ['rev-parse', '--show-toplevel'], {
-		reject: false,
-		timeout: GIT_TIMEOUT_MS,
-		// git translates its messages, so the match below would fail under any non-English locale and
-		// the spurious warning would come back. `C` pins the output this code was written against.
-		env: { LC_ALL: 'C', LANGUAGE: 'C' },
-		extendEnv: true,
-	})
-
-	if (result.exitCode === 0) return classify_top_level(read_spawn_stdout(result).trim())
-
-	return classify_git_failure(result.exitCode, read_spawn_stderr(result))
+	// The C locale `toplevel` asks under is what keeps the stderr match below from failing on a
+	// translated message and bringing the spurious warning back.
+	const result = git_spawn_sync.toplevel(GIT_TIMEOUT_MS)
+
+	if (result.exit_code === 0) return classify_top_level(result.stdout.trim())
+
+	return classify_git_failure(result.exit_code, result.stderr)
 }
 
 // Whether one line is the setting itself rather than prose about it. kit's own template explains the

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

@@ -34,15 +34,26 @@ 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
+// 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'])
+
 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,
+		reached_point_of_use: REACHED_POINT_OF_USE,
 	})
 }
 
-const backlogrun_parent_read_set = { BACKLOGRUN, UNUSED_SKILL_SECTIONS, costed }
+const backlogrun_parent_read_set = {
+	BACKLOGRUN,
+	REACHED_POINT_OF_USE,
+	UNUSED_SKILL_SECTIONS,
+	costed,
+}
 
 export { backlogrun_parent_read_set }

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

@@ -88,6 +88,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ 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 },

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 {

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

@@ -3,8 +3,9 @@
 //
 // **The per-document ceiling was a proxy for a run's cost, not the cost.** A run does not pay "one
 // document's size"; it pays the total its entry reads — the mandated skill files, the sections they
-// point out to, the point-of-use documents reached later, and the resident `CLAUDE.md` every request
-// carries. `read:set` already computes that total, so this budgets it directly: the entry total is
+// point out to, the point-of-use documents that entry reaches later, and the resident `CLAUDE.md` every
+// request carries. `read:set`'s `total read` is that sum less `CLAUDE.md`, which `entry_total_bytes`
+// adds back (`RESIDENT_BASE`), so this budgets the whole directly: the entry total is
 // the primary ceiling, and the per-document ceiling (`document-byte-budget.ts`) falls back to the
 // documents no entry reads (`document-reachability.ts` draws the line). A document an entry reads is
 // held by the entry total and carries no per-document ceiling, so neither budget holds it twice.
@@ -86,11 +87,16 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// `wip-cap.md`, so its ceiling stays.
 	// joshuafolkken/kit#3023 added the `prrun` keyword to `SKILL.md` and `CLAUDE.md`, tipping backlogrun
 	// one block over; `prrun` reads `fullrun`'s set plus its own short manifest.
-	{ entry: 'kickoff', bytes: 229_376 },
-	{ entry: 'fullrun', bytes: 225_280 },
-	{ entry: 'halfrun', bytes: 225_280 },
-	{ entry: 'prrun', bytes: 229_376 },
-	{ entry: 'backlogrun', bytes: 233_472 },
+	// Lowered in joshuafolkken/kit#3078 — a correction of an over-count, not a trim: every entry was
+	// charged for every global point-of-use document, so `kickoff` paid for `followup.md` and the
+	// `backlogrun-*` phase documents it never opens. Each total now counts only what its path reaches.
+	// joshuafolkken/kit#3077 trimmed non-resident rule bodies from `CLAUDE.md`, lowering fullrun, prrun
+	// and backlogrun one block each.
+	{ entry: 'kickoff', bytes: 65_536 },
+	{ entry: 'fullrun', bytes: 126_976 },
+	{ entry: 'halfrun', bytes: 106_496 },
+	{ entry: 'prrun', bytes: 131_072 },
+	{ entry: 'backlogrun', bytes: 212_992 },
 	{ entry: LANE_CHILD, bytes: 77_824 },
 ]
 

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

@@ -420,16 +420,40 @@ function point_of_use_cost(
 	return { file, heading: '', cost: cost_of(read_document(root, file)), is_resolved: true }
 }
 
-function point_of_use_costs(root: string, entry: string): Array<SectionCost> {
-	const found = document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)
-	const references = all_matches(found?.text ?? '', SECTION_REFERENCE).map((match) =>
-		to_reference(match),
-	)
+// **What an entry's path names: its own manifests, and the §1 trigger rows that name the entry**
+// (joshuafolkken/kit#3078). `SKILL.md`'s other text is left out for the reason `sections_for` gives —
+// §2 names every document, so counting it would charge a `kickoff` for `followup.md`. One hop only:
+// the point-of-use documents cite one another, and following them would reach the whole set again.
+// `also` is what a role reaches beside its base entry's path (`read-set-trim.ts`).
+function cited_by(
+	root: string,
+	entry: string,
+	table_text: string,
+	also: ReadonlySet<string>,
+): Set<string> {
+	const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE)
+	const rows = table_text
+		.split('\n')
+		.filter((line) => line.startsWith('|') && line.includes(`\`${entry}\``))
+	const texts = [...manifests.map((file) => read_document(root, file)), ...rows]
+
+	return new Set([...also, ...texts.flatMap((text) => names_in(text))])
+}
+
+function point_of_use_costs(
+	root: string,
+	entry: string,
+	also: ReadonlySet<string>,
+): Array<SectionCost> {
+	const table_text =
+		document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)?.text ?? ''
+	const references = all_matches(table_text, SECTION_REFERENCE).map((match) => to_reference(match))
+	const cited = cited_by(root, entry, table_text, also)
 
-	return point_of_use_files(entry).map((file) => point_of_use_cost(root, file, references))
+	return point_of_use_files(entry, cited).map((file) => point_of_use_cost(root, file, references))
 }
 
-function costed(root: string, entry: string): ReadSetCost {
+function costed(root: string, entry: string, also: ReadonlySet<string> = new Set()): ReadSetCost {
 	const { files, sections } = read_set(root, entry)
 	const own_costs = file_costs(root, files)
 	const section_costs = sections.map((reference) => section_cost(root, reference))
@@ -439,7 +463,7 @@ function costed(root: string, entry: string): ReadSetCost {
 		entry,
 		files: own_costs,
 		sections: section_costs,
-		point_of_use: point_of_use_costs(root, entry),
+		point_of_use: point_of_use_costs(root, entry, also),
 		bash_output_cap: bash_output_cap_reader.bash_output_cap(root),
 		whole: total([own, referenced_cost(root, sections)]),
 		scoped: total([own, scoped_cost(root, sections)]),

package/scripts/document/lane-child-read-set.ts

@@ -64,17 +64,24 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'retrospective.md',
 ])
 
+// **A child that parks reads `backlogrun-park.md`** (`SKILL.md` §1, "A lane child that parks"), a
+// document a standalone `fullrun`'s path never names — so the child's reach adds it to its base
+// entry's (joshuafolkken/kit#3078).
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md'])
+
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {
 		base_entry: FULLRUN,
 		label: LANE_CHILD,
 		unused_skill_sections: UNUSED_SKILL_SECTIONS,
 		skipped_point_of_use: SKIPPED_POINT_OF_USE,
+		reached_point_of_use: REACHED_POINT_OF_USE,
 	})
 }
 
 const lane_child_read_set = {
 	LANE_CHILD,
+	REACHED_POINT_OF_USE,
 	SKIPPED_POINT_OF_USE,
 	UNUSED_SKILL_SECTIONS,
 	costed,

package/scripts/document/read-set-point-of-use.ts

@@ -75,9 +75,14 @@ function is_point_of_use(entry: string, file: string): boolean {
 	return (POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES).has(file)
 }
 
-// The global point-of-use files plus the ones this entry names in its own row.
-function point_of_use_files(entry: string): Array<string> {
-	return [...POINT_OF_USE_FILES, ...(POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES)]
+// **Only the global files the entry reaches, plus the ones this entry names in its own row**
+// (joshuafolkken/kit#3078). `cited` is every document the entry's path names; a global file outside it
+// is one this entry never opens — a `kickoff` never issues `followup` — so charging it made every
+// entry's total the same figure and the per-entry ratchet measured nothing.
+function point_of_use_files(entry: string, cited: ReadonlySet<string>): Array<string> {
+	const reached = [...POINT_OF_USE_FILES].filter((file) => cited.has(file))
+
+	return [...reached, ...(POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES)]
 }
 
 const read_set_point_of_use = {

package/scripts/document/read-set-trim.ts

@@ -24,6 +24,8 @@ interface TrimSpec {
 	unused_skill_sections: ReadonlyArray<string>
 	// The point-of-use documents this role's parent owns; empty when the role owns them all.
 	skipped_point_of_use: ReadonlySet<string>
+	// The point-of-use documents this role reaches that its base entry's path does not name.
+	reached_point_of_use: ReadonlySet<string>
 }
 
 function subtract(left: Cost, right: Cost): Cost {
@@ -59,7 +61,7 @@ function reduce_skill(file: FileCost, saving: Cost): FileCost {
 // **`whole` and `scoped` both carry the own-files cost identically**, so the `SKILL.md` saving lands
 // on each by the same amount — there is no need to re-derive the referenced-section split.
 function costed(root: string, spec: TrimSpec): ReadSetCost {
-	const base = entry_read_set.costed(root, spec.base_entry)
+	const base = entry_read_set.costed(root, spec.base_entry, spec.reached_point_of_use)
 	const saving = unused_skill_cost(root, spec.unused_skill_sections)
 
 	return {

package/scripts/epic/epic-audit.ts

@@ -1,3 +1,4 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 
 // Reading an epic's children against each other.
@@ -43,7 +44,6 @@ const ACCEPTANCE_HEADINGS: ReadonlySet<string> = new Set([
 	'## 受け入れ条件',
 	'## Acceptance criteria',
 ])
-const HEADING_PREFIX = '## '
 
 type FindingLevel = 'error' | 'warning'
 
@@ -169,26 +169,11 @@ function is_acceptance_heading(line: string): boolean {
 	return ACCEPTANCE_HEADINGS.has(line.trim())
 }
 
-function is_heading(line: string): boolean {
-	return line.trimStart().startsWith(HEADING_PREFIX)
-}
-
-// The lines under the acceptance-criteria heading, up to the next `##`. Shaped like the other
-// section readers in this repository, for the same reason: a regex spanning the block backtracks.
-function section_lines(lines: ReadonlyArray<string>): Array<string> {
-	const start = lines.findIndex((line) => is_acceptance_heading(line))
-	if (start === -1) return []
-	const rest = lines.slice(start + 1)
-	const end = rest.findIndex((line) => is_heading(line))
-
-	return end === -1 ? rest : rest.slice(0, end)
-}
-
-// The acceptance-criteria section of a child's body, or an empty string.
+// The acceptance-criteria section of a child's body, up to the next unfenced `##`, or an empty string.
 function acceptance_section(body: string | undefined): string {
 	if (body === undefined) return ''
 
-	return section_lines(body.split('\n')).join('\n')
+	return markdown_section.section_lines_matching(body, is_acceptance_heading).join('\n')
 }
 
 // Everything `node` depends on, directly or through a chain. Walked iteratively so a graph that