@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/{git/git-epic-run.ts → epic/epic-run.ts}

@@ -1,9 +1,9 @@
-import { git_epic_body } from './git-epic-body'
-import { git_epic_promote } from './git-epic-promote'
-import { git_epic_relations } from './git-epic-relations'
-import { git_epic_validate, type EpicSubject } from './git-epic-validate'
-import { git_gh_command } from './git-gh-command'
-import { EPIC_LABEL } from './issue-labels'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { EPIC_LABEL } from '#scripts/git/issue-labels'
+import { epic_body } from './epic-body'
+import { epic_promote } from './epic-promote'
+import { epic_relations } from './epic-relations'
+import { epic_validate, type EpicSubject } from './epic-validate'
 
 const EPIC_LABEL_COLOR = '#5319e7'
 const EPIC_LABEL_DESCRIPTION = 'Tracks a batch of child issues from one split'
@@ -20,18 +20,18 @@ interface CreateEpicInput {
 
 // The relations the declared order implies, applied through the shared module `--add` also uses so
 // the two cannot drift. A failure is reported and stepped over rather than aborting a batch that is
-// otherwise fine — see `git-epic-relations.ts` for why the relation is not part of the contract.
+// otherwise fine — see `epic-relations.ts` for why the relation is not part of the contract.
 async function apply_dependencies(input: {
 	children: ReadonlyArray<number>
 	is_ordered: boolean
 }): Promise<void> {
-	const pairs = git_epic_body.build_dependency_pairs(input.children, input.is_ordered)
+	const pairs = epic_body.build_dependency_pairs(input.children, input.is_ordered)
 	if (pairs.length === 0) return
 
-	const failures = await git_epic_relations.apply_relations(pairs, 'record')
+	const failures = await epic_relations.apply_relations(pairs, 'record')
 
 	console.info(
-		git_epic_relations.format_relation_report({
+		epic_relations.format_relation_report({
 			links: pairs,
 			failures,
 			action: 'record',
@@ -61,7 +61,7 @@ async function fill_run_command(
 ): Promise<void> {
 	if (epic_number === undefined) {
 		console.info(
-			`⚠️  Could not read the new epic's number from its URL; the Execution section still says \`${git_epic_body.format_run_command(undefined)}\`.`,
+			`⚠️  Could not read the new epic's number from its URL; the Execution section still says \`${epic_body.format_run_command(undefined)}\`.`,
 		)
 
 		return
@@ -70,7 +70,7 @@ async function fill_run_command(
 	try {
 		await git_gh_command.issue_edit_body(
 			String(epic_number),
-			git_epic_body.build_epic_body({
+			epic_body.build_epic_body({
 				children: input.children,
 				rationale: input.rationale,
 				is_ordered: input.is_ordered,
@@ -90,7 +90,7 @@ async function create_epic(input: CreateEpicInput): Promise<number> {
 		description: EPIC_LABEL_DESCRIPTION,
 	})
 
-	const body = git_epic_body.build_epic_body({
+	const body = epic_body.build_epic_body({
 		children: input.children,
 		rationale: input.rationale,
 		is_ordered: input.is_ordered,
@@ -107,7 +107,7 @@ async function create_epic(input: CreateEpicInput): Promise<number> {
 	console.info(`📋 Created epic: ${url}`)
 	await apply_dependencies({ children: input.children, is_ordered: input.is_ordered })
 	await fill_run_command(epic_number, input)
-	console.info(`▶ Run the children with: ${git_epic_body.format_run_command(epic_number)}`)
+	console.info(`▶ Run the children with: ${epic_body.format_run_command(epic_number)}`)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -123,7 +123,7 @@ interface PromoteEpicInput {
 // The issue being promoted, or the reason it cannot be. Refused when it already carries the epic
 // sections — a second append would give the auto-close two task lists to disagree about.
 async function read_promotion_subject(epic_number: number): Promise<EpicSubject | undefined> {
-	const subject = git_epic_validate.parse_epic_subject(
+	const subject = epic_validate.parse_epic_subject(
 		await git_gh_command.issue_get_labels_and_body(String(epic_number)),
 	)
 
@@ -133,8 +133,8 @@ async function read_promotion_subject(epic_number: number): Promise<EpicSubject
 		return undefined
 	}
 
-	if (git_epic_promote.has_conflicting_tracking(subject.body)) {
-		const reason = git_epic_promote.conflict_reason(subject.body)
+	if (epic_promote.has_conflicting_tracking(subject.body)) {
+		const reason = epic_promote.conflict_reason(subject.body)
 
 		console.error(`✖ Cannot promote #${String(epic_number)}: ${reason}.`)
 
@@ -144,16 +144,16 @@ async function read_promotion_subject(epic_number: number): Promise<EpicSubject
 	return subject
 }
 
-// Write the promoted body and apply the label. The label is what `git-epic-close.ts` filters on, so
+// Write the promoted body and apply the label. The label is what `epic-close.ts` filters on, so
 // an unlabelled issue is one the auto-close skips forever — a failure there is reported rather than
 // logged past.
 async function write_promotion(
 	input: PromoteEpicInput,
 	existing_body: string | undefined,
 ): Promise<number> {
-	const body = git_epic_promote.build_promoted_body({ ...input, body: existing_body })
+	const body = epic_promote.build_promoted_body({ ...input, body: existing_body })
 
-	const tracking_error = git_epic_promote.find_tracking_error(body, input.children)
+	const tracking_error = epic_promote.find_tracking_error(body, input.children)
 
 	if (tracking_error !== undefined) {
 		console.error(`✖ ${tracking_error}`)
@@ -190,14 +190,14 @@ async function promote_epic(input: PromoteEpicInput): Promise<number> {
 
 	console.info(`📋 Promoted #${String(input.epic_number)} to an epic.`)
 	await apply_dependencies({ children: input.children, is_ordered: input.is_ordered })
-	console.info(`▶ Run the children with: ${git_epic_body.format_run_command(input.epic_number)}`)
+	console.info(`▶ Run the children with: ${epic_body.format_run_command(input.epic_number)}`)
 
 	return SUCCESS_EXIT_CODE
 }
 
 async function check_epic(epic_number: number): Promise<number> {
 	const raw = await git_gh_command.issue_get_labels_and_body(String(epic_number))
-	const subject = git_epic_validate.parse_epic_subject(raw)
+	const subject = epic_validate.parse_epic_subject(raw)
 
 	if (subject === undefined) {
 		console.error(`✖ Could not read issue #${String(epic_number)}.`)
@@ -205,19 +205,19 @@ async function check_epic(epic_number: number): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const results = git_epic_validate.validate_epic(subject)
+	const results = epic_validate.validate_epic(subject)
 
-	console.info(git_epic_validate.format_check_report(subject.number, results))
+	console.info(epic_validate.format_check_report(subject.number, results))
 
-	return git_epic_validate.is_epic_valid(results) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return epic_validate.is_epic_valid(results) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
-const git_epic_run = {
+const epic_run = {
 	parse_created_number,
 	create_epic,
 	promote_epic,
 	check_epic,
 }
 
-export { git_epic_run, EPIC_LABEL_COLOR, EPIC_LABEL_DESCRIPTION, FAILURE_EXIT_CODE }
+export { epic_run, EPIC_LABEL_COLOR, EPIC_LABEL_DESCRIPTION, FAILURE_EXIT_CODE }
 export type { CreateEpicInput, PromoteEpicInput }

package/scripts/{git/git-epic-sections.ts → epic/epic-sections.ts}

@@ -1,8 +1,8 @@
-import { git_epic_parse } from './git-epic-parse'
+import { epic_parse } from './epic-parse'
 
 // Locating a `## <Name>` section inside an epic body, as the shape every rewrite of one needs.
 //
-// It was `git-epic-add-body.ts`'s private half: that file finds the `Dependencies` section so a
+// It was `epic-add-body.ts`'s private half: that file finds the `Dependencies` section so a
 // 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
@@ -29,13 +29,13 @@ interface SectionRange {
 	end: number
 }
 
-// Accepts the body or the lines it was already split into: `git-epic-add-body.ts` holds both forms at
+// Accepts the body or the lines it was already split into: `epic-add-body.ts` holds both forms at
 // different points of one rewrite, and `join`/`split` round-trip exactly, so one function serves both
 // rather than the caller re-deriving a mask that has to agree with this one.
 function to_body_lines(source: string | ReadonlyArray<string>): BodyLines {
 	const lines = typeof source === 'string' ? source.split('\n') : source
 
-	return { lines, mask: git_epic_parse.fence_mask(lines.join('\n')) }
+	return { lines, mask: epic_parse.fence_mask(lines.join('\n')) }
 }
 
 function is_readable(input: BodyLines, index: number): boolean {
@@ -87,12 +87,12 @@ function is_in_range(index: number, range: SectionRange): boolean {
 	return index >= range.start && index < range.end
 }
 
-const git_epic_sections = {
+const epic_sections = {
 	to_body_lines,
 	find_indices,
 	find_section_range,
 	is_in_range,
 }
 
-export { git_epic_sections }
+export { epic_sections }
 export type { BodyLines, SectionRange }

package/scripts/{git/git-epic-shape.ts → epic/epic-shape.ts}

@@ -1,6 +1,6 @@
-import { git_epic_parse } from './git-epic-parse'
-import { to_issue_reference } from './git-epic-reference'
-import { EPIC_LABEL } from './issue-labels'
+import { EPIC_LABEL } from '#scripts/git/issue-labels'
+import { epic_parse } from './epic-parse'
+import { to_issue_reference } from './epic-reference'
 
 // Whether an issue is an epic this repository's writers may edit, and why it is not when it is not.
 //
@@ -47,7 +47,7 @@ function find_epic_shape_error(subject: EpicShapeSubject, body: string): string
 		return `${reference} does not carry the \`${EPIC_LABEL}\` label, so it is not an epic. ${promote_remedy(subject.epic_number)}`
 	}
 
-	if (git_epic_parse.has_external_task_list_entry(body)) {
+	if (epic_parse.has_external_task_list_entry(body)) {
 		return `${reference} tracks a child in another repository; editing the declared order of a cross-repository epic is joshuafolkken/kit#864's scope, not this command's.`
 	}
 
@@ -68,14 +68,14 @@ function find_subject_error(
 	}
 
 	// A declaration an edit can be relative to: exactly one of the two machine-readable forms.
-	return git_epic_parse.has_machine_readable_declaration(subject.body)
+	return epic_parse.has_machine_readable_declaration(subject.body)
 		? undefined
 		: missing_declaration_error(subject.epic_number)
 }
 
-const git_epic_shape = {
+const epic_shape = {
 	find_subject_error,
 }
 
-export { git_epic_shape }
+export { epic_shape }
 export type { EpicShapeSubject }

package/scripts/epic/epic-solo.ts

@@ -21,12 +21,11 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // 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.
 //
-// **An idle repository takes its first `run:solo` candidate ahead of the ranking**
-// (joshuafolkken/kit#2778). An issue carries the label because its defect reaches the verification
-// path, and `wip-cap.md` resumes a batch only once that has merged — so an ordinary candidate ranked
-// ahead of it would spend a whole wave running alone, then hold the fix back behind its own merge.
-// While lanes are running the ranking stands: nothing overtakes a waiting `run:solo` candidate, and
-// the ones ahead of it keep their lanes.
+// **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
+// repository takes the candidates in rank order like any other.
 
 const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
 
@@ -75,32 +74,21 @@ function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelect
 	return { offered: [], withheld: [...children], notice }
 }
 
-// The ranking with the first `run:solo` candidate moved to the head — but only into an idle
-// repository, the one place it may start. Anywhere else the ranking is returned as it was.
-function prefer(children: ReadonlyArray<EpicChild>, read: BusyRead): ReadonlyArray<EpicChild> {
-	const solo = children.find((child) => is_solo(child))
-
-	if (solo === undefined || read.kind !== 'idle') return children
-
-	return [solo, ...children.filter((child) => child !== solo)]
-}
-
 // Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
-// candidates ahead of it when lanes are running, and it alone into an idle repository.
+// candidates ahead of it when it is not first, and it alone once it heads an idle repository's ranking.
 function select_candidates(
 	children: ReadonlyArray<EpicChild>,
 	read: BusyRead,
 	repo: string,
 ): SoloSelection {
-	const ordered = prefer(children, read)
-	const index = ordered.findIndex((child) => is_solo(child))
-	const solo = ordered[index]
+	const index = children.findIndex((child) => is_solo(child))
+	const solo = children[index]
 
-	if (solo === undefined) return first_of(ordered, ordered.length)
-	if (index > 0) return first_of(ordered, index)
-	if (read.kind === 'idle') return first_of(ordered, 1)
+	if (solo === undefined) return first_of(children, children.length)
+	if (index > 0) return first_of(children, index)
+	if (read.kind === 'idle') return first_of(children, 1)
 
-	return none_of(ordered, waiting_message(solo.number, repo))
+	return none_of(children, waiting_message(solo.number, repo))
 }
 
 // An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
@@ -129,11 +117,24 @@ function withhold(result: EpicNextResult, repo: string, selection: SoloSelection
 	}
 }
 
+// What decides the selection. `select` by default; `backlog:next` passes one that ranks before it and
+// caps after it (`backlog-rank.ts`), so the gate itself is written once.
+type SoloSelector = (
+	children: ReadonlyArray<EpicChild>,
+	read: BusyRead,
+	repo: string,
+) => SoloSelection
+
 // Only a `run` answer offers anything, so every other verdict passes through untouched.
-function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
+function gate(
+	result: EpicNextResult,
+	read: BusyRead,
+	repo: string,
+	selector: SoloSelector = select,
+): SoloGate {
 	if (result.verdict !== 'run') return { result }
 
-	const selection = select(epic_report.candidates_for_repo(result, repo), read, repo)
+	const selection = selector(epic_report.candidates_for_repo(result, repo), read, repo)
 	const gated = withhold(result, repo, selection)
 
 	return selection.notice === undefined
@@ -141,7 +142,7 @@ function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
 		: { result: gated, notice: selection.notice }
 }
 
-const epic_solo = { gate, is_solo, prefer, select }
+const epic_solo = { gate, is_solo, select }
 
-export type { SoloGate, SoloSelection }
+export type { SoloGate, SoloSelection, SoloSelector }
 export { epic_solo }

package/scripts/{git/git-epic-validate.ts → epic/epic-validate.ts}

@@ -1,19 +1,19 @@
-import { git_epic_parse, type DeclarationState } from './git-epic-parse'
-import { EPIC_LABEL, has_label_name } from './issue-labels'
-import { parse_json_object_safe } from './parse-json-array'
-import { epic_subject_schema } from './schemas'
+import { EPIC_LABEL, has_label_name } from '#scripts/git/issue-labels'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { epic_subject_schema } from '#scripts/git/schemas'
+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
 // procedure carefully, and three of the four fail silently: a missing label or a bare `#N` child
-// list makes `git-epic-close.ts` skip the epic forever, and prose dependencies make the batch read
+// list makes `epic-close.ts` skip the epic forever, and prose dependencies make the batch read
 // as unordered so a skipped `--add-blocked-by` is never reported. Checking them here reuses
-// `git-epic-parse.ts` rather than restating the patterns, so "what the auto-close can read" and
+// `epic-parse.ts` rather than restating the patterns, so "what the auto-close can read" and
 // "what this check accepts" are one definition instead of two that can drift.
 
 interface EpicSubject {
 	number: number
 	// The epic's own state, as GitHub returned it (`OPEN` / `CLOSED`, casing unnormalized). Only
-	// `git-epic-add.ts` reads it — to refuse adding a child to a closed epic — so it is optional: a read
+	// `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).
 	state?: string | undefined
@@ -65,7 +65,7 @@ function format_children(children: ReadonlyArray<number>): string {
 }
 
 function check_task_list(subject: EpicSubject): CheckResult {
-	const children = git_epic_parse.parse_task_list_issue_numbers(subject.body)
+	const children = epic_parse.parse_task_list_issue_numbers(subject.body)
 	const is_passing = children.length > 0
 
 	return {
@@ -94,11 +94,11 @@ function describe_dependencies(state: DeclarationState): string {
 // each of them. The literal is compared against the constant the generator emits, and the chain
 // against the one the link reader parses, so no two of them can drift into disagreement.
 function check_dependencies(subject: EpicSubject): CheckResult {
-	const state = git_epic_parse.read_declaration(subject.body)
+	const state = epic_parse.read_declaration(subject.body)
 
 	return {
 		name: 'dependencies section',
-		is_passing: git_epic_parse.is_declaration_readable(state),
+		is_passing: epic_parse.is_declaration_readable(state),
 		detail: describe_dependencies(state),
 	}
 }
@@ -107,7 +107,7 @@ function check_dependencies(subject: EpicSubject): CheckResult {
 // deliberately leaves such an epic open. Reporting it here is what turns "stayed open silently"
 // into "was told to close it manually".
 function check_external_children(subject: EpicSubject): CheckResult {
-	const has_external = git_epic_parse.has_external_task_list_entry(subject.body)
+	const has_external = epic_parse.has_external_task_list_entry(subject.body)
 
 	return {
 		name: 'auto-close eligibility',
@@ -144,12 +144,12 @@ function format_check_report(epic_number: number, results: ReadonlyArray<CheckRe
 	return [...lines, '', summary].join('\n')
 }
 
-const git_epic_validate = {
+const epic_validate = {
 	parse_epic_subject,
 	validate_epic,
 	is_epic_valid,
 	format_check_report,
 }
 
-export { git_epic_validate }
+export { epic_validate }
 export type { CheckResult, EpicSubject }

package/{scripts-ai → scripts/epic}/epic.ts

@@ -2,19 +2,20 @@
 /**
  * Create an epic Issue that satisfies every requirement the auto-close and the order warning read.
  *
- * Usage: tsx scripts-ai/epic.ts "<title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->]
+ * Usage: tsx scripts/epic/epic.ts "<title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->]
  *                                                       [--origin <owner/repo#N>]
- *        tsx scripts-ai/epic.ts --promote <N> <N1> <N2> ... [same flags]
- *        tsx scripts-ai/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
+ *        tsx scripts/epic/epic.ts --promote <N> <N1> <N2> ... [same flags]
+ *        tsx scripts/epic/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
  *                                                      [--decision-file <path|->]
- *        tsx scripts-ai/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
  */
-import { git_epic_add, type AddChildrenInput } from '../scripts/git/git-epic-add'
-import { git_epic_reconcile } from '../scripts/git/git-epic-reconcile'
-import { git_epic_remove } from '../scripts/git/git-epic-remove'
-import { git_epic_run } from '../scripts/git/git-epic-run'
-import { git_gh_command } from '../scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { error_text } from '#scripts/lib/error-message'
+import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+import { epic_reconcile } from './epic-reconcile'
+import { epic_remove } from './epic-remove'
+import { epic_run } from './epic-run'
 
 const ARGV_OFFSET = 2
 const FLAGS = '[--ordered] [--rationale-file <path|->] [--origin <owner/repo#N>]'
@@ -37,7 +38,7 @@ async function run_promotion(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_run.promote_epic({
+	return await epic_run.promote_epic({
 		epic_number: parsed.epic_number,
 		children: parsed.children,
 		rationale: epic_cli.read_rationale(parsed.rationale_path),
@@ -67,7 +68,7 @@ function to_add_input(parsed: AddArguments): AddChildrenInput {
 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())
 
-	if (local !== undefined) return await git_epic_add.add_children(to_add_input(local))
+	if (local !== undefined) return await epic_add.add_children(to_add_input(local))
 
 	console.error(epic_cli.format_cross_repo_refusal(found))
 
@@ -109,7 +110,7 @@ async function run_addition(argv: ReadonlyArray<string>): Promise<number> {
 
 	if (parsed === undefined) return await refuse_addition(argv)
 
-	return await git_epic_add.add_children(to_add_input(parsed))
+	return await epic_add.add_children(to_add_input(parsed))
 }
 
 // Deleting a declared order. No position and no `--ordered`: the path itself says which orders go,
@@ -126,7 +127,7 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_remove.remove_order({
+	return await epic_remove.remove_order({
 		epic_number: parsed.epic_number,
 		path: parsed.path,
 		decision: epic_cli.read_decision(parsed.decision_path),
@@ -144,7 +145,7 @@ async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number>
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_reconcile.reconcile_epic(parsed.epic_number)
+	return await epic_reconcile.reconcile_epic(parsed.epic_number)
 }
 
 async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
@@ -156,7 +157,7 @@ async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await git_epic_run.create_epic({
+	return await epic_run.create_epic({
 		title: parsed.title,
 		children: parsed.children,
 		rationale: epic_cli.read_rationale(parsed.rationale_path),
@@ -187,6 +188,6 @@ async function main(): Promise<void> {
 try {
 	await main()
 } catch (error) {
-	console.error(`✖ ${error instanceof Error ? error.message : String(error)}`)
+	console.error(`✖ ${error_text.message_of(error)}`)
 	process.exit(FAILURE_EXIT_CODE)
 }

package/scripts/gh/fix-gh-packages.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 import { z } from 'zod'
 import { fix_gh_packages_logic, type LockfilePackage } from './fix-gh-packages-logic'
 import { gh_cli_token } from './gh-cli-token'
@@ -19,7 +20,7 @@ const npm_packument_schema = z.looseObject({
 type ParsedPackages = Record<string, LockfilePackage>
 
 function read_file(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(file_path)
 }
 
 // Resolution order: NODE_AUTH_TOKEN → a literal token in the project .npmrc → `gh auth token`.

package/scripts/gh/gh-spawn.ts

@@ -1,27 +1,29 @@
 import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { execaSync } from 'execa'
 
 // The synchronous twin of `git_gh_repo.repo_get_name_with_owner`: same fact, read the same way, but
-// through `execaSync` because `josh init` / `josh sync` / `josh doctor` decide before they can await.
+// synchronously because `josh init` / `josh sync` / `josh doctor` decide before they can await.
 // It asks REST for the same reason — `gh repo view` goes through GraphQL, which a cloud session is
 // refused (403), and a repository that reads as unresolved makes `init` / `sync` skip
 // `sonar-project.properties` outright (joshuafolkken/kit#1023). The path comes from the shared
 // builder rather than being spelled out again here.
 //
-// `timeout` is spread in rather than passed as `undefined`: execa's options type does not admit an
-// undefined value for it, and an explicit `undefined` would not mean "no timeout" anyway.
+// An unbounded lookup asks for `NO_BUDGET`, execa's own "no timeout": the shared layer otherwise
+// applies its default budget, which would change what `init` / `sync` wait for.
+const NO_BUDGET = 0
+
 function fetch_repo_name(timeout_ms: number | undefined): string | undefined {
-	const result = execaSync('gh', ['api', git_gh_api_path.repo_api_path(), '--jq', '.full_name'], {
-		...git_gh_exec.direct_environment(),
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: git_gh_api_path.repo_api_path(),
+		jq_filter: '.full_name',
 		cwd: PROJECT_ROOT,
-		reject: false,
-		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		timeout_ms: timeout_ms ?? NO_BUDGET,
 	})
-	if (result.exitCode !== 0 || !result.stdout) return undefined
 
-	return result.stdout.trim() || undefined
+	const name = stdout?.trim()
+
+	return name === '' ? undefined : name
 }
 
 // The unbounded lookup, for callers whose *writes* depend on the answer. A timeout would surface as

package/scripts/git/constants.ts

@@ -10,7 +10,7 @@ const GIT_COMMAND_UNIX = '/usr/bin/git'
 // modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
 const PORCELAIN_FLAG = '--porcelain'
 // The untracked-files mode every porcelain status reading passes (`git-command.ts` carries why it is
-// passed and why it is `all`), shared so `run-carry-flush.ts`'s own reading cannot drift from it.
+// passed and why it is `all`), shared so another module's own reading cannot drift from it.
 const UNTRACKED_FILES_FLAG = '--untracked-files=all'
 
 function get_git_command(): string {

package/scripts/git/git-branch.ts

@@ -75,7 +75,7 @@ async function pull_latest(): Promise<void> {
 	)
 }
 
-const ISSUE_PREFIX_PATTERN = /^\d+-/u
+const ISSUE_PREFIX_PATTERN = /^(\d+)-/u
 
 function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
 	const prefix_a = ISSUE_PREFIX_PATTERN.exec(branch_a)?.[0]
@@ -84,6 +84,14 @@ function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
 	return prefix_a !== undefined && prefix_a === prefix_b
 }
 
+// The issue a branch names, or `undefined` when it does not lead with one — `1937-lane` and
+// `1937-add-a-scope` both read 1937, while `main` reads nothing.
+function issue_from_branch(branch: string): number | undefined {
+	const digits = ISSUE_PREFIX_PATTERN.exec(branch)?.[1]
+
+	return digits === undefined ? undefined : Number(digits)
+}
+
 // The one rule `check_and_create_branch` refuses on, kept pure so `git-preflight.ts` asks it before
 // anything is pulled, switched or staged.
 function is_mismatch(
@@ -133,6 +141,7 @@ const git_branch = {
 	// second copy of the pattern (joshuafolkken/kit#1497). A copy is what let `lane/<N>` ship: nothing
 	// asserted that the name `lane:open` writes is one this function accepts.
 	has_same_issue_prefix,
+	issue_from_branch,
 }
 
 export { git_branch }

package/scripts/git/git-command.ts

@@ -411,14 +411,14 @@ async function push(): Promise<void> {
 // the same thing: it is on the default branch, bringing it up to date before doing something else —
 // `main-sync.ts` for `josh ms`, `release-cli.ts` / `release-publish.ts` around the release pull
 // request, `scripts-ai/prep.ts` before it snapshots the overrides, and `git-branch.ts` →
-// `pull_latest` — reached from `scripts-ai/git-workflow.ts`, so it runs on every `josh git` /
+// `pull_latest` — reached from `git-workflow.ts`, so it runs on every `josh git` /
 // `josh pr` started from the default branch, which makes it the hottest of the five rather than a
 // dormant one. **None of them is
 // asking to absorb divergence**, so `merge_branch`'s reasoning inverts here: a default branch that
 // has diverged is a state to fail loudly on rather than to grow a merge commit over. The name says
 // which of the two this is, as `merge_fast_forward` does beside `merge_branch`.
 async function pull_fast_forward(): Promise<void> {
-	await git_spawn.with_output('pull', ['--ff-only'])
+	await git_spawn.with_output_remote('pull', ['--ff-only'])
 }
 
 // Every local branch matching a `git branch --list` pattern, one name per line. The boolean below is

package/scripts/git/git-error.ts

@@ -1,9 +1,6 @@
+import { error_text } from '#scripts/lib/error-message'
 import { has_stderr_field } from './git-gh-exec'
 
-function get_error_message(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 function get_stderr_from_error(cause: Error): string | undefined {
 	if (!has_stderr_field(cause)) return undefined
 
@@ -46,7 +43,7 @@ function display_error_details(cause: unknown): void {
 }
 
 function handle(error: unknown): void {
-	const error_message = get_error_message(error)
+	const error_message = error_text.message_of(error)
 
 	console.error('')
 	console.error('❌ Error:', error_message)