p67

patch_history/RETRIEX_PATCH_67_CONTEXTUAL_FOLLOWUP_ACTIONS_README.md

@@ -0,0 +1,52 @@
+# RetrieX Patch p67 – Contextual Follow-up Actions
+
+## Ziel
+
+`buildFollowUpActionsMessage()` war vorbereitet, aber nicht in den AgentRunner-Flow eingehängt. Dieser Patch aktiviert die Funktion kontrolliert und kontextsensitiv, damit die Production-UI nach einer fertigen Antwort sinnvolle nächste Schritte anbieten kann, ohne unsichere oder unpassende Aktionen zu zeigen.
+
+## Änderung
+
+- `AgentRunner` rendert nach der finalen Completed-Meta-Card optional eine Follow-up-Actions-Card.
+- Die Card erscheint nur, wenn `agent.production_ui.follow_up_actions.enabled` aktiv ist und echte Kontextsignale vorhanden sind.
+- Shop-Refinement-Actions werden nur bei vorhandenen Shop-Treffern angezeigt.
+- Die generische Shop-Suchaktion wird nur bei Commerce-Kontext ohne Shop-Systemfehler angeboten.
+- Die Knowledge-Action wird nur bei direkter/belastbarer RAG-Evidenz angezeigt.
+- Action-Duplikate werden beim Rendern dedupliziert.
+- Die bisherigen Action-Texte bleiben YAML-konfigurierbar und wurden in kontextbezogene Gruppen getrennt:
+  - `commerce`
+  - `shop_results`
+  - `knowledge`
+
+## Bewusst nicht geändert
+
+- Keine Änderung an Retrieval, Scoring, Ranking, Intent-Erkennung, Shop-Matching oder PromptBuilder.
+- `buildShopProductCardsMessage()` bleibt weiterhin nicht eingehängt, weil Produktkarten zusätzlich zur Antwort deutlich mehr UI-Duplikation und Regressionsrisiko erzeugen würden.
+- Keine neuen fachlichen Keywordlisten oder PHP-only Defaults.
+
+## Geänderte Dateien
+
+- `src/Agent/AgentRunner.php`
+- `src/Config/AgentRunnerConfig.php`
+- `src/Config/ChatMessagesConfig.php`
+- `config/retriex/chat-messages.yaml`
+
+## Lokale Checks
+
+Ausgeführt im ZIP-Arbeitsstand ohne `vendor/`:
+
+```bash
+php -l src/Agent/AgentRunner.php
+php -l src/Config/AgentRunnerConfig.php
+php -l src/Config/ChatMessagesConfig.php
+python3 -c 'import yaml; yaml.safe_load(open("config/retriex/chat-messages.yaml"))'
+```
+
+Zusätzlich wurde `ChatMessagesConfig::validate()` mit der geparsten `chat-messages.yaml` per Smoke-Test geprüft.
+
+## Empfohlene Checks in der Zielumgebung
+
+```bash
+bin/console mto:agent:config:validate
+bin/console mto:agent:regression:test
+bin/console mto:agent:config:audit-source --details
+```