@joshuafolkken/kit 1.953.0 → 1.972.0

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 = {

package/scripts/epic/epic-next.ts

@@ -16,7 +16,7 @@ import { epic_lane_offer, type LaneOffer, type LaneRequest } from './epic-lane-o
 import { epic_next_read, type EpicRead, type SnapshotReads } from './epic-next-read'
 import { epic_next_views, type EpicView } from './epic-next-views'
 import { epic_outside_blocker } from './epic-outside-blocker'
-import { epic_report, type EpicNextResult, type EpicVerdict } from './epic-report'
+import { epic_report, type EpicNextResult } from './epic-report'
 
 // `josh epic:next <E…>` — which of the named epics' children can be started right now, bundled per
 // repository, and what the rest are waiting on (joshuafolkken/kit#860).
@@ -210,7 +210,7 @@ function refuse(reason: string): number {
 // The verdict as it applies to *this* repository. `run` never reaches a caller here: it means some
 // other repository has work, which for this session is something to wait on rather than a state its
 // loop has a branch for. The whole-run timeout is what bounds that wait.
-function repo_verdict(verdict: EpicVerdict): EpicVerdict {
+function repo_verdict(verdict: LaneOffer['verdict']): LaneOffer['verdict'] {
 	return verdict === 'run' ? 'wait' : verdict
 }
 

package/scripts/epic/epic-solo.ts

@@ -0,0 +1,147 @@
+import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { epic_busy, type BusyRead } from './epic-busy'
+import type { EpicChild } from './epic-graph'
+import { epic_report, type EpicNextResult } from './epic-report'
+
+// The `run:solo` gate on what a run is offered (joshuafolkken/kit#2776).
+//
+// `wip-cap.md`'s run-alone section says an issue whose defect reaches the verification path runs
+// alone, and until this gate that was a judgement made at dispatch — the offer handed such an issue
+// out beside others and `backlog:drive` launched every number it was given. The label records the
+// judgement once; this applies it to every ask, so it holds without an agent in the loop.
+//
+// **Both offer paths call `select`**: `backlog:next` (the pool drain, through `gate`) and
+// `epic:next --lanes` (a named epic's children, `epic-lane-offer.ts`). One rule, so the two cannot
+// disagree about what may start beside what.
+//
+// Three rules, all against the repository's `in-progress` holders (`epic_busy.read_repository`):
+// a running `run:solo` issue lets nothing new start; a `run:solo` candidate starts only into an idle
+// repository and then alone; and nothing ranked below a waiting `run:solo` candidate is offered past
+// it, so it is not starved by the lanes it is waiting on. A listing that could not be read is not an
+// idle repository — the same fail-safe answer `epic_busy` gives.
+//
+// **An idle repository takes its first `run:solo` candidate ahead of the ranking**
+// (joshuafolkken/kit#2778). An issue carries the label because its defect reaches the verification
+// path, and `wip-cap.md` resumes a batch only once that has merged — so an ordinary candidate ranked
+// ahead of it would spend a whole wave running alone, then hold the fix back behind its own merge.
+// While lanes are running the ranking stands: nothing overtakes a waiting `run:solo` candidate, and
+// the ones ahead of it keep their lanes.
+
+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 {
+	offered: ReadonlyArray<EpicChild>
+	withheld: ReadonlyArray<EpicChild>
+	notice?: string
+}
+
+interface SoloGate {
+	result: EpicNextResult
+	notice?: string
+}
+
+function is_solo(child: EpicChild): boolean {
+	return has_label_name(child.labels, RUN_SOLO_LABEL)
+}
+
+function solo_holder(read: BusyRead): number | undefined {
+	if (read.kind !== 'busy') return undefined
+
+	return read.issues.find((issue) => has_any_label(issue.labels, SOLO_LABELS))?.number
+}
+
+function held_message(holder: number, repo: string): string {
+	return issue_citation.linkify(
+		`#${String(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		repo,
+	)
+}
+
+function waiting_message(solo: number, repo: string): string {
+	return issue_citation.linkify(
+		`#${String(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		repo,
+	)
+}
+
+function first_of(children: ReadonlyArray<EpicChild>, keep: number): SoloSelection {
+	return { offered: children.slice(0, keep), withheld: children.slice(keep) }
+}
+
+function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelection {
+	return { offered: [], withheld: [...children], notice }
+}
+
+// The ranking with the first `run:solo` candidate moved to the head — but only into an idle
+// repository, the one place it may start. Anywhere else the ranking is returned as it was.
+function prefer(children: ReadonlyArray<EpicChild>, read: BusyRead): ReadonlyArray<EpicChild> {
+	const solo = children.find((child) => is_solo(child))
+
+	if (solo === undefined || read.kind !== 'idle') return children
+
+	return [solo, ...children.filter((child) => child !== solo)]
+}
+
+// Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
+// candidates ahead of it when lanes are running, and it alone into an idle repository.
+function select_candidates(
+	children: ReadonlyArray<EpicChild>,
+	read: BusyRead,
+	repo: string,
+): SoloSelection {
+	const ordered = prefer(children, read)
+	const index = ordered.findIndex((child) => is_solo(child))
+	const solo = ordered[index]
+
+	if (solo === undefined) return first_of(ordered, ordered.length)
+	if (index > 0) return first_of(ordered, index)
+	if (read.kind === 'idle') return first_of(ordered, 1)
+
+	return none_of(ordered, waiting_message(solo.number, repo))
+}
+
+// An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
+// ruled out.
+function select(children: ReadonlyArray<EpicChild>, read: BusyRead, repo: string): SoloSelection {
+	if (read.kind === 'unreadable' || read.kind === 'truncated') {
+		return none_of(children, epic_busy.busy_reason(read, repo, 0))
+	}
+
+	const holder = solo_holder(read)
+
+	if (holder !== undefined) return none_of(children, held_message(holder, repo))
+
+	return select_candidates(children, read, repo)
+}
+
+// The offered candidates of `repo` stay; the withheld ones move to `waiting`, which is where the
+// report already lists children that time alone will release.
+function withhold(result: EpicNextResult, repo: string, selection: SoloSelection): EpicNextResult {
+	return {
+		...result,
+		candidates: result.candidates.map((bundle) =>
+			bundle.repo === repo ? { ...bundle, children: selection.offered } : bundle,
+		),
+		waiting: [...result.waiting, ...selection.withheld],
+	}
+}
+
+// Only a `run` answer offers anything, so every other verdict passes through untouched.
+function gate(result: EpicNextResult, read: BusyRead, repo: string): SoloGate {
+	if (result.verdict !== 'run') return { result }
+
+	const selection = select(epic_report.candidates_for_repo(result, repo), read, repo)
+	const gated = withhold(result, repo, selection)
+
+	return selection.notice === undefined
+		? { result: gated }
+		: { result: gated, notice: selection.notice }
+}
+
+const epic_solo = { gate, is_solo, prefer, select }
+
+export type { SoloGate, SoloSelection }
+export { epic_solo }

package/scripts/epic/epic-triage.ts

@@ -0,0 +1,47 @@
+import { has_label_name, RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/git/issue-labels'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import type { EpicChild } from './epic-graph'
+
+// The triage gate on what a run is offered (joshuafolkken/kit#2779).
+//
+// `run:solo` (joshuafolkken/kit#2776) records that an issue runs alone, but its absence said nothing:
+// "judged safe beside others" and "never judged" looked the same, and an issue opted in mid-run reached
+// `backlog:drive` without any agent reading it. `run:lane` records the other answer, so an issue with
+// neither label is one nobody has judged — and such an issue may be one that must run alone.
+//
+// **One untriaged candidate withholds every candidate**, not just itself: whether the others may start
+// depends on whether it is `run:solo`, which is exactly what is not known yet. The answer is the
+// `triage` verdict, which `backlog:drive` hands back to the parent rather than acting on.
+//
+// **Both offer paths call `untriaged`**: `backlog:next` (the pool drain) and `epic:next --lanes`
+// (a named epic's children, `epic-lane-offer.ts`) — the same pairing `epic_solo` keeps.
+
+type TriageVerdict = 'triage'
+
+const TRIAGE_VERDICT: TriageVerdict = 'triage'
+
+function is_triaged(child: EpicChild): boolean {
+	const { labels } = child
+
+	return has_label_name(labels, RUN_SOLO_LABEL) || has_label_name(labels, RUN_LANE_LABEL)
+}
+
+// The candidates nobody has judged, in the order they were given.
+function untriaged(children: ReadonlyArray<EpicChild>): ReadonlyArray<EpicChild> {
+	return children.filter((child) => !is_triaged(child))
+}
+
+// Names every untriaged number, so the parent reading standard error knows which issues to judge.
+function message(children: ReadonlyArray<EpicChild>, repo: string): string {
+	const numbers = children.map((child) => `#${String(child.number)}`).join(', ')
+
+	return issue_citation.linkify(
+		`Untriaged: ${numbers} carry neither \`${RUN_SOLO_LABEL}\` nor \`${RUN_LANE_LABEL}\` in ${repo}, so nothing is offered until each is judged. Read each one, record its blocked-by order and one of the two labels with a comment saying why, then ask again.`,
+		repo,
+	)
+}
+
+const epic_triage = { TRIAGE_VERDICT, is_triaged, message, untriaged }
+
+export type { TriageVerdict }
+export { epic_triage }

package/scripts/gate/hook-gate-reuse.ts

@@ -53,14 +53,13 @@ function is_force_requested(force_environment: string): boolean {
 // nothing" for "git could not be asked". Every predicate below treats the two differently.
 //
 // **The observation ledger is dropped from the reading, and it is the one line that may be**
-// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes the ledger from
-// what it stages, so a parent's appended line sits modified-but-never-staged for the whole interval
-// between the append and the next `pnpm josh observations:flush` — and every condition below reads a
-// non-empty status as "this operation carries a tree no check has read". Left in, one ledger line
-// would send every commit and every push in the primary checkout back to the full gate for days,
-// which is the reuse this module exists to grant. **Dropping it is sound because nothing can carry
-// it**: the exclusion means the index and the push are byte-for-byte the recorded tree whatever the
-// ledger says, and the ledger's own content is checked by the CI of the pull request the flush opens.
+// (joshuafolkken/kit#1756). Lines are appended throughout a run — a review's record lands after its
+// gate — and every condition below reads a non-empty status as "this operation carries a tree no
+// check has read". Left in, one ledger line would send every commit and every push in the primary
+// checkout back to the full gate, which is the reuse this module exists to grant. **Dropping it is
+// sound because the ledger is no code any check runs**: `pnpm josh git` stages it with the run's
+// commit only after its grammar has been parsed (joshuafolkken/kit#2763), and the rest of its content
+// is checked by the CI of the pull request that carries it.
 async function read_status_lines(): Promise<ReadonlyArray<string> | undefined> {
 	try {
 		const status = await git_command.status()

package/scripts/git/git-closes-keyword.ts

@@ -0,0 +1,15 @@
+// Captures the number, so the one pattern answers every question asked of a PR body: whether the
+// linked issue will auto-close, which issue that is when the invocation did not say
+// (joshuafolkken/kit#1539), and whether a merged pull request closes a child a `backlogrun` judged
+// unfinished (joshuafolkken/kit#2769). A second pattern would be two readings of "closes #N" to disagree.
+const CLOSES_PATTERN = /closes\s+#(\d+)/iu
+
+function parse_closes_issue_number(body: string | undefined): string | undefined {
+	if (body === undefined) return undefined
+
+	return CLOSES_PATTERN.exec(body)?.[1]
+}
+
+const git_closes_keyword = { parse_closes_issue_number }
+
+export { git_closes_keyword }

package/scripts/git/git-followup-flush.ts

@@ -5,12 +5,11 @@ import { git_command } from './git-command'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { main_sync } from './main-sync'
 
-// The observation ledger's only commit path is `pnpm josh observations:flush`, and until now no
-// command's procedure called it (joshuafolkken/kit#1810). The ledger is excluded from ordinary
-// staging (joshuafolkken/kit#1756), so an appended line stayed in the working tree until a person
-// remembered to flush it — the same "a run that had to remember is the run that forgets" defect the
-// staging side was built to avoid, left standing on the commit side. This wires the flush into
-// `pnpm josh followup`, the one step that knows the merge has landed.
+// The residual commit path for the observation ledger (joshuafolkken/kit#1810). A run's appended lines
+// ride its own commit (joshuafolkken/kit#2763), so after the merge the ledger is usually clean and this
+// short-circuits; what it still catches is a line appended after the commit — a second review round's
+// record — which would otherwise stay in the working tree until a person remembered to flush it. This
+// wires the flush into `pnpm josh followup`, the one step that knows the merge has landed.
 //
 // **It runs before the working-tree hold is released** (`scripts-ai/git-followup-finish.ts`, whose
 // `finish()` runs after `git_pr_followup.run()` returns), because a flush switches branches, and a

package/scripts/git/git-followup-issue-close.ts

@@ -0,0 +1,75 @@
+import { poll, type PollOptions } from '#scripts/lib/poll'
+import { z } from 'zod'
+import { git_epic_parse } from './git-epic-parse'
+import { git_gh_command } from './git-gh-command'
+import { parse_json_object_safe } from './parse-json-array'
+
+// **A merged pull request whose `closes #N` GitHub did not apply** (joshuafolkken/kit#2770). From
+// 2026-09-30 06:34Z every merge `followup` made left its issue open — seven in a row, where every
+// earlier one was closed by the pull request within a second — although the merge request, the
+// merging account and the `closes #N` first line were all the same as before. The run then reported
+// success, and a `backlogrun` read the still-open child as a failure and stopped.
+//
+// **The issue's state is what is checked, not `closingIssuesReferences`.** That field is GraphQL-only
+// (a cloud session is answered 403 there, joshuafolkken/kit#1022) and it is not the fact that failed:
+// PR #2768 answered it empty at the time and names #2761 now, while #2761 was never closed by it. The
+// observable defect is an issue left open, so that is what is read, and what is repaired.
+//
+// **A short wait first**, because GitHub applies the keyword asynchronously — the closes it did apply
+// landed within a second of the merge. Closing on the first read would take the close away from the
+// pull request on every run that merely raced it.
+const CLOSE_WAIT: PollOptions = { attempts: 3, interval_ms: 2000 }
+
+const CLOSE_RECOVERY = 'gh api -X PATCH repos/{owner}/{repo}/issues/<N> -f state=closed'
+
+const state_read_schema = z.object({ state: z.string().optional() })
+
+async function is_issue_closed(issue_number: string): Promise<boolean> {
+	const raw = await git_gh_command.issue_get_state_and_relations(issue_number)
+	const parsed = raw === undefined ? undefined : parse_json_object_safe(raw, state_read_schema)
+
+	return git_epic_parse.is_state_closed(parsed?.state)
+}
+
+const FOLLOWUP_CLOSER = 'pnpm josh followup'
+
+// English, like every other string a script posts: the comment says why the close came from this
+// command rather than from the pull request, so a reader of the issue is not left guessing. `closer`
+// names the command that closed it — `followup` at the merge, or `run:merge` when a `backlogrun`
+// finds the child still open afterwards (joshuafolkken/kit#2769).
+function build_close_comment(pr_url: string | undefined, closer: string = FOLLOWUP_CLOSER): string {
+	return (
+		`Closed by \`${closer}\`: ${pr_url ?? 'the merged pull request'} merged, ` +
+		'but GitHub did not apply its ' +
+		'`closes #N` keyword (joshuafolkken/kit#2770).'
+	)
+}
+
+// **Throws when the issue is still open**, so the guard around it reports the failure with the
+// command that finishes it by hand — an issue left open after a merge is the one thing this step
+// exists to stop going unnoticed.
+async function ensure_issue_closed(
+	input: { issue_number: string | undefined; pr_url: string | undefined; closer?: string },
+	wait: PollOptions = CLOSE_WAIT,
+): Promise<void> {
+	const { issue_number } = input
+	const is_done =
+		issue_number === undefined ||
+		(await poll.poll_until(async () => await is_issue_closed(issue_number), wait))
+	if (is_done) return
+
+	console.warn(`⚠️  Issue #${issue_number} is still open after the merge — closing it.`)
+	const comment = build_close_comment(input.pr_url, input.closer)
+
+	if (!(await git_gh_command.issue_close(issue_number, comment))) {
+		throw new Error(`gh api could not close issue #${issue_number}`)
+	}
+}
+
+const git_followup_issue_close = {
+	ensure_issue_closed,
+	build_close_comment,
+	CLOSE_RECOVERY,
+}
+
+export { git_followup_issue_close }