@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/lint_readme_size.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""CI guard for README.md line budget.
+
+The role-first-onboarding roadmap (Phase 2 Step 6) freezes README at
+its current length: replace, do not grow. Every line added above the
+fold must displace an existing line. Budget: 750 lines max.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+README = Path("README.md")
+LIMIT = 750
+
+
+def main() -> int:
+    quiet = "--quiet" in sys.argv
+    if not README.exists():
+        print(f"error: {README} not found", file=sys.stderr)
+        return 1
+    n = sum(1 for _ in README.read_text(encoding="utf-8").splitlines())
+    if n > LIMIT:
+        print(f"FAIL  {README}: {n} lines (limit {LIMIT}). Trim before merge.")
+        return 1
+    if not quiet:
+        print(f"OK    {README}: {n} lines (limit {LIMIT}).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_rule_interactions.py

@@ -25,8 +25,27 @@ import yaml
 QUIET = "--quiet" in sys.argv
 
 ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import resolve_logical, strip_source_prefix  # noqa: E402
+
 MATRIX = ROOT / "docs" / "contracts" / "rule-interactions.yml"
-RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
+
+
+def _rule_exists(slug: str) -> bool:
+    return resolve_logical(f"rules/{slug}.md") is not None
+
+
+def _evidence_exists(file_part: str) -> bool:
+    """Return True if the evidence path resolves under any source root.
+
+    Accepts legacy ``.agent-src.uncompressed/...`` citations and resolves
+    them through the multi-root layout; falls back to a literal repo
+    path check for non-source citations (docs/, agents/, ...).
+    """
+    logical = strip_source_prefix(file_part)
+    if logical is not None:
+        return resolve_logical(logical) is not None
+    return (ROOT / file_part).exists()
 
 ALLOWED_RELATIONS = {
     "overrides",
@@ -77,9 +96,8 @@ def main() -> int:
         if not isinstance(slug, str):
             errors.append(f"rule slug not a string: {slug!r}")
             continue
-        rule_path = RULES_DIR / f"{slug}.md"
-        if not rule_path.exists():
-            errors.append(f"rule slug `{slug}` has no file at {rule_path.relative_to(ROOT)}")
+        if not _rule_exists(slug):
+            errors.append(f"rule slug `{slug}` has no file under any source root (rules/{slug}.md)")
 
     pairs = data.get("pairs") or []
     if not isinstance(pairs, list) or not pairs:
@@ -124,7 +142,7 @@ def main() -> int:
                 errors.append(f"pair `{pid}` evidence item not a string: {citation!r}")
                 continue
             file_part = citation.split("#", 1)[0]
-            if not (ROOT / file_part).exists():
+            if not _evidence_exists(file_part):
                 errors.append(f"pair `{pid}` evidence path does not exist: {file_part}")
 
         # Anchor coverage check

package/scripts/lint_rule_tiers.py

@@ -3,8 +3,8 @@
 
 Hard-fails CI if any rule under .agent-src.uncompressed/rules/ lacks a
 `tier:` declaration or uses an unknown tier value. The valid tier set is
-locked by agents/contexts/hardening-pattern.md and the matrix in
-agents/contexts/rule-trigger-matrix.md.
+locked by agents/settings/contexts/hardening-pattern.md and the matrix in
+agents/settings/contexts/rule-trigger-matrix.md.
 
 Hooked into `task ci` after `task lint-skills`.
 
@@ -20,7 +20,12 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-RULES_DIR = REPO / ".agent-src.uncompressed" / "rules"
+
+# Rules live under every artefact root post-monorepo Phase 4.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+RULES_DIRS = [root / "rules" for root in artefact_roots() if (root / "rules").is_dir()]
 
 VALID_TIERS = frozenset({"1", "2a", "2b", "3", "safety-floor", "mechanical-already"})
 
@@ -41,9 +46,13 @@ def parse_tier(text: str) -> str | None:
 
 
 def main() -> int:
-    rules = sorted(RULES_DIR.glob("*.md"))
+    rules: list[Path] = []
+    for rules_dir in RULES_DIRS:
+        rules.extend(rules_dir.glob("*.md"))
+    rules.sort()
     if not rules:
-        print(f"lint_rule_tiers: no rules found under {RULES_DIR}", file=sys.stderr)
+        roots_label = ", ".join(str(d) for d in RULES_DIRS) or "<no rules root>"
+        print(f"lint_rule_tiers: no rules found under {roots_label}", file=sys.stderr)
         return 1
 
     missing: list[str] = []

package/scripts/lint_skill_tools.py

@@ -2,7 +2,7 @@
 """Block D · D1 — meta-linter for ``scripts/skill_tools/*.py``.
 
 Enforces the four pilot-tool invariants locked by the Block D council
-verdict (`agents/council-responses/block-d-python-tools-pilot-verdict.md`):
+verdict (`agents/runtime/council/responses/block-d-python-tools-pilot-verdict.md`):
 
   1. **stdlib-only** — no third-party imports. Internal package imports
      (``scripts.*``) are allowed.

package/scripts/lint_topics_yaml.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Linter for `.github/topics.yml`.
+
+Asserts:
+  * file exists and parses as YAML
+  * `topics:` is a non-empty list
+  * every topic matches `^[a-z0-9][a-z0-9-]*$` and is \u2264 50 chars
+  * no duplicates
+  * `notes:` key exists (may be empty mapping/string), so the
+    rationale slot is never silently dropped
+  * `equivalents:` (if present) is a mapping whose keys are all
+    listed in `topics:`
+
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 1.3.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+TOPICS_FILE = ROOT / ".github" / "topics.yml"
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+QUIET = "--quiet" in sys.argv
+
+
+def _fail(msg: str) -> None:
+    print(f"\u274c  topics.yml: {msg}", file=sys.stderr)
+
+
+def main() -> int:
+    if not TOPICS_FILE.exists():
+        _fail(f"missing file: {TOPICS_FILE.relative_to(ROOT)}")
+        return 1
+    try:
+        doc = yaml.safe_load(TOPICS_FILE.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        _fail(f"YAML parse error: {e}")
+        return 1
+
+    errors: list[str] = []
+
+    topics = doc.get("topics")
+    if not isinstance(topics, list) or not topics:
+        errors.append("`topics:` must be a non-empty list")
+        topics = []
+
+    seen: set[str] = set()
+    for t in topics:
+        if not isinstance(t, str):
+            errors.append(f"non-string topic entry: {t!r}")
+            continue
+        if len(t) > 50:
+            errors.append(f"topic too long (>50 chars): {t!r}")
+        if not SLUG_RE.match(t):
+            errors.append(f"invalid slug (expect ^[a-z0-9][a-z0-9-]*$): {t!r}")
+        if t in seen:
+            errors.append(f"duplicate topic: {t!r}")
+        seen.add(t)
+
+    if "notes" not in doc:
+        errors.append("`notes:` key missing (may be empty, but must be present)")
+
+    equivalents = doc.get("equivalents")
+    if equivalents is not None:
+        if not isinstance(equivalents, dict):
+            errors.append("`equivalents:` must be a mapping")
+        else:
+            for key, val in equivalents.items():
+                if key not in seen:
+                    errors.append(f"`equivalents:` key {key!r} not in `topics:`")
+                if not isinstance(val, list) or not all(isinstance(v, str) for v in val):
+                    errors.append(f"`equivalents.{key}` must be a list of strings")
+
+    if errors:
+        for e in errors:
+            _fail(e)
+        return 1
+
+    if not QUIET:
+        print(f"\u2705  topics.yml: {len(topics)} topic(s), all valid")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/lint_trust_coherence.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Lint trust/safety coherence across the discovery manifest.
+
+Phase 5.4 of the monorepo trust-and-safety layer. Walks the freshly
+built `dist/discovery/discovery-manifest.json` and asserts three
+invariants:
+
+  1. Every pack whose ``trust_summary`` declares ``advisory`` or
+     ``restricted`` artefacts ships at least one ``*safety-floor*``
+     rule in the same pack.
+  2. Every artefact with ``trust.human_review_required: true`` carries
+     the ``_HRR_BANNER_MARKER`` in its compiled output under
+     ``.agent-src/<logical>``.
+  3. Every rule listed in ``router.json`` ``kernel[]`` declares
+     ``trust.level: core`` (no escalation to advisory/restricted,
+     no demotion to experimental).
+
+Exits 0 clean, 1 on any violation. Stdlib + pyyaml. Cap: ≤ 200 LOC.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+ROUTER = ROOT / "dist" / "router.json"
+COMPILED_SRC = ROOT / ".agent-src"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import strip_source_prefix  # noqa: E402
+
+# Imported lazily inside _banner_marker() to keep the cap loose if compress.py
+# grows additional top-level side effects.
+_BANNER_MARKER = "<!-- agent-config:human-review-banner -->"
+
+# Trust levels that demand a domain-safety floor in the same pack.
+_FLAGGED_LEVELS = ("advisory", "restricted")
+_SAFETY_FLOOR_FRAGMENT = "safety-floor"
+
+
+def _load_manifest(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise SystemExit(
+            f"ERROR: manifest not found: {path}\n"
+            "  Run `task build-discovery` first."
+        )
+    return json.loads(path.read_text("utf-8"))
+
+
+def _load_kernel(path: Path) -> set[str]:
+    if not path.exists():
+        raise SystemExit(f"ERROR: router.json not found: {path}")
+    data = json.loads(path.read_text("utf-8"))
+    kernel = data.get("kernel") or []
+    if not isinstance(kernel, list):
+        raise SystemExit("ERROR: router.json `kernel` must be a list")
+    return {str(name) for name in kernel}
+
+
+def _check_pack_safety_floors(manifest: dict[str, Any]) -> list[str]:
+    """Check 1: advisory/restricted packs ship a *safety-floor* rule."""
+    errs: list[str] = []
+    # Build pack -> [artefact path] index from the artefact list so we can
+    # spot the safety-floor regardless of how trust_summary was computed.
+    pack_paths: dict[str, list[str]] = {}
+    for art in manifest.get("artefacts", []):
+        for pack in art.get("packs", []) or []:
+            pack_paths.setdefault(pack, []).append(art["path"])
+
+    for pack in manifest.get("packs", []):
+        summary = pack.get("trust_summary", {}) or {}
+        flagged_total = sum(int(summary.get(lvl, 0)) for lvl in _FLAGGED_LEVELS)
+        if flagged_total == 0:
+            continue
+        paths = pack_paths.get(pack["id"], [])
+        has_floor = any(_SAFETY_FLOOR_FRAGMENT in p for p in paths)
+        if not has_floor:
+            counts = ", ".join(
+                f"{lvl}={int(summary.get(lvl, 0))}" for lvl in _FLAGGED_LEVELS
+            )
+            errs.append(
+                f"pack `{pack['id']}` declares flagged artefacts ({counts})"
+                f" but ships no `*{_SAFETY_FLOOR_FRAGMENT}*` rule"
+            )
+    return errs
+
+
+def _check_human_review_banners(
+    manifest: dict[str, Any], compiled_src: Path
+) -> list[str]:
+    """Check 2: every human_review_required artefact has the banner."""
+    errs: list[str] = []
+    for art in manifest.get("artefacts", []):
+        trust = art.get("trust", {}) or {}
+        if not trust.get("human_review_required"):
+            continue
+        rel = art["path"]
+        logical = strip_source_prefix(rel)
+        if logical is None:
+            errs.append(
+                f"{rel}: human_review_required=true but path is not under"
+                " any known source root"
+            )
+            continue
+        compiled = compiled_src / logical
+        if not compiled.exists():
+            errs.append(
+                f"{rel}: human_review_required=true but compiled output"
+                f" missing at `{compiled.relative_to(ROOT)}`"
+            )
+            continue
+        body = compiled.read_text("utf-8", errors="replace")
+        if _BANNER_MARKER not in body:
+            errs.append(
+                f"{rel}: human_review_required=true but compiled output"
+                f" `{compiled.relative_to(ROOT)}` is missing the HRR banner"
+                f" (`{_BANNER_MARKER}`) — re-run `task compress`."
+            )
+    return errs
+
+
+def _check_kernel_trust(
+    manifest: dict[str, Any], kernel: set[str]
+) -> list[str]:
+    """Check 3: every kernel rule declares trust.level=core."""
+    errs: list[str] = []
+    # name -> artefact for category=rule entries. Manifest does not always
+    # populate `name` for rules, so fall back to the logical filename stem.
+    rule_by_name: dict[str, dict[str, Any]] = {}
+    for art in manifest.get("artefacts", []):
+        if art.get("category") != "rule":
+            continue
+        name = art.get("name")
+        if not name:
+            logical = strip_source_prefix(art.get("path", ""))
+            if logical is None:
+                continue
+            stem = Path(logical).stem
+            name = stem
+        rule_by_name[name] = art
+
+    for kname in sorted(kernel):
+        art = rule_by_name.get(kname)
+        if art is None:
+            errs.append(
+                f"kernel rule `{kname}` listed in router.json but no"
+                " matching artefact in manifest"
+            )
+            continue
+        level = (art.get("trust", {}) or {}).get("level")
+        if level != "core":
+            errs.append(
+                f"kernel rule `{kname}` has trust.level=`{level}`"
+                " — must be `core` (router.json kernel guarantees Iron-Law"
+                " floor)"
+            )
+    return errs
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--quiet", action="store_true")
+    parser.add_argument(
+        "--manifest", type=Path, default=MANIFEST, help="discovery manifest"
+    )
+    parser.add_argument(
+        "--router", type=Path, default=ROUTER, help="router.json with kernel[]"
+    )
+    parser.add_argument(
+        "--compiled-src",
+        type=Path,
+        default=COMPILED_SRC,
+        help="compiled output root (.agent-src/)",
+    )
+    args = parser.parse_args(argv)
+
+    manifest = _load_manifest(args.manifest)
+    kernel = _load_kernel(args.router)
+
+    errs: list[str] = []
+    errs.extend(_check_pack_safety_floors(manifest))
+    errs.extend(_check_human_review_banners(manifest, args.compiled_src))
+    errs.extend(_check_kernel_trust(manifest, kernel))
+
+    if errs:
+        for e in errs:
+            print(f"ERROR: {e}", file=sys.stderr)
+        print(
+            f"\n{len(errs)} trust-coherence violation(s) across"
+            f" {len(manifest.get('packs', []))} pack(s) and"
+            f" {len(manifest.get('artefacts', []))} artefact(s).",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print(
+            "✅  lint-trust-coherence:"
+            f" {len(manifest.get('packs', []))} pack(s),"
+            f" {len(kernel)} kernel rule(s),"
+            f" {sum(1 for a in manifest.get('artefacts', []) if (a.get('trust') or {}).get('human_review_required'))}"
+            " HRR artefact(s) clean."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/mcp_server/consumer_tool_catalog.json

@@ -22,7 +22,7 @@
     },
     {
       "name": "chat_history_append",
-      "description": "Append one entry to the consumer's chat-history JSONL (`agents/.agent-chat-history`). Path-scoped — writes outside the allowlist raise ValueError. Use `dry_run` to preview the payload without touching the filesystem.",
+      "description": "Append one entry to the consumer's chat-history JSONL (`agents/runtime/.agent-chat-history`; `agents/.agent-chat-history` and `.agent-chat-history` accepted for back-compat). Path-scoped — writes outside the allowlist raise ValueError. Use `dry_run` to preview the payload without touching the filesystem.",
       "side_effect": "fs-write",
       "implemented_on": ["stdio"],
       "input_schema": {
@@ -30,7 +30,7 @@
         "properties": {
           "text": {"type": "string"},
           "entry_type": {"type": "string", "description": "Short `t` tag (e.g. note, decision). Defaults to `note`."},
-          "path": {"type": "string", "description": "Optional path override. Must resolve to `agents/.agent-chat-history` or `.agent-chat-history` under consumer_root."},
+          "path": {"type": "string", "description": "Optional path override. Must resolve to `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under consumer_root."},
           "session": {"type": "string"},
           "dry_run": {"type": "boolean", "default": false},
           "min_schema_version": {"type": "integer"}
@@ -41,7 +41,7 @@
     },
     {
       "name": "chat_history_read",
-      "description": "Read recent chat-history entries from `agents/.agent-chat-history`. Filter by session, limit, or entry-type. Read-only.",
+      "description": "Read recent chat-history entries from `agents/runtime/.agent-chat-history` (`agents/.agent-chat-history` accepted for back-compat). Filter by session, limit, or entry-type. Read-only.",
       "side_effect": "ro",
       "implemented_on": ["stdio"],
       "input_schema": {

package/scripts/mcp_server/telemetry.py

@@ -14,7 +14,7 @@ Outcomes:
   envelope returned.
 - ``latent_demand`` — caller asked for a tool not in the catalog.
 
-The sink writes JSONL to ``agents/.mcp-telemetry/calls.jsonl`` under the
+The sink writes JSONL to ``agents/runtime/mcp-telemetry/calls.jsonl`` under the
 consumer root. Failure to write must not break the wire surface: the
 ``record_call`` helper swallows OSError + ValueError and emits a single
 warning to stderr.
@@ -33,7 +33,7 @@ Outcome = Literal["implemented", "stub", "latent_demand"]
 
 # Stable file location relative to consumer_root. Phase 2 K1 routes
 # this into a queryable store; Phase 1 only needs the file to exist.
-TELEMETRY_REL_DIR = "agents/.mcp-telemetry"
+TELEMETRY_REL_DIR = "agents/runtime/mcp-telemetry"
 TELEMETRY_FILENAME = "calls.jsonl"
 
 # Truncation length for the client_id hash. 12 hex chars = 48 bits of

package/scripts/mcp_server/tools.py

@@ -12,8 +12,11 @@ Names that are neither implemented nor catalog-listed raise
 
 Path-scoping is mandatory for any tool that writes: the resolved target
 path must stay under ``<consumer_root>`` and within the allowlist of
-filenames (`.agent-chat-history`, `agents/.agent-chat-history`). Escape
-attempts surface as ``ValueError`` before the underlying writer runs.
+filenames (`agents/runtime/.agent-chat-history` — current default;
+`agents/.agent-chat-history` and `.agent-chat-history` — kept for
+back-compat with older consumer installs that have not migrated yet).
+Escape attempts surface as ``ValueError`` before the underlying writer
+runs.
 
 This module deliberately does **not** import the ``subprocess`` module
 or ``os``-level shell-execution helpers directly. It imports project
@@ -48,6 +51,12 @@ STDIO_TRANSPORT = "stdio"
 # guard before the underlying writer touches the filesystem.
 _ALLOWED_WRITE_REL_PATHS: frozenset[str] = frozenset(
     {
+        # Current default (Volatile Runtime policy — agents/runtime/ is
+        # local-only and ignored by git).
+        "agents/runtime/.agent-chat-history",
+        # Back-compat: older consumer installs still write to the flat
+        # location. Additive — both paths stay accepted until the next
+        # major tool version bump.
         "agents/.agent-chat-history",
         ".agent-chat-history",
     }
@@ -93,7 +102,7 @@ def _validate_in_tree_path(raw: str | None, consumer_root: Path) -> Path:
     """
     root = consumer_root.resolve()
     if raw is None or raw == "":
-        target = root / "agents" / ".agent-chat-history"
+        target = root / "agents" / "runtime" / ".agent-chat-history"
     else:
         candidate = Path(raw)
         if candidate.is_absolute():
@@ -178,7 +187,8 @@ async def _chat_history_append_handler(
         text: free-form entry text. Stored under the ``text`` field.
         entry_type: short ``t`` tag (e.g. ``note``, ``decision``).
         path: optional override of the target file. Must resolve to one
-            of ``agents/.agent-chat-history`` / ``.agent-chat-history``
+            of ``agents/runtime/.agent-chat-history`` (current default),
+            ``agents/.agent-chat-history``, or ``.agent-chat-history``
             under ``consumer_root``.
         session: optional 16-char session tag. Falls back to the most
             recent body entry's ``s`` (see ``chat_history.append``).
@@ -277,7 +287,8 @@ async def _chat_history_read_handler(
         session: optional 16-char session id.
         entry_type: optional ``t`` field exact-match filter.
         path: optional override; must resolve under
-            ``agents/.agent-chat-history`` or ``.agent-chat-history``.
+            ``agents/runtime/.agent-chat-history`` (current default),
+            ``agents/.agent-chat-history``, or ``.agent-chat-history``.
     """
     from scripts.chat_history import read_entries  # noqa: PLC0415
 
@@ -536,9 +547,11 @@ ALLOWLIST: dict[str, BuiltinTool] = {
         name="chat_history_append",
         description=(
             "Append one entry to the consumer's chat-history JSONL "
-            "(`agents/.agent-chat-history`). Path-scoped — writes "
-            "outside the allowlist raise ValueError. Use `dry_run` to "
-            "preview the payload without touching the filesystem."
+            "(`agents/runtime/.agent-chat-history`; "
+            "`agents/.agent-chat-history` accepted for back-compat). "
+            "Path-scoped — writes outside the allowlist raise "
+            "ValueError. Use `dry_run` to preview the payload without "
+            "touching the filesystem."
         ),
         input_schema={
             "type": "object",
@@ -555,7 +568,9 @@ ALLOWLIST: dict[str, BuiltinTool] = {
                     "type": "string",
                     "description": (
                         "Optional path override. Must resolve to "
-                        "`agents/.agent-chat-history` or "
+                        "`agents/runtime/.agent-chat-history` "
+                        "(current default), "
+                        "`agents/.agent-chat-history`, or "
                         "`.agent-chat-history` under consumer_root."
                     ),
                 },
@@ -572,8 +587,9 @@ ALLOWLIST: dict[str, BuiltinTool] = {
         name="chat_history_read",
         description=(
             "Read recent chat-history entries from "
-            "`agents/.agent-chat-history`. Filter by session, "
-            "trailing-N, or entry-type. Read-only."
+            "`agents/runtime/.agent-chat-history` "
+            "(`agents/.agent-chat-history` accepted for back-compat). "
+            "Filter by session, trailing-N, or entry-type. Read-only."
         ),
         input_schema={
             "type": "object",

package/scripts/mcp_telemetry_health.py

@@ -1,7 +1,7 @@
 """MCP telemetry healthcheck — Phase 1 J6.
 
 Asserts that the per-consumer JSONL sink at
-``<consumer_root>/agents/.mcp-telemetry/calls.jsonl`` received at least
+``<consumer_root>/agents/runtime/mcp-telemetry/calls.jsonl`` received at least
 one record inside a configurable window (default 24 h). Exits non-zero
 on silence so the caller's alert sink — Sentry, email, GitHub Actions
 failure, cron mailer — fires.
@@ -166,7 +166,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "--consumer-root",
         type=Path,
         default=None,
-        help="Root directory containing agents/.mcp-telemetry/ (default: cwd).",
+        help="Root directory containing agents/runtime/mcp-telemetry/ (default: cwd).",
     )
     parser.add_argument(
         "--window-hours",

package/scripts/mcp_telemetry_store.py

@@ -32,7 +32,7 @@ from mcp_server.telemetry import (  # noqa: E402
     TELEMETRY_REL_DIR,
 )
 
-DEFAULT_DB_REL = "agents/.mcp-telemetry/calls.sqlite3"
+DEFAULT_DB_REL = "agents/runtime/mcp-telemetry/calls.sqlite3"
 SCHEMA_VERSION = 1
 
 

package/scripts/measure_augment_budget.py

@@ -21,7 +21,7 @@ Output:
 - Default: stdout summary (totals + per-component breakdown).
 - `--json`: deterministic JSON.
 - `--trend-append`: append a snapshot record to
-  `agents/.augment-budget-history.jsonl`.
+  `agents/runtime/.augment-budget-history.jsonl`.
 
 Exit codes: 0 = under fail threshold, 1 = at/above fail threshold,
 3 = internal error.
@@ -39,7 +39,7 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 AGENTS_MD = REPO_ROOT / "AGENTS.md"
 RULES_DIR = REPO_ROOT / ".augment" / "rules"
-TREND_FILE = REPO_ROOT / "agents" / ".augment-budget-history.jsonl"
+TREND_FILE = REPO_ROOT / "agents" / "runtime" / ".augment-budget-history.jsonl"
 
 # Augment workspace-guidelines ceiling — empirical 2026-05-08.
 # TOTAL_CAP is the hard ceiling Augment itself enforces. FAIL_THRESHOLD is the
@@ -170,7 +170,7 @@ def main() -> int:
     parser.add_argument(
         "--trend-append",
         action="store_true",
-        help="Append a snapshot record to agents/.augment-budget-history.jsonl",
+        help="Append a snapshot record to agents/runtime/.augment-budget-history.jsonl",
     )
     parser.add_argument(
         "--check",

package/scripts/measure_density.py

@@ -22,7 +22,7 @@ Companion signals collected per artifact (consumed by Phases 1.2-1.4):
 Output:
 - Default stdout: per-type distribution buckets + tail (lowest density).
 - ``--json`` deterministic JSON of every artifact.
-- ``--snapshot`` writes JSONL to ``agents/.density-snapshot.jsonl``.
+- ``--snapshot`` writes JSONL to ``agents/runtime/density/snapshot.jsonl``.
 
 Stdlib only; no network. Re-runnable.
 """
@@ -44,7 +44,7 @@ from skill_linter import (  # noqa: E402
     gather_all_candidate_files,
 )
 
-SNAPSHOT_FILE = REPO_ROOT / "agents" / ".density-snapshot.jsonl"
+SNAPSHOT_FILE = REPO_ROOT / "agents" / "runtime" / "density" / "snapshot.jsonl"
 
 _TABLE_ROW = re.compile(r"^\s*\|.*\|\s*$")
 _BULLET = re.compile(r"^\s*[-*]\s+\S")