@mechanai/deepreview 2.2.3 → 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/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.3",
+  "version": "2.3.0",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {