This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 4f2b0b3faab Magpie: sync setup bootstrap docs + pin triage feedback
channel (#68420)
4f2b0b3faab is described below
commit 4f2b0b3faabfed0a34c650c5194c53236efbfcca
Author: Jarek Potiuk <[email protected]>
AuthorDate: Sun Jun 14 01:39:14 2026 +0200
Magpie: sync setup bootstrap docs + pin triage feedback channel (#68420)
* Sync committed magpie-setup bootstrap with apache-magpie framework
The committed magpie-setup bootstrap copy is refreshed from the framework
snapshot as part of a /magpie-setup upgrade. Adds documentation of the new
agent-guard PreToolUse hook to the adopt, upgrade, and verify sub-action
docs
(install/sync procedure, drift-sync handling, and the verify checklist
entry).
* Pin pr-management-triage feedback channel to pr-body (folding)
Explicitly set triage_feedback_channel: pr-body in the project override so
deterministic quality-violation feedback (draft/comment/close actions) is
folded
into the PR description instead of posted as a notifying comment. This was
already the framework default; pinning it documents the project's choice and
makes it durable.
* Bump committed magpie-setup bootstrap to framework 28d261d
Refreshes the committed bootstrap copy from the framework snapshot
(follow-on
/magpie-setup upgrade). Documents adding __pycache__/ and *.pyc to adopted
.gitignore entries (#508) and the corresponding verify check, plus an
unadopt
cleanup note.
---
.agents/skills/magpie-setup/adopt.md | 49 ++++++++++++++++++++++++
.agents/skills/magpie-setup/unadopt.md | 12 +++++-
.agents/skills/magpie-setup/upgrade.md | 10 +++++
.agents/skills/magpie-setup/verify.md | 31 +++++++++++++++
.apache-magpie-overrides/pr-management-config.md | 7 ++++
5 files changed, 108 insertions(+), 1 deletion(-)
diff --git a/.agents/skills/magpie-setup/adopt.md
b/.agents/skills/magpie-setup/adopt.md
index ea7e8af5559..f5d19402217 100644
--- a/.agents/skills/magpie-setup/adopt.md
+++ b/.agents/skills/magpie-setup/adopt.md
@@ -503,8 +503,17 @@ idempotent — re-add them if they're missing.
/.apache-magpie/
/.apache-magpie.local.lock
/.claude/settings.local.json
+__pycache__/
+*.pyc
```
+The `__pycache__/` and `*.pyc` lines (non-anchored — they match at
+any depth) keep the byte-compiled artefacts that framework skill
+scripts emit when run from the adopter checkout (e.g.
+[`setup-status/scripts/collect_status.py`](../setup-status/scripts/collect_status.py))
+out of the tree. Most adopters already carry these from a stock
+Python `.gitignore`; the adopt flow adds them if missing.
+
**Symlink entries — one uniform block per active target
([`agents.md`](agents.md)), no per-layout variation.** Every
framework skill is symlinked under the `magpie-` prefix (see
@@ -1081,6 +1090,45 @@ Four passes, in this order:
SUBSEQUENT adoption — it is the same pass `/magpie-setup
upgrade` runs after a snapshot refresh.
+ **The agent-guard PreToolUse hook is one such adopter-side
+ file.** The framework ships
+ [`tools/agent-guard`](../../tools/agent-guard/README.md) — a
+ deterministic Claude Code `PreToolUse` guard that blocks
+ `gh`/`git` commands which would ping maintainers, carry a
+ `Co-Authored-By` trailer, mark a PR ready prematurely, leak
+ security language publicly, or empty a PR via force-push. Sync
+ it like the post-checkout hook:
+ - Copy the single self-contained script
+ `tools/agent-guard/src/agent_guard/__init__.py` (from the
+ snapshot) to `<repo-root>/.claude/hooks/agent-guard.py`, and
+ populate `<repo-root>/.claude/hooks/guards.d/` from **two**
+ snapshot sources: the engine's bundled
+ `tools/agent-guard/src/agent_guard/guards.d/*.py`, **and every
+ skill-owned guard** — `skills/*/guards/*.py` (e.g. the
+ `pr-management-triage` `mention` + `mark-ready` guards, the
+ `security-issue-fix` `security-language` guard). Collecting all
+ of them into the single `guards.d` is what lets each skill own
+ its own deterministic guard while the hook is wired only once.
+ The dispatcher auto-discovers every `*.py` in the `guards.d`
+ sibling of the script — adding a skill (or a skill adding a
+ guard) needs no re-wiring, only this re-sync (see the tool README).
+ - **Wire the hook once** in `.claude/settings.json` under
+ `hooks.PreToolUse` (matcher `Bash`). Because the committed
+ `.claude/settings.json` is agent-edit-denied, **surface the
+ exact snippet for the maintainer to apply** (or route it
+ through the `update-config` skill) rather than writing it:
+
+ ```json
+ { "matcher": "Bash", "hooks": [ { "type": "command",
+ "command": "python3
\"$CLAUDE_PROJECT_DIR/.claude/hooks/agent-guard.py\"",
+ "timeout": 30 } ] }
+ ```
+
+ Wiring happens **only once**; thereafter guards are
+ added/removed purely by syncing `guards.d` — no settings.json
+ change. If the `hooks.PreToolUse` entry is already present,
+ this pass only re-syncs the script + `guards.d`.
+
2. **Propagate to every worktree (run `worktree-init`
unconditionally).** The main is now adopted; any
pre-existing linked worktree of this repo still lacks
@@ -1213,6 +1261,7 @@ Committed (you'll see in `git status`):
Gitignored (do NOT commit):
.apache-magpie/
.apache-magpie.local.lock
+ __pycache__/ + *.pyc # byte-compiled artefacts from skill scripts;
added to .gitignore if missing
.agents/skills/magpie-* (except magpie-setup, committed above) #
canonical links into the snapshot: opt-in + always-on families
.claude/skills/magpie-* (except magpie-setup, committed above) # relays →
../../.agents/skills/magpie-*
.github/skills/magpie-* (except magpie-setup, committed above) # relays →
../../.agents/skills/magpie-*
diff --git a/.agents/skills/magpie-setup/unadopt.md
b/.agents/skills/magpie-setup/unadopt.md
index a09f33efa89..2dc81387508 100644
--- a/.agents/skills/magpie-setup/unadopt.md
+++ b/.agents/skills/magpie-setup/unadopt.md
@@ -249,7 +249,13 @@ pointing at a deleted snapshot.
[`adopt.md` Step 7](adopt.md) that are present, and leave
any adopter-added entries (e.g. unrelated rules near the
adoption block) untouched. Do not collapse blank lines —
- the diff stays minimal.
+ the diff stays minimal. **Exception:** leave `__pycache__/`
+ and `*.pyc` in place — they are stock Python entries that
+ most repos carry independently of the framework, so removing
+ them would break the adopter's own Python ignores. Only drop
+ them if they sit unambiguously inside the steward-managed
+ block (under the same comment header the adopt flow wrote)
+ and the repo has no other Python sources.
6. **Doc sections.** For each of `README.md`, `AGENTS.md`,
`CONTRIBUTING.md` that contains an adoption section,
remove the section. The boundaries are the section
@@ -372,6 +378,10 @@ need a human re-read.
adopter also has `/.apache-magpie/foo` for unrelated
reasons) → only the exact adopt-template lines are
removed; adopter rules stay.
+- **Stock Python entries (`__pycache__/`, `*.pyc`)** → left
+ in place by default per Step 5; they predate adoption in
+ most repos, so removing them would break the adopter's own
+ Python ignores.
- **Adopter ran `unadopt` then realised they wanted to keep
override content** → the override directory was preserved
by default; if they passed `--purge-overrides` and
diff --git a/.agents/skills/magpie-setup/upgrade.md
b/.agents/skills/magpie-setup/upgrade.md
index b760a7e84b1..205f52a5959 100644
--- a/.agents/skills/magpie-setup/upgrade.md
+++ b/.agents/skills/magpie-setup/upgrade.md
@@ -384,6 +384,16 @@ rather than pulls in via symlink. Examples:
- `<repo-root>/.git/hooks/post-checkout` (the worktree-aware
hook installed during adoption).
+- `<repo-root>/.claude/hooks/agent-guard.py` and the
+ `<repo-root>/.claude/hooks/guards.d/` directory (the
+ deterministic `PreToolUse` guard dispatcher and its guards — see
+ [`adopt.md` Step
12](adopt.md#step-12--post-install-sync--worktree-propagation--sandbox-allowlist--sanity-check)
+ and [`tools/agent-guard`](../../tools/agent-guard/README.md)).
+ `guards.d/` is populated from **both** the engine's bundled
+ `guards.d/*.py` **and** every skill-owned `skills/*/guards/*.py`
+ in the snapshot. Re-syncing it is how a new skill — or a skill
+ that newly adds a guard — reaches an already-adopted repo; the
+ `settings.json` `hooks.PreToolUse` wiring is unchanged.
- Any future hook or local config the framework adds.
These can drift independently of the snapshot — an
diff --git a/.agents/skills/magpie-setup/verify.md
b/.agents/skills/magpie-setup/verify.md
index 1c634d63c10..1f395883696 100644
--- a/.agents/skills/magpie-setup/verify.md
+++ b/.agents/skills/magpie-setup/verify.md
@@ -159,6 +159,9 @@ Check that the entries from
[issue #197](https://github.com/apache/airflow-steward/issues/197);
must never be committed since the content is machine-specific
absolute paths)
+- `__pycache__/` and `*.pyc` (byte-compiled artefacts emitted when
+ framework skill scripts run from the adopter checkout; non-anchored
+ so they match at any depth)
Recommended (a **uniform** `magpie-*` glob block per **active
target dir** — [`agents.md`](agents.md) — with no per-layout
@@ -184,6 +187,8 @@ variation):
target as defense in depth, but `verify` surfaces the
underlying `.gitignore` gap so the operator fixes the root
cause.
+- ⚠ if `__pycache__/` or `*.pyc` is not gitignored — byte-compiled
+ artefacts from skill scripts could be accidentally committed.
- ⚠ if symlink patterns are not gitignored.
### 5. Symlinks point at live framework skills
@@ -303,6 +308,32 @@ Two sub-checks on `<repo-root>/.git/hooks/post-checkout`:
remediation, no operator prompt needed; the sync
pass overwrites silently.
+### 8a. agent-guard PreToolUse hook installed and wired
+
+Three sub-checks for the deterministic guard
+([`tools/agent-guard`](../../tools/agent-guard/README.md)):
+
+1. **Script present + matches the snapshot.**
`<repo-root>/.claude/hooks/agent-guard.py`
+ exists and its content matches the snapshot's
+ `tools/agent-guard/src/agent_guard/__init__.py`.
+ - ⚠ / ✗ on missing / stale — remediation is `/magpie-setup`
+ (adopt or upgrade), whose sync pass re-installs it.
+2. **`guards.d` populated.** `<repo-root>/.claude/hooks/guards.d/`
+ exists and contains every guard the snapshot ships — the
+ engine's bundled `guards.d/*.py` **and** each skill-owned
+ `skills/*/guards/*.py` (e.g. `mention`, `mark_ready`,
+ `security_language`). Flag a *missing* expected guard or a stale
+ copy; extra locally-added `*.py` are fine. A missing skill guard
+ means that skill's deterministic protection is silently inactive
+ — remediation is `/magpie-setup` (adopt/upgrade), which re-collects.
+3. **Hook wired in settings.json.** `<repo-root>/.claude/settings.json`
+ has a `hooks.PreToolUse` entry (matcher `Bash`) whose command
+ runs `agent-guard.py`.
+ - ⚠ if missing — the script is present but not active; print
+ the one-time wiring snippet (see
+ [`adopt.md` Step
12](adopt.md#step-12--post-install-sync--worktree-propagation--sandbox-allowlist--sanity-check))
+ for the maintainer to apply (settings.json is agent-edit-denied).
+
### 8b. Sandbox-allowlist coverage of the current worktree
Defensive cross-check for
diff --git a/.apache-magpie-overrides/pr-management-config.md
b/.apache-magpie-overrides/pr-management-config.md
index c71f6a2c26a..1cc199daade 100644
--- a/.apache-magpie-overrides/pr-management-config.md
+++ b/.apache-magpie-overrides/pr-management-config.md
@@ -25,6 +25,7 @@
- [Identifiers](#identifiers)
- [Project-specific labels](#project-specific-labels)
- [Grace windows](#grace-windows)
+ - [Feedback delivery](#feedback-delivery)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -75,3 +76,9 @@ days).
| Stale-review-ping cooldown | 7 days | 7 days |
| Stale-workflow-approval threshold | 28 days | 28 days |
| Stale-Copilot-review threshold | 7 days | 7 days |
+
+## Feedback delivery
+
+| Key | Value | Notes |
+|---|---|---|
+| `triage_feedback_channel` | `pr-body` | Deterministic quality-violation
feedback for the `draft`, `comment` (deterministic-flag), and `close` actions
is **folded into the PR description** as a managed marker block rather than
posted as a comment. Editing a PR body does not notify subscribers, so the
maintainer mailbox stays quiet (the [denoise
rationale](../../skills/pr-management-triage/rationale.md#why-fold-feedback-into-the-pr-body-denoise)).
Pings, `request-author-confirmation`, se [...]
