Repository navigation
Closed
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Description
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
- 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).
- If the SHA still matches, the pre-fed context is used as-is (no extra fetch).
- 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.
- The freshness check is bounded to a single lightweight
gh pr view --json headRefOidcall (not a full metadata/diff re-fetch) and is a no-op when the prefetch flag is off. - A bats test covers matched-SHA (use cached), moved-SHA (invalidate), and flag-off (no-op) cases.
Tasks / Subtasks
- Add a cheap head-SHA re-check before agentic-tier consumption (AC: test issue from agent #1, Optimize review: small-PR and incremental fast paths #4)
- Single
gh pr view --json headRefOidcompared to the stamped SHA
- Single
- Invalidate + re-fetch or safe-skip on SHA mismatch (AC: Add @claude delegation, auto-merge, and rebase handling #3)
- Re-fetch fresh context at new HEAD, or emit the exit-100 skip sentinel for retry
- Keep it a no-op when the flag is off (AC: Optimize review: small-PR and incremental fast paths #4)
- Add bats coverage for matched / moved / flag-off (AC: feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
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.shbetween the prefetch and the tier-2 launch (~line 874), not inside a prompt. PR_HEAD_SHAis already resolved once at ~line 108 viagh pr view --json headRefOid,...; reusecompute_ci_status-style single-call patterns. The freshness call must be minimal (--json headRefOidonly).- 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.shidempotency 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.
Metadata
Metadata
Assignees
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Activity
don-petry commentedon Jul 10, 2026
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 headRefOidfreshness 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 whenPREFETCH_CONTEXT_ENABLEDis off.Implementation Checklist
scripts/lib/pr-context-prefetch.sh— newassert_prefetch_context_fresh <pr_url> [out_dir]helper: flag-gated no-op; reads the SHA stamped on the pre-fed files; one boundedgh 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 andexit 100..github/workflows/lint.yml— add the new bats test to thebatsjob 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 viascripts/run-bats.sh)don-petry commentedon Jul 10, 2026
Dev-Lead: Implementation Complete
Plan Execution
scripts/lib/pr-context-prefetch.sh— addedassert_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 boundedgh pr view --json headRefOid; returns 0 on match, invalidates files + unsetsPR_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) andexit 100. Wrapped in thePREFETCH_CONTEXT_ENABLEDgate for a byte-identical no-op when off..github/workflows/lint.yml— addedtests/test_prefetch_freshness.batsto thebatsjob 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
Also green: repo lint (
.dev-lead/scripts/dev-lead-lint.sh— shellcheck on 80 files + agent-profile validation),shellcheckon both changed scripts (only pre-existing SC1091 source-follow info), and the fulllint.ymlbats list with no regressions.Files Changed
scripts/lib/pr-context-prefetch.sh: newassert_prefetch_context_freshfreshness-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
gh pr view --json headRefOid— triage itself does not consume the pre-fed context.feat: implement issue #1106 — [Phase 3] HEAD-SHA freshness safeguard …