fix(packaging): make skill references bundle-safe (#125)

* fix(packaging): make skill references bundle-safe

* test(packaging): normalize scanner paths portably

* fix(packaging): bundle required runtime helpers

scripts/test-verify-docs-sync.py

@@ -60,6 +60,88 @@ def main() -> int:
         if errors:
             raise AssertionError(f"non-reference links should be ignored: {errors}")
 
+        scripts = skill / "scripts"
+        assets = skill / "assets"
+        scripts.mkdir()
+        assets.mkdir()
+        required_files = sorted(verify.REQUIRED_PACKAGED_RUNTIME_FILES)
+        for target in required_files:
+            packaged_file = skill / target
+            packaged_file.parent.mkdir(parents=True, exist_ok=True)
+            packaged_file.write_text("# packaged\n", encoding="utf-8")
+        (assets / "example.html").write_text("<!doctype html>\n", encoding="utf-8")
+        required_mentions = ", ".join(f"`{target}`" for target in required_files)
+        packaged_markdown = f"""Use [the reference](references/present.md#section),
+{required_mentions}, and `assets/example.html`.
+From a repository checkout, run `python3 <repo-root>/scripts/verify-geometry.py <file>`.
+"""
+        extracted = verify.scanner_visible_support_references(packaged_markdown)
+        expected = sorted(
+            {"assets/example.html", "references/present.md", *required_files}
+        )
+        if extracted != expected:
+            raise AssertionError(f"strict-bundler references drifted: {extracted}")
+        errors = []
+        verify.check_packaged_support_references(errors, packaged_markdown, skill)
+        if errors:
+            raise AssertionError(f"valid packaged support references failed: {errors}")
+
+        for phantom in ("references/type-*.md", "references/type-<name>.md"):
+            errors = []
+            verify.check_packaged_support_references(
+                errors,
+                packaged_markdown + f"Load `{phantom}` before drawing.\n",
+                skill,
+            )
+            if len(errors) != 1 or "strict skill bundlers will abort installation" not in errors[0]:
+                raise AssertionError(
+                    f"scanner-visible placeholder was not rejected: {phantom!r}: {errors}"
+                )
+
+        errors = []
+        verify.check_packaged_support_references(
+            errors,
+            packaged_markdown + "See [unsafe](references/%2e%2e/secrets.md).\n",
+            skill,
+        )
+        expected = "SKILL.md exposes unsafe packaged support path 'references/../secrets.md'"
+        if errors != [expected]:
+            raise AssertionError(f"unsafe packaged reference was not rejected: {errors}")
+
+        errors = []
+        verify.check_packaged_support_references(
+            errors,
+            packaged_markdown + "See [unsafe](references/%2e%2e%5csecrets.md).\n",
+            skill,
+        )
+        if len(errors) != 1 or "unsafe packaged support path" not in errors[0]:
+            raise AssertionError(f"encoded Windows traversal was not rejected: {errors}")
+
+        actual_skill = verify.SKILL.read_text(encoding="utf-8")
+        actual_references = set(
+            verify.scanner_visible_support_references(actual_skill)
+        )
+        missing_runtime = verify.REQUIRED_PACKAGED_RUNTIME_FILES - actual_references
+        if missing_runtime:
+            raise AssertionError(
+                "actual SKILL.md omits required packaged runtime files: "
+                f"{sorted(missing_runtime)}"
+            )
+
+        missing_one = required_files[0]
+        errors = []
+        verify.check_packaged_support_references(
+            errors,
+            packaged_markdown.replace(f"`{missing_one}`", f"`{Path(missing_one).name}`"),
+            skill,
+        )
+        expected = (
+            f"SKILL.md does not expose required packaged runtime file {missing_one!r}; "
+            "strict skill bundlers will omit it"
+        )
+        if errors != [expected]:
+            raise AssertionError(f"omitted runtime helper was not reported: {errors}")
+
         root = Path(temp_dir) / "repo"
         profile_reference = root / "skills/diagram-design/references/profiles.md"
         command = root / "commands/profile.md"
@@ -181,7 +263,8 @@ diagram-design/
             raise AssertionError(f"missing Factory native path was not reported: {errors}")
 
     print(
-        "PASS: docs sync checks references, profile surfaces, and Factory install contract"
+        "PASS: docs sync checks references, strict-bundler packaging, profile surfaces, "
+        "and Factory install contract"
     )
     return 0