Prepare the GitHub Release draft from finalized release artifacts

[vitormattos]

Parent: #70
Depends on: #73, #74, #84
Blocks: #88, #76

Goal

Create/update the GitHub Release draft from finalized release artifacts after the generated stable release PR is merged and milestone transition is complete.

This issue ends at the second human gate: the maintainer reviews the draft and explicitly clicks Publish release.

Post-publication verification belongs to #88.

Input artifacts

Consume:

• PreparedRelease v1 from Finalize the merged stable release and synchronize aggregate changelog history #73;
• MilestoneTransition v1 from Plan and apply reusable release milestone transitions #74.

Do not rediscover/recalculate release version, changelog, milestone or target commit.

Preconditions

Before creating/updating the draft:

• verify both input artifact schemas/ids;
• confirm the selected stable still points to the expected final release SHA;
• confirm the release preparation PR was merged by an authorized maintainer path;
• verify final release-file digests still match;
• verify target tag/release state is non-conflicting.

Authorization comes from repository permissions/protected workflow policy, never from a label alone.

Privileged mutation uses the configured GitHub App installation token. The PHP tool receives credentials through environment/input and never persists them.

Tag semantics

Create/update one draft using the configured tag prefix and exact final release SHA as target_commitish.

For a new release:

• do not create/push a separate tag before the draft;
• draft tag name is derived from the normalized app version, for example v15.0.4;
• if the tag already exists, require it to point to the same expected commit or fail;
• never retarget an existing published tag.

Draft contents

Body contains:

1. curated public release notes from the finalized changelog/security-safe text;
2. final closed milestone link;
3. full changelog/compare link as the final line.

Prerelease channels set GitHub prerelease state from #80-derived data already carried by PreparedRelease v1.

Do not use GitHub-generated release notes as a substitute for the curated release data.

Human gate

Merging the release PR never publishes the release.

The maintainer reviews the draft and explicitly publishes it.

The existing release: published consumer workflow remains responsible for build/sign/upload/App Store publication.

Output artifact: ReleaseDraft v1

Produce a versioned artifact containing at least:

• PreparedRelease id/hash;
• MilestoneTransition id/hash;
• GitHub Release id/url;
• draft tag name;
• exact target SHA;
• prerelease flag;
• release body digest;
• draft state/readiness.

#88 consumes this artifact after publication.

Recovery before publication

If a correction is required before successful publication:

• keep the same planned version unless explicitly overridden;
• regenerate a new/revised preparation against current branch state;
• produce a new finalized SHA;
• update the draft only after revalidation;
• never silently point an existing published tag to different content.

Acceptance criteria

• draft creation consumes finalized artifacts rather than rediscovering state;
• draft is pinned to exact final SHA;
• tag conflict rules are deterministic;
• milestone and compare links are present;
• prerelease flag is correct;
• security mode exposes only approved public text;
• operation is idempotent;
• publication remains explicit human action;
• ReleaseDraft v1 schema/fixture is committed and consumed by Verify the published release, artifact and App Store handoff #88.

Definition of done

• GitHub Release draft preparation is implemented against finalized artifacts;
• ReleaseDraft v1 schema and fixtures are committed;
• tag/SHA conflict behavior, prerelease mapping, security-safe release text and reruns are tested;
• the operation stops at a draft and never publishes automatically;
• Verify the published release, artifact and App Store handoff #88 can consume the committed draft identity after the human publish gate.

[vitormattos]

Completed in LibreCodeCoop/release-tool#9. release:draft consumes PreparedRelease v1 + MilestoneTransition v1, revalidates branch SHA/final file digests/authorized merger, enforces deterministic tag conflicts, creates or updates only a GitHub Release draft pinned to the exact final SHA, maps prerelease state from the finalized channel, and builds curated notes from finalized public changelog text plus the closed milestone and full changelog link. Published releases are never modified. ReleaseDraft v1 schema/fixture/codec is committed, and full PHP/PHAR/static-analysis/Infection/REUSE/workflow CI is green.