@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/document/document-section.ts

@@ -13,6 +13,7 @@
 // moved to "read it later" is a rule that measurably never fires, and this moves nothing to later.
 
 import { file_reader } from '#scripts/lib/read-file'
+import { document_scan } from './document-scan'
 
 // `#` to `######`, one space, then the title. Written with a literal space rather than `\s+` and a
 // lazy title so it cannot backtrack: `sonarjs/super-linear-regex` rejects the `\s+…+?\s*$` shape,
@@ -21,6 +22,17 @@ const HEADING_PATTERN = /^(?<hashes>#{1,6}) (?<title>.*)$/u
 const FENCE = '```'
 const SINGLE_MATCH = 1
 
+// Any bold span is a citable anchor: the documents point at `- **Cross-package problems → …**` at a
+// line start and at a `**…**` emphasis mid-paragraph alike.
+const BOLD_LABEL_PATTERN = /\*\*([^*]+?)\*\*/gu
+const BOLD_DELIMITER = '**'
+// A one-line inline code span: a double-backtick span (which may quote a backtick) or a single one.
+const CODE_SPAN_PATTERN = /``[^\n]*?``|`[^`\n]*`/gu
+// A label ranks below every heading, so a heading section never ends at one.
+const LABEL_LEVEL = 7
+// A list item opens with `-`, `*` or a number, after any indentation.
+const LIST_ITEM_PATTERN = /^(?<indent>\s*)(?:[-*]|\d+\.) /u
+
 interface Heading {
 	level: number
 	title: string
@@ -58,13 +70,27 @@ function push_heading(found: Array<Heading>, line: string, index: number): void
 // **Fenced blocks are skipped, and that is not defensive tidying.** These documents quote shell, and
 // a shell comment at the start of a line is a `#` in column one. Counted as a heading it would end
 // the section above it early, which is a silent wrong answer rather than a visible failure.
+// One flag per line — `true` for a fence delimiter and every line between a pair of them — so the
+// heading scan and the label scan cannot disagree on what is quoted code.
+function fenced_flags(lines: ReadonlyArray<string>): Array<boolean> {
+	let is_inside_fence = false
+
+	return lines.map(function is_fenced(line: string): boolean {
+		if (!line.startsWith(FENCE)) return is_inside_fence
+
+		is_inside_fence = !is_inside_fence
+
+		return true
+	})
+}
+
 function headings(markdown: string): Array<Heading> {
+	const lines = markdown.split('\n')
+	const fenced = fenced_flags(lines)
 	const found: Array<Heading> = []
-	let is_inside_fence = false
 
-	for (const [index, line] of markdown.split('\n').entries()) {
-		if (line.startsWith(FENCE)) is_inside_fence = !is_inside_fence
-		else if (!is_inside_fence) push_heading(found, line, index)
+	for (const [index, line] of lines.entries()) {
+		if (fenced[index] !== true) push_heading(found, line, index)
 	}
 
 	return found
@@ -74,24 +100,77 @@ function titles(markdown: string): Array<string> {
 	return headings(markdown).map((heading) => heading.title)
 }
 
+// The zero-based line each character offset sits on, read as the number of line starts at or before it.
+function line_starts(markdown: string): Array<number> {
+	return [...markdown.matchAll(/\n/gu)].map((match) => match.index + SINGLE_MATCH)
+}
+
+function line_of(starts: ReadonlyArray<number>, offset: number): number {
+	return starts.filter((start) => start <= offset).length
+}
+
+// **A bold label is an anchor too** (joshuafolkken/kit#3248). The documents cite
+// `- **Output language follows …**` exactly as they cite a heading, and the reference tests accepted
+// both while this reader found only headings — so a green suite promised a section the command then
+// refused. A label may wrap across lines, so the scan runs over the whole text, not line by line.
+//
+// Fenced lines are blanked before the scan rather than filtered after it: a `docs/**` glob in a
+// fence would otherwise take a delimiter and pair every later `**` with the wrong partner. Blanking
+// keeps the line count, so a label's line number still indexes the original document.
+function unfenced_text(markdown: string): string {
+	const lines = markdown.split('\n')
+	const fenced = fenced_flags(lines)
+
+	return lines.map((line, index) => (fenced[index] === true ? '' : line)).join('\n')
+}
+
+// An inline code span gets the same treatment one level down: `prompts/**` mid-paragraph would take a
+// delimiter just as a fenced glob does. Its `*` become spaces, so every offset still indexes the
+// unmasked text — which is where the title is read from, keeping a label that quotes code intact.
+function code_masked(text: string): string {
+	return text.replaceAll(CODE_SPAN_PATTERN, (span) => span.replaceAll('*', ' '))
+}
+
+function labels(markdown: string): Array<Heading> {
+	const text = unfenced_text(markdown)
+	const starts = line_starts(text)
+
+	return [...code_masked(text).matchAll(BOLD_LABEL_PATTERN)].map((match) => ({
+		level: LABEL_LEVEL,
+		title: text.slice(
+			match.index + BOLD_DELIMITER.length,
+			match.index + match[0].length - BOLD_DELIMITER.length,
+		),
+		line: line_of(starts, match.index),
+	}))
+}
+
 // **Prefix, because a reference cites the name and the heading carries the name plus its gloss.**
 // `` → "The hand-off" `` points at `## The hand-off — one session does not have to run the whole
 // epic`, and `` → "The check is asked at every merge" `` at a heading that continues with a comma.
 // Requiring the whole heading would make every such reference unresolvable, and citing the whole
-// heading in the prose would put the gloss into every pointer.
+// heading in the prose would put the gloss into every pointer. Both sides are compared in the forms
+// `document_scan.reference_forms` gives, so a reference that wraps or drops a heading's number lands.
 function is_match(heading: Heading, wanted: string): boolean {
-	return heading.title.startsWith(wanted)
+	return document_scan.reference_forms(heading.title).some((form) => form.startsWith(wanted))
 }
 
 function prefixed(found: ReadonlyArray<Heading>, wanted: string): Array<Heading> {
-	return found.filter((heading) => is_match(heading, wanted))
+	const normalized = document_scan.normalize_reference(wanted)
+
+	return found.filter((heading) => is_match(heading, normalized))
+}
+
+function is_exact(heading: Heading, wanted: string): boolean {
+	return document_scan.reference_forms(heading.title).includes(wanted)
 }
 
 // **Exact wins, and an ambiguous prefix is refused rather than ranked.** Two headings that both
 // start with the cited text is a document whose reference is genuinely ambiguous; picking the first
 // would hand back a section nobody named, which is a failure a whole-file read does not have.
 function select(found: ReadonlyArray<Heading>, wanted: string): Heading | undefined {
-	const exact = found.find((heading) => heading.title === wanted)
+	const normalized = document_scan.normalize_reference(wanted)
+	const exact = found.find((heading) => is_exact(heading, normalized))
 
 	if (exact !== undefined) return exact
 
@@ -103,34 +182,82 @@ function select(found: ReadonlyArray<Heading>, wanted: string): Heading | undefi
 // A section ends where the next heading of the same or higher rank begins, so a `##` section carries
 // its `###` subsections with it — which is what a pointer at a `##` heading means.
 function last_line_of(found: ReadonlyArray<Heading>, chosen: Heading, total_lines: number): number {
-	const index = found.indexOf(chosen)
-	const next = found.slice(index + SINGLE_MATCH).find((heading) => heading.level <= chosen.level)
+	const next = found.find((heading) => heading.line > chosen.line && heading.level <= chosen.level)
 
 	return (next === undefined ? total_lines : next.line) - SINGLE_MATCH
 }
 
-function section(markdown: string, wanted: string): Section | undefined {
-	const lines = markdown.split('\n')
+function indent_of(line: string): number {
+	return line.length - line.trimStart().length
+}
+
+// Where the block a label sits in stops: a blank line, a heading, or a list item at the label line's
+// own depth or shallower — so a label's nested sub-items come with it and its next sibling does not.
+function is_sibling_item(line: string, depth: number): boolean {
+	const { indent } = LIST_ITEM_PATTERN.exec(line)?.groups ?? {}
+
+	return indent !== undefined && indent.length <= depth
+}
+
+function ends_block(line: string, depth: number): boolean {
+	if (line.trim() === '' || HEADING_PATTERN.test(line)) return true
+
+	return is_sibling_item(line, depth)
+}
+
+// A label's section is the paragraph or list item it opens, not the rest of the document.
+function label_last_line(lines: ReadonlyArray<string>, label: Heading): number {
+	const depth = indent_of(lines[label.line] ?? '')
+	const end = lines.findIndex((line, index) => index > label.line && ends_block(line, depth))
+
+	return (end === -1 ? lines.length : end) - SINGLE_MATCH
+}
+
+// **A heading answers before any label does.** A label is consulted only when no heading even
+// starts with the cited text, so an ambiguous heading reference is refused rather than rescued by a
+// bold span that happens to share its prefix.
+function choose(markdown: string, wanted: string): Heading | undefined {
 	const found = headings(markdown)
-	const chosen = select(found, wanted)
+
+	if (prefixed(found, wanted).length > 0) return select(found, wanted)
+
+	return select(labels(markdown), wanted)
+}
+
+function extent_of(markdown: string, chosen: Heading): number {
+	const lines = markdown.split('\n')
+
+	if (chosen.level === LABEL_LEVEL) return label_last_line(lines, chosen)
+
+	return last_line_of(headings(markdown), chosen, lines.length)
+}
+
+function section(markdown: string, wanted: string): Section | undefined {
+	const chosen = choose(markdown, wanted)
 
 	if (chosen === undefined) return undefined
 
-	const last_line = last_line_of(found, chosen, lines.length)
+	const last_line = extent_of(markdown, chosen)
+	const lines = markdown.split('\n').slice(chosen.line, last_line + SINGLE_MATCH)
 
 	return {
 		title: chosen.title,
 		level: chosen.level,
 		first_line: chosen.line,
 		last_line,
-		text: lines.slice(chosen.line, last_line + SINGLE_MATCH).join('\n'),
+		text: lines.join('\n'),
 	}
 }
 
 // Ambiguity and absence are different answers, and the caller reports them differently: one names
 // the candidates, the other lists every heading the file has.
+// Candidates follow `choose`'s order — headings, and labels only when no heading matches — so a
+// refusal never suggests a label that citing it could not select.
 function candidates(markdown: string, wanted: string): Array<string> {
-	return prefixed(headings(markdown), wanted).map((heading) => heading.title)
+	const near = prefixed(headings(markdown), wanted)
+	const listed = near.length > 0 ? near : prefixed(labels(markdown), wanted)
+
+	return listed.map((heading) => heading.title)
 }
 
 function read_optional(file_path: string): string | undefined {

package/scripts/document/entry-read-budget.ts

@@ -70,7 +70,7 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// list, so its ~48KB read crossed a block downward and the recorded ceiling drops to the block multiple
 	// the stale-ratchet message named. The other entries still read it, so their rows hold.
 	// joshuafolkken/kit#2345 added the `implementation-unit` delegation row (full fan-out procedure in
-	// `docs/josh-commands-automation.md` → "`josh fanout`"); `delegation.md` gained only a one-clause mention and a
+	// `docs/josh-commands-backlog.md` → "`josh fanout`"); `delegation.md` gained only a one-clause mention and a
 	// pointer, folded into the existing enumeration and offset by tightening `delegation.md` prose, so every entry
 	// stayed within its block (kickoff has no block of headroom — its pre-#2294 ceiling is the next
 	// multiple, which the downward ratchet holds shut).
@@ -101,12 +101,14 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// provider prose moved to `docs/josh-commands-automation.md`, and the failure-only sections moved to
 	// `backlogrun-recovery.md`, which the parent's reach still charges whole.
 	// joshuafolkken/kit#3171 cut `CLAUDE.md` to triggers and pointers (~12 KB), lowering every entry.
-	{ entry: 'kickoff', bytes: 45_056 },
+	// joshuafolkken/kit#3256 moved `CLAUDE.md`'s residency prose to `residency.md`, lowering kickoff and
+	// halfrun one block each.
+	{ entry: 'kickoff', bytes: 40_960 },
 	// Raised in joshuafolkken/kit#3177: #3173, #3181 and #3183 merged in parallel and together tipped
 	// fullrun 12 bytes over its block; none of #3177's documents are in its read set.
 	// Lowered back in joshuafolkken/kit#3180: the history and lint-settled proofs left its read set.
 	{ entry: 'fullrun', bytes: 57_344 },
-	{ entry: 'halfrun', bytes: 57_344 },
+	{ entry: 'halfrun', bytes: 53_248 },
 	{ entry: 'prrun', bytes: 61_440 },
 	{ entry: 'backlogrun', bytes: 176_128 },
 	{ entry: LANE_CHILD, bytes: 57_344 },

package/scripts/document/entry-read-set.ts

@@ -14,20 +14,20 @@
 
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
 import { PACKAGE_DIR } from '#scripts/init/init-paths'
 import { bash_output_cap_reader } from './bash-output-cap'
-import { document_section, type Section } from './document-section'
+import { document_section } from './document-section'
+import { read_set_cost, type Cost } from './read-set-cost'
 import { read_set_point_of_use } from './read-set-point-of-use'
 
 const { POINT_OF_USE_FILES, POINT_OF_USE_BY_ENTRY, is_point_of_use, point_of_use_files } =
 	read_set_point_of_use
+const { cost_of, scoped_file_cost, total } = read_set_cost
 
 const SKILL_DIRECTORY = path.join('.claude', 'skills', 'workflow-commands')
 const SKILL_FILE = 'SKILL.md'
 const TABLE_SECTION = '1. Which file to read'
 const NOTHING = 0
-const ONE_LINE = 1
 
 // The point-of-use classification — which documents an entry names but reads only at a later step —
 // is its own concern, split into `read-set-point-of-use.ts` in joshuafolkken/kit#2289. This file
@@ -54,11 +54,6 @@ interface SectionReference {
 	heading: string
 }
 
-interface Cost {
-	bytes: number
-	tokens: number
-}
-
 interface SectionCost extends SectionReference {
 	cost: Cost
 	is_resolved: boolean
@@ -297,21 +292,6 @@ function read_set(root: string, entry: string): ReadSet {
 	return { entry, files, sections: sections_for(root, entry, files) }
 }
 
-function cost_of(text: string): Cost {
-	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
-}
-
-function total(costs: ReadonlyArray<Cost>): Cost {
-	const running = { bytes: NOTHING, tokens: NOTHING }
-
-	for (const cost of costs) {
-		running.bytes += cost.bytes
-		running.tokens += cost.tokens
-	}
-
-	return running
-}
-
 function section_cost(root: string, reference: SectionReference): SectionCost {
 	const found = document_section.section(read_document(root, reference.file), reference.heading)
 
@@ -334,74 +314,13 @@ function headings_for(sections: ReadonlyArray<SectionReference>, file: string):
 	return sections.filter((reference) => reference.file === file).map((one) => one.heading)
 }
 
-function add_range(charged: Set<number>, found: Section): void {
-	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
-}
-
-// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
-// file and there is then nothing to union.
-function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
-	const charged = new Set<number>()
-
-	for (const heading of headings) {
-		const found = document_section.section(markdown, heading)
-
-		if (found === undefined) return undefined
-
-		add_range(charged, found)
-	}
-
-	return charged
-}
-
-// **The union's charged lines are split into contiguous runs, and each run is costed on its own
-// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
-// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
-// with no real overlap — a false negative saving the measurement must never print
-// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
-// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
-// real read and keeps `scoped` at or below the per-reference sum by construction.
-function extend_or_start(runs: Array<Array<number>>, index: number): void {
-	const current = runs.at(-1)
-
-	if (current?.at(-1) === index - ONE_LINE) current.push(index)
-	else runs.push([index])
-}
-
-function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
-	const runs: Array<Array<number>> = []
-	const ascending = [...charged].toSorted((left, right) => left - right)
-
-	for (const index of ascending) extend_or_start(runs, index)
-
-	return runs
-}
-
-function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
-	return run.map((index) => lines[index] ?? '').join('\n')
-}
-
-// **Charged per file over the union of the lines its references cover, never per reference.**
-// Summing the references instead double-counts the two ways one file can be cited twice — two
-// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
-// `###` children, which `section()` already returns inside the parent. Either one could push the
-// scoped figure above the whole one and print a *negative* saving, which is the single direction this
-// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
-function file_scoped_cost(root: string, file: string, headings: ReadonlyArray<string>): Cost {
-	const markdown = read_document(root, file)
-	const charged = charged_lines(markdown, headings)
-
-	if (charged === undefined) return cost_of(markdown)
-
-	const lines = markdown.split('\n')
-
-	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
-}
-
+// The per-file union that keeps `scoped` at or below `whole` lives in `read-set-cost.ts`.
 function scoped_cost(root: string, sections: ReadonlyArray<SectionReference>): Cost {
 	const files = unique(sections.map((reference) => reference.file))
 
-	return total(files.map((file) => file_scoped_cost(root, file, headings_for(sections, file))))
+	return total(
+		files.map((file) => scoped_file_cost(read_document(root, file), headings_for(sections, file))),
+	)
 }
 
 function file_costs(root: string, names: ReadonlyArray<string>): Array<FileCost> {
@@ -491,5 +410,7 @@ const entry_read_set = {
 	total,
 }
 
-export type { Cost, FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
+export type { FileCost, ReadSet, ReadSetCost, SectionCost, SectionReference }
 export { entry_read_set }
+
+export { type Cost } from './read-set-cost'

package/scripts/document/read-set-cost.ts

@@ -0,0 +1,98 @@
+import { cost_tokens } from '#scripts/cost-runtime/cost-tokens'
+import { document_section, type Section } from './document-section'
+
+// What a read costs, and the scoped union that charges one file's cited sections once — split out
+// of `entry-read-set.ts` when it reached its line limit (joshuafolkken/kit#3264). `entry_read_set`
+// re-exports `cost_of`, `total` and `Cost` under the names they always had, so the move changed no
+// call site.
+
+const NOTHING = 0
+const ONE_LINE = 1
+
+interface Cost {
+	bytes: number
+	tokens: number
+}
+
+function cost_of(text: string): Cost {
+	return { bytes: Buffer.byteLength(text, 'utf8'), tokens: cost_tokens.estimate(text) }
+}
+
+function total(costs: ReadonlyArray<Cost>): Cost {
+	const running = { bytes: NOTHING, tokens: NOTHING }
+
+	for (const cost of costs) {
+		running.bytes += cost.bytes
+		running.tokens += cost.tokens
+	}
+
+	return running
+}
+
+function add_range(charged: Set<number>, found: Section): void {
+	for (let index = found.first_line; index <= found.last_line; index += ONE_LINE) charged.add(index)
+}
+
+// `undefined` the moment one heading does not resolve, because that reference is charged at its whole
+// file and there is then nothing to union.
+function charged_lines(markdown: string, headings: ReadonlyArray<string>): Set<number> | undefined {
+	const charged = new Set<number>()
+
+	for (const heading of headings) {
+		const found = document_section.section(markdown, heading)
+
+		if (found === undefined) return undefined
+
+		add_range(charged, found)
+	}
+
+	return charged
+}
+
+// **The union's charged lines are split into contiguous runs, and each run is costed on its own
+// natural text.** Joining non-adjacent lines with `\n` into one string fabricates a token boundary at
+// every gap the union skipped, so the estimate could drift a token *above* the per-reference sum even
+// with no real overlap — a false negative saving the measurement must never print
+// (joshuafolkken/kit#1934). A run is a maximal stretch of consecutive charged lines, which is exactly
+// the contiguous text a reader of that section actually reads, so summing the runs both mirrors the
+// real read and keeps `scoped` at or below the per-reference sum by construction.
+function extend_or_start(runs: Array<Array<number>>, index: number): void {
+	const current = runs.at(-1)
+
+	if (current?.at(-1) === index - ONE_LINE) current.push(index)
+	else runs.push([index])
+}
+
+function contiguous_runs(charged: ReadonlySet<number>): Array<Array<number>> {
+	const runs: Array<Array<number>> = []
+	const ascending = [...charged].toSorted((left, right) => left - right)
+
+	for (const index of ascending) extend_or_start(runs, index)
+
+	return runs
+}
+
+function run_text(lines: ReadonlyArray<string>, run: ReadonlyArray<number>): string {
+	return run.map((index) => lines[index] ?? '').join('\n')
+}
+
+// **Charged per file over the union of the lines its references cover, never per reference.**
+// Summing the references instead double-counts the two ways one file can be cited twice — two
+// unresolved headings each charged at the whole file, and a `##` section cited beside one of its own
+// `###` children, which `section()` already returns inside the parent. Either one could push the
+// scoped figure above the whole one and print a *negative* saving, which is the single direction this
+// measurement must not be able to move (joshuafolkken/kit#1776 review round 1).
+function scoped_file_cost(markdown: string, headings: ReadonlyArray<string>): Cost {
+	const charged = charged_lines(markdown, headings)
+
+	if (charged === undefined) return cost_of(markdown)
+
+	const lines = markdown.split('\n')
+
+	return total(contiguous_runs(charged).map((run) => cost_of(run_text(lines, run))))
+}
+
+const read_set_cost = { cost_of, scoped_file_cost, total }
+
+export type { Cost }
+export { read_set_cost }

package/scripts/epic/epic-add-body.ts

@@ -147,6 +147,7 @@ function splice_declaration(
 		if (index === input.first) return [...input.rendered]
 		if (input.dropped.has(index)) return []
 
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
 		return [line]
 	})
 }

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

@@ -301,7 +301,7 @@ function reported_references(
 		.flatMap((reference) => {
 			const state = reported_state(states, reference)
 
-			return state === undefined ? [] : [{ reference, state }]
+			return state === undefined ? [] : { reference, state }
 		})
 }
 

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

@@ -73,9 +73,10 @@ function order_pairs(
 		const blocked = find_child(children, { repo: epic_repo, number: link.blocked })
 		if (blocker === undefined || blocked === undefined) return []
 
-		return is_open_local(blocker, current_repo) && is_open_local(blocked, current_repo)
-			? [{ blocker, blocked }]
-			: []
+		if (!is_open_local(blocker, current_repo) || !is_open_local(blocked, current_repo)) return []
+
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- one return type (sonarjs/function-return-type)
+		return [{ blocker, blocked }]
 	})
 }
 

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

@@ -4,6 +4,7 @@ import { git_gh_command } from '#scripts/gh/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 type { PollOptions } from '#scripts/lib/poll'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { z } from 'zod'
 import {
@@ -14,6 +15,7 @@ import {
 } from './epic-bundle'
 import { epic_bundle_evidence } from './epic-bundle-evidence'
 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'
@@ -393,9 +395,18 @@ async function report_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)
+// The recommendation for one issue, from the open backlog around it. `options` is the poll a caller
+// holding a just-filed issue passes, since the listing trails the create call (`epic-bundle-poll.ts`).
+async function report_for(
+	issue_number: number,
+	repo: string,
+	options?: PollOptions,
+): Promise<number> {
+	const backlog = await epic_bundle_poll.read_until_listed(
+		async () => await read_backlog(repo),
+		issue_number,
+		options,
+	)
 
 	if (!backlog.is_readable) {
 		console.error(unreadable_backlog_message(backlog))

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

@@ -0,0 +1,41 @@
+import { poll, type PollOptions } from '#scripts/lib/poll'
+
+// **The open listing trails the create call** (joshuafolkken/kit#3332): `issue:file` asks
+// `epic:bundle` about the issue it has just filed, and the list endpoint had not shown it yet on every
+// filing of one run, so the placement was skipped each time. A caller that knows the issue is fresh
+// passes a poll and the listing is read again until it shows the issue. An unreadable listing is
+// final, since reading it again is not what would change it.
+
+// A number typed at the command line names an issue that exists already, so it is read once.
+const SINGLE_READ: PollOptions = { attempts: 1, interval_ms: 0 }
+
+interface Listing {
+	is_readable: boolean
+	issues: ReadonlyArray<{ number: number }>
+}
+
+function is_settled(listing: Listing, issue_number: number): boolean {
+	return !listing.is_readable || listing.issues.some((issue) => issue.number === issue_number)
+}
+
+async function read_until_listed<T extends Listing>(
+	read: () => Promise<T>,
+	issue_number: number,
+	options: PollOptions = SINGLE_READ,
+): Promise<T> {
+	const reads: Array<T> = []
+
+	await poll.poll_until(async () => {
+		const listing = await read()
+
+		reads.push(listing)
+
+		return is_settled(listing, issue_number)
+	}, options)
+
+	return reads.at(-1) ?? (await read())
+}
+
+const epic_bundle_poll = { read_until_listed }
+
+export { epic_bundle_poll }

package/scripts/epic/epic-busy.ts

@@ -1,6 +1,6 @@
 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 { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import {
 	ALREADY_DONE_LABEL,
 	has_any_label,

package/scripts/epic/epic-candidate-confirm.ts

@@ -70,11 +70,12 @@ function is_same_blockers(
 	left: ReadonlyArray<IssueReference>,
 	right: ReadonlyArray<IssueReference>,
 ): boolean {
-	const sorted = (blockers: ReadonlyArray<IssueReference>): string =>
-		blockers
+	function sorted(blockers: ReadonlyArray<IssueReference>): string {
+		return blockers
 			.map((blocker) => epic_graph.key_of(blocker))
 			.toSorted((first, second) => first.localeCompare(second))
 			.join(',')
+	}
 
 	return sorted(left) === sorted(right)
 }

package/scripts/epic/epic-classify.ts

@@ -217,7 +217,7 @@ function is_ready(node: string, context: ClassifyContext): boolean {
 function fill_memo(children: ReadonlyArray<EpicChild>, context: ClassifyContext): void {
 	const pending = new Set(children.map((child) => epic_graph.key_of(child)))
 
-	const peel = (): number => {
+	function peel(): number {
 		const ready = [...pending].filter((node) => is_ready(node, context))
 
 		for (const node of ready) {