chipgraph 0.1.0__tar.gz

chipgraph-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "chipgraph",
+  "description": "chipgraph: an AI agent system for chip (IC) design",
+  "owner": {
+    "name": "quynhonsemiconductor",
+    "url": "https://github.com/quynhonsemiconductor"
+  },
+  "plugins": [
+    {
+      "name": "chipgraph",
+      "source": "./plugin",
+      "description": "chipgraph for chip (IC) design in Claude Code: /chipgraph:status, /chipgraph:trace, /chipgraph:ask, /chipgraph:triage, /chipgraph:init-chipgraph and /chipgraph:run, over the chipgraph MCP server."
+    }
+  ]
+}

chipgraph-0.1.0/.dockerignore

@@ -0,0 +1,31 @@
+# Root .dockerignore — the build context is the repo root (docker/Dockerfile COPYs
+# pyproject.toml, uv.lock, README.md, src/, and, for the `test` target, tests/ and
+# examples/ from there), so this lives at the root rather than under docker/.
+
+.git
+.github
+.venv
+venv
+**/__pycache__
+**/*.py[cod]
+*.egg-info
+.eggs
+.mypy_cache
+.ruff_cache
+.pytest_cache
+.cache
+dist
+build
+docs
+!docs/tb-claude-code/
+!docs/tb-claude-code/fixture.py
+doc
+plugin
+.claude-plugin
+evals
+interfaces
+presets
+orgs
+*.md
+!README.md
+.DS_Store

chipgraph-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml,md}]
+indent_style = space
+indent_size = 2

chipgraph-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Default owner for everything in this repo.
+# Enforced via the main-protection ruleset (require_code_owner_review).
+# Org docs: quynhonsemiconductor/.github → docs/ORG-GOVERNANCE.md (the area-team model).
+
+* @quynhonsemiconductor/ai-leads

chipgraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - run: uv sync --locked
+
+      - run: uv run ruff check .
+
+      - run: uv run ruff format --check .
+
+      - run: uv run lint-imports
+
+      - run: uv run mypy
+
+      - run: uv run pytest
+
+      - run: make schemas-check
+
+  # The `edalize` sim adapter (M2-05) on Linux: Verilator from the OSS CAD Suite release
+  # docker/Dockerfile pins, the C++ build deps of a Verilator model and Icarus from apt,
+  # and the `sim` extra. Runs the sample cocotb testbench (examples/tinysoc/dv) and the
+  # failure cases through EdalizeTool with a real LocalRunner, and fails on any skip.
+  sim:
+    name: sim (cocotb, verilator + icarus, py${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.13", "3.14"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install OSS CAD Suite (the release docker/Dockerfile pins), for Verilator
+        run: |
+          set -euo pipefail
+          date="$(sed -n 's/^ARG OSS_CAD_SUITE_DATE=//p' docker/Dockerfile)"
+          sha256="$(sed -n 's/^ARG OSS_CAD_SUITE_SHA256_AMD64=//p' docker/Dockerfile)"
+          file="oss-cad-suite-linux-x64-${date//-/}.tgz"
+          url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/${date}/${file}"
+          curl -fsSL -o "$RUNNER_TEMP/oss-cad-suite.tgz" "$url"
+          echo "${sha256}  $RUNNER_TEMP/oss-cad-suite.tgz" | sha256sum -c -
+          tar -xzf "$RUNNER_TEMP/oss-cad-suite.tgz" -C "$RUNNER_TEMP"
+          rm -f "$RUNNER_TEMP/oss-cad-suite.tgz"
+          echo "$RUNNER_TEMP/oss-cad-suite/bin" >> "$GITHUB_PATH"
+
+      # g++: Verilator compiles the model; liblz4-dev/zlib1g-dev: its FST writer. Icarus
+      # from apt, ahead of the suite's on PATH: the suite's `vvp` wrapper loads the
+      # suite's own cocotb libgpi and no test runs (docs/spikes/S3.md, pitfall 4).
+      - name: Install the C++ build deps of a Verilator model, and Icarus from apt
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            g++ make liblz4-dev zlib1g-dev iverilog
+          mkdir -p "$RUNNER_TEMP/apt-icarus"
+          ln -sf /usr/bin/iverilog /usr/bin/vvp "$RUNNER_TEMP/apt-icarus/"
+          echo "$RUNNER_TEMP/apt-icarus" >> "$GITHUB_PATH"
+
+      - run: uv sync --locked --extra sim
+
+      - name: Tool versions
+        env:
+          PYTHON_VERSION: ${{ matrix.python }}
+        run: |
+          {
+            echo "### sim toolchain, py${PYTHON_VERSION}"
+            echo '```'
+            echo "verilator: $(verilator --version) ($(command -v verilator))"
+            echo "iverilog:  $(iverilog -V 2>&1 | head -n 1) ($(command -v vvp))"
+            echo "g++:       $(g++ --version | head -n 1)"
+            echo "python:    $(uv run --no-sync python --version)"
+            uv run --no-sync python -c 'import importlib.metadata as m; print("edalize:  ", m.version("edalize")); print("cocotb:   ", m.version("cocotb"))'
+            echo "cocotb-config: $(uv run --no-sync which cocotb-config)"
+            echo '```'
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Run the cocotb testbenches through EdalizeTool
+        run: >-
+          uv run --no-sync pytest -q
+          tests/e2e/test_sim_edalize.py tests/adapters/tool/test_edalize.py
+          tests/adapters/parser/test_cocotb.py
+          --junitxml="$RUNNER_TEMP/sim-junit.xml"
+
+      - name: Fail if a sim test was skipped
+        run: |
+          python3 - "$RUNNER_TEMP/sim-junit.xml" <<'PY'
+          import sys
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse(sys.argv[1]).getroot()
+          suite = root if root.tag == "testsuite" else root.find("testsuite")
+          tests, skipped = int(suite.get("tests", 0)), int(suite.get("skipped", 0))
+          print(f"tests={tests} skipped={skipped}")
+          if skipped or tests == 0:
+              raise SystemExit("sim tests were skipped: the toolchain or the `sim` extra is missing")
+          PY
+
+  secrets:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      # The org's shared scanner (gitleaks CLI, canary-checked before trusting a
+      # clean result), pinned like every other ci ref. Replaces the upstream
+      # trufflehog action this repo carried on its own.
+      - uses: quynhonsemiconductor/ci/actions/scan-secrets@956804ad4aa2dcf930909553d306d72b3708fd5d # v1.34.1+ci#308

chipgraph-0.1.0/.github/workflows/evals.yml

@@ -0,0 +1,132 @@
+name: evals
+
+# Real-model evals (task M1-17): `chipgraph eval` with runtime claude-code (headless
+# Claude Code, haiku main session by default) on the ask, triage, triage-holdout and
+# triage-holdout2 suites. Never on push or pull requests: started by hand or weekly. The
+# framework itself is checked on every PR by the fake-runtime tests in the normal CI
+# (tests/evals).
+#
+# Auth: the repository secret CHIPGRAPH_EVALS_CLAUDE_TOKEN, a Claude Code OAuth token of
+# a separate account (`claude setup-token`), passed to `claude` as
+# CLAUDE_CODE_OAUTH_TOKEN. Without the secret the job skips cleanly, green, with a
+# ::notice:: and a line in the run summary (owner decision 2026-11-04). There is no
+# schedule: this workflow runs by hand only, so a green skip can never read as a weekly
+# eval that passed.
+# Cost cap: --budget-usd per suite (claude's --max-budget-usd per sample, and the suite
+# stops once the summed total_cost_usd reaches it); --time-limit per suite.
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: Suite to run
+        type: choice
+        options: [all, ask, triage, triage-holdout, triage-holdout2]
+        default: all
+      main_model:
+        description: Main session model (workers stay on haiku)
+        type: string
+        default: sonnet
+      budget_usd:
+        description: Cost cap per suite, in USD
+        type: string
+        default: "3"
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+env:
+  CLAUDE_CODE_VERSION: 2.1.286
+
+jobs:
+  evals:
+    runs-on: ubuntu-latest
+    timeout-minutes: 240
+    steps:
+      - name: Check for the evals secret
+        id: auth
+        env:
+          TOKEN: ${{ secrets.CHIPGRAPH_EVALS_CLAUDE_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "ok=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ok=false" >> "$GITHUB_OUTPUT"
+            msg="CHIPGRAPH_EVALS_CLAUDE_TOKEN is not set: real-model evals skipped (see evals/README.md)."
+            echo "::notice::$msg"
+            echo "$msg" >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          python-version: "3.14"
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          node-version: "24"
+
+      - name: Install Claude Code
+        if: steps.auth.outputs.ok == 'true'
+        run: |
+          npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+          claude --version
+
+      - run: uv sync --locked
+        if: steps.auth.outputs.ok == 'true'
+
+      - name: Run the evals
+        id: run
+        if: steps.auth.outputs.ok == 'true'
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CHIPGRAPH_EVALS_CLAUDE_TOKEN }}
+          SUITE: ${{ inputs.suite || 'all' }}
+          MAIN_MODEL: ${{ inputs.main_model || 'sonnet' }}
+          BUDGET_USD: ${{ inputs.budget_usd || '3' }}
+          EVAL_OUT: ${{ runner.temp }}/eval-report
+        run: |
+          set -u
+          if [ "$SUITE" = all ]; then suites="ask triage triage-holdout triage-holdout2"; else suites="$SUITE"; fi
+          mkdir -p "$EVAL_OUT"
+          failed=""
+          for suite in $suites; do
+            echo "::group::chipgraph eval $suite"
+            rc=0
+            uv run chipgraph eval "$suite" --runtime claude-code \
+              --main-model "$MAIN_MODEL" --budget-usd "$BUDGET_USD" \
+              --out "$EVAL_OUT/$suite" || rc=$?
+            echo "::endgroup::"
+            if [ -f "$EVAL_OUT/$suite/summary.md" ]; then
+              cat "$EVAL_OUT/$suite/summary.md" >> "$GITHUB_STEP_SUMMARY"
+            else
+              echo "chipgraph eval $suite: no report (exit $rc)" >> "$GITHUB_STEP_SUMMARY"
+            fi
+            [ "$rc" -eq 0 ] || failed="$failed $suite"
+          done
+          echo "failed=$failed" >> "$GITHUB_OUTPUT"
+
+      - name: Upload the eval report
+        if: always() && steps.auth.outputs.ok == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: eval-report-${{ github.run_id }}
+          path: ${{ runner.temp }}/eval-report
+          if-no-files-found: error
+          retention-days: 90
+
+      - name: Fail if a suite failed
+        if: steps.auth.outputs.ok == 'true' && steps.run.outputs.failed != ''
+        env:
+          FAILED: ${{ steps.run.outputs.failed }}
+        run: |
+          echo "::error::eval suites failed:$FAILED"
+          exit 1

chipgraph-0.1.0/.github/workflows/image.yml

@@ -0,0 +1,194 @@
+name: image
+
+# zizmor 1.5.2 (the version the shared action installs) anchors cache-poisoning at
+# the workflow's trigger, not at the cache step, so the inline form on the build
+# actions does not cover it — CONFIRMED 2026-11-04 against a local 1.5.2 (two
+# findings, both image.yml:3:1). The risk is closed in the workflow instead: the
+# PR-running build job READS the GHA cache but never writes it (cache-to is
+# conditional on a push), and the job that writes and publishes runs only on
+# push/tag. OWNER RE-CHECK: when the shared action's pinned zizmor is raised to
+# >=1.30 (which reports nothing here), delete this ignore and confirm the check
+# still passes.
+on:  # zizmor: ignore[cache-poisoning]
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  IMAGE: ghcr.io/quynhonsemiconductor/chipgraph-eda
+
+jobs:
+  build-test:
+    name: build test image, run tinysoc e2e
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    outputs:
+      relevant: ${{ steps.changes.outputs.relevant }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 2 # the merge commit and both parents: enough to diff against the base
+
+      # The job always runs, so it can be a required check; when nothing the image is built
+      # from changed, every later step is skipped and the job still reports success.
+      - name: Decide whether the image is affected
+        id: changes
+        env:
+          EVENT: ${{ github.event_name }}
+          REF: ${{ github.ref }}
+          # Paths the test image is built from or tested with.
+          RELEVANT: '^(docker/|pyproject\.toml$|uv\.lock$|src/|tests/e2e/|examples/|docs/tb-claude-code/|\.dockerignore$|\.github/workflows/image\.yml$)'
+        run: |
+          set -eu
+          relevant=false
+          files=""
+          if [ "$EVENT" = push ] && [ "${REF#refs/tags/}" != "$REF" ]; then
+            relevant=true # a release tag always builds
+          elif ! files="$(git diff --name-only HEAD^1 HEAD)"; then
+            relevant=true # cannot tell: build
+          elif printf '%s\n' "$files" | grep -Eq "$RELEVANT"; then
+            relevant=true
+          fi
+          echo "relevant=$relevant" >> "$GITHUB_OUTPUT"
+          {
+            echo "### image job: relevant=$relevant"
+            echo '```'
+            printf '%s\n' "$files"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+        if: steps.changes.outputs.relevant == 'true'
+
+      # A pull request may READ the cache but never WRITE it: this job runs for
+      # PRs, and the trusted publish job below reuses the same scope. A cache
+      # entry a PR could plant would ride into the published image (zizmor
+      # cache-poisoning, the reason the write is conditional rather than ignored).
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        if: steps.changes.outputs.relevant == 'true'
+        with:
+          context: .
+          file: docker/Dockerfile
+          target: test
+          tags: chipgraph-eda:test
+          load: true
+          push: false
+          cache-from: type=gha
+          cache-to: ${{ github.event_name == 'push' && 'type=gha,mode=max' || '' }}
+
+      - name: Tool versions in the image
+        if: steps.changes.outputs.relevant == 'true'
+        run: |
+          set -o pipefail
+          {
+            echo "### chipgraph-eda:test toolchain"
+            echo '```'
+            docker run --rm chipgraph-eda:test sh -c '
+              echo "verilator: $(verilator --version) ($(command -v verilator))"
+              echo "iverilog:  $(iverilog -V 2>&1 | head -n 1) ($(command -v vvp))"
+              echo "g++:       $(g++ --version | head -n 1)"
+              echo "python:    $(uv run --no-sync python --version)"
+              uv run --no-sync python -c "import importlib.metadata as m; print(\"edalize:  \", m.version(\"edalize\")); print(\"cocotb:   \", m.version(\"cocotb\"))"
+            '
+            echo '```'
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Run the tinysoc e2e suite inside the image
+        if: steps.changes.outputs.relevant == 'true'
+        env:
+          REPORT_DIR: ${{ runner.temp }}/e2e-report
+        run: |
+          set -eu
+          mkdir -p "$REPORT_DIR"
+          docker run --rm \
+            -v "$REPORT_DIR:/tmp/report" \
+            chipgraph-eda:test \
+            sh -c 'uv run --no-sync pytest -m e2e tests/e2e -q --junitxml=/tmp/report/e2e-junit.xml'
+
+      - name: Fail if the e2e tests did not actually run
+        if: steps.changes.outputs.relevant == 'true'
+        env:
+          REPORT_DIR: ${{ runner.temp }}/e2e-report
+        run: |
+          python3 - "$REPORT_DIR/e2e-junit.xml" <<'PY'
+          import sys
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse(sys.argv[1]).getroot()
+          suite = root if root.tag == "testsuite" else root.find("testsuite")
+          if suite is None:
+              raise SystemExit("no <testsuite> found in the junit report")
+
+          tests = int(suite.get("tests", 0))
+          failures = int(suite.get("failures", 0))
+          errors = int(suite.get("errors", 0))
+          skipped = int(suite.get("skipped", 0))
+          passed = tests - failures - errors - skipped
+
+          print(f"tests={tests} passed={passed} failures={failures} errors={errors} skipped={skipped}")
+
+          if skipped:
+              raise SystemExit(
+                  f"{skipped} e2e test(s) were skipped inside the image "
+                  "(verilator/make missing?) — the image must run them, not skip them"
+              )
+          if failures or errors:
+              raise SystemExit("e2e tests failed inside the image")
+          if passed < 5:
+              raise SystemExit(f"expected at least 5 passing e2e tests, got {passed}")
+          PY
+
+  publish:
+    name: publish image to GHCR
+    needs: build-test
+    if: >-
+      needs.build-test.outputs.relevant == 'true' &&
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      packages: write # push chipgraph-eda to ghcr.io
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=raw,value=main,enable={{is_default_branch}}
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}}
+
+      - uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

chipgraph-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+# release-please — one package (python type, bumps pyproject.toml). Releases
+# need the owner's explicit "go release"; the release PR is never merged by CI.
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    uses: quynhonsemiconductor/ci/.github/workflows/release-please.yml@a346843f3ee1848d81ac93974d2a8d04a5ebe7ed # v1.34.6
+    secrets:
+      QNSC_AUTOMATION_PRIVATE_KEY: ${{ secrets.QNSC_AUTOMATION_PRIVATE_KEY }}

chipgraph-0.1.0/.github/workflows/release-uv-lock.yml

@@ -0,0 +1,77 @@
+# =============================================================================
+# Release Please · uv lock — keep uv.lock in step with the release version.
+#
+# release-please bumps pyproject.toml but has no uv.lock updater (upstream
+# googleapis/release-please#2561), so every release PR would fail the repo's
+# `uv sync --locked` jobs on a stale chipgraph version entry. This workflow
+# runs on release-please's own branches only, re-locks, and pushes the updated
+# uv.lock back to the release branch with the qnsc-automation App token — an
+# App-token push is what re-triggers the release PR's checks (the default
+# GITHUB_TOKEN push would leave the required checks stuck on the old head).
+# =============================================================================
+name: Release Please · uv lock
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: uv-lock-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  uv-lock:
+    name: sync uv.lock with the release version
+    # Only release-please's own branches; the App token step below fails loudly
+    # until the App is installed and the org secret granted (infra#489 owner steps).
+    if: startsWith(github.head_ref, 'release-please--branches--')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      # The push needs the branch itself (a pull_request checkout would be the
+      # merge ref) and full history to push back.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
+        id: app-token
+        with:
+          app-id: ${{ vars.QNSC_AUTOMATION_APP_ID }}
+          private-key: ${{ secrets.QNSC_AUTOMATION_PRIVATE_KEY }}
+          repositories: ${{ github.event.repository.name }}
+          permission-contents: write
+
+      # No GHA cache: the job re-locks only, and a PR-branch cache would be
+      # unreadable elsewhere and evict the entries main does use.
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          enable-cache: false
+
+      - name: Re-lock against the bumped pyproject.toml
+        run: uv lock
+
+      - name: Push the updated uv.lock to the release branch
+        env:
+          TOKEN: ${{ steps.app-token.outputs.token }}
+          BRANCH: ${{ github.head_ref }}
+        run: |
+          set -euo pipefail
+          if [ -z "$TOKEN" ]; then
+            echo "::error::no qnsc-automation App token — install the App on this repo and grant it the org secret QNSC_AUTOMATION_PRIVATE_KEY (owner steps in infra#489)"
+            exit 1
+          fi
+          if git diff --quiet uv.lock; then
+            echo "uv.lock already matches pyproject.toml"
+            exit 0
+          fi
+          git config user.name "qnsc-automation[bot]"
+          git config user.email "4166718+qnsc-automation[bot]@users.noreply.github.com"
+          git add uv.lock
+          git commit -m "chore: sync uv.lock with the release version"
+          git push "https://x-access-token:${TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:${BRANCH}"