rc-docs-sync: defer to open documentation PRs instead of duplicating

[enricobattocchi]

Summary

PR #391 was opened on 2026-04-28 to document the wp yoast auth CLI namespace from Yoast/wordpress-seo#23130. That upstream feature merged today (2026-05-11). When 27.7-RC1 is cut, the sync workflow would see the new WP_CLI::add_command(...) calls, invoke the agent, and the agent would open a competing PR for docs/features/wp-cli/auth.md — duplicating #391's work and creating a merge race.

This PR teaches the workflow + agent to defer to pre-documentation PRs rather than duplicate them.

What changed

1. Workflow — new Fetch recent open documentation PRs in this repo step (runs when any_content == 'true'). Uses gh pr list with is:open is:pr -label:rc-doc-sync updated:>=<30 days ago>, keeps only PRs touching docs/** or sidebars.js, and writes the result to $BUNDLE_DIR/open-doc-prs.json.

2. Agent prompt (run.md) — new Step 1.7 — Defer to open documentation PRs between Step 1.6 and Step 2. The agent reads open-doc-prs.json; for any PR plan whose files overlap a listed PR (excluding sidebars.js-only overlap, which is normal cross-cut), or whose area is mentioned in the listed PR's title/body, the agent:

   • Does NOT open a new PR for that plan.
   • Comments on the existing PR with this RC's source evidence (file:line + symbol names + run URL).
   • Notes the deferral in the run summary under a new Overlapped with open PRs section.

Plus minor: Context available in this run now lists open-doc-prs.json, and Step 4 mentions the new run-summary section.

Validation

• Workflow YAML parses (yaml.safe_load).
• The gh pr list + jq pipeline dry-run against the current repo state returns 3 PRs, one of which is Document MyYoast OAuth client CLI commands #391 with docs/features/wp-cli/auth.md in its files list — exactly what the agent's overlap check needs.
• Other PRs in the result: Enhance index command options in reindexables.md #389 (different wp-cli doc enhancement), docs(installation): rewrite Composer install guide #397 (composer install guide, in docs/development/** which is out of scope for the agent anyway).

What was NOT validated: the agent's Step 1.7 reasoning itself (can't run the agent locally without spending budget). Will get its real-world test on 27.7-RC1.

Risk and mitigation

• False-positive overlap (an unrelated PR happens to touch the same file): the deferred plan posts a comment on the existing PR — the human can ignore it. Worst case: a maintainer realises the overlap was bogus and opens a follow-up PR. Mild annoyance, not a blocker.
• sidebars.js-only overlap: the prompt explicitly tells the agent to not treat this as overlap (sidebars.js is co-edited by almost every doc PR). Eventual merge order resolves the navigation entries.
• Stale open PR slips through: the workflow filters to updated >= 30 days ago, so an abandoned-but-not-closed PR drops out naturally.

Test plan

• Workflow YAML parses.
• Open-PR fetch returns the expected entry (Document MyYoast OAuth client CLI commands #391 with the right files).
• Smoke test via workflow_dispatch against any past RC: verify open-doc-prs.json is written, the rest of the run is unchanged.
• Real test on 27.7-RC1: agent comments on Document MyYoast OAuth client CLI commands #391 instead of opening a new wp-cli docs PR.

🤖 Generated with Claude Code