potiuk opened a new pull request, #136:
URL: https://github.com/apache/airflow-steward/pull/136
## Summary
Today's adoption story: each adopter worktree gets its own gitignored
`.apache-steward/` snapshot, so `adopt` / `upgrade` run independently in every
worktree. That wastes disk, splits the upgrade source of truth, and makes
worktrees drift out of step over time.
New story: every worktree of an adopter shares **one** snapshot — the main
checkout's. `adopt` + `upgrade` only run in the main; each worktree's
`.apache-steward/` is a **symlink** to the main's. Worktrees pick up framework
upgrades the moment the main upgrades.
## Behavior changes
| Sub-action | Main checkout | Worktree |
|---|---|---|
| `/setup-steward adopt` | works as before | **refuses with a `cd
<main-path>` pointer** |
| `/setup-steward upgrade` | works as before | **refuses; explains the
symlink propagates** |
| `/setup-steward worktree-init` (new) | refuses with a "wrong context"
pointer | creates `.apache-steward` symlink to main |
| `/setup-steward unadopt` | works as before | **refuses; suggests `rm
<worktree>/.apache-steward` for worktree-only cleanup** |
| `/setup-steward verify` | works as before | works through the symlink;
warns if missing → recommends `worktree-init` |
Worktree detection: `git rev-parse --git-dir` ≠ `git rev-parse
--git-common-dir`. The main's path is the parent of `git rev-parse
--git-common-dir` resolved through `cd … && pwd`.
## Files
1. **`setup-steward/SKILL.md`** — frontmatter + Sub-actions table grow a
`worktree-init` row; `adopt` / `upgrade` / `unadopt` are flagged `main-checkout
only`. Adds an explicit paragraph explaining the worktree-refusal detection.
2. **`setup-steward/adopt.md`** — Step 0 gains a worktree-refusal as item 2,
with the resolved `<main-path>` surfaced in the error message.
3. **`setup-steward/upgrade.md`** — same Step 0 refusal; explicitly explains
that worktrees pick up the refreshed snapshot automatically via the symlink.
4. **`setup-steward/unadopt.md`** — same Step 0 refusal; notes that unadopt
from a worktree would leave the main + other worktrees half-removed.
5. **`setup-steward/verify.md`** — Snapshot-present check grows two new
branches: worktree + missing → suggest `worktree-init`; worktree + regular dir
→ suggest `worktree-init` (legacy per-worktree snapshot conversion).
6. **`setup-steward/worktree-init.md` (new)** — full recipe. Validates we
are in a worktree, validates the main is adopted, inspects the worktree's
existing `<snapshot-dir>` state (four cases), creates the symlink, verifies the
chain. Idempotent. Does **not** touch `.apache-steward-overrides/` (committed,
worktree-local by design).
## What this PR does *not* cover
- **Auto-symlinking on `git worktree add`**: the framework can't force
adopters to install a post-worktree-add hook. The doc notes "run `setup-steward
worktree-init` once per new worktree" as the UX.
- **`.apache-steward-overrides/`** stays per-worktree by design — different
branches may carry different overrides; symlinking would conflate branches.
- **Existing adopter setups with per-worktree snapshots**: keep working as
before. `verify` will surface the legacy shape with a soft warning ("you can
convert to the symlinked shape via `worktree-init` when convenient") rather
than failing.
## Stacking
Branched off `upstream/main` (post-merge of #131, #132, #133, #134). No
conflict with #135 (which only edits adopt.md Step 9b and AGENTS.md; this PR
edits adopt.md Step 0).
## Test plan
- [ ] In a fresh worktree of an adopted tracker (no `.apache-steward/` yet)
→ run `/setup-steward worktree-init` → confirm symlink created, every committed
skill symlink resolves into main's snapshot.
- [ ] In the main checkout → run `/setup-steward worktree-init` → confirm it
refuses with "use `/setup-steward` / `/setup-steward upgrade` instead".
- [ ] In a worktree → run `/setup-steward adopt` → confirm it refuses with
the main-path pointer.
- [ ] In a worktree → run `/setup-steward upgrade` → confirm it refuses,
explains the symlink propagation, and the operator's next move is `cd <main>`.
- [ ] In a worktree with a legacy per-worktree `.apache-steward/` directory
→ run `/setup-steward worktree-init` → confirm move-aside backup + symlink
replacement, with a per-worktree confirm.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
