@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/run/run-stage-read.ts

@@ -1,12 +1,17 @@
+import { backlog_plan_comment } from '#scripts/backlog/backlog-plan-comment'
 import { issue_state } from '#scripts/issue/issue-state'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { run_halfrun_resume } from './run-halfrun-resume'
+import { run_open_pr } from './run-open-pr'
+import { run_pr_return } from './run-pr-return'
 import { run_prrun_resume, type PrrunToken } from './run-prrun-resume'
 import { run_stage, type StageState } from './run-stage'
 
 // The reading half of the stage ladder: the facts `run_stage.state_of` folds
 // into one state, each read from where the stage that produced it left it — never from the
-// conversation. A closed issue and the `run:planned` label come from GitHub; a `halfrun` stop and a `prrun`
+// conversation. A closed issue, the `run:planned` label and a plan comment come from GitHub — a fullrun
+// lane's `issue:plan` posts the comment without the label, so a lane dispatched again after a yield
+// starts at its recorded plan (joshuafolkken/kit#5700); a `halfrun` stop and a `prrun`
 // stop come from the stop's own mark on the tree's hold (`run-halfrun-resume.ts`,
 // `run-prrun-resume.ts`).
 
@@ -17,6 +22,29 @@ interface StageRead {
 	// The `prrun` stop's resume token, kept so the entry acts on it without reading the pull request
 	// again; `undefined` when no `prrun` stop is recorded for the issue.
 	prrun_token: PrrunToken | undefined
+	// What returned an open pull request for a fix, printed under the stage line; absent otherwise.
+	returned?: string
+}
+
+// The text naming what returned the pull request. A read that fails (a gh or API error) answers
+// `undefined` with a warning — the entry goes on to the gate, where `followup` still refuses a red merge.
+async function read_returned(issue: string): Promise<string | undefined> {
+	try {
+		return run_pr_return.format(await run_pr_return.read(issue))
+	} catch (error) {
+		console.warn(`pr-returned check skipped, resuming at the gate: ${String(error)}`)
+
+		return undefined
+	}
+}
+
+// An open pull request returned for a fix resumes at implementation, any other at the gate.
+async function read_open_pr(issue: string): Promise<Omit<StageRead, 'prrun_token'>> {
+	const returned = await read_returned(issue)
+
+	return returned === undefined
+		? { state: run_stage.PR_OPEN }
+		: { state: run_stage.PR_RETURNED, returned }
 }
 
 function is_closed(read: StateRead): boolean {
@@ -38,18 +66,24 @@ async function read_stop(
 // An unreadable issue reads as neither closed nor planned: the ordinary entry that follows reads it
 // again and answers `unknown` for it.
 async function read_stage(issue: string): Promise<StageRead> {
-	const [issue_read, stop] = await Promise.all([
+	const [issue_read, stop, plan] = await Promise.all([
 		issue_state_cli.read_issue(issue),
 		read_stop(issue),
+		backlog_plan_comment.read_plan(Number(issue)),
 	])
 	const state = run_stage.state_of({
 		is_closed: is_closed(issue_read),
 		is_prrun_stopped: stop.prrun_token !== undefined,
 		is_halfrun_stopped: stop.is_halfrun_stopped,
-		is_planned: issue_state.is_planned(issue_read),
+		is_planned: issue_state.is_planned(issue_read) || plan !== undefined,
 	})
 
-	return { state, prrun_token: stop.prrun_token }
+	const has_pr = state === run_stage.FRESH || state === run_stage.PLANNED
+	const is_open_pr = has_pr && (await run_open_pr.is_pending(issue))
+
+	if (!is_open_pr) return { state, prrun_token: stop.prrun_token }
+
+	return { ...(await read_open_pr(issue)), prrun_token: stop.prrun_token }
 }
 
 const run_stage_read = { read_stage }

package/scripts/run/run-stage.ts

@@ -5,7 +5,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 // issue**. A run that finds work already done resumes after it rather than redoing it, and a command
 // whose stopping point the issue has already reached reports that and stops.
 //
-// This module is the pure half of that rule: the five states an issue can be found in, the four
+// This module is the pure half of that rule: the states an issue can be found in, the four
 // commands, and the one table that maps a (state, command) pair to a start and an end. `run:entry` reads
 // the state (`run-stage-read.ts`) and branches on the answer; the stage table in
 // `docs/how-to/run-issues.md` and each stop's `Next:` line are pinned to this module by
@@ -29,9 +29,14 @@ const PLANNED = 'planned'
 const HALFRUN_STOPPED = 'halfrun-stopped'
 const PRRUN_STOPPED = 'prrun-stopped'
 const MERGED = 'merged'
+const PR_OPEN = 'pr-open'
+const PR_RETURNED = 'pr-returned'
 
-// In ladder order: a state's index is how many rungs the issue has already climbed.
-const STATES = [FRESH, PLANNED, HALFRUN_STOPPED, PRRUN_STOPPED, MERGED] as const
+// Ranked states have completed that many rungs. An unverified open PR resumes at the gate; one
+// returned for a fix — a red required check, or a person's comment since the run's last one — resumes
+// at implementation (`run-pr-return.ts`).
+const RANKED_STATES = [FRESH, PLANNED, HALFRUN_STOPPED, PRRUN_STOPPED, MERGED] as const
+const STATES = [...RANKED_STATES, PR_OPEN, PR_RETURNED] as const
 
 type StageState = (typeof STATES)[number]
 
@@ -45,6 +50,8 @@ const STARTS: Readonly<Record<StageState, string>> = {
 	[HALFRUN_STOPPED]: 'gate',
 	[PRRUN_STOPPED]: 'followup',
 	[MERGED]: REACHED,
+	[PR_OPEN]: 'gate',
+	[PR_RETURNED]: 'implement',
 }
 
 // Every start a decision can print, in ladder order — the `run:entry` oracle's vocabulary.
@@ -94,7 +101,8 @@ function state_of(facts: StageFacts): StageState {
 }
 
 function decide(state: StageState, command: StageCommand): StageDecision {
-	const is_reached = STATES.indexOf(state) > COMMANDS.indexOf(command)
+	const ranked_state = state === PR_OPEN || state === PR_RETURNED ? PLANNED : state
+	const is_reached = RANKED_STATES.indexOf(ranked_state) > COMMANDS.indexOf(command)
 	const start = is_reached ? REACHED : STARTS[state]
 
 	return { state, command, start, end: ENDS[command], is_reached }
@@ -107,7 +115,9 @@ function next_commands(command: StageCommand): ReadonlyArray<StageCommand> {
 
 // The `Next:` line a stop's Telegram and report carry, e.g. `Next: prrun #<N> | fullrun #<N>`.
 function next_line(command: StageCommand, issue: string): string {
-	const commands = next_commands(command).map((next) => `${next} ${issue_cite.plain(issue)}`)
+	const commands = next_commands(command).map(
+		(next) => `${next} ${issue_cite.plain_for('linked', issue)}`,
+	)
 
 	return `${NEXT_PREFIX}${commands.join(NEXT_SEPARATOR)}`
 }
@@ -115,7 +125,7 @@ function next_line(command: StageCommand, issue: string): string {
 function format_decision(issue: string, decision: StageDecision): string {
 	const fields = [`at: ${decision.state}`, `to: ${decision.command}`, `start: ${decision.start}`]
 
-	return `stage ${issue_cite.plain(issue)} — ${fields.join(' · ')}`
+	return `stage ${issue_cite.plain_for('linked', issue)} — ${fields.join(' · ')}`
 }
 
 function cell(state: StageState, command: StageCommand): string {
@@ -144,6 +154,8 @@ const run_stage = {
 	KICKOFF,
 	MERGED,
 	PLANNED,
+	PR_OPEN,
+	PR_RETURNED,
 	PRRUN,
 	PRRUN_STOPPED,
 	REACHED,

package/scripts/run/run-status.ts

@@ -8,7 +8,8 @@ import { issue_state, type IssueState } from '#scripts/issue/issue-state'
 // **It is read-only, and that is the whole point** — the merge event has its own composite
 // (`run:merge`), and the pre-edit reads have theirs (`run:prep`); this is the passive glance a resumed
 // session or a non-merge decision takes, which must not write. `run:hold`'s claim and
-// `run:progress`'s clock mark are excluded for exactly that reason.
+// `run:progress`'s clock mark are excluded for exactly that reason; the hold record itself is *read*
+// by `tree:status`, which never claims it.
 //
 // The leading summary line carries the three facts on one line — the state, the cost verdict and the
 // carry summary — so the glance is read off the first line without parsing the sections below it.

package/scripts/run/run-step-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { agent_provider } from '#scripts/agent/agent-provider'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { find_package_directory } from '#scripts/josh/josh-logic'
@@ -15,7 +15,9 @@ import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
 import { run_step, type ParentInput, type StepInput } from './run-step'
 import { run_step_lane_plan } from './run-step-lane-plan'
+import { run_step_progress } from './run-step-progress'
 import { run_step_section } from './run-step-section'
+import { run_step_section_once } from './run-step-section-once'
 
 // `josh run:step [<N>]` — print the run's next single action, followed by the section that governs it
 // (`run-step-section.ts`), computed from the event stream, the carry
@@ -27,6 +29,8 @@ import { run_step_section } from './run-step-section'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
+const SHIP_REPEAT =
+	'ship preconditions: unchanged — printed earlier this session; after a compaction: pnpm josh run:prep '
 const USAGE =
 	'Usage: josh run:step [<issue-number>] — without a number it answers for the `backlogrun` carry record this session drives'
 
@@ -58,6 +62,15 @@ const UNREADABLE_RUN: RunReads = {
 	last_event: undefined,
 }
 
+// A repository's carry belongs to its parent and dispatched children. An interactive numbered
+// fullrun beside another owner uses the existing no-carry path, without changing that owner's record.
+function invocation_carry(carry: CarryRead, is_lane_child: boolean): CarryRead {
+	if (carry.kind !== 'carried') return carry
+	if (is_lane_child || run_headless.is_owned_here(carry.carry, lane_reap.own_ancestry)) return carry
+
+	return { kind: 'none' }
+}
+
 // The run-level reads, keyed on the common git directory both the carry and the event stream share. A
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
 function read_run(
@@ -67,7 +80,10 @@ function read_run(
 ): RunReads {
 	if (directory === undefined) return UNREADABLE_RUN
 
-	const carry = run_carry.read_carry(run_carry.carry_path(directory))
+	const carry = invocation_carry(
+		run_carry.read_carry(run_carry.carry_path(directory)),
+		is_lane_child,
+	)
 	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
 	// The last event *within this invocation's scope*, not the raw newest one: a stale event a previous
 	// invocation left on the stream — an old `child-launch`, say — must not be read as this run's
@@ -108,7 +124,7 @@ function step_input(parts: PrepParts, run_reads: RunReads, is_lane_child: boolea
 		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.
 		is_retrospective_enabled: run_retrospective.is_enabled(),
 		has_changes: parts.has_changes,
-		has_completion_callback: agent_role_profile.has_completion_callback(),
+		has_completion_callback: agent_provider.has_completion_callback(),
 	}
 }
 
@@ -166,24 +182,36 @@ async function run_parent(): Promise<number> {
 	return FAILURE_EXIT_CODE
 }
 
-// The action line, then — under `implement` — the `lane:plan` a lane child runs before its first edit.
-// Only `implement` reads it, so no other step pays for the plan comment's request.
+// The action line, then — under `implement` — the `lane:plan` a lane child runs before its first edit
+// and its `--imports` hint. Only `implement` reads it, so no other step pays for the plan comment's request.
 async function action_lines(input: StepInput, line: string): Promise<ReadonlyArray<string>> {
 	if (line !== run_step.IMPLEMENT) return [line]
-	const next = await run_step_lane_plan.line_for(input.issue_number, input.is_lane_child)
 
-	return next === undefined ? [line] : [line, next]
+	return [line, ...(await run_step_lane_plan.lines_for(input.issue_number, input.is_lane_child))]
+}
+
+// The ship preconditions, once per session while they read the same (`run-step-section-once.ts`):
+// `run:entry` printed them in its bundle, so an unchanged list is one line naming where to re-read it.
+function ship_text(issue_number: string, problems: ReadonlyArray<string>): string {
+	const body = run_prep.ship_body(problems)
+
+	if (run_step_section_once.is_text_recorded(body)) return `${SHIP_REPEAT}${issue_number}`
+	run_step_section_once.record_text(body)
+
+	return body
 }
 
 async function report({ input, ship_problems }: Gathered): Promise<number> {
 	const action = run_step.next_action(input)
 
+	await run_step_progress.record(input.issue_number, action.line, input.last_event)
+
 	const lines = await action_lines(input, action.line)
 
 	for (const line of lines) console.info(line)
 	// On stderr, so stdout stays the action lines and their rule: what `josh ship` would
-	// refuse on is said at every step, while it is still cheap to meet.
-	if (ship_problems.length > 0) console.error(run_prep.ship_body(ship_problems))
+	// refuse on is said at every step — in full once per session, then as one line — while it is still cheap to meet.
+	if (ship_problems.length > 0) console.error(ship_text(input.issue_number, ship_problems))
 
 	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
 	// same failure, so a position missing its issue state is never read as a confident next step.
@@ -213,7 +241,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_step_cli = { run }
+const run_step_cli = { run, ship_text }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-step-lane-plan.ts

@@ -1,27 +1,41 @@
 import { backlog_plan_comment } from '#scripts/backlog/backlog-plan-comment'
+import { backlog_triage_approval } from '#scripts/backlog/backlog-triage-approval'
 import { lane_plan } from '#scripts/lane/lane-plan'
+import { lane_plan_auto } from '#scripts/lane/lane-plan-auto'
 import { shell_quote } from '#scripts/lib/shell-quote'
 
 // The `lane:plan` command a lane child runs before its first edit — `lane-plan-guard.ts` refuses that
 // edit until the plan is cleared. joshuafolkken/kit#4910's child retried a refused Edit eight times
 // before it ran `lane:plan`, since nothing it read named the step first (joshuafolkken/kit#4923).
-// The paths are its plan comment's; with none, the child names its own.
-
-const PATH_PLACEHOLDER = '<path>...'
+// The paths are its plan comment's; with none, the child names its own. A size approval the parent
+// wrote by `backlog:triage --adopt` is named as `--size-approval` (joshuafolkken/kit#6776), ahead of
+// the `--imports` the child appends, which takes every argument after it.
+
+async function command_for(issue_number: string, issue: number): Promise<string> {
+	const command = lane_plan_auto.command_of(
+		issue_number,
+		await backlog_plan_comment.plan_paths(issue),
+	)
+	const approval = await backlog_triage_approval.existing_file(issue_number)
+
+	return approval === undefined
+		? command
+		: `${command} --size-approval ${shell_quote.word(approval)}`
+}
 
-// The command to print under `implement`, or `undefined` when not a lane child or its plan is cleared.
-async function line_for(issue_number: string, is_lane_child: boolean): Promise<string | undefined> {
+// The lines to print under `implement` — the command, then `lane_plan_auto`'s `--imports` hint — or
+// none when not a lane child or its plan is cleared.
+async function lines_for(
+	issue_number: string,
+	is_lane_child: boolean,
+): Promise<ReadonlyArray<string>> {
 	const issue = Number(issue_number)
 
-	if (!is_lane_child || !lane_plan.is_uncleared(issue, process.cwd())) return undefined
-
-	const paths = await backlog_plan_comment.plan_paths(issue)
-	const named =
-		paths.length === 0 ? PATH_PLACEHOLDER : paths.map((path) => shell_quote.word(path)).join(' ')
+	if (!is_lane_child || !lane_plan.is_uncleared(issue, process.cwd())) return []
 
-	return `pnpm josh lane:plan ${issue_number} ${named}`
+	return [await command_for(issue_number, issue), lane_plan_auto.IMPORTS_HINT]
 }
 
-const run_step_lane_plan = { line_for }
+const run_step_lane_plan = { lines_for }
 
 export { run_step_lane_plan }

package/scripts/run/run-step-progress.ts

@@ -0,0 +1,61 @@
+import { lane_implement_signals_record } from '#scripts/lane/lane-implement-signals-record'
+import { run_entry } from '#scripts/run/entry/run-entry'
+import { run_event_step, type FullrunStep } from '#scripts/run/event/run-event-step'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_step } from './run-step'
+
+// The fullrun step a computed position stands at, written as a `step` event (joshuafolkken/kit#6598).
+// **It reads the position `run:step` and `run:entry` already computed**, never decides one: the
+// pre-implementation verdict names the step before the first edit, and the newest event the one after.
+
+const { STEP } = run_event_step
+const KIND = run_event_stream.EVENT_KIND
+
+const VERDICT_STEPS: Readonly<Partial<Record<string, FullrunStep>>> = {
+	[run_step.UPDATE_DEPS]: STEP.UPDATE_DEPS,
+	[run_step.IMPLEMENT]: STEP.IMPLEMENT,
+	[run_step.HUMAN_REVIEW]: STEP.IMPLEMENT,
+	[run_entry.GATE_VERDICT]: STEP.GATE,
+}
+
+const EVENT_STEPS: Readonly<Partial<Record<string, FullrunStep>>> = {
+	[KIND.REVIEW_ROUND]: STEP.GATE,
+	[KIND.PR_OPENED]: STEP.FOLLOWUP,
+}
+
+// `line` is the printed action or verdict, `last_event` the newest event the position was read from.
+function step_of(line: string, last_event = ''): FullrunStep | undefined {
+	return VERDICT_STEPS[line] ?? EVENT_STEPS[last_event]
+}
+
+interface ProgressIo {
+	step: (issue: string, step: FullrunStep) => Promise<void>
+	signals: (issue: string) => Promise<void>
+}
+
+const STREAM_IO: ProgressIo = {
+	step: async (issue, step) => {
+		await run_event_step.record(issue, step)
+	},
+	signals: lane_implement_signals_record.record,
+}
+
+// A position that names no step writes nothing; the gate also writes the implement signals
+// (joshuafolkken/kit#6983).
+async function record(
+	issue: string,
+	line: string,
+	last_event: string | undefined,
+	io: ProgressIo = STREAM_IO,
+): Promise<void> {
+	const step = step_of(line, last_event)
+
+	if (step === undefined) return
+
+	await io.step(issue, step)
+	if (step === STEP.GATE) await io.signals(issue)
+}
+
+const run_step_progress = { record, step_of }
+
+export { run_step_progress }

package/scripts/run/run-step-section-driver.ts

@@ -0,0 +1,27 @@
+import { document_section_cli } from '#scripts/document/document-section-cli'
+import { run_step_section_table, type SectionReference } from './run-step-section-table'
+
+// The text a `backlog:drive` hand-off carries (joshuafolkken/kit#5920), apart from the printing in
+// `run-step-section.ts` (joshuafolkken/kit#5987): the wake driver needs no print, so a change to the
+// printing never reaches its tests.
+
+const { DRIVER_SECTIONS, LOOP } = run_step_section_table
+
+// A section that does not resolve — a document a consumer does not ship — is named instead of
+// failing the hand-off; the table's test keeps every row resolving in kit.
+function carried_text(found: SectionReference, root: string): string {
+	return (
+		document_section_cli.section_text(found.document, found.heading, root) ??
+		`\`${found.document}\` → "${found.heading}"`
+	)
+}
+
+function driver_sections(verdict: string, root: string = process.cwd()): string {
+	const found = DRIVER_SECTIONS.find(([prefix]) => verdict.startsWith(prefix))
+
+	return (found?.[1] ?? [LOOP]).map((section) => carried_text(section, root)).join('\n')
+}
+
+const run_step_section_driver = { driver_sections }
+
+export { run_step_section_driver }

package/scripts/run/run-step-section-once.ts

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto'
+import { existsSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+
+// **A command prints the section that governs it, once per agent session** (joshuafolkken/kit#5626):
+// a command with a row in `run_step_section`'s table prints it, so the reader never spends a
+// `doc:section` turn fetching it. A second print of the same section in the same session — a re-run,
+// or `ship` after `run:review` handed the same step — prints one line naming it instead of the text
+// the session already holds. The line carries the `doc:section` fetch, because a compaction keeps the
+// session id while it drops the section from context.
+//
+// **The marker is keyed on the section, not the command**, so two commands one section governs print
+// it once between them. It is a per-session cache, so it stays in the temp root (`durable-state.ts`).
+// Without a session id (a Codex session, a detached supervisor) nothing is remembered and the section
+// always prints: a missing rule costs more than a repeated one.
+//
+// **A printed text that is no doc section is keyed on the text itself** (joshuafolkken/kit#7111) — the
+// ship preconditions `run:entry` and `run:step` both print — so a changed text prints again.
+
+const MARKER_PREFIX = 'josh-section-'
+const DIGEST_LENGTH = 16
+const TEXT_KEY_PREFIX = 'text\n'
+
+interface PrintedSection {
+	document: string
+	heading: string
+}
+
+function marker_of(key: string): string | undefined {
+	const session = process.env[agent_session_environment.SESSION_ID_KEY]
+
+	if (session === undefined) return undefined
+	const digest = createHash('sha256')
+		.update(`${session}\n${key}`)
+		.digest('hex')
+		.slice(0, DIGEST_LENGTH)
+
+	return path.join(PLATFORM_TEMP_ROOT, `${MARKER_PREFIX}${digest}`)
+}
+
+function section_key(found: PrintedSection): string {
+	return `${found.document}\n${found.heading}`
+}
+
+function is_key_recorded(key: string): boolean {
+	const marker = marker_of(key)
+
+	return marker !== undefined && existsSync(marker)
+}
+
+function record_key(key: string): void {
+	const marker = marker_of(key)
+
+	if (marker !== undefined) writeFileSync(marker, '')
+}
+
+function is_recorded(found: PrintedSection): boolean {
+	return is_key_recorded(section_key(found))
+}
+
+function record(found: PrintedSection): void {
+	record_key(section_key(found))
+}
+
+function is_text_recorded(text: string): boolean {
+	return is_key_recorded(`${TEXT_KEY_PREFIX}${text}`)
+}
+
+function record_text(text: string): void {
+	record_key(`${TEXT_KEY_PREFIX}${text}`)
+}
+
+function repeat_line(found: PrintedSection): string {
+	const fetch = `pnpm josh doc:section ${found.document} "${found.heading}"`
+
+	return `section: ${found.document} → "${found.heading}" — printed earlier this session; after a compaction: ${fetch}`
+}
+
+const run_step_section_once = { is_recorded, is_text_recorded, record, record_text, repeat_line }
+
+export { run_step_section_once }

package/scripts/run/run-step-section-table.ts

@@ -0,0 +1,120 @@
+import { run_step } from './run-step'
+
+// The action → section table `run-step-section.ts` prints from, apart from its printing
+// (joshuafolkken/kit#5987): a reader that needs only a key or a row imports this leaf, so a change
+// to the printing reaches only the tests of the commands that print.
+
+// The key `run:entry` prints under — not a `run:step` action, but the entry's own read, kept in the
+// same table so every mechanically-chosen section has one home.
+const ENTRY = 'entry'
+
+interface SectionReference {
+	document: string
+	heading: string
+}
+
+function reference(document: string, heading: string): SectionReference {
+	return { document, heading }
+}
+
+// The gate's chain governs both the implementation it follows and a stopped ship's report.
+const CHAIN_RULE = 'chain-rule.md'
+const CHAIN = reference(CHAIN_RULE, 'Run the review-to-merge chain')
+const PROGRESS = 'backlogrun-progress.md'
+// The chain's own commands, which print their row themselves (`print_once`); `run:step` prints the
+// `ship` row too, for the `ship --review` it hands. `followup` and `run:progress` print theirs too.
+const SHIP = 'ship'
+const REVIEW = 'run:review'
+const PROGRESS_WATCHER = 'run:progress'
+// `run:park` and `run:pause` print the subsection their ending follows (joshuafolkken/kit#5842), so
+// the reader never opens the whole document. The pause's names every entry's branch — `fullrun` /
+// `halfrun` stop, `backlogrun` continues — since all of them pause; a lane child's park is its stop.
+const PRE_GATE_CUT = 'pre-gate-cut.md'
+// `run:cut` prints the section its non-trivial verdict follows (joshuafolkken/kit#5953): taking the cut
+// has its own key, and the resume keeps the subcommand's, which `run:step` hands as `run:cut --resume`.
+const CUT = 'run:cut take'
+const RESUME = 'run:cut'
+const PARK = 'run:park'
+const PAUSE = 'run:pause'
+const PARK_AND_CONTINUE = reference('backlogrun-park.md', 'park and continue')
+// Rows both tables carry — the step's and the driver's.
+const STEPS = 'backlogrun-steps.md'
+const LOOP = reference(STEPS, 'The loop')
+const RESOLVE = reference(STEPS, 'Resolve what the plan can resolve')
+const RETROSPECTIVE_KEY = 'retrospective'
+const RETROSPECTIVE = reference('retrospective.md', 'The end-of-run retrospective')
+const HUMAN_REVIEW = reference('needs-human-review.md', '`needs-human-review`')
+const EPIC_CHILDREN = reference(PROGRESS, "Running a named epic's children")
+
+// Keyed on a verdict token, or on the josh subcommand a command action runs. An action with no row —
+// `wait`, `stop`, a `decide:` line — has no rule to read beyond its own line.
+const GOVERNING_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
+	[ENTRY, reference('split-assessment.md', 'The question')],
+	[run_step.IMPLEMENT, CHAIN],
+	[run_step.HUMAN_REVIEW, HUMAN_REVIEW],
+	[run_step.UPDATE_DEPS, reference('latest-gate.md', 'The dependency update')],
+	['followup', reference('followup.md', 'Run `pnpm josh followup`')],
+	[PROGRESS_WATCHER, reference('progress-watcher.md', 'Progress while the run is quiet')],
+	['run:merge', EPIC_CHILDREN],
+	['backlog:next', LOOP],
+	[CUT, reference(PRE_GATE_CUT, 'Taking the cut')],
+	[RESUME, reference(PRE_GATE_CUT, 'Resuming')],
+	[SHIP, CHAIN],
+	[REVIEW, CHAIN],
+	[RETROSPECTIVE_KEY, RETROSPECTIVE],
+	['run:carry', reference(PROGRESS, 'The hand-off')],
+	[PARK, PARK_AND_CONTINUE],
+	[PAUSE, reference('prerequisite.md', "Each entry's branch, and the pause")],
+])
+
+// **A lane child reads its own step of the chain, never the whole of it** (joshuafolkken/kit#5016):
+// the chain's step 1 runs `josh main:merge` (in `josh run:chain`), which a lane child leaves to ship's sync, and a
+// child handed the whole section ran it, moving the tree its scoped pair was green on. The step is
+// the chain's step 0, a section of its own beside the chain (joshuafolkken/kit#5946), so neither
+// reader is printed the other's steps. A stopped ship's report reads it too.
+const LANE_CHILD_STEP = reference(CHAIN_RULE, 'A lane child')
+const LANE_CHILD_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
+	[run_step.IMPLEMENT, LANE_CHILD_STEP],
+	[SHIP, LANE_CHILD_STEP],
+	[REVIEW, LANE_CHILD_STEP],
+	[PARK, reference(PRE_GATE_CUT, 'A lane child records its park before it stops')],
+])
+
+// **A `backlog:drive` verdict handed to a session carries its governing sections** (joshuafolkken/kit#5920):
+// keyed on the verdict's prefix, first match wins, so `merge human-review` stands above `merge`. A loop
+// row carries "The loop" — what the session does — beside the section the row needs.
+const DRIVER_SECTIONS: ReadonlyArray<readonly [string, ReadonlyArray<SectionReference>]> = [
+	[RETROSPECTIVE_KEY, [RETROSPECTIVE]],
+	['merge human-review', [HUMAN_REVIEW]],
+	['triage', [LOOP, RESOLVE]],
+	['judge', [LOOP, reference('docs/josh-commands-backlog.md', '`josh auto-ok:judge`')]],
+	// A refused launch is parked `run:stalled` by the driver (joshuafolkken/kit#6878): its section is the
+	// retry of a recovered mechanical failure, never "park and continue".
+	['launch #', [LOOP, RESOLVE]],
+	['merge', [LOOP, EPIC_CHILDREN]],
+	[
+		'epic #',
+		[
+			reference(STEPS, 'Named issues run first, in order'),
+			reference(STEPS, 'The session cut is inside the invocation'),
+		],
+	],
+	['watch', [LOOP, RETROSPECTIVE]],
+]
+
+const run_step_section_table = {
+	CUT,
+	DRIVER_SECTIONS,
+	ENTRY,
+	GOVERNING_SECTIONS,
+	LANE_CHILD_SECTIONS,
+	LOOP,
+	PARK,
+	PAUSE,
+	PROGRESS: PROGRESS_WATCHER,
+	RESUME,
+	RETROSPECTIVE: RETROSPECTIVE_KEY,
+}
+
+export type { SectionReference }
+export { run_step_section_table }