wow20/_bmad-output/implementation-artifacts/spec-1-4-schema-validierung-für-bundle-implementieren.md

title, type, created, status, baseline_commit, review_loop_iteration, context

title	type	created	status	baseline_commit	review_loop_iteration	context
Schema-Validierung für Bundle implementieren (Story 1.4)	feature	2026-08-15	done	33d21cb0ad	0	_bmad-output/implementation-artifacts/epic-1-context.md

Intent

Problem: Der autorisierte Schema-Vertrag (§7) definiert eine abschließende 14-Punkte-Liste struktureller Invalidität und verweist mehrere Prüf-Verhalten (Existenzprüfung raw/-Resource, Kalender-Validität, ISO-8601-Normalform, Listen-Normalisierung) an Story 1.4 — aber es existiert noch keine ausführbare, deterministische Validierung. Ohne sie könnte ein Producer vor der Mutation nicht nachweisen, dass sein Bundle gültig ist, und ein OKF-invalides Bundle würde einen Run nicht zuverlässig scheitern lassen (F-2/AD-1b, A0-2, FR-9).

Approach: Eine agent-unabhängige, deterministische Validator-Instruktion schema/validator.md erstellen, die die abschließende 14-Punkte-Invaliditätsliste (Vertrag §7) 1:1 als mechanische Prüfschritte abbildet, die von Deferred-Work an Story 1.4 verwiesenen Validator-Entscheidungen (ISO-8601-Normalform, Kalender-Validität, Existenzprüfung, Listen-/Absenz-Normalisierung, non-md-Konvention, stale_after-Warning) deterministisch festlegt und ein maschinenlesbares PASS/FAIL-Verdikt mit textueller Fehlerursache ausgibt — ohne LLM-Urteil und ohne Standalone-Anwendung (D-3, Q-6: Agent-Instruktions-Validator, mechanisch zu bestätigen).

Boundaries & Constraints

Always:

• schema/validator.md ist der einzige Ort der Validierungs-Instruktion; er ist rein textuell (kein ausführbarer Code) und agent-unabhängig, liegt außerhalb des Bundles neben dem Vertrag (AD-1, D-3, Q-6).
• Die Validierung bildet die abschließende 14-Punkte-Liste (Vertrag §7) 1:1 ab; sie darf keinen Eintrag hinzufügen oder streichen (Vertrag §7 „abschließende Liste"). Erweiterungen nur über das Story-/Autorisierungs-Verfahren.
• Fehlende optionale Felder (kein sources/generated/verified/status/stale_after) sind niemals invalide (A0-2/AD-1b); sources: []/verified: [] sind zulässig und gleichbedeutend mit Absenz.
• Die Validierung ist deterministisch und ohne LLM-Urteil aufrufbar (AD-13/AD-17h); sie erzeugt pro geprüfter Datei ein PASS/FAIL-Verdikt mit textuell identifizierbarer Fehlerursache (NFR-4).
• Prüfumfang (Vertrag §1): ausschließlich Markdown innerhalb wiki/ (Bundleroot, Area-index.md, Concepts, log.md) plus die raw/-Ziellinien aus sources-resource. raw/, schema/, adapters/ selbst werden nicht als Bundle validiert.
• Existenzprüfung: ein sources-resource unter raw/ MUSS zum Validierungszeitpunkt als Datei existieren (fachliche Validierung, Deferred-Work EC-1).
• Kalender-Validität: Datumsfelder müssen reale Kalenderdaten sein (2026-02-31 ist invalide); der Veraltungsvergleich today >= stale_after erfolgt in UTC (Vertrag §7).
• Valid-Pfad-Auflösung (Vertrag §3.3): resource ist ein /-getrennter relativer Pfad zur Workspace-Root, darf kein ..-Segment, keinen führenden /, kein file:// und keine Backslash-/Windows-Trenner enthalten und muss bei Auflösung innerhalb raw/ landen.
• Dateien unter wiki/, die keine .md-Dateien sind (z. B. wiki/<area>/logo.png), werden als nicht-Bundle-Elemente behandelt und nicht validiert (Deferred-Work EC-11).
• Dokument in Deutsch; das Verdikt-Format ist maschinenlesbar (ein SUCCESS/FAIL-Verb per Datei, gefolgt von textueller Begründung).

Ask First:

• Eine bewusste Verschärfung gegenüber dem Vertrag (z. B. Absicht, resource-Existenz als strukturell statt fachlich zu werten) — nur mit menschlicher Zustimmung, da sie die Abschluss-Position von §7 berührt.
• Die Einführung eines Standalone-Skripts/-Programms (Python/TS/etc.) als eigentliche Validator-Implementierung — der Epic-Context (D-3, Q-6) widerspricht dem; ein späterer Wechsel auf eine konkrete Anwendung ist separat zu autopisieren.

Never:

• Kein eigenes Schema neben schema/wiki-compiler.md; keine Änderung am autorisierten Vertrag (Story 1.3) und keine Änderung an raw/ (immutable, AD-3).
• Kein Standalone-/Executable-Anwendungs-Code, der die Validierung ersetzt (D-3); die Validierungs-Regel bleibt eine Instruktion, kein Programm.
• Keine neue Invaliditätsklasse oder neue Pflichtfelder außerhalb des Vertrags; keine Validierung der Inhalte von raw/-, schema/- oder adapters/-Dateien als Bundle.
• Kein LLM-Urteil in der Prüfung; der Validator ist kein Modell-Aufruf, sondern eine mechanisch befolgte Anweisung.
• Keine Validierung schreibender Art: der Validator mutiert nichts, protokolliert aber (siehe Verification) ein Ausführungs-Protokoll.

Code Map

• schema/validator.md — Zieldatei (neu): deterministische Validator-Instruktion; bildet Vertrag §7 ab und legt die von Deferred-Work an Story 1.4 verwiesenen Entscheidungen fest.
• schema/wiki-compiler.md — normative Grundlage (read-only, Story 1.3-Ergebnis): §1 Geltungsbereich, §2 Bundleroot/Frontmatter, §3 Feldsubset (inkl. §3.3 sources/resource-Auflösung, §3.4 generated, §3.5 verified, §3.6 status, §3.7 stale_after), §5 log.md-Typ, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste, §8 Normreferenzen.
• wiki/index.md — Referenz Bundleroot (read-only): type: bundle + okf_version: "0.2", Frontmatter exklusiv; POSITIV-Beispiel für Prüfschritt 8/9.
• wiki/log.md — Referenz leerer log.md: Kein Frontmatter, reservierte Root-Datei; in dieser Story wird ausschließlich der Zertifizierungs-Ausführungs-Protokolleintrag angehängt (keine inhaltliche Bundle-Änderung, Vertrag §5-konform).
• adapters/claude/README.md, adapters/README.md — Referenz für den Adapter-/Agenten-Kontext (read-only); der Validator ist von Adaptern unabhängig (AD-10).
• _bmad-output/implementation-artifacts/deferred-work.md — Pflicht-Input: die 8 an Story 1.4 verwiesenen Validator-Entscheidungen (EC-1, EC-3, BH-14, F2-Listen, BH-8, EC-11, F17-log.md, F18-stale_after) — werden in der Instruktion deterministisch festgelegt.
• _bmad-output/implementation-artifacts/epic-1-context.md — primärer Planungskontext (read-only).

Tasks & Acceptance

Execution:

• schema/validator.md — Validator-Instruktion anlegen: Zweck & Aufruf (Agent/Prozess führt die Schritte deterministisch aus), Prüfumfang nach Vertrag §1, die 14 Invaliditäts-Punkte 1:1 als mechanische Prüfschritte (inkl. Welcher YAML-/Text-Check je Punkt, welches Artefakt), die fachlichen Zusatzprüfungen (Existenzprüfung raw/-Resource, Kalender-/Datum-Validität in UTC, stale_after-Veraltungs-Warning als Warnung, non-md-Dateien ignoriert), die Normalisierungs-/Toleranz-Vorgaben (Map→1-Element-Liste bei verified, leere Listen = Absenz, semantische Gleichwertigkeit), das maschinenlesbare Verdikt-Format (SUCCESS / FAIL + Datei + Ursache), und die Selbstbegrenzung (abschließende Liste, keine Erweiterung) — F-2/AD-1b, A0-2, FR-9, NFR-4.
• schema/validator.md — die 8 Deferred-Work-Entscheidungen deterministisch festlegen (EC-1 Existenzprüfung, EC-3 Kalender-Validität, BH-14 ISO-8601-Normalform, F2-Listen-Normalisierung, BH-8/F18 stale_after-semantische Warnung statt Invalidität, EC-11 non-md-Konvention, F17 log.md-Feingranularität: leeres Log gültig) — abgeleitet aus dem Vertrag und dem Epic-Context.
• schema/validator.md — Negativ-/Positiv-Fixtures als Referenztabellen dokumentieren: je Invaliditäts-Punkt ein konkretes Fehlerbeispiel (Input → erwartetes FAIL mit Ursache) und je Punkt das gültige Gegenstück (PASS) — belegt die 1:1-Abbildung und macht die mechanische Bedingung reproduzierbar prüfbar (AD-17h).
• schema/validator.md — Verdikt-Format & Selbstbegrenzung normieren: SUCCESS/FAIL-Report-Struktur, keine Validierung von raw//schema//adapters/-Inhalten als Bundle, keine neuen Invaliditätsklassen; textuelle Fehlerursache (NFR-4).
• wiki/log.md — Ausführungs-Protokoll der Validator-Zertifizierung anhängen: Datum, Validator-Revision, Ergebnis der Selbstprüfung gegen die Referenz-Fixtures (PASS/FAIL) — dokumentiert die mechanische Bestätigung (Q-6: „confirmed mechanical"), keine inhaltliche Änderung des Bundles.
• _bmad-output/implementation-artifacts/sprint-status.yaml — Story 1.4 von backlog auf in-progress setzen (nach Start der Implementierung).

Acceptance Criteria:

• Given ein Bundle mit struktureller OKF-Invalidität (z. B. fehlender type), when die Validierung ausgeführt wird, then schlägt der Run fehl (FAIL) mit textuell identifizierbarer Ursache — kein erfolgreicher Run (F-2/AD-1b).
• Given ein Bundle mit fehlenden optionalen Feldern (kein sources/verified), when die Validierung ausgeführt wird, then gilt es als gültig (PASS) — fehlende optionale Felder sind keine Invalidität (A0-2/AD-1b).
• Given ein invalides Bundle, when der Run fehlschlägt, then bleibt raw/ unverändert und die Fehlerursache ist im Verdikt textuell identifizierbar (AD-3, NFR-4).
• Given die Validierung, when ausgeführt, then ist sie eine eigenständige, deterministische Prüfung ohne LLM-Urteil — als Instruktion mechanisch befolgbar (AD-13/AD-17h-konform), nicht Standalone-Code (D-3).
• Given ein sources-resource, when es auf einen wiki/-Concept-Pfad oder außerhalb raw/ zeigt (nicht-existente Datei, ..-Traversal), then ist das Bundle FAIL (Provenienz-Ziellinie, §3.3) bzw. fachliche Invalidität (Existenzprüfung).
• Given die abschließende Invaliditätsliste (§7), when die Instruktion fertig ist, then bildet sie alle 14 Punkte 1:1 ab und führt keine eigene Invaliditätsklasse ein.
• Given ein stale_after in der Vergangenheit, when validiert wird, then ist es kein struktureller Fehler; eine Warnung dokumentiert die Veraltung (F18/BH-8, ohne Invalidität).
• Given verified als einzelne Map, when validiert wird, then wird es als 1-Element-Liste gelesen und nicht abgelehnt (Vertrag §3.5).
• Given eine nicht-.md-Datei unter wiki/, when validiert wird, then wird sie ignoriert (nicht Bundle-Element) (EC-11).

Spec Change Log

• 2026-08-15, Loop 1 (Step-04-Review: Blind-Hunter + Edge-Case-Hunter + Verification-Gap): Kein bad_spec/intent_gap — alle Befunde sind als patch direkt in schema/validator.md lösbar oder defer. Amendments (non-frozen; Code Map + Tasks + Design Notes + Spec Change Log):
  • Bundleroot-/Reserviert-Pflichten dokumentieren: Code Map/Aufruf weisen auf die neuen Bundleroot- und Reserviert-Namen-Voraussetzungen (fehlende wiki/index.md; log.md an Nicht-Root-Position) als strukturelle Norm-Pflichten des Validators hin — keine neue §7-Invaliditätsklasse, sondern Voraussetzungs-Checks (BH-7/EC-2/EC-4).
  • ISO-8601-Maß relativiert: Die Normalform akzeptiert beide Offset-Formen (±HHMM und ±HH:MM, beide gültiges ISO-8601/RFC 3339); nur Nicht-ISO-8601-Formen sind Punkt-14-FAIL (BH-2). Vertrag §7 Punkt 14 bleibt unangetastet („abschließende Liste" nicht verschärft).
  • F15 + Story 2.3 als Deferred/Normreferenz: generated.by: human:<id>-Trust-Semantik wird an Epic 4 verschoben (Deferred-Work F15); der Punkt-11-Link-Check verengt die Linkform nicht (genau-eine-Form bleibt Story 2.3) — als Normreferenz dokumentiert, nicht als Validator-Entscheidung (BH-6, EC-7).
  • KEEP (muss bei Re-Derivation überleben): die 14-Punkte-1:1-Abbildung als tabellarische mechanische Prüfschritte mit deterministischer Fehlerursache; die 8 Deferred-Work-Entscheidungen (EC-1, EC-3, BH-14, F2, BH-8, EC-11, F17, F18); Verdikt-Format SUCCESS/FAIL mit textueller Ursache (NFR-4); Abbruch-Regel (erste verletzte Bedingung); Selbstbegrenzung (abschließende Liste, keine eigene Invaliditätsklasse, kein Schreibzugriff); Positiv-/Negativ-Fixtures als Referenztabellen (AD-17h).

Design Notes

Die Story 1.4 ist das erste ausführbare Artefakt des Projekts: Die Validierung ist keine Standalone-Anwendung (D-3 verbietet Python/TS/etc.), sondern eine deterministische Instruktion, die ein Agent/Prozess mechanisch befolgt (Q-6, AD-17h) und die vor Erzeugung der ersten Concepts (Epic 2) stehen muss.

Die Validierung wird damit in zwei Ebenen modelliert:

Behauptung (Normativ):  schema/wiki-compiler.md  (§7: abschließende 14-Punkte-Liste)
Ableitung (Story 1.4):  schema/validator.md      (Prüfschritte je Punkt + Verdikt-Format)
Ausführung:  deterministisch von einem Agent/Prozess befolgt (kein LLM-Urteil)

Wichtige Normalform-Entscheidungen (aus Deferred-Work):

• verified als Map → 1-Element-Liste (Vertrag §3.5); sources: []/verified: [] = Absenz (semantisch identisch) — die Ausgabe-/Diff-Basis nutzt eine feste Reihenfolge.
• ISO-8601-Normalform für at (Vertrag §3.4/3.5): akzeptiert YYYY-MM-DDTHH:MM:SS mit den Offset-Suffixen Z, ±HHMM und ±HH:MM (alle gültiges ISO-8601/RFC 3339); ein reiner Datumswert wird als T00:00:00Z normalisiert — nicht „Abweichung vom Format"; Punkt-14-FAIL sind nur Nicht-ISO-8601-Formen (Loop-1-Amendment BH-2).
• Datumsfelder müssen reale Kalenderdaten sein (EC-3); Veraltungsvergleich today >= stale_after in UTC (Vertrag §7).
• Existenzprüfung fachlich (EC-1): ein resource unter raw/, das nicht existiert, ist fachlich invalide → FAIL, wird aber nicht als §7-Punkt gezählt (der Validator protokolliert den Punkt separat).
• stale_after in der Vergangenheit: Warnung, kein struktureller Fehler (F18/BH-8).
• Nicht-.md-Dateien unter wiki/ werden ignoriert (EC-11) — keine Ablehnung, keine Konvention-Erfindung über den Vertrag hinaus.

Verification

Commands:

• git status --short && git diff --stat — expected: neue Datei schema/validator.md + wiki/log.md-Protokolleintrag + sprint-status.yaml-Wired-Up (Story 1.4 in-progress, epic-1 in-progress); keine raw/-Mutationen.
• Manuelle Abbildungsprüfung: grep -nE 'Punkt 1[0-4]|Invalid' schema/validator.md — expected: alle 14 Punkte adressiert; grep -n 'abschließend' schema/validator.md — expected: Selbstbegrenzung vorhanden.
• Konformitäts-Smoke an den Referenzfixtures: grep -nE '\bFAIL\b|\bSUCCESS\b' schema/validator.md — expected: je Punkt mindestens ein Beispiel mit klar bezeichneter Erwartung.
• Verdikt-Format: grep -nE '\b(SUCCESS|FAIL)\b' schema/validator.md — expected: ein Verdikt-Verb pro Datei-Syntax dokumentiert.

Manual checks (if no CLI):

• schema/validator.md ist rein textuell (kein Programmcode/Executable-Abschnitt) und beginnt mit Zweck & Aufruf.

• Alle 14 Punkte aus Vertrag §7 sind als eigene Prüfschritte vorhanden; keine darüber hinausgehende Invaliditätsklasse.

• Die 8 Deferred-Work-Direktiven sind deterministisch beantwortet und in der Instruktion auffindbar.

• wiki/log.md enthält (nach Zertifizierung) einen datierten Eintrag „Validator-Selbstprüfung gegen Fixtures: PASS".

• 2026-08-15, Loop 2 (Review: Blind-Hunter + Edge-Case-Hunter + Verification-Gap, kein bad_spec): Die drei Review-Layer fanden keinen norm-beherrschenden Defekt — kein neuer Loopback. Alle Befunde waren als patch direkt in schema/validator.md lösbar (17 Patches, Revision 1→2): §3.2 Bundleroot-/Reserviert-Voraussetzungen als Nicht-§7-Pflichten, Punkt 6/9-Exemption, Punkt 9 auf Dateiinhalt, Punkt 10 BOM-Stripping, Punkt 11 deterministische Link-Prüfung (ohne Story-2.3-Vorwegnahme), Punkt 12 fehlende/leere resource, Punkt 14 usage_count-Integer-Typ, §4.3 akzeptiert ±HH:MM, §4.4-Ausführungs-Reihenfolge mit EC-1-Aggregation, §5-WARN als Berichtskanal, §6.2 Punkt-4-vor-3-Priorität, Fixture-Ergänzungen. Drei Befunde als Deferred/Normreferenz dokumentiert (F15→Epic 4; genau-eine-Linkform→Story 2.3 mit deferred-work.md-Eintrag; stale_after-Konsequenz→Epic 3, bereits BH-8-adressiert). Abschluss: schema/validator.md (Revision 2) final; all 14 Punkte 1:1 abgebildet, no eigene Invaliditätsklasse.

• KEEP (muss bei Re-Derivation überleben): die 14-Punkte-1:1-Abbildung als mechanische Prüfschritte mit deterministischer Fehlerursache; die 8 Deferred-Work-Entscheidungen (EC-1, EC-3, BH-14, F2, BH-8, EC-11, F17, F18); Verdikt-Format SUCCESS/FAIL mit textueller Ursache (NFR-4); Abbruch-Regel (erste verletzte Bedingung); Selbstbegrenzung (abschließende Liste, keine eigene Invaliditätsklasse, kein Schreibzugriff); Positiv-/Negativ-Fixtures (AD-17h); §3.2-Voraussetzungsprüfungen ausdrücklich als Nicht-§7-Pflichten.

Suggested Review Order

Einstiegspunkt: Validator-Instruktion

• Einstieg — Zweck, Aufruf-Ablauf und Ableitung vom Vertrag ¶7; höchste Hebelwirkung für das Gesamtdesign validator.md:8

Normative 1:1-Abbildung (abschließende Liste §7→§3)

• Die 14 Punkte als tabellarische mechanische Prüfschritte; Kernfrage des Reviews: keine Erweiterung/kein Streichen validator.md:48

• Erweiterungs-/Abschluss-Regel plus Punkt-6/9-Exemption (kein Punkt-6-vor-9-Feuer) validator.md:71

• Bundleroot-/Reserviert-Voraussetzungen — ausdrücklich keine neue ¶7-Klasse validator.md:77

Deterministische Normalform & Toleranz

• Listen-vs.-Absenz, fehlende optionale Felder, feste Key-Reihenfolge (F2) validator.md:85

• ISO-8601-Normalform inkl. ±HH:MM-Akzeptanz (keine unautorisierte Verschärfung); Kalender-Validität validator.md:100

• Deterministische Rangfolge & Abbruch-Regel (erste verletzte Bedingung), EC-1-Aggregation validator.md:109

• log.md-Feingranularität (leeres Log gültig), Verdikt-Format inkl. WARN als Berichtskanal validator.md:122

Fachliche Zusatzprüfungen (Deferred-Work)

• EC-1-Existenz als Datei, EC-3-Kalender, EC-4-stale_after-Warnung, EC-11-non-md; Pfad-Auflösung mit Punkt-4-vor-3-Priorität validator.md:149

Referenz-Fixtures & Selbstbegrenzung

• Negativ-/Positiv-Fixtures incl. Isolations-Notiz; per AD-17h reproduzierbar prüfbar validator.md:188

• Normreferenzen inkl. F15/Story-2.3-Defer, Revisionslog validator.md:245

Protokollierung & Status

• Zertifizierungs-Eintrag im Bundle-Log (Vertrag §5-konform; PASS gegen Fixtures) log.md:3

• Story 1.4 auf review gesetzt (separierte /review-Pfad-Transition) sprint-status.yaml:42