From 6b6713d654b552f9e282eeccba71b821baca2cd4 Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 11:11:16 -0800
Subject: [PATCH 1/6] feat(review): quest review records each round in the PR
 body

After each round, `quest review` rewrites the `## Review` section of the
branch's open PR: reviewer, session and round, reviewed head and base,
score, and each finding with its location. The reply now settles each of
the last round's findings by number as fixed, refuted, or open, so the
record carries dispositions without an agent copying them by hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                |  28 ++++-
 assets/CONTEXT.md        |   5 +-
 assets/skills/review.md  |   4 +-
 src/cli/main.ts          |  40 +++++--
 src/cli/review-record.ts |  87 ++++++++++++++
 src/cli/review.ts        | 142 ++++++++++++++++++----
 test/review.test.ts      | 247 +++++++++++++++++++++++++++++++++++++--
 test/runner.test.ts      |   2 +
 8 files changed, 506 insertions(+), 49 deletions(-)
 create mode 100644 src/cli/review-record.ts

diff --git a/README.md b/README.md
index d8261048..23a9cd40 100644
--- a/README.md
+++ b/README.md
@@ -1134,7 +1134,9 @@ malformed reply. The score informs; the findings and their refutations still
 decide when the loop ends. Later rounds resume the same session with the new head and
 `--responses`, the author's free-text fixes and refutations, which a round that
 reported findings requires. A refutation stands only when it cites evidence the
-reviewer can check. A resumed session keeps the instructions it started with,
+reviewer can check. The prompt numbers the last round's findings, and the reply
+settles each by its number as fixed, refuted, or still open, with a one-sentence
+reason; a reply that skips or repeats one fails like any malformed reply. A resumed session keeps the instructions it started with,
 so a round whose applicable `AGENTS.md` or `CLAUDE.md` files changed starts a
 new session instead, which still weighs the responses. Resuming keeps the
 reviewer's prompt cache; Claude Code is asked for its 1-hour cache, and Codex
@@ -1167,14 +1169,32 @@ given every round, and chooses the review's stance, such as adversarial.
 It prints the reviewer, model, and effort, the size and its source, session, round, base, head, a
 `usage` line per turn (input tokens, the part read from the prompt cache, and output), the
 finding count, then each finding as severity, `path:line`, and title over its
-indented body. `--json` prints the same as one object. It exits 0 once the round
+indented body, then `earlier` with the last round's head and its findings, each
+as its disposition, severity, `path:line`, and title over its reason, and last
+a `record` line. `--json` prints the same as one object.
+
+After each round, `quest review` rewrites the `## Review` section of the open PR
+from the branch into the base, found among the upstream's PRs from the
+repository the base's remote pushes to, and prints `record <url>`. The record
+names the reviewer harness, model, and effort, the session and round, the
+reviewed head's full SHA and the base's short one, the score and rationale, each
+finding with its location, and the last round's findings with their
+dispositions. Model text appears as inline code, so it mentions or links
+nothing, and only the reviewed head's SHA appears in full, since the land gate
+counts every full SHA the section names. The section runs to the next level-1 or
+level-2 heading; the rest of the body stays as written, and a body without one
+gains it at the end. With no such PR, or a remote off GitHub, it changes nothing
+and prints `record skipped: <why>`. It edits as the user the GitHub token names
+(`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`), and the land gate counts the
+record only while the PR's author made the body's latest edit, so review your
+own PRs with your own token. A record GitHub refuses fails the command after the
+round's report, with exit status 1. It exits 0 once the round
 finishes, whatever it found, 2 for invalid arguments or a checkout or CLI that
 cannot be reviewed, including a login the API rejects, 3 when the reviewer's
 account hit its usage limit, and 1 for other failures. A usage limit prints one
 line, `error: <harness> hit its usage limit; resets <time>`, where `<time>` is
 the reset as an ISO 8601 UTC timestamp, or `unknown` when the CLI named none.
-`/quest-review` runs the rounds,
-records them in the PR body's `## Review` section, and marks the PR ready.
+`/quest-review` runs the rounds and marks the PR ready.
 
 ## Headless agents
 
diff --git a/assets/CONTEXT.md b/assets/CONTEXT.md
index 903408b1..4b3d8b2a 100644
--- a/assets/CONTEXT.md
+++ b/assets/CONTEXT.md
@@ -136,9 +136,10 @@ A quest PR's size is its quest's; a skill that opens its own PR, such as `/quest
 List them as `Size: M` and one `Implementer: Codex, gpt-6.1-sol, high effort` line per session, which each session adds when it first pushes.
 Read your model and effort rather than guess: Claude Code knows its model and exports `CLAUDE_EFFORT`; Codex records `model` and `effort` in the last `turn_context` of `~/.codex/sessions/*/*/*/rollout-*-$CODEX_THREAD_ID.jsonl`; Grok records `model_id` and `reasoning_effort` in `~/.grok/sessions/*/$GROK_SESSION_ID/chat_history.jsonl`.
 Write `unknown` for any you cannot find.
-The PR body's `## Review` section records the latest round: the reviewer harness, model, and effort, the reviewed head SHA, the round's score out of 10 with its rationale, and each finding's disposition (fixed, or refuted with the reason), or the skip and its reason.
+The PR body's `## Review` section records the latest round, or the skip and its reason.
+`quest review` rewrites it after each round on a branch with an open PR: the reviewer harness, model, and effort, the session and round, the reviewed head SHA and base, the score out of 10 with its rationale, and each finding with its location and disposition, which the next round settles from your responses as fixed, refuted with the reason, or still open.
+Open the draft PR before the first round, and write a round's record by hand only when the round printed `record skipped`, as on another author's fork; add context only after the record, since the next round rewrites the section.
 Never block on a score: the findings and their refutations decide when the review is done.
-Rewrite it after each round.
 A review counts for the head whose SHA it names.
 
 Once "Ready to Review", CI and any online reviewers run.
diff --git a/assets/skills/review.md b/assets/skills/review.md
index 332380e6..9e2d7242 100644
--- a/assets/skills/review.md
+++ b/assets/skills/review.md
@@ -20,12 +20,12 @@ Otherwise, review the committed branch with `quest review`, as `quest context`'s
 Run it in the foreground; a round takes minutes.
 If a round fails because the reviewer is out of quota or logged out, stop reviewing: keep the PR a draft with the `## Waiting` item `quest context`'s Reviews section describes, hand it back, and report the outage.
 Fix each finding you agree with, or refute it with evidence the reviewer can check.
-Commit the fixes, rerun the checks, and run the next round with `--responses`, one response per finding, written in the checkout's `.tmp/`.
+Commit the fixes, rerun the checks, and run the next round with `--responses`, one response per finding by its number, written in the checkout's `.tmp/`.
 Repeat until a round of the head reports no finding you have not refuted with evidence.
 A finding the reviewer keeps against such a refutation is a decision for the user; a background agent lists it under `## Waiting`.
 If you judge the change too trivial to review, skip the review instead and record why.
 
-Rewrite the PR body's `## Review` section after each round, or once for a skip.
+Each round records itself in the PR body's `## Review` section; record a skip there yourself.
 Push, then flip the PR to "Ready for Review" with `quest ready <pr> <token>`, which also drops its `## Waiting` section.
 For your own draft, mark it ready for review yourself.
 Do not wait for online reviewers.
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 46c5b3e6..d094ee97 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -62,6 +62,7 @@ import {
 	review,
 	roundLines,
 } from "./review";
+import { type Recorded, recordRound } from "./review-record";
 import { heal, init, uninstall } from "./setup";
 import { Refusal, describe, notUpstream, releaseQuest, startQuest } from "./start";
 import { CONTEXT, GUIDE, SKILLS, skill } from "./skills";
@@ -1000,7 +1001,8 @@ export function main(argv: string[], out: Output): number | Promise<number> {
 				"`/code-review <effort> <merge-base>...HEAD`), then resumes that session for one turn that applies the base's " +
 				"REVIEW.md, if any, and reports the findings in one JSON schema. Later rounds on the branch resume the " +
 				"same session with the new head and --responses, the author's fixes and refutations of the last " +
-				"round's findings, required while that round reported any. A resumed session keeps the instructions it " +
+				"round's findings, required while that round reported any; the reply settles each of those findings, by " +
+				"its number in the prompt, as fixed, refuted, or still open. A resumed session keeps the instructions it " +
 				"started with, so when the applicable AGENTS.md or CLAUDE.md files change, the round starts a new " +
 				"session that still weighs --responses. --new starts a new session. The session is kept per branch in the clone's common Git directory, so any worktree of the clone resumes it. " +
 				"--branch names the branch instead of the checked-out one, as a detached HEAD requires, such as a " +
@@ -1011,11 +1013,17 @@ export function main(argv: string[], out: Output): number | Promise<number> {
 				"reviewer. The base is fetched first, since the sandbox has no network.\n\n" +
 				"Prints the reviewer, model, and effort, the size and where it came from, session, round, base, head, a usage line per turn (input tokens, the " +
 				"part read from the prompt cache, and output), a score from 0 to 10 for how ready the head is to land with " +
-				"its one-sentence rationale, the finding count, then each finding. A reply without a valid score " +
+				"its one-sentence rationale, the finding count, each finding, then the last round's findings with " +
+				"their dispositions. A reply without a valid score " +
 				"fails as any malformed reply does. --json prints " +
-				"the same as one object. Exits 0 once the round finishes, whatever it found, 2 for invalid arguments " +
+				"the same as one object.\n\n" +
+				"After each round, it rewrites the `## Review` section of the branch's open PR into the base, as the " +
+				"user the GitHub token names, keeping the rest of the body, and prints `record <url>`: the reviewer, " +
+				"session and round, the reviewed head, base, score, and each finding with its disposition. With no " +
+				"such PR, or a remote off GitHub, it prints `record skipped: <why>` and changes nothing.\n\n" +
+				"Exits 0 once the round finishes, whatever it found, 2 for invalid arguments " +
 				"or a checkout or CLI that cannot be reviewed, including a login the API rejects, 3 when the reviewer's " +
-				"account hit its usage limit, and 1 for other failures. A usage limit prints one line, " +
+				"account hit its usage limit, and 1 for other failures, including a record GitHub refuses. A usage limit prints one line, " +
 				"`error: <harness> hit its usage limit; resets <time>`, where <time> is the reset as an ISO 8601 UTC " +
 				"timestamp, or `unknown` when the CLI named none.",
 		)
@@ -1055,10 +1063,26 @@ export function main(argv: string[], out: Output): number | Promise<number> {
 					reviewDependencies(),
 				);
 				pending = run.then(
-					(round) => {
-						if (options.json) print(JSON.stringify(round));
-						else for (const line of roundLines(round)) print(line);
-						return 0;
+					async (round) => {
+						// The round is saved in its session either way, so its report prints before a failed record.
+						let record: Recorded | undefined;
+						let failure: unknown;
+						try {
+							record = await recordRound(root(), round, { github: () => gitHubDependencies(warn), warn });
+						} catch (error) {
+							failure = error;
+						}
+						if (options.json) print(JSON.stringify({ ...round, record: record ?? null }));
+						else {
+							for (const line of roundLines(round)) print(line);
+							if (record !== undefined)
+								print("url" in record ? `record ${record.url}` : `record skipped: ${record.skipped}`);
+						}
+						if (failure === undefined) return 0;
+						warn(
+							`the round finished, but recording it in the PR body failed: ${failure instanceof Error ? failure.message : String(failure)}`,
+						);
+						return 1;
 					},
 					(error: unknown) => {
 						if (error instanceof ReviewInputError) {
diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts
new file mode 100644
index 00000000..61d498b0
--- /dev/null
+++ b/src/cli/review-record.ts
@@ -0,0 +1,87 @@
+// `quest review` rewrites the `## Review` section of its branch's open PR after each round, so the head
+// it reviewed counts without an agent copying the round into the body by hand.
+import { type ClaimDependencies, repositoryPath, upstream } from "./claims";
+import { requireRemote, string } from "./github";
+import { type Round, located, parseBase } from "./review";
+
+const HARNESSES: Record<Round["reviewer"], string> = { claude: "Claude Code", codex: "Codex" };
+
+/**
+ * Model text as one inline code span, so a mention, issue reference, or Markdown in it renders as text.
+ * The land gate counts every full SHA the section names, so only the reviewed head appears in full.
+ */
+function code(text: string): string {
+	const flat = text
+		.replace(/\s+/g, " ")
+		.trim()
+		.replace(/\b[0-9a-f]{40}\b/g, (sha) => sha.slice(0, 12));
+	const fence = "`".repeat(Math.max(0, ...(flat.match(/`+/g) ?? []).map((run) => run.length)) + 1);
+	const pad = /^`|`$/.test(flat) ? " " : "";
+	return `${fence}${pad}${flat}${pad}${fence}`;
+}
+
+const capitalized = (word: string) => word[0]!.toUpperCase() + word.slice(1);
+
+/** The `## Review` section's text for `round`, without its heading. */
+export function reviewRecord(round: Round): string {
+	const lines = [
+		"Rewritten by `quest review` after each round.",
+		"",
+		`- Reviewer: ${HARNESSES[round.reviewer]}, ${round.model}, ${round.effort} effort`,
+		`- Session: ${code(round.session)}, round ${round.round}`,
+		`- Head: ${round.head}`,
+		`- Base: ${round.base.ref} at ${round.base.sha.slice(0, 12)}`,
+		`- Score: ${round.score}/10, ${code(round.rationale)}`,
+	];
+	if (round.findings.length === 0) lines.push("- Findings: none");
+	else lines.push("- Findings, open until the next round settles them:");
+	for (const finding of round.findings)
+		lines.push(`  - ${capitalized(finding.severity)}, ${code(located(finding))}: ${code(finding.title)}`);
+	const settled = round.earlier?.findings ?? [];
+	if (settled.length > 0) lines.push(`- The last round's findings, at ${round.earlier!.head.slice(0, 12)}:`);
+	for (const finding of settled)
+		lines.push(
+			`  - ${capitalized(finding.disposition)}: ${finding.severity}, ${code(located(finding))}: ${code(finding.title)}; ${code(finding.reason)}`,
+		);
+	return lines.join("\n");
+}
+
+/**
+ * `body` with `record` as its first `## Review` section, which it gains when it has none. The section
+ * runs to the next level-1 or level-2 heading, as the land gate reads it; the rest of the body stays as written.
+ */
+export function withReview(body: string, record: string): string {
+	const heading = /^##[ \t]+Review[ \t]*\r?$/m.exec(body);
+	if (!heading) return `${body.trimEnd()}${body.trim() ? "\n\n" : ""}## Review\n\n${record}\n`;
+	const start = heading.index + heading[0].length;
+	const next = /^##?[ \t]/m.exec(body.slice(start));
+	const end = next ? start + next.index : body.length;
+	return `${body.slice(0, start)}\n\n${record}\n${end < body.length ? "\n" : ""}${body.slice(end)}`;
+}
+
+/** Where a round's record went: the PR whose body holds it, or why no body changed. */
+export type Recorded = { url: string } | { skipped: string };
+
+/**
+ * Record `round` in the `## Review` section of the open PR from its branch into its base, found among the
+ * upstream's PRs from the repository the base's remote pushes to, as claims find a branch's PR. The edit
+ * is the token's user's, which the land gate counts only when that user wrote the PR.
+ */
+export async function recordRound(root: string, round: Round, deps: ClaimDependencies): Promise<Recorded> {
+	const { remote, branch: base } = parseBase(root, round.base.ref);
+	const up = await upstream(root, requireRemote(root, remote), deps);
+	if (up.github === null) return { skipped: `${remote} is not on GitHub` };
+	const { client, repository, head } = up.github;
+	const from = `${head.owner}:${round.branch}`;
+	const query = `state=open&head=${encodeURIComponent(from)}&base=${encodeURIComponent(base)}&per_page=100`;
+	const [pull] = await client.all(`${repositoryPath(repository)}/pulls?${query}`);
+	if (pull === undefined) return { skipped: `no open PR from ${from} into ${base}` };
+	const body = typeof pull.body === "string" ? pull.body : "";
+	const next = withReview(body, reviewRecord(round));
+	if (next !== body)
+		await client.request(`${repositoryPath(repository)}/pulls/${Number(pull.number)}`, {
+			method: "PATCH",
+			body: { body: next },
+		});
+	return { url: string(pull.html_url) };
+}
diff --git a/src/cli/review.ts b/src/cli/review.ts
index 92d3bb5c..0809634f 100644
--- a/src/cli/review.ts
+++ b/src/cli/review.ts
@@ -35,6 +35,8 @@ export class ReviewLimitError extends Error {
 }
 
 export const SEVERITIES = ["high", "medium", "low"] as const;
+/** What became of a finding by the next round: the head fixes it, the author's refutation holds, or it still holds. */
+export const DISPOSITIONS = ["fixed", "refuted", "open"] as const;
 
 export interface Finding {
 	/** Repository-relative path. */
@@ -47,6 +49,13 @@ export interface Finding {
 	body: string;
 }
 
+/** A finding of the last round, with what became of it by this one. */
+export interface Settled extends Finding {
+	disposition: (typeof DISPOSITIONS)[number];
+	/** One sentence citing the fix or the refutation's evidence, or why it still holds. */
+	reason: string;
+}
+
 /** Tokens one reviewer turn reported; `cached` is the part of `input` read from the prompt cache. */
 export interface Usage {
 	turn: "review" | "findings";
@@ -60,6 +69,8 @@ export interface Round {
 	reviewer: HarnessName;
 	model: string;
 	effort: string;
+	/** The branch whose session the round continues. */
+	branch: string;
 	/** The PR size that picked the reviewer. */
 	size: Size;
 	/** Where the size came from: the quest's path on the base, `--size`, or `default`. */
@@ -75,16 +86,20 @@ export interface Round {
 	/** One sentence on why. */
 	rationale: string;
 	findings: Finding[];
+	/** The last round's head and its findings, settled by this round; null on the branch's first round. */
+	earlier: { head: string; findings: Settled[] } | null;
 }
 
-/** A reply's verdict on the reviewed head. */
-export type Verdict = Pick<Round, "score" | "rationale" | "findings">;
+/** A reply's verdict on the reviewed head; `earlier` settles the last round's findings by their 1-based number. */
+export type Verdict = Pick<Round, "score" | "rationale" | "findings"> & {
+	earlier: { finding: number; disposition: Settled["disposition"]; reason: string }[];
+};
 
 /** The reply every round's last turn must match; both CLIs enforce it, and `verdict` checks it again. */
 export const SCHEMA = {
 	type: "object",
 	additionalProperties: false,
-	required: ["score", "rationale", "findings"],
+	required: ["score", "rationale", "findings", "earlier"],
 	properties: {
 		score: { type: "integer", minimum: 0, maximum: 10 },
 		rationale: { type: "string" },
@@ -103,6 +118,19 @@ export const SCHEMA = {
 				},
 			},
 		},
+		earlier: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["finding", "disposition", "reason"],
+				properties: {
+					finding: { type: "integer", minimum: 1 },
+					disposition: { type: "string", enum: DISPOSITIONS },
+					reason: { type: "string" },
+				},
+			},
+		},
 	},
 } as const;
 
@@ -237,7 +265,7 @@ interface State {
 	branch: string;
 	reviewer: HarnessName;
 	session: string;
-	rounds: { head: string; findings: number }[];
+	rounds: { head: string; findings: Finding[] }[];
 	/**
 	 * Digests of the instruction files the session started with, and the
 	 * REVIEW.md it was last given. A resumed session keeps its first system or
@@ -726,8 +754,11 @@ async function turn(cli: Cli, call: Turn, cwd: string): Promise<Reply> {
 	return reply;
 }
 
-/** The verdict in a reply, checked against `SCHEMA` so a malformed reply fails rather than reads as clean. */
-export function verdict(reply: { structured?: unknown; text?: string }): Verdict {
+/**
+ * The verdict in a reply, checked against `SCHEMA` so a malformed reply fails rather than reads as clean,
+ * and settling each of the last round's `earlier` findings exactly once.
+ */
+export function verdict(reply: { structured?: unknown; text?: string }, earlier: number): Verdict {
 	let value = reply.structured;
 	if (value === undefined) {
 		try {
@@ -767,7 +798,30 @@ export function verdict(reply: { structured?: unknown; text?: string }): Verdict
 			body: finding.body,
 		};
 	});
-	return { score: score as number, rationale: fields!.rationale, findings: found };
+	const answers = fields!.earlier;
+	if (!Array.isArray(answers)) throw new Error("the reviewer's reply has no earlier list");
+	const settled = answers.map((item, index) => {
+		const answer = record(item);
+		if (
+			answer === undefined ||
+			!Number.isSafeInteger(answer.finding) ||
+			!DISPOSITIONS.includes(answer.disposition as Settled["disposition"]) ||
+			typeof answer.reason !== "string" ||
+			answer.reason.trim() === ""
+		) {
+			throw new Error(`the reviewer's earlier entry ${index + 1} does not match the schema`);
+		}
+		return {
+			finding: answer.finding as number,
+			disposition: answer.disposition as Settled["disposition"],
+			reason: answer.reason,
+		};
+	});
+	const numbers = settled.map((answer) => answer.finding).sort((a, b) => a - b);
+	if (numbers.length !== earlier || numbers.some((n, i) => n !== i + 1)) {
+		throw new Error(`the reviewer's reply does not settle each of the last round's ${earlier} finding(s) once`);
+	}
+	return { score: score as number, rationale: fields!.rationale, findings: found, earlier: settled };
 }
 
 const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
@@ -834,7 +888,8 @@ const SCALE =
 const REPORT =
 	SCALE +
 	" Name each finding's file by its repository-relative path and its line at that head, or null when no single line fits. " +
-	"Its body gives the concrete scenario: the input or state, and the wrong result. Report an empty list when nothing holds.";
+	"Its body gives the concrete scenario: the input or state, and the wrong result. Report an empty list when nothing holds. " +
+	"Report `earlier` as an empty list unless earlier findings are listed above.";
 
 /** The base's REVIEW.md, if it has one. */
 export interface Rules {
@@ -858,10 +913,27 @@ function rulesParts(rules: Rules | null, first: boolean): string[] {
 	];
 }
 
-/** The author's responses to an earlier round, and how a refutation stands. */
-function responseParts(responses: string | undefined): string[] {
-	if (responses === undefined) return [];
+/** Where a finding is: its `path:line`, or its path when no single line fits. */
+export const located = (finding: Finding) => (finding.line === null ? finding.file : `${finding.file}:${finding.line}`);
+
+/**
+ * The last round's findings, numbered, which `earlier` settles, then the author's responses to them and
+ * how a refutation stands.
+ */
+function responseParts(earlier: Finding[], responses: string | undefined): string[] {
+	const parts: string[] = [];
+	if (earlier.length > 0) {
+		const list = earlier.map((f, i) => `${i + 1}. ${f.severity} ${located(f)} ${f.title}`).join("\n");
+		parts.push(
+			`The last review reported these findings, numbered:\n\n<earlier-findings>\n${list}\n</earlier-findings>`,
+			"Settle each in `earlier` by its number: `fixed` when the head fixes it, `refuted` when the author's " +
+				"refutation holds, or `open` when it still holds, reporting it in `findings` again. Give each a " +
+				"one-sentence reason citing the fix, the refutation's evidence, or why it still holds.",
+		);
+	}
+	if (responses === undefined) return parts;
 	return [
+		...parts,
 		`The author responded to the findings of an earlier review:\n\n<responses>\n${responses}\n</responses>`,
 		"Verify each response. A fix holds only if the head fixes the problem. A refutation holds only when it " +
 			"cites evidence you can check and cannot rebut: a `path:line`, a command's output, or a recorded maintainer " +
@@ -894,12 +966,12 @@ function scope({ base, mergeBase, head }: Change): string {
  * A session's follow-up turn: apply the base's REVIEW.md, if any, weigh any
  * responses to an earlier session's findings, and report in the schema.
  */
-export function firstPrompt(change: Change, rules: Rules | null, responses?: string): string {
+export function firstPrompt(change: Change, rules: Rules | null, earlier: Finding[] = [], responses?: string): string {
 	return [
 		`Report your review as JSON matching the response schema: every finding that holds at the head ${change.head}.`,
 		scope(change),
 		...rulesParts(rules, true),
-		...responseParts(responses),
+		...responseParts(earlier, responses),
 		REPORT,
 	].join("\n\n");
 }
@@ -907,6 +979,8 @@ export function firstPrompt(change: Change, rules: Rules | null, responses?: str
 /** What a later round tells the resumed session. */
 export interface LaterRound extends Change {
 	previous: string;
+	/** The findings of the review of `previous`. */
+	earlier: Finding[];
 	responses?: string;
 	rules: Rules | null;
 	/** The session was given REVIEW.md rules the base no longer has. */
@@ -923,7 +997,7 @@ export function laterPrompt(round: LaterRound): string {
 	if (round.rulesRemoved && round.rules === null) {
 		parts.push("The base no longer has a REVIEW.md, so the review rules you were given no longer apply.");
 	}
-	parts.push(...rulesParts(round.rules, false), ...responseParts(responses));
+	parts.push(...rulesParts(round.rules, false), ...responseParts(round.earlier, responses));
 	parts.push(
 		`Report as JSON matching the response schema every finding that holds at ${head}, including any the new changes introduce.`,
 		REPORT,
@@ -932,7 +1006,7 @@ export function laterPrompt(round: LaterRound): string {
 }
 
 /** `<remote>/<branch>` split at the longest remote name it starts with. */
-function parseBase(root: string, base: string): { remote: string; branch: string } {
+export function parseBase(root: string, base: string): { remote: string; branch: string } {
 	const remotes = git(root, ["remote"]).split("\n").filter(Boolean);
 	const remote = remotes.filter((name) => base.startsWith(`${name}/`)).sort((a, b) => b.length - a.length)[0];
 	if (remote === undefined || base.length === remote.length + 1) {
@@ -1052,9 +1126,10 @@ export async function review(options: ReviewOptions, deps: ReviewDependencies):
 	if (previous === undefined && options.responses !== undefined) {
 		throw new ResponsesError("--responses answers a previous round, and this branch has none to resume");
 	}
-	if (previous !== undefined && previous.findings > 0 && options.responses === undefined) {
+	const earlier = previous?.findings ?? [];
+	if (earlier.length > 0 && options.responses === undefined) {
 		throw new ResponsesError(
-			`the last round reported ${previous.findings} finding(s); pass --responses with a fix or refutation for each`,
+			`the last round reported ${earlier.length} finding(s); pass --responses with a fix or refutation for each`,
 		);
 	}
 
@@ -1096,13 +1171,14 @@ export async function review(options: ReviewOptions, deps: ReviewDependencies):
 		if (first.session === undefined) throw new Error(`${harness} did not report its session`);
 		session = first.session;
 		if (reported(first.usage)) usage.push({ turn: "review", ...first.usage });
-		const prompt = firstPrompt(change, rules, options.responses);
+		const prompt = firstPrompt(change, rules, earlier, options.responses);
 		reply = await turn(cli, reviewer.resume(context, session, prompt), root);
 	} else {
 		session = state!.session;
 		const prompt = laterPrompt({
 			...change,
 			previous: previous!.head,
+			earlier,
 			responses: options.responses,
 			rules,
 			rulesRemoved: state!.given.rules !== null,
@@ -1110,14 +1186,15 @@ export async function review(options: ReviewOptions, deps: ReviewDependencies):
 		reply = await turn(cli, reviewer.resume(context, session, prompt), root);
 	}
 	if (reported(reply.usage)) usage.push({ turn: "findings", ...reply.usage });
-	const { score, rationale, findings: found } = verdict(reply);
+	const { score, rationale, findings: found, earlier: answers } = verdict(reply, earlier.length);
 
-	const rounds = [...(resume ? state!.rounds : []), { head, findings: found.length }];
+	const rounds = [...(resume ? state!.rounds : []), { head, findings: found }];
 	save(statePath, { branch, reviewer: harness, session, rounds, given } satisfies State);
 	return {
 		reviewer: harness,
 		model: context.model,
 		effort: context.effort,
+		branch,
 		size: sized.size,
 		sizeFrom: sized.from,
 		session,
@@ -1128,6 +1205,19 @@ export async function review(options: ReviewOptions, deps: ReviewDependencies):
 		score,
 		rationale,
 		findings: found,
+		earlier:
+			previous === undefined
+				? null
+				: {
+						head: previous.head,
+						findings: answers
+							.sort((a, b) => a.finding - b.finding)
+							.map(({ finding, disposition, reason }) => ({
+								...earlier[finding - 1],
+								disposition,
+								reason,
+							})),
+					},
 	};
 }
 
@@ -1145,12 +1235,20 @@ export function roundLines(round: Round): string[] {
 		`findings ${round.findings.length}`,
 	];
 	for (const finding of round.findings) {
-		const where = finding.line === null ? finding.file : `${finding.file}:${finding.line}`;
 		lines.push(
 			"",
-			`${finding.severity} ${where} ${finding.title}`,
+			`${finding.severity} ${located(finding)} ${finding.title}`,
 			...finding.body.split("\n").map((l) => `  ${l}`),
 		);
 	}
+	const settled = round.earlier?.findings ?? [];
+	if (settled.length > 0) lines.push("", `earlier ${settled.length} ${round.earlier!.head}`);
+	for (const finding of settled) {
+		lines.push(
+			"",
+			`${finding.disposition} ${finding.severity} ${located(finding)} ${finding.title}`,
+			`  ${finding.reason.replace(/\s+/g, " ").trim()}`,
+		);
+	}
 	return lines;
 }
diff --git a/test/review.test.ts b/test/review.test.ts
index e68faaea..109cd4a3 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -29,6 +29,24 @@ const CODEX_LOGGED_OUT = "codex is not logged in to its default profile (CODEX_H
 const CLAUDE_LOGGED_OUT =
 	"claude is not logged in to its default profile (CLAUDE_CONFIG_DIR is unset); run `claude auth login`";
 
+/**
+ * The findings turn's reply, `reply`: FAKE_REPLY, or one finding. A JSON reply without `earlier` settles
+ * each earlier finding the prompt numbers as FAKE_DISPOSITION says, `fixed` by default.
+ */
+const REPLY = `
+const listed = /<earlier-findings>\\n([\\s\\S]*?)\\n<\\/earlier-findings>/.exec(stdin)?.[1] ?? "";
+const earlier = [...listed.matchAll(/^(\\d+)\\. /gm)].map((m) => ({
+	finding: Number(m[1]),
+	disposition: process.env.FAKE_DISPOSITION ?? "fixed",
+	reason: "Checked against the head.",
+}));
+let reply = process.env.FAKE_REPLY ?? JSON.stringify({ score: 8, rationale: "Lands once the off-by-one is fixed.", findings: [${JSON.stringify(FINDING)}] });
+try {
+	const parsed = JSON.parse(reply);
+	if (parsed && typeof parsed === "object" && !("earlier" in parsed)) reply = JSON.stringify({ ...parsed, earlier });
+} catch {}
+`;
+
 /**
  * Fake reviewer CLIs. Each logs its argv, stdin, and the variables it was
  * given, then answers as the FAKE_* variables say. FAKE_LOGGED_OUT removes the
@@ -86,7 +104,7 @@ if (argv.includes("--session-id")) {
 		},
 	});
 } else {
-	const reply = process.env.FAKE_REPLY ?? JSON.stringify({ score: 8, rationale: "Lands once the off-by-one is fixed.", findings: [${JSON.stringify(FINDING)}] });
+	${REPLY}
 	result({
 		session_id: at("--resume"),
 		result: reply,
@@ -142,7 +160,8 @@ if (argv[1] === "review") {
 } else {
 	event({ type: "thread.started", thread_id: argv[argv.length - 2] });
 	message("Checking the findings.");
-	message(process.env.FAKE_REPLY ?? JSON.stringify({ score: 8, rationale: "Lands once the off-by-one is fixed.", findings: [${JSON.stringify(FINDING)}] }));
+	${REPLY}
+	message(reply);
 	event({ type: "turn.completed", usage: { input_tokens: 100, cached_input_tokens: 80, output_tokens: 7 } });
 }
 `,
@@ -219,7 +238,14 @@ function setup(host: "CLAUDECODE" | "CODEX_THREAD_ID" | null = "CLAUDECODE"): Se
 	vi.stubEnv("FAKE_LOG", log);
 	// The session's own profile would change the logged-out errors.
 	const unset = [...HOST_CREDENTIALS, "CLAUDECODE", "CODEX_THREAD_ID", "CLAUDE_CONFIG_DIR", "CODEX_HOME"];
-	for (const name of [...unset, "FAKE_LOGGED_OUT", "FAKE_REJECTED", "FAKE_LIMITED", "FAKE_HANG"]) {
+	for (const name of [
+		...unset,
+		"FAKE_LOGGED_OUT",
+		"FAKE_REJECTED",
+		"FAKE_LIMITED",
+		"FAKE_HANG",
+		"FAKE_DISPOSITION",
+	]) {
 		vi.stubEnv(name, undefined);
 	}
 	if (host === "CLAUDECODE") vi.stubEnv("CLAUDECODE", "1");
@@ -801,6 +827,8 @@ fakes("codex reviews read-only with the base's instructions, then reports in the
 			"",
 			"high src/lib.ts:2 Off by one",
 			"  average([3]) is 0.",
+			// The fixture's origin is a local path, which can have no PR.
+			"record skipped: origin is not on GitHub",
 			"",
 		].join("\n"),
 	);
@@ -829,7 +857,7 @@ fakes("codex reviews read-only with the base's instructions, then reports in the
 	expect(second.stdin).toContain("BASE-REVIEW rule");
 	expect(second.stdin).toContain(head);
 	const schema = second.argv[second.argv.indexOf("--output-schema") + 1];
-	expect(JSON.parse(readFileSync(schema, "utf8")).required).toEqual(["score", "rationale", "findings"]);
+	expect(JSON.parse(readFileSync(schema, "utf8")).required).toEqual(["score", "rationale", "findings", "earlier"]);
 });
 
 fakes("--base reviews against another branch, fetched first, with that branch's instructions", async () => {
@@ -910,12 +938,18 @@ fakes("a later round resumes the session with the new head and the author's resp
 	expect(later.code).toBe(0);
 	expect(later.stdout).toContain("round 2\n");
 	expect(later.stdout).toContain("findings 0\n");
+	// The round settles the last round's finding, by its number in the prompt.
+	const first = git(s.repo, "rev-parse", "HEAD~1");
+	expect(later.stdout).toContain(
+		`earlier 1 ${first}\n\nfixed high src/lib.ts:2 Off by one\n  Checked against the head.\n`,
+	);
 
 	const calls = s.calls();
 	const resumed = calls.at(-1)!;
 	expect(resumed.argv.slice(0, 2)).toEqual(["exec", "resume"]);
 	expect(resumed.argv.at(-2)).toBe("thread-1");
 	expect(resumed.stdin).toContain("Fixed at src/lib.ts:1.");
+	expect(resumed.stdin).toContain("<earlier-findings>\n1. high src/lib.ts:2 Off by one\n</earlier-findings>");
 	expect(resumed.stdin).toContain("BASE-REVIEW rule");
 	expect(resumed.stdin).not.toContain("differ from those you were given");
 	const head = git(s.repo, "rev-parse", "HEAD");
@@ -960,6 +994,174 @@ fakes("a change to the applicable instructions starts a new session that weighs
 	expect(review.argv[1]).toBe("review");
 	expect(review.argv.find((arg) => arg.startsWith("developer_instructions="))).toContain("BASE-SRC new rule");
 	expect(followUp.stdin).toContain("Refuted: see src/lib.ts:1.");
+	// The new session is told the findings the responses answer.
+	expect(followUp.stdin).toContain("1. high src/lib.ts:2 Off by one");
+});
+
+/**
+ * Point the fixture's origin at `acme/widget` on GitHub, still fetched from its local copy, and answer the
+ * API with `pulls` as the open PRs from `acme:<branch>` into main. Returns the PR bodies each PATCH wrote.
+ */
+function onGitHub(repo: string, pulls: { number: number; body: string | null }[]): { body: string }[] {
+	const local = git(repo, "remote", "get-url", "origin");
+	git(repo, "remote", "set-url", "origin", "https://github.com/acme/widget.git");
+	git(repo, "config", `url.${local}.insteadOf`, "https://github.com/acme/widget.git");
+	const writes: { body: string }[] = [];
+	const json = (value: unknown) => new Response(JSON.stringify(value), { status: 200 });
+	vi.stubEnv("GH_TOKEN", "token");
+	vi.stubGlobal("fetch", async (input: URL, init?: RequestInit) => {
+		const url = new URL(input);
+		if (url.pathname === "/repos/acme/widget")
+			return json({
+				owner: { login: "acme" },
+				name: "widget",
+				fork: false,
+				default_branch: "main",
+				clone_url: "https://github.com/acme/widget.git",
+				ssh_url: "git@github.com:acme/widget.git",
+			});
+		if (url.pathname === "/repos/acme/widget/pulls") {
+			expect(url.searchParams.get("state")).toBe("open");
+			expect(url.searchParams.get("base")).toBe("main");
+			const head = url.searchParams.get("head");
+			return json(
+				head === "acme:feature"
+					? pulls.map((p) => ({ ...p, html_url: `https://github.com/acme/widget/pull/${p.number}` }))
+					: [],
+			);
+		}
+		const patched = /^\/repos\/acme\/widget\/pulls\/(\d+)$/.exec(url.pathname);
+		if (patched && init?.method === "PATCH") {
+			const { body } = JSON.parse(String(init.body)) as { body: string };
+			writes.push({ body });
+			pulls.find((p) => p.number === Number(patched[1]))!.body = body;
+			return json({});
+		}
+		throw new Error(`unexpected ${init?.method ?? "GET"} ${url.pathname}`);
+	});
+	return writes;
+}
+
+fakes("each round rewrites the Review section of the branch's open PR, keeping the author's prose", async () => {
+	const s = setup();
+	const pull = {
+		number: 7,
+		body: [
+			"Fixes averaging.",
+			"",
+			"## Review",
+			"",
+			"Hand-written record of an older head.",
+			"",
+			"## Models",
+			"",
+			"- Size: S",
+			"- Implementer: Claude Code, claude-opus-5-5, high effort",
+		].join("\r\n"),
+	};
+	const writes = onGitHub(s.repo, [pull]);
+	try {
+		const first = await quest("--root", s.repo, "review");
+		expect(first.stderr).toBe("");
+		expect(first.code).toBe(0);
+		expect(first.stdout).toContain("record https://github.com/acme/widget/pull/7\n");
+		const head = git(s.repo, "rev-parse", "HEAD");
+		const base = git(s.repo, "rev-parse", "origin/main");
+		expect(pull.body).toBe(
+			[
+				// The author's lines keep their line endings.
+				"Fixes averaging.\r\n\r\n## Review\r",
+				"",
+				"Rewritten by `quest review` after each round.",
+				"",
+				"- Reviewer: Codex, gpt-6.1-sol, high effort",
+				"- Session: `thread-1`, round 1",
+				`- Head: ${head}`,
+				`- Base: origin/main at ${base.slice(0, 12)}`,
+				"- Score: 8/10, `Lands once the off-by-one is fixed.`",
+				"- Findings, open until the next round settles them:",
+				"  - High, `src/lib.ts:2`: `Off by one`",
+				"",
+				"## Models\r\n\r\n- Size: S\r\n- Implementer: Claude Code, claude-opus-5-5, high effort",
+			].join("\n"),
+		);
+
+		// The next round settles that finding from the responses; model text never mentions, links, or names a full SHA.
+		write(s.repo, "src/lib.ts", "export const x = 4;\n");
+		git(s.repo, "commit", "-qam", "fix");
+		write(s.repo, ".tmp/responses.md", "1. Fixed at src/lib.ts:1.\n");
+		vi.stubEnv("FAKE_DISPOSITION", "refuted");
+		const title = `Ping @someone about \`${base}\` in #12`;
+		vi.stubEnv(
+			"FAKE_REPLY",
+			JSON.stringify({ score: 9, rationale: "Fixes #3.", findings: [{ ...FINDING, line: null, title }] }),
+		);
+		const second = await quest(
+			"--root",
+			s.repo,
+			"review",
+			"--responses",
+			join(s.repo, ".tmp", "responses.md"),
+			"--json",
+		);
+		expect(second.code).toBe(0);
+		expect(JSON.parse(second.stdout).record).toEqual({ url: "https://github.com/acme/widget/pull/7" });
+		const record = pull.body.split("## Review\r\n\n")[1]!.split("\n\n## Models")[0];
+		expect(record).toContain(`- Session: \`thread-1\`, round 2\n- Head: ${git(s.repo, "rev-parse", "HEAD")}\n`);
+		expect(record).toContain("- Score: 9/10, `Fixes #3.`\n");
+		expect(record).toContain(
+			`  - High, \`src/lib.ts\`: \`\`Ping @someone about \`${base.slice(0, 12)}\` in #12\`\`\n`,
+		);
+		expect(record).toContain(
+			`- The last round's findings, at ${head.slice(0, 12)}:\n  - Refuted: high, \`src/lib.ts:2\`: \`Off by one\`; \`Checked against the head.\``,
+		);
+		expect(record.match(/\b[0-9a-f]{40}\b/g)).toEqual([git(s.repo, "rev-parse", "HEAD")]);
+		expect(pull.body.startsWith("Fixes averaging.\r\n\r\n## Review\r\n\nRewritten")).toBe(true);
+		expect(writes).toHaveLength(2);
+	} finally {
+		vi.unstubAllGlobals();
+	}
+});
+
+fakes("a branch with no open PR, or a body without a Review section, is reported as such", async () => {
+	const s = setup();
+	const pulls: { number: number; body: string | null }[] = [];
+	onGitHub(s.repo, pulls);
+	try {
+		const none = await quest("--root", s.repo, "review");
+		expect(none.code).toBe(0);
+		expect(none.stdout).toContain("record skipped: no open PR from acme:feature into main\n");
+
+		pulls.push({ number: 8, body: null });
+		vi.stubEnv("FAKE_REPLY", JSON.stringify({ score: 10, rationale: "Lands as is.", findings: [] }));
+		write(s.repo, ".tmp/responses.md", "Fixed.\n");
+		const recorded = await quest("--root", s.repo, "review", "--responses", join(s.repo, ".tmp", "responses.md"));
+		expect(recorded.stdout).toContain("record https://github.com/acme/widget/pull/8\n");
+		expect(pulls[0]!.body).toMatch(
+			/^## Review\n\nRewritten by `quest review` after each round\.\n[\s\S]*- Findings: none\n/,
+		);
+	} finally {
+		vi.unstubAllGlobals();
+	}
+});
+
+fakes("a record GitHub refuses fails the command after printing the round", async () => {
+	const s = setup();
+	onGitHub(s.repo, [{ number: 9, body: "" }]);
+	const fetch = globalThis.fetch;
+	vi.stubGlobal("fetch", async (input: URL, init?: RequestInit) =>
+		init?.method === "PATCH"
+			? new Response('{"message":"Must have admin rights"}', { status: 403 })
+			: fetch(input, init),
+	);
+	try {
+		const result = await quest("--root", s.repo, "review");
+		expect(result.code).toBe(1);
+		expect(result.stdout).toContain("findings 1\n");
+		expect(result.stderr).toContain("the round finished, but recording it in the PR body failed: GitHub HTTP 403");
+	} finally {
+		vi.unstubAllGlobals();
+	}
 });
 
 /** Push a commit that `change` makes to origin's main, returning its SHA. */
@@ -994,18 +1196,41 @@ fakes("a reply that does not match the schema fails rather than reads as clean",
 	expect(unscored.stderr).toContain("no score from 0 to 10");
 });
 
-test("the verdict is checked field by field", () => {
-	const scored = { score: 7, rationale: "Fix the finding." };
-	expect(verdict({ structured: { ...scored, findings: [{ ...FINDING, line: null }] } })).toEqual({
+test("the verdict is checked field by field, settling each earlier finding once", () => {
+	const scored = { score: 7, rationale: "Fix the finding.", earlier: [] };
+	expect(verdict({ structured: { ...scored, findings: [{ ...FINDING, line: null }] } }, 0)).toEqual({
 		...scored,
 		findings: [{ ...FINDING, line: null }],
 	});
-	expect(() => verdict({ structured: { ...scored, findings: [{ ...FINDING, line: 0 }] } })).toThrow("does not match");
-	expect(() => verdict({ text: '{"verdict":"approve"}' })).toThrow("no findings list");
+	expect(() => verdict({ structured: { ...scored, findings: [{ ...FINDING, line: 0 }] } }, 0)).toThrow(
+		"does not match",
+	);
+	expect(() => verdict({ text: '{"verdict":"approve"}' }, 0)).toThrow("no findings list");
 	for (const score of [-1, 11, 7.5, "7", undefined]) {
-		expect(() => verdict({ structured: { ...scored, score, findings: [] } })).toThrow("no score from 0 to 10");
+		expect(() => verdict({ structured: { ...scored, score, findings: [] } }, 0)).toThrow("no score from 0 to 10");
+	}
+	expect(() => verdict({ structured: { ...scored, rationale: " ", findings: [] } }, 0)).toThrow("no rationale");
+
+	const fixed = { finding: 1, disposition: "fixed", reason: "src/lib.ts:2 divides by the length." };
+	const refuted = { finding: 2, disposition: "refuted", reason: "The maintainer decided it." };
+	const answered = { ...scored, findings: [], earlier: [refuted, fixed] };
+	expect(verdict({ structured: answered }, 2).earlier).toEqual([refuted, fixed]);
+	expect(() => verdict({ structured: { ...scored, findings: [], earlier: undefined } }, 0)).toThrow(
+		"no earlier list",
+	);
+	// Each of the last round's findings is settled exactly once, by its number.
+	for (const earlier of [[fixed], [fixed, fixed], [fixed, { ...refuted, finding: 3 }]]) {
+		expect(() => verdict({ structured: { ...scored, findings: [], earlier } }, 2)).toThrow("settle each");
+	}
+	for (const bad of [
+		{ ...fixed, disposition: "deferred" },
+		{ ...fixed, reason: " " },
+		{ ...fixed, finding: 1.5 },
+	]) {
+		expect(() => verdict({ structured: { ...scored, findings: [], earlier: [bad] } }, 1)).toThrow(
+			"earlier entry 1",
+		);
 	}
-	expect(() => verdict({ structured: { score: 7, rationale: " ", findings: [] } })).toThrow("no rationale");
 });
 
 test("each changed directory keeps its own instructions, and a directory's symlink is given once", () => {
diff --git a/test/runner.test.ts b/test/runner.test.ts
index 5f3fff4a..4c37d615 100644
--- a/test/runner.test.ts
+++ b/test/runner.test.ts
@@ -2719,6 +2719,7 @@ describe("runner reviews", () => {
 			reviewer: request.reviewer.harness,
 			model: "gpt-6.1-sol",
 			effort: "medium",
+			branch: "quest/m0/one",
 			size: "M",
 			sizeFrom: "default",
 			session: "s",
@@ -2729,6 +2730,7 @@ describe("runner reviews", () => {
 			score: found[round - 1]?.length ? 8 : 10,
 			rationale: "Scored.",
 			findings: (found[round - 1] ?? []) as Round["findings"],
+			earlier: null,
 		});
 	}
 	const tools = (r: Rig) => r.calls().filter((call) => call.tool);

From 812522be4056e00198ab51748be3f850fdf61f8c Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 11:17:43 -0800
Subject: [PATCH 2/6] fix(review): bound each round's reply schema to the last
 round's findings

A first round's reply settled the findings of its own review turn, which
failed the round. The schema now requires exactly as many `earlier`
entries as the last round had findings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/cli/review.ts                | 87 ++++++++++++++++++--------------
 test/live/review-sandbox.test.ts |  3 +-
 test/review.test.ts              |  4 ++
 3 files changed, 55 insertions(+), 39 deletions(-)

diff --git a/src/cli/review.ts b/src/cli/review.ts
index 0809634f..019ba8d1 100644
--- a/src/cli/review.ts
+++ b/src/cli/review.ts
@@ -95,44 +95,51 @@ export type Verdict = Pick<Round, "score" | "rationale" | "findings"> & {
 	earlier: { finding: number; disposition: Settled["disposition"]; reason: string }[];
 };
 
-/** The reply every round's last turn must match; both CLIs enforce it, and `verdict` checks it again. */
-export const SCHEMA = {
-	type: "object",
-	additionalProperties: false,
-	required: ["score", "rationale", "findings", "earlier"],
-	properties: {
-		score: { type: "integer", minimum: 0, maximum: 10 },
-		rationale: { type: "string" },
-		findings: {
-			type: "array",
-			items: {
-				type: "object",
-				additionalProperties: false,
-				required: ["file", "line", "severity", "title", "body"],
-				properties: {
-					file: { type: "string" },
-					line: { type: ["integer", "null"] },
-					severity: { type: "string", enum: SEVERITIES },
-					title: { type: "string" },
-					body: { type: "string" },
+/**
+ * The reply a round's last turn must match, settling exactly the last round's `earlier` findings; both CLIs
+ * enforce it, and `verdict` checks it again. Without the bound, a first round's reply settles the findings
+ * of its own review turn.
+ */
+export const schema = (earlier: number) =>
+	({
+		type: "object",
+		additionalProperties: false,
+		required: ["score", "rationale", "findings", "earlier"],
+		properties: {
+			score: { type: "integer", minimum: 0, maximum: 10 },
+			rationale: { type: "string" },
+			findings: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					required: ["file", "line", "severity", "title", "body"],
+					properties: {
+						file: { type: "string" },
+						line: { type: ["integer", "null"] },
+						severity: { type: "string", enum: SEVERITIES },
+						title: { type: "string" },
+						body: { type: "string" },
+					},
 				},
 			},
-		},
-		earlier: {
-			type: "array",
-			items: {
-				type: "object",
-				additionalProperties: false,
-				required: ["finding", "disposition", "reason"],
-				properties: {
-					finding: { type: "integer", minimum: 1 },
-					disposition: { type: "string", enum: DISPOSITIONS },
-					reason: { type: "string" },
+			earlier: {
+				type: "array",
+				minItems: earlier,
+				maxItems: earlier,
+				items: {
+					type: "object",
+					additionalProperties: false,
+					required: ["finding", "disposition", "reason"],
+					properties: {
+						finding: { type: "integer", minimum: 1, maximum: Math.max(earlier, 1) },
+						disposition: { type: "string", enum: DISPOSITIONS },
+						reason: { type: "string" },
+					},
 				},
 			},
 		},
-	},
-} as const;
+	}) as const;
 
 /**
  * The harness running this command, from the variables each sets for its
@@ -285,7 +292,8 @@ export interface Context {
 	instructions: string;
 	model: string;
 	effort: string;
-	/** Where `--output-schema` reads the schema from. */
+	/** The reply's schema, and where `--output-schema` reads it from. */
+	schema: ReturnType<typeof schema>;
 	schemaFile: string;
 }
 
@@ -416,7 +424,7 @@ const claude: Reviewer = {
 		env: claudeEnv(),
 	}),
 	resume: (context, session, prompt) => ({
-		argv: [...claudeFlags(context), "--resume", session, "--json-schema", JSON.stringify(SCHEMA)],
+		argv: [...claudeFlags(context), "--resume", session, "--json-schema", JSON.stringify(context.schema)],
 		stdin: prompt,
 		env: claudeEnv(),
 	}),
@@ -755,7 +763,7 @@ async function turn(cli: Cli, call: Turn, cwd: string): Promise<Reply> {
 }
 
 /**
- * The verdict in a reply, checked against `SCHEMA` so a malformed reply fails rather than reads as clean,
+ * The verdict in a reply, checked against `schema` so a malformed reply fails rather than reads as clean,
  * and settling each of the last round's `earlier` findings exactly once.
  */
 export function verdict(reply: { structured?: unknown; text?: string }, earlier: number): Verdict {
@@ -1147,14 +1155,17 @@ export async function review(options: ReviewOptions, deps: ReviewDependencies):
 		.split("\0")
 		.filter(Boolean);
 
-	const schemaFile = join(dir, "schema.json");
-	save(schemaFile, SCHEMA);
+	// Named by its bound, so a round on another branch never rewrites the file this one reads.
+	const replySchema = schema(earlier.length);
+	const schemaFile = join(dir, `schema-${earlier.length}.json`);
+	save(schemaFile, replySchema);
 	const files = baseInstructions(root, baseSha, changed);
 	const context: Context = {
 		mergeBase,
 		instructions: instructionsPrompt(baseSha, files),
 		model: picked.model,
 		effort: picked.effort,
+		schema: replySchema,
 		schemaFile,
 	};
 
diff --git a/test/live/review-sandbox.test.ts b/test/live/review-sandbox.test.ts
index 7a360f43..7529ce05 100644
--- a/test/live/review-sandbox.test.ts
+++ b/test/live/review-sandbox.test.ts
@@ -28,7 +28,7 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 
 import { type HarnessName, strippedEnvironment } from "../../src/cli/agent";
 import { DEFAULT_SIZE, REVIEWERS } from "../../src/cli/models";
-import { ReviewInputError, claudeFlags, review, reviewerEnvironment } from "../../src/cli/review";
+import { ReviewInputError, claudeFlags, review, reviewerEnvironment, schema } from "../../src/cli/review";
 
 /** The model a sizeless review runs on `harness`. */
 const modelOf = (harness: HarnessName) => REVIEWERS[DEFAULT_SIZE].find((entry) => entry.harness === harness)!.model;
@@ -377,6 +377,7 @@ describe.each(["codex", "claude"] as const)("%s", (harness) => {
 				instructions: "Do what the user asks.",
 				model: modelOf("claude"),
 				effort: EFFORT,
+				schema: schema(0),
 				schemaFile: "",
 			};
 			const [program, ...args] = claudeFlags(context);
diff --git a/test/review.test.ts b/test/review.test.ts
index 109cd4a3..f5c370ff 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -858,6 +858,8 @@ fakes("codex reviews read-only with the base's instructions, then reports in the
 	expect(second.stdin).toContain(head);
 	const schema = second.argv[second.argv.indexOf("--output-schema") + 1];
 	expect(JSON.parse(readFileSync(schema, "utf8")).required).toEqual(["score", "rationale", "findings", "earlier"]);
+	// A first round settles nothing, so its own review turn's findings never land in `earlier`.
+	expect(JSON.parse(readFileSync(schema, "utf8")).properties.earlier).toMatchObject({ minItems: 0, maxItems: 0 });
 });
 
 fakes("--base reviews against another branch, fetched first, with that branch's instructions", async () => {
@@ -948,6 +950,8 @@ fakes("a later round resumes the session with the new head and the author's resp
 	const resumed = calls.at(-1)!;
 	expect(resumed.argv.slice(0, 2)).toEqual(["exec", "resume"]);
 	expect(resumed.argv.at(-2)).toBe("thread-1");
+	const bounded = JSON.parse(readFileSync(resumed.argv[resumed.argv.indexOf("--output-schema") + 1], "utf8"));
+	expect(bounded.properties.earlier).toMatchObject({ minItems: 1, maxItems: 1 });
 	expect(resumed.stdin).toContain("Fixed at src/lib.ts:1.");
 	expect(resumed.stdin).toContain("<earlier-findings>\n1. high src/lib.ts:2 Off by one\n</earlier-findings>");
 	expect(resumed.stdin).toContain("BASE-REVIEW rule");

From 9f33cedfecadb7bd1ecf99f14f3578f2243d1d41 Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 12:15:38 -0800
Subject: [PATCH 3/6] fix(review): a record with open findings names no full
 SHA

The land gate counts any full SHA in the `## Review` section, so a round
that still reports findings names its head short. A reply that keeps an
earlier finding open must report it again. A first round's schema has no
`earlier` list: given one, the reviewer settled its own review turn's
findings there, and bounded to none, it never finished its reply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                |  14 +++---
 assets/CONTEXT.md        |   2 +-
 src/cli/review-record.ts |   5 +-
 src/cli/review.ts        | 102 ++++++++++++++++++++++-----------------
 test/review.test.ts      |  28 ++++++++---
 5 files changed, 90 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 23a9cd40..4783e19b 100644
--- a/README.md
+++ b/README.md
@@ -1136,7 +1136,8 @@ decide when the loop ends. Later rounds resume the same session with the new hea
 reported findings requires. A refutation stands only when it cites evidence the
 reviewer can check. The prompt numbers the last round's findings, and the reply
 settles each by its number as fixed, refuted, or still open, with a one-sentence
-reason; a reply that skips or repeats one fails like any malformed reply. A resumed session keeps the instructions it started with,
+reason; a reply that skips or repeats one, or keeps more open than it reports,
+fails like any malformed reply. A first round's schema has no such list. A resumed session keeps the instructions it started with,
 so a round whose applicable `AGENTS.md` or `CLAUDE.md` files changed starts a
 new session instead, which still weighs the responses. Resuming keeps the
 reviewer's prompt cache; Claude Code is asked for its 1-hour cache, and Codex
@@ -1177,11 +1178,12 @@ After each round, `quest review` rewrites the `## Review` section of the open PR
 from the branch into the base, found among the upstream's PRs from the
 repository the base's remote pushes to, and prints `record <url>`. The record
 names the reviewer harness, model, and effort, the session and round, the
-reviewed head's full SHA and the base's short one, the score and rationale, each
-finding with its location, and the last round's findings with their
-dispositions. Model text appears as inline code, so it mentions or links
-nothing, and only the reviewed head's SHA appears in full, since the land gate
-counts every full SHA the section names. The section runs to the next level-1 or
+reviewed head, the base's short SHA, the score and rationale, each finding with
+its location, and the last round's findings with their dispositions. The land
+gate counts every full SHA the section names as a review of that head, so the
+head appears in full only once a round reports no findings, and model text
+appears as inline code, which mentions or links nothing and never holds a full
+SHA. The section runs to the next level-1 or
 level-2 heading; the rest of the body stays as written, and a body without one
 gains it at the end. With no such PR, or a remote off GitHub, it changes nothing
 and prints `record skipped: <why>`. It edits as the user the GitHub token names
diff --git a/assets/CONTEXT.md b/assets/CONTEXT.md
index 4b3d8b2a..f5f7e747 100644
--- a/assets/CONTEXT.md
+++ b/assets/CONTEXT.md
@@ -137,7 +137,7 @@ List them as `Size: M` and one `Implementer: Codex, gpt-6.1-sol, high effort` li
 Read your model and effort rather than guess: Claude Code knows its model and exports `CLAUDE_EFFORT`; Codex records `model` and `effort` in the last `turn_context` of `~/.codex/sessions/*/*/*/rollout-*-$CODEX_THREAD_ID.jsonl`; Grok records `model_id` and `reasoning_effort` in `~/.grok/sessions/*/$GROK_SESSION_ID/chat_history.jsonl`.
 Write `unknown` for any you cannot find.
 The PR body's `## Review` section records the latest round, or the skip and its reason.
-`quest review` rewrites it after each round on a branch with an open PR: the reviewer harness, model, and effort, the session and round, the reviewed head SHA and base, the score out of 10 with its rationale, and each finding with its location and disposition, which the next round settles from your responses as fixed, refuted with the reason, or still open.
+`quest review` rewrites it after each round on a branch with an open PR: the reviewer harness, model, and effort, the session and round, the reviewed head and base, naming the head's full SHA only once a round reports no findings, the score out of 10 with its rationale, and each finding with its location and disposition, which the next round settles from your responses as fixed, refuted with the reason, or still open.
 Open the draft PR before the first round, and write a round's record by hand only when the round printed `record skipped`, as on another author's fork; add context only after the record, since the next round rewrites the section.
 Never block on a score: the findings and their refutations decide when the review is done.
 A review counts for the head whose SHA it names.
diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts
index 61d498b0..3392c456 100644
--- a/src/cli/review-record.ts
+++ b/src/cli/review-record.ts
@@ -8,7 +8,7 @@ const HARNESSES: Record<Round["reviewer"], string> = { claude: "Claude Code", co
 
 /**
  * Model text as one inline code span, so a mention, issue reference, or Markdown in it renders as text.
- * The land gate counts every full SHA the section names, so only the reviewed head appears in full.
+ * The land gate counts every full SHA the section names, so no full SHA appears in it.
  */
 function code(text: string): string {
 	const flat = text
@@ -29,7 +29,8 @@ export function reviewRecord(round: Round): string {
 		"",
 		`- Reviewer: ${HARNESSES[round.reviewer]}, ${round.model}, ${round.effort} effort`,
 		`- Session: ${code(round.session)}, round ${round.round}`,
-		`- Head: ${round.head}`,
+		// The land gate counts a full SHA here as a review of that head, which an open finding has not passed.
+		`- Head: ${round.findings.length === 0 ? round.head : `${round.head.slice(0, 12)}, named in full once a round reports no findings`}`,
 		`- Base: ${round.base.ref} at ${round.base.sha.slice(0, 12)}`,
 		`- Score: ${round.score}/10, ${code(round.rationale)}`,
 	];
diff --git a/src/cli/review.ts b/src/cli/review.ts
index 019ba8d1..006c7d7d 100644
--- a/src/cli/review.ts
+++ b/src/cli/review.ts
@@ -95,51 +95,58 @@ export type Verdict = Pick<Round, "score" | "rationale" | "findings"> & {
 	earlier: { finding: number; disposition: Settled["disposition"]; reason: string }[];
 };
 
-/**
- * The reply a round's last turn must match, settling exactly the last round's `earlier` findings; both CLIs
- * enforce it, and `verdict` checks it again. Without the bound, a first round's reply settles the findings
- * of its own review turn.
- */
-export const schema = (earlier: number) =>
-	({
+const FINDINGS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["score", "rationale", "findings"],
+	properties: {
+		score: { type: "integer", minimum: 0, maximum: 10 },
+		rationale: { type: "string" },
+		findings: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["file", "line", "severity", "title", "body"],
+				properties: {
+					file: { type: "string" },
+					line: { type: ["integer", "null"] },
+					severity: { type: "string", enum: SEVERITIES },
+					title: { type: "string" },
+					body: { type: "string" },
+				},
+			},
+		},
+	},
+} as const;
+
+const EARLIER = {
+	type: "array",
+	items: {
 		type: "object",
 		additionalProperties: false,
-		required: ["score", "rationale", "findings", "earlier"],
+		required: ["finding", "disposition", "reason"],
 		properties: {
-			score: { type: "integer", minimum: 0, maximum: 10 },
-			rationale: { type: "string" },
-			findings: {
-				type: "array",
-				items: {
-					type: "object",
-					additionalProperties: false,
-					required: ["file", "line", "severity", "title", "body"],
-					properties: {
-						file: { type: "string" },
-						line: { type: ["integer", "null"] },
-						severity: { type: "string", enum: SEVERITIES },
-						title: { type: "string" },
-						body: { type: "string" },
-					},
-				},
-			},
-			earlier: {
-				type: "array",
-				minItems: earlier,
-				maxItems: earlier,
-				items: {
-					type: "object",
-					additionalProperties: false,
-					required: ["finding", "disposition", "reason"],
-					properties: {
-						finding: { type: "integer", minimum: 1, maximum: Math.max(earlier, 1) },
-						disposition: { type: "string", enum: DISPOSITIONS },
-						reason: { type: "string" },
-					},
-				},
-			},
+			finding: { type: "integer", minimum: 1 },
+			disposition: { type: "string", enum: DISPOSITIONS },
+			reason: { type: "string" },
 		},
-	}) as const;
+	},
+} as const;
+
+/**
+ * The reply a round's last turn must match; both CLIs enforce it, and `verdict` checks it again. Only a
+ * round with the last round's findings to settle has `earlier`: given one, a first round settled its own
+ * review turn's findings there, and bounded to none, it never finished its reply.
+ */
+export const schema = (earlier: number) =>
+	earlier === 0
+		? FINDINGS
+		: {
+				...FINDINGS,
+				required: [...FINDINGS.required, "earlier"],
+				properties: { ...FINDINGS.properties, earlier: EARLIER },
+			};
 
 /**
  * The harness running this command, from the variables each sets for its
@@ -806,7 +813,7 @@ export function verdict(reply: { structured?: unknown; text?: string }, earlier:
 			body: finding.body,
 		};
 	});
-	const answers = fields!.earlier;
+	const answers = earlier === 0 && fields!.earlier === undefined ? [] : fields!.earlier;
 	if (!Array.isArray(answers)) throw new Error("the reviewer's reply has no earlier list");
 	const settled = answers.map((item, index) => {
 		const answer = record(item);
@@ -829,6 +836,11 @@ export function verdict(reply: { structured?: unknown; text?: string }, earlier:
 	if (numbers.length !== earlier || numbers.some((n, i) => n !== i + 1)) {
 		throw new Error(`the reviewer's reply does not settle each of the last round's ${earlier} finding(s) once`);
 	}
+	// A finding still open is one this round reports again; one left out of `findings` would read as clean.
+	const open = settled.filter((answer) => answer.disposition === "open").length;
+	if (open > found.length) {
+		throw new Error(`the reviewer's reply keeps ${open} earlier finding(s) open but reports ${found.length}`);
+	}
 	return { score: score as number, rationale: fields!.rationale, findings: found, earlier: settled };
 }
 
@@ -896,8 +908,7 @@ const SCALE =
 const REPORT =
 	SCALE +
 	" Name each finding's file by its repository-relative path and its line at that head, or null when no single line fits. " +
-	"Its body gives the concrete scenario: the input or state, and the wrong result. Report an empty list when nothing holds. " +
-	"Report `earlier` as an empty list unless earlier findings are listed above.";
+	"Its body gives the concrete scenario: the input or state, and the wrong result. Report an empty list when nothing holds.";
 
 /** The base's REVIEW.md, if it has one. */
 export interface Rules {
@@ -936,7 +947,8 @@ function responseParts(earlier: Finding[], responses: string | undefined): strin
 			`The last review reported these findings, numbered:\n\n<earlier-findings>\n${list}\n</earlier-findings>`,
 			"Settle each in `earlier` by its number: `fixed` when the head fixes it, `refuted` when the author's " +
 				"refutation holds, or `open` when it still holds, reporting it in `findings` again. Give each a " +
-				"one-sentence reason citing the fix, the refutation's evidence, or why it still holds.",
+				"one-sentence reason citing the fix, the refutation's evidence, or why it still holds. Settle only " +
+				"these; a review turn of this session reports this round's findings, never earlier ones.",
 		);
 	}
 	if (responses === undefined) return parts;
diff --git a/test/review.test.ts b/test/review.test.ts
index f5c370ff..d5c7b58c 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -857,9 +857,10 @@ fakes("codex reviews read-only with the base's instructions, then reports in the
 	expect(second.stdin).toContain("BASE-REVIEW rule");
 	expect(second.stdin).toContain(head);
 	const schema = second.argv[second.argv.indexOf("--output-schema") + 1];
-	expect(JSON.parse(readFileSync(schema, "utf8")).required).toEqual(["score", "rationale", "findings", "earlier"]);
 	// A first round settles nothing, so its own review turn's findings never land in `earlier`.
-	expect(JSON.parse(readFileSync(schema, "utf8")).properties.earlier).toMatchObject({ minItems: 0, maxItems: 0 });
+	const replySchema = JSON.parse(readFileSync(schema, "utf8"));
+	expect(replySchema.required).toEqual(["score", "rationale", "findings"]);
+	expect(replySchema.properties.earlier).toBeUndefined();
 });
 
 fakes("--base reviews against another branch, fetched first, with that branch's instructions", async () => {
@@ -951,7 +952,7 @@ fakes("a later round resumes the session with the new head and the author's resp
 	expect(resumed.argv.slice(0, 2)).toEqual(["exec", "resume"]);
 	expect(resumed.argv.at(-2)).toBe("thread-1");
 	const bounded = JSON.parse(readFileSync(resumed.argv[resumed.argv.indexOf("--output-schema") + 1], "utf8"));
-	expect(bounded.properties.earlier).toMatchObject({ minItems: 1, maxItems: 1 });
+	expect(bounded.required).toEqual(["score", "rationale", "findings", "earlier"]);
 	expect(resumed.stdin).toContain("Fixed at src/lib.ts:1.");
 	expect(resumed.stdin).toContain("<earlier-findings>\n1. high src/lib.ts:2 Off by one\n</earlier-findings>");
 	expect(resumed.stdin).toContain("BASE-REVIEW rule");
@@ -1080,7 +1081,8 @@ fakes("each round rewrites the Review section of the branch's open PR, keeping t
 				"",
 				"- Reviewer: Codex, gpt-6.1-sol, high effort",
 				"- Session: `thread-1`, round 1",
-				`- Head: ${head}`,
+				// The land gate counts a full SHA, which a head with an open finding does not earn.
+				`- Head: ${head.slice(0, 12)}, named in full once a round reports no findings`,
 				`- Base: origin/main at ${base.slice(0, 12)}`,
 				"- Score: 8/10, `Lands once the off-by-one is fixed.`",
 				"- Findings, open until the next round settles them:",
@@ -1111,7 +1113,9 @@ fakes("each round rewrites the Review section of the branch's open PR, keeping t
 		expect(second.code).toBe(0);
 		expect(JSON.parse(second.stdout).record).toEqual({ url: "https://github.com/acme/widget/pull/7" });
 		const record = pull.body.split("## Review\r\n\n")[1]!.split("\n\n## Models")[0];
-		expect(record).toContain(`- Session: \`thread-1\`, round 2\n- Head: ${git(s.repo, "rev-parse", "HEAD")}\n`);
+		expect(record).toContain(
+			`- Session: \`thread-1\`, round 2\n- Head: ${git(s.repo, "rev-parse", "HEAD").slice(0, 12)},`,
+		);
 		expect(record).toContain("- Score: 9/10, `Fixes #3.`\n");
 		expect(record).toContain(
 			`  - High, \`src/lib.ts\`: \`\`Ping @someone about \`${base.slice(0, 12)}\` in #12\`\`\n`,
@@ -1119,7 +1123,7 @@ fakes("each round rewrites the Review section of the branch's open PR, keeping t
 		expect(record).toContain(
 			`- The last round's findings, at ${head.slice(0, 12)}:\n  - Refuted: high, \`src/lib.ts:2\`: \`Off by one\`; \`Checked against the head.\``,
 		);
-		expect(record.match(/\b[0-9a-f]{40}\b/g)).toEqual([git(s.repo, "rev-parse", "HEAD")]);
+		expect(record).not.toMatch(/\b[0-9a-f]{40}\b/);
 		expect(pull.body.startsWith("Fixes averaging.\r\n\r\n## Review\r\n\nRewritten")).toBe(true);
 		expect(writes).toHaveLength(2);
 	} finally {
@@ -1144,6 +1148,8 @@ fakes("a branch with no open PR, or a body without a Review section, is reported
 		expect(pulls[0]!.body).toMatch(
 			/^## Review\n\nRewritten by `quest review` after each round\.\n[\s\S]*- Findings: none\n/,
 		);
+		// A round with no findings names its head in full, which the land gate counts.
+		expect(pulls[0]!.body.match(/\b[0-9a-f]{40}\b/g)).toEqual([git(s.repo, "rev-parse", "HEAD")]);
 	} finally {
 		vi.unstubAllGlobals();
 	}
@@ -1219,9 +1225,17 @@ test("the verdict is checked field by field, settling each earlier finding once"
 	const refuted = { finding: 2, disposition: "refuted", reason: "The maintainer decided it." };
 	const answered = { ...scored, findings: [], earlier: [refuted, fixed] };
 	expect(verdict({ structured: answered }, 2).earlier).toEqual([refuted, fixed]);
-	expect(() => verdict({ structured: { ...scored, findings: [], earlier: undefined } }, 0)).toThrow(
+	// A first round's schema has no `earlier`; a later one's requires it.
+	expect(verdict({ structured: { ...scored, findings: [], earlier: undefined } }, 0).earlier).toEqual([]);
+	expect(() => verdict({ structured: { ...scored, findings: [], earlier: undefined } }, 1)).toThrow(
 		"no earlier list",
 	);
+	// A finding kept open is reported again, so a reply cannot keep one open and read as clean.
+	const open = { ...fixed, disposition: "open" };
+	expect(() => verdict({ structured: { ...scored, findings: [], earlier: [open] } }, 1)).toThrow(
+		"keeps 1 earlier finding(s) open but reports 0",
+	);
+	expect(verdict({ structured: { ...scored, findings: [FINDING], earlier: [open] } }, 1).earlier).toEqual([open]);
 	// Each of the last round's findings is settled exactly once, by its number.
 	for (const earlier of [[fixed], [fixed, fixed], [fixed, { ...refuted, finding: 3 }]]) {
 		expect(() => verdict({ structured: { ...scored, findings: [], earlier } }, 2)).toThrow("settle each");

From 06265bbbb2120ba51ec0d2bcd58c2cf364c0412f Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 12:16:33 -0800
Subject: [PATCH 4/6] test(review): narrow the PR body in the record test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 test/review.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/review.test.ts b/test/review.test.ts
index d5c7b58c..aa0084ec 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -1149,7 +1149,7 @@ fakes("a branch with no open PR, or a body without a Review section, is reported
 			/^## Review\n\nRewritten by `quest review` after each round\.\n[\s\S]*- Findings: none\n/,
 		);
 		// A round with no findings names its head in full, which the land gate counts.
-		expect(pulls[0]!.body.match(/\b[0-9a-f]{40}\b/g)).toEqual([git(s.repo, "rev-parse", "HEAD")]);
+		expect(pulls[0]!.body!.match(/\b[0-9a-f]{40}\b/g)).toEqual([git(s.repo, "rev-parse", "HEAD")]);
 	} finally {
 		vi.unstubAllGlobals();
 	}

From 175b628f9c2aaf229142dc8f8a1e5d21632d29c3 Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 12:25:21 -0800
Subject: [PATCH 5/6] fix(review): find the Review section as Markdown parses
 it

A `## Review` line in a code fence read as the section, so a record
rewrite deleted the author's prose after it, and the land gate could
count a SHA in the example. The record writer, the land gate, and the
land fixer now share core's `reviewSection`. Recording also locates the
PR from the checkout's top level, so a review from a subdirectory of a
fork finds the upstream PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                       |  3 +-
 cloudflare/src/github/review.ts |  6 ++-
 cloudflare/test/review.test.ts  |  7 ++++
 src/cli/land-fixer.ts           |  6 +--
 src/cli/review-record.ts        | 21 +++++------
 src/core/index.ts               |  1 +
 src/core/review.ts              | 22 +++++++++++
 test/review.test.ts             | 67 +++++++++++++++++++++++++--------
 8 files changed, 101 insertions(+), 32 deletions(-)
 create mode 100644 src/core/review.ts

diff --git a/README.md b/README.md
index 4783e19b..331d03f1 100644
--- a/README.md
+++ b/README.md
@@ -1184,7 +1184,8 @@ gate counts every full SHA the section names as a review of that head, so the
 head appears in full only once a round reports no findings, and model text
 appears as inline code, which mentions or links nothing and never holds a full
 SHA. The section runs to the next level-1 or
-level-2 heading; the rest of the body stays as written, and a body without one
+level-2 heading, both as Markdown parses them, so an example in a code fence is
+text to the land gate and the record alike; the rest of the body stays as written, and a body without one
 gains it at the end. With no such PR, or a remote off GitHub, it changes nothing
 and prints `record skipped: <why>`. It edits as the user the GitHub token names
 (`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`), and the land gate counts the
diff --git a/cloudflare/src/github/review.ts b/cloudflare/src/github/review.ts
index 149830df..0cc657a2 100644
--- a/cloudflare/src/github/review.ts
+++ b/cloudflare/src/github/review.ts
@@ -5,6 +5,8 @@
 // except the `## Review` record a write-access author keeps in their own pull
 // request's body, which counts only on commits no App committed.
 
+import { reviewSection } from "quest/core";
+
 /** The check run a runner's `quest review` result becomes, written only by the App. */
 export const REVIEW_CHECK = "quest review";
 /** How many merges of the base since its review a head carries the review across; each costs about ten reads. */
@@ -141,8 +143,8 @@ function named(pull: Pick<PullRow, "author" | "body" | "userContentEdits">): Set
 	if (author?.__typename !== "User") return new Set();
 	const editor = pull.userContentEdits?.nodes[0]?.editor;
 	if (editor !== undefined && editor?.login.toLowerCase() !== author.login.toLowerCase()) return new Set();
-	const section = /^##[ \t]+Review[ \t]*$([\s\S]*?)(?=^##?[ \t]|(?![\s\S]))/m.exec(pull.body.replace(/\r/g, ""));
-	return new Set(section?.[1]!.match(/\b[0-9a-f]{40}\b/g) ?? []);
+	const section = reviewSection(pull.body);
+	return new Set(section ? (pull.body.slice(section.start, section.end).match(/\b[0-9a-f]{40}\b/g) ?? []) : []);
 }
 
 /**
diff --git a/cloudflare/test/review.test.ts b/cloudflare/test/review.test.ts
index a46756b9..a35c0ffb 100644
--- a/cloudflare/test/review.test.ts
+++ b/cloudflare/test/review.test.ts
@@ -319,6 +319,9 @@ describe("the review the inbox flags as missing before merge", () => {
 			null,
 		);
 		expect(observedGap(observed({ body: `## Review\n\nClean on ${head}.` }), head, "main")).toBeNull();
+		// The record is the top-level section, never an example of one in a code fence.
+		const fenced = `Example:\n\n\`\`\`md\n## Review\n\`\`\`\n\r\n## Review\r\n\r\nClean on ${head}.\r\n`;
+		expect(observedGap(observed({ body: fenced }), head, "main")).toBeNull();
 	});
 
 	it("gives the land gate's reason for a head nothing counts on", () => {
@@ -340,6 +343,10 @@ describe("the review the inbox flags as missing before merge", () => {
 		["the author's association rules out write access", { association: "CONTRIBUTOR" }],
 		["someone else last edited the body", { editor: "maintainer" }],
 		["the record names another commit", { body: `## Review\n\nClean on ${sha("old")}.` }],
+		[
+			"only an example of a record in a code fence names it",
+			{ body: `\`\`\`md\n## Review\n\nClean on ${head}.\n\`\`\`\n\n## Review\n\nSkipped.` },
+		],
 	])("does not count the author's record when %s", (_, overrides) => {
 		const body = `## Review\n\nClean on ${head}.`;
 		expect(observedGap(observed({ body, ...overrides }), head, "main")).toMatch(/^No review counts/);
diff --git a/src/cli/land-fixer.ts b/src/cli/land-fixer.ts
index 40131382..c93c7273 100644
--- a/src/cli/land-fixer.ts
+++ b/src/cli/land-fixer.ts
@@ -16,6 +16,7 @@ import {
 } from "node:fs";
 import { constants as osConstants } from "node:os";
 import { basename, join } from "node:path";
+import { reviewSection } from "../core";
 import { GitHub, type GitHubDependencies, object, string } from "./github";
 import {
 	baseRemote,
@@ -727,10 +728,9 @@ export function author(result?: Pick<FixResult, "agent" | "model" | "effort">):
 export function review(body: string, head: string, reason: string, attribution: string): string {
 	const line = `mechanical fix by ${attribution}: ${fixerText(reason)} (head ${head})`;
 	if (body.includes(line)) return body;
-	const section = /^## Review[ \t]*\r?$/m.exec(body);
+	const section = reviewSection(body);
 	if (!section) return `${body}\n\n## Review\n\n${line}`;
-	const start = section.index + section[0].length;
-	return `${body.slice(0, start)}\n\n${line}${body.slice(start)}`;
+	return `${body.slice(0, section.start)}\n\n${line}${body.slice(section.start)}`;
 }
 
 /**
diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts
index 3392c456..701f5337 100644
--- a/src/cli/review-record.ts
+++ b/src/cli/review-record.ts
@@ -1,6 +1,8 @@
 // `quest review` rewrites the `## Review` section of its branch's open PR after each round, so the head
 // it reviewed counts without an agent copying the round into the body by hand.
+import { reviewSection } from "../core";
 import { type ClaimDependencies, repositoryPath, upstream } from "./claims";
+import { git } from "./git";
 import { requireRemote, string } from "./github";
 import { type Round, located, parseBase } from "./review";
 
@@ -47,16 +49,11 @@ export function reviewRecord(round: Round): string {
 	return lines.join("\n");
 }
 
-/**
- * `body` with `record` as its first `## Review` section, which it gains when it has none. The section
- * runs to the next level-1 or level-2 heading, as the land gate reads it; the rest of the body stays as written.
- */
+/** `body` with `record` as its `## Review` section, which it gains when it has none; the rest stays as written. */
 export function withReview(body: string, record: string): string {
-	const heading = /^##[ \t]+Review[ \t]*\r?$/m.exec(body);
-	if (!heading) return `${body.trimEnd()}${body.trim() ? "\n\n" : ""}## Review\n\n${record}\n`;
-	const start = heading.index + heading[0].length;
-	const next = /^##?[ \t]/m.exec(body.slice(start));
-	const end = next ? start + next.index : body.length;
+	const section = reviewSection(body);
+	if (!section) return `${body.trimEnd()}${body.trim() ? "\n\n" : ""}## Review\n\n${record}\n`;
+	const { start, end } = section;
 	return `${body.slice(0, start)}\n\n${record}\n${end < body.length ? "\n" : ""}${body.slice(end)}`;
 }
 
@@ -69,8 +66,10 @@ export type Recorded = { url: string } | { skipped: string };
  * is the token's user's, which the land gate counts only when that user wrote the PR.
  */
 export async function recordRound(root: string, round: Round, deps: ClaimDependencies): Promise<Recorded> {
-	const { remote, branch: base } = parseBase(root, round.base.ref);
-	const up = await upstream(root, requireRemote(root, remote), deps);
+	// The checkout's top level, as the round reviewed it: a subdirectory would look for the quest tree below it.
+	const top = git(root, ["rev-parse", "--show-toplevel"]);
+	const { remote, branch: base } = parseBase(top, round.base.ref);
+	const up = await upstream(top, requireRemote(top, remote), deps);
 	if (up.github === null) return { skipped: `${remote} is not on GitHub` };
 	const { client, repository, head } = up.github;
 	const from = `${head.owner}:${round.branch}`;
diff --git a/src/core/index.ts b/src/core/index.ts
index ad780e2d..c3817b34 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -29,6 +29,7 @@ export {
 	size,
 } from "./doc";
 export { type ClosedPull, handBackWaits, handedBack, landed, withoutHandBack } from "./claim";
+export { reviewSection } from "./review";
 export { type Missed, type Moved, type Source, move, relocate, remove } from "./edit";
 export { comparePaths, normalize } from "./path";
 export { type Blocker, blockers, label, lookup, ready, renderBlocker } from "./ready";
diff --git a/src/core/review.ts b/src/core/review.ts
new file mode 100644
index 00000000..44475f15
--- /dev/null
+++ b/src/core/review.ts
@@ -0,0 +1,22 @@
+// A PR body's `## Review` record, which `quest review` writes and the land gate reads.
+
+import { markdown } from "./doc";
+
+/**
+ * Where the body of the first `## Review` section runs: from after its heading's line to the next level-1
+ * or level-2 heading's line, or the end. Only top-level headings count, as Markdown parses them, so an
+ * example inside a code fence, a list, or a quote is text. Null without one.
+ */
+export function reviewSection(body: string): { start: number; end: number } | null {
+	const lineStart = (offset: number) => body.lastIndexOf("\n", offset - 1) + 1;
+	let start: number | undefined;
+	for (const node of markdown(body).children) {
+		if (node.type !== "heading" || node.depth > 2) continue;
+		const from = node.position!.start.offset!;
+		if (start !== undefined) return { start, end: lineStart(from) };
+		const to = node.position!.end.offset!;
+		if (node.depth === 2 && /^##[ \t]+Review[ \t]*$/.test(body.slice(lineStart(from), to)))
+			start = body[to] === "\r" ? to + 1 : to;
+	}
+	return start === undefined ? null : { start, end: body.length };
+}
diff --git a/test/review.test.ts b/test/review.test.ts
index aa0084ec..66642408 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -14,6 +14,7 @@ import {
 	sessionFile,
 	verdict,
 } from "../src/cli/review";
+import { withReview } from "../src/cli/review-record";
 import { tempDir } from "./fixture";
 
 afterEach(() => {
@@ -1005,37 +1006,44 @@ fakes("a change to the applicable instructions starts a new session that weighs
 
 /**
  * Point the fixture's origin at `acme/widget` on GitHub, still fetched from its local copy, and answer the
- * API with `pulls` as the open PRs from `acme:<branch>` into main. Returns the PR bodies each PATCH wrote.
+ * API with `pulls` as the open PRs from `acme:<branch>` into main. With `fork`, `acme/widget` is a fork of
+ * `upstream/widget`, whose root holds the quest tree, and the PRs are upstream's. Returns the PR bodies
+ * each PATCH wrote.
  */
-function onGitHub(repo: string, pulls: { number: number; body: string | null }[]): { body: string }[] {
+function onGitHub(repo: string, pulls: { number: number; body: string | null }[], fork = false): { body: string }[] {
 	const local = git(repo, "remote", "get-url", "origin");
 	git(repo, "remote", "set-url", "origin", "https://github.com/acme/widget.git");
 	git(repo, "config", `url.${local}.insteadOf`, "https://github.com/acme/widget.git");
+	const owner = fork ? "upstream" : "acme";
 	const writes: { body: string }[] = [];
-	const json = (value: unknown) => new Response(JSON.stringify(value), { status: 200 });
+	const json = (value: unknown, status = 200) => new Response(JSON.stringify(value), { status });
+	const info = (login: string, parent: string | null) => ({
+		owner: { login },
+		name: "widget",
+		fork: parent !== null,
+		...(parent === null ? {} : { parent: { owner: { login: parent }, name: "widget" } }),
+		default_branch: "main",
+		clone_url: `https://github.com/${login}/widget.git`,
+		ssh_url: `git@github.com:${login}/widget.git`,
+	});
 	vi.stubEnv("GH_TOKEN", "token");
 	vi.stubGlobal("fetch", async (input: URL, init?: RequestInit) => {
 		const url = new URL(input);
-		if (url.pathname === "/repos/acme/widget")
-			return json({
-				owner: { login: "acme" },
-				name: "widget",
-				fork: false,
-				default_branch: "main",
-				clone_url: "https://github.com/acme/widget.git",
-				ssh_url: "git@github.com:acme/widget.git",
-			});
-		if (url.pathname === "/repos/acme/widget/pulls") {
+		if (url.pathname === "/repos/acme/widget") return json(info("acme", fork ? "upstream" : null));
+		if (url.pathname === "/repos/upstream/widget") return json(info("upstream", null));
+		if (url.pathname.startsWith("/repos/upstream/widget/contents/"))
+			return url.pathname.endsWith("/contents/quest/README.md") ? json({}) : json({}, 404);
+		if (url.pathname === `/repos/${owner}/widget/pulls`) {
 			expect(url.searchParams.get("state")).toBe("open");
 			expect(url.searchParams.get("base")).toBe("main");
 			const head = url.searchParams.get("head");
 			return json(
 				head === "acme:feature"
-					? pulls.map((p) => ({ ...p, html_url: `https://github.com/acme/widget/pull/${p.number}` }))
+					? pulls.map((p) => ({ ...p, html_url: `https://github.com/${owner}/widget/pull/${p.number}` }))
 					: [],
 			);
 		}
-		const patched = /^\/repos\/acme\/widget\/pulls\/(\d+)$/.exec(url.pathname);
+		const patched = new RegExp(`^/repos/${owner}/widget/pulls/(\\d+)$`).exec(url.pathname);
 		if (patched && init?.method === "PATCH") {
 			const { body } = JSON.parse(String(init.body)) as { body: string };
 			writes.push({ body });
@@ -1155,6 +1163,35 @@ fakes("a branch with no open PR, or a body without a Review section, is reported
 	}
 });
 
+fakes("a review from a subdirectory of a fork records on the upstream PR", async () => {
+	const s = setup();
+	const pull = { number: 11, body: "Body." };
+	onGitHub(s.repo, [pull], true);
+	try {
+		const result = await quest("--root", join(s.repo, "src"), "review");
+		expect(result.stderr).toBe("");
+		expect(result.stdout).toContain("record https://github.com/upstream/widget/pull/11\n");
+		expect(pull.body).toMatch(/^Body\.\n\n## Review\n\nRewritten by `quest review`/);
+	} finally {
+		vi.unstubAllGlobals();
+	}
+});
+
+test("the record replaces only a top-level Review section, never an example of one", () => {
+	const fenced = "Example:\n\n```md\n## Review\n\nold\n```\n\nAfter.\n";
+	expect(withReview(fenced, "new")).toBe(`${fenced.trimEnd()}\n\n## Review\n\nnew\n`);
+	const quoted = "> ## Review\n> quoted\n\n## Review\n\nold\n\n# Notes\n\n## Review\n\nsecond\n";
+	expect(withReview(quoted, "new")).toBe(
+		"> ## Review\n> quoted\n\n## Review\n\nnew\n\n# Notes\n\n## Review\n\nsecond\n",
+	);
+	// A level-3 heading stays inside the section, and a rewrite of the same record changes nothing.
+	const nested = "## Review\n\nold\n\n### Detail\n\nmore\n\n## Models\n\n- Size: S\n";
+	const once = withReview(nested, "new");
+	expect(once).toBe("## Review\n\nnew\n\n## Models\n\n- Size: S\n");
+	expect(withReview(once, "new")).toBe(once);
+	expect(withReview("", "new")).toBe("## Review\n\nnew\n");
+});
+
 fakes("a record GitHub refuses fails the command after printing the round", async () => {
 	const s = setup();
 	onGitHub(s.repo, [{ number: 9, body: "" }]);

From 47f66bc1c864adc9bdca06431c8e14b2d0959c5f Mon Sep 17 00:00:00 2001
From: Luke Curley <kixelated@gmail.com>
Date: Thu, 5 Nov 2026 12:30:40 -0800
Subject: [PATCH 6/6] fix(review): refuse a record that a body's unclosed
 construct would swallow

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                |  3 ++-
 src/cli/review-record.ts | 10 +++++++++-
 test/review.test.ts      |  3 +++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 331d03f1..e417c563 100644
--- a/README.md
+++ b/README.md
@@ -1186,7 +1186,8 @@ appears as inline code, which mentions or links nothing and never holds a full
 SHA. The section runs to the next level-1 or
 level-2 heading, both as Markdown parses them, so an example in a code fence is
 text to the land gate and the record alike; the rest of the body stays as written, and a body without one
-gains it at the end. With no such PR, or a remote off GitHub, it changes nothing
+gains it at the end, unless it ends inside an unclosed code fence or HTML
+comment, which fails the record. With no such PR, or a remote off GitHub, it changes nothing
 and prints `record skipped: <why>`. It edits as the user the GitHub token names
 (`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`), and the land gate counts the
 record only while the PR's author made the body's latest edit, so review your
diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts
index 701f5337..a8a35594 100644
--- a/src/cli/review-record.ts
+++ b/src/cli/review-record.ts
@@ -52,7 +52,15 @@ export function reviewRecord(round: Round): string {
 /** `body` with `record` as its `## Review` section, which it gains when it has none; the rest stays as written. */
 export function withReview(body: string, record: string): string {
 	const section = reviewSection(body);
-	if (!section) return `${body.trimEnd()}${body.trim() ? "\n\n" : ""}## Review\n\n${record}\n`;
+	if (!section) {
+		const appended = `${body.trimEnd()}${body.trim() ? "\n\n" : ""}## Review\n\n${record}\n`;
+		// A body that ends inside an unclosed code fence or HTML comment would swallow the heading.
+		if (reviewSection(appended) === null)
+			throw new Error(
+				"the PR body ends inside an unclosed code fence or HTML comment; close it so the record can follow",
+			);
+		return appended;
+	}
 	const { start, end } = section;
 	return `${body.slice(0, start)}\n\n${record}\n${end < body.length ? "\n" : ""}${body.slice(end)}`;
 }
diff --git a/test/review.test.ts b/test/review.test.ts
index 66642408..7223beec 100644
--- a/test/review.test.ts
+++ b/test/review.test.ts
@@ -1190,6 +1190,9 @@ test("the record replaces only a top-level Review section, never an example of o
 	expect(once).toBe("## Review\n\nnew\n\n## Models\n\n- Size: S\n");
 	expect(withReview(once, "new")).toBe(once);
 	expect(withReview("", "new")).toBe("## Review\n\nnew\n");
+	// A heading appended inside an unclosed construct would be no section, which the land gate never reads.
+	for (const open of ["```md\nunclosed", "<!-- unclosed"])
+		expect(() => withReview(open, "new")).toThrow("unclosed code fence or HTML comment");
 });
 
 fakes("a record GitHub refuses fails the command after printing the round", async () => {