Add breeze pr auto-triage command

Add a new Breeze CLI command that helps maintainers efficiently triage
open PRs from non-collaborators that don't meet minimum quality criteria.

The command fetches open PRs via GitHub GraphQL API with optimized chunked
queries, runs deterministic CI checks (failures, merge conflicts, missing
test workflows), optionally runs LLM-based quality assessment, and presents
flagged PRs interactively for maintainer review with author profiles and
contribution history.

Key features:
- Optimized GraphQL queries with chunking to avoid GitHub timeout errors
- Deterministic CI failure detection with categorized fix instructions
- LLM assessment via `claude` or `codex` CLI for content quality
- Interactive review with Rich panels, clickable links, and author context
- "maintainer-accepted" label to skip PRs on future runs
- Workflow approval support for first-time contributor PRs awaiting CI runs
- Merge conflict and commits-behind detection with rebase guidance

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: potiuk

contributing-docs/05_pull_requests.rst

@@ -1,4 +1,4 @@
-
+contributing-docs/05_pull_requests.rst
  .. Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
@@ -75,6 +75,15 @@ Pull Request guidelines
 Before you submit a Pull Request (PR) from your forked repo, check that it meets
 these guidelines:
 
+-   Start with **Draft**: Until you are sure that your PR passes all the quality checks and tests, keep it
+    in **Draft** status. This will signal to maintainers that the PR is not yet ready
+    for review and it will prevent maintainers from accidentally merging it before
+    it's ready. Once you are sure that your PR is ready for review, you can mark it as
+    "Ready for review" in the GitHub UI. Our regular check will convert all PRs from
+    non-collaborators that do not pass our quality gates to Draft status, so if you see
+    that your PR is in Draft status and you haven't set it to Draft. check the
+    comments to see what needs to be fixed.
+
 -   Include tests, either as doctests, unit tests, or both, to your pull request.
 
     The Airflow repo uses `GitHub Actions <https://help.github.com/en/actions>`_ to
@@ -147,6 +156,57 @@ these guidelines:
 -   Adhere to guidelines for commit messages described in this `article <https://cbea.ms/git-commit/>`_.
     This makes the lives of those who come after you (and your future self) a lot easier.
 
+.. _pull-request-quality-criteria:
+
+Pull Request quality criteria
+-----------------------------
+
+Every open PR must meet the following minimum quality criteria before maintainers will review it.
+PRs that do not meet these criteria may be automatically converted to **draft** status by project
+tooling, with a comment explaining what needs to be fixed.
+
+1. **Descriptive title** — The PR title must clearly describe the change.
+   Generic titles such as "Fix bug", "Update code", "Changes", single-word titles, or titles
+   that only reference an issue number (e.g. "Fixes #12345") do not meet this bar.
+
+2. **Meaningful description** — The PR body must contain a meaningful description of *what* the
+   PR does and *why*. An empty body, a body consisting only of the PR template
+   checkboxes/headers with no added text, or a body that merely repeats the title is not
+   sufficient.
+
+3. **Passing static checks** — The PR's static checks (pre-commit / ruff / mypy) must pass.
+   You can run them locally with ``prek run --ref-from main`` before pushing.
+
+4. **Gen-AI disclosure** — If the PR was created with the assistance of generative AI tools,
+   the description must include a disclosure (see `Gen-AI Assisted contributions`_ below).
+
+5. **Coherent changes** — The PR should contain related changes only. Completely unrelated
+   changes bundled together will be flagged.
+
+**What happens when a PR is converted to draft?**
+
+-  The comment informs you what you need to do.
+-  Fix each issue, then mark the PR as "Ready for review" in the GitHub UI - but only after making sure that all the issues are fixed.
+-  Maintainers will then proceed with a normal review.
+
+Converting a PR to draft is **not** a rejection — it is an invitation to bring the PR up to
+the project's standards so that maintainer review time is spent productively.
+
+**What happens when a PR is closed for quality violations?**
+
+If a contributor has more than 3 open PRs that are flagged for quality issues, maintainers may
+choose to **close** the PR instead of converting it to draft. Closed PRs receive the
+``closed because of multiple quality violations`` label and a comment listing the violations.
+Contributors are welcome to open a new PR that addresses the issues listed in the comment.
+
+**What happens when suspicious changes are detected?**
+
+When maintainers review a PR's diff before approving CI workflow runs and determine that it
+contains suspicious changes (e.g. attempts to exfiltrate secrets, modify CI pipelines
+maliciously, or inject harmful code), **all open PRs by the same author** will be closed
+and labeled ``suspicious changes detected``. A comment is posted on each PR explaining that
+the closure was triggered by suspicious changes found in the flagged PR.
+
 Gen-AI Assisted contributions
 -----------------------------
 

dev/breeze/doc/11_issues_tasks.rst

@@ -54,5 +54,5 @@ Example usage:
 
 -----
 
-Next step: Follow the `Advanced Breeze topics <12_advanced_breeze_topics.rst>`__ instructions to learn more
-about advanced Breeze topics and internals.
+Next step: Follow the `Pull request tasks <13_pr_tasks.rst>`__ instructions to learn how to
+manage GitHub pull requests with Breeze.

dev/breeze/doc/13_pr_tasks.rst

@@ -0,0 +1,112 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+Pull request tasks
+------------------
+
+There are Breeze commands that help maintainers manage GitHub pull requests for the Apache Airflow project.
+
+Those are all of the available PR commands:
+
+.. image:: ./images/output_pr.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/dev/breeze/doc/images/output_pr.svg
+  :width: 100%
+  :alt: Breeze PR commands
+
+Auto-triaging PRs
+"""""""""""""""""
+
+The ``breeze pr auto-triage`` command finds open PRs from non-collaborators that don't meet
+minimum quality criteria and lets maintainers take action on them interactively.
+
+.. image:: ./images/output_pr_auto-triage.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/dev/breeze/doc/images/output_pr_auto-triage.svg
+  :width: 100%
+  :alt: Breeze PR auto-triage
+
+The command works in several phases:
+
+1. **Fetch** — Fetches open, non-draft PRs via the GitHub GraphQL API.
+2. **Filter** — Skips collaborators, bot accounts (dependabot, renovate, github-actions),
+   and PRs already labeled ``ready for maintainer review``.
+3. **Assess** — Runs deterministic checks (CI failures, merge conflicts, missing test
+   workflows) and optionally LLM-based quality assessment (via ``claude`` or ``codex`` CLI).
+4. **Triage** — Presents flagged PRs grouped by author. For each PR the maintainer chooses
+   an action:
+
+   * **[D]raft** — Convert to draft and post a comment listing the violations (default for
+     most PRs).
+   * **[C]lose** — Close the PR, add the ``closed because of multiple quality violations``
+     label, and post a comment. This is the suggested default when the author has more than
+     3 flagged PRs.
+   * **[R]eady** — Add the ``ready for maintainer review`` label so the PR is skipped in
+     future runs.
+   * **[S]kip** — Take no action on this PR.
+   * **[Q]uit** — Stop processing.
+
+   The command computes a smart default action based on CI failures, merge conflicts, LLM
+   assessment, and the number of flagged PRs by the same author. In ``--dry-run`` mode the
+   default action is displayed without prompting.
+
+5. **Workflow approval** — PRs with no test workflows run are presented for workflow
+   approval. Before approving, the maintainer reviews the full PR diff to check for
+   suspicious changes (e.g. attempts to exfiltrate secrets or modify CI pipelines). If
+   suspicious changes are confirmed, **all open PRs by that author** are closed, labeled
+   ``suspicious changes detected``, and commented.
+
+Labels used by auto-triage
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command uses the following GitHub labels to track triage state:
+
+``ready for maintainer review``
+   Applied when a maintainer chooses the **[R]eady** action on a flagged PR. PRs with this
+   label are automatically skipped in future triage runs, indicating the maintainer has
+   reviewed the flags and considers the PR acceptable for review.
+
+``closed because of multiple quality violations``
+   Applied when a maintainer chooses the **[C]lose** action. This label marks PRs that were
+   closed because they did not meet quality criteria and the author had more than 3 flagged
+   PRs open at the time. A comment listing the violations is posted on the PR.
+
+``suspicious changes detected``
+   Applied when a maintainer identifies suspicious changes (e.g. secret exfiltration attempts,
+   malicious CI modifications) while reviewing a PR diff during the workflow approval phase.
+   When this label is applied, **all open PRs by the same author** are closed and labeled,
+   with a comment explaining the reason.
+
+These labels must exist in the GitHub repository before using the command. If a label is
+missing, the command will print a warning and skip the labeling step.
+
+Example usage:
+
+.. code-block:: bash
+
+     # Dry run to see which PRs would be flagged and what action would be taken
+     breeze pr auto-triage --dry-run
+
+     # Run with CI checks only (no LLM)
+     breeze pr auto-triage --check-mode ci
+
+     # Filter by label and author
+     breeze pr auto-triage --label area:core --author some-user
+
+     # Limit to 10 PRs
+     breeze pr auto-triage --max-num 10
+
+     # Verbose mode — show individual skip reasons during filtering
+     breeze pr auto-triage --verbose

dev/breeze/doc/README.rst

@@ -50,6 +50,7 @@ The following documents describe how to use the Breeze environment:
 * `Release management tasks <09_release_management_tasks.rst>`_ - describes how to use Breeze for release management tasks.
 * `UI tasks <10_ui_tasks.rst>`_ - describes how Breeze commands are used to support Apache Airflow project UI.
 * `Issues tasks <11_issues_tasks.rst>`_ - describes how Breeze commands are used to manage GitHub issues.
+* `Pull request tasks <13_pr_tasks.rst>`_ - describes how Breeze commands are used to manage GitHub pull requests.
 * `Advanced Breeze topics <12_advanced_breeze_topics.rst>`_ - describes advanced Breeze topics/internals of Breeze.
 
 You can also learn more context and Architecture Decisions taken when developing Breeze in the