@event4u/agent-config 3.3.0 → 4.1.0

package/scripts/cost_summary.py

@@ -2,8 +2,8 @@
 """Emit `cost-summary/v1` JSON per `docs/contracts/cost-summary-schema.md`.
 
 Reads `agents/cost-tracking/sessions.jsonl` (or `--input`), aggregates by
-session, conversation, and model. Honors the caveman suspended-multiplier
-contract (delta = 0 while suspended; see `caveman-telemetry.md`).
+session, conversation, and model. Honors the telegraph suspended-multiplier
+contract (delta = 0 while suspended; see `telegraph-telemetry.md`).
 """
 from __future__ import annotations
 import argparse, json, sys
@@ -36,12 +36,12 @@ def _load(path: Path) -> list[dict]:
 def _delta(row: dict) -> int:
     if not MULTIPLIER_ACTIVE:
         return 0
-    return int(row.get("caveman_delta_tokens") or 0)
+    return int(row.get("telegraph_delta_tokens") or 0)
 
 
 def _zero_kv() -> dict:
     return {"sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0,
-            "output_tokens": 0, "caveman_delta_tokens": 0}
+            "output_tokens": 0, "telegraph_delta_tokens": 0}
 
 
 def _zero_model() -> dict:
@@ -66,14 +66,14 @@ def aggregate(rows: list[dict]) -> dict:
             bucket["total_cost_usd"] += cost
             bucket["input_tokens"] += itok
             bucket["output_tokens"] += otok
-            bucket["caveman_delta_tokens"] += delta
+            bucket["telegraph_delta_tokens"] += delta
         m = by_model[model]
         m["sessions"] += 1
         m["total_cost_usd"] += cost
         m["input_tokens"] += itok
         m["output_tokens"] += otok
-    totals["caveman_multiplier_version"] = MULTIPLIER_VERSION
-    totals["caveman_multiplier_active"] = MULTIPLIER_ACTIVE
+    totals["telegraph_multiplier_version"] = MULTIPLIER_VERSION
+    totals["telegraph_multiplier_active"] = MULTIPLIER_ACTIVE
     return {
         "schema_version": SCHEMA,
         "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),

package/scripts/count_token_optimizer_usage.sh

@@ -10,7 +10,7 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-SKILL="$REPO_ROOT/.agent-src.uncompressed/skills/token-optimizer/SKILL.md"
+SKILL="$REPO_ROOT/.agent-src.uncondensed/skills/token-optimizer/SKILL.md"
 
 if [[ ! -f "$SKILL" ]]; then
     echo "ERROR: $SKILL not found" >&2

package/scripts/gen_discovery_baseline.py

@@ -9,7 +9,7 @@ import sys
 from collections import Counter
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]
-SRC = ROOT / ".agent-src.uncompressed"
+SRC = ROOT / ".agent-src.uncondensed"
 
 
 def _frontmatter(path: pathlib.Path) -> dict[str, str]:
@@ -56,10 +56,10 @@ def main() -> int:
     out.append("## Counts by category\n")
     out.append("| Category | Path | Count |")
     out.append("|---|---|---|")
-    out.append(f"| Skills | `.agent-src.uncompressed/skills/*/SKILL.md` | {len(skills)} |")
-    out.append(f"| Rules | `.agent-src.uncompressed/rules/**/*.md` | {len(rules)} |")
-    out.append(f"| Commands | `.agent-src.uncompressed/commands/**/*.md` | {len(commands)} |")
-    out.append(f"| Templates | `.agent-src.uncompressed/templates/**/*` | {len(templates)} |")
+    out.append(f"| Skills | `.agent-src.uncondensed/skills/*/SKILL.md` | {len(skills)} |")
+    out.append(f"| Rules | `.agent-src.uncondensed/rules/**/*.md` | {len(rules)} |")
+    out.append(f"| Commands | `.agent-src.uncondensed/commands/**/*.md` | {len(commands)} |")
+    out.append(f"| Templates | `.agent-src.uncondensed/templates/**/*` | {len(templates)} |")
     out.append("")
 
     out.append("## Distinct `domain:` values (skills)\n")

package/scripts/generate_index.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Generate `agents/index.md` (internal) and `docs/catalog.md` (public).
 
-Scans `.agent-src.uncompressed/{skills,rules,commands}/` plus `docs/guidelines/`
+Scans `.agent-src.uncondensed/{skills,rules,commands}/` plus `docs/guidelines/`
 and renders two artefact tables — one for maintainers, one for consumers.
 
 Both files are sync-checked in CI via `--check`; drift = build break.
@@ -22,10 +22,10 @@ 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
+# Legacy single-root anchor — kept as fallback for pure-condensed
 # consumer projections. Multi-root discovery uses artefact_roots() so
 # generate_index works across packages/* per ADR-017.
-SRC = ROOT / ".agent-src.uncompressed"
+SRC = ROOT / ".agent-src.uncondensed"
 GUIDELINES = ROOT / "docs" / "guidelines"
 INDEX_PATH = ROOT / "agents" / "index.md"
 CATALOG_PATH = ROOT / "docs" / "catalog.md"
@@ -161,9 +161,9 @@ 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/`),
+# (`.agent-src/`) instead of the source-of-truth (`.agent-src.uncondensed/`),
 # which is excluded from `package.json#files` and `composer.json` archives.
-# Post-ADR-017 the source-of-truth lives at packages/*/.agent-src.uncompressed/,
+# Post-ADR-017 the source-of-truth lives at packages/*/.agent-src.uncondensed/,
 # so we strip whichever prefix matches and pin to the flat .agent-src/ output.
 def _to_shipped_path(path: str) -> str:
     from _lib.agent_src import strip_source_prefix
@@ -195,7 +195,7 @@ def _render_index(skills, rules, commands, guidelines) -> str:
         "# Agent-Config Internal Index",
         "",
         f"Maintainer-facing index of all **{total} artefacts** in this package.",
-        "Auto-generated from `.agent-src.uncompressed/` and `docs/guidelines/`.",
+        "Auto-generated from `.agent-src.uncondensed/` and `docs/guidelines/`.",
         "",
         "> **Regenerate:** `python3 scripts/generate_index.py`",
         "> **Drift check:** `python3 scripts/generate_index.py --check` (runs in `task ci`)",

package/scripts/generate_ownership_matrix.py

@@ -6,7 +6,7 @@ Produces:
   * docs/contracts/file-ownership-matrix.json (machine, internal-locked)
   * agents/settings/contexts/structural/file-ownership-matrix.md (human-readable)
 
-Walks `.agent-src.uncompressed/{rules,skills,commands,contexts,personas}/`,
+Walks `.agent-src.uncondensed/{rules,skills,commands,contexts,personas}/`,
 parses frontmatter for `load_context:` / `load_context_eager:`, scans
 markdown bodies for inline links to `.md` files inside the scanned roots,
 and emits READ_ONLY edges plus depth-2 transitive closure of load_context
@@ -39,10 +39,10 @@ sys.path.insert(0, str(ROOT / "scripts"))
 from _lib.agent_src import artefact_roots, resolve_logical, strip_source_prefix  # noqa: E402
 
 # Canonical anchor used in the committed matrix. Paths are always
-# emitted as ".agent-src.uncompressed/<sub>/<...>" regardless of which
+# emitted as ".agent-src.uncondensed/<sub>/<...>" regardless of which
 # physical root (legacy or packages/*) contains the file, so the matrix
 # stays stable across the monorepo migration.
-CANONICAL_SRC_PREFIX = ".agent-src.uncompressed"
+CANONICAL_SRC_PREFIX = ".agent-src.uncondensed"
 
 SCAN_DIRS = ("rules", "skills", "commands", "contexts", "personas")
 
@@ -76,7 +76,7 @@ def _rel(p: Path) -> str:
 
 def _kind_for(rel: str) -> str:
     parts = rel.split("/")
-    if len(parts) >= 3 and parts[0] == ".agent-src.uncompressed":
+    if len(parts) >= 3 and parts[0] == ".agent-src.uncondensed":
         return parts[1].rstrip("s") if parts[1] != "personas" else "persona"
     return "unknown"
 
@@ -98,7 +98,7 @@ def _parse_frontmatter(p: Path) -> dict:
 def _collect_files(root: Path | None = None) -> list[tuple[Path, str]]:
     """Walk every artefact root and yield ``(physical_path, canonical_rel)``.
 
-    ``canonical_rel`` is always anchored at ``.agent-src.uncompressed/`` so
+    ``canonical_rel`` is always anchored at ``.agent-src.uncondensed/`` so
     the matrix is byte-identical pre- and post-monorepo-move. Duplicates
     across roots resolve to the first hit (legacy first, then packages
     alphabetically) — matches the priority in ``artefact_roots()``.
@@ -212,17 +212,17 @@ def build_matrix(root: Path | None = None) -> tuple[dict[str, FileEntry], list[E
 def _resolve_link(source_rel: str, source_phys: Path, href: str) -> str | None:
     """Resolve a markdown link href to a canonical scanned-root path, or None.
 
-    ``source_rel`` is the canonical (``.agent-src.uncompressed/...``)
+    ``source_rel`` is the canonical (``.agent-src.uncondensed/...``)
     identity of the source file. Relative hrefs are resolved against
     the source's *logical* directory, then looked up across every
     artefact root via :func:`resolve_logical`. This keeps the matrix
     stable when source and target live in different physical packages.
 
     Repo-rooted hrefs (``agents/...``, ``packages/...``, or those
-    starting with ``.agent-src.uncompressed/``) are resolved against
+    starting with ``.agent-src.uncondensed/``) are resolved against
     the repo root and normalised through :func:`strip_source_prefix`.
     """
-    if href.startswith(".agent-src.uncompressed/") or href.startswith("agents/") \
+    if href.startswith(".agent-src.uncondensed/") or href.startswith("agents/") \
             or href.startswith("packages/"):
         cand = (ROOT / href).resolve()
         if not cand.exists():
@@ -267,7 +267,7 @@ def _to_json(files: dict[str, FileEntry], edges: list[Edge]) -> dict:
     return {
         "version": 1,
         "generated_by": "scripts/generate_ownership_matrix.py",
-        "source_of_truth": ".agent-src.uncompressed/",
+        "source_of_truth": ".agent-src.uncondensed/",
         "files": {
             rel: {
                 "kind": e.kind,
@@ -342,7 +342,7 @@ def main(argv: Iterable[str] | None = None) -> int:
     args = ap.parse_args(list(argv) if argv is not None else None)
 
     if not artefact_roots():
-        print("❌  no artefact roots found (legacy or packages/*/.agent-src.uncompressed/)",
+        print("❌  no artefact roots found (legacy or packages/*/.agent-src.uncondensed/)",
               file=sys.stderr)
         return 3
 

package/scripts/generate_pack_manifests.py

@@ -70,7 +70,7 @@ def _package_version() -> str:
 
 
 def _collect_artefacts(pkg_dir: Path) -> list[dict[str, Any]]:
-    src_root = pkg_dir / ".agent-src.uncompressed"
+    src_root = pkg_dir / ".agent-src.uncondensed"
     if not src_root.is_dir():
         return []
     items: list[dict[str, Any]] = []

package/scripts/ghostwriter_fixture_allowlist.txt

@@ -1,7 +1,7 @@
 # Ghostwriter fixture allowlist
 #
 # One file stem per line (without the .md extension).
-# Every file under .agent-src.uncompressed/ghostwriter/ whose stem is
+# Every file under .agent-src.uncondensed/ghostwriter/ whose stem is
 # NOT on this list will fail `task lint-ghostwriter-source`.
 #
 # Adding a new fixture requires:

package/scripts/install

@@ -274,8 +274,8 @@ fi
 # AGENT_CONFIG_ALLOW_SELF_INSTALL=1.
 if ! $GLOBAL && [[ "${AGENT_CONFIG_ALLOW_SELF_INSTALL:-0}" != "1" ]]; then
     self_marker=""
-    if [[ -d "$TARGET_DIR/.agent-src.uncompressed" ]]; then
-        self_marker=".agent-src.uncompressed/"
+    if [[ -d "$TARGET_DIR/.agent-src.uncondensed" ]]; then
+        self_marker=".agent-src.uncondensed/"
     elif [[ -f "$TARGET_DIR/package.json" ]] && \
          grep -qE '"name"[[:space:]]*:[[:space:]]*"@event4u/agent-config"' "$TARGET_DIR/package.json" 2>/dev/null; then
         self_marker='package.json::name === "@event4u/agent-config"'
@@ -285,7 +285,7 @@ if ! $GLOBAL && [[ "${AGENT_CONFIG_ALLOW_SELF_INSTALL:-0}" != "1" ]]; then
         echo "      Target:   $TARGET_DIR" >&2
         echo "      Detected: $self_marker" >&2
         echo "      Run \`task sync\` to regenerate .agent-src/ + .augment/ from" >&2
-        echo "      .agent-src.uncompressed/ instead. To force this anyway, set" >&2
+        echo "      .agent-src.uncondensed/ instead. To force this anyway, set" >&2
         echo "      AGENT_CONFIG_ALLOW_SELF_INSTALL=1." >&2
         exit 2
     fi

package/scripts/install-hooks.sh

@@ -12,7 +12,7 @@ mkdir -p "$HOOKS_DIR"
 
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
-# Pre-push hook: verify .agent-src/ is in sync with .agent-src.uncompressed/
+# Pre-push hook: verify .agent-src/ is in sync with .agent-src.uncondensed/
 # and that the canonical command count matches README + getting-started docs.
 #
 # The command-count gate exists because three consecutive PRs landed
@@ -23,8 +23,8 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 fail=0
 
 echo "🔍 Checking .agent-src/ sync..."
-if ! python3 scripts/compress.py --check; then
-    echo "❌  .agent-src/ is out of sync. Run 'task sync' and compress changed .md files, then commit."
+if ! python3 scripts/condense.py --check; then
+    echo "❌  .agent-src/ is out of sync. Run 'task sync' and condense changed .md files, then commit."
     fail=1
 fi
 
@@ -134,8 +134,8 @@ write_chat_history_hook "post-rewrite"  "git:post-rewrite"
 
 # Auto-sync agent-tool projections after pull / branch-switch ---------------
 #
-# When `.agent-src.uncompressed/`, `.agent-src/`, `scripts/compress.py`,
-# `.agent-tools.yml`, or `Taskfile.yml` change between the previous and
+# When `.agent-src.uncondensed/`, `.agent-src/`, `scripts/condense.py`,
+# `agents/.agent-tools.yml`, or `Taskfile.yml` change between the previous and
 # new HEAD, the developer's working tree has stale `.claude/`,
 # `.augment/`, etc. projections until they remember to run `task sync`.
 # These hooks bridge that gap: fast idempotent re-projection.
@@ -169,7 +169,7 @@ fi
 
 if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
     if git diff --name-only "\$prev" "\$new" 2>/dev/null | \\
-        grep -qE '^(\\.agent-src(\\.uncompressed)?/|scripts/compress\\.py|\\.agent-tools\\.yml|Taskfile\\.yml)'; then
+        grep -qE '^(\\.agent-src(\\.uncondensed)?/|scripts/condense\\.py|\\.agent-tools\\.yml|Taskfile\\.yml)'; then
         if command -v task >/dev/null 2>&1; then
             task sync >/dev/null 2>&1 || true
             task generate-tools >/dev/null 2>&1 || true

package/scripts/install.py

@@ -2921,12 +2921,12 @@ def _detect_legacy_for_migration(project_root: Path) -> list[str]:
 
     - ``AGENT_CONFIG_DEV_MODE=1`` is set (maintainer dogfood loop),
     - the project root IS the agent-config source repo
-      (``.agent-src.uncompressed/`` present),
+      (``.agent-src.uncondensed/`` present),
     - the bridge marker already exists (project is already global-only).
     """
     if os.environ.get("AGENT_CONFIG_DEV_MODE") == "1":
         return []
-    if (project_root / ".agent-src.uncompressed").is_dir():
+    if (project_root / ".agent-src.uncondensed").is_dir():
         return []
     if (project_root / CONSUMER_BRIDGE_MARKER_RELPATH).is_file():
         return []
@@ -3031,7 +3031,7 @@ def _write_consumer_bridge_marker(
     - ``AGENT_CONFIG_DEV_MODE=1`` (maintainer dev installs never lay the
       bridge into the source repo).
     - The project root is the agent-config source repo itself
-      (``.agent-src.uncompressed/`` present) — same rationale.
+      (``.agent-src.uncondensed/`` present) — same rationale.
 
     Atomic write: ``tempfile`` in the same dir + ``os.replace``. Same
     pattern the lockfile uses (see ``scripts/_lib/installed_lock.py``).
@@ -3042,7 +3042,7 @@ def _write_consumer_bridge_marker(
     env_map = env if env is not None else os.environ
     if env_map.get("AGENT_CONFIG_DEV_MODE") == "1":
         return None
-    if (project_root / ".agent-src.uncompressed").is_dir():
+    if (project_root / ".agent-src.uncondensed").is_dir():
         return None
 
     paths_mod = _load_user_global_paths_module()
@@ -3112,7 +3112,7 @@ def _write_per_tool_project_anchors(
 
     - Skipped under ``AGENT_CONFIG_DEV_MODE=1``.
     - Skipped inside the agent-config source repo
-      (``.agent-src.uncompressed/`` present).
+      (``.agent-src.uncondensed/`` present).
     - Skipped when the tool is not in ``tools``.
 
     Atomic write per file (temp file + ``os.replace``); ``0o644``
@@ -3124,7 +3124,7 @@ def _write_per_tool_project_anchors(
     env_map = env if env is not None else os.environ
     if env_map.get("AGENT_CONFIG_DEV_MODE") == "1":
         return []
-    if (project_root / ".agent-src.uncompressed").is_dir():
+    if (project_root / ".agent-src.uncondensed").is_dir():
         return []
 
     paths_mod = _load_user_global_paths_module()
@@ -3548,12 +3548,12 @@ def install_global(
     # (ADR-008 Phase 3.2). Outside a project (e.g. plain `~/`) there is no
     # manifest to write and the global lockfile alone is the source of truth.
     # Skipped inside the agent-config source repo (detected by
-    # `.agent-src.uncompressed/`) — maintainers dogfood with their own
+    # `.agent-src.uncondensed/`) — maintainers dogfood with their own
     # `.agent-settings.yml` and the manifest would be untracked noise.
     if (
         project_root is not None
         and (project_root / SETTINGS_FILE).exists()
-        and not (project_root / ".agent-src.uncompressed").is_dir()
+        and not (project_root / ".agent-src.uncondensed").is_dir()
     ):
         # Collect deployed/marker paths per tool so the manifest records
         # the v2 ``files[]`` inventory (P1.4).
@@ -3571,7 +3571,7 @@ def install_global(
         # ``agents/.event4u-bridge.yml`` lets per-tool adapters locate
         # the global root from inside the repo. Skipped in maintainer
         # dev mode and in the source repo (see contract § Writer
-        # contract; the surrounding ``.agent-src.uncompressed`` guard
+        # contract; the surrounding ``.agent-src.uncondensed`` guard
         # already covers the source-repo case, the dev-mode skip is
         # enforced inside the writer).
         marker_path = _write_consumer_bridge_marker(project_root, installed_version)
@@ -3794,7 +3794,7 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
         dest="apply_payload",
         default=None,
         help=(
-            "path to a WizardApplyPayload JSON file (schemas/"
+            "path to a WizardApplyPayload JSON file (internal/schemas/"
             "wizard-apply-payload.schema.json). When supplied, install.py "
             "reads the payload, validates schema_version, translates "
             "tools/packs/settings into CLI equivalents, and dispatches "
@@ -4072,7 +4072,7 @@ _INTERACTIVE_STACKS: tuple[tuple[str, str], ...] = (
 )
 
 _INTERACTIVE_VERBOSITIES: tuple[tuple[str, str], ...] = (
-    ("quiet", "Caveman / minimal output"),
+    ("quiet", "Telegraph / minimal output"),
     ("normal", "Default verbosity"),
     ("verbose", "Full intent announcements + play-by-play"),
 )
@@ -4579,6 +4579,65 @@ def main(argv: list[str]) -> int:
         _set_conflict_policy(None)
 
 
+def _propose_modules_config(project_root: Path, is_first_run: bool) -> None:
+    """Surface module-root candidates as numbered options on first install.
+
+    Phase B Step 2 of road-to-configurable-modules. Hooks into the
+    project-install path: when the install is first-run, the terminal
+    is a TTY, ``.agent-project-settings.yml`` exists without a populated
+    ``modules:`` block, and the detection helper finds at least one
+    candidate, the installer prints the proposed block and asks the
+    user to paste it into the team file. No automatic write — the
+    layered-settings contract treats ``.agent-project-settings.yml``
+    as user-curated.
+
+    Gates (any miss → silent no-op):
+
+    * ``is_first_run`` must be True — re-runs never re-prompt.
+    * stdin + stdout must be TTYs — non-interactive installs (CI,
+      wizard apply-payload, ``--quiet``) skip silently.
+    * ``QUIET`` must be False.
+    * The detection helper must surface at least one candidate.
+    """
+    if not is_first_run or QUIET or not sys.stdin.isatty() or not sys.stdout.isatty():
+        return
+    try:
+        from scripts._lib.module_detection import detect_module_roots
+    except ImportError:
+        return
+    try:
+        candidates = detect_module_roots(project_root)
+    except OSError:
+        return
+    if not candidates:
+        return
+    print()
+    info("Module-root candidates detected — propose `modules:` block")
+    info(
+        "Paste into .agent-project-settings.yml to enable module-aware "
+        "skills (or skip; the block stays opt-in)."
+    )
+    print()
+    print("  modules:")
+    print("    enabled: true")
+    print(
+        "    root_paths: [" + ", ".join(c.path for c in candidates) + "]"
+    )
+    primary_ns = next(
+        (c.namespace_template_guess for c in candidates if c.namespace_template_guess),
+        "",
+    )
+    if primary_ns:
+        print(f"    namespace_template: '{primary_ns}'")
+    print("    agent_folder: agents")
+    print("    skip_dirs: [.module-template, .example]")
+    print()
+    info(
+        "Re-run anytime via `python3 scripts/propose_modules_config.py` "
+        "(installed under <package>/scripts/)."
+    )
+
+
 def _main_project_install(
     opts: argparse.Namespace,
     project_root: Path,
@@ -4728,6 +4787,12 @@ def _main_project_install(
             print("  Re-run complete. Walkthrough: https://github.com/event4u-app/agent-config/blob/main/docs/getting-started.md")
             print()
 
+    # Module-root proposal (road-to-configurable-modules Phase B Step 2).
+    # First-run TTY installs surface detected `modules:` candidates so
+    # the user can paste an opt-in block into .agent-project-settings.yml.
+    # Silent no-op on re-runs, CI, --quiet, and wizard apply-payload runs.
+    _propose_modules_config(project_root, is_first_run)
+
     # Wizard auto-launch (Phase 6 follow-up). Runs after the success
     # banner so the user sees install completion even if the wizard
     # boot times out. Gate was already evaluated at the top of main()