@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/epic/epic-audit-checks.ts

@@ -1,3 +1,4 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import {
 	epic_audit_logic,
 	type AuditFinding,
@@ -8,19 +9,18 @@ import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 import { epic_nested } from './epic-nested'
 
 // The five cross-child checks. Each takes the children and returns findings — four of them reading
-// the bodies, and the fifth (joshuafolkken/kit#1476) reading a child's labels instead.
+// the bodies, and the fifth reading a child's labels instead.
 //
 // Warnings and errors are kept apart deliberately. An error is a contradiction that will stall the
 // implementation whatever anyone decides — an acceptance criterion that needs something built later.
 // A warning is a thing a reader has to look at: a child mentioning another child may be a real
 // missing dependency or a perfectly good design note about what comes next, and the machine cannot
 // tell. Making that an error would make legitimate notes unwritable, so the machine's job is to
-// stop the omission going unnoticed, not to decide (joshuafolkken/kit#870).
+// stop the omission going unnoticed, not to decide.
 //
 // Every reference these checks read carries the repository it lives in, and every match is on
 // repository and number both. A number alone names a different issue in every repository, so a
-// cross-repository child citing `#40` was checked against *this* repository's issue 40
-// (joshuafolkken/kit#1014).
+// cross-repository child citing `#40` would be checked against *this* repository's issue 40.
 
 const IMPLICIT_DEPENDENCY = 'implicit dependency'
 const ORDER_CONTRADICTION = 'order contradiction'
@@ -61,14 +61,9 @@ function find_sibling(
 
 // Whether anything orders these two, in either direction.
 //
-// A pair in two different repositories used to be treated as ordered, unconditionally. That was not a
-// statement about the pair but about what could be recorded: `blocked_by` was read as bare numbers,
-// so a cross-repository order could not be written onto the graph at all, and reporting one as a
-// contradiction would have failed the audit with no edit to either issue that could ever clear it.
-// joshuafolkken/kit#1126 made such an order recordable and readable, so the premise stopped holding
-// and joshuafolkken/kit#1128 removed the exemption: every pair is asked the same question now, and
-// `depends_on` walks a cross-repository chain by identity exactly as it walks a local one. What keeps
-// that from failing epics written before the capability existed is the finding's *level* rather than
+// Every pair is asked the same question, a cross-repository pair included: `depends_on` walks a
+// cross-repository chain by identity exactly as it walks a local one. What keeps that from failing
+// epics written before a cross-repository order was recordable is the finding's *level* rather than
 // a blind spot — see `order_level`.
 function is_ordered(
 	index: ReadonlyMap<string, EpicChild>,
@@ -131,9 +126,8 @@ function reported_pairs(
 // Check 1 — a child talks about another child, and neither declares a dependency on the other.
 //
 // A declared dependency in *either* direction is enough: `#864 depends on #863` makes `#863`'s note
-// about `#864` an ordinary forward reference. What this catches is the shape found in
-// joshuafolkken/kit#858 — two children each citing the other's deliverable, with `blocked_by` empty
-// on both and the epic declaring them independent.
+// about `#864` an ordinary forward reference. What this catches is two children each citing the
+// other's deliverable, with `blocked_by` empty on both and the epic declaring them independent.
 function find_implicit_dependencies(
 	children: ReadonlyArray<AuditChild>,
 	current_repo: string,
@@ -157,28 +151,24 @@ function find_implicit_dependencies(
 
 // Check 2 — a child's acceptance criteria name another child, with no dependency in either
 // direction. The criteria are where a child states what it must deliver, so a name there with
-// nothing ordering the two is the contradiction found by hand in joshuafolkken/kit#858: the criteria
-// required deliverables of children the graph let it run before.
+// nothing ordering the two is a contradiction: the criteria require deliverables of children the
+// graph lets it run before.
 //
 // A declared dependency the *other* way is suppressed, and that suppression is what keeps the check
 // honest. `#860`'s criteria say `#864` will extend a hook it provides, and `#864` is declared to
-// depend on `#860` — a forward reference, and satisfiable exactly as written. Verified against the
-// real epic: without this, four of the run's five errors were forward references of that shape.
+// depend on `#860` — a forward reference, and satisfiable exactly as written.
 //
 // The level depends on whether the pair can still run out of order. What makes an undeclared order a
 // contradiction is that the criteria's child *can run first*, and **either end closing is enough to
 // make that sentence false**: a closed naming child has already run, and a closed named child has
 // already delivered what the criteria ask for, so nothing is left to run before it. An epic that ever
 // forgot to declare an order would otherwise fail its audit forever — which stops every future
-// `epicrun` on it at the first step, for something that can no longer stall anything. Confirmed on the
-// real epic: `epic:next` handed back a runnable child while the audit was red.
+// `epicrun` on it at the first step, for something that can no longer stall anything.
 //
-// **The condition used to be both ends closed**, and that was stricter than the sentence it encodes
-// (joshuafolkken/kit#1597). It bit on the ordinary way an epic's children cite each other — a closed
-// child's criteria naming an open sibling **as evidence** — and there is no way out of it once the
-// naming child has closed: the alternatives are editing a closed body to remove the numbers or
-// declaring an order nobody decided, and both destroy the record. joshuafolkken/kit#1262 sat red on
-// exactly that shape while nothing in it could run out of order.
+// **One closed end is enough, not both.** Requiring both would bite on the ordinary way an epic's
+// children cite each other — a closed child's criteria naming an open sibling **as evidence** — and
+// there is no way out of it once the naming child has closed: the alternatives are editing a closed
+// body to remove the numbers or declaring an order nobody decided, and both destroy the record.
 //
 // **Demoted rather than dropped**, and the choice is not cosmetic. Dropping the finding does not
 // shorten the report: the acceptance criteria are part of the body, so the same pair falls straight
@@ -232,16 +222,16 @@ function order_message(
 // **Either child closed**: the pair can no longer run out of order, so the finding cannot describe
 // anything that will happen.
 //
-// **A pair in two repositories** (joshuafolkken/kit#1128): that order only became recordable with
-// joshuafolkken/kit#1126, so an error would fail the audit `epicrun` runs before its first child and
-// stop every epic written before it — joshuafolkken/kit#1010 is what that looks like.
+// **A pair in two repositories**: epics written before a cross-repository order was recordable
+// carry such pairs, so an error would fail the audit `epicrun` runs before its first child and stop
+// every one of them.
 //
 // **Be clear about what the warning does and does not buy.** It does *not* make the run safe: the
 // finding fires precisely when nothing orders the pair, so there is no relation for `epic:next` to
-// read and the child is offered as runnable — it can start before the work it cites. What changed is
-// that this was previously *silent*, and is now said out loud. Making it safe means stopping, and
-// stopping is what the recorded decision declined for epics that predate the capability. Clearing one
-// means recording the relation; `josh epic --add` cannot write it yet (joshuafolkken/kit#1138), so
+// read and the child is offered as runnable — it can start before the work it cites. It makes the gap
+// said out loud rather than silent. Making it safe means stopping, and stopping is what the recorded
+// decision declined for epics that predate the capability. Clearing one
+// means recording the relation; `josh epic --add` cannot write it yet, so
 // until then it is the `dependencies/blocked_by` endpoint by hand.
 function order_level(child: AuditChild, other: AuditChild, is_settled: boolean): FindingLevel {
 	if (is_settled) return 'warning'
@@ -349,11 +339,11 @@ function find_orphans(
 		.map((issue_number) => ({
 			level: 'warning' as const,
 			check: ORPHAN_CHILD,
-			message: `#${String(issue_number)} names this epic as its parent but is not in its task list.`,
+			message: `${issue_cite.plain(issue_number)} names this epic as its parent but is not in its task list.`,
 		}))
 }
 
-// Check 5 — a task-list row pointing at another epic (joshuafolkken/kit#1476). What the question is,
+// Check 5 — a task-list row pointing at another epic. What the question is,
 // and what it deliberately is not, is `epic-nested.ts`; this half is what the audit does with the
 // answer.
 //
@@ -392,7 +382,7 @@ function find_nested_epics(
 
 // Check 6 — the epic itself is closed while children it tracks are still open. Unlike the five
 // checks above, this one reads the *root's* state against its children rather than the children
-// against each other (joshuafolkken/kit#2337).
+// against each other.
 //
 // **An error, not a warning.** A closed epic never surfaces its children in the backlog — the epic
 // opt-in only fires while the epic is open — so an open child of a closed epic is stranded: it is

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

@@ -2,6 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_read } from '#scripts/issue/issue-read'
+import { session_cite } from '#scripts/issue/session-cite'
+import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_audit_logic, type AuditFinding, type ReferenceState } from './epic-audit'
 import { epic_audit_checks, type AuditChild } from './epic-audit-checks'
 import { epic_audit_orphans, type ClaimingSearch } from './epic-audit-orphans'
@@ -16,15 +18,14 @@ import { epic_next } from './epic-next'
 import { epic_parse, type DependencyLink } from './epic-parse'
 
 // `josh epic:audit <E>` — read an epic's children against each other and report what contradicts
-// what (joshuafolkken/kit#870).
+// what.
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh epic:audit <epic-number>'
 // Check 3 filters the issues the children cite down to this owner's repositories, so a repository
 // name it could not read silently dropped every qualified reference and reported nothing. A check
-// that disables itself without saying so is worse than one that fails: the report reads clean
-// (joshuafolkken/kit#1016).
+// that disables itself without saying so is worse than one that fails: the report reads clean.
 const UNREADABLE_REPO =
 	'Could not read this repository as `owner/name`, so a reference could not be resolved against it — check `gh auth status` and that this checkout has a GitHub remote.'
 
@@ -35,7 +36,7 @@ const UNREADABLE_REPO =
 // The scope comes from `epic_fetch.scope_for`, the same convention the state and relation reads
 // follow, rather than a second spelling here. Without it a cross-repository child's body was read
 // from *this* repository's issue of that number, and all four body-reading checks then ran against
-// the wrong text (joshuafolkken/kit#1012).
+// the wrong text.
 async function attach_bodies(
 	children: ReadonlyArray<AuditChild>,
 	repo: string,
@@ -59,7 +60,7 @@ async function attach_bodies(
 // Each one is asked of the repository whose body named it, through the same `epic_fetch.scope_for`
 // every other read goes through, and the answers are keyed by that repository and number both. Asked
 // unqualified, a cross-repository child's `#40` was answered by *this* repository's issue 40 — a
-// different issue, whose state then decided the warning (joshuafolkken/kit#1014).
+// different issue, whose state then decided the warning.
 async function resolve_reference_states(
 	referenced: ReadonlyArray<IssueReference>,
 	current_repo: string,
@@ -85,8 +86,8 @@ async function resolve_reference_states(
 
 // The issues the children cite that are not children themselves — the ones check 3 resolves.
 //
-// A reference in a repository this owner does not own is left out rather than probed, inheriting
-// joshuafolkken/kit#869's restriction exactly as `fetch_external_children` does: a body mentioning a
+// A reference in a repository this owner does not own is left out rather than probed, exactly as
+// `fetch_external_children` does: a body mentioning a
 // third party's issue must not send this command to their tracker.
 function outside_references(
 	children: ReadonlyArray<AuditChild>,
@@ -110,14 +111,14 @@ interface AuditInput {
 	epic_number: number
 	// The `owner/repo` the command runs in. A reference is written bare when it names an issue here
 	// and `owner/repo#N` when it does not, so the reader is never handed a number that resolves
-	// somewhere else (joshuafolkken/kit#1014).
+	// somewhere else.
 	repo: string
 	children: ReadonlyArray<AuditChild>
 	tracked: ReadonlyArray<number>
 	reference_states: ReadonlyMap<string, ReferenceState>
 	// The orphan search's whole outcome, not just what it found: a listing that failed and a listing
 	// the page ceiling cut short are both reported, because `[]` here is indistinguishable from
-	// "nothing claims this epic" (joshuafolkken/kit#1033).
+	// "nothing claims this epic".
 	claiming: ClaimingSearch
 	anomalies: ReadonlyArray<AuditFinding>
 	// Computed before the implicit-dependency check so that check can skip the pairs already reported
@@ -125,15 +126,14 @@ interface AuditInput {
 	// arrive twice.
 	contradictions: ReadonlyArray<AuditFinding>
 	// The declared orders check 6 may speak about, already resolved to children and narrowed to the
-	// open, local pairs (joshuafolkken/kit#1712).
+	// open, local pairs.
 	order_pairs: ReadonlyArray<OrderPair>
 	// The epic's `## Decisions` section, and the comments on those pairs' ends — the two places a
 	// placement decision is recorded, and therefore the whole of what check 6 reads.
 	decisions: string
 	order_comments: ReadonlyMap<string, ReadonlyArray<string>>
 	// Whether the epic's own state is confirmed closed. An unreadable state is `false`, so the
-	// closed-epic-with-open-children check never fires on a lookup that did not answer
-	// (joshuafolkken/kit#2337).
+	// closed-epic-with-open-children check never fires on a lookup that did not answer.
 	is_epic_closed: boolean
 }
 
@@ -186,7 +186,7 @@ function audit(input: AuditInput): AuditResult {
 	])
 }
 
-// The graph anomalies, taken from joshuafolkken/kit#860's detection rather than re-derived here —
+// The graph anomalies, taken from the graph's own detection rather than re-derived here —
 // including its rule for whether the body declares an order at all, which is imported rather than
 // restated for exactly the drift this comment warns about.
 function graph_anomalies(
@@ -242,18 +242,18 @@ async function read_order_comments(
 	)
 }
 
-// Why a snapshot yields nothing to audit, with the two reasons told apart (joshuafolkken/kit#1690).
+// Why a snapshot yields nothing to audit, with the two reasons told apart.
 // A body nobody could read parses to zero children exactly as an unpopulated task list does, so
 // without this the audit reported an epic it never read as one tracking no children — and sent the
 // reader to fill in a task list that is already there.
 function no_children_reason(snapshot: EpicSnapshot, epic_number: number): string | undefined {
+	const epic = session_cite.issue(epic_number, undefined, snapshot.repo)
+
 	if (snapshot.body_failure !== undefined) {
-		return `Could not read the body of #${String(epic_number)}. Its task list is what names the children — check \`gh auth status\` and the connection.`
+		return `Could not read the body of ${epic}. Its task list is what names the children — check \`gh auth status\` and the connection.`
 	}
 
-	if (snapshot.child_numbers.length === 0) {
-		return `#${String(epic_number)} tracks no children in a task list.`
-	}
+	if (snapshot.child_numbers.length === 0) return `${epic} tracks no children in a task list.`
 
 	return undefined
 }
@@ -261,8 +261,7 @@ function no_children_reason(snapshot: EpicSnapshot, epic_number: number): string
 // Whether the epic's own state is confirmed closed. Read through the same `scope_for` every other
 // read goes through, so a cross-repository epic is asked of its own repository rather than this one.
 // A read that came back shaped wrong, or a state that is not `CLOSED`, both answer `false`: the
-// finding it feeds is an error, and one must never be manufactured from a lookup that did not answer
-// (joshuafolkken/kit#2337).
+// finding it feeds is an error, and one must never be manufactured from a lookup that did not answer.
 async function read_epic_closed(epic_number: number, scope?: string): Promise<boolean> {
 	const raw = await git_gh_command.issue_get_state_and_relations(String(epic_number), scope)
 	const parsed = epic_issue.parse_epic_issue(raw)
@@ -322,7 +321,7 @@ async function report_audit(epic_number: number, repo: string): Promise<number>
 	if (input === undefined) return FAILURE_EXIT_CODE
 	const result = audit(input)
 
-	console.info(epic_audit_report.format_report(result))
+	console.info(issue_citation.linkify(epic_audit_report.format_report(result), repo))
 
 	return result.exit_code
 }
@@ -350,7 +349,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 // `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).
+// 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)
 }

package/scripts/epic/epic-audit-orphans.ts

@@ -1,6 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { cutoff_of, PAGE_CEILING_CAUSE, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_safe } from '#scripts/git/parse-json-array'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { z } from 'zod'
 import { epic_audit_logic, type AuditFinding, type FindingLevel } from './epic-audit'
 import type { EpicSnapshot } from './epic-fetch'
@@ -10,8 +11,7 @@ import { epic_parse } from './epic-parse'
 // task list does not track. It would never be run, and the epic would close without it.
 //
 // Split from the command because it shares nothing with the rest of it — the other three checks read
-// the children the epic already names, while this one searches for issues the epic does *not* name
-// (joshuafolkken/kit#1016).
+// the children the epic already names, while this one searches for issues the epic does *not* name.
 
 const SEARCH_LIMIT = 50
 const PARENT_MARKERS: ReadonlyArray<string> = ['親:', 'Parent:', '親：']
@@ -36,10 +36,10 @@ function has_parent_marker(line: string): boolean {
 // every such issue as an orphan.
 //
 // The number is read through the same reference parse the checks use, so a parent line (a PARENT_MARKERS
-// prefix) such as `owner/other#858` names that repository's epic and not this one's (joshuafolkken/kit#1014).
+// prefix) such as `owner/other#858` names that repository's epic and not this one's.
 // The known set is this repository alone — a parent line names this epic or it names nothing here —
 // and it is passed rather than omitted so a repository whose own name contains a dot still recognizes
-// `joshuafolkken/site.com#858` (joshuafolkken/kit#1016).
+// `joshuafolkken/site.com#858`.
 function names_this_epic(line: string, epic_number: number, repo: string): boolean {
 	return epic_audit_logic
 		.parse_issue_references(line, repo, epic_audit_logic.known_repos([], repo))
@@ -54,12 +54,12 @@ function claims_parent(body: string | null, epic_number: number, repo: string):
 
 // Why the scan stopped before the end of the open backlog, or that it did not. Both cutoffs hide the
 // same thing — an older issue naming this epic — and they are told apart only so the report can say
-// which one to raise (joshuafolkken/kit#1033).
+// which one to raise.
 //
-// The vocabulary is `listing-cutoff.ts`'s since joshuafolkken/kit#1067, because every caller of the
-// listing now asks this question and a second definition of "I saw everything" is the clone
-// `CLAUDE.md` prohibits. `page_ceiling` is the paging's; `row_limit` here means `SEARCH_LIMIT` body
-// mentions of `#<epic>` came back and the scan stopped there.
+// The vocabulary is `listing-cutoff.ts`'s, because every caller of the listing asks this question
+// and a second definition of "I saw everything" is the clone `CLAUDE.md` prohibits. `page_ceiling`
+// is the paging's; `row_limit` here means `SEARCH_LIMIT` body mentions of `#<epic>` came back and
+// the scan stopped there.
 
 // What the search found, and what it could not cover. The `read` / `unreadable` vocabulary is
 // `git-gh-issue-read.ts`'s, and the union rather than a flag beside the numbers is deliberate: a
@@ -70,14 +70,13 @@ type ClaimingSearch =
 // Open issues naming this epic as their parent. Searched rather than derived, because an orphan is
 // by definition absent from the one list that would otherwise name it.
 //
-// A failed search used to yield `[]` on the reasoning that an unavailable search is no evidence of
-// an orphan. That is true of the *finding* and false of the *report*: `[]` is what "no issue claims
-// this epic" looks like, so a rate limit arrived as a clean audit — the same "could not read" read
-// as "there is nothing" that joshuafolkken/kit#925, #950, #973 and #1048 closed elsewhere. The
-// answer is now carried out and reported instead (joshuafolkken/kit#1033).
+// A failed search is not answered with `[]`, even though an unavailable search is no evidence of an
+// orphan. That is true of the *finding* and false of the *report*: `[]` is what "no issue claims
+// this epic" looks like, so a rate limit would arrive as a clean audit — a "could not read" read as
+// "there is nothing". The answer is carried out and reported instead.
 async function find_claiming_issues(epic_number: number, repo: string): Promise<ClaimingSearch> {
 	const { json, is_capped } = await git_gh_command.issue_search_body(
-		`#${String(epic_number)}`,
+		issue_cite.plain(epic_number),
 		SEARCH_LIMIT,
 	)
 	if (json === undefined) return { kind: 'unreadable' }
@@ -103,7 +102,7 @@ function search_finding(level: FindingLevel, message: string): Array<AuditFindin
 //
 // Either cutoff is a **warning**: the scan *did* run, over the newest issues, and an orphan is
 // normally an issue filed minutes ago. That is something to read rather than a check that did not
-// happen — the level `epic:bundle` reports its own `⚠ … cap` at (joshuafolkken/kit#950).
+// happen — the level `epic:bundle` reports its own `⚠ … cap` at.
 function search_findings(search: ClaimingSearch): Array<AuditFinding> {
 	if (search.kind === 'unreadable') return search_finding('error', UNREADABLE_SEARCH)
 	if (search.cutoff === 'page_ceiling') return search_finding('warning', CAPPED_BY_ISSUES)
@@ -122,7 +121,7 @@ function claimed_numbers(search: ClaimingSearch): Array<number> {
 // The task-list numbers that name issues in *this* repository. `snapshot.child_numbers` appends the
 // cross-repository children's numbers, and an orphan is recognized by number alone — so a local
 // issue whose number collided with a child in another repository was accepted as tracked and never
-// reported (joshuafolkken/kit#1014). Read with the same parser `epic_fetch` reads the local rows
+// reported. Read with the same parser `epic_fetch` reads the local rows
 // with, which never matches a `- [ ] owner/repo#N` row.
 function locally_tracked(snapshot: EpicSnapshot): Array<number> {
 	return epic_parse.parse_task_list_issue_numbers(snapshot.body)

package/scripts/epic/epic-audit-rationale.ts

@@ -3,16 +3,13 @@ import type { AuditChild } from './epic-audit-checks'
 import { epic_graph, type IssueReference } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
 
-// Check 6 — a declared order between two open children that nobody wrote a reason for
-// (joshuafolkken/kit#1712).
+// Check 6 — a declared order between two open children that nobody wrote a reason for.
 //
 // **Every other check looks the other way.** They report a dependency the epic *omitted* — prose or
 // acceptance criteria naming a sibling with nothing ordering the two. Not one of them reads the
-// declaration itself, so a chain somebody typed by hand passed the audit exactly as a justified one
-// did: on 2026-09-10 the chain `#1690 -> #1694 -> #1703 -> #1679 -> #1675 -> #1676` serialized five
-// otherwise independent children through `epicrun`, and the audit reported **0 errors** both while
-// it stood and after it was deleted. It was found because a person asked why the backlog had gone
-// single-file, which is not a mechanism.
+// declaration itself, so without this check a chain somebody typed by hand passes the audit exactly
+// as a justified one does — serializing otherwise independent children through `backlogrun #E`
+// with **0 errors** reported.
 //
 // **Where a reason lives is already settled**, so this check does not invent a place to look:
 // `josh epic --add --decision-file` writes the record to the epic's `## Decisions` **and** as a
@@ -51,7 +48,7 @@ function find_child(
 // finding would be wrong about rather than merely noisy:
 //
 // **Both ends open.** A settled order can no longer stall anything, which is the same reason
-// `order_level` demotes a settled contradiction — and joshuafolkken/kit#1712 asks for it by name.
+// `order_level` demotes a settled contradiction.
 // **Both ends in the repository the audit runs in.** The comment listing reads that repository and
 // takes no `--repo` (`git-gh-issue-read.ts`), so a cross-repository end's record cannot be read at
 // all and every such order would be reported as unjustified whatever its author wrote.
@@ -136,20 +133,18 @@ function is_justified(input: RationaleInput, pair: OrderPair): boolean {
 	)
 }
 
-// **An error rather than a warning**, and the choice is the one joshuafolkken/kit#1712 asks to be
-// recorded.
+// **An error rather than a warning.**
 //
-// A warning would not be read: one real epic carries 447 of them, and the whole reason this check
+// A warning would not be read: a real epic can carry hundreds of them, and the whole reason this check
 // exists is that a false order was invisible. The counter-argument is `order_level`'s doctrine —
 // where the machine cannot tell whether something is wrong, it warns — and it does not reach this
 // check, because what is asserted here is not "this order is wrong". It is "this order's reason is
 // not recorded", which is a fact about the repository's own rule that a placement decision is
 // written down, not a judgement about the order.
 //
-// What makes the level affordable is that both remedies are now one command: `josh epic --remove`
-// deletes the order, and `--decision-file` on either command records the reason. Before
-// joshuafolkken/kit#1712 the first of those did not exist, and an error would have sent the reader
-// to the hand edit `CLAUDE.md` forbids.
+// What makes the level affordable is that both remedies are one command: `josh epic --remove`
+// deletes the order, and `--decision-file` on either command records the reason, so an error never
+// sends the reader to the hand edit `CLAUDE.md` forbids.
 function unjustified_message(pair: OrderPair, current_repo: string): string {
 	const blocker = epic_graph.format_reference(pair.blocker, current_repo)
 	const blocked = epic_graph.format_reference(pair.blocked, current_repo)

package/scripts/epic/epic-audit-report.ts

@@ -5,8 +5,7 @@ import { epic_graph, type GraphAnomaly, type IssueReference } from './epic-graph
 //
 // Only errors decide the exit code. A warning is something a reader has to look at, not something a
 // gate may fail on: check 1 fires on a legitimate forward reference as readily as on a real missing
-// dependency, and a gate that failed on both would make design notes unwritable
-// (joshuafolkken/kit#870).
+// dependency, and a gate that failed on both would make design notes unwritable.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
@@ -34,9 +33,7 @@ function anomaly_findings(anomalies: ReadonlyArray<GraphAnomaly>): Array<AuditFi
 // command that acts on it.
 //
 // Each one is written with the repository it lives in. `- [ ] sveltejs/kit#7`, refused by the owner
-// restriction, was reported as `Could not read #7` and sent the reader to this repository's issue 7
-// — the one message joshuafolkken/kit#1014 left resolving against the wrong repository
-// (joshuafolkken/kit#1016).
+// restriction, reported as `Could not read #7` would send the reader to this repository's issue 7.
 function unreadable_findings(
 	missing: ReadonlyArray<IssueReference>,
 	current_repo: string,

package/scripts/epic/epic-audit.ts

@@ -1,11 +1,11 @@
 import { markdown_section } from '#scripts/issue/markdown-section'
+import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
 
 // Reading an epic's children against each other.
 //
-// `epic:check` verifies one epic's *format*; nothing verified that the children agree. A hand audit
-// of joshuafolkken/kit#858 found two contradictions that would have stalled the implementation, and
-// `epic:check` reported all four of its requirements as passing throughout (joshuafolkken/kit#870).
+// `epic:check` verifies one epic's *format*, not that the children agree: an epic can pass every
+// format requirement while carrying contradictions that would stall the implementation.
 //
 // The graph's own properties — a cycle, and a body that declares one order while the relations
 // record another — are already detected by `epic:next` for its own purposes. This module is a
@@ -21,11 +21,11 @@ const REFERENCE_PATTERN = /#(\d+)\b/gu
 // What may appear in the `owner/repo` written in front of a `#`: exactly the set the previous
 // lookbehind refused a bare reference after, plus the `.` a repository name may legitimately contain.
 //
-// The dot is where this parse and the task-list parse used to disagree. `epic_parse`'s
+// The dot is where this parse and the task-list parse could disagree. `epic_parse`'s
 // `EXTERNAL_REFERENCE_SOURCE` allows one, so `- [ ] owner/site.com#40` is tracked as a genuine
-// cross-repository child; this one excluded it, so a sibling quoting `owner/site.com#40` was read
-// back as `com` — no repository — and every check skipped it in silence. A child that can be tracked
-// but never cited is the gap joshuafolkken/kit#1016 closes.
+// cross-repository child; excluded here, a sibling quoting `owner/site.com#40` would read back as
+// `com` — no repository — and every check would skip it in silence: a child that can be tracked but
+// never cited.
 //
 // Nothing in the syntax separates `owner/site.com` from a path written in prose: `prompts/review.md`
 // has the same shape, and reading it as a repository is the misread the exclusion was there to
@@ -81,8 +81,7 @@ function is_repo_shape(parts: ReadonlyArray<string>): boolean {
 // repositories this epic actually spans. `owner/site.com#40` is read when the epic tracks a child
 // there, and `prompts/review.md#5` is not read at all, because no epic tracks a repository by that
 // name. That makes the set of children that can be *tracked* and the set that can be *cited* the same
-// set, which is what joshuafolkken/kit#1016 asked for, without admitting the path misread that
-// widening the pattern outright would have brought back.
+// set, without admitting the path misread that widening the pattern outright would bring back.
 function reference_repo(
 	prefix: string,
 	repo: string,
@@ -127,8 +126,7 @@ function unique_references(references: ReadonlyArray<IssueReference>): Array<Iss
 // `owner/name` whose body this is: an unqualified `#N` there names that repository's issue N.
 //
 // `known` names the repositories the epic in hand spans, and only a dotted name consults it —
-// see `reference_repo`. A caller with no epic in view passes nothing and gets the dotless reading,
-// which is what every caller got before joshuafolkken/kit#1016.
+// see `reference_repo`. A caller with no epic in view passes nothing and gets the dotless reading.
 function parse_issue_references(
 	text: string,
 	repo: string,
@@ -148,7 +146,7 @@ function parse_issue_references(
 // The repositories an epic actually spans, which is what settles a dotted name written in prose:
 // `owner/site.com#40` is a reference when a child lives there and a path otherwise. Built from the
 // children rather than supplied, so a caller cannot hand the parse a set that disagrees with the
-// epic being read (joshuafolkken/kit#1016).
+// epic being read.
 function known_repos(
 	children: ReadonlyArray<IssueReference>,
 	current_repo: string,
@@ -159,8 +157,14 @@ function known_repos(
 // The issue numbers a piece of prose refers to *in its own repository*. Kept as the narrower reading
 // of the same parse rather than a second one: `epic:bundle` compares two issues' references by
 // number and has no cross-repository notion to compare with.
+//
+// **Only the body's own prose is read**: a number inside a fenced block or on
+// a quote line is pasted material — command output in a reproduction, a quoted comment — not the
+// author naming that issue. Counting it bundled a draft into an unrelated epic because a `lane:list`
+// output in its fence happened to list one of that epic's children. The exclusion is the stop guard's
+// citation reading (`issue_citation.prose_lines`), shared rather than restated.
 function parse_references(text: string, repo = ''): Array<number> {
-	return parse_issue_references(text, repo)
+	return parse_issue_references(issue_citation.prose_lines(text).join('\n'), repo)
 		.filter((reference) => reference.repo === repo)
 		.map((reference) => reference.number)
 }
@@ -201,7 +205,7 @@ function collect_blockers(
 }
 
 // Both ends are named by identity — repository plus number — because an epic can track two children
-// whose numbers collide across repositories (joshuafolkken/kit#864).
+// whose numbers collide across repositories.
 function depends_on(
 	index: ReadonlyMap<string, EpicChild>,
 	node: EpicChild,

package/scripts/epic/epic-body.ts

@@ -1,3 +1,4 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { UNORDERED_DEPENDENCIES } from './epic-parse'
 import { DEPENDENCY_ARROW, to_issue_reference } from './epic-reference'
 
@@ -10,7 +11,7 @@ const RATIONALE_PLACEHOLDER = '<why the work was split this way>'
 // Where a creation records its reasoning, including the reasoning for the order `--ordered` declares.
 // Exported because `epic:audit`'s unjustified-order check reads it as one of the places a declared
 // order's reason may live, and a second spelling of the heading is one that comes to disagree with
-// the writer (joshuafolkken/kit#1712).
+// the writer.
 const SPLIT_RATIONALE_HEADING = '## Split rationale'
 // One child declares no order, so there is nothing for the record below to name.
 const CHAIN_MINIMUM_LENGTH = 2
@@ -38,7 +39,7 @@ function format_dependencies(children: ReadonlyArray<number>, is_ordered: boolea
 }
 
 // The command that runs the batch. `backlogrun #E --only` takes the epic itself rather than a list of
-// children (joshuafolkken/kit#861, joshuafolkken/kit#1985): it re-reads the state from GitHub each
+// children: it re-reads the state from GitHub each
 // round, so an interrupted run resumes without anyone retyping the remaining numbers, and a child that
 // needs a decision is parked rather than ending the run. `--only` runs exactly the epic's children and
 // stops, which is the scope the removed `epicrun #E` keyword had.
@@ -46,13 +47,13 @@ function format_dependencies(children: ReadonlyArray<number>, is_ordered: boolea
 // The epic number is not known while its own body is being built, so the placeholder is filled in by
 // `format_run_command` once the issue exists. Bodies written before this change still say
 // `epicrun …` or `queue …`; nothing reads the `Execution` section — the auto-close reads the task
-// list and `epic:check` never looks at it — so those epics are unaffected (joshuafolkken/kit#865).
+// list and `epic:check` never looks at it — so those epics are unaffected.
 const EPIC_PLACEHOLDER = '<this epic>'
 
 function format_run_command(epic_number: number | undefined): string {
 	const epic = epic_number === undefined ? EPIC_PLACEHOLDER : String(epic_number)
 
-	return `backlogrun #${epic} --only`
+	return `backlogrun ${issue_cite.plain(epic)} --only`
 }
 
 // A backlink to the Issue this split came from, when the split originated in another repository.
@@ -70,14 +71,13 @@ function to_rationale(rationale: string): string {
 	return trimmed.length > 0 ? trimmed : RATIONALE_PLACEHOLDER
 }
 
-// The record that `--ordered` itself is the decision behind the chain it writes
-// (joshuafolkken/kit#1712).
+// The record that `--ordered` itself is the decision behind the chain it writes.
 //
 // **Without it every `--ordered` epic is born failing its own audit.** `epic:audit`'s
-// unjustified-order check asks where a declared order's reason was recorded, and a creation used to
-// record none — the split rationale explains the split in prose that need not name a single issue
-// number, so the check found nothing for any of the links and `epicrun` stopped at step one on a
-// brand-new epic created exactly as documented.
+// unjustified-order check asks where a declared order's reason was recorded, and the split rationale
+// explains the split in prose that need not name a single issue number — so without this record the
+// check finds nothing for any of the links and `backlogrun #E` stops at its audit on a brand-new
+// epic created exactly as documented.
 //
 // **It is a real record, not a formality.** `--ordered` is a person stating the order deliberately,
 // and this says so, when, and where the reasoning is — which is exactly what the check exists to