ci: adopt release branch flow (release-start / release-retry / FF merge to main)

# ── git-warden policy guide ──
# Write the commit message in English
# AI co-author trailers will be removed before commit

Author: zcube

.github/workflows/release-publish.yml

@@ -161,3 +161,26 @@ jobs:
           fi
           git commit -m "chore: bump gitversion-rs to ${VERSION}"
           git push
+
+  merge-to-main:
+    name: Merge release into main
+    needs: [publish, crates-io, homebrew]
+    if: always() && needs.publish.result == 'success' && needs.crates-io.result == 'success' && (needs.homebrew.result == 'success' || needs.homebrew.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Fast-forward main to release
+        run: |
+          git fetch origin release
+          git merge --ff-only origin/release
+          git push origin main
+
+      - name: Delete release branch
+        run: git push origin --delete release

AGENTS.md

@@ -63,33 +63,33 @@ cargo clippy --all-targets -- -D warnings   # lint (keep zero warnings)
 ### Justfile commands
 
 ```bash
-just version        # show current FullSemVer (gitversion-rs)
-just check          # dry-run: see what cargo-release would do (patch)
-just check minor    # dry-run for a minor bump
-just bump           # bump patch: updates Cargo.toml, commits, tags, pushes (no crates.io publish)
-just bump minor     # bump minor
-just bump major     # bump major
-just publish        # publish to crates.io locally (manual fallback)
-just gh-publish     # trigger release-publish.yml: publish GitHub release + crates.io
-just gh-retag       # delete draft release/tag and re-tag HEAD to re-trigger CI
-                    # blocked if GitHub release is published or crates.io already has the version
+just version              # show current FullSemVer (gitversion-rs)
+just check                # dry-run: see what cargo-release would do (patch)
+just check minor          # dry-run for a minor bump
+just release-start        # create release branch from main, bump patch, commit, tag, push
+just release-start minor  # bump minor
+just release-start major  # bump major
+just publish              # publish to crates.io locally (manual fallback)
+just gh-publish           # trigger release-publish.yml: publish GitHub release + crates.io + FF merge release->main
+just release-retry        # reset a failed release: delete draft/tag/branch, recreate from latest main
+                          # blocked if GitHub release is published or crates.io already has the version
 ```
 
 ### Release procedure
 
 1. Ensure `main` is green.
-2. Bump the version and push:
+2. Start the release from `main`:
    ```bash
-   just bump minor   # or patch / major
+   just release-start minor   # or patch / major
    ```
-   This runs `cargo release minor --execute --no-publish` which:
+   This creates a `release` branch and runs `cargo release minor --execute --no-publish` which:
+   - Switches to the new `release` branch
    - Updates `version` in `Cargo.toml`
-   - Commits `"chore: release 0.2.0"`
-   - Creates annotated tag `v0.2.0`
+   - Commits `"chore: release 0.3.0"`
+   - Creates annotated tag `v0.3.0`
    - Pushes commit + tag to origin
 3. The tag push triggers `.github/workflows/release-draft.yml`:
-   - Builds 6 cross-compiled targets (version read directly from `Cargo.toml` via `CARGO_PKG_VERSION`)
-   - Generates changelog with git-cliff, signs artifacts with cosign
+   - Builds 6 cross-compiled targets, generates changelog with git-cliff, signs with cosign
    - Creates a GitHub **draft** release (no crates.io publish at this stage)
 4. Review the draft release, then publish:
    ```bash
@@ -99,11 +99,13 @@ just gh-retag       # delete draft release/tag and re-tag HEAD to re-trigger CI
    - Marks the GitHub release as published
    - Publishes to crates.io
    - Updates the Homebrew tap formula
+   - Fast-forward merges `release → main` and deletes the `release` branch
 5. If CI failed at step 3 (e.g. workflow file was stale on the tag):
    ```bash
-   just gh-retag     # re-tags HEAD and pushes to re-trigger release-draft.yml
+   just release-retry minor   # same level as step 2
    ```
-   Blocked if the release is already published or the version is already on crates.io.
+   Deletes the draft release, tag, and `release` branch, then recreates from the latest `main`.
+   Blocked if the release is already published or the version is on crates.io.
 
 ### Homebrew tap
 

justfile

@@ -14,49 +14,66 @@ install:
 check level="patch":
     cargo release {{level}}
 
-# Bump version, commit Cargo.toml, create annotated tag, push
-# Usage: just bump        (patch)
-#        just bump minor
-#        just bump major
-bump level="patch":
+# Create release branch from main, bump version, commit, tag, push to origin
+# Usage: just release-start        (patch)
+#        just release-start minor
+#        just release-start major
+release-start level="patch":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    CURRENT=$(git rev-parse --abbrev-ref HEAD)
+    if [[ "${CURRENT}" != "main" ]]; then
+        echo "Error: must be on main branch (currently on ${CURRENT})"
+        exit 1
+    fi
+    if git show-ref --verify refs/heads/release >/dev/null 2>&1; then
+        echo "Error: release branch already exists. Use 'just release-retry' to reset it."
+        exit 1
+    fi
+    git pull --ff-only
+    git checkout -b release
     cargo release {{level}} --execute --no-publish
 
-# Publish the tagged commit to crates.io
-# Run after `just bump` has pushed the tag
+# Publish the tagged commit to crates.io (manual fallback)
 publish:
     cargo release publish --execute
 
-# Trigger release-publish.yml workflow to publish draft release and push to crates.io
+# Trigger release-publish.yml: publish GitHub release, crates.io, FF merge release->main
 gh-publish:
     #!/usr/bin/env bash
     set -euo pipefail
     VERSION=$(yq -p toml -oy '.package.version' Cargo.toml)
     gh workflow run release-publish.yml -f tag="v${VERSION}"
 
-# Delete existing draft release + tag, re-tag HEAD, push to re-trigger CI
-# Refuses to run if the release is already published (non-draft) or on crates.io
-gh-retag:
+# Reset a failed release: delete draft/tag/release branch and recreate from latest main
+# Blocked if the GitHub release is published or the version is already on crates.io
+# Usage: just release-retry        (patch)
+#        just release-retry minor
+release-retry level="patch":
     #!/usr/bin/env bash
     set -euo pipefail
     VERSION=$(yq -p toml -oy '.package.version' Cargo.toml)
     TAG="v${VERSION}"
     CRATE="gitversion-rs"
-    STATUS=$(curl -s -o /dev/null -w "%{http_code}" -A "gh-retag/1.0" \
+    STATUS=$(curl -s -o /dev/null -w "%{http_code}" -A "release-retry/1.0" \
         "https://crates.io/api/v1/crates/${CRATE}/${VERSION}")
     if [[ "${STATUS}" == "200" ]]; then
-        echo "Error: ${CRATE} v${VERSION} is already published to crates.io. Refusing to retag."
+        echo "Error: ${CRATE} v${VERSION} is already on crates.io. Cannot retry."
         exit 1
     fi
     IS_DRAFT=$(gh release view "${TAG}" --json isDraft -q '.isDraft' 2>/dev/null || echo "none")
     if [[ "${IS_DRAFT}" == "false" ]]; then
-        echo "Error: ${TAG} is not a draft release. Refusing to retag."
+        echo "Error: ${TAG} is already published. Cannot retry."
         exit 1
     fi
-    echo "Re-tagging ${TAG} at HEAD"
     if [[ "${IS_DRAFT}" == "true" ]]; then
         gh release delete "${TAG}" --yes --cleanup-tag
     fi
     git tag -d "${TAG}" 2>/dev/null || true
     git push origin --delete "${TAG}" 2>/dev/null || true
-    git tag -a "${TAG}" -m "release: ${TAG#v}"
-    git push origin "${TAG}"
+    git push origin --delete release 2>/dev/null || true
+    git checkout main
+    git pull --ff-only
+    git branch -D release 2>/dev/null || true
+    git checkout -b release
+    cargo release {{level}} --execute --no-publish