@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/epic/epic-lane-offer.ts

@@ -1,4 +1,5 @@
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_snapshot_trace } from '#scripts/lane/lane-snapshot-trace'
 import { epic_busy, type BusyRead } from './epic-busy'
 import {
 	epic_candidate_confirm,
@@ -39,11 +40,13 @@ interface RepoPool {
 
 // What is being asked of one repository. `is_all_lanes` is the caller's appetite rather than the
 // repository's capacity: `epic:next --repo` prints a single token unless `--lanes` was passed, so a
-// caller written against the one-child contract keeps getting exactly one child.
+// caller written against the one-child contract keeps getting exactly one child. `is_this_checkout`
+// says whether `repo` is the repository this command runs in, whose ship records are the ones read.
 interface LaneRequest {
 	repo: string
 	limit: number
 	is_all_lanes: boolean
+	is_this_checkout: boolean
 }
 
 // The answer for one repository: the children to start, the verdict standing in their place when
@@ -62,8 +65,27 @@ function is_held(read: BusyRead): boolean {
 	return read.kind === 'unreadable' || read.kind === 'truncated'
 }
 
-function free_lanes(read: BusyRead, limit: number): number {
-	return is_held(read) ? NO_LANES : lane_capacity.free_lanes(limit, epic_busy.occupied_lanes(read))
+function free_lanes(read: BusyRead, limit: number, merge_waiting: number): number {
+	if (is_held(read)) return NO_LANES
+
+	const holders = epic_busy.occupied_lanes(read)
+
+	// A merge-waiting holder frees its place under the limit but keeps its port seat
+	// (`lane_capacity.free_lanes`).
+	return lane_capacity.free_lanes(limit, holders - merge_waiting, holders)
+}
+
+// **A holder whose detached ship waits on its merge holds no lane** — the count `backlog:drive` makes
+// for the pool (`backlog-occupied.ts`), so a named epic's lanes are offered the place too
+// (joshuafolkken/kit#4466). It keeps `in-progress` until the merge. The ship records read are this
+// checkout's, so a `--repo` naming another repository is discounted nothing: its holder numbers
+// would be matched against this repository's unrelated ships.
+async function merge_waiting_holders(read: BusyRead, request: LaneRequest): Promise<number> {
+	if (read.kind !== 'busy' || !request.is_this_checkout) return NO_LANES
+
+	return await lane_snapshot_trace.count_merge_waiting(
+		read.issues.map((issue) => String(issue.number)),
+	)
 }
 
 function wanted_of(request: LaneRequest, free: number): number {
@@ -247,7 +269,7 @@ async function offer_for_repo(
 
 	if (notice !== undefined) console.error(notice)
 
-	const free = free_lanes(read, request.limit)
+	const free = free_lanes(read, request.limit, await merge_waiting_holders(read, request))
 	const ages = await holder_ages(read, request.repo)
 
 	if (free === NO_LANES) {
@@ -263,9 +285,22 @@ async function offer_for_repo(
 	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request, ages)
 }
 
+// A `--repo` compared against the repository this command runs in, case-insensitively as GitHub
+// names it.
+function lane_request(
+	asked: Pick<LaneRequest, 'repo' | 'is_all_lanes'>,
+	limit: number,
+	current_repo: string,
+): LaneRequest {
+	const is_this_checkout = asked.repo.toLowerCase() === current_repo.toLowerCase()
+
+	return { ...asked, limit, is_this_checkout }
+}
+
 const epic_lane_offer = {
 	combine_verdicts,
 	dedupe_pools,
+	lane_request,
 	offer_for_repo,
 }
 

package/scripts/epic/epic-next-main.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { epic_next } from './epic-next'
+
+// The `josh epic:next` entry, kept apart from `epic-next.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).
+//
+// `.env` is read here rather than through the dispatcher's `tsx_arguments`: declaring any would
+// disqualify this command from in-process dispatch, and an unattended `epicrun` asks it every sixty
+// seconds for the whole life of a run (`josh-environment-file.ts` records the measurement). Inside the
+// guard, so a developer's own `.env` cannot decide what the unit tests see.
+//
+// `process.exitCode` rather than `process.exit()`, for the reason `scripts/cost-runtime/cost-main.ts`
+// records: 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 contract is
+// `answer=$(pnpm josh epic:next <E>)`, which is exactly that pipe.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	josh_environment_file.load_environment_file()
+	process.exitCode = await epic_next.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/epic/epic-next.ts

@@ -1,9 +1,6 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
@@ -31,7 +28,6 @@ import { epic_report, type EpicNextResult } from './epic-report'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // Asking for every free lane (`--lanes`) is opt-in, so the answer stays one token for a caller that
 // has not been changed. `--repo` alone prints exactly one number.
 const OPTIONS = { repo: { type: 'string' }, lanes: { type: 'boolean' } } as const
@@ -351,11 +347,13 @@ async function report_epics(
 	const choice = await lane_capacity.lane_limit()
 	if (choice.kind === 'problem') return refuse(choice.problem)
 
-	return await report(
-		views,
-		{ repo: options.repo, limit: choice.limit, is_all_lanes: options.is_all_lanes ?? false },
+	const request = epic_lane_offer.lane_request(
+		{ repo: options.repo, is_all_lanes: options.is_all_lanes ?? false },
+		choice.limit,
 		current_repo,
 	)
+
+	return await report(views, request, current_repo)
 }
 
 // One view per named epic, classified against one shared registry read. `running` is every named
@@ -416,14 +414,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await run_epics(options)
 }
 
-// `process.exitCode` rather than `process.exit()`, for the reason `scripts/cost-runtime/cost-cli.ts` records:
-// 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 contract is `answer=$(pnpm josh epic:next
-// <E>)`, which is exactly that pipe.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const epic_next = {
 	EXTERNAL_NOTICE,
 	FOREIGN_EPIC,
@@ -433,19 +423,11 @@ const epic_next = {
 	parse_options,
 	refuse_reads,
 	views_of,
+	run,
 	run_epics,
 	decide,
 	report,
 }
 
-// `.env` is read here rather than through the dispatcher's `tsx_arguments`: declaring any would
-// disqualify this command from in-process dispatch, and an unattended `epicrun` asks it every sixty
-// seconds for the whole life of a run (`josh-environment-file.ts` records the measurement). Inside the guard
-// rather than in `main`, so a developer's own `.env` cannot decide what the unit tests see.
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	josh_environment_file.load_environment_file()
-	await main(process.argv.slice(ARGV_OFFSET))
-}
-
 export type { NextOptions }
 export { epic_next }

package/scripts/epic/epic-outside-blocker.ts

@@ -24,6 +24,10 @@ type DependencyVerdict = 'resolved' | 'time' | 'human' | 'inherit'
 // a closed blocker is a finished one.
 type ResolveDependency = (blocker: EpicChild, blocked: EpicChild) => DependencyVerdict
 
+// A notice's mark on `run:board`: ❗ rather than ⚠, a text symbol drawn two columns wide over the
+// blank after it.
+const NOTICE_ICON = '❗'
+
 type OutsideCategory = 'time' | 'human'
 
 // A line to announce once per invocation, keyed so the classifier's de-duplication can drop repeats.
@@ -62,7 +66,7 @@ function unread_answer(child: EpicChild, reference: IssueReference): OutsideAnsw
 		category: 'time',
 		notice: {
 			key: `unread:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
+			message: `${NOTICE_ICON} ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
 		},
 	}
 }
@@ -80,7 +84,7 @@ function open_answer(
 		category: 'human',
 		notice: {
 			key: `outside:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
+			message: `${NOTICE_ICON} ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
 		},
 	}
 }

package/scripts/epic/epic-parse.ts

@@ -16,7 +16,10 @@ const TASK_LIST_LINE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'u')
 // `owner/repo#101` on its own. The row patterns below are built from this source, so what counts as
 // a cross-repository reference has one definition — a second copy would let a form the task list
 // accepts be refused where a person types it, or the reverse.
-const EXTERNAL_REFERENCE_SOURCE = String.raw`([\w.-]+)\/([\w.-]+)#(\d+)`
+// A segment starts with a word character, so `.`, `..` and a leading `-` never become an owner or a
+// repository — `../..#1` would otherwise be read as one and walk the API path out of `repos/`.
+const REPOSITORY_SEGMENT_SOURCE = String.raw`\w[\w.-]*`
+const EXTERNAL_REFERENCE_SOURCE = String.raw`(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})#(\d+)`
 const EXTERNAL_REFERENCE_PATTERN = new RegExp(`^${EXTERNAL_REFERENCE_SOURCE}$`, 'u')
 const TASK_LIST_ROW_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+`
 const EXTERNAL_TASK_LIST_PATTERN = new RegExp(
@@ -29,8 +32,10 @@ const EXTERNAL_SHORTHAND_PATTERN = new RegExp(
 	'gmu',
 )
 // `- [ ] https://github.com/owner/repo/issues/101`
-const EXTERNAL_URL_PATTERN =
-	/^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)\b/gmu
+const EXTERNAL_URL_PATTERN = new RegExp(
+	String.raw`${TASK_LIST_ROW_SOURCE}https?:\/\/github\.com\/(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})\/issues\/(\d+)\b`,
+	'gmu',
+)
 
 // Fenced blocks are stripped before matching. An epic body may quote the body template itself, and
 // its sample rows (`- [ ] #101 <title>`) are illustrations, not tracked children — counting them
@@ -345,4 +350,5 @@ export {
 	is_state_closed,
 	UNORDERED_DEPENDENCIES,
 	DECLARED_CHAIN_LINE,
+	REPOSITORY_SEGMENT_SOURCE,
 }

package/scripts/epic/epic-rank.ts

@@ -1,3 +1,5 @@
+import { expected_effect_lint } from '#scripts/issue/expected-effect-lint'
+import { issue_priority } from '#scripts/issue/issue-priority'
 import { issue_rank } from '#scripts/issue/issue-rank'
 import { epic_graph, type EpicChild } from './epic-graph'
 
@@ -27,7 +29,10 @@ function rank(
 	const dependents = dependents_of(pool)
 
 	return issue_rank.rank(children, (child) => ({
+		is_last: issue_priority.is_last(child.body),
 		labels: child.labels,
+		lost_minutes: issue_priority.lost_minutes(child.body),
+		gain_minutes: expected_effect_lint.weekly_minutes(child.body),
 		dependents: dependents.get(epic_graph.key_of(child)) ?? 0,
 	}))
 }

package/scripts/epic/epic-read.ts

@@ -67,6 +67,7 @@ async function read_epic(epic_number: number): Promise<EpicReading | { error: st
 }
 
 const epic_read = {
+	read_subject,
 	read_epic,
 }
 

package/scripts/epic/epic-reconcile.ts

@@ -235,11 +235,50 @@ async function reconcile_epic(epic_number: number): Promise<number> {
 	return await apply_plan(epic_number, plan)
 }
 
+function with_recorded(
+	recorded: ReadonlyArray<EpicChild>,
+	link: DependencyLink,
+	repo: string,
+): Array<EpicChild> {
+	return recorded.map((child) =>
+		child.number === link.blocked && child.repo === repo
+			? { ...child, blocked_by: [...child.blocked_by, to_blocker(link, repo)] }
+			: child,
+	)
+}
+
+// The plan the epic would reconcile to once `link` is recorded, so a caller about to record it can
+// refuse first — a relation recorded and then refused leaves an order the declaration never carries.
+function build_plan_after(input: ReconcilePlanInput, link: DependencyLink): ReconcilePlan {
+	return build_reconcile_plan({
+		...input,
+		recorded: with_recorded(input.recorded, link, input.repo),
+	})
+}
+
+// Why reconciling after recording `link` would refuse, read before anything is written. An epic that
+// cannot be read throws: a failed read is no answer about whether the reconcile would refuse.
+async function refusal_after(
+	epic_number: number,
+	link: DependencyLink,
+): Promise<string | undefined> {
+	const epic = await epic_read.read_epic(epic_number)
+	if ('error' in epic) throw new Error(epic.error)
+
+	const input = { body: epic.subject.body, recorded: epic.recorded, repo: epic.repo }
+	const plan = build_plan_after(input, link)
+	if (plan.kind === 'cycle') return plan.message
+
+	return plan.kind === 'error' ? plan.error : undefined
+}
+
 const epic_reconcile = {
 	NOTHING_TO_RECONCILE,
 	RECONCILED,
+	build_plan_after,
 	build_reconcile_plan,
 	reconcile_epic,
+	refusal_after,
 }
 
 export { epic_reconcile }

package/scripts/epic/epic-run.ts

@@ -84,7 +84,9 @@ async function fill_run_command(
 	}
 }
 
-async function create_epic(input: CreateEpicInput): Promise<number> {
+// The created epic's number, or `undefined` when its URL could not be read — for a caller that writes
+// to the epic next (`epic:bundle --apply` reconciling a recorded order).
+async function create_epic_number(input: CreateEpicInput): Promise<number | undefined> {
 	await git_gh_command.label_ensure({
 		name: EPIC_LABEL,
 		color: EPIC_LABEL_COLOR,
@@ -110,6 +112,12 @@ async function create_epic(input: CreateEpicInput): Promise<number> {
 	await fill_run_command(epic_number, input)
 	console.info(`▶ Run the children with: ${epic_body.format_run_command(epic_number)}`)
 
+	return epic_number
+}
+
+async function create_epic(input: CreateEpicInput): Promise<number> {
+	await create_epic_number(input)
+
 	return SUCCESS_EXIT_CODE
 }
 
@@ -215,6 +223,7 @@ async function check_epic(epic_number: number): Promise<number> {
 
 const epic_run = {
 	create_epic,
+	create_epic_number,
 	promote_epic,
 	check_epic,
 }

package/scripts/epic/epic-solo.ts

@@ -1,5 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_busy, type BusyRead } from './epic-busy'
 import type { EpicChild } from './epic-graph'
@@ -28,8 +28,6 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // them goes first is the ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
 // repository takes the candidates in rank order like any other.
 
-const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
-
 // Which of the ordered candidates may start, which are held back, and why when a reason is worth
 // saying. `offered` keeps the candidates' own order.
 interface SoloSelection {
@@ -38,35 +36,65 @@ interface SoloSelection {
 	notice?: string
 }
 
+interface SoloQueue {
+	solo: EpicChild
+	index: number
+	behind: ReadonlyArray<EpicChild>
+}
+
 interface SoloGate {
 	result: EpicNextResult
 	notice?: string
 }
 
-function is_solo(child: EpicChild): boolean {
+// An issue as its number and its label names — a candidate, or a running issue `run:board` reads.
+type Labelled = Pick<EpicChild, 'number' | 'labels'>
+
+function is_solo(child: Labelled): boolean {
 	return has_label_name(child.labels, RUN_SOLO_LABEL)
 }
 
+// The running `run:solo` issue that lets nothing new start, if any — the one reading `select` and
+// `run:board`'s 🔒 rows share (joshuafolkken/kit#4391).
+function holder_of(running: ReadonlyArray<Labelled>): number | undefined {
+	return running.find((issue) => is_solo(issue))?.number
+}
+
 function solo_holder(read: BusyRead): number | undefined {
 	if (read.kind !== 'busy') return undefined
+	const running = read.issues.map((issue) => ({
+		number: issue.number,
+		labels: (issue.labels ?? []).map((label) => label.name),
+	}))
 
-	return read.issues.find((issue) => has_any_label(issue.labels, SOLO_LABELS))?.number
+	return holder_of(running)
 }
 
+// The words each of the gate's wait notices carries, so `backlog:offer` tells a `run:solo` wait from any
+// other `wait` off the notice `backlog:next` printed (joshuafolkken/kit#4396). Each names its verb:
+// `epic_solo_stale`'s release notice also opens "carries `run:solo` and", and is no wait.
+const HELD_MARK = `carries \`${RUN_SOLO_LABEL}\` and is running in`
+const WAITING_MARK = `carries \`${RUN_SOLO_LABEL}\` and waits for`
+
 function held_message(holder: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		`${issue_cite.plain(holder)} ${HELD_MARK} ${repo}; nothing else starts until it merges or is parked.`,
 		repo,
 	)
 }
 
 function waiting_message(solo: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		`${issue_cite.plain(solo)} ${WAITING_MARK} ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
 		repo,
 	)
 }
 
+// Whether `text` — what an offer printed on stderr — says the `run:solo` gate held the candidates.
+function is_solo_wait(text: string): boolean {
+	return text.includes(HELD_MARK) || text.includes(WAITING_MARK)
+}
+
 function first_of(children: ReadonlyArray<EpicChild>, keep: number): SoloSelection {
 	return { offered: children.slice(0, keep), withheld: children.slice(keep) }
 }
@@ -75,6 +103,15 @@ function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelect
 	return { offered: [], withheld: [...children], notice }
 }
 
+// The first `run:solo` candidate, where it sits, and the candidates ranked behind it, which nothing
+// offers past it. `run:board` draws the same reading on its queued rows (joshuafolkken/kit#4294).
+function queue_of(children: ReadonlyArray<EpicChild>): SoloQueue | undefined {
+	const index = children.findIndex((child) => is_solo(child))
+	const solo = children[index]
+
+	return solo === undefined ? undefined : { solo, index, behind: children.slice(index + 1) }
+}
+
 // Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
 // candidates ahead of it when it is not first, and it alone once it heads an idle repository's ranking.
 function select_candidates(
@@ -82,14 +119,13 @@ function select_candidates(
 	read: BusyRead,
 	repo: string,
 ): SoloSelection {
-	const index = children.findIndex((child) => is_solo(child))
-	const solo = children[index]
+	const queue = queue_of(children)
 
-	if (solo === undefined) return first_of(children, children.length)
-	if (index > 0) return first_of(children, index)
+	if (queue === undefined) return first_of(children, children.length)
+	if (queue.index > 0) return first_of(children, queue.index)
 	if (read.kind === 'idle') return first_of(children, 1)
 
-	return none_of(children, waiting_message(solo.number, repo))
+	return none_of(children, waiting_message(queue.solo.number, repo))
 }
 
 // An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
@@ -143,7 +179,7 @@ function gate(
 		: { result: gated, notice: selection.notice }
 }
 
-const epic_solo = { gate, is_solo, select }
+const epic_solo = { gate, holder_of, is_solo, is_solo_wait, queue_of, select }
 
-export type { SoloGate, SoloSelection, SoloSelector }
+export type { Labelled, SoloGate, SoloQueue, SoloSelection, SoloSelector }
 export { epic_solo }

package/scripts/epic/epic.ts

@@ -8,11 +8,13 @@
  *        tsx scripts/epic/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
  *                                                      [--decision-file <path|->]
  *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ *        tsx scripts/epic/epic.ts --decide <E> <N1> <N2> ... --decision-file <path|->
  */
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+import { epic_decide } from './epic-decide'
 import { epic_reconcile } from './epic-reconcile'
 import { epic_remove } from './epic-remove'
 import { epic_run } from './epic-run'
@@ -26,6 +28,7 @@ const USAGE = [
 	'       josh epic --add <E> <N1> <N2> ... [--order-before <M> | --order-after <M>] [--decision-file <path|->]',
 	'       josh epic --remove <E> <M> <N> ... [--decision-file <path|->]',
 	'       josh epic --reconcile <E>',
+	'       josh epic --decide <E> <N1> <N2> ... --decision-file <path|->',
 ].join('\n')
 const FAILURE_EXIT_CODE = 1
 
@@ -134,6 +137,26 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
+// A decision about children the epic already tracks — the half `--add --decision-file` cannot write,
+// since an insertion with nothing to add is refused.
+async function run_decision(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_decide_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(
+			`✖ An epic number, at least one child issue number, and exactly one readable \`--decision-file\` path (\`-\` reads stdin) are required.\n${USAGE}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await epic_decide.decide({
+		epic_number: parsed.epic_number,
+		children: parsed.children,
+		decision: epic_cli.read_decision(parsed.decision_path) ?? '',
+	})
+}
+
 // Reconcile an epic's declaration with its recorded relations. No decision file and no children: the
 // repair reads what the epic already records rather than being told an order.
 async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number> {
@@ -166,15 +189,26 @@ async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
-// `--add` is checked before `--promote`: both name an existing issue first, and only the flag
-// distinguishes "insert into this epic" from "turn this issue into one".
+type EpicForm = readonly [
+	(argv: ReadonlyArray<string>) => boolean,
+	(argv: ReadonlyArray<string>) => Promise<number>,
+]
+
+// Checked in this order. `--add` comes before `--promote`: both name an existing issue first, and only
+// the flag distinguishes "insert into this epic" from "turn this issue into one".
+const FLAGGED_FORMS: ReadonlyArray<EpicForm> = [
+	[epic_cli.is_reconciliation, run_reconciliation],
+	[epic_cli.is_removal, run_removal],
+	[epic_cli.is_decision_entry, run_decision],
+	[epic_cli.is_addition, run_addition],
+	[epic_cli.is_promotion, run_promotion],
+]
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	if (epic_cli.is_reconciliation(argv)) return await run_reconciliation(argv)
-	if (epic_cli.is_removal(argv)) return await run_removal(argv)
-	if (epic_cli.is_addition(argv)) return await run_addition(argv)
-	if (epic_cli.is_promotion(argv)) return await run_promotion(argv)
+	const form = FLAGGED_FORMS.find(([is_form]) => is_form(argv))
+	const run_form = form === undefined ? run_creation : form[1]
 
-	return await run_creation(argv)
+	return await run_form(argv)
 }
 
 async function main(): Promise<void> {

package/scripts/exports/unused-members-check.ts

@@ -0,0 +1,62 @@
+import path from 'node:path'
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
+import type { NamespaceMember } from '#tools/exports/namespace-members'
+
+const CHECK = 'exports'
+const FAIL_EXIT_CODE = 1
+// A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
+// `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
+//
+// **Not a skip notice**. `SKIP_MARKER` means "a check passed without running",
+// and the gate withholds its green record on it — so a consumer, where this notice prints on every
+// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
+const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — ${NOTHING_TO_CHECK_MARKER} in a consumer project.`
+
+function format_member(root: string, member: NamespaceMember): string {
+	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
+}
+
+function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
+	if (members.length === 0) return `josh ${CHECK}: no unused namespace member`
+
+	return [
+		`josh ${CHECK}: ${String(members.length)} namespace member(s) nothing reads — remove each from its namespace object (and the declaration, if nothing in its file uses it either):`,
+		...members.map((member) => `  ${format_member(root, member)}`),
+	].join('\n')
+}
+
+// Loaded only past the consumer skip: the scanner pulls in `typescript`, an optional peer a
+// basic-profile consumer may not have, and this check runs in every consumer's gate. For the same
+// reason the scanner is left out of the published package (`package.json` `files`); only this check
+// ships. `files` narrows the scan to the namespaces they declare or import directly; undefined scans
+// the whole program.
+async function find_members(
+	root: string,
+	files: ReadonlyArray<string> | undefined,
+): Promise<ReadonlyArray<NamespaceMember>> {
+	const { unused_members } = await import('#tools/exports/unused-members')
+	if (files === undefined) return unused_members.find_unused_members(root)
+
+	return await unused_members.find_unused_members_in(root, files)
+}
+
+async function run_unused_members(root: string, files?: ReadonlyArray<string>): Promise<number> {
+	if (doctor_consumer.is_kit_consumer(root)) {
+		console.info(CONSUMER_NOTICE)
+
+		return 0
+	}
+
+	const members = await find_members(root, files)
+	const output = report(root, members)
+
+	if (members.length === 0) console.info(output)
+	else console.error(output)
+
+	return members.length === 0 ? 0 : FAIL_EXIT_CODE
+}
+
+const unused_members_check = { run_unused_members, CONSUMER_NOTICE }
+
+export { unused_members_check }