Skip to content

[Phase 3] HEAD-SHA freshness safeguard so no tier reviews stale pre-fed context #1106

Closed

Description

@github-actions

Story

As a pipeline maintainer,
I want verify the PR head SHA still matches the pre-fed context's stamped SHA before the expensive agentic tiers consume it, and invalidate/re-fetch when a force-push moved HEAD,
so that the pre-agentic optimization can never cause a review of stale code, neutralizing the staleness objection raised in the idea's adversarial review.

Acceptance Criteria

  1. Before the deep/audit/single tiers consume pre-fed context, the cascade cheaply re-checks the PR's current head SHA against the SHA stamped on the pre-fed files (Story 2).
  2. If the SHA still matches, the pre-fed context is used as-is (no extra fetch).
  3. If HEAD moved (force-push / new push mid-run), the stale pre-fed context is discarded and the run either re-fetches fresh context at the new SHA or safely skips (exit-100 sentinel) to be retried — never proceeds on stale data.
  4. The freshness check is bounded to a single lightweight gh pr view --json headRefOid call (not a full metadata/diff re-fetch) and is a no-op when the prefetch flag is off.
  5. A bats test covers matched-SHA (use cached), moved-SHA (invalidate), and flag-off (no-op) cases.

Tasks / Subtasks

Dev Notes

  • The idea's adversarial rebuttal proposes exactly this: the cheap tier validates that HEAD still matches what was pre-fetched before the expensive deep review runs. Implement it as a shell check in review-one-pr.sh between the prefetch and the tier-2 launch (~line 874), not inside a prompt.
  • PR_HEAD_SHA is already resolved once at ~line 108 via gh pr view --json headRefOid,...; reuse compute_ci_status-style single-call patterns. The freshness call must be minimal (--json headRefOid only).
  • On mismatch, prefer re-fetch at the new SHA (cheap, keeps the review useful) but the exit-100 skip sentinel is an acceptable safe fallback — the scheduler re-runs and the idempotency marker prevents duplicate reviews (review-one-pr.sh idempotency block ~line 318).
  • Within a single review-one-pr.sh invocation the tiers run seconds apart in one process, so real staleness is rare — but this closes the window deterministically and is the safeguard that lets Story 6 recommend default-on.
  • Depends only on Story 2's SHA-stamped files; independent of the prompt rewires (Stories 3-4). Testing via tests/ bats wired into lint.yml.

Project Structure Notes

Localized to scripts/review-one-pr.sh (optionally the Story 2 helper lib). New bats test under tests/, listed in .github/workflows/lint.yml.

References

  • scripts/review-one-pr.sh#head-sha
  • scripts/review-one-pr.sh#idempotency
  • scripts/lib/ci-status.sh

Likely target surface

  • scripts/review-one-pr.sh
  • .github/workflows/lint.yml

Story prepared by the BMAD Scrum Master (Bob) for epic #1101. Status: ready-for-dev.

Activity

  1. don-petry commented on Jul 10, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #1106 — [Phase 3] HEAD-SHA freshness safeguard so no tier reviews stale pre-fed context

    Scope

    Add a cheap gh pr view --json headRefOid freshness re-check that runs after triage and before the agentic tiers (single/deep/audit) consume the Story 2 pre-fed context; on a moved HEAD it invalidates the stale context and takes the exit-100 skip sentinel so the scheduler re-runs at the new SHA. No-op when PREFETCH_CONTEXT_ENABLED is off.

    Implementation Checklist

    • scripts/lib/pr-context-prefetch.sh — new assert_prefetch_context_fresh <pr_url> [out_dir] helper: flag-gated no-op; reads the SHA stamped on the pre-fed files; one bounded gh pr view --json headRefOid; returns 0 on match, invalidates files + unsets exports and returns 100 on mismatch; degrades to 0 on gh failure.
    • scripts/review-one-pr.sh — call the helper after triage completes (~line 794) and before the single/deep/audit branch; on return 100 emit the skip JSON and exit 100.
    • .github/workflows/lint.yml — add the new bats test to the bats job list.

    Tests to Write

    • tests/test_prefetch_freshness.bats — matched-SHA (use cached, files intact), moved-SHA (return 100, files invalidated, exports unset), flag-off (no-op, zero gh calls); plus nothing-prefed no-op and gh-failure degrade-to-proceed.

    Test Command

    bats tests/test_prefetch_freshness.bats (full suite via scripts/run-bats.sh)

  2. don-petry commented on Jul 10, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • scripts/lib/pr-context-prefetch.sh — added assert_prefetch_context_fresh <pr_url> [out_dir]: flag-gated no-op; reads the SHA stamped on the pre-fed files (metadata .pr_head_sha, falling back to the diff # PR_HEAD_SHA: header); one bounded gh pr view --json headRefOid; returns 0 on match, invalidates files + unsets PR_CONTEXT_* exports and returns 100 on mismatch; degrades to 0 on gh failure.
    • scripts/review-one-pr.sh — call the helper right after triage (~line 795) and before the single/deep/audit branch; on return 100 emit the skip JSON (reason":"head-moved-stale-context) and exit 100. Wrapped in the PREFETCH_CONTEXT_ENABLED gate for a byte-identical no-op when off.
    • .github/workflows/lint.yml — added tests/test_prefetch_freshness.bats to the bats job list.
    • tests/test_prefetch_freshness.bats — matched / moved / flag-off (AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5) plus nothing-prefed and gh-failure degrade cases.

    Test Results

    1..6
    ok 1 freshness OFF (unset): no-op, no gh call
    ok 2 freshness OFF (explicit false): no-op, no gh call
    ok 3 freshness ON matched: returns 0 and keeps the pre-fed context
    ok 4 freshness ON moved: invalidates stale context and returns 100
    ok 5 freshness ON but nothing pre-fed: no-op returns 0, no gh call
    ok 6 freshness ON gh failure: degrades to 0 and keeps the pre-fed context
    

    Also green: repo lint (.dev-lead/scripts/dev-lead-lint.sh — shellcheck on 80 files + agent-profile validation), shellcheck on both changed scripts (only pre-existing SC1091 source-follow info), and the full lint.yml bats list with no regressions.

    Files Changed

    • scripts/lib/pr-context-prefetch.sh: new assert_prefetch_context_fresh freshness-check helper.
    • scripts/review-one-pr.sh: invoke the freshness check between triage and the agentic tiers; safe-skip (exit 100) on a moved HEAD.
    • .github/workflows/lint.yml: register the new bats file.
    • tests/test_prefetch_freshness.bats: new coverage.

    Notes

    • Placed the single check after triage and before the branch so it covers all three agentic consumers (single / deep / audit) with one gh pr view --json headRefOid — triage itself does not consume the pre-fed context.
    • On a moved HEAD the run takes the safe-skip (exit 100) fallback (AC Add @claude delegation, auto-merge, and rebase handling #3's accepted alternative to in-process re-fetch): the scheduler re-runs, resolves the new head SHA, re-prefetches, and the idempotency marker (no marker is written on this skip) prevents a duplicate review.
    • gh failure on the check degrades to proceed on the already-SHA-bound context rather than crashing, avoiding a skip/retry storm on a transient blip.
  3. added a commit that references this issue on Jul 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions