@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/delegation/duplicate-read-guard.ts

@@ -1,7 +1,4 @@
-#!/usr/bin/env tsx
 import { statSync } from 'node:fs'
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
 import { json_value } from '#scripts/lib/json-value'
@@ -217,11 +214,6 @@ const duplicate_reads = {
 	NOTICE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('duplicate-read:guard')
-	else hook_decision.write_outcome(await text(process.stdin), duplicate_read_outcome)
-}
-
 export {
 	deny_envelope,
 	DISABLED_VALUES,

package/scripts/delegation/investigation-guard.ts

@@ -1,6 +1,3 @@
-#!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
-import { fileURLToPath } from 'node:url'
 import { agent_session_role } from '#scripts/agent/agent-session-role'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { lane_guard_policy } from '#scripts/lane/lane-guard-policy'
@@ -60,11 +57,6 @@ const investigation_outcome = GUARD.outcome
 const { is_enabled, refusal_path } = GUARD
 const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('investigation:guard')
-	else hook_decision.write_outcome(await text(process.stdin), investigation_outcome)
-}
-
 export {
 	deny_envelope,
 	investigation_outcome,

package/scripts/delegation/investigation-reads.ts

@@ -38,11 +38,10 @@ const SEARCH_LABELS: ReadonlySet<string> = new Set(
 	SEARCH_COMMANDS.map((command) => time_shell.bash_label(command)),
 )
 
-// `.claude/agents/investigator.md`; a consumer receives it through the plugin as `kit:investigator`.
-const INVESTIGATOR_AGENT = 'investigator'
+const { INVESTIGATOR_AGENT } = delegation_policy
 
 // The deny reason is the only text that reaches the model, so it names the count, command and return shape.
-const REASON = `⛔ investigation: ${String(delegation_policy.INVESTIGATION_FILE_THRESHOLD)} files read and not edited, or ${String(delegation_policy.INVESTIGATION_SEARCH_TURN_THRESHOLD)} search turns, since the last delegated unit. Run \`pnpm josh delegate investigation\`, then dispatch the \`${INVESTIGATOR_AGENT}\` agent (\`kit:${INVESTIGATOR_AGENT}\` in a consumer); it returns \`file:line\` citations, never the file text. Keep main-line reads to files you will edit; every read-only search turn counts. \`.claude/skills/workflow-commands/delegation.md\``
+const REASON = `⛔ investigation: ${delegation_policy.INVESTIGATION_LIMIT}. ${delegation_policy.INVESTIGATION_STEP} Keep main-line reads to files you will edit; every read-only search turn counts. \`.claude/skills/workflow-commands/delegation.md\``
 
 interface ReadTally {
 	// The files read and not since edited, resolved.
@@ -61,7 +60,7 @@ interface ReadTally {
 }
 
 // The run's own instructions are not the Issue's subject and cannot be delegated, so they never count.
-// Matched relative to the repository root, so `scripts/eval/prompts/x.ts` stays subject code.
+// Matched relative to the repository root, so `tools/eval/prompts/x.ts` stays subject code.
 const INSTRUCTION_PATHS: ReadonlyArray<string> = ['prompts', '.claude/skills']
 const INSTRUCTION_FILES: ReadonlySet<string> = new Set(['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'])
 const REPOSITORY_ROOT = process.cwd()

package/scripts/dependabot/dependabot-cooldown.ts

@@ -0,0 +1,194 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import {
+	DEFAULT_RELEASE_AGE_MINUTES,
+	release_window,
+	type ReleaseWindow,
+} from '#scripts/version/release-window'
+
+// Dependabot's `cooldown` is the workspace's `minimumReleaseAge` restated in days, so a freshly
+// published action or package waits out the same window pnpm and Safe Chain enforce (kit #4023).
+// The edit is line-based and touches only each entry's `cooldown` block: a consumer's own keys and
+// the file's comments survive, which a YAML round trip would discard.
+const DEPENDABOT_FILE = path.join('.github', 'dependabot.yml')
+const MINUTES_PER_DAY = 1440
+// Dependabot accepts `default-days` from 1 to 90.
+const MIN_DAYS = 1
+const MAX_DAYS = 90
+// pnpm's exclusions name npm packages, so only the npm entry receives them.
+const NPM_ECOSYSTEM = 'npm'
+const UPDATES_PATTERN = /^updates:\s*(?:#.*)?$/u
+const ECOSYSTEM_PATTERN = /^\s*(?:-\s+)?package-ecosystem:\s*['"]?([\w-]+)/u
+const TOP_LEVEL_KEY_PATTERN = /^[^\s#-]/u
+const COOLDOWN_KEY = 'cooldown:'
+
+interface UpdateEntry {
+	start: number
+	end: number
+	key_indent: string
+}
+
+function cooldown_days(minutes: number | undefined): number {
+	const days = Math.ceil((minutes ?? DEFAULT_RELEASE_AGE_MINUTES) / MINUTES_PER_DAY)
+
+	return Math.min(MAX_DAYS, Math.max(MIN_DAYS, days))
+}
+
+function quote(value: string): string {
+	return `'${value.replaceAll("'", "''")}'`
+}
+
+function cooldown_lines(ecosystem: string, window: ReleaseWindow, indent: string): Array<string> {
+	const lines = ['cooldown:', `  default-days: ${String(cooldown_days(window.minutes))}`]
+
+	if (ecosystem === NPM_ECOSYSTEM && window.exclusions.length > 0) {
+		lines.push('  exclude:', ...window.exclusions.map((name) => `    - ${quote(name)}`))
+	}
+
+	return lines.map((line) => `${indent}${line}`)
+}
+
+function indent_width(line: string): number {
+	return line.length - line.trimStart().length
+}
+
+function is_blank(line: string | undefined): boolean {
+	return line?.trim() === ''
+}
+
+function trim_trailing_blanks(lines: ReadonlyArray<string>): Array<string> {
+	const trimmed = [...lines]
+	while (trimmed.length > 1 && is_blank(trimmed.at(-1))) trimmed.pop()
+
+	return trimmed
+}
+
+function is_comment(line: string | undefined): boolean {
+	return line?.trimStart().startsWith('#') === true
+}
+
+// A blank line, or a comment left of `width`: it may sit inside a block or head the next one.
+function is_detached(line: string | undefined, width: number): boolean {
+	return is_blank(line) || (is_comment(line) && indent_width(line ?? '') < width)
+}
+
+// The first key line at or after `from` that sits left of `width`, or `limit`.
+function block_stop(
+	lines: ReadonlyArray<string>,
+	from: number,
+	width: number,
+	limit: number,
+): number {
+	const relative = lines
+		.slice(from, limit)
+		.findIndex((line) => !is_blank(line) && !is_comment(line) && indent_width(line) < width)
+
+	return relative === -1 ? limit : from + relative
+}
+
+// The block runs to the next key line left of `width`. A comment left of `width` in the middle stays
+// inside, while the run of such comments right before that key belongs to what follows.
+function block_end(
+	lines: ReadonlyArray<string>,
+	from: number,
+	width: number,
+	limit: number,
+): number {
+	const stop = block_stop(lines, from, width, limit)
+	let end = stop
+
+	for (let index = stop - 1; index >= from && is_detached(lines[index], width); index -= 1) {
+		if (!is_blank(lines[index])) end = index
+	}
+
+	return end
+}
+
+// The next top-level key. A list written flush with `updates:` and a comment at column 0 both still
+// belong to it, so neither ends the list.
+function updates_end(lines: ReadonlyArray<string>, updates: number): number {
+	const relative = lines.slice(updates + 1).findIndex((line) => TOP_LEVEL_KEY_PATTERN.test(line))
+
+	return relative === -1 ? lines.length : updates + 1 + relative
+}
+
+function find_entries(lines: ReadonlyArray<string>, updates: number): Array<UpdateEntry> {
+	const limit = updates_end(lines, updates)
+	const starts = lines
+		.map((line, index) => ({ index, item: /^(\s*-\s+)\S/u.exec(line)?.[1] }))
+		.filter(({ index, item }) => index > updates && index < limit && item !== undefined)
+	const item_width = Math.min(...starts.map(({ item }) => item?.indexOf('-') ?? 0))
+
+	return starts
+		.filter(({ item }) => item?.indexOf('-') === item_width)
+		.map(({ index, item = '' }) => ({
+			start: index,
+			end: block_end(lines, index + 1, item.length, limit),
+			key_indent: ' '.repeat(item.length),
+		}))
+}
+
+// The entry's own `cooldown:` key, either on a key line or on the item line itself (`- cooldown:`).
+function is_cooldown_key(line: string, index: number, key_indent: string): boolean {
+	const is_key_line = index === 0 || line.startsWith(key_indent)
+
+	return is_key_line && line.slice(key_indent.length).startsWith(COOLDOWN_KEY)
+}
+
+// An entry that opened with `- cooldown:` hands its item marker to the next key once the block goes.
+function promote_first_key(rest: ReadonlyArray<string>, marker: string): Array<string> {
+	const first = rest.findIndex((line) => !is_blank(line) && !line.trimStart().startsWith('#'))
+
+	return rest.map((line, index) =>
+		index === first ? `${marker}${line.slice(marker.length)}` : line,
+	)
+}
+
+function without_cooldown(entry: ReadonlyArray<string>, key_indent: string): Array<string> {
+	const start = entry.findIndex((line, index) => is_cooldown_key(line, index, key_indent))
+	if (start === -1) return [...entry]
+	const rest = entry.slice(block_end(entry, start + 1, key_indent.length + 1, entry.length))
+	if (start > 0) return [...entry.slice(0, start), ...rest]
+
+	return promote_first_key(rest, (entry.at(0) ?? '').slice(0, key_indent.length))
+}
+
+function rewrite_entry(
+	entry: ReadonlyArray<string>,
+	key_indent: string,
+	window: ReleaseWindow,
+): Array<string> {
+	const ecosystem = entry.map((line) => ECOSYSTEM_PATTERN.exec(line)?.[1]).find(Boolean)
+	if (ecosystem === undefined) return [...entry]
+	const body = trim_trailing_blanks(without_cooldown(entry, key_indent))
+	const trailing = entry.slice(trim_trailing_blanks(entry).length)
+
+	return [...body, ...cooldown_lines(ecosystem, window, key_indent), ...trailing]
+}
+
+function merge_cooldown(existing: string, window: ReleaseWindow): string {
+	const lines = existing.split('\n')
+	const updates = lines.findIndex((line) => UPDATES_PATTERN.test(line))
+	if (updates === -1) return existing
+
+	for (const { start, end, key_indent } of find_entries(lines, updates).toReversed()) {
+		lines.splice(start, end - start, ...rewrite_entry(lines.slice(start, end), key_indent, window))
+	}
+
+	return lines.join('\n')
+}
+
+function sync_dependabot_cooldown(root: string): boolean {
+	const config_path = path.join(root, DEPENDABOT_FILE)
+	if (!existsSync(config_path)) return false
+	const existing = readFileSync(config_path, 'utf8')
+	const merged = merge_cooldown(existing, release_window.read_release_window(root))
+	if (merged === existing) return false
+	writeFileSync(config_path, merged)
+
+	return true
+}
+
+const dependabot_cooldown = { cooldown_days, merge_cooldown, sync_dependabot_cooldown }
+
+export { dependabot_cooldown }

package/scripts/discovery/repo-discovery.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
+import { stamped_memo } from '#scripts/lib/stamped-memo'
 import { repo_map_logic, type DiscoveredRepo, type RepoMap } from './repo-map-logic'
 import { repo_origin } from './repo-origin'
 
@@ -59,18 +60,35 @@ function resolve_git_directory(repository_path: string): string | undefined {
 	}
 }
 
-// The work tree's git config text, or nothing when it is unreadable or not a work tree.
-function read_config(repository_path: string): string | undefined {
-	const git_directory = resolve_git_directory(repository_path)
-	if (git_directory === undefined) return undefined
-
+function read_text(file: string): string | undefined {
 	try {
-		return readFileSync(path.join(git_directory, GIT_CONFIG), 'utf8')
+		return readFileSync(file, 'utf8')
 	} catch {
 		return undefined
 	}
 }
 
+// Each work tree's git directory and each config's text, read again only once the `.git` entry or the
+// config itself has changed: `run:board` cites issues through the origin on every redraw
+// (joshuafolkken/kit#4263).
+const git_directories = stamped_memo.create<string | undefined>()
+const configs = stamped_memo.create<string | undefined>()
+
+// The work tree's git config text, or nothing when it is unreadable or not a work tree.
+function read_config(repository_path: string): string | undefined {
+	const git_entry = path.join(repository_path, GIT_DIRECTORY)
+	const git_directory = git_directories.of(
+		repository_path,
+		stamped_memo.file_stamp(git_entry),
+		() => resolve_git_directory(repository_path),
+	)
+	if (git_directory === undefined) return undefined
+
+	const config = path.join(git_directory, GIT_CONFIG)
+
+	return configs.of(config, stamped_memo.file_stamp(config), () => read_text(config))
+}
+
 // The `origin` URL a work tree declares, or nothing when it has no `origin`, no readable config, or
 // is not a work tree at all. Every failure reads as "no remote" so one unreadable sibling cannot
 // fail a command whose contract is to report what it could find.

package/scripts/doctor/doctor-consumer.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
@@ -37,11 +38,7 @@ const STATE_MISSING = 'missing'
 type ClaudeMdState = typeof STATE_OK | typeof STATE_TARGET_MISSING | typeof STATE_MISSING
 
 function parse_manifest(root: string): ManifestShape | undefined {
-	const content = file_reader.read_if_readable(path.join(root, 'package.json'))
-	if (content === undefined) return undefined
-	const parsed = manifest_schema.safeParse(json_value.parse_or_undefined(content))
-
-	return parsed.success ? parsed.data : undefined
+	return package_manifest.read_manifest_if_valid(root, manifest_schema)
 }
 
 function lists_kit_dependency(manifest: ManifestShape | undefined): boolean {

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,10 @@ 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 },
-	{ 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 },
+	{ path: 'docs/josh-commands-automation.md', bytes: 45_056 },
+	{ path: 'docs/josh-commands-run.md', bytes: 69_632 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands.md', bytes: 53_248 },
 	{ 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 +84,10 @@ 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.
+	{ path: 'prompts/collaboration-workflow/issue-template.md', bytes: 12_288 },
 	{ 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 },

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/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 }