@event4u/agent-config 6.0.0 → 6.1.0

package/src/scripts/_lib/global_deploy_inventory.py

@@ -136,11 +136,18 @@ def reap_stale(
     anchor: Path,
     current_files: set[str],
     inventory: dict,
+    dry_run: bool = False,
 ) -> list[Path]:
     """Delete previously-deployed files that the current deploy dropped.
 
     Returns the absolute paths actually deleted. Mutates nothing in
     ``inventory`` — callers record the new state via :func:`record_deploy`.
+
+    ``dry_run=True`` computes and returns the would-delete set (only paths
+    that currently exist on disk) WITHOUT unlinking anything or pruning
+    empty directories — the preview surface for ``install.py --dry-run``.
+    The selection logic (orphan diff, containment proof, directory guard)
+    is identical to the live path, so the preview is exact.
     """
     entry = inventory.get("tools", {}).get(tool_id)
     if not isinstance(entry, dict):
@@ -169,6 +176,11 @@ def reap_stale(
             continue
         if target.is_dir() and not target.is_symlink():
             continue  # never delete directories
+        if dry_run:
+            # Preview: report only what is actually on disk and would go.
+            if target.exists() or target.is_symlink():
+                deleted.append(target)
+            continue
         try:
             target.unlink()
         except FileNotFoundError:
@@ -191,26 +203,41 @@ def reap_stale(
     return deleted
 
 
-def bootstrap_reap_tagged(
+def reap_tagged_orphans(
     anchor: Path,
     dest_subs: list[str],
     current_files: set[str],
     package_tag: str,
+    dry_run: bool = False,
 ) -> list[Path]:
-    """First-run reaping for PRE-inventory installs (marker-based ownership).
-
-    Existing installs in the wild predate the inventory sidecar, so
-    :func:`reap_stale` has nothing to diff against on the first upgraded
-    deploy — the legacy mess (renamed skills, retired command-as-skill
-    entries, the 2026-05-13 colon-named shapes) would rot forever. Every
-    deployed ``.md`` however carries the injected ``package:`` frontmatter
-    tag (install P5.1), which is exactly the ownership proof reaping needs.
+    """Marker-based reaping of package-tagged orphans — runs EVERY deploy.
+
+    This is the self-healing reaping path, complementary to
+    :func:`reap_stale` (which can only diff against the *previous*
+    inventory). It is the **only** path with ownership proof independent
+    of inventory history: every deployed ``.md`` carries the injected
+    ``package:`` frontmatter tag (install P5.1), so a tagged file absent
+    from the current bundle is provably our orphan regardless of whether
+    any inventory ever recorded it.
+
+    Why it must run every deploy, not just on first-run: an install that
+    predates the inventory sidecar never recorded its files, so once a
+    tool *does* get an inventory entry, :func:`reap_stale` has no record
+    of those legacy files to diff against — they would rot forever (the
+    renamed skills, retired command-as-skill entries, 2026-05-13
+    colon-named shapes, and post-6.0.0 command renames like
+    ``create-pr`` → ``pr/create``). Running this sweep unconditionally
+    closes that gap; it is idempotent (a clean tree yields no deletions).
 
     Deletes ``.md`` files under ``<anchor>/<dest_sub>`` that (a) carry
     ``package: <package_tag>`` in their frontmatter and (b) are not in the
     current expected file set; then prunes empty directories. Untagged
     files (user-authored skills in shared anchors) are never touched.
     Returns the absolute paths deleted.
+
+    ``dry_run=True`` returns the would-delete set (tagged orphans actually
+    present on disk) WITHOUT unlinking or pruning — the preview surface for
+    ``install.py --dry-run``. Selection logic is identical to the live path.
     """
     anchor_resolved = anchor.expanduser().resolve()
     deleted: list[Path] = []
@@ -242,6 +269,9 @@ def bootstrap_reap_tagged(
                 line.strip() == needle for line in block.splitlines()
             ):
                 continue
+            if dry_run:
+                deleted.append(md)
+                continue
             try:
                 md.unlink()
             except OSError:

package/src/scripts/_lib/link_crypto.py

@@ -0,0 +1,206 @@
+"""link_crypto — encrypt/decrypt stored third-party package links.
+
+Why this exists
+---------------
+This package never stores a *readable* link to, or name of, an external
+source that inspired an idea (see the source-confidentiality sweep). Where a
+source link genuinely has to be retained — e.g. the upstream URL + pin in
+``agents/settings/contexts/skills-provenance.yml`` for license / refresh
+bookkeeping — it is stored **encrypted**, never in plaintext.
+
+Key resolution (per the maintainer's contract)
+----------------------------------------------
+The symmetric key lives in ``.agent-settings.yml`` under
+``secrets.link_encryption_key`` and is **never committed** (the file is
+gitignored). It is read in this order:
+
+  1. **Project** — ``<project-root>/.agent-settings.yml``.
+  2. **User-global** — ``~/.event4u/agent-config/agent-settings.yml``
+     (with the legacy-path fallback used by the rest of the suite).
+
+``encrypt`` uses the first key it finds (project preferred). ``decrypt`` tries
+the project key first and, only if that fails to authenticate, falls back to
+the user-global key — matching "try the project key, if it doesn't work use
+the global one".
+
+Threat model
+------------
+The goal is **repo confidentiality**: someone browsing the committed tree (or
+the published npm tarball / plugin mirror) must not be able to read which
+external packages were used. It is authenticated symmetric encryption built
+from the Python standard library only (PBKDF2-HMAC-SHA256 key derivation, an
+HMAC-SHA256 counter-mode keystream, encrypt-then-MAC with HMAC-SHA256). No
+third-party crypto dependency is added (scope-control). This is not intended
+to withstand an offline attacker who already holds the key file.
+
+Token format
+------------
+``ENC1:<base64( salt[16] || nonce[16] || ciphertext || tag[32] )>``
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+import re
+import secrets
+import sys
+from pathlib import Path
+
+MAGIC = "ENC1"
+_SALT_LEN = 16
+_NONCE_LEN = 16
+_TAG_LEN = 32
+_PBKDF2_ITERS = 200_000
+_KEY_PATH = "secrets.link_encryption_key"
+_USER_GLOBAL = Path.home() / ".event4u" / "agent-config" / "agent-settings.yml"
+# Legacy user-global location kept readable for older installs.
+_USER_GLOBAL_LEGACY = Path.home() / ".agent-config" / "agent-settings.yml"
+
+
+# --------------------------------------------------------------------------- #
+# Core crypto (stdlib only)
+# --------------------------------------------------------------------------- #
+def _derive(key: str, salt: bytes) -> tuple[bytes, bytes]:
+    dk = hashlib.pbkdf2_hmac("sha256", key.encode("utf-8"), salt, _PBKDF2_ITERS, dklen=64)
+    return dk[:32], dk[32:]  # (enc_key, mac_key)
+
+
+def _keystream(enc_key: bytes, nonce: bytes, n: int) -> bytes:
+    out = bytearray()
+    counter = 0
+    while len(out) < n:
+        out += hmac.new(enc_key, nonce + counter.to_bytes(8, "big"), hashlib.sha256).digest()
+        counter += 1
+    return bytes(out[:n])
+
+
+def encrypt(plaintext: str, key: str) -> str:
+    """Encrypt ``plaintext`` with ``key`` → an ``ENC1:`` token."""
+    if not key:
+        raise ValueError("empty encryption key")
+    salt = secrets.token_bytes(_SALT_LEN)
+    nonce = secrets.token_bytes(_NONCE_LEN)
+    enc_key, mac_key = _derive(key, salt)
+    pt = plaintext.encode("utf-8")
+    ct = bytes(a ^ b for a, b in zip(pt, _keystream(enc_key, nonce, len(pt))))
+    tag = hmac.new(mac_key, salt + nonce + ct, hashlib.sha256).digest()
+    return f"{MAGIC}:" + base64.b64encode(salt + nonce + ct + tag).decode("ascii")
+
+
+def is_token(value: str) -> bool:
+    return isinstance(value, str) and value.startswith(f"{MAGIC}:")
+
+
+def _decrypt_one(token: str, key: str) -> str:
+    raw = base64.b64decode(token[len(MAGIC) + 1:])
+    salt, nonce, rest = raw[:_SALT_LEN], raw[_SALT_LEN:_SALT_LEN + _NONCE_LEN], raw[_SALT_LEN + _NONCE_LEN:]
+    ct, tag = rest[:-_TAG_LEN], rest[-_TAG_LEN:]
+    enc_key, mac_key = _derive(key, salt)
+    expected = hmac.new(mac_key, salt + nonce + ct, hashlib.sha256).digest()
+    if not hmac.compare_digest(expected, tag):
+        raise ValueError("authentication failed (wrong key or corrupt token)")
+    return bytes(a ^ b for a, b in zip(ct, _keystream(enc_key, nonce, len(ct)))).decode("utf-8")
+
+
+def decrypt(token: str, keys: str | list[str]) -> str:
+    """Decrypt ``token``, trying each key in order (project first, then global)."""
+    if not is_token(token):
+        raise ValueError("not an ENC1 token")
+    candidates = [keys] if isinstance(keys, str) else list(keys)
+    candidates = [k for k in candidates if k]
+    if not candidates:
+        raise ValueError("no decryption key available")
+    last: Exception | None = None
+    for k in candidates:
+        try:
+            return _decrypt_one(token, k)
+        except Exception as exc:  # noqa: BLE001 — try next key
+            last = exc
+    raise ValueError(f"decryption failed with all configured keys: {last}")
+
+
+# --------------------------------------------------------------------------- #
+# Key resolution from .agent-settings.yml (project → user-global)
+# --------------------------------------------------------------------------- #
+def _read_key_from(path: Path | None) -> str | None:
+    if not path or not path.is_file():
+        return None
+    # Minimal, dependency-free scalar read so this works even where PyYAML is
+    # absent. Matches `link_encryption_key:` at any indentation.
+    pat = re.compile(r'^\s*link_encryption_key:\s*["\']?([^"\'#\s]+)')
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        m = pat.match(line)
+        if m:
+            return m.group(1)
+    return None
+
+
+def project_key(project_root: Path | str | None = None) -> str | None:
+    root = Path(project_root) if project_root else Path.cwd()
+    return _read_key_from(root / ".agent-settings.yml")
+
+
+def global_key() -> str | None:
+    return _read_key_from(_USER_GLOBAL) or _read_key_from(_USER_GLOBAL_LEGACY)
+
+
+def resolve_keys(project_root: Path | str | None = None) -> list[str]:
+    """Ordered, de-duplicated key list: project first, then user-global.
+
+    An ``EVENT4U_LINK_KEY`` environment variable, if set, is consulted last as
+    a CI/automation escape hatch.
+    """
+    keys: list[str] = []
+    for k in (project_key(project_root), global_key(), os.environ.get("EVENT4U_LINK_KEY")):
+        if k and k not in keys:
+            keys.append(k)
+    return keys
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+def _cli(argv: list[str]) -> int:
+    import argparse
+
+    p = argparse.ArgumentParser(prog="link_crypto", description=__doc__.split("\n", 1)[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    pe = sub.add_parser("encrypt", help="encrypt a plaintext value (reads stdin if no --value)")
+    pe.add_argument("--value")
+    pd = sub.add_parser("decrypt", help="decrypt an ENC1 token (reads stdin if no --value)")
+    pd.add_argument("--value")
+    sub.add_parser("keygen", help="generate a fresh base64 key for .agent-settings.yml")
+    sub.add_parser("keystatus", help="report which key sources resolve (no secrets printed)")
+    args = p.parse_args(argv)
+
+    if args.cmd == "keygen":
+        print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode("ascii").rstrip("="))
+        return 0
+
+    if args.cmd == "keystatus":
+        print(f"project key: {'present' if project_key() else 'absent'}")
+        print(f"user-global key: {'present' if global_key() else 'absent'}")
+        print(f"env EVENT4U_LINK_KEY: {'present' if os.environ.get('EVENT4U_LINK_KEY') else 'absent'}")
+        print(f"resolved key count: {len(resolve_keys())}")
+        return 0
+
+    value = args.value if args.value is not None else sys.stdin.read().strip()
+    keys = resolve_keys()
+    if not keys:
+        sys.stderr.write(
+            "error: no link_encryption_key found in project or user-global "
+            ".agent-settings.yml (secrets.link_encryption_key)\n"
+        )
+        return 2
+    if args.cmd == "encrypt":
+        print(encrypt(value, keys[0]))
+    else:
+        print(decrypt(value, keys))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli(sys.argv[1:]))

package/src/scripts/_lib/security_lint.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Shared helpers for the agent-security corpus linters (road-to-security-pillar.md P1).
+
+Implements the **false-positive containment convention** (P1.5) so the
+self-audit linters can scan a corpus that legitimately *contains* attack
+strings as teaching material, without the allowlist-growth death-spiral:
+
+1. **Fenced-block exemption** — content inside a ```` ```security-example ````
+   fence is skipped by every check. Grep-auditable, scoped to the block.
+2. **Confidence weighting** — a match in a doc / example / template / evals
+   file scores at 0.25x; below the FAIL threshold it is a WARN, not an error.
+3. **Per-file pragma** — ``<!-- security-lint: allow <check> "<reason>" -->``
+   anywhere in the file suppresses one check for that file. Reasons are
+   mandatory and counted; crossing PRAGMA_CAP entries repo-wide means the
+   linter is wrong (escalate per autonomous-execution), not "add another".
+
+There is **no global allowlist** — that is the rejected pattern.
+
+The module is import-only (no side effects). Each linter builds its findings
+with :func:`scan` + the predicates here, then calls :func:`report`.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# repo root, resolved from src/scripts/_lib/security_lint.py
+ROOT = Path(__file__).resolve().parents[3]
+
+PRAGMA_CAP = 20
+EXAMPLE_FENCE_LANG = "security-example"
+
+# Shown in every linter's --help (P1.5 reference obligation).
+GUIDELINE = "docs/guidelines/agent-infra/security-lint-containment.md"
+GUIDELINE_EPILOG = (
+    "False-positive containment (fenced security-example block, confidence "
+    "weighting, per-file `security-lint: allow` pragma — no global allowlist): "
+    f"see {GUIDELINE}."
+)
+
+# Source-of-truth roots scanned by the self-audit linters.
+DEFAULT_SCAN_ROOTS = ("src/skills", "src/rules", "src/agent-src", "src/domains")
+
+# A path is "example/teaching" (0.25x weight) when it lives under docs/ or
+# evals/, or its name marks it as an example/template/fixture.
+_EXAMPLE_PATH = re.compile(
+    r"(^|/)(docs|evals|tests?|fixtures?)(/|$)|example|template|sample|/_template",
+    re.IGNORECASE,
+)
+
+_PRAGMA = re.compile(
+    r"<!--\s*security-lint:\s*allow\s+(?P<check>[\w-]+)\s+"
+    r"\"(?P<reason>[^\"]+)\"\s*-->"
+)
+
+_FENCE = re.compile(r"^(\s*)(`{3,}|~{3,})\s*([\w-]*)\s*$")
+
+SEVERITY_RANK = {"LOW": 1, "MED": 2, "HIGH": 3}
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One linter hit. ``weight`` is the confidence multiplier (1.0 or 0.25)."""
+
+    path: str          # repo-relative
+    line: int          # 1-based; 0 = file-level
+    check: str         # stable check id, also the pragma key
+    severity: str      # HIGH | MED | LOW
+    message: str
+    weight: float = 1.0
+
+    @property
+    def is_fail(self) -> bool:
+        """A HIGH-severity, full-weight finding fails the build."""
+        return self.severity == "HIGH" and self.weight >= 1.0
+
+
+def is_example_path(rel_path: str) -> bool:
+    return bool(_EXAMPLE_PATH.search(rel_path))
+
+
+def path_weight(rel_path: str) -> float:
+    return 0.25 if is_example_path(rel_path) else 1.0
+
+
+@dataclass
+class ScannedFile:
+    """A file pre-split into lines with a fence/pragma mask the linters reuse."""
+
+    path: Path
+    rel: str
+    lines: list[str]
+    # per-line flags (1-based index → flag); index 0 unused
+    in_example_fence: list[bool]
+    in_any_fence: list[bool]
+    pragmas: dict[str, str]          # check id → reason (first 15 lines)
+    weight: float
+
+    def pragma_allows(self, check: str) -> bool:
+        return check in self.pragmas
+
+    def iter_lines(self, *, skip_example_fence: bool = True,
+                   skip_any_fence: bool = False):
+        """Yield (lineno, text) honouring the fence masks."""
+        for i, text in enumerate(self.lines, start=1):
+            if skip_example_fence and self.in_example_fence[i]:
+                continue
+            if skip_any_fence and self.in_any_fence[i]:
+                continue
+            yield i, text
+
+
+def scan_file(path: Path) -> ScannedFile:
+    if path.is_absolute():
+        try:
+            rel = path.relative_to(ROOT).as_posix()
+        except ValueError:
+            rel = path.name  # outside the package root (e.g. a consumer-config audit)
+    else:
+        rel = path.as_posix()
+    raw = path.read_text(encoding="utf-8", errors="surrogatepass")
+    lines = raw.splitlines()
+    n = len(lines)
+    in_example = [False] * (n + 1)
+    in_any = [False] * (n + 1)
+
+    fence_open = False
+    fence_marker = ""
+    fence_is_example = False
+    for i, text in enumerate(lines, start=1):
+        m = _FENCE.match(text)
+        if m and not fence_open:
+            fence_open = True
+            fence_marker = m.group(2)[0]
+            fence_is_example = m.group(3) == EXAMPLE_FENCE_LANG
+            in_any[i] = True
+            in_example[i] = fence_is_example
+            continue
+        if fence_open:
+            in_any[i] = True
+            in_example[i] = fence_is_example
+            # closing fence: same marker char, 3+ long, no info string
+            cm = _FENCE.match(text)
+            if cm and cm.group(2)[0] == fence_marker and cm.group(3) == "":
+                fence_open = False
+                fence_is_example = False
+
+    # Pragmas are explicit, grep-auditable opt-out markers — honour them
+    # anywhere in the file (a long frontmatter can push the body past line 15).
+    pragmas: dict[str, str] = {}
+    for text in lines:
+        for m in _PRAGMA.finditer(text):
+            pragmas[m.group("check")] = m.group("reason")
+
+    return ScannedFile(
+        path=path,
+        rel=rel,
+        lines=lines,
+        in_example_fence=in_example,
+        in_any_fence=in_any,
+        pragmas=pragmas,
+        weight=path_weight(rel),
+    )
+
+
+def scan_path(path: Path, base: Path) -> ScannedFile:
+    """scan_file, but compute ``rel`` relative to an arbitrary ``base`` root.
+
+    Used by the consumer-facing audit (P3.1) to scan a target repo's config
+    instead of this package's ``src/``.
+    """
+    sf = scan_file(path)
+    try:
+        rel = path.resolve().relative_to(base.resolve()).as_posix()
+    except ValueError:
+        rel = path.name
+    return ScannedFile(
+        path=sf.path, rel=rel, lines=sf.lines,
+        in_example_fence=sf.in_example_fence, in_any_fence=sf.in_any_fence,
+        pragmas=sf.pragmas, weight=path_weight(rel),
+    )
+
+
+def iter_corpus(roots=DEFAULT_SCAN_ROOTS, exts=(".md",)):
+    """Yield ScannedFile for every matching file under the given roots."""
+    for root in roots:
+        base = ROOT / root
+        if not base.exists():
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_file() and path.suffix in exts:
+                yield scan_file(path)
+
+
+def report(findings: list[Finding], *, check_label: str) -> int:
+    """Print findings grouped by severity; return an exit code.
+
+    Exit 1 iff at least one finding ``is_fail`` (HIGH + full weight). WARN-level
+    (weighted-down or < HIGH) findings print but never fail the build.
+    """
+    if not findings:
+        print(f"✅  {check_label}: clean ({_corpus_note()}).")
+        return 0
+
+    fails = [f for f in findings if f.is_fail]
+    warns = [f for f in findings if not f.is_fail]
+
+    for f in sorted(findings, key=lambda x: (-SEVERITY_RANK.get(x.severity, 0), x.path, x.line)):
+        glyph = "\U0001f534" if f.is_fail else "⚠️"
+        loc = f"{f.path}:{f.line}" if f.line else f.path
+        wnote = "" if f.weight >= 1.0 else f" (weight {f.weight:g})"
+        print(f"  {glyph} [{f.severity}] {f.check} — {loc}{wnote}: {f.message}")
+
+    print()
+    if fails:
+        print(
+            f"❌  {check_label}: {len(fails)} blocking finding(s), "
+            f"{len(warns)} warning(s). Fix, or mark a true teaching example with a "
+            f"```{EXAMPLE_FENCE_LANG} fence or a `security-lint: allow` pragma."
+        )
+        return 1
+    print(f"⚠️  {check_label}: {len(warns)} warning(s), 0 blocking.")
+    return 0
+
+
+def _corpus_note() -> str:
+    return "scanned " + ", ".join(DEFAULT_SCAN_ROOTS)

package/src/scripts/ai_council/clients.py

@@ -324,7 +324,7 @@ class GeminiClient(ExternalAIClient):
         if api_key is None:
             raise RuntimeError(
                 "GeminiClient requires explicit api_key or injected client. "
-                "Use `api_key_ref: env:GEMINI_API_KEY` in agents/settings/.ai-council.yml."
+                "Use `api_key_ref: env:GEMINI_API_KEY` in ~/.event4u/agent-config/settings/.ai-council.yml."
             )
         try:
             from google import genai  # type: ignore[import-not-found]
@@ -658,7 +658,7 @@ class CliClient(ExternalAIClient):
                 raise CliClientError(
                     f"{type(self).__name__}: binary {self.default_binary!r} "
                     f"not found on PATH. Install the provider CLI or set "
-                    f"`members.{self.name}.binary:` in agents/settings/.ai-council.yml."
+                    f"`members.{self.name}.binary:` in ~/.event4u/agent-config/settings/.ai-council.yml."
                 )
             self.binary = resolved
 

package/src/scripts/ai_council/config.py

@@ -456,6 +456,61 @@ class CouncilConfig:
     source_path: Path | None = None
 
 
+#: Dotfile name for the council config in any scope.
+COUNCIL_CONFIG_RELNAME = ".ai-council.yml"
+
+#: User-global location, relative to ``event4u_root()`` — under ``settings/``
+#: alongside the other per-user config (``.agent-settings.yml``,
+#: ``.agent-user.yml``). This is exactly the path the browser setup wizard
+#: reads/writes (``<writeRoot>/settings/.ai-council.yml`` in
+#: ``src/server/routes/wizard.ts``), so a council configured in the wizard is
+#: the same file the CLI reads.
+COUNCIL_CONFIG_USER_GLOBAL_REL = "settings/.ai-council.yml"
+
+#: Env var pinning the council config to an explicit absolute path, ahead
+#: of the project → user-global search. Mirrors ``EVENT4U_CONFIG_HOME`` but
+#: targets the config file itself (tests / power users).
+COUNCIL_CONFIG_ENV = "AI_COUNCIL_CONFIG"
+
+
+def resolve_config_path(project_root: Path, *, env: dict | None = None) -> Path:
+    """Resolve which ``.ai-council.yml`` the council reads.
+
+    Precedence (first match wins):
+
+    1. ``$AI_COUNCIL_CONFIG`` — explicit absolute override (tests / power
+       users). Honoured even when the target is absent, so a typo surfaces
+       as "create it here" instead of a silent fallback.
+    2. Project-local ``<project_root>/agents/settings/.ai-council.yml`` — a
+       consumer project that checks in its own council config.
+    3. User-global ``~/.event4u/agent-config/settings/.ai-council.yml`` (with
+       the legacy ``~/.config/agent-config/`` read-fallback) — the canonical
+       per-user location, configured once for every project the developer
+       works in, and the exact file the setup wizard reads/writes.
+
+    Always returns a ``Path`` (never ``None``): when nothing exists yet it
+    returns the user-global write target, so callers' ``.exists()`` gate and
+    "create it at <path>" messaging both point at the global location.
+    """
+    env_map = env if env is not None else os.environ
+    override = env_map.get(COUNCIL_CONFIG_ENV)
+    if override:
+        return Path(override).expanduser()
+    project_path = (
+        project_root / "agents" / "settings" / COUNCIL_CONFIG_RELNAME
+    )
+    if project_path.exists():
+        return project_path
+    found = user_global_paths.resolve_with_fallback(
+        COUNCIL_CONFIG_USER_GLOBAL_REL, env=env,
+    )
+    if found is not None:
+        return found
+    return user_global_paths.write_target(
+        COUNCIL_CONFIG_USER_GLOBAL_REL, env=env,
+    )
+
+
 def load_council_config(path: Path) -> CouncilConfig:
     """Load and validate the council YAML at ``path``."""
     if not path.exists():

package/src/scripts/audit_adr_coverage.py

@@ -33,8 +33,6 @@ AREAS: dict[str, dict[str, str]] = {
                 "scope":    "router.json shape, tier semantics, dispatch precedence."},
     "smoke":   {"contract": "smoke-contracts.md",
                 "scope":    "Per-tier smoke contracts, baseline locks, regression gates."},
-    "memory":  {"contract": "agent-memory-contract.md",
-                "scope":    "Memory MCP, propose / promote / poison flow, runtime-trust scoring."},
 }
 
 NAMED = re.compile(r"^(\d{4})-([a-z0-9-]+)\.md$")