@mechanai/deepreview 2.0.2 → 2.1.0

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

@@ -21,8 +21,12 @@ For each fix in the plan, in the order specified by the "Order of Operations" se
 
 1. Read the current file at the referenced location
 2. Apply the code change exactly as specified in the plan
-3. Run `git diff <file>` to verify the edit looks correct
-4. Note what was changed (file path + one-line description)
+3. **Globalize check:** After applying, check whether other files _listed in input.txt or the plan_ have the same pattern. If so, apply the equivalent fix there too. Do NOT search the broader codebase. Common cases:
+   - A loop command fix that applies to the other loop command (code-loop ↔ spec-loop)
+   - A prompt/contract change affecting multiple agent files
+   - A variable rename or policy change referenced in multiple files
+4. Run `git diff <file>` to verify the edit looks correct
+5. Note what was changed (file path + one-line description)
 
 If a fix cannot be applied (file doesn't exist, code doesn't match what was expected), skip it and note the failure.
 

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

@@ -15,7 +15,13 @@ You are a principal engineer conducting a focused code review. Your scope is arc
 
 ## Input
 
-You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type. Also read surrounding files referenced in the diff to understand existing patterns — but read at most 10 files, and do not explore the entire codebase.
+You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type. Read surrounding files referenced in the diff to understand existing patterns (max 10 files).
+
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
 
 ## Review checklist
 

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

@@ -17,6 +17,12 @@ You are a senior engineer focused on backwards compatibility. Your scope is brea
 
 You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - Removed or renamed public exports, functions, classes, or methods

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

@@ -17,14 +17,19 @@ You are a senior engineer conducting a focused code review. Your scope is correc
 
 You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - Logic errors and off-by-one mistakes
 - Unhandled edge cases and null/undefined paths
 - Incorrect assumptions about input or state
 - Race conditions or async handling issues
-- Functions that can fail silently
-- Errors swallowed without logging or re-raising
+- Functions that can fail silently (errors swallowed, not logged or re-raised)
 - Missing error propagation (errors caught but not communicated to callers)
 - Partial failure leaving system in inconsistent state
 - Missing retry/backoff for transient failures

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

@@ -17,6 +17,12 @@ You are a technical writing expert conducting a focused code review. Your scope
 
 You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - **Succinctness:** Comments or docs that are verbose, rambling, or use 3 sentences where 1 would do

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

@@ -17,6 +17,12 @@ You are a senior security and performance engineer conducting a focused code rev
 
 You will receive a path to an input file. This may be a diff, a spec, a plan, or concatenated file contents. Read it with the Read tool and adapt your review to the content type.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - Injection vulnerabilities (SQL, command, XSS, etc.)

package/.opencode/agents/deepreview-spec-completeness.md

@@ -17,6 +17,12 @@ You are a senior engineer reviewing a specification or implementation plan for c
 
 You will receive a path to a spec or plan file. Read it with the Read tool.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - Missing error cases — what happens when things go wrong?

package/.opencode/agents/deepreview-spec-consistency.md

@@ -17,6 +17,12 @@ You are a senior engineer reviewing a specification or implementation plan for i
 
 You will receive a path to a spec or plan file. Read it with the Read tool.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - **Contradictions:** Does section A say one thing and section B say the opposite?

package/.opencode/agents/deepreview-spec-feasibility.md

@@ -17,6 +17,12 @@ You are a principal engineer reviewing a specification or implementation plan fo
 
 You will receive a path to a spec or plan file. Read it with the Read tool. If it references existing code, read the relevant files to assess feasibility against the current codebase.
 
+## Prior Context (if provided)
+
+Your prompt may include sections titled "Design Decisions", "Prior Findings", and "Covered Regions". Rules: do NOT flag design decisions as issues; do NOT re-report prior findings; prioritize uncovered regions but you may still report _new_ issues in covered regions.
+
+Your prompt may also begin with framing directives (e.g., novelty-seeking instructions). Follow those directives in addition to the rules above.
+
 ## Review checklist
 
 - **Impossible requirements:** Does the spec ask for something that can't be done with the specified tools/approach?

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

@@ -7,19 +7,27 @@ You are an orchestrator that runs deepreview repeatedly until the code is clean.
 STEP 1: DETERMINE INPUT MODE
 Parse "$ARGUMENTS" the same way as /deepreview:
 
+- If it starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
+- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
 - If it is a number → MODE=pr, TARGET="$ARGUMENTS"
 - If it is a file path or multiple file paths → MODE=files, TARGET="$ARGUMENTS"
 - If it is empty → MODE=branch, TARGET=""
 
 Set ITERATION=1
+Set PRIOR_CONTEXT="" (empty — built up across iterations)
+Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
+
+If CONTEXT_FILE exists, read its contents and set PRIOR_CONTEXT to:
+"## 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"
 
 STEP 2: RUN INITIAL DEEPREVIEW (full pipeline with cross-validation)
 Run the full deepreview pipeline (Stages 1-5 from the deepreview command):
 
 - Determine SESSION_DIR and write input.txt
-- Stage 1: 5 parallel reviewers
+- 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)
-- 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
 
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
@@ -50,6 +58,7 @@ If ITERATION > 5:
 
 Create new session directory: SESSION_DIR=".ai/deepreview/loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
 Run `mkdir -p $SESSION_DIR`
+Append SESSION_DIR to ALL_SESSION_DIRS
 
 Prepare fresh input:
 
@@ -58,27 +67,65 @@ Prepare fresh input:
 
 Check if input.txt is empty. If empty, tell user "Nothing to review — all changes resolved." and STOP.
 
+STEP 5a: BUILD PRIOR CONTEXT
+Accumulate findings from ALL previous iterations into PRIOR_CONTEXT so no finding is re-reported.
+
+To build this, dispatch a helper task that reads ALL previous syntheses:
+NOTE: Interpolate the actual directory paths from ALL_SESSION_DIRS into this task string — the subagent cannot access your variables.
+Task — Use the Task tool with subagent_type="general":
+"Read the synthesis files from these directories: [LIST EACH PATH FROM ALL_SESSION_DIRS EXCLUDING CURRENT]. If any synthesis file does not exist, skip it. Extract ALL findings across them as a deduplicated Markdown list in this exact format:
+
+## Prior Findings (already reported — do not re-report or verify)
+
+- [Short Issue Title] ([category]) — [file:line]
+
+## Covered Regions (already examined — prioritize elsewhere)
+
+- [file:line-range] (pad each finding's file:line by 20 lines in each direction)
+
+Deduplicate findings that appear in multiple syntheses. Return ONLY these two sections, nothing else."
+
+Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
+"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
+
 NOW RUN A LIGHTWEIGHT REVIEW (Stages 1, 3, 4 only — NO cross-validation):
 
-The key difference: iteration 2+ skips cross-validation entirely. This prevents the validators from filtering out new issues introduced by fixes. Each iteration is a fresh, unbiased review.
+The key difference: iteration 2+ skips cross-validation. This prevents validators from filtering out new issues introduced by fixes.
 
 Stage 1 — DISPATCH 5 PARALLEL REVIEWERS:
-Each reviewer prompt MUST include: "This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Do not assume anything is correct just because it looks intentional."
+Each reviewer prompt MUST include PRIOR_CONTEXT and the novelty-seeking framing below.
+
+The REVIEWER_PREAMBLE for all iter2+ reviewers is:
+"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings.
+
+$PRIOR_CONTEXT
+
+Find genuinely new issues. You may find different issues in covered regions, but prioritize areas not yet examined."
 
 Task 1 — Use the Task tool with subagent_type="deepreview-correctness":
-"This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-correctness.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-correctness.md."
 
 Task 2 — Use the Task tool with subagent_type="deepreview-security":
-"This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-security.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-security.md."
 
 Task 3 — Use the Task tool with subagent_type="deepreview-architecture":
-"This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
 
 Task 4 — Use the Task tool with subagent_type="deepreview-docs":
-"This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
 
 Task 5 — Use the Task tool with subagent_type="deepreview-compatibility":
-"This is a fresh review. You have no prior context about this code. Review it as if seeing it for the first time. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-compatibility.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-compatibility.md."
 
 Wait for all 5. Record which succeeded.
 
@@ -113,5 +160,7 @@ IMPORTANT RULES:
 - Apply ALL findings (critical, warning, AND suggestion) — the goal is a clean review.
 - Do NOT ask the user for permission to apply fixes. Apply automatically.
 - DO ask the user if iteration limit is hit or deadlock is detected.
-- Iteration 2+ MUST skip cross-validation and MUST include "fresh review" framing in prompts.
+- Iteration 2+ MUST skip cross-validation, MUST include PRIOR_CONTEXT, and MUST use novelty-seeking framing.
+- Iteration 2+ MUST NOT tell reviewers to "verify" or "check status of" prior findings.
 - Each iteration uses a NEW session directory — never reuse a previous one.
+- If --context file is provided, include its contents under "Design Decisions" in PRIOR_CONTEXT for ALL iterations (including iter1).

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

@@ -6,15 +6,21 @@ You are an orchestrator that runs deepreview-spec repeatedly until the spec/plan
 
 STEP 1: DETERMINE INPUT
 
-- If "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec-loop <file1.md> [file2.md ...]" and STOP.
+- If "$ARGUMENTS" starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
+- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
+- If remaining "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec-loop [--context <file>] <file1> [file2 ...]" and STOP.
 - Set FILES="$ARGUMENTS"
 - Set ITERATION=1
+- Set PRIOR_CONTEXT="" (empty — built up across iterations)
+- Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
+- If CONTEXT_FILE exists, set PRIOR_CONTEXT="## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
 STEP 2: RUN INITIAL DEEPREVIEW-SPEC (full pipeline with cross-validation)
 Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec command):
 
 - Determine SESSION_DIR=".ai/deepreview/spec-loop-iter1-$(date +%Y-%m-%d-%H%M%S)" and write input.txt
-- Stage 1: 5 parallel reviewers (completeness, consistency, feasibility, docs, architecture)
+- Append SESSION_DIR to ALL_SESSION_DIRS
+- Stage 1: 5 parallel reviewers (completeness, consistency, feasibility, docs, architecture) — 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)
 - Stage 3: Synthesizer
 - Stage 4: Implementation planner (spec changes, not code changes)
@@ -53,41 +59,78 @@ If ITERATION > 7:
 
 Create new session directory: SESSION_DIR=".ai/deepreview/spec-loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
 Run `mkdir -p $SESSION_DIR`
+Append SESSION_DIR to ALL_SESSION_DIRS
 
 Re-read the same files into `$SESSION_DIR/input.txt`:
 `for f in $FILES; do echo "=== $f ===" >> $SESSION_DIR/input.txt; cat "$f" >> $SESSION_DIR/input.txt; echo >> $SESSION_DIR/input.txt; done`
 
 Check if input.txt is empty. If empty, tell user "Nothing to review — files are empty." and STOP.
 
+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:
+
+## Prior Findings (already reported — do not re-report or verify)
+
+- [Short Issue Title] ([category]) — [file:line or section reference]
+
+## 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."
+
+Set PRIOR_CONTEXT to the returned text. If CONTEXT_FILE exists, prepend:
+"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
+
+The REVIEWER_PREAMBLE for all iter2+ reviewers is:
+"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings.
+
+$PRIOR_CONTEXT
+
+Find genuinely new issues. You may find different issues in covered regions, but prioritize areas not yet examined. Focus ONLY on objective issues — do NOT flag stylistic preferences."
+
+<!-- The objectivity constraint is spec-loop-specific because specs lack objective correctness criteria, making subjective drift more likely in iterative passes. -->
+
 NOW RUN A FULL REVIEW (with cross-validation):
 
-Unlike the code loop, spec review iterations ALWAYS include cross-validation. Specs have no
-objective "correct" — without validators filtering subjective opinions, reviewers diverge rather
-than converge, producing more findings each iteration instead of fewer.
+Unlike the code loop, spec review iterations ALWAYS include cross-validation. Without validators
+filtering subjective opinions, reviewers diverge rather than converge.
 
 Stage 1 — DISPATCH 5 PARALLEL REVIEWERS:
-Each reviewer prompt MUST include: "This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Do not assume anything is correct just because it looks intentional. Focus ONLY on objective issues (contradictions, gaps, impossibilities) — do NOT flag stylistic preferences or reorganization suggestions."
 
 Task 1 — Use the Task tool with subagent_type="deepreview-spec-completeness":
-"This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Focus ONLY on objective issues — do NOT flag stylistic preferences. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-completeness.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-completeness.md."
 
 Task 2 — Use the Task tool with subagent_type="deepreview-spec-consistency":
-"This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Focus ONLY on objective issues — do NOT flag stylistic preferences. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-consistency.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-consistency.md."
 
 Task 3 — Use the Task tool with subagent_type="deepreview-spec-feasibility":
-"This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Focus ONLY on objective issues — do NOT flag stylistic preferences. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-feasibility.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-feasibility.md."
 
 Task 4 — Use the Task tool with subagent_type="deepreview-docs":
-"This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Focus ONLY on objective issues — do NOT flag stylistic preferences. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
 
 Task 5 — Use the Task tool with subagent_type="deepreview-architecture":
-"This is a fresh review. You have no prior context about this spec. Review it as if seeing it for the first time. Focus ONLY on objective issues — do NOT flag stylistic preferences. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
+"$REVIEWER_PREAMBLE
+
+Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
 
 Wait for all 5. Record which succeeded.
 
 Stage 2 — DISPATCH 5 PARALLEL VALIDATORS (cross-validation):
 Task 6-10 — Use the Task tool with subagent_type="deepreview-validator" (5 times, one per perspective):
 Each validator reads ALL review files and writes to $SESSION_DIR/validated-{completeness,consistency,feasibility,docs,architecture}.md.
+Note: Validators intentionally do NOT receive PRIOR_CONTEXT. They filter on objective merit only — whether findings are technically valid and actionable. The novelty filter is applied at the reviewer level.
 
 Wait for all 5.
 
@@ -108,7 +151,7 @@ Go to STEP 3.
 STEP 6: DIVERGENCE AND DEADLOCK DETECTION
 Track finding counts across iterations. Detect TWO failure modes:
 
-A) DIVERGENCE: If total findings (critical + warning + suggestion) INCREASE from one iteration to the next:
+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.
@@ -130,4 +173,7 @@ IMPORTANT RULES:
 - Do NOT ask the user for permission to apply fixes. Apply automatically.
 - DO ask the user if iteration limit is hit, divergence is detected, or deadlock is detected.
 - ALL iterations include cross-validation (unlike the code loop).
+- Iteration 2+ MUST include PRIOR_CONTEXT and novelty-seeking framing.
+- Iteration 2+ MUST NOT tell reviewers to "verify" or "check status of" prior findings.
 - Each iteration uses a NEW session directory — never reuse a previous one.
+- If --context file is provided, include its contents under "Design Decisions" in PRIOR_CONTEXT for ALL iterations (including iter1).

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

@@ -6,12 +6,14 @@ You are an orchestrator for a multi-agent spec/plan review pipeline. Follow thes
 
 STEP 1: DETERMINE SESSION DIRECTORY
 
+- If "$ARGUMENTS" starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
+- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
 - Set SESSION_DIR=".ai/deepreview/spec-$(date +%Y-%m-%d-%H%M%S)"
 - Create the directory with `mkdir -p $SESSION_DIR`
 
 STEP 2: PREPARE INPUT
 
-- If "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec <file1.md> [file2.md ...]" and STOP.
+- If remaining "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec [--context <file>] <file1> [file2 ...]" and STOP.
 - Concatenate all specified files into $SESSION_DIR/input.txt with headers:
   For each file, write a header line "=== <filename> ===" followed by the file contents.
   Use: `for f in $ARGUMENTS; do echo "=== $f ===" >> $SESSION_DIR/input.txt; cat "$f" >> $SESSION_DIR/input.txt; echo >> $SESSION_DIR/input.txt; done`
@@ -19,23 +21,28 @@ STEP 2: PREPARE INPUT
 
 Set INPUT_DESCRIPTION="the following spec/plan files: $ARGUMENTS"
 
+If CONTEXT_FILE exists, set DESIGN_CONTEXT to the contents of that file. Build a CONTEXT_PREAMBLE:
+"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n$DESIGN_CONTEXT\n`\n\n"
+
+If CONTEXT_FILE does not exist, set CONTEXT_PREAMBLE="" (empty string).
+
 STEP 3: DISPATCH STAGE 1 — INITIAL REVIEW (5 parallel tasks)
 Dispatch ALL FIVE of these Task tool calls simultaneously in a single message:
 
 Task 1 — Use the Task tool with subagent_type="deepreview-spec-completeness":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-completeness.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-completeness.md."
 
 Task 2 — Use the Task tool with subagent_type="deepreview-spec-consistency":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-consistency.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-consistency.md."
 
 Task 3 — Use the Task tool with subagent_type="deepreview-spec-feasibility":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-feasibility.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-feasibility.md."
 
 Task 4 — Use the Task tool with subagent_type="deepreview-docs":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
 
 Task 5 — Use the Task tool with subagent_type="deepreview-architecture":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
 
 Wait for all 5 to return. Record which succeeded and which failed.
 

package/.opencode/commands/deepreview.md

@@ -7,6 +7,8 @@ You are an orchestrator for a multi-agent code review pipeline. Follow these ste
 STEP 1: DETERMINE INPUT MODE AND SESSION DIRECTORY
 Classify "$ARGUMENTS":
 
+- If it starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
+- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
 - If it is a number → MODE=pr
 - If it is a file path (ends in .md, .txt, .yaml, .json, or file exists on disk) → MODE=files
 - If it is multiple space-separated file paths → MODE=files
@@ -36,23 +38,28 @@ Set INPUT_DESCRIPTION based on mode:
 - MODE=branch: "a branch diff against main"
 - MODE=files: "the following files: <list of filenames>"
 
+If CONTEXT_FILE exists, set DESIGN_CONTEXT to the contents of that file. Build a CONTEXT_PREAMBLE:
+"## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n$DESIGN_CONTEXT\n`\n\n"
+
+If CONTEXT_FILE does not exist, set CONTEXT_PREAMBLE="" (empty string).
+
 STEP 3: DISPATCH STAGE 1 — INITIAL REVIEW (5 parallel tasks)
 Dispatch ALL FIVE of these Task tool calls simultaneously in a single message:
 
 Task 1 — Use the Task tool with subagent_type="deepreview-correctness":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-correctness.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-correctness.md."
 
 Task 2 — Use the Task tool with subagent_type="deepreview-security":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-security.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-security.md."
 
 Task 3 — Use the Task tool with subagent_type="deepreview-architecture":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
 
 Task 4 — Use the Task tool with subagent_type="deepreview-docs":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
 
 Task 5 — Use the Task tool with subagent_type="deepreview-compatibility":
-"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-compatibility.md."
+"${CONTEXT_PREAMBLE}You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-compatibility.md."
 
 Wait for all 5 to return. Record which succeeded and which failed.
 

package/README.md

@@ -35,14 +35,18 @@ This will:
 /deepreview                   # Review current branch vs main
 /deepreview 123               # Review PR #123
 /deepreview file1.ts file2.ts # Review specific files
+/deepreview --context decisions.md   # Review with design context (suppresses known decisions)
 
 /deepreview-loop              # Review + fix loop (repeats until clean or 5 iterations)
 /deepreview-loop 123          # Same, targeting a PR
+/deepreview-loop --context decisions.md       # Loop with design context
+/deepreview-spec-loop --context decisions.md spec.md  # Spec loop with design context
 
 /deepreview-pr-review 123     # Review PR and post findings as a pending GitHub review
 
-/deepreview-spec spec.md      # Spec-focused review (completeness, consistency, feasibility)
-/deepreview-spec-loop spec.md # Spec review + fix loop
+/deepreview-spec spec.md                  # Spec-focused review (completeness, consistency, feasibility)
+/deepreview-spec --context decisions.md spec.md  # Spec review with design context
+/deepreview-spec-loop spec.md             # Spec review + fix loop
 ```
 
 All commands accept a branch diff, PR number, or file path(s). The `-loop` variants

package/package.json

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