@mechanai/deepreview 2.2.2 → 2.3.0

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

@@ -23,8 +23,11 @@ You will receive a path to an implementation plan file. Read it.
 
 For each fix in the plan, in the order specified by the "Order of Operations" section (or top-to-bottom if fixes are independent):
 
+- If the fix is marked `**Validation:** rejected`, skip it entirely. Do not read the file or attempt the change. Note it as `SKIPPED (rejected): path — reason from validation notes`.
+
 1. Read the current file at the referenced location
 2. Apply the code change exactly as specified in the plan
+   - For fixes marked `**Validation:** revised`, the `**Code change:**` field contains the validator's corrected version — apply it normally. Use `APPLIED (revised):` in your response.
 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
@@ -58,6 +61,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]
+APPLIED (revised): path/to/file.ts — [one-line description; code was revised by validator]
+SKIPPED (rejected): path/to/file.ts — [reason from validation notes]
 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]

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

@@ -0,0 +1,91 @@
+---
+description: "Validates proposed fixes from the implementation plan against actual source code or spec documents before application. Part of the deepreview pipeline."
+mode: subagent
+temperature: 0.1
+permission:
+  # Read access is implicitly unrestricted (OpenCode default) — needed to inspect source files.
+  edit:
+    ".ai/deepreview/**": allow
+    "*": deny
+  bash:
+    "git log*": allow
+    "git blame*": allow
+    "*": deny
+---
+
+You are a skeptical senior engineer. Your job is to independently verify each proposed fix in an implementation plan before it gets applied to the codebase. You are not here to agree with the planner — you are here to catch mistakes.
+
+## Input
+
+You will receive paths to:
+
+1. An implementation plan file (the planner's output)
+2. An input file (the original diff or file content being reviewed)
+3. A synthesis file (the review findings the fixes address)
+
+Read all three.
+
+## Process
+
+For each fix in the implementation plan, in order:
+
+1. **Read broader context** — Read the full function/class containing the fix target (up to ~200 lines per fix). If the fix changes a function signature or behavior, also read direct callers. Use the Read tool with offset/limit. Do NOT read entire files.
+   - _If the input is spec/plan documents (not source code):_ skip caller/callee checks. Instead, validate logical consistency, cross-reference accuracy, and that the fix matches the synthesis finding.
+2. **Verify correctness** — Does the proposed code change actually fix the identified issue? Check for:
+   - Logic errors in the fix itself
+   - Missing imports or dependencies
+   - Wrong variable names or types
+   - Broken callers/callees from signature changes
+   - Whether the fix matches what the synthesis finding actually describes
+3. **Check scope** — Does the fix stay within what the finding requires? Flag if it adds unnecessary validation, refactoring, or unrelated changes.
+4. **Detect conflicts** (best-effort) — Do any fixes modify the same file region or interact in ways that would break when applied together? When a conflict is detected, reject the lower-priority fix. When conflicting fixes have equal priority, reject the one that appears later in the plan.
+
+## Verdict per fix
+
+- **approved** — Fix is correct and safe to apply as-is.
+- **revised** — Fix addresses the right issue but needs adjustment. You provide a corrected code change. Note: revised code reflects the validator's correction but has not been re-validated by a second pass.
+- **rejected** — Fix is wrong, introduces a new bug, or is out of scope. Explain why. The applier will skip this fix.
+
+## Output format
+
+Write your validated plan to the output path provided. Use this structure:
+
+```
+# Validated Implementation Plan — [PR/branch] — [date]
+
+## Summary
+[Original summary + validation stats: N approved, N revised, N rejected]
+
+## Fix Plan
+
+### Fix [N]: [Issue Title]
+**File(s):** path/to/file:line
+**Priority:** critical | warning | suggestion
+**Validation:** approved | revised | rejected
+**Validation notes:** [1-2 sentences: what was checked, what was found]
+**Approach:** [original or revised approach]
+**Code change:**
+[Original code if approved, corrected code if revised, "[rejected — see validation notes]" if rejected]
+**Verification:** [from original plan]
+
+## Order of Operations
+[Revised if any fixes were rejected or reordering is needed]
+
+## Risk
+[Updated with any new risks identified during validation]
+```
+
+Critical fixes first, then warnings, then suggestions. Preserve the original ordering within each priority level unless conflict resolution requires reordering.
+
+Be concise. No preamble or filler.
+
+## Quality rules
+
+- **Verify, don't assume.** Read the actual source code before judging a fix. Do not approve or reject based on the plan text alone.
+- **Stay within scope.** Only validate what the plan proposes. Do not suggest additional fixes, improvements, or refactoring.
+- **Preserve approved fixes exactly.** If a fix is approved, copy its code change verbatim — do not edit it.
+- **Reject decisively.** If a fix would introduce a bug, reject it with a clear explanation. Do not try to salvage it with a revision unless the fix is close to correct.
+
+## Response contract
+
+After writing your validated plan file, your ONLY response must be the absolute path to your output file and a single stats line (e.g., "4 approved, 1 revised, 1 rejected"). Do not include any other text.

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

@@ -77,6 +77,38 @@ line: <line number>
 - If the synthesis says "line 42" but looking at the diff that corresponds to a different new-side line, use the correct new-side line
 - If you cannot determine an exact line, use the first line of the relevant function/block
 
+## Suggestion block rules
+
+When a finding contains a ` ```suggestion ` block, the `startLine..line` anchor MUST cover every line that the suggestion replaces — not just the line referenced in the synthesis.
+
+Before writing a suggestion:
+
+1. Identify the exact lines in the diff that will be replaced by the suggestion content
+2. Count those lines — this is your replacement scope
+3. Set `startLine` to the first line being replaced and `line` to the last
+4. The anchor range (startLine..line) MUST cover all original lines being removed or modified. The suggestion may be shorter than the anchor range (deletions are fine), but should not be longer — if your replacement has more lines than the anchor covers, widen the anchor to include all affected lines.
+
+Example — replacing a 5-line callout block (lines 246-250). Note: use exactly three backticks for suggestion blocks in output — the four-backtick fence below is only for illustration:
+
+````
+---
+path: docs/migration.md
+startLine: 246
+line: 250
+---
+```suggestion
+> [!WARNING]
+> The actual default is 1 MB, not 10 MB.
+```
+````
+
+Common mistakes to avoid:
+
+- Anchoring to a single line inside a multi-line block (e.g., `line: 247` when replacing lines 246-250) — this duplicates surrounding lines when applied
+- Including lines in the suggestion body that already exist outside the anchor range — this creates duplicates
+- If you cannot determine the exact replacement scope from the diff, use prose instead of a suggestion block
+- As a safety net, the posting pipeline strips suggestion blocks that exceed the anchor range — if your suggestion disappears, widen the anchor
+
 ## Response contract
 
 After writing the threads file, your ONLY response must be the absolute path to your output file and a count line (e.g., "12 threads written"). Do not summarize findings.

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

@@ -31,12 +31,26 @@ Run the full deepreview pipeline (Stages 1-5 from the deepreview command):
 - Append SESSION_DIR to ALL_SESSION_DIRS
 - Stage 1: 5 parallel reviewers — prepend PRIOR_CONTEXT (if non-empty) to each reviewer's prompt as "${PRIOR_CONTEXT}You are reviewing ... Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-{perspective}.md."
 - Stage 2: 5 parallel validators (cross-validation)
-  - Note: validators do NOT receive PRIOR_CONTEXT. This is intentional — validators independently verify reviewer claims without being influenced by design context.- Stage 3: Synthesizer
+  - Note: validators do NOT receive PRIOR_CONTEXT. This is intentional — validators independently verify reviewer claims without being influenced by design context.
+- Stage 3: Synthesizer
 - Stage 4: Implementation planner
+- Stage 5: Plan validator — dispatch plan-validator with implementation-plan.md, synthesis.md, and input.txt.
+  If it fails, warn and set PLAN_FILE="$SESSION_DIR/implementation-plan.md".
+  Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md".
 
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
 
 STEP 3: CHECK EXIT CONDITION
+DEADLOCK CHECK (iter 2+ only):
+Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If two consecutive iterations produce the SAME findings, this indicates a deadlock — the applier is making changes that don't resolve the issue, or the reviewer keeps flagging the same thing.
+
+When deadlock is detected:
+
+- Tell the user: "Deadlock detected: the following findings persist across iterations:"
+- List the repeated findings.
+- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
+- Follow the user's instruction.
+
 If the synthesis/review has 0 critical AND 0 warning AND 0 suggestion findings:
 
 - Tell the user: "deepreviewloop complete after $ITERATION iteration(s). No findings remain."
@@ -45,7 +59,7 @@ If the synthesis/review has 0 critical AND 0 warning AND 0 suggestion findings:
 STEP 4: APPLY ALL FIXES
 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."
+"Read the implementation plan at $PLAN_FILE. Apply the fixes."
 
 Wait for the applier to return. Parse the applier's response for VERIFICATION status.
 
@@ -54,7 +68,14 @@ 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 revert:
+  1. Run `git checkout -- .` to undo all changes from this iteration.
+  2. Note which fix failed, add it to a SKIP_LIST, and re-run the planner without that fix, writing to `$SESSION_DIR/implementation-plan-retry.md`.
+  3. Dispatch plan-validator — Use the Task tool with subagent_type="deepreview-plan-validator":
+     "Read the implementation plan at $SESSION_DIR/implementation-plan-retry.md, the synthesis at $SESSION_DIR/synthesis.md, and the original input at $SESSION_DIR/input.txt. Write the validated plan to $SESSION_DIR/validated-plan.md. Note: the following findings were intentionally excluded due to verification failures: [SKIP_LIST]"
+      If it fails, set PLAN_FILE="$SESSION_DIR/implementation-plan-retry.md".
+     Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md".
+  4. Pass PLAN_FILE to the applier.
 - If continue: proceed to STEP 5 (the next iteration's reviewers will likely catch the introduced error).
 - If stop: STOP.
 
@@ -192,17 +213,13 @@ Task 12 — Use the Task tool with subagent_type="deepreview-planner":
 
 Record the summary line.
 
-Go to STEP 3.
-
-STEP 6: DECISION DEADLOCK DETECTION
-If two consecutive iterations produce the SAME findings (same file:line, same issue title), this indicates a deadlock — the applier is making changes that don't resolve the issue, or the reviewer keeps flagging the same thing.
+Stage 5 — DISPATCH PLAN VALIDATOR:
+Task 13 — Use the Task tool with subagent_type="deepreview-plan-validator":
+"Read the implementation plan at $SESSION_DIR/implementation-plan.md, the synthesis at $SESSION_DIR/synthesis.md, and the original input at $SESSION_DIR/input.txt. Write the validated plan to $SESSION_DIR/validated-plan.md."
 
-When deadlock is detected:
+If this task fails, emit a warning: "Plan validation failed — applying unvalidated plan." and set PLAN_FILE="$SESSION_DIR/implementation-plan.md". Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md" and record the stats line.
 
-- Tell the user: "Deadlock detected: the following findings persist across iterations:"
-- List the repeated findings.
-- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
-- Follow the user's instruction.
+Go to STEP 3.
 
 IMPORTANT RULES:
 

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

@@ -26,6 +26,9 @@ Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec comma
 - Stage 2: 5 parallel validators (cross-validation)
 - Stage 3: Synthesizer
 - Stage 4: Implementation planner (spec changes, not code changes)
+- Stage 5: Plan validator — dispatch plan-validator with implementation-plan.md, synthesis.md, and input.txt.
+  If it fails, warn and set PLAN_FILE="$SESSION_DIR/implementation-plan.md".
+  Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md".
 
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
 
@@ -46,10 +49,12 @@ B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to t
 STEP 4: APPLY ALL FIXES
 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."
+"Read the implementation plan at $PLAN_FILE. Apply the fixes."
 
 Wait for the applier to return.
 
+<!-- Note: No verification failure handling here (unlike code-loop) because spec changes don't trigger lint/test failures. -->
+
 STEP 5: INCREMENT AND RE-REVIEW
 Set ITERATION = ITERATION + 1
 
@@ -71,17 +76,21 @@ Check if input.txt is empty. If empty, tell user "Nothing to review — files ar
 BUILD PRIOR CONTEXT FOR THIS ITERATION:
 Dispatch a helper task to extract findings from ALL previous syntheses:
 Task — Use the Task tool with subagent_type="general":
-"Read the synthesis files from ALL completed iterations ([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 or section reference]
 
+## Applied Fixes (changes made by previous iterations — new bugs here are regressions)
+
+- [Fix title from implementation plan] — [file:line or section reference] (applied in iter N)
+
 ## Covered Regions (already examined — prioritize elsewhere)
 
 - [file or section references, padded generously around each finding location]
 
-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"
@@ -148,6 +157,12 @@ Task 12 — Use the Task tool with subagent_type="deepreview-planner":
 
 Record the summary line.
 
+Stage 5 — DISPATCH PLAN VALIDATOR:
+Task 13 — Use the Task tool with subagent_type="deepreview-plan-validator":
+"Read the implementation plan at $SESSION_DIR/implementation-plan.md, the synthesis at $SESSION_DIR/synthesis.md, and the original input at $SESSION_DIR/input.txt. Write the validated plan to $SESSION_DIR/validated-plan.md."
+
+If this task fails, emit a warning: "Plan validation failed — applying unvalidated plan." and set PLAN_FILE="$SESSION_DIR/implementation-plan.md". Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md" and record the stats line.
+
 Go to STEP 3.
 
 STEP 6: DIVERGENCE AND DEADLOCK DETECTION

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

@@ -80,18 +80,25 @@ Task 12 — Use the Task tool with subagent_type="deepreview-planner":
 
 Record the summary line from its return.
 
-STEP 7: PRESENT RESULTS
+STEP 7: DISPATCH STAGE 5 — PLAN VALIDATION (1 task)
+Task 13 — Use the Task tool with subagent_type="deepreview-plan-validator":
+"Read the implementation plan at $SESSION_DIR/implementation-plan.md, the synthesis at $SESSION_DIR/synthesis.md, and the original input at $SESSION_DIR/input.txt. Write the validated plan to $SESSION_DIR/validated-plan.md."
+
+If this task fails (agent error, timeout, or does not produce validated-plan.md), emit a warning: "Plan validation failed — applying unvalidated plan." and set PLAN_FILE="$SESSION_DIR/implementation-plan.md". Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md" and record the stats line.
+
+STEP 8: PRESENT RESULTS
 Show the user:
 
 - Session directory: $SESSION_DIR/
 - Which reviewers completed (and any that failed)
 - Stats from synthesis (the stats line from Step 5)
 - Summary from planner (the summary line from Step 6)
+- Plan validation stats (if available, from Step 7)
 - Ask: "Do you want me to apply the fixes to the spec?"
 
-STEP 8: IF USER SAYS YES — DISPATCH STAGE 5 (1 task)
-Task 13 — Use the Task tool with subagent_type="deepreview-applier":
-"Read the implementation plan at $SESSION_DIR/implementation-plan.md. Apply the fixes."
+STEP 9: IF USER SAYS YES — DISPATCH STAGE 6 (1 task)
+Task 14 — Use the Task tool with subagent_type="deepreview-applier":
+"Read the implementation plan at $PLAN_FILE. Apply the fixes."
 
 Show the user the list of files changed from the applier's return.
 

package/.opencode/commands/deepreview.md

@@ -98,18 +98,25 @@ Task 12 — Use the Task tool with subagent_type="deepreview-planner":
 
 Record the summary line from its return.
 
-STEP 7: PRESENT RESULTS
+STEP 7: DISPATCH STAGE 5 — PLAN VALIDATION (1 task)
+Task 13 — Use the Task tool with subagent_type="deepreview-plan-validator":
+"Read the implementation plan at $SESSION_DIR/implementation-plan.md, the synthesis at $SESSION_DIR/synthesis.md, and the original input at $SESSION_DIR/input.txt. Write the validated plan to $SESSION_DIR/validated-plan.md."
+
+If this task fails (agent error, timeout, or does not produce validated-plan.md), emit a warning: "Plan validation failed — applying unvalidated plan." and set PLAN_FILE="$SESSION_DIR/implementation-plan.md". Otherwise set PLAN_FILE="$SESSION_DIR/validated-plan.md" and record the stats line.
+
+STEP 8: PRESENT RESULTS
 Show the user:
 
 - Session directory: $SESSION_DIR/
 - Which reviewers completed (and any that failed)
 - Stats from synthesis (the stats line from Step 5)
 - Summary from planner (the summary line from Step 6)
+- Plan validation stats (if available, from Step 7)
 - Ask: "Do you want me to apply the fixes?"
 
-STEP 8: IF USER SAYS YES — DISPATCH STAGE 5 (1 task)
-Task 13 — Use the Task tool with subagent_type="deepreview-applier":
-"Read the implementation plan at $SESSION_DIR/implementation-plan.md. Apply the fixes."
+STEP 9: IF USER SAYS YES — DISPATCH STAGE 6 (1 task)
+Task 14 — Use the Task tool with subagent_type="deepreview-applier":
+"Read the implementation plan at $PLAN_FILE. Apply the fixes."
 
 Show the user the list of files changed from the applier's return.
 

package/package.json

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

package/src/diff-classifier.ts

@@ -9,6 +9,8 @@ export interface Finding {
 
 export interface ClassifiedFinding extends Finding {
   tier: 1 | 2 | 3;
+  /** Body with suggestion blocks stripped for rendering. Set for tier-1 findings with oversized suggestions and all tier-2 findings containing suggestions. Original `body` is used for ID computation. Set in review-helpers.ts, not in classifyFindings. */
+  renderedBody?: string;
 }
 
 interface FileHunks {

package/src/post-review.ts

@@ -65,7 +65,7 @@ async function updateExistingThreads(
     const batch = toUpdate.slice(i, i + CONCURRENCY);
     await Promise.all(
       batch.map(async ({ finding, commentId, id }) => {
-        const body = embedFindingId(finding.body, id);
+        const body = embedFindingId(finding.renderedBody ?? finding.body, id);
         await updateReviewComment(commentId, body);
       }),
     );
@@ -147,7 +147,7 @@ async function postInlineThreads(
       batch.map(async (f) => {
         const id = findingId(f.path, f.startLine, f.line, f.body);
         // Body rendered by GitHub's Markdown sanitizer; no escaping needed here
-        const body = embedFindingId(f.body, id);
+        const body = embedFindingId(f.renderedBody ?? f.body, id);
         const ok = await postWithRetry(reviewId, f, body);
         return ok ? null : id;
       }),

package/src/review-helpers.test.ts

@@ -0,0 +1,170 @@
+import { describe, it } from "bun:test";
+import assert from "node:assert/strict";
+import { validateSuggestionAnchors, classifyAndLog } from "./review-helpers.ts";
+
+describe("validateSuggestionAnchors — no warnings", () => {
+  it("returns no warnings for findings without suggestion blocks", () => {
+    const findings = [
+      { path: "foo.go", line: 10, body: "This is just prose feedback.", tier: 1 as const },
+    ];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("returns no warnings when suggestion lines fit within anchor range", () => {
+    const body = [
+      "Replace this function:",
+      "```suggestion",
+      "func foo() {",
+      "  return 42",
+      "}",
+      "```",
+    ].join("\n");
+    // Anchor covers 3 lines (8..10), suggestion has 3 lines — matches
+    const findings = [{ path: "foo.go", startLine: 8, line: 10, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("ignores non-suggestion fenced code blocks", () => {
+    const body = [
+      "Example:",
+      "```go",
+      "func foo() {}",
+      "func bar() {}",
+      "func baz() {}",
+      "```",
+    ].join("\n");
+    const findings = [{ path: "foo.go", line: 5, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("skips tier 2 and tier 3 findings", () => {
+    const body = ["```suggestion", "a", "b", "c", "```"].join("\n");
+    const findings = [
+      { path: "foo.go", line: 5, body, tier: 2 as const },
+      { path: "bar.go", line: 10, body, tier: 3 as const },
+    ];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+});
+
+describe("validateSuggestionAnchors — warnings", () => {
+  it("warns when suggestion has more lines than anchor range", () => {
+    const body = [
+      "Fix this:",
+      "```suggestion",
+      "line1",
+      "line2",
+      "line3",
+      "line4",
+      "line5",
+      "```",
+    ].join("\n");
+    // Anchor is single-line (31), suggestion has 5 lines
+    const findings = [{ path: "mise.toml", line: 31, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("mise.toml:31"));
+    assert.ok(warnings[0].includes("1-line anchor"));
+    assert.ok(warnings[0].includes("5-line suggestion"));
+  });
+
+  it("warns for multi-line anchor that is still too narrow", () => {
+    const body = ["```suggestion", "line1", "line2", "line3", "line4", "line5", "```"].join("\n");
+    // Anchor covers 2 lines (893..894), suggestion has 5 lines
+    const findings = [{ path: "migration.md", startLine: 893, line: 894, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("migration.md:893-894"));
+    assert.ok(warnings[0].includes("2-line anchor"));
+  });
+
+  it("handles multiple suggestion blocks — warns based on largest", () => {
+    const body = [
+      "First fix:",
+      "```suggestion",
+      "a",
+      "b",
+      "c",
+      "```",
+      "Second fix:",
+      "```suggestion",
+      "x",
+      "y",
+      "```",
+    ].join("\n");
+    // Single-line anchor, two suggestion blocks (3 lines and 2 lines)
+    const findings = [{ path: "foo.go", line: 5, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    // Should warn — the largest suggestion (3 lines) exceeds the 1-line anchor
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("3-line suggestion"));
+  });
+});
+
+// Minimal diff that puts foo.go line 10 in a hunk (tier 1)
+const DIFF_FOO = `diff --git a/foo.go b/foo.go
+--- a/foo.go
++++ b/foo.go
+@@ -1,15 +1,15 @@
+ line1
+ line2
+ line3
+ line4
+ line5
+ line6
+ line7
+ line8
+ line9
+-old
++new
+ line11
+ line12
+ line13
+ line14
+ line15
+`;
+
+describe("classifyAndLog — suggestion stripping", () => {
+  it("sets renderedBody when suggestion exceeds anchor", () => {
+    const body = ["Replace this:", "```suggestion", "line A", "line B", "line C", "```"].join("\n");
+    // Single-line anchor (no startLine), 3-line suggestion — exceeds
+    const findings = [{ path: "foo.go", line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    assert.notEqual(tier1[0].renderedBody, undefined);
+    assert.ok(!tier1[0].renderedBody!.includes("```suggestion"));
+    // Original body is untouched
+    assert.ok(tier1[0].body.includes("```suggestion"));
+  });
+
+  it("preserves content from unclosed suggestion blocks", () => {
+    const body = [
+      "Some prose",
+      "```suggestion",
+      "line A",
+      "line B",
+      // No closing fence
+    ].join("\n");
+    const findings = [{ path: "foo.go", line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    // renderedBody should contain the unclosed block content
+    const rendered = tier1[0].renderedBody ?? tier1[0].body;
+    assert.ok(rendered.includes("line A"));
+    assert.ok(rendered.includes("line B"));
+  });
+
+  it("handles inverted startLine/line without negative anchorLines", () => {
+    const body = ["Fix:", "```suggestion", "x", "```"].join("\n");
+    // startLine > line (inverted) — anchorLines should clamp to 1
+    const findings = [{ path: "foo.go", startLine: 12, line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    // 1-line suggestion vs clamped 1-line anchor — fits, no stripping
+    assert.equal(tier1[0].renderedBody, undefined);
+  });
+});

package/src/review-helpers.ts

@@ -4,6 +4,7 @@ import { classifyFindings, type Finding, type ClassifiedFinding } from "./diff-c
 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;
+const SUGGESTION_OPEN_RE = /^```suggestion\b/u;
 
 export function escapeHtml(s: string): string {
   return s
@@ -96,9 +97,9 @@ export function buildReviewBody(
     }
     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`;
+      body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.renderedBody ?? 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 += `<details>\n<summary><code>${escapeHtml(f.path)}:${f.line}</code></summary>\n\n${f.renderedBody ?? f.body}\n</details>\n\n`;
     }
   }
   body += AI_TRAILER;
@@ -127,5 +128,134 @@ export function classifyAndLog(
   for (const f of tier3) {
     console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
   }
+  // Identify findings whose suggestion blocks exceed the anchor range
+  const oversized = findingsExceedingAnchor(classified);
+  const suggestionWarnings = formatSuggestionWarnings(oversized);
+  for (const w of suggestionWarnings) {
+    console.warn(w);
+  }
+  // Strip oversized suggestion blocks from tier-1 findings
+  for (const f of tier1) {
+    if (oversized.has(f)) {
+      f.renderedBody = stripSuggestionBlocks(f.body);
+    }
+  }
+  // Tier-2 findings are posted as file-level comments where suggestion blocks
+  // render as inert code — strip them unconditionally.
+  for (const f of tier2) {
+    const stripped = stripSuggestionBlocks(f.body);
+    if (stripped !== f.body) {
+      f.renderedBody = stripped;
+    }
+  }
+  // Tier-3 findings are posted inside the review body where suggestion blocks
+  // render as inert code — strip them unconditionally.
+  for (const f of tier3) {
+    const stripped = stripSuggestionBlocks(f.body);
+    if (stripped !== f.body) {
+      f.renderedBody = stripped;
+    }
+  }
   return { tier1, tier2, tier3 };
 }
+
+/**
+ * Find the largest ```suggestion block in a finding body by line count.
+ * Returns the maximum line count across all suggestion blocks, or 0 if none.
+ */
+function maxSuggestionLines(body: string): number {
+  let max = 0;
+  let inSuggestion = false;
+  let count = 0;
+  for (const line of body.split("\n")) {
+    if (!inSuggestion && SUGGESTION_OPEN_RE.test(line.trim())) {
+      inSuggestion = true;
+      count = 0;
+    } else if (inSuggestion && line.trimEnd() === "```") {
+      inSuggestion = false;
+      max = Math.max(max, count);
+    } else if (inSuggestion) {
+      count++;
+    }
+  }
+  if (inSuggestion) {
+    max = Math.max(max, count);
+  }
+  return max;
+}
+
+/**
+ * Remove all ```suggestion blocks from a finding body, preserving other content.
+ */
+function stripSuggestionBlocks(body: string): string {
+  const lines = body.split("\n");
+  const result: string[] = [];
+  let inSuggestion = false;
+  let pendingBlock: string[] = [];
+  for (const line of lines) {
+    if (!inSuggestion && SUGGESTION_OPEN_RE.test(line.trim())) {
+      inSuggestion = true;
+      pendingBlock = [line];
+    } else if (inSuggestion && line.trimEnd() === "```") {
+      inSuggestion = false;
+      pendingBlock = [];
+    } else if (inSuggestion) {
+      pendingBlock.push(line);
+    } else {
+      result.push(line);
+    }
+  }
+  if (inSuggestion) {
+    // Unclosed block — preserve all lines as-is
+    result.push(...pendingBlock);
+  }
+  return result.join("\n");
+}
+
+function anchorLineCount(f: Finding): number {
+  return f.startLine === undefined ? 1 : Math.max(1, f.line - f.startLine + 1);
+}
+
+/**
+ * Identify tier-1 findings whose largest suggestion block exceeds the anchor range.
+ * Returns a Set of findings that need their suggestion blocks stripped.
+ */
+function findingsExceedingAnchor(findings: ClassifiedFinding[]): Set<ClassifiedFinding> {
+  const exceeded = new Set<ClassifiedFinding>();
+  for (const f of findings) {
+    if (f.tier !== 1) continue;
+    const suggLines = maxSuggestionLines(f.body);
+    if (suggLines === 0) continue;
+    const anchorLines = anchorLineCount(f);
+    if (suggLines > anchorLines) {
+      exceeded.add(f);
+    }
+  }
+  return exceeded;
+}
+
+/**
+ * Format warning messages for findings whose suggestion blocks exceed their anchor range.
+ * @internal
+ */
+export function formatSuggestionWarnings(oversized: Set<ClassifiedFinding>): string[] {
+  const warnings: string[] = [];
+  for (const f of oversized) {
+    const suggLines = maxSuggestionLines(f.body);
+    const anchorLines = anchorLineCount(f);
+    const anchor =
+      f.startLine === undefined ? `${f.path}:${f.line}` : `${f.path}:${f.startLine}-${f.line}`;
+    warnings.push(
+      `WARN: ${anchor} has ${anchorLines}-line anchor but ${suggLines}-line suggestion — anchor should be widened to cover all lines being replaced`,
+    );
+  }
+  return warnings;
+}
+
+/**
+ * Validate that suggestion blocks fit within their anchor ranges.
+ * @internal
+ */
+export function validateSuggestionAnchors(findings: ClassifiedFinding[]): string[] {
+  return formatSuggestionWarnings(findingsExceedingAnchor(findings));
+}