mitai-jinkendo/.claude/docs/audit/platzhalter/PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md

# Normative Standardspezifikation
## Placeholder-Metadaten, Exportverträge und Governance

**Version:** 1.0.0  
**Stand:** 29.03.2026  
**Status:** Verbindlicher Standard  
**Geltungsbereich:** Alle bestehenden, neuen und zukünftigen Platzhalter des Systems  

---

## 1. Normativer Status

Dieses Dokument ist **keine bloße Projektbeschreibung**, sondern eine **verbindliche Standardspezifikation** für das Placeholder-System.

Es gilt für:
- alle aktuell existierenden Platzhalter,
- alle künftig neu eingeführten Platzhalter,
- alle technisch abgeleiteten Exportformate,
- alle Prompt-, Pipeline- und Analyseverwendungen, die auf Placeholders zugreifen,
- alle künftigen Erweiterungen der Placeholder-Registry, des Data Layers und der Exportfunktionen.

### 1.1 Verbindlichkeit
Alle neuen und geänderten Placeholder-Implementierungen **müssen** dieser Spezifikation entsprechen. Abweichungen sind nur zulässig, wenn sie:
1. explizit dokumentiert,
2. versioniert,
3. mit `known_issues` und/oder `deprecated` markiert,
4. und in einem Gap- oder Decision-Log nachvollziehbar begründet werden.

### 1.2 Vorrang
Diese Spezifikation hat Vorrang vor:
- unvollständigen Altbeschreibungen,
- impliziten Verhaltensannahmen in Legacy-Prompts,
- nicht dokumentierten Exportkonventionen,
- informellen Teamabsprachen.

Wenn bestehender Code oder bestehende Exporte von dieser Spezifikation abweichen, ist die Abweichung als **Legacy-Zustand** zu markieren und über Versionierung/Deprecation zu behandeln.

---

## 2. Zielbild

Das System besitzt bereits einen funktionierenden Placeholder-Export und einen Data Layer als Single Source of Truth für Charts, Scores und KI-Platzhalter. Dieser Standard definiert, wie Placeholder künftig **semantisch, technisch und governance-seitig** beschrieben, exportiert und weiterentwickelt werden.

Jeder Placeholder muss als **stabiler, dokumentierter API-Vertrag** behandelbar sein.

Der Standard verlangt, dass zu jedem Placeholder mindestens folgende Ebenen eindeutig bestimmbar oder explizit als unbekannt markiert sind:

1. **Ist-Wert / Beispielwert**
2. **Technische Herkunft**
3. **Semantischer Vertrag**
4. **Fehlwert- und Ausnahmebehandlung**
5. **Qualitäts-/Confidence-Logik**
6. **Verwendungsnachweise**
7. **Versionierung / Deprecation / Nachfolger**

---

## 3. Verbindliche Architekturprinzipien

### 3.1 Placeholder = API-Vertrag
Placeholder sind keine lose Prompt-Hilfe, sondern **stabile API-Verträge**. Semantik, Einheit, Zeitfenster, Rückgabetyp und Fehlwertverhalten müssen dokumentiert und versioniert sein.

### 3.2 Non-breaking first
Bestehende Exporte und bestehende Placeholder-Namen dürfen nicht stillschweigend breaking geändert werden. Änderungen an Semantik, Zeitfenster, Einheit oder Rückgabetyp sind:
- entweder über neue Versionen,
- oder über neue Nachfolger-Platzhalter,
- oder über explizite Deprecation-Pfade
abzubilden.

### 3.3 JSON vor Freitext
Komplexe Metadaten, Rohdaten, strukturierte Diagnosen und technische Hinweise sind primär als JSON bereitzustellen. Freitext darf ergänzen, aber keine strukturierte Pflichtinformation ersetzen.

### 3.4 Zeitfenster explizit
Zeitbezogene Placeholder müssen ein explizites Zeitfenster tragen – mindestens als Metadatum. Legacy-Namen ohne eindeutiges Zeitfenster dürfen im Bestand fortbestehen, müssen aber als semantisch unpräzise markiert werden und einen empfohlenen Nachfolger erhalten.

### 3.5 Fehlwerte explizit
Fehlende Werte dürfen im strukturierten Export nicht nur als String wie `"nicht verfügbar"` modelliert werden. Verbindlich sind strukturierte Felder wie:
- `available`
- `value_raw`
- `missing_reason`
- `missing_value_policy`

### 3.6 Typisierung ist Pflicht
Jeder Placeholder muss einem Typ zugeordnet werden:
- `atomic`
- `raw_data`
- `interpreted`
- `legacy_unknown` (nur als Übergang)

### 3.7 Data Layer bleibt Single Source of Truth
Fachliche Berechnungen dürfen nicht im Exporter dupliziert oder neu erfunden werden. Der Exporter sammelt Metadaten und referenziert technische Herkunft; er ersetzt keine fachlichen Kernfunktionen.

### 3.8 Kein stilles Raten
Wenn technische Herkunft, Zeitfenster, Ausnahmebehandlung oder sonstige Metadaten nicht sicher aus dem Code bestimmbar sind, muss der Zustand als `unknown`, `not_resolved` oder `partially_resolved` markiert werden.

### 3.9 Zukunftsgeltung
Jeder neue Placeholder **muss vor produktivem Einsatz** in Registry, Export und Katalog vollständig gegen dieses Dokument validiert werden.

---

## 4. Geltungsbereich und Pflichtanwendung

### 4.1 Diese Spezifikation gilt für
- bestehende produktive Placeholder,
- neue Placeholder in aktiver Entwicklung,
- experimentelle Placeholder, sobald sie außerhalb eines reinen Dev-Modus verwendet werden,
- Placeholder in Multi-Stage-Pipelines,
- Placeholder in Reports, Dashboards, Prompt-Templates und Exporten.

### 4.2 Diese Spezifikation gilt auch für
- neue Goal-/Score-/Correlation-/Driver-Placeholder,
- künftige Trainingstyp-/Subcategory-Placeholder,
- Placeholder für Diagnose-, Risiko- und Recovery-Logik,
- technische Export-Erweiterungen,
- Two-Stage-Artefakte.

### 4.3 Nicht zulässig ohne Standardkonformität
Nicht zulässig ist:
- ein neuer Placeholder ohne dokumentierten Semantikvertrag,
- ein neuer Placeholder ohne Zeitfenster-Metadatum,
- ein strukturierter Placeholder ohne definierten Output-Typ,
- ein produktiver Placeholder ohne dokumentierte Fehlwertbehandlung,
- ein interpretierter Placeholder ohne Kennzeichnung als solcher.

---

## 5. Scope des technischen Auftrags

### 5.1 In Scope
Der Coding Agent soll:
1. alle existierenden Placeholder inventarisieren,
2. die Metadaten je Placeholder technisch erheben oder als unresolved markieren,
3. einen erweiterten Export erzeugen,
4. einen menschenlesbaren und maschinenlesbaren Katalog erzeugen,
5. die Katalog-/Exportstruktur so implementieren, dass sie **für alle zukünftigen Placeholder wiederverwendbar** ist,
6. Tests und Validierungen ergänzen,
7. Gap-Reports für nicht automatisch auflösbare Metadaten erzeugen.

### 5.2 Out of Scope
Nicht gefordert ist:
- sofortige komplette fachliche Neudefinition aller Legacy-Placeholder,
- sofortige Umbenennung aller problematischen Namen,
- Umsetzung aller in anderen Dokumenten vorgeschlagenen neuen Wunsch-Placeholder,
- Neuimplementierung des gesamten Prompt-Systems.

### 5.3 Zukunftsanforderung
Die technische Lösung muss so gebaut sein, dass **jeder zukünftige Placeholder** denselben Katalog- und Exportmechanismus automatisch oder mit minimalem Zusatzaufwand durchlaufen kann.

---

## 6. Ziel-Deliverables

### 6.1 Code / Export
1. **Erweiterter Placeholder-Export**
   - neuer Endpoint, CLI, Service-Funktion oder Exportmodus
   - Legacy-Export bleibt kompatibel
2. **Zentrales Metadatenmodell / Registry-Erweiterung**
   - wiederverwendbar für bestehende und zukünftige Placeholder
3. **Validierungslogik für neue Placeholder**
   - technische Prüfung gegen dieses Dokument

### 6.2 Dateien / Dokumentation
4. `PLACEHOLDER_CATALOG_EXTENDED.json`
5. `PLACEHOLDER_CATALOG_EXTENDED.md`
6. `PLACEHOLDER_EXPORT_SPEC.md`
7. `PLACEHOLDER_GAP_REPORT.md`
8. optional: `PLACEHOLDER_VALIDATION_REPORT.md`

### 6.3 Tests
9. Tests für:
   - Vollständigkeit des Exports,
   - Konsistenz der Metadaten,
   - Legacy-Kompatibilität,
   - Referenzierbarkeit der Verwendungen,
   - Pflichtfeld-Validierung für neue Placeholder,
   - normkonforme Typisierung und Zeitfenster-Markierung.

---

## 7. Verbindliches Metadaten-Schema pro Placeholder

Jeder Placeholder im erweiterten Export muss mindestens die folgenden Felder besitzen oder explizit als `unknown`/`null`/leer markiert sein.

```json
{
  "key": "weight_aktuell",
  "placeholder": "{{weight_aktuell}}",
  "category": "Körper",
  "type": "atomic",
  "description": "Aktuelles Gewicht in kg",
  "semantic_contract": "Letzter verfügbarer Gewichtseintrag des Profils, keine Mittelung",
  "unit": "kg",
  "time_window": "latest",
  "output_type": "number_or_string",
  "format_hint": "85.8 kg",
  "example_output": "85.8 kg",
  "value_display": "85.8 kg",
  "value_raw": 85.8,
  "available": true,
  "missing_reason": null,
  "missing_value_policy": {
    "legacy_display": "nicht verfügbar",
    "structured_null": true,
    "reason_codes": ["no_data", "insufficient_data", "resolver_error"]
  },
  "exception_handling": {
    "on_error": "return_null_and_reason",
    "notes": "Keine Exception bis in Prompt-Ebene durchreichen"
  },
  "quality_filter_policy": null,
  "confidence_logic": {
    "supported": false,
    "notes": "Für latest-Werte nicht erforderlich"
  },
  "source": {
    "resolver": "get_latest_weight_placeholder",
    "module": "placeholder_resolver.py",
    "function": "get_latest_weight",
    "data_layer_module": "body_metrics.py",
    "source_tables": ["weight_log"]
  },
  "dependencies": ["profile_id"],
  "used_by": {
    "prompts": ["gesamt", "koerper"],
    "pipelines": ["pipeline", "wettkampf-analyse"],
    "charts": []
  },
  "version": "1.0.0",
  "deprecated": false,
  "replacement": null,
  "known_issues": [],
  "notes": []
}
```

### 7.1 Pflichtfelder
Pflichtfelder sind:
- `key`
- `placeholder`
- `category`
- `type`
- `description`
- `semantic_contract`
- `unit`
- `time_window`
- `output_type`
- `value_display`
- `available`
- `missing_value_policy`
- `source`
- `version`
- `deprecated`

### 7.2 Erlaubte Werte für `type`
- `atomic`
- `raw_data`
- `interpreted`
- `legacy_unknown`

### 7.3 Erlaubte Werte für `time_window`
- `latest`
- `7d`
- `14d`
- `28d`
- `30d`
- `90d`
- `custom`
- `mixed`
- `unknown`

### 7.4 Erlaubte Werte für `output_type`
- `string`
- `number`
- `integer`
- `boolean`
- `json`
- `markdown`
- `date`
- `enum`
- `unknown`

---

## 8. Exportformat

### 8.1 Legacy-Export bleibt erhalten
Der bestehende Export bleibt unverändert nutzbar.

### 8.2 Neuer erweiterter Export
Zusätzlich muss ein erweiterter Export existieren, z. B. mit:
- `legacy`
- `metadata.by_category`
- `metadata.flat`
- `metadata.summary`
- `metadata.gaps`
- `metadata.schema_version`

### 8.3 Zukunftsfähigkeit
Der erweiterte Export muss so strukturiert sein, dass neue Placeholder ohne Redesign der Gesamtstruktur ergänzt werden können.

---

## 9. Pflichtregeln für neue und zukünftige Placeholder

Jeder neue Placeholder muss vor Freigabe folgende Fragen beantworten können:
1. Was ist die exakte fachliche Semantik?
2. Welches Zeitfenster gilt?
3. Welcher Typ liegt vor?
4. Was ist der Output-Typ?
5. Welche Datenquelle/Funktion berechnet ihn?
6. Wie werden fehlende Werte dargestellt?
7. Welche Ausnahmebehandlung gilt?
8. Welche bekannten Grenzen/Issues gibt es?
9. Wird ein Quality-Filter angewendet?
10. Ist der Placeholder in Prompts/Pipelines referenziert?

Wenn eine dieser Fragen unbeantwortet bleibt, darf der Placeholder nicht als voll standardkonform gelten.

---

## 10. Legacy-, Deprecation- und Abweichungsregeln

### 10.1 Legacy-Markierung
Bestehende problematische Placeholder dürfen als Legacy bestehen bleiben, wenn sie markiert werden durch:
- `deprecated: true/false`
- `known_issues`
- `replacement`
- dokumentierten Semantikhinweis

### 10.2 Deprecation-Pflicht
Wenn ein Placeholder semantisch unpräzise, technisch instabil oder fachlich überholt ist, muss ein Deprecation-Pfad vorgesehen werden.

### 10.3 Abweichungsprozess
Abweichungen von diesem Standard müssen in einem Decision-/Gap-Log dokumentiert werden, mit:
- Begründung,
- Impact,
- geplanter Nachbesserung,
- Verantwortlichkeit.

---

## 11. Validierung und Governance

### 11.1 Pflichtvalidierungen
Für bestehende und neue Placeholder müssen validierbar sein:
- Pflichtfeld-Vollständigkeit,
- gültige Typisierung,
- gültiges Zeitfenster,
- dokumentierte Quelle,
- dokumentiertes Fehlwertverhalten,
- dokumentierte Legacy-/Deprecation-Information.

### 11.2 CI-/Test-Eignung
Die technische Lösung soll so gebaut werden, dass künftige Validierungen automatisierbar sind.

### 11.3 Two-Stage-Artefakte
Interpretierte Outputs aus Basis-Prompts müssen als `interpreted` gekennzeichnet werden und dürfen nicht als rohe Datenplaceholder ausgegeben werden.

---

## 12. Konkrete Arbeitsanweisung an den Coding Agent

Der Coding Agent soll diese Spezifikation als **verbindlichen Standard** behandeln und die Implementierung so auslegen, dass sie:
- den aktuellen Bestand vollständig erfasst,
- für künftige Placeholder wiederverwendbar ist,
- Legacy-Verhalten nicht still bricht,
- technische Lücken transparent markiert,
- und als Grundlage für zukünftige Placeholder-Governance dient.

---

## 13. Akzeptanzkriterien

Die Umsetzung gilt nur dann als erfolgreich, wenn:
1. alle existierenden Placeholder im erweiterten Katalog enthalten sind,
2. der Legacy-Export weiter funktioniert,
3. das Metadatenmodell für neue Placeholder wiederverwendbar ist,
4. Pflichtfelder validiert werden,
5. unresolved Informationen sauber markiert werden,
6. die Dokumentation ausdrücklich festhält, dass der Standard **für alle neuen und zukünftigen Placeholder** gilt.

---

## 14. Schlussregel

Ab Inkrafttreten dieses Dokuments ist ein neuer Placeholder ohne Standardkonformität nur als explizit dokumentierte Ausnahme zulässig. Der Default ist Standardpflicht, nicht informelle Flexibilität.