Merge branch 'main' into dependabot/pip/myst-parser-gte-4.0.1-and-lt-6

Author: helmut-hoffer-von-ankershoffen

.claude/settings.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude_ai_Atlassian__getConfluencePage",
+      "mcp__claude_ai_Atlassian__getVisibleJiraProjects",
+      "mcp__claude_ai_Atlassian__getAccessibleAtlassianResources",
+      "mcp__claude_ai_Atlassian__getCompassComponent",
+      "mcp__claude_ai_Atlassian__getJiraIssue",
+      "mcp__claude_ai_Atlassian__searchJiraIssuesUsingJql",
+      "mcp__claude_ai_Atlassian__search",
+      "mcp__claude_ai_Atlassian__getConfluenceSpaces",
+      "mcp__claude_ai_Atlassian__getPagesInConfluenceSpace",
+      "mcp__claude-in-chrome__read_page",
+      "mcp__claude-in-chrome__get_page_text",
+      "mcp__claude-in-chrome__tabs_context_mcp",
+      "Bash(make lint)",
+      "Bash(make lint_fix)",
+      "Bash(make test_unit)",
+      "Bash(make test_integration)",
+      "Bash(make audit)",
+      "Bash(gh label list *)",
+      "Bash(gh search *)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [],
+  "extraKnownMarketplaces": {
+    "aignostics-claude-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "aignostics/claude-plugins"
+      },
+      "autoUpdate": true
+    }
+  },
+  "enabledPlugins": {
+    "qms@aignostics-claude-plugins": true
+  }
+}

.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)
+* **Multiple workflow files**, including both entry-point and 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,6 @@ 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)
 
 **Usage**:
 
@@ -398,6 +403,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 +421,6 @@ 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:`
 * PR has label `skip:ci` or `build:native:only`
 
 **Job Dependencies**:
@@ -1006,26 +1011,39 @@ 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 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 +1088,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 |

.github/CODEOWNERS

@@ -1,5 +1,5 @@
 # aignostics code owners
 
-* @helmut-hoffer-von-ankershoffen
+* @aignostics/be-tada @helmut-hoffer-von-ankershoffen
 
 # Reference: <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners>

.github/actions/run-tests/action.yml

@@ -30,9 +30,12 @@ runs:
         (!contains(inputs.commit-message, 'skip:test:all')) &&
         (!contains(github.event.pull_request.labels.*.name, 'skip:test:all'))
       shell: bash
+      env:
+        MAKE_TARGET: ${{ inputs.make-target }}
+        SUMMARY_TITLE: ${{ inputs.summary-title }}
       run: |
         set +e
-        make ${{ inputs.make-target }}
+        make $MAKE_TARGET
         EXIT_CODE=$?
         # Show test execution in GitHub Job summary
         found_files=0
@@ -44,7 +47,7 @@ runs:
         fi
         done
         if [ $found_files -eq 0 ]; then
-          echo "# ${{ inputs.summary-title }}" >> $GITHUB_STEP_SUMMARY
+          echo "# $SUMMARY_TITLE" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
         fi
         # Show test coverage in GitHub Job summary

.github/dependabot.yml

@@ -133,3 +133,76 @@
 - name: documentation-drift
   description: Documentation out of sync with code
   color: "ff6b6b"
+
+# SOP Labels — governance trail on every PR (one mandatory)
+- name: sop:pr-sop-01
+  description: PR-SOP-01 Problem Resolution (bug / anomaly fix)
+  color: "5319e7"
+
+- name: sop:cc-sop-01
+  description: CC-SOP-01 Change Control (feature / planned change)
+  color: "1d76db"
+
+# Type Labels — conventional-commits taxonomy (one per PR)
+# Extends the legacy `bug` / `documentation` / `enhancement` labels with
+# the rest of the conventional-commit vocabulary. Legacy labels remain
+# for backward-compatibility with issue templates and external tooling;
+# the `type:*` namespace is the source of truth for PR-level filtering.
+- name: type:feature
+  description: New functionality (conventional feat)
+  color: "a2eeef"
+
+- name: type:fix
+  description: Bug fix (conventional fix)
+  color: "d73a4a"
+
+- name: type:chore
+  description: Tooling, maintenance, routine task (conventional chore)
+  color: "c5def5"
+
+- name: type:refactor
+  description: Refactor without behaviour change
+  color: "fbca04"
+
+- name: type:docs
+  description: Documentation-only change
+  color: "0075ca"
+
+- name: type:test
+  description: Test-only change
+  color: "006b75"
+
+- name: type:perf
+  description: Performance improvement
+  color: "4b0082"
+
+- name: type:build
+  description: Build / packaging change
+  color: "5319e7"
+
+- name: type:ci
+  description: CI/CD change
+  color: "000000"
+
+# Security Labels — orthogonal axis (0–2 per PR)
+- name: security
+  description: Addresses a security advisory, CVE, or hardens security posture
+  color: "b60205"
+
+- name: security:supply-chain
+  description: Supply-chain (dependency) vulnerability remediation
+  color: "d93f0b"
+
+# Scope Labels — who the change affects (0–1 per PR)
+- name: scope:sdk-consumers
+  description: Affects downstream SDK consumers (uvx aignostics / uv add aignostics)
+  color: "0e8a16"
+
+- name: scope:dev-only
+  description: Affects only our dev/CI env; consumers unaffected
+  color: "bfdadc"
+
+# Automation Labels
+- name: auto-merge
+  description: Eligible for auto-merge once CI is green
+  color: "0e8a16"

.github/labels.yml

@@ -13,12 +13,12 @@ jobs:
       packages: read
     steps:
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version-file: "pyproject.toml"
           enable-cache: true
@@ -37,7 +37,7 @@ jobs:
         run: make audit
 
       - name: Upload audit results
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         if: ${{ always() && (env.GITHUB_WORKFLOW_RUNTIME != 'ACT') }}
         with:
           name: audit-results

.github/workflows/_audit.yml

@@ -39,12 +39,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version-file: "pyproject.toml"
           enable-cache: true
@@ -61,7 +61,7 @@ jobs:
         run: make dist_native
 
       - name: Upload dist_native artifacts
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         if: ${{ always() && (env.GITHUB_WORKFLOW_RUNTIME != 'ACT') }}
         with:
           name: dist_native-${{ matrix.runner }}

.github/workflows/_build-native-only.yml

@@ -46,12 +46,12 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: ${{ inputs.mode == 'interactive' && 0 || 1 }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
         with:
           version-file: "pyproject.toml"
           enable-cache: true
@@ -66,7 +66,7 @@ jobs:
         run: uv sync --all-extras --frozen --link-mode=copy
 
       - name: Setup display
-        uses: pyvista/setup-headless-display-action@7d84ae825e6d9297a8e99bdbbae20d1b919a0b19 # v4.2
+        uses: pyvista/setup-headless-display-action@5bc8de3bc71fcda7a96439571287a554901541a0 # v4.3
 
       - name: Print development version info
         if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
@@ -77,9 +77,8 @@ jobs:
 
       - name: Run Claude Code (Interactive Mode)
         if: inputs.mode == 'interactive'
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@6e2bd52842c65e914eba5c8badd17560bd26b5de # v1.0.89
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: ${{ inputs.track_progress }}
           additional_permissions: |
@@ -93,9 +92,8 @@ jobs:
 
       - name: Run Claude Code (Automation Mode)
         if: inputs.mode == 'automation'
-        uses: anthropics/claude-code-action@v1.0.29
+        uses: anthropics/claude-code-action@6e2bd52842c65e914eba5c8badd17560bd26b5de # v1.0.89
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: ${{ inputs.track_progress }}
           use_sticky_comment: ${{ inputs.use_sticky_comment }}