@event4u/agent-config 3.0.0 → 3.1.0

package/scripts/skill_linter.py

@@ -37,6 +37,7 @@ from validate_frontmatter import (  # noqa: E402
     load_schema,
     validate as validate_against_schema,
 )
+from _lib.agent_src import artefact_roots, resolve_logical  # noqa: E402
 
 Severity = Literal["error", "warning", "info"]
 ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "user-type", "unknown"]
@@ -974,6 +975,30 @@ def extract_frontmatter(text: str) -> Optional[str]:
     return match.group(1) if match else None
 
 
+def _parse_trust_level(frontmatter: str) -> Optional[str]:
+    """Parse `trust.level:` from the nested `trust:` mapping in frontmatter.
+
+    Returns the level string (e.g. ``"core"``, ``"advisory"``) or ``None``
+    if absent. Stdlib-only — mirrors the line-walking approach of
+    ``_parse_yaml_list`` so the linter stays pyyaml-free.
+    """
+    lines = frontmatter.splitlines()
+    in_block = False
+    for line in lines:
+        if not in_block:
+            if line.startswith("trust:"):
+                rhs = line[len("trust:"):].strip()
+                if rhs == "":
+                    in_block = True
+            continue
+        if line.startswith("  level:"):
+            return line[len("  level:"):].strip().strip('"').strip("'")
+        if line.startswith("  "):
+            continue
+        break
+    return None
+
+
 def _parse_yaml_list(frontmatter: str, key: str) -> Optional[list]:
     """Parse a simple top-level YAML list `key:` from frontmatter.
 
@@ -1028,6 +1053,10 @@ def lint_router_frontmatter(rule_id: str, frontmatter: str,
     Lenient checks (info-level until Phase 4 migrations land): non-kernel
     rules without `triggers:` / `routes_to:` get an informational note,
     not an error — the existing description-matching path still works.
+
+    Trust-tier carve-out: rules with ``trust.level: core`` are exempt from
+    the ``router_routes_to_missing`` migration hint — they are authoritative
+    by design and their body legitimately lives inline.
     """
     issues: List[Issue] = []
     triggers = _parse_yaml_list(frontmatter, "triggers")
@@ -1068,9 +1097,15 @@ def lint_router_frontmatter(rule_id: str, frontmatter: str,
                     f"triggers[{idx}] key '{k}' not in allowed set ({allowed})"))
 
     if routes_to is None:
-        issues.append(Issue("info", "router_routes_to_missing",
-            "Non-kernel rule has no routes_to: — body should migrate to skill / "
-            "guideline in Phase 4"))
+        # Trust-tier carve-out: rules pinned at trust.level: core are
+        # authoritative — their body IS the behavior and may legitimately
+        # live inline without a routes_to: delegation. The Phase 4
+        # migration hint applies only to lower-trust rules.
+        trust_level = _parse_trust_level(frontmatter)
+        if trust_level != "core":
+            issues.append(Issue("info", "router_routes_to_missing",
+                "Non-kernel rule has no routes_to: — body should migrate to skill / "
+                "guideline in Phase 4"))
     else:
         repo_root = Path(__file__).resolve().parent.parent
         for idx, item in enumerate(routes_to):
@@ -1079,29 +1114,34 @@ def lint_router_frontmatter(rule_id: str, frontmatter: str,
                     f"routes_to[{idx}] must be 'kind:id'"))
                 continue
             kind, _, target_id = item.partition(":")
+            # Multi-root aware (ADR-017): resolve logical paths via every
+            # source root so kernel rules keep routing to skills/commands
+            # that moved into packages/*/.
+            target: Optional[Path] = None
             if kind == "skill":
-                target = repo_root / ".agent-src.uncompressed" / "skills" / target_id / "SKILL.md"
+                target = resolve_logical(f"skills/{target_id}/SKILL.md")
             elif kind == "guideline":
-                target = repo_root / "docs" / "guidelines" / f"{target_id}.md"
+                gpath = repo_root / "docs" / "guidelines" / f"{target_id}.md"
+                target = gpath if gpath.exists() else None
             elif kind == "command":
-                target = repo_root / ".agent-src.uncompressed" / "commands" / f"{target_id}.md"
+                target = resolve_logical(f"commands/{target_id}.md")
             elif kind == "contract":
                 # Contracts live in two places: stable host docs in
-                # docs/contracts/ and load-bearing flows in
-                # .agent-src.uncompressed/contexts/contracts/ (road-to-path-fixes
+                # docs/contracts/ and load-bearing flows under
+                # contexts/contracts/ inside any source root (road-to-path-fixes
                 # P4 / Council R2). Try both before failing.
-                target = repo_root / "docs" / "contracts" / f"{target_id}.md"
-                if not target.exists():
-                    alt = repo_root / ".agent-src.uncompressed" / "contexts" / "contracts" / f"{target_id}.md"
-                    if alt.exists():
-                        target = alt
+                cpath = repo_root / "docs" / "contracts" / f"{target_id}.md"
+                if cpath.exists():
+                    target = cpath
+                else:
+                    target = resolve_logical(f"contexts/contracts/{target_id}.md")
             else:
                 issues.append(Issue("error", "route_kind_unknown",
                     f"routes_to[{idx}] kind '{kind}' must be 'skill', 'guideline', 'command', or 'contract'"))
                 continue
-            if not target.exists():
+            if target is None or not target.exists():
                 issues.append(Issue("error", "route_target_missing",
-                    f"routes_to[{idx}] target '{item}' not found at {target}"))
+                    f"routes_to[{idx}] target '{item}' not found under any artefact root"))
     return issues
 
 
@@ -2019,86 +2059,126 @@ def lint_usertype(path: Path, text: str) -> LintResult:
 
 
 def gather_all_candidate_files(root: Path) -> list[Path]:
-    """Gather all lintable files. Prefers .agent-src.uncompressed/ (source of truth).
-    Falls back to .agent-src/ only if uncompressed doesn't exist.
-    Skips symlinks to avoid double-counting."""
+    """Gather all lintable files across every source root (ADR-017 multi-root).
+
+    Walks ``artefact_roots()`` (legacy ``.agent-src.uncompressed/`` plus every
+    ``packages/*/.agent-src.uncompressed/``). Falls back to ``.agent-src/``
+    only when no source root exists. Skips symlinks to avoid double-counting.
+    Deduplicates on logical relpath \u2014 first root wins per the agent_src
+    contract.
+    """
     candidates: list[Path] = []
+    seen_logical: set[str] = set()
 
-    # Source of truth directories
-    uncompressed_skills = root / ".agent-src.uncompressed" / "skills"
-    uncompressed_rules = root / ".agent-src.uncompressed" / "rules"
-    uncompressed_commands = root / ".agent-src.uncompressed" / "commands"
-    uncompressed_guidelines = root / ".agent-src.uncompressed" / "guidelines"
-
-    # Fallback directories (only if uncompressed doesn't exist)
-    augment_skills = root / ".agent-src" / "skills"
-    augment_rules = root / ".agent-src" / "rules"
-    augment_commands = root / ".agent-src" / "commands"
-    augment_guidelines = root / ".agent-src" / "guidelines"
-
-    # Skills
-    skills_base = uncompressed_skills if uncompressed_skills.exists() else augment_skills
-    if skills_base.exists():
-        for f in skills_base.rglob("SKILL.md"):
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # Rules
-    rules_base = uncompressed_rules if uncompressed_rules.exists() else augment_rules
-    if rules_base.exists():
-        for f in rules_base.rglob("*.md"):
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # Commands
-    commands_base = uncompressed_commands if uncompressed_commands.exists() else augment_commands
-    if commands_base.exists():
-        for f in commands_base.rglob("*.md"):
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # Guidelines
-    guidelines_base = uncompressed_guidelines if uncompressed_guidelines.exists() else augment_guidelines
-    if guidelines_base.exists():
-        for f in guidelines_base.rglob("*.md"):
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # Personas
-    uncompressed_personas = root / ".agent-src.uncompressed" / "personas"
-    augment_personas = root / ".agent-src" / "personas"
-    personas_base = uncompressed_personas if uncompressed_personas.exists() else augment_personas
-    if personas_base.exists():
-        for f in personas_base.glob("*.md"):
-            if f.name.lower() == "readme.md":
-                continue
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # User-types (sister axis to personas — methodology vs end-user).
-    # Top-level .md only; README and _template/ subtree excluded.
-    uncompressed_usertypes = root / ".agent-src.uncompressed" / "user-types"
-    augment_usertypes = root / ".agent-src" / "user-types"
-    usertypes_base = uncompressed_usertypes if uncompressed_usertypes.exists() else augment_usertypes
-    if usertypes_base.exists():
-        for f in usertypes_base.glob("*.md"):
-            if f.name.lower() == "readme.md":
-                continue
-            if not f.is_symlink():
-                candidates.append(f)
-
-    # Frugality charter (Phase 0.4 Layer 2). Lives in contexts/, not
-    # walked by the artifact-type loops above, but still needs the
-    # index-integrity check.
-    for base in (root / ".agent-src.uncompressed", root / ".agent-src"):
-        charter = base / FRUGALITY_CHARTER_RELPATH
-        if charter.exists() and not charter.is_symlink():
-            candidates.append(charter)
-            break
+    def _add(file: Path, source_root: Path) -> None:
+        if file.is_symlink() or not file.is_file():
+            return
+        try:
+            logical = file.relative_to(source_root).as_posix()
+        except ValueError:
+            logical = file.name
+        # Namespace by artefact-kind subdir so the same skill name across
+        # packs would still dedupe (but the agent_src layout guarantees
+        # each logical path lives in exactly one root post-move).
+        if logical in seen_logical:
+            return
+        seen_logical.add(logical)
+        candidates.append(file)
+
+    sources = artefact_roots()
+    if sources:
+        for src_root in sources:
+            for f in (src_root / "skills").rglob("SKILL.md") if (src_root / "skills").exists() else []:
+                _add(f, src_root)
+            for sub in ("rules", "commands", "guidelines"):
+                base = src_root / sub
+                if base.exists():
+                    for f in base.rglob("*.md"):
+                        _add(f, src_root)
+            for sub in ("personas", "user-types"):
+                base = src_root / sub
+                if base.exists():
+                    for f in base.glob("*.md"):
+                        if f.name.lower() == "readme.md":
+                            continue
+                        _add(f, src_root)
+            charter = src_root / FRUGALITY_CHARTER_RELPATH
+            if charter.exists() and not charter.is_symlink():
+                _add(charter, src_root)
+    else:
+        # Pure-compressed fallback (.agent-src/ only). Used by consumer
+        # projects that vendor the compressed tree without sources.
+        augment_root = root / ".agent-src"
+        if augment_root.exists():
+            for sub_pattern in (
+                ("skills", "SKILL.md"),
+                ("rules", "*.md"),
+                ("commands", "*.md"),
+                ("guidelines", "*.md"),
+            ):
+                base = augment_root / sub_pattern[0]
+                if base.exists():
+                    for f in base.rglob(sub_pattern[1]):
+                        _add(f, augment_root)
+            for sub in ("personas", "user-types"):
+                base = augment_root / sub
+                if base.exists():
+                    for f in base.glob("*.md"):
+                        if f.name.lower() == "readme.md":
+                            continue
+                        _add(f, augment_root)
+            charter = augment_root / FRUGALITY_CHARTER_RELPATH
+            if charter.exists() and not charter.is_symlink():
+                _add(charter, augment_root)
 
     return sorted(set(candidates))
 
 
+def gather_candidate_files_under(src_root: Path) -> list[Path]:
+    """Gather lintable files under an arbitrary source root.
+
+    Mirrors the per-root walk used by ``gather_all_candidate_files`` but
+    scoped to a single directory \u2014 e.g. ``packages/pack-laravel/.agent-src.uncompressed/``
+    so CI can lint a single pack in parallel (ADR-017 Phase 4.4).
+    Skips symlinks and ``README.md`` siblings under ``personas/`` /
+    ``user-types/``.
+    """
+    out: list[Path] = []
+    if not src_root.is_dir():
+        return out
+    seen: set[Path] = set()
+
+    def _push(file: Path) -> None:
+        if file.is_symlink() or not file.is_file():
+            return
+        resolved = file.resolve()
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        out.append(file)
+
+    skills_dir = src_root / "skills"
+    if skills_dir.exists():
+        for f in skills_dir.rglob("SKILL.md"):
+            _push(f)
+    for sub in ("rules", "commands", "guidelines"):
+        base = src_root / sub
+        if base.exists():
+            for f in base.rglob("*.md"):
+                _push(f)
+    for sub in ("personas", "user-types"):
+        base = src_root / sub
+        if base.exists():
+            for f in base.glob("*.md"):
+                if f.name.lower() == "readme.md":
+                    continue
+                _push(f)
+    charter = src_root / FRUGALITY_CHARTER_RELPATH
+    if charter.exists() and not charter.is_symlink():
+        _push(charter)
+    return sorted(set(out))
+
+
 def gather_changed_candidate_files(root: Path) -> list[Path]:
     """Find changed skill/rule files using git diff.
 
@@ -2138,10 +2218,15 @@ def gather_changed_candidate_files(root: Path) -> list[Path]:
             # dirs (.windsurf/, .cursor/, .clinerules/, .claude/) use
             # tool-native frontmatter (e.g. Windsurf's trigger/globs) that
             # the linter does not validate — they regenerate from source.
-            if not (
+            # ADR-017: accept legacy flat layout AND
+            # packages/*/.agent-src.uncompressed/ paths.
+            in_source = (
                 norm.startswith(".agent-src.uncompressed/")
                 or norm.startswith(".agent-src/")
-            ):
+                or "/.agent-src.uncompressed/" in norm
+                or "/.agent-src/" in norm
+            )
+            if not in_source:
                 continue
             if path.name == "SKILL.md" or "/rules/" in norm or "/commands/" in norm:
                 files.append(path)
@@ -2770,20 +2855,37 @@ def lint_governance(path: Path, text: str, artifact_type: str, repo_root: Path |
         return issues
 
     # --- Check: compressed/uncompressed pair exists ---
+    # ADR-017: sources live under packages/*/.agent-src.uncompressed/ but
+    # all packs project into the single repo-root .agent-src/ tree. The
+    # pair-check now resolves via logical relpath, not a path-swap.
+    from _lib.agent_src import strip_source_prefix as _strip
+    norm = path_str.replace("\\", "/")
     if is_uncompressed:
-        # Find expected compressed path
-        compressed_path = Path(path_str.replace("/.agent-src.uncompressed/", "/.agent-src/"))
-        if not compressed_path.exists():
-            issues.append(Issue("warning", "compressed_variant_missing",
-                                f"Uncompressed file exists but compressed variant missing: "
-                                f"{compressed_path.name}"))
+        # Compute logical path then map to .agent-src/ at repo root.
+        # Try direct strip first; fall back to substring split for absolute paths.
+        logical = _strip(norm)
+        if logical is None:
+            marker = "/.agent-src.uncompressed/"
+            idx = norm.rfind(marker)
+            logical = norm[idx + len(marker):] if idx != -1 else None
+        if logical:
+            compressed_path = repo_root / ".agent-src" / logical
+            if not compressed_path.exists():
+                issues.append(Issue("warning", "compressed_variant_missing",
+                                    f"Uncompressed file exists but compressed variant missing: "
+                                    f"{compressed_path.name}"))
     elif is_compressed:
-        # Find expected uncompressed path
-        uncompressed_path = Path(path_str.replace("/.agent-src/", "/.agent-src.uncompressed/"))
-        if not uncompressed_path.exists():
-            issues.append(Issue("warning", "uncompressed_variant_missing",
-                                f"Compressed file exists but uncompressed source missing: "
-                                f"{uncompressed_path.name}"))
+        # Compressed lives at repo-root .agent-src/<logical>. Source could
+        # be at any source root \u2014 resolve via artefact_roots.
+        marker = "/.agent-src/"
+        idx = norm.rfind(marker)
+        logical = norm[idx + len(marker):] if idx != -1 else None
+        if logical:
+            uncompressed_path = resolve_logical(logical)
+            if uncompressed_path is None or not uncompressed_path.exists():
+                issues.append(Issue("warning", "uncompressed_variant_missing",
+                                    f"Compressed file exists but uncompressed source missing: "
+                                    f"{Path(logical).name}"))
 
     # --- Check: file in correct location for type ---
     location_map = {
@@ -3186,18 +3288,23 @@ def check_compression_pairs(root: Path) -> list[LintResult]:
     ]
 
     for subdir, pattern, is_nested in pairs:
-        uncompressed_dir = root / ".agent-src.uncompressed" / subdir
+        # ADR-017: union across every source root.
         compressed_dir = root / ".agent-src" / subdir
+        uncompressed_names: set[str] = set()
+        any_source = False
+        for src_root in artefact_roots():
+            uncompressed_dir = src_root / subdir
+            if not uncompressed_dir.exists():
+                continue
+            any_source = True
+            if is_nested:
+                uncompressed_names |= {d.name for d in uncompressed_dir.iterdir() if d.is_dir() and (d / pattern).exists()}
+            else:
+                uncompressed_names |= {f.name for f in uncompressed_dir.glob(pattern) if f.is_file()}
 
-        if not uncompressed_dir.exists():
+        if not any_source:
             continue
 
-        # Collect names from uncompressed
-        if is_nested:
-            uncompressed_names = {d.name for d in uncompressed_dir.iterdir() if d.is_dir() and (d / pattern).exists()}
-        else:
-            uncompressed_names = {f.name for f in uncompressed_dir.glob(pattern) if f.is_file()}
-
         # Collect names from compressed
         if compressed_dir.exists():
             if is_nested:
@@ -3235,16 +3342,23 @@ def check_compression_pairs(root: Path) -> list[LintResult]:
 def check_compression_quality(root: Path) -> list[LintResult]:
     """Check that compressed skills preserve key content from their uncompressed source."""
     results: list[LintResult] = []
-    uncompressed_dir = root / ".agent-src.uncompressed" / "skills"
     compressed_dir = root / ".agent-src" / "skills"
+    if not compressed_dir.exists():
+        return results
 
-    if not uncompressed_dir.exists() or not compressed_dir.exists():
+    # ADR-017: collect skill dirs from every source root.
+    skill_sources: list[Path] = []
+    for src_root in artefact_roots():
+        uncompressed_dir = src_root / "skills"
+        if uncompressed_dir.exists():
+            skill_sources.extend(sorted(uncompressed_dir.iterdir()))
+    if not skill_sources:
         return results
 
     # Sections that MUST exist in compressed if they exist in uncompressed
     preserved_sections = ["When to use", "Procedure", "Gotcha", "Gotchas", "Do NOT", "Output format", "Output"]
 
-    for skill_dir in sorted(uncompressed_dir.iterdir()):
+    for skill_dir in skill_sources:
         src = skill_dir / "SKILL.md"
         dst = compressed_dir / skill_dir.name / "SKILL.md"
         if not src.exists() or not dst.exists():
@@ -3306,13 +3420,23 @@ def check_compression_quality(root: Path) -> list[LintResult]:
 def check_duplication(root: Path) -> list[LintResult]:
     """Detect skills with highly similar names or descriptions."""
     results: list[LintResult] = []
-    skills_dir = root / ".agent-src.uncompressed" / "skills"
-    if not skills_dir.exists():
+    # ADR-017: collect skill dirs across every source root, dedup by name.
+    skill_dirs: list[Path] = []
+    seen: set[str] = set()
+    for src_root in artefact_roots():
+        sd = src_root / "skills"
+        if not sd.exists():
+            continue
+        for d in sorted(sd.iterdir()):
+            if d.is_dir() and d.name not in seen:
+                seen.add(d.name)
+                skill_dirs.append(d)
+    if not skill_dirs:
         return results
 
     # Collect all skill names and descriptions
     skill_data: list[tuple[str, str, Path]] = []
-    for skill_dir in sorted(skills_dir.iterdir()):
+    for skill_dir in skill_dirs:
         skill_file = skill_dir / "SKILL.md"
         if not skill_file.exists():
             continue
@@ -3497,7 +3621,13 @@ def main() -> int:
             paths.extend(gather_changed_candidate_files(root))
         for raw in args.paths:
             path = (root / raw).resolve() if not Path(raw).is_absolute() else Path(raw)
-            if path.exists():
+            if not path.exists():
+                continue
+            if path.is_dir():
+                # Walk the directory like a source root so callers can pass
+                # `packages/pack-laravel/.agent-src.uncompressed/` (ADR-017 Phase 4.4).
+                paths.extend(gather_candidate_files_under(path))
+            else:
                 paths.append(path)
 
         paths = sorted(set(paths))

package/scripts/skill_trigger_eval.py

@@ -149,16 +149,32 @@ class MockRouter:
         return loaded, len(query) // 4 + len(skills) * 20, 16
 
 
-def load_skill_metas(root: Path = SKILLS_SOURCE) -> list[SkillMeta]:
-    """Parse name + description from every SKILL.md frontmatter under root."""
+def load_skill_metas(root: Path | None = None) -> list[SkillMeta]:
+    """Parse name + description from every SKILL.md frontmatter under root.
+
+    If ``root`` is None, the package's ``artefact_roots()`` are scanned so
+    discovery works across the monorepo's per-pack ``.agent-src.uncompressed/``
+    trees. A single explicit ``root`` keeps tests that mock a sub-tree working
+    unchanged.
+    """
+    if root is not None:
+        roots = [root]
+    else:
+        from _lib.agent_src import artefact_roots
+        roots = [r / "skills" for r in artefact_roots()]
     metas: list[SkillMeta] = []
-    for skill_dir in sorted(p for p in root.iterdir() if p.is_dir()):
-        skill_md = skill_dir / "SKILL.md"
-        if not skill_md.exists():
+    seen: set[str] = set()
+    for skills_dir in roots:
+        if not skills_dir.is_dir():
             continue
-        meta = _parse_frontmatter(skill_md)
-        if meta is not None:
-            metas.append(meta)
+        for skill_dir in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            meta = _parse_frontmatter(skill_md)
+            if meta is not None and meta.name not in seen:
+                metas.append(meta)
+                seen.add(meta.name)
     return metas
 
 
@@ -587,6 +603,10 @@ def build_arg_parser() -> argparse.ArgumentParser:
 
 
 def _default_triggers_path(skill: str) -> Path:
+    from _lib.agent_src import resolve_logical
+    resolved = resolve_logical(f"skills/{skill}/evals/triggers.json")
+    if resolved is not None:
+        return resolved
     return SKILLS_SOURCE / skill / "evals" / "triggers.json"
 
 

package/scripts/smoke/kernel.sh

@@ -29,7 +29,7 @@ log() { [ "$quiet" = "1" ] || printf '%s\n' "$*"; }
 # 1. kernel ids from router.json
 kernel_ids=$(python3 -c '
 import json
-d = json.load(open("router.json"))
+d = json.load(open("dist/router.json"))
 print("\n".join(d.get("kernel", [])))
 ')
 kernel_count=$(printf '%s\n' "$kernel_ids" | grep -c .)

package/scripts/smoke/router.sh

@@ -24,7 +24,12 @@ log() { [ "$quiet" = "1" ] || printf '%s\n' "$*"; }
 result=$(python3 <<'PY'
 import json, os, sys, pathlib
 
-d = json.load(open("router.json"))
+# ADR-017: routes_to resolution walks artefact_roots() across the
+# monorepo. Skills/commands/guidelines may live under any source root.
+sys.path.insert(0, "scripts")
+from _lib.agent_src import resolve_logical
+
+d = json.load(open("dist/router.json"))
 kernel = d.get("kernel", [])
 tier1 = d.get("tier_1", [])
 tier2 = d.get("tier_2", [])
@@ -34,20 +39,34 @@ total = len(ids)
 # Rule-file resolution
 missing_rules = [i for i in ids if not os.path.exists(f".agent-src/rules/{i}.md")]
 
-# routes_to resolution
+# routes_to resolution — multi-root aware via resolve_logical.
 def resolve(ref):
     if ":" not in ref:
-        return f".agent-src.uncompressed/skills/{ref}/SKILL.md", "skill"
-    kind, rest = ref.split(":", 1)
+        kind, rest = "skill", ref
+    else:
+        kind, rest = ref.split(":", 1)
     if kind == "skill":
-        return f".agent-src.uncompressed/skills/{rest}/SKILL.md", "skill"
+        # Legacy projected path first (fast path), then multi-root source.
+        for p in (
+            f".agent-src/skills/{rest}/SKILL.md",
+            f".agent-src.uncompressed/skills/{rest}/SKILL.md",
+        ):
+            if os.path.exists(p):
+                return p, "skill"
+        hit = resolve_logical(f"skills/{rest}/SKILL.md")
+        return (str(hit) if hit else f".agent-src.uncompressed/skills/{rest}/SKILL.md"), "skill"
     if kind == "command":
         for p in (
+            f".agent-src/commands/{rest}.md",
             f".agent-src.uncompressed/commands/{rest}.md",
             f".agent-src.uncompressed/commands/{rest}/INDEX.md",
         ):
             if os.path.exists(p):
                 return p, "command"
+        for logical in (f"commands/{rest}.md", f"commands/{rest}/INDEX.md"):
+            hit = resolve_logical(logical)
+            if hit:
+                return str(hit), "command"
         return f".agent-src.uncompressed/commands/{rest}.md", "command"
     if kind == "guideline":
         return f"docs/guidelines/{rest}.md", "guideline"

package/scripts/smoke/skills.sh

@@ -26,13 +26,21 @@ result=$(python3 <<'PY'
 import os, sys, time, hashlib, pathlib, glob
 sys.path.insert(0, "scripts")
 from validate_frontmatter import parse_frontmatter, load_schema, validate
+from _lib.agent_src import artefact_roots
 
-root = ".agent-src.uncompressed/skills"
-skills = sorted(
-    d for d in os.listdir(root)
-    if os.path.isdir(os.path.join(root, d))
-    and os.path.exists(os.path.join(root, d, "SKILL.md"))
-)
+# ADR-017: walk every source root, collect skill dirs by logical name.
+# First root wins on collision (legacy > core > packs per agent_src).
+skills_by_name: dict[str, str] = {}
+for src_root in artefact_roots():
+    sd = src_root / "skills"
+    if not sd.exists():
+        continue
+    for d in sorted(sd.iterdir()):
+        if not d.is_dir():
+            continue
+        if (d / "SKILL.md").exists() and d.name not in skills_by_name:
+            skills_by_name[d.name] = str(d / "SKILL.md")
+skills = sorted(skills_by_name.keys())
 total = len(skills)
 print(f"TOTAL_SKILLS={total}")
 
@@ -46,7 +54,7 @@ schema = load_schema("skill")
 
 failures = []
 for name in sample:
-    path = os.path.join(root, name, "SKILL.md")
+    path = skills_by_name[name]
     text = open(path, encoding="utf-8").read()
     fm, _ = parse_frontmatter(text)
     if fm is None: