@event4u/agent-config 3.0.0 → 3.1.0

package/scripts/compress.py

@@ -32,14 +32,43 @@ import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.script_output import info, success, flush_summary, resolve_level  # noqa: E402
+from _lib.agent_src import (  # noqa: E402
+    artefact_roots,
+    iter_all_sources,
+    resolve_logical,
+)
 
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
+# Legacy single-root anchor — kept for backward compatibility with callers
+# that pass it explicitly. Multi-root iteration (post-ADR-017 physical
+# move) goes through `_lib.agent_src` helpers.
 SOURCE_DIR = PROJECT_ROOT / ".agent-src.uncompressed"
 TARGET_DIR = PROJECT_ROOT / ".agent-src"
 AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / ".compression-hashes.json"
 SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
 
+
+def _iter_sources():
+    """Yield (physical_path, logical_relpath) for every source artefact.
+
+    Wraps `_lib.agent_src.iter_all_sources` so the compressor walks every
+    active source root (legacy `.agent-src.uncompressed/` plus any
+    `packages/*/.agent-src.uncompressed/`) and keys outputs by the
+    logical relative path that survives the physical move (ADR-017).
+    """
+    yield from iter_all_sources()
+
+
+def _resolve_source(relative: str) -> Path | None:
+    """Find the physical path that backs a logical relative path."""
+    return resolve_logical(relative)
+
+
+def _any_source_root_exists() -> bool:
+    """True if at least one artefact source root contains files."""
+    return bool(artefact_roots())
+
 # Self-projection tool toggle — see .agent-tools.yml. When the file is
 # absent (e.g. tests run in tmp dirs, consumer projects), `_active_tools`
 # returns ``None`` which is treated as "emit every tool".
@@ -148,8 +177,8 @@ def mark_done(relative_path: str) -> None:
     relative paths in the shipped layer (P1 of road-to-path-fixes.md).
     Idempotent — re-running is a no-op.
     """
-    source_file = SOURCE_DIR / relative_path
-    if not source_file.exists():
+    source_file = _resolve_source(relative_path)
+    if source_file is None or not source_file.exists():
         print(f"❌  Source file not found: {relative_path}")
         sys.exit(1)
     apply_path_rewriter(relative_path)
@@ -181,12 +210,9 @@ def mark_all_done() -> None:
     """Mark ALL .md files as compressed (e.g. after initial full compression)."""
     hashes = load_hashes()
     count = 0
-    for source_file in sorted(SOURCE_DIR.rglob("*")):
-        if source_file.is_dir():
-            continue
+    for source_file, relative in _iter_sources():
         if not should_compress(source_file):
             continue
-        relative = str(source_file.relative_to(SOURCE_DIR))
         hashes[relative] = file_hash(source_file)
         count += 1
     save_hashes(hashes)
@@ -194,15 +220,17 @@ def mark_all_done() -> None:
 
 
 def list_changed_md(source_dir: Path) -> list:
-    """List .md files whose source hash differs from stored hash (= need recompression)."""
+    """List .md files whose source hash differs from stored hash (= need recompression).
+
+    The ``source_dir`` parameter is retained for backward compatibility but
+    ignored — iteration walks every active source root (ADR-017).
+    """
+    del source_dir  # multi-root: ignored, kept for signature stability
     hashes = load_hashes()
     changed = []
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
-            continue
+    for source_file, relative in _iter_sources():
         if not should_compress(source_file):
             continue
-        relative = str(source_file.relative_to(source_dir))
         current_hash = file_hash(source_file)
         stored_hash = hashes.get(relative)
         if stored_hash != current_hash:
@@ -211,12 +239,12 @@ def list_changed_md(source_dir: Path) -> list:
 
 
 def find_stale_hashes(source_dir: Path) -> list:
-    """Find hashes stored for source files that no longer exist."""
+    """Find hashes stored for source files that no longer exist in any root."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     hashes = load_hashes()
     stale = []
     for relative in sorted(hashes.keys()):
-        source_file = source_dir / relative
-        if not source_file.exists():
+        if _resolve_source(relative) is None:
             stale.append(relative)
     return stale
 
@@ -240,10 +268,16 @@ def should_compress(filepath: Path) -> bool:
         return False
     if filepath.name in COPY_AS_IS:
         return False
-    try:
-        rel_parts = filepath.relative_to(SOURCE_DIR).parts
-    except ValueError:
-        rel_parts = filepath.parts
+    # Determine the logical relative path so the COPY_AS_IS_DIRS check
+    # works for both legacy (`.agent-src.uncompressed/`) and post-move
+    # (`packages/*/.agent-src.uncompressed/`) source roots.
+    rel_parts: tuple[str, ...] = filepath.parts
+    for root in artefact_roots():
+        try:
+            rel_parts = filepath.relative_to(root).parts
+            break
+        except ValueError:
+            continue
     if rel_parts and rel_parts[0] in COPY_AS_IS_DIRS:
         return False
     return True
@@ -256,7 +290,8 @@ def copy_file(source: Path, target: Path) -> None:
 
 
 def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
-    """Delete files in target that don't exist in source. Returns count."""
+    """Delete files in target that don't exist in any source root. Returns count."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     deleted = 0
     if not target_dir.exists():
         return 0
@@ -265,8 +300,7 @@ def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
         if target_file.is_dir():
             continue
         relative = target_file.relative_to(target_dir)
-        source_file = source_dir / relative
-        if not source_file.exists():
+        if _resolve_source(str(relative)) is None:
             print(f"  Deleting stale: {relative}")
             target_file.unlink()
             deleted += 1
@@ -281,14 +315,17 @@ def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
 
 
 def sync_non_md(source_dir: Path, target_dir: Path) -> int:
-    """Copy all non-.md files (and COPY_AS_IS .md files) from source to target. Returns count."""
+    """Copy all non-.md files (and COPY_AS_IS .md files) from every source
+    root to target. Returns count."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     copied = 0
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
-            continue
+    seen: set[str] = set()
+    for source_file, relative in _iter_sources():
         if should_compress(source_file):
             continue  # .md files are compressed by the agent, not copied here
-        relative = source_file.relative_to(source_dir)
+        if relative in seen:
+            continue
+        seen.add(relative)
         target_file = target_dir / relative
         copy_file(source_file, target_file)
         print(f"  Copied: {relative}")
@@ -298,36 +335,41 @@ def sync_non_md(source_dir: Path, target_dir: Path) -> int:
 
 def list_md_files(source_dir: Path) -> list:
     """List all .md files that need compression by the agent."""
-    files = []
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
+    del source_dir  # multi-root: ignored, kept for signature stability
+    files: list[str] = []
+    seen: set[str] = set()
+    for source_file, relative in _iter_sources():
+        if not should_compress(source_file):
             continue
-        if should_compress(source_file):
-            files.append(str(source_file.relative_to(source_dir)))
-    return files
+        if relative in seen:
+            continue
+        seen.add(relative)
+        files.append(relative)
+    return sorted(files)
 
 
 def check_sync(source_dir: Path, target_dir: Path) -> tuple:
-    """Check if target is in sync with source. Returns (missing, stale) lists."""
+    """Check if target is in sync with source(s). Returns (missing, stale) lists."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     missing = []
     stale = []
 
-    # Files in source but not in target
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
+    # Files in any source root but not in target
+    seen: set[str] = set()
+    for _source_file, relative in _iter_sources():
+        if relative in seen:
             continue
-        relative = str(source_file.relative_to(source_dir))
+        seen.add(relative)
         if not (target_dir / relative).exists():
             missing.append(relative)
 
-    # Files in target but not in source (stale)
+    # Files in target but not in any source root (stale)
     if target_dir.exists():
         for target_file in sorted(target_dir.rglob("*")):
             if target_file.is_dir():
                 continue
             relative = str(target_file.relative_to(target_dir))
-
-            if not (source_dir / relative).exists():
+            if _resolve_source(relative) is None:
                 stale.append(relative)
 
     return missing, stale
@@ -512,11 +554,80 @@ def _rewrite_body_links(body: str, prefix: str) -> str:
     return _BODY_DOCS_RE.sub(prefix + r"\1", body)
 
 
+# ── Human-review banner injection (Phase 5.3 / ADR-018) ───────────────────
+# Source artefacts may set `trust.human_review_required: true` in their
+# frontmatter. The compressor injects a short, parser-stable banner block
+# at the top of the projected body so every downstream surface (agent
+# memory, .augment, .claude, etc.) surfaces the gate. Idempotent — the
+# marker comment prevents double-injection on re-compress.
+
+_HRR_BANNER_MARKER = "<!-- agent-config:human-review-banner -->"
+
+# Plain YAML list item — any scalar, used to read `packs:` / `workspaces:`
+# blocks where values are bare identifiers, not file paths.
+_FM_PLAIN_LIST_RE = re.compile(r'^\s*-\s*(["\']?)([^"\'\n]+?)\1\s*$')
+
+
+def _parse_trust_and_owner(fm_lines):
+    """Extract `trust.level`, `human_review_required`, and an owner hint
+    from a frontmatter line list. Owner falls back to the first pack
+    prefix (`finance-basic` → `finance`), then the first workspace,
+    then `unknown`.
+    """
+    level = None
+    hrr = False
+    packs: list[str] = []
+    workspaces: list[str] = []
+    in_trust = False
+    in_packs = False
+    in_workspaces = False
+    for line in fm_lines:
+        stripped = line.lstrip()
+        indent = len(line) - len(stripped)
+        if indent == 0 and stripped.endswith(":"):
+            key = stripped[:-1]
+            in_trust = key == "trust"
+            in_packs = key == "packs"
+            in_workspaces = key == "workspaces"
+            continue
+        if in_trust and stripped.startswith("level:"):
+            level = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+        elif in_trust and stripped.startswith("human_review_required:"):
+            val = stripped.split(":", 1)[1].strip()
+            hrr = val.lower() == "true"
+        elif in_packs or in_workspaces:
+            m = _FM_PLAIN_LIST_RE.match(line)
+            if m:
+                value = m.group(2).strip()
+                (packs if in_packs else workspaces).append(value)
+    owner = "unknown"
+    if packs:
+        owner = packs[0].split("-")[0]
+    elif workspaces:
+        owner = workspaces[0]
+    return level, hrr, owner
+
+
+def _inject_hrr_banner(body: str, level: str, owner: str) -> str:
+    """Prepend the HUMAN_REVIEW banner block to `body`. Idempotent — a
+    body that already carries `_HRR_BANNER_MARKER` is returned unchanged.
+    """
+    if _HRR_BANNER_MARKER in body:
+        return body
+    banner = (
+        f"{_HRR_BANNER_MARKER}\n"
+        f"> HUMAN REVIEW REQUIRED · trust: {level} · owner: {owner}\n\n"
+    )
+    return banner + body.lstrip("\n")
+
+
 def _rewrite_paths(content: str, source_relative_path: str) -> str:
     """Rewrite logical / legacy paths in `content` for a file shipped at
     `.agent-src/{source_relative_path}`. Idempotent.
 
     See module-level comment above for the full pattern catalog.
+    Also injects the HUMAN_REVIEW banner when the source frontmatter
+    sets `trust.human_review_required: true` (Phase 5.3 / ADR-018).
     """
     prefix = _depth_prefix(source_relative_path)
     fm_lines, body = _split_frontmatter(content)
@@ -524,6 +635,9 @@ def _rewrite_paths(content: str, source_relative_path: str) -> str:
     if fm_lines is None:
         return body
     new_fm = _rewrite_frontmatter_lines(fm_lines, prefix)
+    level, hrr, owner = _parse_trust_and_owner(fm_lines)
+    if hrr and level:
+        body = _inject_hrr_banner(body, level, owner)
     return "---\n" + "\n".join(new_fm) + "\n---\n" + body
 
 
@@ -1096,8 +1210,11 @@ def clean_tools() -> None:
 
 
 def main() -> None:
-    if not SOURCE_DIR.exists():
-        print(f"❌  Source directory not found: {SOURCE_DIR}")
+    # Multi-root awareness (ADR-017): tolerate a missing legacy
+    # `.agent-src.uncompressed/` as long as at least one package-scoped
+    # source root carries artefacts.
+    if not SOURCE_DIR.exists() and not _any_source_root_exists():
+        print(f"❌  No source directory found (looked at {SOURCE_DIR} and packages/*/.agent-src.uncompressed)")
         sys.exit(1)
 
     arg = sys.argv[1] if len(sys.argv) > 1 else "--sync"
@@ -1149,9 +1266,10 @@ def main() -> None:
         copied = sync_non_md(SOURCE_DIR, TARGET_DIR)
         print(f"\n--- Cleanup stale files ---")
         deleted = cleanup_stale(SOURCE_DIR, TARGET_DIR)
-        # Also cleanup stale hashes
+        # Also cleanup stale hashes (multi-root aware — resolve against
+        # every artefact root, not just the legacy SOURCE_DIR).
         hashes = load_hashes()
-        stale_keys = [k for k in hashes if not (SOURCE_DIR / k).exists()]
+        stale_keys = [k for k in hashes if _resolve_source(k) is None]
         for k in stale_keys:
             del hashes[k]
         if stale_keys:

package/scripts/config/presets.py

@@ -93,7 +93,25 @@ def _load_yaml(path: Path) -> dict[str, Any]:
 
 
 def _preset_file(project_root: Path, preset_id: str) -> Path:
-    return project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+    # Legacy single-root layout — honor when present so tests that mock a
+    # ``.agent-src.uncompressed/`` sub-tree under ``project_root`` keep working.
+    legacy = project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+    if legacy.exists():
+        return legacy
+    # Monorepo layout — scan every package root via the agent_src helper.
+    try:
+        import sys as _sys
+        scripts_root = Path(__file__).resolve().parents[1]
+        if str(scripts_root) not in _sys.path:
+            _sys.path.insert(0, str(scripts_root))
+        from _lib.agent_src import artefact_roots  # type: ignore
+    except Exception:
+        return legacy
+    for root in artefact_roots():
+        candidate = root / "presets" / f"{preset_id}.yml"
+        if candidate.exists():
+            return candidate
+    return legacy
 
 
 def _coerce_scalar(raw: str) -> Any:

package/scripts/config/profiles.py

@@ -89,7 +89,22 @@ def _load_yaml(path: Path) -> dict[str, Any]:
 
 
 def _profile_file(project_root: Path, profile_id: str) -> Path:
-    return project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+    legacy = project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+    if legacy.exists():
+        return legacy
+    try:
+        import sys as _sys
+        scripts_root = Path(__file__).resolve().parents[1]
+        if str(scripts_root) not in _sys.path:
+            _sys.path.insert(0, str(scripts_root))
+        from _lib.agent_src import artefact_roots  # type: ignore
+    except Exception:
+        return legacy
+    for root in artefact_roots():
+        candidate = root / "profiles" / f"{profile_id}.yml"
+        if candidate.exists():
+            return candidate
+    return legacy
 
 
 def _build_resolved(

package/scripts/discovery_stats.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Pretty-print the ``stats`` block from the committed discovery manifest.
+
+Cheap sanity surface for developers: counts by category, lifecycle, and
+trust level — answers "how many skills are professional vs core?" in
+one terminal line. Reads only the committed manifest; no scan, no
+generation. See ADR-015.
+
+CLI:
+  python scripts/discovery_stats.py [--manifest PATH]
+
+Exit codes:
+  0  printed
+  1  manifest missing or malformed
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+
+def _fmt_row(label: str, counts: dict[str, int]) -> str:
+    parts = [f"{k}={v}" for k, v in counts.items()]
+    return f"  {label:<14} " + "  ".join(parts)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    args = parser.parse_args(argv)
+
+    if not args.manifest.exists():
+        print(
+            f"error: manifest not found at {args.manifest} "
+            "— run `task build-discovery` first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        manifest = json.loads(args.manifest.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"error: invalid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    stats = manifest.get("stats")
+    if not isinstance(stats, dict):
+        print("error: manifest has no `stats` block (regenerate)", file=sys.stderr)
+        return 1
+
+    rel = args.manifest.relative_to(ROOT) if args.manifest.is_absolute() else args.manifest
+    print(f"Discovery stats — {rel}")
+    print(f"  total          {stats.get('total_artefacts', 0)}")
+    print(_fmt_row("by category", stats.get("by_category", {})))
+    print(_fmt_row("by lifecycle", stats.get("by_lifecycle", {})))
+    print(_fmt_row("by trust", stats.get("by_trust_level", {})))
+    if stats.get("unassigned_count"):
+        print(f"  unassigned     {stats['unassigned_count']}")
+    if stats.get("documented_unassigned_count"):
+        print(f"  documented     {stats['documented_unassigned_count']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/expected_perms.json

@@ -0,0 +1,47 @@
+{
+  "$schema_version": "expected-perms/v1",
+  "$comment": "Expected POSIX modes for the global install tree. Consumed by scripts/lint_global_paths.py as an entry-gate for the migrate-to-global subcommand (road-to-global-only-install Phase 5.0 / A7). Octal modes are strings so JSON tooling never widens 0700 → 700.",
+  "global_root": {
+    "path": "~/.event4u/agent-config",
+    "expected_mode": "0700",
+    "kind": "directory"
+  },
+  "files": [
+    {
+      "glob": "~/.event4u/agent-config/.agent-settings.yml",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/.agent-user.yml",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/.wizard-state.json",
+      "expected_mode": "0600",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/**/*.key",
+      "expected_mode": "0600",
+      "required": false
+    }
+  ],
+  "directories": [
+    {
+      "glob": "~/.event4u/agent-config/state",
+      "expected_mode": "0700",
+      "required": false
+    },
+    {
+      "glob": "~/.event4u/agent-config/settings",
+      "expected_mode": "0700",
+      "required": false
+    }
+  ],
+  "forbid_symlink_escape": {
+    "root": "~/.event4u/agent-config",
+    "$comment": "All symlinks under the global root MUST resolve to paths still under the global root. Cross-root escapes are a security finding (allows external writes via a writable symlink target)."
+  }
+}

package/scripts/generate_index.py

@@ -19,6 +19,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+# Legacy single-root anchor — kept as fallback for pure-compressed
+# consumer projections. Multi-root discovery uses artefact_roots() so
+# generate_index works across packages/* per ADR-017.
 SRC = ROOT / ".agent-src.uncompressed"
 GUIDELINES = ROOT / "docs" / "guidelines"
 INDEX_PATH = ROOT / "agents" / "index.md"
@@ -62,59 +68,79 @@ def _truncate(text: str, limit: int = 200) -> str:
 
 
 def _collect_skills() -> list[Entry]:
-    out = []
-    for skill_dir in sorted((SRC / "skills").iterdir()):
-        skill_md = skill_dir / "SKILL.md"
-        if not skill_md.exists():
+    """Walk every source root for skills; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        skills_root = src_root / "skills"
+        if not skills_root.is_dir():
             continue
-        fm = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
-        name = fm.get("name") or skill_dir.name
-        out.append(Entry(
-            kind="skill",
-            name=name,
-            description=_truncate(fm.get("description", "")),
-            extra="",
-            path=f".agent-src.uncompressed/skills/{skill_dir.name}/SKILL.md",
-        ))
-    return out
+        for skill_dir in sorted(skills_root.iterdir()):
+            if not skill_dir.is_dir() or skill_dir.name in seen:
+                continue
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            fm = _parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+            name = fm.get("name") or skill_dir.name
+            seen[skill_dir.name] = Entry(
+                kind="skill",
+                name=name,
+                description=_truncate(fm.get("description", "")),
+                extra="",
+                path=skill_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 def _collect_rules() -> list[Entry]:
-    out = []
-    for rule_md in sorted((SRC / "rules").glob("*.md")):
-        fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
-        out.append(Entry(
-            kind="rule",
-            name=rule_md.stem,
-            description=_truncate(fm.get("description", "")),
-            extra=fm.get("type", "?"),
-            path=f".agent-src.uncompressed/rules/{rule_md.name}",
-        ))
-    return out
+    """Walk every source root for rules; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        rules_root = src_root / "rules"
+        if not rules_root.is_dir():
+            continue
+        for rule_md in sorted(rules_root.glob("*.md")):
+            if rule_md.stem in seen:
+                continue
+            fm = _parse_frontmatter(rule_md.read_text(encoding="utf-8"))
+            seen[rule_md.stem] = Entry(
+                kind="rule",
+                name=rule_md.stem,
+                description=_truncate(fm.get("description", "")),
+                extra=fm.get("type", "?"),
+                path=rule_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 def _collect_commands() -> list[Entry]:
-    out = []
-    cmd_dir = SRC / "commands"
-    for cmd_md in sorted(cmd_dir.rglob("*.md")):
-        if cmd_md.name == "AGENTS.md":
+    """Walk every source root for commands; first root wins per logical id."""
+    seen: dict[str, Entry] = {}
+    for src_root in artefact_roots():
+        cmd_dir = src_root / "commands"
+        if not cmd_dir.is_dir():
             continue
-        fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
-        is_shim = bool(fm.get("superseded_by"))
-        extra = ""
-        if is_shim:
-            extra = f"shim → /{fm['superseded_by']}"
-        elif fm.get("cluster"):
-            extra = f"cluster: {fm['cluster']}"
-        rel = cmd_md.relative_to(cmd_dir)
-        out.append(Entry(
-            kind="shim" if is_shim else "command",
-            name=fm.get("name") or cmd_md.stem,
-            description=_truncate(fm.get("description", "")),
-            extra=extra,
-            path=f".agent-src.uncompressed/commands/{rel}",
-        ))
-    return out
+        for cmd_md in sorted(cmd_dir.rglob("*.md")):
+            if cmd_md.name == "AGENTS.md":
+                continue
+            rel = cmd_md.relative_to(cmd_dir).as_posix()
+            if rel in seen:
+                continue
+            fm = _parse_frontmatter(cmd_md.read_text(encoding="utf-8"))
+            is_shim = bool(fm.get("superseded_by"))
+            extra = ""
+            if is_shim:
+                extra = f"shim → /{fm['superseded_by']}"
+            elif fm.get("cluster"):
+                extra = f"cluster: {fm['cluster']}"
+            seen[rel] = Entry(
+                kind="shim" if is_shim else "command",
+                name=fm.get("name") or cmd_md.stem,
+                description=_truncate(fm.get("description", "")),
+                extra=extra,
+                path=cmd_md.relative_to(ROOT).as_posix(),
+            )
+    return [seen[k] for k in sorted(seen)]
 
 
 def _collect_guidelines() -> list[Entry]:
@@ -137,8 +163,14 @@ def _collect_guidelines() -> list[Entry]:
 # Path rewriter for the public catalog: link to the shipped surface
 # (`.agent-src/`) instead of the source-of-truth (`.agent-src.uncompressed/`),
 # which is excluded from `package.json#files` and `composer.json` archives.
+# Post-ADR-017 the source-of-truth lives at packages/*/.agent-src.uncompressed/,
+# so we strip whichever prefix matches and pin to the flat .agent-src/ output.
 def _to_shipped_path(path: str) -> str:
-    return path.replace(".agent-src.uncompressed/", ".agent-src/", 1)
+    from _lib.agent_src import strip_source_prefix
+    logical = strip_source_prefix(path)
+    if logical is not None:
+        return f".agent-src/{logical}"
+    return path
 
 
 def _render_table(