diff --git a/.apache-steward-overrides/pr-management-triage-comment-templates.md b/.apache-steward-overrides/pr-management-triage-comment-templates.md index 6c2d1432591fd..48c27fe045d13 100644 --- a/.apache-steward-overrides/pr-management-triage-comment-templates.md +++ b/.apache-steward-overrides/pr-management-triage-comment-templates.md @@ -145,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 @@ -161,14 +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? Once you believe the feedback is addressed, mark the thread as resolved so the reviewer isn't re-pinged needlessly. Thanks! - - -``` - ### `reviewer-ping` (reviewer-re-review) ```markdown 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