agentbundle 0.2.0__py3-none-any.whl

agentbundle/build/shared_libs.py

@@ -0,0 +1,309 @@
+"""T4: shared-libs/ build-pipeline primitive class.
+
+Source rule: ``packs/<pack>/.apm/shared-libs/*.py``.
+Target rule: for every skill in any pack whose ``SKILL.md`` declares
+``metadata.auth: creds``, project each ``shared-libs/*.py`` byte-
+identical into that skill's ``scripts/`` directory; create
+``scripts/`` if absent.
+
+This module owns both halves of the projection contract:
+
+- ``apply_projection(packs_dir)`` — write the files. Called by
+  ``make build-self``.
+- ``check_drift(packs_dir)`` — read-only gate. Returns a list of
+  drift descriptions (empty list == clean). Each description
+  classifies one of the three outcomes RFC-0013 § 4c pins:
+    * **modified** — projected file exists but bytes diverge from source
+    * **missing** — consumer declares ``auth: creds`` but projected file absent
+    * **orphaned** — projected file present but consumer no longer
+      declares ``auth: creds`` (or the source has been removed)
+
+Inter-pack collision: two packs both shipping ``shared-libs/<file>``
+under the same basename is a hard error (``ValueError``) at
+projection time. The v1 catalogue ships one source pack
+(``credential-brokers``); the rail exists to refuse a future
+second-pack collision before it can silently overwrite.
+
+The detection of ``metadata.auth: creds`` is a regex scan against
+``SKILL.md`` text, not a full YAML parse. The strict lint
+(``tools/lint-agent-artifacts.py``) does the YAML round-trip;
+this module only needs to know *which* skills are consumers, and
+the regex is stdlib-only — the build pipeline carries no PyYAML
+dependency.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+# Pin the source path so a downstream consumer that wants to
+# enumerate shim sources doesn't hardcode the literal repeatedly.
+SOURCE_SUBDIR = ".apm/shared-libs"
+
+# Static allow-list of basenames the build pipeline recognises as
+# shim files. Used by the orphan-rail when ``collect_sources`` returns
+# empty (a future PR removes the shared-libs source) — without this,
+# the orphan check would key on an empty source set and silently miss
+# stale projected copies under consumer skills.
+KNOWN_SHIM_BASENAMES: frozenset[str] = frozenset({
+    "credentials_shim.py",
+    "_keychain_macos.py",
+    "_credman_windows.py",
+})
+
+# Regex match against `auth: creds` as an indented mapping value under
+# `metadata:`. The shape we look for, anchored to start-of-line:
+#     metadata:
+#       ...
+#       auth: creds
+# We don't try to honour YAML's full grammar — quoted form
+# (`auth: "creds"`) and inline form (`metadata: { auth: creds }`) are
+# refused by the lint, so they cannot reach the build pipeline.
+# An unquoted scalar token is what every in-tree credentialed skill
+# carries today.
+_AUTH_CREDS_RE = re.compile(
+    r"^[ \t]+auth:[ \t]+creds[ \t]*(?:#.*)?$",
+    re.MULTILINE,
+)
+
+
+@dataclass(frozen=True)
+class SharedLibProjection:
+    """One concrete projection: copy `source` to `target`."""
+
+    source: Path
+    target: Path
+
+
+def collect_sources(packs_dir: Path) -> dict[str, Path]:
+    """Return ``{basename → source_path}`` for every ``.apm/shared-libs/*.py``.
+
+    Raises ``ValueError`` on inter-pack basename collision — two packs
+    shipping the same basename produces non-deterministic projection
+    order and silent overwrites; refuse hard at enumeration time.
+    """
+    sources: dict[str, Path] = {}
+    for pack in sorted(packs_dir.iterdir()):
+        if not pack.is_dir() or not (pack / "pack.toml").exists():
+            continue
+        shared = pack / SOURCE_SUBDIR
+        if not shared.is_dir():
+            continue
+        for src in sorted(shared.glob("*.py")):
+            if src.name in sources:
+                raise ValueError(
+                    f"shared-libs collision: '{src.name}' shipped by both "
+                    f"{sources[src.name]} and {src}"
+                )
+            sources[src.name] = src
+    return sources
+
+
+def _skill_declares_auth_creds(skill_md: Path) -> bool:
+    """Return True if ``SKILL.md``'s frontmatter declares ``auth: creds``.
+
+    Scoped to the frontmatter — text between the first pair of ``---``
+    delimiters. A body-only mention (e.g. inside a code fence) is not
+    a declaration.
+    """
+    try:
+        text = skill_md.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return False
+    end = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+    if end is None:
+        return False
+    fm = "\n".join(lines[1:end])
+    return _AUTH_CREDS_RE.search(fm) is not None
+
+
+def find_creds_consumers(packs_dir: Path) -> list[Path]:
+    """Return every skill-source directory whose ``SKILL.md`` declares
+    ``auth: creds``. Sorted for deterministic projection order.
+    """
+    consumers: list[Path] = []
+    for pack in sorted(packs_dir.iterdir()):
+        if not pack.is_dir() or not (pack / "pack.toml").exists():
+            continue
+        skills_dir = pack / ".apm" / "skills"
+        if not skills_dir.is_dir():
+            continue
+        for skill_dir in sorted(skills_dir.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.is_file():
+                continue
+            if _skill_declares_auth_creds(skill_md):
+                consumers.append(skill_dir)
+    return consumers
+
+
+def compute_projections(packs_dir: Path) -> list[SharedLibProjection]:
+    """Return the full list of ``(source → target)`` pairs.
+
+    Order: outer loop over consumers (sorted), inner loop over source
+    basenames (sorted). Deterministic — drift gates depend on it.
+    """
+    sources = collect_sources(packs_dir)
+    if not sources:
+        return []
+    consumers = find_creds_consumers(packs_dir)
+    out: list[SharedLibProjection] = []
+    for skill_dir in consumers:
+        scripts = skill_dir / "scripts"
+        for basename in sorted(sources):
+            out.append(
+                SharedLibProjection(
+                    source=sources[basename],
+                    target=scripts / basename,
+                )
+            )
+    return out
+
+
+def apply_projection(packs_dir: Path) -> None:
+    """Write every projection target and remove orphans. Creates
+    ``scripts/`` if absent.
+
+    Called by ``make build-self``. Idempotent — running twice produces
+    the same on-disk state.
+
+    Three drift outcomes RFC-0013 § 4c pins are all resolved here:
+      * **missing** → file written from source
+      * **modified** → file overwritten from source
+      * **orphaned** → file removed (consumer no longer declares
+        ``auth: creds``, OR the source basename is no longer shipped)
+    """
+    projections = compute_projections(packs_dir)
+    expected_targets = {p.target for p in projections}
+    # Write current set first so an orphan removed below cannot be
+    # mistaken for a missing write that needs re-running.
+    for proj in projections:
+        proj.target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(proj.source, proj.target)
+    # Orphan removal uses the static basename allow-list so the rail
+    # still fires when ``collect_sources`` returns empty (the source
+    # pack has been dropped). Without the static list, the orphan
+    # set would silently be empty and stale projected copies would
+    # survive.
+    for existing in _enumerate_existing_projections(packs_dir, set(KNOWN_SHIM_BASENAMES)):
+        if existing not in expected_targets:
+            try:
+                existing.unlink()
+            except FileNotFoundError:  # pragma: no cover — race-only
+                pass
+
+
+def _enumerate_existing_projections(
+    packs_dir: Path, source_basenames: set[str]
+) -> list[Path]:
+    """Return every existing projected file in any skill's ``scripts/``
+    whose basename matches a shared-libs source.
+
+    Used to detect orphans: a projected file that exists on disk but
+    is no longer claimed by any (source × creds-consumer) pairing.
+    """
+    found: list[Path] = []
+    for pack in sorted(packs_dir.iterdir()):
+        if not pack.is_dir() or not (pack / "pack.toml").exists():
+            continue
+        skills_dir = pack / ".apm" / "skills"
+        if not skills_dir.is_dir():
+            continue
+        for skill_dir in sorted(skills_dir.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            scripts = skill_dir / "scripts"
+            if not scripts.is_dir():
+                continue
+            for entry in sorted(scripts.iterdir()):
+                if entry.is_file() and entry.name in source_basenames:
+                    found.append(entry)
+    return found
+
+
+def check_drift(packs_dir: Path) -> list[str]:
+    """Return drift descriptions for ``make build-check``.
+
+    Three outcomes per RFC-0013 § 4c:
+        * **modified** — projected bytes diverge from source
+        * **missing** — consumer declares ``auth: creds`` but file absent
+        * **orphaned** — projected file present, no claiming pairing
+
+    Each description ends with the regeneration command so the
+    operator can resolve drift in one invocation.
+    """
+    drifts: list[str] = []
+    try:
+        sources = collect_sources(packs_dir)
+    except ValueError as exc:
+        # Collision blocks the projection entirely — report and stop.
+        drifts.append(f"[shared-libs] {exc}; run: make build-self")
+        return drifts
+    if not sources:
+        # No source pack carries shared-libs/. The orphan rail still
+        # fires: stale projected copies under any consumer skill must
+        # surface, otherwise dropping the source pack silently leaves
+        # vendored copies behind. Use the static basename allow-list
+        # so the rail keys on a known set rather than the (empty)
+        # source set.
+        for existing in _enumerate_existing_projections(
+            packs_dir, set(KNOWN_SHIM_BASENAMES)
+        ):
+            drifts.append(
+                f"[shared-libs] orphaned: "
+                f"{existing.relative_to(packs_dir.parent).as_posix()} "
+                f"present but no source pack ships shared-libs/ "
+                f"(remove the file); "
+                f"run: make build-self FORCE=1"
+            )
+        return drifts
+
+    expected_targets: set[Path] = set()
+    for proj in compute_projections(packs_dir):
+        expected_targets.add(proj.target)
+        source_bytes = proj.source.read_bytes()
+        if not proj.target.exists():
+            drifts.append(
+                f"[shared-libs] missing: "
+                f"{proj.target.relative_to(packs_dir.parent).as_posix()} "
+                f"(consumer declares 'auth: creds'; source: "
+                f"{proj.source.relative_to(packs_dir.parent).as_posix()}); "
+                f"run: make build-self FORCE=1"
+            )
+            continue
+        actual_bytes = proj.target.read_bytes()
+        if actual_bytes != source_bytes:
+            drifts.append(
+                f"[shared-libs] modified: "
+                f"{proj.target.relative_to(packs_dir.parent).as_posix()} "
+                f"diverges from "
+                f"{proj.source.relative_to(packs_dir.parent).as_posix()}; "
+                f"run: make build-self FORCE=1"
+            )
+
+    # Orphan check: any projected file whose basename matches a known
+    # source but is NOT in expected_targets is orphaned.
+    for existing in _enumerate_existing_projections(packs_dir, set(sources)):
+        if existing not in expected_targets:
+            drifts.append(
+                f"[shared-libs] orphaned: "
+                f"{existing.relative_to(packs_dir.parent).as_posix()} "
+                f"present but no consumer skill claims it "
+                f"(remove the file or restore 'metadata.auth: creds' "
+                f"in the surrounding SKILL.md); "
+                f"run: make build-self FORCE=1"
+            )
+
+    return drifts

agentbundle/build/target_resolver.py

@@ -0,0 +1,85 @@
+"""Scope-conditional `target` resolver for v0.3 projection declarations.
+
+The v0.3 adapter contract (RFC-0005) introduced a string-or-scope-map shape
+for `target` on `[adapter.<x>.projections.<primitive>]` entries:
+
+    # bare-string (v0.1 legacy shorthand)
+    target = "tools/hooks/<name>.{sh,py}"
+
+    # scope-map (v0.3 fork)
+    target.repo = "tools/hooks/<name>.{sh,py}"
+    target.user = ".claude/hooks/<name>.{sh,py}"
+
+Some templates also carry the `<attach-to-agent>` placeholder for
+`merge-into-agent-json` consumers (Kiro hook-wiring), resolved per wiring
+entry from the pack-side TOML's `attach-to-agent` field.
+
+This module is a pure-function utility — no I/O, no filesystem access.
+Scope-root resolution (`.` vs `~`) and `<name>` / `<pack>` placeholder
+substitution are the pipeline consumers' (T5/T6) concern; the resolver
+returns a target-template string they can further process.
+"""
+
+from __future__ import annotations
+
+
+_ATTACH_TO_AGENT_PLACEHOLDER = "<attach-to-agent>"
+
+
+def resolve_target(
+    projection: dict,
+    scope: str,
+    attach_to_agent: str | None = None,
+) -> str:
+    """Resolve a projection entry's `target` for a given scope.
+
+    Arguments:
+      projection: a single entry from `adapter.<x>.projections.<primitive>`.
+        Must contain a `target` key (bare string or `{repo, user}` table).
+      scope: `"repo"` or `"user"`.
+      attach_to_agent: optional pack-side agent name; substituted for any
+        `<attach-to-agent>` placeholder in the resolved template. If the
+        template contains the placeholder but no name is given, the call
+        refuses — passing an unsubstituted template downstream is a bug.
+
+    Returns:
+      The resolved target template as a string. `<name>` and `<pack>`
+      placeholders survive verbatim — they're the pipeline's responsibility,
+      not this resolver's.
+
+    Raises:
+      ValueError: when `target` is absent, when the requested `scope` is
+        absent from a scope-map declaration, or when the resolved template
+        contains the `<attach-to-agent>` placeholder but `attach_to_agent`
+        is None.
+    """
+    if "target" not in projection:
+        raise ValueError("projection missing 'target' field")
+
+    target = projection["target"]
+    if isinstance(target, str):
+        resolved = target
+    elif isinstance(target, dict):
+        if scope not in target:
+            raise ValueError(
+                f"projection target has no entry for scope {scope!r}; "
+                f"declared scopes: {sorted(target.keys())}"
+            )
+        resolved = target[scope]
+        if not isinstance(resolved, str):
+            raise ValueError(
+                f"projection target.{scope} is not a string: {type(resolved).__name__}"
+            )
+    else:
+        raise ValueError(
+            f"projection target must be string or scope-map; got {type(target).__name__}"
+        )
+
+    if _ATTACH_TO_AGENT_PLACEHOLDER in resolved:
+        if attach_to_agent is None:
+            raise ValueError(
+                f"target template requires attach-to-agent; got None. Template: {resolved!r}"
+            )
+        resolved = resolved.replace(_ATTACH_TO_AGENT_PLACEHOLDER, attach_to_agent)
+
+    return resolved

agentbundle/build/tests/test_adapter_claude_code.py

@@ -0,0 +1,275 @@
+"""Tests for the Claude Code adapter (T2)."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from agentbundle.build.adapters.claude_code import project, project_packs
+from agentbundle.build.contract import load as load_contract
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+CONTRACT_PATH = REPO_ROOT / "docs" / "contracts" / "adapter.toml"
+
+
+def _seed_pack(root: Path) -> Path:
+    pack = root / "pack"
+    (pack / ".apm" / "skills" / "foo").mkdir(parents=True)
+    (pack / ".apm" / "skills" / "foo" / "SKILL.md").write_text(
+        "---\ndescription: foo skill\n---\n# foo\n",
+        encoding="utf-8",
+    )
+    (pack / ".apm" / "skills" / "foo" / "extra.txt").write_text("nested\n", encoding="utf-8")
+
+    (pack / ".apm" / "agents").mkdir(parents=True)
+    (pack / ".apm" / "agents" / "bar.md").write_text(
+        "---\nname: bar\n---\nagent body\n",
+        encoding="utf-8",
+    )
+
+    (pack / ".apm" / "hooks").mkdir(parents=True)
+    (pack / ".apm" / "hooks" / "baz.sh").write_text("#!/bin/sh\necho hi\n", encoding="utf-8")
+    (pack / ".apm" / "hooks" / "baz.py").write_text("print('hi')\n", encoding="utf-8")
+
+    (pack / ".apm" / "hook-wiring").mkdir(parents=True)
+    (pack / ".apm" / "hook-wiring" / "baz.toml").write_text(
+        '[hooks]\nbaz = "tools/hooks/baz.sh"\n',
+        encoding="utf-8",
+    )
+
+    (pack / ".apm" / "commands").mkdir(parents=True)
+    (pack / ".apm" / "commands" / "qux.md").write_text("# qux\n", encoding="utf-8")
+    return pack
+
+
+class ClaudeCodeAdapterTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.contract = load_contract(CONTRACT_PATH)
+
+    def test_skill_projects_to_claude_skills_directory(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            self.assertTrue((out / ".claude" / "skills" / "foo" / "SKILL.md").exists())
+            self.assertTrue((out / ".claude" / "skills" / "foo" / "extra.txt").exists())
+
+    def test_agent_projects_to_claude_agents_file(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            agent_path = out / ".claude" / "agents" / "bar.md"
+            self.assertTrue(agent_path.exists())
+            self.assertIn("name: bar", agent_path.read_text(encoding="utf-8"))
+
+    def test_agent_model_alias_preserved_verbatim(self) -> None:
+        """Claude Code agents stay markdown-with-frontmatter; `model:
+        opus` is Claude Code's native alias and the projection must
+        not translate it (unlike the kiro JSON projection, which
+        rewrites aliases via the contract's values map). Comma-string
+        `tools` is also preserved verbatim because Claude Code parses
+        the markdown frontmatter itself."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = tmp_path / "pack"
+            (pack / ".apm" / "agents").mkdir(parents=True)
+            (pack / ".apm" / "agents" / "reviewer.md").write_text(
+                "---\nname: reviewer\nmodel: opus\ntools: Read, Grep, Glob, Bash\n---\nbody\n",
+                encoding="utf-8",
+            )
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            text = (out / ".claude" / "agents" / "reviewer.md").read_text(encoding="utf-8")
+            self.assertIn("model: opus", text)
+            self.assertIn("tools: Read, Grep, Glob, Bash", text)
+
+    def test_hook_body_sh_preserved(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            self.assertTrue((out / "tools" / "hooks" / "baz.sh").exists())
+
+    def test_hook_body_py_preserved(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            self.assertTrue((out / "tools" / "hooks" / "baz.py").exists())
+
+    def test_hook_wiring_merges_under_hooks_key(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            settings_path = out / ".claude" / "settings.local.json"
+            settings_path.parent.mkdir(parents=True)
+            settings_path.write_text(
+                json.dumps({"otherKey": {"preserved": True}}),
+                encoding="utf-8",
+            )
+            project(pack, self.contract, out)
+            data = json.loads(settings_path.read_text(encoding="utf-8"))
+            self.assertEqual(data["hooks"], {"baz": "tools/hooks/baz.sh"})
+            self.assertEqual(data["otherKey"], {"preserved": True})
+
+    def test_command_projects_to_claude_commands(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            self.assertTrue((out / ".claude" / "commands" / "qux.md").exists())
+
+    def test_idempotent_direct_file_and_merge_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            first_agent = (out / ".claude" / "agents" / "bar.md").read_bytes()
+            first_settings = (out / ".claude" / "settings.local.json").read_bytes()
+            project(pack, self.contract, out)
+            second_agent = (out / ".claude" / "agents" / "bar.md").read_bytes()
+            second_settings = (out / ".claude" / "settings.local.json").read_bytes()
+            self.assertEqual(first_agent, second_agent)
+            self.assertEqual(first_settings, second_settings)
+
+
+def _seed_minimal_pack(root: Path, name: str, skill_name: str, body: str) -> Path:
+    """Pack with a single skill at .apm/skills/<skill_name>/SKILL.md."""
+    pack = root / name
+    skill_dir = pack / ".apm" / "skills" / skill_name
+    skill_dir.mkdir(parents=True)
+    (skill_dir / "SKILL.md").write_text(body, encoding="utf-8")
+    return pack
+
+
+class ProjectPacksTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.contract = load_contract(CONTRACT_PATH)
+
+    def test_project_packs_iterates_in_order(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack_a = _seed_minimal_pack(tmp_path, "pack-a", "skill-a", "# a\n")
+            pack_b = _seed_minimal_pack(tmp_path, "pack-b", "skill-b", "# b\n")
+            out = tmp_path / "out"
+
+            project_packs([pack_a, pack_b], self.contract, out)
+
+            self.assertTrue((out / ".claude" / "skills" / "skill-a" / "SKILL.md").is_file())
+            self.assertTrue((out / ".claude" / "skills" / "skill-b" / "SKILL.md").is_file())
+
+    def test_single_pack_project_delegates_to_project_packs(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_minimal_pack(tmp_path, "pack", "skill-x", "# x\n")
+            out_a = tmp_path / "out-a"
+            out_b = tmp_path / "out-b"
+
+            project(pack, self.contract, out_a)
+            project_packs([pack], self.contract, out_b)
+
+            self.assertEqual(
+                (out_a / ".claude" / "skills" / "skill-x" / "SKILL.md").read_bytes(),
+                (out_b / ".claude" / "skills" / "skill-x" / "SKILL.md").read_bytes(),
+            )
+
+    def test_same_name_last_wins(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack_a = _seed_minimal_pack(
+                tmp_path, "pack-a", "same-name", "# pack-a\nPACK_A_SENTINEL\n",
+            )
+            pack_b = _seed_minimal_pack(
+                tmp_path, "pack-b", "same-name", "# pack-b\nPACK_B_SENTINEL\n",
+            )
+            out = tmp_path / "out"
+
+            project_packs([pack_a, pack_b], self.contract, out)
+            body = (out / ".claude" / "skills" / "same-name" / "SKILL.md").read_text(
+                encoding="utf-8",
+            )
+            self.assertIn("PACK_B_SENTINEL", body)
+            self.assertNotIn("PACK_A_SENTINEL", body)
+
+    def test_same_name_last_wins_reversed(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack_a = _seed_minimal_pack(
+                tmp_path, "pack-a", "same-name", "# pack-a\nPACK_A_SENTINEL\n",
+            )
+            pack_b = _seed_minimal_pack(
+                tmp_path, "pack-b", "same-name", "# pack-b\nPACK_B_SENTINEL\n",
+            )
+            out = tmp_path / "out"
+
+            project_packs([pack_b, pack_a], self.contract, out)
+            body = (out / ".claude" / "skills" / "same-name" / "SKILL.md").read_text(
+                encoding="utf-8",
+            )
+            self.assertIn("PACK_A_SENTINEL", body)
+            self.assertNotIn("PACK_B_SENTINEL", body)
+
+
+def _seed_named_skills_pack(root: Path, pack_name: str, skill_names: list[str]) -> Path:
+    pack = root / pack_name
+    for skill_name in skill_names:
+        skill_dir = pack / ".apm" / "skills" / skill_name
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text(
+            f"# {skill_name}\nfrom {pack_name}\n",
+            encoding="utf-8",
+        )
+    return pack
+
+
+class TestClaudeCodeOrphanSweep(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.contract = load_contract(CONTRACT_PATH)
+
+    def test_two_stage_shrink(self) -> None:
+        # AC18: project {a, b, c} then {a, c} into the same output.
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            three = _seed_named_skills_pack(tmp_path, "three-skill", ["a", "b", "c"])
+            shrink = _seed_named_skills_pack(tmp_path, "two-skill-shrink", ["a", "c"])
+            out = tmp_path / "out"
+
+            project_packs([three], self.contract, out)
+            self.assertTrue((out / ".claude" / "skills" / "b").is_dir())
+
+            project_packs([shrink], self.contract, out)
+            children = {p.name for p in (out / ".claude" / "skills").iterdir()}
+            self.assertEqual(children, {"a", "c"})
+
+    def test_two_pack_union(self) -> None:
+        # AC20 — claude-code case.
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack_a = _seed_named_skills_pack(tmp_path, "pack-a", ["a", "b"])
+            pack_b = _seed_named_skills_pack(tmp_path, "pack-b", ["b", "c"])
+            out = tmp_path / "out"
+
+            project_packs([pack_a, pack_b], self.contract, out)
+            children = {p.name for p in (out / ".claude" / "skills").iterdir()}
+            self.assertEqual(children, {"a", "b", "c"})
+
+            project_packs([pack_a], self.contract, out)
+            children = {p.name for p in (out / ".claude" / "skills").iterdir()}
+            self.assertEqual(children, {"a", "b"})
+
+
+if __name__ == "__main__":
+    unittest.main()