@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -1,42 +1,32 @@
-// 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).
+// Which documents a workflow entry point names but reads only later — point-of-use, not entry read.
+// Kept apart from `entry-read-set.ts` so the point-of-use classification is 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
+// **Four documents leave the entry read because their first use is a named command, not the entry**.
+// `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 `background-commands.md`'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):
+// `pnpm josh followup`, `chain-rule.md` before the first `pnpm josh gate` launch it governs (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. `chain-rule.md` governs the `/code-review` → `followup`
+// chain and `background-commands.md` the background execution of the gate, the push and the merge
+// tail — all *after* the first edit, so neither is resident from the entry. `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**:
 // `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. Only a lane child reaches it (joshuafolkken/kit#3172):
-// `fullrun.md` no longer names it, so it is charged to the lane child's role alone.
-// **`progress-watcher.md` joins them** (joshuafolkken/kit#3172): the heartbeat every implementing run
-// starts once its hold is claimed, split out of `backlogrun-progress.md` so a single-issue run stops
-// paying for the batch's hand-off and waiting procedure to read it.
+// **`backlogrun-steps.md` joins them**: `backlogrun.md` is a manifest and its detailed procedure
+// lives in `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.
+// **`pre-gate-cut.md` joins them**: it is the single source of the pre-gate cut, a step a dispatched
+// lane child reaches after the entry, so its read is a point-of-use read. Only a lane child reaches
+// it: `fullrun.md` does not name it, so it is charged to the lane child's role alone.
+// **`progress-watcher.md` joins them**: the heartbeat every implementing run starts once its hold is
+// claimed, kept apart from `backlogrun-progress.md` so a single-issue run does not pay for the
+// batch's hand-off and waiting procedure to read it.
 const POINT_OF_USE_FILES: ReadonlySet<string> = new Set([
 	'latest-gate.md',
 	'followup.md',
@@ -50,16 +40,16 @@ const POINT_OF_USE_FILES: ReadonlySet<string> = new Set([
 	'backlogrun-park.md',
 	'backlogrun-steps.md',
 	// Read only when a delegated unit goes silent or a lane's pull request conflicts with `main` — a
-	// failure path, so a run in which nothing fails never reads it (joshuafolkken/kit#3175).
+	// failure path, so a run in which nothing fails never reads it.
 	'backlogrun-recovery.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
+	// end of a run, never the entry. 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
+// another**. 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
@@ -83,8 +73,8 @@ function is_point_of_use(entry: string, file: string): boolean {
 	return (POINT_OF_USE_BY_ENTRY.get(entry) ?? NO_PER_ENTRY_FILES).has(file)
 }
 
-// **Only the global files the entry reaches, plus the ones this entry names in its own row**
-// (joshuafolkken/kit#3078). `cited` is every document the entry's path names; a global file outside it
+// **Only the global files the entry reaches, plus the ones this entry names in its own row**.
+// `cited` is every document the entry's path names; a global file outside it
 // is one this entry never opens — a `kickoff` never issues `followup` — so charging it made every
 // entry's total the same figure and the per-entry ratchet measured nothing.
 function point_of_use_files(entry: string, cited: ReadonlySet<string>): Array<string> {

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

@@ -1,4 +1,4 @@
-// What a document read at a workflow entry costs, in dollars, for one run (joshuafolkken/kit#2289).
+// What a document read at a workflow entry costs, in dollars, for one run.
 //
 // **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

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

@@ -1,4 +1,4 @@
-// Trimming a base entry's read set by role (joshuafolkken/kit#2256).
+// Trimming a base entry's read set by role.
 //
 // **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
@@ -9,8 +9,8 @@
 // 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).
+// moves here with it — and leaves the whole of `entry-read-set.ts` and `SKILL.md` untouched, which
+// every entry point would otherwise pay for.
 
 import { document_section } from './document-section'
 import { entry_read_set, type Cost, type FileCost, type ReadSetCost } from './entry-read-set'

package/scripts/document/resident-budget.ts

@@ -2,25 +2,23 @@ import { document_reachability } from './document-reachability'
 
 // The byte budget of the always-resident document — `CLAUDE.md`, loaded on every request. It is held
 // here rather than in `document-byte-budget.ts` because a resident document is covered by every entry
-// total and must not carry a per-document block entry as well (joshuafolkken/kit#2257); it is held here
-// rather than inside `workflow-skills.test.ts` so `josh bytes CLAUDE.md` counts against the same number
-// the suite enforces (joshuafolkken/kit#3171). Loosening any of the three constants is Tier C —
+// total and must not carry a per-document block entry as well; it is held here rather than inside
+// `workflow-skills.test.ts` so `josh bytes CLAUDE.md` counts against the same number the suite
+// enforces. Loosening any of the three constants is Tier C —
 // `prompts/collaboration-workflow/residency.md`.
 
-// The documents sat at ~83 KB each before the joshuafolkken/kit#854 split, crept back to ~56 KB, and
-// were cut below 30 KB by joshuafolkken/kit#1924. joshuafolkken/kit#3171 cut `CLAUDE.md` to ~14 KB —
-// triggers and pointers only — and lowered this ceiling with it, so the document cannot creep back. It
-// is a guard against re-inlining, not a budget to tune prose against.
-const RESIDENT_CEILING_BYTES = 18_000
+// The ceiling keeps `CLAUDE.md` to triggers and pointers, so the document cannot creep back. It is a
+// guard against re-inlining, not a budget to tune prose against.
+const RESIDENT_CEILING_BYTES = 12_216
 
-// joshuafolkken/kit#951: the ceiling alone stops the wrong thing. Reached, it does not block the
+// The ceiling alone stops the wrong thing. Reached, it does not block the
 // next rule — it makes that rule pay for itself by deleting a neighboring sentence, and the
 // sentence chosen is whichever one no marker pinned rather than whichever one matters least. A
 // required margin turns "at the limit" into a failure while there is still room to write the fix,
 // which is the only point at which moving a procedure into a skill is still a choice.
 const RESIDENT_HEADROOM_BYTES = 2000
 
-// joshuafolkken/kit#1275: a floor under the room left once the procedures are out, so a wholesale
+// A floor under the room left once the procedures are out, so a wholesale
 // re-inlining fails by name instead of silently returning the document to a few bytes of headroom.
 const RE_INLINE_GUARD_HEADROOM_BYTES = 1000
 

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

@@ -15,14 +15,14 @@ import { epic_sections, type BodyLines, type SectionRange } from './epic-section
 // declaration `epic:next` parses, and the native `blocked-by` relations — and editing the body by
 // hand is what leaves them disagreeing, which stops an unattended run outright. So the rewritten
 // body is parsed back before it is returned, and a round trip that does not reproduce the intended
-// links is reported instead of written (joshuafolkken/kit#890).
+// links is reported instead of written.
 
 interface RewriteInput {
 	body: string
 	// The children being placed, in the order the caller named them: the additions and the children
 	// the epic already tracks, together in one list. **A position places both kinds the same way** —
 	// the task-list row and the declaration are one statement, so an addition whose row was appended
-	// while the chain named a position left the two disagreeing (joshuafolkken/kit#1704). Which of
+	// while the chain named a position left the two disagreeing. Which of
 	// them already has a row is read off the body rather than passed in, since the two are placed
 	// identically and only the removal of an existing row differs.
 	placed: ReadonlyArray<number>
@@ -33,11 +33,10 @@ interface RewriteInput {
 	// The decision record to append to the epic's `## Decisions` section, or `undefined` for an
 	// insertion that records none. It is folded in **before** the declaration work below, so the stray
 	// declaration and round-trip guards see the record too: a record carrying a bare `#A -> #B` line
-	// would otherwise be written and then read back by `epic:next` as part of the order
-	// (joshuafolkken/kit#1350).
+	// would otherwise be written and then read back by `epic:next` as part of the order.
 	decision?: string | undefined
 	// Whether an empty `chains_after` means "write that there is no order" rather than "leave the
-	// declaration alone" (joshuafolkken/kit#1712).
+	// declaration alone".
 	//
 	// The two callers mean opposite things by it. An insertion given no position computes no chains
 	// because none were ever declared, so the body is left exactly as it stood. A removal that took out
@@ -92,13 +91,12 @@ function is_placed_row(line: string, placed: ReadonlySet<number>): boolean {
 }
 
 // The rows of the placed children, put beside the row the position names. **The list order is part
-// of what a position declares**: `epic:next` presents an epic's children in task-list order
-// (joshuafolkken/kit#1583), so rewriting only the declaration would leave the two disagreeing
-// (joshuafolkken/kit#1701).
+// of what a position declares**: `epic:next` presents an epic's children in task-list order,
+// so rewriting only the declaration would leave the two disagreeing.
 //
 // **Both kinds of placement go through here.** A child the epic already tracks has its row lifted
 // out first; an addition has none to lift, so the same insertion serves both and they land in the
-// order the caller named rather than in the order they were classified (joshuafolkken/kit#1704).
+// order the caller named rather than in the order they were classified.
 //
 // The target's row is located after the removal rather than before it, so the index needs no
 // adjusting for the rows that came out above it. Both lookups go through `find_indices`, which skips
@@ -119,8 +117,7 @@ function insert_task_rows(
 }
 
 // The task list with the placed children in it: at the position where one was named, appended where
-// none was. An insertion that named no position appends, which is every insertion made before
-// joshuafolkken/kit#1701 and every unordered one since.
+// none was. An insertion that named no position appends.
 function to_placed_lines(input: RewriteInput): Array<string> {
 	const lines = to_body_lines(input.body)
 	const { position } = input
@@ -174,8 +171,8 @@ function replace_declaration(
 
 // The declaration a line names, **re-rendered from the issue numbers it parsed to rather than echoed
 // back**. The message has to name what it found, or the answer "move this line" is unactionable — and
-// the body it comes from is not this process's: it is fetched from GitHub, and since
-// joshuafolkken/kit#1350 it also carries a record file the caller supplied. Echoing a line of either
+// the body it comes from is not this process's: it is fetched from GitHub, and it also carries a
+// record file the caller supplied. Echoing a line of either
 // into stderr puts content this code never read in the console, which is what SonarCloud's
 // `tssecurity:S8689` reports for this path. Rendering from the parsed numbers keeps the useful half —
 // the chain, exactly as the parser read it — while what reaches the console is built from integers.
@@ -207,7 +204,7 @@ type BodyOutcome = { body: string } | { error: string }
 // The task rows and the decision record, in that order. **The record goes in before the declaration
 // work**: it is the one part of the new body that a caller wrote by hand, so the stray-declaration and
 // round-trip guards below have to see it — a record appended afterwards would be written unchecked and
-// read back by `epic:next` as part of the order (joshuafolkken/kit#1350).
+// read back by `epic:next` as part of the order.
 function to_written_lines(input: RewriteInput): Array<string> {
 	const with_rows = to_placed_lines(input)
 	const { decision } = input
@@ -230,7 +227,7 @@ function is_declaration_unchanged(
 
 // The declaration work, once the task rows and any record are in.
 //
-// **An unchanged declaration is left as text rather than re-rendered** (joshuafolkken/kit#1253). The
+// **An unchanged declaration is left as text rather than re-rendered**. The
 // rewrite moves every chain line to the first one's index, so re-rendering a declaration nothing
 // changed detaches the rationale lines a chain is documented by and files them under whichever chain
 // ends up above them — a rewrite of somebody else's prose in exchange for a body that would have been
@@ -260,7 +257,7 @@ function to_declared_body(
 // The declaration to write. An empty computed order means "nothing was ever declared" to an
 // insertion and "the last link was just deleted" to a removal, and only the second has anything to
 // say — the unordered sentence, since an emptied section carries no machine-readable declaration at
-// all (joshuafolkken/kit#1712).
+// all.
 function to_rendered_declaration(input: RewriteInput): Array<string> {
 	const rendered = epic_chains.render_chains(input.chains_after)
 	if (rendered.length > 0) return rendered
@@ -312,11 +309,11 @@ function to_placement_start(position: InsertPosition, target: number, count: num
 // Whether the rewritten task list puts the placed rows where the position asked. The link round trip
 // above says nothing about it — a body whose rows never moved declares exactly the same order and
 // passes every other check here, while `epic:next` goes on presenting the order it was told to
-// replace (joshuafolkken/kit#1701).
+// replace.
 //
 // **It covers an addition's row as well as a moved one**, since a position now places both: the row
 // an addition gains is the half of the statement the declaration cannot verify for itself, and it
-// was the half left unchecked (joshuafolkken/kit#1704).
+// was the half left unchecked.
 function has_intended_rows(body: string, input: RewriteInput): boolean {
 	const { position, placed } = input
 	if (position === undefined || placed.length === 0) return true

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

@@ -11,7 +11,7 @@ import { epic_shape } from './epic-shape'
 // Kept apart from the GitHub calls so the whole decision — which rows to add, which declaration to
 // write, which relations to record and which to drop — is asserted without a network. That
 // separation is the point: the command's value is that it refuses rather than half-applies, and a
-// refusal path only reachable through `gh` is a refusal path nobody tests (joshuafolkken/kit#890).
+// refusal path only reachable through `gh` is a refusal path nobody tests.
 
 interface PlanInput {
 	epic_number: number
@@ -20,18 +20,18 @@ interface PlanInput {
 	children: ReadonlyArray<number>
 	position?: InsertPosition | undefined
 	// `--order-before` / `--order-after`: move the task-list row to `position` and write nothing else —
-	// no declaration, no `blocked-by` (joshuafolkken/kit#1738). The position is carried in the field
+	// no declaration, no `blocked-by`. The position is carried in the field
 	// above rather than in one of its own, because where the row goes is the same question either way;
 	// what this flag decides is whether a dependency is recorded behind it.
 	is_order_only?: boolean | undefined
 	// The epic's current children with their native relations, as `epic:next` reads them.
 	recorded: ReadonlyArray<EpicChild>
-	// The epic's own repository — what a declared bare number names. Needed since
-	// joshuafolkken/kit#1126 made a recorded relation carry the repository it lives in.
+	// The epic's own repository — what a declared bare number names. Needed because a recorded
+	// relation carries the repository it lives in.
 	repo: string
 	// The decision record `--decision-file` supplied, or `undefined` for an insertion that records
 	// none. It reaches the body rewrite rather than being posted separately, so the epic half of the
-	// record rides on the body edit the insertion already makes (joshuafolkken/kit#1350).
+	// record rides on the body edit the insertion already makes.
 	decision?: string | undefined
 }
 
@@ -40,20 +40,20 @@ interface AddPlan {
 	additions: ReadonlyArray<number>
 	// The children the epic already tracked, moved to the position the caller named. Kept apart from
 	// `additions` because the two write different things: an addition gains a task-list row, while a
-	// relocation only moves the row it already had (joshuafolkken/kit#1701).
+	// relocation only moves the row it already had.
 	relocations: ReadonlyArray<number>
 	added: ReadonlyArray<DependencyLink>
 	removed: ReadonlyArray<DependencyLink>
 	// Every link the declaration dropped, whether or not GitHub had recorded it natively — which is what
-	// separates it from `removed` above (joshuafolkken/kit#1711). `removed` is a work list for `gh` and
+	// separates it from `removed` above. `removed` is a work list for `gh` and
 	// is therefore filtered down to relations that exist to be removed; this is the *report*, and a
 	// declared-but-unrecorded order the caller re-pointed is exactly as much a replacement as a recorded
 	// one. Reporting from `removed` let those vanish without a word.
 	replaced: ReadonlyArray<DependencyLink>
 	// The placed children an order-only move puts on the wrong side of an order the declaration already
-	// states — ahead of an issue declared to block them, or behind one they are declared to block
-	// (joshuafolkken/kit#1738). **The wrong side is judged against the whole resulting row order, not
-	// against the move target alone** (joshuafolkken/kit#1753): a relocation can seat a row on the wrong
+	// states — ahead of an issue declared to block them, or behind one they are declared to block.
+	// **The wrong side is judged against the whole resulting row order, not
+	// against the move target alone**: a relocation can seat a row on the wrong
 	// side of a *third* child the target never named, and a check that only compared the target missed
 	// it. `epic:next` filters by `blocked_by` **before** it applies task-list
 	// order, so such a row cannot take effect until the declaration itself changes, and a run that only
@@ -92,12 +92,12 @@ function declared_numbers(chains: ReadonlyArray<ReadonlyArray<number>>): Array<n
 	return [...new Set(chains.flat())]
 }
 
-// The children the epic already tracks, given a position: what used to be filtered out as "nothing to
-// do" is a reorder the moment `--before` / `--after` says where they go. Without a position there is
-// still nothing to do, so the refusal below stands for that case (joshuafolkken/kit#1701).
+// The children the epic already tracks, given a position: what would be "nothing to do" without one
+// is a reorder the moment `--before` / `--after` says where they go. Without a position there is
+// still nothing to do, so the refusal below stands for that case.
 //
 // **The task list decides, not the declaration.** An issue a chain names while no row tracks it is
-// what joshuafolkken/kit#890's cycle came out of, and a move that re-rendered its missing row would
+// what a declaration cycle comes out of, and a move that re-rendered its missing row would
 // repair a body somebody has to reconcile by hand — so it stays outside a move and keeps the refusal
 // it already had.
 function to_relocations(input: PlanInput, tracked: ReadonlyArray<number>): Array<number> {
@@ -108,8 +108,7 @@ function to_relocations(input: PlanInput, tracked: ReadonlyArray<number>): Array
 
 // The issues to place, in the order the caller gave them. Additions and relocations enter one chain
 // segment together, so which comes first is the caller's word rather than which bucket it fell into
-// — and the task list is written from this same list, which is what keeps the two agreeing
-// (joshuafolkken/kit#1704).
+// — and the task list is written from this same list, which is what keeps the two agreeing.
 function to_placed(
 	children: ReadonlyArray<number>,
 	additions: ReadonlyArray<number>,
@@ -183,7 +182,7 @@ interface PlanContext {
 	additions: ReadonlyArray<number>
 	relocations: ReadonlyArray<number>
 	// The two above as one list, in the order the caller named them — what both the chain segment and
-	// the task list are written from (joshuafolkken/kit#1704).
+	// the task list are written from.
 	placed: ReadonlyArray<number>
 	chains_before: ReadonlyArray<ReadonlyArray<number>>
 	chains_after: ReadonlyArray<ReadonlyArray<number>>
@@ -203,13 +202,13 @@ function to_rewrite_input(context: PlanContext, decision: string | undefined): R
 // checks rather than a function that both checks and composes.
 //
 // **The replacements are folded into the decision record before the body is rewritten**, because the
-// epic's `## Decisions` half rides on that same edit (joshuafolkken/kit#1350) — composing it afterwards
+// epic's `## Decisions` half rides on that same edit — composing it afterwards
 // would put the line on the child comments and leave the epic without it. The caller-supplied record
 // has already been validated by `find_decision_error`; what is appended here is generated, not read
 // from a file.
 // An ordinary insertion records every link the declaration names that GitHub does not, which repairs a
-// declared-but-unrecorded order in passing. **An order-only move records nothing at all**
-// (joshuafolkken/kit#1738): `--order-*` exists so a row can move with no dependency appearing behind
+// declared-but-unrecorded order in passing. **An order-only move records nothing at all**:
+// `--order-*` exists so a row can move with no dependency appearing behind
 // it, and a repair made under it would put back exactly the `blocked-by` the caller asked not to have.
 // The declaration is unchanged either way, so the repair is still there for the next insertion to make.
 function to_added_links(
@@ -239,8 +238,7 @@ function does_declare_order(
 // Whether the resulting row order puts `child` on the wrong side of any issue the declaration orders
 // it against — ahead of one declared to block it, or behind one it is declared to block. The move
 // target is not privileged: a relocation can seat a row on the wrong side of a *third* child the
-// target never named, so the whole resulting order is cross-checked rather than the target alone
-// (joshuafolkken/kit#1753).
+// target never named, so the whole resulting order is cross-checked rather than the target alone.
 function does_row_contradict_order(
 	chains: ReadonlyArray<ReadonlyArray<number>>,
 	rows: ReadonlyArray<number>,
@@ -299,15 +297,15 @@ function to_plan(context: PlanContext): PlanOutcome {
 
 // A decision record that cannot be written is refused here rather than dropped: `--decision-file` was
 // given because the record has to exist, so writing the insertion without it would report success for
-// half the job (joshuafolkken/kit#1350). `undefined` is "none was asked for", which is not a refusal.
+// half the job. `undefined` is "none was asked for", which is not a refusal.
 function find_decision_error(decision: string | undefined): string | undefined {
 	return decision === undefined ? undefined : epic_decision.find_decision_error(decision)
 }
 
 // Asked of the declaration as it stands, because a relocation's removal can collapse the very
-// ambiguity this refuses (joshuafolkken/kit#1701).
+// ambiguity this refuses.
 //
-// **An order-only move is not asked at all** (joshuafolkken/kit#1738). The ambiguity is about where a
+// **An order-only move is not asked at all**. The ambiguity is about where a
 // *dependency* would attach — `--before <hub>` cannot say which of the chains running through the hub
 // the new link joins — and `--order-*` attaches no link, so the question has no subject. Asking it
 // anyway would refuse a row move on the strength of a declaration the move never touches.
@@ -361,9 +359,9 @@ function find_input_error(
 
 // The declaration the body will carry. A relocation is a removal followed by the ordinary insertion,
 // so `--before` re-points the chain it lands in and the vacated chain closes around it — both by
-// construction rather than by a second code path (joshuafolkken/kit#1701).
+// construction rather than by a second code path.
 //
-// **An order-only move takes neither step** (joshuafolkken/kit#1738): the declaration it started with
+// **An order-only move takes neither step**: the declaration it started with
 // is the declaration it ends with, which is `keep_declaration` — the same passthrough `--add` with no
 // position already uses. Because the chains come back identical, `diff_links` finds nothing replaced
 // and the body rewrite leaves the `## Dependencies` section byte-identical, so "writes no dependency"
@@ -393,7 +391,7 @@ function build_plan(input: PlanInput): PlanOutcome {
 	const additions = to_additions(input, tracked, declared_numbers(chains_before))
 	const relocations = to_relocations(input, tracked)
 	// `tracked` reaches the chain builder so it can tell a child with no order yet from a number that is
-	// not a child at all; `find_movement_error` has already refused the second (joshuafolkken/kit#949).
+	// not a child at all; `find_movement_error` has already refused the second.
 	// What the builder does with a relocation, and what an order-only move does instead, is on
 	// `to_chains_after` above.
 	const placed = to_placed(input.children, additions, relocations)

package/scripts/epic/epic-add.ts

@@ -1,5 +1,6 @@
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_add_plan, type AddPlan } from './epic-add-plan'
 import type { InsertPosition } from './epic-chains'
 import { epic_decision } from './epic-decision'
@@ -15,7 +16,7 @@ import { epic_relations } from './epic-relations'
 // `josh epic --add <E> <N...> [--before <M> | --after <M> | --order-before <M> | --order-after <M>]
 // [--decision-file <path|->]` — insert children into an existing epic.
 //
-// **`--order-*` moves the row and writes nothing else** (joshuafolkken/kit#1738). `epic:next` offers
+// **`--order-*` moves the row and writes nothing else**. `epic:next` offers
 // children in task-list order, so putting one first meant `--before`, which records a `blocked-by`:
 // "no dependency, but run this one first" had no spelling, and an order written that way stops every
 // child behind the one that stalls.
@@ -23,10 +24,9 @@ import { epic_relations } from './epic-relations'
 // Adding a child by editing the body is what the procedure told an agent to do, and it is what stops
 // an unattended run: the body then declares an order the native `blocked-by` relations do not record,
 // `epic:next` reports `declaration_mismatch`, and the verdict is `error`. This command writes the
-// task-list row, the declaration and the relations from one input, so the three cannot disagree
-// (joshuafolkken/kit#890).
+// task-list row, the declaration and the relations from one input, so the three cannot disagree.
 //
-// **`--decision-file` folds the fourth and fifth writes in** (joshuafolkken/kit#1350). An auto-decided
+// **`--decision-file` folds the fourth and fifth writes in**. An auto-decided
 // placement has to be recorded in the epic's `## Decisions` and on each child, and no command wrote the
 // epic half — so a run read the body, edited it and `PATCH`ed it back, which is the hand edit
 // `CLAUDE.md` forbids. The epic half now rides on the body edit this command already makes, so it costs
@@ -37,7 +37,7 @@ const SUCCESS_EXIT_CODE = 0
 
 // A completed epic takes no new children: adding one silently produces a closed epic with unfinished
 // children, whose backlog opt-in no longer fires, so the child never surfaces and the addition is
-// lost (joshuafolkken/kit#2337). The refusal is only fired on a *confirmed* closed state — an
+// lost. The refusal is only fired on a *confirmed* closed state — an
 // unreadable state field leaves the addition to proceed, since blocking on a lookup that never
 // answered would be the worse failure.
 function is_closed_epic(state: string | undefined): boolean {
@@ -45,7 +45,7 @@ function is_closed_epic(state: string | undefined): boolean {
 }
 
 function closed_epic_error(epic_number: number): string {
-	return `Epic #${String(epic_number)} is closed — a completed epic takes no new children. Reopen it if it is not actually done, or run \`pnpm josh epic:bundle <child>\` to place the child in an open epic instead.`
+	return `Epic ${session_cite.issue(epic_number)} is closed — a completed epic takes no new children. Reopen it if it is not actually done, or run \`pnpm josh epic:bundle <child>\` to place the child in an open epic instead.`
 }
 
 interface AddChildrenInput {
@@ -53,12 +53,11 @@ interface AddChildrenInput {
 	children: ReadonlyArray<number>
 	position?: InsertPosition | undefined
 	// `--order-before` / `--order-after`: place the row at `position` and write nothing else — no
-	// declaration, no `blocked-by` (joshuafolkken/kit#1738).
+	// declaration, no `blocked-by`.
 	is_order_only?: boolean | undefined
-	// The decision record to write, from `--decision-file`. It goes to two places, and both used to be
-	// separate calls a run made afterwards: the epic's `## Decisions` section — folded into the body
-	// edit below, so it costs no round trip — and a comment on each child added
-	// (joshuafolkken/kit#1350).
+	// The decision record to write, from `--decision-file`. It goes to two places, neither of them a
+	// separate call a run makes afterwards: the epic's `## Decisions` section — folded into the body
+	// edit below, so it costs no round trip — and a comment on each child added.
 	decision?: string | undefined
 }
 
@@ -96,20 +95,22 @@ async function apply_plan(plan: AddPlan): Promise<void> {
 // The two things one insertion can do, reported separately because they are different edits: an
 // addition gains a task-list row, a relocation moves the row it already had. Either list can be empty
 // — `--before` / `--after` on children the epic already tracks adds nothing at all
-// (joshuafolkken/kit#1701) — so neither line is printed unconditionally.
+// — so neither line is printed unconditionally.
 // A row moved onto the wrong side of an order the declaration already states. `epic:next` filters by
 // `blocked_by` before it applies task-list order, so the move cannot change when that child is offered
 // until the declaration itself changes — and the placement line above, read alone, says the opposite.
-// It is a warning rather than a refusal for the reason `contradicted` gives (joshuafolkken/kit#1738).
+// It is a warning rather than a refusal for the reason `contradicted` gives.
 function report_contradiction(plan: AddPlan): void {
 	if (plan.contradicted.length === 0) return
 
 	console.info(
-		`⚠️ ${format_issue_references(plan.contradicted)} is still held by a declared order, so \`epic:next\` will not offer it any earlier until that order is changed — \`--remove\` deletes one.`,
+		session_cite.text(
+			`⚠️ ${format_issue_references(plan.contradicted)} is still held by a declared order, so \`epic:next\` will not offer it any earlier until that order is changed — \`--remove\` deletes one.`,
+		),
 	)
 }
 
-// **An order-only move reports the place, because nothing else will** (joshuafolkken/kit#1738). An
+// **An order-only move reports the place, because nothing else will**. An
 // ordinary insertion is followed by the replaced-relation line and the relation report, which between
 // them say where the child landed; `--order-*` writes neither, so without this line the console says a
 // row moved and never says where to. The position is read from the input rather than the plan: the
@@ -122,7 +123,9 @@ function report_order(input: AddChildrenInput, plan: AddPlan): void {
 	const target = to_issue_reference(position.target)
 
 	console.info(
-		`📋 Placed ${placed} ${position.kind} ${target} in epic #${String(input.epic_number)} — order only, no dependency written.`,
+		session_cite.text(
+			`📋 Placed ${placed} ${position.kind} ${target} in epic ${session_cite.issue(input.epic_number)} — order only, no dependency written.`,
+		),
 	)
 	report_contradiction(plan)
 }
@@ -134,19 +137,23 @@ function report_placements(input: AddChildrenInput, plan: AddPlan): void {
 		return
 	}
 
-	const epic = `epic #${String(input.epic_number)}`
+	const epic = `epic ${session_cite.issue(input.epic_number)}`
 
 	if (plan.additions.length > 0) {
-		console.info(`📋 Added ${format_issue_references(plan.additions)} to ${epic}.`)
+		console.info(
+			session_cite.text(`📋 Added ${format_issue_references(plan.additions)} to ${epic}.`),
+		)
 	}
 
 	if (plan.relocations.length > 0) {
-		console.info(`📋 Moved ${format_issue_references(plan.relocations)} within ${epic}.`)
+		console.info(
+			session_cite.text(`📋 Moved ${format_issue_references(plan.relocations)} within ${epic}.`),
+		)
 	}
 }
 
-// **What the insertion discarded, printed from `plan.replaced` rather than `plan.removed`**
-// (joshuafolkken/kit#1711). The two differ by the filter `removed` carries for `gh`'s sake: a link the
+// **What the insertion discarded, printed from `plan.replaced` rather than `plan.removed`**.
+// The two differ by the filter `removed` carries for `gh`'s sake: a link the
 // body declared but nobody ever recorded natively is dropped from the declaration all the same, and
 // reporting from the work list let exactly those go by without a word. A positioned `--add` is the
 // only invocation that can replace anything, so an addition that re-points nothing prints nothing.
@@ -176,7 +183,7 @@ async function comment_decision(children: ReadonlyArray<number>, decision: strin
 
 // The record posted to the children is `plan.decision`, not the caller's file: the plan is what folded
 // the replaced relations into it, and reading the raw input here would leave the epic's `## Decisions`
-// carrying a line the child comments do not (joshuafolkken/kit#1711).
+// carrying a line the child comments do not.
 // A child new to the epic, not a reordering — the only insertion that can put runnable work in the pool.
 function has_new_child(input: AddChildrenInput, plan: AddPlan): boolean {
 	return input.is_order_only !== true && plan.additions.length > 0
@@ -188,7 +195,7 @@ async function write_plan(input: AddChildrenInput, plan: AddPlan): Promise<void>
 	await apply_plan(plan)
 
 	// A relocation is a placement decision as much as an addition is, so the record reaches the child
-	// that was moved too (joshuafolkken/kit#1701).
+	// that was moved too.
 	if (plan.decision !== undefined) {
 		await comment_decision([...plan.additions, ...plan.relocations], plan.decision)
 	}
@@ -196,8 +203,8 @@ async function write_plan(input: AddChildrenInput, plan: AddPlan): Promise<void>
 	if (has_new_child(input, plan)) await backlog_ready.print_offer_hint()
 }
 
-// The epic ready to receive children, or the reason it cannot be added to: unreadable, or closed
-// (joshuafolkken/kit#2337). Both reasons come back as a bare string the one caller prefixes `✖` onto,
+// The epic ready to receive children, or the reason it cannot be added to: unreadable, or closed.
+// Both reasons come back as a bare string the one caller prefixes `✖` onto,
 // so the two refusals read identically on stderr.
 async function read_open_epic(epic_number: number): Promise<EpicReading | { error: string }> {
 	const epic = await epic_read.read_epic(epic_number)