@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/review/review-fix-round.ts

@@ -0,0 +1,144 @@
+import { randomUUID } from 'node:crypto'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { review_attest } from './review-attest'
+import type { ReviewCheckout } from './review-checkout'
+import { review_finding_ledger, type Finding } from './review-finding-ledger'
+import { review_finding_text } from './review-finding-text'
+import { review_stamps } from './review-stamps'
+import { review_stop_log } from './review-stop-log'
+
+// The recorded round's findings and the tree it READ, before its fixes. The ledger keeps the
+// correspondence; this checkout-local handoff keeps the blobs needed to print the next fix delta.
+const finding_schema = z.object({
+	category: z.string(),
+	severity: z.string(),
+	file: z.string(),
+	description: z.string(),
+	disposition: z.string().optional(),
+})
+const round_schema = z.object({
+	id: z.string(),
+	issue: z.number(),
+	snapshot: z.string(),
+	findings: z.array(finding_schema),
+})
+type RecordedRound = z.infer<typeof round_schema>
+type DescribedFinding = Finding & { description: string }
+
+function target(root: string): string {
+	return stamp_file.stamp_path('josh-review-fix-round-', root)
+}
+
+function read(root: string): RecordedRound | undefined {
+	const raw = stamp_file.read_stamp_text(target(root)) ?? ''
+
+	return round_schema.safeParse(json_value.parse_or_undefined(raw)).data
+}
+
+function snapshot(round: RecordedRound): FileMapStamp | undefined {
+	try {
+		return file_map_stamp.parse_stamp(round.snapshot)
+	} catch {
+		return undefined
+	}
+}
+
+function resume(checkout: ReviewCheckout): RecordedRound | undefined {
+	const round = read(checkout.root)
+	const stamp = round === undefined ? undefined : snapshot(round)
+
+	if (stamp === undefined || !review_attest.is_briefed_since(stamp.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	return review_attest.is_attested_on(checkout, checkout.root) ? round : undefined
+}
+
+// Description and category identify a finding across shifted line numbers. Ambiguous matches are
+// kept separate: an uncertain correspondence must not silently close another finding.
+function key(finding: z.infer<typeof finding_schema>): string {
+	return JSON.stringify([
+		finding.category,
+		finding.file.replace(/:\d+(?:-\d+)?$/u, ''),
+		finding.description,
+	])
+}
+
+function correspondence(
+	previous: RecordedRound | undefined,
+	current: RecordedRound,
+): ReadonlyArray<string> {
+	const before = previous?.issue === current.issue ? previous.findings : []
+	const rows = current.findings.map((finding) => ({
+		...finding,
+		status: before.filter((old) => key(old) === key(finding)).length === 1 ? 'continuing' : 'new',
+	}))
+	const resolved = before.filter((old) =>
+		current.findings.every((finding) => key(old) !== key(finding)),
+	)
+
+	return [...rows, ...resolved.map((finding) => ({ ...finding, status: 'resolved' }))].map(
+		(row) =>
+			`- rx:${JSON.stringify({ round: current.id, previous: previous?.id, ...row, status: review_finding_ledger.is_closing(row.disposition) ? 'resolved' : row.status })}`,
+	)
+}
+
+function prepare(
+	issue: number,
+	findings: ReadonlyArray<Finding & { description?: string }>,
+	root: string,
+): RecordedRound | undefined {
+	const stamp = review_stamps.briefed_stamp.read()
+
+	if (stamp === undefined || !review_attest.is_briefed_since(stamp.taken_at, root)) return undefined
+
+	return {
+		id: randomUUID(),
+		issue,
+		snapshot: JSON.stringify(stamp),
+		findings: findings.map((finding) => ({ ...finding, description: finding.description ?? '' })),
+	}
+}
+
+function save(round: RecordedRound, root: string): void {
+	stamp_file.write_stamp(target(root), round)
+}
+
+function lines(round: RecordedRound | undefined, root: string): ReadonlyArray<string> {
+	return round === undefined ? [] : correspondence(read(root), round)
+}
+
+function record_reasons(
+	issue: number,
+	findings: ReadonlyArray<Finding & { description?: string }>,
+): void {
+	review_stop_log.record({
+		issue,
+		stage: 'review:record',
+		is_fixed: true,
+		findings: findings
+			.filter((finding) => (finding.description ?? '').length > 0)
+			.map((finding) => ({
+				kind: `${finding.category}:${finding.severity}`,
+				location: finding.file,
+				sentence: review_finding_text.first_sentence(finding.description ?? ''),
+			})),
+	})
+}
+
+const review_fix_round = {
+	correspondence,
+	lines,
+	prepare,
+	read,
+	record_reasons,
+	resume,
+	save,
+	snapshot,
+}
+
+export type { RecordedRound, DescribedFinding }
+export { review_fix_round }

package/scripts/review/review-gate-mode.ts

@@ -0,0 +1,25 @@
+import { package_manifest, REVIEW_GATE_SCHEMA } from '#scripts/lib/package-manifest'
+import type { z } from 'zod'
+
+type ReviewGateMode = z.infer<typeof REVIEW_GATE_SCHEMA>
+
+const ENV_KEY = 'JOSH_REVIEW_GATE'
+const DEFAULT_MODE: ReviewGateMode = 'local'
+
+function read(directory: string = process.cwd()): ReviewGateMode {
+	return (
+		REVIEW_GATE_SCHEMA.safeParse(process.env[ENV_KEY]).data ??
+		package_manifest.read_nearest_value(
+			directory,
+			package_manifest.josh_schemas.review_gate,
+			function select_mode(manifest) {
+				return manifest.josh?.review_gate
+			},
+		) ??
+		DEFAULT_MODE
+	)
+}
+
+const review_gate_mode = { read }
+
+export { review_gate_mode }

package/scripts/review/review-interaction.ts

@@ -1,9 +1,12 @@
 import { project_checks } from '#scripts/gate/project-checks'
+import { change_base } from '#scripts/git/change-base'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_attest, type ReviewSlot } from './review-attest'
+import { review_code_tree } from './review-code-tree'
 import { review_finding_ledger } from './review-finding-ledger'
+import { review_round2 } from './review-round2'
 
 // The interaction review — one adversarial pass after `/code-review`, over a change to the run
 // tooling (joshuafolkken/kit#4276).
@@ -16,24 +19,42 @@ import { review_finding_ledger } from './review-finding-ledger'
 //
 // **Its round is its own ledger line, `- ri:`**, so the merge gate tells it apart from `/code-review`'s
 // and `josh followup` refuses a due change that has none. The verdicts mirror `review_record.check`'s:
-// `not-required` covers both a change outside the directories and a checkout that keeps no ledger.
+// `not-required` covers a change outside the directories, a change that leaves what executes in them
+// unchanged, and a checkout that keeps no ledger.
 
 const TARGET_DIRECTORIES = ['scripts/run/', 'scripts/lane/', 'scripts/backlog/', 'scripts/hooks/']
 
 const NOT_DUE_LINE =
 	'Interaction review not due: this is not the kit repository, or the change touches none of scripts/run/, scripts/lane/, scripts/backlog/ or scripts/hooks/.'
 
-const ROLE_LINES = [
-	'## Interaction review',
-	'This pass is not a second `/code-review`: do not hunt for bugs inside the diff — the round before it did. Your role is to find three existing features this change breaks. Check only these three:',
+// The pass's three questions — also the implementer's own before round 1, through `josh review:selfcheck`
+// (joshuafolkken/kit#5766).
+const QUESTIONS = [
 	'1. Every state, command, label, file or process this change adds or gives a new meaning to — who else reads or writes it? Search the repository outside the diff for each. Where the plan has a `### 影響を受ける既存の利用者` section, check it names them all.',
 	'2. Does each of those readers and writers still behave correctly when the new state or value reaches it (for example, a paused lane counted as running)?',
 	'3. Does the change add heavy or synchronous work to a path called repeatedly — every second, every Bash call, every edit?',
+]
+
+const ROLE_LINES = [
+	'## Interaction review',
+	'This pass is not a second `/code-review`: do not hunt for bugs inside the diff — the round before it did. Your role is to find three existing features this change breaks. Check only these three:',
+	...QUESTIONS,
 	"Report each break with the reader's `file:line` and the change's, rated by the rubric's severities; it is disposed of by `prompts/review.md` → \"Interaction review\".",
 ]
 
+const INERT_LINE_PREFIX =
+	'Interaction review not due: every run-tooling path this change touches leaves what executes unchanged (round 2’s inert reading — in these directories, an edit to comments or import specifiers only)'
+
 type InteractionStatus = 'ok' | 'missing' | 'not-required'
 
+const NOT_REQUIRED: InteractionStatus = 'not-required'
+
+// The status, and why a due change is not due after all — its paths all inert.
+interface InteractionReading {
+	status: InteractionStatus
+	inert_line?: string
+}
+
 function due_paths(
 	paths: ReadonlyArray<string>,
 	checkout: string = process.cwd(),
@@ -49,21 +70,56 @@ function brief_block(targets: ReadonlyArray<string>): string {
 	return [...ROLE_LINES, 'Changed in the run tooling:', ...listed].join('\n')
 }
 
-async function status_of(
+// **A due change whose every due path leaves what executes unchanged is not due** — round 2's own
+// inert predicate (joshuafolkken/kit#5567), over the change since the base (joshuafolkken/kit#5656).
+async function inert_line(due: ReadonlyArray<string>): Promise<string | undefined> {
+	const base = await change_base.resolved_through_merge()
+	if (base === undefined) return undefined
+	const inert = await review_code_tree.inert_since(base, due)
+	const is_inert = due.every((relative) => review_round2.is_unexecuted(relative, inert))
+
+	return is_inert ? `${INERT_LINE_PREFIX}: ${due.join(', ')}` : undefined
+}
+
+async function unrecorded_reading(due: ReadonlyArray<string>): Promise<InteractionReading> {
+	const line = await inert_line(due)
+
+	return line === undefined ? { status: 'missing' } : { status: NOT_REQUIRED, inert_line: line }
+}
+
+async function reading_of(
 	issue: number,
 	paths: ReadonlyArray<string>,
 	root: string = observation_ledger_home.ledger_root(),
+): Promise<InteractionReading> {
+	const due = due_paths(paths)
+	const content = due.length > 0 ? await observation_ledger_home.read(root) : undefined
+	if (content === undefined) return { status: NOT_REQUIRED }
+	if (review_finding_ledger.has_issue_record(content, issue, 'interaction')) return { status: 'ok' }
+
+	return await unrecorded_reading(due)
+}
+
+async function status_of(
+	issue: number,
+	paths: ReadonlyArray<string>,
+	root?: string,
 ): Promise<InteractionStatus> {
-	const content = due_paths(paths).length > 0 ? await observation_ledger_home.read(root) : undefined
+	const answer = await reading_of(issue, paths, root)
 
-	if (content === undefined) return 'not-required'
+	return answer.status
+}
 
-	return review_finding_ledger.has_issue_record(content, issue, 'interaction') ? 'ok' : 'missing'
+// The reading over this checkout's change — the one `run:review` opens round 1 from.
+async function reading(issue: number, root?: string): Promise<InteractionReading> {
+	return await reading_of(issue, await changed_paths.read_changed_paths(false), root)
 }
 
 // The status over this checkout's change — the reading `review:brief` takes.
 async function status(issue: number, root?: string): Promise<InteractionStatus> {
-	return await status_of(issue, await changed_paths.read_changed_paths(false), root)
+	const answer = await reading(issue, root)
+
+	return answer.status
 }
 
 // **Round 1's slots — the interaction review beside `/code-review`'s where it is due and not yet
@@ -79,7 +135,7 @@ const MISSING_REASON =
 	'This change touches the run tooling, and no interaction review is recorded for its issue — the pass that looks for the existing features a change breaks, which `/code-review` does not (joshuafolkken/kit#4276).'
 
 const REMEDY =
-	'Run it from `pnpm josh review:brief --interaction`, then record it with `pnpm josh review:record --interaction --issue <N> [<category>:<severity>:<file> ...]` — a clean pass is a call with no findings — and reissue the merge.'
+	'Run it from `pnpm josh review:brief --interaction`, whose reviewer writes its findings with `pnpm josh review:submit --interaction`; record them with `pnpm josh review:record --from-slot --interaction --issue <N> [<n>=<disposition> ...]` and reissue the merge.'
 
 function refusal_message(issue: number): string {
 	return [MISSING_REASON, `Issue: ${session_cite.issue(issue)}`, REMEDY].join('\n')
@@ -94,6 +150,8 @@ const review_interaction = {
 	brief_block,
 	due_paths,
 	NOT_DUE_LINE,
+	QUESTIONS,
+	reading,
 	refusal,
 	refusal_message,
 	round_one_slots,
@@ -101,5 +159,5 @@ const review_interaction = {
 	status_of,
 }
 
-export type { InteractionStatus }
+export type { InteractionReading, InteractionStatus }
 export { review_interaction }

package/scripts/review/review-lane-handover.ts

@@ -2,6 +2,9 @@ import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
+import { review_attest } from './review-attest'
+import { review_checkout } from './review-checkout'
+import { review_record } from './review-record'
 import { review_round_reuse, type ReuseAnswer } from './review-round-reuse'
 
 // joshuafolkken/kit#4850: once a lane child has recorded round 1 on a tree `josh ship` reuses, round 2
@@ -9,11 +12,13 @@ import { review_round_reuse, type ReuseAnswer } from './review-round-reuse'
 // the next lane reopened `run:review` after reading it, running a round 2 the ship then ran again. So
 // `run:review` refuses that reopen and `review:record` names the ship as the next step.
 //
-// **A round the ship would review again is not handed over**: `review:record --check` then tells the
-// lane to run round 1 itself, so `run:review` stays open for it.
+// **A round the ship would review again is not handed over**, but once attested its reopen is refused
+// all the same (joshuafolkken/kit#5655): `review:record --check` then names the ship, which reviews it.
 
 const SHIP_STEP = 'pnpm josh ship --detach --review "<title> #<N>"'
 const NEXT_STEP_LINE = `Next: hand over to \`${SHIP_STEP}\` — round 2 is the ship's; never reopen \`run:review\` (chain-rule.md step 0).`
+// What the ship does with files moved since an attested round 1, a widened `lane:plan`'s included.
+const SHIP_REVIEWS_LINE = `Files moved since — a widened \`lane:plan\`'s included — are the ship's: hand over to \`${SHIP_STEP}\`, whose round 2 reads them, or whose own round 1 reviews again where it does not reuse this one; never reopen \`run:review\` (chain-rule.md step 0).`
 
 // A reuse question git could not answer reads as not reused: the lane then reviews the round itself,
 // which costs one review, rather than leaving it to a ship that may review it again detached.
@@ -51,17 +56,37 @@ async function is_handed_over(issue: number): Promise<boolean> {
 	return await is_reused_here(issue)
 }
 
+// joshuafolkken/kit#5655: a `lane:plan` widened after round 1 moves the tree off the round the ship
+// reuses, so `is_handed_over` answered no and each widen opened another round 1. An attested round 1
+// refuses the reopen whatever the reuse answer: the widened files are read by the ship's `--review`.
+async function is_round_attested(issue: number): Promise<boolean> {
+	const verdict = await review_record.check(issue)
+
+	if (verdict.status !== 'ok') return false
+	const checkout = await review_checkout.read_checkout()
+
+	return review_attest.is_attested_on(checkout, checkout.root)
+}
+
+async function is_reopen_refused(issue: number): Promise<boolean> {
+	if (!is_lane_child_of(issue)) return false
+
+	return await is_round_attested(issue)
+}
+
 function refusal(issue: number): string {
 	return (
-		`⛔ run:review: round 1 of ${session_cite.issue(issue)} is recorded and josh ship reuses it, and this is a ` +
-		`dispatched lane child (\`${lane_child_marker.KEY}\`), so no brief is minted. ${NEXT_STEP_LINE}`
+		`⛔ run:review: round 1 of ${session_cite.issue(issue)} is recorded and attested, and this is a ` +
+		`dispatched lane child (\`${lane_child_marker.KEY}\`), so no brief is minted. ${SHIP_REVIEWS_LINE}`
 	)
 }
 
 const review_lane_handover = {
 	NEXT_STEP_LINE,
+	SHIP_REVIEWS_LINE,
 	answer_here,
 	is_handed_over,
+	is_reopen_refused,
 	refusal,
 }
 

package/scripts/review/review-level.ts

@@ -1,31 +1,13 @@
-// Which `/code-review` level a change is reviewed at, decided from the changed paths alone.
-//
-// **The decision takes no judgement.** "This one is small" is a judgement made under cost pressure,
-// and cost pressure resolves it toward "small" exactly when a defect is most likely to be shipped —
-// the same reason the cross-package interrupt removed its own "does this block?" evaluation. So the
-// input is the list of changed paths and nothing else.
+// Mechanical scope and size classification; an unknown executable size keeps the default.
+import { path_decision } from '#scripts/josh/path-decision'
 
 type ReviewLevel = 'low' | 'medium'
 
 const DEFAULT_LEVEL: ReviewLevel = 'medium'
 const REDUCED_LEVEL: ReviewLevel = 'low'
+const TINY_CHANGE_LINES = 20
 
-// Paths that neither execute, nor instruct, nor ship. A defect in one of these cannot change what
-// any program does, cannot change what an agent does, and cannot reach a consumer — the three ways
-// a defect in this repository escapes. Everything else, including every markdown file not named
-// here, is reviewed at the default level.
-//
-// **Being distributed is disqualifying on its own**, which is why `.vscode/**`, `.gitattributes`
-// and `.prettierignore` are *not* here despite looking inert: `package.json`'s `files` ships all
-// three, and `josh init` / `josh sync` write them into every consumer project. Keeping them out is
-// the same criterion that keeps documentation out, applied consistently.
-//
-// **Documentation is deliberately absent from this list**, which is the opposite of what the
-// "Non-runtime updates" testing exception does with it, and the difference is not an oversight.
-// That exception is about whether an automated test could have caught the defect; this is about
-// whether a human reading the diff is the only thing that can. Documentation-only diffs carry real
-// defects — dangling pointers into removed sections, and citations naming the wrong file, in
-// artifacts distributed to every consumer — that no test covers, because prose is what they are.
+// Inert remains separate from reduced review: round 2 uses it to identify non-executing fixes.
 const INERT_PATHS: ReadonlyArray<string> = [
 	'.editorconfig',
 	'.gitignore',
@@ -33,8 +15,6 @@ const INERT_PATHS: ReadonlyArray<string> = [
 	'LICENSE',
 ]
 
-// No directory is inert today. The constant stays because the check reads it, and because the next
-// candidate will arrive as a directory — but an empty list is the honest answer right now.
 const INERT_PREFIXES: ReadonlyArray<string> = []
 const INERT_SUFFIXES: ReadonlyArray<string> = ['.code-workspace']
 
@@ -48,24 +28,44 @@ function is_inert(path: string): boolean {
 	)
 }
 
-// The reduced level applies only when **every** changed path is inert. One executable or
-// instruction file in the diff and the whole change is reviewed at the default level: a review
-// reads the change, not a subset of it, so a per-file level would mean reviewing part of a diff.
-//
-// An empty diff also takes the default. There is nothing to review, so the level does not matter —
-// and answering `low` to "no files changed" would let a caller that failed to read the diff receive
-// a reduced level as though it had.
-function level_for(paths: ReadonlyArray<string>): ReviewLevel {
+function is_reduced_path(relative: string): boolean {
+	return (
+		is_inert(relative) ||
+		relative.endsWith('.md') ||
+		['docs/', 'prompts/', 'tests/'].some((prefix) => relative.startsWith(prefix)) ||
+		/\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(relative)
+	)
+}
+
+function is_tiny(changed_lines: number | undefined): boolean {
+	return changed_lines !== undefined && changed_lines >= 0 && changed_lines <= TINY_CHANGE_LINES
+}
+
+function level_for(paths: ReadonlyArray<string>, changed_lines?: number): ReviewLevel {
 	const changed = paths.map((path) => path.trim()).filter((path) => path !== '')
 
 	if (changed.length === 0) return DEFAULT_LEVEL
 
-	return changed.every((path) => is_inert(path)) ? REDUCED_LEVEL : DEFAULT_LEVEL
+	if (changed.every((relative) => is_reduced_path(relative))) return REDUCED_LEVEL
+
+	return is_tiny(changed_lines) ? REDUCED_LEVEL : DEFAULT_LEVEL
 }
 
 // The paths that forced the default level, so the answer can say why rather than only what.
 function deciding_paths(paths: ReadonlyArray<string>): Array<string> {
-	return paths.map((path) => path.trim()).filter((path) => path !== '' && !is_inert(path))
+	return paths.map((path) => path.trim()).filter((path) => path !== '' && !is_reduced_path(path))
+}
+
+function format_reason(paths: ReadonlyArray<string>, level: ReviewLevel): string {
+	if (level === REDUCED_LEVEL) {
+		return 'every changed path is inert, documentation, a prompt or a test; or the entire diff is at most 20 added/deleted lines'
+	}
+
+	const deciding = deciding_paths(paths)
+
+	if (deciding.length === 0) return 'no changed paths; the default level stands'
+
+	return `changed paths that execute or instruct: ${path_decision.format_path_list(deciding)}`
 }
 
 const review_level = {
@@ -77,6 +77,7 @@ const review_level = {
 	is_inert,
 	level_for,
 	deciding_paths,
+	format_reason,
 }
 
 export type { ReviewLevel }

package/scripts/review/review-lint-findings.ts

@@ -1,8 +1,8 @@
 import { review_lint_sections, type ReviewSection } from './review-lint-sections'
 
-// The finding-line checks of `review:lint` (`prompts/review-rubric.md` → "Review output format"): every
-// finding cites `file_path:line_number` and a severity, and a `low` carries its
-// `no failure scenario — <what you tried>` line. A round-2 first-round line cites the severity it
+// The finding-line checks of the review lint `review:submit --review` runs
+// (`prompts/review-rubric.md` → "Review output format"): every finding cites `file_path:line_number`
+// and a severity, and a `low` carries its `no failure scenario — <what you tried>` line. A round-2 first-round line cites the severity it
 // had (`(was high)`) and its resolution instead.
 
 interface ItemRule {

package/scripts/review/review-lint-sections.ts

@@ -1,7 +1,7 @@
 import { document_section } from '#scripts/document/document-section'
 
-// The parsing half of `review:lint`: a review's markdown split into its `###` sections, and a
-// section's list items grouped with their indented continuation lines. The checks live in
+// The parsing half of the review lint `review:submit --review` runs: a review's markdown split into
+// its `###` sections, and a section's list items grouped with their indented continuation lines. The checks live in
 // `review-lint.ts` and `review-lint-findings.ts`; nothing here judges what it reads.
 
 interface ReviewSection {

package/scripts/review/review-lint.ts

@@ -216,6 +216,12 @@ function with_reference(violations: ReadonlyArray<string>, round: number): Reado
 	return [...violations, `→ the format: ${RUBRIC} → "${section}"`]
 }
 
-const review_lint = { lint_review, with_reference }
+// What `review:submit --review` prints against a review: its violations with the
+// rubric section they are read against, empty on a pass.
+function failures(review: string, round: number): ReadonlyArray<string> {
+	return with_reference(lint_review(review, round), round)
+}
+
+const review_lint = { failures, lint_review, with_reference }
 
 export { review_lint }