Two-tier skill surfaces: admit internal library skills from the private plugin checkout

[jeonghun-jj-lee]

Important

Problem

Amicode's brainstorming cannot run end-to-end: its publish and decompose steps need skills that are tagged surface: internal, but the extension's library-skill resolver stages only surface: public skills from every root — internal skills have no path to Amicode at all, even for team members who hold the private plugin checkout.

Approach

Make the resolver's surface guard per-root: the dev's private plugin checkout (the first library root) admits {public, internal}; the vendored public bundle (the fallback root) admits {public} only. Checkout presence is the eligibility proof — internal skill content exists only in the private repo, so nobody can stage skills they don't already possess.

Approaches Considered

• Per-root surface eligibility (chosen) — smallest change at the documented seam; no new infrastructure; reverses the "no library-level entitlement seam" invariant deliberately (ADR-0003).
• Entitlement-gated runtime fetch of an internal tarball — rejected: new release/download machinery for users who don't exist (team members without a checkout).
• Scrub the internal skills to public — rejected: team policy keeps dev-workflow skills internal.
• Keep public-only resolution — rejected: brainstorming stays dangling at publish.

Scope

In: typed library roots ({ path, surfaces }) at the resolver seam · resolver + packaging tests · settings-override back-compat note · skills.lock.json bump to the post-retag public release.
Out: plugin-side re-tags and brainstorming edits (companion issue, plugin repo) · the agent-fleet port · profile-level preferences.

Assumptions / Open Qs

• Every team Amicode user has the private plugin checkout (true per current onboarding).
• The settings-level library-root override keeps working; its value shape changes and needs a back-compat note.

---

Acceptance Criteria

1. With the private plugin checkout present, a session's skill index includes surface: internal skills and stages them into the session skill directory.
2. With only the vendored bundle root, the index and staging exclude every surface: internal skill.
3. Untagged or malformed skills are dropped from every root with a logged warning.
4. The bundle root drops internal even if a staged artifact somehow contains one (defense-in-depth test).
5. skills.lock.json pins the first public release cut after the plugin re-tags; implement-issue and break-into-subissues are absent from the vendored set.

Key Decisions

• Checkout presence IS the eligibility proof; no runtime download, mint, or verification.
• The seam is the existing surface guard in the library-skill resolver; library roots become typed, preserving first-root-wins by directory name.
• The bundle root keeps the public-only guard as defense in depth on top of the extract pipeline's guarantee.

Constraints & Invariants

• The vendored bundle must never ship internal skills; the existing staging invariant (session skill path points at the staged set, never a library root) is preserved.
• This issue body carries no private markers (no private-package names, closed-vault names, personal paths, or internal codenames).

Prior Art / Patterns

• The resolver's documented surface guard and its "no library-level entitlement seam" invariant comment (reversed by ADR-0003).
• The extension's pinned skill vendoring (skills.lock.json + fetch script) and first-root-wins library roots.
• The plugin repo's surface: taxonomy, extract script, and leak-guard (the tag-level half of the boundary).

Source

Design session 2026-08-02 (brainstorming → grill-with-docs). Durable record: ADR-0003 in this repo. Companion issue: harmoniqs/amico-plugin#52 (plugin-side re-tags + brainstorming terminus choice).

Notes

Sequencing: the plugin PR lands first, CI cuts the new public release, then this PR bumps the lock to it. Marketplace users keep the two re-tagged skills until the lock bump — intended lag, no breakage.