ci(ai-validation): pin validate to prepare merge_sha + fix 2 stray escapes

CR/Copilot pass on the merge-ref + retarget-origin revision raised:

1. (CR on #1991, line 278, Major) Re-resolving refs/pull/<n>/merge
   in validate is racy. GitHub may advance the merge ref between
   prepare and validate (rapid pushes), so Pass 1 (artifact from
   prepare) and Pass 2 (validate workspace) can see different
   revisions. concurrency.cancel-in-progress narrows the window but
   does not make the ref immutable.

   Fix: prepare outputs its post-checkout `git rev-parse HEAD` as
   `merge_sha`, validate checks out THAT exact sha. Both jobs now
   operate on the same revision regardless of subsequent pushes.

2. (Copilot on #1991, two findings on line 294) The merge-ref +
   retarget commit introduced two NEW stray heredoc escapes:
   `PR"'sclaude-code-action'"s`. Same class of error
   as the previous-fix-cycle: shell heredoc escape sequences
   survived verbatim into YAML.

   Fix: replace with plain `PRs` / `claude-code-actions` in the
   inline comment block and step name.

3. (Copilot on #1990/#1991, "PR title/description says HEAD repo +
   head.sha") Metadata cleanup tracked separately — PR titles +
   bodies updated to describe the merge-ref + retarget-origin
   approach (no workflow file change for that part).

Mirrored byte-identically across the 3 open wave-5 PRs (#1990
rolling, #1991 circinus, #1993 sagitta follow-up). Canonical sync
once these merge.

1 files changed, 20 insertions, 4 deletions

diff --git a/.github/workflows/ai-validation.yml b/.github/workflows/ai-validation.yml
index f69844fb..993d1876 100644
--- a/.github/workflows/ai-validation.yml
+++ b/.github/workflows/ai-validation.yml
@@ -57,6 +57,14 @@ jobs:
       # validate's working-directory: _changed_md would otherwise fail
       # before any in-step short-circuit can run.
       has_md_changes: ${{ steps.changes.outputs.has_md_changes }}
+      # The exact SHA of the merge commit that prepare bundled. validate
+      # below checks out THIS sha (rather than re-resolving
+      # `refs/pull/<n>/merge`, which GitHub may update between prepare
+      # and validate on rapid pushes — concurrency.cancel-in-progress
+      # narrows the window but does not make the ref immutable). Pass 1
+      # (artifact) and Pass 2 (validate workspace) now operate on the
+      # same revision.
+      merge_sha: ${{ steps.changes.outputs.merge_sha }}
     steps:
       - name: Checkout PR merge ref (NO credentials)
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -174,6 +182,11 @@ jobs:
             echo "has_md_changes=false" >> "$GITHUB_OUTPUT"
           fi
 
+          # Pin the merge SHA that prepare bundled, so validate below can
+          # check out the exact same revision and avoid drift if GitHub
+          # advances refs/pull/<n>/merge between jobs.
+          echo "merge_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
       - name: Upload PR input artifact
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
@@ -273,25 +286,28 @@ jobs:
         if: steps.secrets-check.outputs.skip != 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          ref: refs/pull/${{ github.event.number }}/merge
+          # Pin to the exact merge SHA prepare bundled so validate's
+          # workspace tree matches Pass 1's artifact even on a PR that
+          # has had additional pushes between prepare and validate.
+          ref: ${{ needs.prepare.outputs.merge_sha }}
           persist-credentials: false
           fetch-depth: 2
 
       # claude-code-action subsequently runs `git fetch origin <head-ref>`
       # internally during its setup. `<head-ref>` is the branch name in
-      # the PR'"'"'s HEAD repo — for fork PRs that branch does NOT exist on
+      # the PR's HEAD repo — for fork PRs that branch does NOT exist on
       # the base repo (which is what `origin` points at after the merge-
       # ref checkout above), so the fetch fails with
       #   fatal: couldn't find remote ref refs/heads/<head-ref>
       #
-      # Re-point origin to the HEAD repo'"'"'s URL so the action'"'"'s fetch
+      # Re-point origin to the HEAD repo's URL so the action's fetch
       # resolves. The workspace tree is unchanged — it remains the merge
       # tree from above. For public forks (the only kind that target
       # vyos/vyos-documentation, since the repo is public) the
       # unauthenticated fetch from the fork succeeds without any credential
       # (persist-credentials:false stripped the extraheader at the end of
       # the previous step).
-      - name: Re-point origin to fork URL for claude-code-action'"'"'s git fetch
+      - name: Re-point origin to fork URL for claude-code-action's git fetch
         if: steps.secrets-check.outputs.skip != 'true'
         env:
           FORK: ${{ github.event.pull_request.head.repo.full_name }}