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.

{
  "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.