@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/backlog/backlog-drive-launch.ts

@@ -0,0 +1,39 @@
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
+import { backlog_drive_owner } from './backlog-drive-owner'
+
+// The driver's lane launch (joshuafolkken/kit#3272). The parent that ran `josh latest` in the primary
+// checkout leaves its rewritten lock file in a stash under this message — `backlogrun-lanes.md` →
+// "Once per repository, before the first lane opens" — and the lane that pops it carries the update
+// into its pull request. **The stash itself is the "first lane" marker**: each launch asks whether it
+// is still on the stack, and the pop that `lane:launch --stash` runs consumes it, so the first launch
+// after the push takes it and every later one finds nothing. A restarted driver needs no memory of
+// which lane was first. Two entries under the message are a state a person resolves, so neither is
+// guessed at — the launch goes ahead without one, as `stash:pop` would refuse it anyway. That skip is
+// said on stderr, because `stash:pop` refusing would have been heard and a silent skip would let the
+// update never reach a pull request.
+const LATEST_STASH_MESSAGE = 'backlogrun: josh latest before lanes'
+
+async function latest_stash(): Promise<string | undefined> {
+	const selection = git_stash.select(await git_stash.list(), LATEST_STASH_MESSAGE)
+
+	if (selection.kind === 'ambiguous') {
+		console.error(
+			`Launching without the "${LATEST_STASH_MESSAGE}" stash: ${selection.selectors.join(', ')} all match — keep one.`,
+		)
+	}
+
+	return selection.kind === 'match' ? LATEST_STASH_MESSAGE : undefined
+}
+
+async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
+	await backlog_drive_owner.assert_current(owner)
+
+	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
+
+	return outcome.kind
+}
+
+const backlog_drive_launch = { LATEST_STASH_MESSAGE, launch }
+
+export { backlog_drive_launch }

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -1,8 +1,8 @@
 import { EPIC_LABEL, has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import type { IssueState } from '#scripts/issue/issue-state'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
-import type { RunCarry } from '#scripts/run/run-carry'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_named } from './backlog-drive-named'
@@ -58,9 +58,7 @@ function settled_outcome(state: IssueState): MergeResult['outcome'] | undefined
 async function classify(issue: string, named: OfferRead, owner: string): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
-	if (result.kind !== 'state') {
-		return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
-	}
+	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
 
 	const outcome = settled_outcome(result.state)
 

package/scripts/backlog/backlog-drive-named.ts

@@ -1,8 +1,8 @@
 import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
-import type { RunEvent } from '#scripts/run/run-event-stream'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_restore } from './backlog-drive-restore'
 import { backlog_named } from './backlog-named'

package/scripts/backlog/backlog-drive-offer-argv.ts

@@ -1,4 +1,4 @@
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import type { DriveState } from './backlog-drive'
 
 const LIST_SEPARATOR = ','

package/scripts/backlog/backlog-drive-owner.ts

@@ -1,4 +1,4 @@
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 
 function owns_record(carry: RunCarry, owner: string): boolean {
 	const current = run_carry.owner_of(Number(owner))

package/scripts/backlog/backlog-drive-restore.ts

@@ -1,4 +1,4 @@
-import { run_event_stream, type RunEvent } from '#scripts/run/run-event-stream'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 const ISSUE_IN_EVENT = /#([1-9]\d*)\b/u
 const SETTLED_KINDS: ReadonlySet<string> = new Set([

package/scripts/backlog/backlog-drive-retrospective.ts

@@ -1,6 +1,6 @@
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { find_package_directory } from '#scripts/josh/josh-logic'
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_retrospective } from '#scripts/run/run-retrospective'
 
 // Whether a drain owes the retrospective, read through the owed rule `run:step` reads, so a drain it

package/scripts/backlog/backlog-drive.ts

@@ -17,7 +17,7 @@
 // without a process, a network or a clock.
 
 import type { LaunchOutcome } from '#scripts/lane/lane-launch-cli'
-import type { MergeResult } from '#scripts/run/run-merge-cli'
+import type { MergeResult } from '#scripts/run/merge/run-merge-cli'
 
 const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'

package/scripts/backlog/backlog-next.ts

@@ -16,7 +16,8 @@ import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { backlog_defect_priority } from './backlog-defect-priority'
 import { backlog_pool } from './backlog-pool'
-import { backlog_rank } from './backlog-rank'
+import { backlog_rank, type GateScope } from './backlog-rank'
+import { backlog_restructure } from './backlog-restructure'
 
 // `josh backlog:next` — what the whole opted-in backlog may run next (joshuafolkken/kit#1630).
 //
@@ -145,6 +146,19 @@ function report(result: EpicNextResult, context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
+// The settled set the views were classified against, so a standalone row and an epic child weigh the
+// same blocker the same way.
+function running_of(
+	views: ReadonlyArray<EpicView>,
+	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
+	context: PoolContext,
+): ReadonlySet<string> {
+	return (
+		views[0]?.running ??
+		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo, context.tracking.index)
+	)
+}
+
 // The two halves as one result. The epic half is already classified by `epic:next`; the standalone
 // half is classified here; the verdict is decided from the merge, so a backlog with a runnable epic
 // child and nothing else says `run` exactly as one with a runnable standalone issue does.
@@ -160,10 +174,7 @@ function combine(views: ReadonlyArray<EpicView>, context: PoolContext): EpicNext
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
 		exclude: context.exclude,
 		repo: context.repo,
-		// The settled set the views were classified against, so a standalone row and an epic child weigh
-		// the same blocker the same way.
-		running:
-			views[0]?.running ?? backlog_pool.running_set(graphs, context.opted_in.issues, context.repo),
+		running: running_of(views, graphs, context),
 	})
 
 	// The same checkout map `epic:next` hands `build_result`. Without it every bundle heading reads
@@ -193,6 +204,7 @@ function settled_views(
 		views[0]?.running ?? running,
 		context.opted_in.issues,
 		context.repo,
+		context.tracking.index,
 	)
 
 	return settled.size === running.size ? views : settled_views(reads, settled, context)
@@ -211,7 +223,7 @@ function views_from(reads: ReadonlyArray<EpicRead>, context: PoolContext): Reado
 
 	return settled_views(
 		reads,
-		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo),
+		backlog_pool.running_set(graphs, context.opted_in.issues, context.repo, context.tracking.index),
 		context,
 	)
 }
@@ -278,7 +290,7 @@ function report_retry(context: PoolContext): number {
 	return SUCCESS_EXIT_CODE
 }
 
-// The rows the offer's cap bounds — the standalone half, which `backlog:plan --waves` reads too.
+// The rows the offer's cap bounds — the standalone half.
 function standalone_keys(context: PoolContext): ReadonlySet<string> {
 	return backlog_pool.standalone_keys(context.opted_in.issues, {
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
@@ -287,6 +299,16 @@ function standalone_keys(context: PoolContext): ReadonlySet<string> {
 	})
 }
 
+// The running lanes still carry the pickup label, so the opted-in listing holds their bodies too —
+// which is what lets a candidate be held back from a restructure a running lane already makes
+// (joshuafolkken/kit#3221). `backlog:plan --waves` reads the same scope, so its first wave is this offer.
+function gate_scope(context: PoolContext): GateScope {
+	return {
+		standalone: standalone_keys(context),
+		declared: backlog_restructure.declared_of(context.opted_in.issues),
+	}
+}
+
 // 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. The cap follows the gate
@@ -302,7 +324,7 @@ async function gate_solo(result: EpicNextResult, context: PoolContext): Promise<
 
 	if (notice !== undefined) console.error(notice)
 
-	const gated = backlog_rank.gate(result, read, repo, standalone_keys(context))
+	const gated = backlog_rank.gate(result, read, repo, gate_scope(context))
 
 	if (gated.notice !== undefined) console.error(gated.notice)
 
@@ -418,7 +440,7 @@ const backlog_next = {
 	READ_FAILURES,
 	VERDICT_TOKENS,
 	resolve,
-	standalone_keys,
+	gate_scope,
 	context_of,
 	run,
 }

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

@@ -3,8 +3,8 @@ import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { rule_value_cache } from '#scripts/rules/rule-value-cache'
-import { run_event_stream } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { z } from 'zod'
 import { backlog_offer, type OfferAnswer } from './backlog-offer'
 
@@ -74,8 +74,8 @@ function to_count(raw: string | undefined): number | undefined {
 
 // A count flag that was given but unreadable makes the invocation unreadable rather than defaulted —
 // the contract `backlog:budget` follows for its own counts.
-function count_of(raw: string | undefined, fallback: number): number | undefined {
-	return raw === undefined ? fallback : to_count(raw)
+function count_of(raw: string | undefined): number | undefined {
+	return raw === undefined ? DEFAULT_COUNT : to_count(raw)
 }
 
 interface OfferCounts {
@@ -86,8 +86,8 @@ interface OfferCounts {
 // The two counts the mapping needs: `--running` decides `wait`, `--retries` decides `retry`. Either
 // given but unreadable refuses the whole invocation.
 function counts_of(values: ParsedValues): OfferCounts | undefined {
-	const running = count_of(cli_flags.string_of(values.running), DEFAULT_COUNT)
-	const retries = count_of(cli_flags.string_of(values.retries), DEFAULT_COUNT)
+	const running = count_of(cli_flags.string_of(values.running))
+	const retries = count_of(cli_flags.string_of(values.retries))
 
 	if (running === undefined || retries === undefined) return undefined
 

package/scripts/backlog/backlog-offer.ts

@@ -5,7 +5,7 @@ import { backlog_next } from './backlog-next'
 // answered — its stdout tokens and its exit code — into the one word `backlog:budget` is then asked
 // with, plus the issue numbers to start and the consecutive-retry count carried to the next ask.
 //
-// **The mapping is `docs/josh-commands-automation.md` → "`josh backlog:offer`", held here so it cannot
+// **The mapping is `docs/josh-commands-backlog.md` → "`josh backlog:offer`", held here so it cannot
 // drift.** It fixes which `backlog:next` answer becomes which `backlog:budget` word, and it carries two
 // context branches an agent once applied by hand every iteration: `wait` is `blocked` while this run
 // has children in flight and `exhausted` when it has none, and `retry` is `blocked` until the third

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

@@ -4,12 +4,13 @@ import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
 import { epic_index } from '#scripts/epic/epic-index'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { 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, type PlanContext } from './backlog-plan'
+import type { GateScope } from './backlog-rank'
 import { backlog_scope } from './backlog-scope'
 import { backlog_waves } from './backlog-waves'
 
@@ -104,9 +105,9 @@ interface Plan {
 	// past the listing cap. Carrying the *whole* index here instead would move that misreport rather
 	// than remove it: the sentence would name an epic that is withholding nothing.
 	tracked: ReadonlyMap<number, number>
-	// The rows the offer's cap bounds, so `--waves` cuts each wave where `backlog:next` does
-	// (joshuafolkken/kit#2928).
-	standalone: ReadonlySet<string>
+	// The rows the offer's cap bounds and the paths each issue restructures, so `--waves` cuts each
+	// wave where `backlog:next` does (joshuafolkken/kit#2928, joshuafolkken/kit#3221).
+	scope: GateScope
 }
 
 // The listing plus whether it was cut. Carried together because the rows alone cannot say whether
@@ -141,7 +142,7 @@ async function classify(
 		repo: context.repo,
 		exclude,
 		tracked: epic_index.withheld_children(context.tracking.index, context.opted_in.issues),
-		standalone: backlog_next.standalone_keys(context),
+		scope: backlog_next.gate_scope(context),
 	}
 }
 
@@ -172,7 +173,7 @@ 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, plan.standalone))
+		console.info(backlog_waves.format_waves(plan.result, context, plan.scope))
 
 		return
 	}

package/scripts/backlog/backlog-pool.ts

@@ -5,7 +5,7 @@ import { epic_index } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
 import type { EpicView } from '#scripts/epic/epic-next-views'
 import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import {
 	ALREADY_DONE_LABEL,
@@ -37,6 +37,9 @@ const DECISION_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALRE
 // `tracked` is the narrowed set `epic_index.withheld_children` builds, not every child an epic
 // tracks (joshuafolkken/kit#1668) — the narrowing itself is defined there, once, for this half and
 // `auto-ok:next` alike.
+// Child number to every open epic whose task list names it — `epic_index.build_tracking_index`.
+type TrackingIndex = ReadonlyMap<number, ReadonlyArray<number>>
+
 // The part of the context that decides which rows the standalone half considers at all.
 type ConsideredContext = Pick<StandaloneContext, 'tracked' | 'exclude' | 'repo'>
 
@@ -69,24 +72,64 @@ function needs_person(issue: OpenIssueData, context: StandaloneContext): boolean
 	)
 }
 
+// Each open epic's key, read off the tracking index — child number to the epics listing it.
+function epic_keys_of(tracking: TrackingIndex, repo: string): ReadonlySet<string> {
+	return new Set([...tracking.values()].flat().map((number) => epic_graph.key_of({ repo, number })))
+}
+
+// The set with every epic that tracks a member added, nested epics included (joshuafolkken/kit#3289).
+// An epic is a container rather than work, so it is never run itself — but it closes once its children
+// do, so a row blocked by it waits on time exactly when one of those children is in this run.
+function with_tracking_epics(
+	running: ReadonlySet<string>,
+	tracking: TrackingIndex,
+	repo: string,
+): ReadonlySet<string> {
+	const tracking_epics = [...tracking]
+		.filter(([child]) => running.has(epic_graph.key_of({ repo, number: child })))
+		.flatMap(([, epics]) => epics.map((number) => epic_graph.key_of({ repo, number })))
+	const grown = new Set([...running, ...tracking_epics])
+
+	return grown.size === running.size ? running : with_tracking_epics(grown, tracking, repo)
+}
+
+// The epics re-derived from the members alone, so an epic whose last running child was just taken out
+// leaves with it rather than lingering from an earlier pass.
+function rooted(
+	running: ReadonlySet<string>,
+	tracking: TrackingIndex,
+	repo: string,
+): ReadonlySet<string> {
+	const epics = epic_keys_of(tracking, repo)
+	const members = new Set([...running].filter((key) => !epics.has(key)))
+
+	return with_tracking_epics(members, tracking, repo)
+}
+
+function is_stuck(issue: OpenIssueData, running: ReadonlySet<string>, repo: string): boolean {
+	return has_any_label(issue.labels, DECISION_LABELS) || waits_outside(issue, running, repo)
+}
+
 // The running set with every standalone row a person has to resolve taken out, repeated until a pass
 // removes nothing — a row waiting on such a row waits on that person too, however long the chain.
 function settle_standalone(
 	running: ReadonlySet<string>,
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
+	tracking: TrackingIndex,
 ): ReadonlySet<string> {
 	const settled = new Set(running)
 
-	// An epic row is never in the set, so deleting its key changes nothing and it needs no filter.
+	// An epic row is never a standalone row, so deleting its key here never happens; `rooted` decides it.
 	for (const issue of issues) {
-		const is_stuck =
-			has_any_label(issue.labels, DECISION_LABELS) || waits_outside(issue, running, repo)
-
-		if (is_stuck) settled.delete(epic_graph.key_of({ repo, number: issue.number }))
+		if (is_stuck(issue, running, repo)) {
+			settled.delete(epic_graph.key_of({ repo, number: issue.number }))
+		}
 	}
 
-	return settled.size === running.size ? running : settle_standalone(settled, issues, repo)
+	const next = rooted(settled, tracking, repo)
+
+	return next.size === running.size ? next : settle_standalone(next, issues, repo, tracking)
 }
 
 // An opted-in row as the graph's node type. Both halves of the pool are then the same shape, so one
@@ -182,18 +225,21 @@ function classify_standalone(
 // (joshuafolkken/kit#1943). A child is opted in through its epic's `auto-ok` even where it carries none
 // of its own, which is why the set is built from the graphs that were read rather than from labels. A
 // standalone row a person has to resolve is left out, so a row waiting on it waits for that person too;
-// an epic child in the same state is taken out by `epic_next_views.settle_views`.
+// an epic child in the same state is taken out by `epic_next_views.settle_views`. An open epic with a
+// child in the set is in it too, so a row blocked by that epic waits rather than needs a person. A
+// closed child is left out: it runs nothing, and kept in the set it would hold its epic there.
 function running_set(
 	graphs: ReadonlyArray<ReadonlyArray<EpicChild>>,
 	issues: ReadonlyArray<OpenIssueData>,
 	repo: string,
+	tracking: TrackingIndex,
 ): ReadonlySet<string> {
 	const running = epic_outside_blocker.running_keys([
-		...graphs.flat(),
+		...graphs.flat().filter((child) => child.state === 'OPEN'),
 		...to_children(standalone_rows(issues), repo),
 	])
 
-	return settle_standalone(running, issues, repo)
+	return settle_standalone(rooted(running, tracking, repo), issues, repo, tracking)
 }
 
 // A cycle no single epic can see, because its links cross from one graph into another. Each epic's own
@@ -336,4 +382,4 @@ const backlog_pool = {
 }
 
 export { backlog_pool }
-export type { ConsideredContext, StandaloneContext }
+export type { ConsideredContext, StandaloneContext, TrackingIndex }

package/scripts/backlog/backlog-rank.ts

@@ -4,6 +4,7 @@ import { epic_rank } from '#scripts/epic/epic-rank'
 import type { EpicNextResult } from '#scripts/epic/epic-report'
 import { epic_solo, type SoloGate, type SoloSelection } from '#scripts/epic/epic-solo'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
+import { backlog_restructure, type Declared } from './backlog-restructure'
 
 // What the backlog offers, in the order it is decided (joshuafolkken/kit#2928): rank, then the
 // `run:solo` gate, then the cap. `backlog:next` and `backlog:plan --waves` both call `select`, so the
@@ -78,29 +79,37 @@ interface OfferInput {
 	repo: string
 	// The keys of the standalone rows — the ones the cap bounds.
 	standalone: ReadonlySet<string>
+	// The paths each issue restructures; two candidates claiming one are not offered together
+	// (joshuafolkken/kit#3221). Absent, nothing is separated.
+	declared?: Declared
 }
 
+// The restructure separation runs before the cap, for the reason the gate does: the cap only ever
+// removes what would otherwise be offered.
 function select(input: OfferInput): SoloSelection {
 	const ranked = rank(input.candidates, input.pool)
+	const { read, repo } = input
+	const gated = epic_solo.select(ranked, read, repo)
+	const separated = backlog_restructure.separate(gated, input.declared ?? new Map(), { read, repo })
 
-	return cap(epic_solo.select(ranked, input.read, input.repo), input.standalone)
+	return cap(separated, input.standalone)
+}
+
+interface GateScope {
+	standalone: ReadonlySet<string>
+	declared: Declared
 }
 
 // `backlog:next`'s gate: `epic_solo.gate` with this selection in place of its bare one.
-function gate(
-	result: EpicNextResult,
-	read: BusyRead,
-	repo: string,
-	standalone: ReadonlySet<string>,
-): SoloGate {
+function gate(result: EpicNextResult, read: BusyRead, repo: string, scope: GateScope): SoloGate {
 	const pool = everything_in(result)
 
 	return epic_solo.gate(result, read, repo, (candidates) =>
-		select({ candidates, pool, read, repo, standalone }),
+		select({ candidates, pool, read, repo, ...scope }),
 	)
 }
 
 const backlog_rank = { everything_in, gate, rank_result, select }
 
 export { backlog_rank }
-export type { OfferInput }
+export type { GateScope, OfferInput }

package/scripts/backlog/backlog-ready.ts

@@ -3,7 +3,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
 import { lane_registry } from '#scripts/lane/lane-registry'
-import type { RunCarry } from '#scripts/run/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_invocation } from '#scripts/run/run-invocation'
 import { backlog_stalled } from './backlog-stalled'

package/scripts/backlog/backlog-restructure.ts

@@ -0,0 +1,152 @@
+import type { BusyRead } from '#scripts/epic/epic-busy'
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import type { SoloSelection } from '#scripts/epic/epic-solo'
+
+// Which candidates may not run side by side because both restructure the same file
+// (joshuafolkken/kit#3221). The condition is deliberately narrow: plain overlap is not serialized,
+// because every resume record of the 2026-10-05 backlog run was resolved mechanically by merging
+// main. What git cannot resolve on its own is a rename or modify/delete conflict — two lanes that
+// each move, split, rename or delete the same file — so only a path both bodies name on a line with
+// such a verb holds the second one back. `remove` is left out: issue bodies use it for lines and
+// options far more often than for files.
+const RESTRUCTURE_WORDS: ReadonlySet<string> = new Set([
+	'move',
+	'moved',
+	'moves',
+	'moving',
+	'rename',
+	'renamed',
+	'renames',
+	'renaming',
+	'split',
+	'splits',
+	'splitting',
+	'delete',
+	'deleted',
+	'deletes',
+	'deleting',
+])
+const RESTRUCTURE_PHRASES: ReadonlyArray<string> = ['移動', '分割', '削除', 'リネーム', '改名']
+const WORD = /[a-z]+/giu
+const CODE_SPAN = /`([^`\s]+)`/gu
+const LINE_SUFFIX = /:\d+(?::\d+)?$/u
+const FILE_EXTENSION = /\.[a-z]\w*$/iu
+
+// The restructured paths each issue declares, by issue number.
+type Declared = ReadonlyMap<number, ReadonlySet<string>>
+
+interface DeclaringIssue {
+	number: number
+	body?: string | undefined
+}
+
+function is_path(token: string): boolean {
+	return token.includes('/') || FILE_EXTENSION.test(token)
+}
+
+function paths_on(line: string): Array<string> {
+	return [...line.matchAll(CODE_SPAN)]
+		.map((match) => (match[1] ?? '').replace(LINE_SUFFIX, ''))
+		.filter((token) => is_path(token))
+}
+
+function is_restructuring(line: string): boolean {
+	const words = line.match(WORD) ?? []
+
+	if (words.some((word) => RESTRUCTURE_WORDS.has(word.toLowerCase()))) return true
+
+	return RESTRUCTURE_PHRASES.some((phrase) => line.includes(phrase))
+}
+
+// The backticked paths on the lines of `body` that carry a restructuring verb.
+function restructured_paths(body: string): ReadonlySet<string> {
+	const lines = body.split('\n').filter((line) => is_restructuring(line))
+
+	return new Set(lines.flatMap((line) => paths_on(line)))
+}
+
+function declared_of(issues: ReadonlyArray<DeclaringIssue>): Declared {
+	return new Map(issues.map((issue) => [issue.number, restructured_paths(issue.body ?? '')]))
+}
+
+interface SeparateContext {
+	read: BusyRead
+	repo: string
+}
+
+// The path each running lane restructures, mapped to the issue that holds it.
+function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
+	const holders = read.kind === 'busy' ? read.issues.map((issue) => issue.number) : []
+	const pairs = holders.flatMap((number) =>
+		[...(declared.get(number) ?? [])].map((path): [string, number] => [path, number]),
+	)
+
+	return new Map(pairs)
+}
+
+function paths_of(child: EpicChild, declared: Declared, repo: string): ReadonlySet<string> {
+	if (child.repo !== repo) return new Set()
+
+	return declared.get(child.number) ?? new Set()
+}
+
+function clash_note(child: EpicChild, path: string, holder: number): string {
+	return `#${String(child.number)} waits: it and #${String(holder)} both restructure \`${path}\`.`
+}
+
+interface Walk {
+	claims: Map<string, number>
+	offered: Array<EpicChild>
+	withheld: Array<EpicChild>
+	notes: Array<string>
+}
+
+function visit(walk: Walk, child: EpicChild, paths: ReadonlySet<string>): void {
+	const clash = [...paths].find((path) => walk.claims.has(path))
+
+	if (clash === undefined) {
+		walk.offered.push(child)
+		for (const path of paths) walk.claims.set(path, child.number)
+
+		return
+	}
+
+	walk.withheld.push(child)
+	walk.notes.push(clash_note(child, clash, walk.claims.get(clash) ?? child.number))
+}
+
+function merged_notice(
+	notice: string | undefined,
+	notes: ReadonlyArray<string>,
+): string | undefined {
+	const parts = notice === undefined ? notes : [notice, ...notes]
+
+	return parts.length === 0 ? undefined : parts.join('\n')
+}
+
+// `selection` with every offered candidate that restructures a path a running lane or an earlier
+// candidate already restructures moved to `withheld`, in offer order.
+function separate(
+	selection: SoloSelection,
+	declared: Declared,
+	context: SeparateContext,
+): SoloSelection {
+	const walk: Walk = {
+		claims: running_claims(declared, context.read),
+		offered: [],
+		withheld: [],
+		notes: [],
+	}
+
+	for (const child of selection.offered) visit(walk, child, paths_of(child, declared, context.repo))
+
+	const notice = merged_notice(selection.notice, walk.notes)
+	const withheld = [...walk.withheld, ...selection.withheld]
+
+	return { offered: walk.offered, withheld, ...(notice !== undefined && { notice }) }
+}
+
+const backlog_restructure = { declared_of, restructured_paths, separate }
+
+export { backlog_restructure }
+export type { Declared }

package/scripts/backlog/backlog-scope.ts

@@ -1,5 +1,5 @@
 import type { EpicNextResult } from '#scripts/epic/epic-report'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { AUTO_OK_LABEL, EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 
 // Which open issues the backlog will not run, and why (joshuafolkken/kit#1652).