From c18e7b27c305eddad1b0ef1c4db32df6e4d91b21 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Mon, 24 Aug 2026 23:16:37 -0700 Subject: [PATCH 1/2] docs(ax): mechanism 4 said the base decides, without the condition that makes it true MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Entry 41's mechanism 4 read "the BASE branch's copy of the file decides whether the event matches" — unconditionally. That is true of #1132, whose head touched one file and it was not `tests.yml`, and false in general: the merge ref is base + head, so a head that edits the workflow contributes its own version and can fix its own triggering. The unqualified form is the sentence a reader lifts. Someone with a stacked PR that DOES edit a workflow would conclude their head cannot help and reach for the wrong remedy — a rebase they do not need, or a manual dispatch that manufactures the artifact whose absence was the symptom. The precise version was already in the same sentence ("merge ref, which is base + head"), so this is a clause rather than a rewrite. Caught by sprint-review at 57534; the qualifier existed at 57497 and did not survive into the entry. Co-Authored-By: Claude Opus 5 --- docs/development/agent-experience-audit.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/development/agent-experience-audit.md b/docs/development/agent-experience-audit.md index c12c72a19..9094fcba4 100644 --- a/docs/development/agent-experience-audit.md +++ b/docs/development/agent-experience-audit.md @@ -2394,12 +2394,14 @@ considered and declined, or the next reader re-derives it. 4. *The base branch predates the workflow fix* → the fix never applies. For a `pull_request` event GitHub reads the workflow definition from the **merge - ref**, which is base + head — so the BASE branch's copy of the file decides - whether the event matches. `#1123` dropped `branches: [main]` from - `tests.yml` on main at 15:20:27Z, and `#1132` still got zero test runs from - a head pushed at 18:11:30Z, three hours later, because its base - (`docs/ax-two-call-sites`, last touched 06:52) still carries the old - filter. Verified by reading `tests.yml` on that branch. + ref**, which is base + head — so when the head does not touch that workflow + file, the BASE branch's copy of it decides whether the event matches. A head + that edits the workflow itself contributes its version to the merge ref and + can fix its own triggering; that is not the case below. `#1123` dropped + `branches: [main]` from `tests.yml` on main at 15:20:27Z, and `#1132` still + got zero test runs from a head pushed at 18:11:30Z, three hours later, + because its base (`docs/ax-two-call-sites`, last touched 06:52) still + carries the old filter. Verified by reading `tests.yml` on that branch. Its whole check list is one skipped `Release Branch Guard`, and its `mergeStateStatus` is `CLEAN` — nothing failing, because nothing ran. From 57492c144c718702a53c7cdc92a86a4d83854100 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 25 Aug 2026 02:48:51 -0700 Subject: [PATCH 2/2] docs(ax): mark the two evidence classes inside mechanism 4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @sprint-review 58119: the qualifying clause and the example it qualifies do not rest on the same kind of evidence, and the entry read as though they did. The example is verified here — pre-#1123 the block was `branches: [main, v1.0.x]` with no `paths:` at all, so the filter is the SOLE candidate cause. My earlier basis (reading tests.yml and finding the filter present) established presence only, which any competing cause would also survive. The clause is not. "A head that edits the workflow contributes its version to the merge ref" is a GitHub platform rule and nothing in this repo reads it — no PR here has edited a workflow its own base would have excluded. It is documentation of the platform, not a measurement of us, and it now says so. Same standing as the `edited` line already flagged that way elsewhere in the entry. A reader who lifts the clause should know it has not been exercised against this history. Docs-only. Co-Authored-By: Claude Opus 5 --- docs/development/agent-experience-audit.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/development/agent-experience-audit.md b/docs/development/agent-experience-audit.md index 9094fcba4..afba3781b 100644 --- a/docs/development/agent-experience-audit.md +++ b/docs/development/agent-experience-audit.md @@ -2401,7 +2401,19 @@ considered and declined, or the next reader re-derives it. `branches: [main]` from `tests.yml` on main at 15:20:27Z, and `#1132` still got zero test runs from a head pushed at 18:11:30Z, three hours later, because its base (`docs/ax-two-call-sites`, last touched 06:52) still - carries the old filter. Verified by reading `tests.yml` on that branch. + carries the old filter. + + **Evidence classes differ across this mechanism, and the difference is worth + marking.** The example is verified *here*: pre-`#1123` the block was + `pull_request: branches: [main, v1.0.x]` with no `paths:` at all, so the + filter is the sole candidate cause rather than merely a present one — an + earlier basis established only that it was present, which a competing cause + would survive. The qualifying clause is different: *"a head that edits the + workflow contributes its version to the merge ref"* is a **GitHub platform + rule, unverified in this repo** — no PR here has edited a workflow its own + base would have excluded, so nothing in this history reads it. It is + documentation of the platform, not a measurement of us. (@sprint-review, + 58118/58119. Same standing as the `edited` line elsewhere in this entry.) Its whole check list is one skipped `Release Branch Guard`, and its `mergeStateStatus` is `CLEAN` — nothing failing, because nothing ran.