co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/pr/findings_json.js

@@ -0,0 +1,187 @@
+const SEVERITIES = ["P0", "P1", "P2", "P3"];
+/** OpenRouter `response_format` for a review. Providers that ignore it still
+ * get the prompt's instruction to return a fenced JSON block. */
+export const FINDINGS_JSON_SCHEMA = {
+    type: "json_schema",
+    json_schema: {
+        name: "review_findings",
+        strict: false,
+        schema: {
+            type: "object",
+            properties: {
+                findings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            severity: { type: "string", enum: [...SEVERITIES] },
+                            blocking: { type: "boolean" },
+                            path: { type: "string" },
+                            lineFrom: { type: "integer" },
+                            lineTo: { type: "integer" },
+                            symbol: { type: "string" },
+                            title: { type: "string" },
+                            body: { type: "string" },
+                            suggestion: { type: "string" },
+                        },
+                        required: ["severity", "path", "lineFrom", "title", "body"],
+                    },
+                },
+                previousFindings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                            state: { type: "string", enum: ["open", "closed"] },
+                            path: { type: "string" },
+                            lineFrom: { type: "integer" },
+                            lineTo: { type: "integer" },
+                        },
+                        required: ["id", "state"],
+                    },
+                },
+            },
+            required: ["findings"],
+        },
+    },
+};
+/** The prompt's contract, kept next to the schema so the two cannot drift. */
+export const FINDINGS_JSON_INSTRUCTIONS = `Return a single JSON object, and nothing else, with this shape:
+{"findings":[{"severity":"P1","blocking":true,"path":"src/a.ts","lineFrom":42,"lineTo":42,"symbol":"helper()","title":"The helper ignores its argument","body":"One sentence on what is wrong and its impact, then a short evidence paragraph.","suggestion":"the exact replacement lines, or omit this field"}],"previousFindings":[{"id":"F1","state":"open"}]}
+
+Rules for the JSON:
+- "severity" is exactly one of P0, P1, P2, P3. "blocking" is true or false.
+- "lineFrom" and "lineTo" are numbers in the new file, copied from the DIFF
+  column, never counted from the @@ header. "lineTo" may equal "lineFrom".
+- "title" is one sentence naming the defect, without the severity or the path.
+- "body" is the explanation. Do not repeat the title, the path, or the location
+  line inside it; our code renders those. Do not add a closing sentence asking
+  whether to explain more, and do not use the words Mechanism, Symptom,
+  Scenario, Verified, Repro, Options, or Scope as labels.
+- "suggestion" holds only the replacement source lines, with their original
+  indentation, when the fix replaces the exact lines lineFrom-lineTo in one
+  hunk of the same file. Omit it otherwise. Never wrap it in a code fence.
+- When a fix needs removed lines, another file, or more than one hunk, omit
+  "suggestion".
+- Return every independently actionable finding, including none: use
+  {"findings":[]} when the change is clean. Never invent a finding to fill the
+  array.`;
+function asNumber(value) {
+    const number = typeof value === "string" ? Number(value) : value;
+    return typeof number === "number" && Number.isFinite(number)
+        ? Math.trunc(number)
+        : undefined;
+}
+function asText(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+/** Like {@link asText} but keeps the leading indentation. A suggestion is
+ * source lines with their original indentation, so trimming the left edge
+ * changes the code it proposes (CORE-40). Only the outer blank lines go. */
+function asSource(value) {
+    return typeof value === "string"
+        ? value.replace(/^\s*\n/, "").replace(/\s+$/, "")
+        : "";
+}
+/** Strips a Markdown fence and any prose around the JSON object. */
+function extractJson(text) {
+    const cleaned = text
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "")
+        .trim();
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch {
+        const start = cleaned.indexOf("{");
+        const end = cleaned.lastIndexOf("}");
+        if (start < 0 || end <= start)
+            return undefined;
+        try {
+            return JSON.parse(cleaned.slice(start, end + 1));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** One JSON finding as Markdown, in the exact shape `parseFindings` reads.
+ * Rendering it here is the point: the model never writes this text itself. */
+function findingMarkdown(raw) {
+    const path = asText(raw.path);
+    const title = asText(raw.title);
+    const lineFrom = asNumber(raw.lineFrom);
+    if (!path || !title || lineFrom === undefined || lineFrom <= 0) {
+        return undefined;
+    }
+    const severity = asText(raw.severity).toUpperCase();
+    const level = SEVERITIES.includes(severity)
+        ? severity
+        : "P2";
+    const impact = raw.blocking === true ? "blocking" : "non-blocking";
+    const symbol = asText(raw.symbol);
+    const lineTo = asNumber(raw.lineTo) ?? lineFrom;
+    const span = lineTo === lineFrom ? `${lineFrom}` : `${lineFrom}-${lineTo}`;
+    const suggestion = asSource(raw.suggestion);
+    const lines = [
+        `### [${level} · ${impact}] \`${path}\`${symbol ? `: \`${symbol}\`` : ""}`,
+        `Location: \`${path}:${span}\``,
+        "",
+        asText(raw.body),
+    ];
+    if (suggestion) {
+        lines.push("", `Suggestion: \`${path}:${span}\``, "```suggestion", suggestion, "```");
+    }
+    return lines.join("\n");
+}
+/** Reads the structured output and renders it as Markdown. `undefined` means
+ * the text was not usable JSON, so the caller falls back to the legacy
+ * Markdown parser rather than dropping the review. */
+export function findingsMarkdownFromJson(text) {
+    const parsed = extractJson(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const raw = Array.isArray(parsed.findings) ? parsed.findings : undefined;
+    if (!raw)
+        return undefined;
+    const blocks = raw
+        .map((item) => item && typeof item === "object"
+        ? findingMarkdown(item)
+        : undefined)
+        .filter((block) => block !== undefined);
+    // A JSON object whose findings were all missing a path or a title is a
+    // malformed answer, not a clean review: falling back keeps it visible.
+    if (raw.length > 0 && blocks.length === 0)
+        return undefined;
+    const parts = ["## Findings", ""];
+    parts.push(blocks.length ? blocks.join("\n\n") : "No actionable findings.");
+    const previous = Array.isArray(parsed.previousFindings)
+        ? parsed.previousFindings
+        : [];
+    const verdicts = previous
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return undefined;
+        const value = item;
+        const id = asText(value.id);
+        const state = asText(value.state).toLowerCase();
+        if (!id || (state !== "open" && state !== "closed"))
+            return undefined;
+        if (state === "closed")
+            return `- ${id}: closed`;
+        const path = asText(value.path);
+        const from = asNumber(value.lineFrom);
+        const to = asNumber(value.lineTo) ?? from;
+        if (!path || from === undefined)
+            return `- ${id}: open`;
+        return `- ${id}: open ${path}:${from}${to !== from ? `-${to}` : ""}`;
+    })
+        .filter((line) => line !== undefined);
+    if (verdicts.length) {
+        parts.push("", "## Previous findings", "", verdicts.join("\n"));
+    }
+    return parts.join("\n");
+}

package/dist/src/pr/review_copy.d.ts

@@ -0,0 +1,20 @@
+/** The severity legend and the review-copy rule (CORE-83 / D11).
+ *
+ * Product text avoids the em dash and the semicolon: the docs linter rejects
+ * them, and the finding parser had to accept both a `—` and a `:` heading
+ * separator only because the prompt itself modelled the em dash. The colon is
+ * the one separator now. The legacy parser still reads an em dash heading so
+ * comments posted before 0.5.0 stay readable. */
+/** `[P2] path: symbol` headings and `Summary: 3 new, 1 open, ...` lines are
+ * built from this legend, so the four levels read the same everywhere. */
+export declare const SEVERITY_LEGEND: ReadonlyArray<{
+    level: string;
+    name: string;
+    description: string;
+}>;
+/** The `## Severity` block the review text starts with. The colon keeps it
+ * free of the em dash the old prompt used. */
+export declare function severitySection(): string;
+/** What the model is told about prose (CORE-83). The review body is rendered
+ * by our code, not the model, so this only has to keep the fields clean. */
+export declare const REVIEW_COPY_RULE = "Write prose without the em dash or the semicolon. Use a colon or a comma instead.";

package/dist/src/pr/review_copy.js

@@ -0,0 +1,40 @@
+/** The severity legend and the review-copy rule (CORE-83 / D11).
+ *
+ * Product text avoids the em dash and the semicolon: the docs linter rejects
+ * them, and the finding parser had to accept both a `—` and a `:` heading
+ * separator only because the prompt itself modelled the em dash. The colon is
+ * the one separator now. The legacy parser still reads an em dash heading so
+ * comments posted before 0.5.0 stay readable. */
+/** `[P2] path: symbol` headings and `Summary: 3 new, 1 open, ...` lines are
+ * built from this legend, so the four levels read the same everywhere. */
+export const SEVERITY_LEGEND = [
+    {
+        level: "P0",
+        name: "Critical",
+        description: "production outage, data loss, or security issue",
+    },
+    {
+        level: "P1",
+        name: "High",
+        description: "major behavior is broken and should be fixed before merge",
+    },
+    {
+        level: "P2",
+        name: "Medium",
+        description: "important correctness or maintainability issue",
+    },
+    {
+        level: "P3",
+        name: "Low",
+        description: "minor, non-blocking improvement or edge case",
+    },
+];
+/** The `## Severity` block the review text starts with. The colon keeps it
+ * free of the em dash the old prompt used. */
+export function severitySection() {
+    const items = SEVERITY_LEGEND.map((row) => `- ${row.level}: ${row.name}: ${row.description}.`);
+    return `## Severity\n\n${items.join("\n")}\n`;
+}
+/** What the model is told about prose (CORE-83). The review body is rendered
+ * by our code, not the model, so this only has to keep the fields clean. */
+export const REVIEW_COPY_RULE = "Write prose without the em dash or the semicolon. Use a colon or a comma instead.";

package/dist/src/pr/reviewer.d.ts

@@ -16,7 +16,7 @@ export declare const NO_DIAGRAM_RULES = "Do not use Mermaid or any other diagram
 export declare function reviewSystemPrompt(diagrams: boolean): string;
 /** Shared PR and local/remote workspace review instructions: confirm claims
  * against the indexed graph, not only the diff slice. */
-export declare const CODEGRAPH_DIFF_VERIFICATION = "Examine the changes line by line, not just file by file \u2014 a single file can\ncontain more than one independent defect, and a change that looks fine in\nisolation can be wrong once you trace what calls it or what else it affects.\nWhen a finding depends on behavior outside the changed lines, confirm it with\ncodegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and\ncodegraph-affected before reporting it. Drop or correct findings that only seem\nplausible from the diff but contradict unchanged callers, callees, or the same\npattern elsewhere in the repo. Use those tools to check blast radius and whether\na test reaches the path \u2014 do not guess coverage or impact from the diff alone\nwhen a tool can answer. A missing regression test is not a substitute for\nidentifying the concrete input or code path that misbehaves when you can.";
+export declare const CODEGRAPH_DIFF_VERIFICATION = "Examine the changes line by line, not just file by file. A single file can\ncontain more than one independent defect, and a change that looks fine in\nisolation can be wrong once you trace what calls it or what else it affects.\nWhen a finding depends on behavior outside the changed lines, confirm it with\ncodegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and\ncodegraph-affected before reporting it. Drop or correct findings that only seem\nplausible from the diff but contradict unchanged callers, callees, or the same\npattern elsewhere in the repo. Use those tools to check blast radius and whether\na test reaches the path. Do not guess coverage or impact from the diff alone\nwhen a tool can answer. A missing regression test is not a substitute for\nidentifying the concrete input or code path that misbehaves when you can.";
 /** GitHub omits `patch` entirely for files it considers too large, and the file
  * still appears in the compare response with only its counts. Rendering that as
  * an empty body reads as "this file did not change", and a reviewer then
@@ -31,6 +31,7 @@ export type { Snapshot };
 export declare function reviewPullRequest(client: GitHubClient, options: Options, usage?: UsageSink, snapshot?: Snapshot, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<AiResponse & {
     visiblePaths: string[];
     guideBuiltAt: string | null;
+    codegraphState: "used" | "disabled" | "unavailable";
 }>;
 /** Local workspace review — same prompt loop as PR review without GitHub. */
 export declare function reviewWorkspaceRevision(revision: Revision, options: Options, headSha: string, usage?: UsageSink, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<AiResponse & {

package/dist/src/pr/reviewer.js

@@ -3,8 +3,10 @@ import { completeWithMermaidTools, } from "../ai/mermaid_loop.js";
 import { loadGuides } from "../review/guides.js";
 import { computeScope } from "./scope.js";
 import { prepareCodegraphTools } from "./codegraph_tools.js";
+import { REVIEW_COPY_RULE, severitySection } from "./review_copy.js";
 import { needsSummary, READ_FULL_DIFF_TOOL, readFullDiff, summarizeDiff, } from "./diff_summary.js";
 import { numberPatch } from "./hunks.js";
+import { FINDINGS_JSON_INSTRUCTIONS, FINDINGS_JSON_SCHEMA, findingsMarkdownFromJson, } from "./findings_json.js";
 const MAX_REVIEW_DIFF_CHARS = 240_000;
 export const MERMAID_GUIDANCE = `Mermaid selection and minimal syntax:
 flowchart = decisions, branches, pipelines, and fallback paths;
@@ -30,7 +32,7 @@ concise by default.`;
 const REVIEW_DIAGRAM_RULES = `People generally find it easier to understand the
 problem you've identified when it's presented in diagrams. When a multi-step
 flow, lifecycle, dependency, data model, protocol, or architecture change is
-part of the finding, you are expected to draw it — do not skip the diagram
+part of the finding, you are expected to draw it. Do not skip the diagram
 just to avoid the extra tool call. During the initial review, use at most one
 diagram, so spend it on the finding that benefits most. If a user later asks
 for detailed reasoning in a reply, that reply may use up to five diagrams, but
@@ -46,20 +48,20 @@ const DIAGRAM_PROMPT_RULES = `People generally find it easier to understand the
 problem you've identified when it's presented in diagrams. When a finding
 involves a multi-step flow, lifecycle, dependency, data model, protocol, or
 architecture change, you are expected to include a Mermaid fenced code block
-for it — reading the syntax with read-mermaid-syntaxes first is a small cost,
+for it. Reading the syntax with read-mermaid-syntaxes first is a small cost,
 not a reason to skip the diagram. This review may contain at most one diagram
 in total, so if more than one finding qualifies, pick the one the diagram
 clarifies most. Its type must be one of the types named in the system
 instructions. Keep labels short and grounded in the supplied evidence. A
 one-line fix or an obvious, single-step cause and effect genuinely needs no
-diagram — that is the only reason to omit one. Close every fenced block.`;
+diagram. That is the only reason to omit one. Close every fenced block.`;
 export function reviewSystemPrompt(diagrams) {
     return `${REVIEW_ROLE}
 ${diagrams ? REVIEW_DIAGRAM_RULES : NO_DIAGRAM_RULES}`;
 }
 /** Shared PR and local/remote workspace review instructions: confirm claims
  * against the indexed graph, not only the diff slice. */
-export const CODEGRAPH_DIFF_VERIFICATION = `Examine the changes line by line, not just file by file — a single file can
+export const CODEGRAPH_DIFF_VERIFICATION = `Examine the changes line by line, not just file by file. A single file can
 contain more than one independent defect, and a change that looks fine in
 isolation can be wrong once you trace what calls it or what else it affects.
 When a finding depends on behavior outside the changed lines, confirm it with
@@ -67,7 +69,7 @@ codegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and
 codegraph-affected before reporting it. Drop or correct findings that only seem
 plausible from the diff but contradict unchanged callers, callees, or the same
 pattern elsewhere in the repo. Use those tools to check blast radius and whether
-a test reaches the path — do not guess coverage or impact from the diff alone
+a test reaches the path. Do not guess coverage or impact from the diff alone
 when a tool can answer. A missing regression test is not a substitute for
 identifying the concrete input or code path that misbehaves when you can.`;
 function text(value, limit = 20_000) {
@@ -76,6 +78,33 @@ function text(value, limit = 20_000) {
         ? `${result.slice(0, limit)}\n[truncated]`
         : result;
 }
+/** Turns a model reply into the Markdown every consumer already parses
+ * (CORE-40 / F02). A reply that is not usable JSON is retried once with an
+ * explicit reminder; if that also fails, the raw text is returned so the
+ * legacy Markdown parser can still read it. This keeps a provider that ignores
+ * `response_format` working, and never drops a review on the floor. */
+async function normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options) {
+    const direct = findingsMarkdownFromJson(response.text);
+    if (direct !== undefined)
+        return direct;
+    report("AI response was not valid JSON, asking once more");
+    const retry = await completeWithMermaidTools(provider, {
+        ...request,
+        job: "review_pull_request_retry",
+        prompt: `${request.prompt}\n\nThe previous answer was not valid JSON. Return only the JSON object described above, with no prose and no code fence.`,
+    }, 1, extraTools, maxToolRounds);
+    if (usage)
+        await usage(retry);
+    if (options.debug) {
+        console.log(`[debug] JSON retry response · input=${retry.tokensIn} tokens · output=${retry.tokensOut} tokens`);
+        console.log(`\n----- JSON RETRY -----\n${retry.text}\n`);
+    }
+    const afterRetry = findingsMarkdownFromJson(retry.text);
+    if (afterRetry !== undefined)
+        return afterRetry;
+    report("AI response was still not JSON, falling back to Markdown parsing");
+    return response.text.trim();
+}
 const MAX_FILE_PATCH_CHARS = 12_000;
 /** GitHub omits `patch` entirely for files it considers too large, and the file
  * still appears in the compare response with only its counts. Rendering that as
@@ -93,12 +122,12 @@ export function filePatch(file) {
         const counts = Number.isFinite(changes) && changes > 0
             ? `${changes} changed lines (+${additions} -${deletions})`
             : "an unreported number of changed lines";
-        return (`[${status}; ${counts}; diff withheld by GitHub, not shown here. ` +
+        return (`[${status}: ${counts}, diff withheld by GitHub, not shown here. ` +
             `Do not treat this file as unchanged and do not report its contents.]`);
     }
     if (patch.length > MAX_FILE_PATCH_CHARS) {
-        return (`${numberPatch(patch.slice(0, MAX_FILE_PATCH_CHARS))}\n[${status}; ${changes} ` +
-            `changed lines total; this file's diff is cut off here, later hunks are ` +
+        return (`${numberPatch(patch.slice(0, MAX_FILE_PATCH_CHARS))}\n[${status}: ${changes} ` +
+            `changed lines total. This file's diff is cut off here, later hunks are ` +
             `not shown.]`);
     }
     return numberPatch(patch);
@@ -153,7 +182,7 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
         : await client.pages(`repos/${options.repo}/pulls/${number}/files`);
     report(`diff files loaded · ${files.length} files`);
     if (!guide) {
-        throw new Error(`repos/${options.repo}/PR_REVIEW_GUIDE.md was not found; run init first`);
+        throw new Error(`repos/${options.repo}/PR_REVIEW_GUIDE.md was not found. Run init first`);
     }
     if (options.debug) {
         console.log(`[debug] guides · short=${guide.length} chars · detailed=${detailed.length} chars · codebase=${codebase.length} chars`);
@@ -208,7 +237,7 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
             patchByPath.set(path, patch);
             const description = await summarizeDiff(path, patch, lowProvider, usage);
             report(`summarized large diff · ${path} · ${changes} changed lines`);
-            return (`FILE: ${path}\n[${changes} changed lines — summarized below; ` +
+            return (`FILE: ${path}\n[${changes} changed lines, summarized below. ` +
                 `call read-full-diff("${path}") for the complete diff if this is not ` +
                 `enough]\n${description}`);
         })),
@@ -242,7 +271,7 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
     const diffWasTruncated = ownPatch.length > MAX_REVIEW_DIFF_CHARS;
     const ownDiff = text(ownPatch, MAX_REVIEW_DIFF_CHARS);
     const unchangedListing = extras?.unchangedPaths?.length
-        ? `\nUNCHANGED SINCE LAST REVIEW (paths only — do not re-report findings here):\n${extras.unchangedPaths
+        ? `\nUNCHANGED SINCE LAST REVIEW (paths only, do not re-report findings here):\n${extras.unchangedPaths
             .map((path) => `- ${path}`)
             .join("\n")}`
         : "";
@@ -253,8 +282,8 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
         ? `${ownDiff}${unchangedListing}`
         : `${ownDiff}
 
-UPSTREAM CONTEXT — arrived via a merge this round, not authored by this pull
-request. Do not raise a finding located only in this code; only note an
+UPSTREAM CONTEXT: arrived via a merge this round, not authored by this pull
+request. Do not raise a finding located only in this code. Only note an
 interaction if the pull request's own change above relies on or conflicts with
 one of these files, and never mark that finding blocking:
 ${upstreamListing}${unchangedListing}`;
@@ -265,66 +294,35 @@ ${upstreamListing}${unchangedListing}`;
     const carryBlock = extras?.carryPrompt ? `${extras.carryPrompt}\n` : "";
     const prompt = `Review this pull request against the repository's review guide and
 codebase conventions. Find only actionable code-level violations supported by
-the diff and either the guide or the codebase conventions — a pull request
+the diff and either the guide or the codebase conventions. A pull request
 that departs from how this repository's own code is actually written is a
 valid finding even when the review guide has no matching rule.
 Do not repeat existing review comments unless the diff still contains the issue.
 Do not invent requirements. Ignore bot noise and historical PR identities.
-Reason thoroughly, then return concise Markdown only with either:
-"## Findings" followed by findings, or "## Findings\\n\\nNo actionable findings."
-There is no fixed number of findings. Return every independently actionable
-finding supported by the diff and guide, including zero findings when appropriate.
-Do not stop early; inspect all supplied diff text first and return the natural
-count. If the diff contains a truncation marker, limit claims to the supplied
-text and do not imply that omitted files were reviewed.
+Reason thoroughly, then answer with the JSON object described below and nothing
+else. There is no fixed number of findings. Return every independently
+actionable finding supported by the diff and guide, including zero findings
+when appropriate. Do not stop early; inspect all supplied diff text first and
+return the natural count. If the diff contains a truncation marker, limit
+claims to the supplied text and do not imply that omitted files were reviewed.
 Do not invent low-value findings.
 When the DIFF section below has an UPSTREAM CONTEXT part, that code arrived
 through a merge and was not authored by this pull request; do not raise a
 finding located only there, and never mark blocking a finding whose only
 support is upstream context.
 ${CODEGRAPH_DIFF_VERIFICATION}
-Each finding must use this exact structure, keeping the default finding under
-120 words excluding an optional diagram and an optional suggestion:
-
-### [P1 · blocking] \`path/to/file.ts\` — \`symbol()\`
-Location: \`path/to/file.ts:42\`
-
-One sentence describing what is wrong and its impact.
-
-Add one short evidence paragraph explaining the mechanism or reproduction.
-Do not add labels such as Mechanism, Symptom, Scenario, Verified, Repro,
-Options, or Scope unless that detail is necessary to understand a complex
-finding. End every finding with this exact sentence on its own line:
-"If you'd like me to explain it in more detail, please ask." No finding may
-omit it and nothing may follow it.
-
-Use P0-P3 severity and exactly either "blocking" or "non-blocking".
-Keep the Location line machine-readable; it is removed from user-facing
-review copies. Use Markdown backticks around paths and symbols.
+Keep the default finding's "body" under 120 words excluding an optional
+suggestion. Write prose only: do not emit Markdown headings, a Location line,
+backticks around the path, or the sentence "If you'd like me to explain it in
+more detail, please ask." Our code renders the heading, the location, and the
+suggestion from your JSON fields. Use P0-P3 severity, and true for blocking.
+${REVIEW_COPY_RULE}
 Every diff line in the DIFF section starts with its line number in the new
-file. Copy Location numbers from that column instead of counting from the @@
-header, and use \`path:from-to\` when the finding spans several lines. Removed
-lines have no number, so anchor a finding about removed code to the nearest
-numbered line.
-
-Include one GitHub suggestion when the fix is a direct replacement of
-consecutive numbered lines from a single hunk of the same file and you are
-confident in the exact replacement text — this is the common case for
-single-line and small multi-line fixes. Keep Location as the full span of
-the problem, and put the suggestion right before the closing sentence:
-
-Suggestion: \`path/to/file.ts:42-43\`
-\`\`\`suggestion
-every line of 42-43 as it should read, with its original indentation
-\`\`\`
-
-The Suggestion range must sit inside the Location range and cover only the
-lines the fix changes. The block replaces that whole range, so write every
-line of it, not just the edited part, and write nothing else inside the block.
-When the replacement itself contains three backticks, open and close the block
-with four. Leave the suggestion out when the fix needs removed lines, another
-file, or more than one hunk, or when you are not sure of the exact code.
+file. Copy "lineFrom" and "lineTo" from that column instead of counting from
+the @@ header. Removed lines have no number, so anchor a finding about removed
+code to the nearest numbered line.
 ${diagrams ? DIAGRAM_PROMPT_RULES : NO_DIAGRAM_RULES}
+${FINDINGS_JSON_INSTRUCTIONS}
 
 REVIEW GUIDE:
 ${guide}
@@ -355,6 +353,7 @@ ${diff}`;
         prompt,
         maxTokens: 24_000 * matrix,
         reasoningEffort: "high",
+        responseFormat: FINDINGS_JSON_SCHEMA,
     };
     report(`AI request · model=${options.highModel ?? "openrouter default"} · ` +
         `prompt=${prompt.length} chars · maxTokens=${request.maxTokens}`);
@@ -371,9 +370,12 @@ ${diff}`;
         console.log(`\n----- INITIAL REVIEW -----\n${response.text}\n`);
     }
     if (!response.text.trim()) {
-        throw new Error("OpenRouter returned an empty review; the reasoning budget may have been exhausted");
+        throw new Error("OpenRouter returned an empty review. The reasoning budget may have been exhausted");
     }
-    let reviewText = response.text.trim();
+    // The model returns JSON; we render the Markdown (CORE-40 / F02). A reply
+    // that is not usable JSON is retried once and then falls back to the legacy
+    // Markdown parser, so a provider that ignores the schema still works.
+    let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options);
     for (let pass = 2; pass <= matrix; pass++) {
         const improvementRequest = {
             ...request,
@@ -381,13 +383,13 @@ ${diff}`;
             prompt: `Audit the draft review below against the complete pull-request diff
 and the supplied review guides. Preserve valid findings, correct inaccurate ones,
 remove duplicate or unsupported ones, and add every missing actionable finding.
-Do not stop early and do not invent requirements. Keep the existing finding
-structure unchanged. Return only the complete revised review in the same format.
+Do not stop early and do not invent requirements. Return the complete revised
+review as the same JSON object the instructions above describe, and nothing else.
 
 ORIGINAL REVIEW CONTEXT:
 ${prompt}
 
-DRAFT REVIEW:
+DRAFT REVIEW (Markdown rendering of the previous JSON answer):
 ${reviewText}`,
         };
         if (options.debug) {
@@ -402,7 +404,7 @@ ${reviewText}`,
         if (!response.text.trim()) {
             throw new Error(`OpenRouter returned an empty review improvement at pass ${pass - 1}`);
         }
-        reviewText = response.text.trim();
+        reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options);
         if (options.debug) {
             console.log(`[debug] improvement ${pass - 1} response · input=${response.tokensIn} tokens · output=${response.tokensOut} tokens`);
             console.log(`\n----- IMPROVED REVIEW ${pass - 1} -----\n${reviewText}\n`);
@@ -411,16 +413,14 @@ ${reviewText}`,
     const visiblePaths = ownFiles.map(({ path }) => path);
     return {
         ...response,
-        text: `## Severity
-
-- P0 — Critical: production outage, data loss, or security issue.
-- P1 — High: major behavior is broken and should be fixed before merge.
-- P2 — Medium: important correctness or maintainability issue.
-- P3 — Low: minor, non-blocking improvement or edge case.
-
-${reviewText}`,
+        text: `${severitySection()}\n${reviewText}`,
         visiblePaths,
         guideBuiltAt: guides.guideBuiltAt,
+        codegraphState: !options.useCodegraph
+            ? "disabled"
+            : codegraphTools.length > 0
+                ? "used"
+                : "unavailable",
     };
 }
 function revisionToGithubFiles(revision) {
@@ -441,7 +441,7 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
     const { shortGuide, detailed, codebase, skill } = guides;
     const guide = shortGuide || skill;
     if (!guide) {
-        throw new Error(`repos/${options.repo}/PR_REVIEW_GUIDE.md was not found; run init first`);
+        throw new Error(`repos/${options.repo}/PR_REVIEW_GUIDE.md was not found. Run init first`);
     }
     const files = revisionToGithubFiles(revision);
     const unchanged = new Set(extras?.unchangedPaths ?? []);
@@ -463,7 +463,7 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
             return `FILE: ${path}\n${filePatch(file)}`;
         patchByPath.set(path, patch);
         const description = await summarizeDiff(path, patch, lowProvider, usage);
-        return `FILE: ${path}\n[${changes} changed lines — summarized below]\n${description}`;
+        return `FILE: ${path}\n[${changes} changed lines, summarized below]\n${description}`;
     }));
     const codegraphTools = options.useCodegraph
         ? extras?.prepareCodegraphTools
@@ -497,13 +497,12 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
     const prompt = `Review these local changes against the repository's review guide and
 codebase conventions. Find only actionable code-level violations supported by
 the diff and either the guide or the codebase conventions.
-Return concise Markdown with either "## Findings" and findings, or
-"## Findings\\n\\nNo actionable findings."
 Do not invent low-value findings. If the diff contains a truncation marker or a
 file is summarized, limit claims to the supplied text and use read-full-diff or
 codegraph tools before asserting behavior outside what was shown.
 ${CODEGRAPH_DIFF_VERIFICATION}
 ${diagrams ? DIAGRAM_PROMPT_RULES : NO_DIAGRAM_RULES}
+${FINDINGS_JSON_INSTRUCTIONS}
 
 REVIEW GUIDE:
 ${guide}
@@ -529,6 +528,7 @@ ${ownDiff}${unchangedListing}`;
         prompt,
         maxTokens: 24_000 * matrix,
         reasoningEffort: "high",
+        responseFormat: FINDINGS_JSON_SCHEMA,
     };
     report(`AI request · prompt=${prompt.length} chars`);
     let response = await completeWithMermaidTools(provider, request, 1, extraTools, maxToolRounds);
@@ -537,7 +537,7 @@ ${ownDiff}${unchangedListing}`;
     if (!response.text.trim()) {
         throw new Error("OpenRouter returned an empty review");
     }
-    let reviewText = response.text.trim();
+    let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options);
     for (let pass = 2; pass <= matrix; pass++) {
         const improvementRequest = {
             ...request,
@@ -547,18 +547,18 @@ Preserve valid findings, correct inaccurate ones, remove duplicate or
 unsupported ones, and add every missing actionable finding. Re-check each
 finding with codegraph when it depends on behavior outside the diff; remove
 findings that only looked plausible from the diff slice.
-Return only the complete revised review in the same format.
+Return the complete revised review as the same JSON object, and nothing else.
 
 ORIGINAL REVIEW CONTEXT:
 ${prompt}
 
-DRAFT REVIEW:
+DRAFT REVIEW (Markdown rendering of the previous JSON answer):
 ${reviewText}`,
         };
         response = await completeWithMermaidTools(provider, improvementRequest, 1, extraTools, maxToolRounds);
         if (usage)
             await usage(response);
-        reviewText = response.text.trim();
+        reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options);
     }
     const codegraphState = !options.useCodegraph
         ? "disabled"
@@ -567,14 +567,7 @@ ${reviewText}`,
             : "unavailable";
     return {
         ...response,
-        text: `## Severity
-
-- P0 — Critical: production outage, data loss, or security issue.
-- P1 — High: major behavior is broken and should be fixed before merge.
-- P2 — Medium: important correctness or maintainability issue.
-- P3 — Low: minor, non-blocking improvement or edge case.
-
-${reviewText}`,
+        text: `${severitySection()}\n${reviewText}`,
         visiblePaths: ownFiles.map(({ path }) => path),
         guideBuiltAt: guides.guideBuiltAt,
         codegraphState,