p61

RETRIEX_PATCH_61_GENRE_SOURCE_OF_TRUTH_GUARD_README.md

@@ -0,0 +1,141 @@
+# RetrieX Patch p61 - Genre Source-of-Truth Guard
+
+## Ziel
+
+p61 schliesst die Genre-Source-of-Truth-Arbeit nach p59/p60/p60b ab.
+
+Der Patch verschiebt keine fachlichen Werte mehr. Stattdessen erzwingt er per Validate/Audit, dass `genre.yaml` die zentrale Pflegequelle fuer genreabhaengige Werte bleibt und Legacy-Pfade nur noch als leere oder explizit eingefrorene Fallbacks dienen.
+
+## Umfang
+
+Geaendert bzw. ergaenzt:
+
+- `config/retriex/governance.yaml`
+- `src/Config/GenreSourceOfTruthGuard.php`
+- `src/Config/RetriexEffectiveConfigProvider.php`
+- `src/Config/ConfigSourceAuditProvider.php`
+- `src/Command/ConfigSourceAuditCommand.php`
+
+## Was der Guard prueft
+
+### 1. Vollstaendige Genre-Werte
+
+`genre.configuration_values` muss eine nicht-leere Map sein.
+
+Fuer jede Gruppe in `genre.adaptation_surface` muss eine entsprechende Gruppe in `genre.configuration_values` existieren.
+
+### 2. Source-Path-Abdeckung
+
+Genre-Wertknoten mit direkter Payload muessen selbst `source_paths` deklarieren oder von einem Parent-Knoten mit `source_paths` abgedeckt sein.
+
+`source_paths` muessen nicht-leere Strings sein und duerfen innerhalb eines Wertknotens nicht doppelt vorkommen.
+
+### 3. Gueltige Source-Pfade
+
+Alle `source_paths` werden gegen die effektive bzw. roh geladene RetrieX-Konfiguration validiert.
+
+Unbekannte Source-Pfade erzeugen jetzt einen Validate-Fehler.
+
+### 4. Legacy-Fallbacks sind leer oder eingefroren
+
+Fuer jeden deklarierten Source-Pfad gilt:
+
+- leerer Legacy-Wert: OK, Status `legacy_fallback_empty`
+- runtime-/env-aufgeloester Pfad: OK, Status `legacy_runtime_resolved_allowed`
+- nicht-leerer Legacy-Wert mit passendem Hash: OK, Status `legacy_frozen_non_empty`
+- nicht-leerer Legacy-Wert ohne registrierten Hash: Fehler
+- nicht-leerer Legacy-Wert mit abweichendem Hash: Fehler
+
+Damit brechen Validate/Audit, wenn neue fachliche Listen wieder ausserhalb von `genre.yaml` landen oder eingefrorene Legacy-Werte veraendert werden.
+
+## Warum eingefrorene Fallback-Hashes?
+
+Einige Legacy-Pfade enthalten weiterhin technische Fallback-/Wiring-Werte oder noch nicht entfernte Legacy-Defaults, die im aktuellen gruenen Stand nicht geloescht werden sollten. p61 friert diese Werte per SHA-256-Hash ein.
+
+Dadurch bleibt der aktuelle Stand kompatibel, aber kuenftige Aenderungen an diesen Legacy-Pfaden muessen bewusst ueber `genre.yaml` erfolgen.
+
+## Audit-Ausgabe
+
+`mto:agent:config:audit-source --details` zeigt zusaetzlich:
+
+- `genre_source_of_truth_violations`
+- `genre_source_of_truth_fallback_empty`
+- `genre_source_of_truth_frozen_non_empty`
+- Detailtabelle `Genre source-of-truth guard`
+
+Die Detailtabelle zeigt pro Genre-Wert:
+
+- Genre value path
+- Legacy/effective source path
+- State
+- Hash
+
+## Validate-/Audit-Verhalten
+
+`mto:agent:config:validate` fuehrt den Guard aus und gibt Fehler aus, wenn die Source-of-Truth-Regeln verletzt sind.
+
+`mto:agent:config:audit-source` gibt bei Source-of-Truth-Fehlern jetzt `Command::FAILURE` zurueck.
+
+## Lokale Checks
+
+Ausgefuehrt:
+
+```bash
+php -l src/Config/GenreSourceOfTruthGuard.php
+php -l src/Config/RetriexEffectiveConfigProvider.php
+php -l src/Config/ConfigSourceAuditProvider.php
+php -l src/Command/ConfigSourceAuditCommand.php
+```
+
+Alle PHP-Lints: OK.
+
+```bash
+python3 - <<'PY'
+# YAML parse config/retriex/*.yaml
+PY
+```
+
+YAML parse: OK.
+
+Zusatzcheck:
+
+- Source-of-Truth-Guard-Simulation gegen den aktuellen Stand: 0 Fehler
+- Ergebnisstatus der Simulation: leer/frozen/runtime erlaubt
+
+Nicht lokal ausfuehrbar:
+
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:regression:test
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+```
+
+Grund:
+
+Das ZIP enthaelt kein `vendor/`.
+
+Fehler:
+
+```text
+Dependencies are missing. Try running "composer install".
+```
+
+## Empfohlene Checks nach Einspielen
+
+```bash
+bin/console cache:clear
+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
+```
+
+## Abschlussbild
+
+Nach p61 gilt:
+
+- `genre.yaml` ist die zentrale fachliche Source of Truth.
+- Legacy-YAMLs sind technische Verarbeitungsschichten bzw. leere/eingefrorene Fallbacks.
+- Neue fachliche Listen ausserhalb von `genre.yaml` werden durch Validate/Audit verhindert.
+- Technische Runtime-/Model-/Vector-/Index-Konfiguration bleibt weiterhin ausserhalb von `genre.yaml`.