@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/compile_router.py

@@ -15,8 +15,11 @@ import sys
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
+# ADR-017: rules now live across multiple source roots. Legacy
+# .agent-src.uncompressed/rules/ is kept as a fallback for the
+# pure-compressed consumer projection.
 RULES_DIR = ROOT / ".agent-src.uncompressed" / "rules"
-OUT_PATH = ROOT / "router.json"
+OUT_PATH = ROOT / "dist" / "router.json"
 SETTINGS_PATH = ROOT / ".agent-settings.yml"
 SCHEMA_VERSION = 1
 
@@ -116,11 +119,39 @@ def _load_settings() -> dict:
     return load_agent_settings(project_path=SETTINGS_PATH)
 
 
+def _iter_rule_files() -> list[Path]:
+    """Walk every source root for rule files. First root wins per id."""
+    try:
+        from scripts._lib.agent_src import artefact_roots  # type: ignore
+    except ImportError:
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_src import artefact_roots  # type: ignore[import-not-found]
+
+    seen: dict[str, Path] = {}
+    roots = artefact_roots()
+    if not roots:
+        # Pure-compressed fallback for consumer projections that vendor
+        # the flat .agent-src/ tree without sources.
+        if RULES_DIR.exists():
+            for path in sorted(RULES_DIR.glob("*.md")):
+                seen.setdefault(path.stem, path)
+    else:
+        for src_root in roots:
+            rd = src_root / "rules"
+            if not rd.exists():
+                continue
+            for path in sorted(rd.glob("*.md")):
+                seen.setdefault(path.stem, path)
+    return [seen[k] for k in sorted(seen)]
+
+
 def _collect(rules_dir: Path) -> dict:
     settings = _load_settings()
     kernel: list[str] = []
     tiered: dict[str, list[dict]] = {"tier-1": [], "tier-2": []}
-    for path in sorted(rules_dir.glob("*.md")):
+    for path in _iter_rule_files():
         fm = _parse_frontmatter(path.read_text(encoding="utf-8"))
         if not fm:
             continue
@@ -172,6 +203,7 @@ def main(argv: list[str]) -> int:
             return 1
         print("✅  router.json is up to date")
         return 0
+    OUT_PATH.parent.mkdir(parents=True, exist_ok=True)
     OUT_PATH.write_text(text, encoding="utf-8")
     counts = (len(out["kernel"]), len(out["tier_1"]), len(out["tier_2"]))
     print(f"✅  router.json — kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}")

package/scripts/compress.py

@@ -32,14 +32,43 @@ import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.script_output import info, success, flush_summary, resolve_level  # noqa: E402
+from _lib.agent_src import (  # noqa: E402
+    artefact_roots,
+    iter_all_sources,
+    resolve_logical,
+)
 
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
+# Legacy single-root anchor — kept for backward compatibility with callers
+# that pass it explicitly. Multi-root iteration (post-ADR-017 physical
+# move) goes through `_lib.agent_src` helpers.
 SOURCE_DIR = PROJECT_ROOT / ".agent-src.uncompressed"
 TARGET_DIR = PROJECT_ROOT / ".agent-src"
 AUGMENT_DIR = PROJECT_ROOT / ".augment"
 HASH_FILE = PROJECT_ROOT / ".compression-hashes.json"
 SETTINGS_FILE = PROJECT_ROOT / ".agent-settings.yml"
 
+
+def _iter_sources():
+    """Yield (physical_path, logical_relpath) for every source artefact.
+
+    Wraps `_lib.agent_src.iter_all_sources` so the compressor walks every
+    active source root (legacy `.agent-src.uncompressed/` plus any
+    `packages/*/.agent-src.uncompressed/`) and keys outputs by the
+    logical relative path that survives the physical move (ADR-017).
+    """
+    yield from iter_all_sources()
+
+
+def _resolve_source(relative: str) -> Path | None:
+    """Find the physical path that backs a logical relative path."""
+    return resolve_logical(relative)
+
+
+def _any_source_root_exists() -> bool:
+    """True if at least one artefact source root contains files."""
+    return bool(artefact_roots())
+
 # Self-projection tool toggle — see .agent-tools.yml. When the file is
 # absent (e.g. tests run in tmp dirs, consumer projects), `_active_tools`
 # returns ``None`` which is treated as "emit every tool".
@@ -148,8 +177,8 @@ def mark_done(relative_path: str) -> None:
     relative paths in the shipped layer (P1 of road-to-path-fixes.md).
     Idempotent — re-running is a no-op.
     """
-    source_file = SOURCE_DIR / relative_path
-    if not source_file.exists():
+    source_file = _resolve_source(relative_path)
+    if source_file is None or not source_file.exists():
         print(f"❌  Source file not found: {relative_path}")
         sys.exit(1)
     apply_path_rewriter(relative_path)
@@ -181,12 +210,9 @@ def mark_all_done() -> None:
     """Mark ALL .md files as compressed (e.g. after initial full compression)."""
     hashes = load_hashes()
     count = 0
-    for source_file in sorted(SOURCE_DIR.rglob("*")):
-        if source_file.is_dir():
-            continue
+    for source_file, relative in _iter_sources():
         if not should_compress(source_file):
             continue
-        relative = str(source_file.relative_to(SOURCE_DIR))
         hashes[relative] = file_hash(source_file)
         count += 1
     save_hashes(hashes)
@@ -194,15 +220,17 @@ def mark_all_done() -> None:
 
 
 def list_changed_md(source_dir: Path) -> list:
-    """List .md files whose source hash differs from stored hash (= need recompression)."""
+    """List .md files whose source hash differs from stored hash (= need recompression).
+
+    The ``source_dir`` parameter is retained for backward compatibility but
+    ignored — iteration walks every active source root (ADR-017).
+    """
+    del source_dir  # multi-root: ignored, kept for signature stability
     hashes = load_hashes()
     changed = []
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
-            continue
+    for source_file, relative in _iter_sources():
         if not should_compress(source_file):
             continue
-        relative = str(source_file.relative_to(source_dir))
         current_hash = file_hash(source_file)
         stored_hash = hashes.get(relative)
         if stored_hash != current_hash:
@@ -211,12 +239,12 @@ def list_changed_md(source_dir: Path) -> list:
 
 
 def find_stale_hashes(source_dir: Path) -> list:
-    """Find hashes stored for source files that no longer exist."""
+    """Find hashes stored for source files that no longer exist in any root."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     hashes = load_hashes()
     stale = []
     for relative in sorted(hashes.keys()):
-        source_file = source_dir / relative
-        if not source_file.exists():
+        if _resolve_source(relative) is None:
             stale.append(relative)
     return stale
 
@@ -240,10 +268,16 @@ def should_compress(filepath: Path) -> bool:
         return False
     if filepath.name in COPY_AS_IS:
         return False
-    try:
-        rel_parts = filepath.relative_to(SOURCE_DIR).parts
-    except ValueError:
-        rel_parts = filepath.parts
+    # Determine the logical relative path so the COPY_AS_IS_DIRS check
+    # works for both legacy (`.agent-src.uncompressed/`) and post-move
+    # (`packages/*/.agent-src.uncompressed/`) source roots.
+    rel_parts: tuple[str, ...] = filepath.parts
+    for root in artefact_roots():
+        try:
+            rel_parts = filepath.relative_to(root).parts
+            break
+        except ValueError:
+            continue
     if rel_parts and rel_parts[0] in COPY_AS_IS_DIRS:
         return False
     return True
@@ -256,7 +290,8 @@ def copy_file(source: Path, target: Path) -> None:
 
 
 def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
-    """Delete files in target that don't exist in source. Returns count."""
+    """Delete files in target that don't exist in any source root. Returns count."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     deleted = 0
     if not target_dir.exists():
         return 0
@@ -265,8 +300,7 @@ def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
         if target_file.is_dir():
             continue
         relative = target_file.relative_to(target_dir)
-        source_file = source_dir / relative
-        if not source_file.exists():
+        if _resolve_source(str(relative)) is None:
             print(f"  Deleting stale: {relative}")
             target_file.unlink()
             deleted += 1
@@ -281,14 +315,17 @@ def cleanup_stale(source_dir: Path, target_dir: Path) -> int:
 
 
 def sync_non_md(source_dir: Path, target_dir: Path) -> int:
-    """Copy all non-.md files (and COPY_AS_IS .md files) from source to target. Returns count."""
+    """Copy all non-.md files (and COPY_AS_IS .md files) from every source
+    root to target. Returns count."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     copied = 0
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
-            continue
+    seen: set[str] = set()
+    for source_file, relative in _iter_sources():
         if should_compress(source_file):
             continue  # .md files are compressed by the agent, not copied here
-        relative = source_file.relative_to(source_dir)
+        if relative in seen:
+            continue
+        seen.add(relative)
         target_file = target_dir / relative
         copy_file(source_file, target_file)
         print(f"  Copied: {relative}")
@@ -298,36 +335,41 @@ def sync_non_md(source_dir: Path, target_dir: Path) -> int:
 
 def list_md_files(source_dir: Path) -> list:
     """List all .md files that need compression by the agent."""
-    files = []
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
+    del source_dir  # multi-root: ignored, kept for signature stability
+    files: list[str] = []
+    seen: set[str] = set()
+    for source_file, relative in _iter_sources():
+        if not should_compress(source_file):
             continue
-        if should_compress(source_file):
-            files.append(str(source_file.relative_to(source_dir)))
-    return files
+        if relative in seen:
+            continue
+        seen.add(relative)
+        files.append(relative)
+    return sorted(files)
 
 
 def check_sync(source_dir: Path, target_dir: Path) -> tuple:
-    """Check if target is in sync with source. Returns (missing, stale) lists."""
+    """Check if target is in sync with source(s). Returns (missing, stale) lists."""
+    del source_dir  # multi-root: ignored, kept for signature stability
     missing = []
     stale = []
 
-    # Files in source but not in target
-    for source_file in sorted(source_dir.rglob("*")):
-        if source_file.is_dir():
+    # Files in any source root but not in target
+    seen: set[str] = set()
+    for _source_file, relative in _iter_sources():
+        if relative in seen:
             continue
-        relative = str(source_file.relative_to(source_dir))
+        seen.add(relative)
         if not (target_dir / relative).exists():
             missing.append(relative)
 
-    # Files in target but not in source (stale)
+    # Files in target but not in any source root (stale)
     if target_dir.exists():
         for target_file in sorted(target_dir.rglob("*")):
             if target_file.is_dir():
                 continue
             relative = str(target_file.relative_to(target_dir))
-
-            if not (source_dir / relative).exists():
+            if _resolve_source(relative) is None:
                 stale.append(relative)
 
     return missing, stale
@@ -512,11 +554,80 @@ def _rewrite_body_links(body: str, prefix: str) -> str:
     return _BODY_DOCS_RE.sub(prefix + r"\1", body)
 
 
+# ── Human-review banner injection (Phase 5.3 / ADR-018) ───────────────────
+# Source artefacts may set `trust.human_review_required: true` in their
+# frontmatter. The compressor injects a short, parser-stable banner block
+# at the top of the projected body so every downstream surface (agent
+# memory, .augment, .claude, etc.) surfaces the gate. Idempotent — the
+# marker comment prevents double-injection on re-compress.
+
+_HRR_BANNER_MARKER = "<!-- agent-config:human-review-banner -->"
+
+# Plain YAML list item — any scalar, used to read `packs:` / `workspaces:`
+# blocks where values are bare identifiers, not file paths.
+_FM_PLAIN_LIST_RE = re.compile(r'^\s*-\s*(["\']?)([^"\'\n]+?)\1\s*$')
+
+
+def _parse_trust_and_owner(fm_lines):
+    """Extract `trust.level`, `human_review_required`, and an owner hint
+    from a frontmatter line list. Owner falls back to the first pack
+    prefix (`finance-basic` → `finance`), then the first workspace,
+    then `unknown`.
+    """
+    level = None
+    hrr = False
+    packs: list[str] = []
+    workspaces: list[str] = []
+    in_trust = False
+    in_packs = False
+    in_workspaces = False
+    for line in fm_lines:
+        stripped = line.lstrip()
+        indent = len(line) - len(stripped)
+        if indent == 0 and stripped.endswith(":"):
+            key = stripped[:-1]
+            in_trust = key == "trust"
+            in_packs = key == "packs"
+            in_workspaces = key == "workspaces"
+            continue
+        if in_trust and stripped.startswith("level:"):
+            level = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+        elif in_trust and stripped.startswith("human_review_required:"):
+            val = stripped.split(":", 1)[1].strip()
+            hrr = val.lower() == "true"
+        elif in_packs or in_workspaces:
+            m = _FM_PLAIN_LIST_RE.match(line)
+            if m:
+                value = m.group(2).strip()
+                (packs if in_packs else workspaces).append(value)
+    owner = "unknown"
+    if packs:
+        owner = packs[0].split("-")[0]
+    elif workspaces:
+        owner = workspaces[0]
+    return level, hrr, owner
+
+
+def _inject_hrr_banner(body: str, level: str, owner: str) -> str:
+    """Prepend the HUMAN_REVIEW banner block to `body`. Idempotent — a
+    body that already carries `_HRR_BANNER_MARKER` is returned unchanged.
+    """
+    if _HRR_BANNER_MARKER in body:
+        return body
+    banner = (
+        f"{_HRR_BANNER_MARKER}\n"
+        f"> HUMAN REVIEW REQUIRED · trust: {level} · owner: {owner}\n\n"
+    )
+    return banner + body.lstrip("\n")
+
+
 def _rewrite_paths(content: str, source_relative_path: str) -> str:
     """Rewrite logical / legacy paths in `content` for a file shipped at
     `.agent-src/{source_relative_path}`. Idempotent.
 
     See module-level comment above for the full pattern catalog.
+    Also injects the HUMAN_REVIEW banner when the source frontmatter
+    sets `trust.human_review_required: true` (Phase 5.3 / ADR-018).
     """
     prefix = _depth_prefix(source_relative_path)
     fm_lines, body = _split_frontmatter(content)
@@ -524,6 +635,9 @@ def _rewrite_paths(content: str, source_relative_path: str) -> str:
     if fm_lines is None:
         return body
     new_fm = _rewrite_frontmatter_lines(fm_lines, prefix)
+    level, hrr, owner = _parse_trust_and_owner(fm_lines)
+    if hrr and level:
+        body = _inject_hrr_banner(body, level, owner)
     return "---\n" + "\n".join(new_fm) + "\n---\n" + body
 
 
@@ -1096,8 +1210,11 @@ def clean_tools() -> None:
 
 
 def main() -> None:
-    if not SOURCE_DIR.exists():
-        print(f"❌  Source directory not found: {SOURCE_DIR}")
+    # Multi-root awareness (ADR-017): tolerate a missing legacy
+    # `.agent-src.uncompressed/` as long as at least one package-scoped
+    # source root carries artefacts.
+    if not SOURCE_DIR.exists() and not _any_source_root_exists():
+        print(f"❌  No source directory found (looked at {SOURCE_DIR} and packages/*/.agent-src.uncompressed)")
         sys.exit(1)
 
     arg = sys.argv[1] if len(sys.argv) > 1 else "--sync"
@@ -1149,9 +1266,10 @@ def main() -> None:
         copied = sync_non_md(SOURCE_DIR, TARGET_DIR)
         print(f"\n--- Cleanup stale files ---")
         deleted = cleanup_stale(SOURCE_DIR, TARGET_DIR)
-        # Also cleanup stale hashes
+        # Also cleanup stale hashes (multi-root aware — resolve against
+        # every artefact root, not just the legacy SOURCE_DIR).
         hashes = load_hashes()
-        stale_keys = [k for k in hashes if not (SOURCE_DIR / k).exists()]
+        stale_keys = [k for k in hashes if _resolve_source(k) is None]
         for k in stale_keys:
             del hashes[k]
         if stale_keys:

package/scripts/config/presets.py

@@ -93,7 +93,25 @@ def _load_yaml(path: Path) -> dict[str, Any]:
 
 
 def _preset_file(project_root: Path, preset_id: str) -> Path:
-    return project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+    # Legacy single-root layout — honor when present so tests that mock a
+    # ``.agent-src.uncompressed/`` sub-tree under ``project_root`` keep working.
+    legacy = project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+    if legacy.exists():
+        return legacy
+    # Monorepo layout — scan every package root via the agent_src helper.
+    try:
+        import sys as _sys
+        scripts_root = Path(__file__).resolve().parents[1]
+        if str(scripts_root) not in _sys.path:
+            _sys.path.insert(0, str(scripts_root))
+        from _lib.agent_src import artefact_roots  # type: ignore
+    except Exception:
+        return legacy
+    for root in artefact_roots():
+        candidate = root / "presets" / f"{preset_id}.yml"
+        if candidate.exists():
+            return candidate
+    return legacy
 
 
 def _coerce_scalar(raw: str) -> Any:

package/scripts/config/profiles.py

@@ -89,7 +89,22 @@ def _load_yaml(path: Path) -> dict[str, Any]:
 
 
 def _profile_file(project_root: Path, profile_id: str) -> Path:
-    return project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+    legacy = project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+    if legacy.exists():
+        return legacy
+    try:
+        import sys as _sys
+        scripts_root = Path(__file__).resolve().parents[1]
+        if str(scripts_root) not in _sys.path:
+            _sys.path.insert(0, str(scripts_root))
+        from _lib.agent_src import artefact_roots  # type: ignore
+    except Exception:
+        return legacy
+    for root in artefact_roots():
+        candidate = root / "profiles" / f"{profile_id}.yml"
+        if candidate.exists():
+            return candidate
+    return legacy
 
 
 def _build_resolved(

package/scripts/context_hygiene_hook.py

@@ -6,7 +6,7 @@ freshness threshold, the 3-failure stop, and tool-loop detection. The
 agent's job shrinks from "remember three counters" to "read this file
 before responding".
 
-Output: `agents/state/context-hygiene.json`
+Output: `agents/runtime/state/context-hygiene.json`
   {
     "tool_calls": <int>,                 // running PostToolUse count
     "consecutive_same_tool": <int>,      // includes the latest call
@@ -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

package/scripts/council_cli.py

@@ -24,15 +24,15 @@ import yaml
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
-AI_COUNCIL_FILE = REPO_ROOT / "agents" / ".ai-council.yml"
+AI_COUNCIL_FILE = REPO_ROOT / "agents" / "settings" / ".ai-council.yml"
 
 # Canonical output dirs per ai-council § "Output path convention".
 # Enforced at write-time by `_validate_council_output_path` so shell-side
 # `>` redirects and forgetful agents can't strand artefacts at agents/ root.
 COUNCIL_CANONICAL_DIRS: dict[str, str] = {
-    "responses": "agents/council-responses",
-    "sessions":  "agents/council-sessions",
-    "questions": "agents/council-questions",
+    "responses": "agents/runtime/council/responses",
+    "sessions":  "agents/runtime/council/sessions",
+    "questions": "agents/runtime/council/questions",
 }
 
 
@@ -139,7 +139,7 @@ def load_settings(
     ``load_agent_settings``. ``ai_council.*`` keys are not whitelisted,
     so the project file remains authoritative for council config.
 
-    Step-2 council-redesign overlay: when ``agents/.ai-council.yml``
+    Step-2 council-redesign overlay: when ``agents/settings/.ai-council.yml``
     exists it is the single source of truth — the validated config is
     synthesized back into ``settings['ai_council']`` and wins over any
     legacy block in ``.agent-settings.yml``. The pre-2 path stays alive
@@ -478,7 +478,7 @@ def _construct_api_member(
     """Build an api-mode client for a known provider name.
 
     ``api_key_ref`` carries the validated ``file:<path>`` / ``env:<VAR>``
-    reference from ``agents/.ai-council.yml`` and is resolved lazily here
+    reference from ``agents/settings/.ai-council.yml`` and is resolved lazily here
     so the council does not require keys for disabled providers. When
     ``api_key_ref`` is ``None`` (no new config yet, or legacy code path),
     fall back to the per-provider loaders so the pre-step-2
@@ -500,7 +500,7 @@ def _construct_api_member(
     if name == "gemini":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'gemini' requires api_key_ref in agents/.ai-council.yml "
+                "member 'gemini' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:GEMINI_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.gemini")
@@ -508,7 +508,7 @@ def _construct_api_member(
     if name == "xai":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'xai' requires api_key_ref in agents/.ai-council.yml "
+                "member 'xai' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:XAI_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.xai")
@@ -516,7 +516,7 @@ def _construct_api_member(
     if name == "perplexity":
         if not api_key_ref:
             raise CouncilDisabledError(
-                "member 'perplexity' requires api_key_ref in agents/.ai-council.yml "
+                "member 'perplexity' requires api_key_ref in agents/settings/.ai-council.yml "
                 "(e.g. `env:PERPLEXITY_API_KEY`) — no legacy fallback."
             )
         api_key = resolve_api_key(api_key_ref, scope="ai_council.members.perplexity")
@@ -794,7 +794,7 @@ def _peer_review_active(ai_cfg: dict[str, Any], args: argparse.Namespace) -> boo
     Resolution chain (highest priority first):
       1. ``--peer-review`` CLI flag — explicit opt-in.
       2. ``ai_council.peer_review.enabled: true`` in
-         ``agents/.ai-council.yml`` — opt-in via config.
+         ``agents/settings/.ai-council.yml`` — opt-in via config.
     Both default to false; peer-review is opt-in by R2 verdict.
     """
     if getattr(args, "peer_review", False):
@@ -1037,7 +1037,7 @@ def _emit_debate_estimate(
     if requested > max_rounds_cap:
         raise argparse.ArgumentTypeError(
             f"--rounds={requested} exceeds debate_max_rounds={max_rounds_cap}; "
-            f"raise the cap in agents/.ai-council.yml or lower --rounds."
+            f"raise the cap in agents/settings/.ai-council.yml or lower --rounds."
         )
     rounds = requested
     per_round_usd = sum(e.total_usd for e in estimates)
@@ -1424,7 +1424,7 @@ def _debate_refusal_cap(
 def _emit_shadow_slo_banner() -> None:
     """Pre-flight SLO banner for solo-dispatch invocations (step-9 P10).
 
-    Reads ``agents/council-shadow-log.jsonl`` and prints the 7-day rolling
+    Reads ``agents/runtime/council/shadow-log.jsonl`` and prints the 7-day rolling
     disagreement rate. ``OK``, ``WARN``, ``BREACH`` are all surfaced so the
     user can see when single-member quality is drifting. Never auto-flips
     back to full council \u2014 visibility-first, action-second (D10).
@@ -1444,7 +1444,7 @@ def _apply_solo_dispatch(
 ) -> tuple[list[ExternalAIClient], str | None]:
     """Filter ``members`` to a single solo-dispatch pick (step-9 P9).
 
-    Loads the routing chain from ``agents/.ai-council.yml`` and asks
+    Loads the routing chain from ``agents/settings/.ai-council.yml`` and asks
     :func:`select_solo_member` for the first chain entry whose member
     is runtime-present. The probe is conservative: a member counts as
     auth-valid iff ``build_members`` returned a runtime client for it
@@ -1596,7 +1596,7 @@ def cmd_run(
     # Phase 8 step 5 — opt-in cost disclosure for non-debate lenses.
     # Default mode is "off" for analysis / default (cheap enough that
     # the disclosure is friction); users opt in by setting
-    # `lenses.<name>.cost_disclosure.mode` in agents/.ai-council.yml.
+    # `lenses.<name>.cost_disclosure.mode` in agents/settings/.ai-council.yml.
     disc_mode, disc_threshold, disc_show = _resolve_cost_disclosure(
         ai_cfg, question.mode,
     )
@@ -1885,7 +1885,7 @@ def cmd_debate(
     if requested > max_rounds_cap:
         raise argparse.ArgumentTypeError(
             f"--rounds={requested} exceeds debate_max_rounds={max_rounds_cap}; "
-            f"raise the cap in agents/.ai-council.yml or lower --rounds."
+            f"raise the cap in agents/settings/.ai-council.yml or lower --rounds."
         )
     rounds = requested
 
@@ -1942,7 +1942,7 @@ def cmd_debate(
             f"❌  council:debate refused · high-end estimate "
             f"${debate_estimate.high_usd:.4f} exceeds "
             f"debate.max_cost_usd=${cap:.2f}. Lower --rounds, drop "
-            f"members, or raise the cap in agents/.ai-council.yml.\n"
+            f"members, or raise the cap in agents/settings/.ai-council.yml.\n"
         )
         return 4
 
@@ -2037,7 +2037,7 @@ def cmd_render(args: argparse.Namespace) -> int:
     Lens resolution order: explicit ``--prompt-mode`` > ``prompt_mode``
     in the payload > ``mode`` in the payload > ``None`` (default decision
     template). R4 Q4 escape hatch ``--prose-synthesis`` overrides the
-    table. ``--output`` writes to ``agents/council-sessions/`` (enforced);
+    table. ``--output`` writes to ``agents/runtime/council/sessions/`` (enforced);
     omit it for stdout.
     """
     payload = json.loads(Path(args.responses).read_text(encoding="utf-8"))
@@ -2258,7 +2258,7 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                         "(anonymised) responses for blind spots before "
                         "synthesis. Adds N extra API calls. Opt-in per the "
                         "R2 verdict; also accepts ai_council.peer_review."
-                        "enabled: true in agents/.ai-council.yml.")
+                        "enabled: true in agents/settings/.ai-council.yml.")
 
 
 def cmd_shadow_report(args: argparse.Namespace) -> int:
@@ -2405,7 +2405,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Required to actually start the debate.")
     p_deb.add_argument("--rounds", type=int, default=None,
                        help="Number of debate rounds (default 2). Capped by "
-                            "ai_council.debate_max_rounds in agents/.ai-council.yml.")
+                            "ai_council.debate_max_rounds in agents/settings/.ai-council.yml.")
     p_deb.add_argument("--auto-continue", action="store_true",
                        default=False, dest="auto_continue",
                        help="Skip the between-round y/N prompt. The hard cap "
@@ -2441,7 +2441,7 @@ def build_parser() -> argparse.ArgumentParser:
                             "to the `mode` recorded in the responses JSON.")
     p_ren.add_argument("--output", default=None,
                        help="Write the rendered markdown to a file under "
-                            "agents/council-sessions/ (enforced). Omit for "
+                            "agents/runtime/council/sessions/ (enforced). Omit for "
                             "stdout. Prefer this over shell redirects so "
                             "the canonical-path check fires at write-time.")
     _add_prose_synthesis_arg(p_ren)
@@ -2483,12 +2483,12 @@ def build_parser() -> argparse.ArgumentParser:
 
     p_sha = sub.add_parser(
         "shadow-report",
-        help="Read agents/council-shadow-log.jsonl and print the 7-day "
+        help="Read agents/runtime/council/shadow-log.jsonl and print the 7-day "
              "rolling disagreement rate + SLO status (step-9 P10).",
     )
     p_sha.add_argument("--log", default=None,
                        help="Path to the shadow log (default: "
-                            "agents/council-shadow-log.jsonl).")
+                            "agents/runtime/council/shadow-log.jsonl).")
     p_sha.add_argument("--window-days", type=int, default=7,
                        help="Rolling window in days (default: 7).")
 

package/scripts/council_prune.py

@@ -4,9 +4,9 @@
 Deletes council files older than `ai_council.session_retention_days`
 (default 7) across all four artefact directories:
 
-  - agents/council-sessions/   (timestamp subdirs + root files)
-  - agents/council-questions/  (mtime-based)
-  - agents/council-responses/  (mtime-based)
+  - agents/runtime/council/sessions/   (timestamp subdirs + root files)
+  - agents/runtime/council/questions/  (mtime-based)
+  - agents/runtime/council/responses/  (mtime-based)
 
 Same logic as the auto-prune that runs on every `council save()`,
 exposed as a Task target so the user can sweep on demand.