@event4u/agent-config 3.0.0 → 3.1.1

package/scripts/check_command_count_messaging.py

@@ -18,13 +18,13 @@ Patterns checked (per file):
 
     README.md
       hero badge   "/badge/Commands-{N}-…"                    → active
-      browse line  "Browse all {N} active commands"           → active
-      browse meta  "{N} files total"                          → total
-      browse meta  "{N} are deprecation shims"                → shims
-      tools blurb  "{N} native commands"                      → active
+      (Prose phrasings "Browse all {N} active commands" and
+       "{N} native commands" were retired in the modernized
+       README — the badge alone now carries the count.)
 
     AGENTS.md
       tree         "commands/  ({N} files — {A} active + {S} deprecation shims)"
+      (Thin-Root: only checked when a `commands/` tree block exists.)
 
     docs/getting-started.md
       browse line  "Browse all {N} active commands"           → active
@@ -38,10 +38,12 @@ import re
 import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
 QUIET = "--quiet" in sys.argv
 
 ROOT = Path(__file__).resolve().parent.parent
-COMMANDS_DIR = ROOT / ".agent-src.uncompressed" / "commands"
 README = ROOT / "README.md"
 AGENTS = ROOT / "AGENTS.md"
 GETTING_STARTED = ROOT / "docs" / "getting-started.md"
@@ -50,14 +52,33 @@ FM_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
 SUPERSEDED_RE = re.compile(r"^superseded_by:\s*\S", re.MULTILINE)
 
 
+def _command_files() -> list[Path]:
+    """Every command ``*.md`` file across all source roots (legacy + packages/*).
+
+    Multi-root aware per ADR-017: post-move the commands live under
+    ``packages/<pack>/.agent-src.uncompressed/commands/``, and the
+    canonical count is the union across packs (deduped by logical path).
+    """
+    seen: dict[str, Path] = {}
+    for root in artefact_roots():
+        cmd_dir = root / "commands"
+        if not cmd_dir.is_dir():
+            continue
+        for f in cmd_dir.rglob("*.md"):
+            if f.name == "AGENTS.md":
+                continue
+            rel = f.relative_to(cmd_dir).as_posix()
+            seen.setdefault(rel, f)
+    return sorted(seen.values())
+
+
 def canonical_counts() -> tuple[int, int, int]:
-    if not COMMANDS_DIR.is_dir():
-        print(f"❌  {COMMANDS_DIR.relative_to(ROOT)} not found", file=sys.stderr)
+    files = _command_files()
+    if not files:
+        print("❌  no commands/ directory found under any artefact root", file=sys.stderr)
         sys.exit(1)
     total = shims = 0
-    for f in COMMANDS_DIR.rglob("*.md"):
-        if f.name == "AGENTS.md":
-            continue
+    for f in files:
         total += 1
         m = FM_RE.match(f.read_text(encoding="utf-8"))
         fm = m.group(1) if m else ""
@@ -83,11 +104,9 @@ def main() -> int:
     print(f"Canonical counts: {total} files · {shims} shims · {active} active")
 
     checks = [
-        # README.md
+        # README.md — modernized: badge is the sole count surface
         (README, r"/badge/Commands-(\d+)-", active, "hero badge"),
-        (README, r"Browse all (\d+) active commands", active, "browse line"),
-        (README, r"\+ (\d+) native commands\)", active, "tools blurb"),
-        # docs/getting-started.md
+        # docs/getting-started.md — still carries the prose browse line
         (GETTING_STARTED, r"Browse all (\d+) active commands", active, "browse line"),
     ]
     # Shim-specific messaging only applies during a deprecation window.

package/scripts/check_council_references.py

@@ -39,6 +39,8 @@ from typing import Iterable
 QUIET = "--quiet" in sys.argv
 
 ROOT = Path(".")
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots, strip_source_prefix  # noqa: E402
 
 # A specific file inside a council dir: must end with .md or .json,
 # must NOT contain `<` or `>` (placeholders), must NOT contain backticks
@@ -50,8 +52,11 @@ PATTERN = re.compile(
 
 # Only these durable surfaces are scanned. Archive, analysis, and the
 # council dirs themselves are excluded by design.
-SCAN_ROOTS = (
-    ".agent-src.uncompressed",
+#
+# Source roots (legacy `.agent-src.uncompressed/` and every
+# `packages/*/.agent-src.uncompressed/`) are discovered at runtime via
+# `artefact_roots()` so the linter follows the monorepo physical layout.
+FIXED_SCAN_ROOTS = (
     "agents/roadmaps",
     "agents/settings/contexts",
     "agents/reference/docs",
@@ -59,6 +64,23 @@ SCAN_ROOTS = (
     "docs/decisions",
     "docs/guidelines",
 )
+
+
+def _scan_roots() -> tuple[str, ...]:
+    cwd = Path(".").resolve()
+    roots: list[str] = []
+    for r in artefact_roots():
+        try:
+            roots.append(r.relative_to(cwd).as_posix() if r.is_absolute() else r.as_posix())
+        except ValueError:
+            # Root lives outside the current working directory (e.g. tests
+            # chdir into a tmp tree). Skip — the test isolates its own
+            # source tree.
+            continue
+    roots.extend(FIXED_SCAN_ROOTS)
+    return tuple(roots)
+
+
 SCAN_EXTS = (".md", ".yml", ".yaml", ".json", ".py")
 
 # Files (or directory prefixes) that legitimately document the output
@@ -111,9 +133,26 @@ STRUCTURAL_CARVEOUTS: tuple[tuple[re.Pattern[str], re.Pattern[str]], ...] = (
 
 
 def _is_allowlisted(rel: str) -> bool:
+    """Match a repo-relative POSIX path against the allowlist.
+
+    Allowlist prefixes are written against the legacy
+    ``.agent-src.uncompressed/`` layout. A physical hit under
+    ``packages/*/.agent-src.uncompressed/`` is normalised to the same
+    logical path before matching so entries keep covering relocated files.
+    """
     if rel in ALLOWLIST_FILES:
         return True
-    return any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES)
+    if any(rel.startswith(prefix) for prefix in ALLOWLIST_PREFIXES):
+        return True
+    logical = strip_source_prefix(rel)
+    if logical is not None:
+        canon = f"{_LEGACY_PREFIX_STR}{logical}"
+        if any(canon.startswith(prefix) for prefix in ALLOWLIST_PREFIXES):
+            return True
+    return False
+
+
+_LEGACY_PREFIX_STR = ".agent-src.uncompressed/"
 
 
 def _is_structurally_allowed(source_rel: str, target_capture: str) -> bool:
@@ -156,7 +195,7 @@ def _iter_files(roots: Iterable[str]) -> Iterable[Path]:
 
 def main() -> int:
     violations: list[tuple[Path, int, str]] = []
-    for path in _iter_files(SCAN_ROOTS):
+    for path in _iter_files(_scan_roots()):
         rel = path.as_posix()
         if _is_allowlisted(rel):
             continue

package/scripts/check_overlay_cascade_subdirs.py

@@ -30,10 +30,14 @@ from scripts._lib.agents_overlay import (  # noqa: E402
 
 DOCS_PATH = REPO_ROOT / "docs" / "customization.md"
 
-# Match `agents/<kind>/` in the first column of the overlay table, plus
-# the ✅/❌ markers in columns 2 and 3.
+# Match `agents/<...>/<kind>/` in the first column of the overlay
+# table, plus the ✅/❌ markers in columns 2 and 3. Captures only the
+# **final** path segment as the kind, so both flat (`agents/overrides/`)
+# and nested (`agents/settings/contexts/`) rows resolve to the bare
+# kind name that ``CASCADE_ELIGIBLE_KINDS`` carries.
 ROW_RE = re.compile(
-    r"^\|\s*`agents/([a-z][a-z0-9_-]*)/`\s*\|\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
+    r"^\|\s*`agents/(?:[a-z][a-z0-9_-]*/)*([a-z][a-z0-9_-]*)/`\s*\|"
+    r"\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
 )
 
 

package/scripts/check_references.py

@@ -81,8 +81,10 @@ SKILL_REF_PATTERN = re.compile(r'`([\w-]+)`\s+skill')
 RULE_REF_PATTERN = re.compile(r'`([\w-]+)`\s+rule')
 
 # Unchecked TODO items (roadmap checkboxes) legitimately reference files
-# and artifacts that do not exist yet. Skip these lines.
-UNCHECKED_TODO_PATTERN = re.compile(r'^\s*[-*+]\s+\[ \]\s')
+# and artifacts that do not exist yet. Skip these lines. `[~]` marks
+# deferred work — same semantics as `[ ]` for reference resolution
+# (forward-looking path, will materialize when the step ships).
+UNCHECKED_TODO_PATTERN = re.compile(r'^\s*[-*+]\s+\[[ ~]\]\s')
 _SKIP_NAMES = {"the", "a", "an", "this", "that", "your", "my", "no", "any", "each", "one",
                "always", "auto", "fail", "vue", "guidelines", "naming",
                "orderBy", "no-commit", "skill-linter", "skill-validator",
@@ -110,6 +112,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"agents/learnings/"),           # consumer-project learning notes
     re.compile(r"agents/proposals/"),           # consumer-project self-improvement proposals
     re.compile(r"agents/drafts/"),              # consumer-project artefact drafts
+    re.compile(r"agents/\.event4u-bridge\.yml"),  # consumer-project bridge marker (ADR-020)
     re.compile(r"guidelines/php-"),             # flattened override naming convention
     re.compile(r"rules/no-commit"),            # example rule in commands
     re.compile(r"skills/[\w-]+\.md"),          # short skill refs in examples (not SKILL.md path)

package/scripts/check_reply_consistency.py

@@ -21,6 +21,10 @@ import re
 import sys
 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
+
 QUIET = "--quiet" in sys.argv
 
 OPTION_LINE_RE = re.compile(r"^\s*>?\s*(\d+)\.\s+\S")
@@ -95,23 +99,42 @@ def validate(text: str, strict: bool = False) -> tuple[int, str]:
 
 
 def cmd_scan_dir(root: Path) -> int:
+    # If the requested root is the legacy ".agent-src.uncompressed" and it
+    # no longer exists (post-monorepo-move), fall back to artefact_roots()
+    # so every packages/*/.agent-src.uncompressed/ is scanned.
     if not root.is_dir():
-        print(f"error: not a directory: {root}", file=sys.stderr)
-        return 9
+        legacy = ROOT / ".agent-src.uncompressed"
+        if root.resolve() == legacy.resolve():
+            roots = artefact_roots()
+            if not roots:
+                print("error: no artefact roots found (legacy or packages/*)", file=sys.stderr)
+                return 9
+        else:
+            print(f"error: not a directory: {root}", file=sys.stderr)
+            return 9
+    else:
+        roots = [root]
     violations: list[tuple[Path, int, str]] = []
-    for md in sorted(root.rglob("*.md")):
-        text = md.read_text(encoding="utf-8")
-        for idx, raw in enumerate(text.splitlines(), start=1):
-            stripped = _strip_codespans(raw)
-            if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
-                violations.append((md, idx, raw.strip()))
+    for r in roots:
+        for md in sorted(r.rglob("*.md")):
+            text = md.read_text(encoding="utf-8")
+            for idx, raw in enumerate(text.splitlines(), start=1):
+                stripped = _strip_codespans(raw)
+                if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
+                    violations.append((md, idx, raw.strip()))
     if violations:
         for path, line, snippet in violations:
             print(f"  🔴 {path}:{line} — inline-tag — {snippet}", file=sys.stderr)
         print(f"\n❌  {len(violations)} legacy-pattern violation(s)", file=sys.stderr)
         return 6
     if not QUIET:
-        print(f"✅  No legacy (recommended) tags found under {root}")
+        def _rel(p: Path) -> str:
+            try:
+                return p.relative_to(ROOT).as_posix()
+            except ValueError:
+                return p.as_posix()
+        scanned = ", ".join(_rel(r) for r in roots)
+        print(f"✅  No legacy (recommended) tags found under {scanned}")
     return 0
 
 

package/scripts/check_template_pin_drift.py

@@ -24,12 +24,26 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
 
 PACKAGE_JSON = REPO_ROOT / "package.json"
-TEMPLATE_FILES = (
-    REPO_ROOT / ".agent-src.uncompressed" / "templates" / "agents" / "agent-project-settings.example.yml",
-    REPO_ROOT / ".agent-src" / "templates" / "agents" / "agent-project-settings.example.yml",
-)
+
+# Source-of-truth template lives under whichever artefact root owns it
+# (legacy .agent-src.uncompressed/ pre-move, packages/*/.agent-src.uncompressed/
+# post-ADR-017). Compressed twin always lands at the flat .agent-src/ surface.
+_TEMPLATE_LOGICAL = "templates/agents/agent-project-settings.example.yml"
+
+
+def _template_files() -> tuple[Path, ...]:
+    src = resolve_logical(_TEMPLATE_LOGICAL)
+    files: list[Path] = []
+    if src is not None:
+        files.append(src)
+    else:
+        files.append(REPO_ROOT / ".agent-src.uncompressed" / _TEMPLATE_LOGICAL)
+    files.append(REPO_ROOT / ".agent-src" / _TEMPLATE_LOGICAL)
+    return tuple(files)
 PIN_LINE_RE = re.compile(r"^\s*agent_config_version\s*:\s*\"?([^\"\s#]*)\"?")
 
 
@@ -70,12 +84,15 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     failures: list[str] = []
-    for template in TEMPLATE_FILES:
+    for template in _template_files():
+        try:
+            rel = template.relative_to(REPO_ROOT)
+        except ValueError:
+            rel = template
         if not template.is_file():
-            failures.append(f"missing template file: {template.relative_to(REPO_ROOT)}")
+            failures.append(f"missing template file: {rel}")
             continue
         pin = _read_template_pin(template)
-        rel = template.relative_to(REPO_ROOT)
         if pin is None:
             failures.append(f"{rel}: no `agent_config_version:` line found")
             continue

package/scripts/check_token_optimizer_freshness.py

@@ -21,7 +21,16 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-SKILL = REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
+# Post-ADR-017 the source-of-truth lives under whichever package owns
+# the skill; resolve_logical() walks every artefact root.
+SKILL = resolve_logical("skills/token-optimizer/SKILL.md") or (
+    REPO_ROOT / ".agent-src.uncompressed" / "skills" / "token-optimizer" / "SKILL.md"
+)
+
+from _lib.agent_src import strip_source_prefix  # noqa: E402
 
 # Catalog row pattern: | name | path | keywords | description |
 ROW_RE = re.compile(
@@ -74,8 +83,14 @@ def resolve(path: str) -> Path | None:
         return None
     cleaned = path.strip().lstrip("`").rstrip("`")
     cleaned = cleaned.split(")")[0].lstrip("[(")
-    candidate = (REPO_ROOT / cleaned).resolve()
-    return candidate
+    # Catalog rows still cite the legacy .agent-src.uncompressed/ prefix
+    # for compactness; resolve those across every packages/* root.
+    logical = strip_source_prefix(cleaned)
+    if logical is not None:
+        hit = resolve_logical(logical)
+        if hit is not None:
+            return hit
+    return (REPO_ROOT / cleaned).resolve()
 
 
 def check_row(row: dict[str, str]) -> list[str]:

package/scripts/compile_router.py

@@ -15,8 +15,11 @@ import sys
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
+# ADR-017: rules now live across multiple source roots. Legacy
+# .agent-src.uncompressed/rules/ is kept as a fallback for the
+# pure-compressed consumer projection.
 RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
-OUT_PATH = ROOT / "router.json"
+OUT_PATH = ROOT / "dist" / "router.json"
 SETTINGS_PATH = ROOT / ".agent-settings.yml"
 SCHEMA_VERSION = 1
 
@@ -116,11 +119,39 @@ def _load_settings() -> dict:
     return load_agent_settings(project_path=SETTINGS_PATH)
 
 
+def _iter_rule_files() -> list[Path]:
+    """Walk every source root for rule files. First root wins per id."""
+    try:
+        from scripts._lib.agent_src import artefact_roots  # type: ignore
+    except ImportError:
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_src import artefact_roots  # type: ignore[import-not-found]
+
+    seen: dict[str, Path] = {}
+    roots = artefact_roots()
+    if not roots:
+        # Pure-compressed fallback for consumer projections that vendor
+        # the flat .agent-src/ tree without sources.
+        if RULES_DIR.exists():
+            for path in sorted(RULES_DIR.glob("*.md")):
+                seen.setdefault(path.stem, path)
+    else:
+        for src_root in roots:
+            rd = src_root / "rules"
+            if not rd.exists():
+                continue
+            for path in sorted(rd.glob("*.md")):
+                seen.setdefault(path.stem, path)
+    return [seen[k] for k in sorted(seen)]
+
+
 def _collect(rules_dir: Path) -> dict:
     settings = _load_settings()
     kernel: list[str] = []
     tiered: dict[str, list[dict]] = {"tier-1": [], "tier-2": []}
-    for path in sorted(rules_dir.glob("*.md")):
+    for path in _iter_rule_files():
         fm = _parse_frontmatter(path.read_text(encoding="utf-8"))
         if not fm:
             continue
@@ -172,6 +203,7 @@ def main(argv: list[str]) -> int:
             return 1
         print("✅  router.json is up to date")
         return 0
+    OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
     OUT_PATH.write_text(text, encoding="utf-8")
     counts = (len(out["kernel"]), len(out["tier_1"]), len(out["tier_2"]))
     print(f"✅  router.json — kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}")