mita/wow20
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6105a7bbc066e216a2a10e2edbc7a20b8fbb2547
wow20/_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md
T

13 KiB
Raw Blame History

title, type, created, status, review_loop_iteration, baseline_commit, context
title type created status review_loop_iteration baseline_commit context
OKF-Schema-Vertrag `schema/wiki-compiler.md` autorisieren (Story 1.3) feature 2026-08-14 done 1 4011dc7fc4
_bmad-output/implementation-artifacts/epic-1-context.md

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

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:

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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):

# 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.
Reference in New Issue View Git Blame Copy Permalink