Skip to content

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

fix(review): stop user uploads inheriting shipped trust; close 4 review findings

Claude72a54c0b8ab1
diff --git a/packages/core/openexecutive/api/routes/knowledge.py b/packages/core/openexecutive/api/routes/knowledge.py
index 6460c284..3d83cea3 100644
--- a/packages/core/openexecutive/api/routes/knowledge.py
+++ b/packages/core/openexecutive/api/routes/knowledge.py
@@ -77,6 +77,21 @@ def _get_store(request: Request): # type: ignore[return]
return ChromaDBStore(persist_directory=get_settings().vector_store_path)
+def _review_store(): # type: ignore[no-untyped-def]
+ """ReviewStore bound to the DB every other consumer reads.
+
+ `ReviewStore()`'s default is captured at import, so a runtime override of
+ `EPISODIC_DB_PATH` (client slots, tests) left this module writing review
+ rows into one database while `routes/review._store` and
+ `retriever._default_review_store` read another — the gate would silently
+ consult state this module never wrote.
+ """
+ from openexecutive.knowledge.review_store import ReviewStore
+ from openexecutive.memory.episodic import DB_PATH
+
+ return ReviewStore(db_path=DB_PATH)
+
+
@router.get("/builtin", response_model=BuiltinListResponse)
async def list_builtin_files() -> BuiltinListResponse:
files: list[BuiltinFileMeta] = []
@@ -109,16 +124,30 @@ async def create_builtin_file(body: BuiltinFileWrite, request: Request) -> Built
if path.exists():
raise HTTPException(status_code=409, detail="File already exists. Use PUT to update.")
+ from openexecutive.knowledge.loader import ingest_builtin_file
+ from openexecutive.knowledge.review_store import ContentType, build_item_id
+
+ # Defence in depth. Shipped failure docs used to derive ids in this very
+ # namespace, so an upload of a name like `board/theranos.md` landed on a
+ # row already marked `approved` + `trusted_default = 1` and inherited it —
+ # trusted, unqueued, and labelled "ships with the product" in the UI. The
+ # FAILURE namespace fixes that at the source; this makes sure no future
+ # id-space change can quietly re-open it.
+ item_id = build_item_id(ContentType.BUILTIN, body.domain, body.filename)
+ existing = _review_store().get_item(item_id)
+ if existing is not None and existing.trusted_default:
+ raise HTTPException(
+ status_code=409,
+ detail="That name belongs to content shipped with Open Executive.",
+ )
+
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(body.content, encoding="utf-8")
- from openexecutive.knowledge.loader import ingest_builtin_file
- from openexecutive.knowledge.review_store import ContentType, ReviewStore
-
chunks = await ingest_builtin_file(path, _get_store(request))
- ReviewStore().register(
- item_id=f"builtin:{body.domain}:{body.filename}",
+ _review_store().register(
+ item_id=item_id,
content_type=ContentType.BUILTIN,
domain=body.domain,
filename=body.filename,
@@ -138,7 +167,7 @@ async def update_builtin_file(
raise HTTPException(status_code=404, detail="File not found. Use POST to create.")
from openexecutive.knowledge.loader import ingest_builtin_file
- from openexecutive.knowledge.review_store import ContentType, ReviewStore
+ from openexecutive.knowledge.review_store import ContentType, build_item_id
from openexecutive.knowledge.store import ChromaDBStore
store = _get_store(request)
@@ -149,8 +178,8 @@ async def update_builtin_file(
path.write_text(body.content, encoding="utf-8")
chunks = await ingest_builtin_file(path, store)
- rs = ReviewStore()
- item_id = f"builtin:{domain}:{filename}"
+ rs = _review_store()
+ item_id = build_item_id(ContentType.BUILTIN, domain, filename)
rs.register(item_id=item_id, content_type=ContentType.BUILTIN, domain=domain, filename=filename)
rs.touch_modified(item_id)
@@ -323,7 +352,7 @@ async def delete_builtin_file(domain: str, filename: str, request: Request) -> d
if not path.exists():
raise HTTPException(status_code=404, detail="File not found")
- from openexecutive.knowledge.review_store import ReviewStore
+ from openexecutive.knowledge.review_store import ContentType, build_item_id
from openexecutive.knowledge.store import ChromaDBStore
store = _get_store(request)
@@ -332,7 +361,9 @@ async def delete_builtin_file(domain: str, filename: str, request: Request) -> d
where={"source": str(path)},
)
path.unlink()
- ReviewStore().delete_item(f"builtin:{domain}:{filename}")
+ _review_store().delete_item(
+ build_item_id(ContentType.BUILTIN, domain, filename)
+ )
return {"deleted": filename}
@@ -396,6 +427,20 @@ async def create_failure_file(body: BuiltinFileWrite, request: Request) -> Built
chunk_size=400,
overlap=40,
)
+
+ # Register, exactly as create_builtin_file does. Without this a
+ # user-authored failure case study had no review row at all, so it could
+ # never enter the withheld set — `retrieve_failures` applied a gate that
+ # could not reach it, and no SME decision could block it.
+ from openexecutive.knowledge.review_store import ContentType, build_item_id
+
+ _review_store().register(
+ item_id=build_item_id(ContentType.FAILURE, body.domain, body.filename),
+ content_type=ContentType.FAILURE,
+ domain=body.domain,
+ filename=body.filename,
+ )
+
return BuiltinWriteResponse(domain=body.domain, filename=body.filename, chunks_indexed=chunks)
@@ -445,6 +490,10 @@ async def delete_failure_file(domain: str, filename: str, request: Request) -> d
where={"source": str(path)},
)
path.unlink()
+
+ from openexecutive.knowledge.review_store import ContentType, build_item_id
+
+ _review_store().delete_item(build_item_id(ContentType.FAILURE, domain, filename))
return {"deleted": filename}
@@ -622,7 +671,7 @@ async def search_knowledge(
# 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]]:
+ def _withheld_sets() -> tuple[set[tuple[str, str]], set[str]]:
from openexecutive.memory.episodic import DB_PATH
if not DB_PATH.exists():
@@ -630,7 +679,8 @@ async def search_knowledge(
try:
rs = _default_review_store()
return (
- rs.get_withheld_filenames(ContentType.BUILTIN),
+ rs.get_withheld_keys(ContentType.BUILTIN)
+ | rs.get_withheld_keys(ContentType.FAILURE),
rs.get_withheld_source_ids(),
)
except Exception:
@@ -653,7 +703,7 @@ async def search_knowledge(
source_id = md_dict.get("source_id")
if source_id:
return source_id in _withheld_external
- return md_dict.get("filename") in _withheld_builtin
+ return (md_dict.get("domain"), md_dict.get("filename")) in _withheld_builtin
builtin_hits: list[SearchHit] = []
external_hits: list[SearchHit] = []
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index fd1cda05..533b2166 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -2278,10 +2278,28 @@ review:
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.
+ The filter keys on the `(domain, filename)` PAIR that Chroma metadata
+ carries. Bare filename was both ambiguous and caller-choosable:
+ `POST /knowledge/builtin` accepts any `(domain, filename)`, so uploading a
+ file named after a shipped doc in a different domain silently withheld
+ that shipped doc from every specialist. `get_priority_map` uses the same
+ key for the same reason. The old design leaned on "all shipped basenames
+ are unique", which only a test over the shipped tree ever checked and
+ which nothing enforced at the write path.
+
+ IDENTITY IS NAMESPACED. `build_item_id` is the single constructor, with
+ three disjoint namespaces: `builtin:<domain>:<file>`,
+ `failure:<domain>:<file>`, `external:<source_id>`. Failure case studies
+ used to fold into `builtin:`, which is the namespace a user upload reaches
+ — and since no file sits at `knowledge/builtin/<domain>/<file>` for a
+ failure doc, `create_builtin_file`'s exists() guard never fired, so an
+ upload INSERT-OR-IGNOREd onto the shipped row and inherited `approved` +
+ `trusted_default = 1`. `_migrate_failure_namespace` (marker
+ `failure_namespace_v1`) re-keys existing rows, carrying status,
+ reviewed_at, notes and annotations across under `PRAGMA
+ defer_foreign_keys`. `create_builtin_file` also refuses outright to write
+ onto a `trusted_default = 1` row, so a future id-space change cannot
+ silently re-open it.
curation: |
Opt-in, per domain. `POST /review/curate {domain, action: start|stop}`
moves a domain's untouched trusted defaults to `pending` (and back).
@@ -2304,7 +2322,14 @@ review:
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
+ sources. It then re-registers, as `pending`, every `.md` under
+ `knowledge/builtin/` the manifest does NOT claim: the reset does not
+ delete user-authored files or their Chroma chunks, so without this a doc
+ an SME had REJECTED came back retrievable with no review row at all —
+ un-suppressed and invisible in the queue. Conservative on purpose, since
+ a previously-approved upload returning for review is the safe direction,
+ and deleting the operator's files would be worse. This means a 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
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index 97e3f071..2a211c17 100644
--- a/packages/core/openexecutive/architecture/prebuilt/api.json
+++ b/packages/core/openexecutive/architecture/prebuilt/api.json
@@ -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. 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. |",
+ "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. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\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-16T11:09:07.698247+00:00"
+ "generated_at": "2026-09-16T13:15:55.101359+00:00"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.json
index 7076b901..adbc2dd4 100644
--- a/packages/core/openexecutive/architecture/prebuilt/rag.json
+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json
@@ -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. 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.",
+ "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 `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\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-16T11:05:57.673913+00:00"
+ "generated_at": "2026-09-16T13:15:55.101359+00:00"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/review.json b/packages/core/openexecutive/architecture/prebuilt/review.json
index d993bf00..e2c2305e 100644
--- a/packages/core/openexecutive/architecture/prebuilt/review.json
+++ b/packages/core/openexecutive/architecture/prebuilt/review.json
@@ -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` 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-16T11:06:06.361019+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\nIdentity is namespaced to match. Failure case studies ship under `knowledge/builtin/failures/<domain>/` and register as `failure:<domain>:<file>`, **not** `builtin:<domain>:<file>`. That second namespace is the one `POST /knowledge/builtin` writes into, and because no file sits at `knowledge/builtin/<domain>/<file>` for a failure doc, that route's \"file already exists\" guard could not fire — an upload of the same name landed on the shipped row and inherited its trust. A one-shot migration re-keys existing rows, carrying the reviewer's status, notes and annotations across.\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/>builtin:&lt;domain&gt;:&lt;file&gt;\"] -->|\"register()<br/>trusted_default = 0\"| P\n F[\"Shipped failure doc<br/>failure:&lt;domain&gt;:&lt;file&gt;\"] -->|separate namespace| B\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-16T13:15:55.101359+00:00"
}
diff --git a/packages/core/openexecutive/cli/fixture_loader.py b/packages/core/openexecutive/cli/fixture_loader.py
index 36a73652..a5e9f7f6 100644
--- a/packages/core/openexecutive/cli/fixture_loader.py
+++ b/packages/core/openexecutive/cli/fixture_loader.py
@@ -613,6 +613,45 @@ async def unload_fixture(settings: Any) -> dict[str, Any]:
return summary
+def _reregister_surviving_user_knowledge(db_path: Path) -> int:
+ """Register non-shipped knowledge files left on disk after a reset.
+
+ `reset_all_state` wipes `review_items`, but user-authored docs under
+ `knowledge/builtin/` (including `failures/`) and their indexed chunks are
+ not removed. Anything the shipped manifest does not list is the operator's
+ own content, so it goes back as `pending`: withheld from retrieval, and
+ listed in the review queue. Returns the number registered.
+ """
+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH
+ from openexecutive.knowledge.review_store import (
+ ContentType,
+ ReviewStore,
+ build_item_id,
+ )
+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES
+
+ store = ReviewStore(db_path=db_path)
+ registered = 0
+ for md in sorted(BUILTIN_KNOWLEDGE_PATH.rglob("*.md")):
+ rel = md.relative_to(BUILTIN_KNOWLEDGE_PATH).as_posix()
+ # Skills have separate management and are absent from the manifest by
+ # construction, so they must not be swept in here.
+ if rel.startswith("skills/") or rel in SHIPPED_BUILTIN_FILES:
+ continue
+ content_type = (
+ ContentType.FAILURE if rel.startswith("failures/") else ContentType.BUILTIN
+ )
+ domain, filename = md.parent.name, md.name
+ store.register(
+ item_id=build_item_id(content_type, domain, filename),
+ content_type=content_type,
+ domain=domain,
+ filename=filename,
+ )
+ registered += 1
+ return registered
+
+
async def reset_all_state(
settings: Any, *, app_state: Any | None = None
) -> dict[str, Any]:
@@ -779,6 +818,23 @@ async def reset_all_state(
except Exception:
logger.exception("reset: sync_external_registrations failed")
+ # The wipe above deleted every review decision, but this reset does
+ # NOT delete user-authored knowledge files or their Chroma chunks —
+ # they live inside the installed package and survive. Left alone,
+ # a document an SME had REJECTED would come back retrievable with
+ # no review row at all: un-suppressed, and invisible in the queue.
+ #
+ # So re-register everything in the tree that the manifest does not
+ # claim, as `pending` — withheld from retrieval AND visible for a
+ # fresh decision. Deliberately conservative: a previously-approved
+ # upload comes back needing review, which is the safe direction.
+ # Deleting the files instead would make a reset silently destroy
+ # the operator's own work.
+ try:
+ _reregister_surviving_user_knowledge(_REVIEW_DB_PATH)
+ except Exception:
+ logger.exception("reset: re-registering user knowledge failed")
+
# 4. People (child tables first to satisfy FK ordering)
from openexecutive.people import store as people_store
people_cleared = _delete_all_rows(
diff --git a/packages/core/openexecutive/knowledge/retriever.py b/packages/core/openexecutive/knowledge/retriever.py
index 7a667343..732988f6 100644
--- a/packages/core/openexecutive/knowledge/retriever.py
+++ b/packages/core/openexecutive/knowledge/retriever.py
@@ -239,7 +239,7 @@ def retrieve(
# Withheld = pending or rejected. Shipped content registers as an approved
# trusted default, so anything pending was deliberately queued for
# curation and must not reach a specialist until it is resolved.
- withheld_builtin = rs.get_withheld_filenames(ContentType.BUILTIN)
+ withheld_builtin = rs.get_withheld_keys(ContentType.BUILTIN)
withheld_external = rs.get_withheld_source_ids()
priority_map = rs.get_priority_map(ContentType.BUILTIN)
@@ -263,13 +263,17 @@ def retrieve(
filtered_builtin = [
r
for r in raw_builtin
- if r["metadata"].get("filename") not in withheld_builtin
+ if (r["metadata"].get("domain"), r["metadata"].get("filename"))
+ not in withheld_builtin
and r["metadata"].get("source_id") not in withheld_external
and _passes_threshold(r, distance_threshold)
]
filtered_builtin.sort(
key=lambda r: PRIORITY_ORDER.get(
- priority_map.get(r["metadata"].get("filename", ""), Priority.NORMAL.value),
+ priority_map.get(
+ (r["metadata"].get("domain", ""), r["metadata"].get("filename", "")),
+ Priority.NORMAL.value,
+ ),
1,
)
)
@@ -374,7 +378,12 @@ def retrieve(
parts.append("### From executive knowledge base:")
for r in builtin_results:
filename = r["metadata"].get("filename", "unknown")
- prio = priority_map.get(filename, Priority.NORMAL.value)
+ # Same (domain, filename) key the map is built on — a bare
+ # filename here would miss every entry and silently drop the
+ # priority label from every citation.
+ prio = priority_map.get(
+ (r["metadata"].get("domain", ""), filename), Priority.NORMAL.value
+ )
prefix = "[verified - priority source] " if prio == Priority.HIGH.value else ""
parts.append(f"[{filename}] {prefix}{r['text']}")
@@ -426,12 +435,14 @@ def retrieve_failures(
# a larger distance means the match is too weak to be useful.
threshold = settings.knowledge_distance_threshold
rs = review_store or _default_review_store()
- withheld = rs.get_withheld_filenames(ContentType.BUILTIN)
+ # FAILURE, not BUILTIN: failure case studies have their own id namespace
+ # so a user upload cannot collide with a shipped one.
+ withheld = rs.get_withheld_keys(ContentType.FAILURE)
filtered = _dedupe_by_text(
[
r
for r in raw
- if r["metadata"].get("filename") not in withheld
+ if (r["metadata"].get("domain"), r["metadata"].get("filename")) not in withheld
and r["distance"] <= threshold
]
)
diff --git a/packages/core/openexecutive/knowledge/review_store.py b/packages/core/openexecutive/knowledge/review_store.py
index 8fcd7e40..e6b0ef1b 100644
--- a/packages/core/openexecutive/knowledge/review_store.py
+++ b/packages/core/openexecutive/knowledge/review_store.py
@@ -32,6 +32,13 @@ class ReviewStatus(StrEnum):
class ContentType(StrEnum):
BUILTIN = "builtin"
EXTERNAL = "external"
+ # Failure case studies ship under `knowledge/builtin/failures/<domain>/`
+ # but need their OWN id namespace. Folding them into `builtin:<domain>:<f>`
+ # put them in the namespace `POST /knowledge/builtin` writes to, and since
+ # no file sits at `builtin/<domain>/<f>` that route's 409 guard could not
+ # fire — an upload INSERT-OR-IGNOREd onto the shipped row and inherited
+ # its `approved` + `trusted_default = 1`.
+ FAILURE = "failure"
class Priority(StrEnum):
@@ -110,6 +117,18 @@ def _row_to_annotation(row: sqlite3.Row) -> Annotation:
)
+def build_item_id(content_type: ContentType, domain: str, filename: str) -> str:
+ """The one place an `item_id` is constructed.
+
+ Three disjoint namespaces. `builtin:` is reachable by a user upload
+ (`POST /knowledge/builtin` writes `knowledge/builtin/<domain>/<file>`), so
+ nothing else may share it — that is what `failure:` exists for.
+ """
+ if content_type is ContentType.EXTERNAL:
+ return f"external:{filename}"
+ return f"{content_type.value}:{domain}:{filename}"
+
+
def _insert_trusted_defaults(
conn: sqlite3.Connection,
rows: Iterable[tuple[ContentType, str, str]],
@@ -123,11 +142,7 @@ def _insert_trusted_defaults(
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}"
- )
+ item_id = build_item_id(content_type, domain, filename)
result = conn.execute(
"INSERT OR IGNORE INTO review_items "
"(item_id, content_type, domain, filename, status, trusted_default, "
@@ -156,6 +171,84 @@ def _insert_trusted_defaults(
return new_count
+_FAILURE_NAMESPACE_KEY = "failure_namespace_v1"
+
+
+def _migrate_failure_namespace(conn: sqlite3.Connection) -> int:
+ """One-shot: re-key shipped failure docs out of the `builtin:` namespace.
+
+ They used to register as `builtin:<domain>:<file>` — the namespace
+ `POST /knowledge/builtin` writes into. Because no file sits at
+ `knowledge/builtin/<domain>/<file>` for a failure doc, that route's
+ `if path.exists(): 409` guard never fired, so an upload of the same name
+ INSERT-OR-IGNOREd onto the shipped row and inherited its `approved` +
+ `trusted_default = 1`: trusted, unqueued, and labelled "ships with the
+ product" in the UI.
+
+ Carries `status`, `reviewed_at`, `reviewer_notes`, `priority` and every
+ annotation across, so an SME's decision on a failure case study survives
+ the re-key. `review_annotations.item_id` is an FK with ON DELETE CASCADE
+ but no ON UPDATE, and `_get_conn` turns foreign keys on, so the parent and
+ child updates have to land in one transaction with the check deferred.
+
+ Runs from `sync_builtin_registrations`, after the new-namespace rows are
+ inserted: an INSERT OR IGNORE will already have created the `failure:` row
+ as a trusted default, so this UPDATE would collide. Old rows are therefore
+ merged onto the new id rather than renamed — the old row's decision wins,
+ since it is the one a human made.
+ """
+ already = conn.execute(
+ "SELECT 1 FROM review_meta WHERE key = ?", (_FAILURE_NAMESPACE_KEY,)
+ ).fetchone()
+ if already is not None:
+ return 0
+
+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES
+
+ migrated = 0
+ conn.execute("PRAGMA defer_foreign_keys = ON")
+ for rel in sorted(SHIPPED_BUILTIN_FILES):
+ path = PurePosixPath(rel)
+ if path.parts[0] != "failures":
+ continue
+ domain, filename = path.parent.name, path.name
+ old_id = f"builtin:{domain}:{filename}"
+ new_id = build_item_id(ContentType.FAILURE, domain, filename)
+
+ old = conn.execute(
+ "SELECT status, reviewed_at, reviewer_notes, priority "
+ "FROM review_items WHERE item_id = ?",
+ (old_id,),
+ ).fetchone()
+ if old is None:
+ continue
+
+ # Carry the human's decision onto the new row, then drop the old one.
+ conn.execute(
+ "UPDATE review_items SET status = ?, reviewed_at = ?, "
+ "reviewer_notes = ?, priority = ? WHERE item_id = ?",
+ (
+ old["status"],
+ old["reviewed_at"],
+ old["reviewer_notes"],
+ old["priority"],
+ new_id,
+ ),
+ )
+ conn.execute(
+ "UPDATE review_annotations SET item_id = ? WHERE item_id = ?",
+ (new_id, old_id),
+ )
+ conn.execute("DELETE FROM review_items WHERE item_id = ?", (old_id,))
+ migrated += 1
+
+ conn.execute(
+ "INSERT OR IGNORE INTO review_meta (key, value) VALUES (?, ?)",
+ (_FAILURE_NAMESPACE_KEY, datetime.now(UTC).isoformat()),
+ )
+ return migrated
+
+
_TRUSTED_DEFAULTS_BACKFILL_KEY = "trusted_defaults_backfill_v1"
@@ -292,12 +385,22 @@ class ReviewStore:
# product" — scanning marked those uploads trusted and auto-approved
# them into retrieval. Skills are absent from the manifest by
# construction (they have separate management).
+ # Entries under `failures/` register as FAILURE so they never occupy
+ # the `builtin:` namespace a user upload can reach.
rows = [
- (ContentType.BUILTIN, PurePosixPath(rel).parent.name, PurePosixPath(rel).name)
+ (
+ ContentType.FAILURE
+ if PurePosixPath(rel).parts[0] == "failures"
+ else ContentType.BUILTIN,
+ PurePosixPath(rel).parent.name,
+ PurePosixPath(rel).name,
+ )
for rel in sorted(SHIPPED_BUILTIN_FILES)
]
with _get_conn(db_path) as conn:
- return _insert_trusted_defaults(conn, rows)
+ count = _insert_trusted_defaults(conn, rows)
+ _migrate_failure_namespace(conn)
+ return count
@staticmethod
def sync_external_registrations(
@@ -510,38 +613,56 @@ class ReviewStore:
).fetchall()
return {row["domain"]: row["n"] for row in rows}
- def get_withheld_filenames(self, content_type: ContentType) -> set[str]:
- """Filenames that must not reach a specialist.
+ def get_withheld_keys(self, content_type: ContentType) -> set[tuple[str, str]]:
+ """(domain, filename) pairs that must not reach a specialist.
`pending` *and* `rejected`. Pending means a human deliberately queued
the item for curation, and the architecture contract is that the
Executive never sees pending material — shipped content registers as
an approved trusted default precisely so that gate can be real.
+ Keyed on the PAIR, not the bare filename. Filename alone was ambiguous
+ and user-reachable: `POST /knowledge/builtin` lets a caller choose any
+ `(domain, filename)`, so uploading a file named after a shipped doc in
+ some *other* domain silently withheld that shipped doc from every
+ specialist. It also meant the design leaned on "all shipped basenames
+ are unique", which only a test over the shipped tree ever checked.
+
`needs_revision` is deliberately absent: `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.
"""
with _get_conn(self._db_path) as conn:
rows = conn.execute(
- "SELECT filename FROM review_items "
+ "SELECT domain, filename FROM review_items "
"WHERE content_type = ? AND status IN ('pending', 'rejected')",
(content_type.value,),
).fetchall()
- return {row["filename"] for row in rows}
+ return {(row["domain"], row["filename"]) for row in rows}
def get_withheld_source_ids(self) -> set[str]:
- return self.get_withheld_filenames(ContentType.EXTERNAL)
+ """Withheld OER source ids. `source_id` is already unambiguous."""
+ with _get_conn(self._db_path) as conn:
+ rows = conn.execute(
+ "SELECT filename FROM review_items "
+ "WHERE content_type = ? AND status IN ('pending', 'rejected')",
+ (ContentType.EXTERNAL.value,),
+ ).fetchall()
+ return {row["filename"] for row in rows}
- def get_priority_map(self, content_type: ContentType) -> dict[str, str]:
- """Map filename → priority for approved items of a given content type."""
+ def get_priority_map(self, content_type: ContentType) -> dict[tuple[str, str], str]:
+ """Map (domain, filename) → priority for approved items of a type.
+
+ Same key as `get_withheld_keys`, and for the same reason: a bare
+ filename is ambiguous across domains and user-choosable.
+ """
with _get_conn(self._db_path) as conn:
rows = conn.execute(
- "SELECT filename, priority FROM review_items "
+ "SELECT domain, filename, priority FROM review_items "
"WHERE content_type = ? AND status = 'approved'",
(content_type.value,),
).fetchall()
- return {row["filename"]: row["priority"] for row in rows}
+ return {(row["domain"], row["filename"]): row["priority"] for row in rows}
def list_items(
self,
diff --git a/packages/core/tests/unit/test_company_doc_identity.py b/packages/core/tests/unit/test_company_doc_identity.py
index 903df69f..de530b1c 100644
--- a/packages/core/tests/unit/test_company_doc_identity.py
+++ b/packages/core/tests/unit/test_company_doc_identity.py
@@ -301,7 +301,7 @@ def test_retrieve_widens_only_the_company_filter(monkeypatch: pytest.MonkeyPatch
class _NullReviewStore:
# `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]:
+ def get_withheld_keys(self, *a: Any, **k: Any) -> set[tuple[str, str]]:
return set()
def get_withheld_source_ids(self, *a: Any, **k: Any) -> set[str]:
diff --git a/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py b/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py
index d5f28e08..9cf0f24e 100644
--- a/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py
+++ b/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py
@@ -189,7 +189,7 @@ def test_reset_clears_review_state_and_reregisters_defaults(
stale = store.list_items(limit=1)[0]
store.set_status(stale.item_id, ReviewStatus.REJECTED, "previous operator's call")
store.add_annotation(stale.item_id, stale.domain, "stale correction")
- assert store.get_withheld_filenames(rs_mod.ContentType.BUILTIN)
+ assert store.get_withheld_keys(rs_mod.ContentType.BUILTIN)
with patch.object(ChromaDBStore, "delete_company_docs", lambda self: None), \
patch.object(ChromaDBStore, "delete_documents", lambda self, **kw: None):
@@ -199,7 +199,7 @@ def test_reset_clears_review_state_and_reregisters_defaults(
assert counts["rejected"] == 0
assert counts["pending"] == 0
assert counts["approved"] == counts["total"] > 0 # re-registered as defaults
- assert store.get_withheld_filenames(rs_mod.ContentType.BUILTIN) == set()
+ assert store.get_withheld_keys(rs_mod.ContentType.BUILTIN) == set()
assert store.list_annotations(active_only=False) == []
@@ -218,3 +218,70 @@ def test_reset_survives_a_db_without_review_tables(
asyncio.run(fixture_loader.reset_all_state(settings_stub))
assert rs_mod.ReviewStore(db_path=_isolate_dbs).count_by_status()["total"] > 0
+
+
+def test_reset_does_not_unsuppress_surviving_user_knowledge(
+ settings_stub: Any, _isolate_dbs: Path
+) -> None:
+ """A factory reset must not silently return rejected content to RAG.
+
+ The reset wipes `review_items` but does NOT delete user-authored files
+ under `knowledge/builtin/` or their indexed chunks — they live inside the
+ installed package. Without re-registration the rejection vanishes while
+ the content survives, so the doc becomes retrievable again with no review
+ row at all: un-suppressed, and invisible in the queue.
+ """
+ from openexecutive.knowledge import review_store as rs_mod
+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH
+ from openexecutive.knowledge.review_store import (
+ ContentType,
+ ReviewStatus,
+ ReviewStore,
+ build_item_id,
+ )
+
+ upload = BUILTIN_KNOWLEDGE_PATH / "hr" / "severance_terms_draft.md"
+ upload.write_text("# draft, legally unsound", encoding="utf-8")
+ item_id = build_item_id(ContentType.BUILTIN, "hr", upload.name)
+ try:
+ ReviewStore.initialize_db(_isolate_dbs)
+ ReviewStore.sync_builtin_registrations(_isolate_dbs)
+ store = ReviewStore(db_path=_isolate_dbs)
+ store.register(
+ item_id=item_id,
+ content_type=ContentType.BUILTIN,
+ domain="hr",
+ filename=upload.name,
+ )
+ store.set_status(item_id, ReviewStatus.REJECTED, "legally unsound")
+ assert ("hr", upload.name) in store.get_withheld_keys(ContentType.BUILTIN)
+
+ with patch.object(ChromaDBStore, "delete_company_docs", lambda self: None), \
+ patch.object(ChromaDBStore, "delete_documents", lambda self, **kw: None):
+ asyncio.run(fixture_loader.reset_all_state(settings_stub))
+
+ survivor = store.get_item(item_id)
+ assert survivor is not None, "surviving content must keep a review row"
+ assert survivor.status == ReviewStatus.PENDING
+ assert survivor.trusted_default is False
+ # Still withheld from retrieval, and visible in the queue.
+ assert ("hr", upload.name) in store.get_withheld_keys(ContentType.BUILTIN)
+ assert any(i.item_id == item_id for i in store.list_items(limit=500))
+ assert rs_mod # module referenced for the isolation fixture
+ finally:
+ upload.unlink()
+
+
+def test_reset_does_not_requeue_shipped_docs(
+ settings_stub: Any, _isolate_dbs: Path
+) -> None:
+ """The re-registration must only sweep in content the manifest disowns."""
+ from openexecutive.knowledge.review_store import ReviewStore
+
+ with patch.object(ChromaDBStore, "delete_company_docs", lambda self: None), \
+ patch.object(ChromaDBStore, "delete_documents", lambda self, **kw: None):
+ asyncio.run(fixture_loader.reset_all_state(settings_stub))
+
+ counts = ReviewStore(db_path=_isolate_dbs).count_by_status()
+ assert counts["pending"] == 0, "shipped docs must come back as trusted defaults"
+ assert counts["approved"] == counts["total"] > 0
diff --git a/packages/core/tests/unit/test_knowledge_routes_review.py b/packages/core/tests/unit/test_knowledge_routes_review.py
new file mode 100644
index 00000000..769dc801
--- /dev/null
+++ b/packages/core/tests/unit/test_knowledge_routes_review.py
@@ -0,0 +1,163 @@
+"""The write path must not let user content inherit shipped trust."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+os.environ.setdefault("ANTHROPIC_API_KEY", "sk-test-not-used")
+
+from fastapi.testclient import TestClient # noqa: E402
+
+from openexecutive.api.main import create_app # noqa: E402
+from openexecutive.knowledge.review_store import ( # noqa: E402
+ ContentType,
+ ReviewStatus,
+ ReviewStore,
+ build_item_id,
+)
+
+
+def _shipped_failure_pair() -> tuple[str, str]:
+ from pathlib import PurePosixPath
+
+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES
+
+ for rel in sorted(SHIPPED_BUILTIN_FILES):
+ p = PurePosixPath(rel)
+ if p.parts[0] == "failures":
+ return p.parent.name, p.name
+ raise AssertionError("manifest has no failures/ entries")
+
+
[email protected](autouse=True)
+def _isolate_audit(monkeypatch: pytest.MonkeyPatch) -> None:
+ import openexecutive.audit as audit
+
+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)
+
+
+def review_db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> ReviewStore:
+ db = tmp_path / "review.db"
+ ReviewStore.initialize_db(db)
+ ReviewStore.sync_builtin_registrations(db)
+ monkeypatch.setattr("openexecutive.memory.episodic.DB_PATH", db, raising=False)
+ monkeypatch.setattr("openexecutive.knowledge.review_store.DB_PATH", db, raising=False)
+ return ReviewStore(db_path=db)
+
+
+def client(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+ store = MagicMock()
+ store.query.side_effect = lambda **kw: []
+ monkeypatch.setattr(
+ "openexecutive.api.routes.knowledge._get_store", lambda _request: store
+ )
+
+ async def _fake_ingest(path: Any, _store: Any, **kw: Any) -> int:
+ return 1
+
+ monkeypatch.setattr(
+ "openexecutive.knowledge.loader.ingest_builtin_file", _fake_ingest
+ )
+ return TestClient(create_app())
+
+
+def test_upload_cannot_inherit_a_shipped_failure_docs_trust(
+ client: TestClient, review_db: ReviewStore
+) -> None:
+ """The HIGH finding, as a regression test.
+
+ Uploading a built-in doc named after a shipped FAILURE case study used to
+ land on that doc's row and inherit `approved` + `trusted_default = 1` —
+ trusted, never queued, and labelled "Ships with Open Executive".
+ """
+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH
+
+ domain, filename = _shipped_failure_pair()
+ written = BUILTIN_KNOWLEDGE_PATH / domain / filename
+ assert not written.exists(), "fixture assumes the upload path is free"
+ try:
+ res = client.post(
+ "/knowledge/builtin",
+ json={"domain": domain, "filename": filename, "content": "# mine"},
+ )
+ assert res.status_code == 200, res.text
+
+ upload = review_db.get_item(build_item_id(ContentType.BUILTIN, domain, filename))
+ assert upload is not None
+ assert upload.trusted_default is False
+ assert upload.status == ReviewStatus.PENDING
+
+ shipped = review_db.get_item(build_item_id(ContentType.FAILURE, domain, filename))
+ assert shipped is not None
+ assert shipped.trusted_default is True
+ assert shipped.status == ReviewStatus.APPROVED
+ finally:
+ written.unlink(missing_ok=True)
+
+
+def test_upload_is_refused_when_the_id_is_already_a_trusted_default(
+ client: TestClient, review_db: ReviewStore
+) -> None:
+ """Defence in depth: never write onto a shipped row, whatever the namespace."""
+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH
+
+ # Forge the pre-fix situation: a trusted row sitting in the upload namespace.
+ domain, filename = "board", "forged_shipped.md"
+ item_id = build_item_id(ContentType.BUILTIN, domain, filename)
+ ReviewStore.initialize_db(review_db._db_path)
+ import sqlite3
+
+ with sqlite3.connect(review_db._db_path) as conn:
+ conn.execute(
+ "INSERT INTO review_items (item_id, content_type, domain, filename, "
+ "status, trusted_default, registered_at, last_modified_at) "
+ "VALUES (?, 'builtin', ?, ?, 'approved', 1, '2025-01-01', '2025-01-01')",
+ (item_id, domain, filename),
+ )
+
+ written = BUILTIN_KNOWLEDGE_PATH / domain / filename
+ try:
+ res = client.post(
+ "/knowledge/builtin",
+ json={"domain": domain, "filename": filename, "content": "# mine"},
+ )
+ assert res.status_code == 409
+ assert not written.exists(), "refused upload must not have been written"
+ finally:
+ written.unlink(missing_ok=True)
+
+
+def test_user_failure_doc_is_registered_and_blockable(
+ client: TestClient, review_db: ReviewStore
+) -> None:
+ """A user-authored failure case study used to have no review row at all.
+
+ `retrieve_failures` applied a gate that could never reach it, so no SME
+ decision could block it.
+ """
+ from openexecutive.knowledge.loader import FAILURES_KNOWLEDGE_PATH
+
+ written = FAILURES_KNOWLEDGE_PATH / "strategy" / "my_case_study.md"
+ try:
+ res = client.post(
+ "/knowledge/failures",
+ json={"domain": "strategy", "filename": written.name, "content": "# mine"},
+ )
+ assert res.status_code == 200, res.text
+
+ item_id = build_item_id(ContentType.FAILURE, "strategy", written.name)
+ item = review_db.get_item(item_id)
+ assert item is not None, "failure uploads must be registered for review"
+ assert item.trusted_default is False
+ # Registered `pending`, so the gate can actually reach it.
+ assert ("strategy", written.name) in review_db.get_withheld_keys(
+ ContentType.FAILURE
+ )
+ finally:
+ written.unlink(missing_ok=True)
diff --git a/packages/core/tests/unit/test_knowledge_search_and_failures.py b/packages/core/tests/unit/test_knowledge_search_and_failures.py
index bc735903..0e7e21ec 100644
--- a/packages/core/tests/unit/test_knowledge_search_and_failures.py
+++ b/packages/core/tests/unit/test_knowledge_search_and_failures.py
@@ -377,7 +377,7 @@ def test_search_company_bucket_is_never_review_filtered(
from openexecutive.knowledge.review_store import ContentType
_register(review_db, "strategy", "deck.pdf")
- assert "deck.pdf" in review_db.get_withheld_filenames(ContentType.BUILTIN)
+ assert ("strategy", "deck.pdf") in review_db.get_withheld_keys(ContentType.BUILTIN)
data = client.post("/knowledge/search", json={"query": "strategy"}).json()
diff --git a/packages/core/tests/unit/test_retriever_gating.py b/packages/core/tests/unit/test_retriever_gating.py
index ff1ce92f..c17aa163 100644
--- a/packages/core/tests/unit/test_retriever_gating.py
+++ b/packages/core/tests/unit/test_retriever_gating.py
@@ -30,7 +30,7 @@ def _isolate_audit(monkeypatch: pytest.MonkeyPatch) -> None:
def fake_review_store() -> SimpleNamespace:
"""ReviewStore stub that returns empty sets — keep retrieval focused on the gate."""
return SimpleNamespace(
- get_withheld_filenames=lambda _ct: set(),
+ get_withheld_keys=lambda _ct: set(),
get_withheld_source_ids=lambda: set(),
get_priority_map=lambda _ct: {},
list_annotations=lambda domains=None, active_only=True: [],
@@ -182,9 +182,9 @@ def _hit(filename: str, text: str, *, distance: float = 0.1) -> dict[str, Any]:
}
-def _review_store(withheld: set[str]) -> SimpleNamespace:
+def _review_store(withheld: set[tuple[str, str]]) -> SimpleNamespace:
return SimpleNamespace(
- get_withheld_filenames=lambda _ct: withheld,
+ get_withheld_keys=lambda _ct: withheld,
get_withheld_source_ids=lambda: set(),
get_priority_map=lambda _ct: {},
list_annotations=lambda domains=None, active_only=True: [],
@@ -200,7 +200,7 @@ def test_withheld_builtin_chunk_is_not_retrieved() -> None:
out = retrieve(
query="a real question about capital structure",
store=store,
- review_store=_review_store({"queued.md"}),
+ review_store=_review_store({("finance", "queued.md")}),
)
assert "TRUSTED CONTENT" in out
assert "WITHHELD CONTENT" not in out
@@ -251,7 +251,7 @@ def test_retrieve_failures_honors_withheld_items() -> None:
out = retrieve_failures(
query="what went wrong with this rollout",
store=store,
- review_store=_review_store({"bad_case.md"}),
+ review_store=_review_store({("finance", "bad_case.md")}),
)
assert "USEFUL FAILURE STORY" in out
diff --git a/packages/core/tests/unit/test_review_routes.py b/packages/core/tests/unit/test_review_routes.py
index ff616944..e3c00ea4 100644
--- a/packages/core/tests/unit/test_review_routes.py
+++ b/packages/core/tests/unit/test_review_routes.py
@@ -79,7 +79,7 @@ def test_curate_start_queues_a_domain(client: TestClient, store: ReviewStore) ->
assert res.status_code == 200
assert res.json() == {"domain": "finance", "action": "start", "affected_count": 2}
# Queued items are withheld from retrieval; other domains are untouched.
- assert store.get_withheld_filenames(ContentType.BUILTIN) == {"a.md", "b.md"}
+ assert store.get_withheld_keys(ContentType.BUILTIN) == {("finance", "a.md"), ("finance", "b.md")}
def test_curate_stop_restores_a_domain(client: TestClient, store: ReviewStore) -> None:
@@ -90,7 +90,7 @@ def test_curate_stop_restores_a_domain(client: TestClient, store: ReviewStore) -
assert res.status_code == 200
assert res.json()["affected_count"] == 1
- assert store.get_withheld_filenames(ContentType.BUILTIN) == set()
+ assert store.get_withheld_keys(ContentType.BUILTIN) == set()
def test_curate_requires_a_domain(client: TestClient, store: ReviewStore) -> None:
diff --git a/packages/core/tests/unit/test_review_store.py b/packages/core/tests/unit/test_review_store.py
index 3c3c2d39..9e00e1a9 100644
--- a/packages/core/tests/unit/test_review_store.py
+++ b/packages/core/tests/unit/test_review_store.py
@@ -99,11 +99,11 @@ def test_touch_modified_needs_revision_stays(store: ReviewStore) -> None:
# ---------------------------------------------------------------------------
-# get_withheld_filenames
+# get_withheld_keys
# ---------------------------------------------------------------------------
-def test_get_withheld_filenames_covers_rejected_and_pending(store: ReviewStore) -> None:
+def test_get_withheld_keys_covers_rejected_and_pending(store: ReviewStore) -> None:
item_a = _register_builtin(store, filename="ratios.md")
item_b = _register_builtin(store, filename="fundraising.md")
_register_builtin(store, filename="modeling.md") # left pending
@@ -111,15 +111,15 @@ def test_get_withheld_filenames_covers_rejected_and_pending(store: ReviewStore)
store.set_status(item_a.item_id, ReviewStatus.REJECTED)
store.set_status(item_b.item_id, ReviewStatus.APPROVED)
- withheld = store.get_withheld_filenames(ContentType.BUILTIN)
- assert withheld == {"ratios.md", "modeling.md"}
- assert "fundraising.md" not in withheld
+ withheld = store.get_withheld_keys(ContentType.BUILTIN)
+ assert withheld == {("finance", "ratios.md"), ("finance", "modeling.md")}
+ assert ("finance", "fundraising.md") not in withheld
-def test_get_withheld_filenames_empty_when_nothing_withheld(store: ReviewStore) -> None:
+def test_get_withheld_keys_empty_when_nothing_withheld(store: ReviewStore) -> None:
item = _register_builtin(store)
store.set_status(item.item_id, ReviewStatus.APPROVED)
- assert store.get_withheld_filenames(ContentType.BUILTIN) == set()
+ assert store.get_withheld_keys(ContentType.BUILTIN) == set()
def test_get_withheld_source_ids(store: ReviewStore) -> None:
@@ -152,8 +152,8 @@ def test_get_priority_map_only_approved(store: ReviewStore) -> None:
# item_b stays pending — should not appear in priority map
pmap = store.get_priority_map(ContentType.BUILTIN)
- assert pmap.get("a.md") == "high"
- assert "b.md" not in pmap
+ assert pmap.get(("finance", "a.md")) == "high"
+ assert ("finance", "b.md") not in pmap
# ---------------------------------------------------------------------------
@@ -285,7 +285,7 @@ def test_sync_builtin_registers_trusted_defaults(tmp_path: Path) -> None:
assert counts["approved"] == registered
assert all(i.reviewed_at is None for i in store.list_items(limit=500))
# Nothing is withheld, so the Executive can use all of it on day one.
- assert store.get_withheld_filenames(ContentType.BUILTIN) == set()
+ assert store.get_withheld_keys(ContentType.BUILTIN) == set()
def test_builtin_filenames_are_unique_across_domains() -> None:
@@ -482,15 +482,15 @@ def test_withheld_covers_pending_and_rejected_but_not_needs_revision(
store.set_status(revising, ReviewStatus.APPROVED)
store.touch_modified(revising) # an edit → needs_revision
- withheld = store.get_withheld_filenames(ContentType.BUILTIN)
+ withheld = store.get_withheld_keys(ContentType.BUILTIN)
- assert "pending.md" in withheld
- assert "rejected.md" in withheld
- assert "approved.md" not in withheld
+ assert ("finance", "pending.md") in withheld
+ assert ("finance", "rejected.md") in withheld
+ assert ("finance", "approved.md") not in withheld
# An edited-but-previously-vetted file stays available: withholding it
# would make editing a file in the knowledge UI silently delete it.
assert store.get_item(revising).status == ReviewStatus.NEEDS_REVISION # type: ignore[union-attr]
- assert "revising.md" not in withheld
+ assert ("finance", "revising.md") not in withheld
assert pending in {i.item_id for i in store.list_items(status=ReviewStatus.PENDING)}
@@ -669,7 +669,7 @@ def test_backfill_keeps_annotated_shipped_docs_retrievable(tmp_path: Path) -> No
ReviewStore.backfill_trusted_defaults(db)
assert store.count_by_status()["pending"] == 0
- assert store.get_withheld_filenames(ContentType.BUILTIN) == set()
+ assert store.get_withheld_keys(ContentType.BUILTIN) == set()
# The correction survives alongside the doc it corrects.
assert len(store.list_annotations(item_id=annotated)) == 1
@@ -751,3 +751,209 @@ def test_sync_ignores_an_unmanifested_file_in_the_builtin_tree() -> None:
assert "finance/user_upload_probe.md" not in SHIPPED_BUILTIN_FILES
finally:
intruder.unlink()
+
+
+# ---------------------------------------------------------------------------
+# Namespace separation: a user upload must never land on a shipped row
+# ---------------------------------------------------------------------------
+
+
+def _shipped_failure_pair() -> tuple[str, str]:
+ """A real (domain, filename) from the manifest's failures/ entries."""
+ from pathlib import PurePosixPath
+
+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES
+
+ for rel in sorted(SHIPPED_BUILTIN_FILES):
+ p = PurePosixPath(rel)
+ if p.parts[0] == "failures":
+ return p.parent.name, p.name
+ raise AssertionError("manifest has no failures/ entries")
+
+
+def test_failure_docs_do_not_occupy_the_upload_namespace(tmp_path: Path) -> None:
+ """The bug: a shipped failure doc used to own `builtin:<domain>:<file>`.
+
+ That is the id `POST /knowledge/builtin` writes to, and since no file sits
+ at `knowledge/builtin/<domain>/<file>` for a failure doc, that route's
+ `path.exists()` 409 could not fire — the upload INSERT-OR-IGNOREd onto the
+ shipped row and inherited `approved` + `trusted_default = 1`.
+ """
+ from openexecutive.knowledge.review_store import build_item_id
+
+ db = tmp_path / "r.db"
+ ReviewStore.initialize_db(db)
+ ReviewStore.sync_builtin_registrations(db)
+ store = ReviewStore(db_path=db)
+
+ domain, filename = _shipped_failure_pair()
+ upload_id = build_item_id(ContentType.BUILTIN, domain, filename)
+ shipped_id = build_item_id(ContentType.FAILURE, domain, filename)
+
+ assert upload_id != shipped_id
+ # The shipped doc is registered, trusted, under the FAILURE namespace.
+ shipped = store.get_item(shipped_id)
+ assert shipped is not None and shipped.trusted_default is True
+ # ...and the upload namespace is free.
+ assert store.get_item(upload_id) is None
+
+ # An upload of that exact name gets its own untrusted, withheld row.
+ store.register(
+ item_id=upload_id,
+ content_type=ContentType.BUILTIN,
+ domain=domain,
+ filename=filename,
+ )
+ upload = store.get_item(upload_id)
+ assert upload is not None
+ assert upload.trusted_default is False
+ assert upload.status == ReviewStatus.PENDING
+ # The shipped doc is untouched by the upload.
+ assert store.get_item(shipped_id).trusted_default is True # type: ignore[union-attr]
+ assert store.get_item(shipped_id).status == ReviewStatus.APPROVED # type: ignore[union-attr]
+
+
+def test_failure_namespace_migration_carries_the_sme_decision(tmp_path: Path) -> None:
+ """An existing DB has failure rows under the old `builtin:` id.
+
+ Re-keying them must not lose the reviewer's decision, notes, or
+ annotations — those are the only record of a human's judgement.
+ """
+ from openexecutive.knowledge.review_store import build_item_id
+
+ db = _legacy_db(tmp_path)
+ domain, filename = _shipped_failure_pair()
+ old_id = _seed_legacy_pending(db, filename, domain=domain)
+
+ ReviewStore.initialize_db(db)
+ store = ReviewStore(db_path=db)
+ store.set_status(old_id, ReviewStatus.REJECTED, "legally unsound")
+ store.add_annotation(old_id, domain, "our counsel disagrees")
+
+ ReviewStore.sync_builtin_registrations(db) # runs the migration
+
+ new_id = build_item_id(ContentType.FAILURE, domain, filename)
+ assert store.get_item(old_id) is None, "old id must not linger"
+ migrated = store.get_item(new_id)
+ assert migrated is not None
+ assert migrated.status == ReviewStatus.REJECTED
+ assert migrated.reviewer_notes == "legally unsound"
+ anns = store.list_annotations(item_id=new_id)
+ assert [a.correction for a in anns] == ["our counsel disagrees"]
+
+ # Idempotent.
+ ReviewStore.sync_builtin_registrations(db)
+ assert store.get_item(new_id).status == ReviewStatus.REJECTED # type: ignore[union-attr]
+
+
+def test_withheld_key_is_domain_qualified(store: ReviewStore) -> None:
+ """A bare filename was ambiguous AND user-choosable.
+
+ `POST /knowledge/builtin` lets a caller pick any (domain, filename), so
+ uploading a file named after a shipped doc in another domain silently
+ withheld that shipped doc from every specialist.
+
+ The withheld row deliberately sits in a domain that appears nowhere else
+ in this test, and the assertion is exact set equality — a key that dropped
+ or hardcoded the domain would still satisfy a mere `in` check.
+ """
+ store.register(
+ item_id="builtin:hr:product_strategy.md",
+ content_type=ContentType.BUILTIN,
+ domain="hr",
+ filename="product_strategy.md",
+ )
+ shipped = store.register(
+ item_id="builtin:product:product_strategy.md",
+ content_type=ContentType.BUILTIN,
+ domain="product",
+ filename="product_strategy.md",
+ )
+ store.set_status(shipped.item_id, ReviewStatus.APPROVED)
+
+ withheld = store.get_withheld_keys(ContentType.BUILTIN)
+
+ assert withheld == {("hr", "product_strategy.md")}
+ # The same basename in another domain is NOT suppressed.
+ assert ("product", "product_strategy.md") not in withheld
+
+
+def test_priority_map_key_is_domain_qualified(store: ReviewStore) -> None:
+ """Same ambiguity, same fix — a bare filename would collide across domains."""
+ a = store.register(
+ item_id="builtin:hr:handbook.md",
+ content_type=ContentType.BUILTIN,
+ domain="hr",
+ filename="handbook.md",
+ )
+ b = store.register(
+ item_id="builtin:legal:handbook.md",
+ content_type=ContentType.BUILTIN,
+ domain="legal",
+ filename="handbook.md",
+ )
+ store.set_status(a.item_id, ReviewStatus.APPROVED)
+ store.set_status(b.item_id, ReviewStatus.APPROVED)
+ store.set_priority(a.item_id, Priority.HIGH)
+
+ pmap = store.get_priority_map(ContentType.BUILTIN)
+
+ assert pmap[("hr", "handbook.md")] == "high"
+ assert pmap[("legal", "handbook.md")] == "normal"
+
+
+def test_legacy_upgrade_does_not_requeue_failure_docs(tmp_path: Path) -> None:
+ """The migration and the backfill have to compose correctly.
+
+ On a pre-#119 database every shipped row is `pending` under a `builtin:`
+ id. The migration copies that `pending` onto the new `failure:` row — so
+ on its own it would hand back 17 of the 81 backlog items this PR exists to
+ remove. `backfill_trusted_defaults`, which runs afterwards, promotes them
+ because they are `trusted_default = 1` with a NULL `reviewed_at`. Pinning
+ the pair: neither step is correct alone.
+ """
+ import sqlite3
+ from pathlib import PurePosixPath
+
+ from openexecutive.knowledge.review_store import build_item_id
+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES
+
+ db = tmp_path / "legacy.db"
+ ReviewStore.initialize_db(db)
+ ReviewStore.sync_builtin_registrations(db)
+
+ # Rewind to the pre-#119 world: no markers, everything pending, failure
+ # docs sitting in the `builtin:` namespace.
+ fails = [
+ PurePosixPath(r)
+ for r in sorted(SHIPPED_BUILTIN_FILES)
+ if PurePosixPath(r).parts[0] == "failures"
+ ]
+ with sqlite3.connect(db) as conn:
+ conn.execute("UPDATE review_items SET status='pending', reviewed_at=NULL")
+ conn.execute("DELETE FROM review_meta")
+ conn.execute("DELETE FROM review_items WHERE content_type='failure'")
+ for p in fails:
+ conn.execute(
+ "INSERT OR IGNORE INTO review_items (item_id, content_type, domain, "
+ "filename, status, trusted_default, registered_at, last_modified_at) "
+ "VALUES (?, 'builtin', ?, ?, 'pending', 1, '2025-01-01', '2025-01-01')",
+ (f"builtin:{p.parent.name}:{p.name}", p.parent.name, p.name),
+ )
+
+ store = ReviewStore(db_path=db)
+ assert store.count_by_status()["pending"] == store.count_by_status()["total"]
+
+ # The upgrade, in the order api/main.py runs it.
+ ReviewStore.initialize_db(db)
+ ReviewStore.sync_builtin_registrations(db)
+ ReviewStore.backfill_trusted_defaults(db)
+
+ counts = store.count_by_status()
+ assert counts["pending"] == 0, "the backlog must not come back"
+ assert counts["approved"] == counts["total"]
+ # Old ids are gone; the failure gate has nothing withheld.
+ d0, f0 = fails[0].parent.name, fails[0].name
+ assert store.get_item(f"builtin:{d0}:{f0}") is None
+ assert store.get_item(build_item_id(ContentType.FAILURE, d0, f0)) is not None
+ assert store.get_withheld_keys(ContentType.FAILURE) == set()