diff --git a/COMMAND_REF.md b/COMMAND_REF.md index da4d93c..d10f336 100644 --- a/COMMAND_REF.md +++ b/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` diff --git a/DEVELOPER_POLICIES.md b/DEVELOPER_POLICIES.md new file mode 100644 index 0000000..a0dbc12 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 7832376..092e6b0 100644 --- a/README.md +++ b/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 \ No newline at end of file +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. diff --git a/RETRIEX_PATCH_12_DEVELOPER_POLICIES_README.md b/RETRIEX_PATCH_12_DEVELOPER_POLICIES_README.md new file mode 100644 index 0000000..ca333d9 --- /dev/null +++ b/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.