Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

fix(watchlist): close the logic-review findings on the research watch policy

Rufusef7fb8d7e994
diff --git a/packages/core/openexecutive/api/routes/watchlist.py b/packages/core/openexecutive/api/routes/watchlist.py
index 3c7a6638..0bbc5ca9 100644
--- a/packages/core/openexecutive/api/routes/watchlist.py
+++ b/packages/core/openexecutive/api/routes/watchlist.py
@@ -108,8 +108,8 @@ class DeclineBody(BaseModel):
class DeclineResponse(BaseModel):
slug: str
reason: str
- # "removed" (declined + deleted) or "kept_quiet" (too_noisy: converted
- # to an active watch with a high severity floor instead).
+ # "removed" (declined + deleted) or "kept_high_floor" (too_noisy: goes
+ # live as a research watch that only surfaces high-severity signals).
result: str
@@ -472,7 +472,8 @@ def approve_watchlist_suggestion(slug: str) -> WatchlistItem:
def decline_watchlist_suggestion(slug: str, body: DeclineBody | None = None) -> DeclineResponse:
"""Decline a research suggestion. The reason picks the remedy:
not_relevant / wrong_source remove it and blacklist (entity / target);
- too_noisy keeps it, live, with a high severity floor."""
+ too_noisy keeps the source, live, but only high-severity signals ever
+ surface — the one way a suggestion goes live without an approve."""
from openexecutive.monitoring.research import watch_policy
reason = (body.reason if body else DECLINE_REASON_NOT_RELEVANT)
@@ -486,8 +487,10 @@ def decline_watchlist_suggestion(slug: str, body: DeclineBody | None = None) ->
if reason == DECLINE_REASON_TOO_NOISY:
if not ms.quiet_pending_suggestion(item.id):
raise HTTPException(status_code=409, detail=f"{slug!r} is not a pending research suggestion")
- watch_policy.record_outcome_for(item, watch_policy.OUTCOME_APPROVED)
- result = "kept_quiet"
+ # The principal kept the source but objected to the shape of the
+ # guess — that is a decline for calibration, not an approval.
+ watch_policy.record_outcome_for(item, watch_policy.OUTCOME_DECLINED)
+ result = "kept_high_floor"
else:
if not ms.delete_pending_suggestion(item.id):
raise HTTPException(status_code=409, detail=f"{slug!r} is not a pending research suggestion")
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 9873a2c6..fd692ffd 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -1369,22 +1369,32 @@ external_monitoring:
+ profile.vendors + profile.tickers + active initiative titles +
strategic_priorities.current_year (+ existing watch labels, which only
corroborate). The entity MUST match a company-data term for a direct add.
+ - vocabulary precedence when a term appears in several sources:
+ company > competitor > vendor > ticker > initiative > priority > watch.
+ Partial (token) matching ignores stopwords and tokens < 4 chars.
- score ledger: +2 entity in company data (mandatory), +1 entity already
- watched under another source, +1 target is the entity's own source (its
- ticker / its domain / a primary-source host: sec.gov, federalregister.gov,
+ watched under another source, +1 target is the entity's own source (the
+ entity's ticker or a profile-tracked ticker / a URL whose SITE LABEL —
+ "acme" in status.acme.com, acme.co.uk; never a subdomain or TLD — is the
+ entity's / a primary-source host: sec.gov, federalregister.gov,
eur-lex), +1 finding confidence high, +1 verification confirmed, +1
cross-specialist consensus, ±1 policy history for (signal_type,
grounding_kind) at >= 5 samples (>= 0.7 / <= 0.3 approval rate).
- direct add at score >= 4 with the mandatory match AND a strong kind
(company / competitor / vendor / ticker — initiative- or
priority-grounded proposals are suggestions at most); model
- `certainty` can only downgrade; `query` never direct; above WATCHLIST_MAX_ENABLED
- (40) enabled rows every add is a suggestion; WATCHLIST_RESEARCH_MAX_DIRECT_ADDS
- (2) and WATCHLIST_RESEARCH_MAX_PROPOSALS (2) per run.
+ `certainty` can only downgrade; `query` never direct; a suggestion needs
+ a linked finding and score >= 1 (SUGGEST_THRESHOLD) — nothing vouching
+ for it is rejected; at or above WATCHLIST_MAX_ENABLED (40) enabled rows
+ EVERY proposal is rejected (suggestions poll too, so the ceiling must
+ stop them or it latches); WATCHLIST_RESEARCH_MAX_DIRECT_ADDS (2) and
+ WATCHLIST_RESEARCH_MAX_PROPOSALS (2) per run (a direct add past its
+ budget is filed as a suggestion and charged to that budget).
- quiet defaults on every research row (model cannot loosen): cadence
daily (vendor_status hourly; page_watch/query weekly), severity_floor
- medium, feed keyword trigger = entity tokens + material-event words +
- priority terms, stock abs_change_pct_gte=5.
+ medium, feed keyword trigger = material-event words + priority terms
+ (NEVER the entity name: feed summaries carry the feed label, so it would
+ match every entry), stock abs_change_pct_gte=5.
- direct → mode=active, origin=research; suggestion → mode=dry_run,
origin=research_proposed; rationale in `notes`; policy stamp (entity,
grounding_kind, specialist, score, reasons, source_url) in
@@ -1399,8 +1409,9 @@ external_monitoring:
target, and by entity for not_relevant declines (token match) —
and rendered to the model as DECLINED. Decline reasons: not_relevant
(blacklist entity), wrong_source (blacklist target), too_noisy (keep
- live at floor=high). Tool-supplied reasons outside the explicit set
- fall back to not_relevant.
+ live at floor=high; response result=kept_high_floor; recorded as a
+ DECLINED outcome for calibration). Tool-supplied reasons outside the
+ explicit set fall back to not_relevant.
- isolation: the routing/synthesis pass has NO watchlist write tools
(add/tune/remove are in _SYNTHESIS_EXCLUDED_TOOLS), so every watch a
research run creates goes through the policy; tune_watchlist_entry
@@ -1411,11 +1422,16 @@ external_monitoring:
auto_disabled by signal_type, grounding_kind, specialist) feed the
history term and are rendered to the model as HOW PAST PROPOSALS TURNED OUT.
- sweep (watch_policy.sweep, on the scheduler's 15-min alert sweep):
- expire suggestions older than WATCHLIST_PROPOSAL_TTL_DAYS (14);
- auto-disable research-origin watches (fired >= 5 & dismissed >= 2 &
- trust <= 0.5; rss/page_watch/vendor_status with no signal in 30 days;
- 3 consecutive failed polls); one `watchlist_suggestions` nudge alert
- when >= 3 suggestions have waited >= 7 days (keyed on the oldest slug).
+ expire suggestions older than WATCHLIST_PROPOSAL_TTL_DAYS (14)
+ (compare-and-delete: an approve in flight wins); auto-disable
+ research-origin watches (fired >= 5 & dismissed >= 2 & trust <= 0.5;
+ 3 consecutive failed polls — silence is NOT a rule, an unchanged page
+ or a healthy vendor is a working watch) and record the target as a
+ 90-day decline; one `watchlist_suggestions` nudge alert when >= 3
+ suggestions have waited >= 7 days — dedup_key watchlist_suggestions:pending
+ (an open card is coalesced in place), external_id per ISO week (a
+ dismissed card is not re-minted until next week), so acting on one
+ suggestion never spawns another nudge.
- the research state fingerprint hashes only enabled + active rows, so
approving / declining a suggestion never triggers a fresh research run.
- surfaces: /watchlist "Suggested by the Executive" (Approve / Decline…
diff --git a/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json b/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json
index 2ccf8ca5..e8eb8f64 100644
--- a/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json
+++ b/packages/core/openexecutive/architecture/prebuilt/external_monitoring.json
@@ -1,7 +1,7 @@
{
"section_id": "external_monitoring",
"title": "External Monitoring",
- "markdown": "`openexecutive.monitoring` watches the outside world on a heartbeat and turns detected changes into briefing proposals via the same alert pipeline that handles inbound email and Slack.\n\nThe `external_monitor_scan` heartbeat (`__internal__` channel, default every 5 min) walks `list_watchlist(enabled_only=True)`, skipping rows fresher than their per-source cadence floor. For each due row it fires a read-only source adapter resolved from `_REGISTRY` by `signal_type`:\n\n- `vendor_status` — Statuspage Atom/RSS incident feeds (AWS, Stripe, GitHub, …). Reads each incident's current status out of the entry body, parses `<updated>` into `published_at`, and keys its dedup on `(entry id, <updated>)`; a **seeding** source (see below).\n- `rss` — generic Atom/RSS via feedparser (changelogs, layoffs.fyi, filings). Parses each entry's `<pubDate>`/`<updated>` into `published_at`; a **seeding** source (see below).\n- `stock` — Yahoo Finance chart endpoint; fires on `abs_change_pct_gte` moves.\n- `page_watch` — change-detection on a feed-less page. Fetches via the keyless httpx fetcher by default, or via xcrawl's scrape API when the row carries `config.fetch = \"xcrawl\"` — so JS-rendered / bot-blocked pages that publish no RSS (most modern news / marketing sites) are still monitorable.\n- `edgar` and the BILLED `query` web-search adapter.\n\nEach `Signal` is trigger-filtered, severity-clamped to the row's `[floor, ceiling]`, and INSERTed into `external_signals` where `UNIQUE(dedup_key)` drops replays. Survivors pass a suppression cascade (`baseline` → `stale` → `dry_run` → `below_floor` → capture-time relevance enrichment → promote), then `promote_signal_to_alert` builds an `AlertEvent` handed to `alerts.pipeline.schedule_evaluation` and surfaced as a `/today` proposal.\n\nEvery signal carries two timestamps that are never conflated: `captured_at` (when the monitor first saw it) and `published_at` (when the upstream says it happened — RSS `<pubDate>`, EDGAR filing date; null for `stock`, `page_watch`, `query`). Two freshness gates run first in the cascade, before anything that costs an LLM call. **Baseline:** the first poll that returns entries for a row whose adapter declares `seed_on_first_poll` (`rss`, `edgar`) records every entry already in the feed — trigger misses included, so the first entry that ever matches a keyword is news and a later, wider trigger can't resurface old ones — as `suppressed_baseline`, promotes nothing, and stamps `watchlist.baselined_at`, so a new watch reports what changes from now on instead of replaying the feed's back-catalogue (the same idea as `page_watch`'s first-observation baseline). It is keyed on `baselined_at` rather than `last_polled_at`, so a failed first fetch can't forfeit it; the claim and the recording are one transaction (a compare-and-swap on the stamp plus the rows, all-or-nothing), so of two overlapping scans exactly one records the back-catalogue and a failure part-way leaves nothing behind to replay; the other scan promotes only entries dated after that stamp (undated entries count as baseline, since the feed controls the date; entries dated more than a few minutes past its own clock are deferred rather than recorded); and baseline rows don't count against `max_signals_per_scan`, so a large feed can't be half-baselined. `vendor_status` used to sit outside both gates for a structural reason: its dedup key was `sha256(slug, entry id)`, and an incident's id never changes across its updates, so any suppressed insert muted that incident for good. Keying on `(entry id, <updated>)` instead (issue #90) makes a suppression cost one *state* of an incident rather than the incident, so both gates now apply to vendor feeds too — and an incident moving Investigating → Resolved mints a new key and surfaces, while re-polling an unchanged feed still dedups. Because a history feed's archive is mostly incidents resolved months ago, the adapter also carves live news out of its own baseline: it reads each incident's current status from the entry body (Statuspage renders the newest update first as `<strong>Resolved</strong>` / `Investigating` / `Monitoring` / … — the body is parsed by a real HTML parser, off the event loop, and the reading is deliberately asymmetric: any sign that the incident is over closes it, wherever it appears, while only a marked-up label can say it is still open. Working out which update is newest turned out to be something tag soup cannot be trusted to express, and every attempt reported a long-resolved incident as live) and exempts the ones still OPEN via the optional `promote_on_baseline` hook, so a watch added during an outage reports that outage on its first poll while the resolved archive is recorded as `suppressed_baseline`. An unrecognised status counts as closed — a vendor changing feed format must not be able to promote its whole archive at HIGH, and nothing is lost, since the next `<updated>` bump surfaces normally. An exempt entry must still pass the row's trigger filter (one that misses stays in the baseline, so widening a trigger later cannot resurface it) and is still judged by the stale gate below: the exemption buys an entry past the baseline, never past its own timestamp, because \"this is live\" is a reading of vendor-controlled markup and an entry the feed dates outside the age window is not news whatever that reading says. **Stale:** a signal whose `published_at` is older than `EXTERNAL_MONITOR_MAX_SIGNAL_AGE_DAYS` (default 7; `0` disables) at capture time is recorded as `suppressed_stale` and never promoted — a January article a feed resurfaces in September is not September news. An entry dated more than `EXTERNAL_MONITOR_MAX_FUTURE_SKEW_HOURS` ahead (default 24; `0` disables; `config_json.max_future_skew_hours` overrides it per row for calendar or maintenance feeds that legitimately date entries ahead) is deferred instead: skipped for the tick and not recorded (recording would burn its dedup key and let a feed mute an announcement for good by post-dating it), with one aggregated `external_signal_deferred` audit row per poll — carrying each held-back entry's summary and link, and emitted even if the poll later raises — then judged normally once the date passes. Inside the window, the alert body handed to triage carries `Published:` and `Discovered:` lines so the item is judged on when it happened. Adapters prefer a plausible date key over one more than a day in the future (and keep the future value when every key is implausible, so the pipeline defers it rather than waving an undated entry through), and the alert body collapses whitespace in the summary so no source can forge its own labeled body line.\n\nThe `query` adapter is a special case: it emits every web hit flat-LOW (it can't judge materiality per-hit), so for query signals enrichment runs BEFORE the floor gate and `_grade_query_severity` regrades from the relevance read (≥0.8 HIGH, ≥0.5 MEDIUM, else LOW). Without this, any query watch item with a `severity_floor` above LOW would suppress every hit — which is what left the Monitoring section empty even while standing queries were returning material findings.\n\nWhich lane a proposal lands in is decided by `briefing.ranking.categorize`: an unrouted, low/medium signal from a monitoring source (`stock`, `vendor_status`, `rss`, `query`, `edgar`, `page_watch`, or any `external:*` topic tag) is `monitoring` (the collapsible Monitoring section); a routed or high/urgent one is `action` (the \"Needs you\" queue). The triage prompt's External Signals rule covers all six source kinds so it trusts the source and emits the `external:*` tags that drive this split.\n\nThe watchlist is editable from chat (`add_watchlist_entry`, `tune_watchlist_entry`) and HTTP (`/watchlist`); the `executive_research` workflow proposes what to watch through a deterministic policy (next section). Because that workflow is LLM-driven and historically proposed feed URLs it never verified (most were dead — 404 / 403 / not-actually-a-feed), every `rss` target is validated at insert time (`monitoring.target_validation`): a URL that fetches and parses as a feed is kept; a public page that isn't a feed is converted to a scrape-backed `page_watch` when xcrawl can read it, otherwise rejected (HTTP 422 / tool error); SSRF-blocked or unparseable URLs are rejected outright and never handed to xcrawl. Non-`rss` types insert unchanged with no network I/O.\n\n### One watch, one card — and dismissals teach the watch\n\n`promote_signal_to_alert` stamps the `AlertEvent` with `dedup_hint=\"watch:<slug>\"`, which `alerts.pipeline` uses as the *alert* dedup key. A repeat from the same watch coalesces into the open card (`occurrence_count`, `last_seen_at`, severity max) rather than minting another, and re-pings only when severity rose into high/urgent — so a ticker that stays over its threshold or an incident that keeps updating no longer produces a new \"Needs you\" item every day. The signal-level `dedup_key` (stock's UTC-date bucket, vendor_status's `<updated>`) is untouched, so every observation still lands in `external_signals`. Dismissing a watch-sourced alert calls `store.record_dismissal(slug)` (`dismiss_count += 1`, `trust_score = max(0.2, trust × 0.8)`); approving calls `record_confirmation` (+0.05). `trust_score` discounts the briefing ranking and is shown to the Executive's alert review as evidence, alongside the newer signals for that watch (a \"Resolved\" incident state, a reversed move) that let it close the card with evidence.\n\n### What the research pass may put on the watchlist\n\nEvery watchlist row carries an `origin`: `manual` (the principal, via UI/API), `executive` (the chat tool acting on a request), `research` (the research pass added it on its own) or `research_proposed` (a pending suggestion). The `executive_research` workflow's watchlist pass no longer calls `add_watchlist_entry`; its only tool is `propose_watch` (slug, signal_type, target, `grounding_entity`, `rationale`, `certainty`), and `monitoring.research.watch_policy` decides what happens to each proposal from company data, not from the model's confidence in itself:\n\n- **Direct add** — the row lands live, `origin=research`, with quiet defaults the model cannot loosen (daily cadence — hourly for `vendor_status`, weekly for `page_watch`/`query` — `severity_floor=medium`, a keyword trigger built from the grounding entity + material-event words + the current-year priorities for feeds, `abs_change_pct_gte=5` for stocks). Requires the `grounding_entity` to name an external entity in company data — the company itself, a `competitive_landscape.primary_competitors` entry, or one of the profile's `vendors` / `tickers` (an initiative title or a current-year priority also grounds a proposal, but only ever to a suggestion: they are bags of common words a planted finding can echo) — *and* a score ≥ 4 on a fixed ledger: +2 entity in company data (mandatory), +1 entity already watched under another source, +1 target is the entity's own source (its ticker, its domain, or a primary-source host such as sec.gov), +1 finding confidence high, +1 verification confirmed, +1 cross-specialist consensus, ±1 from the policy's own approval history for that `(signal_type, grounding kind)` once it has ≥5 samples. The model's `certainty` can only downgrade a direct add to a suggestion; a `query` watch is always a suggestion; above `WATCHLIST_MAX_ENABLED` (40) enabled watches every add becomes a suggestion. At most `WATCHLIST_RESEARCH_MAX_DIRECT_ADDS` (2) per run.\n- **Suggestion** — anything that validates but misses the bar is inserted in `dry_run` (polls and records signals, never alerts) with `origin=research_proposed` and the rationale in `notes`, at most `WATCHLIST_RESEARCH_MAX_PROPOSALS` (2) per run. `/watchlist` shows them in a \"Suggested by the Executive\" section with Approve (`POST /watchlist/{slug}/approve` → `active`, `origin=research`) and Decline (`POST /watchlist/{slug}/decline` with a reason: `not_relevant` blacklists the entity, `wrong_source` blacklists only this target, `too_noisy` keeps it live with `severity_floor=high`). A suggestion nobody reviews within `WATCHLIST_PROPOSAL_TTL_DAYS` (14) is removed. The morning brief mentions the pending count in one line; a `watchlist_suggestions` alert nudges only once ≥3 suggestions have waited ≥7 days.\n- **Reject** — an invalid target, a second watch on the same site + signal type, a declined target, or a spent budget. Every decision is audited (`watchlist_research_added` / `_suggested` / `_rejected`) with the score and reasons; the stamp also lives in the row's `config_json._policy` so approve/decline/auto-disable can attribute the outcome.\n\n**Declines are remembered and enforced.** `watchlist_declines` is keyed by the normalized target (upper-cased ticker; URL with `https` forced, `www.` dropped, host and path lower-cased, query, fragment and trailing slash removed; free-text queries case- and whitespace-folded). A `not_relevant` decline also blacklists the *entity*: any later proposal whose `grounding_entity` names it is refused whatever the target. An explicit decline — the Decline button, \"Stop watching…\" on a research-added card, `remove_watchlist_entry` or `DELETE /watchlist/{slug}` on a research-origin row — is permanent; an unreviewed expiry may be re-proposed once after 90 days. The `propose_watch` handler refuses a declined target or entity before anything is fetched, so a new slug cannot route around a decline; the list is also rendered to the model as DECLINED. The routing pass that runs before the watchlist pass has no watchlist write tools at all (`add_watchlist_entry`, `tune_watchlist_entry`, `remove_watchlist_entry` are withheld from synthesis), and `tune_watchlist_entry` refuses `mode` / `enabled` changes on a pending suggestion — only the principal's approve or decline moves one out of review. Every URL-typed target (`rss`, `vendor_status`, `page_watch`) is checked against the SSRF guard at insert time, and a suggestion's `source_url` link is kept only when it is a public http(s) URL.\n\n**The policy learns from outcomes.** Approve, decline, expiry and auto-disable write `watchlist_policy_outcomes` rows keyed by `(signal_type, grounding kind, specialist)`; the pass renders the tallies (\"stock watches grounded in a competitor: 4 approved / 1 declined\"; \"proposals from cso: …\") and the score ledger reads them. The research turn also shows each existing watch's `origin`, `fired_count`, `dismiss_count` and `trust_score`.\n\n**Research watches retire themselves.** The scheduler's 15-minute sweep (`watch_policy.sweep`, alongside the alert expiry sweep) disables a `research`-origin watch — audited as `watchlist_auto_disabled`, re-enable from `/watchlist` — when it fired ≥5 alerts of which ≥2 were dismissed and trust ≤ 0.5, when a feed/page/status watch produced no signal in 30 days, or after 3 consecutive poll failures; the retired target is also recorded as a 90-day decline so the next run cannot re-add it under a new slug with fresh counters (a disabled row already counts as \"same source watched\"). Approve, decline and expiry are compare-and-act on \"still pending\", so a concurrent approve always wins over a decline or the sweep. Direct adds and auto-disables appear in the brief's \"handled overnight\" block as `watching` / `stopped_watching`. The research skip-if-unchanged fingerprint hashes only enabled, `active` rows, so approving or declining a suggestion never triggers a fresh 7-specialist run.\n\n### Invariants\n\n- Adapters are read-only — they never write upstream and never auto-execute.\n- Every `Signal` carries a deterministic `dedup_key` and a mandatory `provenance_url`.\n- Fetches are SSRF-guarded and bounded by `external_monitor_max_fetch_bytes`; xcrawl scrape (off by default, gated by `XCRAWL_ENABLED` + `XCRAWL_API_KEY`) is the one path that delegates the fetch to an external API.\n- Suppressed signals are still persisted so audits show the full picture.\n- A repeat from the same watch never becomes a second open card: the alert-level `watch:<slug>` key coalesces it, and only a severity escalation re-dispatches.\n- The research model never writes the watchlist: it proposes, deterministic policy adds (only when grounded in company data) or suggests, and a target the principal declined is refused at the handler.",
+ "markdown": "`openexecutive.monitoring` watches the outside world on a heartbeat and turns detected changes into briefing proposals via the same alert pipeline that handles inbound email and Slack.\n\nThe `external_monitor_scan` heartbeat (`__internal__` channel, default every 5 min) walks `list_watchlist(enabled_only=True)`, skipping rows fresher than their per-source cadence floor. For each due row it fires a read-only source adapter resolved from `_REGISTRY` by `signal_type`:\n\n- `vendor_status` — Statuspage Atom/RSS incident feeds (AWS, Stripe, GitHub, …). Reads each incident's current status out of the entry body, parses `<updated>` into `published_at`, and keys its dedup on `(entry id, <updated>)`; a **seeding** source (see below).\n- `rss` — generic Atom/RSS via feedparser (changelogs, layoffs.fyi, filings). Parses each entry's `<pubDate>`/`<updated>` into `published_at`; a **seeding** source (see below).\n- `stock` — Yahoo Finance chart endpoint; fires on `abs_change_pct_gte` moves.\n- `page_watch` — change-detection on a feed-less page. Fetches via the keyless httpx fetcher by default, or via xcrawl's scrape API when the row carries `config.fetch = \"xcrawl\"` — so JS-rendered / bot-blocked pages that publish no RSS (most modern news / marketing sites) are still monitorable.\n- `edgar` and the BILLED `query` web-search adapter.\n\nEach `Signal` is trigger-filtered, severity-clamped to the row's `[floor, ceiling]`, and INSERTed into `external_signals` where `UNIQUE(dedup_key)` drops replays. Survivors pass a suppression cascade (`baseline` → `stale` → `dry_run` → `below_floor` → capture-time relevance enrichment → promote), then `promote_signal_to_alert` builds an `AlertEvent` handed to `alerts.pipeline.schedule_evaluation` and surfaced as a `/today` proposal.\n\nEvery signal carries two timestamps that are never conflated: `captured_at` (when the monitor first saw it) and `published_at` (when the upstream says it happened — RSS `<pubDate>`, EDGAR filing date; null for `stock`, `page_watch`, `query`). Two freshness gates run first in the cascade, before anything that costs an LLM call. **Baseline:** the first poll that returns entries for a row whose adapter declares `seed_on_first_poll` (`rss`, `edgar`) records every entry already in the feed — trigger misses included, so the first entry that ever matches a keyword is news and a later, wider trigger can't resurface old ones — as `suppressed_baseline`, promotes nothing, and stamps `watchlist.baselined_at`, so a new watch reports what changes from now on instead of replaying the feed's back-catalogue (the same idea as `page_watch`'s first-observation baseline). It is keyed on `baselined_at` rather than `last_polled_at`, so a failed first fetch can't forfeit it; the claim and the recording are one transaction (a compare-and-swap on the stamp plus the rows, all-or-nothing), so of two overlapping scans exactly one records the back-catalogue and a failure part-way leaves nothing behind to replay; the other scan promotes only entries dated after that stamp (undated entries count as baseline, since the feed controls the date; entries dated more than a few minutes past its own clock are deferred rather than recorded); and baseline rows don't count against `max_signals_per_scan`, so a large feed can't be half-baselined. `vendor_status` used to sit outside both gates for a structural reason: its dedup key was `sha256(slug, entry id)`, and an incident's id never changes across its updates, so any suppressed insert muted that incident for good. Keying on `(entry id, <updated>)` instead (issue #90) makes a suppression cost one *state* of an incident rather than the incident, so both gates now apply to vendor feeds too — and an incident moving Investigating → Resolved mints a new key and surfaces, while re-polling an unchanged feed still dedups. Because a history feed's archive is mostly incidents resolved months ago, the adapter also carves live news out of its own baseline: it reads each incident's current status from the entry body (Statuspage renders the newest update first as `<strong>Resolved</strong>` / `Investigating` / `Monitoring` / … — the body is parsed by a real HTML parser, off the event loop, and the reading is deliberately asymmetric: any sign that the incident is over closes it, wherever it appears, while only a marked-up label can say it is still open. Working out which update is newest turned out to be something tag soup cannot be trusted to express, and every attempt reported a long-resolved incident as live) and exempts the ones still OPEN via the optional `promote_on_baseline` hook, so a watch added during an outage reports that outage on its first poll while the resolved archive is recorded as `suppressed_baseline`. An unrecognised status counts as closed — a vendor changing feed format must not be able to promote its whole archive at HIGH, and nothing is lost, since the next `<updated>` bump surfaces normally. An exempt entry must still pass the row's trigger filter (one that misses stays in the baseline, so widening a trigger later cannot resurface it) and is still judged by the stale gate below: the exemption buys an entry past the baseline, never past its own timestamp, because \"this is live\" is a reading of vendor-controlled markup and an entry the feed dates outside the age window is not news whatever that reading says. **Stale:** a signal whose `published_at` is older than `EXTERNAL_MONITOR_MAX_SIGNAL_AGE_DAYS` (default 7; `0` disables) at capture time is recorded as `suppressed_stale` and never promoted — a January article a feed resurfaces in September is not September news. An entry dated more than `EXTERNAL_MONITOR_MAX_FUTURE_SKEW_HOURS` ahead (default 24; `0` disables; `config_json.max_future_skew_hours` overrides it per row for calendar or maintenance feeds that legitimately date entries ahead) is deferred instead: skipped for the tick and not recorded (recording would burn its dedup key and let a feed mute an announcement for good by post-dating it), with one aggregated `external_signal_deferred` audit row per poll — carrying each held-back entry's summary and link, and emitted even if the poll later raises — then judged normally once the date passes. Inside the window, the alert body handed to triage carries `Published:` and `Discovered:` lines so the item is judged on when it happened. Adapters prefer a plausible date key over one more than a day in the future (and keep the future value when every key is implausible, so the pipeline defers it rather than waving an undated entry through), and the alert body collapses whitespace in the summary so no source can forge its own labeled body line.\n\nThe `query` adapter is a special case: it emits every web hit flat-LOW (it can't judge materiality per-hit), so for query signals enrichment runs BEFORE the floor gate and `_grade_query_severity` regrades from the relevance read (≥0.8 HIGH, ≥0.5 MEDIUM, else LOW). Without this, any query watch item with a `severity_floor` above LOW would suppress every hit — which is what left the Monitoring section empty even while standing queries were returning material findings.\n\nWhich lane a proposal lands in is decided by `briefing.ranking.categorize`: an unrouted, low/medium signal from a monitoring source (`stock`, `vendor_status`, `rss`, `query`, `edgar`, `page_watch`, or any `external:*` topic tag) is `monitoring` (the collapsible Monitoring section); a routed or high/urgent one is `action` (the \"Needs you\" queue). The triage prompt's External Signals rule covers all six source kinds so it trusts the source and emits the `external:*` tags that drive this split.\n\nThe watchlist is editable from chat (`add_watchlist_entry`, `tune_watchlist_entry`) and HTTP (`/watchlist`); the `executive_research` workflow proposes what to watch through a deterministic policy (next section). Because that workflow is LLM-driven and historically proposed feed URLs it never verified (most were dead — 404 / 403 / not-actually-a-feed), every `rss` target is validated at insert time (`monitoring.target_validation`): a URL that fetches and parses as a feed is kept; a public page that isn't a feed is converted to a scrape-backed `page_watch` when xcrawl can read it, otherwise rejected (HTTP 422 / tool error); SSRF-blocked or unparseable URLs are rejected outright and never handed to xcrawl. Non-`rss` types insert unchanged with no network I/O.\n\n### One watch, one card — and dismissals teach the watch\n\n`promote_signal_to_alert` stamps the `AlertEvent` with `dedup_hint=\"watch:<slug>\"`, which `alerts.pipeline` uses as the *alert* dedup key. A repeat from the same watch coalesces into the open card (`occurrence_count`, `last_seen_at`, severity max) rather than minting another, and re-pings only when severity rose into high/urgent — so a ticker that stays over its threshold or an incident that keeps updating no longer produces a new \"Needs you\" item every day. The signal-level `dedup_key` (stock's UTC-date bucket, vendor_status's `<updated>`) is untouched, so every observation still lands in `external_signals`. Dismissing a watch-sourced alert calls `store.record_dismissal(slug)` (`dismiss_count += 1`, `trust_score = max(0.2, trust × 0.8)`); approving calls `record_confirmation` (+0.05). `trust_score` discounts the briefing ranking and is shown to the Executive's alert review as evidence, alongside the newer signals for that watch (a \"Resolved\" incident state, a reversed move) that let it close the card with evidence.\n\n### What the research pass may put on the watchlist\n\nEvery watchlist row carries an `origin`: `manual` (the principal, via UI/API), `executive` (the chat tool acting on a request), `research` (the research pass added it on its own) or `research_proposed` (a pending suggestion). The `executive_research` workflow's watchlist pass no longer calls `add_watchlist_entry`; its only tool is `propose_watch` (slug, signal_type, target, `grounding_entity`, `rationale`, `certainty`), and `monitoring.research.watch_policy` decides what happens to each proposal from company data, not from the model's confidence in itself:\n\n- **Direct add** — the row lands live, `origin=research`, with quiet defaults the model cannot loosen (daily cadence — hourly for `vendor_status`, weekly for `page_watch`/`query` — `severity_floor=medium`, a keyword trigger of material-event words + the current-year priority terms for feeds — never the entity's own name, which appears in every entry's feed label and would fire on everything — and `abs_change_pct_gte=5` for stocks). Requires the `grounding_entity` to name an external entity in company data — the company itself, a `competitive_landscape.primary_competitors` entry, or one of the profile's `vendors` / `tickers` (an initiative title or a current-year priority also grounds a proposal, but only ever to a suggestion: they are bags of common words a planted finding can echo) — *and* a score ≥ 4 on a fixed ledger: +2 entity in company data (mandatory), +1 entity already watched under another source, +1 target is the entity's own source (the entity's ticker or one the profile tracks; a URL whose site label — `acme` in `status.acme.com` / `acme.co.uk`, never a subdomain or TLD — is the entity's; or a primary-source host such as sec.gov), +1 finding confidence high, +1 verification confirmed, +1 cross-specialist consensus, ±1 from the policy's own approval history for that `(signal_type, grounding kind)` once it has ≥5 samples. The model's `certainty` can only downgrade a direct add to a suggestion; a `query` watch is always a suggestion. At most `WATCHLIST_RESEARCH_MAX_DIRECT_ADDS` (2) per run. When one term appears in several sources the strongest kind wins (company > competitor > vendor > ticker > initiative > priority > watch label).\n- **Suggestion** — anything that validates, has a linked finding and scores at least 1 but misses the bar is inserted in `dry_run` (polls and records signals, never alerts) with `origin=research_proposed` and the rationale in `notes`, at most `WATCHLIST_RESEARCH_MAX_PROPOSALS` (2) per run. `/watchlist` shows them in a \"Suggested by the Executive\" section with Approve (`POST /watchlist/{slug}/approve` → `active`, `origin=research`) and Decline (`POST /watchlist/{slug}/decline` with a reason: `not_relevant` blacklists the entity, `wrong_source` blacklists only this target, `too_noisy` keeps the source live with `severity_floor=high` — the one way a suggestion goes live without an approve — and counts as a decline for calibration). A suggestion nobody reviews within `WATCHLIST_PROPOSAL_TTL_DAYS` (14) is removed. The morning brief mentions the pending count in one line; a `watchlist_suggestions` alert nudges only once ≥3 suggestions have waited ≥7 days — one card for the whole pile (an open card is refreshed in place; a dismissed one is not re-minted until the next ISO week), so acting on a suggestion never spawns another nudge.\n- **Reject** — an invalid target, a second watch on the same site + signal type (disabled rows included), a declined target or entity, nothing vouching for it (no linked finding, score 0), the enabled-watch ceiling `WATCHLIST_MAX_ENABLED` (40; suggestions poll too, so the ceiling stops them as well), or a spent budget. Every decision is audited (`watchlist_research_added` / `_suggested` / `_rejected`) with the score and reasons; the stamp also lives in the row's `config_json._policy` so approve/decline/auto-disable can attribute the outcome.\n\n**Declines are remembered and enforced.** `watchlist_declines` is keyed by the normalized target (upper-cased ticker; URL with `https` forced, `www.` dropped, host and path lower-cased, query, fragment and trailing slash removed; free-text queries case- and whitespace-folded). A `not_relevant` decline also blacklists the *entity*: any later proposal whose `grounding_entity` names it is refused whatever the target. An explicit decline — the Decline button, \"Stop watching…\" on a research-added card, `remove_watchlist_entry` or `DELETE /watchlist/{slug}` on a research-origin row — is permanent; an unreviewed expiry may be re-proposed once after 90 days. The `propose_watch` handler refuses a declined target or entity before anything is fetched, so a new slug cannot route around a decline; the list is also rendered to the model as DECLINED. The routing pass that runs before the watchlist pass has no watchlist write tools at all (`add_watchlist_entry`, `tune_watchlist_entry`, `remove_watchlist_entry` are withheld from synthesis), and `tune_watchlist_entry` refuses `mode` / `enabled` changes on a pending suggestion — only the principal's approve or decline moves one out of review. Every URL-typed target (`rss`, `vendor_status`, `page_watch`) is checked against the SSRF guard at insert time, and a suggestion's `source_url` link is kept only when it is a public http(s) URL.\n\n**The policy learns from outcomes.** Approve, decline, expiry and auto-disable write `watchlist_policy_outcomes` rows keyed by `(signal_type, grounding kind, specialist)`; the pass renders the tallies (\"stock watches grounded in a competitor: 4 approved / 1 declined\"; \"proposals from cso: …\") and the score ledger reads them. The research turn also shows each existing watch's `origin`, `fired_count`, `dismiss_count` and `trust_score`.\n\n**Research watches retire themselves.** The scheduler's 15-minute sweep (`watch_policy.sweep`, alongside the alert expiry sweep) disables a `research`-origin watch — audited as `watchlist_auto_disabled`, re-enable from `/watchlist` — when it fired ≥5 alerts of which ≥2 were dismissed and trust ≤ 0.5, or after 3 consecutive poll failures (silence is deliberately not a rule: an unchanged page or a healthy vendor is a working watch); the retired target is also recorded as a 90-day decline so the next run cannot re-add it under a new slug with fresh counters (a disabled row already counts as \"same source watched\"). Approve, decline and expiry are compare-and-act on \"still pending\", so a concurrent approve always wins over a decline or the sweep. Direct adds and auto-disables appear in the brief's \"handled overnight\" block as `watching` / `stopped_watching`. The research skip-if-unchanged fingerprint hashes only enabled, `active` rows, so approving or declining a suggestion never triggers a fresh 7-specialist run.\n\n### Invariants\n\n- Adapters are read-only — they never write upstream and never auto-execute.\n- Every `Signal` carries a deterministic `dedup_key` and a mandatory `provenance_url`.\n- Fetches are SSRF-guarded and bounded by `external_monitor_max_fetch_bytes`; xcrawl scrape (off by default, gated by `XCRAWL_ENABLED` + `XCRAWL_API_KEY`) is the one path that delegates the fetch to an external API.\n- Suppressed signals are still persisted so audits show the full picture.\n- A repeat from the same watch never becomes a second open card: the alert-level `watch:<slug>` key coalesces it, and only a severity escalation re-dispatches.\n- The research model never writes the watchlist: it proposes, deterministic policy adds (only when grounded in company data) or suggests, and a target the principal declined is refused at the handler.",
"mermaid": "flowchart TD\n ADD[\"add (chat tool / POST /watchlist / research)\"]\n VAL[\"target_validation: rss feed? → keep / convert→page_watch(xcrawl) / reject\"]\n WL[(\"watchlist\")]\n HB[\"external_monitor_scan heartbeat (~5 min)\"]\n AD[\"read-only adapters: vendor_status / rss / stock / query / edgar / page_watch (httpx | xcrawl)\"]\n SIG[(\"external_signals UNIQUE(dedup_key)\")]\n ENRICH[\"capture-time enrichment<br/>(relevance score + why_it_matters)\"]\n PROMO[\"promote_signal_to_alert\"]\n PIPE[\"alert pipeline (triage)\"]\n TODAY[\"/today proposals\"]\n ADD --> VAL\n VAL -->|\"insert valid rows\"| WL\n HB -->|\"walk enabled rows\"| WL\n WL -->|\"poll due rows\"| AD\n AD -->|\"emit Signal\"| SIG\n SIG -->|\"baseline / stale / dry_run / floor gates\"| ENRICH\n ENRICH -->|\"≥ relevance floor\"| PROMO\n PROMO --> PIPE\n PIPE --> TODAY\n class HB hot\n class WL storage\n class VAL compute\n class AD external\n class SIG storage\n class ENRICH compute\n class PROMO compute\n class PIPE compute\n class TODAY entry\n class ADD compute",
- "generated_at": "2026-09-12T11:00:48.077989+00:00"
+ "generated_at": "2026-09-12T11:06:42.982912+00:00"
}
diff --git a/packages/core/openexecutive/monitoring/research/watch_policy.py b/packages/core/openexecutive/monitoring/research/watch_policy.py
index 10a9d0cb..f6af6613 100644
--- a/packages/core/openexecutive/monitoring/research/watch_policy.py
+++ b/packages/core/openexecutive/monitoring/research/watch_policy.py
@@ -19,12 +19,15 @@ Two tiers:
``origin=research_proposed``; the principal approves or declines it on
``/watchlist``. This is the "not sure" case.
-Everything else is rejected, and a target the principal declined is
-rejected in the tool handler before the model can route around it with a
+A proposal with nothing vouching for it (no linked finding, score 0), one
+for a source already watched, one past the enabled-watch ceiling or the
+per-run budgets, is rejected; a target or entity the principal declined is
+refused in the tool handler before the model can route around it with a
new slug. Every decision is audited with its score and reasons.
"""
from __future__ import annotations
+import dataclasses
import logging
import re
from dataclasses import dataclass, field
@@ -77,8 +80,10 @@ TIER_DIRECT = "direct"
TIER_SUGGEST = "suggest"
TIER_REJECT = "reject"
-# Score needed to add without asking. See classify() for the ledger.
+# Score needed to add without asking, and the minimum for a suggestion to
+# be worth the principal's time at all. See classify() for the ledger.
DIRECT_THRESHOLD = 4
+SUGGEST_THRESHOLD = 1
# History only moves the score once the policy has a real sample.
_HISTORY_MIN_SAMPLES = 5
@@ -89,8 +94,7 @@ PRIMARY_SOURCE_HOSTS: frozenset[str] = frozenset({
"federalregister.gov", "eur-lex.europa.eu",
})
-# Grounding-vocabulary kinds, in the order a term is attributed when it
-# appears in more than one source.
+# Grounding-vocabulary kinds.
KIND_COMPANY = "company"
KIND_COMPETITOR = "competitor"
KIND_VENDOR = "vendor"
@@ -108,6 +112,11 @@ GROUNDING_KINDS: frozenset[str] = frozenset({
STRONG_GROUNDING_KINDS: frozenset[str] = frozenset({
KIND_COMPANY, KIND_COMPETITOR, KIND_VENDOR, KIND_TICKER,
})
+# When one term appears in several sources the strongest kind wins.
+_KIND_RANK: dict[str, int] = {
+ KIND_COMPANY: 7, KIND_COMPETITOR: 6, KIND_VENDOR: 5, KIND_TICKER: 4,
+ KIND_INITIATIVE: 3, KIND_PRIORITY: 2, KIND_WATCH: 1,
+}
# Material-event words every research feed trigger carries, so a competitor
# blog surfaces "we raised / we launched / pricing" and not every post.
@@ -142,11 +151,12 @@ _STOCK_DEFAULT_PCT = 5
_DISABLE_MIN_FIRED = 5
_DISABLE_MIN_DISMISSED = 2
_DISABLE_MAX_TRUST = 0.5
-_DEAD_SOURCE_DAYS = 30
-_DEAD_SOURCE_KINDS: frozenset[str] = frozenset({
- SOURCE_KIND_RSS, SOURCE_KIND_PAGE_WATCH, SOURCE_KIND_VENDOR_STATUS,
-})
+# "No signals for N days" is deliberately NOT a retirement rule: page_watch
+# and vendor_status emit nothing while the page is unchanged / the vendor
+# is healthy, which is exactly a working watch. Only poll failures say a
+# source is broken.
_POLL_FAILURES_TO_DISABLE = 3
+_POLL_HISTORY_TO_READ = 10
# Nudge the principal only when suggestions have piled up unreviewed.
_NUDGE_MIN_PENDING = 3
_NUDGE_MIN_AGE_DAYS = 7
@@ -244,7 +254,7 @@ def grounding_vocabulary(
n = _norm(term)
if len(n) < 2:
return
- if n not in vocab or (vocab[n] == KIND_WATCH and kind != KIND_WATCH):
+ if n not in vocab or _KIND_RANK[kind] > _KIND_RANK[vocab[n]]:
vocab[n] = kind
for item in existing:
@@ -341,19 +351,41 @@ def _is_own_source(proposal: WatchProposal, entity_term: str, vocabulary: dict[s
"""The target is the entity's own primary source: its ticker for
stock/edgar, its own domain for a URL, or an allowlisted primary host."""
if proposal.signal_type in (SOURCE_KIND_STOCK, SOURCE_KIND_EDGAR):
- return vocabulary.get(_norm(proposal.target)) in (KIND_TICKER, KIND_WATCH) or (
- _norm(proposal.target) == entity_term
- )
+ # The ticker is the entity itself, or one the profile explicitly
+ # tracks (`tickers`). A ticker that merely appears as some other
+ # watch's target says nothing about THIS entity.
+ target_norm = _norm(proposal.target)
+ return target_norm == entity_term or vocabulary.get(target_norm) == KIND_TICKER
host = registrable_domain(proposal.target)
if not host:
return False
if host in PRIMARY_SOURCE_HOSTS or any(host.endswith("." + h) for h in PRIMARY_SOURCE_HOSTS):
return True
- host_tokens = set(_TOKEN_RE.findall(host.replace(".", " ")))
+ # Only the site's own label counts ("acme" in status.acme.com / acme.co.uk);
+ # subdomain labels and the TLD never do, so "api" or ".cloud" cannot
+ # make an unrelated host look like the entity's.
entity_tokens = {
t for t in entity_term.split() if len(t) >= _MIN_PARTIAL_TOKEN and t not in _STOPWORDS
}
- return bool(entity_tokens & host_tokens)
+ return _site_label(host) in entity_tokens
+
+
+# Second-level labels under which the real site label sits one step deeper
+# (acme.co.uk → "acme").
+_PUBLIC_SECOND_LEVEL: frozenset[str] = frozenset({
+ "co", "com", "org", "net", "gov", "ac", "edu", "or", "ne", "gob",
+})
+
+
+def _site_label(host: str) -> str:
+ """The label that names the site: "acme" for acme.com, status.acme.com
+ and acme.co.uk. Empty for a bare TLD / IP-like host."""
+ labels = [label for label in host.split(".") if label]
+ if len(labels) < 2:
+ return ""
+ if len(labels) >= 3 and labels[-2] in _PUBLIC_SECOND_LEVEL and len(labels[-1]) == 2:
+ return labels[-3]
+ return labels[-2]
def _history_adjustment(
@@ -439,6 +471,19 @@ def classify(
reasons.append("same source already watched")
return Decision(TIER_REJECT, score, entity_term, kind, reasons)
+ enabled_count = sum(1 for i in ctx.existing if i.enabled)
+ if enabled_count >= ctx.settings.max_enabled:
+ # Suggestions poll too, so the ceiling has to stop them as well or
+ # it would latch: every run would add polling rows and no proposal
+ # could ever be direct again.
+ reasons.append(f"watchlist at its ceiling ({enabled_count} enabled)")
+ return Decision(TIER_REJECT, score, entity_term, kind, reasons)
+ if finding is None or score < SUGGEST_THRESHOLD:
+ # Nothing vouches for it: no linked finding, or neither company data
+ # nor evidence scored a point. Not worth the principal's time.
+ reasons.append("no evidence to put in front of the principal")
+ return Decision(TIER_REJECT, score, entity_term, kind, reasons)
+
tier = TIER_SUGGEST
if grounded and score >= DIRECT_THRESHOLD:
tier = TIER_DIRECT
@@ -451,10 +496,6 @@ def classify(
if tier == TIER_DIRECT and proposal.certainty != "confident":
tier = TIER_SUGGEST
reasons.append("model marked it unsure")
- enabled_count = sum(1 for i in ctx.existing if i.enabled)
- if tier == TIER_DIRECT and enabled_count >= ctx.settings.max_enabled:
- tier = TIER_SUGGEST
- reasons.append(f"watchlist at its ceiling ({enabled_count})")
return Decision(tier, score, entity_term, kind, reasons)
@@ -464,7 +505,7 @@ def classify(
def quiet_defaults(
- proposal: WatchProposal, entity_term: str, priority_words: list[str],
+ proposal: WatchProposal, priority_words: list[str],
) -> tuple[str, AlertSeverity, dict[str, Any]]:
"""``(cadence, severity_floor, trigger)`` a research row lands with.
@@ -476,11 +517,12 @@ def quiet_defaults(
if not isinstance(trigger.get("abs_change_pct_gte"), (int, float)):
trigger["abs_change_pct_gte"] = _STOCK_DEFAULT_PCT
elif proposal.signal_type in (SOURCE_KIND_RSS, SOURCE_KIND_PAGE_WATCH, SOURCE_KIND_QUERY):
+ # Material-event words + priority terms only. The entity's own name
+ # must NOT be a keyword: feed summaries are rendered as
+ # "[<feed label>] <title>", so a keyword equal to the label would
+ # match every entry and turn the trigger into a no-op.
existing_kw = trigger.get("keywords")
keywords: list[str] = [str(k) for k in existing_kw] if isinstance(existing_kw, list) else []
- for tok in entity_term.split():
- if len(tok) >= 3 and tok not in keywords:
- keywords.append(tok)
for kw in list(_EVENT_KEYWORDS) + priority_words:
if kw not in keywords:
keywords.append(kw)
@@ -536,7 +578,10 @@ def apply_proposals(
direct_left = max(0, ctx.settings.max_direct_adds)
suggest_left = max(0, ctx.settings.max_suggestions)
seen_targets: set[str] = set()
+ # Rows inserted earlier in this loop must count as "already watched" for
+ # later proposals; work on a copy so the caller's context is untouched.
live_existing = list(ctx.existing)
+ ctx = dataclasses.replace(ctx, existing=live_existing)
for proposal in proposals:
finding = (
@@ -549,7 +594,6 @@ def apply_proposals(
continue
seen_targets.add(proposal.normalized_target)
- ctx.existing = live_existing
decision = classify(proposal, finding, ctx)
if decision.tier == TIER_DIRECT and direct_left <= 0:
decision.tier = TIER_SUGGEST
@@ -569,7 +613,7 @@ def apply_proposals(
summaries.append(_summary(proposal, "rejected", decision.reasons[-1] if decision.reasons else ""))
continue
- cadence, floor, trigger = quiet_defaults(proposal, decision.entity, ctx.priority_terms)
+ cadence, floor, trigger = quiet_defaults(proposal, ctx.priority_terms)
config = dict(proposal.config)
config["_policy"] = _policy_stamp(decision, proposal, finding)
is_direct = decision.tier == TIER_DIRECT
@@ -680,7 +724,7 @@ def _consecutive_poll_failures(slug: str) -> int:
from openexecutive.audit.logger import get_audit_logger
rows = get_audit_logger().query(
- event_type="external_monitor_poll", q=f"Polled {slug} (", limit=_POLL_FAILURES_TO_DISABLE,
+ event_type="external_monitor_poll", q=f"Polled {slug} (", limit=_POLL_HISTORY_TO_READ,
)
except Exception:
return 0
@@ -695,22 +739,13 @@ def _consecutive_poll_failures(slug: str) -> int:
return n
-def _auto_disable_reason(item: WatchlistItem, now: datetime, db_path: Path | None) -> str:
+def _auto_disable_reason(item: WatchlistItem) -> str:
if (
item.fired_count >= _DISABLE_MIN_FIRED
and item.dismiss_count >= _DISABLE_MIN_DISMISSED
and item.trust_score <= _DISABLE_MAX_TRUST
):
return f"dismissed {item.dismiss_count} of {item.fired_count} alerts (trust {item.trust_score:.2f})"
- created = _parse(item.created_at)
- if (
- item.signal_type in _DEAD_SOURCE_KINDS
- and created is not None
- and now - created >= timedelta(days=_DEAD_SOURCE_DAYS)
- and item.id is not None
- and ms.count_signals_since(item.id, now - timedelta(days=_DEAD_SOURCE_DAYS), db_path=db_path) == 0
- ):
- return f"no signals in {_DEAD_SOURCE_DAYS} days"
if _consecutive_poll_failures(item.slug) >= _POLL_FAILURES_TO_DISABLE:
return f"{_POLL_FAILURES_TO_DISABLE} consecutive poll failures"
return ""
@@ -771,7 +806,7 @@ def _auto_disable(now: datetime, db_path: Path | None) -> int:
for item in ms.list_watchlist(enabled_only=True, db_path=db_path):
if item.origin != ORIGIN_RESEARCH or item.mode != MODE_ACTIVE or item.id is None:
continue
- reason = _auto_disable_reason(item, now, db_path)
+ reason = _auto_disable_reason(item)
if not reason:
continue
ms.set_enabled(item.id, False, db_path=db_path)
@@ -800,27 +835,37 @@ def _nudge_if_piled_up(now: datetime, db_path: Path | None) -> int:
pending = ms.list_pending_suggestions(db_path=db_path)
if len(pending) < _NUDGE_MIN_PENDING:
return 0
- oldest = pending[0]
- created = _parse(oldest.created_at)
+ created = _parse(pending[0].created_at)
if created is None or now - created < timedelta(days=_NUDGE_MIN_AGE_DAYS):
return 0
- from openexecutive.alerts.store import insert_alert
-
- key = f"{NUDGE_ALERT_SOURCE}:{oldest.slug}"
+ from openexecutive.alerts.store import coalesce_alert, insert_alert
+
+ # One card for the whole pile: an open card is refreshed in place
+ # (coalesce), and a card the principal already dismissed is not
+ # re-minted until next week — acting on one suggestion must never
+ # spawn another nudge.
+ dedup_key = f"{NUDGE_ALERT_SOURCE}:pending"
+ year, week, _ = now.isocalendar()
+ external_id = f"{dedup_key}:{year}-W{week:02d}"
lines = [f"- {i.slug} ({i.signal_type}) — {i.notes or i.target}"[:200] for i in pending[:10]]
+ body = (
+ "The Executive suggested these sources to monitor and is not sure "
+ "enough to add them on its own. Approve or decline them on the "
+ "Watch list page.\n\n" + "\n".join(lines)
+ )
+ if coalesce_alert(
+ source=NUDGE_ALERT_SOURCE, dedup_key=dedup_key, severity="medium", body=body, db_path=db_path,
+ ):
+ return 0
alert_id = insert_alert(
source=NUDGE_ALERT_SOURCE,
- external_id=key,
+ external_id=external_id,
severity="medium",
headline=f"{len(pending)} watch suggestions are waiting for you",
- body=(
- "The Executive suggested these sources to monitor and is not sure "
- "enough to add them on its own. Approve or decline them on the "
- "Watch list page.\n\n" + "\n".join(lines)
- ),
+ body=body,
suggested_action="Review the suggestions on /watchlist",
topic_tags=["watchlist"],
- dedup_key=key,
+ dedup_key=dedup_key,
db_path=db_path,
)
return 1 if alert_id else 0
@@ -828,6 +873,7 @@ def _nudge_if_piled_up(now: datetime, db_path: Path | None) -> int:
__all__ = [
"DIRECT_THRESHOLD",
+ "SUGGEST_THRESHOLD",
"EVENT_ADDED",
"EVENT_AUTO_DISABLED",
"EVENT_REJECTED",
diff --git a/packages/core/openexecutive/monitoring/store.py b/packages/core/openexecutive/monitoring/store.py
index 28aba974..ea38016a 100644
--- a/packages/core/openexecutive/monitoring/store.py
+++ b/packages/core/openexecutive/monitoring/store.py
@@ -719,7 +719,10 @@ def is_declined(
return True
if declined_at.tzinfo is None:
declined_at = declined_at.replace(tzinfo=UTC)
- return (now or datetime.now(UTC)) - declined_at < timedelta(days=DECLINE_EXPIRED_RETRY_DAYS)
+ now = now or datetime.now(UTC)
+ if now.tzinfo is None:
+ now = now.replace(tzinfo=UTC)
+ return now - declined_at < timedelta(days=DECLINE_EXPIRED_RETRY_DAYS)
def record_policy_outcome(
diff --git a/packages/core/openexecutive/orchestrator/watchlist_tools.py b/packages/core/openexecutive/orchestrator/watchlist_tools.py
index 71280cd3..86ff72df 100644
--- a/packages/core/openexecutive/orchestrator/watchlist_tools.py
+++ b/packages/core/openexecutive/orchestrator/watchlist_tools.py
@@ -564,9 +564,12 @@ async def handle_propose_watch(tool_input: dict[str, Any], collector: list[Any])
raw_index = tool_input.get("finding_index")
finding_index: int | None
try:
- finding_index = int(raw_index) - 1 if raw_index is not None else None
+ # 1-based "#N" from the findings turn; 0 or negative means "none".
+ finding_index = int(raw_index) - 1 if raw_index is not None and int(raw_index) >= 1 else None
except (TypeError, ValueError):
finding_index = None
+ if any(getattr(p, "slug", "") == slug for p in collector):
+ return _err(tool, f"slug {slug!r} was already proposed this run")
collector.append(WatchProposal(
slug=slug,
diff --git a/packages/core/tests/unit/test_watch_policy.py b/packages/core/tests/unit/test_watch_policy.py
index aba9a360..e0faa0c1 100644
--- a/packages/core/tests/unit/test_watch_policy.py
+++ b/packages/core/tests/unit/test_watch_policy.py
@@ -211,12 +211,40 @@ def test_same_site_already_watched_is_rejected(db: Path) -> None:
assert d.tier == wp.TIER_REJECT and "already watched" in d.reasons[-1]
-def test_ceiling_turns_direct_into_suggestion(db: Path) -> None:
+def test_ceiling_rejects_adds_and_suggestions(db: Path) -> None:
for i in range(3):
ms.insert_watchlist_item(slug=f"stock-x{i}", signal_type="stock", target=f"X{i}", db_path=db)
ctx = _ctx(ms.list_watchlist(db_path=db), settings=wp.PolicySettings(max_enabled=3))
d = wp.classify(_proposal(), _finding(), ctx)
- assert d.tier == wp.TIER_SUGGEST and "ceiling" in d.reasons[-1]
+ assert d.tier == wp.TIER_REJECT and "ceiling" in d.reasons[-1]
+ unsure = _proposal(grounding_entity="Initech", target="https://initech.com/feed.xml", certainty="unsure")
+ assert wp.classify(unsure, _finding(), ctx).tier == wp.TIER_REJECT
+
+
+def test_nothing_vouching_is_rejected_not_suggested() -> None:
+ bare = _proposal(grounding_entity="", target="https://randomblog.example/feed", certainty="unsure",
+ finding_index=None)
+ assert wp.classify(bare, None, _ctx()).tier == wp.TIER_REJECT
+ weak = _proposal(grounding_entity="Initech", target="https://initech.com/feed.xml", certainty="unsure")
+ assert wp.classify(weak, _finding(confidence="medium"), _ctx()).tier == wp.TIER_REJECT
+ assert wp.classify(weak, _finding(confidence="high"), _ctx()).tier == wp.TIER_SUGGEST
+
+
+def test_own_source_uses_the_site_label_only() -> None:
+ assert wp._site_label("status.acme.com") == "acme"
+ assert wp._site_label("acme.co.uk") == "acme"
+ assert wp._site_label("api.unrelated-vendor.com") == "unrelated-vendor"
+ p = _proposal(slug="pw", signal_type="page_watch", target="https://api.unrelated.com/pricing",
+ grounding_entity="Launch Helios API")
+ assert "own source" not in " ".join(wp.classify(p, _finding(), _ctx()).reasons)
+ p2 = _proposal(slug="stock-msft", signal_type="stock", target="MSFT", grounding_entity="Acme Corp")
+ assert "own source" not in " ".join(wp.classify(p2, _finding(), _ctx()).reasons)
+
+
+def test_vocabulary_prefers_the_strongest_kind() -> None:
+ profile = CompanyProfile.model_validate({"name": "Acme", "vendors": ["Acme"], "tickers": ["ACME"]})
+ vocab = wp.grounding_vocabulary(profile, [SimpleNamespace(title="Acme")], [])
+ assert vocab["acme"] == wp.KIND_COMPANY
def test_history_adjusts_only_with_enough_samples() -> None:
@@ -233,16 +261,17 @@ def test_history_adjusts_only_with_enough_samples() -> None:
def test_quiet_defaults_add_keywords_and_medium_floor() -> None:
- cadence, floor, trigger = wp.quiet_defaults(_proposal(), "acme corp", ["enterprise"])
+ cadence, floor, trigger = wp.quiet_defaults(_proposal(), ["accounts"])
assert cadence == "daily" and floor.value == "medium"
kws = trigger["keywords"]
- assert kws[:2] == ["acme", "corp"] and "pricing" in kws and "enterprise" in kws
- _, _, stock_trigger = wp.quiet_defaults(
- _proposal(signal_type="stock", target="ACME"), "acme", [],
- )
+ assert "pricing" in kws and "accounts" in kws
+ # The entity's own name is never a keyword: feed summaries carry the
+ # feed label, so it would match every entry.
+ assert "acme" not in kws and "corp" not in kws
+ _, _, stock_trigger = wp.quiet_defaults(_proposal(signal_type="stock", target="ACME"), [])
assert stock_trigger == {"abs_change_pct_gte": 5}
cadence_pw, _, _ = wp.quiet_defaults(
- _proposal(signal_type="page_watch", target="https://acme.com/pricing"), "acme", [],
+ _proposal(signal_type="page_watch", target="https://acme.com/pricing"), [],
)
assert cadence_pw == "weekly"
@@ -253,7 +282,7 @@ def test_quiet_defaults_add_keywords_and_medium_floor() -> None:
def test_apply_adds_direct_and_files_suggestion(db: Path) -> None:
- findings = [_finding(), _finding(title="Initech raised", summary="Initech raised.", confidence="medium")]
+ findings = [_finding(), _finding(title="Initech raised", summary="Initech raised.", confidence="high")]
proposals = [
_proposal(),
_proposal(slug="rss-initech", target="https://initech.com/feed.xml",
@@ -289,6 +318,8 @@ def test_apply_honours_budgets_and_duplicate_targets(db: Path) -> None:
]
assert "duplicate" in out[1]["result_preview"]
assert "budget" in out[5]["result_preview"]
+ # The caller's context is not mutated by the run.
+ assert ctx.existing == []
# --------------------------------------------------------------------- #
@@ -355,6 +386,11 @@ async def test_propose_handler_refuses_declined_target_under_new_slug(
}, collector)
assert '"queued": "stock-acme"' in ok
assert len(collector) == 2 and collector[-1].finding_index == 0
+ dup = await wt.handle_propose_watch({
+ "slug": "stock-acme", "signal_type": "stock", "target": "ACME2",
+ "grounding_entity": "Acme Corp", "rationale": "y", "certainty": "confident", "finding_index": 0,
+ }, collector)
+ assert "already proposed" in dup and len(collector) == 2
# --------------------------------------------------------------------- #
@@ -409,13 +445,13 @@ def test_sweep_expires_a_suggestion_that_already_recorded_signals(db: Path) -> N
assert ms.list_signals_for_watchlist(wid, db_path=db) == []
-def test_sweep_auto_disables_noisy_and_dead_research_watches(db: Path) -> None:
+def test_sweep_auto_disables_noisy_research_watches_only(db: Path) -> None:
import sqlite3
ms.insert_watchlist_item(slug="rss-noisy", signal_type="rss", target="https://noisy.com/feed",
origin=ORIGIN_RESEARCH, db_path=db)
- ms.insert_watchlist_item(slug="rss-dead", signal_type="rss", target="https://dead.com/feed",
- origin=ORIGIN_RESEARCH, db_path=db)
+ ms.insert_watchlist_item(slug="pw-quiet", signal_type="page_watch", target="https://quiet.com/pricing",
+ origin=ORIGIN_RESEARCH, db_path=db) # silent = unchanged page, still working
ms.insert_watchlist_item(slug="rss-mine", signal_type="rss", target="https://mine.com/feed",
db_path=db) # manual: never auto-disabled
with sqlite3.connect(db) as conn:
@@ -423,12 +459,25 @@ def test_sweep_auto_disables_noisy_and_dead_research_watches(db: Path) -> None:
"UPDATE watchlist SET fired_count = 6, dismiss_count = 3, trust_score = 0.4 "
"WHERE slug IN ('rss-noisy', 'rss-mine')"
)
- _backdate(db, "rss-dead", 31)
- _backdate(db, "rss-mine", 31)
+ _backdate(db, "pw-quiet", 45)
counts = wp.sweep(datetime.now(UTC), db_path=db)
- assert counts["disabled"] == 2
+ assert counts["disabled"] == 1
enabled = {w.slug: w.enabled for w in ms.list_watchlist(db_path=db)}
- assert enabled == {"rss-noisy": False, "rss-dead": False, "rss-mine": True}
+ assert enabled == {"rss-noisy": False, "pw-quiet": True, "rss-mine": True}
+
+
+def test_sweep_auto_disables_after_consecutive_poll_failures(db: Path) -> None:
+ from openexecutive.audit import log_event
+
+ ms.insert_watchlist_item(slug="rss-broken", signal_type="rss", target="https://broken.com/feed",
+ origin=ORIGIN_RESEARCH, db_path=db)
+ for _ in range(2):
+ log_event("external_monitor_poll", "Polled rss-broken (rss) — FAILED", actor="external_monitor",
+ details={"watchlist_slug": "rss-broken", "failed": True})
+ assert wp.sweep(datetime.now(UTC), db_path=db)["disabled"] == 0
+ log_event("external_monitor_poll", "Polled rss-broken (rss) — FAILED", actor="external_monitor",
+ details={"watchlist_slug": "rss-broken", "failed": True})
+ assert wp.sweep(datetime.now(UTC), db_path=db)["disabled"] == 1
def test_sweep_nudges_once_suggestions_pile_up(db: Path) -> None:
@@ -441,10 +490,19 @@ def test_sweep_nudges_once_suggestions_pile_up(db: Path) -> None:
)
assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0 # too fresh
_backdate(db, "rss-s0", 8)
+ _backdate(db, "rss-s1", 8)
+ ms.insert_watchlist_item(
+ slug="rss-s3", signal_type="rss", target="https://s3.com/feed",
+ mode=MODE_DRY_RUN, origin=ORIGIN_RESEARCH_PROPOSED, db_path=db,
+ )
assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 1
- assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0 # coalesced
+ assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0 # coalesced into the open card
+ # Acting on the oldest suggestion must not spawn another nudge.
+ first = ms.get_watchlist_item_by_slug("rss-s0", db_path=db)
+ assert first is not None and first.id is not None and ms.approve_suggestion(first.id, db_path=db)
+ assert wp.sweep(datetime.now(UTC), db_path=db)["nudged"] == 0
alerts = [a for a in list_alerts(limit=10, db_path=db) if a.source == wp.NUDGE_ALERT_SOURCE]
- assert len(alerts) == 1 and "3 watch suggestions" in alerts[0].headline
+ assert len(alerts) == 1 and "4 watch suggestions" in alerts[0].headline
def test_initiative_or_priority_grounding_is_never_direct() -> None:
diff --git a/packages/core/tests/unit/test_watchlist_routes.py b/packages/core/tests/unit/test_watchlist_routes.py
index 308afb0d..94ec44d0 100644
--- a/packages/core/tests/unit/test_watchlist_routes.py
+++ b/packages/core/tests/unit/test_watchlist_routes.py
@@ -94,12 +94,15 @@ def test_decline_defaults_to_not_relevant_without_a_body(client: TestClient, db:
def test_decline_too_noisy_keeps_it_live_at_a_high_floor(client: TestClient, db: Path) -> None:
_suggest(db)
res = client.post("/watchlist/rss-initech/decline", json={"reason": "too_noisy"})
- assert res.status_code == 200 and res.json()["result"] == "kept_quiet"
+ assert res.status_code == 200 and res.json()["result"] == "kept_high_floor"
row = ms.get_watchlist_item_by_slug("rss-initech", db_path=db)
assert row is not None
assert row.mode == "active" and row.origin == "research" and row.severity_floor.value == "high"
assert ms.list_declines(db_path=db) == []
- assert ms.policy_outcome_counts(db_path=db) == {("rss", ""): {"approved": 1}}
+ # For calibration it is a decline: the principal objected to the guess.
+ assert ms.policy_outcome_counts(db_path=db) == {("rss", ""): {"declined": 1}}
+ # A second decline / approve now 409s: no longer pending.
+ assert client.post("/watchlist/rss-initech/decline", json={"reason": "too_noisy"}).status_code == 409
def test_decline_validates_reason_and_state(client: TestClient, db: Path) -> None:
diff --git a/packages/ui/src/app/watchlist/page.tsx b/packages/ui/src/app/watchlist/page.tsx
index fa61f7b0..fc8438b6 100644
--- a/packages/ui/src/app/watchlist/page.tsx
+++ b/packages/ui/src/app/watchlist/page.tsx
@@ -571,10 +571,11 @@ export default function WatchlistPage() {
markBusy(slug, true);
try {
const res = await declineWatchSuggestion(slug, reason);
- if (res.result === "kept_quiet") {
- refresh();
- } else {
+ if (res.result === "removed") {
setItems((prev) => prev.filter((it) => it.slug !== slug));
+ } else {
+ // too_noisy: the row went live with a high floor — reload it.
+ refresh();
}
} catch (e) {
setError(e instanceof Error ? e.message : "Decline failed");
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index 672da5a2..426d052f 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -2902,8 +2902,8 @@ export async function approveWatchSuggestion(slug: string): Promise<WatchlistIte
export interface WatchDeclineResponse {
slug: string;
reason: string;
- /** "removed" (declined + deleted) or "kept_quiet" (too_noisy → live with a high floor). */
- result: "removed" | "kept_quiet" | string;
+ /** "removed" (declined + deleted) or "kept_high_floor" (too_noisy → live, only high-severity signals surface). */
+ result: "removed" | "kept_high_floor" | string;
}
/** Decline a research suggestion. The reason picks the remedy server-side. */