@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/review/review-brief-cli.ts

@@ -2,15 +2,23 @@
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import { bash_output_cap_reader } from '#scripts/document/bash-output-cap'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { change_base } from '#scripts/git/change-base'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { run_ship_review } from '#scripts/run/run-ship-review'
 import { review_attest } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
+import type { DiffParts } from './review-diff-parts'
+import { review_diff_write } from './review-diff-write'
 import { review_level, type ReviewLevel } from './review-level'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
@@ -134,13 +142,54 @@ function record_round_one(
 // failed to record would hand the review a command that cannot succeed and the run a check that
 // answers `not-required` — the guard gone, silently, which is the shape this whole record exists to
 // remove.
-async function open_contract(): Promise<{ checkout: ReviewCheckout; nonce: string }> {
+//
+// **Whether this is a resume is read first** (joshuafolkken/kit#2945): `record_target` drops the
+// previous nonce's records, so asked afterwards the finished review would always read as absent. The
+// findings file is the ship's, keyed on `PROJECT_ROOT` as the ship keys it; a review run outside the
+// ship writes none, so it never reads as a resume and keeps the whole change.
+//
+// **The narrowing is measured from the tree that review was briefed on**, and only when that record
+// was written by the brief the pointer names: one left by an earlier brief is not the tree the
+// finished review read, so the resume reads the whole change instead.
+function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
+	const { findings } = openai_review_broker.review_paths(PROJECT_ROOT)
+	const briefed = review_stamps.briefed_stamp.read()
+
+	if (briefed === undefined || !review_attest.is_briefed_since(briefed.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	const is_clean =
+		review_attest.is_reviewed_on(checkout, findings, checkout.root) &&
+		run_ship_review.is_clean_round_one(stamp_file.read_stamp_text(findings))
+
+	return is_clean ? briefed : undefined
+}
+
+async function open_contract(): Promise<{
+	checkout: ReviewCheckout
+	nonce: string
+	resumed_from: FileMapStamp | undefined
+}> {
 	const checkout = await review_checkout.read_checkout()
+	const resumed_from = attested_tree(checkout)
 
 	// Keyed on the root git just answered with, never on `process.cwd()`: the check made before the
 	// merge asks git the same question, and the two hash different keys the moment one of them runs
 	// from a subdirectory — a mismatch that would drop the guard with nothing printed.
-	return { checkout, nonce: review_attest.record_target(checkout, checkout.root) }
+	return { checkout, nonce: review_attest.record_target(checkout, checkout.root), resumed_from }
+}
+
+// Retaken on every round-1 brief, after the pointer it pairs with (joshuafolkken/kit#2945). Swallowed:
+// a record that failed to write predates the next pointer, so the resume widens rather than narrows.
+function record_briefed(round: number, tree: Record<string, string>, base?: string): void {
+	if (round !== FIRST_ROUND) return
+
+	try {
+		review_stamps.briefed_stamp.write(tree, undefined, base)
+	} catch {
+		/* no record widens the resume rather than narrowing it */
+	}
 }
 
 interface ComposeRequest {
@@ -151,8 +200,26 @@ interface ComposeRequest {
 	profile: AgentProfile
 }
 
+// **Swallowed, and the brief keeps its target line** (joshuafolkken/kit#2963): parts that could not be
+// written leave the reviewer the whole `git diff` to read, which costs truncated output rather than
+// scope — the direction every failure here falls.
+async function read_diff(
+	root: string,
+	base: string,
+	paths: ReadonlyArray<string>,
+): Promise<{ parts: DiffParts; cap: number } | undefined> {
+	const cap = bash_output_cap_reader.bash_output_cap(root)
+
+	try {
+		return { parts: await review_diff_write.write_parts({ root, base, paths, cap }), cap }
+	} catch {
+		return undefined
+	}
+}
+
 async function compose_brief(request: ComposeRequest): Promise<string> {
 	const { round, paths, tree, base, profile } = request
+	const contract = await open_contract()
 	const stamps = {
 		gate: review_stamps.gate_stamp.read(),
 		in_flight: review_stamps.in_flight_stamp.read(),
@@ -172,7 +239,8 @@ async function compose_brief(request: ComposeRequest): Promise<string> {
 		// the map is stored against is the same one the brief printed (joshuafolkken/kit#1537).
 		base,
 		rubric_path: RUBRIC_PATH,
-		...(await open_contract()),
+		...contract,
+		diff: await read_diff(contract.checkout.root, base, paths),
 	})
 }
 
@@ -252,6 +320,7 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 	if (resolved.kind === 'rejected') return report_error(resolved.note)
 	console.info(await compose_brief({ round, paths, tree, base, profile: resolved.profile }))
 	record_round_one(round, tree, commit)
+	record_briefed(round, tree, commit)
 
 	return 0
 }
@@ -274,15 +343,10 @@ const review_brief_cli = {
 	FIRST_ROUND,
 	format_reason,
 	KEPT_NOTE_PREFIX,
-	kept_note,
-	LEVEL_ONLY_FLAG,
-	main,
 	parse_round,
 	record_round_one,
 	report_error,
 	run,
-	run_level,
-	USAGE,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/review/review-brief.ts

@@ -1,6 +1,7 @@
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
+import { review_diff_parts, type DiffParts } from './review-diff-parts'
 
 // The text `josh review:brief` prints — the `/code-review` invocation, composed from what the run
 // already knows (joshuafolkken/kit#1241).
@@ -56,7 +57,7 @@ function attest_line(nonce: string): string {
 const RUBRIC_RELATIVE_PATH = 'prompts/review-rubric.md'
 
 function rubric_line(rubric_path: string): string {
-	return `Rubric: read \`${rubric_path}\` first and apply it — it is the severity tests, the round output format, the nine categories and the stop conditions this review is scored against. You do not carry them otherwise, so a review that skips it is scored on the wrong rules.`
+	return `Rubric: read \`${rubric_path}\` first, with the Read tool rather than \`cat\` — it is larger than the Bash output cap, so a Bash print comes back truncated (joshuafolkken/kit#2963) — and apply it: it is the severity tests, the round output format, the nine categories and the stop conditions this review is scored against. You do not carry them otherwise, so a review that skips it is scored on the wrong rules.`
 }
 
 function checkout_block(checkout: ReviewCheckout, nonce: string): string {
@@ -357,6 +358,39 @@ function round_two_block(
 	return narrow_block(scope.recorded_at, scope, root, base)
 }
 
+// **A resumed round 1 reads what changed since the attested review, reusing round 2's reconciliation**
+// (joshuafolkken/kit#2945). A ship that stopped and was re-issued briefed the whole change again, so
+// the reviewer re-read every file the attested review had just read. The scope is the comparison round
+// 2 makes, measured from the tree that review was briefed on. Every reading that cannot narrow falls back to the whole
+// change: no record, a moved base, or an empty target. An empty target is included because a resumed
+// review that read nothing would report a clean verdict over the one already recorded.
+const RESUMED_HEADING =
+	'Resumed round 1 — a review of this branch was already attested, so this pass reads only what changed since the tree it read.'
+
+const RESUMED_QUESTION =
+	'Review these files in full against the rubric — they are the only code this pass has not already read.'
+
+function resumed_target(
+	snapshot: FileMapStamp | undefined,
+	tree: Record<string, string>,
+	root: string,
+	base: string,
+): string {
+	const scope = round_two_scope(snapshot, tree, base)
+
+	if (scope.recorded_at === undefined || scope.target.length === 0) {
+		return whole_change_target(root, base)
+	}
+
+	return [
+		RESUMED_HEADING,
+		`The attested review read the tree recorded at ${scope.recorded_at}.`,
+		`Target: only these files, which changed since that tree:\n${format_paths(root, scope.target)}`,
+		...reconciliation(root, base, scope),
+		RESUMED_QUESTION,
+	].join('\n')
+}
+
 interface BriefStamps {
 	gate: FileMapStamp | undefined
 	in_flight: FileMapStamp | undefined
@@ -377,20 +411,48 @@ interface BriefInput {
 	// The rubric's absolute path, resolved by the caller against the kit package rather than the review
 	// checkout, so it resolves in a consumer that ships no `prompts/` of its own (joshuafolkken/kit#2402).
 	rubric_path: string
+	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume
+	// (joshuafolkken/kit#2945). Absent, round 1 reads the whole change.
+	resumed_from?: FileMapStamp | undefined
+	// The change written as parts under the Bash output cap (joshuafolkken/kit#2963). Absent when the
+	// write failed, and the target line alone then names the change.
+	diff?: { parts: DiffParts; cap: number } | undefined
 }
 
 const SECOND_ROUND = 2
 
+function round_one_target(input: BriefInput): string {
+	const { root } = input.checkout
+
+	if (input.resumed_from === undefined) return whole_change_target(root, input.base)
+
+	return resumed_target(input.resumed_from, input.tree, root, input.base)
+}
+
 function target_block(input: BriefInput): string {
-	if (input.round < SECOND_ROUND) return whole_change_target(input.checkout.root, input.base)
+	if (input.round < SECOND_ROUND) return round_one_target(input)
 
 	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
 }
 
+// **Only beside a whole-change target** (joshuafolkken/kit#2963): each part is a path's diff against
+// the base, so beside a narrowed round 2 or a resumed round 1 the list would hand the reviewer the
+// code that narrowing exists to keep out of scope. Decided by the target actually printed, not by
+// the round: every round that cannot narrow widens through `whole_change_target`, and that round
+// needs the parts as much as a first one does.
+function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	const is_whole_change = target.includes(whole_change_target(input.checkout.root, input.base))
+
+	if (!is_whole_change || input.diff === undefined) return []
+
+	return ['', review_diff_parts.reading_block(input.diff.parts, input.diff.cap)]
+}
+
 // The level alone on the first line, because the level-only mode's contract — a caller reading the
 // answer with `$(...)` — is the one thing a brief must not break.
 function compose(input: BriefInput): string {
 	const profile = input.profile ?? agent_role_profile.DEFAULT_PROFILES.reviewer
+	const target = target_block(input)
 
 	return [
 		input.level,
@@ -404,28 +466,24 @@ function compose(input: BriefInput): string {
 		gate_line(input.stamps, input.tree, input.base),
 		TEST_COMMAND_LINE,
 		'',
-		target_block(input),
+		target,
+		...diff_block(input, target),
 	].join('\n')
 }
 
 const review_brief = {
 	attest_line,
 	BASE_MOVED_PREFIX,
-	base_moved_line,
 	carried_line,
-	checkout_block,
 	checkout_warning,
 	compose,
 	dropped_line,
 	EMPTY_DELTA_LINE,
 	gate_line,
-	green_stamp,
-	in_flight_line,
-	live_marker,
+	RESUMED_HEADING,
 	matching_stamp,
 	no_snapshot_line,
 	NOTHING_LEFT_LINE,
-	NOT_VERIFIED_LINE,
 	rubric_line,
 	RUBRIC_RELATIVE_PATH,
 	ROUND_TWO_HEADING,

package/scripts/review/review-diff-parts.ts

@@ -0,0 +1,89 @@
+// The change handed to the reviewer as files no larger than the Bash output cap
+// (joshuafolkken/kit#2963). The brief used to name the whole change as one `git diff` and the rubric
+// as one path, and the forked reviewer printed both through Bash: every print past
+// `BASH_MAX_OUTPUT_LENGTH` came back as a truncated preview plus a saved file it then re-read, and both
+// stayed in the cached prefix of every later request — 120 overflows and 68 re-reads in one review.
+//
+// **The diff is split, not shortened.** Each changed path gets its own parts, every part fits under the
+// cap, and the parts of one path concatenate back to exactly its diff — so the scope a review covers
+// is the one `git diff` lists, and only the size of a single read changes.
+
+// A map from each changed path to the absolute part files that carry its diff, in order.
+type DiffParts = Readonly<Record<string, ReadonlyArray<string>>>
+
+const LINE_BREAK = '\n'
+
+// A line longer than the budget is cut by characters: a minified file or a lockfile line would
+// otherwise produce one part past the cap, which is the read this module exists to remove.
+function cut_line(line: string, budget: number): Array<string> {
+	const pieces: Array<string> = []
+
+	for (let start = 0; start < line.length; start += budget) {
+		pieces.push(line.slice(start, start + budget))
+	}
+
+	return pieces
+}
+
+function pieces_of(text: string, budget: number): Array<string> {
+	return text.split(/(?<=\n)/u).flatMap((line) => cut_line(line, budget))
+}
+
+// Line-preserving where a line fits, so a part ends on a line boundary and a reader never sees a hunk
+// cut mid-line unless that one line is itself over the budget.
+function is_full(current: string, piece: string, budget: number): boolean {
+	return current.length > 0 && current.length + piece.length > budget
+}
+
+function split_text(text: string, budget: number): Array<string> {
+	const parts: Array<string> = []
+	let current = ''
+
+	for (const piece of pieces_of(text, budget)) {
+		if (is_full(current, piece, budget)) {
+			parts.push(current)
+			current = ''
+		}
+
+		current += piece
+	}
+
+	return current.length > 0 ? [...parts, current] : parts
+}
+
+function part_header(relative: string, index: number, count: number): string {
+	return `# ${relative} — part ${String(index + 1)} of ${String(count)}${LINE_BREAK}`
+}
+
+// The header is counted inside the cap, so the file a reader opens — header included — is what fits.
+// The count in the header is the final one, so it is sized against the widest header it can carry.
+function part_texts(relative: string, diff: string, cap: number): Array<string> {
+	const budget = Math.max(1, cap - part_header(relative, diff.length, diff.length).length)
+	const bodies = split_text(diff, budget)
+
+	return bodies.map((body, index) => `${part_header(relative, index, bodies.length)}${body}`)
+}
+
+function body_of(part: string): string {
+	return part.slice(part.indexOf(LINE_BREAK) + 1)
+}
+
+function part_list(parts: DiffParts): string {
+	return Object.entries(parts)
+		.flatMap(([relative, files]) => [`  ${relative}`, ...files.map((file) => `    ${file}`)])
+		.join(LINE_BREAK)
+}
+
+// **The read instruction names the tool as well as the files.** A part under the cap would survive a
+// `cat`, but the Read tool is the one read that is never truncated, and naming it keeps the reviewer
+// from reaching back for the whole `git diff` the target line defines the change by.
+function reading_block(parts: DiffParts, cap: number): string {
+	return [
+		`Reading the diff: Bash output is cut at ${String(cap)} characters, so the change is written below as one or more parts per path, each under that cap, and together exactly the diff. Read the parts of every path you review with the Read tool. Do not print the diff, or any file this brief names, through Bash (\`git diff\`, \`cat\`).`,
+		part_list(parts),
+	].join(LINE_BREAK)
+}
+
+const review_diff_parts = { body_of, part_texts, reading_block, split_text }
+
+export { review_diff_parts, type DiffParts }

package/scripts/review/review-diff-write.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_diff_parts, type DiffParts } from './review-diff-parts'
+
+// Writes the change as the parts `review-diff-parts.ts` cuts it into (joshuafolkken/kit#2963).
+//
+// **One diff per path, read the way the target line defines the change** — `git -C <root> diff
+// <base> -- <path>` for a tracked path, and the file's own content for an untracked one, which no
+// `git diff` lists. The parts are written to the temp directory keyed per checkout, the same place the
+// brief's other records live, and the directory is replaced on every brief so a part from an earlier
+// tree is never offered beside this one's.
+
+const DIRECTORY_PREFIX = 'josh-review-diff-'
+const DIRECTORY_MODE = 0o700
+const FILE_MODE = 0o600
+const PART_SUFFIX = '.diff'
+const INDEX_WIDTH = 3
+const NUL = '\0'
+const SLUG_SEPARATOR = '__'
+
+function untracked_text(root: string, relative: string): string {
+	try {
+		const content = readFileSync(path.join(root, relative), 'utf8')
+
+		if (content.includes(NUL)) return `untracked binary file ${relative}, not shown\n`
+
+		return `untracked file ${relative}, shown whole:\n${content}`
+	} catch {
+		return `${relative} is listed by the change but holds no diff and no file\n`
+	}
+}
+
+async function path_diff(root: string, base: string, relative: string): Promise<string> {
+	const diff = await git_spawn.read(['-C', root, 'diff', '--no-color', base, '--', relative])
+
+	return diff.length > 0 ? diff : untracked_text(root, relative)
+}
+
+function part_name(position: number, relative: string, index: number): string {
+	const prefix = String(position).padStart(INDEX_WIDTH, '0')
+
+	return `${prefix}-${relative.split('/').join(SLUG_SEPARATOR)}-${String(index + 1)}${PART_SUFFIX}`
+}
+
+interface PathText {
+	relative: string
+	text: string
+}
+
+function write_path(
+	directory: string,
+	position: number,
+	entry: PathText,
+	cap: number,
+): Array<string> {
+	return review_diff_parts.part_texts(entry.relative, entry.text, cap).map((part, index) => {
+		const file = path.join(directory, part_name(position, entry.relative, index))
+
+		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
+
+		return file
+	})
+}
+
+function fresh_directory(root: string): string {
+	const directory = stamp_file.stamp_path(DIRECTORY_PREFIX, root, '')
+
+	rmSync(directory, { recursive: true, force: true })
+	mkdirSync(directory, { mode: DIRECTORY_MODE })
+
+	return directory
+}
+
+interface DiffRequest {
+	root: string
+	base: string
+	paths: ReadonlyArray<string>
+	cap: number
+}
+
+async function write_parts(request: DiffRequest, directory?: string): Promise<DiffParts> {
+	const { root, base, paths, cap } = request
+	const texts = await Promise.all(
+		paths.map(async (relative) => ({ relative, text: await path_diff(root, base, relative) })),
+	)
+	const target = directory ?? fresh_directory(root)
+
+	return Object.fromEntries(
+		texts.map((entry, position) => [entry.relative, write_path(target, position, entry, cap)]),
+	)
+}
+
+const review_diff_write = { path_diff, write_parts }
+
+export { review_diff_write }

package/scripts/review/review-finding-ledger.ts

@@ -151,7 +151,6 @@ function has_issue_record(content: string, issue: number): boolean {
 
 const review_finding_ledger = {
 	CATEGORIES,
-	SEVERITIES,
 	category_counts,
 	finding_line,
 	has_issue_record,

package/scripts/review/review-record-cli.ts

@@ -186,7 +186,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv, new Date())
 }
 
-const review_record_cli = { USAGE, build_lines, parse_finding, run }
+const review_record_cli = { build_lines, parse_finding, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-record.ts

@@ -55,7 +55,6 @@ function refusal_message(issue: number): string {
 }
 
 const review_record = {
-	MISSING_REASON,
 	check,
 	refusal_message,
 }

package/scripts/review/review-round2-cli.ts

@@ -77,7 +77,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const review_round2_cli = { CLOSED_FLAG, JSON_KEY, KNOWN_FLAGS, main, parse_options, run, USAGE }
+const review_round2_cli = { CLOSED_FLAG, parse_options, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-stamps.ts

@@ -59,10 +59,15 @@ const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
 const GATE_PREFIX = 'josh-gate-stamp-'
 const IN_FLIGHT_PREFIX = 'josh-gate-running-'
 const ROUND_ONE_PREFIX = 'josh-review-round1-'
+const BRIEFED_PREFIX = 'josh-review-briefed-'
 
 const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
+// **The tree the latest round-1 brief handed out, retaken on every brief** (joshuafolkken/kit#2945).
+// The round-1 snapshot is kept from the first brief of a run, so it is not the tree a later review
+// read — a resume narrowed against it would skip a file put back to that older content.
+const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
 	PROJECT_ROOT,
@@ -97,16 +102,15 @@ function clear_round_one(target?: string): void {
 }
 
 const review_stamps = {
+	briefed_stamp,
 	clear_round_one,
 	GATE_PREFIX,
 	gate_stamp,
 	IN_FLIGHT_PREFIX,
 	in_flight_stamp,
-	LINT_RELATED_PREFIX,
 	lint_related_stamp,
 	ROUND_ONE_PREFIX,
 	round_one_stamp,
-	TEST_RELATED_PREFIX,
 	test_related_stamp,
 }
 

package/scripts/review/review-tree.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
 
 // The tree `josh review:brief` records: every path the change touches, and the digest of its content
 // (joshuafolkken/kit#1241).
@@ -30,8 +31,18 @@ function digest_of(root: string, relative: string): string {
 
 // Sorted so two readings of one tree produce the same record byte for byte, which is what lets a
 // stored stamp be compared against a fresh reading without a normalization step in between.
+//
+// **The observation ledger is left out of the map**, for the reason `hook-gate-reuse.ts` drops it from
+// the status it reads: it is no code any check runs (joshuafolkken/kit#1756). Kept in, a review's line
+// appended after the gate moved the map, so the ledger commit `pnpm josh followup` pushes carried a
+// tree the record no longer matched — the pre-push hook re-ran the whole unit suite inside the push's
+// 120-second budget, the timed-out push was retried over the still-running suite, and the commit's
+// undo then moved the tree under both (joshuafolkken/kit#2998). Filtered here, every reader of the map
+// — the gate's record, both hooks, the brief and the round-2 fix delta — agrees on it.
 function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, string> {
-	const sorted = [...paths].toSorted((left, right) => left.localeCompare(right))
+	const sorted = paths
+		.filter((relative) => !observation_ledger.is_ledger_path(relative))
+		.toSorted((left, right) => left.localeCompare(right))
 
 	return Object.fromEntries(sorted.map((relative) => [relative, digest_of(root, relative)]))
 }
@@ -43,6 +54,7 @@ function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, str
 // say the gate had verified an arbitrarily edited tree, and `--round 2` would report an empty fix
 // delta. **A defect that answers "all clear" is the one shape this record cannot take**, which is why
 // the root is resolved rather than assumed (measured from `scripts/`: 18 of 25 entries `absent`).
+// The observation ledger is dropped inside `tree_of`, above (joshuafolkken/kit#3017).
 async function read_changed_tree(
 	paths?: ReadonlyArray<string>,
 	root?: string,
@@ -53,6 +65,6 @@ async function read_changed_tree(
 	)
 }
 
-const review_tree = { ABSENT_DIGEST, digest_of, read_changed_tree, tree_of }
+const review_tree = { ABSENT_DIGEST, read_changed_tree, tree_of }
 
 export { review_tree }

package/scripts/rules/decision-oracle-stage.ts

@@ -0,0 +1,18 @@
+import { run_stage } from '#scripts/run/run-stage'
+import type { DecisionOracle } from './decision-oracle'
+
+// The stage-ladder oracle (joshuafolkken/kit#3042), kept beside the enumeration rather than inside it
+// because `decision-oracle.ts` sits at its file-size limit. Where a run on an issue starts — and whether
+// the command typed has already been reached — is computed by `run:entry` from the issue and the tree's
+// hold, so the skill's stage table points at the command rather than re-deciding it in prose. The
+// vocabulary is `run_stage`'s own start tokens, never a second copy.
+const RUN_ENTRY_ORACLE: DecisionOracle = {
+	name: 'run:entry',
+	decision:
+		'Where a run on an issue starts, and whether the typed command has already been reached',
+	args: '<N> [--to kickoff|halfrun|prrun|fullrun]',
+	vocabulary: run_stage.START_TOKENS,
+	single_source: '.claude/skills/workflow-commands/SKILL.md → §2k',
+}
+
+export { RUN_ENTRY_ORACLE }

package/scripts/rules/decision-oracle.ts

@@ -6,6 +6,7 @@
 // not by prose. Single source: `prompts/collaboration-workflow/residency.md` → question 0.
 //
 // Anything not on this list is answered by prose or by a hook-delivered rule, never by a command.
+import { RUN_ENTRY_ORACLE } from './decision-oracle-stage'
 
 // Paths that appear in more than one entry's `single_source` field.
 const CHAIN_RULE_MD = '.claude/skills/workflow-commands/chain-rule.md'
@@ -22,11 +23,11 @@ const BACKLOGRUN_MD = '.claude/skills/workflow-commands/backlogrun.md'
 // now has its verdict contract only in this reference. That makes it the single source and the section
 // a reader is routed to, in the same `file.md → \`josh <command>\`` form the `epic:reconcile` and
 // `lane:list` entries already use. joshuafolkken/kit#2254.
-const RUN_MERGE_REFERENCE = 'docs/josh-commands.md → `josh run:merge`'
-const EPIC_NEXT_REFERENCE = 'docs/josh-commands.md → `josh epic:next`'
-const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands.md → `josh backlog:budget`'
-const RUN_LIVENESS_REFERENCE = 'docs/josh-commands.md → `josh run:liveness`'
-const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands.md → `josh auto-ok:next`'
+const RUN_MERGE_REFERENCE = 'docs/josh-commands-automation.md → `josh run:merge`'
+const EPIC_NEXT_REFERENCE = 'docs/josh-commands-automation.md → `josh epic:next`'
+const BACKLOG_BUDGET_REFERENCE = 'docs/josh-commands-automation.md → `josh backlog:budget`'
+const RUN_LIVENESS_REFERENCE = 'docs/josh-commands-automation.md → `josh run:liveness`'
+const AUTO_OK_NEXT_REFERENCE = 'docs/josh-commands-automation.md → `josh auto-ok:next`'
 
 // Command used by two separate oracle entries (run:cut:resume and run:cut:gate).
 const RUN_CUT_CMD = 'run:cut'
@@ -311,7 +312,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			"Whether an epic's declaration matches its recorded relations, and the repair when it does not",
 		args: '--reconcile <E>',
 		vocabulary: [RECONCILED, NOTHING_TO_RECONCILE],
-		single_source: 'docs/josh-commands.md → `josh epic --reconcile`',
+		single_source: 'docs/josh-commands-automation.md → `josh epic --reconcile`',
 	},
 	{
 		name: 'lane:list',
@@ -319,8 +320,9 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			'Whether each in-progress issue holds a live lane, and the two-directional difference',
 		args: '',
 		vocabulary: [LIVE, STOPPED, UNKNOWN],
-		single_source: 'docs/josh-commands.md → The `in-progress` / lane difference',
+		single_source: 'docs/josh-commands-automation.md → The `in-progress` / lane difference',
 	},
+	RUN_ENTRY_ORACLE,
 ]
 
 // Returns the command name for an oracle entry. When `command` is omitted from the entry,
@@ -339,4 +341,5 @@ const decision_oracle = {
 	get_command,
 }
 
+export type { DecisionOracle }
 export { decision_oracle }