PMFlow/docs/superpowers/plans/2026-04-14-query-source-policy-refactor.md

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