@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,73 @@
+import { epic_fetch } from '#scripts/epic/epic-fetch'
+import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
+import { git_epic_parse } from './git-epic-parse'
+import { git_epic_validate, type EpicSubject } from './git-epic-validate'
+import { git_gh_command } from './git-gh-command'
+
+// Reading an epic and its current graph, for the two commands that edit its declared order.
+//
+// `--add` and `--remove` need exactly the same three things before they may compute anything: the
+// epic's labels and body, the repository a declared bare number names, and every child with its
+// native relations. They were the same forty lines twice until joshuafolkken/kit#1712 gave the
+// removal a home; a second copy is where one of them comes to accept a graph the other refuses.
+
+// Refused rather than stood in for, and both callers *write*. Since joshuafolkken/kit#1126 a plan
+// filters recorded relations by the declared repository, so a placeholder drops every one of them:
+// the "reconcile them before inserting" guard never fires, the superseded link is never dropped, and
+// relations that already exist are re-POSTed — leaving the epic in exactly the mismatched state
+// `epic:audit` refuses to run on.
+const UNKNOWN_REPO =
+	"Could not read this repository from `git remote`, so the epic's relations cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote."
+
+interface EpicReading {
+	subject: EpicSubject
+	recorded: ReadonlyArray<EpicChild>
+	repo: string
+}
+
+async function read_subject(epic_number: number): Promise<EpicSubject | undefined> {
+	return git_epic_validate.parse_epic_subject(
+		await git_gh_command.issue_get_labels_and_body(String(epic_number)),
+	)
+}
+
+// The current children with their native relations. A child that cannot be read stops the command
+// for the reason it stops `epic:next`: a missing node makes whatever it blocks look unblocked, and
+// an edit computed against that graph would record or drop the wrong order.
+async function read_recorded(
+	body: string | undefined,
+): Promise<{ children: ReadonlyArray<EpicChild>; repo: string } | { error: string }> {
+	const repo = await git_gh_command.repo_get_name_with_owner()
+	if (repo === undefined) return { error: UNKNOWN_REPO }
+	const tracked = git_epic_parse.parse_task_list_issue_numbers(body)
+	if (tracked.length === 0) return { children: [], repo }
+
+	const fetched = await epic_fetch.fetch_children(tracked, repo)
+
+	if (fetched.unreadable.length > 0) {
+		const list = epic_graph.format_references(fetched.unreadable, repo)
+
+		return { error: `Could not read ${list}; the epic's dependency graph is incomplete.` }
+	}
+
+	return { children: fetched.children, repo }
+}
+
+// The epic and its current graph, or the reason neither could be read.
+async function read_epic(epic_number: number): Promise<EpicReading | { error: string }> {
+	const subject = await read_subject(epic_number)
+	if (subject === undefined) return { error: `Could not read issue #${String(epic_number)}.` }
+
+	const recorded = await read_recorded(subject.body)
+	if ('error' in recorded) return { error: recorded.error }
+
+	return { subject, recorded: recorded.children, repo: recorded.repo }
+}
+
+const git_epic_read = {
+	UNKNOWN_REPO,
+	read_epic,
+}
+
+export { git_epic_read }
+export type { EpicReading }

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

@@ -0,0 +1,246 @@
+import { epic_graph, type EpicChild, type IssueReference } from '#scripts/epic/epic-graph'
+import { git_epic_add_body } from './git-epic-add-body'
+import { git_epic_chains } from './git-epic-chains'
+import { git_epic_parse, type DependencyLink } from './git-epic-parse'
+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_gh_command } from './git-gh-command'
+
+// `josh epic --reconcile <E>` — bring an epic's `## Dependencies` declaration and its native
+// `blocked-by` relations back into agreement, without a hand edit and without recording a decision
+// (joshuafolkken/kit#2235).
+//
+// `--add` and `--remove` refuse the moment the two disagree, and `backlog:next` reports the graph
+// unusable, so the only exit was to edit the epic body by hand — the very edit those commands exist
+// to remove. There is no judgement in the repair: a relation recorded but never declared is written
+// into the declaration (the relation is the GitHub-side fact, the body its copy), and an order
+// declared but never recorded is aligned by recording it. The result declares exactly what it
+// records, which is what `epic:audit` and `backlog:next` read.
+//
+// **It writes no `## Decisions`.** Synchronizing a copy is not a decision — there is no judgement to
+// record — so the body edit carries the declaration alone, unlike `--add` / `--remove` whose
+// `--decision-file` half rides on the same edit.
+
+const FAILURE_EXIT_CODE = 1
+const SUCCESS_EXIT_CODE = 0
+
+const NOTHING_TO_RECONCILE = 'nothing to reconcile'
+
+// The verdict the success path leads with, so a reader distinguishes a repair from a no-op by the
+// token rather than by the exit code alone. The `lane:list` oracle reads its vocabulary from the
+// emitting module the same way (`lane_occupancy`).
+const RECONCILED = 'reconciled'
+
+interface ReconcilePlanInput {
+	body: string | undefined
+	// The epic's children with their native relations, exactly as `git_epic_read` reads them.
+	recorded: ReadonlyArray<EpicChild>
+	// The epic's own repository — what a declared bare number names (joshuafolkken/kit#1126).
+	repo: string
+}
+
+// What the repair will write. `declare` are relations recorded but never declared — added to the
+// body; `record` are orders declared but never recorded — written as `blocked-by`. A `body` of
+// `undefined` means only relations changed, so the body is left byte-identical.
+interface Reconciliation {
+	body: string | undefined
+	declare: ReadonlyArray<DependencyLink>
+	record: ReadonlyArray<DependencyLink>
+}
+
+type ReconcilePlan =
+	| { kind: 'nothing' }
+	| { kind: 'cycle'; message: string }
+	| { kind: 'reconciled'; reconciliation: Reconciliation }
+	| { kind: 'error'; error: string }
+
+function to_chain(link: DependencyLink): Array<number> {
+	return [link.blocker, link.blocked]
+}
+
+// A blocker of `blocked`, keyed to the epic's own repository so a declared bare number names the
+// right issue (joshuafolkken/kit#1126).
+function to_blocker(link: DependencyLink, repo: string): IssueReference {
+	return { repo, number: link.blocker }
+}
+
+// The union link set as children, so the shared cycle check can read it. Each node carries the
+// blockers the union records; an isolated node carries none and can never be stuck.
+function to_children(links: ReadonlyArray<DependencyLink>, repo: string): Array<EpicChild> {
+	const blockers = new Map<number, Array<IssueReference>>()
+
+	for (const link of links) {
+		blockers.set(link.blocked, [...(blockers.get(link.blocked) ?? []), to_blocker(link, repo)])
+	}
+
+	const numbers = new Set(links.flatMap((link) => [link.blocker, link.blocked]))
+
+	return [...numbers].map((number) => ({
+		number,
+		repo,
+		state: 'OPEN' as const,
+		labels: [],
+		blocked_by: blockers.get(number) ?? [],
+	}))
+}
+
+// Whether the union of declared and recorded orders is circular, read through the one anomaly finder
+// `epic:next` uses rather than a second cycle walk. With the children built from the links, only a
+// cycle can surface — the declaration and the relations are equal by construction.
+function find_cycle(links: ReadonlyArray<DependencyLink>, repo: string): string | undefined {
+	const anomalies = epic_graph.find_anomalies(to_children(links, repo), links, true, repo)
+
+	return anomalies.find((anomaly) => anomaly.kind === 'cycle')?.message
+}
+
+// The body that declares the union order, or the reason it could not be written. Reuses the insertion
+// rewriter with no rows and no decision, so "declare these links" goes through the one code path that
+// already rewrites `## Dependencies` and verifies the round trip.
+function to_reconciled_body(
+	body: string | undefined,
+	target_chains: ReadonlyArray<ReadonlyArray<number>>,
+): { body: string } | { error: string } {
+	return git_epic_add_body.rewrite_body({
+		body: body ?? '',
+		placed: [],
+		position: undefined,
+		chains_after: target_chains,
+		decision: undefined,
+	})
+}
+
+// The two-directional difference between what the body declares and what the relations record, with
+// the chains the body already carries. `declare` are relations recorded but never declared; `record`
+// are orders declared but never recorded.
+interface Mismatch {
+	chains_before: ReadonlyArray<ReadonlyArray<number>>
+	declare: ReadonlyArray<DependencyLink>
+	record: ReadonlyArray<DependencyLink>
+}
+
+function read_mismatch(input: ReconcilePlanInput): Mismatch {
+	const chains_before = git_epic_parse.parse_dependency_chains(input.body)
+	const declared = git_epic_chains.links_of(chains_before)
+
+	return {
+		chains_before,
+		declare: epic_graph.undeclared_relations(declared, input.recorded, input.repo),
+		record: epic_graph.missing_relations(declared, input.recorded, input.repo),
+	}
+}
+
+// The reconciliation for a non-empty mismatch: refuse a cycle, record alone when only relations are
+// missing, and otherwise rewrite the body to declare the union order.
+function to_reconciled_plan(input: ReconcilePlanInput, mismatch: Mismatch): ReconcilePlan {
+	const declared_chains = mismatch.declare.map((link) => to_chain(link))
+	const target_chains = [...mismatch.chains_before, ...declared_chains]
+	const cycle = find_cycle(git_epic_chains.links_of(target_chains), input.repo)
+	if (cycle !== undefined) return { kind: 'cycle', message: cycle }
+
+	const { declare, record } = mismatch
+
+	if (declare.length === 0) {
+		return { kind: 'reconciled', reconciliation: { body: undefined, declare, record } }
+	}
+
+	const rewritten = to_reconciled_body(input.body, target_chains)
+	if ('error' in rewritten) return { kind: 'error', error: rewritten.error }
+
+	return { kind: 'reconciled', reconciliation: { body: rewritten.body, declare, record } }
+}
+
+function build_reconcile_plan(input: ReconcilePlanInput): ReconcilePlan {
+	const mismatch = read_mismatch(input)
+	if (mismatch.declare.length === 0 && mismatch.record.length === 0) return { kind: 'nothing' }
+
+	return to_reconciled_plan(input, mismatch)
+}
+
+// The one line the acceptance asks the repair to state itself: after this, the two readers that
+// refused the mismatched epic agree on its order.
+function report_agreement(epic_number: number): void {
+	console.info(
+		`${RECONCILED} #${String(epic_number)} — epic:audit and backlog:next now agree on this epic's order.`,
+	)
+}
+
+function report_declared(epic_number: number, declare: ReadonlyArray<DependencyLink>): void {
+	if (declare.length === 0) return
+
+	console.info(
+		`📋 Declared ${format_dependency_links(declare)} in epic #${String(epic_number)} to match the recorded relations.`,
+	)
+}
+
+async function record_relations(record: ReadonlyArray<DependencyLink>): Promise<void> {
+	if (record.length === 0) return
+
+	const failures = await git_epic_relations.apply_relations(record, 'record')
+
+	console.info(
+		git_epic_relations.format_relation_report({ links: record, failures, action: 'record' }),
+	)
+}
+
+async function apply_reconciliation(
+	epic_number: number,
+	reconciliation: Reconciliation,
+): Promise<number> {
+	if (reconciliation.body !== undefined) {
+		await git_gh_command.issue_edit_body(String(epic_number), reconciliation.body)
+	}
+
+	report_declared(epic_number, reconciliation.declare)
+	await record_relations(reconciliation.record)
+	report_agreement(epic_number)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function apply_plan(epic_number: number, plan: ReconcilePlan): Promise<number> {
+	if (plan.kind === 'nothing') {
+		console.info(NOTHING_TO_RECONCILE)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	if (plan.kind === 'reconciled') {
+		return await apply_reconciliation(epic_number, plan.reconciliation)
+	}
+
+	console.error(`✖ ${plan.kind === 'cycle' ? plan.message : plan.error}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Reconcile an epic's declaration with its recorded relations, or refuse without writing anything.
+// Every refusal — an unreadable epic, an unreadable graph, a cycle — happens before the body edit,
+// so a rejected invocation leaves the epic exactly as it was.
+async function reconcile_epic(epic_number: number): Promise<number> {
+	const epic = await git_epic_read.read_epic(epic_number)
+
+	if ('error' in epic) {
+		console.error(`✖ ${epic.error}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const plan = build_reconcile_plan({
+		body: epic.subject.body,
+		recorded: epic.recorded,
+		repo: epic.repo,
+	})
+
+	return await apply_plan(epic_number, plan)
+}
+
+const git_epic_reconcile = {
+	NOTHING_TO_RECONCILE,
+	RECONCILED,
+	build_reconcile_plan,
+	reconcile_epic,
+}
+
+export { git_epic_reconcile }
+export type { ReconcilePlan, ReconcilePlanInput, Reconciliation }

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

@@ -0,0 +1,98 @@
+import type { DependencyLink } from './git-epic-parse'
+
+// How an issue and a dependency between two of them are written down.
+//
+// Both spellings had accumulated a copy per module — the body generator, the graph, the chain model
+// and the insertion planner each rendered `#N` and `#B -> #M` themselves. They are one-liners, which
+// is exactly why the copies spread; and a link rendered one way in a message and another way as a
+// dedup key is a difference nothing would report (joshuafolkken/kit#890).
+
+const DEPENDENCY_ARROW = ' -> '
+// How a list of references is written out. One definition rather than a `join` per caller: the
+// repository-aware list in `epic-graph` renders the same kind of list from a different element type,
+// and two separators would let the two disagree over something a reader reads side by side.
+const REFERENCE_SEPARATOR = ', '
+
+// An issue named from outside any one graph — a task-list row, a citation in prose, a blocker
+// relation, a child that could not be read. Repository **and** number, because a number alone cannot
+// identify one: issue numbers are unique per repository, so the same `#40` names two different issues
+// depending on who wrote it (joshuafolkken/kit#1014).
+//
+// It lives here rather than in `epic-graph` because the `blocked-by` relations are read in the git
+// layer and carry a repository of their own (joshuafolkken/kit#1126) — a second declaration there
+// would be the clone `CLAUDE.md` prohibits, and an import the other way would point the lower layer
+// at the higher one. `epic-graph` re-exports it, so every existing importer is unchanged.
+//
+// `state` is present only on a reference read from a `blocked-by` relation whose response carried it
+// (joshuafolkken/kit#1943). The classifier needs it for a blocker no named graph tracks, where there is
+// no child record to read the state from; every other reference leaves it out.
+interface IssueReference {
+	repo: string
+	number: number
+	state?: 'OPEN' | 'CLOSED'
+}
+
+function to_issue_reference(issue_number: number): string {
+	return `#${String(issue_number)}`
+}
+
+function format_dependency_link(link: DependencyLink): string {
+	return `${to_issue_reference(link.blocker)}${DEPENDENCY_ARROW}${to_issue_reference(link.blocked)}`
+}
+
+function join_references(references: ReadonlyArray<string>): string {
+	return references.join(REFERENCE_SEPARATOR)
+}
+
+// A list of links, in the same form a single one takes. One definition rather than a `map().join()`
+// per caller: the insertion planner and the relation reporter now print the same list side by side,
+// and two spellings of it would read as two different things (joshuafolkken/kit#1080).
+function format_dependency_links(links: ReadonlyArray<DependencyLink>): string {
+	return join_references(links.map((link) => format_dependency_link(link)))
+}
+
+function format_issue_references(issue_numbers: ReadonlyArray<number>): string {
+	return join_references(issue_numbers.map((issue_number) => to_issue_reference(issue_number)))
+}
+
+// The `blocked-by` relations a positioned `--add` dropped, named the same way wherever they are
+// reported — on stdout and inside the `--decision-file` record (joshuafolkken/kit#1711). One string
+// rather than two, because the two are read side by side: a reader comparing the console against the
+// record must not have to decide whether two spellings mean the same thing.
+//
+// **Each chain is backticked, never bare and never several to a span.** A line that is *nothing but*
+// `#A -> #B` is read as a dependency declaration anywhere in an epic body — which is what
+// `find_decision_error` refuses a record for — and the `## Decisions` section is parsed with the rest
+// of the body. The label in front already keeps this line out of that pattern; the backticks are what
+// keeps it out if the label is ever reworded. One span **per link** rather than one around the list,
+// because a relocation drops two at once and a single span holding `#890 -> #891, #891 -> #892` reads
+// as one malformed chain in the artifact this line exists to leave behind.
+function format_replaced_relations(links: ReadonlyArray<DependencyLink>): string {
+	const quoted = links.map((link) => `\`${format_dependency_link(link)}\``)
+
+	return `Replaced blocked-by: ${join_references(quoted)}.`
+}
+
+const git_epic_reference = {
+	DEPENDENCY_ARROW,
+	REFERENCE_SEPARATOR,
+	to_issue_reference,
+	join_references,
+	format_dependency_link,
+	format_dependency_links,
+	format_issue_references,
+	format_replaced_relations,
+}
+
+export type { IssueReference }
+export {
+	git_epic_reference,
+	DEPENDENCY_ARROW,
+	REFERENCE_SEPARATOR,
+	to_issue_reference,
+	join_references,
+	format_dependency_link,
+	format_dependency_links,
+	format_issue_references,
+	format_replaced_relations,
+}

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

@@ -0,0 +1,78 @@
+import type { DependencyLink } from './git-epic-parse'
+import { format_dependency_links } from './git-epic-reference'
+import { git_gh_command } from './git-gh-command'
+
+// Recording and dropping the native `blocked-by` relations an epic's declared order implies.
+//
+// The relation is a nicety, not part of the contract: losing it costs only the native link, while
+// the Issue and its task list are already correct. A failure is therefore counted and reported
+// rather than aborting a batch that is otherwise fine. It no longer depends on the gh CLI's version
+// — the relation is written through the REST dependencies endpoint (joshuafolkken/kit#1026).
+//
+// Shared by epic creation and `--add` rather than written once per caller: both apply the same
+// relations for the same reason, and a second copy would be the place a fix is forgotten
+// (joshuafolkken/kit#890).
+
+type RelationAction = 'record' | 'drop'
+
+async function apply_one(link: DependencyLink, action: RelationAction): Promise<boolean> {
+	const blocked = String(link.blocked)
+	const blocker = String(link.blocker)
+
+	return action === 'record'
+		? await git_gh_command.issue_add_blocked_by(blocked, blocker)
+		: await git_gh_command.issue_remove_blocked_by(blocked, blocker)
+}
+
+// How many of the relations could not be applied. Applied concurrently, as epic creation already
+// does: they are independent edits on different issues.
+async function apply_relations(
+	links: ReadonlyArray<DependencyLink>,
+	action: RelationAction,
+): Promise<number> {
+	if (links.length === 0) return 0
+
+	const applied = await Promise.all(links.map(async (link) => await apply_one(link, action)))
+
+	return applied.filter((is_applied) => !is_applied).length
+}
+
+function describe_action(action: RelationAction): string {
+	return action === 'record' ? 'recorded' : 'removed'
+}
+
+// What happened, and to which pairs. The count used to stand on its own, and a count cannot be
+// checked: an insertion that recorded an order nobody declared printed the same
+// `1 blocked-by relation(s) recorded.` as a correct one, so the invented chains of
+// joshuafolkken/kit#1080 were caught only by whoever thought to open the epic body afterwards. The
+// links are named in the `#blocker -> #blocked` form the declaration itself uses, so the reader
+// compares like with like.
+//
+// The failure line still carries no list: `apply_relations` reports how many writes failed and not
+// which, so naming the whole set there would assert more than is known.
+function format_relation_report(input: {
+	links: ReadonlyArray<DependencyLink>
+	failures: number
+	action: RelationAction
+}): string {
+	const verb = describe_action(input.action)
+	const total = String(input.links.length)
+
+	// Nothing to name. Every caller already skips the report on an empty list, but the invariant
+	// belongs with the message rather than with each of them.
+	if (input.links.length === 0) return `🔗 No blocked-by relation was ${verb}.`
+
+	if (input.failures === 0) {
+		return `🔗 ${total} blocked-by relation(s) ${verb}: ${format_dependency_links(input.links)}.`
+	}
+
+	return `⚠️  ${String(input.failures)} of ${total} blocked-by relation(s) could not be ${verb}; the epic body is intact.`
+}
+
+const git_epic_relations = {
+	apply_relations,
+	format_relation_report,
+}
+
+export { git_epic_relations }
+export type { RelationAction }

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

@@ -0,0 +1,152 @@
+import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
+import { git_epic_add_body, type RewriteOutcome } from './git-epic-add-body'
+import { git_epic_chains } from './git-epic-chains'
+import { git_epic_decision } from './git-epic-decision'
+import { chain_links, git_epic_parse, type DependencyLink } from './git-epic-parse'
+import { format_dependency_link, format_dependency_links } from './git-epic-reference'
+import { git_epic_shape } from './git-epic-shape'
+
+// Everything `josh epic --remove` decides before it writes anything.
+//
+// A declared order lives in two places at once — the epic body's `Dependencies` declaration and the
+// native `blocked-by` relations — and until this command there was no way to delete one from both at
+// once. The only route was the hand edit `CLAUDE.md` forbids plus a bare `DELETE` on the
+// dependencies endpoint, and doing either half alone leaves `epic:next` answering
+// `declaration_mismatch`, which stops an unattended run. Epic joshuafolkken/kit#1262 recorded
+// twenty-nine such removals before the command existed (joshuafolkken/kit#1712).
+//
+// Kept apart from the GitHub calls for the reason `git-epic-add-plan.ts` is: the whole decision is
+// asserted without a network, and a refusal path only reachable through `gh` is one nobody tests.
+
+// The path whose consecutive pairs name the orders to delete. `--remove <E> 101 102 103` deletes
+// `#101 -> #102` and `#102 -> #103`, which is the shape a declared chain is written in — so removing
+// a whole chain is one invocation rather than one per link.
+interface RemovePlanInput {
+	epic_number: number
+	body: string | undefined
+	labels: ReadonlyArray<string>
+	path: ReadonlyArray<number>
+	// The epic's current children with their native relations, as `epic:next` reads them.
+	recorded: ReadonlyArray<EpicChild>
+	repo: string
+	// The record `--decision-file` supplied, or `undefined`. It says why the order was deleted, and it
+	// reaches the epic's `## Decisions` and both ends of every deleted order.
+	decision?: string | undefined
+}
+
+interface RemovePlan {
+	body: string
+	// Every order deleted from the declaration — what the report names.
+	links: ReadonlyArray<DependencyLink>
+	// The subset of them a native relation actually backs, which is what there is to drop.
+	removed: ReadonlyArray<DependencyLink>
+	// The children a decision record is posted on: both ends of every deleted order.
+	ends: ReadonlyArray<number>
+}
+
+type RemoveOutcome = { plan: RemovePlan } | { error: string }
+
+const MINIMUM_PATH_LENGTH = 2
+
+// The consecutive pairs of the path, as links. `chain_links` rather than a second walk of its own:
+// what the caller typed is a chain, and it must be read exactly as a declared one is.
+function to_path_links(path: ReadonlyArray<number>): Array<DependencyLink> {
+	return chain_links(path)
+}
+
+function find_path_error(path: ReadonlyArray<number>): string | undefined {
+	if (path.length < MINIMUM_PATH_LENGTH) {
+		return 'Two issue numbers are required after the epic: the order to remove is `<M> <N>`, and a longer list removes each consecutive pair.'
+	}
+
+	return to_path_links(path).length === path.length - 1
+		? undefined
+		: 'The path names the same issue twice in a row, which declares no order.'
+}
+
+// A link the declaration does not name. Refused rather than passed through as a no-op: the caller
+// believes an order exists, and answering "done" to a removal that removed nothing is how a false
+// order survives the one command written to delete it.
+function find_undeclared_error(
+	links: ReadonlyArray<DependencyLink>,
+	chains: ReadonlyArray<ReadonlyArray<number>>,
+): string | undefined {
+	const declared = new Set(
+		git_epic_chains.links_of(chains).map((link) => format_dependency_link(link)),
+	)
+	const missing = links.filter((link) => !declared.has(format_dependency_link(link)))
+
+	return missing.length === 0
+		? undefined
+		: `The declared dependency order does not name ${format_dependency_links(missing)}; there is nothing to remove.`
+}
+
+// A decision record that cannot be written is refused here rather than dropped, exactly as it is for
+// an insertion: `--decision-file` was given because the record has to exist.
+function find_decision_error(decision: string | undefined): string | undefined {
+	return decision === undefined ? undefined : git_epic_decision.find_decision_error(decision)
+}
+
+function find_input_error(
+	input: RemovePlanInput,
+	tracked: ReadonlyArray<number>,
+	chains: ReadonlyArray<ReadonlyArray<number>>,
+): string | undefined {
+	return (
+		git_epic_shape.find_subject_error(input, tracked) ??
+		find_path_error(input.path) ??
+		find_undeclared_error(to_path_links(input.path), chains) ??
+		find_decision_error(input.decision)
+	)
+}
+
+function to_ends(links: ReadonlyArray<DependencyLink>): Array<number> {
+	return [...new Set(links.flatMap((link) => [link.blocker, link.blocked]))]
+}
+
+// The rewrite is the insertion's, with nothing placed: a removal touches the declaration and never
+// the task list, so the children stay exactly where they are and only the arrows go. What it does
+// have to say is `does_clear_declaration` — deleting the last link means writing that there is no
+// order rather than leaving the deleted chain in place.
+function to_body(
+	input: RemovePlanInput,
+	chains_after: ReadonlyArray<ReadonlyArray<number>>,
+): RewriteOutcome {
+	return git_epic_add_body.rewrite_body({
+		body: input.body ?? '',
+		placed: [],
+		chains_after,
+		decision: input.decision,
+		does_clear_declaration: true,
+	})
+}
+
+function build_removal_plan(input: RemovePlanInput): RemoveOutcome {
+	const tracked = git_epic_parse.parse_task_list_issue_numbers(input.body)
+	const chains_before = git_epic_parse.parse_dependency_chains(input.body)
+	const error = find_input_error(input, tracked, chains_before)
+	if (error !== undefined) return { error }
+
+	const links = to_path_links(input.path)
+	const chains_after = git_epic_chains.remove_links(chains_before, links)
+	const rewritten = to_body(input, chains_after)
+	if ('error' in rewritten) return { error: rewritten.error }
+
+	return {
+		plan: {
+			body: rewritten.body,
+			links,
+			// Only the links a relation actually backs: asking `gh` to remove one that was never
+			// recorded is reported as a failure the user cannot act on.
+			removed: epic_graph.recorded_relations(links, input.recorded, input.repo),
+			ends: to_ends(links),
+		},
+	}
+}
+
+const git_epic_remove_plan = {
+	build_removal_plan,
+}
+
+export { git_epic_remove_plan }
+export type { RemovePlan, RemovePlanInput, RemoveOutcome }