✨ chore(publish): improve PyPI workflow gating and bump logic Add a CI to gate the workflow and skip expensive steps for release commits, preventing double publishing and runs- publish workflow into two jobs (ci -> publish) and publish depend on ci to early exit and clearer job.

.github/workflows/publish-pypi.yml

@@ -10,19 +10,28 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # ─── Job 0: CI gate — skip the whole workflow on release commits ───
+  ci:
+    if: |
+      github.repository == 'supervaize/supervaizer' &&
+      !contains(github.event.head_commit.message, 'chore(release):')
+    uses: ./.github/workflows/python-package.yml
+
+  # ─── Job 1: Version bump, tag, build, and publish ───
   publish:
+    needs: ci
     runs-on: ubuntu-latest
-    if: github.repository == 'supervaize/supervaizer' # Only run on public remote
     environment:
       name: pypi
       url: https://pypi.org/p/supervaizer
     permissions:
-      id-token: write # required for trusted publishing if using PyPI's OIDC
-      contents: write # required for committing version bump
+      id-token: write  # required for OIDC trusted publishing
+      contents: write  # required for committing version bump
 
     steps:
       - uses: actions/checkout@v4
         with:
+          fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Python
@@ -36,58 +45,39 @@ jobs:
           enable-cache: true
 
       - name: Install bump-my-version
-        run: |
-          uv tool install bump-my-version
+        run: uv tool install bump-my-version
 
       - name: Determine version bump type
-        id: version-bump-type
+        id: bump-type
+        env:
+          COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
         run: |
-          # Get the commit message of the latest commit
-          COMMIT_MSG=$(git log -1 --pretty=%B)
-          echo "Commit message: $COMMIT_MSG"
-
-          # Check if commit contains [MAJOR] or [MINOR]
-          VERSION_BUMP=patch
-
-          # Determine the bump type based on commit message
-          if [[ "$COMMIT_MSG" == *"[MAJOR]"* ]]; then
-            VERSION_BUMP=major
-          elif [[ "$COMMIT_MSG" == *"[MINOR]"* ]]; then
-            VERSION_BUMP=minor
+          MSG="$COMMIT_MESSAGE"
+          if echo "$MSG" | grep -qi '\[MAJOR\]'; then PART="major"
+          elif echo "$MSG" | grep -qi '\[MINOR\]'; then PART="minor"
+          elif echo "$MSG" | grep -qi '\[PATCH\]'; then PART="patch"
+          else PART="minor"
           fi
+          echo "Bump type: $PART"
+          echo "part=$PART" >> "$GITHUB_OUTPUT"
 
-          echo "Determined version bump type: $VERSION_BUMP"
-          echo "VERSION_BUMP=$VERSION_BUMP" >> $GITHUB_OUTPUT
-
-      - name: Bump version
-        id: bump-version
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BUMPVERSION_CONFIG_FILE: pyproject.toml
+      - name: Bump version and rotate CHANGELOG
         run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email 'github-actions@github.com'
-          # Detect current version from __version__.py (authoritative for search)
-          OLD_VERSION=$(grep '^VERSION =' src/supervaizer/__version__.py | cut -d '"' -f2)
-          export OLD_VERSION
-          # Expose for downstream steps
-          echo "OLD_VERSION=${OLD_VERSION}" >> $GITHUB_OUTPUT
-          bump-my-version bump ${{ steps.version-bump-type.outputs.VERSION_BUMP }} \
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git pull --rebase origin main
+          bump-my-version bump ${{ steps.bump-type.outputs.part }} \
             --config-file pyproject.toml \
             --verbose
-          git fetch origin main
-          git rebase origin/main
           git push --follow-tags
-          # Store the new version
-          echo "NEW_VERSION=$(grep '^VERSION =' src/supervaizer/__version__.py | cut -d '"' -f2)" >> $GITHUB_OUTPUT
 
       - name: Install Hatch
         run: pip install hatch
 
       - name: Build package
         run: hatch build
 
-      - name: Publish to PyPI on main
+      - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: dist/

.github/workflows/python-package.yml

@@ -7,7 +7,8 @@ on:
   push:
     branches: ["develop"]
   pull_request:
-    branches: ["develop"]
+    branches: ["develop", "main"]
+  workflow_call:
 
 jobs:
   build:

CONTRIBUTING.md

@@ -18,7 +18,7 @@ just -l
    - `uv venv`
    - Windows: `.venv\Scripts\activate`
    - Unix/MacOS: `source .venv/bin/activate`
-4. Install development dependencies: `uv pip install -e ".[dev]"` or `just dev-install`
+4. Install development dependencies: `just install-dev`
 5. Install Git hooks: `just install-hooks`
 
 ### Running Tests

GEMINI.md

@@ -7,7 +7,7 @@ This is a Python project that provides a toolkit for building, managing, and con
 The project's dependencies are listed in the `pyproject.toml` file. To install them, you can use the `just` command:
 
 ```bash
-just dev-install
+just install-dev
 ```
 
 **2. Scaffolding:**

docs/CHANGELOG.md

@@ -17,7 +17,7 @@ All notable changes to this project will be documented in this file.
   - example: here the 'How many times to say hello' is supposed to be an 'int'.
   - agent_simple:job_start:74 - AGENT ExampleAgent: Received kwargs: {'action': 'start', 'fields': {'How many times to say hello': '3'}, 'context': JobContext(workspace_id='odm', job_id='01KGM75NQ76AWBAXHXERW8FKHW', started_by='alp', started_at=datetime.datetime(2026, 2, 4, 11, 39, 0, 712598, tzinfo=TzInfo(0)), mission_id='01KGG50ZMFYMHG9N5FGCACF0XA', mission_name='Operate Agent Hello World AI Agent', mission_context=None, job_instructions=JobInstructions(max_cases=None, max_duration=None, max_cost=None, stop_on_warning=False, stop_on_error=True, job_start_time=None)), 'agent_parameters': [{'name': 'SIMPLE AGENT PARAMETER', 'team_id': 2, 'description': 'Setup agent parameter in this workspace', 'is_environment': True, 'value': '123456', 'is_secret': False, 'is_required': False}, {'name': 'SIMPLE AGENT SECRET', 'team_id': 2, 'description': 'Setup agent secret in this workspace', 'is_environment': True, 'value': '123456', 'is_secret': True, 'is_required': False}]}
 
-## Unreleased
+## [Unreleased]
 
 ### Added
 
@@ -44,7 +44,7 @@ All notable changes to this project will be documented in this file.
 | 🔴 Failed  | 0     |
 | ⏱️ in      | ~70s  |
 
-## v0.13.1
+## [0.13.1]
 
 ### Added
 
@@ -62,7 +62,7 @@ All notable changes to this project will be documented in this file.
 | 🔴 Failed  | 0     |
 | ⏱️ in      | 65s   |
 
-## v0.12.0
+## [0.12.0]
 
 ### Added
 
@@ -86,7 +86,7 @@ All notable changes to this project will be documented in this file.
   - `AgentResponse` nested schemas not rebuilt after dependent models — added `AgentResponse.model_rebuild()` after `Case.model_rebuild()` in `supervaizer/__init__.py`
   - `CaseNode.factory` typed as `Callable` which cannot appear in JSON Schema — changed to `Any` (behaviour unchanged)
 
-## v0.11.0
+## [0.11.0]
 
 - **Job Poll mechanism** — New optional `job_poll` method in `AgentMethods` for manual external service polling. When defined, the workbench shows a "Check for updates" button on active jobs. Clicking it calls the agent's poll handler, which checks external services (email inboxes, call status APIs, etc.) and updates cases accordingly. Enables local development without webhooks — production uses real-time webhooks, local mode uses the poll button.
   - `AgentMethods`: new `job_poll: AgentMethod | None` field
@@ -153,7 +153,7 @@ All notable changes to this project will be documented in this file.
 | 🔴 Failed  | 0     |
 | ⏱️ in      | 50s   |
 
-## v0.10.19
+## [0.10.19]
 
 ### Added
 
@@ -165,7 +165,7 @@ All notable changes to this project will be documented in this file.
 - **Admin index** – Simplified displayed information in the admin index template.
 - **CI** – PyPI publish workflow: added concurrency settings to cancel in-progress runs.
 
-## v0.10.18
+## [0.10.18]
 
 ### Added
 
@@ -175,7 +175,7 @@ All notable changes to this project will be documented in this file.
 
 - **Refactor** – Code formatting and trailing whitespace cleanup (admin routes, server, examples, tests, templates).
 
-## v0.10.17
+## [0.10.17]
 
 ### Added
 
@@ -201,7 +201,7 @@ All notable changes to this project will be documented in this file.
 | 🔴 Failed  | 0      |
 | ⏱️ in      | 53.16s |
 
-## v0.10.11
+## [0.10.11]
 
 ### Added
 

justfile

@@ -10,10 +10,9 @@ YYYYMMDD:= `date +%Y%m%d`
 default:
     @just --list
 
-# Dev install
-dev-install:
-    uv venv
-    uv pip install -e .[dev]
+# Install dev dependencies
+install-dev:
+    uv sync --extra dev
 
 # Run pre-commit hooks manually
 precommit:
@@ -83,7 +82,7 @@ release-major:
     just _bump-version major
 
 # Push tags to remote
-push-tags:
+push_tags:
     git push origin --tags
     @echo "Tags pushed to remote"
 
@@ -151,10 +150,23 @@ push-main:
 release:
     just merge-to-main
     just push-main
-    just push-tags
+    just push_tags
     just gh-release
     @echo "✅ Release complete! Main branch and tags pushed to remote"
 
+# Ship to production: precommit, merge develop→main, push (CI does the version bump)
+# Embed bump type token ([MINOR]/[PATCH]/[MAJOR]) so CI picks up the right part.
+# Usage: just ship [patch|minor|major]
+ship part="minor":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    just precommit
+    BUMP_TOKEN=$(echo "{{part}}" | tr '[:lower:]' '[:upper:]')
+    git checkout main
+    git pull origin main
+    git merge develop --no-ff -m "[${BUMP_TOKEN}] chore: merge develop to main"
+    git push origin main
+
 # Create or update GitHub release for the latest tag on origin/main
 gh-release:
     bash tools/gh-release-latest-tag.sh supervaize/supervaizer

pyproject.toml

@@ -131,7 +131,7 @@ commit = true
 tag = true
 tag_name = "v{new_version}"
 tag_message = "Release {new_version}"
-message = "Bump version: {current_version} → {new_version}"
+message = "chore(release): v{new_version}"
 # Optional .devN is stripped on bump (CI publishes X.Y.Z only); use `just version-dev on` locally.
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
 serialize = ["{major}.{minor}.{patch}"]
@@ -145,3 +145,8 @@ replace = 'VERSION = "{new_version}"'
 filename = "pyproject.toml"
 search = 'current_version = "{current_version}"'
 replace = 'current_version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "docs/CHANGELOG.md"
+search = "## [Unreleased]"
+replace = "## [Unreleased]\n\n## [{new_version}] - {now:%Y-%m-%d}"