[P6] Schedule eligible pull request reviews

[richhaase]

---

steward_contract: "3"
id: "workspace-scheduler"
title: "Schedule eligible pull request reviews"
revision: 1
state: draft
created_at: "2026-07-30T16:34:04Z"
approved_at: null
approved_by: null
frozen_body_sha256: null
supersedes: null

Schedule eligible pull request reviews

Outcome

The workspace keeps eligible pull requests current without duplicate automatic reviews or unbounded concurrent work.

Scope

The scheduler obeys the shared watcher lifecycle and persisted controller decisions. It does not decide whether evidence is semantically new or whether a prior finding has recurred.

Acceptance

• AC1: Eligible pull requests are reviewed within the configured global concurrency bound.
• AC2: The same effective pull request revision is not reviewed twice automatically.
• AC3: A tracked pull request can be reviewed again after its head settles without requiring another GitHub review request.
• AC4: Release, snooze, opt-out, stop, and resume decisions control automatic work as recorded.
• AC5: Background reviews do not post results automatically.

[richhaase]

Downstream impact from #193 / #220 / PRs #222 and #221

• Changed: scheduler-facing review and trusted-refresh cancellation semantics are now explicit.
• Contract now: cancellation propagates through canonical configuration fetch and queued reviewers retain backend identity; already completed reviewers stay successful. Each dispatched run reviews one captured diff/object-ID pair.
• Compatibility or migration impact: queue cancellation/recovery must preserve completed evidence and must not restart work merely because cancellation arrived after subprocess completion.
• Required follow-up: add scheduler fixtures for cancellation during trusted fetch, while queued, and immediately after reviewer completion.
• Evidence (PR, tests, fixtures): PR [P1] Enforce trusted review-configuration sources #221 42ca3d7; PR [P1] Extract typed headless review service #222 f11439a.

[richhaase]

Downstream impact from #220 / PR #221 (9c1fad5)

• Changed: scheduler-style watch operation now distinguishes retryable preparation failure from a consumed review.
• Contract now: preparation failures retry to a five-attempt bound without using review budget; cancellation remains immediate and interrupted.
• Compatibility or migration impact: queue accounting should increment review/run counts only after preparation succeeds and semantic execution starts.
• Required follow-up: represent preparation retry state explicitly in scheduler recovery and observability.
• Evidence (PR, tests, fixtures): internal/watch retry-without-budget and exhaustion regressions.

[richhaase]

Downstream impact from #220 / PR #221 (a1ea07b)

• Changed: scheduled preparation retries are scoped to the exact failed head.
• Contract now: retry immediately only if the queued PR head is unchanged; a new head must settle normally, and obsolete pending approval state is cleared when replacement work starts.
• Compatibility or migration impact: scheduler retry records need the associated head SHA and must not preserve superseded action eligibility.
• Required follow-up: model retry head and approval invalidation in queue/recovery fixtures.
• Evidence (PR, tests, fixtures): PR [P1] Enforce trusted review-configuration sources #221 a1ea07b; changed-head settle and obsolete-approval tests.

[richhaase]

Downstream impact from #220 / PR #221 (c1cdafb)

• Changed: scheduler-style preparation retry exhaustion is scoped to the exact queued head.
• Contract now: replacing head A with head B clears A's consecutive preparation-failure count; B settles and starts with a fresh five-attempt allowance.
• Compatibility or migration impact: recovery state must key retry count and retry head together so superseded failures do not poison later work.
• Required follow-up: include cross-head reset behavior in queue persistence/recovery and fake-clock scheduler fixtures.
• Evidence (PR, tests, fixtures): PR [P1] Enforce trusted review-configuration sources #221 c1cdafb; changed-head retry reset regression.