Soften the tone of the docs and comments written today

apps/ai-service/tests/test_agent.py

@@ -142,6 +142,84 @@ def test_drug_attribute_without_an_attribute_does_not_fall_into_overview_retriev
     assert retrieval.calls == []
 
 
+# --- the pediatric dosing gate. This code path gained its first test
+# coverage on 2026-08-11, after driving production reproduced the same
+# behaviour 5/5: the clarify question asked for both age and weight every
+# time, including the field the user had just supplied ("Bé 18 ký ...",
+# "Bé nặng 18 kg ...", "Trẻ 5 tuổi ..." all received "Bé bao nhiêu tuổi và
+# cân nặng bao nhiêu kg?"). Requiring BOTH fields is deliberate and stays —
+# the formulary bands paracetamol by age *and* by mg/kg — so these tests pin
+# the question text without loosening the requirement. --
+
+
+def _pediatric_agent(**frame_kwargs) -> RagAgent:
+    return _agent(QueryFrame(
+        turn_type="dosing_calc",
+        drugs=("paracetamol_acetaminophen",),
+        population="tre_em",
+        **frame_kwargs,
+    ))
+
+
+def test_pediatric_gate_with_a_known_weight_asks_only_for_the_age():
+    reply = _pediatric_agent(weight_kg=18.0).handle("bé 18 ký sốt cao uống paracetamol liều bao nhiêu")
+
+    assert reply.decision == "clarify"
+    assert reply.reason == "missing_pediatric_age_or_weight"
+    assert "tuổi" in reply.clarification
+    # The weight is echoed back so the user can see it was received (and
+    # catch a mis-parse), but is never asked for again.
+    assert "18 kg" in reply.clarification
+    assert "bao nhiêu kg" not in reply.clarification
+
+
+def test_pediatric_gate_with_a_known_age_asks_only_for_the_weight():
+    reply = _pediatric_agent(age_text="5 tuổi").handle("trẻ 5 tuổi sốt cao uống paracetamol liều bao nhiêu")
+
+    assert reply.decision == "clarify"
+    assert "kg" in reply.clarification
+    assert "bao nhiêu tuổi" not in reply.clarification
+
+
+def test_pediatric_gate_with_neither_field_still_asks_for_both():
+    reply = _pediatric_agent().handle("liều paracetamol cho trẻ em")
+
+    assert reply.decision == "clarify"
+    assert "tuổi" in reply.clarification
+    assert "kg" in reply.clarification
+
+
+def test_pediatric_gate_still_requires_both_fields_before_answering():
+    """The safety property, asserted directly: knowing only one of the two
+    must NOT be treated as enough to pick a regimen. Both single-field cases
+    above stop at `clarify` — this states the invariant so a future change
+    that "helpfully" answers with weight alone fails here loudly."""
+    for kwargs in ({"weight_kg": 18.0}, {"age_text": "5 tuổi"}, {}):
+        reply = _pediatric_agent(**kwargs).handle("liều paracetamol cho bé")
+        assert reply.decision == "clarify", kwargs
+        assert reply.reason == "missing_pediatric_age_or_weight", kwargs
+
+
+def test_a_whole_number_weight_is_not_echoed_with_a_trailing_zero():
+    reply = _pediatric_agent(weight_kg=18.0).handle("liều paracetamol cho bé 18 ký")
+
+    assert "18 kg" in reply.clarification
+    assert "18.0" not in reply.clarification
+
+
+def test_the_models_own_clarify_question_still_wins_over_the_generated_one():
+    """Unchanged precedence: when understanding.py produced a question of its
+    own it is still preferred, because it can see phrasing/context this
+    code-level fallback cannot."""
+    reply = _pediatric_agent(
+        weight_kg=18.0,
+        needs_clarify=True,
+        clarify_reason="Bé mấy tháng tuổi rồi ạ?",
+    ).handle("liều paracetamol cho bé 18 ký")
+
+    assert reply.clarification == "Bé mấy tháng tuổi rồi ạ?"
+
+
 def test_needs_clarify_frame_is_surfaced_directly():
     agent = _agent(QueryFrame(
         turn_type="dosing_calc", drugs=("paracetamol",),