ace-review 0.54.2 → 0.55.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eddadd455f524e38373ba3e380f54408fde15a65cddcfb21d80eb7a42509239b
-  data.tar.gz: b54ad58b16b07be48c5817cdd7aeff6bad74f7f6c6c551b6c4fae55428a21ab6
+  metadata.gz: bccdbe28f93f46e3fb13b54474acd6e3f10b4b6b01e0b1259c1f9b2e3395f184
+  data.tar.gz: 6b948eea0b8a90354d71c5c233d3e2674fd550687f76d477374218d3e8abc820
 SHA512:
-  metadata.gz: 39279bea6e0d432ace854271ef27663b104cf6cda2bfe2328ae2155fb528fc0f98f36a2f2b8b4c68aa97f3dea736f707065ff4cca35c973009988a149903c35f
-  data.tar.gz: ba38ad0749fca013d2af25e591dc4c4c93a458322ffa811958a8975aec3d589bb39a8b5423491a9a815c4fa5737cf873e6631f42427176c3ec2ad8ac1f8d3626
+  metadata.gz: d4a3e6588a9e1808b086aa729062f407a4f89ff7d64269e0e4af57f8cec29933da7170388ad0ed998dbe3a504c96039d6bc4a2b9800f95638822eb3838ad78b3
+  data.tar.gz: 72153ae476b7416db5a286384c8fd2c023490ba1d3cb8a67a3b3d1f20dffc5c6ab46caa403348b54d6c84ee7511d3199436ae24870f23c4308621ea63c1f9587

data/.ace-defaults/review/presets/integration.yml

@@ -0,0 +1,11 @@
+presets:
+  - code-valid
+description: "Cross-module contracts and regression risks within a review round"
+review_role: integration
+instructions:
+  bundle:
+    sections:
+      integration_focus:
+        title: "Integration Review Focus"
+        files:
+          - "prompt://focus/phase/integration"

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.55.0] - 2026-09-24
+
+### Added
+
+- Scope complete PR diff blocks by module/lens and enforce 30k context, 30k instructions and 128k complete-input budgets without silent truncation.
+- Cache a shared goals brief by source content and instructions; include selected prior findings and resolutions as optional context.
+
+### Fixed
+
+- Preserve PR identity, task requirements, complete sources and the selected diff in the actual prompt; reject command sources in PR review context.
+- Resolve Pi model/reasoning and record actual reviewer execution identity; incomplete or empty reports do not count as completed reviews.
+- Use one agent-led workflow: at least three PR rounds, ending after two consecutive rounds without confirmed Critical/High findings. Commits do not reset review progress; there is no separate final certification.
+
 ## [0.54.2] - 2026-09-13
 
 ### Technical

data/handbook/guides/code-review-process.g.md

@@ -126,6 +126,41 @@ The project uses a structured review system that supports:
 
 Reviews are executed through standardized commands that create organized sessions with input files, prompts, model reports, and synthesis results. The system handles both general code reviews and specialized handbook reviews with appropriate templates and context.
 
+For a large monorepo PR, compose a review preset from high-level module and functional-lens presets. `file_pattern_groups` intersects its groups: a changed path must match every group's include patterns, and any matching exclusion removes it. Composition concatenates groups, while the older single `file_patterns` remains available for simple scopes. For example:
+
+```yaml
+presets:
+  admin:
+    file_pattern_groups:
+      - include: ["apps/admin/**"]
+  ui:
+    file_pattern_groups:
+      - include: ["**/*.tsx", "**/*.css"]
+        exclude: ["**/*.test.tsx"]
+  admin-ui:
+    presets: [admin, ui]
+```
+
+Select only the scopes needed for the PR. A code-only pass does not account for omitted tests; include needed code/test evidence and cross-module integration within the round. Scope manifests show selected and omitted files. ACE refuses an unparsed diff, missing sources or an oversized prompt rather than silently truncating it.
+
+The agent follows `wfi://review/pr`: minimum three completed PR rounds, ending after the last two consecutive rounds have no confirmed P0/P1 (Critical/High). Provider failures and incomplete reports do not count. Earlier open blockers remain visible; P2 and lower findings do not independently extend the loop. Changes of SHA do not reset counters and there is no additional final review or coverage certificate. Use `--evidence-session` to include selected earlier reports and finding dispositions, including reports from earlier commits. Formal merge checks remain at merge time.
+
+Presets can opt into one shared, content-addressed goals brief. Sources name an exact PR ref and authority. Only base sources may be marked accepted; head sources remain proposals. The brief includes source links and hashes, and its cache key includes source content, summary instructions and the resolved model. Prepare it once before dry runs; subsequent scoped reviews reuse the same artifact. A dry run with a cache miss fails rather than unexpectedly calling a model.
+
+```yaml
+goals_brief:
+  sources:
+    - path: docs/requirements.md
+      ref: base
+      authority: accepted
+    - path: task
+      ref: head
+      authority: proposed
+  models: ["pi:glmflash", "gemini:flash-latest"]
+```
+
+`task` resolves the single applicable PR task spec. Run `ace-review --pr 123 --preset admin-ui --prepare-goals-brief` before `--dry-run`. Model preference is configurable and unavailable providers can be replaced; the cache records which model actually generated the brief. Changing the source content or summarization contract invalidates it.
+
 ## Integration with Development Workflow
 
 ### Development Phases

data/handbook/prompts/focus/phase/integration.md

@@ -0,0 +1,3 @@
+# Cross-module integration
+
+Inspect the contracts between changed modules, including data production, publication and consumption. Check fixes and their possible regressions using the relevant code, tests and supplied prior findings. Report concrete defects with impact and evidence. Closed findings require new evidence to reopen. Integration is part of the current review round, not a separate final certification.

data/handbook/prompts/synthesize-feedback.system.md

@@ -12,6 +12,7 @@ Read all provided review reports and identify **unique actionable findings**.
 
 - **Single report**: Extract each finding with the reviewer tracked
 - **Multiple reports**: When reviewers identify the same issue, merge them into one finding and track all reviewers
+- Preserve every distinct finding, even when only one reviewer identified it. Consensus is metadata, not a filter.
 
 When merging findings from multiple reviewers:
 1. Merge them into a single finding
@@ -144,4 +145,4 @@ User input is directly interpolated into SQL.
 - **For single reports**: Extract each finding with the reviewer in the `reviewers` array
 - **For multiple reports**: Never duplicate findings - if multiple reviewers found the same issue, merge them
 - Process ALL reports thoroughly to capture ALL unique findings
-- When uncertain if two findings are the same (multiple reports), prefer merging if they affect the same code
+- When uncertain whether two findings describe the same defect, keep them separate for verification.

data/handbook/skills/as-review-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: as-review-pr
-description: Review PR and Plan Feedback
+description: Review PR through verified findings and converging rounds
 # bundle: wfi://review/pr
 # context: no-fork
 # agent: general-purpose
@@ -24,7 +24,7 @@ integration:
 assign:
   steps:
     - name: review-pr
-      description: Review code changes for correctness, style, and best practices
+      description: Review and resolve PR feedback through converging rounds
       prerequisites:
         - name: create-pr
           strength: required
@@ -32,12 +32,9 @@ assign:
       produces: [review-feedback]
       consumes: [pull-request]
       when_to_skip:
-        - "No code changes since last review"
-        - "Changes are trivial (typo fix, config update)"
+        - "No PR exists yet"
       effort: medium
       tags: [review, quality]
-      context:
-        default: fork
 skill:
   kind: workflow
   execution:

data/handbook/workflow-instructions/review/pr.wf.md

@@ -1,284 +1,50 @@
 ---
 doc-type: workflow
-title: Review PR and Plan Feedback Workflow
-purpose: Review PR and plan feedback application with comment resolution
+title: Review PR in converging rounds
+purpose: Review a PR, verify concrete findings and finish after two clean rounds
 ace-docs:
-  last-updated: 2026-03-18
-  last-checked: 2026-03-21
+  last-updated: 2026-09-24
+  last-checked: 2026-09-24
 ---
 
-# Review PR and Plan Feedback Workflow
+# Review PR
 
-## Goal
+## Goal and completion rule
 
-Review a GitHub Pull Request using ace-review, verify feedback items, and create a plan for applying the feedback. When feedback comes from PR comments, resolve those comments after implementing fixes.
+The agent runs this workflow; ACE executes individual reviews. Complete at least **3 rounds for the PR**, with the **last 2 consecutive rounds free of confirmed P0/P1 (Critical/High)**. An unresolved earlier P0/P1 remains blocking even if another reviewer does not mention it. A confirmed P0/P1 resets the clean-round streak. There is no additional final review after this rule is satisfied.
 
-## Arguments
+One round covers the PR's needed scope, including cross-module integration. A large round can use several coherent module sessions; modules do not have separate round counters. A round counts only after the needed reports have completed and the agent has verified their findings. Failed providers and incomplete reports do not count as clean rounds.
 
-- `$ARGUMENTS`: Optional PR number and/or additional flags (e.g., `123`, `--preset code-deep`, `123 --preset security`)
+Use at least one available reviewer per needed scope. Prefer the project's configured models, but preferences are not an allowlist. Honor the user's current provider/model restrictions. Record actual provider, model, reasoning and completion status. A zero process exit code alone is not a completed review.
 
-## Instructions
+## 1. Choose and prepare the scope
 
-### Step 1: Determine PR Number
+Identify the PR from the argument or `gh pr view`. Read its goal, current requirements, relevant ADRs and changed-file list. Use the smallest set of presets covering the change. Small coherent PRs can be reviewed whole; split large inputs by high-level module or functional lens, not arbitrary file chunks. Include needed contracts and code when reviewing tests and include integration behavior when modules interact.
 
-If `$ARGUMENTS` contains a PR number, use it. Otherwise, detect the current PR:
+Use `ace-review --pr <number> --preset <preset> --dry-run` to inspect the selected/omitted files, complete prompt and budget. Context and instructions each have a 30k ceiling; total input has a 128k ceiling. Change scope if too large; do not silently truncate or claim omitted code was reviewed. Generated files may use an appropriate deterministic check, recorded in the round summary, without a separate certification system.
 
-```bash
-gh pr view --json number -q '.number'
-```
+For presets with a goals brief, `--prepare-goals-brief` generates or reuses the shared summary. Its cache follows source content and instructions, not review-round state. Architectural foundations should receive design review before implementation.
 
-**Connection error retry**: If PR number detection fails due to a transient connection error (socket hangup, DNS timeout, connection reset), wait 30 seconds and retry up to 2 times. Only treat authentication errors (401/403) and not-found errors (404) as immediate failures.
+## 2. Run a round and verify findings
 
-### Step 2: Run PR Review
+Run `ace-review --pr <number> --preset <preset> --auto-execute` for the needed scopes. Pass selected previous sessions with `--evidence-session <path>` when useful. Earlier commit SHAs are expected: prior reports provide context and dispositions, not current-code certificates. Supply a short summary of fixes and outstanding issues through the preset context when it is more useful than full reports.
 
-**Always use `--pr` flag.** Append any additional parameters from `$ARGUMENTS`:
+First-round review looks for concrete defects against the agreed requirements. Subsequent rounds check fixes, regressions, unresolved issues and the integration affected by changes. They may report newly evidenced defects, but should not redesign the solution or reopen a closed finding without new evidence.
 
-```bash
-# If PR number provided in arguments:
-ace-review --pr <pr-number> [additional-flags]
+Verify reports against code and requirements. Use `ace-review-feedback list --session <path>`, `show`, `verify` and `resolve` to preserve findings and dispositions. Distinguish defects, architectural decisions and optional improvements. A single reviewer's valid finding matters; do not discard it for lack of consensus. Severity is verified by the agent, not accepted just because the model assigned it.
 
-# If no PR number, use detected PR:
-ace-review --pr $(gh pr view --json number -q '.number') [additional-flags]
-```
+Fix confirmed P0/P1 and run appropriate tests. Verify P2 and lower findings, fix those within the task or defer with rationale; they do not independently require another round. Do not expand the PR to implement speculative improvements. If the same blocker recurs without an effective fix, diagnose the cause or request the needed product/architecture decision instead of repeating the same review.
 
-**Examples:**
-- `ace-bundle wfi://review/pr` with `123` → `ace-review --pr 123`
-- `ace-bundle wfi://review/pr` with `--preset code-deep` → `ace-review --pr <current-pr> --preset code-deep`
-- `ace-bundle wfi://review/pr` with `123 --preset security` → `ace-review --pr 123 --preset security`
+## 3. Record progress and finish
 
-**Important for Claude Code**: Run with 15-minute timeout (900000ms) and wait for completion inline (not background). Review typically takes 3-5 minutes.
+Keep a short `rounds.md` in the existing PR review artifacts under `.ace-local/review/`: completed round number, report paths and scopes, confirmed P0/P1, dispositions, tests, open blockers and consecutive clean rounds. Preserve this record across agent restarts. Commits, squash and rebase do not reset the total or clean-round counters. Report SHAs are diagnostic; materially changed code receives the relevant review, not an automatic restart of every scope.
 
-#### Execution Guard (Mandatory)
+Examples:
 
-- Completion is defined by **process exit** (success or failure), not by partial output.
-- Do **not** treat temporary silence/no new output as completion.
-- Do **not** run any Step 3+ commands until Step 2 process exit is confirmed.
-- If 15-minute timeout (900000ms) is reached, report timeout and last observed output, then stop dependent steps.
+- P1 → clean → clean: finish after round 3.
+- clean → clean → clean: finish after round 3.
+- P1 → clean → P1 → clean → clean: finish after round 5.
+- An incomplete attempt does not increment either counter and cannot hide an outstanding blocker.
+- A round that finds a confirmed P1 is not clean even if it is fixed immediately afterward.
 
-Wait for the review process to exit. Note the session directory path from the output.
-
-The review includes:
-- LLM model reviews (e.g., `review-gemini.md`, `review-gpt4.md`)
-- Developer feedback from PR comments (`review-dev-feedback.md`) - if the PR has comments
-- Feedback items in `feedback/` directory
-
-### Step 3: List Feedback Items
-
-List the feedback items extracted from the review:
-
-```bash
-ace-review-feedback list --status draft
-```
-
-**Precondition**: Run this step only after Step 2 process exit is confirmed.
-
-When session ambiguity is possible, use explicit session path from Step 2:
-
-```bash
-ace-review-feedback list --status draft --session <session-dir-from-step-2>
-```
-
-This shows all draft feedback items with their IDs, severity, summaries, and sources (LLM or Developer).
-
-#### Understanding Feedback Context
-
-Feedback items are **session-scoped**. The `feedback list` command discovers items based on:
-1. Explicit `--session <path>` flag (if provided)
-2. `.ace-review-session` cache file in current directory (auto-created after reviews)
-
-If `feedback list` returns empty after a review, first verify Step 2 process completion.
-The session may not be linked to current context.
-Use `ace-review-feedback list --session <session-dir>` to list from a specific session:
-
-```bash
-# List feedback from a specific session (path shown in review output)
-ace-review-feedback list --session .ace-local/review/sessions/review-8p2pk3
-```
-
-### Step 4: Verify Each Feedback Item
-
-For each feedback item (prioritize Critical and High severity):
-
-```bash
-# Read the finding details
-ace-review-feedback show {id}
-```
-
-**Note which items come from Developer Feedback** - these are from PR comments and should be resolved after implementation.
-
-**Then verify in the codebase:**
-
-1. **Check the claim** - Use grep/read to verify the issue exists:
-   - If claim is "X doesn't exist" → `grep -rn "class X" lib/`
-   - If claim is "method missing" → check the actual file
-   - If claim is "file not deleted" → `ls path/to/file`
-
-2. **Mark the verification result:**
-
-   ```bash
-   # If issue is confirmed (valid finding)
-   ace-review-feedback verify {id} --valid --research "Confirmed: issue exists at line X"
-
-   # If issue is not real (false positive)
-   ace-review-feedback verify {id} --invalid --research "False positive: handled by Y"
-   ```
-
-3. **Categorization guide:**
-
-   | Result | Command | When |
-   |--------|---------|------|
-   | ✅ VALID | `--valid` | Issue confirmed in code |
-   | ❌ INVALID | `--invalid` | **False positive** - claim is factually incorrect |
-   | ✅ DONE | `feedback resolve {id}` | Already fixed in this PR |
-   | ⏭️ SKIP | `verify --skip --research "Design: ..."` | **Correct finding**, but not being fixed |
-   | 📋 DEFER | `verify --skip --research "Tracked in task XXX"` | Important, but not this PR (create task first) |
-
-   **Key distinction:**
-   - `verify --invalid`: The finding is **wrong** (false positive)
-     - "Code doesn't exist" → Actually exists
-     - "Missing validation" → Exists elsewhere
-     - "Fails in CI" → Doesn't run in CI
-   - `verify --skip`: The finding is **correct**, but you're not fixing it
-     - Design decision: Intentional choice
-     - Deferred: Tracking in separate task
-
-   **Before skipping**: Always verify the issue still exists by reading the code. Never skip with "out of scope" - either it's a design decision or it should be tracked in a task.
-
-**Example verification:**
-```bash
-# Claim: "TaskPatternExtractor is undefined"
-grep -rn "class TaskPatternExtractor" ace-git/lib/
-# Result: Found at ace-git/lib/ace/git/atoms/task_pattern_extractor.rb:10
-ace-review-feedback verify {id} --invalid --research "Class exists at ace-git/lib/ace/git/atoms/task_pattern_extractor.rb:10"
-```
-
-**Skip verification for:**
-- Low priority items (verify only if time permits)
-- Documentation-only suggestions
-- Style/formatting recommendations
-- Developer Feedback items (these are human-verified)
-
-### Step 5: List Pending Items
-
-After verification, list items ready to work on:
-
-```bash
-ace-review-feedback list --status pending
-```
-
-This shows only verified valid items that need fixing.
-
-### Step 6: Apply Priority Threshold
-
-**Default behavior**: Implement **Medium and higher** severity items (skip Low).
-
-This means:
-- 🔴 Critical → Implement
-- 🟡 High → Implement
-- 🟢 Medium → Implement
-- 🔵 Low → Skip (unless explicitly requested)
-
-### Step 7: Implement Fixes
-
-**CRITICAL: Every fix MUST be marked as resolved before moving to next item.**
-
-For each pending item:
-
-1. **Read the full details:**
-   ```bash
-   ace-review-feedback show {id}
-   ```
-
-2. **Implement the fix** based on the recommendation
-
-3. **IMMEDIATELY mark as resolved** (do NOT skip this step):
-   ```bash
-   ace-review-feedback resolve {id} --resolution "Fixed: <description>"
-   ```
-
-4. **Commit the fix** with a clear message referencing the feedback item
-
-5. **Note the commit SHA** for PR comment resolution (if from Developer Feedback)
-
-⚠️ **Never leave a fixed item as "pending"** - this breaks feedback tracking.
-
-### Step 8: Handle Not-Applicable Items
-
-Before skipping, complete the verification checklist:
-
-1. **Read the code** - Does the issue actually still exist?
-2. **Check current changes** - Was this already fixed in this PR?
-3. **Consider effort** - Is this a quick win (< 5 min) that should just be done?
-
-For items that won't be fixed in this PR:
-
-```bash
-# Design decision - intentionally this way
-ace-review-feedback verify {id} --skip --research "Design: uses polling for simplicity"
-
-# Important but deferred - ALWAYS create/reference a task
-ace-review-feedback verify {id} --skip --research "Tracked in task 253"
-```
-
-**Never skip with "out of scope"** - either:
-- It's a design decision (explain why)
-- It needs a follow-up task (create one and reference it)
-
-### Step 9: Resolve PR Comments (for Developer Feedback items)
-
-After implementing fixes for items sourced from **Developer Feedback**:
-
-1. **Reply to the PR with commit reference**:
-   ```bash
-   gh pr comment $ARGUMENTS --body "Fixed in $(git rev-parse --short HEAD)"
-   ```
-
-2. **Resolve review threads** (if feedback was from a review thread with a thread ID):
-   ```bash
-   # For review threads (PRRT_xxx IDs from review-dev-feedback.md)
-   gh api graphql -f query='
-     mutation {
-       resolveReviewThread(input: {threadId: "PRRT_xxx"}) {
-         thread { isResolved }
-       }
-     }
-   '
-   ```
-
-Note: The thread IDs are included in `review-dev-feedback.md` in the format `(thread: PRRT_xxx)` or `(comment: IC_xxx)`.
-
-### Comment Resolution Summary
-
-| Feedback Source | Resolution Action |
-|-----------------|-------------------|
-| LLM Review | No action needed (not a PR comment) |
-| Developer Feedback (issue comment) | Reply with commit reference |
-| Developer Feedback (review thread) | Reply with commit reference AND resolve thread |
-
-## Quick Reference
-
-```bash
-# Feedback commands
-ace-review-feedback list                      # All feedback
-ace-review-feedback list --status draft       # Unverified items
-ace-review-feedback list --status pending     # Verified valid items
-ace-review-feedback list --session <path>     # From specific session
-ace-review-feedback show {id}                 # Full item details
-ace-review-feedback verify {id} --valid       # Mark as valid
-ace-review-feedback verify {id} --invalid     # Mark as false positive
-ace-review-feedback verify {id} --skip        # Mark as skipped
-ace-review-feedback resolve {id}              # Mark as fixed
-
-# PR comment resolution
-gh pr comment $PR --body "Fixed in $(git rev-parse --short HEAD)"
-```
-
-## Output / Success Criteria
-
-- [ ] PR review completed with feedback items
-- [ ] Feedback items verified (Critical/High priority)
-- [ ] False positives marked as invalid
-- [ ] Confirmed items implemented
-- [ ] PR comments addressed with commit references
-- [ ] Review threads resolved (if applicable)
-- [ ] All items marked as resolved or skipped
+After the completion rule is met and changes have appropriate test results, update the PR description with actual reviewers, scopes, fixes, deferred findings and limitations, then mark the draft ready. Do not run a separate integration or SHA gate. Keep formal merge checks at merge time. Do not merge without explicit user authorization, post replies to people or resolve their threads without authorization. Do not make optional code changes after completion that would unnecessarily reopen review.

data/lib/ace/review/atoms/diff_boundary_finder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "strscan"
+
 module Ace
   module Review
     module Atoms
@@ -20,9 +22,7 @@ module Ace
       #   #     { path: "test/foo_test.rb", content: "diff --git...", lines: 30, change_type: :modified }
       #   #   ]
       module DiffBoundaryFinder
-        # Pattern to match the start of a file diff block
-        # Matches: diff --git a/path/to/file b/path/to/file
-        DIFF_HEADER_PATTERN = /^diff --git a\/(.+?) b\/(.+?)$/
+        DIFF_HEADER_PREFIX = "diff --git "
 
         # Pattern to detect new file mode
         NEW_FILE_PATTERN = /^new file mode/
@@ -50,7 +50,8 @@ module Ace
           current_lines = []
 
           diff_text.each_line do |line|
-            if (match = DIFF_HEADER_PATTERN.match(line))
+            if line.start_with?(DIFF_HEADER_PREFIX)
+              old_path, new_path = parse_header(line)
               # Save the previous block if exists
               if current_block
                 current_block[:content] = current_lines.join
@@ -60,10 +61,11 @@ module Ace
 
               # Start a new block
               current_block = {
-                path: match[2],  # Use the 'b/' side (destination path)
+                path: new_path,
+                old_path: old_path,
                 content: "",
                 lines: 0,
-                change_type: :modified  # Default, may be updated below
+                change_type: (old_path == new_path) ? :modified : :renamed
               }
               current_lines = [line]
             elsif current_block
@@ -88,6 +90,44 @@ module Ace
           blocks
         end
 
+        def self.parse_header(line)
+          paths = line.delete_prefix(DIFF_HEADER_PREFIX).strip
+          if !paths.start_with?('"') && (match = /\Aa\/(.+?) b\/(.+)\z/.match(paths))
+            return [match[1], match[2]]
+          end
+
+          scanner = StringScanner.new(paths)
+          old_path = scan_git_path(scanner)
+          raise ArgumentError, "Unparseable git diff header" unless scanner.skip(/\s+/)
+
+          new_path = scan_git_path(scanner)
+          unless scanner.eos? && old_path&.start_with?("a/") && new_path&.start_with?("b/")
+            raise ArgumentError, "Unparseable git diff header"
+          end
+
+          [old_path.delete_prefix("a/"), new_path.delete_prefix("b/")]
+        end
+        private_class_method :parse_header
+
+        def self.scan_git_path(scanner)
+          if (quoted = scanner.scan(/"(?:\\.|[^"])*"/))
+            decode_git_quoted(quoted[1...-1])
+          else
+            scanner.scan(/\S+/)
+          end
+        end
+        private_class_method :scan_git_path
+
+        def self.decode_git_quoted(value)
+          escapes = {"n" => "\n", "t" => "\t", "r" => "\r", "b" => "\b", "f" => "\f",
+                     "v" => "\v", "a" => "\a", "\\" => "\\", '"' => '"'}
+          value.b.gsub(/\\([0-7]{3}|.)/m) do
+            code = Regexp.last_match(1)
+            code.match?(/\A[0-7]{3}\z/) ? [code.to_i(8)].pack("C") : escapes.fetch(code, code)
+          end.force_encoding(Encoding::UTF_8)
+        end
+        private_class_method :decode_git_quoted
+
         # Parse and return just the file paths from a diff
         #
         # @param diff_text [String, nil] The unified diff text to parse
@@ -111,7 +151,7 @@ module Ace
         def self.file_count(diff_text)
           return 0 if diff_text.nil? || diff_text.empty?
 
-          diff_text.scan(DIFF_HEADER_PATTERN).length
+          diff_text.each_line.count { |line| line.start_with?(DIFF_HEADER_PREFIX) }
         end
 
         # Group file blocks by directory

data/lib/ace/review/atoms/prompt_budget.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "token_estimator"
+require_relative "context_limit_resolver"
+
+module Ace
+  module Review
+    module Atoms
+      # Checks the complete rendered prompt before any model receives it.
+      # An over-budget packet must be respecified as a coherent review scope;
+      # silently truncating a diff cannot produce a complete review.
+      module PromptBudget
+        DEFAULT_INPUT_LIMIT = 128_000
+        DEFAULT_SYSTEM_LIMIT = 30_000
+        DEFAULT_CONTEXT_LIMIT = 30_000
+        OUTPUT_RESERVE = 8_192
+        ESTIMATE_SAFETY_FACTOR = 1.25
+
+        def self.check(system_prompt:, user_prompt:, models:, config: {}, subject: nil, instruction_tokens: nil)
+          settings = config || {}
+          input_limit = integer_limit(settings, "input_max_tokens", DEFAULT_INPUT_LIMIT)
+          raise ArgumentError, "input_max_tokens cannot exceed 128000" if input_limit > DEFAULT_INPUT_LIMIT
+          system_limit = integer_limit(settings, "system_max_tokens", DEFAULT_SYSTEM_LIMIT)
+          raise ArgumentError, "system_max_tokens cannot exceed 30000" if system_limit > DEFAULT_SYSTEM_LIMIT
+          context_limit = integer_limit(settings, "context_max_tokens", DEFAULT_CONTEXT_LIMIT)
+          raise ArgumentError, "context_max_tokens cannot exceed 30000" if context_limit > DEFAULT_CONTEXT_LIMIT
+          system_tokens = conservative_estimate(system_prompt)
+          user_tokens = conservative_estimate(user_prompt)
+          total_tokens = system_tokens + user_tokens
+          # The context ceiling covers all non-diff user input, including
+          # instructions that also have their own ceiling. A proposed preset
+          # cannot relabel project documents as instructions to evade it.
+          context_tokens = subject ? [user_tokens - conservative_estimate(subject), 0].max : nil
+
+          errors = []
+          all_instruction_tokens = system_tokens + instruction_tokens.to_i
+          errors << "review instructions ~#{all_instruction_tokens} tokens exceeds #{system_limit}" if all_instruction_tokens > system_limit
+          errors << "non-diff review context ~#{context_tokens} tokens exceeds #{context_limit}" if context_tokens && context_tokens > context_limit
+          errors << "complete prompt ~#{total_tokens} tokens exceeds #{input_limit}" if total_tokens > input_limit
+
+          eligible_models = []
+          ineligible_models = {}
+          Array(models).each do |model|
+            limits = ContextLimitResolver.resolve_details(model)
+            reserve = [limits.respond_to?(:output_limit) ? limits.output_limit.to_i : 0, OUTPUT_RESERVE].max
+            available = limits.context_limit - reserve
+            if total_tokens > available
+              ineligible_models[model] = available
+            else
+              eligible_models << model
+            end
+          end
+          if Array(models).any? && eligible_models.empty?
+            errors << "complete prompt ~#{total_tokens} tokens exceeds every configured model input allowance: #{ineligible_models.map { |model, allowance| "#{model}=#{allowance}" }.join(", ")}"
+          end
+
+          {success: errors.empty?, errors: errors, system_tokens: system_tokens,
+           user_tokens: user_tokens, total_tokens: total_tokens, input_limit: input_limit,
+           context_tokens: context_tokens, context_limit: context_limit,
+           instruction_tokens: all_instruction_tokens,
+           eligible_models: eligible_models, ineligible_models: ineligible_models}
+        end
+
+        def self.conservative_estimate(text)
+          (TokenEstimator.estimate(text) * ESTIMATE_SAFETY_FACTOR).ceil
+        end
+        private_class_method :conservative_estimate
+
+        def self.integer_limit(settings, key, default)
+          value = settings[key] || settings[key.to_sym] || default
+          raise ArgumentError, "#{key} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+          value
+        end
+        private_class_method :integer_limit
+      end
+    end
+  end
+end

data/lib/ace/review/atoms/token_estimator.rb

@@ -5,8 +5,9 @@ module Ace
     module Atoms
       # Pure function for estimating token counts from text
       #
-      # Uses a simple chars/4 heuristic which provides reasonable accuracy
-      # (typically within 20% of actual token counts) for most text types.
+      # Uses chars/4 for ASCII and counts each non-ASCII UTF-8 byte as one
+      # potential token. The latter deliberately errs high for multilingual
+      # review packets rather than letting a Unicode-heavy prompt exceed its cap.
       # This is intentionally simple and fast - actual tokenization would
       # require model-specific tokenizers which adds complexity and latency.
       #
@@ -34,7 +35,12 @@ module Ace
         def self.estimate(text)
           return 0 if text.nil? || text.empty?
 
-          (text.length.to_f / CHARS_PER_TOKEN).ceil
+          return (text.length.to_f / CHARS_PER_TOKEN).ceil if text.ascii_only?
+          return text.bytesize unless text.valid_encoding?
+
+          ascii_chars = text.each_codepoint.count { |codepoint| codepoint < 128 }
+          non_ascii_bytes = text.bytesize - ascii_chars
+          (ascii_chars.to_f / CHARS_PER_TOKEN).ceil + non_ascii_bytes
         end
 
         # Estimate token count from a file