@joshuafolkken/kit 1.957.0 → 1.972.0

package/scripts/backlog/backlog-next.ts

@@ -2,11 +2,15 @@ import { fileURLToPath } from 'node:url'
 import { auto_ok_cli, type OptedInRead, type TrackingRead } from '#scripts/auto-ok/auto-ok-cli'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
+import { epic_busy } from '#scripts/epic/epic-busy'
+import type { EpicChild } from '#scripts/epic/epic-graph'
 import { epic_index } from '#scripts/epic/epic-index'
 import { epic_next } from '#scripts/epic/epic-next'
 import { epic_next_read, type EpicRead } from '#scripts/epic/epic-next-read'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_report, type EpicNextResult, type EpicVerdict } from '#scripts/epic/epic-report'
+import { epic_solo } from '#scripts/epic/epic-solo'
+import { epic_triage, type TriageVerdict } from '#scripts/epic/epic-triage'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
@@ -61,7 +65,10 @@ const RETRY_MESSAGE =
 // no failure path that could emit it, so widening the shared union would give every consumer of it a
 // member none of them can produce — and `VERDICT_LINES` a line nothing ever prints. The token is a
 // backlog-level answer about the transport, not a reading of one epic's graph.
-type BacklogVerdict = EpicVerdict | 'retry'
+//
+// `triage` is `epic:next`'s word as well as this command's (joshuafolkken/kit#2779), but it is decided
+// after the graph is read rather than from it, so it stays `epic_triage`'s type too.
+type BacklogVerdict = EpicVerdict | 'retry' | TriageVerdict
 
 const VERDICT_TOKENS: Readonly<Record<BacklogVerdict, string>> = {
 	complete: auto_ok_cli.NONE_TOKEN,
@@ -69,6 +76,7 @@ const VERDICT_TOKENS: Readonly<Record<BacklogVerdict, string>> = {
 	retry: 'retry',
 	run: 'run',
 	stop: 'stop',
+	triage: epic_triage.TRIAGE_VERDICT,
 	wait: 'wait',
 }
 
@@ -266,13 +274,47 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
+// The `run:solo` gate is applied here rather than in `resolve`, because `backlog:plan` shares
+// `resolve` and a plan made before the run lists everything (joshuafolkken/kit#2776). The holders are
+// read only on a `run` answer — the one answer the gate can change.
+async function gate_solo(result: EpicNextResult, repo: string): Promise<EpicNextResult> {
+	if (result.verdict !== 'run') return result
+
+	const gated = epic_solo.gate(result, await epic_busy.read_repository(repo), repo)
+
+	if (gated.notice !== undefined) console.error(gated.notice)
+
+	return gated.result
+}
+
+// An untriaged candidate withholds every candidate (joshuafolkken/kit#2779). Checked before the
+// `run:solo` gate, which cannot be applied to an issue whose label is not recorded yet; the numbers go
+// to standard error, the one token to standard output.
+function report_triage(context: PoolContext, untriaged: ReadonlyArray<EpicChild>): number {
+	warn_epic_gap(context)
+	console.error(epic_triage.message(untriaged, context.repo))
+	console.info(VERDICT_TOKENS.triage)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function untriaged_of(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
+	if (result.verdict !== 'run') return []
+
+	return epic_triage.untriaged(epic_report.candidates_for_repo(result, repo))
+}
+
 async function answer_pool(context: PoolContext): Promise<number> {
 	const result = await resolve(context)
 
 	if (result === undefined) return FAILURE_EXIT_CODE
 	if (is_transport_failure(result)) return report_retry(context)
 
-	return report(result, context)
+	const untriaged = untriaged_of(result, context.repo)
+
+	if (untriaged.length > 0) return report_triage(context, untriaged)
+
+	return report(await gate_solo(result, context.repo), context)
 }
 
 // A backlog nobody has opted into answers `none` before either listing below is asked for.
@@ -362,6 +404,7 @@ const backlog_next = {
 	resolve,
 	is_transport_failure,
 	report_retry,
+	report_triage,
 	context_of,
 	answer_pool,
 	report_none,

package/scripts/backlog/backlog-offer.ts

@@ -40,6 +40,7 @@ const VERDICT_ANSWERS: Readonly<Record<string, BacklogAnswer>> = {
 	[TOKENS.complete]: 'exhausted',
 	[TOKENS.error]: 'unreadable',
 	[TOKENS.stop]: 'parked',
+	[TOKENS.triage]: 'untriaged',
 }
 
 // `wait` is `blocked` while this run has children in flight and `exhausted` when it does not — the

package/scripts/backlog/backlog-plan-cli.ts

@@ -9,8 +9,9 @@ import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_named } from './backlog-named'
 import { backlog_next, type OptedIn } from './backlog-next'
-import { backlog_plan, type NamedPlan } from './backlog-plan'
+import { backlog_plan, type NamedPlan, type PlanContext } from './backlog-plan'
 import { backlog_scope } from './backlog-scope'
+import { backlog_waves } from './backlog-waves'
 
 // `josh backlog:plan` — the whole backlog as a plan a person reads before a run starts
 // (joshuafolkken/kit#1652).
@@ -36,9 +37,18 @@ const NAMED_COMMAND = 'backlogrun'
 // The flag that runs the named list and stops, mirrored here so the plan the person reads before the
 // run shows the same scope the run will take (joshuafolkken/kit#1984).
 const ONLY_FLAG = '--only'
+// The flag that renders the run's order wave by wave instead of the pool's sections
+// (joshuafolkken/kit#2778).
+const WAVES_FLAG = '--waves'
 
 const USAGE =
-	'Usage: josh backlog:plan [#<issue-number>...] [--only] [--exclude <issue-number>[,<issue-number>...]]...'
+	'Usage: josh backlog:plan [#<issue-number>...] [--only] [--waves] [--exclude <issue-number>[,<issue-number>...]]...'
+
+// The waves play the opted-in pool forward, and a named prefix runs ahead of it one issue at a time —
+// an epic among them running its children first — so waves drawn from the pool alone would promise an
+// order that invocation does not take.
+const WAVES_WITH_NAMED_MESSAGE =
+	'`--waves` plans the opted-in backlog alone; drop the named issues (and `--only`) to see its waves.'
 
 // The leading `#N` tokens are the named prefix a `backlogrun #N1 #N2 …` runs before the pool. They are
 // read through the invocation grammar so the plan and the run agree on what counts as a named issue.
@@ -56,10 +66,10 @@ function has_only_flag(argv: ReadonlyArray<string>): boolean {
 	return argv.includes(ONLY_FLAG)
 }
 
-// `--only` is stripped before the named block and the options are read, so it is never taken for a
-// positional or an unknown option; whether it was present is carried as a boolean instead.
-function without_only(argv: ReadonlyArray<string>): ReadonlyArray<string> {
-	return argv.filter((token) => token !== ONLY_FLAG)
+// `--only` and `--waves` are stripped before the named block and the options are read, so neither is
+// taken for a positional or an unknown option; whether each was present is carried as a boolean.
+function without_flags(argv: ReadonlyArray<string>): ReadonlyArray<string> {
+	return argv.filter((token) => token !== ONLY_FLAG && token !== WAVES_FLAG)
 }
 
 // The one start-time refusal: `--only` with no named issues has nothing to run. `backlog_named` is the
@@ -103,6 +113,12 @@ interface OpenListing {
 	is_capped: boolean
 }
 
+// Which rendering was asked for: the named prefix the sections lead with, or the waves.
+interface PlanView {
+	named: NamedPlan
+	is_waves: boolean
+}
+
 // The same reads and the same classification `backlog:next` makes, through the same two functions.
 // `undefined` is a failure it has already reported.
 async function classify(
@@ -138,26 +154,32 @@ async function fetch_open(): Promise<OpenListing | undefined> {
 	return read.kind === 'read' ? { rows: read.rows, is_capped } : undefined
 }
 
-function print_plan(
-	plan: Plan,
-	open_issues: ReadonlyArray<OpenIssueData>,
-	is_capped: boolean,
-	named: NamedPlan,
-): void {
-	const scope = { repo: plan.repo, exclude: plan.exclude, tracked: plan.tracked }
-	const rows = backlog_scope.out_of_scope(open_issues, plan.result, scope)
-	// A cut listing cannot say an issue is closed, only that it was not read — so the blocker filter is
-	// switched off rather than fed a set that would silently report standing blockers as gone.
-	const context = {
+// A cut listing cannot say an issue is closed, only that it was not read — so the blocker filter is
+// switched off rather than fed a set that would silently report standing blockers as gone.
+function context_of(plan: Plan, listing: OpenListing): PlanContext {
+	return {
 		repo: plan.repo,
-		titles: backlog_scope.titles_of(open_issues),
-		open_numbers: is_capped ? undefined : backlog_scope.open_numbers_of(open_issues),
+		titles: backlog_scope.titles_of(listing.rows),
+		open_numbers: listing.is_capped ? undefined : backlog_scope.open_numbers_of(listing.rows),
 	}
+}
+
+function print_plan(plan: Plan, listing: OpenListing, view: PlanView): void {
+	const context = context_of(plan, listing)
+
+	if (view.is_waves) {
+		console.info(backlog_waves.format_waves(plan.result, context))
 
-	console.info(backlog_plan.format_plan(plan.result, rows, context, named))
+		return
+	}
+
+	const scope = { repo: plan.repo, exclude: plan.exclude, tracked: plan.tracked }
+	const rows = backlog_scope.out_of_scope(listing.rows, plan.result, scope)
+
+	console.info(backlog_plan.format_plan(plan.result, rows, context, view.named))
 }
 
-async function report(plan: Plan, named: NamedPlan): Promise<number> {
+async function report(plan: Plan, view: PlanView): Promise<number> {
 	const listing = await fetch_open()
 
 	if (listing === undefined) {
@@ -167,12 +189,12 @@ async function report(plan: Plan, named: NamedPlan): Promise<number> {
 	}
 
 	if (listing.is_capped) console.error(OPEN_TRUNCATED_MESSAGE)
-	print_plan(plan, listing.rows, listing.is_capped, named)
+	print_plan(plan, listing, view)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function run_plan(rest: ReadonlyArray<string>, named: NamedPlan): Promise<number> {
+async function run_plan(rest: ReadonlyArray<string>, view: PlanView): Promise<number> {
 	const options = auto_ok_cli.parse_options(without_named(rest), USAGE)
 
 	if (options.usage !== undefined) {
@@ -191,17 +213,33 @@ async function run_plan(rest: ReadonlyArray<string>, named: NamedPlan): Promise<
 
 	const plan = await classify(opted_in, options.exclude ?? [])
 
-	return plan === undefined ? FAILURE_EXIT_CODE : await report(plan, named)
+	return plan === undefined ? FAILURE_EXIT_CODE : await report(plan, view)
+}
+
+// The start-time refusals, `--only`'s and `--waves`'s, in one place so `run` stays a straight line.
+//
+// The waves refusal reads the named block from the flag-stripped tokens, so `--waves #5` is refused
+// like `#5 --waves` rather than having its `#5` dropped by the option parser.
+function refusal_of(
+	named: ReadonlyArray<number>,
+	rest: ReadonlyArray<string>,
+	is_only: boolean,
+	is_waves: boolean,
+): string | undefined {
+	if (!is_waves) return only_refusal(named, is_only)
+
+	return is_only || named_of(rest).length > 0 ? WAVES_WITH_NAMED_MESSAGE : undefined
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const is_only = has_only_flag(argv)
-	const rest = without_only(argv)
+	const is_waves = argv.includes(WAVES_FLAG)
+	const rest = without_flags(argv)
 	// Read the named block from the *original* argv, so `--only` placed before the `#N` block breaks the
 	// leading block exactly as the run grammar does — the plan then refuses an ordering the run refuses,
 	// rather than promising a scope the resumed invocation would stop on (joshuafolkken/kit#1984).
 	const named = named_of(argv)
-	const refusal = only_refusal(named, is_only)
+	const refusal = refusal_of(named, rest, is_only, is_waves)
 
 	if (refusal !== undefined) {
 		console.error(refusal)
@@ -209,7 +247,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return await run_plan(rest, { issues: named, only: is_only })
+	return await run_plan(rest, { named: { issues: named, only: is_only }, is_waves })
 }
 
 // `process.exitCode` rather than `process.exit()`, the reason `backlog:next` records: the plan is
@@ -222,6 +260,7 @@ const backlog_plan_cli = {
 	OPEN_TRUNCATED_MESSAGE,
 	OPEN_UNREADABLE_MESSAGE,
 	USAGE,
+	WAVES_WITH_NAMED_MESSAGE,
 	classify,
 	fetch_open,
 	main,

package/scripts/backlog/backlog-plan.ts

@@ -1,7 +1,9 @@
 import type { EpicChild } from '#scripts/epic/epic-graph'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
+import { epic_solo } from '#scripts/epic/epic-solo'
+import { epic_triage } from '#scripts/epic/epic-triage'
 import type { IssueReference } from '#scripts/git/git-epic-reference'
-import { has_label_name, IN_PROGRESS_LABEL } from '#scripts/git/issue-labels'
+import { has_label_name, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
 import type { OutOfScopeRow } from './backlog-scope'
 
 // The plan a person reads before a `backlogrun` starts (joshuafolkken/kit#1652).
@@ -74,8 +76,28 @@ function join_row(reference: string, title: string, note: string): string {
 	return `${ROW_INDENT}${parts.join('  ')}`
 }
 
+// A `run:solo` child is marked beside its number, so a person reading the plan sees which issues
+// `backlog:next` will start alone before the run starts (joshuafolkken/kit#2776).
+const SOLO_MARK = `[${RUN_SOLO_LABEL}]`
+// A child with neither `run:solo` nor `run:lane` is one `backlog:next` withholds everything for until
+// it is judged (joshuafolkken/kit#2779), so the plan says which ones before the run asks.
+const UNTRIAGED_MARK = '[untriaged]'
+
+function mark_of(child: EpicChild): string | undefined {
+	if (epic_solo.is_solo(child)) return SOLO_MARK
+
+	return epic_triage.is_triaged(child) ? undefined : UNTRIAGED_MARK
+}
+
+function marked_reference(child: EpicChild, repo: string): string {
+	const reference = reference_of(child, repo)
+	const mark = mark_of(child)
+
+	return mark === undefined ? reference : `${reference} ${mark}`
+}
+
 function row_of(child: EpicChild, context: PlanContext, note: string): string {
-	return join_row(reference_of(child, context.repo), title_of(child, context), note)
+	return join_row(marked_reference(child, context.repo), title_of(child, context), note)
 }
 
 // Why this one is not offered yet. The blocker numbers are the answer whenever there are any — that
@@ -221,9 +243,15 @@ const backlog_plan = {
 	PAST_OFFER_NOTE,
 	READY_HEADING,
 	SCOPE_HEADING,
+	SOLO_MARK,
+	UNTRIAGED_MARK,
 	UNUSABLE_HEADING,
 	WAITING_HEADING,
 	format_plan,
+	format_unusable,
+	marked_reference,
+	row_of,
+	section,
 	waiting_note,
 }
 

package/scripts/backlog/backlog-stalled.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks
@@ -101,6 +102,13 @@ function count_ready_tokens(out: string): number {
 	return ready_tokens(out).length
 }
 
+// Whether `backlog:next` answered `triage` (joshuafolkken/kit#2779): no number is runnable, yet a session
+// has work — judging the untriaged issues — so a reader of the numeric lines alone would take it for an
+// empty pool.
+function needs_triage(out: string): boolean {
+	return out.split('\n').some((token) => token.trim() === epic_triage.TRIAGE_VERDICT)
+}
+
 const backlog_stalled = {
 	STALLED,
 	OK,
@@ -111,6 +119,7 @@ const backlog_stalled = {
 	describe,
 	dispatch_age_ms,
 	is_stalled,
+	needs_triage,
 	ready_tokens,
 }
 

package/scripts/backlog/backlog-waves.ts

@@ -0,0 +1,169 @@
+import type { BusyRead } from '#scripts/epic/epic-busy'
+import { epic_classify } from '#scripts/epic/epic-classify'
+import { epic_cross_repo } from '#scripts/epic/epic-cross-repo'
+import { epic_graph, type EpicChild } from '#scripts/epic/epic-graph'
+import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
+import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
+import { epic_solo } from '#scripts/epic/epic-solo'
+import { has_label_name, IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { backlog_plan, type PlanContext } from './backlog-plan'
+
+// The order a `backlogrun` takes, wave by wave, before it starts (joshuafolkken/kit#2778).
+//
+// `backlog:next` answers one ask — what may start now — and `backlog:plan` shows the pool that ask is
+// made from, so the order past the first answer was left for a person to work out by hand. This plays
+// the asks forward under one assumption: **every issue of a wave merges before the next wave starts**.
+//
+// **No rule is written twice.** The first wave is `epic_solo.select` over the very candidates
+// `backlog:next` resolves, asked of an idle repository — so it is what `backlog:next` prints when
+// nothing is running. Each later wave marks the earlier waves closed and re-classifies the same pool
+// through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
+// time — `epic_cross_repo.resolve_cross_repo`, so a blocker in another repository still waits for its
+// release rather than counting as done on close — then puts the runnable set through
+// `epic_solo.select` again.
+
+const IDLE: BusyRead = { kind: 'idle' }
+const CLOSED = 'CLOSED'
+
+const HEADING_ASSUMPTION =
+	'Assumes every issue in a wave merges before the next wave starts. Issues a run already has are left out, and only issues of this repository are planned.'
+const UNREACHED_HEADING = 'Not reached — each names what it is waiting on:'
+const PARALLEL_NOTE = '(parallel)'
+const NEEDS_DECISION_NOTE = `waiting on a person (\`${NEEDS_DECISION_LABEL}\`)`
+const NOT_REACHED_NOTE = 'not reached by the waves above'
+const WAVE_GAP_WIDTH = 2
+const PARALLEL_GAP_WIDTH = 3
+const WAVE_GAP = ' '.repeat(WAVE_GAP_WIDTH)
+const PARALLEL_GAP = ' '.repeat(PARALLEL_GAP_WIDTH)
+
+interface WavePlan {
+	waves: ReadonlyArray<ReadonlyArray<EpicChild>>
+	unreached: ReadonlyArray<EpicChild>
+}
+
+function is_running(child: EpicChild): boolean {
+	return has_label_name(child.labels, IN_PROGRESS_LABEL)
+}
+
+// Every child the classification placed, in the order it placed them: the ranked candidates first,
+// then the waiting ones, then the ones waiting on a person.
+function everything_in(result: EpicNextResult): ReadonlyArray<EpicChild> {
+	const candidates = result.candidates.flatMap((bundle) => bundle.children)
+
+	return [...candidates, ...result.waiting, ...result.blocked_on_people]
+}
+
+function as_closed(child: EpicChild, done: ReadonlySet<string>): EpicChild {
+	return done.has(epic_graph.key_of(child)) ? { ...child, state: CLOSED } : child
+}
+
+// The pool a wave is chosen from. A running issue is left out of it but kept in `running`, so a child
+// behind it waits on it rather than being handed to a person.
+interface WavePool {
+	children: ReadonlyArray<EpicChild>
+	running: ReadonlySet<string>
+	repo: string
+}
+
+function pool_of(result: EpicNextResult, repo: string): WavePool {
+	const all = everything_in(result)
+
+	return {
+		children: all.filter((child) => !is_running(child)),
+		running: epic_outside_blocker.running_keys(all),
+		repo,
+	}
+}
+
+function offer(runnable: ReadonlyArray<EpicChild>, repo: string): ReadonlyArray<EpicChild> {
+	return epic_solo.select(runnable, IDLE, repo).offered
+}
+
+function first_wave(result: EpicNextResult, repo: string): ReadonlyArray<EpicChild> {
+	return offer(epic_report.candidates_for_repo(result, repo), repo)
+}
+
+function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<EpicChild> {
+	const children = pool.children.map((child) => as_closed(child, done))
+	const { runnable } = epic_classify.classify_children(
+		children,
+		epic_cross_repo.resolve_cross_repo,
+		pool.running,
+	)
+
+	return offer(
+		runnable.filter((child) => child.repo === pool.repo),
+		pool.repo,
+	)
+}
+
+// Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
+// the pool's size bounds because every wave closes at least one child.
+function build(result: EpicNextResult, repo: string): WavePlan {
+	const pool = pool_of(result, repo)
+	const done = new Set<string>()
+	const waves: Array<ReadonlyArray<EpicChild>> = []
+
+	for (let wave = first_wave(result, repo); wave.length > 0; wave = next_wave(pool, done)) {
+		waves.push(wave)
+		for (const child of wave) done.add(epic_graph.key_of(child))
+	}
+
+	const unreached = everything_in(result).filter(
+		(child) => child.repo === repo && !done.has(epic_graph.key_of(child)),
+	)
+
+	return { waves, unreached }
+}
+
+// The plan's own "waiting on" wording is reused, so an unreached issue names its blocker the way the
+// plan's waiting section does. Its "past the offer" fallback means nothing across waves, so it reads
+// as not reached instead.
+function unreached_note(child: EpicChild, context: PlanContext): string {
+	if (has_label_name(child.labels, NEEDS_DECISION_LABEL)) return NEEDS_DECISION_NOTE
+	const note = backlog_plan.waiting_note(child, context)
+
+	return note === backlog_plan.PAST_OFFER_NOTE ? NOT_REACHED_NOTE : note
+}
+
+function wave_line(wave: ReadonlyArray<EpicChild>, index: number, repo: string): string {
+	const references = wave.map((child) => backlog_plan.marked_reference(child, repo)).join(' ')
+	const suffix = wave.length > 1 ? `${PARALLEL_GAP}${PARALLEL_NOTE}` : ''
+
+	return `Wave ${String(index + 1)}${WAVE_GAP}${references}${suffix}`
+}
+
+function unreached_lines(plan: WavePlan, context: PlanContext): Array<string> {
+	return plan.unreached.map((child) =>
+		backlog_plan.row_of(child, context, unreached_note(child, context)),
+	)
+}
+
+function format_waves(result: EpicNextResult, context: PlanContext): string {
+	if (result.verdict === 'error') return backlog_plan.format_unusable(result)
+
+	const plan = build(result, context.repo)
+	const waves = plan.waves.map((wave, index) => wave_line(wave, index, context.repo))
+
+	return [
+		`Backlog waves — ${context.repo}`,
+		HEADING_ASSUMPTION,
+		'',
+		...(waves.length === 0 ? [backlog_plan.NOTHING] : waves),
+		'',
+		backlog_plan.section(UNREACHED_HEADING, unreached_lines(plan, context)),
+	].join('\n')
+}
+
+const backlog_waves = {
+	HEADING_ASSUMPTION,
+	NEEDS_DECISION_NOTE,
+	NOT_REACHED_NOTE,
+	PARALLEL_NOTE,
+	UNREACHED_HEADING,
+	build,
+	format_waves,
+}
+
+export { backlog_waves }
+export type { WavePlan }

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

@@ -82,7 +82,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/rule-residency.md', bytes: 24_576 },
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 8192 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
-	{ path: 'docs/josh-commands.md', bytes: 167_936 },
+	{ path: 'docs/josh-commands.md', bytes: 172_032 },
 	{ path: 'prompts/agent-rules.md', bytes: 4096 },
 	{ path: 'prompts/coding-standards.md', bytes: 16_384 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

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

@@ -76,11 +76,13 @@ const ENTRY_READ_BUDGET: ReadonlyArray<EntryBudget> = [
 	// joshuafolkken/kit#2353 wired the watcher-guard note into `backlogrun-progress.md` (read by the three
 	// planning entries): kickoff has no headroom, so the addition was offset by tightening that file's
 	// heartbeat prose, keeping every entry within its existing block.
-	{ entry: 'kickoff', bytes: 258_048 },
-	{ entry: 'fullrun', bytes: 258_048 },
-	{ entry: 'halfrun', bytes: 258_048 },
-	{ entry: 'backlogrun', bytes: 262_144 },
-	{ entry: LANE_CHILD, bytes: 86_016 },
+	// joshuafolkken/kit#2762 moved the rationale of five point-of-use documents to
+	// `docs/maintainers/*-rationale.md`, and the ratchet holds the reduction.
+	{ entry: 'kickoff', bytes: 229_376 },
+	{ entry: 'fullrun', bytes: 229_376 },
+	{ entry: 'halfrun', bytes: 229_376 },
+	{ entry: 'backlogrun', bytes: 233_472 },
+	{ entry: LANE_CHILD, bytes: 81_920 },
 ]
 
 function byte_size(root: string, relative_path: string): number {

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

@@ -7,6 +7,8 @@ import {
 } from './epic-candidate-confirm'
 import { epic_graph, type EpicChild } from './epic-graph'
 import type { EpicVerdict } from './epic-report'
+import { epic_solo } from './epic-solo'
+import { epic_triage, type TriageVerdict } from './epic-triage'
 
 // Which children a repository has room to start right now (joshuafolkken/kit#1491).
 //
@@ -50,7 +52,7 @@ interface LaneRequest {
 // output carries issue numbers or a verdict and nothing else.
 interface LaneOffer {
 	children: ReadonlyArray<EpicChild>
-	verdict: EpicVerdict
+	verdict: EpicVerdict | TriageVerdict
 	notice: string
 }
 
@@ -165,14 +167,75 @@ async function collect(
 	return { children, verdict: children.length > NO_LANES ? RUN_VERDICT : verdict }
 }
 
+// The `run:solo` gate `backlog:next` applies, applied to a named epic's lanes too
+// (joshuafolkken/kit#2776): the confirmed children are cut where `epic_solo.select` says, so a
+// `run:solo` child never opens a lane beside another one on either path.
+function solo_offer(
+	answer: { children: ReadonlyArray<EpicChild>; verdict: EpicVerdict },
+	read: BusyRead,
+	request: LaneRequest,
+): LaneOffer {
+	const { offered, notice } = epic_solo.select(answer.children, read, request.repo)
+
+	if (offered.length === NO_LANES && answer.children.length > NO_LANES) {
+		return { children: [], verdict: WAIT_VERDICT, notice: notice ?? '' }
+	}
+
+	return { ...answer, children: offered, notice: offered_notice(offered, read, request) }
+}
+
+// The confirmation walk stops at the free-lane count, so a `run:solo` candidate ranked past it — or
+// in a pool past it — would never reach `solo_offer` to be preferred. Into an idle repository the
+// first pool holding one is asked first, with it at its head through the same `epic_solo.prefer` the
+// offer applies (joshuafolkken/kit#2778). The candidate stays in its own pool, because a pool carries
+// the graph it is confirmed against.
+function solo_first(pools: ReadonlyArray<RepoPool>, read: BusyRead): ReadonlyArray<RepoPool> {
+	if (read.kind !== 'idle') return pools
+
+	const index = pools.findIndex((pool) => pool.candidates.some((child) => epic_solo.is_solo(child)))
+	const pool = pools[index]
+
+	if (pool === undefined) return pools
+
+	const lifted = { ...pool, candidates: epic_solo.prefer(pool.candidates, read) }
+
+	return [lifted, ...pools.filter((other) => other !== pool)]
+}
+
 // The repository is asked how full it is **before** any candidate is confirmed, for the reason
 // joshuafolkken/kit#1121 records: a repository with no free lane is handed nothing, so the relations
 // request that would confirm a candidate there buys an answer nobody reads — and a polling `epicrun`
 // would pay it every round.
+//
+// **Triage is asked before even that** (joshuafolkken/kit#2779): an untriaged candidate withholds every
+// candidate whatever the occupancy, and it needs only the labels already read. Only a `--lanes` ask
+// is gated — it is the one that opens children beside each other; the single-child form starts one.
+function triage_offer(pools: ReadonlyArray<RepoPool>, request: LaneRequest): LaneOffer | undefined {
+	if (!request.is_all_lanes) return undefined
+
+	const untriaged = epic_triage.untriaged(
+		dedupe_pools(pools.map((pool) => candidates_in(pool, request.repo))).flatMap(
+			(pool) => pool.candidates,
+		),
+	)
+
+	if (untriaged.length === NO_LANES) return undefined
+
+	return {
+		children: [],
+		verdict: epic_triage.TRIAGE_VERDICT,
+		notice: epic_triage.message(untriaged, request.repo),
+	}
+}
+
 async function offer_for_repo(
 	pools: ReadonlyArray<RepoPool>,
 	request: LaneRequest,
 ): Promise<LaneOffer> {
+	const triage = triage_offer(pools, request)
+
+	if (triage !== undefined) return triage
+
 	const read = await epic_busy.read_repository(request.repo)
 	const free = free_lanes(read, request.limit)
 
@@ -184,10 +247,12 @@ async function offer_for_repo(
 		}
 	}
 
-	const for_repo = dedupe_pools(pools.map((pool) => candidates_in(pool, request.repo)))
-	const answer = await collect(for_repo, wanted_of(request, free))
+	const for_repo = solo_first(
+		dedupe_pools(pools.map((pool) => candidates_in(pool, request.repo))),
+		read,
+	)
 
-	return { ...answer, notice: offered_notice(answer.children, read, request) }
+	return solo_offer(await collect(for_repo, wanted_of(request, free)), read, request)
 }
 
 const epic_lane_offer = {