[CLAUDE] Docs: S31 RAG v1.3 baseline PASS (11/11 recall@5=1.000) + gotcha #52

- eval/runs/: baseline v1.1 final PASS after retrieval.py fix (vector search restored)
- eval/trial-state-lock.json: quality_gate.pass=true, baseline=1.000, avg_rerank=0.847
- docs/gotchas.md: +gotcha #52 qdrant-client 1.18 removed search() silent AttributeError
- docs/STATUS.md: S31 entry — RAG PASS, retrieval.py fix, CLI restart required
- docs/HANDOFF.md: S31 brief + CRITICAL CLI restart note
- docs/changelog/sessions/: S31 session log

Root cause: qdrant-client 1.18 removed search() → vec_results always [] → BM25-only
Fix: retrieval.py query_points().points (applied to AI_INFRA repo)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/gotchas.md

@@ -921,6 +921,48 @@ const staticMap: Record<string, string> = {
 - Original Plan CA Chunk B commit: `06a441c` (Implementer missed point 4)
 - Mirror: `fe-admin/src/components/Layout.tsx:33-53`
 
+### 52. `qdrant-client` 1.18 xóa `search()` API — `except Exception: continue` nuốt lỗi silent → vector search luôn trả `[]` (Session 31 RAG eval diagnosis)
+
+**Triệu chứng:** `search_memory` MCP tool chỉ trả kết quả cho queries có BM25 exact-match tốt (có tất cả token trong cùng 1 chunk). Queries dùng ngữ nghĩa / multi-hop concept → **0 results** dù Qdrant `points_count=2949` green.
+
+**Root cause:** `qdrant-client 1.18.0` removed `QdrantClient.search()` method hoàn toàn. `retrieval.py` vẫn gọi `_qdrant.search(...)`:
+```python
+# OLD (broken in 1.18):
+hits = _qdrant.search(
+    collection_name=c,
+    query_vector=query_vector,
+    limit=top_k,
+    with_payload=True,
+)
+# AttributeError: 'QdrantClient' object has no attribute 'search'
+```
+Exception bị `except Exception: continue` nuốt silent → `vec_results = []` mọi lúc → pipeline chỉ có BM25.
+
+**Kết quả trước fix:** RAG eval v1.1 recall@5 = 0.455 (chỉ BM25 queries). v1.0 = 0.455 (same reason). BM25 strict AND-match: ALL tokens phải cùng chunk → multi-token query 8+ tokens fail.
+
+**Fix (retrieval.py):**
+```python
+# NEW (qdrant-client 1.12+ query_points API):
+resp = _qdrant.query_points(
+    collection_name=c,
+    query=query_vector,    # ← param renamed: query_vector → query
+    limit=top_k,
+    with_payload=True,
+)
+for h in resp.points:    # ← .points không phải iterable trực tiếp
+```
+
+**Kết quả sau fix:** recall@5 = 1.000 (11/11), avg rerank = 0.847. PASS gate.
+
+**Phòng tránh:** Pin `qdrant-client` version trong deps (`==1.x.y`). Hoặc thêm health-check startup: `assert hasattr(_qdrant, 'query_points'), "upgrade qdrant-client"`. **KHÔNG dùng `except Exception: continue` che-mờ lỗi API** — ít nhất log warning.
+
+**References:**
+- AI_INFRA: `claude-rag/lib/retrieval.py` `vector_search()` function — fixed 2026-05-26 S31
+- Eval run: `eval/runs/2026-05-26-baseline-v1.1-final.json`
+- Diagnosis: Qdrant REST `/collections/proj_solution_erp` green (2949 points), `bm25.db` 2949 chunks → pipeline broken, not data. Confirmed via `python -c "from qdrant_client import QdrantClient; client.search(...)"` → AttributeError.
+
+---
+
 ## Checklist debug bug mới
 
 1. Build pass không? → fail → check using + package version compat
@@ -950,3 +992,4 @@ const staticMap: Record<string, string> = {
 25. Nếu page move cross-app (Implementer Case 2) nhưng menu leaf KHÔNG hiện sidebar dù BE trả permission OK → check `Layout.tsx` `resolvePath` staticMap miss key mapping → MenuLeaf null guard silent drop (#50). 4-place mirror checklist: page + Routes + menuKeys.ts + Layout.tsx staticMap
 26. Nếu new Seed method KHÔNG chạy prod dù dotnet build PASS + deploy SUCCESS → check nested inside `if (!demoSeedDisabled)` gate (Plan T S23 t10 flag enabled prod) → INFRASTRUCTURE seed phải PROMOTE OUT of DemoSeed gate (#51). Decision tree: production cần để work end-to-end? YES → ungate
 25. Nếu UI audit list show `Đã gửi duyệt → Đã gửi duyệt` lặp gây nhầm → drop dual-phase badge khi state machine self-loop, thay Decision badge + next-target hint parse từ comment (#49)
+27. Nếu RAG `search_memory` trả 0 results dù Qdrant green + BM25 có data → `qdrant-client` upgrade xóa `search()` method, bị nuốt silent. Test: `python -c "from qdrant_client import QdrantClient; c=QdrantClient(url='http://127.0.0.1:6333'); c.search"`. Fix: dùng `query_points(query=...).points` (#52)