overkill 0.3.0__tar.gz → 0.4.1__tar.gz

{overkill-0.3.0 → overkill-0.4.1}/.github/workflows/publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: "3.12"
 

{overkill-0.3.0 → overkill-0.4.1}/.github/workflows/test.yml

@@ -14,9 +14,9 @@ jobs:
         python-version: ["3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -30,4 +30,4 @@ jobs:
         run: uv run mypy src
 
       - name: Pytest
-        run: uv run pytest
+        run: uv run pytest --cov=mr_overkill --cov-report=term-missing --cov-fail-under=70

{overkill-0.3.0 → overkill-0.4.1}/AGENTS.md

@@ -9,7 +9,7 @@
 
 ## Pull Request Rules
 
-Every PR must pass the review loop (`review-loop.sh --dry-run`) before merging. No exceptions. We eat our own dog food — if Mr. Overkill can't approve it, neither can you.
+Every PR must pass the review loop (`overkill review-loop --dry-run`) before merging. No exceptions. We eat our own dog food — if Mr. Overkill can't approve it, neither can you.
 
 ## Branch Rules
 

{overkill-0.3.0 → overkill-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overkill
-Version: 0.3.0
+Version: 0.4.1
 Summary: AI-powered code review loop — automates Codex review + Claude fix cycles
 Project-URL: Repository, https://github.com/modocai/mr-overkill
 Project-URL: Issues, https://github.com/modocai/mr-overkill/issues
@@ -392,12 +392,7 @@ uv run mypy src/
 ## Testing
 
 ```bash
-# Python tests
 uv run pytest --tb=short
-
-# Bash integration tests (requires bats-core)
-brew install bats-core       # one-time setup
-bats test/                   # run all tests
 ```
 
 ## License

{overkill-0.3.0 → overkill-0.4.1}/README.md

@@ -370,12 +370,7 @@ uv run mypy src/
 ## Testing
 
 ```bash
-# Python tests
 uv run pytest --tb=short
-
-# Bash integration tests (requires bats-core)
-brew install bats-core       # one-time setup
-bats test/                   # run all tests
 ```
 
 ## License

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/claude-refactor-full.prompt.md

@@ -35,11 +35,11 @@ You are a refactoring advisor analyzing an entire codebase for **architecture-le
 
 ```json
 {
-  "title": "[P1] Invert dependency: review-loop.sh hardcodes AI provider details",
-  "body": "Currently `bin/review-loop.sh` directly calls OpenAI/Claude APIs with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a `lib/ai-provider.sh` interface with `call_ai()` that encapsulates provider selection, API calls, and retries. `review-loop.sh` calls only `call_ai()` and doesn't know which provider is behind it.\n\n**Rollback**: If `lib/ai-provider.sh` causes issues, revert the single file and restore inline calls — the orchestration logic in review-loop.sh doesn't change.",
+  "title": "[P1] Invert dependency: loop_engine hardcodes AI provider details",
+  "body": "Currently `src/mr_overkill/loop_engine.py` directly calls AI CLI tools with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a Protocol-based `AIProvider` interface with `call()` that encapsulates provider selection, API calls, and retries. `loop_engine.py` calls only the Protocol and doesn't know which provider is behind it.\n\n**Rollback**: If the Protocol abstraction causes issues, revert the single file and restore inline calls — the orchestration logic in loop_engine.py doesn't change.",
   "confidence_score": 0.8,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 150, "end": 220} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 150, "end": 220} }
 }
 ```
 
@@ -51,7 +51,7 @@ You are a refactoring advisor analyzing an entire codebase for **architecture-le
   "body": "The codebase would benefit from separating concerns into Model-View-Controller layers for better organization.",
   "confidence_score": 0.5,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
 }
 ```
 Why this is bad: no concrete impact statement, no evidence of current pain, suggests a pattern without demonstrating need, no phased migration.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/claude-refactor-layer.prompt.md

@@ -35,11 +35,11 @@ You are a refactoring advisor analyzing an entire codebase for **layer-level** (
 
 ```json
 {
-  "title": "[P1] Unify error exit pattern across all bin/ scripts",
-  "body": "Error exits are handled 3 different ways:\n1. `bin/review-loop.sh` uses `die()` (lines 25-28) which logs to stderr and exits 1\n2. `bin/refactor-suggest.sh` uses `log_error` + bare `exit 1` (lines 88, 142, 201)\n3. `bin/apply-fix.sh` calls `echo \"ERROR: ...\" >&2` directly (lines 33, 67)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared `die()` that includes cleanup would prevent resource leaks across all scripts.",
+  "title": "[P1] Unify error handling pattern across orchestration modules",
+  "body": "Error handling is done 3 different ways:\n1. `src/mr_overkill/review_loop.py` raises `SystemExit` (lines 30-35) with stderr logging\n2. `src/mr_overkill/refactor_suggest.py` uses `logger.error` + bare `sys.exit(1)` (lines 88, 142, 201)\n3. `src/mr_overkill/retry.py` raises `RuntimeError` directly (lines 45, 78)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared exception hierarchy with cleanup hooks would prevent resource leaks across all modules.",
   "confidence_score": 0.85,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 25, "end": 28} }
+  "code_location": { "file_path": "src/mr_overkill/review_loop.py", "line_range": {"start": 30, "end": 35} }
 }
 ```
 
@@ -51,7 +51,7 @@ You are a refactoring advisor analyzing an entire codebase for **layer-level** (
   "body": "The codebase could benefit from more consistent error handling patterns.",
   "confidence_score": 0.5,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
 }
 ```
 Why this is bad: no specific examples of inconsistency, no file/line citations, doesn't explain why a coordinated change is needed.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/claude-refactor-micro.prompt.md

@@ -37,10 +37,10 @@ You are a refactoring advisor analyzing an entire codebase for **micro-level** i
 ```json
 {
   "title": "[P1] Extract duplicated validation into shared helper in process_input()",
-  "body": "Lines 42-58 and 103-119 of `bin/review-loop.sh` contain identical input validation logic (same 3 conditions, same error messages). Extracting into a `validate_input()` function eliminates the duplication and ensures future validation changes are applied consistently.",
+  "body": "Lines 55-70 and 130-145 of `src/mr_overkill/loop_engine.py` contain identical iteration-result validation logic (same 3 conditions, same error messages). Extracting into a `_validate_iteration()` helper eliminates the duplication and ensures future validation changes are applied consistently.",
   "confidence_score": 0.9,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 42, "end": 58} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 55, "end": 70} }
 }
 ```
 
@@ -52,7 +52,7 @@ You are a refactoring advisor analyzing an entire codebase for **micro-level** i
   "body": "This code could benefit from the Strategy pattern for better flexibility.",
   "confidence_score": 0.5,
   "priority": 3,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 200} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 200} }
 }
 ```
 Why this is bad: vague, no specific code reference, no measurable benefit, suggests an architecture-level change.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/claude-refactor-module.prompt.md

@@ -35,10 +35,10 @@ You are a refactoring advisor analyzing an entire codebase for **module-level**
 ```json
 {
   "title": "[P1] Extract repeated JSON validation into shared validate_json()",
-  "body": "The same jq-based JSON validation logic appears in `bin/review-loop.sh` (lines 120-135), `bin/refactor-suggest.sh` (lines 45-60), and `bin/apply-fix.sh` (lines 30-42). All three copies check for valid JSON, extract `.findings`, and handle parse errors — but the error messages have already diverged (review-loop prints to stderr, the others use `log_error`). Extracting to `lib/json-utils.sh:validate_json()` eliminates the duplication and unifies error handling.",
+  "body": "The same JSON validation logic appears in `src/example/ingest.py` (lines 12-27), `src/example/export.py` (lines 50-65), and `src/example/validate.py` (lines 8-20). All three copies parse review JSON, extract `findings`, and handle parse errors — but the error messages have already diverged. Extracting to `src/example/json_utils.py:parse_review_json()` eliminates the duplication and unifies error handling.",
   "confidence_score": 0.85,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 120, "end": 135} }
+  "code_location": { "file_path": "src/example/ingest.py", "line_range": {"start": 12, "end": 27} }
 }
 ```
 
@@ -50,7 +50,7 @@ You are a refactoring advisor analyzing an entire codebase for **module-level**
   "body": "Several files handle errors similarly. Consider creating a shared error handler.",
   "confidence_score": 0.6,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 500} }
+  "code_location": { "file_path": "src/mr_overkill/review_loop.py", "line_range": {"start": 1, "end": 500} }
 }
 ```
 Why this is bad: doesn't specify which files, doesn't cite line numbers, doesn't explain what's duplicated or how copies have diverged.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/codex-refactor-full.prompt.md

@@ -35,11 +35,11 @@ You are a refactoring advisor analyzing an entire codebase for **architecture-le
 
 ```json
 {
-  "title": "[P1] Invert dependency: review-loop.sh hardcodes AI provider details",
-  "body": "Currently `bin/review-loop.sh` directly calls OpenAI/Claude APIs with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a `lib/ai-provider.sh` interface with `call_ai()` that encapsulates provider selection, API calls, and retries. `review-loop.sh` calls only `call_ai()` and doesn't know which provider is behind it.\n\n**Rollback**: If `lib/ai-provider.sh` causes issues, revert the single file and restore inline calls — the orchestration logic in review-loop.sh doesn't change.",
+  "title": "[P1] Invert dependency: loop_engine hardcodes AI provider details",
+  "body": "Currently `src/mr_overkill/loop_engine.py` directly calls AI CLI tools with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a Protocol-based `AIProvider` interface with `call()` that encapsulates provider selection, API calls, and retries. `loop_engine.py` calls only the Protocol and doesn't know which provider is behind it.\n\n**Rollback**: If the Protocol abstraction causes issues, revert the single file and restore inline calls — the orchestration logic in loop_engine.py doesn't change.",
   "confidence_score": 0.8,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 150, "end": 220} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 150, "end": 220} }
 }
 ```
 
@@ -51,7 +51,7 @@ You are a refactoring advisor analyzing an entire codebase for **architecture-le
   "body": "The codebase would benefit from separating concerns into Model-View-Controller layers for better organization.",
   "confidence_score": 0.5,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
 }
 ```
 Why this is bad: no concrete impact statement, no evidence of current pain, suggests a pattern without demonstrating need, no phased migration.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/codex-refactor-layer.prompt.md

@@ -35,11 +35,11 @@ You are a refactoring advisor analyzing an entire codebase for **layer-level** (
 
 ```json
 {
-  "title": "[P1] Unify error exit pattern across all bin/ scripts",
-  "body": "Error exits are handled 3 different ways:\n1. `bin/review-loop.sh` uses `die()` (lines 25-28) which logs to stderr and exits 1\n2. `bin/refactor-suggest.sh` uses `log_error` + bare `exit 1` (lines 88, 142, 201)\n3. `bin/apply-fix.sh` calls `echo \"ERROR: ...\" >&2` directly (lines 33, 67)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared `die()` that includes cleanup would prevent resource leaks across all scripts.",
+  "title": "[P1] Unify error handling pattern across orchestration modules",
+  "body": "Error handling is done 3 different ways:\n1. `src/mr_overkill/review_loop.py` raises `SystemExit` (lines 30-35) with stderr logging\n2. `src/mr_overkill/refactor_suggest.py` uses `logger.error` + bare `sys.exit(1)` (lines 88, 142, 201)\n3. `src/mr_overkill/retry.py` raises `RuntimeError` directly (lines 45, 78)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared exception hierarchy with cleanup hooks would prevent resource leaks across all modules.",
   "confidence_score": 0.85,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 25, "end": 28} }
+  "code_location": { "file_path": "src/mr_overkill/review_loop.py", "line_range": {"start": 30, "end": 35} }
 }
 ```
 
@@ -51,7 +51,7 @@ You are a refactoring advisor analyzing an entire codebase for **layer-level** (
   "body": "The codebase could benefit from more consistent error handling patterns.",
   "confidence_score": 0.5,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 700} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
 }
 ```
 Why this is bad: no specific examples of inconsistency, no file/line citations, doesn't explain why a coordinated change is needed.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/codex-refactor-micro.prompt.md

@@ -37,10 +37,10 @@ You are a refactoring advisor analyzing an entire codebase for **micro-level** i
 ```json
 {
   "title": "[P1] Extract duplicated validation into shared helper in process_input()",
-  "body": "Lines 42-58 and 103-119 of `bin/review-loop.sh` contain identical input validation logic (same 3 conditions, same error messages). Extracting into a `validate_input()` function eliminates the duplication and ensures future validation changes are applied consistently.",
+  "body": "Lines 55-70 and 130-145 of `src/mr_overkill/loop_engine.py` contain identical iteration-result validation logic (same 3 conditions, same error messages). Extracting into a `_validate_iteration()` helper eliminates the duplication and ensures future validation changes are applied consistently.",
   "confidence_score": 0.9,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 42, "end": 58} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 55, "end": 70} }
 }
 ```
 
@@ -52,7 +52,7 @@ You are a refactoring advisor analyzing an entire codebase for **micro-level** i
   "body": "This code could benefit from the Strategy pattern for better flexibility.",
   "confidence_score": 0.5,
   "priority": 3,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 200} }
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 200} }
 }
 ```
 Why this is bad: vague, no specific code reference, no measurable benefit, suggests an architecture-level change.

{overkill-0.3.0 → overkill-0.4.1}/prompts/active/codex-refactor-module.prompt.md

@@ -35,10 +35,10 @@ You are a refactoring advisor analyzing an entire codebase for **module-level**
 ```json
 {
   "title": "[P1] Extract repeated JSON validation into shared validate_json()",
-  "body": "The same jq-based JSON validation logic appears in `bin/review-loop.sh` (lines 120-135), `bin/refactor-suggest.sh` (lines 45-60), and `bin/apply-fix.sh` (lines 30-42). All three copies check for valid JSON, extract `.findings`, and handle parse errors — but the error messages have already diverged (review-loop prints to stderr, the others use `log_error`). Extracting to `lib/json-utils.sh:validate_json()` eliminates the duplication and unifies error handling.",
+  "body": "The same JSON validation logic appears in `src/example/ingest.py` (lines 12-27), `src/example/export.py` (lines 50-65), and `src/example/validate.py` (lines 8-20). All three copies parse review JSON, extract `findings`, and handle parse errors — but the error messages have already diverged. Extracting to `src/example/json_utils.py:parse_review_json()` eliminates the duplication and unifies error handling.",
   "confidence_score": 0.85,
   "priority": 1,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 120, "end": 135} }
+  "code_location": { "file_path": "src/example/ingest.py", "line_range": {"start": 12, "end": 27} }
 }
 ```
 
@@ -50,7 +50,7 @@ You are a refactoring advisor analyzing an entire codebase for **module-level**
   "body": "Several files handle errors similarly. Consider creating a shared error handler.",
   "confidence_score": 0.6,
   "priority": 2,
-  "code_location": { "file_path": "bin/review-loop.sh", "line_range": {"start": 1, "end": 500} }
+  "code_location": { "file_path": "src/mr_overkill/review_loop.py", "line_range": {"start": 1, "end": 500} }
 }
 ```
 Why this is bad: doesn't specify which files, doesn't cite line numbers, doesn't explain what's duplicated or how copies have diverged.

overkill-0.4.1/prompts/active/gemini-refactor-full.prompt.md

@@ -0,0 +1,115 @@
+You are a refactoring advisor analyzing an entire codebase for **architecture-level** redesign opportunities.
+
+## Context
+
+- **Target branch**: ${TARGET_BRANCH}
+- **Scope**: full (architecture redesign)
+- **Blast radius**: high-critical — changes may restructure the entire project
+- **Iteration**: ${ITERATION}
+- **Source files list**: ${SOURCE_FILES_PATH}
+
+## Instructions
+
+1. Read the source files list at `${SOURCE_FILES_PATH}` to see which files are in scope.
+2. Read the files and identify architecture-level refactoring opportunities — **structural problems only**:
+   - Wrong abstractions: code is organized around the wrong concepts, forcing workarounds
+   - Inverted dependencies: high-level modules depend on low-level implementation details
+   - Layer violations: business logic in presentation layer, I/O in pure-logic modules, etc.
+   - Missing architectural boundaries the codebase has outgrown not having
+   - Scalability bottlenecks baked into the current structure
+3. Each finding must have a **concrete impact statement**: explain what is currently hard or broken because of this structural problem (e.g., "Adding a new review provider requires modifying 5 files because X depends directly on Y").
+4. **Phased migration required**: Every refactoring_plan must ensure the codebase **remains functional after each step**. No "big bang" rewrites.
+5. **Rollback strategy**: Each step must note what can be reverted independently if the change causes issues.
+6. **Evidence-based only**: Do not suggest restructuring working code unless you can demonstrate a concrete cost (blocked features, recurring bugs, impossible testing). "This would be cleaner" is not sufficient justification.
+7. If this is iteration > 1, focus on whether previous refactoring was properly applied and identify any remaining opportunities.
+
+## Anti-patterns (DO NOT flag these)
+
+- Micro-optimizations (rename variable, split function) — this is micro scope
+- "Trendy" pattern adoption (rewrite in a new framework, adopt microservices) without demonstrated need
+- Suggesting patterns because they exist in other projects, not because this codebase needs them
+- Proposing changes with high blast radius but only cosmetic benefit
+- Restructuring that would break the project's existing CI/CD or deployment model without justification
+
+## Example: Good Finding
+
+```json
+{
+  "title": "[P1] Invert dependency: loop_engine hardcodes AI provider details",
+  "body": "Currently `src/mr_overkill/loop_engine.py` directly calls AI CLI tools with provider-specific logic scattered across lines 150-220, 340-380, and 450-490. This means:\n- Adding a new AI provider requires modifying 3 sections of a 700-line file\n- Testing with a mock provider is impossible without editing production code\n- Provider-specific retry/error logic is interleaved with review orchestration\n\n**Suggested structure**: Extract a Protocol-based `AIProvider` interface with `call()` that encapsulates provider selection, API calls, and retries. `loop_engine.py` calls only the Protocol and doesn't know which provider is behind it.\n\n**Rollback**: If the Protocol abstraction causes issues, revert the single file and restore inline calls — the orchestration logic in loop_engine.py doesn't change.",
+  "confidence_score": 0.8,
+  "priority": 1,
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 150, "end": 220} }
+}
+```
+
+## Example: Bad Finding (DO NOT produce)
+
+```json
+{
+  "title": "[P2] Consider adopting MVC pattern",
+  "body": "The codebase would benefit from separating concerns into Model-View-Controller layers for better organization.",
+  "confidence_score": 0.5,
+  "priority": 2,
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
+}
+```
+Why this is bad: no concrete impact statement, no evidence of current pain, suggests a pattern without demonstrating need, no phased migration.
+
+## Priority Levels
+
+- **P0** — The architecture actively prevents correctness or causes data loss.
+- **P1** — The architecture blocks important feature work or causes systematic bugs.
+- **P2** — Normal improvement: restructuring significantly improves maintainability.
+- **P3** — Strategic: long-term structural improvement.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining the structural problem, concrete impact, and migration strategy; cite files/modules>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "refactoring_plan": {
+    "scope": "full",
+    "summary": "<1-3 sentence overview of the architectural change>",
+    "estimated_files_affected": <int>,
+    "steps": [
+      {
+        "order": <int>,
+        "description": "<what to do in this phase; must leave codebase functional; include rollback note>",
+        "files": ["<file1>", "<file2>"]
+      }
+    ],
+    "estimated_blast_radius": "high-critical"
+  },
+  "overall_correctness": "needs refactoring" | "code is clean",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "refactoring_plan": {
+    "scope": "full",
+    "summary": "No refactoring needed.",
+    "estimated_files_affected": 0,
+    "steps": [],
+    "estimated_blast_radius": "none"
+  },
+  "overall_correctness": "code is clean",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}

overkill-0.4.1/prompts/active/gemini-refactor-layer.prompt.md

@@ -0,0 +1,115 @@
+You are a refactoring advisor analyzing an entire codebase for **layer-level** (cross-cutting) improvements.
+
+## Context
+
+- **Target branch**: ${TARGET_BRANCH}
+- **Scope**: layer (cross-cutting concerns across modules)
+- **Blast radius**: medium-high — changes span multiple modules or layers
+- **Iteration**: ${ITERATION}
+- **Source files list**: ${SOURCE_FILES_PATH}
+
+## Instructions
+
+1. Read the source files list at `${SOURCE_FILES_PATH}` to see which files are in scope.
+2. Read the files and identify cross-cutting refactoring opportunities:
+   - Inconsistent error handling patterns across the codebase
+   - Logging/observability concerns scattered without a clear strategy
+   - Configuration management that should be centralized
+   - Security patterns applied inconsistently (input validation, auth checks)
+   - Cross-cutting concerns (retry logic, caching, rate limiting) duplicated across layers
+3. **Consistency threshold**: Only flag an inconsistency when the same concern is implemented **3 or more different ways** across the codebase. Two slightly different approaches may be intentional.
+4. **Justify coordination**: For each finding, explain **why individual per-file fixes are insufficient** — i.e., why a coordinated cross-cutting change is needed.
+5. **Blast radius justification**: Explicitly compare the number of affected files against the improvement gained. If the ratio is unfavorable (many files changed for marginal benefit), lower the priority or skip.
+6. Each finding must be concrete and actionable — cite specific code locations across multiple files.
+7. If this is iteration > 1, focus on whether previous refactoring was properly applied and identify any remaining opportunities.
+
+## Anti-patterns (DO NOT flag these)
+
+- Architecture redesign (moving modules, changing project structure) — this is full scope
+- Single-file local improvements (renaming, splitting functions) — this is micro scope
+- Suggesting a logging framework when simple stderr output is sufficient for the project's scale
+- Proposing middleware/interceptor patterns when the codebase has < 5 files
+- Flagging minor formatting inconsistencies as cross-cutting concerns
+
+## Example: Good Finding
+
+```json
+{
+  "title": "[P1] Unify error handling pattern across orchestration modules",
+  "body": "Error handling is done 3 different ways:\n1. `src/mr_overkill/review_loop.py` raises `SystemExit` (lines 30-35) with stderr logging\n2. `src/mr_overkill/refactor_suggest.py` uses `logger.error` + bare `sys.exit(1)` (lines 88, 142, 201)\n3. `src/mr_overkill/retry.py` raises `RuntimeError` directly (lines 45, 78)\n\nThis makes it easy to miss cleanup (temp file removal) on error paths. A coordinated change to use a shared exception hierarchy with cleanup hooks would prevent resource leaks across all modules.",
+  "confidence_score": 0.85,
+  "priority": 1,
+  "code_location": { "file_path": "src/mr_overkill/review_loop.py", "line_range": {"start": 30, "end": 35} }
+}
+```
+
+## Example: Bad Finding (DO NOT produce)
+
+```json
+{
+  "title": "[P2] Improve error handling",
+  "body": "The codebase could benefit from more consistent error handling patterns.",
+  "confidence_score": 0.5,
+  "priority": 2,
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 700} }
+}
+```
+Why this is bad: no specific examples of inconsistency, no file/line citations, doesn't explain why a coordinated change is needed.
+
+## Priority Levels
+
+- **P0** — Security or reliability gap: inconsistent application of a critical concern.
+- **P1** — Systematic debt: the inconsistency actively causes bugs or makes them likely.
+- **P2** — Normal improvement: unifying a pattern improves maintainability.
+- **P3** — Nice-to-have: consistency improvement with low immediate impact.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining the problem and suggested change; cite files/lines/functions>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "refactoring_plan": {
+    "scope": "layer",
+    "summary": "<1-3 sentence overview of all proposed changes>",
+    "estimated_files_affected": <int>,
+    "steps": [
+      {
+        "order": <int>,
+        "description": "<what to do>",
+        "files": ["<file1>", "<file2>"]
+      }
+    ],
+    "estimated_blast_radius": "medium-high"
+  },
+  "overall_correctness": "needs refactoring" | "code is clean",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "refactoring_plan": {
+    "scope": "layer",
+    "summary": "No refactoring needed.",
+    "estimated_files_affected": 0,
+    "steps": [],
+    "estimated_blast_radius": "none"
+  },
+  "overall_correctness": "code is clean",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}

overkill-0.4.1/prompts/active/gemini-refactor-micro.prompt.md

@@ -0,0 +1,116 @@
+You are a refactoring advisor analyzing an entire codebase for **micro-level** improvements.
+
+## Context
+
+- **Target branch**: ${TARGET_BRANCH}
+- **Scope**: micro (function/file-level improvements)
+- **Blast radius**: low — changes are confined to individual functions or files
+- **Iteration**: ${ITERATION}
+- **Source files list**: ${SOURCE_FILES_PATH}
+
+## Instructions
+
+1. Read the source files list at `${SOURCE_FILES_PATH}` to see which files are in scope.
+2. Read the files and identify micro-level refactoring opportunities:
+   - Overly complex functions (cyclomatic complexity > 10)
+   - Functions exceeding ~50 lines that could be split into focused helpers
+   - Deeply nested logic (3+ levels of nesting)
+   - Dead code — but **only** for file-private (non-exported) symbols, and only after confirming no callers exist within the file
+   - Misleading names or unclear parameter contracts for **internal** symbols only
+   - Copy-paste duplication within a single file
+3. Each finding must be concrete and actionable — cite specific lines and explain the measurable benefit.
+4. **Scope boundary**: Do NOT suggest changes that require modifying other files. If a rename would break callers in other files, it is out of scope.
+5. Name changes apply only to file-internal (non-exported, non-public-API) symbols.
+6. If this is iteration > 1, focus on whether previous refactoring was properly applied and identify any remaining opportunities.
+
+## Anti-patterns (DO NOT flag these)
+
+- "Convert this function to a class" — this is an architecture-level change
+- Adding type annotations, docstrings, or JSDoc — this is a style preference
+- Renaming exported/public-API symbols that would require changes in other files
+- Suggesting a different framework, library, or language idiom with no measurable benefit
+- Flagging functions under 30 lines as "too long"
+- Suggesting extraction when the resulting helper would only be called once
+
+## Example: Good Finding
+
+```json
+{
+  "title": "[P1] Extract duplicated validation into shared helper in process_input()",
+  "body": "Lines 55-70 and 130-145 of `src/mr_overkill/loop_engine.py` contain identical iteration-result validation logic (same 3 conditions, same error messages). Extracting into a `_validate_iteration()` helper eliminates the duplication and ensures future validation changes are applied consistently.",
+  "confidence_score": 0.9,
+  "priority": 1,
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 55, "end": 70} }
+}
+```
+
+## Example: Bad Finding (DO NOT produce)
+
+```json
+{
+  "title": "[P3] Consider using a design pattern",
+  "body": "This code could benefit from the Strategy pattern for better flexibility.",
+  "confidence_score": 0.5,
+  "priority": 3,
+  "code_location": { "file_path": "src/mr_overkill/loop_engine.py", "line_range": {"start": 1, "end": 200} }
+}
+```
+Why this is bad: vague, no specific code reference, no measurable benefit, suggests an architecture-level change.
+
+## Priority Levels
+
+- **P0** — Correctness risk: the current code has a latent bug or data-loss path.
+- **P1** — Readability blocker: the function is effectively unreviewable.
+- **P2** — Normal improvement: measurably simplifies the code.
+- **P3** — Nice-to-have: minor naming or style improvement.
+
+## Output Format
+
+Output **only** valid JSON matching this schema exactly. Do NOT wrap in markdown fences or add any text outside the JSON.
+
+{
+  "findings": [
+    {
+      "title": "<P-tag + imperative description, max 80 chars>",
+      "body": "<Markdown explaining the problem and suggested change; cite files/lines/functions>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3>,
+      "code_location": {
+        "file_path": "<repo-relative file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "refactoring_plan": {
+    "scope": "micro",
+    "summary": "<1-3 sentence overview of all proposed changes>",
+    "estimated_files_affected": <int>,
+    "steps": [
+      {
+        "order": <int>,
+        "description": "<what to do>",
+        "files": ["<file1>", "<file2>"]
+      }
+    ],
+    "estimated_blast_radius": "low"
+  },
+  "overall_correctness": "needs refactoring" | "code is clean",
+  "overall_explanation": "<1-3 sentence justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+
+If there are no findings, return:
+
+{
+  "findings": [],
+  "refactoring_plan": {
+    "scope": "micro",
+    "summary": "No refactoring needed.",
+    "estimated_files_affected": 0,
+    "steps": [],
+    "estimated_blast_radius": "none"
+  },
+  "overall_correctness": "code is clean",
+  "overall_explanation": "<brief justification>",
+  "overall_confidence_score": <float 0.0-1.0>
+}