@joshuafolkken/kit 1.1136.0 → 1.1178.0

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

@@ -60,7 +60,7 @@ const {
 } = run_cut_report
 
 // **The pre-gate cut is conditional on the same statistic the implementation-phase cut reads**
-// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the recent `RECENT_REQUEST_WINDOW`
+// (joshuafolkken/kit#2312). `cost_cli.session_verdict` prices the newest request
 // against `CONTEXT_CUT_THRESHOLD`, so no second threshold is introduced — an `under` session skips the
 // cut, and an unmeasurable one keeps the old unconditional cut as the safety net joshuafolkken/kit#1933
 // relies on. Only the pre-gate phase is checked here; the implementation-phase caller gates its own

package/scripts/run/run-cut-handoff.ts

@@ -41,6 +41,22 @@ const UNTOUCHED_LABEL = 'Deliberately untouched'
 const INSTRUCTION_LABEL = 'Instruction (verbatim)'
 const EMPTY_LIST_NOTE = '(none)'
 
+type HandoffKey = keyof Handoff
+
+function describe_key(key: HandoffKey): string {
+	const value = handoff_schema.shape[key] instanceof z.ZodArray ? '["…"]' : '"…"'
+
+	return `"${key}": ${value}`
+}
+
+// The shape a handoff file must have, derived from `handoff_schema` so the refusal that asks for the file
+// and the error that rejects it can never name a key the parser does not read (joshuafolkken/kit#3195).
+// A refusal that listed the four items in prose was answered with Markdown, which `parse_handoff` rejects.
+const HANDOFF_FORMAT = `a JSON object {${handoff_schema
+	.keyof()
+	.options.map((key) => describe_key(key))
+	.join(', ')}}`
+
 function parse_handoff(raw: string): Handoff | undefined {
 	try {
 		const parsed = handoff_schema.safeParse(JSON.parse(raw))
@@ -84,7 +100,10 @@ function load_handoff(handoff_path: string | undefined, max_bytes: number): Hand
 	const handoff = read_handoff_file(handoff_path)
 
 	if (handoff === undefined) {
-		return { kind: 'bad', note: `--handoff ${handoff_path} is not a readable handoff file` }
+		return {
+			kind: 'bad',
+			note: `--handoff ${handoff_path} is not a readable handoff file — write ${HANDOFF_FORMAT}`,
+		}
 	}
 
 	if (!is_within_bound(handoff, max_bytes)) {
@@ -114,6 +133,7 @@ function describe_handoff(handoff: Handoff): string {
 }
 
 const run_cut_handoff = {
+	HANDOFF_FORMAT,
 	describe_handoff,
 	handoff_schema,
 	is_complete_handoff,

package/scripts/run/run-cut-report.ts

@@ -14,7 +14,7 @@ const RESUME_VERDICT = 'resume'
 // re-reading the record.
 const RESUME_IMPL_VERDICT = 'resume-impl'
 const FRESH_VERDICT = 'fresh'
-// The recent-window context is under the shared cut threshold, so the pre-gate cut was not worth its
+// The current context is under the shared cut threshold, so the pre-gate cut was not worth its
 // resume and nothing was cut (joshuafolkken/kit#2312). A benign, non-failing answer: the run carries
 // on to the gate itself, exactly as `not-a-lane` does.
 const UNDER_THRESHOLD_VERDICT = 'under-threshold'
@@ -111,7 +111,7 @@ function refuse_unready(state: CutState): number {
 // relaunch costs more than it saves; the current process carries the run on to the gate uncut.
 function report_under_threshold(): number {
 	console.error(
-		'The recent-window context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
+		'The current context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
 	)
 
 	return report(UNDER_THRESHOLD_VERDICT, SUCCESS_EXIT_CODE)

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-cli.ts

@@ -7,6 +7,7 @@ import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
 import { run_ship_next } from './run-ship-next'
+import { run_ship_pre_detach } from './run-ship-pre-detach'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
@@ -171,8 +172,9 @@ function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
 
 async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
 	const result = await step.run(args, state)
+	const section = { header: step.header, body: result.out, code: result.code }
 
-	return { header: step.header, body: result.out, code: result.code }
+	return result.conflicts === undefined ? section : { ...section, conflicts: result.conflicts }
 }
 
 async function emit_phase(args: ShipArguments, stage: Stage, phase: Phase): Promise<void> {
@@ -249,7 +251,14 @@ async function stopped(
 	stage: Stage,
 ): Promise<ReadonlyArray<ShipSection>> {
 	if (run_ship_detach.is_supervised()) {
-		await run_ship_return.return_control(args.number, stage, run_ship_next.resume_of(args))
+		const conflicts = sections.at(-1)?.conflicts
+		const resume = run_ship_next.resume_of(args)
+
+		await run_ship_return.return_control(
+			args.number,
+			stage,
+			conflicts === undefined ? resume : { ...resume, conflicts },
+		)
 	}
 
 	return sections
@@ -324,14 +333,26 @@ function should_detach(args: ShipArguments): boolean {
 // joshuafolkken/kit#2966: the preflight is deterministic and fast, so it runs here, in the agent's own
 // turn, before the hand-off — a stop it finds is fixed by the same session instead of relaunching one
 // from the supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself.
+// joshuafolkken/kit#3222: the type check and the document tests follow it here for the same reason; they
+// are not a stage, so the supervisor's gate runs them again rather than passing over them.
+async function pre_detach_sections(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
+	const preflight = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+	if (preflight.code !== SUCCESS_EXIT_CODE) return [preflight]
+
+	const result = await run_ship_pre_detach.checks()
+
+	return [preflight, { header: run_ship.PRE_DETACH_HEADER, body: result.out, code: result.code }]
+}
+
 async function detach_after_preflight(args: ShipArguments): Promise<number> {
-	const section = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+	const sections = await pre_detach_sections(args)
+	const code = run_ship.exit_code(sections)
 
-	if (section.code === SUCCESS_EXIT_CODE) return await detach(args)
+	if (code === SUCCESS_EXIT_CODE) return await detach(args)
 
-	console.info(run_ship.format_report([section]))
+	console.info(run_ship.format_report(sections))
 
-	return run_ship.exit_code([section])
+	return code
 }
 
 async function supervised_repository(): Promise<string | undefined> {

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

@@ -42,6 +42,8 @@ interface ShipResume {
 	title: string
 	flags: ReadonlyArray<string>
 	is_review: boolean
+	// The paths a merge of the default branch left unmerged (joshuafolkken/kit#3221).
+	conflicts?: ReadonlyArray<string>
 }
 
 // Single quotes, so a `$` or a backtick in a title is never expanded by the shell that runs it.
@@ -90,14 +92,25 @@ const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
 	[STAGE.PREFLIGHT]: detach_as_started,
 	[STAGE.REVIEW]: detach_as_started,
 	[STAGE.GATE]: detach_as_started,
+	[STAGE.SYNC]: detach_as_started,
 	[STAGE.COMMIT]: detach_as_started,
 	[STAGE.ROUND_TWO]: detach_again,
 	[STAGE.FOLLOWUP]: detach_again,
 	[STAGE.REPORT]: detach_again,
 }
 
+// A conflict names its paths (joshuafolkken/kit#3221), so the resumed session resolves them without
+// reading the report or asking git which files are unmerged.
+function conflict_step(conflicts: ReadonlyArray<string>): string {
+	return `Resolve the conflict with origin/main in ${conflicts.join(', ')} (the merge is left in progress: remove the conflict markers in those files), then`
+}
+
 // Two lines' worth: read the stopped report, then the one command that resumes after the fix.
 function next_step(issue: string, stage: Stage, resume: ShipResume): string {
+	const conflicts = resume.conflicts ?? []
+
+	if (conflicts.length > 0) return `${conflict_step(conflicts)} ${AFTER_FIX[stage](resume)}`
+
 	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure, then ${AFTER_FIX[stage](resume)}`
 }
 

package/scripts/run/run-ship-pre-detach.ts

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { type_check_step } from '#scripts/gate/type-check-step'
+import type { JoshResult } from '#scripts/josh/josh-run'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+
+// The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight and before
+// the hand-off (joshuafolkken/kit#3222). In one measured backlogrun about 7 of 31 lane resumes were a
+// gate failure first seen after the detach — a type error in a file the related-only checks never
+// touched, or a document test (a SKILL.md pointer, a byte budget, the command list) that only the full
+// suite runs — each paid for with a relaunched session. These two answer in seconds, so the same
+// session fixes what they find and ships again. **Nothing moves out of the gate**: the supervised gate
+// stage still runs every check, these included.
+//
+// The test targets are the directories those resumes failed in. A consumer has none of them, so only
+// the ones present run, and a consumer meets the type check alone.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const SECTION_SEPARATOR = '\n\n'
+const PASSED = 'type check and document tests passed'
+const DOCUMENT_TEST_TARGETS: ReadonlyArray<string> = [
+	'scripts/document',
+	'scripts/claude',
+	'scripts/rules',
+	'scripts/josh/josh-command-map.test.ts',
+]
+// A present directory need not hold a test the project's Vitest includes — a consumer's own
+// `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
+const DOCUMENT_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+
+function present_targets(directory: string): ReadonlyArray<string> {
+	return DOCUMENT_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
+}
+
+async function command_lists(directory: string): Promise<Array<ReadonlyArray<string>>> {
+	const type_check = await type_check_step.resolve_type_check_args(directory)
+	const targets = present_targets(directory)
+
+	return targets.length === 0 ? [type_check] : [type_check, [...DOCUMENT_TEST_COMMAND, ...targets]]
+}
+
+async function run_in(
+	directory: string,
+	list: ReadonlyArray<string>,
+): Promise<BufferedProcessResult> {
+	return await buffered_process.run_buffered_process(list, { cwd: directory })
+}
+
+// Both run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
+async function checks(directory: string = process.cwd()): Promise<JoshResult> {
+	const lists = await command_lists(directory)
+	const results = await Promise.all(lists.map(async (list) => await run_in(directory, list)))
+	const failed = results.filter((result) => buffered_process.is_process_failed(result))
+
+	if (failed.length === 0) return { code: SUCCESS_EXIT_CODE, out: PASSED }
+
+	return {
+		code: FAILURE_EXIT_CODE,
+		out: failed.map((result) => result.output.trim()).join(SECTION_SEPARATOR),
+	}
+}
+
+const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, PASSED, checks }
+
+export { run_ship_pre_detach }

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-return.ts

@@ -6,7 +6,7 @@ import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
 import type { ShipResume } from './run-ship-next'
-import type { Stage } from './run-ship-stage'
+import { run_ship_stage, type Stage } from './run-ship-stage'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -28,8 +28,8 @@ const OPENAI_PROVIDER = 'openai'
 
 type ReturnOutcome = 'relaunched' | 'recorded'
 
-function stop_text(issue: string, stage: Stage): string {
-	return `#${issue} ${stage} failed — pnpm josh ship --log ${issue}`
+function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
+	return `#${issue} ${run_ship_stage.stop_reason(stage, resume.conflicts)} failed — pnpm josh ship --log ${issue}`
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {
@@ -53,7 +53,10 @@ async function return_control(
 	stage: Stage,
 	resume: ShipResume,
 ): Promise<ReturnOutcome> {
-	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STOP, stop_text(issue, stage))
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.SHIP_STOP,
+		stop_text(issue, stage, resume),
+	)
 
 	const lane = await lane_to_relaunch(issue)
 

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)
 }