@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/epic/epic-next.ts

@@ -20,9 +20,9 @@ import { epic_parse } from './epic-parse'
 import { epic_report, type EpicNextResult } from './epic-report'
 
 // `josh epic:next <E…>` — which of the named epics' children can be started right now, bundled per
-// repository, and what the rest are waiting on (joshuafolkken/kit#860).
+// repository, and what the rest are waiting on.
 //
-// **Several epics answer as one** (joshuafolkken/kit#1493). Every leading argument is an epic
+// **Several epics answer as one**. Every leading argument is an epic
 // reference, and their children merge into one candidate pool per repository — so a repository with
 // six free lanes fills them from every named epic rather than from whichever one was typed first.
 // The merge itself, and why the priority order is the order they were named, is
@@ -33,17 +33,14 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 // Asking for every free lane (`--lanes`) is opt-in, so the answer stays one token for a caller that
-// has not been changed. `--repo` alone still prints exactly one number — what joshuafolkken/kit#1491
-// changed for it is *when* that number appears, not how many arrive (joshuafolkken/kit#1491).
+// has not been changed. `--repo` alone prints exactly one number.
 const OPTIONS = { repo: { type: 'string' }, lanes: { type: 'boolean' } } as const
 const USAGE =
 	'Usage: josh epic:next <epic-number|owner/repo#number>... [--repo <owner/repo>] [--lanes]'
-// A repository that could not be read is refused rather than stood in for. Since
-// joshuafolkken/kit#1126 a blocker carries the repository it lives in, so a placeholder on the
-// children keys them as `unknown/unknown#N` while their blockers keep their real names: every
-// relation misses, `from_blockers([])` calls the child runnable, and an unattended run starts a
-// dependent before its prerequisite. The old placeholder was harmless only while every blocker
-// inherited the child's own repository — it matched itself.
+// A repository that could not be read is refused rather than stood in for. A blocker carries the
+// repository it lives in, so a placeholder on the children would key them as `unknown/unknown#N`
+// while their blockers keep their real names: every relation misses, `from_blockers([])` calls the
+// child runnable, and an unattended run starts a dependent before its prerequisite.
 const UNKNOWN_REPO =
 	'Could not read this repository from `git remote`, so the children cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote.'
 const EXTERNAL_NOTICE = 'Note: this epic tracks children in other repositories.'
@@ -55,7 +52,7 @@ const UNCHECKED_EXCLUSION =
 
 interface NextOptions {
 	// Every epic named, in the order they were named — which is the order their children then take
-	// free lanes in (joshuafolkken/kit#1493). Each reference carries the repository the *epic* lives
+	// free lanes in. Each reference carries the repository the *epic* lives
 	// in when it was qualified (`owner/repo#858`).
 	references?: ReadonlyArray<EpicReference>
 	// The repository to narrow the candidates to (`--repo`).
@@ -93,9 +90,9 @@ function with_repo(
 }
 
 // The positional arguments are epic references and the flags are options, so `epic:next 858 909 --repo
-// X` reads two epics and `epic:next 858 --repo X` still reads one (joshuafolkken/kit#1493). The read is
+// X` reads two epics and `epic:next 858 --repo X` still reads one. The read is
 // strict: an unknown flag reaches the usage line rather than being ignored, and a value that is itself
-// a flag is no value at all — `--repo --lanes` used to narrow to a repository literally named
+// a flag is no value at all — `--repo --lanes` must not narrow to a repository literally named
 // `--lanes` and report `No runnable child in --lanes` with exit 0.
 //
 // `--lanes` without `--repo` is refused rather than ignored: the lane count is a property of one
@@ -118,10 +115,10 @@ function parse_options(argv: ReadonlyArray<string>): NextOptions {
 // leaves whatever it blocks looking unblocked.
 //
 // Each one is named with the repository it lives in, through the same writer the audit uses: an epic
-// tracking `- [ ] sveltejs/kit#7` reported `Could not read #7`, and a reader sent to this
-// repository's issue 7 finds a different issue or none (joshuafolkken/kit#1016).
-// **The epic's own body failing to read is its own anomaly, ahead of the children's**
-// (joshuafolkken/kit#1690). Without it the failure is silent: a body that never arrived parses to
+// tracking `- [ ] sveltejs/kit#7` reporting `Could not read #7` would send a reader to this
+// repository's issue 7, a different issue or none.
+// **The epic's own body failing to read is its own anomaly, ahead of the children's**.
+// Without it the failure is silent: a body that never arrived parses to
 // zero children, the epic is dropped from the views as an unpopulated one, no anomaly is raised, and
 // the verdict falls through to `complete` — which `backlog:next` prints as `none`, so the run reports
 // the backlog exhausted over one request that never left the machine. It is checked first because a
@@ -153,8 +150,8 @@ function unreadable_anomaly(snapshot: EpicSnapshot): GraphAnomaly | undefined {
 // every correct relation as undeclared.
 //
 // Deliberately a disjunction where `epic:check` takes exactly one of the two: a body declaring both
-// a chain and the `None — ...` literal is a contradiction, and reporting it is the check's job
-// (joshuafolkken/kit#1155). Refusing to hand out work here as well would stop an unattended run on a
+// a chain and the `None — ...` literal is a contradiction, and reporting it is the check's job.
+// Refusing to hand out work here as well would stop an unattended run on a
 // body whose declared chain and recorded relations agree — a worse outcome than following the chain
 // the run's own `epic:check` already flagged.
 function is_order_declared(body: string | undefined, links: ReadonlyArray<unknown>): boolean {
@@ -178,7 +175,7 @@ function decide(
 				)
 			: [unreadable]
 	// The cross-repository resolver, not the default one: a blocker in another repository is not
-	// finished when it closes, only when its release is published (joshuafolkken/kit#864).
+	// finished when it closes, only when its release is published.
 	const classification = epic_classify.classify_children(
 		snapshot.children,
 		epic_cross_repo.resolve_cross_repo,
@@ -203,8 +200,8 @@ function repo_verdict(verdict: LaneOffer['verdict']): LaneOffer['verdict'] {
 }
 
 // The confirmed candidates' numbers, one per line, or the verdict that stands in their place when
-// there was no free lane or the relations listing withheld every one of them
-// (joshuafolkken/kit#1121). Standard output carries numbers or a verdict and nothing else, so
+// there was no free lane or the relations listing withheld every one of them.
+// Standard output carries numbers or a verdict and nothing else, so
 // `child=$(josh epic:next … --repo …)` is unchanged for the caller that asked for one child — which
 // is every caller that did not pass `--lanes`.
 function report_offer(offer: LaneOffer): number {
@@ -222,23 +219,22 @@ function report_offer(offer: LaneOffer): number {
 }
 
 // The candidates, once the repository has been asked **how many lanes it already has running** —
-// whichever epic those belong to (joshuafolkken/kit#925, counted rather than excluded since
-// joshuafolkken/kit#1491). The invariant is per *repository* rather than per epic, and it is a
+// whichever epic those belong to, counted rather than excluded. The invariant is per *repository* rather than per epic, and it is a
 // ceiling on how many children run there at once rather than a lock on the whole checkout.
 //
 // Asked only when there *is* a candidate: consulted on `stop` or `complete` too, an unrelated
 // `in-progress` issue would turn a finished epic into a permanent `wait`, and neither of those
 // verdicts is about to start anything. It also never reaches a third party's tracker, since a child
-// in a repository with another owner is refused before it is read (joshuafolkken/kit#869).
+// in a repository with another owner is refused before it is read.
 //
 // **A read that failed answers `wait` too** — never a child, and not an error either
 // (`epic-busy.ts` records why both wrong answers are wrong). **So does a listing that was cut
-// short**: since joshuafolkken/kit#1067 the page ceiling bounds this listing as well, and a short
+// short**: the page ceiling bounds this listing as well, and a short
 // listing with no visible holder is not "nothing is running".
 //
 // One pool per named epic, in the order they were named. Nothing below this line knows what an epic
 // is (`epic-lane-offer.ts` records why), so the whole cost of running several of them is here: build
-// the pools, and let the scheduler spend the free lanes across them (joshuafolkken/kit#1493).
+// the pools, and let the scheduler spend the free lanes across them.
 async function offer_children(
 	views: ReadonlyArray<EpicView>,
 	request: LaneRequest,
@@ -287,7 +283,7 @@ async function report_single(
 // The aggregate listing does not consult the repository-level exclusion — `--repo` is what asks a
 // repository whether it is busy, and doing it here would be one listing per repository for a report
 // nobody branches on. Said out loud rather than left implicit: this output names runnable children,
-// and the `--repo` form may answer `wait` for the very same child (joshuafolkken/kit#925).
+// and the `--repo` form may answer `wait` for the very same child.
 function note_unchecked_exclusion(views: ReadonlyArray<EpicView>): void {
 	if (epic_next_views.combined_verdict(views) === 'run') console.error(UNCHECKED_EXCLUSION)
 }
@@ -295,7 +291,7 @@ function note_unchecked_exclusion(views: ReadonlyArray<EpicView>): void {
 // One block per epic, and the notice printed once for all of them rather than once each: it says
 // what this listing does not check, which is the same sentence however many graphs it covers. The
 // listing names each epic and its children as `#N`, linkified against the current repository so the
-// output a run reads carries clickable references rather than bare ones (joshuafolkken/kit#2329).
+// output a run reads carries clickable references rather than bare ones.
 function report_aggregate(views: ReadonlyArray<EpicView>, current_repo: string): number {
 	note_unchecked_exclusion(views)
 
@@ -339,7 +335,7 @@ async function report(
 	return report_aggregate(views, current_repo)
 }
 
-// The checkout each repository's children would be run in comes from joshuafolkken/kit#869's map. A
+// The checkout each repository's children would be run in comes from the workspace map. A
 // repository absent from it is reported without a path rather than cloned.
 //
 // **Every epic is classified against the same reset**, not one reset each: `reset_reported` and
@@ -352,7 +348,7 @@ async function report_epics(
 ): Promise<number> {
 	if (options.repo === undefined) return await report(views, undefined, current_repo)
 
-	const choice = lane_capacity.lane_limit()
+	const choice = await lane_capacity.lane_limit()
 	if (choice.kind === 'problem') return refuse(choice.problem)
 
 	return await report(
@@ -364,7 +360,7 @@ async function report_epics(
 
 // One view per named epic, classified against one shared registry read. `running` is every named
 // epic's children unless a caller that runs more — `backlog:next` — passes its own set, so a blocker
-// in another named epic waits rather than stops (joshuafolkken/kit#1943).
+// in another named epic waits rather than stops.
 function views_of(
 	reads: ReadonlyArray<EpicRead>,
 	running = epic_outside_blocker.running_keys(reads.flatMap((read) => read.snapshot.children)),
@@ -423,7 +419,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 // `process.exitCode` rather than `process.exit()`, for the reason `scripts/cost-runtime/cost-cli.ts` records:
 // the answer goes to standard output and a write to a pipe is asynchronous on macOS, so exiting can
 // tear the process down before it drains. This command's contract is `answer=$(pnpm josh epic:next
-// <E>)`, which is exactly that pipe (joshuafolkken/kit#996).
+// <E>)`, which is exactly that pipe.
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }

package/scripts/epic/epic-outside-blocker.ts

@@ -1,10 +1,11 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 
-// A blocker no graph in this invocation tracks, weighed rather than ignored (joshuafolkken/kit#1943).
+// A blocker no graph in this invocation tracks, weighed rather than ignored.
 //
-// Until this, a relation pointing outside the epic was announced and dropped, so a child waiting on
-// another epic's open issue was offered as runnable — `backlogrun` would start joshuafolkken/kit#1936's
-// children before joshuafolkken/kit#1921 had restored CI, whatever `blocked-by` said. What decides the
+// A relation pointing outside the epic is weighed rather than announced and dropped, so a child
+// waiting on another epic's open issue is not offered as runnable, whatever `blocked-by` says. What
+// decides the
 // answer is whether *this run* can finish the blocker: an open blocker the run also runs is `time`
 // (waiting resolves it), one it does not is `human` (only a person can), and a blocker whose state was
 // never read is `time` rather than runnable, because an unknown is never read as finished.
@@ -15,12 +16,12 @@ import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 //
 // `inherit` is the ordinary answer: the blocker is not finished, so this child's fate is the
 // blocker's fate. `time` and `human` are for a dependency that is unresolved for a reason the
-// blocker's own state does not show — joshuafolkken/kit#864's case, where a blocker is closed but
-// its package has not been published yet, is `time`.
+// blocker's own state does not show — a blocker that is closed but whose package has not been
+// published yet is `time`.
 type DependencyVerdict = 'resolved' | 'time' | 'human' | 'inherit'
 
-// The extension point. Replaced wholesale by joshuafolkken/kit#864 to add the publish condition;
-// the default knows only that a closed blocker is a finished one.
+// The extension point, replaced wholesale to add the publish condition; the default knows only that
+// a closed blocker is a finished one.
 type ResolveDependency = (blocker: EpicChild, blocked: EpicChild) => DependencyVerdict
 
 type OutsideCategory = 'time' | 'human'
@@ -39,11 +40,11 @@ interface OutsideAnswer {
 const CLOSED = 'CLOSED'
 
 function name_of(child: EpicChild): string {
-	return `#${String(child.number)}`
+	return session_cite.issue(child.number, undefined, child.repo)
 }
 
 // A closed reference as the child record a resolver takes, so a closed blocker in another repository
-// still waits for its release exactly as a tracked one does (joshuafolkken/kit#864).
+// still waits for its release exactly as a tracked one does.
 function as_closed_child(reference: IssueReference): EpicChild {
 	return {
 		number: reference.number,

package/scripts/epic/epic-parse.ts

@@ -1,20 +1,21 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
 // An epic Issue tracks its children as a markdown task list (`- [ ] #101`). Only that syntax
 // counts as tracked: GitHub auto-checks such an entry when the referenced Issue closes, whereas a
 // bare `#101` reference produces a cross-link with no progress tracking.
 //
 // The source is shared by the whole-body scan and the single-line test rather than written twice: a
 // rewriter has to recognize exactly the rows the reader counts, and two copies of this pattern would
-// be two chances to disagree about what a tracked row is (joshuafolkken/kit#890).
+// be two chances to disagree about what a tracked row is.
 const TASK_LIST_ISSUE_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+#(\d+)\b`
 const TASK_LIST_ISSUE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'gmu')
 const TASK_LIST_LINE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'u')
 
 // A task list may also reference an Issue in another repository (`owner/repo#101`, or a full URL).
-// Detecting one is what the auto-close used to bail on; joshuafolkken/kit#864 reads them instead,
-// against their own repository, and the pattern below extracts which repository and which issue.
+// Such a reference is read against its own repository, and the pattern below extracts which repository and which issue.
 // `owner/repo#101` on its own. The row patterns below are built from this source, so what counts as
 // a cross-repository reference has one definition — a second copy would let a form the task list
-// accepts be refused where a person types it, or the reverse (joshuafolkken/kit#985).
+// accepts be refused where a person types it, or the reverse.
 const EXTERNAL_REFERENCE_SOURCE = String.raw`([\w.-]+)\/([\w.-]+)#(\d+)`
 const EXTERNAL_REFERENCE_PATTERN = new RegExp(`^${EXTERNAL_REFERENCE_SOURCE}$`, 'u')
 const TASK_LIST_ROW_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+`
@@ -39,12 +40,12 @@ const FENCE_LINE_PATTERN = /^[ \t]*(?:`{3,}|~{3,})/u
 // A chain between two Issue references (`#101 -> #102`, or the arrow written as `→`), read for its
 // links. `epic:next` compares what the body declares against the `blocked-by` relations actually
 // recorded, and a body that says one order while the relations say another must stop the run rather
-// than silently follow either (joshuafolkken/kit#860).
+// than silently follow either.
 //
-// Only a line that is *nothing but* a chain counts, optionally behind a list marker. Measured
-// against joshuafolkken/kit#858, whose Dependencies section is followed by a prose line recommending
-// an execution order — e.g. `recommended order: #869 -> #863 -> …`. Those arrows are a suggestion, not a
-// declaration, and reading them as one reported four disagreements that did not exist.
+// Only a line that is *nothing but* a chain counts, optionally behind a list marker. A Dependencies
+// section may be followed by a prose line recommending an execution order — e.g.
+// `recommended order: #869 -> #863 -> …`. Those arrows are a suggestion, not a declaration, and
+// reading them as one reports disagreements that do not exist.
 const DECLARED_CHAIN_LINE = /^(?:[-*+][ \t]+)?#\d+(?:[ \t]*(?:->|→)[ \t]*#\d+)+$/u
 const CHAIN_REFERENCE_PATTERN = /#(\d+)/gu
 
@@ -59,7 +60,7 @@ const CLOSED_STATE = 'CLOSED'
 // Which lines a body predicate is allowed to read: `false` for a fence line and for everything
 // between a pair of them. Returned as a mask rather than a filtered string because a rewriter has to
 // put lines back where it found them, and it must skip exactly the lines the readers skip — two
-// separate fence walks would be two chances to disagree (joshuafolkken/kit#890).
+// separate fence walks would be two chances to disagree.
 //
 // Toggling on each fence line keeps this linear — a single regex spanning the block would backtrack.
 // An unterminated fence swallows the rest of the body, which fails safe: fewer children means the
@@ -141,7 +142,7 @@ function to_external_child(match: RegExpMatchArray): ExternalChild | undefined {
 
 // A bare `owner/repo#101`, as a person types it — the same shape the task-list rows carry, read
 // from a command argument rather than from a body. It reuses `to_external_child` so the two cannot
-// disagree about which owner and repository names are acceptable (joshuafolkken/kit#985).
+// disagree about which owner and repository names are acceptable.
 function parse_external_reference(text: string): ExternalChild | undefined {
 	const match = EXTERNAL_REFERENCE_PATTERN.exec(text.trim())
 	if (match === null) return undefined
@@ -157,7 +158,7 @@ function match_external(body: string, pattern: RegExp): Array<ExternalChild> {
 
 // Every cross-repository child the task list tracks, in both spellings. Reported as `owner/repo`
 // plus a number rather than a URL, which is the form the repository map takes and the form the
-// read's REST path is built from (joshuafolkken/kit#864).
+// read's REST path is built from.
 function parse_external_task_list_children(body: string | undefined): Array<ExternalChild> {
 	if (body === undefined) return []
 	const stripped = strip_fenced_blocks(body)
@@ -168,7 +169,7 @@ function parse_external_task_list_children(body: string | undefined): Array<Exte
 	const seen = new Set<string>()
 
 	return found.filter((child) => {
-		const key = `${child.repo}#${String(child.number)}`
+		const key = issue_cite.plain(child.number, child.repo)
 		const is_new = !seen.has(key)
 
 		seen.add(key)
@@ -194,7 +195,7 @@ function has_unordered_declaration(body: string | undefined): boolean {
 // Whether one line, on its own, is part of a machine-readable `Dependencies` declaration — a chain or
 // the unordered sentence. It lives here beside the two patterns it tests rather than in either of the
 // modules that rewrite a body, because both of them need it and a second copy is where one comes to
-// disagree with the parser about what counts as a declaration (joshuafolkken/kit#1350).
+// disagree with the parser about what counts as a declaration.
 function is_declaration_line(line: string): boolean {
 	const trimmed = line.trim()
 
@@ -227,7 +228,7 @@ function chain_links(references: ReadonlyArray<number>): Array<DependencyLink> {
 // Every declared chain, one entry per chain line, each holding its references in the order written.
 // Read at this granularity rather than as a flat link list because an insertion has to know *which*
 // chain a target sits in: two disjoint chains and one branching chain produce the same links, and
-// only the line structure tells them apart (joshuafolkken/kit#890).
+// only the line structure tells them apart.
 //
 // Fenced blocks are stripped first for the reason they are everywhere else: a quoted template's
 // sample chain is an illustration.
@@ -251,13 +252,11 @@ function parse_dependency_links(body: string | undefined): Array<DependencyLink>
 // warning, which need to tell "the order was never recorded" from "there is no order".
 //
 // Answered from the chains above rather than from a pattern of its own, because a second pattern is
-// a second answer: until joshuafolkken/kit#1155 this scanned the whole body for a bare `#N -> #M`,
-// so a rationale paragraph recommending an execution order made an epic declared
-// `None — the children are independent` report as ordered, and `josh followup` then said the batch
-// order was never recorded on every child's merge. The narrowing joshuafolkken/kit#858 applied to
-// the link reader was the same judgement, and `epic --add` writes on that judgement too
-// (`epic-add-body.ts` protects an arrow outside the `Dependencies` section as prose) — so the
-// three readers of one body now recognize the same lines, instead of two patterns that could
+// a second answer: scanning the whole body for a bare `#N -> #M` would let a rationale paragraph
+// recommending an execution order make an epic declared `None — the children are independent`
+// report as ordered. The link reader applies the same narrowing, and `epic --add` writes on that
+// judgement too (`epic-add-body.ts` protects an arrow outside the `Dependencies` section as prose) —
+// so the three readers of one body recognize the same lines, instead of two patterns that could
 // disagree about which line is a declaration. They still answer different questions of those lines:
 // a self-loop (`#101 -> #101`) is a declaration here and yields no link, since `chain_links` drops
 // an edge from an issue to itself.
@@ -283,8 +282,7 @@ function read_declaration(body: string | undefined): DeclarationState {
 
 // Whether that declaration says something a machine can act on: exactly one of the two forms, never
 // both. A body carrying a chain *and* the `None — ...` literal declares an order and declares that
-// there is none, and `epic:check` used to pass it while reporting only the half that contradicts the
-// other (joshuafolkken/kit#1155). Single-sourced here because `epic:check`, `epic --add` and
+// there is none, so `epic:check` must not pass it. Single-sourced here because `epic:check`, `epic --add` and
 // `epic --promote` all mean this same question, and three copies of the disjunction were three
 // chances to accept a body the check rejects.
 function is_declaration_readable(state: DeclarationState): boolean {

package/scripts/epic/epic-promote.ts

@@ -1,3 +1,4 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_body } from './epic-body'
 import { epic_parse } from './epic-parse'
 
@@ -33,7 +34,7 @@ function has_conflicting_tracking(body: string | undefined): boolean {
 function conflict_reason(body: string | undefined): string {
 	if (body?.includes(PROMOTED_HEADING) === true) return 'it already carries the epic sections'
 	const tracked = epic_parse.parse_task_list_issue_numbers(body)
-	const list = tracked.map((child) => `#${String(child)}`).join(', ')
+	const list = tracked.map((child) => session_cite.issue(child)).join(', ')
 
 	return `its body already tracks ${list} as a task list, which would become a second child list`
 }
@@ -61,7 +62,7 @@ function build_promoted_body(input: PromoteInput): string {
 // the children: a declaration-shaped line already present in the issue being promoted is carried
 // into the epic verbatim, and an unordered promotion then adds the `None — ...` literal beside it,
 // so the body would declare an order and declare that there is none. Reported as "does not track
-// every child", that state left nothing to act on (joshuafolkken/kit#1155).
+// every child", that state left nothing to act on.
 function declaration_error(body: string): string | undefined {
 	const state = epic_parse.read_declaration(body)
 	if (epic_parse.is_declaration_readable(state)) return undefined

package/scripts/epic/epic-rank.ts

@@ -1,7 +1,7 @@
 import { issue_rank } from '#scripts/issue/issue-rank'
 import { epic_graph, type EpicChild } from './epic-graph'
 
-// `issue-rank.ts`'s keys over graph children (joshuafolkken/kit#2928), for both offer paths that hand
+// `issue-rank.ts`'s keys over graph children, for both offer paths that hand
 // out children: `backlog:next` (`backlog-rank.ts`) and a named epic's `epic:next --lanes`
 // (`epic-lane-offer.ts`). One ranking, so the two cannot disagree about which child goes first.
 

package/scripts/epic/epic-read.ts

@@ -1,4 +1,5 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_fetch } from './epic-fetch'
 import { epic_graph, type EpicChild } from './epic-graph'
 import { epic_parse } from './epic-parse'
@@ -8,14 +9,14 @@ import { epic_validate, type EpicSubject } from './epic-validate'
 //
 // `--add` and `--remove` need exactly the same three things before they may compute anything: the
 // epic's labels and body, the repository a declared bare number names, and every child with its
-// native relations. They were the same forty lines twice until joshuafolkken/kit#1712 gave the
-// removal a home; a second copy is where one of them comes to accept a graph the other refuses.
+// native relations. They share this one read because a second copy is where one of them comes to
+// accept a graph the other refuses.
 
-// Refused rather than stood in for, and both callers *write*. Since joshuafolkken/kit#1126 a plan
-// filters recorded relations by the declared repository, so a placeholder drops every one of them:
-// the "reconcile them before inserting" guard never fires, the superseded link is never dropped, and
-// relations that already exist are re-POSTed — leaving the epic in exactly the mismatched state
-// `epic:audit` refuses to run on.
+// Refused rather than stood in for, and both callers *write*. A plan filters recorded relations by
+// the declared repository, so a placeholder drops every one of them: the "reconcile them before
+// inserting" guard never fires, the superseded link is never dropped, and relations that already
+// exist are re-POSTed — leaving the epic in exactly the mismatched state `epic:audit` refuses to run
+// on.
 const UNKNOWN_REPO =
 	"Could not read this repository from `git remote`, so the epic's relations cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote."
 
@@ -56,7 +57,8 @@ async function read_recorded(
 // The epic and its current graph, or the reason neither could be read.
 async function read_epic(epic_number: number): Promise<EpicReading | { error: string }> {
 	const subject = await read_subject(epic_number)
-	if (subject === undefined) return { error: `Could not read issue #${String(epic_number)}.` }
+	const unread = `Could not read issue ${session_cite.issue(epic_number)}.`
+	if (subject === undefined) return { error: unread }
 
 	const recorded = await read_recorded(subject.body)
 	if ('error' in recorded) return { error: recorded.error }

package/scripts/epic/epic-reconcile.ts

@@ -1,4 +1,5 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_add_body } from './epic-add-body'
 import { epic_chains } from './epic-chains'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
@@ -8,8 +9,7 @@ import { format_dependency_links } from './epic-reference'
 import { epic_relations } from './epic-relations'
 
 // `josh epic --reconcile <E>` — bring an epic's `## Dependencies` declaration and its native
-// `blocked-by` relations back into agreement, without a hand edit and without recording a decision
-// (joshuafolkken/kit#2235).
+// `blocked-by` relations back into agreement, without a hand edit and without recording a decision.
 //
 // `--add` and `--remove` refuse the moment the two disagree, and `backlog:next` reports the graph
 // unusable, so the only exit was to edit the epic body by hand — the very edit those commands exist
@@ -36,7 +36,7 @@ interface ReconcilePlanInput {
 	body: string | undefined
 	// The epic's children with their native relations, exactly as `epic_read` reads them.
 	recorded: ReadonlyArray<EpicChild>
-	// The epic's own repository — what a declared bare number names (joshuafolkken/kit#1126).
+	// The epic's own repository — what a declared bare number names.
 	repo: string
 }
 
@@ -60,7 +60,7 @@ function to_chain(link: DependencyLink): Array<number> {
 }
 
 // A blocker of `blocked`, keyed to the epic's own repository so a declared bare number names the
-// right issue (joshuafolkken/kit#1126).
+// right issue.
 function to_blocker(link: DependencyLink, repo: string): IssueReference {
 	return { repo, number: link.blocker }
 }
@@ -161,7 +161,7 @@ function build_reconcile_plan(input: ReconcilePlanInput): ReconcilePlan {
 // refused the mismatched epic agree on its order.
 function report_agreement(epic_number: number): void {
 	console.info(
-		`${RECONCILED} #${String(epic_number)} — epic:audit and backlog:next now agree on this epic's order.`,
+		`${RECONCILED} ${session_cite.issue(epic_number)} — epic:audit and backlog:next now agree on this epic's order.`,
 	)
 }
 
@@ -169,7 +169,9 @@ function report_declared(epic_number: number, declare: ReadonlyArray<DependencyL
 	if (declare.length === 0) return
 
 	console.info(
-		`📋 Declared ${format_dependency_links(declare)} in epic #${String(epic_number)} to match the recorded relations.`,
+		session_cite.text(
+			`📋 Declared ${format_dependency_links(declare)} in epic ${session_cite.issue(epic_number)} to match the recorded relations.`,
+		),
 	)
 }
 

package/scripts/epic/epic-reference.ts

@@ -1,3 +1,4 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import type { DependencyLink } from './epic-parse'
 
 // How an issue and a dependency between two of them are written down.
@@ -5,7 +6,7 @@ import type { DependencyLink } from './epic-parse'
 // Both spellings had accumulated a copy per module — the body generator, the graph, the chain model
 // and the insertion planner each rendered `#N` and `#B -> #M` themselves. They are one-liners, which
 // is exactly why the copies spread; and a link rendered one way in a message and another way as a
-// dedup key is a difference nothing would report (joshuafolkken/kit#890).
+// dedup key is a difference nothing would report.
 
 const DEPENDENCY_ARROW = ' -> '
 // How a list of references is written out. One definition rather than a `join` per caller: the
@@ -14,7 +15,7 @@ const DEPENDENCY_ARROW = ' -> '
 const REFERENCE_SEPARATOR = ', '
 
 function to_issue_reference(issue_number: number): string {
-	return `#${String(issue_number)}`
+	return issue_cite.plain(issue_number)
 }
 
 function format_dependency_link(link: DependencyLink): string {
@@ -27,7 +28,7 @@ function join_references(references: ReadonlyArray<string>): string {
 
 // A list of links, in the same form a single one takes. One definition rather than a `map().join()`
 // per caller: the insertion planner and the relation reporter now print the same list side by side,
-// and two spellings of it would read as two different things (joshuafolkken/kit#1080).
+// and two spellings of it would read as two different things.
 function format_dependency_links(links: ReadonlyArray<DependencyLink>): string {
 	return join_references(links.map((link) => format_dependency_link(link)))
 }
@@ -37,7 +38,7 @@ function format_issue_references(issue_numbers: ReadonlyArray<number>): string {
 }
 
 // The `blocked-by` relations a positioned `--add` dropped, named the same way wherever they are
-// reported — on stdout and inside the `--decision-file` record (joshuafolkken/kit#1711). One string
+// reported — on stdout and inside the `--decision-file` record. One string
 // rather than two, because the two are read side by side: a reader comparing the console against the
 // record must not have to decide whether two spellings mean the same thing.
 //

package/scripts/epic/epic-relation-recheck.ts

@@ -1,21 +1,20 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import { epic_parse } from './epic-parse'
 
-// joshuafolkken/kit#1113: a second look at the relations, taken only where the first one is about to
-// become a verdict.
+// A second look at the relations, taken only where the first one is about to become a verdict.
 //
 // `read_blocked_by` answers from the issue's own `issue_dependencies_summary` when that summary says
 // zero, which is what keeps a pass over the whole backlog to one request per issue that declares a
-// blocker (joshuafolkken/kit#1024). The summary is GitHub's count, and it can disagree with the
-// listing it counts: measured on joshuafolkken/kit#1111, whose summary read `total_blocked_by: 0`
-// while `dependencies/blocked_by` returned `#1106`, and where re-POSTing that relation was refused
-// with `Target issue has already been taken` — so the relation was real and only the counter was
-// wrong. `epic:next` read the epic as self-contradictory, printed `declared but not recorded:
-// #1106 -> #1111`, and exited 1. An unattended run stops there, on a graph with nothing to fix.
+// blocker. The summary is GitHub's count, and it can disagree with the listing it counts: a summary
+// can read `total_blocked_by: 0` while `dependencies/blocked_by` returns a blocker whose re-POST is
+// refused with `Target issue has already been taken` — the relation is real and only the counter is
+// wrong. Trusting that counter, `epic:next` reads the epic as self-contradictory, prints `declared
+// but not recorded`, and exits 1. An unattended run stops there, on a graph with nothing to fix.
 //
 // It corrects nothing else. A relation that is genuinely absent still comes back absent, and the
-// mismatch is still reported — the point is that the report is now about the relations rather than
+// mismatch is still reported — the point is that the report is about the relations rather than
 // about a counter.
 
 // A body may legitimately be ahead of its relations — an epic written before `josh` recorded them,
@@ -37,7 +36,7 @@ type BlockersReader = (child: EpicChild) => Promise<Array<IssueReference>>
 // Restricted to `declared_repo` because a declared link is written as a bare number, which names an
 // issue in the epic's own repository — `epic_graph` matches those by number alone. An epic tracking
 // both `#40` and `owner/other#40` would otherwise have the second child re-read on the first one's
-// account, and its relations replaced with a different issue's (joshuafolkken/kit#1014).
+// account, and its relations replaced with a different issue's.
 function suspect_children(
 	children: ReadonlyArray<EpicChild>,
 	body: string | undefined,
@@ -61,7 +60,7 @@ async function reread_child(child: EpicChild, read_blockers: BlockersReader): Pr
 		const reason = error_text.message_of(error)
 
 		console.warn(
-			`⚠ could not re-read the blockers of #${String(child.number)}: ${reason}\n` +
+			`⚠ could not re-read the blockers of ${session_cite.issue(child.number, undefined, child.repo)}: ${reason}\n` +
 				'  a mismatch reported below may be this read failing rather than a missing relation',
 		)
 

package/scripts/epic/epic-relations.ts

@@ -1,4 +1,5 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { session_cite } from '#scripts/issue/session-cite'
 import type { DependencyLink } from './epic-parse'
 import { format_dependency_links } from './epic-reference'
 
@@ -7,11 +8,10 @@ import { format_dependency_links } from './epic-reference'
 // The relation is a nicety, not part of the contract: losing it costs only the native link, while
 // the Issue and its task list are already correct. A failure is therefore counted and reported
 // rather than aborting a batch that is otherwise fine. It no longer depends on the gh CLI's version
-// — the relation is written through the REST dependencies endpoint (joshuafolkken/kit#1026).
+// — the relation is written through the REST dependencies endpoint.
 //
 // Shared by epic creation and `--add` rather than written once per caller: both apply the same
-// relations for the same reason, and a second copy would be the place a fix is forgotten
-// (joshuafolkken/kit#890).
+// relations for the same reason, and a second copy would be the place a fix is forgotten.
 
 type RelationAction = 'record' | 'drop'
 
@@ -41,10 +41,9 @@ function describe_action(action: RelationAction): string {
 	return action === 'record' ? 'recorded' : 'removed'
 }
 
-// What happened, and to which pairs. The count used to stand on its own, and a count cannot be
-// checked: an insertion that recorded an order nobody declared printed the same
-// `1 blocked-by relation(s) recorded.` as a correct one, so the invented chains of
-// joshuafolkken/kit#1080 were caught only by whoever thought to open the epic body afterwards. The
+// What happened, and to which pairs. A count on its own cannot be checked: an insertion that
+// recorded an order nobody declared would print the same `1 blocked-by relation(s) recorded.` as a
+// correct one, so an invented chain would be caught only by whoever opened the epic body. The
 // links are named in the `#blocker -> #blocked` form the declaration itself uses, so the reader
 // compares like with like.
 //
@@ -63,7 +62,9 @@ function format_relation_report(input: {
 	if (input.links.length === 0) return `🔗 No blocked-by relation was ${verb}.`
 
 	if (input.failures === 0) {
-		return `🔗 ${total} blocked-by relation(s) ${verb}: ${format_dependency_links(input.links)}.`
+		return session_cite.text(
+			`🔗 ${total} blocked-by relation(s) ${verb}: ${format_dependency_links(input.links)}.`,
+		)
 	}
 
 	return `⚠️  ${String(input.failures)} of ${total} blocked-by relation(s) could not be ${verb}; the epic body is intact.`