ace-review 0.55.0 → 0.56.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bccdbe28f93f46e3fb13b54474acd6e3f10b4b6b01e0b1259c1f9b2e3395f184
-  data.tar.gz: 6b948eea0b8a90354d71c5c233d3e2674fd550687f76d477374218d3e8abc820
+  metadata.gz: a3eb68d4c56fe426002098bd5d5dc10567ea5dcf92ba709069d526c9d8d4ca77
+  data.tar.gz: bdaafd88e24669a1c2beb50fd16b2daf606f56b7f07d0815a36ba28deda175a3
 SHA512:
-  metadata.gz: d4a3e6588a9e1808b086aa729062f407a4f89ff7d64269e0e4af57f8cec29933da7170388ad0ed998dbe3a504c96039d6bc4a2b9800f95638822eb3838ad78b3
-  data.tar.gz: 72153ae476b7416db5a286384c8fd2c023490ba1d3cb8a67a3b3d1f20dffc5c6ab46caa403348b54d6c84ee7511d3199436ae24870f23c4308621ea63c1f9587
+  metadata.gz: c1acb46ca00a76f48bd05e65f7b167e9bb395732a922bf848a8792fd342be10e85777e155eb6ba5675396a6021bd257fd9d3008dcc26a03656768f83931d9338
+  data.tar.gz: 23c76466b28055d2c02364e711373d2743b71684b3dcb611c2523e344c430546034af289d972c3af80d590bb221f61cef8b2d977c988d334fcd620398c1467c6

data/.ace-defaults/review/config.yml

@@ -41,21 +41,16 @@ defaults:
   gh_simple_timeout: 10  # Timeout for simple gh commands (--version, auth status)
   llm_timeout: 900  # Timeout for LLM queries in seconds (15 minutes)
 
-# Subject strategy configuration
-# Controls how large diffs are handled when they exceed model context limits
+# Review-exempt paths
+# Globs whose changed files never require a model report. A delta round
+# (--delta) touching only these paths is recorded as a no-op session with zero
+# model calls; in any round, matching paths are excluded from the review
+# subject and enumerated in the diff manifest. Patterns that match every path
+# are refused at config load.
 #
-# Strategy Types:
-# - adaptive (default): Auto-selects full or chunked based on model capabilities
-# - full: Send complete diff in single request (for large context models)
-# - chunked: Split diff at file boundaries (for smaller context models)
-#
-# Example:
-#   subject_strategy:
-#     type: adaptive      # or: full, chunked
-#     headroom: 0.15      # Reserve 15% for system prompt (default)
-#     chunking:
-#       max_tokens_per_chunk: 100000  # Max tokens per chunk
-#       include_change_summary: true  # Include file summary in each chunk
+# exempt_paths:
+#   - "CHANGELOG.md"
+#   - "**/*.golden"
 
 # Storage configuration
 # storage:

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.56.1] - 2026-09-29
+
+### Fixed
+- A full PR review round is no longer mistaken for a delta round. dry-cli yields
+  nil for an absent `--delta` and for a bare valueless `--delta`, and both were
+  normalized to auto-resolution — so the first-ever review of any new PR failed
+  with "No prior review session records a head". Nil now stays a full round;
+  auto-resolution is the explicit `--delta auto` value (explicit heads unchanged).
+- The released gemspec now declares `ace-git-github ~> 0.2`, matching the source
+  constraint: the previously published 0.56.0 metadata still pinned `~> 0.1.1`,
+  which kept published installations resolving ace-git-github 0.1.2 and made
+  the released 0.2.0 unreachable through dependency resolution.
+
+## [0.56.0] - 2026-09-27
+
+### Added
+
+- Delta review rounds for PRs: `--delta <head>` reviews only the diff since an explicit reference head, and bare `--delta` auto-resolves the reference from the most recent prior session of the same PR (recorded via `diff_manifest.head_sha`/`delta_reference_head` in session metadata). Prior-session findings are carried forward as evidence; a non-ancestor reference (rewritten history), missing prior sessions, and oversized deltas refuse with actionable messages instead of silently reviewing everything.
+- Review-exempt paths: `exempt_paths` config globs. A delta round touching only exempt paths is recorded as a no-op session with zero model calls (paths and matching patterns enumerated in the report); mixed rounds review only the non-exempt part; full rounds exclude exempt paths from the subject and list them. Patterns that match every path are refused at config load.
+
+### Removed
+
+- The unwired subject strategy surface (`SubjectStrategy`, full/chunked/adaptive strategies, `UnknownStrategyError`, and the commented `subject_strategy` config block). Oversized diffs keep failing with the explicit budget-vs-actual refusal; delta scoping is the intended answer for large PRs (ADR-024: no documented-but-unreachable configuration).
+
+### Changed
+
+- Review session usage records now reflect measured provider tokens: `LlmExecutor`/multi-model metadata record `usage` derived from provider metadata (with `usage_source` no longer pinned to "unavailable"), and no-op delta rounds record zero model calls.
+
 ## [0.55.0] - 2026-09-24
 
 ### Added

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

@@ -29,6 +29,8 @@ For presets with a goals brief, `--prepare-goals-brief` generates or reuses the
 
 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.
 
+Round N+1 does not need to re-review unchanged code. `--delta` scopes the round to the diff since the reference head recorded by the most recent prior session of that PR (`--delta <head>` names an explicit reference), carries its findings forward as evidence, and completes as a zero-model no-op session when the delta is empty. When the project config declares `exempt_paths` and a delta touches only those paths, the round is recorded as a review-exempt no-op; mixed deltas review only the non-exempt part. Full rounds are never converted into no-ops by exempt paths.
+
 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.
 
 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.

data/lib/ace/review/cli/commands/review.rb

@@ -34,6 +34,8 @@ module Ace
             "--preset code-pr             # PR code review",
             "--preset security --auto-execute  # Run and apply fixes",
             "--pr 123                      # Review by PR number",
+            "--pr 123 --delta             # Delta round since the most recent prior session's head",
+            "--pr 123 --delta <head>      # Delta round since an explicit reviewed head",
             "--preset code --subject diff:HEAD~3 --subject files:docs/**/*.md",
             "--preset security --dry-run   # Preview without executing"
           ]
@@ -61,6 +63,8 @@ module Ace
           option :post_comment, type: :boolean, desc: "Post review as PR comment (requires --pr)"
           option :gh_timeout, type: :integer, desc: "Timeout for gh CLI operations in seconds (default: 30)"
           option :evidence_session, type: :array, desc: "Include selected prior review sessions as context"
+          option :delta, type: :string, optional_value: true,
+            desc: "Delta round for --pr: review only changes since a reference head (explicit head, or `auto` to auto-resolve from the most recent prior session for this PR); omit for a full round"
           option :prepare_goals_brief, type: :boolean, desc: "Generate or reuse the shared goals brief for this PR and preset"
 
           # Standard options
@@ -145,6 +149,7 @@ module Ace
             # Handle repeatable options
             process_subjects(options)
             process_models(options)
+            process_delta(options)
 
             # Set defaults
             options[:save_session] = true unless options.key?(:save_session)
@@ -152,6 +157,25 @@ module Ace
             options
           end
 
+          # Normalize --delta: the explicit value "auto" resolves the reference
+          # head from prior sessions (:auto); any other value is the head itself.
+          # dry-cli cannot distinguish an absent --delta from a bare one (both
+          # arrive as nil), and a full round must never be mistaken for a delta
+          # round — so nil stays a full round and auto-resolution is spelled out.
+          def process_delta(options)
+            return unless options.key?(:delta)
+
+            value = options[:delta]
+            value = value.to_s.strip if value.is_a?(String)
+            options[:delta] = if value.nil? || value.empty?
+              nil
+            elsif value.casecmp("auto").zero?
+              :auto
+            else
+              value
+            end
+          end
+
           def process_subjects(options)
             return unless options[:subject]
 

data/lib/ace/review/errors.rb

@@ -138,9 +138,6 @@ module Ace
 
       # Raised when context composition fails
       class ContextComposerError < Error; end
-
-      # Raised when an unknown review strategy is requested
-      class UnknownStrategyError < Error; end
     end
   end
 end

data/lib/ace/review/models/review_options.rb

@@ -12,6 +12,7 @@ module Ace
           :pr, :post_comment, :pr_metadata, :gh_timeout,
           :pr_comments, :pr_comment_data,
           :evidence_sessions,
+          :delta,
           :no_feedback, :feedback_model,
           :list_presets, :list_prompts, :help
 
@@ -60,6 +61,10 @@ module Ace
           @pr_comment_data = nil  # Populated during execution
           @evidence_sessions = Array(hash[:evidence_session]).flat_map { |value| value.to_s.split("\x1F") }.reject(&:empty?)
 
+          # Delta round: nil = not requested, :auto = resolve reference from prior
+          # sessions, otherwise the explicit reference head
+          @delta = hash[:delta]
+
           # Feedback extraction options
           @no_feedback = hash[:no_feedback] || false
           @feedback_model = hash[:feedback_model]
@@ -89,6 +94,11 @@ module Ace
           !pr.nil? && !pr.to_s.strip.empty?
         end
 
+        # Check if a delta round was requested (--delta, with or without a head)
+        def delta_requested?
+          !delta.nil?
+        end
+
         # Check if comment posting should be triggered (includes dry-run preview)
         def should_post_comment?
           pr_review? && post_comment

data/lib/ace/review/molecules/delta_resolver.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "open3"
+require "yaml"
+
+module Ace
+  module Review
+    module Molecules
+      # Resolves and validates the reference head for a delta review round.
+      #
+      # A delta round reviews only the diff between a reference head (an earlier
+      # reviewed commit) and the PR's current head. The reference is either given
+      # explicitly or auto-resolved from the most recent prior review session of
+      # the same PR. Every failure mode fails closed: no prior session, a
+      # non-ancestor reference (e.g. rewritten history) or missing local objects
+      # refuse the round instead of falling back to a full review.
+      module DeltaResolver
+        SHA_PATTERN = /\A[0-9a-f]{40}\z/
+
+        # Resolve the reference head and compute the delta diff.
+        #
+        # @param reference [String, Symbol, nil] explicit head, or :auto to resolve
+        #   from the most recent prior session of this PR
+        # @param pr_metadata [Hash] PR metadata (requires headRefOid and url)
+        # @param project_root [String, nil] repository root for git commands
+        # @return [Hash] {success:, reference_head:, source:, session_dir:, diff:, error:}
+        def self.resolve(reference, pr_metadata, project_root: nil)
+          head = pr_metadata["headRefOid"].to_s
+          return {success: false, error: "Delta review requires the PR head SHA"} unless head.match?(SHA_PATTERN)
+
+          if reference == :auto || reference.nil?
+            session = latest_session_head(pr_metadata["url"].to_s, project_root: project_root)
+            return session unless session[:success]
+
+            reference = session[:reference_head]
+            session_dir = session[:session_dir]
+            source = :session
+          else
+            source = :explicit
+          end
+
+          resolved = rev_parse(reference, project_root: project_root)
+          return resolved unless resolved[:success]
+
+          reference_head = resolved[:stdout]
+          return {success: false, error: "Delta reference '#{reference}' is not a commit SHA"} unless reference_head.match?(SHA_PATTERN)
+          return {success: false, error: "Delta reference head #{reference_head} is not an ancestor of the current PR head #{head}; history was likely rewritten — re-run a full review round"} unless ancestor?(reference_head, head, project_root: project_root)
+
+          diff = run_git(["diff", "#{reference_head}..#{head}"], project_root: project_root)
+          return diff unless diff[:success]
+
+          {success: true, reference_head: reference_head, source: source,
+           session_dir: session_dir, diff: diff[:stdout]}
+        end
+
+        # Find the head SHA recorded by the most recent prior session of this PR.
+        #
+        # @param pr_url [String] canonical PR URL stored in session metadata
+        # @param project_root [String, nil]
+        # @return [Hash] {success:, reference_head:, session_dir:, error:}
+        def self.latest_session_head(pr_url, project_root: nil)
+          root = project_root || Dir.pwd
+          sessions_dir = File.join(root, ".ace-local", "review", "sessions")
+          return {success: false, error: no_prior_session_message(pr_url)} unless Dir.exist?(sessions_dir)
+
+          candidates = Dir.glob(File.join(sessions_dir, "review-*"))
+            .select { |path| File.directory?(path) }
+            # Order by the session's own last write (metadata.yml), not the
+            # directory entry — directory mtimes tie when sessions are created
+            # within the same second.
+            .sort_by { |path| -session_mtime(path).to_f }
+
+          candidates.each do |dir|
+            metadata_path = File.join(dir, "metadata.yml")
+            next unless File.file?(metadata_path)
+
+            metadata = YAML.safe_load_file(metadata_path, permitted_classes: [Time, Date, Symbol])
+            next unless metadata.is_a?(Hash)
+            next unless metadata["pr_url"].to_s == pr_url
+
+            head = metadata.dig("diff_manifest", "head_sha") ||
+                   metadata.dig("diff_manifest", :head_sha)
+            next unless head.to_s.match?(SHA_PATTERN)
+
+            return {success: true, reference_head: head, session_dir: dir}
+          end
+
+          {success: false, error: no_prior_session_message(pr_url)}
+        rescue Psych::Exception, Errno::ENOENT => e
+          {success: false, error: "Cannot read prior review sessions for delta resolution: #{e.message}"}
+        end
+
+        def self.session_mtime(session_dir)
+          metadata_path = File.join(session_dir, "metadata.yml")
+          File.file?(metadata_path) ? File.mtime(metadata_path) : File.mtime(session_dir)
+        end
+        private_class_method :session_mtime
+
+        def self.no_prior_session_message(pr_url)
+          "No prior review session records a head for #{pr_url}; " \
+            "run a full review round first or pass an explicit reference: --delta <head>"
+        end
+        private_class_method :no_prior_session_message
+
+        def self.rev_parse(reference, project_root:)
+          result = run_git(["rev-parse", "#{reference}^{commit}"], project_root: project_root)
+          return result unless result[:success]
+
+          result[:stdout] = result[:stdout].strip
+          result
+        end
+
+        def self.ancestor?(reference_head, head, project_root:)
+          root = project_root || Dir.pwd
+          system("git", "merge-base", "--is-ancestor", reference_head, head, chdir: root,
+            out: File::NULL, err: File::NULL)
+        end
+        private_class_method :ancestor?
+
+        def self.run_git(args, project_root:)
+          root = project_root || Dir.pwd
+          stdout, stderr, status = Open3.capture3("git", *args, chdir: root)
+          unless status.success?
+            detail = stderr.strip
+            detail = "exit #{status.exitstatus}" if detail.empty?
+            return {success: false, error: "git #{args.first} failed for delta review: #{detail}"}
+          end
+
+          {success: true, stdout: stdout}
+        end
+        private_class_method :run_git
+      end
+    end
+  end
+end

data/lib/ace/review/molecules/exempt_paths.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "subject_filter"
+
+module Ace
+  module Review
+    module Molecules
+      # Review-exempt paths: globs whose deltas never require a model report.
+      #
+      # A delta round whose changed files all match the declared patterns is
+      # recorded as a no-op session without any model call; in mixed rounds the
+      # exempt paths are excluded from the subject and enumerated. Patterns are
+      # validated at config load — a pattern that matches every path is refused
+      # instead of silently exempting the world.
+      module ExemptPaths
+        # Probe set covering root-level and nested paths. A pattern matching
+        # every probe leaves nothing reviewable by definition. Dotfiles are
+        # excluded: wildcard patterns never match them under fnmatch pathname
+        # semantics (no FNM_DOTMATCH), so they cannot prove over-breadth.
+        OVER_BROAD_PROBES = ["README.md", "a.txt", "dir/b.txt", "a/b/c.txt"].freeze
+
+        # Conventional spellings authors use for "everything". fnmatch pathname
+        # semantics make bare "*" / "**" single-segment, but their intent is
+        # unmistakable — refuse them instead of silently exempting the world.
+        CONVENTIONAL_MATCH_ALL = ["*", "**"].freeze
+
+        # @param patterns [Object] raw exempt_paths config value
+        # @return [String, nil] refusal message, or nil when valid
+        def self.validate!(patterns)
+          return nil if patterns.nil?
+
+          unless patterns.is_a?(Array) && patterns.all? { |pattern| pattern.is_a?(String) && !pattern.strip.empty? }
+            return "exempt_paths must be a list of non-empty glob strings"
+          end
+
+          patterns.each do |pattern|
+            if CONVENTIONAL_MATCH_ALL.include?(pattern) ||
+                OVER_BROAD_PROBES.all? { |probe| SubjectFilter.glob_match?(pattern, probe) }
+              return "exempt_paths pattern '#{pattern}' matches every path; refusing to exempt the world"
+            end
+          end
+          nil
+        end
+
+        # Partition changed paths (destination paths, as in the diff manifest)
+        # into exempt and non-exempt.
+        #
+        # @param paths [Array<String>]
+        # @param patterns [Array<String>, nil]
+        # @return [Hash] {exempt:, non_exempt:}
+        def self.classify(paths, patterns)
+          patterns = Array(patterns)
+          exempt, non_exempt = Array(paths).partition do |path|
+            patterns.any? { |pattern| SubjectFilter.glob_match?(pattern, path) }
+          end
+          {exempt: exempt, non_exempt: non_exempt}
+        end
+      end
+    end
+  end
+end

data/lib/ace/review/molecules/preset_manager.rb

@@ -110,6 +110,7 @@ module Ace
             reviewers: preset["reviewers"],
             file_patterns: preset["file_patterns"],
             file_pattern_groups: preset["file_pattern_groups"],
+            exempt_paths: preset["exempt_paths"],
             budget: preset["budget"],
             goals_brief: preset["goals_brief"],
             review_role: preset["review_role"] || "scope",

data/lib/ace/review/molecules/review_evidence.rb

@@ -21,7 +21,14 @@ module Ace
             if metadata["pr_url"] && metadata["pr_url"] != pr_metadata["url"]
               return {success: false, error: "#{dir} belongs to a different PR"}
             end
-            reports = Dir.glob(File.join(dir, "review-report-*.md"))
+            # Reviewer reports are written as review-report-<model>.md (Ruby API
+            # path) or review-<model>.md (CLI provider path); prompt/context and
+            # dev-feedback files are not reports.
+            reports = Dir.glob(File.join(dir, "review-*.md")).select do |path|
+              base = File.basename(path)
+              !base.end_with?(".prompt.md", ".context.md") &&
+                !%w[review-dev-feedback.md].include?(base)
+            end
             return {success: false, error: "No review report in #{dir}"} if reports.empty?
 
             lines += ["", "## #{File.basename(dir)} — #{metadata["preset"]}",

data/lib/ace/review/organisms/review_manager.rb

@@ -52,6 +52,10 @@ module Ace
           content_result = extract_review_content(config_result[:config], options)
           return content_result unless content_result[:success]
 
+          # A no-op round (empty delta, or a fully review-exempt delta) is
+          # recorded without composing prompts or calling any model.
+          return save_noop_round(session_dir, options, config_result[:config], content_result) if content_result[:noop]
+
           # Step 4: Compose prompts via ace-bundle
           prompt_result = compose_review_prompt(
             config_result[:config],
@@ -189,11 +193,21 @@ module Ace
           # Merge options with config
           options.merge_config(config)
 
+          # Review-exempt paths are validated at config load, naming the offender
+          if (exempt_error = Molecules::ExemptPaths.validate!(config[:exempt_paths]))
+            return {success: false,
+                    error: "Invalid exempt_paths in review config for preset '#{preset_name}': #{exempt_error}"}
+          end
+
           {success: true, config: config}
         end
 
         # Step 2: Extract subject and context
         def extract_review_content(config, options)
+          if options.delta_requested? && !options.pr_review?
+            return {success: false, error: "--delta requires --pr <identifier>"}
+          end
+
           # Handle PR mode
           if options.pr_review?
             return extract_pr_content(options.pr, config, options)
@@ -274,6 +288,8 @@ module Ace
 
         # Extract PR content (diff and metadata)
         def extract_pr_content(pr_identifier, config, options)
+          return extract_pr_delta_content(pr_identifier, config, options) if options.delta_requested?
+
           # Fetch PR diff and metadata
           fetch_options = options.gh_timeout ? {timeout: options.gh_timeout} : {}
           result = Ace::Review::Molecules::GhPrFetcher.fetch_pr(pr_identifier, fetch_options)
@@ -296,6 +312,8 @@ module Ace
               inventory.length == changed_files && inventory.map { |item| item["path"] }.sort == diff_files.sort
             return {success: false, error: "PR file inventory does not match the fetched diff; review input may be incomplete"}
           end
+          scoped = apply_exempt_paths(scoped, config)
+          return scoped unless scoped[:success]
           scoped[:manifest][:pr_file_inventory_verified] = true
           scoped[:manifest][:head_sha] = result[:metadata]["headRefOid"]
           scoped[:manifest][:base_branch_sha] = result[:metadata]["baseRefOid"]
@@ -341,6 +359,200 @@ module Ace
           }
         end
 
+        # Extract PR content for a delta round: only the diff between a reference
+        # head (explicit, or auto-resolved from the most recent prior session of
+        # this PR) and the current head. Fails closed on missing sessions, rewritten
+        # history, or oversized deltas. An empty delta returns a no-op round marker.
+        def extract_pr_delta_content(pr_identifier, config, options)
+          fetch_options = options.gh_timeout ? {timeout: options.gh_timeout} : {}
+          metadata_result = Molecules::GhPrFetcher.fetch_metadata(pr_identifier, fetch_options)
+          return {success: false, error: metadata_result[:error]} unless metadata_result[:success]
+
+          metadata = metadata_result[:metadata]
+          unless %w[headRefOid baseRefOid].all? { |key| metadata[key].to_s.match?(/\A[0-9a-f]{40}\z/) }
+            return {success: false, error: "Delta review requires exact head/base SHAs"}
+          end
+
+          inventory = Molecules::GhPrFetcher.fetch_file_inventory(metadata, fetch_options)
+          return {success: false, error: inventory[:error]} unless inventory[:success]
+          metadata["files"] = inventory[:files]
+
+          delta = Molecules::DeltaResolver.resolve(options.delta, metadata, project_root: @project_root || Dir.pwd)
+          return {success: false, error: delta[:error]} unless delta[:success]
+
+          options.pr_metadata = metadata
+          # Carry the reference session's findings forward as evidence; an explicit
+          # --evidence-session still merges on top.
+          if delta[:session_dir]
+            options.evidence_sessions = [delta[:session_dir], *options.evidence_sessions].uniq
+          end
+
+          manifest = {
+            head_sha: metadata["headRefOid"],
+            delta_reference_head: delta[:reference_head],
+            delta_base_head: metadata["headRefOid"],
+            delta_reference_source: delta[:source].to_s,
+            delta_scope: "delta since #{delta[:reference_head]}"
+          }
+
+          if delta[:diff].empty?
+            return {success: true, noop: true, noop_reason: :empty_delta,
+                    subject: "", context: nil, cache_dir: options.session_dir || create_cache_directory,
+                    pr_metadata: metadata, delta: delta, diff_manifest: manifest}
+          end
+
+          scoped = Molecules::DiffScope.select(delta[:diff], config[:file_patterns],
+            groups: config[:file_pattern_groups])
+          return scoped unless scoped[:success]
+
+          # Exempt-path acceptance applies to delta rounds: a delta whose files
+          # are all review-exempt is recorded as a no-op without model calls.
+          if Array(config[:exempt_paths]).any?
+            classification = Molecules::ExemptPaths.classify(scoped[:manifest][:selected_files], config[:exempt_paths])
+            if classification[:non_exempt].empty?
+              return {success: true, noop: true, noop_reason: :exempt_delta,
+                      noop_scope: "delta touches only review-exempt paths (#{classification[:exempt].join(", ")}) " \
+                        "matching patterns (#{Array(config[:exempt_paths]).join(", ")})",
+                      subject: "", context: nil, cache_dir: options.session_dir || create_cache_directory,
+                      pr_metadata: metadata, delta: delta,
+                      diff_manifest: manifest.merge(scoped[:manifest]).merge(
+                        exempt_files: classification[:exempt],
+                        exempt_patterns: Array(config[:exempt_paths]))}
+            end
+
+            scoped = apply_exempt_paths(scoped, config)
+            return scoped unless scoped[:success]
+          end
+
+          # The selected delta alone can still exceed the whole-prompt ceiling.
+          diff_tokens = (Atoms::TokenEstimator.estimate(scoped[:diff]) * Atoms::PromptBudget::ESTIMATE_SAFETY_FACTOR).ceil
+          if diff_tokens > Atoms::PromptBudget::DEFAULT_INPUT_LIMIT
+            return {success: false, error: "Review packet exceeds budget: selected delta alone ~#{diff_tokens} tokens exceeds #{Atoms::PromptBudget::DEFAULT_INPUT_LIMIT}; review the delta in coherent module/lens scopes"}
+          end
+
+          {
+            success: true,
+            subject: scoped[:diff],
+            context: format_pr_metadata(metadata),
+            cache_dir: options.session_dir || create_cache_directory,
+            pr_metadata: metadata,
+            delta: delta,
+            diff_manifest: manifest.merge(scoped[:manifest])
+          }
+        end
+
+        # Record a no-op round (empty or fully review-exempt delta) as a complete
+        # session: metadata + report, zero model calls. Prior findings are carried
+        # forward as evidence; unreadable evidence is stated, never pretended.
+        def save_noop_round(session_dir, options, config, content)
+          review_data = {
+            preset: options.preset,
+            review_role: config[:review_role],
+            pr_url: options.pr_metadata&.dig("url"),
+            evidence_sessions: options.evidence_sessions,
+            model: nil,
+            context: content[:context],
+            subject: content[:subject],
+            diff_manifest: content[:diff_manifest],
+            noop: true,
+            noop_reason: content[:noop_reason],
+            delta: content[:delta]
+          }
+
+          metadata = create_metadata(review_data).merge(
+            "noop_round" => true,
+            "noop_reason" => content[:noop_reason].to_s,
+            "delta" => content[:delta] ? {
+              "reference_head" => content[:delta][:reference_head],
+              "reference_source" => content[:delta][:source].to_s
+            } : nil
+          )
+          File.write(File.join(session_dir, "metadata.yml"), YAML.dump(metadata))
+
+          File.write(File.join(session_dir, "review.md"), render_noop_report(options, content))
+
+          {
+            success: true,
+            session_dir: session_dir,
+            output_file: File.join(session_dir, "review.md"),
+            noop: true,
+            message: "No-op review round recorded in #{session_dir} (no model calls)"
+          }
+        end
+
+        def render_noop_report(options, content)
+          delta = content[:delta]
+          lines = []
+          lines << "---"
+          lines << "noop_round: true"
+          lines << "noop_reason: #{content[:noop_reason]}"
+          if delta
+            lines << "delta_reference_head: #{delta[:reference_head]}"
+            lines << "delta_reference_source: #{delta[:source]}"
+          end
+          lines << "pr_url: #{options.pr_metadata&.dig("url")}"
+          lines << "timestamp: #{Time.now.iso8601}"
+          lines << "---"
+          lines << ""
+          lines << "# No-op review round"
+          lines << ""
+          if content[:noop_reason] == :empty_delta && delta
+            lines << "Scope: delta since `#{delta[:reference_head]}` — the delta is empty; there is no change to review."
+          else
+            lines << "Scope: #{content[:noop_scope] || "no-op"}."
+          end
+          lines << ""
+          lines << "Verdict: no new findings. This round is clean only if no carried-forward Critical/High finding remains unresolved."
+          lines << ""
+          if Array(options.evidence_sessions).any?
+            evidence = Molecules::ReviewEvidence.build(session_dirs: options.evidence_sessions,
+              pr_metadata: options.pr_metadata || {})
+            if evidence[:success]
+              lines << "## Carried-forward findings"
+              lines << ""
+              lines << evidence[:content]
+            else
+              lines << "## Evidence not carried forward"
+              lines << ""
+              lines << "Prior session evidence could not be read (#{evidence[:error]}); this round did NOT carry findings forward."
+            end
+          else
+            lines << "## Evidence not carried forward"
+            lines << ""
+            lines << "No prior session was available to carry findings forward."
+          end
+          lines.join("\n")
+        end
+
+        # Drop review-exempt paths from a scoped diff. Matching paths are removed
+        # from the subject and enumerated in the manifest, in every round type.
+        # A full round whose files are all exempt is refused: full rounds are
+        # explicit operator intent, and an empty subject cannot be reviewed.
+        def apply_exempt_paths(scoped, config)
+          patterns = Array(config[:exempt_paths])
+          return scoped if patterns.empty?
+
+          classification = Molecules::ExemptPaths.classify(scoped[:manifest][:selected_files], patterns)
+          return scoped if classification[:exempt].empty?
+
+          exempt_set = classification[:exempt]
+          blocks = Atoms::DiffBoundaryFinder.parse(scoped[:diff]).reject { |block| exempt_set.include?(block[:path]) }
+
+          if blocks.empty?
+            return {success: false,
+                    error: "Every changed file is review-exempt (#{exempt_set.join(", ")}, patterns: #{patterns.join(", ")}); " \
+                      "a full round cannot review an empty subject — use a delta round for exempt acceptance"}
+          end
+
+          manifest = scoped[:manifest].merge(
+            exempt_files: classification[:exempt],
+            exempt_patterns: patterns,
+            selected_files: blocks.map { |block| block[:path] },
+            selected_sha256: Digest::SHA256.hexdigest(blocks.map { |block| block[:content] }.join)
+          )
+          {success: true, diff: blocks.map { |block| block[:content] }.join, manifest: manifest}
+        end
+
         # Format PR metadata for context
         def format_pr_metadata(metadata)
           info = "## Pull Request Information\n\n"