docs: update release workflow for release branch strategy

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: olivermeyer

.github/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides comprehensive guidance for Claude Code and human engineers wo
 
 The Aignostics Python SDK uses a **sophisticated multi-stage CI/CD pipeline** built on GitHub Actions with:
 
-* **19 workflow files** (8 entry points + 11 reusable workflows)
+* **22 workflow files** (11 entry points + 11 reusable workflows)
 * **Reusable workflow architecture** for modularity and maintainability
 * **Environment-based testing** (staging/production with scheduled validation)
 * **Multi-category test execution** (unit, integration, e2e, long_running, very_long_running, scheduled)
@@ -21,7 +21,7 @@ The Aignostics Python SDK uses a **sophisticated multi-stage CI/CD pipeline** bu
 ```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    ci-cd.yml (Main Orchestrator)                    │
-│         Triggered on: push to main, PR, release, tag v*.*.*        │
+│   Triggered on: push to main/release/v*, PR, release, tag v*.*.*   │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                      │
 │  ┌────────┐  ┌───────┐  ┌────────────────┐  ┌────────┐           │
@@ -56,6 +56,9 @@ The Aignostics Python SDK uses a **sophisticated multi-stage CI/CD pipeline** bu
 ┌───────────────────────────────────────────────────────────────┐
 │                    Parallel Entry Points                       │
 ├───────────────────────────────────────────────────────────────┤
+│  prepare-release.yml      → Create release branch             │
+│  publish-release.yml      → Tag + changelog → CI/CD publish   │
+│  merge-release.yml        → Merge branch into main            │
 │  build-native-only.yml    → Native executables (6 platforms)  │
 │  claude-code-*.yml        → PR reviews + interactive sessions  │
 │  test-scheduled-*.yml     → Staging (6h) + Production (24h)   │
@@ -70,7 +73,10 @@ The Aignostics Python SDK uses a **sophisticated multi-stage CI/CD pipeline** bu
 
 | Workflow | Triggers | Purpose | Calls |
 |----------|----------|---------|-------|
-| **ci-cd.yml** | push(main), PR, release, tag | Main CI/CD pipeline | _lint,_audit, _test,_codeql, _ketryx,_package-publish, _docker-publish |
+| **ci-cd.yml** | push(main, release/v*), PR, release, tag | Main CI/CD pipeline | _lint,_audit, _test,_codeql, _ketryx,_package-publish, _docker-publish |
+| **prepare-release.yml** | workflow_dispatch | Create release branch + bump version | — |
+| **publish-release.yml** | workflow_dispatch | Generate changelog, tag, push → CI/CD | — |
+| **merge-release.yml** | workflow_dispatch | Merge release branch into main | — |
 | **build-native-only.yml** | push, PR, release (if msg contains `build:native:only`) | Native executable builds | _build-native-only |
 | **claude-code-interactive.yml** | workflow_dispatch (manual) | Manual Claude sessions | _claude-code (interactive) |
 | **claude-code-automation-pr-review.yml** | PR opened/sync (excludes bots) | Automated PR reviews | _claude-code (automation) |
@@ -379,7 +385,7 @@ uv run pytest -m "(scheduled or scheduled_only)" -v
 * `build:native:only` - Only build native executables
 * `skip:test:long_running` - Skip long-running tests
 * `enable:test:very_long_running` - Enable very long running tests
-* `Bump version:` - Skip CI (version bump commits)
+* `Bump version:` - Skip CI on `main` only (does **not** skip CI on `release/v*` branches)
 
 **Usage**:
 
@@ -398,6 +404,7 @@ git commit -m "fix: issue skip:test:long_running"
 **Triggers**:
 
 * `push` to `main` branch
+* `push` to `release/v*` branches (release branch CI)
 * `pull_request` to `main` (opened, synchronize, reopened)
 * `release` created
 * `tags` matching `v*.*.*`
@@ -415,7 +422,7 @@ Cancels in-progress runs when new commits are pushed to same PR/branch.
 
 * Commit message contains `skip:ci`
 * Commit message contains `build:native:only`
-* Commit starts with `Bump version:`
+* Commit starts with `Bump version:` **on the `main` branch only** (on `release/v*` branches the bump commit intentionally runs CI)
 * PR has label `skip:ci` or `build:native:only`
 
 **Job Dependencies**:
@@ -1006,26 +1013,42 @@ make dist_native
 
 ### Releasing a Version
 
-1. Ensure `main` branch is clean and all tests pass
-2. Run version bump:
+Releases use a four-phase workflow triggered from the developer's machine via `gh workflow run`. This lets Ketryx compliance approvals be collected *before* the tag (and thus before publishing to PyPI).
 
-   ```bash
-   make bump patch  # or minor, major
-   ```
+**Phase 1 — Prepare the release branch** (triggers `prepare-release.yml`):
 
-3. This creates a commit and git tag
-4. Push with tags:
+```bash
+make prepare-release patch   # 1.0.0 → 1.0.1
+make prepare-release minor   # 1.0.0 → 1.1.0
+make prepare-release major   # 1.0.0 → 2.0.0
+make prepare-release 1.2.3   # explicit version
+```
+
+Creates `release/vX.Y.Z` from `main`, commits version bump + `uv.lock`, pushes. CI runs on the branch automatically.
+
+**Phase 2 — Collect Ketryx approvals:**
+
+Point the Ketryx release to `release/vX.Y.Z` and collect approvals. Ensure CI is green.
+
+**Phase 3 — Publish** (triggers `publish-release.yml`):
+
+```bash
+make publish-release             # auto-detects release/v* branch
+make publish-release release/v1.2.3  # explicit branch
+```
+
+Generates `CHANGELOG.md`, creates annotated `vX.Y.Z` tag, pushes → CI/CD fires on tag → Ketryx check must pass before PyPI publish.
+
+**Phase 4 — Merge back to main** (triggers `merge-release.yml`):
+
+```bash
+make merge-release             # auto-detects release/v* branch
+make merge-release release/v1.2.3  # explicit branch
+```
 
-   ```bash
-   git push --follow-tags
-   ```
+Merges `release/vX.Y.Z` into `main` with `--no-ff`, pushes `main`, deletes the release branch.
 
-5. CI detects tag and triggers:
-   * Full CI pipeline (lint, audit, test, CodeQL)
-   * Package build and publish to PyPI
-   * Docker image build and publish
-   * GitHub release creation
-   * Slack notification to team
+**Note on branch protection**: `release/v*` branches should be protected so that only the GitHub Actions bot (`aignostics-release-bot[bot]`) can push to them. This enforces the server-side workflow. Configure in GitHub Settings → Branches → Branch protection rules.
 
 ### Manual Testing with Claude
 
@@ -1070,6 +1093,9 @@ make dist_native
 | File | Type | Purpose | Duration |
 |------|------|---------|----------|
 | `ci-cd.yml` | Entry | Main pipeline orchestration | ~20 min |
+| `prepare-release.yml` | Entry | Create release branch + bump version | ~2 min |
+| `publish-release.yml` | Entry | Generate changelog, create tag, push | ~2 min |
+| `merge-release.yml` | Entry | Merge release branch into main | ~1 min |
 | `build-native-only.yml` | Entry | Native build trigger | ~60 min (6 platforms) |
 | `claude-code-interactive.yml` | Entry | Manual Claude sessions | varies |
 | `claude-code-automation-pr-review.yml` | Entry | Automated PR reviews | ~10 min |

CLAUDE.md

@@ -1277,48 +1277,76 @@ uv sync --all-extras  # Install all optional groups
 
 ### Version Bumping and Releases
 
-**Bump version (via Nox):**
+Releases follow a **four-phase GitHub workflow–based strategy** that allows Ketryx compliance approvals to be collected *before* publishing:
 
-```bash
-# Patch version (1.0.0 -> 1.0.1)
-make bump patch
+```
+Phase 0 (anytime): Create the Ketryx release in the Ketryx portal
+Phase 1:           make prepare-release patch|minor|major|x.y.z
+Phase 2:           Point Ketryx release to release/vX.Y.Z; collect approvals
+Phase 3:           make publish-release
+Phase 4:           make merge-release
+```
 
-# Minor version (1.0.0 -> 1.1.0)
-make bump minor
+**Phase 1 — Prepare the release branch:**
 
-# Major version (1.0.0 -> 2.0.0)
-make bump major
+```bash
+# Creates release/vX.Y.Z branch from main, bumps version files, and pushes.
+# No tag is created yet.
+make prepare-release patch   # 1.0.0 → 1.0.1
+make prepare-release minor   # 1.0.0 → 1.1.0
+make prepare-release major   # 1.0.0 → 2.0.0
+make prepare-release 1.2.3   # explicit version
 ```
 
-**This process:**
+This triggers `prepare-release.yml` on GitHub Actions, which:
 
-1. Updates version in `pyproject.toml`
-2. Creates git commit: "Bump version: 1.0.0 → 1.0.1"
-3. Creates git tag: `v1.0.1`
-4. Generates changelog from conventional commits
+1. Creates `release/vX.Y.Z` branch from `main`
+2. Runs `bump-my-version` (commits version files + `uv.lock`)
+3. Pushes the branch — CI runs lint/test/audit on it
 
-**Push with tags:**
+**Phase 2 — Collect Ketryx approvals:**
+
+Point the Ketryx release to the `release/vX.Y.Z` branch and collect required approvals. CI must be green on the branch before proceeding.
+
+**Phase 3 — Publish (tag + PyPI):**
 
 ```bash
-# Push commits and tags
-git push --follow-tags
+# Generates CHANGELOG.md, creates vX.Y.Z tag, pushes → triggers CI/CD publish.
+make publish-release
 
-# CI detects tag and triggers:
-# 1. Full CI pipeline (lint + test + audit)
-# 2. Package build and publish to PyPI
-# 3. Docker image build and publish
-# 4. GitHub release creation
-# 5. Slack notification
+# Optionally specify a branch explicitly:
+make publish-release release/v1.2.3
 ```
 
-**Manual release (if needed):**
+This triggers `publish-release.yml`, which:
+
+1. Generates `CHANGELOG.md` for the release range
+2. Commits the changelog
+3. Creates and pushes the annotated `vX.Y.Z` tag
+4. CI/CD fires on the tag; Ketryx check must pass before PyPI publish
+
+**Phase 4 — Merge back to main:**
 
 ```bash
-# Build package
-uv build
+# Merges the release branch into main (--no-ff) and deletes the branch.
+make merge-release
+
+# Optionally specify a branch explicitly:
+make merge-release release/v1.2.3
+```
+
+This triggers `merge-release.yml`, which:
 
-# Publish to PyPI (via UV_PUBLISH_TOKEN secret)
-uv publish
+1. Merges `release/vX.Y.Z` into `main` with `--no-ff`
+2. Pushes `main`
+3. Deletes the remote release branch
+
+**What triggers CI/CD:**
+
+```
+make prepare-release  → push to release/vX.Y.Z  → lint + test + audit + Ketryx
+make publish-release  → push vX.Y.Z tag          → full CI + PyPI + Docker + GitHub release
+make merge-release    → push to main              → full CI pipeline
 ```
 
 ### CI/CD Integration

CONTRIBUTING.md

@@ -124,17 +124,38 @@ Notes:
 
 ### Publish Release
 
+Releases follow a four-phase workflow that allows Ketryx compliance approvals to be collected before publishing:
+
+**Phase 1 — Create the release branch:**
+
 ```shell
-make bump   # Patch release
-make minor  # Patch release
-make major  # Patch release
-make x.y.z  # Targeted release
+make prepare-release patch   # 1.0.0 → 1.0.1
+make prepare-release minor   # 1.0.0 → 1.1.0
+make prepare-release major   # 1.0.0 → 2.0.0
+make prepare-release 1.2.3   # explicit version
 ```
 
-Notes:
+This triggers a GitHub Actions workflow that creates `release/vX.Y.Z` from `main`, bumps version files, and pushes the branch. CI runs automatically on the branch.
+
+**Phase 2 — Collect Ketryx approvals:**
+
+Point the Ketryx release to the `release/vX.Y.Z` branch and collect required approvals.
+
+**Phase 3 — Publish (tag → PyPI):**
+
+```shell
+make publish-release
+```
+
+Generates `CHANGELOG.md`, creates the `vX.Y.Z` tag, and pushes — triggering CI/CD which publishes to PyPI, Docker registries, and creates a GitHub release (Ketryx check must pass first).
+
+**Phase 4 — Merge back to main:**
+
+```shell
+make merge-release
+```
 
-1. Changelog generated automatically
-2. Publishes to PyPi, Docker Registries, Read The Docs, Streamlit and Auditing services
+Merges the release branch into `main` with `--no-ff` and deletes the branch.
 
 ## Advanced usage