ci(workflows): retire auto-update-pr-branches

.claude/skills/open-pr/SKILL.md

@@ -318,6 +318,15 @@ a 20-minute poll on the global list never saw the builds). Match the
 
 ## Gotchas
 
+- **Never update a PR branch with `GITHUB_TOKEN`** (`update-branch`
+  from a workflow, or any push as `github-actions[bot]`) when its CI
+  has to run: GitHub holds every run on that head at
+  `action_required`, and the PR sits BLOCKED with no checks until
+  someone approves them (`gh api -X POST
+  repos/{owner}/{repo}/actions/runs/<id>/approve`). The `main` ruleset
+  is not strict, so a branch behind `main` merges anyway; this is why
+  `auto-update-pr-branches.yml` was retired after it put eight such
+  commits on #12229 (2026-10-22).
 - **`isOutdated` ≠ `isResolved`.** A fix-push can outdate a Copilot
   thread while it stays unresolved; outdated threads still count
   against review-clean — resolve them explicitly.

agentic/commands/dependabot.md

@@ -26,14 +26,14 @@ known GitHub quirks. Every gotcha below cost real session round-trips.
      resulting merge commit is authored by `github-actions[bot]`, GitHub then gates that head's
      workflow runs behind manual approval (`action_required`, so the checks never report), and
      Dependabot permanently stops rebasing a branch once a foreign commit lands on it. PR #9674
-     burned 174 runs in 22 h this way. `auto-update-pr-branches.yml` skips Dependabot branches
-     for the same reason (#9772).
+     burned 174 runs in 22 h this way, and #12229 collected eight such commits on 2026-10-22
+     from `auto-update-pr-branches.yml`, which was retired for it.
    - **Already poisoned** (head commit authored by `github-actions[bot]`, checks stuck at
      `action_required`): approve the gated runs once —
      `gh api -X POST repos/{owner}/{repo}/actions/runs/<id>/approve`. Approved runs do report
-     the required contexts on a bot-authored head (verified on #9674), and since
-     `auto-update-pr-branches.yml` no longer touches these branches the head now stays put, so
-     one approval is enough. `@dependabot recreate` also works and additionally restores a
+     the required contexts on a bot-authored head (verified on #9674), and since no workflow
+     updates PR branches any more (only `impl-merge.yml` updates its own `implementation/` PRs)
+     the head stays put, so one approval is enough. `@dependabot recreate` also works and additionally restores a
      clean `dependabot[bot]` head, but it re-resolves the versions.
    - `mergeStateStatus` is computed async — after any update, poll it a few seconds until it
      stabilizes before deciding (UNKNOWN → BEHIND/CLEAN/BLOCKED).

agentic/docs/project-guide.md

@@ -764,7 +764,6 @@ Issue ready for maintainer review
 | **notify-deployment.yml** | Deployment notifications |
 | **util-claude.yml** | Claude utility workflow |
 | **daily-regen.yml** | Scheduled: picks the oldest specs, runs spec polish + cross-library similarity audit, then dispatches bulk-generate |
-| **auto-update-pr-branches.yml** | When `main` advances, updates open PRs that have auto-merge enabled, except Dependabot and spec (`specification/`) PRs — its `GITHUB_TOKEN` merge commit would hold their CI at `action_required` |
 | **watchdog-stuck-jobs.yml** | Periodic safety net: detects and unsticks stalled impl-pipeline PRs |
 | **bot-serving-check.yml** | Daily synthetic monitor for the nginx bot -> seo-proxy path; routes and titles derived from `api/routers/seo.py` and the spec files, and a failure opens/comments the fixed-title issue "Bot serving check is red" (closed again by the next green run) |
 

changelog.d/retire-auto-update-pr-branches.md

@@ -0,0 +1,9 @@
+### Removed
+
+- **The auto-update workflow for PR branches.** `auto-update-pr-branches.yml`
+  merged `main` into every open PR with auto-merge after each push to `main`.
+  The `main` ruleset's checks are not strict, so no PR needed it, and its
+  merge commits, authored by `github-actions[bot]`, held each PR's CI at
+  `action_required` until someone approved the runs by hand (eight times on
+  one PR on 2026-10-22). Auto-merge now fires on the PR's own green head.
+  (#12237)

prompts/workflow-prompts/spec-polish-claude.md

@@ -95,11 +95,10 @@ Then open the PR. Use a HEREDOC for the body so multi-line markdown survives:
     )")
 
     # Enable auto-merge so the PR squash-merges automatically once required
-    # checks (Run Linting / Tests / Frontend Tests) go green and the head
-    # is in sync with main. Auto-merge handles the strict status-check
-    # policy by updating the branch on our behalf. If auto-merge cannot be
-    # enabled (e.g. checks already complete and branch is up-to-date), this
-    # is non-fatal — the PR still exists for human follow-up.
+    # checks (Run Linting / Tests / Frontend Tests) go green. The main
+    # ruleset's status checks are not strict, so a branch behind main
+    # merges too. If auto-merge cannot be enabled (e.g. checks already
+    # complete), this is non-fatal — the PR still exists for human follow-up.
     gh pr merge "$PR_URL" --auto --squash --delete-branch || \
       echo "::warning::Could not enable auto-merge for $PR_URL — leaving PR open for manual handling"