@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/lint_positioning.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Positioning consistency lint for event4u/agent-config.
+
+Asserts that three public-positioning surfaces agree on the canonical
+phrasing and that every advertised GitHub topic is discoverable in the
+README body (literally or through `equivalents:` paraphrases).
+
+Sources:
+  - README.md              — canonical phrasing (H1 + first blockquote)
+  - package.json           — `description` field
+  - .github/about.yml      — `description` field
+  - .github/topics.yml     — `topics:` + optional `equivalents:` map
+
+Failure mode is a diff, not a stack trace. See R5 Phase 3 in
+agents/roadmaps/strategic-visibility-mcp-topics-positioning.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("❌  PyYAML is required: pip3 install pyyaml\n")
+    sys.exit(2)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+README = REPO_ROOT / "README.md"
+PACKAGE_JSON = REPO_ROOT / "package.json"
+ABOUT_YML = REPO_ROOT / ".github" / "about.yml"
+TOPICS_YML = REPO_ROOT / ".github" / "topics.yml"
+
+# Canonical anchor: the right-side phrase of the README H1
+# ("Agent Config — Universal AI Agent OS" → "Universal AI Agent OS").
+# This is the substring that MUST appear in the other two surfaces.
+H1_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+BLOCKQUOTE_RE = re.compile(r"^>\s+(.+?)\s*$", re.MULTILINE)
+DESCRIPTION_MAX = 200
+
+
+def _read_readme_anchors() -> tuple[str, str, str]:
+    text = README.read_text(encoding="utf-8")
+    h1_match = H1_RE.search(text)
+    if not h1_match:
+        raise SystemExit("❌  README.md has no H1 heading")
+    h1 = h1_match.group(1)
+    # Anchor = the phrase after the em dash, falling back to the whole H1.
+    parts = re.split(r"\s+[—–-]\s+", h1, maxsplit=1)
+    anchor = parts[1].strip() if len(parts) == 2 else h1.strip()
+
+    bq_match = BLOCKQUOTE_RE.search(text)
+    blockquote = bq_match.group(1).strip() if bq_match else ""
+    return h1, anchor, blockquote
+
+
+def _read_package_description() -> str:
+    data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    return str(data.get("description", "")).strip()
+
+
+def _read_about_description() -> str:
+    data = yaml.safe_load(ABOUT_YML.read_text(encoding="utf-8")) or {}
+    return str(data.get("description", "")).strip()
+
+
+def _read_topics() -> tuple[list[str], dict[str, list[str]]]:
+    data = yaml.safe_load(TOPICS_YML.read_text(encoding="utf-8")) or {}
+    topics = [str(t) for t in data.get("topics", [])]
+    equivalents = {str(k): [str(v) for v in vs] for k, vs in (data.get("equivalents") or {}).items()}
+    return topics, equivalents
+
+
+def _topic_present(readme_lc: str, topic: str, equivalents: dict[str, list[str]]) -> tuple[bool, str | None]:
+    needles = [topic, topic.replace("-", " "), topic.replace("-", "")] + equivalents.get(topic, [])
+    for n in needles:
+        if n and n.lower() in readme_lc:
+            return True, n
+    return False, None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Positioning consistency lint.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress success output.")
+    args = parser.parse_args()
+
+    h1, anchor, blockquote = _read_readme_anchors()
+    pkg_desc = _read_package_description()
+    about_desc = _read_about_description()
+    topics, equivalents = _read_topics()
+
+    errors: list[str] = []
+    anchor_lc = anchor.lower()
+    if anchor_lc not in pkg_desc.lower():
+        errors.append("package.json.description missing canonical anchor")
+    if anchor_lc not in about_desc.lower():
+        errors.append(".github/about.yml description missing canonical anchor")
+    if len(pkg_desc) > DESCRIPTION_MAX:
+        errors.append(f"package.json.description is {len(pkg_desc)} chars (max {DESCRIPTION_MAX})")
+    if len(about_desc) > DESCRIPTION_MAX:
+        errors.append(f".github/about.yml description is {len(about_desc)} chars (max {DESCRIPTION_MAX})")
+
+    readme_lc = README.read_text(encoding="utf-8").lower()
+    missing_topics: list[str] = []
+    for topic in topics:
+        present, _ = _topic_present(readme_lc, topic, equivalents)
+        if not present:
+            missing_topics.append(topic)
+
+    if errors or missing_topics:
+        sys.stderr.write("❌  positioning drift detected:\n")
+        sys.stderr.write(f"        README anchor:         {anchor}\n")
+        sys.stderr.write(f"        package.json.desc:     {pkg_desc}\n")
+        sys.stderr.write(f"        .github/about.yml:     {about_desc}\n\n")
+        for err in errors:
+            sys.stderr.write(f"        - {err}\n")
+        if missing_topics:
+            sys.stderr.write("\n        topics absent from README (literal + equivalents):\n")
+            for t in missing_topics:
+                sys.stderr.write(f"          - {t}\n")
+            sys.stderr.write(
+                "\n        Resolve by editing all three to share the canonical anchor,\n"
+                "        or extending .github/topics.yml's `equivalents:` map\n"
+                "        (or by removing the topic). The README is the canonical phrasing.\n"
+            )
+        else:
+            sys.stderr.write(
+                "\n        Resolve by editing all three to share the canonical anchor.\n"
+                "        The README is the canonical phrasing; the other two follow it.\n"
+            )
+        return 1
+
+    if not args.quiet:
+        sys.stdout.write(f"✅  positioning consistent (anchor: {anchor!r}, topics: {len(topics)})\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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`.
 

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/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,9 +39,15 @@ 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
+# soft safety-margin gate (0.95). When a branch breaches it, the discipline
+# is: DO NOT loosen the threshold — invoke the `rule-refactor` skill, which
+# audits all rules for merge / delete / move-to-context / promote-to-skill
+# candidates. Threshold-lift is explicitly rejected as a tool-shape anti-
+# pattern (see the validation-budget rule). Only an ADR may grow the cap.
 TOTAL_CAP = 49_512
 WARN_THRESHOLD = 0.85
 FAIL_THRESHOLD = 0.95
@@ -164,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")

package/scripts/measure_frugality_savings.py

@@ -3,7 +3,7 @@
 
 Measures the *current state* of the frugality canon along four
 deterministic axes. Output: JSONL baseline appended to
-agents/.frugality-baseline.jsonl (gitignored).
+agents/runtime/frugality/baseline.jsonl (gitignored).
 
 Metrics:
   A. footprint    — per-rule char/token count, kernel/tier breakdown
@@ -140,7 +140,7 @@ def metric_d_redundancy(root: Path) -> dict:
 
 def main() -> int:
     root = Path(__file__).resolve().parent.parent
-    corpus = root / "agents" / ".agent-chat-history"
+    corpus = root / "agents" / "runtime" / ".agent-chat-history"
 
     record = {
         "schema_version": 1,
@@ -152,7 +152,7 @@ def main() -> int:
         "metric_d_redundancy": metric_d_redundancy(root),
     }
 
-    out = root / "agents" / ".frugality-baseline.jsonl"
+    out = root / "agents" / "runtime" / "frugality" / "baseline.jsonl"
     with out.open("a") as fh:
         fh.write(json.dumps(record, ensure_ascii=False) + "\n")
     print(json.dumps(record, indent=2, ensure_ascii=False))

package/scripts/measure_roadmap_trajectory.py

@@ -3,7 +3,7 @@
 
 Walks `agents/roadmaps/archive/` and computes per-roadmap checkbox
 completion ratio at archival time. Output: one-line trajectory metric
-per roadmap, plus an aggregate `agents/reports/roadmap-trajectory.json`.
+per roadmap, plus an aggregate `agents/runtime/reports/roadmap-trajectory.json`.
 
 Checkbox grammar (mirrors `scripts/roadmap_progress_check.py`):
 - `[ ]` — open

package/scripts/measure_rule_budget.py

@@ -28,7 +28,7 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 RULES_DIR = REPO_ROOT / ".agent-src.uncompressed" / "rules"
 OVERRIDES_FILE = REPO_ROOT / "docs" / "contracts" / "iron-law-overrides.txt"
-TREND_FILE = REPO_ROOT / "agents" / ".rule-budget-history.jsonl"
+TREND_FILE = REPO_ROOT / "agents" / "runtime" / ".rule-budget-history.jsonl"
 
 # Council R2 amendments (2026-05-06) — see docs/contracts/kernel-membership.md § 5.1.
 # Per-rule cap raised 1.5k → 2.5k; warning band raised 1.2k → 2.0k.
@@ -241,7 +241,7 @@ def kernel_budget_check(
 
 
 def trend_append(agg: dict[str, object]) -> tuple[int, str]:
-    """Append a daily snapshot to agents/.rule-budget-history.jsonl.
+    """Append a daily snapshot to agents/runtime/.rule-budget-history.jsonl.
 
     Idempotent per UTC day: if today's date already has a row, the file
     is not modified. Snapshot fields: date, kernel_chars, auto_chars,
@@ -284,7 +284,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "--trend-append",
         action="store_true",
-        help="append today's snapshot to agents/.rule-budget-history.jsonl (idempotent per UTC day)",
+        help="append today's snapshot to agents/runtime/.rule-budget-history.jsonl (idempotent per UTC day)",
     )
     args = parser.parse_args(argv)
 

package/scripts/memory_report.py

@@ -48,7 +48,7 @@ _MODE_MARKER_PATTERN = re.compile(
 )
 _MODE_SCAN_DIRS = (
     Path("agents/sessions"),
-    Path("agents/reports"),
+    Path("agents/runtime/reports"),
     Path("agents/handoffs"),
     Path("agents/learnings"),
 )

package/scripts/migrate_command_suggestions.py

@@ -2,7 +2,7 @@
 """One-shot migration: inject the `suggestion:` frontmatter block into every
 command under `.agent-src.uncompressed/commands/`.
 
-Source-of-truth table: `agents/contexts/command-suggestion-eligibility.md`
+Source-of-truth table: `agents/settings/contexts/command-suggestion-eligibility.md`
 (locked at end of road-to-context-aware-command-suggestion Phase 1).
 
 Idempotent: if `suggestion:` is already present for a command, the file is
@@ -55,8 +55,8 @@ ELIGIBLE: dict[str, tuple[str, str]] = {
     "bug-investigate": ("why is this broken, investigate this error, trace the root cause", "Sentry URL, Jira bug ticket key, or stack trace pasted in the prompt"),
     "commit": ("commit my changes, save this to git, create commits for these changes", "git status shows uncommitted changes"),
     "commit-in-chunks": ("commit everything autonomously, split and commit without confirmation", "autonomous mode active and uncommitted changes present"),
-    "context-create": ("document this part of the codebase, create a context doc for X", "working in a module without an agents/contexts/ doc"),
-    "context-refactor": ("update the context doc, refresh this context document", "existing agents/contexts/*.md referenced in the prompt"),
+    "context-create": ("document this part of the codebase, create a context doc for X", "working in a module without an agents/settings/contexts/ doc"),
+    "context-refactor": ("update the context doc, refresh this context document", "existing agents/settings/contexts/*.md referenced in the prompt"),
     "create-pr": ("open a PR, create a pull request, make a PR for this branch", "branch is ahead of base and not yet on a PR"),
     "create-pr-description": ("write a PR description, draft the PR text", "PR exists or branch ready for review without description"),
     "e2e-heal": ("fix the failing E2E tests, playwright tests are red", "failing test output from tests/e2e/"),

package/scripts/minimal_safe_diff_hook.py

@@ -11,7 +11,7 @@ Wired to multiple events via the manifest:
   - session_start / user_prompt_submit → reset turn-scoped counters
   - pre_tool_use → record the planned edit's path before execution
 
-Output: `agents/state/minimal-safe-diff.json`
+Output: `agents/runtime/state/minimal-safe-diff.json`
   {
     "schema_version": 1,
     "session_id": "<str>",

package/scripts/onboarding_gate_hook.py

@@ -5,7 +5,7 @@ Reads `.agent-settings.yml` from the consumer repo and writes a
 deterministic state file the rule body can cite as the source of
 truth for "do I need to prompt the user about /onboard?".
 
-Output is written to `agents/state/onboarding-gate.json` with:
+Output is written to `agents/runtime/state/onboarding-gate.json` with:
   {
     "required": <bool>,         // true → rule fires on first turn
     "reason":   "<string>",     // why this state was set
@@ -31,7 +31,7 @@ import sys
 from pathlib import Path
 
 # Re-use the shared atomic-write helper so concerns honour the single
-# `agents/state/.dispatcher.lock` discipline (hook-architecture-v1.md
+# `agents/runtime/state/.dispatcher.lock` discipline (hook-architecture-v1.md
 # § Concurrency, Phase 7.4).
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from hooks.state_io import atomic_write_json  # noqa: E402
@@ -84,9 +84,9 @@ def _read_onboarded(settings_path: Path) -> tuple[bool, str]:
 
 def _write_state(consumer_root: Path, required: bool, reason: str,
                  settings_present: bool) -> None:
-    """Write `agents/state/onboarding-gate.json` atomically.
+    """Write `agents/runtime/state/onboarding-gate.json` atomically.
 
-    Uses the shared `agents/state/.dispatcher.lock` so concurrent
+    Uses the shared `agents/runtime/state/.dispatcher.lock` so concurrent
     dispatcher invocations across platforms cannot tear the file
     (hook-architecture-v1.md § Concurrency, Phase 7.4).
     """