@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/build_mcp_registry_manifest.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Build `dist/mcp/registry-manifest.json` + the two rendered payloads.
+
+Reads three on-disk sources:
+  * `package.json`                          — name, version, description, homepage, repository
+  * `.github/topics.yml`                    — topics list (for registries that accept tags)
+  * `workers/mcp/content.json`              — `tool_catalog` (tools_count, install_hint_stdio)
+  * `dist/discovery/discovery-manifest.json` — artefact_count + scanner_version (HARD prereq per AI-Council R5)
+
+Emits:
+  * `dist/mcp/registry-manifest.json`            — source-of-truth manifest
+  * `dist/mcp/awesome-mcp-servers.row.md`        — single Markdown row
+  * `dist/mcp/mcp-cloudflare-catalogue.json`     — single JSON catalogue entry
+
+Lifecycle state (`status`, `submitted_at`, `pr_url`, `last_verified`) is
+**preserved** from the previous manifest. First-time generation seeds
+`status=pending` and nulls the rest. Status transitions are hand-edits
+under maintainer review — see `docs/distribution/mcp-submission-checklist.md`.
+
+CLI: `--write` / `--strict` / `--quiet` — matches the discovery scanner shape.
+
+Schema: `docs/contracts/mcp-registry-manifest.schema.json`
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 2.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+PKG_FILE = ROOT / "package.json"
+TOPICS_FILE = ROOT / ".github" / "topics.yml"
+CONTENT_FILE = ROOT / "workers" / "mcp" / "content.json"
+DISCOVERY_FILE = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+OUT_DIR = ROOT / "dist" / "mcp"
+OUT_MANIFEST = OUT_DIR / "registry-manifest.json"
+OUT_ROW_MD = OUT_DIR / "awesome-mcp-servers.row.md"
+OUT_CF_JSON = OUT_DIR / "mcp-cloudflare-catalogue.json"
+
+REGISTRIES_SEED = [
+    {
+        "id": "awesome-mcp-servers",
+        "label": "punkpeye/awesome-mcp-servers",
+        "listing_format": "markdown-row",
+        "submission_url": "https://github.com/punkpeye/awesome-mcp-servers",
+        "rendered_payload": "dist/mcp/awesome-mcp-servers.row.md",
+    },
+    {
+        "id": "mcp-cloudflare-catalogue",
+        "label": "Cloudflare MCP catalogue",
+        "listing_format": "json-entry",
+        "submission_url": "https://github.com/cloudflare/mcp-server-cloudflare",
+        "rendered_payload": "dist/mcp/mcp-cloudflare-catalogue.json",
+    },
+]
+
+
+def _repo_url(pkg: dict[str, Any]) -> str:
+    raw = (pkg.get("repository") or {}).get("url") or ""
+    return re.sub(r"^git\+|\.git$", "", raw)
+
+
+def _build(now_utc: _dt.datetime) -> dict[str, Any]:
+    pkg = json.loads(PKG_FILE.read_text(encoding="utf-8"))
+    topics_doc = yaml.safe_load(TOPICS_FILE.read_text(encoding="utf-8")) or {}
+    content = json.loads(CONTENT_FILE.read_text(encoding="utf-8"))
+    if not DISCOVERY_FILE.exists():
+        sys.exit(
+            "ERROR: dist/discovery/discovery-manifest.json missing. R3 (discovery) "
+            "is a hard prerequisite per the AI-Council external review. "
+            "Run `npm run build:discovery` first."
+        )
+    discovery = json.loads(DISCOVERY_FILE.read_text(encoding="utf-8"))
+
+    tc = content["tool_catalog"]
+    prior = json.loads(OUT_MANIFEST.read_text(encoding="utf-8")) if OUT_MANIFEST.exists() else {}
+    prior_reg = {r["id"]: r for r in (prior.get("registries") or [])}
+
+    registries: list[dict[str, Any]] = []
+    for seed in REGISTRIES_SEED:
+        prev = prior_reg.get(seed["id"], {})
+        registries.append({
+            **seed,
+            "status": prev.get("status", "pending"),
+            "submitted_at": prev.get("submitted_at"),
+            "pr_url": prev.get("pr_url"),
+            "last_verified": prev.get("last_verified"),
+        })
+
+    return {
+        "version": 1,
+        "generated_at": now_utc.strftime("%Y-%m-%d"),
+        "package": {
+            "name": pkg["name"],
+            "version": pkg["version"],
+            "description": pkg["description"],
+            "homepage": pkg["homepage"],
+            "repository": _repo_url(pkg),
+        },
+        "server": {
+            "name": "agent-config-mcp",
+            "transports": ["stdio", "worker"],
+            "tools_count": len(tc["tools"]),
+            "install_hint_stdio": tc["install_hint_stdio"],
+        },
+        "topics": sorted(topics_doc.get("topics") or []),
+        "discovery": {
+            "artefact_count": len(discovery["artefacts"]),
+            "scanner_version": discovery["scanner_version"],
+        },
+        "registries": registries,
+    }
+
+
+def _render_row_md(m: dict[str, Any]) -> str:
+    pkg = m["package"]
+    srv = m["server"]
+    transports = ", ".join(srv["transports"])
+    return (
+        f"| [{pkg['name']}]({pkg['homepage']}) "
+        f"| {pkg['description']} "
+        f"| {srv['tools_count']} tools ({transports}) "
+        f"| `{srv['install_hint_stdio']}` |\n"
+    )
+
+
+def _render_cf_json(m: dict[str, Any]) -> str:
+    pkg = m["package"]
+    srv = m["server"]
+    payload = {
+        "name": srv["name"],
+        "description": pkg["description"],
+        "homepage": pkg["homepage"],
+        "repository": pkg["repository"],
+        "transports": srv["transports"],
+        "tools_count": srv["tools_count"],
+        "install_hint_stdio": srv["install_hint_stdio"],
+        "topics": m["topics"],
+    }
+    return json.dumps(payload, indent=2, sort_keys=True) + "\n"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--write", action="store_true", help="write outputs to disk (default: print to stdout)")
+    ap.add_argument("--strict", action="store_true", help="exit 2 if on-disk outputs would change")
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+
+    now_utc = _dt.datetime.now(_dt.timezone.utc)
+    manifest = _build(now_utc)
+    manifest_text = json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+    row_md = _render_row_md(manifest)
+    cf_json = _render_cf_json(manifest)
+
+    outputs = [(OUT_MANIFEST, manifest_text), (OUT_ROW_MD, row_md), (OUT_CF_JSON, cf_json)]
+    changed = [p for p, t in outputs if not p.exists() or p.read_text(encoding="utf-8") != t]
+
+    if args.write:
+        OUT_DIR.mkdir(parents=True, exist_ok=True)
+        for p, t in outputs:
+            p.write_text(t, encoding="utf-8")
+        if not args.quiet:
+            verb = "wrote" if changed else "unchanged"
+            print(f"\u2705  {verb} {len(outputs)} file(s) under dist/mcp/")
+    else:
+        if not args.quiet:
+            print(manifest_text, end="")
+
+    return 2 if (args.strict and changed and not args.write) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/build_rule_trigger_matrix.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Build agents/contexts/rule-trigger-matrix.md.
+"""Build agents/settings/contexts/rule-trigger-matrix.md.
 
 Emits a single matrix mapping every rule in `.agent-src.uncompressed/rules/`
 to its trigger event, observability, enforcement surface, hook-cost
@@ -113,7 +113,7 @@ add("commit-conventions.md", "commit message draft", "hook", "output",
 add("docs-sync.md", "file-edit on .augment/{skills,rules,commands}/**", "hook",
     "tool-call", "medium", "2a",
     notes="Detect add/rename/delete; remind to update count + cross-refs")
-add("agent-docs.md", "file-edit on agents/docs/, AGENTS.md", "hook",
+add("agent-docs.md", "file-edit on agents/reference/docs/, AGENTS.md", "hook",
     "tool-call", "medium", "2a", notes="Path-pattern based marker")
 add("upstream-proposal.md", "skill/rule create event", "hook", "output",
     "medium", "2a", notes="Marker after new artifact lands")

package/scripts/capture_showcase_session.py

@@ -11,7 +11,7 @@ Two subcommands:
             task_class, metrics).
 
   metrics   Compute one or all of the four outcome metrics defined in
-            `agents/contexts/outcome-baseline.md` from a captured session
+            `agents/settings/contexts/outcome-baseline.md` from a captured session
             file. Output as text table or JSON.
 
 The four metrics:

package/scripts/chat_history.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Persistent chat-history log for crash recovery.
 
-Maintains `agents/.agent-chat-history` — a JSONL file whose
+Maintains `agents/runtime/.agent-chat-history` — a JSONL file whose
 first line is a header (schema version, started timestamp, cadence
 frequency) and whose remaining lines are append-only entries (user
 messages, phases, tool calls, questions, answers, decisions, commits).
@@ -12,7 +12,7 @@ sessions coexist in one file; each entry self-identifies. No ownership
 layer, no sidecar, no auto-adopt — every hook invocation simply appends
 with its own session tag.
 
-File path defaults to `agents/.agent-chat-history` (relative to CWD) and
+File path defaults to `agents/runtime/.agent-chat-history` (relative to CWD) and
 can be overridden via `$AGENT_CHAT_HISTORY_FILE` (used by tests).
 
 Usage:
@@ -42,7 +42,7 @@ from collections import Counter, deque
 from pathlib import Path
 from typing import Any
 
-DEFAULT_FILE = "agents/.agent-chat-history"
+DEFAULT_FILE = "agents/runtime/.agent-chat-history"
 DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
 SCHEMA_VERSION = 4
 DEFAULT_MAX_SESSIONS = 5
@@ -691,7 +691,7 @@ CADENCE_EVENTS = {
 # internal VALID_HOOK_EVENTS. Used by hook_dispatch() to translate
 # stdin JSON payloads coming from Claude Code, Augment Code, Cursor,
 # Cline, Windsurf, and Gemini CLI into a unified entry-point. Sourced
-# from agents/contexts/chat-history-platform-hooks.md.
+# from agents/settings/contexts/chat-history-platform-hooks.md.
 PLATFORM_EVENT_MAP: dict[str, dict[str, str]] = {
     "claude": {
         "SessionStart": "session_start",
@@ -716,7 +716,7 @@ PLATFORM_EVENT_MAP: dict[str, dict[str, str]] = {
     # with `--setting-sources user`. Until those are resolved, the
     # mapping below is dispatcher-ready but the lifecycle events do
     # not actually fire from Cowork. See
-    # `agents/contexts/chat-history-platform-hooks.md` § Cowork.
+    # `agents/settings/contexts/chat-history-platform-hooks.md` § Cowork.
     "cowork": {
         "SessionStart": "session_start",
         "UserPromptSubmit": "user_prompt",

package/scripts/check_always_budget.py

@@ -56,9 +56,14 @@ CONCENTRATION_TOP3_PCT = 0.30
 # the measured extended-size ceiling at the day road-to-path-fixes was
 # closed; growth above the ceiling regresses CI. Future kernel-aware
 # trimming work retires entries here.
+# R3 Phase 4 mass-annotation added 12 lines of ADR-013 discovery
+# frontmatter (workspaces / packs / lifecycle / trust / install — 189
+# chars) to every always-rule. Both ceilings below were re-baselined
+# +189 to absorb that frontmatter-only growth, mirroring the Phase 2
+# feedback-consolidation `tier: "safety-floor"` precedent (+21).
 KNOWN_CONCENTRATION_BREACHES: dict[str, int] = {
-    "language-and-tone.md": 3_985,
-    "no-cheap-questions.md": 3_530,
+    "language-and-tone.md": 4_174,
+    "no-cheap-questions.md": 3_719,
 }
 # Top-3 non-floor concentration ceiling — same rationale as the
 # per-rule allowlist above. The current top-3 sum (language-and-tone +

package/scripts/check_artefact_checksums.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Phase-6 checksum-stability gate (monorepo Phase 2, ADR-015).
+
+For every artefact in the committed
+``dist/discovery/discovery-manifest.json``, recompute the per-artefact
+sha256 using the same normalization as
+``scripts/build_discovery_manifest.py::_artefact_checksum`` and assert
+it matches the manifest entry.
+
+Distinct from ``validate-discovery-manifest`` (which rebuilds the
+whole manifest in memory and diffs): this gate is the focused
+"does the committed checksum still match the source bytes?" check
+that third-party consumers can run to verify the manifest contract.
+
+CLI:
+  python scripts/check_artefact_checksums.py [--manifest PATH] [--quiet]
+
+Exit codes:
+  0  every artefact checksum matches its source bytes
+  1  one or more checksums drifted (manifest is stale, or source moved)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+# Import the same hashing primitive the builder uses so normalisation
+# stays in lockstep with the generator. (ADR-015 §Phase 6.)
+from build_discovery_manifest import _artefact_checksum  # noqa: E402
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+
+def _frontmatter(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8", errors="replace")
+    fm, _ = parse_frontmatter(text)
+    return fm
+
+
+def _check(manifest_path: Path) -> tuple[int, list[str]]:
+    if not manifest_path.exists():
+        return 1, [f"manifest not found at {manifest_path}"]
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return 1, [f"invalid JSON: {exc}"]
+
+    errors: list[str] = []
+    for art in manifest.get("artefacts", []):
+        rel = art.get("path")
+        recorded = art.get("checksum")
+        if not isinstance(rel, str) or not isinstance(recorded, str):
+            errors.append(f"malformed entry: {art!r}")
+            continue
+        src = ROOT / rel
+        if not src.exists():
+            errors.append(f"{rel}: source file missing")
+            continue
+        actual = _artefact_checksum(src, _frontmatter(src))
+        if actual != recorded:
+            errors.append(
+                f"{rel}: checksum drift "
+                f"(manifest={recorded[:23]}…, source={actual[:23]}…)"
+            )
+    return (0 if not errors else 1), errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    code, errors = _check(args.manifest)
+    if code != 0:
+        for e in errors[:20]:
+            print(f"error: {e}", file=sys.stderr)
+        if len(errors) > 20:
+            print(f"  ... and {len(errors) - 20} more", file=sys.stderr)
+        print(
+            "checksum-stability gate failed — run `task build-discovery` "
+            "and commit dist/discovery/.",
+            file=sys.stderr,
+        )
+        return 1
+    if not args.quiet:
+        manifest = json.loads(args.manifest.read_text(encoding="utf-8"))
+        print(
+            f"OK {args.manifest.relative_to(ROOT)}: "
+            f"{len(manifest['artefacts'])} artefact checksums verified."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_cluster_patterns.py

@@ -32,9 +32,25 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
-COMMANDS_DIR = ROOT / ".agent-src.uncompressed/commands"
+sys.path.insert(0, str(ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
 CONTRACT = ROOT / "docs/contracts/command-clusters.md"
 
+
+def _resolve_command(cluster: str) -> Path:
+    """Return the physical path for ``commands/<cluster>.md``.
+
+    Walks every artefact root (legacy + packages/*) and returns the first
+    match. If none exist, returns the conventional legacy path so the
+    caller can surface a missing-file error.
+    """
+    rel = f"commands/{cluster}.md"
+    hit = resolve_logical(rel)
+    if hit is not None:
+        return hit
+    return ROOT / ".agent-src.uncompressed" / rel
+
 REQUIRED_SECTIONS = ["## Sub-commands", "## Dispatch", "## Rules"]
 TABLE_HEADER_RE = re.compile(
     r"\|\s*Sub-command\s*\|\s*Routes to\s*\|\s*Purpose\s*\|", re.IGNORECASE
@@ -87,10 +103,10 @@ def parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
 
 
 def check_dispatcher(cluster: str) -> FileReport:
-    path = COMMANDS_DIR / f"{cluster}.md"
+    path = _resolve_command(cluster)
     rep = FileReport(path=path, cluster=cluster)
     if not path.exists():
-        rep.errors.append(f"dispatcher file missing: {path.relative_to(ROOT)}")
+        rep.errors.append(f"dispatcher file missing: commands/{cluster}.md")
         return rep
     text = path.read_text(encoding="utf-8")
     fm, body = parse_frontmatter(text)
@@ -136,7 +152,7 @@ def main() -> int:
 
     # Flag clusters: only assert the file exists; legacy shape is preserved.
     flag_missing = [n for n in flag_clusters
-                    if not (COMMANDS_DIR / f"{n}.md").exists()]
+                    if not _resolve_command(n).exists()]
     if flag_missing:
         print(f"❌  Flag-cluster file(s) missing: {flag_missing}")
         return 1

package/scripts/check_command_count_messaging.py

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

package/scripts/check_council_layout.py

@@ -4,21 +4,23 @@
 Council artefacts (questions, responses, sessions) belong in three
 canonical directories under `agents/`:
 
-  - agents/council-questions/<topic-slug>.md       (paired with roadmap/ADR)
-  - agents/council-responses/<topic-slug>.json     (paired with question)
-  - agents/council-sessions/<UTC-timestamp>.json   (ad-hoc sessions)
+  - agents/runtime/council/questions/<topic-slug>.md       (paired with roadmap/ADR)
+  - agents/runtime/council/responses/<topic-slug>.json     (paired with question)
+  - agents/runtime/council/sessions/<UTC-timestamp>.json   (ad-hoc sessions)
 
 The three canonical dirs are gitignored — the linter therefore only
 catches **misplacement**, not naming-conventions inside the dirs:
 
   - Files at agents/ root with a council-* or .council-* prefix
-    (e.g. agents/council-question-foo.md, agents/.council-foo.md).
+    (e.g. agents/council-foo.md, agents/.council-foo.md).
   - council-* files under any other subdirectory of agents/.
 
-`agents/audit-*/` directories are exempt — historical audit bundles
-are cohesive, checked-in narratives (the canonical council dirs are
-gitignored) and may legitimately include council-* artefacts as part
-of the audit's evidence trail.
+`agents/evidence/audits/` is exempt — historical audit bundles are cohesive,
+checked-in narratives (the canonical council dirs are gitignored)
+and may legitimately include council-* artefacts as part of the
+audit's evidence trail. `agents/runtime/` is exempt too — the
+canonical council dirs live at `agents/runtime/council/{questions,
+responses,sessions}/` and the whole `runtime/` tree is gitignored.
 
 Failure modes are enforced by `.agent-src.uncompressed/skills/ai-council/SKILL.md`
 § "Output path convention".
@@ -40,15 +42,17 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 AGENTS_ROOT = Path("agents")
+# Canonical council dirs now live under agents/runtime/council/.
+# Stored as relative POSIX paths from AGENTS_ROOT.
 CANONICAL_DIRS = {
-    "council-questions": ".md",
-    "council-responses": ".json",
-    "council-sessions": ".json",
+    "runtime/council/questions": ".md",
+    "runtime/council/responses": ".json",
+    "runtime/council/sessions": ".json",
 }
-# Subdirectory prefixes whose contents are exempt from the layout check.
-# `audit-*/` covers historical audit bundles where council artefacts
-# form part of the documented evidence trail.
-EXEMPT_DIR_PREFIXES = ("audit-",)
+# Top-level subdirectories whose contents are exempt from the layout
+# check. `audits/` covers historical audit bundles. `runtime/` is the
+# gitignored volatile tree (canonical council dirs live there).
+EXEMPT_DIR_PREFIXES = ("audits", "runtime")
 # A council artefact is a file whose name starts with `council-` or
 # `.council-`. This intentionally excludes roadmaps like
 # `road-to-ai-council.md` whose stem only contains the word "council".
@@ -71,8 +75,8 @@ def find_violations(root: Path) -> list[str]:
         if is_council_artefact(path):
             findings.append(
                 f"{path}: council artefact at agents/ root — move to "
-                f"agents/council-questions/, agents/council-responses/, "
-                f"or agents/council-sessions/ per ai-council § Output path "
+                f"agents/runtime/council/questions/, agents/runtime/council/responses/, "
+                f"or agents/runtime/council/sessions/ per ai-council § Output path "
                 f"convention."
             )
 
@@ -86,14 +90,16 @@ def find_violations(root: Path) -> list[str]:
             continue
         if len(rel.parts) == 1:
             continue  # already handled above
-        if rel.parts[0] in CANONICAL_DIRS:
+        rel_posix = rel.as_posix()
+        if any(rel_posix.startswith(d + "/") for d in CANONICAL_DIRS):
             continue
         if rel.parts[0].startswith(EXEMPT_DIR_PREFIXES):
             continue
         findings.append(
             f"{path}: council artefact in non-canonical directory "
-            f"agents/{rel.parts[0]}/ — only council-questions/, "
-            f"council-responses/, council-sessions/ are allowed."
+            f"agents/{rel.parts[0]}/ — only "
+            f"agents/runtime/council/{{questions,responses,sessions}}/ "
+            f"are allowed."
         )
 
     return findings