@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/issue/issue-labels.ts

@@ -7,41 +7,41 @@ const ENHANCEMENT_LABEL = 'enhancement'
 const BREAKING_CHANGE_LABEL = 'breaking-change'
 const IN_PROGRESS_LABEL = 'in-progress'
 // Applied by `kickoff` once its plan is on the issue, so the next command's `run:entry` reads the issue
-// as planned and starts at the implementation rather than planning again (joshuafolkken/kit#3042).
+// as planned and starts at the implementation rather than planning again.
 // Namespaced like `run:solo`: a bare `planned` is a common roadmap label a person may already apply,
 // and reading one as kickoff's mark would skip the planning that never happened.
 const PLANNED_LABEL = 'run:planned'
 // Parks a child that cannot advance without a person deciding something. `epic:next` is what reads
 // it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
-// forever (joshuafolkken/kit#860).
+// forever.
 const NEEDS_DECISION_LABEL = 'needs-decision'
-// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it
-// (joshuafolkken/kit#2776). A run applies it from the verification-path enumeration in `backlogrun-lanes.md`;
+// Marks an issue whose defect reaches the verification path, so it runs with nothing beside it.
+// A run applies it from the verification-path enumeration in `backlogrun-lanes.md`;
 // `backlog:next` enforces it (`backlog-solo.ts`), so the rule no longer rests on a judgement at
 // dispatch time.
 const RUN_SOLO_LABEL = 'run:solo'
-// The other half of the same judgement: an issue a run read and found safe to run beside others
-// (joshuafolkken/kit#2779). Without it an issue lacking `run:solo` could mean "judged parallel" or
+// The other half of the same judgement: an issue a run read and found safe to run beside others.
+// Without it an issue lacking `run:solo` could mean "judged parallel" or
 // "never judged", and `backlog:next` withholds the second (`epic-triage.ts`).
 const RUN_LANE_LABEL = 'run:lane'
-// Puts an issue at the head of the backlog's ranking (joshuafolkken/kit#2928). A person or a run may
+// Puts an issue at the head of the backlog's ranking. A person or a run may
 // apply it — a run only where it can cite a deadline or a stated urgency, or a policy a person wrote
 // (`backlogrun-steps.md`) — and **only a person removes it**: a run that could clear it could undo
 // the person's ordering. Read by `issue-rank.ts`, the one place the ranking keys are decided.
 const PRIORITY_HIGH_LABEL = 'priority:high'
-// Opts one issue outside any epic into unattended execution (joshuafolkken/kit#906). **Only a
+// Opts one issue outside any epic into unattended execution. **Only a
 // person applies it.** `epicrun #<E>` approves the merges inside `#<E>`; this label is the only way
 // a person extends that approval past the epic's edge, so a label an AI could apply to itself would
 // let an unattended run widen its own authorization — which is not a guard at all.
 const AUTO_OK_LABEL = 'auto-ok'
 // Degrades one issue's run to a `halfrun`-shaped stop: it is implemented and taken through the
-// verification gate, and then nothing is committed, pushed, opened as a pull request or merged
-// (joshuafolkken/kit#1125). **Only a person applies it** — a mark a run could clear for itself is not
+// verification gate, and then nothing is committed, pushed, opened as a pull request or merged.
+// **Only a person applies it** — a mark a run could clear for itself is not
 // a mark.
 //
 // It is the opposite of `auto-ok` in what it does: one widens unattended execution past an epic's
 // edge, the other withholds the last step of it. Unlike `auto-ok`, which `issue:file` applies by
-// default to work found by opted-in work (joshuafolkken/kit#3213), no run ever applies it. `auto-ok`
+// default to work found by opted-in work, no run ever applies it. `auto-ok`
 // answers "may this run at all", this one answers "may its result ship without a person looking".
 //
 // **Not `needs-decision`, and the difference is what the two sets below encode.** A parked issue is
@@ -51,10 +51,9 @@ const AUTO_OK_LABEL = 'auto-ok'
 // checkout and must go on holding the repository. Read as parked in either place, the next child
 // would start on top of that work.
 const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
-// Marks an issue whose work a run verified is **already merged** (joshuafolkken/kit#1679). Closing
-// an Issue is Tier C, so a run that reaches that conclusion may not act on it — and before this
-// label there was no exit that was not Tier C: `fullrun #1656` verified the work was already in
-// `main` from joshuafolkken/kit#1623 and closed the Issue itself.
+// Marks an issue whose work a run verified is **already merged**. Closing
+// an Issue is Tier C, so a run that reaches that conclusion may not act on it — this label is its
+// exit that is not Tier C.
 //
 // **It is not `needs-decision`, and the difference is the whole reason it exists.** A parked issue
 // waits for an answer nobody has given; this one has its answer already — the work is done, and all
@@ -65,7 +64,7 @@ const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
 // takes it off, because taking it off asserts the work is *not* done, which is the same claim in
 // reverse and is no more a run's to make.
 const ALREADY_DONE_LABEL = 'already-done'
-// Marks the Issue that tracks a repository's next release (joshuafolkken/kit#3360). An Issue whose
+// Marks the Issue that tracks a repository's next release. An Issue whose
 // change reaches a consumer only once published is linked to it as a `blocked_by` blocker
 // (`josh issue:release`), so "merged but not yet released" is visible in the backlog. A run applies
 // it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
@@ -90,20 +89,19 @@ const NOT_DIRECTLY_RUNNABLE_LABELS: ReadonlySet<string> = new Set([
 	ALREADY_DONE_LABEL,
 ])
 
-// joshuafolkken/kit#1083: filing-route labels, applied at filing time so the backlog's composition —
-// a review-cap carry-forward vs a split child vs a Tier A in-implementation filing — is countable
-// with `gh api "repos/{owner}/{repo}/issues?labels=<route>"` instead of grepping issue bodies by
-// hand, which is how the 2026-08-30 breakdown was produced and why it did not reproduce. Purely
+// Filing-route labels, applied at filing time so the backlog's composition — a review-cap
+// carry-forward vs a split child vs a Tier A in-implementation filing — is countable with
+// `gh api "repos/{owner}/{repo}/issues?labels=<route>"` instead of grepping issue bodies by hand,
+// which does not reproduce. Purely
 // informational: unlike the three above, a route label says nothing about whether an issue may run,
 // so none of them joins NOT_DIRECTLY_RUNNABLE_LABELS. The names are duplicated as literals in the
 // filing procedures (prose cannot import this module); `scripts/rules/filing-route-label.test.ts` keys the
 // docs to these constants so a filing command that drops the label fails rather than drifting.
 //
-// joshuafolkken/kit#1518 added a fourth: an interrupt is a defect found in *this* repository that
-// does not block the run that found it, and which the WIP cap would otherwise push into the
-// discretionary exit — the route joshuafolkken/kit#1517 took, surviving only as a comment on another
-// issue. It is not `route:tier-a`: that one is a filing the run is blocked by (an upstream defect or
-// a prerequisite), and reading the two as one is what lost #1517.
+// `route:interrupt` is a defect found in *this* repository that does not block the run that found
+// it, and which the WIP cap would otherwise push into the discretionary exit, surviving only as a
+// comment on another issue. It is not `route:tier-a`: that one is a filing the run is blocked by (an
+// upstream defect or a prerequisite), and reading the two as one loses the interrupt.
 const INTERRUPT_ROUTE_LABEL = 'route:interrupt'
 const REVIEW_CAP_ROUTE_LABEL = 'route:review-cap'
 const SPLIT_ROUTE_LABEL = 'route:split'
@@ -145,7 +143,7 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 	},
 ]
 
-// joshuafolkken/kit#1729: the depth of an issue's subject, recorded as a label at filing time.
+// The depth of an issue's subject, recorded as a label at filing time.
 //
 // **The definition is not here.** `.claude/skills/workflow-commands/observation-filing.md` → "The depth test",
 // is the single source: depth 0 is what a consumer of this package touches, depth 1 the run
@@ -154,10 +152,9 @@ const FILING_ROUTE_LABELS: ReadonlyArray<{
 // would be the clone `CLAUDE.md` prohibits, and the descriptions below therefore name the section
 // rather than paraphrase it.
 //
-// **Why a label at all.** joshuafolkken/kit#1698 set a measurable target — the share of open issues
-// at depth 0 — and left nothing that records a depth, so the share could only be obtained by reading
-// every open issue's body by hand. Two hand counts a day apart disagreed on the denominator and were
-// therefore not comparable, which is the failure a recorded label removes.
+// **Why a label at all.** The share of open issues at depth 0 is a measured target, and without a
+// recorded depth it could only be obtained by reading every open issue's body by hand — hand counts
+// disagree on the denominator and are not comparable, which is the failure a recorded label removes.
 //
 // **The depth is read off the subject, so a run applies it.** Unlike `auto-ok` and
 // `needs-human-review` this is not a person's judgement about authorization; it is the same reading
@@ -169,8 +166,7 @@ const DEPTH_2_LABEL = 'depth:2'
 
 // Ordered shallowest first, which is what makes `depth_label_of` deterministic: an issue carrying
 // more than one depth label counts as the **lowest** depth present, the one closest to the consumer.
-// Without a fixed tie-break the same listing measured twice could answer differently, which is the
-// whole defect joshuafolkken/kit#1729 was filed for.
+// Without a fixed tie-break the same listing measured twice could answer differently.
 const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL, DEPTH_2_LABEL]
 
 // The metadata `gh api ... labels` needs, in the shape `FILING_ROUTE_LABELS` above uses and for the
@@ -179,7 +175,7 @@ const DEPTH_LABEL_ORDER: ReadonlyArray<string> = [DEPTH_0_LABEL, DEPTH_1_LABEL,
 // Green, amber and pale blue, so the consumer-facing depth is the one that stands out in a listing.
 //
 // **`josh issue:file` provisions them** through `repository_labels.ensure_labels` before its create
-// call (joshuafolkken/kit#3176), so no document carries a creation command to keep in step.
+// call, so no document carries a creation command to keep in step.
 const DEPTH_LABELS: ReadonlyArray<{
 	name: string
 	color: string
@@ -209,7 +205,7 @@ interface LabelDefinition {
 }
 
 // What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
-// applies with its intended color (joshuafolkken/kit#2197). The `epic` and `in-progress` metadata is
+// applies with its intended color. The `epic` and `in-progress` metadata is
 // the one the workflow documents create them with; the labels only a person applies are left out.
 const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	{
@@ -243,8 +239,8 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 	...DEPTH_LABELS,
 ]
 
-// The pull request release classifications `pr-classification.yml` requires exactly one of
-// (joshuafolkken/kit#2797). The check is distributed by `josh sync`, so the labels it asks for are
+// The pull request release classifications `pr-classification.yml` requires exactly one of.
+// The check is distributed by `josh sync`, so the labels it asks for are
 // provisioned from this same list — a repository that never had them would otherwise fail the check
 // on every pull request that is not an `enhancement`.
 const BUGFIX_LABEL = 'bugfix'
@@ -300,7 +296,7 @@ function has_any_label(
 // A membership test answers whether the label is there; a *removal* has to name it, and
 // `DELETE …/issues/<N>/labels/<name>` names it in the path. Lowercasing the wanted name and sending
 // that would be a second comparison — GitHub's, on a spelling we did not read — so the removal reads
-// the stored one and sends it back (joshuafolkken/kit#1794).
+// the stored one and sends it back.
 function label_name_of(labels: ReadonlyArray<string>, wanted: string): string | undefined {
 	const target = wanted.toLowerCase()
 
@@ -329,7 +325,7 @@ function depth_label_of(labels: ReadonlyArray<LabelReference> | undefined): stri
 }
 
 // Every workflow label this package manages. The label-reference scan
-// (`scripts/document/label-reference.test.ts`, joshuafolkken/kit#1923) reads this to check that no
+// (`scripts/document/label-reference.test.ts`) reads this to check that no
 // document operates on a label name that does not exist here — a stale or mistyped `labels[]=…`
 // otherwise fails silently at run time. One source, so a label added above joins the scan without a
 // second edit.

package/scripts/issue/issue-lint-cli.ts

@@ -6,10 +6,10 @@ import { issue_classification } from './issue-classification'
 import { issue_lint } from './issue-lint'
 
 // `josh issue:lint <path>` — read an Issue body from a file and print `ok`, or every template problem
-// one per line, exiting non-zero (joshuafolkken/kit#2123). It reads a path rather than stdin so it can
+// one per line, exiting non-zero. It reads a path rather than stdin so it can
 // lint a body written to a file before the `gh api … issues` call that files it. A body that declares
 // itself a behavior-change Issue is additionally held to the firing-point, baseline and reproduction
-// rules (joshuafolkken/kit#2212, joshuafolkken/kit#2353).
+// rules.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1

package/scripts/issue/issue-lint.ts

@@ -2,7 +2,7 @@ import { markdown_section } from './markdown-section'
 
 // The Issue body template's four headings (`prompts/collaboration-workflow/issue-template.md`) are a
 // fixed shape, but unlike an epic — which `josh epic:check` verifies — nothing checks that a filed
-// Issue carries them. This reports the ones a body is missing (joshuafolkken/kit#2123). The headings
+// Issue carries them. This reports the ones a body is missing. The headings
 // are the single source's, and the document test pins that these match it.
 const REQUIRED_HEADINGS: ReadonlyArray<string> = [
 	'## 背景',

package/scripts/issue/issue-merged.ts

@@ -1,7 +1,7 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 
-// Whether an issue was closed by a merge, read from its REST timeline (joshuafolkken/kit#2701). The
+// Whether an issue was closed by a merge, read from its REST timeline. The
 // issue's own `state_reason` cannot tell: a pull request's `closes #N` and a person's "Close as
 // completed" both answer `completed`. What only a merge leaves is a merged pull request referencing
 // the issue, so the answer is the conjunction — closed now, as completed, and referenced by a merged
@@ -55,7 +55,9 @@ function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
 	return rows.some((row) => row.event === MERGED_REFERENCE)
 }
 
-async function read_merged(issue: string): Promise<boolean> {
+// `undefined` when the timeline could not be read, so a caller that keeps the answer can tell "not
+// merged" from "ask again".
+async function read_merge_state(issue: string): Promise<boolean | undefined> {
 	try {
 		const raw = await git_gh_exec.exec_gh_api({
 			path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
@@ -65,11 +67,15 @@ async function read_merged(issue: string): Promise<boolean> {
 
 		return is_merged_close(parse_rows(raw))
 	} catch {
-		return false
+		return undefined
 	}
 }
 
-const issue_merged = { is_merged_close, parse_rows, read_merged }
+async function read_merged(issue: string): Promise<boolean> {
+	return (await read_merge_state(issue)) ?? false
+}
+
+const issue_merged = { is_merged_close, parse_rows, read_merge_state, read_merged }
 
 export type { TimelineRow }
 export { issue_merged }

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

@@ -0,0 +1,27 @@
+// The shape an issue number may take, and the refusal when it does not — the one declaration every
+// command reads.
+//
+// It sits in its own module because a rule copied into two files is a rule kept correct in one: a
+// copy that read `/^\d+$/u` accepted issue `0` and a leading zero where every other command refused
+// them. A command that interpolates the number into a shell command a caller is told to paste, a
+// GitHub path, a branch or a lane directory refuses before the interpolation rather than leaving the
+// check to whichever entry point remembered.
+//
+// `ISSUE_NUMBER_PATTERN` stays exported beside `is_issue_number`: a taint analyzer credits a literal
+// pattern test in the expression that returns the value as a sanitizer, but not one reached through a
+// call (`run-merge-cli.ts`).
+
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const BAD_ISSUE_MESSAGE = 'Not an issue number: '
+
+function is_issue_number(value: string): boolean {
+	return ISSUE_NUMBER_PATTERN.test(value)
+}
+
+function require_issue_number(issue: string): void {
+	if (!is_issue_number(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`)
+}
+
+const issue_number_shape = { ISSUE_NUMBER_PATTERN, is_issue_number, require_issue_number }
+
+export { issue_number_shape }

package/scripts/issue/issue-rank.ts

@@ -6,7 +6,7 @@ import {
 	RUN_SOLO_LABEL,
 } from './issue-labels'
 
-// The keys that decide which open issue is offered first (joshuafolkken/kit#2928), defined once for
+// The keys that decide which open issue is offered first, defined once for
 // every ranking that asks: the `🗒 Next issues` display, the `auto-ok` pickup and `backlog:next`.
 //
 // In order: `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or

package/scripts/issue/issue-read-cli.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { issue_read, type IssueComment, type IssueFields } from './issue-read'
 import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
 
-// `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call
-// (joshuafolkken/kit#1715).
+// `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call.
 //
 // It replaces the two `gh api` reads `.claude/skills/workflow-commands/issue-comments.md` tells an agent
 // to type per issue. Measured over four recorded `backlogrun` parents, `issue bookkeeping` was the
@@ -28,7 +28,6 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:read <issue-number> [<issue-number> ...]'
 const BLOCK_SEPARATOR = '\n\n---\n\n'
 // The same bound `issue:state` puts on its batch read, for the same reason: every read is a `gh`
@@ -45,7 +44,7 @@ interface IssueContent {
 type NumberResult = { kind: 'issue'; content: IssueContent } | { kind: ReadFailureKind }
 
 // The formatted block for one issue, or the failure kind — what `run:prep` bundles beside the state
-// and the dependency-update scope (joshuafolkken/kit#1978). It reuses this file's read and the shared
+// and the dependency-update scope. It reuses this file's read and the shared
 // `format_issue` rather than reproducing either, so the two `gh` reads and the block shape stay
 // single-sourced here.
 type BlockRead = { kind: 'ok'; block: string } | { kind: ReadFailureKind }
@@ -59,7 +58,7 @@ interface IssueReport {
 // Dropping it answers fewer numbers than were asked for and still exits zero — and nothing in the
 // output then says a number went unanswered. `#1262` copied out of a table is exactly that token.
 function parse_numbers(argv: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
-	const numbers = argv.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+	const numbers = argv.filter((argument) => issue_number_shape.is_issue_number(argument))
 
 	if (numbers.length === 0 || numbers.length !== argv.length) return undefined
 

package/scripts/issue/issue-read.ts

@@ -1,9 +1,8 @@
-import { parse_json_object_safe, read_json_listing } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined, read_json_listing } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
 // The block `josh issue:read` prints for one issue, kept apart from the reading and the printing so
-// the shape of the report is decided by one pure function — the seam `issue-state.ts` already has
-// (joshuafolkken/kit#1715).
+// the shape of the report is decided by one pure function — the seam `issue-state.ts` already has.
 //
 // **It exists because reading one issue costs a parent two turns.** `.claude/skills/workflow-commands/SKILL.md`
 // `issue-comments.md` requires the body *and* the comments, since a decision recorded after the body was written
@@ -11,7 +10,7 @@ import { z } from 'zod'
 // `gh api repos/{owner}/{repo}/issues/<N>/comments`. Measured over four recorded `backlogrun`
 // parents, `issue bookkeeping` was the single largest contributor to the parent's turn count — 110 of
 // 414 turns, 26.6% — and one-issue-at-a-time `gh api` reads were its dominant shape. A parent's cost
-// grows as n²/2 in its own request count (joshuafolkken/kit#1567), so those turns are the
+// grows as n²/2 in its own request count, so those turns are the
 // distribution this collapses.
 //
 // **The comments are never silently absent.** A listing that could not be read prints a line saying
@@ -65,7 +64,7 @@ const UNKNOWN_TIME = '(undated)'
 // parse.
 function parse_issue_fields(json: string): IssueFields | undefined {
 	try {
-		const parsed = parse_json_object_safe(json, issue_fields_schema)
+		const parsed = parse_json_object_or_undefined(json, issue_fields_schema)
 
 		if (parsed === undefined) return undefined
 

package/scripts/issue/issue-reference.ts

@@ -1,14 +1,14 @@
 // An issue named from outside any one graph — a task-list row, a citation in prose, a blocker
 // relation, a child that could not be read. Repository **and** number, because a number alone cannot
 // identify one: issue numbers are unique per repository, so the same `#40` names two different issues
-// depending on who wrote it (joshuafolkken/kit#1014).
+// depending on who wrote it.
 //
 // It lives in the git layer because the `blocked-by` relations are read here and carry a repository
-// of their own (joshuafolkken/kit#1126); the epic domain builds on this layer, never the other way
-// round (joshuafolkken/kit#2904). `epic-reference` re-exports it, so every epic importer is unchanged.
+// of their own; the epic domain builds on this layer, never the other way
+// round. `epic-reference` re-exports it, so every epic importer is unchanged.
 //
-// `state` is present only on a reference read from a `blocked-by` relation whose response carried it
-// (joshuafolkken/kit#1943). The classifier needs it for a blocker no named graph tracks, where there is
+// `state` is present only on a reference read from a `blocked-by` relation whose response carried it.
+// The classifier needs it for a blocker no named graph tracks, where there is
 // no child record to read the state from; every other reference leaves it out.
 interface IssueReference {
 	repo: string

package/scripts/issue/issue-release-cli.ts

@@ -5,14 +5,16 @@ import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { RELEASE_LABEL } from './issue-labels'
 import { issue_release } from './issue-release'
+import { session_cite } from './session-cite'
 
 // `josh issue:release <N>` — link Issue `<N>` to its repository's release Issue as a `blocked_by`
-// blocker, filing the release Issue when none is open (joshuafolkken/kit#3360). `josh issue:file
+// blocker, filing the release Issue when none is open. `josh issue:file
 // --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
 // by one body of code.
 //
@@ -22,7 +24,6 @@ import { issue_release } from './issue-release'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:release <issue-number>'
 const NONE = 'none'
 const UNKNOWN_REPO_MESSAGE =
@@ -90,10 +91,17 @@ async function release_of(target: string): Promise<ReleaseIssue | undefined> {
 	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
 }
 
-function linked_line(release: ReleaseIssue, issue_number: number): string {
+function linked_line(release: ReleaseIssue, issue_number: number, target: string): string {
 	const how = release.is_filed ? 'filed' : 'open'
+	const release_cite = session_cite.issue(release.issue_number, undefined, target)
 
-	return `release: #${String(release.issue_number)} (${how}) is blocked by #${String(issue_number)}`
+	return `release: ${release_cite} (${how}) is blocked by ${session_cite.issue(issue_number, undefined, target)}`
+}
+
+function unlinked_line(issue_number: number, blocked: string, target: string): string {
+	const blocker = session_cite.issue(issue_number, undefined, target)
+
+	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(blocked, undefined, target)}`
 }
 
 // Whether Issue `issue_number` of `target` now blocks the release Issue. Every outcome is printed.
@@ -104,8 +112,8 @@ async function link(issue_number: number, target: string): Promise<boolean> {
 	const blocked = String(release.issue_number)
 	const is_linked = await git_gh_issue_write.issue_add_blocked_by(blocked, String(issue_number))
 
-	if (is_linked) console.info(linked_line(release, issue_number))
-	else console.error(`✖ #${String(issue_number)} could not be recorded as a blocker of #${blocked}`)
+	if (is_linked) console.info(linked_line(release, issue_number, target))
+	else console.error(unlinked_line(issue_number, blocked, target))
 
 	return is_linked
 }
@@ -120,7 +128,9 @@ function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
 	const [issue_number, ...rest] = positionals_of(argv)
 	const is_single = rest.length === 0 && issue_number !== undefined
 
-	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? Number(issue_number) : undefined
+	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
+		? Number(issue_number)
+		: undefined
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/issue/issue-release.ts

@@ -1,9 +1,9 @@
 import { DEPTH_0_LABEL, RELEASE_LABEL } from './issue-labels'
 
-// The decisions behind `josh issue:release` (joshuafolkken/kit#3360), kept apart from the command
+// The decisions behind `josh issue:release`, kept apart from the command
 // that reads the network so each is a pure answer a test can pin. An Issue whose change reaches a
-// consumer only once published used to surface the release only at the end of `followup`'s report;
-// it is now linked to the repository's release Issue, which it blocks until it merges.
+// consumer only once published is linked to the repository's release Issue, which it blocks until it
+// merges.
 
 interface ListingRow {
 	number: number

package/scripts/issue/issue-report-failures.ts

@@ -1,6 +1,7 @@
 import { capped_output } from '#scripts/document/capped-print'
+import { session_cite } from './session-cite'
 
-// The failure report `issue:read` and `issue:state` share (joshuafolkken/kit#3046). Both read a batch
+// The failure report `issue:read` and `issue:state` share. Both read a batch
 // of numbers, print a block for each one that answered, and name every one that did not; only the
 // result kind that counts as an answer and what a gap must not be mistaken for differ between them.
 
@@ -25,7 +26,7 @@ interface FailureTerms<K extends string> {
 }
 
 // Under the Bash output cap, or as part files past it — a batch of long threads is the shape that
-// overflowed (joshuafolkken/kit#3143).
+// overflowed.
 function print_blocks(blocks: ReadonlyArray<string>, separator: string, label: string): void {
 	if (blocks.length === 0) return
 
@@ -37,10 +38,12 @@ function print_blocks(blocks: ReadonlyArray<string>, separator: string, label: s
 // caller's next move differs: a gap is retried, an answer is not.
 function report_failure(kind: ReadFailureKind, issue_number: string, misreading: string): void {
 	if (kind === 'missing') {
-		console.error(`✖ issue #${issue_number} does not resolve — check the number and the repository`)
+		console.error(
+			`✖ issue ${session_cite.issue(issue_number)} does not resolve — check the number and the repository`,
+		)
 	} else {
 		console.error(
-			`✖ could not read issue #${issue_number} — a rate limit, expired auth, or a dropped connection. This is not "${misreading}"`,
+			`✖ could not read issue ${session_cite.issue(issue_number)} — a rate limit, expired auth, or a dropped connection. This is not "${misreading}"`,
 		)
 	}
 }

package/scripts/issue/issue-scout-cli.ts

@@ -15,13 +15,14 @@ import {
 	type ScoutIssue,
 } from './issue-scout'
 import { issue_scout_closed, type ClosedScan } from './issue-scout-closed'
+import { session_cite } from './session-cite'
 
 const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_about_closed } =
 	issue_scout_closed
 
 // `josh issue:scout "<title>" [--body "<summary>"]` — before an issue is filed, answer the two
 // questions every `new` entry point asks first: has this already been filed, and which epic does it
-// belong to (joshuafolkken/kit#1252).
+// belong to.
 //
 // Both were assembled by hand every time, differently every time: a measured `fullrun new` spent
 // 7 minutes 32 seconds — 22% of the run — listing epics, reading their children and searching for
@@ -104,13 +105,13 @@ function draft_of(args: ScoutArguments, repo: string): BacklogIssue {
 // below decides from prose references, and a title-only draft has none to give it.
 function format_duplicate(candidate: DuplicateCandidate): string {
 	const score = candidate.is_referenced === true ? 'ref' : candidate.score.toFixed(SCORE_DIGITS)
-	const epic = candidate.epic === undefined ? '' : ` (epic #${String(candidate.epic)})`
+	const epic = candidate.epic === undefined ? '' : ` (epic ${session_cite.issue(candidate.epic)})`
 	// The reader does two different things with the two states, so the row has to say which it is: an
 	// open candidate means somebody is already tracking this, a closed one means it may already be
 	// done — and the second is the exit `issue-comments.md` names, not a second filing.
 	const closed = candidate.is_closed === true ? ' (closed)' : ''
 
-	return `  #${String(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
+	return `  ${session_cite.issue(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
 }
 
 // Weak matches are not padding for an empty answer: a list nobody trusts is read once and skipped
@@ -147,7 +148,7 @@ const NO_EPIC_LINE = 'Epic: none — file it standalone; nothing open shares a r
 function format_epic(decision: BundleDecision): Array<string> {
 	const lines = [`Epic: ${epic_bundle_cli.ACTION_LINES[decision.action] ?? ''}`]
 
-	if (decision.epic !== undefined) lines.push(`  Target epic: #${String(decision.epic)}`)
+	if (decision.epic !== undefined) lines.push(`  Target epic: ${session_cite.issue(decision.epic)}`)
 
 	if (decision.candidates.length > 0) {
 		lines.push(`  Related: ${epic_bundle_cli.format_numbers(decision.candidates)}`)
@@ -168,9 +169,9 @@ const NO_REFERENCE_LINE =
 	'Epic: not asked — no issue number in the summary. Pass --body "…#<N>…", or take the epic printed beside a duplicate above.'
 
 // Every placing verdict above asserts that no epic already tracks the draft's relatives, and a cut
-// epic listing cannot support that: `epic:bundle` withholds them for it (joshuafolkken/kit#1697),
+// epic listing cannot support that: `epic:bundle` withholds them for it,
 // while this command drew the same lines out of `ACTION_LINES` and never passed through the gate that
-// does (joshuafolkken/kit#1703). The verdict is `epic:bundle`'s own, reused rather than restated, with
+// does. The verdict is `epic:bundle`'s own, reused rather than restated, with
 // only the `Epic:` label the rest of this report is read by put in front of it.
 function format_unconfirmed_epic(decision: BundleDecision): string {
 	const related = epic_bundle_cli.format_numbers(decision.candidates)
@@ -245,7 +246,7 @@ function format_epic_answer(
 // The closed rows reach the duplicate half only. `decide_bundle` places a draft among issues that
 // are still being worked on, and a closed one can neither gain a sibling nor be recommended as an
 // epic — so widening the placement pool with them would answer a different question from the one it
-// was asked (joshuafolkken/kit#1679).
+// was asked.
 function duplicates_of(
 	draft: BacklogIssue,
 	issues: ReadonlyArray<BacklogIssue>,
@@ -292,8 +293,7 @@ function qualify_duplicate_report(report_text: string, is_incomplete: boolean):
 }
 
 // The report a run copies into its reply, with every `#N` in the `Related:` / `Target epic:` /
-// duplicate listings linkified so the references it carries are clickable rather than bare
-// (joshuafolkken/kit#2329).
+// duplicate listings linkified so the references it carries are clickable rather than bare.
 function linkified_report(
 	draft: BacklogIssue,
 	widened: Widened,
@@ -315,7 +315,7 @@ function linkified_report(
 }
 
 // The scan's answer in both shapes it is read in: the report a person reads, and the candidate numbers
-// `issue:file` holds a filing to (joshuafolkken/kit#2808).
+// `issue:file` holds a filing to.
 interface ScoutOutcome {
 	report: string
 	candidates: ReadonlyArray<number>
@@ -335,7 +335,7 @@ async function scout(args: ScoutArguments, repo: string): Promise<ScoutOutcome |
 
 	const draft = draft_of(args, repo)
 	// A reference the open listing cannot show — the parent that merged minutes ago — is read directly,
-	// the same widening `epic:bundle` does and for the same reason (joshuafolkken/kit#947). The closed
+	// the same widening `epic:bundle` does and for the same reason. The closed
 	// listing needs nothing from it, so the two requests go out together.
 	const [widened, closed] = await Promise.all([
 		epic_bundle_cli.widen_with_referenced(draft, backlog),

package/scripts/issue/issue-scout-closed.ts

@@ -6,11 +6,11 @@ import { z } from 'zod'
 import { EPIC_LABEL, has_any_label } from './issue-labels'
 import type { ScoutIssue } from './issue-scout'
 
-// The closed half of `issue:scout`'s duplicate scan (joshuafolkken/kit#1679), held apart from the CLI
-// so the command that reports the scan and the one that files after it (`issue:file`,
-// joshuafolkken/kit#2808) read one listing rather than two.
+// The closed half of `issue:scout`'s duplicate scan, held apart from the CLI
+// so the command that reports the scan and the one that files after it (`issue:file`) read one
+// listing rather than two.
 
-// How far back the closed half of the scan reaches (joshuafolkken/kit#1679). One page: the duplicate
+// How far back the closed half of the scan reaches. One page: the duplicate
 // this half exists to catch closed hours ago, not months, and the listing is ordered by update so
 // the newest hundred already covers a run's own day several times over.
 //