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-steward.git
The following commit(s) were added to refs/heads/main by this push:
new d856ce2 feat(migration): pre-Magpie → Magpie upgrade migration +
rename ~/.config XDG dir (#440)
d856ce2 is described below
commit d856ce228ad1622103b7984d9306ded062b359dd
Author: Jarek Potiuk <[email protected]>
AuthorDate: Wed Jun 3 01:16:50 2026 +0200
feat(migration): pre-Magpie → Magpie upgrade migration + rename ~/.config
XDG dir (#440)
Migrate adopters still on the pre-rename `apache-steward` layout over to
Apache Magpie, and rename the `~/.config` per-user credential dir.
Transition compat shim (`.claude/skills/setup-steward/`):
- Committed (un-ignored) at the legacy path so it ships in the snapshot
a frozen `/setup-steward upgrade` fetches. A pre-Magpie adopter's
frozen upgrade refreshes the snapshot, reloads this shim in-flight
(Golden rule 9), and the shim's self-contained `upgrade.md` migration
runs: `.apache-steward*` → `.apache-magpie*`, committed `setup-steward`
→ `magpie-setup`, un-prefixed symlinks → `magpie-*`, the `.gitignore`
block → the collapsed `magpie-*` form, and `~/.config/apache-steward/`
→ `~/.config/apache-magpie/` — then it removes itself. This shim is the
ONLY artefact that still carries the `steward` name.
- `skills/setup/upgrade.md` Step 0a routes a half-migrated repo back to
the shim; install-recipes documents the (automatic) migration; AGENTS
notes the shim must not be deleted.
XDG config-dir rename (`~/.config/apache-steward/` →
`~/.config/apache-magpie/`):
- code defaults (oauth-draft / oauth-api / redactor) and docs move to the
new dir — forward-looking for new adopters.
- The framework's OWN sandbox config — `.claude/settings.json` plus the
sandbox-lint baseline (`expected.json` + `__init__.py`) — intentionally
stays on `~/.config/apache-steward/`: it mirrors the maintainer's current
un-migrated creds dir, and `.claude/settings.json` is harness-protected
from the agent. A maintainer flips that pair (settings.json + baseline)
to apache-magpie when they migrate their own `~/.config` dir — the same
pair-flip the migration shim performs for adopters.
Generated-by: Claude Code (Opus 4.8)
---
.claude/skills/setup-steward/SKILL.md | 87 ++++++++
.claude/skills/setup-steward/upgrade.md | 248 +++++++++++++++++++++
.gitignore | 5 +-
.pre-commit-config.yaml | 2 +-
AGENTS.md | 13 +-
docs/rfcs/RFC-AI-0003.md | 4 +-
docs/security/threat-model.md | 6 +-
docs/setup/install-recipes.md | 39 ++++
docs/setup/privacy-llm.md | 4 +-
docs/setup/secure-agent-setup.md | 6 +-
docs/setup/unadopt.md | 6 +-
skills/security-cve-allocate/SKILL.md | 2 +-
skills/security-issue-import-from-md/SKILL.md | 2 +-
skills/security-issue-import/SKILL.md | 2 +-
skills/security-issue-invalidate/SKILL.md | 2 +-
skills/security-issue-sync/SKILL.md | 2 +-
skills/security-issue-sync/apply-and-push.md | 2 +-
skills/setup/adopt.md | 6 +-
skills/setup/unadopt.md | 6 +-
skills/setup/upgrade.md | 24 ++
skills/write-skill/scripts/init_skill.py | 2 +-
skills/write-skill/security-checklist.md | 2 +-
tools/cve-tool-vulnogram/oauth-api/README.md | 4 +-
.../oauth-api/src/vulnogram_api/check.py | 2 +-
.../oauth-api/src/vulnogram_api/credentials.py | 2 +-
.../oauth-api/src/vulnogram_api/record_fetch.py | 2 +-
.../oauth-api/src/vulnogram_api/record_publish.py | 2 +-
.../oauth-api/src/vulnogram_api/record_update.py | 2 +-
.../oauth-api/src/vulnogram_api/setup_session.py | 2 +-
tools/gmail/draft-backends.md | 2 +-
tools/gmail/oauth-draft/README.md | 4 +-
.../oauth-draft/src/oauth_draft/create_draft.py | 2 +-
.../oauth-draft/src/oauth_draft/credentials.py | 2 +-
.../src/oauth_draft/mark_threads_read.py | 2 +-
.../oauth-draft/src/oauth_draft/setup_creds.py | 2 +-
tools/gmail/oauth-draft/tests/test_setup_creds.py | 2 +-
tools/privacy-llm/pii.md | 6 +-
tools/privacy-llm/redactor/README.md | 2 +-
.../privacy-llm/redactor/src/redactor/list_cmd.py | 2 +-
tools/privacy-llm/redactor/src/redactor/mapping.py | 4 +-
tools/privacy-llm/redactor/src/redactor/redact.py | 2 +-
tools/privacy-llm/redactor/src/redactor/reveal.py | 2 +-
tools/privacy-llm/redactor/tests/test_mapping.py | 2 +-
tools/privacy-llm/tool.md | 4 +-
tools/privacy-llm/wiring.md | 6 +-
45 files changed, 468 insertions(+), 66 deletions(-)
diff --git a/.claude/skills/setup-steward/SKILL.md
b/.claude/skills/setup-steward/SKILL.md
new file mode 100644
index 0000000..d1f4005
--- /dev/null
+++ b/.claude/skills/setup-steward/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: setup-steward
+description: |
+ Transition migration shim for pre-Magpie (apache-steward) adopters.
+ This is the ONLY framework artefact that still carries the legacy
+ `steward` name, and it exists for exactly one purpose: to migrate a
+ repo that adopted the framework before it was renamed to Apache
+ Magpie over to the new `magpie-` layout, then delete itself.
+ Sub-actions:
+ `/setup-steward upgrade` — run the one-time pre-Magpie migration
+ (the only supported sub-action)
+when_to_use: |
+ Invoke ONLY as the bridge for a pre-Magpie adopter: a repo whose
+ committed framework skill is still `.claude/skills/setup-steward/`
+ and whose runtime state still uses `.apache-steward*` / un-prefixed
+ framework symlinks. A frozen pre-Magpie `/setup-steward upgrade`
+ lands here automatically after it refreshes the snapshot and reloads
+ the committed skill in-flight. After the migration completes the
+ adopter uses `/magpie-setup` for everything; this shim is gone.
+argument-hint: "[upgrade]"
+capability: capability:setup
+license: Apache-2.0
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/legal/release-policy.html -->
+
+<!-- Placeholder convention (see
../../../AGENTS.md#placeholder-convention-used-in-skill-files):
+ <adopter-skills-dir> → the dir holding the adopter's skills
+ (`.claude/skills/` or `.github/skills/`,
+ per the project's convention)
+ <snapshot-dir> → the gitignored framework snapshot. Pre-Magpie
+ it is `.apache-steward/`; the migration moves
+ it to `.apache-magpie/`. -->
+
+# setup-steward — pre-Magpie migration shim
+
+> **This skill is a one-shot transition artefact.** The framework was
+> renamed from **apache-steward** to **Apache Magpie**, which moved the
+> skill source (`.claude/skills/` → `skills/`), renamed the dotfiles
+> (`.apache-steward*` → `.apache-magpie*`), renamed the bootstrap skill
+> (`setup-steward` → committed as `magpie-setup`), and namespaced every
+> framework skill under a `magpie-` prefix. A repo that adopted the
+> framework **before** that rename has a committed `setup-steward` skill
+> frozen on the old layout, and cannot self-upgrade across the change.
+> This shim is the bridge.
+
+## How a pre-Magpie adopter reaches this shim
+
+The pre-Magpie `setup-steward/upgrade.md` an adopter committed does, on
+every `/setup-steward upgrade`:
+
+1. delete `.apache-steward/` and re-fetch the framework per the
+ committed lock (which lands the **new** Magpie framework on disk),
+2. overwrite its committed `.claude/skills/setup-steward/` from the
+ snapshot's `.apache-steward/.claude/skills/setup-steward/`, and
+3. **reload that skill in-flight** (its Golden rule 9).
+
+Because the Magpie framework still ships this shim at the legacy path
+`.claude/skills/setup-steward/`, step (2) finds it, step (3) reloads
+**this** `upgrade.md`, and the migration below runs in place of the old
+upgrade logic — no manual bootstrap required.
+
+> A `/magpie-setup upgrade` on an already-migrated repo never lands
+> here (it has no `setup-steward` skill). If a repo is only *partly*
+> migrated, `magpie-setup`'s own `upgrade.md` Step 0 detects the
+> leftover `.apache-steward*` artefacts and routes back here.
+
+## Sub-actions
+
+| Invocation | Loads | Purpose |
+|---|---|---|
+| `/setup-steward upgrade` | [`upgrade.md`](upgrade.md) | Run the one-time
pre-Magpie → Magpie migration, then hand off to the migrated `magpie-setup`. |
+| `/setup-steward` (no args) | [`upgrade.md`](upgrade.md) | Same — the
migration is the only thing this shim does. |
+
+Any other sub-action (`adopt`, `verify`, `worktree-init`, `override`,
+`unadopt`) is **not** served here: those belong to the migrated
+`magpie-setup` skill. If asked for one before migrating, run the
+migration first, then invoke it as `/magpie-setup <sub-action>`.
+
+## After the migration
+
+The migration's final step **removes this shim** — it replaces the
+committed `.claude/skills/setup-steward/` with `magpie-setup` and drops
+the `setup-steward` entry. From then on the adopter uses `/magpie-setup`
+for adopt / upgrade / verify / worktree-init / override / unadopt, and
+the `steward` name is gone from their repo entirely.
diff --git a/.claude/skills/setup-steward/upgrade.md
b/.claude/skills/setup-steward/upgrade.md
new file mode 100644
index 0000000..8edc276
--- /dev/null
+++ b/.claude/skills/setup-steward/upgrade.md
@@ -0,0 +1,248 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/legal/release-policy.html -->
+
+# upgrade — one-time pre-Magpie → Magpie migration
+
+You reached this file because a pre-Magpie `/setup-steward upgrade`
+refreshed the framework snapshot and reloaded the committed skill
+in-flight (its Golden rule 9), and the refreshed framework ships this
+migration shim at the legacy `.claude/skills/setup-steward/` path. Run
+the migration below **once**. It is idempotent and every mutating step
+is surfaced before it runs.
+
+The snapshot has already been re-fetched by the pre-Magpie upgrade and
+is the **new Magpie framework**, but it still sits at the old path
+`.apache-steward/` and the rest of the repo still uses the old names.
+The migration renames everything to the Magpie layout and then removes
+this shim.
+
+## Step 0 — Confirm this is a pre-Magpie repo and show the plan
+
+Detect the legacy state. Treat the repo as pre-Magpie if **any** of
+these exist:
+
+- `.apache-steward.lock` (committed legacy pin)
+- `.apache-steward/` (legacy snapshot dir)
+- `.apache-steward-overrides/` (legacy overrides dir)
+- `<adopter-skills-dir>/setup-steward/` (committed legacy bootstrap skill)
+- a framework symlink in `<adopter-skills-dir>` **without** the
+ `magpie-` prefix (e.g. `security-issue-import`, `pr-management-triage`)
+- `~/.config/apache-steward/` (legacy per-user config dir)
+
+If **none** exist, the repo is already on Magpie — stop and tell the
+user to run `/magpie-setup upgrade` instead; there is nothing to
+migrate.
+
+Resolve `<adopter-skills-dir>` exactly as the framework's
+[`magpie-setup` conventions](../../../skills/setup/conventions.md) does —
+detect Pattern A (flat `.claude/skills/`), B (per-skill double-symlink
+to `.github/skills/`), or D (one of `.claude/skills` / `.github/skills`
+is a directory symlink to the other). Pin it for the rest of the run.
+
+**Surface the full migration plan** (every rename below, as a single
+list) and get the user's confirmation before writing anything. This is
+a one-time, repo-reshaping change; the user sees it before it runs.
+
+## Step 1 — Rename the snapshot dir
+
+```bash
+# Gitignored build artefact — a plain mv, no history impact.
+[ -d .apache-steward ] && mv .apache-steward .apache-magpie
+```
+
+If `.apache-magpie/` already exists (a partial prior run), keep it and
+`rm -rf .apache-steward`. After this the snapshot is at
+`.apache-magpie/`, and the new framework's skills are at
+`.apache-magpie/skills/<skill>/` (no longer `.../.claude/skills/...`).
+
+Confirm `.apache-magpie/skills/setup/SKILL.md` exists — that is the new
+bootstrap skill source. If it is missing, the re-fetch landed an
+unexpected layout; stop and surface it.
+
+## Step 2 — Rename the lock files
+
+```bash
+# Committed pin — use git mv so history follows.
+[ -f .apache-steward.lock ] && git mv .apache-steward.lock .apache-magpie.lock
+# Gitignored per-machine record — plain mv.
+[ -f .apache-steward.local.lock ] && mv .apache-steward.local.lock
.apache-magpie.local.lock
+```
+
+## Step 3 — Rename the overrides dir
+
+```bash
+# Committed; preserve every override file and its history.
+[ -d .apache-steward-overrides ] && git mv .apache-steward-overrides
.apache-magpie-overrides
+```
+
+The override **filenames** are keyed to framework skill names. Only one
+framework skill was renamed in the Magpie rename: `setup-steward` →
+`setup`. So if an override `setup-steward.md` exists, rename it too:
+
+```bash
+[ -f .apache-magpie-overrides/setup-steward.md ] && \
+ git mv .apache-magpie-overrides/setup-steward.md
.apache-magpie-overrides/setup.md
+```
+
+All other override filenames (`security-issue-sync.md`,
+`pr-management-triage.md`, …) are unchanged — the `magpie-` prefix is an
+install-time symlink-name concern, not an override-file concern (an
+override targets the skill by its clean source name).
+
+## Step 4 — Replace the committed bootstrap skill (`setup-steward` →
`magpie-setup`)
+
+The committed skill currently on disk at `<adopter-skills-dir>/setup-steward/`
+is **this shim** (the pre-Magpie upgrade just overwrote it from the
+snapshot). Replace it with the real Magpie bootstrap skill, named
+`magpie-setup`, per the adopter's layout pattern:
+
+```bash
+# Pattern A (flat):
+rm -rf <adopter-skills-dir>/setup-steward
+cp -r .apache-magpie/skills/setup <adopter-skills-dir>/magpie-setup
+
+# Pattern B (double-symlinked) — copy into .github/skills/, then the
+# outer .claude/skills/magpie-setup symlink is created in Step 5:
+rm -rf .github/skills/setup-steward .claude/skills/setup-steward
+cp -r .apache-magpie/skills/setup .github/skills/magpie-setup
+
+# Pattern D — write to the canonical side only (D.1 → .github/skills/,
+# D.2 → .claude/skills/); the symlinked side resolves automatically:
+rm -rf <canonical-side>/setup-steward
+cp -r .apache-magpie/skills/setup <canonical-side>/magpie-setup
+```
+
+`magpie-setup` is the one **committed** framework skill (Golden rule 6);
+it lands as new files in `git status` for the migration PR.
+
+## Step 5 — Re-prefix every framework symlink to `magpie-`
+
+Pre-Magpie, framework skills were symlinked under their bare names
+(`<adopter-skills-dir>/security-issue-import` → snapshot). Magpie
+namespaces every framework skill under a `magpie-` prefix. For **each**
+existing framework symlink in `<adopter-skills-dir>` (every entry that
+is a symlink resolving into the snapshot, i.e. not the committed
+`magpie-setup` and not an adopter-owned skill):
+
+1. Determine its clean source name `<n>` (the snapshot skill it points
+ at). **Note the one renamed skill:** a legacy `list-steward-skills`
+ symlink maps to the new source name `list-skills`.
+2. Create `<adopter-skills-dir>/magpie-<n>` → relative path into
+ `.apache-magpie/skills/<n>/` (per pattern — both layers for B; the
+ canonical side only for D).
+3. Remove the old bare symlink (`security-issue-import`,
+ `pr-management-triage`, `list-steward-skills`, …).
+
+Compute the symlink set fresh from `.apache-magpie/skills/` filtered to
+the families the project had (read from the renamed
+`.apache-magpie.lock` plus the always-on `setup-*` / `list-*` families)
+— do not hard-code names. The post-migration state: every framework
+skill the project uses is reachable as `magpie-<n>`, and no bare-named
+framework symlink remains.
+
+## Step 6 — Rewrite the `.gitignore` block
+
+Replace the legacy framework gitignore entries. The Magpie layout
+collapses the per-family symlink lines into a single `magpie-*` glob,
+because **every** framework symlink now carries the prefix:
+
+```text
+# --- remove these legacy lines if present ---
+/.apache-steward/
+/.apache-steward.local.lock
+/.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-* # (Pattern B/D only)
+/.github/skills/pr-management-*
+/.github/skills/issue-*
+/.github/skills/setup-isolated-setup-*
+/.github/skills/setup-override-upstream
+/.github/skills/setup-shared-config-sync
+/.github/skills/list-steward-*
+
+# --- write these Magpie lines ---
+/.apache-magpie/
+/.apache-magpie.local.lock
+/.claude/skills/magpie-*
+/.github/skills/magpie-* # (Pattern B; or the canonical side for
D)
+```
+
+Keep the orientation right for the adopter's pattern (Pattern A → only
+the `.claude/skills/magpie-*` line; D → only the canonical side). The
+committed `.apache-magpie.lock` and `.apache-magpie-overrides/` are
+**not** gitignored.
+
+## Step 7 — Migrate the per-user config dir + sandbox allowlist
+
+The per-user credential / config dir moved from `~/.config/apache-steward/`
+to `~/.config/apache-magpie/`:
+
+```bash
+[ -d ~/.config/apache-steward ] && [ ! -e ~/.config/apache-magpie ] && \
+ mv ~/.config/apache-steward ~/.config/apache-magpie
+```
+
+This dir is **outside** the repo and per-machine — migrate it once per
+machine. **Then tell the operator to update their sandbox allowlist**:
+any `~/.config/apache-steward/` entry in their Claude Code settings
+(project `.claude/settings.local.json`, project `.claude/settings.json`,
+or user-scope `~/.claude/settings.json`) must become
+`~/.config/apache-magpie/`, or sandboxed framework tools will not be
+able to read the moved credentials. The framework cannot edit those
+settings files for the operator — surface the exact one-line change.
+
+## Step 8 — Migrate the post-checkout hook + doc sections
+
+- **Git hook.** If `.git/hooks/post-checkout` contains the legacy
+ `setup-steward verify --auto-fix-symlinks` recipe, update it to
+ `magpie-setup verify --auto-fix-symlinks` (same auto-fix behaviour,
+ new skill name). Leave any non-framework hook lines untouched.
+- **Project docs.** In `README.md` / `AGENTS.md` / `CONTRIBUTING.md`,
+ update any adoption section that still names `setup-steward`,
+ `/setup-steward`, `.apache-steward*`, or the bare-named framework
+ symlinks. Best-effort and surfaced as part of the migration diff; the
+ framework-name prose ("Apache Magpie") is independent and not touched
+ here.
+
+## Step 9 — Hand off to `magpie-setup` and finish the upgrade
+
+The repo is now on the Magpie layout and **this shim is gone** (Step 4
+replaced the committed `setup-steward` with `magpie-setup`). Reload and
+hand off, per Golden rule 9:
+
+1. Re-read `<adopter-skills-dir>/magpie-setup/SKILL.md` and
+ `<adopter-skills-dir>/magpie-setup/upgrade.md`.
+2. The snapshot is already fresh at `.apache-magpie/`, so **skip** the
+ delete/re-fetch steps and resume the migrated upgrade from its
+ **Step 5 (reconcile overrides)** onward — reconcile overrides
+ against the new framework structure, then the Step 6 symlink-refresh
+ pass (idempotent — it confirms the `magpie-*` links Step 5 created),
+ the worktree propagation pass, and the upgrade summary.
+
+## Step 10 — Summary
+
+Report the migration as a single block:
+
+```text
+Migrated pre-Magpie (apache-steward) → Apache Magpie:
+ snapshot .apache-steward/ → .apache-magpie/
+ committed pin .apache-steward.lock → .apache-magpie.lock
+ local pin .apache-steward.local.lock → .apache-magpie.local.lock
+ overrides .apache-steward-overrides/ → .apache-magpie-overrides/
+ bootstrap setup-steward → magpie-setup (committed)
+ symlinks <bare>-* → magpie-* (N re-prefixed)
+ gitignore per-family lines → magpie-* glob
+ user config ~/.config/apache-steward/ → ~/.config/apache-magpie/
+ hook setup-steward verify → magpie-setup verify
+
+Action required (operator): update the ~/.config/apache-steward/ entry
+in your Claude Code sandbox allowlist to ~/.config/apache-magpie/.
+
+From now on use /magpie-setup for everything. The setup-steward shim is
+removed; commit this migration diff as the upgrade PR.
+```
diff --git a/.gitignore b/.gitignore
index 4a499e1..655d048 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,7 +8,10 @@ logs
# Skill source lives in skills/; .claude/skills/ holds only
# gitignored self-adoption symlinks (a maintainer adopts the
# framework into itself to make the skills active locally).
-.claude/skills/
+.claude/skills/*
+# Transition migration shim for pre-Magpie adopters — committed so it
+# ships in the snapshot a frozen `/setup-steward upgrade` fetches.
+!/.claude/skills/setup-steward/
# macOS
.DS_Store
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3b82ad2..5731dc9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -48,7 +48,7 @@ repos:
# Skip the PR template — GitHub pre-populates a new PR description
# with the template verbatim, so a TOC block becomes per-PR noise the
# contributor has to delete by hand.
- exclude:
^(skills/.*|tools/cve-tool-vulnogram/generate-cve-json/SKILL\.md|tools/skill-evals/.*|tools/spec-loop/.*|\.github/PULL_REQUEST_TEMPLATE\.md)$
+ exclude:
^(\.claude/skills/.*|skills/.*|tools/cve-tool-vulnogram/generate-cve-json/SKILL\.md|tools/skill-evals/.*|tools/spec-loop/.*|\.github/PULL_REQUEST_TEMPLATE\.md)$
args:
- "--maxlevel"
- "3"
diff --git a/AGENTS.md b/AGENTS.md
index 4be0632..fa0aaec 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -99,6 +99,7 @@ Repo-root files:
- [`projects/_template/`](projects/_template/) — bootstrap scaffold for a new
adopter's `<project-config>/`.
- [`tools/<name>/`](tools/) — tool adapters (GitHub operations, issue-template
schema, project-board GraphQL, …) for the external tools the skills invoke.
- [`skills/<name>/SKILL.md`](skills/) — the agentic workflows.
+- [`.claude/skills/setup-steward/`](.claude/skills/setup-steward/) — a
**transition migration shim**, deliberately committed (un-ignored) at the
legacy path so it ships in the snapshot. It is the only artefact that still
carries the `steward` name; its sole job is to migrate a pre-Magpie adopter to
the `magpie-` layout (see its
[`SKILL.md`](.claude/skills/setup-steward/SKILL.md)). **Do not delete it**
until the framework drops pre-Magpie migration support.
There is no source code to build or test in this framework
repository itself. Adopting projects may include project-specific
@@ -292,8 +293,8 @@ this order, **first match wins**:
| # | Location | When to use |
|---|---|---|
| 1 | Path in `$APACHE_STEWARD_USER_CONFIG` (env var) | Power-user / CI /
isolated test setups that need to point at a specific config without touching
disk conventions. Wins over both defaults below. |
-| 2 | `~/.config/apache-steward/user.md` | **Recommended default for new
adopters.** Per-user, OS-conventional. One file shared across every worktree of
every adopter project on the machine — so the operator has one
identity-and-tool-picks config, not one per tracker repo and not one per
worktree. |
-| 3 | `<project-config>/user.md` | Per-project fallback, kept for backward
compatibility with adopters who set up `user.md` inside their tracker repo
before `~/.config/apache-steward/` existed as the canonical location. Future
adopters should prefer (2); existing adopters keep working without action. |
+| 2 | `~/.config/apache-magpie/user.md` | **Recommended default for new
adopters.** Per-user, OS-conventional. One file shared across every worktree of
every adopter project on the machine — so the operator has one
identity-and-tool-picks config, not one per tracker repo and not one per
worktree. |
+| 3 | `<project-config>/user.md` | Per-project fallback, kept for backward
compatibility with adopters who set up `user.md` inside their tracker repo
before `~/.config/apache-magpie/` existed as the canonical location. Future
adopters should prefer (2); existing adopters keep working without action. |
Skills must consult locations (1) → (2) → (3) and use the first
file that exists. Do **not** merge across locations; the first
@@ -304,7 +305,7 @@ per the order above. The legacy phrasing
*"… or whichever location wins per the resolution order"*.
The cross-worktree story falls out of (2): every worktree of every
-adopter resolves to the same `~/.config/apache-steward/user.md`,
+adopter resolves to the same `~/.config/apache-magpie/user.md`,
so per-user fields (apache_id, GitHub handle, PMC status, local
clone path) stay coherent without symlinks, pre-commit hooks, or
per-worktree bootstrap. The framework does **not** itself manage
@@ -441,10 +442,10 @@ pinned per-tool with a 7-day default upstream cooldown).
**Tool credentials live under `$HOME`, never in the project tree.**
Any persistent token, API key, OAuth refresh token, or session
cookie a framework tool needs goes under a well-known home-directory
-path — `~/.config/apache-steward/<tool>` for tools the framework
+path — `~/.config/apache-magpie/<tool>` for tools the framework
owns, or whatever upstream convention the third-party tool already
uses. The existing exemplars: Gmail OAuth at
-`~/.config/apache-steward/gmail-oauth.json` (see
+`~/.config/apache-magpie/gmail-oauth.json` (see
[`tools/gmail/oauth-draft/src/oauth_draft/credentials.py`](tools/gmail/oauth-draft/src/oauth_draft/credentials.py)),
PonyMail session cookie at `~/.ponymail-mcp/session.json`, GitHub
auth via `gh auth` (`~/.config/gh/`). Two reasons this is
@@ -792,7 +793,7 @@ individual is already a collaborator on the `<tracker>` repo
identity is already public/known by their collaborator status
and is **not** redacted — there is no privacy gain from masking
them. The mapping from identifier to real value lives at
-`~/.config/apache-steward/pii-mapping.json` (per the home-dir
+`~/.config/apache-magpie/pii-mapping.json` (per the home-dir
credentials rule in [Local setup](#local-setup)) and is never
sent to any LLM. Reveal-to-real-name happens only at the
outbound boundary, when a draft is being assembled. The contract
diff --git a/docs/rfcs/RFC-AI-0003.md b/docs/rfcs/RFC-AI-0003.md
index 1d99950..7cab6fe 100644
--- a/docs/rfcs/RFC-AI-0003.md
+++ b/docs/rfcs/RFC-AI-0003.md
@@ -147,7 +147,7 @@ The identifier format is `<TYPE>-<6-char-lowercase-hex>`
where the hex is `sh
#### Mapping store
-Path: `~/.config/apache-steward/pii-mapping.json` — outside the project tree,
per the framework's home-dir tool-credentials rule.
+Path: `~/.config/apache-magpie/pii-mapping.json` — outside the project tree,
per the framework's home-dir tool-credentials rule.
Format:
@@ -361,7 +361,7 @@ Implementation: stdlib-only (`argparse`, `dataclasses`,
`re`, `urllib.parse`,
The framework treats these surfaces as off-limits to LLM context, even when an
"approved" LLM is in the stack:
-- The contents of `~/.config/apache-steward/pii-mapping.json`. The file is
read by `pii-redact` / `pii-reveal` only. Skills MUST NOT include the mapping
in any LLM-bound prompt, summary, or status comment. For debugging, run
`pii-list` in the user's terminal — that output goes to the user's screen, not
to Claude's context.
+- The contents of `~/.config/apache-magpie/pii-mapping.json`. The file is read
by `pii-redact` / `pii-reveal` only. Skills MUST NOT include the mapping in any
LLM-bound prompt, summary, or status comment. For debugging, run `pii-list` in
the user's terminal — that output goes to the user's screen, not to Claude's
context.
- The `--field <type>:<value>` arguments themselves. Every value passed there
is exactly what the redactor is replacing.
- Any draft text *before* `pii-reveal` runs, when the destination is a
non-internal surface (e.g. a public PR comment) — the body would still carry
identifiers, which leak no PII, but skills should not emit identifier-laden
drafts to non-internal destinations by accident. The destination check in the
approved-LLM gate is a separate safety net for this.
diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md
index 8727da5..d536466 100644
--- a/docs/security/threat-model.md
+++ b/docs/security/threat-model.md
@@ -144,7 +144,7 @@ and triggers a re-audit.
(public visibility, over-broad collaborator list) is a tracker
problem, not a framework problem — though the framework declines
to operate against a tracker it detects as public.
-4. **Credentials in `~/.config/apache-steward/` are honoured by
+4. **Credentials in `~/.config/apache-magpie/` are honoured by
`denyRead`.** The default sandbox blocks the agent from reading
that path. An adopter who relaxes that block (for example by
adding it to `allowRead`) accepts the resulting threat surface.
@@ -386,7 +386,7 @@ interested in it, and the boundary that protects it.
| Tracker comment thread | Confidential, embargoed | P2, P3 | B2, B3 |
| Reporter identity | Confidential until Step 16 | P1, P2 | B3, redactor |
| CVE ID before advisory | Embargoed | P2 | B4 |
-| Credentials in `~/.config/apache-steward/` | Secret | P3, P5 | sandbox
`denyRead` |
+| Credentials in `~/.config/apache-magpie/` | Secret | P3, P5 | sandbox
`denyRead` |
| `gh` token in env | Secret, scoped | P3 | sandbox env, `permissions.ask` |
| CNA-tool OAuth token (`cve_authority.tool`; named example: Vulnogram on
`airflow-s`) | Secret, scoped | P3 | sandbox env |
| Mail-backend OAuth token (`mail_provider.primary`; named example: Gmail on
`airflow-s`) | Secret, scoped | P3 | sandbox env |
@@ -506,7 +506,7 @@ fix-PR diff and combines them into a confirmation.
### X3 — Sandbox bypass via developer override
A maintainer (P5) running locally edits `.claude/settings.json` to
-add `~/.config/apache-steward/` to `allowRead` because they are
+add `~/.config/apache-magpie/` to `allowRead` because they are
debugging an authentication issue. They forget to revert. The next
agent run reads the credentials.
diff --git a/docs/setup/install-recipes.md b/docs/setup/install-recipes.md
index cf7d71c..aeb2324 100644
--- a/docs/setup/install-recipes.md
+++ b/docs/setup/install-recipes.md
@@ -8,6 +8,7 @@
- [Method 3 — git branch (defaults to
`main`)](#method-3--git-branch-defaults-to-main)
- [After any recipe — let the skill take
over](#after-any-recipe--let-the-skill-take-over)
- [Subsequent runs and drift detection](#subsequent-runs-and-drift-detection)
+ - [Migrating a pre-Magpie (`apache-steward`)
adopter](#migrating-a-pre-magpie-apache-steward-adopter)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -282,3 +283,41 @@ new framework skills, removing any that were renamed away),
and updates the local lock. See
[`setup/upgrade.md`](../../skills/setup/upgrade.md)
for the full flow.
+
+## Migrating a pre-Magpie (`apache-steward`) adopter
+
+A repo that adopted the framework **before** it was renamed from
+`apache-steward` to **Apache Magpie** is on the old layout: a committed
+`.claude/skills/setup-steward/` skill, an `.apache-steward/` snapshot,
+`.apache-steward.lock` / `.apache-steward-overrides/`, un-prefixed
+framework symlinks, and `~/.config/apache-steward/`. **No manual recipe
+is needed** — the migration is automatic and one-shot:
+
+```text
+/setup-steward upgrade
+```
+
+The frozen `setup-steward` skill committed in the repo refreshes the
+snapshot per its lock (which lands the current Magpie framework), and —
+because the Magpie framework still ships a transition shim at the legacy
+`.claude/skills/setup-steward/` path — reloads that shim in-flight (its
+Golden rule 9). The shim's
+[`upgrade.md`](../../.claude/skills/setup-steward/upgrade.md) then
+migrates everything in place:
+
+- `.apache-steward*` → `.apache-magpie*` (snapshot, locks, overrides)
+- the committed `setup-steward` skill → `magpie-setup`
+- every un-prefixed framework symlink → `magpie-<name>`
+- the `.gitignore` block → the collapsed `magpie-*` form
+- `~/.config/apache-steward/` → `~/.config/apache-magpie/` (per-machine)
+
+…then **removes itself**. Review and commit the migration diff as the
+upgrade PR. From then on the repo uses `/magpie-setup` for everything,
+and the `steward` name is gone.
+
+> **One manual step the framework cannot do for you:** update any
+> `~/.config/apache-steward/` entry in your Claude Code sandbox
+> allowlist (project `.claude/settings.local.json` / `.claude/settings.json`
+> or user-scope `~/.claude/settings.json`) to `~/.config/apache-magpie/`,
+> or sandboxed framework tools cannot read the moved credentials. The
+> migration surfaces the exact one-line change.
diff --git a/docs/setup/privacy-llm.md b/docs/setup/privacy-llm.md
index 6f7dc03..3e37199 100644
--- a/docs/setup/privacy-llm.md
+++ b/docs/setup/privacy-llm.md
@@ -216,7 +216,7 @@ actual endpoint):
2. Confirm authentication if the endpoint requires it. ASF
endpoints typically authenticate via the user's ASF identity
(LDAP / OAuth); credentials live at
- `~/.config/apache-steward/<endpoint>-token.json` or similar
+ `~/.config/apache-magpie/<endpoint>-token.json` or similar
— never in the project tree
(see [`AGENTS.md` — Local setup](../../AGENTS.md#local-setup)).
3. Place the file at `<project-config>/privacy-llm.md`. Commit.
@@ -295,7 +295,7 @@ zero-data-retention agreement plus a no-training clause.
- An Anthropic account with a zero-data-retention agreement
applied to the API key.
-- The API key at `~/.config/apache-steward/anthropic-api.json`
+- The API key at `~/.config/apache-magpie/anthropic-api.json`
or via `$ANTHROPIC_API_KEY` set from a home-dir-sourced
shell-rc — never in the project tree.
diff --git a/docs/setup/secure-agent-setup.md b/docs/setup/secure-agent-setup.md
index 5dd99ce..a3287b3 100644
--- a/docs/setup/secure-agent-setup.md
+++ b/docs/setup/secure-agent-setup.md
@@ -360,7 +360,7 @@ below, annotated.
"~/.cache/", // dev tool caches (uv HTTP cache, prek
logs, ruff/mypy caches)
"~/.local/share/uv/", // uv's tool venvs (prek, etc.)
"~/.local/bin/", // uv-installed tool entry points
- "~/.config/apache-steward/", // Gmail OAuth refresh token
(oauth-draft tool)
+ "~/.config/apache-magpie/", // Gmail OAuth refresh token (oauth-draft
tool)
"~/.gnupg/", // gpg keys (commit signing)
"/run/user/*/gnupg/" // gpg-agent socket dir
(ssh-via-gpg-agent commit signing)
],
@@ -388,7 +388,7 @@ below, annotated.
"Read(~/.aws/**)", "Read(~/.ssh/**)", "Read(~/.netrc)",
"Read(~/.docker/**)", "Read(~/.kube/**)",
"Read(~/.config/gh/**)", // bash can read it
(sandbox.allowRead); the AGENT can't
- "Read(~/.config/apache-steward/**)", // same — Bash via oauth-draft
tool, not the agent directly
+ "Read(~/.config/apache-magpie/**)", // same — Bash via oauth-draft
tool, not the agent directly
"Read(~/.config/gcloud/**)", "Read(~/.azure/**)",
"Read(//**/.env)", "Read(//**/.env.local)", "Read(//**/.env.*.local)",
"Bash(curl *)", "Bash(wget *)", // network egress via Bash
bypasses the sandbox proxy
@@ -410,7 +410,7 @@ below, annotated.
```
The deny / allow split for `~/.config/gh/` and
-`~/.config/apache-steward/` is deliberate: bash subprocesses (the `gh`
+`~/.config/apache-magpie/` is deliberate: bash subprocesses (the `gh`
CLI, `oauth-draft-create`) need to *use* the credential, but the
agent should never *see* it. `sandbox.filesystem.allowRead` permits
the bash subprocess to read the file; `permissions.deny[Read(...)]`
diff --git a/docs/setup/unadopt.md b/docs/setup/unadopt.md
index 8c781ca..f3188d3 100644
--- a/docs/setup/unadopt.md
+++ b/docs/setup/unadopt.md
@@ -203,15 +203,15 @@ grep apache-steward .gitignore
following are removed — retire each one only if you are
also retiring Magpie from this machine entirely:
-- **`~/.config/apache-steward/user.md`** — the recommended
+- **`~/.config/apache-magpie/user.md`** — the recommended
per-user identity / tool-picks config. One file, shared
across every adopter repo on this machine. If you still
use Magpie in any other repo, leave it.
Otherwise:
```bash
- rm -i ~/.config/apache-steward/user.md
- rmdir ~/.config/apache-steward 2>/dev/null # only removes the dir if
empty (errors silenced)
+ rm -i ~/.config/apache-magpie/user.md
+ rmdir ~/.config/apache-magpie 2>/dev/null # only removes the dir if empty
(errors silenced)
```
- **`~/.claude/` user-scope config, hooks, and settings** —
diff --git a/skills/security-cve-allocate/SKILL.md
b/skills/security-cve-allocate/SKILL.md
index d842ef3..b78a436 100644
--- a/skills/security-cve-allocate/SKILL.md
+++ b/skills/security-cve-allocate/SKILL.md
@@ -249,7 +249,7 @@ Before touching the tracker, verify:
privacy-llm-check
```
- Plus confirm `~/.config/apache-steward/` is writable (for the
+ Plus confirm `~/.config/apache-magpie/` is writable (for the
redactor's mapping file).
If any check fails, stop with a clear message. Do not start
diff --git a/skills/security-issue-import-from-md/SKILL.md
b/skills/security-issue-import-from-md/SKILL.md
index 5d18ad8..ea25ee5 100644
--- a/skills/security-issue-import-from-md/SKILL.md
+++ b/skills/security-issue-import-from-md/SKILL.md
@@ -229,7 +229,7 @@ Before parsing the file, verify:
Plus the rest of the pre-flight items from
[`tools/privacy-llm/wiring.md`](../../tools/privacy-llm/wiring.md#step-0--pre-flight)
- (`~/.config/apache-steward/` writable, collaborator source
+ (`~/.config/apache-magpie/` writable, collaborator source
reachable). Findings parsed in Step 1 below feed the
redact-after-fetch protocol the same way Gmail bodies do —
the file IS the source-of-truth here, treat it like an
diff --git a/skills/security-issue-import/SKILL.md
b/skills/security-issue-import/SKILL.md
index b5f7e28..1aa1f32 100644
--- a/skills/security-issue-import/SKILL.md
+++ b/skills/security-issue-import/SKILL.md
@@ -290,7 +290,7 @@ Before touching any candidate thread, verify:
is approved per
[`tools/privacy-llm/models.md`](../../tools/privacy-llm/models.md#the-pre-flight-check).
In addition, verify:
- - `~/.config/apache-steward/` is writable (the redactor's
+ - `~/.config/apache-magpie/` is writable (the redactor's
mapping file lives there);
- the configured collaborator source is reachable via
`gh api` (default: `<tracker>` from `project.md`);
diff --git a/skills/security-issue-invalidate/SKILL.md
b/skills/security-issue-invalidate/SKILL.md
index 2a47629..22f7dee 100644
--- a/skills/security-issue-invalidate/SKILL.md
+++ b/skills/security-issue-invalidate/SKILL.md
@@ -681,7 +681,7 @@ the **recipient** and the **body shape**.
attachment; the opt-in `oauth_curl` backend is used when
`tools.gmail.draft_backend: oauth_curl` is set and
credentials are on disk (default path
- `~/.config/apache-steward/gmail-oauth.json`).
+ `~/.config/apache-magpie/gmail-oauth.json`).
5. **Existing-draft check.** Before drafting, scan the inbound
thread for an existing pending draft per the
[*Detecting drafts that already exist on a
thread*](../../tools/gmail/draft-backends.md#detecting-drafts-that-already-exist-on-a-thread)
diff --git a/skills/security-issue-sync/SKILL.md
b/skills/security-issue-sync/SKILL.md
index c0b519f..d53d195 100644
--- a/skills/security-issue-sync/SKILL.md
+++ b/skills/security-issue-sync/SKILL.md
@@ -320,7 +320,7 @@ Before reading any tracker state, verify:
Plus the rest of the pre-flight items in
[`tools/privacy-llm/wiring.md`](../../tools/privacy-llm/wiring.md#step-0--pre-flight)
—
- `~/.config/apache-steward/` is writable, the configured
+ `~/.config/apache-magpie/` is writable, the configured
collaborator source is reachable, the redaction-tuning knobs
are loaded into the observed-state bag. Subsequent body reads
in Step 1 (gather current state) follow the
diff --git a/skills/security-issue-sync/apply-and-push.md
b/skills/security-issue-sync/apply-and-push.md
index e41e2f0..2fa5136 100644
--- a/skills/security-issue-sync/apply-and-push.md
+++ b/skills/security-issue-sync/apply-and-push.md
@@ -268,7 +268,7 @@ before moving on to the next item. Use:
`tools.gmail.draft_backend: oauth_curl` and have credentials at
`tools.gmail.oauth_credentials_path` /
`$GMAIL_OAUTH_CREDENTIALS` / default
- `~/.config/apache-steward/gmail-oauth.json`) — invoke
+ `~/.config/apache-magpie/gmail-oauth.json`) — invoke
`uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-create`
(see
[`tools/gmail/oauth-draft/README.md`](../../tools/gmail/oauth-draft/README.md))
with `--thread-id` from Step 1c, the standard `--to` / `--cc`,
diff --git a/skills/setup/adopt.md b/skills/setup/adopt.md
index 10df831..bda4c40 100644
--- a/skills/setup/adopt.md
+++ b/skills/setup/adopt.md
@@ -548,7 +548,7 @@ status, local clone paths, optional tool backends). If the
file
is missing, the skills fall back to interactive prompting and
offer to save the answer back into this file.
-**Recommended location: `~/.config/apache-steward/user.md`** — the
+**Recommended location: `~/.config/apache-magpie/user.md`** — the
OS-conventional per-user config dir. One file, shared across every
worktree of every adopter project on the operator's machine, so
identity-and-tool-picks stay coherent without symlinks or
@@ -624,7 +624,7 @@ setup; the skills skip any block that is missing or marked
`TODO`.
```
**Where to write the file.** Default to
-`~/.config/apache-steward/user.md` for new adopters (the per-user
+`~/.config/apache-magpie/user.md` for new adopters (the per-user
canonical location — shared across every worktree and every
adopter project on the operator's machine). If the operator
already has `<repo-root>/.apache-magpie-overrides/user.md` from a
@@ -633,7 +633,7 @@ file as a fallback, no migration needed. If both exist, the
per-user file wins; surface the conflict to the operator so they
can pick one and delete the other.
-Create the parent directory with `mkdir -p ~/.config/apache-steward/`
+Create the parent directory with `mkdir -p ~/.config/apache-magpie/`
before writing, then write the file at mode `0600` (the directory at
`0700`) since it holds personal preferences and — eventually —
identity that the operator may not want world-readable.
diff --git a/skills/setup/unadopt.md b/skills/setup/unadopt.md
index 658d0b3..ba9ef92 100644
--- a/skills/setup/unadopt.md
+++ b/skills/setup/unadopt.md
@@ -134,10 +134,10 @@ The following will be REMOVED:
The following will be PRESERVED:
.apache-magpie-overrides/ (M file(s); pass `--purge-overrides`
to remove)
- ~/.config/apache-steward/user.md (per-user; shared with other adopters
on this machine — remove manually if this was your last adoption)
+ ~/.config/apache-magpie/user.md (per-user; shared with other adopters
on this machine — remove manually if this was your last adoption)
```
-Surface the `~/.config/apache-steward/user.md` line only if that
+Surface the `~/.config/apache-magpie/user.md` line only if that
file is actually present on disk. If it is absent (or the
operator drove `user.md` resolution via
`$APACHE_STEWARD_USER_CONFIG` / the legacy per-project location),
@@ -285,7 +285,7 @@ A summary of what was removed + what remains:
Preserved:
.apache-magpie-overrides/ (M files; pass `--purge-overrides` to remove)
- ~/.config/apache-steward/user.md (per-user; shared with other adopters on
this machine — remove manually if this was your last adoption)
+ ~/.config/apache-magpie/user.md (per-user; shared with other adopters on
this machine — remove manually if this was your last adoption)
.claude/skills (or .github/skills) (Pattern D directory symlink —
adopter-owned, predates framework adoption)
<list of any non-steward-owned content the plan flagged>
diff --git a/skills/setup/upgrade.md b/skills/setup/upgrade.md
index 7d5ff91..0fcf726 100644
--- a/skills/setup/upgrade.md
+++ b/skills/setup/upgrade.md
@@ -57,6 +57,30 @@ Both paths run the same flow.
route as a recover-snapshot install per the committed
lock, not as an upgrade. Continue at Step 3.
+## Step 0a — Pre-Magpie leftovers safety check
+
+A repo that adopted the framework before it was renamed from
+**apache-steward** to **Apache Magpie** migrates via the
+one-shot transition shim at `.claude/skills/setup-steward/`
+(a frozen `/setup-steward upgrade` lands there automatically;
+see that skill's
[`upgrade.md`](../../.claude/skills/setup-steward/upgrade.md)).
+A fully-migrated repo never reaches *this* file with legacy
+artefacts present.
+
+If you nonetheless detect **any** legacy artefact here —
+`.apache-steward.lock`, `.apache-steward/`,
+`.apache-steward-overrides/`, a committed
+`<adopter-skills-dir>/setup-steward/`, or a framework symlink
+**without** the `magpie-` prefix — a prior migration did not
+finish. Do **not** continue the normal upgrade against the
+half-migrated state. Run the transition migration to
+completion first (follow
+[`.claude/skills/setup-steward/upgrade.md`](../../.claude/skills/setup-steward/upgrade.md),
+which is idempotent and safe to re-run), then resume this
+upgrade. `~/.config/apache-steward/` alone (per-user, no
+in-repo artefacts) just needs the dir + sandbox-allowlist
+move from that file's Step 7.
+
## Step 1 — Compute drift
Compare `<committed-lock>` to `<local-lock>` and to upstream
diff --git a/skills/write-skill/scripts/init_skill.py
b/skills/write-skill/scripts/init_skill.py
index aa37e21..3b5ec32 100755
--- a/skills/write-skill/scripts/init_skill.py
+++ b/skills/write-skill/scripts/init_skill.py
@@ -173,7 +173,7 @@ acceptable, etc.) and the disambiguation rules.
uv run --project <framework>/tools/privacy-llm/checker \\
privacy-llm-check
- Plus confirm `~/.config/apache-steward/` is writable (the
+ Plus confirm `~/.config/apache-magpie/` is writable (the
redactor needs to persist its mapping file there). See
[`tools/privacy-llm/wiring.md`](../../../tools/privacy-llm/wiring.md)
for the redact-after-fetch protocol.
diff --git a/skills/write-skill/security-checklist.md
b/skills/write-skill/security-checklist.md
index 8d24ef8..15d5c7b 100644
--- a/skills/write-skill/security-checklist.md
+++ b/skills/write-skill/security-checklist.md
@@ -156,7 +156,7 @@ uv run --project <framework>/tools/privacy-llm/checker \
privacy-llm-check
```
-Plus confirm `~/.config/apache-steward/` is writable (the
+Plus confirm `~/.config/apache-magpie/` is writable (the
redactor needs to persist its mapping file there). The
boilerplate that
[`init_skill.py`](scripts/init_skill.py) scaffolds includes a
diff --git a/tools/cve-tool-vulnogram/oauth-api/README.md
b/tools/cve-tool-vulnogram/oauth-api/README.md
index 6e5f210..c0b5881 100644
--- a/tools/cve-tool-vulnogram/oauth-api/README.md
+++ b/tools/cve-tool-vulnogram/oauth-api/README.md
@@ -126,7 +126,7 @@ any authenticated section member can perform.
| `--host` | Vulnogram host. Default: `cveprocess.apache.org`. |
| `--cookie-name` | Session cookie name. Default: `connect.sid`
(express-session's default). |
| `--from-address` | ASF account address baked into the session file
(informational). Defaults to `$VULNOGRAM_FROM`, then `git config user.email`. |
- | `--out` | Output path for the session file. Default:
`~/.config/apache-steward/vulnogram-session.json`. |
+ | `--out` | Output path for the session file. Default:
`~/.config/apache-magpie/vulnogram-session.json`. |
| `--skip-validate` | Skip the live HTTP probe after writing. Use only if
the host is unreachable from the box running setup but the cookie is known
good. |
The script writes the session file atomically with mode 600 and
@@ -170,7 +170,7 @@ like an SSH key:
- The setup script writes the file with mode 600 and chmods its
parent directory to 700; do not loosen those.
- Do **not** commit the session file. The path lives outside the
- repo tree by default (`~/.config/apache-steward/vulnogram-session.json`).
+ repo tree by default (`~/.config/apache-magpie/vulnogram-session.json`).
- Sessions are server-side-revocable: log out from
`cveprocess.apache.org/users/logout` in any browser session and
the cookie value stored on disk is immediately useless.
diff --git a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/check.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/check.py
index 9bdf833..65f91fa 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/check.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/check.py
@@ -53,7 +53,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Path to the session JSON. Defaults to "
"$VULNOGRAM_SESSION, else "
- "~/.config/apache-steward/vulnogram-session.json."
+ "~/.config/apache-magpie/vulnogram-session.json."
),
)
ap.add_argument(
diff --git
a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/credentials.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/credentials.py
index df0353a..eeb904b 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/credentials.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/credentials.py
@@ -43,7 +43,7 @@ import stat
import sys
import tempfile
-DEFAULT_CREDENTIALS_DIR = pathlib.Path.home() / ".config" / "apache-steward"
+DEFAULT_CREDENTIALS_DIR = pathlib.Path.home() / ".config" / "apache-magpie"
DEFAULT_CREDENTIALS_PATH = DEFAULT_CREDENTIALS_DIR / "vulnogram-session.json"
DEFAULT_HOST = "cveprocess.apache.org"
diff --git
a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_fetch.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_fetch.py
index 3fb8cf6..d35032d 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_fetch.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_fetch.py
@@ -69,7 +69,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Path to the session JSON. Defaults to "
"$VULNOGRAM_SESSION, else "
- "~/.config/apache-steward/vulnogram-session.json."
+ "~/.config/apache-magpie/vulnogram-session.json."
),
)
ap.add_argument(
diff --git
a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_publish.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_publish.py
index 08d2a57..db3dd70 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_publish.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_publish.py
@@ -82,7 +82,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Path to the session JSON. Defaults to "
"$VULNOGRAM_SESSION, else "
- "~/.config/apache-steward/vulnogram-session.json."
+ "~/.config/apache-magpie/vulnogram-session.json."
),
)
ap.add_argument(
diff --git
a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_update.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_update.py
index 7c71dab..9f96a10 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_update.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/record_update.py
@@ -87,7 +87,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Path to the session JSON. Defaults to "
"$VULNOGRAM_SESSION, else "
- "~/.config/apache-steward/vulnogram-session.json."
+ "~/.config/apache-magpie/vulnogram-session.json."
),
)
ap.add_argument(
diff --git
a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/setup_session.py
b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/setup_session.py
index 2d0d872..dc810ee 100644
--- a/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/setup_session.py
+++ b/tools/cve-tool-vulnogram/oauth-api/src/vulnogram_api/setup_session.py
@@ -32,7 +32,7 @@ session is live; a 302 to ``oauth.apache.org`` means the
value was
typed wrong (or copied without URL-encoding).
The *long-lived secret* is the cookie value. It is written to
-``~/.config/apache-steward/vulnogram-session.json`` (mode 0600,
+``~/.config/apache-magpie/vulnogram-session.json`` (mode 0600,
parent directory 0700) so the file lives outside any project tree
— see the project's *credentials live in $HOME, never in project
tree* convention.
diff --git a/tools/gmail/draft-backends.md b/tools/gmail/draft-backends.md
index 45a05d5..c9c72e4 100644
--- a/tools/gmail/draft-backends.md
+++ b/tools/gmail/draft-backends.md
@@ -95,7 +95,7 @@ who has a credentials file on disk:
- `tools.gmail.oauth_credentials_path` from
`.apache-magpie-overrides/user.md` when set;
- the `$GMAIL_OAUTH_CREDENTIALS` environment variable;
- - the default path `~/.config/apache-steward/gmail-oauth.json`.
+ - the default path `~/.config/apache-magpie/gmail-oauth.json`.
The probe is a single `test -f <path>` — actually parsing the file
or doing a token-refresh probe at this stage would burn HTTP
diff --git a/tools/gmail/oauth-draft/README.md
b/tools/gmail/oauth-draft/README.md
index e2401e4..d122648 100644
--- a/tools/gmail/oauth-draft/README.md
+++ b/tools/gmail/oauth-draft/README.md
@@ -115,7 +115,7 @@ for `security@<project>.apache.org` triage.
| Flag | Purpose |
|---|---|
| `--from-address` | Address baked into the credentials file as the
outgoing `From:`. Defaults to `$GMAIL_FROM`, then `git config user.email`. |
- | `--out` | Output path. Default:
`~/.config/apache-steward/gmail-oauth.json`. |
+ | `--out` | Output path. Default:
`~/.config/apache-magpie/gmail-oauth.json`. |
| `--rm-client-secrets` | Delete the input `client_secrets.json` after
writing the credentials file. |
The script writes the credentials atomically with mode 600 and
@@ -163,7 +163,7 @@ it like an SSH key:
- The setup script writes the file with mode 600 and chmods its parent
directory to 700; do not loosen those.
- Do **not** commit the credentials file. The path lives outside the
- repo tree by default (`~/.config/apache-steward/gmail-oauth.json`).
+ repo tree by default (`~/.config/apache-magpie/gmail-oauth.json`).
- Revoke the refresh token at
<https://myaccount.google.com/permissions> if you suspect it has
leaked.
diff --git a/tools/gmail/oauth-draft/src/oauth_draft/create_draft.py
b/tools/gmail/oauth-draft/src/oauth_draft/create_draft.py
index bfc07e9..014aee5 100644
--- a/tools/gmail/oauth-draft/src/oauth_draft/create_draft.py
+++ b/tools/gmail/oauth-draft/src/oauth_draft/create_draft.py
@@ -198,7 +198,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Path to the OAuth credentials JSON. "
"Defaults to $GMAIL_OAUTH_CREDENTIALS or "
- "~/.config/apache-steward/gmail-oauth.json."
+ "~/.config/apache-magpie/gmail-oauth.json."
),
)
p.add_argument(
diff --git a/tools/gmail/oauth-draft/src/oauth_draft/credentials.py
b/tools/gmail/oauth-draft/src/oauth_draft/credentials.py
index 7c082b2..fb056c8 100644
--- a/tools/gmail/oauth-draft/src/oauth_draft/credentials.py
+++ b/tools/gmail/oauth-draft/src/oauth_draft/credentials.py
@@ -45,7 +45,7 @@ GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/me";
# ``apache-steward`` here as the framework was generalised. Existing
# adopters who still have the file at the old path can either move it
# or set ``$GMAIL_OAUTH_CREDENTIALS`` (or pass ``--credentials``).
-DEFAULT_CREDENTIALS_DIR = pathlib.Path.home() / ".config" / "apache-steward"
+DEFAULT_CREDENTIALS_DIR = pathlib.Path.home() / ".config" / "apache-magpie"
DEFAULT_CREDENTIALS_PATH = DEFAULT_CREDENTIALS_DIR / "gmail-oauth.json"
diff --git a/tools/gmail/oauth-draft/src/oauth_draft/mark_threads_read.py
b/tools/gmail/oauth-draft/src/oauth_draft/mark_threads_read.py
index 9da65c9..bce1a43 100644
--- a/tools/gmail/oauth-draft/src/oauth_draft/mark_threads_read.py
+++ b/tools/gmail/oauth-draft/src/oauth_draft/mark_threads_read.py
@@ -153,7 +153,7 @@ def parse_args(argv: list[str] | None = None) ->
argparse.Namespace:
help=(
"Override the credentials file path. "
"Default: $GMAIL_OAUTH_CREDENTIALS or "
- "~/.config/apache-steward/gmail-oauth.json."
+ "~/.config/apache-magpie/gmail-oauth.json."
),
)
args = ap.parse_args(argv)
diff --git a/tools/gmail/oauth-draft/src/oauth_draft/setup_creds.py
b/tools/gmail/oauth-draft/src/oauth_draft/setup_creds.py
index d13906a..b197faa 100644
--- a/tools/gmail/oauth-draft/src/oauth_draft/setup_creds.py
+++ b/tools/gmail/oauth-draft/src/oauth_draft/setup_creds.py
@@ -27,7 +27,7 @@ Optional flags:
- ``--from-address``: address to bake into the credentials file.
Defaults to ``$GMAIL_FROM`` env var, then ``git config user.email``.
- ``--out``: output path for the credentials file. Defaults to
- ``~/.config/apache-steward/gmail-oauth.json``.
+ ``~/.config/apache-magpie/gmail-oauth.json``.
- ``--rm-client-secrets``: delete the input ``client_secrets.json``
after a successful write. Off by default.
diff --git a/tools/gmail/oauth-draft/tests/test_setup_creds.py
b/tools/gmail/oauth-draft/tests/test_setup_creds.py
index 5a37bcf..2ddb2c5 100644
--- a/tools/gmail/oauth-draft/tests/test_setup_creds.py
+++ b/tools/gmail/oauth-draft/tests/test_setup_creds.py
@@ -78,7 +78,7 @@ def test_parse_args_minimal(monkeypatch):
args = parse_args(["client.json"])
assert args.client_secrets == "client.json"
assert args.from_address == "[email protected]"
- assert args.out.endswith("/.config/apache-steward/gmail-oauth.json")
+ assert args.out.endswith("/.config/apache-magpie/gmail-oauth.json")
assert args.rm_client_secrets is False
diff --git a/tools/privacy-llm/pii.md b/tools/privacy-llm/pii.md
index df1dbce..a8bb73f 100644
--- a/tools/privacy-llm/pii.md
+++ b/tools/privacy-llm/pii.md
@@ -143,7 +143,7 @@ any single ASF project's security tracker.
## The mapping store
-Storage path: **`~/.config/apache-steward/pii-mapping.json`** —
+Storage path: **`~/.config/apache-magpie/pii-mapping.json`** —
home-dir per the framework's tool-credentials rule (see
[`AGENTS.md` — Local setup](../../AGENTS.md#local-setup)).
@@ -161,7 +161,7 @@ Format:
```
- The file is mode `600` and lives outside the project tree —
- the same security posture as `~/.config/apache-steward/gmail-oauth.json`.
+ the same security posture as `~/.config/apache-magpie/gmail-oauth.json`.
- Writes are atomic (`tempfile + os.replace`) so a crash mid-write
cannot leave a half-baked file.
- The mapping is **per-machine, never committed**. Each
@@ -280,7 +280,7 @@ placeholder — see
## What never reaches an LLM
-- The contents of `~/.config/apache-steward/pii-mapping.json`. The
+- The contents of `~/.config/apache-magpie/pii-mapping.json`. The
file is read by `pii-redact` / `pii-reveal` only. Skills MUST
NOT include the mapping in any LLM-bound prompt, summary, or
status comment. If you need to debug what mapped to what, run
diff --git a/tools/privacy-llm/redactor/README.md
b/tools/privacy-llm/redactor/README.md
index 7d45f99..474ca21 100644
--- a/tools/privacy-llm/redactor/README.md
+++ b/tools/privacy-llm/redactor/README.md
@@ -97,7 +97,7 @@ Field types accepted by `--field`:
The mapping is stored at:
```text
-~/.config/apache-steward/pii-mapping.json (default)
+~/.config/apache-magpie/pii-mapping.json (default)
$PII_MAPPING_PATH (env override)
--mapping-path <path> (per-call override)
```
diff --git a/tools/privacy-llm/redactor/src/redactor/list_cmd.py
b/tools/privacy-llm/redactor/src/redactor/list_cmd.py
index d48ae6c..d8c5f2b 100644
--- a/tools/privacy-llm/redactor/src/redactor/list_cmd.py
+++ b/tools/privacy-llm/redactor/src/redactor/list_cmd.py
@@ -44,7 +44,7 @@ def main(argv: list[str] | None = None) -> int:
default=None,
help=(
"Override the mapping file path. "
- "Default: $PII_MAPPING_PATH or
~/.config/apache-steward/pii-mapping.json."
+ "Default: $PII_MAPPING_PATH or
~/.config/apache-magpie/pii-mapping.json."
),
)
parser.add_argument(
diff --git a/tools/privacy-llm/redactor/src/redactor/mapping.py
b/tools/privacy-llm/redactor/src/redactor/mapping.py
index 2926d75..17f3d6e 100644
--- a/tools/privacy-llm/redactor/src/redactor/mapping.py
+++ b/tools/privacy-llm/redactor/src/redactor/mapping.py
@@ -16,7 +16,7 @@
# under the License.
"""Local PII mapping store + identifier generation.
-The mapping file at ``~/.config/apache-steward/pii-mapping.json``
+The mapping file at ``~/.config/apache-magpie/pii-mapping.json``
records ``identifier → {type, value}`` so :mod:`redactor.reveal`
can reverse the substitution made by :mod:`redactor.redact`.
Identifiers are deterministic (first 24 bits of
@@ -39,7 +39,7 @@ from collections.abc import Mapping
MAPPING_VERSION = 1
-DEFAULT_MAPPING_DIR = pathlib.Path.home() / ".config" / "apache-steward"
+DEFAULT_MAPPING_DIR = pathlib.Path.home() / ".config" / "apache-magpie"
DEFAULT_MAPPING_PATH = DEFAULT_MAPPING_DIR / "pii-mapping.json"
ENV_MAPPING_PATH = "PII_MAPPING_PATH"
diff --git a/tools/privacy-llm/redactor/src/redactor/redact.py
b/tools/privacy-llm/redactor/src/redactor/redact.py
index 6fb7d37..6cd8bce 100644
--- a/tools/privacy-llm/redactor/src/redactor/redact.py
+++ b/tools/privacy-llm/redactor/src/redactor/redact.py
@@ -138,7 +138,7 @@ def main(argv: list[str] | None = None) -> int:
default=None,
help=(
"Override the mapping file path. "
- "Default: $PII_MAPPING_PATH or
~/.config/apache-steward/pii-mapping.json."
+ "Default: $PII_MAPPING_PATH or
~/.config/apache-magpie/pii-mapping.json."
),
)
args = parser.parse_args(argv)
diff --git a/tools/privacy-llm/redactor/src/redactor/reveal.py
b/tools/privacy-llm/redactor/src/redactor/reveal.py
index f012b4d..780b4c3 100644
--- a/tools/privacy-llm/redactor/src/redactor/reveal.py
+++ b/tools/privacy-llm/redactor/src/redactor/reveal.py
@@ -75,7 +75,7 @@ def main(argv: list[str] | None = None) -> int:
default=None,
help=(
"Override the mapping file path. "
- "Default: $PII_MAPPING_PATH or
~/.config/apache-steward/pii-mapping.json."
+ "Default: $PII_MAPPING_PATH or
~/.config/apache-magpie/pii-mapping.json."
),
)
args = parser.parse_args(argv)
diff --git a/tools/privacy-llm/redactor/tests/test_mapping.py
b/tools/privacy-llm/redactor/tests/test_mapping.py
index f9d8b55..d4a012a 100644
--- a/tools/privacy-llm/redactor/tests/test_mapping.py
+++ b/tools/privacy-llm/redactor/tests/test_mapping.py
@@ -242,4 +242,4 @@ def test_locate_env_used_when_no_explicit(tmp_path:
pathlib.Path, monkeypatch):
def test_locate_default_when_no_explicit_or_env(monkeypatch):
monkeypatch.delenv("PII_MAPPING_PATH", raising=False)
result = locate_mapping_path(None)
- assert result.parts[-2:] == ("apache-steward", "pii-mapping.json")
+ assert result.parts[-2:] == ("apache-magpie", "pii-mapping.json")
diff --git a/tools/privacy-llm/tool.md b/tools/privacy-llm/tool.md
index 76fdced..fd2c380 100644
--- a/tools/privacy-llm/tool.md
+++ b/tools/privacy-llm/tool.md
@@ -47,7 +47,7 @@ agent's context, and `privacy-llm` is what stops it from
leaking.
| Capability | File | What it covers |
|---|---|---|
-| PII redaction contract | [`pii.md`](pii.md) | Which fields are PII, the
hash-prefixed identifier format (`N-a3f9d2`, `E-b8c247`, …), the local mapping
store at `~/.config/apache-steward/pii-mapping.json`, the redact-then-reveal
lifecycle. |
+| PII redaction contract | [`pii.md`](pii.md) | Which fields are PII, the
hash-prefixed identifier format (`N-a3f9d2`, `E-b8c247`, …), the local mapping
store at `~/.config/apache-magpie/pii-mapping.json`, the redact-then-reveal
lifecycle. |
| Approved-LLM registry | [`models.md`](models.md) | Which LLMs the framework
treats as privacy-approved (Claude Code by default; anything at `*.apache.org`;
local Ollama / vLLM; everything else opt-in), how to declare additions in
`<project-config>/privacy-llm.md`, and what the pre-flight gate checks. |
| Skill-wiring pattern | [`wiring.md`](wiring.md) | The canonical step-by-step
pattern every `<security-list>`- or `<private-list>`-touching skill follows
when applying the contract — Step 0 pre-flight, redact-after-fetch,
reveal-before-send, plus edge cases. Skill `SKILL.md` files link here from
their pre-flight section rather than copying the protocol. |
| Per-project configuration |
[`projects/_template/privacy-llm.md`](../../projects/_template/privacy-llm.md)
| Template the adopter copies into `<project-config>/privacy-llm.md` to declare
their LLM stack, private mailing-list set, collaborator source, and
redaction-tuning knobs (collaborator exemption, enabled field types). Defaults
are documented inline. |
@@ -138,6 +138,6 @@ Concrete invocation patterns are in
| Symptom | Likely cause | Remediation |
|---|---|---|
| Skill refuses to run with "no approved privacy LLM configured" | Adopter has
not yet written `<project-config>/privacy-llm.md`, or it lists no approved
entries | Follow [`docs/setup/privacy-llm.md`](../../docs/setup/privacy-llm.md)
— the default `Claude Code` entry is enough for the local-only case |
-| `pii-reveal` returns text with `N-a3f9d2`-style identifiers still in place |
The mapping file at `~/.config/apache-steward/pii-mapping.json` was deleted,
truncated, or moved | Re-fetch the source; the redactor regenerates identifiers
deterministically from the raw values, but it cannot reverse identifiers it has
no mapping for |
+| `pii-reveal` returns text with `N-a3f9d2`-style identifiers still in place |
The mapping file at `~/.config/apache-magpie/pii-mapping.json` was deleted,
truncated, or moved | Re-fetch the source; the redactor regenerates identifiers
deterministically from the raw values, but it cannot reverse identifiers it has
no mapping for |
| `pii-redact` produces different identifiers across runs | Identifier format
was changed (the framework bumped the hash length, or the prefix scheme) — see
the version field in `pii-mapping.json` | Migration logic lives in the next
framework version's release notes; until then keep the mapping file pinned |
| Skill is meant to read `<security-list>` but is being gated by the
approved-model pre-flight | Adopter has incorrectly classified
`<security-list>` as private in `<project-config>/privacy-llm.md` | Remove
`<security-list>` from the private-list set; PII redaction (which IS required
for `<security-list>`) is independent of the gate |
diff --git a/tools/privacy-llm/wiring.md b/tools/privacy-llm/wiring.md
index 26e3bac..9e92123 100644
--- a/tools/privacy-llm/wiring.md
+++ b/tools/privacy-llm/wiring.md
@@ -94,7 +94,7 @@ Add to the skill's existing Step 0 (pre-flight check) section:
flows (the check itself is the same — the flag only controls
the printed banner). The skill also confirms:
- - `~/.config/apache-steward/` is writable (the redactor's
+ - `~/.config/apache-magpie/` is writable (the redactor's
mapping file lives there). If not, prompt the user to
create it.
- The collaborator-source repository (default: the
@@ -165,7 +165,7 @@ processing of the body:
The redactor returns the body with the matched values
replaced by `<TYPE>-<hex>` identifiers. The mapping file at
- `~/.config/apache-steward/pii-mapping.json` is updated in
+ `~/.config/apache-magpie/pii-mapping.json` is updated in
place.
5. **Use the redacted body for all subsequent processing.**
@@ -237,7 +237,7 @@ project knobs at filter time (step 3 above):
| `gh api` collaborator lookup fails (network, auth, rate-limit) | Skill stops
with an error. Do **not** fall back to "redact everyone including
collaborators" silently — that produces a body where collaborator names are now
identifiers, which downstream skills would not expect. The user retries the
skill once the lookup works. |
| The reporter is *also* a collaborator | The reporter's own values are
excluded from redaction (step 3, first bullet). The collaborator filter does
not apply to them — there is no special second-pass. |
| The body contains a self-reference (`I am X`) where X is a collaborator | X
is filtered out as a collaborator regardless. (Also: probably not a thing —
collaborators rarely send security@ mail about themselves.) |
-| The mapping file at `~/.config/apache-steward/pii-mapping.json` is corrupt |
`pii-redact` returns exit code 2 with the parse error on stderr. The skill
stops; the user investigates the mapping file before re-running. |
+| The mapping file at `~/.config/apache-magpie/pii-mapping.json` is corrupt |
`pii-redact` returns exit code 2 with the parse error on stderr. The skill
stops; the user investigates the mapping file before re-running. |
| `pii-reveal` encounters identifiers not in the local map | They pass through
unchanged. The skill should still complete its outbound, with the unknown
identifiers preserved in the draft text. (This is the cross-machine case: a
colleague redacted, you are revealing.) |
## Skills that follow this pattern
