wow20/schema/compiler.md

Compiler-Instruktion — OKF-Concepts aus Source Material erzeugen (Story 2.1)

Status: abgeleitet (Story 2.1) — deterministische, agent-unabhängige Compiler-Instruktion für die Erzeugung neuer Concepts aus Source Material. Normative Grundlage: schema/wiki-compiler.md (autorisiert, Story 1.3) — insbesondere §2 Bundleroot, §3 Feldsubset (§3.1–§3.7), §5 log.md-Typdefinition, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste, §8 Normreferenzen. Prüfgrundlage: schema/validator.md (abgeleitet, Story 1.4; Revision 6) — die Validierung bleibt die mechanische Bestätigung der Konformität (AD-17h). Ableitungsdatum: 2026-08-16 Kanonischer Producer-Actor: wow-compiler/0.1.0

0. Zweck & Aufruf

Diese Datei ist der einzige Ort der Concept-Erzeugungs-Instruktion des Projekts. Sie ist rein textuell — kein ausführbarer Code, kein Standalone-Programm (D-3). Sie wird von einem vorhandenen agentischen Host (AD-11) als deterministische Anweisung befolgt; sie ersetzt kein LLM-Reasoning, sondern kanalisiert es in eine reproduzierbare, textuell nachvollziehbare Abfolge (AD-5, AD-6, AD-17h).

Aufruf: Der Producer führt den Run in der folgenden festen Ablaufstruktur aus (deterministische Reihenfolge): (0) Input prüfen, (1) Interpretieren, (2) Reconcile, (3) Synthetisieren, (4) Mutieren, (5) Validieren. Jede erzeugte Concept-Datei MUSS anschließend gegen schema/validator.md als SUCCESS nachweisbar sein — erst dann gilt der Run als erfolgreich. Bei einem Validierungs-FAIL wird das Bundle nicht als erfolgreicher Run behandelt, raw/ bleibt unangetastet (AD-3), und die Fehlerursache ist textuell identifizierbar (NFR-4). Die Commit-Boundary ist die Mutations-Boundary (AD-17f): Zwischenstände vor Erreichen der Success-Bedingung werden nicht als fertige Mutation veröffentlicht.

Entscheidungsebenen (keine eigene Norm):

Behauptung (Normativ):  schema/wiki-compiler.md  (§7: abschließende 14-Punkte-Liste)
Ableitung (Story 2.1):  schema/compiler.md       (Erzeugungs-Instruktion)
Bestätigung (Story 1.4): schema/validator.md      (mechanische Prüfung, kein LLM-Urteil)

1. Input (what the compiler consumes)

1. Voraussetzung: Der Run verarbeitet ausschließlich veröffentlichte (committete) Inhalte als Input (AD-17a — „Der Compiler darf nur veröffentlichte (committed) Inhalte als Input verwenden"); Zwischenstände während einer Mutation sind nie Input.
2. Evidenz: Das Source Material unter raw/ — jede Datei unter raw/ ist Evidenz (AD-2/AD-3). Vom Compiler erzeugte Concepts DÜRFEN ausschließlich auf solche raw/-Dateien als sources-resource zeigen.
3. Bestehendes Bundle: Das aktuelle wiki/ (Bundleroot index.md, log.md, bestehende Concepts) ist der zweite Input; der Run beginnt mit dem vorhandenen Bundle und verändert nur, was durch neue Erkenntnisse betroffen ist (AD-5 — niemals „Regenerate Everything").
4. Nicht-Evidenz (Artefakt-/Grenzdateien) sind KEIN Input: raw/README.md, jede raw/**/source.md (Provenienz-Sidecar), schema/, adapters/ — sie sind keine zu verarbeitende Evidenz und dürfen nie als sources-resource eines Concepts verwendet werden.

2. Interpretieren (Wissenseinheiten erkennen)

1. Der Producer liest die bereitgestellten Evidenzdateien und identifiziert darin abgegrenzte Wissenseinheiten (ein Thema, ein Konzept, ein zusammenhängender Sachverhalt).
2. Nicht 1:1 pro Dokument, nicht 1:1 pro Abschnitt (FR-5): Ein Dokument kann mehrere Wissenseinheiten enthalten, die in mehrere Concepts fließen; eine Wissenseinheit kann aus mehreren Abschnitten/Dokumenten stammen. Die Anzahl der Concepts ergibt sich aus den erkannten Einheiten, nicht aus der Datei- oder Abschnittszählung der Source.
3. Grenze der Interpretation (Curated ≠ Copy, FR-2/SM-2): Eine Wissenseinheit wird nur dann zum Concept, wenn sie eigenständig formuliertes kuratiertes Wissen ergibt. Bloße Kopie, das Einfügen großer Quellblöcke oder eine Zusammenfassung des Quelldokuments sind keine Wissensintegration und DÜRFEN nicht erzeugt werden.
4. Ein Concept wird in Deutsch formuliert (Projekt-Sprachkonvention) und ist für Menschen unmittelbar als Markdown lesbar (NFR-2).

3. Reconcile (gegen das bestehende Bundle)

1. Vor der Anlage prüfen, ob die erkannte Wissenseinheit bereits als Concept im Bundle existiert (deterministisch: Dateikollision über den relativen OKF-Pfad, AD-7a).
2. Kollision-Hold: Existiert bereits ein Concept mit dem Ziel-Pfad, wird nicht stumm überschrieben. Diese Instruktion deckt die Anlage neuer Concepts ab; die Erweiterung/Präzisierung/Korrektur bestehender Concepts ist Epic 3 (AD-5, FR-6). Der Run bricht für diese Einheit mit einem textuell identifizierbaren Hinweis ab („Concept existiert bereits — Aktualisierung ist Epic 3").
3. Der Run prüft zusätzlich, ob wiki/index.md als Bundleroot existiert (V-1-Vorbedingung des Validators); fehlt sie, darf kein Concept erzeugt werden (Run-FAIL, Vertrag §2).

4. Synthetisieren (Provenienz & Trust)

Je neuem Concept werden die Frontmatter-Metadaten nach Vertrag §3 festgelegt:

1. type (Pflicht, §3.1): ein nicht-leerer String; für fachliche Wissenseinheiten ist concept die Standard-Klasse.
2. sources (optional, §3.3): Liste von Maps; je Eintrag MUSS resource gesetzt sein. Regeln:
   • resource ist ein /-getrennter relativer Workspace-Pfad innerhalb raw/ — nie wiki/ (AD-4b/Punkt 3), kein .., kein führendes /, kein Backslash/Windows-Trenner, keine URL-Form (Punkt 4).
   • Jede referenzierte Datei MUSS unter raw/ zum Zeitpunkt des Runs als Datei existieren (EC-1; Verzeichnisse sind unzulässig).
   • Zusätzlich zu resource sind optional zulässig: id, title, author, usage_count (Ganzzahl ≥ 0), last_modified (YYYY-MM-DD, reale Kalenderdaten).
   • Key-Subset je Eintrag (Innen-Ebene, Vertrag §3.3): Innerhalb eines sources-Eintrags sind ausschließlich die Felder resource, id, title, author, usage_count, last_modified erlaubt — jeder andere Key ist eine unautorisierte Verletzung und löst beim Validator Punkt 6 aus (nicht nur die Top-Level-Felder zählen).
3. generated (v1-Default, §3.4/A0-20): Map { by, at }. by ist zwingend und nicht leer; Produkt-Konvention: wow-compiler/0.1.0 (dieser Compiler). at ist der Ausführungszeitpunkt in vollem ISO-8601-Datetime (YYYY-MM-DDTHH:MM:SS mit Z/±HHMM/±HH:MM), nie ein reines Datum (Validator §4.3, Punkt 14). verified bleibt ungesetzt — maschinell erzeugt und ungeprüft (A0-20).
4. status/stale_after (optional): nur Werte aus §3.6 (draft/stable/deprecated) bzw. §3.7 (YYYY-MM-DD). Bei der Erzeugung neuer Concepts bleibt beides in der Regel ungesetzt — die Absenz von status bedeutet laut Vertrag §3.6 per Definition den Default stable; der Compiler trifft also bewusst keine Lebenszyklus-Entscheidung, sondern überlässt den Default der Vertrags-Semantik.
5. Frontmatter-Reihenfolge (kanonische Normalform, Validator §4.1): type, sources, generated, verified, status, stale_after. Duplikat-Keys sind verboten (Punkt 13). Keine unautorisierten Felder (Punkt 6); okf_version/type: bundle NIE in Concepts (Punkt 9).

5. Mutieren (Dateien schreiben)

1. Ziel-Pfad: Das neue Concept ist eine Markdown-Datei unter wiki/. In dieser Story (keine deterministische Area-Zuordnung; Story 2.4) werden neue Concepts auf Root-Ebene angelegt: wiki/<concept-kebab-case>.md. Es wird kein wiki/<area>/-Verzeichnis angelegt; ein als Area gedachtes Ziel (Unterverzeichnis) wird bis Story 2.4 abgelehnt und führt zu einem textuell identifizierbaren Hinweis („Area-Zuordnung ist Story 2.4").
   • Konvention für den Dateinamen: kebab-case-Slug aus der Concept-Identität (kein Sonderzeichen, keine Endung .md-Dopplung). Der Dateiname definiert die Concept-Identität (relativer OKF-Pfad ohne .md, AD-7a).
2. Dateiinhalt: YAML-Frontmatter gemäß §4 (kein weiteres Feld), gefolgt von einem Markdown-Body, der die Wissenseinheit eigenständig und lesbar darstellt (NFR-2, NFR-3). Der Body darf keine grossen Quell-Exzerpte enthalten (FR-2). Claim-granulare Inline-Provenienz (AD-4a) ist Story 2.2 und wird hier nicht gefordert.
3. Index-Regel (Punkt 11/§6): Nach Anlage MUSS das neue (Root-)Concept in der Bundleroot wiki/index.md verlinkt werden — seine Identität (relativer OKF-Pfad ohne .md) als relativer Bundle-Pfad referenziert, mit oder ohne .md-Endung (eine genau-eine-Form-Festlegung ist Story 2.3). Ohne diese Verlinkung ist das Bundle strukturell invalide (§7 Punkt 11).
   • All dies (Anlage + Verlinkung + log.md) erst abschließen, wenn die Validierung (§6) SUCCESS liefert. Zwischenstände werden nicht als fertige Mutation veröffentlicht — Commit-Boundary ist die Mutations-Boundary (AD-17f).
4. Dokumentation (log.md, Vertrag §5): Die Anlage neuer Concepts wird als datumsgruppierter Eintrag in wiki/log.md dokumentiert (neueste zuerst; Header = ISO-Datum YYYY-MM-DD), verknüpft mit dem neuen Concept-Pfad und den genutzten raw/-Quellen. log.md bleibt ohne Frontmatter (Punkt 10).

6. Validieren (mechanische Bestätigung)

1. Nach Abschluss aller Mutationen wird das gesamte Bundle gemäß schema/validator.md geprüft (§3 14 Punkte je Datei + §6-Fachprüfungen; Verdikt-Grammatik §5).
2. Erfolgsbedingung: Alle Dateien unter wiki/ — Bundleroot, log.md, sämtliche neuen Concepts — liefern SUCCESS (kein FAIL; stale_after-WARN wäre nur Berichtskanal). Dabei ist insbesondere Punkt 11 (Index-Regel) zu bestätigen: jeder neue Root-Concept-Pfad ist in wiki/index.md verlinkt.
3. Bei jedem FAIL gilt der Run als gescheitert; es werden keine weiteren Mutationen durchgeführt, raw/ bleibt unangetastet (AD-3), und die Fehlerursache wird textuell benannt (NFR-4).
4. Der Producer hält das Verdikt-Ergebnis (je Datei SUCCESS/FAIL) als Ausführungs-Nachweis fest (z. B. in der Story-Spezifikations-Verification oder im Run-Bericht).

6.5 Determinismus- & Selbsttest-Norm (Nachprüf-Sektion)

Jede Erzeugungsentscheidung dieser Instruktion ist textual-deterministisch begründbar (AD-13): die erkannten Wissenseinheiten (§2), die Reconcile-Kollisionsprüfung (§3), die Frontmatter-Werte (§4) und die Ziel-Pfade (§5) folgen aus dem Input ohne probabilistische Verfahren. Es gibt keine Embedding-/Vector-Infrastruktur und kein reines LLM-Urteil als alleinige Entscheidungsbasis.

Vor Abschluss eines Runs prüft der Producer jedes erzeugte Concept gegen die folgenden drei Selbsttest-Kriterien (AD-17h-konform; der Validator in §6 bleibt die mechanische Prüfung, diese Kriterien sind seine Vorab-Projektion):

1. Vollständige §3-Subset-Konformität: Das Frontmatter enthält ausschließlich Keys aus {type, sources, generated, verified, status, stale_after} in kanonischer Reihenfolge (§4.1 des Validators); type ist gesetzt und non-empty; keine Duplikat-Keys (Punkt 13, auch innerhalb von sources/generated/verified-Einträgen); Keine unautorisierten Keys — weder auf Top-Level-Ebene noch innerhalb von sources/generated/verified-Einträgen (Vertrag §3.3/§3.4/§3.5, Punkt 6); okf_version/type: bundle kommen nicht vor (Punkt 9).
2. at-Normalform: generated.at (und ggf. verified[].at) ist ein volles ISO-8601-Datetime YYYY-MM-DDTHH:MM:SS mit Z/±HHMM/±HH:MM — keine reine Datumsangabe (Punkt 14; Validator §4.3).
3. sources-Existenz: Jeder sources[].resource verweist auf einen /-getrennten relativen Pfad unter raw/, der zum Validierungszeitpunkt als Datei existiert (EC-1); kein .., kein führendes /, kein Backslash, keine URL-Form, kein wiki/-Pfad (Punkt 3/4, §6.2).

Weicht ein erzeugtes Concept in mindestens einem Kriterium ab, wird es nicht als erfolgreiche Erzeugung behandelt; der Run korrigiert oder verwirft die Datei und dokumentiert die Abweichung textuell (NFR-4) — es fließt nichts Ungeprüftes in das Bundle.

6.6 Positiv-/Negativ-Beispiele (Referenztabellen)

Die folgende Tabelle macht jede Erzeugungsregel dieser Instruktion reproduzierbar nachprüfbar (AD-17h, Verifikations-Kultur aus Story 1.4 — Verifikations-Beleg). „✓" = ideal-konform (erwartet: Validator-SUCCESS), „✗" = verletzte Regel (erwartet: Validator-FAIL mit der genannten Fehlerursache).

Regel (§)	✓ Positiv-Beispiel	✗ Negativ-Beispiel (Fehlerursache)
§4.1 type Pflicht (§3.1)	type: concept	type: (leer) → Punkt 1
§4.1 Feldsubset (§3)	nur type, sources, generated	foo: bar → Punkt 6
§4.2 sources[].resource → raw/ (§3.3, AD-4b)	resource: raw/prd/prd-wow20-2026-08-14.md	resource: wiki/foo.md → Punkt 3
§4.2 Path-Grammatik (§3.3, Punkt 4)	/-getrennt, relativ, unter raw/	resource: ../outside.md → Punkt 4
§4.2 EC-1-Existenz (§3.3, §6.2)	resource: raw/prd/prd-wow20-2026-08-14.md (Datei existiert)	resource: raw/fehlt.md → EC-1
§4.3 generated.by Pflicht (§3.4)	generated: {by: wow-compiler/0.1.0, at: …}	generated: {at: …} (ohne by) → Punkt 7
§4.3 generated.at volles ISO-8601-Datetime (§3.4, Validator §4.3)	at: 2026-08-16T09:23:33Z	at: 2026-08-16 (reines Datum) → Punkt 14
§4.3 verified ungesetzt (A0-20)	(kein verified)	verified: {by: human:x, at: …} → Punkt 6 (unautorisiertes Feld, nur maschinelle Erzeugung A0-20), hier nicht erzeugt
§4.4 canonical Key-Reihenfolge (Validator §4.1)	type → sources → generated	Reihenfolge generated vor type → Normalform-Abweichung (kein FAIL, aber nicht erzeugt)
§4.4 keine Duplikat-Keys (Punkt 13)	jeder Key einmal	zweimal type: → Punkt 13
§4.4 sources-Eintrag-Key-Subset (Vertrag §3.3)	nur resource, id, title, author, usage_count, last_modified	resource … + z. B. role: x → Punkt 6 (unautorisiertes Feld, Innen-Ebene)
§4.4 kein okf_version/type: bundle (Punkt 9)	(nicht vorhanden)	okf_version: "0.2" → Punkt 9
§5.1 Root-Pfad & Verlinkung (Punkt 11, §6)	wiki/<slug>.md + Link in wiki/index.md	Concept ohne Link in index.md → Punkt 11; wiki/<area>/<slug>.md → Bereichs-Hinweis (Story 2.4)
§5.4 log.md-Dokumentation (§5)	datumsgruppierter Eintrag mit Concept-Pfad + Quellen	fehlender Eintrag → kein Validator-FAIL, aber dokumentarische Pflicht verletzt
§6.4 Allen-Pfad-Formen-Vermeidung (Punkt 4)	/-getrennt, relativ, unter raw/	..-Traversal, führendes /, Backslash (raw\foo.md), URL-Form (https://…) → Punkt 4
§7 Selbstbegrenzung (kein Standalone, D-3)	rein textuelle Instruktion	Code-/Executable-Abschnitt → D-3-Verstoß

Interpretations-Hinweis: Die „✗"-Zeilen zeigen die deterministische Fehlerursache, die der Validator (Story 1.4) für die jeweilige Abweichung ausgibt. Die „✓"-Zeilen sind die Vorgabe, unter der ein neu erzeugtes Concept den Run passieren kann — genau diese Form wurde im Demonstrationslauf (2026-08-16) gegen alle 3 erzeugten Concepts erfüllt.

7. Selbstbegrenzung (Scope der Instruktion)

Diese Instruktion ist auf die Erzeugung neuer Concepts auf Root-Ebene begrenzt. Folgendes verbleibt in anderen Stories und wird hier nicht vorweggenommen:

• Claim-granulare Provenienz je belegter Aussage (Inline-raw/-Verweise, Kontext-Marker) → Story 2.2 (AD-4a, A0-3).
• Deterministische Area-Zuordnung & Concept-Hierarchie (Anlage von wiki/<area>/index.md + wiki/<area>/<concept>.md) → Story 2.4 (AD-7c, A0-10).
• Progressive Discovery über index.md (Navigation, Area-Indizes, Suche) → Story 2.5 (AD-9, FR-11).
• Eine genau-eine-Linkform (mit/ohne .md-Endung) → Story 2.3 (AD-7b, A0-9) — der Punkt-11-Check akzeptiert beide Schreibweisen.
• Aktualisierung bestehender Concepts (Erweitern/Präzisieren/Korrigieren) und Synthese über mehrere Concepts → Epic 3 (AD-5, FR-6/FR-7).
• Standalone-Compiler / eigene LLM-Runtime / MCP → verboten in v1 (D-3, D-4, AD-11).
• OKF-Dialekt / Schema-Erweiterung → niemals (AD-1a; Vertrag §7 „abschließende Liste").

8. Normreferenzen & Revisionslog

Normreferenzen (read-only):

• schema/wiki-compiler.md — autorisierter Vertrag (Story 1.3): §2 Bundleroot, §3.1–§3.7 Feldsubset & Formate, §5 log.md-Typ, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste, §8 Normreferenzen.
• schema/validator.md — Prüfgrundlage (Story 1.4, Revision 6): §3 14 Punkte, §4 Normalform (Reihenfolge §4.1, ISO-8601 §4.3), §5 Verdikt, §6 Fachprüfungen (EC-1 Existenz, EC-3 Kalender, EC-11 non-md).
• Architektur-Spine (raw/architecture-spine): AD-2/AD-3 (raw immutable), AD-5 (inkrementelle Kompilation), AD-6 (Reason/Mutate-Trennung), AD-7a (Identität = OKF-Pfad ohne .md), AD-10 (agent-unabhängige Regeln), AD-11 (keine eigene Runtime), AD-15 (Trust-Metadaten v1), AD-17a (nur veröffentlichte/committete Inhalte als Input), AD-17f (Commit-Boundary = Mutations-Boundary), AD-17h (Determinismus), D-3 (kein Standalone).
• PRD (raw/prd): FR-2 (Sources vs. Curated), FR-5 (Concept-Erzeugung), FR-9 (OKF-Konformität), A-4 (nur lokale Sources).
• Epics (raw/epics): Story-2.1-Ziel und -Abgrenzung zu Story 2.2–2.5.

Revisionslog:

• Revision 1 (2026-08-16): Erstes abgeleitetes Artefakt — Concept-Erzeugung als deterministische Instruktion: Input-Grenzen (§1), Interpretieren (Wissenseinheiten, kein 1:1/keine Kopie, §2), Reconcile (Kollision-Hold, §3), Synthetisieren (Frontmatter-Normalform, §4), Mutieren (Root-Ebene + Index-Regel + log.md, §5), Validieren (Validator-SUCCESS als Erfolgsbedingung, §6), Selbstbegrenzung (§7).
• Revision 1.1 (2026-08-16): Nach dem Demonstrationslauf ergänzt — §6.5 Determinismus- & Selbsttest-Norm (drei Nachprüf-Kriterien: §3-Subset-Konformität, at-Normalform, sources-Existenz; AD-17h-konform) und §6.6 Positiv-/Negativ-Beispiele (Referenztabellen je Erzeugungsregel mit deterministischer Fehlerursache). Revisionslog (§8) nachgeführt; §6-Nummerierung angepasst.
• Revision 1.2 (2026-08-16, Step-04-Review): Nachschärfungen aus dem Story-2.1-Review — Input-Regel korrekt auf AD-17a statt AD-17.2 referenziert (§1); sources-Eintrag-Key-Subset (Innen-Ebene, Vertrag §3.3) in §4.2 und als §6.5-Kriterium-1 / §6.6-Tabellenzeile ergänzt; status-Absenz-Formulierung an die Vertrags-Definition (Absenz = stable, §3.6) angebunden (§4.4); Klarstellung Bereichs-Ziele bis Story 2.4 (§5.1/§6.6); §6.6-Fehlerursache der verified-Zeile auf Punkt 6 korrigiert; §6.6-Referenzlabel von §4.5 auf §4.4 korrigiert; §6.6 um vollständige Punkt-4-Pfad-Verbote ergänzt; AD-17f als Commit-Boundary in §0/§5.3/§6.6 sichtbar gemacht.