@joshuafolkken/kit 1.1136.0 → 1.1178.0

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-ship-stage.ts

@@ -20,6 +20,7 @@ const STAGE = {
 	PREFLIGHT: 'preflight',
 	REVIEW: 'review',
 	GATE: 'gate',
+	SYNC: 'sync',
 	COMMIT: 'commit',
 	ROUND_TWO: 'round-2',
 	FOLLOWUP: 'followup',
@@ -99,6 +100,9 @@ const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => bo
 	// the recorded round, and only a commit pins the tree that round read.
 	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
 	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
+	// The merge of the default branch before the commit (joshuafolkken/kit#3221): once committed, a
+	// conflicting pull request is the followup's to merge again.
+	[STAGE.SYNC]: (_done, state) => state.is_merged || state.is_committed,
 	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
 	// The round-2 pass (joshuafolkken/kit#2489) reads the pushed fix delta, so its record is honored only
 	// while that push still stands — new work pushed on top reruns it.
@@ -138,6 +142,14 @@ function event_text(issue: string, stage: Stage, phase: Phase): string {
 	return `#${issue} ${stage} ${phase}`
 }
 
+// A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in
+// (joshuafolkken/kit#3221), so the event stream reads the cause without anyone opening the report.
+const CONFLICT = 'conflict'
+
+function stop_reason(stage: Stage, conflicts: ReadonlyArray<string> = []): string {
+	return conflicts.length > 0 ? CONFLICT : stage
+}
+
 const run_ship_stage = {
 	PHASE,
 	STAGE,
@@ -148,6 +160,7 @@ const run_ship_stage = {
 	mark_done,
 	read_done,
 	record_path,
+	stop_reason,
 }
 
 export type { Phase, ShipState, Stage }

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

@@ -4,6 +4,7 @@ import { run_ship_preflight } from './run-ship-preflight'
 import { run_ship_review_steps } from './run-ship-review-steps'
 import { run_ship_scoped } from './run-ship-scoped'
 import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
+import { run_ship_sync, type StepResult } from './run-ship-sync'
 
 // The stages `josh ship` runs, in the order a change ships (joshuafolkken/kit#2398), kept apart from the
 // chaining CLI so the order is read in one place.
@@ -24,7 +25,7 @@ interface ShipArguments {
 interface Step {
 	stage: Stage
 	header: string
-	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
+	run: (args: ShipArguments, state: ShipState) => Promise<StepResult>
 }
 
 const { STAGE } = run_ship_stage
@@ -56,6 +57,13 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 				async () => await josh(['gate']),
 			]),
 	},
+	// joshuafolkken/kit#3221: the default branch merged again right before the commit, so the pull
+	// request opens on a branch that is current; a clean merge goes on without waking anyone.
+	{
+		stage: STAGE.SYNC,
+		header: run_ship.SYNC_HEADER,
+		run: async () => await run_ship_sync.sync_stage(),
+	},
 	{
 		stage: STAGE.COMMIT,
 		header: run_ship.COMMIT_HEADER,
@@ -69,7 +77,7 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.FOLLOWUP,
 		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await josh(['followup', args.title, ...args.notify]),
+		run: async (args) => await run_ship_sync.followup_stage(args.title, args.notify),
 	},
 	{
 		stage: STAGE.REPORT,

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

@@ -0,0 +1,114 @@
+import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
+import { is_merge_conflict } from '#scripts/gh/git-pr-checks-eval'
+import { git_command } from '#scripts/git/git-command'
+import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { error_text } from '#scripts/lib/error-message'
+import { run_ship_scoped } from './run-ship-scoped'
+
+// `josh ship` keeps the branch current with the default branch itself (joshuafolkken/kit#3221). The
+// lane merged it once, before the hand-off, and nothing merged it again while the pull request opened
+// and CI ran — so a default branch that moved meanwhile stopped the followup as `interrupted`, and a
+// relaunched session spent its first turns finding out that the cause was a conflict. Most of those
+// conflicts were not conflicts at all to git: merging the default branch again resolved them.
+//
+// So the merge happens twice more, mechanically: once before the commit (`sync_stage`), and once when
+// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). Only a merge git
+// itself cannot finish stops the ship, and it stops as `conflict`, naming the unmerged paths so the
+// resumed session goes straight to them.
+
+const should_forward_stderr = true
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+// A default branch that keeps moving under a pull request is merged again at most this often per ship;
+// past it the followup failure stands, so a busy default branch cannot hold a ship in a loop.
+const MAX_MERGE_RETRIES = 2
+const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
+const DEFERRED_PREFIX = 'merge deferred to the followup: '
+const CURRENT_SUFFIX = ' brings nothing in'
+
+// A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
+interface StepResult extends JoshResult {
+	conflicts?: ReadonlyArray<string>
+}
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+// A merge that could not even be attempted — a fetch that failed — reads as a refusal: nothing was
+// changed, and the followup still finds a real conflict on GitHub's side.
+async function merge_outcome(): Promise<MergeOutcome> {
+	try {
+		return await main_merge.merge()
+	} catch (error) {
+		return { kind: 'refused', message: error_text.message_of(error) }
+	}
+}
+
+function conflict_result(files: ReadonlyArray<string>, lead: string): StepResult {
+	const out = [lead, CONFLICT_NOTE, ...files].filter((line) => line !== '').join('\n')
+
+	return { code: FAILURE_EXIT_CODE, out, conflicts: files }
+}
+
+// A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
+// touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
+// the tree meets the scoped pair again, so the commit never carries an unchecked merge.
+async function sync_stage(): Promise<StepResult> {
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
+	if (outcome.kind === 'merged') return await run_ship_scoped.scoped_pair()
+
+	const out =
+		outcome.kind === 'current'
+			? `${outcome.branch}${CURRENT_SUFFIX}`
+			: `${DEFERRED_PREFIX}${outcome.message}`
+
+	return { code: SUCCESS_EXIT_CODE, out }
+}
+
+// Any read that fails answers "not conflicting": the followup failure then stands as it was.
+async function is_conflicting(): Promise<boolean> {
+	try {
+		const state = await git_gh_pr_read.pr_get_merge_state(await git_command.branch())
+
+		return is_merge_conflict(state?.merge_state_status)
+	} catch {
+		return false
+	}
+}
+
+// The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
+async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
+	if (!(await is_conflicting())) return failed
+
+	const outcome = await merge_outcome()
+
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, failed.out)
+	if (outcome.kind !== 'merged') return failed
+
+	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+
+	return push.code === SUCCESS_EXIT_CODE ? undefined : push
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	retries = 0,
+): Promise<StepResult> {
+	const result = await josh(['followup', title, ...notify])
+
+	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
+
+	const stop = await merge_again(title, result)
+
+	return stop ?? (await followup_stage(title, notify, retries + 1))
+}
+
+const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
+
+export type { StepResult }
+export { run_ship_sync }

package/scripts/run/run-ship.ts

@@ -10,8 +10,10 @@
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
 const PREFLIGHT_HEADER = '=== preflight ==='
+const PRE_DETACH_HEADER = '=== pre-detach checks ==='
 const REVIEW_HEADER = '=== review ==='
 const GATE_HEADER = '=== gate ==='
+const SYNC_HEADER = '=== sync origin/main ==='
 const COMMIT_HEADER = '=== commit/push/PR ==='
 const ROUND_TWO_HEADER = '=== round-2 review ==='
 const FOLLOWUP_HEADER = '=== followup ==='
@@ -29,6 +31,8 @@ interface ShipSection {
 	header: string
 	body: string
 	code: number
+	// The paths a stopped merge left unmerged (joshuafolkken/kit#3221), handed to the stop prompt.
+	conflicts?: ReadonlyArray<string>
 }
 
 function section_report(section: ShipSection): string {
@@ -65,10 +69,12 @@ const run_ship = {
 	FOLLOWUP_HEADER,
 	GATE_HEADER,
 	PREFLIGHT_HEADER,
+	PRE_DETACH_HEADER,
 	REPORT_HEADER,
 	REVIEW_HEADER,
 	ROUND_TWO_HEADER,
 	SKIPPED_BODY,
+	SYNC_HEADER,
 	STOPPED_PREFIX,
 	exit_code,
 	failed_section,

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

@@ -209,10 +209,16 @@ function log_hint(context: WakeContext): string {
 	return `The output of every session this supervisor started is in ${context.log_target}.`
 }
 
+// The log hint goes ahead of the note: the Telegram length limit cuts the tail, and a long failure note
+// (stdout tail plus stderr tail) would otherwise take the one line that says where to look next.
+function warning_body(stop: LoopStop, body: string, context: WakeContext): string {
+	return [body, log_hint(context), stop.note].filter(Boolean).join('\n')
+}
+
 async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext): Promise<void> {
 	await telegram_notify.warn({
 		issue_title: WARNING_TITLE,
-		body: [body, stop.note, log_hint(context)].filter(Boolean).join('\n'),
+		body: warning_body(stop, body, context),
 		recovery: WARNING_RECOVERY,
 	})
 }
@@ -408,6 +414,7 @@ const run_wake_cli = {
 	USAGE,
 	run,
 	stop_body,
+	warning_body,
 }
 
 if (process.argv[1] === SCRIPT_PATH) await main(process.argv.slice(ARGV_OFFSET))

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

@@ -8,6 +8,8 @@ const FIRST_LINE = 0
 const RESUME_PREFIX = 'resume: '
 const DETAILS_TAIL_LENGTH = 2048
 const TRUNCATION_MARK = '... '
+// The prefix `backlog-drive-cli.ts` gives the exception it catches.
+const ERROR_PREFIX = 'error '
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -37,16 +39,54 @@ function details_tail(details: string): string {
 		: details
 }
 
-function handoff_material(verdict: string, resume: string, details: string): string {
+// **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.
+//
+// **The claim comes first** (joshuafolkken/kit#3238). The supervisor hands the record off before the
+// wake, so until the session adopts it with `--resume` every count it writes — `--merged`, `--done`,
+// the closing `--cut` — is refused as advancing a handed-off budget, and the supervisor, seeing no
+// claim, ends the run as a failed wake.
+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',
+		'stop the run, because the child stopped before its commit for a person (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, invocation: string): string {
+	const found = NEXT_BY_VERDICT.find(([prefix]) => verdict.startsWith(prefix))
+
+	return `\nNext: first claim the carry record with ${run_carry.claim_command(invocation)}, then ${found?.[1] ?? NEXT_DEFAULT}`
+}
+
+function handoff_material(
+	verdict: string,
+	resume: string,
+	invocation: 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, invocation)}${context}`
 }
 
-function driver_result(out: string, read: CarryRead, details = ''): DriveResult {
+function driver_result(
+	out: string,
+	read: CarryRead,
+	invocation: string,
+	details = '',
+): DriveResult {
 	const lines = out.split('\n')
 	const verdict = lines[FIRST_LINE]
 
@@ -57,13 +97,27 @@ function driver_result(out: string, read: CarryRead, details = ''): DriveResult
 		return { kind: 'failed', note: `backlog:drive returned an incomplete result: ${out}` }
 	}
 
-	return { kind: 'judgment', material: handoff_material(verdict, resume, details) }
+	return { kind: 'judgment', material: handoff_material(verdict, resume, invocation, details) }
+}
+
+// **The cause is the driver's stdout `error …` line, so it leads the note** (joshuafolkken/kit#3242).
+// `backlog:drive` prints an exception only to stdout, and its stderr is never empty — every command it
+// ran is there — so reading `err ?? out` dropped the one line that said why. The stderr follows as its
+// tail, for the same reason `details_tail` cuts a judgment's details.
+function cause_of(out: string): string {
+	const errors = out.split('\n').filter((line) => line.startsWith(ERROR_PREFIX))
+
+	return errors.length > 0 ? errors.join('\n') : details_tail(out)
+}
+
+function failure_note(result: JoshResult): string {
+	return [cause_of(result.out), details_tail(result.err ?? '')].filter(Boolean).join('\n')
 }
 
-function read_result(result: JoshResult, target: string): DriveResult {
-	if (result.code !== SUCCESS) return { kind: 'failed', note: result.err ?? result.out }
+function read_result(result: JoshResult, target: string, invocation: string): DriveResult {
+	if (result.code !== SUCCESS) return { kind: 'failed', note: failure_note(result) }
 
-	return driver_result(result.out, run_carry.read_carry(target), result.err)
+	return driver_result(result.out, run_carry.read_carry(target), invocation, result.err)
 }
 
 function claim_record(target: string, invocation: string): boolean {
@@ -87,7 +141,7 @@ async function drive(target: string): Promise<DriveResult> {
 
 	const result = await josh_command.josh_run(args, true)
 
-	return read_result(result, target)
+	return read_result(result, target, read.carry.invocation)
 }
 
 export const run_wake_driver = { drive, driver_args, driver_result }

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.

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

@@ -1,4 +1,5 @@
 import { issue_bug_label } from '#scripts/issue/issue-bug-label'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
 import { z } from 'zod'
 import { test_declared_logic } from './test-declared-logic'
 
@@ -11,7 +12,7 @@ import { test_declared_logic } from './test-declared-logic'
 // that test catches anything — the added and changed tests run against the merge-base, and at least one
 // of them has to fail there.
 
-type RedVerdict = 'red' | 'green' | 'no-test'
+type RedVerdict = 'red' | 'green' | 'no-test' | 'test-only'
 
 // The declaration a bug-fix Issue carries under its background heading, in the same slot as the
 // behavior-change declaration (`behavior-change-lint.ts`). Read from the declaration, never inferred,
@@ -33,6 +34,18 @@ function unit_test_files(paths: ReadonlyArray<string>): Array<string> {
 		.filter((path) => test_declared_logic.is_test_file(path) && path.endsWith(UNIT_TEST_SUFFIX))
 }
 
+// **A change whose every path is a test file has no pre-fix code to run against**
+// (joshuafolkken/kit#3214). The merge-base then runs the same code as HEAD, so its result equals HEAD's
+// and says nothing about the fix. Exempt paths do not count: a document-rule test reads `*.md` and
+// `prompts/` files, so a change to one of those is pre-fix content the test can be red against.
+// Observation ledger paths do not count either way (joshuafolkken/kit#3230): a run commits its own
+// ledger entry, and no test reads it as pre-fix content.
+function is_test_only(paths: ReadonlyArray<string>): boolean {
+	const counted = paths.filter((path) => !observation_ledger.is_ledger_path(path))
+
+	return counted.length > 0 && counted.every((path) => test_declared_logic.is_test_file(path))
+}
+
 // Vitest's JSON report carries one `testResults` entry per file it loaded — a file that failed to load
 // included — and none for a file its config excluded, so this is how many files actually ran. The
 // changed-path count cannot stand in for it: a file the merge-base config does not include runs nothing
@@ -58,7 +71,8 @@ function verdict_for(test_count: number, is_failed: boolean): RedVerdict {
 }
 
 // Only `green` on a declared bug fix is refused. `no-test` is already `josh test:declared`'s refusal
-// when a runtime file changed, and a declared fix that touched only docs has nothing to reproduce.
+// when a runtime file changed, a declared fix that touched only docs has nothing to reproduce, and a
+// `test-only` fix runs the same code on the merge-base as on HEAD.
 function is_refused(body: string, verdict: RedVerdict): boolean {
 	return verdict === 'green' && is_bug_fix(body)
 }
@@ -67,6 +81,7 @@ const test_red_logic = {
 	BUG_DECLARATION_LINE,
 	is_bug_fix,
 	is_refused,
+	is_test_only,
 	ran_file_count,
 	unit_test_files,
 	verdict_for,

package/scripts/test/test-red.ts

@@ -11,7 +11,7 @@ import { execa } from 'execa'
 import { test_red_logic, type RedVerdict } from './test-red-logic'
 
 // `josh test:red` — run the added and changed Vitest files against the pre-fix tree and print `red`,
-// `green` or `no-test` (joshuafolkken/kit#2448).
+// `green`, `no-test` or `test-only` (joshuafolkken/kit#2448).
 //
 // **The pre-fix tree is a detached worktree at the merge-base, never the caller's checkout.** The tests
 // are copied in from the working tree, so what runs is the new test against the old code, and the
@@ -26,7 +26,7 @@ const REPORT_NAME = 'report.json'
 const NODE_MODULES = 'node_modules'
 const VITEST_BIN = path.join(NODE_MODULES, '.bin', 'vitest')
 const USAGE =
-	'Usage: josh test:red — prints red / green / no-test for the changed tests on the merge-base'
+	'Usage: josh test:red — prints red / green / no-test / test-only for the changed tests on the merge-base'
 
 interface RedRun {
 	verdict: RedVerdict
@@ -34,9 +34,7 @@ interface RedRun {
 }
 
 // The changed Vitest files that still exist — a deleted test has nothing to run.
-async function changed_tests(): Promise<Array<string>> {
-	const paths = await changed_paths.read_changed_paths(false)
-
+function changed_tests(paths: ReadonlyArray<string>): Array<string> {
 	return test_red_logic.unit_test_files(paths).filter((file) => existsSync(file))
 }
 
@@ -126,12 +124,15 @@ async function verdict_on(base: string, files: ReadonlyArray<string>): Promise<R
 }
 
 // The verdict over the current checkout. No merge-base (not a repository, no default branch) reads as
-// `no-test` — there is no pre-fix tree to run against, and a guard fails open.
+// `no-test` — there is no pre-fix tree to run against, and a guard fails open. A change whose every path
+// is a test file is `test-only` without a run: the merge-base runs the same code as HEAD.
 async function run(): Promise<RedRun> {
 	const base = await change_base.resolved()
-	const files = await changed_tests()
+	const paths = await changed_paths.read_changed_paths(false)
+	const files = changed_tests(paths)
 
 	if (base === undefined || files.length === 0) return { verdict: 'no-test', files }
+	if (test_red_logic.is_test_only(paths)) return { verdict: 'test-only', files }
 
 	return { verdict: await verdict_on(base, files), files }
 }