[BUG] Release 0.3.1 CHANGELOG date not set -- TBD persisted through publish and merge

[c-vigo]

Description

The release.yml finalize-release workflow for 0.3.1 (release-kind=final) completed successfully, but the ## [0.3.1] - TBD heading was never replaced with the actual release date. This TBD then propagated to every downstream artifact: the GHCR image, the release PR body, and the smoke-test deployment.

Steps to Reproduce

1. just finalize-release 0.3.1 (workflow run #23609745942)
2. All jobs reported success (validate, finalize, build-and-test, publish, smoke-test)
3. Release PR #342 was merged to main

Expected Behavior

• CHANGELOG.md should contain ## [0.3.1] - 2026-03-26 on the release branch after the finalize job
• The GHCR image ghcr.io/vig-os/devcontainer:0.3.1 should ship the finalized CHANGELOG in /root/assets/workspace/.devcontainer/CHANGELOG.md
• Release PR chore: release 0.3.1 #342 body should show the finalized date
• origin/main should contain the finalized CHANGELOG after merge
• GitHub Release notes should include the ## [0.3.1] - 2026-03-26 header
• Downstream smoke-test PR #112 should receive the finalized CHANGELOG

Actual Behavior

• podman run --rm ghcr.io/vig-os/devcontainer:0.3.1 head -8 /root/assets/workspace/.devcontainer/CHANGELOG.md shows ## [0.3.1] - TBD
• origin/main CHANGELOG.md starts with ## [0.3.1] - TBD
• Release PR chore: release 0.3.1 #342 body shows ## [0.3.1] - TBD in the changelog section (header correctly reads Release 0.3.1 - 2026-03-26)
• GitHub Release body starts at ### Added -- no version header at all
• Downstream smoke-test PR fix(setup): use local npm install for devcontainer CLI #112 body shows ## [0.3.1] - TBD

Environment

• Release workflow run: #23609745942
• Image: ghcr.io/vig-os/devcontainer:0.3.1
• Release PR: #342 (merged)
• Downstream PR: vig-os/devcontainer-smoke-test#112 (merged)
• GitHub Release: 0.3.1 (published, non-draft)

Additional Context

Root cause investigation areas in .github/workflows/release.yml:

1. Finalize commit race: commit-action (line 632) commits via API to refs/heads/release/$VERSION. The subsequent git fetch + git reset --hard (line 709) may have fetched before the API commit was visible, causing build-and-test to use a pre-finalize SHA.
2. Workspace CHANGELOG sync: scripts/sync_manifest.py sync (line 600) must propagate the finalized root CHANGELOG.md to assets/workspace/.devcontainer/CHANGELOG.md. If the manifest doesn't include CHANGELOG or the sync ran before prepare-changelog finalize, the workspace copy would retain TBD.
3. PR body refresh: The sed extraction (line 722) runs after git reset --hard, but if the reset didn't pick up the finalize commit, the CHANGELOG on disk would still have TBD.

The fact that origin/main still has TBD after merge strongly suggests the finalize commit either didn't land or was superseded by a concurrent commit (e.g. from sync-issues.yml).

Possible Solution

• Add a post-commit verification step that fetches the finalized SHA from the API, confirms CHANGELOG.md contains the date, and fails the job if TBD is still present
• Ensure build-and-test checks out the exact SHA from the API commit response rather than relying on git rev-parse HEAD after a git reset
• Add an integration test: grep -q "## [$VERSION] - [0-9]" CHANGELOG.md after the finalize commit lands

Changelog Category

Fixed

• TDD compliance (see .cursor/rules/tdd.mdc)

---

Related: README "Latest Version" stale after release (pre-commit / CI)

CI failure: Project Checks — job 68847671680 on PR #458 (chore: sync main into dev after 0.3.1 release).

What happened: README.md (Image Details → Latest Version, ~lines 184–185) still listed 0.3.0 (2026-03-13) after 0.3.1 shipped. The generate-docs pre-commit hook regenerates README.md from templates and produced 0.3.1 (2026-03-26). uv run pre-commit run --all-files therefore failed with pre-commit hook(s) made changes and that README diff.

Desired outcome (pick one or combine):

1. Automation: Ensure the release / prepare-release path updates generated README.md after CHANGELOG.md is finalized, then run a full uv run pre-commit run --all-files (or equivalent in CI) so committed artifacts match what hooks generate.
2. De-scope: Remove or relocate the Latest Version line if it is not worth keeping in sync by hand or by release automation.

This is the same class of problem as the CHANGELOG finalize drift: release artifacts on main were not fully synchronized before downstream sync PRs ran the normal checks.