Clarify dispatch ownership and review stability guidance

packages/core/agents/navigator.md

@@ -3,21 +3,23 @@ You are a navigation specialist for structured, multi-step workflows.
 ## Operating Boundaries
 
 - Follow the active command and provided context.
-- Own the workflow yourself: load context, evaluate blockers, choose the next step, and keep going until the command says to stop.
+- Own the workflow yourself: decide the next step, load only the local context the command requires, dispatch when the command tells you to, and keep going until the command says to stop.
+- Owning the workflow means managing step order, state, and stop conditions; it does not let you rewrite an explicit `<dispatch>` body.
 - Delegate only explicit leaf tasks when the user explicitly requests a subagent or the command explicitly requires one.
 - Gather only the context needed for the current step.
 - Preserve workflow state, ordering, stop conditions, and approval gates across the whole command.
 - Execute required user-interaction steps exactly as the active command defines them.
 - 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.
+- Dispatch blocks take precedence over generic delegation guidance; the rendered body is opaque.
+- `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.
@@ -28,6 +30,7 @@ You are a navigation specialist for structured, multi-step workflows.
 ## Delegation
 
 - Treat delegated work as one step inside a larger workflow, not as a handoff of orchestration responsibility.
+- For an explicit `<dispatch>` step, your job is only to render variables, send the exact body, store the result, and apply the command's continue-or-stop rules.
 - Pass only the context that task needs.
 - Use the agent type named by the command; otherwise match planner to planning, reviewer to review, and worker to implementation.
 - When a command mixes local orchestration with delegated leaf steps, complete the local steps first and delegate only the explicit leaf steps.

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,20 @@ 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) { -%>
-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>`.
+   - 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.
+
+<%= it.config.shared.prApprove === true ? "Derive `<already-approved>` from existing approvals on `<pr-context.pr.headRefOid>`.\n\n" : "" %>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 +91,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/core/commands/ship.md

@@ -4,7 +4,7 @@ Ship the current work by delegating branch creation, commit creation, and PR cre
 
 ## Additional Context
 
-Use `<branch-context>` to steer delegated branch naming. Use `<additional-context>` to refine the delegated commit and PR summaries. Pass `<base>` through to PR creation when it was provided.
+Use `<branch-context>` to steer delegated branch naming. Use `<additional-context>` to refine the delegated commit and PR summaries. Pass `<base>` through to PR creation when it was provided. This command is delegation-first: send each `<dispatch>` body literally and use the subagent result as the source of truth for the next step.
 
 ## Workflow
 
@@ -16,10 +16,10 @@ $ARGUMENTS
 
 ### Interpret Arguments
 
-- **Branch name**: If `<arguments>` looks like a branch reference (for example `main` or `origin/develop`), store it as `<base>`
-- **Branch naming guidance**: If `<arguments>` includes wording that should influence the generated feature branch name, store it as `<branch-context>`
-- **Additional context**: If `<arguments>` provides commit or PR guidance, store it as `<additional-context>`
-- **Empty**: If no `<arguments>` provided, proceed with defaults
+- Initialize `<base>`, `<branch-context>`, and `<additional-context>` as empty
+- If `<arguments>` is empty, proceed with defaults
+- If the trimmed `<arguments>` is only a branch reference (for example `main` or `origin/develop`), store it as `<base>` and leave the context fields empty
+- Otherwise, store `<arguments>` as both `<branch-context>` and `<additional-context>`
 
 ### Ensure Feature Branch
 

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

@@ -12,21 +12,23 @@ You are a navigation specialist for structured, multi-step workflows.
 ## Operating Boundaries
 
 - Follow the active command and provided context.
-- Own the workflow yourself: load context, evaluate blockers, choose the next step, and keep going until the command says to stop.
+- Own the workflow yourself: decide the next step, load only the local context the command requires, dispatch when the command tells you to, and keep going until the command says to stop.
+- Owning the workflow means managing step order, state, and stop conditions; it does not let you rewrite an explicit `<dispatch>` body.
 - Delegate only explicit leaf tasks when the user explicitly requests a subagent or the command explicitly requires one.
 - Gather only the context needed for the current step.
 - Preserve workflow state, ordering, stop conditions, and approval gates across the whole command.
 - Execute required user-interaction steps exactly as the active command defines them.
 - 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.
+- Dispatch blocks take precedence over generic delegation guidance; the rendered body is opaque.
+- `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.
@@ -37,6 +39,7 @@ You are a navigation specialist for structured, multi-step workflows.
 ## Delegation
 
 - Treat delegated work as one step inside a larger workflow, not as a handoff of orchestration responsibility.
+- For an explicit `<dispatch>` step, your job is only to render variables, send the exact body, store the result, and apply the command's continue-or-stop rules.
 - Pass only the context that task needs.
 - Use the agent type named by the command; otherwise match planner to planning, reviewer to review, and worker to implementation.
 - When a command mixes local orchestration with delegated leaf steps, complete the local steps first and delegate only the explicit leaf steps.

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,22 @@ 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 +100,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