@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/review/review-round2.ts

@@ -1,5 +1,8 @@
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { path_decision } from '#scripts/josh/path-decision'
+import { json_value } from '#scripts/lib/json-value'
+import { release_approval_prune } from '#scripts/release/release-approval-prune'
+import { z } from 'zod'
 import { review_level } from './review-level'
 
 // Whether the second review round runs at all.
@@ -11,7 +14,8 @@ import { review_level } from './review-level'
 // 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 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`).
+// `prompts/`, `josh metrics` approvals, and source files whose only change is in comments
+// (`review-code-tree.ts`).
 //
 // **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;
@@ -22,24 +26,46 @@ type RoundTwoVerdict = 'required' | 'skip'
 
 const REQUIRED_VERDICT: RoundTwoVerdict = 'required'
 const SKIPPED_VERDICT: RoundTwoVerdict = 'skip'
+const VERDICTS = [REQUIRED_VERDICT, SKIPPED_VERDICT] as const
+
+// One stable code per branch of `decide`, so a decision can be counted by why it fell where it did —
+// the reason sentences carry paths and timestamps and cannot be (joshuafolkken/kit#4064).
+const CODE = {
+	EMPTY: 'empty',
+	INERT: 'inert',
+	OPEN_FINDING: 'open-finding',
+	NO_SNAPSHOT: 'no-snapshot',
+	BASE_MOVED: 'base-moved',
+	LIVE: 'live',
+} as const
+
+type RoundTwoCode = (typeof CODE)[keyof typeof CODE]
+
+// The key `josh review:round2 --json` prints its verdict under, read back by `josh ship`.
+const JSON_KEY = 'round2'
+const json_schema = z.object({
+	[JSON_KEY]: z.enum(VERDICTS),
+	code: z.enum(Object.values(CODE)),
+	reason: z.string(),
+})
 
 // **The default is `required`, and every uncertainty resolves to it.** A command that answered `skip`
 // on a missing record would be the cheapest possible run and the most dangerous — the direction
 // `review-brief.ts` already takes when it widens a round-2 target it cannot name.
 const OPEN_FINDING_REASON =
-	'the caller did not assert that every round-1 High/Medium finding closed, so the pass that verifies them is due'
+	'the ledger does not show every round-1 High/Medium finding closed, so the pass that verifies them is due'
 const NO_SNAPSHOT_REASON =
 	'no round-1 snapshot was recorded, so the fix delta cannot be named — the round runs rather than assuming it is empty'
 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 leaves what executes unchanged — inert, documentation, a prompt, or a comment-only edit'
+	'every path round 1 fixed leaves what executes unchanged — inert, documentation, a prompt, a metrics approval, 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'
+	"the change base moved since round 1 was recorded and round 1's tree could not be carried onto the new one — no recorded round-1 blobs, or the carry conflicts — so the fix delta cannot be named and the round runs"
 
 interface RoundTwoInput {
 	// **The commit the tree above is a diff against**. This decision reads the
@@ -49,20 +75,28 @@ interface RoundTwoInput {
 	// a `skip`, which is worse than a mistargeted read — nothing gets read at all.
 	// `undefined` where it could not be resolved to a commit, which is refused exactly like a mismatch.
 	base: string | undefined
-	// Asserted by the caller from round 1's own output, because no command can read a review's
-	// findings. It is a report of a fact already written down, not a judgement made under cost
-	// pressure — and its absence is the safe answer, so a caller that forgets it pays a round.
+	// Read from the issue's ledger, where `review:record` keeps each finding's disposition
+	// (`review-round-one-closure.ts`), not asserted by the caller (joshuafolkken/kit#5286).
 	is_round_one_closed: boolean
+	// Why round 1 is open, quoted into the `required` answer. Absent falls back to the generic reason.
+	open_reason?: string
 	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>
+	// Asked only when the base moved: round 1's tree carried onto the current base, diffed against the
+	// tree now (`review-round-one-blobs.ts`). `undefined`, or no reader at all, is the moved-base refusal.
+	carried_delta?: (snapshot: FileMapStamp) => ReadonlyArray<string> | undefined
 }
 
-interface RoundTwoDecision {
+interface RoundTwoAnswer {
 	verdict: RoundTwoVerdict
+	code: RoundTwoCode
 	reason: string
+}
+
+interface RoundTwoDecision extends RoundTwoAnswer {
 	// The paths round 1's fixes changed. Returned even on `required` so the caller can name them, and
 	// on a `skip` so the record the run leaves behind says what went unreviewed.
 	delta: ReadonlyArray<string>
@@ -99,8 +133,17 @@ function is_documentation(relative: string): boolean {
 	return relative.startsWith(DOCUMENTATION_PREFIX) && relative.endsWith(MARKDOWN_EXTENSION)
 }
 
+// **A `josh metrics` approval is data, not code** (joshuafolkken/kit#4842): the ship's pre-detach
+// re-record rewrites it after round 1, and the gate's own metrics step checks it — the same reason
+// `review-reviewed-tree.ts` reads it as no move.
 function is_unexecuted(relative: string, comment_only: ReadonlyArray<string>): boolean {
-	if (review_level.is_inert(relative) || is_documentation(relative)) return true
+	if (
+		review_level.is_inert(relative) ||
+		is_documentation(relative) ||
+		release_approval_prune.is_approval(relative)
+	) {
+		return true
+	}
 
 	return comment_only.includes(relative)
 }
@@ -109,43 +152,84 @@ 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) }
+): RoundTwoAnswer {
+	if (delta.length === 0) {
+		return { verdict: SKIPPED_VERDICT, code: CODE.EMPTY, reason: empty_reason(taken_at) }
+	}
 
 	const deciding = delta.filter((relative) => !is_unexecuted(relative, comment_only))
 
-	if (deciding.length === 0) return { verdict: SKIPPED_VERDICT, reason: inert_reason(delta) }
+	if (deciding.length === 0) {
+		return { verdict: SKIPPED_VERDICT, code: CODE.INERT, reason: inert_reason(delta) }
+	}
+
+	return { verdict: REQUIRED_VERDICT, code: CODE.LIVE, reason: live_reason(deciding) }
+}
 
-	return { verdict: REQUIRED_VERDICT, reason: live_reason(deciding) }
+function required(code: RoundTwoCode, reason: string): RoundTwoDecision {
+	return { verdict: REQUIRED_VERDICT, code, reason, delta: [] }
 }
 
-function required(reason: string): RoundTwoDecision {
-	return { verdict: REQUIRED_VERDICT, reason, delta: [] }
+// On a moved base the digest comparison is a set difference, not the fix delta, so the carried
+// reading replaces it and every later rule is the same one an unmoved base gets.
+function fix_delta(
+	input: RoundTwoInput,
+	snapshot: FileMapStamp,
+): ReadonlyArray<string> | undefined {
+	if (file_map_stamp.describes_base(snapshot, input.base)) {
+		return file_map_stamp.changed_since(snapshot, input.tree)
+	}
+
+	return input.carried_delta?.(snapshot)
 }
 
 function decide(input: RoundTwoInput): RoundTwoDecision {
-	if (!input.is_round_one_closed) return required(OPEN_FINDING_REASON)
-	if (input.snapshot === undefined) return required(NO_SNAPSHOT_REASON)
-	if (!file_map_stamp.describes_base(input.snapshot, input.base)) return required(BASE_MOVED_REASON)
+	if (!input.is_round_one_closed) {
+		return required(CODE.OPEN_FINDING, input.open_reason ?? OPEN_FINDING_REASON)
+	}
+
+	if (input.snapshot === undefined) return required(CODE.NO_SNAPSHOT, NO_SNAPSHOT_REASON)
+
+	const delta = fix_delta(input, input.snapshot)
 
-	const delta = file_map_stamp.changed_since(input.snapshot, input.tree)
+	if (delta === undefined) return required(CODE.BASE_MOVED, BASE_MOVED_REASON)
 
 	return { ...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only), delta }
 }
 
+function to_json(answer: RoundTwoAnswer): string {
+	return JSON.stringify({ [JSON_KEY]: answer.verdict, code: answer.code, reason: answer.reason })
+}
+
+// The answer `to_json` printed, or `undefined` for any other output — read by the one caller that
+// records it, which must not guess a verdict from text it cannot parse.
+function parse_json(text: string): RoundTwoAnswer | undefined {
+	const parsed = json_schema.safeParse(json_value.parse_or_undefined(text.trim())).data
+
+	return parsed === undefined
+		? undefined
+		: { verdict: parsed[JSON_KEY], code: parsed.code, reason: parsed.reason }
+}
+
 const review_round2 = {
 	BASE_MOVED_REASON,
+	CODE,
 	decide,
 	EMPTY_DELTA_REASON_PREFIX,
 	empty_reason,
 	INERT_DELTA_REASON_PREFIX,
 	inert_reason,
+	is_unexecuted,
+	JSON_KEY,
 	live_reason,
 	NO_SNAPSHOT_REASON,
 	OPEN_FINDING_REASON,
+	parse_json,
 	REQUIRED_VERDICT,
 	SKIPPED_VERDICT,
+	to_json,
 	verdict_for_delta,
 }
 
+export type { RoundTwoAnswer, RoundTwoCode, RoundTwoVerdict }
 export { review_round2 }

package/scripts/review/review-stamps.ts

@@ -1,3 +1,5 @@
+import { gate_labels } from '#scripts/gate/gate-labels'
+import { verification_inputs } from '#scripts/gate/verification-inputs'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
 
@@ -9,14 +11,27 @@ import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-
 // The scoped stamps claim less than the gate stamp (changed files, two checks), so they stay separate.
 const LINT_RELATED_PREFIX = 'josh-lint-related-stamp-'
 const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
+// `josh test:e2e` answered green — a run or a printed skip — on this tree (`test-e2e-stamp.ts`).
+const E2E_PREFIX = 'josh-e2e-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 REVIEWED_PREFIX = 'josh-review-recorded-'
 
-const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
+// The records that vouch for a check carry the fingerprint of its declared inputs
+// (`verification-inputs.ts`): the gate's every declared check, a scoped record its own.
+function inputs_of(labels: ReadonlyArray<string>): () => string {
+	return () => verification_inputs.fingerprint(labels)
+}
+
+const gate_stamp: FileMapStampAccess = file_map_stamp.create(
+	GATE_PREFIX,
+	PROJECT_ROOT,
+	inputs_of(verification_inputs.DECLARED_LABELS),
+)
 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`).
@@ -26,14 +41,19 @@ const round_one_code_stamp: FileMapStampAccess = file_map_stamp.create(
 )
 // 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)
+// Retaken on every recorded round: the tree that round's verdict stands for, its fixes included.
+const reviewed_stamp: FileMapStampAccess = file_map_stamp.create(REVIEWED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
 	PROJECT_ROOT,
+	inputs_of([gate_labels.LINT_LABEL]),
 )
 const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	TEST_RELATED_PREFIX,
 	PROJECT_ROOT,
+	inputs_of([gate_labels.UNIT_LABEL]),
 )
+const e2e_stamp: FileMapStampAccess = file_map_stamp.create(E2E_PREFIX, 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.
@@ -61,6 +81,7 @@ const review_stamps = {
 	briefed_stamp,
 	clear_round_one,
 	clear_round_one_code,
+	e2e_stamp,
 	GATE_PREFIX,
 	gate_stamp,
 	IN_FLIGHT_PREFIX,
@@ -70,6 +91,7 @@ const review_stamps = {
 	round_one_code_stamp,
 	ROUND_ONE_PREFIX,
 	round_one_stamp,
+	reviewed_stamp,
 	test_related_stamp,
 }
 

package/scripts/review/review-stop-log.ts

@@ -0,0 +1,110 @@
+import { mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { json_value } from '#scripts/lib/json-value'
+import type { StopFinding } from '#scripts/run/ship/run-ship-review'
+import { z } from 'zod'
+
+// The durable record of every review finding that stopped a `josh ship` — one JSON line per finding,
+// with its kind, the `<file>[:<line>]` it cites and its first sentence, read back by
+// `josh review:stops` (joshuafolkken/kit#4519). The findings a round did not stop on — a ship round's
+// fixes made in place, and a `review:record` round's findings written with a reason
+// (joshuafolkken/kit#4817) — are in it too, marked fixed, which `review:stops` leaves out. The lane ledger's stop line keeps only the kinds, and
+// the finding's text was only in the ship log in the temp root, which a reboot clears.
+//
+// **It lives in the git common directory**, beside the test-read map: every lane worktree of one clone
+// appends to the same file, and a reboot keeps it. Appended with the lane ledger's `append`, so
+// concurrent lanes never lose each other's lines.
+//
+// **A test run writes nothing** unless it passes its own path, the lane ledger's rule: the writer sits on
+// the ship's stop path, which many suites exercise.
+
+const LOG_FILE = 'review-stops.jsonl'
+const LINE_SEPARATOR = '\n'
+
+const stop_line_schema = z.object({
+	at: z.string(),
+	issue: z.number(),
+	stage: z.string(),
+	kind: z.string(),
+	location: z.string(),
+	sentence: z.string(),
+	fixed: z.boolean().optional(),
+})
+
+type StopLine = z.infer<typeof stop_line_schema>
+
+// One stopped review: the issue, the stage that stopped and the findings that decided it. A round that
+// passed on fixes made in place is recorded too, marked `is_fixed`, so the lane's next review still sees
+// the constraint each fix met (joshuafolkken/kit#4780); `review:stops` leaves those lines out.
+interface ReviewStop {
+	issue: number
+	stage: string
+	findings: ReadonlyArray<StopFinding>
+	is_fixed?: boolean
+}
+
+function target(): string | undefined {
+	if (process.env['VITEST'] !== undefined) return undefined
+
+	const common = git_common_directory.repository()
+
+	return common === undefined
+		? undefined
+		: path.join(common, git_common_directory.STATE_DIRECTORY, LOG_FILE)
+}
+
+function write(destination: string, stop: ReviewStop): void {
+	const at = new Date().toISOString()
+	const mark = stop.is_fixed === true ? { fixed: true } : {}
+
+	mkdirSync(path.dirname(destination), { recursive: true })
+
+	for (const finding of stop.findings) {
+		lane_ledger_write.append(destination, {
+			at,
+			issue: stop.issue,
+			stage: stop.stage,
+			...finding,
+			...mark,
+		})
+	}
+}
+
+// Best-effort, as the lane ledger is: a record must never fail the stop it records.
+function record(stop: ReviewStop, log_path: string | undefined = target()): void {
+	if (log_path === undefined || stop.findings.length === 0) return
+
+	try {
+		write(log_path, stop)
+	} catch {
+		// Recording is best-effort: a failed append is dropped rather than raised into the ship's stop.
+	}
+}
+
+function parse_line(line: string): StopLine | undefined {
+	return stop_line_schema.safeParse(json_value.parse_or_undefined(line)).data
+}
+
+function is_present(line: StopLine | undefined): line is StopLine {
+	return line !== undefined
+}
+
+// Every recorded finding, oldest first; a malformed line — a write cut short — is skipped.
+function read(log_path: string | undefined = target()): ReadonlyArray<StopLine> {
+	const raw = log_path === undefined ? undefined : stamp_file.read_stamp_text(log_path)
+
+	if (raw === undefined) return []
+
+	return raw
+		.split(LINE_SEPARATOR)
+		.map((line) => parse_line(line.trim()))
+		.filter(is_present)
+}
+
+const review_stop_log = { read, record, target }
+
+export type { ReviewStop, StopLine }
+export { review_stop_log }

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_stats } from '#scripts/lane/lane-stats'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { review_stop_log, type StopLine } from './review-stop-log'
+
+// `josh review:stops [--period <days>]` — every review finding that stopped a `josh ship` in the last
+// `<days>` (7 by default), one line each, ordered by kind and then file so the findings of one kind and
+// one place sit together for classification (joshuafolkken/kit#4519). The write half is
+// `review-stop-log.ts`, called on every ship stop.
+
+const OPTIONS = { period: { type: 'string' } } as const
+const DEFAULT_PERIOD_DAYS = 7
+const USAGE = 'usage: josh review:stops [--period <days>]'
+const NO_SENTENCE = '(no sentence)'
+const DATE_LENGTH = 10
+// `process.argv` holds the runtime and the script before the command's own arguments.
+const FIRST_ARGUMENT = 2
+
+interface StopsContext {
+	log_path?: string | undefined
+	now_ms?: number
+}
+
+// An unknown flag or a period that is not a positive whole number of days is refused, never defaulted.
+function period_of(argv: ReadonlyArray<string>): number | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	if (values === undefined) return undefined
+
+	return cli_flags.to_positive(values.period ?? String(DEFAULT_PERIOD_DAYS))
+}
+
+function compare(left: StopLine, right: StopLine): number {
+	const by_kind = left.kind.localeCompare(right.kind)
+
+	if (by_kind !== 0) return by_kind
+
+	return left.location.localeCompare(right.location) || left.at.localeCompare(right.at)
+}
+
+function line_of(stop: StopLine): string {
+	const sentence = stop.sentence === '' ? NO_SENTENCE : stop.sentence
+	const where = `${session_cite.issue(stop.issue)} ${stop.stage} ${stop.at.slice(0, DATE_LENGTH)}`
+
+	return `${stop.kind}  ${stop.location}  ${where} — ${sentence}`
+}
+
+function format_report(stops: ReadonlyArray<StopLine>, period_days: number): string {
+	const period = `the last ${String(period_days)} day(s)`
+
+	if (stops.length === 0) return `no review stop findings recorded in ${period}`
+
+	const body = stops.toSorted(compare).map((stop) => line_of(stop))
+
+	return [`review stop findings in ${period} (${String(stops.length)}):`, ...body].join('\n')
+}
+
+function run(argv: ReadonlyArray<string>, context: StopsContext = {}): number {
+	const period_days = period_of(argv)
+
+	if (period_days === undefined) {
+		console.error(USAGE)
+
+		return 1
+	}
+
+	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
+	const stopped = review_stop_log.read(context.log_path).filter((line) => line.fixed !== true)
+	const stops = lane_stats.in_window(stopped, window)
+
+	console.info(format_report(stops, period_days))
+
+	return 0
+}
+
+function main(): void {
+	process.exitCode = run(process.argv.slice(FIRST_ARGUMENT))
+}
+
+const review_stops_cli = { format_report, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { review_stops_cli }

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { lane_session_broker } from '#scripts/lane/lane-session-broker'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
+import { review_attest, type ReviewSlot } from './review-attest'
+
+// `josh review:submit` — the one write path for a ship reviewer's findings (joshuafolkken/kit#4799).
+// The reviewer pipes its findings here on stdin, and this command writes them to the slot's findings
+// file under the same key the supervisor reads it by (`run-ship-reviewer.ts`), so no path is ever
+// copied out of a prompt. A line outside the `review:record` grammar is refused before anything is
+// written, while the reviewer can still fix it.
+//
+// **A clean review is said with `--none`, never with empty stdin**: a reviewer that forgot the pipe,
+// or ran on a terminal, sends nothing, and reading that as clean would lose every finding it had.
+
+const ARGV_OFFSET = 2
+const INTERACTION_FLAG = '--interaction'
+const NONE_FLAG = '--none'
+const FLAGS: ReadonlySet<string> = new Set([INTERACTION_FLAG, NONE_FLAG])
+const USAGE =
+	'Usage: josh review:submit [--interaction] < findings | josh review:submit [--interaction] --none'
+const EMPTY_NOTE = `nothing written — no findings on stdin; a review with none passes ${NONE_FLAG}`
+const NONE_WITH_FINDINGS_NOTE = `nothing written — ${NONE_FLAG} was passed with findings on stdin`
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface Submission {
+	slot: ReviewSlot
+	is_none: boolean
+}
+
+function submission_of(argv: ReadonlyArray<string>): Submission | undefined {
+	const is_valid = argv.every((flag) => FLAGS.has(flag)) && new Set(argv).size === argv.length
+
+	if (!is_valid) return undefined
+
+	const { CODE, INTERACTION } = review_attest.REVIEW_SLOT
+
+	return {
+		slot: argv.includes(INTERACTION_FLAG) ? INTERACTION : CODE,
+		is_none: argv.includes(NONE_FLAG),
+	}
+}
+
+function grammar_refusal(findings: string): string | undefined {
+	const verdict = run_ship_review.read_verdict(findings)
+
+	return verdict.kind === run_ship_review.VERDICT.INVALID
+		? `nothing written — ${verdict.note}`
+		: undefined
+}
+
+// The refusal for stdin that does not match the flags, or for a line outside the grammar.
+function refusal_of(submission: Submission, findings: string): string | undefined {
+	const is_empty = findings.trim() === ''
+
+	if (submission.is_none) return is_empty ? undefined : NONE_WITH_FINDINGS_NOTE
+
+	return is_empty ? EMPTY_NOTE : grammar_refusal(findings)
+}
+
+function write(submission: Submission, findings: string): string {
+	const { slot, is_none } = submission
+	const target = lane_session_broker.review_paths(PROJECT_ROOT, slot).findings
+
+	stamp_file.write_text_stamp(target, is_none ? '' : findings)
+
+	return is_none
+		? `the ${slot} review is submitted with no findings.`
+		: `the ${slot} review's findings are submitted.`
+}
+
+function run(argv: ReadonlyArray<string>, findings: string): number {
+	const submission = submission_of(argv)
+	const refusal = submission === undefined ? USAGE : refusal_of(submission, findings)
+
+	if (submission === undefined || refusal !== undefined) {
+		console.error(refusal)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(write(submission, findings))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(): Promise<void> {
+	const findings = process.stdin.isTTY ? '' : await text(process.stdin)
+
+	process.exitCode = run(process.argv.slice(ARGV_OFFSET), findings)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+const review_submit_cli = { EMPTY_NOTE, USAGE, run }
+
+export { review_submit_cli }

package/scripts/review/review-tree.ts

@@ -1,8 +1,6 @@
-import { readFileSync } from 'node:fs'
-import path from 'node:path'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
 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.
@@ -18,15 +16,7 @@ import { observation_ledger } from '#scripts/observations/observation-ledger'
 // A path the change lists but the working tree does not hold — deleted, or renamed away. Recorded
 // rather than dropped: a delete applied by a fix is part of the fix delta, and a dropped entry would
 // read as "unchanged" on the comparison.
-const ABSENT_DIGEST = 'absent'
-
-function digest_of(root: string, relative: string): string {
-	try {
-		return stamp_file.digest(readFileSync(path.join(root, relative)))
-	} catch {
-		return ABSENT_DIGEST
-	}
-}
+const ABSENT_DIGEST = input_fingerprint.ABSENT
 
 // 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.
@@ -39,11 +29,10 @@ function digest_of(root: string, relative: string): string {
 // undo then moved the tree under both. 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
-		.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)]))
+	return input_fingerprint.of_files(
+		root,
+		paths.filter((relative) => !observation_ledger.is_ledger_path(relative)),
+	)
 }
 
 // **The root is asked of git, never taken from `process.cwd()` — nor from `PROJECT_ROOT`, which is