Cap skill turns/timeout + sync local HEAD after skill pushes (#783)

* Add turn/timeout caps and sync local HEAD after skill pushes

Three defensive additions to the upstream-release-docs pipeline.

## Sync local HEAD with skill-pushed commits

claude-code-action works in a sibling scratch checkout (the
`.claude-pr/` dir we gitignore) and pushes its commits to origin
without advancing the outer workflow checkout's HEAD. Every
subsequent step that reads local git state saw stale HEAD at the
pre-skill SHA.

Symptoms on PR #780:
- `skill_commits` counter reported 0 despite commit `d4b3c7c`
  existing on the PR branch -- triggered the silent-run NOTE on
  a run that wasn't actually silent.
- `autofix` early-exited with "No skill-touched files in scope"
  because its `git diff BASELINE_SHA..HEAD` returned nothing.
  41 unformatted files from the skill landed on CI and failed
  the Lint and format checks job.

Fix: new step between `skill_review` and `skill_commits` that
runs `git fetch origin $HEAD_REF && git merge --ff-only`. Local
HEAD now reflects whatever the skill pushed, so downstream steps
see the truth.

## --max-turns caps

Per-session turn ceilings via claude_args:
- skill_gen: 500 (baselines: 89 silent → 397 full rebuild)
- skill_review: 30 (baseline: 4-5 turns every run)

Clips genuine runaway loops without interfering with legitimate
complex runs. Hitting a cap fails loudly; we raise deliberately
if a release genuinely needs more.

## timeout-minutes per step

Wall-clock ceilings:
- skill_gen: 45 min (observed: 15-22 min)
- skill_review: 10 min (observed: 1-2 min)

Kills a stuck process before it burns the full 90-min job budget.

## What this does NOT cover

- Legitimate-but-expensive runs (PR #780 at $27 is real work).
- Upstream Anthropic pricing changes.
- High-frequency workflow triggering.

For those: set a monthly spend cap at the Anthropic console.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Fail loudly on sync-step errors (Copilot review)

Drops the `|| true` after `git merge --ff-only`. Silently
continuing on a failed sync reintroduces the exact
skill_commits=0 + autofix-skips-files bugs this step prevents.

A no-op fast-forward (local already at origin) still exits 0
cleanly, so the common case is unaffected. Only genuine
divergence or merge errors now fail the step.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rdimitrov

.github/workflows/upstream-release-docs.yml

@@ -514,6 +514,11 @@ jobs:
       # verification.
       - name: Run upstream-release-docs skill (generation)
         id: skill_gen
+        # Wall-clock ceiling. Observed gen runs take 15–22 min depending
+        # on release scope; 45 min kills a stuck process before it
+        # burns the full 90-minute job budget. Paired with --max-turns
+        # below for a runaway-cost ceiling.
+        timeout-minutes: 45
         uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
@@ -542,8 +547,15 @@ jobs:
           # only, which misses most of the "why" narrative that PR
           # authors write at open time. GH_TOKEN for auth is already
           # in the job env at the top of this workflow.
+          #
+          # --max-turns 500: observed gen baselines are 89 turns
+          # (silent) to 397 (full content rebuild). 500 gives headroom
+          # over the worst legitimate run, while clipping a genuine
+          # runaway before it spirals. Hitting the cap produces a
+          # loud failure -- raise deliberately if a release needs more.
           claude_args: |
             --model claude-opus-4-7
+            --max-turns 500
             --allowed-tools "Bash(gh:*)"
           prompt: |
             You are running in GitHub Actions with no interactive user. Follow
@@ -678,6 +690,11 @@ jobs:
       - name: Run docs-review on skill output (fresh context)
         id: skill_review
         if: always() && steps.skill_gen.conclusion == 'success'
+        # Editorial review is a short pass: 1-2 min wall clock, 4-5
+        # turns in every run so far. 10 / 30 are 5-6x buffers over
+        # baseline -- cheap safety net for the rare case where review
+        # spirals on a file it can't stop "improving".
+        timeout-minutes: 10
         uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
@@ -688,9 +705,12 @@ jobs:
           display_report: true
           # gh access parallels skill_gen so the review pass can
           # re-verify claims against PR descriptions and linked
-          # issues if needed.
+          # issues if needed. --max-turns 30 is 6x the 4-5-turn
+          # baseline; if review ever needs more, the cap fails
+          # loudly and we raise it.
           claude_args: |
             --model claude-opus-4-7
+            --max-turns 30
             --allowed-tools "Bash(gh:*)"
           prompt: |
             You are running in GitHub Actions with no interactive user. Follow
@@ -723,6 +743,33 @@ jobs:
             if they exist -- they're signal files handed off to the
             next workflow step, not part of the docs.
 
+      # claude-code-action works in a sibling scratch checkout (the
+      # .claude-pr/ dir we gitignore) and pushes commits to origin
+      # directly, without advancing the outer workflow checkout's
+      # HEAD. Without an explicit sync, every subsequent step that
+      # reads local git state (skill_commits counter, autofix's git
+      # diff) sees stale HEAD at the pre-skill SHA -- which is what
+      # caused PR #780's "skill_commits=0 despite a real skill
+      # commit" + unformatted files landing on CI unformatted.
+      #
+      # Fetch + fast-forward-merge origin so local HEAD reflects
+      # whatever the skill pushed. Fail loudly on fetch or merge
+      # errors -- silently continuing on stale HEAD reintroduces
+      # the exact skill_commits=0 + autofix-skips-files bugs this
+      # step is meant to prevent. Gated on skill_gen success; if
+      # gen didn't run, there's nothing for the skill to have
+      # pushed and this step is skipped.
+      # A no-op fast-forward (local already at origin, e.g. skill
+      # made no commits) exits 0 cleanly.
+      - name: Sync local branch with skill-pushed commits
+        if: always() && steps.skill_gen.conclusion == 'success'
+        env:
+          HEAD_REF: ${{ steps.eff.outputs.head_ref }}
+        run: |
+          git fetch origin "$HEAD_REF" --quiet
+          git merge --ff-only "origin/$HEAD_REF"
+          echo "Local HEAD after sync: $(git rev-parse HEAD)"
+
       # Mirror of skill_gen_stats for skill_review. Reads the same
       # canonical log path, which skill_review overwrote on exit.
       - name: Capture skill_review stats