project-auto-wizard 0.1.5

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

@@ -0,0 +1,303 @@
+# ===================================================================
+# PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml
+# Release PR pipeline: version confirm + AI changelog + automerge
+# ===================================================================
+#
+# Runs on release PRs ({{DEVELOP_BRANCH}} -> {{MAIN_BRANCH}}) and:
+# 1. Confirms the release version (patch +1 and sync of every version file)
+# 2. Acquires a release summary:
+#    - If version.yml metadata.template.options.coderabbit is true:
+#      requests a CodeRabbit summary comment once and polls the PR body
+#      (30s x 10 polls = 5 minutes max)
+#    - Otherwise (or on poll timeout): generates the summary locally with
+#      changelog_manager.py ai-summary (engine chain: user API key ->
+#      GitHub Models -> rule-based fallback; always succeeds)
+# 3. Updates CHANGELOG.json / CHANGELOG.md and commits to the PR head
+#    branch with [skip ci]
+# 4. Enables automerge (gh pr merge --auto --merge)
+#
+# The merge-commit subject carries the release-confirm pattern
+# "chore(release):" — keep in sync with PROJECT-COMMON-VERSION-CONTROL
+# and PROJECT-COMMON-RELEASE-PUBLISH.
+#
+# Optional secrets/vars:
+# - secrets.WORKFLOW_PAT: PAT used for the merge. Without it the merge is
+#   performed with GITHUB_TOKEN, and GitHub will NOT trigger downstream
+#   {{MAIN_BRANCH}}-push workflows (e.g. RELEASE-PUBLISH) for that merge.
+# - secrets.AI_API_KEY (+ vars.AI_API_BASE_URL / vars.AI_MODEL): preferred
+#   summary engine. Falls back to GitHub Models, then to rule-based.
+# ===================================================================
+
+name: PROJECT-AUTO-CHANGELOG-CONTROL
+
+concurrency:
+  group: auto-changelog-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: false
+
+# No workflow_dispatch: this pipeline needs a live PR context and would be
+# a dead lever without one. The manual recovery path is
+# PROJECT-RELEASE-PUBLISH's workflow_dispatch.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: ["{{MAIN_BRANCH}}"]
+
+permissions:
+  contents: write
+  pull-requests: write
+  models: read
+
+jobs:
+  changelog-and-merge:
+    name: Version confirm + changelog + automerge
+    # Guard: only release PRs whose head is the develop branch of THIS
+    # repository enter the pipeline (protects against accidental feature
+    # PRs opened against production and against fork PRs with a spoofed
+    # "develop" head ref).
+    if: >-
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.event.pull_request.head.ref == '{{DEVELOP_BRANCH}}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR head
+        uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: Git config
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Read coderabbit option from version.yml
+        id: options
+        run: |
+          # scoped to the metadata: -> template: -> options: chain so an
+          # unrelated "coderabbit:" key can never hijack the value
+          CODERABBIT=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?coderabbit:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
+          echo "coderabbit=$CODERABBIT" >> $GITHUB_OUTPUT
+          echo "coderabbit option: $CODERABBIT"
+
+      - name: Request CodeRabbit summary (PR-body-init protection)
+        id: coderabbit_request
+        if: steps.options.outputs.coderabbit == 'true'
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+
+          # The PR body can lag right after open (API replication) —
+          # retry the read up to 3 times before deciding.
+          CURRENT_BODY=""
+          for attempt in 1 2 3; do
+            CURRENT_BODY=$(curl -s -H "Authorization: token ${{ github.token }}" \
+                                "https://api.github.com/repos/${{ github.repository }}/pulls/${PR_NUMBER}" | \
+                                jq -r '.body // ""')
+            if [ -n "$CURRENT_BODY" ] && [ "$CURRENT_BODY" != "null" ]; then
+              echo "[try $attempt] body length=$(printf '%s' "$CURRENT_BODY" | wc -c)"
+              break
+            fi
+            echo "[try $attempt] body empty — possible replication lag, retrying"
+            sleep 2
+          done
+
+          if printf '%s\n' "$CURRENT_BODY" | grep -q "Summary by CodeRabbit"; then
+            # Protection: a summary already exists — never wipe it, never re-request
+            echo "Summary by CodeRabbit already present — skipping request"
+            echo "already_found=true" >> $GITHUB_OUTPUT
+          else
+            echo "already_found=false" >> $GITHUB_OUTPUT
+            echo "requesting CodeRabbit summary on PR #$PR_NUMBER"
+            curl -s -H "Authorization: token ${{ github.token }}" \
+                 -H "Content-Type: application/json" \
+                 -X POST \
+                 -d '{"body": "@coderabbitai summary"}' \
+                 "https://api.github.com/repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" > /dev/null
+            echo "CodeRabbit summary requested"
+          fi
+
+      - name: Poll PR body for CodeRabbit summary (30s x 10 polls = 5 minutes max)
+        id: poll
+        if: steps.options.outputs.coderabbit == 'true'
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+
+          if [ "${{ steps.coderabbit_request.outputs.already_found }}" = "true" ]; then
+            echo "summary already present — skipping poll"
+            curl -s -H "Authorization: token ${{ github.token }}" \
+                 "https://api.github.com/repos/${{ github.repository }}/pulls/${PR_NUMBER}" | \
+                 jq -r '.body // ""' > pr_body.md
+            echo "summary_found=true" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          MAX_POLLS=10
+          POLL_INTERVAL=30
+          FOUND=false
+
+          for i in $(seq 1 $MAX_POLLS); do
+            echo "[$i/$MAX_POLLS] checking PR body... ($(date '+%H:%M:%S'))"
+
+            PR_BODY=$(curl -s -H "Authorization: token ${{ github.token }}" \
+                           "https://api.github.com/repos/${{ github.repository }}/pulls/${PR_NUMBER}" | \
+                           jq -r '.body // ""')
+
+            if [ -n "$PR_BODY" ] && [ "$PR_BODY" != "null" ] && printf '%s\n' "$PR_BODY" | grep -q "Summary by CodeRabbit"; then
+              echo "CodeRabbit summary found"
+              printf '%s\n' "$PR_BODY" > pr_body.md
+              FOUND=true
+              break
+            fi
+
+            if [ "$i" -lt "$MAX_POLLS" ]; then
+              sleep $POLL_INTERVAL
+            fi
+          done
+
+          if [ "$FOUND" = "true" ]; then
+            echo "summary_found=true" >> $GITHUB_OUTPUT
+          else
+            echo "no CodeRabbit summary after 5 minutes — falling back to ai-summary"
+            echo "summary_found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Confirm release version (patch +1 and sync)
+        id: bump
+        run: |
+          # Idempotency: if the PR head is already this workflow's own
+          # version-confirm commit (re-run / synchronize retrigger), do not
+          # bump a second time — reuse the confirmed version.
+          HEAD_MSG=$(git log -1 --pretty=%s)
+          if printf '%s\n' "$HEAD_MSG" | grep -q "^chore(version): confirm v.* \[skip ci\]"; then
+            NEW_VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
+            echo "version already confirmed by a previous run — reusing $NEW_VERSION (no re-increment)"
+          else
+            NEW_VERSION=$(python3 .github/scripts/version_manager.py increment | tail -n 1)
+            if [ -z "$NEW_VERSION" ]; then
+              echo "version bump failed"
+              exit 1
+            fi
+            python3 .github/scripts/version_manager.py sync
+            echo "release version confirmed: $NEW_VERSION"
+          fi
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Generate summary with the AI engine chain (fallback path)
+        if: steps.options.outputs.coderabbit != 'true' || steps.poll.outputs.summary_found != 'true'
+        env:
+          # PR title goes through the env block — never inline-interpolate
+          # untrusted text into the shell string (quote injection).
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          AI_API_KEY: ${{ secrets.AI_API_KEY }}
+          AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
+          AI_MODEL: ${{ vars.AI_MODEL }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
+
+          git fetch origin {{MAIN_BRANCH}}
+          git log --pretty=%s "origin/{{MAIN_BRANCH}}..HEAD" > commits.txt
+          echo "commits to summarize: $(wc -l < commits.txt)"
+
+          python3 .github/scripts/changelog_manager.py ai-summary \
+            --commits-file commits.txt \
+            --version "$VERSION" \
+            --output summary.md \
+            --pr-title "$PR_TITLE"
+
+          # Feed the generated summary through the same channel the
+          # CodeRabbit path uses: update-from-summary reads ./pr_body.md
+          cp summary.md pr_body.md
+
+      - name: Update CHANGELOG from summary
+        run: |
+          # note: `grep | sed || echo default` never fires the default (the
+          # pipeline exits with sed's 0) — default via ${var:-} instead
+          PROJECT_TYPE=$(grep "^project_type:" version.yml 2>/dev/null | sed 's/project_type: *"\([^"]*\)".*/\1/')
+          PROJECT_TYPE=${PROJECT_TYPE:-unknown}
+          PROJECT_TYPES=$(grep "^project_types:" version.yml 2>/dev/null | sed -E 's/.*\[([^]]*)\].*/\1/' | tr -d '" ')
+          PROJECT_TYPES=${PROJECT_TYPES:-$PROJECT_TYPE}
+
+          export VERSION="${{ steps.bump.outputs.new_version }}"
+          export PROJECT_TYPE PROJECT_TYPES
+          export TODAY=$(date '+%Y-%m-%d')
+          export PR_NUMBER="${{ github.event.pull_request.number }}"
+          export TIMESTAMP=$(date '+%Y-%m-%dT%H:%M:%SZ')
+
+          python3 .github/scripts/changelog_manager.py update-from-summary
+          python3 .github/scripts/changelog_manager.py generate-md
+
+      - name: Commit release docs to the PR head branch
+        run: |
+          HEAD_BRANCH="${{ github.event.pull_request.head.ref }}"
+          VERSION="${{ steps.bump.outputs.new_version }}"
+
+          # Working files must not land in the repo
+          rm -f pr_body.md summary.md commits.txt
+
+          git add -A
+
+          if git diff --staged --quiet; then
+            echo "no changes to commit"
+          else
+            git commit -m "chore(version): confirm v${VERSION} and update release docs [skip ci]"
+
+            # Race-condition guard: pull-rebase then push (up to 3 retries)
+            MAX_RETRIES=3
+            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..."
+
+              if git push origin HEAD:$HEAD_BRANCH; then
+                PUSH_SUCCESS=true
+                echo "release docs pushed to $HEAD_BRANCH"
+                break
+              else
+                echo "push failed, syncing with remote..."
+                if git pull --rebase origin $HEAD_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
+            done
+
+            if [ "$PUSH_SUCCESS" = false ]; then
+              echo "push failed after $MAX_RETRIES attempts"
+              exit 1
+            fi
+          fi
+
+      - name: Enable automerge
+        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: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          VERSION="${{ steps.bump.outputs.new_version }}"
+
+          # Merge-commit subject carries the release-confirm pattern —
+          # VERSION-CONTROL skips on it and RELEASE-PUBLISH proceeds on it.
+          SUBJECT="chore(release): v${VERSION} (PR #${PR_NUMBER})"
+
+          if gh pr merge "$PR_NUMBER" --auto --merge --subject "$SUBJECT"; then
+            echo "automerge enabled: $SUBJECT"
+          elif gh pr merge "$PR_NUMBER" --merge --subject "$SUBJECT"; then
+            echo "automerge unavailable — merged directly: $SUBJECT"
+          else
+            # Both attempts failed — diagnose instead of pretending success.
+            ALLOW_MERGE_COMMIT=$(gh api "repos/${GITHUB_REPOSITORY}" --jq '.allow_merge_commit' 2>/dev/null || echo "unknown")
+            if [ "$ALLOW_MERGE_COMMIT" = "false" ]; then
+              echo "::error::이 레포는 merge commit이 비활성화되어 있습니다 — Settings에서 'Allow merge commits'를 켜세요; 릴리스 감지는 merge commit subject를 사용합니다"
+            else
+              echo "::error::PR merge failed (allow_merge_commit=$ALLOW_MERGE_COMMIT) — check branch protection rules, required checks, and token permissions"
+            fi
+            exit 1
+          fi

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

@@ -0,0 +1,293 @@
+# ===================================================================
+# PROJECT-COMMON-README-VERSION-UPDATE.yaml
+# Automatic README version update workflow
+# ===================================================================
+#
+# On every push to {{MAIN_BRANCH}} this workflow reads the latest version
+# via version_manager.py and rewrites the version section of README.md.
+#
+# ===================================================================
+# How it works:
+# 1. Triggered by a push to {{MAIN_BRANCH}}
+# 2. Reads the latest version via version_manager.py
+# 3. Updates the version line in README.md
+# 4. Commits and pushes the change ([skip ci])
+#
+# Supported version line formats (case-insensitive, flexible spacing):
+# - ## 최신 버전 : v1.0.0 (2025-08-15)
+# - ## 최신버전 : v1.0.0 (2025-08-15)
+# - ## Current Version : v1.0.0 (2025-08-15)
+# - ## Recent Version : v1.0.0 (2025-08-15)
+# - ## Latest Version : v1.0.0
+# - ## Version : v1.0.0
+# - ## 버전 : v1.0.0
+#
+# The marker comment <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
+# is added automatically above the version line.
+#
+# Unsupported formats (will fail):
+# - markdown bold (**) inside the version line
+# - missing colon
+# - regex special characters (*, [, ], ^, $) in the version line
+#
+# Environment variables:
+# - SHOW_DATE: whether to append the date (true/false, default: true)
+#   * true:  v1.0.0 (2025-08-16)
+#   * false: v1.0.0
+#
+# Note (safety-net path): on a direct push to {{MAIN_BRANCH}} this
+# workflow reads the pre-bump version — PROJECT-VERSION-CONTROL bumps
+# afterwards with a [skip ci] commit that does not re-trigger this
+# workflow, so the README stays one version behind until the next
+# release/push. Run this workflow manually (workflow_dispatch) to catch up.
+# ===================================================================
+
+name: README VERSION UPDATE
+
+env:
+  # Whether to show the date next to the version (true/false)
+  SHOW_DATE: true
+
+concurrency:
+  group: readme-version-update
+  cancel-in-progress: false
+
+on:
+  push:
+    branches: ["{{MAIN_BRANCH}}"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-readme:
+    name: Update README version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+          ref: "{{MAIN_BRANCH}}"
+
+      - name: Git config
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Check README.md exists
+        id: precheck
+        run: |
+          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"
+          fi
+
+      - name: Read latest version via version_manager.py
+        id: version_info
+        if: steps.precheck.outputs.readme_exists == 'true'
+        run: |
+          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"
+            exit 1
+          fi
+          RELEASE_DATE=$(date '+%Y-%m-%d')
+
+          echo "latest_version=$LATEST_VERSION" >> $GITHUB_OUTPUT
+          echo "release_date=$RELEASE_DATE" >> $GITHUB_OUTPUT
+
+      - name: Update version line in README.md
+        if: steps.precheck.outputs.readme_exists == 'true'
+        run: |
+          LATEST_VERSION="${{ steps.version_info.outputs.latest_version }}"
+          RELEASE_DATE="${{ steps.version_info.outputs.release_date }}"
+          SHOW_DATE="${{ env.SHOW_DATE }}"
+
+          # ---------------------------------------------------------
+          # Error message helper
+          # ---------------------------------------------------------
+          print_error_message() {
+            local error_type="$1"
+            local version_line="$2"
+            local header_part="$3"
+            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 ""
+            echo "Make sure the README version line matches one of:"
+            echo "  ## 최신 버전 : v1.0.0 (2025-08-15)"
+            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 (:)"
+          }
+
+          if [ "$SHOW_DATE" = "true" ]; then
+            VERSION_TEXT="v${LATEST_VERSION} (${RELEASE_DATE})"
+            echo "version text with date: $VERSION_TEXT"
+          else
+            VERSION_TEXT="v${LATEST_VERSION}"
+            echo "version text: $VERSION_TEXT"
+          fi
+
+          # Patterns for recognized version lines (case-insensitive, flexible spacing)
+          VERSION_PATTERNS=(
+            "^##[[:space:]]*최신[[:space:]]*버전[[:space:]]*:"
+            "^##[[:space:]]*최신버전[[:space:]]*:"
+            "^##[[:space:]]*[Cc]urrent[[:space:]]*[Vv]ersion[[:space:]]*:"
+            "^##[[:space:]]*[Rr]ecent[[:space:]]*[Vv]ersion[[:space:]]*:"
+            "^##[[:space:]]*[Vv]ersion[[:space:]]*:"
+            "^##[[:space:]]*버전[[:space:]]*:"
+            "^##[[:space:]]*[Ll]atest[[:space:]]*[Vv]ersion[[:space:]]*:"
+          )
+
+          VERSION_LINE=""
+          PATTERN_FOUND=""
+
+          for pattern in "${VERSION_PATTERNS[@]}"; do
+            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"
+              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"
+
+            if grep -q "^# " README.md; then
+              # right after the first title
+              sed -i '/^# /a\\n<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->\n## Latest Version : '"$VERSION_TEXT" README.md
+            else
+              # at the very top of the file
+              sed -i '1i\<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->\n## Latest Version : '"$VERSION_TEXT"'\n' README.md
+            fi
+            echo "default version line inserted: $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 ""
+            fi
+
+            # Make sure the AUTO-VERSION-SECTION marker sits above the line
+            LINE_NUMBER=$(grep -n -i "$PATTERN_FOUND" README.md | head -n 1 | cut -d: -f1)
+            PREV_LINE_NUMBER=$((LINE_NUMBER - 1))
+
+            if [ $PREV_LINE_NUMBER -gt 0 ]; then
+              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"
+                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"
+              LINE_NUMBER=$((LINE_NUMBER + 1))
+            fi
+
+            # ---------------------------------------------------------
+            # Extract the header part (up to the colon)
+            # ---------------------------------------------------------
+            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"
+              exit 1
+            fi
+
+            # ---------------------------------------------------------
+            # Replace by line number (avoids regex special-char issues)
+            # ---------------------------------------------------------
+            NEW_LINE="${HEADER_PART}${VERSION_TEXT}"
+
+            # Escape sed replacement metacharacters (backslash, & and the
+            # | delimiter) coming from README content so they cannot inject
+            # into the replacement expression
+            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"
+              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"
+              exit 1
+            fi
+
+            echo "version line updated: $VERSION_TEXT"
+          fi
+
+      - name: Commit and push changes
+        if: steps.precheck.outputs.readme_exists == 'true'
+        run: |
+          git add README.md
+
+          if git diff --staged --quiet; then
+            echo "no changes in README.md"
+          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
+            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..."
+
+              if git push origin HEAD:{{MAIN_BRANCH}}; then
+                PUSH_SUCCESS=true
+                echo "README.md version update 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
+            done
+
+            if [ "$PUSH_SUCCESS" = false ]; then
+              echo "push failed after $MAX_RETRIES attempts"
+              exit 1
+            fi
+          fi