@joshuafolkken/kit 1.1136.0 → 1.1166.0

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

@@ -7,6 +7,7 @@ import { run_entry, type EntryParts } from './run-entry'
 import { run_entry_stop } from './run-entry-stop'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold_cli } from './run-hold-cli'
+import { run_label } from './run-label'
 import { run_next } from './run-next'
 import { run_prep } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
@@ -231,6 +232,15 @@ function is_settled(decision: StageDecision): boolean {
 	return decision.is_reached && decision.state !== run_stage.MERGED
 }
 
+// The tree is held and the budget allows the run, so the issue is marked as running before its reads
+// (joshuafolkken/kit#3182) — the label then shows in the `labels:` line the report below carries.
+async function proceed(issue_number: string, hold: string, cost: string): Promise<number> {
+	await run_label.mark(issue_number)
+	const reads = await gather_reads(issue_number)
+
+	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+}
+
 async function claim_run({ issue_number, command }: EntryRequest): Promise<number> {
 	const hold = await claim_hold(issue_number, command)
 
@@ -248,9 +258,7 @@ async function claim_run({ issue_number, command }: EntryRequest): Promise<numbe
 		return await stop_run({ parts, command, reason: BUDGET_REASON, should_release: true })
 	}
 
-	const reads = await gather_reads(issue_number)
-
-	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
+	return await proceed(issue_number, hold, cost)
 }
 
 // A carried cut is asked first, before anything is read (`run:cut --resume`); `kickoff` claims and cuts

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_label } from './run-label'
 import { run_preflight, type PreflightDecision } from './run-preflight'
 import { run_prrun_resume } from './run-prrun-resume'
 import { run_tidy_cli } from './run-tidy-cli'
@@ -267,7 +268,7 @@ function report_unreadable_release(): number {
 // Until then this removed whatever was there, and the `busy` stop message sent a person here to clear
 // a record they had judged stale from outside the run that wrote it — so the guard's own recovery
 // instruction was a way to free a live run's tree, which is the incident it was written after.
-function release(target: string, claimant: string): number {
+function release_record(target: string, claimant: string): number {
 	const read = run_hold.read_hold(target)
 
 	if (read.kind === 'free') return remove_record(target, false)
@@ -279,6 +280,19 @@ function release(target: string, claimant: string): number {
 	return remove_record(target, true)
 }
 
+// **A numbered run's own release takes its `in-progress` marker back off** (joshuafolkken/kit#3182),
+// whether or not a record was still there — the stop that releases is the run ending its hold on the
+// issue. A refused release (another run's record, an unreadable one) touches no label, and an
+// unnumbered run names no issue to touch.
+async function release(target: string, claimant: string): Promise<number> {
+	const code = release_record(target, claimant)
+	const is_own_end = code === SUCCESS_EXIT_CODE && claimant !== run_hold.UNNUMBERED_ISSUE
+
+	if (is_own_end) await run_label.unmark(claimant)
+
+	return code
+}
+
 // The one path that removes a record without matching it, which is why it says what it removed: a
 // record genuinely abandoned by a crashed session has no run left to release it, and the eight-hour
 // expiry alone leaves a dirty tree held until a person acts.
@@ -335,7 +349,7 @@ async function dispatch(request: HoldRequest, target: string, is_linked: boolean
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
 
-	return release(target, request.claimant)
+	return await release(target, request.claimant)
 }
 
 async function answer(request: HoldRequest): Promise<number> {

package/scripts/run/run-label.ts

@@ -0,0 +1,50 @@
+import { git_followup_label } from '#scripts/followup/git-followup-label'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+
+// **The `in-progress` marker belongs to the commands that open and release a run**
+// (joshuafolkken/kit#3182). Every manifest used to spell the label's create, apply and removal as raw
+// `gh api` calls, so each copy was a place the marker could be forgotten; `run:entry` applies it the
+// moment the tree is held and the budget allows the run, and `run:release` takes it back off.
+//
+// **Neither half ever fails the command it rides on.** The hold is the guard and the label only
+// reports it, so a refused write is warned about by name — with the call that finishes it by hand —
+// and the run's own verdict stands.
+
+const MARK_RECOVERY = "gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=in-progress'"
+const UNMARK_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress'
+
+function warn(action: string, issue: string, recovery: string): void {
+	console.warn(`⚠ could not ${action} \`in-progress\` on #${issue} — run by hand: ${recovery}`)
+}
+
+// `issue_add_label` creates the label when the repository lacks it (`lane-dispatch.ts`), so no
+// separate provisioning call is made here.
+async function mark(issue: string): Promise<boolean> {
+	const is_marked = await git_gh_command.issue_add_label(issue, IN_PROGRESS_LABEL)
+
+	if (!is_marked) warn('apply', issue, MARK_RECOVERY)
+
+	return is_marked
+}
+
+// The removal is `followup`'s own — read first, removed only when present, under the stored
+// casing — so an issue that never carried the label is never written to.
+async function unmark(issue: string): Promise<boolean> {
+	try {
+		await git_followup_label.strip_in_progress(issue)
+
+		return true
+	} catch {
+		warn('remove', issue, UNMARK_RECOVERY)
+
+		return false
+	}
+}
+
+const run_label = {
+	mark,
+	unmark,
+}
+
+export { run_label }

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

@@ -48,7 +48,10 @@ interface MergeContext {
 	child: string
 	epic: string | undefined
 	repo: string | undefined
-	over: number
+	// The hand-off threshold, or `undefined` where no AI session owns the loop — the supervisor's
+	// `backlog:drive` has no context to cut, so a merge there is never handed back as `over`
+	// (joshuafolkken/kit#3156).
+	over: number | undefined
 	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
@@ -327,8 +330,10 @@ async function resume_cut(child: string): Promise<boolean> {
 }
 
 // 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> {
+// is read as `over` — "could not measure" is never "still cheap". No threshold is no session to measure.
+async function is_over_budget(over: number | undefined): Promise<boolean> {
+	if (over === undefined) return false
+
 	const result = await josh(['cost', '--over', String(over)])
 
 	return result.code !== 0 || result.out === OVER

package/scripts/run/run-merge.ts

@@ -35,7 +35,7 @@ const ONE = 1
 // - `merged`      — CLOSED; the child finished and its pull request merged. Also an OPEN, unparked
 //                   child a merged pull request's `closes #N` names — GitHub merged it without closing
 //                   the issue (joshuafolkken/kit#2769).
-// - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (SKILL.md → §2z).
+// - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (needs-human-review.md).
 // - `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

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

@@ -8,6 +8,7 @@ import { error_text } from '#scripts/lib/error-message'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_locate } from './run-prep-locate'
+import { run_ship_preflight } from './run-ship-preflight'
 
 // `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
 // (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and
@@ -41,6 +42,7 @@ interface PrepReads {
 	latest: LatestDecision
 	has_changes: boolean
 	locations: string
+	ship_problems: ReadonlyArray<string>
 }
 
 // Exactly one issue number, or the call is refused: `run:prep` prepares one run, and a second number
@@ -91,15 +93,16 @@ async function lane_has_changes(): Promise<boolean> {
 }
 
 async function gather(issue_number: string): Promise<PrepReads> {
-	const [content, state, has_changes] = await Promise.all([
+	const [content, state, has_changes, ship_problems] = await Promise.all([
 		issue_read_cli.read_block(issue_number),
 		issue_state_cli.read_issue(issue_number),
 		lane_has_changes(),
+		run_ship_preflight.ahead(issue_number),
 	])
 	// Located from the body just read, so it waits for that read rather than joining the batch above.
 	const locations = await run_prep_locate.locate(content.kind === 'ok' ? content.block : '')
 
-	return { content, state, latest: latest_decision(), has_changes, locations }
+	return { content, state, latest: latest_decision(), has_changes, locations, ship_problems }
 }
 
 function content_body(issue_number: string, content: BlockRead): string {
@@ -119,6 +122,7 @@ function to_parts(issue_number: string, reads: PrepReads): PrepParts {
 		latest_reason: reads.latest.reason,
 		has_changes: reads.has_changes,
 		locations: reads.locations,
+		ship_problems: reads.ship_problems,
 	}
 }
 

package/scripts/run/run-prep.ts

@@ -24,6 +24,10 @@ const CONTENT_HEADER = '=== issue ==='
 const STATE_HEADER = '=== state ==='
 const LATEST_HEADER = '=== dependency update ==='
 const LOCATIONS_HEADER = '=== code locations ==='
+const SHIP_HEADER = '=== ship preconditions ==='
+const SHIP_MET = 'met — nothing `josh ship` refuses on as the tree stands'
+const SHIP_UNMET =
+	'unmet — `josh ship` will refuse until these are fixed; fix them before the gate:'
 const SECTION_SEPARATOR = '\n\n'
 const LATEST_JOINER = ' — '
 
@@ -41,6 +45,9 @@ interface PrepParts {
 	// Whether a lane child's tree holds uncommitted work — read for the verdict, not printed in the
 	// report (joshuafolkken/kit#2476).
 	has_changes: boolean
+	// What `josh ship` would refuse on as the tree stands — `run_ship_preflight.ahead`
+	// (joshuafolkken/kit#3154).
+	ship_problems: ReadonlyArray<string>
 }
 
 function human_review_value(state: IssueState | undefined): string {
@@ -72,6 +79,12 @@ function section(header: string, body: string): string {
 	return `${header}\n${body}`
 }
 
+function ship_body(problems: ReadonlyArray<string>): string {
+	if (problems.length === 0) return SHIP_MET
+
+	return [SHIP_UNMET, ...problems.map((problem) => `  - ${problem}`)].join('\n')
+}
+
 function format_report(parts: PrepParts): string {
 	return [
 		summary(parts),
@@ -79,6 +92,7 @@ function format_report(parts: PrepParts): string {
 		section(STATE_HEADER, state_body(parts)),
 		section(LATEST_HEADER, `${parts.latest_scope}${LATEST_JOINER}${parts.latest_reason}`),
 		section(LOCATIONS_HEADER, parts.locations),
+		section(SHIP_HEADER, ship_body(parts.ship_problems)),
 	].join(SECTION_SEPARATOR)
 }
 
@@ -86,9 +100,12 @@ const run_prep = {
 	CONTENT_HEADER,
 	LATEST_HEADER,
 	LOCATIONS_HEADER,
+	SHIP_HEADER,
+	SHIP_UNMET,
 	STATE_HEADER,
 	SUMMARY_PREFIX,
 	format_report,
+	ship_body,
 }
 
 export type { PrepParts }

package/scripts/run/run-ship-preflight.ts

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_pr } from '#scripts/gh/git-pr'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_branch } from '#scripts/git/git-branch'
 import { git_preflight } from '#scripts/git/git-preflight'
@@ -22,6 +23,7 @@ import { run_ship_scoped } from './run-ship-scoped'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>.`
+const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section to a file and hand it to josh ship with --body-file <path>, or the ship refuses.`
 
 interface PreflightRequest {
 	title: string
@@ -34,13 +36,20 @@ async function body_text(body_path: string | undefined): Promise<string | undefi
 	return await git_gh_command.pr_get_body(await git_branch.current())
 }
 
-async function evidence_problems(body_path: string | undefined): Promise<Array<string>> {
+// `no_body_problem` answers a runtime change with no body to read at all — no `--body-file` and no open
+// PR, which is every run before its ship opens one.
+async function evidence_problems(
+	body_path: string | undefined,
+	no_body_problem: string = EVIDENCE_PROBLEM,
+): Promise<Array<string>> {
 	const [paths, body] = await Promise.all([
 		changed_paths.read_changed_paths(false),
 		body_text(body_path),
 	])
 
-	return live_evidence.verdict_for(paths, body) === 'required' ? [EVIDENCE_PROBLEM] : []
+	if (live_evidence.verdict_for(paths, body) !== 'required') return []
+
+	return [body === undefined ? no_body_problem : EVIDENCE_PROBLEM]
 }
 
 function refusal(problems: ReadonlyArray<string>): JoshResult {
@@ -81,7 +90,29 @@ async function stage(request: PreflightRequest): Promise<JoshResult> {
 	return scoped.code === SUCCESS_EXIT_CODE ? { code: SUCCESS_EXIT_CODE, out: 'ready' } : scoped
 }
 
-const run_ship_preflight = { EVIDENCE_PROBLEM, stage }
+async function classification_problems(issue_number: string): Promise<Array<string>> {
+	await git_pr.release_classification(issue_number, await git_branch.current())
+
+	return []
+}
+
+// **The same two refusals, asked before the ship rather than by it** (joshuafolkken/kit#3154). In one
+// measured backlogrun 20 of 41 lane `ship` refusals were a missing classification or missing evidence —
+// facts fixed long before the ship, refused at the run's largest context. `run:prep` (and so `run:entry`)
+// and `run:step` print this, so the Issue body and the evidence are met while they are cheap. Nothing
+// here replaces `stage`: the ship and `followup` still refuse on both. Before the PR exists the evidence
+// can only live in the file the ship will be handed, so it is asked for as that file, not reported as a
+// body that already failed.
+async function ahead(issue_number: string): Promise<Array<string>> {
+	const [classification, evidence] = await Promise.all([
+		caught(classification_problems(issue_number)),
+		caught(evidence_problems(undefined, EVIDENCE_PENDING)),
+	])
+
+	return [...classification, ...evidence]
+}
+
+const run_ship_preflight = { EVIDENCE_PENDING, EVIDENCE_PROBLEM, ahead, stage }
 
 export type { PreflightRequest }
 export { run_ship_preflight }

package/scripts/run/run-ship-review-steps.ts

@@ -155,7 +155,7 @@ async function record_and_route(
 	if (recorded.code !== SUCCESS_EXIT_CODE) return recorded
 
 	const outcome = outcome_of(verdict)
-	const out = [...verdict.specs, outcome.note].join('\n')
+	const out = [...verdict.report, outcome.note].join('\n')
 
 	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
 }

package/scripts/run/run-ship-review.ts

@@ -23,6 +23,12 @@ const LINE_SEPARATOR = /\r?\n/u
 const HIGH = 'high'
 const MEDIUM = 'medium'
 const FIXED_PREFIX = 'fixed '
+// What a finding line carries after its spec: one sentence saying what is wrong, so a stopped ship's
+// log tells the resumed lane child the defect rather than only its location (joshuafolkken/kit#3159).
+const DESCRIPTION_SEPARATOR = ' — '
+// Where the spec ends on read: a reviewer that types the dash as `-`, `--` or `–` still ends it there,
+// so its sentence never lands in the ledger's file field.
+const DESCRIPTION_BOUNDARY = / [—–-]{1,2} /u
 
 const VERDICT = {
 	CLEAN: 'clean',
@@ -35,6 +41,7 @@ type ReviewVerdict =
 	| {
 			kind: typeof VERDICT.CLEAN | typeof VERDICT.FIXED | typeof VERDICT.BLOCKING
 			specs: ReadonlyArray<string>
+			report: ReadonlyArray<string>
 	  }
 	| { kind: typeof VERDICT.INVALID; note: string }
 
@@ -49,6 +56,7 @@ interface RoundOutcome {
 interface Finding {
 	spec: string
 	is_fixed: boolean
+	line: string
 }
 
 const MISSING_NOTE = 'the reviewer wrote no findings file — the review did not complete'
@@ -69,7 +77,8 @@ function findings_instruction(findings_path: string, fixed_clause: string): stri
 	const categories = review_finding_ledger.CATEGORIES.join(', ')
 
 	return [
-		`Then write every finding to ${findings_path}, one per line as <category>:<severity>:<file>[:<line>]`,
+		`Then write every finding to ${findings_path}, one per line as`,
+		`<category>:<severity>:<file>[:<line>]${DESCRIPTION_SEPARATOR}<one sentence: what is wrong and why>`,
 		`(category one of ${categories}; severity high, medium or low)${fixed_clause},`,
 		'and an empty file when there is none.',
 	].join(' ')
@@ -99,10 +108,17 @@ function verification_prompt(brief_path: string, findings_path: string): string
 	].join(' ')
 }
 
+// The spec is what `review:record` reads; the description after it travels only in the stage output.
+function spec_of(unmarked: string): string {
+	const end = unmarked.search(DESCRIPTION_BOUNDARY)
+
+	return (end === -1 ? unmarked : unmarked.slice(0, end)).trim()
+}
+
 function finding_of(line: string): Finding {
-	if (!line.startsWith(FIXED_PREFIX)) return { spec: line, is_fixed: false }
+	const is_fixed = line.startsWith(FIXED_PREFIX)
 
-	return { spec: line.slice(FIXED_PREFIX.length).trim(), is_fixed: true }
+	return { spec: spec_of(is_fixed ? line.slice(FIXED_PREFIX.length) : line), is_fixed, line }
 }
 
 function spec_findings(text: string): ReadonlyArray<Finding> {
@@ -133,7 +149,8 @@ function scored_kind(findings: ReadonlyArray<Finding>): ScoredVerdict['kind'] {
 
 // Absent means the reviewer never finished; a line outside the grammar means its verdict cannot be
 // recorded — both stop the ship rather than read as clean. The specs are recorded without the `fixed`
-// mark: a fixed finding was still a finding of that round.
+// mark: a fixed finding was still a finding of that round. The report keeps each line whole — mark and
+// description — for the stage output a resumed lane child reads.
 function read_verdict(text: string | undefined): ReviewVerdict {
 	if (text === undefined) return { kind: VERDICT.INVALID, note: MISSING_NOTE }
 
@@ -144,7 +161,11 @@ function read_verdict(text: string | undefined): ReviewVerdict {
 		return { kind: VERDICT.INVALID, note: `unreadable finding: ${invalid.spec}` }
 	}
 
-	return { kind: scored_kind(findings), specs: findings.map((finding) => finding.spec) }
+	return {
+		kind: scored_kind(findings),
+		specs: findings.map((finding) => finding.spec),
+		report: findings.map((finding) => finding.line),
+	}
 }
 
 // Round 1 passes clean or with every blocking finding fixed in place; round 2 follows the commit.

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

@@ -10,6 +10,7 @@ import { run_carry, type CarryRead } from './run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream } from './run-event-stream'
 import { run_headless } from './run-headless'
+import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
 import { run_step, type StepInput } from './run-step'
@@ -85,14 +86,14 @@ function read_run(
 	}
 }
 
-async function gather(issue_number: string): Promise<StepInput> {
-	const reads = await run_prep_cli.gather(issue_number)
-	const parts = run_prep_cli.to_parts(issue_number, reads)
-	const is_lane_child = lane_child_marker.is_child_of(process.cwd())
-	const run_reads = read_run(await run_carry.repository_directory(), issue_number, is_lane_child)
+interface Gathered {
+	input: StepInput
+	ship_problems: ReadonlyArray<string>
+}
 
+function step_input(parts: PrepParts, run_reads: RunReads, is_lane_child: boolean): StepInput {
 	return {
-		issue_number,
+		issue_number: parts.issue_number,
 		state: parts.state?.state,
 		is_human_review: parts.state?.is_human_review ?? false,
 		latest_scope: parts.latest_scope,
@@ -110,6 +111,15 @@ async function gather(issue_number: string): Promise<StepInput> {
 	}
 }
 
+async function gather(issue_number: string): Promise<Gathered> {
+	const reads = await run_prep_cli.gather(issue_number)
+	const parts = run_prep_cli.to_parts(issue_number, reads)
+	const is_lane_child = lane_child_marker.is_child_of(process.cwd())
+	const run_reads = read_run(await run_carry.repository_directory(), issue_number, is_lane_child)
+
+	return { input: step_input(parts, run_reads, is_lane_child), ship_problems: parts.ship_problems }
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const issue_number = run_prep_cli.parse_number(argv)
 
@@ -119,9 +129,12 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const input = await gather(issue_number)
+	const { input, ship_problems } = await gather(issue_number)
 
 	console.info(run_step.next_action(input).line)
+	// On stderr, so stdout stays the one action line (joshuafolkken/kit#3154): 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))
 
 	// 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.

package/scripts/run/run-wake-driver.ts

@@ -37,13 +37,36 @@ function details_tail(details: string): string {
 		: details
 }
 
+// **The hand-off names its next move, so the woken session never searches the procedure for it**
+// (joshuafolkken/kit#3156). Whatever the branch, the session acts on it and hands the loop back to the
+// supervisor with a cut; only a person's stop ends the run instead.
+const HAND_BACK = 'then hand the loop back with pnpm josh run:carry --cut --owner "$PPID"'
+const NEXT_BY_VERDICT: ReadonlyArray<readonly [string, string]> = [
+	[
+		'retrospective',
+		`run what pnpm josh run:step prints (retrospective.md), close it with pnpm josh run:carry --retrospective --summary "<result>" --owner "$PPID", ${HAND_BACK}`,
+	],
+	[
+		'merge human-review',
+		'the child stopped before its commit for a person; stop the run (needs-human-review.md)',
+	],
+	['epic #', `follow backlogrun-steps.md → "Named issues run first, in order", ${HAND_BACK}`],
+]
+const NEXT_DEFAULT = `act on the result by backlogrun-steps.md → "The loop", ${HAND_BACK}`
+
+function next_move(verdict: string): string {
+	const found = NEXT_BY_VERDICT.find(([prefix]) => verdict.startsWith(prefix))
+
+	return `\nNext: ${found?.[1] ?? NEXT_DEFAULT}`
+}
+
 function handoff_material(verdict: string, resume: string, details: string): string {
 	const context = details === '' ? '' : `\nDetails: ${details_tail(details)}`
 	const epic = verdict.startsWith('epic #')
 		? '\nThe named item is an epic. Follow backlogrun-steps.md named epic procedure; do not launch the epic root as a fullrun child. After all children merge or park, record the root with pnpm josh run:carry --done <epic-number> --owner "$PPID" before continuing to the next named item.'
 		: ''
 
-	return `Driver result: ${verdict}\n${resume}${epic}${context}`
+	return `Driver result: ${verdict}\n${resume}${epic}${next_move(verdict)}${context}`
 }
 
 function driver_result(out: string, read: CarryRead, details = ''): DriveResult {

package/scripts/run/run-wake-session.ts

@@ -29,7 +29,8 @@ import { run_invocation } from './run-invocation'
 //
 // **The waker adds nothing to what may be run.** The argument vector is the constant command plus an
 // invocation rebuilt to say exactly what the record said, and nothing here writes a label: `auto-ok`
-// stays a person's to apply, so a woken session is offered by exactly the rules the first one was. A
+// arrives only through `issue:file`'s default, so a woken session is offered by exactly the rules the
+// first one was. A
 // pool that grew across the seam is `backlogrun-steps.md` → "What one invocation approves", not the
 // waker's doing (joshuafolkken/kit#1675).
 const WAKE_COMMAND = claude_agent_argv.AGENT_COMMAND

package/scripts/test/test-declared-logic.ts

@@ -12,7 +12,7 @@
 // can catch a defect in it; this set keeps documentation *in* because a test could never have caught a
 // prose defect either way. The two answer different questions, so sharing one list would be wrong, not
 // a clone avoided. Here only paths that are mechanically certain to touch no runtime code are exempt —
-// the non-executable config and cosmetic-asset arms of `CLAUDE.md`'s "Non-runtime updates" exception
+// the non-executable config and cosmetic-asset arms of `prompts/testing-guide.md`'s "Non-runtime updates" exception
 // stay `required`, and a person declares that exception in the Step 0 work summary. Under-exempting
 // costs one declared exception; over-exempting ships an untested runtime change. The one widening is
 // the basic profile's manual check below, for files no runner kit has could test.