ace-review 0.59.0 → 0.60.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeb8650e65f2751e795ea4db791eb9074f95b26ee0eb93d54e4db8040b826b47
-  data.tar.gz: 58a8a7d0a1d268e7282029a9e7805b975deba5d56d6afc24d7b88ab7cf8e8650
+  metadata.gz: acf36b5361402d845cc259ac24c06b4dd1e686cbc25b0a80b62c34ae8453ab53
+  data.tar.gz: 1fbd838c775362c85876d5c160e5352ba3f048a502034659f3f3d14429ae43f3
 SHA512:
-  metadata.gz: b0d0d7238c634039f0b40e3302bf7ba90ff6a84db3e4e6833e72632905590b15ff4df1c6e0da927633c15fa444e97e4fdaf2fbd7292adbe8fe9df3381f98a7f3
-  data.tar.gz: d63ca8120a95fb200115fc27ece39f49ba4d3b662587ea94b5532f978c7a27bb8ed722746e46c0d6c46388f39f84494bb48c4eba0bc38d9053c0668a7acec7d8
+  metadata.gz: adc5171f507ca5b4adc1ada99d0688fb2878236a21339ef7d1fd6c5341e017966a3c721e09cb5bb33a528ebc239e261b137501e9db49fedea4ac9bb100b0cc6f
+  data.tar.gz: 2c7751781253a309563b56d204a981299429f02de6ce09313b19f6cd652e0c4d9f6d68ed83647460778ed6a3edc3e8d25e65995f09650964e754c5995aa251b4

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

@@ -10,7 +10,6 @@
 # max_concurrent_models - Max parallel LLM queries for multi-model execution (default: 3)
 # auto_execute    - Auto-execute LLM query without confirmation (default: false)
 # provider_timeout - Timeout for forge operations in seconds (default: 30)
-# gh_simple_timeout - Timeout for simple gh commands like --version, auth status (default: 10)
 # llm_timeout     - Timeout for LLM queries in seconds (default: 900)
 #
 # Environment Variables:
@@ -38,7 +37,6 @@ defaults:
   max_concurrent_models: 3  # Max parallel LLM queries for multi-model execution
   auto_execute: false  # Set to true to auto-execute LLM query without confirmation
   provider_timeout: 30  # Timeout for forge operations in seconds
-  gh_simple_timeout: 10  # Timeout for simple gh commands (--version, auth status)
   llm_timeout: 900  # Timeout for LLM queries in seconds (15 minutes)
 
 # Review-exempt paths
@@ -79,5 +77,13 @@ campaign:
       revision: delivery-v1
       minimum_rounds: 3
       clean_rounds: 2
+      maximum_rounds: 5
+      required_scopes: [full]
+      required_checks: [tests]
+    discovery:
+      revision: discovery-v1
+      minimum_rounds: 2
+      clean_rounds: 1
+      maximum_rounds: 2
       required_scopes: [full]
       required_checks: [tests]

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.60.1] - 2026-10-10
+
+### Fixed
+
+- Require the published producer and consumer patch versions containing the protected context and managed-attempt APIs; exclude incompatible prior dependency graphs.
+
+## [0.60.0] - 2026-10-08
+
+### Added
+
+- Enforce finite campaign phases, durable provider-attempt reservations, convergence limits, escalation and resume through the same campaign owner.
+- Join canonical collection/check/approval child receipts and current parent result acceptance.
+
+### Fixed
+
+- Accept forge-neutral URLs in typed PR subjects and use the verified held result snapshot without a second projection.
+
+### Added
+
+- ReviewManager can execute a bounded prepared candidate through the maintained provider and feedback pipeline, requiring an explicit bound verdict and complete execution evidence before returning approval.
+
+### Fixed
+
+- Remove the unused GitHub CLI timeout setting from the shipped defaults; forge operations use provider_timeout.
+- Reject missing, duplicate-key or malformed feedback inventories instead of silently dropping findings and reporting a clean extraction.
+
+## [0.59.1] - 2026-10-06
+
+### Fixed
+
+- Concurrent review starts exclusively claim isolated sessions, refuse occupied explicit paths, and preserve report and feedback provenance. Single-model execution reports its exact session path; feedback creation discovers its `review.md`. Release exports publish complete copies without replacing equal-clock reports.
+
 ## [0.59.0] - 2026-10-05
 
 ### Changed

data/docs/campaigns.md

@@ -103,13 +103,14 @@ The final round may reference an explicit approval artifact with `approval: {"pa
 ```json
 {
   "producer":"IMPLEMENTER_ACTOR",
-  "reviewer":"ACTUAL_EXECUTED_REVIEWER_MODEL",
+  "reviewer":"INDEPENDENT_REVIEWER_ACTOR",
   "verdict":"approved",
   "head":"EXACT_REVIEWED_HEAD_SHA",
   "base":"EXACT_REVIEWED_BASE_SHA",
   "contract_identity":"FROZEN_CONTRACT_SHA256",
   "required_scopes":["full"],
   "reports":[{"path":"SESSION/review-report-MODEL.md","sha256":"REPORT_SHA256"}],
+  "report_models":[{"report":{"path":"SESSION/review-report-MODEL.md","sha256":"REPORT_SHA256"},"report_model":"ACTUAL_EXECUTED_MODEL"}],
   "receipt":{"attempt_id":"ACCEPTED_REVIEW_APPROVAL_ATTEMPT_ID","digest":"ACCEPTED_RECEIPT_SHA256"},
   "checks":[{"name":"tests","verdict":"passed","receipt":{
     "attempt_id":"ACCEPTED_CHECK_ATTEMPT_ID","digest":"ACCEPTED_RECEIPT_SHA256"
@@ -119,7 +120,7 @@ The final round may reference an explicit approval artifact with `approval: {"pa
 
 The approval `receipt` refers to an ordinary managed `operation: "review"` receipt with an executed `review.verdict: "approved"`, the same exact head, producer/reviewer actors and checksummed report artifacts. Submit that attributable outcome through the existing coordinator after the independent reviewer actually approves. Do not include a campaign result in this source receipt; campaign consumption happens afterward. The read-only `attempt evidence --kind review-approval` boundary revalidates its accepted authority. A collection receipt certifies execution even when its report rejects the candidate; it cannot certify approval. Every retained approval remains authority-backed across head changes through explicit historical validation.
 
-Producer and reviewer must differ. Reviewer identity must match the actual completed execution model in the referenced session; approvals must cover every required scope. Required checks refer to a succeeded execution receipt already accepted by the ace-assign coordinator. The receipt operation must match the check: `tests` requires `test`; other explicit check names require the same operation name. An unrelated operation claiming a passed tests field is rejected. Run the check under an existing managed assignment attempt and submit its attributable result, current head, check outcomes and checksummed artifacts through `ace-assign attempt finish`. Use the accepted attempt ID and receipt digest here. A self-authored check JSON file is insufficient. Campaign recording and acceptance consult the read-only `ace-assign attempt evidence --attempt ID --receipt-digest DIGEST --format json --kind check --check-name tests` boundary, which revalidates current head and source artifacts against accepted history. Retain `ace-assign` alongside `ace-review` for this qjl evidence capability; unavailable authority blocks acceptance explicitly. Campaign commands never run the check for you or create a second execution journal. Authenticated producer/reviewer attribution and execution acceptance remain owned by ace-assign.
+Producer and reviewer must differ. Reviewer identifies the authenticated actor, independently of the model. Each report must have exactly one `report_models` entry whose checksummed reference belongs to `reports` and whose `report_model` matches verified session execution metadata. Missing, duplicate, extra or mismatched entries fail; model names do not substitute for actor attribution. Approvals must cover every required scope. Required checks refer to a succeeded execution receipt already accepted by the ace-assign coordinator. The receipt operation must match the check: `tests` requires `test`; other explicit check names require the same operation name. An unrelated operation claiming a passed tests field is rejected. Run the check under an existing managed assignment attempt and submit its attributable result, current head, check outcomes and checksummed artifacts through `ace-assign attempt finish`. Use the accepted attempt ID and receipt digest here. A self-authored check JSON file is insufficient. Campaign recording and acceptance consult the read-only `ace-assign attempt evidence --attempt ID --receipt-digest DIGEST --format json --kind check --check-name tests` boundary, which revalidates current head and source artifacts against accepted history. Retain `ace-assign` alongside `ace-review` for this qjl evidence capability; unavailable authority blocks acceptance explicitly. Campaign commands never run the check for you or create a second execution journal. Authenticated producer/reviewer attribution and execution acceptance remain owned by ace-assign.
 
 ```sh
 ace-review campaign finish CAMPAIGN_ID --format json
@@ -139,6 +140,10 @@ Submit a normal succeeded review receipt through `ace-assign attempt finish`. Ad
 
 The receipt retains ordinary attempt/assignment/project/scope binding, producer, current head, reviewer approval and executed checks. Its producer/reviewer actors must match the campaign assessment. The trusted coordinator rechecks live campaign state and rejects stale, blocked, mismatched or dry-run results. Accepting evidence records a separate journal commit without moving the candidate branch.
 
+## Guarded source consumption
+
+Source-owned receipt composition can call `CampaignManager#with_verified_result!(result:, subject:, contract_identity:, policy:, head:, base:, producer:, reviewer:) { |current| ... }`. It requires a block and an existing campaign lock, revalidates current acceptance and the exact expected tuple, and yields a deeply frozen projection while holding one read transaction. Keep the entire receipt/CAS operation inside that block; a retained projection is not a later permission. Do not call public campaign methods from inside the block. Exceptions release the lock, and validation failures never yield. This API does not itself provide protected child linkage or authorize a journal mutation.
+
 ## Restart, contract changes and failures
 
 Campaign authority lives in `.ace-local/review/campaigns/`; retain this directory and source evidence across process/context restarts. Records are serialized with a lock and replaced atomically with checksums. Every retained completed session, including earlier rounds and partial coverage, must keep its immutable accepted review-collection authority. Historical reads use `ace-assign attempt evidence --kind review-collection --historical-head EXACT_RECORDED_HEAD` to validate that receipt and its artifacts. This read-only mode cannot certify current checks; check-purpose proofs always require the live head. Losing/corrupting evidence from any retained counted round or assessment makes it unavailable; historical counters remain diagnostic and do not manufacture acceptance. These records are durable local artifacts, not a second assignment execution journal.

data/docs/usage.md

@@ -65,7 +65,36 @@ ace-review [OPTIONS]
 | `--no-feedback` | Skip feedback extraction |
 | `--feedback-model` | Model for feedback extraction |
 | `--save-session` | Save session files (default: true) |
-| `--session-dir` | Custom session directory |
+| `--session-dir` | Fresh session directory; existing empty directories may be claimed once |
+
+### Concurrent reviews and exact session selection
+
+Each new review claims its own session before writing prompts or metadata. Automatic
+sessions use `.ace-local/review/sessions/review-<id>` with an opaque suffix when a
+name collides. Successful execution prints both the exported report and the actual
+session directory. Same-clock reviews preserve separate reports and feedback.
+
+```bash
+bin/ace-review --preset code-valid --subject diff:BASE..HEAD --auto-execute
+# Output includes: Session directory: /project/.ace-local/review/sessions/review-<id>
+bin/ace-review-feedback list --session /project/.ace-local/review/sessions/review-<id>
+# Output contains only this session's findings.
+```
+
+For manual feedback creation, pass the exact reported session path to
+`bin/ace-review-feedback create --session PATH`. Single-model `review.md` and
+multi-model reports are discovered within that directory. Published findings are
+immutable; start a fresh review when findings already exist.
+
+An explicit path must be absent or an unclaimed empty directory. A permanent claim
+remains after success, failure or interruption. Reusing a claimed or nonempty path,
+a regular file, or a symlink fails before reviewer execution and preserves existing
+contents. Choose a fresh writable path after an allocation refusal:
+
+```bash
+bin/ace-review --preset code-valid --subject diff:BASE..HEAD --session-dir .ace-local/review/source-round-2
+# Output includes: Review session prepared: .ace-local/review/source-round-2
+```
 
 ### Informational
 
@@ -117,6 +146,14 @@ ace-review --list-prompts
 
 Manage feedback items extracted from reviews.
 
+Extraction requires an explicit `findings` array in the synthesis response.
+A missing array, duplicate JSON key, or finding without a nonempty textual title
+and description fails the entire extraction; valid findings are not published
+as a partial replacement. For example, `{"findings":[{"title":"","finding":"Bug"}]}`
+is an extraction failure, while `{"findings":[]}` is a completed empty extraction.
+Neither a provider's successful exit nor empty extraction is an approval verdict.
+
+
 ### Subcommands
 
 | Command | Description |

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

@@ -17,6 +17,17 @@ One round covers the PR's needed scope, including cross-module integration. A la
 
 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.
 
+## Execution boundary
+
+The ordinary commands below use the local campaign store and coordinator-accepted
+ordinary receipts. For an installed protected parent with registered
+`review_campaign`, use its original authenticated authority and the protected
+handoff below instead. The installed launcher owns the original linked collection,
+check and approval children; each must succeed, settle and release before its
+receipt can count. A worker-local report or ordinary `attempt finish` cannot
+replace that linkage. Draft creation/update may precede review; ready and merge
+still require the accepted current-candidate result and executed checks.
+
 ## 1. Choose and prepare the scope
 
 Identify the PR from an explicit number, owner/repository#number or URL and read normalized evidence with `ace-git pr show IDENTIFIER --format json`. Use the assignment's retained forge selection: `--server NAME` or `--default-server`, mutually exclusive; otherwise resolve the repository remote. Keep that same selection on `ace-review --pr IDENTIFIER` in every round. Do not infer a forge or PR from a fixed hostname or caller identity. 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.
@@ -37,7 +48,7 @@ Verify reports against code and requirements. Use `ace-review-feedback list --se
 
 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.
 
-## 3. Record progress and finish
+## 3. Ordinary campaign recording and finish
 
 Use the durable `ace-review campaign` authority for completed rounds, verified dispositions, required scopes and clean streak. Start/reuse it with explicit subject JSON and a frozen behavioral requirements document; snapshot the applicable delivery policy. Pin an empty round before collection with head/base, scope IDs and presets, then pass `--campaign ID --campaign-round ROUND --campaign-scope SCOPE` to the existing review runner. Have the existing assignment coordinator accept each completed collection as a `review-collect` receipt with a passed review-execution outcome and checksummed metadata/report/prompt artifacts. Include its accepted receipt reference with the session and verified feedback dispositions in `campaign record-round`; editable execution flags alone cannot count. Full PR scopes require the complete unfiltered whole-PR inventory without delta references. Filtered module reviews and delta reviews use explicit module or delta scopes frozen in the campaign policy; pin the delta reference before collection. The default delivery `full` policy requires whole-PR rounds. Record partial attempts without counting them as completed rounds. See `ace-review/docs/campaigns.md` for exact input schemas and examples.
 
@@ -52,3 +63,68 @@ Examples:
 - A round that finds a confirmed P1 is not clean even if it is fixed immediately afterward.
 
 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. Finish with `ace-review campaign finish ID --format json` after the final round records independent current-head approval backed by an accepted ordinary review receipt and passing required check artifacts. The source approval receipt must bind the approved reviewer verdict, actors, head and report hashes; caller-written approval JSON and collection receipts alone cannot approve the candidate. Search convergence alone cannot approve stale/incomplete evidence or unresolved earlier P0/P1. The result remains a local artifact until ace-assign independently verifies it through its existing attempt receipt boundary. 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.
+
+
+## Protected campaign recording and parent result handoff
+
+Use the original parent mapping, assignment, attempt, exact candidate SHA and
+positive candidate generation from its accepted registration/status. Campaign ID,
+subject, frozen requirements identity and policy come from that registered parent;
+these commands have no caller-selected campaign, project, scope or base flags.
+The round's base and scopes remain the exact pinned R1 input. Do not run local
+`ace-review campaign record-round` or `finish` as an installed authority substitute.
+
+Upload the existing R1 round JSON inside the closed R2 envelope:
+`{"version":1,"round":ROUND_OBJECT,"artifacts":[{"path":"report.md","sha256":"SHA256"}]}`.
+`ROUND_OBJECT` retains the documented attempt_id, round_id, head/base,
+required_scopes, scope_identity, sessions, dispositions and optional approval.
+Its attempt_id equals the stable mutation ID below and its head equals the parent
+SHA. Each artifact path is a bounded relative materialization name; it is not an
+instruction for the authority to read the worker filesystem. Supply exact report,
+metadata, prompt, feedback and approval bytes referenced by that round as ordered
+`--artifact` files matching the envelope's paths/digests. The envelope is at most
+16 KiB, with at most 16 artifacts of at most 64 KiB each. The authority privately
+materializes bytes and resolves child receipt references from canonical history;
+collection proves execution, while independently accepted approval and matching
+check children establish acceptance. Never add the parent campaign result to a
+source child receipt.
+
+```sh
+ace-assign campaign-record-round --mapping MAPPING --assignment PARENT --attempt ATTEMPT --head SHA --candidate-generation N --mutation ROUND-ATTEMPT --input ROUND-ENVELOPE.json --artifact REPORT-BYTES
+ace-assign campaign-export-result --mapping MAPPING --assignment PARENT --attempt ATTEMPT --head SHA --candidate-generation N --output RESULT.json
+```
+
+Repeat `--artifact` for all envelope artifacts in declared order, or omit it for
+an empty pin. Record each completed round under the frozen policy; export succeeds
+only when that policy, current candidate, independent approval and required checks
+are accepted. Export creates mode0600 result bytes once and reports path, sha256,
+result_identity and journal_commit. An existing output is reusable only when its
+bytes match exactly; do not rewrite or compose a replacement result.
+
+The original parent receipt keeps its existing assignment/attempt/project/scope,
+producer, exact head, `operation: "review"`, `verdict: "succeeded"`, independent
+reviewer approval and executed checks. Add
+`"campaign":{"id":"REGISTERED-CAMPAIGN","result":{"path":"RESULT.json","sha256":"EXPORTED-SHA256"}}`
+and include that identical reference in its `artifacts` array. Supply the exact
+exported bytes in the matching ordered upload slot alongside the receipt's other
+artifacts; local artifact names become canonical imported references on acceptance.
+Submit through the maintained public boundary, using the persisted authority
+generation and a stable original result mutation:
+
+```sh
+ace-assign submit-result --mapping MAPPING --assignment PARENT --attempt ATTEMPT --head SHA --candidate-generation N --expected-generation G --mutation RESULT-MUTATION --receipt PARENT-RECEIPT.json --artifact RESULT.json
+```
+
+This submits evidence; it does not independently approve, finish or release the
+parent. The original reviewer/finish owner retains that gate. Authority generation
+G and candidate generation N are distinct. Ready/merge revalidate this canonical
+parent campaign result and checks at the current candidate.
+
+On a lost reply/restart, preserve the exact round mutation, envelope and ordered
+bytes; identical round replay returns retained history without another completed
+round. Re-export may only reuse identical result bytes. Preserve original result
+mutation, generation and upload bytes for result replay; do not refresh selectors
+to manufacture success. Changed candidate, policy, requirements or missing child
+settlement/source artifacts refuses current export/submission/ready/merge while
+retaining historical rounds. Read original canonical status and route the precise
+producer blocker; do not fabricate receipts or bypass to ordinary commands.

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

@@ -2,6 +2,8 @@
 
 require "digest"
 require "json"
+require "uri"
+require "ace/git/atoms/server_url"
 
 module Ace
   module Review
@@ -86,15 +88,22 @@ module Ace
             parsed = Ace::Git::Atoms::PrIdentifier.parse(string!(pr, "pr"))
             raise Invalid, "PR must include repository identity (owner/repo#number)" unless parsed&.repo
             raise Invalid, "PR number must be positive" unless parsed.number.to_i.positive?
-            repository = repository.delete_suffix("/")
-            repo = parsed.repo
-            if repository.start_with?("https://github.com/")
-              unless repository.delete_prefix("https://github.com/").casecmp?(repo)
-                raise Invalid, "PR repository identity does not match the declared repository"
-              end
-              repo = repo.downcase
-              repository = "https://github.com/#{repo}"
+            begin
+              uri = URI.parse(repository)
+            rescue URI::InvalidURIError
+              raise Invalid, "PR repository must be an explicit HTTP(S) repository URL"
             end
+            unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+              raise Invalid, "PR repository must be an explicit HTTP(S) repository URL"
+            end
+            normalized = Ace::Git::Atoms::ServerUrl.normalize(repository)
+            repo = parsed.repo.downcase
+            # Retain the exact server/port and optional forge base path. The
+            # qualified PR names the final owner/repository pair on that server.
+            unless normalized.split("/").drop(1).last(2).join("/") == repo
+              raise Invalid, "PR repository identity does not match the declared repository"
+            end
+            repository = "#{uri.scheme.downcase}://#{normalized}"
             {"repository" => repository, "pr" => "#{repo}##{parsed.number.to_i}"}
           else
             {"repository" => repository, "local_candidate_id" => id!(local, "local_candidate_id")}
@@ -105,13 +114,16 @@ module Ace
           object!(value, "policy")
           required = %w[revision minimum_rounds clean_rounds required_scopes required_checks]
           raise Invalid, "policy requires #{required.join(', ')}" unless (required - value.keys).empty?
-          raise Invalid, "unknown policy fields" unless (value.keys - required).empty?
+          raise Invalid, "unknown policy fields" unless (value.keys - required - ["maximum_rounds"]).empty?
           string!(value["revision"], "policy revision")
           %w[minimum_rounds clean_rounds].each do |key|
             raise Invalid, "#{key} must be a positive integer" unless value[key].is_a?(Integer) && value[key].positive?
           end
           strings!(value["required_scopes"], "required_scopes").each { |v| id!(v, "scope") }
           strings!(value["required_checks"], "required_checks")
+          if value.key?("maximum_rounds") && !(value["maximum_rounds"].is_a?(Integer) && value["maximum_rounds"].positive?)
+            raise Invalid, "maximum_rounds must be a positive integer"
+          end
           canonical(value)
         end
       end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+require_relative "campaign_contract"
+
+module Ace
+  module Review
+    module Atoms
+      # Exploration budgets are independent of the current-head acceptance gate.
+      module CampaignPolicy
+        Contract = CampaignContract
+        DEFAULTS = {
+          "discovery" => {"minimum_rounds" => 2, "clean_rounds" => 1, "maximum_rounds" => 2},
+          "delivery" => {"minimum_rounds" => 3, "clean_rounds" => 2, "maximum_rounds" => 5}
+        }.transform_values(&:freeze).freeze
+        TERMINAL_FAILURES = %w[authentication authorization model_unavailable unclassified].freeze
+        TRANSIENT_FAILURES = %w[timeout transport rate_limit unavailable].freeze
+        INFRASTRUCTURE_RETRIES = 2
+
+        def self.bounds!(profile:, policy:)
+          defaults = DEFAULTS[profile]
+          raise Contract::Invalid, "unsupported campaign profile #{profile}" unless defaults
+          Contract.object!(policy, "campaign policy")
+          result = defaults.merge(policy.slice("minimum_rounds", "clean_rounds", "maximum_rounds"))
+          unless result.values.all? { |value| value.is_a?(Integer) && value.positive? } &&
+              result["minimum_rounds"] <= result["maximum_rounds"] &&
+              result["clean_rounds"] <= result["maximum_rounds"] &&
+              result["maximum_rounds"] <= defaults["maximum_rounds"]
+            raise Contract::Invalid, "campaign policy conflicts with its finite execution budget"
+          end
+          if profile == "delivery" &&
+              (result["minimum_rounds"] < 3 || result["clean_rounds"] < 2)
+            raise Contract::Invalid, "delivery policy cannot weaken its search requirements"
+          end
+          result.freeze
+        end
+
+        def self.next_phase(record:, phase_id:, reason:, route:, additional_rounds:)
+          Contract.id!(phase_id, "phase ID")
+          Contract.string!(reason, "next phase reason")
+          Contract.string!(route, "next phase route")
+          unless additional_rounds.is_a?(Integer) && additional_rounds.positive?
+            raise Contract::Invalid, "next phase requires an explicit finite positive budget"
+          end
+          existing = record.fetch("phases").find { |phase| phase["id"] == phase_id }
+          if existing
+            unless existing.values_at("reason", "route", "maximum_rounds") == [reason, route, additional_rounds]
+              raise Contract::Invalid, "conflicting replay of authorized next phase"
+            end
+            return existing
+          end
+          {"id" => phase_id, "profile" => record.fetch("profile"), "round_start" => record.fetch("rounds").size,
+            "maximum_rounds" => additional_rounds, "reason" => reason, "route" => route}.freeze
+        end
+
+        def self.decision(profile:, bounds:, phase_rounds:, completed_rounds:, clean_streak:,
+          accepted:, recurrence: false, execution_failure: nil)
+          raise Contract::Invalid, "unsupported campaign profile #{profile}" unless DEFAULTS.key?(profile)
+          unless [phase_rounds, completed_rounds, clean_streak].all? { |n| n.is_a?(Integer) && n >= 0 } &&
+              phase_rounds <= completed_rounds && clean_streak <= completed_rounds && phase_rounds <= bounds.fetch("maximum_rounds") &&
+              [true, false].include?(accepted) && [true, false].include?(recurrence)
+            raise Contract::Invalid, "campaign counters or acceptance differ"
+          end
+          converged = profile == "delivery" && completed_rounds >= bounds.fetch("minimum_rounds") &&
+            clean_streak >= bounds.fetch("clean_rounds")
+          remaining = bounds.fetch("maximum_rounds") - phase_rounds
+          outcome, action = if profile == "discovery" && remaining.zero?
+            ["discovery_complete", "export_candidate"]
+          elsif execution_failure
+            ["execution_failed", "resolve_execution_failure"]
+          elsif profile == "delivery" && accepted && converged && !recurrence
+            ["accepted", "finish"]
+          elsif remaining.zero?
+            ["needs_escalation", "authorize_next_phase"]
+          elsif recurrence
+            ["needs_diagnosis", "diagnose_canonical_defect"]
+          elsif converged
+            ["search_converged", "satisfy_acceptance"]
+          else
+            ["in_progress", "review"]
+          end
+          {"profile" => profile, "outcome" => outcome, "next_action" => action,
+            "remaining_rounds" => remaining, "phase_rounds" => phase_rounds,
+            "search_converged" => converged, "accepted" => outcome == "accepted",
+            "execution_failure" => execution_failure}.freeze
+        end
+
+        # Severity corrections target the exact observation. A successful fix
+        # never retroactively changes the severity of the original round.
+        def self.clean_streak(record)
+          corrections = record.fetch("assessments").select { |item| item["kind"] == "severity_correction" }
+            .to_h { |item| [item.fetch("source_id"), item] }
+          rounds = record.fetch("rounds").to_h { |item| [item.fetch("attempt_id"), item] }
+          streak = 0
+          record.fetch("attempts").each do |attempt|
+            blocked = attempt.fetch("assessments").any? do |item|
+              correction = corrections[item.fetch("source_id")]
+              priority = correction ? correction.fetch("priority") : item.fetch("priority")
+              disposition = correction ? correction.fetch("disposition") : item.fetch("disposition")
+              item["observed_in_round"] && %w[high critical].include?(priority) && disposition != "invalid"
+            end
+            streak = 0 if blocked
+            if rounds.key?(attempt.fetch("attempt_id"))
+              round_observations = record.fetch("attempts").select { |item| attempt["round_id"] ? item["round_id"] == attempt["round_id"] : item["attempt_id"] == attempt["attempt_id"] }
+                .flat_map { |item| item.fetch("assessments") }
+              round_blocked = round_observations.any? do |item|
+                correction = corrections[item.fetch("source_id")]
+                priority = correction ? correction.fetch("priority") : item.fetch("priority")
+                disposition = correction ? correction.fetch("disposition") : item.fetch("disposition")
+                item["observed_in_round"] && %w[high critical].include?(priority) && disposition != "invalid"
+              end
+              streak = round_blocked ? 0 : streak + 1
+            end
+          end
+          streak
+        end
+
+        def self.canonical_findings(record)
+          findings = {}
+          (record.fetch("inherited_findings") + record.fetch("assessments")).each do |item|
+            next if item["kind"] == "repair_attempt"
+            id = item.fetch("id")
+            prior = findings[id]
+            sources = prior ? prior.fetch("sources") : item.fetch("sources", []).dup
+            source = item.slice("source_id", "artifact", "source_artifact", "priority", "disposition", "reason")
+            sources = sources + [source] unless sources.include?(source)
+            findings[id] = item.merge("sources" => sources)
+          end
+          findings.values
+        end
+
+        def self.recurring_blockers(record)
+          fixes = {}
+          recurring = {}
+          observed = []
+          record.fetch("assessments").each do |item|
+            id = item.fetch("id")
+            observation = item.slice("source_id", "artifact")
+            fresh_observation = !observed.include?(observation)
+            observed << observation if item["observed_in_round"] && fresh_observation
+            if item["kind"] == "repair_attempt"
+              fixes[id] = item
+            elsif %w[resolved invalid].include?(item["disposition"])
+              fixes.delete(id)
+              recurring.delete(id)
+            elsif item["observed_in_round"] && fresh_observation &&
+                %w[high critical].include?(item["priority"]) && fixes.key?(id)
+              recurring[id] = {"finding_id" => id, "repair_attempt" => fixes.fetch(id), "recurrence" => item}
+            end
+          end
+          recurring.values
+        end
+
+        # Entries are the durable before-call reservations, not report imports.
+        # An unanswered original call requires resolution, never a fresh retry.
+        def self.retry_decision(attempts:, round_id:, scope:, provider:)
+          [round_id, scope, provider].each { |value| Contract.string!(value, "execution selection") }
+          raise Contract::Invalid, "execution attempts must be an array" unless attempts.is_a?(Array)
+          attempts.each { |entry| Contract.object!(entry, "execution attempt") }
+          selected = attempts.select do |entry|
+            entry.values_at("round_id", "scope", "provider") == [round_id, scope, provider]
+          end
+          selected.each do |entry|
+            unless %w[running uncertain succeeded failed].include?(entry["status"]) &&
+                (entry["status"] != "failed" || (TERMINAL_FAILURES + TRANSIENT_FAILURES).include?(entry["failure"]))
+              raise Contract::Invalid, "execution attempt disposition differs"
+            end
+          end
+          state = if selected.any? { |entry| %w[running uncertain].include?(entry["status"]) }
+            "resolve_original_attempt"
+          elsif selected.any? { |entry| entry["status"] == "succeeded" }
+            "already_completed"
+          elsif selected.any? { |entry| TERMINAL_FAILURES.include?(entry["failure"]) }
+            "terminal_failure"
+          elsif selected.size >= INFRASTRUCTURE_RETRIES + 1
+            "retries_exhausted"
+          else
+            "execute"
+          end
+          {"next_action" => state, "execution_attempts" => selected.size,
+            "remaining_attempts" => [INFRASTRUCTURE_RETRIES + 1 - selected.size, 0].max}.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require_relative "campaign_policy"
 
 module Ace
   module Review
@@ -7,32 +8,28 @@ module Ace
       module CampaignProjection
         def self.build(record)
           rounds = record.fetch("rounds")
-          findings = record.fetch("inherited_findings").to_h { |finding| [finding.fetch("id"), finding] }
-          record.fetch("assessments").each { |finding| findings[finding.fetch("id")] = finding }
-          open = findings.values.select { |finding| %w[open reopened].include?(finding["disposition"]) }
+          findings = CampaignPolicy.canonical_findings(record)
+          open = findings.select { |finding| %w[open reopened].include?(finding["disposition"]) }
           policy = record.fetch("policy")
           attempts = record.fetch("attempts")
-          completed = rounds.to_h { |round| [round.fetch("attempt_id"), round] }
-          streak = 0
-          attempts.each do |attempt|
-            # A verified blocker resets convergence when observed, even if its
-            # logical round never completes or a different round completes next.
-            if attempt.fetch("assessments").any? { |finding| finding["observed_in_round"] &&
-                %w[high critical].include?(finding["priority"]) && finding["disposition"] != "invalid" }
-              streak = 0
-            end
-            round = completed[attempt.fetch("attempt_id")]
-            streak = round["clean"] ? streak + 1 : 0 if round
-          end
+          streak = CampaignPolicy.clean_streak(record)
+          phase = record.fetch("phases").last
+          bounds = record.fetch("bounds").merge("maximum_rounds" => phase.fetch("maximum_rounds"))
+          decision = CampaignPolicy.decision(profile: record.fetch("profile"), bounds: bounds,
+            phase_rounds: rounds.size - phase.fetch("round_start"), completed_rounds: rounds.size,
+            clean_streak: streak, accepted: false, recurrence: !CampaignPolicy.recurring_blockers(record).empty?)
           sessions = attempts.flat_map { |attempt| attempt.fetch("sessions") }.uniq { |session| session["path"] }
           {"campaign_id" => record.fetch("id"), "subject" => record.fetch("subject"),
            "contract_identity" => record.fetch("contract_identity"), "effective_policy" => policy,
            "predecessor" => record["predecessor"], "successor_reason" => record["successor_reason"],
            "required_scopes" => policy.fetch("required_scopes"), "completed_rounds" => rounds.size,
-           "clean_streak" => streak, "open_findings" => open, "findings" => findings.values,
-           "search_converged" => rounds.size >= policy.fetch("minimum_rounds") &&
-             streak >= policy.fetch("clean_rounds"),
-           "counters" => {"recording_attempts" => attempts.size,
+           "clean_streak" => streak, "open_findings" => open, "findings" => findings,
+           "search_converged" => decision.fetch("search_converged"),
+           "profile" => record.fetch("profile"), "phase" => phase, "phases" => record.fetch("phases"),
+           "bounds" => record.fetch("bounds"), "decision" => decision,
+           "execution_attempts" => record.fetch("execution_attempts"),
+           "recurring_blockers" => CampaignPolicy.recurring_blockers(record),
+           "counters" => {"recording_attempts" => attempts.size, "execution_attempts" => record.fetch("execution_attempts").size,
              "provider_calls" => sessions.sum { |s| s.fetch("provider_calls") },
              "report_files" => sessions.sum { |s| s.fetch("report_files") }, "completed_rounds" => rounds.size},
            "rounds" => rounds, "attempts" => attempts, "head_transitions" => record.fetch("head_transitions")}

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

@@ -3,6 +3,8 @@ require_relative "commands/campaign/start"
 require_relative "commands/campaign/status"
 require_relative "commands/campaign/record_round"
 require_relative "commands/campaign/finish"
+require_relative "commands/campaign/resume"
+require_relative "commands/campaign/assess"
 
 module Ace
   module Review
@@ -11,7 +13,7 @@ module Ace
         extend Ace::Support::Cli::RegistryDsl
         PROGRAM_NAME = "ace-review campaign"
         REGISTERED_COMMANDS = [["start", "Start/reuse a frozen campaign"], ["status", "Inspect history and evidence"],
-          ["record-round", "Pin or record scoped evidence"], ["finish", "Validate current acceptance"]].freeze
+          ["record-round", "Pin or record scoped evidence"], ["finish", "Validate current acceptance"], ["resume", "Authorize a finite next phase"], ["assess", "Record verified finding assessment"]].freeze
         HELP_EXAMPLES = ["ace-review campaign start --subject subject.json --contract requirements.md --profile delivery",
           "ace-review campaign status ID --format json", "ace-review campaign record-round ID --input round.json",
           "ace-review campaign finish ID --format json"].freeze
@@ -19,9 +21,11 @@ module Ace
         register "status", Commands::Campaign::Status
         register "record-round", Commands::Campaign::RecordRound
         register "finish", Commands::Campaign::Finish
+        register "resume", Commands::Campaign::Resume
+        register "assess", Commands::Campaign::Assess
         help = Ace::Support::Cli::HelpCommand.build(program_name: PROGRAM_NAME, version: Ace::Review::VERSION,
           commands: [["start", "Start/reuse a frozen campaign"], ["status", "Inspect history and evidence"],
-            ["record-round", "Pin or record scoped evidence"], ["finish", "Validate current acceptance"]],
+            ["record-round", "Pin or record scoped evidence"], ["finish", "Validate current acceptance"], ["resume", "Authorize a finite next phase"], ["assess", "Record verified finding assessment"]],
           examples: ["ace-review campaign start --subject subject.json --contract requirements.md --profile delivery",
             "ace-review campaign status ID --format json", "ace-review campaign record-round ID --input round.json",
             "ace-review campaign finish ID --format json"])

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require_relative "base"
+module Ace
+  module Review
+    module CLI
+      module Commands
+        module Campaign
+          class Assess < Base
+            desc "Record verified severity correction or evidenced repair attempt"
+            argument :id, required: true, desc: "Durable campaign ID"
+            option :input, required: true, desc: "Assessment JSON with source identity, kind, reason and evidence"
+
+            def call(id:, **options)
+              run(options) { |manager| manager.assess_finding(id, read_json(options[:input]), dry_run: options[:dry_run]) }
+              0
+            end
+          end
+        end
+      end
+    end
+  end
+end