Skip to content

Multi-tier framework for evaluating AI agent skills and plugins with quality gates, security scanning, harness compatibility checks, semantic overlap detection, synthetic evaluation dataset generation, and live agent evaluation that measures how skills affect agent behavior. Ships reusable CI templates that bring every check to any repository.

fix(tier2): allow contained directory aliases (#282)

Narendran Raghavanfc900e07a265
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef302fe6..427a87ba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -477,6 +477,16 @@ All notable changes to SkillEvaluator are documented in this file.
scoring agree, while scoped searches and slash-valued patterns retain their
classification.
+- Tier 2 `similarity-check` and `context-optimization-check` no longer abort
+ with a "symlink or reparse point" error when a skill or collection aliases
+ one agent directory to another, such as `.agents -> .claude`. A directory
+ link whose name is not a scanned file type and whose relative target is a
+ regular directory found by the same scan is skipped without being followed,
+ so the target directory is scanned once. Absolute links and Windows
+ junctions, broken or escaping links, links to the scan root or one of the
+ alias's parent directories, `..` after a named component, and aliases that
+ point at another link remain rejected.
+
- Tier 3 `claude-code` trials no longer hang until the agent timeout after the
agent has already answered. Claude Code moves a shell command that outlasts
its Bash timeout to the background, and a headless run waits for background
diff --git a/docs/tier2-deduplication.mdx b/docs/tier2-deduplication.mdx
index 417853a8..b57a7ad5 100644
--- a/docs/tier2-deduplication.mdx
+++ b/docs/tier2-deduplication.mdx
@@ -353,12 +353,19 @@ limit (`scalar_comparison_limit`), the execution error and the JSON
Split the skill, remove repeated material, or use a narrower embedding model.
Tier 2 treats skill content and catalog files as untrusted input. Before any
-provider call, it rejects linked roots, linked directories and manifests,
-hard-linked selected files, non-regular files, paths outside the verified scan
-root, and all file redirects except the exact contained
-`CLAUDE.md -> AGENTS.md` compatibility alias. That alias is validated but never
-followed; its exactly named, independently discovered, single-link regular
-sibling target is scanned once. Explicit limits bound
+provider call, it rejects linked roots and manifests, hard-linked selected
+files, non-regular files, paths outside the verified scan root, and all
+redirects except two kinds of contained compatibility alias. The exact
+`CLAUDE.md -> AGENTS.md` file alias is validated but never followed; its exactly
+named, independently discovered, single-link regular sibling target is scanned
+once. A directory alias such as `.agents -> .claude` is accepted only when its
+name is not a scanned file type, its raw link text is relative with `..` only
+as leading segments, the target stays below the scan root and is neither the
+root nor one of the alias's own parent directories, and the same walk finds
+that target as a regular directory. The alias is never followed, so the target
+directory is scanned once. Absolute links and Windows junctions, broken links,
+links that escape the root, and aliases that point at another link remain
+rejected. Explicit limits bound
discovered paths, file counts, per-file and total input bytes, content chunks,
candidate clusters, catalog size and entry count, vector length, returned
matches, and pairwise scalar work. Catalog loading also rejects duplicate JSON
@@ -398,7 +405,8 @@ handling terms before sending confidential skill content to a hosted endpoint.
| Duplicate sections occur in one file | Reports the relevant headings and line ranges |
| Skill contains an exactly named, single-link regular `AGENTS.md` plus `CLAUDE.md -> AGENTS.md` | Validates and skips the alias, then scans `AGENTS.md` once |
| Skill carries large generated snapshots (`evals`, `.evals`, `results`, `.results`, `versions`, `.versions`) | Excluded directories are pruned during traversal, so their contents never count toward the discovered-path limit |
- | A directory is a Windows junction or other reparse point | Rejected during the walk, like symbolic links |
+ | Skill contains a relative directory alias such as `.agents -> .claude` whose target is a regular directory in the same skill | Skips the alias without following it, then scans the target directory once |
+ | A directory is a Windows junction, other reparse point, or a symbolic link that does not qualify as a contained alias | Rejected during the walk, before descent |
| Embedding or chat-LLM analysis is incomplete | Reports an error; does not claim a clean result |
| Skill exceeds the content-chunk, comparison-work, or LLM-review limit (candidate clusters, cluster members, or prompt size) | Stops before the remaining analysis and reports the scan as incomplete; no duplicate-content finding is added |
| The chat LLM declines to classify a cluster | Reports an advisory MEDIUM `llm_refused` finding for that cluster's sections |
@@ -411,6 +419,7 @@ handling terms before sending confidential skill content to a hosted endpoint.
| Catalog path is missing | Returns an error and does not rebuild it silently |
| Candidate lacks a root `SKILL.md` | Rejects the catalog query |
| A skill contains an exactly named, single-link regular `AGENTS.md` plus `CLAUDE.md -> AGENTS.md` | Validates and skips the unrelated compatibility alias while discovering `SKILL.md` |
+ | The collection contains a relative directory alias such as `.agents -> .claude` whose target is a regular directory in the same collection | Skips the alias without following it, so manifests in the target are discovered once |
| Candidate matches multiple catalog entries | Reports matches in descending similarity order |
| Provider, endpoint, model, mode, or vector length differs | Rejects the catalog; query with matching settings or rebuild it |
| Catalog is malformed, non-finite, or oversized | Rejects it before comparison |
diff --git a/src/skillevaluator/deduplication/utils/skill_collector.py b/src/skillevaluator/deduplication/utils/skill_collector.py
index f5698d09..7560947e 100644
--- a/src/skillevaluator/deduplication/utils/skill_collector.py
+++ b/src/skillevaluator/deduplication/utils/skill_collector.py
@@ -29,7 +29,11 @@ from skillevaluator.constants import (
CONTENT_DEDUP_SCANNABLE_EXTENSIONS,
)
from skillevaluator.utils.path_security import matches_filesystem_name
-from skillevaluator.utils.tier2_paths import is_contained_compatibility_alias
+from skillevaluator.utils.tier2_paths import (
+ contained_directory_alias_target,
+ is_contained_compatibility_alias,
+ is_link_or_reparse,
+)
from skillevaluator.validators.frontmatter_parser import FRONTMATTER_PATTERN
logger = logging.getLogger(__name__)
@@ -440,6 +444,8 @@ def _collect_files_anchored(
candidates: list[_CandidateFile] = []
declared_total_bytes = 0
+ regular_directories: set[str] = set()
+ directory_aliases: dict[Path, tuple[str, str]] = {}
def _raise_traversal_error(error: OSError) -> None:
raise error
@@ -457,18 +463,34 @@ def _collect_files_anchored(
rel_path = directory.relative_to(root).as_posix()
if matches_filesystem_name(directory, excluded):
logger.debug("Skipping excluded path: %s", rel_path)
+ # A pruned regular directory is still a valid alias
+ # target; its contents stay excluded either way.
+ if not is_link_or_reparse(directory):
+ regular_directories.add(rel_path)
continue
# ``os.walk(..., followlinks=False)`` does not follow normal
# symlinks, but Windows directory junctions are separate
- # reparse points and may still be traversed. Reject every
- # retained redirect before allowing the walk to recurse.
+ # reparse points and may still be traversed. Never descend
+ # into a retained redirect: an unselected, contained alias
+ # such as ``.agents -> .claude`` is recorded for validation
+ # after the walk; every other redirect is rejected here.
if _is_link_or_reparse(directory, rel_path):
- raise SkillCollectionError(
- "unsafe_path",
- f"Refusing symbolic link or reparse point: {rel_path}",
- rel_path=rel_path,
- suggestion="Replace the link with a regular directory stored inside the skill directory.",
+ target = (
+ None
+ if directory.suffix.lower() in CONTENT_DEDUP_SCANNABLE_EXTENSIONS
+ else contained_directory_alias_target(directory, directory.relative_to(root))
)
+ if target is None:
+ raise SkillCollectionError(
+ "unsafe_path",
+ f"Refusing symbolic link or reparse point: {rel_path}",
+ rel_path=rel_path,
+ suggestion="Replace the link with a regular directory stored inside the skill directory.",
+ )
+ directory_aliases[directory] = (rel_path, target)
+ yield directory
+ continue
+ regular_directories.add(rel_path)
kept.append(name)
dirnames[:] = kept
for name in kept:
@@ -496,6 +518,17 @@ def _collect_files_anchored(
"limit": CONTENT_DEDUP_MAX_DISCOVERED_PATHS,
},
)
+ for alias_rel_path, target in directory_aliases.values():
+ if target not in regular_directories:
+ raise SkillCollectionError(
+ "unsafe_path",
+ (
+ "Refusing symbolic link or reparse point whose target is not a regular directory "
+ f"in the skill: {alias_rel_path} -> {target}"
+ ),
+ rel_path=alias_rel_path,
+ suggestion="Point the link at a regular directory stored inside the skill directory.",
+ )
discovered_paths.sort()
discovered_names_by_parent: dict[Path, set[str]] = {}
for discovered_path in discovered_paths:
@@ -518,6 +551,10 @@ def _collect_files_anchored(
logger.debug("Skipping excluded path: %s", rel_path)
continue
+ if file_path in directory_aliases:
+ logger.debug("Skipping directory alias in favor of regular target: %s", rel_path)
+ continue
+
if _is_link_or_reparse(file_path, rel_path):
if is_contained_compatibility_alias(
file_path,
diff --git a/src/skillevaluator/embedding/extractor.py b/src/skillevaluator/embedding/extractor.py
index 7788d6a1..6b1a66d0 100644
--- a/src/skillevaluator/embedding/extractor.py
+++ b/src/skillevaluator/embedding/extractor.py
@@ -33,7 +33,11 @@ from skillevaluator.constants import (
from skillevaluator.deduplication.utils.skill_collector import _SecureReadError, _SecureRoot
from skillevaluator.embedding.limits import validate_max_entries
from skillevaluator.logging_config import get_logger
-from skillevaluator.utils.tier2_paths import is_contained_compatibility_alias, safe_path_label
+from skillevaluator.utils.tier2_paths import (
+ contained_directory_alias_target,
+ is_contained_compatibility_alias,
+ safe_path_label,
+)
from skillevaluator.validators.frontmatter_parser import FRONTMATTER_PATTERN
logger = get_logger(__name__)
@@ -323,14 +327,31 @@ def _read_bounded_manifest(
raise ValueError(f"Manifest is not valid UTF-8: {file_path.name}") from exc
+def _is_discovery_manifest_name(name: str) -> bool:
+ """Return whether *name* could be selected as a skill, rule, or workflow manifest."""
+ folded = name.casefold()
+ return any(folded == variant.casefold() for variant in SKILL_MANIFEST_VARIANTS) or folded.endswith(
+ RULES_FILE_EXTENSION
+ )
+
+
def _iter_discovery_files(root: Path):
- """Yield bounded files from one pruned inter-skill traversal."""
+ """Yield bounded files from one pruned inter-skill traversal.
+
+ A contained directory alias such as ``.agents -> .claude`` is never
+ followed. It is skipped only when its name cannot be a manifest and the
+ same walk enumerates its target as a regular directory, so the canonical
+ directory is scanned once. Every other directory redirect is rejected.
+ """
if _is_symlink_or_reparse(root):
raise ValueError(f"Discovery root is a symlink or reparse point: {root.name}")
if not root.is_dir():
return
discovered_paths = 0
+ discovered_files: list[Path] = []
+ regular_directories: set[str] = set()
+ directory_aliases: list[tuple[str, str]] = []
def _raise_walk_error(error: OSError) -> None:
raise ValueError(f"Cannot safely traverse the Tier 2 collection: {error}") from error
@@ -343,11 +364,25 @@ def _iter_discovery_files(root: Path):
discovered_paths += 1
if discovered_paths > MAX_DISCOVERED_PATHS:
raise ValueError(f"Collection path limit exceeded ({MAX_DISCOVERED_PATHS}) before embedding")
+ directory = Path(dirpath) / dirname
+ relative = directory.relative_to(root)
if dirname in DISCOVERY_EXCLUDED_DIRS:
+ # A pruned regular directory is still a valid alias target;
+ # its contents stay excluded either way.
+ if not _is_symlink_or_reparse(directory):
+ regular_directories.add(relative.as_posix())
continue
- directory = Path(dirpath) / dirname
if _is_symlink_or_reparse(directory):
- raise ValueError(f"Discovery path contains a symlink or reparse point: {dirname}")
+ target = (
+ None
+ if _is_discovery_manifest_name(dirname)
+ else contained_directory_alias_target(directory, relative)
+ )
+ if target is None:
+ raise ValueError(f"Discovery path contains a symlink or reparse point: {dirname}")
+ directory_aliases.append((relative.as_posix(), target))
+ continue
+ regular_directories.add(relative.as_posix())
kept_dirs.append(dirname)
dirnames[:] = kept_dirs
@@ -365,7 +400,16 @@ def _iter_discovery_files(root: Path):
)
continue
raise ValueError(f"Discovery path contains a symlink or reparse point: {filename}")
- yield file_path
+ discovered_files.append(file_path)
+
+ for alias, target in directory_aliases:
+ if target not in regular_directories:
+ raise ValueError(
+ "Discovery path contains a symlink or reparse point whose target is not a regular "
+ f"directory in the scan root: {alias} -> {target}"
+ )
+ logger.debug("Skipping directory alias in favor of regular target: %s -> %s", alias, target)
+ yield from discovered_files
def _discover_skills(root: Path, budget: _ExtractionBudget) -> list[ContentEntry]:
diff --git a/src/skillevaluator/utils/tier2_paths.py b/src/skillevaluator/utils/tier2_paths.py
index 3a31a0f9..4f26c10b 100644
--- a/src/skillevaluator/utils/tier2_paths.py
+++ b/src/skillevaluator/utils/tier2_paths.py
@@ -9,7 +9,7 @@ import os
import stat
from collections.abc import Collection
from contextlib import suppress
-from pathlib import Path
+from pathlib import Path, PurePosixPath
from typing import TYPE_CHECKING
if TYPE_CHECKING:
@@ -64,6 +64,44 @@ def is_contained_compatibility_alias(path: Path, *, sibling_names: Collection[st
)
+def contained_directory_alias_target(path: Path, relative: Path) -> str | None:
+ """Return the in-root target that an unselected directory alias names, or ``None``.
+
+ ``relative`` is the alias path below the scan root. Only the raw link text
+ is read; the alias is never followed. The text must be relative, may climb
+ only through the alias's own (already traversed) parent directories, and
+ must then name a path below the root that is neither the root nor an
+ ancestor of the alias. The returned POSIX-style relative path is an identity
+ claim only: callers skip the alias and accept it only when the same walk
+ independently enumerates that path as a regular directory.
+ """
+ try:
+ metadata = path.lstat()
+ target_text = os.readlink(path) # noqa: PTH115 - validate the raw link text without following it
+ except (OSError, ValueError):
+ return None
+ if getattr(metadata, "st_nlink", 1) != 1 or not target_text or "\x00" in target_text:
+ return None
+ target = Path(target_text)
+ if target.anchor:
+ return None
+
+ parts = target.parts
+ ascent = 0
+ while ascent < len(parts) and parts[ascent] == "..":
+ ascent += 1
+ descent = parts[ascent:]
+ base = relative.parent.parts
+ # A ``..`` after a named component could climb out of a linked directory,
+ # making the lexical claim differ from the physical target.
+ if ascent > len(base) or not descent or ".." in descent:
+ return None
+ normalized = PurePosixPath(*base[: len(base) - ascent], *descent)
+ if PurePosixPath(relative.as_posix()).is_relative_to(normalized):
+ return None
+ return normalized.as_posix()
+
+
def paths_refer_to_same_location(left: Path, right: Path) -> bool:
"""Compare output paths after resolving aliases, symlinks, and hard links."""
with suppress(OSError):
@@ -143,6 +181,7 @@ def sanitize_tier2_results(results: list[ValidationResult], *paths: Path | None)
__all__ = [
+ "contained_directory_alias_target",
"is_contained_compatibility_alias",
"is_link_or_reparse",
"paths_refer_to_same_location",
diff --git a/tests/deduplication/utils/test_skill_collector.py b/tests/deduplication/utils/test_skill_collector.py
index f38b6a95..5387d3c6 100644
--- a/tests/deduplication/utils/test_skill_collector.py
+++ b/tests/deduplication/utils/test_skill_collector.py
@@ -227,6 +227,97 @@ class TestCollectFiles:
assert exc_info.value.check_name == "unsafe_path"
assert exc_info.value.rel_path == "CLAUDE.md"
+ def test_contained_agent_directory_alias_is_skipped_and_target_is_collected_once(
+ self,
+ skill_root: Path,
+ ) -> None:
+ canonical = skill_root / ".claude"
+ canonical.mkdir()
+ (canonical / "shared.md").write_text("# Shared agent instructions\n")
+ try:
+ (skill_root / ".agents").symlink_to(canonical.name, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ result = collect_files(skill_root)
+
+ assert [item.rel_path for item in result] == [".claude/shared.md"]
+
+ def test_directory_alias_counts_toward_path_budget(self, skill_root: Path, monkeypatch) -> None:
+ canonical = skill_root / ".claude"
+ canonical.mkdir()
+ (canonical / "shared.md").write_text("# Shared agent instructions\n")
+ try:
+ (skill_root / ".agents").symlink_to(canonical.name, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+ monkeypatch.setattr(skill_collector, "CONTENT_DEDUP_MAX_DISCOVERED_PATHS", 2)
+
+ with pytest.raises(SkillCollectionError) as exc_info:
+ collect_files(skill_root)
+
+ assert exc_info.value.check_name == "path_count_limit"
+ assert exc_info.value.metadata == {"actual": 3, "limit": 2}
+
+ def test_directory_alias_to_pruned_regular_directory_is_skipped(self, skill_root: Path) -> None:
+ (skill_root / "SKILL.md").write_text("# Skill\n")
+ (skill_root / "evals").mkdir()
+ (skill_root / "evals" / "snapshot.md").write_text("# Generated snapshot\n")
+ try:
+ (skill_root / "latest-evals").symlink_to("evals", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ result = collect_files(skill_root)
+
+ assert [item.rel_path for item in result] == ["SKILL.md"]
+
+ def test_rejects_directory_alias_chain(self, skill_root: Path) -> None:
+ canonical = skill_root / ".canonical"
+ canonical.mkdir()
+ (canonical / "shared.md").write_text("# Shared agent instructions\n")
+ try:
+ (skill_root / ".claude").symlink_to(canonical.name, target_is_directory=True)
+ (skill_root / ".agents").symlink_to(".claude", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(SkillCollectionError) as exc_info:
+ collect_files(skill_root)
+
+ assert exc_info.value.check_name == "unsafe_path"
+ assert exc_info.value.rel_path == ".agents"
+ assert ".agents -> .claude" in str(exc_info.value)
+
+ @pytest.mark.parametrize("alias_name", ["guide.md", "helper.PY"])
+ def test_rejects_directory_alias_with_scannable_name(self, skill_root: Path, alias_name: str) -> None:
+ canonical = skill_root / "canonical"
+ canonical.mkdir()
+ try:
+ (skill_root / alias_name).symlink_to(canonical.name, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(SkillCollectionError) as exc_info:
+ collect_files(skill_root)
+
+ assert exc_info.value.check_name == "unsafe_path"
+ assert exc_info.value.rel_path == alias_name
+
+ @pytest.mark.parametrize("target", ["missing", ".", "..", "../outside"])
+ def test_rejects_directory_alias_without_contained_regular_target(self, skill_root: Path, target: str) -> None:
+ (skill_root.parent / "outside").mkdir()
+ try:
+ (skill_root / ".agents").symlink_to(target, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(SkillCollectionError) as exc_info:
+ collect_files(skill_root)
+
+ assert exc_info.value.check_name == "unsafe_path"
+ assert exc_info.value.rel_path == ".agents"
+
class TestCollectFilesSafety:
@pytest.mark.skipif(os.name != "posix", reason="descriptor-anchored availability is a POSIX-specific contract")
diff --git a/tests/embedding/test_extractor.py b/tests/embedding/test_extractor.py
index b72b6ac6..0febd62b 100644
--- a/tests/embedding/test_extractor.py
+++ b/tests/embedding/test_extractor.py
@@ -515,6 +515,74 @@ class TestDiscoverAndExtract:
with pytest.raises(ValueError, match=r"symlink|reparse|unsafe"):
discover_and_extract(tmp_path, "skill")
+ def test_contained_directory_alias_is_skipped_and_target_discovered_once(self, tmp_path: Path, write_skill) -> None:
+ collection = tmp_path / "skills"
+ write_skill(collection / "shared-skills", "helper", "Shared helper for every coding agent")
+ (collection / ".claude").mkdir()
+ try:
+ # A Path target uses native separators, so the link also resolves on Windows.
+ (collection / ".claude" / "skills").symlink_to(Path("..") / "shared-skills", target_is_directory=True)
+ (collection / ".agents").symlink_to(".claude", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ entries = discover_and_extract(collection, "skill")
+
+ assert [Path(entry.path).relative_to(collection).as_posix() for entry in entries] == ["shared-skills/helper"]
+
+ def test_directory_alias_to_pruned_regular_directory_is_skipped(self, tmp_path: Path, write_skill) -> None:
+ collection = tmp_path / "skills"
+ write_skill(collection, "visible-skill", "Visible skill")
+ write_skill(collection / "evals", "generated-skill", "Generated snapshot")
+ try:
+ (collection / "latest-evals").symlink_to("evals", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ entries = discover_and_extract(collection, "skill")
+
+ assert [entry.name for entry in entries] == ["visible-skill"]
+
+ def test_rejects_directory_alias_chain(self, tmp_path: Path, write_skill) -> None:
+ collection = tmp_path / "skills"
+ write_skill(collection / "canonical", "helper", "Shared helper for every coding agent")
+ try:
+ (collection / ".claude").symlink_to("canonical", target_is_directory=True)
+ (collection / ".agents").symlink_to(".claude", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(ValueError, match=r"symlink or reparse point.*\.agents -> \.claude"):
+ discover_and_extract(collection, "skill")
+
+ @pytest.mark.parametrize("alias_name", ["SKILL.md", "skill.md", "team.mdc", "workflow-rules.mdc"])
+ def test_rejects_directory_alias_with_manifest_name(self, tmp_path: Path, write_skill, alias_name: str) -> None:
+ collection = tmp_path / "skills"
+ write_skill(collection / "canonical", "helper", "Shared helper for every coding agent")
+ try:
+ (collection / alias_name).symlink_to("canonical", target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(ValueError, match=r"symlink or reparse point"):
+ discover_and_extract(collection, "skill")
+
+ @pytest.mark.parametrize("target", ["missing", ".", "..", "../outside", "absolute"])
+ def test_rejects_directory_alias_without_contained_regular_target(
+ self, tmp_path: Path, write_skill, target: str
+ ) -> None:
+ collection = tmp_path / "skills"
+ write_skill(collection, "visible-skill", "Visible skill")
+ (tmp_path / "outside").mkdir()
+ link_text = str(collection / "visible-skill") if target == "absolute" else target
+ try:
+ (collection / ".agents").symlink_to(link_text, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ with pytest.raises(ValueError, match=r"symlink or reparse point"):
+ discover_and_extract(collection, "skill")
+
def test_discover_rules_in_folder(self, tmp_path: Path) -> None:
rules_dir = tmp_path / "team-rules"
rules_dir.mkdir()
diff --git a/tests/test_cli.py b/tests/test_cli.py
index bfcac5e2..4d9059c3 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -199,6 +199,48 @@ def test_similarity_cli_handles_pinned_openclaw_compatibility_layout(tmp_path: P
]
+def test_tier2_clis_scan_contained_agent_directory_alias_once(tmp_path: Path, monkeypatch) -> None:
+ collection = tmp_path / "skills"
+ skill = collection / "agent-alias"
+ canonical = skill / ".claude"
+ canonical.mkdir(parents=True)
+ (skill / "SKILL.md").write_text(
+ "---\nname: agent-alias\ndescription: Share one canonical directory across coding agents\n---\n\n"
+ "# Agent Alias\n\nRead the canonical agent directory before changing any project files in this skill.\n"
+ )
+ (canonical / "shared.md").write_text(
+ "# Shared context\n\nSHARED_CANARY: use these same instructions for every coding agent that loads this skill.\n"
+ )
+ try:
+ (skill / ".agents").symlink_to(canonical.name, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+ second = collection / "second-skill"
+ second.mkdir()
+ (second / "SKILL.md").write_text("---\nname: second-skill\ndescription: Exercise an unrelated workflow\n---\n")
+
+ embedded_texts: list[str] = []
+
+ def embed_orthogonally(_self, texts: list[str]) -> list[list[float]]:
+ vectors: list[list[float]] = []
+ for text in texts:
+ vector = [0.0] * 64
+ vector[len(embedded_texts)] = 1.0
+ embedded_texts.append(text)
+ vectors.append(vector)
+ return vectors
+
+ monkeypatch.setattr("skillevaluator.embedding.client.EmbeddingClient.embed", embed_orthogonally)
+
+ similarity = CliRunner().invoke(cli, ["similarity-check", str(collection), "--type", "skill"])
+ context = CliRunner().invoke(cli, ["context-optimization-check", str(skill), "--threshold", "1.0"])
+
+ assert similarity.exit_code == 0, similarity.output
+ assert context.exit_code == 0, context.output
+ assert "symbolic link or reparse point" not in click.unstyle(context.output)
+ assert sum("SHARED_CANARY" in text for text in embedded_texts) == 1
+
+
@pytest.mark.parametrize(
("command", "runner_path"),
[
diff --git a/tests/utils/test_tier2_paths.py b/tests/utils/test_tier2_paths.py
index 005432da..b886980d 100644
--- a/tests/utils/test_tier2_paths.py
+++ b/tests/utils/test_tier2_paths.py
@@ -3,11 +3,24 @@
from __future__ import annotations
+import os
import stat
from pathlib import Path
from types import SimpleNamespace
-from skillevaluator.utils.tier2_paths import is_link_or_reparse
+import pytest
+
+from skillevaluator.utils.tier2_paths import contained_directory_alias_target, is_link_or_reparse
+
+
+def _directory_alias(root: Path, relative: str, target: str) -> Path:
+ alias = root / relative
+ alias.parent.mkdir(parents=True, exist_ok=True)
+ try:
+ alias.symlink_to(target, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+ return alias
def test_windows_reparse_attribute_is_rejected_without_symlink_mode(tmp_path: Path, monkeypatch) -> None:
@@ -23,3 +36,64 @@ def test_windows_reparse_attribute_is_rejected_without_symlink_mode(tmp_path: Pa
monkeypatch.setattr(Path, "lstat", fake_lstat)
assert is_link_or_reparse(target)
+
+
+ ("relative", "target", "expected"),
+ [
+ pytest.param(".agents", ".claude", ".claude", id="sibling"),
+ pytest.param(".claude/skills", "../shared-skills", "shared-skills", id="leading-parent"),
+ pytest.param("nested/.agents", "./.claude/", "nested/.claude", id="current-directory"),
+ ],
+)
+def test_contained_directory_alias_target_returns_lexical_in_root_claim(
+ tmp_path: Path, relative: str, target: str, expected: str
+) -> None:
+ alias = _directory_alias(tmp_path, relative, target)
+
+ assert contained_directory_alias_target(alias, Path(relative)) == expected
+
+
+ ("relative", "target"),
+ [
+ pytest.param(".agents", ".", id="root"),
+ pytest.param(".agents", "..", id="parent-of-root"),
+ pytest.param(".agents", "../outside", id="escape"),
+ pytest.param("nested/.agents", "../../outside", id="nested-escape"),
+ pytest.param("nested/deeper/.agents", "..", id="own-parent"),
+ pytest.param("nested/.agents", "../nested", id="own-parent-by-name"),
+ pytest.param(".agents", "linked/../.claude", id="parent-after-named-component"),
+ ],
+)
+def test_contained_directory_alias_target_rejects_root_escape_and_cycle_claims(
+ tmp_path: Path, relative: str, target: str
+) -> None:
+ alias = _directory_alias(tmp_path, relative, target)
+
+ assert contained_directory_alias_target(alias, Path(relative)) is None
+
+
+def test_contained_directory_alias_target_rejects_absolute_link_text(tmp_path: Path) -> None:
+ (tmp_path / ".claude").mkdir()
+ alias = _directory_alias(tmp_path, ".agents", str(tmp_path / ".claude"))
+
+ assert contained_directory_alias_target(alias, Path(".agents")) is None
+
+
+def test_contained_directory_alias_target_rejects_unreadable_link_text(tmp_path: Path) -> None:
+ regular = tmp_path / "regular"
+ regular.mkdir()
+
+ assert contained_directory_alias_target(regular, Path("regular")) is None
+
+
+def test_contained_directory_alias_target_rejects_hard_linked_alias(tmp_path: Path) -> None:
+ (tmp_path / ".claude").mkdir()
+ alias = _directory_alias(tmp_path, ".agents", ".claude")
+ try:
+ os.link(alias, tmp_path / ".agents-copy", follow_symlinks=False)
+ except (NotImplementedError, OSError) as exc:
+ pytest.skip(f"hard links to symlinks unavailable: {exc}")
+
+ assert contained_directory_alias_target(alias, Path(".agents")) is None