@joshuafolkken/kit 1.2116.0 → 1.3000.0

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 }

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

@@ -0,0 +1,157 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cost_pricing } from '#scripts/cost-runtime/cost-pricing'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
+import { z } from 'zod'
+import { review_pair } from './review-pair'
+import { review_pair_log, type PairFinding, type PairSide } from './review-pair-log'
+import { review_record_slot } from './review-record-slot'
+
+// `josh review:pair` — record one paired comparison (joshuafolkken/kit#6902): the Opus reviewer's
+// findings from the code slot, the Sonnet reviewer's from the paired findings file, and each agent's
+// cost from its transcript, appended to `review-pairs.jsonl`. It reads the code slot and writes the
+// ledger alone, so neither `review:attest` nor the merge gate sees the paired result.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NONE_LINE = 'none'
+const USD_DIGITS = 2
+const SEVERITY_PATTERN = /^[^:]+:(?<severity>[^:]+):/u
+const USAGE = 'Usage: josh review:pair --issue <N> --opus-agent <id> --sonnet-agent <id>'
+const OPTIONS = {
+	issue: { type: 'string' },
+	'opus-agent': { type: 'string' },
+	'sonnet-agent': { type: 'string' },
+} as const
+const request_schema = z.object({
+	issue: z.coerce.number().int().positive(),
+	'opus-agent': z.string().min(1),
+	'sonnet-agent': z.string().min(1),
+})
+
+interface AgentCost {
+	model?: string | undefined
+	usd?: number
+}
+
+interface PairSources {
+	opus_text: () => string | undefined
+	sonnet_text: () => string | undefined
+	cost_of: (agent: string) => AgentCost
+	log_path?: string | undefined
+}
+
+interface PairRequest {
+	issue: number
+	opus_agent: string
+	sonnet_agent: string
+}
+
+function refuse(text: string): number {
+	console.error(text)
+
+	return FAILURE_EXIT_CODE
+}
+
+// A delegated unit's transcript is `<session>/subagents/agent-<id>.jsonl` (`cost-transcript.ts`); a
+// headless reviewer the ship or a lane's broker started is a session of its own (joshuafolkken/kit#7020).
+function is_agent_session(session_id: string, agent: string): boolean {
+	return session_id === agent || session_id.endsWith(`/agent-${agent}`)
+}
+
+function agent_cost(agent: string): AgentCost {
+	const directories = cost_transcript.transcript_directories(process.cwd())
+	const file = cost_transcript
+		.list_sessions_across(directories)
+		.find((session) => is_agent_session(session.session_id, agent))
+	if (file === undefined) return {}
+	const { records } = cost_transcript.read_session(file)
+
+	return { model: records[0]?.model, usd: cost_pricing.cost_of(records) }
+}
+
+function to_finding(line: string): PairFinding {
+	const spec = review_record_slot.unmarked(line)
+
+	return { severity: SEVERITY_PATTERN.exec(spec)?.groups?.['severity'] ?? '', line: spec }
+}
+
+// A reviewer's findings text, `none` read as no finding; `undefined` where it is missing or unreadable.
+function findings_of(text: string | undefined): ReadonlyArray<PairFinding> | undefined {
+	const verdict = run_ship_review.read_verdict(text?.trim() === NONE_LINE ? '' : text)
+
+	if (verdict.kind === run_ship_review.VERDICT.INVALID) return undefined
+
+	return verdict.report.map((line) => to_finding(line))
+}
+
+function side(agent: string, text: string | undefined, sources: PairSources): PairSide | undefined {
+	const findings = findings_of(text)
+
+	return findings === undefined
+		? undefined
+		: { agent, ...sources.cost_of(agent), findings: [...findings] }
+}
+
+function request_of(argv: ReadonlyArray<string>): PairRequest | undefined {
+	const values = request_schema.safeParse(cli_flags.arguments_of(argv, OPTIONS)?.values).data
+
+	if (values === undefined) return undefined
+
+	return {
+		issue: values.issue,
+		opus_agent: values['opus-agent'],
+		sonnet_agent: values['sonnet-agent'],
+	}
+}
+
+function dollars(usd: number | undefined): string {
+	return usd === undefined ? '$?' : `$${usd.toFixed(USD_DIGITS)}`
+}
+
+function summary(opus: PairSide, sonnet: PairSide): string {
+	const sides = [
+		`opus ${String(opus.findings.length)} findings ${dollars(opus.usd)}`,
+		`sonnet ${String(sonnet.findings.length)} findings ${dollars(sonnet.usd)}`,
+	]
+
+	return `review:pair recorded — ${sides.join(' · ')}`
+}
+
+function record(request: PairRequest, sources: PairSources): number {
+	const opus = side(request.opus_agent, sources.opus_text(), sources)
+	const sonnet = side(request.sonnet_agent, sources.sonnet_text(), sources)
+
+	if (opus === undefined || sonnet === undefined) return refuse('a reviewer left no findings')
+	const line = { at: new Date().toISOString(), issue: request.issue, opus, sonnet }
+	if (!review_pair_log.record(line, sources.log_path)) return refuse('no ledger to record into')
+	console.info(summary(opus, sonnet))
+
+	return SUCCESS_EXIT_CODE
+}
+
+const SOURCES: PairSources = {
+	opus_text: () => review_record_slot.slot_text(false),
+	sonnet_text: () => stamp_file.read_stamp_text(review_pair.paths().findings),
+	cost_of: agent_cost,
+	log_path: review_pair_log.target(),
+}
+
+function run(argv: ReadonlyArray<string>, sources: PairSources = SOURCES): number {
+	const request = request_of(argv)
+
+	return request === undefined ? refuse(USAGE) : record(request, sources)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = run(process.argv.slice(ARGV_OFFSET))
+}
+
+const review_pair_cli = { agent_cost, findings_of, is_agent_session, run }
+
+export type { PairSources }
+export { review_pair_cli }

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

@@ -0,0 +1,75 @@
+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 { z } from 'zod'
+
+// `review-pairs.jsonl` — one line per paired comparison (joshuafolkken/kit#6902): the Opus and the
+// Sonnet reviewer's findings on the same round-1 brief, each with its severity, and each reviewer's
+// cost. It lives in the git common directory beside `review-stops.jsonl`, so it outlives the lane
+// worktree that recorded it. Nothing that gates reads it.
+
+const LOG_FILE = 'review-pairs.jsonl'
+const LINE_SEPARATOR = '\n'
+const finding_schema = z.object({ severity: z.string(), line: z.string() })
+const side_schema = z.object({
+	agent: z.string(),
+	model: z.string().optional(),
+	usd: z.number().optional(),
+	findings: z.array(finding_schema),
+})
+const pair_line_schema = z.object({
+	at: z.string(),
+	issue: z.number(),
+	opus: side_schema,
+	sonnet: side_schema,
+})
+
+type PairFinding = z.infer<typeof finding_schema>
+type PairSide = z.infer<typeof side_schema>
+type PairLine = z.infer<typeof pair_line_schema>
+
+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 record(line: PairLine, log_path: string | undefined = target()): boolean {
+	if (log_path === undefined) return false
+	mkdirSync(path.dirname(log_path), { recursive: true })
+	lane_ledger_write.append(log_path, line)
+
+	return true
+}
+
+function parse_line(line: string): PairLine | undefined {
+	return pair_line_schema.safeParse(json_value.parse_or_undefined(line)).data
+}
+
+function is_present(line: PairLine | undefined): line is PairLine {
+	return line !== undefined
+}
+
+// Every recorded comparison, oldest first; a malformed line — a write cut short — is skipped.
+function read(log_path: string | undefined = target()): ReadonlyArray<PairLine> {
+	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_pair_log = { read, record, target }
+
+export type { PairFinding, PairLine, PairSide }
+export { review_pair_log }

package/scripts/review/review-pair-session.ts

@@ -0,0 +1,98 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
+import { detached_launch } from '#scripts/run/detached-launch'
+import { z } from 'zod'
+import { review_pair } from './review-pair'
+
+// The paired reviewer beside a round 1 the ship runs (joshuafolkken/kit#7020): the ship pairs its code
+// brief with `review_pair.offer`, and whoever starts the code reviewer — the ship itself or the lane's
+// broker — starts this one beside it. **It never gates**: a failed start or run is only noted, and
+// `josh review:pair` compares the two headless sessions by the ids their stream-json logs open with.
+
+type LaunchEnvironment = Readonly<Record<string, string | undefined>>
+
+const PAIR_COMMAND = 'review:pair'
+const OBJECT_OPENING = '{'
+const record_schema = z.looseObject({})
+const init_schema = z.object({
+	type: z.literal('system'),
+	subtype: z.literal('init'),
+	session_id: z.string().min(1),
+})
+
+function note(text: string): void {
+	process.stderr.write(`paired reviewer: ${text}\n`)
+}
+
+function session_in(line: string): string | undefined {
+	if (!line.startsWith(OBJECT_OPENING)) return undefined
+	const record = parse_json.parse_json_object_or_undefined(line, record_schema)
+
+	return init_schema.safeParse(record).data?.session_id
+}
+
+// A log is appended to across launches, so its last session is the latest one.
+function session_of(log_path: string): string | undefined {
+	const lines = stamp_file.read_stamp_text(log_path)?.split('\n') ?? []
+
+	return lines.map((line) => session_in(line.trim())).findLast((id) => id !== undefined)
+}
+
+async function run(directory: string, environment: LaunchEnvironment): Promise<void> {
+	const { brief, log } = review_pair.paths(directory)
+	const opening = review_pair.opening(brief)
+	const built = agent_argv.with_profile_in(opening, review_pair.PAIRED_PROFILE, directory)
+
+	if (built.kind === 'rejected') {
+		note(`not started — ${built.note}`)
+
+		return
+	}
+
+	stamp_file.remove_stamp(log)
+	const request = {
+		argv: built.argv,
+		cwd: directory,
+		log_path: log,
+		profile: built.profile,
+		env: environment,
+	}
+	const result = await detached_launch.launch_attached(request, note)
+
+	if (result.kind === 'failed') note(`not started — ${result.note}`)
+}
+
+// Started only while the round is paired, and settled even when it throws: the round waits on it so
+// the pair can be recorded, but never fails with it.
+async function launch(directory: string, environment: LaunchEnvironment): Promise<void> {
+	if (!review_pair.is_offered(directory)) return
+
+	try {
+		await run(directory, environment)
+	} catch (error) {
+		note(`failed — ${error_text.message_of(error)}`)
+	}
+}
+
+// The `josh review:pair` argv for a paired round that ran, or `undefined` when it was unpaired or a
+// session left no id to compare.
+function pair_argv(
+	issue: string,
+	code_log: string,
+	directory: string,
+): ReadonlyArray<string> | undefined {
+	if (!review_pair.is_offered(directory)) return undefined
+	const opus = session_of(code_log)
+	const sonnet = session_of(review_pair.paths(directory).log)
+
+	if (opus === undefined || sonnet === undefined) return undefined
+
+	return [PAIR_COMMAND, '--issue', issue, '--opus-agent', opus, '--sonnet-agent', sonnet]
+}
+
+const review_pair_session = { launch, pair_argv, session_of }
+
+export type { LaunchEnvironment }
+export { review_pair_session }

package/scripts/review/review-pair.ts

@@ -0,0 +1,112 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_prompt_level } from './review-prompt-level'
+import { review_round } from './review-round'
+
+// The paired comparison review (joshuafolkken/kit#6902): with `JOSH_REVIEWER_PAIRED=1`, round 1's code
+// brief is copied to a paired brief that a Sonnet reviewer reads beside the Opus one, so the two
+// detections can be compared on the same brief. **The paired reviewer is recorded, never gating**: its
+// brief tells it to skip `review:attest` and `review:submit` and write its findings to a file of its own,
+// which only `josh review:pair` reads — no review slot, attest or merge check reads it.
+
+const PAIRED_ENV = 'JOSH_REVIEWER_PAIRED'
+const ENABLED_VALUE = '1'
+const BRIEF_PREFIX = 'josh-review-paired-brief-'
+const FINDINGS_PREFIX = 'josh-review-paired-findings-'
+const LOG_PREFIX = 'josh-review-paired-log-'
+const PAIRED_PROFILE = agent_role_profile.VERIFICATION_PROFILES.anthropic
+
+interface PairedPaths {
+	brief: string
+	findings: string
+	log: string
+}
+
+function is_enabled(environment: NodeJS.ProcessEnv = process.env): boolean {
+	return environment[PAIRED_ENV] === ENABLED_VALUE
+}
+
+function paths(directory: string = PROJECT_ROOT): PairedPaths {
+	return {
+		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
+		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
+		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
+	}
+}
+
+// The override sits right under the level line, ahead of the attest and submit steps it cancels: a
+// `reviewer` agent's own definition also tells it to submit, and a paired submit would overwrite the code
+// slot the merge gate reads.
+function paired_brief(text: string, findings: string): string {
+	const [level = '', ...rest] = text.split('\n')
+
+	return [
+		level,
+		'',
+		'## Paired comparison run — recorded only, never gating',
+		'',
+		`This overrides every attest and submit step below and your agent definition: never run \`review:attest\` or \`review:submit\`. Write your findings to ${findings}, one per line as \`<category>:<severity>:<file>[:<line>] — <sentence>\`, or the single line \`none\`.`,
+		'',
+		...rest,
+	].join('\n')
+}
+
+function paired_opening(brief: string): string {
+	return [
+		`${review_prompt_level.opening(brief)}Review this checkout as a paired /code-review, recorded only: read the review brief at ${brief}`,
+		'and follow its first section over everything else — never run review:attest or review:submit.',
+		'Review it yourself in this session and never launch a second reviewer.',
+	].join(' ')
+}
+
+function launch_note(brief: string): string {
+	const opening = paired_opening(brief)
+
+	return [
+		`paired brief: ${brief}`,
+		`paired model: ${PAIRED_PROFILE.model} · effort ${PAIRED_PROFILE.effort}`,
+		`paired prompt: ${opening}`,
+		'Paired comparison on: launch a third `reviewer` beside round 1 with the paired model and prompt; when both return, run `pnpm josh review:pair --issue <N> --opus-agent <id> --sonnet-agent <id>` before `review:record`. Its result never gates.',
+	].join('\n')
+}
+
+// Round 1's code brief, copied for the paired reviewer when the comparison is on; round 2 is never paired.
+// **A paired brief exists only while this round is paired** (joshuafolkken/kit#7020): an unpaired brief
+// removes the last one, since the ship's reviewer launch reads its presence as the pair being on.
+function offer(
+	text: string,
+	environment: NodeJS.ProcessEnv = process.env,
+	directory: string = PROJECT_ROOT,
+): string | undefined {
+	const { brief, findings } = paths(directory)
+
+	stamp_file.remove_stamp(findings)
+
+	if (!is_enabled(environment) || review_round.from_brief(text) === '2') {
+		stamp_file.remove_stamp(brief)
+
+		return undefined
+	}
+
+	stamp_file.write_text_stamp(brief, `${paired_brief(text, findings)}\n`)
+
+	return launch_note(brief)
+}
+
+function is_offered(directory: string = PROJECT_ROOT): boolean {
+	return stamp_file.read_stamp_text(paths(directory).brief) !== undefined
+}
+
+const review_pair = {
+	PAIRED_ENV,
+	PAIRED_PROFILE,
+	is_enabled,
+	is_offered,
+	offer,
+	opening: paired_opening,
+	paths,
+}
+
+export type { PairedPaths }
+export { review_pair }

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

@@ -1,4 +1,4 @@
-import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { agent_safe_text } from '#scripts/agent/agent-safe-text'
 import type { StopFinding } from '#scripts/run/ship/run-ship-review'
 import { review_stop_log, type StopLine } from './review-stop-log'
 
@@ -33,9 +33,7 @@ function entry_text(line: StopLine): string {
 	const disposition = line.fixed === true ? 'fixed in place' : 'stopped'
 	const text = `${key_of(line)} (${line.kind}, ${disposition} in the ${line.stage} stage)`
 
-	return agent_role_profile
-		.printable(text.replaceAll(LINE_BREAKS, ' '))
-		.slice(0, ENTRY_LENGTH_LIMIT)
+	return agent_safe_text.printable(text.replaceAll(LINE_BREAKS, ' ')).slice(0, ENTRY_LENGTH_LIMIT)
 }
 
 // The latest findings of the lane's issue that `is_kept` admits, oldest first.

package/scripts/review/review-prompt-level.ts

@@ -0,0 +1,28 @@
+import { file_reader } from '#scripts/lib/read-file'
+
+// **A reviewer's launch prompt opens with its review level** (joshuafolkken/kit#5555): the level sits on
+// the brief's first line, which the prompt only points at, so a transcript never carried it and
+// `josh lane:breakdown` printed `round 1` where it means `round 1 · medium`. The prompt stays one line —
+// a detached launch refuses a control character — so the level leads it before a separator, and the
+// transcript reader reads it back with the same pattern.
+
+const LEVEL_PATTERN = /^(low|medium|high|xhigh|max)(?:$| — )/u
+const SEPARATOR = ' — '
+
+// The level a line opens with — a brief's bare first line or a prompt's lead — `undefined` otherwise.
+function level_of(line: string): string | undefined {
+	return LEVEL_PATTERN.exec(line)?.[1]
+}
+
+// The lead a prompt pointing at `brief_path` opens with: its level and the separator, or nothing for a
+// brief not written or not opening with a level.
+function opening(brief_path: string): string {
+	const [first = ''] = (file_reader.read_if_readable(brief_path) ?? '').split('\n', 1)
+	const level = level_of(first.trim())
+
+	return level === undefined ? '' : `${level}${SEPARATOR}`
+}
+
+const review_prompt_level = { level_of, opening }
+
+export { review_prompt_level }