@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/init/start-steps.ts

@@ -104,7 +104,7 @@ function add_missing_labels(): void {
 }
 
 // Main already has a history here, so the setup reaches it the way every other change does: through
-// an Issue and a pull request a person merges (joshuafolkken/kit#2816).
+// an Issue and a pull request a person merges.
 async function open_setup_pull_request(context: RunContext): Promise<void> {
 	await start_setup_pr.open(context.root, context.baseline)
 }
@@ -112,7 +112,7 @@ async function open_setup_pull_request(context: RunContext): Promise<void> {
 // What was already changed before the setup ran, read whenever a setup pull request will follow, so
 // it can tell the setup's files from the user's own (#2872). Kit's own `josh init` needs it as much as
 // a caller's command: its `josh format` rewrites the project's own sources, which kit cannot name, and
-// leaving them out failed the pull request's Prettier check (joshuafolkken/kit#3136).
+// leaving them out failed the pull request's Prettier check.
 function baseline_of(
 	steps: ReadonlyArray<StartStep>,
 	context: StepContext,

package/scripts/init/tsconfig-preset-migration.ts

@@ -12,7 +12,7 @@ import { string_array_schema } from '#scripts/lib/schemas'
 // `*.json`; a consumer whose `extends` still points at the old path would never be repaired by the
 // ensure-based merge — an `@joshuafolkken/*` tsconfig entry is already present, so nothing is added
 // — hence the rewrite here. Scoped to `@joshuafolkken/*/tsconfig/*` paths so an unrelated
-// project-local `.jsonc` config is left alone. See joshuafolkken/kit#681.
+// project-local `.jsonc` config is left alone.
 const LEGACY_PRESET_ENTRY = /@joshuafolkken\/[^/]+\/tsconfig\/[^/]+\.jsonc$/u
 const LEGACY_SUFFIX = '.jsonc'
 const CURRENT_SUFFIX = '.json'

package/scripts/init/vscode-tasks.ts

@@ -0,0 +1,62 @@
+import { parse_jsonc } from '#scripts/config-merge/parse-jsonc'
+import { patch_json_array } from '#scripts/config-merge/patch-json-array'
+import { json_object_schema } from '#scripts/lib/schemas'
+import { z } from 'zod'
+import { init_logic_json_merge } from './init-logic-json-merge'
+
+type Task = Record<string, unknown>
+
+const TASKS_KEY = 'tasks'
+const LABEL_KEY = 'label'
+const TASKS_VERSION = '2.0.0'
+const VSCODE_TASKS_FILENAME = 'tasks.json'
+
+// A label kit once shipped a task under, mapped to the label that replaced it. A consumer's task still
+// carrying the retired label is the same kit task under its old name, so it is replaced in place — an
+// append would leave the retired folder-open pane starting beside its successor.
+const RETIRED_LABELS: ReadonlyMap<unknown, string> = new Map([
+	['josh: run event watch', 'josh: run board'],
+])
+
+const task_array_schema = z.array(json_object_schema)
+
+function read_tasks(parsed: Record<string, unknown>): Array<Task> {
+	const result = task_array_schema.safeParse(parsed[TASKS_KEY])
+
+	return result.success ? result.data : []
+}
+
+// A task is identified by its `label` — the name VSCode runs it by and `dependsOn` refers to it by.
+function has_label(element: unknown, label: unknown): boolean {
+	const result = json_object_schema.safeParse(element)
+	if (!result.success) return false
+	const own = result.data[LABEL_KEY]
+
+	return (RETIRED_LABELS.get(own) ?? own) === label
+}
+
+// Kit owns the tasks whose label it ships: each is replaced with kit's current definition in place,
+// a kit task the file lacks is appended, and every other task the consumer declared is kept as
+// authored, comments included — the label-level counterpart of the key-level merge
+// `.vscode/settings.json` gets.
+function merge_tasks(content: string, kit_tasks: ReadonlyArray<Task>): string {
+	let merged = init_logic_json_merge.merge_json_object(content, { version: TASKS_VERSION })
+
+	for (const task of kit_tasks) {
+		merged = patch_json_array.upsert_element(merged, {
+			key: TASKS_KEY,
+			value: task,
+			is_target: (element) => has_label(element, task[LABEL_KEY]),
+		})
+	}
+
+	return merged
+}
+
+function read_kit_tasks(content: string): Array<Task> {
+	return read_tasks(parse_jsonc(content))
+}
+
+const vscode_tasks = { VSCODE_TASKS_FILENAME, merge_tasks, read_kit_tasks }
+
+export { vscode_tasks }

package/scripts/issue/baseline-measure.ts

@@ -1,8 +1,8 @@
 import { markdown_section } from './markdown-section'
 
 // A behavior-change Issue's baseline section is written as `command + value`, never prose, so that
-// `pnpm josh measure:rerun` can re-run the command after merge and print a before/after pair
-// (joshuafolkken/kit#2212). When the value has not moved, the premise the rule rested on is recorded
+// `pnpm josh measure:rerun` can re-run the command after merge and print a before/after pair.
+// When the value has not moved, the premise the rule rested on is recorded
 // as refuted in the observation ledger — reusing that append-only mechanism rather than a second one.
 
 const BASELINE_HEADING = '## ベースライン'

package/scripts/issue/behavior-change-lint.ts

@@ -6,8 +6,8 @@ import { reproduction_measure } from './reproduction-measure'
 // A behavior-change Issue owes three headings the ordinary template does not — a firing-point heading
 // (the tool call the rule breaks on), a baseline heading (a re-runnable measurement) and a
 // reproduction heading (the command and its actual output). This checks them, but only for an Issue
-// that declares itself one, and never asks the model to judge whether it is (joshuafolkken/kit#2212,
-// joshuafolkken/kit#2353). The declaration, the headings and the grammars are the template's, pinned
+// that declares itself one, and never asks the model to judge whether it is. The declaration, the
+// headings and the grammars are the template's, pinned
 // by the document test.
 
 // The body declares itself a behavior-change Issue with this exact line under its opening heading.

package/scripts/issue/defect-rate-cli.ts

@@ -79,7 +79,7 @@ function search_path(query: string, page: number = FIRST_PAGE): string {
 
 // How many pages the search holds, read off the first page's own count. Bounded by the API's
 // ceiling, past which GitHub serves no page at all — so this asks for exactly the pages `gh api
-// --paginate` used to walk to.
+// --paginate` would walk to.
 function page_count(first: SearchPage): number {
 	return Math.ceil(Math.min(first.total_count, SEARCH_RESULT_CEILING) / Number(PER_PAGE))
 }
@@ -87,13 +87,12 @@ function page_count(first: SearchPage): number {
 async function read_page(query: string, page: number): Promise<SearchPage | undefined> {
 	const raw = await git_gh_exec.exec_gh_api({ path: search_path(query, page) })
 
-	return parse_json.parse_json_object_safe(raw, search_page_schema)
+	return parse_json.parse_json_object_or_undefined(raw, search_page_schema)
 }
 
-// Every page of one search. joshuafolkken/kit#3103: `--paginate` follows each page's `next` link, so
-// a two-week window of ~5 pages cost ~1.5 s a page, one after another, on every `backlog:plan`. The
-// first page names the total, so the rest are fetched together; any page that does not read fails
-// the whole search, as a failed `--paginate` did.
+// Every page of one search. Not `gh api --paginate`: it follows each page's `next` link one page
+// after another, at about 1.5 s a page, on every `backlog:plan`. The first page names the total, so
+// the rest are fetched together; any page that does not read fails the whole search.
 async function read_pages(query: string): Promise<ReadonlyArray<SearchPage> | undefined> {
 	const first = await read_page(query, FIRST_PAGE)
 
@@ -138,7 +137,7 @@ async function search(query: string): Promise<SearchResult | undefined> {
 }
 
 // The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks
-// this same measurement (joshuafolkken/kit#2455), so the two cannot disagree about the rate.
+// this same measurement, so the two cannot disagree about the rate.
 async function measure_window(
 	repo: string,
 	days: number,

package/scripts/issue/defect-rate.ts

@@ -1,20 +1,27 @@
 import { behavior_change_lint } from './behavior-change-lint'
-import { has_label_name, INTERRUPT_ROUTE_LABEL } from './issue-labels'
+import {
+	BUG_LABEL,
+	BUGFIX_LABEL,
+	ENHANCEMENT_LABEL,
+	has_label_name,
+	INTERRUPT_ROUTE_LABEL,
+} from './issue-labels'
 import { markdown_section } from './markdown-section'
 
-// The defect rate of merged work over a window (joshuafolkken/kit#2449): issues filed as defects
-// divided by behavior changes completed. Both sides are read from an issue-kind declaration line and
-// the `route:interrupt` label, so nothing here asks for a judgement.
+// The defect rate of merged work over a window: issues filed as defects
+// divided by enhancements completed. Both sides are read from labels and the defect declaration line,
+// so nothing here asks for a judgement.
 
 // A body declares itself a defect with this exact line, the sibling of the behavior-change declaration.
-// Filers already write it, but the issue template does not list it yet and no filing lint enforces it,
-// so a defect filed without it is counted only when it carries `route:interrupt`.
+// Older bodies rarely wrote it, so the labels a maintainer re-applied after review count as well — the
+// name changed over time (`bugfix` earlier, `bug` from `issue:file`), and the labels read both periods
+// by one standard where the declaration alone moved the rate with the filing habit.
 const DEFECT_DECLARATION_LINE = '- 種別: 不具合'
+const DEFECT_LABELS: ReadonlyArray<string> = [BUG_LABEL, BUGFIX_LABEL, INTERRUPT_ROUTE_LABEL]
 const DEFAULT_WINDOW_DAYS = 14
-// The rate measured when the command was introduced — 20 / 48 over 2026-09-09 to 2026-09-23, recorded
-// on joshuafolkken/kit#2449 as the rounded 0.42, which is the threshold that issue fixed. `backlog:next` defers new mechanisms while the current rate is above it
-// (joshuafolkken/kit#2455).
-const BASELINE_RATE = 0.42
+// The rate over 2026-09-09 to 2026-09-23 measured by the label definition — 150 / 206, rounded.
+// `backlog:next` defers new mechanisms while the current rate is above it.
+const BASELINE_RATE = 0.73
 const MS_PER_DAY = 86_400_000
 const ISO_DATE_LENGTH = 10
 const RATE_DIGITS = 2
@@ -28,7 +35,7 @@ interface DefectRate {
 	days: number
 	since: string
 	defects: number
-	behavior_changes: number
+	enhancements: number
 	is_capped: boolean
 }
 
@@ -53,27 +60,30 @@ function filed_query(repo: string, since: string): string {
 	return `repo:${repo} is:issue created:>=${since}`
 }
 
+// Narrowed to the denominator's label, so the search pages only through what is counted.
 function completed_query(repo: string, since: string): string {
-	return `repo:${repo} is:issue is:closed reason:completed closed:>=${since}`
+	return `repo:${repo} is:issue is:closed reason:completed label:${ENHANCEMENT_LABEL} closed:>=${since}`
 }
 
 function is_defect(issue: RateIssue): boolean {
 	return (
 		markdown_section.has_line(issue.body, DEFECT_DECLARATION_LINE) ||
-		has_label_name(issue.labels, INTERRUPT_ROUTE_LABEL)
+		DEFECT_LABELS.some((label) => has_label_name(issue.labels, label))
 	)
 }
 
-function is_behavior_change(issue: RateIssue): boolean {
-	return behavior_change_lint.is_target(issue.body)
+// The denominator is every enhancement, not only the behavior changes `backlog:next` defers: a count
+// the priority itself shrinks would push the rate further up while it is above the baseline.
+function is_enhancement(issue: RateIssue): boolean {
+	return has_label_name(issue.labels, ENHANCEMENT_LABEL)
 }
 
-// A defect declaration or `route:interrupt` wins over a behavior-change declaration, so an issue that
-// is both counts as the fix it is.
+// A defect label or declaration wins over a behavior-change declaration, so an issue that is both
+// counts as the fix it is.
 function kind_of(issue: RateIssue): IssueKind {
 	if (is_defect(issue)) return 'defect'
 
-	return is_behavior_change(issue) ? 'mechanism' : 'other'
+	return behavior_change_lint.is_target(issue.body) ? 'mechanism' : 'other'
 }
 
 function measure(input: DefectRateInput): DefectRate {
@@ -81,17 +91,17 @@ function measure(input: DefectRateInput): DefectRate {
 		days: input.days,
 		since: input.since,
 		defects: input.filed.filter((issue) => is_defect(issue)).length,
-		behavior_changes: input.completed.filter((issue) => is_behavior_change(issue)).length,
+		enhancements: input.completed.filter((issue) => is_enhancement(issue)).length,
 		is_capped: input.is_capped,
 	}
 }
 
-// Undefined when no behavior change completed in the window: a rate over zero is no answer, and
-// printing 0 or Infinity would read as one.
+// Undefined when no enhancement completed in the window: a rate over zero is no answer, and printing
+// 0 or Infinity would read as one.
 function rate_of(result: DefectRate): number | undefined {
-	if (result.behavior_changes === 0) return undefined
+	if (result.enhancements === 0) return undefined
 
-	return result.defects / result.behavior_changes
+	return result.defects / result.enhancements
 }
 
 // Strictly above: a rate equal to the baseline has not risen, and a window with no rate is no answer.
@@ -104,16 +114,16 @@ function is_above_baseline(result: DefectRate): boolean {
 function rate_text(result: DefectRate): string {
 	const rate = rate_of(result)
 
-	if (rate === undefined) return 'n/a (no behavior change completed in the window)'
+	if (rate === undefined) return 'n/a (no enhancement completed in the window)'
 
-	return `${rate.toFixed(RATE_DIGITS)} (${String(result.defects)} / ${String(result.behavior_changes)})`
+	return `${rate.toFixed(RATE_DIGITS)} (${String(result.defects)} / ${String(result.enhancements)})`
 }
 
 function format(result: DefectRate): ReadonlyArray<string> {
 	const lines = [
 		`Defect rate over the last ${String(result.days)} days (since ${result.since}): ${rate_text(result)}`,
-		`  Defects filed: ${String(result.defects)} — declared \`${DEFECT_DECLARATION_LINE}\` or labelled ${INTERRUPT_ROUTE_LABEL}`,
-		`  Behavior changes completed: ${String(result.behavior_changes)} — declared \`${behavior_change_lint.DECLARATION_LINE}\`, closed as completed`,
+		`  Defects filed: ${String(result.defects)} — labelled ${DEFECT_LABELS.join(' / ')} or declared \`${DEFECT_DECLARATION_LINE}\``,
+		`  Enhancements completed: ${String(result.enhancements)} — labelled ${ENHANCEMENT_LABEL}, closed as completed`,
 	]
 
 	if (!result.is_capped) return lines

package/scripts/issue/git-next-issues.ts

@@ -3,14 +3,15 @@ import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { parse_json_array_safe } from '#scripts/git/parse-json-array'
 import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
 import { issue_rank, type DependencyRow } from './issue-rank'
+import { session_cite } from './session-cite'
 
-// The next-issues display printed when a workflow completes (#821): up to five open issues in
+// The next-issues display printed when a workflow completes: up to five open issues in
 // priority order, so the user picks the next run from the completion output instead of opening the
 // issue list. Priority is recency — a newer issue usually encodes the most current understanding
 // of the backlog — with the label-based exclusions below, under the ranking keys `issue-rank.ts`
-// defines (joshuafolkken/kit#2928).
+// defines.
 //
-// `prioritize` is also the order `epicrun` picks up `auto-ok` issues in (joshuafolkken/kit#906).
+// `prioritize` is also the order `epicrun` picks up `auto-ok` issues in.
 // The two ask one question — which open issue outside an epic is run next — so they share one
 // answer; a second ordering would have the run start something other than what this display, shown
 // at the end of every workflow, has just told the person is next.
@@ -19,7 +20,7 @@ const DISPLAY_LIMIT = 5
 const HEADER = '🗒 Next issues (newest first):'
 
 // Surfacing an `epic`, an `in-progress` or a `needs-decision` issue as "next" would suggest a run
-// the workflow rules forbid, duplicate, or cannot finish (joshuafolkken/kit#861). The set itself is
+// the workflow rules forbid, duplicate, or cannot finish. The set itself is
 // shared with the `auto-ok` pickup, which asks the same question of the same listing shape.
 function has_excluded_label(issue: OpenIssueData): boolean {
 	return has_any_label(issue.labels, NOT_DIRECTLY_RUNNABLE_LABELS)
@@ -51,7 +52,7 @@ function dependency_row(issue: OpenIssueData): DependencyRow {
 }
 
 // Every candidate in rank order, uncapped. `backlog:next` takes this rather than `prioritize`, so the
-// `run:solo` gate sees the whole ranking before anything is cut (joshuafolkken/kit#2928).
+// `run:solo` gate sees the whole ranking before anything is cut.
 function order(
 	issues: ReadonlyArray<OpenIssueData>,
 	completed_issue_number?: number,
@@ -69,7 +70,7 @@ function order(
 
 // **This display deliberately does not drop a blocked issue, and the `auto-ok` pickup deliberately
 // does.** They share this ordering and differ on the set, which reads as an inconsistency and is not
-// one (joshuafolkken/kit#1005).
+// one.
 //
 // The display is read by a person, who can see that an issue is blocked, judge that the blocker is
 // nearly done or does not really block it, and start anyway. The pickup feeds an unattended run,
@@ -87,7 +88,7 @@ function prioritize(
 function format_lines(issues: ReadonlyArray<OpenIssueData>): Array<string> {
 	if (issues.length === 0) return []
 	const rows = issues.map(
-		(issue, index) => `  ${String(index + 1)}. #${String(issue.number)} ${issue.title}`,
+		(issue, index) => `  ${String(index + 1)}. ${session_cite.issue(issue.number, issue.title)}`,
 	)
 
 	return [HEADER, ...rows]
@@ -99,7 +100,7 @@ function format_lines(issues: ReadonlyArray<OpenIssueData>): Array<string> {
 // failed over a purely informational display.
 async function fetch_next_issue_lines(completed_issue_number?: number): Promise<Array<string>> {
 	try {
-		// **`is_capped` is deliberately not read here** (joshuafolkken/kit#1067). The paging is
+		// **`is_capped` is deliberately not read here**. The paging is
 		// newest-first and this display keeps only the five newest of the twenty it asks for, so a
 		// listing the page ceiling cut short is a *prefix* of the one it would otherwise have got — the
 		// same five rows, in the same order. There is nothing the truncation hides that this display

package/scripts/issue/issue-auto-ok.ts

@@ -5,18 +5,24 @@ import { issue_file } from './issue-file'
 import { AUTO_OK_LABEL, has_label_name, RELEASE_LABEL } from './issue-labels'
 import { issue_state_cli } from './issue-state-cli'
 
-// Whether `josh issue:file` applies `auto-ok` to the Issue it files (joshuafolkken/kit#3213). Work
-// found during an unattended run used to wait in the backlog until a person labelled it, so the
-// filing now computes the answer instead of leaving it to the agent's memory: an Issue filed while a
+// Whether `josh issue:file` applies `auto-ok` to the Issue it files. So that work found during an
+// unattended run does not wait in the backlog until a person labels it, the filing computes the
+// answer instead of leaving it to the agent's memory: an Issue filed while a
 // `backlogrun` carry record is live, or from a branch whose Issue carries `auto-ok`, is opted in by
 // default. `--no-auto-ok` is the one exception, declared for an Issue that needs a person's judgement
 // (a Tier B toss-up or a Tier C action). A filing to another repository is never opted in: that
 // repository's own `backlogrun` would implement and merge it though nobody opted that repository in.
-// A `release` Issue is never opted in either (joshuafolkken/kit#3360): a release is Tier C, so only a
+// A `release` Issue is never opted in either: a release is Tier C, so only a
 // person applies `auto-ok` to it, whatever the carry record or the branch's Issue says.
+// `--requested` withholds the default the same way: a person asked for this filing (a `new` entry, or
+// a request in conversation), so the run's own opt-in does not speak for them — `auto-ok` comes only
+// from their own `--label auto-ok`. A filing without the declaration — an observation, a
+// retrospective, a routed filing — keeps the default above.
 
 interface AutoOkSignals {
 	is_opted_out: boolean
+	// `--requested`: a person asked for the filing, so neither the carry record nor the branch speaks.
+	is_requested: boolean
 	// The filing carries the `release` label.
 	is_release: boolean
 	is_carried: boolean
@@ -39,6 +45,10 @@ const RELEASE: AutoOkDecision = {
 	is_applied: false,
 	reason: `a ${RELEASE_LABEL} Issue is opted in by a person only`,
 }
+const REQUESTED: AutoOkDecision = {
+	is_applied: false,
+	reason: 'a person asked for this filing; auto-ok only when they declare it',
+}
 const CARRIED: AutoOkDecision = { is_applied: true, reason: 'a backlogrun carry record is live' }
 const BRANCH_OPTED_IN: AutoOkDecision = {
 	is_applied: true,
@@ -49,18 +59,21 @@ const NOT_OPTED_IN: AutoOkDecision = {
 	reason: 'no backlogrun carry record is live and the branch names no auto-ok Issue',
 }
 
-type Withholding = Pick<AutoOkSignals, 'is_opted_out' | 'is_release'>
+// What the filing itself declares: `--no-auto-ok` and `--requested`.
+type AutoOkDeclared = Pick<AutoOkSignals, 'is_opted_out' | 'is_requested'>
+type Withholding = AutoOkDeclared & Pick<AutoOkSignals, 'is_release'>
 
-// The two signals that withhold `auto-ok` before any other is read, or `undefined` when neither holds.
+// The three signals that withhold `auto-ok` before any other is read, or `undefined` when none holds.
 function withheld(signals: Withholding): AutoOkDecision | undefined {
 	if (signals.is_opted_out) return OPTED_OUT
 	if (signals.is_release) return RELEASE
+	if (signals.is_requested) return REQUESTED
 
 	return undefined
 }
 
-// The opt-out and the `release` label win over every signal, then the carry record, then the branch's
-// Issue.
+// The opt-out, the `release` label and `--requested` win over every signal, then the carry record,
+// then the branch's Issue.
 function decide(signals: AutoOkSignals): AutoOkDecision {
 	const decision = withheld(signals)
 
@@ -99,12 +112,12 @@ async function branch_labels(current: string): Promise<ReadonlyArray<string> | u
 // Each read is skipped once an earlier signal has already decided the answer; a cross-repository
 // filing is refused before any signal is read. `labels` are the ones the filing declares.
 async function resolve(
-	is_opted_out: boolean,
+	declared: AutoOkDeclared,
 	target: string,
 	current: string,
 	labels: ReadonlyArray<string> = [],
 ): Promise<AutoOkDecision> {
-	const withholding = { is_opted_out, is_release: has_label_name(labels, RELEASE_LABEL) }
+	const withholding = { ...declared, is_release: has_label_name(labels, RELEASE_LABEL) }
 	const decision = withheld(withholding)
 
 	if (decision !== undefined) return decision
@@ -116,5 +129,5 @@ async function resolve(
 
 const issue_auto_ok = { decide, line_of, resolve }
 
-export type { AutoOkDecision, AutoOkSignals }
+export type { AutoOkDeclared, AutoOkDecision, AutoOkSignals }
 export { issue_auto_ok }

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

@@ -1,18 +1,18 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { z } from 'zod'
 import { issue_backlinks, type UpstreamEntry } from './issue-backlinks'
 
 // `josh issue:backlinks <N>` — read origin issue N, then the upstream issues it lists, and print one
 // of `ok` / `missing-origin` / `missing-upstream` / `wrong-heading`, exiting non-zero on anything but
-// `ok` so it works as a gate (joshuafolkken/kit#2123).
+// `ok` so it works as a gate.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const REF_PATTERN = /^([\w.-]+\/[\w.-]+)#(\d+)$/u
 const BODY_FIELD = 'body'
 const USAGE = 'Usage: josh issue:backlinks <issue-number>'
@@ -21,7 +21,7 @@ const body_schema = z.object({ body: z.string().nullish() })
 
 function parse_body(raw_json: string | undefined): string | undefined {
 	if (raw_json === undefined) return undefined
-	const parsed = parse_json_object_safe(raw_json, body_schema)
+	const parsed = parse_json_object_or_undefined(raw_json, body_schema)
 
 	return parsed === undefined ? undefined : (parsed.body ?? '')
 }
@@ -67,7 +67,7 @@ async function classify(issue_number: string): Promise<string | undefined> {
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const [issue_number] = argv
 
-	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) {
+	if (issue_number === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE

package/scripts/issue/issue-backlinks.ts

@@ -1,9 +1,10 @@
 // The upstream backlink headings (`prompts/collaboration-workflow/issue-template.md`) are fixed so
 // they can be found by grep — the document says so outright — yet nothing greps them, and a
 // one-directional link (an origin that lists an upstream the upstream never points back at) survives
-// undetected. This classifies an origin issue's filed backlinks into one of four fixed words
-// (joshuafolkken/kit#2123). The headings are the single source's, pinned by the document test.
+// undetected. This classifies an origin issue's filed backlinks into one of four fixed words.
+// The headings are the single source's, pinned by the document test.
 
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { markdown_section } from './markdown-section'
 
 const ORIGIN_HEADING = '## Origin'
@@ -12,7 +13,6 @@ const UPSTREAM_CANDIDATE_HEADING = '## Upstream candidate'
 const CHECKBOX_PATTERN = /^\s*-\s*\[[ xX]\]/u
 const WRONG_UPSTREAM_HEADING_PATTERN = /^##\s+Upstream\b/iu
 const BARE_REFERENCE_PATTERN = /^#\d+$/u
-const DIGITS_PATTERN = /^\d+$/u
 const REFERENCE_MARK = '#'
 const PATH_SEPARATOR = '/'
 const PATH_SEGMENT_COUNT = 2
@@ -28,7 +28,7 @@ interface UpstreamEntry {
 	body: string
 }
 
-// A heading inside a code fence is example text, so neither lookup counts one (joshuafolkken/kit#3066).
+// A heading inside a code fence is example text, so neither lookup counts one.
 function has_heading(body: string, heading: string): boolean {
 	return markdown_section.has_line(body, heading)
 }
@@ -71,7 +71,7 @@ function is_qualified_reference(token: string): boolean {
 	const [path, number, ...rest] = token.split(REFERENCE_MARK)
 	if (number === undefined || rest.length > 0) return false
 
-	return DIGITS_PATTERN.test(number) && has_two_segments(path)
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(number) && has_two_segments(path)
 }
 
 function has_bare_reference(section: ReadonlyArray<string>): boolean {
@@ -134,7 +134,7 @@ function upstream_references(origin_body: string): ReadonlyArray<string> {
 // Whether classifying the origin needs the upstream bodies fetched. Only the `## Origin` back-check
 // does; a wrong, malformed or missing upstream heading is decided from the origin body alone. So the
 // CLI can skip the network for those, and never mask a `wrong-heading` verdict behind an upstream
-// that happens to be unreadable (joshuafolkken/kit#2123).
+// that happens to be unreadable.
 function needs_upstreams(origin_body: string): boolean {
 	if (has_wrong_upstream_heading(origin_body)) return false
 

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

@@ -1,19 +1,20 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueRead } from '#scripts/gh/git-gh-issue-read'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { issue_cite, type CiteTarget } from './issue-cite'
 
 // `josh issue:cite <N> [<N> ...] [--repo <owner/repo>]` — the paste-ready citation line for every
-// Issue named, in one call (joshuafolkken/kit#2220).
+// Issue named, in one call.
 //
-// It answers the cost that made the bare `#N` cheaper than the correct citation: the title each line
-// needs used to be a per-Issue `gh api` read, and naming several Issues at once — a backlog listing, a
-// lane status report — meant several round trips before a single correct line could be written. The
-// numbers go in together and the titles come back together, so the correct form is now the cheap one.
+// It answers the cost that makes the bare `#N` cheaper than the correct citation: a per-Issue
+// `gh api` read for each title means several round trips before a single correct line of a backlog
+// listing or lane status report can be written. The numbers go in together and the titles come back
+// together, so the correct form is the cheap one.
 //
 // **A token that is not a number refuses the whole invocation**, exactly as `issue:read` does: an
 // argument the parser cannot read is a mistake, and dropping it answers fewer Issues than were asked
@@ -30,6 +31,7 @@ const READ_CONCURRENCY = 8
 const TITLE_FIELD = 'title'
 const LINE_SEPARATOR = '\n'
 const USAGE = 'Usage: josh issue:cite <issue-number|owner/repo#N> [ ... ] [--repo <owner/repo>]'
+const OPTIONS = { repo: { type: 'string' } } as const
 
 const title_schema = z.looseObject({ title: z.string() })
 
@@ -38,13 +40,9 @@ type LineResult = { kind: 'ok'; line: string } | { kind: 'fail'; line: string }
 // The title out of the one-field read, or `undefined` for an empty or unparseable one — an empty title
 // is not a summary, so it is reported as a read that produced nothing rather than cited as a blank.
 function parse_title(json: string): string | undefined {
-	try {
-		const title = title_schema.parse(JSON.parse(json)).title.trim()
+	const title = json_value.parse_with(json, title_schema)?.title.trim()
 
-		return title === '' ? undefined : title
-	} catch {
-		return undefined
-	}
+	return title === '' ? undefined : title
 }
 
 // A read's outcome as one line: the citation on success, the matching failure line otherwise. The
@@ -115,13 +113,17 @@ function report(results: ReadonlyArray<LineResult>): number {
 	return failures.length === 0 ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
+// The targets the command line names, or `undefined` for a line nobody can read — an unknown flag and
+// a `--repo` given no value are refused with the same usage a non-numeric token is.
+function read_targets(args: ReadonlyArray<string>): ReadonlyArray<CiteTarget> | undefined {
+	const parsed = cli_flags.arguments_of(args, OPTIONS)
+	if (parsed === undefined) return undefined
+
+	return parse_targets(parsed.positionals, parsed.values.repo)
+}
+
 async function run(args: ReadonlyArray<string>): Promise<number> {
-	const parsed = parseArgs({
-		args: [...args],
-		options: { repo: { type: 'string' } },
-		allowPositionals: true,
-	})
-	const targets = parse_targets(parsed.positionals, parsed.values.repo)
+	const targets = read_targets(args)
 
 	if (targets === undefined) {
 		console.error(USAGE)