feat(review-fix-loop): define invocation, checkpoint, and terminal-result contracts

CHANGELOG.md

@@ -4,15 +4,96 @@ summary: Chronological history of repository and skill changes.
 
 # Changelog
 
-## 2026-07-30 — Removed the unproven verification-sufficiency pass and its required-evidence field from review-correctness, and simplified the review-fix-loop design around local coordination and Git-native publication safety
+## 2026-07-30 — Defined the review-fix-loop invocation, checkpoint, and terminal-result contracts, removed the unproven verification-sufficiency pass and its required-evidence field from review-correctness, and simplified the review-fix-loop design around local coordination and Git-native publication safety
 
+- fix(review-fix-loop): reject `converged` when any `review_records` entry — not
+  only the final-head-bound one — recorded a mutation attempt, closing the gap
+  the tenth (final) review-code-change pass on #96 found
+- fix(review-fix-loop): add a per-pass `reviewer_identity` field to
+  `review_records` in both checkpoint and terminal-result, and reject a dirty
+  `candidate.worktree` (`staged`/`unstaged`/`untracked`) in
+  `validate_invocation`, closing the two gaps the ninth review-code-change pass
+  on #96 found (`4daa2a67a38be3baa7741380eb689581ce31a1db`)
+- docs: record the ninth review-fix-loop fix cycle in the changelog
+  (`80690173571678bb14d14703451a8ab6d29b2cba`)
+- fix(review-fix-loop): complete the terminal-result schema against the design's
+  Terminal result contract field list (`worktree`, `resume_status`,
+  `unresolved_or_deferred_findings`) and require `ahead_by`/`behind_by`
+  alongside the head fields whenever a source is `bound`, closing the gaps the
+  eighth review-code-change pass on #96 found
+  (`adf2ef5062038836d750b01e19f1549373ce1aad`)
+- docs: record the eighth review-fix-loop fix cycle in the changelog
+  (`65a256a32b3087d064efb5e4a24725cfb1762467`)
+- fix(review-fix-loop): complete the checkpoint schema against the design's
+  durable-checkpoint field list (`preserved_failed_attempts`, `pull_request`)
+  and extend the optional pull-request identity cross-check to both
+  cross-document functions, closing the gap the seventh review-code-change pass
+  on #96 found (`e7a955a321bafab1cd6f20b77758aa26670567bc`)
+- docs: record the seventh review-fix-loop fix cycle in the changelog
+  (`f6d1adccea4ee1e6571c911b10053aa4c27e00ba`)
+- docs: record the sixth review-fix-loop fix cycle in the changelog
+  (`31789481f000567a4b69cb0a1d5ba77b8d8c4dba`)
+- fix(review-fix-loop): systematically close cross-document identity checks and
+  commit provenance, enumerating the complete invariant field set
+  (`invocation_id`, `repository`, `branch`, original fix-cycle budget,
+  `publication.policy`, initial head, initial comparison base) that must agree
+  across invocation, checkpoint, and terminal-result, closing the one remaining
+  gap (`branch` in `validate_checkpoint_against_invocation`) plus the
+  commit-provenance gap (`created_commits`/`fix_commit_sha` linkage) the sixth
+  review-code-change pass on #96 found
+  (`040ae824fae708efe46ca772f378c30378c9c695`)
+- fix(review-fix-loop): add the missing repository/branch/publication.policy
+  checkpoint cross-check, the design-enumerated `allowed_remediation_scope`,
+  `worktree`, and `validation_outcomes` schema fields, and correct a
+  misattributed changelog SHA, closing all three items the fifth
+  review-code-change pass on #96 found
+  (`a6178b8da086fab80bd52596babb0208304163a1`)
+- docs: record the fifth review-fix-loop fix cycle in the changelog
+  (`e71ea93ad98beec7b39cf6bb6c2a123743e820cf`)
+- fix(review-fix-loop): add validate_checkpoint_against_invocation cross-check,
+  symmetric to the existing `validate_terminal_against_checkpoint`, closing the
+  gap the fourth review-code-change pass on #96 found: nothing inside a
+  checkpoint document alone could prove `base_revision_history[0]` was the
+  invocation's real original comparison base
+  (`c625bb87b7aefb2371b992b20e4ce07b12b1c270`)
+- docs: record the coordinator-authorized fourth fix cycle in the changelog
+  (`2f3addbdceefb0a952fa1fb035475d0a9d31ebfb`)
+- fix(review-fix-loop): require non-empty scoped validation and full base
+  history match, closing two remaining gaps the third review-code-change pass on
+  #96 found: an empty or scope-incomplete `validation_summary` could still claim
+  `converged`, and the checkpoint/terminal-result cross-check compared only the
+  final comparison base, never the initial one
+  (`3d240c6be6a33bf131aa7ccee2544c59a36614c1`)
+- docs: record the third review-fix-loop fix cycle in the changelog
+  (`86c7df20d44d0c398c34bee5b8272dca4b239cf7`)
+- docs: record the comparison_base cross-check fix in the changelog
+  (`7d206acd32151405865c4ade4e9e7399ea739f57`)
+- fix(review-fix-loop): check comparison_base in the checkpoint/terminal-result
+  cross-check, closing a gap where `validate_terminal_against_checkpoint`
+  silently omitted the base-identity leg CONTRACT.md already documented it as
+  covering, found by the second review-code-change pass on #96
+  (`e18f1469cf6d5f5cff1d99045dd041cdc5e77b71`)
+- docs: record the converged-evidence fix in the changelog
+  (`1c9fcdc5f4ae5765414f4b25839c07122c3bb151`)
+- fix(review-fix-loop): reject converged results with non-clean embedded
+  evidence, closing a gap where `validate_terminal_result` never inspected
+  `review_records` or `validation_summary`, found by the initial
+  review-code-change pass on #96 (`fc701b0bb29047af7b2ad24f25fb1db739718f89`)
+- docs: record the review-fix-loop contracts changelog entry
+  (`461db19fdd89e65afdf1c13fb870c5c427c00b67`)
+- feat(review-fix-loop): define invocation, checkpoint, and terminal-result
+  contracts, adding the skill-local schemas, a dependency-free validator, and 62
+  unit tests covering valid, invalid, boundary, cross-document, and
+  round-trip/determinism cases for both `local_commit` and `update_pr` (#96)
+  (`0689cda71833751249ebc5e65b766d231cf2c093`)
 - feat(review-suite)!: remove the verification-sufficiency pass and its
   mandatory `verification_sufficiency_evidence` field from `review-correctness`
   and the shared review-result contract, advancing `schema_version` `1.3 → 1.4`;
   the traversal (consumer/impact) pass and `consumer_impact_evidence` are
   unchanged, per #57's ablation matrix and #89's harder-case validation finding
   no demonstrated value for the removed pass plus a confirmed, twice-reproduced
   false-positive regression when it ran without the traversal pass (#93)
+  (`b91e12b063ea6d7ed49f152ee359f1f0eb326363`)
 - docs: simplify the review-fix-loop design
   (`2e7a8cd93af9f2c8cec36d6c393694f7849adedb`)
 

skills/review-fix-loop/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: review-fix-loop
+description: Validate the review-fix-loop invocation, checkpoint, and terminal-result contracts that later children of epic #95 use to run the standalone review-remediation workflow. Use when authoring, resuming, or terminating a review-fix-loop invocation to check its documents against the shared schemas before trusting or acting on them. This child does not yet run reviewers, apply fixes, acquire locks, manage worktrees, or publish anything; see design/review-fix-loop.md and references/CONTRACT.md for the full behavioral design and current implementation status.
+allowed-tools: Read, Bash
+---
+
+# Review Fix Loop
+
+`review-fix-loop` will become a repository-owned skill that takes cooperative
+ownership of an existing committed candidate, runs the complete repository
+review suite, applies material ticket-scoped fixes, and repeats until review
+converges or a bounded stop condition is reached. The full design is
+[`design/review-fix-loop.md`](../../design/review-fix-loop.md).
+
+This child ([issue #96](https://github.com/shaug/agent-scripts/issues/96), the
+first of epic [#95](https://github.com/shaug/agent-scripts/issues/95)) defines
+and validates only the contracts later children build on:
+
+- the **invocation** a caller or standalone operator supplies to start or resume
+  a loop;
+- the **durable checkpoint** the loop would record between phases; and
+- the **terminal result** the loop returns.
+
+It does not run a reviewer, apply a fix, acquire a lock, manage a worktree,
+recover from interruption, or publish anything — those behaviors belong to
+issues #97 (local locking, isolated attempts, and recovery), #98 (reviewer
+isolation and orchestration), #99 (`local_commit`), and #100 (`update_pr`). Do
+not invoke this skill expecting an executable review-fix loop yet; use it to
+validate a document you or a later child produced against the shared schemas.
+
+## Load the contracts
+
+Read [`references/CONTRACT.md`](references/CONTRACT.md) and the three schemas
+beside it before authoring or trusting any invocation, checkpoint, or
+terminal-result document:
+
+- [`references/invocation.schema.json`](references/invocation.schema.json)
+- [`references/checkpoint.schema.json`](references/checkpoint.schema.json)
+- [`references/terminal-result.schema.json`](references/terminal-result.schema.json)
+
+[`references/examples/`](references/examples) contains complete, valid documents
+for both the `local_commit` and `update_pr` publication policies, including a
+`changes_remaining` and a `blocked` terminal result, each already in the
+canonical serialized form `scripts/validate.py` produces.
+
+## Validate a document
+
+`scripts/validate.py` is dependency-free, matching the convention used by the
+bundled `review-code-change` review-suite contract, so it works wherever this
+skill is installed:
+
+```bash
+python3 skills/review-fix-loop/scripts/validate.py invocation path/to/invocation.json
+python3 skills/review-fix-loop/scripts/validate.py checkpoint path/to/checkpoint.json
+python3 skills/review-fix-loop/scripts/validate.py terminal-result path/to/result.json
+```
+
+Each prints `valid <kind>: <path>` and exits `0` on success, or prints one
+diagnostic per violation to stderr and exits `1`. A malformed document exits
+`2`.
+
+The module also exposes importable functions for a caller that already holds
+parsed documents in memory: `validate_invocation`, `validate_checkpoint`,
+`validate_terminal_result`, `reconstruct_cycle_accounting` (derive consumed and
+remaining fix cycles from a checkpoint's recorded attempts),
+`validate_checkpoint_against_invocation` (confirm a checkpoint's initial head,
+original base, cycle budget, invocation ID, repository, and publication policy
+match the invocation it derives from), and
+`validate_terminal_against_checkpoint` (confirm a terminal result's budget and
+head/base identities match the checkpoint it derives from). See
+[`references/CONTRACT.md`](references/CONTRACT.md) for the cross-field semantics
+these functions enforce beyond plain JSON Schema, and
+`scripts/tests/test_validate.py` for the complete valid, invalid, boundary, and
+round-trip case coverage.
+
+## Non-goals of this child
+
+- Running a reviewer or applying a fix.
+- Acquiring a local or remote-target lock, managing a worktree, or recovering an
+  interrupted attempt.
+- Publishing anything, including the `update_pr` expected-old fast-forward
+  update.
+- Migrating `implement-ticket`, `babysit-pr`, `carve-changesets`, or any other
+  existing caller.
+- Owning acceptance criteria or a caller-specific acceptance ledger — the
+  contract records `acceptance_reconciliation_required` but the caller always
+  retains its own ledger.