potiuk · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026 · Oct 25, 2026
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -9,7 +9,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${PLUGIN_ROOT}/hooks/check-upgrade.sh",
+            "command": "/bin/bash -p \"${PLUGIN_ROOT}/plugins/magpie-setup/hooks/check-upgrade.sh\"",
             "timeout": 10
           }
         ]

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -565,7 +565,7 @@ repos:
         name: render-preflight-fixtures (pre-flight eval cases vs the real checker)
         language: system
         entry: python3 tools/dev/render-preflight-fixtures.py
-        files: ^(plugins/magpie-setup/skills/setup/setup_preflight/.*|tools/skill-evals/evals/setup/preflight-floor/fixtures/.*|tools/dev/render-preflight-fixtures\.py)$
+        files: ^(plugins/magpie-setup/skills/setup/setup_preflight/.*|tools/skill-evals/evals/setup/(preflight-floor|welcome-first-run)/fixtures/.*|tools/dev/render-preflight-fixtures\.py)$
         pass_filenames: false
   # something else.
   - repo: local

diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
@@ -54,7 +54,7 @@ extension point = a documented, labelled slot with a tracking issue.
 | [`tools/forwarder-relay`](../../tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](../../tools/gmail/asf-relay.md)) | huntr.com, HackerOne, GHSA relay |
 | [`tools/scan-format`](../../tools/scan-format/) | ASVS | other scanner formats |
 | [`tools/vcs`](../../tools/vcs/) | Git, Mercurial, Fossil, Subversion | Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Perforce [\#605](https://github.com/apache/magpie/issues/605) |
-| Forge / tracker | [`github`](../../tools/github/), [`forgejo`](../../tools/forgejo/) `partial` foundation, [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) `partial-read-only` foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/), [`gitlab`](../../tools/gitlab/) `partial-read-only` foundation | Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issues/606), GitLab [\#305](https://github.com/apache/magpie/issues/305), Bugzilla [\#302](https://github.com/apache/magpie/issues/302) |
+| Forge / tracker | [`github`](../../tools/github/), [`forgejo`](../../tools/forgejo/) `partial` foundation, [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) `partial` foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/), [`gitlab`](../../tools/gitlab/) `partial` foundation | Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issues/606), GitLab [\#305](https://github.com/apache/magpie/issues/305), Bugzilla [\#302](https://github.com/apache/magpie/issues/302) |
 | [`tools/chat`](../../tools/chat/) | [`chat-slack`](../../tools/chat-slack/), [`chat-discord`](../../tools/chat-discord/) | Matrix [\#309](https://github.com/apache/magpie/issues/309), Zulip [\#308](https://github.com/apache/magpie/issues/308) |
 | Agent harness | Claude Code, [Codex](codex.md) `experimental` ([#313](https://github.com/apache/magpie/issues/313)), [Gemini CLI](gemini.md) `experimental` ([#314](https://github.com/apache/magpie/issues/314)), [Local LLM (Ollama / llama.cpp / vLLM)](local-llm.md) ([#315](https://github.com/apache/magpie/issues/315)), [Cursor](cursor.md) ([#316](https://github.com/apache/magpie/issues/316)), [Goose](goose.md) `guide only` ([#319](https://github.com/apache/magpie/issues/319)), [Aider](aider.md) `guide only` ([#317](https://github.com/apache/magpie/issues/317)), [GitHub Copilot](copilot.md) `guide only` ([#318](https://github.com/apache/magpie/issues/318)), [JetBrains Junie](junie.md) `action guard` ([#321](https://github.com/apache/magpie/issues/321)), [Grok](grok.md) `reviewer backend + action guard + spec-loop` ([#1416](https://github.com/apache/magpie/issues/1416)) | Amazon Q [#320](https://github.com/apache/magpie/issues/320)–OpenHands [#322](https://github.com/apache/magpie/issues/322) |
 | Security cross-ref | [`tools/osv`](../../tools/osv/) | — |

diff --git a/docs/labels-and-capabilities.md b/docs/labels-and-capabilities.md
@@ -337,7 +337,7 @@ or a contract-free mix of substrates (e.g. `tools/spec-inventory` is
 | [`tools/egress-gateway`](../tools/egress-gateway/) | `substrate:sandbox` | Egress-allowlist forward proxy (proxy.py plugin); host-level egress chokepoint — defence-in-depth for RFC-AI-0003 §4.4 |
 | [`tools/container-gateway`](../tools/container-gateway/) | `substrate:sandbox` | Per-project policy proxy for the podman / docker API; label-scoped, mount- and privilege-checked container access from inside the sandbox |
 | [`tools/forwarder-relay`](../tools/forwarder-relay/) | `contract:report-relay` | Adapter contract for inbound-relay backends (ASF Security relay, huntr.com, HackerOne triagers). Pure interface spec; adapters declare detection + credit-extraction + reporter-addressing rules. |
-| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` + `contract:tracker` | Coverage: `partial`. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context, branch restriction context for PR-management decisions, pull-request discovery/fetching, read-only commit fetching, read-only diff fetching, comments-only discussion fetching, read-only review-state fetching, Cloud-only pull-request task listing/fetching, read-only merge-check context fetching, and read-only status fetching, plus narrowly scoped pull-request comment creation on Cloud and Data Center and Cloud-only approve/unapprove actions. Native Bitbucket issue operations are not implemented: Atlassian removed the native Bitbucket Cloud Issue Tracker API on 2026-08-20 and Data Center native issues were never supported, so the historical issue CLI surface fails closed before any request. Data Center `pr jira-issues <id>` provides read-only discovery of Jira keys associated with pull-request commits and hands them to the Jira bridge (`tools/jira`) for tracker operations. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Broader linked Jira coverage and the remaining pull-request coverage are incomplete. |
+| [`tools/bitbucket`](../tools/bitbucket/) | `contract:change-request` + `contract:tracker` | Coverage: `partial`. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context, branch restriction context for PR-management decisions, pull-request discovery/fetching, read-only commit fetching, read-only diff fetching, comments-only discussion fetching, read-only review-state fetching, Cloud-only pull-request task listing/fetching, read-only merge-check context fetching, and read-only status fetching, plus narrowly scoped pull-request comment creation on Cloud and Data Center and Cloud-only write actions: `pr review` (with a `comment`, `approve`, or `request-changes` verdict), approve/unapprove, request-changes/remove-request-changes, decline, reject, and `pr merge` (with `pr merge-task-status` to follow an asynchronous merge). Native Bitbucket issue operations are not implemented: Atlassian removed the native Bitbucket Cloud Issue Tracker API on 2026-08-20 and Data Center native issues were never supported, so the historical issue CLI surface fails closed before any request. Data Center `pr jira-issues <id>` provides read-only discovery of Jira keys associated with pull-request commits and hands them to the Jira bridge (`tools/jira`) for tracker operations. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Broader linked Jira coverage and the remaining pull-request coverage are incomplete. |
 | [`tools/forgejo`](../tools/forgejo/) | `contract:tracker` + `contract:source-control` + `contract:change-request` | Coverage: `partial`. Forgejo / Gitea REST API and `tea` CLI forge bridge foundation for issue listing/fetching, confirmed issue creation, body edits, comments, labels, and milestones under `contract:tracker`, git-backed branch/commit/push operations under `contract:source-control`, and pull-request creation via REST API / compare URL and label edits under `contract:change-request`. Project boards are unsupported (`no-op`) due to absence of REST card/column endpoints. The `partial` qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. |
 | [`tools/fossil`](../tools/fossil/) | `contract:tracker` + `contract:source-control` | Fossil SCM forge bridge: integrates local SQLite-backed ticket tracking, wiki, and forum reads with the version-control shim |
 | [`tools/github`](../tools/github/) | `contract:tracker` + `contract:source-control` + `contract:change-request` + `contract:people` | GitHub REST / GraphQL tracker substrate (called by every lifecycle phase) plus the Git source-control binding documented in [`source-control.md`](../tools/github/source-control.md) (runnable backend in [`tools/vcs`](../tools/vcs/)), the pull-request review/merge gate (`change-request`; the ASF default backend, alongside `tools/jira-patch/` and `tools/mail-patch/` for SVN-first projects), and account profiles / collaborators / team membership (`people`) |

diff --git a/docs/mode-economics.md b/docs/mode-economics.md
@@ -95,7 +95,8 @@ block runs as one command. Then the rules prose moved there too, and the
 command now emits the sections its own findings name, so there is no
 second file to read and no per-skill copy of one.
 
-The block is **585 tokens**, against 1,679 before the check existed and
+The block is **635 tokens** (585 before the Subversion personal layer
+joined its path), against 1,679 before the check existed and
 3,271 at its peak. Each of the 65 skills is **1,075–1,081 tokens cheaper
 than on `main`** while carrying the whole check: `ci-runner-audit` 3,281 →
 2,203 (−32.9%), and the sidecar that briefly cost 2,516 tokens × 65 copies

diff --git a/docs/modes.md b/docs/modes.md
@@ -311,6 +311,8 @@ contributor threads on their own. The always-on `setup` and
 | [`setup-isolated-setup-doctor`](../skills/setup-isolated-setup-doctor/SKILL.md) | In-session functional health check of the secure-agent sandbox: probes SSH agent / Yubikey reachability, localhost port access, and filesystem restrictions. |
 | [`setup-status`](../skills/setup-status/SKILL.md) | Render a Markdown adoption dashboard: install method and pin, drift, and which skills are wired in the current repo. |
 | [`setup-welcome-guide`](../skills/setup-welcome-guide/SKILL.md) | Show a Magpie welcome guide on demand — the general one or a family's — and turn a dismissed one back on. |
+| [`setup-complete-upgrade`](../skills/setup-complete-upgrade/SKILL.md) | Finish a Magpie upgrade in one run: check this machine and project against the installed version, apply one approved plan, re-check, and print exact commands for what is out of reach. |
+| [`setup-privacy-llm`](../skills/setup-privacy-llm/SKILL.md) | Decide which LLMs may see this project's private foundation content, write `privacy-llm.md`, and prove it with the approved-model gate and the PII redactor. |
 | [`committer-onboarding`](../skills/committer-onboarding/SKILL.md) | Post-vote committer and PMC onboarding for Apache projects: walks the nominator through every step from ICLA check to welcome announcement for both podlings and TLPs. |
 | [`security-tracker-stats-dashboard`](../skills/security-tracker-stats-dashboard/SKILL.md) | Generate a self-contained HTML dashboard of `<tracker>` statistics (lifecycle-band breakdowns, time-to-triage trends, velocity) without modifying any tracker state. |
 | [`optimize-skill`](../skills/optimize-skill/SKILL.md) | Optimize an existing framework skill by applying restructuring patterns: split oversized SKILL.md into linked sibling docs, trim frontmatter, improve eval alignment. |

diff --git a/docs/security/README.md b/docs/security/README.md
@@ -33,9 +33,9 @@ End-to-end automation for an ASF project's security-issue handling
 process — from inbound report on the project's `security@` mailing
 list through to a published CVE record on `cve.org`. Eleven skills
 that compose into the canonical 16-step lifecycle, three that produce,
-verify, and maintain the project's own security model, plus one
-read-only supporting skill for tracker-stats dashboards (fifteen skills
-total).
+verify, and maintain the project's own security model, one that carries
+that model into an OSS Scanner enrolment, plus one read-only supporting
+skill for tracker-stats dashboards (sixteen skills total).
 
 Why a framework skill family? The 16-step process exists across
 the foundation; every project's security team runs essentially
@@ -204,9 +204,10 @@ below sends, merges, or posts anything without you confirming it.*
 
 ### Security-model skills
 
-The lifecycle skills above route **one report**. These three maintain the
-document they route it against — the project's security model — so that
-routing has something to cite. See
+The lifecycle skills above route **one report**. These four work on the
+document they route it against — the project's security model: three
+maintain it so that routing has something to cite, and one carries it into
+an external scanner's enrolment. See
 [**`security-model-preparation.md`**](security-model-preparation.md) for
 the lifecycle and the rationale.
 
@@ -215,6 +216,7 @@ the lifecycle and the rationale.
 | [`security-model-prepare`](../../skills/security-model-prepare/SKILL.md) | Produce a first model for a project that has none, in draft-first mode, and land it with its discoverability chain as one PR per repository. |
 | [`security-model-verify`](../../skills/security-model-verify/SKILL.md) | Pre-flight an existing model: can an agent mechanically reach it, and does it cover the minimum bar a triager depends on. Discoverability is the only hard gate. |
 | [`security-model-update`](../../skills/security-model-update/SKILL.md) | Read the decision history back into the model — new known-non-finding entries and a model-gap list, regression-checked against past valid reports. |
+| [`security-submit-to-oss-scan`](../../skills/security-submit-to-oss-scan/SKILL.md) | Prepare the enrolment (or update) PR that puts a project into Anthropic's OSS Scanner — `project.yaml`, an offline-capable `Dockerfile`, and a `threat_model.md` derived from the security model — and guide the maintainer through testing it first. |
 
 The rubric these skills measure against is maintained externally by
 Alpha-Omega (<https://github.com/alpha-omega-security/threat-model>) and

diff --git a/docs/setup/README.md b/docs/setup/README.md
@@ -63,9 +63,11 @@ New to Magpie? The [quick start](../quick-start.md) walks the whole path in
 one place — install, the first `/magpie-setup:setup` run, and a recording of it
 happening — plus the other agents and the secure-isolation setup to run next.
 
-The first setup skill you run opens with a one-minute
+The `setup` skill (`/magpie-setup:setup`) opens with a one-minute
 [welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/setup.md):
 the typical flow, what needs configuring, what to ask it, and how to make it yours.
+If no Magpie skill has run here before, the general Magpie welcome comes first and this one on the next `setup` run.
+The other setup-family skills do not show it.
 Dismiss it, or hide it for good, from its last line;
 *"show the setup welcome again"* or `/magpie-setup:welcome-guide setup` brings it back.
 
@@ -157,7 +159,8 @@ for the complete rule.
 | [`setup-isolated-setup-update`](../../skills/setup-isolated-setup-update/SKILL.md) | Surface drift between the installed setup and the framework's latest. |
 | [`setup-privacy-llm`](../../skills/setup-privacy-llm/SKILL.md) | Configure which LLMs may see this project's private foundation mail, then prove it: detect the stack, write `privacy-llm.md` from the matching variant, and run the approved-LLM gate and the PII redactor end to end. |
 | [`setup`](../../skills/setup/SKILL.md) | Adopt and maintain the framework in a project repo through installation, verification, updates, overrides, and unadoption. |
-| [`setup upgrade`](../../skills/setup/upgrade.md) | Pull the framework checkout to latest `origin/main`. |
+| [`setup upgrade`](../../skills/setup/upgrade.md) | Pinned-snapshot install: re-fetch the snapshot per the committed lock, refresh symlinks, reconcile overrides, and refresh the personal layer's pre-flight checker. A marketplace install upgrades through the agent's plugin update instead. |
+| [`setup-complete-upgrade`](../../skills/setup-complete-upgrade/SKILL.md) | Finish a Magpie upgrade in one run: check this machine and project against the installed version, apply one approved plan, re-check, and print exact commands for what is out of reach. |
 | [`setup verify`](../../skills/setup/verify.md) | Verify the framework is integrated correctly into an adopter tracker. |
 | [`setup-status`](../../skills/setup-status/SKILL.md) | Render a Markdown adoption dashboard (install pin, drift, wired agent targets, installed skill families, symlink health) and adjust the wiring in place. |
 | [`setup-shared-config-sync`](../../skills/setup-shared-config-sync/SKILL.md) | Commit + push the user's shared Claude config to its sync repo. |

diff --git a/docs/setup/marketplace.md b/docs/setup/marketplace.md
@@ -610,7 +610,7 @@ automatic while the *changes* stay confirmed.
 | Agent | Mechanism |
 |---|---|
 | **Claude Code** | `SessionStart` hook [`plugins/magpie-setup/hooks/check-upgrade.sh`](../../plugins/magpie-setup/hooks/check-upgrade.sh) compares the installed version to a marker in the plugin's persistent data dir and prompts on change. Deterministic. |
-| **Codex CLI** | The same [`plugins/magpie-setup/hooks/check-upgrade.sh`](../../plugins/magpie-setup/hooks/check-upgrade.sh), wired inline via the plugin's `hooks` block — Codex uses the same event schema and the same `SessionStart` event. Codex sets `PLUGIN_ROOT`/`PLUGIN_DATA` (and the `CLAUDE_*` pair for compatibility), which the script reads. See the caveat below. |
+| **Codex CLI** | The same [`plugins/magpie-setup/hooks/check-upgrade.sh`](../../plugins/magpie-setup/hooks/check-upgrade.sh), wired inline in the `hooks` block of the root plugin's [`.codex-plugin/plugin.json`](../../.codex-plugin/plugin.json) as `/bin/bash -p "${PLUGIN_ROOT}/plugins/magpie-setup/hooks/check-upgrade.sh"` — Codex uses the same event schema and the same `SessionStart` event. For the root plugin `PLUGIN_ROOT` is the repo root, where the script finds the version manifests and the `skills/setup` symlink it needs. Codex sets `PLUGIN_ROOT`/`PLUGIN_DATA` (and the `CLAUDE_*` pair for compatibility), which the script reads. See the caveat below. |
 | **VS Code / Copilot, Cursor, Kiro (AP1)** | None. Agent Plugins 1.0 specifies no hook component and VS Code ignores client extension directories, so there is nothing to fire. Run `/magpie-setup:complete-upgrade` after updating. |
 | **Gemini CLI** | No lifecycle hook; the extension context file [`GEMINI.md`](../../GEMINI.md) instructs the agent to compare the extension version to a recorded marker and prompt on change (LLM-driven, advisory). |
 | Other agents | Run `/magpie-setup:complete-upgrade` manually after updating the package. |