@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/repo/required-checks-logic.ts

@@ -0,0 +1,206 @@
+import { yaml_document } from '#scripts/lib/yaml-document'
+import { z } from 'zod'
+
+// The status checks kit's distributed workflows report, keyed by the workflow that reports them —
+// the single source `josh ruleset:check` and `josh doctor` compare a repository's required status
+// checks against (joshuafolkken/kit#3012). Each name is the job's `name:`, the string a ruleset's
+// required check is matched by; `required-checks-logic.test.ts` reads it back off the workflows.
+//
+// `E2E` belongs here even though `josh followup` deliberately does not wait on it
+// (joshuafolkken/kit#991): a ruleset counts a skipped job as passing, and the job is skipped when the
+// project has no E2E suite, so requiring it never blocks a merge — it only refuses a red one.
+interface WorkflowChecks {
+	workflow: string
+	checks: ReadonlyArray<string>
+}
+
+const CI_WORKFLOW = '.github/workflows/ci.yml'
+const SONAR_WORKFLOW = '.github/workflows/sonar-qube.yml'
+const CLASSIFICATION_WORKFLOW = '.github/workflows/pr-classification.yml'
+const REQUIRED_STATUS_CHECKS = 'required_status_checks'
+const NOT_FOUND_STATUS = 404
+
+const DISTRIBUTED_CHECKS: ReadonlyArray<WorkflowChecks> = [
+	{ workflow: CI_WORKFLOW, checks: ['Checks', 'Detect E2E', 'E2E', 'Security Audit'] },
+	{ workflow: SONAR_WORKFLOW, checks: ['SonarQube'] },
+	{ workflow: CLASSIFICATION_WORKFLOW, checks: ['Release classification'] },
+]
+
+// Where the repository's required checks live. A ruleset is the source `--apply` writes to; classic
+// branch protection is read beside it, and is the source for a repository that never moved to rulesets.
+type RequiredSource =
+	| { kind: 'ruleset'; ruleset_id: number; contexts: ReadonlyArray<string> }
+	| { kind: 'protection'; contexts: ReadonlyArray<string> }
+	| { kind: 'none' }
+	| { kind: 'unreadable' }
+
+const status_check_schema = z.looseObject({ context: z.string() })
+const branch_rule_schema = z.looseObject({
+	type: z.literal(REQUIRED_STATUS_CHECKS),
+	ruleset_id: z.number(),
+	parameters: z.looseObject({ required_status_checks: z.array(status_check_schema) }),
+})
+const protection_schema = z.looseObject({ contexts: z.array(z.string()) })
+const ruleset_rule_schema = z.looseObject({
+	type: z.string(),
+	parameters: z
+		.looseObject({ required_status_checks: z.array(status_check_schema).optional() })
+		.optional(),
+})
+const ruleset_schema = z.looseObject({ rules: z.array(ruleset_rule_schema) })
+const workflow_job_schema = z.looseObject({ name: z.string().optional() })
+const workflow_schema = z.looseObject({ jobs: z.record(z.string(), workflow_job_schema) })
+
+// One `gh api` read: the body it answered, or the HTTP status it failed with (`undefined` when
+// nothing answered at all).
+type ApiRead = { kind: 'body'; stdout: string } | { kind: 'failed'; status: number | undefined }
+
+type BranchRule = z.infer<typeof branch_rule_schema>
+type RulesetRule = z.infer<typeof ruleset_rule_schema>
+
+function parse_yaml_safe(content: string): unknown {
+	try {
+		return yaml_document.parse_yaml(content)
+	} catch {
+		return undefined
+	}
+}
+
+// The job `name:`s a workflow defines — the contexts it reports. A file that does not parse, or has
+// no `jobs` mapping, reports nothing.
+function workflow_job_names(content: string): Array<string> {
+	const parsed = workflow_schema.safeParse(parse_yaml_safe(content))
+	if (!parsed.success) return []
+
+	return Object.values(parsed.data.jobs).flatMap((job) =>
+		job.name === undefined ? [] : [job.name],
+	)
+}
+
+// The checks this repository should require: only those a workflow it has actually reports. A file
+// of the same name is not enough — a project's own `ci.yml` with a `build` job is never told to
+// require `Checks`, which nothing there would ever report.
+function expected_checks(read_workflow: (workflow: string) => string | undefined): Array<string> {
+	return DISTRIBUTED_CHECKS.flatMap((entry) => {
+		const content = read_workflow(entry.workflow)
+		if (content === undefined) return []
+		const reported = workflow_job_names(content)
+
+		return entry.checks.filter((check) => reported.includes(check))
+	})
+}
+
+function parse_json(stdout: string): unknown {
+	try {
+		return JSON.parse(stdout)
+	} catch {
+		return undefined
+	}
+}
+
+function status_check_rules(payload: unknown): Array<BranchRule> {
+	if (!Array.isArray(payload)) return []
+
+	return payload.flatMap((entry: unknown) => {
+		const parsed = branch_rule_schema.safeParse(entry)
+
+		return parsed.success ? [parsed.data] : []
+	})
+}
+
+// `GET repos/{owner}/{repo}/rules/branches/{branch}` — every rule in force on the branch, across
+// rulesets. The contexts of all of them are combined, since each is enforced; the first ruleset is the
+// one `--apply` writes to. No `required_status_checks` rule at all reads as `none`.
+function parse_branch_rules(stdout: string | undefined): RequiredSource {
+	const payload = stdout === undefined ? undefined : parse_json(stdout)
+	if (!Array.isArray(payload)) return { kind: 'unreadable' }
+	const rules = status_check_rules(payload)
+	const [first] = rules
+	if (first === undefined) return { kind: 'none' }
+	const contexts = rules.flatMap((rule) =>
+		rule.parameters.required_status_checks.map((check) => check.context),
+	)
+
+	return { kind: 'ruleset', ruleset_id: first.ruleset_id, contexts }
+}
+
+// `GET …/branches/{branch}/protection/required_status_checks`. GitHub answers a branch without
+// protection (or without required checks) with a 404, which alone reads as `none`. Any other
+// failure — a 403 for a caller without admin access, a 5xx, a timeout — or a body that is not the
+// expected document reads as `unreadable`, so a check that is in fact required is never reported
+// missing.
+function parse_protection(read: ApiRead): RequiredSource {
+	if (read.kind === 'failed') {
+		return { kind: read.status === NOT_FOUND_STATUS ? 'none' : 'unreadable' }
+	}
+
+	const parsed = protection_schema.safeParse(parse_json(read.stdout))
+
+	return parsed.success
+		? { kind: 'protection', contexts: parsed.data.contexts }
+		: { kind: 'unreadable' }
+}
+
+// GitHub enforces rulesets and classic protection together, so a check either one requires is
+// required. The ruleset stays the source `--apply` writes to; a protection read that failed for any
+// reason but a 404 leaves the whole answer `unreadable`, as a lone protection read would.
+function combine_sources(rules: RequiredSource, protection: RequiredSource): RequiredSource {
+	if (rules.kind !== 'ruleset') return protection
+	if (protection.kind === 'none') return rules
+	if (protection.kind !== 'protection') return { kind: 'unreadable' }
+
+	return { ...rules, contexts: [...new Set([...rules.contexts, ...protection.contexts])] }
+}
+
+function missing_checks(
+	expected: ReadonlyArray<string>,
+	contexts: ReadonlyArray<string>,
+): Array<string> {
+	return expected.filter((check) => !contexts.includes(check))
+}
+
+function with_added_checks(rule: RulesetRule, missing: ReadonlyArray<string>): RulesetRule {
+	if (rule.type !== REQUIRED_STATUS_CHECKS || rule.parameters === undefined) return rule
+	const current = rule.parameters.required_status_checks ?? []
+	const added = missing.map((context) => ({ context }))
+
+	return {
+		...rule,
+		parameters: { ...rule.parameters, required_status_checks: [...current, ...added] },
+	}
+}
+
+// The `PUT repos/{owner}/{repo}/rulesets/{id}` body: the ruleset's own rules, unchanged but for the
+// missing contexts appended to its required-checks rule. `rules` replaces the whole list, so every
+// other rule is carried over as read rather than dropped.
+function ruleset_update_body(
+	ruleset_stdout: string,
+	missing: ReadonlyArray<string>,
+): string | undefined {
+	const parsed = ruleset_schema.safeParse(parse_json(ruleset_stdout))
+	if (!parsed.success) return undefined
+
+	return JSON.stringify({
+		rules: parsed.data.rules.map((rule) => with_added_checks(rule, missing)),
+	})
+}
+
+// The `POST …/protection/required_status_checks/contexts` body, which appends rather than replaces.
+function protection_update_body(missing: ReadonlyArray<string>): string {
+	return JSON.stringify({ contexts: missing })
+}
+
+const required_checks_logic = {
+	DISTRIBUTED_CHECKS,
+	workflow_job_names,
+	expected_checks,
+	parse_branch_rules,
+	parse_protection,
+	combine_sources,
+	missing_checks,
+	ruleset_update_body,
+	protection_update_body,
+}
+
+export type { ApiRead, RequiredSource, WorkflowChecks }
+export { required_checks_logic }

package/scripts/repo/required-checks-report.ts

@@ -0,0 +1,71 @@
+import { repo_setting } from './repo-setting'
+import type { RequiredSource } from './required-checks-logic'
+
+// What one read of a repository's required status checks found, against what kit's distributed
+// workflows report (joshuafolkken/kit#3012).
+interface RequiredChecksReport {
+	repo: string | undefined
+	branch: string | undefined
+	source: RequiredSource
+	expected: ReadonlyArray<string>
+	missing: ReadonlyArray<string>
+}
+
+const LABEL = 'Required status checks'
+const APPLY_COMMAND = 'pnpm josh ruleset:check --apply'
+
+function source_label(source: RequiredSource): string {
+	return source.kind === 'ruleset' ? `ruleset ${String(source.ruleset_id)}` : 'branch protection'
+}
+
+// An unreadable answer is never reported as a missing one — the same rule every repository-setting
+// report follows — so it names the possible causes and no remediation.
+function format_unreadable(report: RequiredChecksReport): Array<string> {
+	return [
+		`  ⚠ ${LABEL}: could not be read (${repo_setting.report_target(report.repo)}) — not checked, not necessarily missing`,
+		'    `gh` is missing or unauthenticated, or the request failed (offline, timed out).',
+	]
+}
+
+// No ruleset or protection requires anything. `--apply` adds to an existing rule and never creates
+// one — which branches a ruleset targets and who may bypass it are the maintainer's choices.
+function format_none(report: RequiredChecksReport, target: string): Array<string> {
+	return [
+		`  ⚠ ${LABEL}: none required on ${String(report.branch)} (${target})`,
+		`    Expected: ${report.expected.join(', ')}`,
+		'    Create a branch ruleset (Settings → Rules → Rulesets) that requires them.',
+	]
+}
+
+function format_found(report: RequiredChecksReport, target: string): Array<string> {
+	const where = `${String(report.branch)} (${target}, ${source_label(report.source)})`
+
+	if (report.missing.length === 0) {
+		return [`  ✔ ${LABEL}: all ${String(report.expected.length)} kit checks required on ${where}`]
+	}
+
+	return [
+		`  ⚠ ${LABEL}: ${report.missing.join(', ')} not required on ${where}`,
+		`    Add: ${APPLY_COMMAND}`,
+	]
+}
+
+function format_report(report: RequiredChecksReport): Array<string> {
+	const target = repo_setting.report_target(report.repo)
+	if (report.source.kind === 'unreadable') return format_unreadable(report)
+	if (report.source.kind === 'none') return format_none(report, target)
+
+	return format_found(report, target)
+}
+
+// Whether nothing is left to do: the checks were read and every expected one is required.
+function is_complete(report: RequiredChecksReport): boolean {
+	const is_read = report.source.kind === 'ruleset' || report.source.kind === 'protection'
+
+	return is_read && report.missing.length === 0
+}
+
+const required_checks_report = { format_report, is_complete }
+
+export type { RequiredChecksReport }
+export { required_checks_report }

package/scripts/repo/ruleset-check-cli.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { repo_setting } from './repo-setting'
+import { required_checks_report, type RequiredChecksReport } from './required-checks-report'
+import { ruleset_check } from './ruleset-check'
+
+// `josh ruleset:check [--apply]` — say whether the default branch requires every status check kit's
+// distributed workflows report, and with `--apply` add the missing ones (joshuafolkken/kit#3012).
+// Changing a repository setting is outward-facing, so the write happens only on the flag a person
+// typed; `josh sync` and `josh doctor` never pass it. Exits non-zero while anything is left to do.
+
+const ARGV_OFFSET = 2
+const APPLY_FLAG = '--apply'
+const FAILURE_EXIT_CODE = 1
+
+function exit_code_for(report: RequiredChecksReport): number {
+	return required_checks_report.is_complete(report) ? 0 : FAILURE_EXIT_CODE
+}
+
+function apply(report: RequiredChecksReport): number {
+	try {
+		if (!ruleset_check.apply_missing(report)) return FAILURE_EXIT_CODE
+	} catch (error) {
+		console.error(`Could not add ${report.missing.join(', ')}: ${String(error)}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(`  ✔ Added: ${report.missing.join(', ')}`)
+
+	return 0
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	const report = ruleset_check.inspect(gh_spawn.get_repo_name_with_owner(), PROJECT_ROOT)
+
+	repo_setting.print_section(required_checks_report.format_report(report))
+	const is_writable = argv.includes(APPLY_FLAG) && report.missing.length > 0
+
+	return is_writable ? apply(report) : exit_code_for(report)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const ruleset_check_cli = { APPLY_FLAG, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { ruleset_check_cli }

package/scripts/repo/ruleset-check.ts

@@ -0,0 +1,147 @@
+import path from 'node:path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { gh_failure } from '#scripts/gh/git-gh-failure'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { file_reader } from '#scripts/lib/read-file'
+import { repo_setting } from './repo-setting'
+import { required_checks_logic, type ApiRead, type RequiredSource } from './required-checks-logic'
+import { required_checks_report, type RequiredChecksReport } from './required-checks-report'
+
+// Read a repository's required status checks on its default branch and compare them with the checks
+// kit's distributed workflows report (joshuafolkken/kit#3012). Every read degrades to `unreadable`
+// rather than throwing; the one write, `apply_missing`, runs only on `josh ruleset:check --apply`.
+
+function read_api(api_path: string): string | undefined {
+	return git_gh_exec.read_gh_api_sync({
+		path: api_path,
+		cwd: PROJECT_ROOT,
+		timeout_ms: repo_setting.GH_TIMEOUT_MS,
+	})
+}
+
+function read_default_branch(repo: string): string | undefined {
+	const branch = git_gh_exec
+		.read_gh_api_sync({
+			path: `repos/${repo}`,
+			jq_filter: '.default_branch',
+			cwd: PROJECT_ROOT,
+			timeout_ms: repo_setting.GH_TIMEOUT_MS,
+		})
+		?.trim()
+
+	return branch === '' ? undefined : branch
+}
+
+// Unlike `read_api`, keeps the failure's HTTP status: a 404 here means "no protection", which is an
+// answer, while any other failure is not.
+function read_protection(repo: string, branch: string): ApiRead {
+	try {
+		const stdout = git_gh_exec.exec_gh_api_sync({
+			path: `repos/${repo}/branches/${branch}/protection/required_status_checks`,
+			cwd: PROJECT_ROOT,
+			timeout_ms: repo_setting.GH_TIMEOUT_MS,
+		})
+
+		return { kind: 'body', stdout }
+	} catch (error) {
+		return { kind: 'failed', status: gh_failure.failure_of(error)?.status }
+	}
+}
+
+// Rulesets and classic branch protection both, since GitHub enforces both; unreadable rules stop
+// there rather than letting protection alone pass for the whole answer.
+function read_source(repo: string, branch: string): RequiredSource {
+	const from_rules = required_checks_logic.parse_branch_rules(
+		read_api(`repos/${repo}/rules/branches/${branch}`),
+	)
+	if (from_rules.kind === 'unreadable') return from_rules
+	const from_protection = required_checks_logic.parse_protection(read_protection(repo, branch))
+
+	return required_checks_logic.combine_sources(from_rules, from_protection)
+}
+
+// The checks `root` should require, decided by the jobs its distributed workflows define on disk.
+function expected_in(root: string): Array<string> {
+	return required_checks_logic.expected_checks((workflow) =>
+		file_reader.read_if_readable(path.join(root, workflow)),
+	)
+}
+
+function contexts_of(source: RequiredSource): ReadonlyArray<string> {
+	return source.kind === 'ruleset' || source.kind === 'protection' ? source.contexts : []
+}
+
+function inspect(repo: string | undefined, root: string): RequiredChecksReport {
+	const expected = expected_in(root)
+	const branch = repo === undefined ? undefined : read_default_branch(repo)
+	const source: RequiredSource =
+		repo === undefined || branch === undefined ? { kind: 'unreadable' } : read_source(repo, branch)
+	const missing =
+		source.kind === 'unreadable'
+			? []
+			: required_checks_logic.missing_checks(expected, contexts_of(source))
+
+	return { repo, branch, source, expected, missing }
+}
+
+function apply_to_ruleset(repo: string, ruleset_id: number, missing: ReadonlyArray<string>): void {
+	const api_path = `repos/${repo}/rulesets/${String(ruleset_id)}`
+	const current = git_gh_exec.exec_gh_api_sync({ path: api_path, cwd: PROJECT_ROOT })
+	const body = required_checks_logic.ruleset_update_body(current, missing)
+	if (body === undefined) throw new Error(`Unexpected ruleset response from ${api_path}`)
+
+	git_gh_exec.exec_gh_api_sync({ path: api_path, method: 'PUT', body, cwd: PROJECT_ROOT })
+}
+
+function apply_to_protection(repo: string, branch: string, missing: ReadonlyArray<string>): void {
+	git_gh_exec.exec_gh_api_sync({
+		path: `repos/${repo}/branches/${branch}/protection/required_status_checks/contexts`,
+		method: 'POST',
+		body: required_checks_logic.protection_update_body(missing),
+		cwd: PROJECT_ROOT,
+	})
+}
+
+function apply_to_source(
+	repo: string,
+	branch: string,
+	source: RequiredSource,
+	missing: ReadonlyArray<string>,
+): boolean {
+	if (source.kind === 'ruleset') {
+		apply_to_ruleset(repo, source.ruleset_id, missing)
+
+		return true
+	}
+
+	if (source.kind !== 'protection') return false
+	apply_to_protection(repo, branch, missing)
+
+	return true
+}
+
+// The one write: append the missing checks to the rule that already requires checks. A repository
+// with neither a ruleset rule nor protection gets nothing created for it, which `format_report`
+// explains. Throws on a failed request so the caller can report it; `false` when nothing was written.
+function apply_missing(report: RequiredChecksReport): boolean {
+	const { repo, branch, source, missing } = report
+	if (repo === undefined || branch === undefined || missing.length === 0) return false
+
+	return apply_to_source(repo, branch, source, missing)
+}
+
+// The `josh doctor` section: read, never write.
+function report_required_checks_section(
+	repo: string | undefined,
+	root: string,
+): RequiredChecksReport {
+	const report = inspect(repo, root)
+
+	repo_setting.print_section(required_checks_report.format_report(report))
+
+	return report
+}
+
+const ruleset_check = { expected_in, inspect, apply_missing, report_required_checks_section }
+
+export { ruleset_check }

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

@@ -42,8 +42,4 @@ async function main(): Promise<void> {
 	process.exitCode = await read_and_run()
 }
 
-const report_lint_cli = { run, OK_MESSAGE }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { report_lint_cli }

package/scripts/review/disposition-cli.ts

@@ -37,7 +37,7 @@ function main(argv: ReadonlyArray<string>): void {
 	process.exitCode = run(argv)
 }
 
-const disposition_cli = { USAGE, main, reason_line, run }
+const disposition_cli = { USAGE, reason_line, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/review/live-evidence.ts

@@ -1,5 +1,5 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
-import { git_gh_command } from '#scripts/git/git-gh-command'
 import { reproduction_measure } from '#scripts/issue/reproduction-measure'
 import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-logic'
 

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

@@ -101,13 +101,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const review_attest_cli = {
-	CHECK_FLAG,
-	main,
-	NOT_REQUIRED_LINE,
 	run,
-	run_check,
-	UNKNOWN_NONCE_LINE,
-	USAGE,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/review/review-attest.ts

@@ -1,7 +1,9 @@
 import { randomBytes } from 'node:crypto'
+import { lstatSync } from 'node:fs'
 import { git_command } from '#scripts/git/git-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 
 // The record that says which checkout a `/code-review` actually read (joshuafolkken/kit#1522).
@@ -80,17 +82,7 @@ function attest_path(nonce: string): string {
 function read_json(source: string): unknown {
 	const raw = stamp_file.read_stamp_text(source)
 
-	if (raw === undefined) return undefined
-
-	try {
-		return JSON.parse(raw)
-	} catch {
-		return undefined
-	}
-}
-
-function is_record(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null
+	return raw === undefined ? undefined : json_value.parse_or_undefined(raw)
 }
 
 function string_field(value: Record<string, unknown>, key: string): string | undefined {
@@ -100,7 +92,7 @@ function string_field(value: Record<string, unknown>, key: string): string | und
 }
 
 function to_checkout(value: unknown): ReviewCheckout | undefined {
-	if (!is_record(value)) return undefined
+	if (!json_value.is_record(value)) return undefined
 
 	const root = string_field(value, 'root')
 	const branch = string_field(value, 'branch')
@@ -112,7 +104,7 @@ function to_checkout(value: unknown): ReviewCheckout | undefined {
 }
 
 function to_pointer(value: unknown): PointerRecord | undefined {
-	if (!is_record(value)) return undefined
+	if (!json_value.is_record(value)) return undefined
 
 	const nonce = string_field(value, 'nonce')
 	const taken_at = string_field(value, 'taken_at')
@@ -240,6 +232,47 @@ function check(now: number = Date.now(), root?: string): AttestVerdict {
 	return verdict
 }
 
+function is_written_since(source: string, taken_at: string): boolean {
+	try {
+		const stats = lstatSync(source)
+
+		return stats.isFile() && stats.mtimeMs >= Date.parse(taken_at)
+	} catch {
+		return false
+	}
+}
+
+// **Whether the last briefed review of this branch finished** (joshuafolkken/kit#2945). 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`
+// mints the next nonce, since that call drops the record it reads. The branch must match: the pointer
+// is keyed on the root, and a lane root outlives the branch a previous run reviewed there.
+//
+// **An attestation alone is not a finished review.** The reviewer may attest and then die before it
+// reports — a timeout, a usage limit — and narrowing on that would call files nobody read "already
+// read". So the findings file, written only once the review has its verdict, must postdate the brief
+// this pointer names; one left from an earlier review is older than that brief and does not count.
+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
+
+	return is_written_since(findings_path, pointer.taken_at)
+}
+
+// Whether a record written at `written_at` belongs to the brief the pointer names rather than an earlier
+// one (joshuafolkken/kit#2945): that brief writes it right after minting the pointer. ISO timestamps
+// order as strings.
+function is_briefed_since(written_at: string, root?: string): boolean {
+	const pointer = read_pointer(root)
+
+	return pointer !== undefined && written_at >= pointer.taken_at
+}
+
 // The pointer is keyed on the repository root rather than on `process.cwd()`, which is what
 // `PROJECT_ROOT` is. `josh review:brief` records against the root it just asked git for, so the check
 // has to ask the same question: run the two from different directories — one from `scripts/`, one
@@ -294,18 +327,17 @@ function refusal_message(verdict: AttestVerdict): string {
 }
 
 const review_attest = {
-	ATTEST_PREFIX,
 	attest,
 	attest_path,
 	check,
 	check_here,
 	clear,
 	clear_here,
-	EXPECT_PREFIX,
 	expect_path,
+	is_briefed_since,
+	is_reviewed_on,
 	MISMATCH_VERDICT,
 	MISSING_REASON,
-	POINTER_PREFIX,
 	pointer_path,
 	read_attestation,
 	read_expectation,