@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,472 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import type { IssueReference } from '#scripts/git/git-epic-reference'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { z } from 'zod'
+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 { 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'
+
+// `josh epic:bundle <N>` — after an issue is filed, look at the open backlog and say whether it
+// belongs with something already there (joshuafolkken/kit#873).
+//
+// 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.
+
+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 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.'
+
+// The backlog listing asks for the title too (joshuafolkken/kit#1252). Kept apart from the epic
+// listing's schema rather than made optional on one: the epic listing does not ask for the field, and
+// a schema that tolerates its absence everywhere would let a missing title pass unnoticed here.
+//
+// `blocked_by_count` is the blocker count GitHub already puts in the listing response
+// (joshuafolkken/kit#1736). It is **nullish rather than defaulted**, and that is the whole safety of
+// the read below: a row the listing carries no summary for must not be read as a row with no
+// blockers, because that reading is what would silently drop a relation instead of costing a
+// request. Nothing in today's pipeline is expected to arrive without one — the response carries the
+// summary on every issue, and `git-gh-issue-list.ts` filters pull requests, which are what lack it,
+// out client-side — so this tolerates a shape the listing is not supposed to hand over rather than
+// describing one it does.
+const backlog_schema = epic_schema.extend({
+	title: z.string().nullable(),
+	blocked_by_count: z.number().nullish(),
+})
+
+type BacklogRow = z.infer<typeof backlog_schema>
+
+// The epic index is `epic-index.ts`'s, shared with the `auto-ok` pickup since
+// joshuafolkken/kit#1633: both commands ask which epic tracks an issue, and a second copy of the
+// task-list read would answer differently the first time that shape moved.
+const { build_epic_index } = epic_index
+
+function to_epic_field(epic: number | undefined): { epic?: number } {
+	return epic === undefined ? {} : { epic }
+}
+
+// Undefined when the read failed, which the caller reports — as opposed to an issue that genuinely
+// declares no relations, which is an empty array.
+async function epic_issue_relations(
+	issue_number: string,
+	repo: string,
+): Promise<Array<IssueReference> | undefined> {
+	const parsed = epic_issue.parse_epic_issue(
+		await git_gh_command.issue_get_state_and_relations(issue_number),
+	)
+
+	return parsed === undefined ? undefined : epic_issue.blocker_references_of(parsed, repo)
+}
+
+// One read per backlog issue *that has blockers*, a few at a time.
+//
+// Since joshuafolkken/kit#1024 a read is `gh api`: one REST request for the issue, and a second to
+// its `dependencies/blocked_by` endpoint unless the issue's own dependency summary reports exactly
+// zero blockers. That second request was already skipped on a zero; the first one was not, so the
+// command still paid one request for every open issue in the repository — a cost that grows with the
+// backlog and made the command heavier exactly as more issues made it more useful
+// (joshuafolkken/kit#1736). The listing that produced these rows already carries that same summary,
+// so the zero is known *before* the read rather than inside it, and the read is skipped outright.
+//
+// One read would do if `gh` exposed the reverse of `blockedBy`, but it does not (`blocks` is not a
+// JSON field), so a dependency declared on the *other* issue is only visible by asking that issue.
+// Spawning all of them at once is what turns a rate limit into a wrong answer: a refused read becomes
+// an empty relation list, and a bundle that should have been proposed is reported as "no strong
+// signal" instead. Batching bounds the burst; the `unreadable` list below is what keeps a refused
+// read from passing as an answer (joshuafolkken/kit#873). The pool itself is `bounded-pool.ts`,
+// shared with the reference reads below it and with the eval suite (joshuafolkken/kit#1144).
+const RELATION_CONCURRENCY = 8
+const NO_BLOCKERS = 0
+
+// GitHub's own count, not an inference from what was read. Strictly `=== 0`, so a row carrying no
+// summary at all answers `false` and keeps its read: an absent count says nothing about whether the
+// issue has blockers, and treating the two alike is the one way this shortcut could lose a
+// relation. Skipping is cheap and wrong-in-silence; reading is a request and always right.
+function has_no_blockers(row: BacklogRow): boolean {
+	return row.blocked_by_count === NO_BLOCKERS
+}
+
+// Every row still gets an entry, in order, so the index alignment `fetch_backlog` relies on is the
+// same whether a row was read or answered from the listing.
+async function fetch_relations(
+	rows: ReadonlyArray<BacklogRow>,
+	repo: string,
+): Promise<Array<Array<IssueReference> | undefined>> {
+	return await bounded_pool.bounded_map(rows, RELATION_CONCURRENCY, async (row) =>
+		has_no_blockers(row) ? [] : await epic_issue_relations(String(row.number), repo),
+	)
+}
+
+// The open backlog, with each issue's relations and the epic tracking it. `unreadable` names the
+// issues whose relations could not be read, so a "nothing to bundle" verdict is never quietly based
+// on data that never arrived.
+interface FetchedBacklog {
+	issues: Array<BacklogIssue>
+	unreadable: Array<number>
+	is_readable: boolean
+	// Why the backlog listing stopped short, or that it did not. A `ScanCutoff` rather than a flag
+	// since joshuafolkken/kit#1067: the page ceiling now bounds this listing too, and the two cutoffs
+	// cite different numbers.
+	cutoff?: ScanCutoff
+	has_epic_list?: boolean
+	// The epic listing's own cutoff. Separate from `cutoff`, which is the backlog listing's: the two
+	// hide different things, so a caller told only "something was truncated" cannot tell whether the
+	// epic that tracks a candidate was among what it could not see.
+	epic_cutoff?: ScanCutoff
+	// The epic view, kept so a referenced issue read afterwards can be placed without a second read.
+	context?: ReferencedContext
+}
+
+// One listing row as the bundler reads it. Split from the fetch so that function stays a list of
+// requests rather than a request list plus a row mapping.
+function to_backlog_issue(
+	row: { number: number; title?: string | null; body?: string | null },
+	context: { repo: string; epics: Map<number, number>; epic_numbers: ReadonlySet<number> },
+	blocked_by: ReadonlyArray<IssueReference>,
+): BacklogIssue {
+	return {
+		number: row.number,
+		repo: context.repo,
+		title: row.title ?? '',
+		body: row.body ?? '',
+		blocked_by,
+		is_epic: context.epic_numbers.has(row.number),
+		...to_epic_field(context.epics.get(row.number)),
+	}
+}
+
+// What a caller does not need read for it. `issue:scout` asks about an issue that does not exist yet:
+// it has no number, so no recorded dependency can name it and it declares none of its own — the
+// relation reads cannot change its answer, and skipping them takes one request per open issue off the
+// command a run makes before every filing (joshuafolkken/kit#1252). `epic:bundle` leaves it unset and
+// reads them exactly as before.
+interface BacklogOptions {
+	include_relations?: boolean
+}
+
+// The relations, or an empty list each when the caller asked for none. Every issue still gets a row,
+// so the index alignment `fetch_backlog` relies on holds either way.
+async function read_relations(
+	rows: ReadonlyArray<BacklogRow>,
+	repo: string,
+	options: BacklogOptions | undefined,
+): Promise<Array<Array<IssueReference> | undefined>> {
+	if (options?.include_relations === false) return rows.map(() => [])
+
+	return await fetch_relations(rows, repo)
+}
+
+async function fetch_backlog(
+	repo: string,
+	epics: Map<number, number>,
+	epic_numbers: ReadonlySet<number> = new Set(epics.values()),
+	options?: BacklogOptions,
+): Promise<FetchedBacklog> {
+	const { json, is_capped } = await git_gh_command.issue_list_open_bodies(BACKLOG_LIMIT)
+	// A failed listing is not an empty backlog. Reported rather than degraded into one, which would
+	// have a `gh` failure arrive as "that issue does not exist".
+	if (json === undefined) return { issues: [], unreadable: [], is_readable: false }
+	// Same reason as `fetch_epics`: an unparseable listing is not an empty backlog.
+	const rows = parse_json_array_or_undefined(json, backlog_schema)
+	if (rows === undefined) return { issues: [], unreadable: [], is_readable: false }
+	const relations = await read_relations(rows, repo, options)
+
+	return {
+		is_readable: true,
+		// Either cutoff hides the same thing: a related issue past it, reported as "no existing issue
+		// shares a reference" — an assertion about data that was never loaded.
+		cutoff: cutoff_of(rows.length, BACKLOG_LIMIT, is_capped),
+		issues: rows.map((row, index) =>
+			to_backlog_issue(row, { repo, epics, epic_numbers }, relations[index] ?? []),
+		),
+		unreadable: rows.filter((_, index) => relations[index] === undefined).map((row) => row.number),
+	}
+}
+
+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 (joshuafolkken/kit#943).
+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] ?? ''
+}
+
+// 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 —
+// confidently, and with exit 0 (joshuafolkken/kit#950).
+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) => `#${String(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'
+	const arrows = links.map((link) => `#${String(link.blocker)} -> #${String(link.blocked)}`)
+
+	return `  Order: ${arrows.join(', ')}`
+}
+
+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 (joshuafolkken/kit#1737).
+	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 (joshuafolkken/kit#1697). `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()
+
+	if (open_epics === undefined) {
+		return { issues: [], unreadable: [], is_readable: false, has_epic_list: false }
+	}
+
+	const epics = build_epic_index(open_epics.epics)
+	// From the epic list itself, not from the index's values: an epic tracking no child yet has no
+	// entry in the index, and would enter the backlog as an ordinary issue that its own children then
+	// propose bundling with (joshuafolkken/kit#873).
+	const epic_numbers = new Set(open_epics.epics.map((epic) => epic.number))
+
+	return {
+		...(await fetch_backlog(repo, epics, epic_numbers, options)),
+		has_epic_list: true,
+		epic_cutoff: open_epics.cutoff,
+		context: { repo, epics, epic_numbers },
+	}
+}
+
+// The backlog the decision is made from: the open listing, plus the referenced issues it could not
+// show. Without the second half the command answers about a window that closes minutes after the
+// follow-up issue is filed (joshuafolkken/kit#947).
+async function widen_with_referenced(
+	subject: BacklogIssue,
+	backlog: FetchedBacklog,
+): Promise<FetchedBacklog> {
+	const { context } = backlog
+	if (context === undefined) return backlog
+	// An issue an epic already tracks has nothing to bundle — `decide_bundle` answers from that alone
+	// and never looks at the candidates. Widening first spends a request per reference on a verdict
+	// that ignores them, and prints "⚠ Could not read #891." above "Already in an epic", which reads
+	// as a gap in an answer the read was never part of.
+	if (subject.epic !== undefined) return backlog
+	const known = new Set(backlog.issues.map((issue) => issue.number))
+	const found = await epic_bundle_referenced.referenced_candidates(subject, known, context)
+	if (found === undefined) return backlog
+
+	return {
+		...backlog,
+		issues: [...backlog.issues, ...found.issues],
+		unreadable: [...backlog.unreadable, ...found.unreadable],
+	}
+}
+
+// Why nothing could be recommended, when the backlog could not be read. A failed listing is not an
+// empty backlog: degrading it into one had a `gh` failure arrive as "that issue does not exist".
+function unreadable_backlog_message(backlog: FetchedBacklog): string {
+	return backlog.has_epic_list === false
+		? 'Could not list the open epics; no recommendation was made.'
+		: 'Could not list the open issues; no recommendation was made.'
+}
+
+const NO_CUTOFF: ScanCutoff = 'none'
+
+function warn_cutoff(message: string | undefined): void {
+	if (message !== undefined) console.error(message)
+}
+
+// What the read could not cover, so a verdict is never quietly based on data that never arrived. The
+// wording of each gap is `epic-bundle-gaps.ts`'s; what stays here is which gaps this command has.
+function warn_about_gaps(backlog: FetchedBacklog): void {
+	if (backlog.unreadable.length > 0) {
+		console.error(`⚠ Could not read ${format_numbers(backlog.unreadable)}.`)
+	}
+
+	warn_cutoff(epic_bundle_gaps.backlog_gap(backlog.cutoff ?? NO_CUTOFF, BACKLOG_LIMIT))
+	warn_cutoff(epic_bundle_gaps.epic_gap(backlog.epic_cutoff ?? NO_CUTOFF, BACKLOG_LIMIT))
+}
+
+function report_decision(subject: BacklogIssue, backlog: FetchedBacklog, repo: string): 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)
+
+	// The `Related:` / `Children:` listings name issues as `#N`; linkified here so the recommendation a
+	// run copies into its reply carries clickable references rather than bare ones (joshuafolkken/kit#2329).
+	const report = format_decision(decision, subject, others, is_established)
+
+	console.info(issue_citation.linkify(report, repo))
+
+	return SUCCESS_EXIT_CODE
+}
+
+// Widen, report what the read could not cover, then decide. Split out of `report_for`, which is
+// otherwise all guard clauses.
+async function report_widened(
+	subject: BacklogIssue,
+	backlog: FetchedBacklog,
+	repo: string,
+): Promise<number> {
+	const widened = await widen_with_referenced(subject, backlog)
+
+	warn_about_gaps(widened)
+
+	return report_decision(subject, widened, repo)
+}
+
+// The recommendation for one issue, from the open backlog around it.
+async function report_for(issue_number: number, repo: string): Promise<number> {
+	const backlog = await read_backlog(repo)
+
+	if (!backlog.is_readable) {
+		console.error(unreadable_backlog_message(backlog))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const subject = backlog.issues.find((issue) => issue.number === issue_number)
+
+	if (subject === undefined) {
+		console.error(`#${String(issue_number)} is not an open issue in ${repo}.`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report_widened(subject, backlog, repo)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = epic_issue.parse_epic_number(argv[0])
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const repo = await git_gh_command.repo_get_name_with_owner()
+
+	// A repository that could not be read is refused rather than stood in for. Since
+	// joshuafolkken/kit#1130 the members are keyed by repository and the blockers carry their own, so a
+	// placeholder matches nothing: every recorded dependency would vanish and the command would answer
+	// `Nothing to bundle.` with exit 0 — a confident verdict built on a read that failed, on the
+	// command a run consults before deciding an issue belongs nowhere.
+	if (repo === undefined) {
+		console.error(UNKNOWN_REPO_MESSAGE)
+
+		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 (joshuafolkken/kit#1005).
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const epic_bundle_cli = {
+	USAGE,
+	BACKLOG_LIMIT,
+	ACTION_LINES,
+	ALREADY_TRACKED_LINE,
+	build_epic_index,
+	format_numbers,
+	format_order,
+	unreadable_backlog_message,
+	read_backlog,
+	report_for,
+	fetch_epics,
+	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

@@ -0,0 +1,147 @@
+import { epic_bundle, type BacklogIssue } from './epic-bundle'
+
+// The facts the bundle decision was already made from, printed beside the order it prints
+// (joshuafolkken/kit#1737).
+//
+// `is_strong_signal` reads exactly two things — whether a body names the other issue's number, and
+// whether a `blocked-by` is already recorded in either direction — and neither ever reached the
+// output. What did reach it was the verdict and, where relations happened to be recorded, the
+// arrows. So confirming "should this issue really follow #123" meant opening both issue bodies and
+// re-deriving by hand what the command had just finished reading. The facts cost nothing to fetch a
+// second time: they are in hand at the moment the verdict is composed.
+//
+// **It states the facts and the direction they point, and stops there.** No line here says where to
+// put the issue and none composes a command to run: ordering depends on intent, so a machine that
+// decided it would write a confident order nobody's data supports. What is added is the material for
+// the judgement, not the judgement.
+
+// Which of the two readings a line came from. Kept apart in the data rather than only in the
+// wording, so a caller can tell a recorded relation from a sentence somebody wrote.
+type EvidenceKind = 'dependency' | 'reference'
+
+// One fact, and the order it points to. `first` is the issue the fact puts ahead of `second`.
+interface OrderingEvidence {
+	kind: EvidenceKind
+	first: number
+	second: number
+}
+
+// The two readings, each written as a directed test of one issue against another. Both are
+// `epic-bundle.ts`'s own, called rather than restated: the candidate search decides from exactly
+// these, and a second spelling here would let the two disagree about what a signal is.
+//
+// **Both put the named issue first, and that is why one shape covers them.** A recorded
+// `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<{
+	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) },
+]
+
+// 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> {
+	const directions = [
+		{ from: subject, to: other },
+		{ 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 })),
+	)
+}
+
+// Every unordered pair of the bundle's members.
+//
+// **The pairs are the ones `bundle_dependency_links` walks, not the subject's alone.** That function
+// builds its member set as `[subject, ...candidates]` and emits an arrow for any pair of them, so an
+// arrow between two candidates is ordinary — and evidence taken over the subject's pairs would leave
+// exactly that arrow unexplained, which is the gap this whole block exists to close.
+function member_pairs(
+	members: ReadonlyArray<BacklogIssue>,
+): Array<{ left: BacklogIssue; right: BacklogIssue }> {
+	return members.flatMap((left, index) =>
+		members.slice(index + 1).map((right) => ({ left, right })),
+	)
+}
+
+// Every fact behind the bundle, over the members the order is drawn from.
+//
+// The repository filter is the one `bundle_dependency_links` applies: a bare number declared in a
+// member elsewhere would be resolved against this repository by the epic body, naming a different
+// issue entirely (joshuafolkken/kit#1130).
+function ordering_evidence(
+	subject: BacklogIssue,
+	candidates: ReadonlyArray<BacklogIssue>,
+): Array<OrderingEvidence> {
+	const members = [subject, ...candidates].filter((member) => member.repo === subject.repo)
+
+	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.
+//
+// **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
+// while a body is written once and stops holding the moment somebody edits an older issue to add a
+// backlink to a newer one, as the review round cap and the upstream-interrupt rules both require. So
+// 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 }>
+> = {
+	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',
+	},
+}
+
+const EVIDENCE_HEADING = '  Evidence:'
+// One step deeper than the heading, which is itself indented under the verdict.
+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 first = `#${String(item.first)}`
+	const second = `#${String(item.second)}`
+	const order = `${order_prefix}${first}${order_suffix}`
+
+	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${where} — ${order}`
+}
+
+// The block that goes under `Order:`. Empty when neither reading found anything, which leaves the
+// existing `none declared — do not invent one` wording standing on its own.
+function format_evidence(
+	subject: BacklogIssue,
+	candidates: ReadonlyArray<BacklogIssue>,
+): Array<string> {
+	const found = ordering_evidence(subject, candidates)
+	if (found.length === 0) return []
+
+	return [EVIDENCE_HEADING, ...found.map((item) => format_one(item))]
+}
+
+const epic_bundle_evidence = {
+	EVIDENCE_HEADING,
+	ordering_evidence,
+	format_evidence,
+}
+
+export type { EvidenceKind, OrderingEvidence }
+export { epic_bundle_evidence }