@joshuafolkken/kit 1.872.0

package/scripts/document/read-files-cli.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { bash_output_cap_reader } from './bash-output-cap'
+import { document_section } from './document-section'
+
+// `josh read:files <path> [<path> ...]` — read several files in one call
+// (joshuafolkken/kit#2202).
+//
+// **This is the mid-implementation counterpart of `run:prep`.** `run:prep` folds a run's pre-edit
+// reads into one call at a *pre-determined* point (before implementing), and kit#2165 / kit#2162
+// showed that folding a routine section into one composite command is the only lever that has moved
+// round-trip density — advice did not (kit#1304), a live density line did not (kit#1329 / kit#1337),
+// and the lane-child notice did not (kit#2164, taken off in kit#2178). What those composite commands
+// could not reach is the implementation phase itself: an agent editing several files reads one, edits
+// it, reads the next, edits it — the interleaved nine-turn sequence kit#2178 measured — because the
+// edit set is not a routine known in advance.
+//
+// **But it is known one moment earlier: Step 0 enumerates every change with its file.** So there is a
+// pre-determined point after all, and this is the command that folds the reads at it: given the Step 0
+// target list, it returns every file's contents in one call. The reads collapse to one turn, and — the
+// whole point — the edits that follow no longer depend on an interleaved read, so they fall out into
+// one turn too. The lever is structural, not another way to *say* "batch": `report-format.md` routes
+// the run here at the Step 0 seam, beside the `josh lines` step that already reads the same list.
+//
+// **Under the cap it prints every file; over it, a directive and no content**, the invariant
+// `doc:read` holds for one file (kit#2188). A truncated preview is the failure this refuses — so an
+// over-cap batch is not printed but named, and the directive tells the run to read the files with the
+// Read tool *in one turn*, which keeps the reads folded even on the fallback path.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const SUCCESS_EXIT_CODE = 0
+const NONE = 0
+const USAGE = 'Usage: josh read:files <path> [<path> ...]'
+const OVER_CAP_PREFIX = 'Over the Bash cap'
+const READ_TOOL_DIRECTIVE = 'read these files with the Read tool in one turn, not cat:'
+// The rule that fences each file's contents, so a reader — and a `grep` — finds where one file ends
+// and the next begins in the single blob this prints.
+const HEADER_RULE = '====='
+const BLOCK_SEPARATOR = '\n\n'
+
+interface FileRead {
+	path: string
+	text: string | undefined
+}
+
+interface PresentRead {
+	path: string
+	text: string
+}
+
+function byte_length(text: string): number {
+	return Buffer.byteLength(text, 'utf8')
+}
+
+function read_one(name: string, root: string): FileRead {
+	return { path: name, text: document_section.read_optional(path.resolve(root, name)) }
+}
+
+function is_present(read: FileRead): read is PresentRead {
+	return read.text !== undefined
+}
+
+function file_block(read: PresentRead): string {
+	return `${HEADER_RULE} ${read.path} ${HEADER_RULE}\n${read.text}`
+}
+
+function combined_text(present: ReadonlyArray<PresentRead>): string {
+	return present.map((read) => file_block(read)).join(BLOCK_SEPARATOR)
+}
+
+// The one line that stands in for an over-cap batch: both figures so the reason is legible, every
+// path so the Read tool has its arguments, and none of the files' content.
+function over_cap_directive(paths: ReadonlyArray<string>, bytes: number, cap: number): string {
+	const figures = `(${bytes.toLocaleString('en-US')} B > ${cap.toLocaleString('en-US')} B)`
+
+	return `${OVER_CAP_PREFIX} ${figures} — ${READ_TOOL_DIRECTIVE} ${paths.join(' ')}`
+}
+
+// Print every present file in one call, or — over the cap — the directive and no content, never a
+// truncated preview. Nothing at all when no named file could be read; the missing ones are reported
+// separately.
+function print_present(present: ReadonlyArray<PresentRead>, cap: number): void {
+	if (present.length === NONE) return
+
+	const text = combined_text(present)
+	const bytes = byte_length(text)
+	const paths = present.map((read) => read.path)
+
+	if (bytes > cap) console.info(over_cap_directive(paths, bytes, cap))
+	else console.info(text)
+}
+
+// Every path that resolved to nothing is named, and one such path makes the whole call non-zero — a
+// caller that asked for a file it did not get is told which one rather than left to subtract.
+function report_missing(reads: ReadonlyArray<FileRead>): number {
+	const missing = reads.filter((read) => !is_present(read))
+
+	for (const read of missing) console.error(`Cannot read ${read.path}`)
+
+	return missing.length > NONE ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+function run(argv: ReadonlyArray<string>, root: string = process.cwd()): number {
+	if (argv.length === NONE) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reads = argv.map((name) => read_one(name, root))
+
+	print_present(reads.filter(is_present), bash_output_cap_reader.bash_output_cap(root))
+
+	return report_missing(reads)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const read_files_cli = {
+	OVER_CAP_PREFIX,
+	READ_TOOL_DIRECTIVE,
+	SUCCESS_EXIT_CODE,
+	USAGE,
+	main,
+	over_cap_directive,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { read_files_cli }

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

@@ -0,0 +1,295 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { backlogrun_parent_read_set } from './backlogrun-parent-read-set'
+import { entry_read_set, type ReadSetCost, type SectionCost } from './entry-read-set'
+import { lane_child_read_set } from './lane-child-read-set'
+import { read_set_pricing } from './read-set-pricing'
+
+// `josh read:set` — what this entry point reads before it starts, and what that costs
+// (joshuafolkken/kit#1776).
+//
+// **The entry cost had no reading of its own.** It could be inferred after the fact from
+// `josh cost`, which measures a whole session and cannot say which part of it was the mandated read;
+// so the baseline for joshuafolkken/kit#1776 could only be written by hand, once, from one
+// transcript. This prints it per entry point, from the documents themselves, as often as anyone
+// wants to ask.
+//
+// **Two figures under one definition, which is what makes a before and an after comparable.**
+// `whole` is every file in the set read in full — what a run pays with no way to fetch a heading.
+// `scoped` is the set's own files in full plus the cross-referenced *sections* alone — what the same
+// run pays with `josh doc:section`. Neither figure drops a document and neither drops a rule: the
+// difference is entirely the part of a referenced file that the reference never pointed at.
+
+const { BACKLOGRUN } = backlogrun_parent_read_set
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const FLAG_PREFIX = '-'
+const JSON_FLAG = '--json'
+const JSON_INDENT = 2
+const NOTHING = 0
+const PERCENT = 100
+const LABEL_GUTTER = 4
+const NUMBER_WIDTH = 9
+const DOLLAR_WIDTH = 7
+const DOLLAR_DECIMALS = 2
+// The premise the dollar column is read against: each figure is what that read costs *per run of this
+// size*, because an entry-read token rides every request as cached context. Printed rather than
+// assumed, so a reader checks the assumption instead of guessing it (joshuafolkken/kit#2289).
+const PREMISE = `  $ = cost per run, assuming a ${String(read_set_pricing.ASSUMED_REQUESTS)}-request run (each entry-read token re-read from cache per request)`
+const USAGE = 'Usage: josh read:set [<entry>] [--json]'
+const WHOLE_LABEL = 'whole — every referenced file read in full'
+const SCOPED_LABEL = 'scoped — referenced sections only'
+const TOTAL_READ_LABEL = 'total read — scoped entry plus point-of-use reached'
+const SECTION_LABEL = '-- sections referenced out of the set --'
+const POINT_OF_USE_LABEL = '-- read at the point of use, not at the entry --'
+// **The dispatched lane child reads a trimmed `fullrun` set** — the point-of-use documents the parent
+// owns are dropped and the entry-only `SKILL.md` sections are read section by section, so `total read`
+// falls well below a normal `fullrun`'s (joshuafolkken/kit#2021).
+const LANE_CHILD_NOTE: ReadonlyArray<string> = [
+	'  a dispatched lane child (`JOSH_LANE_CHILD`) reads this trimmed set:',
+	'  - skips the point-of-use documents the parent owns — child dispatch, lane opening, the progress watcher and the hand-off',
+	'  - omits SKILL.md §0/§2a/§2b/§2c/§2e/§2i/§3 — dispatch already authorized the run and a leaf child never uses them',
+]
+// **The `backlogrun` parent reads a trimmed set of its own** — a scheduler that never implements, so
+// the implementer-only `SKILL.md` sections are read section by section rather than whole
+// (joshuafolkken/kit#2256). A *different* trim from the lane child's: the parent keeps §0/§2b/§2c/§2e/
+// §2i, which are the scheduler's own, and drops no point-of-use document.
+const BACKLOGRUN_PARENT_NOTE: ReadonlyArray<string> = [
+	'  the backlogrun parent (scheduler) reads this trimmed set:',
+	'  - omits SKILL.md §2a/§2f/§2g/§3 — the parent never implements, so it claims no tree and files no `into` target',
+	'  - keeps every point-of-use document — the parent is the one dispatching children and running lanes',
+]
+const FETCH_RULE =
+	'fetch: one `Read` call per file — never `cat`, and never two files in one command.'
+const OVER_CAP_NOTE = '   Read (over the Bash cap)'
+const UNDER_CAP_NOTE = '   Read'
+
+function to_number(value: number): string {
+	return value.toLocaleString('en-US').padStart(NUMBER_WIDTH)
+}
+
+// The per-run dollar cost of a row, from its token count. Priced by `read-set-pricing`, which reads
+// `cost-pricing.ts`'s rates rather than carrying its own, so this column never becomes a second price
+// list (joshuafolkken/kit#2289).
+function to_dollars(tokens: number): string {
+	return `$${read_set_pricing.dollars_per_run(tokens).toFixed(DOLLAR_DECIMALS)}`.padStart(
+		DOLLAR_WIDTH,
+	)
+}
+
+// The column is sized from the longest label in this report rather than from a constant: the section
+// labels carry a file name *and* a heading, so a fixed width pushed them past it and the `tok` / `B`
+// columns stopped lining up with the file rows above (joshuafolkken/kit#1776 review round 1).
+function row(
+	label: string,
+	cost: { tokens: number; bytes: number },
+	width: number,
+	note = '',
+): string {
+	return `  ${label.padEnd(width)}${to_number(cost.tokens)} tok ${to_number(cost.bytes)} B ${to_dollars(cost.tokens)}${note}`
+}
+
+// **The tool is printed per file rather than left to be judged, and it is `Read` on every row.** A
+// file larger than the Bash output cap cannot be delivered by `cat` at all — what comes back is a
+// middle-truncated preview, which is how one measured entry paid for the same five files twice
+// (joshuafolkken/kit#1797) — and a file under the cap is still fetched with `Read`, because the rule
+// beneath the report is one `Read` per file rather than a size judgement made row by row. Printing
+// `cat` as an option for the small rows would have the report contradict its own closing line the
+// first time anyone raised `BASH_MAX_OUTPUT_LENGTH` past the smallest document in the set.
+function fetch_note(bytes: number, cap: number): string {
+	return bytes > cap ? OVER_CAP_NOTE : UNDER_CAP_NOTE
+}
+
+function section_label(section: SectionCost): string {
+	const mark = section.is_resolved ? '' : ' (unresolved — charged whole)'
+
+	return `${section.file} → "${section.heading}"${mark}`
+}
+
+function point_of_use_label(section: SectionCost): string {
+	return section.heading === '' ? section.file : section_label(section)
+}
+
+function saved_percent(report: ReadSetCost): number {
+	if (report.whole.tokens === NOTHING) return NOTHING
+
+	return Math.round(((report.whole.tokens - report.scoped.tokens) / report.whole.tokens) * PERCENT)
+}
+
+function labels_of(report: ReadSetCost): Array<string> {
+	return [
+		...report.files.map((entry) => entry.file),
+		...report.sections.map((section) => section_label(section)),
+		...report.point_of_use.map((entry) => point_of_use_label(entry)),
+		WHOLE_LABEL,
+		SCOPED_LABEL,
+		TOTAL_READ_LABEL,
+	]
+}
+
+// **The total the entry actually reads**: the scoped entry plus each point-of-use section (or whole
+// file where no section is named). It is the figure a before/after compares — a lane
+// child's set is smaller here, not in `scoped` alone (joshuafolkken/kit#2021).
+function total_read(report: ReadSetCost): { tokens: number; bytes: number } {
+	return entry_read_set.total([report.scoped, ...report.point_of_use.map((one) => one.cost)])
+}
+
+function label_width(report: ReadSetCost): number {
+	return Math.max(...labels_of(report).map((label) => label.length)) + LABEL_GUTTER
+}
+
+function file_lines(report: ReadSetCost, width: number): Array<string> {
+	return report.files.map((entry) =>
+		row(entry.file, entry.cost, width, fetch_note(entry.cost.bytes, report.bash_output_cap)),
+	)
+}
+
+// **What left the entry read is listed, never dropped.** Each row names the whole document or the
+// operational section fetched by the command whose turn reaches it.
+function point_of_use_lines(report: ReadSetCost, width: number): Array<string> {
+	if (report.point_of_use.length === NOTHING) return []
+
+	return [
+		`  ${POINT_OF_USE_LABEL}`,
+		...report.point_of_use.map((entry) => row(point_of_use_label(entry), entry.cost, width)),
+	]
+}
+
+function fetch_lines(report: ReadSetCost): Array<string> {
+	const cap = report.bash_output_cap.toLocaleString('en-US')
+
+	// **Scoped to the rows that carry the marker, not to every row.** Every row is marked `Read`, so a
+	// sentence keyed on the word `Read` would claim a `cat` truncates files that are well under the
+	// cap — the contradiction round 1 found on the row, relocated to the closing line.
+	return [
+		`  ${FETCH_RULE}`,
+		`  A Bash result is truncated past ${cap} characters, so a \`cat\` of any file marked`,
+		`  \`${OVER_CAP_NOTE.trim()}\` returns a preview rather than the file, and it is then read a second time.`,
+		'',
+	]
+}
+
+// **The per-reference rows can overlap, and the total below does not.** Two references into one file
+// are charged once between them, so these rows are what each pointer names rather than addends of
+// `scoped`.
+function section_lines(report: ReadSetCost, width: number): Array<string> {
+	if (report.sections.length === NOTHING) return []
+
+	return [
+		`  ${SECTION_LABEL}`,
+		...report.sections.map((section) => row(section_label(section), section.cost, width)),
+	]
+}
+
+function total_lines(report: ReadSetCost, width: number): Array<string> {
+	const saved = report.whole.tokens - report.scoped.tokens
+
+	return [
+		'',
+		row(WHOLE_LABEL, report.whole, width),
+		row(SCOPED_LABEL, report.scoped, width),
+		row(TOTAL_READ_LABEL, total_read(report), width),
+		`  saved by reading sections: ${saved.toLocaleString('en-US')} tok (${String(saved_percent(report))}%)`,
+		'',
+	]
+}
+
+function note_lines(report: ReadSetCost): Array<string> {
+	if (report.entry === lane_child_read_set.LANE_CHILD) return [...LANE_CHILD_NOTE, '']
+
+	if (report.entry === BACKLOGRUN) return [...BACKLOGRUN_PARENT_NOTE, '']
+
+	return []
+}
+
+function report_lines(report: ReadSetCost): Array<string> {
+	const width = label_width(report)
+
+	return [
+		`entry: ${report.entry}`,
+		PREMISE,
+		...note_lines(report),
+		...file_lines(report, width),
+		...section_lines(report, width),
+		...point_of_use_lines(report, width),
+		...total_lines(report, width),
+		...fetch_lines(report),
+	]
+}
+
+// **`lane-child` is a synthetic entry, not a table keyword.** It is not a keyword a person types, so
+// it stays out of `SKILL.md`'s "1. Which file to read" table and out of `entry_read_set.entries()`
+// (whose derivation the rule tests pin); the CLI adds it to the list it offers and validates against.
+function known_entries(root: string): Array<string> {
+	return [...entry_read_set.entries(root), lane_child_read_set.LANE_CHILD]
+}
+
+function wanted_entries(argv: ReadonlyArray<string>, root: string): Array<string> {
+	const named = argv.filter((value) => !value.startsWith(FLAG_PREFIX))
+
+	return named.length > NOTHING ? named : known_entries(root)
+}
+
+// **An unrecognized keyword is refused, never reported on.** Left to fall through it produced a
+// complete, plausible report — the skill file, the gate documents, `whole` equal to `scoped` and a
+// saving of zero — and exited 0, answering "nothing to save" instead of
+// "no such entry" for a mistyped keyword (joshuafolkken/kit#1776 review round 1). That is the silent wrong answer
+// `doc:section` refuses for an unresolvable heading, and this is the same refusal.
+function unknown_entries(wanted: ReadonlyArray<string>, root: string): Array<string> {
+	const known = known_entries(root)
+
+	return wanted.filter((entry) => !known.includes(entry))
+}
+
+function costed_entry(root: string, entry: string): ReadSetCost {
+	if (entry === lane_child_read_set.LANE_CHILD) return lane_child_read_set.costed(root)
+
+	if (entry === BACKLOGRUN) return backlogrun_parent_read_set.costed(root)
+
+	return entry_read_set.costed(root, entry)
+}
+
+function printed(reports: ReadonlyArray<ReadSetCost>, is_json: boolean): string {
+	if (is_json) return JSON.stringify(reports, undefined, JSON_INDENT)
+
+	return reports.flatMap((report) => report_lines(report)).join('\n')
+}
+
+function run(argv: ReadonlyArray<string>, root: string = process.cwd()): number {
+	const wanted = wanted_entries(argv, root)
+	const unknown = unknown_entries(wanted, root)
+
+	if (wanted.length === NOTHING || unknown.length > NOTHING) {
+		console.error(`${USAGE}\nKnown entries: ${known_entries(root).join(', ')}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reports = wanted.map((entry) => costed_entry(root, entry))
+
+	console.info(printed(reports, argv.includes(JSON_FLAG)))
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const read_set_cli = {
+	FETCH_RULE,
+	JSON_FLAG,
+	POINT_OF_USE_LABEL,
+	SCOPED_LABEL,
+	TOTAL_READ_LABEL,
+	USAGE,
+	WHOLE_LABEL,
+	known_entries,
+	main,
+	run,
+	saved_percent,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { read_set_cli }

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

@@ -0,0 +1,89 @@
+// Which documents a workflow entry point names but reads only later — point-of-use, not entry read
+// (joshuafolkken/kit#1776, split out of `entry-read-set.ts` in joshuafolkken/kit#2289 to keep that
+// file under its line ceiling and to keep the point-of-use classification its own concern from the
+// costing that reads it).
+//
+// **Four documents leave the entry read because their first use is a named command, not the entry**
+// (joshuafolkken/kit#1797, joshuafolkken/kit#1856, joshuafolkken/kit#1873). `latest-gate.md` is read
+// when `pnpm josh latest:scope` answers `required`, `followup.md` in the turn that issues
+// `pnpm josh followup`, `chain-rule.md` before the first `pnpm josh gate` launch it governs
+// (joshuafolkken/kit#2296 — the section is how that gate starts, overlapped with the review), and
+// `background-commands.md` before the first backgroundable command (`pnpm josh gate`). **They are
+// not deferred or summarized** — the named operational section is fetched in the same turn; only
+// `latest-gate.md` remains whole because its result branches across that document.
+// Measured on `fullrun #1783`, `followup.md` rode 55 requests before its first use. **`chain-rule.md`
+// is joshuafolkken/kit#1856's addition**: it governs the `/code-review` → `followup` chain, which in
+// `fullrun` / `queue` / `epicrun` / `backlogrun` runs *after* the first edit, so its 7,396 tokens
+// were resident from the entry for no run that had yet reached a review.
+// **`background-commands.md` is joshuafolkken/kit#1873's**: it was §2h's resident body, governing the
+// background execution of the gate, the push and the merge tail — all after the first edit — so it
+// left `SKILL.md` for the point-of-use list. `SKILL.md` → §1, "Four documents are read at the point
+// of use", is the single source.
+// **`backlogrun`'s own per-child phase documents are point-of-use too** (joshuafolkken/kit#2010):
+// `backlogrun.md` was split so the entry read carries only what binds before the first child, and the
+// four phase documents below are read from it at the step each names — dispatching a child, opening a
+// lane, the progress watcher and the hand-off, a child that cannot finish — never at the entry. Kept
+// out of the count here, exactly as the four above are. `SKILL.md` → §1 is the human source.
+// **`backlogrun-steps.md` joins them** (joshuafolkken/kit#2190): `backlogrun.md` was cut to a manifest
+// and its detailed procedure moved into `backlogrun-steps.md`, read on demand rather than at the
+// entry. Counting the manifest's pointers into it would put that prose straight back into the entry
+// figure under another name, which is exactly what this reduction removes.
+// **`pre-gate-cut.md` joins them** (joshuafolkken/kit#2289): it is the single source of the pre-gate
+// cut, a step every implementing run — and every dispatched lane child — reaches after the entry, so
+// its read is a point-of-use read the count was silently omitting. Measured on the backlogrun of
+// 2026-09-21, the lane children read it 21 times across 13 runs — the largest single document read,
+// and the one the point-of-use list had no row for.
+const POINT_OF_USE_FILES: ReadonlySet<string> = new Set([
+	'latest-gate.md',
+	'followup.md',
+	'chain-rule.md',
+	'background-commands.md',
+	'pre-gate-cut.md',
+	'backlogrun-child.md',
+	'backlogrun-lanes.md',
+	'backlogrun-progress.md',
+	'backlogrun-park.md',
+	'backlogrun-steps.md',
+	// Read only when `run:step` prints `pnpm josh retrospective` at a run's stop position — the very
+	// end of a run, never the entry (joshuafolkken/kit#2328). Kept out of every entry's read for the
+	// same reason the phase documents above are: no run that never drains its backlog reaches it.
+	'retrospective.md',
+])
+
+// **A file an entry names but reads only later — point-of-use for that entry, an entry read for
+// another** (joshuafolkken/kit#2161). The global set above cannot express this, because a file
+// dropped there leaves *every* entry's read. The four ordinary entries read the decision documents
+// only when delegation or filing arises; the lane child omits their SKILL.md sections. `backlogrun`'s
+// parent additionally reads `fullrun.md` and `split-assessment.md` inside a dispatched child, while
+// `fullrun`, `halfrun` and `kickoff` read them at their own entries.
+const DEFERRED_DECISIONS: ReadonlySet<string> = new Set(['delegation.md', 'issue-scout.md'])
+
+const POINT_OF_USE_BY_ENTRY: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+	['kickoff', DEFERRED_DECISIONS],
+	['fullrun', DEFERRED_DECISIONS],
+	['halfrun', DEFERRED_DECISIONS],
+	['backlogrun', new Set([...DEFERRED_DECISIONS, 'fullrun.md', 'split-assessment.md'])],
+])
+
+const NO_PER_ENTRY_FILES: ReadonlySet<string> = new Set()
+
+// **A file is point-of-use for an entry when the global set names it, or the per-entry map does.**
+function is_point_of_use(entry: string, file: string): boolean {
+	if (POINT_OF_USE_FILES.has(file)) return true
+
+	return (POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES).has(file)
+}
+
+// The global point-of-use files plus the ones this entry names in its own row.
+function point_of_use_files(entry: string): Array<string> {
+	return [...POINT_OF_USE_FILES, ...(POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES)]
+}
+
+const read_set_point_of_use = {
+	POINT_OF_USE_FILES,
+	POINT_OF_USE_BY_ENTRY,
+	is_point_of_use,
+	point_of_use_files,
+}
+
+export { read_set_point_of_use }

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

@@ -0,0 +1,52 @@
+// What a document read at a workflow entry costs, in dollars, for one run (joshuafolkken/kit#2289).
+//
+// **The dollars are not "tokens x one rate".** A token read at the entry is not paid once — it rides
+// every later request of the run as cached context, so its cost is the per-token cache-read rate
+// times the number of requests the run makes. Measured on the backlogrun of 2026-09-21: 13 runs
+// averaged 118 requests each, cache reads were 52% of billed input, and the fresh information a run
+// took in was 0.8% of what it was billed for. Reading `read:set` as tokens alone hid this — the
+// reader had to multiply by the request count and the rate in their head to judge whether a document
+// was worth moving off the entry read.
+//
+// **The rate is not defined here.** The per-million-token input rate and the cache-read multiplier
+// come from `cost-pricing.ts` — the same constants `josh cost` and `josh time` price a run with — so
+// there is no second price list to drift. This file is the model (a token rides every request as a
+// cache read) and the one assumption the model needs (how many requests a run makes); the arithmetic
+// is `cost_pricing.estimate_cost`'s.
+
+import { cost_pricing } from '#scripts/cost-runtime/cost-pricing'
+import { cost_usage } from '#scripts/cost-runtime/cost-usage'
+
+// The run size the dollar figure assumes, and the model it is priced against. The number is the
+// measured mean of the 2026-09-21 backlogrun (epic #2280); `read:set` prints it as its stated premise
+// so a reader can check the assumption rather than trust it. A run twice this size costs twice as
+// much per entry-read token, so the figure is "per run of this size", never an absolute.
+const ASSUMED_REQUESTS = 118
+
+// The model these runs execute on. Its base input rate and the cache-read multiplier are read from
+// the price table rather than written here, so the dollar figure tracks any price change with no edit
+// to this file.
+const REFERENCE_MODEL = 'claude-opus-4-8'
+
+// A token read at the entry is written to cache once and then read back on every request. Modelled as
+// a pure cache read across the run — the one-time write is under 1% of the total and folding it in
+// would only obscure the term that dominates the cost — so the run's cost of holding `tokens` of
+// entry-read context is `tokens x ASSUMED_REQUESTS` cache-read tokens, priced by the reference model.
+function dollars_per_run(tokens: number): number {
+	const price = cost_pricing.resolve_price(REFERENCE_MODEL)
+
+	if (price === undefined) return 0
+
+	return cost_pricing.estimate_cost(
+		{ ...cost_usage.EMPTY_TOTALS, cache_read_tokens: tokens * ASSUMED_REQUESTS },
+		price,
+	)
+}
+
+const read_set_pricing = {
+	ASSUMED_REQUESTS,
+	REFERENCE_MODEL,
+	dollars_per_run,
+}
+
+export { read_set_pricing }

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

@@ -0,0 +1,78 @@
+// Trimming a base entry's read set by role (joshuafolkken/kit#2256).
+//
+// **A dispatched lane child (the worker) and a `backlogrun` parent (the scheduler) both read a trimmed
+// version of a base entry.** The worker trims `fullrun` (`lane-child-read-set.ts`); the parent trims
+// `backlogrun` (`backlogrun-parent-read-set.ts`). Both do the same two things: the `SKILL.md` sections
+// that role never uses are read at the section level rather than whole, and — where the role owns no
+// point-of-use document — those are dropped too. This is the one mechanism the two derivations share,
+// single-sourced here rather than cloned; each supplies its own base entry, label, unused sections and
+// skipped point-of-use set.
+//
+// **Deriving off the base entry's own figures keeps each honest** — a row that moves in the base set
+// moves here with it — and leaves the whole of `entry-read-set.ts` untouched (joshuafolkken/kit#2021
+// decided this against reshaping `SKILL.md` itself, which every entry point would have paid for).
+
+import { document_section } from './document-section'
+import { entry_read_set, type Cost, type FileCost, type ReadSetCost } from './entry-read-set'
+
+interface TrimSpec {
+	// The table entry whose read set is trimmed — `fullrun` for the worker, `backlogrun` for the parent.
+	base_entry: string
+	// The label the trimmed set reports as; `lane-child` for the worker, `backlogrun` for the parent.
+	label: string
+	// The `SKILL.md` sections this role never uses, read at the section level rather than in full.
+	unused_skill_sections: ReadonlyArray<string>
+	// The point-of-use documents this role's parent owns; empty when the role owns them all.
+	skipped_point_of_use: ReadonlySet<string>
+}
+
+function subtract(left: Cost, right: Cost): Cost {
+	return { bytes: left.bytes - right.bytes, tokens: left.tokens - right.tokens }
+}
+
+function skill_text(root: string): string {
+	const path = entry_read_set.document_path(root, entry_read_set.SKILL_FILE)
+
+	return document_section.read_optional(path) ?? ''
+}
+
+// An unresolved heading is charged at zero rather than at its whole file: unlike the entry read's own
+// section measurement, a miss here would *under*-count the trim, so each derivation's test pins that
+// its sections resolve and this stays a safe fallback rather than the expected path.
+function section_cost(text: string, heading: string): Cost {
+	return entry_read_set.cost_of(document_section.section(text, heading)?.text ?? '')
+}
+
+function unused_skill_cost(root: string, sections: ReadonlyArray<string>): Cost {
+	const text = skill_text(root)
+
+	return entry_read_set.total(sections.map((heading) => section_cost(text, heading)))
+}
+
+// The saving lands entirely on the `SKILL.md` row, so every other file is returned unchanged.
+function reduce_skill(file: FileCost, saving: Cost): FileCost {
+	if (file.file !== entry_read_set.SKILL_FILE) return file
+
+	return { file: file.file, cost: subtract(file.cost, saving) }
+}
+
+// **`whole` and `scoped` both carry the own-files cost identically**, so the `SKILL.md` saving lands
+// on each by the same amount — there is no need to re-derive the referenced-section split.
+function costed(root: string, spec: TrimSpec): ReadSetCost {
+	const base = entry_read_set.costed(root, spec.base_entry)
+	const saving = unused_skill_cost(root, spec.unused_skill_sections)
+
+	return {
+		...base,
+		entry: spec.label,
+		files: base.files.map((file) => reduce_skill(file, saving)),
+		point_of_use: base.point_of_use.filter((one) => !spec.skipped_point_of_use.has(one.file)),
+		whole: subtract(base.whole, saving),
+		scoped: subtract(base.scoped, saving),
+	}
+}
+
+const read_set_trim = { costed, unused_skill_cost }
+
+export type { TrimSpec }
+export { read_set_trim }