From 4417db2b3dc30b5d407d4205a57baf8639da56e7 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 25 Aug 2026 04:03:39 -0700 Subject: [PATCH] docs(ax): name which sha a provenance check needs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "verify by sha, not by PR" rule is one step short of actionable: `gh pr view` returns two real shas for a merged PR, and because this repo squash-merges, `headRefOid` is never an ancestor of `main`. `merge-base --is-ancestor` fed the head exits non-zero, which reads as "the fix was never deployed" — the exact inversion of the check's normal use. Nothing errors, so a re-read does not catch it. Adds a rider under the existing bullet: `mergeCommit.oid` for "did this land / is it in that image", `headRefOid` only for "what did CI run against". Caught by @sprint-review on a #1161 close-out that was correct on every other fact, including the merge timestamp — which is what let the wrong sha survive. Appended under the existing rule at :2479, deliberately NOT at the end-of-file anchor where five open PRs already collide. Co-Authored-By: Claude Opus 5 --- docs/development/agent-experience-audit.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/development/agent-experience-audit.md b/docs/development/agent-experience-audit.md index c12c72a19..bf1e6031c 100644 --- a/docs/development/agent-experience-audit.md +++ b/docs/development/agent-experience-audit.md @@ -2482,6 +2482,26 @@ workflow's clock instead of the pod's, the parent commit instead of the head. entirely. If the count of check runs is zero, that is the loudest possible signal, and it prints as silence. + **Rider — which sha, for a provenance check.** "By sha" is not yet specific + enough, because `gh pr view` hands you two real ones and the wrong choice + answers rather than errors. This repo squash-merges, so a merged PR's + `headRefOid` is **never** an ancestor of `main`: + + ``` + gh pr view 1161 --json mergeCommit,headRefOid + 39032b7c mergeCommit.oid merge-base --is-ancestor origin/main → yes + 7f677235 headRefOid merge-base --is-ancestor origin/main → NO + ``` + + Both commits exist, both belong to #1161, and `--is-ancestor` fed the head + exits non-zero — which reads as *the fix was never deployed*, inverting the + conclusion of the exact check used to establish that #1161 **is** live in the + running image. There is no error state to notice. Use `mergeCommit.oid` for + "did this land / is it in that image"; use `headRefOid` only for "what did CI + run against." Caught by @sprint-review (2026-08-25) in a close-out that was + right on every other fact — the merge timestamp included, which is what made + the wrong sha survive a re-read. + **And if that comparison keeps failing, stop pushing rather than re-dispatching.** @sprint-review (57014) caught this branch taking four heads in twelve minutes against a `tests.yml` that runs 5–6 — a cadence under the