@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/document/document-section-cli.ts

@@ -6,18 +6,16 @@ import { capped_output } from './capped-print'
 import { document_section } from './document-section'
 import { entry_read_set } from './entry-read-set'
 
-// `josh doc:section` — print one section of a markdown document (joshuafolkken/kit#1776).
+// `josh doc:section` — print one section of a markdown document.
 //
-// **It exists because the documents already cite each other by section and the reader could only
-// fetch files.** `` `backlogrun-progress.md` → "The hand-off" `` names 249 lines; opening
-// `backlogrun-progress.md` costs far more. Every entry point pays that difference at the moment it
-// starts, before anything has been implemented.
+// **It exists because the documents cite each other by section.** `` `backlogrun-progress.md` →
+// "The hand-off" `` names one section; opening `backlogrun-progress.md` costs far more. Every entry
+// point would pay that difference at the moment it starts, before anything has been implemented.
 //
 // **What it is not is a summary.** The section is printed verbatim, headings and all, so a run that
 // reads a section has read the same words a run that opened the file would have. Nothing is deferred
 // and nothing is condensed — the extent of the read changes, not its content, which is why this is
-// not the "read it later" scheme joshuafolkken/kit#1344 and joshuafolkken/kit#1460 each measured
-// never firing.
+// not a "read it later" scheme, which never fires.
 //
 // **A heading that does not resolve is a refusal, not an empty answer.** A pointer whose target was
 // renamed would otherwise print nothing and read as a section with nothing in it — the one outcome
@@ -36,7 +34,7 @@ const USAGE = 'Usage: josh doc:section <file.md> "<heading>"'
 // **Every branch resolves against `root`, including the first.** Left relative to the process's own
 // directory, a bare name that happened to exist beside the caller would beat the document under
 // `root` and print a section of the wrong file — silently, which is the failure this command exists
-// to refuse (joshuafolkken/kit#1776 review round 2).
+// to refuse.
 function resolve_document(name: string, root: string = process.cwd()): string {
 	const named = path.resolve(root, name)
 

package/scripts/document/document-section.ts

@@ -1,16 +1,13 @@
 // Reading one **section** of a markdown document, because a section is the unit these documents
-// cross-reference each other in (joshuafolkken/kit#1776).
+// cross-reference each other in.
 //
-// **The reference form was already a section reference, and only the reader was missing.** Every
-// workflow document points at another one as `` `backlogrun-progress.md` → "The hand-off" `` — a file
-// *and* a heading. A reader with no way to fetch a heading has one move left, which is to open the
-// file, so a pointer at 249 lines was costing 2,121. `backlogrun.md` and its point-of-use phase
-// documents are opened for many such references and are among the largest items an entry reads.
+// **The reference form is a section reference.** Every workflow document points at another one as
+// `` `backlogrun-progress.md` → "The hand-off" `` — a file *and* a heading. A reader with no way to
+// fetch a heading has one move left, which is to open the whole file.
 //
 // **Nothing here defers a read.** The section is fetched in the same turn, in the main line, by the
-// run that has to obey it — what changes is the extent of the fetch, never whether it happens. That
-// is the distinction joshuafolkken/kit#1344 and joshuafolkken/kit#1460 were written after: a rule
-// moved to "read it later" is a rule that measurably never fires, and this moves nothing to later.
+// run that has to obey it — what changes is the extent of the fetch, never whether it happens. A rule
+// moved to "read it later" is a rule that never fires, and this moves nothing to later.
 
 import { file_reader } from '#scripts/lib/read-file'
 import { document_scan } from './document-scan'
@@ -54,8 +51,7 @@ function to_heading(line: string, index: number): Heading | undefined {
 	if (groups === undefined) return undefined
 
 	// Destructured rather than read as properties: `noPropertyAccessFromIndexSignature` refuses
-	// `groups.title`. The bracket form was refused too, until joshuafolkken/kit#1783 switched off the
-	// `dot-notation` fix that rewrote it back — so this is a choice now rather than the only spelling.
+	// `groups.title`.
 	const { hashes = '', title = '' } = groups
 
 	return { level: hashes.length, title: title.trim(), line: index }
@@ -109,7 +105,7 @@ 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
+// **A bold label is an anchor too**. 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.

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

@@ -4,8 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { document_section } from './document-section'
 
-// `josh edit:files <plan-path>` — apply several content-addressed edits in one call
-// (joshuafolkken/kit#2366).
+// `josh edit:files <plan-path>` — apply several content-addressed edits in one call.
 //
 // **This is the write-side counterpart of `read:files`, and it reverses what kit#2202 rejected.**
 // kit#2202 folded the pre-edit *reads* into one call and left the edits to native multiple `Edit`
@@ -25,12 +24,12 @@ import { document_section } from './document-section'
 // order against the running text; if any of them fails to match, that file is left exactly as it was
 // and its failures are named. So a partial plan never leaves a file half-edited.
 //
-// **Only independent edits are folded (joshuafolkken/kit#2493).** An edit whose original range overlaps
+// **Only independent edits are folded.** An edit whose original range overlaps
 // an earlier edit's of the same file, or whose match count that earlier edit changed, depends on it — it
 // addresses text that edit rewrote, removed or duplicated — and is refused as `dependent`. Such an edit is
 // issued on its own after the batch, so a fold never hides an ordering the author did not see.
 //
-// **`-` reads the plan from standard input (joshuafolkken/kit#2493)**, so a lane child passes its edits
+// **`-` reads the plan from standard input**, so a lane child passes its edits
 // in the one call as a quoted heredoc (`pnpm josh edit:files - <<'EDITS'`) instead of writing a plan file
 // first — the quoted delimiter expands nothing, and the call carries the old/new pairs an `Edit` would.
 

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

@@ -1,5 +1,5 @@
 // The byte ceiling on what each workflow entry reads before it starts — the primary budget, a
-// ratchet like the per-document one (joshuafolkken/kit#2257).
+// ratchet like the per-document one.
 //
 // **The per-document ceiling was a proxy for a run's cost, not the cost.** A run does not pay "one
 // document's size"; it pays the total its entry reads — the mandated skill files, the sections they
@@ -10,7 +10,7 @@
 // documents no entry reads (`document-reachability.ts` draws the line). A document an entry reads is
 // held by the entry total and carries no per-document ceiling, so neither budget holds it twice.
 //
-// THE CEILING IS BLOCK-QUANTIZED, exactly as the per-document one is (joshuafolkken/kit#2231): an
+// THE CEILING IS BLOCK-QUANTIZED, exactly as the per-document one is: an
 // entry total is one number, so recording its raw size would make every lane that nudges a covered
 // document bump this shared line. The recorded ceiling is the smallest `BLOCK_BYTES` multiple at or
 // above the measured total, so growth within a block needs no edit and a crossing bumps to the same
@@ -44,74 +44,12 @@ interface EntryBudget {
 // size. Names exactly the entries `known_entries` offers: the test fails on a stale entry and on an
 // entry with no row, so the definition cannot rot as entries are added or removed.
 const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
-	// Raised in joshuafolkken/kit#2289 when `pre-gate-cut.md` joined the point-of-use set: its ~29KB
-	// read is a point-of-use read every entry's total now counts, a correction of an under-count rather
-	// than new reading. Raised again in joshuafolkken/kit#2282 when the same document grew by its
-	// status-quo decision record, and once more in joshuafolkken/kit#2295 when it recorded the
-	// recent-context hand-off. Lowered in joshuafolkken/kit#2294 — the FIRST downward move on this
-	// ratchet — when `pre-gate-cut.md` was compressed (37,786 B → ~20,300 B): every entry that reads it
-	// crossed a block downward, so the recorded ceilings drop to the block multiples the stale-ratchet
-	// message named rather than staying loose above the reduction. `kickoff` and the lane child rose one
-	// block again in joshuafolkken/kit#2312 when `pre-gate-cut.md` recorded the resume-side cost the
-	// conditional cut is built on; the other entries stayed within their block. `backlogrun` rose one
-	// 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 `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
-	// `retrospective.md` (which the lane child skips) and a one-line pointer in `backlogrun-steps.md`, so
-	// every entry stayed within its block rather than climbing back to a pre-#2294 ceiling the downward
-	// ratchet holds shut. joshuafolkken/kit#2342 added the `--summary` close to `retrospective.md` in a
-	// single sentence, kept short so every entry that reads it stays within its block.
-	// Lowered for the lane child in joshuafolkken/kit#2357 — a downward move on this ratchet — when
-	// `backlogrun-steps.md` left the child's point-of-use set: the child never opened the scheduler's step
-	// 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-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).
-	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
-	// planning entries): kickoff has no headroom, so the addition was offset by tightening that file's
-	// heartbeat prose, keeping every entry within its existing block.
-	// joshuafolkken/kit#2762 moved the rationale of five point-of-use documents to
-	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction. joshuafolkken/kit#2895 did
-	// the same for eight more, lowering fullrun, halfrun and backlogrun one block each.
-	// joshuafolkken/kit#2998 split the command reference, so every reference to an automation command
-	// now names `josh-commands-automation.md`; the longer path tipped backlogrun one block over.
-	// joshuafolkken/kit#2994 moved `CLAUDE.md`'s explanations to `docs/maintainers/claude-md-history.md`,
-	// lowering backlogrun one block; kickoff's reduction was offset by joshuafolkken/kit#3024's longer
-	// `wip-cap.md`, so its ceiling stays.
-	// joshuafolkken/kit#3023 added the `prrun` keyword to `SKILL.md` and `CLAUDE.md`, tipping backlogrun
-	// one block over; `prrun` reads `fullrun`'s set plus its own short manifest.
-	// Lowered in joshuafolkken/kit#3078 — a correction of an over-count, not a trim: every entry was
-	// charged for every global point-of-use document, so `kickoff` paid for `followup.md` and the
-	// `backlogrun-*` phase documents it never opens. Each total now counts only what its path reaches.
-	// joshuafolkken/kit#3077 trimmed non-resident rule bodies from `CLAUDE.md`, lowering fullrun, prrun
-	// and backlogrun one block each.
-	// 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.
-	// 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: 53_248 },
-	{ entry: 'prrun', bytes: 61_440 },
-	{ entry: 'backlogrun', bytes: 176_128 },
-	{ entry: LANE_CHILD, bytes: 57_344 },
+	{ entry: 'kickoff', bytes: 36_864 },
+	{ entry: 'fullrun', bytes: 53_248 },
+	{ entry: 'halfrun', bytes: 49_152 },
+	{ entry: 'prrun', bytes: 57_344 },
+	{ entry: 'backlogrun', bytes: 90_112 },
+	{ entry: LANE_CHILD, bytes: 49_152 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

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

@@ -1,5 +1,4 @@
-// What a workflow entry point reads before it does anything, and what that costs
-// (joshuafolkken/kit#1776).
+// What a workflow entry point reads before it does anything, and what that costs.
 //
 // **The entry read was the largest fixed cost a run had, and nothing measured it.** Measured on the
 // `queue` parent of 2026-09-11: 159,323 billed input tokens per request at 16 requests, with the
@@ -28,13 +27,15 @@ 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
+// How `read:set` names the union a point-of-use document is charged at: `file → "A" + "B"`.
+const HEADING_JOINER = '" + "'
 
 // 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
+// is its own concern, held in `read-set-point-of-use.ts`. This file
 // reads that classification to drop those files from the entry read and to cost them separately.
 
 // The fetch cap a `cat` truncates at, and the harness default it falls back to, are read from
-// `bash-output-cap.ts` — split out in joshuafolkken/kit#2161 to keep this file under its line ceiling.
+// `bash-output-cap.ts`.
 // `section()` hands back a `##` heading's `###` children with it, so the table parse has to say
 // where it stops — see `table_rows`.
 const SUBSECTION_PREFIX = '### '
@@ -120,12 +121,6 @@ function unique(names: ReadonlyArray<string>): Array<string> {
 
 // **Scanned with `exec` rather than collected from `matchAll`.** A fresh `RegExp` rather than the
 // shared one, so the caller's `lastIndex` is never carried between two scans of different documents.
-//
-// This spelling used to be forced rather than chosen: `unicorn/prefer-iterator-to-array` rejected
-// the spread while the `--fix` for a `for…of` push loop put the spread straight back, so neither
-// form was green. joshuafolkken/kit#1783 removed that contradiction — the spread is accepted now —
-// and rewriting this helper was left outside that Issue's scope, so the loop stands on the
-// `lastIndex` isolation above alone.
 function all_matches(text: string, pattern: RegExp): Array<RegExpExecArray> {
 	const scanner = new RegExp(pattern.source, pattern.flags)
 	const found: Array<RegExpExecArray> = []
@@ -153,8 +148,7 @@ function columns_of(line: string): { entry: string; files: string } | undefined
 	if (groups === undefined) return undefined
 
 	// Destructured rather than read as properties: `noPropertyAccessFromIndexSignature` refuses
-	// `groups.entry`. The bracket form was refused too, until joshuafolkken/kit#1783 switched off the
-	// `dot-notation` fix that rewrote it back — so this is a choice now rather than the only spelling.
+	// `groups.entry`.
 	const { entry = '', files = '' } = groups
 
 	return { entry, files }
@@ -181,11 +175,9 @@ function push_row(rows: Map<string, ReadonlyArray<string>>, line: string): void
 // section: every other table in the document would otherwise contribute rows of its own.
 //
 // **And it stops at the section's first subsection.** `section()` returns a `##` heading's `###`
-// children with it, and joshuafolkken/kit#1797 put a second two-column table under one of them — the
-// point-of-use triggers. Its rows parse as entry rows, and only the "no `.md` in the second column"
-// guard kept `latest`, `eval` and `followup` out of the keyword set; one edit adding a document name
-// to a trigger cell would have registered them as entry points. The stop makes that explicit rather
-// than incidental.
+// children with it, and one of them holds a second two-column table — the point-of-use triggers.
+// Its rows would parse as entry rows, and one edit adding a document name to a trigger cell would
+// register them as entry points. The stop makes that explicit rather than incidental.
 function table_rows(root: string): Map<string, ReadonlyArray<string>> {
 	const rows = new Map<string, ReadonlyArray<string>>()
 	const found = document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)
@@ -226,7 +218,7 @@ function is_sibling_document(root: string, name: string): boolean {
 // resident on every request already, and one at a `prompts/` topic names a file reached on its own
 // step rather than at the entry.
 //
-// **A pointer into a point-of-use document is not an entry cost either** (joshuafolkken/kit#1797).
+// **A pointer into a point-of-use document is not an entry cost either**.
 // Counting one would put `followup.md` straight back into the entry figure under another name, when
 // the whole point is that the run reaches it half an hour later — and then only by fetching it whole
 // at that moment, which is a cost of that step rather than of the entry.
@@ -327,38 +319,62 @@ function file_costs(root: string, names: ReadonlyArray<string>): Array<FileCost>
 	return names.map((file) => ({ file, cost: cost_of(read_document(root, file)) }))
 }
 
+// **A point-of-use document is charged at the union of the sections its entry's path names, and whole
+// only where nothing names a section**. `SKILL.md` → §1 makes a pointer
+// written `` `X.md` → "Heading" `` a read of that section alone, so a route table whose every row names
+// one section reads those sections, never the file — and charging the file anyway made a router that
+// trims its routes measure exactly as heavy as one that reads everything.
 function point_of_use_cost(
 	root: string,
 	file: string,
 	references: ReadonlyArray<SectionReference>,
 ): SectionCost {
-	const reference = references.find((one) => one.file === file)
+	const markdown = read_document(root, file)
+	const headings = unique(references.filter((one) => one.file === file).map((one) => one.heading))
 
-	if (reference !== undefined) return section_cost(root, reference)
+	if (headings.length === NOTHING) {
+		return { file, heading: '', cost: cost_of(markdown), is_resolved: true }
+	}
 
-	return { file, heading: '', cost: cost_of(read_document(root, file)), is_resolved: true }
+	return {
+		file,
+		heading: headings.join(HEADING_JOINER),
+		cost: scoped_file_cost(markdown, headings),
+		is_resolved: headings.every(
+			(heading) => document_section.section(markdown, heading) !== undefined,
+		),
+	}
 }
 
-// **What an entry's path names: its own manifests, and the §1 trigger rows that name the entry**
-// (joshuafolkken/kit#3078). `SKILL.md`'s other text is left out for the reason `sections_for` gives —
+// **What an entry's path names: its own manifests, and the §1 trigger rows that name the entry**.
+// `SKILL.md`'s other text is left out for the reason `sections_for` gives —
 // §2 names every document, so counting it would charge a `kickoff` for `followup.md`. One hop only:
 // the point-of-use documents cite one another, and following them would reach the whole set again.
-// `also` is what a role reaches beside its base entry's path (`read-set-trim.ts`).
-function cited_by(
-	root: string,
-	entry: string,
-	table_text: string,
-	also: ReadonlySet<string>,
-): Set<string> {
+function path_texts(root: string, entry: string, table_text: string): Array<string> {
 	const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE)
 	const rows = table_text
 		.split('\n')
 		.filter((line) => line.startsWith('|') && line.includes(`\`${entry}\``))
-	const texts = [...manifests.map((file) => read_document(root, file)), ...rows]
 
-	return new Set([...also, ...texts.flatMap((text) => names_in(text))])
+	return [...manifests.map((file) => read_document(root, file)), ...rows]
 }
 
+// The sections a point-of-use document is read by: every pointer in §1's table, and every one the
+// entry's own manifests carry — the route a run follows into that document.
+function point_of_use_references(
+	root: string,
+	entry: string,
+	table_text: string,
+): Array<SectionReference> {
+	const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE)
+	const texts = [table_text, ...manifests.map((file) => read_document(root, file))]
+
+	return texts.flatMap((text) =>
+		all_matches(text, SECTION_REFERENCE).map((match) => to_reference(match)),
+	)
+}
+
+// `also` is what a role reaches beside its base entry's path (`read-set-trim.ts`).
 function point_of_use_costs(
 	root: string,
 	entry: string,
@@ -366,8 +382,9 @@ function point_of_use_costs(
 ): Array<SectionCost> {
 	const table_text =
 		document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)?.text ?? ''
-	const references = all_matches(table_text, SECTION_REFERENCE).map((match) => to_reference(match))
-	const cited = cited_by(root, entry, table_text, also)
+	const references = point_of_use_references(root, entry, table_text)
+	const named = path_texts(root, entry, table_text).flatMap((text) => names_in(text))
+	const cited = new Set([...also, ...named])
 
 	return point_of_use_files(entry, cited).map((file) => point_of_use_cost(root, file, references))
 }

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

@@ -1,7 +1,7 @@
-// What a dispatched lane child reads, and what that costs (joshuafolkken/kit#2021).
+// What a dispatched lane child reads, and what that costs.
 //
 // **A lane child is the largest fixed cost a `backlogrun` has.** Measured on the batch of
-// 2026-09-13, the lane child sessions were 72% of the run's whole input (joshuafolkken/kit#1936),
+// 2026-09-13, the lane child sessions were 72% of the run's whole input,
 // and each `claude -p fullrun #N` child read the `fullrun` entry set in full — around 227KB. Most of
 // that is spent on procedure a leaf child never carries out: it dispatches no child of its own, opens
 // no lane, runs no progress watcher and performs no hand-off, so the point-of-use documents that
@@ -10,7 +10,7 @@
 // **This models the child as a trimmed `fullrun`, derived rather than transcribed.** The set is the
 // `fullrun` entry read with two subtractions — the `SKILL.md` sections a child never uses read at the
 // section level, and the point-of-use documents a leaf never reaches dropped — applied by the shared
-// `read-set-trim`, which the `backlogrun` parent trim uses too (joshuafolkken/kit#2256).
+// `read-set-trim`, which the `backlogrun` parent trim uses too.
 
 import type { ReadSetCost } from './entry-read-set'
 import { read_set_trim } from './read-set-trim'
@@ -22,7 +22,7 @@ const FULLRUN = 'fullrun'
 // 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.
+// are single rows of §2's table, 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',
 	'3. What stays resident, and what is read from here',
@@ -30,15 +30,15 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 
 // **The point-of-use documents a leaf child never reaches**: child dispatch, lane opening and the
 // progress watcher / hand-off are the parent's, so their single-source documents are dropped from
-// the child's read. **`latest-gate.md` is the parent's too** (joshuafolkken/kit#2189): the dependency
+// the child's read. **`latest-gate.md` is the parent's too**: the dependency
 // update runs once per session in the outermost run, never in a dispatched lane child (`latest:scope`
 // answers `skip` in a lane via the lane guard), so the child never opens `latest-gate.md`. The gate documents
 // (`chain-rule.md`, `background-commands.md`), `followup.md` and `backlogrun-park.md` stay — a child
 // runs the gate, opens its PR, and may park on a decision, so it does reach every one of those.
-// **`retrospective.md` is the parent's too** (joshuafolkken/kit#2328): the end-of-run retrospective
+// **`retrospective.md` is the parent's too**: the end-of-run retrospective
 // runs once at the batch's own end, never in a leaf child, so `run:step` answers `stop` for a child at
 // the stop position and the child never opens it.
-// **`backlogrun-steps.md` is the parent's too** (joshuafolkken/kit#2357): it is the scheduler's step
+// **`backlogrun-steps.md` is the parent's too**: it is the scheduler's step
 // 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
@@ -46,7 +46,7 @@ const UNUSED_SKILL_SECTIONS: ReadonlyArray<string> = [
 // 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
+// **`progress-watcher.md` is the parent's too**: 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',
@@ -62,7 +62,7 @@ const SKIPPED_POINT_OF_USE: ReadonlySet<string> = new Set([
 
 // **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). **`pre-gate-cut.md` is the child's alone** (joshuafolkken/kit#3172):
+// entry's. **`pre-gate-cut.md` is the child's alone**:
 // 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'])

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

@@ -4,8 +4,7 @@ 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).
+// `josh read:files <path> [<path> ...]` — read several files in one call.
 //
 // **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

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

@@ -5,14 +5,11 @@ import { entry_read_set, type ReadSetCost, type SectionCost } from './entry-read
 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).
+// `josh read:set` — what this entry point reads before it starts, and what that costs.
 //
-// **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.
+// **The entry cost has a reading of its own.** `josh cost` measures a whole session and cannot say
+// which part of it was the mandated read; 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.
@@ -34,7 +31,7 @@ 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).
+// assumed, so a reader checks the assumption instead of guessing it.
 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'
@@ -44,15 +41,15 @@ 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).
+// falls well below a normal `fullrun`'s.
 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/§3 — dispatch already authorized the run and a leaf child edits no rule',
 ]
 // **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, which is the
+// the implementer-only `SKILL.md` sections are read section by section rather than whole.
+// A *different* trim from the lane child's: the parent keeps §0, which is 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:',
@@ -70,7 +67,7 @@ function to_number(value: number): string {
 
 // 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).
+// list.
 function to_dollars(tokens: number): string {
 	return `$${read_set_pricing.dollars_per_run(tokens).toFixed(DOLLAR_DECIMALS)}`.padStart(
 		DOLLAR_WIDTH,
@@ -78,8 +75,8 @@ function to_dollars(tokens: number): string {
 }
 
 // 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).
+// labels carry a file name *and* a heading, so a fixed width would push them past it and the `tok` /
+// `B` columns would stop lining up with the file rows above.
 function row(
 	label: string,
 	cost: { tokens: number; bytes: number },
@@ -92,7 +89,7 @@ function row(
 // **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
+//  — 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.
@@ -129,7 +126,7 @@ function labels_of(report: ReadSetCost): Array<string> {
 
 // **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).
+// child's set is smaller here, not in `scoped` alone.
 function total_read(report: ReadSetCost): { tokens: number; bytes: number } {
 	return entry_read_set.total([report.scoped, ...report.point_of_use.map((one) => one.cost)])
 }
@@ -230,10 +227,10 @@ function wanted_entries(argv: ReadonlyArray<string>, root: string): Array<string
 	return named.length > NOTHING ? named : known_entries(root)
 }
 
-// **An unrecognized keyword is refused, never reported on.** Left to fall through it produced a
+// **An unrecognized keyword is refused, never reported on.** Left to fall through it would produce 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
+// saving of zero — and exit 0, answering "nothing to save" instead of "no such entry" for a mistyped
+// keyword. 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)

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

@@ -2,7 +2,7 @@ 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`
+// of `entry-read-set.ts` when it reached its line limit. `entry_read_set`
 // re-exports `cost_of`, `total` and `Cost` under the names they always had, so the move changed no
 // call site.
 
@@ -52,8 +52,8 @@ function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<n
 // **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
+// with no real overlap — a false negative saving the measurement must never print.
+// 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 {
@@ -81,7 +81,7 @@ function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): str
 // 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).
+// measurement must not be able to move.
 function scoped_file_cost(markdown: string, headings: ReadonlyArray<string>): Cost {
 	const charged = charged_lines(markdown, headings)