Write the report a completed review was always for

Work item V5 of the M3 plan. A review could be run and every finding decided,
and then it produced nothing: no report, no export, nothing to send anyone.

The renderer is pure, so the exact text is testable without a database, and an
assembler gathers what it needs in one place rather than two routes drifting
about what a report contains. Two things make it more than a list of findings.

It says what was examined, not only what was found. A reader cannot otherwise
tell "nothing is wrong" from "nothing was looked at", and that distinction is
the whole value of a review. The counts come from the coverage ledger the
pipeline already reconciled, so they are what the app counted rather than what
a model claimed.

It records what the person decided, dismissals included, with their reasons. A
dismissal is evidence about the engine rather than an absence of one, and
dropping it would throw away the only signal that says which prompts need work.
Confirmed nitpicks stay too: what someone chose to keep is not the report's to
second-guess.

The protocol's own prose about output format is deliberately not parsed.
Rendering arbitrary instructions is not tractable, and a report whose shape
depended on prompt-shaped text would change meaning without anyone editing the
code that writes it.

Exports live outside the run directory, so a report outlives the worktrees,
bundle and logs that deleting a review removes. The filename uses the UTC day
and turns branch slashes into hyphens, so a second export the same day replaces
the first instead of accumulating near-identical files.

Eighteen unit tests on the text itself, including the no-em-dash rule that
binds every surface, plus two end-to-end tests that build the report from a
review which actually ran and write the export to disk. Three mutations
checked and all caught: dropping dismissals, omitting the completeness
statement, and reversing the severity order.

Author: Poolchaos

docs/DECISIONS.md

@@ -709,3 +709,23 @@ verified evidence, in writing, here.
   automatically. When the dependency has a branch of the same name as the one
   being reviewed it is preselected and labelled as suggested, because that is
   almost always the other half of the change, and almost always is not always.
+- 2026-07-31 DECIDED (V5, D-38): the report is the app's own rendering of the
+  finding format, and a protocol's prose about output format is not parsed.
+  Rendering arbitrary instructions is not tractable, and a report whose shape
+  depended on prompt-shaped text would change meaning without anyone editing
+  the code that writes it.
+- 2026-07-31 DECIDED (V5): the report states what was examined as well as what
+  was found. A reader cannot otherwise tell "nothing is wrong" from "nothing
+  was looked at", and that distinction is the whole value of a review. The
+  counts come from the coverage ledger the pipeline already reconciled, not
+  from anything a model claimed.
+- 2026-07-31 DECIDED (V5): dismissed findings appear in the report with their
+  reasons. A dismissal is evidence about the engine rather than an absence of
+  one, and dropping it would throw away the only signal that says which
+  prompts need work. Confirmed NITPICKs are kept too (D-11): what a person
+  chose to keep is not the report's to second-guess.
+- 2026-07-31 DECIDED (V5, D-39): exports are written under the data root's
+  exports directory, outside the run directory, so a report outlives the
+  worktrees, bundle and logs that deleting a review removes. The filename uses
+  the UTC day and turns branch slashes into hyphens, so a second export the
+  same day replaces the first rather than accumulating near-identical files.

docs/plans/M3-FINISH-PLAN.md

@@ -347,7 +347,7 @@ confirms the wiring.
 | V2 | confirm/dismiss/complete/context routes, confirmation UI, keyboard map | V1         | DONE   |
 | V3 | project detail page, fetch-now, links CRUD, project delete    | V1         | DONE   |
 | V4 | preflight route and panel, linked toggle with suggestion      | V3         | DONE   |
-| V5 | report renderer, report/export routes, report UI              | V2         |        |
+| V5 | report renderer, report/export routes, report UI              | V2         | DONE   |
 | V6 | resume/queued/merged/delete UI, settings editor, probe buttons | V2         |        |
 | V7 | rulesets detail, enable toggle, snapshot filter, export       | V1         |        |
 | V8 | e2e journey, theme screenshots, design audit, CI --e2e        | V2-V7      |        |

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

@@ -0,0 +1,57 @@
+/**
+ * Writes the report to a file.
+ *
+ * Exports live outside the run directory on purpose: deleting a review removes
+ * its worktrees, bundle and logs, and the report it produced should outlive
+ * all of that. It is the thing the review was for.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { repoSlug } from "@/lib/git/url";
+import { exportsDir } from "@/lib/paths";
+import { exportFileName, renderReport } from "@/lib/review/report";
+import { requireProject } from "@/server/db/repositories/projects";
+import { requireReview, statusOf } from "@/server/db/repositories/reviews";
+import { buildReportInput } from "@/server/review/report-input";
+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 { db, dataDir } = runtime();
+    const { id } = await context.params;
+
+    const review = requireReview(db, id);
+    const status = statusOf(review);
+    if (status !== "complete") {
+      return Response.json(
+        {
+          error: `This review is ${status.replace(/_/g, " ")}, so there is no report to export.`,
+          code: "NotComplete",
+        },
+        { status: 409 },
+      );
+    }
+
+    const markdown = renderReport(buildReportInput(db, id));
+    const name = exportFileName({
+      projectSlug: repoSlug(requireProject(db, review.projectId).name),
+      fromBranch: review.fromBranch,
+      intoBranch: review.intoBranch,
+      at: review.completedAt ?? review.createdAt,
+    });
+
+    const directory = exportsDir(dataDir);
+    await mkdir(directory, { recursive: true });
+    const path = join(directory, name);
+    await writeFile(path, markdown, "utf8");
+
+    return ok({ path, markdown });
+  });
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The report for a completed review.
+ *
+ * Only for a completed one: a report is the record of what a person accepted,
+ * so a review still waiting on decisions has nothing to report yet.
+ */
+
+import { renderReport } from "@/lib/review/report";
+import { requireReview, statusOf } from "@/server/db/repositories/reviews";
+import { buildReportInput } from "@/server/review/report-input";
+import { handler, ok } from "@/server/api/respond";
+import { runtime } from "@/server/runtime";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+): Promise<Response> {
+  return handler(async () => {
+    const { db } = runtime();
+    const { id } = await context.params;
+
+    const status = statusOf(requireReview(db, id));
+    if (status !== "complete") {
+      return Response.json(
+        {
+          error:
+            `This review is ${status.replace(/_/g, " ")}. A report is the record of what a ` +
+            "person accepted, so it exists once every finding has been decided.",
+          code: "NotComplete",
+        },
+        { status: 409 },
+      );
+    }
+
+    return ok({ markdown: renderReport(buildReportInput(db, id)) });
+  });
+}

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

@@ -58,6 +58,8 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
   const { id } = use(params);
   const [snapshot, setSnapshot] = useState<Snapshot | null>(null);
   const [live, setLive] = useState<string[]>([]);
+  const [report, setReport] = useState<string | null>(null);
+  const [exported, setExported] = useState("");
 
   async function reload() {
     const response = await fetch(`/api/reviews/${id}`);
@@ -221,6 +223,16 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
               </ol>
             </Card>
 
+            {review.status === "complete" ? (
+              <ReportPanel
+                reviewId={id}
+                report={report}
+                exported={exported}
+                onLoaded={setReport}
+                onExported={setExported}
+              />
+            ) : null}
+
             {review.status === "awaiting_confirmation" && reported.length > 0 ? (
               <ConfirmationQueue
                 reviewId={id}
@@ -277,6 +289,87 @@ export default function ReviewPage({ params }: { params: Promise<{ id: string }>
   );
 }
 
+/**
+ * The report, once a person has decided everything.
+ *
+ * Fetched on demand rather than with the page: it is the last thing anyone
+ * looks at, and a review that is still running has no report to speak of.
+ */
+function ReportPanel({
+  reviewId,
+  report,
+  exported,
+  onLoaded,
+  onExported,
+}: {
+  reviewId: string;
+  report: string | null;
+  exported: string;
+  onLoaded: (markdown: string) => void;
+  onExported: (path: string) => void;
+}) {
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    if (report !== null) return;
+    let cancelled = false;
+    void (async () => {
+      const response = await fetch(`/api/reviews/${reviewId}/report`);
+      const body = (await response.json()) as { markdown?: string; error?: string };
+      if (cancelled) return;
+      if (response.ok && body.markdown) onLoaded(body.markdown);
+      else setError(body.error ?? "The report could not be built.");
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [reviewId, report, onLoaded]);
+
+  return (
+    <section className="mb-6">
+      <header className="mb-3 flex flex-wrap items-center justify-between gap-3">
+        <h2 className="text-sm font-semibold">Report</h2>
+        <span className="flex items-center gap-2">
+          <Button
+            onClick={() => {
+              if (report) void navigator.clipboard?.writeText(report);
+            }}
+            disabled={!report}
+          >
+            Copy
+          </Button>
+          <Button
+            variant="primary"
+            onClick={async () => {
+              const response = await fetch(`/api/reviews/${reviewId}/export`, { method: "POST" });
+              const body = (await response.json()) as { path?: string; error?: string };
+              if (response.ok && body.path) onExported(body.path);
+              else setError(body.error ?? "The report could not be exported.");
+            }}
+          >
+            Export
+          </Button>
+        </span>
+      </header>
+
+      {error ? <Problem>{error}</Problem> : null}
+      {exported ? (
+        <p className="mb-2 text-xs text-[var(--color-good)]">Written to {exported}</p>
+      ) : null}
+
+      {report === null ? (
+        <p className="text-sm text-[var(--color-ink-muted)]">Building the report...</p>
+      ) : (
+        <Card className="max-h-[32rem] overflow-auto p-4">
+          <pre className="text-xs leading-5 whitespace-pre-wrap">
+            <code className="font-[family-name:var(--font-mono)]">{report}</code>
+          </pre>
+        </Card>
+      )}
+    </section>
+  );
+}
+
 function Stat({ label, value }: { label: string; value: string }) {
   return (
     <div className="flex justify-between gap-4">