fix(workflows): delete and recreate immutable release as draft

[WilliamBerryiii]

Description

Published releases on this repository are immutable — the gh release edit --draft=true step introduced in PR #545 fails with HTTP 422: state cannot be changed when release is immutable. This PR replaces the edit approach with a delete-and-recreate cycle: capture the release metadata, delete the immutable published release, and recreate it as a mutable draft so downstream jobs can upload assets. The git tag persists across the delete/create cycle, and the publish-release job converts the draft back to published after upload completes.

Why prior approaches failed:

• PR fix(workflows): add manual tag creation for draft releases until release-please-action updates #538 ("draft": true in config) — release-please cannot find draft releases via the Releases API, causing it to scan full history and propose a bogus v3.0.0
• PR fix(workflows): replace draft release config with post-creation draft conversion #545 (gh release edit --draft=true) — published releases are immutable on this repo (HTTP 422)

Related Issue(s)

Fixes #543

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

• Validated YAML syntax of main.yml with yamllint
• Confirmed gh release delete preserves the git tag (documented GitHub CLI behavior)
• Confirmed gh release create --draft --verify-tag recreates a mutable draft tied to the existing tag
• Verified --notes-file approach safely handles release body content with special characters

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

The delete-and-recreate approach is safe because:

1. Tag preservation — gh release delete only removes the release object; the git tag remains intact
2. Timing — release-please has already completed version anchoring before this step runs, so the brief absence of the release object has no effect
3. Metadata fidelity — release title and body are captured before deletion and reapplied to the new draft via --notes-file (avoids shell interpolation issues)
4. Downstream compatibility — all subsequent jobs reference steps.release.outputs.tag_name, which is unaffected by the recreate

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Updates the main release workflow to handle GitHub’s “immutable published releases” behavior by replacing the prior “edit to draft” approach with a delete-and-recreate flow that results in a mutable draft release for asset uploads.

Changes:

• Capture the just-created release’s title/body, delete the immutable published release, and recreate it as a draft tied to the existing tag.
• Keep downstream jobs uploading assets against the same tag_name, then publish the draft at the end of the workflow.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.34%. Comparing base (fe21499) to head (f551177).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #550      +/-   ##
==========================================
- Coverage   85.36%   85.34%   -0.03%     
==========================================
  Files          23       23              
  Lines        4475     4475              
==========================================
- Hits         3820     3819       -1     
- Misses        655      656       +1     

Flag	Coverage Δ
pester	85.34% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[WilliamBerryiii]

Dismissing the automated review comments — none apply here:

1. Null fields: release-please always sets name and body when creating a release. This step gates on release_created == 'true', so both fields are guaranteed populated.

2. Redundant API calls: Two gh release view calls in a release pipeline that runs occasionally is negligible overhead. The suggestion introduces a jq dependency when gh --json -q already handles filtering natively.

3. Retry/rollback logic: If gh release create fails, the step fails visibly in CI — re-run the workflow to recover. The suggested rollback recreates the release as published (immutable), which puts us right back where we started. Adding 40+ lines of retry/rollback for a near-impossible transient failure is over-engineering.