# External Query Gateway Baseline 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:** Route non-plan external `query.answer` through a dedicated external gateway, keep DuckDuckGo HTML search as bounded fallback, and stop internal sources from leaking into external answers.

**Architecture:** Add a small `external_query_service` that owns structured planning, adapter selection, and external evidence verification. Wire AdaptiveRAG external probing and retrieval to that service so `route_mode=external` no longer answers from internal retrieval or fail-open source summaries.

**Tech Stack:** Python 3.11, FastAPI, PMFlow AdaptiveRAG, Pydantic, pytest, httpx

---

### Task 1: Lock The External Gateway Contract With Tests

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

- [ ] **Step 1: Write failing tests for external gateway fallback order**
- [ ] **Step 2: Write failing tests for external source filtering to fail closed**
- [ ] **Step 3: Run targeted pytest to confirm the new tests fail for the right reason**

### Task 2: Add External Query Service And Planner Contract

**Files:**
- Create: `backend/app/services/external_query_service/__init__.py`
- Create: `backend/app/services/external_query_service/schemas.py`
- Create: `backend/app/services/external_query_service/planner.py`
- Create: `backend/app/services/external_query_service/registry.py`
- Create: `backend/app/services/external_query_service/gateway.py`
- Create: `backend/app/services/external_query_service/adapters/live_search.py`
- Create: `backend/app/services/external_query_service/adapters/mcp.py`
- Modify: `backend/app/config/ai_prompts.py`
- Modify: `backend/app/services/llm_service/shared_part_01.py`

- [ ] **Step 1: Add structured `ExternalQueryPlan` / evidence schemas**
- [ ] **Step 2: Add planner prompt and structured schema registration**
- [ ] **Step 3: Implement registry-first gateway with MCP placeholder and live-search fallback**
- [ ] **Step 4: Re-run targeted pytest for the service layer**

### Task 3: Wire AdaptiveRAG External Probe And Retrieval

**Files:**
- Modify: `backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py`
- Modify: `backend/app/services/adaptive_rag_service/mixin_deep_guard_rules.py`

- [ ] **Step 1: Route external probe through the new gateway**
- [ ] **Step 2: Route external retrieval through the new gateway instead of direct HTML search**
- [ ] **Step 3: Add external answer verification / guard behavior**
- [ ] **Step 4: Re-run targeted pytest for AdaptiveRAG contracts**

### Task 4: Update Docs And Verify

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

- [ ] **Step 1: Update architecture/runtime docs for the external gateway chain**
- [ ] **Step 2: Run targeted backend pytest**
- [ ] **Step 3: Run `python -m py_compile` on touched backend modules**
- [ ] **Step 4: Summarize MCP adapter assumptions and current fallback behavior**