Skip to content

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

Merge remote-tracking branch 'origin/main' into claude/81md-review-backlog-te066i

Claudecf4caa264e1b
diff --cc packages/core/openexecutive/api/routes/knowledge.py
index dd00766e,43c8581e..15603caa
--- a/packages/core/openexecutive/api/routes/knowledge.py
+++ b/packages/core/openexecutive/api/routes/knowledge.py
@@@ -544,7 -545,7 +545,12 @@@ async def search_knowledge
`retrieve()` produces. Intended for the Knowledge UI's Query mode and
for tuning the knowledge base offline.
"""
- from openexecutive.knowledge.retriever import DOMAIN_ALIASES
- from openexecutive.knowledge.retriever import DOMAIN_ALIASES, _with_general
++ from openexecutive.knowledge.retriever import (
++ DOMAIN_ALIASES,
++ _default_review_store,
++ _with_general,
++ )
++ from openexecutive.knowledge.review_store import ContentType
from openexecutive.knowledge.store import ChromaDBStore
if not body.query.strip():
@@@ -595,6 -601,6 +606,43 @@@
except Exception:
return []
++ # Mirror `retrieve()`'s review gate. Withheld = pending or rejected; the
++ # chat path drops those before a specialist ever sees them, so a panel
++ # that advertises itself as showing "what RAG would surface" must drop
++ # them too — otherwise it reports knowledge the Executive cannot use.
++ # Resolved once per request, via the retriever's own resolver so both
++ # paths read the same database. Company docs are never registered in
++ # `review_items`, so the company bucket is deliberately not filtered.
++ #
++ # Degrades to "nothing withheld" rather than failing, matching the
++ # per-collection `except` above: this is a read-only diagnostic, and a
++ # broken panel helps nobody. `retrieve()` is the enforcing gate and does
++ # NOT degrade. The exists() check matters on its own — `sqlite3.connect`
++ # creates the file, and a diagnostic read must not materialise a database.
++ def _withheld_sets() -> tuple[set[str], set[str]]:
++ from openexecutive.memory.episodic import DB_PATH
++
++ if not DB_PATH.exists():
++ return set(), set()
++ try:
++ rs = _default_review_store()
++ return (
++ rs.get_withheld_filenames(ContentType.BUILTIN),
++ rs.get_withheld_source_ids(),
++ )
++ except Exception:
++ return set(), set()
++
++ _withheld_builtin, _withheld_external = _withheld_sets()
++
++ def _is_withheld(row: dict[str, object]) -> bool:
++ md = row.get("metadata") or {}
++ md_dict = md if isinstance(md, dict) else {}
++ source_id = md_dict.get("source_id")
++ if source_id:
++ return source_id in _withheld_external
++ return md_dict.get("filename") in _withheld_builtin
++
builtin_hits: list[SearchHit] = []
external_hits: list[SearchHit] = []
want_builtin = "builtin" in include
@@@ -607,7 -613,7 +655,11 @@@
wanted_builtin = n_builtin if want_builtin else 0
wanted_external = n_external if want_external else 0
window = (wanted_builtin + wanted_external) * _BUILTIN_OVERFETCH_MULTIPLIER
-- raw = _query_collection(ChromaDBStore.BUILTIN_COLLECTION, window)
++ raw = [
++ r
++ for r in _query_collection(ChromaDBStore.BUILTIN_COLLECTION, window)
++ if not _is_withheld(r)
++ ]
for r in raw:
md = r.get("metadata") or {}
md_dict = md if isinstance(md, dict) else {}
@@@ -632,7 -647,7 +693,13 @@@
failure_hits: list[SearchHit] = []
if "failures" in include:
failure_hits = _hits_from_chroma(
-- _query_collection(ChromaDBStore.FAILURES_COLLECTION, n_failures)
++ [
++ r
++ for r in _query_collection(
++ ChromaDBStore.FAILURES_COLLECTION, n_failures
++ )
++ if not _is_withheld(r)
++ ]
)
return KnowledgeSearchResponse(
diff --cc packages/core/openexecutive/architecture/architecture-facts.yaml
index fa256e2c,029d400d..690ba2c2
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@@ -2151,110 -2201,10 +2201,115 @@@ external_monitoring
review:
store: openexecutive.knowledge.review_store.ReviewStore (shares episodic_memory.db).
+ default_state: |
+ Shipped content is TRUSTED ON ARRIVAL. `sync_builtin_registrations` and
+ `sync_external_registrations` register `approved` with a NULL
+ `reviewed_at`, so a new instance starts with an EMPTY review queue.
+ Before this, all 81 built-in docs registered `pending`, and a brand-new
+ box greeted its first user with "81 items need review" — work nobody had
+ a basis to do on day one, gating nothing.
+
+ PROVENANCE IS AN EXPLICIT COLUMN FED BY A COMMITTED MANIFEST — never
+ inferred, and never re-derived from the filesystem. Two mistakes were
+ caught here in review, both of which silently approved a user's own
+ unvetted document and labelled it "shipped" in the UI:
+ 1. Keying on (pending, reviewed_at NULL). A brand-new upload via
+ `POST /knowledge/builtin` -> `ReviewStore.register()` has exactly
+ that shape.
+ 2. Keying on "a .md file exists under knowledge/builtin/". That route
+ writes the user's file into that SAME tree
+ (`api/routes/knowledge._resolve_path`), so a directory scan re-flagged
+ uploads as shipped on the next boot.
+ So `review_items.trusted_default` (INTEGER, default 0; additive ALTER for
+ older DBs) is set to 1 only for paths listed in
+ `knowledge/shipped_manifest.py::SHIPPED_BUILTIN_FILES`, which
+ `sync_builtin_registrations` iterates instead of rglobbing the tree.
+ Regenerate that manifest when adding or removing a built-in doc;
+ `test_shipped_manifest_matches_git` fails on drift. `register()` never
+ sets the flag, so user content stays `trusted_default = 0` forever.
+
+ Two states, read together:
+ - trusted_default=1, approved, reviewed_at IS NULL -> shipped, unvetted
+ - approved + reviewed_at set -> an SME signed off
+ `count_trusted_defaults_by_domain()` counts the first kind and drives the
+ "Curate N" affordance. The UI reads `trusted_default` off the API rather
+ than inferring it.
+
+ MIGRATION ORDER MATTERS. `ReviewStore.backfill_trusted_defaults()` must run
+ AFTER both registration syncs, because it only touches rows they have
+ flagged `trusted_default = 1`. Call sites: `api/main.py` lifespan and
+ `clients/slots._ensure_schemas`. A `review_meta` marker row
+ (`trusted_defaults_backfill_v1`) makes it fire exactly once, written under
+ `BEGIN IMMEDIATE` with `INSERT OR IGNORE` so two workers booting together
+ cannot raise a UNIQUE violation out of the lifespan. The marker lives in
+ `review_meta` rather than `PRAGMA user_version` because
+ `episodic_memory.db` is shared with episodic memory, alerts, people,
+ talent and more.
+
+ The migration's rule is NO SHIPPED DOC LOSES RETRIEVABILITY ON UPGRADE.
+ Its only exclusion is `reviewed_at IS NULL` (which `set_status` always
+ stamps, so every explicit approve/reject is skipped). Notes and
- annotations deliberately do NOT hold a row back: `retrieve_context`
++ annotations deliberately do NOT hold a row back: `retrieve`
+ injects annotations by DOMAIN regardless of item status, so withholding an
+ annotated doc would feed the Executive a correction to a document it can
+ no longer see.
effect_on_retrieval: |
- Rejected items are filtered out of every retrieval. Approved items
- can be promoted in priority. The Executive never sees pending items
- until an SME approves them.
+ WITHHELD = `pending` OR `rejected`. `get_withheld_filenames(content_type)`
+ is the single query the retrieval path uses; it replaced the old
+ rejected-only lookups, which no longer exist.
+
- Both `retrieve_context` and `retrieve_failures` apply it. The failures
++ Both `retrieve` and `retrieve_failures` apply it, and so does
++ `POST /knowledge/search` — the diagnostic panel documents itself as
++ showing what RAG would surface, so it drops withheld rows too. It
++ degrades to unfiltered if review state is unreadable (a read-only
++ diagnostic should not 500, and must not create the DB file);
++ `retrieve` is the enforcing gate and does NOT degrade. The failures
+ path is the one that used to leak: failure case studies are registered
+ for review but indexed into FAILURES_COLLECTION, and `retrieve_failures`
+ consulted no review state at all, so rejecting a failure case study did
+ nothing.
+
+ The gate is now real. It could only be made real once shipped content
+ defaulted to approved — enforcing it beforehand would have left a fresh
+ instance with zero retrievable knowledge.
+
+ `needs_revision` is deliberately NOT withheld. `touch_modified` flips an
+ item there on ANY content edit, so withholding it would make editing a
+ file in the knowledge UI silently delete it from retrieval. Approved
+ items can still be promoted in priority.
+
+ The filter keys on bare `filename` (that is what Chroma metadata carries),
+ not `item_id`. All 81 built-in basenames are unique across domains and a
+ unit test pins that invariant — a duplicate basename would make a withheld
+ item in one domain silently suppress another domain's file.
+ curation: |
+ Opt-in, per domain. `POST /review/curate {domain, action: start|stop}`
+ moves a domain's untouched trusted defaults to `pending` (and back).
+ Both directions require `trusted_default = 1 AND reviewed_at IS NULL`, so
+ neither a user's own upload nor an item an SME decided on is ever moved.
+
+ `domain` is REQUIRED — there is no "curate everything" selector. While a
+ domain is curated its items are withheld, so no single call may take the
+ whole knowledge base away from the Executive. The UI confirms with the
+ exact count before starting.
+ bulk_approve: |
+ `POST /review/bulk-approve` selects by `domain` (min_length=1 —
+ the store reads a falsy domain as "no filter", so an empty string would
+ widen a scoped call to every pending item), an explicit `item_ids` list
+ (over BULK_MAX_IDS=500 raises rather than silently truncating), or
+ `all_pending: true`. A call with no selector is a 400 —
+ the same "a bulk call must always carry a selector" rule as
+ `/alerts/bulk-ack`. Returns `{approved_count, item_ids}` and writes a
+ `review_bulk_approve` audit event; `/review/curate` writes `review_curate`.
+ reset_and_slots: |
+ `reset_all_state` wipes `review_annotations` + `review_items` (child
+ first) and re-registers the shipped docs — built-in and any ingested OER
+ sources — so a factory reset no longer
+ inherits the previous operator's approvals and rejections — a stale
+ rejection would otherwise keep suppressing retrieval on the new box.
+ `clients.slots._ensure_schemas` runs `sync_builtin_registrations` after
+ `initialize_db`, so a newly activated client slot has its trusted
+ defaults immediately instead of an empty table until the next restart.
workflows:
contract: Structured input → ordered named steps → rendered Markdown artifact.
diff --cc packages/core/openexecutive/architecture/prebuilt/api.json
index 5caafdb4,7371b91c..97e3f071
--- a/packages/core/openexecutive/architecture/prebuilt/api.json
+++ b/packages/core/openexecutive/architecture/prebuilt/api.json
@@@ -1,7 -1,7 +1,7 @@@
{
"section_id": "api",
"title": "API Reference",
- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
++ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the eight specialist domains or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
"mermaid": null,
- "generated_at": "2026-09-16T09:58:32.694362+00:00"
- "generated_at": "2026-09-16T10:00:04.693907+00:00"
++ "generated_at": "2026-09-16T11:09:07.698247+00:00"
}
diff --cc packages/core/openexecutive/architecture/prebuilt/rag.json
index 54d1c3c6,b23e9b3b..7076b901
--- a/packages/core/openexecutive/architecture/prebuilt/rag.json
+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json
@@@ -1,7 -1,7 +1,7 @@@
{
"section_id": "rag",
"title": "Knowledge & RAG",
- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Five collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve_context` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `filename` metadata Chroma carries, which relies on built-in basenames being unique across domains — a unit test pins that.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",
- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Five collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Chat/email attachments share the collection but are namespaced `attachment:<name>`, since the sender picks that name and an unprefixed one would overwrite the curated document it collides with; they also carry a non-specialist domain, so they are not retrieved (see Integrations).\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",
++ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. Five collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Chat/email attachments share the collection but are namespaced `attachment:<name>`, since the sender picks that name and an unprefixed one would overwrite the curated document it collides with; they also carry a non-specialist domain, so they are not retrieved (see Integrations).\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The ninth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint and in the UI's picker). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `filename` metadata Chroma carries, which relies on built-in basenames being unique across domains — a unit test pins that.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.",
"mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class Failures storage\n class Research storage\n class Inject hot",
- "generated_at": "2026-09-16T09:20:23.351660+00:00"
- }
- "generated_at": "2026-09-16T10:00:04.693907+00:00"
++ "generated_at": "2026-09-16T11:05:57.673913+00:00"
+ }
diff --cc packages/core/openexecutive/architecture/prebuilt/review.json
index 4e15d18a,dbcb4711..d993bf00
--- a/packages/core/openexecutive/architecture/prebuilt/review.json
+++ b/packages/core/openexecutive/architecture/prebuilt/review.json
@@@ -1,7 -1,7 +1,7 @@@
{
"section_id": "review",
"title": "SME Knowledge Review",
- "markdown": "Knowledge that reaches a specialist passes through a subject-matter-expert (SME) review gate. The queue and its decisions live in `openexecutive.knowledge.review_store.ReviewStore`, which shares the `./episodic_memory.db` SQLite database with episodic memory.\n\n### Shipped knowledge is trusted on arrival\n\nThe ~81 Markdown files under `knowledge/builtin/` are curated upstream and ship with the product. They register as **trusted defaults** — `approved`, with a NULL `reviewed_at` — so a new instance starts with an **empty** review queue and the Executive can draw on that material immediately. The same applies to manifest-listed external (OER) sources.\n\nProvenance is an explicit `trusted_default` column, fed by a committed manifest — it is never inferred. That matters more than it looks: a document a user creates through the knowledge UI is *also* `pending` with a NULL `reviewed_at`, **and** it is written into the same `knowledge/builtin/` tree the shipped docs live in. So neither the status shape nor the presence of a file on disk can tell the two apart. `sync_builtin_registrations` walks `SHIPPED_BUILTIN_FILES` rather than the directory, and `register()` — the path user uploads take — never sets the flag.\n\nRead together with `reviewed_at`:\n\n| State | `reviewed_at` | Meaning |\n|---|---|---|\n| `approved` + `trusted_default` | *NULL* | **Trusted default** — shipped with the product, nobody here has vetted it |\n| `approved` | set | An SME signed off, and can promote the item in priority |\n| `pending` | — | Deliberately queued for curation |\n| `rejected` | set | An SME rejected it |\n| `needs_revision` | — | Was decided on; the content has since been edited |\n\nAn install that predates this registers its shipped docs as `pending`. `ReviewStore.backfill_trusted_defaults()` promotes them once, guarded by a marker row in `review_meta`. It runs *after* the registration syncs, because it only touches rows they have flagged as shipped — a user's own upload awaiting review is never approved on their behalf.\n\nIts rule is that **no shipped doc loses retrievability on upgrade**: the sole exclusion is an explicit SME decision (which always stamps `reviewed_at`). Reviewer notes and annotations do not hold a row back — annotations are injected into specialist context by domain regardless of item status, so withholding an annotated doc would hand the Executive a correction to a document it can no longer see.\n\n### Effect on retrieval\n\nAn item is **withheld** when it is `pending` *or* `rejected`. Withheld items are filtered out of every retrieval — `retrieve_context` for the built-in and external collections, and `retrieve_failures` for the failure case studies, which share the same review registrations but live in their own Chroma collection.\n\nBecause shipped content defaults to approved, `pending` genuinely means *a human deliberately queued this*, which is what makes withholding it safe. `needs_revision` is deliberately **not** withheld: an item lands there on any content edit, so withholding it would make editing a file in the knowledge UI silently drop it from retrieval.\n\n### Curation is opt-in, one domain at a time\n\n`POST /review/curate` with `{\"domain\": \"finance\", \"action\": \"start\"}` moves that domain's untouched trusted defaults into the queue; `\"stop\"` puts them back. Neither direction disturbs an item an SME actually decided on.\n\n`domain` is required. There is no \"curate everything\" selector, because curating withholds content — no single call should be able to take the whole knowledge base away from the Executive. The UI names the exact count before it starts.\n\n`POST /review/bulk-approve` clears the queue again, selecting by `domain`, an explicit `item_ids` list (over 500 is rejected rather than silently truncated), or `all_pending: true`. A call carrying no selector is rejected, and so is an empty `domain` — the store reads a falsy domain as \"no filter\", so accepting one would quietly turn a scoped approve into a blanket one. Both endpoints write audit events (`review_bulk_approve`, `review_curate`).\n\n### SME annotations\n\nAlongside a status, an SME can attach **annotations** — free-text corrections stored in `review_annotations` and injected into retrieved context for the item's domain. They let an expert correct or localize shipped material without editing the underlying file.",
- "markdown": "Knowledge that flows into retrieval passes through a subject-matter-expert (SME) review gate before it can influence the Executive. The queue and its decisions live in `openexecutive.knowledge.review_store.ReviewStore`, which shares the same `./episodic_memory.db` SQLite database as episodic memory.\n\nItems enter the queue in a pending state. An SME then resolves each one:\n\n- **Pending** — awaiting an SME decision. The Executive never sees pending items; they are excluded from every retrieval until resolved.\n- **Rejected** — filtered out of every retrieval. A rejected item can never surface in a specialist's context.\n- **Approved** — eligible for retrieval, and can be promoted in priority so it ranks ahead of unprioritized material.\n\n### Effect on retrieval\n\nThe gate is a filter layered on top of the normal RAG path: a chunk only reaches a specialist if it is approved (or never required review). Rejection is durable and global — it removes the item from all future queries rather than just down-ranking it. Approval with priority promotion lets an SME push vetted, high-value knowledge to the top of the retrieved set. The net effect is that the curated knowledge the Executive reasons over is exactly the set an SME has signed off on, with rejected material held back and pending material invisible.",
- "mermaid": "flowchart TD\n In[\"New knowledge item\"]\n Queue[\"Pending review queue<br/>ReviewStore\"]\n SME{\"SME decision\"}\n Rej[\"Rejected<br/>excluded from all retrieval\"]\n App[\"Approved<br/>priority promotion\"]\n RAG[\"Retrieval\"]\n Spec[\"Specialist context\"]\n In --> Queue\n Queue --> SME\n SME -->|reject| Rej\n SME -->|approve| App\n App --> RAG\n RAG --> Spec\n class In entry\n class Queue storage\n class SME compute\n class RAG compute\n class Spec hot\n",
- "generated_at": "2026-06-01T00:00:00+00:00"
++ "markdown": "Knowledge that reaches a specialist passes through a subject-matter-expert (SME) review gate. The queue and its decisions live in `openexecutive.knowledge.review_store.ReviewStore`, which shares the `./episodic_memory.db` SQLite database with episodic memory.\n\n### Shipped knowledge is trusted on arrival\n\nThe ~81 Markdown files under `knowledge/builtin/` are curated upstream and ship with the product. They register as **trusted defaults** — `approved`, with a NULL `reviewed_at` — so a new instance starts with an **empty** review queue and the Executive can draw on that material immediately. The same applies to manifest-listed external (OER) sources.\n\nProvenance is an explicit `trusted_default` column, fed by a committed manifest — it is never inferred. That matters more than it looks: a document a user creates through the knowledge UI is *also* `pending` with a NULL `reviewed_at`, **and** it is written into the same `knowledge/builtin/` tree the shipped docs live in. So neither the status shape nor the presence of a file on disk can tell the two apart. `sync_builtin_registrations` walks `SHIPPED_BUILTIN_FILES` rather than the directory, and `register()` — the path user uploads take — never sets the flag.\n\nRead together with `reviewed_at`:\n\n| State | `reviewed_at` | Meaning |\n|---|---|---|\n| `approved` + `trusted_default` | *NULL* | **Trusted default** — shipped with the product, nobody here has vetted it |\n| `approved` | set | An SME signed off, and can promote the item in priority |\n| `pending` | — | Deliberately queued for curation |\n| `rejected` | set | An SME rejected it |\n| `needs_revision` | — | Was decided on; the content has since been edited |\n\nAn install that predates this registers its shipped docs as `pending`. `ReviewStore.backfill_trusted_defaults()` promotes them once, guarded by a marker row in `review_meta`. It runs *after* the registration syncs, because it only touches rows they have flagged as shipped — a user's own upload awaiting review is never approved on their behalf.\n\nIts rule is that **no shipped doc loses retrievability on upgrade**: the sole exclusion is an explicit SME decision (which always stamps `reviewed_at`). Reviewer notes and annotations do not hold a row back — annotations are injected into specialist context by domain regardless of item status, so withholding an annotated doc would hand the Executive a correction to a document it can no longer see.\n\n### Effect on retrieval\n\nAn item is **withheld** when it is `pending` *or* `rejected`. Withheld items are filtered out of every retrieval — `retrieve` for the built-in and external collections, and `retrieve_failures` for the failure case studies, which share the same review registrations but live in their own Chroma collection.\n\nBecause shipped content defaults to approved, `pending` genuinely means *a human deliberately queued this*, which is what makes withholding it safe. `needs_revision` is deliberately **not** withheld: an item lands there on any content edit, so withholding it would make editing a file in the knowledge UI silently drop it from retrieval.\n\n### Curation is opt-in, one domain at a time\n\n`POST /review/curate` with `{\"domain\": \"finance\", \"action\": \"start\"}` moves that domain's untouched trusted defaults into the queue; `\"stop\"` puts them back. Neither direction disturbs an item an SME actually decided on.\n\n`domain` is required. There is no \"curate everything\" selector, because curating withholds content — no single call should be able to take the whole knowledge base away from the Executive. The UI names the exact count before it starts.\n\n`POST /review/bulk-approve` clears the queue again, selecting by `domain`, an explicit `item_ids` list (over 500 is rejected rather than silently truncated), or `all_pending: true`. A call carrying no selector is rejected, and so is an empty `domain` — the store reads a falsy domain as \"no filter\", so accepting one would quietly turn a scoped approve into a blanket one. Both endpoints write audit events (`review_bulk_approve`, `review_curate`).\n\n### SME annotations\n\nAlongside a status, an SME can attach **annotations** — free-text corrections stored in `review_annotations` and injected into retrieved context for the item's domain. They let an expert correct or localize shipped material without editing the underlying file.",
+ "mermaid": "flowchart TD\n A[\"Shipped doc<br/>(builtin / OER manifest)\"] -->|\"sync_*_registrations<br/>sets trusted_default = 1\"| B[\"approved<br/>reviewed_at = NULL<br/><b>trusted default</b>\"]\n U[\"User upload<br/>(POST /knowledge/builtin)\"] -->|\"register()<br/>trusted_default = 0\"| P\n B -->|retrievable| R([\"Specialist context\"])\n B -->|\"POST /review/curate<br/>action: start\"| P[\"pending\"]\n P -->|\"action: stop\"| B\n P -.->|withheld| X[\"Never reaches<br/>the Executive\"]\n P -->|approve| S[\"approved<br/>reviewed_at set<br/><b>SME signed off</b>\"]\n P -->|reject| J[\"rejected\"]\n J -.->|withheld| X\n S -->|retrievable, priority applies| R\n S -->|content edited| N[\"needs_revision\"]\n N -->|still retrievable| R\n",
- "generated_at": "2026-09-16T10:10:18.071509+00:00"
++ "generated_at": "2026-09-16T11:06:06.361019+00:00"
}
diff --cc packages/core/openexecutive/knowledge/review_store.py
index 42000a58,e738a3a2..8fcd7e40
--- a/packages/core/openexecutive/knowledge/review_store.py
+++ b/packages/core/openexecutive/knowledge/review_store.py
@@@ -110,103 -99,6 +110,103 @@@ def _row_to_annotation(row: sqlite3.Row
)
+def _insert_trusted_defaults(
+ conn: sqlite3.Connection,
+ rows: Iterable[tuple[ContentType, str, str]],
+) -> int:
+ """INSERT OR IGNORE a batch of (content_type, domain, filename) as trusted defaults.
+
+ Shared by both registration syncs so the "what does shipped content look
+ like on arrival" decision lives in exactly one place. `INSERT OR IGNORE`
+ means an existing SME decision is never overwritten. Returns new rows.
+ """
+ now = datetime.now(UTC).isoformat()
+ new_count = 0
+ for content_type, domain, filename in rows:
+ item_id = (
+ f"builtin:{domain}:{filename}"
+ if content_type is ContentType.BUILTIN
+ else f"external:{filename}"
+ )
+ result = conn.execute(
+ "INSERT OR IGNORE INTO review_items "
+ "(item_id, content_type, domain, filename, status, trusted_default, "
+ " registered_at, last_modified_at) "
+ "VALUES (?, ?, ?, ?, ?, 1, ?, ?)",
+ (
+ item_id,
+ content_type.value,
+ domain,
+ filename,
+ ReviewStatus.APPROVED.value,
+ now,
+ now,
+ ),
+ )
+ new_count += result.rowcount
+ if result.rowcount == 0:
+ # The row already existed, so the INSERT was ignored and its
+ # provenance may predate the column. Flag it — status is untouched,
+ # so an SME decision on a shipped doc survives.
+ conn.execute(
+ "UPDATE review_items SET trusted_default = 1 "
+ "WHERE item_id = ? AND trusted_default = 0",
+ (item_id,),
+ )
+ return new_count
+
+
+_TRUSTED_DEFAULTS_BACKFILL_KEY = "trusted_defaults_backfill_v1"
+
+
+def _backfill_trusted_defaults(conn: sqlite3.Connection) -> int:
+ """One-shot: promote never-touched shipped rows to trusted defaults.
+
+ Shipped content used to register as `pending`, so every pre-existing
+ install carries a queue of docs nobody asked for. It now registers
+ `approved` with a NULL `reviewed_at`; this brings older databases in line.
+
+ Scoped to `trusted_default = 1`, which is why this runs AFTER the
+ registration syncs have flagged provenance — a user's own upload awaiting
+ its first review is also (pending, reviewed_at NULL) and must not be
+ approved on their behalf.
+
+ The guiding rule is **no shipped doc loses retrievability on upgrade**.
+ Before this change `pending` was still retrieved, so every shipped doc was
+ reachable; now `pending` is withheld, and any shipped row left behind here
+ would silently vanish from the Executive's context. That is why notes and
+ annotations do NOT hold a row back: they are supplementary, not decisions.
- An annotated doc is the worst case — `retrieve_context` injects annotations
++ An annotated doc is the worst case — `retrieve` injects annotations
+ by DOMAIN regardless of item status, so withholding the doc would feed the
+ Executive a correction to a document it can no longer see.
+
+ `reviewed_at IS NULL` is the real exclusion, and it is enough: `set_status`
+ always stamps it, so every explicit approve or reject is skipped, and a
+ rejected row is not `pending` anyway.
+
+ Guarded by a marker row so it runs exactly once: re-running would undo a
+ later curation request. `BEGIN IMMEDIATE` + `INSERT OR IGNORE` make the
+ check-then-write safe against two processes booting at the same time
+ (two uvicorn workers, or the API racing a CLI command).
+ """
+ conn.execute("BEGIN IMMEDIATE")
+ already = conn.execute(
+ "SELECT 1 FROM review_meta WHERE key = ?", (_TRUSTED_DEFAULTS_BACKFILL_KEY,)
+ ).fetchone()
+ if already is not None:
+ return 0
+
+ result = conn.execute(
+ "UPDATE review_items SET status = 'approved' "
+ "WHERE trusted_default = 1 AND status = 'pending' AND reviewed_at IS NULL"
+ )
+ conn.execute(
+ "INSERT OR IGNORE INTO review_meta (key, value) VALUES (?, ?)",
+ (_TRUSTED_DEFAULTS_BACKFILL_KEY, datetime.now(UTC).isoformat()),
+ )
+ return result.rowcount
+
+
class ReviewStore:
def __init__(self, db_path: Path = DB_PATH) -> None:
self._db_path = db_path
diff --cc packages/core/tests/unit/test_company_doc_identity.py
index 00000000,adc36c60..903df69f
mode 000000,100644..100644
--- a/packages/core/tests/unit/test_company_doc_identity.py
+++ b/packages/core/tests/unit/test_company_doc_identity.py
@@@ -1,0 -1,312 +1,314 @@@
+ """Company-document identity: the orphan sweep and the `general` catch-all.
+
+ Companions to `test_documents_upload.py`, covering the two halves of the fix
+ that live below the API layer:
+
+ * `reconcile_company_docs` — deployed stores still hold chunks the old upload
+ path indexed under a random `tmpXXXXXXXX` staging name (#113). Nothing can
+ reach them: DELETE matches on `filename`, and a re-upload lands on different
+ ids, so they are neither replaceable nor removable.
+ * `retriever._with_general` — `general` is the default on `POST /documents`
+ and the default option in the UI's picker, but it maps to no specialist
+ (#114), so an unclassified document was retrievable by none of them.
+ """
+ from __future__ import annotations
+
+ from pathlib import Path
+ from typing import Any
+
+ import pytest
+
+ from openexecutive.knowledge.loader import (
+ GENERAL_DOMAIN,
+ UPLOAD_DOMAINS,
+ _make_chunk_id,
+ reconcile_company_docs,
+ )
+ from openexecutive.knowledge.retriever import DOMAIN_ALIASES, _with_general
+
+ from ._fake_store import FakeStore as _FakeStore
+
+
+ def _orphan(name: str, index: int = 0) -> tuple[str, dict[str, Any]]:
+ """A row as the pre-fix upload path wrote it: temp name, temp-path source."""
+ return (
+ _make_chunk_id(f"/tmp/{name}", index),
+ {"domain": "finance", "filename": name, "source": f"/tmp/{name}", "chunk_index": index},
+ )
+
+
+ def _docs_dir(tmp_path: Path) -> Path:
+ d = tmp_path / "docs"
+ d.mkdir()
+ return d
+
+
+ # ── the sweep ─────────────────────────────────────────────────────────────
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_drops_orphaned_temp_chunks(tmp_path: Path) -> None:
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md"), _orphan("tmp8qd9liu4.md", 1)]))
+
+ swept, _ = await reconcile_company_docs(store, _docs_dir(tmp_path))
+
+ assert swept == 2
+ assert store.rows == {}
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_spares_real_documents(tmp_path: Path) -> None:
+ docs = _docs_dir(tmp_path)
+ (docs / "plan.md").write_text("# Plan\nGrow revenue.")
+ store = _FakeStore(
+ {
+ _make_chunk_id("plan.md", 0): {
+ "domain": "strategy",
+ "filename": "plan.md",
+ "source": "plan.md",
+ "chunk_index": 0,
+ },
+ **dict([_orphan("tmp1du9epr4.md")]),
+ }
+ )
+
+ swept, indexed = await reconcile_company_docs(store, docs)
+
+ assert swept == 1
+ assert indexed == 0, "a document already indexed under its real name is left alone"
+ assert store.filenames() == {"plan.md"}
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_preserves_the_domain_of_indexed_documents(tmp_path: Path) -> None:
+ """Re-ingesting from disk would retag everything `general` — the on-disk
+ copy carries no record of the domain the uploader chose."""
+ docs = _docs_dir(tmp_path)
+ (docs / "plan.md").write_text("# Plan\nGrow revenue.")
+ store = _FakeStore(
+ {
+ _make_chunk_id("plan.md", 0): {
+ "domain": "finance",
+ "filename": "plan.md",
+ "source": "plan.md",
+ "chunk_index": 0,
+ }
+ }
+ )
+
+ await reconcile_company_docs(store, docs)
+
+ assert [m["domain"] for m in store.rows.values()] == ["finance"]
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_reindexes_a_document_with_no_chunks(tmp_path: Path) -> None:
+ """The recovery path: the file survived on disk, its chunks were orphans."""
+ docs = _docs_dir(tmp_path)
+ (docs / "plan.md").write_text("# Plan\n" + "grow revenue thirty percent. " * 50)
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md")]))
+
+ swept, indexed = await reconcile_company_docs(store, docs)
+
+ assert (swept, indexed) == (1, 1)
+ assert store.filenames() == {"plan.md"}
+ assert {m["domain"] for m in store.rows.values()} == {GENERAL_DOMAIN}
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_is_idempotent(tmp_path: Path) -> None:
+ docs = _docs_dir(tmp_path)
+ (docs / "plan.md").write_text("# Plan\n" + "grow revenue thirty percent. " * 50)
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md")]))
+
+ await reconcile_company_docs(store, docs)
+ snapshot = dict(store.rows)
+ second = await reconcile_company_docs(store, docs)
+
+ assert second == (0, 0)
+ assert store.rows == snapshot
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_spares_a_real_document_named_like_a_temp_file(tmp_path: Path) -> None:
+ docs = _docs_dir(tmp_path)
+ (docs / "tmp1du9epr4.md").write_text("# Notes\nA real file, awkwardly named.")
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md")]))
+
+ swept, _ = await reconcile_company_docs(store, docs)
+
+ assert swept == 0, "a document still present on disk is never swept"
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_skips_entirely_when_the_docs_dir_is_missing(tmp_path: Path) -> None:
+ """An absent docs dir is ambiguous: "no documents" and "the volume is not
+ mounted yet" look identical. Sweeping in the second case destroys exactly
+ the documents that were recoverable, because the file that would have
+ spared each one is invisible."""
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md")]))
+
+ swept, indexed = await reconcile_company_docs(store, tmp_path / "does-not-exist")
+
+ assert (swept, indexed) == (0, 0)
+ assert store.rows, "an unmounted docs dir must not be read as 'delete everything'"
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_continues_past_an_unreadable_document(tmp_path: Path) -> None:
+ docs = _docs_dir(tmp_path)
+ (docs / "broken.pdf").write_bytes(b"not a real pdf")
+ (docs / "plan.md").write_text("# Plan\n" + "grow revenue thirty percent. " * 50)
+ store = _FakeStore()
+
+ _, indexed = await reconcile_company_docs(store, docs)
+
+ assert indexed == 1
+ assert store.filenames() == {"plan.md"}
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_ignores_subdirectories(tmp_path: Path) -> None:
+ """Notion sync writes Markdown into docs/notion/, which belongs to the
+ notion_wiki collection — it must not be pulled into company_docs."""
+ docs = _docs_dir(tmp_path)
+ (docs / "notion").mkdir()
+ (docs / "notion" / "page.md").write_text("# Wiki\n" + "wiki content. " * 50)
+ store = _FakeStore()
+
+ swept, indexed = await reconcile_company_docs(store, docs)
+
+ assert (swept, indexed) == (0, 0)
+ assert store.rows == {}
+
+
+ def test_delete_by_ids_ignores_an_empty_list() -> None:
+ """Chroma's `col.delete()` with neither `ids` nor `where` deletes the
+ ENTIRE collection, and the sweep passes an empty list whenever there is
+ nothing orphaned — i.e. on every boot of a healthy install."""
+ from openexecutive.knowledge.store import ChromaDBStore
+
+ calls: list[Any] = []
+ store = ChromaDBStore.__new__(ChromaDBStore) # no ChromaDB client needed
+ store._get_or_create_collection = lambda name: calls.append(name) # type: ignore[method-assign]
+
+ store.delete_by_ids("company_docs", [])
+
+ assert calls == [], "an empty id list must not reach Chroma at all"
+
+
+ # ── the `general` catch-all ───────────────────────────────────────────────
+
+
+ def test_general_is_an_accepted_upload_domain() -> None:
+ assert GENERAL_DOMAIN in UPLOAD_DOMAINS
+
+
+ def test_with_general_widens_a_specialist_filter() -> None:
+ assert _with_general(["finance"]) == ["finance", GENERAL_DOMAIN]
+
+
+ def test_with_general_does_not_duplicate() -> None:
+ assert _with_general([GENERAL_DOMAIN]) == [GENERAL_DOMAIN]
+
+
+ def test_with_general_leaves_an_absent_filter_alone() -> None:
+ assert _with_general(None) is None, "None already matches every domain"
+
+
+ @pytest.mark.parametrize("specialist", sorted(DOMAIN_ALIASES))
+ def test_every_specialist_retrieves_general_company_docs(specialist: str) -> None:
+ """The whole point of #114: an unclassified upload must be visible to all
+ specialists rather than to none."""
+ assert GENERAL_DOMAIN in (_with_general(DOMAIN_ALIASES[specialist]) or [])
+
+
+ def test_with_general_leaves_an_empty_filter_alone() -> None:
+ """`store.query` treats both None and [] as "no filter", so [] already
+ matches every domain — widening it to ["general"] would *narrow* it to
+ general-only, inverting this function's purpose."""
+ assert _with_general([]) == []
+
+
+ @pytest.mark.asyncio
+ async def test_recovered_document_lands_under_general_despite_the_install_path(
+ tmp_path: Path,
+ ) -> None:
+ """`infer_domain_from_path` scans every component of the absolute path, so
+ an install rooted under e.g. /srv/finance/ would tag recovered documents
+ `finance`. The reconcile must pass the domain explicitly."""
+ docs = tmp_path / "finance" / "company" / "docs"
+ docs.mkdir(parents=True)
+ (docs / "plan.md").write_text("# Plan\n" + "grow revenue thirty percent. " * 50)
+ store = _FakeStore()
+
+ await reconcile_company_docs(store, docs)
+
+ assert {m["domain"] for m in store.rows.values()} == {GENERAL_DOMAIN}
+
+
+ @pytest.mark.asyncio
+ async def test_sweep_reports_zero_when_the_delete_fails(tmp_path: Path) -> None:
+ """The boot log must not claim to have dropped rows that are still there."""
+ docs = _docs_dir(tmp_path)
+ store = _FakeStore(dict([_orphan("tmp1du9epr4.md")]))
+ store.delete_by_ids = lambda collection, ids: 0 # type: ignore[assignment]
+
+ swept, _ = await reconcile_company_docs(store, docs)
+
+ assert swept == 0
+
+
+ class _RecordingStore(_FakeStore):
+ """Captures the domain filter each collection is queried with."""
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.queries: dict[str, list[str] | None] = {}
+
+ def query(
+ self,
+ query_text: str,
+ collection: str,
+ domain_filter: list[str] | None = None,
+ n_results: int = 5,
+ ) -> list[dict[str, Any]]:
+ self.queries[collection] = domain_filter
+ return []
+
+
+ def test_retrieve_widens_only_the_company_filter(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Guards the wiring, not just the helper: reverting the `_with_general`
+ call in `retrieve()` would otherwise leave the whole suite green while
+ #114 silently regresses."""
+ from openexecutive.knowledge import retriever
+ from openexecutive.knowledge.store import ChromaDBStore
+
+ store = _RecordingStore()
+ monkeypatch.setattr(retriever, "_default_review_store", lambda: _NullReviewStore())
+
+ retriever.retrieve(
+ query="what is our runway and hiring plan for next quarter",
+ specialist_name="cfo",
+ store=store, # type: ignore[arg-type]
+ )
+
+ assert store.queries[ChromaDBStore.COMPANY_COLLECTION] == ["finance", GENERAL_DOMAIN]
+ assert store.queries[ChromaDBStore.BUILTIN_COLLECTION] == ["finance"]
+ assert store.queries[ChromaDBStore.NOTION_COLLECTION] == ["finance"]
+
+
+ class _NullReviewStore:
- def get_rejected_filenames(self, *a: Any, **k: Any) -> set[str]:
++ # `get_withheld_*` superseded the rejected-only lookups when `pending`
++ # became a real retrieval gate; these are the methods `retrieve()` calls.
++ def get_withheld_filenames(self, *a: Any, **k: Any) -> set[str]:
+ return set()
+
- def get_rejected_source_ids(self, *a: Any, **k: Any) -> set[str]:
++ def get_withheld_source_ids(self, *a: Any, **k: Any) -> set[str]:
+ return set()
+
+ def get_priority_map(self, *a: Any, **k: Any) -> dict[str, str]:
+ return {}
+
+ def list_annotations(self, *a: Any, **k: Any) -> list[Any]:
+ return []
diff --cc packages/core/tests/unit/test_knowledge_search_and_failures.py
index 269fe716,fb96671e..bc735903
--- a/packages/core/tests/unit/test_knowledge_search_and_failures.py
+++ b/packages/core/tests/unit/test_knowledge_search_and_failures.py
@@@ -233,3 -233,57 +233,152 @@@ def test_failures_rejects_path_traversa
# The path-segment regex requires a *.md and no slashes/dots-as-traversal,
# so the encoded "../evil.md" must be rejected as a bad filename.
assert res.status_code in (400, 404)
+
+
+ # ── #114: the Query panel must mirror what retrieve() actually does ────────
+
+
+ def test_search_accepts_the_general_domain(client: TestClient) -> None:
+ """`general` is a real, uploadable company domain. Rejecting it left the
+ operator unable to introspect the documents most likely to need it — the
+ unclassified ones."""
+ res = client.post(
+ "/knowledge/search", json={"query": "pricing", "domain_filter": ["general"]}
+ )
+
+ assert res.status_code == 200, res.text
+
+
+ def test_search_still_rejects_an_unknown_domain(client: TestClient) -> None:
+ res = client.post(
+ "/knowledge/search", json={"query": "pricing", "domain_filter": ["finanace"]}
+ )
+
+ assert res.status_code == 400
+
+
+ def test_search_widens_the_company_filter_with_general(
+ monkeypatch: pytest.MonkeyPatch, client: TestClient
+ ) -> None:
+ """This endpoint is documented as the parallel of `retrieve()`. If it does
+ not widen COMPANY the same way, the panel reports zero company hits for a
+ specialist that does retrieve them in chat — the exact #114 symptom, shown
+ by the tool an operator would use to diagnose it."""
+ seen: dict[str, list[str] | None] = {}
+
+ def recording_query(
+ query_text: str,
+ collection: str,
+ domain_filter: list[str] | None = None,
+ n_results: int = 5,
+ ) -> list[dict[str, Any]]:
+ seen[collection] = domain_filter
+ return []
+
+ recording_store = MagicMock()
+ recording_store.query.side_effect = recording_query
+ monkeypatch.setattr(
+ "openexecutive.api.routes.knowledge._get_store",
+ lambda _request: recording_store,
+ )
+
+ res = client.post("/knowledge/search", json={"query": "pricing", "specialist": "cfo"})
+
+ assert res.status_code == 200, res.text
+ assert seen["company_docs"] == ["finance", "general"]
+ assert seen["builtin_knowledge"] == ["finance"]
++
++
++# ---------------------------------------------------------------------------
++# The review gate: the diagnostic panel must not advertise withheld knowledge
++# ---------------------------------------------------------------------------
++
++
++def review_db(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Any:
++ """Point the retriever's review-store resolver at an isolated DB."""
++ from openexecutive.knowledge.review_store import ReviewStore
++
++ db = tmp_path / "review.db"
++ ReviewStore.initialize_db(db)
++ # Patch only the module attribute. `_default_review_store` imports DB_PATH
++ # inside its body, and `_withheld_sets` reads the same attribute for its
++ # exists() check, so this one patch exercises the real resolver wiring
++ # instead of stubbing it out.
++ monkeypatch.setattr("openexecutive.memory.episodic.DB_PATH", db, raising=False)
++ return ReviewStore(db_path=db)
++
++
++def _register(store: Any, domain: str, filename: str, *, content_type: Any = None) -> str:
++ from openexecutive.knowledge.review_store import ContentType
++
++ ct = content_type or ContentType.BUILTIN
++ item_id = (
++ f"builtin:{domain}:{filename}" if ct is ContentType.BUILTIN else f"external:{filename}"
++ )
++ store.register(item_id=item_id, content_type=ct, domain=domain, filename=filename)
++ return item_id
++
++
++def test_search_omits_a_withheld_builtin_doc(client: TestClient, review_db: Any) -> None:
++ """A doc queued for curation is withheld from chat, so the panel must not show it."""
++ from openexecutive.knowledge.review_store import ReviewStatus
++
++ # Unregistered content is not withheld — establish the baseline first.
++ before = client.post("/knowledge/search", json={"query": "strategy"}).json()
++ assert [h["filename"] for h in before["builtin"]] == ["product_strategy.md"]
++
++ # register() leaves it `pending`, which is withheld.
++ item = _register(review_db, "strategy", "product_strategy.md")
++ after = client.post("/knowledge/search", json={"query": "strategy"}).json()
++ assert after["builtin"] == []
++
++ # Approving it brings it back.
++ review_db.set_status(item, ReviewStatus.APPROVED)
++ restored = client.post("/knowledge/search", json={"query": "strategy"}).json()
++ assert [h["filename"] for h in restored["builtin"]] == ["product_strategy.md"]
++
++
++def test_search_omits_a_rejected_external_source(client: TestClient, review_db: Any) -> None:
++ from openexecutive.knowledge.review_store import ContentType, ReviewStatus
++
++ item = _register(
++ review_db, "finance", "openstax-finance", content_type=ContentType.EXTERNAL
++ )
++ review_db.set_status(item, ReviewStatus.REJECTED, "not for us")
++
++ data = client.post("/knowledge/search", json={"query": "strategy"}).json()
++
++ assert data["external"] == []
++ # The un-registered builtin row is unaffected.
++ assert [h["filename"] for h in data["builtin"]] == ["product_strategy.md"]
++
++
++def test_search_omits_a_withheld_failure_case(client: TestClient, review_db: Any) -> None:
++ """Failure cases share review registrations but their own Chroma collection."""
++ _register(review_db, "strategy", "kodak-digital.md")
++
++ data = client.post("/knowledge/search", json={"query": "strategy"}).json()
++
++ assert data["failures"] == []
++
++
++def test_search_company_bucket_is_never_review_filtered(
++ client: TestClient, review_db: Any
++) -> None:
++ """Company docs are not registered in review_items, so they must pass through.
++
++ The withheld entry deliberately carries the COMPANY row's own filename.
++ Registering some unrelated builtin doc would make this vacuous — no filter
++ bug could ever drop `deck.pdf` on account of a different name. With the
++ name shared, wiring the company bucket through `_is_withheld` drops the
++ row and fails here, which is the regression this guards.
++ """
++ from openexecutive.knowledge.review_store import ContentType
++
++ _register(review_db, "strategy", "deck.pdf")
++ assert "deck.pdf" in review_db.get_withheld_filenames(ContentType.BUILTIN)
++
++ data = client.post("/knowledge/search", json={"query": "strategy"}).json()
++
++ assert [h["filename"] for h in data["company"]] == ["deck.pdf"]