@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -1,43 +1,36 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_label_schema } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import { issue_cite } from '#scripts/issue/issue-cite'
 import { session_cite } from '#scripts/issue/session-cite'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import type { PollOptions } from '#scripts/lib/poll'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { z } from 'zod'
-import {
-	epic_bundle,
-	type BacklogIssue,
-	type BundleAction,
-	type BundleDecision,
-	type MembershipContext,
-} from './epic-bundle'
-import { epic_bundle_evidence } from './epic-bundle-evidence'
+import { epic_bundle, type BacklogIssue, type MembershipContext } from './epic-bundle'
+import { epic_bundle_apply } from './epic-bundle-apply'
+import { epic_bundle_format } from './epic-bundle-format'
 import { epic_bundle_gaps } from './epic-bundle-gaps'
 import { epic_bundle_poll } from './epic-bundle-poll'
 import { epic_bundle_referenced, type ReferencedContext } from './epic-bundle-referenced'
 import { epic_index, epic_schema, type FetchedEpics } from './epic-index'
 import { epic_issue } from './epic-issue'
-import { format_dependency_links, type IssueReference } from './epic-reference'
+import type { IssueReference } from './epic-reference'
 
 // `josh epic:bundle <N>` — after an issue is filed, look at the open backlog and say whether it
 // belongs with something already there.
 //
 // The machine finds the candidates; the decision to bundle is the caller's. This command prints what
-// it found and what it recommends, and writes nothing.
+// it found and what it recommends, and writes nothing — unless `--apply` asks it to write the answers
+// whose placement is settled (`epic-bundle-apply.ts`).
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // The open backlog was 13 issues when this was written. Scanning all of them is instant, so there is
 // no index and no cache; add one when the number makes it necessary, not before.
 const BACKLOG_LIMIT = 200
-const USAGE = 'Usage: josh epic:bundle <issue-number>'
+const APPLY_FLAG = '--apply'
+const USAGE = 'Usage: josh epic:bundle <issue-number> [--apply]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the backlog cannot be keyed by repository — check `gh auth status` and that this is a checkout with an `origin` remote.'
 
@@ -202,23 +195,7 @@ async function fetch_backlog(
 	}
 }
 
-const ACTION_LINES: Readonly<Record<string, string>> = {
-	add_to_epic: 'Add it to the epic that already tracks a related issue (Tier A — do it).',
-	create_epic: 'Create an epic for these (Tier A — do it).',
-	ask: 'Related issues sit in more than one epic: choose the one you recommend, add it, and record why (Tier A — do it).',
-	none: 'Nothing to bundle.',
-}
-
-// `Nothing to bundle.` is right when nothing was found, and wrong when an epic already tracks the
-// issue — there the answer is actionable: a caller looking for somewhere to put a prerequisite adds
-// it to *that* epic rather than creating a second one.
-const ALREADY_TRACKED_LINE = 'Already in an epic — add to that one, do not create a second.'
-
-function headline(decision: BundleDecision): string {
-	if (decision.action === 'none' && decision.epics.length > 0) return ALREADY_TRACKED_LINE
-
-	return ACTION_LINES[decision.action] ?? ''
-}
+const { format_decision } = epic_bundle_format
 
 // The epics currently open, at this command's own listing limit. A failed read stays `undefined` and
 // is reported: without the list, an issue an epic already tracks is told to create a second one —
@@ -227,72 +204,6 @@ async function fetch_epics(): Promise<FetchedEpics | undefined> {
 	return await epic_index.fetch_epics(BACKLOG_LIMIT)
 }
 
-function format_numbers(numbers: ReadonlyArray<number>): string {
-	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
-}
-
-// The order to record alongside the bundle. Bundling without it records the batch and loses the
-// reason it is a batch, so the recommendation carries it rather than leaving it to be remembered.
-function format_links(links: ReadonlyArray<{ blocker: number; blocked: number }>): string {
-	if (links.length === 0) return '  Order: none declared — do not invent one'
-
-	return `  Order: ${format_dependency_links(links)}`
-}
-
-function format_order(
-	decision: BundleDecision,
-	subject: BacklogIssue,
-	backlog: ReadonlyArray<BacklogIssue>,
-): Array<string> {
-	if (decision.action !== 'add_to_epic' && decision.action !== 'create_epic') return []
-	const members = backlog.filter((issue) => decision.candidates.includes(issue.number))
-	const children = epic_bundle.bundle_children(subject, members)
-
-	// The evidence goes under the order rather than beside the verdict: what it explains is the
-	// order, and a reader checking one reads straight on into the other.
-	return [
-		`  Children: ${format_numbers(children)}`,
-		format_links(epic_bundle.bundle_dependency_links(subject, members)),
-		...epic_bundle_evidence.format_evidence(subject, members),
-	]
-}
-
-// The verdicts that put the subject into an epic. Each one asserts that no epic already tracks it —
-// `create_epic` asserts as much about the candidates too — and that negative is exactly what a cut
-// epic listing cannot establish. `none` is absent on purpose: it either
-// names the epic it *found* tracking the subject, which a cut cannot unseat, or reports no candidate
-// at all, which says nothing about epics.
-const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
-	'add_to_epic',
-	'create_epic',
-	'ask',
-])
-
-// `is_membership_established` is what separates "no epic tracks these" from "their epics were never
-// read".
-function format_decision(
-	decision: BundleDecision,
-	subject: BacklogIssue,
-	backlog: ReadonlyArray<BacklogIssue>,
-	is_membership_established: boolean,
-): string {
-	if (!is_membership_established && PLACING_ACTIONS.has(decision.action)) {
-		return epic_bundle_gaps.unconfirmed_membership(format_numbers(decision.candidates)).join('\n')
-	}
-
-	const lines = [headline(decision), `  ${decision.reason}`]
-
-	if (decision.candidates.length > 0) {
-		lines.push(`  Related: ${format_numbers(decision.candidates)}`)
-	}
-
-	if (decision.epics.length > 1) {
-		lines.push(`  Epics involved: ${format_numbers(decision.epics)}`)
-	}
-
-	return [...lines, ...format_order(decision, subject, backlog)].join('\n')
-}
-
 // The open backlog and the epics tracking it, read once.
 async function read_backlog(repo: string, options?: BacklogOptions): Promise<FetchedBacklog> {
 	const open_epics = await fetch_epics()
@@ -366,7 +277,13 @@ function warn_about_gaps(backlog: FetchedBacklog): void {
 	warn_cutoff(epic_bundle_gaps.epic_gap(backlog.epic_cutoff ?? NO_CUTOFF, BACKLOG_LIMIT))
 }
 
-function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: string): number {
+// The report always prints; `--apply` then writes what it settled (`epic-bundle-apply.ts`).
+async function report_decision(
+	subject: BacklogIssue,
+	backlog: FetchedBacklog,
+	repo: string,
+	is_apply: boolean,
+): Promise<number> {
 	const others = backlog.issues.filter((issue) => issue.number !== subject.number)
 	const is_established = epic_bundle_gaps.is_membership_established(backlog.epic_cutoff)
 	const decision = epic_bundle.decide_bundle(subject, others)
@@ -376,8 +293,14 @@ function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: s
 	const report = format_decision(decision, subject, others, is_established)
 
 	console.info(issue_citation.linkify(report, repo))
-
-	return SUCCESS_EXIT_CODE
+	if (!is_apply) return SUCCESS_EXIT_CODE
+
+	return await epic_bundle_apply.apply_decision({
+		decision,
+		subject,
+		members: epic_bundle_format.members_of(decision, others),
+		is_membership_established: is_established,
+	})
 }
 
 // Widen, report what the read could not cover, then decide. Split out of `report_for`, which is
@@ -386,12 +309,13 @@ async function report_widened(
 	subject: BacklogIssue,
 	backlog: FetchedBacklog,
 	repo: string,
+	is_apply: boolean,
 ): Promise<number> {
 	const widened = await widen_with_referenced(subject, backlog)
 
 	warn_about_gaps(widened)
 
-	return report_decision(subject, widened, repo)
+	return await report_decision(subject, widened, repo, is_apply)
 }
 
 // The recommendation for one issue, from the open backlog around it. `options` is the poll a caller
@@ -400,6 +324,7 @@ async function report_for(
 	issue_number: number,
 	repo: string,
 	options?: PollOptions,
+	is_apply = false,
 ): Promise<number> {
 	const backlog = await epic_bundle_poll.read_until_listed(
 		async () => await read_backlog(repo),
@@ -423,11 +348,12 @@ async function report_for(
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report_widened(subject, backlog, repo)
+	return await report_widened(subject, backlog, repo, is_apply)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const issue_number = epic_issue.parse_epic_number(argv[0])
+	const raw_issue = argv.find((argument) => argument !== APPLY_FLAG)
+	const issue_number = epic_issue.parse_epic_number(raw_issue)
 
 	if (issue_number === undefined) {
 		console.error(USAGE)
@@ -448,25 +374,14 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await report_for(issue_number, repo)
-}
-
-// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
-// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
-// command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
-// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
+	return await report_for(issue_number, repo, undefined, argv.includes(APPLY_FLAG))
 }
 
 const epic_bundle_cli = {
 	USAGE,
 	BACKLOG_LIMIT,
-	ACTION_LINES,
-	ALREADY_TRACKED_LINE,
+	...epic_bundle_format,
 	build_epic_index,
-	format_numbers,
-	format_order,
 	unreadable_backlog_message,
 	read_backlog,
 	report_for,
@@ -474,11 +389,7 @@ const epic_bundle_cli = {
 	fetch_backlog,
 	widen_with_referenced,
 	warn_about_gaps,
-	format_decision,
 	run,
-	main,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { epic_bundle_cli }

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

@@ -1,4 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
+import type { SignalSection } from './epic-audit'
 import { epic_bundle, type BacklogIssue } from './epic-bundle'
 
 // The facts the bundle decision was already made from, printed beside the order it prints.
@@ -20,10 +21,26 @@ import { epic_bundle, type BacklogIssue } from './epic-bundle'
 type EvidenceKind = 'dependency' | 'reference'
 
 // One fact, and the order it points to. `first` is the issue the fact puts ahead of `second`.
+// `section` is where a reference was read, so the reader sees it was the acceptance criteria or the
+// parent line that counted, not a mention elsewhere in the body.
 interface OrderingEvidence {
 	kind: EvidenceKind
 	first: number
 	second: number
+	section?: SignalSection
+}
+
+// What one directed test found: nothing, or the fact with whatever detail it carries.
+type EvidenceFound = Pick<OrderingEvidence, 'section'> | undefined
+
+function blocker_found(from: BacklogIssue, to: BacklogIssue): EvidenceFound {
+	return epic_bundle.names_as_blocker(from, to) ? {} : undefined
+}
+
+function reference_found(from: BacklogIssue, to: BacklogIssue): EvidenceFound {
+	const section = epic_bundle.reference_section(from, to)
+
+	return section === undefined ? undefined : { section }
 }
 
 // The two readings, each written as a directed test of one issue against another. Both are
@@ -34,14 +51,28 @@ interface OrderingEvidence {
 // `blocked-by` says so outright: the blocker has to land before the issue that declares it. A
 // reference says it by having been written — the issue that names another was drafted with that
 // other one already in existence, so the named one is the earlier of the two.
-const EVIDENCE_TESTS: ReadonlyArray<{
+interface EvidenceTest {
 	kind: EvidenceKind
-	holds: (from: BacklogIssue, to: BacklogIssue) => boolean
-}> = [
-	{ kind: 'dependency', holds: (from, to) => epic_bundle.names_as_blocker(from, to) },
-	{ kind: 'reference', holds: (from, to) => epic_bundle.names_in_body(from, to) },
+	find: (from: BacklogIssue, to: BacklogIssue) => EvidenceFound
+}
+
+const EVIDENCE_TESTS: ReadonlyArray<EvidenceTest> = [
+	{ kind: 'dependency', find: blocker_found },
+	{ kind: 'reference', find: reference_found },
 ]
 
+// One test in one direction: the fact it found, or none.
+function directed_evidence(
+	test: EvidenceTest,
+	from: BacklogIssue,
+	to: BacklogIssue,
+): Array<OrderingEvidence> {
+	const found = test.find(from, to)
+	if (found === undefined) return []
+
+	return [{ kind: test.kind, first: to.number, second: from.number, ...found }]
+}
+
 // Both directions of one pair, because both are facts. Two issues that name each other produce two
 // lines pointing opposite ways, which is the honest report: the reader is the one deciding.
 function pair_evidence(subject: BacklogIssue, other: BacklogIssue): Array<OrderingEvidence> {
@@ -50,10 +81,8 @@ function pair_evidence(subject: BacklogIssue, other: BacklogIssue): Array<Orderi
 		{ from: other, to: subject },
 	]
 
-	return EVIDENCE_TESTS.flatMap(({ kind, holds }) =>
-		directions
-			.filter((pair) => holds(pair.from, pair.to))
-			.map((pair) => ({ kind, first: pair.to.number, second: pair.from.number })),
+	return EVIDENCE_TESTS.flatMap((test) =>
+		directions.flatMap((pair) => directed_evidence(test, pair.from, pair.to)),
 	)
 }
 
@@ -85,8 +114,8 @@ function ordering_evidence(
 	return member_pairs(members).flatMap((pair) => pair_evidence(pair.left, pair.right))
 }
 
-// How each kind reads. `where` says the fact came from prose rather than from a recorded relation,
-// and the two `order_*` halves say how strongly the fact settles the order.
+// How each kind reads. The two `order_*` halves say how strongly the fact settles the order; where a
+// reference was read comes from the fact itself (`section_phrase`).
 //
 // **A recorded dependency states the order; a reference only points at it.** A `blocked-by` says
 // outright that the blocker lands first. A reference says it by having been written — which holds
@@ -95,20 +124,14 @@ function ordering_evidence(
 // the reference line reports the direction it points to and asserts nothing further; deciding is
 // still the reader's.
 const EVIDENCE_WORDING: Readonly<
-	Record<EvidenceKind, { verb: string; where: string; order_prefix: string; order_suffix: string }>
+	Record<EvidenceKind, { verb: string; order_prefix: string; order_suffix: string }>
 > = {
-	dependency: {
-		verb: 'is recorded as blocked by',
-		where: '',
-		order_prefix: '',
-		order_suffix: ' comes first',
-	},
-	reference: {
-		verb: 'names',
-		where: ' in its body',
-		order_prefix: 'that points to ',
-		order_suffix: ' first',
-	},
+	dependency: { verb: 'is recorded as blocked by', order_prefix: '', order_suffix: ' comes first' },
+	reference: { verb: 'names', order_prefix: 'that points to ', order_suffix: ' first' },
+}
+
+function section_phrase(item: OrderingEvidence): string {
+	return item.section === undefined ? '' : ` in its ${item.section}`
 }
 
 const EVIDENCE_HEADING = '  Evidence:'
@@ -117,12 +140,12 @@ const EVIDENCE_INDENT_WIDTH = 4
 const EVIDENCE_INDENT = ' '.repeat(EVIDENCE_INDENT_WIDTH)
 
 function format_one(item: OrderingEvidence): string {
-	const { verb, where, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
+	const { verb, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
 	const first = issue_cite.plain(item.first)
 	const second = issue_cite.plain(item.second)
 	const order = `${order_prefix}${first}${order_suffix}`
 
-	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${where} — ${order}`
+	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${section_phrase(item)} — ${order}`
 }
 
 // The block that goes under `Order:`. Empty when neither reading found anything, which leaves the

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

@@ -0,0 +1,116 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import {
+	epic_bundle,
+	type BacklogIssue,
+	type BundleAction,
+	type BundleDecision,
+} from './epic-bundle'
+import { epic_bundle_evidence } from './epic-bundle-evidence'
+import { epic_bundle_gaps } from './epic-bundle-gaps'
+import { format_dependency_links } from './epic-reference'
+
+// How `josh epic:bundle` words its verdict. Split out of `epic-bundle-cli.ts`, which reads the backlog,
+// when `--apply` pushed that file past its line ceiling; the wording has no reads of its own.
+
+const ACTION_LINES: Readonly<Record<string, string>> = {
+	add_to_epic: 'Add it to the epic that already tracks a related issue (Tier A — do it).',
+	create_epic: 'Create an epic for these (Tier A — do it).',
+	ask: 'Related issues sit in more than one epic: choose the one you recommend, add it, and record why (Tier A — do it).',
+	none: 'Nothing to bundle.',
+}
+
+// `Nothing to bundle.` is right when nothing was found, and wrong when an epic already tracks the
+// issue — there the answer is actionable: a caller looking for somewhere to put a prerequisite adds
+// it to *that* epic rather than creating a second one.
+const ALREADY_TRACKED_LINE = 'Already in an epic — add to that one, do not create a second.'
+
+function headline(decision: BundleDecision): string {
+	if (decision.action === 'none' && decision.epics.length > 0) return ALREADY_TRACKED_LINE
+
+	return ACTION_LINES[decision.action] ?? ''
+}
+
+function format_numbers(numbers: ReadonlyArray<number>): string {
+	return numbers.map((issue_number) => issue_cite.plain(issue_number)).join(', ')
+}
+
+// The backlog rows of the verdict's candidates — what the printed order and `--apply` both read.
+function members_of(
+	decision: BundleDecision,
+	backlog: ReadonlyArray<BacklogIssue>,
+): Array<BacklogIssue> {
+	return backlog.filter((issue) => decision.candidates.includes(issue.number))
+}
+
+// The order to record alongside the bundle. Bundling without it records the batch and loses the
+// reason it is a batch, so the recommendation carries it rather than leaving it to be remembered.
+function format_links(links: ReadonlyArray<{ blocker: number; blocked: number }>): string {
+	if (links.length === 0) return '  Order: none declared — do not invent one'
+
+	return `  Order: ${format_dependency_links(links)}`
+}
+
+function format_order(
+	decision: BundleDecision,
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+): Array<string> {
+	if (decision.action !== 'add_to_epic' && decision.action !== 'create_epic') return []
+	const members = members_of(decision, backlog)
+	const children = epic_bundle.bundle_children(subject, members)
+
+	// The evidence goes under the order rather than beside the verdict: what it explains is the
+	// order, and a reader checking one reads straight on into the other.
+	return [
+		`  Children: ${format_numbers(children)}`,
+		format_links(epic_bundle.bundle_dependency_links(subject, members)),
+		...epic_bundle_evidence.format_evidence(subject, members),
+	]
+}
+
+// The verdicts that put the subject into an epic. Each one asserts that no epic already tracks it —
+// `create_epic` asserts as much about the candidates too — and that negative is exactly what a cut
+// epic listing cannot establish. `none` is absent on purpose: it either
+// names the epic it *found* tracking the subject, which a cut cannot unseat, or reports no candidate
+// at all, which says nothing about epics.
+const PLACING_ACTIONS: ReadonlySet<BundleAction> = new Set<BundleAction>([
+	'add_to_epic',
+	'create_epic',
+	'ask',
+])
+
+// `is_membership_established` is what separates "no epic tracks these" from "their epics were never
+// read".
+function format_decision(
+	decision: BundleDecision,
+	subject: BacklogIssue,
+	backlog: ReadonlyArray<BacklogIssue>,
+	is_membership_established: boolean,
+): string {
+	if (!is_membership_established && PLACING_ACTIONS.has(decision.action)) {
+		return epic_bundle_gaps.unconfirmed_membership(format_numbers(decision.candidates)).join('\n')
+	}
+
+	const lines = [headline(decision), `  ${decision.reason}`]
+
+	if (decision.candidates.length > 0) {
+		lines.push(`  Related: ${format_numbers(decision.candidates)}`)
+	}
+
+	if (decision.epics.length > 1) {
+		lines.push(`  Epics involved: ${format_numbers(decision.epics)}`)
+	}
+
+	return [...lines, ...format_order(decision, subject, backlog)].join('\n')
+}
+
+const epic_bundle_format = {
+	ACTION_LINES,
+	ALREADY_TRACKED_LINE,
+	format_numbers,
+	format_order,
+	format_decision,
+	members_of,
+}
+
+export { epic_bundle_format }

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

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { epic_bundle_cli } from './epic-bundle-cli'
+
+// The `josh epic:bundle` entry, kept apart from `epic-bundle-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+//
+// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
+// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
+// command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
+// is in `scripts/cost-runtime/cost-main.ts`, which met the truncation first.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await epic_bundle_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -44,10 +44,21 @@ interface ReferencedLookups {
 	dropped: Array<number>
 }
 
+// Every number the body names, the ones a bundle signal counts first: the cap below must not leave a
+// signal unread because twenty background mentions came ahead of it in the body.
+function signal_first(subject: BacklogIssue): Array<number> {
+	const signals = epic_audit_logic
+		.signal_references(subject.body, subject.repo)
+		.map((reference) => reference.number)
+	const all = epic_audit_logic.parse_references(subject.body, subject.repo)
+
+	return [...new Set([...signals, ...all])]
+}
+
 function referenced_lookups(subject: BacklogIssue, known: ReadonlySet<number>): ReferencedLookups {
-	const candidates = epic_audit_logic
-		.parse_references(subject.body, subject.repo)
-		.filter((number) => number !== subject.number && !known.has(number))
+	const candidates = signal_first(subject).filter(
+		(number) => number !== subject.number && !known.has(number),
+	)
 
 	return {
 		numbers: candidates.slice(0, REFERENCED_LOOKUP_LIMIT),

package/scripts/epic/epic-bundle.ts

@@ -1,6 +1,6 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, RELEASE_LABEL } from '#scripts/issue/issue-labels'
-import { epic_audit_logic } from './epic-audit'
+import { epic_audit_logic, type SignalSection } from './epic-audit'
 import { epic_graph } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
 import type { IssueReference } from './epic-reference'
@@ -11,9 +11,9 @@ import type { IssueReference } from './epic-reference'
 // not reach the other way in: two issues filed days apart that turn out to be the front and back of
 // one job are executed separately, in whatever order, with the reasoning recorded nowhere.
 //
-// The candidate search reads issue references out of prose — the same reading `epic:audit` does
-// inside one epic. That analysis is imported rather than written a second time; the only
-// difference is what it is pointed at.
+// The candidate search reads issue references out of the acceptance criteria and the `parent: #N`
+// line — the same reading `epic:audit` does inside one epic. That analysis is imported rather than
+// written a second time; the only difference is what it is pointed at.
 
 // An open issue as the search sees it.
 interface BacklogIssue {
@@ -59,11 +59,19 @@ interface BundleDecision {
 	reason: string
 }
 
-// Whether `from`'s body names `to`. One direction of the citation test, because which direction it
-// was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced here rather than
-// written a second time there, so the candidate search and the evidence beside it cannot drift apart.
+// Where `from`'s body names `to` in a place that counts as a relation — its acceptance criteria or
+// its `parent: #N` line — or nothing. One direction of the citation test, because which direction
+// and which section it was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced
+// here rather than written a second time there, so the candidate search and the evidence beside it
+// cannot drift apart. A number written only as the background of a filing is not a relation.
+function reference_section(from: BacklogIssue, to: BacklogIssue): SignalSection | undefined {
+	return epic_audit_logic
+		.signal_references(from.body, from.repo)
+		.find((reference) => reference.number === to.number)?.section
+}
+
 function names_in_body(from: BacklogIssue, to: BacklogIssue): boolean {
-	return epic_audit_logic.parse_references(from.body, from.repo).includes(to.number)
+	return reference_section(from, to) !== undefined
 }
 
 // Whether two issues cite each other, in either direction. A one-way citation is enough: the point
@@ -324,7 +332,7 @@ function bundle_children(
 
 const epic_bundle = {
 	names_as_blocker,
-	names_in_body,
+	reference_section,
 	NO_SIGNAL_REASON,
 	already_tracked_reason,
 	has_recorded_dependency,

package/scripts/epic/epic-busy.ts

@@ -1,12 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import {
-	ALREADY_DONE_LABEL,
-	has_any_label,
-	IN_PROGRESS_LABEL,
-	NEEDS_DECISION_LABEL,
-} from '#scripts/issue/issue-labels'
+import { has_any_label, IN_PROGRESS_LABEL, PARKED_LABELS } from '#scripts/issue/issue-labels'
 import { session_cite } from '#scripts/issue/session-cite'
 
 // How much of a repository's parallelism is already spoken for — asked of the *repository*, never of
@@ -34,12 +29,10 @@ const LISTING_LIMIT = 100
 // Read through `has_any_label` rather than compared directly, for the casing reason
 // `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
 //
-// `already-done` joins `needs-decision` here for the same reason it joins it in
-// `epic_classify.local_category`: the run that applied it committed
-// nothing, so the checkout it ran in is clean and there is no uncommitted work for the next child to
-// start on top of. That is exactly what separates both from `needs-human-review`, which is
-// deliberately not parked because its work is still sitting in the tree.
-const PARKED_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+// The park labels (`PARKED_LABELS`): `already-done` and `run:stalled` join `needs-decision` here for
+// the same reason they join it in `epic_classify.local_category`: the run that applied one leaves no
+// uncommitted work for the next child to start on top of. That is exactly what separates them from
+// `needs-human-review`, which is deliberately not parked because its work is still sitting in the tree.
 
 // What one repository answered. `unreadable` is kept apart from `idle` because reading a failed
 // read as an empty listing is a confident absence