project-auto-wizard 0.14.0 → 0.15.1

package/payload/workflows/common/PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml

@@ -85,16 +85,28 @@ jobs:
       github.event.pull_request.head.ref == '{{DEVELOP_BRANCH}}'
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       pull-requests: read
     outputs:
       open: ${{ steps.state.outputs.open }}
     steps:
+      # Only the message catalog and language setting are needed for the log wording
+      - name: Checkout message catalog
+        uses: actions/checkout@v7
+        with:
+          sparse-checkout: |
+            .github/scripts/messages.py
+            version.yml
+          sparse-checkout-cone-mode: false
+
       - name: Read the current PR state
         id: state
         env:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
         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 "$@"; }
           PR_NUMBER=${{ github.event.pull_request.number }}
           # A push to {{DEVELOP_BRANCH}} mid-pipeline queues a run that later reprocesses the
           # already-merged PR - an empty summary comment, duplicate CHANGELOG entries and a
@@ -104,10 +116,10 @@ jobs:
           STATE=$(gh pr view "$PR_NUMBER" --json state -q .state 2>/dev/null || echo "UNKNOWN")
           if [ "$STATE" = "MERGED" ] || [ "$STATE" = "CLOSED" ]; then
             echo "open=false" >> "$GITHUB_OUTPUT"
-            echo "::notice::PR #$PR_NUMBER is already $STATE — skipping the release pipeline"
+            echo "::notice::$(m wf_changelog.pr_not_open pr_number="$PR_NUMBER" state="$STATE")"
           else
             echo "open=true" >> "$GITHUB_OUTPUT"
-            echo "PR #$PR_NUMBER state: $STATE"
+            echo "$(m wf_changelog.pr_state pr_number="$PR_NUMBER" state="$STATE")"
           fi
 
   changelog-and-merge:
@@ -131,18 +143,22 @@ jobs:
       - name: Read semver_auto option from version.yml
         id: semver_options
         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 "$@"; }
           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
         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: steps.copilot_options.outputs.copilot_ai == 'true'
@@ -152,6 +168,8 @@ jobs:
       - name: Collect commits since last release
         id: collect
         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 fetch origin {{MAIN_BRANCH}}
           git log --pretty=%s "origin/{{MAIN_BRANCH}}..HEAD" > commits.txt
           # Body-footer BREAKING CHANGE: lines are appended after the subject list, one per
@@ -165,7 +183,7 @@ jobs:
             cp _full_diff_stat.txt diff_stat.txt
           fi
           rm -f _full_diff_stat.txt
-          echo "commits to summarize: $(wc -l < commits.txt)"
+          echo "$(m wf_changelog.commits_to_summarize n="$(wc -l < commits.txt)")"
 
       - name: Collect issues merged into {{DEVELOP_BRANCH}}
         continue-on-error: true
@@ -173,6 +191,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           GITHUB_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 "$@"; }
           git log --pretty=%H "origin/{{MAIN_BRANCH}}..HEAD" > commit_shas.txt
 
@@ -211,6 +230,8 @@ 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: never raise a version this PR already confirmed (not yet published).
           # Looking only at the HEAD commit message lets the guard slip when more commits
           # pile on top of the confirm commit (extra {{DEVELOP_BRANCH}} pushes, a
@@ -227,7 +248,7 @@ jobs:
           else
             BUMP="patch"
           fi
-          echo "bump level: $BUMP"
+          echo "$(m wf_common.bump_level bump="$BUMP")"
 
           if [ -n "$MAIN_VERSION" ] && [ -n "$HEAD_VERSION" ] && version_gt "$HEAD_VERSION" "$MAIN_VERSION" && ! is_tagged "$HEAD_VERSION"; then
             # Already-confirmed version - recompute from the {{MAIN_BRANCH}} version and raise it
@@ -237,22 +258,22 @@ jobs:
             TARGET=$(python3 -c 'import sys; sys.path.insert(0, ".github/scripts"); from version_manager import increment_version; print(increment_version(sys.argv[1], sys.argv[2]))' "$MAIN_VERSION" "$BUMP")
             if version_gt "$TARGET" "$HEAD_VERSION"; then
               NEW_VERSION=$(python3 .github/scripts/version_manager.py set "$TARGET" | tail -n 1)
-              echo "confirmed version raised: $HEAD_VERSION -> $NEW_VERSION ($BUMP from {{MAIN_BRANCH}} $MAIN_VERSION)"
+              echo "$(m wf_changelog.version_raised head_version="$HEAD_VERSION" new_version="$NEW_VERSION" bump="$BUMP" main_branch="{{MAIN_BRANCH}}" main_version="$MAIN_VERSION")"
             else
               NEW_VERSION="$HEAD_VERSION"
-              echo "version already confirmed and not yet released — reusing $NEW_VERSION ({{MAIN_BRANCH}} is $MAIN_VERSION)"
+              echo "$(m wf_changelog.version_reuse_unreleased new_version="$NEW_VERSION" main_branch="{{MAIN_BRANCH}}" main_version="$MAIN_VERSION")"
             fi
           elif [ -z "$MAIN_VERSION" ] && printf '%s\n' "$HEAD_MSG" | grep -q "^chore(version): confirm v.* \[skip ci\]"; then
             # Re-run of a first release where {{MAIN_BRANCH}} has no version.yml yet
             NEW_VERSION="$HEAD_VERSION"
-            echo "version already confirmed by a previous run — reusing $NEW_VERSION (no re-increment)"
+            echo "$(m wf_changelog.version_reuse_previous new_version="$NEW_VERSION")"
           else
             NEW_VERSION=$(python3 .github/scripts/version_manager.py increment --bump "$BUMP" | tail -n 1)
             python3 .github/scripts/version_manager.py sync
-            echo "release version confirmed: $NEW_VERSION ($BUMP)"
+            echo "$(m wf_changelog.version_confirmed new_version="$NEW_VERSION" bump="$BUMP")"
           fi
           if [ -z "$NEW_VERSION" ]; then
-            echo "version bump failed"
+            echo "$(m wf_common.version_bump_failed)"
             exit 1
           fi
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
@@ -269,6 +290,8 @@ 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 "$@"; }
           VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
 
           SUMMARY_RESULT=$(python3 .github/scripts/changelog_manager.py ai-summary \
@@ -281,7 +304,7 @@ jobs:
           # On fallback, append the reason (the script also emits it as ::warning::) to the engine line so the cause is visible without opening the job log
           FALLBACK_REASON=$(python3 -c 'import html,json,sys; print(html.escape((json.loads(sys.argv[1]).get("fallback_reason") or "")[:200]))' "$SUMMARY_RESULT" 2>/dev/null || echo "")
           ENGINE_LINE="$ENGINE${FALLBACK_REASON:+ ($FALLBACK_REASON)}"
-          echo "summary engine: $ENGINE_LINE"
+          echo "$(m wf_changelog.summary_engine engine_line="$ENGINE_LINE")"
           echo "engine: $ENGINE_LINE" >> "$GITHUB_STEP_SUMMARY"
           echo "engine=$ENGINE" >> $GITHUB_OUTPUT
           echo "fallback_reason=$FALLBACK_REASON" >> $GITHUB_OUTPUT
@@ -296,6 +319,8 @@ jobs:
           FALLBACK_REASON: ${{ steps.summary.outputs.fallback_reason }}
           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 "$@"; }
           PR_NUMBER=${{ github.event.pull_request.number }}
           # Find this bot's earlier summary comment by its marker and replace it so re-runs and re-syncs do not pile up comments
           MARKER="<!-- project-auto-wizard:pr-summary -->"
@@ -315,12 +340,12 @@ jobs:
             --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$MARKER\"))) | .id" 2>/dev/null | tail -n 1 || true)
           if [ -n "$COMMENT_ID" ]; then
             gh api -X PATCH "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}" --input comment_payload.json > /dev/null \
-              && echo "summary comment updated (#${COMMENT_ID})" \
-              || echo "comment update failed — continuing (this workflow never blocks the release)"
+              && echo "$(m wf_changelog.comment_updated comment_id="${COMMENT_ID}")" \
+              || echo "$(m wf_changelog.comment_update_failed)"
           else
             gh api -X POST "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" --input comment_payload.json > /dev/null \
-              && echo "summary comment posted" \
-              || echo "comment post failed — continuing (this workflow never blocks the release)"
+              && echo "$(m wf_changelog.comment_posted)" \
+              || echo "$(m wf_changelog.comment_post_failed)"
           fi
 
           rm -f comment_body.md comment_payload.json
@@ -344,8 +369,12 @@ jobs:
       - name: Commit release docs to the PR head branch
         env:
           GH_TOKEN: ${{ github.token }}
+          # Passed through env so shell metacharacters in the branch name are never parsed as commands
+          PAW_HEAD_REF: ${{ github.event.pull_request.head.ref }}
         run: |
-          HEAD_BRANCH="${{ github.event.pull_request.head.ref }}"
+          [ -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 "$@"; }
+          HEAD_BRANCH="$PAW_HEAD_REF"
           VERSION="${{ steps.bump.outputs.new_version }}"
 
           # Working files must not land in the repo
@@ -356,7 +385,7 @@ jobs:
           # {{DEVELOP_BRANCH}} after the merge).
           PR_STATE=$(gh pr view "${{ github.event.pull_request.number }}" --json state -q .state 2>/dev/null || echo "UNKNOWN")
           if [ "$PR_STATE" = "MERGED" ] || [ "$PR_STATE" = "CLOSED" ]; then
-            echo "::notice::PR is already $PR_STATE — not pushing release docs"
+            echo "::notice::$(m wf_changelog.pr_closed_skip_docs pr_state="$PR_STATE")"
             exit 0
           fi
 
@@ -367,7 +396,7 @@ 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"
+            echo "$(m wf_common.no_changes)"
           else
             git commit -m "chore(version): confirm v${VERSION} and update release docs [skip ci]"
 
@@ -378,18 +407,18 @@ jobs:
 
             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:$HEAD_BRANCH; then
                 PUSH_SUCCESS=true
-                echo "release docs pushed to $HEAD_BRANCH"
+                echo "$(m wf_changelog.docs_pushed head_branch="$HEAD_BRANCH")"
                 break
               else
-                echo "push failed, syncing with remote..."
+                echo "$(m wf_common.push_failed_syncing)"
                 if git pull --rebase origin $HEAD_BRANCH; then
-                  echo "rebase ok, retrying push..."
+                  echo "$(m wf_common.rebase_ok)"
                 else
-                  echo "rebase failed, manual conflict resolution required"
+                  echo "$(m wf_common.rebase_failed)"
                   git rebase --abort 2>/dev/null || true
                   exit 1
                 fi
@@ -397,7 +426,7 @@ jobs:
             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
           fi
@@ -408,6 +437,7 @@ jobs:
           # (RELEASE-PUBLISH etc.); GITHUB_TOKEN merges do not.
           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 "$@"; }
           PR_NUMBER=${{ github.event.pull_request.number }}
           VERSION="${{ steps.bump.outputs.new_version }}"
@@ -424,18 +454,18 @@ jobs:
           MAX_ATTEMPTS=4
           for ATTEMPT in $(seq 1 $MAX_ATTEMPTS); do
             if [ "$(gh pr view "$PR_NUMBER" --json state -q .state 2>/dev/null)" = "MERGED" ]; then
-              echo "PR #$PR_NUMBER is already merged"
+              echo "$(m wf_changelog.pr_already_merged pr_number="$PR_NUMBER")"
               MERGED=true
               break
             fi
             if gh pr merge "$PR_NUMBER" --auto --merge --subject "$SUBJECT" 2> "$ERR_FILE"; then
-              echo "automerge enabled: $SUBJECT"
+              echo "$(m wf_changelog.automerge_enabled subject="$SUBJECT")"
               MERGED=true
               break
             fi
             cat "$ERR_FILE" >&2
             if gh pr merge "$PR_NUMBER" --merge --subject "$SUBJECT" 2> "$ERR_FILE"; then
-              echo "automerge unavailable — merged directly: $SUBJECT"
+              echo "$(m wf_changelog.automerge_unavailable subject="$SUBJECT")"
               MERGED=true
               break
             fi
@@ -451,7 +481,7 @@ jobs:
                 && echo "head branch updated from base" || true
             fi
             WAIT=$((ATTEMPT * 10))
-            echo "merge attempt $ATTEMPT/$MAX_ATTEMPTS failed — retrying in ${WAIT}s"
+            echo "$(m wf_changelog.merge_retry attempt="$ATTEMPT" max_attempts="$MAX_ATTEMPTS" wait="${WAIT}")"
             sleep "$WAIT"
           done
 
@@ -465,7 +495,7 @@ jobs:
             elif [ "$ALLOW_MERGE_COMMIT" = "false" ]; then
               echo "::error::$(m wf_changelog.merge_commit_disabled)"
             else
-              echo "::error::PR merge failed after $MAX_ATTEMPTS attempts (allow_merge_commit=$ALLOW_MERGE_COMMIT) — check branch protection rules, required checks, and token permissions"
+              echo "::error::$(m wf_changelog.merge_gave_up max_attempts="$MAX_ATTEMPTS" allow_merge_commit="$ALLOW_MERGE_COMMIT")"
             fi
             exit 1
           fi
@@ -496,6 +526,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
         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 "$@"; }
           PR_NUMBER=${{ github.event.pull_request.number }}
           MAX_WAIT=1800
@@ -527,6 +558,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
         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_changelog.release_publish_triggered)"

package/payload/workflows/common/PROJECT-COMMON-README-VERSION-UPDATE.yaml

@@ -39,6 +39,15 @@
 # README always ends on the released version. Run it manually
 # (workflow_dispatch) to catch up at any other time.
 #
+# trunk-based mode: RELEASE-PUBLISH bumps the version, rewrites the README
+# line in its own commit and then dispatches this workflow, so the push
+# run is skipped there. Two workflows committing to the same README line
+# at the same time is what made releases fail on a rebase conflict.
+#
+# Push conflicts: if the README on {{MAIN_BRANCH}} moved in the meantime
+# (a release commit rewrote the same line), a run that shows the same
+# version, or whose version is already stale, is skipped instead of failing.
+#
 # The version line under the AUTO-VERSION-SECTION marker is already
 # rewritten inside the release commit itself (version_manager.py
 # increment/set), so the release tag snapshot shows the released
@@ -83,25 +92,48 @@ jobs:
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
 
+      - 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")
+          # A push in trunk-based mode is a release: RELEASE-PUBLISH rewrites the
+          # README itself and dispatches this workflow afterwards. Running on the
+          # push too would race it on the same README line.
+          if [ "$MODE" = "trunk-based" ] && [ "${{ github.event_name }}" = "push" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "$(m wf_readme.trunk_skip)"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Check README.md exists
         id: precheck
+        if: steps.mode.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 README.md ]; then
             echo "readme_exists=true" >> $GITHUB_OUTPUT
           else
             echo "readme_exists=false" >> $GITHUB_OUTPUT
-            echo "README.md not found — nothing to update, skipping"
+            echo "$(m wf_readme.not_found)"
           fi
 
       - name: Read latest version via version_manager.py
         id: version_info
         if: steps.precheck.outputs.readme_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 "$@"; }
           LATEST_VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
           # Guard: an empty version must never reach the README rewrite —
           # it would commit a corrupted "v (date)" line.
           if [ -z "$LATEST_VERSION" ]; then
-            echo "failed to read the current version"
+            echo "$(m wf_readme.read_version_failed)"
             exit 1
           fi
           RELEASE_DATE=$(date '+%Y-%m-%d')
@@ -112,6 +144,7 @@ jobs:
       - name: Update version line in README.md
         if: steps.precheck.outputs.readme_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 "$@"; }
           LATEST_VERSION="${{ steps.version_info.outputs.latest_version }}"
           RELEASE_DATE="${{ steps.version_info.outputs.release_date }}"
@@ -130,28 +163,28 @@ jobs:
             local version_text="$4"
 
             echo ""
-            echo "README.md version update failed"
-            echo "  error type: $error_type"
-            echo "  current version line: $version_line"
-            echo "  extracted header: $header_part"
-            echo "  new version text: $version_text"
+            echo "$(m wf_readme.update_failed)"
+            echo "$(m wf_readme.err_type error_type="$error_type")"
+            echo "$(m wf_readme.err_current_line version_line="$version_line")"
+            echo "$(m wf_readme.err_header header_part="$header_part")"
+            echo "$(m wf_readme.err_new_text version_text="$version_text")"
             echo ""
-            echo "Make sure the README version line matches one of:"
+            echo "$(m wf_readme.hint_formats)"
             echo "  $(m wf_readme.hint_first_example)"
             echo "  ## Current Version : v1.0.0"
             echo "  ## Version : v1.0.0"
-            echo "Notes:"
-            echo "  - no markdown bold (**) characters"
-            echo "  - no regex special characters (*, [, ], ^, $)"
-            echo "  - the version must come right after the colon (:)"
+            echo "$(m wf_readme.hint_notes)"
+            echo "$(m wf_readme.hint_no_bold)"
+            echo "$(m wf_readme.hint_no_regex)"
+            echo "$(m wf_readme.hint_after_colon)"
           }
 
           if [ "$SHOW_DATE" = "true" ]; then
             VERSION_TEXT="v${LATEST_VERSION} (${RELEASE_DATE})"
-            echo "version text with date: $VERSION_TEXT"
+            echo "$(m wf_readme.text_with_date version_text="$VERSION_TEXT")"
           else
             VERSION_TEXT="v${LATEST_VERSION}"
-            echo "version text: $VERSION_TEXT"
+            echo "$(m wf_readme.text version_text="$VERSION_TEXT")"
           fi
 
           # Patterns for recognized version lines (case-insensitive, flexible spacing)
@@ -172,14 +205,14 @@ jobs:
             if grep -qi "$pattern" README.md; then
               VERSION_LINE=$(grep -i "$pattern" README.md | head -n 1)
               PATTERN_FOUND="$pattern"
-              echo "version line found: $VERSION_LINE"
+              echo "$(m wf_readme.line_found version_line="$VERSION_LINE")"
               break
             fi
           done
 
           # No version line yet — insert a default one
           if [ -z "$VERSION_LINE" ]; then
-            echo "no version line found — inserting a new one"
+            echo "$(m wf_readme.line_inserting)"
             # Heading wording follows the configured language; an existing line keeps its own wording
             DEFAULT_HEADING=$(m wf_readme.default_heading)
 
@@ -190,16 +223,16 @@ jobs:
               # at the very top of the file
               sed -i '1i\<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->\n## '"$DEFAULT_HEADING"' : '"$VERSION_TEXT"'\n' README.md
             fi
-            echo "default version line inserted: $VERSION_TEXT"
+            echo "$(m wf_readme.line_inserted version_text="$VERSION_TEXT")"
           else
             # Update the existing version line
 
             # Validate the line format
             if [[ "$VERSION_LINE" =~ \*\* ]]; then
               echo ""
-              echo "warning: the version line contains markdown bold (**) characters"
-              echo "  current line: $VERSION_LINE"
-              echo "  this may break the version update"
+              echo "$(m wf_readme.warn_bold)"
+              echo "$(m wf_readme.warn_current_line version_line="$VERSION_LINE")"
+              echo "$(m wf_readme.warn_may_break)"
               echo ""
             fi
 
@@ -211,12 +244,12 @@ jobs:
               PREV_LINE=$(sed -n "${PREV_LINE_NUMBER}p" README.md)
               if [[ "$PREV_LINE" != *"AUTO-VERSION-SECTION"* ]]; then
                 sed -i "${PREV_LINE_NUMBER}a\\<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->" README.md
-                echo "auto-update marker comment added"
+                echo "$(m wf_readme.marker_added)"
                 LINE_NUMBER=$((LINE_NUMBER + 1))
               fi
             else
               sed -i '1i\<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->' README.md
-              echo "auto-update marker comment added"
+              echo "$(m wf_readme.marker_added)"
               LINE_NUMBER=$((LINE_NUMBER + 1))
             fi
 
@@ -224,7 +257,7 @@ jobs:
             HEADER_PART=$(printf '%s\n' "$VERSION_LINE" | sed 's/\(.*:\).*/\1 /')
 
             if [ -z "$HEADER_PART" ] || [[ "$HEADER_PART" == "$VERSION_LINE" ]]; then
-              print_error_message "header extraction failed - no colon (:) found" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
+              print_error_message "$(m wf_readme.err_no_colon)" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
               exit 1
             fi
 
@@ -237,62 +270,81 @@ jobs:
             ESCAPED_LINE=$(printf '%s' "$NEW_LINE" | sed 's/[&\\|]/\\&/g')
 
             if ! sed -i "${LINE_NUMBER}s|.*|${ESCAPED_LINE}|" README.md 2>/tmp/sed_error.log; then
-              SED_ERROR=$(cat /tmp/sed_error.log 2>/dev/null || echo "unknown sed error")
-              print_error_message "sed command failed - $SED_ERROR" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
+              SED_ERROR=$(cat /tmp/sed_error.log 2>/dev/null || m wf_readme.err_sed_unknown)
+              print_error_message "$(m wf_readme.err_sed error="$SED_ERROR")" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
               exit 1
             fi
 
             # Verify the replacement
             UPDATED_LINE=$(sed -n "${LINE_NUMBER}p" README.md)
             if [[ "$UPDATED_LINE" != *"$VERSION_TEXT"* ]]; then
-              print_error_message "version replacement verification failed" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
-              echo "  updated line: $UPDATED_LINE"
+              print_error_message "$(m wf_readme.err_verify)" "$VERSION_LINE" "$HEADER_PART" "$VERSION_TEXT"
+              echo "$(m wf_readme.updated_line_detail updated_line="$UPDATED_LINE")"
               exit 1
             fi
 
-            echo "version line updated: $VERSION_TEXT"
+            echo "$(m wf_readme.line_updated version_text="$VERSION_TEXT")"
           fi
 
       - name: Commit and push changes
         if: steps.precheck.outputs.readme_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 "$@"; }
           git add README.md
 
           if git diff --staged --quiet; then
-            echo "no changes in README.md"
+            echo "$(m wf_readme.no_changes)"
           else
             VERSION="${{ steps.version_info.outputs.latest_version }}"
 
             git commit -m "docs(readme): update version to v$VERSION [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
+            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 "README.md version update pushed"
+                echo "$(m wf_readme.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
               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
+              git rebase --abort 2>/dev/null || true
+
+              # The same README line was rewritten on the remote (a release commit).
+              # Nothing is lost when it already shows this version or is ahead of it.
+              REMOTE_VERSION=$(git show origin/{{MAIN_BRANCH}}:version.yml | grep -m1 '^version:' | sed 's/version:[ \t]*"\{0,1\}\([0-9][0-9.]*\)"\{0,1\}.*/\1/')
+              if [ -n "$REMOTE_VERSION" ] && [ "$REMOTE_VERSION" != "$VERSION" ]; then
+                echo "$(m wf_readme.conflict_skip_stale version="$VERSION" remote_version="$REMOTE_VERSION")"
+                PUSH_SUCCESS=true
+                break
+              fi
+              if git show origin/{{MAIN_BRANCH}}:README.md | grep -qF "v${VERSION}"; then
+                echo "$(m wf_readme.conflict_skip_same version="$VERSION")"
+                PUSH_SUCCESS=true
+                break
+              fi
+
+              echo "$(m wf_common.rebase_failed)"
+              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