# WP10 Device Search and Knowledge Q&A Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Deliver authorized device search and evidence-grounded device Q&A by extending the existing canonical governance knowledge pipeline.

**Architecture:** PostgreSQL device assets, authorized source mappings, and operational events remain authoritative. A bounded device retriever joins the existing knowledge retrieval pipeline before fusion, filters source business-domain scope in SQL, and emits the same stable evidence contract used by lexical/vector retrieval. The existing answer synthesizer remains the only generative path; it must refuse or report model unavailability instead of fabricating. LightRAG remains shadow-only and is not activated by WP10.

**Tech Stack:** Flask, SQLAlchemy/PostgreSQL, existing knowledge retrieval and Q&A services, Vue 2/Vuetify, pytest, Node test runner.

---

## Scope and constraints

- Search platform UID, device name, authorized source ID, location, organization, responsible person, and related alarm/fault/maintenance/downtime records.
- Derive device data range from each `ingestion_sources.permission_scope.business_domains`. An empty scope is admin-only; non-admin access is default-deny.
- Apply authorization inside SQL before device candidates are returned, then retain the pipeline's post-fusion authorization check.
- Return stable object UID, asset version, source time, point key/revision, source IDs, and related event evidence.
- For Q&A, return only model-selected canonical citations. When the model is unavailable or evidence is insufficient, return no answer and still expose the authorized retrieval evidence for inspection.
- Persist query audit evidence without storing raw questions, generated answers, secrets, or full retrieved content.
- Provide an admin-only source-scope configuration path and query-audit view.
- Do not add NL2SQL, online analysis, BI development, predictive maintenance, automatic repair, generic web search, or direct LightRAG answers.
- Do not claim enterprise acceptance until a real source scope, device corpus, answer model, and golden set have been validated.

### Task 1: Device evidence contract and deterministic query behavior

**Files:**
- Create: `app/core/knowledge/retrieval/device.py`
- Create: `tests/knowledge/test_device_retrieval.py`
- Modify: `app/core/knowledge/retrieval/pipeline.py`
- Modify: `tests/knowledge/test_retrieval.py`

- [x] Write failing tests that define query normalization, maximum length, deterministic device scoring, stable point keys, safe readable content, and source/event evidence boundaries.
- [x] Write a failing pipeline test proving device evidence participates in fusion and is still removed when its business domain is outside the access context.
- [x] Run only the two tests and confirm failure is caused by the absent device retriever integration.
- [x] Implement `SqlDeviceKnowledgeRetriever` with a 300-character query boundary, a maximum 100 results, SQL-pre-filtered business-domain authorization, and deterministic ranking.
- [x] Aggregate only authorized source codes and authorized alarm/fault/maintenance/downtime titles; do not include event evidence JSON or source configuration.
- [x] Emit `KnowledgeEvidence` with `object_type="DeviceAsset"`, `object_version=current_version`, one stable summary point, source time, and the authorized business-domain UID.
- [x] Add the optional `device` retriever to `KnowledgeRetrievalPipeline`; include it in standard search modes without changing LightRAG routing.
- [x] Re-run only device retrieval and pipeline tests until green.

### Task 2: Source scope management and real PostgreSQL authorization

**Files:**
- Create: `app/core/knowledge/device_scope.py`
- Create: `tests/knowledge/test_device_scope.py`
- Create: `tests/integration/test_device_knowledge_postgres.py`

- [x] Write failing service tests for sorted unique UUID scopes, the 100-domain boundary, invalid UUID rejection, missing source rejection, empty-scope admin-only semantics, and preservation of non-domain scope keys.
- [x] Write a failing PostgreSQL test with two device sources in different business domains plus one unscoped source.
- [x] Prove an admin can retrieve all three, a domain-A viewer can retrieve only source-A assets/events, source-B IDs do not match, and an unscoped asset does not leak.
- [x] Implement `DeviceSourceScopeService` and its SQLAlchemy repository against the existing `IngestionSource.permission_scope`.
- [x] Implement the device retriever query using an `authorized_sources` CTE so filtering occurs before text matching and aggregation.
- [x] Add a source-detail lookup that applies the same authorization and returns only safe device/source/event fields.
- [x] Run only the source-scope and PostgreSQL device-knowledge tests until green.

### Task 3: Knowledge API integration, citations, and query audit

**Files:**
- Create: `app/core/knowledge/query_audit.py`
- Create: `tests/knowledge/test_query_audit.py`
- Modify: `app/api/knowledge_base/routes.py`
- Modify: `tests/knowledge/test_api.py`
- Modify: `app/core/system/permissions.py`
- Modify: `tests/test_permission_matrix.py`

- [x] Write failing API tests for device search evidence, grounded device answers with citation content, model-unavailable answers with authorized retrieval evidence, device source detail, admin source-scope list/update, and admin query-audit list.
- [x] Write failing audit tests proving only a normalized SHA-256 query hash, subject, roles, authorized domains, mode, retriever counts, cited point identities, degraded components, correlation ID, and latency are stored.
- [x] Assert that raw query text, answer text, evidence content, credentials, and source configuration never enter the audit payload.
- [x] Instantiate `SqlDeviceKnowledgeRetriever` in the default canonical pipeline and add safe device fallback to `/api/knowledge/sources/<uid>`.
- [x] Add `evidence` to `/api/knowledge/ask` responses and enrich selected citations with their retrieved content and source metadata.
- [x] Persist a query audit for every executed search/ask; fail the request if mandatory audit persistence fails.
- [x] Add admin-only `GET/PUT /api/knowledge/admin/device-sources[/<uid>/scope]` and `GET /api/knowledge/admin/query-audits`.
- [x] Keep public search/ask under `governance:read` and all scope/audit operations under `knowledge:manage`.
- [x] Run only knowledge API, audit, and permission tests until green.

### Task 4: Device-focused knowledge workbench

**Files:**
- Create: `frontend/src/views/knowledgeBaseProduct/deviceKnowledgeModel.js`
- Create: `frontend/tests/device-knowledge-model.test.mjs`
- Modify: `frontend/src/views/knowledgeBaseProduct/index.vue`
- Modify: `frontend/src/api/governanceKnowledge.js`
- Create: `tests/knowledge/test_device_knowledge_frontend_contract.py`

- [x] Write failing model tests for device object labels, answer-status presentation, citation/evidence fallback, source-scope display, and admin-only controls.
- [x] Write a failing frontend contract test for device search prompts, source ID/location/responsible/fault coverage, explicit no-answer language, source-scope management, and audit visibility.
- [x] Add device prompt examples and render readable `DeviceAsset` evidence without parsing or exposing private source configuration.
- [x] For ask responses, display selected citations when grounded; otherwise display authorized retrieval evidence beneath the explicit refusal/model-unavailable state.
- [x] Add an admin source-scope dialog accepting newline-separated business-domain UUIDs and show that an empty scope is admin-only.
- [x] Add an admin query-audit list that displays time, mode, retriever counts, cited-point count, degraded components, and correlation ID but never raw questions.
- [x] Use the existing `$snackbar` interface for success and failure feedback.
- [x] Run only the Node model test, frontend contract test, and ESLint on changed frontend files.

### Task 5: Acceptance set, documentation, and release-copy parity

**Files:**
- Create: `docs/acceptance/WP10_DEVICE_KNOWLEDGE_GOLDEN_SET.json`
- Modify: `docs/FUNCTION_MODULE_CENSUS_20260726.md`
- Modify: `docs/DATAOPS_PHASE1_3_MONTH_WORK_PLAN_20260729.md`
- Modify: `docs/architecture/DATA_MODEL.md`
- Modify: `docs/architecture/OPENAPI.yaml`
- Modify: `tests/test_architecture_artifacts.py`
- Mirror changed backend files under: `deployment/app/`

- [x] Add a versioned ten-case acceptance set covering name, platform UID, source ID, location, responsible person, fault, grounded owner/fault questions, unauthorized-domain refusal, and insufficient-evidence refusal.
- [x] Document source-scope semantics, SQL pre-filtering, post-fusion authorization, audit data minimization, citation behavior, and model-unavailable behavior.
- [x] Mark WP10 engineering maturity separately from enterprise source-scope, real-model, and golden-set acceptance.
- [x] Update CAT-11, CAT-12, KAI-03, KAI-04, KAI-05, KAI-06, KAI-08, KAI-09, KAI-20, and KAI-22 without claiming NL2SQL or production K6 completion.
- [x] Regenerate OpenAPI and assert all new admin endpoints plus ask evidence fields are represented.
- [x] Copy every changed `app/` backend file to `deployment/app/` and verify byte parity.

### Task 6: Targeted validation and local branch commit

**Files:**
- Test only WP10-related files and directly affected permission/architecture contracts.

- [x] Run WP10 device retrieval, scope, query audit, API, frontend contract, PostgreSQL integration, permission, and architecture tests only.
- [x] Run Ruff only on changed Python files.
- [x] Run ESLint only on changed frontend files and run the device knowledge Node model test.
- [x] Build the frontend production bundle because the existing knowledge workbench changes.
- [x] Rebuild only local backend/frontend services needed for WP10 browser validation.
- [x] In the browser, verify authorized device search by source ID and fault, model-unavailable/insufficient evidence does not fabricate an answer, source detail is safe, source-scope management works, query audits contain no raw question, and a clean knowledge page has zero console errors.
- [x] Confirm the existing device asset and observability pages still load through unchanged navigation.
- [x] Commit the verified WP10 change on `codex/dataops-phase1-equipment-governance`; do not push or deploy production.