@mechanai/deepreview 2.13.0 → 2.15.0

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

@@ -58,9 +58,9 @@ Write your validated plan to the output path provided. Use this structure:
 
 ## Fix Plan
 
-### Fix [N]: [Issue Title]
+### Fix [N]: [Issue Title] (full format — critical/warning)
 **File(s):** path/to/file:line
-**Priority:** critical | warning | suggestion
+**Priority:** critical | warning
 **Validation:** approved | revised | rejected
 **Validation notes:** [1-2 sentences: what was checked, what was found]
 **Approach:** [original or revised approach]
@@ -68,6 +68,14 @@ Write your validated plan to the output path provided. Use this structure:
 [Original code if approved, corrected code if revised, "[rejected — see validation notes]" if rejected]
 **Verification:** [from original plan]
 
+### Fix [N]: [Issue Title] (compact format — suggestion)
+**File(s):** path/to/file:line
+**Priority:** suggestion
+**Validation:** approved | revised | rejected
+**Validation notes:** [1-2 sentences: what was checked, what was found]
+**Change:** [Original or corrected instruction; "[rejected — see validation notes]" if rejected]
+**Verification:** [from original plan, if present]
+
 ## Order of Operations
 [Revised if any fixes were rejected or reordering is needed]
 

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

@@ -25,19 +25,22 @@ You will receive a path to a synthesis file. Read it.
 
 ## Documentation Drift handling
 
-If the synthesis contains a "Documentation Drift" section with a batched checklist, consolidate all those items into a **single** fix entry in the plan. Do not create separate fix entries for each documentation item. Use this format:
+If the synthesis contains a "Documentation Drift" section with a batched checklist, consolidate all those items into a **single** fix entry in the plan using compact format. Do not create separate fix entries for each documentation item. Use this format:
 
 ```
 ### Fix [N]: Documentation Updates
+
 **File(s):** [list all affected files]
 **Priority:** suggestion
-**Approach:** Batch update stale/verbose documentation
-**Code changes:**
-[Group changes by file. For each file, show the exact text replacement.]
+**Change:**
+
+- path/to/file1:42 — Replace "old text" with "new text"
+- path/to/file2:18 — Delete stale comment
+- path/to/file3:55 — Replace "old description" with "new description"
 **Verification:** Confirm updated docs match current code behavior
 ```
 
-Critical documentation findings (which appear individually in the "Critical Issues" section, not in "Documentation Drift") should still get their own fix entries.
+Critical documentation findings (which appear individually in the "Critical Issues" section, not in "Documentation Drift") should still get their own fix entries using full format.
 
 ## Quality rules
 
@@ -45,6 +48,15 @@ Critical documentation findings (which appear individually in the "Critical Issu
 - **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.
 
+## Format selection
+
+Select the output format for each fix based on its priority:
+
+- **Full format** for `critical` and `warning` fixes — include Approach and Code change blocks
+- **Compact format** for `suggestion` fixes — use a one-line Change instruction instead (e.g., "Replace X with Y", "Delete line N", "Add X after line N")
+
+For batched documentation fixes, the Change field uses a bullet list (one instruction per location).
+
 ## Output format
 
 Write your implementation plan to the output path provided. Use this structure:
@@ -53,22 +65,33 @@ Write your implementation plan to the output path provided. Use this structure:
 # Implementation Plan — [PR/branch] — [date]
 
 ## Summary
+
 [What needs to be fixed and the estimated scope of work]
 
 ## Fix Plan
 
-### Fix [N]: [Issue Title]
+### Fix [N]: [Issue Title] (full format — critical/warning)
+
 **File(s):** path/to/file:line
-**Priority:** critical | warning | suggestion
+**Priority:** critical | warning
 **Approach:** [what to change and why — 1-2 sentences]
 **Code change:**
 [Exact code to replace the problematic code. Use actual variable names, actual logic. Not pseudocode.]
 **Verification:** [what to check after the fix — 1 sentence]
 
+### Fix [N]: [Issue Title] (compact format — suggestion)
+
+**File(s):** path/to/file:line
+**Priority:** suggestion
+**Change:** [One-line instruction: "Replace X with Y" or "Delete lines N-M" or "Add X after line N"]
+**Verification:** [optional — omit if obvious]
+
 ## Order of Operations
+
 [If fixes depend on each other, specify the order. Otherwise: "Fixes are independent — apply in any order."]
 
 ## Risk
+
 [Any fixes that could introduce new issues and what to watch for]
 ```
 

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

@@ -21,6 +21,25 @@ If your prompt begins with a "Prior Findings" preamble, reviewers were instructe
 - **New findings only**: Your synthesis should contain only genuinely new findings. Do not re-synthesize issues from the prior review preamble.
 - **Regression detection**: If a reviewer flags something in a region that was previously fixed (per the preamble), treat it as a potential regression and flag it at warning severity or higher.
 
+## Novelty classification (iter2+ loop context only)
+
+If your prompt includes a "## Prior Findings for Novelty Classification" preamble, classify each
+finding in the current iteration:
+
+- **[NEW]**: mechanism not present in any prior finding (different file + different mechanism, or same file but genuinely different issue)
+- **[RECURRING]**: same file + same mechanism as a prior finding (even if reworded or at a slightly different line)
+- **[REGRESSION]**: found in code/spec modified by a previous iteration's applied fix AND the mechanism is directly related to the change made by the fix
+
+Classification process (after deduplication, before ranking):
+
+1. Check "Applied Fixes" — if the finding is in a region modified by a fix AND the mechanism is directly related to the change, classify as [REGRESSION].
+2. Check prior findings — if a finding matches an existing mechanism (same file + similar problem, even if differently worded), classify as [RECURRING].
+3. Everything else is [NEW].
+
+Prefix each finding entry with its classification tag: `[NEW]`, `[RECURRING]`, or `[REGRESSION]`.
+
+If no "Prior Findings for Novelty Classification" preamble is present, skip classification entirely — do not emit tags or the Iteration Metrics section.
+
 ## Process
 
 1. Read all validated review files
@@ -50,6 +69,12 @@ Write your synthesis to the output path provided. Use this structure:
 ## Overall Assessment
 [2-3 sentences: is this safe to merge, what is the biggest concern, overall quality]
 
+## Iteration Metrics
+Iteration N: X findings (Y new, Z recurring, W regression)
+- Convergence: [converging|deadlocked|diverging]
+
+[Omit this section entirely if no novelty classification was performed (iter1 or single-pass)]
+
 ## Critical Issues (must fix before merge)
 [All critical severity items, deduplicated and ranked by confidence]
 
@@ -74,6 +99,17 @@ The following doc/comment updates were identified (suggestion-level):
 
 Be concise. No preamble or filler.
 
+Convergence value for the Iteration Metrics section:
+
+- `converging`: 0 new findings, or fewer new findings than the prior iteration
+- `deadlocked`: 0 new findings but recurring findings persist
+- `diverging`: more new findings than the prior iteration
+
 ## Response contract
 
-After writing your synthesis file, your ONLY response must be the absolute path to your output file and a single stats line (e.g., "3 critical, 5 warnings, 2 suggestions"). Do not summarize findings. Do not include any other text.
+After writing your synthesis file, your ONLY response must be the absolute path to your output file and a single stats line. Format:
+
+- Without novelty classification: `"3 critical, 5 warnings, 2 suggestions"`
+- With novelty classification: `"3 critical, 5 warnings, 2 suggestions | 4 new, 5 recurring, 1 regression"`
+
+Do not summarize findings. Do not include any other text.

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

@@ -16,6 +16,7 @@ Parse "$ARGUMENTS" the same way as /deepreview:
 
 Set ITERATION=1
 Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
+Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 
 Determine REPO_ROOT — the main repository root (not a worktree root). Run:
@@ -53,10 +54,38 @@ Run the full deepreview pipeline (Stages 1-5 from the deepreview command):
 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:
+Parse the stats line from the synthesizer. If it contains novelty metrics (the `| N new, N recurring, N regression` suffix), use NOVELTY MODE. Otherwise use LEGACY MODE.
+
+NOVELTY MODE (iter2+ only):
+
+A) CONVERGENCE EXIT: If `0 new AND 0 regression`:
+
+- Tell the user: "deepreview-loop converged after $ITERATION iteration(s). No new findings detected."
+- STOP.
+
+B) DEADLOCK (synthesizer signal): If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
+
+- Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
+- List the recurring findings from the synthesis.
+- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
+- Follow the user's instruction.
+
+C) DEADLOCK (orchestrator fallback): Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If they match BUT the synthesizer did NOT signal deadlock (i.e., it classified some as [NEW]):
+
+- Log warning: "Note: deterministic check found matching findings, but synthesizer classified them as new. Trusting synthesizer classification."
+- Do NOT trigger deadlock. Continue.
+
+D) Otherwise: proceed to STEP 4.
+
+Tracking: If `0 new`, increment CONSECUTIVE_ZERO_NEW. If `> 0 new`, reset CONSECUTIVE_ZERO_NEW to 0. Deadlock (B) triggers when CONSECUTIVE_ZERO_NEW >= 2 AND recurring > 0.
+
+LEGACY MODE (fallback when synthesizer omits novelty metrics):
+
+Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
+
+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:
 
 - Tell the user: "Deadlock detected: the following findings persist across iterations:"
 - List the repeated findings.
@@ -65,7 +94,7 @@ When deadlock is detected:
 
 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."
+- Tell the user: "deepreview-loop complete after $ITERATION iteration(s). No findings remain."
 - STOP.
 
 STEP 4: APPLY ALL FIXES
@@ -249,8 +278,20 @@ Task 14 — Use the Task tool with subagent_type="deepreview-validator":
 Wait for all 7 to return.
 
 Stage 3 — DISPATCH SYNTHESIZER:
+Extract PRIOR_FINDINGS_SECTION from PRIOR_CONTEXT: include only the "## Prior Findings" and "## Applied Fixes" sections (not "Known Issue Locations" or "Covered Regions" — those are for reviewers only).
+
+If PRIOR_FINDINGS_SECTION is non-empty, include the novelty classification header in the synthesizer prompt. If empty (helper returned malformed context), omit the header — the synthesizer will operate in standard mode and the orchestrator MUST use LEGACY MODE for this iteration's exit check.
+
 Task 15 — 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, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is non-empty:
+  "## Prior Findings for Novelty Classification
+  $PRIOR_FINDINGS_SECTION
+
+  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, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is empty:
+  "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, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
 
 Record the stats line.
 

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

@@ -12,6 +12,7 @@ STEP 1: DETERMINE INPUT
 - Set FILES="$ARGUMENTS"
 - Set ITERATION=1
 - Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
+- Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 - Determine REPO_ROOT — the main repository root (not a worktree root). Run:
   `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
@@ -47,6 +48,47 @@ Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec comma
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
 
 STEP 3: CHECK EXIT CONDITIONS
+
+Parse the stats line from the synthesizer. If it contains novelty metrics (the `| N new, N recurring, N regression` suffix), use NOVELTY MODE. Otherwise use LEGACY MODE.
+
+NOVELTY MODE (iter2+ only):
+
+A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
+
+- Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
+- STOP.
+
+B) CONVERGENCE EXIT: If `0 new AND 0 regression`:
+
+- Tell the user: "deepreview-spec-loop converged after $ITERATION iteration(s). No new findings detected. Remaining recurring findings (if any) reflect reviewer opinion differences."
+- STOP.
+
+C) DEADLOCK EXIT: If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
+
+- Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
+- List the recurring findings.
+- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
+- Follow the user's instruction.
+
+D) DIVERGENCE CHECK (iter2+ only): If total findings INCREASE from the previous iteration:
+
+- If all additional findings are classified [RECURRING] (none are [NEW]):
+  Treat as deadlock, not divergence. Tell the user: "Apparent divergence is actually recurring findings being re-reported. Treating as deadlock."
+  Trigger deadlock prompt (same as C).
+- Otherwise (genuinely new findings increasing):
+  Tell the user: "Divergence detected: findings increased from N to M. The review is not converging — fixes are introducing new issues or reviewers are finding new stylistic concerns."
+  Show the iteration-over-iteration stats.
+  Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
+  Follow the user's instruction.
+
+E) Otherwise: proceed to STEP 4.
+
+Tracking: If `0 new`, increment CONSECUTIVE_ZERO_NEW. If `> 0 new`, reset CONSECUTIVE_ZERO_NEW to 0. Deadlock (C) triggers when CONSECUTIVE_ZERO_NEW >= 2 AND recurring > 0.
+
+LEGACY MODE (fallback when synthesizer omits novelty metrics):
+
+Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
+
 Track the total finding count (critical + warning + suggestion) for each iteration in a list: HISTORY.
 
 A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
@@ -54,11 +96,11 @@ A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
 - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
 - STOP.
 
-B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations (i.e., the last 2 totals are both >= the historical minimum):
+B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations:
 
-- Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging. The spec has been substantively improved but remaining findings likely reflect reviewer opinion differences."
-- Show the latest stats breakdown (critical/warning/suggestion).
-- STOP. Do NOT ask to continue — plateaus in spec review are a natural stopping point.
+- Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging."
+- Show the latest stats breakdown.
+- STOP.
 
 STEP 4: APPLY ALL FIXES
 Dispatch the applier automatically — do NOT ask the user for permission.
@@ -74,7 +116,7 @@ Set ITERATION = ITERATION + 1
 
 If ITERATION > 7:
 
-- Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — plateau detection should have stopped earlier."
+- Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — convergence or deadlock detection should have stopped earlier."
 - Show the latest stats.
 - STOP.
 
@@ -177,8 +219,20 @@ Note: Validators intentionally do NOT receive PRIOR_CONTEXT. They filter on obje
 Wait for all 5.
 
 Stage 3 — DISPATCH SYNTHESIZER:
+Extract PRIOR_FINDINGS_SECTION from PRIOR_CONTEXT: include only the "## Prior Findings" and "## Applied Fixes" sections (not "Known Issue Locations" or "Covered Regions" — those are for reviewers only).
+
+If PRIOR_FINDINGS_SECTION is non-empty, include the novelty classification header in the synthesizer prompt. If empty (helper returned malformed context), omit the header — the synthesizer will operate in standard mode and the orchestrator MUST use LEGACY MODE for this iteration's exit check.
+
 Task 11 — Use the Task tool with subagent_type="deepreview-synthesizer":
-"Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md. Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is non-empty:
+  "## Prior Findings for Novelty Classification
+  $PRIOR_FINDINGS_SECTION
+
+  Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is empty:
+  "Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
 
 Record the stats line.
 
@@ -196,23 +250,6 @@ If this task fails, emit a warning: "Plan validation failed — applying unvalid
 
 Go to STEP 3.
 
-STEP 6: DIVERGENCE AND DEADLOCK DETECTION
-Track finding counts across iterations. Detect TWO failure modes:
-
-A) DIVERGENCE: If total findings INCREASE from one iteration to the next:
-
-- Tell the user: "Divergence detected: findings increased from N to M. The review is not converging — fixes are introducing new issues or reviewers are finding new stylistic concerns."
-- Show the iteration-over-iteration stats.
-- Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
-- Follow the user's instruction.
-
-B) DEADLOCK: If two consecutive iterations produce the same findings (same location, same issue title):
-
-- 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.
-
 IMPORTANT RULES:
 
 - Do NOT read any review/synthesis/plan files yourself. Ever.

package/package.json

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