sync: 189 file da Baida98/AI@ba97a2d4 (2026-08-26 08:44 UTC) [deploy-all] (#106)

- sync: 189 file da Baida98/AI@ba97a2d4 (2026-08-26 08:44 UTC) [deploy-all] (9c23e83b42554b8a9988959e707769b6e3f246e7)

agents/unified_loop.py

@@ -3777,6 +3777,29 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
         except Exception:
             pass  # decision_memory non disponibile — continua normalmente
 
+        # B5-ORDER: una spiegazione completa e non operativa è già un intento
+        # sufficiente. Deve bypassare le guardie di ambiguità, che sono riservate a
+        # comandi realmente vaghi; le guardie in _is_pure_explanation() proteggono
+        # file, mutazioni, dati realtime e richieste troppo lunghe.
+        # Sprint 5 ITEM 13: classify_ms — tempo routing/classificazione goal (sync, <1ms)
+        _t0_classify = _time.monotonic()
+        if self._is_pure_explanation(goal):
+            try:
+                from api.state import record_timing as _rtcB5
+                _rtcB5("classify_ms", (_time.monotonic() - _t0_classify) * 1000)
+            except Exception:
+                pass
+            await self._transition_state(state, AgentState.THINKING, on_step)
+            _r = await _finish(await self._run_fallback(state, on_step))
+            _r["timing_ms"] = int((_time.monotonic() - _t_run) * 1000)
+            _r["effective_max_steps"] = state.max_steps
+            if _sid_token is not None:
+                try: _sid_var.reset(_sid_token)
+                except Exception: pass
+            if self._session_files:
+                asyncio.ensure_future(self._vfs_git_backup())
+            return _r
+
         # P29-B1: gate ambiguità strutturale — _is_goal_ambiguous() era P28-B2 dead code (mai chiamata).
         # Zero LLM, <0.1ms. Lingua-aware via self._run_lang (P28-B1). Fires dopo blacklist e prima del routing.
         if _is_goal_ambiguous(goal):
@@ -3940,9 +3963,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
             return _r_bl
 
 
-        # Sprint 5 ITEM 13: classify_ms — tempo routing/classificazione goal (sync, <1ms)
-        _t0_classify = _time.monotonic()
-
         # S402: Fast Path — greeting/ack/identità semplice → bypass tutto l'overhead
         if self._is_simple_query(goal):
             try:
@@ -3992,27 +4012,6 @@ class UnifiedAgentLoop(DirectToolsMixin, PromptBuilderMixin, LLMSelectionMixin,
         # già — "direct tools + fallback" — ma il codice faceva solo _run_fallback senza tool).
         # Bug: query meteo/news/cerca non chiamavano mai i tool reali → LLM allucinava i dati
         # → ResponseVerifier girava su risposta inventata → retry → 20-60s inutili.
-        # B5: query spiegazione pura → _run_fallback diretta (-20-30s risparmio)
-        # Scenari: "cos'è X", "spiegami Y", "how does Z work?", "explain W"
-        # Fail-open: se regex troppo larga → path normale (nessuna perdita)
-        if self._is_pure_explanation(goal):
-            try:
-                from api.state import record_timing as _rtcB5
-                _rtcB5("classify_ms", (_time.monotonic() - _t0_classify) * 1000)
-            except Exception:
-                pass
-            await self._transition_state(state, AgentState.THINKING, on_step)
-            _r = await _finish(await self._run_fallback(state, on_step))
-            _r["timing_ms"] = int((_time.monotonic() - _t_run) * 1000)
-            _r["effective_max_steps"] = state.max_steps
-            if _sid_token is not None:
-                try: _sid_var.reset(_sid_token)
-                except Exception: pass
-            if self._session_files:
-                asyncio.ensure_future(self._vfs_git_backup())
-            return _r
-
-
         # P36: Hybrid Execution Router — Python code analysis fast path.
         # Se goal contiene keyword analisi + codice Python nel context/goal,
         # chiama python_analyze direttamente (<5ms) saltando planner+LLM (5-15s).

agents/unified_loop_llm.py

@@ -119,12 +119,26 @@ class LLMSelectionMixin:
         return self._verifier_llm
 
     def _is_pure_explanation(self, goal: str) -> bool:
-        """B5: True se goal è domanda concettuale pura — nessun tool necessario.
-        4 guard fail-open: len<300 | pattern interrogativo | no action verb | no file ref."""
+        """True per una spiegazione concettuale completa che non richiede mutazioni.
+
+        I riferimenti nominali contestuali, per esempio ``dopo una modifica al
+        codice``, non trasformano una domanda esplicativa in un task operativo.
+        Una seconda azione imperativa resta invece un percorso operativo.
+        """
         if len(goal) > 300:                                return False
-        if not self._PURE_EXPLANATION_RE.search(goal[:200]): return False
-        if self._EXPL_ACTION_RE.search(goal[:200]):           return False
-        if self._EXPL_FILE_REF_RE.search(goal[:200]):         return False
+        text = goal[:200]
+        if not self._PURE_EXPLANATION_RE.search(text):      return False
+        if self._EXPL_FILE_REF_RE.search(text):             return False
+        contextual_spans = [
+            match.span()
+            for match in self._EXPL_CONTEXTUAL_ACTION_REF_RE.finditer(text)
+        ]
+        for action in self._EXPL_ACTION_RE.finditer(text):
+            if not any(
+                start <= action.start() < end
+                for start, end in contextual_spans
+            ):
+                return False
         return True
 
     # S371: _SKIP_SMOL_RE — skippa smolagents per query semplici (notizie, cerca) → direct tools
@@ -543,7 +557,7 @@ class LLMSelectionMixin:
         r"^\s*(?:"
         r"(?:cos'?[e\xe8]\s+)"
         r"|(?:che\s+cos'?[a\xe0]?\s*[e\xe8]\s+)"
-        r"|(?:spiegami\b)"
+        r"|(?:spiega(?:mi)?\b)"
         r"|(?:dimmi\s+(?:come|cosa|cos|perch[e\xe8]|qual[e\xe8])\b)"
         r"|(?:qual[e\xe8]\s+|qual\s+[e\xe8]\s+)(?:la\s+)?(?:differenz[ae]|scopo|significato)"
         r"|(?:come\s+funziona\s+(?!il\s+(?:mio|tuo|nostro|codice|progetto|login|sito|sistema|questo)\b))"
@@ -556,6 +570,11 @@ class LLMSelectionMixin:
         r")",
         re.IGNORECASE | re.DOTALL,
     )
+    _EXPL_CONTEXTUAL_ACTION_REF_RE = re.compile(
+        r"\b(?:dopo|prima|durante|in seguito a|a seguito di)\s+una\s+modifica\s+"
+        r"(?:al|del|nel)\s+(?:codice|file|progetto)\b",
+        re.IGNORECASE,
+    )
     _EXPL_ACTION_RE = re.compile(
         r"\b(crea|scrivi|genera|implementa|esegui|correggi|fix|run|create|write|"
         r"generate|implement|execute|installa|deploy|avvia|configura|aggiorna|update|"

tests/test_pure_explanation_routing.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+
+from agents.unified_loop_llm import LLMSelectionMixin
+from agents.unified_loop_tools import DirectToolsMixin
+
+
+class _ExplanationClassifier(LLMSelectionMixin, DirectToolsMixin):
+    """Harness minimale: il classificatore non richiede provider o stato runtime."""
+
+
+def _classifier() -> _ExplanationClassifier:
+    return _ExplanationClassifier()
+
+
+def test_observed_mobile_prompt_is_a_pure_explanation() -> None:
+    goal = (
+        "Spiega in una frase concreta come i test di regressione riducono il rischio "
+        "di introdurre bug dopo una modifica al codice."
+    )
+
+    assert _classifier()._is_pure_explanation(goal) is True
+
+
+def test_technical_keywords_do_not_override_a_complete_explanation() -> None:
+    goal = (
+        "Spiega in una frase concreta come i test di regressione riducono il rischio "
+        "di introdurre bug dopo una modifica al codice."
+    )
+
+    assert _classifier()._needs_tools(goal) is True
+    assert _classifier()._is_pure_explanation(goal) is True
+
+
+def test_pure_explanation_precedes_ambiguity_gates() -> None:
+    loop_source = (Path(__file__).parents[1] / "agents" / "unified_loop.py").read_text(
+        encoding="utf-8"
+    )
+
+    assert loop_source.index("if self._is_pure_explanation(goal):") < loop_source.index(
+        "if _is_goal_ambiguous(goal):"
+    )
+
+
+def test_spiega_prefix_is_recognized_like_spiegami() -> None:
+    assert _classifier()._is_pure_explanation(
+        "Spiega perché la cache migliora le prestazioni di una applicazione."
+    ) is True
+    assert _classifier()._is_pure_explanation(
+        "Spiegami perché la cache migliora le prestazioni di una applicazione."
+    ) is True
+
+
+def test_secondary_operational_action_stays_out_of_pure_explanation_route() -> None:
+    assert _classifier()._is_pure_explanation(
+        "Spiega la differenza tra cache e storage, poi modifica il file di configurazione."
+    ) is False
+
+
+def test_explicit_file_reference_stays_out_of_pure_explanation_route() -> None:
+    assert _classifier()._is_pure_explanation(
+        "Spiega cosa fa questa funzione nel codice."
+    ) is False
+
+
+def test_overlong_explanation_stays_on_normal_route() -> None:
+    assert _classifier()._is_pure_explanation("Spiega " + ("il concetto. " * 30)) is False