overkill 0.8.2__tar.gz → 0.9.0__tar.gz

{overkill-0.8.2 → overkill-0.9.0}/.overkillrc.example

@@ -17,6 +17,9 @@
 # Enable auto-commit of fixes (default: true)
 # AUTO_COMMIT=true
 
+# Push the review/* branch created by --commit (default: false — stays local)
+# COMMIT_SCOPE_PUSH=false
+
 # CI trigger policy for iteration commits (default: last-only)
 #   last-only — append "[skip ci]" to each iteration commit; push a single
 #               empty "chore: trigger CI" commit only when the loop ends

{overkill-0.8.2 → overkill-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: overkill
-Version: 0.8.2
+Version: 0.9.0
 Summary: AI-powered code review loop — automates Codex/Gemini review + Claude fix cycles
 Project-URL: Repository, https://github.com/modocai/mr-overkill
 Project-URL: Issues, https://github.com/modocai/mr-overkill/issues
@@ -117,14 +117,31 @@ overkill refactor-suggest -n 1 --dry-run
 overkill review-loop [OPTIONS]
 
 Options:
-  -t, --target <branch>    Target branch to diff against (default: develop)
+  -t, --target <rev>       Target to diff against (default: develop). Accepts any
+                           git revision, not just a branch name: a SHA, a tag, or
+                           HEAD~5 all work, so you can review "everything since
+                           commit X" without opening a PR. A revision that moves
+                           with HEAD is pinned to a SHA when the run starts, so
+                           the loop's own fix commits cannot shrink the range.
+  --commit <rev>           Review an already-merged commit instead of the branch
+                           diff. Creates a review/<sha>-<ts> branch off HEAD and
+                           applies fixes there; no PR is created. <rev> is a single
+                           commit — ranges are not supported. Excludes -t.
+  --push                   Push the auto-created review branch (default: local only)
+  --wip                    Include uncommitted working-tree changes in the review.
+                           With commits enabled they are parked in a scaffolding
+                           commit that is unwound when the run finishes, so no
+                           commit is left behind either way. Excludes --commit.
   -n, --max-loop <N>       Maximum review-fix iterations (required, unless --resume)
   --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
   --no-self-review         Disable self-review (equivalent to --max-subloop 0)
   --dry-run                Run review only, do not fix
   --no-auto-commit         Fix but do not commit/push (single iteration)
   --resume                 Resume from a previously interrupted run (reuses existing logs)
-  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --fix-nits               Also flag nits and style issues during self-review
+  --context <text>         Additional context for the reviewer (design intent,
+                           constraints)
+  --reviewer-backend <be>  Reviewer backend: claude|codex|gemini (default: codex)
   --ci-trigger-mode <m>    CI trigger policy: every|last-only|none (default: last-only).
                            'last-only' tags each iteration commit with [skip ci]
                            and pushes a single empty trigger commit on PASS —
@@ -142,8 +159,108 @@ Examples:
   overkill review-loop --resume              # resume an interrupted run
   overkill review-loop -n 2 --reviewer-backend claude  # use Claude as reviewer
   overkill review-loop -n 10 --ci-trigger-mode last-only  # CI fires once on PASS
+
+  # Review only what landed after a given commit, before opening a PR
+  overkill review-loop -t abc123 -n 3
+  overkill review-loop -t "$(git merge-base origin/develop HEAD)" -n 3
+
+  # Improve a commit that is already merged
+  overkill review-loop --commit abc123 -n 1 --dry-run   # report only, no branch
+  overkill review-loop --commit abc123 -n 3             # fix on a review/* branch
+
+  # Review work you have not committed yet
+  overkill review-loop --wip -n 1 --dry-run   # report only, nothing touched
+  overkill review-loop --wip -n 3             # fix it, still uncommitted at the end
+```
+
+### Reviewing an already-merged commit
+
+`--commit` exists for the case the branch diff cannot express: a change that
+already landed, which you now want to improve.
+
+1. The commit's diff is written to `.overkill/logs/scope.diff`. It is computed
+   against the commit's **first parent**, so merge commits produce a real patch
+   — `git show` prints nothing for those.
+2. A `review/<sha>-<timestamp>` branch is created off your current HEAD and the
+   fixes are committed there. The branch stays local unless you pass `--push`,
+   and no PR is created or commented on.
+3. The reviewer treats `scope.diff` as *scope only*. Since other commits may
+   have landed since, it must confirm each finding against the file's current
+   contents and cite current line numbers.
+
+Run it from a clean, up-to-date checkout of the branch the commit lives on:
+
+```bash
+git switch main && git pull
+overkill review-loop --commit abc123 -n 3
 ```
 
+**After upgrading, re-run `overkill init`** in each repo — `--commit` and
+`--wip` need the `${REVIEW_SCOPE_NOTE}` marker that the refreshed review prompts
+carry, and the run aborts with an explanatory error if it is missing. Note that
+`init` overwrites `.overkill/prompts/active/`, so back up any customised prompts
+first.
+
+### Reviewing work you have not committed yet
+
+Without `--wip` the review scope is `git diff <target>...<current>` — committed
+work only. A dirty tree is rejected outright, and under `--dry-run` it is
+silently left out of scope. `--wip` pulls it in.
+
+How it gets there depends on whether the run is allowed to commit:
+
+| Command | Mechanism | Iterations | Commits left behind |
+|---|---|---|---|
+| `--wip --dry-run` | worktree diff written to `.overkill/logs/wip.diff` | 1 (review only) | none |
+| `--wip --no-auto-commit` | same | 1 | none |
+| `--wip` | scaffolding commit, unwound at the end | up to `-n` | none |
+
+Both paths end the same way: your working tree is dirty again, with the fixes
+applied on top of your own edits. Only the iteration count differs. Multiple
+iterations need commits because the loop detects convergence from the commit
+graph, so `--wip` parks your work in a throwaway commit, lets the loop run
+against it unchanged, and then removes the scaffolding with
+`git reset --mixed`.
+
+```bash
+overkill review-loop --wip -n 3
+git diff                              # your work plus the fixes, uncommitted
+cat .overkill/logs/wip-fixes.diff     # just what the loop changed
+```
+
+Worth knowing before you use it:
+
+- **Nothing is ever pushed** in `--wip` mode, and no PR is commented on. This is
+  not configurable — the scaffolding commit holds unfinished work.
+- **`git add -A` sweeps in anything `.gitignore` does not cover.** The file list
+  is printed before the scaffolding commit is made. Nothing is pushed and the
+  commit is unwound, but check the list if you keep untracked secrets around.
+- **A staged/unstaged split does not survive.** `git reset --mixed` leaves
+  everything unstaged.
+- **If the run is interrupted the scaffolding stays.** The command to undo it is
+  printed at the start and the base commit is saved to
+  `.overkill/logs/wip-base.txt`; `--wip --resume` picks an interrupted run back
+  up, parking the work again if the scaffolding is already gone. A run that
+  already finished is left alone. Resume needs commits enabled — the other two
+  modes are a single pass with nothing to resume. A *fresh* `--wip` run refuses
+  to start on top of leftover scaffolding rather than nest a second commit on
+  it, which would strand the earlier draft on the branch — including when the
+  scaffolding sits behind fix commits the interrupted run already made. A
+  resume refuses too if you have committed normally on top of it, because
+  unwinding would rewind that commit into uncommitted changes.
+- **A resumed run's `wip-fixes.diff` only covers the iterations after the
+  resume.** Re-parking folds the earlier attempt's fixes in with your own work,
+  so they cannot be told apart again; that attempt's diff is kept beside it as
+  `wip-fixes-<sha>.diff`.
+- **Commit hooks are skipped** for the run's own commits. Work in progress
+  routinely fails hooks it will pass once finished, and every commit `--wip`
+  makes is torn down again.
+- **An unfinished merge, rebase, cherry-pick or revert blocks the mode.** The
+  scaffolding commit would conclude the operation, and unwinding would then
+  reset past it.
+- **New files are included.** They are staged as intent-to-add so the reviewer
+  can see them, then unstaged again.
+
 ## Usage: overkill refactor-suggest
 
 Unlike `review-loop` which reviews diffs, `refactor-suggest` analyzes the **entire codebase** for refactoring opportunities at a chosen scope level.
@@ -164,7 +281,7 @@ Options:
   --resume                 Resume from a previously interrupted run (reuses existing logs)
   --with-review            Run review-loop after PR creation (default: 4 iterations)
   --with-review-loops <N>  Set review-loop iteration count (implies --with-review)
-  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --reviewer-backend <be>  Reviewer backend: claude|codex|gemini (default: codex)
   --diagnostic-log         Save full Claude event stream to sidecar files
   --no-budget-gate         Skip token-budget checks and run regardless
                            (same as OVERKILL_SKIP_BUDGET=1)

{overkill-0.8.2 → overkill-0.9.0}/README.md

@@ -94,14 +94,31 @@ overkill refactor-suggest -n 1 --dry-run
 overkill review-loop [OPTIONS]
 
 Options:
-  -t, --target <branch>    Target branch to diff against (default: develop)
+  -t, --target <rev>       Target to diff against (default: develop). Accepts any
+                           git revision, not just a branch name: a SHA, a tag, or
+                           HEAD~5 all work, so you can review "everything since
+                           commit X" without opening a PR. A revision that moves
+                           with HEAD is pinned to a SHA when the run starts, so
+                           the loop's own fix commits cannot shrink the range.
+  --commit <rev>           Review an already-merged commit instead of the branch
+                           diff. Creates a review/<sha>-<ts> branch off HEAD and
+                           applies fixes there; no PR is created. <rev> is a single
+                           commit — ranges are not supported. Excludes -t.
+  --push                   Push the auto-created review branch (default: local only)
+  --wip                    Include uncommitted working-tree changes in the review.
+                           With commits enabled they are parked in a scaffolding
+                           commit that is unwound when the run finishes, so no
+                           commit is left behind either way. Excludes --commit.
   -n, --max-loop <N>       Maximum review-fix iterations (required, unless --resume)
   --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
   --no-self-review         Disable self-review (equivalent to --max-subloop 0)
   --dry-run                Run review only, do not fix
   --no-auto-commit         Fix but do not commit/push (single iteration)
   --resume                 Resume from a previously interrupted run (reuses existing logs)
-  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --fix-nits               Also flag nits and style issues during self-review
+  --context <text>         Additional context for the reviewer (design intent,
+                           constraints)
+  --reviewer-backend <be>  Reviewer backend: claude|codex|gemini (default: codex)
   --ci-trigger-mode <m>    CI trigger policy: every|last-only|none (default: last-only).
                            'last-only' tags each iteration commit with [skip ci]
                            and pushes a single empty trigger commit on PASS —
@@ -119,8 +136,108 @@ Examples:
   overkill review-loop --resume              # resume an interrupted run
   overkill review-loop -n 2 --reviewer-backend claude  # use Claude as reviewer
   overkill review-loop -n 10 --ci-trigger-mode last-only  # CI fires once on PASS
+
+  # Review only what landed after a given commit, before opening a PR
+  overkill review-loop -t abc123 -n 3
+  overkill review-loop -t "$(git merge-base origin/develop HEAD)" -n 3
+
+  # Improve a commit that is already merged
+  overkill review-loop --commit abc123 -n 1 --dry-run   # report only, no branch
+  overkill review-loop --commit abc123 -n 3             # fix on a review/* branch
+
+  # Review work you have not committed yet
+  overkill review-loop --wip -n 1 --dry-run   # report only, nothing touched
+  overkill review-loop --wip -n 3             # fix it, still uncommitted at the end
+```
+
+### Reviewing an already-merged commit
+
+`--commit` exists for the case the branch diff cannot express: a change that
+already landed, which you now want to improve.
+
+1. The commit's diff is written to `.overkill/logs/scope.diff`. It is computed
+   against the commit's **first parent**, so merge commits produce a real patch
+   — `git show` prints nothing for those.
+2. A `review/<sha>-<timestamp>` branch is created off your current HEAD and the
+   fixes are committed there. The branch stays local unless you pass `--push`,
+   and no PR is created or commented on.
+3. The reviewer treats `scope.diff` as *scope only*. Since other commits may
+   have landed since, it must confirm each finding against the file's current
+   contents and cite current line numbers.
+
+Run it from a clean, up-to-date checkout of the branch the commit lives on:
+
+```bash
+git switch main && git pull
+overkill review-loop --commit abc123 -n 3
 ```
 
+**After upgrading, re-run `overkill init`** in each repo — `--commit` and
+`--wip` need the `${REVIEW_SCOPE_NOTE}` marker that the refreshed review prompts
+carry, and the run aborts with an explanatory error if it is missing. Note that
+`init` overwrites `.overkill/prompts/active/`, so back up any customised prompts
+first.
+
+### Reviewing work you have not committed yet
+
+Without `--wip` the review scope is `git diff <target>...<current>` — committed
+work only. A dirty tree is rejected outright, and under `--dry-run` it is
+silently left out of scope. `--wip` pulls it in.
+
+How it gets there depends on whether the run is allowed to commit:
+
+| Command | Mechanism | Iterations | Commits left behind |
+|---|---|---|---|
+| `--wip --dry-run` | worktree diff written to `.overkill/logs/wip.diff` | 1 (review only) | none |
+| `--wip --no-auto-commit` | same | 1 | none |
+| `--wip` | scaffolding commit, unwound at the end | up to `-n` | none |
+
+Both paths end the same way: your working tree is dirty again, with the fixes
+applied on top of your own edits. Only the iteration count differs. Multiple
+iterations need commits because the loop detects convergence from the commit
+graph, so `--wip` parks your work in a throwaway commit, lets the loop run
+against it unchanged, and then removes the scaffolding with
+`git reset --mixed`.
+
+```bash
+overkill review-loop --wip -n 3
+git diff                              # your work plus the fixes, uncommitted
+cat .overkill/logs/wip-fixes.diff     # just what the loop changed
+```
+
+Worth knowing before you use it:
+
+- **Nothing is ever pushed** in `--wip` mode, and no PR is commented on. This is
+  not configurable — the scaffolding commit holds unfinished work.
+- **`git add -A` sweeps in anything `.gitignore` does not cover.** The file list
+  is printed before the scaffolding commit is made. Nothing is pushed and the
+  commit is unwound, but check the list if you keep untracked secrets around.
+- **A staged/unstaged split does not survive.** `git reset --mixed` leaves
+  everything unstaged.
+- **If the run is interrupted the scaffolding stays.** The command to undo it is
+  printed at the start and the base commit is saved to
+  `.overkill/logs/wip-base.txt`; `--wip --resume` picks an interrupted run back
+  up, parking the work again if the scaffolding is already gone. A run that
+  already finished is left alone. Resume needs commits enabled — the other two
+  modes are a single pass with nothing to resume. A *fresh* `--wip` run refuses
+  to start on top of leftover scaffolding rather than nest a second commit on
+  it, which would strand the earlier draft on the branch — including when the
+  scaffolding sits behind fix commits the interrupted run already made. A
+  resume refuses too if you have committed normally on top of it, because
+  unwinding would rewind that commit into uncommitted changes.
+- **A resumed run's `wip-fixes.diff` only covers the iterations after the
+  resume.** Re-parking folds the earlier attempt's fixes in with your own work,
+  so they cannot be told apart again; that attempt's diff is kept beside it as
+  `wip-fixes-<sha>.diff`.
+- **Commit hooks are skipped** for the run's own commits. Work in progress
+  routinely fails hooks it will pass once finished, and every commit `--wip`
+  makes is torn down again.
+- **An unfinished merge, rebase, cherry-pick or revert blocks the mode.** The
+  scaffolding commit would conclude the operation, and unwinding would then
+  reset past it.
+- **New files are included.** They are staged as intent-to-add so the reviewer
+  can see them, then unstaged again.
+
 ## Usage: overkill refactor-suggest
 
 Unlike `review-loop` which reviews diffs, `refactor-suggest` analyzes the **entire codebase** for refactoring opportunities at a chosen scope level.
@@ -141,7 +258,7 @@ Options:
   --resume                 Resume from a previously interrupted run (reuses existing logs)
   --with-review            Run review-loop after PR creation (default: 4 iterations)
   --with-review-loops <N>  Set review-loop iteration count (implies --with-review)
-  --reviewer-backend <be>  Reviewer backend: claude|codex (default: codex)
+  --reviewer-backend <be>  Reviewer backend: claude|codex|gemini (default: codex)
   --diagnostic-log         Save full Claude event stream to sidecar files
   --no-budget-gate         Skip token-budget checks and run regardless
                            (same as OVERKILL_SKIP_BUDGET=1)

{overkill-0.8.2 → overkill-0.9.0}/prompts/active/claude-review.prompt.md

@@ -1,5 +1,5 @@
 You are a code reviewer analyzing a proposed change.
-
+${REVIEW_SCOPE_NOTE}
 ## Context
 
 - **Current branch**: ${CURRENT_BRANCH}

{overkill-0.8.2 → overkill-0.9.0}/prompts/active/codex-review.prompt.md

@@ -1,5 +1,5 @@
 You are a code reviewer analyzing a proposed change.
-
+${REVIEW_SCOPE_NOTE}
 ## Context
 
 - **Current branch**: ${CURRENT_BRANCH}

{overkill-0.8.2 → overkill-0.9.0}/prompts/active/gemini-review.prompt.md

@@ -1,5 +1,5 @@
 You are a code reviewer analyzing a proposed change.
-
+${REVIEW_SCOPE_NOTE}
 ## Context
 
 - **Current branch**: ${CURRENT_BRANCH}

{overkill-0.8.2 → overkill-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "overkill"
-version = "0.8.2"
+version = "0.9.0"
 description = "AI-powered code review loop — automates Codex/Gemini review + Claude fix cycles"
 readme = "README.md"
 license = { text = "MIT" }

{overkill-0.8.2 → overkill-0.9.0}/src/mr_overkill/agents.py

@@ -16,6 +16,7 @@ from abc import ABC, abstractmethod
 from importlib.resources import as_file, files
 from pathlib import Path
 
+from mr_overkill import commit_scope, wip_scope
 from mr_overkill.budget import SKIP_BUDGET_ENV_VAR, budget_gate_disabled
 from mr_overkill.budget.claude import claude_budget_sufficient
 from mr_overkill.budget.codex import codex_budget_sufficient
@@ -47,6 +48,211 @@ def _format_reviewer_context(raw: str) -> str:
     return f"## Author Context\n\n{raw}"
 
 
+_SCOPE_NOTE_MARKER = "${REVIEW_SCOPE_NOTE}"
+
+
+# Shared by both WIP mechanisms: the code under review is a draft, and the
+# reviewer has to be told so or it will report the draft-ness as the defect.
+# Neither mechanism hands over the draft alone: both artefacts also carry the
+# author's own committed work on this branch, and that is finished code.  So the
+# subject names the draft portion and each caller carves the rest out.
+def _wip_draft_calibration(subject: str) -> str:
+    """Draft-vs-defect calibration, scoped to *subject*."""
+    return f"""
+### This work is unfinished
+
+{subject} has not been committed by the author, so judge it as a **draft**:
+
+- Do flag defects in what is actually written — bugs, unsafe assumptions, \
+resource leaks, debug statements or credentials left behind.
+- Do **not** flag incompleteness itself. A half-implemented feature, a missing \
+test for code still being written, or a function that is clearly the next thing \
+the author will fill in is not a finding.
+"""
+
+
+# The no-commit WIP mechanism leaves the author's draft uncommitted, so the
+# self-review diff — ``git diff HEAD`` over the files the fixer touched — carries
+# the draft alongside the fix.  Unsaid, the self-reviewer reads the draft as the
+# fixer's work: it reports the incompleteness, or calls the draft scope creep and
+# the re-fix reverts work that exists nowhere but the working tree.
+def _wip_self_review_note(scope_diff: Path) -> str:
+    """Draft-vs-fix separation for the no-commit self-reviewer."""
+    return f"""
+
+### The diff also contains the author's uncommitted draft
+
+Nothing was committed before the fix, so the diff file shows the author's own work \
+in progress as well as the fix. The draft as it stood **before any fix ran** was \
+captured at `{scope_diff}`, so anything already written there is the author's rather \
+than the fix. That capture was taken against a different base — match it by content, \
+not by line number — and where a hunk mixes the two, the findings above say which \
+part is the fix.
+
+- Judge **only the fix**. Hunks that belong to the author's draft are out of scope.
+- Do **not** report the draft's incompleteness, and do **not** report it as scope \
+creep or ask for it to be reverted — it is not the fixer's work, and reverting it \
+would destroy uncommitted work.
+"""
+
+
+def _format_wip_scope(config: LoopConfig) -> str:
+    """Build the WIP-scope override block for whichever mechanism is in play."""
+    if config.scope_diff_file is not None:
+        # No-commit run: the branch diff shows only committed work, so it is
+        # actively misleading here — the scope artefact is the whole truth.
+        return f"""
+> **REVIEW MODE: UNCOMMITTED WORK — read this first. It overrides the framing \
+in the line above and re-scopes the Instructions below.**
+
+The change under review is the author's **uncommitted working tree**, captured \
+in full at `{config.scope_diff_file}`. Read that file first.
+
+**Ignore the `git diff` command in the Instructions section.** It compares two \
+commits, so it shows only the part of the work that happens to be committed \
+already — reviewing it would silently skip everything the author is actually \
+working on.
+
+The scope diff was taken from the working tree as it exists right now, so its \
+paths and line numbers are **current** and you may cite them directly.
+
+It runs from this branch's fork point with `{config.target_branch}`, so it also \
+contains commits the author already made here. `git diff \
+{config.target_branch}...HEAD` prints exactly that committed portion — it is in \
+scope too, but it is finished code, so the draft allowance below does not apply \
+to it.
+{_wip_draft_calibration("The uncommitted part of the change under review")}"""
+
+    # Scaffolding-commit run: the branch diff is exactly right, but the
+    # scaffolding commit's message would otherwise read as the change under
+    # review, and it sits on top of whatever the author has already committed
+    # on this branch rather than at the bottom of the diff.
+    return f"""
+> **REVIEW MODE: UNCOMMITTED WORK — read this first.**
+
+The commit on this branch whose message is `{wip_scope.SCAFFOLD_MESSAGE}` is not a \
+change the author wrote a commit for. It is their **uncommitted work**, parked in \
+a throwaway commit so that it can be reviewed and so that fixes have somewhere to \
+land. It will be unwound when this run finishes. Review it exactly as if the \
+author had committed it deliberately — it is the change under review.
+
+Commits **before** it are the author's own committed work on this branch. They are \
+in scope too, but they are finished code, so the draft allowance below does not \
+apply to them. Commits **after** it are fixes an earlier iteration of this loop \
+already applied.
+{_wip_draft_calibration("The work parked in that commit")}"""
+
+
+def _format_review_scope(config: LoopConfig, iteration: int) -> str:
+    """Build the scope override block, or "" in normal branch-diff mode.
+
+    Empty-string-means-no-section, like ``EXTRA_REVIEW_GUIDELINES`` in the
+    self-review prompt.  Note ``string.Template`` does not substitute
+    recursively, so every value here is interpolated in Python.
+    """
+    sha = config.scope_commit
+    if not sha:
+        return _format_wip_scope(config) if config.wip else ""
+
+    diff_path = config.scope_diff_file
+    ancestry = ""
+    if not commit_scope.is_ancestor_of_head(sha):
+        ancestry = (
+            f"\n> WARNING: `{sha[:7]}` is **not an ancestor of HEAD**. Much of the "
+            "code it touched may not exist in the working tree at all. Report only "
+            "defects you can locate in a file that exists right now.\n"
+        )
+
+    if iteration <= 1:
+        fixes = (
+            "None yet — this is the first pass. The `git diff` command in the "
+            "Instructions section will print **nothing** on this iteration. That is "
+            "expected, it is not an error, and it is **not** the change under review."
+        )
+    else:
+        fixes = (
+            f"This is iteration {iteration}. Earlier iterations already produced fix "
+            "commits on this branch, and the `git diff` command in the Instructions "
+            "section prints **those fixes** — not the change under review. Use it to "
+            "(a) confirm which of your earlier findings are now resolved — **never "
+            "re-report a resolved finding** — and (b) look for new defects the fixes "
+            "themselves introduced.\n\nIf every earlier finding is resolved and you "
+            'find nothing new, return zero findings and `"patch is correct"`.'
+        )
+
+    return f"""
+> **REVIEW MODE: COMMIT SCOPE — read this first. It overrides the framing in the \
+line above and re-scopes the Instructions and Review Guidelines below.**
+
+You are **not** reviewing a proposed change. You are reviewing a change that was \
+**already merged**:
+
+- **Commit under review**: {commit_scope.commit_headline(sha)}
+- **Its diff**: `{diff_path}`
+{ancestry}
+Read that diff file first. Do **not** try to reconstruct it with `git show` or \
+`git diff` — it has already been generated correctly for you, including for merge \
+commits (where `git show` prints nothing at all).
+
+### The scope diff is historical — the code has moved on
+
+Other commits have landed since. A line number, a function, or a whole file in the \
+scope diff may no longer exist, may have been renamed, or may already have been fixed.
+
+1. Use the scope diff **only** to decide *what is in scope*: which files and which \
+behaviour the commit touched.
+2. **The current contents of the working tree are the sole authority on whether a \
+defect exists.** Before reporting anything, open the current file and confirm the \
+defect is still there. If the current code already handles it, drop the finding.
+3. Every `code_location` must be a **current** path with **current** line numbers, \
+verified by reading the file. Line numbers copied from the scope diff will be wrong.
+4. If a file in the scope diff no longer exists, skip it.
+
+### Reading the guidelines below
+
+Wherever a guideline says "this diff", read it as "the change made by \
+`{sha[:7]}`, as it manifests in the code as it exists right now". The requirement \
+that the issue be **introduced by this diff** still holds: do not flag pre-existing \
+problems, and do not flag problems introduced by *later* commits.
+
+### Fixes already applied on this branch
+
+{fixes}
+"""
+
+
+def _review_prompt_vars(config: LoopConfig, iteration: int) -> dict[str, str]:
+    """Template variables shared by all three review prompts."""
+    return {
+        "CURRENT_BRANCH": config.current_branch,
+        "TARGET_BRANCH": config.target_branch,
+        "ITERATION": str(iteration),
+        "REVIEWER_CONTEXT": _format_reviewer_context(config.reviewer_context),
+        "REVIEW_SCOPE_NOTE": _format_review_scope(config, iteration),
+    }
+
+
+def _render_review_prompt(
+    prompt_file: Path, config: LoopConfig, iteration: int
+) -> str | None:
+    """Render a review prompt, or ``None`` if it cannot be used.
+
+    In a scoped mode a prompt that predates the feature would silently drop the
+    scope note and have the reviewer inspect the wrong diff — which reads as
+    "no findings" rather than as a failure.  Refuse instead.
+    """
+    raw = prompt_file.read_text(encoding="utf-8")
+    if (config.scope_commit or config.wip) and _SCOPE_NOTE_MARKER not in raw:
+        logger.error(
+            "Prompt %s predates scoped review support (no %s marker). "
+            "Run 'overkill init' to refresh the prompt templates.",
+            prompt_file,
+            _SCOPE_NOTE_MARKER,
+        )
+        return None
+    return string.Template(raw).safe_substitute(_review_prompt_vars(config, iteration))
+
+
 # ── Review schema (single source of truth for structured output) ─────
 
 
@@ -217,15 +423,9 @@ class CodexReviewAgent(ReviewAgent):
             logger.error("Review prompt not found: %s", prompt_file)
             return False
 
-        tmpl = string.Template(
-            prompt_file.read_text(encoding="utf-8")
-        )
-        prompt_text = tmpl.safe_substitute({
-            "CURRENT_BRANCH": config.current_branch,
-            "TARGET_BRANCH": config.target_branch,
-            "ITERATION": str(iteration),
-            "REVIEWER_CONTEXT": _format_reviewer_context(config.reviewer_context),
-        })
+        prompt_text = _render_review_prompt(prompt_file, config, iteration)
+        if prompt_text is None:
+            return False
 
         if not self._budget_fn("codex", config.budget_scope, 0):
             raise BudgetTimeoutError(
@@ -323,15 +523,9 @@ class ClaudeReviewAgent(ReviewAgent):
             logger.error("Review prompt not found: %s", prompt_file)
             return False
 
-        tmpl = string.Template(
-            prompt_file.read_text(encoding="utf-8")
-        )
-        prompt_text = tmpl.safe_substitute({
-            "CURRENT_BRANCH": config.current_branch,
-            "TARGET_BRANCH": config.target_branch,
-            "ITERATION": str(iteration),
-            "REVIEWER_CONTEXT": _format_reviewer_context(config.reviewer_context),
-        })
+        prompt_text = _render_review_prompt(prompt_file, config, iteration)
+        if prompt_text is None:
+            return False
 
         if not self._budget_fn("claude", config.budget_scope, 0):
             raise BudgetTimeoutError(
@@ -426,15 +620,9 @@ class GeminiReviewAgent(ReviewAgent):
             logger.error("Review prompt not found: %s", prompt_file)
             return False
 
-        tmpl = string.Template(
-            prompt_file.read_text(encoding="utf-8")
-        )
-        prompt_text = tmpl.safe_substitute({
-            "CURRENT_BRANCH": config.current_branch,
-            "TARGET_BRANCH": config.target_branch,
-            "ITERATION": str(iteration),
-            "REVIEWER_CONTEXT": _format_reviewer_context(config.reviewer_context),
-        })
+        prompt_text = _render_review_prompt(prompt_file, config, iteration)
+        if prompt_text is None:
+            return False
 
         if not self._budget_fn("gemini", config.budget_scope, 0):
             raise BudgetTimeoutError(
@@ -591,6 +779,11 @@ class ClaudeSelfReviewAgent(SelfReviewAgent):
             budget_scope=config.budget_scope,
             dry_run=config.dry_run,
             fix_nits=config.fix_nits,
+            scope_note=(
+                _wip_self_review_note(config.scope_diff_file)
+                if config.wip and config.scope_diff_file is not None
+                else ""
+            ),
             original_review_json=json.loads(review_json_str),
         )