Improve push-reference-docs skill: handle diverged docs branches on retarget

[marko-lisica]

Related issue: NA

What & why

The push-reference-docs skill's OPEN-PR path told the operator to retarget the PR's base from the source docs branch to the target docs branch as an unconditional one-liner. That is only safe when the source branch is an ancestor of the target.

Release docs branches (e.g. docs-v4.89.0 and docs-v4.90.0) routinely diverge onto separate lines from an older common ancestor. Since a GitHub PR diff is merge-base(HEAD, base)...HEAD, retargeting to a diverged branch moves the merge-base back to that old ancestor and silently pulls every source-only commit into the PR diff — files the author never touched. This happened in practice and required a manual rebase to clean up.

Changes

Rewrote the OPEN-PR path into a 7-step procedure:

• Fetch the PR head branch + both docs branches.
• Divergence check via git merge-base --is-ancestor <source> <target>:
  • CONTAINED → plain retarget is safe (previous behavior).
  • DIVERGED → rebase the branch onto the target first.
• Rebase-onto: compute the fork point and git rebase --onto <target> <fork-point> to replay only the PR's own commits.
• Verify the diff stat matches the original before force-pushing (--force-with-lease), with a fallback to hand the push to the user if a permission rule blocks it.
• Retarget via REST API (unchanged), then report whether a rebase was needed.
• Added a one-line explanation of the merge-base(HEAD, base)...HEAD mechanism so the next operator understands the why.

Docs-tooling change only — no product code, no user-facing behavior, no tests/migrations.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}