project-auto-wizard 0.14.0 → 0.15.1

package/payload/workflows/common/PROJECT-COMMON-RELEASE-PUBLISH.yaml

@@ -35,6 +35,13 @@
 # trigger and workflow_dispatch is dispatched too. A PAT or human merge
 # already fired the push event, so those are left alone (no double deploy).
 #
+# The trunk-based docs commit is pushed with fetch -> rebase -> push retries.
+# If README.md conflicts with a concurrent README commit (a date refresh),
+# the remote README is kept and the released version line is reapplied, so
+# a README conflict never stops the tag and the Release from being created.
+# README-VERSION-UPDATE skips its own push run in trunk-based mode; this
+# workflow dispatches it after publishing instead.
+#
 # Release-confirm pattern: "chore(release):" — keep in sync with
 # PROJECT-COMMON-AUTO-CHANGELOG-CONTROL and PROJECT-COMMON-VERSION-CONTROL.
 #
@@ -94,15 +101,18 @@ jobs:
       - name: Detect branch mode
         id: mode
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           # scoped to the metadata: -> template: -> branches: chain so an
           # unrelated top-level "mode:" key can never hijack the value
           MODE=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?branches:.*?mode:\s*\"?([A-Za-z-]+)", t, re.S); print(m.group(1) if m else "pr-flow")' 2>/dev/null || echo "pr-flow")
           echo "mode=$MODE" >> $GITHUB_OUTPUT
-          echo "branch mode: $MODE"
+          echo "$(m wf_release.branch_mode mode="$MODE")"
 
       - name: Release gate
         id: gate
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
           m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           MODE="${{ steps.mode.outputs.mode }}"
           EVENT="${{ github.event_name }}"
@@ -123,11 +133,11 @@ jobs:
 
           echo "proceed=$PROCEED" >> $GITHUB_OUTPUT
           if [ "$PROCEED" = "true" ]; then
-            echo "release gate open (mode=$MODE, event=$EVENT)"
+            echo "$(m wf_release.gate_open mode="$MODE" event="$EVENT")"
             exit 0
           fi
 
-          echo "not a release-confirm push in pr-flow mode — skipping"
+          echo "$(m wf_release.gate_closed)"
 
           # Drift guard: skipping is normal, but a version.yml that
           # has run ahead of the newest tag is not — it means the version was
@@ -138,13 +148,13 @@ jobs:
           LATEST_VERSION="${LATEST_TAG#v}"
 
           if [ -z "$FILE_VERSION" ] || [ -z "$LATEST_VERSION" ]; then
-            echo "drift guard skipped (no version.yml version or no tag yet)"
+            echo "$(m wf_release.drift_skipped)"
             exit 0
           fi
 
           HIGHER=$(printf '%s\n%s\n' "$FILE_VERSION" "$LATEST_VERSION" | sort -V | tail -n 1)
           if [ "$FILE_VERSION" != "$LATEST_VERSION" ] && [ "$HIGHER" = "$FILE_VERSION" ]; then
-            echo "::error::version.yml($FILE_VERSION) is ahead of the newest tag($LATEST_TAG) but no release was published — this version will never reach npm. Recover with: Actions → PROJECT-RELEASE-PUBLISH → Run workflow (workflow_dispatch bypasses this gate)."
+            echo "::error::$(m wf_release.drift_error file_version="$FILE_VERSION" latest_tag="$LATEST_TAG")"
             {
               echo "$(m wf_release.drift_heading)"
               echo ""
@@ -157,7 +167,7 @@ jobs:
             exit 1
           fi
 
-          echo "drift guard ok (version.yml=$FILE_VERSION, latest tag=$LATEST_TAG)"
+          echo "$(m wf_release.drift_ok file_version="$FILE_VERSION" latest_tag="$LATEST_TAG")"
 
       - name: Read semver_auto option from version.yml
         id: semver_options
@@ -166,11 +176,13 @@ jobs:
           steps.mode.outputs.mode == 'trunk-based' &&
           github.event_name == 'push'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           # scoped to the metadata: -> template: -> options: chain so an
           # unrelated "semver_auto:" key can never hijack the value
           SEMVER_AUTO=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?semver_auto:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
           echo "semver_auto=$SEMVER_AUTO" >> $GITHUB_OUTPUT
-          echo "semver_auto option: $SEMVER_AUTO"
+          echo "$(m wf_common.semver_auto_option semver_auto="$SEMVER_AUTO")"
 
       - name: Read copilot_ai option from version.yml
         id: copilot_options
@@ -179,11 +191,13 @@ jobs:
           steps.mode.outputs.mode == 'trunk-based' &&
           github.event_name == 'push'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           # scoped to the metadata: -> template: -> options: chain so an
           # unrelated "copilot_ai:" key can never hijack the value
           COPILOT_AI=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?copilot_ai:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
           echo "copilot_ai=$COPILOT_AI" >> $GITHUB_OUTPUT
-          echo "copilot_ai option: $COPILOT_AI"
+          echo "$(m wf_common.copilot_ai_option copilot_ai="$COPILOT_AI")"
 
       - name: Install Copilot CLI
         if: >-
@@ -206,13 +220,15 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }}
           COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           # Idempotency: on a re-run of a failed job the checked-out HEAD may
           # already be this workflow's own docs commit — never bump twice.
           # Jump straight to the common tail (tag + release for the current
           # version).
           HEAD_MSG=$(git log -1 --pretty=%s)
           if printf '%s\n' "$HEAD_MSG" | grep -q "^chore(version): release v.* docs \[skip ci\]"; then
-            echo "HEAD is already this workflow's release docs commit — skipping re-increment (idempotent re-run)"
+            echo "$(m wf_release.head_is_docs_commit)"
             exit 0
           fi
 
@@ -222,11 +238,11 @@ jobs:
           # release (no previous tag to diff against).
           LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
           if [ -n "$LAST_TAG" ]; then
-            echo "collecting commits since $LAST_TAG"
+            echo "$(m wf_release.collect_since last_tag="$LAST_TAG")"
             LOG_RANGE="${LAST_TAG}..HEAD"
             DIFF_BASE="$LAST_TAG"
           else
-            echo "no previous tag — collecting the full history"
+            echo "$(m wf_release.collect_all)"
             LOG_RANGE="HEAD"
             DIFF_BASE="4b825dc642cb6eb9a060e54bf8d69288fbee4904" # git empty tree hash
           fi
@@ -248,15 +264,15 @@ jobs:
           else
             BUMP="patch"
           fi
-          echo "bump level: $BUMP"
+          echo "$(m wf_common.bump_level bump="$BUMP")"
 
           NEW_VERSION=$(python3 .github/scripts/version_manager.py increment --bump "$BUMP" | tail -n 1)
           if [ -z "$NEW_VERSION" ]; then
-            echo "version bump failed"
+            echo "$(m wf_common.version_bump_failed)"
             exit 1
           fi
           python3 .github/scripts/version_manager.py sync
-          echo "release version: $NEW_VERSION ($BUMP)"
+          echo "$(m wf_release.release_version new_version="$NEW_VERSION" bump="$BUMP")"
 
           python3 .github/scripts/changelog_manager.py ai-summary \
             --commits-file commits.txt \
@@ -289,39 +305,57 @@ jobs:
           git add -u
           git ls-files -z --others --exclude-standard -- CHANGELOG.json CHANGELOG.md | xargs -0 -r git add --
           if git diff --staged --quiet; then
-            echo "no changes to commit"
+            echo "$(m wf_common.no_changes)"
           else
             git commit -m "chore(version): release v${NEW_VERSION} docs [skip ci]"
 
-            # Race-condition guard: pull-rebase then push (up to 3 retries)
-            MAX_RETRIES=3
+            # >>> push-with-retry
+            # Race-condition guard: fetch -> rebase -> push, retried. A concurrent
+            # README-only commit (date refresh) touches the same version line and
+            # conflicts on rebase; the remote README is kept and this run's version
+            # line is reapplied, so a README conflict never blocks the release.
+            MAX_RETRIES=5
             RETRY_COUNT=0
             PUSH_SUCCESS=false
 
             while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
               RETRY_COUNT=$((RETRY_COUNT + 1))
-              echo "push attempt $RETRY_COUNT/$MAX_RETRIES..."
+              echo "$(m wf_common.push_attempt retry_count="$RETRY_COUNT" max_retries="$MAX_RETRIES")"
 
               if git push origin HEAD:{{MAIN_BRANCH}}; then
                 PUSH_SUCCESS=true
-                echo "release docs pushed"
+                echo "$(m wf_release.docs_pushed)"
                 break
-              else
-                echo "push failed, syncing with remote..."
-                if git pull --rebase origin {{MAIN_BRANCH}}; then
-                  echo "rebase ok, retrying push..."
-                else
-                  echo "rebase failed, manual conflict resolution required"
-                  git rebase --abort 2>/dev/null || true
-                  exit 1
+              fi
+
+              echo "$(m wf_common.push_failed_syncing)"
+              git fetch origin {{MAIN_BRANCH}}
+              if git rebase origin/{{MAIN_BRANCH}}; then
+                echo "$(m wf_common.rebase_ok)"
+                continue
+              fi
+
+              # Only README.md conflicting: "ours" is the remote side during a rebase
+              if [ "$(git diff --name-only --diff-filter=U)" = "README.md" ]; then
+                git checkout --ours -- README.md
+                python3 -c 'import sys; sys.path.insert(0, ".github/scripts"); import version_manager as vm; vm.update_readme_version(vm.get_current_version())' || true
+                git add README.md
+                if GIT_EDITOR=true git rebase --continue; then
+                  echo "$(m wf_common.readme_conflict_resolved)"
+                  continue
                 fi
               fi
+
+              echo "$(m wf_common.rebase_failed)"
+              git rebase --abort 2>/dev/null || true
+              exit 1
             done
 
             if [ "$PUSH_SUCCESS" = false ]; then
-              echo "push failed after $MAX_RETRIES attempts"
+              echo "$(m wf_common.push_gave_up max_retries="$MAX_RETRIES")"
               exit 1
             fi
+            # <<< push-with-retry
           fi
 
       - name: Resolve version + idempotency guard
@@ -330,9 +364,11 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
           if [ -z "$VERSION" ]; then
-            echo "failed to read version"
+            echo "$(m wf_release.read_version_failed)"
             exit 1
           fi
           echo "version=$VERSION" >> $GITHUB_OUTPUT
@@ -344,32 +380,36 @@ jobs:
           # "release created" can be re-run and still publish the release.
           if git rev-parse "v$VERSION" >/dev/null 2>&1; then
             echo "tag_exists=true" >> $GITHUB_OUTPUT
-            echo "tag v$VERSION already exists — skipping tag push"
+            echo "$(m wf_release.tag_exists version="$VERSION")"
           else
             echo "tag_exists=false" >> $GITHUB_OUTPUT
           fi
 
           if gh release view "v$VERSION" >/dev/null 2>&1; then
             echo "release_exists=true" >> $GITHUB_OUTPUT
-            echo "release v$VERSION already exists — nothing to publish"
+            echo "$(m wf_release.release_exists version="$VERSION")"
           else
             echo "release_exists=false" >> $GITHUB_OUTPUT
-            echo "publishing release v$VERSION"
+            echo "$(m wf_release.publishing version="$VERSION")"
           fi
 
       - name: Create and push tag
         if: steps.gate.outputs.proceed == 'true' && steps.version.outputs.tag_exists != 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           VERSION="${{ steps.version.outputs.version }}"
           git tag "v$VERSION"
           git push origin "v$VERSION"
-          echo "tag v$VERSION pushed"
+          echo "$(m wf_release.tag_pushed version="$VERSION")"
 
       - name: Build release notes (changelog export + GitHub generate-notes)
         if: steps.gate.outputs.proceed == 'true' && steps.version.outputs.release_exists != 'true'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           VERSION="${{ steps.version.outputs.version }}"
 
           # AI/changelog notes for this version
@@ -397,7 +437,7 @@ jobs:
             echo "Release v$VERSION" > notes.md
           fi
 
-          echo "release notes assembled ($(wc -c < notes.md) bytes)"
+          echo "$(m wf_release.notes_assembled n="$(wc -c < notes.md)")"
 
       - name: Create GitHub Release
         if: steps.gate.outputs.proceed == 'true' && steps.version.outputs.release_exists != 'true'
@@ -408,9 +448,11 @@ jobs:
           # default token.
           GH_TOKEN: ${{ secrets.WORKFLOW_PAT || github.token }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           VERSION="${{ steps.version.outputs.version }}"
           gh release create "v$VERSION" --title "v$VERSION" --notes-file notes.md
-          echo "GitHub Release v$VERSION published"
+          echo "$(m wf_release.published version="$VERSION")"
 
       - name: Trigger README-VERSION-UPDATE
         # Pushes made with the bot token (GITHUB_TOKEN) never wake the README update
@@ -422,6 +464,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
           m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           if gh workflow run PROJECT-COMMON-README-VERSION-UPDATE.yaml --ref {{MAIN_BRANCH}}; then
             echo "$(m wf_release.readme_dispatch_ok)"
@@ -449,6 +492,7 @@ jobs:
           RELEASE_VERSION: ${{ steps.version.outputs.version }}
           MAIN_BRANCH: "{{MAIN_BRANCH}}"
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
           m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           # Merge commit of this version's release PR - releases that are not merges
           # (safety-net bump, manual republish) were already deployed by a human push,

package/payload/workflows/common/PROJECT-COMMON-VERSION-CONTROL.yaml

@@ -66,20 +66,22 @@ jobs:
       - name: Release merge / mode guard
         id: release_guard
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           SKIP="false"
 
           # trunk-based mode: RELEASE-PUBLISH owns versioning — skip safety net
           MODE=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"^\s*mode:\s*\"?([A-Za-z-]+)", t, re.M); print(m.group(1) if m else "pr-flow")' 2>/dev/null || echo "pr-flow")
           if [ "$MODE" = "trunk-based" ]; then
             SKIP="true"
-            echo "trunk-based mode detected — RELEASE-PUBLISH owns version bumping, skipping"
+            echo "$(m wf_version.trunk_skip)"
           fi
 
           # release-confirm pattern: the merge commit of a release PR
           HEAD_MSG=$(git log -1 --pretty=%B)
           if echo "$HEAD_MSG" | grep -q "chore(release):"; then
             SKIP="true"
-            echo "release-confirm commit detected (chore(release):) — skipping safety-net bump"
+            echo "$(m wf_version.confirm_skip)"
           fi
 
           # release merge detection: the release push includes a version.yml change
@@ -91,51 +93,57 @@ jobs:
           fi
           if git diff --name-only $RANGE 2>/dev/null | grep -qx "version.yml"; then
             SKIP="true"
-            echo "release merge detected (push contains a version.yml change) — skipping safety-net bump"
+            echo "$(m wf_version.release_merge_skip)"
           fi
 
           echo "skip=$SKIP" >> $GITHUB_OUTPUT
           if [ "$SKIP" = "false" ]; then
-            echo "direct push to {{MAIN_BRANCH}} detected — running safety-net version bump"
+            echo "$(m wf_version.direct_push main_branch="{{MAIN_BRANCH}}")"
           fi
 
       - name: Read current version
         id: current_version
         if: steps.release_guard.outputs.skip != 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           CURRENT_VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
           if [ -z "$CURRENT_VERSION" ]; then
-            echo "failed to read current version"
+            echo "$(m wf_version.read_current_failed)"
             exit 1
           fi
           echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
-          echo "current version: $CURRENT_VERSION"
+          echo "$(m wf_version.current_version current_version="$CURRENT_VERSION")"
 
       - name: Bump patch version and sync
         id: version
         if: steps.release_guard.outputs.skip != 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           NEW_VERSION=$(python3 .github/scripts/version_manager.py increment | tail -n 1)
           if [ -z "$NEW_VERSION" ]; then
-            echo "version bump failed"
+            echo "$(m wf_common.version_bump_failed)"
             exit 1
           fi
           python3 .github/scripts/version_manager.py sync
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "new version: $NEW_VERSION"
+          echo "$(m wf_version.new_version new_version="$NEW_VERSION")"
 
       - name: Read project types
         id: project_info
         if: steps.release_guard.outputs.skip != 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           if [ -f "version.yml" ]; then
             PROJECT_TYPES=$(grep "^project_types:" version.yml 2>/dev/null | sed -E 's/.*\[([^]]*)\].*/\1/' | tr -d '" ')
             PROJECT_TYPES=${PROJECT_TYPES:-unknown}
             echo "project_types=$PROJECT_TYPES" >> $GITHUB_OUTPUT
-            echo "project types: $PROJECT_TYPES"
+            echo "$(m wf_version.project_types project_types="$PROJECT_TYPES")"
           else
             echo "project_types=unknown" >> $GITHUB_OUTPUT
-            echo "version.yml not found"
+            echo "$(m wf_version.yml_not_found)"
           fi
 
       - name: Update CHANGELOG for the safety-net release
@@ -150,6 +158,8 @@ jobs:
           AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
           AI_MODEL: ${{ vars.AI_MODEL }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           NEW_VERSION="${{ steps.version.outputs.new_version }}"
 
           # Commits pushed straight to {{MAIN_BRANCH}} since the last release tag (full history if there is no tag)
@@ -160,7 +170,7 @@ jobs:
           # line. The script reads each line as one entry, so passing the whole body (%B)
           # would turn description lines into change entries.
           git log --pretty=%b "$LOG_RANGE" | grep -E '^BREAKING[ -]CHANGE[[:space:]]*:' >> commits.txt || true
-          echo "commits since ${LAST_TAG:-the beginning}: $(wc -l < commits.txt)"
+          echo "$(m wf_version.commits_since last_tag="${LAST_TAG:-the beginning}" n="$(wc -l < commits.txt)")"
 
           python3 .github/scripts/changelog_manager.py ai-summary \
             --commits-file commits.txt \
@@ -183,6 +193,8 @@ jobs:
         id: commit_push
         if: steps.release_guard.outputs.skip != 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
 
@@ -193,45 +205,63 @@ jobs:
           git ls-files -z --others --exclude-standard -- CHANGELOG.json CHANGELOG.md | xargs -0 -r git add --
 
           if git diff --staged --quiet; then
-            echo "no changes to commit (already in sync)"
+            echo "$(m wf_version.no_changes_synced)"
             echo "pushed=false" >> "$GITHUB_OUTPUT"
           else
             NEW_VERSION="${{ steps.version.outputs.new_version }}"
             COMMIT_MSG="chore(version): bump to v${NEW_VERSION} [skip ci]"
 
             if git commit -m "$COMMIT_MSG"; then
-              # Race-condition guard: pull-rebase then push (up to 3 retries)
-              MAX_RETRIES=3
+              # >>> push-with-retry
+              # Race-condition guard: fetch -> rebase -> push, retried. A concurrent
+              # README-only commit (date refresh) touches the same version line and
+              # conflicts on rebase; the remote README is kept and this run's version
+              # line is reapplied, so a README conflict never blocks the release.
+              MAX_RETRIES=5
               RETRY_COUNT=0
               PUSH_SUCCESS=false
 
               while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
                 RETRY_COUNT=$((RETRY_COUNT + 1))
-                echo "push attempt $RETRY_COUNT/$MAX_RETRIES..."
+                echo "$(m wf_common.push_attempt retry_count="$RETRY_COUNT" max_retries="$MAX_RETRIES")"
 
                 if git push origin HEAD:{{MAIN_BRANCH}}; then
                   PUSH_SUCCESS=true
-                  echo "version bump commit pushed"
+                  echo "$(m wf_version.bump_pushed)"
                   break
-                else
-                  echo "push failed, syncing with remote..."
-                  if git pull --rebase origin {{MAIN_BRANCH}}; then
-                    echo "rebase ok, retrying push..."
-                  else
-                    echo "rebase failed, manual conflict resolution required"
-                    git rebase --abort 2>/dev/null || true
-                    exit 1
+                fi
+
+                echo "$(m wf_common.push_failed_syncing)"
+                git fetch origin {{MAIN_BRANCH}}
+                if git rebase origin/{{MAIN_BRANCH}}; then
+                  echo "$(m wf_common.rebase_ok)"
+                  continue
+                fi
+
+                # Only README.md conflicting: "ours" is the remote side during a rebase
+                if [ "$(git diff --name-only --diff-filter=U)" = "README.md" ]; then
+                  git checkout --ours -- README.md
+                  python3 -c 'import sys; sys.path.insert(0, ".github/scripts"); import version_manager as vm; vm.update_readme_version(vm.get_current_version())' || true
+                  git add README.md
+                  if GIT_EDITOR=true git rebase --continue; then
+                    echo "$(m wf_common.readme_conflict_resolved)"
+                    continue
                   fi
                 fi
+
+                echo "$(m wf_common.rebase_failed)"
+                git rebase --abort 2>/dev/null || true
+                exit 1
               done
 
               if [ "$PUSH_SUCCESS" = false ]; then
-                echo "push failed after $MAX_RETRIES attempts"
+                echo "$(m wf_common.push_gave_up max_retries="$MAX_RETRIES")"
                 exit 1
               fi
+              # <<< push-with-retry
               echo "pushed=true" >> "$GITHUB_OUTPUT"
             else
-              echo "commit failed"
+              echo "$(m wf_version.commit_failed)"
               exit 1
             fi
           fi
@@ -242,6 +272,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
           m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           gh workflow run PROJECT-COMMON-RELEASE-PUBLISH.yaml --ref {{MAIN_BRANCH}}
           echo "$(m wf_version.release_publish_triggered)"
@@ -254,13 +285,14 @@ jobs:
         # so only a warning is left.
         if: steps.release_guard.outputs.skip != 'true' && steps.commit_push.outputs.pushed == 'true'
         run: |
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
           m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
           DEVELOP_BRANCH="{{DEVELOP_BRANCH}}"
           NEW_VERSION="${{ steps.version.outputs.new_version }}"
           MANUAL="git checkout $DEVELOP_BRANCH && git pull && git merge origin/{{MAIN_BRANCH}} && git push"
 
           if ! git ls-remote --exit-code --heads origin "$DEVELOP_BRANCH" >/dev/null 2>&1; then
-            echo "branch $DEVELOP_BRANCH not found — nothing to back-merge"
+            echo "$(m wf_version.no_develop develop_branch="$DEVELOP_BRANCH")"
             exit 0
           fi
 
@@ -268,7 +300,7 @@ jobs:
             git fetch -q origin "$DEVELOP_BRANCH" {{MAIN_BRANCH}}
             git checkout -q -B safety-net-back-merge "origin/$DEVELOP_BRANCH"
             if git merge-base --is-ancestor "origin/{{MAIN_BRANCH}}" HEAD; then
-              echo "$DEVELOP_BRANCH already contains {{MAIN_BRANCH}}"
+              echo "$(m wf_version.already_contains develop_branch="$DEVELOP_BRANCH" main_branch="{{MAIN_BRANCH}}")"
               exit 0
             fi
             if ! git merge --no-edit -m "chore(version): merge v${NEW_VERSION} safety-net bump into ${DEVELOP_BRANCH} [skip ci]" "origin/{{MAIN_BRANCH}}"; then
@@ -277,19 +309,23 @@ jobs:
               exit 0
             fi
             if git push origin "HEAD:$DEVELOP_BRANCH"; then
-              echo "safety-net bump v$NEW_VERSION merged into $DEVELOP_BRANCH"
+              echo "$(m wf_version.backmerged new_version="$NEW_VERSION" develop_branch="$DEVELOP_BRANCH")"
               exit 0
             fi
-            echo "push attempt $ATTEMPT failed — retrying"
+            echo "$(m wf_version.push_retry attempt="$ATTEMPT")"
             sleep 5
           done
           echo "::warning::$(m wf_version.backmerge_push_failed dev="$DEVELOP_BRANCH" manual="$MANUAL")"
 
       - name: Summary
         if: always()
+        env:
+          PAW_REF_NAME: ${{ github.ref_name }}
         run: |
-          echo "version-control workflow finished"
-          echo "  skipped (release merge / trunk-based): ${{ steps.release_guard.outputs.skip }}"
-          echo "  previous version: ${{ steps.current_version.outputs.current_version }}"
-          echo "  new version: ${{ steps.version.outputs.new_version }}"
-          echo "  branch: ${{ github.ref_name }}"
+          [ -f "$GITHUB_WORKSPACE/.github/scripts/messages.py" ] || { echo "::error::messages.py is missing; rerun \`npx project-auto-wizard --mode full --force\`"; exit 1; }
+          m() { python3 "$GITHUB_WORKSPACE/.github/scripts/messages.py" get "$@"; }
+          echo "$(m wf_version.finished)"
+          echo "$(m wf_version.sum_skipped skip="${{ steps.release_guard.outputs.skip }}")"
+          echo "$(m wf_version.sum_previous current_version="${{ steps.current_version.outputs.current_version }}")"
+          echo "$(m wf_version.sum_new new_version="${{ steps.version.outputs.new_version }}")"
+          echo "$(m wf_version.sum_branch ref_name="$PAW_REF_NAME")"