Handle documentation draft reruns explicitly

[DeagleGross]

Handle documentation draft reruns explicitly

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Skip existing docs drafts by default; support verified no-op refreshes.

Description

Adds a manual existing_draft choice with skip as the default and refresh as the explicit alternative. A read-only preparation job checks source eligibility and validates the existing automated draft's current identity before deciding whether to run the agent. Default reruns link the canonical draft in the job summary and skip inference, publication, and source/docs notifications. Source patches and version inputs are not fetched on this path. Both choices retain normal creation when no draft exists.

Explicit refresh keeps the existing push-plus-title contract for real updates, and adds a distinct docs_pr_action: "unchanged" outcome for sufficient existing documentation. That outcome requires exactly one no-op and one notification, a trusted selected draft, and post-agent evidence that working-tree content, staging, untracked files, and HEAD remain at the trusted original draft head. It also rechecks the live docs PR identity/head before attribution. A title-only updated outcome still fails rather than silently dropping edits. Sufficient refreshes report already sufficient, not updated, and retain the idempotent managed source-author body section without renaming the PR or replacing its generated/human-edited description. Matching non-draft or identity-mismatched automation PRs block replacement instead of authorizing duplicate creation.

Addresses the rerun failure reported in run 37358446353, where sufficient existing documentation led to a title-only update that violated the mandatory-push contract. The baseline validator independently reproduces that rejection. This preserves the manual-only merged-main gate, existing model/turn budget, token topology, command permissions, version resolution, context preparation, and author-attribution behavior. No gh-aw upgrade or unrelated workflow edits.

Validation

• python -m unittest discover -s .github\workflows\pr-docs-check — passed, 71 tests, no skips. Includes real temporary Git repositories executing the workflow's exact post-agent evidence script for clean, unstaged, staged, staged-but-restored, untracked, committed, and deleted-file cases; mocked API fixtures exercise the actual trusted preparation producer.
• node --test .github\workflows\pr-docs-check\test_author_body.cjs — passed, 9 tests, including execution of the actual attribution step for unchanged refreshes, repeat-write idempotence, preservation of human edits, and changed-identity rejection.
• gh aw compile pr-docs-check --strict — passed with repository-pinned gh-aw v0.89.21, no warnings; regenerated the lock file. Structured inspection also passed for dispatch defaults, agent dependencies/condition, skipped-agent publication conditions, and post-analysis evidence placement.
• actionlint.exe -shellcheck= -pyflakes= -ignore 'unknown permission scope "copilot-requests"' -ignore 'property "safe-outputs-head-app-token" is not defined' -ignore 'unexpected key "queue" for "concurrency" section' -ignore 'property "aw" is not defined' .github\workflows\pr-docs-check.lock.yml — passed with native actionlint v1.7.12. These exact four compiler/tooling diagnostics were also reproduced against the unchanged latest-main lock file; no new diagnostics. Optional ShellCheck and Pyflakes integrations were disabled.
• git diff --check and git diff --cached --check — passed.
• Local baseline fixture check loading origin/main:.github/workflows/pr-docs-check/validate_outcome.py — reproduced the required-push error for title-only updated and unsupported-action error for the sufficient unchanged fixture; the new sufficient-refresh contract passes.

Boundary: no production workflow was dispatched, no model inference was run, and dotnet/AspNetCore.Docs#37773 was not modified. Live GitHub publication and model adherence to the revised prompt remain unexercised. No framework build was run because this change is confined to the documentation workflow and its helpers/tests.

Fixes: N/A (no issue was supplied; the failing workflow run is linked above).

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[dotnet-policy-service]

Hey @dotnet/aspnet-build, looks like this PR is something you want to take a look at.