docs: stabilize review guidance across reruns

packages/core/agents/navigator.md

@@ -11,13 +11,13 @@ You are a navigation specialist for structured, multi-step workflows.
 - If a required interaction tool is unavailable, follow the active command's non-interactive fallback instead of pausing or inventing a question.
 - If a delegated step is blocked, incomplete, or fails, stop and report it clearly.
 
-## Dispatch Blocks
+## Dispatch Execution
 
 - Treat each `<dispatch agent="AGENT_NAME">...</dispatch>` block as a literal message dispatch instruction.
-- `agent` is required and names the exact subagent to invoke.
-- The block body is the exact user message to send.
-- Do not summarize, rewrite, normalize, interpret, or improve the body.
-- Preserve line breaks and ordering exactly after variable substitution.
+- `agent` is required; invoke that exact subagent type.
+- Set `prompt` to the dispatch body exactly after variable substitution.
+- Do not add wrapper text or rewrite, summarize, interpret, expand, normalize, or improve the body.
+- Preserve line breaks and ordering exactly.
 - Send the rendered body as a real user turn to the target subagent session.
 - Never infer what a slash command means when handling a dispatch block. Forward it literally.
 - Process every valid dispatch block you receive.

packages/core/agents/reviewer.md

@@ -42,15 +42,22 @@ Before reviewing, always check repository guidance:
 4. **Skip Noise**:
     - Skip generated, lockfile, or bulk-format churn unless meaningful
     - Don't read every downstream caller - only root cause files
-    - Skip feedback that was already settled in prior PR discussion unless the new diff adds fresh evidence of a material problem
+    - Skip feedback that was already settled in the provided review context unless the new diff adds fresh evidence of a material problem
+
+## Review Stability
+
+- Aim for stable outcomes across reruns on the same effective diff
+- When prior review context is provided, treat it as the baseline for consistency
+- If no relevant code changed since the last review, do not introduce new findings unless there is concrete new evidence or a clearly missed material defect
+- If revising an earlier conclusion, explicitly justify the change based on new diff content, new context, or a clearly missed defect
+- Do not churn on unchanged code paths or re-litigate earlier judgments without new evidence
 
 ## Finding Threshold
 
 - Only report when you can name the likely failure mode
 - Report convention violations only when they conflict with `AGENTS.md`
 - Don't report style, naming, or cleanup unless it masks a real defect
 - Don't publish speculative comments—be certain before flagging hazards
-- Treat resolved threads and explicit author replies that intentionally decline a prior suggestion as settled by default; only re-raise when the issue still clearly causes a real bug, security problem, or broken contract in the current diff
 - Be concise; if it takes more than a few sentences, reconsider
 
 ## Importance Levels

packages/core/commands/pr/review.md

@@ -38,22 +38,24 @@ Call `changes_load` with `base: <pr-context.pr.baseRefName>`, `head: <pr-context
 ### Review Changes
 
 Following the reviewer agent guidance:
-1. Read every changed file for full context before finalizing findings
-2. Check `<pr-context.reviews>`, `<pr-context.issueComments>`, and `<pr-context.threads>`
-3. Derive `<settled-threads>` from `<pr-context.threads>`:
+1. Check `<pr-context.reviews>`, `<pr-context.issueComments>`, and `<pr-context.threads>`
+2. Derive `<settled-threads>` from `<pr-context.threads>`:
    - Treat resolved threads as settled
-   - Treat threads as settled when they already contain feedback from `<pr-context.viewerLogin>` and a later reply from another participant makes it clear the suggestion was intentionally declined, deferred, or answered without a code change request
-   - Only revive a settled thread when the new diff adds concrete evidence that the underlying concern is still a material bug, security issue, or broken contract
-4. Prefer inline comments for file-specific findings; use the review body only for high-level summaries
-5. Use diff hunks in `<changes>` to map inline comments to the correct lines
-6. Do NOT duplicate findings already raised or settled
-
-Derive `<previous-grade>` from prior reviews.
-<% if (it.config.shared.prApprove === true) { -%>
+   - Treat threads as settled when they already contain feedback from `<pr-context.viewerLogin>` and a later reply makes it clear the concern was intentionally declined, deferred, or answered without a code change request
+   - Treat threads as settled when the author's reply directly answers the concern and the current diff does not add a materially different failure mode
+3. Derive `<prior-review-baseline>` from `<pr-context.reviews>` authored by `<pr-context.viewerLogin>`
+4. Use diff hunks in `<changes>` to map inline comments to the correct lines
+5. Derive `<eligible-findings>` as findings that are:
+   - new in this diff
+   - from a previously unreviewed changed area
+   - clearly missed material defects with a concrete failure mode
+   Exclude anything already covered by `<settled-threads>` or `<prior-review-baseline>` on the same effective diff.
+
+<% if (it.config.shared.prApprove === true) { %>
 Derive `<already-approved>` from existing approvals on `<pr-context.pr.headRefOid>`.
-<% } -%>
+<% } %>
 
-Before publishing, derive: `<has-inline-comments>`, `<has-body-note>`, `<publish-grade>`, and `<grade-changed>`.
+Before publishing, derive: `<has-inline-comments>`, `<has-body-note>`, `<publish-grade>`, and whether each proposed finding is included in `<eligible-findings>`.
 
 **Grading and Publishing Rules:**
 1. Assign a grade based on code quality (1-5 stars)
@@ -93,7 +95,8 @@ For multi-line: add `startLine`. For deleted lines: use `side: "LEFT"`.
 - Call `pr_sync` with:
   - `refUrl: <pr-context.pr.url>`
   - `review.body`: the grade line first (for example `★★★☆☆`), followed by any non-inline notes
-  - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open or settled threads in `<pr-context.threads>` unless the new diff introduces a materially different failure mode**
+  - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open threads in `<pr-context.threads>` unless the new diff introduces a materially different failure mode**
+  - Include only findings from `<eligible-findings>`
 - Never omit the grade from `review.body` in this branch
 - Do not pass any other fields
 

packages/core/commands/review.md

@@ -42,11 +42,8 @@ If `<changes>.comparison` is not "uncommitted":
 ### Review Changes
 
 Following the reviewer agent guidance:
-1. Read each changed file for full context in the current session before drafting findings
-2. Analyze for bugs, security issues, and correctness problems
-3. Formulate findings ordered by impact
-4. Store the overall rating as `<star-rating>`, the top-line conclusion as `<short-verdict>`, and the severity counts as `<critical>`, `<high>`, `<medium>`, and `<low>`
-5. Store the total number of findings as `<count>`
+1. Store the overall rating as `<star-rating>`, the top-line conclusion as `<short-verdict>`, and the severity counts as `<critical>`, `<high>`, `<medium>`, and `<low>`
+2. Store the total number of findings as `<count>`
 
 While reading files:
 - Load any relevant nested `AGENTS.md` in the current session before applying review criteria

packages/opencode/.opencode/agents/navigator.md

@@ -20,13 +20,13 @@ You are a navigation specialist for structured, multi-step workflows.
 - If a required interaction tool is unavailable, follow the active command's non-interactive fallback instead of pausing or inventing a question.
 - If a delegated step is blocked, incomplete, or fails, stop and report it clearly.
 
-## Dispatch Blocks
+## Dispatch Execution
 
 - Treat each `<dispatch agent="AGENT_NAME">...</dispatch>` block as a literal message dispatch instruction.
-- `agent` is required and names the exact subagent to invoke.
-- The block body is the exact user message to send.
-- Do not summarize, rewrite, normalize, interpret, or improve the body.
-- Preserve line breaks and ordering exactly after variable substitution.
+- `agent` is required; invoke that exact subagent type.
+- Set `prompt` to the dispatch body exactly after variable substitution.
+- Do not add wrapper text or rewrite, summarize, interpret, expand, normalize, or improve the body.
+- Preserve line breaks and ordering exactly.
 - Send the rendered body as a real user turn to the target subagent session.
 - Never infer what a slash command means when handling a dispatch block. Forward it literally.
 - Process every valid dispatch block you receive.

packages/opencode/.opencode/agents/reviewer.md

@@ -49,15 +49,22 @@ Before reviewing, always check repository guidance:
 4. **Skip Noise**:
     - Skip generated, lockfile, or bulk-format churn unless meaningful
     - Don't read every downstream caller - only root cause files
-    - Skip feedback that was already settled in prior PR discussion unless the new diff adds fresh evidence of a material problem
+    - Skip feedback that was already settled in the provided review context unless the new diff adds fresh evidence of a material problem
+
+## Review Stability
+
+- Aim for stable outcomes across reruns on the same effective diff
+- When prior review context is provided, treat it as the baseline for consistency
+- If no relevant code changed since the last review, do not introduce new findings unless there is concrete new evidence or a clearly missed material defect
+- If revising an earlier conclusion, explicitly justify the change based on new diff content, new context, or a clearly missed defect
+- Do not churn on unchanged code paths or re-litigate earlier judgments without new evidence
 
 ## Finding Threshold
 
 - Only report when you can name the likely failure mode
 - Report convention violations only when they conflict with `AGENTS.md`
 - Don't report style, naming, or cleanup unless it masks a real defect
 - Don't publish speculative comments—be certain before flagging hazards
-- Treat resolved threads and explicit author replies that intentionally decline a prior suggestion as settled by default; only re-raise when the issue still clearly causes a real bug, security problem, or broken contract in the current diff
 - Be concise; if it takes more than a few sentences, reconsider
 
 ## Importance Levels

packages/opencode/.opencode/commands/pr/review.md

@@ -54,20 +54,24 @@ Call `kompass_changes_load` with `base: <pr-context.pr.baseRefName>`, `head: <pr
 ### Review Changes
 
 Following the reviewer agent guidance:
-1. Read every changed file for full context before finalizing findings
-2. Check `<pr-context.reviews>`, `<pr-context.issueComments>`, and `<pr-context.threads>`
-3. Derive `<settled-threads>` from `<pr-context.threads>`:
+1. Check `<pr-context.reviews>`, `<pr-context.issueComments>`, and `<pr-context.threads>`
+2. Derive `<settled-threads>` from `<pr-context.threads>`:
    - Treat resolved threads as settled
-   - Treat threads as settled when they already contain feedback from `<pr-context.viewerLogin>` and a later reply from another participant makes it clear the suggestion was intentionally declined, deferred, or answered without a code change request
-   - Only revive a settled thread when the new diff adds concrete evidence that the underlying concern is still a material bug, security issue, or broken contract
-4. Prefer inline comments for file-specific findings; use the review body only for high-level summaries
-5. Use diff hunks in `<changes>` to map inline comments to the correct lines
-6. Do NOT duplicate findings already raised or settled
+   - Treat threads as settled when they already contain feedback from `<pr-context.viewerLogin>` and a later reply makes it clear the concern was intentionally declined, deferred, or answered without a code change request
+   - Treat threads as settled when the author's reply directly answers the concern and the current diff does not add a materially different failure mode
+3. Derive `<prior-review-baseline>` from `<pr-context.reviews>` authored by `<pr-context.viewerLogin>`
+4. Use diff hunks in `<changes>` to map inline comments to the correct lines
+5. Derive `<eligible-findings>` as findings that are:
+   - new in this diff
+   - from a previously unreviewed changed area
+   - clearly missed material defects with a concrete failure mode
+   Exclude anything already covered by `<settled-threads>` or `<prior-review-baseline>` on the same effective diff.
+
 
-Derive `<previous-grade>` from prior reviews.
 Derive `<already-approved>` from existing approvals on `<pr-context.pr.headRefOid>`.
 
-Before publishing, derive: `<has-inline-comments>`, `<has-body-note>`, `<publish-grade>`, and `<grade-changed>`.
+
+Before publishing, derive: `<has-inline-comments>`, `<has-body-note>`, `<publish-grade>`, and whether each proposed finding is included in `<eligible-findings>`.
 
 **Grading and Publishing Rules:**
 1. Assign a grade based on code quality (1-5 stars)
@@ -98,7 +102,8 @@ For multi-line: add `startLine`. For deleted lines: use `side: "LEFT"`.
 - Call `kompass_pr_sync` with:
   - `refUrl: <pr-context.pr.url>`
   - `review.body`: the grade line first (for example `★★★☆☆`), followed by any non-inline notes
-  - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open or settled threads in `<pr-context.threads>` unless the new diff introduces a materially different failure mode**
+  - `review.comments`: inline comments (changed lines only) - **skip lines or concerns already covered by open threads in `<pr-context.threads>` unless the new diff introduces a materially different failure mode**
+  - Include only findings from `<eligible-findings>`
 - Never omit the grade from `review.body` in this branch
 - Do not pass any other fields
 

packages/opencode/.opencode/commands/review.md

@@ -47,11 +47,8 @@ If `<changes>.comparison` is not "uncommitted":
 ### Review Changes
 
 Following the reviewer agent guidance:
-1. Read each changed file for full context in the current session before drafting findings
-2. Analyze for bugs, security issues, and correctness problems
-3. Formulate findings ordered by impact
-4. Store the overall rating as `<star-rating>`, the top-line conclusion as `<short-verdict>`, and the severity counts as `<critical>`, `<high>`, `<medium>`, and `<low>`
-5. Store the total number of findings as `<count>`
+1. Store the overall rating as `<star-rating>`, the top-line conclusion as `<short-verdict>`, and the severity counts as `<critical>`, `<high>`, `<medium>`, and `<low>`
+2. Store the total number of findings as `<count>`
 
 While reading files:
 - Load any relevant nested `AGENTS.md` in the current session before applying review criteria