@joshuafolkken/kit 1.1178.0 → 1.1229.0

package/scripts/discovery/repo-origin.ts

@@ -111,12 +111,12 @@ function origin_section_lines(lines: ReadonlyArray<string>): Array<string> {
 	return end === NOT_FOUND ? rest : rest.slice(0, end)
 }
 
-// The value of a `key = value` entry, or nothing when the line declares a different key. Split on
+// The value of a `url = value` entry, or nothing when the line declares a different key. Split on
 // the first separator rather than matched, for the reason `parse_scp_like` is split by hand.
-function entry_value(line: string, key: string): string | undefined {
+function url_value(line: string): string | undefined {
 	const separator = line.indexOf('=')
 	if (separator === NOT_FOUND) return undefined
-	if (line.slice(0, separator).trim() !== key) return undefined
+	if (line.slice(0, separator).trim() !== URL_KEY) return undefined
 
 	return line.slice(separator + 1).trim()
 }
@@ -129,7 +129,7 @@ function parse_origin_from_config(content: string): string | undefined {
 	const lines = content.split('\n').map((line) => line.trim())
 
 	return origin_section_lines(lines)
-		.map((line) => entry_value(line, URL_KEY))
+		.map((line) => url_value(line))
 		.find((url) => url !== undefined)
 }
 
@@ -153,7 +153,7 @@ function parse_remote_urls_from_config(content: string): Array<string> {
 
 	return section_groups(lines)
 		.filter((group) => REMOTE_SECTION.test(group[0] ?? ''))
-		.flatMap((group) => group.map((line) => entry_value(line, URL_KEY)))
+		.flatMap((group) => group.map((line) => url_value(line)))
 		.filter((url) => url !== undefined)
 }
 

package/scripts/doctor/doctor-consumer.ts

@@ -3,6 +3,7 @@ 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 { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { z } from 'zod'
 
@@ -20,7 +21,6 @@ const PLUGIN_ID = 'kit@kit'
 // full document, so this pointer is also what tells a consumer repository apart from kit itself.
 const CLAUDE_MD_POINTER = `@${NODE_MODULES}/${KIT_PACKAGE_NAME}/dist/${CLAUDE_MD}`
 const SECRETLINT_BIN = path.join(NODE_MODULES, '.bin', 'secretlint')
-const GIT_TIMEOUT_MS = 2000
 
 const manifest_schema = z.object({
 	name: z.string().optional(),
@@ -77,7 +77,7 @@ function is_plugin_declared(root: string): boolean {
 // from installing kit's git hooks — the failure is silent but for one stderr line.
 function configured_hooks_path(root: string): string | undefined {
 	const value = git_spawn_sync.read(['-C', root, 'config', '--get', 'core.hooksPath'], {
-		timeout: GIT_TIMEOUT_MS,
+		timeout: PROBE_TIMEOUT_MS,
 	})
 
 	return value === '' ? undefined : value

package/scripts/doctor/doctor-io.ts

@@ -2,11 +2,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
 const JOSH_BIN = 'josh'
-const GIT_TIMEOUT_MS = 2000
 const NOT_A_REPOSITORY_MESSAGE = 'not a git repository'
 const NPM_VERSION_UPDATES_DISABLED = 'open-pull-requests-limit: 0'
 const DEPENDABOT_CONFIG_PATH = '.github/dependabot.yml'
@@ -72,7 +72,7 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 function resolve_git_top_level(): GitTopLevel {
 	// 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)
+	const result = git_spawn_sync.toplevel(PROBE_TIMEOUT_MS)
 
 	if (result.exit_code === 0) return classify_top_level(result.stdout.trim())
 
@@ -194,7 +194,6 @@ type GitTopLevel =
 	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
 
 const doctor_io = {
-	GIT_TIMEOUT_MS,
 	resolve_path_josh,
 	resolve_pnpm_global_josh,
 	has_distributed_dependabot_config,

package/scripts/document/capped-print-part.ts

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+// Where `capped-print.ts` writes the parts of an over-cap output, and how a path is recognized as one
+// of them (joshuafolkken/kit#3332). Both halves live here so the writer and the investigation guard,
+// which must not count a read of a part as reading the Issue's subject, share one spelling of the
+// shape — kept free of the writer's own imports, since the guard runs as a hook on every tool call.
+
+const DIRECTORY_PREFIX = 'josh-capped-print-'
+const PART_PREFIX = 'part-'
+const PART_SUFFIX = '.md'
+// A part is `part-<N>.md` and nothing else, so a run's own file that happens to sit beside one is not
+// mistaken for it.
+const PART_PATTERN = /^part-[1-9]\d*\.md$/u
+
+function part_name(index: number): string {
+	return `${PART_PREFIX}${String(index + 1)}${PART_SUFFIX}`
+}
+
+// **The file's own parent, and the file's own name, both have to match.** A directory prefix alone
+// would exempt anything a run unpacked under a similarly named directory; the caller also requires the
+// path to lie outside the checkout, so no repository file is ever exempted by its name.
+function is_part_file(absolute: string): boolean {
+	const parent = path.basename(path.dirname(absolute))
+
+	return parent.startsWith(DIRECTORY_PREFIX) && PART_PATTERN.test(path.basename(absolute))
+}
+
+const capped_print_part = { DIRECTORY_PREFIX, part_name, is_part_file }
+
+export { capped_print_part }

package/scripts/document/capped-print.ts

@@ -3,6 +3,7 @@ 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'
+import { capped_print_part } from './capped-print-part'
 
 // 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
@@ -17,9 +18,7 @@ import { bash_output_cap_reader } from './bash-output-cap'
 // 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
@@ -27,10 +26,10 @@ const LINE_BREAK = '\n'
 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))
+	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, capped_print_part.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}`)
+		const file = path.join(directory, capped_print_part.part_name(index))
 
 		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
 

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

@@ -88,8 +88,17 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
 	// 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 },
+	// joshuafolkken/kit#3277 moved the run, lane and session commands to `docs/josh-commands-run.md`.
+	// joshuafolkken/kit#3280 moved the issue, epic, backlog and review commands to
+	// `docs/josh-commands-backlog.md`.
+	// joshuafolkken/kit#3278 moved `josh latest` and `josh overrides` — commands a person types — from
+	// the automation page to `docs/josh-commands.md`, which grew one block and the automation page shrank one.
+	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands.md', bytes: 40_960 },
+	// joshuafolkken/kit#3279 moved the label sections here out of `docs/josh-commands-backlog.md`.
+	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },

package/scripts/document/document-scan.ts

@@ -0,0 +1,117 @@
+// Pulling machine-checkable references out of the distributed documents, so a few structural scans
+// can replace the ~140 per-phrase marker suites the documents used to carry (joshuafolkken/kit#1923).
+// Every function here is a pure string extractor: it takes document text and returns the references
+// it names, which is what lets the scans that call it be checked on a synthetic string with a
+// deliberately broken reference in it.
+
+// A command reference, only inside a code span. `` `pnpm josh gate` `` and `` `josh review:brief` ``
+// are the copy-and-paste form; the leading backtick keeps prose like "josh will decide" out, which
+// would otherwise read "will" as a command name.
+const COMMAND_PATTERN = /`(?:pnpm )?josh ([a-z][a-z0-9:-]+)/gu
+
+// A label the documents operate on — applied (`labels[]=…`), removed (`…/labels/<name>`) or created
+// (`labels -f name=…`). Prose that merely names a label is not scanned; a mistyped name only breaks
+// where a command carries it.
+const LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_-]*)/gu
+
+// A section reference: a markdown file, an arrow, and the cited heading in straight or Japanese
+// quotes — `` `backlogrun-progress.md` → "The hand-off" ``. The code span is optional and a section
+// number may sit between the arrow and the heading (`` `SKILL.md` → §1, "…" ``): both forms are in
+// the documents, as is a name linked to its file (`` [`residency.md`](./residency.md) →「…」 ``), and a
+// pattern that skipped them let a broken reference of each form through (joshuafolkken/kit#3076).
+// The backreference pairs the code span's backticks, and the lookbehind keeps a bare name from
+// starting mid-path — inside a URL or after an unpaired backtick.
+const SECTION_PATTERN =
+	/(?<![\w./:`-])(?<tick>`?)(?<file>[\w./-]+\.md)\k<tick>\s*→\s*(?:§\w+,\s*)?["「](?<heading>[^"」]+)["」]/gu
+
+// A markdown link's `(target)`, dropped before the section scan so a linked name sits right before its
+// arrow — the link text already carries the file the reference names.
+const LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu
+
+// A relative markdown link target, with an optional `#anchor`. External `https://…` links carry no
+// `.md`, so the pattern never matches them.
+const LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu
+
+// Filenames that appear in the documents as illustrations of the reference form itself, never as real
+// targets — the doc-section explanation cites `` `path.md` → "Heading" `` and `` `X.md` → "Heading" ``.
+const PLACEHOLDER_FILES: ReadonlySet<string> = new Set(['x.md', 'foo.md', 'file.md', 'path.md'])
+
+function matches(text: string, pattern: RegExp): Array<RegExpMatchArray> {
+	return [...text.matchAll(pattern)]
+}
+
+// A trailing colon is a placeholder for the sub-command that follows — `` `josh epic:` `` stands for
+// `epic:audit`, `epic:next` and the rest — so it names no command of its own.
+function command_references(text: string): Array<string> {
+	return matches(text, COMMAND_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((name) => !name.endsWith(':'))
+}
+
+// A `<placeholder>` inside a command, and `depth:<n>` after the char class stops at `<`, both leave a
+// token that is not a real label. Real labels never end in a colon and never carry angle brackets.
+function is_real_label(token: string): boolean {
+	return token.length > 0 && !token.endsWith(':') && !token.includes('<')
+}
+
+function label_references(text: string): Array<string> {
+	return matches(text, LABEL_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((token) => is_real_label(token))
+}
+
+function base_name(path: string): string {
+	return path.split('/').at(-1) ?? path
+}
+
+function is_placeholder_file(name: string): boolean {
+	return name.includes('<') || PLACEHOLDER_FILES.has(base_name(name).toLowerCase())
+}
+
+interface SectionReference {
+	file: string
+	heading: string
+}
+
+function section_references(text: string): Array<SectionReference> {
+	return matches(text.replaceAll(LINK_TARGET_PATTERN, ''), SECTION_PATTERN)
+		.map(({ groups }) => ({ file: groups?.['file'] ?? '', heading: groups?.['heading'] ?? '' }))
+		.filter((reference) => !is_placeholder_file(reference.file))
+}
+
+function link_targets(text: string): Array<string> {
+	return matches(text, LINK_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((file) => !is_placeholder_file(file))
+}
+
+// A cited heading and the heading it names are compared with backticks dropped and whitespace
+// collapsed, because a reference wraps at the column the prose wraps at — sometimes across a
+// blockquote `> ` continuation — while the heading it points at is one unbroken line.
+function normalize_reference(heading: string): string {
+	return heading
+		.replaceAll('`', '')
+		.split(/\s+/u)
+		.filter((word) => word !== '>')
+		.join(' ')
+}
+
+// The two forms a heading can be cited by: with its leading number (`2b. Delegating…`) and without
+// (`Delegating…`), since a document's own numbering is a prefix a reference may or may not carry.
+function reference_forms(title: string): Array<string> {
+	const normalized = normalize_reference(title)
+
+	return [normalized, normalized.replace(/^\d+[a-z]?\. /u, '')]
+}
+
+const document_scan = {
+	command_references,
+	label_references,
+	link_targets,
+	normalize_reference,
+	reference_forms,
+	section_references,
+}
+
+export type { SectionReference }
+export { document_scan }

package/scripts/document/document-section.ts

@@ -13,6 +13,7 @@
 // moved to "read it later" is a rule that measurably never fires, and this moves nothing to later.
 
 import { file_reader } from '#scripts/lib/read-file'
+import { document_scan } from './document-scan'
 
 // `#` to `######`, one space, then the title. Written with a literal space rather than `\s+` and a
 // lazy title so it cannot backtrack: `sonarjs/super-linear-regex` rejects the `\s+…+?\s*$` shape,
@@ -21,6 +22,17 @@ const HEADING_PATTERN = /^(?<hashes>#{1,6}) (?<title>.*)$/u
 const FENCE = '```'
 const SINGLE_MATCH = 1
 
+// Any bold span is a citable anchor: the documents point at `- **Cross-package problems → …**` at a
+// line start and at a `**…**` emphasis mid-paragraph alike.
+const BOLD_LABEL_PATTERN = /\*\*([^*]+?)\*\*/gu
+const BOLD_DELIMITER = '**'
+// A one-line inline code span: a double-backtick span (which may quote a backtick) or a single one.
+const CODE_SPAN_PATTERN = /``[^\n]*?``|`[^`\n]*`/gu
+// A label ranks below every heading, so a heading section never ends at one.
+const LABEL_LEVEL = 7
+// A list item opens with `-`, `*` or a number, after any indentation.
+const LIST_ITEM_PATTERN = /^(?<indent>\s*)(?:[-*]|\d+\.) /u
+
 interface Heading {
 	level: number
 	title: string
@@ -58,13 +70,27 @@ function push_heading(found: Array<Heading>, line: string, index: number): void
 // **Fenced blocks are skipped, and that is not defensive tidying.** These documents quote shell, and
 // a shell comment at the start of a line is a `#` in column one. Counted as a heading it would end
 // the section above it early, which is a silent wrong answer rather than a visible failure.
+// One flag per line — `true` for a fence delimiter and every line between a pair of them — so the
+// heading scan and the label scan cannot disagree on what is quoted code.
+function fenced_flags(lines: ReadonlyArray<string>): Array<boolean> {
+	let is_inside_fence = false
+
+	return lines.map(function is_fenced(line: string): boolean {
+		if (!line.startsWith(FENCE)) return is_inside_fence
+
+		is_inside_fence = !is_inside_fence
+
+		return true
+	})
+}
+
 function headings(markdown: string): Array<Heading> {
+	const lines = markdown.split('\n')
+	const fenced = fenced_flags(lines)
 	const found: Array<Heading> = []
-	let is_inside_fence = false
 
-	for (const [index, line] of markdown.split('\n').entries()) {
-		if (line.startsWith(FENCE)) is_inside_fence = !is_inside_fence
-		else if (!is_inside_fence) push_heading(found, line, index)
+	for (const [index, line] of lines.entries()) {
+		if (fenced[index] !== true) push_heading(found, line, index)
 	}
 
 	return found
@@ -74,24 +100,77 @@ function titles(markdown: string): Array<string> {
 	return headings(markdown).map((heading) => heading.title)
 }
 
+// The zero-based line each character offset sits on, read as the number of line starts at or before it.
+function line_starts(markdown: string): Array<number> {
+	return [...markdown.matchAll(/\n/gu)].map((match) => match.index + SINGLE_MATCH)
+}
+
+function line_of(starts: ReadonlyArray<number>, offset: number): number {
+	return starts.filter((start) => start <= offset).length
+}
+
+// **A bold label is an anchor too** (joshuafolkken/kit#3248). The documents cite
+// `- **Output language follows …**` exactly as they cite a heading, and the reference tests accepted
+// both while this reader found only headings — so a green suite promised a section the command then
+// refused. A label may wrap across lines, so the scan runs over the whole text, not line by line.
+//
+// Fenced lines are blanked before the scan rather than filtered after it: a `docs/**` glob in a
+// fence would otherwise take a delimiter and pair every later `**` with the wrong partner. Blanking
+// keeps the line count, so a label's line number still indexes the original document.
+function unfenced_text(markdown: string): string {
+	const lines = markdown.split('\n')
+	const fenced = fenced_flags(lines)
+
+	return lines.map((line, index) => (fenced[index] === true ? '' : line)).join('\n')
+}
+
+// An inline code span gets the same treatment one level down: `prompts/**` mid-paragraph would take a
+// delimiter just as a fenced glob does. Its `*` become spaces, so every offset still indexes the
+// unmasked text — which is where the title is read from, keeping a label that quotes code intact.
+function code_masked(text: string): string {
+	return text.replaceAll(CODE_SPAN_PATTERN, (span) => span.replaceAll('*', ' '))
+}
+
+function labels(markdown: string): Array<Heading> {
+	const text = unfenced_text(markdown)
+	const starts = line_starts(text)
+
+	return [...code_masked(text).matchAll(BOLD_LABEL_PATTERN)].map((match) => ({
+		level: LABEL_LEVEL,
+		title: text.slice(
+			match.index + BOLD_DELIMITER.length,
+			match.index + match[0].length - BOLD_DELIMITER.length,
+		),
+		line: line_of(starts, match.index),
+	}))
+}
+
 // **Prefix, because a reference cites the name and the heading carries the name plus its gloss.**
 // `` → "The hand-off" `` points at `## The hand-off — one session does not have to run the whole
 // epic`, and `` → "The check is asked at every merge" `` at a heading that continues with a comma.
 // Requiring the whole heading would make every such reference unresolvable, and citing the whole
-// heading in the prose would put the gloss into every pointer.
+// heading in the prose would put the gloss into every pointer. Both sides are compared in the forms
+// `document_scan.reference_forms` gives, so a reference that wraps or drops a heading's number lands.
 function is_match(heading: Heading, wanted: string): boolean {
-	return heading.title.startsWith(wanted)
+	return document_scan.reference_forms(heading.title).some((form) => form.startsWith(wanted))
 }
 
 function prefixed(found: ReadonlyArray<Heading>, wanted: string): Array<Heading> {
-	return found.filter((heading) => is_match(heading, wanted))
+	const normalized = document_scan.normalize_reference(wanted)
+
+	return found.filter((heading) => is_match(heading, normalized))
+}
+
+function is_exact(heading: Heading, wanted: string): boolean {
+	return document_scan.reference_forms(heading.title).includes(wanted)
 }
 
 // **Exact wins, and an ambiguous prefix is refused rather than ranked.** Two headings that both
 // start with the cited text is a document whose reference is genuinely ambiguous; picking the first
 // would hand back a section nobody named, which is a failure a whole-file read does not have.
 function select(found: ReadonlyArray<Heading>, wanted: string): Heading | undefined {
-	const exact = found.find((heading) => heading.title === wanted)
+	const normalized = document_scan.normalize_reference(wanted)
+	const exact = found.find((heading) => is_exact(heading, normalized))
 
 	if (exact !== undefined) return exact
 
@@ -103,34 +182,82 @@ function select(found: ReadonlyArray<Heading>, wanted: string): Heading | undefi
 // A section ends where the next heading of the same or higher rank begins, so a `##` section carries
 // its `###` subsections with it — which is what a pointer at a `##` heading means.
 function last_line_of(found: ReadonlyArray<Heading>, chosen: Heading, total_lines: number): number {
-	const index = found.indexOf(chosen)
-	const next = found.slice(index + SINGLE_MATCH).find((heading) => heading.level <= chosen.level)
+	const next = found.find((heading) => heading.line > chosen.line && heading.level <= chosen.level)
 
 	return (next === undefined ? total_lines : next.line) - SINGLE_MATCH
 }
 
-function section(markdown: string, wanted: string): Section | undefined {
-	const lines = markdown.split('\n')
+function indent_of(line: string): number {
+	return line.length - line.trimStart().length
+}
+
+// Where the block a label sits in stops: a blank line, a heading, or a list item at the label line's
+// own depth or shallower — so a label's nested sub-items come with it and its next sibling does not.
+function is_sibling_item(line: string, depth: number): boolean {
+	const { indent } = LIST_ITEM_PATTERN.exec(line)?.groups ?? {}
+
+	return indent !== undefined && indent.length <= depth
+}
+
+function ends_block(line: string, depth: number): boolean {
+	if (line.trim() === '' || HEADING_PATTERN.test(line)) return true
+
+	return is_sibling_item(line, depth)
+}
+
+// A label's section is the paragraph or list item it opens, not the rest of the document.
+function label_last_line(lines: ReadonlyArray<string>, label: Heading): number {
+	const depth = indent_of(lines[label.line] ?? '')
+	const end = lines.findIndex((line, index) => index > label.line && ends_block(line, depth))
+
+	return (end === -1 ? lines.length : end) - SINGLE_MATCH
+}
+
+// **A heading answers before any label does.** A label is consulted only when no heading even
+// starts with the cited text, so an ambiguous heading reference is refused rather than rescued by a
+// bold span that happens to share its prefix.
+function choose(markdown: string, wanted: string): Heading | undefined {
 	const found = headings(markdown)
-	const chosen = select(found, wanted)
+
+	if (prefixed(found, wanted).length > 0) return select(found, wanted)
+
+	return select(labels(markdown), wanted)
+}
+
+function extent_of(markdown: string, chosen: Heading): number {
+	const lines = markdown.split('\n')
+
+	if (chosen.level === LABEL_LEVEL) return label_last_line(lines, chosen)
+
+	return last_line_of(headings(markdown), chosen, lines.length)
+}
+
+function section(markdown: string, wanted: string): Section | undefined {
+	const chosen = choose(markdown, wanted)
 
 	if (chosen === undefined) return undefined
 
-	const last_line = last_line_of(found, chosen, lines.length)
+	const last_line = extent_of(markdown, chosen)
+	const lines = markdown.split('\n').slice(chosen.line, last_line + SINGLE_MATCH)
 
 	return {
 		title: chosen.title,
 		level: chosen.level,
 		first_line: chosen.line,
 		last_line,
-		text: lines.slice(chosen.line, last_line + SINGLE_MATCH).join('\n'),
+		text: lines.join('\n'),
 	}
 }
 
 // Ambiguity and absence are different answers, and the caller reports them differently: one names
 // the candidates, the other lists every heading the file has.
+// Candidates follow `choose`'s order — headings, and labels only when no heading matches — so a
+// refusal never suggests a label that citing it could not select.
 function candidates(markdown: string, wanted: string): Array<string> {
-	return prefixed(headings(markdown), wanted).map((heading) => heading.title)
+	const near = prefixed(headings(markdown), wanted)
+	const listed = near.length > 0 ? near : prefixed(labels(markdown), wanted)
+
+	return listed.map((heading) => heading.title)
 }
 
 function read_optional(file_path: string): string | undefined {

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

@@ -70,7 +70,7 @@ 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`"); `delegation.md` gained only a one-clause mention and a
+	// `docs/josh-commands-backlog.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).
@@ -101,12 +101,14 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// 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 },
+	// joshuafolkken/kit#3256 moved `CLAUDE.md`'s residency prose to `residency.md`, lowering kickoff and
+	// halfrun one block each.
+	{ entry: 'kickoff', bytes: 40_960 },
 	// 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: 'halfrun', bytes: 53_248 },
 	{ entry: 'prrun', bytes: 61_440 },
 	{ entry: 'backlogrun', bytes: 176_128 },
 	{ entry: LANE_CHILD, bytes: 57_344 },