@mechanai/deepreview 2.1.5 → 2.2.1

package/.opencode/agents/deepreview-applier.md

@@ -6,6 +6,10 @@ permission:
   edit: allow
   bash:
     "git diff*": allow
+    "mise run fmt*": allow
+    "mise run lint*": allow
+    "mise run check*": allow
+    "mise run test*": allow
     "*": deny
 ---
 
@@ -21,7 +25,7 @@ For each fix in the plan, in the order specified by the "Order of Operations" se
 
 1. Read the current file at the referenced location
 2. Apply the code change exactly as specified in the plan
-3. **Globalize check:** After applying, check whether other files _listed in input.txt or the plan_ have the same pattern. If so, apply the equivalent fix there too. Do NOT search the broader codebase. Common cases:
+3. **Globalize check:** After applying, check whether other files _listed in input.txt or the plan_ have the same pattern. If so, apply the equivalent fix there too. Do NOT search the broader codebase. To identify "listed files": for diff inputs, use files from `diff --git a/... b/...` headers; for concatenated file inputs, use files from `=== filename ===` headers. Common cases:
    - A loop command fix that applies to the other loop command (code-loop ↔ spec-loop)
    - A prompt/contract change affecting multiple agent files
    - A variable rename or policy change referenced in multiple files
@@ -30,6 +34,24 @@ For each fix in the plan, in the order specified by the "Order of Operations" se
 
 If a fix cannot be applied (file doesn't exist, code doesn't match what was expected), skip it and note the failure.
 
+## Scope rules
+
+- Apply ONLY what the plan specifies. Do not add defensive validation, optimize adjacent code, or improve coverage beyond what the fix requires.
+- If the plan's code change seems incomplete or wrong, apply it anyway and note the concern — do not improvise a "better" fix.
+
+## Verification (after all fixes are applied)
+
+After applying all fixes, run verification if `mise.toml` exists in the project root:
+
+1. Run `mise run fmt` (auto-fix formatting — this is expected to modify files)
+2. Run `mise run lint` or `mise run check` (whichever exists)
+3. Run `mise run test`
+
+If lint/check/test fails:
+
+- Include the error output in your response
+- Mark the relevant fix as FAILED with the error
+
 ## Response contract
 
 Your ONLY response must be a list of files modified, one per line, in this format:
@@ -37,6 +59,8 @@ Your ONLY response must be a list of files modified, one per line, in this forma
 ```
 APPLIED: path/to/file.ts — [one-line description of change]
 SKIPPED: path/to/other.ts — [reason it couldn't be applied]
+FAILED: path/to/broken.ts — [lint/test error message]
+VERIFICATION: [PASS | FAIL — summary of fmt/lint/test results]
 ```
 
 Do not include any other text.

package/.opencode/agents/deepreview-architecture.md

@@ -36,6 +36,11 @@ Your prompt may also begin with framing directives (e.g., novelty-seeking instru
 
 Use `git log` on changed files to understand the evolution of the code.
 
+## Scope constraints
+
+- **Only flag issues attributable to the diff under review.** Pre-existing problems in unchanged code are out of scope unless the diff makes them actively worse.
+- Focus on structural and design issues, not cosmetic ones.
+
 ## Output format
 
 Write your review to the output path provided. Use this format for each finding:

package/.opencode/agents/deepreview-compatibility.md

@@ -38,6 +38,10 @@ Your prompt may also begin with framing directives (e.g., novelty-seeking instru
 
 Use `git log` and `git show` to check if removed/changed items had external consumers.
 
+## Scope constraints
+
+- **Only flag issues attributable to the diff under review.** Pre-existing compatibility concerns in unchanged code are out of scope unless the diff makes them actively worse.
+
 ## Output format
 
 Write your review to the output path provided. Use this format for each finding:

package/.opencode/agents/deepreview-correctness.md

@@ -38,6 +38,11 @@ Your prompt may also begin with framing directives (e.g., novelty-seeking instru
 
 Use `git blame` and `git log` on changed files to understand intent when unclear.
 
+## Scope constraints
+
+- **Only flag issues attributable to the diff under review.** Pre-existing bugs in unchanged code are out of scope unless the diff makes them actively worse.
+- Focus on correctness of the new/changed code, not unrelated pre-existing issues.
+
 ## Output format
 
 Write your review to the output path provided. Use this format for each finding:

package/.opencode/agents/deepreview-docs.md

@@ -49,10 +49,16 @@ Write your review to the output path provided. Use this format for each finding:
 
 Severity guide:
 
-- **critical:** Doc/comment claims something false about the code (will mislead developers or users)
+- **critical:** Doc/comment claims something false that would cause an implementer to build the wrong thing or misuse an API. Stale wording that is obviously outdated (and thus unlikely to mislead) is NOT critical.
 - **warning:** Duplicate or stale content that wastes reader attention
 - **suggestion:** Verbose text that could be tightened
 
+## Scope constraints
+
+- **Only flag issues attributable to the diff under review.** Pre-existing documentation problems in unchanged code are out of scope unless the diff makes them actively worse.
+- **ADRs (Architecture Decision Records) are historical documents.** Do not flag them for being "stale" — they record the decision at the time it was made. Only flag ADRs if the diff explicitly modifies them and introduces inconsistencies.
+- **Test code cosmetics** (test function names, test descriptions) are suggestions at most, never warnings or critical.
+
 If you find no issues, write: "No documentation issues found."
 
 Be concise. No preamble or filler. Each finding should be actionable in 3-5 lines. If you find no issues in a category, say so in one line.

package/.opencode/agents/deepreview-planner.md

@@ -23,6 +23,12 @@ You will receive a path to a synthesis file. Read it.
 2. For each finding, read ONLY the specific function or block referenced (use the Read tool with offset/limit to read ~50 lines around the referenced line — do NOT read entire files)
 3. Write exact code changes for each fix
 
+## Quality rules
+
+- **One clean solution per fix.** Do not include your reasoning process, rejected approaches, or self-corrections in the output. If you are unsure which approach is best, pick the simplest one and add a one-line "Alternative:" note.
+- **Stay within scope.** Only fix what the synthesis identifies. Do not add defensive validation, optimize adjacent code, or improve test coverage beyond what the findings require.
+- **Concrete, not aspirational.** Every code change must be copy-pasteable. No pseudocode, no "something like this", no TODOs.
+
 ## Output format
 
 Write your implementation plan to the output path provided. Use this structure:

package/.opencode/agents/deepreview-review-formatter.md

@@ -22,18 +22,34 @@ Read both files.
 ## Process
 
 1. Read the synthesis and identify every individual finding (each bullet or paragraph that describes a distinct issue)
-2. For each finding, determine:
+2. If the synthesis contains an "Overall Assessment" section, emit it as the **first document** with frontmatter `summary: true` (no `path` or `line`). The body should be the assessment text, lightly edited for brevity.
+3. For each finding, determine:
    - `path`: the file path (relative to repo root) the finding refers to
    - `line`: the specific line number (new-side of diff). If the synthesis gives a range, use the end line.
    - `startLine`: if the finding spans multiple lines, use the start of the range. Omit if single-line.
-3. Read `input.txt` (the diff) to:
+4. Read `input.txt` (the diff) to:
    - Verify line references are correct
    - Generate ` ```suggestion ` blocks where a concrete fix is obvious and fits within the diff
-4. Write each finding as a document in the output file
+5. Write each finding as a document in the output file
 
 ## Output format
 
-Write to the output path provided. Use this exact format — one document per finding, separated by `---`:
+Write to the output path provided. The file has two parts:
+
+### 1. Summary document (first, when synthesis has an Overall Assessment)
+
+If the synthesis contains an "Overall Assessment" section, the first document must have `summary: true` in its frontmatter. Its body is a 2-3 sentence overall assessment. This appears as the review body on GitHub. Omit this document only if the synthesis has no assessment section.
+
+```
+---
+summary: true
+---
+<2-3 sentence overall assessment from the synthesis>
+```
+
+### 2. Finding documents (one per finding)
+
+Each finding follows the summary, separated by `---`:
 
 ```
 ---
@@ -49,7 +65,7 @@ line: <line number>
 - One finding per document. Never bundle multiple issues.
 - No stats, severity counts, or framing ("3 critical issues found")
 - No references to local file paths, session directories, AI tooling, or the deepreview pipeline
-- Use permalinks for code references: `https://github.com/OWNER/REPO/blob/$PR_HEAD_SHA/<path>#L<line>`
+- Use permalinks for code references: `https://github.com/OWNER/REPO/blob/<PR_HEAD_SHA>/<path>#L<line>`
   - Get OWNER/REPO from the diff header or from `input.txt` context
 - Use ` ```suggestion ` blocks where a concrete fix is obvious
 - American English. Succinct. No filler.

package/.opencode/agents/deepreview-security.md

@@ -36,6 +36,11 @@ Your prompt may also begin with framing directives (e.g., novelty-seeking instru
 
 Use `git blame` and `git log` on changed files to understand intent when unclear.
 
+## Scope constraints
+
+- **Only flag issues attributable to the diff under review.** Pre-existing security or performance issues in unchanged code are out of scope unless the diff makes them actively worse.
+- **Test code patterns** (test fixtures, test helpers, deliberate test doubles) should only be flagged if they could leak into production or mask real bugs. `std::mem::forget` in a test to keep a tempdir alive is not a security concern.
+
 ## Output format
 
 Write your review to the output path provided. Use this format for each finding:

package/.opencode/agents/deepreview-validator.md

@@ -14,26 +14,38 @@ permission:
     "*": deny
 ---
 
-You are a skeptical senior engineer. Your job is to cross-validate code review findings by checking every claim against the actual source code. You are not here to agree — you are here to disprove.
+You are a skeptical senior engineer. Your job is to cross-validate code review findings by checking every claim against the actual source code. You are not here to agree — you are here to disprove. Your default stance is rejection; a finding must earn its place with verifiable evidence.
 
 ## Input
 
-You will receive paths to 3 review files and a perspective label (correctness, security, or architecture). Read all 3 review files.
+You will receive paths to review files and a perspective label. Read all review files.
 
 ## Process
 
-For each finding in all 3 reviews:
+For each finding in all reviews:
 
 1. Read the source file and line referenced in the finding
-2. Determine if the claimed issue actually exists in the code
-3. If the finding makes claims about external tool behavior (CLI flags, API parameters, library methods), **verify those claims**. Run `--help`, check man pages, or use WebFetch to check documentation. If the claimed behavior doesn't exist, classify as disproved.
-4. Check if the issue is already handled elsewhere (error handling, validation, guards)
-5. Classify the finding:
-   - **confirmed** (high confidence): you verified the issue exists in the code
+2. **Verify the reference exists.** If the finding claims something exists at a specific file:line (a function, a reference, a pattern), confirm that thing actually exists at that location. If it doesn't, classify as disproved.
+3. Determine if the claimed issue actually exists in the code
+4. If the finding makes claims about external tool behavior (CLI flags, API parameters, library methods), **verify those claims**. Run `--help`, check man pages, or use WebFetch to check documentation. If the claimed behavior doesn't exist, classify as disproved.
+5. Check if the issue is already handled elsewhere (error handling, validation, guards)
+6. **Assess severity proportionality.** If the finding's severity is more than one level above what the evidence supports (e.g., a stale comment rated "critical" when it's clearly a "suggestion"), downgrade it or classify as trivial.
+7. Classify the finding:
+   - **confirmed** (high confidence): you verified the issue exists in the code and the severity is proportionate
    - **plausible** (medium confidence): the issue might exist but you cannot fully verify
-   - **disproved** (low confidence): the code already handles this, the claim is wrong, or the finding assumes external tool/API behavior that doesn't exist
+   - **trivial**: the issue technically exists but is not worth fixing — severity is inflated, the fix is cosmetic, or the finding is a style preference rather than an objective defect
+   - **disproved** (low confidence): the code already handles this, the claim is wrong, the referenced location doesn't contain what's claimed, or the finding assumes external tool/API behavior that doesn't exist
 
-Discard all low-confidence (disproved) findings entirely.
+Discard all **disproved** and **trivial** findings entirely.
+
+## Rejection criteria (discard the finding if ANY apply)
+
+- The referenced file:line does not contain what the finding claims
+- The finding flags a pre-existing issue in unchanged code that the diff does not make worse
+- The severity is inflated by more than one level (e.g., a typo in a comment rated "critical")
+- The finding is a design opinion or stylistic preference, not an objective defect
+- The finding duplicates another reviewer's finding on the same file:line (note the overlap, keep only one)
+- The finding references a historical document (ADR, changelog) as "stale" when the document is intentionally historical
 
 ## Output format
 

package/.opencode/commands/deepreview-loop.md

@@ -8,13 +8,14 @@ STEP 1: DETERMINE INPUT MODE
 Parse "$ARGUMENTS" the same way as /deepreview:
 
 - If it starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
-- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
+- Validate `CONTEXT_FILE`: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
+  _(Canonical source for `CONTEXT_FILE` validation rules. Keep `deepreview.md`, `deepreview-spec.md`, and `deepreview-spec-loop.md` in sync.)_
 - If it is a number → MODE=pr, TARGET="$ARGUMENTS"
 - If it is a file path or multiple file paths → MODE=files, TARGET="$ARGUMENTS"
 - If it is empty → MODE=branch, TARGET=""
 
 Set ITERATION=1
-Set PRIOR_CONTEXT="" (empty — built up across iterations)
+Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 
 If CONTEXT_FILE exists, read its contents and set PRIOR_CONTEXT to:
@@ -43,9 +44,20 @@ Dispatch the applier automatically — do NOT ask the user for permission.
 Use the Task tool with subagent_type="deepreview-applier":
 "Read the implementation plan at $SESSION_DIR/implementation-plan.md. Apply the fixes."
 
-Wait for the applier to return.
+Wait for the applier to return. Parse the applier's response for VERIFICATION status.
 
-STEP 5: INCREMENT AND RE-REVIEW (lightweight — NO cross-validation)
+STEP 4b: HANDLE VERIFICATION RESULTS
+If the applier reports VERIFICATION: FAIL:
+
+- Show the user the error summary from the applier's response
+- Ask: "Applied fixes failed verification (lint/test). Options: revert and skip failing fix, continue anyway, or stop?"
+- If revert: run `git checkout -- .` to undo all changes from this iteration, note which fix failed, add it to a SKIP_LIST, and re-run the planner+applier without that fix.
+- If continue: proceed to STEP 5 (the next iteration's reviewers will likely catch the introduced error).
+- If stop: STOP.
+
+If the applier reports VERIFICATION: PASS (or no verification was possible): proceed to STEP 5.
+
+STEP 5: INCREMENT AND RE-REVIEW
 Set ITERATION = ITERATION + 1
 
 If ITERATION > 5:
@@ -67,36 +79,47 @@ Prepare fresh input:
 
 Check if input.txt is empty. If empty, tell user "Nothing to review — all changes resolved." and STOP.
 
-STEP 5a: BUILD PRIOR CONTEXT
+STEP 5a: DIFF SIZE DIVERGENCE CHECK
+Compare the size of the new input.txt to the previous iteration's input.txt (in bytes or lines).
+If the new input is more than 50% larger than the previous iteration's input:
+
+- Tell the user: "Divergence warning: diff grew from ~N to ~M lines (X% increase). The applier may be adding more code than it's fixing."
+- Ask: "Continue with the larger diff, or revert last iteration's changes?"
+- If revert: run `git checkout -- .`, STOP.
+- If continue: proceed.
+
+STEP 5b: BUILD PRIOR CONTEXT
 Accumulate findings from ALL previous iterations into PRIOR_CONTEXT so no finding is re-reported.
 
-To build this, dispatch a helper task that reads ALL previous syntheses:
+To build this, dispatch a helper task that reads ALL previous syntheses AND implementation plans:
 NOTE: Interpolate the actual directory paths from ALL_SESSION_DIRS into this task string — the subagent cannot access your variables.
 Task — Use the Task tool with subagent_type="general":
-"Read the synthesis files from these directories: [LIST EACH PATH FROM ALL_SESSION_DIRS EXCLUDING CURRENT]. If any synthesis file does not exist, skip it. Extract ALL findings across them as a deduplicated Markdown list in this exact format:
+"Read the synthesis files AND implementation plan files from these directories: [LIST EACH PATH FROM ALL_SESSION_DIRS EXCLUDING CURRENT]. If any file does not exist, skip it. Extract:
 
 ## Prior Findings (already reported — do not re-report or verify)
 
 - [Short Issue Title] ([category]) — [file:line]
 
+## Applied Fixes (changes made by previous iterations — new bugs here are regressions)
+
+- [Fix title from implementation plan] — [file:line] (applied in iter N)
+
 ## Covered Regions (already examined — prioritize elsewhere)
 
 - [file:line-range] (pad each finding's file:line by 20 lines in each direction)
 
-Deduplicate findings that appear in multiple syntheses. Return ONLY these two sections, nothing else."
+Deduplicate findings that appear in multiple syntheses. Return ONLY these three sections, nothing else."
 
 Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
-NOW RUN A LIGHTWEIGHT REVIEW (Stages 1, 3, 4 only — NO cross-validation):
-
-The key difference: iteration 2+ skips cross-validation. This prevents validators from filtering out new issues introduced by fixes.
+STEP 5c: RUN REVIEW WITH CROSS-VALIDATION
 
 Stage 1 — DISPATCH 5 PARALLEL REVIEWERS:
 Each reviewer prompt MUST include PRIOR_CONTEXT and the novelty-seeking framing below.
 
 The REVIEWER_PREAMBLE for all iter2+ reviewers is:
-"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings.
+"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings. If you find a bug in code listed under 'Applied Fixes', flag it as a regression.
 
 $PRIOR_CONTEXT
 
@@ -129,14 +152,39 @@ Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/re
 
 Wait for all 5. Record which succeeded.
 
-Stage 3 (skip Stage 2) — DISPATCH SYNTHESIZER DIRECTLY ON RAW REVIEWS:
-Task 6 — Use the Task tool with subagent_type="deepreview-synthesizer":
-"Read the reviews at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Write the synthesis to $SESSION_DIR/synthesis.md."
+STEP 5d: VERIFY REVIEWER OUTPUT
+Check how many review files were actually written. Run: `ls $SESSION_DIR/review-*.md 2>/dev/null | wc -l`
+
+- If 0 files exist: Tell the user "All reviewers failed to produce output. This usually means the diff is too large for subagent context windows or there was an infrastructure failure." STOP.
+- If 1-2 files exist: Warn the user "Only N/5 reviewers produced output. Proceeding with partial results." Continue with what exists.
+- If 3+ files exist: Proceed normally.
+
+Stage 2 — DISPATCH 5 PARALLEL VALIDATORS (cross-validation):
+Task 6 — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: correctness. Read all review files at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-correctness.md."
+
+Task 7 — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: security. Read all review files at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-security.md."
+
+Task 8 — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: architecture. Read all review files at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-architecture.md."
+
+Task 9 — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: docs. Read all review files at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-docs.md."
+
+Task 10 — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: compatibility. Read all review files at: $SESSION_DIR/review-correctness.md, $SESSION_DIR/review-security.md, $SESSION_DIR/review-architecture.md, $SESSION_DIR/review-docs.md, $SESSION_DIR/review-compatibility.md. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-compatibility.md."
+
+Wait for all 5 to return.
+
+Stage 3 — DISPATCH SYNTHESIZER:
+Task 11 — Use the Task tool with subagent_type="deepreview-synthesizer":
+"Read the validated reviews at: $SESSION_DIR/validated-correctness.md, $SESSION_DIR/validated-security.md, $SESSION_DIR/validated-architecture.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-compatibility.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
 
 Record the stats line.
 
 Stage 4 — DISPATCH PLANNER:
-Task 7 — Use the Task tool with subagent_type="deepreview-planner":
+Task 12 — Use the Task tool with subagent_type="deepreview-planner":
 "Read the synthesis at $SESSION_DIR/synthesis.md. Write the implementation plan to $SESSION_DIR/implementation-plan.md."
 
 Record the summary line.
@@ -159,8 +207,9 @@ IMPORTANT RULES:
 - Use ONLY the file paths and stats/summary lines returned by subagents.
 - Apply ALL findings (critical, warning, AND suggestion) — the goal is a clean review.
 - Do NOT ask the user for permission to apply fixes. Apply automatically.
-- DO ask the user if iteration limit is hit or deadlock is detected.
-- Iteration 2+ MUST skip cross-validation, MUST include PRIOR_CONTEXT, and MUST use novelty-seeking framing.
+- DO ask the user if: iteration limit is hit, deadlock is detected, verification fails, or diff size diverges.
+- Iteration 2+ MUST include cross-validation, MUST include PRIOR_CONTEXT, and MUST use novelty-seeking framing.
 - Iteration 2+ MUST NOT tell reviewers to "verify" or "check status of" prior findings.
 - Each iteration uses a NEW session directory — never reuse a previous one.
 - If --context file is provided, include its contents under "Design Decisions" in PRIOR_CONTEXT for ALL iterations (including iter1).
+- If all reviewers produce zero output files, STOP immediately — do not continue to synthesis.

package/.opencode/commands/deepreview-spec-loop.md

@@ -11,7 +11,7 @@ STEP 1: DETERMINE INPUT
 - If remaining "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec-loop [--context <file>] <file1> [file2 ...]" and STOP.
 - Set FILES="$ARGUMENTS"
 - Set ITERATION=1
-- Set PRIOR_CONTEXT="" (empty — built up across iterations)
+- Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 - If CONTEXT_FILE exists, set PRIOR_CONTEXT="## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
@@ -81,7 +81,7 @@ Task — Use the Task tool with subagent_type="general":
 
 Deduplicate findings that appear in multiple syntheses. Return ONLY these two sections, nothing else."
 
-Set PRIOR_CONTEXT to the returned text. If CONTEXT_FILE exists, prepend:
+Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
 The REVIEWER_PREAMBLE for all iter2+ reviewers is:

package/README.md

@@ -83,6 +83,23 @@ its own context, keeping token usage minimal.
 - `git`
 - `gh` CLI (only for PR commands)
 
+## Upgrade
+
+OpenCode caches plugins on first install and does not automatically check for newer versions.
+To upgrade:
+
+```bash
+rm -rf ~/.cache/opencode/packages/*deepreview*/
+```
+
+Then restart OpenCode. It will re-fetch the latest version.
+
+If you installed with `--local`, also re-run the setup script to update symlinks:
+
+```bash
+bunx @mechanai/deepreview@latest/setup --local
+```
+
 > [!NOTE]
 > If upgrading from the old `npx @anthropic/deepreview install` workflow, remove
 > the old copied files first (`rm ~/.config/opencode/agents/deepreview*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.1.5",
+  "version": "2.2.1",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {

package/src/diff-classifier.ts

@@ -22,8 +22,18 @@ interface FileHunks {
  * Tier 2: file-level (file in diff but line not in any hunk)
  * Tier 3: review body (file not in diff)
  */
+// 5MB — diffs larger than this are truncated before parsing
+const MAX_DIFF_SIZE = 5 * 1024 * 1024;
+
 export function classifyFindings(findings: Finding[], diffText: string): ClassifiedFinding[] {
-  const parsed = parseDiff(diffText);
+  let effectiveDiff = diffText;
+  if (diffText.length > MAX_DIFF_SIZE) {
+    console.warn(
+      `WARN: Diff size (${(diffText.length / 1024 / 1024).toFixed(1)}MB) exceeds ${MAX_DIFF_SIZE / 1024 / 1024}MB limit. Truncating — some findings may be demoted to tier 3.`,
+    );
+    effectiveDiff = diffText.slice(0, MAX_DIFF_SIZE);
+  }
+  const parsed = parseDiff(effectiveDiff);
   const fileMap = buildFileMap(parsed);
 
   return findings.map((finding) => {

package/src/parse-threads.test.ts

@@ -2,7 +2,76 @@ import { describe, it } from "bun:test";
 import assert from "node:assert/strict";
 import { parseThreads } from "./parse-threads.ts";
 
-describe("parseThreads", () => {
+describe("parseThreads summary extraction", () => {
+  it("extracts a summary document marked with summary: true", () => {
+    const input = [
+      "---",
+      "summary: true",
+      "---",
+      "Overall this PR looks good with minor issues.",
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Error not propagated.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "Overall this PR looks good with minor issues.");
+    assert.equal(result.findings.length, 1);
+    assert.equal(result.findings[0].path, "src/main.go");
+  });
+
+  it("returns undefined summary when no summary document exists", () => {
+    const input = ["---", "path: src/main.go", "line: 10", "---", "Error not propagated."].join(
+      "\n",
+    );
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, undefined);
+    assert.equal(result.findings.length, 1);
+  });
+
+  it("handles summary at end of file", () => {
+    const input = [
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Finding body.",
+      "---",
+      "summary: true",
+      "---",
+      "Summary at the end.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "Summary at the end.");
+    assert.equal(result.findings.length, 1);
+  });
+});
+
+describe("parseThreads summary edge cases", () => {
+  it("treats empty summary body as empty string", () => {
+    const input = [
+      "---",
+      "summary: true",
+      "---",
+      "",
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Finding.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "");
+    assert.equal(result.findings.length, 1);
+  });
+});
+
+describe("parseThreads findings", () => {
   it("parses a single finding", () => {
     const input = [
       "---",
@@ -13,11 +82,11 @@ describe("parseThreads", () => {
     ].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result.length, 1);
-    assert.equal(result[0].path, "pkg/server/handler.go");
-    assert.equal(result[0].line, 48);
-    assert.equal(result[0].startLine, undefined);
-    assert.equal(result[0].body.trim(), "The error is silently discarded.");
+    assert.equal(result.findings.length, 1);
+    assert.equal(result.findings[0].path, "pkg/server/handler.go");
+    assert.equal(result.findings[0].line, 48);
+    assert.equal(result.findings[0].startLine, undefined);
+    assert.equal(result.findings[0].body.trim(), "The error is silently discarded.");
   });
 
   it("parses multiple findings separated by ---", () => {
@@ -36,23 +105,23 @@ describe("parseThreads", () => {
     ].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result.length, 2);
-    assert.equal(result[0].path, "a.go");
-    assert.equal(result[0].startLine, 10);
-    assert.equal(result[0].line, 15);
-    assert.equal(result[1].path, "b.go");
-    assert.equal(result[1].line, 3);
+    assert.equal(result.findings.length, 2);
+    assert.equal(result.findings[0].path, "a.go");
+    assert.equal(result.findings[0].startLine, 10);
+    assert.equal(result.findings[0].line, 15);
+    assert.equal(result.findings[1].path, "b.go");
+    assert.equal(result.findings[1].line, 3);
   });
 
   it("ignores startLine: 0 (treats as single-line)", () => {
     const input = ["---", "path: x.go", "startLine: 0", "line: 5", "---", "Body."].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result[0].startLine, undefined);
+    assert.equal(result.findings[0].startLine, undefined);
   });
 
-  it("returns empty array for empty input", () => {
+  it("returns empty findings for empty input", () => {
     const result = parseThreads("");
-    assert.equal(result.length, 0);
+    assert.equal(result.findings.length, 0);
   });
 });

package/src/parse-threads.ts

@@ -2,6 +2,12 @@ import matter from "gray-matter";
 import yaml from "js-yaml";
 import type { Finding } from "./diff-classifier.ts";
 
+/** @internal Not part of the public API — subject to change without notice. */
+export interface ParsedThreads {
+  findings: Finding[];
+  summary?: string;
+}
+
 /**
  * gray-matter engine restricted to safe YAML parsing (no !!js/function etc.).
  * FAILSAFE_SCHEMA returns all scalars as strings — numeric fields (line, startLine)
@@ -16,11 +22,13 @@ const safeYamlEngine = (s: string): Record<string, unknown> => {
 const matterOptions = { engines: { yaml: safeYamlEngine } };
 
 /**
- * Parse a threads.md file into an array of finding objects.
- * The file uses --- separators between findings, each with YAML frontmatter.
+ * Parse a threads.md file into findings and an optional summary.
+ * The file uses --- separators between documents, each with YAML frontmatter.
+ * A document with `summary: true` in its frontmatter is extracted as the review summary.
  */
-function parseThreads(content: string): Finding[] {
+function parseThreads(content: string): ParsedThreads {
   const findings: Finding[] = [];
+  let summary: string | undefined;
   const documents = splitDocuments(content);
 
   for (const doc of documents) {
@@ -33,6 +41,16 @@ function parseThreads(content: string): Finding[] {
       continue;
     }
     const data = parsed.data as Record<string, unknown>;
+
+    // Handle summary documents
+    if (String(data.summary).toLowerCase() === "true") {
+      if (summary !== undefined) {
+        console.warn("WARN: Multiple summary documents found — using the last one.");
+      }
+      summary = parsed.content.trim();
+      continue;
+    }
+
     const path = typeof data.path === "string" ? data.path : undefined;
     const lineNum = Number(data.line);
     if (path === undefined || path === "" || !Number.isFinite(lineNum) || lineNum < 1) {
@@ -56,7 +74,7 @@ function parseThreads(content: string): Finding[] {
     });
   }
 
-  return findings;
+  return { findings, summary };
 }
 
 const YAML_KEY_RE = /^\w[\w\s]*:/u;

package/src/post-review.test.ts

@@ -2,6 +2,36 @@ import { describe, it } from "bun:test";
 import assert from "node:assert/strict";
 import { parseThreads } from "./parse-threads.ts";
 import { classifyFindings } from "./diff-classifier.ts";
+import { buildReviewBody } from "./review-helpers.ts";
+
+describe("buildReviewBody", () => {
+  it("includes summary when provided and no tier3 findings", () => {
+    const body = buildReviewBody([], "owner", "repo", "a".repeat(40), "Overall looks good.");
+    assert.ok(body.includes("Overall looks good."));
+    assert.ok(body.includes("🤖 Review generated by AI"));
+  });
+
+  it("includes both summary and tier3 findings", () => {
+    const tier3 = [{ path: "pkg/other.go", line: 5, body: "Unused import.", tier: 3 as const }];
+    const body = buildReviewBody(tier3, "owner", "repo", "a".repeat(40), "Has issues.");
+    assert.ok(body.includes("Has issues."));
+    assert.ok(body.includes("pkg/other.go"));
+    assert.ok(body.includes("Unused import."));
+  });
+
+  it("works without summary (backward compatible)", () => {
+    const tier3 = [{ path: "pkg/other.go", line: 5, body: "Unused import.", tier: 3 as const }];
+    const body = buildReviewBody(tier3, "owner", "repo", "a".repeat(40));
+    assert.ok(!body.includes("undefined"));
+    assert.ok(body.includes("pkg/other.go"));
+    assert.ok(body.includes("🤖 Review generated by AI"));
+  });
+
+  it("only shows trailer when no summary and no tier3 findings", () => {
+    const body = buildReviewBody([], "owner", "repo", "a".repeat(40));
+    assert.equal(body, "\n\n---\n🤖 Review generated by AI");
+  });
+});
 
 describe("integration: parse → classify", () => {
   const threadsContent = [
@@ -38,7 +68,7 @@ describe("integration: parse → classify", () => {
   ].join("\n");
 
   it("classifies findings correctly across all 3 tiers", () => {
-    const findings = parseThreads(threadsContent);
+    const { findings } = parseThreads(threadsContent);
     assert.equal(findings.length, 3);
 
     const classified = classifyFindings(findings, diff);

package/src/post-review.ts

@@ -1,8 +1,7 @@
 import { readFile, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { parseThreads } from "./parse-threads.ts";
-import { classifyFindings } from "./diff-classifier.ts";
-import type { Finding, ClassifiedFinding } from "./diff-classifier.ts";
+import { type Finding, type ClassifiedFinding } from "./diff-classifier.ts";
 import { type PrInfo, getPrInfo, execFileAsync } from "./graphql.ts";
 import {
   type PendingReview,
@@ -14,12 +13,13 @@ import {
   updateReviewComment,
 } from "./review-api.ts";
 import {
-  escapeHtml,
   isValidPath,
   isRateLimitError,
   findingId,
   embedFindingId,
   extractFindingId,
+  buildReviewBody,
+  classifyAndLog,
 } from "./review-helpers.ts";
 
 export interface PostReviewOptions {
@@ -37,27 +37,7 @@ export interface PostReviewResult {
   failed: string[];
 }
 
-const AI_TRAILER = "\n\n---\n🤖 Review generated by AI";
-
-function buildReviewBody(
-  tier3Findings: ClassifiedFinding[],
-  owner: string,
-  name: string,
-  headOid: string,
-): string {
-  let body = "";
-  for (const f of tier3Findings) {
-    if (!isValidPath(f.path)) {
-      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
-      continue;
-    }
-    const permalink = `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blob/${headOid}/${f.path.split("/").map(encodeURIComponent).join("/")}#L${f.line}`;
-    // Neutralize all HTML tags — GitHub re-renders markdown inside <details>.
-    body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.body}\n</details>\n\n`;
-  }
-  body += AI_TRAILER;
-  return body;
-}
+const MAX_INLINE_FINDINGS = 200;
 
 async function updateExistingThreads(
   existingReview: PendingReview,
@@ -79,9 +59,16 @@ async function updateExistingThreads(
     }
   }
 
-  for (const { finding, commentId, id } of toUpdate) {
-    const body = embedFindingId(finding.body, id);
-    await updateReviewComment(commentId, body);
+  const CONCURRENCY = 2;
+  for (let i = 0; i < toUpdate.length; i += CONCURRENCY) {
+    if (i > 0) await Bun.sleep(1000);
+    const batch = toUpdate.slice(i, i + CONCURRENCY);
+    await Promise.all(
+      batch.map(async ({ finding, commentId, id }) => {
+        const body = embedFindingId(finding.body, id);
+        await updateReviewComment(commentId, body);
+      }),
+    );
   }
 
   console.log(`Updated ${toUpdate.length} existing threads.`);
@@ -146,13 +133,20 @@ async function postInlineThreads(
     (f) => !updatedIds.has(findingId(f.path, f.startLine, f.line, f.body)),
   );
 
-  for (let i = 0; i < pending.length; i += CONCURRENCY) {
+  if (pending.length > MAX_INLINE_FINDINGS) {
+    console.warn(
+      `WARN: ${pending.length} inline findings exceed limit of ${MAX_INLINE_FINDINGS}. Truncating.`,
+    );
+  }
+  const capped = pending.slice(0, MAX_INLINE_FINDINGS);
+
+  for (let i = 0; i < capped.length; i += CONCURRENCY) {
     if (i > 0) await Bun.sleep(1000);
-    const batch = pending.slice(i, i + CONCURRENCY);
+    const batch = capped.slice(i, i + CONCURRENCY);
     const results = await Promise.all(
       batch.map(async (f) => {
         const id = findingId(f.path, f.startLine, f.line, f.body);
-        // Trust boundary: body content is rendered by GitHub's Markdown sanitizer
+        // Body rendered by GitHub's Markdown sanitizer; no escaping needed here
         const body = embedFindingId(f.body, id);
         const ok = await postWithRetry(reviewId, f, body);
         return ok ? null : id;
@@ -165,31 +159,6 @@ async function postInlineThreads(
   return failedFindings;
 }
 
-function classifyAndLog(
-  findings: Finding[],
-  diff: string,
-): { tier1: ClassifiedFinding[]; tier2: ClassifiedFinding[]; tier3: ClassifiedFinding[] } {
-  const validated = findings.filter((f) => {
-    if (!isValidPath(f.path)) {
-      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
-      return false;
-    }
-    return true;
-  });
-  const classified = classifyFindings(validated, diff);
-  const tier1 = classified.filter((f) => f.tier === 1);
-  const tier2 = classified.filter((f) => f.tier === 2);
-  const tier3 = classified.filter((f) => f.tier === 3);
-
-  for (const f of tier2) {
-    console.warn(`WARN: ${f.path}:${f.line} demoted to file-level`);
-  }
-  for (const f of tier3) {
-    console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
-  }
-  return { tier1, tier2, tier3 };
-}
-
 async function ensureReview(
   prNodeId: string,
   headOid: string,
@@ -198,18 +167,22 @@ async function ensureReview(
   tier3: ClassifiedFinding[],
   owner: string,
   name: string,
+  summary?: string,
 ): Promise<{ reviewId: string; updatedFindings: Set<string> }> {
   const existingReview = await findPendingReview(prNodeId);
   if (existingReview) {
     console.log(`Found existing pending review: ${existingReview.id}`);
-    await updateReviewBody(existingReview.id, buildReviewBody(tier3, owner, name, headOid));
+    await updateReviewBody(
+      existingReview.id,
+      buildReviewBody(tier3, owner, name, headOid, summary),
+    );
     const updated = await updateExistingThreads(existingReview, [...tier1, ...tier2]);
     return { reviewId: existingReview.id, updatedFindings: updated };
   }
   const reviewId = await createPendingReview(
     prNodeId,
     headOid,
-    buildReviewBody(tier3, owner, name, headOid),
+    buildReviewBody(tier3, owner, name, headOid, summary),
   );
   console.log(`Created pending review: ${reviewId}`);
   return { reviewId, updatedFindings: new Set() };
@@ -220,10 +193,11 @@ async function loadAndValidatePr(
   prNumber: number,
   expectedSha: string | undefined,
   cwd: string | undefined,
-): Promise<{ findings: Finding[]; prInfo: PrInfo } | null> {
+): Promise<{ findings: Finding[]; prInfo: PrInfo; summary?: string } | null> {
   if (!isValidPath(threadsPath)) {
     throw new Error(`Invalid threadsPath: ${threadsPath}`);
   }
+  // cwd is a trusted parameter set by the plugin framework (not user-supplied)
   const base = await realpath(resolve(cwd ?? process.cwd()));
   const candidatePath = resolve(base, threadsPath);
   let resolved: string;
@@ -236,8 +210,8 @@ async function loadAndValidatePr(
     throw new Error(`threadsPath escapes working directory: ${threadsPath}`);
   }
   const content = await readFile(resolved, "utf8");
-  const findings = parseThreads(content);
-  if (findings.length === 0) return null;
+  const { findings, summary } = parseThreads(content);
+  if (findings.length === 0 && (summary === undefined || summary === "")) return null;
 
   const prInfo = await getPrInfo(prNumber, { cwd });
   if (prInfo.state !== "OPEN") {
@@ -249,7 +223,7 @@ async function loadAndValidatePr(
     throw new Error(`ABORT: PR head moved (expected ${resolvedSha}, got ${prInfo.headOid}).`);
   }
 
-  return { findings, prInfo };
+  return { findings, prInfo, summary };
 }
 
 async function postFindings(
@@ -258,6 +232,7 @@ async function postFindings(
   tier3: ClassifiedFinding[],
   prInfo: PrInfo,
   skipIds: string[],
+  summary?: string,
 ): Promise<PostReviewResult> {
   const { owner, name, prNodeId, headOid } = prInfo;
   const { reviewId, updatedFindings } = await ensureReview(
@@ -268,6 +243,7 @@ async function postFindings(
     tier3,
     owner,
     name,
+    summary,
   );
 
   const skipSet = new Set(skipIds);
@@ -280,28 +256,28 @@ async function postFindings(
   const skipped = inlineFindings.filter((f) =>
     updatedFindings.has(findingId(f.path, f.startLine, f.line, f.body)),
   ).length;
-  const posted = inlineFindings.length - skipped - failedIds.length;
+  const pending = inlineFindings.length - skipped;
+  const truncatedCount = Math.max(0, pending - MAX_INLINE_FINDINGS);
+  const posted = Math.min(pending, MAX_INLINE_FINDINGS) - failedIds.length;
   const totalFindings = [...tier1, ...tier2].length;
   const skippedByUser = totalFindings - inlineFindings.length;
-  const summary =
-    `Posted ${posted}/${totalFindings} inline threads (${skipped} up-to-date, ${skippedByUser} skipped, ${failedIds.length} failed). ` +
+  const statusSummary =
+    `Posted ${posted}/${totalFindings} inline threads (${skipped} up-to-date, ${skippedByUser} skipped, ${failedIds.length} failed${truncatedCount > 0 ? `, ${truncatedCount} truncated` : ""}). ` +
     `${tier3.length} findings in review body.`;
 
-  console.log(summary);
+  console.log(statusSummary);
 
-  return { summary, failed: failedIds };
+  return { summary: statusSummary, failed: failedIds };
 }
 
-/**
- * Post a review to a GitHub PR.
- */
 export async function postReview(opts: PostReviewOptions): Promise<PostReviewResult> {
   const { threadsPath, prNumber, dryRun = false, skipIds = [], expectedSha } = opts;
 
   const result = await loadAndValidatePr(threadsPath, prNumber, expectedSha, opts.cwd);
   if (!result) return { summary: "No findings to post.", failed: [] };
 
-  const { findings, prInfo } = result;
+  const { findings, prInfo, summary: reviewSummary } = result;
+
   const diff =
     opts.diffText ??
     (
@@ -321,5 +297,5 @@ export async function postReview(opts: PostReviewOptions): Promise<PostReviewRes
     };
   }
 
-  return postFindings(tier1, tier2, tier3, prInfo, skipIds);
+  return postFindings(tier1, tier2, tier3, prInfo, skipIds, reviewSummary);
 }

package/src/review-api.ts

@@ -64,7 +64,15 @@ async function fetchRemainingComments(
   const comments: ReviewComment[] = [];
   let pageInfo = initialPageInfo;
   let pages = 0;
+  // 5 minute aggregate timeout for pagination
+  const deadline = Date.now() + 5 * 60 * 1000;
   while (pageInfo.hasNextPage && pages++ < MAX_PAGES) {
+    if (Date.now() > deadline) {
+      console.warn(
+        `WARN: Aggregate timeout reached after ${pages} pages. Returning partial results.`,
+      );
+      break;
+    }
     const page = await graphql<CommentsPage>(
       `
         query ($reviewId: ID!, $after: String!) {

package/src/review-helpers.ts

@@ -1,6 +1,9 @@
 import crypto from "node:crypto";
+import { classifyFindings, type Finding, type ClassifiedFinding } from "./diff-classifier.ts";
 
 const FINDING_ID_RE = /<!-- finding:([a-f0-9]+) -->/u;
+const AI_TRAILER = "\n\n---\n🤖 Review generated by AI";
+const GITHUB_NAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u;
 
 export function escapeHtml(s: string): string {
   return s
@@ -63,3 +66,66 @@ export function extractFindingId(body: string): string | null {
   const match = FINDING_ID_RE.exec(body);
   return match ? match[1] : null;
 }
+
+/** @internal Not part of the public API — subject to change without notice. */
+export function buildReviewBody(
+  tier3Findings: ClassifiedFinding[],
+  owner: string,
+  name: string,
+  headOid: string,
+  summary?: string,
+): string {
+  const validOid = /^[0-9a-f]{40,64}$/u.test(headOid);
+  if (!validOid) {
+    console.warn(`WARN: Invalid headOid format (${headOid}). Skipping permalinks.`);
+  }
+  const validRepo = GITHUB_NAME_RE.test(owner) && GITHUB_NAME_RE.test(name);
+  if (!validRepo) {
+    console.warn(`WARN: Invalid owner/name format (${owner}/${name}). Skipping permalinks.`);
+  }
+  let body = "";
+  if (summary !== undefined && summary !== "") {
+    // Trust boundary: summary is AI-generated Markdown from the formatter agent,
+    // rendered by GitHub's Markdown sanitizer (same trust level as finding bodies).
+    body += summary + "\n\n";
+  }
+  for (const f of tier3Findings) {
+    if (!isValidPath(f.path)) {
+      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
+      continue;
+    }
+    if (validOid && validRepo) {
+      const permalink = `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blob/${headOid}/${f.path.split("/").map(encodeURIComponent).join("/")}#L${f.line}`;
+      body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.body}\n</details>\n\n`;
+    } else {
+      body += `<details>\n<summary><code>${escapeHtml(f.path)}:${f.line}</code></summary>\n\n${f.body}\n</details>\n\n`;
+    }
+  }
+  body += AI_TRAILER;
+  return body;
+}
+
+export function classifyAndLog(
+  findings: Finding[],
+  diff: string,
+): { tier1: ClassifiedFinding[]; tier2: ClassifiedFinding[]; tier3: ClassifiedFinding[] } {
+  const validated = findings.filter((f) => {
+    if (!isValidPath(f.path)) {
+      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
+      return false;
+    }
+    return true;
+  });
+  const classified = classifyFindings(validated, diff);
+  const tier1 = classified.filter((f) => f.tier === 1);
+  const tier2 = classified.filter((f) => f.tier === 2);
+  const tier3 = classified.filter((f) => f.tier === 3);
+
+  for (const f of tier2) {
+    console.warn(`WARN: ${f.path}:${f.line} demoted to file-level`);
+  }
+  for (const f of tier3) {
+    console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
+  }
+  return { tier1, tier2, tier3 };
+}