Problem statement
The reusable GitHub Action's incremental mode reduces duplicate publication, but it does not reduce review scope. On every pull-request update, the Action still invokes OCR over the full merge-base-to-current-head range.
This makes later pushes increasingly expensive on large pull requests even when the newest change is small.
Concrete production evidence:
The newest push changed 7 files and 323 lines. OCR reviewed the cumulative range: 63 selected files and 15,700 changed lines. The selected scope was therefore 9 times larger by file count and 48.6 times larger by changed-line count. The OCR step took 46:31 and used 3,981,022 tokens.
The behavior is present in the latest audited release, v1.7.15:
This is not a request to replace the complete immutable manifest proposed in #367. It is the Action-level range-selection and checkpoint-advancement contract that can consume that completeness state.
Proposed solution
Add an opt-in, completeness-gated cross-push range mode to the reusable GitHub Action.
The Action should maintain or consume a versioned checkpoint identifying the last compatible, completely reviewed PR head and select its range as follows:
- Initial, reopened, and ready-for-review events use the full PR merge-base-to-head range.
- A normal synchronize event uses last-complete-head-to-current-head when:
- the checkpoint belongs to the same repository and PR;
- its reviewed head is an ancestor of the current head;
- its base, OCR version, model identity, rules, and relevant policy are compatible;
- its coverage and publication state are complete.
- The Action falls back to a full PR review when state is absent, corrupt, partial, failed, canceled, incompatible, non-ancestor, or associated with a different base.
- The checkpoint advances only after OCR coverage and required publication/state persistence are complete.
- A canceled, failed, partially completed, malformed, or ambiguously published run never advances the checkpoint.
- A same-head rerun becomes an observable no-op unless full mode is explicitly requested.
- Expose a manual full-review override.
- Emit the selected mode, reason, checkpoint before/after, exact from/to SHAs, ancestry result, and source run in machine-readable output.
The immutable coverage vocabulary and terminal-state rules should come from #367 rather than introducing a second manifest format.
Acceptance criteria
- A seven-file follow-up to a previously complete review invokes OCR only for the unreviewed checkpoint-to-head range.
- Two rapid pushes where the first run is canceled cause the surviving run to cover last-complete-head through latest-head; no intervening commit is skipped.
- Force pushes, base changes, incompatible configuration, missing state, and incomplete prior runs deterministically select full fallback and report the reason.
- Raw synchronize-event before is never treated as proof that the preceding range completed.
- Checkpoint updates are authenticated, schema-validated, idempotent, and resistant to stale concurrent writes.
- Existing fork-safety and trusted-workflow guarantees are retained.
- Full-range review remains available for explicit or policy-driven use.
Alternatives considered
Use synchronize event before-to-after directly
This is unsafe when an intermediate run is canceled or fails. In the observed workflow, run https://github.com/vybestack/llxprt-code/actions/runs/29937651406 was canceled after 38:42 of OCR work. Treating the next event's before SHA as reviewed would create a coverage gap.
Use OCR resume
Released per-file resume from #265 / PR #306 is useful for retrying a compatible identical range. It validates the same textual review range and does not establish a durable last-successfully-reviewed PR head across changed ranges.
Leave checkpointing entirely to every caller
Callers can implement this, but the reusable Action already owns PR range resolution, publication state, overlap suppression, and GitHub write reconciliation. A generic, explicit Action contract avoids incompatible implementations while allowing callers to choose the persistence backend.
Continue full reviews and only suppress repeated comments
That improves presentation but does not reduce model work, tokens, or elapsed time.
Affected area
- CLI / Commands
- Output / Formatting
- Configuration
- Telemetry / Observability
- Other: reusable GitHub Action
Additional context
Related work:
The llxprt integration issue containing the measured run analysis and local workflow work is vybestack/llxprt-code#2649.
Problem statement
The reusable GitHub Action's incremental mode reduces duplicate publication, but it does not reduce review scope. On every pull-request update, the Action still invokes OCR over the full merge-base-to-current-head range.
This makes later pushes increasingly expensive on large pull requests even when the newest change is small.
Concrete production evidence:
The newest push changed 7 files and 323 lines. OCR reviewed the cumulative range: 63 selected files and 15,700 changed lines. The selected scope was therefore 9 times larger by file count and 48.6 times larger by changed-line count. The OCR step took 46:31 and used 3,981,022 tokens.
The behavior is present in the latest audited release, v1.7.15:
This is not a request to replace the complete immutable manifest proposed in #367. It is the Action-level range-selection and checkpoint-advancement contract that can consume that completeness state.
Proposed solution
Add an opt-in, completeness-gated cross-push range mode to the reusable GitHub Action.
The Action should maintain or consume a versioned checkpoint identifying the last compatible, completely reviewed PR head and select its range as follows:
The immutable coverage vocabulary and terminal-state rules should come from #367 rather than introducing a second manifest format.
Acceptance criteria
Alternatives considered
Use synchronize event before-to-after directly
This is unsafe when an intermediate run is canceled or fails. In the observed workflow, run https://github.com/vybestack/llxprt-code/actions/runs/29937651406 was canceled after 38:42 of OCR work. Treating the next event's before SHA as reviewed would create a coverage gap.
Use OCR resume
Released per-file resume from #265 / PR #306 is useful for retrying a compatible identical range. It validates the same textual review range and does not establish a durable last-successfully-reviewed PR head across changed ranges.
Leave checkpointing entirely to every caller
Callers can implement this, but the reusable Action already owns PR range resolution, publication state, overlap suppression, and GitHub write reconciliation. A generic, explicit Action contract avoids incompatible implementations while allowing callers to choose the persistence backend.
Continue full reviews and only suppress repeated comments
That improves presentation but does not reduce model work, tokens, or elapsed time.
Affected area
Additional context
Related work:
The llxprt integration issue containing the measured run analysis and local workflow work is vybestack/llxprt-code#2649.