apache · potiuk · Aug 26, 2026
@@ -95,7 +95,7 @@ jobs:
       - name: "Install Breeze"
         uses: ./.github/actions/breeze
       - name: "Run unit tests"
-        run: uv tool run --from apache-airflow-breeze pytest -n auto --color=yes
+        run: uv run --locked pytest -n auto --color=yes
         working-directory: ./dev/breeze/
   run-breeze-integration-tests:
     timeout-minutes: 120
@@ -122,7 +122,7 @@ jobs:
       - name: "Install hatch"
         run: uv tool install hatch
       - name: "Run integration tests"
-        run: uv tool run --from apache-airflow-breeze pytest -v --color=yes -m integration_tests
+        run: uv run --locked pytest -v --color=yes -m integration_tests
         working-directory: ./dev/breeze/
   tests-shared-distributions:
     timeout-minutes: 10

@@ -22,7 +22,7 @@ Don't spell out **Directed Acyclic Graph** except for historical context.
 
 - Install prek: `uv tool install prek`
 - Enable commit hooks: `prek install`
-- Install breeze shim (one-time, per machine): `scripts/tools/setup_breeze` — installs `~/.local/bin/breeze` that runs breeze via `uvx` from the current git worktree's `dev/breeze` (so each worktree, including ephemeral agent worktrees, gets its own breeze tied to its sources). See [ADR 0017](dev/breeze/doc/adr/0017-use-uvx-to-run-breeze-from-local-sources.md).
+- Install breeze shim (one-time, per machine): `scripts/tools/setup_breeze` — installs `~/.local/bin/breeze` that runs breeze via `uv run --locked` from the current git worktree's `dev/breeze`, with dependencies pinned by `dev/breeze/uv.lock` (so each worktree, including ephemeral agent worktrees, gets its own breeze tied to its sources). See [ADR 0017](dev/breeze/doc/adr/0017-use-uvx-to-run-breeze-from-local-sources.md).
 - **Never run pytest, python, or airflow commands directly on the host** — always use `breeze`.
 - Place temporary scripts in `dev/` (mounted as `/opt/airflow/dev/` inside Breeze).
 

diff --git a/contributing-docs/03_contributors_quick_start.rst b/contributing-docs/03_contributors_quick_start.rst
@@ -414,9 +414,10 @@ see in CI in your local environment.
    ``uv`` is the recommended general-purpose Python development environment for Airflow.
 
 2. Run ``./scripts/tools/setup_breeze`` in your checked-out repository. This installs a small shim
-   at ``~/.local/bin/breeze`` that runs Breeze via ``uvx`` from the current git worktree's
-   ``dev/breeze`` folder, so each worktree (including ephemeral ones used by coding agents) gets
-   its own Breeze tied to that worktree's sources. See
+   at ``~/.local/bin/breeze`` that runs Breeze via ``uv run --locked`` from the current git
+   worktree's ``dev/breeze`` folder, so each worktree (including ephemeral ones used by coding
+   agents) gets its own Breeze, tied to that worktree's sources and to the dependency versions
+   pinned in ``dev/breeze/uv.lock``. See
    `ADR 0017 <../dev/breeze/doc/adr/0017-use-uvx-to-run-breeze-from-local-sources.md>`_ for the
    rationale.
 

diff --git a/contributing-docs/quick-start-ide/contributors_quick_start_gitpod.rst b/contributing-docs/quick-start-ide/contributors_quick_start_gitpod.rst
@@ -65,8 +65,9 @@ the shim installer, which works the same in Gitpod as on a local machine:
    pip install uv
    ./scripts/tools/setup_breeze
 
-This installs ``~/.local/bin/breeze`` as a small shim that runs Breeze via ``uvx`` from the
-current git worktree's ``dev/breeze`` folder. See
+This installs ``~/.local/bin/breeze`` as a small shim that runs Breeze via ``uv run --locked``
+from the current git worktree's ``dev/breeze`` folder, with dependencies pinned by
+``dev/breeze/uv.lock``. See
 `ADR 0017 <../../dev/breeze/doc/adr/0017-use-uvx-to-run-breeze-from-local-sources.md>`_ for the
 rationale.
 

@@ -130,7 +130,8 @@ To test your changes locally, check out the `v2-11-test` branch. Breeze on Airfl
 not compatible with Airflow 2.11, so you need a Breeze that matches the branch you're on.
 
 If you installed Breeze via the recommended shim (`./scripts/tools/setup_breeze`), nothing extra
-is needed — the shim runs Breeze via `uvx` from the current git worktree's `dev/breeze`, so
+is needed — the shim runs Breeze via `uv run --locked` from the current git worktree's
+`dev/breeze`, so
 checking out a different branch (or using a separate git worktree) automatically picks up that
 branch's Breeze:
 

@@ -388,7 +388,7 @@ export AIRFLOW_REPO_ROOT=$(pwd)
 ```
 
 - Install `breeze` command (recommended — installs a shim at `~/.local/bin/breeze` that runs
-  breeze via `uvx` from the current git worktree's `dev/breeze`; see
+  breeze via `uv run --locked` from the current git worktree's `dev/breeze`; see
   [ADR 0017](breeze/doc/adr/0017-use-uvx-to-run-breeze-from-local-sources.md)):
 
 ```shell script

@@ -40,7 +40,8 @@ out, in [editable/development mode](https://packaging.python.org/en/latest/guide
 
 The recommended way to make `breeze` available is to install a small **shim script** at
 `~/.local/bin/breeze` that runs breeze from the `dev/breeze` folder of the *current* git
-worktree via `uvx`. This avoids a single global install and means each git worktree
+worktree via `uv run --locked`, with every dependency pinned by the committed
+`dev/breeze/uv.lock`. This avoids a single global install and means each git worktree
 (including ephemeral worktrees used by coding agents) gets its own breeze, tied to that
 worktree's sources. Because the shim is a real file on `PATH`, subprocesses (pre-commit
 hooks, CI scripts, dev tools) see it just like a `uv tool`-installed binary. See
@@ -84,12 +85,12 @@ else
     exit 1
 fi
 exec env AIRFLOW_ROOT_PATH="${breeze_root}" SKIP_BREEZE_SELF_UPGRADE_CHECK=1 \
-    uvx --from "${breeze_root}/dev/breeze" --quiet breeze "$@"
+    uv run --project "${breeze_root}/dev/breeze" --locked --quiet breeze "$@"
 ```
 
 Then `breeze` invoked from any Airflow checkout uses that checkout's source, and from
 anywhere else it uses `$AIRFLOW_REPO_ROOT` or the baked-in fallback. The first call in a
-fresh worktree pays a one-time `uvx` resolve/install; subsequent calls hit the cache.
+fresh worktree pays a one-time sync of `dev/breeze/.venv`; subsequent calls reuse it.
 
 The legacy global-install path (`uv tool install -e ./dev/breeze --force` or
 `pipx install -e ./dev/breeze --force`) still works for users who explicitly want a single

@@ -269,7 +269,8 @@ Set your working directory to the root of this cloned repository.
 
 The recommended way to make ``breeze`` available is to install a small **shim script** at
 ``~/.local/bin/breeze`` that runs breeze from the ``dev/breeze`` folder of the current git
-worktree via ``uvx``. This avoids a single global install and means each git worktree
+worktree via ``uv run --locked``, with every dependency pinned by the committed
+``dev/breeze/uv.lock``. This avoids a single global install and means each git worktree
 (including ephemeral worktrees used by coding agents) gets its own breeze, tied to that
 worktree's sources. Because the shim is a real file on ``PATH``, subprocesses (pre-commit
 hooks, CI scripts, dev tools) see it just like a ``uv tool``-installed binary. See
@@ -300,10 +301,10 @@ marks it executable. To do it manually, write this file to ``~/.local/bin/breeze
         exit 1
     fi
     exec env AIRFLOW_ROOT_PATH="${repo_root}" SKIP_BREEZE_SELF_UPGRADE_CHECK=1 \
-        uvx --from "${repo_root}/dev/breeze" --quiet breeze "$@"
+        uv run --project "${repo_root}/dev/breeze" --locked --quiet breeze "$@"
 
 Then ``breeze`` invoked from any Airflow checkout uses that checkout's source. The first call in
-a fresh worktree pays a one-time ``uvx`` resolve/install; subsequent calls hit the cache.
+a fresh worktree pays a one-time sync of ``dev/breeze/.venv``; subsequent calls reuse it.
 
 Alternative: legacy global install (``uv tool`` or ``pipx``)
 ------------------------------------------------------------

@@ -35,7 +35,7 @@ Date: 2024-11-11
 
 ## Status
 
-Superseded by [17. Use `uvx` to run breeze from local sources](0017-use-uvx-to-run-breeze-from-local-sources.md)
+Superseded by [17. Run breeze from the current worktree's locked sources](0017-use-uvx-to-run-breeze-from-local-sources.md)
 
 Supersedes [10. Use pipx to install breeze](0010-use-pipx-to-install-breeze.md)
 

@@ -21,17 +21,17 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
-- [17. Use `uvx` to run breeze from local sources](#17-use-uvx-to-run-breeze-from-local-sources)
+- [17. Run breeze from the current worktree's locked sources](#17-run-breeze-from-the-current-worktrees-locked-sources)
   - [Status](#status)
   - [Context](#context)
   - [Decision](#decision)
   - [Consequences](#consequences)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-# 17. Use `uvx` to run breeze from local sources
+# 17. Run breeze from the current worktree's locked sources
 
-Date: 2026-04-26
+Date: 2026-04-26 (amended 2026-08-26: dispatch moved from ``uvx`` to ``uv run --locked``)
 
 ## Status
 
@@ -65,12 +65,23 @@ Two patterns have made that single-install model awkward:
    the same ``~/.local/bin/breeze`` symlink, and an agent that does ``uv tool install
    --force`` to "fix" itself silently sabotages every other worktree on the machine.
 
-``uv`` ships a tool — ``uvx`` — that runs a command from a project directory in an
-ephemeral, cached environment without installing anything globally. ``uvx --from
-./dev/breeze breeze ...`` resolves dependencies once per ``pyproject.toml`` /``uv.lock``
-hash, caches the resulting environment, and reuses it on subsequent calls. The first
-call in a fresh worktree is slow (one resolve + install); every call after that is
-fast.
+``uv`` ships a way to run a command from a project directory without installing anything
+globally: ``uv run --project ./dev/breeze --locked breeze ...`` syncs that project's own
+environment (``dev/breeze/.venv``) to exactly what ``dev/breeze/uv.lock`` pins, then runs the
+command in it. The first call in a fresh worktree pays for the sync; every call after that
+reuses the environment.
+
+The ``--locked`` part matters as much as the per-worktree part. The two alternatives that
+install from a path — ``uvx --from ./dev/breeze`` and ``uv tool install -e ./dev/breeze`` —
+re-resolve breeze's requirements against the package index on every fresh environment and read
+neither ``dev/breeze/uv.lock`` nor the ``[tool.uv] exclude-newer`` buffer declared next to it
+(that setting governs project operations such as ``uv lock`` and ``uv sync`` only). Under those,
+the committed lock recorded nothing and an unrelated upstream release could change breeze with
+no commit in this repository. click 8.5.0 showed the cost: released on 2026-08-26, it added a
+``help`` field to ``click.Argument.to_info_dict()`` — the dict breeze hashes to detect command
+drift — so within the hour every CI job resolved the new click, every command taking a
+positional argument hashed differently from its committed value, and static checks went red on
+every open PR regardless of what it touched. The lock said click 8.4.2 throughout.
 
 That gives us a way to make ``breeze`` always run from the *current* worktree's source
 without ever touching a shared global install — but the dispatch mechanism has to be
@@ -87,9 +98,9 @@ The recommended way to run breeze is via a small **shim script** at
 ```shell
 #!/usr/bin/env bash
 # Apache Airflow breeze shim — managed by scripts/tools/setup_breeze (ADR 0017).
-# Runs breeze from the dev/breeze folder of the current git worktree via 'uvx',
-# so each worktree (e.g. parallel agentic runs) gets its own ephemerally-installed
-# breeze tied to that worktree's source.
+# Runs breeze from the dev/breeze folder of the current git worktree via 'uv run',
+# so each worktree (e.g. parallel agentic runs) gets its own environment tied to
+# that worktree's source, with dependencies resolved from dev/breeze/uv.lock.
 #
 # Resolution order for the Airflow sources breeze runs from:
 #   1. the current git worktree (per-worktree isolation — see above);
@@ -115,7 +126,7 @@ else
     exit 1
 fi
 exec env AIRFLOW_ROOT_PATH="${breeze_root}" SKIP_BREEZE_SELF_UPGRADE_CHECK=1 \
-    uvx --from "${breeze_root}/dev/breeze" --quiet breeze "$@"
+    uv run --project "${breeze_root}/dev/breeze" --locked --quiet breeze "$@"
 ```
 
 ``scripts/tools/setup_breeze`` writes this file (replacing any previous
@@ -128,20 +139,27 @@ The user-facing command stays the same — they still type ``breeze`` — but ea
 invocation:
 
 * resolves ``$(git rev-parse --show-toplevel)`` from the current working directory,
-* dispatches to ``uvx --from <that-worktree>/dev/breeze breeze``,
-* and therefore always runs the breeze code that belongs to that worktree.
+* dispatches to ``uv run --project <that-worktree>/dev/breeze --locked breeze``,
+* and therefore always runs the breeze code that belongs to that worktree, with the
+  dependencies that worktree's ``uv.lock`` pins.
 
 Because the shim is a real file on ``PATH`` (not a shell function), it is also
 visible to subprocesses — pre-commit hooks, CI scripts, dev tools, and anything
 else that does ``subprocess.run(["breeze", ...])`` will pick it up exactly like
 they picked up the old ``uv tool``-installed binary.
 
 The two ``env`` variables matter: ``AIRFLOW_ROOT_PATH`` short-circuits breeze's
-installation-source detection (which walks up from ``__file__`` and would
-otherwise misfire because ``__file__`` lives inside the uvx cache, not the
-source tree), and ``SKIP_BREEZE_SELF_UPGRADE_CHECK=1`` disables the "your
-install is older than your sources" nag — moot under uvx, which auto-rebuilds
-the env when ``pyproject.toml`` / ``uv.lock`` change.
+installation-source detection (which walks up from ``__file__`` and would otherwise
+misfire on installs that do not live in the source tree), and
+``SKIP_BREEZE_SELF_UPGRADE_CHECK=1`` disables the "your install is older than your
+sources" nag — moot here, since ``uv run`` re-syncs the environment whenever
+``pyproject.toml`` / ``uv.lock`` change and installs the sources as editable.
+
+CI installs breeze the same way: ``scripts/ci/install_breeze.sh`` runs
+``uv sync --project ./dev/breeze/ --locked`` and puts ``dev/breeze/.venv/bin`` on ``PATH``
+rather than installing a global ``uv tool``. Dependency upgrades reach breeze only through a
+change to ``dev/breeze/uv.lock`` — in practice the scheduled ``breeze ci upgrade`` PR, which
+regenerates the lock and the command-output files together, as one reviewable commit.
 
 ``uv tool install -e ./dev/breeze`` and ``pipx install -e ./dev/breeze`` remain
 supported as alternatives for users who explicitly want the old single-install
@@ -159,6 +177,10 @@ behaviour, but they are no longer the recommended path.
   checked out — not whatever was current the last time someone reinstalled.
   The "your installed breeze is older than your sources" warning class largely
   goes away.
+* **Reproducible dependencies.** Two checkouts of the same commit run breeze with the
+  same dependency versions, whatever the index served that day, so the command hashes
+  under ``dev/breeze/doc/images/`` are a property of the repository rather than of the
+  calendar — and the ``exclude-newer`` buffer around lock upgrades finally applies.
 * **Cheap setup in fresh worktrees.** Spinning up a new worktree (manually or
   via an agent) needs no extra install step; ``breeze`` works the moment
   ``cd`` lands in the tree.
@@ -175,11 +197,15 @@ behaviour, but they are no longer the recommended path.
 
 **Costs**
 
-* **First call in a new worktree is slow.** ``uvx`` has to resolve and install
-  breeze's dependencies the first time it sees a given ``pyproject.toml`` /
-  ``uv.lock``. Subsequent calls hit the cache and are fast.
+* **First call in a new worktree is slow.** ``uv run`` has to populate
+  ``dev/breeze/.venv`` (~275 MB, mostly hardlinked into the uv cache; ignored by both
+  ``.gitignore`` and ``.dockerignore``) the first time. Subsequent calls reuse it.
+* **A stale lock blocks breeze.** Editing ``dev/breeze/pyproject.toml`` without re-running
+  ``uv lock`` makes every breeze call fail until the lock is refreshed. The error names the
+  fix, and the alternative — silently running dependencies nobody recorded — is the failure
+  mode this dispatch removes.
 * **Adds a small bash startup overhead.** The shim is a tiny bash script that
-  runs ``git rev-parse`` and ``uvx`` for every invocation. Negligible at the
+  runs ``git rev-parse`` and ``uv run`` for every invocation. Negligible at the
   command line, but noticeable inside tight loops or shell completion that
   re-invokes ``breeze`` many times.
 * **Resolution is current-worktree-first, with two fallbacks.** ``breeze``

@@ -1 +1 @@
-43e56152396620517257cbcd0ce28ccd
+f941b35af1d912596b27d89d4863dd0a
@@ -1 +1 @@
-d23c74c8aa244d8b8cd55c9182049f10
+fc42909eb684d7821ff2a3575a7e1073
@@ -1 +1 @@
-3f40148d24cfcc454145bc9971902ead
+59daf613dc467f3f1f923bcf7d24eb88
@@ -1 +1 @@
-08e27060ce2c204f4a2b5b1d0c326c74
+0c19dd1538b155da498dd37640c9327e
@@ -1 +1 @@
-bcbd14d163c29520124a0049a1b084dd
+3ce1a62e91cffceefefd09619cb6eb52
@@ -1 +1 @@
-ba04bbdd68c6b991e906625178b3478f
+012f58c236bd03a3dd0a1578af2a4d85
@@ -1 +1 @@
-83f4fffcd60ffdf1711983ffa43a5eee
+81eeaa4e9ab9ab7ec358057d6e4e0968
@@ -1 +1 @@
-abc593ccc646cf825fab808db673a269
+bbff103f342a54b5f22b0a3577d3a632
@@ -1 +1 @@
-f75f1f3af7d1bc1e4b7cdd5fd1747ee9
+2b3987215e9ca3cf742199fba144c0e2
@@ -1 +1 @@
-912bce7922f7ce90391f7af648ac4636
+c9fae60d9f4e72e390a08d53366d20f9
@@ -1 +1 @@
-737cf1595fa7afd91a23ef79f46eff16
+7a1170264859cd3fc078681755907622
@@ -1 +1 @@
-d7ed9abca3180bd5a1648f95a2624413
+943b61b60f81476638e74ab0e5ba451e
@@ -1 +1 @@
-a2f42c9ae4c6b66967588bd5ab538031
+f95887aff9ae25fe203629e01c2fe25d
@@ -1 +1 @@
-3162d4ae447d02bdddf9d67590fb4134
+bc1e2c3d12063d93fa3f3605b4f42de1
@@ -1 +1 @@
-465b1fffb9a13eb9a97ffa2dcadd4c58
+4d7d540413a5955a51eaf7d035ff31bc
@@ -1 +1 @@
-ce0ed1333a3f38983043d4eb04f0bf1c
+0f0f937f1a0d86a58147723b1400b3ac
@@ -1 +1 @@
-ec8538954daf8fe21156a7ad72992e85
+465c7719885f58cdf5fc8bd0592ba7de
@@ -1 +1 @@
-b635f3eb5c8e04be0937b9e85dee856a
+b937b6a253ce2ab2cbabb9cd8b7369d4
@@ -1 +1 @@
-a94ab59178e740921f451bdc68bfb445
+57343f19b12400ac43ea8fc4b892ac99
@@ -1 +1 @@
-f08a2861a8c88397caa6ea8471819456
+1a68af03bc2f8fae0d46e4a2a2266eb0
@@ -1 +1 @@
-e850a14ddf66f700b2595d65d7511869
+d4841617ec2b8d96643f6695adcb68d6
@@ -1 +1 @@
-0278a7f8d4d43cf91efbaaae1368326e
+cfa0588bb3e466155cd793b4528ac28c
@@ -1 +1 @@
-b4b01862a54de30d7df835ee6f9150df
+3cdf6229fb227fdbf3f7b0524b4a7f75
@@ -1 +1 @@
-4c341666e70a017acd38edd879adb595
+e302335890458a12a28a52ed51b6337f
@@ -1 +1 @@
-f11826c57955e3a6bef2f3c95989cacc
+caf04a20ceb4b3a426e095860f8a800f
@@ -1 +1 @@
-2bbd90928e950df8cf78abd0aff50f0b
+3005f4343ce3d9c33960042d8d7e2d20
@@ -1 +1 @@
-ccda221c325794a1a29ff0b77159dbeb
+56f677845a9c84dbdc1131c51b9af83a
@@ -1 +1 @@
-2d18c088667df831820438a03ba9654a
+e89451fe0b493819e12e78316a070cee
@@ -1 +1 @@
-04af62df42438f286d861f3f1956e5e4
+e7f68555c25e802df53097e5e7558088
@@ -1 +1 @@
-43eb5774bbdef528e443613d1d8048d9
+02ba09ea9213ae046fe814563630054d
@@ -1 +1 @@
-fc0029baa8c28609f1e6972829465401
+1ab3cf1b8c5a5deb4181110bb41fb811
@@ -1 +1 @@
-776d6d9819a1351ff4f96f3884f9e039
+9372d4ac91f1f8aec84665bd5bbc7dc6
@@ -1 +1 @@
-64c20fc3168ebec7147f51be8e323040
+0d407ea088f01326dfc1104f12a3017d
@@ -1 +1 @@
-3a8636011e5f5d6090c61ec0433575e5
+0cdb967ba346e6663ac663acf599b5ae
@@ -1 +1 @@
-4d9236fb254edf6d1f6e8ec815b50223
+76d2a06163a1c3f4dbc54f2e4aa13ade
@@ -1 +1 @@
-7135479eff2be2409fad7759de789087
+58ecc16666e1b4f5c5572533e7ccc0a7
@@ -1 +1 @@
-07feb53b4eeacb942d45ad1a70dc8740
+109d8450ccc1fa74ebc2547ae2db41d5
@@ -1 +1 @@
-65b7b00a5792d185aee3628fdc2227de
+c4e8633fee01c127eb062f8ccfac1c5c
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		43e56152396620517257cbcd0ce28ccd
		f941b35af1d912596b27d89d4863dd0a
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		d23c74c8aa244d8b8cd55c9182049f10
		fc42909eb684d7821ff2a3575a7e1073
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		3f40148d24cfcc454145bc9971902ead
		59daf613dc467f3f1f923bcf7d24eb88
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		08e27060ce2c204f4a2b5b1d0c326c74
		0c19dd1538b155da498dd37640c9327e
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		bcbd14d163c29520124a0049a1b084dd
		3ce1a62e91cffceefefd09619cb6eb52
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		ba04bbdd68c6b991e906625178b3478f
		012f58c236bd03a3dd0a1578af2a4d85
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		83f4fffcd60ffdf1711983ffa43a5eee
		81eeaa4e9ab9ab7ec358057d6e4e0968
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		abc593ccc646cf825fab808db673a269
		bbff103f342a54b5f22b0a3577d3a632
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		f75f1f3af7d1bc1e4b7cdd5fd1747ee9
		2b3987215e9ca3cf742199fba144c0e2
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		912bce7922f7ce90391f7af648ac4636
		c9fae60d9f4e72e390a08d53366d20f9