Finalize the merged stable release and synchronize aggregate changelog history

[vitormattos]

Parent: #70
Depends on: #72, #79, #83
Related: #81, #86
Blocks: #74, #75, #76

Goal

Keep the selected stable branch authoritative for the release being prepared while maintaining an aggregate per-major release history on main without introducing a second mandatory human release gate.

This is release metadata synchronization, not generic code backport automation.

LibreSign branch model

• the selected stable branch is the authoritative source for that stable release;
• its release PR contains the final per-major changelog section plus app/package version files;
• main keeps an aggregate archive of docs/changelogs/changelog-<major>.md files for all supported majors;
• main does not receive an older stable's app/package version;
• main synchronization is derived from the already-reviewed stable changelog text.

Release sequence

For a selected stable release:

1. generate one reviewable release PR against the selected stable;
2. maintainer reviews and merges that PR;
3. revalidate the merged stable state and final release SHA;
4. continue milestone/draft preparation;
5. synchronize the released per-major changelog section back to main through an automated/generated changelog-only PR or equivalent protected-branch-safe mechanism.

Main synchronization must not require the maintainer to repeat the same release-content review before the GitHub Release draft can be created.

If branch protection requires a second approval, treat that as repository governance, not as a semantic release gate; it must not cause the release engine to regenerate or reinterpret the changelog.

For a release where main itself is the configured release branch, no sync-back step is needed.

Output artifact: PreparedRelease v1

After the generated stable release PR is merged and revalidated, produce PreparedRelease v1.

It consumes ReleasePreparation v1 and records at least:

• ReleasePlan id/hash;
• ReleasePreparation id/hash;
• selected release branch;
• merged release PR number/URL;
• final merged release SHA;
• final normalized app version/tag name/channel/mode;
• final changelog section/digest as actually merged;
• final release-file digests;
• aggregate-history synchronization state/provenance.

This is the first artifact allowed to contain the final release SHA.

#74 and #75 consume PreparedRelease v1; they must not rediscover or guess the release commit independently.

Consistency

• release text is generated once for the stable release;
• main receives the exact released section/content;
• retrying never duplicates a version section;
• source stable SHA and synchronization provenance are recorded;
• main's archive can lag briefly but must converge deterministically.

Conflict avoidance

Each app major has an independent changelog file.

Do not reintroduce cumulative changelog slicing across majors.

Safety

• verify selected stable HEAD before preparing mutation;
• verify final merged stable SHA before draft creation;
• never direct-push to protected branches;
• only configured release files may change;
• never mix feature/bugfix code backports into changelog synchronization;
• security releases follow Define security-release-safe domain and serialization contracts #84 and must not sync embargoed details prematurely.

Acceptance criteria

• a normal stable release has one semantic release PR review gate;
• stable app/version files are updated only on stable target;
• main receives exact released changelog content without version regression;
• different majors do not conflict on one changelog file;
• sync-back is idempotent and protected-branch safe;
• release draft preparation does not depend on a second manual changelog review.

Definition of done

• merged release PRs can be revalidated deterministically;
• PreparedRelease v1 schema and fixtures are committed;
• final release SHA and final file/changelog digests come from the merged state;
• aggregate-history synchronization is implemented, idempotent and protected-branch safe;
• security-mode synchronization rules are enforced;
• Plan and apply reusable release milestone transitions #74/Prepare the GitHub Release draft from finalized release artifacts #75 can consume PreparedRelease v1 without recomputing finalized release state.

[vitormattos]

Completed in LibreCodeCoop/release-tool#7. release:finalize consumes an applied ReleasePreparation v1, revalidates the actually merged PR and target branch, records final SHA/version/tag/file/changelog digests in PreparedRelease v1, accepts human edits only within the configured release-file scope, rejects unexpected files/drift, and creates exact changelog-only protected-branch-safe history synchronization. Reruns converge or fail closed on conflicting/manual branch edits. Security mode defers public history sync. Schema/fixtures and business/API tests are committed; full QA/PHAR/REUSE/security CI is green.