feat(rag): honest deflection gate with amber UI state and alternative-question chips

tests/e2e/test_honest_deflection.py

@@ -0,0 +1,197 @@
+"""Phase 04 E2E (Playwright): honest deflection when retrieval is weak.
+
+Story: ``.agent/user_stories/honest-deflection.md``
+Run in isolation (DB must be up: ``podman compose up -d db``):
+
+    uv run pytest tests/e2e/test_honest_deflection.py -v --no-cov
+
+The seeded KB (``tests/fixtures/docs``) + the mock LLM's genuine
+token-overlap embeddings make the honesty gate deterministic: the
+off-topic baking question scores far below ``BOR_RELEVANCE_THRESHOLD``,
+so Brain must deflect — amber bubble, "I haven't done anything like
+that", and ≥2 "Maybe try" chips about topics it really covers.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from pathlib import Path
+from threading import Thread
+from typing import Any
+
+import httpx
+from playwright.sync_api import Page, expect
+from sqlalchemy import select, text
+
+from app.config import Settings, get_settings
+from app.db import SessionLocal
+from app.models import QueryLog
+from app.rag.importer import ImportSummary, import_sources
+from app.rag.llm import LLMClient
+
+REPO = Path(__file__).resolve().parents[2]
+FIXTURES = REPO / "tests" / "fixtures" / "docs"
+OFF_TOPIC = "How do I bake sourdough bread?"
+# The mock's deflection answer (tests/e2e/mock_llm.py) must match this.
+DEFLECT_PHRASE = r"haven't done anything like that"
+MOCK_ANSWER_MARKER = "Deterministic mock answer for E2E"
+
+
+async def _import_fixtures(mock_port: int) -> ImportSummary:
+    kwargs: dict[str, Any] = {"_env_file": None, "llm_base_url": f"http://127.0.0.1:{mock_port}/v1"}
+    settings = Settings(**kwargs)  # pyright: ignore[reportCallIssue]
+    return await import_sources([FIXTURES], LLMClient(settings))
+
+
+def _run_in_thread(coro: Any) -> Any:
+    """Run a coroutine on a worker thread.
+
+    Playwright's sync API keeps an asyncio loop running on the test thread,
+    so ``asyncio.run`` cannot be called directly from a test body.
+    """
+    box: dict[str, Any] = {}
+
+    def runner() -> None:
+        try:
+            box["value"] = asyncio.run(coro)
+        except BaseException as e:  # noqa: BLE001 — re-raised on the test thread
+            box["error"] = e
+
+    t = Thread(target=runner)
+    t.start()
+    t.join()
+    if "error" in box:
+        raise box["error"]
+    return box["value"]
+
+
+def _reset_db(mock_port: int, seed: bool) -> ImportSummary | None:
+    """Truncate the KB (and query log), then optionally re-import fixtures."""
+    with SessionLocal() as db:
+        db.execute(text("TRUNCATE chunks, documents, query_log"))
+        db.commit()
+    if not seed:
+        return None
+    return _run_in_thread(_import_fixtures(mock_port))
+
+
+def _deflected_chips(page: Page) -> Any:
+    return page.locator(".msg.brain.is-deflected .maybe-try .suggestion-chip")
+
+
+def test_off_topic_question_deflects_honestly(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    summary = _reset_db(mock_llm, seed=True)
+    assert summary is not None and summary.added == 3
+    page.set_default_timeout(30_000)
+    page.goto(app_url)
+    expect(page.locator("#kb-banner")).to_be_hidden()
+
+    page.fill("#message-input", OFF_TOPIC)
+    page.click("#send-btn")
+    expect(page.locator(".msg.user .bubble")).to_contain_text(OFF_TOPIC)
+
+    # The answer bubble is the deflected one: amber, honest phrasing.
+    bubble = page.locator(".msg.brain.is-deflected .bubble").first
+    bubble.wait_for(state="visible", timeout=30_000)
+    expect(bubble).to_have_text(re.compile(DEFLECT_PHRASE, re.IGNORECASE), timeout=30_000)
+    expect(page.locator(".msg.brain.is-deflected")).to_have_count(1)
+
+    # Visually distinct from a normal answer (accent-bg / accent-line).
+    style = bubble.evaluate("el => getComputedStyle(el)")
+    assert style["backgroundColor"] == "rgb(255, 247, 232)"  # --accent-bg #fff7e8
+    assert style["borderTopColor"] == "rgb(245, 158, 11)"  # --accent-line #f59e0b
+
+    # ≥2 "Maybe try:" chips below the bubble, in an accessible group.
+    chips = _deflected_chips(page)
+    expect(chips.first).to_be_visible(timeout=30_000)
+    assert chips.count() >= 2, "deflection must offer 2-3 alternative chips"
+    group = page.locator(".msg.brain.is-deflected .maybe-try")
+    expect(group).to_have_count(1)
+    expect(group.first).to_have_attribute("aria-label", "Maybe try")
+    expect(group.first).to_have_attribute("role", "list")
+    # Chip component contract: brand pill, ≥44px touch target.
+    chip_style = chips.first.evaluate("el => getComputedStyle(el)")
+    assert chip_style["backgroundColor"] == "rgb(238, 240, 254)"  # --brand-soft
+    assert chip_style["color"] == "rgb(55, 48, 163)"  # --brand-ink
+    box = chips.first.bounding_box()
+    assert box is not None and box["height"] >= 44
+
+    # Button recovers (never stale).
+    expect(page.locator("#send-btn")).to_be_enabled()
+    expect(page.locator("#send-label")).to_have_text("Send")
+
+
+def test_deflection_suggestions_are_clickable(
+    page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+    _reset_db(mock_llm, seed=True)
+    page.set_default_timeout(30_000)
+    page.goto(app_url)
+    page.fill("#message-input", OFF_TOPIC)
+    page.click("#send-btn")
+    chips = _deflected_chips(page)
+    expect(chips.first).to_be_visible(timeout=30_000)
+    chip_text = chips.first.inner_text().strip()
+    assert chip_text
+
+    # Phase 04 chip contract (wire what exists): click fills + focuses.
+    chips.first.click()
+    expect(page.locator("#message-input")).to_have_value(chip_text)
+    expect(page.locator("#message-input")).to_be_focused()
+
+    # Completing the question asks it: a new user bubble + a reply —
+    # and the chip's topic is one Brain really covers, so this turn is
+    # a grounded (non-deflected) answer quoting the question.
+    page.press("#message-input", "Enter")
+    expect(page.locator(".msg.user .bubble")).to_have_count(2, timeout=30_000)
+    expect(page.locator(".msg.user .bubble").nth(1)).to_contain_text(chip_text)
+    expect(page.locator(".msg.brain .bubble")).to_have_count(2, timeout=30_000)
+    second = page.locator(".msg.brain .bubble").nth(1)
+    expect(second).to_contain_text(chip_text, timeout=30_000)
+    expect(second).to_contain_text(MOCK_ANSWER_MARKER, timeout=30_000)
+    # Still exactly one deflected turn in the conversation.
+    expect(page.locator(".msg.brain.is-deflected")).to_have_count(1)
+
+    # Button recovers after the second turn (never stale).
+    expect(page.locator("#send-btn")).to_be_enabled()
+    expect(page.locator("#send-label")).to_have_text("Send")
+
+
+def test_deflected_done_event_and_query_log(app_url: str, mock_llm: int, db_ready: None) -> None:
+    """Raw SSE contract for a deflected turn + the durable query_log row."""
+    _reset_db(mock_llm, seed=True)
+
+    frames: list[dict[str, Any]] = []
+    with httpx.stream(
+        "POST", f"{app_url}/api/chat", json={"message": OFF_TOPIC}, timeout=60.0
+    ) as r:
+        assert r.status_code == 200
+        assert r.headers["content-type"].startswith("text/event-stream")
+        buf = ""
+        for part in r.iter_text():
+            buf += part
+            while "\n\n" in buf:
+                frame, buf = buf.split("\n\n", 1)
+                if frame.strip().startswith("data:"):
+                    frames.append(json.loads(frame.strip().removeprefix("data:").strip()))
+    assert buf.strip() == ""  # stream ends cleanly on a frame boundary
+
+    deltas = [f for f in frames if f.get("type") == "delta"]
+    assert len(deltas) >= 2  # the deflection is streamed too
+    done = [f for f in frames if f.get("type") == "done"]
+    assert len(done) == 1
+    assert frames[-1]["type"] == "done"
+    assert done[0]["deflected"] is True
+    assert 2 <= len(done[0]["suggestions"]) <= 3
+    assert all(s.strip() for s in done[0]["suggestions"])
+
+    # Durable record: deflected=true + the weak top_score.
+    with SessionLocal() as db:
+        row = db.scalars(select(QueryLog)).one()
+    assert row.question == OFF_TOPIC
+    assert row.deflected is True
+    assert 0.0 < row.top_score < get_settings().relevance_threshold
+    assert row.chunk_hits >= 1

tests/integration/test_chat_api.py

@@ -32,6 +32,7 @@ from app.rag.llm import EmbeddingError, LLMError
 
 FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "docs"
 QUESTION = "How is my Kubernetes cluster set up?"
+OFF_TOPIC = "How do I bake sourdough bread?"
 DIM = 768
 _TOKEN_RE = re.compile(r"[a-z0-9]+")
 
@@ -164,11 +165,51 @@ def test_chat_writes_query_log_row(client, db, seeded_kb: FakeRagLLM) -> None:
     total_chunks = db.scalar(select(func.count()).select_from(Chunk))
     assert row.chunk_hits == min(get_settings().top_k_chunks, total_chunks)
     assert row.top_score > 0.0  # genuine token-overlap cosine, best hit
+    assert row.top_score >= get_settings().relevance_threshold  # why the gate answered
     assert row.top_score <= 1.0
     assert "docs/homelab/kubernetes.md" in row.sources
     assert row.latency_ms >= 0
 
 
+def test_off_topic_question_deflects_honestly(client, db, seeded_kb: FakeRagLLM) -> None:
+    """Phase 04 contract: weak retrieval ⇒ honest deflection, no fake answer."""
+    fastapi_app.dependency_overrides[chat_api.get_llm] = lambda: seeded_kb
+    try:
+        _, _, frames = _stream_chat(client, OFF_TOPIC)
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+    assert not any(f.get("type") == "error" for f in frames)
+    deltas = [f for f in frames if f.get("type") == "delta"]
+    assert len(deltas) >= 2  # the LLM is still called (voice stays chippy)
+    done = frames[-1]
+    assert done["type"] == "done"
+    assert done["deflected"] is True
+    # 2-3 alternative chips, all non-empty, derived from real titles/topics.
+    assert 2 <= len(done["suggestions"]) <= 3
+    assert all(s.strip() for s in done["suggestions"])
+    assert any(
+        "Deploying a New Service" in s for s in done["suggestions"]
+    ), "the best weak-hit title must be offered as a chip"
+    assert done["sources"], "weak hits are still reported as the closest sources"
+
+    # The LLM saw the LOW prompt: DEFLECT_MODE + titles, never doc content.
+    (system, user) = seeded_kb.seen_messages[0][0], seeded_kb.seen_messages[0][1]
+    assert user["content"] == OFF_TOPIC
+    assert "<relevance>LOW</relevance>" in system["content"]
+    assert "DEFLECT_MODE" in system["content"]
+    assert "HONESTY GATE" in system["content"]
+    assert "Talos Linux" not in system["content"]  # full doc content never sent
+    assert "<documents>" not in system["content"]
+
+    # Durable record: deflected=true + the weak top_score.
+    row = db.scalars(select(QueryLog)).one()
+    assert row.question == OFF_TOPIC
+    assert row.deflected is True
+    assert 0.0 < row.top_score < get_settings().relevance_threshold
+    assert row.chunk_hits >= 1
+
+
 def test_chat_empty_kb_streams_empty_sources(client, db) -> None:
     db.execute(text("TRUNCATE chunks, documents, query_log"))
     db.commit()
@@ -179,11 +220,17 @@ def test_chat_empty_kb_streams_empty_sources(client, db) -> None:
     finally:
         fastapi_app.dependency_overrides.clear()
 
+    # Nothing retrieved ⇒ nothing to pretend to know: honest deflection.
     done = frames[-1]
     assert done["type"] == "done"
-    assert done["deflected"] is False
+    assert done["deflected"] is True
     assert done["sources"] == []
+    assert 2 <= len(done["suggestions"]) <= 3  # onboarding fallback chips
+    (system, _user) = llm.seen_messages[0][0], llm.seen_messages[0][1]
+    assert "DEFLECT_MODE" in system["content"]
+    assert "nothing close at all" in system["content"]
     row = db.scalars(select(QueryLog)).one()
+    assert row.deflected is True
     assert row.top_score == 0.0
     assert row.chunk_hits == 0
     assert row.sources == ""

tests/unit/test_chat_gate.py

@@ -0,0 +1,322 @@
+"""Unit: the honesty gate (A8) — boundary, prompts, and suggestion chips.
+
+Pure gate logic runs against fake retriever output (``RetrievedChunk``
+rows from a fake retriever) with no Postgres and no network. The
+endpoint-level tests drive ``POST /api/chat`` with the retriever, the DB
+session, and the LLM all faked, so the whole deflection contract
+(prompt → deltas → done event → query_log) is verified without a stack.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Iterator
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api import chat as chat_api
+from app.config import Settings
+from app.main import app as fastapi_app
+from app.models import Document, QueryLog
+from app.rag.retriever import RetrievedChunk, weak_hit_titles
+from app.rag.suggestions import MAX_SUGGESTIONS, derive_suggestions
+
+ANSWER = "I haven't done anything like that — try one of these instead!"
+
+
+def _settings(threshold: float = 0.30) -> Settings:
+    return Settings(
+        _env_file=None,  # pyright: ignore[reportCallIssue]
+        relevance_threshold=threshold,
+    )
+
+
+def _doc(title: str, content: str) -> Document:
+    return Document(
+        id=uuid.uuid4(),
+        source="Homelab",
+        path=f"{title.lower().replace(' ', '-')}.md",
+        full_path="/tmp/doc.md",
+        title=title,
+        content=content,
+        content_hash="0" * 64,
+    )
+
+
+def _chunk(doc: Document, score: float) -> RetrievedChunk:
+    return RetrievedChunk(
+        chunk_id=uuid.uuid4(),
+        position=0,
+        content=doc.content[:32],
+        score=score,
+        document=doc,
+    )
+
+
+# ---------- gate boundary (fake retriever rows, no LLM) ----------
+
+
+def test_gate_boundary_score_at_threshold_answers() -> None:
+    """Score exactly at the threshold ⇒ HIGH (the gate is strict <)."""
+    doc = _doc("Kubernetes Homelab Cluster", "TALOS_DOC_CONTENT")
+    plan = chat_api.plan_turn([_chunk(doc, 0.30)], _settings(threshold=0.30))
+    assert plan.deflected is False
+    assert plan.top_score == pytest.approx(0.30)
+    assert "<relevance>HIGH</relevance>" in plan.system_prompt
+    assert "DEFLECT_MODE" not in plan.system_prompt
+    assert "TALOS_DOC_CONTENT" in plan.system_prompt
+    assert plan.suggestions == []
+
+
+def test_gate_boundary_just_below_threshold_deflects() -> None:
+    doc = _doc("Kubernetes Homelab Cluster", "TALOS_DOC_CONTENT")
+    plan = chat_api.plan_turn([_chunk(doc, 0.2999)], _settings(threshold=0.30))
+    assert plan.deflected is True
+    assert plan.top_score == pytest.approx(0.2999)
+    assert "<relevance>LOW</relevance>" in plan.system_prompt
+    assert "DEFLECT_MODE" in plan.system_prompt
+    # Titles only: the full document content must never reach the LLM.
+    assert "TALOS_DOC_CONTENT" not in plan.system_prompt
+    assert "Kubernetes Homelab Cluster" in plan.system_prompt
+
+
+def test_gate_is_env_tunable_via_settings() -> None:
+    doc = _doc("Backup Strategy", "BACKUP_DOC_CONTENT")
+    hits = [_chunk(doc, 0.30)]
+    assert chat_api.plan_turn(hits, _settings(threshold=0.35)).deflected is True
+    assert chat_api.plan_turn(hits, _settings(threshold=0.25)).deflected is False
+
+
+def test_gate_zero_chunks_deflects_with_fallback_chips() -> None:
+    plan = chat_api.plan_turn([], _settings())
+    assert plan.deflected is True
+    assert plan.top_score == 0.0
+    assert "nothing close at all" in plan.system_prompt
+    # No weak hits ⇒ onboarding fallback fills the chips.
+    assert 2 <= len(plan.suggestions) <= MAX_SUGGESTIONS
+
+
+# ---------- prompt content (LOW vs HIGH) ----------
+
+
+def test_low_prompt_has_titles_only_no_content() -> None:
+    a = _doc("Kubernetes Homelab Cluster", "ALPHA_DOC_CONTENT")
+    b = _doc("Backup Strategy", "BETA_DOC_CONTENT")
+    plan = chat_api.plan_turn([_chunk(b, 0.10), _chunk(a, 0.20)], _settings())
+    prompt = plan.system_prompt
+    assert "<relevance>LOW</relevance>" in prompt
+    assert "DEFLECT_MODE" in prompt
+    assert "HONESTY GATE" in prompt  # the LOW rule is what the model follows
+    assert "- Kubernetes Homelab Cluster" in prompt
+    assert "- Backup Strategy" in prompt
+    assert "ALPHA_DOC_CONTENT" not in prompt
+    assert "BETA_DOC_CONTENT" not in prompt
+    assert "<documents>" not in prompt
+
+
+def test_high_path_unaffected() -> None:
+    a = _doc("Kubernetes Homelab Cluster", "ALPHA_DOC_CONTENT")
+    b = _doc("Backup Strategy", "BETA_DOC_CONTENT")
+    plan = chat_api.plan_turn([_chunk(a, 0.90), _chunk(b, 0.40)], _settings())
+    assert plan.deflected is False
+    assert plan.suggestions == []
+    assert "<relevance>HIGH</relevance>" in plan.system_prompt
+    assert "DEFLECT_MODE" not in plan.system_prompt
+    assert "ALPHA_DOC_CONTENT" in plan.system_prompt
+    assert "BETA_DOC_CONTENT" in plan.system_prompt
+    assert [d.title for d in plan.docs] == ["Kubernetes Homelab Cluster", "Backup Strategy"]
+
+
+# ---------- weak_hit_titles (fake retriever mapping) ----------
+
+
+def test_weak_hit_titles_dedupe_and_rank_by_best_score() -> None:
+    a = _doc("Kubernetes Homelab Cluster", "AAA")
+    b = _doc("Backup Strategy", "BBB")
+    chunks = [_chunk(b, 0.5), _chunk(a, 0.2), _chunk(a, 0.9)]
+    assert weak_hit_titles(chunks) == ["Kubernetes Homelab Cluster", "Backup Strategy"]
+
+
+# ---------- suggestions derivation ----------
+
+
+def test_suggestions_derived_from_titles_in_order() -> None:
+    got = derive_suggestions(
+        ["Kubernetes Homelab Cluster", "Backup Strategy", "Deploying a New Service"],
+        fallback=["should not appear"],
+    )
+    assert len(got) == 3
+    assert all(s.strip() for s in got)
+    assert "Kubernetes Homelab Cluster" in got[0]
+    assert "Backup Strategy" in got[1]
+    assert "Deploying a New Service" in got[2]
+
+
+def test_suggestions_capped_at_three() -> None:
+    got = derive_suggestions([f"Title {i}" for i in range(6)], fallback=["F"])
+    assert len(got) == MAX_SUGGESTIONS == 3
+
+
+def test_suggestions_top_up_from_fallback_when_titles_thin() -> None:
+    got = derive_suggestions(
+        ["Backup Strategy"],
+        fallback=["How is my Kubernetes cluster set up?", "What's my backup strategy?"],
+    )
+    assert len(got) == 3
+    assert got[0] == "What's in your notes about Backup Strategy?"
+    assert got[1] == "How is my Kubernetes cluster set up?"
+
+
+def test_suggestions_dedupes_and_ignores_blank() -> None:
+    got = derive_suggestions(
+        ["Backup Strategy", "backup strategy", "   "],
+        fallback=["What's my backup strategy?", "   "],
+    )
+    # "backup strategy" is a case-insensitive dup; blank title/fallback are
+    # skipped — including ones that only look blank after formatting. Only
+    # two valid items remain, and the list never pads with junk.
+    assert got == [
+        "What's in your notes about Backup Strategy?",
+        "What's my backup strategy?",
+    ]
+    assert all("about ?" not in s and s == s.strip() for s in got)
+
+
+def test_suggestions_empty_input_yields_fallback_only() -> None:
+    assert derive_suggestions([], fallback=[]) == []
+    got = derive_suggestions([], fallback=["One?", "Two?"])
+    assert got == ["One?", "Two?"]
+
+
+# ---------- endpoint-level gate (fake retriever + fake LLM + fake session) ----------
+
+
+class _CannedLLM:
+    """Records the messages it is given; streams a canned answer."""
+
+    def __init__(self, answer: str = ANSWER) -> None:
+        self.settings = Settings(_env_file=None)  # pyright: ignore[reportCallIssue]
+        self.embed_batches = 0
+        self.answer = answer
+        self.seen: list[list[dict[str, str]]] = []
+
+    async def embed_one(self, _text: str) -> list[float]:
+        return [0.0] * 768
+
+    async def chat_stream(self, messages: list[dict[str, str]]):
+        self.seen.append(messages)
+        for i in range(0, len(self.answer), 12):
+            yield self.answer[i : i + 12]
+
+
+class _FakeSession:
+    """Stands in for the DB session: records the QueryLog row it is given."""
+
+    def __init__(self) -> None:
+        self.added: list[Any] = []
+        self.commits = 0
+
+    def add(self, obj: Any) -> None:
+        self.added.append(obj)
+
+    def commit(self) -> None:
+        self.commits += 1
+
+
+@pytest.fixture()
+def gate_env(monkeypatch: pytest.MonkeyPatch) -> Iterator[tuple[_FakeSession, _CannedLLM]]:
+    """``POST /api/chat`` with retriever, session, and LLM all faked."""
+    monkeypatch.setattr(chat_api, "db_available", lambda: True)
+    session = _FakeSession()
+    llm = _CannedLLM()
+    monkeypatch.setitem(fastapi_app.dependency_overrides, chat_api.get_db, lambda: session)
+    monkeypatch.setitem(fastapi_app.dependency_overrides, chat_api.get_llm, lambda: llm)
+    yield session, llm
+    fastapi_app.dependency_overrides.clear()
+
+
+def _ask(client: TestClient, message: str) -> list[dict[str, Any]]:
+    with client.stream("POST", "/api/chat", json={"message": message}) as r:
+        assert r.status_code == 200
+        frames: list[dict[str, Any]] = []
+        buf = ""
+        for part in r.iter_text():
+            buf += part
+            while "\n\n" in buf:
+                frame, buf = buf.split("\n\n", 1)
+                frame = frame.strip()
+                if frame.startswith("data:"):
+                    frames.append(json.loads(frame.removeprefix("data:").strip()))
+    assert buf.strip() == ""
+    return frames
+
+
+def _fake_retriever(chunks: list[RetrievedChunk]) -> Any:
+    def retrieve(_db: Any, _vec: list[float]) -> list[RetrievedChunk]:
+        return chunks
+
+    return retrieve
+
+
+def test_endpoint_just_below_threshold_deflects(
+    client: TestClient,
+    gate_env: tuple[_FakeSession, _CannedLLM],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    session, llm = gate_env
+    doc = _doc("Deploying a New Service", "DOC_CONTENT_NEVER_SENT")
+    monkeypatch.setattr(chat_api, "retrieve", _fake_retriever([_chunk(doc, 0.2999)]))
+
+    frames = _ask(client, "How do I bake sourdough bread?")
+
+    deltas = [f for f in frames if f["type"] == "delta"]
+    assert "".join(d["text"] for d in deltas) == ANSWER  # the LLM was still called
+    done = frames[-1]
+    assert done["type"] == "done"
+    assert done["deflected"] is True
+    assert 2 <= len(done["suggestions"]) <= MAX_SUGGESTIONS  # title chip + fallback
+    assert all(s.strip() for s in done["suggestions"])
+    assert any("Deploying a New Service" in s for s in done["suggestions"])
+
+    # The LLM saw the LOW prompt: DEFLECT_MODE + titles, never doc content.
+    (system, user) = llm.seen[0][0], llm.seen[0][1]
+    assert user["content"] == "How do I bake sourdough bread?"
+    assert "DEFLECT_MODE" in system["content"]
+    assert "DOC_CONTENT_NEVER_SENT" not in system["content"]
+
+    # Durable record: deflected + the weak score.
+    (row,) = session.added
+    assert isinstance(row, QueryLog)
+    assert row.deflected is True
+    assert row.top_score == pytest.approx(0.2999)
+    assert session.commits == 1
+
+
+def test_endpoint_score_at_threshold_answers(
+    client: TestClient,
+    gate_env: tuple[_FakeSession, _CannedLLM],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    session, llm = gate_env
+    doc = _doc("Kubernetes Homelab Cluster", "TALOS_DOC_SENT")
+    monkeypatch.setattr(chat_api, "retrieve", _fake_retriever([_chunk(doc, 0.30)]))
+
+    frames = _ask(client, "How is my Kubernetes cluster set up?")
+
+    done = frames[-1]
+    assert done["type"] == "done"
+    assert done["deflected"] is False
+    assert done["suggestions"] == []
+    assert done["sources"] and done["sources"][0]["title"] == "Kubernetes Homelab Cluster"
+
+    (system, _user) = llm.seen[0][0], llm.seen[0][1]
+    assert "<relevance>HIGH</relevance>" in system["content"]
+    assert "DEFLECT_MODE" not in system["content"]
+    assert "TALOS_DOC_SENT" in system["content"]
+
+    (row,) = session.added
+    assert isinstance(row, QueryLog)
+    assert row.deflected is False
+    assert row.top_score == pytest.approx(0.30)