From 285fc038d7eea92731ff149c21f4c2119c6d40e0 Mon Sep 17 00:00:00 2001
From: Alejandro Perez <alejandro.perez.gancedo@gmail.com>
Date: Mon, 6 Jul 2026 17:18:11 +0100
Subject: [PATCH] app: adopt agent findings as review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An 'Add to review' action on finding rows (FindingsPanel + Briefing)
converts a finding into a local comment at its anchor, with the agent's
severity/title/rationale and an honest provenance footer. Posting to
the human's PR still rides the existing guarded Mirror / Submit-review
flows — two deliberate clicks between agent output and GitHub (§9).
Idempotent: an adopted finding shows Added and cannot double-post.
---
 app/src/components/BriefingFindings.tsx   | 37 +++++++++
 app/src/components/BriefingTab.tsx        | 26 ++++++
 app/src/components/DiffView.tsx           | 28 +++++++
 app/src/components/FindingsPanel.test.tsx | 50 ++++++++++++
 app/src/components/FindingsPanel.tsx      | 39 +++++++++
 app/src/lib/finding-comment.test.ts       | 99 +++++++++++++++++++++++
 app/src/lib/finding-comment.ts            | 58 +++++++++++++
 7 files changed, 337 insertions(+)
 create mode 100644 app/src/lib/finding-comment.test.ts
 create mode 100644 app/src/lib/finding-comment.ts

diff --git a/app/src/components/BriefingFindings.tsx b/app/src/components/BriefingFindings.tsx
index 48f87e3..e955c76 100644
--- a/app/src/components/BriefingFindings.tsx
+++ b/app/src/components/BriefingFindings.tsx
@@ -33,6 +33,14 @@ interface BriefingFindingsProps {
    * Briefing tab list.
    */
   readonly limit?: number;
+  /**
+   * Adopt a finding as a review comment (explicit click; outward posting still
+   * rides the guarded Mirror / Submit-review flows). Omitted by read-only
+   * surfaces (the board preview rail) and when the gate is not InReview.
+   */
+  readonly onAdopt?: ((finding: ReviewFinding) => void) | undefined;
+  /** Ids of findings that already have an adopted comment. */
+  readonly adoptedIds?: ReadonlySet<string> | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -55,9 +63,13 @@ function locationLabel(finding: ReviewFinding): string {
 function FindingRow({
   finding,
   onJumpTo,
+  onAdopt,
+  adopted,
 }: {
   readonly finding: ReviewFinding;
   readonly onJumpTo: (path: string, side: DiffSide, line: number) => void;
+  readonly onAdopt?: ((finding: ReviewFinding) => void) | undefined;
+  readonly adopted: boolean;
 }) {
   const meta = severityMeta(finding.severity);
   const [start] = finding.range;
@@ -94,6 +106,27 @@ function FindingRow({
         >
           {locationLabel(finding)}
         </span>
+        {onAdopt !== undefined &&
+          hasLine &&
+          (adopted ? (
+            <span
+              className="shrink-0 rounded border border-border/60 px-1.5 py-0.5 text-[10px] text-muted-foreground/70"
+              title="A review comment for this finding already exists"
+            >
+              Added ✓
+            </span>
+          ) : (
+            <button
+              type="button"
+              onClick={() => {
+                onAdopt(finding);
+              }}
+              className="shrink-0 cursor-pointer rounded border border-border bg-transparent px-1.5 py-0.5 text-[10px] text-muted-foreground hover:border-primary/50 hover:text-foreground"
+              title="Add this finding as a review comment (posts to GitHub only via Mirror / Submit review)"
+            >
+              Add to review
+            </button>
+          ))}
         {hasLine ? (
           <button
             type="button"
@@ -134,6 +167,8 @@ export function BriefingFindings({
   findings,
   onJumpTo,
   limit,
+  onAdopt,
+  adoptedIds,
 }: BriefingFindingsProps) {
   if (findings.length === 0) return null;
   const ranked = sortFindingsBySeverity(findings);
@@ -157,6 +192,8 @@ export function BriefingFindings({
             key={finding.id}
             finding={finding}
             onJumpTo={onJumpTo}
+            onAdopt={onAdopt}
+            adopted={adoptedIds?.has(finding.id) ?? false}
           />
         ))}
       </ul>
diff --git a/app/src/components/BriefingTab.tsx b/app/src/components/BriefingTab.tsx
index ab3146b..27402f3 100644
--- a/app/src/components/BriefingTab.tsx
+++ b/app/src/components/BriefingTab.tsx
@@ -20,6 +20,8 @@ import type { EvidenceSummary } from "../bindings/EvidenceSummary";
 import type { RecapPayload } from "../bindings/RecapPayload";
 import { useAppStore } from "../store";
 import { recapStale } from "@/lib/recap";
+import type { ReviewFinding } from "../bindings/ReviewFinding";
+import { adoptedFindingIds, findingCommentBody } from "@/lib/finding-comment";
 import { findingsBreakdown } from "./FindingsPanel";
 import { IntentHero } from "./IntentHero";
 import { InstrumentRow } from "./InstrumentRow";
@@ -44,6 +46,7 @@ export function BriefingTab({ review, active, onJumpToDiff }: BriefingTabProps)
   const fetchEvidence = useAppStore((s) => s.fetchEvidence);
   const fetchRecap = useAppStore((s) => s.fetchRecap);
   const preReview = useAppStore((s) => s.preReview);
+  const addComment = useAppStore((s) => s.addComment);
   const recap = useAppStore((s) => s.recaps[review.pr] ?? null);
   const appTheme = useAppStore((s) => s.config?.app_theme ?? "dark");
   const dark = appTheme !== "light";
@@ -119,6 +122,27 @@ export function BriefingTab({ review, active, onJumpToDiff }: BriefingTabProps)
   };
   const showRecap = hasRecapContent || stale;
 
+  // Adopt a finding as a local review comment (explicit click; outward posting
+  // still rides the guarded Mirror / Submit-review flows — §9). Commenting is
+  // only meaningful while the gate is InReview, matching the Diff tab's rule.
+  const canAdopt = review.gate_state === "InReview";
+  const adoptedFindings = useMemo(
+    () => adoptedFindingIds(review.review_findings, review.comments),
+    [review.review_findings, review.comments],
+  );
+  const handleAdoptFinding = useCallback(
+    (finding: ReviewFinding) => {
+      void addComment(
+        finding.path,
+        finding.range[0],
+        finding.range[1],
+        findingCommentBody(finding),
+        finding.side,
+      );
+    },
+    [addComment],
+  );
+
   return (
     <div className="h-full overflow-y-auto">
       <div className="mx-auto max-w-4xl space-y-5 px-6 py-6">
@@ -132,6 +156,8 @@ export function BriefingTab({ review, active, onJumpToDiff }: BriefingTabProps)
           <BriefingFindings
             findings={review.review_findings}
             onJumpTo={onJumpToDiff}
+            onAdopt={canAdopt ? handleAdoptFinding : undefined}
+            adoptedIds={adoptedFindings}
           />
         )}
 
diff --git a/app/src/components/DiffView.tsx b/app/src/components/DiffView.tsx
index 87dc1d7..018f538 100644
--- a/app/src/components/DiffView.tsx
+++ b/app/src/components/DiffView.tsx
@@ -47,6 +47,10 @@ import {
 import type { FileDiff } from "../diff-parser";
 import { pairRequests } from "@/lib/request-pairing";
 import { findingDecorations } from "@/lib/finding-decorations";
+import {
+  adoptedFindingIds,
+  findingCommentBody,
+} from "@/lib/finding-comment";
 import { elapsedSince } from "@/lib/relative-time";
 import { useAppStore } from "../store";
 import { registerCustomThemes } from "@/lib/monaco-themes";
@@ -882,6 +886,28 @@ export function DiffView({
   // Only open the input form when the review is InReview
   const effectiveActiveComment = canAddComments ? activeComment : null;
 
+  // Findings already adopted as review comments (idempotent Add-to-review).
+  const adoptedFindings = useMemo(
+    () => adoptedFindingIds(review.review_findings, review.comments),
+    [review.review_findings, review.comments],
+  );
+
+  // Adopt a finding: create a local comment at the finding's anchor with the
+  // agent-attributed body. Outward posting still rides the guarded Mirror /
+  // Submit-review flows (§9) — this only drafts the comment locally.
+  const handleAdoptFinding = useCallback(
+    (finding: ReviewFinding) => {
+      void onAddComment(
+        finding.path,
+        finding.range[0],
+        finding.range[1],
+        findingCommentBody(finding),
+        finding.side,
+      );
+    },
+    [onAddComment],
+  );
+
   // -- Relocated PR-info: external reference links --
   const prHref = useMemo(() => prUrl(review.pr), [review.pr]);
   const issueHref = useMemo(() => issueUrl(review.issue), [review.issue]);
@@ -2348,6 +2374,8 @@ export function DiffView({
             });
           }}
           onJumpTo={handleJumpTo}
+          onAdopt={canAddComments ? handleAdoptFinding : undefined}
+          adoptedIds={adoptedFindings}
         />
 
         {/* ----------------------------------------------------------------- */}
diff --git a/app/src/components/FindingsPanel.test.tsx b/app/src/components/FindingsPanel.test.tsx
index bcfe837..d7b3750 100644
--- a/app/src/components/FindingsPanel.test.tsx
+++ b/app/src/components/FindingsPanel.test.tsx
@@ -290,3 +290,53 @@ describe("FindingsPanel", () => {
     ).toBeInTheDocument();
   });
 });
+
+describe("FindingsPanel — adopt as review comment", () => {
+  it("calls onAdopt with the finding and shows Added once adopted", () => {
+    const finding = makeFinding({ id: "a", title: "Missing tenant scope" });
+    const onAdopt = vi.fn();
+    const { rerender } = render(
+      <FindingsPanel
+        findings={[finding]}
+        dismissed={new Set()}
+        open={true}
+        onToggle={noop}
+        onDismiss={noop}
+        onJumpTo={noop}
+        onAdopt={onAdopt}
+        adoptedIds={new Set()}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Add to review" }));
+    expect(onAdopt).toHaveBeenCalledWith(finding);
+
+    rerender(
+      <FindingsPanel
+        findings={[finding]}
+        dismissed={new Set()}
+        open={true}
+        onToggle={noop}
+        onDismiss={noop}
+        onJumpTo={noop}
+        onAdopt={onAdopt}
+        adoptedIds={new Set(["a"])}
+      />,
+    );
+    expect(screen.queryByRole("button", { name: "Add to review" })).toBeNull();
+    expect(screen.getByText("Added ✓")).toBeDefined();
+  });
+
+  it("hides the affordance entirely when onAdopt is absent", () => {
+    render(
+      <FindingsPanel
+        findings={[makeFinding({ id: "a" })]}
+        dismissed={new Set()}
+        open={true}
+        onToggle={noop}
+        onDismiss={noop}
+        onJumpTo={noop}
+      />,
+    );
+    expect(screen.queryByRole("button", { name: "Add to review" })).toBeNull();
+  });
+});
diff --git a/app/src/components/FindingsPanel.tsx b/app/src/components/FindingsPanel.tsx
index 0f0edd2..ca34ee5 100644
--- a/app/src/components/FindingsPanel.tsx
+++ b/app/src/components/FindingsPanel.tsx
@@ -41,6 +41,14 @@ interface FindingsPanelProps {
   readonly onDismiss: (id: string) => void;
   /** Scroll the diff to a finding's line, side-aware. */
   readonly onJumpTo: (path: string, side: DiffSide, line: number) => void;
+  /**
+   * Adopt a finding as a review comment (explicit click; the comment reaches
+   * GitHub only through the guarded Mirror / Submit-review flows). Omit when
+   * commenting is unavailable (gate not InReview) to hide the affordance.
+   */
+  readonly onAdopt?: ((finding: ReviewFinding) => void) | undefined;
+  /** Ids of findings that already have an adopted comment. */
+  readonly adoptedIds?: ReadonlySet<string> | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -192,10 +200,16 @@ function FindingRow({
   finding,
   onDismiss,
   onJumpTo,
+  onAdopt,
+  adopted,
 }: {
   readonly finding: ReviewFinding;
   readonly onDismiss: (id: string) => void;
   readonly onJumpTo: (path: string, side: DiffSide, line: number) => void;
+  /** Adopt this finding as a review comment; absent when commenting is off. */
+  readonly onAdopt?: ((finding: ReviewFinding) => void) | undefined;
+  /** Whether a comment for this finding already exists. */
+  readonly adopted: boolean;
 }) {
   const [expanded, setExpanded] = useState(false);
   const meta = severityMeta(finding.severity);
@@ -236,6 +250,27 @@ function FindingRow({
         >
           {locationLabel(finding)}
         </span>
+        {onAdopt !== undefined &&
+          hasLine &&
+          (adopted ? (
+            <span
+              className="shrink-0 rounded border border-border/60 px-1.5 py-0.5 text-[10px] text-muted-foreground/70"
+              title="A review comment for this finding already exists"
+            >
+              Added ✓
+            </span>
+          ) : (
+            <button
+              type="button"
+              onClick={() => {
+                onAdopt(finding);
+              }}
+              className="shrink-0 cursor-pointer rounded border border-border bg-transparent px-1.5 py-0.5 text-[10px] text-muted-foreground hover:border-primary/50 hover:text-foreground"
+              title="Add this finding as a review comment (posts to GitHub only via Mirror / Submit review)"
+            >
+              Add to review
+            </button>
+          ))}
         {hasLine ? (
           <button
             type="button"
@@ -307,6 +342,8 @@ export function FindingsPanel({
   onToggle,
   onDismiss,
   onJumpTo,
+  onAdopt,
+  adoptedIds,
 }: FindingsPanelProps) {
   const visible = useMemo(
     () =>
@@ -372,6 +409,8 @@ export function FindingsPanel({
               finding={finding}
               onDismiss={onDismiss}
               onJumpTo={onJumpTo}
+              onAdopt={onAdopt}
+              adopted={adoptedIds?.has(finding.id) ?? false}
             />
           ))}
         </ul>
diff --git a/app/src/lib/finding-comment.test.ts b/app/src/lib/finding-comment.test.ts
new file mode 100644
index 0000000..7e49210
--- /dev/null
+++ b/app/src/lib/finding-comment.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import {
+  findingCommentBody,
+  isFindingAdopted,
+  adoptedFindingIds,
+} from "./finding-comment";
+import type { ReviewFinding } from "../bindings/ReviewFinding";
+import type { Comment } from "../bindings/Comment";
+
+const finding = {
+  id: "f0-abcd1234",
+  severity: "Warning",
+  path: "platform/src/app/api/shares.py",
+  range: [28, 28],
+  side: "New",
+  title: "New route missing the trailing slash",
+  rationale: "FastAPI 307-redirects and some clients drop the body.",
+  area: "backend",
+} satisfies ReviewFinding;
+
+function commentAt(
+  path: string,
+  range: [number, number],
+  side: "Old" | "New",
+  body: string,
+): Comment {
+  return {
+    id: "c-1",
+    anchor: { DiffLine: { path, range, side } },
+    body,
+    origin: "Local",
+  };
+}
+
+describe("findingCommentBody", () => {
+  it("carries severity, title, rationale, and provenance", () => {
+    const body = findingCommentBody(finding);
+    expect(body).toContain("**Agent pre-review · WARNING**");
+    expect(body).toContain(finding.title);
+    expect(body).toContain(finding.rationale);
+    expect(body).toContain("adopted by the reviewer");
+  });
+});
+
+describe("isFindingAdopted", () => {
+  it("matches a local comment at the same anchor carrying the title", () => {
+    const comment = commentAt(
+      finding.path,
+      [28, 28],
+      "New",
+      findingCommentBody(finding),
+    );
+    expect(isFindingAdopted(finding, [comment])).toBe(true);
+  });
+
+  it("does not match a different line, side, or body", () => {
+    const wrongLine = commentAt(
+      finding.path,
+      [29, 29],
+      "New",
+      findingCommentBody(finding),
+    );
+    const wrongSide = commentAt(
+      finding.path,
+      [28, 28],
+      "Old",
+      findingCommentBody(finding),
+    );
+    const unrelated = commentAt(finding.path, [28, 28], "New", "just a note");
+    expect(isFindingAdopted(finding, [wrongLine])).toBe(false);
+    expect(isFindingAdopted(finding, [wrongSide])).toBe(false);
+    expect(isFindingAdopted(finding, [unrelated])).toBe(false);
+  });
+
+  it("ignores plan-anchored comments", () => {
+    const plan: Comment = {
+      id: "c-2",
+      anchor: { PlanStep: 1 },
+      body: findingCommentBody(finding),
+      origin: "Local",
+    };
+    expect(isFindingAdopted(finding, [plan])).toBe(false);
+  });
+});
+
+describe("adoptedFindingIds", () => {
+  it("collects only the adopted ids", () => {
+    const other = { ...finding, id: "f1-ffff0000", range: [40, 41] as [number, number] };
+    const comment = commentAt(
+      finding.path,
+      [28, 28],
+      "New",
+      findingCommentBody(finding),
+    );
+    const ids = adoptedFindingIds([finding, other], [comment]);
+    expect(ids.has("f0-abcd1234")).toBe(true);
+    expect(ids.has("f1-ffff0000")).toBe(false);
+  });
+});
diff --git a/app/src/lib/finding-comment.ts b/app/src/lib/finding-comment.ts
new file mode 100644
index 0000000..ea0cfb0
--- /dev/null
+++ b/app/src/lib/finding-comment.ts
@@ -0,0 +1,58 @@
+import type { ReviewFinding } from "../bindings/ReviewFinding";
+import type { Comment } from "../bindings/Comment";
+
+/**
+ * Turning an agent finding into a review comment ("adopting" it).
+ *
+ * A finding is advisory and local; a comment is the unit cockpit actually
+ * sends outward (dispatched to the rework agent on authored PRs, or posted to
+ * GitHub through the guarded mirror / submit-review flows on review requests).
+ * Adoption is always an explicit reviewer click, and the outward post still
+ * rides the existing explicit confirmation — so agent output never reaches a
+ * human's PR without two deliberate human actions (Invariant §9).
+ */
+
+/**
+ * The comment body for an adopted finding: GitHub-renderable markdown with the
+ * severity and title up front, the agent's rationale as the body, and an
+ * honest provenance footer.
+ */
+export function findingCommentBody(finding: ReviewFinding): string {
+  const severity = finding.severity.toUpperCase();
+  return `**Agent pre-review · ${severity}** — ${finding.title}\n\n${finding.rationale}\n\n_Advisory finding from the reviewer's pre-review agent, adopted by the reviewer._`;
+}
+
+/**
+ * Whether a finding has already been adopted: a local comment exists on the
+ * same diff line range/side whose body carries the finding's title. Keeps the
+ * adopt button idempotent without persisting a findings↔comments link (comments
+ * stay ephemeral per Invariant §0.4).
+ */
+export function isFindingAdopted(
+  finding: ReviewFinding,
+  comments: readonly Comment[],
+): boolean {
+  return comments.some((comment) => {
+    if (!("DiffLine" in comment.anchor)) return false;
+    const anchor = comment.anchor.DiffLine;
+    return (
+      anchor.path === finding.path &&
+      anchor.range[0] === finding.range[0] &&
+      anchor.range[1] === finding.range[1] &&
+      anchor.side === finding.side &&
+      comment.body.includes(finding.title)
+    );
+  });
+}
+
+/** The ids of every finding already adopted into a comment. */
+export function adoptedFindingIds(
+  findings: readonly ReviewFinding[],
+  comments: readonly Comment[],
+): ReadonlySet<string> {
+  const ids = new Set<string>();
+  for (const finding of findings) {
+    if (isFindingAdopted(finding, comments)) ids.add(finding.id);
+  }
+  return ids;
+}