From 8ea475a3e86c8b69c07589c991da9f845f67b897 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Mon, 18 May 2026 23:10:18 +0200 Subject: [PATCH 1/3] Refresh apache-steward bootstrap to snapshot b20a3f2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-syncs .github/skills/setup-steward/ from the framework snapshot so future /setup-steward runs execute against the matching bootstrap. Highlights since the previous version: - New opt-in family `issue` (issue-fix-workflow, issue-triage, issue-reassess-stats) per apache-steward#209. - Newly-introduced opt-in families now auto-add on upgrade and write back to the committed lock (no prompt). - pr-management-triage pre-classification + pr-management-stats predicate refinements. - Smaller fixes (license-header criteria, --body= variant parsing). The committed pin (.apache-steward.lock) is unchanged — still tracks main. Contributors run /setup-steward upgrade to align their local snapshot. Files retain duplicate SPDX headers (LICENSE-2.0 from this repo's prek hook, release-policy.html from the framework's own header). Both URLs are valid Apache license pointers; unifying the form belongs upstream in apache-steward. --- .github/skills/setup-steward/SKILL.md | 6 +-- .github/skills/setup-steward/adopt.md | 42 ++++++++++++------- .github/skills/setup-steward/conventions.md | 3 ++ .github/skills/setup-steward/overrides.md | 3 ++ .github/skills/setup-steward/unadopt.md | 3 ++ .github/skills/setup-steward/upgrade.md | 40 +++++++++++++++++- .github/skills/setup-steward/verify.md | 9 ++-- .github/skills/setup-steward/worktree-init.md | 3 ++ 8 files changed, 86 insertions(+), 23 deletions(-) diff --git a/.github/skills/setup-steward/SKILL.md b/.github/skills/setup-steward/SKILL.md index 266caf8d2f47b..f821f89b71e37 100644 --- a/.github/skills/setup-steward/SKILL.md +++ b/.github/skills/setup-steward/SKILL.md @@ -53,7 +53,7 @@ license: Apache-2.0 This skill is **the only framework artefact an adopter project commits**. Every other apache-steward skill (security, -pr-management) is a gitignored symlink into the gitignored +pr-management, issue) is a gitignored symlink into the gitignored snapshot at `` that this skill manages. The adoption model is **snapshot + agentic overrides + drift- @@ -262,7 +262,7 @@ These two families are not exposed in the `skill-families:` prompt and not stored as user-selectable in the lock files; every sub-action that wires symlinks always covers them in addition to the user's opt-in family picks (`security`, -`pr-management`). Dropping them is *not* a supported +`pr-management`, `issue`). Dropping them is *not* a supported configuration — the secure-setup and discovery flows the framework ships depend on those skills being callable. @@ -332,7 +332,7 @@ first, then continue. |---|---| | `from:` / `from:` | Adopt or upgrade from a specific framework ref or version. Used during `adopt` (overrides the user prompt) and `upgrade` (overrides the committed lock for *this run only* — does NOT update the committed lock). | | `method:` | Pick the install method explicitly. Default during `adopt`: prompt the user. | -| `skill-families:` | Comma-separated **opt-in** families to symlink (`security`, `pr-management`). Default on `adopt`: prompt. Default on `upgrade`: read the families list from `` / `` and **ensure every framework skill in those families has a valid symlink** — create or repair missing / broken symlinks, not just add new ones. The flag never accepts the always-on families (`setup-*` minus `setup-steward` itself, and `list-steward-*`); per [Golden rule 8](#golden-rules) those are wired up unconditionally on every run and there is no way to ask for them or opt out. | +| `skill-families:` | Comma-separated **opt-in** families to symlink (`security`, `pr-management`, `issue`). Default on `adopt`: prompt. Default on `upgrade`: read the families list from `` / ``, **auto-include any opt-in family the framework has introduced since the lock was written** (recorded back into the lock), and **ensure every framework skill in the effective family set has a valid symlink** — create or repair missing / broken symlinks, not just add new ones. The flag never accepts the always-on families (`setup-*` minus `setup-steward` itself, and `list-steward-*`); per [Golden rule 8](#golden-rules) those are wired up unconditionally on every run and there is no way to ask for them or opt out. | | `--purge-overrides` | *(unadopt only)* Also `git rm -r` `.apache-steward-overrides/`. Default: preserve. | | `dry-run` | Show what the skill would do without writing anything. | diff --git a/.github/skills/setup-steward/adopt.md b/.github/skills/setup-steward/adopt.md index bba98609e5923..cc0ebd345291f 100644 --- a/.github/skills/setup-steward/adopt.md +++ b/.github/skills/setup-steward/adopt.md @@ -1,6 +1,9 @@ + + # adopt — first-time install of apache-steward into an adopter repo The default sub-action when the user says "adopt apache-steward". @@ -37,9 +40,9 @@ between automatically: (overrides the prompt). - `skill-families:` — comma-separated **opt-in** families to symlink (default: prompt). Valid values: - `security`, `pr-management`. The flag does **not** accept - the always-on families (`setup-*` minus `setup-steward` - itself, and `list-steward-*`); per + `security`, `pr-management`, `issue`. The flag does **not** + accept the always-on families (`setup-*` minus + `setup-steward` itself, and `list-steward-*`); per [`SKILL.md` Golden rule 8](SKILL.md#golden-rules) those are wired up unconditionally on every adopt run and the user is never asked about them. @@ -137,7 +140,7 @@ fetch — the recipe ran first and left the snapshot in place. After the fetch (or skip), confirm `/.claude/skills/` lists the framework skills -(`pr-management-*`, `security-*`, `setup-*`, +(`pr-management-*`, `security-*`, `issue-*`, `setup-*`, `list-steward-*`). If not, the fetch produced an unexpected layout — surface and stop. @@ -241,17 +244,24 @@ for the opt-in set. Otherwise prompt the user with: has a security tracker. - **`pr-management`** — five skills for maintainer-facing PR queue work. +- **`issue`** — five skills for general-issue tracker work + (triage, reassess, reproducer, fix-workflow, stats). + Maintainer-only; for projects with a general-issue tracker + (JIRA, GitHub Issues, Bugzilla, GitLab Issues) that is + *not* the security tracker. See + [`docs/issue-management/README.md`](../../../docs/issue-management/README.md). **Prefer structured Q&A.** When the agent harness offers a structured-question tool, use a *multi-select* prompt for -the two opt-in families (`security`, `pr-management`) — the -families are not mutually exclusive. Pre-select whichever -family the user named in their initial "adopt" request (e.g. -*"adopt apache-steward for PR triage"* → `pr-management` -pre-selected; the user can also tick `security`). If the -user named no family, default to selecting both for an -adopter that is a maintainer-driven repo, or to no -pre-selection otherwise. Free-form chat is the fallback. +the three opt-in families (`security`, `pr-management`, +`issue`) — the families are not mutually exclusive. +Pre-select whichever family the user named in their initial +"adopt" request (e.g. *"adopt apache-steward for PR triage"* +→ `pr-management` pre-selected; the user can also tick the +others). If the user named no family, default to selecting +all three for an adopter that is a maintainer-driven repo, +or to no pre-selection otherwise. Free-form chat is the +fallback. Do **not** offer `setup-*` or `list-steward-*` as selectable options in the prompt — they are wired up @@ -283,12 +293,14 @@ idempotent — re-add them if they're missing. /.claude/settings.local.json /.claude/skills/security-* /.claude/skills/pr-management-* +/.claude/skills/issue-* /.claude/skills/setup-isolated-setup-* /.claude/skills/setup-override-upstream /.claude/skills/setup-shared-config-sync /.claude/skills/list-steward-* /.github/skills/security-* /.github/skills/pr-management-* +/.github/skills/issue-* /.github/skills/setup-isolated-setup-* /.github/skills/setup-override-upstream /.github/skills/setup-shared-config-sync @@ -325,9 +337,9 @@ relative path into The set of skills to link is the **union** of: 1. **The opt-in families the user picked in Step 5** - (`security`, `pr-management`, or both). Each contributes - every framework skill in the snapshot whose name starts - with that family's prefix. + (`security`, `pr-management`, `issue`, or any + combination). Each contributes every framework skill in + the snapshot whose name starts with that family's prefix. 2. **The always-on families** (no user input — per [`SKILL.md` Golden rule 8](SKILL.md#golden-rules)): every `setup-*` skill *except* `setup-steward` itself, diff --git a/.github/skills/setup-steward/conventions.md b/.github/skills/setup-steward/conventions.md index 723f65eb6c5f1..177653e847a21 100644 --- a/.github/skills/setup-steward/conventions.md +++ b/.github/skills/setup-steward/conventions.md @@ -1,6 +1,9 @@ + + # conventions — auto-detect the adopter's skills-dir layout Different ASF projects already organise their `.claude/skills/` diff --git a/.github/skills/setup-steward/overrides.md b/.github/skills/setup-steward/overrides.md index 1d473b33219da..79f7c6943988f 100644 --- a/.github/skills/setup-steward/overrides.md +++ b/.github/skills/setup-steward/overrides.md @@ -1,6 +1,9 @@ + + # overrides — manage agentic overrides for framework skills The agentic-overrides mechanism is the framework's answer to diff --git a/.github/skills/setup-steward/unadopt.md b/.github/skills/setup-steward/unadopt.md index 06d801461f0f7..28dcafecf52ea 100644 --- a/.github/skills/setup-steward/unadopt.md +++ b/.github/skills/setup-steward/unadopt.md @@ -1,6 +1,9 @@ + + # unadopt — remove the apache-steward framework from an adopter repo The reverse of [`adopt.md`](adopt.md). Removes the framework diff --git a/.github/skills/setup-steward/upgrade.md b/.github/skills/setup-steward/upgrade.md index 8d2e06aa2b7f4..259b50d7e2e0b 100644 --- a/.github/skills/setup-steward/upgrade.md +++ b/.github/skills/setup-steward/upgrade.md @@ -1,6 +1,9 @@ + + # upgrade — refresh the gitignored snapshot per the committed lock The upgrade flow is **drift-driven**. It detects mismatch @@ -226,7 +229,22 @@ silent on families). Compose the **effective family set** for this upgrade as: - **Opt-in families** the project recorded (`security`, - `pr-management`, or both). + `pr-management`, `issue`, or any combination). +- **Newly-introduced opt-in families** — families the + framework now ships that did not exist when the lock was + written. Detect by enumerating the prefixes of opt-in + families in the snapshot (`security-*`, `pr-management-*`, + `issue-*`) and comparing against the lock's recorded set. + Any family present in the snapshot but absent from the + lock is auto-added to the effective set on this run, and + the addition is **written back to ``** + (same fields as + [`adopt.md` Step 4](adopt.md#step-4--write-committed-lock-fresh-only)). + Surface the added family in the upgrade summary so the + operator sees it; do not prompt — per the framework's + policy each opt-in family is maintainer-grade and an + adopter that has already adopted the framework is in scope + for any opt-in family the framework grows. - **Always-on families** (always added — never read from the lock, never user-configurable, per [`SKILL.md` Golden rule 8](SKILL.md#golden-rules)): @@ -239,6 +257,18 @@ on disk — it expands automatically when the framework adds a new `setup-*` or `list-steward-*` skill in a release, and contracts on a rename / removal without code changes here. +Before creating symlinks for a newly-introduced opt-in +family, reconcile the adopter's `.gitignore` so the new +family's snapshot symlinks are gitignored. Append the +`.gitignore` lines from +[`adopt.md` Step 7](adopt.md#step-7--gitignore-entries-fresh-only) +for the new family's prefix (e.g. `/.claude/skills/issue-*` +and the `.github/skills/` mirror when the adopter uses the +double-symlinked convention). The append is idempotent — +skip lines that already exist. The same idempotence covers +adopters whose `.gitignore` already had the entries (e.g. +from a manually-edited block or a previous adopt run). + The post-upgrade state must be: *every framework skill in the new snapshot that belongs to the effective family set has a valid symlink in ``*, and *no @@ -441,7 +471,8 @@ setup-steward (bootstrap): ✓ in sync OR ↻ overwritten from snapshot (reloaded in-flight) Symlinks (main checkout): - Opt-in families: , (from lock) + Opt-in families: , , (from lock) + Newly added opt-in: (introduced since lock was written; lock updated) Always-on families: setup-*, list-steward-* (per Golden rule 8) ✓ + - +.gitignore reconcile: + ✓ all opt-in family prefixes already gitignored OR + + -* and /.github/skills/-* + lines appended for newly-introduced opt-in families> + Hooks + local config: ✓ ↻ diff --git a/.github/skills/setup-steward/verify.md b/.github/skills/setup-steward/verify.md index b43d0ac4d3d09..f08264e5627dd 100644 --- a/.github/skills/setup-steward/verify.md +++ b/.github/skills/setup-steward/verify.md @@ -1,6 +1,9 @@ + + # verify — health check of the steward integration + drift detection Confirms the framework is wired in correctly so the rest of @@ -115,9 +118,9 @@ Check that the entries from Recommended: - The framework-skill symlink patterns (`security-*`, - `pr-management-*`, `setup-isolated-setup-*`, - `setup-shared-config-sync`) under both `.claude/skills/` - and `.github/skills/` per convention. + `pr-management-*`, `issue-*`, `setup-isolated-setup-*`, + `setup-shared-config-sync`, `list-steward-*`) under both + `.claude/skills/` and `.github/skills/` per convention. - ✗ if `/.apache-steward/` is not gitignored — the snapshot is at risk of being accidentally committed. diff --git a/.github/skills/setup-steward/worktree-init.md b/.github/skills/setup-steward/worktree-init.md index 164a9d9736e79..53432b4d8dbd0 100644 --- a/.github/skills/setup-steward/worktree-init.md +++ b/.github/skills/setup-steward/worktree-init.md @@ -1,6 +1,9 @@ + + # worktree-init — share the main checkout's snapshot from a worktree `adopt` and `upgrade` are **main-checkout-only**. A new git From 453fe90fd43deb2ee0bb32b8553c5b869e0f012e Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Tue, 19 May 2026 01:13:45 +0200 Subject: [PATCH 2/3] Drop @-ping of reviewer in author-primary triage templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a `` placeholder (backtick-quoted login, no @) for templates whose only addressee is the PR author: `request-author-confirmation`, `reviewer-ping` (author-primary), `review-nudge` (author-primary). The reviewer is still mentioned for context but no longer @-pinged when the next action is on the contributor. Also updates these templates to instruct the author to mark threads as resolved and ping the reviewer when they believe the feedback is addressed — making the resolve + handback step explicit instead of relying on the queue label alone. This is a local override; will follow up with a PR to apache/airflow-steward to make the policy framework-wide. --- .../pr-management-triage-comment-templates.md | 47 ++++++++++++++++++- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/.apache-steward-overrides/pr-management-triage-comment-templates.md b/.apache-steward-overrides/pr-management-triage-comment-templates.md index 6c2d1432591fd..a8271e9796767 100644 --- a/.apache-steward-overrides/pr-management-triage-comment-templates.md +++ b/.apache-steward-overrides/pr-management-triage-comment-templates.md @@ -97,6 +97,30 @@ rationale). _Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this [two-stage triage process](https://github.com/apache/airflow/blob/main/contributing-docs/25_maintainer_pr_triage.md#why-the-first-pass-is-automated) so that our maintainers' limited time is spent where it matters most: the conversation with you._ ``` +## Reviewer-mention policy in author-primary templates + +When a comment's only addressee is the PR author (the +`request-author-confirmation`, `reviewer-ping` author-primary, +and `review-nudge` author-primary templates), the body references +the reviewer **without** `@`-mentioning them. The framework's +default `` placeholder renders as `@login` and is +appropriate when the reviewer is one of the message's addressees +(e.g. the reviewer-re-review variants). In author-primary +templates we use a different placeholder, ``, +that renders the same set of GitHub logins **as +backtick-quoted code** (e.g. `` `phanikumv` ``, +`` `phanikumv`, `eladkal` ``) — recognisable as a GitHub +handle without producing a notification. + +The policy: reviewer is mentioned for context; an `@`-ping is +only appropriate when the reviewer is the next person whose +action we are asking for. + +| Placeholder | Renders as | Use in | +|---|---|---| +| `` | `@login [, @login ...]` (framework default) | reviewer-re-review variants, `mark-ready-with-ping` | +| `` | `` `login` [, `login` ...] `` (backtick-quoted, no `@`) | `request-author-confirmation`, `reviewer-ping` (author-primary), `review-nudge` (author-primary) | + ## Template bodies The framework's [`comment-templates.md`](../../.claude/skills/pr-management-triage/comment-templates.md) @@ -148,7 +172,7 @@ This is **not** a rejection — you're welcome to open a new PR addressing the i ### `review-nudge` (author-primary) ```markdown -@ — This PR has new commits since the last review requesting changes from . Could you address the outstanding review comments and either push a fix or reply in each thread explaining why the feedback doesn't apply? Once the threads are resolved please mark the PR as "Ready for review" and re-request review. Thanks! +@ — This PR has new commits since the last review requesting changes from . Could you address the outstanding review comments and either push a fix or reply in each thread explaining why the feedback doesn't apply? Once the threads are resolved please mark the PR as "Ready for review" and re-request review. Thanks! ``` @@ -164,11 +188,30 @@ This is **not** a rejection — you're welcome to open a new PR addressing the i ### `reviewer-ping` (author-primary) ```markdown -@ — There are unresolved review thread(s) on this PR from . Could you either push a fix or reply in each thread explaining why the feedback doesn't apply? Once you believe the feedback is addressed, mark the thread as resolved so the reviewer isn't re-pinged needlessly. Thanks! +@ — There are unresolved review thread(s) on this PR from . Could you either push a fix or reply in each thread explaining why the feedback doesn't apply? When you believe the feedback is addressed, please mark the threads as resolved and ping the reviewer () for a final look. Thanks! + + +``` + +### `request-author-confirmation` + +```markdown +@ — There are unresolved review thread(s) on this PR from , and you have engaged with each one (post-review commits and/or in-thread replies). Could you confirm whether you believe the feedback is fully addressed and the PR is ready for maintainer review confirmation? + +If yes, please mark the thread(s) as resolved and ping the reviewer () for a final look. They will either label the PR ready for maintainer review or follow up with additional feedback. + +If you are still working on a thread, please reply with what is outstanding so the threads stay unresolved on purpose. ``` +The literal marker string `ready for maintainer review confirmation` +appears in the first paragraph verbatim — the framework's +[`viewer_confirmation_request_present`](../../.claude/skills/pr-management-triage/classify-and-act.md#viewer_confirmation_request_present) +precondition searches for that exact text on subsequent sweeps; +do not edit the wording around it in a way that breaks the +case-sensitive substring match. + ### `reviewer-ping` (reviewer-re-review) ```markdown From b9eb9c46c7c2d4c6ce21c950c1a5fc72573fcdb3 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Tue, 19 May 2026 04:47:04 +0200 Subject: [PATCH 3/3] =?UTF-8?q?Drop=20redundant=20author-primary=20templat?= =?UTF-8?q?e=20overrides=20=E2=80=94=20now=20framework=20default?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After apache-steward#226 merged (upstream PR upstreaming the `` placeholder, the resolve-and-ping pattern in `request-author-confirmation` / `reviewer-ping` author-primary / `review-nudge` author-primary, and the Reviewer-mention policy section), this override file's matching sections are redundant — the framework now ships them by default. Dropped: - Reviewer-mention policy section (framework ships in comment-templates.md) - `review-nudge` (author-primary) template body - `reviewer-ping` (author-primary) template body - `request-author-confirmation` template body + post-note Kept (all Airflow-specific): - Project-specific URLs (apache/airflow contributing-docs links) - Quality-criteria marker string - AI-attribution footer (Apache Airflow branded) - All templates referencing airflow URLs (draft, comment-only, close, stale-draft-close, inactive-to-draft, suspicious-changes, etc.) and the reviewer-re-review variants / mark-ready-with-ping File shrinks 279 → 220 lines. --- .../pr-management-triage-comment-templates.md | 59 ------------------- 1 file changed, 59 deletions(-) diff --git a/.apache-steward-overrides/pr-management-triage-comment-templates.md b/.apache-steward-overrides/pr-management-triage-comment-templates.md index a8271e9796767..48c27fe045d13 100644 --- a/.apache-steward-overrides/pr-management-triage-comment-templates.md +++ b/.apache-steward-overrides/pr-management-triage-comment-templates.md @@ -97,30 +97,6 @@ rationale). _Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this [two-stage triage process](https://github.com/apache/airflow/blob/main/contributing-docs/25_maintainer_pr_triage.md#why-the-first-pass-is-automated) so that our maintainers' limited time is spent where it matters most: the conversation with you._ ``` -## Reviewer-mention policy in author-primary templates - -When a comment's only addressee is the PR author (the -`request-author-confirmation`, `reviewer-ping` author-primary, -and `review-nudge` author-primary templates), the body references -the reviewer **without** `@`-mentioning them. The framework's -default `` placeholder renders as `@login` and is -appropriate when the reviewer is one of the message's addressees -(e.g. the reviewer-re-review variants). In author-primary -templates we use a different placeholder, ``, -that renders the same set of GitHub logins **as -backtick-quoted code** (e.g. `` `phanikumv` ``, -`` `phanikumv`, `eladkal` ``) — recognisable as a GitHub -handle without producing a notification. - -The policy: reviewer is mentioned for context; an `@`-ping is -only appropriate when the reviewer is the next person whose -action we are asking for. - -| Placeholder | Renders as | Use in | -|---|---|---| -| `` | `@login [, @login ...]` (framework default) | reviewer-re-review variants, `mark-ready-with-ping` | -| `` | `` `login` [, `login` ...] `` (backtick-quoted, no `@`) | `request-author-confirmation`, `reviewer-ping` (author-primary), `review-nudge` (author-primary) | - ## Template bodies The framework's [`comment-templates.md`](../../.claude/skills/pr-management-triage/comment-templates.md) @@ -169,14 +145,6 @@ This is **not** a rejection — you're welcome to open a new PR addressing the i ``` -### `review-nudge` (author-primary) - -```markdown -@ — This PR has new commits since the last review requesting changes from . Could you address the outstanding review comments and either push a fix or reply in each thread explaining why the feedback doesn't apply? Once the threads are resolved please mark the PR as "Ready for review" and re-request review. Thanks! - - -``` - ### `review-nudge` (reviewer-re-review) ```markdown @@ -185,33 +153,6 @@ This is **not** a rejection — you're welcome to open a new PR addressing the i ``` -### `reviewer-ping` (author-primary) - -```markdown -@ — There are unresolved review thread(s) on this PR from . Could you either push a fix or reply in each thread explaining why the feedback doesn't apply? When you believe the feedback is addressed, please mark the threads as resolved and ping the reviewer () for a final look. Thanks! - - -``` - -### `request-author-confirmation` - -```markdown -@ — There are unresolved review thread(s) on this PR from , and you have engaged with each one (post-review commits and/or in-thread replies). Could you confirm whether you believe the feedback is fully addressed and the PR is ready for maintainer review confirmation? - -If yes, please mark the thread(s) as resolved and ping the reviewer () for a final look. They will either label the PR ready for maintainer review or follow up with additional feedback. - -If you are still working on a thread, please reply with what is outstanding so the threads stay unresolved on purpose. - - -``` - -The literal marker string `ready for maintainer review confirmation` -appears in the first paragraph verbatim — the framework's -[`viewer_confirmation_request_present`](../../.claude/skills/pr-management-triage/classify-and-act.md#viewer_confirmation_request_present) -precondition searches for that exact text on subsequent sweeps; -do not edit the wording around it in a way that breaks the -case-sensitive substring match. - ### `reviewer-ping` (reviewer-re-review) ```markdown