fix(gator): preserve resolved review feedback

[drew]

Summary

Make Gator reviews durable, pragmatic, and convergent across pull request revisions.

The original issue was repeated feedback on #2471: each new head triggered a reviewer without the prior inline-thread replies, resolutions, or maintainer waivers, so rejected feedback appeared new again. This PR now addresses that root cause and the broader review patterns found in the Gator retrospective: scope drift into unchanged code, duplicate invariant findings, rebase-triggered rereviews, unsupported edge-case blockers, and open-ended review iteration.

Related Issue

None.

Changes

• build a paginated review-feedback ledger containing review summaries, general findings, inline threads, replies, resolution state, resolver identity, stable finding IDs, and first-seen review heads
• establish explicit review scope:
  • initial reviews inspect the complete PR
  • follow-up reviews inspect unresolved obligations plus the author-only delta since the previous reviewed revision
  • unchanged code cannot produce a new finding without newly available evidence of a Critical security, data-loss, or correctness defect
• preserve trusted maintainer resolutions and waivers across revisions and carry open findings forward without duplicate threads
• use base SHA, merge-base SHA, and stable patch IDs to recognize equivalent patches across rebases and avoid treating upstream-only changes as new PR scope
• group equivalent cases under one invariant and stable finding ID instead of reporting sibling examples over successive passes
• distinguish blocking findings from advisory feedback:
  • blockers must be concrete, reachable, materially introduced or worsened by the PR, and proportionate to fix
  • suggestions do not block or repeat on follow-up passes
  • pre-existing and orthogonal hardening is routed to follow-up work
• add a machine-validated reviewer findings contract requiring prerequisite, supported entry point, sink, changed location, base-versus-head behavior, impact, deterministic reproducer, PR ownership, and requested change
• automatically downgrade unsupported blockers and duplicate-invariant proposals to non-blocking hypotheses
• add a human convergence checkpoint after three finding-bearing rounds; autonomous Warning findings stop until a maintainer accepts the scope, splits follow-up work, waives an obligation, or authorizes another round
• stop autonomous review when remediation materially grows the PR into another subsystem, non-goal, or public configuration/policy surface
• require invariant-level remediation matrices for security-sensitive state machines so related protocol, identity, revocation, fallback, and trust-boundary cases are reviewed together
• add reviewer-quality telemetry for duplicate proposals, waived or resolved findings raised again, unchanged-code proposals, first-seen SHAs, finding-bearing rounds, convergence, and missing reproducers
• make the GitHub write guard fail closed when it cannot verify the current head or prior Gator dispositions, and require the exact head SHA and Gator payload version on review writes
• version the immutable Gator payload, bundle supporting resources through the launcher, and make stale watchers stop without GitHub writes so operators can rebuild and relaunch them
• update the Gator prompt, gate skill, reviewer persona, image, launcher skill, and operational documentation for the new workflow

Testing

• bash scripts/agents/gator/bin/review_feedback_ledger_test.sh
• bash scripts/agents/gator/bin/gh_guard_test.sh
• bash scripts/agents/gator/bin/validate_review_findings_test.sh
• bash scripts/agents/runtime/supervisor_test.sh
• uv run /Users/anewberry/.codex/skills/.system/skill-creator/scripts/quick_validate.py scripts/agents/gator/skills/gator-gate
• live ledger validation against fix(gator): preserve resolved review feedback #2533
• live legacy-history replay against test(e2e): add reusable QEMU infrastructure for E2E tests #2471, which correctly entered the convergence checkpoint
• mise run pre-commit
• mise run test

Checklist

• Tests cover the new behavior
• Agent workflow documentation is updated
• Gator skill structure validates
• Full pre-commit suite passes
• Full test suite passes

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.