p38

RETRIEX_PATCH_38_YAML_EXTERNALIZATION_HARDENING_README.md

@@ -0,0 +1,123 @@
+# RetrieX Patch p38 - YAML Externalization Hardening
+
+## Ziel
+
+Dieser Patch schliesst die nach p37 verbliebenen sinnvollen YAML-Externalization-Luecken im PHP-Core. Fokus ist nicht technische Infrastruktur, sondern fachliche, sprachliche und UI-nahe Listen, Tokens, Vergleichswerte, Prompt-Regeln und Normalisierungsregeln.
+
+Die Leitlinie bleibt:
+
+- keine neuen Token-/Stringlisten im PHP-Core
+- fachliche, sprachliche und UI-nahe Werte ueber YAML
+- bestehende 1.5.3-Logik nicht fachlich veraendern
+- keine neuen Spezialfaelle fuer konkrete Produkte
+
+## Geaenderte Dateien
+
+- `config/retriex/agent.yaml`
+- `config/retriex/language.yaml`
+- `config/retriex/prompt.yaml`
+- `src/Config/AgentRunnerConfig.php`
+- `src/Config/LanguageCleanupConfig.php`
+- `src/Config/PromptBuilderConfig.php`
+- `src/Agent/AgentRunner.php`
+- `src/Agent/PromptBuilder.php`
+- `src/Knowledge/Retrieval/QueryCleaner.php`
+- `src/Knowledge/Retrieval/NdjsonLexicalIndexBuilder.php`
+- `src/Knowledge/Retrieval/NdjsonKeywordRetriever.php`
+- `src/Knowledge/Retrieval/NdjsonChunkLookup.php`
+- `src/Knowledge/Retrieval/NdjsonHybridRetriever.php`
+
+## Inhalt
+
+### AgentRunner
+
+Externalisiert wurden insbesondere:
+
+- Placeholder-Ausgaben der Query-/Input-Normalisierung
+- Shop-Repair-/Shop-Query-Heartbeat-Meldungen
+- No-LLM-Produktfeldtexte und Produktzeilen-Templates
+- Follow-up-Kontextlabels
+- Production-UI-Stage-Labels
+- Production-UI-Confidence-Labels
+- Production-UI-Texte, Templates und Shop-Meta-Labels
+- Follow-up-Action-Chips fuer Commerce und Knowledge
+
+Zusaetzlich nutzt der Runner vorhandene Language-Cleanup-Konfiguration fuer ASCII-Transliteration, Separator-Normalisierung und Dash-Normalisierung.
+
+### Language Cleanup
+
+`language.yaml` enthaelt nun zusaetzlich zentrale Normalisierungsregeln fuer:
+
+- Wortseparatoren (`-`, `/`, `_`)
+- Unicode-Dash-Aequivalente
+
+`LanguageCleanupConfig` stellt dafuer zentrale Methoden bereit:
+
+- `replaceWordSeparatorsWithSpace()`
+- `normalizeDashEquivalents()`
+
+### PromptBuilder
+
+Externalisiert wurden verbliebene Prompt-/Policy-Regeln rund um:
+
+- Fallback-Escalation bei vorhandenen Shop-Ergebnissen
+- Measurement-Evidence-Guard-Templates
+- finale Measurement-Evidence-Regeln
+- Parameter-Split-Pattern
+- Parameter-Trim-Zeichen
+
+Die Unicode-Dash-Normalisierung nutzt nun ebenfalls `LanguageCleanupConfig`.
+
+### Retrieval-Normalisierung
+
+Wiederholte Separatorlisten in Retrieval-Klassen wurden durch die zentrale Language-Cleanup-Methode ersetzt.
+
+Betroffen:
+
+- `QueryCleaner`
+- `NdjsonLexicalIndexBuilder`
+- `NdjsonKeywordRetriever`
+- `NdjsonChunkLookup`
+- `NdjsonHybridRetriever`
+
+## Bewusst nicht externalisiert
+
+Nicht Ziel dieses Patches waren rein technische Infrastrukturwerte, z. B.:
+
+- Boolean-Parser-Werte wie `true`, `false`, `yes`, `no`, `on`, `off`
+- technische Statuscodes und interne State-Keys
+- DTO-/Array-Schluessel
+- Log-/HTTP-/Encoding-Infrastruktur
+- Zeilenumbruch-Normalisierung
+
+Diese Werte sind keine fachlichen oder sprachlichen Matching-/Prompt-/UI-Listen.
+
+## Lokale Validierung
+
+Da im ZIP kein `vendor/` enthalten ist, konnten Symfony-Console-Checks nicht direkt ausgefuehrt werden.
+
+Durchgefuehrt wurden:
+
+- `php -l` fuer alle geaenderten PHP-Dateien: OK
+- YAML-Parse fuer geaenderte YAML-Dateien: OK
+- statische Greps auf die zuvor identifizierten Reststellen: OK
+
+Gepruefte ehemalige Problemklassen:
+
+- keine PHP-Funde mehr fuer `normalized user input` / `corrected user input`
+- keine PHP-Funde mehr fuer die harten Measurement-Evidence-Regeltexte
+- keine PHP-Funde mehr fuer die alten Separatorlisten `['-', '/', '_']`
+- keine PHP-Funde mehr fuer die alten Unicode-Dash-Listen
+- keine PHP-Funde mehr fuer die AgentRunner-UI-Labels wie `RetrieX-Status`, `Datenbasis`, `Folgeaktionen`, `Artikelnummer`, `Preis`, `Verfuegbarkeit`, `Relevanz`
+
+## Empfohlene Checks nach Einspielen
+
+Bitte im echten Projekt mit installiertem `vendor/` ausfuehren:
+
+```bash
+bin/console mto:agent:config:validate
+bin/console mto:agent:regression:test
+bin/console mto:agent:config:audit-source --details
+bin/console mto:agent:config:audit-patterns --details
+```
+