@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,60 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { run_ship_probe } from '#scripts/run/ship/run-ship-probe'
+import { review_comment_round } from './review-comment-round'
+import type { Finding } from './review-finding-ledger'
+import { review_record_code_round } from './review-record-code-round'
+
+// The issue-comment half of `josh review:record`: a round kept on the issue rather than in the
+// observation ledger (`review-comment-round.ts` carries it there once the issue closes).
+
+const FAILURE_EXIT_CODE = 1
+const AFTER_PUSH_LINE =
+	'The branch is pushed and the tree is clean, so this round is recorded on the issue, not in the ledger — a ledger line would need a push of its own and restart CI.'
+
+interface CommentRound {
+	issue: number
+	lines: ReadonlyArray<string>
+	root: string
+	findings: ReadonlyArray<Finding>
+}
+
+// **A comment that could not be posted fails the record**: it is the round's only copy, so a
+// swallowed refusal would read as a recorded round that exists nowhere.
+async function post(issue: number, lines: ReadonlyArray<string>): Promise<number> {
+	try {
+		const url = await git_gh_issue_write.issue_comment(
+			String(issue),
+			review_comment_round.body_of(lines),
+		)
+
+		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
+
+		return 0
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+// **A code round recorded once the branch is pushed and the tree clean goes to the issue unasked**
+// (joshuafolkken/kit#4907): `josh run:review` pushed at the first green gate, and a ledger line now
+// would ride no commit of the run's but a push of its own, restarting CI. `--check` reads the issue's
+// comment rounds too (`review-record.ts`). The round still stamps its tree, so `josh ship` reuses it
+// as round 1.
+async function is_after_push(): Promise<boolean> {
+	return await run_ship_probe.is_pushed_clean()
+}
+
+async function post_after_push(round: CommentRound): Promise<number> {
+	console.info(AFTER_PUSH_LINE)
+	const code = await post(round.issue, round.lines)
+
+	if (code === 0) await review_record_code_round.follow(round.issue, round.root, round.findings)
+
+	return code
+}
+
+const review_record_comment = { is_after_push, post, post_after_push }
+
+export { review_record_comment }

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

@@ -0,0 +1,35 @@
+import { error_text } from '#scripts/lib/error-message'
+import { review_interaction } from './review-interaction'
+
+// What `josh review:record` says about the interaction review (`review-interaction.ts`).
+//
+// **A round-1 fix can make the pass due after its brief opened** (joshuafolkken/kit#4835): the fix
+// reaches the run tooling the original change did not, so round 1 opened with `/code-review`'s brief
+// alone. A recorded code round reads the pass's status over the fixed tree and names its brief, so the
+// lane runs it before `josh ship` instead of the ship's review stage running it alone and stopping on
+// its finding. A status git could not read prints nothing — the merge gate still refuses a missing pass.
+
+const NOT_REQUIRED_LINE =
+	'No interaction review is due: the change touches no run tooling, or this checkout keeps no ledger.'
+const DUE_HEAD = 'Interaction review now due'
+
+// An interaction reviewer that already ran beside round 1 is only recorded, never run twice.
+function due_line(issue: number): string {
+	return `${DUE_HEAD}: this round’s change touches the run tooling and no interaction pass is recorded. Before \`josh ship\`, record it with \`pnpm josh review:record --interaction --issue ${String(issue)} [<finding> ...]\` — if no interaction reviewer ran beside this round, first open its brief with \`pnpm josh review:brief --interaction\` and run that \`reviewer\` — so a finding is fixed in this lane rather than stopping the ship.`
+}
+
+async function report_due(issue: number, root: string): Promise<void> {
+	try {
+		if ((await review_interaction.status(issue, root)) === 'missing') console.info(due_line(issue))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_interaction.report_due', error)
+	}
+}
+
+const review_record_interaction = {
+	due_line,
+	NOT_REQUIRED_LINE,
+	report_due,
+}
+
+export { review_record_interaction }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { review_record_cli } from './review-record-cli'
+
+// The `josh review:record` entry, kept apart from `review-record-cli.ts` because `run-ship-review.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await review_record_cli.run(process.argv.slice(ARGV_OFFSET), new Date())
+}

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

@@ -0,0 +1,108 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { run_review_join_read, type JoinVerdict } from '#scripts/run/review/run-review-join-read'
+import { run_review_pinned_join } from '#scripts/run/review/run-review-pinned-join'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// What `josh review:record` does about the background `josh test:pinned` (joshuafolkken/kit#4834).
+//
+// **A round-1 fix can add hunks the check never read**: `josh run:review` launched it on the briefed
+// tree, and its join closed before the fix. The ship's pre-detach was then the first to name the fixed
+// tree's unpinned places, and stopped on them. A recorded code round compares the fixed tree with the
+// launch's and, where they differ, starts the check again with the launch's `--unpinned-ok` reason and
+// says who reads its answer. **Nothing waits on it in the foreground** (joshuafolkken/kit#4895): the
+// ship's pre-detach reads that same check's answer on that tree rather than running its own
+// (`run-review-pinned-join.ts`). A foreground read stalled the lane for minutes, and pinning what it
+// named moved the tree again under the next probe.
+//
+// **The same tree starts nothing**, and so does a tree either side could not read, or a checkout with
+// no launch. The fix's first `josh check:related` runs this same restart (joshuafolkken/kit#4948), so a
+// record on the tree it checked takes over the check already running there. `check:related` alone
+// waits on the check it started (joshuafolkken/kit#4987), within a bound that keeps the verdict line
+// under a foreground Bash call's cap (`check-related-pinned.ts`).
+
+function started_line(): string {
+	return `test:pinned restarted in the background on the tree this round's fixes moved. Where it names unpinned places, the ship's pre-detach stops on them: pin each with a test that turns red without it, or ship with \`--unpinned-ok "<reason>"\`.`
+}
+
+// `root` is the checkout `josh run:review` keyed its launch to: the ledger root `review:record` writes
+// under is the same working directory, and a test's temporary root holds no launch. Answers whether a
+// check was started.
+async function restart_if_moved(root: string = PROJECT_ROOT): Promise<boolean> {
+	try {
+		const is_started = await run_review_pinned_join.restart_if_moved(root)
+
+		if (is_started) console.info(started_line())
+
+		return is_started
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.restart_if_moved', error)
+
+		return false
+	}
+}
+
+// **A join the lane skipped is read here** (joshuafolkken/kit#5212): `josh run:review --join` was never
+// run, so the unpinned places would surface only as the ship's pre-detach failure. It reads only an
+// answer already left on this tree, so nothing waits on it either. A read that stops nothing prints
+// nothing, and a join already read changes nothing.
+const CHOICE_LINE =
+	'Unpinned before the ship: pin each place above with a test that turns red without it, or ship with `--unpinned-ok "<reason>"`.\n'
+
+function show_stop(joined: JoinVerdict | undefined): void {
+	if (joined?.is_stop !== true) return
+	console.info(test_pinned_logic.report_text(joined.summary, CHOICE_LINE).trimEnd())
+}
+
+async function read_skipped_join(root: string = PROJECT_ROOT): Promise<void> {
+	try {
+		if (run_review_join_read.is_due(root)) show_stop(await run_review_join_read.read_finished(root))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.read_skipped_join', error)
+	}
+}
+
+// Whether the lane's code round is on the ledger: from then on `review:record` owns the restart, behind
+// its own handover guard.
+async function is_round_recorded(root: string): Promise<boolean> {
+	const issue = lane_child_marker.marked_issue()
+	if (issue === undefined) return false
+	const content = await observation_ledger_home.read(root)
+
+	return content !== undefined && review_finding_ledger.has_issue_record(content, Number(issue))
+}
+
+// `josh check:related`'s restart (joshuafolkken/kit#4948) runs only in a lane child outside a ship's
+// supervisor and before its round 1 is recorded: a launch record outlives its issue in a reused
+// checkout, and a child relaunched after a ship stop may re-detach without `--review`, which reads no
+// answer.
+async function is_restartable_before_record(root: string): Promise<boolean> {
+	if (!lane_child_marker.is_child_of(root) || run_ship_detach.is_supervised()) return false
+
+	return !(await is_round_recorded(root))
+}
+
+// Answers whether a check was started, so `check:related` waits on its answer (joshuafolkken/kit#4987).
+async function restart_in_lane(root: string = PROJECT_ROOT): Promise<boolean> {
+	try {
+		return (await is_restartable_before_record(root)) && (await restart_if_moved(root))
+	} catch (error) {
+		error_text.trace_swallowed('review_record_pinned.restart_in_lane', error)
+
+		return false
+	}
+}
+
+const review_record_pinned = {
+	CHOICE_LINE,
+	read_skipped_join,
+	restart_if_moved,
+	restart_in_lane,
+	started_line,
+}
+
+export { review_record_pinned }

package/scripts/review/review-record.ts

@@ -1,5 +1,6 @@
 import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_comment_round } from './review-comment-round'
 import { review_finding_ledger } from './review-finding-ledger'
 
 // The gate that refuses a merge until the `/code-review` round was recorded.
@@ -33,14 +34,37 @@ interface RecordVerdict {
 // lane. Every file of the directory is read, so the round is found whichever
 // file holds it; a directory that is not there answers `undefined`, a ledger this checkout does not
 // keep, which becomes `not-required`.
+//
+// **A round recorded on the issue counts too** (`josh review:record --comment`): a round that ran after
+// the branch was pushed keeps its lines there so CI does not restart (joshuafolkken/kit#4907). Comments
+// that could not be read are no record — the refusal stands.
+type CommentLines = (issue: number) => Promise<ReadonlyArray<string>>
+
+async function has_comment_record(issue: number, read: CommentLines): Promise<boolean> {
+	try {
+		const lines = await read(issue)
+
+		return review_finding_ledger.has_issue_record(lines.join('\n'), issue)
+	} catch {
+		return false
+	}
+}
+
+async function is_recorded(content: string, issue: number, read: CommentLines): Promise<boolean> {
+	if (review_finding_ledger.has_issue_record(content, issue)) return true
+
+	return await has_comment_record(issue, read)
+}
+
 async function check(
 	issue: number,
 	root: string = observation_ledger_home.ledger_root(),
+	read_comment_lines: CommentLines = review_comment_round.issue_lines,
 ): Promise<RecordVerdict> {
 	const content = await observation_ledger_home.read(root)
 
 	if (content === undefined) return { status: 'not-required' }
-	if (review_finding_ledger.has_issue_record(content, issue)) return { status: 'ok', issue }
+	if (await is_recorded(content, issue, read_comment_lines)) return { status: 'ok', issue }
 
 	return { status: 'missing', issue }
 }

package/scripts/review/review-reviewed-tree.ts

@@ -0,0 +1,307 @@
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { moved_paths, type MovedParts } from '#scripts/gate/moved-paths'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { release_approval_prune } from '#scripts/release/release-approval-prune'
+import { test_declared_logic } from '#scripts/test/test-declared-logic'
+import { review_attest } from './review-attest'
+import { review_checkout, type ReviewCheckout } from './review-checkout'
+import { review_round_one_blobs } from './review-round-one-blobs'
+import { review_round2 } from './review-round2'
+import { review_stamps } from './review-stamps'
+
+// The tree a recorded `/code-review` round stands for: the changed files as they were when
+// `review:record` wrote the round, its fixes included (joshuafolkken/kit#4620). A lane reviews before
+// `josh ship`, so the ship's round 1 asks this record whether the tree moved since: unmoved, the
+// recorded round is the ship's; moved only where round 2 reads, it is still the ship's and round 2
+// reads the delta (joshuafolkken/kit#4878); else round 1 reads the delta from here.
+//
+// **Taken at the record, not the brief**. A round that fixed findings approved its own edits, so the
+// briefed tree is not what its verdict covers: a file reverted to the briefed bytes would drop out of a
+// delta measured from there with its finding back in it.
+
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/u
+// No file's digest: a path recorded with it never matches the tree, whether the change holds it or not.
+const UNSETTLED_DIGEST = 'unsettled'
+
+// **A file a recorded High cites is recorded as unsettled**: a High is never fixed in place, so the
+// round's verdict does not stand for that file. Its digest matches no tree, so it always reads as moved
+// — the tree is never held, and round 2 reads its fix where its delta holds it (joshuafolkken/kit#4941);
+// anywhere else round 1 reads it again rather than passing over the finding it still holds. A file
+// outside the change (a reader the change broke) is recorded too: left out, it would be absent on both
+// sides and read as unmoved.
+function settled_files(
+	files: Record<string, string>,
+	unsettled: ReadonlyArray<string>,
+): Record<string, string> {
+	const cited = unsettled.map((file): [string, string] => [
+		file.replace(LINE_SUFFIX, ''),
+		UNSETTLED_DIGEST,
+	])
+
+	return { ...files, ...Object.fromEntries(cited) }
+}
+
+// Swallowed: no record re-runs the ship's round 1 over the whole change — wider, never narrower. The
+// blobs let a sync's change to a covered document carry onto the new base (`carried_paths`).
+async function record(unsettled: ReadonlyArray<string> = []): Promise<void> {
+	try {
+		const { files, base } = await gate_tree.read_gate_tree()
+		const blobs = review_round_one_blobs.capture(Object.keys(files))
+
+		review_stamps.reviewed_stamp.write(settled_files(files, unsettled), undefined, base, blobs)
+	} catch {
+		/* no record widens the next round rather than narrowing it */
+	}
+}
+
+// An empty tree or an unresolved base is git not answering, never "nothing moved".
+//
+// **A base the ship's sync moved is unmoved for every path the default branch left alone**
+// (joshuafolkken/kit#4829): with every recorded digest matching, only a synced path the round covers
+// changes what it read — unless round 2 would not execute it and main alone moved it
+// (joshuafolkken/kit#4984). Main's other paths are the scoped pair's, the gate's and CI's to check.
+//
+// **A `josh metrics` approval the branch rewrote is no move** (joshuafolkken/kit#4788): the ship's
+// pre-detach re-record writes it after `review:record`, and it is data `josh metrics` derives and the
+// gate's own metrics step checks, never what the round reviewed. An approval a recorded High cites
+// stays unsettled, so it still reads as moved.
+function is_rerecorded_approval(stamp: FileMapStamp, path: string): boolean {
+	return release_approval_prune.is_approval(path) && stamp.files[path] !== UNSETTLED_DIGEST
+}
+
+// **A test added or edited since the record is no move** (joshuafolkken/kit#4874): `chain-rule.md`
+// step 0 pins each `test:pinned` unpinned place after `review:record`, and a test changes no runtime
+// the round's verdict covers; round 2 still reads the test delta (`review-round2.ts` keeps tests live).
+// A test removed since, or one a recorded High cites, still reads as moved.
+function is_pinning_test(stamp: FileMapStamp, tree: GateTree, path: string): boolean {
+	const is_settled = Object.hasOwn(tree.files, path) && stamp.files[path] !== UNSETTLED_DIGEST
+
+	return is_settled && test_declared_logic.is_test_file(path)
+}
+
+function is_no_move(stamp: FileMapStamp, tree: GateTree, path: string): boolean {
+	return is_rerecorded_approval(stamp, path) || is_pinning_test(stamp, tree, path)
+}
+
+// How the tree stands against the record: `held` — nothing the round read moved; `delta` — every move
+// is one round 2 reads (joshuafolkken/kit#4878); `unsettled` — any other move, or git did not answer.
+const MOVEMENT = { DELTA: 'delta', HELD: 'held', UNSETTLED: 'unsettled' } as const
+
+type Movement = (typeof MOVEMENT)[keyof typeof MOVEMENT]
+
+// The movement, and on `unsettled` the condition that decided it, with the path that met it where one
+// did — printed by `review:record --check` so a lane reads why the ship reviews round 1 again
+// (joshuafolkken/kit#4941).
+interface Standing {
+	movement: Movement
+	cause?: string
+}
+
+const CAUSE = {
+	NO_RECORD: 'no reviewed tree was recorded',
+	SKIPPED:
+		'a move round 2 would not read — documentation, a prompt, an inert path, a revert to the briefed bytes, or a file outside the change',
+	SYNCED: 'the default branch changed a file the round covers',
+	UNFIXED:
+		"a file a recorded High cites still holds its round-1 brief bytes, so no fix is in round 2's delta",
+	UNATTESTED: 'the round was not attested on this branch',
+	UNREAD: 'git did not answer',
+} as const
+
+function unsettled_by(cause: string, path?: string): Standing {
+	return { movement: MOVEMENT.UNSETTLED, cause: path === undefined ? cause : `${cause}: ${path}` }
+}
+
+// **A covered file only the default branch moved is no move where round 2 would not execute it**
+// (joshuafolkken/kit#4984): documentation, a prompt or an inert path — a generated usage heading main
+// rewrote beside the lane's own. Its recorded blob carried onto the new base reproduces the file now
+// only where main's change is all that moved it (`review-round-one-blobs.ts`); a lane edit since the
+// record, a carry git cannot make, or a path a recorded High cites stays moved.
+function is_carry_candidate(stamp: FileMapStamp, path: string): boolean {
+	const is_settled = Object.hasOwn(stamp.files, path) && stamp.files[path] !== UNSETTLED_DIGEST
+
+	return is_settled && review_round2.is_unexecuted(path, [])
+}
+
+function carried_paths(stamp: FileMapStamp, tree: GateTree, parts: MovedParts): Array<string> {
+	const candidates = parts.synced.filter((path) => is_carry_candidate(stamp, path))
+	const { blobs, base: from } = stamp
+	const delta =
+		candidates.length === 0
+			? undefined
+			: review_round_one_blobs.carried_delta({ blobs, from, to: tree.base, paths: candidates })
+
+	return delta === undefined ? [] : candidates.filter((path) => !delta.includes(path))
+}
+
+function moved_files(stamp: FileMapStamp, tree: GateTree, parts: MovedParts): Array<string> {
+	return parts.changed.filter((path) => !is_no_move(stamp, tree, path))
+}
+
+// **Round 2 reads a move only where its own delta holds it**: it diffs from the round-1 brief's stamp
+// (`briefed`) and passes over documentation, prompts and inert paths (`review-round2.ts`), so a file
+// reverted to the briefed bytes, or one round 2 skips, would ship unread. A path a recorded High cites
+// is read there too — its fix is the delta round 2 verifies, and its brief names the file as a High's
+// fix (`review-brief.ts`). A default-branch change to a covered file is outside round 2's carried delta.
+function is_read_by_round_two(
+	path: string,
+	tree: GateTree,
+	briefed: FileMapStamp | undefined,
+): boolean {
+	if (review_round2.is_unexecuted(path, [])) return false
+
+	return briefed?.files[path] !== tree.files[path]
+}
+
+// An unread High-cited file round 2 would execute is one whose fix has not landed, not a revert.
+function unread_cause(stamp: FileMapStamp, path: string): string {
+	const is_cited = stamp.files[path] === UNSETTLED_DIGEST
+
+	return is_cited && !review_round2.is_unexecuted(path, []) ? CAUSE.UNFIXED : CAUSE.SKIPPED
+}
+
+function moved_standing(
+	stamp: FileMapStamp,
+	moved: ReadonlyArray<string>,
+	tree: GateTree,
+	briefed: FileMapStamp | undefined,
+): Standing {
+	if (moved.length === 0) return { movement: MOVEMENT.HELD }
+
+	const unread = moved.find((path) => !is_read_by_round_two(path, tree, briefed))
+
+	if (unread === undefined) return { movement: MOVEMENT.DELTA }
+
+	return unsettled_by(unread_cause(stamp, unread), unread)
+}
+
+async function standing(
+	stamp: FileMapStamp,
+	tree: GateTree,
+	briefed?: FileMapStamp,
+): Promise<Standing> {
+	const parts = await moved_paths.moved_parts(stamp, tree)
+
+	if (parts === undefined) return unsettled_by(CAUSE.UNREAD)
+
+	const carried = carried_paths(stamp, tree, parts)
+	const synced = parts.synced.find(
+		(path) => Object.hasOwn(stamp.files, path) && !carried.includes(path),
+	)
+
+	if (synced !== undefined) return unsettled_by(CAUSE.SYNCED, synced)
+
+	const moved = moved_files(stamp, tree, parts).filter((path) => !carried.includes(path))
+
+	return moved_standing(stamp, moved, tree, briefed)
+}
+
+async function movement(
+	stamp: FileMapStamp,
+	tree: GateTree,
+	briefed?: FileMapStamp,
+): Promise<Movement> {
+	const answer = await standing(stamp, tree, briefed)
+
+	return answer.movement
+}
+
+async function is_unmoved(stamp: FileMapStamp, tree: GateTree): Promise<boolean> {
+	return (await movement(stamp, tree)) === MOVEMENT.HELD
+}
+
+// **Only a review attested on this branch is reused**, as `resume_point` narrows from no other: the
+// reuse skips the ship's own `review:attest --check`, so a round recorded over a review that read
+// another checkout, or never finished, would otherwise ship unreviewed.
+async function standing_here(): Promise<Standing> {
+	const stamp = review_stamps.reviewed_stamp.read()
+
+	if (stamp === undefined) return unsettled_by(CAUSE.NO_RECORD)
+
+	const checkout = await review_checkout.read_checkout()
+
+	if (!review_attest.is_attested_on(checkout, checkout.root)) return unsettled_by(CAUSE.UNATTESTED)
+
+	const tree = await gate_tree.read_gate_tree()
+
+	return await standing(stamp, tree, review_stamps.round_one_stamp.read())
+}
+
+// The files a recorded High cites — the ones the round-2 brief names as a High's fix to read whole.
+function high_cited(): ReadonlyArray<string> {
+	const files = review_stamps.reviewed_stamp.read()?.files ?? {}
+
+	return Object.keys(files).filter((path) => files[path] === UNSETTLED_DIGEST)
+}
+
+// The record a resumed brief narrows from: written after the brief the pointer names, whose review was
+// attested on this branch. Asked before the next brief mints its pointer, which this record then
+// predates — so it narrows one round, never two.
+function resume_point(checkout: ReviewCheckout): FileMapStamp | undefined {
+	const stamp = review_stamps.reviewed_stamp.read()
+
+	if (stamp === undefined || !review_attest.is_briefed_since(stamp.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	return review_attest.is_attested_on(checkout, checkout.root) ? stamp : undefined
+}
+
+// **A ship's round 1 that stopped on a finding stays its round 1 however the tree moves since**: the
+// tree moves by the fix, and the fix delta is round 2's to verify (joshuafolkken/kit#2964). Reviewed
+// as round 1 again, every stop would cost one more review and one more chance to stop. The marker
+// names the issue, so a checkout that ships another issue next never reuses this one's round.
+const STOPPED_PREFIX = 'josh-review-round1-stopped-'
+
+function stopped_path(): string {
+	return stamp_file.stamp_path(STOPPED_PREFIX, PROJECT_ROOT)
+}
+
+// Written when the ship's round 1 stops on a finding, removed when it ends any other way. A write the
+// temp directory refuses is swallowed: no marker re-runs round 1 — wider, never narrower.
+function mark_stopped(issue: number, is_stopped: boolean): void {
+	if (!is_stopped) {
+		stamp_file.remove_stamp(stopped_path())
+
+		return
+	}
+
+	try {
+		stamp_file.write_text_stamp(stopped_path(), String(issue))
+	} catch {
+		/* no marker reviews round 1 again rather than passing over it */
+	}
+}
+
+function is_stopped_on(issue: number): boolean {
+	return stamp_file.read_stamp_text(stopped_path()) === String(issue)
+}
+
+// The ship drops both records when the issue changed after the recorded round's brief: that round never
+// read the new specification, so the next one reviews the whole change.
+function discard(): void {
+	try {
+		review_stamps.reviewed_stamp.remove()
+		stamp_file.remove_stamp(stopped_path())
+	} catch {
+		/* the temp directory refused the removal; nothing else here can */
+	}
+}
+
+const review_reviewed_tree = {
+	MOVEMENT,
+	discard,
+	high_cited,
+	is_stopped_on,
+	is_unmoved,
+	mark_stopped,
+	movement,
+	record,
+	resume_point,
+	standing_here,
+}
+
+export type { Movement, Standing }
+export { review_reviewed_tree }