@joshuafolkken/kit 1.1387.0 → 1.1453.0

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { change_base } from '#scripts/git/change-base'
 import { path_decision } from '#scripts/josh/path-decision'
+import { review_code_tree } from './review-code-tree'
 import { review_round2 } from './review-round2'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
@@ -44,6 +45,14 @@ function parse_options(argv: ReadonlyArray<string>): Options | undefined {
 	}
 }
 
+// Only the paths the code record covers are re-read, so a run without one parses nothing.
+async function read_comment_only(base: string | undefined): Promise<ReadonlyArray<string>> {
+	const snapshot = review_stamps.round_one_code_stamp.read()
+	const tree = await review_code_tree.read(Object.keys(snapshot?.files ?? {}))
+
+	return review_code_tree.comment_only(snapshot, tree, base)
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const options = parse_options(argv)
 
@@ -53,11 +62,13 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
+	// The commit the tree below is a diff against, so the snapshot can be refused when it was taken
+	// against a different one — and the resolved commit rather than `git_command.change_base`, whose
+	// fallback is a ref name that moves and would compare equal to itself.
+	const base = await change_base.resolved()
 	const { verdict, reason } = review_round2.decide({
-		// The commit the tree below is a diff against, so the snapshot can be refused when it was taken
-		// against a different one — and the resolved commit rather than `git_command.change_base`, whose
-		// fallback is a ref name that moves and would compare equal to itself.
-		base: await change_base.resolved(),
+		base,
+		comment_only: await read_comment_only(base),
 		is_round_one_closed: options.is_round_one_closed,
 		snapshot: review_stamps.round_one_stamp.read(),
 		// No paths argument: `read_changed_tree` reads them itself, from the one definition of
@@ -76,7 +87,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const review_round2_cli = { CLOSED_FLAG, parse_options, run }
+const review_round2_cli = { CLOSED_FLAG, parse_options, read_comment_only, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/review-round2.ts

@@ -9,14 +9,14 @@ import { review_level } from './review-level'
 //
 // **The two arms are the two states in which round 2's reason does not arise.** Round 2 exists
 // because round 1's *fix code* is unreviewed, and that is structural. Arm A applies where there is no fix code — the findings closed without an edit — so
-// the premise is absent rather than overridden. Arm B applies where the fix code neither executes,
-// nor instructs, nor ships, which is `review-level.ts`'s inert set: the same three ways a defect in
-// this repository escapes, read here for the fix delta instead of the whole change.
+// the premise is absent rather than overridden. Arm B applies where the fix leaves what executes
+// unchanged: `review-level.ts`'s inert set, documentation under `docs/` and the root `README.md`,
+// `prompts/`, and source files whose only change is in comments (`review-code-tree.ts`).
 //
-// **The wider line — "the fix delta touches no runtime code path" — is not adopted**: as
-// `review-level.ts` records, documentation-only diffs carry real defects no test covers. A prompt
-// fix and a test fix are exactly where the review is the only detector, so exempting them would
-// remove the round in the case it earns its keep.
+// **Arm B is wider than the review level's inert set, on purpose** (joshuafolkken/kit#3787). Round 1
+// still reviews a documentation or prompt change in full, and the fix to its findings is still made;
+// what goes unread is only that fix. `.claude/**`, `CLAUDE.md`, tests and configuration stay outside:
+// a test fix can weaken the verification it belongs to, and nothing reads that but the review.
 
 type RoundTwoVerdict = 'required' | 'skip'
 
@@ -33,7 +33,11 @@ const NO_SNAPSHOT_REASON =
 const EMPTY_DELTA_REASON_PREFIX =
 	'the fix delta is empty: round 1 wrote no fix code, so there is no unreviewed fix for a verification pass to read'
 const INERT_DELTA_REASON_PREFIX =
-	'every path round 1 fixed is inert — it neither executes, nor instructs, nor ships'
+	'every path round 1 fixed leaves what executes unchanged — inert, documentation, a prompt, or a comment-only edit'
+const README_PATH = 'README.md'
+const DOCUMENTATION_PREFIX = 'docs/'
+const MARKDOWN_EXTENSION = '.md'
+const PROMPTS_PREFIX = 'prompts/'
 const BASE_MOVED_REASON =
 	'the change base moved since round 1 was recorded, so the two file maps do not cover the same set of paths and their difference is not the fix delta — the round runs rather than reading that difference as one'
 
@@ -51,6 +55,9 @@ interface RoundTwoInput {
 	is_round_one_closed: boolean
 	snapshot: FileMapStamp | undefined
 	tree: Record<string, string>
+	// The paths whose code round 1's fixes left as it was (`review_code_tree.comment_only`). Absent is
+	// none, which is what a run without a code record pays.
+	comment_only?: ReadonlyArray<string>
 }
 
 interface RoundTwoDecision {
@@ -86,13 +93,26 @@ function live_reason(deciding: ReadonlyArray<string>): string {
 	return `round 1's fixes touched paths that execute, instruct or ship: ${path_decision.format_path_list(deciding)}`
 }
 
+function is_documentation(relative: string): boolean {
+	if (relative === README_PATH || relative.startsWith(PROMPTS_PREFIX)) return true
+
+	return relative.startsWith(DOCUMENTATION_PREFIX) && relative.endsWith(MARKDOWN_EXTENSION)
+}
+
+function is_unexecuted(relative: string, comment_only: ReadonlyArray<string>): boolean {
+	if (review_level.is_inert(relative) || is_documentation(relative)) return true
+
+	return comment_only.includes(relative)
+}
+
 function verdict_for_delta(
 	delta: ReadonlyArray<string>,
 	taken_at: string,
+	comment_only: ReadonlyArray<string> = [],
 ): { verdict: RoundTwoVerdict; reason: string } {
 	if (delta.length === 0) return { verdict: SKIPPED_VERDICT, reason: empty_reason(taken_at) }
 
-	const deciding = delta.filter((relative) => !review_level.is_inert(relative))
+	const deciding = delta.filter((relative) => !is_unexecuted(relative, comment_only))
 
 	if (deciding.length === 0) return { verdict: SKIPPED_VERDICT, reason: inert_reason(delta) }
 
@@ -110,7 +130,7 @@ function decide(input: RoundTwoInput): RoundTwoDecision {
 
 	const delta = file_map_stamp.changed_since(input.snapshot, input.tree)
 
-	return { ...verdict_for_delta(delta, input.snapshot.taken_at), delta }
+	return { ...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only), delta }
 }
 
 const review_round2 = {

package/scripts/review/review-stamps.ts

@@ -13,11 +13,17 @@ 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 ROUND_ONE_CODE_PREFIX = 'josh-review-round1-code-'
 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)
+// Written beside the round-1 snapshot: the comment-free digest of each source file (`review-code-tree.ts`).
+const round_one_code_stamp: FileMapStampAccess = file_map_stamp.create(
+	ROUND_ONE_CODE_PREFIX,
+	PROJECT_ROOT,
+)
 // Retaken on every brief: the round-1 snapshot is not the tree a later review read.
 const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
@@ -29,24 +35,39 @@ const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	PROJECT_ROOT,
 )
 
+// Swallowed: a code record left behind only ever sits beside an older snapshot, which the next
+// round-1 brief replaces together with it.
+function clear_round_one_code(target?: string): void {
+	try {
+		round_one_code_stamp.remove(target)
+	} catch {
+		/* the next round-1 brief overwrites it */
+	}
+}
+
 // Called only from the end of a merged run: a leftover widens the next delta (safe), while an early
 // removal lets round 1 re-snapshot an already-fixed tree (unsafe). Swallowed — the PR already merged.
-function clear_round_one(target?: string): void {
+function clear_round_one(target?: string, code_target?: string): void {
 	try {
 		round_one_stamp.remove(target)
 	} catch {
 		/* a record left behind widens the next round rather than narrowing it */
 	}
+
+	clear_round_one_code(code_target)
 }
 
 const review_stamps = {
 	briefed_stamp,
 	clear_round_one,
+	clear_round_one_code,
 	GATE_PREFIX,
 	gate_stamp,
 	IN_FLIGHT_PREFIX,
 	in_flight_stamp,
 	lint_related_stamp,
+	ROUND_ONE_CODE_PREFIX,
+	round_one_code_stamp,
 	ROUND_ONE_PREFIX,
 	round_one_stamp,
 	test_related_stamp,

package/scripts/rules/implementation-cut.ts

@@ -176,9 +176,9 @@ const IMPLEMENTATION_CUT_REASON =
 	'because the verdict was only ever read at session entry, where the context has not yet grown. The ' +
 	"verdict is `pnpm josh cost --cut`'s exactly — the same per-request billed-input statistic against the " +
 	'same threshold, never a second measurement. Issue `pnpm josh run:cut --impl <N> --handoff <path>` now and read the ' +
-	'verdict: on `cut`, **end the turn immediately** — in a lane the fresh process owns the run and ' +
-	'continues implementing, so it must not be waited for; outside a lane nothing is relaunched, so first ' +
-	'send the `confirmation` Telegram naming the resume command `fullrun #<N>` and keep the hold; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
+	'verdict: on `cut`, read what the command printed. Where it relaunched a fresh process, **end the turn ' +
+	'immediately** — that process owns the run and continues implementing, so it must not be waited for, ' +
+	'and **no Telegram is owed**: a cut that resumes itself leaves a person nothing to act on. Where it printed that nothing was relaunched, do what it prints, then end the turn; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
 	'`unknown`, this process carries the run on and the edit is simply the next call. Never relaunch a ' +
 	'second process after `busy`. This fired because the dispatch mark names this lane or the run hold ' +
 	'names this issue; a person working here carries no mark and holds no run, so sees no refusal, so there is no human-or-child judgement left to make. The ' +

package/scripts/rules/pre-gate-cut.ts

@@ -172,7 +172,7 @@ const PRE_GATE_CUT_REASON =
 	'176K of 204K output riding across that boundary, and joshuafolkken/kit#1864 measured the step ' +
 	'itself firing 0 times in 6 lane children while it was carried as prose. Issue ' +
 	'`pnpm josh run:cut <N>` now, and read the verdict: on `cut`, **end the turn immediately** — the ' +
-	'fresh process owns the run from there and must not be waited for; on `not-a-lane`, `unready`, ' +
+	'fresh process owns the run from there and must not be waited for, and **no Telegram is owed** for a cut that resumes itself; on `not-a-lane`, `unready`, ' +
 	'`busy`, `failed` or `unknown`, this process carries the run on and the gate is simply the next ' +
 	'call. Never relaunch a second process after `busy`. This fired because the dispatch mark names ' +
 	'this lane; a person working here carries no mark and sees no refusal, so there is no ' +

package/scripts/run/board/run-board-checks.ts

@@ -0,0 +1,42 @@
+import { run_event_checks, type PrChecks } from '#scripts/run/event/run-event-checks'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+
+// Each child's newest `pr-checks` line — its pull request's CI counts and CodeRabbit's state as
+// `josh followup` last polled them (joshuafolkken/kit#3770). Read from the stream alone, so a redraw
+// asks GitHub nothing.
+
+interface HeldChecks {
+	checks: PrChecks
+	at_ms: number
+}
+
+const { PR_CHECKS } = run_event_stream.EVENT_KIND
+
+function held_of(event: RunEvent): HeldChecks | undefined {
+	const checks = event.kind === PR_CHECKS ? run_event_checks.checks_of(event.text) : undefined
+
+	return checks === undefined ? undefined : { checks, at_ms: Date.parse(event.at) }
+}
+
+// The stream's bound reorders its lines, so the newest is the latest `at`, not the last line.
+function is_newer(held: HeldChecks, current: HeldChecks | undefined): boolean {
+	return current === undefined || held.at_ms >= current.at_ms
+}
+
+function newest_of(events: ReadonlyArray<RunEvent>): ReadonlyMap<number, PrChecks> {
+	const newest = new Map<number, HeldChecks>()
+
+	for (const event of events) {
+		const held = held_of(event)
+		const issue = Number(run_event_scope.issue_named(event))
+
+		if (held !== undefined && is_newer(held, newest.get(issue))) newest.set(issue, held)
+	}
+
+	return new Map([...newest].map(([issue, held]) => [issue, held.checks]))
+}
+
+const run_board_checks = { newest_of }
+
+export { run_board_checks }

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

@@ -15,6 +15,7 @@ import { run_board_read } from './run-board-read'
 import { run_board_screen, type Screen } from './run-board-screen'
 import { run_board_spin } from './run-board-spin'
 import type { BoardPorts } from './run-board-state'
+import { run_board_thanks_read } from './run-board-thanks-read'
 import { run_board_tick } from './run-board-tick'
 import { run_board_usage_read } from './run-board-usage-read'
 
@@ -52,6 +53,7 @@ const LIVE_PORTS: BoardPorts = {
 	read_machine: machine_capacity.read_sample,
 	read_usage: run_board_usage_read.usage_reader(),
 	read_closed: async (issues) => await run_board_closed.read_all(issues),
+	read_thanks: async () => await run_board_thanks_read.read_thanks(),
 	now: () => Date.now(),
 	write: (frame) => process.stdout.write(frame),
 	// No fallback: a terminal that opens no link, or a pipe, gets the bare number rather than a URL.

package/scripts/run/board/run-board-every.ts

@@ -15,7 +15,8 @@ interface ChatFrame {
 	local: LocalRead | undefined
 }
 
-// One frame in the chat's form, with every escape stripped because a chat shows them as text.
+// One frame in the chat's form, with every escape stripped because a chat shows them as text. The
+// reviewers are thanked on the terminal's board alone, so the chat reads no roster.
 async function chat_frame(ports: BoardPorts): Promise<ChatFrame> {
 	let text = ''
 	const chat_ports: BoardPorts = {
@@ -23,6 +24,7 @@ async function chat_frame(ports: BoardPorts): Promise<ChatFrame> {
 		is_tty: false,
 		size: undefined,
 		form: 'chat',
+		read_thanks: undefined,
 		write: (frame) => {
 			text += stripVTControlCharacters(frame)
 		},

package/scripts/run/board/run-board-fit.ts

@@ -5,14 +5,17 @@ import { run_board_labels } from './run-board-labels'
 // A live `run:board` frame kept within the terminal. A frame taller than the pane scrolls the
 // alternate screen as it is written, and the header — the lines that say whether the run moves and
 // how far it is — is what scrolls off. So the parts below it give way instead, least wanted first:
-// the footer, the legend, the finished rows, the notes, the rows not yet started, the parked rows
-// and, last, the running rows — what a person keeps the board open to see. Each stage stops once the
+// the footer, the legend, the oldest notes until three are left, the finished rows, the rest of the
+// notes, the reviewers thanked above the legend, the rows not yet started, the parked rows and, last,
+// the running rows — what a person keeps the board open to see. Each stage stops once the
 // frame fits, a cut row is counted on its section's `more N` line, and the order a row is drawn in
 // never changes. A line wider than the pane wraps, so every line is counted by the rows it takes on
 // screen, not as one.
 
 const { WORDS } = run_board_labels
 const INDENT = '  '
+// The newest notes kept until the finished rows are gone; the older ones give way before them.
+const NOTES_KEPT = 3
 
 interface TerminalSize {
 	rows: number
@@ -52,21 +55,24 @@ interface FrameParts {
 	above: ReadonlyArray<string>
 	plan: ReadonlyArray<PlanSection>
 	notes: NotesPart
+	// The reviewers thanked, drawn right above the legend; none where nobody is.
+	thanks?: ReadonlyArray<string> | undefined
 	legend: ReadonlyArray<string>
 	footer: ReadonlyArray<string>
 }
 
 // One thing that gives way: a part as a whole, one note (the oldest shown), or one issue row.
-type Yielder = 'footer' | 'legend' | 'note' | PlanLine
+type Yielder = 'thanks' | 'footer' | 'legend' | 'note' | PlanLine
 
 interface Cut {
+	thanks: boolean
 	footer: boolean
 	legend: boolean
 	notes: number
 	rows: ReadonlySet<PlanLine>
 }
 
-const NO_CUT: Cut = { footer: false, legend: false, notes: 0, rows: new Set() }
+const NO_CUT: Cut = { thanks: false, footer: false, legend: false, notes: 0, rows: new Set() }
 
 // The columns a line takes on screen: its color escapes take none, an emoji two.
 function width_of(line: string): number {
@@ -117,6 +123,7 @@ function compose(parts: FrameParts, cut: Cut): Array<string> {
 		...parts.above,
 		...plan_lines(parts.plan, cut.rows),
 		...notes_lines(parts.notes, cut.notes),
+		...(cut.thanks ? [] : (parts.thanks ?? [])),
 		...(cut.legend ? [] : parts.legend),
 		...(cut.footer ? [] : parts.footer),
 	]
@@ -154,12 +161,15 @@ function order_of(parts: FrameParts): Array<Yielder> {
 		.map((line, index) => ({ line, index }))
 		.filter((entry) => entry.line.row !== undefined)
 	const notes = parts.notes.lines.map((): Yielder => 'note')
+	const surplus = Math.max(0, notes.length - NOTES_KEPT)
 
 	return [
 		'footer',
 		'legend',
+		...notes.slice(0, surplus),
 		...yielding(rows, 'finished'),
-		...notes,
+		...notes.slice(surplus),
+		'thanks',
 		...yielding(rows, 'pending'),
 		...yielding(rows, 'parked'),
 		...yielding(rows, 'running'),
@@ -175,6 +185,7 @@ function cut_of(order: ReadonlyArray<Yielder>, count: number): Cut {
 	const gone = order.slice(0, count)
 
 	return {
+		thanks: gone.includes('thanks'),
 		footer: gone.includes('footer'),
 		legend: gone.includes('legend'),
 		notes: gone.filter((item) => item === 'note').length,

package/scripts/run/board/run-board-fresh.ts

@@ -0,0 +1,64 @@
+import { styleText } from 'node:util'
+import { run_progress } from '#scripts/run/progress/run-progress'
+
+// **The one place a freshly updated part of `run:board` is emphasized** — the header's `💓` and third
+// line, an issue row's phase, start and end (joshuafolkken/kit#3784). The emphasis fades in three
+// one-second stages, decided by the part's age alone, so no frame remembers the one before it. Only a
+// live screen draws it: a chat, a `--once` frame or a pipe gets the text as it is.
+
+type FreshStage = 'inverse' | 'bold-color' | 'bold' | 'none'
+
+type TextFormat = Parameters<typeof styleText>[0]
+
+// What decides whether a frame emphasizes at all: a screen frame with a spinner is a live terminal.
+interface FreshFrame {
+	now_ms: number
+	form: 'screen' | 'chat'
+	spinner: string | undefined
+}
+
+const STAGE_MS = run_progress.MS_PER_SECOND
+const FADING: ReadonlyArray<FreshStage> = ['inverse', 'bold-color', 'bold']
+const FORMATS: Readonly<Record<Exclude<FreshStage, 'none'>, TextFormat>> = {
+	inverse: 'inverse',
+	'bold-color': ['bold', 'cyan'],
+	bold: 'bold',
+}
+
+// The stage a part `age_ms` old is drawn in; an unknown or a future age is never emphasized.
+function stage_of(age_ms: number | undefined): FreshStage {
+	if (age_ms === undefined || age_ms < 0) return 'none'
+
+	return FADING[Math.floor(age_ms / STAGE_MS)] ?? 'none'
+}
+
+function paint(text: string, stage: FreshStage): string {
+	if (stage === 'none' || text === '') return text
+
+	return styleText(FORMATS[stage], text)
+}
+
+function is_live(frame: FreshFrame): boolean {
+	return frame.form === 'screen' && frame.spinner !== undefined
+}
+
+// `text` emphasized as a part `age_ms` old, where the frame is a live screen.
+function aged(text: string, age_ms: number | undefined, frame: FreshFrame): string {
+	return is_live(frame) ? paint(text, stage_of(age_ms)) : text
+}
+
+// `text` emphasized as a part that changed at `at_ms`.
+function since(text: string, at_ms: number | undefined, frame: FreshFrame): string {
+	return aged(text, at_ms === undefined ? undefined : frame.now_ms - at_ms, frame)
+}
+
+// `text` right-aligned to `width` with only the text emphasized, never the blanks before it, so the
+// column keeps its width and an inverse stage does not light up the padding.
+function padded(text: string, width: number, emphasized: string): string {
+	return `${' '.repeat(Math.max(0, width - text.length))}${emphasized}`
+}
+
+const run_board_fresh = { aged, padded, paint, since, stage_of }
+
+export { run_board_fresh }
+export type { FreshFrame, FreshStage }