fix: defer tag push until after build; update docs for merged release workflow

release.yml: split "Tag release" into two steps — create the tag locally
first (so hatch-vcs can derive the version during uv build), then push to
origin only after a successful build. The push step also fails fast with a
clear error if the tag already exists on origin (e.g. workflow re-run for
the same version). Adds a prominent comment on publish-testpypi noting
that PyPI/TestPyPI Trusted Publisher configs must reference release.yml
(not the former publish.yml).

spec/plan docs: update all references to the old two-workflow model
(tag-only release.yml + tag-triggered publish.yml, GitHub App token)
to reflect the merged release.yml that runs tests, builds, publishes to
TestPyPI→PyPI, and creates the GitHub Release using GITHUB_TOKEN only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

.github/workflows/release.yml

@@ -61,24 +61,42 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Tag release
-        run: |
-          git tag "v${{ steps.normalize.outputs.version }}"
-          git push origin "v${{ steps.normalize.outputs.version }}"
+      # Create the tag locally so hatch-vcs can derive the package version during
+      # `uv build`. The tag is pushed to origin only AFTER a successful build to
+      # avoid leaving a dangling remote tag if the build fails.
+      - name: Create local release tag
+        run: git tag "v${{ steps.normalize.outputs.version }}"
 
       - name: Install uv
         uses: astral-sh/setup-uv@e58605a9b6da7c637471fab8847a5e5a6b8df081  # v5
 
       - name: Build wheel and sdist
         run: uv build
 
+      # Fail fast if the tag already exists on origin (e.g. re-running the workflow
+      # for the same version) before attempting to push, to surface a clear error
+      # rather than a confusing "already exists" git message.
+      - name: Push release tag
+        run: |
+          if git ls-remote --exit-code --tags origin \
+              "refs/tags/v${{ steps.normalize.outputs.version }}" > /dev/null 2>&1; then
+            echo "ERROR: tag v${{ steps.normalize.outputs.version }} already exists on origin" >&2
+            exit 1
+          fi
+          git push origin "v${{ steps.normalize.outputs.version }}"
+
       - name: Upload dist artifact
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
         with:
           name: dist
           path: dist/
           if-no-files-found: error
 
+  # IMPORTANT: The PyPI and TestPyPI Trusted Publisher configurations must reference
+  # this workflow file (`.github/workflows/release.yml`). If they still point to the
+  # former `publish.yml`, OIDC token exchange will be rejected by PyPI/TestPyPI.
+  # Update both configs at https://pypi.org and https://test.pypi.org before running
+  # this workflow for the first time.
   publish-testpypi:
     name: Publish → TestPyPI
     needs: build

docs/metamorphic/plans/2026-06-18-golden-vector-parity.md

@@ -1092,9 +1092,15 @@ jobs:
           git push origin v${{ inputs.version }}
 ```
 
-Note: the tag push triggers `publish.yml` which runs tests, builds the wheel and sdist via `uv build`, and publishes to TestPyPI then PyPI using OIDC Trusted Publishing.
+Note: the merged `release.yml` handles the full pipeline — tests (matrix), build,
+TestPyPI → PyPI publish (OIDC Trusted Publishing), and GitHub Release creation. No
+GitHub App token is required; `GITHUB_TOKEN` with `contents: write` handles the tag
+push. The PyPI/TestPyPI Trusted Publisher configuration must reference `release.yml`
+(not the former `publish.yml`).
 
-Required secrets: `RELEASE_APP_ID`, `RELEASE_APP_PRIVATE_KEY` (GitHub App with `contents:write` on `nauticalab/starfix-python`).
+Required secrets: `STARFIX_APP_ID` + `STARFIX_APP_PRIVATE_KEY` (for `golden-sync-check`
+in `ci.yml`). The `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` secrets are no longer
+needed by `release.yml`.
 
 - [ ] **Step 2: Commit**
 
@@ -1124,9 +1130,9 @@ gh pr create \
 - Adds `tests/golden/include_metadata_v0.3.json` (copied from authoritative Rust fixture)
 - Adds `tests/test_golden_parity_metadata.py`: 9 parametrized cross-language parity tests + 2 invariant tests
 - Adds `golden-sync-check` CI job to `ci.yml` — fetches fixture from `nauticalab/starfix` main on every PR and fails on drift
-- Adds manual `release.yml` workflow using GitHub App token
+- Adds manual `release.yml` workflow: tests → build → TestPyPI → PyPI → GitHub Release (OIDC, no API token secrets needed)
 
-Requires `STARFIX_APP_ID` + `STARFIX_APP_PRIVATE_KEY` secrets (for drift check) and `RELEASE_APP_ID` + `RELEASE_APP_PRIVATE_KEY` secrets (for release workflow) to be set on the repo.
+Requires `STARFIX_APP_ID` + `STARFIX_APP_PRIVATE_KEY` secrets (for `golden-sync-check` drift check) to be set on the repo. Also requires the PyPI/TestPyPI Trusted Publisher configs to reference `.github/workflows/release.yml`.
 
 Part of PLT-1735. Companion PR: nauticalab/starfix (Rust side).
 

docs/metamorphic/specs/2026-06-18-golden-vector-parity-design.md

@@ -326,47 +326,22 @@ Required secrets: `RELEASE_APP_ID`, `RELEASE_APP_PRIVATE_KEY` — a GitHub App w
 1. `cargo-release` bumps `Cargo.toml` → commits → publishes crate to crates.io → creates `v{version}` tag → pushes both
 2. Tag push fires `ci.yml` → runs tests and verifies version/tag sync
 
-#### `nauticalab/starfix-python` — new `.github/workflows/release.yml`
+#### `nauticalab/starfix-python` — `.github/workflows/release.yml`
 
 `hatch-vcs` reads the version from git tags automatically; there is no version file to
-bump. The release workflow only needs to create and push the tag:
+bump. The release workflow handles the full pipeline: tests, build, TestPyPI → PyPI
+publish, and GitHub Release creation. No GitHub App token is needed — `GITHUB_TOKEN`
+with `contents: write` is sufficient for the tag push.
 
-```yaml
-name: release
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release version (e.g. 0.3.0)'
-        required: true
-        type: string
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Generate GitHub App token
-        id: app-token
-        uses: actions/create-github-app-token@v3
-        with:
-          app-id: ${{ secrets.RELEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
-
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
+The tag is created locally first (so `hatch-vcs` can derive the version during `uv build`),
+then pushed to origin only after a successful build to avoid leaving a dangling remote tag
+on build failure.
 
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Tag and push release
-        run: |
-          git tag v${{ inputs.version }}
-          git push origin v${{ inputs.version }}
-```
+Job sequence: `test` (matrix 3.10/3.11/3.12) → `build` (local tag + build + push tag) →
+`publish-testpypi` → `publish-pypi` (PyPI publish + GitHub Release).
 
-Tag push fires the existing `publish.yml` → pure-Python package published to PyPI.
+> **Note:** The PyPI and TestPyPI Trusted Publisher configurations must reference
+> `.github/workflows/release.yml`. Update both configs before triggering the first release.
 
 ### Release procedure (coordinated across both repos)