diff --git a/patch_history/RETRIEX_PATCH_43S_FINAL_CONFIG_AUDIT_FREEZE_README.md b/patch_history/RETRIEX_PATCH_43S_FINAL_CONFIG_AUDIT_FREEZE_README.md new file mode 100644 index 0000000..f9604d8 --- /dev/null +++ b/patch_history/RETRIEX_PATCH_43S_FINAL_CONFIG_AUDIT_FREEZE_README.md @@ -0,0 +1,154 @@ +# RetrieX Patch 43S - Final Config Audit / Freeze Documentation + +## Ziel + +p43S schließt die p43 YAML-Maps-/Listen-Konsolidierungsreihe mit einem dokumentierten Freeze ab. + +Der Patch setzt auf dem grün bestätigten p43R-Stand auf und nimmt bewusst **keine Runtime-Änderung** mehr vor. Ziel ist, den erreichten Zustand zu dokumentieren und die verbleibenden YAML-Listen/Maps zu klassifizieren, damit zukünftige Änderungen nicht erneut unsystematisch lokale Listen oder harte Core-Begriffe einführen. + +## Änderungen + +### Dokumentation ergänzt + +Neu: + +- `patch_history/RETRIEX_PATCH_43S_FINAL_CONFIG_AUDIT_FREEZE_README.md` +- `patch_history/RETRIEX_PATCH_43S_FINAL_YAML_LIST_MAP_INVENTORY.md` + +## Keine Runtime-Dateien geändert + +p43S ändert bewusst keine der folgenden Bereiche: + +- kein PHP-Code +- keine fachliche Runtime-Logik +- keine Scoringänderung +- keine Retrievaländerung +- keine Prompt-Regeländerung +- keine Admin-UI +- keine neuen harten fachlichen Listen im PHP-Core +- keine YAML-Werte in produktiver Config geändert + +## Bestätigte p43-Reihe im aktuellen Stand + +Im aktualisierten `rag-inprogress.zip` sind die folgenden p43-Schritte enthalten: + +- p43A / p43A2 - Config Reduction / Vocabulary-View-Fallbacks +- p43B - ProductRoleResolver +- p43C - ReferenceAnchorExtractor +- p43D - Prompt Role Vocabulary Consolidation +- p43E - Direct Attribute Vocabulary View +- p43F - SearchRepair Accessory Code Vocabulary View +- p43G - Measurement Evidence Context Fallback +- p43H - Rag Evidence Synonym Vocabulary Map +- p43I - Input Normalization Fuzzy Routing Vocabulary View +- p43J - Governance Protected Short Model Fallback +- p43K - Governance Required Profile Defaults +- p43L - Language Cleanup Protected Term Default +- p43M - Vocabulary Map Alias Dedup +- p43N - Language Cleanup Group Sets +- p43O - Prompt Measurement Evidence Vocabulary Maps +- p43P - Prompt Measurement Evidence Duplicate Warning Cleanup +- p43Q - Agent Term Vocabulary View Consolidation +- p43R - Prompt Measurement Context Vocabulary Views + +## Audit-Ergebnis + +Der aktuelle Stand hat die zuvor geplante YAML-Maps-/Listen-Optimierung weitgehend ausgeschöpft. + +Die verbleibenden Listen/Maps fallen in diese Kategorien: + +### Zentralisiert / View-basiert + +Diese Bereiche sind jetzt über zentrale `vocabulary_views`, `vocabulary_maps`, Map-Aliase oder Language-Group-Sets geführt: + +- Agent-Termlisten für Follow-up, No-LLM-Fallback, Shop-Prompt und Input-Normalisierung +- SearchRepair-Terme für Direct-Attribute-, Accessory-Code- und Candidate-Handling +- Prompt-Rollenbegriffe und Measurement-Evidence-Terme +- Shop-/Accessory-Fokus-Varianten +- RAG-Evidence-Synonyme +- Language-Cleanup-Basisgruppen über `group_sets` +- Governance-Fallbacks für bewusst gleiche Baselines + +### Bewusst lokal + +Diese YAML-Inhalte bleiben bewusst lokal, weil sie nicht bloß Vocabulary-Daten sind: + +- Prompt-Regeltexte und Antwort-/Formatierungsregeln in `prompt.yaml` +- Regex-/Pattern-Regeln, die konkrete Guardrail-Logik ausdrücken +- parameternahe Sonderkontexte wie pH-spezifische negative Measurement-Kontextbegriffe +- Intent-/Routing-Pattern in `intent.yaml` +- Governance-/Regression-Baselines, die unabhängig auditierbar bleiben sollen +- Language-Cleanup-Profile, wo die Profilstruktur selbst Pflegeinformation ist + +### Bewusst nicht weiter konsolidiert + +Folgende identische oder ähnliche Listen wurden im Audit gesehen, aber nicht weiter verschoben: + +1. `governance.regression_baseline.protected_short_model_tokens` und `vocabulary.views.retrieval.important_short_model_tokens` + - bleiben getrennt, weil die Governance-Regression eine unabhängige Guardrail-Baseline sein soll. + +2. `vocabulary.maps.prompt.measurement_evidence_guard.request_terms.redox` und `vocabulary.maps.agent.rag_evidence_guard.synonyms.values.redox_terms` + - bleiben getrennt, weil Prompt-Measurement-Request-Terme und RAG-Evidence-Synonyme unterschiedliche Domänenverwendungen haben, auch wenn die aktuelle Wertemenge identisch ist. + +3. `vocabulary.maps.prompt.measurement_evidence_guard.request_terms.ph` und `vocabulary.maps.agent.rag_evidence_guard.synonyms.values.ph_terms` + - bleiben getrennt aus demselben Grund: unterschiedliche semantische Domänen, keine Cross-Map-Abhängigkeit erzwingen. + +4. `governance.regression_baseline.protected_accessory_prompt_keywords` und `governance.regression_baseline.protected_retrieval_reagent_words` + - bleiben getrennt, weil sie verschiedene Guardrail-Baselines absichern. + +## Freeze-Regeln für zukünftige Änderungen + +Nach p43S gelten für weitere YAML-/Listen-Arbeiten: + +1. Neue fachliche, sprachliche, UI-nahe, Prompt-, Retrieval-, Shop-, Intent- oder Guardrail-Listen nicht im PHP-Core hart codieren. +2. Neue Begriffslisten bevorzugt in `vocabulary.yaml`, `language.yaml` oder der passenden Domain-YAML pflegen. +3. Lokale Listen nur dann verwenden, wenn sie echte lokale Semantik ausdrücken, z. B. Prompt-Regel, Regression-Baseline, Profilstruktur oder Domain-spezifische Override-Fläche. +4. Bei weiterer Konsolidierung immer effektive Werte vor/nach Patch vergleichen. +5. Governance-Baselines nicht aus denselben Views ableiten, die sie absichern sollen. +6. Prompt-Regeltexte nicht in Vocabulary-Views verschieben; Vocabulary ist für Begriffe/Listen/Maps, nicht für Prompt-Verhalten. +7. Keine Cross-Domain-Map-Aliase erzwingen, wenn zwei aktuell identische Listen unterschiedliche fachliche Bedeutungen haben. + +## Empfohlener Abschlussstatus + +Mit p43S ist die aktuelle Optimierungsreihe abgeschlossen. + +Weitere Arbeiten sollten nur gestartet werden, wenn ein konkretes neues Ziel vorliegt, z. B.: + +- neue Accuracy-/Regression-Anforderung +- konkrete Audit-Warnung +- konkret duplizierte Liste mit gleicher Domänenbedeutung +- Performance-/Stabilitätsproblem +- Admin-/Pflegeoberflächen-Thema + +Ohne neues Ziel sollte die p43 YAML-Maps-/Listen-Optimierungsserie hier eingefroren werden. + +## Lokale Prüfungen + +Ausgeführt: + +```bash +php -l src/Config/AgentRunnerConfig.php +php -l src/Config/PromptBuilderConfig.php +php -l src/Config/SearchRepairConfig.php +php -l src/Config/DomainVocabularyConfig.php +php -l src/Config/LanguageCleanupConfig.php +php -l src/Config/GovernanceConfig.php +python3 YAML parse check for config/retriex/*.yaml +python3 p43 patch-history presence check +python3 duplicate-list audit for remaining intentional duplicates +zip -T retriex_p43s_final_config_audit_freeze_patch_only.zip +``` + +Alle lokal ausführbaren Prüfungen waren grün. + +Nicht lokal ausführbar: + +```bash +bin/console c:cl +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 +``` + +Grund: Der ZIP-Stand enthält lokal kein `vendor/`; `bin/console` bricht in der Artefaktumgebung mit fehlenden Dependencies ab. diff --git a/patch_history/RETRIEX_PATCH_43S_FINAL_YAML_LIST_MAP_INVENTORY.md b/patch_history/RETRIEX_PATCH_43S_FINAL_YAML_LIST_MAP_INVENTORY.md new file mode 100644 index 0000000..c4f2286 --- /dev/null +++ b/patch_history/RETRIEX_PATCH_43S_FINAL_YAML_LIST_MAP_INVENTORY.md @@ -0,0 +1,141 @@ +# RetrieX p43S - Final YAML List / Map Inventory + +Dieses Inventar dokumentiert den Stand nach p43R und p43S. Es ist bewusst dokumentarisch und verändert keine Runtime-Konfiguration. + +## Zweck + +Die p43-Serie hat zentrale Begriffslisten, Maps und Cleanup-Gruppen aus lokalen Domain-YAMLs in zentrale Pflegebereiche überführt: + +- `config/retriex/vocabulary.yaml` +- `config/retriex/language.yaml` +- gezielte Domain-YAMLs mit lokalen Overrides + +Dieses Inventar hält fest, welche Bereiche ab jetzt als zentralisiert gelten und welche Bereiche bewusst lokal bleiben. + +## Zentralisierte Pflegebereiche + +### Vocabulary-Views + +Verwendet für reine Begriffslisten, die von Agent-, Prompt-, Retrieval-, SearchRepair-, Commerce- oder Shop-Config gelesen werden. + +Beispiele: + +- `agent.input_normalization_fuzzy_routing_terms` +- `agent.follow_up_context.commercial_table_follow_up.table_terms` +- `agent.no_llm_fallback.product_roles.main_device_request_keywords` +- `agent.no_llm_fallback.product_roles.accessory_product_keywords` +- `agent.shop_prompt.current_input_preservation_terms` +- `agent.shop_prompt.context_anchor_enrichment.trigger_terms` +- `search_repair.direct_product_type_terms` +- `search_repair.direct_product_attribute_stop_terms` +- `search_repair.requested_accessory_code_terms` +- `search_repair.model_candidate_exclude_terms` +- `prompt.measurement_evidence_guard.accessory_lookup_guard_terms` +- `prompt.measurement_evidence_guard.accessory_lookup_passthrough_terms` +- `prompt.measurement_evidence_guard.generic_positive_context_terms` +- `prompt.measurement_evidence_guard.generic_negative_context_terms` + +### Vocabulary-Maps + +Verwendet für key-basierte Synonyme oder Parameterlisten. + +Beispiele: + +- `agent.rag_evidence_guard.synonyms` +- `shop.accessory_focus_variants` +- `prompt.measurement_evidence_guard.request_terms` +- `prompt.measurement_evidence_guard.positive_terms` +- `prompt.measurement_evidence_guard.non_equivalent_terms` + +### Vocabulary-Map-Aliase + +Map-Aliase sind erlaubt, wenn mehrere Keys wirklich dieselbe Wertemenge innerhalb derselben Map-Domäne verwenden. + +Beispiele: + +- Salinität-Aliase in `agent.rag_evidence_guard.synonyms` +- Redox/ORP-Aliase in `agent.rag_evidence_guard.synonyms` +- Varianten in `shop.accessory_focus_variants` + +Nicht empfohlen sind Cross-Domain-Aliase zwischen fachlich unterschiedlichen Maps, selbst wenn aktuell dieselben Werte vorkommen. + +### Language-Group-Sets + +Verwendet für gemeinsame Cleanup-Basisgruppen. + +Beispiele: + +- `stopword_groups.de_conversation` +- `phrase_groups.user_instruction` +- Cleanup-Profile mit `stopword_group_sets` und `phrase_group_sets` + +## Bewusst lokale Bereiche + +### Prompt-Regeln + +Prompt-Regeltexte bleiben in `prompt.yaml`, weil sie Verhalten ausdrücken, nicht bloß Vocabulary. + +Beispiele: + +- `measurement_evidence_guard.intro_rules` +- `measurement_evidence_guard.product_specific_rules` +- `measurement_evidence_guard.final_rules` +- `output_priority.rules` +- `fallback_escalation.*` +- Antwortformat- und Quellenregeln + +### Regex- und Pattern-Regeln + +Regex-Listen bleiben dort, wo sie die jeweilige Domain-Logik ausdrücken. + +Beispiele: + +- Prompt Role Guard Patterns +- Measurement Generic Request Patterns +- Numeric Value Focus Patterns +- Intent-/Routing-Patterns + +### Governance-/Regression-Baselines + +Regression- und Governance-Baselines bleiben unabhängig, damit sie nicht dieselbe Quelle validieren, die sie absichern sollen. + +Beispiele: + +- `regression_baseline.protected_short_model_tokens` +- Accessory-/Reagent-Guardrail-Baselines + +### Parameternahe Sonderkontexte + +Parameternahe Kontextlisten bleiben lokal, wenn sie bewusst Schreibvarianten oder Prompt-Matching-Nuancen enthalten. + +Beispiel: + +- pH-spezifische `negative_context_terms` im Measurement-Evidence-Parameterblock + +## Verbleibende bewusst akzeptierte Duplikate + +| Bereich | Grund für Beibehaltung | +| --- | --- | +| Governance protected short model tokens vs. retrieval important short model tokens | unabhängige Guardrail-Baseline | +| Prompt request terms für pH/Redox vs. RAG-Evidence-Synonyme | unterschiedliche Domain-Semantik | +| Governance accessory prompt keywords vs. retrieval reagent words | unterschiedliche Regression-Baselines | + +## Pflegeleitlinie nach p43S + +Neue Listen sollen erst klassifiziert werden: + +1. Reine Begriffe, Synonyme oder Varianten? → `vocabulary.yaml` +2. Sprachbereinigung / Cleanup-Profil? → `language.yaml` +3. Prompt-Verhalten, Antwortregel oder Formatregel? → lokale Prompt-Config +4. Regression-/Governance-Schutz? → lokale Governance-Config +5. Domain-spezifischer Override? → lokale Domain-YAML mit optionalem Vocabulary-Fallback + +Vor Merge immer prüfen: + +```bash +bin/console c:cl +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 +```