@mechanai/deepreview 2.13.0 → 2.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/.opencode/agents/deepreview-synthesizer.md +37 -1
  2. package/.opencode/commands/deepreview-loop.md +46 -5
  3. package/.opencode/commands/deepreview-spec-loop.md +60 -23
  4. package/package.json +1 -1
package/.opencode/agents/deepreview-synthesizer.md CHANGED
@@ -21,6 +21,25 @@ If your prompt begins with a "Prior Findings" preamble, reviewers were instructe
21
21
  - **New findings only**: Your synthesis should contain only genuinely new findings. Do not re-synthesize issues from the prior review preamble.
22
22
  - **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.
23
23
 
24
+ ## Novelty classification (iter2+ loop context only)
25
+
26
+ If your prompt includes a "## Prior Findings for Novelty Classification" preamble, classify each
27
+ finding in the current iteration:
28
+
29
+ - **[NEW]**: mechanism not present in any prior finding (different file + different mechanism, or same file but genuinely different issue)
30
+ - **[RECURRING]**: same file + same mechanism as a prior finding (even if reworded or at a slightly different line)
31
+ - **[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
32
+
33
+ Classification process (after deduplication, before ranking):
34
+
35
+ 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].
36
+ 2. Check prior findings — if a finding matches an existing mechanism (same file + similar problem, even if differently worded), classify as [RECURRING].
37
+ 3. Everything else is [NEW].
38
+
39
+ Prefix each finding entry with its classification tag: `[NEW]`, `[RECURRING]`, or `[REGRESSION]`.
40
+
41
+ If no "Prior Findings for Novelty Classification" preamble is present, skip classification entirely — do not emit tags or the Iteration Metrics section.
42
+
24
43
  ## Process
25
44
 
26
45
  1. Read all validated review files
@@ -50,6 +69,12 @@ Write your synthesis to the output path provided. Use this structure:
50
69
  ## Overall Assessment
51
70
  [2-3 sentences: is this safe to merge, what is the biggest concern, overall quality]
52
71
 
72
+ ## Iteration Metrics
73
+ Iteration N: X findings (Y new, Z recurring, W regression)
74
+ - Convergence: [converging|deadlocked|diverging]
75
+
76
+ [Omit this section entirely if no novelty classification was performed (iter1 or single-pass)]
77
+
53
78
  ## Critical Issues (must fix before merge)
54
79
  [All critical severity items, deduplicated and ranked by confidence]
55
80
 
@@ -74,6 +99,17 @@ The following doc/comment updates were identified (suggestion-level):
74
99
 
75
100
  Be concise. No preamble or filler.
76
101
 
102
+ Convergence value for the Iteration Metrics section:
103
+
104
+ - `converging`: 0 new findings, or fewer new findings than the prior iteration
105
+ - `deadlocked`: 0 new findings but recurring findings persist
106
+ - `diverging`: more new findings than the prior iteration
107
+
77
108
  ## Response contract
78
109
 
79
- 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.
110
+ After writing your synthesis file, your ONLY response must be the absolute path to your output file and a single stats line. Format:
111
+
112
+ - Without novelty classification: `"3 critical, 5 warnings, 2 suggestions"`
113
+ - With novelty classification: `"3 critical, 5 warnings, 2 suggestions | 4 new, 5 recurring, 1 regression"`
114
+
115
+ Do not summarize findings. Do not include any other text.
package/.opencode/commands/deepreview-loop.md CHANGED
@@ -16,6 +16,7 @@ Parse "$ARGUMENTS" the same way as /deepreview:
16
16
 
17
17
  Set ITERATION=1
18
18
  Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
19
+ Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
19
20
  Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
20
21
 
21
22
  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):
53
54
  Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
54
55
 
55
56
  STEP 3: CHECK EXIT CONDITION
56
- DEADLOCK CHECK (iter 2+ only):
57
- 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.
58
57
 
59
- When deadlock is detected:
58
+ 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.
59
+
60
+ NOVELTY MODE (iter2+ only):
61
+
62
+ A) CONVERGENCE EXIT: If `0 new AND 0 regression`:
63
+
64
+ - Tell the user: "deepreview-loop converged after $ITERATION iteration(s). No new findings detected."
65
+ - STOP.
66
+
67
+ B) DEADLOCK (synthesizer signal): If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
68
+
69
+ - Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
70
+ - List the recurring findings from the synthesis.
71
+ - Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
72
+ - Follow the user's instruction.
73
+
74
+ 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]):
75
+
76
+ - Log warning: "Note: deterministic check found matching findings, but synthesizer classified them as new. Trusting synthesizer classification."
77
+ - Do NOT trigger deadlock. Continue.
78
+
79
+ D) Otherwise: proceed to STEP 4.
80
+
81
+ 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.
82
+
83
+ LEGACY MODE (fallback when synthesizer omits novelty metrics):
84
+
85
+ Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
86
+
87
+ DEADLOCK CHECK (iter 2+ only):
88
+ Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If two consecutive iterations produce the SAME findings:
60
89
 
61
90
  - Tell the user: "Deadlock detected: the following findings persist across iterations:"
62
91
  - List the repeated findings.
@@ -65,7 +94,7 @@ When deadlock is detected:
65
94
 
66
95
  If the synthesis/review has 0 critical AND 0 warning AND 0 suggestion findings:
67
96
 
68
- - Tell the user: "deepreviewloop complete after $ITERATION iteration(s). No findings remain."
97
+ - Tell the user: "deepreview-loop complete after $ITERATION iteration(s). No findings remain."
69
98
  - STOP.
70
99
 
71
100
  STEP 4: APPLY ALL FIXES
@@ -249,8 +278,20 @@ Task 14 — Use the Task tool with subagent_type="deepreview-validator":
249
278
  Wait for all 7 to return.
250
279
 
251
280
  Stage 3 — DISPATCH SYNTHESIZER:
281
+ 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).
282
+
283
+ 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.
284
+
252
285
  Task 15 — Use the Task tool with subagent_type="deepreview-synthesizer":
253
- "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."
286
+
287
+ - If PRIOR_FINDINGS_SECTION is non-empty:
288
+ "## Prior Findings for Novelty Classification
289
+ $PRIOR_FINDINGS_SECTION
290
+
291
+ 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."
292
+
293
+ - If PRIOR_FINDINGS_SECTION is empty:
294
+ "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."
254
295
 
255
296
  Record the stats line.
256
297
 
package/.opencode/commands/deepreview-spec-loop.md CHANGED
@@ -12,6 +12,7 @@ STEP 1: DETERMINE INPUT
12
12
  - Set FILES="$ARGUMENTS"
13
13
  - Set ITERATION=1
14
14
  - Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
15
+ - Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
15
16
  - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
16
17
  - Determine REPO_ROOT — the main repository root (not a worktree root). Run:
17
18
  `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
47
48
  Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
48
49
 
49
50
  STEP 3: CHECK EXIT CONDITIONS
51
+
52
+ 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.
53
+
54
+ NOVELTY MODE (iter2+ only):
55
+
56
+ A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
57
+
58
+ - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
59
+ - STOP.
60
+
61
+ B) CONVERGENCE EXIT: If `0 new AND 0 regression`:
62
+
63
+ - Tell the user: "deepreview-spec-loop converged after $ITERATION iteration(s). No new findings detected. Remaining recurring findings (if any) reflect reviewer opinion differences."
64
+ - STOP.
65
+
66
+ C) DEADLOCK EXIT: If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
67
+
68
+ - Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
69
+ - List the recurring findings.
70
+ - Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
71
+ - Follow the user's instruction.
72
+
73
+ D) DIVERGENCE CHECK (iter2+ only): If total findings INCREASE from the previous iteration:
74
+
75
+ - If all additional findings are classified [RECURRING] (none are [NEW]):
76
+ Treat as deadlock, not divergence. Tell the user: "Apparent divergence is actually recurring findings being re-reported. Treating as deadlock."
77
+ Trigger deadlock prompt (same as C).
78
+ - Otherwise (genuinely new findings increasing):
79
+ 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."
80
+ Show the iteration-over-iteration stats.
81
+ Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
82
+ Follow the user's instruction.
83
+
84
+ E) Otherwise: proceed to STEP 4.
85
+
86
+ 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.
87
+
88
+ LEGACY MODE (fallback when synthesizer omits novelty metrics):
89
+
90
+ Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
91
+
50
92
  Track the total finding count (critical + warning + suggestion) for each iteration in a list: HISTORY.
51
93
 
52
94
  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:
54
96
  - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
55
97
  - STOP.
56
98
 
57
- 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):
99
+ B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations:
58
100
 
59
- - 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."
60
- - Show the latest stats breakdown (critical/warning/suggestion).
61
- - STOP. Do NOT ask to continue — plateaus in spec review are a natural stopping point.
101
+ - Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging."
102
+ - Show the latest stats breakdown.
103
+ - STOP.
62
104
 
63
105
  STEP 4: APPLY ALL FIXES
64
106
  Dispatch the applier automatically — do NOT ask the user for permission.
@@ -74,7 +116,7 @@ Set ITERATION = ITERATION + 1
74
116
 
75
117
  If ITERATION > 7:
76
118
 
77
- - Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — plateau detection should have stopped earlier."
119
+ - Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — convergence or deadlock detection should have stopped earlier."
78
120
  - Show the latest stats.
79
121
  - STOP.
80
122
 
@@ -177,8 +219,20 @@ Note: Validators intentionally do NOT receive PRIOR_CONTEXT. They filter on obje
177
219
  Wait for all 5.
178
220
 
179
221
  Stage 3 — DISPATCH SYNTHESIZER:
222
+ 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).
223
+
224
+ 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.
225
+
180
226
  Task 11 — Use the Task tool with subagent_type="deepreview-synthesizer":
181
- "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."
227
+
228
+ - If PRIOR_FINDINGS_SECTION is non-empty:
229
+ "## Prior Findings for Novelty Classification
230
+ $PRIOR_FINDINGS_SECTION
231
+
232
+ 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."
233
+
234
+ - If PRIOR_FINDINGS_SECTION is empty:
235
+ "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."
182
236
 
183
237
  Record the stats line.
184
238
 
@@ -196,23 +250,6 @@ If this task fails, emit a warning: "Plan validation failed — applying unvalid
196
250
 
197
251
  Go to STEP 3.
198
252
 
199
- STEP 6: DIVERGENCE AND DEADLOCK DETECTION
200
- Track finding counts across iterations. Detect TWO failure modes:
201
-
202
- A) DIVERGENCE: If total findings INCREASE from one iteration to the next:
203
-
204
- - 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."
205
- - Show the iteration-over-iteration stats.
206
- - Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
207
- - Follow the user's instruction.
208
-
209
- B) DEADLOCK: If two consecutive iterations produce the same findings (same location, same issue title):
210
-
211
- - Tell the user: "Deadlock detected: the following findings persist across iterations:"
212
- - List the repeated findings.
213
- - Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
214
- - Follow the user's instruction.
215
-
216
253
  IMPORTANT RULES:
217
254
 
218
255
  - Do NOT read any review/synthesis/plan files yourself. Ever.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mechanai/deepreview",
3
- "version": "2.13.0",
3
+ "version": "2.14.0",
4
4
  "description": "Multi-agent parallel code/spec review for OpenCode",
5
5
  "license": "MIT",
6
6
  "repository": {