feat(skill-sources): Phase B — fetch/pin/symlink wiring for trusted external skill sources

docs/skill-sources/README.md

@@ -125,8 +125,9 @@ directory draws no eval-coverage advisory because its evals are external).
 
 ## How a trusted skill is installed
 
-The [`setup`](../../skills/setup/SKILL.md) skill drives the fetch (see
-`/magpie-setup skill-sources`). In outline:
+The [`setup`](../../skills/setup/SKILL.md) skill drives the fetch — the
+[`skill-sources`](../../skills/setup/skill-sources.md) sub-action
+(`/magpie-setup skill-sources`). In outline:
 
 1. Read `<project-config>/skill-sources.md` — the trust list. Sources not
    listed there are never fetched.

skills/setup/SKILL.md

@@ -10,6 +10,7 @@ description: |
     `/magpie-setup upgrade` - refresh the gitignored snapshot per the committed lock (main-checkout only)
     `/magpie-setup worktree-init` - symlink a worktree's snapshot to the main's
     `/magpie-setup verify` - health check + drift detection
+    `/magpie-setup skill-sources` - fetch/pin/symlink skills from trusted external sources listed in the adopter trust list (main-checkout only)
     `/magpie-setup override <skill>` - open or scaffold an agentic override in `.apache-magpie-overrides/`
     `/magpie-setup unadopt` - reverse the adoption (snapshot, locks, symlinks, hook, doc sections); preserves `.apache-magpie-overrides/` by default (main-checkout only)
 when_to_use: |
@@ -163,13 +164,32 @@ The drift check on every framework-skill invocation compares
 this against `<committed-lock>` and surfaces any mismatch as a
 proposed `/magpie-setup upgrade`.
 
+### Source locks — the same split, for trusted external sources
+
+Skills pulled from [trusted external
+sources](../../docs/skill-sources/README.md) use their **own**
+pair of locks with the identical committed-pin / local-fingerprint
+split, kept separate from the framework locks so a source re-pin
+never entangles a framework upgrade:
+
+- **`.apache-magpie.sources.lock`** (committed) — the project's
+  per-source pins, one block per source keyed by `id`
+  (`method`/`url`/`ref` + `commit`|`sha512`).
+- **`.apache-magpie.sources.local.lock`** (gitignored) — this
+  machine's per-source fetch fingerprint.
+
+They are written and reconciled by
+[`skill-sources.md`](skill-sources.md) and re-fetched on
+`upgrade`; the format and drift semantics live there.
+
 ## Detail files in this directory
 
 | File | Purpose |
 |---|---|
 | [`adopt.md`](adopt.md) | First-time adoption walk-through — recognise existing-snapshot vs needs-bootstrap, write the two lock files, ask the user which skill families to wire up, create the gitignored symlinks, scaffold `.apache-magpie-overrides/`, install the post-checkout hook, update project docs. The default sub-action. |
 | [`upgrade.md`](upgrade.md) | Refresh the gitignored snapshot per the committed lock, reconcile any agentic overrides + symlinks against the new framework structure, surface conflicts. Drives the on-drift remediation flow. |
 | [`verify.md`](verify.md) | Read-only health check — snapshot present + intact, both lock files in sync, symlinks point at live targets, `.gitignore` correct, `.apache-magpie-overrides/` exists, drift status (committed vs local), the `setup` skill itself is current. |
+| [`skill-sources.md`](skill-sources.md) | Fetch/verify skills from trusted external sources listed in `<project-config>/skill-sources.md`, pin them in the committed `.apache-magpie.sources.lock`, and symlink the provided skills in exactly like framework skills. The runnable half of [trusted external skill sources](../../docs/skill-sources/README.md); the install gate is the adopter trust list. |
 | [`agents.md`](agents.md) | The agent-target registry — *which* directories framework-skill symlinks land in across vendors, and the **canonical-plus-relay** model: `.agents/skills/` is the one canonical home (links into the snapshot/source); every other target (`claude-code`, `github`, holdout natives like Windsurf / Goose) gets a per-skill relay symlink into `.agents/skills/`. Defines active-target selection, SKILL.md format portability, and the Claude-Code-only layer (sandbox/hooks). The source of truth every sub-action consults for the target set. |
 | [`overrides.md`](overrides.md) | Agentic-override file management — open / scaffold an override for a framework skill, list existing overrides, help reconcile when the framework changes the underlying skill's structure on upgrade. |
 | [`unadopt.md`](unadopt.md) | Reverse the adoption — remove snapshot, locks, symlinks, post-checkout hook, `.gitignore` entries, the adoption sections in `README.md` / `AGENTS.md` / `CONTRIBUTING.md`, and the committed `setup` skill itself. Preserves `.apache-magpie-overrides/` by default; `--purge-overrides` removes it too. Surfaces the full removal plan before any write. |
@@ -217,7 +237,7 @@ accept, `upgrade`:
 5. Updates `<local-lock>` to the new fetch.
 
 **Golden rule 4 — `.gitignore` keeps the adopter repo clean.**
-Three things gitignored in the adopter repo:
+Gitignored in the adopter repo:
 
 - `<snapshot-dir>` (the entire framework snapshot — gigabytes
   potentially).
@@ -228,12 +248,19 @@ Three things gitignored in the adopter repo:
   `.claude/skills/` / `.github/skills/` / holdouts (they target
   the canonical entries) — both would dangle in a fresh clone.
   The one exception un-ignored in each dir is `magpie-setup`.
+- `.apache-magpie-sources/` (the gitignored fetch of every
+  trusted external skill source) and
+  `.apache-magpie.sources.local.lock` (per-machine source-fetch
+  fingerprint), when the adopter trusts any source. See
+  [`skill-sources.md`](skill-sources.md).
 
 **Committed**: this skill (`setup`, as the canonical
 `.agents/skills/magpie-setup/` plus its relays), the
-`<committed-lock>`, the `.apache-magpie-overrides/`
-directory, the `.gitignore` entries themselves, any
-project-doc updates the `adopt` sub-action makes.
+`<committed-lock>`, the **`.apache-magpie.sources.lock`**
+per-source pins (the project's committed vouch for each trusted
+source), the `.apache-magpie-overrides/` directory, the
+`.gitignore` entries themselves, any project-doc updates the
+`adopt` sub-action makes.
 
 **Golden rule 5 — `.agents/skills/` is canonical; everything
 else just relays into it.** Regardless of how an adopting
@@ -334,6 +361,7 @@ The skill dispatches by the first positional argument:
 | `/magpie-setup upgrade` | [`upgrade.md`](upgrade.md) | Refresh snapshot per `<committed-lock>` + reconcile overrides + refresh symlinks. **Main-checkout only** — worktrees pick up upgrades automatically via the symlink installed by `worktree-init`. |
 | `/magpie-setup worktree-init` | [`worktree-init.md`](worktree-init.md) | **Worktree-only.** Symlink the worktree's `<snapshot-dir>` to the main checkout's so this worktree shares one framework state. No fetch, no lock files written; idempotent. |
 | `/magpie-setup verify` | [`verify.md`](verify.md) | Read-only health check + drift status report. Works in both main and worktrees. |
+| `/magpie-setup skill-sources` (aka `skill-sources add <id>`) | [`skill-sources.md`](skill-sources.md) | Fetch/verify/pin/symlink skills from the trusted external sources the adopter listed in `<project-config>/skill-sources.md`. **Main-checkout only** — worktrees share the source snapshots via `worktree-init`. |
 | `/magpie-setup override <skill>` | [`overrides.md`](overrides.md) | Open / scaffold an override file. |
 | `/magpie-setup unadopt` | [`unadopt.md`](unadopt.md) | Reverse the adoption. Removes snapshot, locks, symlinks, hook, doc sections, and this skill itself. Preserves `.apache-magpie-overrides/` unless `--purge-overrides` is passed. **Main-checkout only.** |
 

skills/setup/adopt.md

@@ -502,13 +502,28 @@ idempotent — re-add them if they're missing.
 ```text
 /.apache-magpie/
 /.apache-magpie.local.lock
+/.apache-magpie-sources/
+/.apache-magpie.sources.local.lock
 /.claude/settings.local.json
 /.claude/hooks/agent-guard.py
 /.claude/hooks/guards.d/
 __pycache__/
 *.pyc
 ```
 
+The `/.apache-magpie-sources/` and
+`/.apache-magpie.sources.local.lock` lines keep the gitignored
+fetch of every [trusted external skill
+source](../../docs/skill-sources/README.md) and its per-machine
+fetch fingerprint out of the tree — the source counterpart of
+`/.apache-magpie/` + `/.apache-magpie.local.lock`. The committed
+per-source pins (`.apache-magpie.sources.lock`) are **not** ignored;
+they travel with the repo like `<committed-lock>`. These two lines
+are harmless when the adopter trusts no source (the paths simply
+never appear); [`skill-sources.md`](skill-sources.md) also adds
+them idempotently the first time a source is pinned on an older
+adoption.
+
 The `__pycache__/` and `*.pyc` lines (non-anchored — they match at
 any depth) keep the byte-compiled artefacts that framework skill
 scripts emit when run from the adopter checkout (e.g.
@@ -643,6 +658,25 @@ confirm, then create them. Always-on entries are surfaced
 read-only — the prompt is "confirm this list" not "edit this
 list".
 
+## Step 8b — Wire up trusted external-source skills
+
+If `<project-config>/skill-sources.md` (the adopter trust list)
+exists and lists any source, run the
+[`skill-sources`](skill-sources.md) sub-action now as a content
+pass: fetch + verify each trusted source into
+`.apache-magpie-sources/<id>/`, write both source locks, and
+create the canonical + relay `magpie-<name>` symlinks for the
+skills each source `provides` — the same wiring Step 8 does for
+framework skills, just targeting the source snapshots. Nothing is
+fetched if the trust list is absent or empty (the common case);
+this step is then a no-op.
+
+Source skills are `magpie-`-prefixed and gitignored exactly like
+framework skills, so the `.gitignore` block from
+[Step 7](#step-7--gitignore-entries-fresh-only) already covers
+their symlinks; the `.apache-magpie-sources/` snapshot dir and
+`.apache-magpie.sources.local.lock` were added there too.
+
 ## Step 9 — Scaffold `.apache-magpie-overrides/` (FRESH only)
 
 Create `<repo-root>/.apache-magpie-overrides/` (directory)