Add tag-targeted manual recovery path for publish workflow

[iwizsophy]

Summary

Add a manual recovery path to the publish workflow so a failed tag publish can be rerun by specifying an existing release tag in workflow_dispatch, without deleting and recreating the tag and without introducing a dedicated rerun tag.

Background

• The Publish workflow run 23298561746 for tag v1.1.0 failed on 2026-03-19.
• The failure occurred in Authenticate to NuGet.
• The failing response was a 503 from NuGet token exchange and returned a Read-only Mode page.
• The workflow succeeded when rerun on 2026-03-20.

This indicates the immediate cause was an external transient failure, not a build, test, pack, or package-content problem.

Problem

The current recovery options are weaker than they should be:

• The normal tag-push path is correct, but recovery depends on rerunning the failed GitHub Actions run.
• workflow_dispatch currently supports branch-based execution only.
• If rerun is unavailable, the remaining workaround is deleting and recreating the release tag.
• Recreating a release tag is operationally risky and should not be the preferred recovery path.

Proposal

Extend the publish workflow so workflow_dispatch can target an existing release tag or release ref.

Expected behavior:

• Keep the existing tag-push publish flow unchanged.
• Add a manual dispatch input such as release_tag or release_ref.
• When an existing release tag/ref is provided:
  • checkout that exact existing ref
  • derive the expected package version from that tag
  • validate the tag format and annotated-tag requirement
  • resolve whether the tagged commit belongs to main or develop
  • publish using the same routing rules as the tag-push path
• Do not introduce a dedicated rerun tag naming scheme.
• Do not require deleting and recreating the original release tag for recovery.
• Document the preferred recovery order:
  1. rerun the failed workflow run
  2. use manual dispatch with the existing release tag
  3. delete/recreate the tag only as a last resort

Impact Scope

Likely impacted components:

• .github/workflows/publish.yml
• scripts/Validate-PublishWorkflow.ps1
• release workflow documentation
• DECISIONS.md if maintainer review concludes this recovery behavior should be recorded as an accepted decision

Non-Goals

• Introducing rerun-only tags
• Changing normal tag-push release behavior
• Relaxing branch-routing validation
• Relaxing annotated-tag validation
• Changing NuGet trusted publishing configuration itself

Validation / Tests

• Update workflow invariant validation for the new manual dispatch path.
• Verify tag-push behavior remains unchanged.
• Verify manual dispatch with an existing release tag resolves the expected package version.
• Verify manual dispatch still rejects invalid tags and invalid branch routing.
• Verify rerun/recovery documentation matches the implemented workflow behavior.

Acceptance Criteria

• A maintainer can manually rerun a failed release publish by specifying an existing release tag.
• The workflow publishes the same package version that the tag represents.
• The workflow still enforces annotated tags and branch-based feed routing.
• Tag-push publishing behavior remains unchanged.
• Documentation is updated to describe the supported recovery path and when tag recreation is allowed.

Notes

This issue is about recovery from transient external publish failures, such as NuGet token exchange 503 responses.