Fix auto-skip detection in build-staged.yml

.github/workflows/build-staged.yml

@@ -72,9 +72,19 @@ jobs:
           fi
           echo "Commit message: $COMMIT_MESSAGE"
 
-          # Detect changed files for auto-skip detection
+          # Detect changed files for auto-skip detection.
+          # For pull_request events, GitHub Actions checks out a synthetic merge
+          # commit where HEAD^1 is the base (main) and HEAD^2 is the PR head.
+          # Diffing HEAD^1 against HEAD (the merge result) gives exactly what this
+          # PR would introduce on top of the current base; this avoids two failure
+          # modes of the previous logic:
+          #   - HEAD^2..HEAD returned base-side changes since the PR branched,
+          #     so non-doc PRs were misclassified as docs-only.
+          #   - HEAD^1..HEAD^2 would, if main has advanced since the PR branched,
+          #     surface those base-only changes as PR-side deletions and
+          #     misclassify a docs-only PR as needing a build.
           if [[ "$EVENT_NAME" == "pull_request" ]]; then
-            CHANGED_FILES=$(git diff --name-only HEAD^2 HEAD 2>/dev/null || git diff --name-only HEAD^ HEAD 2>/dev/null || echo "")
+            CHANGED_FILES=$(git diff --name-only HEAD^1 HEAD 2>/dev/null || git diff --name-only HEAD^ HEAD 2>/dev/null || echo "")
           else
             CHANGED_FILES=$(git diff --name-only HEAD^ HEAD 2>/dev/null || echo "")
           fi