Implement atomic version reservation in publish workflow

- Added a new `reserve-version` job to the GitHub Actions workflow, ensuring atomic reservation of the next publish version via the GitHub Git Refs API.
- Rewired downstream jobs to consume outputs from `reserve-version`, replacing previous dependencies on the `validate` job.
- Removed legacy `git-tag-staging` and `Calculate unified version` steps to streamline the workflow.
- Updated documentation to reflect the new version reservation process and clarify the role of GHCR as image storage only.
- Conducted verification on a real `alpha` run, confirming successful execution and proper tagging behavior.

Author: mitchdowney

…c-publish-version-reservation-part-01.md …c-publish-version-reservation-part-01.md.llm/history/active/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md renamed to .llm/history/completed/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md .llm/history/active/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md renamed to .llm/history/completed/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md

@@ -12,12 +12,12 @@ apply this plan revision to the .llm plan files, then execute Prompt 1.
 
 #### Files Modified
 
-- .llm/plans/active/atomic-publish-version-reservation/00-SUMMARY.md
-- .llm/plans/active/atomic-publish-version-reservation/01-reserve-version-job.md
-- .llm/plans/active/atomic-publish-version-reservation/04-docs-publish-update.md
-- .llm/plans/active/atomic-publish-version-reservation/05-verification.md
+- .llm/plans/completed/atomic-publish-version-reservation/00-SUMMARY.md
+- .llm/plans/completed/atomic-publish-version-reservation/01-reserve-version-job.md
+- .llm/plans/completed/atomic-publish-version-reservation/04-docs-publish-update.md
+- .llm/plans/completed/atomic-publish-version-reservation/05-verification.md
 - .github/workflows/publish-alpha.yml
-- .llm/history/active/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md
+- .llm/history/completed/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md
 
 ### Session 2 - 2026-04-23
 
@@ -38,12 +38,12 @@ implement these plans. as you finish each step in the copy pasta you should mark
 - docs/PUBLISH.md
 - .cursor/rules/plan-execution-completion-tracking.mdc
 - .github/instructions/plan-execution-completion-tracking.instructions.md
-- .llm/plans/active/atomic-publish-version-reservation/COPY-PASTA.md
+- .llm/plans/completed/atomic-publish-version-reservation/COPY-PASTA.md
 - .llm/plans/completed/atomic-publish-version-reservation/01-reserve-version-job.md
 - .llm/plans/completed/atomic-publish-version-reservation/02-rewire-needs-and-outputs.md
 - .llm/plans/completed/atomic-publish-version-reservation/03-remove-git-tag-staging-and-validate-version.md
 - .llm/plans/completed/atomic-publish-version-reservation/04-docs-publish-update.md
-- .llm/history/active/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md
+- .llm/history/completed/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md
 
 ### Session 3 - 2026-04-23
 
@@ -65,4 +65,4 @@ https://github.com/podverse/metaboost/actions/runs/24857171910 thanks to this ru
 - .llm/plans/completed/atomic-publish-version-reservation/00-SUMMARY.md (moved)
 - .llm/plans/completed/atomic-publish-version-reservation/05-verification.md (moved then updated)
 - .llm/plans/completed/atomic-publish-version-reservation/COPY-PASTA.md (moved then updated)
-- .llm/history/active/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md
+- .llm/history/completed/atomic-publish-version-reservation/atomic-publish-version-reservation-part-01.md

.llm/plans/completed/atomic-publish-version-reservation/00-EXECUTION-ORDER.md

@@ -0,0 +1,44 @@
+# Execution Order — Atomic Publish Version Reservation (metaboost)
+
+This plan reworks `.github/workflows/publish-alpha.yml` so that the publish version
+`X.Y.Z-{suffix}.N` is selected and reserved **atomically** via the GitHub Git Refs API
+**before** any Docker image is pushed. GHCR is no longer the source of truth for the
+next `N`; Git tags are.
+
+All phases are **sequential**. Do not start phase N+1 until phase N is fully complete
+and verified.
+
+## Phase 1 — Add `reserve-version` and rewire downstream jobs
+
+Single PR / branch. After this phase the workflow has both the new `reserve-version`
+job and the old `validate` version-calculation step + `git-tag-staging` job (the old
+ones are removed in Phase 2 to keep the diff reviewable).
+
+1. `01-reserve-version-job.md` — Add the new `reserve-version` job between `validate`
+   and `publish-docker`.
+2. `02-rewire-needs-and-outputs.md` — Update every downstream job to depend on
+   `reserve-version` and consume `needs.reserve-version.outputs.*`.
+
+## Phase 2 — Remove the legacy version-calculation and tag job
+
+3. `03-remove-git-tag-staging-and-validate-version.md` — Delete the `git-tag-staging`
+   job and the `Calculate unified version` step from `validate`. Update remaining
+   `needs:` lists.
+
+## Phase 3 — Documentation
+
+4. `04-docs-publish-update.md` — Update [docs/PUBLISH.md](../../../../docs/PUBLISH.md)
+   to describe atomic reservation via Git ref API; clarify GHCR is image storage only.
+
+## Phase 4 — Verify on a real run
+
+5. `05-verification.md` — Push to `alpha`, walk through the verification checklist,
+   and only then move on to the podverse plan set.
+
+```mermaid
+flowchart TD
+  p1["Phase 1: reserve-version + rewire"] --> p2["Phase 2: remove legacy version + tag job"]
+  p2 --> p3["Phase 3: docs"]
+  p3 --> p4["Phase 4: verify on alpha"]
+  p4 --> pv["Then start podverse plan set"]
+```

.llm/plans/completed/atomic-publish-version-reservation/00-SUMMARY.md

@@ -0,0 +1,72 @@
+# Summary — Atomic Publish Version Reservation (metaboost)
+
+## Why this keeps failing
+
+Run [24852065873](https://github.com/podverse/metaboost/actions/runs/24852065873)
+failed with `Refusing to move tag 0.1.9-staging.0` even after the previous "GHCR +
+Git tags" combined-discovery change. That means the `Calculate unified version` step
+in `validate` still picked `.0`, almost certainly because:
+
+- `git ls-remote --tags origin "refs/tags/${BASE_VERSION}-${SUFFIX}.*"` returned
+  nothing (errors are swallowed by trailing `|| true`), or
+- the GHCR tag list was empty / `404` and we treated it as bootstrap.
+
+Even when the increment **is** correct, the current ordering is unsafe:
+
+- `publish-docker` pushes images first; `git-tag-staging` runs after and can fail.
+  GHCR tags are mutable, so a duplicate `N` already overwrote images by the time the
+  Git tag check rejects.
+- Two concurrent runs can both compute the same `N` (race).
+
+## Goal
+
+A single, atomic source of truth for `N`: **the Git tag
+`refs/tags/X.Y.Z-{suffix}.N`**, reserved before publish via
+the GitHub Git Refs API (`POST /repos/{owner}/{repo}/git/refs`).
+
+```mermaid
+flowchart TD
+  validateNode["validate (build, lint, type-check, audit)"] --> reserveNode["reserve-version (compute N + create tag at workflow SHA)"]
+  reserveNode --> publishNode["publish-docker (uses reserved version)"]
+  publishNode --> verifyNode["verify-published-tags"]
+  verifyNode --> releaseNode["github-prerelease-create + changelog-pr-to-develop"]
+```
+
+## Decisions
+
+- **Git ref API is source of truth.** The GitHub `POST /repos/{owner}/{repo}/git/refs`
+  endpoint is atomic: HTTP 201 = we won the race; HTTP 422 = "Reference already
+  exists". For computed prerelease tags we bump `N` and retry; for exact-tag
+  reservations (`version_override` and `main`) we resolve the existing tag and only
+  accept 422 if it already points at `github.sha`.
+- **GHCR is image storage only.** No more GHCR tag discovery for selecting `N`.
+  Verification of pushed tags continues to use GHCR after the fact.
+- **No silent failure in the authoritative reservation path.** All shell uses
+  `set -euo pipefail`. Git Refs API failures other than 201/422 fail immediately;
+  non-authoritative discovery fallbacks are explicit and logged.
+- **Smart start hint, not source of truth.** `git ls-remote --tags` is only used to
+  pick a starting `N` so we don't loop linearly from 0. If it fails or returns
+  nothing, we still walk from 0; the create-ref race detection guarantees
+  correctness.
+- **Two-phase rollout in this workflow.** Phase 1 adds `reserve-version` and rewires
+  consumers (the old version step still runs but is unused). Phase 2 deletes the
+  legacy version step and the `git-tag-staging` job. This keeps the diff reviewable
+  and lets us bail back to the old behaviour if Phase 1 misbehaves.
+
+## Plan files
+
+- `00-EXECUTION-ORDER.md`
+- `00-SUMMARY.md` (this file)
+- `01-reserve-version-job.md`
+- `02-rewire-needs-and-outputs.md`
+- `03-remove-git-tag-staging-and-validate-version.md`
+- `04-docs-publish-update.md`
+- `05-verification.md`
+- `COPY-PASTA.md`
+
+## Out of scope
+
+- Podverse alignment lives in
+  `podverse/.llm/plans/active/ci-atomic-version-reservation/`. Do not touch podverse
+  until metaboost Phase 4 verification is green.
+- `main` (RTM) tag handling stays as today (no suffix, single `X.Y.Z`).