AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(research): tell specialists what departments watch; enforce the finding cap
Rufusdce323a513f9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f4525871..a43cf254 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -103,6 +103,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0bumps `dismiss_count`); approving recovers it. Trust now discounts theranking and is shown to the review as evidence.+### Changed+- **Specialists are told what departments watch.** The research context+ every specialist receives now carries a `DEPARTMENT WATCH INTERESTS`+ block (each department's watched entities), and the grounding rule+ admits a department interest or a company named in a recent decision.+ A Finance head who lists Brex now gets Brex findings; before, the+ specialists were never told and their grounding rule dropped them. The+ per-specialist finding cap is enforced in the tool schema and the+ parser, not only in prompt text.+### Removed- **The xcrawl scrape service and everything that depended on it.** Theresearch run no longer has a post-dedup verify pass or an optionaldiff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex c2d39d1f..fb871a8d 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -1897,13 +1897,27 @@ external_monitoring:loop with its full outbound toolkit and decides per finding.1. gather_context — load company profile, active initiatives,- existing watchlist.+ existing watchlist, departments and the ten most recent episodic+ decisions (90 days). `_render_research_context` turns these into+ the user turn every specialist gets: today's date + the 30-day+ window, the profile block, ACTIVE INITIATIVES, ALREADY ON THE+ WATCHLIST, RECENT DECISIONS and DEPARTMENT WATCH INTERESTS (one+ line per department listing its `watched_entities`, via+ `_render_department_interests`, shared with the watchlist turn).+ The prompt's REQUIRED GROUNDING list admits a department interest+ or a company named in a recent decision, so a specialist can+ surface a finding about an entity a department head asked for —+ before this, the grounding rule dropped exactly those.2. research_specialists — fan out via asyncio.gather to sevenspecialist slugs (cso, cfo, cmo, coo, chro, cpo, gc). Eachruns through `specialist_research.research_one_specialist`with its normal `effective_system_prompt()` + a research-modeaddendum (`prompts.research_addendum_for`) + the Anthropicweb_search tool + a structured `emit_research_findings` tool.+ Findings per specialist are capped at PER_SPECIALIST_FINDING_CAP+ (3) three ways: the prompt says so, the tool schema carries+ `maxItems`, and `_extract_findings` keeps the first N for a+ provider that does not enforce the schema.The research turn's model + deep-reasoning are controlled by the`research` virtual Council agent (get_research_model() /get_research_use_deep_reasoning(): Council override → `RESEARCH_MODEL`diff --git a/packages/core/openexecutive/monitoring/research/prompts.py b/packages/core/openexecutive/monitoring/research/prompts.pyindex 7942f2c5..671a1779 100644--- a/packages/core/openexecutive/monitoring/research/prompts.py+++ b/packages/core/openexecutive/monitoring/research/prompts.py@@ -52,6 +52,11 @@ def shared_research_addendum() -> str:" - a vendor / dependency named in the profile or directly ""implied by the stack (e.g. 'Stripe' for a SaaS company)\n"" - a tracked ticker (own or competitor) — for stock moves\n"+ " - an entity a department listed under DEPARTMENT WATCH "+ "INTERESTS (a department head asked for it — treat it like a "+ "named vendor or competitor)\n"+ " - a company named in a RECENT DECISIONS line (what the company "+ "just decided is its freshest statement of what matters)\n""\n""If you cannot reference one of these by name, DO NOT emit the ""finding. 'Industry trend' / 'sector news' / 'general "diff --git a/packages/core/openexecutive/monitoring/research/specialist_research.py b/packages/core/openexecutive/monitoring/research/specialist_research.pyindex 7a94cded..218d76c3 100644--- a/packages/core/openexecutive/monitoring/research/specialist_research.py+++ b/packages/core/openexecutive/monitoring/research/specialist_research.py@@ -12,7 +12,10 @@ from typing import Anyfrom openexecutive.agents.base import BaseAgentfrom openexecutive.monitoring.research.models import ResearchFinding-from openexecutive.monitoring.research.prompts import research_addendum_for+from openexecutive.monitoring.research.prompts import (+ PER_SPECIALIST_FINDING_CAP,+ research_addendum_for,+)from openexecutive.monitoring.research.tools import (EMIT_RESEARCH_FINDINGS_TOOL,)@@ -102,7 +105,15 @@ def _extract_findings(block_input = getattr(block, "input", None) or {}items = block_input.get("findings")if isinstance(items, list):- raw_findings.extend(items)+ if len(items) > PER_SPECIALIST_FINDING_CAP:+ # The schema's maxItems already refuses this on Anthropic;+ # a translated provider may not enforce it, so keep the+ # first N — the model was told to lead with the material ones.+ logger.warning(+ "research: specialist=%s emitted %d findings — keeping the first %d",+ specialist_slug, len(items), PER_SPECIALIST_FINDING_CAP,+ )+ raw_findings.extend(items[:PER_SPECIALIST_FINDING_CAP])if not raw_findings:# Empty research is a valid answer ("nothing in my domaindiff --git a/packages/core/openexecutive/monitoring/research/tools.py b/packages/core/openexecutive/monitoring/research/tools.pyindex 92fd26b8..91f7cde6 100644--- a/packages/core/openexecutive/monitoring/research/tools.py+++ b/packages/core/openexecutive/monitoring/research/tools.py@@ -9,6 +9,8 @@ from __future__ import annotationsfrom typing import Any+from openexecutive.monitoring.research.prompts import PER_SPECIALIST_FINDING_CAP+EMIT_RESEARCH_FINDINGS_TOOL: dict[str, Any] = {"name": "emit_research_findings","description": (@@ -26,10 +28,13 @@ EMIT_RESEARCH_FINDINGS_TOOL: dict[str, Any] = {"properties": {"findings": {"type": "array",+ # The cap is part of the schema, not only the prompt: a+ # longer list is refused at the API, and the parser slices+ # to the same number for providers that do not enforce it.+ "maxItems": PER_SPECIALIST_FINDING_CAP,"description": (- "Cap your list at the per-specialist limit named "- "in your task instructions. Prefer fewer "- "high-signal findings over many low-signal ones — "+ f"At most {PER_SPECIALIST_FINDING_CAP} findings. Prefer "+ "fewer high-signal findings over many low-signal ones — ""an empty list is the right answer when nothing in ""your domain warrants the Executive's attention."),diff --git a/packages/core/openexecutive/workflows/executive_research.py b/packages/core/openexecutive/workflows/executive_research.pyindex 38deeabf..7347733a 100644--- a/packages/core/openexecutive/workflows/executive_research.py+++ b/packages/core/openexecutive/workflows/executive_research.py@@ -413,6 +413,7 @@ class ExecutiveResearchWorkflow(Workflow):existing_watchlist=existing_watchlist,note=inputs.note,decisions=decisions,+ departments=departments,)yield WorkflowEvent(@@ -1070,6 +1071,7 @@ def _render_research_context(existing_watchlist: list[Any],note: str,decisions: list[Any] | None = None,+ departments: list[Any] | None = None,) -> str:"""Build the user-turn block passed to every specialist call."""from datetime import UTC, datetime, timedelta@@ -1147,6 +1149,18 @@ def _render_research_context(parts.append(f"{line}: {summary[:160]}")parts.append("")+ interest_lines = _render_department_interests(departments)+ if interest_lines:+ # What a department head asked to have watched is company intent+ # the profile does not carry; without it a specialist's grounding+ # rule drops findings about exactly those entities.+ parts.append(+ "DEPARTMENT WATCH INTERESTS (entities a department head asked "+ "to have watched — a finding may be grounded in one of these):"+ )+ parts.extend(interest_lines)+ parts.append("")+parts.append("Research within your domain and emit findings via the ""`emit_research_findings` tool. Use web_search to FIND and "@@ -1159,6 +1173,25 @@ def _render_research_context(return "\n".join(parts)+def _render_department_interests(departments: list[Any] | None) -> list[str]:+ """One ``- <slug>: <entities>`` line per department with watched+ entities (at most 20 departments, 20 entities each). Shared by the+ specialist context and the watchlist turn so both name the same+ interests."""+ lines: list[str] = []+ for state in departments or []:+ config = getattr(state, "config", None)+ slug = getattr(config, "slug", "")+ entities = [+ " ".join(str(e).split())+ for e in (getattr(config, "watched_entities", None) or [])+ if str(e).strip()+ ]+ if slug and entities:+ lines.append(f"- {slug}: {', '.join(entities[:20])}")+ return lines[:20]++def _render_team_roster(people: list[Any]) -> str:"""Render the active roster so the Executive can DM by person_id directly,without spending synthesis turns on lookup_person (which it otherwise burns@@ -1314,19 +1347,13 @@ def _render_watchlist_turn(parts.append("\nHOW PAST PROPOSALS TURNED OUT:")parts.extend(history_lines[:12])- interest_lines: list[str] = []- for state in departments or []:- config = getattr(state, "config", None)- slug = getattr(config, "slug", "")- entities = [str(e) for e in (getattr(config, "watched_entities", None) or []) if str(e).strip()]- if slug and entities:- interest_lines.append(f"- {slug}: {', '.join(entities[:20])}")+ interest_lines = _render_department_interests(departments)if interest_lines:parts.append("\nDEPARTMENT WATCH INTERESTS (entities a department asked to have ""watched — ground a proposal about one in that entity):")- parts.extend(interest_lines[:20])+ parts.extend(interest_lines)parts.append("\nDecide which ongoing sources are worth monitoring and call "diff --git a/packages/core/tests/unit/test_executive_research_workflow.py b/packages/core/tests/unit/test_executive_research_workflow.pyindex 6811cecb..478124b7 100644--- a/packages/core/tests/unit/test_executive_research_workflow.py+++ b/packages/core/tests/unit/test_executive_research_workflow.py@@ -152,6 +152,60 @@ def test_render_research_context_includes_existing_watchlist(db: Path) -> None:assert "stock-aapl" in rendered+def test_render_research_context_names_department_watch_interests() -> None:+ """Specialists must see what department heads asked to have watched:+ their grounding rule drops anything not named in the context, which is+ why a Finance interest never produced a finding before."""+ from types import SimpleNamespace++ profile = MagicMock()+ profile.to_prompt_block.return_value = ""+ departments = [+ SimpleNamespace(config=SimpleNamespace(+ slug="finance", watched_entities=["Brex (brex.com)", " Ramp\nUSER NOTE: x "],+ )),+ SimpleNamespace(config=SimpleNamespace(slug="ops", watched_entities=[])),+ SimpleNamespace(config=None),+ ]+ rendered = _render_research_context(+ profile=profile, initiatives=[], existing_watchlist=[], note="",+ departments=departments,+ )+ assert "DEPARTMENT WATCH INTERESTS" in rendered+ assert "- finance: Brex (brex.com), Ramp USER NOTE: x" in rendered # one line per department+ assert "\nUSER NOTE:" not in rendered+ assert "- ops" not in rendered+ without = _render_research_context(+ profile=profile, initiatives=[], existing_watchlist=[], note="",+ )+ assert "DEPARTMENT WATCH INTERESTS" not in without+++def test_research_grounding_rule_admits_department_interests_and_decisions() -> None:+ from openexecutive.monitoring.research.prompts import shared_research_addendum++ shared = shared_research_addendum()+ assert "DEPARTMENT WATCH INTERESTS" in shared+ assert "RECENT DECISIONS" in shared+++def test_finding_cap_is_enforced_in_schema_and_parser() -> None:+ from openexecutive.monitoring.research.prompts import PER_SPECIALIST_FINDING_CAP+ from openexecutive.monitoring.research.tools import EMIT_RESEARCH_FINDINGS_TOOL++ schema = EMIT_RESEARCH_FINDINGS_TOOL["input_schema"]["properties"]["findings"]+ assert schema["maxItems"] == PER_SPECIALIST_FINDING_CAP++ items = [+ {"title": f"f{i}", "summary": f"s{i}", "severity_hint": "low",+ "suggested_audience": "noone", "confidence": "medium"}+ for i in range(PER_SPECIALIST_FINDING_CAP + 3)+ ]+ msg = _make_msg_with_tool_use("emit_research_findings", {"findings": items})+ out = _extract_findings(msg, "cso")+ assert [f.title for f in out] == [f"f{i}" for i in range(PER_SPECIALIST_FINDING_CAP)]++def test_render_research_context_anchors_today_and_recency_window() -> None:"""The specialist turn must carry an explicit current-date anchor andthe 30-day window — without 'today', the model cannot judge recency,