Let a human decide every finding, and refuse to finish until they have

Work item V2 of the M3 plan: the loop the whole app exists to reach. Findings
could be produced and read, and there was no way to accept or reject one, so
the founding requirement, that nothing is reported until a person says so, was
not drivable at all.

Four routes: confirm, dismiss with a reason, complete, and the file context a
decision needs. Completing refuses while anything is undecided and says how
many, on the server rather than by hiding a button, because the gatekeeper is a
rule about the data and a script calling the API directly should meet the same
wall the screen does. Completing also releases the worktrees, which joins
cancelled and failed from V1 and finishes D-12: the confirmation screen was the
last thing that needed the checkout.

Dismissing requires a reason and confirming does not. Accepting the engine's
case adds nothing to it; a dismissal without a reason leaves no record of
whether the engine was wrong or the reviewer was in a hurry, and those two are
the difference between a prompt that needs fixing and one that does not.

The queue is built for someone working through twenty findings rather than
admiring one: j and k to move, c to confirm, d to dismiss, enter for the
surrounding code, and confirming jumps to the next undecided finding rather
than the next row. Decided findings collapse to a line instead of vanishing, so
what was dismissed and why stays on the page.

The file-context endpoint serves only paths a finding in that review cites,
and only while it awaits confirmation. The first guard's test initially passed
with the guard deleted, because it asked for a file that does not exist and the
404 came from the failed read; it now asks for a fixture file that genuinely
exists and that the reviewer deliberately finds nothing in, and the mutation is
caught.

Driven end to end against a running production server with the fake engine:
complete refused with seven undecided, context returned the lines around a
finding, one dismissal with a reason, six confirmations, complete accepted, and
the run directory left holding bundle and logs with the checkout gone. The
engine note added in V1 earned itself immediately, naming the fake in the run
so there was no question which binary answered.

Author: Poolchaos

docs/DECISIONS.md

@@ -656,3 +656,24 @@ verified evidence, in writing, here.
   confirmation; complete joins the cleanup list when the confirmation flow
   lands (D-12 as implemented). Cleanup is best effort: a failure to remove
   becomes a run note, never a mask over the outcome that matters.
+- 2026-07-31 DECIDED (V2, D-34): dismissing a finding requires a reason;
+  confirming does not. Accepting the engine's case adds nothing to it, while a
+  dismissal without a reason leaves no record of whether the engine was wrong
+  or the reviewer was in a hurry, and those two are the difference between a
+  prompt that needs fixing and one that does not.
+- 2026-07-31 DECIDED (V2, D-35): a review completes only when every finding is
+  decided, enforced by the complete route with the undecided count in the
+  message. The human gatekeeper is a rule about the data, so a script calling
+  the API directly meets the same wall the screen does.
+- 2026-07-31 DECIDED (V2, D-36): the file-context endpoint serves only paths a
+  finding in that review actually cites, and only while the review awaits
+  confirmation. Without the first guard it is a way to read any file on the
+  machine; without the second it promises a checkout that D-12 has already
+  removed. Proving the first guard needed a test using a file that genuinely
+  exists in the checkout: an absent path 404s from the failed read whether the
+  guard is there or not, and the first version of that test passed with the
+  guard deleted.
+- 2026-07-31 DECIDED (V2): completing a review removes its worktrees, joining
+  cancelled and failed from V1 (D-12 now fully implemented). The confirmation
+  screen was the last thing that needed the checkout; the bundle and the logs
+  stay as the evidence behind the report.

docs/plans/M3-FINISH-PLAN.md

@@ -344,7 +344,7 @@ confirms the wiring.
 | V  | Contents                                                     | Depends on | Status |
 | -- | ------------------------------------------------------------ | ---------- | ------ |
 | V1 | budget cap, engine note, no-auto-probe, worktree cleanup, 404 unlink, activity cap | -          | DONE   |
-| V2 | confirm/dismiss/complete/context routes, confirmation UI, keyboard map | V1         |        |
+| V2 | confirm/dismiss/complete/context routes, confirmation UI, keyboard map | V1         | DONE   |
 | V3 | project detail page, fetch-now, links CRUD, project delete    | V1         |        |
 | V4 | preflight route and panel, linked toggle with suggestion      | V3         |        |
 | V5 | report renderer, report/export routes, report UI              | V2         |        |

src/app/api/findings/[id]/confirm/route.ts

@@ -0,0 +1,23 @@
+/**
+ * A human accepting a finding.
+ *
+ * The whole app exists to reach this moment: nothing is reported until a
+ * person has said so. No reason is required, because accepting the engine's
+ * case adds nothing to it; dismissing does require one.
+ */
+
+import { confirmFinding } from "@/server/db/repositories/findings";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { id } = await context.params;
+    return ok({ finding: confirmFinding(runtime().db, id) });
+  });
+}

src/app/api/findings/[id]/dismiss/route.ts

@@ -0,0 +1,29 @@
+/**
+ * A human rejecting a finding, and saying why.
+ *
+ * The reason is the point. A dismissal without one leaves no record of
+ * whether the engine was wrong or the reviewer was in a hurry, and those two
+ * are the difference between a prompt that needs fixing and one that does not.
+ */
+
+import { z } from "zod";
+import { dismissFinding } from "@/server/db/repositories/findings";
+import { handler, ok, readJson } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+const body = z.object({
+  reason: z.string().trim().min(1, "a dismissal needs a reason"),
+});
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { id } = await context.params;
+    const { reason } = await readJson(request, body);
+    return ok({ finding: dismissFinding(runtime().db, id, reason) });
+  });
+}

src/app/api/reviews/[id]/complete/route.ts

@@ -0,0 +1,63 @@
+/**
+ * Closing a review, once every finding has been decided.
+ *
+ * Enforced here rather than by hiding the button: the human gatekeeper is a
+ * rule about the data, and a client that forgot to check, or a script calling
+ * the API directly, must hit the same wall. Completing also releases the
+ * worktrees, because the confirmation screen was the last thing that needed
+ * them (D-12).
+ */
+
+import { listFindingsByStatus } from "@/server/db/repositories/findings";
+import { requireReview, statusOf, transitionReview } from "@/server/db/repositories/reviews";
+import { removeReviewWorktrees } from "@/server/review/service";
+import { failed, handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db, dataDir, manager } = runtime();
+    const { id } = await context.params;
+
+    const status = statusOf(requireReview(db, id));
+    if (status !== "awaiting_confirmation") {
+      return Response.json(
+        {
+          error: `This review is ${status.replace(/_/g, " ")}, so there is nothing to complete.`,
+          code: "NotAwaitingConfirmation",
+        },
+        { status: 409 },
+      );
+    }
+
+    const undecided = listFindingsByStatus(db, id, ["verified", "open_question"]);
+    if (undecided.length > 0) {
+      return Response.json(
+        {
+          error:
+            `${undecided.length} finding(s) still need a decision. A report is the record ` +
+            "of what a person accepted, so every finding is confirmed or dismissed first.",
+          code: "UndecidedFindings",
+        },
+        { status: 409 },
+      );
+    }
+
+    transitionReview(db, id, "complete", { currentStage: null });
+
+    try {
+      await removeReviewWorktrees(db, id, dataDir);
+    } catch (error) {
+      // The review is complete either way; a stuck checkout is not a reason
+      // to refuse the decision the human already made.
+      return failed(error, 500);
+    }
+
+    return ok({ snapshot: manager.snapshot(id) });
+  });
+}

src/app/api/reviews/[id]/context/route.ts

@@ -0,0 +1,67 @@
+/**
+ * The lines around a finding, read from the review's own worktree.
+ *
+ * Two guards, both about not becoming a file server. The path must be one a
+ * finding in this review actually cites, so a caller cannot walk the disk by
+ * asking for something else. And the review must be awaiting confirmation,
+ * which is the only status whose worktree is guaranteed to still exist
+ * (D-12); afterwards the checkout is gone and the quoted code stored on each
+ * finding is the record.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { worktreeRootDir } from "@/lib/paths";
+import { listFindings } from "@/server/db/repositories/findings";
+import { requireReview, statusOf } from "@/server/db/repositories/reviews";
+import { handler, notFound, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+/** Enough to see the shape of the function a finding sits in. */
+const RADIUS = 20;
+
+export async function GET(
+  request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db, dataDir } = runtime();
+    const { id } = await context.params;
+    const url = new URL(request.url);
+    const path = url.searchParams.get("path") ?? "";
+    const line = Number.parseInt(url.searchParams.get("line") ?? "", 10);
+
+    const status = statusOf(requireReview(db, id));
+    if (status !== "awaiting_confirmation") {
+      return notFound(
+        `File context for a review that is ${status.replace(/_/g, " ")}. ` +
+          "The checkout only exists while the findings are being decided",
+      );
+    }
+
+    const cited = listFindings(db, id).some((finding) => finding.filePath === path);
+    if (!cited) return notFound("A file this review did not raise a finding in");
+
+    let contents: string;
+    try {
+      contents = await readFile(join(worktreeRootDir(dataDir, id), path), "utf8");
+    } catch {
+      return notFound(`${path} in the review's checkout`);
+    }
+
+    const all = contents.split("\n");
+    const centre = Number.isFinite(line) ? line : 1;
+    const start = Math.max(1, centre - RADIUS);
+    const end = Math.min(all.length, centre + RADIUS);
+
+    return ok({
+      path,
+      start,
+      end,
+      total: all.length,
+      lines: all.slice(start - 1, end).map((text, index) => ({ number: start + index, text })),
+    });
+  });
+}

src/app/reviews/[id]/page.tsx

@@ -10,6 +10,7 @@
  */
 
 import { use, useEffect, useState } from "react";
+import { ConfirmationQueue, type Finding } from "@/components/confirmation";
 import { PageBody, PageHeader } from "@/components/page";
 import {
   Badge,
@@ -49,16 +50,7 @@ interface Snapshot {
   };
   stages: { stage: string; status: string; attempt: number }[];
   notes: { kind: string; message: string; at: string }[];
-  findings: {
-    id: string;
-    filePath: string;
-    lineStart: number;
-    severity: string;
-    issue: string;
-    comment: string;
-    status: string;
-    quotedCode: string;
-  }[];
+  findings: Finding[];
   running: boolean;
 }
 
@@ -120,6 +112,54 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
   );
   const reported = findings.filter((finding) => finding.status !== "killed");
 
+  /**
+   * The findings as a list you can only read.
+   *
+   * Used while a review is still running, and after it is complete. Between
+   * those two the confirmation queue takes over, because that is the one
+   * moment the findings are a thing to act on rather than a thing to look at.
+   */
+  const renderReadOnly = () =>
+    reported.length === 0 ? (
+      <Empty title={snapshot.running ? "Nothing reported yet" : "No findings"}>
+        {snapshot.running
+          ? "Findings appear once the adversarial pass has run and each one has been checked against the file."
+          : "Every hunk was accounted for and nothing survived verification."}
+      </Empty>
+    ) : (
+      <ul className="grid gap-3">
+        {reported.map((finding) => (
+          <li key={finding.id}>
+            <Card className="p-4">
+              <div className="flex flex-wrap items-center gap-2">
+                <Badge tone={severityTone(finding.severity)}>{finding.severity}</Badge>
+                {finding.status === "confirmed" ? <Badge tone="good">confirmed</Badge> : null}
+                {finding.status === "dismissed" ? <Badge tone="neutral">dismissed</Badge> : null}
+                {finding.status === "open_question" ? (
+                  <Badge tone="question">open question</Badge>
+                ) : null}
+                <Mono className="text-xs text-[var(--color-ink-muted)]">
+                  {finding.filePath}:{finding.lineStart}
+                </Mono>
+              </div>
+              <p className="mt-2 font-medium">{finding.issue}</p>
+              <p className="mt-1 text-sm text-[var(--color-ink-muted)]">{finding.comment}</p>
+              {finding.dismissReason ? (
+                <p className="mt-1 text-xs text-[var(--color-ink-faint)]">
+                  Dismissed: {finding.dismissReason}
+                </p>
+              ) : null}
+              {finding.quotedCode ? (
+                <pre className="mt-3 overflow-x-auto rounded border border-[var(--color-border)] bg-[var(--color-surface-sunken)] p-3 text-xs">
+                  <code className="font-[family-name:var(--font-mono)]">{finding.quotedCode}</code>
+                </pre>
+              ) : null}
+            </Card>
+          </li>
+        ))}
+      </ul>
+    );
+
   return (
     <>
       <PageHeader
@@ -181,45 +221,19 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
               </ol>
             </Card>
 
-            <h2 className="mb-3 text-sm font-semibold">
-              Findings{reported.length > 0 ? ` (${reported.length})` : ""}
-            </h2>
-
-            {reported.length === 0 ? (
-              <Empty title={snapshot.running ? "Nothing reported yet" : "No findings"}>
-                {snapshot.running
-                  ? "Findings appear once the adversarial pass has run and each one has been checked against the file."
-                  : "Every hunk was accounted for and nothing survived verification."}
-              </Empty>
+            {review.status === "awaiting_confirmation" && reported.length > 0 ? (
+              <ConfirmationQueue
+                reviewId={id}
+                findings={findings}
+                onChanged={() => void reload()}
+              />
             ) : (
-              <ul className="grid gap-3">
-                {reported.map((finding) => (
-                  <li key={finding.id}>
-                    <Card className="p-4">
-                      <div className="flex flex-wrap items-center gap-2">
-                        <Badge tone={severityTone(finding.severity)}>{finding.severity}</Badge>
-                        {finding.status === "open_question" ? (
-                          <Badge tone="question">open question</Badge>
-                        ) : null}
-                        <Mono className="text-xs text-[var(--color-ink-muted)]">
-                          {finding.filePath}:{finding.lineStart}
-                        </Mono>
-                      </div>
-                      <p className="mt-2 font-medium">{finding.issue}</p>
-                      <p className="mt-1 text-sm text-[var(--color-ink-muted)]">
-                        {finding.comment}
-                      </p>
-                      {finding.quotedCode ? (
-                        <pre className="mt-3 overflow-x-auto rounded border border-[var(--color-border)] bg-[var(--color-surface-sunken)] p-3 text-xs">
-                          <code className="font-[family-name:var(--font-mono)]">
-                            {finding.quotedCode}
-                          </code>
-                        </pre>
-                      ) : null}
-                    </Card>
-                  </li>
-                ))}
-              </ul>
+              <>
+                <h2 className="mb-3 text-sm font-semibold">
+                  Findings{reported.length > 0 ? ` (${reported.length})` : ""}
+                </h2>
+                {renderReadOnly()}
+              </>
             )}
           </div>