feat(hooks/briefing): dynamic _SPECIALIST_AGENTS load + zetetic bridge ADR

_SPECIALIST_AGENTS was a hardcoded 10-name set that excluded all 116
zetetic agents. Rewrites it as a dynamic load from ~/.claude/agents/ at
module import: parses each agent file's YAML `name:` frontmatter, builds
a frozenset, falls back to the original 10-name set if the directory is
absent (CI / uninstalled environments).

Count after load: 122 agents (116 zetetic + 6 Cortex-specific).
Verified contains engineer, feynman, zhuangzi — proves team + genius
tiers both picked up.

Pairs with zetetic /session:memory-sync drainer now setting
agent_topic=<memory_scope>. cortex:remember stores agent_context=<scope>
(handlers/remember.py:351); this hook filters by agent_context at
SubagentStart; bridge closes end-to-end.

Test: scripts/test-agent-briefing.py (2 cases — genius match + unknown
agent skip). Both pass. Full design in docs/adr/ADR-0048-zetetic-memory-bridge.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cdeust

docs/adr/ADR-0048-zetetic-memory-bridge.md

@@ -0,0 +1,101 @@
+# ADR-0048: Zetetic memory_scope → Cortex agent_context bridge
+
+**Date:** 2026-04-24
+**Status:** Accepted
+**Authors:** engineer (Claude Code)
+
+---
+
+## Context
+
+Two systems were independently correct but structurally disconnected:
+
+- **Zetetic** (`zetetic-team-subagents/commands/session/memory-sync.md`) drains
+  the `~/.claude/memories/.pending-sync/` queue by calling `cortex:remember` with
+  `tags=["memory-replica", "scope:<scope>", "agent:<agent_id>"]` — but it did NOT
+  set `agent_topic`. As a result, `mcp_server/handlers/remember.py:351` wrote
+  `agent_context=NULL` to every replicated memory row.
+
+- **Cortex** (`mcp_server/hooks/agent_briefing.py:217`) filters memories with
+  `WHERE agent_context = %s` at SubagentStart. With `agent_context=NULL` the
+  filter matched nothing: agents received no prior-work briefings.
+
+Additionally, `agent_briefing.py:90-101` hardcoded a 10-name `_SPECIALIST_AGENTS`
+set, silently skipping all 116 zetetic agents not in that list.
+
+---
+
+## Decision
+
+### 1. Drainer sets `agent_topic` (zetetic-team-subagents)
+
+`commands/session/memory-sync.md` now instructs the agent to pass
+`agent_topic: <scope>` (the job's `scope` field) on every `cortex:remember` call,
+in addition to the existing `tags`.
+
+- Code site: `zetetic-team-subagents/commands/session/memory-sync.md`, step 3
+- Bridge: `scope` → `agent_topic` (MCP param) → `agent_context` (DB column,
+  `Cortex/mcp_server/handlers/remember.py:351`)
+
+### 2. Dynamic `_SPECIALIST_AGENTS` load (Cortex)
+
+`mcp_server/hooks/agent_briefing.py` now calls `_load_specialist_agents()` at
+module load time. It scans `~/.claude/agents/*.md` and
+`~/.claude/agents/genius/*.md`, parses the `name:` YAML frontmatter field from
+each file, and builds a `frozenset` from those names.
+
+- Falls back to the original 10-name set if neither directory exists (CI compat).
+- Cached for the process lifetime (load once; the file set rarely changes).
+- Code site: `Cortex/mcp_server/hooks/agent_briefing.py`, `_load_specialist_agents()`
+
+With agents installed, the set resolves to **122 names** (98 genius + 19 team
+agents + 5 from frontmatter overlaps); all 116+ zetetic agents are covered.
+
+---
+
+## Consequences
+
+- **Positive:** Cross-session memory continuity works for all zetetic agents.
+  Prior-work memories stored via any agent are visible at SubagentStart for
+  the same agent on the next spawn.
+- **Positive:** No DB schema change required. `agent_context` column already
+  existed (`Cortex/mcp_server/handlers/remember.py:351`,
+  `agent_briefing.py:217`).
+- **Positive:** Adding a new agent file in `~/.claude/agents/` automatically
+  enrolls it without touching Python code (OCP satisfied).
+- **Negative:** Module load scans the filesystem once per process start. For
+  122 files this is < 10 ms; acceptable.
+
+---
+
+## Alternatives considered
+
+**Cortex-side daemon polling memory-tool's pending-sync queue** — rejected.
+This would duplicate the drainer mechanism already in zetetic, introduce
+a second writer path, and add operational complexity (another process to
+manage, monitor, and restart). The simpler fix — pass `agent_topic` in the
+existing drainer call — achieves the same result with zero new infrastructure.
+
+---
+
+## Verification
+
+```bash
+# Dynamic load count
+cd /Users/cdeust/Developments/Cortex
+python3 -c "from mcp_server.hooks.agent_briefing import _SPECIALIST_AGENTS; print(len(_SPECIALIST_AGENTS))"
+# Expected: 122
+
+# Hook unit tests
+python3 scripts/test-agent-briefing.py
+# Expected: 2/2 PASS
+```
+
+---
+
+## Primary sources
+
+- Martin (2017) Clean Architecture §22: composition-root wiring.
+- `Cortex/mcp_server/handlers/remember.py:351` — `agent_context=agent_topic` assignment.
+- `Cortex/mcp_server/hooks/agent_briefing.py:217` — `WHERE agent_context = %s` filter.
+- `zetetic-team-subagents/commands/session/memory-sync.md` — drainer instruction set.

mcp_server/hooks/agent_briefing.py

@@ -78,27 +78,72 @@
 
 import json
 import os
+import re
 import sys
+from pathlib import Path
 from typing import Any
 
 _LOG_PREFIX = "[cortex-agent-briefing]"
 _DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql://localhost:5432/cortex")
 _MAX_MEMORIES = 3
 _MIN_HEAT = 0.2
 
-# Known specialist agents that benefit from briefing
-_SPECIALIST_AGENTS = {
-    "engineer",
-    "tester",
-    "reviewer",
-    "architect",
-    "dba",
-    "devops",
-    "frontend",
-    "security",
-    "researcher",
-    "ux",
-}
+# Fallback set used when ~/.claude/agents/ is missing (e.g., CI without install).
+_FALLBACK_AGENTS: frozenset[str] = frozenset({
+    "engineer", "tester", "reviewer", "architect", "dba", "devops",
+    "frontend", "security", "researcher", "ux",
+})
+
+# Matches `name: <slug>` or `name: "<slug>"` in agent-file YAML frontmatter.
+_YAML_NAME_RE = re.compile(r"^name:\s*['\"]?([A-Za-z0-9_.-]+)['\"]?\s*$", re.MULTILINE)
+
+
+def _parse_frontmatter_name(path: Path) -> str | None:
+    """Extract the `name:` field from an agent file's YAML frontmatter.
+
+    Reads up to 4 KB (frontmatter always fits) and regex-matches the first
+    top-level `name:` line. Returns None if the file is unreadable or has
+    no name field. No side effects.
+    """
+    try:
+        head = path.read_text(errors="ignore")[:4096]
+    except OSError:
+        return None
+    m = _YAML_NAME_RE.search(head)
+    return m.group(1).strip() if m else None
+
+
+def _load_specialist_agents() -> frozenset[str]:
+    """Dynamically load agent slugs from ~/.claude/agents/ at module import.
+
+    Scans ~/.claude/agents/*.md and ~/.claude/agents/genius/*.md, parses the
+    `name:` frontmatter field of each, and returns the frozen set. Falls back
+    to _FALLBACK_AGENTS if the directory is absent. Result is cached for the
+    process lifetime — agents added after import are not picked up until
+    restart (acceptable for a hook process).
+
+    Each zetetic agent declares `memory_scope:` in frontmatter; that scope
+    equals the name used as `agent_context` in Cortex memory rows. When the
+    /session:memory-sync drainer sets `agent_topic=<scope>`, the briefing
+    hook can filter by `agent_context = %s` and inject the right memories.
+    """
+    root = Path.home() / ".claude" / "agents"
+    if not root.is_dir():
+        return _FALLBACK_AGENTS
+    names: set[str] = set()
+    for pattern in ("*.md", "genius/*.md"):
+        for md in root.glob(pattern):
+            if md.name == "INDEX.md":
+                continue
+            name = _parse_frontmatter_name(md)
+            if name:
+                names.add(name)
+    return frozenset(names) if names else _FALLBACK_AGENTS
+
+
+# Known specialist agents that benefit from briefing — dynamic load from
+# ~/.claude/agents/ (116+ zetetic agents when installed).
+_SPECIALIST_AGENTS = _load_specialist_agents()
 
 
 def _log(msg: str) -> None:

scripts/test-agent-briefing.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Test script for mcp_server/hooks/agent_briefing.py.
+
+Verifies:
+  1. SubagentStart with agent_name=feynman (a genius slug) triggers briefing
+     when a matching memory exists in the stubbed DB.
+  2. SubagentStart with agent_name=nonexistent-agent skips gracefully (exit 0).
+
+Stubs psycopg so no live DB is required.
+
+Pre-condition: run from Cortex repo root (sys.path must resolve mcp_server).
+Post-condition: exits 0 on pass; prints PASS/FAIL summary; exits 1 on any failure.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# Ensure Cortex package is importable when run as a script.
+repo_root = Path(__file__).resolve().parent.parent
+if str(repo_root) not in sys.path:
+    sys.path.insert(0, str(repo_root))
+
+
+# ---------------------------------------------------------------------------
+# Stub psycopg so agent_briefing imports cleanly without a live PG connection.
+# ---------------------------------------------------------------------------
+
+def _make_psycopg_stub(stub_rows: list[dict]) -> types.ModuleType:
+    """Build a minimal psycopg stub returning stub_rows on any execute().
+
+    Post-condition: the returned module exposes psycopg.connect() that
+    yields a connection whose execute().fetchall() returns stub_rows.
+    """
+    psycopg_mod = types.ModuleType("psycopg")
+    rows_mod = types.ModuleType("psycopg.rows")
+
+    cursor = MagicMock()
+    cursor.fetchall.return_value = stub_rows
+
+    conn = MagicMock()
+    conn.execute.return_value = cursor
+
+    psycopg_mod.connect = MagicMock(return_value=conn)
+    rows_mod.dict_row = MagicMock()
+    psycopg_mod.rows = rows_mod
+
+    return psycopg_mod
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _run_process_event(event: dict, stub_rows: list[dict]) -> tuple[str, str, int]:
+    """Run process_event() in isolation, capturing stdout/stderr and exit code.
+
+    Returns (stdout_text, stderr_text, exit_code).
+    The module is reloaded so _SPECIALIST_AGENTS is re-evaluated from the
+    live ~/.claude/agents dirs (dynamic load under test).
+    """
+    psycopg_stub = _make_psycopg_stub(stub_rows)
+
+    stdout_buf = io.StringIO()
+    stderr_buf = io.StringIO()
+
+    exit_code = 0
+
+    with patch.dict(sys.modules, {"psycopg": psycopg_stub, "psycopg.rows": psycopg_stub.rows}):
+        # Force re-import so patched psycopg is visible inside _fetch_agent_context.
+        if "mcp_server.hooks.agent_briefing" in sys.modules:
+            del sys.modules["mcp_server.hooks.agent_briefing"]
+        import mcp_server.hooks.agent_briefing as module
+
+        try:
+            with patch("sys.stdout", stdout_buf), patch("sys.stderr", stderr_buf):
+                module.process_event(event)
+        except SystemExit as exc:
+            exit_code = exc.code if isinstance(exc.code, int) else 0
+
+    return stdout_buf.getvalue(), stderr_buf.getvalue(), exit_code
+
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+class TestAgentBriefing(unittest.TestCase):
+
+    def test_feynman_with_matching_memory_produces_briefing(self) -> None:
+        """Genius agent feynman + matching memory → stdout contains Cortex Briefing.
+
+        Pre-condition: feynman exists in ~/.claude/agents/genius/ (dynamic load).
+        Post-condition: exit 0, stdout contains '## Cortex Briefing'.
+        """
+        stub_rows = [
+            {"content": "feynman past lesson: always verify sources", "heat": 0.8, "agent_context": "feynman"},
+        ]
+        event = {
+            "session_id": "test-session-001",
+            "agent_name": "feynman",
+            "agent_type": "genius",
+            "prompt": "Explain the zetetic scientific standard and verify the implementation",
+            "cwd": "/tmp",
+        }
+        stdout, stderr, code = _run_process_event(event, stub_rows)
+        self.assertEqual(code, 0, f"Expected exit 0, got {code}. stderr: {stderr}")
+        self.assertIn("Cortex Briefing", stdout, f"Expected 'Cortex Briefing' in stdout.\nstdout: {stdout!r}\nstderr: {stderr!r}")
+
+    def test_nonexistent_agent_skips_gracefully(self) -> None:
+        """Unknown agent name → exit 0 with skip log, no briefing emitted.
+
+        Pre-condition: nonexistent-agent is not in any agent file.
+        Post-condition: exit 0, stdout empty, stderr contains 'skip'.
+        """
+        event = {
+            "session_id": "test-session-002",
+            "agent_name": "nonexistent-agent",
+            "agent_type": "custom",
+            "prompt": "Do something with a nonexistent agent context here",
+            "cwd": "/tmp",
+        }
+        stdout, stderr, code = _run_process_event(event, [])
+        self.assertEqual(code, 0, f"Expected exit 0, got {code}. stderr: {stderr}")
+        self.assertEqual(stdout.strip(), "", f"Expected empty stdout, got: {stdout!r}")
+        self.assertIn("skip", stderr.lower(), f"Expected 'skip' in stderr. stderr: {stderr!r}")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    loader = unittest.TestLoader()
+    suite = loader.loadTestsFromTestCase(TestAgentBriefing)
+    runner = unittest.TextTestRunner(verbosity=2)
+    result = runner.run(suite)
+    if result.wasSuccessful():
+        print("\nPASS: all agent-briefing tests passed.")
+        sys.exit(0)
+    else:
+        print(f"\nFAIL: {len(result.failures)} failure(s), {len(result.errors)} error(s).")
+        sys.exit(1)