@joshuafolkken/kit 1.1010.0 → 1.1035.0

package/scripts/doctor/doctor-ports.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME, PORT_SEED_KEY, ports } from '#ports'
 import { lane_environment } from '#scripts/lane/lane-environment'
+import { file_reader } from '#scripts/lib/read-file'
 
 // Each discovered repository's port seed and the dev / preview ports it resolves to, plus which
 // repositories share a seed (joshuafolkken/kit#1494).
@@ -40,7 +40,7 @@ interface SharedSeed {
 // the one key that is actually wrong.
 function read_repository_ports(name: string, repository_path: string): RepoPorts {
 	const file = path.join(repository_path, ENV_FILE_NAME)
-	const content = existsSync(file) ? readFileSync(file, 'utf8') : ''
+	const content = file_reader.read_file_or_empty(file)
 
 	try {
 		const seed = lane_environment.read_root_seed(content)

package/scripts/document/document-byte-budget.ts

@@ -65,7 +65,7 @@ function block_ceiling(size: number): number {
 // unreached file, so the definition cannot rot as documents move on or off the execution path.
 const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 8192 },
-	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 32_768 },
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 36_864 },
 	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/followup-reference.md', bytes: 16_384 },
 	{ path: '.claude/skills/workflow-commands/fullrun-steps.md', bytes: 8192 },
@@ -79,37 +79,29 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	// two budgets must not hold it twice — the reachability line moved it from `unreached` to
 	// `point-of-use`.
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	{ path: 'docs/josh-commands.md', bytes: 180_224 },
-	{ path: 'prompts/agent-rules.md', bytes: 4096 },
-	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
+	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
-	{ path: 'prompts/collaboration-workflow/consultation-vs-execution.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/cross-repo-epic.md', bytes: 8192 },
-	{ path: 'prompts/collaboration-workflow/distributed-docs.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/durable-rules.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/epic-audit.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/epic-bundle.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/cross-repo-epic.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/epic-audit.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/epic-bundle.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 8192 },
 	// #2662 adds the feature and compatibility declarations to the canonical filing procedure.
 	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/latest-first.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/no-clones.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 24_576 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/plan-comment.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/principles.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/proposal-request.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/report-format.md', bytes: 28_672 },
-	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 28_672 },
 	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 57_344 },
 	{ path: 'prompts/collaboration-workflow/shell-body.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/simplicity-first.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/single-source-rules.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/turn-batching.md', bytes: 24_576 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
 	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 20_480 },

package/scripts/document/document-section.ts

@@ -12,7 +12,7 @@
 // is the distinction joshuafolkken/kit#1344 and joshuafolkken/kit#1460 were written after: a rule
 // moved to "read it later" is a rule that measurably never fires, and this moves nothing to later.
 
-import { readFileSync } from 'node:fs'
+import { file_reader } from '#scripts/lib/read-file'
 
 // `#` to `######`, one space, then the title. Written with a literal space rather than `\s+` and a
 // lazy title so it cannot backtrack: `sonarjs/super-linear-regex` rejects the `\s+…+?\s*$` shape,
@@ -134,11 +134,7 @@ function candidates(markdown: string, wanted: string): Array<string> {
 }
 
 function read_optional(file_path: string): string | undefined {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return undefined
-	}
+	return file_reader.read_if_readable(file_path)
 }
 
 const document_section = {

package/scripts/document/entry-read-budget.ts

@@ -82,7 +82,7 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	{ entry: 'fullrun', bytes: 229_376 },
 	{ entry: 'halfrun', bytes: 229_376 },
 	{ entry: 'backlogrun', bytes: 233_472 },
-	{ entry: LANE_CHILD, bytes: 81_920 },
+	{ entry: LANE_CHILD, bytes: 77_824 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

package/scripts/{git/git-epic-add-body.ts → epic/epic-add-body.ts}

@@ -1,12 +1,12 @@
-import { git_epic_chains, type Chains, type InsertPosition } from './git-epic-chains'
-import { git_epic_decision } from './git-epic-decision'
-import { git_epic_parse, UNORDERED_DEPENDENCIES } from './git-epic-parse'
+import { epic_chains, type Chains, type InsertPosition } from './epic-chains'
+import { epic_decision } from './epic-decision'
+import { epic_parse, UNORDERED_DEPENDENCIES } from './epic-parse'
 import {
 	format_dependency_link,
 	format_issue_references,
 	to_issue_reference,
-} from './git-epic-reference'
-import { git_epic_sections, type BodyLines, type SectionRange } from './git-epic-sections'
+} from './epic-reference'
+import { epic_sections, type BodyLines, type SectionRange } from './epic-sections'
 
 // Rewriting an epic body so its task list and its dependency declaration both name a newly inserted
 // child, and refusing to hand back a body that would not.
@@ -50,7 +50,7 @@ interface RewriteInput {
 
 type RewriteOutcome = { body: string } | { error: string }
 
-const { find_indices, is_in_range, to_body_lines } = git_epic_sections
+const { find_indices, is_in_range, to_body_lines } = epic_sections
 
 function to_task_row(issue_number: number): string {
 	return `- [ ] ${to_issue_reference(issue_number)}`
@@ -66,7 +66,7 @@ function to_task_rows(placed: ReadonlyArray<number>): Array<string> {
 // insertion that declared no order takes, and the only one it can take: with no position named there
 // is nothing for a row to be relative to.
 function append_task_rows(input: BodyLines, placed: ReadonlyArray<number>): Array<string> {
-	const rows = find_indices(input, (line) => git_epic_parse.is_task_list_line(line))
+	const rows = find_indices(input, (line) => epic_parse.is_task_list_line(line))
 	const last = rows.at(-1)
 	if (last === undefined) return [...input.lines]
 
@@ -80,7 +80,7 @@ function append_task_rows(input: BodyLines, placed: ReadonlyArray<number>): Arra
 // The issue a task-list row names, read through the parser rather than a second pattern of its own —
 // a row this recognizes is exactly a row `epic:next` and the auto-close read.
 function to_row_number(line: string): number | undefined {
-	const [issue_number] = git_epic_parse.parse_task_list_issue_numbers(line)
+	const [issue_number] = epic_parse.parse_task_list_issue_numbers(line)
 
 	return issue_number
 }
@@ -136,7 +136,7 @@ function to_placed_lines(input: RewriteInput): Array<string> {
 const DEPENDENCIES_HEADING = /^#{1,6}[ \t]+Dependencies\b/u
 
 function find_dependencies_range(input: BodyLines): SectionRange | undefined {
-	return git_epic_sections.find_section_range(input, DEPENDENCIES_HEADING)
+	return epic_sections.find_section_range(input, DEPENDENCIES_HEADING)
 }
 
 function splice_declaration(
@@ -162,7 +162,7 @@ function replace_declaration(
 	const range = find_dependencies_range(input)
 	if (range === undefined) return undefined
 
-	const found = find_indices(input, (line) => git_epic_parse.is_declaration_line(line))
+	const found = find_indices(input, (line) => epic_parse.is_declaration_line(line))
 	const declarations = found.filter((index) => is_in_range(index, range))
 	const [first] = declarations
 
@@ -182,7 +182,7 @@ function replace_declaration(
 // The unordered sentence parses to no chain, and its own constant stands in for it: that branch has no
 // numbers to render, and the sentence is a literal this module already shares with the parser.
 function to_safe_declaration(line: string): string {
-	const [rendered] = git_epic_chains.render_chains(git_epic_parse.parse_dependency_chains(line))
+	const [rendered] = epic_chains.render_chains(epic_parse.parse_dependency_chains(line))
 
 	return rendered ?? UNORDERED_DEPENDENCIES
 }
@@ -194,7 +194,7 @@ function find_stray_declaration(lines: ReadonlyArray<string>): string | undefine
 	const input = to_body_lines(lines)
 	const range = find_dependencies_range(input)
 	if (range === undefined) return undefined
-	const stray = find_indices(input, (line) => git_epic_parse.is_declaration_line(line)).find(
+	const stray = find_indices(input, (line) => epic_parse.is_declaration_line(line)).find(
 		(index) => !is_in_range(index, range),
 	)
 
@@ -212,7 +212,7 @@ function to_written_lines(input: RewriteInput): Array<string> {
 	const { decision } = input
 	if (decision === undefined) return with_rows
 
-	return git_epic_decision.append_decision(with_rows.join('\n'), decision).split('\n')
+	return epic_decision.append_decision(with_rows.join('\n'), decision).split('\n')
 }
 
 // Whether the body already declares exactly the order the caller computed, chain structure included:
@@ -222,9 +222,9 @@ function is_declaration_unchanged(
 	lines: ReadonlyArray<string>,
 	rendered: ReadonlyArray<string>,
 ): boolean {
-	const declared = git_epic_parse.parse_dependency_chains(lines.join('\n'))
+	const declared = epic_parse.parse_dependency_chains(lines.join('\n'))
 
-	return git_epic_chains.render_chains(declared).join('\n') === rendered.join('\n')
+	return epic_chains.render_chains(declared).join('\n') === rendered.join('\n')
 }
 
 // The declaration work, once the task rows and any record are in.
@@ -261,7 +261,7 @@ function to_declared_body(
 // say — the unordered sentence, since an emptied section carries no machine-readable declaration at
 // all (joshuafolkken/kit#1712).
 function to_rendered_declaration(input: RewriteInput): Array<string> {
-	const rendered = git_epic_chains.render_chains(input.chains_after)
+	const rendered = epic_chains.render_chains(input.chains_after)
 	if (rendered.length > 0) return rendered
 
 	return input.does_clear_declaration === true ? [UNORDERED_DEPENDENCIES] : []
@@ -277,7 +277,7 @@ function build_body(input: RewriteInput): BodyOutcome {
 }
 
 function to_link_keys(chains: Chains): Array<string> {
-	return git_epic_chains
+	return epic_chains
 		.links_of(chains)
 		.map((link) => format_dependency_link(link))
 		.toSorted((left, right) => left.localeCompare(right))
@@ -287,7 +287,7 @@ function to_link_keys(chains: Chains): Array<string> {
 // key lists rather than by reading the text back by eye — the round trip is the only evidence that
 // the rewrite and the parser agree.
 function has_intended_links(body: string, chains_after: Chains): boolean {
-	const written = to_link_keys(git_epic_parse.parse_dependency_chains(body))
+	const written = to_link_keys(epic_parse.parse_dependency_chains(body))
 	const intended = to_link_keys(chains_after)
 
 	return (
@@ -296,7 +296,7 @@ function has_intended_links(body: string, chains_after: Chains): boolean {
 }
 
 function missing_rows(body: string, expected: ReadonlyArray<number>): Array<number> {
-	const tracked = git_epic_parse.parse_task_list_issue_numbers(body)
+	const tracked = epic_parse.parse_task_list_issue_numbers(body)
 
 	return expected.filter((issue_number) => !tracked.includes(issue_number))
 }
@@ -319,7 +319,7 @@ function to_placement_start(position: InsertPosition, target: number, count: num
 function has_intended_rows(body: string, input: RewriteInput): boolean {
 	const { position, placed } = input
 	if (position === undefined || placed.length === 0) return true
-	const tracked = git_epic_parse.parse_task_list_issue_numbers(body)
+	const tracked = epic_parse.parse_task_list_issue_numbers(body)
 	const target = tracked.indexOf(position.target)
 	if (target === -1) return false
 	const start = to_placement_start(position, target, placed.length)
@@ -334,7 +334,7 @@ function find_rewrite_error(body: string, input: RewriteInput): string | undefin
 		return `The rewritten body would not track ${format_issue_references(missing)} as a task-list row.`
 	}
 
-	if (!git_epic_parse.has_machine_readable_declaration(body)) {
+	if (!epic_parse.has_machine_readable_declaration(body)) {
 		return 'The rewritten body would carry no unambiguous machine-readable `Dependencies` declaration.'
 	}
 
@@ -357,9 +357,9 @@ function rewrite_body(input: RewriteInput): RewriteOutcome {
 	return error === undefined ? built : { error }
 }
 
-const git_epic_add_body = {
+const epic_add_body = {
 	rewrite_body,
 }
 
-export { git_epic_add_body }
+export { epic_add_body }
 export type { RewriteInput, RewriteOutcome }

package/scripts/{git/git-epic-add-plan.ts → epic/epic-add-plan.ts}

@@ -1,10 +1,10 @@
-import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
-import { git_epic_add_body, type RewriteInput } from './git-epic-add-body'
-import { git_epic_chains, type InsertOutcome, type InsertPosition } from './git-epic-chains'
-import { git_epic_decision } from './git-epic-decision'
-import { git_epic_parse, type DependencyLink } from './git-epic-parse'
-import { format_dependency_links, to_issue_reference } from './git-epic-reference'
-import { git_epic_shape } from './git-epic-shape'
+import { epic_add_body, type RewriteInput } from './epic-add-body'
+import { epic_chains, type InsertOutcome, type InsertPosition } from './epic-chains'
+import { epic_decision } from './epic-decision'
+import { epic_graph, type EpicChild } from './epic-graph'
+import { epic_parse, type DependencyLink } from './epic-parse'
+import { format_dependency_links, to_issue_reference } from './epic-reference'
+import { epic_shape } from './epic-shape'
 
 // Everything `josh epic --add` decides before it writes anything.
 //
@@ -273,16 +273,13 @@ function to_contradicted(
 }
 
 function to_plan(context: PlanContext): PlanOutcome {
-	const { removed: replaced } = git_epic_chains.diff_links(
-		context.chains_before,
-		context.chains_after,
-	)
-	const decision = git_epic_decision.append_replacements(context.input.decision, replaced)
-	const rewritten = git_epic_add_body.rewrite_body(to_rewrite_input(context, decision))
+	const { removed: replaced } = epic_chains.diff_links(context.chains_before, context.chains_after)
+	const decision = epic_decision.append_replacements(context.input.decision, replaced)
+	const rewritten = epic_add_body.rewrite_body(to_rewrite_input(context, decision))
 	if ('error' in rewritten) return { error: rewritten.error }
 
-	const links_after = git_epic_chains.links_of(context.chains_after)
-	const result_rows = git_epic_parse.parse_task_list_issue_numbers(rewritten.body)
+	const links_after = epic_chains.links_of(context.chains_after)
+	const result_rows = epic_parse.parse_task_list_issue_numbers(rewritten.body)
 
 	return {
 		plan: {
@@ -304,7 +301,7 @@ function to_plan(context: PlanContext): PlanOutcome {
 // given because the record has to exist, so writing the insertion without it would report success for
 // half the job (joshuafolkken/kit#1350). `undefined` is "none was asked for", which is not a refusal.
 function find_decision_error(decision: string | undefined): string | undefined {
-	return decision === undefined ? undefined : git_epic_decision.find_decision_error(decision)
+	return decision === undefined ? undefined : epic_decision.find_decision_error(decision)
 }
 
 // Asked of the declaration as it stands, because a relocation's removal can collapse the very
@@ -320,7 +317,7 @@ function find_ambiguity_error(
 ): string | undefined {
 	if (input.is_order_only === true) return undefined
 
-	return git_epic_chains.find_position_ambiguity(chains_before, input.position)
+	return epic_chains.find_position_ambiguity(chains_before, input.position)
 }
 
 // The refusals about what is being placed and where: the position may not name one of the issues
@@ -355,9 +352,9 @@ function find_input_error(
 	chains_before: ReadonlyArray<ReadonlyArray<number>>,
 ): string | undefined {
 	return (
-		git_epic_shape.find_subject_error(input, tracked) ??
+		epic_shape.find_subject_error(input, tracked) ??
 		find_placement_error(input, tracked, chains_before) ??
-		find_relation_error(git_epic_chains.links_of(chains_before), input.recorded, input.repo) ??
+		find_relation_error(epic_chains.links_of(chains_before), input.recorded, input.repo) ??
 		find_decision_error(input.decision)
 	)
 }
@@ -377,10 +374,10 @@ function to_chains_after(
 	moves: { placed: ReadonlyArray<number>; relocations: ReadonlyArray<number> },
 	tracked: ReadonlyArray<number>,
 ): InsertOutcome {
-	if (input.is_order_only === true) return git_epic_chains.keep_declaration(chains_before)
+	if (input.is_order_only === true) return epic_chains.keep_declaration(chains_before)
 
-	return git_epic_chains.insert_children(
-		git_epic_chains.remove_children(chains_before, moves.relocations),
+	return epic_chains.insert_children(
+		epic_chains.remove_children(chains_before, moves.relocations),
 		moves.placed,
 		input.position,
 		tracked,
@@ -388,8 +385,8 @@ function to_chains_after(
 }
 
 function build_plan(input: PlanInput): PlanOutcome {
-	const tracked = git_epic_parse.parse_task_list_issue_numbers(input.body)
-	const chains_before = git_epic_parse.parse_dependency_chains(input.body)
+	const tracked = epic_parse.parse_task_list_issue_numbers(input.body)
+	const chains_before = epic_parse.parse_dependency_chains(input.body)
 	const error = find_input_error(input, tracked, chains_before)
 	if (error !== undefined) return { error }
 
@@ -413,9 +410,9 @@ function build_plan(input: PlanInput): PlanOutcome {
 	})
 }
 
-const git_epic_add_plan = {
+const epic_add_plan = {
 	build_plan,
 }
 
-export { git_epic_add_plan }
+export { epic_add_plan }
 export type { AddPlan, PlanInput, PlanOutcome }

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

@@ -1,16 +1,16 @@
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
-import { epic_issue } from '#scripts/epic/epic-issue'
-import { git_epic_add_plan, type AddPlan } from './git-epic-add-plan'
-import type { InsertPosition } from './git-epic-chains'
-import { git_epic_decision } from './git-epic-decision'
-import { git_epic_read, type EpicReading } from './git-epic-read'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { epic_add_plan, type AddPlan } from './epic-add-plan'
+import type { InsertPosition } from './epic-chains'
+import { epic_decision } from './epic-decision'
+import { epic_issue } from './epic-issue'
+import { epic_read, type EpicReading } from './epic-read'
 import {
 	format_issue_references,
 	format_replaced_relations,
 	to_issue_reference,
-} from './git-epic-reference'
-import { git_epic_relations } from './git-epic-relations'
-import { git_gh_command } from './git-gh-command'
+} from './epic-reference'
+import { epic_relations } from './epic-relations'
 
 // `josh epic --add <E> <N...> [--before <M> | --after <M> | --order-before <M> | --order-after <M>]
 // [--decision-file <path|->]` — insert children into an existing epic.
@@ -65,7 +65,7 @@ interface AddChildrenInput {
 function report_relations(plan: AddPlan, failures: { added: number; removed: number }): void {
 	if (plan.removed.length > 0) {
 		console.info(
-			git_epic_relations.format_relation_report({
+			epic_relations.format_relation_report({
 				links: plan.removed,
 				failures: failures.removed,
 				action: 'drop',
@@ -76,7 +76,7 @@ function report_relations(plan: AddPlan, failures: { added: number; removed: num
 	if (plan.added.length === 0) return
 
 	console.info(
-		git_epic_relations.format_relation_report({
+		epic_relations.format_relation_report({
 			links: plan.added,
 			failures: failures.added,
 			action: 'record',
@@ -87,8 +87,8 @@ function report_relations(plan: AddPlan, failures: { added: number; removed: num
 // Dropped before recorded: inserting `#N` between `#B` and `#M` replaces `#B -> #M`, and applying the
 // new link first would leave `#M` momentarily blocked by both.
 async function apply_plan(plan: AddPlan): Promise<void> {
-	const removed = await git_epic_relations.apply_relations(plan.removed, 'drop')
-	const added = await git_epic_relations.apply_relations(plan.added, 'record')
+	const removed = await epic_relations.apply_relations(plan.removed, 'drop')
+	const added = await epic_relations.apply_relations(plan.added, 'record')
 
 	report_relations(plan, { added, removed })
 }
@@ -167,7 +167,7 @@ async function comment_decision(children: ReadonlyArray<number>, decision: strin
 	)
 
 	console.info(
-		git_epic_decision.format_decision_report({
+		epic_decision.format_decision_report({
 			total: children.length,
 			failures: posted.filter((is_posted) => !is_posted).length,
 		}),
@@ -200,7 +200,7 @@ async function write_plan(input: AddChildrenInput, plan: AddPlan): Promise<void>
 // (joshuafolkken/kit#2337). Both reasons come back as a bare string the one caller prefixes `✖` onto,
 // so the two refusals read identically on stderr.
 async function read_open_epic(epic_number: number): Promise<EpicReading | { error: string }> {
-	const epic = await git_epic_read.read_epic(epic_number)
+	const epic = await epic_read.read_epic(epic_number)
 	if ('error' in epic) return epic
 	if (is_closed_epic(epic.subject.state)) return { error: closed_epic_error(epic_number) }
 
@@ -218,7 +218,7 @@ async function add_children(input: AddChildrenInput): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const outcome = git_epic_add_plan.build_plan({
+	const outcome = epic_add_plan.build_plan({
 		epic_number: input.epic_number,
 		body: epic.subject.body,
 		labels: epic.subject.labels,
@@ -241,9 +241,9 @@ async function add_children(input: AddChildrenInput): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
-const git_epic_add = {
+const epic_add = {
 	add_children,
 }
 
-export { git_epic_add }
+export { epic_add }
 export type { AddChildrenInput }

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

@@ -1,7 +1,5 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_epic_decision } from '#scripts/git/git-epic-decision'
-import { git_epic_parse, type DependencyLink } from '#scripts/git/git-epic-parse'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { issue_read } from '#scripts/issue/issue-read'
 import { epic_audit_logic, type AuditFinding, type ReferenceState } from './epic-audit'
@@ -10,10 +8,12 @@ import { epic_audit_orphans, type ClaimingSearch } from './epic-audit-orphans'
 import { epic_audit_rationale, type OrderPair } from './epic-audit-rationale'
 import { epic_audit_report, type AuditResult } from './epic-audit-report'
 import { epic_cross_repo } from './epic-cross-repo'
+import { epic_decision } from './epic-decision'
 import { epic_fetch, type EpicSnapshot } from './epic-fetch'
 import { epic_graph, type IssueReference } from './epic-graph'
 import { epic_issue } from './epic-issue'
 import { epic_next } from './epic-next'
+import { epic_parse, type DependencyLink } from './epic-parse'
 
 // `josh epic:audit <E>` — read an epic's children against each other and report what contradicts
 // what (joshuafolkken/kit#870).
@@ -278,7 +278,7 @@ async function to_audit_input(
 	epic_number: number,
 	repo: string,
 ): Promise<AuditInput> {
-	const links = git_epic_parse.parse_dependency_links(snapshot.body)
+	const links = epic_parse.parse_dependency_links(snapshot.body)
 	const order_pairs = epic_audit_rationale.order_pairs(links, children, snapshot.repo, repo)
 
 	return {
@@ -291,7 +291,7 @@ async function to_audit_input(
 		anomalies: fetch_anomalies(snapshot, children, links),
 		contradictions: epic_audit_checks.find_order_contradictions(children, repo),
 		order_pairs,
-		decisions: git_epic_decision.read_recorded_reasons(snapshot.body),
+		decisions: epic_decision.read_recorded_reasons(snapshot.body),
 		order_comments: await read_order_comments(order_pairs),
 		is_epic_closed: await read_epic_closed(epic_number, epic_fetch.scope_for(snapshot.repo, repo)),
 	}

package/scripts/epic/epic-audit-orphans.ts

@@ -1,10 +1,10 @@
-import { git_epic_parse } from '#scripts/git/git-epic-parse'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { cutoff_of, PAGE_CEILING_CAUSE, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_safe } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 import { epic_audit_logic, type AuditFinding, type FindingLevel } from './epic-audit'
 import type { EpicSnapshot } from './epic-fetch'
+import { epic_parse } from './epic-parse'
 
 // Check 4's half of `epic:audit`: an issue that names this epic as its parent but that the epic's
 // task list does not track. It would never be run, and the epic would close without it.
@@ -125,7 +125,7 @@ function claimed_numbers(search: ClaimingSearch): Array<number> {
 // reported (joshuafolkken/kit#1014). Read with the same parser `epic_fetch` reads the local rows
 // with, which never matches a `- [ ] owner/repo#N` row.
 function locally_tracked(snapshot: EpicSnapshot): Array<number> {
-	return git_epic_parse.parse_task_list_issue_numbers(snapshot.body)
+	return epic_parse.parse_task_list_issue_numbers(snapshot.body)
 }
 
 const epic_audit_orphans = {

package/scripts/epic/epic-audit-rationale.ts

@@ -1,7 +1,7 @@
-import type { DependencyLink } from '#scripts/git/git-epic-parse'
 import { epic_audit_logic, type AuditFinding } from './epic-audit'
 import type { AuditChild } from './epic-audit-checks'
 import { epic_graph, type IssueReference } from './epic-graph'
+import type { DependencyLink } from './epic-parse'
 
 // Check 6 — a declared order between two open children that nobody wrote a reason for
 // (joshuafolkken/kit#1712).

package/scripts/epic/epic-audit.ts

@@ -20,7 +20,7 @@ const REFERENCE_PATTERN = /#(\d+)\b/gu
 // What may appear in the `owner/repo` written in front of a `#`: exactly the set the previous
 // lookbehind refused a bare reference after, plus the `.` a repository name may legitimately contain.
 //
-// The dot is where this parse and the task-list parse used to disagree. `git_epic_parse`'s
+// The dot is where this parse and the task-list parse used to disagree. `epic_parse`'s
 // `EXTERNAL_REFERENCE_SOURCE` allows one, so `- [ ] owner/site.com#40` is tracked as a genuine
 // cross-repository child; this one excluded it, so a sibling quoting `owner/site.com#40` was read
 // back as `com` — no repository — and every check skipped it in silence. A child that can be tracked

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

@@ -1,7 +1,7 @@
-import { UNORDERED_DEPENDENCIES } from './git-epic-parse'
-import { DEPENDENCY_ARROW, to_issue_reference } from './git-epic-reference'
+import { UNORDERED_DEPENDENCIES } from './epic-parse'
+import { DEPENDENCY_ARROW, to_issue_reference } from './epic-reference'
 
-// The epic body is the machine-readable half of the epic contract: `scripts/git/git-epic-close.ts`
+// The epic body is the machine-readable half of the epic contract: `scripts/epic/epic-close.ts`
 // reads the task list to decide when the batch is finished, and the order-unrecorded warning reads
 // the `Dependencies` section. Generating both from the same input is what keeps them from
 // disagreeing with each other, or with the run command printed next to them.
@@ -25,7 +25,7 @@ interface EpicBodyInput {
 	epic_number?: number | undefined
 }
 
-// Task-list syntax, never a bare `#N` link: `git_epic_parse.parse_task_list_issue_numbers` matches
+// Task-list syntax, never a bare `#N` link: `epic_parse.parse_task_list_issue_numbers` matches
 // nothing else, and GitHub only auto-checks a row written this way.
 function format_progress(children: ReadonlyArray<number>): string {
 	return children.map((child) => `- [ ] ${to_issue_reference(child)}`).join('\n')
@@ -139,12 +139,12 @@ function build_dependency_pairs(
 		.filter((pair) => pair.blocked !== pair.blocker)
 }
 
-const git_epic_body = {
+const epic_body = {
 	EPIC_PLACEHOLDER,
 	build_epic_body,
 	build_dependency_pairs,
 	format_run_command,
 }
 
-export { git_epic_body, SPLIT_RATIONALE_HEADING }
+export { epic_body, SPLIT_RATIONALE_HEADING }
 export type { EpicBodyInput }

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

@@ -1,6 +1,5 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import type { IssueReference } from '#scripts/git/git-epic-reference'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
@@ -18,6 +17,7 @@ import { epic_bundle_gaps } from './epic-bundle-gaps'
 import { epic_bundle_referenced, type ReferencedContext } from './epic-bundle-referenced'
 import { epic_index, epic_schema, type FetchedEpics } from './epic-index'
 import { epic_issue } from './epic-issue'
+import type { IssueReference } from './epic-reference'
 
 // `josh epic:bundle <N>` — after an issue is filed, look at the open backlog and say whether it
 // belongs with something already there (joshuafolkken/kit#873).

package/scripts/epic/epic-bundle.ts

@@ -1,7 +1,7 @@
-import type { DependencyLink } from '#scripts/git/git-epic-parse'
-import type { IssueReference } from '#scripts/git/git-epic-reference'
 import { epic_audit_logic } from './epic-audit'
 import { epic_graph } from './epic-graph'
+import type { DependencyLink } from './epic-parse'
+import type { IssueReference } from './epic-reference'
 
 // Bundling a newly filed issue with the ones it turns out to be related to.
 //

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

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { epic_classify, type ResolveDependency } from './epic-classify'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import type { BlockersReader } from './epic-relation-recheck'
@@ -118,7 +119,7 @@ async function read_or_withhold(
 	try {
 		return await read_blockers(candidate)
 	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error)
+		const reason = error_text.message_of(error)
 
 		console.warn(
 			`⚠ could not confirm the blockers of #${String(candidate.number)}: ${reason}\n` +