@joshuafolkken/kit 1.1136.0 → 1.1166.0

package/scripts/agent/codex-hooks.ts

@@ -33,22 +33,13 @@ const UNMATCHED_EVENTS: ReadonlySet<string> = new Set(['UserPromptSubmit'])
 const JSON_INDENT = '\t'
 
 function adapter_command(mode: string): string {
-	return hook_launch.bundle_launch_command(
-		`codex-hook-adapter.js ${mode}`,
-		`pnpm exec tsx scripts/hooks/codex-hook-adapter.ts ${mode}`,
-	)
+	return hook_launch.hook_launch_command(`codex-hook-adapter ${mode}`)
 }
 
 // Each Claude-side guard command the adapter stands in for, keyed by that command verbatim.
 const ADAPTED_COMMANDS: ReadonlyMap<string, string> = new Map([
-	[
-		hook_launch.hook_launch_command('pretool-guard.js', 'pretool:guard'),
-		adapter_command('pretool'),
-	],
-	[
-		hook_launch.hook_launch_command('format-edited.js', 'format:edited'),
-		adapter_command('posttool'),
-	],
+	[hook_launch.hook_launch_command('pretool-guard'), adapter_command('pretool')],
+	[hook_launch.hook_launch_command('format-edited'), adapter_command('posttool')],
 ])
 
 function codex_handler(handler: HookHandler): HookHandler {

package/scripts/backlog/backlog-budget.ts

@@ -59,7 +59,7 @@ type BudgetVerdict =
 	typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT | typeof TRIAGE_VERDICT
 
 // What `backlog:next` answered, in the words this decision needs. The mapping is mechanical and is
-// written once, in `backlogrun-steps.md` → "The loop": numbers are `candidates`, `wait` is `blocked` while
+// written once, in `docs/josh-commands-automation.md` → "`josh backlog:offer`": numbers are `candidates`, `wait` is `blocked` while
 // this run has children in flight and `exhausted` when it does not, `none` is `exhausted`, `stop` is
 // `parked`, `triage` is `untriaged`, and `error` or a failed listing is `unreadable`.
 const ANSWERS = ['blocked', 'candidates', 'exhausted', 'parked', 'unreadable', 'untriaged'] as const

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
-import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
@@ -217,7 +216,8 @@ function merge_token(out: string, code: number): string {
 }
 
 // The child's transcript, where its lane recorded one, so `run:merge` can tell an API outage from a
-// failure exactly as it does for the parent that passes `--output` by hand.
+// failure exactly as it does for the parent that passes `--output` by hand. No hand-off threshold: the
+// supervisor runs this loop, and a process has no context to cut (joshuafolkken/kit#3156).
 async function merge(issue: string, owner: string): Promise<MergeResult> {
 	await backlog_drive_owner.assert_current(owner)
 	const lane = await lane_registry.find_open_lane(issue)
@@ -225,7 +225,7 @@ async function merge(issue: string, owner: string): Promise<MergeResult> {
 		child: issue,
 		epic: undefined,
 		repo: undefined,
-		over: CONTEXT_CUT_THRESHOLD,
+		over: undefined,
 		owner: run_carry.owner_of(Number(owner)),
 		output: lane?.output,
 	})
@@ -381,6 +381,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const backlog_drive_cli = {
 	end_line,
 	finish: backlog_drive_finish.finish,
+	merge,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
 	parse,

package/scripts/backlog/backlog-drive-offer-argv.ts

@@ -3,11 +3,20 @@ import type { DriveState } from './backlog-drive'
 
 const LIST_SEPARATOR = ','
 
+// **A child in flight is never offered** (joshuafolkken/kit#3156). A lane child merges its own PR and
+// drops `in-progress` before GitHub closes the issue and before the loop collects it, so `backlog:next`
+// can offer it again; launching it then is refused by its still-open lane and handed to an AI session.
+function excluded(state: DriveState): ReadonlyArray<string> {
+	return [...new Set([...state.exclude, ...state.in_flight])]
+}
+
 function offer_argv(
 	state: DriveState,
 	carry: RunCarry,
 	forwarded: ReadonlyArray<string>,
 ): ReadonlyArray<string> {
+	const exclude = excluded(state)
+
 	return [
 		'backlog:offer',
 		'--json',
@@ -21,7 +30,7 @@ function offer_argv(
 		String(state.in_flight.length),
 		'--retries',
 		String(state.retries),
-		...(state.exclude.length === 0 ? [] : ['--exclude', state.exclude.join(LIST_SEPARATOR)]),
+		...(exclude.length === 0 ? [] : ['--exclude', exclude.join(LIST_SEPARATOR)]),
 		...forwarded,
 	]
 }

package/scripts/backlog/backlog-offer.ts

@@ -5,15 +5,15 @@ import { backlog_next } from './backlog-next'
 // answered — its stdout tokens and its exit code — into the one word `backlog:budget` is then asked
 // with, plus the issue numbers to start and the consecutive-retry count carried to the next ask.
 //
-// **The mapping is `backlogrun-steps.md` → "The loop"'s table, held here so it cannot drift.** That table
-// fixed which `backlog:next` answer becomes which `backlog:budget` word, and it carried two context
-// branches an agent had to apply by hand every iteration: `wait` is `blocked` while this run has
-// children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third
+// **The mapping is `docs/josh-commands-automation.md` → "`josh backlog:offer`", held here so it cannot
+// drift.** It fixes which `backlog:next` answer becomes which `backlog:budget` word, and it carries two
+// context branches an agent once applied by hand every iteration: `wait` is `blocked` while this run
+// has children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third
 // consecutive one, which is `unreadable`. Both are decided from a count here rather than from a
-// judgement.
+// judgement (joshuafolkken/kit#3175 dropped the prose copy from `backlogrun-steps.md`).
 
 // Three consecutive `retry` answers end the run: below that a transport hiccup is re-asked, at it the
-// outage is not a hiccup. `backlogrun-steps.md` → "The loop" is the single source of the count.
+// outage is not a hiccup. "`josh backlog:offer`" is the single source of the count.
 const RETRY_LIMIT = 3
 const FAILURE_EXIT_CODE = 1
 const NO_RETRIES = 0

package/scripts/behavior/behavior-rules.ts

@@ -13,7 +13,13 @@ const TOOL_USE = 'tool_use'
 const COMMAND_KEY = 'command'
 const FIRST_POSITION_OFFSET = 1
 const TOOL_RESULT = 'tool_result'
-const DENIED_BASH_PREFIX = 'Permission to use Bash with command '
+// The openings of the two results that mean a Bash call never ran: the permission layer's refusal,
+// and a PreToolUse hook's block (joshuafolkken/kit#3197). A PostToolUse hook error is deliberately
+// absent — that hook fires after the command has already run.
+const DENIED_BASH_PREFIXES = [
+	'Permission to use Bash with command ',
+	'PreToolUse:Bash hook error: ',
+]
 
 // The git subcommands that stage or rewrite the index — the ones `CLAUDE.md` reserves for `pnpm josh
 // git` under "Never stage or mutate the git index on your own". An agent that runs one directly has
@@ -71,14 +77,15 @@ function is_index_mutation(command: string): boolean {
 		.some((segment) => INDEX_MUTATION_HEAD.test(segment) && !is_dry_run(segment))
 }
 
-// An errored result alone may mean a command ran and failed. Only the permission layer's refusal
-// identifies a Bash call that never ran; the parser keeps the opening of that result's text.
+// An errored result alone may mean a command ran and failed. Only a refusal before execution — the
+// permission layer's or a PreToolUse hook's — identifies a Bash call that never ran; the parser keeps
+// the opening of that result's text.
 function is_denied_result(block: Block): boolean {
 	return (
 		block.type === TOOL_RESULT &&
 		block.result_id !== '' &&
 		block.is_error === true &&
-		block.error_text.startsWith(DENIED_BASH_PREFIX)
+		DENIED_BASH_PREFIXES.some((prefix) => block.error_text.startsWith(prefix))
 	)
 }
 

package/scripts/delegation/investigation-reads.ts

@@ -71,7 +71,7 @@ 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, 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".`
+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.
@@ -92,13 +92,13 @@ interface ReadTally {
 	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
@@ -264,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.
@@ -444,7 +444,7 @@ function is_at_search_threshold(search_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.

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/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/entry-read-budget.ts

@@ -57,7 +57,7 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// block in joshuafolkken/kit#2317 when `backlogrun-child.md`'s outage section recorded the
 	// session-resume re-dispatch and the outage-fold window.
 	// Raised in joshuafolkken/kit#2328 when `retrospective.md` joined the point-of-use set and `SKILL.md`
-	// grew by §2j: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
+	// grew by `retrospective.md`: every entry that reads `SKILL.md` discovers the retrospective document, so its ~5KB
 	// and the new section crossed a block for each. The lane child is exempt — it never runs the
 	// retrospective (`run:step` answers `stop` for a child at the stop position), so it skips both.
 	// joshuafolkken/kit#2335 recorded the drain-time firing with the operational detail in
@@ -70,8 +70,8 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// list, so its ~48KB read crossed a block downward and the recorded ceiling drops to the block multiple
 	// the stale-ratchet message named. The other entries still read it, so their rows hold.
 	// joshuafolkken/kit#2345 added the `implementation-unit` delegation row (full fan-out procedure in
-	// `docs/josh-commands-automation.md` → "`josh fanout`"); `SKILL.md` §2b gained only a one-clause mention and a
-	// pointer, folded into the existing enumeration and offset by tightening §2b prose, so every entry
+	// `docs/josh-commands-automation.md` → "`josh fanout`"); `delegation.md` gained only a one-clause mention and a
+	// pointer, folded into the existing enumeration and offset by tightening `delegation.md` prose, so every entry
 	// stayed within its block (kickoff has no block of headroom — its pre-#2294 ceiling is the next
 	// multiple, which the downward ratchet holds shut).
 	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
@@ -92,12 +92,24 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// `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 },
+	// Lowered in joshuafolkken/kit#3172: the heartbeat left `backlogrun-progress.md` for its own
+	// `progress-watcher.md`, and `pre-gate-cut.md` became the lane child's alone, so fullrun, halfrun
+	// and prrun stop paying for ~50KB of batch and lane procedure; backlogrun lost the moved prose.
+	// Lowered in joshuafolkken/kit#3174: `SKILL.md` was cut to a manifest (~21KB → ~11KB) and the entry
+	// sequence `fullrun`, `halfrun` and `prrun` shared moved into one `entry-sequence.md`.
+	// Lowered in joshuafolkken/kit#3175: the loop became the driver's hand-backs, the supervisor and
+	// provider prose moved to `docs/josh-commands-automation.md`, and the failure-only sections moved to
+	// `backlogrun-recovery.md`, which the parent's reach still charges whole.
+	// joshuafolkken/kit#3171 cut `CLAUDE.md` to triggers and pointers (~12 KB), lowering every entry.
+	{ entry: 'kickoff', bytes: 45_056 },
+	// Raised in joshuafolkken/kit#3177: #3173, #3181 and #3183 merged in parallel and together tipped
+	// fullrun 12 bytes over its block; none of #3177's documents are in its read set.
+	// Lowered back in joshuafolkken/kit#3180: the history and lint-settled proofs left its read set.
+	{ entry: 'fullrun', bytes: 57_344 },
+	{ entry: 'halfrun', bytes: 57_344 },
+	{ entry: 'prrun', bytes: 61_440 },
+	{ entry: 'backlogrun', bytes: 176_128 },
+	{ entry: LANE_CHILD, bytes: 57_344 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

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

@@ -19,19 +19,12 @@ const LANE_CHILD = 'lane-child'
 const FULLRUN = 'fullrun'
 
 // **The `SKILL.md` sections a dispatched lane child never uses**, read at the section level rather
-// than in full. A child is handed one issue to run, so it never files a new one with an `into`
-// target (§2a), never delegates its own pre-implementation reading (§2b), never names a repository or
-// scouts for a duplicate at its entry (§2c, §2e), returns an observation to the parent rather than
-// filing it (§2i), and never edits these documents (§3). Its dispatch is already an explicit workflow
-// invocation, so §0 cannot decide anything for it either. Review delegation remains in chain-rule.md.
+// than in full. A child never edits these documents (§3), and its dispatch is already an explicit
+// workflow invocation, so §0 cannot decide anything for it either. The other rules it never uses — the
+// `into` target, delegation, the repository prefix, the scout, observation filing, the retrospective —
+// are single rows of §2's table since joshuafolkken/kit#3174, so no section of them is left to trim.
 const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 	'0. The rule that fires before any of them — explicit invocation',
-	'2a. The `into <target>` suffix — where the new Issue lands',
-	'2b. Delegating a step to a cheaper tier',
-	'2c. The `owner/repo#` prefix — which repository the run acts on',
-	'2e. Before filing a new Issue — `pnpm josh issue:scout`',
-	'2i. An observation worth filing is filed without asking',
-	'2j. The end-of-run retrospective — read when `run:step` prints it',
 	'3. What stays resident, and what is read from here',
 ]
 
@@ -49,10 +42,12 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // list — what one invocation approves, the named-issue order, the session-cut record, the loop and the
 // once-per-session tail — none of which a leaf child performs. Every reference to it lives in a
 // document the child never reads (`backlogrun.md`, `backlogrun-progress.md`, `retrospective.md`) or in a
-// `SKILL.md` section the child trims (§0's session-cut note, §2b, §2i, §2j), so the child has no path
+// `SKILL.md` section the child trims (§0's session-cut note), so the child has no path
 // that opens it. It was the child's single largest read — ~16,000 tokens read whole — charged for a
 // document it never reaches, so dropping it is a correction of an over-count, not a loss of any rule the
 // child needs. The parent still reads it in full.
+// **`progress-watcher.md` is the parent's too** (joshuafolkken/kit#3172): a dispatched child is refused
+// a watcher by its `JOSH_LANE_CHILD` mark, so it never opens the watcher's document.
 const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'backlogrun-child.md',
 	'backlogrun-lanes.md',
@@ -61,13 +56,16 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 	'delegation.md',
 	'issue-scout.md',
 	'latest-gate.md',
+	'progress-watcher.md',
 	'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'])
+// entry's (joshuafolkken/kit#3078). **`pre-gate-cut.md` is the child's alone** (joshuafolkken/kit#3172):
+// only a lane child resumes or takes the pre-gate cut, so `fullrun.md` stopped naming it and the
+// child's reach carries it instead.
+const REACHED_POINT_OF_USE: ReadonlySet<string> = new Set(['backlogrun-park.md', 'pre-gate-cut.md'])
 
 function costed(root: string): ReadSetCost {
 	return read_set_trim.costed(root, {