Report each finding in the shape the protocol asks for

The example protocol defines a finding as File, Lines, Issue, Comment. The
report was rendering a markdown heading and prose paragraphs instead, which is
readable but is not the structure someone deciding what to fix can scan.

Findings now carry labelled fields, with the rule code when there is one and
the mechanism that traces the finding to the change. Lines is a single number,
or a range only when the finding genuinely spans more than one. The quoted code
sits below, still byte-checked against the file, rather than inside the
sentence explaining the problem.

The tests passed both before and after that change, which is the more useful
half of this commit: they were asserting on the text of a finding and never on
its shape, so the format could have drifted without anything noticing. They pin
it now, and the mutation back to headings fails two of them.

The other half was missing further upstream. Nothing told the model what a
comment is for. The adversarial prompt now says it: the issue is one sentence
naming the problem, the comment explains what is wrong and what it breaks in
language someone who did not write the code can follow, and no code goes in the
comment because the code that proves the finding is quoted separately. A report
cannot make prose out of a comment full of code, so the instruction belongs
where the comment is written rather than where it is rendered.

Author: Poolchaos

docs/DECISIONS.md

@@ -729,3 +729,16 @@ verified evidence, in writing, here.
   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.
+- 2026-07-31 FIXED (maintainer question): the report renders each finding in
+  the labelled structure the example protocol defines, File, Lines, Issue,
+  Comment, rather than as a markdown heading and prose. It did not before, and
+  the tests passed both before and after the change, which means they were
+  asserting on the text of a finding and never on its shape. They pin the
+  format now. Lines is a single number, or a range only when the finding
+  genuinely spans more than one line.
+- 2026-07-31 FIXED: the adversarial prompt now says what a comment is for.
+  Nothing told the model that the comment must be plain language a
+  non-author can follow, or that code belongs in the quotation rather than in
+  the sentence explaining the problem. A report cannot make prose out of a
+  comment full of code, so the instruction belongs where the comment is
+  written rather than where it is rendered.

src/lib/review/report.ts

@@ -172,23 +172,32 @@ function completeness(input: ReportInput): string {
   );
 }
 
+/**
+ * One finding, in the structure the protocol defines.
+ *
+ * Labelled fields rather than prose, because a finding is read by someone
+ * deciding what to fix: the file, the lines, what is wrong and what it breaks,
+ * each findable without reading a paragraph. The comment is plain language by
+ * contract; the code that proves it sits below, quoted and byte-checked,
+ * rather than inside the sentence explaining it.
+ */
 function renderFinding(finding: ReportFinding): string[] {
-  const rule = finding.ruleCode ? ` (rule ${finding.ruleCode})` : "";
   return [
-    `#### ${finding.filePath}:${lineRange(finding)}${rule}`,
-    "",
-    `**${finding.issue}**`,
-    "",
-    finding.comment,
+    `File: ${finding.filePath}`,
+    `Lines: ${lineRange(finding)}`,
+    ...(finding.ruleCode ? [`Rule: ${finding.ruleCode}`] : []),
+    `Issue: ${finding.issue}`,
+    `Comment: ${finding.comment}`,
+    ...(finding.mechanism ? [`Mechanism: ${finding.mechanism}`] : []),
     "",
-    ...(finding.mechanism ? [`How it fails: ${finding.mechanism}`, ""] : []),
     ...(finding.quotedCode ? ["```", finding.quotedCode, "```", ""] : []),
   ];
 }
 
+/** A single line, or a range when the finding genuinely spans one. */
 function lineRange(finding: ReportFinding): string {
   return finding.lineEnd > finding.lineStart
-    ? `${finding.lineStart}-${finding.lineEnd}`
+    ? `${finding.lineStart} - ${finding.lineEnd}`
     : String(finding.lineStart);
 }
 

src/lib/review/stage-schemas.ts

@@ -41,6 +41,7 @@ const candidateFindingSchema = z.object({
   severity: z.enum(SEVERITIES),
   ruleCode: z.string().nullable(),
   issue: z.string().min(1),
+  /** Plain language, no code: what is wrong and what it breaks. */
   comment: z.string().min(1),
   /** Input, mechanism, wrong output. A finding without one is a guess. */
   mechanism: z.string().min(1),

src/server/review/content.ts

@@ -247,6 +247,12 @@ export function renderAdversarialPrompt(
     "Cite line numbers exactly as shown in the left column above: those are the",
     "line numbers in the file as it stands after the change. A hunk you do not",
     "mention is treated as unreviewed and fails the run.",
+    "",
+    "For each finding: the issue is one sentence naming the problem, and the",
+    "comment explains what is wrong and what it breaks in plain language that",
+    "someone who did not write the code can follow. Put no code in the comment;",
+    "the code that proves the finding is quoted separately and checked against",
+    "the file.",
   ].join("\n");
 }
 

tests/lib/review/report.test.ts

@@ -81,6 +81,43 @@ describe("what the report says was found", () => {
   it("carries the quoted code that was checked against the file", () => {
     expect(renderReport(BASE)).toContain("  repository.save(order);");
   });
+
+  it("uses the labelled structure the protocol defines", () => {
+    // File, lines, issue and comment, each findable without reading a
+    // paragraph, because a finding is read by someone deciding what to fix.
+    const report = renderReport(BASE);
+    expect(report).toContain("File: app/src/orders/save.ts");
+    expect(report).toContain("Lines: 4");
+    expect(report).toContain("Rule: 1");
+    expect(report).toContain("Issue: The await was removed, so the save is not waited for.");
+    expect(report).toContain(
+      "Comment: The caller returns before the write lands, and a failure is unobservable.",
+    );
+  });
+
+  it("gives a range only when the finding spans more than one line", () => {
+    expect(renderReport(BASE)).toContain("Lines: 4");
+    expect(renderReport(BASE)).not.toContain("Lines: 4 - 4");
+    expect(
+      renderReport({ ...BASE, confirmed: [{ ...FINDING, lineStart: 4, lineEnd: 9 }] }),
+    ).toContain("Lines: 4 - 9");
+  });
+
+  it("keeps code out of the comment line and in the quotation", () => {
+    // The comment is what a person reads to decide; the code is the evidence
+    // underneath it, quoted and byte-checked.
+    const report = renderReport(BASE);
+    const commentLine = report.split("\n").find((line) => line.startsWith("Comment: "));
+    expect(commentLine).toBeDefined();
+    expect(commentLine).not.toContain("repository.save");
+    expect(report).toContain("repository.save(order);");
+  });
+
+  it("omits the rule line when a finding carries no rule code", () => {
+    expect(renderReport({ ...BASE, confirmed: [{ ...FINDING, ruleCode: null }] })).not.toContain(
+      "Rule:",
+    );
+  });
 });
 
 describe("what the report says was examined", () => {