diff --git a/.github/workflows/docs-drift-check.yml b/.github/workflows/docs-drift-check.yml
index f1f7275cd3..a3bf7b7f58 100644
--- a/.github/workflows/docs-drift-check.yml
+++ b/.github/workflows/docs-drift-check.yml
@@ -17,6 +17,13 @@ name: Docs Drift Check
# because they document it through the SDK, which does not depend on the implementing
# package. The comment now also states what the run could NOT see — the derivation being
# read past its precision, with its silence taken for absence, is what #9192 records.
+#
+# And since #9519 it states WHICH TREE it read. On `pull_request`, actions/checkout gives
+# the MERGE of base and head, so the row set is a fact about a commit that exists on no
+# branch a reader can name — while the comment's own re-derivation command sent them to
+# run the tool on their own worktree. A reader who did that got a different list and
+# reported a correct row as a false positive, and the investigation of the non-existent
+# defect cost a full round. Same posture, one more thing the run knows and used not to say.
on:
pull_request:
@@ -98,7 +105,89 @@ jobs:
const crossCutting = data.crossCuttingSymbols || [];
const weak = data.weakAnchorsDropped || [];
const coarse = data.packageMentionDocs || [];
- const rederive = `node scripts/docs-audit/affected-docs.mjs --json origin/${baseRef}`;
+ // ── WHICH TREE THIS WAS COMPUTED ON (#9519) ─────────────────────────────
+ // The row set is a fact about two commits and this comment named neither.
+ // Pages are read with `readFileSync` from the WORKING TREE, and on a
+ // `pull_request` run `actions/checkout` gives us merge(base, head) — a tree
+ // that exists on no branch a reader can name and that GitHub drops once the
+ // PR closes. The change set is a diff whose base was published only as
+ // `origin/`, a moving NAME. The re-derivation command below then sent
+ // the reader to run the tool against THEIR tree, so a page that gained or
+ // lost an anchor token on the base branch after their worktree was cut
+ // produced a row they could not reproduce, with nothing here to say why.
+ //
+ // Measured: a reader did exactly that, grepped, found nothing, and reported
+ // a correct row as a false positive; the follow-up then investigated a
+ // defect class that does not exist in this tool — the anchor set is derived
+ // fresh per run, with no cache, index or snapshot anywhere — at the cost of
+ // a full round. Naming the tree is this file's own #9192 posture (say what
+ // the run could not see) applied to one more thing the run already knows.
+ //
+ // The mapper change behind this is strictly ADDITIVE: `computedOn` is read
+ // off git at the emit boundary, after every derivation has finished, so no
+ // row above depends on it. Verified byte-for-byte against the pre-change
+ // mapper on three refs — the `computedOn` block is the entire diff.
+ const computedOn = data.computedOn || {};
+ const parents = Array.isArray(computedOn.headParents) ? computedOn.headParents : [];
+ // Parent ORDER on `refs/pull/N/merge` (base first, head second) is GitHub's
+ // convention, not git's, so it is CHECKED against the event payload rather
+ // than assumed — the pair is labelled only when the payload says which is
+ // which, and stays unlabelled otherwise. A confidently wrong label would
+ // send a reader off to rebuild the mirror image of the tree.
+ const prHeadSha = context.payload.pull_request.head.sha;
+ const mergedHead = parents.find(p => p === prHeadSha) || null;
+ const mergedBase = mergedHead ? (parents.find(p => p !== mergedHead) || null) : null;
+ // The COMMIT the mapper measured its diff from — the three-dot merge-base it
+ // had already resolved, not `origin/` re-read later. Naming the commit
+ // is what makes the command replayable from any clone; naming the branch is
+ // what made it a trap.
+ const diffBase = computedOn.diffBase || null;
+ const rederive = `node scripts/docs-audit/affected-docs.mjs --json ${diffBase || `origin/${baseRef}`}`;
+ const treeBlock = (() => {
+ // ⛔ Never degrade to silence here. An unnamed tree is the exact state this
+ // block exists to end, so a missing identity is SAID, not omitted.
+ if (!computedOn.head) {
+ return ['', '> ⚠️ This run could not identify the commit it read, so the list above cannot be'
+ + ' tied to a tree. Re-derive against your own checkout and compare by hand.'];
+ }
+ const lines = [
+ '',
+ 'Which tree this was computed on
',
+ '',
+ mergedHead && mergedBase
+ ? `This run read \`content/docs\` from \`${computedOn.head}\` — the merge of head`
+ + ` \`${mergedHead}\` into base \`${mergedBase}\`, which is what \`actions/checkout\``
+ + ` gives a \`pull_request\` run. **Not** the PR head.`
+ : `This run read \`content/docs\` from \`${computedOn.head}\`.`,
+ '',
+ `A worktree cut from an older \`${baseRef}\` holds a different \`content/docs\`, so re-deriving`
+ + ` there can legitimately return a different list — that is a **different tree, not a wrong`
+ + ` row**. To answer on the same tree:`,
+ '',
+ '```sh',
+ ];
+ if (mergedHead && mergedBase) {
+ lines.push(
+ '# while this PR is open — GitHub drops the merge commit once it closes',
+ `git fetch origin ${computedOn.head} && git checkout ${computedOn.head}`,
+ '# afterwards, rebuild it from the two parents, which stay fetchable',
+ `git fetch origin ${mergedBase} ${mergedHead} && git checkout -B drift-repro ${mergedBase} && git merge --no-ff ${mergedHead}`,
+ '',
+ );
+ } else {
+ lines.push(`git fetch origin ${computedOn.head} && git checkout ${computedOn.head}`);
+ }
+ lines.push(rederive, '```');
+ // A sha that misidentifies the tree is worse than no sha, so the one
+ // condition under which it does is stated right where the sha is.
+ if (computedOn.dirty === true) {
+ lines.push('', '⚠️ That checkout carried **uncommitted changes**, so the commit above does not fully identify what was read.');
+ } else if (computedOn.dirty === null) {
+ lines.push('', '⚠️ This run could not check whether its checkout was clean, so the commit above may not fully identify what was read.');
+ }
+ lines.push('