p59

patch_history/RETRIEX_PATCH_59A_GENRE_NATIVE_SOURCEPATH_CLEANUP_README.md

@@ -0,0 +1,109 @@
+# RetrieX Patch 59A - Genre Native Source Path Cleanup
+
+## Ziel
+
+Dieser Patch startet die kontrollierte Aufraeumphase nach der Genre-Zentralisierung.
+Er entfernt leere Legacy-`source_paths` aus `config/retriex/genre.yaml`, ohne eingefrorene
+nicht-leere Fallbacks, Runtime-Resolved-Pfade oder fachliche Runtime-Logik zu veraendern.
+
+## Hintergrund
+
+Nach p58 ist `genre.yaml` fuer viele fachliche Werte bereits die zentrale Pflegeflaeche.
+Die alten YAML-Pfade wurden aber noch als leere Legacy-Fallbacks in
+`genre.configuration_values.*.source_paths` mitgefuehrt. Diese Referenzen sind fuer die
+fachliche Pflege nicht mehr notwendig und erzeugen unnoetige Audit-/Migrationslast.
+
+## Aenderungen
+
+### `config/retriex/genre.yaml`
+
+- 92 leere Legacy-`source_paths` wurden entfernt.
+- 30 Value-Nodes, die dadurch keine Legacy-Quelle mehr brauchen, wurden mit
+  `origin: genre_native` markiert.
+- Gemischte Nodes behalten weiterhin ihre nicht-leeren/frozen Source-Pfade.
+- Nicht-leere frozen Fallbacks bleiben unveraendert.
+- Runtime-Resolved-Pfade bleiben unveraendert:
+  - `commerce.max_shop_results`
+  - `commerce.store_api_base_url`
+
+### `src/Config/GenreSourceOfTruthGuard.php`
+
+- Der Guard erlaubt nun `origin: genre_native` als explizite native Herkunft fuer
+  `genre.configuration_values`-Nodes.
+- `origin` wird als Metadatenfeld behandelt, analog zu `source_paths` und `description`.
+- Native Nodes zaehlen als abgedeckt und muessen keine Legacy-`source_paths` mehr deklarieren.
+- Die Guard-Summary enthaelt zusaetzlich `genre_native_value_nodes`.
+
+## Bewusst nicht geaendert
+
+- Keine Aenderung an Retrieval-, Prompt-, Scoring-, Commerce- oder Shopware-Runtime-Logik.
+- Keine neuen fachlichen Token-/Stringlisten im PHP-Core.
+- Keine Entfernung der eingefrorenen nicht-leeren Fallbacks.
+- Keine Entfernung technischer Runtime-Pfade.
+- Keine Bereinigung der `adaptation_surface`-Inventarlisten; diese sollten separat klassifiziert werden.
+
+## Ergebnis der lokalen Strukturpruefung
+
+Vor Patch:
+
+- 131 deklarierte `source_paths` in `genre.configuration_values`
+- 92 davon zeigten auf leere Legacy-Fallbacks
+- 39 zeigten auf nicht-leere/frozen bzw. Runtime-resolved Werte
+
+Nach Patch:
+
+- 39 deklarierte `source_paths`
+- 0 leere Legacy-`source_paths`
+- 30 `genre_native` Value-Nodes
+- 0 Coverage-Fehler in der lokalen Guard-Simulation
+- 0 fehlende frozen Source-Pfade
+- 0 frozen Hash-Mismatches in der lokalen Guard-Simulation
+
+## Lokale Checks
+
+Ausgefuehrt im entpackten Patch-Arbeitsstand:
+
+```bash
+php -l src/Config/GenreSourceOfTruthGuard.php
+php -l src/Config/GenreConfig.php
+php -l src/Config/RetriexEffectiveConfigProvider.php
+```
+
+Alle PHP-Lints waren erfolgreich.
+
+Zusaetzlich wurde `config/retriex/genre.yaml` mit PyYAML geparst und eine lokale
+Guard-Simulation fuer Source-Path-Abdeckung, leere Legacy-Pfade und frozen Hashes ausgefuehrt.
+
+## Nicht lokal ausfuehrbar
+
+Die Symfony-Console-Checks konnten in der bereitgestellten ZIP nicht ausgefuehrt werden,
+da `vendor/` fehlt:
+
+```text
+Dependencies are missing. Try running "composer install".
+```
+
+Bitte im vollstaendigen Projekt mit Dependencies 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
+```
+
+## Erwartete Audit-Auswirkung
+
+`genre_value_paths_with_source_paths` und `genre_declared_source_paths` sollten sinken,
+weil leere Legacy-Referenzen entfernt wurden. Das ist beabsichtigt.
+
+`legacy_fallback_empty` sollte im Genre-Source-of-Truth-Guard auf 0 fallen.
+`genre_native_value_nodes` sollte die nativ markierten Value-Nodes ausweisen.
+
+## Naechster moeglicher Patch
+
+p59B sollte die `adaptation_surface`-Inventarlisten separat klassifizieren:
+
+- Welche Pfade sind weiterhin technische Review-/Audit-Inventare?
+- Welche leeren Legacy-Pfade koennen auch aus der Surface-Liste entfernt werden?
+- Welche nicht-leeren frozen Pfade bleiben bewusst technische Fallbacks?