@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/epic/epic-candidate-confirm.ts

@@ -1,20 +1,19 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_classify, type ResolveDependency } from './epic-classify'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import type { BlockersReader } from './epic-relation-recheck'
 import { epic_report, type EpicVerdict } from './epic-report'
 
-// joshuafolkken/kit#1121: the other direction of joshuafolkken/kit#1113's defect, checked where it
-// would otherwise start work.
+// A stale dependency counter, checked where it would otherwise start work.
 //
 // `read_blocked_by` answers from the issue's own `issue_dependencies_summary` when that summary says
-// zero, so a child whose counter is stale is read as `blocked_by: []`. joshuafolkken/kit#1113
+// zero, so a child whose counter is stale is read as `blocked_by: []`. `epic-relation-recheck.ts`
 // re-reads such a child only when the epic body *declared* the missing link, which is the direction
 // that makes `epic:next` exit 1 on a graph with nothing to fix. A relation recorded but never
 // declared leaves no trace in the body, so nothing marks the child as a suspect — and there the
 // mistake runs the other way: the child is classified runnable and handed to an unattended run,
-// which then implements a deliverable before the thing it needs. That is exactly the ordering
-// joshuafolkken/kit#1005 exists to preserve.
+// which then implements a deliverable before the thing it needs.
 //
 // So the summary is not trusted for the one child that is about to be offered. The candidate's
 // relations are read from the listing, and a listing that disagrees replaces that child's
@@ -29,14 +28,14 @@ interface ConfirmContext {
 	resolve: ResolveDependency
 	read_blockers: BlockersReader
 	// The issues this invocation may run, so a re-classified candidate weighs an outside blocker exactly
-	// as `decide` did (joshuafolkken/kit#1943). Absent, the classifier's own default applies.
+	// as `decide` did. Absent, the classifier's own default applies.
 	running?: ReadonlySet<string> | undefined
 }
 
 // The answer for one repository: the children to offer, or the verdict that stands in its place when
 // every candidate was withheld.
 //
-// A list rather than one child since joshuafolkken/kit#1491: a repository runs as many children at
+// A list rather than one child: a repository runs as many children at
 // once as it has free lanes, and how many that is comes from the caller as `wanted`. The type says
 // nothing about lanes or epics — it is a list and a verdict, so the same walk serves one lane, six,
 // or a caller that has not been written yet.
@@ -123,7 +122,7 @@ async function read_or_withhold(
 		const reason = error_text.message_of(error)
 
 		console.warn(
-			`⚠ could not confirm the blockers of #${String(candidate.number)}: ${reason}\n` +
+			`⚠ could not confirm the blockers of ${session_cite.issue(candidate.number, undefined, candidate.repo)}: ${reason}\n` +
 				'  it is withheld rather than offered; asking again is what resolves this',
 		)
 
@@ -137,17 +136,17 @@ function warn_withheld(candidate: EpicChild, listed: ReadonlyArray<IssueReferenc
 	const named = listed.map((blocker) => epic_graph.key_of(blocker)).join(', ')
 
 	console.warn(
-		`⚠ #${String(candidate.number)} is withheld: its relations listing names ${named}, ` +
+		`⚠ ${session_cite.issue(candidate.number, undefined, candidate.repo)} is withheld: its relations listing names ${named}, ` +
 			'which the dependency summary it was classified from did not count',
 	)
 }
 
 // Relations the listing recovered that this epic does not track as a child.
 //
-// `classify_children` weighs such a blocker since joshuafolkken/kit#1943, so a candidate that is still
+// `classify_children` weighs such a blocker, so a candidate that is still
 // offered here has only outside blockers the classifier found finished. The relation is still named,
 // because the run has just paid a request to learn it exists and the graph holds nothing to order it
-// against (joshuafolkken/kit#1121).
+// against.
 function untracked_blockers(
 	listed: ReadonlyArray<IssueReference>,
 	children: ReadonlyArray<EpicChild>,
@@ -161,7 +160,7 @@ function warn_untracked(candidate: EpicChild, untracked: ReadonlyArray<IssueRefe
 	const named = untracked.map((blocker) => epic_graph.key_of(blocker)).join(', ')
 
 	console.warn(
-		`⚠ #${String(candidate.number)} is offered although its relations listing names ${named}: ` +
+		`⚠ ${session_cite.issue(candidate.number, undefined, candidate.repo)} is offered although its relations listing names ${named}: ` +
 			'this epic does not track those, and every one of them is already finished',
 	)
 }
@@ -207,14 +206,13 @@ async function confirm_one(
 
 // The bundle walked from its head until `wanted` candidates have confirmed, or the bundle runs out.
 //
-// Walking on rather than making the whole repository wait is the recorded decision on
-// joshuafolkken/kit#1108: a healthy sibling should not be held for one child whose counter is stale,
+// Walking on rather than making the whole repository wait is deliberate: a healthy sibling should not be held for one child whose counter is stale,
 // and nobody repairs that counter — so the next poll would put the same child at the head and answer
 // the same way, and the wait would never clear. The worst case is one request per candidate, and it
 // happens only when every candidate is withheld, where the epic is broken and stopping is right.
 //
-// **It stops the moment the caller's appetite is met**, so asking for one child costs exactly what
-// it cost before joshuafolkken/kit#1491: the walk ends at the first confirmation.
+// **It stops the moment the caller's appetite is met**, so asking for one child costs one walk to
+// the first confirmation.
 //
 // Recursive rather than a loop with two exits, because the corrected graph has to be threaded from
 // one candidate to the next: a second candidate is classified against what the first read
@@ -254,8 +252,7 @@ function withheld_verdict(
 // The answer for one repository. An empty bundle costs no request and re-derives the verdict the
 // caller already had, so the path a repository with nothing to offer takes is unchanged.
 //
-// `wanted` defaults to one lane, so a caller written before joshuafolkken/kit#1491 asks for exactly
-// what it used to get.
+// `wanted` defaults to one lane.
 async function answer_for_repo(
 	candidates: ReadonlyArray<EpicChild>,
 	context: ConfirmContext,

package/scripts/epic/epic-chains.ts

@@ -6,8 +6,7 @@ import { DEPENDENCY_ARROW, format_dependency_link, to_issue_reference } from './
 // `epic:next` reads the declaration as a flat list of links, which is all a comparison against the
 // native relations requires. An insertion cannot work from that: two disjoint chains and one
 // branching chain produce the same links, and only the line structure says which chain a target sits
-// in. So this module works in chains — one per declared line — and derives the links from them
-// (joshuafolkken/kit#890).
+// in. So this module works in chains — one per declared line — and derives the links from them.
 //
 // Every relation the caller applies comes from diffing the links before against the links after.
 // That is what makes `--before` need no special case: inserting `#N` between `#B` and `#M` drops
@@ -104,7 +103,7 @@ function start_chain(additions: ReadonlyArray<number>, position: InsertPosition)
 // A second declaration alongside the existing ones. Every other chain is copied through untouched,
 // so nothing that was declared about anything else changes. Two callers reach it: a target that no
 // chain names yet, and a `--after` whose target already has a successor — a branch rather than a
-// splice (joshuafolkken/kit#1080).
+// splice.
 function add_chain(
 	chains: Chains,
 	additions: ReadonlyArray<number>,
@@ -116,9 +115,9 @@ function add_chain(
 // No declared chain names the target. Two states look identical from the chains alone, and they are
 // not the same thing: a child the epic tracks simply has no order yet — legitimate in an epic mixing
 // ordered and unordered children — and gets the first order anyone declared for it, as a new line.
-// A number that is not a child at all is still refused (joshuafolkken/kit#949).
-// The only reason left to refuse a position. "Not named in the declared order" used to be it, and is
-// now a legitimate state — a child with no order constraint (joshuafolkken/kit#949). The wording
+// A number that is not a child at all is still refused.
+// The only reason left to refuse a position. "Not named in the declared order" is not one — it is a
+// legitimate state, a child with no order constraint. The wording
 // matches `find_addition_error`'s, which is what the workflow docs tell the operator to expect.
 function not_a_child_error(target: number): InsertOutcome {
 	return {
@@ -145,7 +144,7 @@ function has_successor(chain: Chain, target: number): boolean {
 
 // `--after <M>` where the declaration already names something after `#M`. Splicing there puts the
 // additions between `#M` and that successor, which records `#N -> #<successor>` — an order nobody
-// declared, and the second of joshuafolkken/kit#1080's two paths. What `--after <M>` states is that
+// declared. What `--after <M>` states is that
 // `#M` must finish first, and a fan-out (`#A -> #B` beside `#A -> #C`) already expresses exactly
 // that, so the addition becomes a chain line of its own and the existing one is left as it stood.
 // Appending after the tail is not a branch: with no successor to displace it keeps extending the
@@ -178,8 +177,7 @@ function to_ambiguous_position_error(position: InsertPosition): string {
 // an ambiguity rather than resolve it: with `#890 -> #891` beside `#892 -> #891`, moving `#892` before
 // `#891` leaves one chain naming `#891`, and the insertion then splices into a place nobody
 // identified — recording `#890 -> #892`, an order the caller never asked for, and dropping
-// `#890 -> #891`, one they never asked to lose. So the plan asks this of the declaration as it stands
-// (joshuafolkken/kit#1701).
+// `#890 -> #891`, one they never asked to lose. So the plan asks this of the declaration as it stands.
 //
 // **`before` is the only kind that can do it, and asking it of `after` too refuses the very case this
 // Issue is about.** A `before` splices its child in *front* of the target, so the child inherits
@@ -237,12 +235,10 @@ function insert_at_position(
 // No position given: nothing was declared about the additions, so the declaration is copied through
 // exactly as it stood. An order is recorded only where `--before` / `--after` names one.
 //
-// The additions used to extend the **last declared chain**, and that invented a dependency
-// (joshuafolkken/kit#1253). An epic mixing ordered and unordered children is the normal state
-// (joshuafolkken/kit#949), so an unrelated child added to one came out blocked by whatever issue
-// happened to sit at that chain's tail — and `epic:next` then withheld it as blocked, with neither a
-// park nor a `needs-decision` label to show that it was stuck. An epic with no chain at all was
-// already left alone, which is the same answer this gives for every epic.
+// Extending the **last declared chain** instead would invent a dependency. An epic mixing ordered
+// and unordered children is the normal state, so an unrelated child added to one would come out
+// blocked by whatever issue happened to sit at that chain's tail — and `epic:next` would withhold it
+// as blocked, with neither a park nor a `needs-decision` label to show that it was stuck.
 function keep_declaration(chains: Chains): InsertOutcome {
 	return { chains: chains.map((chain) => [...chain]) }
 }
@@ -292,20 +288,19 @@ function already_declared_error(issue_number: number): string {
 // Checked on the way in *and* on the way out. The result matters more than the input: a child the
 // task list has lost but the declaration still names would otherwise be written into a chain a second
 // time — `--after #892` on `#890 -> #891 -> #892 -> #891` produces a cycle, whose verdict is `error`,
-// which halts the very run this command exists to keep going (joshuafolkken/kit#890). The example was
-// a no-position add until joshuafolkken/kit#1253 stopped that path touching the declaration at all;
-// the guard still matters, because a positioned insert writes into a chain.
+// which halts the very run this command exists to keep going. A no-position add never touches the
+// declaration; the guard matters because a positioned insert writes into a chain.
 //
 // The two guards cover different things, and both are needed since `add_chain` can write into a
 // chain the addition is not in. The in-guard refuses an addition the declaration already names
 // **anywhere**; the out-guard catches a repeat **within one chain**. The out-guard deliberately does
 // not scan across chains: one issue named by two of them is a fan-out — `#A -> #B` and `#A -> #C` —
-// which is a legitimate declaration, not a duplicate (joshuafolkken/kit#949).
+// which is a legitimate declaration, not a duplicate.
 // `tracked` is the epic's task list, and it is required rather than defaulted. It separates "this
 // child has no order yet" from "this number is not a child at all": the first gets a new chain, the
 // second is refused. A default would make one path refuse everything and the other check nothing, so
 // the same input would be accepted or refused depending only on whether anything happened to be
-// declared yet (joshuafolkken/kit#949).
+// declared yet.
 // Everything that can refuse the input, before anything is built from it.
 function find_insertion_error(
 	chains: Chains,
@@ -325,7 +320,7 @@ function find_insertion_error(
 // A reorder expressed as a removal followed by the ordinary insertion. Splicing the child out of
 // every chain that names it closes the chain around it — `#A -> #N -> #B` becomes `#A -> #B` — so the
 // re-insertion goes through `insert_children` unchanged, and the relations to drop still fall out of
-// diffing the declaration before against the declaration after (joshuafolkken/kit#1701).
+// diffing the declaration before against the declaration after.
 //
 // A chain left with one reference declares nothing and is dropped rather than rendered as a bare
 // `#N`, which the parser would read as prose. Its remaining child simply has no order any more,
@@ -358,7 +353,7 @@ function split_chain(chain: Chain, dropped: ReadonlySet<string>): Array<Array<nu
 }
 
 // A declared order removed: every chain is cut at each named link, and **the ends are never
-// reconnected** (joshuafolkken/kit#1712). `#A -> #B -> #C` minus `#B -> #C` leaves `#A -> #B`, and
+// reconnected**. `#A -> #B -> #C` minus `#B -> #C` leaves `#A -> #B`, and
 // removing a middle child's two links leaves `#A` and `#C` with no order rather than `#A -> #C`.
 //
 // Reconnecting would declare an order nobody stated, which is exactly what the audit shipped beside
@@ -397,7 +392,7 @@ const epic_chains = {
 	links_of,
 	diff_links,
 	find_position_ambiguity,
-	// Exported since joshuafolkken/kit#1738 so `--order-before` / `--order-after` can pass the
+	// Exported so `--order-before` / `--order-after` can pass the
 	// declaration through by the same function `--add` without a position uses. An order-only move is
 	// "leave the declaration exactly as it stood" applied to a call that *does* name a position, so a
 	// second copy of the passthrough would be the clone `CLAUDE.md` prohibits.

package/scripts/epic/epic-classify.ts

@@ -19,14 +19,13 @@ import {
 // difference is not academic: the moment kit's child closes and app-kit's child is waiting for the
 // release to publish, there is no runnable child, nothing carries `in-progress` (kit's child is
 // closed) and nothing carries `needs-decision` (nothing was parked). A label-based reading sees
-// "nothing running, nothing parked" and stops — in the one situation where it should wait
-// (joshuafolkken/kit#860).
+// "nothing running, nothing parked" and stops — in the one situation where it should wait.
 
 // What a caller does with a child: run it, wait for it, or stop and report it.
 type ChildCategory = 'runnable' | 'time' | 'human' | 'done'
 
 // `DependencyVerdict` and `ResolveDependency` live in `epic-outside-blocker.ts`, which weighs a
-// blocker no graph tracks with the same resolver (joshuafolkken/kit#1943), and are re-exported below.
+// blocker no graph tracks with the same resolver, and are re-exported below.
 
 interface Classification {
 	runnable: ReadonlyArray<EpicChild>
@@ -51,7 +50,7 @@ function has_label(child: EpicChild, label: string): boolean {
 
 // The labels that put a child in `human` on their own. `needs-decision` waits for an answer nobody
 // has given; `already-done` has its answer — the work is merged, and the close that is left is Tier C
-// and so a person's (joshuafolkken/kit#1679). Neither is resolved by waiting, which is what separates
+// and so a person's. Neither is resolved by waiting, which is what separates
 // them from `in-progress` below.
 const HUMAN_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
 
@@ -62,12 +61,12 @@ function has_human_label(child: EpicChild): boolean {
 // What a child is before its dependencies are considered. A parked child is `human` whatever blocks
 // it, and a child already being worked on is `time` — someone else's session will finish it.
 //
-// **A child that is itself an epic is `human`** (joshuafolkken/kit#1476). An epic is not a unit of
+// **A child that is itself an epic is `human`**. An epic is not a unit of
 // work, so a run handed one has nothing to implement; before this the row fell straight through to
 // `from_blockers`, which mints `runnable` for anything unblocked, and `epicrun` passed the epic to
 // `fullrun` as an ordinary issue. `human` rather than `time` because no amount of waiting turns an
 // epic into work: a person has to flatten the row or restructure the epics, and meta-epic support is
-// frozen (joshuafolkken/kit#894). What the question is — and, just as importantly, what it is not —
+// frozen. What the question is — and, just as importantly, what it is not —
 // is `epic-nested.ts`, which the audit asks the same way.
 function local_category(child: EpicChild): ChildCategory | undefined {
 	if (child.state === CLOSED) return 'done'
@@ -99,9 +98,9 @@ interface ClassifyContext {
 	index: ReadonlyMap<string, EpicChild>
 	resolve: ResolveDependency
 	// Keyed by identity — repository plus number — because two children of one epic can share a
-	// number across repositories (joshuafolkken/kit#864).
+	// number across repositories.
 	memo: Map<string, ChildCategory>
-	// Every issue this invocation may run, keyed like `index` (joshuafolkken/kit#1943). A blocker
+	// Every issue this invocation may run, keyed like `index`. A blocker
 	// outside `index` waits when it is in here and goes to a person when it is not.
 	running: ReadonlySet<string>
 }
@@ -125,9 +124,9 @@ function report_notice(notice: OutsideNotice): void {
 	console.warn(notice.message)
 }
 
-// A blocker no graph in this invocation tracks. It used to be announced and dropped, which offered a
-// child waiting on another epic's open issue as runnable; it is weighed now, and what could not be
-// decided is still said out loud (joshuafolkken/kit#1126, joshuafolkken/kit#1943).
+// A blocker no graph in this invocation tracks. It is weighed rather than announced and dropped, which
+// would offer a child waiting on another epic's open issue as runnable; what could not be decided is
+// still said out loud.
 function outside_category(
 	child: EpicChild,
 	reference: IssueReference,
@@ -147,7 +146,7 @@ function outside_category(
 
 // Said out loud because the report cannot say it: a withheld epic prints as a bare `#N` under
 // "Waiting on a person", which is true of a parked issue and of an epic alike, and the two need
-// entirely different things done to them (joshuafolkken/kit#1476).
+// entirely different things done to them.
 function report_nested_epic(child: EpicChild): void {
 	const line = `epic:${epic_graph.key_of(child)}`
 	if (reported.has(line)) return

package/scripts/epic/epic-cli-argv.ts

@@ -1,20 +1,19 @@
 import type { ParseArgsOptionsConfig } from 'node:util'
 import { cli_flags } from '#scripts/lib/cli-flags'
 
-// The argument reading every `josh epic` form shares, on top of `cli_flags` (joshuafolkken/kit#3261).
+// The argument reading every `josh epic` form shares, on top of `cli_flags`.
 //
-// They were private to `epic-cli.ts` until `--remove` needed the same readers (joshuafolkken/kit#1712),
+// They were private to `epic-cli.ts` until `--remove` needed the same readers,
 // at which point the choice was to copy them or to name them. Copying is what `CLAUDE.md` prohibits,
 // and the failure it would produce is specific: two readers disagreeing about what counts as a flag
 // value would have one form silently take a `--decision-file` path for an issue number.
 //
 // **Each form names its own flags, and the read is strict.** Which flags consume the argument after
 // them is per form: `--before` takes a value only under `--add`, and treating it as one everywhere had
-// `josh epic "T" 101 102 --after 103` silently drop #103 (joshuafolkken/kit#890). A flag the form does
+// `josh epic "T" 101 102 --after 103` silently drop #103. A flag the form does
 // not know refuses the invocation — a mistyped flag would otherwise leave its value positional, so it
 // becomes an issue number and the edit silently lands somewhere else.
 
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 // Every value flag is read as a list so a repeat is visible rather than resolved to one of the two:
 // two `--decision-file` paths name two records, and two `--before` targets name two places.
 const VALUE_OPTION = { type: 'string', multiple: true } as const
@@ -88,7 +87,7 @@ function is_switch_set(parsed: EpicArgv, flag: string): boolean {
 // A value-taking flag given without a usable value, or given twice. **Refused rather than read as "none
 // was asked for"** — `--decision-file` is passed precisely because the record has to exist, so a shell
 // that ate the path would otherwise land the edit, write no record, post no comment and exit 0: success
-// reported for half the job. Repeated, it names two records (joshuafolkken/kit#1350).
+// reported for half the job. Repeated, it names two records.
 function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
 	return (
 		cli_flags.given_values(argv, flag).length > SINGLE || cli_flags.is_value_unusable(argv, flag)
@@ -104,5 +103,5 @@ const epic_cli_argv = {
 	is_value_unusable,
 }
 
-export { epic_cli_argv, ISSUE_NUMBER_PATTERN }
+export { epic_cli_argv }
 export type { EpicArgv, FormFlags }

package/scripts/epic/epic-cli-remove.ts

@@ -1,6 +1,7 @@
-import { epic_cli_argv, ISSUE_NUMBER_PATTERN, type EpicArgv, type FormFlags } from './epic-cli-argv'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { epic_cli_argv, type EpicArgv, type FormFlags } from './epic-cli-argv'
 
-// `josh epic --remove <E> <M> <N> …`'s argument rules (joshuafolkken/kit#1712).
+// `josh epic --remove <E> <M> <N> …`'s argument rules.
 //
 // Its own module rather than a fourth parser inside `epic-cli.ts`, which sits at its line ceiling —
 // and because the rules read as one thing: the arguments after the epic are a **path**, which is the
@@ -30,14 +31,18 @@ function is_removal(argv: ReadonlyArray<string>): boolean {
 // repeat would silently delete a different set of orders than the one typed, and skipping an
 // unparsable argument would shift every pair after it.
 function to_path_numbers(raw_path: ReadonlyArray<string>): Array<number> | undefined {
-	if (raw_path.some((raw) => !ISSUE_NUMBER_PATTERN.test(raw))) return undefined
+	if (raw_path.some((raw) => !issue_number_shape.is_issue_number(raw))) return undefined
 
 	return raw_path.length < MINIMUM_PATH_LENGTH ? undefined : raw_path.map(Number)
 }
 
 function read_subject(parsed: EpicArgv): { epic_number: number; path: Array<number> } | undefined {
 	const [raw_epic, ...raw_path] = parsed.positionals
-	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+
+	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
+		return undefined
+	}
+
 	const path = to_path_numbers(raw_path)
 
 	return path === undefined ? undefined : { epic_number: Number(raw_epic), path }

package/scripts/epic/epic-cli.ts

@@ -1,6 +1,8 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
 import { cli_body } from '#scripts/josh/cli-body'
 import type { InsertKind, InsertPosition } from './epic-chains'
-import { epic_cli_argv, ISSUE_NUMBER_PATTERN, type EpicArgv, type FormFlags } from './epic-cli-argv'
+import { epic_cli_argv, type EpicArgv, type FormFlags } from './epic-cli-argv'
 import { epic_cli_remove } from './epic-cli-remove'
 import { epic_parse, type ExternalChild } from './epic-parse'
 
@@ -12,20 +14,20 @@ const RATIONALE_FLAG = '--rationale-file'
 const ORIGIN_FLAG = '--origin'
 const PROMOTE_FLAG = '--promote'
 const ADD_FLAG = '--add'
-// `--reconcile <E>`: bring the epic's declaration and its recorded relations back into agreement
-// (joshuafolkken/kit#2235). It takes no value flags — the epic number is the whole subject.
+// `--reconcile <E>`: bring the epic's declaration and its recorded relations back into agreement.
+// It takes no value flags — the epic number is the whole subject.
 const RECONCILE_FLAG = '--reconcile'
 const BEFORE_FLAG = '--before'
 const AFTER_FLAG = '--after'
 // The same two places with the declaration withheld: move the task-list row and write neither the
-// dependency declaration nor the `blocked-by` relation (joshuafolkken/kit#1738). They exist because
+// dependency declaration nor the `blocked-by` relation. They exist because
 // `epic:next` offers children in task-list order, so "no dependency, but run this one first" had no
 // spelling at all — only a false dependency, or a row nobody would reach.
 const ORDER_BEFORE_FLAG = '--order-before'
 const ORDER_AFTER_FLAG = '--order-after'
 // The decision record for an insertion, read the same way `--rationale-file` is read for a creation:
 // from a file, or from stdin as `-`. The text is a judgement, so the caller writes it; what the command
-// contributes is placing it in the epic's `## Decisions` and on each child (joshuafolkken/kit#1350).
+// contributes is placing it in the epic's `## Decisions` and on each child.
 const DECISION_FLAG = '--decision-file'
 // Which flags each form knows, and which of them consume the argument after them — per form, for the
 // reason `epic-cli-argv.ts` gives.
@@ -53,7 +55,7 @@ interface CreateArguments {
 }
 
 // `--promote <N> <N1> <N2> …`: the issue to promote, then its children. No title — the issue already
-// has one, and the discussion in it is usually the split rationale (joshuafolkken/kit#865).
+// has one, and the discussion in it is usually the split rationale.
 interface PromoteArguments {
 	epic_number: number
 	children: Array<number>
@@ -66,7 +68,7 @@ interface PromoteArguments {
 // `--ordered` would ask GitHub to make an issue block itself.
 function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
 	const numbers = raw_children
-		.filter((raw) => ISSUE_NUMBER_PATTERN.test(raw))
+		.filter((raw) => issue_number_shape.is_issue_number(raw))
 		.map(Number)
 		.filter((value) => Number.isSafeInteger(value))
 
@@ -120,7 +122,10 @@ interface ReconcileArguments {
 // and no position — the repair reads what the epic already records rather than being told an order.
 function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArguments | undefined {
 	const [raw_epic] = positionals_of(argv, RECONCILE_FORM)
-	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+
+	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
+		return undefined
+	}
 
 	return { epic_number: Number(raw_epic) }
 }
@@ -130,7 +135,11 @@ function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArgume
 // have it block itself under `--ordered`.
 function to_promote_arguments(parsed: EpicArgv): PromoteArguments | undefined {
 	const [raw_epic, ...raw_children] = parsed.positionals
-	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+
+	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
+		return undefined
+	}
+
 	const epic_number = Number(raw_epic)
 	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
 	if (children.length === 0) return undefined
@@ -146,13 +155,13 @@ function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments
 
 // `--add <E> <N...> [--before <M> | --after <M> | --order-before <M> | --order-after <M>]`: the epic
 // to insert into, then the children. The epic comes first for the same reason it does under
-// `--promote`, so the children stay a bare list of numbers (joshuafolkken/kit#890).
+// `--promote`, so the children stay a bare list of numbers.
 interface AddArguments {
 	epic_number: number
 	children: Array<number>
 	position?: InsertPosition | undefined
 	// `--order-before` / `--order-after` rather than `--before` / `--after`: the row moves and nothing
-	// else is written (joshuafolkken/kit#1738).
+	// else is written.
 	is_order_only?: boolean | undefined
 	decision_path?: string | undefined
 }
@@ -165,7 +174,7 @@ function is_addition(argv: ReadonlyArray<string>): boolean {
 // The outcome of reading a positioning flag: the position, nothing, or a refusal. One shape for all
 // three so the caller branches on a field rather than on a value's type. `is_order_only` rides on the
 // same value because one flag decides both halves — where the row goes, and whether a dependency is
-// written behind it (joshuafolkken/kit#1738).
+// written behind it.
 interface PositionOutcome {
 	position?: InsertPosition
 	is_order_only?: boolean
@@ -176,7 +185,7 @@ const NO_POSITION: PositionOutcome = { is_refused: false }
 const REFUSED_POSITION: PositionOutcome = { is_refused: true }
 
 // The four positioning flags as one table: the place each one names, and whether a dependency is
-// written behind the row it moves. **One table rather than two branches** (joshuafolkken/kit#1738) —
+// written behind the row it moves. **One table rather than two branches** —
 // `--order-before` asks the same placement question `--before` does, so a second parsing path could
 // come to disagree with this one about what a repeated flag or a non-numeric target means.
 interface PositionFlag {
@@ -224,7 +233,7 @@ function parse_position(parsed: EpicArgv): PositionOutcome {
 	const has_flag = count_position_flags(parsed) > 0
 	const target = read_position_target(parsed)
 	if (target === undefined) return has_flag ? REFUSED_POSITION : NO_POSITION
-	if (!ISSUE_NUMBER_PATTERN.test(target.raw)) return REFUSED_POSITION
+	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(target.raw)) return REFUSED_POSITION
 
 	return {
 		position: { kind: target.kind, target: Number(target.raw) },
@@ -245,7 +254,11 @@ function read_add_subject(
 	parsed: EpicArgv,
 ): { epic_number: number; children: Array<number> } | undefined {
 	const [raw_epic, ...raw_children] = parsed.positionals
-	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+
+	if (raw_epic === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw_epic)) {
+		return undefined
+	}
+
 	const epic_number = Number(raw_epic)
 	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
 
@@ -267,7 +280,7 @@ function to_add_arguments(parsed: EpicArgv): AddArguments | undefined {
 }
 
 // An unknown flag is refused by the strict read: a mistyped positioning flag would otherwise leave its
-// value positional, so it becomes a child and the edit lands somewhere else (joshuafolkken/kit#890).
+// value positional, so it becomes a child and the edit lands somewhere else.
 function parse_add_arguments(argv: ReadonlyArray<string>): AddArguments | undefined {
 	const parsed = is_decision_path_unusable(argv) ? undefined : read_form(argv, ADD_FORM)
 
@@ -277,7 +290,7 @@ function parse_add_arguments(argv: ReadonlyArray<string>): AddArguments | undefi
 // The one refusal `--add` has to explain rather than merely report. `into owner/repo#N` is a legal
 // thing for a person to type, and this command cannot serve it: it reads and edits issues in the
 // repository it is run from. Falling through to the usage line would read as "that form does not
-// exist" when what it means is "run it in the other checkout" (joshuafolkken/kit#985).
+// exist" when what it means is "run it in the other checkout".
 interface CrossRepoAddTarget {
 	epic: ExternalChild
 	local: AddArguments
@@ -307,7 +320,7 @@ function find_cross_repo_add_target(argv: ReadonlyArray<string>): CrossRepoAddTa
 function format_add_arguments(local: AddArguments): string {
 	const { position } = local
 	// The order-only prefix rides along, since it is what decides whether the other checkout writes a
-	// dependency — a suggestion that dropped it would be a different instruction (joshuafolkken/kit#1738).
+	// dependency — a suggestion that dropped it would be a different instruction.
 	const prefix = local.is_order_only === true ? '--order-' : '--'
 	const suffix =
 		position === undefined ? '' : ` ${prefix}${position.kind} ${String(position.target)}`
@@ -315,7 +328,7 @@ function format_add_arguments(local: AddArguments): string {
 	return `${[local.epic_number, ...local.children].map(String).join(' ')}${suffix}`
 }
 
-// **`--decision-file` is named rather than relayed** (joshuafolkken/kit#1350). The suggestion is a
+// **`--decision-file` is named rather than relayed**. The suggestion is a
 // command to run in a *different* checkout, and the path was resolved against this one: a relative path
 // does not exist there, `-` cannot be re-read from a consumed stdin, and an unquoted path with a space
 // would break the line the person copies. So the flag is asked for again instead of pasted in wrong.
@@ -329,8 +342,8 @@ function format_decision_note(local: AddArguments): Array<string> {
 
 // A fully-qualified reference to *this* repository is the same instruction spelled longer, not a
 // cross-repository one — and `into owner/repo#N` is exactly how the suffix is documented, so a run
-// inside that repository would otherwise be refused and told to go to the checkout it is already in
-// (joshuafolkken/kit#985). An unreadable current repository resolves to a refusal rather than to a
+// inside that repository would otherwise be refused and told to go to the checkout it is already in.
+// An unreadable current repository resolves to a refusal rather than to a
 // write: refusing costs one command, and guessing wrong writes into the wrong epic.
 function resolve_local_add(
 	found: CrossRepoAddTarget,
@@ -342,7 +355,7 @@ function resolve_local_add(
 // What to type instead. `josh doctor` prints the checkout for each repository, which is the part a
 // run cannot guess.
 function format_cross_repo_refusal(found: CrossRepoAddTarget): string {
-	const reference = `${found.epic.repo}#${String(found.epic.number)}`
+	const reference = session_cite.issue(found.epic.number, undefined, found.epic.repo)
 
 	return [
 		`✖ ${reference} is an epic in another repository; this command reads and writes issues in the repository it runs from.`,
@@ -353,14 +366,14 @@ function format_cross_repo_refusal(found: CrossRepoAddTarget): string {
 
 function parse_check_argument(argv: ReadonlyArray<string>): number | undefined {
 	const [raw] = positionals_of(argv, CHECK_FORM)
-	if (raw === undefined || !ISSUE_NUMBER_PATTERN.test(raw)) return undefined
+	if (raw === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(raw)) return undefined
 
 	return Number(raw)
 }
 
 // `-` reads stdin, matching `gh issue create --body-file -`. The reader is `cli_body`'s, shared with
 // `josh notify --body-file` and `josh followup --notify-message-file` rather than copied per entry
-// point (joshuafolkken/kit#1198), so the stdin form cannot come to mean one thing here and something
+// point, so the stdin form cannot come to mean one thing here and something
 // else there.
 const { read_file_or_stdin } = cli_body
 
@@ -371,8 +384,7 @@ function read_rationale(rationale_path: string | undefined): string {
 }
 
 // `undefined` rather than `''` for an omitted path: an insertion that records no decision is the
-// ordinary case, and an empty string is a record that says nothing — which `epic --add` refuses
-// (joshuafolkken/kit#1350).
+// ordinary case, and an empty string is a record that says nothing — which `epic --add` refuses.
 function read_decision(decision_path: string | undefined): string | undefined {
 	return decision_path === undefined ? undefined : read_file_or_stdin(decision_path)
 }