ace-review 0.56.1 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3eb68d4c56fe426002098bd5d5dc10567ea5dcf92ba709069d526c9d8d4ca77
-  data.tar.gz: bdaafd88e24669a1c2beb50fd16b2daf606f56b7f07d0815a36ba28deda175a3
+  metadata.gz: ad21edc3f01275162f0b17aaa9033413abdca90a54a89b7240305b350087ac1a
+  data.tar.gz: 8a516e358225b6351f05b631f0866bb51c23c7cbfdf69dfd6c19e59a764c7d29
 SHA512:
-  metadata.gz: c1acb46ca00a76f48bd05e65f7b167e9bb395732a922bf848a8792fd342be10e85777e155eb6ba5675396a6021bd257fd9d3008dcc26a03656768f83931d9338
-  data.tar.gz: 23c76466b28055d2c02364e711373d2743b71684b3dcb611c2523e344c430546034af289d972c3af80d590bb221f61cef8b2d977c988d334fcd620398c1467c6
+  metadata.gz: a22b32abda5cdfdef0c9c01a0cdeb9668aa60a98884ba93c48ea96d3c1f8ec1455fe08cbff16944afc661f2d4760a1aa644ea944b874e53ef6b5c033636d28d4
+  data.tar.gz: 3e65df04186e2748b7ab716555157ecb2c5e4153cb78928a8a15823717ee750f5bb346c9328f8f401f09f7570c02cf81cdade75f08159bc2aaee0afd427019c4

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

@@ -71,3 +71,13 @@ feedback:
 
 # Review presets - load from .ace/review/presets/*.yml
 # Individual preset files provide better organization and shareability
+
+# Campaign persistence snapshots this policy; changing config never rewrites history.
+campaign:
+  profiles:
+    delivery:
+      revision: delivery-v1
+      minimum_rounds: 3
+      clean_rounds: 2
+      required_scopes: [full]
+      required_checks: [tests]

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.57.0] - 2026-10-01
+
+### Fixed
+
+- Retain a checksummed subject identity index before publishing campaign records, preventing first-record deletion or interrupted creation from resetting history. Subject-scoped lookup isolates unrelated record corruption.
+- Reject campaign-bound PR collection from a different checkout head before executing a model.
+- Require an explicitly successful model entry and matching runner-recorded head before campaign completion; incomplete execution or conflicting metadata cannot count.
+
+- Canonical GitHub repository identities reuse campaign history across trailing slashes and repository case. Local full scope rejects empty Git diffs, including distinct commits with identical trees.
+
+- Partial High/Critical observations reset convergence across logical round IDs; a different completed round cannot reuse the preceding clean streak.
+- Missing GitHub CLI/authentication produces blocked campaign JSON instead of an uncaught source exception.
+
+### Added
+
+- `ace-review campaign start|status|record-round|finish`: durable campaign identity, frozen policy/contracts, linked successors and atomic checksummed history. Completed rounds and clean streak survive head changes while current acceptance requires intact evidence for all counted rounds, verified feedback, independent approval and passing checks backed by coordinator-accepted execution receipts.
+- Bind existing review collection with `--campaign`, `--campaign-round` and `--campaign-scope`; incomplete/no-op/failed attempts do not advance round counters. Replay is idempotent and conflicting writes fail.
+- Independent approval binds an accepted ordinary review receipt to the exact head, producer/reviewer and reports; caller approval JSON or collection evidence cannot grant acceptance. Retained approvals remain authority-backed across head drift.
+- Packaged campaign usage and assignment receipt integration through the existing coordinator authority.
+
+### Fixed
+
+- Existing campaign status and finish use their own checksummed successor marker, so unrelated corrupt records cannot block them. Publish supersession before the successor record so an interrupted publication remains blocked.
+
+### Technical
+
+- Approval rejection coverage first validates accepted session evidence and then asserts rejection at approval authority, preventing stale checksums from making the negative control pass early.
+
 ## [0.56.1] - 2026-09-29
 
 ### Fixed

data/README.md

@@ -56,3 +56,7 @@ ace-test-e2e ace-review
 
 ---
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)
+
+### Durable review campaigns
+
+Use `ace-review campaign start|status|record-round|finish` to retain review history independently of current-head evidence. See [campaign usage](docs/campaigns.md) for frozen contracts/policy, pinned scopes, restart/replay and assignment receipt consumption. Existing review and feedback commands remain primary operations.

data/docs/campaigns.md

@@ -0,0 +1,154 @@
+# Durable review campaigns
+
+A campaign preserves verified review history across commits, squash, rebase and process restarts. Its search counters describe completed rounds; current acceptance also requires current-head evidence, passing required checks and an independent reviewer approval. Campaign commands execute no models, commits, merges, publications or deployments.
+
+## Start and inspect
+
+Use a frozen requirements document containing behavioral requirements only. Do not supply mutable task status, implementation plans or completion reports as requirements. Place input artifacts under `.ace-local/` so they do not change the candidate worktree.
+
+```sh
+mkdir -p .ace-local/campaign-input
+# Run inside the candidate repository. This writes a local discovery identity.
+python3 - <<'PY'
+import json, pathlib
+root = pathlib.Path.cwd().resolve()
+out = root / '.ace-local/campaign-input'
+(out / 'subject.json').write_text(json.dumps({
+    'repository': 'local:' + str(root), 'local_candidate_id': 'candidate-a'
+}))
+(out / 'requirements.md').write_text('Reject invalid input and preserve accepted history.\n')
+PY
+ace-review campaign start --subject .ace-local/campaign-input/subject.json \
+  --contract .ace-local/campaign-input/requirements.md --profile delivery --dry-run
+ace-review campaign start --subject .ace-local/campaign-input/subject.json \
+  --contract .ace-local/campaign-input/requirements.md --profile delivery
+ace-review campaign status CAMPAIGN_ID --format json
+```
+
+Expected: dry-run emits `dry_run: true` without creating campaign state. GitHub repository case and a trailing slash normalize to the same repository/PR identity and reuse the same findings/history. Start emits a `campaign_id`, the requirements content digest and a policy snapshot. Initial status has zero completed rounds and `accepted: false`. In this repository use `bin/ace-review` for every invocation.
+
+For an existing GitHub subject use `{"repository":"https://github.com/owner/repo","pr":"owner/repo#42"}`. The identity format is provider-neutral; collection currently supports the existing local and GitHub sources. An unavailable forge adapter is an explicit error. Local repository identity is `local:` followed by its real checkout path; different local candidates use different `local_candidate_id` values.
+
+## Pin and collect a round
+
+Before collection, record a pin with empty sessions and dispositions. `attempt_id` identifies one immutable recording submission; `round_id` identifies the logical round. Use a new attempt ID for partial progress and completion. Required scopes must equal the frozen policy scopes. Each scope identity pins the review preset and explicit subject selectors before collection. Collection must use those exact selectors. The local `full` scope requires only the exact pinned diff selector; file subsets use explicit module scope IDs in the frozen policy. PR `full` also requires the collector’s complete verified diff inventory with no filtered or exempted files and no delta reference; module presets and delta collection use explicit module or delta scope IDs. Both collection and recording validate the manifest.
+
+```json
+{
+  "attempt_id": "pin-r1",
+  "round_id": "r1",
+  "head": "EXACT_REVIEWED_HEAD_SHA",
+  "base": "EXACT_REVIEWED_BASE_SHA",
+  "required_scopes": ["full"],
+  "scope_identity": {"full": {"preset":"code-valid","subjects":["diff:EXACT_BASE_SHA..EXACT_HEAD_SHA"]}},
+  "sessions": [],
+  "dispositions": []
+}
+```
+
+Replace the SHA placeholders with exact Git revisions. For local campaigns, the latest explicit round pin defines the current base; changing that pin invalidates older-base evidence while preserving history. Both revisions must exist as Git commits. A local `full` scope must contain a nonempty Git diff; equal revisions or distinct commits with identical trees are rejected at pinning, collection and acceptance. For PR scopes pin `subjects: ["pr:owner/repo#42"]`; PR collection uses the fetched PR head/base. The reserved `full` scope always covers the whole PR. For delta collection, freeze an explicit `delta` scope in the policy; that scope additionally pins `delta_reference_head` to an exact SHA in its scope identity and collects with `--delta SHA`; a delta cannot satisfy a scope pinned without that reference. Candidate code must be committed before campaign collection or acceptance. Untracked artifacts under the ACE-private `.ace-local/` directory do not dirty the candidate, even without a gitignore entry. Tracked changes there and tracked or untracked source changes elsewhere still block collection and acceptance.
+
+```sh
+ace-review campaign record-round CAMPAIGN_ID --input .ace-local/campaign-input/pin.json
+ace-review --preset code-valid --subject diff:EXACT_BASE_SHA..EXACT_HEAD_SHA --auto-execute \
+  --campaign CAMPAIGN_ID --campaign-round r1 --campaign-scope full
+```
+
+Expected: the pin reports `recorded_complete: false`, then the existing review runner writes its ordinary session artifacts with the pinned campaign/contract/scope/head/base binding. Other review invocations, repeated model/subject/evidence flags and feedback commands retain their normal behavior. A zero-model no-op, failed/incomplete report, or skipped/failed feedback extraction cannot complete a campaign round. Do not use `--no-feedback` for campaign collection. The runner records a successful extraction inventory, including explicit zero findings; deleting a listed finding invalidates the session. Local head/base values must name available Git commits.
+
+Verify findings with `ace-review-feedback verify --valid|--invalid --research ... --session SESSION`, and resolve repairs with `ace-review-feedback resolve --resolution ... --session SESSION`. Every feedback item must have substantive verification research; resolved items also need a resolution.
+
+## Record coverage and dispositions
+
+Submit a new attempt ID with all reports needed for the round. Metadata, reports and prompts must retain their execution checksums. An artifact reference always has repository-relative `path` and SHA-256 of the exact file bytes.
+
+```json
+{
+  "attempt_id": "complete-r1",
+  "round_id": "r1",
+  "head": "EXACT_REVIEWED_HEAD_SHA",
+  "base": "EXACT_REVIEWED_BASE_SHA",
+  "required_scopes": ["full"],
+  "scope_identity": {"full": {"preset":"code-valid","subjects":["diff:EXACT_BASE_SHA..EXACT_HEAD_SHA"]}},
+  "sessions": [{"scope":"full","metadata":{
+    "path":".ace-local/review/sessions/review-SESSION/metadata.yml",
+    "sha256":"METADATA_SHA256"
+  }, "receipt":{"attempt_id":"ACCEPTED_COLLECTION_ATTEMPT_ID","digest":"ACCEPTED_COLLECTION_RECEIPT_SHA256"}}],
+  "dispositions": [{
+    "source_id":".ace-local/review/sessions/review-SESSION#FEEDBACK_ID",
+    "reason":"Verified claim against the requirements and regression test."
+  }]
+}
+```
+
+Each completed session requires an immutable execution receipt already accepted by ace-assign's coordinator. Collect the real review under an existing managed assignment attempt, then submit a normal succeeded receipt with `operation: "review-collect"`, a passed `review-execution` check, live head and checksummed artifacts covering `metadata.yml`, the report files, both prompts, and `llm_metadata.yml` for a single-model execution. This attests successful collection, including a report containing blocking findings; it does not approve the candidate. Record its accepted attempt ID/digest in the session's `receipt` field. Collection metadata alone, a check receipt, or a receipt from a different session cannot count as executed review. Campaign commands read this proof through `ace-assign attempt evidence --kind review-collection`; they never create execution attempts or a second journal. The trusted coordinator must validate actual execution and its artifacts before accepting the collection receipt. Acceptance is that coordinator's attestation: the local operator or OS-enforced service verifies the operation and accepts its attributable outcome; worker claims cannot accept themselves. Campaigns consume this existing trust boundary and do not add a process executor or independent process-attestation system. Evidence queries read accepted receipts from the managed immutable Git journal; editable attempt caches and unmanaged histories cannot certify execution.
+
+Use `dispositions: []` for a session with no findings. Every source finding needs exactly one disposition. Findings from incomplete or unaccepted sessions cannot change campaign assessments. A completed individual module session may supply verified findings while other required scopes are still incomplete. Source status derives the disposition: pending/skip stays open, done is resolved, invalid is invalid. A confirmed High/Critical makes the round non-clean even if already resolved. The same rule applies to a High/Critical observed during partial coverage. It resets the clean streak immediately even if already resolved and that logical round never completes; completing a different round cannot preserve the old streak. Two subsequent clean rounds are still required by the default policy. Earlier findings remain open when absent from later reports. A confirmed High/Critical in a later partial round invalidates the earlier approval even if resolved; complete that round and collect the required subsequent clean reviews.
+
+`finding_id` optionally links an assessment to an existing canonical finding. Reopening requires `disposition: "reopened"` and a new verified source occurrence; terminal feedback files are never forced back to pending. Corrections are appended to campaign history. Recording preserves exact verified finding bytes under `campaigns/evidence/`, so normal pending-to-done/invalid feedback updates do not erase earlier assessments. To resolve an earlier open finding, update and verify its original feedback item, then include its existing `source_id` and a reason in the next submission alongside current sessions. Its terminal source is revalidated and snapshotted; the old report does not count as current scope coverage, and the resolution alone is not a newly observed High/Critical. A later change to a canonical finding previously confirmed High/Critical still invalidates an earlier approval, including invalidation or a severity reduction, until a completed current round covers the candidate; an empty or partial submission cannot make that old approval acceptable. A submission cannot assign two source findings to the same canonical finding ID; submit one verified assessment per canonical claim. A linked successor contract retains predecessor findings for explicit disposition.
+
+```sh
+ace-review campaign record-round CAMPAIGN_ID --input .ace-local/campaign-input/complete.json
+ace-review campaign status CAMPAIGN_ID --format json
+```
+
+Expected: complete coverage increments `completed_rounds` once. Identical replay returns `replayed: true`; conflicting content for the same attempt or completed round fails nonzero. Partial scope coverage persists as an attempt without incrementing completed or clean counters. Reusing a report from an already counted round is rejected. Provider calls, report files, recording attempts and completed rounds are separate counters.
+
+## Current approval and finish
+
+Delivery defaults are three completed rounds and two consecutive rounds without confirmed High/Critical. The default scope is `full` and required check name is `tests`. Configure `campaign.profiles.delivery` in `.ace/review/config.yml`, or supply `start --policy FILE` with exactly `revision`, `minimum_rounds`, `clean_rounds`, `required_scopes`, `required_checks`. Explicit false/null or otherwise malformed policy files fail instead of selecting defaults. The campaign freezes that revision and policy. R1 does not implement discovery profiles, round caps, automatic retries or escalation.
+
+The final round may reference an explicit approval artifact with `approval: {"path": ..., "sha256": ...}`. An approval binds an independently approved executed review already accepted by the assignment coordinator. Caller-written approval JSON alone cannot supply the verdict. It must contain:
+
+```json
+{
+  "producer":"IMPLEMENTER_ACTOR",
+  "reviewer":"ACTUAL_EXECUTED_REVIEWER_MODEL",
+  "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"}],
+  "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"
+  }}]
+}
+```
+
+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.
+
+```sh
+ace-review campaign finish CAMPAIGN_ID --format json
+```
+
+Expected: exit zero and `accepted: true` only with convergence, no unresolved High/Critical, intact current-head/base evidence, independent approval and all passing required checks. Missing GitHub CLI or authentication blocks PR start/status/finish with a parseable source-unavailable reason. Otherwise finish emits parseable JSON with `accepted: false` and reasons and exits nonzero. Save the JSON result using your calling process's file API; the CLI does not publish it.
+
+## Consume through an assignment
+
+Submit a normal succeeded review receipt through `ace-assign attempt finish`. Add this optional reference and include the identical result artifact in the receipt's verified `artifacts` array:
+
+```json
+{"campaign":{"id":"CAMPAIGN_ID","result":{
+  "path":".ace-local/campaign-input/result.json","sha256":"RESULT_SHA256"
+}}}
+```
+
+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.
+
+## 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.
+
+Start with changed requirements and `--reason "Requirement X changed"` to create a linked successor; `--predecessor ID` selects it explicitly. Same active subject/requirements/policy starts reuse one campaign, including concurrently. Requirements A → B → A create a new A successor of B; the superseded first A remains history. Restore missing active records rather than creating an orphan campaign that forgets them. Conflicting policy for an existing contract fails rather than rewriting history. A successor durably supersedes its predecessor: status keeps predecessor history and exposes `active_contract: false` and `superseded_by`, while collection, new recordings and acceptance are blocked. Old results cannot pass the assignment receipt verifier.
+
+The checksummed `.identity-index.json` retains each subject’s campaign IDs and is published before a new campaign record. A missing indexed record blocks that subject’s start/reuse, including deletion of its first record; restore the retained record to recover. Missing or corrupt indexes and unregistered records fail closed; no automatic reconstruction discards history. Subject lookup reads only its indexed records, so unrelated missing/corrupt campaign records do not block reuse. Retain the index together with the records. Existing campaign `status` and `finish` inspect their own checksummed record and successor marker.
+
+`status` is read-only and exits successfully for known blocked/stale state. Unknown/corrupt campaigns fail. `start`, `record-round` and `finish` support `--dry-run` without state writes. JSON remains parseable with `--quiet`/`--verbose`; `--format text` supplies compact presentation. No force option bypasses evidence.
+
+Retain the campaign evidence snapshots as well as original review sessions. Missing retained report: restore the exact retained artifact at its recorded path; collecting a new round does not erase the missing source requirement. Incomplete scope: use a new attempt ID for the same pinned round with complete coverage. Changed head/base: preserve history and collect current evidence. Invalid/mixed identity: correct the explicit input; no source is silently redirected. Conflicting replay: keep the accepted submission and use a new logical round for new evidence.
+
+Campaign-bound GitHub collection requires checkout `HEAD` to equal the fetched PR head before model execution. Check out the candidate first; the accepted execution receipt and runner metadata then identify the same reviewed code. Ordinary unbound PR collection continues to support a different checkout head.

data/docs/demo/ace-review-getting-started.tape.yml

@@ -0,0 +1,32 @@
+---
+description: Showcase ace-review presets, diff review, PR review, and feedback
+tags:
+- ace-review
+- docs
+- getting-started
+settings:
+  font_size: 12
+  width: 960
+  height: 540
+  format: gif
+  env:
+    PROJECT_ROOT_PATH: /home/mc/ace-t.5nx
+scenes:
+- name: Switch to project root
+  commands:
+  - type: cd $PROJECT_ROOT_PATH && clear
+    sleep: 1s
+- name: List available presets
+  commands:
+  - type: ace-review --list-presets
+    sleep: 3s
+- name: Review branch diff with preset
+  commands:
+  - type: ace-review --preset code-fit --subject diff:origin/main..HEAD --dry-run
+    sleep: 3s
+- name: Run a review
+  commands:
+  - type: ace-review --preset code-fit --subject "files:ace-retro/**/*.rb"
+    sleep: 10s
+teardown:
+- cleanup