@joshuafolkken/kit 1.872.0

package/scripts/git/git-epic-remove.ts

@@ -0,0 +1,101 @@
+import { git_epic_decision } from './git-epic-decision'
+import { git_epic_read } from './git-epic-read'
+import { format_dependency_links } from './git-epic-reference'
+import { git_epic_relations } from './git-epic-relations'
+import { git_epic_remove_plan, type RemovePlan } from './git-epic-remove-plan'
+import { git_gh_command } from './git-gh-command'
+
+// `josh epic --remove <E> <M> <N> [<N2> ...] [--decision-file <path|->]` — delete a declared order
+// from the epic's body and from the native `blocked-by` relations in one input
+// (joshuafolkken/kit#1712).
+//
+// It is `--add`'s missing counterpart. `--add` exists because writing the declaration and the
+// relations separately is what leaves them disagreeing; deleting them separately leaves them
+// disagreeing in exactly the same way, and there was no command for it at all — so the only route
+// was the hand edit `CLAUDE.md` forbids, twenty-nine times over on epic joshuafolkken/kit#1262.
+
+const FAILURE_EXIT_CODE = 1
+const SUCCESS_EXIT_CODE = 0
+
+interface RemoveOrderInput {
+	epic_number: number
+	path: ReadonlyArray<number>
+	decision?: string | undefined
+}
+
+// The record is posted on **both ends** of every deleted order, not on one of them. Whoever later
+// asks why `#B` is no longer waiting on `#A` may be reading either issue, and a record on one of
+// them is a record the other reader never sees.
+async function comment_decision(ends: ReadonlyArray<number>, decision: string): Promise<void> {
+	const posted = await Promise.all(
+		ends.map(async (end) => await git_gh_command.issue_try_comment(String(end), decision)),
+	)
+
+	console.info(
+		git_epic_decision.format_decision_report({
+			total: ends.length,
+			failures: posted.filter((is_posted) => !is_posted).length,
+		}),
+	)
+}
+
+function report_relations(plan: RemovePlan, failures: number): void {
+	if (plan.removed.length === 0) return
+
+	console.info(
+		git_epic_relations.format_relation_report({ links: plan.removed, failures, action: 'drop' }),
+	)
+}
+
+async function write_plan(
+	epic_number: number,
+	plan: RemovePlan,
+	decision: string | undefined,
+): Promise<void> {
+	await git_gh_command.issue_edit_body(String(epic_number), plan.body)
+	console.info(
+		`📋 Removed ${format_dependency_links(plan.links)} from epic #${String(epic_number)}.`,
+	)
+	report_relations(plan, await git_epic_relations.apply_relations(plan.removed, 'drop'))
+
+	if (decision !== undefined) await comment_decision(plan.ends, decision)
+}
+
+// Delete a declared order, or refuse without writing anything. Every refusal happens before the body
+// edit, so a rejected invocation leaves the epic exactly as it was.
+async function remove_order(input: RemoveOrderInput): Promise<number> {
+	const epic = await git_epic_read.read_epic(input.epic_number)
+
+	if ('error' in epic) {
+		console.error(`✖ ${epic.error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const outcome = git_epic_remove_plan.build_removal_plan({
+		epic_number: input.epic_number,
+		body: epic.subject.body,
+		labels: epic.subject.labels,
+		path: input.path,
+		recorded: epic.recorded,
+		repo: epic.repo,
+		decision: input.decision,
+	})
+
+	if ('error' in outcome) {
+		console.error(`✖ ${outcome.error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	await write_plan(input.epic_number, outcome.plan, input.decision)
+
+	return SUCCESS_EXIT_CODE
+}
+
+const git_epic_remove = {
+	remove_order,
+}
+
+export { git_epic_remove }
+export type { RemoveOrderInput }

package/scripts/git/git-epic-run.ts

@@ -0,0 +1,223 @@
+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'
+
+const EPIC_LABEL_COLOR = '#5319e7'
+const EPIC_LABEL_DESCRIPTION = 'Tracks a batch of child issues from one split'
+const FAILURE_EXIT_CODE = 1
+const SUCCESS_EXIT_CODE = 0
+
+interface CreateEpicInput {
+	title: string
+	children: ReadonlyArray<number>
+	rationale: string
+	is_ordered: boolean
+	origin?: string | undefined
+}
+
+// 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.
+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)
+	if (pairs.length === 0) return
+
+	const failures = await git_epic_relations.apply_relations(pairs, 'record')
+
+	console.info(
+		git_epic_relations.format_relation_report({
+			links: pairs,
+			failures,
+			action: 'record',
+		}),
+	)
+}
+
+// The epic's own number, from the URL `gh issue create` prints. Needed because the run command in
+// the body names the epic, and the number only exists once the issue does.
+const ISSUE_URL_NUMBER = /\/(?<number>\d+)\s*$/u
+
+function parse_created_number(url: string): number | undefined {
+	const { groups } = ISSUE_URL_NUMBER.exec(url.trim()) ?? {}
+	const { number: raw } = groups ?? {}
+	if (raw === undefined) return undefined
+	const parsed = Number(raw)
+
+	return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+// Rewrite the body once the number is known, so `## Execution` carries a command that can be run as
+// written rather than a placeholder. A failure here costs the substitution and nothing else — the
+// epic and its task list are already correct, and nothing machine-readable lives in that section.
+async function fill_run_command(
+	epic_number: number | undefined,
+	input: CreateEpicInput,
+): 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)}\`.`,
+		)
+
+		return
+	}
+
+	try {
+		await git_gh_command.issue_edit_body(
+			String(epic_number),
+			git_epic_body.build_epic_body({
+				children: input.children,
+				rationale: input.rationale,
+				is_ordered: input.is_ordered,
+				origin: input.origin,
+				epic_number,
+			}),
+		)
+	} catch {
+		console.info('⚠️  Could not substitute the epic number into the Execution section.')
+	}
+}
+
+async function create_epic(input: CreateEpicInput): Promise<number> {
+	await git_gh_command.label_ensure({
+		name: EPIC_LABEL,
+		color: EPIC_LABEL_COLOR,
+		description: EPIC_LABEL_DESCRIPTION,
+	})
+
+	const body = git_epic_body.build_epic_body({
+		children: input.children,
+		rationale: input.rationale,
+		is_ordered: input.is_ordered,
+		origin: input.origin,
+	})
+
+	const url = await git_gh_command.issue_create_with_label({
+		title: input.title,
+		label: EPIC_LABEL,
+		body,
+	})
+	const epic_number = parse_created_number(url)
+
+	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)}`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+interface PromoteEpicInput {
+	epic_number: number
+	children: ReadonlyArray<number>
+	rationale: string
+	is_ordered: boolean
+	origin?: string | undefined
+}
+
+// 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(
+		await git_gh_command.issue_get_labels_and_body(String(epic_number)),
+	)
+
+	if (subject === undefined) {
+		console.error(`✖ Could not read issue #${String(epic_number)}.`)
+
+		return undefined
+	}
+
+	if (git_epic_promote.has_conflicting_tracking(subject.body)) {
+		const reason = git_epic_promote.conflict_reason(subject.body)
+
+		console.error(`✖ Cannot promote #${String(epic_number)}: ${reason}.`)
+
+		return undefined
+	}
+
+	return subject
+}
+
+// Write the promoted body and apply the label. The label is what `git-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 tracking_error = git_epic_promote.find_tracking_error(body, input.children)
+
+	if (tracking_error !== undefined) {
+		console.error(`✖ ${tracking_error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	await git_gh_command.issue_edit_body(String(input.epic_number), body)
+
+	if (await git_gh_command.issue_add_label(String(input.epic_number), EPIC_LABEL)) {
+		return SUCCESS_EXIT_CODE
+	}
+
+	console.error(
+		`✖ Wrote the epic sections to #${String(input.epic_number)} but could not apply the \`${EPIC_LABEL}\` label; apply it by hand.`,
+	)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Promote an existing issue into an epic: append the epic sections, apply the label, and record the
+// dependency relations exactly as a new epic would.
+async function promote_epic(input: PromoteEpicInput): Promise<number> {
+	const subject = await read_promotion_subject(input.epic_number)
+	if (subject === undefined) return FAILURE_EXIT_CODE
+
+	await git_gh_command.label_ensure({
+		name: EPIC_LABEL,
+		color: EPIC_LABEL_COLOR,
+		description: EPIC_LABEL_DESCRIPTION,
+	})
+	const written = await write_promotion(input, subject.body)
+	if (written !== SUCCESS_EXIT_CODE) return written
+
+	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)}`)
+
+	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)
+
+	if (subject === undefined) {
+		console.error(`✖ Could not read issue #${String(epic_number)}.`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const results = git_epic_validate.validate_epic(subject)
+
+	console.info(git_epic_validate.format_check_report(subject.number, results))
+
+	return git_epic_validate.is_epic_valid(results) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+const git_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 type { CreateEpicInput, PromoteEpicInput }

package/scripts/git/git-epic-sections.ts

@@ -0,0 +1,98 @@
+import { git_epic_parse } from './git-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
+// 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
+// a copy that forgot it would append a decision into a quoted template (joshuafolkken/kit#1350).
+//
+// Nothing here writes. The two consumers decide what to do with a range; this decides where one is.
+
+// A heading of any level, with its `#` run captured so the level can be compared. Read from the
+// trimmed line, so an indented heading inside a list still counts as one.
+const ANY_HEADING = /^(#{1,6})[ \t]/u
+const HEADING_LEVEL_GROUP = 1
+const NOT_A_HEADING = 0
+
+interface BodyLines {
+	lines: ReadonlyArray<string>
+	// `false` for a fence line and everything between a pair of them. A heading or a declaration
+	// inside a fenced block is an illustration, and treating one as real would edit a quoted template.
+	mask: ReadonlyArray<boolean>
+}
+
+interface SectionRange {
+	// The first line after the heading, and the first line of whatever follows the section.
+	start: number
+	end: number
+}
+
+// Accepts the body or the lines it was already split into: `git-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')) }
+}
+
+function is_readable(input: BodyLines, index: number): boolean {
+	return input.mask[index] === true
+}
+
+function find_indices(input: BodyLines, is_wanted: (line: string) => boolean): Array<number> {
+	return input.lines
+		.map((line, index) => (is_readable(input, index) && is_wanted(line) ? index : -1))
+		.filter((index) => index !== -1)
+}
+
+// A line's heading level, or `0` for a line that is not a heading.
+function heading_level(line: string): number {
+	return (ANY_HEADING.exec(line.trim())?.[HEADING_LEVEL_GROUP] ?? '').length
+}
+
+// Whether this line closes a section opened at `level`: a readable heading of the same level or a
+// higher one. A deeper heading belongs to the section rather than ending it.
+function is_section_end(input: BodyLines, index: number, level: number): boolean {
+	if (!is_readable(input, index)) return false
+	const found = heading_level(input.lines[index] ?? '')
+
+	return found !== NOT_A_HEADING && found <= level
+}
+
+// Where the named section runs: the lines after its heading, up to the next heading **of the same or a
+// higher level**. Not "the next heading of any level" — `## Decisions` is written as one `###` entry per
+// decision, the template the epic body documents, so ending at any heading would make the section one
+// line long and place every appended record after its first entry (joshuafolkken/kit#1350). A `##`
+// section running to the next `##` is what a reader of the body already takes it to mean.
+//
+// `undefined` is "the body has no such section", which is a different answer from an empty one — the
+// caller creates the section in the first case and appends inside it in the second.
+function find_section_range(input: BodyLines, heading: RegExp): SectionRange | undefined {
+	const [found] = find_indices(input, (line) => heading.test(line.trim()))
+	if (found === undefined) return undefined
+
+	const level = heading_level(input.lines[found] ?? '')
+	const start = found + 1
+	const next = input.lines
+		.slice(start)
+		.findIndex((_line, offset) => is_section_end(input, start + offset, level))
+
+	return { start, end: next === -1 ? input.lines.length : start + next }
+}
+
+function is_in_range(index: number, range: SectionRange): boolean {
+	return index >= range.start && index < range.end
+}
+
+const git_epic_sections = {
+	to_body_lines,
+	find_indices,
+	find_section_range,
+	is_in_range,
+}
+
+export { git_epic_sections }
+export type { BodyLines, SectionRange }

package/scripts/git/git-epic-shape.ts

@@ -0,0 +1,81 @@
+import { git_epic_parse } from './git-epic-parse'
+import { to_issue_reference } from './git-epic-reference'
+import { EPIC_LABEL } from './issue-labels'
+
+// Whether an issue is an epic this repository's writers may edit, and why it is not when it is not.
+//
+// Both `josh epic --add` and `josh epic --remove` ask exactly this before they compute anything: the
+// label, the absence of a cross-repository child, a task list to place rows in, and a declaration
+// their edit can be relative to. It lives in one module rather than in each of them, because the two
+// commands must refuse the same inputs for the same reasons — a second copy is where one comes to
+// accept an epic the other refuses (joshuafolkken/kit#1712).
+
+// The part of an epic these refusals read. Narrower than either command's own input on purpose: a
+// shape check that could see the children being placed would invite conditions that belong to the
+// caller.
+interface EpicShapeSubject {
+	epic_number: number
+	body: string | undefined
+	labels: ReadonlyArray<string>
+}
+
+function missing_declaration_error(epic_number: number): string {
+	const check = `josh epic:check ${String(epic_number)}`
+
+	return `${to_issue_reference(epic_number)} has no unambiguous machine-readable \`Dependencies\` declaration; run \`${check}\` first.`
+}
+
+// What to do about a target that is not an epic. The refusal is deliberate — neither command ever
+// promotes an issue on its own, because promotion rewrites someone's issue into a container and the
+// choice between promoting and creating a new epic depends on what the target *is*, which only a
+// reader of it knows (`.claude/skills/workflow-commands/split-assessment.md` → promote-or-create).
+// Naming both arms is what keeps the refusal one command away from being actionable rather than a
+// dead end, which is the whole point of `into <target>` (joshuafolkken/kit#985).
+function promote_remedy(epic_number: number): string {
+	const promote = `josh epic --promote ${String(epic_number)} <N...>`
+
+	return `Promote it with \`${promote}\` when it is a request, a discussion or a container; create a new epic over both when it is itself one of the deliverables.`
+}
+
+// The label and the task list are checked separately from the declaration because they fail
+// differently: without rows there is nowhere to put a new one, and without a declaration there is
+// nothing for an edit to be relative to.
+function find_epic_shape_error(subject: EpicShapeSubject, body: string): string | undefined {
+	const reference = to_issue_reference(subject.epic_number)
+
+	if (!subject.labels.includes(EPIC_LABEL)) {
+		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)) {
+		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.`
+	}
+
+	return undefined
+}
+
+function find_subject_error(
+	subject: EpicShapeSubject,
+	tracked: ReadonlyArray<number>,
+): string | undefined {
+	const reference = to_issue_reference(subject.epic_number)
+	if (subject.body === undefined) return `Could not read the body of ${reference}.`
+	const shape_error = find_epic_shape_error(subject, subject.body)
+	if (shape_error !== undefined) return shape_error
+
+	if (tracked.length === 0) {
+		return `${reference} tracks no child as a \`- [ ] #N\` row; there is nowhere to add one.`
+	}
+
+	// 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)
+		? undefined
+		: missing_declaration_error(subject.epic_number)
+}
+
+const git_epic_shape = {
+	find_subject_error,
+}
+
+export { git_epic_shape }
+export type { EpicShapeSubject }

package/scripts/git/git-epic-validate.ts

@@ -0,0 +1,155 @@
+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'
+
+// 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
+// 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
+// "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
+	// 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
+	labels: ReadonlyArray<string>
+	body: string | undefined
+}
+
+interface CheckResult {
+	name: string
+	is_passing: boolean
+	detail: string
+}
+
+// The `number,labels,body` read's answer, as the shape every epic writer reads. It lives beside
+// the checks because `EpicSubject` is defined here, and each command that wanted one had otherwise
+// to restate the unwrapping (joshuafolkken/kit#890).
+function parse_epic_subject(raw_json: string | undefined): EpicSubject | undefined {
+	if (raw_json === undefined) return undefined
+
+	const parsed = parse_json_object_safe(raw_json, epic_subject_schema)
+	if (parsed === undefined) return undefined
+
+	return {
+		number: parsed.number,
+		state: parsed.state,
+		labels: (parsed.labels ?? []).map((label) => label.name),
+		body: parsed.body,
+	}
+}
+
+// The membership test is `has_label_name` rather than `Array.includes` because GitHub keeps the
+// casing a label was created with and treats `Epic` and `epic` as one label. Compared literally, a
+// repository that predates these scripts was told to *add* a label it already carries — and GitHub
+// then refuses the addition as a duplicate, so the instruction could not be followed either.
+function check_label(subject: EpicSubject): CheckResult {
+	const is_passing = has_label_name(subject.labels, EPIC_LABEL)
+
+	return {
+		name: 'epic label',
+		is_passing,
+		detail: is_passing
+			? `the \`${EPIC_LABEL}\` label is applied`
+			: `add the \`${EPIC_LABEL}\` label — the auto-close only looks at labelled issues`,
+	}
+}
+
+function format_children(children: ReadonlyArray<number>): string {
+	return children.map((child) => `#${String(child)}`).join(', ')
+}
+
+function check_task_list(subject: EpicSubject): CheckResult {
+	const children = git_epic_parse.parse_task_list_issue_numbers(subject.body)
+	const is_passing = children.length > 0
+
+	return {
+		name: 'child task list',
+		is_passing,
+		detail: is_passing
+			? `${String(children.length)} child issue(s) tracked: ${format_children(children)}`
+			: 'no `- [ ] #N` rows found — a bare `#N` link is not tracked and never auto-closes',
+	}
+}
+
+function describe_dependencies(state: DeclarationState): string {
+	if (state.has_chain && state.has_none_literal) {
+		return 'a chain (`#N -> #M`) and the `None — ...` literal are both declared; they contradict each other'
+	}
+
+	if (state.has_chain) return 'an ordered chain (`#N -> #M`) is declared'
+	if (state.has_none_literal) return 'declared as an unordered batch'
+
+	return 'neither a line that is only `#N -> #M` nor the `None — ...` literal found; an arrow sharing its line with anything else is prose, and prose order is not machine-readable'
+}
+
+// An unordered batch is a legitimate state, so the absence of a chain is not a failure by itself.
+// What this reports is the two states a reader cannot act on: neither form present, so "no order"
+// and "the order was never written down" are indistinguishable, and both present, so the body says
+// 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)
+
+	return {
+		name: 'dependencies section',
+		is_passing: git_epic_parse.is_declaration_readable(state),
+		detail: describe_dependencies(state),
+	}
+}
+
+// A cross-repository child cannot be resolved without a different `--repo`, so the auto-close
+// 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)
+
+	return {
+		name: 'auto-close eligibility',
+		is_passing: !has_external,
+		detail: has_external
+			? 'tracks a child in another repository — this epic will not auto-close; close it manually'
+			: 'every tracked child is in this repository',
+	}
+}
+
+function validate_epic(subject: EpicSubject): Array<CheckResult> {
+	return [
+		check_label(subject),
+		check_task_list(subject),
+		check_dependencies(subject),
+		check_external_children(subject),
+	]
+}
+
+function is_epic_valid(results: ReadonlyArray<CheckResult>): boolean {
+	return results.every((result) => result.is_passing)
+}
+
+function format_check_line(result: CheckResult): string {
+	return `${result.is_passing ? '✔' : '✖'} ${result.name} — ${result.detail}`
+}
+
+function format_check_report(epic_number: number, results: ReadonlyArray<CheckResult>): string {
+	const lines = results.map((result) => format_check_line(result))
+	const summary = is_epic_valid(results)
+		? `✅ Epic #${String(epic_number)} satisfies every requirement.`
+		: `❌ Epic #${String(epic_number)} does not satisfy every requirement.`
+
+	return [...lines, '', summary].join('\n')
+}
+
+const git_epic_validate = {
+	parse_epic_subject,
+	validate_epic,
+	is_epic_valid,
+	format_check_report,
+}
+
+export { git_epic_validate }
+export type { CheckResult, EpicSubject }