AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
fix(review): ship built-in knowledge trusted instead of as an 81-item backlog
Rufuseb69f476a44b
diff --git a/README.md b/README.mdindex cf5fd65a..855efb53 100644--- a/README.md+++ b/README.md@@ -181,6 +181,8 @@ The first time you visit the app, you'll be guided through a wizard to set up yoAfter onboarding, the Executive will reference your specific company context in every response.+The built-in knowledge base is **trusted by default** — the Executive can use it straight away, and the Review queue starts empty rather than asking you to sign off on ~81 shipped documents. Items reach the queue when you upload a document, edit an existing file, or deliberately send a domain for review from the Review page. While a domain is being reviewed its content is withheld from the Executive, so the UI confirms the count before it starts.+## Interfaces| Interface | How to Use |diff --git a/packages/core/openexecutive/api/main.py b/packages/core/openexecutive/api/main.pyindex 52345fad..71d50925 100644--- a/packages/core/openexecutive/api/main.py+++ b/packages/core/openexecutive/api/main.py@@ -275,8 +275,14 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:from openexecutive.knowledge.external_sources import load_manifestfrom openexecutive.knowledge.review_store import ReviewStore- ReviewStore.initialize_db()- ReviewStore.sync_builtin_registrations()+ # Pass the path the readers resolve (`api/routes/review._store` and+ # `retriever._default_review_store` both use `memory.episodic.DB_PATH`).+ # `review_store.DB_PATH` is bound at import, so a bare call could write the+ # backfill marker to a different file than the app reads.+ from openexecutive.memory.episodic import DB_PATH as REVIEW_DB_PATH++ ReviewStore.initialize_db(REVIEW_DB_PATH)+ ReviewStore.sync_builtin_registrations(REVIEW_DB_PATH)# Register any OER sources that were already ingested before this PR deployed.ingested_external = [@@ -285,7 +291,13 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:if src.cache_dir.exists() and any(src.cache_dir.iterdir())]if ingested_external:- ReviewStore.sync_external_registrations(ingested_external)+ ReviewStore.sync_external_registrations(ingested_external, REVIEW_DB_PATH)++ # One-shot legacy migration. Must run AFTER both syncs: it only promotes+ # rows they have flagged as shipped, so an older install's phantom+ # "81 items need review" backlog clears without touching a user's own+ # uploads that are genuinely awaiting a first review.+ ReviewStore.backfill_trusted_defaults(REVIEW_DB_PATH)from openexecutive.evals.persistence import (initialize_eval_runs_db,diff --git a/packages/core/openexecutive/api/routes/review.py b/packages/core/openexecutive/api/routes/review.pyindex b3b817a9..1bad8cb7 100644--- a/packages/core/openexecutive/api/routes/review.py+++ b/packages/core/openexecutive/api/routes/review.py@@ -1,11 +1,12 @@from __future__ import annotations-from typing import Any+from typing import Any, Literalfrom fastapi import APIRouter, HTTPExceptionfrom pydantic import BaseModel, ConfigDict, Fieldfrom openexecutive.knowledge.review_store import (+ BULK_MAX_IDS,Annotation,ContentType,Priority,@@ -37,11 +38,35 @@ class ReviewItemPatch(BaseModel):class BulkApproveRequest(BaseModel):- domain: str | None = None+ model_config = ConfigDict(str_strip_whitespace=True)++ # min_length matters: the store treats a falsy domain as "no filter", so a+ # `""` here would pass the selector guard below and then silently widen to+ # every pending item in every domain.+ domain: str | None = Field(default=None, min_length=1)+ item_ids: list[str] | None = Field(default=None, max_length=BULK_MAX_IDS)+ # Approving the entire queue is a real action, not a default. Requiring an+ # explicit opt-in keeps a selector-less call from silently clearing+ # everything when a caller meant to pass a filter and forgot.+ all_pending: bool = Falseclass BulkApproveResponse(BaseModel):approved_count: int+ item_ids: list[str]+++class CurateRequest(BaseModel):+ model_config = ConfigDict(str_strip_whitespace=True)++ domain: str = Field(..., min_length=1, max_length=200)+ action: Literal["start", "stop"]+++class CurateResponse(BaseModel):+ domain: str+ action: Literal["start", "stop"]+ affected_count: intclass AnnotationCreate(BaseModel):@@ -134,8 +159,66 @@ async def update_review_item(item_id: str, body: ReviewItemPatch) -> ReviewItem:@router.post("/bulk-approve", response_model=BulkApproveResponse)async def bulk_approve(body: BulkApproveRequest) -> BulkApproveResponse:- count = _store().bulk_approve(domain=body.domain)- return BulkApproveResponse(approved_count=count)+ if body.domain is None and body.item_ids is None and not body.all_pending:+ raise HTTPException(+ status_code=400,+ detail="Provide 'domain', 'item_ids', or 'all_pending': true.",+ )+ ids = _store().bulk_approve(domain=body.domain, item_ids=body.item_ids)+ if ids:+ from openexecutive.audit import log_event as audit_log++ audit_log(+ "review_bulk_approve",+ f"Bulk approve: {len(ids)} knowledge item(s)",+ actor="user",+ details={+ "count": len(ids),+ "item_ids": ids[:100],+ "domain": body.domain,+ "all_pending": body.all_pending,+ },+ )+ return BulkApproveResponse(approved_count=len(ids), item_ids=ids)++[email protected]("/curate", response_model=CurateResponse)+async def curate_domain(body: CurateRequest) -> CurateResponse:+ """Opt one domain's shipped defaults into (or out of) the review queue.++ Built-in knowledge ships as a trusted default, so the queue is empty until+ the user asks to curate something. `domain` is required on purpose: while a+ domain is being curated its items are `pending`, and pending is withheld+ from retrieval — no single call should be able to take the whole knowledge+ base away from the Executive.+ """+ store = _store()+ if body.action == "start":+ count = store.queue_for_curation(body.domain)+ else:+ count = store.stop_curation(body.domain)++ if count:+ from openexecutive.audit import log_event as audit_log++ verb = "queued for curation" if body.action == "start" else "restored to default"+ audit_log(+ "review_curate",+ f"{count} item(s) in '{body.domain}' {verb}",+ actor="user",+ details={+ "domain": body.domain,+ "action": body.action,+ "count": count,+ },+ )+ return CurateResponse(domain=body.domain, action=body.action, affected_count=count)++[email protected]("/trusted-defaults", response_model=dict[str, int])+async def trusted_defaults_by_domain() -> dict[str, int]:+ """Domain → count of never-reviewed shipped defaults, for the curate UI."""+ return _store().count_trusted_defaults_by_domain()# ---------------------------------------------------------------------------diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex c91adb57..fa256e2c 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -2151,10 +2151,110 @@ external_monitoring:review:store: openexecutive.knowledge.review_store.ReviewStore (shares episodic_memory.db).+ default_state: |+ Shipped content is TRUSTED ON ARRIVAL. `sync_builtin_registrations` and+ `sync_external_registrations` register `approved` with a NULL+ `reviewed_at`, so a new instance starts with an EMPTY review queue.+ Before this, all 81 built-in docs registered `pending`, and a brand-new+ box greeted its first user with "81 items need review" — work nobody had+ a basis to do on day one, gating nothing.++ PROVENANCE IS AN EXPLICIT COLUMN FED BY A COMMITTED MANIFEST — never+ inferred, and never re-derived from the filesystem. Two mistakes were+ caught here in review, both of which silently approved a user's own+ unvetted document and labelled it "shipped" in the UI:+ 1. Keying on (pending, reviewed_at NULL). A brand-new upload via+ `POST /knowledge/builtin` -> `ReviewStore.register()` has exactly+ that shape.+ 2. Keying on "a .md file exists under knowledge/builtin/". That route+ writes the user's file into that SAME tree+ (`api/routes/knowledge._resolve_path`), so a directory scan re-flagged+ uploads as shipped on the next boot.+ So `review_items.trusted_default` (INTEGER, default 0; additive ALTER for+ older DBs) is set to 1 only for paths listed in+ `knowledge/shipped_manifest.py::SHIPPED_BUILTIN_FILES`, which+ `sync_builtin_registrations` iterates instead of rglobbing the tree.+ Regenerate that manifest when adding or removing a built-in doc;+ `test_shipped_manifest_matches_git` fails on drift. `register()` never+ sets the flag, so user content stays `trusted_default = 0` forever.++ Two states, read together:+ - trusted_default=1, approved, reviewed_at IS NULL -> shipped, unvetted+ - approved + reviewed_at set -> an SME signed off+ `count_trusted_defaults_by_domain()` counts the first kind and drives the+ "Curate N" affordance. The UI reads `trusted_default` off the API rather+ than inferring it.++ MIGRATION ORDER MATTERS. `ReviewStore.backfill_trusted_defaults()` must run+ AFTER both registration syncs, because it only touches rows they have+ flagged `trusted_default = 1`. Call sites: `api/main.py` lifespan and+ `clients/slots._ensure_schemas`. A `review_meta` marker row+ (`trusted_defaults_backfill_v1`) makes it fire exactly once, written under+ `BEGIN IMMEDIATE` with `INSERT OR IGNORE` so two workers booting together+ cannot raise a UNIQUE violation out of the lifespan. The marker lives in+ `review_meta` rather than `PRAGMA user_version` because+ `episodic_memory.db` is shared with episodic memory, alerts, people,+ talent and more.++ The migration's rule is NO SHIPPED DOC LOSES RETRIEVABILITY ON UPGRADE.+ Its only exclusion is `reviewed_at IS NULL` (which `set_status` always+ stamps, so every explicit approve/reject is skipped). Notes and+ annotations deliberately do NOT hold a row back: `retrieve_context`+ injects annotations by DOMAIN regardless of item status, so withholding an+ annotated doc would feed the Executive a correction to a document it can+ no longer see.effect_on_retrieval: |- Rejected items are filtered out of every retrieval. Approved items- can be promoted in priority. The Executive never sees pending items- until an SME approves them.+ WITHHELD = `pending` OR `rejected`. `get_withheld_filenames(content_type)`+ is the single query the retrieval path uses; it replaced the old+ rejected-only lookups, which no longer exist.++ Both `retrieve_context` and `retrieve_failures` apply it. The failures+ path is the one that used to leak: failure case studies are registered+ for review but indexed into FAILURES_COLLECTION, and `retrieve_failures`+ consulted no review state at all, so rejecting a failure case study did+ nothing.++ The gate is now real. It could only be made real once shipped content+ defaulted to approved — enforcing it beforehand would have left a fresh+ instance with zero retrievable knowledge.++ `needs_revision` is deliberately NOT withheld. `touch_modified` flips an+ item there on ANY content edit, so withholding it would make editing a+ file in the knowledge UI silently delete it from retrieval. Approved+ items can still be promoted in priority.++ The filter keys on bare `filename` (that is what Chroma metadata carries),+ not `item_id`. All 81 built-in basenames are unique across domains and a+ unit test pins that invariant — a duplicate basename would make a withheld+ item in one domain silently suppress another domain's file.+ curation: |+ Opt-in, per domain. `POST /review/curate {domain, action: start|stop}`+ moves a domain's untouched trusted defaults to `pending` (and back).+ Both directions require `trusted_default = 1 AND reviewed_at IS NULL`, so+ neither a user's own upload nor an item an SME decided on is ever moved.++ `domain` is REQUIRED — there is no "curate everything" selector. While a+ domain is curated its items are withheld, so no single call may take the+ whole knowledge base away from the Executive. The UI confirms with the+ exact count before starting.+ bulk_approve: |+ `POST /review/bulk-approve` selects by `domain` (min_length=1 —+ the store reads a falsy domain as "no filter", so an empty string would+ widen a scoped call to every pending item), an explicit `item_ids` list+ (over BULK_MAX_IDS=500 raises rather than silently truncating), or+ `all_pending: true`. A call with no selector is a 400 —+ the same "a bulk call must always carry a selector" rule as+ `/alerts/bulk-ack`. Returns `{approved_count, item_ids}` and writes a+ `review_bulk_approve` audit event; `/review/curate` writes `review_curate`.+ reset_and_slots: |+ `reset_all_state` wipes `review_annotations` + `review_items` (child+ first) and re-registers the shipped docs — built-in and any ingested OER+ sources — so a factory reset no longer+ inherits the previous operator's approvals and rejections — a stale+ rejection would otherwise keep suppressing retrieval on the new box.+ `clients.slots._ensure_schemas` runs `sync_builtin_registrations` after+ `initialize_db`, so a newly activated client slot has its trusted+ defaults immediately instead of an empty table until the next restart.workflows:contract: Structured input → ordered named steps → rendered Markdown artifact.diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 137a3f95..5caafdb4 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. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |","mermaid": null,- "generated_at": "2026-09-12T12:03:38.574978+00:00"+ "generated_at": "2026-09-16T09:58:32.694362+00:00"}diff --git a/packages/core/openexecutive/architecture/prebuilt/clients.json b/packages/core/openexecutive/architecture/prebuilt/clients.jsonindex b7a3a4fb..8aed28e1 100644--- a/packages/core/openexecutive/architecture/prebuilt/clients.json+++ b/packages/core/openexecutive/architecture/prebuilt/clients.json@@ -1,7 +1,7 @@{"section_id": "clients","title": "Client Companies (Slots)",- "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* \u2014 save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored \u2014 client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB \u2014 chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults \u2014 departments, onboarding templates, principal briefs, cadences \u2014 so the new client's Today page works without a restart. That wipe covers the **derived caches** \u2014 `briefing_narrative` and `person_insights` \u2014 as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active \u2014 recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase \u2014 aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one \u2014 a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` \u2014 a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup \u2014 a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe \u2014 on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments \u2014 so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent \u2014 the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent \u2014 unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** \u2014 your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact \u2014 editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** \u2014 no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** \u2014 a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones \u2014 single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** \u2014 then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am \u2014 rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings \u2192 advanced tools.",+ "markdown": "The **clients** module (`openexecutive.clients`) adds **multi-client mode** for fractional executives: one Open Executive instance serving several client companies, exactly **one active at a time**. It generalizes the fixture switcher's swap machinery into named, durable *slots* — save files of the full company context. Single-company installs are untouched: nothing changes until a slot is explicitly created, and the `/clients` page shows only an intro until then.\n\n## What a slot contains\n\nEach slot lives at `company/_client_slots/<slug>/` (gitignored — client data is never committable):\n\n| Artifact | What it carries |\n| --- | --- |\n| `state.db` | A transactionally-consistent copy of the shared SQLite DB — chat history, scheduled actions, onboarding plans, talent pipeline, departments, people, watchlist, audit/run history |\n| `profile.yaml` | The company profile |\n| `docs/`, `skills/` | Company documents (all file types) and company-authored skills |\n| `mcp_servers.json` | Per-client external MCP tools (e.g. one client's Crayon or Google Workspace credentials) |\n| `meta.json` | Display name + created/saved timestamps |\n\n## Switching\n\n`POST /clients/{slug}/activate` saves the current client back to its slot (`VACUUM INTO` for the DB copy), then restores the target: the DB through sqlite3's online **backup API** (the live file's inode never changes, so handles held elsewhere stay valid), the company artifacts by replacement, and the ChromaDB `company_docs` collection + company skills re-indexed from the restored directories. Idempotent schema initializers re-run after every restore, so a slot saved before a schema-adding deploy gains the new tables. Activating a **blank** slot (created with `source: \"blank\"`, no `state.db` yet) factory-wipes the per-client tables and re-seeds defaults — departments, onboarding templates, principal briefs, cadences — so the new client's Today page works without a restart. That wipe covers the **derived caches** — `briefing_narrative` and `person_insights` — as well as authored state. They are regenerable, but `/today` serves them from cache and only regenerates in a background task, so a surviving row renders the *outgoing* client's briefing text under the incoming one, and `person_insights` reaches Discord, the MCP server, and the morning/end-of-day digests as well as the UI. Switching into a slot that already has `state.db` was never exposed: the sqlite backup API truncates the destination to an exact copy of the source.\n\nThe first activation from single-company mode auto-snapshots the original company to `_user_backup` (the same restore point the fixture switcher uses); `POST /fixtures/unload` brings it back and exits client mode.\n\n## Invariants\n\n- At most one slot is active — recorded in an allowlist-validated `.active_client` sentinel.\n- **Only the active client is live**: its scheduled actions fire, its docs are indexed; parked clients sleep. The single-instance scheduler constraint is unchanged.\n- Slot operations share the fixture switcher's destructive-op lock, so fixture loads, snapshots, resets, and slot switches serialize against each other. The Notion sync tick coordinates with the same lock without queueing on it: it skips its tick while the lock is held, fetches from Notion unlocked, and takes the lock only for its short local write phase — aborting without writing if the active client changed mid-fetch (in-process only; a CLI run is a separate process the lock cannot see). A fixture and a client are never active simultaneously (slot ops refuse with 409 while a fixture is loaded); loading a fixture saves an active client back to its slot first, so demos can never destroy client work. Factory reset clears the active-client sentinel but preserves slot directories.\n- `generated_fixtures` is operator-level (the demo library) and is preserved verbatim across switches.\n- **Every path that swaps the live company wipes the derived caches**, from one shared list (`cli.fixture_loader.PER_CLIENT_CACHE_TABLES`): blank/seed slot activation, factory reset, and fixture load *and* unload. Three hand-maintained copies of that list is what let the leak survive in two paths after being fixed in one — a new per-company cache table goes in the constant, once. On the fixture path the wipe runs in `_apply_state_from_source`, unconditionally: a fixture needs only `profile.yaml`, so gating it on `memory.json` would skip exactly the loads that still swap the company.\n- Do **not** treat `person_insights`' `input_hash` as a guard against this. It covers per-person signals (role, principal flag, status, counters, availability, authority and department scope, bucketed timestamps, the UTC day) but carries no person, name or company identity, and the cache key is `person_id` — a reused autoincrement PK. An outgoing principal and a freshly seeded incoming one hash identically whenever those signals coincide, which is ordinary steady state for a seeded slot.\n- Each client gets a stable Honcho workspace (`openexec-client-<slug>`) so peer memory survives parking; fixture teardown paths recognise the prefix and never delete these.\n\n## Caveats\n\n`mcp_servers.json` is read by the MCP gateway at process startup — a switch that changes it takes effect on the next API restart (the activate response carries `mcp_config_changed`). Scheduled actions whose `run_at` passed while a client was parked are claimed on the first tick after activation; authority gates still apply, but expect the returning client's overdue follow-ups to fire shortly after a switch.\n\nTwo residuals. `/today`'s background regeneration tasks capture the outgoing company's data and can write it back into the live DB for up to roughly 25 seconds after the wipe — on **every** swapping path, fixture load/unload and slot activation alike, since those writers neither take the destructive-op lock nor check company identity. For `person_insights` it does not self-heal: the late write stores the outgoing `input_hash`, which the incoming person's signals often match, so the stale note survives until the UTC-day bucket rolls. Closing this needs company identity in the cache hash or those writers taking the lock. Second, and blank-slot only, `dynamic_workflows` / `eval_scenarios` are client-scoped but **not** wiped: they are authored rather than derived, and the first-activation snapshot captures only profile, docs, `memory.json`, people and departments — so wiping them before extending that snapshot would destroy the operator's own work. Until then the outgoing client's workflow definitions stay registered and active on the blank path, runnable against the incoming client's data and readable via `/workflows`.\n\n## Setting up a new engagement with AI\n\n`POST /clients/generate` turns **real intake material** into a reviewable draft of the client: profile, org, roster, starter docs, and known history. Intake material is pasted text (kickoff-call notes, a brief, website copy) and/or **file attachments** (PDF, Word, Excel, CSV, Markdown/text; the request is multipart). Each attachment's extracted text both feeds the draft and is appended to the bundle as a `source_<name>.md` company doc, so it lands in the seed slot and is indexed into the `company_docs` collection on activation alongside the AI-written docs (extracted text, not the original binary; legacy `.xls` is unsupported). It runs the Council-configurable `engagement_intake` agent — the grounded sibling of the demo fixture generator (same bundle schema, validation, and repair-retry; the Company Simulator's fictional path is unchanged). Grounding rules: extract, don't invent — unstated numbers stay null, only people named in the material appear, docs are engagement working documents (intake brief, current-state summary, stakeholder map, open questions), and **no contact handles are ever imported**, even if present in the notes.\n\nSaving the reviewed draft (`POST /clients` with `source: \"generated\"`) writes a **seed slot**: profile and docs as normal slot artifacts, plus `people.yaml` / `departments.yaml` / `memory.json` in the same shapes curated fixtures use. Nothing touches live state until activation, when the blank-restore path applies the seed files with the fixture loader's seeders and skips the default-department reseed (the draft supplied the org). After the first save-back writes `state.db`, the seed files remain as the engagement's birth record but are no longer consulted; `meta.json` records `origin: \"generated\"` and the intake notes.\n\n## The practice layer: engagement metadata + cockpit\n\nEach slot's `meta.json` carries optional **engagement metadata** — your role for the client, engagement status (active/paused/winding down/completed), start and renewal dates, retainer (display only), and primary contact — editable via `PATCH /clients/{slug}` for active *and* parked slots, because meta.json lives outside the swapped client state. Renewal awareness deliberately lives here and never as scheduled actions (those swap with the client and would vanish when parked).\n\nThe **practice cockpit** (`GET /clients/cockpit`) gives cross-client awareness without touching the one-active-client ceiling: the active client is counted from the live DB, and each parked client's `state.db` is opened **read-only, in place** — no activation, no lock. Cards roll up pending/overdue follow-ups, awaiting replies, unread alerts, onboarding tasks due within a week, and renewal countdowns. Parked data is as fresh as the slot's last save point and every card says so; one broken slot degrades to a single error-flagged card, never a failed board. Cockpit cards link to the **engagement value report** — a workflow that turns the client's own record (decisions, deliverables, follow-through) into a renewal-ready artifact, reading parked clients without activating them. With two or more clients, `/today` gains an \"Across your clients\" section for the parked ones — single-company installs see none of this, anywhere.\n\n## Overnight rotation (cockpit v2)\n\nWith `CLIENT_ROTATION_ENABLED=true` (off by default), a nightly scheduled job (`CLIENT_ROTATION_TIME`, default 03:30 UTC) activates each parked client in turn, generates its morning brief as an artifact in that client's own record, runs its monitor scan, saves it back, and **always restores the original active client** — then delivers one cross-client digest via the original client's principal channel. Two safety rails matter: the scheduler **pauses claiming** while the rotation's `.rotation_in_progress` marker exists (so a just-activated client's overdue outbound backlog can never fire at 3am — rotation does brief + monitors only, never outbound), and the rotation row is re-seeded after every slot activation because scheduled rows swap with the client. Completed engagements and never-activated slots sleep through rotation; per-client failures are skipped and reported in the digest.\n\n## API + UI\n\n`GET /clients` (list + active + fixture status), `POST /clients` (`source: \"current\"` captures the live company and activates; `\"blank\"` creates an empty client to onboard fresh; `\"generated\"` saves a reviewed intake draft as a seed slot), `POST /clients/generate` (grounded AI draft from intake notes and/or file attachments; multipart), `PATCH /clients/{slug}` (engagement metadata), `GET /clients/cockpit` (practice board), `POST /clients/save` (checkpoint without switching), `POST /clients/{slug}/activate`, `DELETE /clients/{slug}` (refuses the active slot). The `/clients` page lives under Settings → advanced tools.\n\n**Knowledge review state per slot.** `_ensure_schemas` re-runs the idempotent schema inits after a restore, including `ReviewStore.initialize_db` followed by `sync_builtin_registrations`. Without that second call a freshly activated slot carried an empty `review_items` table until the next process restart; now it gets the shipped docs as trusted defaults straight away, matching a normal boot.","mermaid": "flowchart TD\n UI[\"/clients page (Settings)\"] -->|\"activate slug\"| Lock[\"destructive-op lock (shared with fixtures)\"]\n Lock --> SaveBack[\"save-back: VACUUM INTO state.db + copy profile / docs / skills / mcp\"]\n SaveBack --> SlotA[(\"slot A dir\")]\n SlotB[(\"slot B dir\")] --> Restore[\"restore: sqlite backup API + artifact replacement\"]\n Lock --> Restore\n Restore --> Live[(\"live company context\")]\n Restore --> Chroma[\"reindex company_docs + skills\"]\n Restore -.stable workspace.-> Honcho[\"Honcho peer memory\"]\n Live --> Scheduler[\"scheduler: only the ACTIVE client's actions fire\"]",- "generated_at": "2026-09-07T00:00:00Z"+ "generated_at": "2026-09-16T09:20:23.406805+00:00"}\ No newline at end of filediff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.jsonindex a09bb6a4..54d1c3c6 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** \u2014 curated MBA-style domain knowledge shipped with the repo.\n- **COMPANY** \u2014 customer documents ingested via the `/documents` endpoint. Curated uploads only \u2014 synced Notion pages do not land here.\n- **NOTION_WIKI** \u2014 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** \u2014 recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** \u2014 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 \u2014 e.g. `cso`\u2192`strategy`, `cpo`\u2192`product`,`strategy`, `board_comms`\u2192`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block \u2014 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.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `board_comms`→`board`,`finance`. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve_context` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `filename` metadata Chroma carries, which relies on built-in basenames being unique across domains — a unit test pins that.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.","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-08-31T00:00:00+00:00"-}+ "generated_at": "2026-09-16T09:20:23.351660+00:00"+}\ No newline at end of filediff --git a/packages/core/openexecutive/architecture/prebuilt/review.json b/packages/core/openexecutive/architecture/prebuilt/review.jsonindex dbcb4711..4e15d18a 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 flows into retrieval passes through a subject-matter-expert (SME) review gate before it can influence the Executive. The queue and its decisions live in `openexecutive.knowledge.review_store.ReviewStore`, which shares the same `./episodic_memory.db` SQLite database as episodic memory.\n\nItems enter the queue in a pending state. An SME then resolves each one:\n\n- **Pending** — awaiting an SME decision. The Executive never sees pending items; they are excluded from every retrieval until resolved.\n- **Rejected** — filtered out of every retrieval. A rejected item can never surface in a specialist's context.\n- **Approved** — eligible for retrieval, and can be promoted in priority so it ranks ahead of unprioritized material.\n\n### Effect on retrieval\n\nThe gate is a filter layered on top of the normal RAG path: a chunk only reaches a specialist if it is approved (or never required review). Rejection is durable and global — it removes the item from all future queries rather than just down-ranking it. Approval with priority promotion lets an SME push vetted, high-value knowledge to the top of the retrieved set. The net effect is that the curated knowledge the Executive reasons over is exactly the set an SME has signed off on, with rejected material held back and pending material invisible.",- "mermaid": "flowchart TD\n In[\"New knowledge item\"]\n Queue[\"Pending review queue<br/>ReviewStore\"]\n SME{\"SME decision\"}\n Rej[\"Rejected<br/>excluded from all retrieval\"]\n App[\"Approved<br/>priority promotion\"]\n RAG[\"Retrieval\"]\n Spec[\"Specialist context\"]\n In --> Queue\n Queue --> SME\n SME -->|reject| Rej\n SME -->|approve| App\n App --> RAG\n RAG --> Spec\n class In entry\n class Queue storage\n class SME compute\n class RAG compute\n class Spec hot\n",- "generated_at": "2026-06-01T00:00:00+00:00"+ "markdown": "Knowledge that reaches a specialist passes through a subject-matter-expert (SME) review gate. The queue and its decisions live in `openexecutive.knowledge.review_store.ReviewStore`, which shares the `./episodic_memory.db` SQLite database with episodic memory.\n\n### Shipped knowledge is trusted on arrival\n\nThe ~81 Markdown files under `knowledge/builtin/` are curated upstream and ship with the product. They register as **trusted defaults** — `approved`, with a NULL `reviewed_at` — so a new instance starts with an **empty** review queue and the Executive can draw on that material immediately. The same applies to manifest-listed external (OER) sources.\n\nProvenance is an explicit `trusted_default` column, fed by a committed manifest — it is never inferred. That matters more than it looks: a document a user creates through the knowledge UI is *also* `pending` with a NULL `reviewed_at`, **and** it is written into the same `knowledge/builtin/` tree the shipped docs live in. So neither the status shape nor the presence of a file on disk can tell the two apart. `sync_builtin_registrations` walks `SHIPPED_BUILTIN_FILES` rather than the directory, and `register()` — the path user uploads take — never sets the flag.\n\nRead together with `reviewed_at`:\n\n| State | `reviewed_at` | Meaning |\n|---|---|---|\n| `approved` + `trusted_default` | *NULL* | **Trusted default** — shipped with the product, nobody here has vetted it |\n| `approved` | set | An SME signed off, and can promote the item in priority |\n| `pending` | — | Deliberately queued for curation |\n| `rejected` | set | An SME rejected it |\n| `needs_revision` | — | Was decided on; the content has since been edited |\n\nAn install that predates this registers its shipped docs as `pending`. `ReviewStore.backfill_trusted_defaults()` promotes them once, guarded by a marker row in `review_meta`. It runs *after* the registration syncs, because it only touches rows they have flagged as shipped — a user's own upload awaiting review is never approved on their behalf.\n\nIts rule is that **no shipped doc loses retrievability on upgrade**: the sole exclusion is an explicit SME decision (which always stamps `reviewed_at`). Reviewer notes and annotations do not hold a row back — annotations are injected into specialist context by domain regardless of item status, so withholding an annotated doc would hand the Executive a correction to a document it can no longer see.\n\n### Effect on retrieval\n\nAn item is **withheld** when it is `pending` *or* `rejected`. Withheld items are filtered out of every retrieval — `retrieve_context` for the built-in and external collections, and `retrieve_failures` for the failure case studies, which share the same review registrations but live in their own Chroma collection.\n\nBecause shipped content defaults to approved, `pending` genuinely means *a human deliberately queued this*, which is what makes withholding it safe. `needs_revision` is deliberately **not** withheld: an item lands there on any content edit, so withholding it would make editing a file in the knowledge UI silently drop it from retrieval.\n\n### Curation is opt-in, one domain at a time\n\n`POST /review/curate` with `{\"domain\": \"finance\", \"action\": \"start\"}` moves that domain's untouched trusted defaults into the queue; `\"stop\"` puts them back. Neither direction disturbs an item an SME actually decided on.\n\n`domain` is required. There is no \"curate everything\" selector, because curating withholds content — no single call should be able to take the whole knowledge base away from the Executive. The UI names the exact count before it starts.\n\n`POST /review/bulk-approve` clears the queue again, selecting by `domain`, an explicit `item_ids` list (over 500 is rejected rather than silently truncated), or `all_pending: true`. A call carrying no selector is rejected, and so is an empty `domain` — the store reads a falsy domain as \"no filter\", so accepting one would quietly turn a scoped approve into a blanket one. Both endpoints write audit events (`review_bulk_approve`, `review_curate`).\n\n### SME annotations\n\nAlongside a status, an SME can attach **annotations** — free-text corrections stored in `review_annotations` and injected into retrieved context for the item's domain. They let an expert correct or localize shipped material without editing the underlying file.",+ "mermaid": "flowchart TD\n A[\"Shipped doc<br/>(builtin / OER manifest)\"] -->|\"sync_*_registrations<br/>sets trusted_default = 1\"| B[\"approved<br/>reviewed_at = NULL<br/><b>trusted default</b>\"]\n U[\"User upload<br/>(POST /knowledge/builtin)\"] -->|\"register()<br/>trusted_default = 0\"| P\n B -->|retrievable| R([\"Specialist context\"])\n B -->|\"POST /review/curate<br/>action: start\"| P[\"pending\"]\n P -->|\"action: stop\"| B\n P -.->|withheld| X[\"Never reaches<br/>the Executive\"]\n P -->|approve| S[\"approved<br/>reviewed_at set<br/><b>SME signed off</b>\"]\n P -->|reject| J[\"rejected\"]\n J -.->|withheld| X\n S -->|retrievable, priority applies| R\n S -->|content edited| N[\"needs_revision\"]\n N -->|still retrievable| R\n",+ "generated_at": "2026-09-16T10:10:18.071509+00:00"}diff --git a/packages/core/openexecutive/cli/fixture_loader.py b/packages/core/openexecutive/cli/fixture_loader.pyindex 82885d5c..36a73652 100644--- a/packages/core/openexecutive/cli/fixture_loader.py+++ b/packages/core/openexecutive/cli/fixture_loader.py@@ -732,6 +732,53 @@ async def reset_all_state(),)+ # 3c. Knowledge review state (same DB as the episodic rows above). A+ # "factory reset" that keeps the previous operator's approvals,+ # rejections and SME annotations is not a factory reset — and a+ # rejection still suppresses retrieval, so a stale one would silently+ # withhold knowledge on the new box. Wipe both tables (child first for+ # FK ordering), then re-register the shipped docs so the reset state is+ # trusted defaults rather than an empty table.+ # Resolve the review DB through ``memory.episodic.DB_PATH`` like every+ # other consumer (``api/routes/review._store``,+ # ``retriever._default_review_store``). ``review_store.DB_PATH`` is+ # bound at import, so using it here could wipe a different file than+ # the one the app reads under a runtime override.+ from openexecutive.knowledge.review_store import ReviewStore+ from openexecutive.memory.episodic import DB_PATH as _REVIEW_DB_PATH++ # Guarded like the episodic wipe above: never materialise a DB the+ # caller never created. ``sqlite3.connect`` creates the file, so an+ # unguarded initialize_db + sync would leave ~81 rows in a stray DB.+ if _REVIEW_DB_PATH.exists():+ # ``_delete_all_rows`` guards a missing FILE but not a missing+ # TABLE, and nothing guarantees the review schema exists here (a+ # slot restored before these tables shipped, or a test DB built+ # table-by-table). ``initialize_db`` is idempotent.+ ReviewStore.initialize_db(_REVIEW_DB_PATH)+ _delete_all_rows(+ _REVIEW_DB_PATH,+ ("review_annotations", "review_items"),+ )+ try:+ ReviewStore.sync_builtin_registrations(_REVIEW_DB_PATH)+ except Exception:+ logger.exception("reset: sync_builtin_registrations failed")+ # External (OER) sources too, or they carry no review rows until+ # the next process restart re-syncs them in the lifespan. Same+ # selector as api/main.py: only sources ingested onto this disk.+ try:+ from openexecutive.knowledge.external_sources import load_manifest+ ingested = [+ {"id": src.id, "domains": src.domains}+ for src in load_manifest()+ if src.cache_dir.exists() and any(src.cache_dir.iterdir())+ ]+ if ingested:+ ReviewStore.sync_external_registrations(ingested, _REVIEW_DB_PATH)+ except Exception:+ logger.exception("reset: sync_external_registrations 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/clients/slots.py b/packages/core/openexecutive/clients/slots.pyindex b8a92418..46d90781 100644--- a/packages/core/openexecutive/clients/slots.py+++ b/packages/core/openexecutive/clients/slots.py@@ -565,6 +565,28 @@ def _ensure_schemas() -> None:init_departments(db_path)init_monitoring(db_path)ReviewStore.initialize_db(db_path)+ # Register shipped knowledge as trusted defaults too — without this a+ # freshly activated slot has an empty review_items table until the next+ # process restart, so its knowledge page and review stats read as empty.+ ReviewStore.sync_builtin_registrations(db_path)+ # External sources as well, mirroring the lifespan. A slot captured from a+ # pre-existing database carries `external:*` rows; the backfill below only+ # promotes rows a sync has flagged as shipped, so skipping this would leave+ # them `pending` — and pending is now withheld from retrieval.+ try:+ from openexecutive.knowledge.external_sources import load_manifest++ ingested = [+ {"id": src.id, "domains": src.domains}+ for src in load_manifest()+ if src.cache_dir.exists() and any(src.cache_dir.iterdir())+ ]+ if ingested:+ ReviewStore.sync_external_registrations(ingested, db_path)+ except Exception:+ logger.exception("slot schema init: sync_external_registrations failed")+ # Must follow both syncs: it only promotes rows they have flagged.+ ReviewStore.backfill_trusted_defaults(db_path)def _reseed_blank_defaults(*, seed_departments: bool = True) -> None:diff --git a/packages/core/openexecutive/knowledge/retriever.py b/packages/core/openexecutive/knowledge/retriever.pyindex 99493152..fd8f0ce9 100644--- a/packages/core/openexecutive/knowledge/retriever.py+++ b/packages/core/openexecutive/knowledge/retriever.py@@ -210,8 +210,11 @@ def retrieve(store = ChromaDBStore(persist_directory=settings.vector_store_path)rs = review_store or _default_review_store()- rejected_builtin = rs.get_rejected_filenames(ContentType.BUILTIN)- rejected_external = rs.get_rejected_source_ids()+ # 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_external = rs.get_withheld_source_ids()priority_map = rs.get_priority_map(ContentType.BUILTIN)# Over-fetch slightly so post-query text dedup (multi-domain chunks share@@ -229,13 +232,13 @@ def retrieve())- # Filter out rejected files and rejected OER sources, drop weak+ # Filter out withheld files and withheld OER sources, drop weak# matches, then sort by SME priority.filtered_builtin = [rfor r in raw_builtin- if r["metadata"].get("filename") not in rejected_builtin- and r["metadata"].get("source_id") not in rejected_external+ if r["metadata"].get("filename") not in withheld_builtin+ and r["metadata"].get("source_id") not in withheld_externaland _passes_threshold(r, distance_threshold)]filtered_builtin.sort(@@ -363,12 +366,18 @@ def retrieve_failures(specialist_name: str | None = None,n_results: int = 2,store: ChromaDBStore | None = None,+ review_store: ReviewStore | None = None,) -> str:"""Query the failure_cases collection and return formatted context.Returns an empty string if no result clears the distance threshold —tangential failure stories are noise, so we prefer surfacing nothingover surfacing a poor match.++ Failure case studies are registered for review like any other built-in+ doc, so the same withheld filter applies here. Without it, rejecting a+ failure case study did nothing at all — these live in their own Chroma+ collection, which this path used to query without consulting review state."""from openexecutive.config import get_settings@@ -390,7 +399,16 @@ def retrieve_failures(# Cosine distance threshold (configurable via KNOWLEDGE_DISTANCE_THRESHOLD):# a larger distance means the match is too weak to be useful.threshold = settings.knowledge_distance_threshold- filtered = _dedupe_by_text([r for r in raw if r["distance"] <= threshold])+ rs = review_store or _default_review_store()+ withheld = rs.get_withheld_filenames(ContentType.BUILTIN)+ filtered = _dedupe_by_text(+ [+ r+ for r in raw+ if r["metadata"].get("filename") not in withheld+ and r["distance"] <= threshold+ ]+ )results = filtered[:n_results]# Audit emit (failure cases collection). Fire even when empty so thediff --git a/packages/core/openexecutive/knowledge/review_store.py b/packages/core/openexecutive/knowledge/review_store.pyindex e738a3a2..42000a58 100644--- a/packages/core/openexecutive/knowledge/review_store.py+++ b/packages/core/openexecutive/knowledge/review_store.py@@ -3,11 +3,11 @@ from __future__ import annotationsimport osimport sqlite3import uuid-from collections.abc import Generator+from collections.abc import Generator, Iterablefrom contextlib import contextmanagerfrom datetime import UTC, datetimefrom enum import StrEnum-from pathlib import Path+from pathlib import Path, PurePosixPathfrom typing import Anyfrom pydantic import BaseModel, ConfigDict@@ -16,6 +16,11 @@ DB_PATH = Path(os.environ.get("EPISODIC_DB_PATH", "./episodic_memory.db"))PRIORITY_ORDER: dict[str, int] = {"high": 0, "normal": 1, "low": 2}+# Bound an explicit bulk id list well under SQLite's variable limit. Public+# because the API layer validates against the same number — a private copy+# there would silently drift from the limit the store enforces.+BULK_MAX_IDS = 500+class ReviewStatus(StrEnum):PENDING = "pending"@@ -44,6 +49,11 @@ class ReviewItem(BaseModel):filename: strstatus: ReviewStatus = ReviewStatus.PENDINGpriority: Priority = Priority.NORMAL+ # True only for content that SHIPS with the product. Provenance cannot be+ # inferred from status/reviewed_at: a brand-new user upload is also+ # (pending, reviewed_at NULL), so curation keyed on that would silently+ # approve someone's document.+ trusted_default: bool = Falsereviewer_notes: str = ""reviewed_at: str | None = Noneregistered_at: str@@ -81,6 +91,7 @@ def _row_to_item(row: sqlite3.Row) -> ReviewItem:filename=row["filename"],status=ReviewStatus(row["status"]),priority=Priority(row["priority"]),+ trusted_default=bool(row["trusted_default"]),reviewer_notes=row["reviewer_notes"] or "",reviewed_at=row["reviewed_at"],registered_at=row["registered_at"],@@ -99,6 +110,103 @@ def _row_to_annotation(row: sqlite3.Row) -> Annotation:)+def _insert_trusted_defaults(+ conn: sqlite3.Connection,+ rows: Iterable[tuple[ContentType, str, str]],+) -> int:+ """INSERT OR IGNORE a batch of (content_type, domain, filename) as trusted defaults.++ Shared by both registration syncs so the "what does shipped content look+ like on arrival" decision lives in exactly one place. `INSERT OR IGNORE`+ means an existing SME decision is never overwritten. Returns new rows.+ """+ now = datetime.now(UTC).isoformat()+ new_count = 0+ for content_type, domain, filename in rows:+ item_id = (+ f"builtin:{domain}:{filename}"+ if content_type is ContentType.BUILTIN+ else f"external:{filename}"+ )+ result = conn.execute(+ "INSERT OR IGNORE INTO review_items "+ "(item_id, content_type, domain, filename, status, trusted_default, "+ " registered_at, last_modified_at) "+ "VALUES (?, ?, ?, ?, ?, 1, ?, ?)",+ (+ item_id,+ content_type.value,+ domain,+ filename,+ ReviewStatus.APPROVED.value,+ now,+ now,+ ),+ )+ new_count += result.rowcount+ if result.rowcount == 0:+ # The row already existed, so the INSERT was ignored and its+ # provenance may predate the column. Flag it — status is untouched,+ # so an SME decision on a shipped doc survives.+ conn.execute(+ "UPDATE review_items SET trusted_default = 1 "+ "WHERE item_id = ? AND trusted_default = 0",+ (item_id,),+ )+ return new_count+++_TRUSTED_DEFAULTS_BACKFILL_KEY = "trusted_defaults_backfill_v1"+++def _backfill_trusted_defaults(conn: sqlite3.Connection) -> int:+ """One-shot: promote never-touched shipped rows to trusted defaults.++ Shipped content used to register as `pending`, so every pre-existing+ install carries a queue of docs nobody asked for. It now registers+ `approved` with a NULL `reviewed_at`; this brings older databases in line.++ Scoped to `trusted_default = 1`, which is why this runs AFTER the+ registration syncs have flagged provenance — a user's own upload awaiting+ its first review is also (pending, reviewed_at NULL) and must not be+ approved on their behalf.++ The guiding rule is **no shipped doc loses retrievability on upgrade**.+ Before this change `pending` was still retrieved, so every shipped doc was+ reachable; now `pending` is withheld, and any shipped row left behind here+ would silently vanish from the Executive's context. That is why notes and+ annotations do NOT hold a row back: they are supplementary, not decisions.+ An annotated doc is the worst case — `retrieve_context` injects annotations+ by DOMAIN regardless of item status, so withholding the doc would feed the+ Executive a correction to a document it can no longer see.++ `reviewed_at IS NULL` is the real exclusion, and it is enough: `set_status`+ always stamps it, so every explicit approve or reject is skipped, and a+ rejected row is not `pending` anyway.++ Guarded by a marker row so it runs exactly once: re-running would undo a+ later curation request. `BEGIN IMMEDIATE` + `INSERT OR IGNORE` make the+ check-then-write safe against two processes booting at the same time+ (two uvicorn workers, or the API racing a CLI command).+ """+ conn.execute("BEGIN IMMEDIATE")+ already = conn.execute(+ "SELECT 1 FROM review_meta WHERE key = ?", (_TRUSTED_DEFAULTS_BACKFILL_KEY,)+ ).fetchone()+ if already is not None:+ return 0++ result = conn.execute(+ "UPDATE review_items SET status = 'approved' "+ "WHERE trusted_default = 1 AND status = 'pending' AND reviewed_at IS NULL"+ )+ conn.execute(+ "INSERT OR IGNORE INTO review_meta (key, value) VALUES (?, ?)",+ (_TRUSTED_DEFAULTS_BACKFILL_KEY, datetime.now(UTC).isoformat()),+ )+ return result.rowcount++class ReviewStore:def __init__(self, db_path: Path = DB_PATH) -> None:self._db_path = db_path@@ -116,6 +224,7 @@ class ReviewStore:priority TEXT NOT NULL DEFAULT 'normal',reviewer_notes TEXT DEFAULT '',reviewed_at TEXT,+ trusted_default INTEGER NOT NULL DEFAULT 0,registered_at TEXT NOT NULL,last_modified_at TEXT NOT NULL);@@ -135,54 +244,80 @@ class ReviewStore:);CREATE INDEX IF NOT EXISTS idx_annot_domainON review_annotations(domain, is_active);++ CREATE TABLE IF NOT EXISTS review_meta (+ key TEXT PRIMARY KEY,+ value TEXT NOT NULL+ );""")+ # Additive column for databases created before provenance was+ # tracked. Existing rows default to 0 (not shipped); the+ # registration syncs re-flag the shipped ones on the next boot.+ cols = {r["name"] for r in conn.execute("PRAGMA table_info(review_items)")}+ if "trusted_default" not in cols:+ conn.execute(+ "ALTER TABLE review_items "+ "ADD COLUMN trusted_default INTEGER NOT NULL DEFAULT 0"+ )@staticmethod- def sync_builtin_registrations(db_path: Path = DB_PATH) -> int:- """INSERT OR IGNORE for every .md file in knowledge/builtin/ (excluding skills/).+ def backfill_trusted_defaults(db_path: Path = DB_PATH) -> int:+ """Run the one-shot legacy migration. Call AFTER the registration syncs.- Idempotent — safe to call on every startup. Returns number of new registrations.+ Ordering matters: the migration only touches rows the syncs have+ flagged `trusted_default = 1`, so running it first would promote+ nothing (or, before provenance existed, would have promoted user+ uploads awaiting their first review)."""- from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH+ with _get_conn(db_path) as conn:+ return _backfill_trusted_defaults(conn)- now = datetime.now(UTC).isoformat()- new_count = 0+ @staticmethod+ def sync_builtin_registrations(db_path: Path = DB_PATH) -> int:+ """Register the built-in knowledge docs that ship with the product.++ Registers as a **trusted default**: `approved` with a NULL `reviewed_at`.+ This content ships with the product and is curated upstream, so a new+ instance starts with an empty review queue rather than ~81 items nobody+ asked to adjudicate. `reviewed_at` stays NULL to keep "shipped default"+ distinguishable from "an SME actually signed off on this".++ Idempotent — safe to call on every startup. Returns new registrations.+ """+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES++ # Driven by the committed manifest, never by scanning the directory.+ # `POST /knowledge/builtin` writes a USER's document into this same+ # tree, so "a .md file exists here" does not mean "this ships with the+ # product" — scanning marked those uploads trusted and auto-approved+ # them into retrieval. Skills are absent from the manifest by+ # construction (they have separate management).+ rows = [+ (ContentType.BUILTIN, PurePosixPath(rel).parent.name, PurePosixPath(rel).name)+ for rel in sorted(SHIPPED_BUILTIN_FILES)+ ]with _get_conn(db_path) as conn:- for md_file in sorted(BUILTIN_KNOWLEDGE_PATH.rglob("*.md")):- # Skip skills — they have separate management- if "skills" in md_file.parts:- continue- domain = md_file.parent.name- filename = md_file.name- item_id = f"builtin:{domain}:{filename}"- result = conn.execute(- "INSERT OR IGNORE INTO review_items "- "(item_id, content_type, domain, filename, registered_at, last_modified_at) "- "VALUES (?, ?, ?, ?, ?, ?)",- (item_id, ContentType.BUILTIN.value, domain, filename, now, now),- )- new_count += result.rowcount- return new_count+ return _insert_trusted_defaults(conn, rows)@staticmethoddef sync_external_registrations(ingested_source_ids: list[dict[str, Any]], db_path: Path = DB_PATH) -> int:- """INSERT OR IGNORE for all ingested OER sources. Returns new registration count."""- now = datetime.now(UTC).isoformat()- new_count = 0+ """Register all ingested OER sources. Returns new registration count.++ Trusted defaults for the same reason as `sync_builtin_registrations`:+ these sources come from the shipped manifest, not from the user.+ """+ rows = [+ (+ ContentType.EXTERNAL,+ src["domains"][0] if src.get("domains") else "general",+ src["id"],+ )+ for src in ingested_source_ids+ ]with _get_conn(db_path) as conn:- for src in ingested_source_ids:- item_id = f"external:{src['id']}"- domain = src["domains"][0] if src.get("domains") else "general"- result = conn.execute(- "INSERT OR IGNORE INTO review_items "- "(item_id, content_type, domain, filename, registered_at, last_modified_at) "- "VALUES (?, ?, ?, ?, ?, ?)",- (item_id, ContentType.EXTERNAL.value, domain, src["id"], now, now),- )- new_count += result.rowcount- return new_count+ return _insert_trusted_defaults(conn, rows)def register(self,@@ -274,33 +409,129 @@ class ReviewStore:raise KeyError(f"Review item not found: {item_id}")return _row_to_item(row)- def bulk_approve(self, domain: str | None = None) -> int:+ def bulk_approve(+ self,+ domain: str | None = None,+ item_ids: list[str] | None = None,+ ) -> list[str]:+ """Approve many pending items at once. Returns the item_ids updated.++ Selects by ``domain`` and/or an explicit ``item_ids`` list (capped at+ ``BULK_MAX_IDS``). With neither selector, every pending item is+ approved — the long-standing "Approve all pending" behavior.+ """now = datetime.now(UTC).isoformat()- with _get_conn(self._db_path) as conn:- if domain:- result = conn.execute(- "UPDATE review_items SET status = 'approved', reviewed_at = ?, "- "last_modified_at = ? WHERE status = 'pending' AND domain = ?",- (now, now, domain),- )- else:- result = conn.execute(- "UPDATE review_items SET status = 'approved', reviewed_at = ?, "- "last_modified_at = ? WHERE status = 'pending'",- (now, now),+ clauses = ["status = 'pending'"]+ params: list[Any] = []+ if domain:+ clauses.append("domain = ?")+ params.append(domain)+ if item_ids is not None:+ if not item_ids:+ return []+ if len(item_ids) > BULK_MAX_IDS:+ raise ValueError(+ f"item_ids exceeds BULK_MAX_IDS ({len(item_ids)} > {BULK_MAX_IDS}); "+ "silently dropping the tail would under-approve without telling "+ "the caller")+ clauses.append(f"item_id IN ({','.join('?' * len(item_ids))})")+ params.extend(item_ids)+ where = " AND ".join(clauses)+ with _get_conn(self._db_path) as conn:+ conn.execute("BEGIN IMMEDIATE") # select + update under one write lock+ rows = conn.execute(+ f"SELECT item_id FROM review_items WHERE {where}", params+ ).fetchall()+ ids = [r["item_id"] for r in rows]+ if not ids:+ return []+ conn.execute(+ "UPDATE review_items SET status = 'approved', reviewed_at = ?, "+ f"last_modified_at = ? WHERE item_id IN ({','.join('?' * len(ids))})",+ (now, now, *ids),+ )+ return ids++ def _move_untouched(self, domain: str, *, from_status: str, to_status: str) -> int:+ """Flip status for a domain's never-reviewed items only.++ Two guards, both required. `trusted_default = 1` restricts this to+ content that SHIPS with the product — without it a user's own upload,+ which is also (pending, reviewed_at NULL), would be approved by a+ "stop curating" click it had nothing to do with. `reviewed_at IS NULL`+ then spares any shipped doc an SME has explicitly decided on.++ `reviewed_at` is left alone: moving an item between the queue and+ trusted-default is not itself a review decision.+ """+ now = datetime.now(UTC).isoformat()+ with _get_conn(self._db_path) as conn:+ result = conn.execute(+ "UPDATE review_items SET status = ?, last_modified_at = ? "+ "WHERE trusted_default = 1 AND status = ? AND reviewed_at IS NULL "+ " AND domain = ?",+ (to_status, now, from_status, domain),+ )return result.rowcount- def get_rejected_filenames(self, content_type: ContentType) -> set[str]:+ def queue_for_curation(self, domain: str) -> int:+ """Move one domain's trusted defaults into the review queue.++ Queued items are `pending`, and pending is withheld from retrieval, so+ this deliberately takes that domain's knowledge away from the Executive+ until the user works through it. Returns the number of items queued.+ """+ return self._move_untouched(+ domain,+ from_status=ReviewStatus.APPROVED.value,+ to_status=ReviewStatus.PENDING.value,+ )++ def stop_curation(self, domain: str) -> int:+ """Undo `queue_for_curation` — restore a domain's untouched defaults."""+ return self._move_untouched(+ domain,+ from_status=ReviewStatus.PENDING.value,+ to_status=ReviewStatus.APPROVED.value,+ )++ def count_trusted_defaults_by_domain(self) -> dict[str, int]:+ """Map domain → number of never-reviewed trusted defaults.++ Drives the "Curate N" affordance so the UI can state up front how much+ content a curation request would withhold.+ """+ with _get_conn(self._db_path) as conn:+ rows = conn.execute(+ "SELECT domain, COUNT(*) AS n FROM review_items "+ "WHERE trusted_default = 1 AND status = 'approved' "+ " AND reviewed_at IS NULL GROUP BY domain"+ ).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.++ `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.++ `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 WHERE content_type = ? AND status = 'rejected'",+ "SELECT filename FROM review_items "+ "WHERE content_type = ? AND status IN ('pending', 'rejected')",(content_type.value,),).fetchall()return {row["filename"] for row in rows}- def get_rejected_source_ids(self) -> set[str]:- return self.get_rejected_filenames(ContentType.EXTERNAL)+ def get_withheld_source_ids(self) -> set[str]:+ return self.get_withheld_filenames(ContentType.EXTERNAL)def get_priority_map(self, content_type: ContentType) -> dict[str, str]:"""Map filename → priority for approved items of a given content type."""diff --git a/packages/core/openexecutive/knowledge/shipped_manifest.py b/packages/core/openexecutive/knowledge/shipped_manifest.pynew file mode 100644index 00000000..684a90a2--- /dev/null+++ b/packages/core/openexecutive/knowledge/shipped_manifest.py@@ -0,0 +1,113 @@+"""The built-in knowledge files that SHIP with Open Executive.++This list is the *only* source of truth for content provenance. It cannot be+derived from the filesystem at runtime: `POST /knowledge/builtin` writes a+user's own document into the very same `knowledge/builtin/<domain>/` tree+(`api/routes/knowledge._resolve_path`), so "there is a .md file at this path"+is equally true of shipped content and of a confidential draft someone just+uploaded. Re-deriving provenance from the tree marked those uploads as shipped+and auto-approved them into retrieval.++`ReviewStore.sync_builtin_registrations` registers exactly these paths as+trusted defaults. Anything else in the tree belongs to the user and reaches+`review_items` through `ReviewStore.register()`, which never sets+`trusted_default`.++Regenerate after adding or removing a built-in knowledge doc:++ git ls-files 'packages/core/openexecutive/knowledge/builtin/**/*.md' \+ | grep -v '/skills/' \+ | sed 's#packages/core/openexecutive/knowledge/builtin/##' | sort++`tests/unit/test_review_store.py::test_shipped_manifest_matches_git` fails if+this drifts from the tracked files.+"""++from __future__ import annotations++# Paths are POSIX-relative to `knowledge/builtin/`.+SHIPPED_BUILTIN_FILES: frozenset[str] = frozenset(+ (+ "board/audit_and_comp_committees.md",+ "board/board_communication.md",+ "board/board_composition_and_governance.md",+ "board/ceo_succession.md",+ "board/investor_relations.md",+ "board/special_situations.md",+ "failures/board/credit-suisse.md",+ "failures/board/theranos.md",+ "failures/finance/enron.md",+ "failures/finance/silicon-valley-bank.md",+ "failures/finance/wework-ipo.md",+ "failures/hr/twitter-x-acquisition.md",+ "failures/hr/uber-culture.md",+ "failures/hr/yahoo-talent-exodus.md",+ "failures/legal/ftx-collapse.md",+ "failures/marketing/new-coke.md",+ "failures/operations/boeing-737-max.md",+ "failures/operations/spirit-airlines.md",+ "failures/product/quibi.md",+ "failures/strategy/aol-time-warner.md",+ "failures/strategy/google-glass.md",+ "failures/strategy/kodak-digital.md",+ "failures/strategy/peloton.md",+ "finance/accounting_basics.md",+ "finance/capital_allocation.md",+ "finance/financial_modeling.md",+ "finance/financial_statements.md",+ "finance/fundraising.md",+ "finance/ipo_and_late_stage_readiness.md",+ "finance/saas_metrics.md",+ "finance/unit_economics.md",+ "finance/valuation_methods.md",+ "hr/compensation_design.md",+ "hr/culture_and_values.md",+ "hr/hiring_frameworks.md",+ "hr/layoffs_and_rifs.md",+ "hr/manager_effectiveness.md",+ "hr/org_design.md",+ "hr/performance_management.md",+ "hr/talent_development.md",+ "legal/ai_and_data_law.md",+ "legal/commercial_contracts.md",+ "legal/data_privacy_and_security.md",+ "legal/employment_law_for_managers.md",+ "legal/ip_strategy.md",+ "legal/ma_legal_essentials.md",+ "legal/securities_and_cap_table.md",+ "legal/startup_legal_basics.md",+ "marketing/brand_strategy.md",+ "marketing/content_marketing.md",+ "marketing/customer_marketing.md",+ "marketing/demand_generation.md",+ "marketing/go_to_market.md",+ "marketing/positioning_and_messaging.md",+ "marketing/pricing_and_packaging.md",+ "operations/ai_and_automation.md",+ "operations/business_continuity.md",+ "operations/customer_support_operations.md",+ "operations/procurement_and_vendor_management.md",+ "operations/project_management.md",+ "operations/quality_and_process.md",+ "operations/scaling_operations.md",+ "operations/security_operations.md",+ "product/experimentation.md",+ "product/launch_playbooks.md",+ "product/prioritization_frameworks.md",+ "product/product_analytics.md",+ "product/product_discovery.md",+ "product/product_led_growth.md",+ "product/product_market_fit.md",+ "product/product_strategy.md",+ "product/roadmapping.md",+ "strategy/business_model_frameworks.md",+ "strategy/competitive_analysis.md",+ "strategy/corporate_strategy.md",+ "strategy/growth_strategy.md",+ "strategy/mergers_acquisitions.md",+ "strategy/okr_frameworks.md",+ "strategy/partnerships_and_alliances.md",+ "strategy/scenario_planning.md",+ "strategy/startup_lifecycle.md",+ )+)diff --git a/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py b/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.pyindex aecbe77f..d5f28e08 100644--- a/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py+++ b/packages/core/tests/unit/test_fixture_loader_reset_rebootstrap.py@@ -42,11 +42,16 @@ def settings_stub(tmp_path: Path) -> Any:def _isolate_dbs(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:"""Point every DB the reset touches at tmp_path and initialize schemas."""from openexecutive.departments import store as dept_store+ from openexecutive.knowledge import review_store as rs_modfrom openexecutive.memory import episodicfrom openexecutive.people import store as people_storeepisodic_path = tmp_path / "episodic.db"monkeypatch.setattr(episodic, "DB_PATH", episodic_path)+ # The reset wipes and re-registers knowledge review state. Its module+ # DB_PATH default is bound at import, so without this every test in this+ # file writes review rows into the real ./episodic_memory.db.+ monkeypatch.setattr(rs_mod, "DB_PATH", episodic_path)monkeypatch.setattr(people_store, "DB_PATH", tmp_path / "people.db")monkeypatch.setattr(dept_store, "DB_PATH", tmp_path / "depts.db")# ``initialize_db``'s ``db_path`` default is bound at def time, so a@@ -163,3 +168,53 @@ def test_reset_bootstraps_are_idempotent_on_second_call(assert cadence_rows, "expected at least one dept_cadence row after reset"for slug, count in cadence_rows:assert count == 1, f"dept_cadence for {slug} duplicated: {count} rows"+++def test_reset_clears_review_state_and_reregisters_defaults(+ settings_stub: Any, _isolate_dbs: Path+) -> None:+ """A factory reset must not inherit the previous operator's review decisions.++ A rejection suppresses retrieval, so a stale one would keep silently+ withholding knowledge on the reset box. After the wipe the shipped docs are+ re-registered as trusted defaults rather than left as an empty table.+ """+ from openexecutive.knowledge import review_store as rs_mod+ from openexecutive.knowledge.review_store import ReviewStatus, ReviewStore++ ReviewStore.initialize_db(_isolate_dbs)+ store = ReviewStore(db_path=_isolate_dbs)+ ReviewStore.sync_builtin_registrations(_isolate_dbs)++ 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)++ 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 = store.count_by_status()+ 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.list_annotations(active_only=False) == []+++def test_reset_survives_a_db_without_review_tables(+ settings_stub: Any, _isolate_dbs: Path+) -> None:+ """The review schema is not guaranteed to exist on the reset path."""+ from openexecutive.knowledge import review_store as rs_mod++ with sqlite3.connect(_isolate_dbs) as conn:+ conn.execute("DROP TABLE IF EXISTS review_annotations")+ conn.execute("DROP TABLE IF EXISTS review_items")++ 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))++ assert rs_mod.ReviewStore(db_path=_isolate_dbs).count_by_status()["total"] > 0diff --git a/packages/core/tests/unit/test_retriever_gating.py b/packages/core/tests/unit/test_retriever_gating.pyindex 2738c4c0..ff1ce92f 100644--- a/packages/core/tests/unit/test_retriever_gating.py+++ b/packages/core/tests/unit/test_retriever_gating.py@@ -13,12 +13,25 @@ from openexecutive.knowledge.retriever import ()[email protected](autouse=True)+def _isolate_audit(monkeypatch: pytest.MonkeyPatch) -> None:+ """Keep `_emit_retrieval_audit` out of the default ./episodic_memory.db.++ retrieve() and retrieve_failures() both emit an audit row. Unpatched they+ write to the module default, and the leaked rows only break *other*+ modules' assertions in a full-suite run.+ """+ import openexecutive.knowledge.retriever as retriever_mod++ monkeypatch.setattr(retriever_mod, "_audit_log", lambda *a, **k: None)++@pytest.fixturedef fake_review_store() -> SimpleNamespace:"""ReviewStore stub that returns empty sets — keep retrieval focused on the gate."""return SimpleNamespace(- get_rejected_filenames=lambda _ct: set(),- get_rejected_source_ids=lambda: set(),+ get_withheld_filenames=lambda _ct: set(),+ get_withheld_source_ids=lambda: set(),get_priority_map=lambda _ct: {},list_annotations=lambda domains=None, active_only=True: [],)@@ -154,3 +167,92 @@ def test_perfect_match_distance_zero_is_kept(out = retrieve(query="a real question about strategy", store=store, review_store=fake_review_store)assert "perfect" in outassert "also perfect" in out+++# ---------------------------------------------------------------------------+# The pending gate: withheld items never reach a specialist+# ---------------------------------------------------------------------------+++def _hit(filename: str, text: str, *, distance: float = 0.1) -> dict[str, Any]:+ return {+ "text": text,+ "distance": distance,+ "metadata": {"filename": filename, "domain": "finance", "type": "builtin"},+ }+++def _review_store(withheld: set[str]) -> SimpleNamespace:+ return SimpleNamespace(+ get_withheld_filenames=lambda _ct: withheld,+ get_withheld_source_ids=lambda: set(),+ get_priority_map=lambda _ct: {},+ list_annotations=lambda domains=None, active_only=True: [],+ )+++def test_withheld_builtin_chunk_is_not_retrieved() -> None:+ """A doc queued for curation must not reach the Executive."""+ store = _make_store(+ [_hit("queued.md", "WITHHELD CONTENT"), _hit("trusted.md", "TRUSTED CONTENT")],+ [],+ )+ out = retrieve(+ query="a real question about capital structure",+ store=store,+ review_store=_review_store({"queued.md"}),+ )+ assert "TRUSTED CONTENT" in out+ assert "WITHHELD CONTENT" not in out+++def test_nothing_withheld_returns_everything() -> None:+ store = _make_store([_hit("a.md", "ALPHA"), _hit("b.md", "BETA")], [])+ out = retrieve(+ query="a real question about capital structure",+ store=store,+ review_store=_review_store(set()),+ )+ assert "ALPHA" in out+ assert "BETA" in out+++def test_withheld_external_source_is_not_retrieved() -> None:+ hit = _hit("oer.md", "EXTERNAL CONTENT")+ hit["metadata"]["source_id"] = "openstax-finance"+ store = _make_store([hit, _hit("trusted.md", "TRUSTED CONTENT")], [])+ rs = _review_store(set())+ rs.get_withheld_source_ids = lambda: {"openstax-finance"}++ out = retrieve(query="a real question about capital structure", store=store, review_store=rs)++ assert "TRUSTED CONTENT" in out+ assert "EXTERNAL CONTENT" not in out+++def test_retrieve_failures_honors_withheld_items() -> None:+ """Failure case studies live in their own collection and used to ignore+ review state entirely — rejecting one did nothing."""+ from openexecutive.knowledge.retriever import retrieve_failures+ from openexecutive.knowledge.store import ChromaDBStore++ store = MagicMock()++ def fake_query(*, query_text: str, collection: str, domain_filter: Any, n_results: int):+ if collection == ChromaDBStore.FAILURES_COLLECTION:+ return [+ _hit("bad_case.md", "REJECTED FAILURE STORY"),+ _hit("good_case.md", "USEFUL FAILURE STORY"),+ ]+ return []++ store.query.side_effect = fake_query++ out = retrieve_failures(+ query="what went wrong with this rollout",+ store=store,+ review_store=_review_store({"bad_case.md"}),+ )++ assert "USEFUL FAILURE STORY" in out+ assert "REJECTED FAILURE STORY" not in outdiff --git a/packages/core/tests/unit/test_review_routes.py b/packages/core/tests/unit/test_review_routes.pynew file mode 100644index 00000000..ff616944--- /dev/null+++ b/packages/core/tests/unit/test_review_routes.py@@ -0,0 +1,211 @@+"""Unit tests for the /review API surface: curation and bulk approve."""+from __future__ import annotations++import os+from pathlib import Path++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.api.routes import review as review_routes # noqa: E402+from openexecutive.knowledge.review_store import ( # noqa: E402+ ContentType,+ ReviewStatus,+ ReviewStore,+)++[email protected](autouse=True)+def _isolate_audit(monkeypatch: pytest.MonkeyPatch) -> None:+ """Keep audit writes out of the default ./episodic_memory.db.++ `audit.log_event` writes to the module default unless patched, and the+ leaked rows only break *other* modules' assertions in a full-suite run.+ """+ import openexecutive.audit as audit++ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)+++def store(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> ReviewStore:+ db = tmp_path / "review.db"+ ReviewStore.initialize_db(db)+ monkeypatch.setattr(review_routes, "_store", lambda: ReviewStore(db_path=db))+ return ReviewStore(db_path=db)+++def client() -> TestClient:+ return TestClient(create_app())+++def _default(store: ReviewStore, filename: str, domain: str = "finance") -> str:+ """Register an item in its shipped state: approved, trusted, never reviewed."""+ import sqlite3++ item_id = f"builtin:{domain}:{filename}"+ store.register(+ item_id=item_id,+ content_type=ContentType.BUILTIN,+ domain=domain,+ filename=filename,+ )+ with sqlite3.connect(store._db_path) as conn:+ conn.execute(+ "UPDATE review_items SET status = 'approved', trusted_default = 1 "+ "WHERE item_id = ?",+ (item_id,),+ )+ return item_id+++# ---------------------------------------------------------------------------+# POST /review/curate+# ---------------------------------------------------------------------------+++def test_curate_start_queues_a_domain(client: TestClient, store: ReviewStore) -> None:+ _default(store, "a.md")+ _default(store, "b.md")+ _default(store, "hr.md", domain="hr")++ res = client.post("/review/curate", json={"domain": "finance", "action": "start"})++ 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"}+++def test_curate_stop_restores_a_domain(client: TestClient, store: ReviewStore) -> None:+ _default(store, "a.md")+ client.post("/review/curate", json={"domain": "finance", "action": "start"})++ res = client.post("/review/curate", json={"domain": "finance", "action": "stop"})++ assert res.status_code == 200+ assert res.json()["affected_count"] == 1+ assert store.get_withheld_filenames(ContentType.BUILTIN) == set()+++def test_curate_requires_a_domain(client: TestClient, store: ReviewStore) -> None:+ """No 'curate everything' selector — one click must not dark the whole KB."""+ assert client.post("/review/curate", json={"action": "start"}).status_code == 422+ assert (+ client.post("/review/curate", json={"domain": "", "action": "start"}).status_code+ == 422+ )+++def test_curate_rejects_an_unknown_action(client: TestClient, store: ReviewStore) -> None:+ res = client.post("/review/curate", json={"domain": "finance", "action": "nuke"})+ assert res.status_code == 422+++def test_curate_unknown_domain_is_a_noop(client: TestClient, store: ReviewStore) -> None:+ _default(store, "a.md")+ res = client.post("/review/curate", json={"domain": "nope", "action": "start"})+ assert res.status_code == 200+ assert res.json()["affected_count"] == 0+++# ---------------------------------------------------------------------------+# GET /review/trusted-defaults+# ---------------------------------------------------------------------------+++def test_trusted_defaults_counts_by_domain(client: TestClient, store: ReviewStore) -> None:+ _default(store, "a.md")+ _default(store, "b.md")+ _default(store, "h.md", domain="hr")++ res = client.get("/review/trusted-defaults")++ assert res.status_code == 200+ assert res.json() == {"finance": 2, "hr": 1}+++def test_trusted_defaults_excludes_reviewed_items(+ client: TestClient, store: ReviewStore+) -> None:+ signed_off = _default(store, "a.md")+ store.set_status(signed_off, ReviewStatus.APPROVED, "our CFO checked this")++ assert client.get("/review/trusted-defaults").json() == {}+++# ---------------------------------------------------------------------------+# POST /review/bulk-approve+# ---------------------------------------------------------------------------+++def test_bulk_approve_requires_a_selector(client: TestClient, store: ReviewStore) -> None:+ _default(store, "a.md")+ client.post("/review/curate", json={"domain": "finance", "action": "start"})++ res = client.post("/review/bulk-approve", json={})++ assert res.status_code == 400+ assert store.count_by_status()["pending"] == 1 # nothing was touched+++def test_bulk_approve_all_pending_needs_the_explicit_flag(+ client: TestClient, store: ReviewStore+) -> None:+ _default(store, "a.md")+ client.post("/review/curate", json={"domain": "finance", "action": "start"})++ res = client.post("/review/bulk-approve", json={"all_pending": True})++ assert res.status_code == 200+ assert res.json()["approved_count"] == 1+ assert store.count_by_status()["pending"] == 0+++def test_bulk_approve_by_item_ids(client: TestClient, store: ReviewStore) -> None:+ a = _default(store, "a.md")+ _default(store, "b.md")+ client.post("/review/curate", json={"domain": "finance", "action": "start"})++ res = client.post("/review/bulk-approve", json={"item_ids": [a]})++ assert res.status_code == 200+ assert res.json()["item_ids"] == [a]+ assert store.get_item("builtin:finance:b.md").status == ReviewStatus.PENDING # type: ignore[union-attr]+++def test_bulk_approve_caps_the_id_list(client: TestClient, store: ReviewStore) -> None:+ res = client.post(+ "/review/bulk-approve", json={"item_ids": [f"builtin:x:{i}.md" for i in range(501)]}+ )+ assert res.status_code == 422+++def test_bulk_approve_rejects_an_empty_domain(client: TestClient, store: ReviewStore) -> None:+ """An empty domain must not masquerade as a scoped selector.++ The store treats a falsy domain as "no filter", so `{"domain": ""}` used to+ pass the selector guard and then widen to every pending item in every+ domain — while the audit trail recorded a scoped approve.+ """+ _default(store, "a.md", domain="finance")+ _default(store, "b.md", domain="hr")+ client.post("/review/curate", json={"domain": "finance", "action": "start"})+ client.post("/review/curate", json={"domain": "hr", "action": "start"})+ assert store.count_by_status()["pending"] == 2++ for bad in ("", " "):+ res = client.post("/review/bulk-approve", json={"domain": bad})+ assert res.status_code == 422, f"domain={bad!r} should be rejected"++ assert store.count_by_status()["pending"] == 2 # nothing was approved+++def test_curate_rejects_an_absurdly_long_domain(client: TestClient, store: ReviewStore) -> None:+ res = client.post("/review/curate", json={"domain": "x" * 5000, "action": "start"})+ assert res.status_code == 422diff --git a/packages/core/tests/unit/test_review_store.py b/packages/core/tests/unit/test_review_store.pyindex bee273f5..3c3c2d39 100644--- a/packages/core/tests/unit/test_review_store.py+++ b/packages/core/tests/unit/test_review_store.py@@ -1,6 +1,7 @@"""Unit tests for the SME knowledge review store."""from __future__ import annotations+import sqlite3from pathlib import Pathimport pytest@@ -98,30 +99,30 @@ def test_touch_modified_needs_revision_stays(store: ReviewStore) -> None:# ----------------------------------------------------------------------------# get_rejected_filenames+# get_withheld_filenames# ----------------------------------------------------------------------------def test_get_rejected_filenames_returns_only_rejected(store: ReviewStore) -> None:+def test_get_withheld_filenames_covers_rejected_and_pending(store: ReviewStore) -> None:item_a = _register_builtin(store, filename="ratios.md")item_b = _register_builtin(store, filename="fundraising.md")- item_c = _register_builtin(store, filename="modeling.md")+ _register_builtin(store, filename="modeling.md") # left pendingstore.set_status(item_a.item_id, ReviewStatus.REJECTED)store.set_status(item_b.item_id, ReviewStatus.APPROVED)- rejected = store.get_rejected_filenames(ContentType.BUILTIN)- assert rejected == {"ratios.md"}- assert "fundraising.md" not in rejected- assert "modeling.md" not in rejected+ withheld = store.get_withheld_filenames(ContentType.BUILTIN)+ assert withheld == {"ratios.md", "modeling.md"}+ assert "fundraising.md" not in withheld-def test_get_rejected_filenames_empty_when_none_rejected(store: ReviewStore) -> None:- _register_builtin(store)- assert store.get_rejected_filenames(ContentType.BUILTIN) == set()+def test_get_withheld_filenames_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()-def test_get_rejected_source_ids(store: ReviewStore) -> None:+def test_get_withheld_source_ids(store: ReviewStore) -> None:store.register(item_id="external:openstax-finance",content_type=ContentType.EXTERNAL,@@ -129,7 +130,7 @@ def test_get_rejected_source_ids(store: ReviewStore) -> None:filename="openstax-finance",)store.set_status("external:openstax-finance", ReviewStatus.REJECTED)- assert "openstax-finance" in store.get_rejected_source_ids()+ assert "openstax-finance" in store.get_withheld_source_ids()# ---------------------------------------------------------------------------@@ -145,7 +146,7 @@ def test_set_priority(store: ReviewStore) -> None:def test_get_priority_map_only_approved(store: ReviewStore) -> None:item_a = _register_builtin(store, filename="a.md")- item_b = _register_builtin(store, filename="b.md")+ _register_builtin(store, filename="b.md")store.set_status(item_a.item_id, ReviewStatus.APPROVED)store.set_priority(item_a.item_id, Priority.HIGH)# item_b stays pending — should not appear in priority map@@ -163,8 +164,8 @@ def test_get_priority_map_only_approved(store: ReviewStore) -> None:def test_bulk_approve_all_pending(store: ReviewStore) -> None:for fn in ["a.md", "b.md", "c.md"]:_register_builtin(store, filename=fn)- count = store.bulk_approve()- assert count == 3+ ids = store.bulk_approve()+ assert len(ids) == 3for fn in ["a.md", "b.md", "c.md"]:item = store.get_item(f"builtin:finance:{fn}")assert item is not None@@ -179,8 +180,8 @@ def test_bulk_approve_domain_filter(store: ReviewStore) -> None:domain="hr",filename="b.md",)- count = store.bulk_approve(domain="finance")- assert count == 1+ ids = store.bulk_approve(domain="finance")+ assert ids == ["builtin:finance:a.md"]assert store.get_item("builtin:finance:a.md") is not Noneassert store.get_item("builtin:finance:a.md").status == ReviewStatus.APPROVED # type: ignore[union-attr]assert store.get_item("builtin:hr:b.md") is not None@@ -260,3 +261,493 @@ def test_count_by_status(store: ReviewStore) -> None:assert counts["pending"] == 1assert counts["approved"] == 1assert counts["total"] == 2+++# ---------------------------------------------------------------------------+# Trusted defaults: shipped content does not create a review backlog+# ---------------------------------------------------------------------------+++def test_sync_builtin_registers_trusted_defaults(tmp_path: Path) -> None:+ """A fresh instance must start with an empty review queue.++ Shipped knowledge registers `approved` with a NULL `reviewed_at` — usable+ immediately, but still distinguishable from an item an SME signed off on.+ """+ db = tmp_path / "fresh.db"+ ReviewStore.initialize_db(db)+ registered = ReviewStore.sync_builtin_registrations(db)+ store = ReviewStore(db_path=db)++ assert registered > 0+ counts = store.count_by_status()+ assert counts["pending"] == 0+ 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()+++def test_builtin_filenames_are_unique_across_domains() -> None:+ """The retrieval filter keys on bare filename, not item_id.++ Two domains shipping the same basename would make a withheld item in one+ domain silently suppress the other. Guard the invariant the filter relies on.+ """+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH++ names = [+ md.name+ for md in BUILTIN_KNOWLEDGE_PATH.rglob("*.md")+ if "skills" not in md.parts+ ]+ duplicates = {n for n in names if names.count(n) > 1}+ assert not duplicates, f"duplicate built-in basenames: {sorted(duplicates)}"+++def test_sync_builtin_does_not_overwrite_an_sme_decision(tmp_path: Path) -> None:+ db = tmp_path / "fresh.db"+ ReviewStore.initialize_db(db)+ ReviewStore.sync_builtin_registrations(db)+ store = ReviewStore(db_path=db)++ victim = store.list_items(limit=1)[0]+ store.set_status(victim.item_id, ReviewStatus.REJECTED, "not for us")++ ReviewStore.sync_builtin_registrations(db) # a later boot++ after = store.get_item(victim.item_id)+ assert after is not None+ assert after.status == ReviewStatus.REJECTED+++def test_sync_external_registers_trusted_defaults(tmp_path: Path) -> None:+ db = tmp_path / "fresh.db"+ ReviewStore.initialize_db(db)+ ReviewStore.sync_external_registrations(+ [{"id": "oer-finance-101", "domains": ["finance"]}], db+ )+ item = ReviewStore(db_path=db).get_item("external:oer-finance-101")+ assert item is not None+ assert item.status == ReviewStatus.APPROVED+ assert item.reviewed_at is None+++# ---------------------------------------------------------------------------+# Backfill: existing installs lose their phantom backlog, keep real decisions+# ---------------------------------------------------------------------------+++def _legacy_pending(store: ReviewStore, filename: str) -> str:+ """Register an item the way the pre-trusted-defaults code did."""+ item = _register_builtin(store, filename=filename)+ assert item.status == ReviewStatus.PENDING+ return item.item_id+++def _legacy_db(tmp_path: Path) -> Path:+ """A database created before trusted defaults existed.++ Old schema (no `review_meta`, so no backfill marker) plus the `pending`+ rows the old `sync_builtin_registrations` would have written. Calling+ `initialize_db` on this is exactly what an upgrade does.+ """+ db = tmp_path / "legacy.db"+ conn = sqlite3.connect(db)+ conn.executescript("""+ CREATE TABLE review_items (+ item_id TEXT PRIMARY KEY,+ content_type TEXT NOT NULL,+ domain TEXT NOT NULL,+ filename TEXT NOT NULL,+ status TEXT NOT NULL DEFAULT 'pending',+ priority TEXT NOT NULL DEFAULT 'normal',+ reviewer_notes TEXT DEFAULT '',+ reviewed_at TEXT,+ registered_at TEXT NOT NULL,+ last_modified_at TEXT NOT NULL+ );+ CREATE TABLE review_annotations (+ annotation_id TEXT PRIMARY KEY,+ item_id TEXT NOT NULL+ REFERENCES review_items(item_id) ON DELETE CASCADE,+ domain TEXT NOT NULL,+ correction TEXT NOT NULL,+ is_active INTEGER NOT NULL DEFAULT 1,+ created_at TEXT NOT NULL+ );+ """)+ conn.commit()+ conn.close()+ return db+++def _shipped_pairs(n: int) -> list[tuple[str, str]]:+ """The first n real (domain, filename) pairs the builtin syncs register."""+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH++ return [+ (md.parent.name, md.name)+ for md in sorted(BUILTIN_KNOWLEDGE_PATH.rglob("*.md"))+ if "skills" not in md.parts+ ][:n]+++def _seed_legacy_pending(db: Path, filename: str, domain: str = "finance") -> str:+ item_id = f"builtin:{domain}:{filename}"+ conn = sqlite3.connect(db)+ conn.execute(+ "INSERT INTO review_items (item_id, content_type, domain, filename, "+ "registered_at, last_modified_at) VALUES (?, 'builtin', ?, ?, ?, ?)",+ (item_id, domain, filename, "2025-01-01T00:00:00+00:00", "2025-01-01T00:00:00+00:00"),+ )+ conn.commit()+ conn.close()+ return item_id+++def _register_default(store: ReviewStore, filename: str, domain: str = "finance") -> str:+ """Register an item in its shipped state: approved, trusted, never reviewed."""+ item_id = f"builtin:{domain}:{filename}"+ store.register(+ item_id=item_id,+ content_type=ContentType.BUILTIN,+ domain=domain,+ filename=filename,+ )+ with sqlite3.connect(store._db_path) as conn:+ conn.execute(+ "UPDATE review_items SET status = 'approved', trusted_default = 1 "+ "WHERE item_id = ?",+ (item_id,),+ )+ return item_id+++def test_backfill_promotes_only_untouched_pending_rows(tmp_path: Path) -> None:+ db = _legacy_db(tmp_path)+ pairs = _shipped_pairs(3)+ untouched = _seed_legacy_pending(db, pairs[0][1], domain=pairs[0][0])+ decided = _seed_legacy_pending(db, pairs[1][1], domain=pairs[1][0])+ upload = _seed_legacy_pending(db, "my_own_upload.md", domain="finance")++ ReviewStore.initialize_db(db) # adds the provenance column+ store = ReviewStore(db_path=db)+ store.set_status(decided, ReviewStatus.REJECTED, "off base")++ ReviewStore.sync_builtin_registrations(db) # flags shipped provenance+ ReviewStore.backfill_trusted_defaults(db) # the upgrade++ assert store.get_item(untouched).status == ReviewStatus.APPROVED # type: ignore[union-attr]+ assert store.get_item(untouched).reviewed_at is None # type: ignore[union-attr]+ # An explicit decision survives...+ assert store.get_item(decided).status == ReviewStatus.REJECTED # type: ignore[union-attr]+ # ...and a user's own upload is never approved on their behalf.+ assert store.get_item(upload).status == ReviewStatus.PENDING # type: ignore[union-attr]+++def test_backfill_runs_once_and_does_not_undo_curation(tmp_path: Path) -> None:+ """Re-running init must not drag a deliberately curated domain back."""+ db = _legacy_db(tmp_path)+ domain, filename = _shipped_pairs(1)[0]+ item = _seed_legacy_pending(db, filename, domain=domain)++ ReviewStore.initialize_db(db)+ ReviewStore.sync_builtin_registrations(db)+ ReviewStore.backfill_trusted_defaults(db)+ store = ReviewStore(db_path=db)+ assert store.get_item(item).status == ReviewStatus.APPROVED # type: ignore[union-attr]++ assert store.queue_for_curation(domain) >= 1+ ReviewStore.backfill_trusted_defaults(db) # another boot++ assert store.get_item(item).status == ReviewStatus.PENDING # type: ignore[union-attr]+++# ---------------------------------------------------------------------------+# The pending gate+# ---------------------------------------------------------------------------+++def test_withheld_covers_pending_and_rejected_but_not_needs_revision(+ store: ReviewStore,+) -> None:+ pending = _legacy_pending(store, "pending.md")+ rejected = _legacy_pending(store, "rejected.md")+ revising = _legacy_pending(store, "revising.md")+ approved = _legacy_pending(store, "approved.md")++ store.set_status(rejected, ReviewStatus.REJECTED)+ store.set_status(approved, ReviewStatus.APPROVED)+ store.set_status(revising, ReviewStatus.APPROVED)+ store.touch_modified(revising) # an edit → needs_revision++ withheld = store.get_withheld_filenames(ContentType.BUILTIN)++ assert "pending.md" in withheld+ assert "rejected.md" in withheld+ assert "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 pending in {i.item_id for i in store.list_items(status=ReviewStatus.PENDING)}+++def test_withheld_source_ids_scope_to_external(store: ReviewStore) -> None:+ store.register(+ item_id="external:oer-1",+ content_type=ContentType.EXTERNAL,+ domain="finance",+ filename="oer-1",+ )+ _legacy_pending(store, "builtin-only.md")++ assert store.get_withheld_source_ids() == {"oer-1"}+ assert "builtin-only.md" not in store.get_withheld_source_ids()+++# ---------------------------------------------------------------------------+# Opt-in curation+# ---------------------------------------------------------------------------+++def test_curation_moves_only_untouched_defaults(store: ReviewStore) -> None:+ default_a = _register_default(store, "a.md")+ default_b = _register_default(store, "b.md")+ signed_off = _register_default(store, "signed.md")++ store.set_status(signed_off, ReviewStatus.APPROVED, "checked by our CFO")++ assert store.queue_for_curation("finance") == 2+ assert store.get_item(default_a).status == ReviewStatus.PENDING # type: ignore[union-attr]+ assert store.get_item(default_b).status == ReviewStatus.PENDING # type: ignore[union-attr]+ # An explicit approval is not curation fodder — it keeps its timestamp.+ assert store.get_item(signed_off).status == ReviewStatus.APPROVED # type: ignore[union-attr]+ assert store.get_item(signed_off).reviewed_at is not None # type: ignore[union-attr]++ assert store.stop_curation("finance") == 2+ assert store.get_item(default_a).status == ReviewStatus.APPROVED # type: ignore[union-attr]+ assert store.get_item(default_a).reviewed_at is None # type: ignore[union-attr]+++def test_curation_is_domain_scoped(store: ReviewStore) -> None:+ _register_default(store, "fin.md")+ _register_default(store, "hr.md", domain="hr")++ assert store.queue_for_curation("finance") == 1+ assert store.get_item("builtin:hr:hr.md").status == ReviewStatus.APPROVED # type: ignore[union-attr]+++def test_count_trusted_defaults_by_domain(store: ReviewStore) -> None:+ _register_default(store, "a.md")+ _register_default(store, "h.md", domain="hr")+ decided = _register_default(store, "decided.md")+ store.set_status(decided, ReviewStatus.APPROVED, "vetted")++ assert store.count_trusted_defaults_by_domain() == {"finance": 1, "hr": 1}+++# ---------------------------------------------------------------------------+# Bulk approve: explicit id selector+# ---------------------------------------------------------------------------+++def test_bulk_approve_by_item_ids(store: ReviewStore) -> None:+ a = _legacy_pending(store, "a.md")+ _legacy_pending(store, "b.md")++ ids = store.bulk_approve(item_ids=[a])++ assert ids == [a]+ assert store.get_item("builtin:finance:b.md").status == ReviewStatus.PENDING # type: ignore[union-attr]+++def test_bulk_approve_empty_id_list_is_a_noop(store: ReviewStore) -> None:+ _legacy_pending(store, "a.md")+ assert store.bulk_approve(item_ids=[]) == []+ assert store.count_by_status()["pending"] == 1+++def test_bulk_approve_ignores_already_decided_items(store: ReviewStore) -> None:+ rejected = _legacy_pending(store, "rejected.md")+ store.set_status(rejected, ReviewStatus.REJECTED, "no")++ assert store.bulk_approve(item_ids=[rejected]) == []+ assert store.get_item(rejected).status == ReviewStatus.REJECTED # type: ignore[union-attr]+++# ---------------------------------------------------------------------------+# Provenance: shipped content vs the user's own uploads+# ---------------------------------------------------------------------------+++def test_curation_never_touches_a_user_upload(store: ReviewStore) -> None:+ """A user's own document is also (pending, reviewed_at NULL).++ Inferring "this is a queued shipped default" from that shape made+ `stop_curation` approve someone's brand-new upload and count it as shipped+ content — a first review decision taken on their behalf by a button+ pressed for an unrelated reason.+ """+ shipped = _register_default(store, "shipped.md")+ upload = store.register(+ item_id="builtin:finance:my_upload.md",+ content_type=ContentType.BUILTIN,+ domain="finance",+ filename="my_upload.md",+ )+ assert upload.trusted_default is False+ assert store.get_item(shipped).trusted_default is True # type: ignore[union-attr]++ # Simulate a restart: the sync must NOT re-flag the upload as shipped,+ # even though the upload physically lives in the built-in tree.+ ReviewStore.sync_builtin_registrations(store._db_path)+ assert store.get_item(upload.item_id).trusted_default is False # type: ignore[union-attr]++ # Curating the domain queues the shipped docs; the upload is already+ # pending and is not something curation owns.+ queued = store.queue_for_curation("finance")+ assert queued >= 1+ assert store.get_item(shipped).status == ReviewStatus.PENDING # type: ignore[union-attr]++ # Stopping restores exactly what it queued — never the upload, which keeps+ # waiting for a real first review.+ assert store.stop_curation("finance") == queued+ assert store.get_item(shipped).status == ReviewStatus.APPROVED # type: ignore[union-attr]+ assert store.get_item(upload.item_id).status == ReviewStatus.PENDING # type: ignore[union-attr]+ assert store.get_item(upload.item_id).trusted_default is False # type: ignore[union-attr]+++def test_backfill_never_approves_a_user_upload(tmp_path: Path) -> None:+ """The upgrade must not silently publish a doc a human left in the queue."""+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH++ db = _legacy_db(tmp_path)+ domain, _ = _shipped_pairs(1)[0]+ # The upload must physically exist in the built-in tree — that is exactly+ # where `POST /knowledge/builtin` puts it, and it is what made a directory+ # scan mistake it for shipped content.+ on_disk = BUILTIN_KNOWLEDGE_PATH / domain / "my_unvetted_memo.md"+ on_disk.write_text("# confidential draft", encoding="utf-8")+ try:+ upload = _seed_legacy_pending(db, on_disk.name, domain=domain)++ ReviewStore.initialize_db(db)+ ReviewStore.sync_builtin_registrations(db) # must never flag the upload+ ReviewStore.backfill_trusted_defaults(db)+ store = ReviewStore(db_path=db)++ item = store.get_item(upload)+ assert item is not None+ assert item.trusted_default is False+ assert item.status == ReviewStatus.PENDING+ finally:+ on_disk.unlink()+++def test_backfill_keeps_annotated_shipped_docs_retrievable(tmp_path: Path) -> None:+ """No shipped doc may lose retrievability on upgrade.++ Annotations are injected into specialist context by DOMAIN regardless of+ item status, so holding an annotated doc back would feed the Executive a+ correction to a document it can no longer see.+ """+ db = _legacy_db(tmp_path)+ ReviewStore.initialize_db(db)+ ReviewStore.sync_builtin_registrations(db)+ store = ReviewStore(db_path=db)++ # Put every shipped row back to the pre-change 'pending' state, then have+ # an SME annotate one and leave a note on another.+ with sqlite3.connect(db) as conn:+ conn.execute("UPDATE review_items SET status = 'pending'")+ annotated, noted = (i.item_id for i in store.list_items(limit=2))+ store.add_annotation(annotated, "finance", "we use a 12% WACC, not 8%")+ store.update_notes(noted, "double-check this one")++ ReviewStore.backfill_trusted_defaults(db)++ assert store.count_by_status()["pending"] == 0+ assert store.get_withheld_filenames(ContentType.BUILTIN) == set()+ # The correction survives alongside the doc it corrects.+ assert len(store.list_annotations(item_id=annotated)) == 1+++def test_backfill_is_concurrency_safe(tmp_path: Path) -> None:+ """Two processes booting at once must not crash on the marker row."""+ import threading++ db = _legacy_db(tmp_path)+ for domain, filename in _shipped_pairs(20):+ _seed_legacy_pending(db, filename, domain=domain)+ ReviewStore.initialize_db(db)+ ReviewStore.sync_builtin_registrations(db)++ errors: list[Exception] = []++ def _boot() -> None:+ try:+ ReviewStore.backfill_trusted_defaults(db)+ except Exception as exc: # pragma: no cover - only on regression+ errors.append(exc)++ threads = [threading.Thread(target=_boot) for _ in range(6)]+ for t in threads:+ t.start()+ for t in threads:+ t.join()++ assert errors == []+++def test_bulk_approve_rejects_an_oversized_id_list(store: ReviewStore) -> None:+ """Silently dropping the tail would under-approve without telling anyone."""+ from openexecutive.knowledge.review_store import BULK_MAX_IDS++ with pytest.raises(ValueError, match="BULK_MAX_IDS"):+ store.bulk_approve(item_ids=[f"builtin:x:{i}.md" for i in range(BULK_MAX_IDS + 1)])+++def test_shipped_manifest_matches_git(tmp_path: Path) -> None:+ """The manifest must list exactly the built-in docs the repo ships.++ It cannot be derived from the filesystem at runtime — a user's upload lands+ in the same tree — so it is committed, and this guards it against drift.+ Adding a knowledge doc without regenerating the manifest fails here.+ """+ import subprocess++ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES++ prefix = "packages/core/openexecutive/knowledge/builtin/"+ tracked = subprocess.run(+ ["git", "ls-files", f"{prefix}**/*.md"],+ capture_output=True,+ text=True,+ cwd=Path(__file__).resolve().parents[4],+ check=True,+ ).stdout.split()+ expected = {+ p[len(prefix):] for p in tracked+ if p.startswith(prefix) and "/skills/" not in p+ }++ assert expected, "git ls-files returned nothing — check the path prefix"+ missing = expected - SHIPPED_BUILTIN_FILES+ extra = SHIPPED_BUILTIN_FILES - expected+ assert not missing, f"regenerate shipped_manifest.py — missing: {sorted(missing)}"+ assert not extra, f"regenerate shipped_manifest.py — no longer shipped: {sorted(extra)}"+++def test_sync_ignores_an_unmanifested_file_in_the_builtin_tree() -> None:+ """A user upload sits in the shipped tree but must never be registered by the sync."""+ from openexecutive.knowledge.loader import BUILTIN_KNOWLEDGE_PATH+ from openexecutive.knowledge.shipped_manifest import SHIPPED_BUILTIN_FILES++ intruder = BUILTIN_KNOWLEDGE_PATH / "finance" / "user_upload_probe.md"+ intruder.write_text("# not shipped", encoding="utf-8")+ try:+ assert "finance/user_upload_probe.md" not in SHIPPED_BUILTIN_FILES+ finally:+ intruder.unlink()diff --git a/packages/ui/src/app/guide/page.tsx b/packages/ui/src/app/guide/page.tsxindex 87b816ce..55bf99da 100644--- a/packages/ui/src/app/guide/page.tsx+++ b/packages/ui/src/app/guide/page.tsx@@ -12,7 +12,7 @@ const SECTIONS = [{ id: 'ask_oe', label: 'Ask OE', sub: 'The page-aware assistant panel — explains any screen and fills forms for you to review.' },{ id: 'today', label: 'Today / Morning Brief', sub: 'What needs you right now: proposals, department health, and people with open items.' },{ id: 'pulse', label: 'Pulse (Memory)', sub: "The Executive's running memory — decisions made, initiatives in flight, advice gathered." },- { id: 'review', label: 'Review Queue', sub: 'Approve, reject, or correct incoming knowledge before the Executive relies on it.' },+ { id: 'review', label: 'Review Queue', sub: 'Built-in knowledge is trusted by default. Review what you upload or edit, or send a domain for review yourself.' },{ id: 'jobs', label: 'Jobs (Workflows)', sub: 'Multi-step workflows that produce a deliverable — board prep, GTM plan, perf review.' },{ id: 'artifacts', label: 'Artifacts', sub: 'Your library of finished documents — drafts and workflow outputs in one place.' },{ id: 'watchlist', label: 'Watch List', sub: 'External monitors — stock tickers, RSS feeds, status pages, web queries — that raise alerts.' },diff --git a/packages/ui/src/components/ReviewQueue.tsx b/packages/ui/src/components/ReviewQueue.tsxindex 612bed0a..fd5ff461 100644--- a/packages/ui/src/components/ReviewQueue.tsx+++ b/packages/ui/src/components/ReviewQueue.tsx@@ -9,9 +9,11 @@ import {ReviewStatus,addAnnotation,bulkApproveReviewItems,+ curateDomain,deleteAnnotation,getBuiltinFile,getReviewItem,+ getTrustedDefaults,listAllAnnotations,listItemAnnotations,listReviewItems,@@ -45,10 +47,34 @@ const PRIORITY_CLASSES: Record<ReviewPriority, string> = {low: "bg-surface-overlay/60 text-fg-muted border border-line-strong/60",};-function StatusPill({ status }: { status: ReviewStatus }) {+const TRUSTED_DEFAULT_CLASS =+ "bg-surface-overlay/60 text-fg-muted border border-line-strong/60";++function StatusPill({+ status,+ reviewedAt,+ trustedDefault,+}: {+ status: ReviewStatus;+ reviewedAt?: string | null;+ trustedDefault?: boolean;+}) {+ // Provenance comes from the server, never inferred: a user's own upload can+ // also sit approved-with-no-timestamp, and labelling it "Ships with Open+ // Executive" would be a lie about where the content came from.+ const trusted = trustedDefault === true && status === "approved" && reviewedAt == null;return (- <span className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${STATUS_CLASSES[status]}`}>- {STATUS_LABELS[status]}+ <span+ className={`text-[10px] font-medium px-1.5 py-0.5 rounded-full ${+ trusted ? TRUSTED_DEFAULT_CLASS : STATUS_CLASSES[status]+ }`}+ title={+ trusted+ ? "Ships with Open Executive. Available to the Executive, but nobody here has reviewed it."+ : undefined+ }+ >+ {trusted ? "Default" : STATUS_LABELS[status]}</span>);}@@ -218,7 +244,11 @@ function ItemSlideOver({<div className="flex items-center gap-1.5 mt-1.5 flex-wrap"><span className="text-[10px] bg-surface-overlay text-fg-muted border border-line-strong rounded px-1.5 py-0.5">{item.domain}</span><span className="text-[10px] bg-surface-overlay text-fg-muted border border-line-strong rounded px-1.5 py-0.5">{item.content_type}</span>- <StatusPill status={item.status} />+ <StatusPill+ status={item.status}+ reviewedAt={item.reviewed_at}+ trustedDefault={item.trusted_default}+ /><PriorityPill priority={item.priority} /></div></div>@@ -402,15 +432,19 @@ export default function ReviewQueue() {const [filterType, setFilterType] = useState<"builtin" | "external" | "">("");const [selectedItemId, setSelectedItemId] = useState<string | null>(null);const [rejectModal, setRejectModal] = useState<RejectModalState>(null);+ const [trustedDefaults, setTrustedDefaults] = useState<Record<string, number>>({});+ const [pendingItems, setPendingItems] = useState<ReviewItem[]>([]);const loadQueue = useCallback(async () => {setLoading(true);try {- const [pending, needsRevision] = await Promise.all([+ const [pending, needsRevision, defaults] = await Promise.all([listReviewItems({ status: "pending", limit: 200 }),listReviewItems({ status: "needs_revision", limit: 200 }),+ getTrustedDefaults().catch(() => ({}) as Record<string, number>),]);setItems([...pending, ...needsRevision]);+ setTrustedDefaults(defaults);} finally {setLoading(false);}@@ -419,13 +453,23 @@ export default function ReviewQueue() {const loadAll = useCallback(async () => {setLoading(true);try {- const result = await listReviewItems({- status: filterStatus || undefined,- domain: filterDomain || undefined,- content_type: filterType || undefined,- limit: 500,- });+ // The per-domain action row must reflect what the SERVER would do, so it+ // reads its own unfiltered sources. Deriving those counts from the+ // filtered, 500-capped `allItems` made the buttons vanish whenever a+ // status filter was set, and undercounted past the cap.+ const [result, defaults, pending] = await Promise.all([+ listReviewItems({+ status: filterStatus || undefined,+ domain: filterDomain || undefined,+ content_type: filterType || undefined,+ limit: 500,+ }),+ getTrustedDefaults().catch(() => ({}) as Record<string, number>),+ listReviewItems({ status: "pending", limit: 500 }),+ ]);setAllItems(result);+ setTrustedDefaults(defaults);+ setPendingItems(pending);} finally {setLoading(false);}@@ -482,13 +526,38 @@ export default function ReviewQueue() {await loadAll();};+ const handleCurate = async (domain: string, action: "start" | "stop") => {+ // Starting curation withholds that domain from the Executive, so say so+ // before doing it — this is the one action here that removes knowledge.+ if (action === "start") {+ const n = trustedDefaults[domain] ?? 0;+ const ok = window.confirm(+ `Queue ${n} item${n === 1 ? "" : "s"} in "${domain}" for review?\n\n` ++ `They will be withheld from the Executive until you approve them. ` ++ `You can undo this with "Stop curating".`,+ );+ if (!ok) return;+ }+ await curateDomain(domain, action);+ await loadQueue();+ await loadAll();+ };+const handleItemUpdated = (updated: ReviewItem) => {setItems((prev) => prev.map((i) => (i.item_id === updated.item_id ? updated : i)));setAllItems((prev) => prev.map((i) => (i.item_id === updated.item_id ? updated : i)));};// Unique domains from current list- const domains = Array.from(new Set(allItems.map((i) => i.domain))).sort();+ // Union of every source, so a domain is never hidden just because the+ // current filter excludes it from `allItems`.+ const domains = Array.from(+ new Set([+ ...allItems.map((i) => i.domain),+ ...pendingItems.map((i) => i.domain),+ ...Object.keys(trustedDefaults),+ ]),+ ).sort();return (<div className="p-6">@@ -526,7 +595,39 @@ export default function ReviewQueue() {)}</div>{!loading && items.length === 0 && (- <div className="text-center py-16 text-fg-subtle text-sm">All caught up — nothing to review.</div>+ <div className="py-12 max-w-2xl mx-auto text-center">+ <p className="text-sm text-fg">Nothing waiting on you.</p>+ <p className="text-xs text-fg-muted mt-2 leading-relaxed">+ The knowledge that ships with Open Executive is trusted by default — the+ Executive can use it right away, and it does not sit here waiting for+ sign-off. Items appear in this queue when you upload something new, edit an+ existing file, or deliberately send a domain for review.+ </p>+ {Object.keys(trustedDefaults).length > 0 && (+ <div className="mt-6 text-left">+ <p className="text-[11px] uppercase tracking-wide text-fg-subtle mb-2">+ Review a domain yourself+ </p>+ <p className="text-xs text-fg-muted mb-3 leading-relaxed">+ Sending a domain for review withholds it from the Executive until you+ work through it.+ </p>+ <div className="flex gap-2 flex-wrap">+ {Object.entries(trustedDefaults)+ .sort(([a], [b]) => a.localeCompare(b))+ .map(([domain, count]) => (+ <button+ key={domain}+ onClick={() => handleCurate(domain, "start")}+ className="text-[11px] text-fg-muted hover:text-amber-400 bg-surface-elevated border border-line-strong hover:border-amber-900/60 px-2.5 py-1.5 rounded-lg transition-colors"+ >+ Curate {domain} ({count})+ </button>+ ))}+ </div>+ </div>+ )}+ </div>)}<div className="space-y-2">{items.map((item) => (@@ -579,18 +680,51 @@ export default function ReviewQueue() {</select></div>- {/* Bulk approve by domain */}+ {/* Per-domain actions: approve what's queued, or start/stop curating. */}{domains.length > 0 && (<div className="flex gap-2 mb-4 flex-wrap">- {domains.map((d) => (- <button- key={d}- onClick={() => handleBulkApprove(d)}- className="text-[10px] text-fg-muted hover:text-emerald-400 bg-surface-elevated border border-line-strong hover:border-emerald-900/60 px-2 py-1 rounded-lg transition-colors"- >- Approve all pending in {d}- </button>- ))}+ {domains.map((d) => {+ const pendingInDomain = pendingItems.filter((i) => i.domain === d);+ // "Stop curating" reverses queue_for_curation, whose selector is+ // `trusted_default = 1 AND reviewed_at IS NULL`. Mirror BOTH: a+ // user's own upload is pending with no timestamp too, and+ // counting it would render a button that does nothing.+ const untouchedPending = pendingInDomain.filter(+ (i) => i.trusted_default && i.reviewed_at == null,+ ).length;+ const defaultsInDomain = trustedDefaults[d] ?? 0;+ return (+ <div key={d} className="flex gap-1">+ {pendingInDomain.length > 0 && (+ <button+ onClick={() => handleBulkApprove(d)}+ className="text-[10px] text-fg-muted hover:text-emerald-400 bg-surface-elevated border border-line-strong hover:border-emerald-900/60 px-2 py-1 rounded-lg transition-colors"+ >+ Approve all pending in {d}+ </button>+ )}+ {untouchedPending > 0 ? (+ <button+ onClick={() => handleCurate(d, "stop")}+ className="text-[10px] text-fg-muted hover:text-fg bg-surface-elevated border border-line-strong px-2 py-1 rounded-lg transition-colors"+ title={`Return ${untouchedPending} unreviewed item(s) in ${d} to trusted default`}+ >+ Stop curating {d}+ </button>+ ) : (+ defaultsInDomain > 0 && (+ <button+ onClick={() => handleCurate(d, "start")}+ className="text-[10px] text-fg-muted hover:text-amber-400 bg-surface-elevated border border-line-strong hover:border-amber-900/60 px-2 py-1 rounded-lg transition-colors"+ title={`Send ${defaultsInDomain} shipped item(s) in ${d} for review — they will be withheld from the Executive until approved`}+ >+ Curate {d} ({defaultsInDomain})+ </button>+ )+ )}+ </div>+ );+ })}</div>)}@@ -736,7 +870,11 @@ function ItemRow({<div className="flex items-center gap-2 flex-wrap"><span className="text-sm text-fg font-medium truncate">{item.filename}</span><span className="text-[10px] bg-surface-overlay text-fg-muted border border-line-strong rounded px-1.5 py-0.5">{item.domain}</span>- <StatusPill status={item.status} />+ <StatusPill+ status={item.status}+ reviewedAt={item.reviewed_at}+ trustedDefault={item.trusted_default}+ /><PriorityPill priority={item.priority} /></div><p className="text-[11px] text-fg-subtle mt-0.5">Added {formatDate(item.registered_at)}</p>diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 280bd1d1..35db08c3 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -1207,6 +1207,8 @@ export interface ReviewItem {priority: ReviewPriority;reviewer_notes: string;reviewed_at: string | null;+ /** True only for content that ships with the product, not a user upload. */+ trusted_default: boolean;registered_at: string;last_modified_at: string;}@@ -1280,16 +1282,41 @@ export async function patchReviewItem(itemId: string, patch: ReviewItemPatch): Preturn res.json();}-export async function bulkApproveReviewItems(domain?: string): Promise<{ approved_count: number }> {+// A bulk approve must always carry a selector — the backend rejects a call+// with none, so clearing the whole queue is an explicit `all_pending` opt-in+// rather than an empty body.+export async function bulkApproveReviewItems(+ domain?: string,+): Promise<{ approved_count: number; item_ids: string[] }> {const res = await fetch(`${API_BASE}/review/bulk-approve`, {method: "POST",headers: { "Content-Type": "application/json" },- body: JSON.stringify({ domain }),+ body: JSON.stringify(domain ? { domain } : { all_pending: true }),});if (!res.ok) throw new Error("Failed to bulk approve");return res.json();}+export async function curateDomain(+ domain: string,+ action: "start" | "stop",+): Promise<{ domain: string; action: "start" | "stop"; affected_count: number }> {+ const res = await fetch(`${API_BASE}/review/curate`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ domain, action }),+ });+ if (!res.ok) throw new Error("Failed to update curation");+ return res.json();+}++/** Domain → count of shipped docs nobody has reviewed yet. */+export async function getTrustedDefaults(): Promise<Record<string, number>> {+ const res = await fetch(`${API_BASE}/review/trusted-defaults`);+ if (!res.ok) throw new Error("Failed to load trusted defaults");+ return res.json();+}+export async function listAllAnnotations(activeOnly = true): Promise<ReviewAnnotation[]> {const res = await fetch(`${API_BASE}/review/annotations?active_only=${activeOnly}`);if (!res.ok) throw new Error("Failed to list annotations");