co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/knowledge/synthesis.js

@@ -1,5 +1,6 @@
 import { AiBatch } from "../ai/batch.js";
-import { sectionTitles } from "./sections.js";
+import { isPullRequestFact } from "./guide.js";
+import { sectionAllowsPrFacts, sectionTitles } from "./sections.js";
 const allowedSections = new Set([
     "identity",
     "devloop",
@@ -40,7 +41,7 @@ function parseJson(text) {
         return JSON.parse(`${cleaned.slice(start, lastCompleteObject + 1)}]`);
     }
 }
-function factsFromResponse(text, evidence, defaultScope) {
+function factsFromResponse(text, evidence, defaultScope, origin) {
     const parsed = parseJson(text);
     if (!Array.isArray(parsed)) {
         throw new Error("AI fact output must be an array");
@@ -73,6 +74,7 @@ function factsFromResponse(text, evidence, defaultScope) {
                 scope,
                 confidence,
                 status: "active",
+                origin,
             },
         ];
     });
@@ -124,8 +126,31 @@ function pullRequestUnit(pr) {
         diff: promptText(pr.diff, 8_000),
     });
 }
-function queueFor(provider, repo, ai, model, concurrency) {
-    return new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v2:${model}`);
+function queueFor(provider, repo, ai, model, concurrency, validate) {
+    return new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v2:${model}`, validate);
+}
+/** `factsFromResponse` as a validator: `null` when the text parses into facts,
+ * otherwise the parse error's message. Used so an unparseable response is never
+ * cached (CORE-30). */
+function validateFacts(response, evidence, defaultScope) {
+    try {
+        factsFromResponse(response.text, evidence, defaultScope, "repository");
+        return null;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `${evidence}: ${message}`;
+    }
+}
+/** `validSection` as a validator: `null` when the section body is usable,
+ * otherwise a short reason. A section that is empty or malformed is retried
+ * once and then left uncached, so a later `sync` does not replay it. */
+function validateSection(response, key) {
+    const section = cleanSection(response.text, key);
+    if (!validSection(section, key)) {
+        return "synthesis output is not a valid section";
+    }
+    return null;
 }
 function extractRequest(prompt, maxTokens) {
     return {
@@ -151,17 +176,20 @@ function validSection(text, key) {
 }
 function sectionGoal(key) {
     const goals = {
-        layout: "Describe module responsibilities and important dependency or change-impact paths; do not list routine public symbols.",
+        layout: "Describe module responsibilities and important dependency or change-impact paths. Do not list routine public symbols.",
         tests: "State which verification is required after a behavior change and the dependency/setup that makes it meaningful.",
         devloop: "Give local build, debugging, or change-impact guidance that is not already stated in Shipping.",
-        ship: "Give one concise release/CI checklist; merge overlapping workflow, artifact, and release-gate facts.",
+        ship: "Give one concise release/CI checklist. Merge overlapping workflow, artifact, and release-gate facts.",
         style: "Keep only repository-specific, evidenced conventions. Return only the heading when none are actionable.",
     };
     return goals[key] ?? "Keep only actionable repository-specific guidance.";
 }
 function synthesisFacts(facts, key) {
-    return facts
-        .filter((item) => item.sectionKey === key)
+    return (facts
+        // A section that states repository policy never learns from a single pull
+        // request's narrative; only `review-bar` may (CORE-32 / F26b).
+        .filter((item) => item.sectionKey === key &&
+        (sectionAllowsPrFacts(key) || !isPullRequestFact(item)))
         .sort((a, b) => (b.status === "active" ? 1 : 0) - (a.status === "active" ? 1 : 0) ||
         ({
             current: 3,
@@ -176,9 +204,12 @@ function synthesisFacts(facts, key) {
         b.weight - a.weight ||
         b.evidence.length - a.evidence.length ||
         a.claim.localeCompare(b.claim))
-        .slice(0, 20);
+        .slice(0, 20));
 }
 export async function extractAiFacts(provider, repo, source, options, usage) {
+    return (await extractAiFactsWithReport(provider, repo, source, options, usage)).facts;
+}
+export async function extractAiFactsWithReport(provider, repo, source, options, usage) {
     const requests = [];
     const evidence = [];
     const scopes = [];
@@ -220,7 +251,13 @@ ${files}`, 2_200));
             scopes.push("current");
         }
     }
-    const queue = queueFor(provider, repo, options.ai, options.lowModel ?? "", options.aiConcurrent);
+    const queue = queueFor(provider, repo, options.ai, options.lowModel ?? "", options.aiConcurrent, 
+    // Each request carries different evidence, so the validator looks the
+    // request up by identity to find which evidence it belongs to.
+    (request, response) => {
+        const at = requests.indexOf(request);
+        return validateFacts(response, evidence[at] ?? "repository files", scopes[at] ?? "historical-example");
+    });
     const responses = await queue.run(requests, usage);
     const facts = [];
     for (let index = 0; index < responses.length; index++) {
@@ -228,7 +265,9 @@ ${files}`, 2_200));
         if (!response)
             continue;
         try {
-            facts.push(...factsFromResponse(response.text, evidence[index], scopes[index] ?? "historical-example").filter((item) => !hasUnsupportedIdentifier(item.claim, source) &&
+            facts.push(...factsFromResponse(response.text, evidence[index], scopes[index] ?? "historical-example", evidence[index] === "repository files"
+                ? "repository"
+                : "pull-request").filter((item) => !hasUnsupportedIdentifier(item.claim, source) &&
                 !hasUnsupportedPath(item.claim, source) &&
                 (evidence[index] !== "repository files" ||
                     allowsContributionSections(source) ||
@@ -241,7 +280,13 @@ ${files}`, 2_200));
             console.log(`[ai] extract units ${index + 1}/${responses.length}`);
         }
     }
-    return facts;
+    return { facts, skipped: queue.skippedUnits() };
+}
+/** Same as {@link extractAiFacts}, but also reports what the batch skipped so
+ * the caller can put it in the final `[done]` line (CORE-30). */
+export async function enrichFactsWithReport(provider, repo, base, source, options, usage) {
+    const { facts, skipped } = await extractAiFactsWithReport(provider, repo, source, options, usage);
+    return { facts: mergeFacts(base, facts), skipped };
 }
 function mergeFacts(base, extra) {
     const merged = new Map(base.map((item) => [item.id, { ...item, evidence: [...item.evidence] }]));
@@ -268,6 +313,11 @@ export async function synthesizeSections(provider, repo, facts, _previousMarkdow
         if (onlySections && !onlySections.has(key))
             continue;
         const relevant = synthesisFacts(facts, key);
+        // A section whose only facts came from a single pull request has no
+        // repository policy to synthesize, so it is left to the deterministic
+        // renderer instead of asking the model for an empty answer (CORE-32).
+        if (!relevant.length)
+            continue;
         keys.push(key);
         requests.push({
             job: "synth_section",
@@ -304,12 +354,17 @@ FACTS:
 ${JSON.stringify(relevant)}`,
         });
     }
-    const queue = queueFor(provider, repo, ai, model, ai === "hetzner" ? 1 : concurrency);
+    const queue = queueFor(provider, repo, ai, model, ai === "hetzner" ? 1 : concurrency, (request, response) => validateSection(response, keys[requests.indexOf(request)] ?? ""));
     const responses = await queue.run(requests, usage);
+    // A section that the batch skipped has no response, and a unit that failed
+    // validation never produces one: omit those keys entirely rather than
+    // passing an empty string, so `assembleSkill` keeps its own content for them
+    // (an empty string is a *present* override and would blank the section).
     const overrides = {};
     responses.forEach((response, index) => {
         const section = response ? cleanSection(response.text, keys[index]) : "";
-        overrides[keys[index]] = validSection(section, keys[index]) ? section : "";
+        if (validSection(section, keys[index]))
+            overrides[keys[index]] = section;
     });
-    return overrides;
+    return { overrides, skipped: queue.skippedUnits() };
 }

package/dist/src/knowledge/types.d.ts

@@ -39,6 +39,11 @@ export type Fact = {
     scope: "current" | "repeated-history" | "historical-example";
     confidence: "high" | "medium" | "low";
     status: "active" | "contradicted" | "stale";
+    /** Where the fact was mined from. A fact read out of a single pull request
+     * describes that request, not the repository, so it may not become a
+     * repository-wide rule (CORE-32 / F26b). Missing means `repository`, which
+     * keeps facts written before this field existed. */
+    origin?: "repository" | "pull-request";
 };
 export type State = {
     version: 1;

package/dist/src/local/codegraph_prepare.d.ts

@@ -1,5 +1,5 @@
-import type { ToolHandler } from "../ai/mermaid_loop.ts";
 import { type Presence } from "../tools/codegraph.ts";
+import type { ToolHandler } from "../ai/mermaid_loop.ts";
 import { type Run } from "../pr/checkout.ts";
 export type LocalCodegraphState = "used" | "disabled" | "unavailable";
 export type LocalCodegraphPrepare = {
@@ -11,7 +11,8 @@ export declare function prepareLocalCodegraph(input: {
     gitRoot: string;
     enabled: boolean;
     allowInstall: boolean;
-    interactive: boolean;
+    /** Overrides the TTY/CI detection, for tests. */
+    interactive?: boolean;
     run?: Run;
     detect?: () => Promise<Presence>;
 }): Promise<LocalCodegraphPrepare>;

package/dist/src/local/codegraph_prepare.js

@@ -1,5 +1,5 @@
+import { canPrompt, ensureCodegraphForReview, } from "../tools/codegraph.js";
 import { codegraphTools, ensureCodegraphIndex } from "../pr/codegraph_tools.js";
-import { ensureCodegraphForReview } from "../tools/codegraph.js";
 import { createCodegraphRunner, LOCAL_CODEGRAPH_DIR, } from "../tools/codegraph_exec.js";
 import { log, startHeartbeat } from "../util/log.js";
 import { ensureCodegraphGitExclude } from "./codegraph_exclude.js";
@@ -12,7 +12,9 @@ export async function prepareLocalCodegraph(input) {
     await ensureCodegraphGitExclude(input.gitRoot, run);
     const resolved = await ensureCodegraphForReview({
         allowInstall: input.allowInstall,
-        interactive: input.interactive,
+        // The prompt is safe only when a human can answer it; `canPrompt` checks
+        // stdin, stdout and `CI`, so a `</dev/null` or piped run never asks (F01).
+        interactive: input.interactive ?? canPrompt(),
         log: (message) => log("codegraph", message.replace(/^\[codegraph\]\s*/, "")),
     });
     if (!("path" in resolved)) {

package/dist/src/local/git_ops.d.ts

@@ -1,9 +1,10 @@
 import { type Run } from "../pr/checkout.ts";
+import { CliError } from "../cli/error.ts";
 export declare function gitRoot(cwd: string, run?: Run): Promise<string>;
-export declare class ReviewCliError extends Error {
-    code: string;
-    hint?: string;
-    exitCode: number;
+/** Backward-compatible name for the shared CLI error. Local and remote review
+ * threw this before CORE-10 introduced `CliError`, so it stays as a thin
+ * subclass and every existing call site keeps working. */
+export declare class ReviewCliError extends CliError {
     constructor(code: string, message: string, hint?: string, exitCode?: number);
 }
 export declare function assertGitQuiet(cwd: string, run?: Run): Promise<void>;

package/dist/src/local/git_ops.js

@@ -1,6 +1,7 @@
 import { runCommand } from "../pr/checkout.js";
 import { normalizeGithubRemote } from "./git_parse.js";
 import { stat } from "../util/runtime.js";
+import { CliError, EXIT_USAGE } from "../cli/error.js";
 export async function gitRoot(cwd, run = runCommand) {
     const result = await run("git", ["rev-parse", "--show-toplevel"], cwd);
     if (result.code !== 0) {
@@ -8,15 +9,13 @@ export async function gitRoot(cwd, run = runCommand) {
     }
     return result.stdout.trim();
 }
-export class ReviewCliError extends Error {
-    code;
-    hint;
-    exitCode;
-    constructor(code, message, hint, exitCode = 2) {
-        super(message);
-        this.code = code;
-        this.hint = hint;
-        this.exitCode = exitCode;
+/** Backward-compatible name for the shared CLI error. Local and remote review
+ * threw this before CORE-10 introduced `CliError`, so it stays as a thin
+ * subclass and every existing call site keeps working. */
+export class ReviewCliError extends CliError {
+    constructor(code, message, hint, exitCode = EXIT_USAGE) {
+        super(code, message, hint, exitCode);
+        this.name = "ReviewCliError";
     }
 }
 export async function assertGitQuiet(cwd, run = runCommand) {

package/dist/src/local/review_local.js

@@ -4,16 +4,19 @@ import { buildLocalReviewJson, formatHumanLocalReview, resolvedFromFirstReview,
 import { emptyAiMetrics, recordAiCost, runInitOrRemake, } from "../services/setup.js";
 import { aiFor } from "../services/review.js";
 import { loadGuides } from "../review/guides.js";
-import { buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
+import { buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
 import { revisionHash } from "../review/revision.js";
 import { parseFindings } from "../pr/findings.js";
 import { reviewWorkspaceRevision } from "../pr/reviewer.js";
 import { runCommand } from "../pr/checkout.js";
 import { log, startHeartbeat, timed, withCliLogsToStderr, } from "../util/log.js";
+import { printRunSummary, summaryFromMetrics } from "../util/run_summary.js";
 import { setCliInteractive } from "../cli/args.js";
 import { prepareLocalCodegraph } from "./codegraph_prepare.js";
+import { canPrompt } from "../tools/codegraph.js";
 import { acquireLocalReviewLock } from "./review_lock.js";
 import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, headSha, ReviewCliError, } from "./git_ops.js";
+import { EXIT_RUNTIME, exitWith } from "../cli/error.js";
 import { buildLocalRevision, mergeBase, resolveBaseRef, } from "./git_revision.js";
 import { clearLocalCarry, localSubjectId, saveLocalCarry, tryLoadLocalCarry, } from "./carry_over_store.js";
 function storedFindings(resolved) {
@@ -45,7 +48,9 @@ function fail(error, json) {
         if (error.hint)
             console.error(`Hint: ${error.hint}`);
     }
-    process.exit(error.exitCode);
+    // Set the exit code and return; `process.exit` here would assert in libuv on
+    // Windows whenever a fetch pool is open (CORE-11).
+    exitWith(error.exitCode);
 }
 function installInterruptCleanup(releaseSync, json) {
     const onSignal = () => {
@@ -58,10 +63,10 @@ function installInterruptCleanup(releaseSync, json) {
                     code: "aborted",
                     message: "Review canceled.",
                 },
-                exitCode: 3,
+                exitCode: EXIT_RUNTIME,
             }));
         }
-        process.exit(3);
+        exitWith(EXIT_RUNTIME);
     };
     for (const signal of ["SIGINT", "SIGTERM"]) {
         try {
@@ -106,7 +111,7 @@ export async function runLocalReview(cli) {
             }
             if (cli.remakeBeforeReview) {
                 if (options.auth !== "gh") {
-                    throw new ReviewCliError("usage", "Remake before review requires GitHub CLI authentication (`--auth=gh`).");
+                    throw new ReviewCliError("usage", "Sync before review requires GitHub CLI authentication (`--auth=gh`).");
                 }
                 await runInitOrRemake({ ...options, command: "remake" });
             }
@@ -139,7 +144,7 @@ export async function runLocalReview(cli) {
                 else {
                     console.log("No changes to review.");
                 }
-                process.exit(0);
+                exitWith(0);
             }
             const subjectId = localSubjectId(repo, root, branch);
             if (cli.fresh)
@@ -148,10 +153,19 @@ export async function runLocalReview(cli) {
             if (carryLoad.unavailable) {
                 warnings.push({
                     code: "carry_over_unavailable",
-                    message: "Could not read the local carry-over cache; continuing without prior findings.",
+                    message: "Could not read the local carry-over cache. Continuing without prior findings.",
                 });
             }
-            const previous = carryLoad.data;
+            let previous = carryLoad.data;
+            // A guide rebuilt after the last review judged its findings under rules
+            // that no longer exist. Rather than let those stale findings mask new
+            // ones, start fresh automatically (CORE-42 / F03) — the same effect as
+            // `--fresh`, without making the user remember the flag.
+            if (previous &&
+                guideRebuiltSince(previous.guideBuiltAt, guides.guideBuiltAt)) {
+                await clearLocalCarry(repo, root, branch).catch(() => { });
+                previous = null;
+            }
             let carryPrevious = null;
             let carryItems = [];
             const extras = {};
@@ -174,7 +188,9 @@ export async function runLocalReview(cli) {
                 gitRoot: root,
                 enabled: options.useCodegraph === true,
                 allowInstall: cli.allowToolInstall,
-                interactive: !json,
+                // `--json` output must stay machine-readable, so never prompt then;
+                // `canPrompt` adds the TTY and CI checks (F01).
+                interactive: !json && canPrompt(),
             });
             extras.prepareCodegraphTools = () => Promise.resolve(codegraphPrep.tools);
             const stopHeartbeat = startHeartbeat("reviewing local changes");
@@ -194,10 +210,12 @@ export async function runLocalReview(cli) {
                 }, aiFor(options), (message) => log("review", message), extras));
             }
             finally {
+                // Stopping the heartbeat on the error path too, otherwise the interval
+                // keeps the event loop alive and a post-fetch exit never lands (CORE-11).
+                stopHeartbeat();
                 await lock?.release();
                 lock = null;
             }
-            stopHeartbeat();
             const codegraphState = codegraphPrep.state;
             const visiblePaths = new Set(response.visiblePaths);
             if (carryPrevious) {
@@ -206,7 +224,7 @@ export async function runLocalReview(cli) {
             const parsed = parseFindings(response.text);
             const filesByPath = new Map(revision.files.map((f) => [f.path, f]));
             const allResolved = carryPrevious
-                ? resolveCarryOutcomes(carryItems, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed, response.guideBuiltAt, carryPrevious)
+                ? resolveCarryOutcomes(carryItems, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed)
                 : resolvedFromFirstReview(parsed, filesByPath);
             const findingsToStore = storedFindings(allResolved);
             const afterBuilt = await buildLocalRevision(root, baseSha, base.label, runCommand);
@@ -252,18 +270,22 @@ export async function runLocalReview(cli) {
                     warnings,
                     usage,
                     durationMs,
+                    reviewBlocking: options.reviewBlocking,
                 }));
             }
             else {
                 console.log("\n" +
-                    formatHumanLocalReview(header, revision, response.guideBuiltAt, codegraphState, allResolved, warnings) +
+                    formatHumanLocalReview(header, revision, response.guideBuiltAt, codegraphState, allResolved, warnings, options.reviewBlocking) +
                     "\n");
+                printRunSummary(summaryFromMetrics(aiMetrics, performance.now() - started));
             }
-            process.exit(reviewExitCodeFromResolved(allResolved));
+            exitWith(reviewExitCodeFromResolved(allResolved, options.reviewBlocking));
         }
         catch (error) {
-            if (error instanceof ReviewCliError)
+            if (error instanceof ReviewCliError) {
                 fail(error, json);
+                return;
+            }
             throw error;
         }
         finally {

package/dist/src/pr/checkout.js

@@ -32,17 +32,28 @@ export async function pathExists(path) {
 async function cloneInto(repo, dir, run) {
     log("checkout", `cloning ${repo} into ${dir}`);
     const started = performance.now();
+    // `-c core.longpaths=true` has to be in effect for the clone itself: a deep
+    // source tree can overrun the Windows path limit while the objects are being
+    // written, and setting the config afterwards is too late to help. CORE-11.
     const result = await run("git", [
+        "-c",
+        "core.longpaths=true",
         "clone",
         "--filter=blob:none",
         `https://github.com/${repo}`,
         dir,
     ]);
     if (result.code !== 0) {
-        throw new Error(`git clone failed: ${result.stderr.trim()}`);
+        // One actionable line, not the raw multi-line git transcript: the caller
+        // only needs to know the clone failed and what it costs them. CORE-11.
+        const firstLine = result.stderr
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find((line) => line.length > 0) ?? "";
+        throw new Error(`git clone failed (exit ${result.code}) for ${repo}, so this review has no ` +
+            `repository scope and falls back to the diff only` +
+            (firstLine ? `: ${firstLine}` : ""));
     }
-    // Deep source trees overrun the Windows path limit even under a short root.
-    await run("git", ["config", "core.longpaths", "true"], dir);
     log("checkout", `cloned in ${((performance.now() - started) / 1000).toFixed(1)}s`);
     return dir;
 }

package/dist/src/pr/codegraph_tools.js

@@ -143,7 +143,7 @@ export function codegraphTools(binary, worktree, runner = createCodegraphRunner(
                             },
                             file: {
                                 type: "string",
-                                description: "A file path — reads the file's symbol map instead of a single symbol.",
+                                description: "A file path. Reads the file's symbol map instead of a single symbol.",
                             },
                             symbolsOnly: {
                                 type: "boolean",
@@ -324,7 +324,7 @@ export function codegraphTools(binary, worktree, runner = createCodegraphRunner(
                 type: "function",
                 function: {
                     name: "codegraph-impact",
-                    description: "Analyze what else in the codebase is affected by changing a specific symbol — its blast radius.",
+                    description: "Analyze what else in the codebase is affected by changing a specific symbol, meaning its blast radius.",
                     parameters: {
                         type: "object",
                         properties: {
@@ -362,7 +362,7 @@ export function codegraphTools(binary, worktree, runner = createCodegraphRunner(
                 type: "function",
                 function: {
                     name: "codegraph-affected",
-                    description: "Find test files affected by one or more changed source files — the direct way to check whether a change is covered by any test, instead of guessing from the diff.",
+                    description: "Find test files affected by one or more changed source files. This is the direct way to check whether a change is covered by any test, instead of guessing from the diff.",
                     parameters: {
                         type: "object",
                         properties: {

package/dist/src/pr/diff_summary.js

@@ -10,7 +10,7 @@ export async function summarizeDiff(path, patch, provider, usage) {
         prompt: `Summarize this diff for \`${path}\` in 3-5 sentences: what changed, the
 mechanism, and precisely which branches, patterns, or call paths are affected.
 Do not speculate beyond what the diff shows. Do not suggest fixes or judge
-whether the change is correct — only describe it.
+whether the change is correct. Only describe it.
 
 ${patch}`,
         maxTokens: 500,
@@ -23,7 +23,7 @@ export const READ_FULL_DIFF_TOOL = {
     type: "function",
     function: {
         name: "read-full-diff",
-        description: "Read the complete, untruncated diff for one file in this pull request's own changes. Only files whose diff was summarized (over 500 changed lines) are available this way — everything else is already shown in full.",
+        description: "Read the complete, untruncated diff for one file in this pull request's own changes. Only files whose diff was summarized (over 500 changed lines) are available this way. Everything else is already shown in full.",
         parameters: {
             type: "object",
             properties: {
@@ -45,7 +45,7 @@ export function readFullDiff(patchByPath, args) {
     if (patch)
         return numberPatch(patch);
     return patchByPath.size === 0
-        ? "No large files were summarized in this review; every file's diff is already shown in full above."
+        ? "No large files were summarized in this review. Every file's diff is already shown in full above."
         : `No summarized diff found for \`${path}\`. Summarized files: ${[
             ...patchByPath.keys(),
         ].join(", ")}`;

package/dist/src/pr/findings.js

@@ -1,5 +1,12 @@
 const FILE_LINE = /(?<path>(?:[\w.-]+\/)*[\w.-]+\.[A-Za-z0-9]+):(?<from>\d+)(?:-(?<to>\d+))?/g;
-const NEW_HEADING = /^\[(?<severity>P[0-3])\s*·\s*(?<impact>blocking|non-blocking)\]\s+(?<path>.+?)\s+—\s+(?<symbol>.+)$/;
+/** The finding heading: `[P2 · non-blocking] \`path\` — \`symbol\``. The model
+ * sometimes writes `:` where the prompt asked for the em dash, and sometimes
+ * leaves the symbol off. Both are accepted: an unrecognised heading used to
+ * send every finding down the fallback path, which is what produced the
+ * truncated and shifted output in F02. The separator may also sit directly
+ * against the path (`\`src/a.ts\`: \`helper()\``), which is how the model
+ * usually writes the colon form. */
+const NEW_HEADING = /^\[(?<severity>P[0-3])\s*·\s*(?<impact>blocking|non-blocking)\]\s+(?<path>.+?)(?:\s*(?:—|:)\s*(?<symbol>.+))?$/;
 function uncode(value) {
     return value.trim().replace(/^`|`$/g, "").trim();
 }
@@ -27,19 +34,23 @@ function newFinding(header, block) {
     if (!at)
         return undefined;
     const path = uncode(meta.groups.path);
-    const symbol = uncode(meta.groups.symbol);
+    const symbol = uncode(meta.groups.symbol ?? "");
     const severity = meta.groups.severity;
     const impact = meta.groups.impact;
     const excerpt = bodyWithoutLocation(block);
     const summary = excerpt.split(/\r?\n/).find((line) => line.trim()) ?? "";
     return {
         ...at,
-        path,
-        heading: `[${severity} · ${impact}] \`${path}\` — \`${symbol}\``,
+        // The Location line is authoritative for the path; the heading only names
+        // it, and may omit the symbol entirely.
+        path: at.path || path,
+        heading: symbol
+            ? `[${severity} · ${impact}] \`${path}\`: \`${symbol}\``
+            : `[${severity} · ${impact}] \`${path}\``,
         excerpt,
         severity,
         blocking: impact === "blocking",
-        symbol,
+        symbol: symbol || undefined,
         summary,
     };
 }

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

@@ -0,0 +1,26 @@
+/** Structured review output (CORE-40 / F02).
+ *
+ * F02: findings were truncated mid-sentence (`... while \`u`) and split at the
+ * wrong offsets, because the model's free-form Markdown was sliced by the
+ * fallback parser. The fix is to have the model return JSON and generate the
+ * Markdown ourselves, so a finding's boundaries can no longer be guessed from
+ * prose. Markdown stays the internal contract — every downstream consumer
+ * (`parseFindings`, carry-over, GitHub posting) keeps working unchanged.
+ */
+import type { Json } from "../types.ts";
+import type { ParsedFinding } from "./findings.ts";
+/** OpenRouter `response_format` for a review. Providers that ignore it still
+ * get the prompt's instruction to return a fenced JSON block. */
+export declare const FINDINGS_JSON_SCHEMA: Json;
+/** The prompt's contract, kept next to the schema so the two cannot drift. */
+export declare const FINDINGS_JSON_INSTRUCTIONS = "Return a single JSON object, and nothing else, with this shape:\n{\"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\"}]}\n\nRules for the JSON:\n- \"severity\" is exactly one of P0, P1, P2, P3. \"blocking\" is true or false.\n- \"lineFrom\" and \"lineTo\" are numbers in the new file, copied from the DIFF\n  column, never counted from the @@ header. \"lineTo\" may equal \"lineFrom\".\n- \"title\" is one sentence naming the defect, without the severity or the path.\n- \"body\" is the explanation. Do not repeat the title, the path, or the location\n  line inside it; our code renders those. Do not add a closing sentence asking\n  whether to explain more, and do not use the words Mechanism, Symptom,\n  Scenario, Verified, Repro, Options, or Scope as labels.\n- \"suggestion\" holds only the replacement source lines, with their original\n  indentation, when the fix replaces the exact lines lineFrom-lineTo in one\n  hunk of the same file. Omit it otherwise. Never wrap it in a code fence.\n- When a fix needs removed lines, another file, or more than one hunk, omit\n  \"suggestion\".\n- Return every independently actionable finding, including none: use\n  {\"findings\":[]} when the change is clean. Never invent a finding to fill the\n  array.";
+/** 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 declare function findingsMarkdownFromJson(text: string): string | undefined;
+/** The findings a JSON review produced, for callers that want the objects
+ * rather than the Markdown. */
+export type JsonFindingResult = {
+    markdown: string;
+    findings: ParsedFinding[];
+};