docs: make the release preparation sequence executable end to end #534

Goal

make the release preparation sequence executable end to end.

Background and evidence

Release-preparation review of a90aa1429647b6eb4820a01aabe37799ca55ad5e on macOS arm64. Bash 5.3.20; ordinary local POSIX filesystem.

docs/release-process.md step 3 tells a maintainer to update VERSION, README, and CHANGELOG, but omits the checked-in lib/bash/base-bash-libs.release version. Following those steps for 2.2.0 in an isolated copy fails the documented validator with:

Repository baseline is present.
Documentation contract passed.
Embedded release metadata version (2.1.0) does not match VERSION (2.2.0).

The guide also asks for artifacts built from <full-tag-sha> at step 4, before the release-prep PR is merged at step 6 and before the tag preflight/publication at steps 7-8. A maintainer needs a clear distinction between candidate rehearsal artifacts and final artifacts bound to the eventual merged release commit; the current order cannot literally be followed with a final tag SHA.

write_release_metadata updates metadata inside a built artifact, but does not fix the source checkout required by tests/validate.sh.

Scope and acceptance criteria

• List every source metadata file required when advancing VERSION, including the embedded release identity version.
• Preserve the intended checkout provenance placeholders rather than committing a self-referential hash.
• Separate pre-merge rehearsal from the final clean merged commit, tag absence check, publish, and remote verification.
• Explain the final full commit SHA used to build/bind artifacts before the tag exists and avoid an instruction that requires precreating a forbidden tag.
• Add a release-prep documentation/fixture check so the prescribed metadata transition passes the baseline.

Validation

Rehearse the documented metadata update in a disposable checkout; run validation through the release metadata checks and exercise existing release guard fixtures. Do not publish.

Source references:

• docs/release-process.md
• tests/validate.sh
• lib/bash/base-bash-libs.release
• scripts/release-artifact
• scripts/release

Non-goals

No release publication or unrelated API redesign. Preserve documented compatibility except for the defective behavior identified above.

Project fields

• Project: base-bash-libs
• Status: Ready
• Priority: P2
• Area: Docs
• Initiative: Adoption Polish
• Size: S
• Milestone: v2.2.0

Agent assignment

Assignee: @codeforester. Implementation may be handled through the normal issue-backed worktree and reviewed PR workflow.