tool-compass 2.2.2__tar.gz → 2.4.0__tar.gz

tool_compass-2.4.0/.dockerignore

@@ -0,0 +1,84 @@
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+.venv/
+ENV/
+env/
+.eggs/
+*.egg-info/
+*.egg
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+.benchmarks/
+
+# Build artifacts
+dist/
+build/
+*.manifest
+*.spec
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Local development files
+*.local.json
+.env.local
+.env*
+
+# Gradio cache
+flagged/
+
+# Keep db directory structure but not contents
+db/*.db
+db/*.hnsw
+!db/.gitkeep
+
+# Sources that don't belong in the production image (CT-B-004).
+# These are intentionally excluded so a future regression to
+# `COPY . .` doesn't silently ship them.
+tests/
+docs/
+site/
+archive/
+.github/
+.claude/
+# Translation READMEs (re-run on TranslateGemma 12B; not runtime artifacts)
+README.ja.md
+README.zh.md
+README.es.md
+README.fr.md
+README.hi.md
+README.it.md
+README.pt-BR.md
+# Audit / governance docs — not needed at runtime
+SCORECARD.md
+SHIP_GATE.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+SECURITY.md
+CHANGELOG.md

{tool_compass-2.2.2 → tool_compass-2.4.0}/.env.example

@@ -55,8 +55,10 @@ GRADIO_SERVER_PORT=7860
 # Analytics (optional)
 # =============================================================================
 
-# Disable analytics tracking
+# Disable analytics tracking (truthy: 1/true/yes/on). Overrides the
+# analytics_enabled config-file key when set.
 # TOOL_COMPASS_ANALYTICS_DISABLED=true
 
-# Hot cache size (number of frequently used tools to pre-load)
+# Hot cache size (number of frequently used tools to pre-load). Overrides the
+# hot_cache_size config-file key; clamped to a safe minimum like any config value.
 # TOOL_COMPASS_HOT_CACHE_SIZE=10

tool_compass-2.4.0/.github/dependabot.yml

@@ -0,0 +1,89 @@
+version: 2
+updates:
+  # =============================================================================
+  # pip — Python runtime + dev dependencies
+  # =============================================================================
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    groups:
+      # Minor + patch only so breaking majors open as SEPARATE PRs.
+      # (Avoids the ollama-intern PR #4 incident where 5 breaking majors
+      # shipped bundled under a wildcard group.)
+      all-pip:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  # Daily security-only overlay (CT-B-006) — CVE updates from the GitHub
+  # Advisory Database don't wait the monthly cadence. open-pull-requests-limit
+  # raised to 10 since these are infrequent and load-bearing.
+  # NOTE: Dependabot security advisories are auto-emitted; this second entry
+  # exists to give them their own schedule/labels/PR cap independent of the
+  # monthly version-update entry above. The `allow: dependency-type: all`
+  # block scopes this entry to all dependencies; security advisories are
+  # always opened regardless of the version-update grouping rules.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+    allow:
+      - dependency-type: "all"
+    labels:
+      - "security"
+      - "dependencies"
+
+  # =============================================================================
+  # github-actions — workflow file action references
+  # =============================================================================
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    groups:
+      all-github-actions:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  # Daily security-only overlay for actions (CT-B-006).
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+    allow:
+      - dependency-type: "all"
+    labels:
+      - "security"
+      - "dependencies"
+
+  # =============================================================================
+  # docker — Dockerfile base-image FROM directives (CT-B-005)
+  # =============================================================================
+  # Pairs with the digest-pinned `FROM python:3.11-slim@sha256:...` in
+  # Dockerfile (CT-B-003). Without this ecosystem entry the digest pin
+  # would become a stale anchor with no machine-readable refresh path.
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 2
+    groups:
+      all-docker:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  # Daily security-only overlay for docker base images (CT-B-006).
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+    allow:
+      - dependency-type: "all"
+    labels:
+      - "security"
+      - "dependencies"

{tool_compass-2.2.2 → tool_compass-2.4.0}/.github/workflows/ci.yml

@@ -35,9 +35,16 @@ on:
     - cron: '0 9 * * 1,3,5'
   workflow_dispatch:
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+# NOTE: concurrency is intentionally NOT set at the workflow level.
+# A workflow-level cancel-in-progress would cancel the whole run when a
+# new push lands on the same ref — including the pages-deploy job that
+# carries its own concurrency: pages / cancel-in-progress: false. The
+# job-level setting cannot override workflow-level cancellation because
+# the entire run is cancelled before per-job concurrency takes effect.
+# Each test/lint/integration/docker job below carries its own
+# concurrency block scoped to PR refs only (push events on main are
+# never cancelled). The pages-build / pages-deploy jobs keep their
+# dedicated concurrency: pages group with cancel-in-progress: false.
 
 # Default least-privilege; individual jobs that need more elevate explicitly.
 permissions:
@@ -47,6 +54,13 @@ jobs:
   lint:
     name: Org URL sanity check
     runs-on: ubuntu-latest
+    # CT-B-011: lint is a sub-30-second shell check; 5 min is generous.
+    timeout-minutes: 5
+    # PR-scoped concurrency: a newer push to the same PR cancels the
+    # older run, but pushes to main never cancel themselves.
+    concurrency:
+      group: lint-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
     permissions:
       contents: read
     steps:
@@ -56,12 +70,27 @@ jobs:
       - name: Check for stale org/user URLs
         run: bash scripts/check-org-urls.sh
 
-      # CDS-FT-001: SCORECARD drift guard. Soft-fail for now — shipcheck
-      # markdown output is still settling. Flip continue-on-error to false
-      # once the format stabilizes.
-      # TODO(swarm): enforce once shipcheck JSON format stabilizes
-      - name: Verify SCORECARD is in sync
+      - name: Set up Python (pre-commit)
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.11'
+
+      # CT-B-018: run the pre-commit hooks (ruff format + ruff check +
+      # standard hygiene + gitleaks). Same hooks the contributor runs
+      # locally; this is the CI-side enforcement. Soft-fail for the first
+      # cycle to surface formatting drift without blocking PRs while
+      # contributors install pre-commit locally.
+      # TODO(swarm): flip continue-on-error to false after one full release
+      # cycle so the pre-commit gate becomes blocking.
+      - name: Run pre-commit hooks
         continue-on-error: true
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+      # CDS-FT-001: SCORECARD drift guard — now BLOCKING. The dogfood-swarm v3
+      # pass fixed CIDOCS-01 (regenerate-scorecard.sh forces NO_COLOR + strips
+      # ANSI), so `--check` diff-cleans deterministically in non-TTY CI. The
+      # committed SCORECARD was verified in sync at flip time.
+      - name: Verify SCORECARD is in sync
         run: |
           if [ -f Makefile ] && grep -q "^verify-scorecard:" Makefile; then
             make verify-scorecard
@@ -69,9 +98,32 @@ jobs:
             echo "Makefile verify-scorecard target missing — skipping"
           fi
 
+      # CT-B-008 cross-domain: verify that /metrics emits the expected
+      # Four Golden Signals surface. Soft-fail because the saturation
+      # gauges land in BE-B-002 (backend domain); flip to fatal once that
+      # work merges.
+      - name: Verify metrics surface (Four Golden Signals)
+        continue-on-error: true
+        run: |
+          if [ -f Makefile ] && grep -q "^verify-metrics:" Makefile; then
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt || true
+            make verify-metrics || true
+          else
+            echo "Makefile verify-metrics target missing — skipping"
+          fi
+
   test:
     name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
+    # CT-B-011: per-matrix-cell budget. pytest has its own 30s per-test cap
+    # (pyproject.toml [tool.pytest.ini_options]); 15 min envelope covers
+    # install + coverage + pip-audit with headroom for a slow runner.
+    timeout-minutes: 15
+    # PR-scoped concurrency (see workflow-top NOTE).
+    concurrency:
+      group: test-${{ matrix.python-version }}-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
     permissions:
       contents: read
 
@@ -116,6 +168,9 @@ jobs:
           name: junit-reports-${{ matrix.python-version }}
           path: junit-${{ matrix.python-version }}.xml
           if-no-files-found: warn
+          # CT-B-012: JUnit reports are short-lived diagnostic data — only
+          # useful for the most recent few runs. Default 90d is wasted.
+          retention-days: 14
 
       - name: Run tests with coverage
         if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
@@ -142,13 +197,17 @@ jobs:
           name: pip-audit-report
           path: pip-audit-report.json
           if-no-files-found: ignore
+          # CT-B-012: CVE diagnostic snapshot — 14d aligns with the JUnit
+          # retention and is plenty of window for incident response.
+          retention-days: 14
 
+      # Now BLOCKING. The dogfood-swarm v3 pass reviewed the CVE baseline:
+      # `pip-audit -r requirements.txt` reports no known vulnerabilities. The
+      # report-only artifact step above still runs for the full JSON snapshot.
       - name: Audit dependencies for vulnerabilities
         if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
         run: |
           pip-audit -r requirements.txt
-        # TODO(swarm): enforce after CVE baseline reviewed — issue #TBD
-        continue-on-error: true  # Warn-only until clean baseline established
 
   # TST-FT-002: nightly Hypothesis fuzzing. Runs on schedule (Mon/Wed/Fri 09:00
   # UTC) or manually via workflow_dispatch. Never runs on push/PR — nightly-only.
@@ -157,6 +216,9 @@ jobs:
     name: Nightly Hypothesis fuzz
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    # CT-B-011: Hypothesis nightly profile is deliberately slow — 45 min cap
+    # is wider than the test job because fuzz examples are unbounded.
+    timeout-minutes: 45
     permissions:
       contents: read
       issues: write
@@ -184,9 +246,10 @@ jobs:
 
       - name: Open tracking issue on failure
         if: failure() && steps.fuzz.conclusion == 'failure'
-        # TODO(swarm): pin actions/github-script to SHA once nightly-fuzz run
-        # history confirms the job shape is stable.
-        uses: actions/github-script@v7
+        # SHA-pinned per SLSA L3 supply-chain hygiene (CT-B-001). nightly-fuzz
+        # carries issues:write, so a compromised v7 mutable tag would inherit
+        # issue-creation capability. Bump via dependabot's github-actions sweep.
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const title = `[nightly-fuzz] Hypothesis failures on ${context.sha}`;
@@ -212,6 +275,13 @@ jobs:
     name: Integration Tests
     runs-on: ubuntu-latest
     needs: test  # Only run after unit tests pass
+    # CT-B-011: Ollama install + nomic-embed-text pull + integration suite
+    # dominates; 25 min envelope covers the cold-start pull path.
+    timeout-minutes: 25
+    # PR-scoped concurrency (see workflow-top NOTE).
+    concurrency:
+      group: integration-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
     permissions:
       contents: read
 
@@ -271,6 +341,12 @@ jobs:
     name: Docker Build
     runs-on: ubuntu-latest
     needs: test
+    # CT-B-011: docker buildx + gha cache; 20 min covers a cold-cache build.
+    timeout-minutes: 20
+    # PR-scoped concurrency (see workflow-top NOTE).
+    concurrency:
+      group: docker-${{ github.event.pull_request.number || github.run_id }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
     permissions:
       contents: read
 
@@ -299,6 +375,8 @@ jobs:
     name: Build site
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     runs-on: ubuntu-latest
+    # CT-B-011: Starlight npm ci + Astro build; 10 min is generous.
+    timeout-minutes: 10
     permissions:
       contents: read
     steps:
@@ -308,6 +386,12 @@ jobs:
         with:
           node-version: 22
 
+      # CT-B-016: read repo-level Pages configuration so the build is not
+      # silently dependent on Settings → Pages UI state. configure-pages
+      # is idempotent and exposes the base path to downstream steps.
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
       - name: Install site dependencies
         working-directory: site
         run: npm ci
@@ -325,6 +409,9 @@ jobs:
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     needs: pages-build
     runs-on: ubuntu-latest
+    # CT-B-011: deploy is a metadata operation against the Pages backend;
+    # 5 min is the fail-fast budget.
+    timeout-minutes: 5
     # Dedicated concurrency group so a long deploy is never cancelled by a
     # newer CI run (CDS-A-012).
     concurrency:

tool_compass-2.4.0/.github/workflows/publish.yml

@@ -0,0 +1,285 @@
+# Tool Compass Release Pipeline
+# Publishes to PyPI (trusted publishing) and GHCR on release
+
+name: Publish
+
+# Triggers — the load-bearing one for the auto-chain is `workflow_run`:
+#  * `release: published` does NOT fire when the Release was created by
+#    release.yml using secrets.GITHUB_TOKEN (GitHub's recursion guard). Without
+#    the workflow_run trigger below, a tag-push release would publish to npm
+#    (via release.yml) but silently SKIP PyPI + GHCR here. The `workflow_run`
+#    trigger gated on Release.conclusion == 'success' closes the chain.
+#  * `release: published` retained for manual hand-cut Releases (gh release
+#    create from a maintainer's terminal — attributed to a user, fires normally).
+#  * `workflow_dispatch` retained for re-run-from-UI on transient failure.
+on:
+  release:
+    types: [published]
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
+  workflow_dispatch:
+
+# Publish workflows must serialize, not cancel. Cancelling a mid-flight twine
+# upload leaves PyPI in a state where the next retry fails with E409 ('File
+# already exists') and needs manual --skip-existing recovery. Group per release
+# tag — resolved across all trigger types (under workflow_run github.ref is the
+# default branch, not the tag) — so distinct tags run independently while
+# same-tag re-fires queue safely.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref }}
+  cancel-in-progress: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    # When triggered by workflow_run, only proceed if the upstream Release
+    # workflow succeeded. release: published / workflow_dispatch invocations set
+    # workflow_run to null, which evaluates this expression to truthy (we only
+    # want to short-circuit FAILED workflow_run events).
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
+    # CT-B-011: fail-fast budgets per SRE 'fail fast' (Google SRE Book ch.21).
+    # Default GitHub timeout is 360 min; a wedged dependency install or twine
+    # check is well outside the legitimate envelope at 10 min.
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Under workflow_run, github.ref is the default branch (main), NOT the
+          # tag — build the tagged commit, not main's HEAD. Resolve the tag from
+          # the single canonical expression used throughout this workflow.
+          ref: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package with twine
+        run: twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+          # CT-B-012: dist/ is an ephemeral build-to-publish handoff; the
+          # canonical artifacts live at PyPI + GHCR after publish completes.
+          # Keep the workflow copy around 7 days for incident-response replays.
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    # CT-B-011: PyPI upload + propagation; 10 min covers retries.
+    timeout-minutes: 10
+    permissions:
+      id-token: write
+      # CT-B-009: attestations:write enables SLSA provenance attestations on
+      # the published wheel + sdist via pypa/gh-action-pypi-publish v1.13+.
+      # Combined with `attestations: true` below, PyPI surfaces a verifiable
+      # build attestation tied to this commit + workflow run.
+      attestations: write
+      contents: read
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          # CT-B-009: emit SLSA build provenance attestations for the wheel
+          # and sdist. PyPI verifies the attestation against the workflow's
+          # OIDC identity; downstream consumers can audit the chain from a
+          # specific commit -> workflow run -> published artifact.
+          attestations: true
+
+  docker:
+    name: Publish to GHCR
+    runs-on: ubuntu-latest
+    # PyPI ships first (CDS-B-005). If PyPI fails, Docker must not ship a
+    # half-release; if PyPI succeeds, Docker becomes the recoverable tail.
+    needs: publish-pypi
+    # CT-B-011: multi-arch buildx (linux/amd64 + linux/arm64) + push to GHCR
+    # is the longest leg; 30 min covers the warm cache path with headroom.
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+      # CT-B-009: id-token + attestations enable buildx SLSA provenance
+      # mode=max on the image manifest below.
+      id-token: write
+      attestations: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Under workflow_run, github.ref is main, NOT the tag — build the
+          # tagged commit, not main's HEAD. Same resolved-tag expression used
+          # throughout this workflow.
+          ref: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Resolve the release version explicitly. Under workflow_run github.ref
+      # points at the default branch (main), NOT the tag — so
+      # docker/metadata-action's type=semver rules (which only fire on a
+      # refs/tags/... ref) emit NOTHING and the image never gets a :X.Y.Z / :X.Y
+      # tag (only :latest + :sha-...). The tag that started the upstream Release
+      # run is carried on github.event.workflow_run.head_branch (= the tag ref).
+      # Feed the resolved version into metadata-action via type=raw below.
+      - name: Resolve release version
+        id: ver
+        shell: bash
+        run: |
+          set -euo pipefail
+          REF="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}"
+          V="${REF#v}"
+          echo "version=${V}" >> "$GITHUB_OUTPUT"
+          echo "major_minor=$(echo "$V" | cut -d. -f1-2)" >> "$GITHUB_OUTPUT"
+          echo "resolved=${V} (event=${{ github.event_name }} ref=${REF})"
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # type=raw from the explicitly-resolved version (see Resolve step) —
+          # NOT type=semver, which silently emits nothing under workflow_run
+          # because github.ref is main, not the tag. Each enable=... gates its
+          # raw tag so an empty/missing version never pushes a bogus tag.
+          tags: |
+            type=raw,value=${{ steps.ver.outputs.version }},enable=${{ steps.ver.outputs.version != '' }}
+            type=raw,value=${{ steps.ver.outputs.major_minor }},enable=${{ steps.ver.outputs.major_minor != '' }}
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      # QEMU is required to cross-build linux/arm64 from an amd64 runner.
+      - name: Set up QEMU
+        # SHA-pinned per SLSA L3 supply-chain hygiene (CT-B-002). publish job
+        # carries packages:write — a compromised mutable v3 tag would inherit
+        # GHCR write capability during a release window. Bump via dependabot.
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Build and push
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          # CT-B-009: SLSA provenance mode=max emits buildx provenance
+          # attestation (including all input source digests) attached to the
+          # image manifest. sbom: true emits an SPDX SBOM attestation in the
+          # same manifest. Both consumable via `cosign verify-attestation`
+          # or `docker buildx imagetools inspect`.
+          provenance: mode=max
+          sbom: true
+
+  release-smoke:
+    name: Release smoke test
+    runs-on: ubuntu-latest
+    needs: [publish-pypi, docker]
+    # CT-B-011: PyPI propagation retry loop + docker pull + version handshake.
+    # 15 min is the propagation-retry window plus headroom.
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Derive version (strip leading v)
+        id: ver
+        run: |
+          set -euo pipefail
+          # Resolve the tag across all trigger types. Under workflow_run
+          # github.event.release.tag_name is null and github.ref is main —
+          # workflow_run.head_branch carries the tag ref (e.g. v2.4.0).
+          TAG="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.11'
+
+      - name: PyPI smoke — install + --version matches tag
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.ver.outputs.version }}"
+          # PyPI propagation is fast but not instant; retry briefly. If no
+          # iteration succeeds the loop falls through and the subsequent
+          # `tool-compass --version` invocation fails with a clear "command
+          # not found", which is the desired loud failure mode (CT-B-014).
+          install_ok=0
+          for _ in $(seq 1 12); do
+            if pip install "tool-compass==${VERSION}"; then
+              install_ok=1
+              break
+            fi
+            sleep 10
+          done
+          if [ "$install_ok" -ne 1 ]; then
+            echo "::error::PyPI smoke failed: tool-compass==${VERSION} did not become installable in the propagation window"
+            exit 1
+          fi
+          OUT="$(tool-compass --version 2>&1 || true)"
+          echo "tool-compass --version → $OUT"
+          echo "$OUT" | grep -Fq "${VERSION}" || {
+            echo "::error::PyPI smoke failed: --version output did not contain ${VERSION}"
+            exit 1
+          }
+
+      - name: Log in to GHCR (pull)
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker smoke — pull + --version matches tag
+        run: |
+          set -euo pipefail
+          TAG="${{ steps.ver.outputs.tag }}"
+          VERSION="${{ steps.ver.outputs.version }}"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${VERSION}"
+          docker pull "$IMAGE"
+          OUT="$(docker run --rm --entrypoint tool-compass "$IMAGE" --version 2>&1 || true)"
+          echo "docker --version → $OUT"
+          echo "$OUT" | grep -Fq "${VERSION}" || {
+            echo "::error::Docker smoke failed: --version output did not contain ${VERSION}"
+            exit 1
+          }