Define review-fix-loop invocation, checkpoint, and terminal-result contracts

[shaug]

Outcome

Define and validate the public invocation, checkpoint, grant, cycle-budget, review-record, and terminal-result contracts for review-fix-loop.

Parent epic: #95
Design: design/review-fix-loop.md

Scope

• Add the skill-local schemas and validation needed by later implementation leaves.
• Model cycle budgets as invocation-scoped state.
• Define the terminal states and their caller-facing mappings.
• Represent selected and declined findings, validation evidence, retained commits, publication state, and required operator action.
• Reject unsupported review-only and zero-cycle invocations.
• Keep acceptance ownership and caller-specific ledgers outside this skill.

Non-goals

• Running reviewers or applying fixes.
• Locking, worktree management, recovery, or publication.
• Migrating existing callers.

Acceptance criteria

• Valid examples for both local_commit and update_pr pass strict validation.
• Invalid or ambiguous inputs fail closed with actionable diagnostics.
• Zero-cycle and review-only requests are rejected.
• Cycle consumption and remaining budget can be reconstructed from checkpoint history.
• Every terminal state has an explicit publication/retained-commit/operator-action contract.
• Contract serialization is deterministic and covered by complete snapshots.

Validation

• Unit tests for valid, invalid, boundary, and round-trip cases.
• Repository just format, just lint, and just test.

Dependencies

No implementation dependency. This is the foundation for the execution and reviewer-orchestration leaves.

[shaug]

Merged via #107 (merge commit 2750038, PR head 99094f87d31f018ce162c4a08ab78fe5f0bb6bc1), independently verified on main: git merge-base --is-ancestor 99094f8 origin/main confirms the PR head is present on mainline.

Acceptance criteria — verified against the merged mainline checkout

• Valid examples for both local_commit and update_pr pass strict validation.
• Invalid or ambiguous inputs fail closed with actionable diagnostics.
• Zero-cycle and review-only requests are rejected.
• Cycle consumption and remaining budget can be reconstructed from checkpoint history.
• Every terminal state has an explicit publication/retained-commit/operator-action contract.
• Contract serialization is deterministic and covered by complete snapshots.

Validation (rerun against a fresh origin/main checkout post-merge)

• python3 -m unittest discover -s skills/review-fix-loop/scripts/tests -p 'test_*.py' — 115/115 pass.
• just format — pass, no reformatting needed.
• just lint — pass, including skills-ref validate skills/review-fix-loop.
• just test — full repository suite (implement-epic, implement-ticket, babysit-pr, carve-changesets, all four review skills, review-fix-loop's own 115 tests, review-suite's 310 tests) — pass, no failures.

Review history

11 full review-code-change passes across 10 fix cycles converged on a systematic completeness sweep against design/review-fix-loop.md's enumerated field lists (full detail in #107's description). The final (11th) pass found one more item, deliberately not fixed in this round and recorded below as a disclosed follow-up.

Known follow-up (not fixed in this round; carried forward)

validate_terminal_result does not enforce that a validation_summary entry with status passed/failed carries result, or that an unavailable entry carries reason — validate_checkpoint already enforces this for the identically-shaped validation_outcomes, and references/CONTRACT.md documents that validation_summary "follows the same status/result/reason shape as every other validation collection in this contract family," so this is a real gap against the candidate's own documented contract, not a new requirement. Reproduced directly against the checked-in examples (stripping result from a converged example's passed entries, and appending diagnostically-empty failed/unavailable entries to changes_remaining/blocked examples all validate with zero errors). Proposed fix: add a loop in validate_terminal_result over validation_summary mirroring validate_checkpoint's existing loop over validation_outcomes, plus a covering test. Left to a follow-up ticket or the next review-fix-loop child that touches this validator, since it is independent, well-scoped, and does not block #97/#98's contract dependency on this ticket.

Closing as delivered. Refs #95.