@event4u/agent-config 3.3.0 → 4.2.0

package/scripts/_lib/agent_settings.py

@@ -50,6 +50,7 @@ Contract — pure, read-only, tolerant:
 """
 from __future__ import annotations
 
+import copy
 import logging
 import os
 from pathlib import Path
@@ -60,6 +61,7 @@ from . import user_global_paths
 logger = logging.getLogger(__name__)
 
 DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_TEAM_FILE = ".agent-project-settings.yml"
 USER_GLOBAL_FILENAME = "agent-settings.yml"
 
 #: Canonical write target under the new ``~/.event4u/agent-config/``
@@ -86,11 +88,25 @@ MERGEABLE_KEYS: tuple[str, ...] = (
     "cost_profile",
     "personal.bot_icon",
     "personal.autonomy",
-    "caveman.speak_scope",
+    "telegraph.speak_scope",
 )
 
 _DEFAULTS: dict[str, Any] = {}
 
+#: Defaults applied by :func:`get_modules_config` when a key is absent
+#: from both the team file and the developer cascade. The values mirror
+#: the ``modules:`` block shipped in
+#: ``templates/agents/agent-project-settings.example.yml``. Lists are
+#: returned as fresh copies — callers may mutate the result safely.
+MODULES_DEFAULTS: dict[str, Any] = {
+    "enabled": False,
+    "root_paths": [],
+    "namespace_template": "",
+    "agent_folder": "agents",
+    "skip_dirs": [".module-template", ".example"],
+    "detection_acknowledged": False,
+}
+
 
 #: Anchor identifier returned by :func:`find_project_root_with_anchor`.
 ANCHOR_AGENT_SETTINGS = "agent-settings"
@@ -470,6 +486,184 @@ def load_agent_settings(
     return merged
 
 
+def get_modules_config(
+    project_root: Path | str | None = None,
+    team_path: Path | str | None = None,
+    project_path: Path | str | None = None,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    """Return the merged ``modules:`` configuration with defaults applied.
+
+    Three-tier precedence (deepest wins) per the layered-settings model
+    documented in ``docs/guidelines/agent-infra/layered-settings.md``:
+
+    1. :data:`MODULES_DEFAULTS` — package-shipped defaults.
+    2. Team file — ``<project_root>/.agent-project-settings.yml``
+       (committed, all developers see the same values).
+    3. Developer cascade — every ``.agent-settings.yml`` walked by
+       :func:`_resolve_cascade_paths` (git-ignored local overrides).
+
+    The team layer may pin keys via a top-level ``locked_keys`` list of
+    dotted paths (e.g. ``[modules.root_paths]``). Locked keys discard any
+    matching override from the developer cascade and emit a ``logging``
+    INFO record. Locks are advisory — the team file always wins anyway —
+    but the explicit list makes the intent reviewable and gives the loader
+    a hook for the warning.
+
+    ``project_root`` defaults to ``find_project_root(cwd or Path.cwd())``.
+    ``team_path`` overrides the resolved team-file location for tests.
+    ``project_path`` + ``cwd`` flow through to :func:`load_agent_settings`
+    unchanged.
+
+    Pure, read-only — no file is ever written. Missing files / malformed
+    YAML / absent ``modules:`` block all return the defaults.
+    """
+    cwd_resolved = cwd if cwd is not None else Path.cwd()
+
+    if team_path is not None:
+        team_file = Path(team_path)
+    else:
+        if project_root is not None:
+            root = Path(project_root)
+        else:
+            root = find_project_root(cwd_resolved) or cwd_resolved
+        team_file = root / DEFAULT_TEAM_FILE
+
+    team_raw = _read_yaml(team_file) or {}
+    team_modules = team_raw.get("modules") if isinstance(team_raw.get("modules"), dict) else {}
+    locked_keys_raw = team_raw.get("locked_keys")
+    locked_keys: tuple[str, ...] = tuple(
+        k for k in (locked_keys_raw or []) if isinstance(k, str)
+    )
+
+    dev_merged = load_agent_settings(
+        project_path=project_path,
+        cwd=cwd,
+    )
+    dev_modules = dev_merged.get("modules") if isinstance(dev_merged.get("modules"), dict) else {}
+
+    merged: dict[str, Any] = copy.deepcopy(MODULES_DEFAULTS)
+    if team_modules:
+        _deep_merge(merged, team_modules)
+
+    if dev_modules:
+        for key, value in dev_modules.items():
+            dotted = f"modules.{key}"
+            if dotted in locked_keys and key in (team_modules or {}):
+                logger.info(
+                    "agent_settings: ignoring developer override of locked key %s",
+                    dotted,
+                )
+                continue
+            if isinstance(value, dict) and isinstance(merged.get(key), dict):
+                _deep_merge(merged[key], value)
+            else:
+                merged[key] = value
+
+    return merged
+
+
+def enumerate_modules(
+    project_root: Path | str | None = None,
+    cwd: Path | None = None,
+    modules_config: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """Enumerate every module under ``modules.root_paths``.
+
+    Phase D Step 1 of road-to-configurable-modules. For each path in
+    ``modules.root_paths`` (resolved relative to ``project_root``), lists
+    immediate subdirectories that survive the ``modules.skip_dirs`` filter
+    and reports whether each module ships a per-module agent folder
+    (``modules.agent_folder``, default ``agents``).
+
+    Returns a list of dicts \u2014 one per discovered module \u2014 sorted by
+    ``(root_path, name)`` for deterministic output:
+
+    * ``name``               \u2014 directory name of the module
+    * ``root_path``          \u2014 repo-relative root containing the module
+    * ``module_path``        \u2014 repo-relative path to the module itself
+    * ``has_agent_folder``   \u2014 ``True`` iff a directory matching
+      ``modules.agent_folder`` lives directly under the module
+    * ``agent_folder_path``  \u2014 repo-relative path to that folder
+      (``None`` when ``has_agent_folder`` is ``False``)
+
+    Contract:
+
+    * ``modules.enabled`` is **not** consulted \u2014 callers decide whether
+      to skip the call. Disabled projects normally yield ``[]`` because
+      ``root_paths`` is empty by default.
+    * Missing roots are skipped silently (logged at INFO).
+    * Hidden directories (leading ``.``) and entries in
+      ``modules.skip_dirs`` are filtered out.
+    * Symlinks are followed only when they resolve inside the project
+      root \u2014 same boundary as ``find_project_root``.
+    * Pure, read-only \u2014 no file or directory is ever written.
+
+    ``modules_config`` lets tests inject a pre-built dict; when ``None``
+    the function calls :func:`get_modules_config` with the same
+    ``project_root`` / ``cwd`` so the precedence chain matches.
+    """
+    cwd_resolved = cwd if cwd is not None else Path.cwd()
+    if project_root is not None:
+        root = Path(project_root)
+    else:
+        root = find_project_root(cwd_resolved) or cwd_resolved
+    root = root.resolve()
+
+    if modules_config is None:
+        modules_config = get_modules_config(project_root=root, cwd=cwd)
+
+    root_paths_raw = modules_config.get("root_paths") or []
+    skip_dirs_raw = modules_config.get("skip_dirs") or MODULES_DEFAULTS["skip_dirs"]
+    agent_folder = str(modules_config.get("agent_folder") or MODULES_DEFAULTS["agent_folder"])
+
+    skip_dirs: set[str] = {str(s) for s in skip_dirs_raw if isinstance(s, str)}
+
+    discovered: list[dict[str, Any]] = []
+    for raw in root_paths_raw:
+        if not isinstance(raw, str) or not raw.strip():
+            continue
+        root_rel = raw.strip().strip("/")
+        root_abs = (root / root_rel).resolve()
+        try:
+            if not root_abs.is_dir() or not str(root_abs).startswith(str(root)):
+                logger.info("enumerate_modules: skipping missing/out-of-tree root %s", root_rel)
+                continue
+        except OSError:
+            logger.info("enumerate_modules: unreadable root %s", root_rel)
+            continue
+
+        try:
+            children = sorted(root_abs.iterdir(), key=lambda p: p.name)
+        except OSError:
+            logger.info("enumerate_modules: cannot list %s", root_rel)
+            continue
+
+        for child in children:
+            name = child.name
+            if name.startswith(".") or name in skip_dirs:
+                continue
+            if not child.is_dir():
+                continue
+            agent_dir = child / agent_folder
+            has_agent = agent_dir.is_dir()
+            try:
+                module_rel = child.resolve().relative_to(root)
+            except ValueError:
+                continue
+            entry: dict[str, Any] = {
+                "name": name,
+                "root_path": root_rel,
+                "module_path": str(module_rel),
+                "has_agent_folder": has_agent,
+                "agent_folder_path": str(module_rel / agent_folder) if has_agent else None,
+            }
+            discovered.append(entry)
+
+    discovered.sort(key=lambda m: (m["root_path"], m["name"]))
+    return discovered
+
+
 def iter_setting_overrides(
     project_path: Path | str | None = None,
     user_global_path: Path | str | None = None,

package/scripts/_lib/agent_src.py

@@ -1,17 +1,17 @@
 """Locate artefact source roots across the monorepo physical layout.
 
 Phase 4 of the monorepo migration (ADR-017) physically moves source
-artefacts out of the flat ``.agent-src.uncompressed/`` directory into
-``packages/core/.agent-src.uncompressed/`` and
-``packages/pack-*/.agent-src.uncompressed/`` trees. This helper hides
+artefacts out of the flat ``.agent-src.uncondensed/`` directory into
+``packages/core/.agent-src.uncondensed/`` and
+``packages/pack-*/.agent-src.uncondensed/`` trees. This helper hides
 that decision from every scanner so they keep working pre-move and
 post-move with the same call shape.
 
 Contract:
 
 - ``artefact_roots()`` returns every directory that contains source
-  ``.md`` artefacts. Pre-move that is ``.agent-src.uncompressed/`` at
-  the repo root. Post-move it is every ``packages/*/.agent-src.uncompressed/``.
+  ``.md`` artefacts. Pre-move that is ``.agent-src.uncondensed/`` at
+  the repo root. Post-move it is every ``packages/*/.agent-src.uncondensed/``.
   Both can coexist during the migration window.
 - ``iter_artefacts()`` yields every source ``.md`` path under those roots.
 - ``logical_relpath(p)`` returns the artefact's stable identity path
@@ -19,7 +19,7 @@ Contract:
   root contains it. This is what manifests, hash maps, and projections
   use as the artefact key.
 - ``strip_source_prefix(p)`` returns the same as ``logical_relpath``
-  but accepts repo-relative POSIX strings (used by the compressor's
+  but accepts repo-relative POSIX strings (used by the condenseor's
   output-path computation and the LEGACY_SRC_PREFIX logic).
 """
 from __future__ import annotations
@@ -28,22 +28,22 @@ from pathlib import Path
 from typing import Iterator
 
 ROOT = Path(__file__).resolve().parents[2]
-LEGACY_SRC = ROOT / ".agent-src.uncompressed"
+LEGACY_SRC = ROOT / ".agent-src.uncondensed"
 PACKAGES = ROOT / "packages"
 
 # Repo-relative POSIX path prefixes that anchor an artefact source tree.
 # Order: legacy first (kept until the move lands), then packages/*. Each
 # entry is the prefix that gets stripped to obtain the logical path.
-_LEGACY_PREFIX = ".agent-src.uncompressed/"
-_PACKAGE_SUFFIX = "/.agent-src.uncompressed/"
+_LEGACY_PREFIX = ".agent-src.uncondensed/"
+_PACKAGE_SUFFIX = "/.agent-src.uncondensed/"
 
 
 def artefact_roots() -> list[Path]:
     """Every existing directory that contains source ``.md`` artefacts.
 
-    Returns at most one ``.agent-src.uncompressed/`` root (legacy) plus
+    Returns at most one ``.agent-src.uncondensed/`` root (legacy) plus
     one root per ``packages/*/`` subdirectory that exposes its own
-    ``.agent-src.uncompressed/`` tree. Order is stable: legacy first,
+    ``.agent-src.uncondensed/`` tree. Order is stable: legacy first,
     then ``packages/`` entries sorted alphabetically.
     """
     roots: list[Path] = []
@@ -51,7 +51,7 @@ def artefact_roots() -> list[Path]:
         roots.append(LEGACY_SRC)
     if PACKAGES.exists():
         for pkg in sorted(PACKAGES.iterdir()):
-            sub = pkg / ".agent-src.uncompressed"
+            sub = pkg / ".agent-src.uncondensed"
             if sub.is_dir():
                 roots.append(sub)
     return roots
@@ -111,11 +111,11 @@ def logical_relpath(path: Path) -> str:
     """Return the artefact's logical identity path (POSIX, no prefix).
 
     Examples:
-        ``.agent-src.uncompressed/skills/laravel/SKILL.md``
+        ``.agent-src.uncondensed/skills/laravel/SKILL.md``
             → ``skills/laravel/SKILL.md``
-        ``packages/pack-laravel/.agent-src.uncompressed/skills/laravel/SKILL.md``
+        ``packages/pack-laravel/.agent-src.uncondensed/skills/laravel/SKILL.md``
             → ``skills/laravel/SKILL.md``
-        ``packages/core/.agent-src.uncompressed/rules/scope-control.md``
+        ``packages/core/.agent-src.uncondensed/rules/scope-control.md``
             → ``rules/scope-control.md``
 
     Raises ``ValueError`` if ``path`` is not under any known source root.
@@ -130,15 +130,15 @@ def logical_relpath(path: Path) -> str:
 
 
 def strip_source_prefix(rel: str) -> str | None:
-    """Strip the ``.agent-src.uncompressed/`` anchor from a repo-relative path.
+    """Strip the ``.agent-src.uncondensed/`` anchor from a repo-relative path.
 
     Accepts both the legacy flat layout and the monorepo packages layout.
     Returns ``None`` if the path is not under any source root.
 
     Examples:
-        ``".agent-src.uncompressed/rules/foo.md"`` → ``"rules/foo.md"``
-        ``"packages/core/.agent-src.uncompressed/rules/foo.md"`` → ``"rules/foo.md"``
-        ``"packages/pack-laravel/.agent-src.uncompressed/skills/x/SKILL.md"``
+        ``".agent-src.uncondensed/rules/foo.md"`` → ``"rules/foo.md"``
+        ``"packages/core/.agent-src.uncondensed/rules/foo.md"`` → ``"rules/foo.md"``
+        ``"packages/pack-laravel/.agent-src.uncondensed/skills/x/SKILL.md"``
             → ``"skills/x/SKILL.md"``
         ``"docs/architecture.md"`` → ``None``
     """

package/scripts/_lib/bench_ab_cache.py

@@ -0,0 +1,162 @@
+"""Baseline-cache helpers for the package-impact A/B bench.
+
+Phase 2 Step 2 of `agents/roadmaps/road-to-package-impact-benchmark.md`.
+
+A daily `task bench:ab` run wants to skip re-running the `without` arm when
+nothing the model would see has changed. We define "changed" by a three-part
+key:
+
+    (corpus_hash, claude_cli_version, target_shape_hash)
+
+Cached `without` reports live under `internal/bench/reports/ab/`. Each report
+header records the cache key inputs; this module reads the directory, picks
+the latest matching report, and reports freshness.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports" / "ab"
+
+
+@dataclass(frozen=True)
+class CacheKey:
+    corpus_hash: str
+    claude_cli_version: str
+    target_shape_hash: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "corpus_hash": self.corpus_hash,
+            "claude_cli_version": self.claude_cli_version,
+            "target_shape_hash": self.target_shape_hash,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> "CacheKey":
+        return cls(
+            corpus_hash=data.get("corpus_hash", ""),
+            claude_cli_version=data.get("claude_cli_version", ""),
+            target_shape_hash=data.get("target_shape_hash", ""),
+        )
+
+
+@dataclass(frozen=True)
+class CacheLookup:
+    found: bool
+    fresh: bool
+    report_path: Path | None
+    cached_key: CacheKey | None
+    reason: str  # human-readable: "missing", "fresh", "stale: corpus", etc.
+
+
+def hash_file(path: Path) -> str:
+    """SHA-256 of a single file (used for corpus_hash)."""
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()[:16]
+
+
+def claude_cli_version() -> str:
+    """Best-effort: `claude --version` or fallback to the env CLAUDE_CLI_VERSION.
+
+    When the CLI is missing, return "unavailable:<reason>" so the cache key
+    still varies meaningfully when the CLI is later installed.
+    """
+    override = os.environ.get("CLAUDE_CLI_VERSION")
+    if override:
+        return override.strip()
+    if shutil.which("claude") is None:
+        return "unavailable:not-on-path"
+    try:
+        out = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as err:
+        return f"unavailable:{type(err).__name__}"
+    if out.returncode != 0:
+        return f"unavailable:exit-{out.returncode}"
+    return (out.stdout or out.stderr).strip().splitlines()[0] if out.stdout or out.stderr else "unknown"
+
+
+def target_shape_hash() -> str:
+    """Re-export the shape hash from the clone script for a single source of truth."""
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(
+        "bench_ab_clone", REPO_ROOT / "scripts" / "bench_ab_clone.py"
+    )
+    if spec is None or spec.loader is None:
+        return "unknown"
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.target_shape_hash()  # type: ignore[no-any-return]
+
+
+def build_key(corpus_path: Path) -> CacheKey:
+    return CacheKey(
+        corpus_hash=hash_file(corpus_path),
+        claude_cli_version=claude_cli_version(),
+        target_shape_hash=target_shape_hash(),
+    )
+
+
+def iter_cached_reports(variant: str = "without") -> list[Path]:
+    """Return all report JSON paths under reports/ab/ for the given variant.
+
+    Filenames follow `{stamp}-{corpus}-{variant}.json` (Phase 2 Step 3).
+    """
+    if not REPORTS_DIR.exists():
+        return []
+    matches = sorted(REPORTS_DIR.glob(f"*-{variant}.json"))
+    return list(matches)
+
+
+def read_report_key(report_path: Path) -> CacheKey | None:
+    try:
+        data = json.loads(report_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    raw = data.get("cache_key")
+    if not isinstance(raw, dict):
+        return None
+    return CacheKey.from_dict({k: str(v) for k, v in raw.items()})
+
+
+def lookup(corpus_path: Path) -> CacheLookup:
+    """Find the latest cached `without` report and report freshness vs. the current key."""
+    if not corpus_path.exists():
+        return CacheLookup(False, False, None, None, f"missing corpus: {corpus_path}")
+    current = build_key(corpus_path)
+    candidates = iter_cached_reports("without")
+    if not candidates:
+        return CacheLookup(False, False, None, None, "no cached `without` report")
+    # Reports sorted by filename — last is latest given UTC stamps
+    latest = candidates[-1]
+    cached_key = read_report_key(latest)
+    if cached_key is None:
+        return CacheLookup(True, False, latest, None, "cached report missing cache_key")
+    if cached_key == current:
+        return CacheLookup(True, True, latest, cached_key, "fresh")
+    # Diagnose which input drifted
+    drift_parts = []
+    if cached_key.corpus_hash != current.corpus_hash:
+        drift_parts.append("corpus")
+    if cached_key.claude_cli_version != current.claude_cli_version:
+        drift_parts.append("claude_cli_version")
+    if cached_key.target_shape_hash != current.target_shape_hash:
+        drift_parts.append("target_shape")
+    return CacheLookup(True, False, latest, cached_key, "stale: " + ",".join(drift_parts))