# Query Source Policy Refactor 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:** Make `query.answer` decide internal vs external source first, stop mixed retrieval in v1, and replace fake embeddings with real embedding backends.

**Architecture:** Keep `plan mode` in PMFlow. Move `source_policy` to the `query.answer` gateway and propagate it through AdaptiveRAG. Collapse duplicated query-answer source decisions so retrieval only executes against the selected source family.

**Tech Stack:** FastAPI, SQLAlchemy async, PMFlow kernel, AdaptiveRAG, pytest

---

### Task 1: Add Contract Tests For Source Policy

**Files:**
- Modify: `backend/tests/test_adaptive_rag_mainline_contract.py`
- Modify: `backend/tests/test_rag_route_contract.py`

- [ ] **Step 1: Write failing tests**
- [ ] **Step 2: Run targeted pytest to verify failures**
- [ ] **Step 3: Implement the minimal contract changes**
- [ ] **Step 4: Re-run targeted pytest**

### Task 2: Front-Load Source Policy In query.answer

**Files:**
- Modify: `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_answer_entry.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_answer_mainline.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_core_intent.py`

- [ ] **Step 1: Write failing tests for source_policy propagation**
- [ ] **Step 2: Run targeted pytest to verify failures**
- [ ] **Step 3: Implement gateway propagation and unified query semantics**
- [ ] **Step 4: Re-run targeted pytest**

### Task 3: Remove Source-Selection Drift And Mixed Retrieval

**Files:**
- Modify: `backend/app/services/adaptive_rag_service/mixin_deep_guard_answer.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_multistep_flow.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py`

- [ ] **Step 1: Write failing tests for internal-only / external-only retrieval domains**
- [ ] **Step 2: Run targeted pytest to verify failures**
- [ ] **Step 3: Implement retrieval-domain gating and remove duplicated source-selection branches**
- [ ] **Step 4: Re-run targeted pytest**

### Task 4: Replace Fake Embeddings

**Files:**
- Modify: `backend/app/services/llm_service/mixin_task_helpers.py`
- Modify: `backend/tests/test_adaptive_rag_mainline_contract.py`

- [ ] **Step 1: Write failing tests for embedding provider selection and fake-vector removal**
- [ ] **Step 2: Run targeted pytest to verify failures**
- [ ] **Step 3: Implement real embedding backend selection**
- [ ] **Step 4: Re-run targeted pytest**

### Task 5: Update Runtime Docs And Verify

**Files:**
- Modify: `AGENTS.md`
- Modify: `docs/architecture/RUNTIME_GUARDRAILS.md`
- Modify: `docs/architecture/CODE_REFERENCE_INDEX.md`

- [ ] **Step 1: Update runtime/documentation summaries for source_policy and embedding rules**
- [ ] **Step 2: Run targeted backend pytest**
- [ ] **Step 3: Run `python -m py_compile` for touched backend modules**
- [ ] **Step 4: Summarize deviations vs baseline**