skills/setup/worktree-init.md - magpie - Git at Google

 <!-- SPDX-License-Identifier: Apache-2.0
      https://www.apache.org/legal/release-policy.html -->

 # worktree-init — share the main checkout's snapshot from a worktree

 `adopt` and `upgrade` are **main-checkout-only**. A new git
 worktree of an already-adopted tracker repo gets the framework
 state by **symlinking** its `.apache-magpie/` directory to the
 main checkout's snapshot, rather than maintaining its own copy.
 One snapshot on disk, one upgrade source, every worktree always
 current.

 This sub-action is the worktree counterpart of `adopt`:

 - **`adopt`** runs in the main checkout, fetches the snapshot,
   writes both lock files, and wires up symlinks.
 - **`worktree-init`** runs in a worktree, validates the main is
   adopted, and points the worktree's `<snapshot-dir>` at the
   main's. Nothing is fetched; no lock files are written.

 The skill is idempotent: re-running on a worktree that already
 has the right symlink is a no-op.

 ## Step 0 — Pre-flight

 1. **Confirm we are in a git worktree, not the main checkout.**
    Compare `git rev-parse --git-dir` against
    `git rev-parse --git-common-dir`. They are equal in the main
    checkout and different in a worktree. If equal, stop:

    > *"You appear to be in the main checkout (`<path>`).
    > `worktree-init` only runs in a worktree. Use
    > `/magpie-setup` (or `/magpie-setup upgrade`) here
    > instead."*

 2. **Resolve the main checkout's path.** Take
    `$(cd "$(git rev-parse --git-common-dir)" && pwd)`; the
    parent of that is the main checkout's working tree. Pin
    the result as `<main>` for the rest of this flow.

 3. **Confirm the main checkout is adopted.** Check that
    `<main>/.apache-magpie/` exists and that
    `<main>/.apache-magpie.lock` exists. If either is missing,
    stop:

    > *"The main checkout at `<main>` is not adopted yet. From
    > the main checkout: `cd <main> && /magpie-setup`. Re-run
    > `worktree-init` here once that is complete."*

 4. **Inspect the worktree's `<snapshot-dir>` state.** Four
    possibilities, each handled below:

    | Current state | Action |
    |---|---|
    | Missing | Step 1 — create the symlink. |
    | Symlink to `<main>/.apache-magpie/` | No-op. Surface "already wired" and stop. |
    | Symlink to **something else** | Step 1 with a move-aside warning. The skill backs the existing link up, names what it pointed at, and asks the user to confirm before replacing. |
    | Regular directory (per-worktree snapshot from before this convention) | Step 1 with a move-aside warning. Back up the directory to `.apache-magpie.bak.<timestamp>` and create the symlink. **Do not** `rm -rf` without confirmation — the directory may hold uncommitted local edits the operator wants to preserve before the framework standardised on snapshot-from-main. |

 ## Step 1 — Create the snapshot symlink

 ```bash
 ln -s <main>/.apache-magpie <worktree>/.apache-magpie
 ```

 **Trusted external skill sources.** If the main checkout has a
 `.apache-magpie-sources/` directory (the adopter trusts at least
 one [external source](../../docs/skill-sources/README.md)), share
 it the same way so this worktree's source-skill symlinks resolve
 against one snapshot on disk:

 ```bash
 # only when <main>/.apache-magpie-sources exists:
 ln -s <main>/.apache-magpie-sources <worktree>/.apache-magpie-sources
 ```

 Then verify the chain end-to-end:

 - `ls -la <worktree>/.apache-magpie` returns a symlink pointing
   at `<main>/.apache-magpie`.
 - `ls <worktree>/.apache-magpie/skills/` lists the
   same skills as `ls <main>/.apache-magpie/skills/`.
 - when sources are in use, `ls -la <worktree>/.apache-magpie-sources`
   is likewise a symlink to `<main>/.apache-magpie-sources`.

 ## Step 1b — Wire up the worktree's per-target symlinks

 The snapshot symlink in Step 1 only makes the framework's
 *source* available to this worktree. The per-skill symlinks (the
 gitignored entries the agent harness actually resolves) live in
 **every active target dir** ([`agents.md`](agents.md) —
 `.agents/skills/` (universal), `.claude/skills/`,
 `.github/skills/`, plus any present holdout) and are
 **per-worktree** — each working copy needs its own in every
 target. A worktree branched from before adoption
 landed, or branched from a state where the symlinks were
 cleaned, has none on disk.

 Compose the **effective family set** for this worktree:

 - **Opt-in families** the project recorded — read from
   `<main>/.apache-magpie.lock` (the committed lock; the
   worktree shares it via git).
 - **Always-on families** — every `family: setup` skill in the
   snapshot *except* `setup` itself, and every
   `family: utilities` skill, per
   [`SKILL.md` Golden rule 8](SKILL.md#golden-rules) (read the
   `family:` frontmatter key, not the name prefix). These
   are added unconditionally, never read from the lock.

 Wiring follows the **canonical-plus-relay** model
 ([`agents.md`](agents.md)), with no per-layout variation. For each
 framework skill in the effective family set:

 - **Canonical (`.agents/skills/`)** — ensure
   `<worktree>/.agents/skills/magpie-<skill>` →
   `../../.apache-magpie/skills/<skill>/` (the worktree's snapshot
   symlink from Step 1). Create if missing, repair if broken or
   pointing at the wrong path, leave alone if correct.
 - **Relays (`.claude/skills/`, `.github/skills/`, any present
   holdout)** — ensure `<worktree>/<target>/skills/magpie-<skill>`
   → `../../.agents/skills/magpie-<skill>`. Create / repair / leave
   alone the same way.

 All these entries are gitignored and per-worktree.

 The worktree's target directories themselves — `.agents/skills/`,
 `.claude/skills/`, `.github/skills/`, any holdout — are **not**
 framework artefacts; they are checked into the repo as part of the
 adopter's layout, so every worktree inherits them via the
 ordinary `git worktree add` flow. `worktree-init` only wires the
 `magpie-*` entries inside them; it does not touch the
 directories.

 Pick a framework skill symlink that should now exist in **each**
 active target dir (e.g.
 `<worktree>/.agents/skills/magpie-security-issue-sync/SKILL.md`
 and `<worktree>/.claude/skills/magpie-security-issue-sync/SKILL.md`)
 and confirm `readlink -f` resolves each into
 `<main>/.apache-magpie/...` rather than dangling — same
 sanity check as Step 1's bottom bullet, just now end-to-end
 from agent-harness path through the worktree's symlink
 through the snapshot symlink to the framework source, in every
 target.

 ## Step 1c — Add the worktree to its own project-local sandbox allowlists

 Defensive against
 [issue #197](https://github.com/apache/magpie/issues/197) —
 `sandbox.filesystem.allowRead: ["."]` does not in practice cover
 the worktree's working dir, so reads under this worktree fail
 under the sandbox until an explicit absolute path is added. See
 [`setup-isolated-setup-install/SKILL.md` → Step P](../setup-isolated-setup-install/SKILL.md#step-p--project-root-coverage-in-the-sandbox-allowlists)
 for the underlying rationale.

 If `~/.claude/scripts/sandbox-add-project-root.sh` is installed,
 invoke it from the worktree's working directory (no
 `--all-worktrees` flag — only this one worktree needs adding;
 the helper picks up the current worktree's
 `git rev-parse --show-toplevel` and writes the abs path to
 `<this-worktree>/.claude/settings.local.json`):

 ```bash
 "$HOME/.claude/scripts/sandbox-add-project-root.sh"
 ```

 **Invoke with `dangerouslyDisableSandbox: true`** — the target
 `settings.local.json` is in Claude Code's built-in sandbox
 `denyWithinAllow` set, so a sandboxed Bash write fails with
 `operation not permitted`. Surface the bypass proposal to the
 operator *before* invoking; name the helper and the target file
 (`<worktree>/.claude/settings.local.json`); confirm. Reason:
 *"writing project-local sandbox-allowlist entry (issue #197
 fix)"*.

 The helper writes to **project-local** scope, not user-scope —
 each worktree carries its own `.claude/settings.local.json`
 entry, and the per-worktree file is gitignored. The helper is
 idempotent (no-op when already added) and exits 0 when
 prereqs are missing (no `jq`, not in a git repo). Surface a
 one-line recap row for the Step 2 summary:

 - ✓ already covered, OR
 - + added `<worktree-path>`, OR
 - ⚠ helper not installed — `/magpie-setup-isolated-setup-install` to wire it up.

 `worktree-init` does **not** fail when the helper is absent;
 secure-agent isolation is independent of framework adoption.

 ## Step 1d — Seed the worktree's agent-guard PreToolUse hook

 The committed `.claude/settings.json` wires the deterministic
 guard ([`tools/agent-guard`](../../tools/agent-guard/README.md))
 at `$CLAUDE_PROJECT_DIR/.claude/hooks/agent-guard.py` — a
 **per-worktree** path. The script + its `guards.d/` are
 adopter-installed local files synced into the **main** checkout by
 [`adopt.md` Step 12 pass 1](adopt.md#step-12--post-install-sync--worktree-propagation--sandbox-allowlist--sanity-check)
 / [`upgrade.md` Step 6b](upgrade.md#step-6b--sync-locally-installed-hooks-and-configuration)
 and **gitignored** ([`adopt.md` Step 7](adopt.md#step-7--gitignore-entries-fresh-only)).
 Because they are gitignored, no worktree inherits them via git —
 every worktree starts without the script and would run with the
 guard **silently inactive** until seeded.

 This is the agent-driven counterpart of the
 [post-checkout hook's agent-guard seeding](adopt.md#step-10--worktree-aware-post-checkout-hook-fresh-only):
 the git hook covers `git worktree add`, this step covers worktrees
 that pre-date the hook or where its best-effort copy did not run.

 Seed from the main checkout's already-synced copy — a plain file
 copy, the same `<main>` resolved in Step 0:

 ```bash
 # Only when the main has a guard and this worktree has none — never
 # overwrite a copy the worktree already carries (worktree-local guards).
 if [ -f "<main>/.claude/hooks/agent-guard.py" ] &&
    [ ! -f "<worktree>/.claude/hooks/agent-guard.py" ]; then
   mkdir -p "<worktree>/.claude/hooks/guards.d"
   cp "<main>/.claude/hooks/agent-guard.py" "<worktree>/.claude/hooks/agent-guard.py"
   cp "<main>/.claude/hooks/guards.d/"*.py "<worktree>/.claude/hooks/guards.d/" 2>/dev/null || true
 fi
 ```

 Idempotent: a no-op when the worktree already has the script, and
 a no-op when the main has no agent-guard yet (an adopter who has
 not run the Step 12 / Step 6b sync). Surface a one-line recap row
 for Step 2:

 - ✓ already present, OR
 - + seeded from `<main>` (script + N guards), OR
 - ⚠ main has no agent-guard yet — run `/magpie-setup` (or
   `/magpie-setup upgrade`) from the main checkout to sync it.

 `worktree-init` does **not** fail when the main carries no
 agent-guard; the guard is an opt-in adopter-side file, and the
 worktree's framework-skill symlinks are usable without it.

 ## Step 2 — Recap

 Print a short summary:

 - The snapshot symlink that was just created or confirmed.
 - The main checkout's resolved path.
 - The framework version the main is pinned at (read from
   `<main>/.apache-magpie.lock`).
 - The effective family set wired in Step 1b across every
   active target dir (`.agents/skills/`, the `.claude/`/`.github/`
   pair, any present holdout), split into *opt-in* and
   *always-on*, with per-skill ✓ / + / ↻ counts.
 - The sandbox-allowlist recap row from Step 1c.
 - The agent-guard recap row from Step 1d (✓ already present /
   + seeded / ⚠ main has no agent-guard yet).
 - A reminder: `upgrade` from the main, not from the worktree.

 ## Inputs

 | Flag | Effect |
 |---|---|
 | `--force` | Replace an existing `<snapshot-dir>` (symlink or regular dir) without the confirmation prompt. Skips the move-aside backup. Use only when you are sure the existing state holds nothing worth keeping. |
 | `dry-run` | Show what the skill would do without writing anything. |

 ## Adopter overrides

 This sub-action does **not** touch `.apache-magpie-overrides/`.
 That directory is committed in the tracker repo and is
 worktree-local by design — different branches may carry
 different overrides. Symlinking it would conflate branches.

 ## What this sub-action is NOT for

 - **Fetching the framework.** Use `adopt` in the main checkout
   first.
 - **Upgrading the framework version.** Use `upgrade` in the
   main checkout; the symlink means every worktree sees the
   refreshed snapshot immediately.
 - **Auto-running on `git worktree add`.** Adopters who want
   automatic worktree initialisation can wrap `git worktree add`
   with a script that calls `/magpie-setup worktree-init` —
   the framework does not install that wrapper.

 ## Failure modes

 | Symptom | Likely cause | Fix |
 |---|---|---|
 | Step 0 step 3 stops with "main checkout not adopted" | The main has never run `adopt`. | `cd <main> && /magpie-setup`, then re-run `worktree-init` here. |
 | `worktree-init` runs but skills still fail to resolve | The per-target `magpie-<skill>` symlinks (in `.agents/skills/`, the `.claude/`/`.github/` pair, or a holdout) are missing from this worktree's commit (the worktree was branched from before `adopt` ran on main). | Re-run `worktree-init` from main's `adopt` flow afterwards, or `git merge` / `git rebase` the branch carrying the symlink commits. |
 | `<snapshot-dir>` is a regular directory and `--force` is not passed | A previous worktree snapshot is still on disk. | Re-run the skill, accept the move-aside prompt, then optionally inspect `.apache-magpie.bak.<timestamp>` for any non-snapshot content before deleting. |
	<!-- SPDX-License-Identifier: Apache-2.0
	https://www.apache.org/legal/release-policy.html -->

	# worktree-init — share the main checkout's snapshot from a worktree

	`adopt` and `upgrade` are main-checkout-only. A new git
	worktree of an already-adopted tracker repo gets the framework
	state by symlinking its `.apache-magpie/` directory to the
	main checkout's snapshot, rather than maintaining its own copy.
	One snapshot on disk, one upgrade source, every worktree always
	current.

	This sub-action is the worktree counterpart of `adopt`:

	- `adopt` runs in the main checkout, fetches the snapshot,
	writes both lock files, and wires up symlinks.
	- `worktree-init` runs in a worktree, validates the main is
	adopted, and points the worktree's `<snapshot-dir>` at the
	main's. Nothing is fetched; no lock files are written.

	The skill is idempotent: re-running on a worktree that already
	has the right symlink is a no-op.

	## Step 0 — Pre-flight

	1. Confirm we are in a git worktree, not the main checkout.
	Compare `git rev-parse --git-dir` against
	`git rev-parse --git-common-dir`. They are equal in the main
	checkout and different in a worktree. If equal, stop:

	> *"You appear to be in the main checkout (`<path>`).
	> `worktree-init` only runs in a worktree. Use
	> `/magpie-setup` (or `/magpie-setup upgrade`) here
	> instead."*

	2. Resolve the main checkout's path. Take
	`$(cd "$(git rev-parse --git-common-dir)" && pwd)`; the
	parent of that is the main checkout's working tree. Pin
	the result as `<main>` for the rest of this flow.

	3. Confirm the main checkout is adopted. Check that
	`<main>/.apache-magpie/` exists and that
	`<main>/.apache-magpie.lock` exists. If either is missing,
	stop:

	> *"The main checkout at `<main>` is not adopted yet. From
	> the main checkout: `cd <main> && /magpie-setup`. Re-run
	> `worktree-init` here once that is complete."*

	4. Inspect the worktree's `<snapshot-dir>` state. Four
	possibilities, each handled below:

	\| Current state \| Action \|
	\|---\|---\|
	\| Missing \| Step 1 — create the symlink. \|
	\| Symlink to `<main>/.apache-magpie/` \| No-op. Surface "already wired" and stop. \|
	\| Symlink to something else \| Step 1 with a move-aside warning. The skill backs the existing link up, names what it pointed at, and asks the user to confirm before replacing. \|
	\| Regular directory (per-worktree snapshot from before this convention) \| Step 1 with a move-aside warning. Back up the directory to `.apache-magpie.bak.<timestamp>` and create the symlink. Do not `rm -rf` without confirmation — the directory may hold uncommitted local edits the operator wants to preserve before the framework standardised on snapshot-from-main. \|

	## Step 1 — Create the snapshot symlink

	```bash
	ln -s <main>/.apache-magpie <worktree>/.apache-magpie
	```

	Trusted external skill sources. If the main checkout has a
	`.apache-magpie-sources/` directory (the adopter trusts at least
	one [external source](../../docs/skill-sources/README.md)), share
	it the same way so this worktree's source-skill symlinks resolve
	against one snapshot on disk:

	```bash
	# only when <main>/.apache-magpie-sources exists:
	ln -s <main>/.apache-magpie-sources <worktree>/.apache-magpie-sources
	```

	Then verify the chain end-to-end:

	- `ls -la <worktree>/.apache-magpie` returns a symlink pointing
	at `<main>/.apache-magpie`.
	- `ls <worktree>/.apache-magpie/skills/` lists the
	same skills as `ls <main>/.apache-magpie/skills/`.
	- when sources are in use, `ls -la <worktree>/.apache-magpie-sources`
	is likewise a symlink to `<main>/.apache-magpie-sources`.

	## Step 1b — Wire up the worktree's per-target symlinks

	The snapshot symlink in Step 1 only makes the framework's
	source available to this worktree. The per-skill symlinks (the
	gitignored entries the agent harness actually resolves) live in
	every active target dir ([`agents.md`](agents.md) —
	`.agents/skills/` (universal), `.claude/skills/`,
	`.github/skills/`, plus any present holdout) and are
	per-worktree — each working copy needs its own in every
	target. A worktree branched from before adoption
	landed, or branched from a state where the symlinks were
	cleaned, has none on disk.

	Compose the effective family set for this worktree:

	- Opt-in families the project recorded — read from
	`<main>/.apache-magpie.lock` (the committed lock; the
	worktree shares it via git).
	- Always-on families — every `family: setup` skill in the
	snapshot except `setup` itself, and every
	`family: utilities` skill, per
	[`SKILL.md` Golden rule 8](SKILL.md#golden-rules) (read the
	`family:` frontmatter key, not the name prefix). These
	are added unconditionally, never read from the lock.

	Wiring follows the canonical-plus-relay model
	([`agents.md`](agents.md)), with no per-layout variation. For each
	framework skill in the effective family set:

	- Canonical (`.agents/skills/`) — ensure
	`<worktree>/.agents/skills/magpie-<skill>` →
	`../../.apache-magpie/skills/<skill>/` (the worktree's snapshot
	symlink from Step 1). Create if missing, repair if broken or
	pointing at the wrong path, leave alone if correct.
	- **Relays (`.claude/skills/`, `.github/skills/`, any present
	holdout)** — ensure `<worktree>/<target>/skills/magpie-<skill>`
	→ `../../.agents/skills/magpie-<skill>`. Create / repair / leave
	alone the same way.

	All these entries are gitignored and per-worktree.

	The worktree's target directories themselves — `.agents/skills/`,
	`.claude/skills/`, `.github/skills/`, any holdout — are not
	framework artefacts; they are checked into the repo as part of the
	adopter's layout, so every worktree inherits them via the
	ordinary `git worktree add` flow. `worktree-init` only wires the
	`magpie-*` entries inside them; it does not touch the
	directories.

	Pick a framework skill symlink that should now exist in each
	active target dir (e.g.
	`<worktree>/.agents/skills/magpie-security-issue-sync/SKILL.md`
	and `<worktree>/.claude/skills/magpie-security-issue-sync/SKILL.md`)
	and confirm `readlink -f` resolves each into
	`<main>/.apache-magpie/...` rather than dangling — same
	sanity check as Step 1's bottom bullet, just now end-to-end
	from agent-harness path through the worktree's symlink
	through the snapshot symlink to the framework source, in every
	target.

	## Step 1c — Add the worktree to its own project-local sandbox allowlists

	Defensive against
	[issue #197](https://github.com/apache/magpie/issues/197) —
	`sandbox.filesystem.allowRead: ["."]` does not in practice cover
	the worktree's working dir, so reads under this worktree fail
	under the sandbox until an explicit absolute path is added. See
	[`setup-isolated-setup-install/SKILL.md` → Step P](../setup-isolated-setup-install/SKILL.md#step-p--project-root-coverage-in-the-sandbox-allowlists)
	for the underlying rationale.

	If `~/.claude/scripts/sandbox-add-project-root.sh` is installed,
	invoke it from the worktree's working directory (no
	`--all-worktrees` flag — only this one worktree needs adding;
	the helper picks up the current worktree's
	`git rev-parse --show-toplevel` and writes the abs path to
	`<this-worktree>/.claude/settings.local.json`):

	```bash
	"$HOME/.claude/scripts/sandbox-add-project-root.sh"
	```

	Invoke with `dangerouslyDisableSandbox: true` — the target
	`settings.local.json` is in Claude Code's built-in sandbox
	`denyWithinAllow` set, so a sandboxed Bash write fails with
	`operation not permitted`. Surface the bypass proposal to the
	operator before invoking; name the helper and the target file
	(`<worktree>/.claude/settings.local.json`); confirm. Reason:
	*"writing project-local sandbox-allowlist entry (issue #197
	fix)"*.

	The helper writes to project-local scope, not user-scope —
	each worktree carries its own `.claude/settings.local.json`
	entry, and the per-worktree file is gitignored. The helper is
	idempotent (no-op when already added) and exits 0 when
	prereqs are missing (no `jq`, not in a git repo). Surface a
	one-line recap row for the Step 2 summary:

	- ✓ already covered, OR
	- + added `<worktree-path>`, OR
	- ⚠ helper not installed — `/magpie-setup-isolated-setup-install` to wire it up.

	`worktree-init` does not fail when the helper is absent;
	secure-agent isolation is independent of framework adoption.

	## Step 1d — Seed the worktree's agent-guard PreToolUse hook

	The committed `.claude/settings.json` wires the deterministic
	guard ([`tools/agent-guard`](../../tools/agent-guard/README.md))
	at `$CLAUDE_PROJECT_DIR/.claude/hooks/agent-guard.py` — a
	per-worktree path. The script + its `guards.d/` are
	adopter-installed local files synced into the main checkout by
	[`adopt.md` Step 12 pass 1](adopt.md#step-12--post-install-sync--worktree-propagation--sandbox-allowlist--sanity-check)
	/ [`upgrade.md` Step 6b](upgrade.md#step-6b--sync-locally-installed-hooks-and-configuration)
	and gitignored ([`adopt.md` Step 7](adopt.md#step-7--gitignore-entries-fresh-only)).
	Because they are gitignored, no worktree inherits them via git —
	every worktree starts without the script and would run with the
	guard silently inactive until seeded.

	This is the agent-driven counterpart of the
	[post-checkout hook's agent-guard seeding](adopt.md#step-10--worktree-aware-post-checkout-hook-fresh-only):
	the git hook covers `git worktree add`, this step covers worktrees
	that pre-date the hook or where its best-effort copy did not run.

	Seed from the main checkout's already-synced copy — a plain file
	copy, the same `<main>` resolved in Step 0:

	```bash
	# Only when the main has a guard and this worktree has none — never
	# overwrite a copy the worktree already carries (worktree-local guards).
	if [ -f "<main>/.claude/hooks/agent-guard.py" ] &&
	[ ! -f "<worktree>/.claude/hooks/agent-guard.py" ]; then
	mkdir -p "<worktree>/.claude/hooks/guards.d"
	cp "<main>/.claude/hooks/agent-guard.py" "<worktree>/.claude/hooks/agent-guard.py"
	cp "<main>/.claude/hooks/guards.d/"*.py "<worktree>/.claude/hooks/guards.d/" 2>/dev/null \|\| true
	fi
	```

	Idempotent: a no-op when the worktree already has the script, and
	a no-op when the main has no agent-guard yet (an adopter who has
	not run the Step 12 / Step 6b sync). Surface a one-line recap row
	for Step 2:

	- ✓ already present, OR
	- + seeded from `<main>` (script + N guards), OR
	- ⚠ main has no agent-guard yet — run `/magpie-setup` (or
	`/magpie-setup upgrade`) from the main checkout to sync it.

	`worktree-init` does not fail when the main carries no
	agent-guard; the guard is an opt-in adopter-side file, and the
	worktree's framework-skill symlinks are usable without it.

	## Step 2 — Recap

	Print a short summary:

	- The snapshot symlink that was just created or confirmed.
	- The main checkout's resolved path.
	- The framework version the main is pinned at (read from
	`<main>/.apache-magpie.lock`).
	- The effective family set wired in Step 1b across every
	active target dir (`.agents/skills/`, the `.claude/`/`.github/`
	pair, any present holdout), split into opt-in and
	always-on, with per-skill ✓ / + / ↻ counts.
	- The sandbox-allowlist recap row from Step 1c.
	- The agent-guard recap row from Step 1d (✓ already present /
	+ seeded / ⚠ main has no agent-guard yet).
	- A reminder: `upgrade` from the main, not from the worktree.

	## Inputs

	\| Flag \| Effect \|
	\|---\|---\|
	\| `--force` \| Replace an existing `<snapshot-dir>` (symlink or regular dir) without the confirmation prompt. Skips the move-aside backup. Use only when you are sure the existing state holds nothing worth keeping. \|
	\| `dry-run` \| Show what the skill would do without writing anything. \|

	## Adopter overrides

	This sub-action does not touch `.apache-magpie-overrides/`.
	That directory is committed in the tracker repo and is
	worktree-local by design — different branches may carry
	different overrides. Symlinking it would conflate branches.

	## What this sub-action is NOT for

	- Fetching the framework. Use `adopt` in the main checkout
	first.
	- Upgrading the framework version. Use `upgrade` in the
	main checkout; the symlink means every worktree sees the
	refreshed snapshot immediately.
	- Auto-running on `git worktree add`. Adopters who want
	automatic worktree initialisation can wrap `git worktree add`
	with a script that calls `/magpie-setup worktree-init` —
	the framework does not install that wrapper.

	## Failure modes

	\| Symptom \| Likely cause \| Fix \|
	\|---\|---\|---\|
	\| Step 0 step 3 stops with "main checkout not adopted" \| The main has never run `adopt`. \| `cd <main> && /magpie-setup`, then re-run `worktree-init` here. \|
	\| `worktree-init` runs but skills still fail to resolve \| The per-target `magpie-<skill>` symlinks (in `.agents/skills/`, the `.claude/`/`.github/` pair, or a holdout) are missing from this worktree's commit (the worktree was branched from before `adopt` ran on main). \| Re-run `worktree-init` from main's `adopt` flow afterwards, or `git merge` / `git rebase` the branch carrying the symlink commits. \|
	\| `<snapshot-dir>` is a regular directory and `--force` is not passed \| A previous worktree snapshot is still on disk. \| Re-run the skill, accept the move-aside prompt, then optionally inspect `.apache-magpie.bak.<timestamp>` for any non-snapshot content before deleting. \|