project-auto-wizard 0.15.0 → 0.15.1

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

@@ -10,7 +10,7 @@
 #   workflows call GitHub Copilot CLI, which consumes GitHub Copilot AI Credits.
 #   Falls back to rule-based summaries whenever Copilot is off or unavailable.
 # ===
-# 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 +20,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

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

@@ -105,6 +105,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
@@ -142,6 +143,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 +152,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
@@ -165,6 +168,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 +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
 
@@ -225,6 +230,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 +290,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 +319,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 +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: |
+          [ -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
@@ -426,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 }}"
@@ -514,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
@@ -545,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,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

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,6 +101,7 @@ 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
@@ -104,6 +112,7 @@ jobs:
       - 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 }}"
@@ -167,6 +176,7 @@ 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
@@ -181,6 +191,7 @@ 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
@@ -209,6 +220,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: on a re-run of a failed job the checked-out HEAD may
           # already be this workflow's own docs commit — never bump twice.
@@ -297,8 +309,12 @@ jobs:
           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
 
@@ -310,22 +326,36 @@ jobs:
                 PUSH_SUCCESS=true
                 echo "$(m wf_release.docs_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
+
+              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 "$(m wf_common.push_gave_up max_retries="$MAX_RETRIES")"
               exit 1
             fi
+            # <<< push-with-retry
           fi
 
       - name: Resolve version + idempotency guard
@@ -334,6 +364,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 "$@"; }
           VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
           if [ -z "$VERSION" ]; then
@@ -365,6 +396,7 @@ jobs:
       - 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"
@@ -376,6 +408,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 "$@"; }
           VERSION="${{ steps.version.outputs.version }}"
 
@@ -415,6 +448,7 @@ 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
@@ -430,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)"
@@ -457,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,