project-auto-wizard 0.15.0 → 0.16.0

package/payload/scripts/version_manager.py

@@ -95,16 +95,33 @@ def read_file(path):
 
 def write_file(path, text):
     """Write text preserving the dominant line ending of the existing file
-    on disk (LF stays LF, CRLF stays CRLF — never platform-dependent)."""
+    on disk (LF stays LF, CRLF stays CRLF — never platform-dependent).
+    Returns False (and leaves the file untouched) when the content is already identical."""
     p = Path(path)
     eol = "\n"
+    previous = None
     if p.is_file():
         with open(p, "r", encoding="utf-8", newline="") as f:
-            eol = _detect_eol(f.read())
+            previous = f.read()
+        eol = _detect_eol(previous)
     if eol != "\n":
         text = text.replace("\n", eol)
+    if previous == text:
+        return False
     with open(p, "w", encoding="utf-8", newline="") as f:
         f.write(text)
+    return True
+
+
+# Files whose content actually changed in this process. Lets the sync check tell "reconciled" from "already in sync".
+_CHANGED_FILES = []
+
+
+def write_synced(path, text):
+    """write_file() for version files: logs `updated:` only when the content really changed."""
+    if write_file(path, text):
+        _CHANGED_FILES.append(str(path))
+        log(t("version_manager.updated", path=path))
 
 
 # ===================================================================
@@ -176,6 +193,21 @@ def get_current_version():
     return read_scalar_key("version", "0.0.0")
 
 
+# Names that used to be separate types. A version.yml written before the merge may still carry them,
+# and the release workflow can run before the wizard rewrites that file, so they are read as the new name.
+TYPE_ALIASES = {"next": "react"}
+
+
+def _canonical_types(types):
+    """Map aliased type names to their current name, dropping duplicates while keeping order."""
+    out = []
+    for t in types:
+        t = TYPE_ALIASES.get(t, t)
+        if t not in out:
+            out.append(t)
+    return out
+
+
 def get_project_types_csv():
     """Return project_types as a list. Supports both:
       project_types: ["a", "b"]
@@ -196,7 +228,7 @@ def get_project_types_csv():
         inner = m.group(1)
         items = re.findall(r'"([^"]*)"|\'([^\']*)\'', inner)
         types = [a or b for a, b in items]
-        return [t for t in types if t]
+        return _canonical_types([t for t in types if t])
 
     # Block list form:
     # project_types:
@@ -207,7 +239,7 @@ def get_project_types_csv():
         block = m.group(1)
         # trailing comments are allowed on list items too
         types = re.findall(r'-[ \t]*["\']?([^"\'#\n]+?)["\']?[ \t]*(?:#.*)?$', block, re.MULTILINE)
-        return [t.strip() for t in types if t.strip()]
+        return _canonical_types([t.strip() for t in types if t.strip()])
 
     return []
 
@@ -221,16 +253,19 @@ def get_type_path(project_type, project_types_list=None):
     if not m:
         return "."
     block = m.group(1)
-    km = re.search(
-        r'^[ \t]+["\']?' + re.escape(project_type)
-        + r'["\']?:[ \t]*["\']?([^"\'#\n]+?)["\']?[ \t]*(?:#.*)?$',
-        block,
-        re.MULTILINE,
-    )
-    if km:
-        val = km.group(1).strip()
-        if val and val != "null":
-            return val
+    # The current name first, then any older name that maps to it (e.g. next -> react).
+    names = [project_type] + [old for old, new in TYPE_ALIASES.items() if new == project_type]
+    for name in names:
+        km = re.search(
+            r'^[ \t]+["\']?' + re.escape(name)
+            + r'["\']?:[ \t]*["\']?([^"\'#\n]+?)["\']?[ \t]*(?:#.*)?$',
+            block,
+            re.MULTILINE,
+        )
+        if km:
+            val = km.group(1).strip()
+            if val and val != "null":
+                return val
     return "."
 
 
@@ -419,8 +454,7 @@ def sync_maven(path_dir, new_version):
         return True
     new_full = _keep_snapshot(old_version, new_version)
     new_text, _ = _pom_replace(text, ["version"], new_full)
-    write_file(root_pom, new_text)
-    log(t("version_manager.updated", path=root_pom))
+    write_synced(root_pom, new_text)
 
     root_artifact = _pom_text(text, ["artifactId"])
     for child in sorted(Path(path_dir).glob("*/pom.xml")):
@@ -432,8 +466,7 @@ def sync_maven(path_dir, new_version):
         ctext, _ = _pom_replace(ctext, ["parent", "version"], new_full)
         if _pom_text(ctext, ["version"]) == old_version:
             ctext, _ = _pom_replace(ctext, ["version"], new_full)
-        write_file(child, ctext)
-        log(t("version_manager.updated", path=child))
+        write_synced(child, ctext)
     return True
 
 
@@ -524,8 +557,7 @@ def sync_spring(path_dir, new_version):
         if not matches:
             log(t("version_manager.warn_spring_no_gradle_line", file=gradle_file))
             continue
-        write_file(gradle_file, new_text)
-        log(t("version_manager.updated", path=gradle_file))
+        write_synced(gradle_file, new_text)
 
 
 def _pubspec_build_number(path_dir):
@@ -566,8 +598,7 @@ def sync_flutter(path_dir, new_version, version_code):
         new_text = pattern.sub(r'\1 ' + full_version, text, count=1)
     else:
         new_text = text.rstrip("\n") + f"\nversion: {full_version}\n"
-    write_file(target, new_text)
-    log(t("version_manager.updated", path=target))
+    write_synced(target, new_text)
 
 
 def _json_indent(text):
@@ -594,8 +625,7 @@ def sync_json_version(target, new_version, key_path):
     for k in key_path[:-1]:
         node = node.setdefault(k, {})
     node[key_path[-1]] = new_version
-    write_file(target, json.dumps(data, indent=_json_indent(raw), ensure_ascii=False) + "\n")
-    log(t("version_manager.updated", path=target))
+    write_synced(target, json.dumps(data, indent=_json_indent(raw), ensure_ascii=False) + "\n")
 
 
 _TOML_HEADER_RE = re.compile(r'^[ \t]*\[+[ \t]*([^\]\n]+?)[ \t]*\]+[ \t]*(?:#.*)?$', re.MULTILINE)
@@ -645,8 +675,7 @@ def sync_python(path_dir, new_version):
         return
     for target, (start, end) in spans:
         text = read_file(target)
-        write_file(target, text[:start] + new_version + text[end:])
-        log(t("version_manager.updated", path=target))
+        write_synced(target, text[:start] + new_version + text[end:])
 
 
 _PLIST_VERSION_RE = re.compile(r'(<key>CFBundleShortVersionString</key>\s*<string>)([^<]*)(</string>)')
@@ -676,8 +705,7 @@ def sync_react_native(path_dir, new_version):
                 log(t("version_manager.skipped_plist", file=plist_file))
                 continue
             new_text = _PLIST_VERSION_RE.sub(lambda mm: mm.group(1) + new_version + mm.group(3), text)
-            write_file(plist_file, new_text)
-            log(t("version_manager.updated", path=plist_file))
+            write_synced(plist_file, new_text)
             found_plist = True
     else:
         log(t("version_manager.warn_rn_ios_missing", dir=ios_dir))
@@ -686,8 +714,7 @@ def sync_react_native(path_dir, new_version):
     if gradle_file.is_file():
         text = read_file(gradle_file)
         new_text = re.sub(r'versionName\s+"[^"]*"', f'versionName "{new_version}"', text)
-        write_file(gradle_file, new_text)
-        log(t("version_manager.updated", path=gradle_file))
+        write_synced(gradle_file, new_text)
     else:
         log(t("version_manager.warn_rn_gradle_missing", file=gradle_file))
 
@@ -859,7 +886,6 @@ TYPE_HANDLERS = {
     # Only types that need a build number compute version_code (this has a pubspec-adjusting side effect).
     "flutter": TypeHandler(read=_read_flutter, sync=lambda d, v, code: sync_flutter(d, v, code())),
     "react": _PACKAGE_JSON,
-    "next": _PACKAGE_JSON,
     "node": _PACKAGE_JSON,
     "python": TypeHandler(read=_read_python, sync=lambda d, v, _code: sync_python(d, v)),
     "react-native": TypeHandler(read=_read_react_native, sync=lambda d, v, _code: sync_react_native(d, v)),
@@ -896,11 +922,12 @@ def sync_versions():
     primary_type = types[0]
     project_version = get_project_file_version(primary_type)
 
-    log(t("version_manager.sync_check"))
-    log(t("version_manager.sync_yml_version", version=yml_version))
-    log(t("version_manager.sync_project_version", version=project_version))
-
     if yml_version != project_version:
+        # The detail lines are only useful when the two disagree; an in-sync check prints a single line
+        # (this check runs several times per job, so a multi-line block each time is just noise).
+        log(t("version_manager.sync_check"))
+        log(t("version_manager.sync_yml_version", version=yml_version))
+        log(t("version_manager.sync_project_version", version=project_version))
         if validate_version(yml_version) and validate_version(project_version):
             higher = get_higher_version(yml_version, project_version)
             log(t("version_manager.sync_mismatch", version=higher))
@@ -913,11 +940,13 @@ def sync_versions():
             log(t("version_manager.warn_format_invalid"))
             return yml_version
     else:
-        types = get_project_types_csv()
-        if types:
-            log(t("version_manager.sync_multi", version=yml_version))
-            sync_all_project_files(yml_version)
-        log(t("version_manager.sync_ok", version=yml_version))
+        # The primary type matches, but the other types' files may still lag behind; reconcile them quietly.
+        changed_before = len(_CHANGED_FILES)
+        sync_all_project_files(yml_version)
+        if len(_CHANGED_FILES) > changed_before:
+            log(t("version_manager.sync_reconciled", version=yml_version))
+        else:
+            log(t("version_manager.sync_ok", version=yml_version))
         return yml_version
 
 

package/payload/version.yml.template

@@ -9,8 +9,11 @@
 # - copilot_ai: opt-in (default false) — true lets the release/PR summary
 #   workflows call GitHub Copilot CLI, which consumes GitHub Copilot AI Credits.
 #   Falls back to rule-based summaries whenever Copilot is off or unavailable.
+# - release_automerge: default true — false stops the release PR (develop -> main)
+#   from being merged automatically. Merge it yourself with a merge commit
+#   (not squash or rebase); the workflow renames the PR so the release still publishes.
 # ===
-# Supported project types: spring, flutter, next, react, react-native,
+# Supported project types: spring, flutter, react, react-native,
 #                          react-native-expo, node, python, basic, go
 # Multi-type projects: list every type in the project_types array
 #   -> the first entry is the primary type (project_types is the single source of truth)
@@ -20,7 +23,7 @@
 # Synced files per type:
 # - spring: build.gradle / build.gradle.kts / pom.xml
 # - flutter: pubspec.yaml
-# - next/react/node: package.json
+# - react/node: package.json
 # - react-native: Info.plist + build.gradle
 # - react-native-expo: app.json
 # - python: pyproject.toml / setup.py
@@ -53,6 +56,7 @@ metadata:
     options:
       semver_auto: {{OPT_SEMVER_AUTO}}
       copilot_ai: {{OPT_COPILOT_AI}}
+      release_automerge: {{OPT_RELEASE_AUTOMERGE}}
       deploy_style: "{{OPT_DEPLOY_STYLE}}" # simple | nginx | traefik | none (server deploy workflows)
 {{TYPE_OPTIONS}}
 {{DEPLOY}}

package/payload/workflows/common/PROJECT-COMMON-AI-PR-SUMMARY.yaml

@@ -53,6 +53,7 @@ jobs:
       - 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
@@ -75,6 +76,7 @@ jobs:
           COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
           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 }}
 
@@ -154,6 +156,7 @@ jobs:
           # AUTO-CHANGELOG-CONTROL).
           HEAD_REF: ${{ github.event.pull_request.head.ref }}
         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 "$@"; }
           ISSUE_NUM=$(python3 .github/scripts/issue_helper.py extract-branch-issue "$HEAD_REF")
 

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

@@ -29,6 +29,10 @@
 #    direct merge), retrying with backoff while GitHub catches up with the
 #    freshly pushed head; an already-merged PR counts as success
 #
+# With version.yml release_automerge: false, step 5 and the wait job are
+# skipped: the PR is renamed to the release-confirm subject and one guidance
+# comment asks the maintainer to merge it with a merge commit (not squash or rebase).
+#
 # The merge-commit subject carries the release-confirm pattern
 # "chore(release):" — keep in sync with PROJECT-COMMON-VERSION-CONTROL
 # and PROJECT-COMMON-RELEASE-PUBLISH.
@@ -105,6 +109,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 }}
           # A push to {{DEVELOP_BRANCH}} mid-pipeline queues a run that later reprocesses the
@@ -126,6 +131,9 @@ jobs:
     needs: precheck
     if: needs.precheck.outputs.open == 'true'
     runs-on: ubuntu-latest
+    outputs:
+      # Read by wait-for-merge-and-trigger-release: with automerge off there is no merge for it to wait for
+      automerge: ${{ steps.automerge_option.outputs.release_automerge }}
     steps:
       - name: Checkout PR head
         uses: actions/checkout@v7
@@ -142,6 +150,7 @@ 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
@@ -150,6 +159,7 @@ jobs:
       - 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
@@ -157,6 +167,15 @@ jobs:
           echo "copilot_ai=$COPILOT_AI" >> $GITHUB_OUTPUT
           echo "$(m wf_common.copilot_ai_option copilot_ai="$COPILOT_AI")"
 
+      - name: Read release_automerge option from version.yml
+        id: automerge_option
+        run: |
+          # Same metadata: -> template: -> options: scope as copilot_ai. A missing key means ON:
+          # installs from before the option existed already automerge, and that must not change.
+          AUTOMERGE=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?^\s+release_automerge:\s*\"?(true|false)", t, re.S|re.M); print(m.group(1) if m else "true")' 2>/dev/null || echo "true")
+          echo "release_automerge=$AUTOMERGE" >> $GITHUB_OUTPUT
+          echo "release_automerge option: $AUTOMERGE"
+
       - name: Install Copilot CLI
         if: steps.copilot_options.outputs.copilot_ai == 'true'
         continue-on-error: true
@@ -165,6 +184,7 @@ 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
@@ -187,6 +207,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
 
@@ -225,6 +246,7 @@ 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
@@ -284,6 +306,7 @@ 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)
 
@@ -312,6 +335,7 @@ 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
@@ -361,9 +385,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: |
+          [ -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="${{ github.event.pull_request.head.ref }}"
+          HEAD_BRANCH="$PAW_HEAD_REF"
           VERSION="${{ steps.bump.outputs.new_version }}"
 
           # Working files must not land in the repo
@@ -420,12 +447,44 @@ jobs:
             fi
           fi
 
+      - name: Prepare manual release merge (release_automerge=false)
+        if: steps.automerge_option.outputs.release_automerge == 'false'
+        env:
+          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 }}"
+
+          # The PR title carries the release-confirm pattern, so a human merge commit (its message includes the PR title)
+          # still passes the RELEASE-PUBLISH gate. A failed rename only warns: the run must not fail here.
+          SUBJECT="chore(release): v${VERSION} (PR #${PR_NUMBER})"
+          if gh pr edit "$PR_NUMBER" --title "$SUBJECT"; then
+            echo "$(m wf_changelog.automerge_off subject="$SUBJECT")"
+          else
+            echo "::warning::$(m wf_changelog.automerge_rename_failed pr_number="$PR_NUMBER")"
+          fi
+
+          # One guidance comment per PR: re-runs (synchronize) find it by its marker and leave it alone.
+          MARKER='<!-- release-automerge-off -->'
+          EXISTING=$(gh api --paginate "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
+            --jq ".[] | select(.body | contains(\"$MARKER\")) | .id" 2>/dev/null | head -1 || true)
+          if [ -z "$EXISTING" ]; then
+            BODY="$MARKER
+          $(m wf_changelog.automerge_off_comment)"
+            gh pr comment "$PR_NUMBER" --body "$BODY" \
+              || echo "::warning::$(m wf_changelog.automerge_rename_failed pr_number="$PR_NUMBER")"
+          fi
+
       - name: Enable automerge
+        if: steps.automerge_option.outputs.release_automerge != 'false'
         env:
           # With a PAT the merge push triggers downstream workflows
           # (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 }}"
@@ -491,6 +550,8 @@ jobs:
   wait-for-merge-and-trigger-release:
     name: Wait for merge and trigger RELEASE-PUBLISH (works without WORKFLOW_PAT)
     needs: changelog-and-merge
+    # Nothing merges by itself when release_automerge is false, so there is nothing to wait for.
+    if: needs.changelog-and-merge.outputs.automerge != 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 35
     permissions:
@@ -514,6 +575,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
@@ -545,6 +607,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,9 +92,29 @@ 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
@@ -98,6 +127,7 @@ jobs:
         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 —
@@ -114,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 }}"
@@ -258,6 +289,7 @@ jobs:
       - 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
 
@@ -268,8 +300,9 @@ jobs:
 
             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
 
@@ -281,21 +314,37 @@ jobs:
                 PUSH_SUCCESS=true
                 echo "$(m wf_readme.pushed)"
                 break
-              else
-                echo "$(m wf_common.push_failed_syncing)"
-
-                if git pull --rebase origin {{MAIN_BRANCH}}; then
-                  echo "$(m wf_common.rebase_ok)"
-                else
-                  echo "$(m wf_common.rebase_failed)"
-                  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 "$(m wf_common.push_gave_up max_retries="$MAX_RETRIES")"
               exit 1
             fi
+            # <<< push-with-retry
           fi