124 lines
13 KiB
Markdown
124 lines
13 KiB
Markdown
---
|
|
title: 'OKF-Schema-Vertrag `schema/wiki-compiler.md` autorisieren (Story 1.3)'
|
|
type: 'feature'
|
|
created: '2026-08-14'
|
|
status: 'done'
|
|
review_loop_iteration: 1
|
|
baseline_commit: 4011dc7fc4205164402fd26251e5322042978837
|
|
context:
|
|
- _bmad-output/implementation-artifacts/epic-1-context.md
|
|
---
|
|
|
|
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
|
|
|
## Intent
|
|
|
|
**Problem:** `schema/wiki-compiler.md` ist ein Platzhalter ohne Verbindlichkeit — alle Producer (Compiler, Adapter, Story 1.4-Validator) könnten unterschiedliche OKF-Details annehmen (z. B. `sources`-Form, `log.md`-Format, `status`-Regeln), was Portabilität und deterministische Konformität gefährdet (FR-9, NFR-6).
|
|
|
|
**Approach:** Den Platzhalter zum autorisierten, verbindlichen OKF-0.2-Schema-Vertrag ausbauen: das erlaubte Feldsubset (inkl. exakter `sources`-Form, `generated`/`verified`, `status`-Policing), `okf_version`-Regel, `log.md`-Typdefinition, Index-Regel, Validitätsprädikate für Concepts/Bundle-Root sowie das Provenienz-Verbot (nie `wiki/`-Pfade) normativ festlegen.
|
|
|
|
## Boundaries & Constraints
|
|
|
|
**Always:**
|
|
- `schema/wiki-compiler.md` ist der einzige normative Ort für das OKF-Feldsubset, `log.md`-Typ, Index-Regel, Validitätsprädikate und das `sources`→`raw`-Verbot (A0-1/AD-1a, FR-9, NFR-6).
|
|
- `type` ist das einzige Pflichtfeld für Concepts; die Bundle-Root `wiki/index.md` trägt zusätzlich `okf_version: "0.2"` und `type: bundle` (bereits vorhanden, wird normativ fixiert).
|
|
- Das Schema-Bindungs-Verbot gilt: `sources`-Einträge lösen ausschließlich auf `raw/`-Pfade oder extern referenzierte immutable Evidenz auf — niemals auf `wiki/`-Concept-Pfade (A0-4/AD-4b).
|
|
- Strukturelle OKF-Invalidität schlägt den Compilation Run fehl; fehlende optionale Felder sind nicht invalide (A0-2/AD-1b, F-2).
|
|
- In v1 sind nur lokal unter `raw/` materialisierte Sources unterstützt (FR-1, A-4); das Schema lässt dementsprechend keine URL-Form der Sources zu.
|
|
- Kein generiertes Concept führt ein anderes generiertes Concept als alleinige Provenienz (A0-5/AD-4c) — Teil der Schema-Validierung.
|
|
- Gültige `status`-Werte: `draft` | `stable` | `deprecated` (OKF `slotting`; Absenz ⇒ `stable`-Default wird normativ dokumentiert).
|
|
- Dokument in Deutsch; Beispiel-Frontmatter OKF-konform (YAML).
|
|
|
|
**Ask First:**
|
|
- Abweichungen vom normativen OKF-0.2-Standard (PRD §13) — jede bewusste Verschärfung gegenüber OKF 0.2 erfordert menschliche Zustimmung (z. B. falls nur lokal erlaubte Sources als Verschärfung bestätigt werden soll).
|
|
|
|
**Never:**
|
|
- Kein eigener OKF-Dialekt und kein paralleles Schema neben `schema/wiki-compiler.md` (AD-1: nur dieses eine Schema bindet).
|
|
- Keine Implementierung des Validators in dieser Story (das ist Story 1.4); keine Umschreibung von `schema/` in einen Executable-Code/Programmcode.
|
|
- Keine Änderung an `raw/` (immutable, AD-3) und keine Adapter-Semantik (AD-10).
|
|
- Keine Erfindung zusätzlicher Pflichtfelder oder eigener Statuswerte außerhalb OKF-0.2.
|
|
|
|
## I/O & Edge-Case Matrix
|
|
|
|
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
|
|----------|--------------|---------------------------|----------------|
|
|
| HAPPY_PATH | `schema/wiki-compiler.md` autorisiert, vollständiger Feldsubset-Vertrag | Vertrag normativ; alle Producer/Adapter lesen dieselben Regeln (FR-9, NFR-6) | N/A |
|
|
| OPTIONAL | Concept ohne optionale Felder (nur `type`) | Gültig; nicht abgelehnt (A0-2/AD-1b, F-2) | N/A |
|
|
| INVALID | `sources`-Eintrag zeigt auf `wiki/`-Concept-Pfad | Schema markiert dies als nicht konform (A0-4/AD-4b) | Klare textuelle Fehlerursache (NFR-4) |
|
|
| CONFLICT | Zwei Producer interpretieren `sources`-Form unterschiedlich | Schema legt exakt eine Form fest (Liste von Maps) | N/A |
|
|
|
|
</frozen-after-approval>
|
|
|
|
## Code Map
|
|
|
|
- `schema/wiki-compiler.md` — **Zieldatei**: Platzhalter → autorisierter Verbindlicher Vertrag (A0-1/AD-1a); erzwingt Feldsubset, `log.md`-Typ, Index-Regel, Validitätsprädikate, `sources`→`raw`-Verbot.
|
|
- `wiki/index.md` — Bundleroot (exists): `type: bundle`, `okf_version: "0.2"`, keine weiteren Field-Subsets; dient als Referenz für Bundle-Root-Prädikat.
|
|
- `wiki/log.md` — leer; strukturelle Vorlage (kein Frontmatter, reservierter Name); Typdefinition im Schema.
|
|
- `raw/prd/prd-wow20-2026-08-14.md` — normative Quelle: FR-9, NFR-6, §13 OKF-0.2-Referenz (nur lesen).
|
|
- `raw/architecture-spine/architecture-spine-2026-08-14.md` — AD-1a/1b, A0-1/A0-2/A0-4/A0-5, D-10, Structural Seed (nur lesen).
|
|
- `raw/epics/epics-2026-08-14.md` — A0-1…A0-20-Subset-Formulierungen (nur lesen).
|
|
- `_bmad-output/implementation-artifacts/spec-1-2-...md` — Continuity: `raw/`-Konvention & artefact/evidence-Grenze (nur lesen).
|
|
|
|
## Tasks & Acceptance
|
|
|
|
**Execution:**
|
|
- [x] `schema/wiki-compiler.md` — Platzhalter-Status in einen autorisierten Vertrag umwandeln; normativ festlegen: Feldsubset (Pflicht/optional), exakte `sources`-Form (Liste von Maps), `generated`/`verified`-Zulässigkeit, `status`-Werte & Default, `stale_after`, `okf_version`-Regel, `log.md`-Typdefinition, Index-Regel (jede Area hat `index.md`), Validitätsprädikate für Concepts und Bundle-Root, Provenienz-Verbot, strukturelle-Invalidität-vs.-Optimalität-Regel — AD-1a/A0-1, FR-9, NFR-6.
|
|
- [x] `schema/wiki-compiler.md` — Bundleroot-Regel: `okf_version: "0.2"` nur in `wiki/index.md` (nicht in Area-`index.md`); Area-`index.md` trägt kein Frontmatter — AD-1, AD-9.
|
|
- [x] `schema/wiki-compiler.md` — Determinismus der Provenienz-Ziellinie: `resource`-Pfade sind relative Workspace-Pfade unter `raw/`, `..`-Traversale (die aus `raw/` hinausweist) ist unzulässig; die Auflöse-Regel ist Teil der Validitätsprädikate — AD-4b/A0-4.
|
|
- [x] `schema/wiki-compiler.md` — Orthogonalität von `status` und Trust: `status`-Policing (`draft`|`stable`|`deprecated`, Absenz ⇒ `stable`) und `verified`-Status sind unabhängige Dimensionen; ein nicht-human-reviewtes Concept ist nicht deshalb nicht-`stable` — AD-15/A0-20.
|
|
- [x] `schema/wiki-compiler.md` — A0-5/AD-4c unter v1: da `sources` in v1 ausschließlich auf `raw/`-Evidenz zeigt, ist die „keine alleinige Provenienz aus generierten Concepts"-Regel tautologisch erfüllt; als Normreferenz und Wegfall-Option bei späterer Quellenerweiterung dokumentieren, nicht als eigenes Feuerbedingungs-Prädikat.
|
|
- [x] `schema/wiki-compiler.md` — Abschluss der Norm: Bundleroot-Frontmatter exklusiv `type`+`okf_version` (und `type: bundle` nur in Bundleroot); frontmatterlose, nicht-reservierte `.md`-Datei im Bundle = strukturell invalide; `sources: []`/`verified: []` zulässig (semantisch = Absenz); abweichender `okf_version`-Wert (z. B. `"0.3"`) strukturell invalide; Liste struktureller Invalidität abschließend; keine unautorisierten Keys in `sources`/`generated`/`verified`-Einträgen; leere `by`-Angaben verboten; korrekte Abschnitts-Querverweise (§7 Invalidität, §5 `log.md`, §6 Index-Regel, §6.1 Concept-Prädikat); Vertrags-Eigen-Metadaten (Autorisierungsdatum, Revision, autorisierende Story).
|
|
|
|
**Acceptance Criteria:**
|
|
- Given der autorisierte Vertrag, when ein Concept geprüft wird, then ist `type` das einzige Pflichtfeld; `sources`, `generated`, `verified`, `status`, `stale_after` werden als Subset validiert (AD-1a).
|
|
- Given ein Concept, when `sources` gesetzt ist, then muss `sources` eine Liste von Maps sein (mit `resource` als einziger Pflicht-Evidenzangabe) — keine Map-/Objekt-Form (AD-4b).
|
|
- Given ein `sources`-Eintrag, when er auf einen `wiki/`-Concept-Pfad zeigt, then ist das Bundle strukturell invalide (nie auf `wiki/`-Concept-Pfade, A0-4/AD-4b).
|
|
- Given das Schema, when ein neues Area-Verzeichnis in `wiki/` angelegt wird, then bindet es die Index-Regel (jede Area hat `index.md`) und den `log.md`-Typ (AD-1a).
|
|
- Given ein Concept mit erlaubten optionalen Feldern aber ohne `sources`/`verified`, when es validiert wird, then ist es nicht strukturell invalide (A0-2/AD-1b: fehlende optionale Felder sind kein Fehler).
|
|
- Given die Bundle-Root, when geprüft, then darf `okf_version: "0.2"` nur in `wiki/index.md` stehen; `log.md` folgt der Schema-Typdefinition (AD-1, AD-9).
|
|
|
|
## Spec Change Log
|
|
|
|
- **2026-08-15, Loop 1 (bad_spec-Loopback aus Step-04):** Der Review (Blind-Hunter + Edge-Case) fand drei norm-beherrschende Lücken, die die Planung hätte determinieren müssen.
|
|
- Trigger: BH-2 (A0-5/AD-4c unter v1 vakant, nicht prüfbar), BH-4/EC-2 (Provenienz-Ziellinie ohne deterministische Auflöse-Basis, `..`-Traversale), BH-7 (`stable`-Default kollidiert mit v1-unverified-Default).
|
|
- Amendment (non-frozen Tasks): vier neue Tasks konkretisieren (1) Determinismus der `resource`-Auflösung inkl. `..`-Verbot, (2) Orthogonalität `status`/Trust, (3) A0-5 als v1-tautologisch erfüllt statt eigenem Prädikat, (4) Abschluss der Norm inkl. Frontmatter-Exklusivität, frontmatterlose `.md`-Datei, leere Listen, `okf_version`-Fehlwert, abschließende Invaliditätsliste, verbotene leere `by`, korrekte Querverweise, Vertrags-Eigen-Metadaten.
|
|
- Bekannt-bad-State vermieden: Neuerung eines Prädikats, das nie feuert (Intransparenz), undefinierte `resource`-Auflösung (nicht reproduzierbare Kern-AC), stiller Widerspruch `stable` vs. unverified (frisch generierte Concepts als `stable`).
|
|
- KEEP (muss bei Re-Derivation überleben): die gesamte Vertragsstruktur §1–§8 (Geltungsbereich, Bundleroot/`okf_version`, Feldsubset-Themen, `sources`-Liste-von-Maps + `raw/`-Ziellinie, `generated`/`verified` inkl. Actor-Konvention und `human:`-Präfix, `log.md`-Typ, Index-Regel, Concept-/Bundle-Root-Prädikate, strukturell-invalid-vs-optional, Normreferenzen); MUSS/SOLL/KANN-Verbindlichkeitsgrade; v1-Default (generated ohne verified).
|
|
|
|
- **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). Verbleibende Inkonsistenzen wurden als `patch` lokal in den Contract (§7) bzw. die Verification-Sektion (oben) eingearbeitet; Traceability-Ergänzungen (`verified`-Singleton-Coercing, `sources`-Eintrags-Optionalkeys) dokumentieren OKF-0.2-Konformität statt lokaler Erfindung; `log.md`-Position wurde auf die autorisierte Root-only-Position (AD-17b) zurückgeführt. Ergebnis: `schema/wiki-compiler.md` final; der Validator (Story 1.4) implementiert die abschließende 14-Punkte-Invaliditätsliste. Details in `deferred-work.md`.
|
|
|
|
## Design Notes
|
|
|
|
Normative Quelle = PRD §13 fixiert OKF-0.2 (SPEC). Das Schema **normativ legt** fest (Story 1.3 autorisiert, Story 1.4 implementiert Validierung):
|
|
|
|
```yaml
|
|
# Concept (Beispiel)
|
|
type: concept # Pflichtfeld; einziges Pflichtfeld
|
|
sources: # Liste von Maps (keine Map-Form), nur raw/- oder externe Evidenz
|
|
- resource: raw/<quelle>/<datei>.md
|
|
id: s1 # optional; effizient für Zitat-Attribution
|
|
generated: # optional; nur ({by, at}) - by Pflicht innerhalb generated
|
|
by: <producer>/<version>
|
|
at: <ISO 8601 datetime>
|
|
verified: # optional; Liste von {by, at}; human:-Präfix = human reviewed
|
|
status: draft # draft | stable | deprecated; Absenz ⇒ stable
|
|
stale_after: 2026-12-31 # absolutes Datum YYYY-MM-DD
|
|
```
|
|
|
|
- `okf_version: "0.2"` nur in Bundleroot-`index.md`.; Area-`index.md` trägt **kein** Frontmatter (AD-1/AD-9).
|
|
- `log.md`: reservierter Name, kein Frontmatter; flache Liste datumsgruppierter Einträge (neueste zuerst), `YYYY-MM-DD`-Header (OKF §9).
|
|
- `sources`-Provenienz: niemals `wiki/`-Pfade (A0-4/AD-4b); externe Evidenz in v1 nur lokal `raw/` (FR-1/A-4).
|
|
- Der Vertrag bleibt rein textuell (Markdown), kein executable code (AD-1).
|
|
|
|
## Verification
|
|
|
|
**Commands:**
|
|
- `git diff --stat` — expected: `schema/wiki-compiler.md`-Erweiterung (Platzhalter→autorisiert); keine `raw/`- und keine `wiki/`-Mutationen (Updates an `_bmad-output/`-Artefakten — Spec, Sprint-Status, Deferred-Work — sind prozessimmanent und erlaubt).
|
|
- Manuelle Konformitätsprüfung (Liste-von-Maps-Regel, `raw/`-Pfad-Bindung): `grep -c "Liste von Maps" schema/wiki-compiler.md` (expected: ≥ 1) und `grep -n "raw/" schema/wiki-compiler.md` (expected: Provenienz-Ziellinie & deterministische Auflöse-Basis in §3.3).
|
|
- Konformitäts-Smoke-Test an den Referenzdateien (Bundleroot/AC-6): `grep -nE '^type:|^okf_version:' wiki/index.md` (expected: exakt 2 Zeilen `type: bundle` und `okf_version: "0.2"`); `grep -rn "okf_version\|type: bundle" wiki/` (expected: ausschließlich `wiki/index.md`).
|
|
- Referenz-Statik des Vertrags: `grep -oE '§[0-9]+(\.[0-9]+)?' schema/wiki-compiler.md` abgleichen gegen die Markdown-Überschriften (expected: alle Verweise zeigen auf existierende Abschnitte; keine toten Verweise).
|
|
|
|
**Manual checks (if no CLI):**
|
|
- `schema/wiki-compiler.md` beginnt mit klarer `Status: autorisiert`-Kennzeichnung (kein „Platzhalter"-Text mehr).
|
|
- Alle vier AC-Aspekte (Feldsubset, `sources`-Form, Index-Regel+`log.md`-Typ, Provenienz-Verbot) sind abschnittsweise adressiert.
|