@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/document/command-reference-line-budget.ts

@@ -0,0 +1,42 @@
+// The long-line ceiling of the command reference — one source for `command-reference.test.ts` and the
+// fast `josh lint:related` path (`document-ratchet-check.ts`), so the two can never hold different
+// lines. A reference entry is a short summary; the why behind it lives in the page's maintainer
+// rationale file. The pages once carried 137 lines over 400 characters (joshuafolkken/kit#3868); the
+// ceiling is a ratchet at the long lines left after condensing them, so lowering it is the only way
+// it moves.
+
+// The only files under `docs/` an agent is routed to read — the four command references; the rest of
+// `docs/` is reference a human browses, so the byte budget (`document/document-byte-budget.ts`)
+// covers these alone.
+const COMMAND_REFERENCE_DOCS: ReadonlyArray<string> = [
+	'docs/josh-commands.md',
+	'docs/josh-commands-automation.md',
+	'docs/josh-commands-run.md',
+	'docs/josh-commands-backlog.md',
+]
+const LONG_LINE_CHARACTERS = 400
+const MAX_LONG_LINES = 3
+
+// The lines over the length limit across every page handed in — the ceiling holds the pages
+// together, so one page's cut makes room in another.
+function long_line_count(texts: ReadonlyArray<string>): number {
+	return texts
+		.flatMap((text) => text.split('\n'))
+		.filter((line) => line.length > LONG_LINE_CHARACTERS).length
+}
+
+// The failure for a count over the ceiling, or undefined at or under it.
+function long_line_violation(count: number): string | undefined {
+	if (count <= MAX_LONG_LINES) return undefined
+
+	return `the command reference (${COMMAND_REFERENCE_DOCS.join(', ')}) has ${count.toString()} lines over ${LONG_LINE_CHARACTERS.toString()} characters, over its ceiling of ${MAX_LONG_LINES.toString()}. Shorten the entry — the why belongs in the page's maintainer rationale file.`
+}
+
+const command_reference_line_budget = {
+	COMMAND_REFERENCE_DOCS,
+	long_line_count,
+	long_line_violation,
+	MAX_LONG_LINES,
+}
+
+export { command_reference_line_budget }

package/scripts/document/document-byte-budget.ts

@@ -58,7 +58,7 @@ function block_ceiling(size: number): number {
 // unreached file, so the definition cannot rot as documents move on or off the execution path.
 const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/dependency-update/SKILL.md', bytes: 4096 },
-	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 12_288 },
+	{ path: '.claude/skills/epic-commands/SKILL.md', bytes: 8192 },
 	{ path: '.claude/skills/epic-commands/epic-bundle.md', bytes: 4096 },
 	{ path: '.claude/skills/epic-commands/execution-waves.md', bytes: 4096 },
 	{ path: '.claude/skills/verify-ui/SKILL.md', bytes: 4096 },
@@ -73,10 +73,18 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/prerequisite.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
+	// `command:derive`'s usage section (joshuafolkken/kit#4970) crossed the 45056 block.
 	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
-	{ path: 'docs/josh-commands-run.md', bytes: 65_536 },
-	{ path: 'docs/josh-commands-backlog.md', bytes: 53_248 },
-	{ path: 'docs/josh-commands.md', bytes: 49_152 },
+	// The carried `--unpinned-ok` record (joshuafolkken/kit#4775) crossed the 73728 block.
+	// `run:merge`'s withdrawn child (joshuafolkken/kit#4916) crossed the 77824 block.
+	// `lane:plan --probe` and the entry probe (joshuafolkken/kit#5211) crossed the 81920 block.
+	{ path: 'docs/josh-commands-run.md', bytes: 86_016 },
+	// `josh effect:audit` (joshuafolkken/kit#4958) and `issue:priority`'s usage section (joshuafolkken/kit#4960) crossed the 57344 block;
+	// `josh prose:stale` (joshuafolkken/kit#5287) crossed the 61440 block.
+	{ path: 'docs/josh-commands-backlog.md', bytes: 65_536 },
+	// `run:merge` withdrawing a lane closed without a merge (joshuafolkken/kit#4916) crossed the 53248 block;
+	// `gate --static-group` (joshuafolkken/kit#5215) crossed the 57344 block.
+	{ path: 'docs/josh-commands.md', bytes: 61_440 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 4096 },
@@ -84,8 +92,11 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/gh-rest.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/glossary.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/issue-citation.md', bytes: 4096 },
-	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 8192 },
+	// The priority declaration and its criteria (joshuafolkken/kit#4383) crossed the 8192 block; the
+	// causing-lane declaration and criteria F / G (joshuafolkken/kit#4749) crossed the 12288 one.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow/lane-instructions.md', bytes: 4096 },
+	{ path: 'prompts/collaboration-workflow/measurement.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/operating-rules.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/output-bounds.md', bytes: 4096 },
 	{ path: 'prompts/collaboration-workflow/overview.md', bytes: 4096 },
@@ -101,7 +112,8 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'prompts/collaboration-workflow/wip-cap.md', bytes: 8192 },
 	{ path: 'prompts/refactoring.md', bytes: 8192 },
 	{ path: 'prompts/review-rubric.md', bytes: 12_288 },
-	{ path: 'prompts/review.md', bytes: 12_288 },
+	// Self-check 2's `josh prose:stale` pointer (joshuafolkken/kit#5287) crossed the 12288 block.
+	{ path: 'prompts/review.md', bytes: 16_384 },
 	{ path: 'prompts/sonar-hotspot-handling.md', bytes: 8192 },
 	{ path: 'prompts/testing-guide.md', bytes: 12_288 },
 ]

package/scripts/document/document-checks.ts

@@ -0,0 +1,20 @@
+import { document_byte_check } from './document-byte-check'
+import { document_ratchet_check } from './document-ratchet-check'
+
+// The document checks `josh lint:related` brings forward from the gate's tests, as one call: the
+// byte ceilings (`document-byte-check.ts`) and the ratchets (`document-ratchet-check.ts`). Both run
+// every time, so one edit reports every ceiling it broke in one pass rather than one per run.
+
+const CHECKS = [document_byte_check, document_ratchet_check]
+
+function check_files(root: string, absolute_files: ReadonlyArray<string>): number {
+	return Math.max(...CHECKS.map((check) => check.check_files(root, absolute_files)))
+}
+
+function check_all(root: string): number {
+	return Math.max(...CHECKS.map((check) => check.check_all(root)))
+}
+
+const document_checks = { check_all, check_files }
+
+export { document_checks }

package/scripts/document/document-ratchet-check.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { project_checks } from '#scripts/gate/project-checks'
+import { command_reference_line_budget } from './command-reference-line-budget'
+import { issue_citation_budget } from './issue-citation-budget'
+
+// The two document ratchets the gate's tests hold — the command reference's long-line ceiling
+// (`command-reference.test.ts`) and each agent-read document's issue-citation count
+// (`issue-citation-budget.test.ts`) — made reachable on the fast between-edits path beside
+// `document-byte-check.ts`, so a documentation edit that breaks either surfaces in seconds rather
+// than in a minutes-long `check:related` (joshuafolkken/kit#4986). The ceilings, the counting and the
+// messages are the budget modules' alone; this adds none of its own.
+//
+// It reads no change of its own: `lint:related` hands in the files it already resolved. The citation
+// check holds the documents the budget records; a document with no entry, and the whole-list checks
+// (a stale or a zero entry), stay with the gate's test, which knows the agent-read set.
+//
+// Both ratchets are kit's: the budget records kit's paths, and a consumer's own file at one of them
+// holds its own count, so a consumer root is checked by neither.
+
+const LABEL = 'document ratchet'
+
+function read_text(absolute_path: string): string | undefined {
+	return existsSync(absolute_path) ? readFileSync(absolute_path, 'utf8') : undefined
+}
+
+// The long-line failure across the whole command reference, which the ceiling holds together.
+function long_line_message(root: string): string | undefined {
+	const texts = command_reference_line_budget.COMMAND_REFERENCE_DOCS.map((relative_path) =>
+		read_text(path.join(root, relative_path)),
+	).filter((text): text is string => text !== undefined)
+
+	return command_reference_line_budget.long_line_violation(
+		command_reference_line_budget.long_line_count(texts),
+	)
+}
+
+function touches_command_reference(root: string, absolute_files: ReadonlyArray<string>): boolean {
+	const references = new Set(command_reference_line_budget.COMMAND_REFERENCE_DOCS)
+
+	return absolute_files.some((absolute_path) => references.has(path.relative(root, absolute_path)))
+}
+
+// The citation failure for one file the budget records, or undefined when it holds its count, has no
+// entry, or is gone from the tree.
+function citation_message(root: string, absolute_path: string): string | undefined {
+	const relative_path = path.relative(root, absolute_path)
+	const recorded = issue_citation_budget.recorded_citations_for(relative_path)
+	const text = read_text(absolute_path)
+	if (recorded === 0 || text === undefined) return undefined
+
+	const current = issue_citation_budget.count_citations(text)
+
+	return issue_citation_budget.citation_violation(relative_path, current, recorded)
+}
+
+function citation_messages(
+	root: string,
+	absolute_files: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return absolute_files
+		.map((absolute_path) => citation_message(root, absolute_path))
+		.filter((message): message is string => message !== undefined)
+}
+
+// Prints one labelled line per failure and answers non-zero, or stays silent and answers zero.
+function report(messages: ReadonlyArray<string | undefined>): number {
+	const lines = messages
+		.filter((message): message is string => message !== undefined)
+		.map((message) => `${LABEL}: ${message}`)
+	if (lines.length === 0) return 0
+
+	process.stdout.write(`${lines.join('\n')}\n`)
+
+	return 1
+}
+
+// The check over a resolved change: the long-line ceiling when it touches a command reference page,
+// and the citation count of every changed file the budget records. An unrelated change reads nothing.
+function check_files(root: string, absolute_files: ReadonlyArray<string>): number {
+	if (!project_checks.is_kit_repository(root)) return 0
+	const long_line = touches_command_reference(root, absolute_files)
+		? long_line_message(root)
+		: undefined
+
+	return report([long_line, ...citation_messages(root, absolute_files)])
+}
+
+// The whole-tree fallback: the long-line ceiling and every recorded document, a superset of any change.
+function check_all(root: string): number {
+	if (!project_checks.is_kit_repository(root)) return 0
+	const absolute_files = issue_citation_budget.ISSUE_CITATION_BUDGET.map((entry) =>
+		path.join(root, entry.path),
+	)
+
+	return report([long_line_message(root), ...citation_messages(root, absolute_files)])
+}
+
+const document_ratchet_check = { check_all, check_files }
+
+export { document_ratchet_check }

package/scripts/document/document-scan.ts

@@ -57,7 +57,7 @@ function command_references(text: string): Array<string> {
 		.filter((name) => !name.endsWith(':'))
 }
 
-// A `<placeholder>` inside a command, and `depth:<n>` after the char class stops at `<`, both leave a
+// A `<placeholder>` inside a command, and `label:<n>` after the char class stops at `<`, both leave a
 // token that is not a real label. Real labels never end in a colon and never carry angle brackets.
 function is_real_label(token: string): boolean {
 	return token.length > 0 && !token.endsWith(':') && !token.includes('<')

package/scripts/document/document-section-cli.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -22,7 +21,6 @@ import { entry_read_set } from './entry-read-set'
 // renamed would otherwise print nothing and read as a section with nothing in it — the one outcome
 // that is worse than reading the whole file.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const FILE_ARGUMENT = 0
 const HEADING_ARGUMENT = 1
@@ -101,12 +99,6 @@ function run(argv: ReadonlyArray<string>, root: string = process.cwd()): number
 	return markdown === undefined ? FAILURE_EXIT_CODE : print_section(markdown, heading, root)
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
-}
-
 const document_section_cli = { FAILURE_EXIT_CODE, USAGE, resolve_document, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
-
 export { document_section_cli }

package/scripts/document/document-section-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { document_section_cli } from './document-section-cli'
+
+// The `josh doc:section` entry, kept apart from `document-section-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = document_section_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/document/document-section.ts

@@ -262,6 +262,7 @@ function read_optional(file_path: string): string | undefined {
 
 const document_section = {
 	candidates,
+	fenced_flags,
 	headings,
 	read_optional,
 	section,

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

@@ -34,6 +34,9 @@ const { block_ceiling } = document_byte_budget
 const { LANE_CHILD } = lane_child_read_set
 const { BACKLOGRUN } = backlogrun_parent_read_set
 const NOTHING = 0
+// The command that re-measures every entry total in seconds, named by the over-budget message so a
+// trim is checked without re-running the whole lint or gate.
+const RECHECK_COMMAND = 'pnpm josh bytes'
 
 interface EntryBudget {
 	entry: string
@@ -46,8 +49,8 @@ interface EntryBudget {
 const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	{ entry: 'kickoff', bytes: 36_864 },
 	{ entry: 'fullrun', bytes: 53_248 },
-	{ entry: 'halfrun', bytes: 49_152 },
-	{ entry: 'prrun', bytes: 53_248 },
+	{ entry: 'halfrun', bytes: 45_056 },
+	{ entry: 'prrun', bytes: 57_344 },
 	{ entry: 'backlogrun', bytes: 81_920 },
 	{ entry: LANE_CHILD, bytes: 45_056 },
 ]
@@ -95,7 +98,7 @@ function over_budget_message(entry: string, current_bytes: number, recorded_byte
 	const next = block_ceiling(current_bytes).toString()
 	const raise_hint = `raise its recorded size to ${next} in scripts/document/entry-read-budget.ts so the reason shows in the PR diff`
 
-	return `entry ${entry} reads ${current_bytes.toString()} bytes, over its ${recorded_bytes.toString()}-byte ceiling. Trim what it reads, or ${raise_hint}.`
+	return `entry ${entry} reads ${current_bytes.toString()} bytes, over its ${recorded_bytes.toString()}-byte ceiling. Trim what it reads, or ${raise_hint}. Recheck with \`${RECHECK_COMMAND}\`.`
 }
 
 // The stale-ratchet message: a recorded ceiling more than a block above the entry's actual total was
@@ -113,6 +116,7 @@ function stale_budget_message(
 
 const entry_read_budget = {
 	ENTRY_READ_BUDGET,
+	RECHECK_COMMAND,
 	entry_total_bytes,
 	over_budget_message,
 	recorded_bytes_for,

package/scripts/document/issue-citation-budget.ts

@@ -0,0 +1,94 @@
+// The issue-number citation ceiling of every agent-read document — an exact ratchet.
+//
+// Issue-number citations and the "why / measured / rejected" prose around them are what swell the
+// documents an agent reads at run time; a reduction epic cuts them only for the next PRs to add them
+// back, because nothing held the reduced count. This list is that hold:
+// `issue-citation-budget.test.ts` fails `pnpm josh gate` when an agent-read document cites more issue
+// numbers than its entry records, and when it cites fewer — a reduction must lower its entry in the
+// same PR, so the ceiling follows the count down and never sits loose above it. A document absent from
+// the list has a ceiling of zero. History belongs in `docs/maintainers/<topic>-rationale.md`, which
+// this budget does not hold (`docs/maintainers/residency-rationale.md` → "The issue-citation ratchet").
+//
+// The ratchet is exact rather than block-quantized like `document-byte-budget.ts`: a single added
+// citation is the growth this exists to refuse, so there is no headroom to quantize.
+
+interface CitationBudget {
+	path: string
+	citations: number
+}
+
+// An issue number as a document cites it — `#1234` or `joshuafolkken/kit#1234`. Three digits or more,
+// so a placeholder (`#N`, `#<N>`) and a list ordinal are not counted.
+const CITATION_PATTERN = /#\d{3,}\b/gu
+
+const ISSUE_CITATION_BUDGET: ReadonlyArray<CitationBudget> = [
+	{ path: 'docs/josh-commands-backlog.md', citations: 13 },
+	{ path: 'docs/josh-commands-run.md', citations: 4 },
+	{ path: 'docs/josh-commands.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/file-edits.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/glossary.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/issue-citation.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/issue-template.md', citations: 5 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/output-bounds.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/overview.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/plan-comment.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/principles.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/report-format.md', citations: 7 },
+	{ path: 'prompts/collaboration-workflow/residency.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', citations: 5 },
+	{ path: 'prompts/collaboration-workflow/shell-body.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', citations: 2 },
+	{ path: 'prompts/refactoring.md', citations: 1 },
+	{ path: 'prompts/review-rubric.md', citations: 1 },
+	{ path: 'prompts/sonar-hotspot-handling.md', citations: 2 },
+	{ path: 'prompts/testing-guide.md', citations: 3 },
+]
+
+const BUDGET_FILE = 'scripts/document/issue-citation-budget.ts'
+
+function count_citations(text: string): number {
+	return text.match(CITATION_PATTERN)?.length ?? 0
+}
+
+// The recorded ceiling for one path — zero when the list carries no entry for it.
+function recorded_citations_for(relative_path: string): number {
+	return ISSUE_CITATION_BUDGET.find((entry) => entry.path === relative_path)?.citations ?? 0
+}
+
+function over_budget_message(relative_path: string, current: number, recorded: number): string {
+	const hint = `move the history to docs/maintainers/<topic>-rationale.md, or record ${current.toString()} in ${BUDGET_FILE} so the reason shows in the PR diff`
+
+	return `${relative_path} cites ${current.toString()} issue numbers, over its ceiling of ${recorded.toString()}. Cut the citations — ${hint}.`
+}
+
+function stale_budget_message(relative_path: string, current: number, recorded: number): string {
+	const hint = `lower its entry to ${current.toString()} in ${BUDGET_FILE} (remove the entry at 0) so the ratchet holds the reduction`
+
+	return `${relative_path} cites ${current.toString()} issue numbers but records ${recorded.toString()}. ${hint}.`
+}
+
+// The failure for one document, or undefined when its count equals its record. Growth and a
+// reduction left unrecorded both fail, which is what makes the ceiling a ratchet rather than a cap.
+function citation_violation(
+	relative_path: string,
+	current: number,
+	recorded: number,
+): string | undefined {
+	if (current > recorded) return over_budget_message(relative_path, current, recorded)
+	if (current < recorded) return stale_budget_message(relative_path, current, recorded)
+
+	return undefined
+}
+
+const issue_citation_budget = {
+	ISSUE_CITATION_BUDGET,
+	citation_violation,
+	count_citations,
+	recorded_citations_for,
+}
+
+export type { CitationBudget }
+export { issue_citation_budget }

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

@@ -222,22 +222,27 @@ function fetch_anomalies(
 //
 // A listing that could not be read is left out of the map rather than entered as `[]`, so a
 // transport failure reads as "not asked" instead of "nobody recorded anything" — the finding it
-// would otherwise manufacture is an `error`, which stops the epic.
+// would otherwise manufacture is an `error`, which stops the epic. Only a comment from an author with
+// write access records a rationale.
 async function read_order_comments(
 	pairs: ReadonlyArray<OrderPair>,
 ): Promise<Map<string, ReadonlyArray<string>>> {
 	const ends = epic_audit_rationale.pair_ends(pairs)
-	const listings = await Promise.all(
-		ends.map(async (child) => await git_gh_command.issue_list_comments(String(child.number))),
+	const parsed = await Promise.all(
+		ends.map(async (child) => {
+			const listing = await git_gh_command.issue_list_comments(String(child.number))
+
+			return await issue_read.parse_comments(listing)
+		}),
 	)
 
 	return new Map(
 		ends.flatMap((child, index) => {
-			const comments = issue_read.parse_comments(listings[index])
+			const comments = parsed[index]
 
 			return comments === undefined
 				? []
-				: [[epic_graph.key_of(child), comments.map((comment) => comment.body)] as const]
+				: [[epic_graph.key_of(child), issue_read.trusted_bodies(comments)] as const]
 		}),
 	)
 }
@@ -349,7 +354,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.
+// is in `scripts/cost-runtime/cost-main.ts`, which met the truncation first.
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
@@ -360,6 +365,7 @@ const epic_audit_cli = {
 	attach_bodies,
 	resolve_reference_states,
 	outside_references,
+	read_order_comments,
 	audit,
 	run,
 }

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

@@ -0,0 +1,137 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { epic_add } from './epic-add'
+import {
+	epic_bundle,
+	type BacklogIssue,
+	type BundleAction,
+	type BundleDecision,
+} from './epic-bundle'
+import { epic_reconcile } from './epic-reconcile'
+import { epic_run } from './epic-run'
+
+// `josh epic:bundle <N> --apply` — write the answer whose placement is settled: `add_to_epic` through
+// `epic --add`'s writer, `create_epic` through `epic`'s. Nothing here edits an epic itself, so the
+// task list and the `blocked-by` relations stay as those writers keep them.
+//
+// **An order the candidates already record is carried into the epic body** by `epic --reconcile`,
+// which declares exactly the recorded relations — an order nobody recorded is never invented.
+//
+// `ask` stays the caller's: which epic to choose is a judgement, recorded with its reasoning.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface ApplyInput {
+	decision: BundleDecision
+	subject: BacklogIssue
+	// The backlog rows of `decision.candidates`, as `format_order` reads them.
+	members: ReadonlyArray<BacklogIssue>
+	is_membership_established: boolean
+}
+
+const UNAPPLIED_LINES: Readonly<Partial<Record<BundleAction, string>>> = {
+	ask: '↷ `--apply` wrote nothing: the related issues sit in more than one epic. Choose one and place it with `pnpm josh epic --add <E> <N> --decision-file <path>`.',
+	none: '↷ `--apply` wrote nothing: there is nothing to place.',
+}
+const WITHHELD_LINE =
+	'↷ `--apply` wrote nothing: the epic listing was cut short, so no placement was confirmed.'
+const UNREAD_EPIC_LINE =
+	"✖ The new epic's number could not be read, so the recorded order was not written; run `pnpm josh epic --reconcile <E>` on it."
+
+function has_order(input: ApplyInput): boolean {
+	return epic_bundle.bundle_dependency_links(input.subject, input.members).length > 0
+}
+
+function children_of(input: ApplyInput): Array<number> {
+	return epic_bundle.bundle_children(input.subject, input.members)
+}
+
+// An epic whose number could not be read cannot be given the order, so that is a failure rather than
+// an order silently left out.
+async function reconcile_order(
+	epic_number: number | undefined,
+	input: ApplyInput,
+): Promise<number> {
+	if (!has_order(input)) return SUCCESS_EXIT_CODE
+
+	if (epic_number === undefined) {
+		console.error(UNREAD_EPIC_LINE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await epic_reconcile.reconcile_epic(epic_number)
+}
+
+// A member another epic tracks stays there: `add_to_epic` can name an inner epic while a candidate sits
+// in its parent, and adding that candidate here would put one issue in two task lists.
+function placeable(epic_number: number, input: ApplyInput): ApplyInput {
+	const members = input.members.filter(
+		(member) => member.epic === undefined || member.epic === epic_number,
+	)
+
+	return { ...input, members }
+}
+
+async function add_to_epic(epic_number: number, input: ApplyInput): Promise<number> {
+	const placed = placeable(epic_number, input)
+	const added = await epic_add.add_children({ epic_number, children: children_of(placed) })
+	if (added !== SUCCESS_EXIT_CODE) return added
+
+	return await reconcile_order(epic_number, placed)
+}
+
+// The title is the subject's, since the subject is what the bundle was asked about; the rationale is
+// the verdict's own reason, which already names the signal that grouped them.
+function title_of(subject: BacklogIssue): string {
+	const title = subject.title ?? `bundle with ${issue_cite.plain(subject.number)}`
+
+	return `Epic: ${title}`
+}
+
+async function create_epic(input: ApplyInput): Promise<number> {
+	const epic_number = await epic_run.create_epic_number({
+		title: title_of(input.subject),
+		children: children_of(input),
+		rationale: input.decision.reason,
+		is_ordered: false,
+	})
+
+	return await reconcile_order(epic_number, input)
+}
+
+function report_unapplied(action: BundleAction): number {
+	const line = UNAPPLIED_LINES[action]
+	if (line !== undefined) console.info(line)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function apply_decision(input: ApplyInput): Promise<number> {
+	const { decision } = input
+
+	if (!input.is_membership_established) {
+		console.info(WITHHELD_LINE)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	if (decision.action === 'add_to_epic' && decision.epic !== undefined) {
+		return await add_to_epic(decision.epic, input)
+	}
+
+	if (decision.action === 'create_epic') return await create_epic(input)
+
+	return report_unapplied(decision.action)
+}
+
+const epic_bundle_apply = {
+	UNAPPLIED_LINES,
+	WITHHELD_LINE,
+	UNREAD_EPIC_LINE,
+	title_of,
+	apply_decision,
+}
+
+export { epic_bundle_apply }
+export type { ApplyInput }