@event4u/agent-config 1.15.0 → 1.17.0

package/scripts/check_portability.py

@@ -250,6 +250,55 @@ def check_file(filepath: Path, patterns: list, allowlist: list) -> List[Violatio
     return violations
 
 
+# ── Identity-framing detector ───────────────────────────────────────────
+# The package's public identity surface (README, AGENTS, copilot-instructions)
+# must read stack-neutral. Laravel is the deepest reference stack today, never
+# the headline. This detector flags banned phrases that elevate any single
+# stack to identity status. Source-of-truth list lives in the
+# road-to-1-15-followups.md roadmap (P0 #1, F1.5).
+_IDENTITY_FRAMING_PATTERNS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"\bLaravel-first\b", re.IGNORECASE), "identity-laravel-first"),
+    (re.compile(r"\bfor\s+PHP\s*/\s*Laravel\s+teams?\b", re.IGNORECASE), "identity-for-php-laravel-teams"),
+    (re.compile(r"\bfor\s+Laravel\s+teams?\b", re.IGNORECASE), "identity-for-laravel-teams"),
+    (re.compile(r"\bprimary\s+audience\s*[:=]\s*Laravel\b", re.IGNORECASE), "identity-primary-audience-laravel"),
+    (re.compile(r"\bbuilt\s+for\s+Laravel\b", re.IGNORECASE), "identity-built-for-laravel"),
+    (re.compile(r"\bLaravel\s*=\s*primary\b", re.IGNORECASE), "identity-laravel-equals-primary"),
+    (re.compile(r"\*\*Reference\s+implementation:\s*Laravel\.?\*\*", re.IGNORECASE), "identity-reference-implementation-laravel"),
+]
+
+# Files whose identity framing must stay stack-neutral. Relative to repo root.
+IDENTITY_SCAN_FILES = [
+    "README.md",
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+]
+
+
+def check_identity_framing(filepath: Path) -> List[Violation]:
+    """Flag banned identity-framing phrases in README / AGENTS / copilot-instructions.
+
+    The package presents itself as a universal governance system; any phrase
+    that pins identity to a single stack (Laravel-first, built for Laravel,
+    Reference implementation: Laravel as a bolded headline) is a regression.
+    """
+    violations: List[Violation] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8").splitlines()
+    except Exception:
+        return violations
+
+    for i, line in enumerate(lines, 1):
+        for pattern, name in _IDENTITY_FRAMING_PATTERNS:
+            m = pattern.search(line)
+            if m:
+                violations.append(Violation(
+                    file=str(filepath), line=i, match=m.group(0),
+                    pattern_name=name, severity="error",
+                    context=line.strip(),
+                ))
+    return violations
+
+
 # ── Task-command detector ───────────────────────────────────────────────
 # Artefact files shipped in the package must not reference `task <name>`
 # invocations (per augment-portability rule). Consumer projects may not
@@ -266,6 +315,7 @@ _TASK_FENCE_RE = re.compile(r"^\s*task\s+([a-z][a-z0-9:_-]*)\b")
 # by the task-invocation detector (but still scanned for layer 1 + 2).
 _TASK_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )
 
 
@@ -373,6 +423,7 @@ _CLI_INVOCATION_MAP: list[tuple[re.Pattern, str]] = [
 # own help, the portability rule that defines the mapping).
 _CLI_DETECTOR_SKIP = (
     "rules/augment-portability.md",
+    "contexts/communication/rules-auto/augment-portability-mechanics.md",
 )
 
 
@@ -467,6 +518,12 @@ def scan_all(root: Path) -> tuple[List[Violation], list[str]]:
                 if not any(path_str.endswith(skip) for skip in _CLI_DETECTOR_SKIP):
                     violations.extend(check_cli_invocations(f))
 
+    # Layer 5: identity-framing scan on the public identity surface
+    for rel in IDENTITY_SCAN_FILES:
+        f = root / rel
+        if f.is_file():
+            violations.extend(check_identity_framing(f))
+
     return violations, detected
 
 

package/scripts/check_public_catalog_links.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+Public-catalog link checker (regression guard for road-to-pr-34-followups 1.1).
+
+`docs/catalog.md` is the consumer-facing catalog rendered by
+`scripts/generate_index.py`. Consumers receive the package via npm /
+Composer / archive surfaces — `.agent-src.uncompressed/` is **not**
+shipped (see `package.json#files`). Every link in the public catalog
+must therefore resolve to a shipped surface.
+
+Checks:
+  1. No link href contains `.agent-src.uncompressed/`.
+  2. Every link href resolves on disk.
+  3. Every link href starts with a path declared in `package.json#files`
+     (or one of the always-shipped root files).
+
+Exit codes: 0 = clean, 1 = violations found.
+
+Usage:
+    python3 scripts/check_public_catalog_links.py
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CATALOG = ROOT / "docs" / "catalog.md"
+PACKAGE_JSON = ROOT / "package.json"
+
+LINK_RE = re.compile(r"\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+FORBIDDEN_PREFIX = ".agent-src.uncompressed/"
+
+
+def _shipped_roots() -> tuple[set[str], set[str]]:
+    """Return (shipped_dirs, shipped_files) from package.json#files."""
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    dirs: set[str] = set()
+    files: set[str] = set()
+    for entry in data.get("files", []):
+        if entry.endswith("/"):
+            dirs.add(entry.rstrip("/"))
+        else:
+            files.add(entry)
+    return dirs, files
+
+
+def _resolve(href: str) -> Path | None:
+    href = href.split("#", 1)[0]
+    if not href or href.startswith(("http://", "https://", "mailto:", "tel:")):
+        return None
+    target = (CATALOG.parent / href).resolve()
+    try:
+        return target.relative_to(ROOT.resolve())
+    except ValueError:
+        return None
+
+
+def _under_shipped_surface(rel: Path, dirs: set[str], files: set[str]) -> bool:
+    s = str(rel)
+    if s in files:
+        return True
+    return any(s == d or s.startswith(d + "/") for d in dirs)
+
+
+def main() -> int:
+    if not CATALOG.exists():
+        print(f"❌  {CATALOG.relative_to(ROOT)} not found")
+        return 1
+
+    dirs, files = _shipped_roots()
+    text = CATALOG.read_text(encoding="utf-8")
+
+    forbidden: list[tuple[int, str]] = []
+    missing: list[tuple[int, str]] = []
+    unshipped: list[tuple[int, str]] = []
+
+    for lineno, line in enumerate(text.splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            href = m.group("href")
+            if FORBIDDEN_PREFIX in href:
+                forbidden.append((lineno, href))
+                continue
+            rel = _resolve(href)
+            if rel is None:
+                continue  # external / non-resolvable
+            if not (ROOT / rel).exists():
+                missing.append((lineno, href))
+                continue
+            if not _under_shipped_surface(rel, dirs, files):
+                unshipped.append((lineno, href))
+
+    total_violations = len(forbidden) + len(missing) + len(unshipped)
+    if not total_violations:
+        print(f"✅  docs/catalog.md — all links resolve to shipped surfaces.")
+        return 0
+
+    print(f"❌  docs/catalog.md — {total_violations} violation(s):")
+    if forbidden:
+        print(f"\n  {len(forbidden)} link(s) point at unshipped `.agent-src.uncompressed/`:")
+        for ln, href in forbidden[:10]:
+            print(f"    line {ln}: {href}")
+        if len(forbidden) > 10:
+            print(f"    … and {len(forbidden) - 10} more")
+    if missing:
+        print(f"\n  {len(missing)} link(s) do not resolve on disk:")
+        for ln, href in missing[:10]:
+            print(f"    line {ln}: {href}")
+    if unshipped:
+        print(f"\n  {len(unshipped)} link(s) point outside `package.json#files`:")
+        for ln, href in unshipped[:10]:
+            print(f"    line {ln}: {href}")
+    print("\nFix: update `scripts/generate_index.py` _to_shipped_path() / catalog renderer,")
+    print("then re-run `python3 scripts/generate_index.py`.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_references.py

@@ -32,7 +32,10 @@ class BrokenRef:
 
 
 SCAN_DIRS = [".agent-src", "agents"]
-SKIP_DIRS = ["agents/roadmaps/archive"]  # archived roadmaps have historical refs
+SKIP_DIRS = [
+    "agents/roadmaps/archive",  # archived roadmaps have historical refs
+    "agents/council-sessions",  # per-user audit trail (gitignored), captured provider output
+]
 ROOT = Path(".")
 
 # YAML memory files (engineering-memory layer) live under `agents/memory/`.
@@ -98,6 +101,14 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"skills/[\w-]+/SKILL\.md"),    # example skill paths in commands
     re.compile(r"\{"),                         # template placeholders like {module}
     re.compile(r"\.compression-hashes\.json"), # JSON file, not .md
+    # Forward references inside in-flight planning docs (road-to-
+    # structural-optimization.md and its companion spike protocols).
+    # Each pattern below is removed once the matching phase lands.
+    re.compile(r"structural-optimization-3a-spike\.md"),       # 3a.0.2
+    re.compile(r"contexts/judges/no-consolidate-rationale"),   # 3a.0.2 abort
+    re.compile(r"contexts/judges/judge-shared-procedure"),     # 3a.1
+    re.compile(r"contexts/analysis/project-analysis-core-procedure"),  # 3b.1
+    re.compile(r"agents/roadmaps/phase6-non-overlap-evidence"),        # 6.1 conditional
 ]
 
 
@@ -115,8 +126,20 @@ def collect_artifacts(root: Path) -> dict[str, set[str]]:
             arts["skills"].add(d.name)
     for f in (augment / "rules").glob("*.md") if (augment / "rules").exists() else []:
         arts["rules"].add(f.stem)
-    for f in (augment / "commands").glob("*.md") if (augment / "commands").exists() else []:
-        arts["commands"].add(f.stem)
+    cmd_dir = augment / "commands"
+    if cmd_dir.exists():
+        for f in cmd_dir.rglob("*.md"):
+            if f.name == "AGENTS.md":
+                continue
+            # Top-level: bare stem ("commit"). Nested: cluster-sub ("council-default")
+            # AND the cluster:sub form, since references may use either.
+            rel = f.relative_to(cmd_dir).with_suffix("")
+            parts = rel.parts
+            if len(parts) == 1:
+                arts["commands"].add(parts[0])
+            else:
+                arts["commands"].add("-".join(parts))
+                arts["commands"].add(":".join(parts))
     gdir = augment / "guidelines"
     if gdir.exists():
         for f in gdir.rglob("*.md"):
@@ -222,6 +245,13 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
             if any(p.search(raw_ref) for p in EXAMPLE_PATH_PATTERNS):
                 continue
 
+            # Skip references into directories already excluded from scanning
+            # (gitignored audit trails, archived roadmaps). Files there are
+            # not committed, so existence checks would always fail in CI.
+            if any(raw_ref.startswith(skip + "/") or raw_ref == skip
+                   for skip in SKIP_DIRS):
+                continue
+
             resolved = False
             # Try raw ref as-is from root (covers .agent-src/..., agents/..., etc.)
             if (root / raw_ref).exists():

package/scripts/check_roadmap_trackable.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""CI guard for the `roadmap-progress-sync` rule's trackability Iron Law.
+
+Every non-draft file under `agents/roadmaps/` (excluding `archive/`,
+`skipped/`, template/README/open-questions) MUST:
+
+  1. Be parseable by the dashboard's `PHASE_RE` — i.e. contain at least
+     one `## Phase <id>` or `### Phase <id>` heading.
+  2. Have at least one trackable checkbox (`- [ ]`, `[x]`, `[~]`, `[-]`)
+     under every parsed phase.
+
+A roadmap that fails (1) is invisible to `agents/roadmaps-progress.md`
+and silently lies to the next reader. A phase that fails (2) shows as
+`⬜ empty` and contributes nothing to progress percentages.
+
+Both failure modes are rule violations per
+`.augment/rules/roadmap-progress-sync.md` § "Iron Law — every active
+roadmap is trackable". This script is the CI backstop so the rule
+cannot be quietly broken again.
+
+Exit codes:
+  0 — every active roadmap has parseable phases with at least one
+      checkbox per phase.
+  1 — at least one violation found; details printed to stdout.
+
+Invocation (from project root):
+  python3 scripts/check_roadmap_trackable.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Reuse the dashboard's regexes and helpers — single source of truth so
+# the linter cannot drift from what the dashboard actually parses.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / ".augment" / "scripts"))
+from update_roadmap_progress import (  # noqa: E402
+    CHECKBOX_RE,
+    PHASE_RE,
+    is_draft,
+    is_roadmap_candidate,
+    parse_frontmatter,
+)
+
+ROADMAP_ROOT = Path("agents/roadmaps")
+
+
+def find_active_roadmaps(root: Path) -> list[Path]:
+    """Return every non-draft roadmap candidate under root."""
+    out: list[Path] = []
+    for path in sorted(root.rglob("*.md")):
+        if not path.is_file() or not is_roadmap_candidate(path):
+            continue
+        text = path.read_text(encoding="utf-8")
+        if is_draft(parse_frontmatter(text)):
+            continue
+        out.append(path)
+    return out
+
+
+def violations_for(path: Path) -> list[str]:
+    """Return human-readable violation strings for a single roadmap."""
+    text = path.read_text(encoding="utf-8")
+    matches = list(PHASE_RE.finditer(text))
+    if not matches:
+        return [
+            f"{path}: no `## Phase <id>` or `### Phase <id>` heading "
+            "matched the dashboard's PHASE_RE — roadmap is invisible "
+            "to agents/roadmaps-progress.md. Either rename headings to "
+            "the canonical `Phase <id>` form or add `status: draft` to "
+            "the frontmatter."
+        ]
+    out: list[str] = []
+    for i, pm in enumerate(matches):
+        start = pm.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        if not CHECKBOX_RE.search(text[start:end]):
+            phase_id = pm.group(2)
+            name = (pm.group(3) or "").strip() or f"Phase {phase_id}"
+            out.append(
+                f"{path}: Phase {phase_id} ({name[:60]}) has zero "
+                "trackable checkboxes — add at least one `- [ ]` (or "
+                "`[x]`/`[~]`/`[-]`) item or remove the phase."
+            )
+    return out
+
+
+def main() -> int:
+    if not ROADMAP_ROOT.is_dir():
+        print(f"❌  {ROADMAP_ROOT} not found — run from project root.", file=sys.stderr)
+        return 1
+    findings: list[str] = []
+    for path in find_active_roadmaps(ROADMAP_ROOT):
+        findings.extend(violations_for(path))
+    if findings:
+        print("❌  Trackable-roadmap rule violations:\n")
+        for f in findings:
+            print(f"  - {f}")
+        print(
+            "\nRule: .augment/rules/roadmap-progress-sync.md "
+            '§ "Iron Law — every active roadmap is trackable"'
+        )
+        return 1
+    count = len(find_active_roadmaps(ROADMAP_ROOT))
+    print(f"✅  {count} active roadmap(s) — all parseable, all phases have checkboxes.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_safety_floor_untouched.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Safety-floor exclusion linter (Phase 2A.0 of road-to-structural-optimization).
+
+Per Q3=A locked decision (council Round 3, 2026-05-03), the four
+safety-floor always-rules are out of scope for Phase 2A slimming:
+
+  - non-destructive-by-default
+  - commit-policy
+  - scope-control
+  - verify-before-complete
+
+This linter compares HEAD against a baseline ref (default: ``main``)
+and fails CI if any of those four rule files were modified by the
+working branch.
+
+Lift via the two-gate rollback documented in
+``agents/roadmaps/road-to-structural-optimization.md`` § Phase 2A
+Abort/rollback.
+
+Exit codes: 0 = clean (or skipped — see ``--skip-if-no-baseline``),
+1 = safety-floor file modified, 3 = internal error.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR_REL = ".agent-src.uncompressed/rules"
+SAFETY_FLOOR = (
+    "non-destructive-by-default.md",
+    "commit-policy.md",
+    "scope-control.md",
+    "verify-before-complete.md",
+)
+
+
+def _run_git(args: list[str]) -> tuple[int, str]:
+    proc = subprocess.run(
+        ["git", *args],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+def _baseline_exists(ref: str) -> bool:
+    code, _ = _run_git(["rev-parse", "--verify", "--quiet", ref])
+    return code == 0
+
+
+def _changed_files(baseline: str) -> list[str]:
+    code, output = _run_git(["diff", "--name-only", f"{baseline}...HEAD"])
+    if code != 0:
+        raise RuntimeError(f"git diff failed: {output}")
+    return [line.strip() for line in output.splitlines() if line.strip()]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--baseline",
+        default="origin/main",
+        help="Baseline ref (default: origin/main)",
+    )
+    parser.add_argument(
+        "--skip-if-no-baseline",
+        action="store_true",
+        help="Exit 0 silently if baseline ref does not exist (local dev)",
+    )
+    args = parser.parse_args()
+
+    if not _baseline_exists(args.baseline):
+        if args.skip_if_no_baseline:
+            print(f"ℹ️  baseline {args.baseline} not found — skipped")
+            return 0
+        # Fallback: try plain `main`
+        if _baseline_exists("main"):
+            args.baseline = "main"
+        else:
+            print(
+                f"❌  baseline {args.baseline} (and `main`) not found. "
+                "Pass --skip-if-no-baseline to silence in local dev.",
+                file=sys.stderr,
+            )
+            return 3
+
+    try:
+        changed = _changed_files(args.baseline)
+    except RuntimeError as exc:
+        print(f"❌  {exc}", file=sys.stderr)
+        return 3
+
+    floor_paths = {f"{RULES_DIR_REL}/{name}" for name in SAFETY_FLOOR}
+    breaches = sorted(p for p in changed if p in floor_paths)
+
+    if breaches:
+        print(
+            "❌  Safety-floor rule(s) modified — Phase 2A is not allowed to "
+            "touch these (Q3=A locked decision):",
+            file=sys.stderr,
+        )
+        for path in breaches:
+            print(f"    {path}", file=sys.stderr)
+        print(
+            "\n    Lift via the two-gate rollback documented in "
+            "agents/roadmaps/road-to-structural-optimization.md "
+            "§ Phase 2A Abort/rollback.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"✅  Safety-floor untouched ({len(SAFETY_FLOOR)} rules guarded "
+        f"vs. {args.baseline})."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/command_suggester/cooldown.py

@@ -31,7 +31,7 @@ def is_explicit_slash_invocation(message: str) -> bool:
 
     Per the `command-suggestion` rule, explicit slash invocations
     bypass the suggestion layer entirely \u2014 they're handled by
-    `slash-commands` directly. The engine should not score in that
+    `slash-command-routing-policy` directly. The engine should not score in that
     case. Helper exposed for the runtime caller and the GT-CS4
     golden.
     """

package/scripts/command_suggester/loader.py

@@ -26,7 +26,10 @@ def load_commands(commands_dir: Path) -> list[CommandSpec]:
     this loader.
     """
     specs: list[CommandSpec] = []
-    for path in sorted(commands_dir.glob("*.md")):
+    for path in sorted(commands_dir.rglob("*.md")):
+        # Skip cluster authoring docs — not commands.
+        if path.name == "AGENTS.md":
+            continue
         text = path.read_text(encoding="utf-8")
         data, _offset = parse_frontmatter(text)
         if data is None:

package/scripts/compress.py

@@ -312,6 +312,29 @@ def generate_gemini_md() -> None:
     print("  ✅  Created GEMINI.md → AGENTS.md symlink")
 
 
+def _command_slug(source_file: Path) -> str:
+    """Return the flat .claude/skills/ slug for a command source file.
+
+    Top-level commands keep their stem (`commit.md` → `commit`). Nested
+    commands flatten the relative path with `-` (`council/default.md` →
+    `council-default`). Keeps slug collisions out of `.claude/skills/`
+    while preserving native nested invocation in `.agent-src/commands/`.
+    """
+    rel = source_file.relative_to(COMMANDS_SOURCE)
+    return "-".join(rel.with_suffix("").parts)
+
+
+def _iter_commands():
+    """Yield (source_file, slug) for every command .md file (recursive)."""
+    if not COMMANDS_SOURCE.exists():
+        return
+    for source_file in sorted(COMMANDS_SOURCE.rglob("*.md")):
+        # Skip the cluster AGENTS.md authoring doc (not a command).
+        if source_file.name == "AGENTS.md":
+            continue
+        yield source_file, _command_slug(source_file)
+
+
 def generate_claude_skills() -> None:
     """Create .claude/skills/ symlinks for ALL skills in .agent-src/skills/.
     """
@@ -321,16 +344,14 @@ def generate_claude_skills() -> None:
 
     # All skill directories in .agent-src/skills/
     skills = sorted([d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()])
-    # All command names (to protect from stale cleanup)
-    command_names = set()
-    if COMMANDS_SOURCE.exists():
-        command_names = {f.stem for f in COMMANDS_SOURCE.glob("*.md")}
+    # All command slugs (to protect from stale cleanup)
+    command_slugs = {slug for _, slug in _iter_commands()}
 
     CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
 
     # Clean stale symlinks (but not converted commands or README)
     for item in CLAUDE_SKILLS_DIR.iterdir():
-        if item.is_symlink() and item.name not in skills and item.name not in command_names and item.name != "README.md":
+        if item.is_symlink() and item.name not in skills and item.name not in command_slugs and item.name != "README.md":
             item.unlink()
 
     count = 0
@@ -357,11 +378,15 @@ def extract_description_from_md(content: str) -> str:
 
 
 def generate_claude_commands() -> None:
-    """Create .claude/skills/{name}/SKILL.md symlinks for ALL Augment commands.
+    """Create .claude/skills/{slug}/SKILL.md symlinks for ALL Augment commands.
 
     Commands in .agent-src/commands/ are the single source of truth.
     They must include name: and disable-model-invocation: true in frontmatter
     (added once, then maintained as part of the command file).
+
+    Top-level commands use their filename stem as the slug. Nested
+    cluster commands (e.g. `commands/council/default.md`) are flattened
+    to `council-default` so directories never collide in `.claude/skills/`.
     """
     if not COMMANDS_SOURCE.exists():
         print("  ⚠️  .agent-src/commands/ not found — skipping commands")
@@ -374,32 +399,53 @@ def generate_claude_commands() -> None:
     if SKILLS_SOURCE.exists():
         skill_names = {d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()}
 
+    # Track current command slugs for stale-directory cleanup
+    current_slugs: set[str] = set()
     count = 0
     skipped = 0
-    for source_file in sorted(COMMANDS_SOURCE.glob("*.md")):
-        name = source_file.stem
-
+    for source_file, slug in _iter_commands():
         # Skip if a real skill with the same name exists — skill takes priority
-        if name in skill_names:
+        if slug in skill_names:
             skipped += 1
             continue
 
+        current_slugs.add(slug)
+
         # Create skill directory (real dir, symlinked SKILL.md inside)
-        skill_dir = CLAUDE_SKILLS_DIR / name
+        skill_dir = CLAUDE_SKILLS_DIR / slug
         skill_dir.mkdir(parents=True, exist_ok=True)
 
         skill_file = skill_dir / "SKILL.md"
         if skill_file.exists() or skill_file.is_symlink():
             skill_file.unlink()
 
-        # Symlink: .claude/skills/{name}/SKILL.md → ../../../.agent-src/commands/{name}.md
-        rel_target = Path("../../../.agent-src/commands") / source_file.name
+        # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
+        rel_path = source_file.relative_to(COMMANDS_SOURCE)
+        rel_target = Path("../../../.agent-src/commands") / rel_path
         skill_file.symlink_to(rel_target)
         count += 1
 
+    # Clean stale command skill directories — real dirs from removed commands.
+    # Only delete if the directory contains exactly the SKILL.md symlink we created.
+    removed_dirs = 0
+    for item in CLAUDE_SKILLS_DIR.iterdir():
+        if not item.is_dir() or item.is_symlink():
+            continue
+        if item.name in skill_names or item.name in current_slugs:
+            continue
+        skill_md = item / "SKILL.md"
+        if skill_md.is_symlink():
+            entries = list(item.iterdir())
+            if len(entries) == 1 and entries[0].name == "SKILL.md":
+                skill_md.unlink()
+                item.rmdir()
+                removed_dirs += 1
+
     msg = f"  ✅  Created {count} command symlinks in .claude/skills/"
     if skipped:
         msg += f" ({skipped} skipped — same-name skill exists)"
+    if removed_dirs:
+        msg += f" ({removed_dirs} stale dirs removed)"
     print(msg)