fix: handle non-version pushes in release workflow to prevent failures

Author: markhazleton

.github/workflows/release.yml

@@ -32,7 +32,12 @@ jobs:
         run: |
           chmod +x .github/workflows/scripts/get-next-version.sh
           .github/workflows/scripts/get-next-version.sh "${{ github.event.inputs.release_version || '' }}"
+      - name: Skip if nothing to release
+        if: steps.get_tag.outputs.skip_release == 'true'
+        run: |
+          echo "::notice::pyproject.toml version is already tagged. No release needed for this push."
       - name: Validate release version matches pyproject.toml
+        if: steps.get_tag.outputs.skip_release != 'true'
         run: |
           pyproject_version=$(grep -oE '^[[:space:]]*version[[:space:]]*=[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+"' pyproject.toml | head -n1 | sed -E 's/.*"([0-9]+\.[0-9]+\.[0-9]+)"/\1/')
           if [ -z "$pyproject_version" ]; then
@@ -51,25 +56,26 @@ jobs:
 
           echo "Version parity check passed: $release_version"
       - name: Check if release already exists
+        if: steps.get_tag.outputs.skip_release != 'true'
         id: check_release
         run: |
           chmod +x .github/workflows/scripts/check-release-exists.sh
           .github/workflows/scripts/check-release-exists.sh ${{ steps.get_tag.outputs.new_version }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Create release package variants
-        if: steps.check_release.outputs.exists == 'false'
+        if: steps.get_tag.outputs.skip_release != 'true' && steps.check_release.outputs.exists == 'false'
         run: |
           chmod +x .github/workflows/scripts/create-release-packages.sh
           .github/workflows/scripts/create-release-packages.sh ${{ steps.get_tag.outputs.new_version }}
       - name: Generate release notes
-        if: steps.check_release.outputs.exists == 'false'
+        if: steps.get_tag.outputs.skip_release != 'true' && steps.check_release.outputs.exists == 'false'
         id: release_notes
         run: |
           chmod +x .github/workflows/scripts/generate-release-notes.sh
           .github/workflows/scripts/generate-release-notes.sh ${{ steps.get_tag.outputs.new_version }} ${{ steps.get_tag.outputs.latest_tag }}
       - name: Create GitHub Release
-        if: steps.check_release.outputs.exists == 'false'
+        if: steps.get_tag.outputs.skip_release != 'true' && steps.check_release.outputs.exists == 'false'
         run: |
           chmod +x .github/workflows/scripts/create-github-release.sh
           .github/workflows/scripts/create-github-release.sh ${{ steps.get_tag.outputs.new_version }}

.github/workflows/scripts/get-next-version.sh

@@ -78,6 +78,12 @@ if PYPROJECT_VERSION=$(get_pyproject_version); then
     echo "New version will be: $PYPROJECT_VERSION (source: pyproject.toml)"
     exit 0
   fi
+
+  # pyproject.toml version is already tagged — nothing new to release
+  echo "new_version=$PYPROJECT_VERSION" >> $GITHUB_OUTPUT
+  echo "skip_release=true" >> $GITHUB_OUTPUT
+  echo "pyproject.toml version $PYPROJECT_VERSION is already tagged. Nothing to release."
+  exit 0
 fi
 
 # 3) Fallback: increment latest tag

CHANGELOG.md

@@ -14,6 +14,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Agent-agnostic canonical layout**: All command prompts now live in `.documentation/commands/` as the single source of truth. Platform directories (`.claude/`, `.github/`, `.cursor/`, etc.) contain only thin shims that redirect to canonical content with user-override resolution.
 - **Multi-user personalization**: New `/speckit.personalize` command creates per-user prompt overrides in `.documentation/{git-user}/commands/`. Users can customize any command without affecting team defaults; personalized files are committed to git for transparency.
 - **Personalize command template**: `templates/commands/personalize.md` — resolves git user identity, copies and annotates shared prompts for individual customization.
+- **Release template Step 10 — Update Public-Facing Version References**: `/speckit.release` now requires updating roadmap, release notes, and index docs to match the new version, plus a stale-version-string scan, preventing public documentation from drifting behind the actual release.
+
+### Fixed
+
+- **Release workflow fails on non-version pushes**: When `pyproject.toml` version was already tagged, `get-next-version.sh` would auto-increment to the next patch and the validation step would fail with a version mismatch. The script now detects the already-tagged condition, sets `skip_release=true`, and the workflow exits gracefully with a notice instead of failing.
 
 ### Changed