mishkan-harness 0.2.0 → 0.2.3

package/payload/mishkan/observability/watchd/src/mishkan_watchd/state.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 from collections import deque
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
+from time import monotonic
 from typing import Any, Optional
 
 
@@ -26,6 +27,12 @@ def _now() -> str:
         f"{datetime.now(tz=timezone.utc).microsecond // 1000:03d}Z"
 
 
+# How long an event for an unconfirmed session is buffered before being
+# dropped. session_discover polls every 10s, so 15s covers the case where
+# a hook fires for a brand-new session before its first JSONL flush.
+_PENDING_TTL_S = 15.0
+
+
 @dataclass
 class AgentState:
     name: str
@@ -36,6 +43,13 @@ class AgentState:
     tokens_in: int = 0
     tokens_out: int = 0
     cost_estimate_usd: float = 0.0
+    # Claude tier this agent runs on (opus / sonnet / haiku). Lifted from
+    # post-tool-observe.sh's `agent_spawn` payload, which already carries the
+    # model field that model-route.py injected. Consumed by the Usage tab to
+    # pick the per-agent context window (Sonnet 4.6 = 1M, Opus 4.x = 1M,
+    # Haiku 4.5 = 200k) instead of pinning the bar at a single fleet-wide
+    # default. Empty string when the spawner didn't surface a model.
+    model: str = ""
 
 
 @dataclass
@@ -93,24 +107,97 @@ class CogneeStoreState:
     last_probe: Optional[str] = None
 
 
+@dataclass
+class GraphifyState:
+    """Aggregated Graphify state across all watched projects.
+
+    graphify_tail emits scan events whose payload carries the latest
+    nodes/edges for a single project; we keep the most recent per-project
+    rollup so the snapshot served to a new TUI client carries the current
+    state even if the scan event itself fired before the client connected.
+    """
+    nodes: int = 0
+    edges: int = 0
+    communities: int = 0
+    scans: int = 0
+    queries: int = 0
+    last_scan_project: Optional[str] = None
+    last_scan_at: Optional[str] = None
+    last_query_project: Optional[str] = None
+    last_query_at: Optional[str] = None
+    last_query_text: Optional[str] = None
+
+
 @dataclass
 class HarnessState:
     sessions: dict[str, SessionState] = field(default_factory=dict)
     worktrees: dict[str, WorktreeState] = field(default_factory=dict)
     mcp_servers: dict[str, MCPServerState] = field(default_factory=dict)
     cognee: dict[str, CogneeStoreState] = field(default_factory=dict)
+    graphify: GraphifyState = field(default_factory=GraphifyState)
     recent_hooks: deque[dict[str, Any]] = field(default_factory=lambda: deque(maxlen=50))
     started: str = field(default_factory=_now)
+    # Bounded ring of recently-stopped session ids. Any event for an id
+    # in this ring is dropped silently — prevents background-hook events
+    # (e.g. CLAUDE_PROJECT_DIR leaking from a stale shell env) from
+    # resurrecting a stopped session via _ensure_session. Capacity 256 is
+    # ~256 × poll_interval = several minutes of memory; cheap.
+    _stopped_recently: deque[str] = field(default_factory=lambda: deque(maxlen=256))
+
+    # Sessions confirmed alive by session_discover. Only sessions in this
+    # set are eligible to have non-session_start events applied to state.
+    # session_discover emits session_start when it observes an active
+    # JSONL; that adds to this set. session_stop removes from it.
+    _confirmed_alive: set[str] = field(default_factory=set)
+
+    # Per-session buffer of events that arrived before the session_id was
+    # confirmed alive by session_discover. Each entry: (monotonic ts, event).
+    # On session_start the buffer for that sid is flushed in order. Entries
+    # older than _PENDING_TTL_S are dropped during apply() sweep — bounds
+    # memory for sids that session_discover never confirms (typically
+    # hooks firing for already-gone sessions).
+    _pending: dict[str, deque] = field(default_factory=dict)
 
     # ----- event application -------------------------------------------------
 
     def apply(self, event: dict[str, Any]) -> None:
-        """Apply a bus-format event to the state. Idempotent on unknowns."""
+        """Apply a bus-format event to the state.
+
+        Authority gate: session_discover is the source of truth for alive
+        sessions. Only sessions confirmed by session_discover (via
+        session_start) are eligible to have events applied. Events for
+        unknown session_ids are buffered briefly (_PENDING_TTL_S) and
+        flushed if confirmation arrives; otherwise dropped.
+
+        This kills the phantom-session bug at its root: bus_tail can no
+        longer resurrect stopped or never-alive sessions, no matter what
+        old hook events surface from disk.
+        """
         try:
+            self._sweep_pending()
             etype = event.get("type")
             session_id = event.get("session")
+
             if session_id:
-                self._ensure_session(session_id, event.get("project") or "unknown")
+                if etype == "session_start":
+                    # session_discover has just confirmed this session is alive.
+                    self._confirmed_alive.add(session_id)
+                    self._ensure_session(session_id, event.get("project") or "unknown")
+                    self._flush_pending(session_id)
+                elif etype == "session_stop":
+                    # Honoured below; remove from confirmed + tombstone.
+                    pass
+                elif session_id in self._stopped_recently:
+                    # Stopped session — drop silently. Tombstone window handles
+                    # lagging hook events for sessions whose stop just propagated.
+                    return
+                elif session_id not in self._confirmed_alive:
+                    # Unknown session. Buffer with TTL — if session_discover
+                    # confirms within _PENDING_TTL_S we replay in order;
+                    # otherwise the sweep drops it.
+                    buf = self._pending.setdefault(session_id, deque(maxlen=200))
+                    buf.append((monotonic(), event))
+                    return
 
             if etype == "agent_spawn":
                 self._on_agent_spawn(session_id, event)
@@ -128,16 +215,53 @@ class HarnessState:
                 self._on_mcp(event)
             elif etype == "cognee_op":
                 self._on_cognee_op(event)
+            elif etype in ("graphify_scan", "graphify_query"):
+                self._on_graphify(event)
             elif etype == "session_start":
                 pass  # ensured above
             elif etype == "session_stop":
-                self.sessions.pop(session_id, None) if session_id else None
+                if session_id:
+                    self.sessions.pop(session_id, None)
+                    self._confirmed_alive.discard(session_id)
+                    self._pending.pop(session_id, None)
+                    # Tombstone so lagging hook events for this session
+                    # don't resurrect it. Bounded ring — old tombstones age out.
+                    self._stopped_recently.append(session_id)
 
             if session_id and session_id in self.sessions:
                 self.sessions[session_id].recent_events.append(event)
         except Exception:
             return  # fail-open on any state error
 
+    # ----- pending buffer (confirmed-alive gate) -----------------------------
+
+    def _sweep_pending(self) -> None:
+        """Drop pending events older than _PENDING_TTL_S.
+
+        Called at the head of every apply() — bounded O(buffered sids)
+        which stays small in practice (only sids session_discover hasn't
+        confirmed yet, mostly transient).
+        """
+        if not self._pending:
+            return
+        now = monotonic()
+        for sid in list(self._pending.keys()):
+            buf = self._pending[sid]
+            while buf and (now - buf[0][0]) > _PENDING_TTL_S:
+                buf.popleft()
+            if not buf:
+                del self._pending[sid]
+
+    def _flush_pending(self, session_id: str) -> None:
+        """Replay all buffered events for a now-confirmed session, in order."""
+        buf = self._pending.pop(session_id, None)
+        if not buf:
+            return
+        for _, ev in list(buf):
+            # Re-enter apply(); the sid is now in _confirmed_alive so the
+            # gate above accepts.
+            self.apply(ev)
+
     # ----- snapshot for new clients ------------------------------------------
 
     def to_snapshot(self) -> dict[str, Any]:
@@ -149,6 +273,7 @@ class HarnessState:
             "worktrees": {p: _dc_to_dict(w) for p, w in self.worktrees.items()},
             "mcp_servers": {n: _dc_to_dict(s) for n, s in self.mcp_servers.items()},
             "cognee": {n: _dc_to_dict(s) for n, s in self.cognee.items()},
+            "graphify": _dc_to_dict(self.graphify),
             "recent_hooks": list(self.recent_hooks),
         }
 
@@ -177,11 +302,13 @@ class HarnessState:
         agent_name = event.get("agent") or (event.get("payload") or {}).get("subagent_type")
         if not agent_name:
             return
+        payload = event.get("payload") or {}
         sess.agents_active[agent_name] = AgentState(
             name=agent_name,
             started=event.get("ts") or _now(),
             last_tool=event.get("tool"),
             status="running",
+            model=str(payload.get("model") or ""),
         )
 
     def _on_agent_complete(self, sid: Optional[str], event: dict[str, Any]) -> None:
@@ -260,6 +387,33 @@ class HarnessState:
         s.last_probe = event.get("ts")
         self.cognee[store] = s
 
+    def _on_graphify(self, event: dict[str, Any]) -> None:
+        """Aggregate Graphify scan/query events into a single rollup.
+
+        We don't break this down per-project here — the TUI cards show the
+        most recent scan's totals + a query counter, which is what a single
+        rollup needs. The snapshot serializer flattens this back to a dict
+        so the existing TUI Knowledge tab can read it directly.
+        """
+        p = event.get("payload") or {}
+        etype = event.get("type")
+        g = self.graphify
+        if etype == "graphify_scan":
+            if p.get("nodes") is not None:
+                g.nodes = int(p["nodes"])
+            if p.get("edges") is not None:
+                g.edges = int(p["edges"])
+            if p.get("communities") is not None:
+                g.communities = int(p["communities"])
+            g.scans += 1
+            g.last_scan_project = p.get("project")
+            g.last_scan_at = p.get("scanned_at") or event.get("ts")
+        elif etype == "graphify_query":
+            g.queries += 1
+            g.last_query_project = p.get("project")
+            g.last_query_at = event.get("ts")
+            g.last_query_text = p.get("question") or p.get("file")
+
 
 def _dc_to_dict(dc) -> dict[str, Any]:
     return {k: v for k, v in dc.__dict__.items()}

package/payload/mishkan/observability/watchd/tests/test_state.py

@@ -11,6 +11,7 @@ from mishkan_watchd.state import HarnessState
 
 def test_agent_spawn_creates_session_and_agent():
     s = HarnessState()
+    s.apply({"ts": "x", "session": "sess-1", "type": "session_start", "project": "/tmp/proj"})
     s.apply({
         "ts": "2026-06-05T12:00:00.000Z",
         "session": "sess-1",
@@ -27,6 +28,7 @@ def test_agent_spawn_creates_session_and_agent():
 
 def test_token_usage_accumulates_per_session():
     s = HarnessState()
+    s.apply({"ts": "x", "session": "sess-tok", "type": "session_start", "project": "/p"})
     for tin, tout in [(100, 20), (200, 40), (50, 10)]:
         s.apply({
             "ts": "2026-06-05T12:00:00.000Z",
@@ -51,6 +53,7 @@ def test_session_stop_removes_session():
 def test_snapshot_serializes_cleanly():
     import json
     s = HarnessState()
+    s.apply({"ts": "x", "session": "snap", "type": "session_start", "project": "/p"})
     s.apply({
         "ts": "x", "session": "snap", "project": "/p",
         "type": "agent_spawn", "tool": "Task", "agent": "caleb",
@@ -63,8 +66,9 @@ def test_snapshot_serializes_cleanly():
 
 def test_unknown_event_type_is_ignored_gracefully():
     s = HarnessState()
-    s.apply({"ts": "x", "session": "weird", "type": "completely_unknown_type"})
-    # Session is created but no specific state mutation; no exception.
+    s.apply({"ts": "x", "session": "weird", "type": "session_start", "project": "/p"})
+    s.apply({"ts": "y", "session": "weird", "type": "completely_unknown_type"})
+    # Session exists from session_start; unknown type triggers no exception.
     assert "weird" in s.sessions
 
 

package/payload/mishkan/org/org.json

@@ -0,0 +1,141 @@
+{
+  "generated_from": "docs/design/MISHKAN_agent_aliases.md",
+  "schema_version": 1,
+  "groups": [
+    {
+      "id": "orchestration",
+      "label": "Orchestration",
+      "domain": null,
+      "mission": "Routes every request, owns scope, owns technical standards. The two interface layers of MISHKAN — PM (Nehemiah) talks to Y4NN, CTO (Bezalel) gates technical quality.",
+      "charter": "No specialist work happens without scope (Nehemiah) and technical fit (Bezalel) approved first.",
+      "agents": [
+        {"alias": "nehemiah", "role": "project_manager", "short": "PM", "description": "Scope, delivery, sprint state, user interface in exploration mode.", "source": "Book of Nehemiah"},
+        {"alias": "bezalel", "role": "cto", "short": "CTO", "description": "Technical standards, architecture, quality bar.", "source": "Exodus 31:2"}
+      ]
+    },
+    {
+      "id": "research",
+      "label": "Research Pipeline",
+      "domain": null,
+      "mission": "Shared research pipeline reachable by any agent facing an unknown. Six stages: clarify → formulate → research → summarise → evaluate → report.",
+      "charter": "No fabricated facts. If it's unknown, the pipeline runs. The report carries verifiable sources or marks the unknown explicitly.",
+      "agents": [
+        {"alias": "jakin", "role": "intent_clarificator", "short": "intent", "description": "Establishes the threshold — clarifies what the question really is before research starts.", "source": "1 Kings 7:21"},
+        {"alias": "ezra", "role": "research_details_formulator", "short": "formulate", "description": "Structures the research plan with precision.", "source": "Ezra 7:6"},
+        {"alias": "caleb", "role": "contextual_web_researcher", "short": "web", "description": "Goes wide and returns a faithful, fearless report.", "source": "Numbers 13:30"},
+        {"alias": "shaphan", "role": "contextual_research_summarizer", "short": "summarize", "description": "Compresses Caleb's findings into actionable summary.", "source": "2 Kings 22:3-10"},
+        {"alias": "shemaiah", "role": "contextual_research_results_evaluator", "short": "evaluate", "description": "Discerns true signal from false in the research output.", "source": "Nehemiah 6:10-13"},
+        {"alias": "baruch", "role": "research_reporter", "short": "report", "description": "Carries the final message back faithfully.", "source": "Jeremiah 36:4"}
+      ]
+    },
+    {
+      "id": "chosheb",
+      "label": "Chosheb",
+      "domain": "Design",
+      "hebrew": "חֹשֵׁב",
+      "hebrew_meaning": "Cunning work — deviser of artistic works (Exodus 31:4)",
+      "mission": "Designs the visible and felt experience before a line of frontend code is written. Owns UI, UX, design system tokens, accessibility intent.",
+      "charter": "Design handoff to Panim is complete or it doesn't ship. DS fit, a11y, asset manifest, QA matrix — all four lenses or the package is incomplete.",
+      "relationships": "Chosheb → Panim (design handoff · unidirectional)",
+      "agents": [
+        {"alias": "aholiab", "role": "chosheb_team_lead", "short": "lead", "description": "Bezalel's partner — leads design craftsmen, coordinates handoff.", "source": "Exodus 31:6"},
+        {"alias": "hiram", "role": "senior_ui_design_and_prototype_implementation", "short": "ui", "description": "Crafts the visible beautiful things — UI design and prototypes.", "source": "1 Kings 7:13-14"},
+        {"alias": "deborah", "role": "cognitive_and_emotional_ux_expert", "short": "ux", "description": "Sees what others miss — cognitive and emotional UX guidance.", "source": "Judges 4:4-5"},
+        {"alias": "elasah", "role": "chosheb_team_reporter", "short": "report", "description": "Carries the team's structured output faithfully.", "source": "Jeremiah 29:3"}
+      ]
+    },
+    {
+      "id": "panim",
+      "label": "Panim",
+      "domain": "Frontend",
+      "hebrew": "פָּנִים",
+      "hebrew_meaning": "Face · presence · what is turned toward (Exodus 33:14)",
+      "mission": "Implements every visible surface — components, pages, design system code, asset pipeline, a11y/SEO. Consumes Chosheb's handoff, contracts with Yasad's APIs.",
+      "charter": "What the user sees is correct, accessible, and consistent with the DS. Token changes propagate everywhere or nowhere — no half-rolled-out themes.",
+      "relationships": "Chosheb → Panim (design handoff) · Panim ↔ Yasad (API contracts)",
+      "agents": [
+        {"alias": "huram", "role": "panim_team_lead", "short": "lead", "description": "Leads all visible frontend works — cunning across stack.", "source": "2 Chronicles 2:13"},
+        {"alias": "oholiab", "role": "senior_frontend_engineer_frontend_design_system_expert", "short": "ds", "description": "Keeper of patterns and standards across components.", "source": "Exodus 35:34"},
+        {"alias": "salma", "role": "senior_frontend_developer", "short": "dev", "description": "Implements visible form — the builder of frontend code.", "source": "1 Chronicles 2:51"},
+        {"alias": "obed", "role": "smart_frontend_assets_feeder", "short": "assets", "description": "Faithful servant who supplies and sustains assets.", "source": "Ruth 4:17"},
+        {"alias": "asaph", "role": "seo_accessibility_expert", "short": "a11y", "description": "Makes the work heard and received by all — SEO + a11y.", "source": "1 Chronicles 16:5"},
+        {"alias": "jahaziel", "role": "frontend_qa_engineer", "short": "qa", "description": "Sees what others miss — frontend QA, evaluates without producing.", "source": "2 Chronicles 20:14"},
+        {"alias": "ahikam", "role": "panim_team_reporter", "short": "report", "description": "Carries the team's structured output faithfully.", "source": "2 Kings 22:12"}
+      ]
+    },
+    {
+      "id": "yasad",
+      "label": "Yasad",
+      "domain": "Backend",
+      "hebrew": "יָסַד",
+      "hebrew_meaning": "To lay the foundation · establish solidly (Psalm 24:2)",
+      "mission": "Lays and maintains the backend foundation — endpoints, contracts, data schema, persistence, business invariants. Contract-first.",
+      "charter": "Contracts before code. Migrations reviewed by 4 orthogonal lenses (contracts/perf/security/tests) before they ship.",
+      "relationships": "Panim ↔ Yasad (API contracts) · Yasad ↔ Mishmar (audit + remediation)",
+      "agents": [
+        {"alias": "zerubbabel", "role": "yasad_team_lead", "short": "lead", "description": "Governor who lays the deep base — leads backend foundation work.", "source": "Ezra 3:2"},
+        {"alias": "zadok", "role": "senior_software_engineer_design_system_master", "short": "patterns", "description": "Keeper of what must not change — backend patterns.", "source": "2 Samuel 8:17"},
+        {"alias": "nathan", "role": "senior_software_engineer_software_architecture_master", "short": "arch", "description": "Brings architectural vision — what should and should not be built.", "source": "2 Samuel 7:2"},
+        {"alias": "hizkiah", "role": "senior_backend_engineer_pure_backend_implementation", "short": "impl", "description": "Strength of Yah — does the direct backend implementation labour.", "source": "2 Chronicles 31:13"},
+        {"alias": "shallum", "role": "senior_backend_engineering_databases_expert", "short": "db", "description": "Keeper of what is stored — database design and migration.", "source": "2 Kings 15:10"},
+        {"alias": "uriah", "role": "backend_qa_engineer", "short": "qa", "description": "Absolute integrity — holds the line on backend standards.", "source": "2 Samuel 11"},
+        {"alias": "igal", "role": "yasad_team_reporter", "short": "report", "description": "Reports faithfully from his section.", "source": "Numbers 13:7"}
+      ]
+    },
+    {
+      "id": "mishmar",
+      "label": "Mishmar",
+      "domain": "Security",
+      "hebrew": "מִשְׁמָר",
+      "hebrew_meaning": "Guard · watch · the post set day and night (Nehemiah 4:9)",
+      "mission": "Cross-cutting security — code, surface, infrastructure, threat model. A constraint shaping every team's output from the start, not a team reviewing at the end.",
+      "charter": "Sensitive surface changes pass the 3-lens gate (code-OWASP / surface / threat-model) with adversarial refute before merge. Hardening overlay re-applied on every container recreate.",
+      "relationships": "Mishmar ↔ all teams (cross-cutting audit) · Mishmar → Migdal (security gates infra)",
+      "agents": [
+        {"alias": "phinehas", "role": "mishmar_team_lead", "short": "lead", "description": "Acted decisively to stop a breach — zealous for the boundary.", "source": "Numbers 25:7-8"},
+        {"alias": "benaiah", "role": "software_and_infrastructure_security_expert_devsecops", "short": "infra-sec", "description": "Mighty man who handles the hardest infrastructure threats.", "source": "2 Samuel 23:20"},
+        {"alias": "joab", "role": "web_mobile_desktop_security_expert", "short": "app-sec", "description": "Field general across all attack vectors — app surface security.", "source": "2 Samuel 8:16"},
+        {"alias": "ira", "role": "code_security_ops", "short": "code-sec", "description": "Keeps watch at the code level — security ops.", "source": "2 Samuel 20:26"},
+        {"alias": "hushai", "role": "software_security_advisor", "short": "advisor", "description": "Trusted advisor who outmanoeuvred the attacker — security counsel.", "source": "2 Samuel 15:37"},
+        {"alias": "maaseiah", "role": "mishmar_team_reporter", "short": "report", "description": "Carries the structured account faithfully.", "source": "Nehemiah 8:4"}
+      ]
+    },
+    {
+      "id": "migdal",
+      "label": "Migdal",
+      "domain": "Infrastructure",
+      "hebrew": "מִגְדָּל",
+      "hebrew_meaning": "Tower · load-bearing structures of the wall (Nehemiah 3:1)",
+      "mission": "Builds and operates the load-bearing infrastructure — systems, network, devops pipelines, observability, recovery. Gated by Mishmar at change time.",
+      "charter": "Infra change passes the 5-lens panel (design/systems/devops/observability/health) before apply. No `:latest` tags. Hardening overlay always re-applied. DR drilled quarterly.",
+      "relationships": "Mishmar → Migdal (security gates) · Migdal serves all teams' runtime",
+      "agents": [
+        {"alias": "eliashib", "role": "migdal_team_lead", "short": "lead", "description": "Organises the foundational infrastructure work.", "source": "Nehemiah 3:1"},
+        {"alias": "palal", "role": "systems_engineer_os_virtualisation_networks", "short": "systems", "description": "Works at the structural intersection — OS / virt / networks.", "source": "Nehemiah 3:25"},
+        {"alias": "meshullam", "role": "infrastructure_design_engineer", "short": "design", "description": "Designs connections between infrastructure parts.", "source": "Nehemiah 3:4"},
+        {"alias": "hanun", "role": "devsecops_practitioner_support_ops", "short": "devsecops", "description": "Long support stretch — devsecops practice, operational support.", "source": "Nehemiah 3:13"},
+        {"alias": "meremoth", "role": "devops_engineer", "short": "devops", "description": "Works at the delivery layer — pipelines, deploys.", "source": "Nehemiah 3:4"},
+        {"alias": "rehum", "role": "infrastructure_health_and_security_advisor", "short": "health", "description": "Watches for risk and advises — infrastructure health.", "source": "Nehemiah 3:17"},
+        {"alias": "zaccur", "role": "migdal_team_reporter", "short": "report", "description": "Keeps record, mindful of what happened.", "source": "Nehemiah 3:2"}
+      ]
+    },
+    {
+      "id": "sefer",
+      "label": "Sefer",
+      "domain": "Documentation",
+      "hebrew": "סֵפֶר",
+      "hebrew_meaning": "Book · scroll · official written record (Nehemiah 8, Ezra 6)",
+      "mission": "Documentation across three layers — organisation (Seraiah), project (Joah), team (Shevna). Pull-based: pulls at milestones and on trigger events, not on every commit.",
+      "charter": "What is not written down is forgotten. Release notes assembled from git log per category. ADRs for every consequential decision. Style guide applied uniformly.",
+      "relationships": "Sefer ← all teams (pulls at milestones + trigger events)",
+      "agents": [
+        {"alias": "jehoshaphat", "role": "sefer_team_lead", "short": "lead", "description": "First Recorder in David's court — cares for national archives.", "source": "2 Samuel 8:16"},
+        {"alias": "seraiah", "role": "organisation_layer_specialist", "short": "org", "description": "Operates at the highest state level — org-wide documentation.", "source": "2 Samuel 8:17"},
+        {"alias": "joah", "role": "project_layer_specialist", "short": "project", "description": "Documents specific events and decisions of each project.", "source": "2 Kings 18:18"},
+        {"alias": "shevna", "role": "team_layer_specialist", "short": "team", "description": "Embedded with teams — documents their specific outputs.", "source": "2 Kings 18:18"},
+        {"alias": "jehonathan", "role": "knowledge_publication_specialist", "short": "publish", "description": "Takes knowledge and makes it legible for others.", "source": "1 Chronicles 27:32"},
+        {"alias": "huldah", "role": "sefer_team_reporter", "short": "report", "description": "Verifies, interprets, reports back with authority.", "source": "2 Kings 22:14"}
+      ]
+    }
+  ]
+}

package/payload/mishkan/scripts/pre-commit-eval-gate.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# pre-commit-eval-gate.sh — run MISHKAN evals if their contract surface changed.
+#
+# Optional install: symlink as your repo's .git/hooks/pre-commit so the gate
+# fires before every commit. Detects whether the staged changes touch any
+# eval's sentinel paths; runs only the affected eval(s).
+#
+# Install:
+#   ln -s "$(pwd)/payload/mishkan/scripts/pre-commit-eval-gate.sh" .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# Uninstall:
+#   rm .git/hooks/pre-commit
+#
+# Exit codes:
+#   0 → no relevant changes OR all triggered evals passed
+#   1 → at least one eval failed (commit blocked)
+#   2 → an eval's environment is missing (jq, validator)
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+cd "$REPO_ROOT"
+
+changed=$(git diff --cached --name-only --diff-filter=ACMR)
+[[ -z "$changed" ]] && exit 0
+
+trigger_baruch=false
+while IFS= read -r f; do
+  case "$f" in
+    payload/mishkan/templates/research-log.schema.json) trigger_baruch=true ;;
+    payload/mishkan/scripts/validate-research-log.sh)   trigger_baruch=true ;;
+    payload/mishkan/agents/baruch.md)                   trigger_baruch=true ;;
+    payload/mishkan/skills/baruch-research-reporting-craft/*) trigger_baruch=true ;;
+    payload/mishkan/evals/baruch/*)                     trigger_baruch=true ;;
+  esac
+done <<< "$changed"
+
+overall=0
+if [[ "$trigger_baruch" == "true" ]]; then
+  echo "→ Baruch eval (contract surface changed)"
+  if bash payload/mishkan/evals/baruch/run.sh; then
+    echo "  ✓ Baruch eval passed"
+  else
+    rc=$?
+    echo "  ✗ Baruch eval failed (exit $rc)" >&2
+    overall=$rc
+  fi
+fi
+
+exit "$overall"