@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,171 @@
+import { git_epic_parse, type DependencyLink } from './git-epic-parse'
+import { format_replaced_relations } from './git-epic-reference'
+import { git_epic_sections, type BodyLines, type SectionRange } from './git-epic-sections'
+
+// Placing a decision record inside an epic body's `## Decisions` section.
+//
+// `epic-commands` requires an auto-decision to be written in **both** the epic's `## Decisions` and a
+// comment on each child it applies to, and until now no command wrote the epic half — so a run had to
+// read the body, edit it and `PATCH` it back by hand, which is the one operation `CLAUDE.md` forbids.
+// Measured on runs #1333 and #1349, that repair-shaped detour is where the post-merge bookkeeping
+// spends its round trips, and the two most recent filings skipped the epic half entirely rather than
+// pay for it (joshuafolkken/kit#1350).
+//
+// So the record rides on the body edit `--add` already makes: no extra round trip, and the half that
+// was being dropped is written by the command instead of by hand.
+
+const DECISIONS_HEADING = '## Decisions'
+const DECISIONS_HEADING_PATTERN = /^#{1,6}[ \t]+Decisions\b/u
+const BLANK_LINE = ''
+// Editors count from one; `find_indices` answers a zero-based index.
+const FIRST_LINE_NUMBER = 1
+
+// A record that says nothing is worse than no record: it satisfies the "was it written" question
+// while leaving the reasoning unrecoverable. Refused before anything is written.
+const EMPTY_RECORD =
+	'The decision record is empty; write the record before recording it, or leave `--decision-file` off.'
+
+// **The offending line is named, never quoted.** The record is a file the caller handed over, and
+// echoing a line of it into stderr puts arbitrary file content in the console — the leak SonarCloud's
+// `tssecurity:S8689` reports for exactly this path on joshuafolkken/kit#1350. A line number is as
+// actionable, since the author has the file open, and it carries nothing out of it.
+function to_declaration_error(line_number: number): string {
+	return `Line ${String(line_number)} of the decision record is nothing but a dependency chain, which \`epic:next\` would read as part of the epic's dependency order; wrap it in backticks, fence it, or reword it.`
+}
+
+// Whether the record can be written at all. The declaration check is the load-bearing one: a bare
+// `#A -> #B` line anywhere in the body is parsed as a declaration, so a record quoting an order as a
+// standalone line would silently add a dependency nobody declared — the failure mode
+// joshuafolkken/kit#1253 documents, arriving by a second route.
+//
+// **It is judged exactly the way the merged body will be judged**: the predicate is the parser's own,
+// and the lines are read through the same fence mask, so a record whose chain sits inside a fenced
+// block — which the parser ignores once merged — is accepted rather than refused with advice to wrap in
+// backticks that the fence has already given it.
+function find_decision_error(record: string): string | undefined {
+	if (record.trim().length === 0) return EMPTY_RECORD
+
+	const input = git_epic_sections.to_body_lines(record)
+	const [found] = git_epic_sections.find_indices(input, (line) =>
+		git_epic_parse.is_declaration_line(line),
+	)
+
+	return found === undefined ? undefined : to_declaration_error(found + FIRST_LINE_NUMBER)
+}
+
+// The record as the lines it contributes, with a blank line in front so it never runs into whatever
+// it is appended after. Trailing blanks are dropped rather than preserved: the record's own file
+// almost always ends with a newline, and keeping it would grow the section by a blank line per entry.
+function to_record_lines(record: string): Array<string> {
+	return [BLANK_LINE, ...record.trimEnd().split('\n')]
+}
+
+// A body with no `## Decisions` section at all: the section is created at the end, which is where
+// every epic that has one carries it (`epic --add --decision-file` writes it there, after `## Progress`).
+function to_new_section(lines: ReadonlyArray<string>, record: string): Array<string> {
+	return [...lines, BLANK_LINE, DECISIONS_HEADING, ...to_record_lines(record)]
+}
+
+// The last line of the section that is not blank, as an offset into the whole body. Appending after
+// it rather than at `range.end` keeps the blank line that separates the section from the next heading
+// where it was, instead of pushing the record below it and outside the section.
+function last_content_index(input: BodyLines, range: SectionRange): number {
+	const inside = input.lines.slice(range.start, range.end)
+	const offset = inside.findLastIndex((line) => line.trim().length > 0)
+
+	return offset === -1 ? range.start : range.start + offset + 1
+}
+
+// Append the record to the epic's `## Decisions` section, creating the section when there is none.
+//
+// The section's *end* rather than its start: the entries are a log, and a reader looking for the most
+// recent decision reads down. Nothing else in the body moves.
+function append_decision(body: string, record: string): string {
+	const input = git_epic_sections.to_body_lines(body)
+	const range = git_epic_sections.find_section_range(input, DECISIONS_HEADING_PATTERN)
+	if (range === undefined) return to_new_section(input.lines, record).join('\n')
+
+	const at = last_content_index(input, range)
+
+	return [...input.lines.slice(0, at), ...to_record_lines(record), ...input.lines.slice(at)].join(
+		'\n',
+	)
+}
+
+// The record as it will actually be written, with the relations this insertion replaced appended to
+// it (joshuafolkken/kit#1711).
+//
+// **A positioned `--add` discards the `blocked-by` relation the child already had, and until now the
+// record said nothing about it.** On joshuafolkken/kit#1703 that overwrote a decision whose reasoning
+// was written down, twice in four minutes, leaving the body's declaration, the native relations and
+// the recorded decision disagreeing with one another. The record is the artifact read months later, so
+// it is where what was replaced has to survive — the console line scrolls away.
+//
+// **The policy is to report, not to refuse.** Re-pointing a position is what joshuafolkken/kit#1701
+// deliberately added, so refusing an invocation that carries no `--decision-file` would close a
+// working route to force a record; naming what was dropped costs the caller nothing and loses nothing.
+//
+// `undefined` stays `undefined`: an insertion that records no decision gains none here, and an
+// insertion that replaced nothing gains no line.
+function append_replacements(
+	record: string | undefined,
+	links: ReadonlyArray<DependencyLink>,
+): string | undefined {
+	if (record === undefined || links.length === 0) return record
+
+	return [record.trimEnd(), BLANK_LINE, format_replaced_relations(links)].join('\n')
+}
+
+// What happened to the child half of the record, phrased as a count for the reason the relation report
+// is: the useful signal is whether every child now carries the reasoning, not which comment was
+// refused. The epic half is never reported here — it rode on the body edit, so it landed or the
+// insertion did not.
+function format_decision_report(input: { total: number; failures: number }): string {
+	if (input.failures === 0) {
+		return `📝 Decision recorded on the epic and ${String(input.total)} child issue(s).`
+	}
+
+	return `⚠️  ${String(input.failures)} of ${String(input.total)} child comment(s) could not be posted; the epic's \`${DECISIONS_HEADING}\` entry is intact.`
+}
+
+// The heading a creation writes its reasoning under. Beside a pattern exactly as `DECISIONS_HEADING`
+// is, and tied to `git_epic_body`'s own literal by a test that reads a body the builder produced
+// rather than by a string comparison (joshuafolkken/kit#1712).
+const RATIONALE_HEADING_PATTERN = /^#{1,6}[ \t]+Split rationale\b/u
+
+function read_section(body: string, heading: RegExp): string {
+	const input = git_epic_sections.to_body_lines(body)
+	const range = git_epic_sections.find_section_range(input, heading)
+	if (range === undefined) return ''
+
+	return input.lines.slice(range.start, range.end).join('\n')
+}
+
+// Every place the epic body itself records why something was decided: the `## Decisions` log an
+// insertion or a removal appends to, **and** the `## Split rationale` a creation writes.
+//
+// Both, not just the first. `josh epic … --ordered` declares a whole chain and records its reasoning
+// under `## Split rationale`, writing no `## Decisions` at all — so a reader that looked only at
+// `## Decisions` would report every correctly-documented ordered epic as unjustified the moment it
+// was created (joshuafolkken/kit#1712). It is this module's because the heading patterns are: a
+// second reader with its own copies is one that comes to disagree with the writers about where a
+// record goes.
+function read_recorded_reasons(body: string | undefined): string {
+	if (body === undefined) return ''
+
+	return [
+		read_section(body, DECISIONS_HEADING_PATTERN),
+		read_section(body, RATIONALE_HEADING_PATTERN),
+	].join('\n')
+}
+
+const git_epic_decision = {
+	DECISIONS_HEADING,
+	append_decision,
+	append_replacements,
+	read_recorded_reasons,
+	find_decision_error,
+	format_decision_report,
+}
+
+export { git_epic_decision }

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

@@ -0,0 +1,351 @@
+// An epic Issue tracks its children as a markdown task list (`- [ ] #101`). Only that syntax
+// counts as tracked: GitHub auto-checks such an entry when the referenced Issue closes, whereas a
+// bare `#101` reference produces a cross-link with no progress tracking.
+//
+// The source is shared by the whole-body scan and the single-line test rather than written twice: a
+// rewriter has to recognize exactly the rows the reader counts, and two copies of this pattern would
+// be two chances to disagree about what a tracked row is (joshuafolkken/kit#890).
+const TASK_LIST_ISSUE_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+#(\d+)\b`
+const TASK_LIST_ISSUE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'gmu')
+const TASK_LIST_LINE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'u')
+
+// A task list may also reference an Issue in another repository (`owner/repo#101`, or a full URL).
+// Detecting one is what the auto-close used to bail on; joshuafolkken/kit#864 reads them instead,
+// against their own repository, and the pattern below extracts which repository and which issue.
+// `owner/repo#101` on its own. The row patterns below are built from this source, so what counts as
+// a cross-repository reference has one definition — a second copy would let a form the task list
+// accepts be refused where a person types it, or the reverse (joshuafolkken/kit#985).
+const EXTERNAL_REFERENCE_SOURCE = String.raw`([\w.-]+)\/([\w.-]+)#(\d+)`
+const EXTERNAL_REFERENCE_PATTERN = new RegExp(`^${EXTERNAL_REFERENCE_SOURCE}$`, 'u')
+const TASK_LIST_ROW_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+`
+const EXTERNAL_TASK_LIST_PATTERN = new RegExp(
+	String.raw`${TASK_LIST_ROW_SOURCE}(?:${EXTERNAL_REFERENCE_SOURCE}|https?:\/\/)`,
+	'mu',
+)
+// `- [ ] owner/repo#101`
+const EXTERNAL_SHORTHAND_PATTERN = new RegExp(
+	String.raw`${TASK_LIST_ROW_SOURCE}${EXTERNAL_REFERENCE_SOURCE}\b`,
+	'gmu',
+)
+// `- [ ] https://github.com/owner/repo/issues/101`
+const EXTERNAL_URL_PATTERN =
+	/^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)\b/gmu
+
+// Fenced blocks are stripped before matching. An epic body may quote the body template itself, and
+// its sample rows (`- [ ] #101 <title>`) are illustrations, not tracked children — counting them
+// would attach a nonexistent Issue to the batch and keep the epic open forever.
+const FENCE_LINE_PATTERN = /^[ \t]*(?:`{3,}|~{3,})/u
+
+// A chain between two Issue references (`#101 -> #102`, or the arrow written as `→`), read for its
+// links. `epic:next` compares what the body declares against the `blocked-by` relations actually
+// recorded, and a body that says one order while the relations say another must stop the run rather
+// than silently follow either (joshuafolkken/kit#860).
+//
+// Only a line that is *nothing but* a chain counts, optionally behind a list marker. Measured
+// against joshuafolkken/kit#858, whose Dependencies section is followed by a prose line recommending
+// an execution order — e.g. `recommended order: #869 -> #863 -> …`. Those arrows are a suggestion, not a
+// declaration, and reading them as one reported four disagreements that did not exist.
+const DECLARED_CHAIN_LINE = /^(?:[-*+][ \t]+)?#\d+(?:[ \t]*(?:->|→)[ \t]*#\d+)+$/u
+const CHAIN_REFERENCE_PATTERN = /#(\d+)/gu
+
+// The other half of a machine-readable `Dependencies` section: the exact sentence that declares a
+// batch to have no order. It lives here, beside the chain patterns, because all of them are what a
+// reader of the body is allowed to rely on — the generator imports this rather than restating it, so
+// the text it writes and the text checked for are one string.
+const UNORDERED_DEPENDENCIES = 'None — the children are independent; any execution order works.'
+
+const CLOSED_STATE = 'CLOSED'
+
+// Which lines a body predicate is allowed to read: `false` for a fence line and for everything
+// between a pair of them. Returned as a mask rather than a filtered string because a rewriter has to
+// put lines back where it found them, and it must skip exactly the lines the readers skip — two
+// separate fence walks would be two chances to disagree (joshuafolkken/kit#890).
+//
+// Toggling on each fence line keeps this linear — a single regex spanning the block would backtrack.
+// An unterminated fence swallows the rest of the body, which fails safe: fewer children means the
+// epic is simply never matched, and it stays open for manual closing.
+function fence_mask(body: string): Array<boolean> {
+	let is_inside_fence = false
+
+	return body.split('\n').map((line) => {
+		if (FENCE_LINE_PATTERN.test(line)) {
+			is_inside_fence = !is_inside_fence
+
+			return false
+		}
+
+		return !is_inside_fence
+	})
+}
+
+function strip_fenced_blocks(body: string): string {
+	const mask = fence_mask(body)
+
+	return body
+		.split('\n')
+		.filter((_, index) => mask[index] === true)
+		.join('\n')
+}
+
+function to_issue_number(match: RegExpMatchArray): number | undefined {
+	const [, raw] = match
+	if (raw === undefined) return undefined
+
+	const parsed = Number(raw)
+
+	return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+function parse_task_list_issue_numbers(body: string | undefined): Array<number> {
+	if (body === undefined) return []
+
+	const numbers = Array.from(strip_fenced_blocks(body).matchAll(TASK_LIST_ISSUE_PATTERN), (match) =>
+		to_issue_number(match),
+	).filter((value): value is number => value !== undefined)
+
+	return [...new Set(numbers)]
+}
+
+// Every body predicate must strip fenced blocks first, for the reason given on FENCE_LINE_PATTERN.
+// The patterns are non-global, so `test` keeps no `lastIndex` state between calls.
+function has_pattern_match(pattern: RegExp, body: string | undefined): boolean {
+	if (body === undefined) return false
+
+	return pattern.test(strip_fenced_blocks(body))
+}
+
+function has_external_task_list_entry(body: string | undefined): boolean {
+	return has_pattern_match(EXTERNAL_TASK_LIST_PATTERN, body)
+}
+
+// A child of this epic that lives in another repository.
+interface ExternalChild {
+	repo: string
+	number: number
+}
+
+const OWNER_GROUP = 1
+const REPO_GROUP = 2
+const EXTERNAL_NUMBER_GROUP = 3
+
+function to_external_child(match: RegExpMatchArray): ExternalChild | undefined {
+	const owner = match[OWNER_GROUP]
+	const repo = match[REPO_GROUP]
+	if (owner === undefined || repo === undefined) return undefined
+	const parsed = Number(match[EXTERNAL_NUMBER_GROUP])
+
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) return undefined
+
+	return { repo: `${owner}/${repo}`, number: parsed }
+}
+
+// A bare `owner/repo#101`, as a person types it — the same shape the task-list rows carry, read
+// from a command argument rather than from a body. It reuses `to_external_child` so the two cannot
+// disagree about which owner and repository names are acceptable (joshuafolkken/kit#985).
+function parse_external_reference(text: string): ExternalChild | undefined {
+	const match = EXTERNAL_REFERENCE_PATTERN.exec(text.trim())
+	if (match === null) return undefined
+
+	return to_external_child(match)
+}
+
+function match_external(body: string, pattern: RegExp): Array<ExternalChild> {
+	return Array.from(body.matchAll(pattern), (match) => to_external_child(match)).filter(
+		(child): child is ExternalChild => child !== undefined,
+	)
+}
+
+// Every cross-repository child the task list tracks, in both spellings. Reported as `owner/repo`
+// plus a number rather than a URL, which is the form the repository map takes and the form the
+// read's REST path is built from (joshuafolkken/kit#864).
+function parse_external_task_list_children(body: string | undefined): Array<ExternalChild> {
+	if (body === undefined) return []
+	const stripped = strip_fenced_blocks(body)
+	const found = [
+		...match_external(stripped, EXTERNAL_SHORTHAND_PATTERN),
+		...match_external(stripped, EXTERNAL_URL_PATTERN),
+	]
+	const seen = new Set<string>()
+
+	return found.filter((child) => {
+		const key = `${child.repo}#${String(child.number)}`
+		const is_new = !seen.has(key)
+
+		seen.add(key)
+
+		return is_new
+	})
+}
+
+// Whether one line is a tracked child row. Used by the rewriter to find where the rows end, so a
+// new row lands beside the existing ones rather than at the bottom of the body.
+function is_task_list_line(line: string): boolean {
+	return TASK_LIST_LINE_PATTERN.test(line)
+}
+
+// Fenced blocks are stripped here for the same reason they are everywhere else: an epic body may
+// quote the template, and a declaration inside that quote is an illustration, not a declaration.
+function has_unordered_declaration(body: string | undefined): boolean {
+	if (body === undefined) return false
+
+	return strip_fenced_blocks(body).includes(UNORDERED_DEPENDENCIES)
+}
+
+// Whether one line, on its own, is part of a machine-readable `Dependencies` declaration — a chain or
+// the unordered sentence. It lives here beside the two patterns it tests rather than in either of the
+// modules that rewrite a body, because both of them need it and a second copy is where one comes to
+// disagree with the parser about what counts as a declaration (joshuafolkken/kit#1350).
+function is_declaration_line(line: string): boolean {
+	const trimmed = line.trim()
+
+	return DECLARED_CHAIN_LINE.test(trimmed) || trimmed === UNORDERED_DEPENDENCIES
+}
+
+// One declared link: `blocker` must finish before `blocked` starts.
+interface DependencyLink {
+	blocker: number
+	blocked: number
+}
+
+const REFERENCE_GROUP = 1
+
+// The issue numbers of one chain line, in order.
+function chain_references(line: string): Array<number> {
+	return Array.from(line.matchAll(CHAIN_REFERENCE_PATTERN), (match) =>
+		Number(match[REFERENCE_GROUP]),
+	).filter((value) => Number.isSafeInteger(value))
+}
+
+// `#1 -> #2 -> #3` becomes two links; consecutive links share their middle reference.
+function chain_links(references: ReadonlyArray<number>): Array<DependencyLink> {
+	return references
+		.slice(1)
+		.map((blocked, index) => ({ blocker: references[index] ?? blocked, blocked }))
+		.filter((link) => link.blocker !== link.blocked)
+}
+
+// Every declared chain, one entry per chain line, each holding its references in the order written.
+// Read at this granularity rather than as a flat link list because an insertion has to know *which*
+// chain a target sits in: two disjoint chains and one branching chain produce the same links, and
+// only the line structure tells them apart (joshuafolkken/kit#890).
+//
+// Fenced blocks are stripped first for the reason they are everywhere else: a quoted template's
+// sample chain is an illustration.
+function parse_dependency_chains(body: string | undefined): Array<Array<number>> {
+	if (body === undefined) return []
+
+	return strip_fenced_blocks(body)
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => DECLARED_CHAIN_LINE.test(line))
+		.map((line) => chain_references(line))
+}
+
+// Every link the body declares, in the order written. Flattened from the chains above rather than
+// re-scanning the body, so "what a chain line is" has one definition.
+function parse_dependency_links(body: string | undefined): Array<DependencyLink> {
+	return parse_dependency_chains(body).flatMap((references) => chain_links(references))
+}
+
+// Whether the body declares an order at all — asked by `epic:check` and by the order-unrecorded
+// warning, which need to tell "the order was never recorded" from "there is no order".
+//
+// Answered from the chains above rather than from a pattern of its own, because a second pattern is
+// a second answer: until joshuafolkken/kit#1155 this scanned the whole body for a bare `#N -> #M`,
+// so a rationale paragraph recommending an execution order made an epic declared
+// `None — the children are independent` report as ordered, and `josh followup` then said the batch
+// order was never recorded on every child's merge. The narrowing joshuafolkken/kit#858 applied to
+// the link reader was the same judgement, and `epic --add` writes on that judgement too
+// (`git-epic-add-body.ts` protects an arrow outside the `Dependencies` section as prose) — so the
+// three readers of one body now recognize the same lines, instead of two patterns that could
+// disagree about which line is a declaration. They still answer different questions of those lines:
+// a self-loop (`#101 -> #101`) is a declaration here and yields no link, since `chain_links` drops
+// an edge from an issue to itself.
+function has_declared_dependency_chain(body: string | undefined): boolean {
+	return parse_dependency_chains(body).length > 0
+}
+
+// What the body declares about order, as the two independent answers every reader of it needs. Read
+// from the whole fence-stripped body rather than from the `Dependencies` section, because that is
+// where `epic:next` reads its links from: a chain line left outside the section is followed by the
+// run, so a check that could not see it would call such a body consistent.
+interface DeclarationState {
+	has_chain: boolean
+	has_none_literal: boolean
+}
+
+function read_declaration(body: string | undefined): DeclarationState {
+	return {
+		has_chain: has_declared_dependency_chain(body),
+		has_none_literal: has_unordered_declaration(body),
+	}
+}
+
+// Whether that declaration says something a machine can act on: exactly one of the two forms, never
+// both. A body carrying a chain *and* the `None — ...` literal declares an order and declares that
+// there is none, and `epic:check` used to pass it while reporting only the half that contradicts the
+// other (joshuafolkken/kit#1155). Single-sourced here because `epic:check`, `epic --add` and
+// `epic --promote` all mean this same question, and three copies of the disjunction were three
+// chances to accept a body the check rejects.
+function is_declaration_readable(state: DeclarationState): boolean {
+	return state.has_chain !== state.has_none_literal
+}
+
+function has_machine_readable_declaration(body: string | undefined): boolean {
+	return is_declaration_readable(read_declaration(body))
+}
+
+function has_child(children: ReadonlyArray<number>, issue_number: number): boolean {
+	return children.includes(issue_number)
+}
+
+// The Issue the merged PR just closed is treated as closed without querying it. GitHub applies the
+// `closes #N` side effect asynchronously, so reading its state right after the merge is a race that
+// would intermittently leave a finished epic open.
+function is_state_closed(state: string | undefined): boolean {
+	return state?.toUpperCase() === CLOSED_STATE
+}
+
+const git_epic_parse = {
+	fence_mask,
+	is_task_list_line,
+	is_declaration_line,
+	chain_links,
+	parse_dependency_chains,
+	parse_task_list_issue_numbers,
+	has_external_task_list_entry,
+	has_declared_dependency_chain,
+	has_unordered_declaration,
+	read_declaration,
+	is_declaration_readable,
+	has_machine_readable_declaration,
+	parse_dependency_links,
+	parse_external_task_list_children,
+	parse_external_reference,
+	has_child,
+	is_state_closed,
+}
+
+export type { DeclarationState, DependencyLink, ExternalChild }
+export {
+	git_epic_parse,
+	fence_mask,
+	is_task_list_line,
+	is_declaration_line,
+	chain_links,
+	parse_dependency_chains,
+	parse_task_list_issue_numbers,
+	has_external_task_list_entry,
+	has_declared_dependency_chain,
+	has_unordered_declaration,
+	read_declaration,
+	is_declaration_readable,
+	has_machine_readable_declaration,
+	parse_dependency_links,
+	parse_external_task_list_children,
+	parse_external_reference,
+	has_child,
+	is_state_closed,
+	UNORDERED_DEPENDENCIES,
+	DECLARED_CHAIN_LINE,
+}

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

@@ -0,0 +1,102 @@
+import { git_epic_body } from './git-epic-body'
+import { git_epic_parse } from './git-epic-parse'
+
+// Promoting an existing issue into an epic.
+//
+// The discussion that concluded "this is really several issues" is almost always *inside* an
+// existing issue, and that discussion is usually the split rationale itself. Creating a separate
+// epic leaves two issues tracking one topic, so the promotion appends the epic's sections to the
+// body rather than replacing it (joshuafolkken/kit#865).
+
+const EPIC_SECTION_MARKER = '## Progress'
+const PROMOTED_HEADING = '## Split into children'
+
+interface PromoteInput {
+	body: string | undefined
+	children: ReadonlyArray<number>
+	rationale: string
+	is_ordered: boolean
+	epic_number: number
+	origin?: string | undefined
+}
+
+// Whether appending the epic sections would leave the body tracking two sets of children.
+//
+// The signal is task-list rows, not the promoted heading: an issue created by `josh epic` already
+// carries a task list without ever having been promoted, and appending to it would produce two task
+// lists and two contradictory `## Dependencies` sections. A pre-existing row on an ordinary issue —
+// someone's `- [x] #850` checklist — is the same hazard from the other direction, since the promoted
+// body keeps everything that was there and every parser scans the whole thing.
+//
+// Detected from the body rather than the `epic` label, which can be applied by hand without any of
+// the sections.
+function has_conflicting_tracking(body: string | undefined): boolean {
+	if (body === undefined) return false
+	if (body.includes(PROMOTED_HEADING)) return true
+
+	return git_epic_parse.parse_task_list_issue_numbers(body).length > 0
+}
+
+// Why the promotion was refused, phrased as what was found rather than as a rule number.
+function conflict_reason(body: string | undefined): string {
+	if (body?.includes(PROMOTED_HEADING) === true) return 'it already carries the epic sections'
+	const tracked = git_epic_parse.parse_task_list_issue_numbers(body)
+	const list = tracked.map((child) => `#${String(child)}`).join(', ')
+
+	return `its body already tracks ${list} as a task list, which would become a second child list`
+}
+
+// The promoted body: everything that was there, then the epic sections under one heading that says
+// what happened. The original text is never rewritten — it is the record of why the split was made.
+function build_promoted_body(input: PromoteInput): string {
+	const existing = (input.body ?? '').trimEnd()
+	const epic_sections = git_epic_body.build_epic_body({
+		children: input.children,
+		rationale: input.rationale,
+		is_ordered: input.is_ordered,
+		origin: input.origin,
+		epic_number: input.epic_number,
+	})
+
+	return [existing, '', PROMOTED_HEADING, '', epic_sections, ''].join('\n').trimStart()
+}
+
+// Why the promoted body would not satisfy what `epic:check` reads — a task list of children and an
+// unambiguous machine-readable `Dependencies` declaration — or `undefined` when it would. The label
+// is applied separately by the caller.
+//
+// The two causes are named apart because they need different actions and only one of them is about
+// the children: a declaration-shaped line already present in the issue being promoted is carried
+// into the epic verbatim, and an unordered promotion then adds the `None — ...` literal beside it,
+// so the body would declare an order and declare that there is none. Reported as "does not track
+// every child", that state left nothing to act on (joshuafolkken/kit#1155).
+function declaration_error(body: string): string | undefined {
+	const state = git_epic_parse.read_declaration(body)
+	if (git_epic_parse.is_declaration_readable(state)) return undefined
+
+	return state.has_chain
+		? 'The promoted body would declare an order and declare that there is none: the issue being promoted already carries a line that is only a chain (`#N -> #M`), and it contradicts the `Dependencies` section written for the epic. Reword that line first; nothing was written.'
+		: 'The promoted body would carry no machine-readable `Dependencies` declaration; nothing was written.'
+}
+
+function find_tracking_error(body: string, children: ReadonlyArray<number>): string | undefined {
+	const tracked = git_epic_parse.parse_task_list_issue_numbers(body)
+
+	if (children.some((child) => !tracked.includes(child))) {
+		return 'The promoted body would not track every child; nothing was written.'
+	}
+
+	return declaration_error(body)
+}
+
+const git_epic_promote = {
+	EPIC_SECTION_MARKER,
+	PROMOTED_HEADING,
+	has_conflicting_tracking,
+	conflict_reason,
+	build_promoted_body,
+	find_tracking_error,
+}
+
+export type { PromoteInput }
+export { git_epic_promote }