@joshuafolkken/kit 1.1166.0 → 1.1229.0

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 },

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

@@ -14,20 +14,20 @@
 
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
 import { PACKAGE_DIR } from '#scripts/init/init-paths'
 import { bash_output_cap_reader } from './bash-output-cap'
-import { document_section, type Section } from './document-section'
+import { document_section } from './document-section'
+import { read_set_cost, type Cost } from './read-set-cost'
 import { read_set_point_of_use } from './read-set-point-of-use'
 
 const { POINT_OF_USE_FILES, POINT_OF_USE_BY_ENTRY, is_point_of_use, point_of_use_files } =
 	read_set_point_of_use
+const { cost_of, scoped_file_cost, total } = read_set_cost
 
 const SKILL_DIRECTORY = path.join('.claude', 'skills', 'workflow-commands')
 const SKILL_FILE = 'SKILL.md'
 const TABLE_SECTION = '1. Which file to read'
 const NOTHING = 0
-const ONE_LINE = 1
 
 // The point-of-use classification — which documents an entry names but reads only at a later step —
 // is its own concern, split into `read-set-point-of-use.ts` in joshuafolkken/kit#2289. This file
@@ -54,11 +54,6 @@ interface SectionReference {
 	heading: string
 }
 
-interface Cost {
-	bytes: number
-	tokens: number
-}
-
 interface SectionCost extends SectionReference {
 	cost: Cost
 	is_resolved: boolean
@@ -297,21 +292,6 @@ function read_set(root: string, entry: string): ReadSet {
 	return { entry, files, sections: sections_for(root, entry, files) }
 }
 
-function cost_of(text: string): Cost {
-	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
-}
-
-function total(costs: ReadonlyArray<Cost>): Cost {
-	const running = { bytes: NOTHING, tokens: NOTHING }
-
-	for (const cost of costs) {
-		running.bytes += cost.bytes
-		running.tokens += cost.tokens
-	}
-
-	return running
-}
-
 function section_cost(root: string, reference: SectionReference): SectionCost {
 	const found = document_section.section(read_document(root, reference.file), reference.heading)
 
@@ -334,74 +314,13 @@ function headings_for(sections: ReadonlyArray<SectionReference>, file: string):
 	return sections.filter((reference) => reference.file === file).map((one) => one.heading)
 }
 
-function add_range(charged: Set<number>, found: Section): void {
-	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
-}
-
-// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
-// file and there is then nothing to union.
-function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
-	const charged = new Set<number>()
-
-	for (const heading of headings) {
-		const found = document_section.section(markdown, heading)
-
-		if (found === undefined) return undefined
-
-		add_range(charged, found)
-	}
-
-	return charged
-}
-
-// **The union's charged lines are split into contiguous runs, and each run is costed on its own
-// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
-// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
-// with no real overlap — a false negative saving the measurement must never print
-// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
-// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
-// real read and keeps `scoped` at or below the per-reference sum by construction.
-function extend_or_start(runs: Array<Array<number>>, index: number): void {
-	const current = runs.at(-1)
-
-	if (current?.at(-1) === index - ONE_LINE) current.push(index)
-	else runs.push([index])
-}
-
-function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
-	const runs: Array<Array<number>> = []
-	const ascending = [...charged].toSorted((left, right) => left - right)
-
-	for (const index of ascending) extend_or_start(runs, index)
-
-	return runs
-}
-
-function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
-	return run.map((index) => lines[index] ?? '').join('\n')
-}
-
-// **Charged per file over the union of the lines its references cover, never per reference.**
-// Summing the references instead double-counts the two ways one file can be cited twice — two
-// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
-// `###` children, which `section()` already returns inside the parent. Either one could push the
-// scoped figure above the whole one and print a *negative* saving, which is the single direction this
-// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
-function file_scoped_cost(root: string, file: string, headings: ReadonlyArray<string>): Cost {
-	const markdown = read_document(root, file)
-	const charged = charged_lines(markdown, headings)
-
-	if (charged === undefined) return cost_of(markdown)
-
-	const lines = markdown.split('\n')
-
-	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
-}
-
+// The per-file union that keeps `scoped` at or below `whole` lives in `read-set-cost.ts`.
 function scoped_cost(root: string, sections: ReadonlyArray<SectionReference>): Cost {
 	const files = unique(sections.map((reference) => reference.file))
 
-	return total(files.map((file) => file_scoped_cost(root, file, headings_for(sections, file))))
+	return total(
+		files.map((file) => scoped_file_cost(read_document(root, file), headings_for(sections, file))),
+	)
 }
 
 function file_costs(root: string, names: ReadonlyArray<string>): Array<FileCost> {
@@ -491,5 +410,7 @@ const entry_read_set = {
 	total,
 }
 
-export type { Cost, FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
+export type { FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
 export { entry_read_set }
+
+export { type Cost } from './read-set-cost'

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

@@ -0,0 +1,98 @@
+import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
+import { document_section, type Section } from './document-section'
+
+// What a read costs, and the scoped union that charges one file's cited sections once — split out
+// of `entry-read-set.ts` when it reached its line limit (joshuafolkken/kit#3264). `entry_read_set`
+// re-exports `cost_of`, `total` and `Cost` under the names they always had, so the move changed no
+// call site.
+
+const NOTHING = 0
+const ONE_LINE = 1
+
+interface Cost {
+	bytes: number
+	tokens: number
+}
+
+function cost_of(text: string): Cost {
+	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
+}
+
+function total(costs: ReadonlyArray<Cost>): Cost {
+	const running = { bytes: NOTHING, tokens: NOTHING }
+
+	for (const cost of costs) {
+		running.bytes += cost.bytes
+		running.tokens += cost.tokens
+	}
+
+	return running
+}
+
+function add_range(charged: Set<number>, found: Section): void {
+	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
+}
+
+// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
+// file and there is then nothing to union.
+function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
+	const charged = new Set<number>()
+
+	for (const heading of headings) {
+		const found = document_section.section(markdown, heading)
+
+		if (found === undefined) return undefined
+
+		add_range(charged, found)
+	}
+
+	return charged
+}
+
+// **The union's charged lines are split into contiguous runs, and each run is costed on its own
+// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
+// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
+// with no real overlap — a false negative saving the measurement must never print
+// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
+// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
+// real read and keeps `scoped` at or below the per-reference sum by construction.
+function extend_or_start(runs: Array<Array<number>>, index: number): void {
+	const current = runs.at(-1)
+
+	if (current?.at(-1) === index - ONE_LINE) current.push(index)
+	else runs.push([index])
+}
+
+function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
+	const runs: Array<Array<number>> = []
+	const ascending = [...charged].toSorted((left, right) => left - right)
+
+	for (const index of ascending) extend_or_start(runs, index)
+
+	return runs
+}
+
+function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
+	return run.map((index) => lines[index] ?? '').join('\n')
+}
+
+// **Charged per file over the union of the lines its references cover, never per reference.**
+// Summing the references instead double-counts the two ways one file can be cited twice — two
+// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
+// `###` children, which `section()` already returns inside the parent. Either one could push the
+// scoped figure above the whole one and print a *negative* saving, which is the single direction this
+// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
+function scoped_file_cost(markdown: string, headings: ReadonlyArray<string>): Cost {
+	const charged = charged_lines(markdown, headings)
+
+	if (charged === undefined) return cost_of(markdown)
+
+	const lines = markdown.split('\n')
+
+	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
+}
+
+const read_set_cost = { cost_of, scoped_file_cost, total }
+
+export type { Cost }
+export { read_set_cost }

package/scripts/epic/epic-add-body.ts

@@ -147,6 +147,7 @@ function splice_declaration(
 		if (index === input.first) return [...input.rendered]
 		if (input.dropped.has(index)) return []
 
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
 		return [line]
 	})
 }

package/scripts/epic/epic-audit-checks.ts

@@ -301,7 +301,7 @@ function reported_references(
 		.flatMap((reference) => {
 			const state = reported_state(states, reference)
 
-			return state === undefined ? [] : [{ reference, state }]
+			return state === undefined ? [] : { reference, state }
 		})
 }
 

package/scripts/epic/epic-audit-rationale.ts

@@ -73,9 +73,10 @@ function order_pairs(
 		const blocked = find_child(children, { repo: epic_repo, number: link.blocked })
 		if (blocker === undefined || blocked === undefined) return []
 
-		return is_open_local(blocker, current_repo) && is_open_local(blocked, current_repo)
-			? [{ blocker, blocked }]
-			: []
+		if (!is_open_local(blocker, current_repo) || !is_open_local(blocked, current_repo)) return []
+
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
+		return [{ blocker, blocked }]
 	})
 }