@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -9,11 +9,10 @@ import { epic_shape } from './epic-shape'
 // Everything `josh epic --remove` decides before it writes anything.
 //
 // A declared order lives in two places at once — the epic body's `Dependencies` declaration and the
-// native `blocked-by` relations — and until this command there was no way to delete one from both at
-// once. The only route was the hand edit `CLAUDE.md` forbids plus a bare `DELETE` on the
-// dependencies endpoint, and doing either half alone leaves `epic:next` answering
-// `declaration_mismatch`, which stops an unattended run. Epic joshuafolkken/kit#1262 recorded
-// twenty-nine such removals before the command existed (joshuafolkken/kit#1712).
+// native `blocked-by` relations — and this command deletes one from both at once. The alternative is
+// the hand edit `CLAUDE.md` forbids plus a bare `DELETE` on the dependencies endpoint, and doing
+// either half alone leaves `epic:next` answering `declaration_mismatch`, which stops an unattended
+// run.
 //
 // Kept apart from the GitHub calls for the reason `epic-add-plan.ts` is: the whole decision is
 // asserted without a network, and a refusal path only reachable through `gh` is one nobody tests.

package/scripts/epic/epic-remove.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_decision } from './epic-decision'
 import { epic_read } from './epic-read'
 import { format_dependency_links } from './epic-reference'
@@ -6,13 +7,12 @@ import { epic_relations } from './epic-relations'
 import { epic_remove_plan, type RemovePlan } from './epic-remove-plan'
 
 // `josh epic --remove <E> <M> <N> [<N2> ...] [--decision-file <path|->]` — delete a declared order
-// from the epic's body and from the native `blocked-by` relations in one input
-// (joshuafolkken/kit#1712).
+// from the epic's body and from the native `blocked-by` relations in one input.
 //
 // It is `--add`'s missing counterpart. `--add` exists because writing the declaration and the
 // relations separately is what leaves them disagreeing; deleting them separately leaves them
-// disagreeing in exactly the same way, and there was no command for it at all — so the only route
-// was the hand edit `CLAUDE.md` forbids, twenty-nine times over on epic joshuafolkken/kit#1262.
+// disagreeing in exactly the same way, and without a command for it the only route is the hand edit
+// `CLAUDE.md` forbids.
 
 const FAILURE_EXIT_CODE = 1
 const SUCCESS_EXIT_CODE = 0
@@ -54,7 +54,9 @@ async function write_plan(
 ): Promise<void> {
 	await git_gh_command.issue_edit_body(String(epic_number), plan.body)
 	console.info(
-		`📋 Removed ${format_dependency_links(plan.links)} from epic #${String(epic_number)}.`,
+		session_cite.text(
+			`📋 Removed ${format_dependency_links(plan.links)} from epic ${session_cite.issue(epic_number)}.`,
+		),
 	)
 	report_relations(plan, await epic_relations.apply_relations(plan.removed, 'drop'))
 

package/scripts/epic/epic-report.ts

@@ -3,9 +3,8 @@ import { epic_graph, type EpicChild, type GraphAnomaly } from './epic-graph'
 
 // Turning a classification into the answer a caller acts on.
 //
-// The verdict is what `epicrun` (joshuafolkken/kit#861) branches on, so the three "nothing to run"
-// cases are kept apart: waiting, stopping, and being finished are different instructions
-// (joshuafolkken/kit#860).
+// The verdict is what `epicrun` branches on, so the three "nothing to run"
+// cases are kept apart: waiting, stopping, and being finished are different instructions.
 
 // What the caller should do next.
 type EpicVerdict = 'run' | 'wait' | 'stop' | 'complete' | 'error'
@@ -13,17 +12,16 @@ type EpicVerdict = 'run' | 'wait' | 'stop' | 'complete' | 'error'
 interface RepoCandidates {
 	repo: string
 	children: ReadonlyArray<EpicChild>
-	// The local checkout a runner would work in, from joshuafolkken/kit#869's map. Absent when the
+	// The local checkout a runner would work in, from the checkout discovery map. Absent when the
 	// repository is not checked out here — reported rather than cloned, since creating a working tree
-	// nobody asked for is not a step this command takes (joshuafolkken/kit#864).
+	// nobody asked for is not a step this command takes.
 	path?: string
 }
 
 interface EpicNextResult {
 	verdict: EpicVerdict
 	// Runnable children bundled per repository. How many of one bundle may start at once is the
-	// repository's free-lane count, which `epic-lane-offer.ts` decides and this report does not know
-	// (joshuafolkken/kit#1491).
+	// repository's free-lane count, which `epic-lane-offer.ts` decides and this report does not know.
 	candidates: ReadonlyArray<RepoCandidates>
 	waiting: ReadonlyArray<EpicChild>
 	blocked_on_people: ReadonlyArray<EpicChild>
@@ -32,12 +30,12 @@ interface EpicNextResult {
 
 // Bundle by repository, repositories in name order, so a run is reproducible rather than dependent
 // on the order GitHub happened to list the repositories in. **The children are not re-ordered at
-// all** since joshuafolkken/kit#1583 — they keep the order the epic's task list gave them, which is
+// all** — they keep the order the epic's task list gave them, which is
 // how an epic says which of its runnable children goes first; the reasoning is at `bundle_by_repo`
 // below.
 // The discovery map is keyed lowercase — GitHub resolves owner and repository names
 // case-insensitively — so the lookup lowercases too. Without it any capital in a repository name
-// printed "no local checkout" for a repository that is checked out (joshuafolkken/kit#864).
+// printed "no local checkout" for a repository that is checked out.
 //
 // `exactOptionalPropertyTypes` rejects `{ path: undefined }`, so the key is added only when there
 // is a path to put in it.
@@ -63,14 +61,14 @@ function bundle_by_repo(
 	for (const [repo] of grouped) repos.push(repo)
 
 	// **The children keep the order they arrived in, which is the order the epic's task list names
-	// them** (joshuafolkken/kit#1583). They used to be re-sorted by issue number here, on the premise
-	// that number order is split order — true only of an epic whose children were all filed in one
-	// split, and false of every epic that grows as work is found: there the number order is *filing*
-	// order, and an epic had no way at all to say which of its runnable children should go first.
+	// them**. Re-sorting by issue number would assume that number order is split order — true only of
+	// an epic whose children were all filed in one split, and false of every epic that grows as work
+	// is found: there the number order is *filing* order, and an epic would have no way at all to say
+	// which of its runnable children should go first.
 	//
-	// Nothing else had to change to make the body order authoritative: `epic-fetch.ts` →
-	// `fetch_children` already reads the task list in body order and `epic-classify.ts` fills
-	// `runnable` in that order, so this sort was the one step discarding it.
+	// The body order is authoritative end to end: `epic-fetch.ts` → `fetch_children` reads the task
+	// list in body order and `epic-classify.ts` fills `runnable` in that order, so a sort here would be
+	// the one step discarding it.
 	//
 	// **The repositories are still sorted by name**, which is a different question — that is grouping,
 	// not the order work is offered in.
@@ -115,7 +113,7 @@ function build_result(
 }
 
 // Every runnable child of one repository, in the order they would be offered — **the order the
-// epic's own task list names them** (joshuafolkken/kit#1583). It was lowest number first until then,
+// epic's own task list names them**. It was lowest number first until then,
 // on the premise that number order is split order; an epic that gains children as work is found has
 // no such property, and the epic could not express a priority at all.
 //
@@ -126,7 +124,7 @@ function build_result(
 //
 // The whole bundle rather than only its head, because the confirmation walk needs the rest of it: a
 // candidate whose relations listing disagrees with its summary is withheld and the next one is
-// confirmed in its place (joshuafolkken/kit#1121).
+// confirmed in its place.
 function candidates_for_repo(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
 	return result.candidates.find((bundle) => bundle.repo === repo)?.children ?? []
 }
@@ -138,8 +136,8 @@ function format_bundle_heading(bundle: RepoCandidates): string {
 }
 
 // A child in another repository is written `owner/repo#N`, not a bare `#N` — a bare number resolves
-// against the reader's own repository and would linkify to the wrong issue there
-// (joshuafolkken/kit#2329). This reuses the one spelling `epic_graph.format_reference` already gives
+// against the reader's own repository and would linkify to the wrong issue there.
+// This reuses the one spelling `epic_graph.format_reference` already gives
 // every other read of a child, rather than a second one here.
 function format_child(child: EpicChild, current_repo: string): string {
 	return `    ${epic_graph.format_reference(child, current_repo)}`

package/scripts/epic/epic-run.ts

@@ -1,5 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { EPIC_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_body } from './epic-body'
 import { epic_promote } from './epic-promote'
 import { epic_relations } from './epic-relations'
@@ -128,7 +129,7 @@ async function read_promotion_subject(epic_number: number): Promise<EpicSubject
 	)
 
 	if (subject === undefined) {
-		console.error(`✖ Could not read issue #${String(epic_number)}.`)
+		console.error(`✖ Could not read issue ${session_cite.issue(epic_number)}.`)
 
 		return undefined
 	}
@@ -136,7 +137,7 @@ async function read_promotion_subject(epic_number: number): Promise<EpicSubject
 	if (epic_promote.has_conflicting_tracking(subject.body)) {
 		const reason = epic_promote.conflict_reason(subject.body)
 
-		console.error(`✖ Cannot promote #${String(epic_number)}: ${reason}.`)
+		console.error(`✖ Cannot promote ${session_cite.issue(epic_number)}: ${reason}.`)
 
 		return undefined
 	}
@@ -168,7 +169,7 @@ async function write_promotion(
 	}
 
 	console.error(
-		`✖ Wrote the epic sections to #${String(input.epic_number)} but could not apply the \`${EPIC_LABEL}\` label; apply it by hand.`,
+		`✖ Wrote the epic sections to ${session_cite.issue(input.epic_number)} but could not apply the \`${EPIC_LABEL}\` label; apply it by hand.`,
 	)
 
 	return FAILURE_EXIT_CODE
@@ -188,7 +189,7 @@ async function promote_epic(input: PromoteEpicInput): Promise<number> {
 	const written = await write_promotion(input, subject.body)
 	if (written !== SUCCESS_EXIT_CODE) return written
 
-	console.info(`📋 Promoted #${String(input.epic_number)} to an epic.`)
+	console.info(`📋 Promoted ${session_cite.issue(input.epic_number)} to an epic.`)
 	await apply_dependencies({ children: input.children, is_ordered: input.is_ordered })
 	console.info(`▶ Run the children with: ${epic_body.format_run_command(input.epic_number)}`)
 
@@ -200,7 +201,7 @@ async function check_epic(epic_number: number): Promise<number> {
 	const subject = epic_validate.parse_epic_subject(raw)
 
 	if (subject === undefined) {
-		console.error(`✖ Could not read issue #${String(epic_number)}.`)
+		console.error(`✖ Could not read issue ${session_cite.issue(epic_number)}.`)
 
 		return FAILURE_EXIT_CODE
 	}

package/scripts/epic/epic-sections.ts

@@ -6,7 +6,7 @@ import { epic_parse } from './epic-parse'
 // declaration is replaced inside it rather than wherever a declaration-shaped line happens to sit.
 // `## Decisions` needs the identical search, and a second copy of it is the clone `CLAUDE.md`
 // prohibits — the fence mask especially, since a heading inside a fenced block is an illustration and
-// a copy that forgot it would append a decision into a quoted template (joshuafolkken/kit#1350).
+// a copy that forgot it would append a decision into a quoted template.
 //
 // Nothing here writes. The two consumers decide what to do with a range; this decides where one is.
 
@@ -65,7 +65,7 @@ function is_section_end(input: BodyLines, index: number, level: number): boolean
 // Where the named section runs: the lines after its heading, up to the next heading **of the same or a
 // higher level**. Not "the next heading of any level" — `## Decisions` is written as one `###` entry per
 // decision, the template the epic body documents, so ending at any heading would make the section one
-// line long and place every appended record after its first entry (joshuafolkken/kit#1350). A `##`
+// line long and place every appended record after its first entry. A `##`
 // section running to the next `##` is what a reader of the body already takes it to mean.
 //
 // `undefined` is "the body has no such section", which is a different answer from an empty one — the

package/scripts/epic/epic-shape.ts

@@ -8,7 +8,7 @@ import { to_issue_reference } from './epic-reference'
 // label, a task list to place rows in, and a declaration
 // their edit can be relative to. It lives in one module rather than in each of them, because the two
 // commands must refuse the same inputs for the same reasons — a second copy is where one comes to
-// accept an epic the other refuses (joshuafolkken/kit#1712).
+// accept an epic the other refuses.
 
 // The part of an epic these refusals read. Narrower than either command's own input on purpose: a
 // shape check that could see the children being placed would invite conditions that belong to the
@@ -30,7 +30,7 @@ function missing_declaration_error(epic_number: number): string {
 // choice between promoting and creating a new epic depends on what the target *is*, which only a
 // reader of it knows (`.claude/skills/workflow-commands/split-assessment.md` → promote-or-create).
 // Naming both arms is what keeps the refusal one command away from being actionable rather than a
-// dead end, which is the whole point of `into <target>` (joshuafolkken/kit#985).
+// dead end, which is the whole point of `into <target>`.
 function promote_remedy(epic_number: number): string {
 	const promote = `josh epic --promote ${String(epic_number)} <N...>`
 
@@ -41,7 +41,7 @@ function promote_remedy(epic_number: number): string {
 // differently: without rows there is nowhere to put a new one, and without a declaration there is
 // nothing for an edit to be relative to.
 //
-// **A child in another repository is not a refusal** (joshuafolkken/kit#3161). The declaration names
+// **A child in another repository is not a refusal**. The declaration names
 // bare numbers only, so neither command can write an order across repositories — such an order lives
 // in the native relations alone (`epic_graph.child_links`), which these edits never read or drop — and
 // the rewrite leaves a row it does not recognize exactly where it stood.

package/scripts/epic/epic-solo-stale.ts

@@ -1,12 +1,13 @@
 import { setTimeout as sleep } from 'node:timers/promises'
 import type { OpenIssueData } from '#scripts/git/git-schemas'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_any_label, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { lane_await } from '#scripts/lane/lane-await'
 import { lane_registry } from '#scripts/lane/lane-registry'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import type { BusyRead } from './epic-busy'
 
-// A `run:solo` holder nothing is running for (joshuafolkken/kit#3017).
+// A `run:solo` holder nothing is running for.
 //
 // A running `run:solo` issue lets nothing new start (`epic-solo.ts`), and "running" is read off the
 // `in-progress` label alone. A label nothing removed — a child that parked itself, then had its
@@ -77,7 +78,7 @@ async function find_stale(
 }
 
 function stale_message(stale: ReadonlyArray<OpenIssueData>, repo: string): string {
-	const named = stale.map((issue) => `#${String(issue.number)}`).join(', ')
+	const named = stale.map((issue) => issue_cite.plain(issue.number)).join(', ')
 
 	return issue_citation.linkify(
 		`${named} carries \`${RUN_SOLO_LABEL}\` and \`${IN_PROGRESS_LABEL}\`, but no process of it is running in ${repo} — the \`${IN_PROGRESS_LABEL}\` label is stale, so it does not hold the backlog. Remove the label once you have confirmed nothing is running it.`,

package/scripts/epic/epic-solo.ts

@@ -1,10 +1,11 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_busy, type BusyRead } from './epic-busy'
 import type { EpicChild } from './epic-graph'
 import { epic_report, type EpicNextResult } from './epic-report'
 
-// The `run:solo` gate on what a run is offered (joshuafolkken/kit#2776).
+// The `run:solo` gate on what a run is offered.
 //
 // `backlogrun-lanes.md`'s run-alone rule says an issue whose defect reaches the verification path runs
 // alone, and until this gate that was a judgement made at dispatch — the offer handed such an issue
@@ -16,16 +17,15 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // disagree about what may start beside what.
 //
 // Three rules, all against the repository's `in-progress` holders (`epic_busy.read_repository`, with
-// a stale `run:solo` holder taken out by `epic_solo_stale.release` — joshuafolkken/kit#3017):
+// a stale `run:solo` holder taken out by `epic_solo_stale.release`):
 // a running `run:solo` issue lets nothing new start; a `run:solo` candidate starts only into an idle
 // repository and then alone; and nothing ranked below a waiting `run:solo` candidate is offered past
 // it, so it is not starved by the lanes it is waiting on. A listing that could not be read is not an
 // idle repository — the same fail-safe answer `epic_busy` gives.
 //
-// **The label does not move a candidate up the ranking** (joshuafolkken/kit#2928, reversing
-// joshuafolkken/kit#2778). `run:solo` means "runs alone", and tidying that merely touches the
-// verification path carries it as well as a defect that breaks it. Which of them goes first is the
-// ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
+// **The label does not move a candidate up the ranking**. `run:solo` means "runs alone", and tidying
+// that merely touches the verification path carries it as well as a defect that breaks it. Which of
+// them goes first is the ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
 // repository takes the candidates in rank order like any other.
 
 const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
@@ -55,14 +55,14 @@ function solo_holder(read: BusyRead): number | undefined {
 
 function held_message(holder: number, repo: string): string {
 	return issue_citation.linkify(
-		`#${String(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		`${issue_cite.plain(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
 		repo,
 	)
 }
 
 function waiting_message(solo: number, repo: string): string {
 	return issue_citation.linkify(
-		`#${String(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		`${issue_cite.plain(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
 		repo,
 	)
 }

package/scripts/epic/epic-triage.ts

@@ -1,10 +1,11 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import type { EpicChild } from './epic-graph'
 
-// The triage gate on what a run is offered (joshuafolkken/kit#2779).
+// The triage gate on what a run is offered.
 //
-// `run:solo` (joshuafolkken/kit#2776) records that an issue runs alone, but its absence said nothing:
+// `run:solo` records that an issue runs alone, but its absence said nothing:
 // "judged safe beside others" and "never judged" looked the same, and an issue opted in mid-run reached
 // `backlog:drive` without any agent reading it. `run:lane` records the other answer, so an issue with
 // neither label is one nobody has judged — and such an issue may be one that must run alone.
@@ -21,7 +22,7 @@ type TriageVerdict = 'triage'
 const TRIAGE_VERDICT: TriageVerdict = 'triage'
 
 // Read off a bare label list too, so `josh issue:file` refuses an untriaged `auto-ok` filing by the
-// same answer the offer paths withhold it by (joshuafolkken/kit#3313).
+// same answer the offer paths withhold it by.
 function has_triage_label(labels: ReadonlyArray<string>): boolean {
 	return has_label_name(labels, RUN_SOLO_LABEL) || has_label_name(labels, RUN_LANE_LABEL)
 }
@@ -37,7 +38,7 @@ function untriaged(children: ReadonlyArray<EpicChild>): ReadonlyArray<EpicChild>
 
 // Names every untriaged number, so the parent reading standard error knows which issues to judge.
 function message(children: ReadonlyArray<EpicChild>, repo: string): string {
-	const numbers = children.map((child) => `#${String(child.number)}`).join(', ')
+	const numbers = children.map((child) => issue_cite.plain(child.number)).join(', ')
 
 	return issue_citation.linkify(
 		`Untriaged: ${numbers} carry neither \`${RUN_SOLO_LABEL}\` nor \`${RUN_LANE_LABEL}\` in ${repo}, so nothing is offered until each is judged. Read each one, record its blocked-by order and one of the two labels with a comment saying why, then ask again.`,

package/scripts/epic/epic-validate.ts

@@ -1,6 +1,7 @@
 import { epic_subject_schema } from '#scripts/git/git-schemas'
-import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { EPIC_LABEL, has_label_name } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 import { epic_parse, type DeclarationState } from './epic-parse'
 
 // The four requirements an epic has to satisfy are otherwise enforced only by an agent reading the
@@ -15,7 +16,7 @@ interface EpicSubject {
 	// The epic's own state, as GitHub returned it (`OPEN` / `CLOSED`, casing unnormalized). Only
 	// `epic-add.ts` reads it — to refuse adding a child to a closed epic — so it is optional: a read
 	// that came back without the field leaves it undefined, which the refusal treats as "not confirmed
-	// closed" rather than blocking (joshuafolkken/kit#2337).
+	// closed" rather than blocking.
 	state?: string | undefined
 	labels: ReadonlyArray<string>
 	body: string | undefined
@@ -29,11 +30,11 @@ interface CheckResult {
 
 // The `number,labels,body` read's answer, as the shape every epic writer reads. It lives beside
 // the checks because `EpicSubject` is defined here, and each command that wanted one had otherwise
-// to restate the unwrapping (joshuafolkken/kit#890).
+// to restate the unwrapping.
 function parse_epic_subject(raw_json: string | undefined): EpicSubject | undefined {
 	if (raw_json === undefined) return undefined
 
-	const parsed = parse_json_object_safe(raw_json, epic_subject_schema)
+	const parsed = parse_json_object_or_undefined(raw_json, epic_subject_schema)
 	if (parsed === undefined) return undefined
 
 	return {
@@ -61,7 +62,7 @@ function check_label(subject: EpicSubject): CheckResult {
 }
 
 function format_children(children: ReadonlyArray<number>): string {
-	return children.map((child) => `#${String(child)}`).join(', ')
+	return children.map((child) => session_cite.issue(child)).join(', ')
 }
 
 function check_task_list(subject: EpicSubject): CheckResult {
@@ -138,8 +139,8 @@ function format_check_line(result: CheckResult): string {
 function format_check_report(epic_number: number, results: ReadonlyArray<CheckResult>): string {
 	const lines = results.map((result) => format_check_line(result))
 	const summary = is_epic_valid(results)
-		? `✅ Epic #${String(epic_number)} satisfies every requirement.`
-		: `❌ Epic #${String(epic_number)} does not satisfy every requirement.`
+		? `✅ Epic ${session_cite.issue(epic_number)} satisfies every requirement.`
+		: `❌ Epic ${session_cite.issue(epic_number)} does not satisfy every requirement.`
 
 	return [...lines, '', summary].join('\n')
 }

package/scripts/epic/epic.ts

@@ -64,7 +64,7 @@ function to_add_input(parsed: AddArguments): AddChildrenInput {
 
 // A qualified target — `owner/repo#N`. Naming this repository it is the same insertion written
 // longer, so it is performed; naming another it is refused with the command to run there, because
-// this command reads and writes only the repository it runs from (joshuafolkken/kit#985).
+// this command reads and writes only the repository it runs from.
 async function run_qualified_addition(found: CrossRepoAddTarget): Promise<number> {
 	const local = epic_cli.resolve_local_add(found, await git_gh_command.repo_get_name_with_owner())
 
@@ -78,7 +78,7 @@ async function run_qualified_addition(found: CrossRepoAddTarget): Promise<number
 // Why an insertion could not be read. A qualified target is answered on its own terms; an unusable
 // `--decision-file` path is named, because the generic line below would send the person after the epic
 // number and the positioning flag when what went missing is the record path a shell expanded to
-// nothing (joshuafolkken/kit#1350); anything else gets the requirements and the usage line.
+// nothing; anything else gets the requirements and the usage line.
 async function refuse_addition(argv: ReadonlyArray<string>): Promise<number> {
 	const qualified = epic_cli.find_cross_repo_add_target(argv)
 
@@ -104,7 +104,7 @@ async function refuse_addition(argv: ReadonlyArray<string>): Promise<number> {
 //
 // `--decision-file` is the one text an insertion does carry, and it is a *decision* rather than the
 // epic's rationale: it says why this child was placed here, and it goes to the epic's `## Decisions`
-// and to each child (joshuafolkken/kit#1350).
+// and to each child.
 async function run_addition(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = epic_cli.parse_add_arguments(argv)
 
@@ -115,7 +115,7 @@ async function run_addition(argv: ReadonlyArray<string>): Promise<number> {
 
 // Deleting a declared order. No position and no `--ordered`: the path itself says which orders go,
 // and what is deleted is only ever what it names — the ends are never reconnected, since a removal
-// that wrote an order would be declaring one nobody stated (joshuafolkken/kit#1712).
+// that wrote an order would be declaring one nobody stated.
 async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = epic_cli.parse_remove_arguments(argv)
 
@@ -135,7 +135,7 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 }
 
 // Reconcile an epic's declaration with its recorded relations. No decision file and no children: the
-// repair reads what the epic already records rather than being told an order (joshuafolkken/kit#2235).
+// repair reads what the epic already records rather than being told an order.
 async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = epic_cli.parse_reconcile_arguments(argv)
 

package/scripts/exports/unused-members-cli.ts

@@ -10,7 +10,7 @@ const FAIL_EXIT_CODE = 1
 // A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
 // `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
 //
-// **Not a skip notice** (joshuafolkken/kit#3162). `SKIP_MARKER` means "a check passed without running",
+// **Not a skip notice**. `SKIP_MARKER` means "a check passed without running",
 // and the gate withholds its green record on it — so a consumer, where this notice prints on every
 // run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
 const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — nothing to check in a consumer project.`

package/scripts/followup/followup-issue-number.ts

@@ -5,8 +5,7 @@
 // and the run's tail cannot disagree about what "the completed issue" is.
 //
 // It sits in a module of its own because both consumers need it and neither may import the other:
-// the tail reads it to record a run, and the entry point reads it to build one
-// (joshuafolkken/kit#1539).
+// the tail reads it to record a run, and the entry point reads it to build one.
 function parse_issue_number_from_text(input: string | undefined): string | undefined {
 	if (input === undefined) return undefined
 	const trimmed = input.trim()

package/scripts/followup/git-followup-cleanup.ts

@@ -1,15 +1,14 @@
 import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
 
-// joshuafolkken/kit#1539: everything a run does after its merge is cleanup, and a merge cannot be
-// taken back. Those steps used to be plain sequential statements, so whichever of them threw first
-// discarded every one after it — and the working-tree hold release is the last of them. Three runs
-// (joshuafolkken/kit#1197, #1537, #1319) ended that way: merged, the issue closed, and the hold left
-// behind for the next run to trip over.
+// Everything a run does after its merge is cleanup, and a merge cannot be taken back. As plain
+// sequential statements, whichever step threw first would discard every one after it — and the
+// working-tree hold release is the last of them, so the hold would be left behind for the next run
+// to trip over.
 //
 // **A step is run on its own, and its failure never reaches the next one.** The whole point is that
 // the steps are independent: the completion comment has nothing to do with the hold release, and
-// letting one decide the other is wrong whatever made it fail — this Issue's own defect, a Telegram
-// rate limit, or a Bad Gateway from GitHub.
+// letting one decide the other is wrong whatever made it fail — a Telegram rate limit, or a Bad
+// Gateway from GitHub.
 //
 // **Reported, never swallowed.** A cleanup that failed invisibly is a run that lies about what it
 // did, so the failure is printed where the run is being watched, with the command that finishes the

package/scripts/followup/git-followup-finish.ts

@@ -7,9 +7,9 @@ import { parse_completed_issue_number } from './followup-issue-number'
 import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
 import { git_followup_pending } from './git-followup-pending'
 
-// **The count of unreleased merges, not the project version** (joshuafolkken/kit#1486). This line
-// used to read the local `package.json` and was read as "the version this run just shipped"; children
-// no longer bump, so that number names the *previous* release and the reading is false. The count is
+// **The count of unreleased merges, not the project version**. The local `package.json` version
+// reads as "the version this run just shipped", but children do not bump, so that number names the
+// *previous* release and the reading is false. The count is
 // the one `pnpm josh release` acts on, and it is printed here for the same reason it goes into the
 // Telegram: a number that keeps climbing is a release nobody has run.
 //
@@ -45,8 +45,8 @@ async function print_completion(
 	await print_pending_release()
 }
 
-// A **merged** run ends here, and the round-1 review snapshot's lifetime is one run
-// (joshuafolkken/kit#1441). `--no-merge` is not the end of one — the pull request is still open and
+// A **merged** run ends here, and the round-1 review snapshot's lifetime is one run.
+// `--no-merge` is not the end of one — the pull request is still open and
 // the issue is still the current task, the same line `print_next_issues` and the epic auto-close
 // already draw — and clearing there would be the unsafe direction: the next round-1 brief would find
 // no record and write a fresh one against the already-fixed tree, which is the arm-A skip over
@@ -74,8 +74,7 @@ async function clear_review_records(should_merge: boolean): Promise<void> {
 	await clear_review_target(should_merge)
 }
 
-// joshuafolkken/kit#1091: the working-tree hold a typed entry point claims before it starts is
-// released here, on the one seam every `fullrun` — and every child of an `epicrun` or a `queue` —
+// The working-tree hold a typed entry point claims before it starts is released here, on the one seam every `fullrun` — and every child of an `epicrun` or a `queue` —
 // passes through, so a finished run never leaves the next one locked out. **Gated on `should_merge`
 // like the epic auto-close and the round-1 snapshot clear**: a `--no-merge` run has not finished, and
 // its tree is still the one nobody else may start in.
@@ -95,7 +94,7 @@ async function release_worktree_hold(should_merge: boolean): Promise<void> {
 	}
 }
 
-// joshuafolkken/kit#1821: a `run:progress` watcher outlives the turn that started it and, left alone,
+// A `run:progress` watcher outlives the turn that started it and, left alone,
 // waits out its whole bound — up to an hour — after the run it was watching has already merged.
 // Removing its liveness record here, on the same merge seam that releases the working-tree hold, lets
 // the watcher read the record gone on its next tick and stop at once. **Keyed like the hold, on the
@@ -127,10 +126,9 @@ async function end_progress_watcher(should_merge: boolean): Promise<void> {
 	}
 }
 
-// **The steps are independent, and one of them failing must not discard the rest**
-// (joshuafolkken/kit#1539). They used to be bare statements, so whichever threw first ended the
-// process — and the hold release is the last of them, which is how three merged runs left their
-// working tree locked. The order is still the contract: `print_completion` ends with the
+// **The steps are independent, and one of them failing must not discard the rest**.
+// As bare statements, whichever threw first would end the process — and the hold release is the
+// last of them, so a merged run would leave its working tree locked. The order is still the contract: `print_completion` ends with the
 // unreleased-merge count, the final console line.
 function build_report_steps(
 	issue_number: string | undefined,
@@ -160,7 +158,7 @@ function build_record_steps(should_merge: boolean): ReadonlyArray<CleanupStep> {
 		{
 			label: 'The working-tree hold release',
 			// **The forced spelling, because the run that wrote the record is this one and it is
-			// ending** (joshuafolkken/kit#1799). A release names the run it belongs to, so a person
+			// ending**. A release names the run it belongs to, so a person
 			// finishing this step by hand is releasing a record they did not write — the plain form
 			// would answer `held` and remove nothing, which is a printed recovery that cannot recover.
 			recovery: 'pnpm josh run:release --force',

package/scripts/followup/git-followup-flush.ts

@@ -1,15 +1,19 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_spawn } from '#scripts/git/git-spawn'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
 import { observation_ledger_prepare } from '#scripts/observations/observation-ledger-prepare'
 import { observations_flush } from '#scripts/observations/observations-flush'
 
-// The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
-// ride its own commit (joshuafolkken/kit#2763), so the ledger is usually clean by now and this
-// short-circuits; what it still catches is a line appended after that commit — a second review round's
-// record — which would otherwise stay in the working tree after the merge.
+// The residual commit path for the observation ledger. A run's appended lines
+// ride its own commit, so the ledger is usually clean by now and this
+// short-circuits; what it still catches is a line appended after that commit — an observation
+// recorded between the commit and the merge — which would otherwise stay in the working tree after
+// the merge. **A passing second review round is not one of them**: it used to
+// be the usual case, and its push restarted the pull request's CI on six lanes of fourteen in a day,
+// so `review:record --comment` now records that round on the issue and leaves the tree clean.
 //
-// **It commits onto the pull request's own branch, before the merge** (joshuafolkken/kit#2919). It used
+// **It commits onto the pull request's own branch, before the merge**. It used
 // to flush after the merge from the default branch, which a lane cannot reach, so a lane's lines
 // waited in the primary checkout for a batch-end flush and were lost there to another run's stash.
 // Committed to the branch instead, the lines merge with the pull request — in a lane as anywhere — and
@@ -20,10 +24,10 @@ const COMMIT_MESSAGE_PREFIX = 'Record observation ledger entries'
 function commit_message(issue_number: string | undefined): string {
 	return issue_number === undefined
 		? COMMIT_MESSAGE_PREFIX
-		: `${COMMIT_MESSAGE_PREFIX} #${issue_number}`
+		: `${COMMIT_MESSAGE_PREFIX} ${issue_cite.plain(issue_number)}`
 }
 
-// **A broken line refuses the merge rather than riding it** (joshuafolkken/kit#2123): the branch's
+// **A broken line refuses the merge rather than riding it**: the branch's
 // ledger file goes away with the lane, so a line left behind here is a line lost.
 async function assert_grammar(): Promise<void> {
 	const broken = await observation_ledger_prepare.prepare(await git_command.repository_root())