@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/ci/pr-classification.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import {
 	BREAKING_CHANGE_LABEL as BREAKING,
 	BUGFIX_LABEL as BUGFIX,
@@ -7,7 +8,7 @@ import {
 	ENHANCEMENT_LABEL,
 	type ReleaseClassification,
 } from '#scripts/git/issue-labels'
-import { execaSync } from 'execa'
+import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 const CLASSIFICATION_SET: ReadonlySet<string> = new Set(CLASSIFICATION_LABELS)
@@ -95,17 +96,17 @@ function select_issue_classification(issue_json: string): ReleaseClassification
 // payload, that run fails, and when it lands in the newer check suite GitHub keeps its red result —
 // a rerun replays the same payload and fails again (joshuafolkken/kit#2712).
 function fetch_current_labels(repository: string, pull_number: number): ReadonlyArray<string> {
-	const result = execaSync(
-		'gh',
-		['api', `repos/${repository}/issues/${String(pull_number)}/labels`, '--jq', '.[].name'],
-		{ reject: false },
-	)
-
-	if (result.exitCode !== 0) {
-		throw new Error(`Could not read the pull request labels: ${result.stderr}`)
-	}
+	const path = `repos/${repository}/issues/${String(pull_number)}/labels`
+
+	try {
+		const names = git_gh_exec.exec_gh_api_sync({ path, jq_filter: '.[].name' })
 
-	return result.stdout.split('\n').filter((name) => name !== '')
+		return names.split('\n').filter((name) => name !== '')
+	} catch (error) {
+		const detail = error_text.message_of(error)
+
+		throw new Error(`Could not read the pull request labels: ${detail}`, { cause: error })
+	}
 }
 
 function check_event(
@@ -133,6 +134,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const pr_classification = {
 	classification_error,
 	check_event,
+	fetch_current_labels,
 	declaration,
 	is_classification,
 	select_issue_classification,

package/scripts/cost-runtime/cost-transcript.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 import { lane_paths } from '#scripts/lane/lane-paths'
+import { file_reader } from '#scripts/lib/read-file'
 import { cost_usage, type UsageRecord } from './cost-usage'
 
 // Finding and reading Claude Code's session transcripts (joshuafolkken/kit#962).
@@ -404,16 +405,8 @@ function tally(content: string): Omit<SessionUsage, 'session_id'> {
 	}
 }
 
-function read_text(file_path: string): string | undefined {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return undefined
-	}
-}
-
 function read_session(file: SessionFile): SessionUsage {
-	const content = read_text(file.path)
+	const content = file_reader.read_if_readable(file.path)
 
 	if (content === undefined) return { session_id: file.session_id, ...empty_session() }
 
@@ -426,7 +419,7 @@ function read_session(file: SessionFile): SessionUsage {
 // "could not be read" is already reported through `is_readable`, and throwing here would turn one
 // missing session into a failed command.
 function read_raw(file: SessionFile): string {
-	return read_text(file.path) ?? ''
+	return file_reader.read_if_readable(file.path) ?? ''
 }
 
 // The same read, with the failure left visible (joshuafolkken/kit#1439). **An unreadable transcript
@@ -435,7 +428,7 @@ function read_raw(file: SessionFile): string {
 // measured* rather than as measured at zero. `is_readable` on `SessionUsage` is the same distinction
 // on the cost side; this is it for a caller that wants the text.
 function read_optional(file: SessionFile): string | undefined {
-	return read_text(file.path)
+	return file_reader.read_if_readable(file.path)
 }
 
 // One directory the search looked in, and whether it was there to look in. `exists` tells a directory

package/scripts/delegation/delegation-policy.ts

@@ -92,6 +92,17 @@ const DELEGATABLE_STEPS: ReadonlyArray<DelegatableStep> = [
 		verifier:
 			'the parent opens the cited lines; a conclusion those lines do not support fails there, and reading a handful of cited regions costs far less than redoing the reading. The unit reports what the code does and never what to change — deciding that is `diagnosis`, which stays kept, so a unit returning a root cause would be delegating the rejected row under this name',
 	},
+	{
+		name: 'lane-failure-investigation',
+		// The `backlogrun` parent's counterpart of `investigation` (joshuafolkken/kit#2947). The parent
+		// orchestrates and never implements, yet it read a failed lane's logs, records and sources in its
+		// own context — about 150 grep / cat / sed calls on 2026-10-02 — and every later request of the
+		// batch re-read them. The verifier is `investigation`'s, and so is the boundary: the unit reports
+		// what happened, and what the parent does about it (park, re-dispatch, file) stays its own call.
+		does: "find out why a lane's child stopped, failed or conflicted — its output log, run records, PR checks and the files they name — and return the conclusion plus the `file:line` or log-line citations that support it, never the text read, so the batch parent's context stays the size its orchestration needs",
+		verifier:
+			'the parent opens the cited lines and re-reads the child with `pnpm josh issue:state`; a conclusion those do not support fails there. The unit reports what happened and never what to do — parking, re-dispatching or filing stays with the parent, so a wrong account is caught before it is acted on',
+	},
 ]
 
 // Steps that were considered and are **not** delegatable, kept as a list rather than dropped: the

package/scripts/doctor/doctor-consumer.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { safe_json_parse } from '#scripts/version/parse-json'
@@ -36,16 +37,8 @@ const STATE_TARGET_MISSING = 'target-missing'
 const STATE_MISSING = 'missing'
 type ClaudeMdState = typeof STATE_OK | typeof STATE_TARGET_MISSING | typeof STATE_MISSING
 
-function read_optional(file_path: string): string | undefined {
-	try {
-		return existsSync(file_path) ? readFileSync(file_path, 'utf8') : undefined
-	} catch {
-		return undefined
-	}
-}
-
 function parse_manifest(root: string): ManifestShape | undefined {
-	const content = read_optional(path.join(root, 'package.json'))
+	const content = file_reader.read_if_readable(path.join(root, 'package.json'))
 	if (content === undefined) return undefined
 	const parsed = manifest_schema.safeParse(safe_json_parse(content))
 
@@ -74,7 +67,7 @@ function is_kit_consumer(root: string): boolean {
 }
 
 function is_plugin_declared(root: string): boolean {
-	const content = read_optional(path.join(root, SETTINGS_PATH))
+	const content = file_reader.read_if_readable(path.join(root, SETTINGS_PATH))
 	if (content === undefined) return false
 	const parsed = settings_schema.safeParse(safe_json_parse(content))
 
@@ -94,7 +87,7 @@ function configured_hooks_path(root: string): string | undefined {
 }
 
 function claude_md_state(root: string): ClaudeMdState {
-	const content = read_optional(path.join(root, CLAUDE_MD))
+	const content = file_reader.read_if_readable(path.join(root, CLAUDE_MD))
 	if (content === undefined) return STATE_MISSING
 	if (!content.includes(CLAUDE_MD_POINTER)) return STATE_OK
 

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 },
@@ -73,46 +73,38 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/issue-comments.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/issue-fold-existing.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/needs-human-review.md', bytes: 8192 },
-	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 28_672 },
+	{ path: '.claude/skills/workflow-commands/observation-filing.md', bytes: 24_576 },
 	// `pre-gate-cut.md` left this per-document budget in joshuafolkken/kit#2289: it became a point-of-use
 	// document, so its bytes are now held by every entry's total read (`entry-read-budget.ts`) and the
 	// 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: 'docs/josh-commands.md', bytes: 184_320 },
+	{ 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/rule-delivery.md', bytes: 57_344 },
+	{ path: 'prompts/collaboration-workflow/residency.md', bytes: 28_672 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', bytes: 45_056 },
 	{ 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/turn-batching.md', bytes: 20_480 },
 	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', bytes: 12_288 },
-	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 20_480 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 16_384 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
 	{ path: 'prompts/review-rubric.md', bytes: 20_480 },
 	{ path: 'prompts/review.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

@@ -77,12 +77,13 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// planning entries): kickoff has no headroom, so the addition was offset by tightening that file's
 	// heartbeat prose, keeping every entry within its existing block.
 	// joshuafolkken/kit#2762 moved the rationale of five point-of-use documents to
-	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction.
+	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction. joshuafolkken/kit#2895 did
+	// the same for eight more, lowering fullrun, halfrun and backlogrun one block each.
 	{ entry: 'kickoff', bytes: 229_376 },
-	{ entry: 'fullrun', bytes: 229_376 },
-	{ entry: 'halfrun', bytes: 229_376 },
-	{ entry: 'backlogrun', bytes: 233_472 },
-	{ entry: LANE_CHILD, bytes: 81_920 },
+	{ entry: 'fullrun', bytes: 225_280 },
+	{ entry: 'halfrun', bytes: 225_280 },
+	{ entry: 'backlogrun', bytes: 229_376 },
+	{ 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 }