Know What Was Reviewed, Reused, or Missed

A visible comment is only one piece of evidence about an OpenCodeReview run. The more important operational question is what happened to every selected file, especially when a run was interrupted, resumed, budget-limited, or produced no findings. This chapter follows the review lifecycle from selected denominator to terminal coverage state, then contrasts the detailed local transcript with content-sparse telemetry. The goal is to read “complete,” “partial,” “failed,” and “skipped” as different claims rather than as variations of a comment count.

That distinction extends the earlier output boundary. A finding may be unanchored yet real; a file may be successfully reviewed yet produce no comment; a later group may never be dispatched. OCR’s persistent state exists to keep those facts separate after the terminal output has disappeared.

Coverage is a lifecycle, not a comment count

Before concurrent group work begins, OCR registers the dispatchable files in a selected set and seals that denominator. A selected item is not yet a completed item. It is a promise about what this run intends to cover. Sealing the set before resume reuse and concurrent execution prevents the denominator from changing while results arrive in different orders.

Each selected item then moves toward a terminal outcome. It may complete in the current run, be reused from a compatible parent session, fail with a classified reason, or be explicitly waived where that workflow allows it. The run-level state is derived from those item outcomes. If every selected item reaches a successful terminal state, the run can be complete relative to its selected set. If some fail, it can be partial; if all selected work fails, it can be failed. With no selected work, it is skipped. These states say nothing about whether the model’s conclusions are correct. They say whether the planned review coverage reached an outcome.

stateDiagram-v2 [*] --> Selected: Scope is sealed Selected --> Completed: Review finishes Selected --> Reused: Compatible result adopted Selected --> Failed: Error or limit Selected --> Waived: Explicitly waived Completed --> RunComplete: All selected items settled Reused --> RunComplete: All selected items settled Selected --> RunPartial: Some items remain failed Failed --> RunPartial: Other items completed Failed --> RunFailed: All selected items failed [*] --> RunSkipped: Nothing selected

The state model makes a clean result more precise. A file with no comments can still be completed if the review task finished normally; “no comments” is not the same as “not reviewed.” A file omitted by a selection rule is outside the selected denominator; it should not become a failed item merely because it was never dispatched. A file left behind by an aggregate token budget is selected but failed or uncovered under the budget boundary. Those differences are what allow an operator to decide whether to accept the run, rerun a subset, or inspect a policy change.

Resume depends on preserving this lifecycle. OCR allows resume for compatible range and commit reviews, not moving workspace reviews. It replays the parent session’s append-only JSONL and uses the parent manifest as the authority for reuse.