Skip to content

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.md
index 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.0
bumps `dismiss_count`); approving recovers it. Trust now discounts the
ranking 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.** The
research run no longer has a post-dedup verify pass or an optional
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 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 seven
specialist slugs (cso, cfo, cmo, coo, chro, cpo, gc). Each
runs through `specialist_research.research_one_specialist`
with its normal `effective_system_prompt()` + a research-mode
addendum (`prompts.research_addendum_for`) + the Anthropic
web_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.py
index 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.py
index 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 Any
from openexecutive.agents.base import BaseAgent
from 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 domain
diff --git a/packages/core/openexecutive/monitoring/research/tools.py b/packages/core/openexecutive/monitoring/research/tools.py
index 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 annotations
from 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.py
index 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.py
index 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 and
the 30-day window — without 'today', the model cannot judge recency,