Address review: guard hook names, use --from-ref by default, point agents at breeze verify

The manual-stage hook names in the mapping are now checked against
ci-amd.yml, so a renamed hook fails a test instead of going stale. The
default prek row uses --from-ref, the scope AGENTS.md recommends, and
--full keeps CI's --all-files form. Step 7 of the publish-changes skill,
the AGENTS.md commands block and the selective-checks doc now point at
breeze verify. All patches in the CLI tests use autospec.

Author: Andrushika

.agents/skills/airflow-publish-changes/SKILL.md

@@ -115,7 +115,7 @@ code review checklist in [`.github/instructions/code-review.instructions.md`](..
    and fix any failures. The skipped hooks start long-running local servers or provision the
    opt-in Codex environment rather than run checks that complete.
 6. Run relevant individual tests and confirm they pass.
-7. Find which tests to run for the changes with selective-checks and run those tests in parallel to confirm they pass and check for CI-specific issues.
+7. Run `breeze verify` and execute every command it lists. The list comes from the same selective-checks logic CI uses. `breeze verify --full` shows everything CI runs for the default matrix cell, including the full suite CI adds when a change touches CI tooling or dependency files. Confirm the commands pass and check for CI-specific issues.
 8. Check for security issues — no secrets, no injection vulnerabilities, no unsafe patterns.
 
 Before pushing, always rebase your branch onto the latest target branch (usually `main`)

AGENTS.md

@@ -54,6 +54,7 @@ Don't spell out **Directed Acyclic Graph** except for historical context.
 - **Run regular (fast) static checks:** `prek run --from-ref <target_branch> --stage pre-commit`
 - **Run manual (slower) checks:** `prek run --from-ref <target_branch> --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex` (the skipped hooks start long-running local servers or provision the opt-in Codex environment rather than run checks that complete)
 - **Build docs:** `breeze build-docs`
+- **List the local verification for your changes:** `breeze verify` (add `--full` for everything CI runs for the default matrix cell, `--json` for machine-readable output). It uses the same selective-checks logic as CI.
 - **Determine which tests to run based on changed files:** `breeze ci selective-check --commit-ref <commit_with_squashed_changes>`
 <!-- END generated-commands, please keep comment here to allow auto update -->
 

contributing-docs/08_static_code_checks.rst

@@ -236,6 +236,7 @@ To check other usage types of the pre-commit framework, see `Pre-commit website
      - "- **Run regular (fast) static checks:** `prek run --from-ref <target_branch> --stage pre-commit`"
      - "- **Run manual (slower) checks:** `prek run --from-ref <target_branch> --stage manual --skip compile-ui-assets-dev --skip view-skill-eval --skip run-skill-eval-codex` (the skipped hooks start long-running local servers or provision the opt-in Codex environment rather than run checks that complete)"
      - "- **Build docs:** `breeze build-docs`"
+     - "- **List the local verification for your changes:** `breeze verify` (add `--full` for everything CI runs for the default matrix cell, `--json` for machine-readable output). It uses the same selective-checks logic as CI."
      - "- **Determine which tests to run based on changed files:** `breeze ci selective-check --commit-ref <commit_with_squashed_changes>`"
 .. AGENT-SKILL-END
 

dev/breeze/doc/03_developer_tasks.rst

@@ -335,7 +335,8 @@ Each row says what kind of check it is, whether it runs on the host or needs Doc
 CI image (``breeze``), and the exact command. Jobs CI runs on every PR regardless of the change
 (breeze's own unit tests, the shared distributions) only show up with ``--full``. The translation
 check is never listed: CI runs it with ``|| true``, so it cannot fail a PR.
-Use ``--json`` for machine-readable output with the same fields.
+Use ``--json`` for machine-readable output with the same fields. The ``prek`` row uses
+``--from-ref`` by default, the scope AGENTS.md recommends; ``--full`` shows CI's ``--all-files`` form.
 
 When a change touches CI tooling or dependency files, selective checks make CI run the full suite.
 The default list leaves that expansion out and only shows what the changed files match themselves,

dev/breeze/doc/ci/04_selective_checks.md

@@ -50,6 +50,11 @@ contributors in case of simpler changes.
 > [`dev/breeze/src/airflow_breeze/utils/selective_checks.py`](../../src/airflow_breeze/utils/selective_checks.py).
 > When you change that file, **update this document in the same PR** so the behaviour and the
 > documentation stay in sync.
+>
+> `breeze verify` maps the `run_*` flags to local commands in
+> [`dev/breeze/src/airflow_breeze/utils/verification_plan.py`](../../src/airflow_breeze/utils/verification_plan.py).
+> Adding a `run_*` flag to `SelectiveChecks` also means classifying it there;
+> `dev/breeze/tests/test_verification_plan.py` fails until you do.
 
 ## Why selective checks exist (the optimisation goal)
 

dev/breeze/src/airflow_breeze/utils/verification_plan.py

@@ -84,11 +84,21 @@ class VerificationItem:
 )
 
 
-def build_prek_item(sc: SelectiveChecks, base_ref: str) -> VerificationItem:
+def build_prek_item(sc: SelectiveChecks, base_ref: str, *, full: bool) -> VerificationItem:
+    from_ref = f"prek run --from-ref {shlex.quote(base_ref)} --to-ref HEAD"
     if sc.basic_checks_only:
-        command = f"SKIP_BREEZE_PREK_HOOKS=true SKIP={sc.skip_prek_hooks} prek run --from-ref {shlex.quote(base_ref)} --to-ref HEAD"
-        return VerificationItem("prek", command, "host")
-    return VerificationItem("prek", f"SKIP={sc.skip_prek_hooks} prek run --all-files", "breeze")
+        return VerificationItem(
+            "prek", f"SKIP_BREEZE_PREK_HOOKS=true SKIP={sc.skip_prek_hooks} {from_ref}", "host"
+        )
+    # CI's static-checks job runs every file, because a non-basic change can affect hooks that
+    # read files outside the diff. Locally the diff is the practical scope, as AGENTS.md advises.
+    return VerificationItem(
+        "prek",
+        f"SKIP={sc.skip_prek_hooks} prek run --all-files"
+        if full
+        else f"SKIP={sc.skip_prek_hooks} {from_ref}",
+        "breeze",
+    )
 
 
 def build_unit_test_items(group: str, test_types_json: str | None) -> list[VerificationItem]:
@@ -125,7 +135,7 @@ def build_local_verification_plan(
     full_tests_needed: bool,
     full: bool = False,
 ) -> dict[str, Any]:
-    items = [build_prek_item(sc, base_ref)]
+    items = [build_prek_item(sc, base_ref, full=full)]
     if sc.run_unit_tests:
         items += build_unit_test_items("core", sc.core_test_types_list_as_strings_in_json)
     if not sc.skip_providers_tests:
@@ -142,14 +152,14 @@ def build_local_verification_plan(
         breeze_tests = VerificationItem("unit", "cd dev/breeze && uv run --locked pytest", "host")
         if breeze_tests not in items:
             items.append(breeze_tests)
-        dists = " ".join(sorted(json.loads(sc.shared_distributions_as_json)))
-        items.append(
-            VerificationItem(
-                "unit",
-                f"for d in {dists}; do (cd shared/$d && uv run --group dev pytest) || exit 1; done",
-                "host",
+        if dists := " ".join(sorted(json.loads(sc.shared_distributions_as_json))):
+            items.append(
+                VerificationItem(
+                    "unit",
+                    f"for d in {dists}; do (cd shared/$d && uv run --group dev pytest) || exit 1; done",
+                    "host",
+                )
             )
-        )
     return {
         "base_ref": base_ref,
         "default_python_version": sc.default_python_version,

dev/breeze/tests/test_verification_plan.py

@@ -18,6 +18,7 @@
 
 import inspect
 import json
+import re
 import shlex
 from functools import cached_property
 from unittest.mock import Mock
@@ -62,6 +63,7 @@ def _mock_selective_checks(**flags: object) -> Mock:
         setattr(sc, flag, False)
     sc.skip_providers_tests = True
     sc.skip_prek_hooks = "identity"
+    sc.shared_distributions_as_json = "[]"
     sc.default_python_version = DEFAULT_PYTHON_MAJOR_MINOR_VERSION
     for flag, value in flags.items():
         setattr(sc, flag, value)
@@ -75,16 +77,27 @@ def test_each_flag_maps_to_its_commands(flag: str):
     )
     commands = [item["command"] for item in result["items"]]
     assert commands == [
-        "SKIP=identity prek run --all-files",
+        "SKIP=identity prek run --from-ref main --to-ref HEAD",
         *(command for _, command, _ in FLAG_COMMANDS[flag]),
     ]
 
 
 @pytest.mark.parametrize(
-    ("basic_checks_only", "expected"),
+    ("basic_checks_only", "full", "expected"),
     [
-        (False, ("prek", "SKIP=identity prek run --all-files", "breeze")),
+        (False, False, ("prek", "SKIP=identity prek run --from-ref main --to-ref HEAD", "breeze")),
+        (False, True, ("prek", "SKIP=identity prek run --all-files", "breeze")),
         (
+            True,
+            False,
+            (
+                "prek",
+                "SKIP_BREEZE_PREK_HOOKS=true SKIP=identity prek run --from-ref main --to-ref HEAD",
+                "host",
+            ),
+        ),
+        (
+            True,
             True,
             (
                 "prek",
@@ -94,9 +107,15 @@ def test_each_flag_maps_to_its_commands(flag: str):
         ),
     ],
 )
-def test_prek_command_follows_basic_checks_only(basic_checks_only: bool, expected: tuple[str, str, str]):
+def test_prek_command_follows_basic_checks_only_and_full(
+    basic_checks_only: bool, full: bool, expected: tuple[str, str, str]
+):
     result = build_local_verification_plan(
-        _mock_selective_checks(basic_checks_only=basic_checks_only), (), "main", full_tests_needed=False
+        _mock_selective_checks(basic_checks_only=basic_checks_only),
+        (),
+        "main",
+        full_tests_needed=False,
+        full=full,
     )
     prek = result["items"][0]
     assert (prek["kind"], prek["command"], prek["runs_in"]) == expected
@@ -107,7 +126,7 @@ def test_docs_only_change_mirrors_the_ci_cell():
     sc = _selective_checks(files)
     result = build_local_verification_plan(sc, files, "main", full_tests_needed=False)
     assert [item["command"] for item in result["items"]] == [
-        f"SKIP={sc.skip_prek_hooks} prek run --all-files",
+        f"SKIP={sc.skip_prek_hooks} prek run --from-ref main --to-ref HEAD",
         "breeze build-docs apache-airflow",
     ]
 
@@ -225,8 +244,9 @@ def test_full_plan_adds_the_jobs_ci_runs_on_every_pr():
     sc = _selective_checks(files)
     lean = build_local_verification_plan(sc, files, "main", full_tests_needed=False)["items"]
     full = build_local_verification_plan(sc, files, "main", full_tests_needed=False, full=True)["items"]
-    assert [i["command"] for i in full] == [
-        *(i["command"] for i in lean),
+    assert full[0]["command"] == f"SKIP={sc.skip_prek_hooks} prek run --all-files"
+    assert [i["command"] for i in full[1:]] == [
+        *(i["command"] for i in lean[1:]),
         "cd dev/breeze && uv run --locked pytest",
         "for d in "
         + " ".join(sorted(json.loads(sc.shared_distributions_as_json)))
@@ -240,3 +260,16 @@ def test_full_plan_does_not_duplicate_breeze_tests_for_a_breeze_change():
         _selective_checks(files), files, "main", full_tests_needed=True, full=True
     )
     assert [i["command"] for i in full["items"]].count("cd dev/breeze && uv run --locked pytest") == 1
+
+
+def test_manual_stage_hooks_in_the_mapping_are_the_ones_ci_runs():
+    workflow = (AIRFLOW_ROOT_PATH / ".github" / "workflows" / "ci-amd.yml").read_text()
+    hooks = [
+        hook
+        for commands in FLAG_COMMANDS.values()
+        for _, command, _ in commands
+        for hook in re.findall(r"prek run --stage manual (\S+)", command)
+    ]
+    assert hooks
+    for hook in hooks:
+        assert f"--stage manual {hook} " in workflow, hook

dev/breeze/tests/test_verify_commands.py

@@ -31,6 +31,7 @@
 
 @patch(
     "airflow_breeze.commands.verify_commands.get_changed_files_against",
+    autospec=True,
     return_value=("airflow-core/docs/index.rst",),
 )
 def test_json_output_keeps_stdout_parseable(mock_files, monkeypatch):
@@ -55,6 +56,7 @@ def test_json_output_keeps_stdout_parseable(mock_files, monkeypatch):
 
 @patch(
     "airflow_breeze.commands.verify_commands.run_command",
+    autospec=True,
     return_value=CompletedProcess(
         args=[], returncode=128, stdout="", stderr="fatal: Not a valid object name"
     ),
@@ -68,6 +70,7 @@ def test_unknown_base_ref_is_a_clean_usage_error(mock_run):
 
 @patch(
     "airflow_breeze.commands.verify_commands.get_changed_files_against",
+    autospec=True,
     return_value=("airflow-core/docs/index.rst",),
 )
 def test_selective_checks_narration_is_hidden_unless_verbose(mock_files):
@@ -85,7 +88,9 @@ def test_selective_checks_narration_is_hidden_unless_verbose(mock_files):
     ],
 )
 def test_full_suite_expansion_is_explained(files: tuple[str, ...], expanded: bool):
-    with patch("airflow_breeze.commands.verify_commands.get_changed_files_against", return_value=files):
+    with patch(
+        "airflow_breeze.commands.verify_commands.get_changed_files_against", autospec=True, return_value=files
+    ):
         result = CliRunner().invoke(verify, [], catch_exceptions=False)
         full = CliRunner().invoke(verify, ["--full"], catch_exceptions=False)
     assert result.exit_code == 0
@@ -95,7 +100,7 @@ def test_full_suite_expansion_is_explained(files: tuple[str, ...], expanded: boo
     assert "breeze testing core-tests" not in " ".join(result.output.split())
 
 
-@patch("airflow_breeze.commands.verify_commands.run_command")
+@patch("airflow_breeze.commands.verify_commands.run_command", autospec=True)
 def test_changed_files_list_renames_like_ci_diff_tree(mock_run):
     mock_run.side_effect = [
         CompletedProcess(args=[], returncode=0, stdout="abc123\n", stderr=""),
@@ -108,11 +113,12 @@ def test_changed_files_list_renames_like_ci_diff_tree(mock_run):
 
 @patch(
     "airflow_breeze.commands.verify_commands.get_changed_files_against",
+    autospec=True,
     return_value=("airflow-core/docs/index.rst",),
 )
 def test_long_commands_are_folded_not_truncated(mock_files):
     result = CliRunner().invoke(verify, [], catch_exceptions=False)
     assert result.exit_code == 0
     assert "\u2026" not in result.output
     compact = re.sub(r"[\u2502\s]", "", result.output)
-    assert "update-uv-lockprekrun--all-files" in compact
+    assert "prekrun--from-refmain--to-refHEAD" in compact

dev/skill-evals/last-eval-hash.txt

@@ -1,3 +1,3 @@
 # Generated by dev/skill-evals/eval.py — do not edit or resolve conflicts by hand.
 # Run `prek run run-skill-eval --hook-stage manual --all-files` to regenerate.
-485f916101818db48c8311bd3e96770695e8681411e9c063a1ff05bc1d051d7c
+feffd0248dc326fd6bf082528de786a9770481947aadba9382ef1f1e3f8d8ee9