@joshuafolkken/kit 1.872.0

package/scripts/run/run-merge-steps.ts

@@ -0,0 +1,326 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { git_stash } from '#scripts/git/git-stash'
+import { IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { lane_close } from '#scripts/lane/lane-close'
+import { lane_reap } from '#scripts/lane/lane-reap'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_relaunch } from '#scripts/lane/lane-relaunch'
+import { run_carry, type CarryChange, type CarryOwner, type RunCarry } from './run-carry'
+import { run_cut, type RunCut } from './run-cut'
+import { run_merge } from './run-merge'
+
+// The result of attempting to apply a carry change. Distinguishing `refused` from `applied` lets
+// callers surface the refusal as a hard failure rather than silently continuing on a carry that was
+// not advanced (joshuafolkken/kit#2114).
+type ApplyCarryResult =
+	{ kind: 'applied'; carry: RunCarry } | { kind: 'refused'; carry: RunCarry } | { kind: 'none' }
+
+// The side-effect half of `run:merge` (joshuafolkken/kit#2024). The pure decisions are `run-merge.ts`'s;
+// this file is what those decisions drive — the same actions the parent used to spend two turns on,
+// collapsed into one command.
+//
+// **What was a separate `pnpm josh` call stays one.** `main:sync`, `lane:close`, `cost` and
+// `epic:next` / `backlog:next` are run as captured subprocesses, so their output lands in this
+// command's own return value rather than on the caller's stdout and their report logic is reused
+// rather than cloned. The new work — counting the outcome into the single-source carry record, parking
+// a failed child, and generating the progress comment from that record — is in-process, because it has
+// a reusable logic function and no stdout to keep clean.
+
+const OVER = 'over'
+const LANES = '--lanes'
+const REPO_FLAG = '--repo'
+const LANE_CLOSE_OCCASION = 'lane close'
+const GIT_ENTRY = '.git'
+
+// One returned child's context, gathered from the command line by the CLI.
+interface MergeContext {
+	child: string
+	epic: string | undefined
+	repo: string | undefined
+	over: number
+	owner: CarryOwner
+	// The child's transcript output path, when the caller passed `--output`. Read to tell an API-outage
+	// ending apart from a genuine child failure (joshuafolkken/kit#2240); absent leaves outage detection
+	// off, so the child is classified from its GitHub state alone as before.
+	output?: string | undefined
+}
+
+interface FailedResult {
+	carry: RunCarry | undefined
+	is_parked: boolean
+	// Set when the carry record refused the count because this session is not its owner
+	// (joshuafolkken/kit#2114). The caller surfaces this as a hard failure rather than continuing.
+	is_refused: boolean
+}
+
+// A captured `pnpm josh` subprocess: its output is read back rather than inherited, and a non-zero
+// exit is a value to branch on rather than a throw. The step's stderr stays piped here — `run:merge`
+// composes its own report from the captured values — so this passes `josh_command.josh_run`'s default.
+async function josh(args: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(args)
+}
+
+// Read the single-source carry record, or `undefined` when there is none to advance.
+async function read_record(): Promise<{ target: string; carry: RunCarry } | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	const target = run_carry.carry_path(directory)
+	const read = run_carry.read_carry(target)
+
+	if (read.kind !== 'carried' && read.kind !== 'expired') return undefined
+
+	return { target, carry: read.carry }
+}
+
+// Count the outcome into the carry record, respecting the ownership guard so a session whose record
+// was handed off cannot advance a budget that is no longer its own. Returns `refused` when the
+// ownership check fails — callers treat this as a hard failure so the operation is not silently
+// skipped (joshuafolkken/kit#2114).
+async function apply_carry(
+	ctx: MergeContext,
+	change: CarryChange | undefined,
+): Promise<ApplyCarryResult> {
+	const record = await read_record()
+
+	if (record === undefined) return { kind: 'none' }
+
+	if (change === undefined) return { kind: 'applied', carry: record.carry }
+
+	if (run_carry.is_count_refused(record.carry, ctx.owner)) {
+		return { kind: 'refused', carry: record.carry }
+	}
+
+	return { kind: 'applied', carry: run_carry.apply_change(record.target, record.carry, change) }
+}
+
+// The carry record when this session may not act on it — the same ownership guard `apply_carry` asks —
+// or `undefined`. Asked before an action that counts nothing, like the cut fallback's relaunch, so a
+// stray session is refused rather than relaunching a lane it does not own (joshuafolkken/kit#2484).
+async function refused_carry(ctx: MergeContext): Promise<RunCarry | undefined> {
+	const record = await read_record()
+
+	if (record === undefined || !run_carry.is_count_refused(record.carry, ctx.owner)) return undefined
+
+	return record.carry
+}
+
+async function sync_main(): Promise<void> {
+	const result = await josh(['main:sync'])
+
+	if (result.code !== 0) throw new Error(`main:sync failed: ${result.out}`)
+}
+
+async function close_lane(child: string): Promise<void> {
+	await josh(['lane:close', child])
+}
+
+function preserved_comment(message: string): string {
+	return [
+		'The lane held uncommitted work when `run:merge` closed it, so it was stashed before the close:',
+		`- recover with \`pnpm josh stash:pop "${message}"\``,
+	].join('\n')
+}
+
+async function stash_work(child: string, directory: string): Promise<void> {
+	const message = git_stash.work_message(child, LANE_CLOSE_OCCASION)
+
+	await git_stash.push(message, directory)
+	await git_gh_issue_write.issue_try_comment(child, preserved_comment(message))
+}
+
+// Stash whatever the lane still holds uncommitted before its tree is removed (joshuafolkken/kit#2476):
+// `lane:close` deletes by force, and a merged child that had popped its parked work and then read
+// `already-done` left that work nowhere else. The stash stack outlives the tree, so the push is the copy.
+// Returns whether closing is safe — `false` when the tree could not be read or pushed, so it is left
+// rather than lost. A directory with no `.git` is no work tree — the remnant of an interrupted close —
+// and holds nothing git could keep, so it is closed rather than stranded behind a status that fails.
+async function preserve_uncommitted(child: string): Promise<boolean> {
+	const lane = await lane_close.resolve_lane(child)
+	const { directory } = lane.targets
+
+	if (!existsSync(path.join(directory, GIT_ENTRY))) return true
+
+	try {
+		if (await git_stash.has_changes(directory)) await stash_work(child, directory)
+
+		return true
+	} catch {
+		console.error(`#${child}: uncommitted work could not be stashed — lane left at ${directory}`)
+
+		return false
+	}
+}
+
+// The progress comment is a human-readable mirror of the carry record, so it is best-effort and only
+// where a named epic has a body to carry it — a pure backlog run keeps the record alone.
+async function post_counters(ctx: MergeContext, carry: RunCarry | undefined): Promise<void> {
+	if (carry === undefined || ctx.epic === undefined) return
+
+	await git_gh_issue_write.issue_try_comment(ctx.epic, run_merge.counters_comment(carry))
+}
+
+// A merged child: count the merge (which resets the failure streak), return to the default branch,
+// stash any uncommitted work the lane still holds and close it, and mirror the counters onto the epic. Returns the carry when the ownership check
+// fails — the caller treats a non-undefined return as a hard refusal and must not offer a next child
+// (joshuafolkken/kit#2114). Returns `undefined` on success.
+async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
+	const refused = await refused_carry(ctx)
+
+	if (refused !== undefined) return refused
+
+	await sync_main()
+	const result = await apply_carry(ctx, {
+		...run_merge.change_of('merged'),
+		merged_issue: Number(ctx.child),
+	})
+
+	if (result.kind === 'refused') return result.carry
+
+	if (await preserve_uncommitted(ctx.child)) await close_lane(ctx.child)
+	await post_counters(ctx, result.kind === 'applied' ? result.carry : undefined)
+
+	return undefined
+}
+
+// A stale label removal must not fail the run, so a failed removal is swallowed exactly as the
+// `|| true` in the hand-written procedure did.
+async function remove_in_progress(child: string): Promise<void> {
+	try {
+		await git_gh_issue_write.issue_remove_label(child, IN_PROGRESS_LABEL)
+	} catch {
+		// A stale label may already be gone; a failed removal must not fail the run.
+	}
+}
+
+// A failed child: count the failure, end whatever of its process is still running (a child judged
+// abandoned that hung on a wait loop would otherwise answer the pgrep liveness check `alive` for its
+// issue number forever, joshuafolkken/kit#2421), drop the stale `in-progress`, and park it with
+// `needs-decision` so the next offer does not hand the same child straight back. Returns the record
+// so the caller can read the streak against the guard. Returns `is_refused: true` without touching labels when the
+// carry record rejected the count (joshuafolkken/kit#2114).
+async function do_failed(ctx: MergeContext): Promise<FailedResult> {
+	const result = await apply_carry(ctx, run_merge.change_of('failed'))
+
+	if (result.kind === 'refused') return { carry: result.carry, is_parked: false, is_refused: true }
+
+	const carry = result.kind === 'applied' ? result.carry : undefined
+
+	lane_reap.reap_child(ctx.child)
+	await remove_in_progress(ctx.child)
+	const is_parked = await git_gh_issue_write.issue_add_label(ctx.child, NEEDS_DECISION_LABEL)
+
+	return { carry, is_parked, is_refused: false }
+}
+
+// The outcome of counting an outage: the record to read the streak against, and whether the count was
+// refused because this session does not own the budget (joshuafolkken/kit#2240).
+interface OutageResult {
+	carry: RunCarry | undefined
+	is_refused: boolean
+}
+
+// An API-outage child: count the outage into its own streak, end any process it left — before the
+// re-dispatch launches a second one matching the same pattern (joshuafolkken/kit#2421) — and drop the
+// stale `in-progress` so the child is offerable again, but **do not** park it with `needs-decision` — the environment failed, not
+// the child, so it is re-dispatchable in the same run (joshuafolkken/kit#2240). Returns the record so
+// the caller can read the outage streak against its guard. Returns `is_refused: true` without touching
+// labels when the carry record rejected the count (joshuafolkken/kit#2114).
+async function do_outage(ctx: MergeContext): Promise<OutageResult> {
+	const result = await apply_carry(ctx, run_merge.change_of('outage'))
+
+	if (result.kind === 'refused') return { carry: result.carry, is_refused: true }
+
+	lane_reap.reap_child(ctx.child)
+	await remove_in_progress(ctx.child)
+
+	return { carry: result.kind === 'applied' ? result.carry : undefined, is_refused: false }
+}
+
+interface RelaunchableCut {
+	lane: LaneInfo
+	target: string
+	cut: RunCut
+}
+
+// The lane's cut the fallback may relaunch, or `undefined` (joshuafolkken/kit#2484). An OpenAI lane is
+// left out: its supervisor, not this command, starts the process after a standing cut.
+async function relaunchable_lane(child: string): Promise<LaneInfo | undefined> {
+	const lane = await lane_registry.find_open_lane(child)
+
+	return lane === undefined || lane_relaunch.is_openai_lane(lane) ? undefined : lane
+}
+
+async function relaunchable_cut(child: string): Promise<RelaunchableCut | undefined> {
+	const lane = await relaunchable_lane(child)
+
+	if (lane === undefined) return undefined
+
+	const carried = run_cut.lane_cut_sync(lane.directory)
+
+	if (carried === undefined || !run_cut.is_relaunchable(carried.cut, child)) return undefined
+
+	return { lane, ...carried }
+}
+
+async function has_resumable_cut(child: string): Promise<boolean> {
+	return (await relaunchable_cut(child)) !== undefined
+}
+
+// **The cutting child launches its own successor; this is only the fallback** (joshuafolkken/kit#2484).
+// `lane:await` wakes the parent once every process of the lane has gone, so a cut still unadopted then
+// means the successor never took it over. It is relaunched through the same `lane_relaunch` the cut uses,
+// once per cut — the record is marked first, so a second unadopted return is parked instead. Returns
+// whether a successor was started.
+async function resume_cut(child: string): Promise<boolean> {
+	const found = await relaunchable_cut(child)
+
+	if (found === undefined || !run_cut.mark_merge_relaunched(found.target, found.cut)) return false
+
+	const result = lane_relaunch.resume(found.lane, found.cut.phase, (note) => {
+		console.error(note)
+	})
+
+	return result.kind === 'launched'
+}
+
+// The hand-off check, asked at a merge alone. A subprocess that cannot measure exits non-zero, which
+// is read as `over` — "could not measure" is never "still cheap".
+async function is_over_budget(over: number): Promise<boolean> {
+	const result = await josh(['cost', '--over', String(over)])
+
+	return result.code !== 0 || result.out === OVER
+}
+
+// The next offer: one issue number per line up to the free lanes, or a verdict token, exactly as the
+// parent read it. `--lanes` needs `--repo`, so the epic form is used only where both are present.
+async function ask_next(ctx: MergeContext): Promise<string> {
+	if (ctx.epic === undefined || ctx.repo === undefined) {
+		const backlog = await josh(['backlog:next'])
+
+		return backlog.out
+	}
+
+	const offer = await josh(['epic:next', ctx.epic, REPO_FLAG, ctx.repo, LANES])
+
+	return offer.out
+}
+
+const run_merge_steps = {
+	apply_carry,
+	ask_next,
+	do_failed,
+	do_merged,
+	do_outage,
+	has_resumable_cut,
+	is_over_budget,
+	refused_carry,
+	resume_cut,
+}
+
+export type { MergeContext, OutageResult }
+export { run_merge_steps }

package/scripts/run/run-merge.ts

@@ -0,0 +1,158 @@
+import {
+	ALREADY_DONE_LABEL,
+	EPIC_LABEL,
+	has_label_name,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/git/issue-labels'
+import type { IssueState } from '#scripts/issue/issue-state'
+import type { CarryChange, RunCarry } from './run-carry'
+
+// joshuafolkken/kit#2024: a `backlogrun` merge event was two parent turns — a reading turn and an
+// acting turn — spent at the session whose context is largest and whose per-turn cost is highest.
+// This is the pure core of the one composite command that collapses it: the parent calls
+// `run:merge <N>` once at a child's return and reads back the next child number, or a control verdict.
+//
+// Everything here is pure — the classification of the returned child, the counter change that outcome
+// implies, the consecutive-failure guard, and the progress-comment text generated from the
+// single-source carry record. The side effects (`main:sync`, `lane:close`, the comment write, the
+// label edits, `epic:next` / `backlog:next`) are the CLI's, so the branches this file decides are
+// unit-tested without a network — `merged`, `parked`, `failed`, `human-review`, `unresolved`.
+
+const CLOSED_STATE = 'CLOSED'
+// Three failures in a row stop the run — the figure `backlogrun-progress.md` states in prose. A merge
+// resets the streak (`run-carry.ts` → `next_failures`), so the guard trips only on an environment
+// failing every child it is handed rather than on failures scattered across a long run.
+const CONSECUTIVE_FAILURE_LIMIT = 3
+// Three API outages in a row stop the run too (joshuafolkken/kit#2240) — the same shape as the failure
+// guard, over its own streak. An outage is a child that could not reach the API, so a run of them is
+// the environment being down; stopping is what keeps the run from re-dispatching into a dead API
+// forever. A merge or a genuine child failure resets it (`run-carry.ts` → `next_outages`).
+const CONSECUTIVE_OUTAGE_LIMIT = 3
+const ONE = 1
+
+// What a returned child turned out to be, decided from its GitHub state and — for the failed case
+// alone — the exit record.
+// - `merged`      — CLOSED; the child finished and its pull request merged.
+// - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (SKILL.md → §2z).
+// - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
+// - `split`       — OPEN and carrying `epic`; its work was divided into new children.
+// - `outage`      — OPEN and carrying neither, but the exit record shows it could not reach the API; not
+//                   the child's failure, so it is re-dispatchable and uncounted against the failure guard
+//                   (joshuafolkken/kit#2240).
+// - `cut`         — OPEN and carrying neither, but its lane holds a declared cut no successor adopted;
+//                   the child ended its session on purpose, so it is resumed rather than parked and
+//                   counts nothing (joshuafolkken/kit#2484).
+// - `failed`      — OPEN and carrying neither, and not an outage; the child did not finish.
+// - `unresolved`  — the state could not be read; re-read before deciding.
+type ChildOutcome =
+	'merged' | 'human-review' | 'parked' | 'split' | 'cut' | 'outage' | 'failed' | 'unresolved'
+
+// What the CLI read beside the GitHub state: whether the exit record is an API outage, and whether the
+// lane holds a cut its successor never adopted.
+interface EndingSignals {
+	is_outage: boolean
+	is_cut: boolean
+}
+
+const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
+
+function is_closed(state: IssueState): boolean {
+	return state.state.toUpperCase() === CLOSED_STATE
+}
+
+// A parked child is one a person still owns: it stopped for a decision (`needs-decision`) or it was
+// found already merged (`already-done`). Either way it is left alone and not counted as a failure.
+const PARK_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
+
+function is_parked(state: IssueState): boolean {
+	return PARK_LABELS.some((label) => has_label_name(state.labels, label))
+}
+
+// **CLOSED means merged, whatever labels it carries** — a child that finished and merged keeps the
+// `needs-human-review` a person put on it, so that label is read only on an OPEN child
+// (`backlogrun-progress.md` → "Running a named epic's children").
+// An OPEN, unparked child that is not waiting on a person: a declared cut is resumed
+// (joshuafolkken/kit#2484), and it is read before the outage so a cut whose process then lost the API is
+// still resumed from its record; an OPEN, unparked child that could not reach the API is an `outage`,
+// not a `failed` (joshuafolkken/kit#2240).
+function unfinished_outcome(signals: EndingSignals): ChildOutcome {
+	if (signals.is_cut) return 'cut'
+
+	return signals.is_outage ? 'outage' : 'failed'
+}
+
+function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
+	if (state.is_human_review) return 'human-review'
+
+	if (has_label_name(state.labels, EPIC_LABEL)) return 'split'
+
+	if (is_parked(state)) return 'parked'
+
+	return unfinished_outcome(signals)
+}
+
+// The signals are read by the CLI and matter only for an OPEN child — a CLOSED child is merged
+// regardless of how the process exited.
+function classify_child(
+	state: IssueState | undefined,
+	signals: EndingSignals = NO_SIGNALS,
+): ChildOutcome {
+	if (state === undefined) return 'unresolved'
+
+	if (is_closed(state)) return 'merged'
+
+	return open_outcome(state, signals)
+}
+
+// The counter change a child's outcome implies. A merge counts a merge (which resets the failure
+// streak); a failure counts a failure; a split, parked or human-review child counts nothing — a decision
+// waiting on a person is not the environment failing — and `undefined` says the carry record is left
+// untouched.
+function change_of(outcome: ChildOutcome): CarryChange | undefined {
+	if (outcome === 'merged') return { merged: ONE }
+
+	if (outcome === 'failed') return { failures: ONE }
+
+	if (outcome === 'outage') return { outages: ONE }
+
+	return undefined
+}
+
+function is_guard_tripped(failures: number): boolean {
+	return failures >= CONSECUTIVE_FAILURE_LIMIT
+}
+
+// The outage guard, over its own streak (joshuafolkken/kit#2240). Same shape as the failure guard: a
+// run of consecutive outages is the environment being down, so the run stops rather than re-dispatching.
+function is_outage_guard_tripped(outages: number): boolean {
+	return outages >= CONSECUTIVE_OUTAGE_LIMIT
+}
+
+// The progress comment, generated from the single-source carry record so the counters live in one
+// place and this text is derived rather than a second copy kept alongside it (joshuafolkken/kit#2024).
+// It is script-emitted, so it stays English while the run's session-facing prose follows
+// `JOSH_SESSION_LANG`.
+function counters_comment(carry: RunCarry): string {
+	return [
+		'Run progress (generated from the carry record):',
+		`- started: ${carry.started_at}`,
+		`- merged: ${String(carry.merged)}`,
+		`- filed: ${String(carry.filed)}`,
+		`- consecutive failures: ${String(carry.failures)}`,
+		`- consecutive outages: ${String(carry.outages)}`,
+		`- cuts crossed: ${String(carry.cuts)}`,
+	].join('\n')
+}
+
+const run_merge = {
+	CONSECUTIVE_FAILURE_LIMIT,
+	CONSECUTIVE_OUTAGE_LIMIT,
+	change_of,
+	classify_child,
+	counters_comment,
+	is_guard_tripped,
+	is_outage_guard_tripped,
+}
+
+export type { ChildOutcome, EndingSignals }
+export { run_merge }

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_next } from './run-next'
+import { run_prep_cli } from './run-prep-cli'
+
+// `josh run:next <N>` — print the next step a `fullrun` takes, from the run's state
+// (joshuafolkken/kit#2188). It reads exactly what `run:prep` reads — the issue state, the
+// `human_review` line and the dependency scope — by calling `run:prep`'s own gather, so the two never
+// answer from different facts, and hands the assembled parts to the state → step mapping in
+// `run-next.ts`.
+//
+// **It is the consumer `run:prep` was built to have.** joshuafolkken/kit#1978 bundled the reads;
+// joshuafolkken/kit#2165 added the read-only glance; this one prints the decision those reads support,
+// which is the trim epic #2166 is after — prose a reader interprets replaced by a computed answer.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh run:next <issue-number>'
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = run_prep_cli.parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reads = await run_prep_cli.gather(issue_number)
+	const parts = run_prep_cli.to_parts(issue_number, reads)
+
+	console.info(run_next.format_report(parts))
+
+	// A state that could not be read is a non-zero exit, exactly as `run:prep` exits on the same
+	// failure, so a bundle missing its state is never read as a confident "implement".
+	return parts.state === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_next_cli = { USAGE, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_next_cli }

package/scripts/run/run-next.ts

@@ -0,0 +1,80 @@
+import type { PrepParts } from './run-prep'
+import { run_step, type PreVerdict } from './run-step'
+
+// `josh run:next <N>` — the next step a `fullrun` takes, printed from the run's state
+// (joshuafolkken/kit#2188). It is the foundation the epic #2166 rests on: the entry read is trimmed by
+// replacing prose that a reader has to interpret with a command that answers "what now" from the same
+// state `run:prep` already gathered, so the answer is computed rather than judged.
+//
+// **It is now the degenerate form of `run:step`** (joshuafolkken/kit#2248). `run:step` computes a run's
+// position from the event stream, the carry record and the issue state; a `fullrun` with nothing emitted
+// yet is at its pre-implementation position, which is exactly what this prints. The state → step mapping
+// lives once, in `run-step.ts`'s `pre_verdict`, and this maps each verdict to the prose sentence a
+// reader expects — so there is no second implementation of the mapping.
+
+const ALREADY_DONE_STEP =
+	'Issue is CLOSED — nothing to run. Verify it against merged code before starting.'
+const KEEP_WORK_STEP =
+	'Issue is CLOSED but this lane holds uncommitted work — stash it with `git stash push -u -m "<N>: uncommitted work at already-done"` before ending.'
+const LATEST_STEP =
+	'Update dependencies first (latest: required), load the dependency-update skill, then implement.'
+const HUMAN_REVIEW_STEP =
+	'Implement and run the verification gate, then STOP before the commit (needs-human-review).'
+const IMPLEMENT_STEP = 'Implement, then run the verification gate (refactor, gate, /code-review).'
+const UNKNOWN_STEP =
+	'State could not be read — resolve the failure in run:prep before deciding the next step.'
+
+// The prose sentence for each pre-implementation verdict `run:step` computes. The verdict set is
+// `run-step.ts`'s, so a new position can never be printed here without a sentence to print it with.
+const STEP_OF: Record<PreVerdict, string> = {
+	'already-done': ALREADY_DONE_STEP,
+	'human-review': HUMAN_REVIEW_STEP,
+	implement: IMPLEMENT_STEP,
+	'keep-work': KEEP_WORK_STEP,
+	unknown: UNKNOWN_STEP,
+	'update-deps': LATEST_STEP,
+}
+
+// The four facts a step is keyed on, lifted off `PrepParts` so the mapping is a pure function of state
+// and the CLI does the reading. `state` is `undefined` exactly when `run:prep` could not read it.
+interface NextInput {
+	state: string | undefined
+	is_human_review: boolean
+	latest_scope: string
+	has_changes: boolean
+}
+
+function to_input(parts: PrepParts): NextInput {
+	return {
+		state: parts.state?.state,
+		is_human_review: parts.state?.is_human_review ?? false,
+		latest_scope: parts.latest_scope,
+		has_changes: parts.has_changes,
+	}
+}
+
+// The prose for the pre-implementation position `run:step` computes — the degenerate case where the
+// run has emitted no event yet. The ordering of the guards is `run-step.ts`'s `pre_verdict`, so the two
+// never disagree about which fact wins.
+function next_step(input: NextInput): string {
+	return STEP_OF[run_step.pre_verdict(input)]
+}
+
+function format_report(parts: PrepParts): string {
+	return next_step(to_input(parts))
+}
+
+const run_next = {
+	ALREADY_DONE_STEP,
+	HUMAN_REVIEW_STEP,
+	IMPLEMENT_STEP,
+	KEEP_WORK_STEP,
+	LATEST_STEP,
+	UNKNOWN_STEP,
+	format_report,
+	next_step,
+	to_input,
+}
+
+export type { NextInput }
+export { run_next }