patch 12

COMMAND_REF.md

@@ -16,6 +16,10 @@ Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die vera
 | `mto:agent:ingest:version` | Ingest | Startet einen Ingest für eine konkrete Dokumentversion |
 | `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
 | `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload |
+| `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
+| `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
+| `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
+| `mto:agent:regression:test` | Config / Governance | Fuehrt Offline-Regression-Guards fuer stabile Pfade aus |
 | `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
 | `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
 | `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
@@ -480,9 +484,71 @@ Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche
 
 ---
 
-## 11. Fazit
 
-Der aktuelle Custom-CLI-Umfang des Systems besteht aus **14 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
+## 11. Config-Governance / YAML-only Guardrails
+
+These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths.
+
+### `mto:agent:config:validate`
+
+Validates the effective RetrieX configuration.
+
+**Signature**
+```bash
+bin/console mto:agent:config:validate [--json]
+```
+
+**Expected result before merge**
+- status `OK`
+- no errors
+
+### `mto:agent:config:audit-source`
+
+Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.
+
+**Signature**
+```bash
+bin/console mto:agent:config:audit-source [--details] [--json]
+```
+
+**Expected result before merge**
+- no missing YAML mappings
+- no new undocumented PHP-only semantic constants
+- no constructor defaults without YAML/service-parameter mapping
+
+Use `--details` for reviewable console output and `--json` for machine-readable CI output.
+
+### `mto:agent:config:dump-effective`
+
+Dumps the effective RetrieX configuration inventory.
+
+**Signature**
+```bash
+bin/console mto:agent:config:dump-effective [--summary]
+```
+
+Use `--summary` for a compact review view.
+
+### `mto:agent:regression:test`
+
+Runs offline regression guards for stable configuration paths.
+
+**Signature**
+```bash
+bin/console mto:agent:regression:test [--json]
+```
+
+**Expected result before merge**
+- status `OK`
+- all checks pass
+
+This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.
+
+---
+
+## 12. Fazit
+
+Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens **18 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
 
 - `mto:agent:ingest:run`
 - `mto:agent:system:rebuild`

DEVELOPER_POLICIES.md

@@ -0,0 +1,125 @@
+# RetrieX Developer Policies
+
+Status: binding after completion of the YAML-only migration through Patch 11.0a.
+
+These policies protect the stable RetrieX configuration architecture. They are intentionally operational and must be followed by developers before a change is merged.
+
+## 1. Source of truth
+
+The functional configuration source of truth is YAML under `config/retriex/`.
+
+This applies especially to:
+
+- vocabulary, synonyms, stopwords and token lists
+- intent rules and commerce routing
+- search repair and query enrichment rules
+- prompt texts, labels, output-priority rules and grounding rules
+- agent messages, source labels, status messages and templates
+- retrieval thresholds, token groups and scoring-related rule lists
+- shop matching and commerce query parsing rules
+- model and index defaults
+
+PHP classes may read and validate these values, but must not silently redefine them.
+
+## 2. No new PHP-only defaults
+
+New configurable values must be added in YAML first.
+
+Required pattern:
+
+1. Add the value to the matching file in `config/retriex/`.
+2. Wire the value through `config/services.yaml` when constructor injection is needed.
+3. Expose/read it through the matching `src/Config/*Config.php` class.
+4. Keep `mto:agent:config:validate` green.
+5. Keep `mto:agent:config:audit-source --details` free of missing YAML mappings.
+
+Not allowed:
+
+- new constructor defaults that act as business or answer logic
+- new hardcoded keyword lists in `src/`
+- new PHP-only constants for semantic or product-specific behavior
+- hidden fallbacks that change retrieval, prompt, shop or intent behavior when YAML is incomplete
+
+## 3. Allowed technical constants
+
+Technical constants are allowed only when they are not business, prompt, retrieval, product, intent or shop semantics.
+
+Examples that may be acceptable:
+
+- internal status strings
+- command exit handling
+- filesystem mode details
+- non-semantic implementation identifiers
+
+If a constant influences answer quality, matching, routing, scoring, prompt behavior or shop behavior, it belongs in YAML.
+
+## 4. Fallback policy
+
+Fallbacks are not a normal extension mechanism.
+
+A fallback is only acceptable when all conditions are met:
+
+- the value has a YAML path or explicit service-parameter mapping
+- the fallback is documented as defensive infrastructure behavior
+- the audit does not report it as missing YAML mapping
+- the fallback cannot change semantic answer behavior in normal operation
+
+If in doubt, move the value to YAML.
+
+## 5. Required checks before merge
+
+Every change touching `src/Config`, `config/retriex`, prompt, retrieval, intent, commerce, shop matching, SSE/job completion or answer grounding must run:
+
+```bash
+php bin/console cache:clear
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:regression:test
+```
+
+Expected result:
+
+- config validation: OK
+- regression baseline: OK
+- source audit: no missing YAML mappings
+- no new undocumented PHP-only semantic constants
+- no new constructor defaults without YAML/service-parameter mapping
+
+## 6. Protected regression baseline
+
+The following behavior must not regress:
+
+- lowest water-hardness limit remains `0,02 deg dH` for Testomat 808
+- follow-up indicator answer remains focused on indicator type 300
+- accessory price follow-up for indicator type 300 returns the matching indicator products, not device prices
+- history-based shop follow-up such as `suche im shop` keeps the relevant product context
+- advisory product questions may use shop/catalog fallback when RAG knowledge is insufficient
+- SSE/job completion must close loader/think states reliably, including reconnect/watchdog cases
+
+Offline checks are covered by `mto:agent:regression:test`. End-to-end behavior still needs manual or integration verification when the touched code path is not covered offline.
+
+## 7. Strict YAML validation
+
+Strict YAML validation remains intentionally deferred.
+
+Until a later patch explicitly enables it, developers must enforce these policies through:
+
+- code review
+- `mto:agent:config:validate`
+- `mto:agent:config:audit-source --details`
+- `mto:agent:regression:test`
+
+Strict mode must remain configurable and disabled by default when it is introduced later.
+
+## 8. Pull request checklist
+
+Use this checklist for every relevant PR:
+
+- [ ] All new configurable behavior is in `config/retriex/*.yaml`.
+- [ ] No new semantic keyword/token/prompt list was added directly to PHP.
+- [ ] No new constructor default was added without YAML/service-parameter mapping.
+- [ ] `mto:agent:config:validate` is OK.
+- [ ] `mto:agent:config:audit-source --details` has no missing YAML mappings.
+- [ ] `mto:agent:regression:test` is OK.
+- [ ] The protected functional flows were manually checked if the touched area can affect them.
+- [ ] README or patch README documents the reason for any intentionally accepted technical fallback.

README.md

@@ -471,6 +471,10 @@ Verifizierte relevante Commands im aktuellen Stand:
 - `mto:agent:tags:job:run`
 - `mto:agent:tag:health`
 - `mto:agent:system:rebuild`
+- `mto:agent:config:validate`
+- `mto:agent:config:audit-source`
+- `mto:agent:config:dump-effective`
+- `mto:agent:regression:test`
 - `mto:agent:test:shop-search`
 - `mto:agent:test-vector`
 - `mto:agent:user:create`
@@ -481,4 +485,29 @@ Verifizierte relevante Commands im aktuellen Stand:
 
 ```bash
 bin/console mto:agent:vector:control --status
-bin/console mto:agent:vector:control --install --start --reload
+bin/console mto:agent:vector:control --install --start --reload
+
+```
+
+
+---
+
+## Developer Policies / Governance
+
+The YAML-only migration is treated as completed after Patch 11.0a, as long as these checks stay green:
+
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:regression:test
+```
+
+From now on, developers must follow `DEVELOPER_POLICIES.md`.
+
+Core rules:
+
+- YAML under `config/retriex/` is the source of truth for configurable behavior.
+- No new PHP-only semantic defaults, token lists, prompt texts, matching rules or business fallbacks.
+- New configurable behavior must be added through YAML and wired explicitly.
+- Regression-sensitive flows from the 1.4.2/1.5.0 baseline must remain protected.
+- Strict YAML validation is deferred and must remain disabled by default when introduced later.

RETRIEX_PATCH_12_DEVELOPER_POLICIES_README.md

@@ -0,0 +1,60 @@
+# RetrieX Patch 12 - Developer Policies after YAML-only Migration
+
+This patch does not continue the YAML-only migration and does not enable strict validation.
+
+Patch 1 through 11.0a are treated as the completed YAML-only migration baseline. Patch 12 documents the developer rules that must be followed from now on to prevent regressions and new PHP-only configuration drift.
+
+## Scope
+
+Changed files:
+
+- `DEVELOPER_POLICIES.md`
+- `README.md`
+- `COMMAND_REF.md`
+
+## What changed
+
+### Developer policies
+
+Added a binding policy document with rules for:
+
+- YAML as source of truth
+- no new PHP-only defaults
+- no hardcoded semantic lists in core code
+- fallback restrictions
+- mandatory pre-merge checks
+- protected regression baseline
+- deferred strict validation
+- PR checklist
+
+### README
+
+The README now points developers to `DEVELOPER_POLICIES.md` and lists the config-governance commands together with the other important commands.
+
+The previously open final bash code block in the README was also closed while appending the policy section.
+
+### Command reference
+
+`COMMAND_REF.md` now includes the existing config/governance commands:
+
+- `mto:agent:config:validate`
+- `mto:agent:config:audit-source`
+- `mto:agent:config:dump-effective`
+- `mto:agent:regression:test`
+
+## Intentional non-changes
+
+No PHP runtime behavior was changed.
+No retrieval, prompt, shop, agent, SSE, audit or validation logic was changed.
+Strict YAML validation remains deferred and disabled.
+
+## Recommended validation
+
+```bash
+php bin/console cache:clear
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:regression:test
+```
+
+In this ZIP work environment, `vendor/` is not included, so Symfony console commands may need to be run in the real project checkout after dependencies are installed.