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.pyindex 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) -> Builtif 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_idfrom openexecutive.knowledge.store import ChromaDBStorestore = _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) -> dif 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_idfrom openexecutive.knowledge.store import ChromaDBStorestore = _get_store(request)@@ -332,7 +361,9 @@ async def delete_builtin_file(domain: str, filename: str, request: Request) -> dwhere={"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) -> Builtchunk_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) -> dwhere={"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_PATHif 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_builtinbuiltin_hits: list[SearchHit] = []external_hits: list[SearchHit] = []diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 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. Approveditems 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` (childfirst) 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+ longerinherits the previous operator's approvals and rejections — a stalerejection would otherwise keep suppressing retrieval on the new box.`clients.slots._ensure_schemas` runs `sync_builtin_registrations` afterdiff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 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.jsonindex 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.jsonindex 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:<domain>:<file>\"] -->|\"register()<br/>trusted_default = 0\"| P\n F[\"Shipped failure doc<br/>failure:<domain>:<file>\"] -->|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.pyindex 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_storepeople_cleared = _delete_all_rows(diff --git a/packages/core/openexecutive/knowledge/retriever.py b/packages/core/openexecutive/knowledge/retriever.pyindex 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 = [rfor 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_builtinand r["metadata"].get("source_id") not in withheld_externaland _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_thresholdrs = 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([rfor r in raw- if r["metadata"].get("filename") not in withheld+ if (r["metadata"].get("domain"), r["metadata"].get("filename")) not in withheldand r["distance"] <= threshold])diff --git a/packages/core/openexecutive/knowledge/review_store.py b/packages/core/openexecutive/knowledge/review_store.pyindex 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 = 0for 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@staticmethoddef 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 queuedthe item for curation, and the architecture contract is that theExecutive never sees pending material — shipped content registers asan 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 anitem there on *any* content edit, so withholding it would make editinga 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.pyindex 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.MonkeyPatchclass _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.pyindex 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"] == 0assert counts["pending"] == 0assert 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"] > 0diff --git a/packages/core/tests/unit/test_knowledge_routes_review.py b/packages/core/tests/unit/test_knowledge_routes_review.pynew file mode 100644index 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.pyindex 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.pyindex 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 outassert "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 outdiff --git a/packages/core/tests/unit/test_review_routes.py b/packages/core/tests/unit/test_review_routes.pyindex 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 == 200assert 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 == 200assert 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.pyindex 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 mappmap = 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"] == registeredassert 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 withheldassert 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) -> NoReviewStore.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_FILESfinally: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()