@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/report/report-lint-child-summary.ts

@@ -0,0 +1,94 @@
+import { markdown_shape } from './markdown-shape'
+import { report_format_reference } from './report-format-reference'
+import { report_labels, type ReportLabels } from './report-labels'
+
+// A lane child's closing summary carries only what GitHub does not, in a bounded length
+// (`backlogrun-child.md` → "What the summary carries, and how long it may be"). This checks the half a
+// machine can: the line bound, the cause / fix / result labels, and no changed-file list — a run of
+// bullets that are a path and nothing else. What else belongs in it stays the writer's judgement.
+
+// Two path-only bullets in a row already read as a list; one alone may be the one file a finding names.
+const MIN_FILE_LIST_RUN = 2
+const LIST_ITEM_PREFIX = /^\s*(?:\d+\.|[-*])\s+/u
+const PATH_CHARACTERS = /^[\w.@/-]+$/u
+const FILE_EXTENSION = /\.[a-z]+$/iu
+const BACKTICK = '`'
+// A label opens its line — after an optional list marker and bold marker — so a longer word ending
+// in the label, or `Fix the parser` inside a sentence, does not stand in for a missing label.
+const LABEL_LEAD = /^\s*(?:(?:\d+\.|[-*])\s+)?(?:\*\*)?/u
+const LETTER_PATTERN = /^\p{L}/u
+
+function opens_with_label(line: string, label: string): boolean {
+	const rest = line.replace(LABEL_LEAD, '')
+
+	return rest.startsWith(label) && !LETTER_PATTERN.test(rest.slice(label.length))
+}
+
+// A bullet whose whole text, backticks aside, is one path — a slash segment or a file name.
+function is_path_item(line: string): boolean {
+	if (!LIST_ITEM_PREFIX.test(line)) return false
+
+	const item = line.replace(LIST_ITEM_PREFIX, '').replaceAll(BACKTICK, '').trim()
+
+	return PATH_CHARACTERS.test(item) && (item.includes('/') || FILE_EXTENSION.test(item))
+}
+
+function path_item_runs(lines: ReadonlyArray<string>): ReadonlyArray<ReadonlyArray<string>> {
+	const runs: Array<Array<string>> = [[]]
+
+	for (const line of lines) {
+		if (is_path_item(line)) runs.at(-1)?.push(line)
+		else runs.push([])
+	}
+
+	return runs.filter((run) => run.length >= MIN_FILE_LIST_RUN)
+}
+
+function length_violation(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	const max = report_labels.CHILD_SUMMARY_MAX_LINES
+	if (lines.length <= max) return []
+
+	return [`✖ ${String(lines.length)} lines — the summary holds at most ${String(max)}`]
+}
+
+function label_violations(
+	lines: ReadonlyArray<string>,
+	labels: ReportLabels,
+): ReadonlyArray<string> {
+	return [labels.cause, labels.fix, labels.result]
+		.filter((label) => lines.every((line) => !opens_with_label(line, label)))
+		.map((label) => `✖ missing label: ${label}`)
+}
+
+function file_list_violations(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	return path_item_runs(lines).map(
+		(run) =>
+			`✖ changed-file list (${String(run.length)} path-only items) — GitHub carries it: ${run[0]?.trim() ?? ''}`,
+	)
+}
+
+// Every violation, in a fixed order; an empty array is a clean summary.
+function lint_child_summary(
+	summary: string,
+	labels: ReportLabels = report_labels.session_labels(),
+): ReadonlyArray<string> {
+	const lines = markdown_shape.content_lines(summary)
+
+	return [
+		...length_violation(lines),
+		...label_violations(lines, labels),
+		...file_list_violations(lines),
+	]
+}
+
+// The violations followed by one line naming where the summary's shape is written; a clean summary
+// stays empty, so `ok` is still the only output of a pass.
+function with_reference(violations: ReadonlyArray<string>): ReadonlyArray<string> {
+	if (violations.length === 0) return violations
+
+	return [...violations, `→ the shape: ${report_format_reference.child_summary_pointer()}`]
+}
+
+const report_lint_child_summary = { lint_child_summary, with_reference }
+
+export { report_lint_child_summary }

package/scripts/report/report-lint-cli.ts

@@ -3,24 +3,38 @@ import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { report_lint } from './report-lint'
+import { report_lint_child_summary } from './report-lint-child-summary'
 
 // `josh report:lint` — read a two-layer work summary candidate from stdin and print `ok`, or the
-// mechanical violations one per line, exiting non-zero so it works as a gate.
+// mechanical violations one per line, exiting non-zero so it works as a gate. `--child-summary`
+// checks a lane child's closing summary instead.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const OK_MESSAGE = 'ok'
+const CHILD_SUMMARY_FLAG = '--child-summary'
+const ARGV_OFFSET = 2
 const NO_INPUT_MESSAGE =
-	'✖ nothing on stdin — pipe the work summary in, e.g. `pnpm josh report:lint < summary.md`'
+	'✖ nothing on stdin — pipe the summary in, e.g. `pnpm josh report:lint < summary.md`'
 
-function run(summary: string): number {
+function lint(summary: string, is_child_summary: boolean): ReadonlyArray<string> {
+	if (is_child_summary) {
+		return report_lint_child_summary.with_reference(
+			report_lint_child_summary.lint_child_summary(summary),
+		)
+	}
+
+	return report_lint.with_reference(report_lint.lint_report(summary))
+}
+
+function run(summary: string, argv: ReadonlyArray<string>): number {
 	if (summary.trim().length === 0) {
 		console.error(NO_INPUT_MESSAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const violations = report_lint.lint_report(summary)
+	const violations = lint(summary, argv.includes(CHILD_SUMMARY_FLAG))
 
 	if (violations.length === 0) {
 		console.info(OK_MESSAGE)
@@ -28,15 +42,16 @@ function run(summary: string): number {
 		return SUCCESS_EXIT_CODE
 	}
 
-	console.error(report_lint.with_reference(violations).join('\n'))
+	console.error(violations.join('\n'))
 
 	return FAILURE_EXIT_CODE
 }
 
 async function read_and_run(): Promise<number> {
-	if (process.stdin.isTTY) return run('')
+	const argv = process.argv.slice(ARGV_OFFSET)
+	if (process.stdin.isTTY) return run('', argv)
 
-	return run(await text(process.stdin))
+	return run(await text(process.stdin), argv)
 }
 
 // `.env` is read here, on the command path alone, so the labels follow the session language.
@@ -45,4 +60,8 @@ async function main(): Promise<void> {
 	process.exitCode = await read_and_run()
 }
 
+const report_lint_cli = { run }
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { report_lint_cli }

package/scripts/report/report-lint.ts

@@ -1,3 +1,4 @@
+import { markdown_shape } from './markdown-shape'
 import { report_format_reference } from './report-format-reference'
 import { report_labels, type ReportLabels } from './report-labels'
 
@@ -40,19 +41,6 @@ const MIN_BREAK_CONDITIONS = 3
 const LIST_ITEM_PATTERN = /^\s*(?:\d+\.|[-*])\s+/u
 const REASON_SEPARATORS = /^[\s:：—|、,.。-]+/u
 
-function first_content_line(summary: string): string {
-	return (
-		summary
-			.split('\n')
-			.find((line) => line.trim().length > 0)
-			?.trim() ?? ''
-	)
-}
-
-function is_fenced(summary: string): boolean {
-	return first_content_line(summary).startsWith('```')
-}
-
 // A label counts only where no letter follows it, so `Change` is not found inside `Changes and tests`.
 function has_label(summary: string, label: string): boolean {
 	return summary
@@ -111,12 +99,6 @@ function has_path_or_flag(sentence: string): boolean {
 	)
 }
 
-function fence_violation(summary: string): ReadonlyArray<string> {
-	return is_fenced(summary)
-		? ['✖ the summary is wrapped in a code fence — write it as plain markdown']
-		: []
-}
-
 function label_violations(summary: string, labels: ReportLabels): ReadonlyArray<string> {
 	return missing_labels(summary, labels).map((label) => `✖ missing label: ${label}`)
 }
@@ -212,7 +194,7 @@ function lint_report(
 	labels: ReportLabels = report_labels.session_labels(),
 ): ReadonlyArray<string> {
 	return [
-		...fence_violation(summary),
+		...markdown_shape.fence_violation(summary, 'summary'),
 		...label_violations(summary, labels),
 		...length_violations(summary, labels),
 		...intrusion_violations(summary, labels),

package/scripts/review/prose-stale-cli.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { change_base } from '#scripts/git/change-base'
+import { git_grep_hits } from '#scripts/git/git-grep-hits'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
+import { test_pinned_logic, type Hunk } from '#scripts/test/test-pinned-logic'
+import { prose_stale_scan, type Reference, type Term } from './prose-stale-scan'
+
+// `josh prose:stale` — each word the change removed (a declared or exported name, a `josh x:y` command, an
+// `UPPER_CASE` constant, a `.md` heading) that a `.md` line or a comment line under prompts, docs,
+// .claude or scripts still names, as `file:line kind word`; `ok` when none (joshuafolkken/kit#5287).
+// The diff runs from the change base to the working tree, so an uncommitted edit counts. Exit 1 on a
+// reference, 2 when the base or a search could not be read.
+
+const USAGE = 'usage: josh prose:stale'
+const NO_BASE = 'prose:stale: no change base — fetch the default branch, then re-run'
+const SEARCH_PATHS = ['*.md', 'prompts', 'docs', '.claude', 'scripts', ':(exclude)CHANGELOG.md']
+// `process.argv` holds the runtime and the script before the command's own arguments.
+const FIRST_ARGUMENT = 2
+
+async function read_hunks(root: string, base: string): Promise<Array<Hunk>> {
+	const diff = await git_spawn.read([
+		'-C',
+		root,
+		'diff',
+		'-U0',
+		'--no-color',
+		'--no-ext-diff',
+		'--src-prefix=a/',
+		'--dst-prefix=b/',
+		base,
+	])
+
+	return test_pinned_logic.all_hunks(diff)
+}
+
+async function reference_of(term: Term, root: string): Promise<Reference> {
+	const { target, flags } = prose_stale_scan.pattern(term)
+	const { hits, has_failed } = await git_grep_hits.search(target, flags, SEARCH_PATHS, root)
+
+	return { term, hits, has_failed }
+}
+
+async function references(root: string, base: string): Promise<Array<Reference>> {
+	const registered = new Set(Object.keys(COMMAND_MAP))
+	const terms = prose_stale_scan.stale_terms(await read_hunks(root, base), registered)
+
+	return await Promise.all(terms.map(async (term) => await reference_of(term, root)))
+}
+
+function refuse(message: string): number {
+	console.error(message)
+
+	return prose_stale_scan.FAILED_EXIT
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) return refuse(USAGE)
+
+	const base = await change_base.resolved()
+
+	if (base === undefined) return refuse(NO_BASE)
+
+	const root = await git_spawn.read(['rev-parse', '--show-toplevel'])
+	const { text, exit_code } = prose_stale_scan.report(await references(root, base))
+
+	console.info(text)
+
+	return exit_code
+}
+
+// A git call that throws (no repository, a diff that failed) exits 2, never 1's "found".
+async function guarded(argv: ReadonlyArray<string>): Promise<number> {
+	try {
+		return await run(argv)
+	} catch (error) {
+		return refuse(`prose:stale: ${String(error)}`)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await guarded(process.argv.slice(FIRST_ARGUMENT))
+}
+
+const prose_stale_cli = { guarded, references, run }
+
+export { prose_stale_cli }

package/scripts/review/prose-stale-scan.ts

@@ -0,0 +1,152 @@
+import type { Hit } from '#scripts/git/git-grep-hits'
+import type { Hunk } from '#scripts/test/test-pinned-logic'
+import { review_readers_scan } from './review-readers-scan'
+
+// The words a diff removed that prose may still name (joshuafolkken/kit#5287) — the self-check's
+// "Prose matches the code" (`prompts/review.md`). Pure: `prose-stale-cli.ts` reads the diff and searches.
+//
+// **A removed line names four kinds of word**: a name (a top-level declaration, exported or not — a
+// namespace object's member is a plain `function` — or an `export { … }` entry) and an `UPPER_CASE`
+// constant on a code file's removed line (the declaration reading is `review-readers-scan.ts`'s), a `josh x:y` command
+// on any removed line, and a `.md` file's `#` heading. **A word the diff still writes is not removed**: an
+// identifier or command any added line carries, a heading an added `.md` line still titles, and a command
+// the registry still holds.
+
+type TermKind = 'name' | 'constant' | 'command' | 'heading'
+
+interface Term {
+	kind: TermKind
+	word: string
+}
+
+interface Reference {
+	term: Term
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+interface Report {
+	text: string
+	exit_code: number
+}
+
+const CODE_FILE = /\.(?:ts|js)$/u
+const MARKDOWN_EXTENSION = '.md'
+const COMMAND = /\bjosh\s+(?<command>[a-z][\w-]*:[\w:-]+)/gu
+const UPPER_CASE = /^[A-Z][A-Z\d_]*[A-Z\d]$/u
+const HEADING = /^#{1,6} (?<text>.+)$/u
+// A command token (`review:stops`) as well as an identifier, so one set answers both kinds.
+const TOKEN = /[\w-]+(?::[\w-]+)*/gu
+// A comment line of a code, shell or YAML file: `//`, `/*`, a block comment's `*`, or `#`.
+const COMMENT_LINE = /^\s*(?:\/[/*]|\*|#)/u
+const OK_LINE = 'ok'
+const FOUND_EXIT = 1
+const FAILED_EXIT = 2
+
+function to_terms(kind: TermKind, words: ReadonlyArray<string>): Array<Term> {
+	return words.map((word) => ({ kind, word }))
+}
+
+function code_terms(source: string): Array<Term> {
+	const declared = review_readers_scan.declarations(source).map((entry) => entry.name)
+	const listed = [...review_readers_scan.exported_names(source)]
+	const constants = declared.filter((name) => UPPER_CASE.test(name))
+	const names = [...declared.filter((name) => !UPPER_CASE.test(name)), ...listed]
+
+	return [...to_terms('name', names), ...to_terms('constant', constants)]
+}
+
+function command_terms(lines: ReadonlyArray<string>): Array<Term> {
+	const commands = lines.flatMap((line) =>
+		[...line.matchAll(COMMAND)].map((match) => match.groups?.['command'] ?? ''),
+	)
+
+	return to_terms('command', commands)
+}
+
+function headings(lines: ReadonlyArray<string>): Array<string> {
+	const texts = lines.map((line) => HEADING.exec(line)?.groups?.['text']?.trim())
+
+	return texts.filter((text): text is string => text !== undefined && text !== '')
+}
+
+function hunk_terms(hunk: Hunk): Array<Term> {
+	const lines = hunk.old_lines
+	const code = CODE_FILE.test(hunk.file) ? code_terms(lines.join('\n')) : []
+	const titled = hunk.file.endsWith(MARKDOWN_EXTENSION) ? to_terms('heading', headings(lines)) : []
+
+	return [...code, ...command_terms(lines), ...titled]
+}
+
+interface Kept {
+	tokens: ReadonlySet<string>
+	titles: ReadonlySet<string>
+	registered: ReadonlySet<string>
+}
+
+function kept_of(hunks: ReadonlyArray<Hunk>, registered: ReadonlySet<string>): Kept {
+	const added = hunks.flatMap((hunk) => hunk.new_lines ?? [])
+	const markdown = hunks.filter((hunk) => hunk.file.endsWith(MARKDOWN_EXTENSION))
+	const titles = headings(markdown.flatMap((hunk) => hunk.new_lines ?? []))
+	const tokens = added.flatMap((line) => [...line.matchAll(TOKEN)].map((match) => match[0]))
+
+	return { tokens: new Set(tokens), titles: new Set(titles), registered }
+}
+
+function is_removed(term: Term, kept: Kept): boolean {
+	if (term.kind === 'heading') return !kept.titles.has(term.word)
+	if (term.kind === 'command' && kept.registered.has(term.word)) return false
+
+	return !kept.tokens.has(term.word)
+}
+
+// Each removed word once, in diff order; `registered` is the command registry's names.
+function stale_terms(hunks: ReadonlyArray<Hunk>, registered: ReadonlySet<string>): Array<Term> {
+	const kept = kept_of(hunks, registered)
+	const unique = new Map(hunks.flatMap((hunk) => hunk_terms(hunk)).map((term) => [term.word, term]))
+
+	return [...unique.values()].filter((term) => is_removed(term, kept))
+}
+
+// A heading is searched quoted, the way a `→ "Heading"` pointer names it; any other word as a whole word.
+function pattern(term: Term): { target: string; flags: ReadonlyArray<string> } {
+	if (term.kind === 'heading') return { target: `"${term.word}"`, flags: [] }
+
+	return { target: term.word, flags: ['-w'] }
+}
+
+// Prose only: a `.md` line, or a comment line of any other searched file.
+function is_prose(hit: Hit): boolean {
+	return hit.path.endsWith(MARKDOWN_EXTENSION) || COMMENT_LINE.test(hit.excerpt)
+}
+
+function reference_lines(reference: Reference): Array<string> {
+	const { kind, word } = reference.term
+
+	if (reference.has_failed) return [`search failed: ${kind} ${word}`]
+
+	return reference.hits
+		.filter((hit) => is_prose(hit))
+		.map((hit) => `${hit.path}:${hit.line} ${kind} ${word}`)
+}
+
+function exit_code_of(references: ReadonlyArray<Reference>, lines: ReadonlyArray<string>): number {
+	if (references.some((reference) => reference.has_failed)) return FAILED_EXIT
+
+	return lines.length > 0 ? FOUND_EXIT : 0
+}
+
+// `ok` only when every search answered and none found prose; a failed search is never read as none.
+function report(references: ReadonlyArray<Reference>): Report {
+	const lines = references.flatMap((reference) => reference_lines(reference))
+
+	return {
+		text: lines.length > 0 ? lines.join('\n') : OK_LINE,
+		exit_code: exit_code_of(references, lines),
+	}
+}
+
+const prose_stale_scan = { FAILED_EXIT, pattern, report, stale_terms }
+
+export type { Reference, Term }
+export { prose_stale_scan }

package/scripts/review/review-attest.ts

@@ -32,8 +32,20 @@ import { review_checkout, type ReviewCheckout } from './review-checkout'
 // **Absence is a failure, never a pass.** A fork that ignored the instruction leaves no attestation,
 // and `check` answers `missing` rather than `ok`: the one shape this record must never take is the
 // one the defect already had.
-
-const POINTER_PREFIX = 'josh-review-target-'
+//
+// **One pointer per review slot**: `/code-review` and the interaction review run side by side in a
+// ship (joshuafolkken/kit#4672), so a brief minted for one never drops the other's nonce, and `check`
+// asks every slot against its own nonce. The code slot's pointer is the one the resume narrowing and
+// the issue watch read.
+
+const REVIEW_SLOT = { CODE: 'code', INTERACTION: 'interaction' } as const
+const REVIEW_SLOTS = [REVIEW_SLOT.CODE, REVIEW_SLOT.INTERACTION] as const
+type ReviewSlot = (typeof REVIEW_SLOTS)[number]
+
+const POINTER_PREFIXES: Readonly<Record<ReviewSlot, string>> = {
+	code: 'josh-review-target-',
+	interaction: 'josh-review-interaction-target-',
+}
 const EXPECT_PREFIX = 'josh-review-expect-'
 const ATTEST_PREFIX = 'josh-review-attest-'
 
@@ -64,8 +76,8 @@ interface PointerRecord {
 	taken_at: string
 }
 
-function pointer_path(root: string = PROJECT_ROOT): string {
-	return stamp_file.stamp_path(POINTER_PREFIX, root)
+function pointer_path(root: string = PROJECT_ROOT, slot: ReviewSlot = REVIEW_SLOT.CODE): string {
+	return stamp_file.stamp_path(POINTER_PREFIXES[slot], root)
 }
 
 function expect_path(nonce: string): string {
@@ -114,8 +126,8 @@ function to_pointer(value: unknown): PointerRecord | undefined {
 	return undefined
 }
 
-function read_pointer(root?: string): PointerRecord | undefined {
-	return to_pointer(read_json(pointer_path(root)))
+function read_pointer(root?: string, slot?: ReviewSlot): PointerRecord | undefined {
+	return to_pointer(read_json(pointer_path(root, slot)))
 }
 
 function read_expectation(nonce: string): ReviewCheckout | undefined {
@@ -135,6 +147,13 @@ function drop_records(pointer: PointerRecord | undefined): void {
 	stamp_file.remove_stamp(attest_path(pointer.nonce))
 }
 
+function drop_slot(root: string | undefined, slot: ReviewSlot): void {
+	const pointer = read_pointer(root, slot)
+
+	stamp_file.remove_stamp(pointer_path(root, slot))
+	drop_records(pointer)
+}
+
 // An unparseable timestamp reads as stale rather than as fresh, so a corrupted record drops the
 // requirement instead of wedging every merge in the checkout that holds it.
 function is_stale(taken_at: string, now: number): boolean {
@@ -153,13 +172,23 @@ function is_stale(taken_at: string, now: number): boolean {
 // attestation rather than accepting the one an earlier round already satisfied. Leaving the old pair
 // on disk would only be litter, but an orphaned expectation is also a nonce a fork could still attest
 // against, which is a contract nobody is checking.
-function record_target(checkout: ReviewCheckout, root?: string): string {
+//
+// **A code brief opens a new round, and closes the interaction contract with it.** Only
+// `review:brief --interaction` mints that slot, after the code brief of its round, so a contract
+// left unattested — its reviewer died, or the fix took the change out of the interaction review's
+// paths — would otherwise refuse every later round 2 and merge in the checkout.
+function record_target(
+	checkout: ReviewCheckout,
+	root?: string,
+	slot: ReviewSlot = REVIEW_SLOT.CODE,
+): string {
 	const nonce = randomBytes(NONCE_BYTES).toString('hex')
 	const taken_at = new Date().toISOString()
 
-	drop_records(read_pointer(root))
+	if (slot === REVIEW_SLOT.CODE) drop_slot(root, REVIEW_SLOT.INTERACTION)
+	drop_records(read_pointer(root, slot))
 	stamp_file.write_stamp(expect_path(nonce), { ...checkout, taken_at })
-	stamp_file.write_stamp(pointer_path(root), { nonce, taken_at })
+	stamp_file.write_stamp(pointer_path(root, slot), { nonce, taken_at })
 
 	return nonce
 }
@@ -220,8 +249,8 @@ function verdict_for(nonce: string): AttestVerdict {
 // tree, and evidence does not expire. Checked first, a mismatch older than eight hours would answer
 // `not-required` and the merge would go through on exactly the review this whole record exists to
 // catch — a run that parks, waits on CI or resumes the next morning reaches that state normally.
-function check(now: number = Date.now(), root?: string): AttestVerdict {
-	const pointer = read_pointer(root)
+function check_slot(now: number, root: string | undefined, slot: ReviewSlot): AttestVerdict {
+	const pointer = read_pointer(root, slot)
 
 	if (pointer === undefined) return not_required()
 
@@ -232,6 +261,21 @@ function check(now: number = Date.now(), root?: string): AttestVerdict {
 	return verdict
 }
 
+function is_passing(verdict: AttestVerdict): boolean {
+	return verdict.status === 'ok' || verdict.status === not_required().status
+}
+
+// Every slot answers on its own nonce: the first refusal stands, else an `ok`, else `not-required`.
+function check(now: number = Date.now(), root?: string): AttestVerdict {
+	const verdicts = REVIEW_SLOTS.map((slot) => check_slot(now, root, slot))
+
+	return (
+		verdicts.find((verdict) => !is_passing(verdict)) ??
+		verdicts.find((verdict) => verdict.status === 'ok') ??
+		not_required()
+	)
+}
+
 function is_written_since(source: string, taken_at: string): boolean {
 	try {
 		const stats = lstatSync(source)
@@ -242,6 +286,18 @@ function is_written_since(source: string, taken_at: string): boolean {
 	}
 }
 
+// Whether the brief the pointer names was attested, on this branch — the half of a finished review
+// that does not depend on where its verdict was written down.
+function is_attested_on(checkout: Pick<ReviewCheckout, 'branch'>, root?: string): boolean {
+	const pointer = read_pointer(root)
+
+	if (pointer === undefined) return false
+
+	const verdict = verdict_for(pointer.nonce)
+
+	return verdict.status === 'ok' && verdict.expected?.branch === checkout.branch
+}
+
 // **Whether the last briefed review of this branch finished**. A ship resumed
 // after a stop re-issues round 1, and without this answer it briefed the whole change again — the
 // files the finished review had just read, re-read at full cost. It is asked before `record_target`
@@ -255,11 +311,7 @@ function is_written_since(source: string, taken_at: string): boolean {
 function is_reviewed_on(checkout: ReviewCheckout, findings_path: string, root?: string): boolean {
 	const pointer = read_pointer(root)
 
-	if (pointer === undefined) return false
-
-	const verdict = verdict_for(pointer.nonce)
-
-	if (verdict.status !== 'ok' || verdict.expected?.branch !== checkout.branch) return false
+	if (pointer === undefined || !is_attested_on(checkout, root)) return false
 
 	return is_written_since(findings_path, pointer.taken_at)
 }
@@ -286,10 +338,7 @@ async function check_here(now: number = Date.now()): Promise<AttestVerdict> {
 // contract's lifetime is one run, and a record left behind would be the one the *next* run's check
 // reads. Cleared out of turn it would drop the guard, so it is called from nowhere else.
 function clear(root?: string): void {
-	const pointer = read_pointer(root)
-
-	stamp_file.remove_stamp(pointer_path(root))
-	drop_records(pointer)
+	for (const slot of REVIEW_SLOTS) drop_slot(root, slot)
 }
 
 // The counterpart to `check_here`, keyed the same way and for the same reason.
@@ -328,24 +377,25 @@ function refusal_message(verdict: AttestVerdict): string {
 
 const review_attest = {
 	attest,
-	attest_path,
 	check,
 	check_here,
 	clear,
 	clear_here,
 	expect_path,
+	is_attested_on,
 	is_briefed_since,
 	is_reviewed_on,
 	MISMATCH_VERDICT,
 	MISSING_REASON,
-	pointer_path,
 	read_attestation,
 	read_expectation,
 	read_pointer,
 	record_target,
 	refusal_message,
+	REVIEW_SLOT,
+	REVIEW_SLOTS,
 	STALE_AFTER_MS,
 }
 
-export type { AttestVerdict }
+export type { AttestVerdict, ReviewSlot }
 export { review_attest }