feat(review): quest review records each round in the PR body

README.md

@@ -1134,7 +1134,10 @@ 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, 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
@@ -1167,14 +1170,35 @@ 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, 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, 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, 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
+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
 

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 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.
-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.

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.

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) ?? []) : []);
 }
 
 /**

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/);

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)}`;
 }
 
 /**

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) {

src/cli/review-record.ts

@@ -0,0 +1,95 @@
+// `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";
+
+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 no full SHA appears in it.
+ */
+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}`,
+		// 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)}`,
+	];
+	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 `## 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) {
+		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)}`;
+}
+
+/** 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> {
+	// 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}`;
+	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) };
+}