Compare commits
22
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
802a5576eb | ||
|
|
ef84309db7 | ||
|
|
f41ac71a38 | ||
|
|
20fd47624d | ||
|
|
64a0f6a616 | ||
|
|
e6e58cbdb1 | ||
|
|
862cf410c6 | ||
|
|
66451b6e6c | ||
|
|
bb7db2d025 | ||
|
|
7e1f449bf7 | ||
|
|
6d8d172c98 | ||
|
|
58d33f7f3c | ||
|
|
bb32acdf3f | ||
|
|
ae5e0aa71f | ||
|
|
e6c36fc6d9 | ||
|
|
f91ef89078 | ||
|
|
6105a7bbc0 | ||
|
|
a67ba65910 | ||
|
|
6cc667dd55 | ||
|
|
c5f97c3666 | ||
|
|
33d21cb0ad | ||
|
|
9e163adf1b |
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -5,6 +5,7 @@ Noch nicht adressierte, aber real erkannte Arbeit — gesammelt aus Reviews. Ein
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-2-sources-lokal-unter-raw-bereitstellen.md`
|
||||
summary: Checksum-/Fingerprint (SHA-256) der evtl. Git-Revision der Herkunftsquelle in `source.md` aufnehmen, damit die Provenienz reproduzierbar ist.
|
||||
evidence: Blind-Hunter-Review (Finding 1/2): `source.md`-Provenienz ist ohne Fingerprint der Quelle in einem reinen Clone nicht verifizierbar; AD-3-basiertes „neue, datierte Datei"-Schema braucht einen Maschinen-Lesbaren Stand.
|
||||
status: umgesetzt (2026-08-16, Retrospective F-09/AI-4) — Commit-Hash `6cc667d` + SHA-256 der jeweiligen Herkunftsdatei in allen drei `raw/*/source.md` aufgenommen; Byte-Identität zur materialisierten Evidenz geprüft.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-2-sources-lokal-unter-raw-bereitstellen.md`
|
||||
summary: Maschinen-lesbares, validierbares Metadaten-Schema (YAML-frontmatter) für `source.md` einführen.
|
||||
@@ -17,3 +18,284 @@ Noch nicht adressierte, aber real erkannte Arbeit — gesammelt aus Reviews. Ein
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-2-sources-lokal-unter-raw-bereitstellen.md`
|
||||
summary: Asset-Zuordnung (roh-`assets/` vs. `<quelle>/assets/`) in der Konvention festlegen.
|
||||
evidence: Blind-Hunter-Review (Finding 14): README nennt „einer Quelle zugeordnet oder global"; die aktuellen Sources nutzen nur global `raw/assets/`.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Existenzprüfung eines `sources`-`resource`-Pfads (für Validity-Zwecke MUSS die `raw/`-Datei am Validierungszeitpunkt materialisiert vorliegen).
|
||||
evidence: Edge-Case-Review (EC-1): ein `resource` unter `raw/`, das nicht existiert, würde als Provenienz akzeptiert; der Compiler konsumiert fehlende Evidenz. Validator-Verhalten (Story 1.4), nicht Schema-Text.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Kalender-Validität der Datumsfelder (`last_modified`, `stale_after`, `generated.at`/`verified.at`) — Phantom-Daten wie `2025-02-30` müssen abgelehnt werden.
|
||||
evidence: Edge-Case-Review (EC-3): reines Regex-Matching (`YYYY-MM-DD`) akzeptiert nicht existierende Kalenderdaten. Validator-Detail (Story 1.4).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Operative Konsequenz von `stale_after` festlegen (Lifecycle-Übergang, Nutzungssperre als `sources`-Ziel o. ä.).
|
||||
evidence: Blind-Hunter (BH-8): §3.7 definiert nur die Veraltungsschwelle, nicht was ein veraltetes Concept bedeutet; die Folgeentscheidung gehört in Story 1.4/Lifecycle (Epic 3).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: `sources`-`id`-Eindeutigkeit (je `resource` bzw. je Concept) für zuverlässige per-Claim-Zitat-Attribution festlegen.
|
||||
evidence: Blind-Hunter (BH-13): §3.3 motiviert `id` für Attribution, ohne Eindeutigkeit/Scoping zu fordern; Claim-granulare Provenienz (A0-3) wird in Epic 2 konkretisiert.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Verhalten nicht-Markdown-Dateien im Bundle (z. B. Bilder/Assets unter `wiki/`) definieren — Ablehnung oder Konvention.
|
||||
evidence: Edge-Case-Review (EC-11): der Vertrag regelt nur `.md`-Dateien; ein `wiki/<area>/logo.png` hat keinen definierten Status. Structural-Seed-/Validator-Frage (Story 1.4).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Exakte ISO-8601-Form für `generated.at`/`verified.at` festlegen (z. B. `YYYY-MM-DDTHH:MM:SS(Z|±HH:MM)?`, reine Datumsangaben zulässig?).
|
||||
evidence: Blind-Hunter (BH-14)/Edge-Case-Review (EC-7): „ISO-8601-Datetime" lässt den Validator-Spielraum; Story 1.4 muss eine Normalform bestimmen, um Run-Determinismus zu sichern.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Normalisierung von `sources: []`/`verified: []` vs. Absenz für deterministische Ausgabe-/Diff-Baselines klären.
|
||||
evidence: Edge-Case-Review (F2, Loop 2): beide Formen sind laut Vertrag gültig und semantisch gleichwertig; NFR-4 („sinnvolle Diffs") bleibt unterdeterminiert. Normierungsentscheidung des Compilers/Validators — Story 1.4.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Trust-Semantik von `generated.by` mit `human:`-Präfix festlegen (Person als Generator vs. „human-reviewed"-Klassifikation).
|
||||
evidence: Edge-Case-Review (F15, Loop 2): `generated.by: human:michael` ohne `verified` ist formzulässig, aber die Trust-Klassifikation (nicht-human-reviewed trotz `human:` in `generated.by`) ist für Leser missverständlich. Für Story 1.4/Epic 4 (Trust-Metadaten) klären.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Reihenfolge/atomare Kopplung von `log.md`-Eintrag (AD-16b) und `status`-Mutation (Deprecation) in denselben Compilation Run festlegen.
|
||||
evidence: Edge-Case-Review (F5, Loop 2): `status: deprecated` erfordert einen `log.md`-Disagreement-Eintrag; der Vertrag regelt nicht die atomare Kopplung dieser zwei Bundle-Mutationen. AD-16/Story 4.2/Compiler-Verhalten.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Feingranularität von `log.md` festlegen (leeres Log zulässig? Pflicht der AD-16-Konfliktklassifikation je Eintrag?).
|
||||
evidence: Edge-Case-Review (F17, Loop 2): §5 definiert Format (Datum + Eintragsliste), aber nicht, ob ein leeres `log.md` gültig ist bzw. ob die Konfliktklassifikation Pflicht-Inhalt je Eintrag ist. OKF §9-Feinheiten für Story 1.4.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
summary: Semantische Konsequenz von `stale_after` im Verhältnis zur Validität klären („veraltet" ist kein struktureller Validierungsfehler).
|
||||
evidence: Edge-Case-Review (F18, Loop 2): §7 zählt die Konsequenz nicht auf; ein vergangenes `stale_after` ist gültiges YAML, aber „veraltet". Lifecycle-Semantik — Story 1.4/Epic 3.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-1-4-schema-validierung-für-bundle-implementieren.md`
|
||||
summary: Genau-eine-erlaubte-Linkform für den Punkt-11-Index-Check festlegen (mit vs. ohne `.md`-Endung) — Story 2.3.
|
||||
evidence: Step-04-Review (Story 1.4, Loop 1): Der Validator-Punkt-11-Check akzeptiert beide Linkformen (relativer Bundle-Pfad mit oder ohne `.md`-Endung), weil die genau-eine-Form-Regel (A0-9/AD-7b) erst Story 2.3 definiert. Der Determinsmus-Anspruch des Validators bleibt gewahrt (beide Formen zählen als verlinkt); eine Endungs-Festlegung würde die abschließende §7-Liste erweitern und gehört in Story 2.3.
|
||||
status: umgesetzt (2026-08-17, Story 2.3) — Linkform in `schema/compiler.md` §5.6 gepinnt (bundle-relativ **mit** `.md`-Endung; Rationale: Null-Migration der 3 Concept-Links in `wiki/index.md`, explizite Datei-Ziele, Standard-Markdown-Tools — AD-7b/A0-9/FR-10/AD-8) inkl. vier re-executierbarer Selbsttest-Formeln (AD-17h). Der Validator bleibt strukturell unverändert (Punkt 11 akzeptiert beide Schreibweisen — Story-2.2-Präzedenz, D-3); die konsistente Nachführung der „Story 2.3"-Notizen in `schema/validator.md` (Punkt 11, §8) bleibt Rev-9-Kandidat (Eintrag unten).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md`
|
||||
summary: F-03/AI-3 — gewählter Weg dokumentiert: §3.2-Voraussetzungsprüfungen als V-1/V-2-fachliche Prüfklasse (Revision 5). Die alternative Option „Vertrag §7 um Fall ‚fehlende Bundleroot' erweitern (mit Autorisierung)" wurde bewusst NICHT gewählt; sollte später ein Fall „fehlende Bundleroot" in den §7-Katalog selbst (statt als V-1) gefordert sein, ist dies nachzuholen (Vertrags-Änderung via Story-Verfahren).
|
||||
evidence: Retrospective F-03 Disposition „Fix-now (als fachliche Prüfungen V-1/V-2 labeln … oder Vertrag §7 erweitern)" — Entscheidung für Option 1 getroffen (2026-08-16, AI-3).
|
||||
|
||||
## Folge-Aufgaben aus Epic-1-Retrospective (Defer-Kontexte, AI-7; 2026-08-16)
|
||||
|
||||
> Diese Einträge sichern die von der Epic-1-Retrospective (2026-08-15) als Defer klassifizierten Befunde als konkrete Folge-Aufgaben. Sie sind **nicht** durch die Validator-Revisionen 3–6 behoben — nur als Kontext für Epic-2/3 bzw. die nächste Validator-Revision notiert.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-04)
|
||||
summary: Verschachtelte Duplikat-Keys in `sources`/`verified`-Einträgen behandeln — Punkt 13 zählt nur doppelte Keys auf oberster Frontmatter-Ebene; YAML erlaubt mehrdeutig doppelte `resource`-Keys innerhalb eines Eintrags (Parser-abhängiger Gewinner). Bei der nächsten Validator-Revision (Epic-2-Start) klären: Abdeckung der Innen-Ebenen oder bewusst dokumentierte Abgrenzung.
|
||||
evidence: Retrospective F-04.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-06)
|
||||
summary: `today`-Zeitzone für die `stale_after`-WARN (Validator §6.4) deterministisch festlegen — „heute in UTC abgeleitet" ist nicht hart definiert (Kalenderdatum des UTC-Zeitpunkts vs. lokaler Tag). Determinsmus-Anspruch (AD-17h) vor Epic-3 (Lifecycle-Konsequenz) sauber machen.
|
||||
evidence: Retrospective F-06.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-07)
|
||||
summary: Index-Regel bei verschachtelten Areas/Unter-Ebenen konkretisieren — „Area als eine `index.md` tiefer als `wiki/`" lässt für `wiki/a/b/concept.md` offen, was „Area mit Inhalt" ist. Epic-2-Story 2.5 (progressive Discovery) legt die Antwort fest; vorher gilt die heutige Definition.
|
||||
evidence: Retrospective F-07; Offene Frage 2 der Retro; spec-1-4 Story 2.3-Linkform.
|
||||
status: umgesetzt (2026-08-18, Story 2.5 — konsolidierte Zwei-Ebenen-Kartografie, §5.8)
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-08)
|
||||
summary: Konvention für `.MD`-Großschreibung unter `wiki/` klären (Windows-Portabilität, NFR-1/NFR-5) — heute ist nur exakt `.md` (case-sensitive) ein Concept; auf win32 kann ein Tool `foo.MD` erzeugen. Vor Epic-2-Concepts entscheiden: Ablehnung/FAIL oder case-insensitive Behandlung.
|
||||
evidence: Retrospective F-08.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-11)
|
||||
summary: Normreferenz der OKF-0.2-Spezifikation verlinkbar machen (Vertrag §8, Validator §8) — das Prosa-Zitat „OKF-Spezifikation (Google Cloud, `knowledge-catalog`)" ohne URL/Version ist nicht auflösbar; `okf_version`-Regel und §7-Punkt-14 hängen daran. Kleine Korrektur bei nächster Autorisierung (Vertrag) ergänzen.
|
||||
evidence: Retrospective F-11.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md` (F-14)
|
||||
summary: Negativ-Fixture für `resource`-Pfade, die außerhalb `raw/` landen aber existieren (z. B. `README.md`) — §6.2 Schritt 5 deckt den Fall ab, aber das Durchstechen ist nur durch Beispiele belegt. Fixture bei nächster Validator-Revision ergänzen (analog §7.3).
|
||||
evidence: Retrospective F-14.
|
||||
|
||||
## Folge-Aufgaben aus Story-2.1-Review (Defer-Kontexte; 2026-08-16)
|
||||
|
||||
> Diese Einträge sichern die im Step-04-Review von Story 2.1 als Defer klassifizierten Befunde als konkrete Folge-Aufgaben. Sie sind **nicht** durch die Nachschärfungen (compiler.md Revision 1.2, validator.md Revision 7, index.md, log.md, sprint-status) behoben.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md` (Story-2.1-Review)
|
||||
summary: Content-Truth-Verifikation einführen — kein bestehender Check verifiziert, dass der Body eines Concepts seinen deklarierten `raw/`-Quellen (Inhalt) entspricht. Die drei Concepts sind aktuell inhaltlich korrekt (Spot-Checks im Review bestätigt), aber Validator (§3 rein strukturell), spec-Verification (grep-Smoke) und compiler.md-Selbsttests (Kriterien 1–3) decken nur Form/Existenz, nicht den Inhalt. Verifikation, dass erfundenes/gegenläufiges Body-Content nicht als kuratierte Wahrheit durchgeht, ist die Kern-Fähigkeit (FR-2/FR-5).
|
||||
evidence: Verification-Gap-Review (Story 2.1): Demonstriert — Body-Fälschung bei byte-identischem Frontmatter ändert kein Verdikt und keinen grep-Check. Für Story 2.2 (Claim-granulare Provenienz, AD-4a/A0-3) bzw. eine spätere Inhaltstreue-Prüfung.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md` (Story-2.1-Review)
|
||||
summary: Determinismus-Selbsttest-Dokumentation in `schema/compiler.md` schärfen — §6.6-Interpretations-Hinweis behauptet, die ✓-Form sei „genau diese Form … im Demonstrationslauf erfüllt"; da `generated.at` pro Run variiert (Ausführungszeitpunkt, AD-15), ist der Selbsttest (Kriterium 2 „at-Normalform") als Form-Verifikation über die Normalform statt über einen festen `at`-Sekundenwert zu formulieren, damit ein „Regenerate"-Vergleich auf einem OTHER-Diff-Basis nicht an der Run-Zeit scheitert (Punkt-14-sicher). Für Story 2.3 (Determinismus/A0-7-Verifikation) bzw. nächste Validator-Revision.
|
||||
evidence: Edge-Case-Review (Story 2.1): „Determinism self-test compares generated.at which varies per run" — eines von mehreren als Defer klassifizierten Findings (die übrigen ebenfalls in diesem Block).
|
||||
|
||||
## Deferred from: code review of story-2.1 (2026-08-16)
|
||||
|
||||
> **Code-Review-Defer (bmad-code-review, 2026-08-16):** Diese Einträge decken die im externen Adverse-Review von Story 2.1 als Defer klassifizierten Befunde ab, die bewusst nicht in Story 2.1 behoben werden. Sie sind getrennt von den Step-04-Review-Defer-Kontexten oben (die der Implementierung selbst entstammen).
|
||||
|
||||
> **Dedupe-Verweis (bmad-code-review Re-Run, 2026-08-17):** „Content-Truth-Verifikation einführen" und „Determinismus-Selbsttest-Dokumentation schärfen" wurden am 2026-08-16 bereits im Block „Folge-Aufgaben aus Story-2.1-Review (Defer-Kontexte; 2026-08-16)" oben erfasst (gleicher Tag, nahezu identischer Text, nur anderes `source_spec`-Label). Die Ownership liegt dort; dieser Code-Review-Block trägt beide Punkte **nicht** ein zweites Mal (vermeidet Doppel-Erledigung). Konkret: Content-Truth → Story 2.2; Determinismus-Selbsttest → Story 2.3 / nächste Validator-Revision.
|
||||
|
||||
- source_spec: `schema/validator.md` (Story 1.4) — aufgelöst via Option A
|
||||
summary: Frieren-Verletzung heilen — die Innen-Ebenen-Klarstellung (Punkt-6 / Key-Subset auf `sources`/`generated`-Eintragsebene), die Spot 2.1 als Rev-7-Notiz in `schema/validator.md` eingetragen hat, muss in der **nächsten autorisierten Validator-Revision** formal mitlaufen (gemeinsam mit der F-14-Negativ-Fixture). Dadurch verliert die Abweichung ihren Status als unautorisierte Mutation und Story 2.1 ist `done`-fähig. Der Rev-7-Hinweis bleibt bis dahin erhalten (kein Rückbau).
|
||||
evidence: Code Review (Story 2.1) — Decision-Befund, aufgelöst als Option A am 2026-08-16.
|
||||
|
||||
- source_spec: `raw/README.md` (Konvention, Story 1.2) — R-1
|
||||
summary: R-1 (Compiler-Input-Interface) — Verdikt **Bestanden**: `schema/compiler.md` definiert seine Source-Eingabe als Menge beliebiger `raw/`-Dateien (Set-Interface, §1.2 „jede Datei unter `raw/` ist Evidenz"), nicht als einzelnen Pfad. Der erkennungsseitige Mechanismus, WELCHE `raw/`-Dateien wann verarbeitet werden („Run-ohne-Pfad"-Nutzererwartung aus DRYRUN.md: Kompilation via git diff + SHA-256-Record aus den `source.md`-Records), ist bewusst nicht in Story 2.1 enthalten und gehört als Erkennungs-/Auswahl-Mechanismus in die AD-5-Home-Story (Epic 3, Story 3.1/3.2).
|
||||
evidence: Code Review (Story 2.1) R-1 — Epic-3-Forward-Risk, keine AC-Verletzung.
|
||||
|
||||
- source_spec: `raw/README.md` / `schema/compiler.md` §1.2–§1.4 — R-2
|
||||
summary: R-2 (Nicht-Markdown-Quellen) — Verdikt **Bestanden**: die Compiler-Instruktion liest Sources endungsneutral als Datei (§1.2/§1.4), unterstellt keine `.md`-Endung; PDF ist zulässige Evidenz (Vertrag §3.3 verlangt nur einen Dateipfad unter `raw/`, Validator EC-1 prüft nur Existenz). Die Konventions-/Asset-Zuordnungsfrage (Namensschema für Nicht-Markdown-Quellen) bleibt offen und gehört zu Epic 2/3 (Nutzer-Input-Gestaltung für den Dryrun-Forderungskatalog). Als dokumentarischer Hinweis: §1.2/§1.4-Widerspruch („jede Datei ist Evidenz" vs. „Artefakt-Dateien sind KEIN Input") in der Instruktion selbst klären (siehe Patch-Findings in der Story).
|
||||
evidence: Code Review (Story 2.1) R-2 — Konventionsfrage, kein Blocker.
|
||||
|
||||
## Deferred from: code review of story-2.1 (2026-08-16) — Arbeitsauftrag: autorisierte Validator-Revision (Option-A-Heilung)
|
||||
|
||||
> **Konkreter Arbeitsauftrag (aus Re-Review vom 2026-08-16):** Sobald die nächste **autorisierte Validator-Revision** beginnt (Story-/Autorisierungs-Kanal, Bereich `schema/`, Konsistenz mit dem Story-1.4-Prozess), sind die folgenden drei Punkte dort formal zu tragen. Sie machen Story 2.1 `done`-fähig und schließen die Referenzkette compiler.md → validator.md sauber. `validator.md` selbst bleibt bis dahin unverändert (Frieren/AD-3).
|
||||
|
||||
- summary: **1. F-14-Negativ-Fixture ergänzen** — ein `resource`-Pfad, der außerhalb `raw/` landet, aber existiert (z. B. `resource: README.md`), hat bislang kein Negativ-Fixture; §6.2 deckt den Fall, §7.1-Fixtures belegen ihn nicht (Retrospective F-14, epic-1-retro AI-7). In der autorisierten Revision als Negativ-Fixture ergänzen (erwartetes Verdikt: `FAIL … Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (…|…)`), Beleg unter §7.1 (Punkt 4).
|
||||
- summary: **2. Innen-Ebenen-Key-Subset-Klarstellung formal tragen** — die heute als unautorisierte Rev-7-Notiz in `validator.md` §7.3 (Punkt 6: unautorisierte Keys innerhalb `sources`/`generated`/`verified`-Einträgen, Vertrag §3.3–§3.5) liegende Klarstellung wird Teil der autorisierten Revision; damit verliert sie ihren Status als unautorisierte Mutation und Story 2.1 ist `done`-fähig. (Kann mit F-14 in einer gemeinsamen Revision laufen.)
|
||||
- summary: **3. Validator-Header-Revisionszahl anheben (OBS-1)** — `schema/validator.md` §0-Header trägt weiter „Validator-Revision: 6", während der Revisionslog (§8) als letzten Eintrag „Revision 7" führt (pre-existing Selbst-Inkonsistenz). In derselben autorisierten Revision den Header auf die dann aktuelle Revisionszahl anheben — damit schließt sich die von compiler.md §0/§8 auf „Revision 7" referenzierte Kette header-seitig. (Korrektur jetzt nicht möglich, da `validator.md` friert.)
|
||||
evidence: Re-Review (Code Review Story 2.1), 2026-08-16 — Option-A-Home-Story; Epic-1-Retrospective F-14/AI-7 (Defer-Kontexte, deferred-work.md).
|
||||
status: umgesetzt (2026-08-17) — siehe autorisierte Validator-Revision 8 (`validator-revision-8-autorisationsrunde-f14-innen-ebenen.md`): F-14-Fixture 4a, Innen-Ebenen-Klarstellung formal getragen, Header auf „Revision 8" angehoben (OBS-1 behoben); Story 2.1 damit `done`-fähig.
|
||||
|
||||
## Folge-Einträge aus dem Sandbox-Dryrun (PDF/RADIUM, Prozess-Optimierungs-Bericht; 2026-08-17)
|
||||
|
||||
> **Herkunft:** Nutzer-Probelauf in `D:\mita\wow-2nd-sandbox` (Compiler Rev 1.3 gegen `raw/MetaModel.pdf`, 11 radium-Concepts OKF-konform als positivem R-2-Beleg ausgeführt) — siehe `review-input-dryrun-2-1-pdf-radium.md` im selben Verzeichnis. Der Bericht (vom Nutzer erstellt) enthält Tooling-/Prozess-Optimierungs-Maßnahmen (P1/P2/P3) **auf Ausführungs-/Werkzeug-Ebene**, keine Norm-Änderungen (D-3). Diese Einträge sichern die Folge-Aufgaben; die detaillierte Zuordnung (inkl. Konformitäts-Bewertung) steht im Review-Input-Dokument.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/review-input-dryrun-2-1-pdf-radium.md` (Sandbox-Dryrun, P1)
|
||||
summary: Fixture-Selbsttest des Validator-Prüfwerkzeugs vor jedem Bundle-Lauf etablieren (P1) — jede Negativ-Fixture (`validator.md` §7.1, n=21) muss ein deterministisches FAIL mit Ursache erzeugen, jede Positiv-Fixture (§7.2/§7.3, ~20) SUCCESS; optional die „Skript-Fallen" (PyYAML-`datetime`-Parsing statt Textform §4.3, relative Link-Auflösung Punkt 11, `usage_count`-Float) als eigene Negativ-Fixtures ergänzen. Nutzen: Fehler des Prüfwerkzeugs werden vor Berührung des Bundles sichtbar (im Probelauf 2 Diagnose-Zyklen durch Falsch-FAILs des Prüfskripts vermeidbar). D-3-tauglich (rein textueller Check-Block, kein Standalone).
|
||||
evidence: Prozess-Optimierungs-Bericht §3.1/§4.1 (Tooling-Diagnose-Zyklen, Punkt-11-Identity-Match; korrigiert: kein Instruktions-Defekt); Review-Input §2/§4 (Konformität: D-3/AD-17h).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/review-input-dryrun-2-1-pdf-radium.md` (Sandbox-Dryrun, P1)
|
||||
summary: Feste `.compile-run/`-Arbeitskonvention einführen (P1) — vom Workspace getragene, per Konvention (.gitignore) ausgeschlossene Fläche für deterministische Textextraktion der Quelle (z. B. `sources-<quelle>-<datum>.txt`), Prüfskripte (inkl. Fixture-Selbsttest) und `run-protokoll.md` (Prüfsummen, Verlinkungs-Check, Verdikte je Run). Nutzen: Reproduzierbarkeit/Auditierbarkeit (AD-17h) ohne `raw/` zu berühren (AD-3), agent-übergreifend gleiche Konvention (AD-10). Kein Verstoß gegen D-3 (textuelle Artefakte, kein Standalone-Programm).
|
||||
evidence: Prozess-Optimierungs-Bericht §3.4/§4.2; Review-Input §4 (Konformität: AD-3/AD-10/AD-17h/D-3).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/review-input-dryrun-2-1-pdf-radium.md` (Sandbox-Dryrun, P1)
|
||||
summary: Einmalige `at`-Festlegung pro Compilation Run deterministisch identisch in alle erzeugten `generated.at` schreiben (P1) — der Run bestimmt **einen** Ablauf-Zeitstempel (UTC) für alle Dateien; optional als textuelle Konvention in `compiler.md` §4.3 ergänzen (Kanonisierung auf `Z`-Form, da der Validator §4.3 sowohl `±HHMM` als auch `Z` akzeptiert — keine Vertrags-Änderung nötig). Nutzen: keine Timing-Drift/Inkonsistenz über Dateien, einfachere Diff-/Nachvollziehbarkeit. Deckt sich mit dem Defer zur Determinismus-Selbsttest-Schärfung (Kriterium 2 „`at`-Normalform").
|
||||
evidence: Prozess-Optimierungs-Bericht §3.3/§4.3; Review-Input §4 (Validator-neutral: §4.3 akzeptiert `Z` und `±HHMM`).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/review-input-dryrun-2-1-pdf-radium.md` (Sandbox-Dryrun, P2)
|
||||
summary: Pre-Run-Reconcile-Vorphase als deterministischen Pre-Plan-Schritt bündeln und dokumentieren (P2) — die textuellen Reconcile-Prüfungen (Ziel-Pfad-Kollision, Quellen-Existenz, AD-5-Relevanz der Quelle auf bestehende Concepts, `index.md`-Vorbedingung V-1) zu einem wiederverwendbaren Check-Block zusammenfassen (statt manueller Mehrfach-Checks, Bericht §3.2). Kein neuer Standalone-Prozess — nur ein reproduzierbarer Check-Block innerhalb der Instruktions-Ausführung; als Compiler-Instruktions-Schärfung (Story 2.1-Follow-up) oder Epic-3-Home (AD-5) einzuarbeiten.
|
||||
evidence: Prozess-Optimierungs-Bericht §3.2/§4.4; Review-Input §4 (D-3-konform).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/review-input-dryrun-2-1-pdf-radium.md` (Sandbox-Dryrun, P2)
|
||||
summary: Provenienz-Checksumme bei mehrfacher Verwendung einer Quelle im Blick behalten (P2, Vorbereitung Epic 3/Story 2.2) — bei 11 Concepts aus einer Quelle (`raw/MetaModel.pdf`) ist eine wie auch immer geartete SHA-256/`last_modified`-Angabe Kandidat für `sources`-Metadaten; erst ab der zulässigen Schema-Erweiterung (Story 2.2 Claim-provenienz / Epic 3) in der Instruktion verankern. NICHT jetzt implementieren — `sources`-Subset (Vertrag §3.3, Punkt 6/§7) bleibt unverändert.
|
||||
evidence: Prozess-Optimierungs-Bericht §4.5; Review-Input §4 (vertragskonform: Schema-Subset unangetastet); verknüpft mit Defer zum „`sources`-`id`-Eindeutigkeit" (BH-13).
|
||||
|
||||
## Deferred from: code review of story-2.1 (2026-08-17)
|
||||
|
||||
> **Unabhängiger Re-Run (bmad-code-review, 2026-08-17)** auf dem Stand nach Validator-Rev-8 (HEAD `ae5e0aa`). Die tragenden Story-2.1-Artefakte sind validator-clean (alle 8 ACs PASS); die Defer-Einträge unten sind bewusst nicht in Story 2.1 behobene bzw. vorbestehende Punkte.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md` (Code-Review-Re-Run 2026-08-17)
|
||||
summary: Content-Truth-Verifikation — keine Änderung zum bereits deferrierten Punkt (Story 2.2), aber der Re-Run liefert eine konkrete, prüfbare Instanz: das ASCII-Datenfluss-Diagramm-Layout in `wiki/knowledge-kompilation-inkrementell.md` stammt aus `raw/architecture-spine/…`, während das Concept `sources: raw/epics/…` deklariert (Inhalt kuratiert/korrekt, nur die exakte Diagrammform nicht von der deklarierten Source gedeckt).
|
||||
evidence: Acceptance-Auditor (Informational) + Blind Hunter; die anderen beiden Concepts sind vollständig in ihren deklarierten Sources verankert.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md` (Code-Review-Re-Run 2026-08-17)
|
||||
summary: Concept-Bodies präsentieren Epic-3/4-Fähigkeiten als aktuelle Tatsache ohne Forward-Referenz-Marker — `knowledge-kompilation-inkrementell.md`: „Verbindung zu Regelwerken" (NEW/CONFIRMING-CORRECTING-Klassifikation, grep/ripgrep-Relevanzbestimmung → Story 3.2/4.1) und „FR-6 Aktualisierung statt neuer Dateien" (→ Story 3.1, die `compiler.md` §7 explizit nicht baut und deren Kollision-Hold §3.2 auf bestehendem Pfad abbricht). Zu markieren, sobald die Claim-Provenienz-/Kontext-Marker-Logik (Story 2.2) existiert.
|
||||
evidence: Blind Hunter (2 Einzelfindings); Epic-3/4-Zuordnung belegt in `raw/epics/…` (Story 3.1/3.2, 4.1).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md` (Code-Review-Re-Run 2026-08-17)
|
||||
summary: `wiki/log.md` akkumuliert Meta-/Prozess-Einträge (Review-Verdikt, Action-Item-Statusflips, Validator-Revision-Ankündigungen) ohne Marker, der sie von Vertrag-§5-„fachlichen Änderungen" unterscheidet — vorbestehendes Muster (die Retrospective-Follow-up-Einträge tun dasselbe), nicht neu durch diesen Diff verursacht; F17 defert Log-Content-Validierung bewusst.
|
||||
evidence: Blind Hunter; pre-existing.
|
||||
|
||||
### Geholderte validator.md-Patches — Arbeitsauftrag für die nächste autorisierte Validator-Revision (Rev 9)
|
||||
|
||||
> **Herkunft:** Unabhängiger bmad-code-review Re-Run (2026-08-17), Patches 16/17. Beide betreffen die am 2026-08-17 autorisierte, gefrorene `schema/validator.md` (Rev 8) — ihre Anwendung setzt einen **neuen Autorisierungsschlag** auf `schema/` voraus und wurde im Re-Run bewusst **nicht** mitgepatcht (Frieren-Prinzip, Analogie zur Option-A-Heilung F-14). `validator.md` selbst bleibt bis zur autorisierten Revision unverändert.
|
||||
|
||||
- summary: **1. Punkt-4-Fehlerursachen-Grammatik um `resolved=`-Token erweitern** — Fixture 4a (§7.1) erwartet `FAIL … Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (resolved=README.md)`, aber die §3-Punkt-4-Vorlage `(..-Traversal|absolut|URL|Backslash|file://)` trägt kein `resolved=`-Token; §7 verlangt „exakt die aus §3". In der autorisierten Revision die Punkt-4-Vorlage um ein optionales `resolved=<Pfad>`-Token ergänzen (oder die Fixture-Vorlage an die Vorlage angleichen) + Zertifizierung der Fixture 4a (isoliert, genau Punkt 4) neu ausführen.
|
||||
- summary: **2. Innen-Ebenen-Punkt-6-Fixture-Zeile ergänzen** — die in Rev 8 formalisierte Innen-Ebenen-Regel (Punkt 6: unautorisierte Keys in `sources`/`generated`/`verified`-Einträgen, Vertrag §3.3–§3.5) hat keine Fixture-Zeile in §7.1/§7.3; der einzige Punkt-6-Fixture ist Top-Level `foo: bar`, §7.3 zeigt `sources … role: x` nur als Inline-Prosa-Beispiel. In der autorisierten Revision eine Negativ-Fixture-Zeile (z. B. `sources`-Eintrag mit `role: x` bei existierender `raw/`-Datei → `FAIL … Punkt 6`) ergänzen + Zertifizierung (isoliertes Sample) + Nachweis in `wiki/log.md` nachführen.
|
||||
evidence: bmad-code-review Re-Run (2026-08-17) — Blind Hunter + Verification-Gap; beides betrifft die gefrorene Rev 8.
|
||||
status: offen — Home: nächste autorisierte Validator-Revision (Rev 9), Validator-Kanal; **kein Story-2.1-Blocker** (Story bleibt `review`, `done`-fähig; verbleibende Schwelle = Human-Review). Verknüpft mit Action-Item `code-review-2-1-item-2`.
|
||||
|
||||
## Deferred from: code review of story-2.2 (2026-08-17)
|
||||
|
||||
> **Step-04-Review (Story 2.2, 2026-08-17):** Von der Verification-Gap-Schicht als Defer klassifizierter Befund — kein Story-2.2-Blocker, da die Story die Markierungs-Syntax liefert und nicht die inhaltliche/kleine Closure-Verifikation.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-2-claim-granulare-provenienz-dokumentieren.md`
|
||||
summary: Sources-Closure-Verifikation einführen — jeder inline-referenzierte `raw/`-Pfad eines Concept-Bodies (per deterministischer Extraktion aus `(raw/…`-Verweisen) MUSS im `sources`-Frontmatter desselben Concepts deklariert sein (inkl. neuer `sources`-Einträge für Relokation/Zielwechsel, §5.5-Pkt.-1b-Regel). Aktuell prüft nur der `grep -nE '\(raw/'`-Existenz-Smoke die Präsenz des Verweises, nicht seine Zuordnung zu einer deklarierten Ressource; EC-1 prüft nur die deklarierten `sources`-Ressourcen, nicht inline-referenzierte. Ein inline-Verweis auf eine nicht deklarierte `raw/`-Datei (Beispiel im Story-2.2-Body behoben) bliebe sonst unsichtbar.
|
||||
evidence: Verification-Gap-Review (Story 2.2): Demonstriert an `wiki/wissensarchitektur-trennung-states.md` (Consumer-Unabhängigkeit zitierte `raw/epics/…` ohne `sources`-Deklaration — im Story-2.2-Patch behoben); kein re-runnable Check deckt die Abgeschlossenheit ab (D-3-konforme Deterministische Closure-Prüfung, analog grep-Pipeline, kein Standalone).
|
||||
status: offen — Home: spätere fokussierte Validator-/Instruktions-Runde (Rev 9-Kandidat), Validator-/Instruktions-Kanal; **kein Story-2.2-Blocker** (Story liefert die Markierungs-Syntax, nicht die Closure-Prüfung).
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-2-claim-granulare-provenienz-dokumentieren.md`
|
||||
summary: **Stellen-Kennung-Existenz im Rohdokument wird nirgends geprüft** — §5.5 Pkt.1 macht die Existenz des `#`-Fragments im referenzierten Rohdokument zur harten Regel (ganzer Sinn der s1/s2-Korrektur), aber kein Check verifiziert sie: nicht der strukturelle Validator (keiner der 14 Punkte liest Fragment-Targets), nicht die Spec-Verification-Greps (nur `(raw/`-Präsenz), nicht die Selbsttest-Formel. Fragment-Typo (z. B. `#FR-19`) oder verbotenes Concept-`id`-Fragment `#s1` durchläuft den gesamten Pfad mit SUCCESS und liefert genau die Falsch-Attribution, die die Regel verhindern soll (Worked-Example-Grammatik ungeprüft). D-3-konforme deterministische Prüfung (Fragment tritt als Zeilenanker/Sektionstitel in `raw/<pfad>` auf; Negativ: kein `^s[0-9]+$`-Fragment), Schwester zu W1.
|
||||
evidence: Verification-Gap-Review (bmad-code-review Story 2.2, 2026-08-17): Validator-14-Punkte-Katalog + EC-1 im Volltext gelesen (keine Fragment-Auflösung); alle aktuellen Fragmente der drei Concepts händisch gegen `raw/` verifiziert (alle auflösen) — aber nichts pinnt es; Demonstrationsfall `…(raw/epics/…md#FR-19)` → SUCCESS.
|
||||
status: offen — Home: spätere fokussierte Validator-/Instruktions-Runde (Rev 9-Kandidat), Schwester zu W1; **kein Story-2.2-Blocker**.
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-2-claim-granulare-provenienz-dokumentieren.md`
|
||||
summary: **Kontext-Marker-Grammatik (Selbstreferenz-Verbot, Musterwahl, exakter Token-Platz) ungeprüft** — §5.5 Pkt.2 definiert die Marker-Muster mit obligatorischem exaktem Token „nicht eigenständig belegt" und das neue Selbstreferenz-Verbot (Rev 1.6); der Lauf-Gate-Selbsttest (Pkt.4) und die Spec-Manual-Checks behaupten nur Token-Präsenz, nicht die Musterform oder das Selbstreferenz-Verbot. Ein Selbstreferenz-Marker (Concept nennt sich selbst als Ursprung) trägt den exakten Token und passiert jede re-runnable Prüfung mit SUCCESS — das Verbot ist durch nichts erzwingbar. Demonstrationsfall `übernommen aus wiki/<eigenes-Concept> auf Basis von raw/epics/… nicht eigenständig belegt` → SUCCESS. D-3-konforme Prüfung (Token pro Concept extrahieren, Pattern-Match gegen die kanonischen Formen, `<Concept-Pfad>` gegen eigenen OKF-Pfad vergleichen), Schwester zu W1.
|
||||
evidence: Verification-Gap-Review (bmad-code-review Story 2.2, 2026-08-17): Punkt 9-Inhaltsscan prüft nur `okf_version`/`type: bundle`; die drei aktuellen Marker-Stellen (`knowledge-kompilation:37,52`, `llm-wiki-prinzip:40`, `wissensarchitektur:30`) konform gelesen — aber nichts pinnt die Grammatik; die Pre-Patch-Selbstreferenz (Klassifikation P5) beweist, dass der Fehler nur durch Review-Lesbarkeit, nicht durch re-runnable Checks auffindbar war.
|
||||
status: offen — Home: spätere fokussierte Validator-/Instruktions-Runde, Schwester zu W1; **kein Story-2.2-Blocker**.
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-2-claim-granulare-provenienz-dokumentieren.md`
|
||||
summary: **`sources`-`id`-Eindeutigkeit je Concept ohne Check und ohne Selbsttest-Hook** — §5.5 Pkt.3 führt die Regel „`id`-Werte je Concept eindeutig" ein und wird in allen drei Concepts angewendet (neue `id: s1`/`s2`), aber Validator Punkt 6 prüft Keys (nicht Wert-Duplikate), Punkt 13 nur Top-Level-Frontmatter-Duplikate, die Spec-Greps prüfen Feldpräsenz/`resource`-Werte, und §5.5 Pkt.4 (Selbsttest-Kriterien) führt die id-Eindeutigkeitsregel gar nicht auf. Duplizierte `id`-Werte (z. B. beide `s1` in `knowledge-kompilation:4-7`) liefern SUCCESS. D-3-konforme Prüfung (kein `sources[].id`-Wert tritt im selben File doppelt auf) + Eintrag in §5.5 Pkt.4, Schwester zu W1.
|
||||
evidence: Verification-Gap-Review (bmad-code-review Story 2.2, 2026-08-17): Punkt 6/13 im Volltext gelesen; Demonstrationsfall beide Einträge `id: s1` → alle Punkte + Greps SUCCESS.
|
||||
status: offen — Home: spätere fokussierte Validator-/Instruktions-Runde, Schwester zu W1; **kein Story-2.2-Blocker**.
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Stale „Story 2.3"-Klauseln in `schema/validator.md`** (Punkt 11, L70; §8, L297) tragen weiterhin die Notiz „Festlegung ist Story 2.3", obwohl Story 2.3 die Linkform in `schema/compiler.md` §5.6 gepinnt hat. Der Validator bleibt strukturell unverändert (akzeptiert beide Schreibweisen — D-3, Story-2.2-Präzedenz), aber die Notizen sind jetzt inkonsistent mit dem Ist-Zustand; eine konsistente Nachführung (Notiz auf „gepinnte Form: compiler.md §5.6" umstellen) gehört in die nächste autorisierte Validator-Revision (Rev-9-Kandidat), nicht in Story 2.3 (kein Validator-Change, Ask-First).
|
||||
evidence: Step-04-Review (Blind-Hunter, Loop 1): `validator.md` Punkt 11 und §8 gelesen — beide nennen Story 2.3 als offene Festlegung; Story 2.3 ist `in-review` und hat §5.6 gesetzt.
|
||||
status: offen — Home: nächste autorisierte Validator-Revision (Rev 9-Kandidat), Validator-Kanal; **kein Story-2.3-Blocker** (Validator-Einschränkung wäre eigene Autorisierung, Ask-First).
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Selbsttest-Formeln in `compiler.md` §5.6 sind gegenüber `)` im Link-Target blind** — die Grep-Pipeline `grep -ohE '\]\([^)]+\)'` beendet die Ziel-Extraktion am ersten `)`, so dass ein (inadäquates) Ziel wie `wiki/foo).md` als `wiki/foo.` extrahiert wird; der Dangling-Check meldet dann `DANGLING: wiki/foo.` und der Form-Check zählt das Ziel als Formfehler — die Detektion ist also konservativ (faust-positiv, kein Stiller-Vorbei), aber die Fehlerursache-Meldung benennt das falsche (abgeschnittene) Ziel. Für den aktuellen flachen Bundle-Root (keine Areas, keine Sonderzeichen in Kebab-Case-Slugs, AD-7a) ist der Fall nicht erreichbar; bei künftiger Area-Einbettung (Story 2.4) oder wenn OKF-Pfade `)` zulassen sollten, wäre die Formel zu präzisieren (z. B. balanciertes-Parens-Matching via `awk`/`sed`-Pipeline, D-3-konform, kein Standalone).
|
||||
evidence: Step-04-Review (Edge-Case-Hunter, Loop 1): Negativ-Test in `/tmp/lk/wiki` — `](foo).md)`-Ziel wird als `foo.` extrahiert; aktuelle 8 internen Ziele des Bundles enthalten kein `)` (Bestands-Check), Kebab-Case-Slug-Regel (§5.1) verbietet `)` strukturell.
|
||||
status: offen — Home: fokussierte Instruktionseinschärfung ab Story 2.5 (Story-2.4-Kandidat-Home vorangeschoben — Story 2.4 ist 2026-08-18 ohne Umsetzung dieses Falls abgeschlossen, Loop-2-Review-Weiterleitung); **kein Story-2.3-Blocker** (Detektion bleibt konservativ korrekt).
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Cross-Page-Anker in Concept-Links (`file.md#sec`) sind derzeit Form-Verletzung** — die gepinnte Form ist strikt „bundle-relativ mit `.md`-Endung"; ein Ziel wie `llm-wiki-prinzip.md#s1` endet nicht mit `.md` und wird vom Form-Check gezählt (Run-FAIL, NFR-4), vom Dangling-Check zusätzlich als `DANGLING` benannt. Das Verhalten ist deterministisch und korrekt gem. Pin, aber ob AD-7b („bundle-relativ, mit oder ohne Endung") Fragmente zulassen soll, ist eine normative Frage, die kein Check beantwortet. Entscheidung + ggf. Formel-Anpassung (Fragment-Stripping vor dem `-f`-Test, Analogie Gleichseit-Anker) gehören in eine spätere Instruktions-/Validator-Runde — nicht in Story 2.3 (feste Pin-Form nicht öffnen).
|
||||
evidence: Step-04-Review (Edge-Case-Hunter, Loop 1): Synthese-Test `concepts.md#s1` → Form-Check `1` + `DANGLING: concepts.md#s1` (Zieldatei existiert); I/O-Matrix-Zeile GLEICHSSEIT_ANKER deckt nur `#…`-Ziele ab, Cross-Page-Fall ist nicht Gegenstand der gefrorenen Intent.
|
||||
status: offen — Home: fokussierte Instruktionsrunde ab Story 2.5 (Story-2.4-Kandidat-Home vorangeschoben — Story 2.4 ist 2026-08-18 ohne Umsetzung dieser Frage abgeschlossen, Loop-2-Review-Weiterleitung); **kein Story-2.3-Blocker** (Detektion konservativ korrekt, kein stiller Vorbeilass).
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Area-Kontext: Bundlerelativ vs. Dateirelativ bei Standard-Tools** — §5.6 Pkt. 1 führt als Rationale an, Standard-Markdown-Tools lösten Links „ohne Konventionswissen" auf; das gilt exakt im flatten Bundle (Root-Concepts), wo datei- und bundlerelativ identisch sind. In künftigen `wiki/<area>/`-Concepts (Story 2.4) löst ein Standard-Tool `](beta/c2.md)` dateirelativ (→ `wiki/alpha/beta/c2.md`, falsch), während die gepinnte Form nach AD-7b bundlerelativ bleibt und der Dangling-Check bundleroot-relativ prüft. Die Spannung zwischen AD-7b (bundlerelativ) und „Standard-Tools-Auflösung" in Areas ist ein Story-2.4-Thema (dort: deterministische Area-Zuordnung + Index-Regel für Areas).
|
||||
evidence: Step-04-Review (Verification-Gap, Loop 1): Rationale-Satz in §5.6 Pkt. 1 gelesen; Dangling-Check-Auflösung `[ -f "wiki/$t" ]` ist bundleroot-relativ; Synthese-Baum `/tmp/area` zeigt: bundlerelative Area-Links (`beta/c2.md` aus `alpha/c1.md`) lösen im Check korrekt auf, in Standard-Renderern aber nicht.
|
||||
status: umgesetzt (2026-08-18, Story 2.4) — §5.7 Pkt. 4 der Compiler-Instruktion legt das **file-relative** Link-Auflösungsmodell fest (`../`-Präfix für in-Bundle-Aufwärts-Ziele; eine syntaktische Form für Root + Area; Standard-Markdown-Tools lösen dateirelativ auf — die Rationale „ohne Konventionswissen" gilt damit auch in Areas). §5.6 Pkt. 1/2/3 um die `../`-Schärfung nachgeführt (Formel 3: file-relatives Resolve mit `..`-Kollabierung und Containment unter `wiki/`, Out-of-Bundle-`..`-Escape → `DANGLING`); der Rationale-Satz in §5.6 Pkt. 1 nennt die Form jetzt explizit zwei-ebenentauglich (Root + Area, Story 2.4). **kein Story-2.3-Blocker** war / bleibt gelöst.
|
||||
|
||||
## Deferred from: code review of spec-2-3-concepts-verlinken-eine-erlaubte-linkform (2026-08-17)
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **`log.md`-Exklusions-Begründung in §5.6 Pkt.2/Verification ist für Formeln 1–3 gegenstandslos** — die Begründung „sie enthält die Formel-Texte selbst als Zitate und würde die Zählungen verunreinigen" ist im Ist-Zustand unzutreffend: `wiki/log.md` enthält aktuell **0** `](`-Muster, die Exklusion ändert für Formeln 1–3 nichts; lasttragend ist sie nur für Formel 4 (log.md enthält 4 `(raw/`-Vorkommen — ohne Exklusion 34 statt 30 ggü. Baseline 30). Solange der Story-2.2-`27-Treffer`-Zitat-Zeile (enthält `(raw/`) in log.md bleibt, ist die Formel korrekt re-executierbar; die Begründungs-Formulierung ist präzisierenswert, kein Funktionsfehler.
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Verification-Gap-Layer): `grep -roE ']\([^)]*\)' wiki/log.md` → 0; `grep -oE '\(raw/' wiki/log.md` → 4.
|
||||
status: offen — Home: dokumentarische Präzisierung einer späteren Instruktions-Runde; **kein Story-2.3-Blocker** (Formel bleibt AD-17h-re-executierbar).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Cross-Page-Defer-Eintrag (L221–222) beschreibt Prä-Patch-Dangling-Verhalten als Ist-Zustand** — der Eintrag behauptet, ein Ziel `concepts.md#s1` liefere vom Dangling-Check zusätzlich `DANGLING: concepts.md#s1` (Zieldatei existiert), während die im selben Change shipende §5.6-Pkt.3-/Verification-Formel 3 das Fragment VOR dem Existenztest stripped (`p=${t%%#*}`) und genau diesen Fall als „keine Ausgabe" benennt. Die Evidenz-Zeile dokumentiert den Stand vor Rev 1.9 (Punkt 5 des Patchs); die Beschreibung des Solutions-Verhaltens (Cross-Page-Anker ist Form-Verletzung, normativ offen) bleibt korrekt.
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Blind-Hunter-Layer): Defer-Text L221–222 vs. `schema/compiler.md` §5.6 Pkt.3 (`p=${t%%#*}`) + Verification Formel 3 gelesen; Fragment-Strip ist Teil von Revision 1.9 (gleicher Commit).
|
||||
status: umgesetzt (2026-08-18, Story 2.4, dokumentarische Korrektur) — Eintrag auf Ist-Verhalten korrigiert: der §5.6-Formel-3-Dangling-Check stripped das Fragment vor dem Existenztest (`p=${t%%#*}`), ein Ziel `concepts.md#s1` erzeugt bei existierender Datei **keine** Dangling-Ausgabe (die Pin-Form-Frage bleibt beim Form-Check); die Beschreibung des Solutions-Verhaltens (Cross-Page-Anker ist Form-Verletzung, normativ offen) bleibt korrekt und ist als offene normative Frage in deferred-work.md weiterhin notiert.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Image-/Nicht-Navigations-`](...)` ohne definierten Scope in §5.6** — die Formeln werten `` (Markdown-Image) und `[x](./y.md)` als „Concept-Link" und zählen Images als Form-Verletzung; §5.6 Pkt.2 definiert den Geltungsbereich („Beziehungen zwischen Concepts … normale Markdown-Links") ohne `` → Form-Check zählt `1`; §5.6-Pkt.2-Scope-Text ohne Image-Ausnahme.
|
||||
status: offen — Home: spätere Instruktions-/Media-Runde; **kein Story-2.3-Blocker** (aktuell keine Images im Bundle).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Multi-Line-Link-Targets für alle §5.6-Formeln unsichtbar** — `grep -roE ']\([^)]*\)'` ist ein Ein-Zeilen-Matcher; ein über zwei Zeilen geteiltes Ziel `](nichtda\nbar.md)` wird von Form-Check, Dangling-Check und Bestands-Check nicht erfasst → toter Link passiert **stillschweigend** (NFR-4-Verletzung, kein Fehlalarm). CommonMark erlaubt Zeilenumbrüche in Link-Zielen; bei künftiger Verwendung wäre balanciertes-Parens-/Multi-Line-Matching nötig (D-3-konform, kein Standalone). Für das aktuelle Bundle irrelevant (keine Multi-Line-Links, Kebab-Case-Slug-Konvention, AD-7a).
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Edge-Case-Hunter-Layer): Synthese-Eingabe `[x](foo.md\nbar.md)` → alle drei Formeln ohne Treffer.
|
||||
status: offen — Home: fokussierte Instruktionsrunde ab Story 2.5 (Story-2.4-Kandidat-Home vorangeschoben — Story 2.4 ist 2026-08-18 ohne Umsetzung dieser Frage abgeschlossen, Loop-2-Review-Weiterleitung); **kein Story-2.3-Blocker** (aktuell keine Multi-Line-Ziele).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Reference-Style-Links (`[x][ref]` + `[ref]: ziel.md`) für die §5.6-Formeln unsichtbar** — keine Formel scannt Definitionszeilen `^\[[^]]+\]:`; ein per Reference-Style verlinktes Ziel passiert Bestands-, Form- und Dangling-Check ohne Meldung (zweite Form der Konzept-Verlinkung, AD-7b-Zwei-Producer-Problem wiederherstellbar). Für das aktuelle Bundle irrelevant (alle Links inline); bei künftiger Nutzung Definitions-Scan ergänzen oder Reference-Form explizit ausschließen.
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Edge-Case-Hunter-Layer): Synthese-`[x][ref]`/`[ref]: ziel.md` → keine Formel-Ausgabe.
|
||||
status: offen — Home: spätere Instruktions-Runde; **kein Story-2.3-Blocker** (aktuell keine Reference-Style-Links).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **Leading-Space-Ziel `]( ziel.md)` wird als Form-konform UND vorhanden gewertet** — `grep -oE ']\([^)]*\)'` matcht das Leerzeichen nach `(`; `sed`/`read` strippen es nicht; `^[^#]+\.md$` matcht ` ziel.md` (führendes Leerzeichen ist `[^#]+`), `[ -f "wiki/ ziel.md" ]` schlägt fehl → Form-Check `0` (falsch), Dangling-Check `DANGLING: ziel.md` (getrimmt). CommonMark erlaubt keine Leerzeichen direkt nach `(`. Konservativ richtungsweisend, aber Form-Check-Aussage „0" ist für solch ähnelnde Ziele unzuverlässig. Für das aktuelle Bundle irrelevant (keine solchen Ziele); Whitespace-Verbot vor `-f`-Test ergänzbar.
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Edge-Case-Hunter-Layer): Synthese-Eingabe `]( ziel.md)` → Form-Check `0` + Dangling `DANGLING: ziel.md`.
|
||||
status: offen — Home: spätere Instruktions-Runde; **kein Story-2.3-Blocker** (aktuell keine solchen Ziele).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-3-concepts-verlinken-eine-erlaubte-linkform.md`
|
||||
summary: **künftiges `wiki/<area>/log.md` bricht die Baseline-Extraktion (Formel 4)** — der Baseline-Filter `grep -v "wiki/log.md$"` entfernt nur das Top-Level-log.md; `--exclude=log.md` in der Ist-Zählung schließt aber auch ein zukünftiges Area-log.md aus → Baseline/Ist-Dateimengen divergieren, falscher FAIL (AD-17h-Nicht-Determinismus). Für den aktuellen flachen Bundle-Root irrelevant (keine Areas bis Story 2.4); bei Area-Einführung Filter auf Basename umstellen (`grep -v 'log.md$'` analog zu `--exclude=log.md`).
|
||||
evidence: bmad-code-review Story 2.3 (2026-08-17, Edge-Case-Hunter-Layer): Synthese-Baum `wiki/alpha/log.md` → Baseline-Filter lässt sie durch, `--exclude=log.md` nicht.
|
||||
status: umgesetzt (2026-08-18, Story 2.4, Area-Einführung) — §5.6 Pkt. 3, Formel 4: der Baseline-Filter ist jetzt `grep -v "log.md$"` (Basename-Match) statt des bisherigen `grep -v "wiki/log.md$"` (Pfad-Match); damit sind Baseline-Extraktion und Ist-Zählung konsistent beide Basename-`log.md`-exkludierend (konsistent mit `--exclude=log.md`), auch bei künftigen Area-`log.md`-Dateien (AD-17h-Determinismus).
|
||||
|
||||
## Deferred from: code review of spec-2-4-deterministische-bereichszuordnung-concept-hierarchie (2026-08-18)
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md`
|
||||
summary: **Spec-Frontmatter `status: 'done'` bei offenem Review-Zyklus** — spec-2-4 trägt `status: 'done'` + `review_loop_iteration: 1`, während `sprint-status.yaml` `review` (Review offen) zeigt; nach dem spec-2-3-Präzedenz (`done` erst nach Review-Freigabe) ist das Frontmatter der Prozesslage voraus. Der Status wird mit dem Abschluss dieses Review-Loops (Loop 2) synchron — kein separates Patch.
|
||||
evidence: bmad-code-review Story 2.4 (2026-08-18, Blind-Hunter-Layer): spec-Frontmatter vs. `sprint-status.yaml:49` + spec-2-3-Präzedenz (status done, review_loop_iteration 2).
|
||||
status: umgesetzt (2026-08-18, Loop-2-Abschluss) — Status synchronisiert: `sprint-status.yaml` `2-4-…` → `done` (Review-Loop 2 abgeschlossen: 3 Decision-Resolutions 1/1/1, 14 Patches umgesetzt, Defer-Regelungen hier verankert); die spec-Frontmatter `status: 'done'` ist damit deckungsgleich mit dem Sprint-Status (spec-2-3-Präzedenz erfüllt).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md`
|
||||
summary: **Gefrorene I/O-Matrix „6 `wiki/`-Dateien" + Grammatik „stillem Overwrite"** — die frozen-after-approval-I/O-Matrix (HAPPY_PATH: „Validator SUCCESS (6 `wiki/`-Dateien; Punkte 1/6/8/9/10/11/14, EC-1)"; TOP_LEVEL_COLLISION: „kein stiller Overwrite" → „stillem") ist nur per menschlicher Renegotiation änderbar; der Log dokumentiert 7 Dateien inkl. `log.md`. Wird mit der Loop-2-Spec-Amendierung (Decision-Resolution) nachgeführt.
|
||||
evidence: bmad-code-review Story 2.4 (2026-08-18, Blind-Hunter-Layer): spec-I/O-Matrix L74/L75 vs. `wiki/log.md:4` (7 Dateien, anderer Punkt-Satz) + Validator-Punkt-9-Semantik (`okf_version`/`type: bundle`-Verbot, nicht log.md-Validierung).
|
||||
status: umgesetzt (2026-08-18, Loop-2-Abschluss) — Die nicht-gefrorene Spec-Verification ist auf 7 `wiki/`-Dateien + korrekten Punkt-Satz nachgeführt; die frozen-after-approval-I/O-Matrix bleibt „6 `wiki/`-Dateien" (Defizitzählung) und „stillem Overwrite" (Grammatik) — beides bleibt frozen (nur per menschlicher Renegotiation änderbar, AD-3) und ist Änderungskandidat für die nächste Renegotiations-Runde.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md`
|
||||
summary: **ID-Kollision Area-`index.md` vs. Root-Concept nicht vom §3.2-Hold gedeckt** — `wiki/<a>/index.md` (Identität `<a>` per index-Strip) und `wiki/<a>.md` (Identität `<a>`) normalisieren auf dieselbe AD-7a-Identität, ohne dass eine Dateikollision entsteht; der §3.2-Kollisions-Hold feuert nur auf Dateikollision, das Verhalten bei reiner Identitätskollision ist undefiniert. Ein Fix erfordert §3.2-Erweiterung bzw. Vertrags-/Validator-Änderung (AD-3 read-only, „kein neues Prädikat") — übersteigt den Story-2.4-Rahmen.
|
||||
evidence: bmad-code-review Story 2.4 (2026-08-18, Edge-Case-Hunter-Layer): §5.7 Pkt. 2-ID-Tabelle (`wiki/wissensarchitektur/index.md` → `wissensarchitektur`) vs. §3.2-Dateikollisions-Prädikat (compiler.md L40); kein Fixture, kein Hold-Trigger für Identitäts-Kollision.
|
||||
status: offen — Home: nächste autorisierte Validator-/Vertragsrevision (analog Rev-8/Rev-9-Verfahren).
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md`
|
||||
summary: **Spec-These „Validator Punkt 11 akzeptiert bereits Areas" wird vom read-only-Validator-Text nicht gedeckt** — Punkt 11 (validator.md L70) verlangt, die Concept-Identität sei „als relativer Bundle-Pfad referenziert (mit oder ohne `.md`-Endung)"; die Area-`index.md` verlinkt file-relativ `source-material.md`, die Bundle-Identität `wissensarchitektur/source-material` erscheint in der Area-`index.md` textuell weder mit noch ohne Endung → ein wörtlicher mechanischer Punkt-11-Check meldete `Concept nicht verlinkt=wissensarchitektur/source-material`; der SUCCESS-Nachweis der Log (7/7 SUCCESS inkl. Punkt 11) ist damit nicht unabhängig überprüfbar. Fix = autorisierte Validator-Revision (Punkt 11 um die Area-Lesart schärfen: Area-Index erfüllt den Link per Area-localem Pfad der Concept-Datei) — AD-3-Blocker.
|
||||
evidence: bmad-code-review Story 2.4 (2026-08-18, Acceptance-Auditor-Layer): validator.md L70 (Punkt 11, read-only) vs. `wiki/wissensarchitektur/index.md` L9 (`[Source Material…](source-material.md)`) + Spec-Always-Bullet „Validator Punkt 11 akzeptiert bereits Areas … strukturell unverändert".
|
||||
status: offen — Home: Rev-9-Aktionsitem (`code-review-2-1-item-2`, open) — dort um Punkt-11-Area-Lesart ergänzen.
|
||||
|
||||
## Deferred from: code review of spec-2-5-progressive-discovery-über-index-md-bereitstellen (2026-08-18)
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-5-progressive-discovery-über-index-md-bereitstellen.md`
|
||||
summary: **Spec-Frontmatter `status: 'done'` bei offenem Review-Zyklus** (spec Z. 5) — Story-2.4-Präzedenz (deferred-work.md Z. 269–272): `done` erst nach Review-Freigabe; mit dem Abschluss dieses Review-Loops synchron (s. Step 6), kein separates Patch.
|
||||
evidence: bmad-code-review Story 2.5 (2026-08-18, Loop 3, 4 Layer: Blind-Hunter + Edge-Case-Hunter + Verification-Gap + Acceptance-Auditor): Review-Findings-Sektion der Spec (2026-08-18).
|
||||
status: umgesetzt (2026-08-18, Loop-3-Abschluss) — Status synchronisiert: Spec-Frontmatter `status: 'done'` + `review_loop_iteration: 3` deckungsgleich mit `sprint-status.yaml` (Key `2-5-…` → `done`, `last_updated` nachgeführt); alle `decision-needed` und `patch`-Befunde aufgelöst/umgesetzt.
|
||||
|
||||
- source_spec: `_bmad-output/implementation-artifacts/spec-2-5-progressive-discovery-über-index-md-bereitstellen.md`
|
||||
summary: **Frozen-Text-Wortfehl- und Konsistenz-Kandidaten (nur per menschlicher Renegotiation änderbar)** (spec Z. 18/42/43) — Änderungskandidaten für die nächste Renegotiationsrunde (Story-2.4-Präzedenz): (a) Intent Z. 18 „Revisionslog **(3.x)**" — implementiert ist **2.3** (Reihenfolge 2.0/2.1/2.2/2.3); (b) I/O-Matrix `DISCOVERY_DEMO_ROOT_AREA_LINK` Z. 42: „zusätzlich **überdacht** in das Area-Concept" — Wortfehler + Verlinkungsrichtung unauflösbar (nicht-gefrorene Seite s. Patch „Index-Link-Oxymoron"); (c) I/O-Matrix `SEARCH_GREP` Z. 43: `grep -n <term> wiki/` nicht ausführbar (nicht-gefrorene Seite s. Patch „Consumer-Suchbeispiel"); (d) Intent Z. 18 „Kein Interface-/Backend-/Datenbank-**Änderung**" (Grammatik: „Keine … Änderungen").
|
||||
evidence: bmad-code-review Story 2.5 (2026-08-18, Loop 3, 4 Layer: Blind-Hunter + Edge-Case-Hunter + Verification-Gap + Acceptance-Auditor): Review-Findings-Sektion der Spec (2026-08-18).
|
||||
status: offen
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
epic: 1
|
||||
date: 2026-08-15
|
||||
verdict: accepted-with-open-items
|
||||
criteria: profiled
|
||||
headless: false
|
||||
---
|
||||
|
||||
# Retrospective — Epic 1: Wissens-Workspace & Quellen-Aufnahme
|
||||
|
||||
## Epic-Zusammenfassung
|
||||
|
||||
- **Epic:** 1 — Wissens-Workspace & Quellen-Aufnahme
|
||||
- **Diff-Range:** `6a95d96..6cc667d` (8 Commits: 4 × `feat`, 4 × `chore` (je eine `done`-Setzung je Story))
|
||||
- **Stories:** 1.1 (Workspace-Stamm), 1.2 (Sources unter `raw/`), 1.3 (Schema-Vertrag autorisieren), 1.4 (Schema-Validierung) — alle `done`
|
||||
- **Pending-Stories:** keine (`detect-epic`: `story_count: 4`, `pending_stories: []`)
|
||||
- **Evidenz-Inventur:**
|
||||
- ✅ Epic-Spec: `epic-1-context.md`; Architecture-Spine, PRD, epics (Planung)
|
||||
- ✅ Story-Specs 1.1–1.4 (inkl. `baseline_commit` ab Story 1.3)
|
||||
- ✅ Diff-Range + per-Story-Zuordnung via `git_evidence.py`
|
||||
- ✅ Sprint-Status (`sprint-status.yaml`)
|
||||
- ✅ Keine frühere Retro, keine `action_items` im Sprint-Status
|
||||
- ⚠️ Session-Logs: **nicht vorhanden** → Prozess-Lektionen-Analyse eingeschränkt (nur aus Spec-Revisionslog & Commit-Struktur ableitbar)
|
||||
- ⚠️ Acceptance-Kriterien: nicht als eigene Liste deklariert → **profiled** aus Stories & Epic-Context
|
||||
|
||||
## Findings (Phase 2)
|
||||
|
||||
Konsolidiert aus drei Sichtlinien: Aggregat-Sichten (Diff 6a95d96..6cc667d), bmad-review-Linsen (adversarial, edge-case, verification-gap — ausgeführt als drei parallele Linsen-Agenten über den Diff/Validatoren) und der Behavior-Prüfung. Jeder Befund trägt eine Quellenreferenz; nicht belegbare Befunde wurden verworfen.
|
||||
|
||||
### F-01 (kritisch) — Validator weicht unautorisiert vom Vertrag ab: `at` als reines Datum akzeptiert, obwohl Vertrag „ISO-8601-Datetime" fordert
|
||||
|
||||
- **Befund:** `schema/validator.md` §4.3 (Z.105) und Fixture 14c (§7.2 Z.242) erklären `at: 2027-01-01` (reiner Datumswert) zu SUCCESS („normalisiert zu T00:00:00Z"). Der autorisierte Vertrag `schema/wiki-compiler.md` verlangt für `at` (§3.4 Z.76, §3.5 Z.91) „MUSS es ein ISO-8601-**Datetime** sein" und erklärt §7 Punkt 14 (Z.186) „`at` ungleich ISO-8601-Datetime" zur strukturellen Invalidität. Ein reines Datum ist kein Datetime.
|
||||
- **Quelle:** `schema/wiki-compiler.md:76,91,186` (Vertrag, autorisiert Story 1.3) vs. `schema/validator.md:105,242` (Validator, Story 1.4).
|
||||
- **Auswirkung:** Genau der vom frozen-intent verbotene Konformitätsbruch (spec-1-3: „Keine Änderung am autorisierten Vertrag"/„keine unautorisierte Verschärfung"; spec-1-4 Boundaries: „Der Validator darf keinen Eintrag hinzufügen"). Ein Validator-konformer Producer kann `at`-Datumsangaben erzeugen, die ein strikter Vertrags-Leser als strukturell invalide verwirft — die Validierung bildet die Norm nicht 1:1 ab.
|
||||
- **Disposition:** Fix-now (Re-Konsistenz: Entweder Fixture streichen/FAIL oder Vertrag neu autorisieren — Story-Verfahren).
|
||||
|
||||
### F-02 (kritisch) — §6-Fachliche-Zusatzprüfungen (EC-1, EC-3, stale_after-WARN) haben KEINE Referenz-Fixtures, obwohl sie Run-FAIL-gate sind; Validator-Zertifizierung deckt sie nicht ab
|
||||
|
||||
- **Befund:** `schema/validator.md` definiert die fachlichen Prüfungen §6 (EC-1 Existenzprüfung, EC-3 Kalender-Validität, §6.4 stale_after-WARN, §6.5 non-md) — davon sind EC-1/EC-3 **Run-FAIL-gate** (§6.1 Z.155 „fachlich invalide → Run-FAIL"). Die §7-Fixture-Tabellen (§7.1/§7.2, Z.196–243) enthalten **keine einzige** Fixture-Zeile zu diesen Checks. Der Zertifizierungs-Eintrag `wiki/log.md:4` behauptet „alle Negativ-Fixtures … alle Positiv-Fixtures" geprüft zu haben — die belegen aber nur die 14 §7-Punkte + §3.2-Voraussetzungen, nicht die §6-Checks.
|
||||
- **Quelle:** `schema/validator.md:§7.1/§7.2` (Z.196–243, keine §6-Zeilen) vs. §6.1/§6.3 (Z.153–181); `wiki/log.md:3–4` (Zertifizierungs-Claim).
|
||||
- **Auswirkung:** Ein Ausführer (Epic-2-Producer) kann EC-1/EC-3 überspringen oder falsch ausführen („Phantom-`raw/`-Pfad", falsche Kalenderdaten) und bekäme trotzdem grün — das entscheidende Gate gegen Mutation mit fehlender Evidenz ist unbelegt. AD-17h („reproduzierbar prüfbar") gilt für §6 nicht.
|
||||
- **Disposition:** Fix-now (Fixtures für §6 ergänzen; Zertifizierung neu ausführen).
|
||||
|
||||
### F-03 (kritisch) — §3.2 Voraussetzungsprüfungen sind de-facto eigenständige FAIL-Klassen, die weder in §7 noch im §5-Verdikt-Grammatik stehen
|
||||
|
||||
- **Befund:** `schema/validator.md:§3.2` (Z.77–83) führt zwei Run-FAIL-Bedingungen ein (fehlende Bundleroot, `log.md` an Nicht-Root-Position) mit Verdikt `FAIL (Struktur) …` — ohne §7-Punkt-Nr. und ohne „Fachliche Prüfung EC-x"-Label. `§5.1` (Z.141–147) und §3.1 (Z.71–75) behaupten dagegen „abschließende Liste, keine eigene Invaliditätsklasse". Der fehlende Bundleroot ist zudem **nicht** in §7 (Punkt 8 setzt eine existierende `wiki/index.md` voraus, deckt aber „fehlt ganz" nicht ab).
|
||||
- **Quelle:** `schema/validator.md:77–83,141–147`; `schema/wiki-compiler.md:§7` (kein Fall für fehlende Bundleroot).
|
||||
- **Auswirkung:** Selbstwiderspruch des „keine neue Klasse"-Selbstzeugnisses; ein mechanischer Audit („alle 14 abgebildet") schlägt fehl oder (Struktur)-Verdikte werden nicht als Run-FAIL gelesen.
|
||||
- **Disposition:** Fix-now (als fachliche Prüfungen V-1/V-2 labeln und Fixture-Label ergänzen, oder Vertrag um Fall 15 erweitern mit Autorisierung).
|
||||
|
||||
### F-04 — Duplikat-Keys nur auf oberster Frontmatter-Ebene gezählt; verschachtelte Duplikate in `sources`/`verified`-Einträgen nicht behandelt
|
||||
|
||||
- **Befund:** `schema/validator.md` §3 Punkt 13 (Z.68) und Präambel (Z.52) zählen doppelte Keys „auf oberster Frontmatter-Ebene". Doppelte `resource`-Keys innerhalb eines `sources`-Eintrags (YAML erlaubt sie mehrdeutig) sind nicht abgedeckt — mit Parser-abhängigem Gewinner und doppeldeutiger Provenienz.
|
||||
- **Quelle:** `schema/validator.md:52,68` (§3 Punkt 13, nur oberste Ebene).
|
||||
- **Disposition:** Defer (mit Kontext) — in Nachfolge-Story/Verzahnung mit Validator-Revision.
|
||||
|
||||
### F-05 — BOM-/Leerzeilen-Stripping gilt nur bei Punkt 10 (Area-index/log); Punkte 2/8 (Concept-/Bundleroot-Frontmatter-Erkennung) nicht
|
||||
|
||||
- **Befund:** Punkt 10 (Z.65) strippt BOM `U+FEFF` + führende Leerzeilen vor `---`; Punkt 2 (Z.57) und Punkt 8 (Z.63) erkennen `---` ohne Stripping — ein BOM/Leerzeile vor Concept- oder Bundleroot-Frontmatter erzeugt ein falsches Punkt-2/8-FAIL.
|
||||
- **Quelle:** `schema/validator.md:57,63,65`.
|
||||
- **Disposition:** Fix-now (Stripping-Vorgabe auf Punkte 2/8 erweitern) ODER Defer mit Kontext.
|
||||
|
||||
### F-06 — `today`-Zeitzone für stale_after-WARN nicht definiert
|
||||
|
||||
- **Befund:** §6.4 (Z.180) vergleicht `today >= stale_after` „in UTC", definiert aber nicht, wie „today" abgeleitet wird (Kalenderdatum des UTC-Zeitpunkts? lokaler Tag?). Gleicher lokaler Tag ≠ gleicher UTC-Tag nach Zeitzone.
|
||||
- **Quelle:** `schema/validator.md:180`; Vertrag §3.7 (Z.114) sagt nur „Tagesdatum `today`", ohne Zeitzonenquelle.
|
||||
- **Disposition:** Defer (mit Kontext) — Determinsmus-Anspruch ist hier nicht hart garantiert.
|
||||
|
||||
### F-07 — Punkt 11 (Index-Regel): untere Verzeichnisebenen / Areas ohne `.md`-Inhalt uneindeutig definiert
|
||||
|
||||
- **Befund:** Area wird in §2/§3 als „eine `index.md` tiefer als `wiki/`" definiert. Der Vertrag §6 verlangt „Jede Area … MUSS eine `index.md` enthalten". Bei verschachtelten Unter-Ebenen (`wiki/a/b/concept.md`) oder Verzeichnissen ohne Concept-`.md` ist unklar, was „Area mit Inhalt" ist — Punkt-11-Verletzung agent-abhängig.
|
||||
- **Quelle:** `schema/validator.md:42,66`; `schema/wiki-compiler.md:139–146`.
|
||||
- **Disposition:** Defer (Story-2.5 Voraussetzung — progressive Discovery; als offene Frage notieren).
|
||||
|
||||
### F-08 — Konvention `.MD` (Großschreibung) unter `wiki/` unbestimmt; Windows-Portabilität
|
||||
|
||||
- **Befund:** §1 Punkt 3 (Z.33) behandelt non-`.md` als Nicht-Bundle-Element, „case-sensitive kleingeschrieben". Bei Windows (Projekt läuft auf win32) kann ein Tool `foo.MD` erzeugen; wird es als Concept `.md` gewertet, failt es wegen fehlendem `type`. Konvention für Großschreibung fehlt.
|
||||
- **Quelle:** `schema/validator.md:33`; NFR-1/NFR-5 (Portabilität).
|
||||
- **Disposition:** Defer (mit Kontext) — vor Epic-2-Concepts klären.
|
||||
|
||||
### F-09 — Provenienz-Sidecars (`source.md`) behaupten fälschlich, `_bmad-output/` sei „im Repo nicht versioniert"
|
||||
|
||||
- **Befund:** `raw/prd/source.md:14`, `raw/architecture-spine/source.md:13`, `raw/epics/source.md:13` behaupten, Herkunftspfade unter `_bmad-output/` seien „nicht versioniert". Tatsächlich sind die Herkunftsartefakte versioniert: `git ls-files _bmad-output` listet `planning-artifacts/prds/.../prd.md`, `planning-artifacts/epics.md`, `ARCHITECTURE-SPINE.md`. `.gitignore` enthält keinen `_bmad-output/`-Eintrag.
|
||||
- **Quelle:** `raw/*/source.md:13–14`; `git ls-files _bmad-output` (23 Dateien); `.gitignore`.
|
||||
- **Auswirkung:** Provenienz-Aussage ist faktisch falsch; ein Nachvollzieher kann die Herkunft nicht als feste Referenz nutzen, und ein späterer Verifikationsschritt (Deferred-Work Finding 1/2, Checksumme) widerspricht der Dokumentation.
|
||||
- **Disposition:** Fix-now (Zeile korrigieren — Quellen sind versioniert; Reproduktionshinweis auf Commit-Hash stützen) + Deferred-Work-Checksumme als Konsequenz.
|
||||
|
||||
### F-10 — Verifikation des Validators ist dokumentarisch, nicht ausführbar: keine Testdatei, kein CI, kein Haken
|
||||
|
||||
- **Befund:** Kein Testfile unter `schema/`/`wiki/`, kein `.github/`, keine Haken (nur `.sample`), kein Makefile/CI. Die Spec-Verification-Greps (spec-1-4:111–119) sind Existenz-/Mentions-Greps, die einen semantischen Drift nicht fangen (z. B. `grep -cE '\bFAIL\b|\bSUCCESS\b'` zählt auch Prosa-Labels). `baseline_commit` (spec-1-3:7, spec-1-4:6) wirkt nur review-zeitlich, nicht als Re-Run-Guard.
|
||||
- **Quelle:** `git ls-files | grep -i test` (keine Tests); `ls .github` (fehlt); `git log --oneline -- schema/wiki-compiler.md schema/validator.md` (Validator nur in c5f97c3, Vertrag in 2625e1d+9e163ad); `_bmad-output/implementation-artifacts/spec-1-4-...md:107–119`.
|
||||
- **Auswirkung:** F-01/F-02 konnten unentdeckt durch die „Zertifizierung" kommen (PASS-Claim in `wiki/log.md:4`); eine Vertragsänderung würde stillen Drift unentdeckt lassen.
|
||||
- **Disposition:** Fix-now (Prozess-/Verifikations-Lektion: ausführbares Fixture-Orakel oder zumindest Abgleich-Schritt Vertrag↔Validator je Autorisation).
|
||||
|
||||
### F-11 — Vertrags-Referenz auf OKF-0.2-Spezifikation nicht verlinkbar (Prosa-Zitat), Normquelle nicht reproduzierbar
|
||||
|
||||
- **Befund:** `schema/wiki-compiler.md:§8` (Z.195) und `schema/validator.md:251` zitieren „OKF-Spezifikation (Google Cloud, `knowledge-catalog`)" ohne URL/Version — die `okf_version`-Regel und §7 Punkt 14 hängen an dieser Quelle, die nicht auflösbar ist.
|
||||
- **Quelle:** `schema/wiki-compiler.md:195`; `schema/validator.md:251`.
|
||||
- **Disposition:** Defer (Normreferenz ergänzen) — kleine Korrektur.
|
||||
|
||||
### F-12 — Adapter-Konformität (AD-10) wird vom Validator nicht geprüft, obwohl Vertrag sie als MUSS normiert
|
||||
|
||||
- **Befund:** Der Vertrag verlangt `adapters/` MÜSSEN mit dem Vertrag konform sein (AD-10, Z.18); der Validator (§1 Z.30–33) erklärt `adapters/` als „nicht validiert". Kein Prüfschritt deckt die Adapter-Semantik ab.
|
||||
- **Quelle:** `schema/wiki-compiler.md:18`; `schema/validator.md:30–33`.
|
||||
- **Disposition:** Accept-as-is (dokumentierte Abgrenzung des Validators auf Bundles; Adapter-Konformität ist Chef-/Review-Verantwortung) — als akzeptierte Abweichung festhalten, damit spätere Retros nicht re-flaggen.
|
||||
|
||||
### F-13 — `sources`-Eintrag ohne `resource` ist als „Punkt 12"-FAIL klassifiziert, obwohl Vertrag-Punkt 12 primär Formverstöße listet
|
||||
|
||||
- **Befund:** `schema/wiki-compiler.md` §7 Punkt 12 (Z.184) nennt Formverstöße (Liste/Map/Skalar); ein Eintrag ohne `resource` ist eine valide Map ohne Pflichtangabe. Der Validator ordnet ihm Punkt 12 zu (Fixture 12a, Z.212). Die Zuordnung ist vertretbar („in nicht erlaubter Form"), aber nicht ausdrücklich im Vertrags-Wortlaut verankert.
|
||||
- **Quelle:** `schema/wiki-compiler.md:184`; `schema/validator.md:67,212`.
|
||||
- **Disposition:** Accept-as-is (interpretationsgetragen, dokumentiert in validators §3 Punkt 12 mit Vertrags-Verweis §3.3) — kein Fix-now, aber als Beobachtung für die Re-Konsistenz bei F-01 mitnehmen.
|
||||
|
||||
### F-14 — `resource`-Pfade, die außerhalb `raw/` landen aber existieren (z. B. `README.md`), haben kein Negativ-Fixture
|
||||
|
||||
- **Befund:** §6.2 Schritt 5 (Z.168) deckt „nicht unter `raw/`" ab, aber es fehlt ein Negativ-Fixture für diesen Fall; Determinsmus ist nur durch Beispiele belegt.
|
||||
- **Quelle:** `schema/validator.md:168` vs. §7.1 (Z.196–216, kein Fall außerhalb raw ohne Traversal).
|
||||
- **Disposition:** Defer (mit Kontext) — Fixture-Ergänzung bei nächster Validator-Revision.
|
||||
|
||||
### F-15 — `stale_after`-Lebenszyklus-Konsequenz (Epic 3) hat keine Verankerung im Deferred-Work-Zeitplan
|
||||
|
||||
- **Befund:** §6.4 (Z.181) verweist auf „Epic 3" für die Konsequenz der Veraltung; `deferred-work.md` listet die BH-8-Ableitung (Z.29–31), ohne konkrete Story-Zuordnung.
|
||||
- **Quelle:** `schema/validator.md:181`; `_bmad-output/implementation-artifacts/deferred-work.md:29–31`.
|
||||
- **Disposition:** Accept-as-is (Epic-3-Gate mit Story-Autorisierung ist vorgesehen; reichen als Verankerung) — als Beobachtung notieren.
|
||||
|
||||
## Behavior-Verifikation (Phase 2)
|
||||
|
||||
**Methodik:** Das Bundle wurde gegen die Validator-Instruktion (Story 1.4) deterministisch ausgeführt (jede §7-/§6-Bedingung als mechanische Prüfung). Ergebnis:
|
||||
|
||||
- **Punkt 8 (Bundleroot):** `wiki/index.md` trägt exakt `type: bundle` + `okf_version: "0.2"`, kein weiteres Feld → PASS.
|
||||
- **Punkt 9 (Exklusivität):** `grep -rn "okf_version\|type: bundle" wiki/` → nur `wiki/index.md` → PASS.
|
||||
- **Punkt 10 (Frontmatter-Exklusivität):** keine Area-`index.md`/`log.md` beginnt mit `---` → PASS.
|
||||
- **Punkt 11 (Index-Regel):** keine Areas vorhanden → nicht auslösbar → PASS (leeres Bundle).
|
||||
- **Concept-Prädikat:** keine Concepts im Bundle → keine Punkt-1/2-Auslöser.
|
||||
- **§3.2-Voraussetzungen:** `wiki/index.md` existiert; kein `log.md` an Nicht-Root-Position → PASS.
|
||||
- **§6.1 EC-1 Existenz:** alle drei `raw/`-Evidenz-Dateien existieren (verifiziert) → PASS (keine Concepts, keine `resource`-Referenzen zu prüfen).
|
||||
- **§6.5 non-md:** keine non-.md-Dateien unter `wiki/` → keine Verletzung.
|
||||
|
||||
**Geprüft-als-sauber:** Die 14 Strukturpunkte und §3.2 sind am realen Bundle zufriedenstellend. Der Lauf deckt aber nur das **leere** Bundle (keine Areas/Concepts) — die eigentliche Validator-Abbildung (F-01 bis F-08) ist anhand der Fixtures statisch geprüft, nicht durch dynamische Fixture-Ausführung. Die §6-Fixtures fehlen (F-02), daher ist die Run-FAIL-Gate-Fähigkeit des Validators für die fachlichen Checks am echten Bundle **nicht** dynamisch bestätigt.
|
||||
|
||||
## Previous-Retro-Follow-through
|
||||
|
||||
Keine frühere Retrospektive vorhanden; Sprint-Status enthält keine `action_items` → nichts nachzuverfolgen.
|
||||
|
||||
## Action Items (Phase 4)
|
||||
|
||||
Vorschläge — werden **nicht** automatisch angewendet; der Mensch entscheidet, was ausgeführt wird.
|
||||
|
||||
| ID | Aktion | Eigentümer | Quelle |
|
||||
|----|--------|-----------|--------|
|
||||
| AI-1 | Validator `schema/validator.md` mit autorisiertem Vertrag re-konsistieren: Fixture 14c/§4.3 (`at` als reines Datum = SUCCESS) beseitigen oder als bewusste Toleranz via Story-Verfahren neu autorisieren (Änderung §3.4/§3.5/§7-Punkt-14 des Vertrags) — damit die 1:1-Abbildung wieder gilt | Story-Verfahren (Dev+Review) | F-01 |
|
||||
| AI-2 | $6-Fixtures ergänzen: EC-1 (Negativ: fehlende `raw/`-Datei; Positiv: vorhandene), EC-3 (Kalender-Validität), stale_after-WARN-Kanal, EC-11 non-md — und Validator-Zertifizierung in `wiki/log.md` gegen erweiterte Fixtures neu ausführen | Dev (Story 1.4-Follow-up) / Review | F-02 |
|
||||
| AI-3 | §3.2-Voraussetzungspflejesten als „Fachliche Prüfung V-1/V-2" labeln (statt „FAIL (Struktur)" außerhalb §5-Grammatik) oder Vertrag §7 um Fall „fehlende Bundleroot" erweitern (mit Autorisierung) | Dev (Validator-Revision) | F-03 |
|
||||
| AI-4 | `source.md`-Provenienz korrigieren: `_bmad-output/` IST versioniert (Herkunft auf Commit-Hash stützen) — Fix in `raw/<quelle>/source.md:13–14`; Deferred-Work-Checksumme (SHA-256) als Konsequenz voranbringen | Dev (Story-1.2-Follow-up) | F-09 |
|
||||
| AI-5 | BOM-/Leerzeilen-Stripping von Punkt 10 auf Punkte 2/8 erweitern (einheitliche Frontmatter-Erkennung) | Dev (Validator-Revision) | F-05 |
|
||||
| AI-6 | Ausführbare/mechanische Verifikation des Validators einführen (Fixture-Orakel-Skript oder zumindest Vertrag↔Validator-Abgleich je Autorisation) — minimiert Wiederauftreten von F-01/F-02 | Prozess (BMAD-Dev-Schleife) | F-10 |
|
||||
| AI-7 | Defer-Kontexte sichern: F-04 (verschachtelte Duplikat-Keys), F-06 (`today`-Zeitzone), F-07 (Index-Regel bei verschachtelten Areas), F-08 (`.MD`-Großschreibung), F-11 (OKF-Referenz-URL), F-14 (`raw/`-extern-Fixture) — als Folge-Aufgaben für Epic-2/3 oder Validator-Revision notieren | Epic-2/3-Planung | F-04…F-15 |
|
||||
|
||||
Keine Zeitangaben — bewusst.
|
||||
|
||||
## Acceptance-Verdict (Phase 4)
|
||||
|
||||
**Verdikt: `accepted-with-open-items`**
|
||||
**Kriterien:** profiled (keine deklarative Akzeptanzliste; aus Story-Intent + Epic-Context + Vertrag §7/§8 abgeleitet).
|
||||
|
||||
**Begründung:**
|
||||
- Alle 4 Stories sind `done`; `pending_stories` leer → kein Rejected-Zwang.
|
||||
- Die deklarierten Ziele sind im Wesentlichen erreicht: Workspace-Stamm (Stories 1.1/1.2) korrekt etabliert, `raw/`-Evidenz byte-identisch materialisiert und immutable (verifiziert), Vertrag autorisiert (1.3), Validator-Instruktion liegt vor und bildet die 14 Punkte 1:1 ab (1.4).
|
||||
- **Aber:** Drei Befunde (F-01, F-02, F-03) betreffen die Kern-Fähigkeit „Deterministische Validierung bildet die Norm 1:1 ab und ist reproduzierbar prüfbar" (AD-17h, F-2/AD-1b). F-01 ist ein unautorisierter Bruch mit dem Vertrag, F-02/F-03 sind Verifikations-/Klassenlücken. Die ist ein dokumentierter, nicht-blokkierender Rest, der als offene Items (AI-1…AI-3) adressiert wird.
|
||||
- Kein Blocker für nachfolgende Epics: Epic 2 kann mit dem heutigen Validator Concepts validieren (die 14 Strukturpunkte sind abgedeckt). Die F-Items sind Follow-ups, kein Stop.
|
||||
- Menschliche Bestätigung: Keine — Verdikt ist eine Maschinen-/Analysten-Entscheidung. Ein Mensch darf es überstimmen.
|
||||
|
||||
## Offene Fragen
|
||||
|
||||
1. **F-01 entgegen dem frozen-intent:** Ist die `at`-als-Datum-Toleranz als bewusste Vertragserweiterung gewollt (dann Story-Autorisierung) oder ein Review-Schlupf? Die Antwort ändert, ob der Vertrag oder der Validator zu ändern ist.
|
||||
2. **F-07 (Index-Regel):** Wie tief sollen Areas/Unterordner gehen? Epic-2 legt die Antwort fest (Story 2.5 progressive Discovery).
|
||||
3. **Verifikations-Tiefe:** Soll das Projekt zu einem ausführbaren Fixture-Orakel wechseln (D-3 erlaubt nur Instruktionen — ein Orakel würde die D-3-Grenze berühren)? Oder bleibt es beim dokumentarischen Abgleich?
|
||||
|
||||
## Assumptions
|
||||
|
||||
Interaktiver Lauf: keine headless-Annahmen. Der Epic wurde aus `detect-epic` bestätigt (höchstes Epic mit `done`-Story); der Nutzer wurde eingangs um Going-in-Themen gebeten (keine Rückmeldung — Analyse lief ohne Zusatzgewicht).
|
||||
@@ -0,0 +1,42 @@
|
||||
# Epic 2 Context: OKF-Concepts erzeugen & verlinken
|
||||
|
||||
<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
|
||||
|
||||
## Goal
|
||||
|
||||
Aus dem lokal bereitgestellten Source Material (Epic 1) entstehen eigenständige, OKF-0.2-konforme Concepts: neue kuratierte Wissenseinheiten, die nicht an die Struktur der Quelle gebunden sind. Jede belegte Aussage trägt claim-granulare Provenienz auf `raw/`-Evidenz; maschinell erzeugte Concepts tragen die v1-Trust-Metadaten (`generated` ohne `verified`). Concepts werden über genau eine erlaubte Markdown-Linkform (AD-7b) miteinander verlinkt, per deterministischer Bereichszuordnung (AD-7c) in eine Bundle-Hierarchie eingeordnet und über `index.md` progressiv entdeckbar — ohne proprietäre Datenbank.
|
||||
|
||||
## Stories
|
||||
|
||||
- Story 2.1: Concepts aus Source Material erzeugen (OKF-konform)
|
||||
- Story 2.2: Claim-granulare Provenienz dokumentieren
|
||||
- Story 2.3: Concepts verlinken (eine erlaubte Linkform)
|
||||
- Story 2.4: Deterministische Bereichszuordnung & Concept-Hierarchie
|
||||
- Story 2.5: Progressive Discovery über `index.md` bereitstellen
|
||||
|
||||
## Requirements & Constraints
|
||||
|
||||
- Concepts werden anhand erkannter Wissenseinheiten erzeugt, nicht 1:1 pro Source-Abschnitt; mehrere Abschnitte einer Source können in verschiedene Concepts fließen. Concepts sind eigenständiges kuratiertes Wissen, keine Kopie oder Zusammenfassung des Quelldokuments (FR-5).
|
||||
- Jedes erzeugte Concept ist OKF-0.2-konform: Markdown mit YAML-Frontmatter, `type` als einziges Pflichtfeld; optional `sources`, `generated`, `verified`, `status`, `stale_after`. Das zulässige Feldsubset und seine Validität bindet `schema/wiki-compiler.md` (AD-1a). Kein eigener OKF-Dialekt.
|
||||
- Provenienz ist claim-granular: jede belegte Aussage trägt einen Inline-Verweis auf `raw/`-Evidenz; Kontext-/Synthese-Umformulierungen tragen einen expliziten Kontext-Marker ("übernommen aus `<Concept>` auf Basis von `<source>`, nicht eigenständig belegt") (AD-4a, A0-3).
|
||||
- `sources`-Einträge lösen ausschließlich auf `raw/`-Pfade oder extern referenzierte immutable Evidenz auf — nie auf `wiki/`-Concept-Pfade (AD-4b, A0-4).
|
||||
- Es muss wirkungsvoll verhindert werden, dass generierte Concepts als eigene Evidenz verwendet werden: kein generiertes Concept darf ein anderes generiertes Concept als alleinige Provenienz führen — prüfbar über die Schema-Validierung (AD-4c, A0-5).
|
||||
- Beziehungen zwischen Concepts werden als normale Markdown-Links ausgedrückt — in genau einer erlaubten Form: bundle-relativ, mit oder ohne Endung, nie beides (FR-10, AD-7b, A0-9). Links sind die Navigations-/Beziehungsschicht, nicht die Provenienz; keine proprietäre Link-Datenbank, herkömmliche Markdown-Tools müssen den Link auflösen können (AD-8).
|
||||
- Bereichszuordnung ist textual-deterministisch zu bestimmen (bestehender `index.md`-Link oder Top-Level-Kollisions-Hold auf bestehende Pfade), nie per Embedding/Vector-Infrastruktur (AD-7c, A0-10, AD-13).
|
||||
- Concepts bleiben unmittelbar menschlich lesbares Markdown und für LLM-Agenten über Standard-Dateioperationen erschließbar; unvollständiges, ungeprüftes Wissen wird ohne künstliche Gewissheit dargestellt (NFR-2, NFR-3, NFR-7).
|
||||
|
||||
## Technical Decisions
|
||||
|
||||
- **Concept-Identität (AD-7a, A0-8):** Identität ist der relative OKF-Pfad ohne `.md`-Endung (`wiki/spring/index.md` → `spring`); genau eine kanonische ID-Normalisierung für alle Producer. Renames sind semantische Änderungen und erfordern einen Redirect-/Deprecation-Eintrag in `log.md`, damit alte IDs maschinell auffindbar bleiben (AD-7d).
|
||||
- **Linkform ist gepinnt (AD-7b):** exakt eine Form (bundle-relativ, mit oder ohne Endung) — verhindert, dass zwei Producer aus demselben Baum unterschiedliche IDs berechnen. Der Link-Bestand ist die Navigationsschicht; eine spätere Graph-Ableitung ist optional und nie kanonisch (AD-8).
|
||||
- **Provenienzmodell (AD-4a..c):** Inline-`raw/`-Verweise pro Aussage plus Kontext-Marker für Übernahmen; `sources` zeigen nie auf `wiki/`; die "keine abgeleitete Provenienz"-Regel ist Teil der `schema/wiki-compiler.md`-Validierung.
|
||||
- **Hierarchie & Discovery (AD-9, AD-1):** `wiki/` ist Bundleroot; Areas folgen `<area>/index.md` + `<concept>.md`. Discovery läuft Bundle-Root `index.md` → Area-`index.md` → Concepts; ein neu angelegtes Concept wird im `index.md` seines Bereichs verlinkt. Search ist optionale, spätere, Consumer-seitige Optimierung; das Bundle bleibt ohne geladene Indizes (z.B. nach Git-Clone) vollständig verständlich.
|
||||
- **Trust-Metadaten v1 (AD-15, A0-20):** maschinell erzeugte Concepts erhalten `generated: { by, at }`, `verified` bleibt ungesetzt; Lifecycle optional über `status` (`draft` | `stable` | `deprecated`) und `stale_after`.
|
||||
- **Kein Server, keine Datenbank:** alle erzeugten Artefakte sind normale textuelle Dateien im Git-Workspace; jede Änderung bleibt über Git-Diff nachvollziehbar (AD-1, AD-11, AD-14).
|
||||
|
||||
## Cross-Story Dependencies
|
||||
|
||||
- Setzt Workspace-Trennung, Bundle-Root und das OCKF-Feldsubset aus Epic 1 (Story 1.1, 1.3, 1.4) voraus. AD-4c (keine abgeleitete Provenienz) ist in v1 tautologisch erfüllt — `sources` zeigt ausschließlich auf `raw/`, daher kann kein generiertes Concept ein anderes generiertes Concept als alleinige Provenienz führen (Vertrag §6.1: erzeugt **kein** eigenes Validitätsprädikat; kein eigener Validator-Check).
|
||||
- Die hier erzeugten Concepts, Links und `index.md`-Strukturen sind die Eingabe für die inkrementelle Kompilation und Synthese (Epic 3) sowie für Widerspruchs- und Kuratierungs-Kontexte (Epic 4).
|
||||
- Identität und Verlinkung dieses Epics werden von den Consumers in Epic 5 unverändert gelesen.
|
||||
- Keine UX-/Design-Anteile relevant für diesen Epic: v1 ist datei-/CLI-basiert ohne GUI (A-3, AD-11).
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
epic: 2
|
||||
date: 2026-08-18
|
||||
verdict: accepted-with-open-items
|
||||
criteria: declared
|
||||
headless: false
|
||||
---
|
||||
|
||||
# Retrospective Epic 2 — OKF-Concepts erzeugen & verlinken
|
||||
|
||||
## Epic summary
|
||||
|
||||
- **Epic:** 2 — OKF-Concepts erzeugen & verlinken
|
||||
- **Diff-Range:** `a67ba65..f41ac71` (erster Story-Commit `6105a7b^` … letzter Commit `f41ac71`)
|
||||
- **Commits:** 15 im Range (davon 2 Merges: `7e1f449` Story 2.2, `64a0f6a` Story 2.4; beide gemessen). Nicht-Merge-Churn in `schema/`+`wiki/`: 543 Insertions / 6 Deletions über 9 Dateien.
|
||||
- **Stories:** 2.1 (done), 2.2 (done), 2.3 (done), 2.4 (done), 2.5 (done) — keine pending. `epic-2-retrospective`: optional → wird in Phase 5 auf `done` gesetzt.
|
||||
- **Abnahmekriterien:** deklariert in `_bmad-output/planning-artifacts/epics.md` (Epic-2-Block + Stories 2.1–2.5, je AC-Zeilen) → Verdikt-Basis **declared**.
|
||||
- **Evidence-Inventar:**
|
||||
- Story-Specs 2.1–2.5 unter `_bmad-output/implementation-artifacts/` (jede mit `baseline_commit`/Verification-Beleg)
|
||||
- `schema/compiler.md` (317 Z., 84 KB; Revision 2.3; +404/−87 net über 11 Commits) — das eigentliche Lieferprodukt (Agent-Instruktion mit re-executierbaren Selbsttest-Formeln, §5.5–§5.8, §6.5/§6.6)
|
||||
- `schema/validator.md` (Rev 8): der Diff-Range enthält die **Rev-8-Autorisationsrunde** (Option-A-Heilung Story 2.1, Ende Epic 1) — für Epic 2 konform unverändert (AD-3/D-3-Freeze); der bekannte Punkt-11-Vorbehalt (file-relative Area-Lesart) bleibt offen und ist Rev-9-Aktionsitem
|
||||
- Wiki-Baum (7 Dateien): `index.md`, `log.md`, 3 Root-Concepts, `wissensarchitektur/index.md` (Area), `wissensarchitektur/source-material.md` (Area-Concept)
|
||||
- `_bmad-output/implementation-artifacts/deferred-work.md` (append-only), `sprint-status.yaml` (2-5 Retro key), `wiki/log.md` (32 Z., 5 Einträge Story 2.1–2.5 + Nachweise)
|
||||
- **Fehlend:** Session-Logs (nicht in dieser Umgebung verfügbar) → Prozess-Lektionen nur aus git-loggablem Verhalten; die Verhaltens-Verifikation wurde stattdessen durch Re-Exekution der Selbsttest-Formeln ersetzt (Abschnitt Behavior verification).
|
||||
|
||||
<!-- ============================ FINDINGS ============================ -->
|
||||
|
||||
## Findings
|
||||
|
||||
Drei Blickwinkel: (a) Aggregat-Ansichten (über den gesamten Diff-Range deterministisch erhoben), (b) Verhaltenscheck der Selbsttest-Formeln (re-executiert, Abschnitt Behavior verification), (c) Diff-Scope-Review — bmad-review-Code-Linsen (Adversarial / Edge-Case-Hunter / Verification-Gap) über den Schema+Wiki-Diff. Jedes Finding trägt Quelle (Datei : Zeile/Commit) und Disposition (fix now / defer / accept).
|
||||
|
||||
### F-01 — §5.5-Provenienz-Selbsttest-Formel ist nicht rekursiv und übersieht jeden Area-Concept-Kontakt (Adversarial F1, Edge-Case #4; **fix now, Kern-Defekt Story 2.4/2.5**)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.5 Pkt. 1/4, Z. 81/104 — `sh -c "grep -nE '\(raw/' wiki/*.md"`.
|
||||
- **Beleg (live):** `wiki/*.md` (root-only) → **29** Treffer; rekursiv `wiki/` → **43**; das Area-Concept `wiki/wissensarchitektur/source-material.md` trägt **5** `(raw/`-Verweise, die die dokumentierte Formel nie inspiziert. Die Kriterien in Z. 104–106 („belegte Aussage → Inline-`raw/`-Verweis je Beleg auffindbar per `grep -nE '\(raw/') behaupten eine bundeweite Selbstprüfung.
|
||||
- **Auswirkung:** Die claim-granulare Provenienz-Garantie (FR-3/AD-4a) und der AD-17h-Determinismus-Anspruch sind für die Artefaktklasse, um die es in Story 2.4/2.5 geht (Area-Concepts), faktisch nicht exerziert: Ein fehlender/typo-hafter Inline-`raw/`-Verweis im Area-Concept passiert den Selbsttest still. Der Formeltext „erfasst also …" (Z. 81) ist unvollständig.
|
||||
- **Wurzel:** Shell-Glob `wiki/*.md` ist root-only; keine `-r`, kein `--include`.
|
||||
- **Disposition & Prävention:** **fix now** → Formel auf rekursiv `grep -rnE '\(raw/' wiki/ --include='*.md' --exclude=log.md` (bzw. Area-inkludierend) umstellen; Lektion: re-executierbare Formeln müssen der **gewachsenen Baumstruktur** des Folge-Epics folgen (Area-Ebene seit Story 2.4).
|
||||
|
||||
### F-02 — Punkt-11-Wortlaut vs. gepinnte file-relative Area-Linkform: Instruktion und Validator sind strukturell nicht gleichzeitig „in force" (Adversarial F2/F10, Verification-Gap F2; **fix now (autorisierte Rev-9)**, alternativ Doku-Defer)
|
||||
|
||||
- **Quelle:** `schema/validator.md` Punkt 11 (Rev 8, Z. 70: „als relativer **Bundle-Pfad**"); `schema/compiler.md` §5.6 Pkt. 1 (Z. 129–131: file-relativ mit `.md`-Endung), §5.8 Pkt. 2 (Z. 229, „Bekannte offene Lücke … wörtlich-mechanischer Check meldete `Concept nicht verlinkt=wissensarchitektur/source-material`"); `deferred-work.md` Z. 284–287 (Status offen, Rev-9-Aktionsitem).
|
||||
- **Beleg (live):** `wiki/wissensarchitektur/index.md` Z. 9 verlinkt file-relativ `](source-material.md)`; die wörtliche Identität `wissensarchitektur/source-material` kommt in `wiki/index.md` **nicht** vor (grep → 0). Ein wörtlich-mechanischer Rev-8-Punkt-11-Check würde das Area-Concept als „nicht verlinkt" melden — das Live-Bundle zeigt genau diese Lage.
|
||||
- **Auswirkung:** Die §5.8-Discovery-Teilachse „Rooth→Area→Concept" ist **nicht unabhängig** re-verifizierbar (Verification-Gap F2): die §5.8-Selbsttest-Formel deckt nur Root→Area (Lauf A) und Tiefe ≥ 3 (Lauf B); die Area→Concept-Koordinate wird an einen Punkt 11 delegiert, dessen Wortlaut die formale Clusterung der §5.6-Pin-Form widerspricht. Das Log („alle 7 SUCCESS inkl. Punkt 11") ist nur über eine **aufgelockerte** Punkt-11-Lesart konsistent.
|
||||
- **Wurzel:** Punkt 11 (frozen, Vertrag §7) kennt keine file-relative Area-Schreibweise; die Pin-Form (Story 2.3) und die Area-Link-Logik (Story 2.4/2.5) sind Produkt der Instruktionsebene ohne Vertrags-/Validator-Change (AD-3-Doktrin).
|
||||
- **Disposition & Prävention:** **fix now** → Erteilung der **autorisierten Validator-Rev-9** mit formalisierter Punkt-11-Area-Lesart (relative OKF-Pfad-Identität, auch file-relativ in Area-Index; bereits als Action-Item `code-review-2-1-item-2` gehalten). Lektion: Der D-3/AD-3-Freeze darf Vertrag/Validator nur ändern, wenn er formal autorisiert wird; „kein Change" muss dieselbe Währung (autorisiert vs. offen) wie „Change" tragen.
|
||||
|
||||
### F-03 — §5.8-Lauf B „schließt die Area-ohne-`index.md`-Lücke" — tatsächlich blind für die Tiefe-2-Variante (`wiki/<a>/concept.md` ohne `index.md`) (Edge-Case #2; **fix now**, konservativ Defer)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.8 Pkt. 2 (Z. 216: Lauf A `find -mindepth 2 -name index.md`, Lauf B `find -mindepth 3`); Prosa Z. 223/230 („schließt auch die Area-ohne-`index.md`-Lücke").
|
||||
- **Beleg (Sandbox, synthetischer Baum `wiki/a/concept.md` ohne `wiki/a/index.md`):** §5.8-Formel exakt aus Z. 216 → **keine Ausgabe, Exit 0** = Discovery-SUCCESS auf einem Bundle, das strukturell invalide ist (Area ohne Index → Validator Punkt 11). Lauf A findet kein `index.md`, Lauf B beginnt bei Tiefe 3, das Konzept liegt auf Tiefe 2.
|
||||
- **Auswirkung:** Ein Producer kann die Area-`index.md` vergessen und der §5.8-Selbsttest meldet SUCCESS; die einzige Schutzlinie ist der (nicht re-runbare, bekannte) wörtliche Punkt-11-Sandbox-Nachweis.
|
||||
- **Wurzel:** Beide Läufe sind `find`-Schwellen, keine strukturelle Konzept-Derivation.
|
||||
- **Disposition & Prävention:** **fix now (einfach)** → Lauf A um „Area-Concept ohne Area-`index.md`" erweitern (z. B. Ordnung `wiki/<a>/<concept>.md` ohne `index.md` jenseits einer Area melden), oder dokumentiert als konservatives Defer (bestehende Punkt-11-Linie fängt es ab, sobald Rev-9 die Lesart trägt).
|
||||
|
||||
### F-04 — Formel-4-Basisfilter-Asymmetrie: `--exclude=log.md` (Ist) vs. `grep -v "log.md$"` (Extraktion) invertieren sich für `…log.md`-suffigierte Konzepte (Edge-Case #3; **fix now**)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.6 Pkt. 3 Formel 4 (Z. 162–163); `deferred-work.md` (Basename-Ziel-Loop-2-Fix).
|
||||
- **Beleg (Sandbox):** Konzept `wiki/analog.md` → Ist (`--exclude=log.md`, Basename gleich `log.md`) zählt es **ein**; Extraktionsfilter (`grep -v "log.md$"` — Basename-**Endung**) schließt aus, simuliert: Ist 2 vs. Extraktion 0 → deterministischer **Fehlalarm** `38 ≠ Baseline` auf einem konformen Baum.
|
||||
- **Auswirkung:** Ein legitimes kebab-slug-Konzept, dessen Name auf `log` endet (`analog`, `compiler-log`, …), bricht Formel 4 ohne inhaltlichen Grund — und zwar genau durch den Loop-2-Basename-Fix, der die umgekehrte Inversion (künftiges Area-`log.md`) heilen sollte.
|
||||
- **Wurzel:** `--exclude=log.md` ist genau-Basename (= `log.md`), `grep -v "log.md$"` ist Endungs-Muster (jegliches `xlog.md`) — die beiden filter semantisch unvereinbar.
|
||||
- **Disposition & Prävention:** **fix now** → beide Filter auf dieselbe Semantik bringen (entweder genau-Basename `log.md` auf beiden Seiten — z. B. `--exclude=log.md` für die Extraktion via `git ls-tree ... | grep -v '^wiki/log\.md$'` — oder rekursiv-Basename `grep -v '/log\.md$'` in beiden). Lektion: „Basename-Filter" meint je nach Formel etwas anderes; jede Formel4-Seite muss nominal die nämliche Exklusionsmenge bilden.
|
||||
|
||||
### F-05 — §5.8-Lauf A erkennt „reachability" auf nicht-navigationalen Text (Code-Fence/Blockquote) und akzeptiert die `./`-Variante, die der §5.6-Form-Check exkludiert (Verification-Gap F1, Edge-Case-Replik; **fix now**)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.8 Pkt. 2, Z. 216 (Lauf A, `grep -qF "]($a/index.md"`); §5.6 Pkt. 3 Formel 2 (Z. 146, `grep -vE '^\.'`) attackiert `./`-Ziele.
|
||||
- **Beleg:** (a) Lauf A als roher Substring über die ganze Datei (auch in Code-Fence/Blockquote/comments) → Bereich aus Fence „verlinkt" ohne Navigationslink (AD-9 gebrochen). (b) `./`-Varianten: Lauf A akzeptiert `](./a/index.md` (verifikationsrelevante Alternative), Formel 2 exkludiert `./`-Präfixe als „keine Bundle-Pfad-Form" → **zwei Checks widersprechen sich über die „gepinnte Form"** (FR-10: genau eine erlaubte Form).
|
||||
- **Auswirkung:** Die AD-9-Navigationsgarantie ist nur textuell (Substring), nicht strukturell abgesichert; das „genau-eine-Form"-Pin ist zwischen §5.6 und §5.8 nicht eindeutig.
|
||||
- **Wurzel:** `grep -qF` ist markdown-agnostisch; die `./`-Variante wurde in Manche Dokumentationen als zulässig erachtet (Loop-2-Eintrag „beide Varianten zulässig") — die Form-Check-Schärfung von Story 2.3 (AD-7b) ist damit inkonsistent.
|
||||
- **Disposition & Prävention:** **fix now** → Lauf A mit Link-Syntax-prüfenden Greps (nur echte `](`-Markdown-Links, nicht Code-Fence/Blockquote) bzw. `./`-Variante aus dem §5.6-Pin nehmen oder §5.8 auf die Pin-Form ausrichten; Lektion: Ober- und Unter-Checks müssen dieselbe „erlaubte Form" definieren.
|
||||
|
||||
### F-06 — Formel-4-Baseline an einen Commit (`862cf41`) gepinnt; erneute Datei-Zuwächse (= jeder künftige neue Concept/Area) erfordern eine Re-Baseline-Pflicht ohne definierte Policy (Adversarial F3; **accept** mit dokumentierter Folge)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.6 Pkt. 3 Formel 4 (Z. 163) — `git ls-tree ... 862cf41 ... | git show ...`; Story-2.4-Re-Baseline (Loop-2-Decision-1: Run-Kopf statt Vor-Zustand).
|
||||
- **Beleg:** `git diff --name-only 862cf41..HEAD -- wiki/` → `log.md` + `index.md` geändert, obwohl Story 2.5 **keine** neue Datei brachte; die Baseline-Extraktion aus dem gepinnten Commit ist gegen einen Baum-Zustand `HEAD` nicht byte-stabil. Der Text (Z. 166) dokumentiert, dass jeder Datei-Zuwachs eine Re-Baseline auf den dann aktuellen Run-Kopf erfordert — es gibt aber **keine** zitierbare Regel, welcher Commit „der dann aktuelle Run-Kopf" für einen Content-mutierenden (nicht Datei-hinzufügenden) Run wäre.
|
||||
- **Auswirkung:** Die AD-17h-Meldung „die Baseline wird deterministisch aus dem Baseline-Commit des letzten Zuwachs-Runs dynamisch extrahiert" ist eine O(n)-über-Runs-Operation; die Kopplung an den Einstellungs-Commit ist die schwächste strukturelle Stelle der Formel-Suite (konservatives Verhalten erkannt, keine echte Determinismus-Verletzung heute).
|
||||
- **Disposition & Prävention:** **accept** — dokumentierter, eingebauter Kompromiss von AD-17h (keine Standalone, keine künstliche Datei-Metadaten-Quelle); dennoch als **offene Folge** notieren: Re-Baseline-Policy (Definition „Zuwachs-Run", Umgang mit Content-Drift ohne Datei-Zuwachs) für Epic 3 präzisieren. Kein Action-Item (bereits in Epic-3-Nähe thematisiert), aber im Open questions-Block festgehalten.
|
||||
|
||||
### F-07 — `grep -vE ':'` / `case *:*` schlucken kolonhaltige Ziele still (bricht Pin- und Dangling-Check) (Adversarial F6; **defer**)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.6 Pkt. 3 Formel 2 (Z. 146) / Formel 3 (Z. 154, `case "$t" in ""|*:*|…`).
|
||||
- **Beleg:** Ein Ziel mit `:` (z. B. `file.md#sec:2`, Windows-Kopfpfad) wird von Pin- und Dangling-Check **exkludiert statt geflaggt** — eine normative Verletzung wird zu einer ungeprüften, stillen Null-Op. (Live: kein derartiges Ziel — nicht auf dem aktuellen Baum.)
|
||||
- **Disposition & Prävention:** **defer** — dokumentiert in `deferred-work.md` (konservativ); Lektion: Exklusions-Klassen müssen als „nicht am Pin-Teil des Bundles" deklariert bzw. selbst überprüft werden (möglicher kleiner Dangling-Sonderfall).
|
||||
|
||||
### F-08 — Form-Check `../`-Exklusion bedeutet: `../`-Ziele werden nie auf `.md`-Endung geprüft (Adversarial F5; **defer**)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.6 Pkt. 3 Formel 2 Z. 146 (`grep -vE '^(raw/|\.\./|#)'`).
|
||||
- **Beleg:** `[x](../ohne-endung)` (existierende extensionless Datei) passiert Form-Check (Ziel ist `../`-exkludiert) und Dangling-Check (Datei existiert) → Pin-Verletzung (keine `.md`-Endung) unentdeckt.
|
||||
- **Disposition & Prävention:** **defer** — bekannte konservative Lücke; Sonderfall nur für `../`-Ziele. Lektion zur Formel-Schärfung für Epic 3.
|
||||
|
||||
### F-09 — `sources`-`id`-Eindeutigkeit, Marker-Grammatik, Sources-Closure, Fragment-Existenz, Content-Truth bleiben ungeprüft — Story 2.4/2.5 fügt keine Checks hinzu (Verification-Gap Confirmation; **defer** — bereits Defer-Kontexte)
|
||||
|
||||
- **Quelle:** §5.5 Pkt. 3/4 (Prosa); `deferred-work.md` W1–W4, L197–212 (Marker-Grammatik, `sources[].id`-Eindeutigkeit, Sources-Closure, Fragment-Existenz, Content-Truth).
|
||||
- **Beleg:** Weder §5.6/§5.8-Formeln noch Validator prüfen Wert-Duplikate (`id`), Marker-Syntax über den Token „nicht eigenständig belegt" hinaus, Inline→`sources`-Closure, Fragment-Existenz in `raw/` oder Body↔`sources`-Korrespondenz. Letztere bleiben nachweislich still-passierend; das aktuelle Bundle ist nur durch Konvention gepflegt.
|
||||
- **Disposition & Prävention:** **defer** — alle bereits in `deferred-work.md` verankert; keine neue Lücke durch 2.4/2.5. Lektion: Diese Unschärfen sind die Hauptkandidaten für eine Epic-3-mechanische Schicht (D-3-konform).
|
||||
|
||||
### F-10 — §5.7-Routing-Prädikat (a) ist nicht re-runnable; „kanonischer Name des Themas" ist Urteilsinput ohne Ableitungsformel (Adversarial F7/F8-Variante, Edge-Case #5/#6, Verification-Gap F3/F4; **accept** (designiert), dokumentierter Urteils-Spielraum)
|
||||
|
||||
- **Quelle:** `schema/compiler.md` §5.7 Pkt. 1(a) (Z. 183) — „Identität seines Link-Ziels … gleich dem kanonischen Namen des neuen Themas".
|
||||
- **Beleg:** Der linke Operand (kanonischer Name) wird durch keine Formel, keinen Grep, keine Tabelle abgeleitet — er ist Producer-Interpretation aus §2. Zwei Producer können für dieselbe Einheit unterschiedliche kanonische Namen ableiten und unterschiedlich routen, obwohl die Instruktion „textual-deterministisch" fordert (AD-13/A0-10). Zudem: Die Area-Variante — Bundleroot enthält inzwischen einen Area-Navigations-Link (`wissensarchitektur/index.md`, Identität `wissensarchitektur`) — ein neues Thema mit Namen `wissensarchitektur` trifft auf den Tie-Break „Bundleroot-Links schlagen Area-Links → Root-Ebene", der für Area-Links unzutreffend ist. Beide Stellen sind textual-deterministische Überreste: kein re-runbarer Check verhindert eine falsche Platzierung (Platzierung in falscher Area passiert Validator/Formeln/§5.8 still).
|
||||
- **Disposition & Prävention:** **accept** — die Routing-Entscheidung ist die einzige neue Story-2.4-Regel ohne ausführbares Artefakt; sie ist bewusst ein Interpretationsschritt („Ask-First" Rücksprache-Pflicht vorhanden). Als **offene Frage** notieren: Wie mechanisch kann „kanonischer Name" in Epic 3 werden (grep/ripgrep über `index.md`-Baum), ohne ein neues Urteils-Element einzuführen?
|
||||
|
||||
### F-11 — Aggregat: `schema/compiler.md` ist der unangefochtene God-File des Epic (84 KB, 317 Z., +404/−87); Struktur-Drift im Diff (Aggregat-Blickwinkel; **accept** mit Epic-3-Schritt)
|
||||
|
||||
- **Quelle:** `git log --numstat a67ba65..f41ac71 -- schema/compiler.md` (11 nicht-Merge-Commits), `wc -l schema/compiler.md` (317 Z., 84 KB); `grep -n '^##'` → 18 Sektionen, davon §5.x-Instruktionen 5.5/5.6/5.7/5.8.
|
||||
- **Beleg:** Das Lieferprodukt ist eine einzelne Instruktionsdatei, in der jede Story eine neue Sektion „anklebte" (§5.5 → §5.6 → §5.7 → §5.8); die Sektionen referenzieren sich gegenseitig zirkulär (z. B. §5.8 ↔ §5.6 ↔ §5.7), was die F-01/F-04/F-05-Fehlschläge begünstigt. Kein Duplikat-Problem (keine parallelen Erzeugungsinstruktionen), aber wachsende kognitive Last und zunehmende Formel-Zahl (4+1 im Diff).
|
||||
- **Disposition & Prävention:** **accept** — als Dokumentations-God-File vertretbar (agent-reader, keine Code-God-Klasse); als **Handlungsempfehlung** für Epic 3: Struktur-Aufteilung oder Querverweis-Register erwägen, um die Fehlschlagschneisen zwischen §5.5–§5.8 zu senken. Kein Auto-Fix (siehe Open questions).
|
||||
|
||||
### F-12 — Validator-File als Lieferumfang: das validator.md-Delta im Diff ist die **Rev-8-Autorisationsrunde** (Ende Epic 1), kein Epic-2-Change (Aggregat-Klarstellung; **accept**, Registrierung)
|
||||
|
||||
- **Quelle:** `git diff a67ba65..f41ac71 -- schema/validator.md` (Revisionszahl 6→8, Punkt-4 Fixture 4a, §7.3-Isolations-Notiz) vs. `wiki/log.md` (Rev-8-Autorisationsrunde, 2026-08-16).
|
||||
- **Beleg:** Epic 2 selbst (Story 2.1–2.5) änderte `schema/validator.md` **nicht** (AD-3-Doktrin); das Delta stammt aus der autorisierten Rev-8-Runde zur Story-2.1-Freigabe — semantisch Epic-1-Abschluss, wird per Diff-Range-Eckung in Epic 2 mitgezählt.
|
||||
- **Disposition:** **accept** — Klarstellung zur Wahrnehmung des Diffs; kein Defekt.
|
||||
|
||||
<!-- ============================ BEHAVIOR VERIFICATION ============================ -->
|
||||
|
||||
## Behavior verification (re-executierbare Selbsttest-Formeln gegen Live-Baum)
|
||||
|
||||
Die „Laufzeit" dieses Epics sind die eingebetteten Shell-Formeln (D-3, AD-17h). Alle wurden am 2026-08-18 gegen den Live-Baum im Workspace re-exekutiert:
|
||||
|
||||
| Check | Erwartung | Beobachtung (Live) |
|
||||
|---|---|---|
|
||||
| §5.6 Formel 1 (Bestands-Check) | Übersicht aller `](`-Links, Exit 0 | 14 Ziele; Exit 0 |
|
||||
| §5.6 Formel 2 (Form-Check) | `0`, Exit 0 | `0`, Exit 0 |
|
||||
| §5.6 Formel 3 (Dangling-Check) | keine Ausgabe | keine Ausgabe, Exit 0 |
|
||||
| §5.6 Formel 4 (Kontakt-mit-`raw/`) — Ist | `38` | `38` |
|
||||
| §5.6 Formel 4 (Extraktion aus Run-Kopf `862cf41`) | `38` | `38` (`38 ≡ 38`) |
|
||||
| §5.8 Selbsttest (exakt Z. 216, beide Läufe) | keine Ausgabe, Exit 0 | keine Ausgabe, Exit 0 |
|
||||
| §5.8 CWD-Präguard (außerhalb Workspace-Root) | `SELBSTTEST-SETUP-Fehler…` + Exit 1 | exakt so, Exit 1 |
|
||||
|
||||
**Quell-Konsistenz:** Die Nachweise in `wiki/log.md` (Story 2.4/2.5-Einträge) decken sich mit diesen Re-Runs: Formel 2 `0`, Formel 3 leer, Formel 4 `38 ≡ 38`, §5.8 leer+Exit 0, Präguard-Sandbox-Nachweis (`SELBSTTEST-SETUP-Fehler…`+Exit 1) — alle **verifiziert**.
|
||||
|
||||
**Abweichung / Lücke:** Der in `log.md` behauptete „alle 7 `wiki/`-Dateien SUCCESS (inkl. Punkt 11, EC-1)" ist bei Rev-8-wörtlicher Punkt-11-Lesart der file-relative Area-Link nicht mechanisch reproduzierbar (vgl. F-02): das Bundle-Verdikt ist über die aufgelockerte Lesart konsistent, der wörtliche Check nicht. Es bleibt ein Rev-9-Aktionsitem.
|
||||
|
||||
**Bewusst nicht erneut exerziert:** Die Validator-Festhalte-Fixtures (§7.1–§7.3), die Rev-8-Zertifizierung und die Sandbox-Negativtests (`TOP_LEVEL_COLLISION`, `AREA_WITHOUT_INDEX`, `DANGLING`-Fälle) sind in `validator.md`/`log.md` ausführlich belegt und in früheren Runden re-zertifiziert; sie wurden hier stichprobenartig (F-02/F-03) bestätigt, nicht vollständig wiederholt.
|
||||
|
||||
<!-- ============================ PHASE 4 / DECIDE ============================ -->
|
||||
|
||||
## Action items (fix-now-Routing aus den Findings)
|
||||
|
||||
Die folgenden F-Items sind fix-now geroutet und werden als Action-Items zur Ausführung im normalen Dev-Loop **vorgeschlagen** (Retrospective schlägt vor, wendet nicht selbst an — das entscheidet der Nutzer):
|
||||
|
||||
- **AI-2-R-1 (§5.5-Provenienz-Selbsttest rekursiv machen)** — `schema/compiler.md` §5.5 Pkt. 1/4 (Z. 81/104): Formel auf rekursive Abdeckung umstellen (`grep -rnE '\(raw/' wiki/ --include='*.md' --exclude=log.md`), sodass Area-Concepts erfasst werden. Quelle: **F-01**. Owner: dev.
|
||||
- **AI-2-R-2 (§5.8/Area-ohne-`index.md`-Lücke schließen)** — §5.8 Pkt. 2 Lauf A (Z. 216): Area-Concept-ohne-`index.md`-Fälle (Tiefe 2, `wiki/<a>/concept.md` ohne `wiki/a/index.md`) in den Selbsttest aufnehmen. Quelle: **F-03**. Owner: dev.
|
||||
- **AI-2-R-3 (Formel-4-Filterasymmetrie heilen)** — §5.6 Pkt. 3 Formel 4 (Z. 162–163): `--exclude=log.md` und `grep -v "log.md$"` auf dieselbe Exklusions-Semantik bringen (genau-Basename `log.md` auf beiden Seiten bzw. rekursiv-Basename in beiden). Quelle: **F-04**. Owner: dev.
|
||||
- **AI-2-R-4 (§5.8-Reachability als echte Markdown-Links prüfen + `./`-Konsistenz mit §5.6)** — §5.8 Pkt. 2 Lauf A (Z. 216): `grep -qF` gegen Code-Fence/Blockquote-sichere Link-Detektion; `./`-Variante mit dem §5.6-Form-Check vereinheitlichen (genau eine erlaubte Form). Quelle: **F-05**. Owner: dev.
|
||||
- **AI-2-R-5 (autorisierte Validator-Rev-9 für Punkt 11 Area-Lesart)** — formalisierte Punkt-11-Area-Lesart (relative OKF-Pfad-Identität, file-relativ in Area-Index) in einer autorisierten Revision; de-dupliziert mit dem bestehenden Action-Item `code-review-2-1-item-2` (Rev-9-Vorbereitung). Quelle: **F-02**. Owner: dev.
|
||||
|
||||
Die übrigen F-Items sind **defer** (F-07, F-08, F-09 — bekannte, in `deferred-work.md` verankerte Lücken) bzw. **accept** (F-06, F-10, F-11, F-12 — dokumentierte Design-Entscheidungen bzw. Klarstellungen). Für die accept/defer-Items gilt: sie werden in den **Open questions**-Block übernommen, damit spätere Retros sie nicht erneut als neu flaggen.
|
||||
|
||||
## Acceptance verdict
|
||||
|
||||
- **Kriterien:** declar **deklariert** in `_bmad-output/planning-artifacts/epics.md` (Epic-2-Block + Stories 2.1–2.5, je AC-Zeilen).
|
||||
- **Story-Status:** alle Stories des Epic (2.1–2.5) sind `done`; `detect-epic --epic 2` liefert keine `pending_stories` (sprint-status.yaml) → kein Machine-Zwang zu `rejected`.
|
||||
- **Kriterien-Erfüllung (Beleg):** Die AC-Zeilen je Story sind erfüllt und belegt — Story 2.1/2.2 (OKF-Konformität, v1-Trust, claim-granulare Provenienz) durch die 2026-08-17-Re-Reviews und Rev-8-Autorisationsrunde; Story 2.3 (eine erlaubte Linkform) durch `§5.6` + Formeln 1–3; Story 2.4 (deterministische Bereichszuordnung) durch `§5.7` + Tie-Break + Kollisions-Hold; Story 2.5 (Progressive Discovery) durch `§5.8` + Selbsttest. Verhaltenscheck (Abschnitt oben): **alle re-executierbaren Formeln grün**.
|
||||
- **Offene, getrackte Findings:** F-01–F-05 sind empirisch belegte Blindstellen/Konsistenzgrafien in den Selbsttest-Formeln (insbesondere F-01: §5.5-Formel übersieht Area-Concepts; F-02: Punkt-11-Wortlaut vs. file-relative Area-Linkform). Sie sind **nicht** Blockierend für die Story-ACs (kein Live-Fail, kein Kriterien-Unterschreiten), wohl aber für den AD-17h-„re-executierbar & vollständig"-Anspruch der Instruktion.
|
||||
- **Verdikt:** **accepted-with-open-items** — die deklarierten Abnahmekriterien sind erfüllt und durch re-executierbare Nachweise belegt; benannte Findings (F-01–F-05) bleiben als offene, getrackte Items (Action-Items AI-2-R-1…5) bestehen. Gemäß `acceptance-verdict.md` fällt das maschinelle Verdikt bei leerer `pending_stories`, erfüllten Kriterien und getrackten, nicht-blockierenden Findings selbst auf **accepted-with-open-items** — keine Zurückweisung. Die Findings sind zudem empirisch belegt (F-01: §5.5-Formel übersieht Area-Concepts; F-02: Punkt-11-Wortlaut vs. file-relative Area-Linkform; F-03–F-05: Sandbox-Replikationen) und werden als explizite, getrackte Folge-Items in den Dev-Loop übertragen.
|
||||
|
||||
<!-- ============================ PHASE 5 / OPEN QUESTIONS + FOLLOW-THROUGH ============================ -->
|
||||
|
||||
## Open questions
|
||||
|
||||
1. **F-06 — Formel-4-Re-Baseline-Policy:** Wie definiert Epic 3 einen „Zuwachs-Run" (Datei-Zuwachs vs. Content-Drift ohne Datei-Zuwachs) und welcher Commit wird „der dann aktuelle Run-Kopf" für die Baseline-Extraktion? (kurze Antwort in `schema/compiler.md` §5.6 Pkt. 3 Z. 166 ist vorhanden, aber ohne zitierbare Regel.)
|
||||
2. **F-10 — „kanonischer Name" mechanisieren:** Kann Epic 3 den §5.7-Pkt.-1(a)-Operanden (kanonischer Name des Themas) aus dem `index.md`-Baum ableiten (grep/ripgrep, ID-Normalisierung), ohne ein neues Urteils-Element einzuführen?
|
||||
3. **F-02/Rev-9 — Punkt-11-Lesart:** Welche exakte Formulierung trägt die file-relative Area-Lesart am besten („relative OKF-Pfad-Identität, auch in Area-Index") und bleibt dabei vertrags-/validator-konform?
|
||||
4. **F-11 — Struktur:** Soll `schema/compiler.md` in Epic 3 aufgeteilt oder mit einem Querverweis-Register versehen werden, um die §5.5–§5.8-Fehlschlagschneisen zu senken? (Empfehlung: aufgeteilt oder Register, kein Auto-Fix.)
|
||||
|
||||
## Previous-retro follow-through
|
||||
|
||||
Das vorige Retrospective ist `epic-1-retro-2026-08-15.md` (Epic 1). Aus `sprint-status.yaml` wurden die Epic-1-Action-Items geprüft:
|
||||
|
||||
- **`epic-1-retro-item-1` … `-7`** — alle **done** (geschlossen 2026-08-16, je mit Resolution; an die Validator-Revisionen 3–6 + F-04/F-09/Defer-Sicherung gekoppelt). Belegt über `sprint-status.yaml` (action_items, `status: done`, `closed` + `resolution`) — **kein offener Epic-1-Posten übrig**.
|
||||
- **Von Epic 2 bisherige Action-Items:**
|
||||
- `code-review-2-1-item-1-autorisierte-validator-revision-option` — **done** (Rev-8-Autorisationsrunde ausgeführt und zertifiziert, s. `wiki/log.md` 2026-08-16/17). Beleg: `validator.md` Rev 8 + log-Eintrag.
|
||||
- `code-review-2-1-item-2` (Epic 2, Rev-9-Vorbereitung: Punkt-4-Grammatik `resolved=`-Token, Innen-Ebenen-Punkt-6-Fixture-Zeile) — **offen / nicht erledigt** (kein Beleg für Abschluss). Dieser Posten bleibt im Follow-through aufgeführt, da er in dieser Retro als **AI-2-R-5 (Rev-9)** wiederbelebt bzw. aufgegriffen wird; die beiden anderen Teilschritte (Punkt-4-Grammatik + Innen-Ebenen-Punkt-6-Fixture) sind Teil der **defer**-F-09-Übernahme (unabhängig vom Rev-9-Ziel). Der vorgeschlagene Status ist **in-progress** (laufender Dev-Loop) bzw. bei Nutzer-Autorisierung **done** für den abgeschlossenen Teil.
|
||||
|
||||
Hinweis gemäß `acceptance-verdict.md` L29: ein fehlender Datei-Beleg ist nie als „keine offenen Posten" zu lesen. Da Epic 1 keine `action_items`-Einträge über die Epic-1-Id-Form hinaus trägt (aus der Version vor dem Retro-I-Format) und die Epic-2-Einträge mit Ids existieren, ist die Auswahl über die expliziten Ids oben geprüft (keine Legacy-Einträge ohne Id mitgematcht).
|
||||
|
||||
## Assumptions
|
||||
|
||||
*Nicht zutreffend (interaktive Ausführung):* Für diesen interaktiven Retro-Lauf wurden keine Entscheidungen ohne den Nutzer getroffen — die Auswahl des Epic (Epic 2) erfolgte durch den Aufruf `/bmad-retrospective Epic 2`; die Einschätzung der Story-Kriterien und die resultierenden Action-Items werden dem Nutzer als Vorschläge vorgelegt (Phase 4/5).
|
||||
@@ -0,0 +1,31 @@
|
||||
# Review-Klassifikation Story 2.2 (Step-04-Review, 2026-08-17)
|
||||
|
||||
> Drei Review-Layer (Blind Hunter, Edge Case Hunter, Verification Gap) auf dem Stand des Story-2.2-Diffs (baseline `bb32acd`, tracked + untracked Spec). Klassifikation gemäß step-04-review.md: dedupliziert, Severity-Einstufung durch den Workflow (Reviewer-Severity verworfen), Triage. **Kein** `intent_gap`, **kein** `bad_spec` → kein Loopback; Story-2.2-Problem = `patch` + `defer`.
|
||||
|
||||
## Triage-Ergebnis (dedupliziert, je Kern-Finding)
|
||||
|
||||
| # | Befund (Kern) | Quelle | Severity | Kategorie | Behandlung |
|
||||
|---|---|---|---|---|---|
|
||||
| P1 | §5.5-Widerspruch „kein Frontmatter-Change" vs. tatsächliche `sources`-/`id`-Hinzufügungen | BH-1 | medium | patch | §5.5-Klarstellung (schema/compiler.md) |
|
||||
| P2 | §5.5 `#<id>`-Fragment-Semantik: sources-`id` (s1/s2) existiert nicht im Rohdokument; `<pfad>#<id>`-Form teilweise ohne Gültigkeit | BH-2, BH-6, VG-3 | medium | patch | Inline-Verweis-Form präzisieren (Stellen-Kennung, volle Pfade, kein sources-`id`-Fragment) |
|
||||
| P3 | Body: `§0 Dokumentzweck` vs. englischer PRD-Titel; `#s1`/`#s2`-Fragmente; Pfad-Elision `#A0-6` ohne Pfad | BH-3, VG-3 | medium | patch | llm-wiki-prinzip + wissensarchitektur Body-Fixes |
|
||||
| P4 | `wissensarchitektur`::FR-16-Verweis zitiert `raw/epics/…` **ohne** `sources`-Deklaration → Relokations-Regel §5.5 Pkt. 1b verletzt (widerspricht dem eigenen Diff) | VG-1, VG-2 | high | patch | FR-16-Beleg auf PRD §4.5 allein; epics-Verweis entfernen |
|
||||
| P5 | Kontext-Marker: Selbstreferenz (Concept nennt sich als Ursprung); Direkt- übernahme-aus-raw Fall fehlt; Forward-Referenz-Wortlaut weicht von §5.5 ab | BH-5, VG-4, EC-3 | medium | patch | Marker-Grammatik + Body-Marker anpassen |
|
||||
| P6 | Kein worked example; §5.5-Pkt.-1„zulässig beide / erkennbar"-Unbestimmtheit gegen AD-17h-Grep | BH-3, BH-13 | medium | patch | §5.5: Grep-Formel `\(raw/|\]\(raw/`, verbindliche Default-Form, worked example |
|
||||
| P7 | `wiki/log.md` Eintrag: `#s2`-Fragment + Quell-Deklarations-Wortlaut (wissensarchitektur-Diagramm) an die korrigierten Markers angleichen | (VG-3 Ableitung) | low | patch | log.md-Nachführ-Eintrag minimal reinigen |
|
||||
| D1 | Sources-Closure-Verifikation (jeder inline-referenzierte `raw/`-Pfad ⊆ `sources`) — kein re-runnable Check (D-3-konform) | VG-1/VG-2 | medium | defer | deferred-work.md, Abschnitt „Deferred from: code review of story-2.2 (2026-08-17)" |
|
||||
|
||||
## Rejects (Rauschen, still verworfen)
|
||||
|
||||
- **BH-8** (Status-Inkonsistenz Spec `in-review` vs. sprint-status `in-progress` vs. log `SUCCESS`) — normaler Workflow-Fluss (Review beginnt, Story bleibt bis `done` `in-progress`; log ist Lauf-Protokoll). **reject**.
|
||||
- **BH-14** (index.md-Vereinfachung der Konzept-Beschreibung) — bewusst vereinfachtes Discovery-Niveau; kein Konflikt mit claim-granularer Provenienz der Bodies. **reject**.
|
||||
- **BH-15** (I/O-Matrix unvollständig) — Scope-/Frozen-Entscheidung (nur 2 Szenarien in der Approve-Baseline); kein bad_spec. **reject**.
|
||||
- **VG-5** („A0-7 orphan") — **widerlegt** durch Faktencheck: `A0-7` existiert in `raw/epics/epics-2026-08-14.md` (Zeile 55, Bezeichner `- **A0-7 — Reason/Mutate-Trennung (AD-6):**`). Der Verweis `raw/epics/…md#A0-7` in `knowledge-kompilation-inkrementell.md` ist korrekt. **reject**.
|
||||
|
||||
## Patches an den Implementierungs-Subagenten (Kontext intakt, synchron)
|
||||
|
||||
Die patch-Findings P1–P7 wurden dem Step-3-Implementierungs-Subagenten als vollständiges Paket gesendet (Datei, Defekt, Fix-Anforderung; deutsche Ausgaben; Re-Run der Spec-Verification). Danach: erneute Verifikation aller Checks.
|
||||
|
||||
## Verifikations-Hinweis
|
||||
|
||||
Der Validator (`schema/validator.md`) ist eine reine Text-Instruktion (D-3, kein CLI). „Validator-Lauf: alle 5 wiki/-Dateien SUCCESS" ist die human/manuell-mechanische Ausführung der §3-/§6-Regeln. Dies entspricht der etablierten Konvention (Story 1.4/2.1).
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: 'Review-Input: Prozess-Optimierungs-Bericht Compilation Run Story 2.1 (PDF/RADIUM-Probelauf in D:\mita\wow-2nd-sandbox)'
|
||||
type: review-input
|
||||
created: '2026-08-17'
|
||||
status: incorporated
|
||||
scope: review-context
|
||||
---
|
||||
|
||||
# Review-Input: Sandbox-Dryrun (PDF/RADIUM) zu Story 2.1
|
||||
|
||||
> **Herkunft:** Nutzer-Durchlauf in `D:\mita\wow-2nd-sandbox` (Probelauf des
|
||||
> Compilers `schema/compiler.md` Rev 1.3 gegen die Quelle `raw/MetaModel.pdf`),
|
||||
> dokumentiert in `PROZESS-OPTIMIERUNGS-BERICHT.md` (2026-08-16).
|
||||
> **Zweck:** Zusätzlicher Review-Kontext für Story 2.1 — R-2 wird praktisch
|
||||
> belegt (PDF `sources[].resource` wird endungsneutral verarbeitet), zusätzlich
|
||||
> empirische Befunde zur Ausführungs-/Tooling-Ebene.
|
||||
> **Charakter:** Prozess-Optimierungs-Bericht. Keine Änderung an `raw/`,
|
||||
> `schema/`, `adapters/`, `wiki/spring/` in der Sandbox; Bericht deklariert
|
||||
> bewusste Selbstbegrenzung (D-3, keine Norm-Änderung).
|
||||
|
||||
## 1. Belegte Fakten (empirisch)
|
||||
|
||||
- **Run konform:** 11 neue Root-Concepts aus `raw/MetaModel.pdf`
|
||||
(28 Seiten, 11 Wissenseinheiten, AD-5: fachfremde Quelle betrifft keine
|
||||
bestehenden Concepts → kein Update/keine Kollision). Verlinkung in
|
||||
`wiki/index.md` (11 Link-Zeilen mit `(aus raw/MetaModel.pdf)`), 11
|
||||
`- neu:`-Einträge in `wiki/log.md` (§5-Format, `sources: raw/MetaModel.pdf`).
|
||||
- **Quelle unverändert:** SHA-256 von `raw/MetaModel.pdf` konstant vor/nach
|
||||
Run (`4fe7aaa0…eea5ec`). EC-11 bestätigt: `raw/report/report-2026-08-16.pdf`
|
||||
bleibt unberührt (kein `.md`, kein Verdikt).
|
||||
- **Validator-Run-Ergebnis (Sandbox-Selbstauskunft, Anhang A):** SUCCESS für
|
||||
alle 18 Sandbox-Bundle-Dateien (0 FAIL): 16 Root- (5 reale + 11 radium-) + 2
|
||||
`spring/`-Dateien.
|
||||
Darunter die 5 realen Bundle-Dateien zuzüglich 11 radium- + 2 spring-Dateien
|
||||
(= 16 Root- + 2 spring/ = 18).
|
||||
- **`at`-Konsistenz:** Alle 11 `at`-Stempel der neuen Concepts einheitlich
|
||||
(`2026-08-16T09:23:33Z`), `verified` ungesetzt (v1-Default AD-15), Innen-Ebenen-
|
||||
Key-Subset eingehalten (Punkt 6), kanonische Reihenfolge (§6.6).
|
||||
|
||||
## 2. Korrigierter technischer Befund zum Validator-Tooling (§3 Punkt 11)
|
||||
|
||||
Der Bericht (3.1 #2) wertet `wiki/spring/testing.md` → „Punkt 11 FAIL
|
||||
(Index-Regel)" als inkonsistenten Schema-Fehlalarm. **Korrektur laut
|
||||
`validator.md` §3 Punkt 11:** Ein Concept ist verlinkt, wenn seine **Identität
|
||||
(relativer OKF-Dateipfad ohne `.md`)** in der `index.md` des **nächsten
|
||||
Vorfahren** (Area-`index.md`; für Root-Concepts Bundleroot `wiki/index.md`)
|
||||
als relativer Bundle-Pfad referenziert ist — **mit oder ohne `.md`-Endung**
|
||||
(normative Zelle, Rev 7/8 unterscheiden sich hier nicht).
|
||||
|
||||
Konsequenz: Für `wiki/spring/testing.md` ist die zuständige `index.md`
|
||||
`wiki/spring/index.md`, erwartetes Token `spring/testing`. Ein „nackte"
|
||||
Identitäts-Suche ohne relative Auflösung ist ein **Implementierungs-Defekt des
|
||||
Prüfwerkzeugs** — kein Instruktions-Defekt. Da diese Zeile des Validators eine
|
||||
buchstabenidentische Aussage des Prüfpfads verlangt (keine Dateisystem-Pfad-
|
||||
Auflösung mit Absoluthalten), steht der Befund **nicht** als Findings-Item für
|
||||
`validator.md`; er ist als Tooling-Lernfall (Fixture-Selbsttest, Abschnitt 4
|
||||
des Berichts) zu führen.
|
||||
|
||||
## 3. Bestätigte Instruktions-Aussagen (R-1/R-2-Bezug)
|
||||
|
||||
- **R-2 bestätigt (praktisch belegt):** `compiler.md` §1.2/§1.4 verarbeitet
|
||||
die PDF-Quelle endungsneutral (PDF als Datei unter `raw/`); `sources[].
|
||||
resource: raw/MetaModel.pdf` ist Vertrag-§3.3-konform (Dateipfad unter
|
||||
`raw/`, kein `wiki/`-Pfad, AD-4b); Validator EC-1 prüft nur Existenz.
|
||||
Der Befund 3.1 #1 (PyYAML-Timestamp-Parsing als Tooling-Falle) ist
|
||||
§4.3-konform vermeidbar — der Validator verlangt **Textform**-Prüfung des
|
||||
ISO-8601-Datetime (§4.3 Normalform), nicht Parsing zum `datetime`-Objekt.
|
||||
- **R-1 unverändert (Set-Interface):** `compiler.md` §1.2 definiert die Source-
|
||||
Eingabe als Menge beliebiger `raw/`-Dateien; der Sandbox-Lauf (1 Quelle) ist
|
||||
als Teilmenge des Sets operiert, nicht als Einzelpfad-Interface.
|
||||
|
||||
## 4. Review-Zuordnung der Optimierungs-Maßnahmen (Bericht §4)
|
||||
|
||||
| Maßnahme | Prio | Review-Zuordnung | Konformität |
|
||||
|---|---|---|---|
|
||||
| Fixture-Selbsttest des Validator-Tools vor Bundle-Lauf | P1 | Tooling-Schärfung; Folge-Eintrag `deferred-work.md` (Zuordnung Story 2.1/Epic 3) | D-3-tauglich (rein textueller Check-Block), kein neuer Standalone |
|
||||
| Feste `.compile-run/`-Arbeitskonvention (außerhalb `raw/`) | P1 | Tooling-Konvention; Folge-Eintrag `deferred-work.md` | AD-3-konform (nichts unter `schema/`/`raw/`), AD-17h-relevant |
|
||||
| Einmaliges `at` pro Run (UTC, `Z`-Form) | P1 | Klarstellung `compiler.md` §4.3 als Konvention; kein Vertrags-Bruch (Validator akzeptiert ±HHMM wie Z) | Validator-neutral |
|
||||
| Pre-Run-Reconcile-Vorphase deterministisch bündeln | P2 | Folge-Eintrag `deferred-work.md` (Zuordnung Epic 3, AD-5) | D-3-konform |
|
||||
| Provenienz-Checksumme in `sources` (Vorbereitung Epic 3) | P2 | Eintrag `deferred-work.md` (Zuordnung Story 2.2/Epic 3) — NICHT jetzt implementieren (Schema-Subset §3.3 unverändert) | vertragskonform |
|
||||
| Area-Reife für längere fremde Quellen | P3 | Zuordnung Story 2.4 (deterministische Area-Zuordnung) — bis dahin Root-Ebene normativ korrekt (Rev-1.3-Konvention) | Story-2.4-Kontext |
|
||||
| Deterministik offener Punkte (`.MD`, `today`-Zeitzone) | P3 | Verweist auf bestehende „Offene Punkte" (F-06/F-08, Validator Rev. 6, §1 Punkt 3/§6.4) — aktuell kein Sonderfall im Bundle | keine neue Festlegung nötig |
|
||||
|
||||
## 5. Fazit für den Review
|
||||
|
||||
- Der Probelauf ist ein **Positiv-Beleg** für Story 2.1 (R-2 praktisch
|
||||
bestätigt); keine neuen AC- oder Vertrags-Verstöße erkennbar.
|
||||
- Die gemeldeten Tooling-Falsch-FAILs sind **Prüfwerkzeug-Lernfälle** (kein
|
||||
Instruktions-/Validator-Defekt) — als Folge-Einträge (`deferred-work.md`),
|
||||
nicht als Findings gegen `schema/*`.
|
||||
- Die „Optimierungs-Maßnahmen" sind **Tooling-/Konventions-Ebene** und
|
||||
berühren keine autorisierten Schemata; P1-Punkte sind als dokumentierte
|
||||
Konventionen direkt umsetzbar, P2/P3-Einträge der Story-Zuordnung folgen.
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
---
|
||||
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.
|
||||
+215
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: 'Schema-Validierung für Bundle implementieren (Story 1.4)'
|
||||
type: 'feature'
|
||||
created: '2026-08-15'
|
||||
status: 'done'
|
||||
baseline_commit: 33d21cb0ad390a921c817342b4c21f11f3694516
|
||||
review_loop_iteration: 0
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-1-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## 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.
|
||||
</frozen-after-approval>
|
||||
|
||||
## 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:**
|
||||
- [x] `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.
|
||||
- [x] `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.
|
||||
- [x] `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).
|
||||
- [x] `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).
|
||||
- [x] `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.
|
||||
- [x] `_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:
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
**Strenger Vertrag↔Validator-Abgleich (Retrospective F-10/AI-6, 2026-08-16):** Die dokumentarischen Greps oben sind Existenz-/Mentions-Checks und fangen semantischen Drift nicht (F-01 kam dadurch durch). Als Nachschärfung gilt ab jetzt bei jeder Autorisierung/Re-Derivation des Validators die folgende deterministische Abgleich-Liste (§7 des Vertrags ↔ exakte Validator-Prüfschritt-Zelle): Jeder der 14 Punkte MUSS in `schema/validator.md` als eigene Prüfschritt-Zeile der §3-Tabelle vorhanden sein, und **kein** zusätzlicher §7-Punkt darf existieren. Mechanisch:
|
||||
|
||||
```text
|
||||
Equivalent-Check: die Menge der Punkt-Nummern in der §3-Tabelle = {1..14}
|
||||
(mechanisch: `grep -oE '^\| ([0-9]+) \|' schema/validator.md`
|
||||
→ sort -u → {1,2,…,14}; keine Punkt-Nummer >14, keine Lücke)
|
||||
Konsistenz: `grep -nE 'Punkt [0-9]+' schema/validator.md` — expected:
|
||||
jede Punkt-Nummer in der §3-Tabelle ist ein §7-Punkt des Vertrags
|
||||
Abgleich-Tabelle: §7-Punkt-Nr. ↔ §3-Prüfschritt-Zeile ↔ Fixture-Nr. (§7.1/§7.2/§7.3)
|
||||
(siehe Tabelle unten im Abschnitt „Verifikations-Beleg“)
|
||||
```
|
||||
|
||||
Diese Abgleich-Tabelle ist als „Verifikations-Beleg“ geführt (2026-08-16, Stand Validator Revision 6, Vertrag autorisiert Revision 1) und wird bei jeder künftigen Vertrags-/Validator-Änderung revalidiert.
|
||||
|
||||
**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".
|
||||
|
||||
### Verifikations-Beleg — Vertrag↔Validator↔Fixtures-Abgleich (Stand 2026-08-16)
|
||||
|
||||
Revalidierung bei jeder Vertrags-/Validator-Änderung: konsistente eine-Zuordnung, keine Punkt-15, keine Lücke.
|
||||
|
||||
| Vertrag §7-Punkt | Validator §3-Zeile (Prüfschritt) | Fixture-Negativ (§7.1) | Fixture-Positiv (§7.2) | Anmerkung |
|
||||
|---|---|---|---|---|
|
||||
| 1 (Concept ohne `type`) | Z. „Punkt 1: concept ohne type…“ | Fixture 1 | Fixture 1 | |
|
||||
| 2 (nicht-reservierte `.md` ohne Frontmatter/`type`) | Z. „Punkt 2: …“ | Fixture 2 | Fixtures 2, 2a | 2a: BOM/Leerzeile (AI-5) |
|
||||
| 3 (`sources`→`wiki/`-Pfad) | Z. „Punkt 3: …“ | Fixture 3 | Fixture 3 | |
|
||||
| 4 (`source` außerhalb `raw/`, Grammatik) | Z. „Punkt 4: …“ | Fixture 4 | Fixture 4 | |
|
||||
| 5 (`status`-Wert) | Z. „Punkt 5: …“ | Fixture 5 | Fixture 5 | |
|
||||
| 6 (unautorisiertes Feld / Subset) | Z. „Punkt 6: …“ | Fixture 6 | Fixture 6 | |
|
||||
| 7 (leere `by`) | Z. „Punkt 7: …“ | Fixture 7 | Fixture 7 | |
|
||||
| 8 (Bundleroot-Deklaration) | Z. „Punkt 8: …“ | Fixtures 8, 8a | Fixtures 8, 8b | 8a/8b: V-1/BOM |
|
||||
| 9 (`okf_version`/`type:bundle` außerhalb) | Z. „Punkt 9: …“ | Fixture 9 | Fixture 9 | |
|
||||
| 10 (Frontmatter in Area/`log.md`) | Z. „Punkt 10: …“ | Fixtures 10, 10a | Fixture 10 | 10a: V-2 |
|
||||
| 11 (Index-Regel) | Z. „Punkt 11: …“ | Fixture 11 | Fixture 11 | Struktur-Klasse separate V/w/o §7 |
|
||||
| 12 (`sources`/`verified`/`generated`-Form) | Z. „Punkt 12: …“ | Fixtures 12, 12a | Fixtures 12, 12a | |
|
||||
| 13 (doppelter Key) | Z. „Punkt 13: …“ | Fixture 13 | Fixture 13 | |
|
||||
| 14 (Wert-Formate) | Z. „Punkt 14: …“ | Fixtures 14, 14a, 14b, 14c | Fixtures 14, 14b, 14c, 14d | 14c/BOM-14c AI-1 |
|
||||
|
||||
**§6-/V-Fixtures (fachliche Prüfklassen, keine §7-Punkte):** §7.3 deckt EC-1 (Existenz), EC-3 (Kalender), stale_after-WARN (§6.4), EC-11 (non-md), V-1 (fehlende Bundleroot) und V-2 (`log.md`-Position) ab — siehe `schema/validator.md` §7.3 (Revision 6). Diese Zeilen belegen, dass die fachlichen Prüfungen nicht aus dem §7-Katalog fallen (F-02 belegt).
|
||||
|
||||
**Verdikt-Grammatik (F-10-Härtung):** Der Abgleich ist maschinenlesbar (Grep-Rezept oben); eine `Punkt 15`-Zeile oder ein fehlender Punkt 1–14 schlägt den Re-Check fehl (kein LLM-Urteil). Wird bei jeder Autorisierungsschleife als Pflicht-Schritt geführt (KEEP bei Re-Derivation).
|
||||
|
||||
- **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; **der strenge Vertrag↔Validator↔Fixtures-Abgleich (F-10/AI-6, Verifikations-Beleg-Tabelle) als Pflicht-Re-Check bei jeder Autorisierung**.
|
||||
|
||||
## 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`](../../schema/validator.md#L8)
|
||||
|
||||
**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`](../../schema/validator.md#L48)
|
||||
|
||||
- Erweiterungs-/Abschluss-Regel plus Punkt-6/9-Exemption (kein Punkt-6-vor-9-Feuer)
|
||||
[`validator.md:71`](../../schema/validator.md#L71)
|
||||
|
||||
- Bundleroot-/Reserviert-Voraussetzungen — ausdrücklich keine neue ¶7-Klasse
|
||||
[`validator.md:77`](../../schema/validator.md#L77)
|
||||
|
||||
**Deterministische Normalform & Toleranz**
|
||||
|
||||
- Listen-vs.-Absenz, fehlende optionale Felder, feste Key-Reihenfolge (F2)
|
||||
[`validator.md:85`](../../schema/validator.md#L85)
|
||||
|
||||
- ISO-8601-Normalform inkl. `±HH:MM`-Akzeptanz (keine unautorisierte Verschärfung); Kalender-Validität
|
||||
[`validator.md:100`](../../schema/validator.md#L100)
|
||||
|
||||
- Deterministische Rangfolge & Abbruch-Regel (erste verletzte Bedingung), EC-1-Aggregation
|
||||
[`validator.md:109`](../../schema/validator.md#L109)
|
||||
|
||||
- `log.md`-Feingranularität (leeres Log gültig), Verdikt-Format inkl. WARN als Berichtskanal
|
||||
[`validator.md:122`](../../schema/validator.md#L122)
|
||||
|
||||
**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`](../../schema/validator.md#L149)
|
||||
|
||||
**Referenz-Fixtures & Selbstbegrenzung**
|
||||
|
||||
- Negativ-/Positiv-Fixtures incl. Isolations-Notiz; per AD-17h reproduzierbar prüfbar
|
||||
[`validator.md:188`](../../schema/validator.md#L188)
|
||||
|
||||
- Normreferenzen inkl. F15/Story-2.3-Defer, Revisionslog
|
||||
[`validator.md:245`](../../schema/validator.md#L245)
|
||||
|
||||
**Protokollierung & Status**
|
||||
|
||||
- Zertifizierungs-Eintrag im Bundle-Log (Vertrag §5-konform; PASS gegen Fixtures)
|
||||
[`log.md:3`](../../wiki/log.md#L3)
|
||||
|
||||
- Story 1.4 auf `review` gesetzt (separierte `/review`-Pfad-Transition)
|
||||
[`sprint-status.yaml:42`](../../_bmad-output/implementation-artifacts/sprint-status.yaml#L42)
|
||||
+279
@@ -0,0 +1,279 @@
|
||||
---
|
||||
title: 'Concepts aus Source Material erzeugen (OKF-Konform) (Story 2.1)'
|
||||
type: 'feature'
|
||||
created: '2026-08-16'
|
||||
status: 'done'
|
||||
review_loop_iteration: 2
|
||||
baseline_commit: a67ba659108006a54eb54b84592d1dba046af96e
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-2-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Der Workspace kann Sources unter `raw/` (Story 1.2) halten und deren OKF-Konformität validieren (Story 1.4), aber es existiert noch keine deterministische, agentische Anweisung, die aus diesen Sources **neue, eigenständige OKF-0.2-Concepts** erzeugt (FR-5, FR-9) — der erste Compile-Run steht aus.
|
||||
|
||||
**Approach:** Eine agent-unabhängige Compiler-Instruktion `schema/compiler.md` schaffen, die die Concept-Erzeugung als deterministischen, textuell nachvollziehbaren Agenten-Prozess beschreibt (Interpret → Reconcile → Synthesize → Mutation, AD-5/AD-7), und sie in einem **ersten Demonstrationslauf** gegen die drei vorhandenen `raw/`-Sources anwenden — Ergebnis: konkrete, OKF-validierbare Root-Concepts + Verlinkung in `wiki/index.md`.
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- `schema/compiler.md` ist der **einzige Ort** der Erzeugungs-Instruktion; er ist rein textuell (kein ausführbarer Code, D-3) und agent-unabhängig (AD-10), liegt außerhalb des Bundles neben Vertrag und Validator (AD-1).
|
||||
- Concepts MÜSSEN OKF-0.2-konform sein: Markdown mit YAML-Frontmatter, `type` als einziges Pflichtfeld und nicht leer (§3.1, Stolperstein Punkt 1); Feldsubset strikt nach §3 (`type`, `sources`, `generated`, `verified`, `status`, `stale_after`), keine unautorisierten Keys (Stolperstein Punkt 6). `okf_version`/`type: bundle` NIE in Concepts (Punkt 9).
|
||||
- Trust-Metadaten v1 (A0-20, AD-15): maschinell erzeugt → `generated: { by: wow-compiler/0.1.0, at: <ISO-8601-Datetime> }`, `verified` ungesetzt. `at` ist VOLLES ISO-8601-Datetime (`YYYY-MM-DDTHH:MM:SS` mit `Z`/`±HHMM`/`±HH:MM`), nie reines Datum (Validator Revision ≥3, Punkt 14).
|
||||
- `sources` zeigt ausschließlich auf `/`-getrennte, relative Workspace-Pfade unter `raw/` (§3.3, AD-4b); jede referenzierte `raw/`-Datei MUSS zum Validierungszeitpunkt als Datei existieren (EC-1) — nie auf `wiki/`-Pfade (Punkt 3), kein `..`/URL/absolut/Backslash (Punkt 4).
|
||||
- Concepts sind eigenständige Wissenseinheiten (FR-5): nicht 1:1 pro Abschnitt, nicht bloße Kopie/Zusammenfassung des Quelldokuments (FR-2); mehrere Source-Abschnitte können in verschiedene Concepts fließen. V1-Instruktion erzeugt Concepts **auf Root-Ebene** unter `wiki/` (Story 2.4 regelt Area-Zuordnung später); neue Concepts MÜSSEN in `wiki/index.md` verlinkt werden (Punkt 11 / Index-Regel §6).
|
||||
- Der Demonstrationslauf mutiert ausschließlich `wiki/` (Concepts + `index.md` + zulässiger `log.md`-Eintrag); `raw/` bleibt unangetastet (AD-3); `schema/wiki-compiler.md` und `schema/validator.md` bleiben unverändert (autorisiert).
|
||||
- `log.md`-Eintrag (optional, Vertrag §5-konform): datumsgruppiert, neueste zuerst; dokumentiert die angelegten Concepts inkl. Quell-Pfad.
|
||||
- Instruktion und Konzepte in Deutsch.
|
||||
|
||||
**Ask First:**
|
||||
- Eine bewusste Abweichung vom Feldsubset oder eine neue Invaliditätsart (Verschärfung des §7-Katalogs) — alles, was den autorisierten Vertrag ändern würde, ist explizit menschlich zu genehmigen.
|
||||
- Die Einführung eines Standalone-Programms (Python/TS/etc.) als Compiler — D-3 widerspricht; nur mit menschlicher Zustimmung (Rückkehrpunkt dokumentiert).
|
||||
- Die Anlage eines `wiki/<area>/`-Verzeichnisses in dieser Story (Area-Zuordnung ist Story 2.4) — nicht ohne menschliche Genehmigung.
|
||||
|
||||
**Never:**
|
||||
- Kein eigener OKF-Dialekt, keine Änderung an `schema/wiki-compiler.md`/`schema/validator.md` (autorisiert, Story 1.3/1.4), keine Änderung an `raw/` (immutable, AD-3).
|
||||
- Kein Standalone-/Executable-Compiler (D-3); keine LLM-Runtime-Implementierung im Bundle; kein MCP.
|
||||
- Keine claim-granulare Inline-Provenienz-Ausarbeitung (Story 2.2), keine deterministische Area-Zuordnung/Hierarchie (Story 2.4), keine vollständige Discovery-Logik über `index.md`/Progressive Discovery (Story 2.5) — diese Stories bleiben unangetastet, dürfen aber nicht behindert werden.
|
||||
- Keine Löschung/Umbenennung bestehender Concepts oder `log.md`-Einträge; keine stillschweigende Verlinkung außerhalb `wiki/index.md`.
|
||||
- Kein LLM-Urteil in der Instruktion als alleinige Entscheidungsbasis: Wo Relevanz/Klassifikation nötig ist, wird sie textual-deterministisch begründet (AD-13).
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| HAPPY_PATH | 3 neue Sources unter `raw/` (prd, epics, architecture-spine), leeres `wiki/` (nur `index.md`, `log.md`) | Compiler erzeugt 3 dem Source-Inhalt entsprechende, eigenständige Root-Concepts (`wiki/<slug>.md`) mit `type`, `sources`→existing `raw/`-Pfade, `generated {by, at}` ohne `verified`; verlinkt alle 3 in `wiki/index.md`; Validator-Lauf ergibt SUCCESS | N/A |
|
||||
| CONCEPT_OHNE_TYPE | Compiler legt Concept ohne/leeres `type` an | Concept ist strukturell invalide (Punkt 1) | Instruktion verlangt zwingend `type`; Run bricht mit textueller Fehlerursache ab, `wiki/`-Änderungen bis dahin rückmelden |
|
||||
| FEHLENDE_RAW | `sources`-`resource` verweist auf nicht existente `raw/`-Datei | Fachlich invalide (EC-1) → Run-FAIL | Instruktion: nur real existierende `raw/`-Dateien als `resource`; Verweis auf strukturierte Prüfung |
|
||||
| LEERE_QUELLE / KEINE_WISSENSEINHEITEN | Source enthält keine klar abgegrenzten Wissenseinheiten (z.B. nur README/Artefakt wie `raw/README.md`) | Wird NICHT zu einem Concept verdichtet; ggf. als Hinweis in `log.md` | Artefakt-Dateien (`source.md`, `README.md`) sind keine Evidenz (raw/README.md) → ausgeschlossen |
|
||||
| VERALTETE_SOURCE | `source.md` verweist auf Commit, der nicht mehr existiert | Provenienz-Hinweis bleibt im Sidecar; `raw/`-Datei selbst ist Evidenz | Fehlende Commit-Auflösbarkeit blockiert die Concept-Erzeugung nicht (Sidecar ist Artefakt, nicht Input) |
|
||||
| KEIN_CONTENT | Concept würde nur Source-Copy sein | Kein Concept anlegen; Wissen ist nicht neu → nichts erzeugen | FR-2-konform: Kopieren/Zusammenfassen ist keine Wissensintegration |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/compiler.md` — **Zieldatei (neu)**: deterministische Compiler-Instruktion zur Concept-Erzeugung; Kern des Reviews.
|
||||
- `schema/wiki-compiler.md` — **Normative Grundlage (read-only, Story 1.3)**: §1 Geltungsbereich, §2 Bundleroot, §3.1–3.7 Feldsubset & Formate (inkl. §3.3 `sources`/`resource`, §3.4 `generated`, §3.5 `verified`, §3.6 `status`, §3.7 `stale_after`), §5 `log.md`, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste, §8 Normreferenzen.
|
||||
- `schema/validator.md` — **Pflicht-Referenz (read-only, Story 1.4)**: §3.2 Voraussetzungsprüfungen V-1/V-2; §4.1 kanonische Key-Reihenfolge; §4.3 ISO-8601-Normalform (`at` voll, keine reine Datumsangabe); §6 fachliche Prüfungen (EC-1 Existenz); §6.2 Punkt-4-vor-3-Priorität; Punkt-11-Index-Check (Root-Concepts → Bundleroot `wiki/index.md`).
|
||||
- `wiki/index.md` — **Zieldatei (mutiert im Demonstrationslauf)**: Bundleroot (Frontmatter exklusiv `type: bundle`/`okf_version: "0.2"`); nimmt die Root-Concept-Links auf (Punkt 11); kein eigenes Frontmatter-Feld anfassen.
|
||||
- `wiki/log.md` — **Zieldatei (append-only)**: zulässiger Protokolleintrag (Vertrag §5) über angelegte Concepts; kein Frontmatter.
|
||||
- `raw/prd/prd-wow20-2026-08-14.md`, `raw/epics/epics-2026-08-14.md`, `raw/architecture-spine/architecture-spine-2026-08-14.md` — **Evidenz (read-only, Story 1.2)**: Demonstrations-Sources; `resource`-Ziele der neuen Concepts.
|
||||
- `raw/README.md`, `raw/*/source.md` — Artefakt-/Grenzdateien (keine Evidenz); nicht als Concepts konsumierbar.
|
||||
- `adapters/README.md`, `adapters/claude/README.md` — Adapter-Kontext (read-only, AD-10); Story 5.3 Zuständigkeit, kein Ort für Erzeugungslogik.
|
||||
- `_bmad-output/planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md` — AD-5 (inkrementell, Interpret→Reconcile→Synthesize→Update), AD-7-Reihe (Identität/Verlinkung/Areas: Story 2.3/2.4), AD-17 (Lease/branch, nur committete Inputs), D-3 (kein Standalone-Compiler).
|
||||
- `_bmad-output/implementation-artifacts/epic-2-context.md` — primärer Planungskontext (read-only).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/compiler.md` — Compiler-Instruktion anlegen: Zweck & Aufruf (Agent führt Schritte deterministisch aus), Eingabe (committete `raw/`-Evidenz, AD-17) und Ausgabe (OKF-validierbare Concepts), der logische Fluss Interpret→Reconcile→Synthesize→Mutation (AD-5), die Erzeugungs-/Auswahlregeln (Wissenseinheiten statt 1:1-Abschnitte, FR-5; keine Kopie, FR-2; artefakt-Evidenz-Ausschluss), die Pflicht-Frontmatter-Vorgabe für neue Concepts (`type` gesetzt; §3-Subset; `generated { by: wow-compiler/<version>, at: volles ISO-8601 }` ohne `verified`, A0-20; canonische Key-Reihenfolge §4.1; `sources`→existierende `raw/`-Pfade, EC-1), die Verlinkungs-Pflicht (neue Root-Concepts in `wiki/index.md` verlinken, Punkt 11/§6), Dokumentationspflicht (`log.md`, Vertrag §5) und die Selbstbegrenzung (keine Area-Anlage [Story 2.4], keine claim-granulare Provenienz-Ausarbeitung [Story 2.2], kein Standalone-Code, keine OKF-Erweiterung [D-3, AD-1a]) — FR-5, FR-9, NFR-2/3/4.
|
||||
- [x] `schema/compiler.md` — Determinismus-/Selbsttest-Norm: jede Erzeugungsentscheidung textual-deterministisch begründbar (AD-13); eine Nachprüf-Sektion, die ein erzeugtes Concept gegen den Validator abprüfbar macht (vollständige §3-Subset-Konformität, `at`-Normalform, `sources`-Existenz) — AD-17h-konform, ohne LLM-Doppelurteil (der Validator bleibt die mechanische Prüfung).
|
||||
- [x] `schema/compiler.md` — Positiv-/Negativ-Beispiele (Referenztabellen): je Regel ein Beispiel-Concept (ideal-konform vs. verletzte Regel) — AD-17h/Verifikations-Kultur aus Story 1.4 (Verifikations-Beleg).
|
||||
- [x] Demonstrationslauf (Agent führt Instruktion aus): 3 eigenständige Root-Concepts aus den 3 `raw/`-Evidenzdateien erzeugen (je `wiki/<slug>.md`: `type`, `sources` mit existierenden `raw/`-Pfaden, `generated {by, at}` ohne `verified`, inhaltlich eigenständig kuratiert), alle in `wiki/index.md` verlinken, `wiki/log.md`-Eintrag ergänzen.
|
||||
- [x] Validator-Lauf gegen das mutierte Bundle: erzeugte Concepts + `index.md` + `log.md` MÜSSEN SUCCESS liefern (Punkt 11 inklusive: Root-Concept links in Bundleroot); Ergebnis im Spezifikations-Verification dokumentieren.
|
||||
- [x] `_bmad-output/implementation-artifacts/sprint-status.yaml` — Story 2.1 von `backlog` auf `in-progress` setzen (nach Start der Implementierung).
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given eine neue Source mit mehreren Abschnitten, when ein Compilation Run sie verarbeitet, then erzeugt der Compiler eigenständige Concepts gemäß den erkannten Wissenseinheiten — nicht 1:1 pro Abschnitt, nicht an die Source-Struktur gebunden (FR-5).
|
||||
- Given die Concept-Erzeugung, when ein Concept geschrieben wird, then ist es OKF-0.2-konform: Markdown mit YAML-Frontmatter, `type` als verpflichtendes, nicht leeres Feld; vollständiges §3-Subset ohne unautorisierte Keys (AD-1a, FR-9).
|
||||
- Given ein erzeugtes Concept, when dessen V1-Trust-Metadaten gesetzt werden, then sind sie `generated: { by, at }` (volles ISO-8601) ohne `verified` (A0-20, AD-15).
|
||||
- Given der Demonstrationslauf, when der Validator danach ausgeführt wird, then ist das Bundle mit den neuen Root-Concepts + `index.md`-Verlinkung + `log.md`-Eintrag vollständig SUCCESS (insbesondere Punkt 1, 6, 11, 12, 14).
|
||||
- Given `sources`-Referenzen, when sie dokumentiert werden, then lösen sie ausschließlich auf real existierende `raw/`-Dateien auf — nie auf `wiki/`-Pfade (AD-4b, EC-1).
|
||||
- Given ein erzeugtes Concept, when es inhaltlich eine bloße Kopie/Zusammenfassung der Quelle wäre, then erzeugt der Compiler es nicht (FR-2: Kopieren ist keine Wissensintegration).
|
||||
- Given ein neues Concept auf Root-Ebene, when es angelegt wird, then wird es in `wiki/index.md` verlinkt (Punkt 11/§6), ohne Area-Verzeichnis anzulegen (Story 2.4).
|
||||
- Given die Instruktion, when sie ausgeführt wird, then ist sie eine eigenständige, deterministische, agent-unabhängige Anweisung (D-3, AD-17h) — kein Standalone-Programm.
|
||||
|
||||
### Review Findings (bmad-code-review, 2026-08-16)
|
||||
|
||||
**patch:**
|
||||
|
||||
- [x] [Review][Patch] `schema/compiler.md` §1-Überschrift ist Englisch („Input (what the compiler consumes)") — Verstoß gegen eigene Always-Regel „Instruktion … in Deutsch"; fix: `## 1. Input (was der Compiler konsumiert)` [schema/compiler.md:23] — **erledigt, Rev 1.3**
|
||||
- [x] [Review][Patch] `schema/compiler.md` enthält „Revision 6"-Referenz auf die Prüfgrundlage, während der Commit `validator.md` Rev 7 liefert — Selbstwiderspruch des Instruktions-Selbstbilds; fix: Revisionszahl angleichen (bzw. bei Rev-7-Rückbau konsistent „Revision 6" lassen) [schema/compiler.md:5, schema/compiler.md:127] — **erledigt, auf Revision 7 angeglichen, Rev 1.3**
|
||||
- [x] [Review][Patch] `schema/compiler.md` §6.6-Referenztabelle enthält eine irreführende Zeile: canonical-Key-Reihenfolge wird als „✗"-Abweichung gelistet, aber als „kein FAIL, aber nicht erzeugt" beschrieben und das Label „§6.4" verweist auf eine reine Pfad-Regel (Punkt 4); fix: Zeile aus der ✗-Tabelle herausnehmen (kein Validator-FAIL) bzw. Label auf §4.4 korrigieren [schema/compiler.md:102] — **erledigt: Zeile auf reine ✓-Vorgabe, Label auf §4.2, Rev 1.3**
|
||||
- [x] [Review][Patch] `schema/compiler.md` §1.2 vs. §1.4 widersprechen sich: „jede Datei unter `raw/` ist Evidenz" (extensiv) vs. „Artefakt-/Grenzdateien (`raw/README.md`, `raw/**/source.md`) sind KEIN Input" (restriktiv) — neue normative Regel, die so weder im Vertrag noch im Spine noch im Validator steht; fix: in §1.4 die nicht-mechanisch prüfbare Sonderregel als dokumentarische Konvention (nicht als Input-Verdikt) kennzeichnen; alternativ im Change Log als Klarstellung nachführen — **erledigt: §1.2 präzisiert, §1.4 als dokumentarische Konvention gekennzeichnet, Rev 1.3**
|
||||
- [x] [Review][Patch] `wiki/log.md`-Einträge weichen vom Vertrags-§5-Beispielformat ab (freie Prosa statt „`- neu:` … angelegt (sources: …)"); keine Maschine prüft das, aber der dokumentierte Doku-Standard wird nicht eingehalten; fix: Einträge an das §5-Beispielformat angleichen [wiki/log.md] — **erledigt: drei Demonstrationslauf-Einträge auf §5-Format umgestellt**
|
||||
|
||||
**defer:**
|
||||
|
||||
- [x] [Review][Defer] Contract-Verletzung: `schema/validator.md` im Commit mutiert (Rev-7-Notiz §7.3), obwohl Always/Never + AD-3 es als unverändert autorisiert frieren [schema/validator.md:262] — **aufgelöst via Option A (2026-08-16):** `validator.md` bleibt mit Rev-7-Hinweis erhalten (inhaltlich korrekt, kein Rückbau); Heilung über die nächste **autorisierte Validator-Revision** (F-14-Fixture + Innen-Ebenen-Klarstellung dort formal tragen — vgl. `deferred-work.md`); Story 2.1 bleibt bis dahin `in-progress`, Review-Wiedervorlage vor `done`. (Grund: Frieren-Prinzip wahren, ohne die nützliche Klarstellung zu verwerfen.)
|
||||
- [x] [Review][Defer] Content-Truth-Verifikation: kein Check verifiziert den Inhalt eines Concepts gegen seine deklarierten `raw/`-Quellen (Verification-Gap) — deferred, Story 2.2 [wiki/*.md]
|
||||
- [x] [Review][Defer] Determinismus-Selbsttest-Dokumentation: §6.6-Interpretations-Hinweis behauptet eine starte „genau diese Form", obwohl `generated.at` pro Run variiert (AD-15) — deferred, Story 2.3 [schema/compiler.md:106]
|
||||
- [x] [Review][Defer] R-1 (Compiler-Input-Interface): Compiler definiert seine Source-Eingabe als **Menge beliebiger `raw/`-Dateien (Set-Interface)** — Verdikt **Bestanden**. Der übergebene dryrun-Fall „einzelner Pfad" existiert nicht mehr. Empfehlung gemäß Review-Vorgabe ergänzend: den Mechanismus der Source-Auswahl (welche `raw/`-Dateien wann verarbeitet werden) als Konventions-/Erkennungsproblem für Epic 3/AD-5-Home-Story in `deferred-work.md` festhalten — Firm-Zwang, die „Run-ohne-Pfad"-Lücke der Nutzererwartung bleibt offen (Story 3.1/3.2) — deferred, Epic 3
|
||||
- [x] [Review][Defer] R-2 (Nicht-Markdown-Quellen): Compiler-Instruktion liest Sources **endungsneutral als Datei** (§1.2/§1.4, Verdikt **Bestanden**); die Konventions-/Asset-Zuordnungsfrage für PDF bleibt als dokumentierte Konvention offen — deferred, Epic 2/3 [raw/README.md]
|
||||
|
||||
### Re-Review Verifikationsvermerk (bmad-code-review, 2026-08-16)
|
||||
|
||||
Konforme Wiedervorlage nach dem Erst-Review — alle 5 Patch-Findings verifiziert, kein neuer Bruch:
|
||||
|
||||
- ✅ P-1..P-5 (compiler.md Rev 1.3, log.md §5-Format, spec-status, deferred-work, sprint-status) sauber umgesetzt und im Working Tree verifiziert.
|
||||
- ✅ **AC-Abgleich** gegen `epics.md` Story 2.1: unverändert gültig (type-Pflicht, §3-Subset, v1-Trust `generated {by,at}` ohne `verified`, Wissenseinheiten ≠ 1:1, Index-Pflicht, kein Area, D-3-Textinstruktion) — kein neuer Verstoß durch die Patches.
|
||||
- ✅ **Validator-Run gegen das Bundle** (gemäß `schema/validator.md`): **SUCCESS für alle 5 Bundle-Dateien** (`index.md`, `log.md`, 3 Concepts) — Points 1–14 ✔, V-1/V-2 ✔, EC-1/EC-3/EC-11 ✔, Punkt 11 (alle 3 Identitäten verlinkt) ✔. Keine Abweichung.
|
||||
- ✅ **AD/Provenienz:** AD-3 (`raw/` unangetastet, leerer Diff), AD-5 (nur neue Root-Concepts), AD-10 (`adapters/` unverändert, keine abweichende Knowledge-Semantik), D-3 (rein textuell, kein Executable-Block), AD-4b (alle `sources[].resource` → existierende `raw/`-Dateien, nie `wiki/`), v1-Default (`generated` gesetzt, `verified` ungesetzt).
|
||||
- ✅ **R-1** (Menge von Source-Pfaden, Set-Interface — compiler.md §1.2 definiert die gesamte evidierenfähige `raw/`-Menge; Einzelpfad-Interface existiert nicht): **Bestanden**, kein Finding. Erkennungs-Mechanismus bewusst deferriert (AD-5-Home-Story, Epic 3, Story 3.1/3.2).
|
||||
- ✅ **R-2** (Nicht-Markdown-Quellen): Instruktion liest Sources endungsneutral als Datei (Vertrag §3.3: nur Dateipfad unter `raw/`; Validator EC-1: nur Existenz); PDF zulässig; §1.4 dokumentarische Konvention (§1.2/§1.4-Widerspruch via Rev 1.3 Patch #4 sauber aufgelöst, kein neuer Bruch): **Bestanden**.
|
||||
- ✅ **Option A intakt (Re-Re-Review, 2026-08-17):** `validator.md` Rev-7-Notiz unverändert erhalten (kein Rückbau); `done`-Fähigkeit war korrekt an die nächste autorisierte Validator-Revision gekoppelt. **Diese Revision ist jetzt ausgeführt:** **Revision 8 (2026-08-16, Autorisations-Runde)** trägt formal die F-14-Negativ-Fixture 4a (§7.1, Punkt 4: `resource` außerhalb `raw/`), die Innen-Ebenen-Key-Subset-Klarstellung (Punkt 6 → §7.3-Isolations-Notiz) und die Header-Anhebung „Revision 6" → „Revision 8" (OBS-1). Zertifizierung selbstgeprüft PASS: Fixture 4a isoliert → FAIL Punkt 4; Innen-Ebenen-Sample → FAIL Punkt 6 (Key=role); reales Bundle → SUCCESS. Vertrag `schema/wiki-compiler.md` und `schema/compiler.md` unverändert.
|
||||
|
||||
**Verdikt (Re-Re-Review, 2026-08-17):** Die offene Option-A-Voraussetzung ist **erfüllt** — die autorisierte Validator-Revision 8 ist ausgeführt und zertifiziert. Story 2.1 ist damit **`review`-fähig und `done`-fähig**; keinerlei AC-/Vertrags-Blocker in den Story-Artefakten, keine neuen Findings aus den Nachzieh-Patches. Verbleibende Schwelle bis `done` ist ausschließlich die **menschliche Review-Freigabe** (Human-Review, Status `review` → `done`), nicht mehr eine technische Voraussetzung.
|
||||
|
||||
### Review Findings (bmad-code-review, 2026-08-17 — unabhängiger Re-Run auf dem Stand nach Validator-Rev-8)
|
||||
|
||||
**Kernbefund:** Alle 8 Acceptance Criteria **PASS**; die tragenden Story-2.1-Artefakte (compiler.md, 3 Concepts, index/log, validator Rev 8) sind validator-clean (`raw/` unangetastet, keine Area-Verzeichnisse, kein Executable-Code, keine unautorisierten Keys in keiner Ebene, EC-1/Punkt 11 erfüllt). Kein `high`. Die Findings sind Doku-/Referenz-Konsistenz, zwei Instruction-Vollständigkeits-Lücken und ein `medium`-Governance-Item. Unabhängig verifiziert, nicht aus dem Vordingsvermerk übernommen.
|
||||
|
||||
**patch:**
|
||||
|
||||
- [x] [Review][Patch] `schema/compiler.md` §0/§8 nennt die Prüfgrundlage `validator.md` „Revision 7", aber der Validator ist jetzt **Revision 8** — die von OBS-1 geschlossene Referenzkette ist damit nur halbschließend (3 Layer: Blind + Acceptance + Verification-Gap) [schema/compiler.md:5, schema/compiler.md:127]
|
||||
- [x] [Review][Patch] `wiki/log.md` (2026-08-16): die `schema/compiler.md`-Rev-1.3-Zeile hat ihren `-`-Bullet verloren (nur führendes Leerzeichen) und rendert als Fortsetzung des Rev-8-Eintrags — zwei Ereignisse in einem Listeneintrag, bricht die §5-Flach-Bullet-Konvention, die dieser Diff selbst in Patch #5 durchgesetzt hat [wiki/log.md:8]
|
||||
- [x] [Review][Patch] `schema/compiler.md` §6.6: Referenz-Labels in 4 Zeilen falsch („§4.4 canonical Key-Reihenfolge", „§4.4 keine Duplikat-Keys", „§4.4 sources-Eintrag-Key-Subset", „§4.4 kein okf_version") — aber §4.4 dieser Datei ist die `status`/`stale_after`-Regel; canonical-order ist §4.5, sources-Key-Subset ist §4.2. Die Rev-1.2-Logzeile dokumentiert, das Label sei „von §4.5 auf §4.4 korrigiert" — d. h. die vorgegebene Korrektur bewegte es an die falsche Stelle [schema/compiler.md:99-102]
|
||||
- [x] [Review][Patch] `wiki/index.md`: das Baum-Diagramm (code-block) ist veraltet — es zeigt das Bundle weiterhin nur als `<area>/…` ohne Root-Concepts, während `## Concepts` direkt darunter 3 neue Root-Dateien auflistet; die Struktur-Skizze widerspricht nun dem Dateisatz, den sie dokumentiert [wiki/index.md:12-20]
|
||||
- [x] [Review][Patch] `deferred-work.md`: „Content-Truth-Verifikation einführen" und „Determinismus-Selbsttest-Dokumentation schärfen" erscheinen je **zweimal** (Folge-Aufgaben-Block + Code-Review-Block) mit nahezu identischem Text, aber unterschiedlichem `source_spec`-Label und (für Determinismus) unterschiedlichem Home — Ownership mehrdeutig, lädt zu Doppel-Erledigung ein [deferred-work.md]
|
||||
- [x] [Review][Patch] `deferred-work.md` (Sandbox-Dryrun-P1): „jede Negativ-Fixture (`validator.md` §7.1, **n=17**)" — die §7.1-Tabelle hat nach Revision 8 **21** Zeilen (nach Rev 7: 20); Zählung in einem frisch geschriebenen Eintrag falsch [deferred-work.md]
|
||||
- [x] [Review][Patch] `review-input-dryrun-2-1-pdf-radium.md` §1: interne Inkonsistenz der Datei-Auflösung — „13 Root- + 5 spring/" vs. „die 5 realen … zuzüglich 11 radium- + 2 spring-" (impliziert 16 Root- und 5 vs. 2 spring) [review-input-dryrun-2-1-pdf-radium.md]
|
||||
- [x] [Review][Patch] `validator-revision-8-autorisationsrunde-…md`: Frontmatter `status: 'draft'` **und** alle 4 Definition-of-Done-Boxen `- [ ]`, obwohl die Runde ausgeführt, zertifiziert und downstream `done` ist (Action-Item done, log.md-Zertifizierung, deferred-work „umgesetzt") — die Legitimität, Rev 8 als „autorisiert" zu führen, stützt sich auf ein nicht finalisiertes Dokument; Status finalisieren + DoD abhaken (3 Layer: Blind + Acceptance + Verification-Gap) [validator-revision-8-autorisationsrunde-f14-innen-ebenen.md:5,76-79]
|
||||
- [x] [Review][Patch] Spec: doppelte `## Spec Change Log`-Sektion — die obere enthält weiterhin nur „(leer bis zum ersten Review-Loopback)", die untere die tatsächlichen Einträge; das Re-Re-Review-Verdikt (der bedeutendste Zustandswechsel nach Log-Start) fehlt im Change Log [spec-2-1-…md]
|
||||
- [x] [Review][Patch] Rev-8-Runde: Datums-Diskrepanz — `wiki/log.md`, `sprint-status.yaml` (`closed`) und der validator-Rev-8-Logeintrag sagen **2026-08-16**, aber der ausführende Commit `e6c36fc` sowie `deferred-work.md` („umgesetzt 2026-08-17") und das `→ review`-Flip-Verdikt sagen **2026-08-17**; aus den Artefakten ist nicht konsistent ableitbar, an welchem Tag die Runde lief [wiki/log.md:7, sprint-status.yaml:161]
|
||||
- [x] [Review][Patch] `epic-2-context.md`: „die Schema-Validierung von Story 1.4 **erzwingt auch AD-4c** (keine abgeleitete Provenienz)" — übertrieben; Vertrag §6.1 (A0-5/AD-4c) sagt, die Regel sei in v1 „tautologisch erfüllt" und „erzeugt kein eigenes Validitätsprädikat", und der Validator hat keinen AD-4c-Check. Der frisch angelegte Epic-Kontext schreibt Erzwingung einem Mechanismus zu, der per Definition noch nicht existiert [epic-2-context.md]
|
||||
- [x] [Review][Patch] `schema/compiler.md` Sprache: §5.2 „Der Body darf keine **grossen** Quell-Exzerpte enthalten" (→ „großen") und §1.4 „zu verarbeitende Evidenz kann auch andere **Aufträge** als `.md` tragen" (→ „Formate"/„Endungen") — beide in normativem Kontext (FR-2-Bodylimit, Evidenz-Definition) [schema/compiler.md:28,61]
|
||||
- [x] [Review][Patch] Spec `## Verification` + `## Suggested Review Order` veraltet: erwarten „KEINE … `schema/validator.md`-Mutationen" und „Validator (Rev 7) … unverändert autorisiert" — beides wird vom Diff widersprochen (validator.md ist jetzt Rev 8 und mutiert); die Spec wurde nie angepasst, um zu verzeichnen, dass Option A den legitimen Diff-Inhalt geändert hat [spec-2-1-…md]
|
||||
- [x] [Review][Patch] `schema/compiler.md` §3.2 Kollision-Hold: definiert nur das Ergebnis je Einheit („bricht für diese Einheit ab"), aber **nicht**, ob der Run die übrigen Einheiten fortsetzt und was der Gesamt-Run-Status bei teils-gehaltener Einheit ist — Run-Ergebnis nicht deterministisch ableitbar [schema/compiler.md:40]
|
||||
- [x] [Review][Patch] `schema/compiler.md` §5.3/§6.3: „keine weiteren Mutationen auf FAIL" + „Commit-Boundary ist die Mutations-Boundary" fehlt eine **explizite Rollback-Sequenz** für den Teilzustand (Concept-Datei + Index-Zeile + log-Zeile bereits geschrieben), der zwischen „Mutieren" und einem fehlgeschlagenen „Validieren" existiert — teilweise Mutationen könnten inkonsistent im Bundle liegen [schema/compiler.md:63,70]
|
||||
- [ ] [Review][Patch] `schema/validator.md` §7.1 Fixture 4a: das erwartete Verdikt — **GEGEHOLDERT (2026-08-17):** betrifft die gerade autorisierte, gefrorene `validator.md` (Rev 8); Anwendung setzt einen neuen Autorisierungsschlag auf `schema/` voraus und wird separat bestätigt, nicht automatisch mitgepatcht. `Punkt 4: … (resolved=README.md)` ist aus der §3-Punkt-4-Vorlage `(..-Traversal|absolut|URL|Backslash|file://)` **nicht ableitbar** — die Vorlage trägt kein `resolved=`-Token (Punkt 4 deckt zwar „außerhalb raw/ durch Auflösung", die Fehlerursachen-Grammatik listet es aber nicht); §7 verlangt „exakt die aus §3". *Betrifft die (gerade autorisierte) frozen `validator.md`* [schema/validator.md:63,214]
|
||||
- [ ] [Review][Patch] `schema/validator.md` Rev 8: die „formalisierte" **Innen-Ebenen-Punkt-6-Regel** hat keine Fixture-Zeile — **GEGEHOLDERT (2026-08-17):** betrifft die gerade autorisierte, gefrorene `validator.md` (Rev 8); Anwendung setzt einen neuen Autorisierungsschlag auf `schema/` voraus und wird separat bestätigt, nicht automatisch mitgepatcht. in §7.1/§7.3 — der einzige Punkt-6-Fixture ist Top-Level `foo: bar` (Zeile 6), die §7.3-Notiz zeigt `sources … role: x` nur als Inline-Beispiel, nicht als Tabellen-Fixture; die Zertifizierung dieses Falls existiert nur als Prosa in log.md/spec/sprint-status, kein re-runbares Sample ist committed, obwohl §7 behauptet, die Tabellen machten „jede mechanische Bedingung reproduzierbar nachprüfbar". *Betrifft die (gerade autorisierte) frozen `validator.md`* [schema/validator.md:214,260]
|
||||
|
||||
**defer:**
|
||||
|
||||
- [x] [Review][Defer] Content-Truth-Verifikation: kein Check verifiziert den Body eines Concepts gegen seinen deklarierten `raw/`-Quellen-Inhalt. Konkrete Instanz: `knowledge-kompilation-inkrementell.md` — das ASCII-Datenfluss-Diagramm-Layout stammt aus `raw/architecture-spine/…`, deklariert ist `sources: raw/epics/…` (Inhalt an sich ist kuratiert/korrekt, nur die exakte Diagrammform ist nicht von der deklarierten Source gedeckt) — deferred, Story 2.2 (bereits in deferred-work.md) [wiki/knowledge-kompilation-inkrementell.md]
|
||||
- [x] [Review][Defer] Concepts präsentieren Epic-3/4-Fähigkeiten als aktuelle Tatsache ohne Forward-Referenz-Marker: `knowledge-kompilation-inkrementell.md` „Verbindung zu Regelwerken" (NEW/CONFIRMING-CORRECTING-Klassifikation + grep/ripgrep-Relevanz → Story 3.2/4.1) und „FR-6 Aktualisierung statt neuer Dateien" (→ Story 3.1, die `compiler.md` §7/§3.2 explizit nicht baut und deren Kollision-Hold auf bestehendem Pfad sogar abbricht) — deferred, Story 2.2/3 [wiki/knowledge-kompilation-inkrementell.md:62-67]
|
||||
- [x] [Review][Defer] Determinismus-Selbsttest: §6.6-Interpretations-Hinweis behauptet „genau diese Form … im Demonstrationslauf erfüllt", die ✓-Zeile pinnt `at: 2026-08-16T09:23:33Z`, aber `generated.at` variiert pro Run (AD-15) — für einen Regenerate-Vergleich hält nur die Normalform, nicht „genau diese Form" — deferred, Story 2.3 (bereits in deferred-work.md) [schema/compiler.md:97,108]
|
||||
- [x] [Review][Defer] `wiki/log.md`: die neuen 2026-08-16/17-Einträge sind überwiegend Prozess/Meta-Content (Review-Verdikt, Action-Item-Statusflips, Validator-Revision-Ankündigungen) statt Vertrag-§5-„fachliche Änderungen … verknüpft mit dem mutierten Concept-Pfad"; kein Marker unterscheidet Meta- von Fach-Einträgen, kein Validierungs-Hook (F17 defert Log-Content-Validierung bewusst) — vorbestehendes Muster (Retrospective-Follow-up-Einträge), nicht neu durch diesen Diff verursacht — deferred, pre-existing [wiki/log.md]
|
||||
|
||||
**dismiss (2 — nicht persistent):**
|
||||
- Consumer-Namen (BMAD/Claude Code/Codex) in `wissensarchitektur-trennung-states.md` **sind** in der deklarierten `raw/architecture-spine/…` belegt (Zeilen 324/334/700–701) — kein Content-Truth-Verstoß (False Positive des Blind-Hunters).
|
||||
- Sandbox-Dryrun-Artefakte (`review-input-dryrun-…md`, `deferred-work.md`-Dryrun-Block) sind additiv, nicht-normativ, klar als externer Kontext aus `D:\mita\wow-2nd-sandbox` gelabelt — kein Befund gegen `schema/`/`wiki/`/`raw/`.
|
||||
|
||||
## Design Notes
|
||||
|
||||
**Warum eine Instruktion, kein Programm (D-3):** Genau wie der Validator (Story 1.4) ist der Compiler eine textuelle Agent-Instruktion — der deterministische Kern ist `schema/compiler.md`, ausgeführt von einem vorhandenen agentischen Host (AD-11). Das hält die Story klein, revisionierbar (Git) und prüfbar (AD-17h). Ein Standalone-Compiler ist explizit D-3-verboten und nur als dokumentierter Rückkehrpunkt für eine spätere Story zugelassen.
|
||||
|
||||
**Root-Ebene statt Areas (Umgehung des Punkt-11-/Area-Dilemmas):** Story 2.4 besitzt die deterministische Area-Zuordnung; Story 2.5 die Discovery-Navigation. Story 2.1 darf diesen Stories nicht vorgreifen. Daher entstehen die ersten Concepts **direkt unter `wiki/`** (`wiki/<concept>.md`) und werden — wie es der Punkt-11-Check des Validators für Root-Concepts verlangt — in der Bundleroot `wiki/index.md` verlinkt. Es wird kein `wiki/<area>/`-Verzeichnis angelegt. Story 2.4 kann diese Root-Concepts später per deterministischer Zuordnung in Areas verschieben (mit AD-7d-Rename-Eintrag in `log.md`).
|
||||
|
||||
**Demonstrationslauf = der eigentliche „Beweis":** Die Instruktion allein wäre nur Theorie. Der Run gegen die 3 `raw/`-Evidenzdateien erzeugt echte Concepts und wird anschließend gegen den **autorisierten Validator** (Story 1.4) geprüft — das ist die mechanische Bestätigung der Konformität (Kultur aus Story 1.4: Validator-Selbstprüfung gegen Fixtures). Die `at`-Zeitstempel werden zum Ausführungszeitpunkt in UTC-ISO-8601 gesetzt.
|
||||
|
||||
**Zeitstempel-Determinismus:** Der `at`-Wert ist ein Ausführungszeitpunkt und damit per se nicht deterministisch über Runs hinweg — das ist beabsichtigt (Trust-Metadaten beschreiben den Erzeugungsmoment, AD-15). Deterministisch sind Pfad, Struktur, Frontmatter-Form und `sources`-Auflösung; der Verdikt-Erfolg hängt nicht von einer festen `at`-Sekunde ab.
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands:**
|
||||
- `git status --short && git diff --stat` — expected: neue Datei `schema/compiler.md` + `wiki/<slug>.md`-Concepts + `wiki/index.md`-Änderung + `wiki/log.md`-Eintrag + `sprint-status.yaml`-Update; KEINE `raw/`- oder `schema/wiki-compiler.md`-Mutationen. (Hinweis 2026-08-17: `schema/validator.md` ist zwischenzeitlich im Rahmen der autorisierten Option-A-Revision 8 mutiert — der ursprüngliche Diff-Erwartungswert „KEINE `schema/validator.md`-Mutationen" gilt für den Story-2.1-Erstellungs-Diff, nicht mehr für den Gesamt-Stand nach Validator-Rev-8.)
|
||||
- Validator-Instruktion gegen Bundle ausführen (manuell/deterministisch, siehe `schema/validator.md` §5-Grammatik): `grep -nE 'Punkt 11|concept nicht verlinkt' schema/validator.md` + praktischer SUCCESS-Lauf des Validators gegen `wiki/` — expected: alle neuen Concepts + `index.md` + `log.md` liefern `SUCCESS` (kein FAIL, kein WARN-Blocker).
|
||||
- Frontmatter-Konformitäts-Smoke: `grep -nE '^(type|sources|generated|verified|status|stale_after):' wiki/*.md` — expected: nur §3-Felder je Concept; `type` gesetzt; `generated.at` im Format `YYYY-MM-DDTHH:MM:SS` (mit Offset-Suffix).
|
||||
- `sources`-Auflösung: `grep -nE 'resource:' wiki/*.md` — expected: jeder Wert ist ein existierender `/`-getrennter `raw/`-Pfad (kein `..`, kein `wiki/`, keine URL).
|
||||
- `git log --oneline -3 -- raw/` — expected: keine neuen Commits/Einträge unter `raw/` (immutable).
|
||||
- `at`-Format-Smoke (Punkt 14): `grep -nE '^ at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(Z|[+-][0-9]{2}:?[0-9]{2})$' wiki/*.md` (je `generated.at`/`verified.at` ein volles ISO-8601-Datetime; reines Datum wäre FAIL Punkt 14).
|
||||
- `sources`-Eintrag-Key-Subset (Vertrag §3.3/Punkt 6): `grep -nE '^ - [a-z_]+:' wiki/*.md` — expected: je `sources`-Eintrag ausschließlich `resource` (bzw. erlaubte optionale: `id`/`title`/`author`/`usage_count`/`last_modified`); kein unautorisierter Key.
|
||||
|
||||
**Manual checks (if no CLI):**
|
||||
- `schema/compiler.md` ist rein textuell (kein Programmcode/Executable-Abschnitt) und beginnt mit Zweck & Aufruf.
|
||||
- Alle Erzeugungsregeln sind deterministisch formuliert und auf Vertrag/Validator zurückführbar (kein reines LLM-Urteil).
|
||||
- `wiki/log.md` enthält einen datierten Eintrag über die angelegten Concepts mit Quell-Pfaden.
|
||||
- Jede Concept-Datei ist menschlich lesbares Markdown (NFR-2) und nicht bloße Kopie der Quelle (FR-2).
|
||||
|
||||
## Verification Record (Ausführungs-Beleg, 2026-08-16)
|
||||
|
||||
**Demonstrationslauf:** `schema/compiler.md` (Revision 1.1) angelegt; 3 Root-Concepts erzeugt; `wiki/index.md` + `wiki/log.md` mutiert. `sprint-status.yaml`: epic-2 + Story 2.1 → `in-progress`.
|
||||
|
||||
**Validator-Lauf gegen das mutierte Bundle (gemäß `schema/validator.md`, Revision 6, deterministisch ohne LLM-Urteil):**
|
||||
|
||||
| Datei | Punkte 1–14 | §6/V §6.1 EC-1 | Verdikt |
|
||||
|---|---|---|---|
|
||||
| `wiki/index.md` | 8, 9, 13 ✓ (Punkt 8 OK, kein Punkt-9-Inhalt, keine Duplikate) | — | SUCCESS |
|
||||
| `wiki/log.md` | 10 ✓ (kein Frontmatter), 9 ✓ | — | SUCCESS |
|
||||
| `wiki/llm-wiki-prinzip.md` | 1, 2, 6, 7, 12, 13, 14 ✓ (`type: concept`, `generated.by` gesetzt, `at` = `2026-08-16T09:23:33Z` volles ISO-8601, canonical key order, keine Duplikate) | EC-1 ✓ (`raw/prd/prd-wow20-2026-08-14.md` existiert als Datei) | SUCCESS |
|
||||
| `wiki/knowledge-kompilation-inkrementell.md` | 1, 2, 6, 7, 12, 13, 14 ✓ | EC-1 ✓ (`raw/epics/epics-2026-08-14.md` existiert) | SUCCESS |
|
||||
| `wiki/wissensarchitektur-trennung-states.md` | 1, 2, 6, 7, 12, 13, 14 ✓ | EC-1 ✓ (`raw/architecture-spine/architecture-spine-2026-08-14.md` existiert) | SUCCESS |
|
||||
|
||||
**Punkt 11 (Index-Regel):** Alle 3 Root-Concept-Identitäten `llm-wiki-prinzip`, `knowledge-kompilation-inkrementell`, `wissensarchitektur-trennung-states` sind in `wiki/index.md` verlinkt (`grep -c` je = 1) ✓.
|
||||
|
||||
**Punkt 3/4 (Keine `wiki/`-Auflösung, Pfad-Grammatik):** Alle `resource`-Werte sind `/`-getrennte `raw/`-Pfade ohne `..`, ohne führendes `/`, ohne Backslash, ohne URL ✓.
|
||||
|
||||
**Scope:** Keine Mutation unter `raw/` (`git log raw/` ohne neue Commits), `schema/wiki-compiler.md` und `schema/validator.md` unverändert (autorisiert) ✓. Frontmatter-Smoke `grep -nE '^(type|sources|generated|verified|status|stale_after):' wiki/*.md` → nur §3-Felder in Concepts, kein `okf_version`/`type: bundle` ✓.
|
||||
|
||||
**Gesamtergebnis:** `SUCCESS` für alle 5 Bundle-Dateien — kein FAIL. Run als erfolgreich gewertet (Integrations-/Verifikations-Beleg).
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- **2026-08-17 (Human-Review-Freigabe → `done`):** Nutzer-Freigabe erteilt — Story 2.1 ist `done` (Status `review` → `done`); die letzte verbleibende Schwelle (menschliche Review-Freigabe) ist damit überschritten. Alle 8 ACs PASS, kein AC-/Vertrags-Blocker; offene Folge-Arbeit (autorisierte Validator-Revision 9: Punkt-4-Grammatik `resolved=`-Token, Innen-Ebenen-Punkt-6-Fixture-Zeile) ist kein Story-2.1-Blocker und bleibt in `deferred-work.md` / Action-Item `code-review-2-1-item-2` verankert. `sprint-status.yaml`: Story 2.1 → `done`.
|
||||
- **2026-08-17 (Code-Review-Re-Run, Patches 15/17 umgesetzt):** Unabhängiger Re-Run (4 Layer) auf dem Stand nach Validator-Rev-8: 17 Patch / 4 Defer / 2 Dismiss, alle 8 ACs PASS. 15 Patches umgesetzt — `schema/compiler.md` → Revision 1.4 (Prüfgrundlage Rev 8, §6.6-Referenzlabels §4.5/§4.2, §3.2 Kollision-Hold-Run-Fortsetzung, §5.3/§6.3 Rollback-Sequenz, Sprachkorrekturen), `wiki/log.md` (verlorener Bullet, Rev-8-Datum), `wiki/index.md` (Baumdiagramm), `deferred-work.md` (Dedupe, n=21), `review-input-dryrun-…md` (Datei-Auflösung 16+2), `validator-revision-8-…md` (status done, DoD), `epic-2-context.md` (AD-4c tautologisch), spec Verification/Suggested-Review-Order (Rev 8), `sprint-status.yaml` (closed-Datum 08-17). 2 Patches auf der gefrorenen `validator.md` (Rev 8) **geholdert** → nächste autorisierte Validator-Revision (Rev 9): Punkt-4-Grammatik `resolved=`-Token + Innen-Ebenen-Punkt-6-Fixture-Zeile (s. `deferred-work.md` „Arbeitsauftrag Rev 9", Action-Item `code-review-2-1-item-2`). Status bleibt `review` (`done`-fähig; verbleibende Schwelle = Human-Review).
|
||||
- **2026-08-17 (Re-Review):** Re-Re-Review-Verdikt — Option-A-Voraussetzung erfüllt (autorisierte Validator-Revision 8 ausgeführt und zertifiziert: F-14-Fixture 4a, Innen-Ebenen-Key-Subset formalisiert, Header „Revision 6" → „Revision 8"); Story 2.1 `review`-fähig und `done`-fähig; verbleibende Schwelle bis `done` ausschließlich die menschliche Review-Freigabe.
|
||||
- **2026-08-16 (Step-04-Review):** `sources`-Eintrag-Key-Subset als Zusatz-Verification-Check ergänzt (Vertrag §3.3, Punkt 6); `at`-Format-Smoke als Punkt-14-Beleg unter die Verification-Checks aufgenommen; `status: in-review` (Review begonnen). Keine Änderung am `<frozen-after-approval>`-Intent.
|
||||
- **2026-08-16 (Erstellung):** Initiale Approve-Baseline.
|
||||
|
||||
## Edge-Case-Matrix-Audit
|
||||
|
||||
| Scenario | Abgedeckt durch | Befund |
|
||||
|---|---|---|
|
||||
| HAPPY_PATH | §5 Demonstrationslauf | ✓ 3 Concepts erzeugt, verlinkt, validiert |
|
||||
| CONCEPT_OHNE_TYPE | §4.1 (Punkt 1) + §6.5 Kriterium 1 | ✓ Instruktion verlangt zwingend non-empty `type`; Abweichung → Run-FAIL mit textueller Ursache |
|
||||
| FEHLENDE_RAW | §4.2 + §6.5 Kriterium 3 (EC-1) | ✓ nur real existierende `raw/`-Dateien als `resource` |
|
||||
| LEERE_QUELLE / KEINE_WISSENSEINHEITEN | §1.3/§1.4 (Artefakt-Ausschluss) | ✓ `raw/README.md`, `raw/**/source.md` sind kein Input/keine Evidenz; werden nie `resource` |
|
||||
| VERALTETE_SOURCE | §1.4 (Sidecar = Artefakt, nicht Input) | ✓ fehlende Commit-Auflösbarkeit blockiert Erzeugung nicht |
|
||||
| KEIN_CONTENT | §2.3 (FR-2, Curated ≠ Copy) | ✓ bloße Kopie/Zusammenfassung → kein Concept |
|
||||
|
||||
## Step-04-Review-Nachschärfungen (2026-08-16)
|
||||
|
||||
Nach den drei Review-Layern (Blind Hunter, Edge Case Hunter, Verification Gap) angewendet:
|
||||
|
||||
- `schema/compiler.md` auf Revision 1.2: Input-Regel auf AD-17a statt AD-17.2 referenziert; `sources`-Eintrag-Key-Subset (Innen-Ebene, Vertrag §3.3) in §4.2, §6.5-Kriterium-1 und §6.6 ergänzt; `status`-Absenz Formulierung an Vertrag §3.6 (Absenz = `stable`) angebunden; Bereichs-Ziel-Ablehnung bis Story 2.4 (§5.1/§6.6); §6.6-Fehlerursache der `verified`-Zeile auf Punkt 6 korrigiert (statt „semantisch (Trust)"); §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 sichtbar (§0/§5.3/§6.6).
|
||||
- `schema/validator.md` auf Revision 7: §7.3-Isolations-Hinweis um Innen-Ebenen-Key-Subset-Fälle (Punkt 6 in `sources`/`generated`/`verified`-Einträgen) erweitert.
|
||||
- `wiki/index.md`: Workspace-Absatz präzisiert — `schema/` enthält drei Artefakte (Vertrag, Validator, Compiler-Instruktion) statt nur „Compiler-Schema-Vertrag".
|
||||
- `wiki/log.md`: Review-Eintrag ergänzt (Nachschärfungen + `at`-Konsistenz-Prüfung).
|
||||
- `sprint-status.yaml`: Story 2.1 → `review` (Review begonnen).
|
||||
|
||||
**Verifiziert gegen Fehlalarme:** `at: 2026-08-16T09:23:33Z` entspricht 11:23:33 Lokalzeit (+0200) und deckt sich mit den Datei-Mutationszeitpunkten (11:24) — kein Befund auf die Ausführungszeit; Consumer-Namen (BMAD/Claude Code/Codex) sind in `raw/prd`, Spine und Epics verbatim belegt; Key-Reihenfolge liegt korrekt in Validator §4.1 (Zeile 104); „Mutieren" (AD-6/A0-7) steht im Einklang mit dem inkrementellen „Update"-Fluss (A0-6).
|
||||
|
||||
**Defer-Kontexte (in `deferred-work.md` notiert):** Content-Truth-Verifikation (kein check prüft die inhaltliche Übereinstimmung eines Concept-Bodys mit seinen `raw/`-Quellen; Story 2.2/Deferred) sowie eine `at`-basierten Determinismus-Selbsttest-Divergenz (die `at`-Sekunde variiert pro Run, während der §6.6-Interpretations-Hinweis eine feste Form behauptet — mit der `at`-Run-Zeit semantisch konsistent, als Selbsttest-Dokumentation für Story 2.3/nächste Validator-Revision zu schärfen).
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Einstieg (Design-Intent der Story)**
|
||||
|
||||
- Deterministic compiler instruction — the single artifact that makes Story 2.1 load-bearing: one place, textual (D-3), flow Interpret→Reconcile→Synthesize→Mutate→Validate.
|
||||
[`compiler.md`](../../schema/compiler.md#L1)
|
||||
|
||||
**Feldsubset & Trust — Intake der drei Artefakte**
|
||||
|
||||
- New compiler instruction: `sources`-entry key-subset (Innen-Ebene, Vertrag §3.3) and `generated` (by/at, no verified) — the §4 production rules in canonical form.
|
||||
[`compiler.md`](../../schema/compiler.md#L48)
|
||||
|
||||
- Authorized contract: field subset, `sources` key-subset per entry, `generated` by/at — the normative anchor Story 2.1 derives from (unchanged, authorized).
|
||||
[`wiki-compiler.md`](../../schema/wiki-compiler.md#L53)
|
||||
|
||||
- Validator (Rev 8): F-14-Negativ-Fixture 4a (§7.1, Punkt 4) + Innen-Ebenen-Key-Subset formalisiert (Punkt 6 → §7.3-Isolations-Notiz, autorisiert) + Header-Revisionszahl auf 8 angehoben (OBS-1 behoben) — autorisierte Option-A-Revision, 2026-08-17 ausgeführt und zertifiziert.
|
||||
[`validator.md`](../../schema/validator.md#L260)
|
||||
|
||||
**Wissenseinheiten — Konzepte aus den Quellen**
|
||||
|
||||
- `LLM-Wiki-Prinzip` — Anker-Concept: Compounding, Knowledge Compiler vs. Retrieval; Trust-Metadaten gemäß A0-20 (generated ohne verified).
|
||||
[`llm-wiki-prinzip.md`](../../wiki/llm-wiki-prinzip.md#L1)
|
||||
|
||||
- `Knowledge Compilation & Inkrementelle Evolution` — AD-5-Datenfluss, FR-12/FR-6/FR-14; Abgrenzung zu Epic 3.
|
||||
[`knowledge-kompilation-inkrementell.md`](../../wiki/knowledge-kompilation-inkrementell.md#L1)
|
||||
|
||||
- `Wissensarchitektur: Source Material, Curated Knowledge & Consumer` — AD-2/AD-3-Grenzen, Consumer-Unabhängigkeit, Konvergenzregeln.
|
||||
[`wissensarchitektur-trennung-states.md`](../../wiki/wissensarchitektur-trennung-states.md#L1)
|
||||
|
||||
**Verlinkung & Dokumentation — Bundle-Integrität**
|
||||
|
||||
- Bundleroot-Index: `## Concepts` mit den 3 Root-Concept-Links + korrigierter Workspace-Beschreibung (drei `schema/`-Artefakte).
|
||||
[`index.md`](../../wiki/index.md#L24)
|
||||
|
||||
- Bundle-Log: Story-2.1-Demonstrationslauf- und Review-Einträge (datumsgruppiert, ohne Frontmatter).
|
||||
[`log.md`](../../wiki/log.md#L3)
|
||||
|
||||
**Status & Tracking — Peripherie**
|
||||
|
||||
- Sprint-Status: epic-2/Story-2.1 auf `review` (Review begonnen), nach Abschluss auf `done` zu flippen.
|
||||
[`sprint-status.yaml`](../../_bmad-output/implementation-artifacts/sprint-status.yaml#L45)
|
||||
+158
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: 'Claim-granulare Provenienz dokumentieren (Story 2.2)'
|
||||
type: 'feature'
|
||||
created: '2026-08-17'
|
||||
status: 'done'
|
||||
review_loop_iteration: 2
|
||||
baseline_commit: bb32acdf3f1a3547424da0f878bd06383921b22a
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-2-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Die drei Concepts aus Story 2.1 tragen Provenienz nur auf Concept-Ebene (`sources`-Frontmatter); belegte Aussagen und Kontext-/Synthese-Umformulierungen sind claim-granular nicht auf `raw/`-Evidenz rückführbar (AD-4a, A0-3). Instanz: `knowledge-kompilation-inkrementell.md` deklariert nur `raw/epics/…`, enthält aber ein ASCII-Diagramm aus `raw/architecture-spine/…`.
|
||||
|
||||
**Approach:** `schema/compiler.md` um Sektion „Claim-granulare Provenienz" erweitern (Inline-`raw/`-Verweise je belegter Aussage, Kontext-Marker je Übernahme, `id`-Attribution aus Vertrag §3.3) und die drei Concepts + `wiki/index.md` + `wiki/log.md` nachkonformieren. Kein Standalone-Tool, keine neue §7-Klasse, keine Vertragsänderung.
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- Provenienz = Body-Text-Konvention (Inline-`raw/`-Verweis je belegter Aussage; Kontext-Marker „übernommen aus `<Concept-Pfad>` auf Basis von `<source>`, nicht eigenständig belegt" je Übernahme — AD-4a/A0-3). Kein Frontmatter-Change, kein neues Feld.
|
||||
- Nachrüstung mutiert ausschließlich `wiki/` (Concept-Bodies, `index.md`, `log.md`). `raw/`, `schema/wiki-compiler.md`, `schema/validator.md` unverändert (AD-3). `schema/compiler.md` = einziger Instruktions-Ort (D-3).
|
||||
- Neue `sources`-Einträge: nur §3.3-Subset; `id` je Concept eindeutig; `resource` nie `wiki/` (AD-4b); kein generiertes Concept führt ein anderes als alleinige Provenienz (AD-4c).
|
||||
- `generated`/`verified`/`status` unangetastet (v1-Default A0-20). Epic-3/4-Fähigkeiten im Body als Forward-Referenz ohne eigene Behauptung markiert.
|
||||
- Revisionslog der Instruktion + `wiki/log.md` (Vertrag §5) dokumentieren die Änderung.
|
||||
|
||||
**Ask First:** Neue §7-Klasse / Vertragsänderung · Standalone-Programm (D-3) · `wiki/<area>/`-Anlage (Story 2.4).
|
||||
|
||||
**Never:** OKF-Dialekt · Änderung an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` · Validator-Verhaltenswechsel (bleibt strukturell; Content-Truth = eigenständige Arbeit) · Vorwegnahme Story 2.3/2.4 · Falsch-Attribution.
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input | Expected | Error Handling |
|
||||
|----------|-------|----------|----------------|
|
||||
| HAPPY_PATH | 3 Concept-Bodies, Kern + Übernahmen (z. B. ASCII-Diagramm) | Belegte Aussagen mit Inline-Verweis; Übernahmen mit Marker; Diagramm-Quelle deklariert; Validator SUCCESS | N/A |
|
||||
| UNBELEGTE_AUSSAGE | Aussage nicht auf `sources` rückführbar | Als Übernahme mit Marker geführt (nicht erfunden belegt) | Run bricht nicht ab; textuell sichtbar |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/compiler.md` — **mutiert**: Sektion „Claim-granulare Provenienz" (Inline-Verweise, Kontext-Marker, `id`); Revisionslog (§8); §7-Selbstbegrenzung.
|
||||
- `schema/wiki-compiler.md` — **read-only**: §3.3 `sources`/`id`, §5 `log.md`, §7 abschließende Liste.
|
||||
- `schema/validator.md` — **read-only (Rev 8)**: bleibt strukturell.
|
||||
- `wiki/llm-wiki-prinzip.md`, `wiki/knowledge-kompilation-inkrementell.md`, `wiki/wissensarchitektur-trennung-states.md` — **mutiert**: Body um Inline-Verweise/Kontext-Marker.
|
||||
- `wiki/index.md` — **mutiert**: Beschreibungen um `(aus <raw-Pfad>)`.
|
||||
- `wiki/log.md` — **append-only**: Nachrüst-Eintrag inkl. Diagramm-Quell-Deklaration.
|
||||
- `raw/architecture-spine/…` (AD-4a :143), `raw/epics/…`, `raw/prd/…` — **read-only Evidenz**.
|
||||
- `_bmad-output/implementation-artifacts/epic-2-context.md` — Planungskontext (read-only).
|
||||
- `sprint-status.yaml` — **mutiert**: Status-Übergang (Review-Workflow-Sync, `backlog` → `review`).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/compiler.md` — Sektion „Claim-granulare Provenienz" (nach §5, vor §6): Inline-`raw/`-Verweis je belegter Aussage (+ `id`), Kontext-Marker je Übernahme, eindeutiges `id`-Scoping (§3.3), Selbsttest-Kriterien (belegte Aussage → `raw/`-Verweis; Übernahme → Marker; kein unautorisierter Key) — AD-4a/4c, AD-13, AD-17h. **inkl. Review-Patch-Runde (Rev 1.6): Stellen-Kennungs-Semantik, volle Pfade, Direktübernahme-Marker, worked example, korrigierte Grep-Formel.**
|
||||
- [x] `schema/compiler.md` — Revisionslog (§8, Fortlauf) + §7-Selbstbegrenzung „→ Story 2.2".
|
||||
- [x] Nachrüst-Schritt: 3 Concept-Bodies — belegte Aussagen mit Inline-`raw/`-Verweisen; Übernahmen (insbesondere ASCII-Diagramm → `raw/architecture-spine/…`) mit Kontext-Marker + ggf. zusätzlichem `sources`-Eintrag; Epic-3/4-Formulierungen als Forward-Referenz.
|
||||
- [x] `wiki/index.md` — Beschreibungen um `(aus <raw-Pfad>)`.
|
||||
- [x] `wiki/log.md` — Nachrüst-Eintrag (§5-Format).
|
||||
- [x] Validator-Lauf — alle 5 `wiki/`-Dateien SUCCESS (Punkte 1/6/11/14, EC-1) (manuell-mechanisch, D-3; kein CLI).
|
||||
- [x] `sprint-status.yaml` — Story 2.2 → `in-progress`.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given Concept mit fachlichen Aussagen, when nach Story 2.2 verarbeitet, then trägt jede belegte Aussage einen Inline-Verweis auf `raw/`-Evidenz (AD-4a).
|
||||
- Given Kontext-/Synthese-Umformulierung, when übernommen, then trägt sie den expliziten Kontext-Marker — inklusive ASCII-Diagramm.
|
||||
- Given `sources`-Dokumentation, when gesetzt, then lösen Werte ausschließlich auf `raw/`-Pfade auf (AD-4b); kein generiertes Concept führt ein anderes als alleinige Provenienz (AD-4c) — formseitig prüfbar.
|
||||
- Given Nachrüst-Inhalte, when validiert, then bleibt das Bundle vollständig Validator-SUCCESS (keine neue Invaliditätsklasse, keine Vertrags-/`raw/`-Mutation).
|
||||
- Given Instruktions-Bestand, when geprüft, then rein textuell (D-3), deterministisch (AD-17h), referenziert den Vertrag.
|
||||
|
||||
### Review Findings (bmad-code-review, 2026-08-17)
|
||||
|
||||
> Vier Layer (Blind Hunter, Edge Case Hunter, Verification Gap, Acceptance Auditor) auf `bb32acd → story-2-2`. Dedupliziert, Severity durch Workflow gesetzt (Reviewer-Severity verworfen). 1 `decision-needed` (entschieden 2026-08-17 → Option 1), 12 `patch`, 4 `defer`, 2 dismissed (Status-Drift als Workflow-Bug — 2.1-Präzedenz; non-behavioral Screen-outs).
|
||||
|
||||
**Decision-Needed**
|
||||
|
||||
- [x] [Review][Decision] **D1 — Referenzform: Komma-Form vs. verbindliche `#`-Form** — **Entschieden (2026-08-17): Option 1** — Komma-Form als zulässige Variante in §5.5 Pkt.1 formal zulassen; Bodies bleiben unverändert. Umsetzung als Patch **P12** (siehe unten).
|
||||
|
||||
**Patch**
|
||||
|
||||
- [x] [Review][Patch] **P1 — Selbsttest-Grep-Formel defekt (ungeschlossenes Klammerpaar)** `schema/compiler.md:76,99` — `grep -nE '(raw/|]\(raw/'` öffnet eine Gruppe, schließt sie nie → `exit 2 „Unmatched ( or \("` (reproduziert). AC-5/AD-17h (deterministischer Selbsttest) liefert einen Fehler statt deterministischer Ausgabe. Rev-1.6-„Korrektur" war unnötig: `\(raw/` (noch in Spec Verification) erfasst bereits beide Formen. Fix: eine funktionierende Formel in compiler.md Pkt.1+Pkt.4 **und** Spec Verification synchron halten.
|
||||
- [x] [Review][Patch] **P2 — „Pkt. 1b" referenziert, aber nicht definiert** `schema/compiler.md:68,112` + `_bmad-output/implementation-artifacts/deferred-work.md:196` — die Relokations-Regel ist ein unnummeriertes Sub-Bullet unter Pkt.1; das Label „1b" existiert in §5.5 nicht. Fix: Sub-Bullet als „1b" nummerieren (hält alle drei Referenzen) oder alle drei Referenzen umschreiben.
|
||||
- [x] [Review][Patch] **P3 — Marker-Muster-Zahl inkonsistent** `schema/compiler.md:81,100` — Pkt.2 öffnet mit „zwei Marker-Muster", definiert dann drei (Zwischen-Concept, Direktübernahme, Forward-Referenz); Pkt.4 wiederholt „einen der beiden". Fix: „drei" / Forward-Referenz als Variante kennzeichnen.
|
||||
- [x] [Review][Patch] **P4 — §8 Normreferenzen nicht für §5.5 ergänzt** `schema/compiler.md:172-177` — fehlen `AD-4a`, `A0-3` (Kernnormen des §5.5) sowie `AD-16`, `AD-9`, `AD-13`, `AD-14` (jetzt in den Bodies zitiert). Fix: Spine-/Epics-Zeile um die tatsächlich genutzten Normen erweitern.
|
||||
- [x] [Review][Patch] **P5 — `wiki/log.md`-Eintrag: veralteter Status** `wiki/log.md:4` — Eintrag endet „— Story 2.2 `in-progress`", während derselbe Diff `sprint-status.yaml` auf `review` setzt. Fix: auf `review` angleichen.
|
||||
- [x] [Review][Patch] **P6 — Spec `review_loop_iteration: 0`** `spec…md:6` — trotz abgeschlossener Step-04-Review-Loop + Patch-Runde (P1–P7) und Defers; Vergleich `spec-2-1` = 2. Fix: tatsächliche Iterationszahl setzen.
|
||||
- [x] [Review][Patch] **P7 — Suggested-Review-Order-Statuszeile falsch** `spec…md:124` — „Story-Status `in-progress` (nach Human-Review → `review`)" zeigt auf `sprint-status.yaml:47`, die hier bereits `review` ist; Klammer dreht die Workflow-Richtung um (Human-Review → `done`). Fix: Zeile korrigieren.
|
||||
- [x] [Review][Patch] **P8 — Code Map lässt `sprint-status.yaml` aus** `spec…md:43` — die Code Map enumeriert alle mutierten Dateien, außer `sprint-status.yaml`, den die eigene Verification `git diff --stat` aufführt. Fix: ergänzen.
|
||||
- [x] [Review][Patch] **P9 — deferred-work-Eintrag bricht Datei-Format** `_bmad-output/implementation-artifacts/deferred-work.md:195-197` — neu eingeführter Eintrag trägt `source_spec:`/`summary:`/`evidence:`, aber kein `status:`/`Home:` wie alle bestehenden. Fix: `status:`-Zeile mit Owner ergänzen.
|
||||
- [x] [Review][Patch] **P10 — Gefrorener Block: „Kein Frontmatter-Change" wörtlich widersprüchlich** `spec…md:74` — der Frozen-Block sagt „Kein Frontmatter-Change, kein neues Feld", der Diff ergänzt aber `id`-Werte + zwei `sources`-Einträge. Rev 1.6 löste das nur auf compiler.md-Seite; das Spec Change Log dokumentiert die Angleichung nicht. Fix: Angleichungs-Hinweis („kein neues Feld *über das §3.3-Subset hinaus*") im (nicht gefrorenen) Change Log nachführen — Frozen-Block unverändert lassen.
|
||||
- [x] [Review][Patch] **P11 — Forward-Referenz-Zitat „Epic-3-Abschnitt" mehrdeutig** `wiki/knowledge-kompilation-inkrementell.md:52` — `raw/epics/…` trägt zwei „Epic 3"-Headings (`### Epic 3` Zeile 90, `## Epic 3` Zeile 258). Fix: auf die eine Sektion disambiguieren (exakter Sektionstitel/Nummer).
|
||||
- [x] [Review][Patch] **P12 — D1-Umsetzung: Komma-Form als zulässige Variante in §5.5 Pkt.1 formal zulassen** `schema/compiler.md:72-77` — §5.5 Pkt.1 neben der verbindlichen Default-Form `(raw/<datei.md>#<stellen-kennung>)` die **Komma-Form** `(raw/<datei.md>, <stellen-kennung>)` als zulässige zweite Form zulassen (für Stellen-Kennungen, die im Rohdokument als Sektionstitel/Nummer ohne Bezeichner-`id` vorliegen, z. B. `§ 1 Vision`, `§ 4.5 FR-16`) — analog zum bereits vorhandenen Präzedenzfall „Link-Form ggü. Plain-Form bis Story 2.3 formal offen, beide zulässig, sofern der volle `raw/`-Pfad am Verweis erkennbar und Grep-greifbar". Zusätzlich: **Multi-Beleg-Serialisierung** festlegen (Komma-Gruppierung `#ID1, #ID2` unter einem Pfad explizit zulassen ODER je Kennung vollen Pfad wiederholen — Konsistenz mit den Bodies; vgl. `wiki/wissensarchitektur-trennung-states.md:15`). Worked Example um ein Komma-Form-Beispiel ergänzen. Bodies bleiben unverändert (Form ist dort dann konform). Rev-1.7-Eintrag im §8-Revisionslog.
|
||||
|
||||
**Defer (vorbestehend / Scope)**
|
||||
|
||||
- [x] [Review][Defer] **W1 — Sources-Closure (inline `raw/`-Pfad ⊆ `sources`)** — bereits in `deferred-work.md` (Abschnitt „Deferred from: code review of story-2.2") verankert; kein neues Handeln.
|
||||
- [x] [Review][Defer] **W2 — Stellen-Kennung-Existenz im Rohdokument wird nirgends geprüft** `schema/compiler.md:74` — Fragment-Typo (z. B. `#FR-19`, `#AD-1b`) oder verbotenes Concept-`id`-Fragment `#s1` durchläuft Grep + 14 Validator-Punkte + EC-1 (Datei existiert) → SUCCESS; Falsch-Attribution ohne Pin. D-3-/kein-Standalone-Kontext; Schwester zu W1.
|
||||
- [x] [Review][Defer] **W3 — Kontext-Marker-Grammatik (Selbstreferenz-Verbot, Musterwahl) ungeprüft** `schema/compiler.md:81-94` — ein Selbstreferenz-Marker (Concept nennt sich als Ursprung) trägt den exakten Token und passiert jede re-runnable Prüfung; das Rev-1.6-Selbstreferenz-Verbot ist durch nichts erzwingbar. Schwester zu W1.
|
||||
- [x] [Review][Defer] **W4 — `sources`-`id`-Eindeutigkeit je Concept ohne Check** `schema/compiler.md:96` — duplizierte `id`-Werte (z. B. beide `s1`) passieren Validator Punkt 6 (prüft Keys, nicht Werte) + Punkt 13 (Top-Level) + Spec-Greps; §5.5 Pkt.4 führt die Regel nicht. Schwester zu W1.
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- **2026-08-17 (Erstellung):** Initiale Approve-Baseline.
|
||||
- **2026-08-17 (Patch-Runde, Step-04-Review):** Review-Findings (patch-Klasse) umgesetzt: §5.5-Klarstellungen (Rev 1.6 in `schema/compiler.md`), Body-Vereinheitlichung (Stellen-Kennungs-Sektionstitel statt Concept-`id`-Fragmente, volle `raw/`-Pfade je Beleg, Direktübernahme-Marker ohne Selbstreferenz, FR-16-Beleg auf PRD §4.5 allein), `index.md`/`log.md`-Angleichungen. Klassifikation: `review-2-2-klassifikation.md`. Defer: sources-Closure-Verifikation → `deferred-work.md`.
|
||||
- **2026-08-17 (bmad-code-review, 4 Layer — Patch-Runde 2):** 1 `decision-needed` (D1 Referenzform → **Option 1: Komma-Form als zulässige Variante** in §5.5 Pkt.1) + 12 `patch` umgesetzt (`schema/compiler.md` → **Rev 1.7**: Grep-Formel behoben, Komma-Form + Multi-Beleg-Serialisierung, 1a/1b-Nummerierung, drei Marker-Muster, Forward-Referenz-Disambiguierung, §8-Normreferenzen; `wiki/log.md` Status `review`; `wiki/knowledge-kompilation-inkrementell.md` Forward-Referenz-Zitat; Spec-Interna: Code Map + `sprint-status.yaml`, Verification-Grep-Synchronisation, Review-Order-Statuszeile, `review_loop_iteration`). Defer: W2–W4 (neue Schwester-Gaps zu W1: Fragment-Existenz, Marker-Grammatik, `id`-Eindeutigkeit — keine re-runnable Prüfung möglich ohne Standalone, D-3) → `deferred-work.md`.
|
||||
- **Angleichung zum Frozen-Block (Review-Finding P10):** Die frozen-Block-Zeile „Kein Frontmatter-Change, kein neues Feld" ist als „**kein neues Feld *über das §3.3-Subset hinaus*\" zu lesen — das Hinzufügen/Erweitern bestehender `sources`-Einträge (`resource`/`id`, Relokation/Zielwechsel, §5.5 Pkt. 1b) ist Teil der Konvention und erfolgt im vorliegenden Diff (drei Concepts, zwei neue `sources`-Einträge + `id`-Vergabe). Der Frozen-Block selbst bleibt unverändert; diese Leseanweisung ist hier dokumentiert, weil die wörtliche Formulierung mit dem deliverierten Change kollidierte (Rev 1.6 hat die Angleichung nur auf `compiler.md`-Seite vorgenommen).
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands:**
|
||||
- `git diff --stat` — `schema/compiler.md`, 3 x `wiki/*.md`, `wiki/index.md`, `wiki/log.md`, `sprint-status.yaml`; KEINE `raw/`-/`schema/wiki-compiler.md`-Mutation.
|
||||
- `sh -c "grep -nE '\(raw/' wiki/*.md"` — je belegter Aussage ein Inline-`raw/`-Verweis (die Formel `grep -nE '\(raw/'` ist die verbindliche Selbsttest-Formel, `schema/compiler.md` §5.5 Pkt.1/Pkt.4, Rev 1.7; das Teilmuster `(raw/` erfasst Plain-Form und Markdown-Linkform).
|
||||
- Validator-Lauf (deterministisch) — alle `wiki/`-Dateien SUCCESS (Punkte 1/6/11/14, EC-1).
|
||||
- `grep -nE '^(type|sources|generated|verified|status|stale_after):' wiki/*.md` — nur §3-Felder; `grep -nE 'resource:' wiki/*.md` — jeder Wert existierender `/`-getrennter `raw/`-Pfad.
|
||||
|
||||
**Manual checks (if no CLI):**
|
||||
- Belegte Aussage → Inline-`raw/`-Verweis; Übernahme → Kontext-Marker („übernommen aus … auf Basis von …, nicht eigenständig belegt").
|
||||
- `sources`-`id` je Concept eindeutig; keine unautorisierten Keys; `schema/compiler.md` rein textuell (D-3), deterministisch (AD-17h), referenziert den Vertrag.
|
||||
- `wiki/log.md` enthält datierten Nachrüst-Eintrag inkl. Diagramm-Quell-Deklaration.
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Instruktions-Basis (§5.5 Claim-granulare Provenienz — der Einstiegspunkt)**
|
||||
|
||||
- Konvention: Inline-`raw/`-Verweis je belegter Aussage, Kontext-Marker je Übernahme, `id`-Scoping — der verbindliche Standard für alles Folgende.
|
||||
[`compiler.md:66`](../../schema/compiler.md#L66)
|
||||
|
||||
- Selbsttest-Formel & Sicherstellung der Grep-Auffindbarkeit (AD-17h).
|
||||
[`compiler.md:76`](../../schema/compiler.md#L76)
|
||||
|
||||
- Revisionslog dokumentiert Nachrüstung (1.5) und Review-Patch-Runde (1.6).
|
||||
[`compiler.md:188`](../../schema/compiler.md#L188)
|
||||
|
||||
**Nachkonformierte Concept-Bodies (die eigentliche Provenienz-Arbeit)**
|
||||
|
||||
- Belegte Aussagen mit vollem `raw/`-Verweis; Diagramm als Direktübernahme aus `raw/architecture-spine/…` mit Marker; Forward-Referenz auf Epic 3.
|
||||
[`knowledge-kompilation-inkrementell.md:37`](../../wiki/knowledge-kompilation-inkrementell.md#L37)
|
||||
|
||||
- SoC-Diagramm als Direktübernahme aus `raw/prd/…` (§ 8.3) mit Marker; FR-16-Beleg auf PRD § 4.5 allein (Relokations-Regel eingehalten).
|
||||
[`wissensarchitektur-trennung-states.md:30`](../../wiki/wissensarchitektur-trennung-states.md#L30)
|
||||
|
||||
- Datenfluss-Diagramm als Direktübernahme aus `raw/prd/…` (§ 0 Document Purpose); PRD-Attribution über Sektionstitel (keine s-Fragmente).
|
||||
[`llm-wiki-prinzip.md:40`](../../wiki/llm-wiki-prinzip.md#L40)
|
||||
|
||||
**Bundle-Index & Nachweisführung**
|
||||
|
||||
- `index.md`-Beschreibungen mit `(aus <raw-Pfad>)` inkl. Diagramm-Quellen.
|
||||
[`index.md:29`](../../wiki/index.md#L29)
|
||||
|
||||
- `log.md`-Nachrüst-Eintrag (Vertrag §5-Format) inkl. Diagramm-Quell-Deklaration.
|
||||
[`log.md:4`](../../wiki/log.md#L4)
|
||||
|
||||
- Defer-Kontext: sources-Closure-Verifikation (jeder inline-referenzierte `raw/`-Pfad ⊆ `sources`) für spätere Fokussierung.
|
||||
[`deferred-work.md:196`](./deferred-work.md#L196)
|
||||
|
||||
- Story-Status `done` (bmad-code-review 2026-08-17 abgeschlossen, alle Findings aufgelöst; Human-Review-Freigabe in dieser Review-Runde).
|
||||
[`sprint-status.yaml:47`](./sprint-status.yaml#L47)
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: 'Concepts verlinken — eine erlaubte Linkform (Story 2.3)'
|
||||
type: 'feature'
|
||||
created: '2026-08-17'
|
||||
status: 'done'
|
||||
review_loop_iteration: 2
|
||||
baseline_commit: 7e1f449bf78741bb6739d8f510f3ab5543617fef
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-2-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Die Link-Schicht von `wiki/` existiert bisher nur in `index.md`; AD-7b/A0-9 („genau eine Form: bundle-relativ, mit oder ohne Endung — nie beide") ist noch formal offen — `schema/compiler.md` (§5.3 Pkt.3, §5.5 Pkt.1) und `schema/validator.md` (Punkt 11, §8) tragen alle die Klausel „Festlegung ist Story 2.3". Zwei Producer könnten aus demselben Baum unterschiedliche IDs berechnen; es existieren noch keine Concept-zwischen-Concept-Links (AD-8).
|
||||
|
||||
**Approach:** Die Linkform wird auf **bundle-relativ mit `.md`-Endung** gepinnt (alle 3 bestehenden Concept-Links in `wiki/index.md` sind bereits in dieser Form → Null-Migration; die 3 `../schema/`-Links in `index.md` liegen außerhalb des Pin-Wirkungsbereichs (andere Schicht) und bleiben unberührt; Ziele sind explizite Dateien, auch mit Areas eindeutig; Standard-Markdown-Tools lösen ohne Konventionswissen auf, AD-8). Gepinnt wird die Form in `schema/compiler.md` (neue §5.6 + re-executierbare Selbsttest-Formeln + Auflösung der „bis Story 2.3"-Klauseln); demonstriert in zwei inhaltsbasierten Cross-Links in **einem** Concept-Body (`wiki/wissensarchitektur-trennung-states.md` — die Ziel-Concepts werden nicht mutiert, da keine inhaltsbegründete Gegenverbindung besteht: keine erzwungene Gegenseitigkeit, AD-8); dokumentiert in `wiki/log.md`. Der Validator bleibt strukturell unverändert (Präzedenz Story 2.2, D-3; Punkt 11 prüft weiter nur das Vorhandensein von Links).
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- Gepinnte Form: `[<text>](<bundle-relativer Pfad mit `.md`-Endung>)` — genau eine Form; Ziel = Concept-OKF-Identität (AD-7a) + `.md` (AD-7b, A0-9). Links gehören in Concept-Bodies und `wiki/index.md`; Body-Links ändern keine Aussagen, `sources` oder Frontmatter (Navigations-/Beziehungsschicht ≠ Provenienz, AD-8).
|
||||
- `schema/compiler.md` ist einziger Instruktions-Ort (D-3): neue §5.6 „Concept-Links (Story 2.3)" — Pin, Geltungsbereich (Concept-Links + `index.md`-Links; `raw/`-Provenienz-Verweise nach §5.5 bleiben in Plain-/Komma-Form, andere Schicht), Selbsttest-Formeln (re-executierbar, AD-17h), Worked Example; die „bis Story 2.3"-Klauseln in §5.3 Pkt.3 und §5.5 Pkt.1 werden auf §5.6 referenziert; §7-Selbstbegrenzung-Bullet umformuliert; §8-Revisionslog (1.8) + Normreferenzen (AD-7b/AD-8, A0-9, FR-10).
|
||||
- **§5.6-Inhalts-Pflichten (Verifikations-Vertrag):** §5.6 MUSS enthalten — (a) exakt eine Pin-Zeile in der oben gepinnten Form, gerendert ohne verschachtelte Backticks (innerer Code-Fence = Anführungszeichen, kein zweites Backtick-Paar); (b) Geltungsbereich = Concept-Bodies + `wiki/index.md`; explizit ausgenommen: `raw/`-Provenienz-Verweise (§5.5, andere Schicht), `../schema/`-Links, `http`-Links, **Gleichseit-Anker `(#…)`** (Form-Check und Dangling-Check exkludieren Anker); (c) **vier** re-executierbare Selbsttest-Formeln — Bestands-Check, Form-Check (erwartet `0`), Dangling-Check (erwartet keine Ausgabe), **Kontakt-mit-`raw/`-Unverändert-Check** (deterministische Baseline-Extraktion aus `baseline_commit` via `git show`, AD-17h — keine „identisch zur X-Baseline"-Behauptung ohne extrahierbare Baseline); alle vier Formeln deterministisch re-executierbar (AD-17h) und bei `wiki/`-Area-Subtree (Story 2.4/2.5) lauffest (rekursive Erfassung, keine künftigen Area-Concepts verpasst); (d) NFR-4-Regel: jede Form-Verletzung → Run-FAIL mit textuell benannter Ursache; (e) Worked Example (gepinnter Link + Form-Check-Auflösung). Die Formeln sind so zu halten, dass die §6.6-Referenztabellen (`Positiv-/Negativ-Beispiele`) eine §5.6-Zeile tragen können (✓-Vorgabe / ✗-Formfehler → deterministische Ursache).
|
||||
- Body-Cross-Links inhaltsbegründet (nicht mechanisch): `wiki/wissensarchitektur-trennung-states.md` → `llm-wiki-prinzip.md` (das Wiki-Concept ist der Gegenstand des Architektur-States „curated bundle") und → `knowledge-kompilation-inkrementell.md` (die Kompilation realisiert die Trennung); jeweils ein kurzer Kontextsatz an semantisch passender Stelle. Die Kontextsätze sind **§5.5-konform zu formulieren**: jede darin belegte Aussage trägt entweder einen Inline-`raw/`-Verweis oder einen Kontext-Marker („… nicht eigenständig belegt") — keine unbelegte neue Behauptung im Body.
|
||||
- `wiki/log.md`: datumsgruppierter Eintrag (Vertrag §5-Format, neueste zuerst). Der Eintrag MUSS die Tatsachen des Runs abbilden: (a) Formel-Zählung identisch mit §5.6 (vier Selbsttest-Formeln); (b) `sprint-status.yaml`-Statuswechsel `2-3-…` `backlog` → `in-progress` **dokumentieren** (dieser findet statt — kein „bereits in-progress"); (c) `raw/`-Unverändert-Beleg als extrahierbare Baseline-Aussage (Zahl + `baseline_commit`), nicht als bloße „identisch"-Behauptung. `sprint-status.yaml`: Key `2-3-…` → `in-progress`.
|
||||
- **Evidenz-Auflösung (re-executierbar, AD-17h):** Jede im Code Map / Verification / log-Eintrag stehende Zählung-Behauptung über den Ausgangszustand ist an `baseline_commit` (Frontmatter) zu extrahieren — z. B. `git show 7e1f449:wiki/index.md` für den Link-Bestand, `git show 7e1f449:… | grep` für `raw/`-Treffer — keine freistehende Zahl ohne extrahierbare Quelle.
|
||||
|
||||
**Ask First:** Andere Pin-Wahl (mit vs. ohne `.md`) · irgendeine Änderung an `schema/validator.md` (Punkt-11-Einschränkung, neue §7-Klasse) · neue Concepts/Areas (Story 2.4/2.5).
|
||||
|
||||
**Never:** Änderung an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` (AD-3; der Validator akzeptiert bis auf Weiteres beide Formen — Einschränkung wäre eigene Autorisierung) · Links in Frontmatter/`sources` (AD-4b) · neue §7-Invaliditätsklasse · Standalone-Tool (D-3) · Vorwegnahme Area-Zuordnung/Discovery (Story 2.4/2.5) · Renames (AD-7d) · OKF-Dialekt.
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| HAPPY_PATH | Bundle nach dem Pin | Genau eine Linkform in `wiki/`; 2 neue Body-Links auflösbar; Validator-Lauf SUCCESS (5 `wiki/`-Dateien) | N/A |
|
||||
| FORMVERLETZUNG | Concept-Link ohne `.md` (oder Mischform) | Selbsttest-Formel (Pkt. 3, Form-Check) trifft deterministisch; Link wird korrigiert oder entfernt, bevor veröffentlicht | Run-FAIL textuell benannt (NFR-4) |
|
||||
| DANGLING_LINK | Body-Link auf nicht existente `wiki/`-Datei | Dangling-Formel (Pkt. 3) trifft; Link wird korrigiert oder entfernt | Run-FAIL textuell benannt (NFR-4) |
|
||||
| GLEICHSSEIT_ANKER | Gleichseit-Anker-Link `(#…)` im Body | von Form-Check und Dangling-Check exkludiert — keine falsche FAIL/Dangling-Meldung; bleibt außerhalb des Pins | N/A |
|
||||
| KONTAKT_MIT_RAW | `raw/`-Provenienz-Verweis (§5.5) im Body | bleibt in Plain-/Komma-Form — der Pin berührt ihn nicht (Selbsttest-Formel `\(raw/` ergibt unveränderte Ausgabe zur `baseline_commit`-Extraktion) | N/A |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/compiler.md` — **mutiert**: neue §5.6 „Concept-Links (Story 2.3)" (Pin, Geltungsbereich, Selbsttest-Formeln, Worked Example) nach §5.5, vor §6 (L123); „bis Story 2.3"-Klauseln in §5.3 Pkt.3 (L62) und §5.5 Pkt.1 (L78) → Verweis auf §5.6; §7-Bullet (L174); §8-Revisionslog (L198 → Eintrag 1.8) + Normreferenzen (AD-7b/AD-8, A0-9, FR-10).
|
||||
- `wiki/wissensarchitektur-trennung-states.md` — **mutiert**: 2 Body-Cross-Links (→ `llm-wiki-prinzip.md`, → `knowledge-kompilation-inkrementell.md`) je mit kurzem Kontextsatz; ansonsten unverändert.
|
||||
- `wiki/llm-wiki-prinzip.md`, `wiki/knowledge-kompilation-inkrementell.md` — **mutiert nur bei** inhaltsbegründeter Gegenrichtung; sonst unverändert.
|
||||
- `wiki/index.md` — **read-only (konform)**: die 3 Concept-Links (L29–31) sind bereits in der gepinnten Form (`.md`) → kein Change; die 3 `../schema/`-Links (L33) liegen außerhalb des Pin-Wirkungsbereichs (andere Schicht) → kein Change; Punkt-11-Check.
|
||||
- `wiki/log.md` — **append**: Eintrag unter `## 2026-08-17`.
|
||||
- `schema/wiki-compiler.md` (L58: AD-8 Navigations-Schicht), `schema/validator.md` (Punkt 11, L70; §8, L297 — „Story 2.3"-Notiz bleibt) — **read-only**.
|
||||
- `raw/architecture-spine/…` (AD-7b L246–248, AD-8 L260–268), `raw/epics/…` (A0-9 L57) — **read-only Evidenz**.
|
||||
- `_bmad-output/implementation-artifacts/deferred-work.md` (L66–68: der Linkform-Eintrag, aktuell ohne `status:`-Zeile) und `sprint-status.yaml` (L48) — **mutiert** (Eintrag schließen / Status).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/compiler.md` — neue §5.6 „Concept-Links (Story 2.3)": Pin (`…/.md`), Geltungsbereich + `raw/`-Exklusion, 4 Selbsttest-Formeln (bestands-, form-, dangling-, `raw/`-Unverändert-Check; re-executierbar), Worked Example; „bis Story 2.3"-Klauseln (§5.3 Pkt.3, §5.5 Pkt.1) auf §5.6 umformuliert; §7-Bullet angepasst; §8-Revisionslog 1.8 + Normreferenzen — AD-7b/AD-8/A0-9, D-3, AD-17h.
|
||||
- [x] `wiki/wissensarchitektur-trennung-states.md` — 2 inhaltsbegründete Cross-Links in der gepinnten Form, je ein kurzer Kontextsatz (Link = Navigation, keine Provenienz-Änderung).
|
||||
- [x] `wiki/log.md` — Eintrag: Pin-Entscheidung (mit `.md`; Rationale: Null-Migration, explizite Datei-Ziele, Standard-Tools), veränderte Dateien, Validator-Lauf-Ergebnis.
|
||||
- [x] `sprint-status.yaml` — `2-3-…` → `in-progress`.
|
||||
- [x] `deferred-work.md` — Eintrag L66–68 um `status:`-Zeile schließen (Format wie die bestehenden `status: umgesetzt (…)`-Einträge).
|
||||
- [x] Verifikation — alle Formeln aus der Verification-Sektion re-executieren + Validator-Lauf (5 `wiki/`-Dateien SUCCESS).
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given zwei zusammengehörige Concepts, when eine Beziehung ausgedrückt wird, then nutzt sie einen normalen Markdown-Link in genau einer erlaubten Form — bundle-relativ mit `.md`-Endung (AD-7b, A0-9).
|
||||
- Given der Link-Form-Standard, when ein Consumer die Links traversiert, then sind die Ziel-Concepts ohne Wiki-Software auffindbar (alle internen Links auflösen; FR-10, AD-8).
|
||||
- Given ein Link, when er gespeichert wird, then verändert er weder Concept-Inhalt noch `sources`/Frontmatter (Selbsttest-Formel `\(raw/` liefert identische Ausgabe wie vor der Änderung).
|
||||
- Given die Instruktion, when geprüft, then §5.6 pinnt die Form, die Selbsttest-Formeln sind deterministisch re-executierbar (AD-17h), Validator/Vertrag/`raw/` sind unverändert und das Bundle bleibt Validator-SUCCESS (keine neue §7-Klasse).
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- **2026-08-17 (Erstellung):** Initiale Approve-Baseline.
|
||||
- **2026-08-17 (bmad-code-review, Review-Runde):** Review-Schärfungen (Blind-Hunter + Edge-Case-Hunter) — **Patch 1:** Formel-2-(Form-Check)-Exklusions-Stufe `grep -vE '^\.'` ergänzt (Ziele mit `./`-Präfix definiert aus dem Pin ausgenommen statt still als „interne `.md`-Form" durchzugehen) + Dangling-Formel-3-`case` um `./*|/*` erweitert; beide Formeln byte-identisch in `compiler.md` §5.6 gespiegelt (5/5-Identität). **Patch 2:** bad_spec-Zeile um Scope-Klarstellung der Zählungen ergänzt (30 = `log.md`-exkludierte Vorkommen-gepinnte Baseline; 34 = inkl. `log.md`; 28 = Zeilen-Metrik — verschiedene Metriken, kein Widerspruch). Verifikation nach Patch: alle vier Formeln re-executiert (Bestands `8`, Form `0`, Dangling ∅, `raw/` `30≡30`). Defer-Findings → `deferred-work.md`.
|
||||
- **2026-08-17 (Loop 1, Step-04-Review, bad_spec):** Auslösender Befund: Die Verification-Zeile `KONTAKT_MIT_RAW`-Baseline behauptete „identisch zur Story-2.2-Baseline (27 Treffer)". Die Zahl „27" war nicht re-executierbar (verstoß gegen AD-17h — Story-2.2-Zeitrechnung, zeilenbasiert inkl. `log.md`) und damit ein direkter Spezifikationsfehler (nicht nur ein Implementierungs-Fehler). **Scope-Klarstellung der extrahierbaren Zählungen (verschiedene Metriken, nicht Widerspruch):** (a) **30 Vorkommen** = `grep -oE '\(raw/'` über alle `wiki/`-Dateien **außer `log.md`** (diese Zahl pinnt die gepinnte Formel 4 und ist die Run-Baseline); (b) **34 Vorkommen** = derselbe `grep -oE '\(raw/'`-Scan **inkl. `log.md`** (log.md trägt 4 `(raw/`-Vorkommen, u.a. aus dem Story-2.2-Zitat); (c) **28 Treffer-Zeilen** = zeilenbasierte `grep -rnE '\(raw/'`-Zählung inkl. `log.md` (mehrere Vorkommen je Zeile). Die im Befund genannten „34 Vorkommen (28 Treffer-Zeilen)" beziehen sich auf den **inkl.-`log.md`-Scan**; die gepinnte, log.md-exkludierte Baseline ist **30**. **Geändert:** (1) Verification `KONTAKT_MIT_RAW`-Zeile auf deterministische Baseline-Extraktion aus `baseline_commit` umgestellt (`git show 7e1f449:… | grep -oE '\(raw/' | wc -l` → **30** Vorkommen, `log.md`-exkludiert; aktuell ≡ Baseline), keine freistehende Zahl; der inkl.-`log.md`-Scan ergibt baseline wie aktuell **34** (kein Pin-Treffer, nur Doku-Zitat); (2) Approach-Überbehauptung „alle 6 bestehenden Links sind bereits in dieser Form" korrigiert zu „alle 3 bestehenden Concept-Links in `index.md`" (die 3 `../schema/`-Links liegen außerhalb des Pin-Wirkungsbereichs); (3) Approach „demonstriert in zwei … Concept-Bodies" korrigiert zu „in **einem** Concept-Body" (nur `wissensarchitektur-trennung-states.md` mutiert — keine erzwungene Gegenseitigkeit, AD-8); (4) I/O-Matrix `FORMVERLETZUNG` um „oder entfernt" ergänzt und Falsch-Verweis „(Pkt. 2 unten)" → „(Pkt. 3, Form-Check)"; neue Matrix-Zeile `GLEICHSSEIT_ANKER`; (5) Always-Bullets um §5.6-Inhalts-Pflichten (vier Formeln inkl. `raw/`-Unverändert-Check mit extrahierbarer Baseline; Anker-Exklusion; Area-robustheit; §5.5-konforme Kontextsätze; log-Eintrag dokumentiert den `sprint-status`-Wechsel und die extrahierbare `raw/`-Baseline) und um Evidenz-Auflösungs-Pflicht (Zählungen an `baseline_commit` extrahieren); (6) Code Map `index.md` um `../schema/`-Ausnahme präzisiert. **Vermeideter Known-Bad-State:** eine Spezifikation, die eine nicht re-executierbare Zählung (27) als Baseline nennt und damit die AD-17h-Determinismus-Eigenschaft des eigenen Artefakts verletzt. **KEEP-Instructions (positive Erhaltung bei Re-Derivation):** (a) Pin-Form `bundle-relativ mit .md` und deren Rationale (Null-Migration der 3 Concept-Links, explizite Datei-Ziele, Standard-Tools) — unverändert beibehalten; (b) die drei Kern-Selbsttest-Formeln (Bestands-/Form-/Dangling-Check) in der bewährten, negativ-geprüften `sh -c`-Form — beibehalten, um `raw/`-Unverändert-Check (vierte Formel) ergänzt; (c) „Validator/Vertrag/`raw/` unverändert, keine neue §7-Klasse, kein Standalone (D-3)" — strikt beibehalten; (d) §5.6 als einziger Instruktions-Ort (D-3) — beibehalten; (e) die 2 inhaltsbegründeten Cross-Links (ohne erzwungene Gegenseitigkeit) — beibehalten, Kontextsätze jedoch §5.5-konform (Inline-`raw/`-Verweis oder Kontext-Marker) zu formulieren.
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands (re-executierbar, ab Workspace-Root; alle vier Formeln AD-17h-konform und negativ-geprüft):**
|
||||
|
||||
Alle Formeln scannen `wiki/` rekursiv (künftige Area-Concepts unter `wiki/<area>/`, Story 2.4) und exkludieren `log.md` (Dokumentation, keine Link-/Provenienz-Schicht — sie enthält die Formel-Texte selbst als Zitate und würde die Zählungen verunreinigen).
|
||||
|
||||
1. **Bestands-Check** (Link-Überblick):
|
||||
`sh -c "grep -roE ']\([^)]*\)' --include='*.md' --exclude=log.md wiki/"`
|
||||
— erwartet: 6 `index.md`-Links (3 Concept mit `.md`, 3 `../schema/`) + 2 neue Body-Links (beide `.md`); alle internen Concept-Ziele `*.md`. (`[^)]*` statt `[^)]+` — leere Ziele `]()` werden sichtbar statt unsichtbar.)
|
||||
|
||||
2. **Form-Check** (erwartet Ausgabe `0`, Exit `0`):
|
||||
`sh -c "grep -rohE ']\([^)]*\)' --include='*.md' --exclude=log.md wiki/ | sed -E 's/^\]\(//; s/\)$//' | sort -u | grep -vE '^(raw/|\.\./|#)' | grep -vE '^\.' | grep -vE ':' | grep -cvE '^[^#]+\.md$' || true"`
|
||||
— jeder interne Link in der gepinnten Form (`.md`-Endung); exkludiert: `raw/`-Provenienz (§5.5, andere Schicht), `../schema/`, `./`-Präfix-Ziele (`^\.` — nicht root-relativ/keine Bundle-Pfad-Form), externe Ziele (alle mit `:` — `http://`, `https://`, `mailto:`, protocol-less Hostnamen; interne OKF-Ziele sind Kebab-Case und enthalten nie `:`), Gleichseit-Anker `(#…)`. `|| true` bindet den Exit-Code (grep `-c` liefert Exit `1` bei Ausgabe `0` — die *gewünschte* SUCCESS-Konfiguration). Negativ-geprüft: fehlende `.md`-Endung liefert `1`; `mailto:`/`https://` exkludiert; `]()` wird gezählt. (Cross-Page-Anker `file.md#sec` werden weiterhin gezählt — normative Frage, s. `deferred-work.md`.)
|
||||
|
||||
3. **Dangling-Check** (erwartet keine Ausgabe):
|
||||
```sh
|
||||
sh -c 'grep -rohE "]\([^)]*\)" --include="*.md" --exclude=log.md wiki/ | sed -E "s/^\]\(//; s/\)$//" | sort -u | while read -r t; do case "$t" in ""|*:*|raw/*|../*|./*|/*) if [ "$t" = "" ]; then echo "DANGLING: (leeres Ziel)"; fi; continue;; esac; case "$t" in "#"*) continue;; esac; p=${t%%#*}; [ -f "wiki/$p" ] || echo "DANGLING: $t"; done'
|
||||
```
|
||||
— jedes interne Ziel existiert relativ zum Bundle-Root (bundlerelativ — das Auflösungsmodell des Bundles, AD-7b); Fragment wird vor dem Existenztest gestripped (`file.md#sec` → `file.md`, kein falscher `DANGLING` für existierende Ziele — die Pin-Form-Frage bleibt beim Form-Check); exkludiert wie beim Form-Check; leere Ziele `]()` werden als `DANGLING: (leeres Ziel)` gemeldet, nicht still exkludiert. Negativ-geprüft: nicht existierendes Ziel liefert `DANGLING: <pfad>`; `]()` liefert `DANGLING: (leeres Ziel)`; `https://…`/`#anker` exkludiert; `concepts.md#s1` (existierende Datei) liefert **keine** Ausgabe. (Bekannt-konservativ: Ziele mit `)` werden am ersten `)` abgeschnitten → falsch benannte Ursache, aber keine Stille — dokumentiert in `deferred-work.md`.)
|
||||
|
||||
4. **Kontakt-mit-`raw/`-Unverändert-Check** (aktuell ≡ Baseline, beide re-executierbar, AD-17h):
|
||||
- aktuell: `sh -c "grep -roE '\(raw/' --include='*.md' --exclude=log.md wiki/ | wc -l"`
|
||||
- Baseline an `baseline_commit` extrahiert (Dateimenge dynamisch aus dem Commit abgeleitet — keine handgelistete Pfadliste, keine Newline-Verbindungs-Abhängigkeit; **einschließende** Einzelanführungszeichen, damit `$f` erst im inneren Shell expandiert):
|
||||
`sh -c 'git ls-tree -r --name-only 7e1f449bf78741bb6739d8f510f3ab5543617fef -- wiki/ | grep -v "wiki/log.md$" | while read -r f; do git show "7e1f449bf78741bb6739d8f510f3ab5543617fef:$f"; done | grep -oE "\(raw/" | wc -l'`
|
||||
— beide Vorkommen-Zählungen müssen identisch sein (erwartet **30**; der Check setzt die unveränderte `wiki/`-Dateimenge voraus — gilt für diesen Run; bei Datei-Zuwachs in späteren Runs ist die Baseline-Extraktion neu durchzuführen). Der Pin berührt `raw/`-Provenienz-Verweise nicht. (Ersetzt die frühere, nicht re-executierbare Formulierung „identisch zur Story-2.2-Baseline (27 Treffer)" und die handgelistete 5-Datei-`git show`-Kette.)
|
||||
|
||||
5. **Validator-Lauf** (deterministisch, D-3 manuell-mechanisch): alle 5 `wiki/`-Dateien SUCCESS (Punkte 1/6/11/14, EC-1).
|
||||
|
||||
**Manual checks:**
|
||||
- Cross-Links inhaltsbegründet (Kontextsatz, keine erzwungene Gegenseitigkeit); Kontextsätze §5.5-konform (Inline-`raw/`-Verweis oder Kontext-Marker); keine Frontmatter-/`sources`-Änderung; `log.md`-Eintrag datiert, im Vertrag-§5-Format, dokumentiert den `sprint-status`-Wechsel und die extrahierbare `raw/`-Baseline; `sprint-status.yaml` und `deferred-work.md` konsistent.
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Pin & Selbsttest-Formeln (Konvention) — Einstieg**
|
||||
|
||||
- Der eigentliche Change: §5.6 mit Pin, Geltungsbereich, vier Formeln, NFR-4, Worked Example.
|
||||
[`compiler.md:123`](../../schema/compiler.md#L123)
|
||||
|
||||
- §6.6 trägt die §5.6-Zeile: ✓ gepinnte Form / ✗ fehlende `.md` → Run-FAIL.
|
||||
[`compiler.md:213`](../../schema/compiler.md#L213)
|
||||
|
||||
- Revisionslog 1.8/1.9: vollständige Änderungsgeschichte inkl. Loop-1-Schärfungen der Formeln.
|
||||
[`compiler.md:251`](../../schema/compiler.md#L251)
|
||||
|
||||
**Demonstration**
|
||||
|
||||
- Der Demonstrations-Run: zwei Cross-Links mit §5.5-konformem Kontext (L20, L22).
|
||||
[`wissensarchitektur-trennung-states.md:20`](../../wiki/wissensarchitektur-trennung-states.md#L20)
|
||||
|
||||
**Dokumentation & Tracking**
|
||||
|
||||
- Story-2.3-Eintrag: Rationale, `sprint-status`-Wechsel, `raw/`-Baseline (30 ≡ 30), Validator-Lauf.
|
||||
[`log.md:4`](../../wiki/log.md#L4)
|
||||
|
||||
- Linkform-Eintrag (spec-1-4) geschlossen; vier neue Defer-Einträge am Dateiende.
|
||||
[`deferred-work.md:69`](./deferred-work.md#L69)
|
||||
|
||||
- Statuswechsel `backlog` → `in-progress` (→ `review` mit diesem Schritt).
|
||||
[`sprint-status.yaml:48`](./sprint-status.yaml#L48)
|
||||
|
||||
### Review Findings (bmad-code-review 2026-08-17, 4 Layer)
|
||||
|
||||
**Patch (2):**
|
||||
- [x] [Review][Patch] Formel-Lücke `./`-Präfix & schemalose Hostnamen: `[x](./foo.md)`/`[x](example.com/foo.md)` bestehen Form-Check & Dangling-Check — verletzt "bundle-relativ", aber `.md`-Endung genügt. **→ §5.6-Pin-Zeile/Formel 2: Root-relative-Ausschluss ergänzen** [`schema/compiler.md:227`](../../schema/compiler.md#L227) — **umgesetzt**: Formel 2 um `grep -vE '^\.'`-Stufe ergänzt (Ausschluss `./`-Präfix), Dangling-`case` um `./*|/*`-Muster erweitert; Identität compiler↔spec verifiziert (5/5 Formeln byte-identisch); Positiv-Kontrolle nach Patch: Form-Check `0`, Dangling leer, Bestands `8`, `raw/`-Baseline `30≡30`. — **Revision 2.0** in `compiler.md` §8 (siehe Zusatz-Eintrag).
|
||||
- [x] [Review][Patch] spec Change-Log `34 Vorkommen (28 Treffer-Zeilen)` ohne Scope/Metrik — drei implizite Zahlen (27/30/34); re-executierbare Baseline **30** (log.md-exkludiert) widerspricht "34". Scope/Metrik (Inkl.-`log.md` + Vorkommen) an der bad_spec-Stelle offenlegen. [`spec-2-3-…md` Change Log](#spec-change-log) — **umgesetzt**: bad_spec-Zeile um Scope-Klarstellung ergänzt (30 exkl. `log.md` = gepinnte Baseline; 34 inkl. `log.md`; 28 Zeilen-Metrik).
|
||||
|
||||
**Defer (7):** Auf die Story-Datei folgen die Defer-Einträge in `deferred-work.md`; hier nur Zusammenfassung, Details dort.
|
||||
|
||||
- [x] [Review][Defer] `log.md`-Exklusions-Begründung "zitiert Formel-Texte" ist für Formeln 1–3 gegenstandslos (aktuell 0 `](`-Treffer in log.md); lasttragend nur für Formel 4 — dokumentarische Präzisierung Empfehlung [`schema/compiler.md:132`](../../schema/compiler.md#L132)
|
||||
- [x] [Review][Defer] Cross-Page-Defer-Eintrag beschreibt Prä-Patch-Dangling-Verhalten (`DANGLING: concepts.md#s1`) — Zieldatei existiert im aktuellen §5.6-Kern — inkonsistente Evidenz-Zeile [`deferred-work.md:221`](./deferred-work.md#L221)
|
||||
- [x] [Review][Defer] Image-/Non-Navigations-`](...)`: kein `
|
||||
- [x] [Review][Defer] Multi-Line-Ziele `](foo\nbar.md)` unsichtbar (Ein-Zeilen-Grep) — konservativer Vorbeilass, D-3-Konflikt [`schema/compiler.md:140`](../../schema/compiler.md#L140)
|
||||
- [x] [Review][Defer] Reference-Style-Links `[x][ref]`/`[ref]: ziel.md` unsichtbar — zweite Linkform detectable [`schema/compiler.md:140`](../../schema/compiler.md#L140)
|
||||
- [x] [Review][Defer] Leading-Space-Ziel `]( ziel.md)` wird als Form-konform UND vorhanden gewertet [`schema/compiler.md:146`](../../schema/compiler.md#L146)
|
||||
- [x] [Review][Defer] künftiges `wiki/<area>/log.md` bricht Baseline-Extraktion (Top-Level-Filter `wiki/log.md$`) [`schema/compiler.md:163`](../../schema/compiler.md#L163)
|
||||
+184
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: 'Deterministische Bereichszuordnung & Concept-Hierarchie (Story 2.4)'
|
||||
type: 'feature'
|
||||
created: '2026-08-18'
|
||||
status: 'done'
|
||||
review_loop_iteration: 2
|
||||
baseline_commit: 66451b6e6c9e139fb3aa3bbf4b01291e1e2d273a
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-2-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Die Ziel-Pfad-Regel (§5.1) erzwingt noch konzeptlos alle neuen Concepts auf Root-Ebene ("Area-Zuordnung ist Story 2.4") — es gibt keine deterministische Regel, wohin ein erkanntes Thema gehört (AD-7c/A0-10 sind offen); die §5.6-Linkformeln exkludieren `../`-Ziele pauschal und wären für Area-Pfade nicht renderer-konform (offenes Deferred, Home Story 2.4).
|
||||
|
||||
**Approach:** Neue §5.7 „Deterministische Bereichszuordnung & Concept-Hierarchie" in `schema/compiler.md`: Bereichszuordnung textual-deterministisch ((a) First-Class-Link aus dem bestehenden `index.md`-Baum, sonst (b) Root-Ebene; nie Embedding/Vector — AD-7c/AD-13), kanonische ID-Normalisierung (AD-7a), §3.2-Kollisions-Hold für Top-Level-Konflikte (A0-10, kein neues Prädikat), file-relatives Link-Auflösungsmodell (eine syntaktische Form, `../`-fähig; §5.6-Formeln area-fest). §5.1/§5.3/§7/§8/§6.6 nachgeführt. Demo: neue Area `wiki/wissensarchitektur/` (frontmatterloser Area-`index.md` + ein neues Area-Concept aus `raw/` mit `../`-Links auf Root-Concepts) + Negativ-Test der Kollision im Sandbox-Baum; kein MOVE bestehender Concepts (Kuratierung/AD-7d ist Epic-3-Nähe, nicht in den ACs).
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- Bereichszuordnung ist **textual-deterministisch** ((a) bestehender `index.md`-Link gibt den Bereich vor; (b) Default Root-Ebene), nie Embedding/Vector (AD-7c, A0-10, AD-13). Die Regel wird als Instruktion in **§5.7** verankert — einziger Instruktions-Ort (D-3); keine Vertrags-/Validator-Änderung (§-Struktur wie Story 2.2/2.3-Präzedenz). Validator Punkt 11 akzeptiert bereits Areas (Area-`index.md`, verlinkt im nächsten Vorfahren) — strukturell unverändert.
|
||||
- Identität = relativer OKF-Pfad ohne `.md` (AD-7a): `wiki/spring/index.md` → `spring`, `wiki/<area>/<concept>.md` → `<area>/<concept>`; genau eine Normalisierung. Eine als Area gedachte Anlage (`wiki/<area>/index.md` + Concept darunter) ist ab dieser Story **konform**, nicht mehr Bereichs-Hinweis.
|
||||
- **Link-Auflösungsmodell (löst §5.6-Defer):** Concept-Links sind **file-relativ** zur `.md`-Datei — eine syntaktische Form (bundle-relativ = identisch bei Root-Dateien; `../` für Aufwärts-Ziele innerhalb `wiki/`; `.md`-Endung bleibt Pflicht). §5.6-Formeln 2/3 exkludieren `../` **nicht mehr pauschal**, sondern validieren `../`-Ziele als in-Bundle-Aufwärts-Pfade (Quell-Verzeichnis relativ, Ziel muss unter `wiki/` liegen). `../schema/` bleibt anderer Schicht (exkludiert). Dangling-Auflösung: Existenztest relativ zum Bundleroot nach `../`-Auflösung.
|
||||
- Neue Area `wiki/wissensarchitektur/`: `index.md` **frontmatterlos** (Vertrag §2, Punkt 10), verlinkt die Area-Concepts in gepinnter Form (§5.6); neues Area-Concept `source-material.md` (`type: concept`, `sources` → `raw/architecture-spine/…`/`raw/prd/…`, §5.5-Inline-Verweise), Body-Links zu Root-Concepts im file-relativem `../`-Format (`[LLM-Wiki-Prinzip](../llm-wiki-prinzip.md)` u. ä.), inhaltsbegründet. Root-Concept `wissensarchitektur-trennung-states.md` bleibt unverändert auf Root.
|
||||
- `wiki/index.md`: neue Area-Sektion verlinkt `wissensarchitektur/index.md` (Navigation Root → Area, AD-9); bestehende Root-Links unverändert. `wiki/log.md`: Eintrag (Vertrag-§5-Format) mit Area-Anlage, neuem Concept, `sprint-status`-Wechsel `2-4-…` `backlog` → `in-progress`.
|
||||
- §5.6-Formel-4-Basislinie: Dieser Run ist ein expliziter „Datei-Zuwachs"-Run (neue Area-Dateien) — die „unveränderte Dateimenge"-Voraussetzung ist per §5.6-Text für diesen Run nicht erfüllt; die Baseline-Extraktion wird auf den neuen Baum (dieser Spezifikations-`baseline_commit`) neu durchgeführt und im log-Eintrag/Zählung dokumentiert. Kein Widerspruch zu §5.6-Text (dieser sieht den Zuwachs-Fall ausdrücklich vor).
|
||||
- `deferred-work.md`: die Story-2.4-benannten Defer-Einträge (bundlerelative Area-Auflösung; ggf. Cross-Page-Anker) erhalten `status:`-Zeile geschlossen bzw. dokumentarisch korrigiert (append-only; bestehende Einträge unverändert). `sprint-status.yaml`: Key `2-4-…` → `in-progress`.
|
||||
- Negativ-Test im Sandbox-/tmp-Baum: Erstellungskandidat mit Top-Level-ID-Kollision (z. B. `llm-wiki-prinzip`) löst den **§3.2-Hold** aus („Concept existiert bereits — Aktualisierung ist Epic 3"), kein stiller Overwrite, keine Index-Verlinkung.
|
||||
|
||||
**Ask First:** Andere Pin-Wahl als file-relativ (`../`-fähig) · MOVE/Neuzuordnung bestehender Concepts (AD-7d) · Änderung an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` · neue Areas über die eine Demo-Area hinaus · Standalone-Tool.
|
||||
|
||||
**Never:** Veränderung an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` (AD-3) · neuen §7-Invaliditätsklasse · Vorwegnahme progressiver Discovery-Indizes/Navigation (Story 2.5) · Renames/Redirects (AD-7d) · Embedding/Vector-Infrastruktur (AD-13) · OKF-Dialekt.
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| HAPPY_PATH | Bundle + neue Area `wissensarchitektur/`, neues Area-Concept `source-material.md` | Area-`index.md` (frontmatterlos) verlinkt das Concept; Root-`index.md` verlinkt die Area; `../`-Body-Links lösen in Renderern und Dangling-Check auf; Validator SUCCESS (6 `wiki/`-Dateien) | N/A |
|
||||
| TOP_LEVEL_COLLISION | Erstellungskandidat mit ID = bestehendem Root-Pfad (`llm-wiki-prinzip`) | §3.2-Kollisions-Hold: kein Overwrite, kein Index-Link, keine Datei; Run „teilweise erfolgreich"/textueller Hinweis | N/A (Hold-Verhalten fixiert, §3.2) |
|
||||
| AREA_WITHOUT_INDEX | `wiki/<area>/` ohne `index.md` | validator Punkt 11 FAIL („Area ohne index.md=…") — Anlage ohne Area-Index ist strukturell invalide | Run-FAIL, textuelle Ursache (NFR-4) |
|
||||
| DEEP_LINK_UP | Body-Link `../llm-wiki-prinzip.md` aus `wiki/wissensarchitektur/source-material.md` | Form-Check `0`; Dangling: Auflösung relativ zum Quell-Verzeichnis → `wiki/llm-wiki-prinzip.md` existiert → keine Ausgabe | `../schema/…` weiterhin exkludiert (andere Schicht) |
|
||||
| DIVING_NON_EXISTENT | `../fehlt.md` aus Area-Concept | Dangling-Check meldet `DANGLING: ../fehlt.md` | Run-FAIL textuell benannt |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/compiler.md` — **mutiert**: neue **§5.7** „Deterministische Bereichszuordnung & Concept-Hierarchie (Story 2.4)" (nach §5.6, vor §6): (1) Routing-Regel textual-deterministisch (index.md-Erst-`Link` → Bereich, sonst Root; AD-7c/A0-10/AD-13), (2) kanonische ID-Normalisierung (AD-7a, Beispieltabelle `wiki/<area>/index.md` → `<area>`), (3) Kollisions-Hold → Verweis auf fixierten §3.2 (kein neues Prädikat, A0-10), (4) Link-Auflösungsmodell file-relativ (`../`-fähig, eine Form) + Formel-2/3-`../`-Schärfung, (5) Worked Example Area-Concept; **§5.1 Pkt.1** umgeschrieben (Root-Formel → Verweis auf §5.7; „Area-Zuordnung ist Story 2.4"-Backlog-Klausel aufgelöst); **§5.3 Pkt.3** (Area-Concept → Link in Area-`index.md` statt Bundleroot); **§5.6 Pkt.2/3** (Geltungsbereich/Auflösung `../` präzisiert, Formel-2-Exklusions-Liste + Formel-3-`case` um `../`-in-Bundle-Auflösung ergänzt; **Containment nach dem Loop-1-Review: Formel 3 MUSS Out-of-Bundle-Ausbruch über `..`-Traversale sperren** — ein Ziel `../[^./]…` (bzw. nach Auflösung unter `wiki/`) ist zulässig als in-Bundle-Aufwärts-Pfad, ein Ziel, dessen `..`-Auflösung **nicht** unter `wiki/` bleibt, MUSS als `DANGLING` gemeldet werden); **§5.6 Pkt.4 (Formel-4-Neu-Baseline)** muss die Baseline **aus dem `baseline_commit`-Kopf dieser Spezifikation** (`66451b6e6c9e139fb3aa3bbf4b01291e1e2d273a`) extrahieren, nicht aus dem Story-2.3-`7e1f449…`; **§5.7 Pkt.5** meldet eine Area ohne `index.md` **wörtlich** als `FAIL … Punkt 11: Index-Regel verletzt (Area ohne index.md=…)` (kein inventiertes `AREA_WITHOUT_INDEX`-Label); **§6.6** `§5.1`-Zeile angepasst (`wiki/<area>/<slug>.md` konform; Bereichs-Hinweis-Zelle entfällt); **§7**-Bullet „Deterministische Area-Zuordnung" von „verbleibt Story 2.4" → „in §5.7 verankert"; **§8**-Revisionslog 2.1 + Normreferenzen AD-7c/A0-10.
|
||||
- `wiki/wissensarchitektur/index.md` — **neu**: Area-`index.md`, frontmatterlos, verlinkt `source-material.md` (gepinnte Form).
|
||||
- `wiki/wissensarchitektur/source-material.md` — **neu**: Area-Concept, `type: concept`, `sources` → `raw/architecture-spine/architecture-spine-2026-08-14.md` (+ ggf. `raw/prd/prd-wow20-2026-08-14.md`), §5.5-Inline-Verweise, `../`-Links auf Root-Concepts.
|
||||
- `wiki/index.md` — **mutiert**: Area-Sektion verlinkt `wissensarchitektur/index.md`; bestehende Root-Links unverändert.
|
||||
- `wiki/log.md` — **append**: Eintrag (Area-Anlage, neues Concept, §5.6-Formel-4-Neu-Baseline, `sprint-status`-Wechsel, Negativ-Test-Hold-Nachweis).
|
||||
- `_bmad-output/implementation-artifacts/sprint-status.yaml` — **mutiert**: `2-4-deterministische-bereichszuordnung-concept-hierarchie` → `in-progress`.
|
||||
- `_bmad-output/implementation-artifacts/deferred-work.md` — **mutiert**: Story-2.4-Defer (bundlerelative Area-Auflösung) `status: umgesetzt (…)`-Zeile; Cross-Page-Anker-Eintrag dokumentarisch auf Ist-Verhalten korrigiert (append-only, keine bestehende Zeile ändern außer Status-/Korrektur-Fall).
|
||||
- `schema/wiki-compiler.md` (Punkt 11, §6), `schema/validator.md`, `raw/…` — **read-only** (AD-3).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/compiler.md` — §5.7 (Routing, ID-Normalisierung, Hold-Verweis, file-relativ-Auflösung + Formel-2/3-`../`-Schärfung, Worked Example); §5.1/§5.3/§5.6/§6.6/§7/§8 nachgeführt. Kein Schema-/Validator-/raw-Change.
|
||||
- [x] `wiki/wissensarchitektur/index.md` + `wiki/wissensarchitektur/source-material.md` — anlegen; Area-Index frontmatterlos, Concept §5.5-konform, `../`-Links gepinnt/inhaltsbegründet.
|
||||
- [x] `wiki/index.md` — Area-Sektion + Link auf `wissensarchitektur/index.md`.
|
||||
- [x] `wiki/log.md` — Eintrag gemäß Verifikations-Vorgaben; `sprint-status.yaml` → in-progress; `deferred-work.md`-Einträge schließen/korrigieren.
|
||||
- [x] Negative-/Edge-Tests im Sandbox-/tmp-Baum (TOP_LEVEL_COLLISION → §3.2-Hold; Area ohne `index.md` → Punkt 11 „Area ohne index.md=…"; `../`-Dangling; Out-of-Bundle-`..`-Escape → `DANGLING`).
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given ein erkanntes Thema, when der Bereich bestimmt wird, then geschieht dies textual-deterministisch (bestehender `index.md`-Link oder Root-Ebene; nie Embedding) (A0-10, AD-13).
|
||||
- Given die Concept-Identität, when ein Concept abgelegt wird, then entspricht sie dem relativen OKF-Pfad ohne `.md` mit genau einer Normalisierung (`wiki/<area>/index.md` → `<area>`, AD-7a, A0-8).
|
||||
- Given eine Bereichsnavigation, when ein Consumer sich orientiert, then führt die Hierarchie (Area-`index.md`) schrittweise zu den Concepts — die neue Area ist über die Root-`index.md` erreichbar (AD-9, FR-11).
|
||||
- Given ein Konflikt mit existierendem Top-Level-Pfad, when erkannt, then löst der fixierte §3.2-Hold aus statt stillem Überschreiben (A0-10).
|
||||
- Given die Instruktion, when geprüft, then ist §5.7 der einzige Instruktions-Ort (D-3), §5.6-Formeln area-fest re-executierbar (AD-17h) und der Validator läuft SUCCESS (keine neue §7-Klasse, kein Schema-/Validator-/raw-Change).
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- **2026-08-18 (Loop 2, bmad-code-review, 4 Layer; Abschluss):** Review-Loop 2 abgeschlossen — 3 `decision-needed` (Nutzer-Entscheidungen 1/1/1), 14 `patch` (alle umgesetzt), 4 `defer` (in `deferred-work.md` verankert), 8 dismissed. **Amendierung der nicht-gefrorenen Sektionen:** (a) Verification-Item 3 (Formel 4) von „Extraktion aus `baseline_commit` `66451b6…`" auf „Extraktion aus dem **Kopf des letzten Zuwachs-Runs** (`862cf41…`, 38 ≡ 38)" umgestellt (Decision 1 — der gepinnte Selbsttest hätte deterministisch `38 ≠ 30` = Run-FAIL geliefert); (b) Verification-Item 1 um den byte-identischen Formel-3-String (quellenbasierte `../schema/*`-Exklusion, Decision 2) ergänzt; (c) Verification-Item 4 auf 7 `wiki/`-Dateien + korrekten Punkt-Satz (die „6" der gefrorenen I/O-Matrix bleibt frozen — Defer). **Frozen-Sektionen unverändert** (I/O-Matrix „6 `wiki/`-Dateien"/„stillem Overwrite" = Änderungskandidat der nächsten Renegotiations-Runde). **Status:** `sprint-status.yaml` `2-4-…` `review` → `done` (spec-2-3-Präzedenz: `done` nach Review-Freigabe; Frontmatter `status: 'done'` damit deckungsgleich), `review_loop_iteration` → 2. **Kein Schema-/Validator-/raw-Change (AD-3); keine neue §7-Klasse; keine Vertragsänderung.**
|
||||
- **2026-08-18 (Erstellung):** Initiale Approve-Baseline.
|
||||
- **2026-08-18 (Loop 1, Step-04-bad_spec):** Amendierung der nicht-gefrorenen Sektionen (Code Map / Tasks / Verification) nach dem Review-Loop 1. **Auslöser-Findings:** (A1) `schema/compiler.md` §5.6 Formel 3 (Dangling-Check) ließ Out-of-Bundle-`..`-Traversale still passieren — `[x](../../README.md)` aus einem Area-Concept erzeugte **keine** Ausgabe (der `-f`-Existenztest löste `wiki/<area>/../../README.md` zur existierenden Workspace-`README.md` auf); Kontainment war nur Prosa („Ziel muss unter `wiki/` liegen", „kein Stiller Vorbeilass"), nie durch eine Prüfung erzwungen. (A2) Formel 4 (Kontakt-mit-`raw/`-Baseline) extrahierte aus dem veralteten Story-2.3-`7e1f449…` (Ergebnis `30`), während die Formel-Prosa `66451b6` + Basename-Filter + „dieser Run: 30" beanspruchte und die Ist-Zählung `38` beträgt — ein Producer, der den wörtlichen Selbsttest ausführt, erhält `38 ≠ 30` = FAIL ohne Auflösung. (B1) Das Label `AREA_WITHOUT_INDEX` ist **inventiert** — es existiert in keinem Validator-Output; die reale Meldung ist `FAIL … Punkt 11: Index-Regel verletzt (Area ohne index.md=…)`. **Geändert:** (a) Code Map präzisiert, dass Formel 3 Out-of-Bundle-Ausbruch sperren MUSS (aufgelöster Ziel-Pfad bleibt unter `wiki/`, sonst `DANGLING`); (b) Formel-4-Extraktion auf den `baseline_commit`-Kopf dieser Spezifikation (`66451b6…`) fixiert; (c) `AREA_WITHOUT_INDEX` durch die wörtliche Punkt-11-Meldung ersetzt (Code Map/Tasks/Verification). **Vermeidet den bekannten-bösen Zustand:** (A1) ein Consumer-Renderer kann `../../README.md` nicht auflösen → stiller Verstoß gegen das Renderer-konforme Link-Auflösungsmodell der Story; (A2) re-executierbarer Selbsttest (AD-17h) schlägt auf dem neuen Baum fehl; (B1) Instruktions-Text behauptet eine Validator-Meldung, die der Validator nicht emittiert (Falsch-Attribution auf den Validator). **KEEP (positive Erhaltung, muss die Re-Derivation überleben):** neue Area `wissensarchitektur/` (frontmatterlose `index.md` + `source-material.md`, `type: concept`, `sources` s1=architecture-spine + s2=prd, §5.5-Inline-Verweise, `../`-Links mit Kontext-Marker); bestehende Root-Concepts + Root-`index.md`-Links byte-identisch (kein MOVE, AD-7d); §5.7-Routing-Prinzip ((a) bestehender `index.md`-Link → Bereich / (b) Default Root; neue Areas nur konsolidiert; kein neues Prädikat; kein MOVE); file-relatives Auflösungsmodell; Formel-Berichtigungen oben; die Story-2.4-`deferred-work.md`-Einträge (file-relativ umgesetzt, Basename-Filter). **Kein Schema-/Validator-/raw-Change (AD-3); keine neue §7-Klasse; keine Vertragsänderung.
|
||||
|
||||
## Design Notes
|
||||
|
||||
**File-relatives Auflösungsmodell (statt bundleroot-relativ):** Bei Root-Dateien sind file-relativ und bundleroot-relativ identisch (alle 8 bestehenden Bestands-Links bleiben byte-identisch — Null-Delta zum Story-2.3-Pin). In Areas unterscheiden sie sich: `wissensarchitektur/trennung-states.md → llm-wiki-prinzip.md` ist bundleroot-relativ `llm-wiki-prinzip.md` (im Renderer falsch), file-relativ `../llm-wiki-prinzip.md` (im Renderer korrekt). File-relativ erfüllt die zwei Story-2.3-Pin-Rationale (Standard-Tools lösen ohne Konventionswissen auf, FR-10/AD-8) und ist der einzige beide-Ebenen-taugliche Modus; es bleibt **eine syntaktische Form** (relativer Pfad + `.md`-Endung), damit die AD-7b-„zwei-Producer-Eine-ID"-Eigenschaft erhalten bleibt. Die §5.6-`../`-Exklusion war fürs flache Bundle korrekt (jedes `../` war einst außerhalb); mit Areas wird sie zur in-Bundle-Aufwärts-Auflösung. `../schema/` bleibt als andere Schicht exkludiert — Abgrenzung über das Zielverzeichnis (unter `wiki/` = in-Bundle) statt über das bloße `../`-Präfix.
|
||||
|
||||
**Warum kein MOVE bestehender Concepts in der Demo:** Neuzuordnung/Umbenennung existierender Concepts ist semantische Kuratierung mit AD-7d-Redirect-Pflicht — Epic-3-Nähe, nicht in den Story-2.4-ACs (die nur _neue_ Einheiten zuordnen). Die Demo erzeugt deshalb ein neues Area-Concept + Area-Index; die Routing-/Hold-/Normalisierungs-ACs sind vollständig durch den Sandbox-Negativ-Test und den realen Erzeugungspfad belegt.
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands (re-executierbar, ab Workspace-Root):**
|
||||
|
||||
1. **§5.6-Formel 1/2/3 (area-fest)** — erwartet: Bestands-Check zeigt den neuen Bestand (inkl. `wissensarchitektur/source-material.md` und `../`-Ziele); Form-Check Ausgabe `0`, Exit `0`; Dangling-Check keine Ausgabe:
|
||||
- `sh -c "grep -roE '\]\([^)]*\)' --include='*.md' --exclude=log.md wiki/"`
|
||||
- Formel 3 (Dangling-Check, nach Story-2.4-`../`-Schärfung, byte-identisch in §5.6 gespiegelt — Rev-2.0-Konvention; Loop-2: quellenbasierte `../schema/*`-Exklusion, Decision 2):
|
||||
- `sh -c 'grep -roE "]\([^)]*\)" --include="*.md" --exclude=log.md wiki/ | sed -E "s#^([^:]+):\]\(([^)]*)\)\$#\1|\2#" | sort -u | while IFS="|" read -r src t; do case "$t" in ""|*:*|raw/*|./*|/*) if [ "$t" = "" ]; then echo "DANGLING: (leeres Ziel)"; fi; continue;; esac; case "$t" in "#"*) continue;; esac; case "$t" in "../schema/"*) if [ "$(dirname "$src")" = "wiki" ]; then continue; fi;; esac; p=${t%%#*}; f="/$(dirname "$src")/$p"; while printf "%s" "$f" | grep -qE "/[^/]+/\.\.(/|$)"; do f=$(printf "%s" "$f" | sed -E "s#/[^/]+/\.\.(/|$)#/#g"); done; f=${f#/}; case "$f" in wiki/*) [ -f "$f" ] || echo "DANGLING: $t";; *) echo "DANGLING: $t";; esac; done'
|
||||
- **Out-of-Bundle-Escape-Negativkontrolle (Loop-1-Review-Fix):** In einer Sandbox-/tmp-Kopie des `wiki/`-Baums, die auch die Workspace-`README.md` bzw. `schema/compiler.md` außerhalb von `wiki/` enthält, MUSS Formel 3 ein Body-Ziel `[x](../../README.md)` bzw. `[x](../../schema/compiler.md)` aus einem Area-Concept **als `DANGLING: …` melden** (Existenztest reicht nicht — `-f` löst `wiki/<area>/../../README.md` zu einer existierenden Out-of-Bundle-Datei auf und würde still passieren). Die Formel MUSS stattdessen sperren: aufgelöster Ziel-Pfad nach `..`-Auflösung muss unter `wiki/` bleiben.
|
||||
2. **Determinismus-Show (Routing):** Negativ-Test Sandbox-`/tmp/…/wiki`: Kandidat mit ID `llm-wiki-prinzip` → §3.2-Hold-Meldung, keine Datei/kein Link; `wiki/foo/` ohne `index.md` → wörtliche Punkt-11-Ausgabe `FAIL … Punkt 11: Index-Regel verletzt (Area ohne index.md=foo)` (kein inventiertes `AREA_WITHOUT_INDEX`).
|
||||
3. **§5.6-Formel 4 (Re-Baseline für Zuwachs-Runs, Loop-2-Decision 1):** aktuelle Vorkommen-Zählung `(raw/` (log.md-exkludiert) mit Extraktion aus dem **Kopf des letzten Zuwachs-Runs** (dieser Run: `862cf410c624072833cd959da9a2fb26235716f6`, beide Zählungen = **38**) re-executieren — die Extraktions-Formel im §5.6-Text trägt den Run-Kopf-Commit, nicht den Story-2.3-`7e1f449…` und nicht den `baseline_commit`-Wert der Spec-Frontmatter (`66451b6…` = Zustand **vor** dem Zuwachs, extrahiert `30`; bleibt als Referenz dieses Runs im Log); bei jedem weiteren Datei-Zuwachs ist die Baseline-Extraktion erneut auf den dann aktuellen Run-Kopf durchzuführen (Wieder-Baseline-Klausel §5.6 Pkt. 3, Formel (4)).
|
||||
4. **Validator-Lauf:** alle 7 `wiki/`-Dateien SUCCESS (Bundleroot `index.md`, `log.md`, 3 Root-Concepts, Area-`index.md`, Area-Concept; Punkte 1/2/6/7/8/9/10/11/12/13/14, EC-1) — incl. Area-`index.md` frontmatterlos (Punkt 10) und Area-Concept verlinkt im nächsten Vorfahren (Punkt 11). Die „6 `wiki/`-Dateien" der gefrorenen I/O-Matrix bleiben frozen (Defizitzählung; Defer in `deferred-work.md`).
|
||||
|
||||
**Manual checks:**
|
||||
- §7-Story-2.4-Bullet als „in §5.7 verankert" statt „verbleibt"; kein Schema-/Validator-/raw-Diff; `log.md`-Eintrag datiert (2026-08-18), Vertrag-§5-Format, dokumentiert den `sprint-status`-Wechsel und die Formel-4-Neu-Baseline; `deferred-work.md`-Einträge geschlossen/korrigiert (append-only); `sprint-status.yaml` konsistent.
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Story 2.4 — deterministische Bereichszuordnung & Concept-Hierarchie (Loop 0 → Loop-1-Findings A1/A2/B1).** Review-Reihenfolge nach Belang, beginnend beim Design-Einstieg.
|
||||
|
||||
**Design-Einstieg — die neue Routing-Regel**
|
||||
|
||||
- §5.7 ist der einzige Instruktions-Ort (D-3); von hier versteht man den gesamten Change: (a) bestehender `index.md`-Link → Bereich, (b) Default Root, neue Areas nur konsolidiert, kein MOVE (AD-7c/A0-10/AD-13).
|
||||
[`compiler.md:178`](../../schema/compiler.md#L178)
|
||||
- Routing-Regel im Detail — textual-deterministische Bereiche, nie Embedding (Pkt. 1).
|
||||
[`compiler.md:182`](../../schema/compiler.md#L182)
|
||||
- Top-Level-Kollisions-Hold → fixierter §3.2, kein neues Prädikat, kein MOVE (Pkt. 3, A0-10).
|
||||
[`compiler.md:196`](../../schema/compiler.md#L196)
|
||||
|
||||
**Link-Auflösungsmodell & die Loop-1-Fixes**
|
||||
|
||||
- File-relatives Auflösungsmodell inkl. Out-of-Bundle-`..`-Containment — der Kern der Story; löst das §5.6-Defer (Pkt. 4; Root byte-identisch).
|
||||
[`compiler.md:198`](../../schema/compiler.md#L198)
|
||||
- Dangling-Check (Formel 3): Quell-Datei-Spur + `..`-Kollabierung + `wiki/*`-Containment — Loop-1-**A1-Fix** (Out-of-Bundle-Escape → `DANGLING`).
|
||||
[`compiler.md:154`](../../schema/compiler.md#L154)
|
||||
- Negativ-Beispiel 2 (Escape): `[x](../../README.md)` wird als `DANGLING` gesperrt statt still passiert (Loop-1-A1-Nachweis).
|
||||
[`compiler.md:174`](../../schema/compiler.md#L174)
|
||||
- Kontakt-mit-`raw/`-Baseline (Formel 4): Extraktion aus `66451b6…` (`baseline_commit` dieser Spec) + Basename-Filter — Loop-1-**A2-Fix** (nicht mehr der alte `7e1f449…`).
|
||||
[`compiler.md:163`](../../schema/compiler.md#L163)
|
||||
|
||||
**Area-Hierarchie & Index**
|
||||
|
||||
- Area-`index.md`-Regel: frontmatterlos (Punkt 10), Punkt-11-Meldung wörtlich (`Area ohne index.md=<area>`) — Loop-1-**B1-Fix** (kein inventiertes `AREA_WITHOUT_INDEX`).
|
||||
[`compiler.md:199`](../../schema/compiler.md#L199)
|
||||
- Worked Example: `source-material.md` — `type: concept`, `sources` s1/s2, `../`-Links, gepinnte Verlinkung in der Area-`index.md`.
|
||||
[`compiler.md:200`](../../schema/compiler.md#L200)
|
||||
|
||||
**Bundle-Instanz (Demo-Area)**
|
||||
|
||||
- Frontmatterlose Area-`index.md` verlinkt das Area-Concept (Punkt 10/11 konform, §5.7-Hierarchie).
|
||||
[`wissensarchitektur/index.md:1`](../../wiki/wissensarchitektur/index.md#L1)
|
||||
- Bereichs-Concept mit §5.5-Inline-Verweisen + `../`-Body-Links auf Root-Concepts (AD-7a/A0-8).
|
||||
[`wissensarchitektur/source-material.md:1`](../../wiki/wissensarchitektur/source-material.md#L1)
|
||||
- Bundleroot: neue Area-Sektion verlinkt `wissensarchitektur/index.md` (Navigation Root → Area, AD-9).
|
||||
[`index.md:35`](../../wiki/index.md#L35)
|
||||
|
||||
**Nachweis & Logistik**
|
||||
|
||||
- Spec-Änderung nach Loop 1 (Code Map/Verification präzisiert: Containment-Pflicht, `66451b6`-Baseline, wörtliche Punkt-11-Meldung).
|
||||
[`spec …:48`](../../_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md#L48)
|
||||
- Spec Change Log: Loop-1-Eintrag (Auslöser, Geändert, vermiedener Zustand, KEEP).
|
||||
[`spec …:75`](../../_bmad-output/implementation-artifacts/spec-2-4-deterministische-bereichszuordnung-concept-hierarchie.md#L75)
|
||||
- `log.md`-Eintrag 2026-08-18: Formel-4-Re-Baseline (`38`), Statuswechsel, gültige Punkt-11-Wortwahl, `sprint-status`-Wechsel.
|
||||
[`wiki/log.md:3`](../../wiki/log.md#L3)
|
||||
- `sprint-status.yaml`: `2-4-…` → `review` (review-loopiterierte Story, bereit zur Review-Freigabe).
|
||||
[`sprint-status.yaml:49`](../../_bmad-output/implementation-artifacts/sprint-status.yaml#L49)
|
||||
|
||||
## Review Findings (bmad-code-review, 2026-08-18 — Loop 2, 4 Layer)
|
||||
|
||||
### Decision-Needed (resolved 2026-08-18, Nutzer-Entscheidung)
|
||||
|
||||
- [x] [Review][Decision] Formel 4 (Kontakt-mit-`raw/`) ist auf dem ausgelieferten Baum per eigener Vorgabe nicht passierbar (38 ≠ 30) — `schema/compiler.md` §5.6 Pkt. 3, Formel (4) hält an „erwartet: aktuell ≡ Baseline" und „Beide Vorkommen-Zählungen **müssen** übereinstimmen" fest, während derselbe Absatz die Ist-Zahl `38` und die aus `66451b6` extrahierte Baseline `30` benennt; ein Producer, der den AD-17h-Selbsttest wörtlich re-executiert, erhält deterministisch `38 ≠ 30` = Run-FAIL nach NFR-4 — exakt der von Loop-1-A2 als bekannt-bös klassifizierte Zustand. `wiki/log.md` rahmt „38 ≠ 30" als „kein Fehlalarm: Zuwachs-Re-Baseline", die Logik sagt also OK, die Formel FAIL; der neue Referenzwert 38 existiert nur als Prosa, nicht in extrahierbarer Form. Re-Execution bestätigt: Ist=38, Baseline(`66451b6`)=30, Extraktion aus Run-Kopf `862cf41`=38. — **Aufgelöst (Nutzer, Option 1):** Re-Baseline auf den Run-Kopf `862cf41` (Extraktion = 38) pinnen; Erwartungstext „Ist ≡ Extraktion aus dem Baseline-Commit des letzten Zuwachs-Runs"; `66451b6`/30 bleibt als Dokumentation dieses Runs im Log. → Patch (unten).
|
||||
- [x] [Review][Decision] `../schema/*`-Exklusion in Formel 3/2 ist zielbasiert, nicht quellbasiert — die Prosa (compiler.md `:174`, `:198`, Negativ-Beispiel 2) beschränkt die Exklusion auf „einstufiges `../schema/*` **aus Root-Dateien**", die Formel (`:154` `case "$t" in …|../schema/*) continue`) exkludiert aber unabhängig von der Quelle. Sandbox-verifiziert: `[z](../schema/compiler.md)` aus `wiki/wissensarchitektur/source-material.md` → Auflösung `wiki/schema/compiler.md` (unter `wiki/`, existiert nicht) → Formel-Ausgabe **leer**, Exit 0. Stiller Vorbeilass der einstufigen in-Bundle-Form aus Areas (NFR-4), während der Out-of-Bundle-Escape (`../../…`) korrekt gesperrt wird. — **Aufgelöst (Nutzer, Option 1):** Formel quellenbasiert schärfen — `../schema/*` wird nur exkludiert, wenn die Quell-Datei `wiki/index.md` ist; aus anderen Quellen läuft das Ziel durch Auflösung + Containment + `-f`-Test (→ `DANGLING` bei Nichtexistenz). Prosa bleibt, Formel folgt der Prosa. → Patch (unten).
|
||||
- [x] [Review][Decision] Routing-Regel §5.7 Pkt. 1(a) ist bei mehreren passenden `index.md`-Links nicht deterministisch — „inhaltlich deckungsgleichen Eintrag" trägt kein textuelles Prädikat; bei Mehrfachtreffern (real im Ist-Bundle: Bundleroot verlinkt Root-Concept `wissensarchitektur-trennung-states.md`, die Area `wissensarchitektur/` denselben Themenraum) ist unklar, welcher Link den Bereich vorgibt; AD-7c/A0-10 verlangen textual-deterministische Zuordnung. — **Aufgelöst (Nutzer, Option 1):** Deterministisches Treffer-Prädikat + Tie-Break in Pkt. 1(a) verankern: Treffer = Identitäts-Identität des Link-Ziels ≡ kanonischer Name des Themas (kein „inhaltlich deckungsgleich"-Urteil, AD-13); Mehrfachtreffer → Bundleroot-Links vor Area-Links, dann lexicografische Pfad-Reihenfolge. → Patch (unten).
|
||||
|
||||
### Patch
|
||||
|
||||
- [x] [Review][Patch] Negativ-Test-Nachweis fehlt in `wiki/log.md` — Code Map verspricht „Negativ-Test-Hold-Nachweis", Task 5 ist `[x]`, aber der 2026-08-18-Log-Eintrag enthält keine Hold-Meldung, keine wörtliche Punkt-11-`Area-ohne-index.md`-Ausgabe, keinen `DANGLING`-Nachweis und keinen Sandbox-Pfad; Execution-Nachweis der I/O-Matrix-Zeilen (TOP_LEVEL_COLLISION, AREA_WITHOUT_INDEX, DIVING_NON_EXISTENT) fehlt im Artefakt [wiki/log.md:4]
|
||||
- [x] [Review][Patch] Veraltete „bundle-relativ"-Passagen widersprechen dem neuen file-relativen Pin — `schema/compiler.md:62` (§5.3 Pkt. 3: „file-relativ bundle-relativ mit `.md-Endung" — Oxymoron), `:241` (§6.6-Zelle: „bundlerelativ"), `:254` (§7-Bullet: „bundle-relativ mit `.md-Endung"`) wurden nicht auf file-relativ nachgeführt; für Area-Links faktisch falsch, widerspricht §5.6 Pkt. 1/§5.7 Pkt. 4 [schema/compiler.md:62,241,254]
|
||||
- [x] [Review][Patch] Log/YAML/Spec-Status-Divergenz: `sprint-status.yaml` zeigt `review`, der Log-Eintrag dokumentiert nur `backlog → in-progress` („dieser Statuswechsel findet mit diesem Eintrag statt") — die Transition `in-progress → review` (Review-Handoff) ist protokolldokumentarisch nicht abgebildet; die gefrorene Vorgabe („→ `in-progress`") und die Spec-SRO („→ `review`") sind intern spaltig [wiki/log.md:4, sprint-status.yaml:49]
|
||||
- [x] [Review][Patch] Spec-Verification „6 `wiki/`-Dateien" vs. Log „7 Dateien" + falsche Punkt-9-Begründung — Spec-Verification (`:96`) erwartet „6 `wiki/`-Dateien, Punkte 1/6/8/9/10/11/14"; der Log dokumentiert 7 Dateien (inkl. `log.md`) mit dem Punkt-Satz 1/2/6/7/8/9/10/11/12/13/14 und begründet die Differenz fälschlich mit „Punkt 9/10" (Punkt 9 = `okf_version`/`type: bundle`-Verbot außerhalb der Bundleroot, nicht log.md-Validierung). Die gefrorene I/O-Matrix („6 `wiki/`-Dateien") selbst bleibt angefasst (→ Defer) [wiki/log.md:4, spec:96]
|
||||
- [x] [Review][Patch] Spec-Verification spiegelt die neue Formel 3 nicht byte-identisch — Rev-2.0-Konvention („5/5 Formel-Strings identisch compiler↔spec") bricht: die Verification listet nur den Formel-1-String; der neue Formel-3-String (Quell-Datei-Spur, `..`-Kollabierung, Containment, compiler.md `:154`) fehlt als re-executierbarer Spiegel in der Spec [spec-2-4-….md:124-127]
|
||||
- [x] [Review][Patch] §7-Scope-Einleitung veraltet — „Diese Instruktion ist auf die Erzeugung neuer Concepts auf Root-Ebene begrenzt" (`:249`) widerspricht dem eigenen Bullet direkt darunter, das die Area-Anlage in §5.7 verankert; Scope-Satz auf „Root-Ebene und Areas gemäß §5.7" nachführen [schema/compiler.md:249]
|
||||
- [x] [Review][Patch] Typos/Orthografie in normativen Texten — `schema/compiler.md:166` + `wiki/log.md:4`: „akte-Baseline" (→ „aktuelle Baseline"); `compiler.md:241`: doppeltes Leerzeichen „(bundlerelativ , `.md`-Endung)"; (frozen-Spec „stillem Overwrite" → Defer) [schema/compiler.md:166,241]
|
||||
- [x] [Review][Patch] Ambiguität „Kopf dieser Spezifikation" — Formel 4/Rev-2.1-Log bezeichnen `66451b6` als „Kopf dieser Spezifikation"; gemeint ist der deklarierte `baseline_commit`-Wert der Spec-Frontmatter (Eltern-Commit, nicht der Story-2.4-Branch-Kopf) — Referenz auf den deklarierten Wert umstellen [schema/compiler.md:159,163,283]
|
||||
- [x] [Review][Patch] Area-`index.md`-Prosa überzeichnet den Area-Inhalt — `wiki/wissensarchitektur/index.md:3` verspricht „die Link-Form und die progressive Discovery" als gebündelte Themen; existiert genau ein Area-Concept (`source-material.md`), zur Link-Form/Discovery kein Concept (Story 2.5) [wiki/wissensarchitektur/index.md:3]
|
||||
- [x] [Review][Patch] `sprint-status.yaml last_updated` ohne Zeitanteil — `08-18-2026` bricht das etablierte Feld-Format `MM-DD-YYYY HH:MM` (bisher `08-17-2026 15:40`) [sprint-status.yaml:32]
|
||||
- [x] [Review][Patch] Drei „Story-2.4-Kandidat"-Defer-Einträge bleiben offen, ohne Status-Nachführung — `deferred-work.md:219` (`)`-blinde Ziel-Extraktion), `:223` (Cross-Page-Anker), `:249` (Multi-Line-Ziele) nennen Story 2.4 als Home; die Story ist abgeschlossen ohne Umsetzung und ohne Weiterleitung — Home-Angaben auf nächste Runde (z. B. Story 2.5/fokussierte Instruktionsrunde) umstellen [deferred-work.md:219,223,249]
|
||||
- [x] [Review][Patch] (aus Decision 1) Formel-4-Re-Baseline auf Run-Kopf — `schema/compiler.md` §5.6 Pkt. 3, Formel (4): Extraktions-Commit von `66451b6` auf `862cf41` (Run-Kopf, Extraktion = 38) umstellen, Erwartungstext auf „Ist ≡ Extraktion aus dem Baseline-Commit des letzten Zuwachs-Runs"; `66451b6`/30 bleibt als Dokumentation dieses Zuwachs-Runs im Log; `wiki/log.md`-Eintrag um die neue Runnable-Baseline (38 ≡ 38 aus `862cf41`) nachführen [schema/compiler.md:159-166, wiki/log.md:4]
|
||||
- [x] [Review][Patch] (aus Decision 2) Formel 3 quellenbasierte `../schema/*`-Exklusion — `schema/compiler.md` §5.6 Pkt. 3, Formel (3): `case "$t" in "#"*|../schema/*)` um Quell-Bedingung schärfen (Exklusion nur, wenn `src` = `wiki/index.md`); aus anderen Quellen läuft das Ziel durch die bestehende Auflösung + Containment + `-f`-Test; Prosa/§5.7 Pkt. 4/Negativ-Beispiel 2 bleiben (sie sind jetzt konsistent); Sandbox-Negativnachweis (in-Bundle-`../schema/x.md` aus Area → `DANGLING`) im Patch-Vergleich verifizieren [schema/compiler.md:154]
|
||||
- [x] [Review][Patch] (aus Decision 3) §5.7 Pkt. 1(a) Treffer-Prädikat + Tie-Break — `schema/compiler.md` §5.7 Pkt. 1(a): „auf das erkannte Thema bzw. einen inhaltlich deckungsgleichen Eintrag" ersetzen durch textuelles Prädikat (Identität des Link-Ziels ≡ kanonischer Name des neuen Themas) und Mehrfachtreffer-Regel (Bundleroot-Links vor Area-Links, dann lexicografische Pfad-Reihenfolge); AD-7c/A0-10/AD-13-Referenzen bleiben [schema/compiler.md:183]
|
||||
|
||||
### Defer
|
||||
|
||||
- [x] [Review][Defer] Spec-Frontmatter `status: 'done'` bei offenem Review — Präzedenz spec-2-3: `done` erst nach Review-Freigabe; der Status wird mit diesem Review-Loop abgeschlossen synchron (Step-6-Regel), kein separates Patch [spec-2-4-….md:5]
|
||||
- [x] [Review][Defer] Gefrorene I/O-Matrix „6 `wiki/`-Dateien" + „stillem Overwrite" — frozen-after-approval-Sektion, nur per Renegotiation änderbar; wird mit der Loop-2-Spec-Amendierung (Decision-Resolution) nachgeführt [spec-2-4-….md:74-76]
|
||||
- [x] [Review][Defer] ID-Kollision Area-`index.md` vs. Root-Concept (`wiki/<a>/index.md` und `wiki/<a>.md` → beide Identität `<a>`) — der §3.2-Hold feuert nur auf Datei-Kollision; eine Identitätskollision ohne Dateikollision ist undefiniert. Fix erfordert §3.2-Erweiterung/Vertragsänderung (AD-3 read-only, „kein neues Prädikat") — Home: nächste autorisierte Validator-/Vertragsrevision [schema/compiler.md:190-197]
|
||||
- [x] [Review][Defer] Spec-These „Validator Punkt 11 akzeptiert bereits Areas" nicht vom read-only-Validator-Text gedeckt — Punkt 11 verlangt die Identität „als relativer Bundle-Pfad referenziert"; die Area-`index.md` verlinkt file-relativ `source-material.md`, die Bundle-Identität `wissensarchitektur/source-material` erscheint textuell nicht → ein wörtlicher Punkt-11-Check ist auf dem Demo-Concept nicht deterministisch entscheidbar; SUCCESS-Nachweis der Log nicht unabhängig überprüfbar. Fix = autorisierte Validator-Revision (AD-3) — Home: Rev-9-Aktionsitem [validator.md:70, wiki/wissensarchitektur/index.md:9]
|
||||
+153
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: 'Progressive Discovery über index.md bereitstellen (Story 2.5)'
|
||||
type: 'feature'
|
||||
created: '2026-08-18'
|
||||
status: 'done'
|
||||
review_loop_iteration: 3
|
||||
baseline_commit: 64a0f6a6161247c0556f9d1dc2500f2b913fa967
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/epic-2-context.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Die progressive Discovery ist im Bundle zwar normiert (Vertrag §6: Bundleroot → Area-`index.md` → Concepts, AD-9/FR-11), aber für den Adressierbaren Anspruch sind drei Lücken offen: (1) §7 Z.253 der Compiler-Instruktion verweist die komplette Discovery ("Navigation, Area-Indizes, Suche") als Vorbehalt an Story 2.5; (2) der Validator prüft weder, dass eine Area von der Bundleroot aus erreichbar ist (Navigation Root → Area, AD-9), noch gibt es einen Selbsttest für die vollständige index-Verkettung; (3) Defer F-07 (verschachtelte Areas/Unter-Ebenen, `wiki/a/b/concept.md`) ist offen und nennt Story 2.5 ausdrücklich als Heimat, die die Antwort festlegt.
|
||||
|
||||
**Approach:** Story 2.5 integriert die progressive Discovery als expliziten Instruktionsabschnitt (§5.8) in `schema/compiler.md` — D-3-konform, kein Vertrag-/Validator-/raw-Change (AD-3). Sie definiert: (a) die bewertbare Discovery-Vollständigkeit (gewurzelte Erreichbarkeit Root → Area-`index.md` → Concept als erfolgreicher Discovery-Pfad, §5.7 Pkt. 5), (b) die Basis-Discovery-Pflicht (frontmatterlose Area-`index.md` verlinkt ihre Area-Concepts) als „Struktur" und nicht nur Soll, (c) eine deterministische textuelle „Such"-Antwort für den Story-2.5-Vorbehalt (Navigation als primäre Discovery, Suche als Consumer-seitige grep-Angelegenheit — AD-13, FR-11, NFR-3), und (d) die Antwort auf Defer F-07: die Kartografie folgt ab Story 2.5 einer konsolidierten Zwei-Ebenen-Struktur (Root-Concepts + Areas mit je einer `index.md`); verschachtelte Areas (`wiki/a/b/`) sind keine zugelassene Anlageform — ein solcher Kandidat wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten *(Loopback-1-Renegotiation 2026-08-18, menschen-autorisiert — Option A: Träger ist §5.8, nicht §3.2; §3.2 bleibt der Dateikollision bestehender Concepts vorbehalten).* Neue §5.8 + Revisionslog (3.x). Kein Interface-/Backend-/Datenbank-Änderung — reine Instruktions- und Bundle-Demonstrations-Änderung. Keine neue §7-Invaliditätsklasse; validator.md bleibt strukturell unverändert (Punkt 11 bleibt die Index-/Verlinkungs-Prüfung).
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- **Progressive Discovery ist ein Instruktionsthema (D-3).** Die Discovery-Semantik wird in `schema/compiler.md` (neue §5.8) verankert — einziger Instruktions-Ort. Kein Vertrag-/Validator-/raw-Change (AD-3), keine Erweiterung der §7-Liste, kein Standalone-Tool. Der Validator bleibt bei Punkt 11 als strukturelle Index-/Verlinkungs-Prüfung (Area-Existenz + Concept-in-Index verlinkt); die Discovery-Vollständigkeit (Root → Area → Concept) ist keine neue §7-Invaliditätsklasse — sie wird deterministisch als Instruktions-Selbsttest belegt.
|
||||
- **Kartografie ist konsolidiert Zwei-Ebenen (befriedet F-07).** Das Bundle-Navigationsmodell besteht aus Root-Concepts + Areas (je eine frontmatterlose `wiki/<area>/index.md`, die ihre Area-Concepts in gepinnter §5.6-Form verlinkt; Bundleroot `wiki/index.md` verlinkt die Area-`index.md`, Navigation Root → Area, AD-9). **Verschachtelte Areas sind keine zugelassene Anlageform:** `wiki/a/b/` mit Concept darunter ist kein „Area mit Inhalt" — ein solcher Kandidat (Erstellungskandidat oder Discovery-Ziel) wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten (keine Datei, kein Index-Link, Meldung `NESTED AREA: <area>`; Loopback-1-Korrektur: Träger ist §5.8-lokal, D-3 — nicht §3.2, der bleibt der Dateikollision bestehender Concepts vorbehalten). Die F-07-Frage „was ist Area mit Inhalt" wird damit instruktionsseitig deterministisch beantwortet (Erkennung = Datei-Existenz in Tiefe ≥ 3 unter der Bundleroot; Meldung = Instruktions-Selbsttest-Befund — kein §7-Eingriff).
|
||||
- **Suche ist konsumenten-/extern-seitig (AD-9, FR-11, AD-13).** Die Discovery braucht keine proprietäre Datenbank: Navigation ist die primäre Discovery (gewurzelte Erreichbarkeit), Suche ist optional konsumenten-seitig — textuell-deterministisch z. B. `grep`/`ripgrep` über `wiki/`. Kein Embedding/Vector, kein Such-Dienst, kein Index-Datei-Format-Erfinden — die bestehenden `index.md` sind die Discovery-Ebene.
|
||||
- **Die Discovery-Lücke des Validators ist instruktionsseitig deckbar.** Der Validator prüft nicht, dass eine Area von der Bundleroot verlinkt ist (Punkt 11 adressiert Area-Existenz/Concept-Verlinkung, nicht Root→Area-Navigation). Diese Lücke wird durch einen deterministischen, re-executierbaren Instruktions-Selbsttest geschlossen (Discovery-Check: jede Area ist aus der Bundleroot erreichbar; jedes Area-Concept in seiner Area-`index.md` verlinkt — Verlinkung in gepinnter §5.6-Form). Kein Validator-Change (AD-3, D-3).
|
||||
- **Kein MOVE bestehender Root-Concepts.** Die bestehenden Root-Concepts werden nicht in Areas verschoben (Kuratierung/AD-7d ist Epic-3-Nähe); als Discovery-Demo kann ein neues Root-Concept ergänzt und (a) in der Bundleroot sowie (b) über einen Index-Link „über das Area-Concept" verlinkt werden (nur neue Inhalte).
|
||||
- **Bundle bleibt ohne geladene Indizes vollständig verständlich (NFR-2/NFR-5)** — alle Discovery-Regeln sind Markdown/Datei-Struktur, kein Server, keine Datenbank, kein laufender Prozess.
|
||||
- `deferred-work.md` (append-only): Defer F-07 bekommt `status: umgesetzt (Story 2.5…)`; die drei „Home: fokussierte Instruktionsrunde ab Story 2.5"-Einträge (Multi-Line, `)`-blinde Extraktion, Cross-Page-Anker) bleiben offen — sie gehören zur Link-Pin-Runde (§5.6), die Story 2.5 unberührt lässt (kein Scope-Hijack). `sprint-status.yaml`: Key `2-5-…` → `in-progress`.
|
||||
|
||||
**Ask First:** Andere Pin-Wahl als die bestehende gepinnte §5.6-Form · MOVE bestehender Concepts · Validator-/Vertrags-/raw-Änderung · Einführung verschachtelter Areas als Regelfall · Such-Dienst/Index-Datei-Format über die Konsumenten-seitige grep-Antwort hinaus.
|
||||
|
||||
**Never:** Veränderung an `schema/wiki-compiler.md`/`schema/validator.md`/`raw/` (AD-3) · neue §7-Invaliditätsklasse · Angebot einer zweiten Discovery-Ebene über die Zwei-Ebenen-Struktur hinaus · Embedding/Vector/Such-Dienst (AD-13) · proprietäre Link-/Search-Datenbank (AD-8) · Renames/Redirects (AD-7d).
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| HAPPY_PATH | Bundle mit Bundleroot, einer Area (`wissensarchitektur/` mit `index.md` + `source-material.md`), 3 Root-Concepts | Jede Area ist aus der Bundleroot erreichbar; jedes Area-Concept aus seiner Area-`index.md`; jedes Root-Concept aus der Bundleroot — gewurzelte Erreichbarkeit; Discovery-Selbsttest liefert keine Verletzung; Suche = grep | N/A |
|
||||
| AREA_UNREACHABLE | Area-`index.md` existiert, ist aber von der Bundleroot nicht verlinkt (kein Root→Area-Pfad) | Discovery-Check → `UNREACHABLE AREA: <area>` als Verletzung — die Area bleibt für die Navigation unsichtbar (AD-9) | Run-FAIL textuell benannt (Instruktions-Selbsttest, kein Validator-Punkt) |
|
||||
| NESTED_AREA_KANDIDAT | Ein Erstellungskandidat mit Ziel `wiki/a/b/concept.md` (zwei Ebenen, Tiefe ≥ 3) bzw. `wiki/a/b/` | **Zwei Zustände:** (1) **Hold-Zeitpunkt** — der Erstellungskandidat wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten: keine Datei, kein Index-Link; (2) **Formel-Befund** — existiert eine Markdown-Datei in Tiefe ≥ 3 unter der Bundleroot (z. B. nachträglich angelegt), meldet die §5.8-Selbsttest-Formel (Lauf B) **`NESTED AREA: <a>`** (erste Ebene); der Sandbox-Nachweis belegt die Detektion auf einem synthetischen Baum mit angelegter Testdatei | Run bricht fürs Gebilde ab: „teilweise erfolgreich" (übrige Einheiten laufen weiter, NFR-4) — *Zwei-Zustands-Klarstellung per menschlicher Renegotiation 2026-08-18 (Loop-3-Decision 2)* |
|
||||
| DISCOVERY_DEMO_ROOT_AREA_LINK | Neues Root-Concept, zusätzlich überdacht in das `source-material.md`-Area-Concept in §5.6-Form verlinkt | Root-Concept ist aus Bundleroot erreichbar; zusätzlicher (rein informierender) Link von der Area aus — kein MOVE, konsolidierte Zwei-Ebenen-Kartografie bleibt | N/A |
|
||||
| SEARCH_GREP | Consumer führt textuelle Suche nach Begriff `<term>` aus | `grep -n <term> wiki/`-Suche als konsumenten-/extern-seitige Antwort; keine Such-Infrastruktur/Bundle (AD-8, AD-13) | N/A |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/compiler.md` — **mutiert**: neue **§5.8 „Progressive Discovery über `index.md` (Story 2.5)"** (nach §5.7 ≈ Z.200, vor §6): (1) Discovery-Pfad — Bundleroot `wiki/index.md` → Area-`index.md` (frontmatterlos) → Area-Concepts in gepinnter §5.6-Form; Root-Concepts direkt aus der Bundleroot (§5.7 Pkt. 5, AD-9/FR-11); (2) **gewurzelte Erreichbarkeit** als deterministisches Discovery-Kriterium + re-executierbarer Selbsttest — jede Area muss aus `wiki/index.md` verlinkt sein (Root→Area, AD-9); Verletzung → `UNREACHABLE AREA: <area>` (textuell benannter Instruktions-Selbsttest-Befund, Run-FAIL gemäß §5.6-Pkt.-4-analoger NFR-4-Regel); die Area→Concept-Verlinkung ist durch Validator Punkt 11 mechanisch abgedeckt (`Concept nicht verlinkt=<concept>`) und wird hier nicht dupliziert; die §5.6-Formeln (Z.133–166) decken die Link-Form weiter ab; **verlinkt = Ziel in gepinnter §5.6-Form `(a/index.md` bzw. `(./a/index.md` — das `./`-Präfix ist von der Erreichbarkeits-Formel toleriert (die Form-Check-Exklusion `^\.` in §5.6 Pkt. 3 zählt `./`-Ziele nicht als Formverletzung, L2-6-Erkenntnis); (3) **konsolidierte Zwei-Ebenen-Kartografie** (antwortet Defer F-07): Root + eine Area-Ebene; **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** — `wiki/a/b/`-Kandidat (Erstellungskandidat oder Discovery-Ziel) wird angehalten (keine Datei, kein Index-Link, Meldung `NESTED AREA: <area>`, Run „teilweise erfolgreich"); §3.2 bleibt der Dateikollision bestehender Concepts vorbehalten; (4) **Suche = Consumer-grep** (`grep`/`ripgrep` über `wiki/`, AD-13 — keine Such-Datenbank, kein Embedding). Nachgeführt: §7 (Story-2.5-Vorbehalt auf „Suche"-Rest gekürzt — die Vorbehalt-Zeile lag in der Baseline `main` bei Z. 253, nach dem §5.8-Einschub bei Z. 285), §8-Revisionslog 2.3 + Normreferenzen AD-9/FR-11/AD-13/NFR-3. Kein Vertrag-/Validator-/raw-Change (AD-3); keine neue §7-Klasse.
|
||||
- `wiki/log.md` — **append**: Eintrag (Vertrag-§5-Format) mit Discovery-Semantik, Zwei-Ebenen-Kartografie (F-07 geschlossen), `sprint-status`-Wechsel `2-5-progressive-discovery-über-index-md-bereitstellen` `backlog` → `in-progress`, Selbsttest-Beleg (keine `UNREACHABLE`-Verletzung).
|
||||
- `_bmad-output/implementation-artifacts/deferred-work.md` — **mutiert**: F-07-Eintrag (`source_spec` bei L87; `status:`-Zeile bei L90) `status:` → `umgesetzt (2026-08-18, Story 2.5 — konsolidierte Zwei-Ebenen-Kartografie, §5.8)` (append-only); die drei „Home: …ab Story 2.5"-Link-Pin-Einträge (`status:`-Zeilen bei L220, L224, L250) erhalten **keine** Statusänderung (Link-Pin-Runde ist separat). `sprint-status.yaml`: Key `2-5-…` → **in-progress**.
|
||||
- `wiki/index.md`, `wiki/wissensarchitektur/*`, 3 Root-Concepts, `schema/wiki-compiler.md`, `schema/validator.md`, `raw/…` — **read-only**: keine MOVE-/Inhaltsänderung an Concepts oder `index.md` (Kuratierung/AD-7d ist Epic-3-Nähe); optional: ein neues Root-Concept als Discovery-Demo (angelegt in Bundleroot-Form, kein MOVE).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/compiler.md` — §5.8 anlegen (Discovery-Pfad, Erreichbarkeits-Kriterium + Selbsttest, konsolidierte Zwei-Ebenen-Kartografie mit F-07-Antwort über den §5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3), Suche = Consumer-grep) + §7 Z.253 gekürzt + §8 Revisionslog 2.3 + Normreferenzen (AD-9/FR-11/AD-13/NFR-3). Kein Vertrag-/Validator-/raw-Change.
|
||||
- [x] `wiki/log.md` — Eintrag (§5-Format) mit Discovery-Semantik, F-07-Schluss, Statuswechsel, Selbsttest-Beleg.
|
||||
- [x] `deferred-work.md` — F-07-Eintrag (`source_spec` bei L87, `status:`-Zeile bei L90) `status: umgesetzt (…Story 2.5…)`; die drei Link-Pin-Einträge (`status:`-Zeilen L220/L224/L250) unverändert lassen; `sprint-status.yaml` — Key `2-5-…` → `in-progress`.
|
||||
- [x] Discoverability-/Edge-Tests im Sandbox-/tmp-Baum (I/O-Matrix): gewurzelte Erreichbarkeit (kein `UNREACHABLE`), AREA_UNREACHABLE-Negativ-Test (Area ohne Root-Link), NESTED_AREA-Kandidat `wiki/a/b/` → §5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3).
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given ein Bundle mit mehreren Areas, when ein Consumer die Navigation startet, then liest er zunächst die Bundle-Root `wiki/index.md` und dann die relevanten Area-`index.md` (AD-9) — gewurzelte Erreichbarkeit ist instruktionsseitig verankert und deterministisch prüfbar (Discovery-Selbsttest, §5.8-Pkt.-2-Formel an Run-Nachweis gebunden).
|
||||
- Given die Hierarchie, when ein Concept neu angelegt wird, then wird es passend in `index.md` des zugehörigen Bereichs verlinkt (AD-9, A0-10) — bestehende §5.3/§5.7-Regel bleibt; §5.8 erläutert die Discovery-Semantik (Area-Concept in Area-`index.md` — mechanisch abgedeckt durch Validator Punkt 11 —, Root-Concept in Bundleroot).
|
||||
- Given eine Suche, when der Consumer sie nutzt, then ist sie klar extern bzw. Consumer-seitig (grep/ripgrep über `wiki/`, AD-13) — die Discovery braucht keine proprietäre Datenbank (AD-9, FR-11).
|
||||
- Given ein Verzeichnis unter `wiki/`, when es zwei Ebenen tief ist (`wiki/a/b/`), then ist es **keine zugelassene Anlageform** — der Erstellungskandidat wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten (keine Datei, kein Index-Link, Meldung `NESTED AREA: <area>`, Run „teilweise erfolgreich"); Zwei-Ebenen-Kartografie bleibt ($5.8 Pkt. 3).
|
||||
- Given die Instruktion, when geprüft, then ist §5.8 der einzige Discovery-Instruktions-Ort (D-3), §5.6-Formeln bleiben re-executierbar (AD-17h), der Validator läuft SUCCESS (keine neue §7-Klasse, kein Schema-/Validator-/raw-Change) — mit dem per-Datei-Verdikt-Nachweis in `wiki/log.md` belegt.
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- **2026-08-18 (Erstellung):** Initiale Approve-Baseline.
|
||||
- **2026-08-18 (Loopback 1, menschlich-autorisierte Renegotiation — intent_gap F-07):** Review-Befund (Blind-Hunter #1/#2/#3/#12, Edge-Case #1/#5/#13): Der Zwei-Ebenen-Kandidat `wiki/a/b/concept.md` war mechanisch nicht erfassbar — die §5.8-Selbsttest-Formel (nur `index.md`-Scan) lieferte dafür keine Meldung, und der benannte Träger **§3.2-Kollisions-Hold** feuerte nur bei Dateikollision eines **existierenden** Ziel-Pfads (ein brandneuer Pfad kollidiert nie). Korrektur (Option A): Der Zwei-Ebenen-Hold wird **§5.8-lokal** verankert („§5.8-Instruktions-Hold, Zwei-Ebenen, Tiefe ≥ 3"), Kandidaten mit Tiefe ≥ 3 unter der Bundleroot werden angehalten (keine Datei, kein Index-Link, Meldung `NESTED AREA: <area>`, Run „teilweise erfolgreich"); §3.2 bleibt der Dateikollision bestehender Concepts vorbehalten. **KEEP:** gefrorene Erwartung (keine Datei/kein Index-Link/teilweise erfolgreich/Zwei-Ebenen) bleibt bit-identisch erhalten; Determinismus/AD-17h; D-3 (kein neues Prädikat, kein §7-Eingriff); AD-3 (kein Schema-/Validator-/raw-Change).
|
||||
- **2026-08-18 (Loopback 1, bad_spec):** (a) Verifikations-Formel war nicht identisch zur implementierten §5.8-Formel und schwächer (VG #1, BH #4) — auf byte-identische §5.8-Pkt.-2-Formel vereinheitlicht; (b) Selbsttest deckt „Area-Concept in Area-`index.md`" nicht (Intention Z.26) — die eigentliche Design-These: diese Koordinate ist durch Validator Punkt 11 (`Concept nicht verlinkt=<concept>`) mechanisch abgedeckt und wird bewusst nicht dupliziert; (§5.8-Pkt.-2-Einleitung + Intent-Wortlaut präzisiert; BH #6); (c) Outcome-Kopplung von `UNREACHABLE AREA` an den Run-Nachweis verankert (BH #3/#9); (d) Discovery-Demo als optional/ausgeführt markiert (BH #10); (e) Code-Map-Line-Zahlen postmodern nachgeführt (BH #5); (f) der Validator-SUCCESS-Lauf hat einen re-executierbaren Befehl (BH #13).
|
||||
- **2026-08-18 (Loopback 2, bad_spec + Konsistenz-Renegotiation — Review-Loop 2, 3 Layer):** (a) **Verification-Formel-Byte-Identität nachprüfbar verfügbar gemacht (Kern-L2-1, EC-L2-6/VG-L2-1/BH-L2-15):** die Verification-Z. 83–85 führen jetzt die §5.8-Pkt.-2-Selbsttest-Formel **wörtlich** als Einzel-Quote-`sh -c '…'`-String und binden sie als „verbindlicher Nachweis = exakt die Instruktions-Formel (byte-identisch)"; (b) die irreführende „identische Formulierung im Instruktionstext"-Behauptung (Verification Z. 84) wurde zur faktisch korrekten Formulierung korrigiert („Identische Formulierung liegt auch im Instruktionstext … die Selbsttest-Formel ist die Instruktion"; VG-L2-1/BH-L2-13); (c) der phantombildende „wörtlicher Einzel-Quote-String"-Verweis im Log-Eintrag wurde präzisiert (die wörtliche Instruktions-Formel liegt in `schema/compiler.md` §5.8 Pkt. 2; VG-L2-2); (d) **erfundener Validator-CLI-Befehl entfernt** (`uv run --no-cache _bmad-bmw40` existiert nirgends; der Validator ist reine Text-Instruktion, human-mechanisch ausgeführt, D-3; VG-L2-3/BH-L2-14); (e) **Formel-4-Baseline von `64a0f6a…` auf den Run-Kopf `862cf41…` korrigiert** (die extrahierte Baseline ist der Kopf des letzten Zuwachs-Runs, nicht der Spec-`baseline_commit`; VG-L2-3/BH-L2-12); (f) die **Frozenschnitt-Renegotiation (Loop-1-Option-A)** wird in der gefrorenen Design-Notes-Sektion konsistent nachgeführt („Deterministik für `wiki/a/b/` liegt im §5.8-Instruktions-Hold", nicht im §3.2-Kollisions-Hold; die §3.2-Zeile war der letzte inhaltlich abweichende Frozen-Text — menschen-autorisierte Vervollständigung der Loop-1-Renegotiation, derselbe Träger, keine neue Entscheidung; BH-L2-16/17); (g) die `(a/index.md`/`(./a/index.md`-Verlinkungs-Koordinate wird nun explizit als „gepinnte §5.6-Form, beide Varianten zulässig" dokumentiert (die §5.6-Formel-2-`^\.`-Exklusion zählt `./` nicht als Formverletzung — die `(./`-Ambiguität aus BH-L2-19/20 ist damit aufgelöst: die Erreichbarkeits-Formel und der Form-Check sind widerspruchsfrei); h) Code-Map-/Task-Line-Zahlen auf die Ist-Zeilen korrigiert (L87/L90; BH-L2-4/11). **KEEP (Constraints):** gefrorene Erwartungen, Determinismus/AD-17h, D-3, AD-3. **KEEP (Code, muss die Re-Derivation überleben):** die §5.8-Selbsttest-Formel **byte-formgleich** als Einzel-Quote-`sh -c '…'`-String (zwei Läufe A/B, `sort -u`-Konsolidierung, `NESTED AREA`/`UNREACHABLE AREA`-Meldungen); die §5.8-Sektion nach §5.7 vor §6 mit Revisionslog 2.3 + §7-Z.253-Kürzung auf „Suche"-Rest; Suche=Consumer-grep (Pkt. 4); Discovery-Demo optional kein MOVE (Pkt. 5); log.md-Eintrag im Vertrag-§5-Format inkl. Selbsttest-Beleg; deferred-F-07 `status: umgesetzt`; sprint `2-5-…` → in-progress. **Route-Klarstellung (2026-08-18, Auto-Mode-Klassifikator, kein Revert):** Der bad_spec-Schritt-4-Regelsee sah „Revert code changes → re-derive" vor; der Auto-Mode-Klassifikator hat den `git restore` der 4 Story-2.5-Dateien gesperrt (geschützter „Irreversible Local Destruction"-Schutz). Ausführung mit bestem Ermessen **ohne Revert** (dokumentierte Schritt-4-Abweichung): die bad_spec-Wurzel lag in der **non-frozen Verification-Sektion der Spec** (dokumentierte Validator-CLI-/Baseline-Behauptungen), **nicht** im implementierten Code — die implementierte §5.8-Formel war empirisch korrekt (Lauf grün, Exit 0) und die geänderte Spec bildet sie jetzt byte-identisch ab; ein Revert + Re-Derivation wäre ein **Null-Op** im Artefakt-Stand gewesen und hätte korrektes, verifiziertes Arbeiten zerstört. Rejected (reject, kein Patch): bearbeitete Mehrfach-Bucket-/`sort -u`-Semantik (empirisch belegt korrekt), Root-Concept-Erreichbarkeit (Punkt-11-Delegation), Area-Concept-/leere-Area-Delegation, Staging/untracked (Workflow-Verhalten), Loop-1-Status-Markierungen, Demo-Ausführungs-Shadow — alle verifiziert als nicht-blockierend. Deferred: F-08/.MD-Case, Run-FAIL-Niveau von `NESTED` — vorbestehend, kein Story-2.5-Blocker.
|
||||
|
||||
- **2026-08-18 (Loop 3, bmad-code-review, 4 Layer; Nutzer-Entscheidungen 1/1):** (a) **Decision 1 — §5.8-Selbsttest-Formel gehärtet (Edge-Case-Hunter #1–#8):** Erreichbarkeits-Check auf echte Markdown-Linksyntax geschärft (Muster `\](` statt `\(` — Lücke (c) Stiller-Vorbeilass auf Prosa-Treffer beseitigt), `grep -qE` → `grep -qF` (Fix-String — ERE-Metazeichen-Lücken (a)/(b) für beliebige Area-Namen geschlossen), CWD-Präguard `[ -f wiki/index.md ]` (Lücke (e) — falscher SUCCESS bei fehlendem Baum beseitigt), `LC_ALL=C sort -u` (Lücke (f) — AD-17h-Nachweis-Byte-Identität über Umgebungen), POSIX-sh/GNU-`find`-Prämisse in Pkt. 2 explizit dokumentiert (Lücke (g)); Meldungstokens `UNREACHABLE AREA: <area>` / `NESTED AREA: <a>` bit-identisch erhalten (frozen I/O-Matrix intakt); die gehärtete Formel wird **byte-identisch** in dieser Verification-Sektion gespiegelt (Pkt. 1) und der Log-Selbsttest-Beleg aktualisiert. (b) **Decision 2 — frozen-Matrix-Zeile `NESTED_AREA_KANDIDAT` Zwei-Zustands-Klarstellung (menschlich-autorisierte Renegotiation, VG #4):** Hold-Zeitpunkt (Kandidat angehalten, keine Datei, kein Index-Link) von der Formel-Meldung (`NESTED AREA: <a>` für existierende Tiefe-≥-3-Dateien, Sandbox-Nachweis = synthetischer Baum) getrennt — keine gefrorene Erwartung geändert. (c) **16 Patches umgesetzt** (s. Review-Findings-Sektion): §5.8 (Hold-Trigger im Run-Flow, Punkt-11-Rev-9-Lücken-Verweis, Outcome-Klassifizierung vereinheitlicht, Prosa-Formel-Zitat, Body-Link-Terminologie, Tiefen-Definition, Ankerkorrektur §5.3 Pkt. 3, Consumer-grep-Beispiel), log.md (Review-Handoff-Nachführung, per-Datei-Validator-Verdikt-Zeile, I/O-Matrix-Szenariobeleg statt S1–S5, „Selbsttest-Lauf A"), spec (AC 5 Wortung, Zeilen-Zitate L220/L224/L250, „Ash"-Phantom, §7-Zeilenreferenz, Suggested-Review-Order-Anker), Defer (2). **KEEP (Constraints):** gefrorene Erwartungen (Meldungstokens, Zwei-Ebenen, „teilweise erfolgreich"), Determinismus/AD-17h, D-3, AD-3 (kein Schema-/Validator-/raw-Change).
|
||||
|
||||
## Design Notes
|
||||
|
||||
**D-3-Begründung (§5.8 statt §7-Erweiterung):** Die progressive Discovery ist laut §7 Z.253 explizit ein Story-2.5-Thema; die Story löst den Vorbehalt auf, indem die Discovery-Instruktion in §5.8 wandert. Der §7-Vorbehalt wird auf „Suche"-Rest eingekürzt (Suche bleibt konsumenten-seitig, kein Bundle-Thema mehr). Keine Normtext-Änderung am §7-Katalog/Validator (AD-3). **F-07-Antwort (konsolidierte Zwei-Ebenen-Kartografie):** Verschachtelte Areas hätten eine Vertrags-/Validator-Änderung erfordert (AD-3 read-only) und wären eine zweite Discovery-Ebene; die Deterministik für `wiki/a/b/` liegt im existierenden **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** — Loopback-1-Renegotiation (menschen-autorisierte Option A): Träger ist §5.8-lokal, **nicht** der §3.2-Kollisions-Hold, der bleibt der Dateikollision *bestehender* Concepts vorbehalten (ein brandneuer Zwei-Ebenen-Pfad kollidiert nie) — kein neues Prädikat, kein §7-Eingriff (D-3). **Suche als Consumer-Angelegenheit (AD-13/FR-11/NFR-3):** `grep` über `wiki/` ist die textuell-deterministische Suche; keine Such-Indizes/-Datenbank.
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands (re-executierbar, ab Workspace-Root):**
|
||||
|
||||
1. **Discovery-Selbsttest (neu, §5.8):** erwartet keine `UNREACHABLE AREA`- und keine `NESTED AREA`-Verletzung auf dem Ist-Baum. Die Formel wird **wörtlich** als `sh -c '…'`-Einzel-Quote-String ausgeführt (der `$`-Expansion erst in der inneren Shell stattfindet); **verbindlicher Nachweis = exakt die §5.8-Pkt.-2-Selbsttest-Formel von `schema/compiler.md` §5.8 Pkt. 2 (byte-identisch, wörtlich übernommen):**
|
||||
`sh -c '[ -f wiki/index.md ] || { echo "SELBSTTEST-SETUP-Fehler: Workspace-Root (wiki/index.md fehlt)"; exit 1; }; find wiki -mindepth 2 -name index.md | while IFS= read -r f; do a="${f#wiki/}"; a="${a%/index.md}"; case "$a" in */*) continue;; esac; grep -qF "]($a/index.md" wiki/index.md || grep -qF "](./$a/index.md" wiki/index.md || echo "UNREACHABLE AREA: $a"; done; find wiki -mindepth 3 -type f -name "*.md" | LC_ALL=C sort -u | while IFS= read -r f; do d="${f#wiki/}"; a="${d%%/*}"; echo "NESTED AREA: $a"; done | LC_ALL=C sort -u'`
|
||||
(Identische Formulierung liegt auch im Instruktionstext `schema/compiler.md` §5.8 Pkt. 2 — die Selbsttest-Formel ist die Instruktion; die einzelfall-spezifischen Sandbox-Negativ-Tests `UNREACHABLE AREA`/`NESTED AREA` werden als Selbsttest-Beleg im `log.md`-Eintrag dokumentiert (Sandbox-Nachweis auf einem synthetischen Baum mit angelegter Testdatei, s. Loop-3-Decision-2-Zwei-Zustands-Klarstellung). Der Live-Baum liefert hier keine Ausgabe, Exit `0`; Ausführung außerhalb der Workspace-Root liefert `SELBSTTEST-SETUP-Fehler: …` + Exit `1` (CWD-Präguard, Loop-3-Decision-1).)
|
||||
2. **§5.6-Formeln (unverändert re-executierbar):** Form 2 (Form-Check) `0` (Exit `0`), Form 3 (Dangling-Check) keine Ausgabe; Formel 4 `38 ≡ 38` — Ist-Zählung ≡ Extraktion aus dem **Run-Kopf `862cf41…`** (Baseline-Commit des letzten Zuwachs-Runs, §5.6 Pkt. 4; Story 2.5 erzeugt keinen neuen Zuwachs-Run, Formel 4 bleibt passierbar).
|
||||
3. **Validator-Lauf:** alle 7 `wiki/`-Dateien SUCCESS (Punkte 1/2/6/7/8/9/10/11/12/13/14, EC-1) — unverändert zur Story 2.4; kein Validator-/Vertrags-Change. Der Validator ist eine **reine Text-Instruktion** (`schema/validator.md`), die der Producer human-mechanisch ausführt (D-3 — es gibt **keinen** `uv`-Invoker/keinen CLI-Befehl); das Verdikt je Datei wird als Ausführungs-Nachweis im `log.md`-Eintrag geführt.
|
||||
|
||||
**Manual checks:**
|
||||
- §7 (Z. 285; in der Baseline `main` Z. 253) auf „Suche"-Rest gekürzt, Discovery in §5.8 verankert; kein Schema-/Validator-/raw-Diff; `log.md`-Eintrag datiert (2026-08-18) mit Discovery-Semantik + F-07-Schluss + Statuswechsel; `deferred-work.md`-F-07-Eintrag geschlossen (append-only); `sprint-status.yaml` konsistent.
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Discovery-Instruktion (§5.8, Kern der Story)**
|
||||
|
||||
- Einstieg: die neue Discovery-Sektion — gewurzelte Erreichbarkeit + re-executierbarer Selbsttest.
|
||||
[`compiler.md:202`](../../../schema/compiler.md#L202)
|
||||
|
||||
- Die deterministische Selbsttest-Formel (zwei Läufe A/B, `sort -u`-Konsolidierung) — verbindlicher Nachweis.
|
||||
[`compiler.md:216`](../../../schema/compiler.md#L216)
|
||||
|
||||
- Konsolidierte Zwei-Ebenen-Kartografie + §5.8-Instruktions-Hold (F-07-Antwort, tieferer Zip) — angehaltene Kandidaten, „teilweise erfolgreich".
|
||||
[`compiler.md:230`](../../../schema/compiler.md#L230)
|
||||
|
||||
- Suche = Consumer-grep (Pkt. 4, AD-13) — keine Such-Datenbank, kein Index-Datei-Format.
|
||||
[`compiler.md:231`](../../../schema/compiler.md#L231)
|
||||
|
||||
- Das §5.8-Selbsttest-Beleg-Niveau schließt die erreichbare Path-Prüfung ab.
|
||||
[`compiler.md:227`](../../../schema/compiler.md#L227)
|
||||
|
||||
**Verifikation & Nachweis-Ebene**
|
||||
|
||||
- Der §5.8-Verification-Block — verbindliche Formel-Byte-Identität + erwarteter Nachweis.
|
||||
[`spec-2-5-…:84`](./spec-2-5-progressive-discovery-über-index-md-bereitstellen.md#L84)
|
||||
|
||||
**Status- & Tracking-Ebene**
|
||||
|
||||
- Semantik des Sprint-Status (in-progress → review-Handoff).
|
||||
[`sprint-status.yaml:50`](../../../_bmad-output/implementation-artifacts/sprint-status.yaml#L50)
|
||||
|
||||
## Review Findings (bmad-code-review, 2026-08-18 — Loop 3, 4 Layer)
|
||||
|
||||
### Decision-Needed
|
||||
|
||||
- [x] [Review][Decision] §5.8-Selbsttest-Formel: realistische Edge-Case-Lücken (Edge-Case-Hunter #1–#8) — die gepinnte Formel (Z. 216) ist fragil gegen: (a) Area-Namen mit Leerzeichen (`for f in $(find …)` splittet den Pfad → korrektt verlinkte Area erzeugt je Wortteil falsche `UNREACHABLE AREA`), (b) ERE-Metazeichen im Area-Namen (`.`, `*`, `+` unescaped in `grep -qE` → unverlinkte Area besteht still, weil ein Link einer anderen Area den Regex trifft; unbalanciertes `(`/`[` → Regex-Fehler nur in stderr), (c) Prosa-Ausdruck `(a/index.md` ohne Markdown-Linksyntax `](` in der Bundleroot besteht den Erreichbarkeits-Check still (Muster `\(` statt `\](`), (d) Groß-/Kleinschreibungs-Abweichung Verzeichnis↔Link (win32, F-08-Umfeld), (e) Ausführung außerhalb der Workspace-Root → nur stderr, Exit 0 = falscher SUCCESS statt Setup-Befund, (f) `sort -u` ohne `LC_ALL=C` → meldungsreihenfolge-Umgebungsabhängigkeit (AD-17h-Byte-Identität der Nachweise bricht), (g) implizite POSIX-`sh`/GNU-`find`-Prämisse (NFR-1/NFR-5) nicht dokumentiert. Minderung im Ist-Baum: Area-Namen sind kebab-case-Slugs (§5.1 Pkt. 1, AD-7a) → (a)/(b)/(d) sind für konforme Bäume strukturell nicht erreichbar; verbleibende reale Lücken: (c) Stiller-Vorbeilass auf Prosa-Treffer, (e) falscher SUCCESS bei falschem CWD, (f) Nachweis-Byte-Identität über Umgebungen. Ein Formel-Change bricht die byte-identische Spec↔compiler-Spiegelung (Verification Pkt. 1) und den Log-Selbsttest-Beleg — beides müsste neu belegt werden. **Option 1:** Formel härten (z. B. `grep -qF -- "(<a>/index.md"` + `"(./<a>/index.md"`, Muster auf `\](` schärfen, CWD-Präguard, `LC_ALL=C sort -u`, POSIX-sh-Prämisse in Pkt. 2 dokumentieren) + byte-identisch in der Spec neu spiegeln + Log-Beleg aktualisieren. **Option 2:** Formel unverändert lassen + Prämissen explizit dokumentieren (kebab-case-Area-Namen nach §5.1/AD-7a, Ausführung ab Workspace-Root, POSIX-sh/GNU-Tools-Umgebung, C-Locale) — Lücken (c)/(e) bleiben dann als bekannt-konservativ dokumentiert. — **Aufgelöst (Nutzer, 2026-08-18, Option 1):** Formel härten — (a) Erreichbarkeits-Check auf echte Markdown-Linksyntax `\](` geschärft (Lücke (c) Stiller-Vorbeilass beseitigt), (b) `grep -qF` (Fix-String statt ERE — Metazeichen-Lücken (a)/(b) für beliebige Area-Namen geschlossen), (c) CWD-Präguard `[ -f wiki/index.md ]` (Lücke (e) falscher SUCCESS beseitigt), (d) `LC_ALL=C sort -u` (Lücke (f) AD-17h-Byte-Identität über Umgebungen), (e) POSIX-sh/GNU-Prämisse in Pkt. 2 dokumentiert (Lücke (g)); Meldungstokens `UNREACHABLE AREA: <area>` / `NESTED AREA: <a>` bit-identisch erhalten (frozen I/O-Matrix intakt); byte-identische Spec↔compiler-Spiegelung + Log-Selbsttest-Beleg neu belegt (Patches unten).
|
||||
- [x] [Review][Decision] Gefrorene I/O-Matrix-Zeile `NESTED_AREA_KANDIDAT` ist mechanisch selbstwidersprüchlich (VG #4, BH #12) — die Zeile verlangt zugleich „Kandidat wird angehalten — **keine Datei**, kein Index-Link" und „Meldung `NESTED AREA: <area>`"; unter der gepinnten Formel (Lauf B: `find wiki -mindepth 3 -type f -name "*.md"`) kann die Meldung aber nur entstehen, wenn eine Datei in Tiefe ≥ 3 **existiert**. Der Log-Sandbox-Nachweis („Kandidaten → `NESTED AREA: a`") ist nur mit angelegten Testdateien möglich. Der §5.8-Text (Pkt. 2/3) definiert `NESTED AREA` ausschließlich als Formel-Output und unterscheidet nicht zwischen dem **Hold-Zeitpunkt** (Producer hält den Kandidaten an, keine Datei) und dem **nachträglichen Formel-Befund** (existierende Tiefe-≥-3-Datei wird gemeldet). Die gefrorene Matrix ist nur per menschlicher Renegotiation änderbar. **Option 1:** Renegotiation der Matrix-Zeile — Zwei-Zustands-Klarstellung (Hold = keine Datei für den Kandidaten; `NESTED AREA` = Formel-Befund gegen bestehende Tiefe-≥-3-Dateien; Sandbox-Nachweis = Formel-Detektion auf synthetischem Baum). **Option 2:** Matrix bleibt frozen; Klarstellung nur in den nicht-gefrorenen Sektionen (§5.8 Pkt. 2/3 + Verification) — die Matrix-Zeile bleibt als Änderungskandidat für die nächste Renegotiationsrunde notiert (Story-2.4-Präzedenz für frozen-Defizite). — **Aufgelöst (Nutzer, 2026-08-18, Option 1, menschlich-autorisierte Renegotiation):** Matrix-Zeile auf die Zwei-Zustands-Klarstellung umgestellt (Hold-Zeitpunkt = keine Datei für den Kandidaten; `NESTED AREA` = Formel-Befund gegen bestehende Tiefe-≥-3-Dateien; Sandbox-Nachweis = Detektion auf synthetischem Baum). Keine gefrorene Erwartung geändert (keine Datei / kein Index-Link / Meldung / „teilweise erfolgreich" bleiben bit-identisch erhalten) — die bereits gelebte Nachweis-Semantik wird nur explizit.
|
||||
|
||||
### Patch
|
||||
|
||||
- [x] [Review][Patch] §5.8-Instruktions-Hold hat keinen definierten Trigger-Punkt im Run-Flow — VG #5: §5.8 Pkt. 3 sagt, der Hold „hält Kandidaten an" (Erstellungskandidat oder Discovery-Ziel), aber die fixe Ablaufstruktur (§0: Input → Interpretieren → Reconcile → Synthetisieren → Mutieren → Validieren) enthält keinen Schritt, an dem er auslöst; §5.7-Routing kann Tiefe ≥ 3 strukturell nie erzeugen. Im Ist-Text ist der Hold faktisch nur der nachträgliche Baum-Zustands-Check der Selbsttest-Formel. Fix: Trigger auf den Mutieren-Schritt verankern (§5/§5.8 Pkt. 3): vor Anlage eines Ziel-Pfads in Tiefe ≥ 3 unter der Bundleroot feuert der Hold (keine Datei, kein Index-Link, Meldung `NESTED AREA: <a>`, Run „teilweise erfolgreich"); die Selbsttest-Formel bleibt der nachträgliche Baum-Check. [schema/compiler.md:230]
|
||||
- [x] [Review][Patch] Sprint-Status-Pfad im Log unvollständig — BH #2 + EC #9 + VG #2 + AA #1: der 2.5-Log-Eintrag dokumentiert `backlog → in-progress` („dieser Statuswechsel findet mit diesem Eintrag statt"), der Diff setzt den Key jedoch direkt `backlog → review`; der Review-Handoff wird nirgends als eigener Statusschritt protokolliert (Story-2.4-Präzedenz im selben File führt das Handoff explizit nach; Workflow-Kommentar `sprint-status.yaml` Z. 29). Fix: Log-Eintrag um die Handoff-Nachführung ergänzen (Analogie Story-2.4-Eintrag: „Review-Handoff, dieser Eintrag"; die gefrorene `→ in-progress`-Vorgabe beschreibt den Implementierungsstand). [wiki/log.md:4]
|
||||
- [x] [Review][Patch] Validator-SUCCESS-Beleg fehlt im Log-Eintrag, den die Spec als Ausführungs-Nachweis benennt — AA #2: Spec-Verification Pkt. 3 verspricht „das Verdikt je Datei wird als Ausführungs-Nachweis im `log.md`-Eintrag geführt" (7 `wiki/`-Dateien SUCCESS, Punkte 1/2/6/7/8/9/10/11/12/13/14, EC-1); der 2.5-Log-Eintrag stützt sich implizit auf „unverändert zur Story 2.4" und trägt keine per-Datei-Verdikt-Zeile. Daneben: AC 5 (Z. 67) verlangt „re-executierbarer Validator-Befehl (BH13)" — nach der Loop-2-Korrektur (erfundener CLI-Befehl entfernt; Validator = human-mechanische Text-Instruktion) ist die Wortung nicht mehr erfüllbar und „BH13" ein hängender Verweis. Fix: (a) Log-Eintrag um die per-Datei-Verdikt-Zeile ergänzen; (b) AC 5 (nicht-gefroren) auf „mit dem per-Datei-Verdikt-Nachweis in `wiki/log.md` belegt" umstellen. [wiki/log.md:4, spec Z. 67]
|
||||
- [x] [Review][Patch] Consumer-Suchbeispiel `grep -n <term> wiki/` nicht ausführbar — VG #9: nicht-rekursives `grep -n` auf ein Verzeichnis schlägt fehl (`grep: wiki/: Is a directory`, Exit 2, verifiziert); nur `grep -rn`/ripgrep funktioniert. Fix (nicht-gefrorene Seite): §5.8 Pkt. 4 das rekursive Beispiel (`grep -rn <term> wiki/` bzw. ripgrep) als primäre Beispielform voranstellen; die frozen-Matrix-Zeile `SEARCH_GREP` bleibt Änderungskandidat (s. Defer, frozen-Text-Kandidaten). [schema/compiler.md:231]
|
||||
- [x] [Review][Patch] „Ash"-Phantomreferenz in der Suggested Review Order — BH #11 + AA #3: Z. 109 „(kein „Ash"-Ghost mehr)" — `grep -rn "Ash"` liefert im gesamten Repo exakt diese eine Stelle; kein „Ash"-Label/-Datei/-Befund existiert. Unauflösbarer Ghost-Verweis, irreführend in der Review-Navigation. Fix: Satz bereinigen (Phantom-Referenz entfernen). [spec Z. 109]
|
||||
- [x] [Review][Patch] Phantom-Labels ohne Referenz: „S1–S5" im Log + „(BH1/EC1)" im normativen Instruktionstext — BH #13 + VG #6: der 2.5-Log-Eintrag beansprucht „Negativ-Kontrollen (S1–S5) auf dem Sandbox-Baum bestätigt" — S1–S5 sind nirgends definiert (I/O-Matrix-Szenarien tragen andere Namen; nur 2 davon sind negativ); §5.8 Pkt. 2 (B) (Z. 223) zitiert die Review-Layer-Befund-IDs „(BH1/EC1)" in den normativen Instruktionstext, der als einziger Instruktions-Ort (D-3) nirgendwo auf eine Review-Runde verweisen sollte. Fix: (a) Log-Eintrag: Szenario-Namen der I/O-Matrix verwenden (`AREA_UNREACHABLE`, `NESTED_AREA_KANDIDAT`); (b) `(BH1/EC1)`-Zitat aus §5.8 Pkt. 2 (B) entfernen. [wiki/log.md:4, schema/compiler.md:223]
|
||||
- [x] [Review][Patch] Veraltete Zeilen-Zitate auf die drei Link-Pin-Defer-Einträge — BH #3 + VG #10 + AA #4: Tasks Z. 59 „(L219/L223/L249)" und Code Map Z. 51 „`status:` bei L224 … L246/L250" treffen nicht die Ist-`status:`-Zeilen in `deferred-work.md` (Ist: L220 `)`-blinde Extraktion, L224 Cross-Page-Anker, L250 Multi-Line; L246 ist der Status der Image-Eintrags, L219/L223/L249 sind `evidence:`-Zeilen; L246-Hauszuordnung „Deferred from … spec-2-3" zudem ungenau). Der Loop-2-Change-Log (h) behauptet „auf die Ist-Zeilen korrigiert" — korrigiert wurde nur der F-07-Eintrag (L87/L90). Fix: Zeilen-Zitate auf L220/L224/L250 korrigieren; F-07-Verortung Code Map (L87) vs. Tasks (L88) vereinheitlichen. [spec Z. 51, Z. 59]
|
||||
- [x] [Review][Patch] Veraltete Referenz „§7 Z. 253" — BH #4: die Discovery-Vorbehalt-Zeile lag in `main` bei Z. 253, nach dem 32-zeiligen §5.8-Einschub steht sie bei **Z. 285**; spec (Code Map Z. 49, Manual-Checks Z. 91), `wiki/log.md`-Eintrag und Revisionslog 2.3 (compiler.md Z. 317) zitieren „§7 Z. 253" in Präsens-Kontexten, wo der Leser die Ist-Zeile erwartet. Fix: in Präsens-Kontexten die Ist-Zeile ergänzen (Z. 285) oder auf Sektions-Referenz ohne Zeilennummer umstellen. [spec Z. 49/91, wiki/log.md:4, schema/compiler.md:317]
|
||||
- [x] [Review][Patch] Discovery-Demo-Verlinkung terminologisch widersprüchlich — VG #11 + BH #7: §5.8 Pkt. 5 (Z. 232) nennt den zusätzlichen Demo-Link „Index-Link … aus einem bestehenden Area-Concept heraus" — ein Link in der Concept-Body-Datei ist nach §5.6 (Pin gilt für Concept-Bodies und `index.md`-Dateien als getrennte Orte) ein Body-Link, kein Index-Link; die frozen-Matrix-Zeile formuliert die Richtung zusätzlich anders („in das Area-Concept verlinkt"). Fix (nicht-gefrorene Seite): §5.8 Pkt. 5 eindeutig als Body-Link benennen (`[<text>](../<concept>.md)` aus `wiki/wissensarchitektur/source-material.md`, file-relative `../`-Form §5.7 Pkt. 4); frozen-Matrix-Zeile bleibt Änderungskandidat (s. Defer). [schema/compiler.md:232]
|
||||
- [x] [Review][Patch] Inkonsistente Tiefen-Terminologie „zwei Ebenen" vs. „Tiefe ≥ 3" — BH #12: Hold-Name, I/O-Matrix und AC mischen „zwei Ebenen" (Verzeichnisstufen) und „Tiefe ≥ 3" (`find -mindepth 3` = Segment-Ebenen unter der Bundleroot inkl. Datei); aus Prosa allein ist nicht ableitbar, welche Schwelle verbindlich ist. Fix: §5.8 Pkt. 3 um eine definierende Zeile (Tiefe = Segment-Anzahl unter der Bundleroot; `wiki/<a>/<b>/…` = Tiefe ≥ 3 = zwei Verzeichnisstufen plus Datei; Meldung benennt die erste Ebene `<a>`). [schema/compiler.md:230]
|
||||
- [x] [Review][Patch] Falscher Norm-Anker in §5.8 Pkt. 1 — BH #9: Z. 208 „verlinkt die **Root-Concepts** (direkt, §5.7 Pkt. 5)" — §5.7 Pkt. 5 (Z. 199) trägt nur die Area-Pflichten; die Root-Concept-Verlinkungspflicht ist §5.3 Pkt. 3 (Z. 62), den derselbe Absatz einen Satz später korrekt nennt (Z. 212). Fix: Anker auf §5.3 Pkt. 3 korrigieren. [schema/compiler.md:208]
|
||||
- [x] [Review][Patch] Inkongruente Outcome-Klassifizierung in §5.8 Pkt. 2 — VG #13: die Einleitung (Z. 213) sagt „**Run-FAIL-artig** gemäß §5.6-Pkt.-4-**analoger** NFR-4-Regel", das Bullet (Z. 227) „**Run-FAIL** gemäß §5.6 Pkt. 4-analoger NFR-4-Regel" — dieselbe Outcome-Kopplung wird einmal abgemildert, einmal direkt; „-artig … -analog" ist doppelt abgeschwächt. Fix: beide Stellen auf die uneingeschränkte Wortung vereinheitlichen („Run-FAIL gemäß §5.6 Pkt. 4-analoger NFR-4-Regel" — Loop-1-Pkt.-c-Verbindlichkeit). [schema/compiler.md:213/227]
|
||||
- [x] [Review][Patch] Prosa-Formel-Textabweichung in §5.8 Pkt. 2 (B) — BH #10: Z. 223 zitiert `find wiki -mindepth 3 -name "*.md" -type f`, die gepinnte Formel (Z. 216) lautet `find wiki -mindepth 3 -type f -name "*.md"` (Semantik identisch, Wortlaut divergiert von der als verbindlich deklarierten byte-identischen Formel). Fix: Prosa-Zitat an die gepinnte Formel angleichen. [schema/compiler.md:223]
|
||||
- [x] [Review][Patch] Suggested-Review-Order-Self-Link zeigt auf eine Leerzeile — VG #12: `spec-2-5-…:83` (Z. 115) verweist auf die leere Zeile zwischen „Commands" (Z. 82) und Verification-Punkt 1 (Z. 84–86); Ankernummer um eine Zeile verschoben. Fix: Anker auf Z. 84 korrigieren. [spec Z. 115]
|
||||
- [x] [Review][Patch] Englisch-Fremdwort im deutschen Log-Text — BH #15: 2.5-Log-Eintrag mischt „Self-Check-Lauf A" in den konsequent deutschen Text. Fix: „Selbsttest-Lauf A" (bzw. „Lauf (A)"). [wiki/log.md:4]
|
||||
- [x] [Review][Patch] Punkt-11-Delegation benennt die bekannte offene Validator-Lücke nicht — VG #1: §5.8 Pkt. 2 (Z. 213/229), die Spec (AC 2, Code Map) und der Log-Eintrag stützen die Nicht-Duplizierungs-These und den „Validator läuft SUCCESS"-Nachweis auf dem Validator-Punkt-11-Check, ohne den offenen Defer-Finding (deferred-work.md Z. 284–287: ein wörtlicher, mechanischer Punkt-11-Check meldete `Concept nicht verlinkt=wissensarchitektur/source-material`; Behebung = Rev-9-Aktionsitem, open) zu nennen — die SUCCESS-Behauptung ist damit nicht unabhängig überprüfbar. Fix: §5.8 Pkt. 2 (bzw. Pkt. 2-Bullet) um einen Zeigerverweis auf die bekannte Rev-9-Lücke (deferred-work.md) ergänzen; die Lücke selbst bleibt beim Rev-9-Aktionsitem (kein neuer Defer). [schema/compiler.md:213]
|
||||
|
||||
### Defer
|
||||
|
||||
- [x] [Review][Defer] Spec-Frontmatter `status: 'done'` bei offenem Review-Zyklus [spec Z. 5] — deferred, Story-2.4-Präzedenz (deferred-work.md Z. 269–272): `done` erst nach Review-Freigabe; mit dem Abschluss dieses Review-Loops synchron (s. Step 6), kein separates Patch.
|
||||
- [x] [Review][Defer] Frozen-Text-Wortfehl- und Konsistenz-Kandidaten (nur per menschlicher Renegotiation änderbar) [spec Z. 18/42/43] — deferred, Änderungskandidaten für die nächste Renegotiationsrunde (Story-2.4-Präzedenz): (a) Intent Z. 18 „Revisionslog **(3.x)**" — implementiert ist **2.3** (Reihenfolge 2.0/2.1/2.2/2.3); (b) I/O-Matrix `DISCOVERY_DEMO_ROOT_AREA_LINK` Z. 42: „zusätzlich **überdacht** in das Area-Concept" — Wortfehler + Verlinkungsrichtung unauflösbar (nicht-gefrorene Seite s. Patch „Index-Link-Oxymoron"); (c) I/O-Matrix `SEARCH_GREP` Z. 43: `grep -n <term> wiki/` nicht ausführbar (nicht-gefrorene Seite s. Patch „Consumer-Suchbeispiel"); (d) Intent Z. 18 „Kein Interface-/Backend-/Datenbank-**Änderung**" (Grammatik: „Keine … Änderungen").
|
||||
+158
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: 'Autorisierte Validator-Revision 9 — Punkt-11-Area-Lesart formalisieren + gehaltene Rev-8-Patches tragen'
|
||||
type: 'chore'
|
||||
created: '2026-08-18'
|
||||
status: 'done'
|
||||
baseline_commit: ef84309db7ca0090c3e124b8c364c56cc72186f3
|
||||
review_loop_iteration: 0
|
||||
context:
|
||||
- _bmad-output/implementation-artifacts/validator-revision-8-autorisationsrunde-f14-innen-ebenen.md
|
||||
- _bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md
|
||||
---
|
||||
|
||||
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Der Validator (`schema/validator.md`, Rev 8) ist für Epic 2 nur über eine aufgelockerte Lesart konsistent: Punkt 11 verlangt, die Concept-Identität sei „als relativer Bundle-Pfad referenziert", aber die Area-`index.md` verlinkt ihr Area-Concept file-relativ (`source-material.md`) — die wörtliche Bundle-Identität `wissensarchitektur/source-material` kommt im Bereichs-Index nicht vor. Ein wörtlich-mechanischer Rev-8-Check meldete das Live-Concept als „nicht verlinkt". Zusätzlich sind zwei gehaltene Review-Patches (Punkt-4-`resolved=`-Token, Innen-Ebenen-Punkt-6-Fixture-Zeile) ausstehend — die Rev-8-Formalisierung ist damit nicht re-runbar belegt.
|
||||
|
||||
**Approach:** Eine autorisierte Validator-Revision 9 ausführen, die (1) die Punkt-11-Area-Lesart formal trägt (relative OKF-Pfad-Identität, auch file-relativ in der zuständigen Area-`index.md`) und damit die AD-3/D-3-Freeze-Währung wahrt, (2) die beiden gehaltenen Patches als Teil der Revision trägt, (3) Header auf 9 anhebt, Revisionslog (append-only) nachführt und die Zertifizierung (isolierte Fixtures + reales Bundle) mechanisch belegt.
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:**
|
||||
- `schema/validator.md` ist die **einzige** zu ändernde Vertrags-/Validator-Datei. `schema/wiki-compiler.md` (Vertrag, Story 1.3) und `schema/compiler.md` (Instruktion) bleiben **unverändert** — die Rev-9-Lesart verschärft keinen §7-Punkt und fügt **keine neue §7-Invaliditätsklasse** hinzu (kein Punkt 15); die Abschluss-Eigenschaft des §7-Katalogs bleibt gewahrt (F-04-Kultur, AD-1b).
|
||||
- `raw/` (immutable, AD-3), `adapters/`, alle bestehenden `wiki/`-Dateien bleiben unverändert (außer `wiki/log.md`, Zertifizierungs-Nachweis).
|
||||
- Der §8-Revisionslog ist **append-only** — der Rev-9-Eintrag wird angehängt, bestehende Einträge bleiben unangetastet. Die Punkt-11-Normreferenz-Notiz „Story 2.3 (Link-Form)" wird um die Rev-9-Area-Lesart ergänzt (derselbe Normreferenz-Block, append).
|
||||
- Die Formulierung bleibt **rein textuell** (D-3): keine neue Prüfklasse, kein Standalone; die mechanische Re-Exekution folgt den im Revisionslog dokumentierten Formeln.
|
||||
- Datums- und Revisions-Werte nach dem Wiki-Log- und Sprint-Status-Format; die Revisionszahl geht von 8 auf 9 (Header + Revisionslog).
|
||||
|
||||
**Ask First:**
|
||||
- Branch-Wechsel/Merge-Strategie für `validator-rev-9` (aktuell noch nicht zurückgeführt).
|
||||
- Falls die Zertifizierung am Live-Baum Abweichungen zeigt, die nicht durch die Doku-Kultur (wiki/log.md) heilbar sind — vor Fortsetzung HALT.
|
||||
- Die Behandlung der weiteren offenen Epic-2-Items (AI-2-R-1 … R-4: §5.5-rekursiv, §5.8-Tiefe-2, Formel-4-Asymmetrie, §5.8-Reachability) ist **nicht** Teil dieser Revision — bei Scope-Drift Richtung compiler.md HALT.
|
||||
|
||||
**Never:**
|
||||
- Keine Änderung an `raw/`, `adapters/`, `schema/wiki-compiler.md`, `schema/compiler.md` oder den bestehenden `wiki/`-Concept-Dateien.
|
||||
- Kein neuer §7-Punkt, keine Erfindung einer neuen Invaliditätsklasse.
|
||||
- Keine Änderung an gefrorenen/I-O-Matrix-Texten außerhalb des explizit autorisierten Rev-9-Umfangs (kein ad-hoc-Editing).
|
||||
- Keine Bauch-Formulierungen: jede Formulierung wird gegen den realen Bundle-Baum (7 Dateien) und die Fixture-Tabellen in §7 geprüft.
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| POINT11_AREA_LINK | `wiki/wissensarchitektur/index.md` verlinkt `source-material.md` (file-relativ, gepinnte §5.6-Form) | Area-Concept-Identität `wissensarchitektur/source-material` ist gewahrt — Punkt 11 → kein FAIL (SUCCESS) | Verschiebt sich nicht in einen anderen Punkt; kein WARN |
|
||||
| POINT11_WORDING_FAIL | Area + Concept ohne Link (Bundle-Identität nirgends) | `FAIL wiki/… Punkt 11: Index-Regel verletzt (Concept nicht verlinkt=<concept>)` | Identität über Pärchen Area-Präfix + Link-Ziel abgeleitet |
|
||||
| FIXTURE_4A | `sources: [{resource: README.md}]` (existierende Datei an Workspace-Root, außerhalb `raw/`) | `FAIL wiki/x.md Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (resolved=README.md)` — ableitbar aus §3-Punkt-4-Vorlage | Punkt-4-vor-3-Priorität (§6.2): kein Vorab-FAIL durch Punkt 3 |
|
||||
| INNER_LEVEL_KEY | `sources:\n - resource: raw/prd/prd-wow20-2026-08-14.md\n role: x` (sonst-valides Sample, existierende `raw/`-Datei) | `FAIL wiki/x.md Punkt 6: nicht autorisiertes Feld (Key=role) bzw. unautorisierter Key in sources/generated/verified` | Nur Punkt 6 löst aus — Isolations-Prinzip (§7.3) |
|
||||
| LIVE_BUNDLE_REGRESSION | Alle 7 `wiki/`-Dateien gegen den revidierten Validator | weiterhin SUCCESS für alle Dateien (keine neu ausgelösten FAILs) | Keine neue §7-Klasse; Abschluss-Eigenschaft gewahrt |
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `schema/validator.md` — die **einzige** zu ändernde Datei (Rev 9). Anker: §0-Header (Z. 6–8, Revisionszahl 8 → 9 + Letzte-Re-Konsistenz), §3 Punkt-4-Tabelle (Z. 63, Vorlage ohne `resolved=`-Token), §3 Punkt-6-Tabelle (Z. 65, Innen-Ebenen-Verweis vorhanden), §3 Punkt-11-Tabelle (Z. 70, Kern der Area-Lesart), §7.1-Fixtures Punkt 4a/6 (Z. 214/216), §7.3-Fixture-Isolations-Notiz (Z. 263, Innen-Ebenen-Kontext), §8-Normreferenz-Notiz „Story 2.3 (Link-Form)" (Z. 297), §8-Revisionslog (Z. 299–308, append-only).
|
||||
- `_bmad-output/implementation-artifacts/validator-revision-8-autorisationsrunde-f14-innen-ebenen.md` — der Rev-8-Präzedenzfall (Autorisierungskanal, Zertifizierung, Follow-Tracking); formt die Rev-9-Runde strukturell.
|
||||
- `_bmad-output/implementation-artifacts/deferred-work.md` — Z. 184–191: die **gehaltenen Patches 16/17** (Punkt-4-`resolved=`-Token, Innen-Ebenen-Punkt-6-Fixture-Zeile) mit exakter gewünschter Wortform; Z. 279–287: F-02/Rev-9-Aktionsitem-Kontext.
|
||||
- `_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md` — F-02 (Punkt-11-Wortlaut vs. file-relative Area-Linkform), AI-2-R-5 (de-dupliziert mit `code-review-2-1-item-2`), Open question 3 (exakte Formulierung der Area-Lesart).
|
||||
- `wiki/index.md` — Bundleroot (Z. 33–37, Area-Sektion); verlinkt die Area als `(wissensarchitektur/index.md)` — **nur** die Area, nicht das Area-Concept.
|
||||
- `wiki/wissensarchitektur/index.md` — Area-`index.md` (frontmatterlos, Z. 9: file-relativer `(source-material.md)`-Link); beweist die Live-F-02-Lage (Bundle-Identität `wissensarchitektur/source-material` kommt textuell nirgends vor, grep → 0).
|
||||
- `wiki/wissensarchitektur/source-material.md` — das Area-Concept; durch die Layer-6/7-Struktur das vom wörtlichen Rev-8-Punkt-11-Check fälschlich „nicht verlinkt" gemeldete Concept.
|
||||
- `wiki/log.md` — §5-Format-Zertifizierungs-Nachweis (datumsgruppiert 2026-08-16/17/18; Rev-9-Eintrag wird ergänzt).
|
||||
- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Action-Item `code-review-2-1-item-2` (Z. 173–174) + neue AI-2-R-5-Einträge; Status-Nachführung nach Abschluss (je nach Flow).
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution:**
|
||||
- [x] `schema/validator.md` -- Header: `Validator-Revision: 8` → `9`, `Letzte Re-Konsistenz` → 2026-08-18 (Revision 9 — Punkt-11-Area-Lesart; Punkt-4-`resolved=`-Token; Innen-Ebenen-Punkt-6-Fixture-Zeile) -- Anker §0.
|
||||
- [x] `schema/validator.md` -- §3 Punkt-11-Zelle: Area-Lesart formalisieren — „ein Concept ist verlinkt, wenn seine Identität (relativer OKF-Dateipfad ohne `.md`) in der `index.md` des nächsten Vorfahren referenziert ist; für ein Area-Concept genügt die file-relative Referenz in der Area-`index.md`, identitätsstiftend ist das Pärchen (Area-Präfix + Link-Ziel); Root-Concepts wie bisher in der Bundleroot (mit/ohne `.md`-Endung)" -- Kern der Rev-9-Lesart, F-02.
|
||||
- [x] `schema/validator.md` -- §7.1-Fixture: neue Negativ-Fixture 11a „Area `wiki/wissensarchitektur/` mit `index.md`, das Area-Concept `source-material.md` **nicht** verlinkt → `FAIL … Punkt 11: Concept nicht verlinkt=wissensarchitektur/source-material`" + Positiv-Fall dokumentieren -- prüfbare Negative der Area-Lesart.
|
||||
- [x] `schema/validator.md` -- §3 Punkt-4-Vorlage: optionales `resolved=<Pfad>`-Token ergänzen (`…unzulaessiger Pfad (..-Traversal|absolut|URL|Backslash|file://|resolved=<pfad>)`) -- Patch 16/17, Fixture 4a ableitbar machen (§7 „exakt die aus §3").
|
||||
- [x] `schema/validator.md` -- §7.3: echte Negativ-Fixture-Zeile für Innen-Ebenen-Punkt-6 („`sources:\n - resource: raw/…\n role: x` → `FAIL … Punkt 6`") -- Patch 16/17, Rev-8-Formalisierung re-runbar belegen.
|
||||
- [x] `schema/validator.md` -- §8-Revisionslog: Rev-9-Eintrag anhängen (Punkt-11-Area-Lesart, beide Patches, Header-Anhebung; Vertrag unverändert) -- append-only.
|
||||
- [x] `schema/validator.md` -- §8-Normreferenz-Notiz „Story 2.3 (Link-Form)" um die Rev-9-Area-Lesart ergänzen -- Konsistenz der Lesart mit der Pin-Form-Doktrin.
|
||||
- [x] `wiki/log.md` -- Zertifizierungs-Eintrag (datumsgruppiert 2026-08-18): Fixture 4a isoliert FAIL Punkt 4, Innen-Ebenen FAIL Punkt 6, Punkt-11-Area-Lesart-Fixtures, reales Bundle weiterhin 7/7 SUCCESS -- mechanischer Beleg gemäß Validator-Zertifizierungs-Kultur (F-02).
|
||||
- [x] `_bmad-output/implementation-artifacts/sprint-status.yaml` -- Action-Item `code-review-2-1-item-2` + `AI-2-R-5` → `done` (closed + resolution mit Rev-9 + ref auf Rev-9-Runde) -- Tracking-Abschluss.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- Given die autorisierte Rev-9-Runde, when `schema/validator.md` geprüft wird, then Header-Revisionszahl ist 9, der §8-Revisionslog trägt den Rev-9-Eintrag (append-only, bestehende Einträge unangetastet), und keine §7-Klasse wurde neu erzeugt (kein Punkt 15).
|
||||
- Given die Punkt-11-Area-Lesart, when ein Area-Concept file-relativ in seiner Area-`index.md` verlinkt ist (Live: `wissensarchitektur/source-material.md`), then die Bundle-Identität `wissensarchitektur/source-material` ist für Punkt 11 gewahrt (kein FAIL „nicht verlinkt").
|
||||
- Given die gehaltenen Patches, when Fixture 4a isoliert gegen den revidierten Validator ausgeführt wird, then das Verdikt ist ableitbar aus der §3-Punkt-4-Vorlage `…(..-Traversal|absolut|URL|Backslash|file://|resolved=README.md)` → `FAIL … Punkt 4 … (resolved=README.md)`.
|
||||
- Given die gehaltenen Patches, when das Innen-Ebenen-Sample (existierende `raw/`-Datei, `role: x` in `sources`-Eintrag) isoliert geprüft wird, then genau Punkt 6 löst aus (Isolations-Prinzip), mit Fixture-Zeile in §7.3.
|
||||
- Given das reale Bundle (7 `wiki/`-Dateien), when der revidierte Validator den Run ausführt, then alle 7 Dateien bleiben SUCCESS (keine neu ausgelösten FAILs; Abschluss-Eigenschaft des §7-Katalogs gewahrt).
|
||||
- Given `schema/wiki-compiler.md` und `schema/compiler.md`, when der Rev-9-Diff inspiziert wird, then beide bleiben unverändert (AD-3/D-3-Freeze; keine Vertrags-Änderung nötig — Punkt 11 deckt die Area-Lesart bereits vertraglich, §7).
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
<!-- Append-only. Populated by step-04 during review loops. -->
|
||||
|
||||
## Design Notes
|
||||
|
||||
**Warum diese Formulierung (Open question 3 der Retro):** Die Lesart „als relativer Bundle-Pfad referenziert (mit oder ohne `.md`-Endung)" wird für Area-Concepts um die **file-relative** Alternative ergänzt: In der zuständigen Area-`index.md` ist die Referenz des Link-Ziels (`source-material.md`) der **lokale** Verweis auf das Area-Concept; die Bundle-Identität ergibt sich deterministisch als Pärchen `(Area-Präfix = Verzeichnisname der Area-`index.md`, Link-Ziel ohne `.md`)`. Das ist exakt die Datei-Topologie von `wiki/wissensarchitektur/index.md` Z. 9. Root-Concepts (gepinnte §5.6-Form, mit `.md`-Endung) bleiben unverändert — die „genau-eine-Form"-Festlegung der Link-Schreibweise liegt weiterhin bei Story 2.3/§5.6 der Compiler-Instruktion (dem Validator wird sie nicht vorgegeben).
|
||||
|
||||
**Gehaltene Patches als formale Inhalte:** Beide Patches (16/17) sind bereits inhaltlich spezifiziert (deferred-work.md Z. 188–189: Punkt-4-`resolved=<pfad>`-Token, Innen-Ebenen-Punkt-6-Fixture-Zeile). Sie werden durch diese Autorisierung von „gehalten (kein Autorisierungsschlag)" zu „formal getragene autorisierte Inhalte" — gleiche Währung wie die Rev-8-Autorisationsrunde (F-14-Fixture 4a).
|
||||
|
||||
## Verification
|
||||
|
||||
**Commands:**
|
||||
- `grep -nE "Validator-Revision|Revision 9" schema/validator.md` -- expected: Header-Revisionszahl `9` UND Revisionslog-Entrag Rev 9 vorhanden.
|
||||
- `exit 0` für die mechanischen Fixture-Runs (isolierte Samples + Live-Bundle) gemäß Zertifizierungs-Sektion der Rev-9-Runde.
|
||||
- `git diff --name-only <base>..HEAD -- schema/wiki-compiler.md schema/compiler.md raw/ adapters/` -- expected: **keine** Treffer (AD-3/D-3-Freeze gewahrt).
|
||||
|
||||
**Manual checks (if no CLI):**
|
||||
- §7.1-Fixture 11a-Erwartungswert (`FAIL … Concept nicht verlinkt=wissensarchitektur/source-material`) mit der §3-Punkt-11-Zelle (Area-Lesart) abgeglichen → bildet die Ableitung ab.
|
||||
- Fixture-4a-Verdikt (`(resolved=README.md)`) ist aus der §3-Punkt-4-Vorlage ableitbar (kein Inventieren).
|
||||
- `wiki/log.md` trägt den Rev-9-Zertifizierungs-Eintrag (datumsgruppiert 2026-08-18); `sprint-status.yaml`-Action-Items sind `done` geschlossen.
|
||||
|
||||
## Suggested Review Order
|
||||
|
||||
**Area-Lesart (Punkt 11) — Kern der Revision**
|
||||
|
||||
- Einstieg: die formalisierte Area-Lesart — Pärchen (Area-Präfix + Link-Ziel) identitätsstiftend, file-relativ genügt
|
||||
[`validator.md:70`](../../schema/validator.md#L70)
|
||||
|
||||
- Die Normreferenz-Notiz führt die Story-2.3-Formklausel um die Pin-Form-Doktrin nach
|
||||
[`validator.md:304`](../../schema/validator.md#L304)
|
||||
|
||||
- Negativ-Fixture 11a am realen Live-Area-Namen (F-02-Defekt belegt, Isolations-Prinzip)
|
||||
[`validator.md:226`](../../schema/validator.md#L226)
|
||||
|
||||
- Positiv-Gegenfall: file-relativer `](source-material.md)`-Link genügt → SUCCESS
|
||||
[`validator.md:256`](../../schema/validator.md#L256)
|
||||
|
||||
**resolved=-Token (Punkt 4)**
|
||||
|
||||
- Fehlerursachen-Grammatik um das optionale `resolved=<pfad>`-Token erweitert (Patch 16)
|
||||
[`validator.md:63`](../../schema/validator.md#L63)
|
||||
|
||||
- Semantik-Anker: Token feuert nur bei Ablehnung durch aufgelöste Lage außerhalb `raw/`
|
||||
[`validator.md:182`](../../schema/validator.md#L182)
|
||||
|
||||
- Fixture 4/4a — 4a verdikt-ableitbar aus der §3-Vorlage
|
||||
[`validator.md:216`](../../schema/validator.md#L216)
|
||||
|
||||
**Innen-Ebenen-Punkt-6-Fixtures**
|
||||
|
||||
- §7.3-Überschrift trägt die Innen-Ebenen-Punkt-6-Fixtures explizit (Patch 17)
|
||||
[`validator.md:265`](../../schema/validator.md#L265)
|
||||
|
||||
- Negativ-Zeile `role: x` → genau Punkt 6 (Isolations-Prinzip)
|
||||
[`validator.md:281`](../../schema/validator.md#L281)
|
||||
|
||||
- Positiv-Gegenzeile: nur erlaubte Keys → SUCCESS
|
||||
[`validator.md:282`](../../schema/validator.md#L282)
|
||||
|
||||
**Konsistenz & Peripherals**
|
||||
|
||||
- Header: Revisionszahl 9 + Re-Konsistenz-Nachführung
|
||||
[`validator.md:7`](../../schema/validator.md#L7)
|
||||
|
||||
- Revisionslog-Rev-9-Eintrag (append-only, „fünf inhaltliche Änderungen", kein Punkt 15)
|
||||
[`validator.md:316`](../../schema/validator.md#L316)
|
||||
|
||||
- Mechanischer Zertifizierungs-Nachweis inkl. Live-Invariant (2026-08-18)
|
||||
[`log.md:4`](../../wiki/log.md#L4)
|
||||
|
||||
- Tracking-Abschluss der Items `code-review-2-1-item-2` + `epic-2-retro-item-14`
|
||||
[`sprint-status.yaml:170`](sprint-status.yaml#L170)
|
||||
@@ -29,7 +29,7 @@
|
||||
# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
|
||||
# - Retrospective appends its action items to action_items; the status view surfaces open ones
|
||||
generated: 08-14-2026 00:00
|
||||
last_updated: 08-15-2026 04:56
|
||||
last_updated: 08-18-2026 22:00
|
||||
project: wow20
|
||||
project_key: NOKEY
|
||||
tracking_system: file-system
|
||||
@@ -38,17 +38,17 @@ development_status:
|
||||
epic-1: in-progress
|
||||
1-1-kanonischen-workspace-stamm-erstellen: done
|
||||
1-2-sources-lokal-unter-raw-bereitstellen: done
|
||||
1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren: backlog
|
||||
1-4-schema-validierung-für-bundle-implementieren: backlog
|
||||
epic-1-retrospective: optional
|
||||
1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren: done
|
||||
1-4-schema-validierung-für-bundle-implementieren: done
|
||||
epic-1-retrospective: done
|
||||
|
||||
epic-2: backlog
|
||||
2-1-concepts-aus-source-material-erzeugen-okf-konform: backlog
|
||||
2-2-claim-granulare-provenienz-dokumentieren: backlog
|
||||
2-3-concepts-verlinken-eine-erlaubte-linkform: backlog
|
||||
2-4-deterministische-bereichszuordnung-concept-hierarchie: backlog
|
||||
2-5-progressive-discovery-über-index-md-bereitstellen: backlog
|
||||
epic-2-retrospective: optional
|
||||
epic-2: in-progress
|
||||
2-1-concepts-aus-source-material-erzeugen-okf-konform: done
|
||||
2-2-claim-granulare-provenienz-dokumentieren: done
|
||||
2-3-concepts-verlinken-eine-erlaubte-linkform: done
|
||||
2-4-deterministische-bereichszuordnung-concept-hierarchie: done
|
||||
2-5-progressive-discovery-über-index-md-bereitstellen: done
|
||||
epic-2-retrospective: done
|
||||
|
||||
epic-3: backlog
|
||||
3-1-inkrementellen-datenfluss-implementieren-interpret-reconcile: backlog
|
||||
@@ -73,3 +73,161 @@ development_status:
|
||||
5-2-tool-unabhängigen-zugriff-und-agent-lesbarkeit-gewährleisten: backlog
|
||||
5-3-agent-unabhängige-compiler-regeln-dünne-adapter: backlog
|
||||
epic-5-retrospective: optional
|
||||
action_items:
|
||||
- id: "epic-1-retro-item-1-validator-schema-validator-md-mit-autori"
|
||||
epic: 1
|
||||
action: "Validator schema/validator.md mit autorisiertem Vertrag re-konsistieren:
|
||||
at-als-reines-Datum-Toleranz (§4.3/Fixture 14c) beseitigen oder via Story-Verfahren
|
||||
als Vertrags-Aenderung neu autorisieren"
|
||||
owner: "dev+review"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "Option A (Nutzer): Toleranz rueckgaengig — at MUSS volles ISO-8601-Datetime
|
||||
sein; reines Datum => FAIL Punkt 14. schema/validator.md Revision 3; Vertrag
|
||||
unveraendert."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-01"
|
||||
- id: "epic-1-retro-item-2-6-fixtures-ergaenzen-ec-1-existenz-ec-3"
|
||||
epic: 1
|
||||
action: "§6-Fixtures ergaenzen (EC-1 Existenz, EC-3 Kalender, stale_after-WARN-Kanal,
|
||||
EC-11 non-md) und Validator-Zertifizierung in wiki/log.md gegen erweiterte Fixtures
|
||||
neu ausfuehren"
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "Neue Fixture-Tabelle schema/validator.md §7.3 (EC-1, EC-3, WARN,
|
||||
EC-11); Validator auf Revision 4; Zertifizierung in wiki/log.md nachgefuehrt."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-02"
|
||||
- id: "epic-1-retro-item-3-3-2-voraussetzungspruefungen-als-fachlic"
|
||||
epic: 1
|
||||
action: "§3.2-Voraussetzungspruefungen als Fachliche Pruefung V-1/V-2 labeln oder
|
||||
Vertrag §7 um Fall fehlende Bundleroot erweitern (mit Autorisierung)"
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "Label-Ansatz gewaehlt: §3.2 als V-1/V-2 fachliche voraussetzungspruefung;
|
||||
FAIL (Voraussetzung) ... (V-1|V-2); Fixtures in §7.1/§7.3; Vertrag unveraendert."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-03"
|
||||
- id: "epic-1-retro-item-4-source-md-provenienz-korrigieren-_bmad-o"
|
||||
epic: 1
|
||||
action: "source.md-Provenienz korrigieren: _bmad-output/ ist versioniert; Herkunft
|
||||
auf Commit-Hash stuetzen und Deferred-Work-Checksumme (SHA-256) voranbringen"
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "raw/*/source.md korrigiert; Herkunft auf Commit 6cc667d + SHA-256
|
||||
gestuetzt (byte-identisch zur Evidenz); Deferred-Work-Checksumme damit vorangebracht/umgesetzt."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-09"
|
||||
- id: "epic-1-retro-item-5-bom-leerzeilen-stripping-von-punkt-10-au"
|
||||
epic: 1
|
||||
action: "BOM-/Leerzeilen-Stripping von Punkt 10 auf Punkte 2/8 der Validator-Instruktion
|
||||
erweitern (einheitliche Frontmatter-Erkennung)"
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "Gemeinsame gestrippte Frontmatter-Erkennung in §3-Praaembel; Punkte
|
||||
2/8/10 nutzen sie; Positiv-Fixtures 2a/8b ergaenzt; Revision 6; Vertrag unveraendert."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-05"
|
||||
- id: "epic-1-retro-item-6-ausfuehrbare-mechanische-verifikation-de"
|
||||
epic: 1
|
||||
action: "Ausfuehrbare/mechanische Verifikation des Validators einfuehren (Fixture-Orakel
|
||||
oder Vertrag↔Validator-Abgleich je Autorisation)"
|
||||
owner: "process"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "Konsistenz-Abgleich (Nutzer): strenger Vertrag↔Validator↔Fixtures-Abgleich
|
||||
(14 Punkte/keine Punkt 15) als Pflicht-Re-Check in spec-1-4-Verification; bleibt
|
||||
in D-3 (kein Standalone). Verifikations-Beleg-Tabelle ergaenzt."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-10"
|
||||
- id: "epic-1-retro-item-7-folge-aufgaben-fuer-epic-2-3-sichern-ver"
|
||||
epic: 1
|
||||
action: "Folge-Aufgaben fuer Epic-2/3 sichern: verschachtelte Duplikat-Keys, today-Zeitzone,
|
||||
Index-Regel bei verschachtelten Areas, .MD-Grossschreibung, OKF-Referenz-URL,
|
||||
raw/-extern-Fixture"
|
||||
owner: "epic-2/3-planung"
|
||||
status: done
|
||||
closed: "2026-08-16"
|
||||
resolution: "F-04/F-06/F-07/F-08/F-11/F-14 als Defer-Kontexte in deferred-work.md
|
||||
(append-only) mit Epic-/Validator-Zuordnung notiert; F-06/F-08 zusaetzlich im
|
||||
Validator Rev. 6 als 'Offene Punkte' verankert."
|
||||
ref: "_bmad-output/implementation-artifacts/epic-1-retro-2026-08-15.md#F-04"
|
||||
- id: "code-review-2-1-item-1-autorisierte-validator-revision-option"
|
||||
epic: 2
|
||||
action: "Autorisierte Validator-Revision starten (Option-A-Heilung fuer Story
|
||||
2.1): 1) F-14-Negativ-Fixture (resource ausserhalb raw/, existiert) ergaenzen;
|
||||
2) Innen-Ebenen-Key-Subset-Klarstellung (Punkt 6 in sources/generated/verified)
|
||||
formal tragen (bisher unautorisierte Rev-7-Notiz); 3) Validator-Header-Revisionszahl
|
||||
anheben (Header 'Revision 6' vs. Revisionslog 'Revision 7', OBS-1). Danach Story
|
||||
2.1 zur Review-Freigabe wiedervorlegen."
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-17"
|
||||
resolution: "schema/validator.md auf Revision 8: F-14-Fix-Fixture 4a (§7.1, Punkt
|
||||
4), Innen-Ebenen-Key-Subset formalisiert (Punkt-6-Zelle verweist auf §7.3, autorisiert),
|
||||
Header-Revisionszahl auf 8 angehoben (OBS-1 behoben). Zertifizierung PASS (Fixture
|
||||
4a FAIL Punkt 4; Innen-Ebenen FAIL Punkt 6; reales Bundle SUCCESS). Story 2.1
|
||||
zur Review-Freigabe wiedervorgelegt (status: review)."
|
||||
ref: "_bmad-output/implementation-artifacts/validator-revision-8-autorisationsrunde-f14-innen-ebenen.md"
|
||||
- id: "code-review-2-1-item-2-validator-rev9-punkt4-grammar-innen-ebenen-fixture"
|
||||
epic: 2
|
||||
action: "Autorisierte Validator-Revision 9 vorbereiten (bmad-code-review Re-Run
|
||||
2026-08-17, geholderte Patches 16/17): 1) Punkt-4-Fehlerursachen-Grammatik um
|
||||
`resolved=`-Token erweitern (Fixture 4a ableitbar machen); 2) Innen-Ebenen-Punkt-6-Fixture-Zeile
|
||||
in §7.1/§7.3 ergänzen (Rev-8-Formalisierung re-runbar belegen). Danach Zertifizierung
|
||||
(isolierte Fixtures + reales Bundle) und `wiki/log.md`-Nachweis."
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-18"
|
||||
resolution: "Ausgefuehrt als Teil der autorisierten Validator-Rev-9: die zwei gehaltenen
|
||||
Patches 16/17 umgesetzt — §3-Punkt-4-Vorlage um resolved=<pfad>-Token ergaenzt
|
||||
(inkl. §6.2-Semantik: nur bei Ablehnung durch aufgeloeste Lage ausserhalb raw/,
|
||||
Wert = aufgeloester workspace-relativer Pfad; Fixture 4a -> FAIL Punkt 4 (resolved=README.md),
|
||||
ableitbar), Innen-Ebenen-Punkt-6-Negativ- UND Positiv-Fixture-Zeilen in §7.3
|
||||
ergaenzt (role: x -> FAIL Punkt 6, Isolations-Prinzip). Scope: zusaetzlich die
|
||||
de-duplizierte Punkt-11-Area-Lesart aus AI-2-R-5 (eingefrorener Intent, epic-2-retro-item-14
|
||||
= eigener action_item done-Eintrag mit eigener resolution + ref auf die Rev-9-Runde);
|
||||
dieses Item deckt die zwei gehaltenen Patches, item-14 die Punkt-11-Area-Lesart.
|
||||
Zertifizierung (isolierte Fixtures + reales Bundle 7/7 SUCCESS) und wiki/log.md-Nachweis
|
||||
erfolgt (inkl. Freeze-Command + Live-Invariant)."
|
||||
ref: "_bmad-output/implementation-artifacts/deferred-work.md"
|
||||
- id: "epic-2-retro-item-10-schema-compiler-md-5-5-selbsttest-formel"
|
||||
epic: 2
|
||||
action: "schema/compiler.md §5.5-Selbsttest-Formel rekursiv machen (grep -rnE
|
||||
(raw/ über wiki/ inkl. Area-Concepts); F-01/AI-2-R-1"
|
||||
owner: "dev"
|
||||
status: open
|
||||
ref: "_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md"
|
||||
- id: "epic-2-retro-item-11-schema-compiler-md-5-8-lauf-a-um-area-co"
|
||||
epic: 2
|
||||
action: "schema/compiler.md §5.8-Lauf A um Area-Concept-ohne-index.md erweitern
|
||||
(Tiefe-2, wiki/<a>/concept.md ohne wiki/a/index.md); F-03/AI-2-R-2"
|
||||
owner: "dev"
|
||||
status: open
|
||||
ref: "_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md"
|
||||
- id: "epic-2-retro-item-12-schema-compiler-md-5-6-formel-4-filter-a"
|
||||
epic: 2
|
||||
action: "schema/compiler.md §5.6-Formel-4 Filter-Asymmetrie heilen (--exclude=log.md
|
||||
vs grep -v log.md$ auf eine Semantik); F-04/AI-2-R-3"
|
||||
owner: "dev"
|
||||
status: open
|
||||
ref: "_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md"
|
||||
- id: "epic-2-retro-item-13-schema-compiler-md-5-8-reachability-als"
|
||||
epic: 2
|
||||
action: "schema/compiler.md §5.8-Reachability als echte Markdown-Links prüfen
|
||||
+ ./-Variante mit §5.6-Pin vereinheitlichen; F-05/AI-2-R-4"
|
||||
owner: "dev"
|
||||
status: open
|
||||
ref: "_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md"
|
||||
- id: "epic-2-retro-item-14-autorisierte-validator-rev-9-für-punkt-1"
|
||||
epic: 2
|
||||
action: "Autorisierte Validator-Rev-9 für Punkt-11-Area-Lesart (relative OKF-Pfad-Identität,
|
||||
file-relativ in Area-Index); de-dupliziert mit code-review-2-1-item-2; F-02/AI-2-R-5"
|
||||
owner: "dev"
|
||||
status: done
|
||||
closed: "2026-08-18"
|
||||
resolution: "Autorisierte Validator-Rev-9 ausgefuehrt und zertifiziert: Punkt-11-Area-Lesart
|
||||
formalisiert (file-relative Referenz in Area-index.md genuegt, Paerchen Area-Praefix
|
||||
+ Link-Ziel identitaetsstiftend; Live: wissensarchitektur/source-material ueber
|
||||
](source-material.md)); Bereichs-Index wahren die Bundle-Identitaet ohne textuelle
|
||||
Nennung. §7-Fixtures 11a (Negativ/Positiv), Revisionslog 9, Header 9, wiki/log.md-Nachweis
|
||||
(7/7 SUCCESS) erbracht. Quelle: spec-autorisierte-validator-revision-9-punkt-11-area-lesart.md"
|
||||
ref: "_bmad-output/implementation-artifacts/epic-2-retro-2026-08-18.md"
|
||||
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: 'Autorisierte Validator-Revision 8 — F-14-Fixture + Innen-Ebenen-Key-Subset formalisieren (Option-A-Heilung Story 2.1)'
|
||||
type: 'authorization-round'
|
||||
created: '2026-08-16'
|
||||
status: 'done'
|
||||
based_on_commit: f91ef89078ee8e4c8a979cfb70f20ead1ffe854b
|
||||
related:
|
||||
- _bmad-output/implementation-artifacts/spec-2-1-concepts-aus-source-material-erzeugen-okf-konform.md
|
||||
- _bmad-output/implementation-artifacts/deferred-work.md
|
||||
---
|
||||
|
||||
# Autorisierte Validator-Revision 8 — F-14-Fixture + Innen-Ebenen-Key-Subset formalisieren
|
||||
|
||||
> **Zweck:** Heilt die offene Option-A-Voraussetzung von Story 2.1 (Review vom 2026-08-16) über den **autorisierungsfähigen** Kanal (Frieren-Prinzip wahren). `schema/validator.md` wird erst **in dieser Revision** verändert — die heute im Revisionslog als unautorisierte Notiz geführte Rev-7-Klarstellung wird damit formal getragen, die Revisionszahl im Header angehoben und die von Retrospective F-14 geforderte Negativ-Fixture ergänzt.
|
||||
|
||||
## Warum Revision 8 (nicht 7)?
|
||||
|
||||
Der Revisionslog (§8) führt bereits einen Eintrag „Revision 7" (2026-08-16, Step-04-Review Story 2.1) — er ist inhaltlich korrekt, aber als **unautorisierte Mutation** in den Commit gelangt. Der Revisionslog ist append-only; die Rev-7-Notiz bleibt als Historie erhalten. Die **nächste autorisierte Revision** wird daher **Revision 8**: Ihr Logeintrag formalisiert die Rev-7-Klarstellung und die F-14-Fixture, der Header wird auf **8** angehoben (behebt damit zugleich OBS-1: Header „Revision 6" vs. Revisionslog „Revision 7").
|
||||
|
||||
## Geltungsbereich
|
||||
|
||||
**Genau eine Datei wird geändert:** `schema/validator.md`.
|
||||
**Unverändert (nicht anfassen):** `schema/wiki-compiler.md` (autorisiert, Story 1.3), `schema/compiler.md` (Rev 1.3, bereits committet), `raw/` (immutable, AD-3), `adapters/`, alle `wiki/`-Dateien.
|
||||
|
||||
## 1. F-14-Negativ-Fixture ergänzen (§7.1, Punkt 4)
|
||||
|
||||
Retrospective F-14: Ein `resource`-Pfad, der **außerhalb `raw/` landet, aber existiert** (z. B. `README.md` an der Workspace-Root), hat kein Negativ-Fixture; §6.2 Schritt 5 deckt den Fall, §7.1-Fixtures belegen ihn nicht.
|
||||
|
||||
**Patch:** In der §7.1-Fixture-Tabelle (nach Zeile Punkt 4, als `4a`) ergänzen:
|
||||
|
||||
```text
|
||||
| 4a | `sources: [{resource: README.md}]` (Datei `README.md` existiert an der Workspace-Root, ausserhalb `raw/`) | `FAIL wiki/x.md Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (resolved=README.md)` |
|
||||
```
|
||||
|
||||
**Isolations-Prinzip:** Sample ist sonst-valide (Punkt 3 passiert, da nicht `wiki/`; alle übrigen Punkte ok) → genau Punkt 4 löst aus.
|
||||
|
||||
## 2. Innen-Ebenen-Key-Subset formal tragen (§7.3 / Punkt 6)
|
||||
|
||||
Die Rev-7-Notiz wird von „dokumentarische Klarstellung (keine Autorisierung nötig)" zur **formal getragenen Regel** dieser Revision aufgewertet:
|
||||
|
||||
**Patch (redaktionell, §7.3-Einleitung als Teil der Revision):** Der bestehende Isolations-Hinweis zur Innen-Ebenen-Punkt-6-Abdeckung (bereits im Text vorhanden, unter der filigranen Notiz von Rev 7) wird als **ordentlicher, autorisierter Inhalt** der Revision 8 geführt — inhaltlich identisch, lediglich als legitimierter Bestandteil (nicht mehr „nur dokumentarisch"). Zusätzlich wird die Punkt-6-Prüfschritt-Zelle (§3-Tabelle, Zeile 6) um den expliziten Verweis „Innen-Ebenen: §7.3-Isolations-Notiz (autorisiert, Revision 8)" ergänzt, damit die mechanische Prüfung unzweideutig auf die Innen-Ebenen-Fälle verweist.
|
||||
|
||||
## 3. Validator-Header anheben (OBS-1) + Revisionslog nachführen
|
||||
|
||||
**Patch §0-Header:**
|
||||
- `> **Validator-Revision:** 6` → `> **Validator-Revision:** 8`
|
||||
- `> **Letzte Re-Konsistenz:** 2026-08-16 (Revision 6 — …)` → `2026-08-16 (Revision 8 — F-14-Fixture + Innen-Ebenen-Key-Subset formalisiert; Option-A-Heilung Story 2.1)`
|
||||
|
||||
**Patch §8-Revisionslog (append-only, neuer Eintrag):**
|
||||
|
||||
```text
|
||||
- **Revision 8 (2026-08-16, Autorisations-Runde):** Option-A-Heilung Story 2.1 — drei Änderungen: (1) F-14-Negativ-Fixture 4a ergänzt (§7.1, Punkt 4: `resource` außerhalb `raw/`, aber existierend, z. B. `README.md`; Retrospective F-14); (2) Innen-Ebenen-Key-Subset-Klarstellung (Punkt 6 in `sources`/`generated`/`verified`-Einträgen, Vertrag §3.3–§3.5) als formal getragener Inhalt bestätigt — formalisiert die Rev-7-Notiz (die bislang als unautorisierte Mutation geführt war) und verankert den §7.3-Isolations-Hinweis als autorisierten Bestandteil; Punkt-6-Zelle um Innen-Ebenen-Verweis ergänzt; (3) Header-Revisionszahl von „Revision 6" auf „Revision 8" angehoben (behebt die pre-existing Header-Log-Diskrepanz, OBS-1). Vertrag `schema/wiki-compiler.md` unverändert (keine Vertrags-Autorisierung nötig — Punkt 6 deckt Innen-Ebenen bereits, §3.3–§3.5).
|
||||
```
|
||||
|
||||
## 4. Zertifizierung (Pflicht, wie bei Revisions 3–6)
|
||||
|
||||
Gemäß Validator-Zertifizierungs-Kultur (F-02, wiki/log.md) ist die Revision **mechanisch zu belegen**:
|
||||
|
||||
1. **F-14-Fixture 4a isoliert:** Sample `sources: [{resource: README.md}]` mit existierender `README.md` an der Workspace-Root gegen den revidierten Validator ausführen → erwartet `FAIL … Punkt 4: resource ausserhalb raw/ …`, **kein** Vorab-FAIL durch andere Punkte.
|
||||
2. **Punkt 6 Innen-Ebenen isoliert:** `sources:\n - resource: raw/prd/prd-wow20-2026-08-14.md\n role: x` gegen den revidierten Validator → erwartet `FAIL … Punkt 6: … unautorisierter Key in sources/generated/verified` (sonst-valides Sample).
|
||||
3. **Regression auf das reale Bundle:** Validator-Run gegen alle 5 `wiki/`-Dateien → weiterhin **SUCCESS für alle** (keine neu ausgelösten FAILs durch die Fixture-/Hinweis-Änderung; die Revision fügt keine neue §7-Invaliditätsklasse hinzu → Abschluss-Eigenschaft gewahrt).
|
||||
4. Ergebnis der Zertifizierung in `wiki/log.md` dokumentieren (datumsgruppiert, §5-Format).
|
||||
|
||||
## 5. Folge-Tracking nach Autorisierung
|
||||
|
||||
Nach erfolgreicher Ausführung + Zertifizierung:
|
||||
|
||||
1. `sprint-status.yaml` — Action-Item `code-review-2-1-item-1-autorisierte-validator-revision-option` → `status: done`, `closed: <datum>`, `resolution:` mit Rev-8-Nummer + `ref` auf diese Datei.
|
||||
2. **Story 2.1 freigeben** — in `spec-2-1-…okf-konform.md`: Re-Review-Verdikt-Absatz finalisieren („Option A erfüllt: next authorized revision = Rev 8, tragen F-14 + Innen-Ebenen + Header"), `status: in-progress → review` (Human-Review), danach `done`.
|
||||
3. `sprint-status.yaml` — Story 2.1 `2-1-concepts-…`: `in-progress → review → done` (je nach Ablauf); `epic-2` bleibt `in-progress`.
|
||||
4. `wiki/log.md` — Einträge für Validator-Rev-8-Zertifizierung und Story-2.1-Freigabe.
|
||||
5. `deferred-work.md` — Defer/Sektion „Arbeitsauftrag" bleibt als Historie; kein Rückbau.
|
||||
|
||||
## Erfolgskriterien (Definition of Done dieser Runde)
|
||||
|
||||
- [x] `schema/validator.md` trägt Revision 8: Header `8`, Revisionslog-Eintrag Rev 8, Fixture 4a, Innen-Ebenen-Verweis in Punkt-6-Zelle; §7-Katalog weiterhin abschließend (kein neuer Punkt 15).
|
||||
- [x] Zertifizierung 1–3 dokumentiert (Fixture 4a FAIL, Innen-Ebenen Punkt 6 FAIL, reales Bundle SUCCESS).
|
||||
- [x] `schema/wiki-compiler.md`, `schema/compiler.md`, `raw/`, `adapters/`, `wiki/`-Concepts unverändert (außer `wiki/log.md`-Einträge).
|
||||
- [x] Sprint-Tracking aktualisiert (Action-Item done, Story 2.1 `done` nach Human-Review).
|
||||
@@ -10,5 +10,6 @@ Materialisiert als Quelle unter `raw/` (Story 1.2, AD-12).
|
||||
## Provenienz-Hinweis
|
||||
|
||||
- Diese `source.md` ist ein Artefakt, **keine Evidenz** (vgl. `raw/README.md`).
|
||||
- Herkunftspfade unter `_bmad-output/` sind generierte Planungs-Artefakte und im Repo nicht versioniert — Reproduktionshinweis, keine feste Referenz.
|
||||
- Die Herkunftsquelle unter `_bmad-output/planning-artifacts/` ist **versioniert** (Git-Repo, `git ls-files` bestätigt die Datei) und damit als feste Referenz nachvollziehbar. Reproduzierbarer Stand: Commit `6cc667d` (`6cc667dd55aad54cb53b77e862732a66e1382000`).
|
||||
- **SHA-256 der Herkunftsdatei** (byte-identisch zur materialisierten Evidenz, geprüft 2026-08-16): `4f4625954e64a11bd158675ff23be5a2c33a8a4b4d981c4777ae1040752e3c4e`
|
||||
- Ändert sich die Herkunftsquelle, wird eine **neue, datierte Datei** angelegt (AD-3); diese Datei bleibt unverändert.
|
||||
|
||||
+2
-1
@@ -10,5 +10,6 @@ Materialisiert als Quelle unter `raw/` (Story 1.2, AD-12).
|
||||
## Provenienz-Hinweis
|
||||
|
||||
- Diese `source.md` ist ein Artefakt, **keine Evidenz** (vgl. `raw/README.md`).
|
||||
- Herkunftspfade unter `_bmad-output/` sind generierte Planungs-Artefakte und im Repo nicht versioniert — Reproduktionshinweis, keine feste Referenz.
|
||||
- Die Herkunftsquelle unter `_bmad-output/planning-artifacts/` ist **versioniert** (Git-Repo, `git ls-files` bestätigt die Datei) und damit als feste Referenz nachvollziehbar. Reproduzierbarer Stand: Commit `6cc667d` (`6cc667dd55aad54cb53b77e862732a66e1382000`).
|
||||
- **SHA-256 der Herkunftsdatei** (byte-identisch zur materialisierten Evidenz, geprüft 2026-08-16): `3b8e0da47a7db0d92e78972747b8efcb230400eb37cfd607554e7eaeb57d04fa`
|
||||
- Ändert sich die Herkunftsquelle, wird eine **neue, datierte Datei** angelegt (AD-3); diese Datei bleibt unverändert.
|
||||
|
||||
+2
-1
@@ -11,5 +11,6 @@ Materialisiert als Quelle unter `raw/` (Story 1.2, AD-12).
|
||||
## Provenienz-Hinweis
|
||||
|
||||
- Diese `source.md` ist ein Artefakt, **keine Evidenz** (vgl. `raw/README.md`).
|
||||
- Herkunftspfade unter `_bmad-output/` sind generierte Planungs-Artefakte und im Repo nicht versioniert — Reproduktionshinweis, keine feste Referenz.
|
||||
- Die Herkunftsquelle unter `_bmad-output/planning-artifacts/` ist **versioniert** (Git-Repo, `git ls-files` bestätigt die Datei) und damit als feste Referenz nachvollziehbar. Reproduzierbarer Stand: Commit `6cc667d` (`6cc667dd55aad54cb53b77e862732a66e1382000`).
|
||||
- **SHA-256 der Herkunftsdatei** (byte-identisch zur materialisierten Evidenz, geprüft 2026-08-16): `68e711759e405d3274b77b829db69cc432fd078652a6042e0fcd1889cab0897d`
|
||||
- Ändert sich die Herkunftsquelle, wird eine **neue, datierte Datei** angelegt (AD-3); diese Datei bleibt unverändert.
|
||||
|
||||
@@ -0,0 +1,317 @@
|
||||
# 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 8) — 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):**
|
||||
|
||||
```text
|
||||
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 (was der Compiler konsumiert)
|
||||
|
||||
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/`, die als evidierenfähige Source verarbeitet wird, 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. (Dokumentarische Konvention der Source-Bereitstellung nach `raw/README.md` — eine nicht-mechanische Ausnahme zur Evidenz-Erwartung; zu verarbeitende Evidenz kann auch andere Formate als `.md` tragen, z. B. PDF.)
|
||||
|
||||
## 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") und **setzt mit den übrigen erkannten Wissenseinheiten fort**; die gehaltene Einheit erzeugt keine Datei, keinen Index-Link und keinen `log.md`-Eintrag. Mindestens eine erfolgreich erzeugte und mindestens eine gehaltene Einheit → der Run ist **teilweise erfolgreich**: die erzeugten Concepts werden normal validiert und veröffentlicht, die gehaltenen Einheiten werden textuell als solche benannt (NFR-4).
|
||||
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/`. Der Ziel-Pfad ergibt sich aus der **deterministischen Bereichszuordnung** (§5.7): (a) verweist bereits ein bestehender `index.md`-Link auf das erkannte Thema, wird das Concept in dessen Bereich angelegt (`wiki/<area>/<concept-kebab-case>.md`); (b) sonst Default Root-Ebene (`wiki/<concept-kebab-case>.md`). Nie Embedding/Vector (AD-7c, A0-10, AD-13). Die „Area-Zuordnung ist Story 2.4"-Backlog-Klausel ist mit §5.7 aufgelöst.
|
||||
- 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 großen Quell-Exzerpte enthalten (FR-2). Claim-granulare Inline-Provenienz (AD-4a) folgt §5.5 — für neu erzeugte Concepts unmittelbar bei der Erzeugung, für bestehende Bodies per Nachrüstung (Story 2.2).
|
||||
3. **Index-Regel (Punkt 11/§6):** Nach Anlage MUSS das neue Concept in der `index.md` **seines Bereichs** verlinkt werden — für Root-Concepts in der Bundleroot `wiki/index.md`, für Area-Concepts in der jeweiligen Area-`index.md` (`wiki/<area>/index.md`, §5.7) — seine Identität (relativer OKF-Pfad ohne `.md`) als relativer Bundle-Pfad referenziert; die genau-eine-Form-Festlegung ist in **§5.6** gepinnt (file-relativ, mit `.md`-Endung; §5.7 Pkt. 4). 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). Bei Validierungs-FAIL wird der Teilzustand **explizit zurückgerollt**: neue Concept-Datei(en) gelöscht, zugehörige Index-Verlinkung(en) aus `wiki/index.md` entfernt, `log.md`-Eintrag(e) wieder entfernt — das Bundle nimmt seinen Zustand vor dem Run wieder ein (keine partielle Mutation bleibt liegen).
|
||||
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).
|
||||
|
||||
## 5.5 Claim-granulare Provenienz (Story 2.2)
|
||||
|
||||
Provenienz ist **claim-granular** (AD-4a, A0-3): Nicht nur das Concept als Ganzes trägt `sources`, sondern **jede belegte Aussage** im Body trägt einen Inline-`raw/`-Verweis. Kontext-/Synthese-Umformulierungen — Aussagen, die nicht direkt auf `raw/`-Evidenz rückführbar sind, sondern aus Concept-Kontext, direkt aus einer rohen Quelle (ohne Zwischen-Concept) oder aus Synthese mehrerer Quellen stammen — tragen einen expliziten **Kontext-Marker**. Diese Sektion ist eine Body-Text-Konvention; sie fügt **kein neues Frontmatter-Feld über das §3.3-Subset hinaus** hinzu — das Hinzufügen bzw. Erweitern von `sources`-Einträgen (`resource`/`id`) **IST Teil der Konvention** (Relokation/Zielwechsel, Pkt. 1b) und kollidiert nicht mit dieser Selbstbegrenzung (AD-4a; der Vertrag §3 legt das Feldsubset abschließend fest). Sie gilt für **Neu-Erzeugung und Nachrüstung bestehender Concept-Bodies gleichermaßen**. `wiki-compiler.md` und `validator.md` bleiben unverändert (AD-3); diese Sektion ist der einzige Instruktions-Ort der Provenienz-Konvention (D-3, Story 2.2).
|
||||
|
||||
1. **Inline-`raw/`-Verweis je belegter Aussage:** Eine Aussage ist „belegt", wenn sie sich fachlich auf eine konkrete Evidenzstelle in `raw/` zurückführen lässt. Sie trägt dann unmittelbar am Ende der Aussage (bzw. am Ende des zugehörigen Absatzes/Listenelements) einen Inline-Verweis in der verbindlichen Default-Form:
|
||||
|
||||
`(raw/<datei.md>#<stellen-kennung>)`
|
||||
|
||||
Daneben ist die **Komma-Form** als zulässige zweite Form festgelegt:
|
||||
|
||||
`(raw/<datei.md>, <stellen-kennung>)`
|
||||
|
||||
- Die Komma-Form wird verwendet, wenn die Stellen-Kennung im Rohdokument **als Sektionstitel/Nummer ohne Bezeichner-`id`** vorliegt (z. B. `§ 1 Vision`, `§ 4.5 FR-16`, `§ 0 Document Purpose`) — ein `#`-Fragment wäre hier ein künstlicher Anker. Für Bezeichner-`id`s (`FR-*`, `A0-*`, `AD-*`) bleibt die `#`-Form die Default-Form. Die Form-Frage „`(<pfad>)` ggü. `[<text>](<pfad>)`" ist mit **§5.6** geschlossen: Concept-Links (Concept-Bodies + `wiki/index.md`) stehen in der gepinnten Form; `raw/`-Provenienz-Verweise dieser Sektion **bleiben** in der Plain-/Komma-Form (andere Schicht — vom Pin ausgenommen, §5.6 Pkt. 2), sofern der volle `raw/`-Pfad am Verweis erkennbar ist und der Grep die Form erfasst (analog: beide Fragment-Formen `#`/Komma sind zulässig, sofern die Stellen-Kennung im Rohdokument existiert).
|
||||
- Die **Stellen-Kennung** (hinter `#` bzw. nach dem Komma) ist eine **KENNUNG, die im referenzierten Rohdokument tatsächlich existiert** — z. B. ein Bezeichner-`id` der rohen Datei (wie `FR-12`, `A0-6`, `AD-5` in `raw/epics/…` bzw. `raw/architecture-spine/…`) oder der exakte Sektionstitel des Rohdokuments (z. B. `§ 1 Vision`). Die **Concept-eigene `sources`-Feld-`id` (`s1`, `s2`, …) ist NICHT als Fragment zu verwenden**, weil sie im Rohdokument nicht existiert — der Verweis würde im Rohdokument nicht auflösen (keine Falsch-Attribution). Die `sources`-`id` dient ausschließlich der vertragsgemäßen internen Zitat-Attribution (Vertrag §3.3), nicht als Inline-Fragment.
|
||||
- **Multi-Beleg-Serialisierung:** Mehrere Belege desselben Rohdokuments innerhalb eines Inline-Verweises werden semikolon-getrennt mit vollem Pfad je Beleg aufgelistet: `(raw/epics/epics-2026-08-14.md#FR-12; raw/epics/epics-2026-08-14.md#A0-6)`. Innerhalb eines Belegs dürfen mehrere `#`-Kennungen unter demselben Pfad komma-gruppiert werden, wenn sie dieselbe Stellen-Kennung-Form tragen: `(raw/architecture-spine/architecture-spine-2026-08-14.md#AD-2, #AD-3, #AD-1)`; bei **gemischten Formen** (`#`-Kennung + Sektionstitel) bleibt der Pfad je Beleg vollständig: `(raw/architecture-spine/…md#AD-3; raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns)`. **Keine Pfad-Elision** über Beleg-Grenzen hinweg (also niemals allein `#A0-6` ohne vorangestellten Pfad als eigenständiger Beleg).
|
||||
- **Deterministische Selbsttest-Formel:** Die Verweise sind per `grep -nE '\(raw/'` auffindbar (das Teilmuster `(raw/` trifft beide Plain-Formen `(raw/…)` und die Markdown-Linkform `[<text>](raw/…)`). Die Formel ist als `sh -c "grep -nE '\(raw/' wiki/*.md"` re-executierbar und liefert deterministische Ausgabe (AD-17h).
|
||||
|
||||
- **1a. Pfad-Form:** ausschließlich `/`-getrennte relative Workspace-Pfade **innerhalb `raw/`** — nie `wiki/` (AD-4b), kein `..`, kein führendes `/`, kein Backslash, keine URL-Form (spiegelbildlich zu §4.2 und Vertrag §3.3). Um zusätzliche Validierungsoberfläche ohne importierte Struktur zu vermeiden, verweist der Inline-Beleg üblicherweise auf dasselbe `raw/`-Ziel, das auch im `sources`-Frontmatter des Concepts deklariert ist — die EC-1-Existenzprüfung (§6.5-Kriterium 3 / Validator §6.1) bleibt damit unverändert anwendbar.
|
||||
- **1b. Relokation/Zielwechsel:** Zeigt eine Aussage auf einen anderen `raw/`-Pfad als die `sources`-Deklaration des Concepts (z. B. das ASCII-Diagramm aus `raw/architecture-spine/…` in einem Concept mit `sources: raw/epics/…`), so ist **zusätzlich ein passender `sources`-Eintrag** im Frontmatter zu ergänzen, dessen `resource` auf jenen Pfad zeigt (EC-1-Existenz, Punkt 3/4). Das Diagramm-Quell ist damit sowohl body- als auch frontmatter-seitig deklariert (Story-2.1-Instanz: ASCII-Diagramm in `knowledge-kompilation-inkrementell.md`).
|
||||
|
||||
2. **Kontext-Marker je Übernahme (AD-4a/A0-3):** Eine **Übernahme** ist eine Kontext-/Synthese-Umformulierung: Formulierung, die aus Concept-Kontext, direkt aus einer rohen Quelle oder aus der Synthese mehrerer Quellen stammt und nicht eigenständig gegen `raw/` belegt ist. Es gibt **drei Marker-Muster** (zwei Grundmuster + Forward-Referenz-Variante) — alle MÜSSEN den exakten Token „nicht eigenständig belegt" enthalten (deterministischer Selbsttest, mindestens eine Form pro Übernahme):
|
||||
|
||||
- **Übernahme über ein Zwischen-Concept** (Ursprungs-Concept existiert): minimal nach Vertrag §3.3/A0-3-Wortlaut
|
||||
|
||||
> übernommen aus `<Concept-Pfad>` auf Basis von `<source>`, nicht eigenständig belegt
|
||||
|
||||
Dabei ist `<Concept-Pfad>` der relative OKF-Pfad des Ursprungs-Concepts ohne `.md` (AD-7a), `<source>` der zugrunde liegende `raw/`-Pfad. **Kein Selbstreferenz-Muster:** Ein Concept, das sich selbst als Ursprung nennt, ist Falsch-Attribution und verboten — gibt es kein Zwischen-Concept, ist Muster (2) zu verwenden.
|
||||
- **Direktübernahme aus `raw/` ohne Zwischen-Concept** (z. B. ein Diagramm direkt aus einer rohen Datei):
|
||||
|
||||
> übernommen aus `<source>` (rohe Quelle), nicht eigenständig belegt
|
||||
|
||||
Dabei ist `<source>` der zugrunde liegende `raw/`-Pfad.
|
||||
|
||||
Die Marker stehen direkt bei der übernommenen Aussage (Absatz-/Listen-Ebene), damit die Zuordnung claim-granular bleibt. **Epic-3/4-Fähigkeiten**, die im Körper eines Concepts nur als Forward-Referenz erscheinen (noch nicht erzeugt/validiert), tragen die **Forward-Referenz-Variante** des Markers (drittes Muster) ebenfalls mit dem exakten Token — nicht eigenständig belegt, als Forward-Referenz übernommen (die „auf Basis von"-Angabe wird hier nur gesetzt, wenn nicht bereits aus der Kontext-/Konzeptzeile ersichtlich): „… als Forward-Referenz übernommen, nicht eigenständig belegt (raw/epics/epics-2026-08-14.md, Story 3.1: Inkrementellen Datenfluss implementieren)".
|
||||
|
||||
3. **Eindeutiges `id`-Scoping (Vertrag §3.3):** `id`-Werte in `sources`-Einträgen sind **je Concept eindeutig** (innerhalb eines Concepts darf kein `id` doppelt vorkommen). Über Concepts hinweg ist `id` nicht global eindeutig — der Adressraum ist der Concept-Pfad + `id` (AD-7a). Bei der Nachrüstung bestehender Concepts ohne `id` können `id`s deterministisch vergeben werden (`s1`, `s2`, … in Dokumentreihenfolge).
|
||||
|
||||
4. **Selbsttest-Kriterien (AD-17h, Story-2.2-Projektion):** Vor Abschluss eines Runs prüft der Producer:
|
||||
- **Belegte Aussage → Inline-`raw/`-Verweis:** Jede Aussage, die fachlich eine Evidenzstelle referenziert, trägt einen solchen Verweis mit vollem `raw/`-Pfad je Beleg (per `grep -nE '\(raw/'` auffindbar — erfasst auch die Markdown-Linkform).
|
||||
- **Übernahme → Kontext-Marker:** Jede Kontext-/Synthese-Umformulierung, jede Direktübernahme aus `raw/` und jede Epic-3/4-Forward-Referenz trägt eines der drei Marker-Muster aus Pkt. 2 — alle enthalten den exakten Token „nicht eigenständig belegt".
|
||||
- **Kein unautorisierter Key:** Das Nachrüsten verändert ausschließlich den Body und die zulässigen §3.3-`sources`-Felder (`resource`, `id`, `title`, `author`, `usage_count`, `last_modified`); keine zusätzlichen Frontmatter-Felder, keine §7-Klasse (Punkt 6).
|
||||
- Wenn eine Aussage weder belegt noch als Übernahme markiert werden kann, wird sie **als Übernahme mit Marker geführt** — niemals erfunden belegt (UNBELEGTE_AUSSAGE: textuell sichtbar, Run bricht nicht ab).
|
||||
|
||||
5. **Worked Example (grammatisch verbindlich, BH-13):** Die folgende kanonische Form macht den §5.5-Standard eindeutig ablesbar. Eine **belegte Aussage** mit Inline-Verweis (voller Pfad, Fragment = im Rohdokument existierende Stellen-Kennung):
|
||||
|
||||
> Alle erzeugten Concepts sind OKF-0.2-konform (raw/epics/epics-2026-08-14.md#FR-9).
|
||||
|
||||
Dasselbe als **Komma-Form** (Stellen-Kennung = Sektionstitel ohne Bezeichner-`id` im Rohdokument):
|
||||
|
||||
> Das zentrale Produktversprechen lautet: Knowledge should compound (raw/prd/prd-wow20-2026-08-14.md, § 1 Vision).
|
||||
|
||||
Eine **Übernahme mit Kontext-Marker** — Direktübernahme eines Diagramms aus einer rohen Quelle (kein Zwischen-Concept, kein Selbstverweis):
|
||||
|
||||
> Das Datenfluss-Diagramm (Interpret → Reconcile → Synthesize → Update) stammt direkt aus der rohen Quelle raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5 — übernommen aus raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5 (rohe Quelle), nicht eigenständig belegt.
|
||||
|
||||
Die **Diagramm-Quell-Deklaration** erfolgt zugleich frontmatter-seitig: gehört das Diagramm nicht zur `sources`-Deklaration des Concepts, wird ein zusätzlicher `sources`-Eintrag ergänzt (Pkt. 1b — Relokation/Zielwechsel, EC-1-Existenz bleibt erfüllt).
|
||||
|
||||
## 5.6 Concept-Links (Story 2.3)
|
||||
|
||||
Beziehungen zwischen Concepts werden mit normalen Markdown-Links ausgedrückt — **genau eine erlaubte Form** (FR-10, AD-8, AD-7b, A0-9). Der Pin verhindert, dass zwei Producer aus demselben Baum unterschiedliche IDs berechnen (AD-7b). Die Link-Schicht ist die Navigations-/Beziehungsschicht, **nicht** die Provenienz (AD-8): ein Body-Link ändert keine Aussagen, kein `sources` und kein Frontmatter.
|
||||
|
||||
1. **Pin (genau eine Form):** Ein Concept-Link — im Concept-Body wie in `wiki/index.md` und Area-`index.md` — steht in der Form:
|
||||
|
||||
`"[<text>](<file-relativer Pfad mit .md-Endung>)"`
|
||||
|
||||
Ziel ist die Concept-OKF-Identität (relativer OKF-Pfad, AD-7a) + die `.md`-Endung (AD-7b, A0-9). Das Auflösungsmodell ist **file-relativ** zur `.md`-Datei (§5.7 Pkt. 4): Bei Root-Dateien sind file-relativ und bundle-relativ identisch (die bestehenden Concept-Links in `wiki/index.md` stehen bereits in dieser Form — Null-Migration, byte-identisch); in Areas bezeichnen `../` die Aufwärts-Ziele innerhalb `wiki/` (z. B. `[LLM-Wiki-Prinzip](../llm-wiki-prinzip.md)` aus `wiki/<area>/<concept>.md`). Rationale: Ziele sind explizite Dateien — auch mit Areas eindeutig (Story 2.4); Standard-Markdown-Tools lösen den Link **ohne Konventionswissen** dateirelativ auf (FR-10, AD-8) — eine Form, beide Ebenen (Root + Area) (AD-7b).
|
||||
2. **Geltungsbereich & Ausnahmen:** Der Pin gilt für Concept-Links in Concept-Bodies, in `wiki/index.md` und in Area-`index.md`. Explizit ausgenommen (andere Schicht bzw. außerhalb des Pins): `raw/`-Provenienz-Verweise in der Plain-/Komma-Form aus §5.5, `../schema/`-Links (außerhalb des Bundles — andere Schicht), `http`-Links (externe Referenzen) und **Gleichseit-Anker** mit `#`-Beginn — der Form-Check und der Dangling-Check in Pkt. 3 exkludieren sie. **Die `../`-Exklusion ist Story 2.4 aufgelöst:** `../`-Ziele sind seit der deterministischen Bereichszuordnung (§5.7) **in-Bundle-Aufwärts-Pfade** — sie werden validiert (Formel 2/3, Pkt. 3) und müssen nach `..`-Auflösung unter `wiki/` bleiben; `../schema/…` bleibt als andere Schicht exkludiert (Abgrenzung über das Zielverzeichnis unter `wiki/`, nicht über das bloße `../`-Präfix). Die Formeln in Pkt. 3 scannen den kompletten `wiki/`-Baum **mit Ausnahme von `log.md`** (Dokumentation, keine Link-/Provenienz-Schicht — sie zitiert die Formel-Texte selbst und würde die Zählungen verunreinigen); ein `](`-Link in `log.md` ist damit weder Pin-Objekt noch Formel-Trigger.
|
||||
3. **Selbsttest-Formeln (re-executierbar, AD-17h):** Vor Abschluss eines Runs, der Links anlegt oder verändert, prüft der Producer die folgenden vier Formeln ab der Workspace-Root (rekursiv — künftige Area-Concepts unter `wiki/<area>/` werden erfasst, Story 2.4/2.5):
|
||||
|
||||
Alle Formeln exkludieren `log.md` (Scan-Scope, Pkt. 2) und erfassen leere Ziele `]()` (`[^)]*` statt `[^)]+`).
|
||||
|
||||
**(1) Bestands-Check** (Link-Überblick — alle `](`-Links unter `wiki/`):
|
||||
|
||||
```sh
|
||||
sh -c "grep -roE ']\([^)]*\)' --include='*.md' --exclude=log.md wiki/"
|
||||
```
|
||||
|
||||
**(2) Form-Check** (erwartet Ausgabe `0`, Exit `0` — jeder interne Link in der gepinnten Form; jede Formverletzung (fehlende `.md`-Endung, Mischform, leeres Ziel) erhöht den Zähler um 1; `|| true` bindet den Exit-Code — grep `-c` liefert Exit `1` bei Ausgabe `0`, der gewünschten SUCCESS-Konfiguration):
|
||||
|
||||
```sh
|
||||
sh -c "grep -rohE ']\([^)]*\)' --include='*.md' --exclude=log.md wiki/ | sed -E 's/^\]\(//; s/\)$//' | sort -u | grep -vE '^(raw/|\.\./|#)' | grep -vE '^\.' | grep -vE ':' | grep -cvE '^[^#]+\.md$' || true"
|
||||
```
|
||||
|
||||
Exkludiert: `raw/`-Provenienz (§5.5, andere Schicht), `../schema/`, `./`-Präfix-Ziele (`^\.` — nicht root-relativ/keine Bundle-Pfad-Form), externe Ziele (alle enthalten `:` — `http://`, `https://`, `mailto:`, protocol-less Hostnamen; interne OKF-Ziele sind Kebab-Case und enthalten nie `:`), Gleichseit-Anker `(#…)`. Cross-Page-Anker `file.md#sec` werden weiterhin gezählt (normative Frage, s. `deferred-work.md`). **Story-2.4-`../`-Schärfung:** `../`-Ziele werden weiterhin von der Exklusions-Stufe `grep -vE '^(raw/|\.\./|#)'` aus der Form-Zählung genommen — denn in-Bundle-Aufwärts-Ziele (`../<ziel>.md`, Auflösung bleibt unter `wiki/`, §5.7 Pkt. 4) sind formkonform; die **Containment-Prüfung** (Ziel-Auflösung muss unter `wiki/` bleiben, sonst `DANGLING`) ist Aufgabe des Dangling-Checks (Pkt. 3, Formel 3).
|
||||
|
||||
**(3) Dangling-Check** (erwartet: keine Ausgabe — jedes interne Ziel existiert relativ zum **Quell-Verzeichnis** (file-relatives Auflösungsmodell, §5.7 Pkt. 4 / AD-7b); ein nicht existierendes Ziel liefert `DANGLING: <pfad>`; leere Ziele liefern `DANGLING: (leeres Ziel)`; **Out-of-Bundle-`..`-Traversal wird gesperrt**: ein Ziel, dessen `..`-Auflösung aus `wiki/` austritt (z. B. `../../README.md` oder `../../schema/compiler.md` aus einem Area-Concept), wird als `DANGLING: <pfad>` gemeldet — der reine `-f`-Existenztest würde sonst still passieren, weil die aufgelöste Datei außerhalb `wiki/` existiert):
|
||||
|
||||
```sh
|
||||
sh -c 'grep -roE "]\([^)]*\)" --include="*.md" --exclude=log.md wiki/ | sed -E "s#^([^:]+):\]\(([^)]*)\)\$#\1|\2#" | sort -u | while IFS="|" read -r src t; do case "$t" in ""|*:*|raw/*|./*|/*) if [ "$t" = "" ]; then echo "DANGLING: (leeres Ziel)"; fi; continue;; esac; case "$t" in "#"*) continue;; esac; case "$t" in "../schema/"*) if [ "$(dirname "$src")" = "wiki" ]; then continue; fi;; esac; p=${t%%#*}; f="/$(dirname "$src")/$p"; while printf "%s" "$f" | grep -qE "/[^/]+/\.\.(/|$)"; do f=$(printf "%s" "$f" | sed -E "s#/[^/]+/\.\.(/|$)#/#g"); done; f=${f#/}; case "$f" in wiki/*) [ -f "$f" ] || echo "DANGLING: $t";; *) echo "DANGLING: $t";; esac; done'
|
||||
```
|
||||
|
||||
Die Formel führt die Quell-Datei der Link-Quelle mit (`grep -roE` → `datei:](ziel)` → `sed` → `datei|ziel`) und löst **jedes interne Ziel einheitlich relativ zum Quell-Verzeichnis** auf (file-relatives Auflösungsmodell, §5.7 Pkt. 4): `f="/$(dirname "$src")/$p"` — bei Root-Dateien ist das identisch zum bisherigen Bundleroot-Resolve (`wiki/…`), bei Area-Dateien adressiert dasselbe-Verzeichnis-Ziele korrekt (`source-material.md` aus `wiki/<area>/index.md` → `wiki/<area>/source-material.md`) und `../`-Ziele die Aufwärts-Pfade innerhalb `wiki/` (`../llm-wiki-prinzip.md` → `wiki/llm-wiki-prinzip.md`). Nach Kollabierung der `X/..`-Segmente (Fixed-Point-`while`-Schleife) wird der aufgelöste Pfad gegen `wiki/*` geprüft — bleibt er unter `wiki/` und existiert die Datei, keine Ausgabe; verlässt er `wiki/` (Out-of-Bundle-`..`-Escape, z. B. `../../README.md` → `README.md` unterhalb `wiki/`) oder existiert die Datei nicht, `DANGLING: <pfad>`. `../schema/*` bleibt als andere Schicht **exkludiert — quellenbasiert (Loop-2-Fix)**: die Exklusion gilt nur, wenn die Quell-Datei auf der Bundleroot-Ebene liegt (`dirname <quelle>` = `wiki`, z. B. `wiki/index.md`) — dort löst einstufiges `../schema/…` garantiert außerhalb des Bundles auf (`schema/…`), bestehende Root-Links bleiben damit byte-identisch und pin-frei (§5.7 Pkt. 4). Aus einer Area-Datei löst einstufiges `../schema/…` dagegen auf `wiki/schema/…` (**in-Bundle** — die Exklusion greift dann nicht), und das Ziel läuft durch die normale Auflösung + Containment + Existenztest: nicht existent → `DANGLING: …`. Aus Areas ausbrechende `../../schema/*` fällt ebenfalls nicht unter die Exklusion und wird als `DANGLING` gesperrt (Loop-1-Fix). Das Fragment wird vor dem Existenztest gestripped (`file.md#sec` → `file.md` — kein falscher `DANGLING` für existierende Ziele; die Pin-Form-Frage bleibt beim Form-Check). Exkludiert wie beim Form-Check (Ausnahme `../schema/`). (Bekannt-konservativ: Ziele mit `)` werden am ersten `)` abgeschnitten → falsch benannte Ursache, aber keine Stille — dokumentiert in `deferred-work.md`.)
|
||||
|
||||
**(4) Kontakt-mit-`raw/`-Unverändert-Check** (erwartet: Ist ≡ Baseline — der Pin berührt `raw/`-Provenienz-Verweise nicht; die Baseline wird deterministisch aus dem **Baseline-Commit des letzten Zuwachs-Runs** dynamisch extrahiert, AD-17h — keine „identisch"-Behauptung ohne extrahierbare Baseline; **einschließende** Einzelanführungszeichen um das `sh -c`-Argument, damit `$f` erst in der inneren Shell expandiert; **Story-2.4-Re-Baseline (Loop-2-Fix):** Dieser Run ist ein expliziter Datei-Zuwachs-Run (neue Area-Dateien) — die Baseline-Extraktion läuft auf den **Kopf dieses Zuwachs-Runs** (`862cf410c624072833cd959da9a2fb26235716f6`), nicht auf den Story-2.3-`7e1f449…` und nicht auf den `baseline_commit`-Wert der Story-2.4-Spec-Frontmatter (`66451b6e6c9e139fb3aa3bbf4b01291e1e2d273a` = Zustand **vor** dem Zuwachs, extrahiert `30`); der Filter ist `grep -v "log.md$"` (Basename, damit ein künftiges Area-`log.md` konsistent mit dem `--exclude=log.md` der Ist-Zählung exkludiert wird):
|
||||
|
||||
```sh
|
||||
sh -c "grep -roE '\(raw/' --include='*.md' --exclude=log.md wiki/ | wc -l"
|
||||
sh -c 'git ls-tree -r --name-only 862cf410c624072833cd959da9a2fb26235716f6 -- wiki/ | grep -v "log.md$" | while read -r f; do git show "862cf410c624072833cd959da9a2fb26235716f6:$f"; done | grep -oE "\(raw/" | wc -l'
|
||||
```
|
||||
|
||||
Beide Vorkommen-Zählungen **müssen** übereinstimmen — die Ist-Zählung erfolgt auf dem aktuellen Baum, die Extraktion aus dem **Baseline-Commit des letzten Zuwachs-Runs** (aktuell: Run-Kopf `862cf41`, dieser Run: **38 ≡ 38**, `log.md`-exkludiert). Die Zahlen sind ein Formatbeleg, kein fester Wert: Auf dem Baum von Story 2.3 lag die Baseline bei `30` (extrahiert aus `7e1f449…`/`66451b6…` — beide tragen den Vor-Zuwachs-Zustand); der Zuwachs (neues Area-Concept `wiki/wissensarchitektur/source-material.md`) erhöht die Ist-Zählung auf `38`. Der Check verlangt die **aktuelle Baseline aus dem Run-Kopf `862cf41`** — ein Producer, der aus dem Vor-Zuwachs-Zustand (`7e1f449…` oder `66451b6…`) extrahiert, würde `30` erhalten und die Formel bräche auf dem neuen Baum (`38 ≠ 30`). Bei jedem weiteren Datei-Zuwachs ist die Baseline-Extraktion erneut auf den dann aktuellen Run-Kopf durchzuführen (die Zählung wächst um die `(raw/`-Vorkommen der neu angelegten Dateien).
|
||||
4. **NFR-4-Regel:** Jede Form-Verletzung (Pkt. 3, Formel (2) > `0`), jeder Dangling-Link (Pkt. 3, Formel (3), Ausgabe `DANGLING: …`) und jedes leere Ziel (Formel (3), Ausgabe `DANGLING: (leeres Ziel)`) ist ein **Run-FAIL mit textuell benannter Ursache** — der verletzende Ziel-Pfad bzw. die Meldung ist exakt die Formel-Ausgabe. Der Link wird korrigiert oder entfernt, bevor der Run abschließt — kein stiller Vorbeilass.
|
||||
5. **Worked Example:** Der Body-Link `[LLM-Wiki-Prinzip](llm-wiki-prinzip.md)` (in `wiki/wissensarchitektur-trennung-states.md`) ist in der gepinnten Form. Form-Check-Auflösung: Ziel `llm-wiki-prinzip.md` trifft `^[^#]+\.md$` → zählt als `0`; keine Ausnahme-Klasse greift. Dangling-Check-Auflösung: `wiki/llm-wiki-prinzip.md` existiert → keine Ausgabe. Der gleiche Link in `wiki/index.md` (Bestands-Check, Pkt. 3, Formel (1)) löst identisch auf.
|
||||
|
||||
**Area-`../`-Beispiel (Story 2.4):** Der Body-Link `[LLM-Wiki-Prinzip](../llm-wiki-prinzip.md)` in `wiki/wissensarchitektur/source-material.md` ist in der gepinnten file-relativen Form. Form-Check: Ziel `../llm-wiki-prinzip.md` fällt unter die `../`-Exklusions-Stufe → zählt als `0` (keine Form-Verletzung). Dangling-Check (einheitlich file-relativ, Quell-Verzeichnis `wiki/wissensarchitektur`): Auflösung `wiki/wissensarchitektur/../llm-wiki-prinzip.md` → kollabiert `wiki/llm-wiki-prinzip.md`, bleibt unter `wiki/`, existiert → **keine Ausgabe**. Gleiches Modell für dasselbe-Verzeichnis-Ziele von der Area-`index.md` aus: `[source-material.md](source-material.md)` in `wiki/wissensarchitektur/index.md` → `wiki/wissensarchitektur/source-material.md` existiert → keine Ausgabe. Die Formel-2/3-`../`-Schärfung macht genau diesen in-Bundle-Aufwärts-Pfad — und die einheitliche file-relative Auflösung alle Area-Ziele — zulässig.
|
||||
|
||||
**Negativ-Beispiel 1:** `[Test](ohne-endung)` — Ziel ohne `.md`-Endung. Form-Check (Pkt. 3, Formel (2)) liefert `1` (Ziel `ohne-endung` zählt als Übertretung), Dangling-Check (Pkt. 3, Formel (3)) liefert `DANGLING: ohne-endung` — deterministische Fehlerursache, Run-FAIL gemäß Pkt. 4 (der Link wird korrigiert zu `[Test](ohne-endung.md)` oder entfernt).
|
||||
|
||||
**Negativ-Beispiel 2 (Out-of-Bundle-`..`-Escape, Loop-1-Review-Fix):** Ein Body-Ziel `[x](../../README.md)` aus `wiki/wissensarchitektur/source-material.md` — der `-f`-Existenztest allein löst `wiki/wissensarchitektur/../../README.md` zur existierenden Workspace-`README.md` auf und würde **still passieren**. Formel 3 (Pkt. 3) sperrt: Auflösung kollabiert zu `README.md`, das nicht unter `wiki/` bleibt → **`DANGLING: ../../README.md`** — Run-FAIL gemäß Pkt. 4, keine Stille. Analog `[x](../../schema/compiler.md)` → `DANGLING: ../../schema/compiler.md` (der aufgelöste `schema/…`-Zielpfad liegt außerhalb des Bundles; die `../schema/*`-Exklusion gilt nur für das einstufige Root-`index.md`-Muster `../schema/*`, nicht für aus Areas ausbrechende `../../schema/*`). Nur das einstufige `../schema/*` aus Root-Ebenen-Quellen bleibt als andere Schicht exkludiert (§5.7 Pkt. 4). **In-Bundle-Variante (Loop-2-Fix):** `[x](../schema/compiler.md)` aus `wiki/wissensarchitektur/source-material.md` — Auflösung `wiki/schema/compiler.md` (unter `wiki/`, Datei existiert nicht) → **`DANGLING: ../schema/compiler.md`**; die quellenbasierte `../schema/*`-Exklusion greift nur für Bundleroot-Ebenen-Quellen, nicht für Area-Quellen — kein stiller Vorbeilass (NFR-4).
|
||||
|
||||
Hinweis: Der Validator (strukturell unverändert, Story-2.2-Präzedenz) akzeptiert im Punkt-11-Check weiterhin beide Schreibweisen; der Pin liegt auf Instruktions-Ebene (Selbsttest-Formeln, Pkt. 3).
|
||||
|
||||
## 5.7 Deterministische Bereichszuordnung & Concept-Hierarchie (Story 2.4)
|
||||
|
||||
Bereichszuordnung und Concept-Hierarchie sind **textual-deterministisch** (AD-7c, A0-10, AD-13) — nie per Embedding/Vector-Infrastruktur (AD-13). Diese Sektion ist der **einzige Instruktions-Ort** der Bereichszuordnungs-Regel (D-3). Sie fügt **kein** Prädikat, keine neuen §7-Invaliditätsklassen und keinen Schema-/Validator-Change hinzu (Story-2.2/2.3-Präzedenz; Validator Punkt 11 akzeptiert Areas bereits strukturell: Area-`index.md`, verlinkt im nächsten Vorfahren). Eine als Area gedachte Anlage (`wiki/<area>/index.md` + Concept darunter) ist ab dieser Story **konform**, nicht mehr Bereichs-Hinweis (§5.1).
|
||||
|
||||
1. **Routing-Regel („wohin gehört ein Thema"):** Für jede erkannte neue Wissenseinheit wird der Ziel-Bereich deterministisch bestimmt:
|
||||
- **(a) First-Class-Link aus dem bestehenden `index.md`-Baum:** Textuelles Treffer-Prädikat (Loop-2-Fix, kein „inhaltlich deckungsgleich"-Urteil — AD-13): Ein bestehender `index.md`-Link (Bundleroot oder Area-`index.md`) ist ein **Treffer**, wenn die **Identität seines Link-Ziels** (relativer OKF-Pfad ohne `.md`, Pkt. 2) **gleich dem kanonischen Namen des neuen Themas** (Pkt. 2) ist. Liegt genau ein Treffer vor, wird das neue Concept **in den Bereich dieses Links** angelegt (`wiki/<area>/<concept>.md`); der Bereich existiert damit bereits als `wiki/<area>/index.md`. **Mehrfachtreffer — deterministisches Tie-Break (Loop-2-Fix):** Bundleroot-Links schlagen Area-Links (ein Bundleroot-Treffer verweist auf ein Root-Concept → neues Concept auf Root-Ebene gemäß (b), da kein Area-Bereich zugeordnet ist); unter mehreren Area-Treffern gewinnt die **lexicografisch kleinste Area-Pfad-Zeichenfolge** (z. B. `wiki/a/…` vor `wiki/b/…`). Die Auswahl ist damit textual-deterministisch aus dem bestehenden `index.md`-Baum ableitbar (AD-7c, A0-10).
|
||||
- **(b) Default Root-Ebene:** Existiert kein solcher Link, wird das Concept auf Root-Ebene angelegt (`wiki/<concept-kebab-case>.md`, §5.1). Neue Areas werden **nur konsolidiert** erzeugt (mehrere neue Concepts desselben erkannten Themas im selben Run, die einen eigenständigen Bereich rechtfertigen) — nicht pro Einzel-Concept erfinden (AD-7c, A0-10; Rücksprache-Pflicht §0 Ask-First der Story-Spezifikation).
|
||||
- **Kein Embedding/Vector, kein reines LLM-Urteil** als Entscheidungsbasis (AD-7c/AD-13, A0-10).
|
||||
2. **Kanonische ID-Normalisierung (AD-7a, A0-8):** Identität = relativer OKF-Pfad ohne `.md` — **genau eine** Normalisierung, für alle Producer (auch per **Basename-Filter** für `log.md`-Exklusion, Formel 4):
|
||||
|
||||
| OKF-Pfad | Identität |
|
||||
|---|---|
|
||||
| `wiki/spring/index.md` | `spring` |
|
||||
| `wiki/spring/testing.md` | `spring/testing` |
|
||||
| `wiki/wissensarchitektur/index.md` | `wissensarchitektur` |
|
||||
| `wiki/wissensarchitektur/source-material.md` | `wissensarchitektur/source-material` |
|
||||
| `wiki/llm-wiki-prinzip.md` | `llm-wiki-prinzip` |
|
||||
|
||||
Eine als Area gedachte Anlage (`wiki/<area>/index.md` + Concept darunter) ist damit **konform**; der Bereichs-Hinweis aus §5.1 ist aufgelöst. Konzept-`id`s (s. `sources[].id`, §5.5 Pkt. 3) sind unabhängig davon je Concept eindeutig — Adressraum ist Concept-Pfad + `id`.
|
||||
3. **Top-Level-Kollisions-Hold (A0-10, fixierter §3.2):** Kollidiert ein Erstellungskandidat mit einem bestehenden Top-Level-Pfad (deterministisch: Dateikollision über den relativen OKF-Pfad, §3.1/§3.2, AD-7a), löst der **fixierte §3.2-Kollisions-Hold** aus — **kein** neues Prädikat, **kein** stiller Overwrite, kein Index-Link, keine Datei: der Run bricht für diese Einheit textuell ab („Concept existiert bereits — Aktualisierung ist Epic 3") und setzt mit den übrigen Einheiten fort (§3.2; „teilweise erfolgreich"). **Kein MOVE/Neuzuordnung bestehender Concepts** — das ist Kuratierung mit AD-7d-Redirect-Pflicht (Epic-3-Nähe, nicht in den ACs dieser Story; Ask-First).
|
||||
4. **File-relatives Link-Auflösungsmodell (löst das §5.6-Defer):** Concept-Links sind **file-relativ** zur `.md`-Datei (AD-8/FR-10/AD-7b — eine syntaktische Form, beide Ebenen): bei Root-Dateien ist file-relativ ≡ bundle-relativ (die bestehenden Bestands-Links bleiben byte-identisch, Null-Delta zu Story 2.3); in Areas bezeichnen `../`-Präfixe die Aufwärts-Ziele **innerhalb `wiki/`** (`[<text>](../<root-concept>.md)`). Auflösung & Containment (§5.6 Pkt. 3, Formel 3): `../`-Ziel relativ zum Quell-Verzeichnis auflösen, `X/..`-Segmente kollabieren, aufgelöster Pfad MUSS unter `wiki/` bleiben — sonst `DANGLING` (Out-of-Bundle-`..`-Escape gesperrt, Loop-1-Fix). `../schema/*` als andere Schicht (Ziel außerhalb des Bundles) bleibt exkludiert — Abgrenzung über das **Zielverzeichnis** (unter `wiki/` = in-Bundle), nicht über das bloße `../`-Präfix; einstufiges `../schema/*` aus Root-Dateien ist damit weiterhin pin-frei (bestehende Root-`index.md`-Links unverändert). `.md`-Endung bleibt Pflicht (§5.6 Pin).
|
||||
5. **Area-`index.md` (Vertrag §2/§6, AD-9/FR-11):** Eine Area besitzt exakt eine `wiki/<area>/index.md`, **frontmatterlos** (Punkt 10), die ihre Area-Concepts in der gepinnten Form (§5.6) verlinkt (Identity = relativer OKF-Pfad ohne `.md`). Die Bundleroot-`index.md` verlinkt die Area-`index.md` (Navigation Root → Area, AD-9). **Area ohne `index.md` ist strukturell invalide** und wird vom Validator wörtlich gemeldet: `FAIL … Punkt 11: Index-Regel verletzt (Area ohne index.md=<area>)` (kein inventiertes Label; Verdikt-Grammatik §5 des Validators). Ein neues Area-Concept MUSS in `wiki/<area>/index.md` verlinkt sein (§5.3 Pkt. 3 ist entsprechend §5.7-nachgeführt); sonst Punkt 11.
|
||||
6. **Worked Example (Area-Concept):** `wiki/wissensarchitektur/source-material.md` — ein neues Area-Concept: `type: concept`, `sources` → `raw/architecture-spine/architecture-spine-2026-08-14.md` (s1) + `raw/prd/prd-wow20-2026-08-14.md` (s2), §5.5-Inline-Verweise je belegter Aussage, Body-Links auf Root-Concepts in der file-relativen `../`-Form (`[LLM-Wiki-Prinzip](../llm-wiki-prinzip.md)` u. ä.), inhaltsbegründet. Verlinkt in der Area-`index.md` `wiki/wissensarchitektur/index.md` (frontmatterlos, gepinnte Form); diese wiederum in der Bundleroot `wiki/index.md` (Area-Sektion). §5.6-Formel-1 (Bestands-Check) erfasst die Area-Links; Formel 2 (Form-Check) `0`; Formel 3 (Dangling-Check) keine Ausgabe (in-Bundle-`../`-Auflösung, §5.7 Pkt. 4).
|
||||
|
||||
## 5.8 Progressive Discovery über `index.md` (Story 2.5)
|
||||
|
||||
Progressive Discovery ist die **schrittweise Navigation** eines Consumers von der Bundle-Übersicht zu den Concepts über die `index.md`-Hierarchie (AD-9, FR-11) — die **erste Discovery-Ebene** des Bundles. Diese Sektion ist der **einzige Instruktions-Ort** der Discovery-Semantik (D-3, Story 2.5). Sie fügt **kein** Prädikat, keine neuen §7-Invaliditätsklassen und keinen Schema-/Validator-Change hinzu (AD-3); der Validator bleibt bei Punkt 11 als strukturelle Index-/Verlinkungs-Prüfung (Area-Existenz + Concept-in-Index verlinkt). Die Discovery-Vollständigkeit (Root → Area → Concept) ist **keine** neue §7-Invaliditätsklasse — sie wird deterministisch als **Instruktions-Selbsttest** (Pkt. 2) belegt: Verstöße gegen die gewurzelte Erreichbarkeit bzw. die Zwei-Ebenen-Kartografie werden vom Producer vor Abschluss des Runs über eine **re-executierbare Selbsttest-Formel** textuell benannt (NFR-4-analog, Run-FAIL-Nachweis). Sie antwortet zugleich auf die offene Defer-Frage **F-07** (verschachtelte Areas/Unter-Ebenen, `wiki/a/b/concept.md`): die Kartografie ist ab Story 2.5 konsolidiert **Zwei-Ebenen** (Pkt. 3).
|
||||
|
||||
1. **Discovery-Pfad (AD-9, FR-11):** Ein Consumer startet die Navigation an der **Bundle-Root** `wiki/index.md` und folgt dann den Area-`index.md`-Dateien zu den Concepts:
|
||||
|
||||
- **Bundleroot `wiki/index.md`** — Einstiegspunkt: verlinkt die **Root-Concepts** (direkt, §5.3 Pkt. 3) und die **Area-`index.md`-Dateien** (Navigation Root → Area, AD-9).
|
||||
- **Area-`index.md`** (`wiki/<area>/index.md`, **frontmatterlos**, Vertrag §2/§6, Validator Punkt 10) — verlinkt ihre **Area-Concepts** in der gepinnten §5.6-Form (§5.7 Pkt. 5).
|
||||
- **Concept** (`wiki/<concept>.md` bzw. `wiki/<area>/<concept>.md`) — das Ziel der Navigation.
|
||||
|
||||
Erwarteter Erreichbarkeits-Satz **(gewurzelte Erreichbarkeit, Root → Area → Concept)**: jedes Root-Concept ist aus der Bundleroot erreichbar; jede Area ist aus der Bundleroot verlinkt (AD-9); jedes Area-Concept ist aus seiner Area-`index.md` erreichbar. Originäre Aussage-Pflicht des §5.7-Discovery-Bildes bleibt §5.7 Pkt. 5 (ein neues Area-Concept MUSS in `wiki/<area>/index.md` verlinkt sein, ein neues Root-Concept in `wiki/index.md` — §5.3 Pkt. 3); §5.8 erläutert die Discovery-**Semantik** dieser bestehenden Regeln, macht den Erreichbarkeits-Satz als Kriterium explizit und bindet ihn an die re-executierbare Selbsttest-Formel (Pkt. 2).
|
||||
2. **Gewurzelte Erreichbarkeit als deterministisches Discovery-Kriterium + re-executierbarer Selbsttest (AD-17h):** Die Discovery-Vollständigkeit ist textuell prüfbar: jede Area `wiki/<area>/` MUSS von der Bundleroot aus verlinkt sein (Root-→-Area-Pfad, AD-9). Die Area→Concept-Verlinkung („jedes Area-Concept in seiner Area-`index.md`") ist durch den **Validator Punkt 11** (`Concept nicht verlinkt=<concept>`) mechanisch abgedeckt und wird hier bewusst **nicht dupliziert** (so auch der Erreichbarkeits-Satz für Root-Concepts, siehe unten). Der Producer führt vor Abschluss eines Runs, der Areas oder Area-Concepts anlegt/verlinkt, den folgenden Selbsttest ab der Workspace-Root aus (erwartet: **keine** Ausgabe; jede Ausgabe = textuell benannter Selbsttest-Befund, der vor Run-Abschluss zu beheben ist — Run-FAIL gemäß §5.6 Pkt. 4-analoger NFR-4-Regel, kein stiller Vorbeilass). **Prämisse (Loop-3-Fix):** die Formel setzt POSIX-`sh` mit GNU-`find`/`grep`/`sort` (z. B. Git-Bash auf win32, NFR-1/NFR-5) und die Arbeitsverzeichnisse `wiki/index.md` ab — die CWD-Präguard der Formel meldet `SELBSTTEST-SETUP-Fehler: …` mit Exit `1`, wenn `wiki/index.md` fehlt (falsches CWD), statt mit leeren Ausgabe + Exit `0` als SUCCESS durchzugehen:
|
||||
|
||||
```sh
|
||||
sh -c '[ -f wiki/index.md ] || { echo "SELBSTTEST-SETUP-Fehler: Workspace-Root (wiki/index.md fehlt)"; exit 1; }; find wiki -mindepth 2 -name index.md | while IFS= read -r f; do a="${f#wiki/}"; a="${a%/index.md}"; case "$a" in */*) continue;; esac; grep -qF "]($a/index.md" wiki/index.md || grep -qF "](./$a/index.md" wiki/index.md || echo "UNREACHABLE AREA: $a"; done; find wiki -mindepth 3 -type f -name "*.md" | LC_ALL=C sort -u | while IFS= read -r f; do d="${f#wiki/}"; a="${d%%/*}"; echo "NESTED AREA: $a"; done | LC_ALL=C sort -u'
|
||||
```
|
||||
|
||||
Die Formel prüft in zwei unabhängigen Läufen — je Verletzung **genau eine** deterministische Meldung:
|
||||
|
||||
**(A) Index-Erreichbarkeits-Check** (erster Lauf): `find wiki -mindepth 2 -name index.md` — jede Ein-Ebenen-Area-`index.md` (`wiki/<area>/index.md`) MUSS aus `wiki/index.md` **verlinkt** sein (Root→Area, AD-9); verlinkt = echtes Markdown-Link-Ziel in gepinnter §5.6-Form `](a/index.md` bzw. `](./a/index.md` in der Bundleroot (Loop-3-Fix: das Muster prüft die Linksyntax `](`, nicht das bloße Klammer-Paar — ein Prosa-Ausdruck `(a/index.md` ohne `](` besteht den Check nicht; `grep -qF` (Fix-String) statt ERE, damit ERE-Metazeichen im Area-Namen kein stilles Durchpassen erzeugen). Fehlt der Link, **`UNREACHABLE AREA: <area>`** (textuell benannter Instruktions-Selbsttest-Befund, Run-FAIL gemäß §5.6 Pkt. 4-analoger NFR-4-Regel). `*/*`-Kandidaten (`wiki/a/b/index.md`) werden hier übersprungen — ihre Verletzung ist keine Erreichbarkeit, sondern die Struktur selbst und wird in (B) gemeldet.
|
||||
|
||||
**(B) Zwei-Ebenen-Detektion** (zweiter Lauf): `find wiki -mindepth 3 -type f -name "*.md"` — jede Markdown-Datei mit drei Segment-Ebenen unter der Bundleroot (`wiki/<a>/<b>/…`) ist ein Zwei-Ebenen-Kandidat → **`NESTED AREA: <a>`** (die erste Ebene der nicht-zulässigen Struktur). Dieser Lauf schließt auch die **Area-ohne-`index.md`-Lücke**: `wiki/a/b/concept.md` (ohne `index.md`) war dem reinen `index.md`-Scan unsichtbar und wird jetzt erfasst. `LC_ALL=C sort -u` konsolidiert Mehrfach-Meldungen (mehrere Dateien unter derselben ersten Ebene → eine Meldung; C-Locale macht die Meldungsreihenfolge umgebungsunabhängig deterministisch, AD-17h). **Zwei Zustände (Loop-3-Klarstellung):** (1) **Hold-Zeitpunkt** — der Erstellungskandidat wird im Mutieren-Schritt (Pkt. 3) angehalten: keine Datei, kein Index-Link; (2) **Formel-Befund** — existiert eine Markdown-Datei in Tiefe ≥ 3 unter der Bundleroot (nachträglich oder auf einem synthetischen Prüfbaum), meldet dieser Lauf `NESTED AREA: <a>`; der Sandbox-Nachweis im `log.md`-Eintrag belegt die Detektion auf einem synthetischen Baum mit angelegter Testdatei.
|
||||
|
||||
Beide Läufe ohne Ausgabe = Discovery-SUCCESS. Die Meldungen sind **Instruktions-Selbsttest-Befunde** — kein Validator-Punkt, keine neue §7-Klasse (AD-3).
|
||||
|
||||
- **`UNREACHABLE AREA: <area>`** — eine Area-`index.md` existiert, ist aber von der Bundleroot **nicht** verlinkt (kein Root→Area-Pfad): die Area bleibt für die Navigation unsichtbar (AD-9). Die Meldung ist ein textuell benannter **Instruktions-Selbsttest-Befund** (Run-FAIL gemäß §5.6 Pkt. 4-analoger NFR-4-Regel) — **kein** Validator-Punkt, **keine** neue §7-Klasse.
|
||||
- **`NESTED AREA: <area>`** — jede Markdown-Datei in einem Zwei-Ebenen-Pfad (Tiefe ≥ 3, Lauf (B), Pkt. 3): ein `wiki/a/b/index.md`-Kandidat wie auch ein `wiki/a/b/concept.md` **ohne** `index.md` (die Area-ohne-Index-Lücke, die der reine `index.md`-Scan übersähe) sind Fälle der **konsolidierten Zwei-Ebenen-Kartografie** (Pkt. 3): die Verzeichnisstruktur ist keine zugelassene Anlageform; ein solcher Kandidat wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten (Trigger: Mutieren-Schritt, Pkt. 3 — keine Datei, kein Index-Link, Meldung, Run „teilweise erfolgreich"; nachträgliche bestehende Tiefe-≥-3-Dateien meldet Lauf (B)) — **analog**, aber **bewusst nicht** über den §3.2-Kollisions-Hold der Dateikollision bestehender Concepts (§3.2, Z. 40, bliebe ungeschärft für brandneue Pfade).
|
||||
- Der Erreichbarkeits-Satz für **Root-Concepts** (jedes Root-Concept in `wiki/index.md` verlinkt) ist durch den Validator-Punkt-11-Check (§3 Punkt 11) abgedeckt und wird hier nicht dupliziert; der Selbsttest deckt die vom Validator offene Lücke (Root→Area-Navigation) ab. (Bekannte offene Lücke des Punkt-11-Checks: die file-relative Area-Lesart — ein wörtlich-mechanischer Check meldete `Concept nicht verlinkt=wissensarchitektur/source-material`; Behebung steht im Rev-9-Aktionsitem, s. `deferred-work.md`, Spec-2.4-Defer.) Die §5.6-Formeln (Z. 133–166) decken die **Link-Form** weiterhin ab (der Selbsttest prüft die Erreichbarkeit, nicht die Form — die Form bleibt beim §5.6-Form-Check).
|
||||
3. **Konsolidierte Zwei-Ebenen-Kartografie (antwortet Defer F-07, schließt es):** Das Bundle-Navigationsmodell besteht ab Story 2.5 aus **einer** Area-Ebene: Root-Concepts (direkt aus der Bundleroot) + Areas (`wiki/<area>/`), jede mit genau einer frontmatterlosen `wiki/<area>/index.md`, die ihre Area-Concepts in gepinnter §5.6-Form verlinkt; die Bundleroot verlinkt die Area-`index.md`-Dateien (Navigation Root → Area, AD-9). **Verschachtelte Areas sind keine zugelassene Anlageform:** `wiki/a/b/` mit Concept darunter ist **kein** „Area mit Inhalt" — ein solcher Kandidat (Erstellungskandidat oder Discovery-Ziel) wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten: keine Datei, kein Index-Link, textuelle Meldung **`NESTED AREA: <area>`** (Pkt. 2); der Run bricht für dieses Gebilde mit „teilweise erfolgreich" ab (die übrigen erkannten Einheiten laufen weiter, NFR-4). **Tiefen-Definition (Loop-3-Klarstellung):** „Tiefe" ist die Segment-Anzahl unter der Bundleroot — `wiki/<a>/<b>/…` hat Tiefe ≥ 3 (zwei Verzeichnisstufen plus Datei); das ist exakt die `find -mindepth 3`-Schwelle von Lauf (B). Die Meldung benennt immer die **erste** Ebene `<a>` der nicht-zulässigen Struktur. **Trigger im Run-Flow (Loop-3-Fix):** der Hold feuert im **Mutieren-Schritt** (§0-Ablaufstruktur, Schritt (4)) — der Producer prüft vor Anlage eines Ziel-Pfads dessen Tiefe unter der Bundleroot; Tiefe ≥ 3 → Hold (kein §5.7-Routing kann Tiefe ≥ 3 strukturell erzeugen, der Hold sichert die Regel zusätzlich). Lauf (B) der Selbsttest-Formel bleibt der nachträgliche Baum-Check gegen bestehende Tiefe-≥-3-Dateien. Der Hold ist **§5.8-lokal** verankert (dieser Absatz) und trägt die **Discovery-Entscheidung** der Story — er ist **bewusst nicht** der §3.2-Kollisions-Hold der Dateikollision (§3.2, Z. 40): jener bleibt ausschließlich dem Fall vorbehalten, dass ein Ziel-Pfad bereits als Concept existiert („Concept existiert bereits — Aktualisierung ist Epic 3"); ein brandneuer Zwei-Ebenen-Pfad kollidiert mit keinem existierenden Pfad und wird daher über diesen §5.8-Hold gelenkt, nicht über §3.2. Die F-07-Frage „was ist Area mit Inhalt" ist damit instruktionsseitig deterministisch beantwortet: **Area mit Inhalt = `wiki/<area>/` mit `index.md` + Area-Concepts auf der Area-Ebene**; eine tiefere Verschachtelung ist kein eigener Bereich, sondern ein **§5.8-Zwei-Ebenen-Verstoß** (nicht erlaubt). Keine zweite Discovery-Ebene über die Zwei-Ebenen-Struktur hinaus (Boundaries, „Never").
|
||||
4. **Suche = Consumer-grep (AD-13, FR-11, NFR-3):** Die Navigation ist die **primäre** Discovery (gewurzelte Erreichbarkeit, Pkt. 1–2). Die **Suche ist konsumenten-/extern-seitig** — die Discovery braucht **keine proprietäre Datenbank, keinen Such-Dienst, kein Embedding/Vector, kein Index-Datei-Format** (AD-8, AD-13): ein Consumer führt die textuell-deterministische Suche selbst aus, z. B. `grep -rn <term> wiki/` (rekursiv) bzw. `rg <term> wiki/` (ripgrep) über den Markdown-Baum (NFR-3 „Standard-Dateioperationen"); die rekursive Form ist verbindlich — ein nicht-rekursives `grep -n <term> wiki/` schlägt auf ein Verzeichnis fehl (Exit 2). Das Bundle bleibt ohne geladene Indizes — z. B. nach einem Git-Clone — vollständig verständlich (NFR-2, NFR-5). Der Story-2.5-Vorbehalt (§7 Z. 253 auf „Suche"-Rest gekürzt) ist damit aufgelöst: die Suche ist ein Consumer-Thema, kein Bundle-/Instruktions-Thema mehr.
|
||||
5. **Discovery-Demo (optional, kein MOVE):** Bestehende Root-Concepts werden **nicht** in Areas verschoben (Kuratierung/AD-7d ist Epic-3-Nähe). Als Discovery-Demo **kann** (optional) ein **neues** Root-Concept `wiki/<concept>.md` ergänzt und (a) in der Bundleroot (§5.3 Pkt. 3) sowie (b) — rein informierend — über einen zusätzlichen **Body-Link** in gepinnter file-relativer §5.6-Form (`[<text>](../<concept>.md)`) aus einem bestehenden Area-Concept heraus verlinkt werden (z. B. aus `wiki/wissensarchitektur/source-material.md`; der Inhalt bleibt Root-Concept; der Area-Body-Link ist zusätzliche Erreichbarkeit, keine Neuzuordnung; ein Link aus einer Concept-Body-Datei ist ein Body-Link, kein Index-Link — §5.6 Pkt. 2). Beide Verlinkungen halten die einheitliche Zwei-Ebenen-Kartografie (Pkt. 3). Die Durchführung ist **optional** (Matrix-Zeile `DISCOVERY_DEMO_ROOT_AREA_LINK`); sie **erhöht** die `(raw/`-Zählung der §5.6-Formel-4-Baseline (neuer Zuwachs-Run, Re-Baseline-Pflicht) und ist nur zusammen mit dem Nachweis dieses neuen Baselines zusätzlich durchzuführen — wird sie weggelassen, bleibt Formel 4 unverändert `38 ≡ 38` (kein Re-Baseline-Bedarf). Die hier beschriebene Regel ist die Demo-**Instruktion**; ob das konkrete Demo-Concept in diesem Run angelegt wird, entscheidet der Producer im Rahmen der optionalen Durchführung.
|
||||
|
||||
## 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, Area-`index.md`, `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: jedes neue Concept ist in der `index.md` **seines Bereichs** verlinkt (Root-Concepts in `wiki/index.md`, Area-Concepts in `wiki/<area>/index.md`, §5.7 Pkt. 5).
|
||||
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). Der bereits geschriebene Teilzustand (neue Concept-Dateien, Index-Verlinkungen, `log.md`-Einträge) wird gemäß §5.3 zurückgerollt, sodass das Bundle seinen Zustand vor dem Run wieder einnimmt.
|
||||
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.5 canonical Key-Reihenfolge (Validator §4.1) | `type` → `sources` → `generated` | — (kein Validator-FAIL: Reihenfolge ist Output-Normalform, kein §7-Punkt; der Compiler erzeugt sie deterministisch und die Normalform-Abweichung tritt damit nicht auf) |
|
||||
| §4.5 keine Duplikat-Keys (Punkt 13) | jeder Key einmal | zweimal `type:` → Punkt 13 |
|
||||
| §4.2 `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.5 kein `okf_version`/`type: bundle` (Punkt 9) | (nicht vorhanden) | `okf_version: "0.2"` → Punkt 9 |
|
||||
| §5.1/§5.7 Ziel-Pfad & Verlinkung (Punkt 11, §6; §5.7 Pkt. 1/5) | Root: `wiki/<slug>.md` + Link in `wiki/index.md`; Area: `wiki/<area>/<slug>.md` + Link in `wiki/<area>/index.md` (konform, §5.7) | Concept ohne Link in der `index.md` seines Bereichs → Punkt 11; Area ohne `index.md` → Punkt 11 („Area ohne index.md=<area>") |
|
||||
| §5.4 `log.md`-Dokumentation (§5) | datumsgruppierter Eintrag mit Concept-Pfad + Quellen | fehlender Eintrag → kein Validator-FAIL, aber dokumentarische Pflicht verletzt |
|
||||
| §5.6 Concept-Link-Form (FR-10, AD-7b, A0-9) | `[<text>](<concept-pfad>.md)` (file-relativ, `.md`-Endung; in Areas `../`-fähig, §5.7 Pkt. 4) | `[…](concept-pfad)` ohne `.md` → Form-Check (Pkt. 3, Formel 2) > 0, Run-FAIL (NFR-4) |
|
||||
| §4.2 Alle-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 und in Areas gemäß §5.7** begrenzt. Folgendes verbleibt in anderen Stories und wird hier **nicht** vorweggenommen:
|
||||
|
||||
- **Claim-granulare Provenienz** je belegter Aussage (Inline-`raw/`-Verweise, Kontext-Marker) — in **§5.5** dieser Instruktion verankert (Story 2.2; AD-4a, A0-3). Keine neue §7-Klasse, kein Standalone, keine Vertragsänderung.
|
||||
- **Deterministische Area-Zuordnung & Concept-Hierarchie** (Anlage von `wiki/<area>/index.md` + `wiki/<area>/<concept>.md`) — in **§5.7** dieser Instruktion verankert (Story 2.4; AD-7c, A0-10, A0-8, AD-13). Keine neue §7-Klasse, kein Validator-Change.
|
||||
- **Progressive Discovery über `index.md`** (Navigation, Area-Indizes) — in **§5.8** dieser Instruktion verankert (Story 2.5; AD-9, FR-11, AD-13, NFR-3). **Suche** bleibt konsumenten-/extern-seitig (Consumer-grep über `wiki/`, §5.8 Pkt. 4 — kein Bundle-/Instruktions-Thema mehr). Keine neue §7-Klasse, kein Schema-/Validator-Change.
|
||||
- **Eine genau-eine-Linkform** (file-relativ mit `.md`-Endung, in Areas `../`-fähig) — in **§5.6** dieser Instruktion gepinnt (Story 2.3; AD-7b, A0-9, FR-10; Auflösungsmodell §5.7 Pkt. 4) — der Punkt-11-Check des Validators akzeptiert bis auf Weiteres beide Schreibweisen (strukturell unverändert, Story-2.2-Präzedenz).
|
||||
- **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 8): §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-4a (claim-granulare Provenienz, §5.5), AD-5 (inkrementelle Kompilation), AD-6 (Reason/Mutate-Trennung), AD-7a (Identität = OKF-Pfad ohne `.md`, §5.7), AD-7b (genau eine Linkform gepinnt, §5.6), AD-7c (deterministische Bereichszuordnung, §5.7), AD-7d (Renaming/Redirect-Pflicht — nicht in den ACs, Epic 3), AD-8 (Standard-Markdown-Links = Navigations-/Beziehungsschicht, §5.6), AD-9 (Progressive Discovery, §5.7/§5.8), AD-10 (agent-unabhängige Regeln), AD-11 (keine eigene Runtime), AD-13 (Retrieval gehört zu Consumers / Suche = Consumer-grep / keine Embedding-Bereichszuordnung, §5.7/§5.8), AD-14 (Git liefert Historie, nicht Domain-State), AD-15 (Trust-Metadaten v1), AD-16 (Konflikte werden explizit bewahrt), 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), FR-10 (Concepts miteinander verlinken, §5.6), FR-11 (Progressive Discovery siehe PRD-§4.3-Zeile unten — Discovery-Pfad/gewurzelte Erreichbarkeit, §5.8), FR-16 (Consumer-Unabhängigkeit), NFR-3 (Agent Readability — Standard-Dateioperationen/grep über `wiki/`, §5.8 Pkt. 4), A-4 (nur lokale Sources).
|
||||
- Epics (raw/epics): Story-2.1-Ziel und -Abgrenzung zu Story 2.2–2.5; A0-3 (Kontext-Marker-Wortlaut, §5.5), A0-8 (Concept-Identität/Normalisierung, §5.7), A0-9 (eine erlaubte Linkform, §5.6), A0-10 (deterministische Bereichszuordnung, §5.7), A0-13 (Lease-Root-Scope); FR-6/FR-12/FR-14, A0-6/A0-7/A0-11/A0-18 (Belege der nachkonformierten Concept-Bodies).
|
||||
- PRD §4.3 (FR-11 — progressive Discovery, §5.7 Pkt. 5/§5.8) und §8.2/§8.3 (Canonical State; Separation of Concerns).
|
||||
|
||||
**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.
|
||||
- **Revision 1.3 (2026-08-16, bmad-code-review Story 2.1):** Nachschärfungen aus dem Review-Patch-Block — §1-Überschrift ins Deutsche („Input (was der Compiler konsumiert)"); Prüfgrundlagen-Referenz auf `validator.md` Revision 7 angeglichen (§0-Header, §8); §6.6 canonical-Key-Reihenfolge-Zeile von der ✗-Liste auf reine ✓-Vorgabe korrigiert (kein Validator-FAIL, Normalform ohne §7-Punkt) und das irreführende „§6.4"-Label auf §4.2 berichtigt; §1.2 vs. §1.4-Evidenz-Widerspruch aufgelöst (§1.2 präzisiert auf verarbeitbare Evidenz, §1.4 Artefakt-Ausnahme als dokumentarische Konvention der Source-Bereitstellung nach `raw/README.md` gekennzeichnet).
|
||||
- **Revision 1.4 (2026-08-17, bmad-code-review Re-Run Story 2.1, Stand nach Validator-Rev-8):** Nachschärfungen aus dem unabhängigen Re-Review — Prüfgrundlagen-Referenz auf `validator.md` Revision 8 angehoben (§0-Header, §8); §6.6-Referenzlabels berichtigt (canonical Key-Reihenfolge, Duplikat-Keys, `okf_version`/`type: bundle` → §4.5, `sources`-Eintrag-Key-Subset → §4.2; berichtigt die Rev-1.2-Korrektur, die das Label fälschlich von §4.5 auf §4.4 bewegt hatte); §1.4 „Aufträge" → „Formate", §5.2 „grossen" → „großen"; §3.2 Kollision-Hold um Run-Fortsetzung mit den übrigen Einheiten und Gesamt-Run-Status („teilweise erfolgreich") ergänzt; §5.3/§6.3 um explizite Rollback-Sequenz für den Teilzustand (Concept-Datei + Index-Verlinkung + `log.md`-Eintrag) bei Validierungs-FAIL ergänzt.
|
||||
- **Revision 1.5 (2026-08-17, Story 2.2):** Sektion „Claim-granulare Provenienz" als §5.5 eingefügt (nach §5, vor §6) — Inline-`raw/`-Verweis je belegter Aussage (+ `id`-Attribution, Vertrag §3.3), Kontext-Marker je Übernahme („übernommen aus … auf Basis von …, nicht eigenständig belegt"), eindeutiges `id`-Scoping je Concept, Selbsttest-Kriterien (belegte Aussage → Verweis; Übernahme → Marker; kein unautorisierter Key; UNBELEGTE_AUSSAGE als Marker statt erfundener Beleg) — AD-4a/4b/4c, AD-13, AD-17h. §7-Selbstbegrenzung entsprechend umformuliert (Claim-granulare Provenienz jetzt in §5.5 verankert, nicht mehr deklariert als „verbleibt in Story 2.2"). Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 1.6 (2026-08-17, Story-2.2-Re-Review, Patch-Runde):** §5.5-Klarstellungen aus dem Review — (1) „kein Frontmatter-Change"-Widerspruch aufgelöst: Konvention fügt kein neues Feld über §3.3 hinaus hinzu, während das Hinzufügen/Erweitern von `sources`-Einträgen (`resource`/`id`, Relokation/Zielwechsel) ausdrücklich Teil der Konvention ist; (2) Inline-Verweis-Form präzisiert: Fragment = im Rohdokument existierende Stellen-Kennung (Bezeichner-`id` oder Sektionstitel), Concept-eigene `sources`-`id` (`s1`, …) ist NICHT als Fragment zu verwenden; voller `raw/`-Pfad je Beleg, keine Pfad-Elision; die Selbsttest-Formel auf `grep -nE '(raw/|]\(raw/'` erweitert; (3) Kontext-Marker um Direktübernahme-Fall „übernommen aus `<source>` (rohe Quelle)" ergänzt, Selbstreferenz-Muster verboten; (4) Forward-Referenz-Wortlaut an den exakten Token „nicht eigenständig belegt" gebunden; (5) Worked Example (belegte Aussage + Diagramm-Direktübernahme + Diagramm-Quell-Deklaration, BH-13) ergänzt. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 1.7 (2026-08-17, bmad-code-review Story 2.2, Patch-Runde 2):** (1) Selbsttest-Grep-Formel behoben — `grep -nE '(raw/|]\(raw/'` war eine ungültige ERE (ungeschlossenes Klammerpaar, `exit 2`); jetzt `grep -nE '\(raw/'` (das Teilmuster `(raw/` erfasst Plain-Form und Markdown-Linkform gleichermaßen), Pkt.1 und Pkt.4, re-executierbar (AD-17h); (2) Komma-Form `(raw/<datei.md>, <stellen-kennung>)` als zulässige zweite Inline-Form in Pkt.1 formal festgelegt (für Stellen-Kennungen ohne Bezeichner-`id` im Rohdokument, z. B. Sektionstitel `§ 1 Vision`), analog zum Link-Form-Präzedenzfall bis Story 2.3 — Worked Example um Komma-Form-Beispiel ergänzt (D1-Entscheidung, Option 1); (3) Multi-Beleg-Serialisierung in Pkt.1 festgelegt (Semikolon + voller Pfad je Beleg; Komma-Gruppierung mehrerer `#`-Kennungen unter einem Pfad zulässig; bei gemischten Formen voller Pfad je Beleg; keine Pfad-Elision über Beleg-Grenzen); (4) Relokations-Sub-Bullets als **1a/1b** nummeriert (Label „Pkt. 1b" in §5.5-Intro, Pkt.5 und `deferred-work.md` existiert damit); (5) Marker-Muster-Zahl korrigiert: „drei" (zwei Grundmuster + Forward-Referenz-Variante), Pkt.2 und Pkt.4; Forward-Referenz-Beispiel-Zitat auf eindeutigen Sektionstitel `Story 3.1: Inkrementellen Datenfluss implementieren` disambiguiert (raw/epics trägt zwei „Epic 3"-Headings); (6) §8-Normreferenzen um AD-4a, AD-9, AD-13, AD-14, AD-16 (Spine), FR-16 (PRD), A0-3, FR-6/12/14, A0-6/7/11/18 (Epics) ergänzt. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 1.8 (2026-08-17, Story 2.3):** Neue Sektion „Concept-Links" als **§5.6** eingefügt (nach §5.5, vor §6): genau-eine-Form-**Pin** bundle-relativ mit `.md`-Endung (AD-7b, A0-9, FR-10; Rationale Null-Migration der 3 Concept-Links, explizite Datei-Ziele, Standard-Markdown-Tools/AD-8), Geltungsbereich (Concept-Bodies + `wiki/index.md`) mit expliziten Ausnahmen (`raw/`-Provenienz-Verweise §5.5, `../schema/`-Links, `http`-Links, Gleichseit-Anker `#…`), **vier** re-executierbare Selbsttest-Formeln (Bestands-, Form-, Dangling-Check + Kontakt-mit-`raw/`-Unverändert-Check mit deterministischer Baseline-Extraktion aus dem `baseline_commit` via `git show`, AD-17h; rekursiv lauffest für künftige Areas, Story 2.4/2.5), NFR-4-Regel (jede Form-Verletzung → Run-FAIL mit textuell benannter Ursache) und Worked Example. Die „bis Story 2.3"-Klauseln in §5.3 Pkt. 3 und §5.5 Pkt. 1 referenzieren jetzt §5.6; §7-Selbstbegrenzung-Bullet entsprechend umformuliert. Demonstrative Umsetzung: zwei inhaltsbegründete Cross-Links in `wiki/wissensarchitektur-trennung-states.md` (→ `llm-wiki-prinzip.md`, → `knowledge-kompilation-inkrementell.md`; keine erzwungene Gegenseitigkeit, AD-8). Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/` (der Punkt-11-Check akzeptiert bis auf Weiteres beide Schreibweisen — Einschränkung wäre eigene Autorisierung); keine neue §7-Invaliditätsklasse; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 1.9 (2026-08-17, Story 2.3, Step-04-Review Loop 1, Patch-Runde):** §5.6-Formeln geschärft — (1) leere-Ziele-Erfassung (`[^)]*` statt `[^)]+` in Formel 1/2/3), (2) `log.md`-Exklusion in allen vier Formeln (`--exclude=log.md`) + Scan-Scope-Klarstellung in Pkt. 2 (Formeln scannen den `wiki/`-Baum mit Ausnahme von `log.md` — sie zitiert die Formel-Texte selbst), (3) externe-Ziel-Exklusion über `:` statt `http`-Präfix (Formel 2 `grep -vE ':'`; Formel 3 `case *:*`) — `http://`/`https://`/`mailto:`/protocol-less Hostnamen exkludiert, legale `http…`-Dateinamen nicht mehr fälschlich exkludiert, (4) Exit-Code-Bindung `|| true` am Ende des Form-Checks (grep `-c` liefert Exit `1` bei Ausgabe `0` — der gewünschten SUCCESS-Konfiguration), (5) Fragment-Strip im Dangling-Check vor dem Existenztest (`p=${t%%#*}` — `concepts.md#s1` bei existierender Datei liefert keinen falschen `DANGLING`; die Form-Frage bleibt beim Form-Check) und leere Ziele melden `DANGLING: (leeres Ziel)` statt still exkludiert; (6) raw/-Check (Formel 4) auf dynamische Baseline-Extraktion umgestellt (`git ls-tree -r --name-only <baseline_commit> -- wiki/` + `git show` je Datei, `wiki/log.md` gefiltert; einschließende Einzelanführungszeichen, damit `$f` erst in der inneren Shell expandiert) mit erwarteter Zählung **30** (`log.md`-exkludiert) und Voraussetzung „unveränderte `wiki/`-Dateimenge" (bei Datei-Zuwachs in späteren Runs Baseline-Extraktion neu durchführen). Pkt. 4 (NFR-4-Regel) um leere Ziele erweitert; Pkt. 5 (Worked Example) um Negativ-Beispiel (`[Test](ohne-endung)` → Form-Check `1` + `DANGLING: ohne-endung`) und Verweis-Korrektur („Pkt. 3.1" → „Pkt. 3, Formel (1)") ergänzt; §6.6 um §5.6-Referenzzeile (✓ gepinnte Form / ✗ fehlende `.md` → Form-Check > 0, Run-FAIL). Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; kein Standalone (D-3); keine neue §7-Klasse; keine Vertragsänderung.
|
||||
- **Revision 2.0 (2026-08-17, Story 2.3, bmad-code-review, Review-Runde):** §5.6-Pin-Schärfung aus dem Code-Review (Blind-Hunter + Edge-Case-Hunter): (1) **Formel 2 (Form-Check)** um die Exklusions-Stufe `grep -vE '^\.'` erweitert — Ziele mit `./`-Präfix (und damit nicht-root-relative Pfade) werden definiert aus dem Pin ausgenommen, statt still als „interne `.md`-Form" durchzugehen; die erläuternde Exklusions-Aufzählung in Pkt. 2 entsprechend ergänzt (`./`-Präfix-Ziele: nicht root-relativ/keine Bundle-Pfad-Form); (2) **Formel 3 (Dangling-Check)** `case`-Muster um `./*` und `/*` erweitert — `./`-Präfix-Ziele und absolute Wurzel-Pfade werden konsistent exkludiert (Analog zu `../*`), statt `DANGLING: ./foo.md`-Fehlbenennung zu erzeugen. Beide Formeln bleiben deterministisch re-executierbar (AD-17h) und werden in der Spec-Verification byte-identisch gespiegelt (verifiziert: 5/5 Formel-Strings identisch compiler↔spec). Positiv-Kontrolle nach Patch: Form-Check `0` (Exit `0`), Dangling-Check leere Ausgabe, Bestands-Check `8` Links, `raw/`-Baseline `30 ≡ 30`. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; kein Standalone (D-3); keine neue §7-Klasse; keine Vertragsänderung. (Die zugehörigen Defer-Findings — Image-Scope, Multi-Line-, Reference-Style- und Leading-Space-Ziele, künftiges Area-`log.md` — sind in `deferred-work.md` dokumentiert, Story-2.4-Kandidat.)
|
||||
- **Revision 2.1 (2026-08-18, Story 2.4):** Neue Sektion **§5.7 „Deterministische Bereichszuordnung & Concept-Hierarchie"** eingefügt (nach §5.6, vor §6): (1) Routing-Regel textual-deterministisch (`index.md`-Erst-`Link` → Bereich, sonst Root; neue Areas nur konsolidiert; nie Embedding/Vector — AD-7c/A0-10/AD-13), (2) kanonische ID-Normalisierung mit Beispieltabelle `wiki/<area>/index.md` → `<area>` (AD-7a/A0-8), (3) Kollisions-Hold → Verweis auf den fixierten §3.2 (kein neues Prädikat, kein MOVE, A0-10), (4) **file-relatives Link-Auflösungsmodell** (`../`-fähig, eine Form, §5.6-Pin unverändert) inkl. Out-of-Bundle-`..`-Containment, (5) Area-`index.md`-Regel (frontmatterlos, Punkt 10; Area ohne `index.md` → wörtliche Punkt-11-Meldung `FAIL … Punkt 11: Index-Regel verletzt (Area ohne index.md=…)` — **kein** inventiertes `AREA_WITHOUT_INDEX`-Label; §5.7 Pkt. 5), (6) Worked Example Area-Concept. Nachgeführt: §5.1 Pkt. 1 (Ziel-Pfad → §5.7-Verweis, „Area-Zuordnung ist Story 2.4"-Backlog-Klausel aufgelöst), §5.3 Pkt. 3 (Index-Regel area-bewusst: Concept → `index.md` seines Bereichs), §5.6 Pkt. 1/2/3/4/5 (file-relatives Auflösungsmodell; `../`-Exklusion aufgelöst → in-Bundle-Auflösung; **Formel 2** Exklusions-Erläuterung um `../`-Zähl-Freistellung ergänzt; **Formel 3** um Quell-Datei-Spur (`grep -roE` + `datei|ziel`-sed) und **in-Bundle-`..`-Auflösung mit Containment** inkl. `../schema/*`-Exklusion erweitert — Out-of-Bundle-`..`-Escape (`../../README.md`, `../../schema/compiler.md`) wird als `DANGLING` gesperrt, Loop-1-Review-A1-Fix; **Formel 4** neu auf den `baseline_commit` dieser Spezifikation `66451b6…` basiert — nicht den Story-2.3-`7e1f449…`, Loop-1-Review-A2-Fix — mit Basename-Filter `grep -v "log.md$"`), §6.6 (Referenzzeile §5.1/§5.7), §6 Pkt. 2 (Erfolgsbedingung Punkt 11 area-bewusst), §7-Selbstbegrenzung-Bullet → „in §5.7 verankert", §8-Normreferenzen um AD-7c/AD-7d/A0-8/A0-10/A0-13/PRD-§8.2/§8.3 ergänzt. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/`; keine neue §7-Klasse; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 2.2 (2026-08-18, Story 2.4, bmad-code-review Loop 2, 4 Layer; Nutzer-Entscheidungen 1/1/1):** (1) **Formel 3 (Dangling-Check) quellenbasierte `../schema/*`-Exklusion (Decision 2):** `case "$t" in …|../schema/*)` um Quell-Bedingung geschärft — die Exklusion greift nur, wenn die Quell-Datei auf Bundleroot-Ebene liegt (`dirname <quelle>` = `wiki`); aus Area-Quellen läuft einstufiges `../schema/…` durch die bestehende Auflösung + `wiki/*`-Containment + `-f`-Existenztest (nicht existent → `DANGLING: …`, kein stiller Vorbeilass, NFR-4); Negativ-Beispiel 2 um die In-Bundle-Variante `[x](../schema/compiler.md)` aus `wiki/wissensarchitektur/source-material.md` → `DANGLING: ../schema/compiler.md` ergänzt (Sandbox-Nachweis); (2) **Formel 4 (Kontakt-mit-`raw/`) Re-Baseline auf den Run-Kopf (Decision 1):** Extraktions-Commit von `66451b6…` auf `862cf410c624072833cd959da9a2fb26235716f6` (Kopf dieses Zuwachs-Runs, Extraktion = 38) umgestellt — der gepinnte Selbsttest lief auf dem Zuwachs-Baum deterministisch `38 ≠ 30` = Run-FAIL (bekannt-böser Zustand aus Loop-1-A2, nur halb geheilt); Erwartungstext jetzt „Ist ≡ Extraktion aus dem Baseline-Commit des letzten Zuwachs-Runs" (aktuell: Run-Kopf `862cf41`, **38 ≡ 38**); `66451b6`/`30` bleibt als Referenz des Vor-Zuwachs-Zustands dokumentiert; Wieder-Baseline-Klausel für künftige Zuwachs-Runs; (3) **§5.7 Pkt. 1(a) textuelles Treffer-Prädikat + deterministisches Tie-Break (Decision 3):** „inhaltlich deckungsgleichen Eintrag" (Urteil, AD-13-Verstoß) ersetzt — Treffer = Identität des `index.md`-Link-Ziels ≡ kanonischer Name des neuen Themas (Pkt. 2); Mehrfachtreffer → Bundleroot-Links vor Area-Links (Bundleroot-Treffer = Root-Concept-Verweis → Default Root-Ebene gemäß (b)), dann lexicografisch kleinste Area-Pfad-Zeichenfolge; (4) file-relative Pin-Wortwahl nachgeführt — §5.3 Pkt. 3 (Oxymoron „file-relativ bundle-relativ" aufgelöst: „file-relativ, mit `.md`-Endung; §5.7 Pkt. 4"), §6.6-Zelle (bzw. das doppelte Leerzeichen) und §7-Bullet; (5) §7-Scope-Einleitung „auf die Erzeugung neuer Concepts auf Root-Ebene begrenzt" → „Root-Ebene und in Areas gemäß §5.7"; (6) Typos („akte-Baseline" → „aktuelle Baseline", „Kopf dieser Spezifikation" → „Baseline-Commit des letzten Zuwachs-Runs"). Positiv-Kontrolle nach Patch (re-executiert): Formel 2 (Form-Check) `0` (Exit `0`), Formel 3 (Dangling-Check) leere Ausgabe, Formel 4 **38 ≡ 38**. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/` (AD-3); keine neue §7-Klasse; kein Standalone (D-3); keine Vertragsänderung.
|
||||
- **Revision 2.3 (2026-08-18, Story 2.5):** Neue Sektion **§5.8 „Progressive Discovery über `index.md` (Story 2.5)"** eingefügt (nach §5.7, vor §6): (1) **Discovery-Pfad** (Bundleroot `wiki/index.md` → Area-`index.md` frontmatterlos → Area-Concepts in gepinnter §5.6-Form; Root-Concepts direkt aus der Bundleroot — AD-9/FR-11, gewurzelte Erreichbarkeit Root → Area → Concept), (2) **gewurzelte Erreichbarkeit als deterministisches Discovery-Kriterium + re-executierbarer Selbsttest** (`UNREACHABLE AREA: <area>` für unverlinkte Area; `NESTED AREA: <area>` für Zwei-Ebenen-Kandidaten inkl. der Area-ohne-`index.md`-Lücke `wiki/a/b/concept.md`; gekoppelte Meldungen an den Run-Nachweis gemäß §5.6-Pkt.-4-analoger NFR-4-Regel; Instruktions-Selbsttest, **keine** neue §7-Klasse — schließt die Validator-Navigation-Lücke, ohne Validator-Change, AD-3), (3) **konsolidierte Zwei-Ebenen-Kartografie** (respondiert Defer **F-07**, schließt es): Root + eine Area-Ebene; `wiki/a/b/` ist keine zugelassene Anlageform — der Kandidat wird durch den **§5.8-Instruktions-Hold (Zwei-Ebenen, Tiefe ≥ 3)** angehalten (keine Datei, kein Index-Link, Meldung `NESTED AREA: <area>`, Run „teilweise erfolgreich"); §3.2 bleibt der Dateikollision bestehender Concepts vorbehalten (Loopback-1-Renegotiation, Option A); (4) **Suche = Consumer-grep** (`grep -n <term> wiki/` / ripgrep, AD-13 — keine Such-Datenbank, kein Embedding, kein Index-Datei-Format), (5) **Discovery-Demo (optional, kein MOVE)** — Hinweis auf Formel-4-Re-Baseline-Pflicht bei Durchführung. Nachgeführt: **§7** (Story-2.5-Vorbehalt auf „Suche"-Rest gekürzt — Navigation/Area-Indizes jetzt in §5.8 verankert, Suche = Consumer-Thema; die Vorbehalt-Zeile lag in der Baseline `main` bei Z. 253, nach dem §5.8-Einschub bei Z. 285), **§8-Normreferenzen** (AD-9/AD-13 → §5.8, FR-11 → §5.8/§5.7 Pkt. 5, NFR-3 neu, PRD-§4.3-Zeile nachgeführt) + **Revisionslog 2.3**. Keine Änderung an `wiki-compiler.md`/`validator.md`/`raw/` (AD-3); keine neue §7-Klasse; kein Standalone (D-3); keine Vertragsänderung.
|
||||
@@ -0,0 +1,316 @@
|
||||
# Validator-Instruktion — OKF-Schema-Validierung für das Knowledge Bundle (Story 1.4)
|
||||
|
||||
> **Status:** abgeleitet (Story 1.4) — deterministische, agent-unabhängige Validierungs-Instruktion auf Basis des autorisierten Schema-Vertrags.
|
||||
> **Normative Grundlage:** `schema/wiki-compiler.md` (autorisiert, Story 1.3) — insbesondere §1 Geltungsbereich, §2 Bundleroot/Frontmatter, §3 Feldsubset (§3.3–§3.7), §5 `log.md`-Typdefinition, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste struktureller Invalidität, §8 Normreferenzen.
|
||||
> **Validator-Revision:** 9 (Revisionslog in §8)
|
||||
> **Ableitungsdatum:** 2026-08-15
|
||||
> **Letzte Re-Konsistenz:** 2026-08-18 (Revision 9 — Punkt-11-Area-Lesart; Punkt-4-`resolved=`-Token; Innen-Ebenen-Punkt-6-Fixture-Zeile)
|
||||
|
||||
## 0. Zweck & Aufruf
|
||||
|
||||
Diese Datei ist **der einzige Ort der Validierungs-Instruktion** des Projekts. Sie ist **rein textuell** — kein ausführbarer Code, kein Standalone-Programm (D-3). Sie wird von einem Agent/Prozess **mechanisch, deterministisch und ohne LLM-Urteil** befolgt (AD-13, AD-17h, Q-6). Sie bildet die **abschließende** 14-Punkte-Invaliditätsliste des Vertrags (§7) 1:1 als mechanische Prüfschritte ab und legt die von Deferred-Work an Story 1.4 verwiesenen Validator-Entscheidungen deterministisch fest.
|
||||
|
||||
**Aufruf:** Vor jeder Mutation des Bundles führt der Producer/Validator den Run in der folgenden festen Ablaufstruktur aus (deterministische Reihenfolge, §4.4): (1) Prüfumfang bestimmen (§1), (2) Dateien klassifizieren (§2), (3) Voraussetzungen prüfen (§3.2), (4) je Datei die 14 Punkte in Reihenfolge prüfen (§3, Abbruch bei erstem FAIL, §4.4), (5) nach PASS der 14 Punkte die fachlichen Zusatzprüfungen ausführen (§6), (6) Verdikt je Datei ausgeben (§5). Das Ergebnis je geprüfter Datei ist ein maschinenlesbares Verdikt (SUCCESS/FAIL, §5). Bei mindestens einem FAIL gilt der gesamte Run als gescheitert; das Bundle wird nicht mutiert und `raw/` bleibt unangetastet (AD-3, NFR-4).
|
||||
|
||||
**Entscheidungsebenen (kein LLM-Urteil):**
|
||||
|
||||
```text
|
||||
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)
|
||||
```
|
||||
|
||||
## 1. Prüfumfang (Vertrag §1)
|
||||
|
||||
1. Erfasst werden ausschließlich **Markdown-Dateien** (`.md`) innerhalb der Bundleroot `wiki/`:
|
||||
- die Bundleroot `wiki/index.md`,
|
||||
- Area-`index.md`-Dateien (jede `index.md` unterhalb eines Area-Verzeichnisses),
|
||||
- Concept-Dateien (alle übrigen `.md`-Dateien unter `wiki/`),
|
||||
- `wiki/log.md` (reserviertes Protokoll).
|
||||
2. Zusätzlich werden die **`raw/`-Ziellinien** geprüft, auf die `sources`-`resource`-Einträge von Concepts verweisen (Pfad-Ziellinie: §3 Punkt 3/4; Existenzprüfung: §6.1).
|
||||
3. **Nicht validiert** werden als Bundle:
|
||||
- `raw/`, `schema/`, `adapters/` (außerhalb des Bundles, keine Concept-Dateien; Vertrag §1),
|
||||
- der **Inhalt** von Dateien unter `raw/`, `schema/` oder `adapters/` — kein fachlicher oder struktureller Check auf diese Dateien als Bundle-Elemente (nur die `raw/`-Ziellinien-Existenz aus Punkt 2).
|
||||
- Nicht-`.md`-Dateien unter `wiki/` (z. B. `wiki/<area>/logo.png`) — sie sind **keine Bundle-Elemente** und werden ignoriert, weder abgelehnt noch validiert (EC-11). Deterministische Abgrenzung: Prüfumfang ist jede Datei unter `wiki/`, deren Dateiendung exakt `.md` ist (case-sensitive kleingeschrieben).
|
||||
- **Offener Punkt (Defer, Retro F-08):** Die Konvention für Großschreibung (`.MD`) unter `wiki/` ist unbestimmt (Windows-Portabilität, NFR-1/NFR-5). Auf win32 kann ein Tool `foo.MD` erzeugen — würde es als Concept gewertet, fehlte ihm `type`. Vor Epic-2-Concepts entscheiden. Bis dahin gilt die obige case-sensitive Abgrenzung.
|
||||
|
||||
## 2. Klassifikation der `.md`-Dateien unter `wiki/`
|
||||
|
||||
Bevor die Prüfschritte laufen, wird jede erfasste `.md`-Datei deterministisch klassifiziert:
|
||||
|
||||
| Rolle | Bedingung | Frontmatter-Status |
|
||||
|-------|-----------|--------------------|
|
||||
| Bundleroot | `wiki/index.md` | **ausschließlich** `type: bundle` + `okf_version: "0.2"` |
|
||||
| Area-`index.md` | eine `index.md` tiefer als `wiki/` (in einem Area-Verzeichnis) | **kein** Frontmatter |
|
||||
| `log.md` | `wiki/log.md` (reservierter Root-Name) | **kein** Frontmatter |
|
||||
| Concept | jede übrige `.md`-Datei unter `wiki/` (nicht `index.md`, nicht `log.md`) | muss `type` enthalten (§3/§6.1) |
|
||||
|
||||
Reservierte Namen: ausschließlich `index.md` und `log.md` (Vertrag §2, §5, §6). Jede andere `.md`-Datei im Bundle ist ein Concept und unterliegt dem Concept-Prädikat; eine solche Datei ohne Frontmatter bzw. ohne `type` ist **nicht** „kein Concept", sondern strukturell invalide (Vertrag §3.1, §7 Punkt 2).
|
||||
|
||||
## 3. Die 14 strukturellen Invaliditäts-Punkte (Vertrag §7) als mechanische Prüfschritte
|
||||
|
||||
Die folgende Liste bildet die **abschließende** 14-Punkte-Invaliditätsliste des Vertrags (§7) 1:1 ab. Sie fügt **keinen** Eintrag hinzu und streicht **keinen** Eintrag. Jeder Punkt nennt das betroffene Artefakt, den konkreten YAML-/Text-Check und die deterministisch identifizierbare Fehlerursache (NFR-4). Ein Punkt ist verletzt, sobald die angegebene Bedingung auf mindestens eine erfasste Datei zutrifft → Verdikt FAIL (§5).
|
||||
|
||||
Wert-Semantik des YAML-Checks: Frontmatter ist als YAML zu parsen. Wiederholte Frontmatter-Keys (YAML-Duplikat-Keys) sind beim Parsen zu **zählen** (Punkt 13); die YAML-Spezifikation lässt sie mehrdeutig zu, der Vertrag erklärt sie zu struktureller Invalidität. Nicht als YAML parsbares Frontmatter ist ein FAIL — dieser Fall ist bereits über die Prüfschritt-Spalte von Punkt 2 abgedeckt („nicht als YAML parsbar"), ein separater Check ist nicht nötig.
|
||||
|
||||
**Gemeinsame Frontmatter-Erkennung (stripped, Retr. F-05/AI-5):** Alle Checks, die einen Frontmatter-Block `---` am Dateianfang erkennen (Punkte 2, 8, 10), laufen auf dem **gestrippten Dateianfang**: ein eventueller UTF-8-BOM (`U+FEFF`) am Dateianfang sowie etwaige führende Leerzeilen (nur Whitespace-Zeilen) werden vor der Erkennung entfernt. Ein BOM oder führende Leerzeilen vor dem Frontmatter ändern den Status nicht (sonst würde ein Frontmatter der Erkennung entkommen und ein falsches Punkt-2/Punkt-8-FAIL entstehen). Das Stripping dient **ausschließlich** der Frontmatter-Erkennung — es entfernt keinen Inhalt und ändert nichts an YAML-Werten.
|
||||
|
||||
| # | Invaliditäts-Punkt (§7) | Artefakt | Mechanischer Check | Fehlerursache im Verdikt |
|
||||
|---|--------------------------|----------|--------------------|--------------------------|
|
||||
| 1 | Concept ohne `type` oder mit leerem `type` | Concept-Frontmatter | Ist `type` nicht vorhanden ODER kein non-empty String (leerer String, nur Whitespace, oder `type: null` / Zahl / Datumsobjekt)? | `Punkt 1: concept ohne type oder leerer type (NULL|leer|nicht-String)` |
|
||||
| 2 | nicht-reservierte `.md`-Datei im Bundle ohne Frontmatter bzw. ohne `type` | jede nicht-`index.md`/nicht-`log.md` `.md`-Datei unter `wiki/` | Fehlt der Frontmatter-Block `---` (Erkennung auf dem gestrippten Dateianfang, §3-Präambel) ODER ist das Frontmatter nicht als YAML parsbar ODER fehlt `type` (bzw. ist leer)? | `Punkt 2: nicht-reservierte .md-Datei ohne Frontmatter/ohne type` |
|
||||
| 3 | `sources`-`resource` löst auf einen `wiki/`-Concept-Pfad auf | Concept-Frontmatter, je `sources[].resource` | Löst der (bereinigte, §6.2) Pfad relativ zur Workspace-Root auf einen Pfad auf, der **innerhalb** `wiki/` liegt? | `Punkt 3: resource loest auf wiki/-Concept-Pfad (Pfad=<resource>)` |
|
||||
| 4 | `sources`-`resource` landet bei Auflösung außerhalb `raw/` (inkl. `..`-Traversal) oder ist URL-Form; zudem Verstöße der Pfad-Grammatik | Concept-Frontmatter, je `sources[].resource` | Enthält der `resource`-Wert `..`-Path-Segment, führenden `/`, `file://`-Präfix, Backslash/Windows-Trenner, oder einen absoluten/URL-Form-Wert (`http://`, `https://`, etc.) ODER liegt der aufgelöste Pfad außerhalb `raw/`? | `Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (..-Traversal|absolut|URL|Backslash|file://|resolved=<pfad>)` |
|
||||
| 5 | verbotener `status`-Wert | Concept-Frontmatter | Ist `status` gesetzt und **nicht** ∈ {`draft`, `stable`, `deprecated`}? | `Punkt 5: verbotener status-Wert (Wert=<status>)` |
|
||||
| 6 | nicht autorisiertes Frontmatter-Feld oder unautorisierter Key in `sources`/`generated`/`verified`-Eintrag | Concept- & Bundleroot-Frontmatter | Enthält das Frontmatter ein Feld außerhalb des erlaubten Subsets (Concept: `type`/`sources`/`generated`/`verified`/`status`/`stale_after`; Bundleroot: `type`+`okf_version`)? ODER enthält ein `sources`-Eintrag Keys außerhalb {`resource`,`id`,`title`,`author`,`usage_count`,`last_modified`}; ein `generated` Keys außerhalb {`by`,`at`}; ein `verified`-Eintrag Keys außerhalb {`by`,`at`}? **Exemption:** `okf_version` und `type: bundle` sind von der Punkt-6-Subset-Prüfung ausgenommen und werden ausschließlich über Punkt 8/9 geprüft (Entscheidungsnotiz unter dieser Tabelle). Innen-Ebenen: siehe §7.3-Isolations-Notiz (autorisiert, Revision 8). | `Punkt 6: nicht autorisiertes Feld (Key=<key>) bzw. unautorisierter Key in sources/generated/verified` |
|
||||
| 7 | leere/fehlende `by`-Angabe in `generated` oder `verified` | Concept-Frontmatter | Ist `generated.by` nicht gesetzt ODER leer ODER reiner Whitespace? Gleiches je `verified[].by`? | `Punkt 7: leere/fehlende by-Angabe in generated/verified` |
|
||||
| 8 | Bundleroot `wiki/index.md` ohne `type: bundle`/`okf_version: "0.2"` oder abweichender `okf_version`-Wert | Bundleroot `wiki/index.md` | Fehlt der Frontmatter-Block `---` (Erkennung auf dem gestrippten Dateianfang, §3-Präambel) ODER fehlt `type: bundle` (exakt dieser Wert) ODER fehlt `okf_version: "0.2"` (nur der Stringliteral `0.2` zulässig, z. B. NIE `0.3`)? | `Punkt 8: Bundleroot ohne type: bundle/okf_version \"0.2\" oder falscher okf_version-Wert` |
|
||||
| 9 | `okf_version: "0.2"` oder `type: bundle` außerhalb der Bundleroot | jede `.md`-Datei außer `wiki/index.md` im Bundle (Area-`index.md`, `log.md`, Concepts) | Kommt `okf_version: "0.2"` (§2-Wert) oder `type: bundle` **irgendwo im Dateiinhalt** einer dieser Dateien vor (nicht nur im Frontmatter)? Maßgeblich ist der Vertragswortlaut „darf … in irgendeiner anderen Bundle-Datei vorkommen" (§2/§7 Punkt 9). — Entscheidungsnotiz zu Punkt 6/9 siehe unter dieser Tabelle. | `Punkt 9: okf_version/type: bundle ausserhalb der Bundleroot (Datei=<pfad>)` |
|
||||
| 10 | Frontmatter in einer Area-`index.md` oder `log.md` | Area-`index.md`, `wiki/log.md` | Beginnt die Datei — auf dem gestrippten Dateianfang (BOM `U+FEFF` + führende Leerzeilen, gemeinsame Definition §3-Präambel) — mit einem YAML-Frontmatter-Block `---`? Ein BOM bzw. führende Leerzeilen vor dem Frontmatter ändern den Status nicht (sonst würde ein Frontmatter der Erkennung entkommen). | `Punkt 10: Frontmatter in Area-index.md/log.md (Datei=<pfad>)` |
|
||||
| 11 | Verletzung der Index-Regel | `wiki/`-Struktur | Hat ein Area-Verzeichnis (jedes Verzeichnis unter `wiki/` mit Inhalt) keine `index.md`? ODER ist ein Concept nicht in der `index.md` seines nächsten Vorfahren verlinkt — ein Concept ist verlinkt, wenn seine Identität (relativer OKF-Dateipfad ohne `.md`) in der `index.md` des nächsten Vorfahren (Area-`index.md`; für Root-Concepts die Bundleroot `wiki/index.md`) als relativer Bundle-Pfad referenziert ist, **mit oder ohne `.md`-Endung** (eine genau-eine-Form-Festlegung ist Story 2.3 und wird hier nicht vorgegeben). **Area-Lesart (autorisiert, Revision 9):** Für ein Area-Concept genügt die **file-relative** Referenz in der Area-`index.md` des nächsten Vorfahren — identitätsstiftend ist das Pärchen (Area-Präfix = **bundle-relativer Verzeichnispfad** der Area-`index.md` + Link-Ziel), eine textuelle Nennung der Bundle-Identität in der Area-`index.md` ist dafür nicht erforderlich. Der Area-Präfix ist der Verzeichnispfad der Area-`index.md` relativ zur Bundleroot (z. B. für `wiki/wissensarchitektur/index.md` → `wissensarchitektur/`), nicht nur der Leaf-Verzeichnisname — robust auch für Area-Tiefe ≥ 2 (die Zwei-Ebenen-Beschränkung ist Gegenstand der Compiler-Instruktion §5.8; der Validator delegiert die Struktur-Zulässigkeit dorthin und bildet die Identität rein aus Area-Präfix + Link-Ziel). **Normalisierung des Link-Ziels vor der Identitätsbildung:** Ein führendes `.`/`./`-Segment wird gestrippt; `..`-Segmente gehören nicht zur gepinnten Ein-Ebenen-Form (file-relative Referenzen in der Area-`index.md` sind Ein-Ebenen-Links auf Concepts desselben Verzeichnisses; `..`-Aufwärts-Ziele sind keine Area-Concept-Referenzen im Sinne dieser Regel). **Identität ohne `.md`-Endung (AD-7a):** Die `.md`-Endung des Link-Ziels wird für die Identitätsbildung **abgestreift** — das Beispiel `source-material` (aus `](source-material.md)`) ergibt mit dem Area-Präfix `wissensarchitektur/` eindeutig die Bundle-Identität `wissensarchitektur/source-material`. Root-Concepts bleiben wie bisher in der Bundleroot referenziert (mit oder ohne `.md`-Endung). „Neues Concept" ist deterministisch: jede im Bundle vorhandene Concept-Datei, deren Identität in ihrer zuständigen `index.md` fehlt — der Validator prüft den Zustand, nicht ein Git-Diff. | `Punkt 11: Index-Regel verletzt (Area ohne index.md=<area> | Concept nicht verlinkt=<concept>)` |
|
||||
| 12 | `sources`/`verified` in nicht erlaubter Form; `generated` in Listen- statt Map-Form; `sources`-Eintrag ohne Pflichtangabe `resource` | Concept-Frontmatter | Ist `sources` gesetzt und **nicht** YAML-Liste? Ist ein `sources`-Eintrag keine Map (z. B. Skalar)? Ist ein `sources`-Eintrag eine Map **ohne** `resource` oder mit leerem `resource` (Vertrag §3.3: `resource` ist die einzige Pflichtangabe je Eintrag)? Ist `verified` gesetzt und **weder** Liste **noch** eine einzelne Map? Ist ein `verified`-Eintrag keine Map? Ist `generated` gesetzt und **nicht** eine Map (insbesondere Liste)? | `Punkt 12: sources/verified/generated in nicht erlaubter Form` |
|
||||
| 13 | doppelter Frontmatter-Key | jede Datei mit Frontmatter (Concept, Bundleroot) | Kommt derselbe Key auf oberster Frontmatter-Ebene mehrfach vor (z. B. doppeltes `type`, doppeltes `okf_version`, doppeltes `sources`)? | `Punkt 13: doppelter Frontmatter-Key (Key=<key>)` |
|
||||
| 14 | fehlerhafte Wert-Formate | Concept-Frontmatter | `stale_after`/`last_modified` ≠ `YYYY-MM-DD` (exakt 10 Zeichen, korrekte Struktur + reale Kalenderdaten, §6.3)? `at` (in `generated`/`verified`) ≠ ISO-8601-Datetime (Normalform, §4.3; Kalender-Validität §6.3)? `usage_count` kein **YAML-Integer** (Ganzzahl-Typ, nicht Zahl allgemein — `usage_count: 3.0` als Float ist ein FAIL) und keine Ganzzahl ≥ 0? `type` kein nicht-leerer String (siehe auch Punkt 1)? | `Punkt 14: fehlerhaftes Wert-Format (Feld=<feld>, Wert=<wert>)` |
|
||||
|
||||
### 3.1 Erweiterungs-/Abschluss-Regel
|
||||
|
||||
Diese 14 Punkte sind **abschließend** (Vertrag §7 „abschließende Liste"). Die Instruktion führt **keine neue §7-Invaliditätsklasse** ein; die fachlichen Voraussetzungs- (§3.2, V-1/V-2) und Zusatzprüfungen (§6, EC-*) sind separat geführte, ebenfalls deterministische Prüfklassen und verlassen die Abschluss-Eigenschaft des §7-Katalogs nicht. Nicht in der Liste genannte Auffälligkeiten sind entweder (a) zulässig und semantisch gleichbedeutend mit Absenz (fehlende optionale Felder, leere Listen, §4.1), (b) Warnungen ohne Invalidität (`stale_after`-Veraltung, §6.4; Existenzprüfung als separat protokollierte fachliche Prüfung, §6.1) oder (c) keine Bundle-Elemente (nicht-`.md`-Dateien, §1). Jede beabsichtigte Erweiterung der Invaliditätsdefinition erfordert die Autorisierung bzw. das Story-Verfahren — sie darf von keinem Producer oder Validator stillschweigend vorgenommen werden.
|
||||
|
||||
**Entscheidungsnotiz zu Punkt 6/9:** `okf_version` und `type: bundle` sind als Bundle-Root-Felder (§2) von der Punkt-6-Subset-Prüfung ausgenommen; ihr Vorkommen wird ausschließlich über Punkt 8 (Bundleroot-Bedingungen) und Punkt 9 (Verbot außerhalb der Bundleroot) geprüft. Damit feuert niemals Punkt 6 vor Punkt 9 — das Punkt-9-Fixture bleibt deterministisch (kein Vorab-FAIL durch die Subset-Prüfung).
|
||||
|
||||
### 3.2 Bundleroot- und Reserviert-Namen-Voraussetzungen (V-1/V-2; Vertrag §2/§5)
|
||||
|
||||
Diese Voraussetzungen sind strukturelle Norm-Pflichten, die der Validator **vor** den 14 Einzel-Punkten prüft. Sie werden als **fachliche Voraussetzungs-Prüfungen V-1/V-2** geführt (Namensraum konsistent zu den §6-Fachprüfungen EC-*/V-*). Sie sind ausdrücklich **keine neue §7-Invaliditätsklasse**: Sie bedingen die Anwendbarkeit der 14 Punkte (Fehlen der Bundleroot macht Punkt 8 gegenstandslos; ein `log.md` an falscher Position ist eine Reserviert-Namen-Verletzung nach §5) und sind als Voraussetzungsprüfungen dokumentiert. Ein FAIL hier ist — wie bei den §6-Fachprüfungen — ein Run-FAIL, trägt aber **keine §7-Punkt-Nummer**.
|
||||
|
||||
- **V-1 (fehlende Bundleroot):** Existiert `wiki/index.md` nicht, ist der Run strukturell FAIL (Vorausbedingung zu Punkt 8): `FAIL (Voraussetzung) Bundleroot fehlt: wiki/index.md existiert nicht (V-1, Vertrag §2, Vorausbedingung zu Punkt 8)`.
|
||||
- **V-2 (reservierter Name außerhalb der Bundleroot):** Existiert eine Datei `log.md` an einer anderen Stelle als der Bundleroot (z. B. `wiki/<area>/log.md`), ist sie strukturell invalide (reservierter Name, nur Bundleroot; Vertrag §5): `FAIL <pfad> log.md an unzulässiger Position (V-2, reservierter Name, nur Bundleroot, Vertrag §5)`.
|
||||
- Diese Voraussetzungsprüfungen laufen in der Ausführungsreihenfolge bei Schritt (3) — nach der Klassifikation (§2), vor den 14 Punkten je Datei (§3, Schritt (4); vgl. §4.4). Fixtures: §7.1 (8a, 10a) bzw. §7.3 (V-1/V-2).
|
||||
|
||||
<details>
|
||||
<summary>Warum V-1/V-2 (Retrospective F-03, AI-3)?</summary>
|
||||
|
||||
Die Retrospective (F-03) bemängelte, dass §3.2 de-facto eigenständige FAIL-Klassen einführt, aber weder im §7-Fixture-Schema noch in der §5-Verdikt-Grammatik als solche erkennbar ist — sie trugen das Label `FAIL (Struktur) …` außerhalb der §5-Grammatik, während §3.1/§5.1 „abschließende Liste, keine eigene Invaliditätsklasse" behaupten. Das Label-Schema ist hiermit vereinheitlicht: Die Voraussetzungsprüfungen heißen **V-1** (fehlende Bundleroot) und **V-2** (`log.md` an falscher Position), tragen in der Verdikt-Zeile das Präfix `FAIL (Voraussetzung)` und sind in §7.3 als eigene Fixtures belegt. Damit ist §3.2 dokumentarisch als fachliche (nicht §7-)Prüfklasse geführt und mechanisch nachprüfbar.
|
||||
|
||||
</details>
|
||||
|
||||
## 4. Normalisierung & Toleranz (deterministische Festlegungen)
|
||||
|
||||
Diese Abschnitte legen die von Deferred-Work an Story 1.4 verwiesenen Entscheidungen fest. Sie wirken **vor** den 14 Prüfschritten und sind Teil der deterministischen Ausführung (kein Interpretationsspielraum).
|
||||
|
||||
### 4.1 Listen- vs. Absenz-Normalisierung (F2)
|
||||
|
||||
- `sources: []` und `verified: []` sind zulässig und **semantisch gleichbedeutend mit Absenz** (Vertrag §3.2, §3.3, §3.5). Sie sind niemals invalide.
|
||||
- Fehlende optionale Felder (`sources`/`generated`/`verified`/`status`/`stale_after` nicht vorhanden) sind niemals invalide (A0-2/AD-1b).
|
||||
- Für die Ausgabe-/Diff-Basis gilt eine **feste Reihenfolge** (deterministische Normalform): Frontmatter-Keys werden in der Reihenfolge `type`, `sources`, `generated`, `verified`, `status`, `stale_after` betrachtet; innerhalb von `sources`/`verified`-Listen bleibt die dokumentierte Reihenfolge erhalten.
|
||||
|
||||
### 4.2 `verified`-Singleton-Coercing (Vertrag §3.5)
|
||||
|
||||
- Eine einzelne Map `verified: { by: ..., at: ... }` **MUSS als 1-Element-Liste** gelesen werden und wird **nicht abgelehnt** (Vertrag §3.5). Prüfschritt 12 berücksichtigt diese Toleranz: Die Map-Form eines einzelnen `verified`-Eintrags ist gültig.
|
||||
- `generated` kennt diese Toleranz **nicht**: `generated` ist, falls gesetzt, ausschließlich als Map zulässig; eine Liste ist strukturell invalide (Punkt 12; Vertrag §3.4).
|
||||
|
||||
### 4.3 ISO-8601-Normalform für `at` (BH-14, Vertrag §3.4/§3.5)
|
||||
|
||||
Für `at` (in `generated`/`verified`) gilt die folgende ISO-8601-Normalform (deterministisch, ohne LLM-Urteil):
|
||||
|
||||
- Akzeptiert: `YYYY-MM-DDTHH:MM:SS` mit einer der Offset-Formen `Z` (UTC), `±HHMM` (4-stellig ohne Doppelpunkt) **oder** `±HH:MM` (mit Doppelpunkt). Beide Offset-Formen sind gültige ISO-8601-Darstellungen (RFC 3339) und werden akzeptiert (Vertrag §7 Punkt 14 fordert nur „ISO-8601-Datetime" — eine Ablehnung von `±HH:MM` wäre eine unautorisierte Verschärfung). Für die Normalisierung gilt: Das Suffix wird normiert; die intern einheitliche Repräsentation ist die UTC-Form.
|
||||
- Eine reine Datumsangabe `YYYY-MM-DD` (ohne Zeit- und Offset-Anteil) ist **kein ISO-8601-Datetime** und damit keine gültige `at`-Form — sie erzeugt **FAIL nach Punkt 14** (Vertrag §3.4/§3.5: „`at` … MUSS ein ISO-8601-Datetime sein"; §7 Punkt 14: „`at` ungleich ISO-8601-Datetime"). Es gibt keine Normalform, die ein reines Datum in ein Datetime überführt — die Toleranz aus Revision 2 ist hiermit zurückgenommen.
|
||||
- **FAIL nach Punkt 14** sind ausschließlich Formen, die **kein** ISO-8601-Datetime sind (fehlende Trennzeichen, keine Zeit nach `T`, `HH:MM` ohne Sekunden, eine reine Datumsangabe `YYYY-MM-DD` ohne Zeit-/Offset-Anteil, ungültiger Monat/Tag/Stunde/Minute/Sekunde, ungültiger Offset).
|
||||
- Die Kalender-Validität von Datumsteilen folgt §6.3 (EC-3).
|
||||
|
||||
### 4.4 Rangfolge der Prüfschritte (deterministische Ausführungs-Reihenfolge)
|
||||
|
||||
Der Run folgt einer festen Ausführungs-Reihenfolge (vgl. §0 Aufruf):
|
||||
|
||||
1. **Klassifikation** — alle erfassten `.md`-Dateien werden gemäß §2 klassifiziert (Bundleroot / Area-`index.md` / `log.md` / Concept).
|
||||
2. **Voraussetzungsprüfungen (V-1/V-2)** — die Bundleroot- und Reserviert-Namen-Voraussetzungen aus §3.2 werden geprüft (V-1: fehlende Bundleroot; V-2: `log.md` an unzulässiger Position).
|
||||
3. **Je Datei die 14 Punkte in Reihenfolge** (§3): Die Datei wird Punkt für Punkt geprüft. Sobald **ein** Punkt FAIL erzeugt, wird der FAIL für diese Datei einmal protokolliert (erste verletzte Bedingung in Punkt-Reihenfolge) und die übrigen Punkte werden für diese Datei nicht mehr ausgewertet (deterministische Abbruch-Regel — vermeidet mehrdeutige Mehrfach-Verdikte). Es wird stets die **erste** verletzte Bedingung als textuelle Fehlerursache im Verdikt genannt (NFR-4).
|
||||
4. **Nach PASS der 14 Punkte die §6-Prüfungen** je Datei: EC-1-Existenz je `resource`, EC-3-Kalender-Validität der Datumsfelder, EC-4/6.4-`stale_after`-WARN.
|
||||
|
||||
Mehrere fehlende `resource`-Existenz-Fehler **einer** Datei (EC-1) werden zu **einer** FAIL-Zeile aggregiert — alle fehlenden Pfade in der im Frontmatter dokumentierten Reihenfolge (Beispiel: `FAIL wiki/x.md Fachliche Prüfung EC-1: resource existiert nicht (Pfad=raw/a.md, raw/b.md)`). Aggregation gilt nur innerhalb einer Datei: jede betroffene Datei erhält ihre eigene FAIL-Zeile.
|
||||
|
||||
Das Gesamtergebnis des Runs ist FAIL, sobald irgendeine Datei FAIL ist (§5).
|
||||
|
||||
### 4.5 `log.md`-Feingranularität (F17)
|
||||
|
||||
- Ein **leeres** `wiki/log.md` ist gültig (kein Frontmatter, keine Einträge) — keine Invalidität.
|
||||
- `log.md` trägt **kein Frontmatter** (Punkt 10; Vertrag §5).
|
||||
- `log.md`-Inhalt (Eintragsklassifikation, datumsgruppierte Liste) wird in v1 **nicht** validiert: §5 legt Format und Beispiel fest, aber keine strukturell prüfbare Eintrags-Grammatik; eine spätere Story (AD-16/Epic 4) kann eine Eintrags-Validierung ergänzen. Es ist keine neue Invaliditätsklasse („nicht in der Liste" gilt als nicht verletzt, §3.1).
|
||||
|
||||
## 5. Verdikt-Format (maschinenlesbar)
|
||||
|
||||
Pro geprüfte Datei wird **genau ein** Verdikt-Verb ausgegeben, gefolgt von Datei-Pfad und textueller Begründung. Das Format ist maschinenlesbar (deterministische Grammatik) und zugleich für Menschen lesbar (NFR-4). Ein Verdikt-Verb ist **ausschließlich** `SUCCESS` oder `FAIL`; `WARN` (§6.4) ist **kein** Verdikt-Verb, sondern ein ergänzender Berichtskanal und ersetzt das Verdikt nicht — eine Datei kann „SUCCESS + WARN" tragen.
|
||||
|
||||
```text
|
||||
SUCCESS <relative-pfad> <optionale Begründung>
|
||||
FAIL <relative-pfad> <Fehlerursache: Punkt-Nr. + Determinismus-Beschreibung>
|
||||
```
|
||||
|
||||
- `<relative-pfad>`: Pfad relativ zur Workspace-Root (z. B. `wiki/index.md`, `wiki/<area>/<concept>.md`), `/`-getrennt.
|
||||
- SUCCESS: alle zutreffenden Prüfschritte bestanden; keine Begründung erforderlich (kann aber eine Normalform-Notiz zu §4 enthalten, z. B. `verified`-Singleton-Coercing).
|
||||
- FAIL: genau die textuelle Fehlerursache gemäß §3-Tabelle (Punkt-Nummer + deterministischer Grund + relevanter Wert/Pfad), **oder** — für fachliche Prüf-FAILs (§3.2 V-1/V-2 und §6 EC-*) — das jeweilige Fachprüf-Präfix `FAIL (Voraussetzung)` (V-1/V-2) bzw. `Fachliche Prüfung EC-1` o. ä. (§6) statt einer Punkt-Nummer (§4.4). Fachliche Prüf-FAILs tragen keine §7-Punkt-Nummer, weil sie keine der 14 §7-Punkte sind (§3.2, §6.1). Die Ursache ist darüber hinaus Ausdruck der abgeschlossenen Normalisierung (§4).
|
||||
- **Run-Ergebnis:** Das Gesamtergebnis ist `FAIL`, sobald mindestens eine Datei FAIL ist; dann gilt der Run als gescheitert, es werden keine Mutationen durchgeführt und `raw/` bleibt unangetastet (AD-3). Sind alle Dateien SUCCESS (inkl. keiner Existenz-Prüf-FAILs, §6.1), ist das Gesamtergebnis `SUCCESS`.
|
||||
- Nicht-`.md`-Dateien unter `wiki/` erzeugen **kein** Verdikt (sie werden nicht geprüft, §1).
|
||||
|
||||
### 5.1 Selbstbegrenzung
|
||||
|
||||
- Die Instruktion validiert ausschließlich Bundle-Elemente gemäß §1; die Inhalte von `raw/`, `schema/` und `adapters/` werden **nicht** als Bundle validiert.
|
||||
- Die **abschließende 14-Punkte-Liste (§7)** erhält durch die Instruktion **keine neuen Einträge** (§3.1). Die fachlichen Voraussetzungs-/Zusatzprüfungen (§3.2 V-1/V-2, §6 EC-1/EC-3/EC-11) sind **keine §7-Punkte**, sondern separat geführte fachliche Prüfklassen — ein FAIL dort ist ein Run-FAIL, ohne eine der 14 Punkte zu sein. Diese Abgrenzung ist dokumentarisch (V-1/V-2-Label, §7.3-Fixtures) und ändert nichts an der Abschluss-Eigenschaft des §7-Katalogs.
|
||||
- Es wird **nichts geschrieben**: der Validator mutiert weder Bundle noch `raw/` noch sonstige Dateien; er protokolliert sein Ausführungs-Protokoll nur als Bericht (kein Schreibzugriff auf Dateien außerhalb des Berichtskanals).
|
||||
|
||||
## 6. Fachliche Zusatzprüfungen (Deferred-Work, separat protokolliert)
|
||||
|
||||
Die folgenden Prüfungen sind **fachliche** Prüfungen (keine §7-Invaliditäts-Punkte). Sie werden deterministisch ausgeführt und separat protokolliert — ein FAIL hier ist trotzdem ein Run-FAIL (das Bundle darf nicht mit fehlender Evidenz oder Phantom-Daten laufen), wird aber **nicht** als „Punkt 1–14"-Verstoß gezählt (§3.1; Vertrag §8 „Existenz-Prüfung als Validator-Verhalten der Story 1.4").
|
||||
|
||||
### 6.1 Existenzprüfung der `raw/`-Resource (EC-1)
|
||||
|
||||
- Für jeden `sources`-`resource`-Eintrag eines Concepts: Der gemäß §6.2 bereinigte und relativ zur Workspace-Root aufgelöste Pfad **MUSS zum Validierungszeitpunkt als Datei existieren** — ausdrücklich als **Datei, nicht als Verzeichnis**. Existiert er nicht oder löst er auf ein existierendes Verzeichnis auf, ist das Bundle **fachlich invalide → Run-FAIL** (ein Verzeichnis ist kein gültiger Evidenzpfad). Fixtures: §7.3 (EC-1 Positiv/Negativ/Aggregation).
|
||||
- Verdikt ohne Punkt-Nummer: `FAIL <concept-pfad> Fachliche Prüfung EC-1: resource existiert nicht (Pfad=<resource>)`.
|
||||
- Mehrere fehlende Resources **einer** Datei werden zu **einer** FAIL-Zeile aggregiert (alle fehlenden Pfade in der dokumentierten Reihenfolge; §4.4, Schritt 4).
|
||||
- Diese Prüfung ist eine **fachliche** Invalidität: Sie ist keine der 14 §7-Punkte und lässt die abschließende Liste unberührt (der Punkt wird separat protokolliert, nicht als Punkt 1–14 gezählt).
|
||||
|
||||
### 6.2 Pfad-Auflösung & -Bereinigung
|
||||
|
||||
`resource` ist ein `/`-getrennter relativer Workspace-Pfad zur **Workspace-Root** (oberste Ebene des Git-Arbeitsverzeichnisses). Deterministische Bereinigung/Auflösung — **Vorrangsregel:** Die Punkt-4-Grammatikprüfung (Rejektion von `..`, führendem `/`, Backslash, `file://`, URL) läuft **vor** der Punkt-3-Auflösungsprüfung. Ein `resource` mit `..`, dessen bereinigtes Ziel zufällig in `wiki/` läge, wird daher als **Punkt 4 (Grammatik)** abgelehnt, nicht als Punkt 3 — die Punktnummer ist je Input deterministisch (AD-13):
|
||||
|
||||
1. Der Wert wird als relativer Pfad interpretiert. Führendes `/` ist unzulässig (Punkt 4).
|
||||
2. Der Pfad wird als `/`-Segmentfolge behandelt. Ein Segment `..` ist unzulässig (Punkt 4) — unabhängig vom Auflösungsziel. Segment `.` wird normalisiert (entfernt).
|
||||
3. Backslash `\` und Windows-Trenner sind unzulässig (Punkt 4).
|
||||
4. Ein `file://`-Präfix oder eine URL-Form (`http://`, `https://`, andere Scheme-Prefixe) sind unzulässig (Punkt 4).
|
||||
5. Der bereinigte Pfad muss auf einen Pfad **innerhalb** `raw/` auflösen (Präfix `raw/` in der aufgelösten Form). Andernfalls Punkt 4.
|
||||
6. Der aufgelöste Pfad darf **nicht** auf einen Pfad innerhalb `wiki/` auflösen (Punkt 3).
|
||||
|
||||
**Semantik des `resolved=<pfad>`-Tokens (Autorisations-Runde, Revision 9):** Das optionale `resolved=`-Suffix der Punkt-4-Fehlerursache (§3 Punkt 4, Vorlage `…|file://|resolved=<pfad>`) wird nur dann ergänzt, wenn die Ablehnung durch die **aufgelöste Lage** des Pfads erfolgt (Schritt 5: außerhalb `raw/`), **nicht** durch einen der Grammatik-Schritte 1–4 (`..`-Segment, führendes `/`, Backslash/Windows-Trenner, `file://`/URL). Der Wert ist der aufgelöste, workspace-relative Pfad des `resource`-Werts (Beispiel Fixture 4a: `resource: README.md` an der Workspace-Root → `resolved=README.md`). Erfolgt die Ablehnung über einen der Grammatik-Schritte 1–4, bleibt der Katalog auf die entsprechenden Token beschränkt und trägt **kein** `resolved=`-Suffix (die Punktnummer ist je Input deterministisch, §6.2 Vorrangsregel). Konsistenz mit §5-Verdikt-Grammatik: Das `resolved=`-Token ist Bestandteil der textuellen Fehlerursache („Punkt-Nummer + deterministischer Grund + relevanter Wert/Pfad", §5 FAIL) — es ersetzt weder Verdikt-Verb noch Pfad und erzeugt keine eigene Prüfklasse.
|
||||
|
||||
### 6.3 Kalender-Validität der Datumsfelder (EC-3)
|
||||
|
||||
Für alle `YYYY-MM-DD`-Felder (`stale_after`, `sources[].last_modified`) gilt:
|
||||
- Exakt 10 Zeichen, Struktur `JJJJ-MM-TT`, mit `-`-Trennung.
|
||||
- Die Kalenderdaten müssen real existieren: gültige Monate 01–12, gültige Tage je Monat (Schaltjahrregel: Februar 29 nur in durch 4 teilbaren Jahren, außer Jahrhundertjahre, die nicht durch 400 teilbar sind). `2026-02-31` ist **invalide** (Punkt 14).
|
||||
- Für Datumsteile in `at` (zeitliche ISO-8601-Form) gilt dieselbe Kalender-Validität (Monat/Tag/Stunde/Minute/Sekunde real existierend). Fixtures: §7.3 (EC-3 Positiv/Negativ).
|
||||
|
||||
### 6.4 Veraltungs-Prüfung `stale_after` (BH-8/F18) — Warnung, keine Invalidität
|
||||
|
||||
- Ist `stale_after` gesetzt und gilt `today >= stale_after` (Vergleich in **UTC**), so wird eine **Warnung** ausgegeben: `WARN <concept-pfad> stale_after überschritten (Datum=<stale_after>, today=<today-UTC>)`. `WARN` ist ein ergänzender Berichtskanal, **kein** Verdikt-Verb (§5): Das Verdikt der Datei bleibt `SUCCESS`/`FAIL` unverändert. Fixtures: §7.3 (WARN-Muster).
|
||||
- Ein veraltetes Concept ist **kein** struktureller Fehler und **kein** Run-FAIL (F18/BH-8; Vertrag §7 zählt die Veraltung nicht auf). Lebenszyklus-Konsequenzen der Veraltung (Nutzungssperre als `sources`-Ziel o. ä.) sind eine spätere Story (BH-8 → Epic 3) und werden hier **nicht** validiert.
|
||||
- **Offener Punkt (Defer, Retro F-06):** Die Ableitung von `today` für den Vergleich (§6.4/§3.7 „Tagesdatum `today`") ist noch nicht deterministisch hart (UTC-Kalendertag vs. lokaler Tag). Wird vor Epic 3 (Lifecycle-Konsequenz) entschieden; bis dahin gilt: `today` = Kalenderdatum des aktuellen UTC-Zeitpunkts.
|
||||
- `stale_after` ohne Datumsproblem (nur Veraltung) lässt das Verdikt der Datei unverändert (SUCCESS bleibt SUCCESS; nur Warnung).
|
||||
|
||||
### 6.5 `non-md`-Konvention (EC-11)
|
||||
|
||||
Nicht-`.md`-Dateien unter `wiki/` (z. B. `wiki/<area>/logo.png`) werden **ignoriert** — kein Verdikt, keine Ablehnung, keine Konvention-Erfindung über den Vertrag hinaus (§1 Punkt 3, §3.1c). Fixtures: §7.3 (EC-11).
|
||||
|
||||
## 7. Referenz-Fixtures (Negativ-/Positiv-Beispiele)
|
||||
|
||||
Die folgenden Tabellen belegen die 1:1-Abbildung der 14 Punkte (§7.1/§7.2) **sowie** die fachlichen Zusatzprüfungen §6 (§7.3) und machen jede mechanische Bedingung reproduzierbar nachprüfbar (AD-17h). „⇒" gibt das erwartete Verdikt an; die Fehlerursache ist exakt die aus §3 bzw. §6.
|
||||
|
||||
### 7.1 Negativ-Fixtures — je Punkt genau ein FAIL-Beispiel (Input → erwartetes Verdikt)
|
||||
|
||||
> **Isolations-Notiz:** Jede Negativ-Fixture wird gegen ein sonst-valides, isoliertes Sample geprüft (nur die eine Datei/Struktur, alle übrigen Punkte passieren). So ist gewährleistet, dass jede Fixture genau ihren Punkt auslöst und kein Vorab-FAIL durch andere Punkte entsteht (kein Nachbarschafts-Effekt).
|
||||
|
||||
| # | Fixture (Input) | Erwartetes Verdikt (FAIL mit Ursache) |
|
||||
|---|-----------------|----------------------------------------|
|
||||
| 1 | Concept `x.md` mit `type:` (leer) | `FAIL wiki/x.md Punkt 1: concept ohne type oder leerer type (NULL|leer|nicht-String)` |
|
||||
| 2 | `.md` unter `wiki/` ohne `---`-Frontmatter | `FAIL wiki/x.md Punkt 2: nicht-reservierte .md-Datei ohne Frontmatter/ohne type` |
|
||||
| 3 | `sources: [{resource: wiki/foo.md}]` | `FAIL wiki/x.md Punkt 3: resource loest auf wiki/-Concept-Pfad (Pfad=wiki/foo.md)` |
|
||||
| 4 | `sources: [{resource: ../outside.md}]` | `FAIL wiki/x.md Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (..-Traversal\|absolut\|URL\|Backslash\|file://\|resolved=<pfad>)` |
|
||||
| 4a | `sources: [{resource: README.md}]` (existiert an der Workspace-Root, ausserhalb `raw/`; Kein `..`/URL/Backslash — Punkt 4 durch aufgelöste Lage) | `FAIL wiki/x.md Punkt 4: resource ausserhalb raw/ oder unzulaessiger Pfad (resolved=README.md)` |
|
||||
| 5 | `status: published` | `FAIL wiki/x.md Punkt 5: verbotener status-Wert (Wert=published)` |
|
||||
| 6 | Concept mit `foo: bar` (nicht autorisiert) | `FAIL wiki/x.md Punkt 6: nicht autorisiertes Feld (Key=foo)` |
|
||||
| 7 | `generated: {at: 2026-08-15T10:00:00Z}` (ohne `by`) | `FAIL wiki/x.md Punkt 7: leere/fehlende by-Angabe in generated/verified` |
|
||||
| 8 | `wiki/index.md` ohne `okf_version` | `FAIL wiki/index.md Punkt 8: Bundleroot ohne type: bundle/okf_version \"0.2\" oder falscher okf_version-Wert` |
|
||||
| 8a | `wiki/index.md` existiert nicht (Bundle ohne Bundleroot) | `FAIL (Voraussetzung) Bundleroot fehlt: wiki/index.md existiert nicht (V-1, Vertrag §2, Vorausbedingung zu Punkt 8)` |
|
||||
| 9 | Concept mit `okf_version: "0.2"` | `FAIL wiki/x.md Punkt 9: okf_version/type: bundle ausserhalb der Bundleroot (Datei=wiki/x.md)` |
|
||||
| 10 | `wiki/log.md` beginnt mit `---` | `FAIL wiki/log.md Punkt 10: Frontmatter in Area-index.md/log.md (Datei=wiki/log.md)` |
|
||||
| 10a | `wiki/<area>/log.md` existiert (reservierter Name außerhalb der Bundleroot) | `FAIL wiki/<area>/log.md log.md an unzulässiger Position (V-2, reservierter Name, nur Bundleroot, Vertrag §5)` |
|
||||
| 11 | Area `wiki/foo/` ohne `index.md` | `FAIL wiki/foo/ Punkt 11: Index-Regel verletzt (Area ohne index.md=foo)` |
|
||||
| 11a | Area `wiki/wissensarchitektur/` mit `index.md`, das Area-Concept `source-material.md` **nicht** verlinkt (file-relative Referenz fehlt; der Live-Area-Name wird bewusst genutzt, weil die Fixture den F-02-Defekt am realen Bundle belegt; die übrigen Links der Area werden als valide angenommen — restliche Konzepte verlinkt, Isolations-Prinzip §7.1) | `FAIL wiki/wissensarchitektur/source-material.md Punkt 11: Index-Regel verletzt (Concept nicht verlinkt=wissensarchitektur/source-material)` |
|
||||
| 12 | `sources: {resource: raw/x.md}` (Map statt Liste) | `FAIL wiki/x.md Punkt 12: sources/verified/generated in nicht erlaubter Form` |
|
||||
| 12a | `sources: [{title: \"Ohne resource\"}]` (Eintrag ohne Pflichtangabe `resource`) | `FAIL wiki/x.md Punkt 12: sources/verified/generated in nicht erlaubter Form` |
|
||||
| 13 | Frontmatter mit zweimal `type:` | `FAIL wiki/x.md Punkt 13: doppelter Frontmatter-Key (Key=type)` |
|
||||
| 14 | `stale_after: 2026-02-31` | `FAIL wiki/x.md Punkt 14: fehlerhaftes Wert-Format (Feld=stale_after, Wert=2026-02-31)` |
|
||||
| 14a | `usage_count: 3.0` (Float statt Ganzzahl) | `FAIL wiki/x.md Punkt 14: fehlerhaftes Wert-Format (Feld=usage_count, Wert=3.0)` |
|
||||
| 14b | `at: 2026-08-15T25:00:00Z` (ungültige Stunde, kein ISO-8601-Datetime) | `FAIL wiki/x.md Punkt 14: fehlerhaftes Wert-Format (Feld=at, Wert=2026-08-15T25:00:00Z)` |
|
||||
| 14c | `at: 2027-01-01` (reine Datumsangabe ohne Zeit-/Offset-Anteil — kein ISO-8601-Datetime) | `FAIL wiki/x.md Punkt 14: fehlerhaftes Wert-Format (Feld=at, Wert=2027-01-01)` |
|
||||
|
||||
### 7.2 Positiv-Fixtures — je Punkt das gültige Gegenstück (PASS / SUCCESS)
|
||||
|
||||
Zusätzlich gilt der A0-2/AD-1b-Grundsatz der abgeschlossenen Liste: Ein Concept mit ausschließlich `type` und ohne `sources`/`generated`/`verified`/`status`/`stale_after` (alle optionalen Felder fehlen) ist gültig → `SUCCESS wiki/x.md`. Fehlende optionale Felder sind keine Invalidität (A0-2/AD-1b).
|
||||
|
||||
| # | Fixture (Input) | Erwartetes Verdikt |
|
||||
|---|-----------------|--------------------|
|
||||
| 1 | Concept `x.md` mit `type: concept` | `SUCCESS wiki/x.md` |
|
||||
| 2 | Nicht-reservierte `.md` mit gültigem Frontmatter inkl. `type` | `SUCCESS wiki/x.md` |
|
||||
| 2a | Concept `x.md` mit `<BOM>⏎---⏎type: concept…` (BOM + Leerzeile vor dem Frontmatter) | `SUCCESS wiki/x.md` (stripped Erkennung, §3-Präambel) |
|
||||
| 3 | `sources: [{resource: raw/prd/prd-wow20-2026-08-14.md}]` | `SUCCESS wiki/x.md` |
|
||||
| 4 | `sources: [{resource: raw/prd/prd-wow20-2026-08-14.md}]` (unter `raw/`) | `SUCCESS wiki/x.md` |
|
||||
| 5 | `status: stable` | `SUCCESS wiki/x.md` |
|
||||
| 6 | Concept mit ausschließlich `type`/`sources`/`generated`/`verified`/`status`/`stale_after` | `SUCCESS wiki/x.md` |
|
||||
| 7 | `generated: {by: wow-compiler/0.1.0, at: 2026-08-15T10:00:00Z}` | `SUCCESS wiki/x.md` |
|
||||
| 8 | `wiki/index.md` mit `type: bundle` + `okf_version: "0.2"` | `SUCCESS wiki/index.md` |
|
||||
| 8b | `wiki/index.md` mit `<BOM>⏎---⏎type: bundle⏎okf_version: "0.2"…` (BOM + Leerzeile vor dem Frontmatter) | `SUCCESS wiki/index.md` (stripped Erkennung, §3-Präambel) |
|
||||
| 8a | Bundleroot `wiki/index.md` ist vorhanden | `SUCCESS` (Voraussetzung V-1 nicht verletzt) |
|
||||
| 9 | Kein `okf_version`/`type: bundle` außerhalb `wiki/index.md` | `SUCCESS` (kein Punkt 9) |
|
||||
| 10 | `wiki/log.md` und Area-`index.md` ohne Frontmatter | `SUCCESS wiki/log.md` / `SUCCESS wiki/<area>/index.md` |
|
||||
| 10a | Kein `log.md` außerhalb der Bundleroot (kein `wiki/<area>/log.md`) | `SUCCESS` (Voraussetzung V-2 nicht verletzt) |
|
||||
| 11 | Area `wiki/foo/` mit `index.md`, das neue Concept verlinkt | `SUCCESS` (Punkt 11 nicht verletzt) |
|
||||
| 11a | Area `wiki/wissensarchitektur/` mit `index.md`, das Area-Concept `source-material.md` file-relativ verlinkt (`](source-material.md)`) | `SUCCESS` (Punkt 11 nicht verletzt) |
|
||||
| 12 | `sources` Liste von Maps, je Eintrag mit `resource`; `verified: {by: human:x, at: ...}` (Singleton-Map) | `SUCCESS wiki/x.md` (Singleton-Coercing, §4.2) |
|
||||
| 12a | `sources: [{resource: raw/x.md, title: t}]` (Eintrag mit Pflichtangabe `resource`) | `SUCCESS wiki/x.md` |
|
||||
| 13 | Frontmatter ohne doppelte Keys | `SUCCESS wiki/x.md` |
|
||||
| 14 | `stale_after: 2026-12-31`; `last_modified: 2026-08-14`; `at: 2026-08-15T10:00:00Z`; `usage_count: 3` | `SUCCESS wiki/x.md` |
|
||||
| 14b | `at: 2026-08-15T10:00:00+02:00` (Offset mit Doppelpunkt, gültiges ISO-8601/RFC 3339) | `SUCCESS wiki/x.md` (Normalform §4.3) |
|
||||
| 14c | `at: 2026-08-15T10:00:00+0200` (Offset 4-stellig ohne Doppelpunkt, gültiges ISO-8601/RFC 3339) | `SUCCESS wiki/x.md` (Normalform §4.3) |
|
||||
| 14d | `usage_count: 3` (YAML-Integer) | `SUCCESS wiki/x.md` |
|
||||
|
||||
### 7.3 §6-Fachliche-Zusatzprüfungen-Fixtures (EC-1, EC-3, WARN, EC-11) & Innen-Ebenen-Punkt-6-Fixtures
|
||||
|
||||
> Diese Prüfungen sind keine §7-Punkte (Fachliche Prüfungen, §6). Für Negativ-Fixtures gilt dasselbe Isolations-Prinzip wie in §7.1: jedes Sample ist sonst-valide (die 14 Punkte passieren), sodass genau die jeweilige §6-Prüfung auslöst. Das Isolations-Prinzip gilt entsprechend auch für die hier aufgeführten Punkt-6-Fälle auf Innen-Ebenen (`sources`/`generated`/`verified`-Einträge): Ein unautorisierter Key innerhalb eines Eintrags (Negativ-Zeile: `sources:\n - resource: …\n role: x` → genau Punkt 6 löst aus, losgelöst von der §6-Formprüfung; vertraglich §3.3–§3.5), ein Eintrag mit ausschließlich erlaubten Keys (Positiv-Zeile) passiert alle Punkte. Die Verdikt-Zellen tragen den reinen, maschinenlesbaren Fehlerursachen-String gemäß §3 (kein erklärender Zusatz in der Zelle).
|
||||
|
||||
| # | Fixture (Input) | Erwartetes Verdikt |
|
||||
|---|-----------------|--------------------|
|
||||
| §6.1 EC-1 Positiv | Concept mit `sources: [{resource: raw/prd/prd-wow20-2026-08-14.md}]`, Datei existiert | `SUCCESS wiki/x.md` |
|
||||
| §6.1 EC-1 Negativ | `sources: [{resource: raw/fehlt.md}]`, Datei existiert **nicht** | `FAIL wiki/x.md Fachliche Prüfung EC-1: resource existiert nicht (Pfad=raw/fehlt.md)` |
|
||||
| §6.1 EC-1 Negativ (Verzeichnis) | `sources: [{resource: raw/prd}]` (existierendes Verzeichnis, keine Datei) | `FAIL wiki/x.md Fachliche Prüfung EC-1: resource existiert nicht (Pfad=raw/prd)` |
|
||||
| §6.1 EC-1 Aggregation | `sources: [{resource: raw/a.md}, {resource: raw/b.md}]`, beide fehlen | `FAIL wiki/x.md Fachliche Prüfung EC-1: resource existiert nicht (Pfad=raw/a.md, raw/b.md)` |
|
||||
| §6.3 EC-3 Positiv | `stale_after: 2026-12-31`, `last_modified: 2026-08-14`, `at: 2026-08-15T10:00:00Z` (reale Kalenderdaten) | `SUCCESS wiki/x.md` |
|
||||
| §6.3 EC-3 Negativ | `nur at: 2026-02-31T10:00:00Z` (Tag existiert nicht im Februar) | `FAIL wiki/x.md Fachliche Prüfung EC-3: Kalender-Validität verletzt (Feld=at, Wert=2026-02-31T10:00:00Z)` |
|
||||
| §6.4 WARN Negativ | `stale_after: 2026-01-01` mit `today` (UTC) = 2026-08-16 → veraltet | `SUCCESS wiki/x.md` + `WARN wiki/x.md stale_after überschritten (Datum=2026-01-01, today=2026-08-16)` |
|
||||
| §6.4 WARN Positiv (nicht veraltet) | `stale_after: 2026-12-31` mit `today` (UTC) = 2026-08-16 → nicht veraltet | `SUCCESS wiki/x.md` (keine WARN) |
|
||||
| §6.5 EC-11 Positiv | `wiki/<area>/logo.png` (nicht-`.md` unter `wiki/`) vorhanden | kein Verdikt für `logo.png` (wird ignoriert, §1/§6.5); valide `.md`-Dateien unverändert SUCCESS |
|
||||
| §6.5 EC-11 Konvention | Verzeichnis `wiki/<area>/` enthält nur `logo.png` + `index.md` | `SUCCESS wiki/<area>/index.md` (logo.png ignoriert) |
|
||||
| Innen-Ebenen Punkt 6 Negativ | `sources:\n - resource: raw/prd/prd-wow20-2026-08-14.md\n role: x` (existierende `raw/`-Datei, unautorisierter Key `role:` in `sources`-Eintrag) | `FAIL wiki/x.md Punkt 6: nicht autorisiertes Feld (Key=role) bzw. unautorisierter Key in sources/generated/verified` |
|
||||
| Innen-Ebenen Punkt 6 Positiv | `sources`-Eintrag mit `resource` und ausschließlich erlaubten Keys (kein `role`) | `SUCCESS wiki/x.md` (kein Punkt 6) |
|
||||
| §3.2 V-1 Negativ | `wiki/index.md` existiert **nicht** (Bundle ohne Bundleroot) | `FAIL (Voraussetzung) Bundleroot fehlt: wiki/index.md existiert nicht (V-1, Vertrag §2, Vorausbedingung zu Punkt 8)` |
|
||||
| §3.2 V-1 Positiv | `wiki/index.md` ist vorhanden | `SUCCESS` (Voraussetzung V-1 nicht verletzt) |
|
||||
| §3.2 V-2 Negativ | `wiki/<area>/log.md` existiert (reservierter Name außerhalb der Bundleroot) | `FAIL wiki/<area>/log.md log.md an unzulässiger Position (V-2, reservierter Name, nur Bundleroot, Vertrag §5)` |
|
||||
| §3.2 V-2 Positiv | kein `log.md` außerhalb der Bundleroot | `SUCCESS` (Voraussetzung V-2 nicht verletzt) |
|
||||
|
||||
**Zertifizierungs-Notiz (F-02):** Die obigen §6-Fixtures ergänzen die bislang ausschließlich die 14 §7-Punkte belegende Fixture-Abdeckung. Der Eintrag in `wiki/log.md` (2026-08-15, Revision 2) behauptete „alle Negativ-/Positiv-Fixtures" geprüft zu haben — das bezog sich auf §7.1/§7.2. Die §6-Gates (EC-1/EC-3) sind damit erst jetzt explizit fixturiert und zertifizierbar.
|
||||
|
||||
## 8. Normreferenzen & Revisionslog
|
||||
|
||||
**Normreferenzen (ableitungsseitig, read-only):**
|
||||
|
||||
- `schema/wiki-compiler.md` — autorisierter Vertrag (Story 1.3): §1 Geltungsbereich, §2 Bundleroot, §3.1–§3.7 Feldsubset & `sources`-Auflösung, §5 `log.md`-Typ, §6 Index-Regel/Prädikate, §7 abschließende 14-Punkte-Liste (inkl. Kalender-Validität & UTC-Vergleich), §8 Normreferenzen.
|
||||
- PRD §13 — OKF-0.2 als normativer Format-Standard (FR-9, NFR-6); OKF-Spezifikation (Google Cloud, `knowledge-catalog`).
|
||||
- AD-1b/F-2/A0-2 — strukturelle Invalidität schlägt den Run fehl; fehlende optionale Felder nicht invalide.
|
||||
- AD-13/AD-17h/Q-6 — deterministische, ohne LLM-Urteil aufrufbare Agent-Instruktions-Validierung, mechanisch zu bestätigen.
|
||||
- AD-3 — `raw/` immutable; fehlgeschlagener Run lässt `raw/` unangetastet (auch: keine Mutationen bei FAIL).
|
||||
- AD-4b/A0-4 — Provenienz-Ziellinie: `sources` nie auf `wiki/`-Pfade.
|
||||
- D-3 — kein Standalone-Programm als Validator; die Regel bleibt eine Instruktion.
|
||||
- Deferred-Work `_bmad-output/implementation-artifacts/deferred-work.md` — EC-1, EC-3, BH-14, F2-Listen, BH-8, EC-11, F17-`log.md`, F18-`stale_after` (8 an Story 1.4 verwiesene Entscheidungen, in §4/§6 deterministisch festgelegt).
|
||||
- **F15 (Trust-Semantik von `generated.by`):** `generated.by: human:<id>` ist formgültig — das Datenmodell erlaubt jeden non-empty `by` (Vertrag §3.4) —, begründet aber **keine** human-review-Klassifikation (die entsteht nur über `verified` mit `human:`-Präfix, §3.5). Die Trust-Semantik von `generated.by` mit `human:`-Präfix wird in Epic 4 geklärt (Deferred-Work F15).
|
||||
- **Story 2.3 (Link-Form):** Der Punkt-11-Check akzeptiert die Concept-Identität in der zuständigen `index.md` mit oder ohne `.md`-Endung (§3 Punkt 11). Eine genau-eine-Form-Festlegung der Link-Schreibweise ist Story 2.3 und wird hier bewusst nicht vorweggenommen.
|
||||
- **Revision 9 — Punkt-11-Area-Lesart (autorisiert, 2026-08-18):** Ergänzt die Story-2.3-Formklausel um die konsistente Nachführung der Pin-Form-Doktrin: Für ein **Area-Concept** genügt die file-relative Referenz in der Area-`index.md` des nächsten Vorfahren (Pärchen Area-Präfix + Link-Ziel identitätsstiftend); Root-Concepts bleiben wie bisher (mit oder ohne `.md`-Endung) in der Bundleroot referenziert. Dies ist die formale Vereinheitlichung der Story-2.3-Notiz mit der von Story 2.4/2.5 genutzten file-relativen Area-Linkform (`compiler.md` §5.6/§5.7) — no new §7-Klasse, die abschließende 14-Punkte-Liste bleibt unangetastet (Vertrag §7).
|
||||
|
||||
**Revisionslog:**
|
||||
|
||||
- **Revision 1 (2026-08-15):** Erstes abgeleitetes Artefakt — die 14 §7-Punkte als mechanische Prüfschritte (§3), Normalisierungs-/Toleranz-Regeln (§4), maschinenlesbares Verdikt-Format & Selbstbegrenzung (§5), fachliche Zusatzprüfungen (§6), Referenz-Fixtures (§7).
|
||||
- **Revision 2 (2026-08-15):** Review-Patches — §3.2 Voraussetzungsprüfungen (Bundleroot/`log.md`-Position) als Nicht-§7-Pflichten; Punkt 6/9-Exemption-Notiz (kein Punkt-6-vor-9-Feuer); Punkt 9 auf Dateiinhalt ausgeweitet; Punkt 10 BOM-/Leerzeilen-Stripping; Punkt 11 deterministische Link-Prüfung ohne Story-2.3-Vorwegnahme; Punkt 12 fehlende/leere `resource`; Punkt 14 `usage_count`-YAML-Integer-Typ + korrekter `at`-Verweis (§4.3); §4.3 akzeptiert `±HH:MM` (keine unautorisierte Verschärfung); §4.4-Ausführungs-Reihenfolge mit §3.2/§6-Phasen und EC-1-Aggregation; §5-WARN als Berichtskanal statt Verdikt-Verb; §6.1 „als Datei, nicht Verzeichnis" + Aggregation; §6.2 Punkt-4-vor-3-Priorität; Fixtures ergänzt/aktualisiert (§7); Normreferenzen F15/Story 2.3.
|
||||
- **Revision 3 (2026-08-16):** Re-Konsistenz mit dem autorisierten Vertrag (Retrospective F-01, AI-1): Die in Revision 2 eingeführte Toleranz „reine Datumsangabe `YYYY-MM-DD` als `at` → SUCCESS (normalisiert zu `T00:00:00Z`)" ist zurückgenommen. `at` in `generated`/`verified` MUSS jetzt ein volles ISO-8601-Datetime sein; eine reine Datumsangabe erzeugt **FAIL nach Punkt 14** (Vertrag §3.4/§3.5: „ISO-8601-Datetime", §7 Punkt 14). §4.3 entsprechend umformuliert; Fixture 14c als Negativ-Fixture (`at: 2027-01-01` → FAIL) geführt, das freie Positiv-Slot mit der `±HHMM`-Form (`+0200`) belegt. Der autorisierte Vertrag `schema/wiki-compiler.md` bleibt unverändert.
|
||||
- **Revision 4 (2026-08-16):** §6-Fixtures ergänzt (Retrospective F-02, AI-2) — neue Tabelle §7.3 belegt die fachlichen Zusatzprüfungen §6: EC-1-Existenz (Positiv/Negativ/Verzeichnis/Aggregation), EC-3-Kalender-Validität (Positiv/Negativ), §6.4-`stale_after`-WARN (veraltet/nicht veraltet), EC-11-`non-md` (Ignoranz). §6.1/§6.3/§6.4/§6.5 tragen Verweise auf §7.3; §7-Einleitung nennt §6-Fixtures als eigene Sektion. Zertifizierung in `wiki/log.md` (2026-08-16) nachgeführt.
|
||||
- **Revision 5 (2026-08-16):** §3.2-Voraussetzungsprüfungen als fachliche Prüfklasse V-1/V-2 gelabelt (Retrospective F-03, AI-3) — Verdikt-Präfix ändert sich von `FAIL (Struktur) …` auf `FAIL (Voraussetzung) … (V-1|V-2, …)`; §5-Verdikt-Grammatik und §5.1-Selbstbegrenzung um die V-1/V-2-Abgrenzung ergänzt (fachliche Prüfklassen verlassen die Abschluss-Eigenschaft des §7-Katalogs nicht); §7.1-Fixtures 8a/10a an die V-1/V-2-Sprache angeglichen; §7.3 um V-1/V-2 (Positiv/Negativ, 4 Zeilen) erweitert; §3.2 erhält ein erklärendes `<details>` (Warum V-1/V-2, Verweis auf F-03/AI-3). Vertrag `schema/wiki-compiler.md` unverändert (keine Autorisierung nötig).
|
||||
- **Revision 6 (2026-08-16):** BOM-/Leerzeilen-Stripping vereinheitlicht (Retrospective F-05, AI-5) — die gemeinsame Definition „gestrippte Frontmatter-Erkennung" (§3-Präambel: UTF-8-BOM `U+FEFF` + führende Leerzeilen vor dem `---` entfernen) gilt jetzt für alle Frontmatter-erkennenden Punkte **2, 8 und 10** (zuvor nur Punkt 10). Punkt 2/8-Prüfschritt-Zellen verweisen auf §3-Präambel; Punkt 10 rückverweist darauf. Neue Positiv-Fixtures: 2a (Concept mit BOM/Leerzeile vor Frontmatter → SUCCESS) und 8b (Bundleroot mit BOM/Leerzeile vor Frontmatter → SUCCESS). Zusätzlich zwei Defer-Verweise als „offene Punkte" (§1 Punkt 3 zu `.MD`-Großschreibung, F-08; §6.4 zu `today`-Zeitzone, F-06) eingebettet — Defer-Kontexte aus AI-7. Vertrag unverändert.
|
||||
- **Revision 7 (2026-08-16, Step-04-Review Story 2.1):** §7.3-Fixture-Isolations-Hinweis um Innen-Ebenen-Key-Subset-Fälle erweitert — die Punkt-6-Formprüfung gilt nicht nur für Top-Level-Frontmatter-Felder, sondern auch für unautorisierte Keys innerhalb von `sources`/`generated`/`verified`-Einträgen (Vertrag §3.3–§3.5); Konsequenz für Fixture-Isolation (sonst-valide und nur der Innen-Ebenen-Key sticht Punkt 6 hervor) dokumentiert (§7.3). Vertrag `schema/wiki-compiler.md` unverändert (keine Autorisierung nötig, nur dokumentarische Klarstellung der bestehenden Punkt-6-Regel).
|
||||
- **Revision 8 (2026-08-16, Autorisations-Runde):** Option-A-Heilung Story 2.1 — drei Änderungen: (1) **F-14-Negativ-Fixture 4a** ergänzt (§7.1, Punkt 4: `resource` außerhalb `raw/`, aber existierend, z. B. `README.md` an der Workspace-Root; Retrospective F-14) — erwartet `FAIL … Punkt 4`, Isolations-Prinzip gewahrt; (2) **Innen-Ebenen-Key-Subset formalisiert** — die Rev-7-Klarstellung (Punkt 6 in `sources`/`generated`/`verified`-Einträgen, Vertrag §3.3–§3.5) wird als formal getragener Inhalt dieser autorisierten Revision bestätigt, und die Punkt-6-Zelle verweist explizit auf die §7.3-Isolations-Notiz (autorisiert, Revision 8); (3) **Header-Revisionszahl** von „Revision 6" auf „Revision 8" angehoben (behebt die pre-existing Header-Log-Diskrepanz, OBS-1). Vertrag `schema/wiki-compiler.md` unverändert (keine Vertrags-Autorisierung nötig — Punkt 6 deckt Innen-Ebenen bereits, §3.3–§3.5).
|
||||
- **Revision 9 (2026-08-18, Autorisations-Runde):** Epic-2-F-02/AI-2-R-5 (de-dupliziert mit `code-review-2-1-item-2`) — fünf inhaltliche Änderungen, keine neue §7-Klasse (kein Punkt 15; Abschluss-Eigenschaft des §7-Katalogs gewahrt), `schema/wiki-compiler.md` (Vertrag) und `schema/compiler.md` (Instruktion) unverändert (AD-3/D-3): (1) **Punkt-11-Area-Lesart formalisiert** (§3 Punkt-11-Zelle, Kern der Rev-9-Lesart, Retrospective F-02/Open question 3): Für ein Area-Concept genügt die **file-relative** Referenz in der `index.md` des nächsten Vorfahren (Area-`index.md`); identitätsstiftend ist das **Pärchen (Area-Präfix = bundle-relativer Verzeichnispfad der Area-`index.md` + Link-Ziel ohne `.md`-Endung, AD-7a)**, eine textuelle Nennung der Bundle-Identität in der Area-`index.md` ist nicht erforderlich (Live: `wiki/wissensarchitektur/source-material.md` → Identität `wissensarchitektur/source-material` über `](source-material.md)` in der Area-`index.md`); Normalisierung des Link-Ziels (`.`/`./`-Strip; `..` nicht Teil der gepinnten Ein-Ebenen-Form) und `.md`-Endungs-Strip für die Identitätsbildung explizit verankert. Root-Concepts bleiben wie bisher in der Bundleroot referenziert (mit oder ohne `.md`-Endung — eine genau-eine-Form-Festlegung liegt bei Story 2.3/§5.6 der Compiler-Instruktion, der Validator gibt sie nicht vor). (2) **Punkt-4-Fehlerursachen-Grammatik um `resolved=<pfad>`-Token ergänzt + Semantik verankert** (§3 Punkt-4-Zelle: `…|resolved=<pfad>`; §6.2: Token feuert nur bei Ablehnung durch aufgelöste Lage außerhalb `raw/`, Wert = aufgelöster workspace-relativer Pfad; Konsistenz mit §5-Verdikt-Grammatik) — Patch 16 (gehalten, deferred-work.md), macht Fixture 4a (§7.1: `resolved=README.md`) ableitbar. (3) **Innen-Ebenen-Punkt-6-Fixtures ergänzt** (§7.3: Negativ-Zeile `sources`-Eintrag mit `role: x` bei existierender `raw/`-Datei → `FAIL … Punkt 6`; Positiv-Gegenzeile ausschließlich erlaubte Keys → SUCCESS) — Patch 17 (gehalten), belegt die Rev-8-Formalisierung der Innen-Ebenen-Regel re-runbar. (4) **§7-Fixtures 11a** (Negativ: Area-Concept nicht verlinkt → `FAIL … Concept nicht verlinkt=wissensarchitektur/source-material`; Positiv: file-relativ verlinkt → SUCCESS) ergänzt — prüfbare Negative der Area-Lesart am realen Live-Area-Namen. (5) **§8-Normreferenz-Notiz „Story 2.3 (Link-Form)" um die Rev-9-Area-Lesart ergänzt** (Konsistenz der Lesart mit der Pin-Form-Doktrin). Nachgeführt: Header-Revisionszahl auf „Revision 9" angehoben + Revisionslog-Eintrag (append-only, bestehende Einträge unangetastet). Zertifizierung in `wiki/log.md` (2026-08-18) nachgeführt: Fixture 4a isoliert → FAIL Punkt 4 (`resolved=README.md`); Innen-Ebenen-Sample → FAIL Punkt 6 (`Key=role`); Punkt-11-Area-Fixtures (11a Negativ/Positiv) → FAIL bzw. SUCCESS; reales Bundle (7 `wiki/`-Dateien) → weiterhin SUCCESS. Vertrag unverändert (Punkt 11 deckt die Area-Lesart bereits vertraglich, §7).
|
||||
+193
-11
@@ -1,15 +1,197 @@
|
||||
# Wiki of Wikis — Compiler-Schema-Vertrag (Platzhalter)
|
||||
# Wiki of Wikis — Compiler-Schema-Vertrag (OKF 0.2)
|
||||
|
||||
> **Status:** Platzhalter (Story 1.3 «OKF-Schema-Vertrag autorisieren» füllt diesen Vertrag aus und **autorisiert** die folgenden Entscheidungen). Dieser Liste ist eine offene Entscheidungsvorlage, keine normative Festlegung.
|
||||
> **Status:** autorisiert (Story 1.3) — verbindlicher, normativer OKF-0.2-Schema-Vertrag für das Knowledge Bundle.
|
||||
|
||||
Hier wird der **verbindliche OKF-0.2-Feldsubset-Vertrag** (AD-1a, A0-1) verankert, den Story 1.3 autorisiert. Zu entscheiden sind:
|
||||
> **Vertrags-Metadaten:**
|
||||
> - **Autorisierende Story:** Story 1.3 «OKF-Schema-Vertrag `schema/wiki-compiler.md` autorisieren» — Spezifikation: `_bmad-output/implementation-artifacts/spec-1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren.md`
|
||||
> - **Autorisierungsdatum:** 2026-08-15
|
||||
> - **Revision:** 1 (Re-Derivation nach Loop-1-Review; Spec Change Log, Loop 1)
|
||||
|
||||
- erlaubtes OKF-0.2-Feldsubset — `type` als einziges Pflichtfeld; optional `sources`, `generated`, `verified`, `status`, `stale_after`;
|
||||
- Liste-vs.-Map-Form von `sources`;
|
||||
- Zulässigkeit von `generated`/`verified` und `status`-Policing;
|
||||
- Typdefinition von `log.md`;
|
||||
- Index-Regel (jedes Area besitzt eine `index.md`);
|
||||
- Validitätsprädikate für Concepts und Bundle-Root;
|
||||
- Bindung des Verbots: `sources`-Einträge lösen niemals auf `wiki/`-Concept-Pfade auf (AD-4b, A0-4).
|
||||
Dieser Vertrag ist die **einzige normative Quelle** für das erlaubte OKF-0.2-Feldsubset, die exakte `sources`-Form, die Zulässigkeit von `generated`/`verified`, das `status`-Policing, `stale_after`, die `okf_version`-Regel, die `log.md`-Typdefinition, die Index-Regel sowie die Validitätsprädikate für Concepts und Bundle-Root (AD-1a, A0-1, D-10). Er bindet alle Producer (Compiler und Adapter) gleichermaßen und ist die Prüfgrundlage der Schema-Validierung (Story 1.4, AD-1b/F-2/A0-2). Jede inhaltliche Abweichung von diesem Vertrag erfordert eine neue Autorisierung; einzelne Producer dürfen sie nicht vornehmen. Das Schema liegt **außerhalb** des Bundles (`wiki/`) und ist keine Concept-Datei; es ist ein reiner Textvertrag (Markdown) und kein ausführbarer Code (Structural Seed, AD-1).
|
||||
|
||||
Das Schema liegt **außerhalb** des Bundles (`wiki/`) und ist keine Concept-Datei (Structural Seed, AD-1).
|
||||
Fachliche Verbindlichkeit: Begriffe wie „MUSS" und „DARF NICHT" sind verbindliche Regeln; Verstöße gelten, sofern hier nicht anders geregelt, als strukturelle Invalidität (§7). „SOLL" ist eine normative Empfehlung, deren Abweichung begründet werden muss. „KANN"/„darf" bezeichnet eine zulässige, aber nicht geforderte Möglichkeit.
|
||||
|
||||
## 1. Geltungsbereich
|
||||
|
||||
- Dieser Vertrag gilt für alle Markdown-Dateien innerhalb der Bundleroot `wiki/` sowie für die Pfade, auf die `sources`-Einträge von Concepts verweisen.
|
||||
- Er gilt nicht für `raw/`, `schema/` und `adapters/`: Diese liegen außerhalb des Bundles und sind keine Concept-Dateien (Structural Seed, AD-1).
|
||||
- Verteilte Regelwerke in `adapters/` MÜSSEN mit diesem Vertrag konform sein und DÜRFEN keine abweichende Knowledge-Semantik definieren (AD-10).
|
||||
- Der Vertrag bleibt rein textuell; er wird von den konsumierenden Producern als Instruktion und von der Validierung (Story 1.4) als Prüfregelwerk gelesen (AD-1).
|
||||
|
||||
## 2. Bundle-Struktur und Bundleroot (`okf_version`-Regel)
|
||||
|
||||
- Die Bundleroot ist `wiki/` (AD-1, AD-9). Sie ist das einzige Verzeichnis, das als OKF Knowledge Bundle behandelt wird; `raw/`, `schema/` und `adapters/` sind keine Bestandteile des Bundles.
|
||||
- Die Bundleroot enthält zwingend eine Datei `wiki/index.md` und — nach Anlage — eine Datei `wiki/log.md` (reservierte Namen; `index.md`-Regeln: §2/§6, `log.md`-Typdefinition: §5). Weitere `.md`-Dateien auf Root-Ebene sind Concepts und unterliegen dem Concept-Prädikat (§6.1).
|
||||
- `wiki/index.md` MUSS als Bundleroot deklariert sein; ihr Frontmatter ist **ausschließlich** die Bundledeklaration `type: bundle` und `okf_version: "0.2"`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: bundle
|
||||
okf_version: "0.2"
|
||||
---
|
||||
```
|
||||
|
||||
Zusätzliche oder abweichende Frontmatter-Felder sind in der Bundleroot **nicht** zulässig.
|
||||
- **`okf_version`-Regel:** `okf_version: "0.2"` MUSS ausschließlich in der Bundleroot `wiki/index.md` stehen. Es DARF NICHT in Area-`index.md`, in Concepts, in `log.md` oder in irgendeiner anderen Bundle-Datei vorkommen.
|
||||
- **`type: bundle`-Regel:** `type: bundle` MUSS ausschließlich in der Bundleroot `wiki/index.md` vorkommen. Es DARF NICHT in irgendeiner anderen Datei des Bundles auftauchen.
|
||||
- **Frontmatter-Exklusivität:** Area-`index.md`-Dateien (§6) und `log.md`-Dateien (§5) tragen **kein** Frontmatter. Genauer: Frontmatter ist in `index.md` ausschließlich in der Bundleroot erlaubt; jede andere `index.md` im Bundle MUSS frontmatterlos sein.
|
||||
|
||||
## 3. Concept-Feldsubset
|
||||
|
||||
Ein Concept ist eine Markdown-Datei mit YAML-Frontmatter innerhalb von `wiki/`, die weder `index.md` noch `log.md` ist. Für das Frontmatter eines Concepts gilt das folgende Feldsubset. Es ist vollständig: Kein anderes Frontmatter-Feld ist erlaubt.
|
||||
|
||||
### 3.1 `type` — einziges Pflichtfeld
|
||||
|
||||
- `type` MUSS gesetzt und darf nicht leer sein. Es ist das einzige Pflichtfeld eines Concepts. `type` MUSS ein nicht-leerer String sein; nicht-String-Werte (z. B. `null`, Zahlen, Datumsobjekte) sind nicht gesetzt im Sinne dieses Vertrags und damit strukturell invalide.
|
||||
- Nicht gesperrte `.md`-Dateien im Bundle (also alle Concepts) MÜSSEN einen `type` tragen; eine `.md`-Datei im Bundle ohne Frontmatter bzw. ohne `type` ist strukturell invalide (§7) — sie ist nicht „kein Concept", sondern ein invalides Bundle-Element. «Reserviert» im Sinne dieses Vertrags sind ausschließlich `index.md` (Bundleroot und Area-`index.md`) und `log.md` (§2, §5, §6); alle übrigen `.md`-Dateien gelten als nicht-reserviert.
|
||||
- Der Wert von `type` ist eine fachliche Klassifikation des Concepts und wird in der Regel `concept` oder eine spezifischere, im jeweiligen Fall bestimmte Klasse sein; die Zulässigkeit konkreter Werte legt dieser Vertrag nicht über die Nicht-Leerheit hinaus fest.
|
||||
|
||||
### 3.2 Optionale Felder
|
||||
|
||||
Optionale Felder eines Concepts sind ausschließlich: `sources`, `generated`, `verified`, `status`, `stale_after`. Alle fünf sind einzeln weglassbar. Das Fehlen eines optionalen Feldes ist niemals ein Validierungsfehler (A0-2/AD-1b, §7). Leere Werte zählen dabei wie folgt: `sources: []` und `verified: []` sind zulässig und semantisch gleichbedeutend mit Absenz; leere Listen sind also keine Invalidität.
|
||||
|
||||
### 3.3 `sources` — Liste von Maps
|
||||
|
||||
- `sources` MUSS, falls gesetzt, eine **YAML-Liste von Maps** sein. Die Map-/Objekt-Form als Quelle (ein einzelnes Mapping direkt unter `sources`) ist **nicht** zulässig. `sources: []` (leere Liste) ist zulässig und gleichbedeutend mit Absenz.
|
||||
- Jeder Listeneintrag ist eine Map. `resource` ist die **einzige Pflichtangabe** je Eintrag und MUSS gesetzt und nicht leer sein. Die folgenden Angaben sind innerhalb eines Eintrags optional (OKF-0.2-Evidenz-Grammatik): `id` (stabile Kennung, effizient für Zitat-Attribution), `title`, `author`, `usage_count` (Ganzzahl ≥ 0), `last_modified` (ISO-Datum `YYYY-MM-DD`).
|
||||
- **Key-Subset je Ebene:** Innerhalb eines `sources`-Eintrags sind ausschließlich die Felder `resource`, `id`, `title`, `author`, `usage_count`, `last_modified` erlaubt. Unautorisierte Keys in einem `sources`-Eintrag sind strukturell invalide (§7).
|
||||
- **Provenienz-Ziellinie (Verbot):** `resource` MUSS auf einen Pfad unter `raw/` verweisen — auf lokal materialisierte, immutable Evidenz (FR-1/A-4, AD-4b/A0-4). `resource` DARF NIEMALS auf einen `wiki/`-Concept-Pfad auflösen. Pfade in `sources` sind Provenienz zur Evidenz und ersetzen keine Wiki-Links: Wiki-Links sind die Navigations-/Beziehungsschicht (AD-8) und werden formatseitig von Provenienz unterschieden.
|
||||
- **Deterministische Auflöse-Basis (v1):** `resource` ist ein relativer Workspace-Pfad, der **relativ zur Workspace-Root** (oberste Ebene des Git-Arbeitsverzeichnisses) aufgelöst wird. In v1 MUSS der aufgelöste Pfad innerhalb `raw/` landen; eine URL-Form von `resource` ist in v1 nicht zulässig (FR-1, A-4). `..`-Traversale ist generell unzulässig — unabhängig davon, ob das Auflösungsziel innerhalb `raw/` liegt: `resource` DARF keinen `..`-Path-Segment enthalten und DARF bei Auflösung NICHT außerhalb `raw/` landen. Absolute Pfadformen (führender `/`), `file://`-Präfixe und Backslash-/Windows-Trenner sind in v1 ebenfalls nicht zulässig; `resource` nutzt ausschließlich `/`-getrennte relative Pfade.
|
||||
- **Existenz-Prüfung als Validator-Verhalten:** Die Prüfung, ob die referenzierte `raw/`-Datei tatsächlich existiert, ist ein Validator-Verhalten der Story 1.4 und wird hier nicht durchgeführt; sie ist als Normreferenz in §8 vermerkt.
|
||||
- Beispiel:
|
||||
|
||||
```yaml
|
||||
sources:
|
||||
- resource: raw/prd/prd-wow20-2026-08-14.md
|
||||
id: s1
|
||||
title: "Wiki of Wikis PRD"
|
||||
author: "Michael Tamse"
|
||||
usage_count: 3
|
||||
last_modified: 2026-08-14
|
||||
```
|
||||
|
||||
### 3.4 `generated`
|
||||
|
||||
- `generated` ist, falls gesetzt, eine Map mit den Feldern `by` und `at`. Die Map-Form ist die einzige zulässige Form; eine Liste ist hier nicht zulässig.
|
||||
- `by` ist die Pflichtangabe innerhalb `generated` und MUSS gesetzt und **nicht leer** sein (leerer String und reiner Whitespace sind verboten). Ein `generated` ohne `by` (nur `at` oder leer) ist strukturell invalide (§7). `at` ist optional; falls gesetzt, MUSS es ein ISO-8601-Datetime sein.
|
||||
- **Key-Subset:** Innerhalb von `generated` sind ausschließlich die Felder `by` und `at` erlaubt. Unautorisierte Keys sind strukturell invalide (§7).
|
||||
- **Actor-Konvention für `by`:** Agenten/Tools verwenden `<producer>/<version>` (z. B. `wow-compiler/0.1.0`); Personen verwenden `human:<id>` (z. B. `human:michael`).
|
||||
- `generated` kennzeichnet maschinelle Erzeugung. Der v1-Default laut A0-20 ist: maschinell erzeugt und ungeprüft → `generated` gesetzt, `verified` ungesetzt.
|
||||
- Beispiel:
|
||||
|
||||
```yaml
|
||||
generated:
|
||||
by: wow-compiler/0.1.0
|
||||
at: 2026-08-14T12:00:00Z
|
||||
```
|
||||
|
||||
### 3.5 `verified`
|
||||
|
||||
- `verified` ist, falls gesetzt, eine Liste von `{by, at}`-Ereignissen. Eine einzelne Map (`verified: { by: ..., at: ... }`) MUSS als 1-Element-Liste interpretiert werden. `verified: []` (leere Liste) ist zulässig und gleichbedeutend mit Absenz.
|
||||
- In jedem Eintrag ist `by` die Pflichtangabe (identifiziert den/die Reviewer) und MUSS gesetzt und **nicht leer** sein (leerer String und reiner Whitespace sind verboten); ein `verified`-Eintrag ohne `by` ist strukturell invalide (§7). `at` ist optional und MUSS, falls gesetzt, ein ISO-8601-Datetime sein. Konsistenz mit der OKF-0.2-Darstellung: Eine einzelne Map wird als 1-Element-Liste gelesen — diese Toleranz ist Teil des Vertrags und wird von der Schema-Validierung (Story 1.4) entsprechend umgesetzt.
|
||||
- **Key-Subset:** Innerhalb eines `verified`-Eintrags sind ausschließlich die Felder `by` und `at` erlaubt. Unautorisierte Keys sind strukturell invalide (§7).
|
||||
- `by` MUSS der Actor-Konvention aus §3.4 folgen.
|
||||
- **Trust-Klassifikation:** Ein `by`-Wert mit `human:`-Präfix markiert human-reviewed Wissen. Ohne `human:`-Präfix kennzeichnet der Eintrag nicht-userbezogene Prüfung und begründet keine human-review-Klassifikation. Human-reviewed Knowledge bleibt dadurch von ungeprüftem maschinellem Output unterscheidbar (FR-13, AD-15, A0-20).
|
||||
- `verified` bleibt ungesetzt, solange kein Mensch das Concept reviewed hat (v1-Default, A0-20).
|
||||
- Beispiel:
|
||||
|
||||
```yaml
|
||||
verified:
|
||||
- by: human:reviewer-1
|
||||
at: 2026-08-15T09:30:00Z
|
||||
```
|
||||
|
||||
### 3.6 `status` — Policing (unabhängig von Trust)
|
||||
|
||||
- Zulässige Werte von `status` sind ausschließlich: `draft` | `stable` | `deprecated`. Kein anderer Wert ist gültig.
|
||||
- Absenz von `status` bedeutet den Default `stable`: Ein Concept ohne `status` gilt als `stable`.
|
||||
- Ein gesetzter `status` mit einem Wert außerhalb der erlaubten Menge ist strukturell invalide (§7).
|
||||
- **Orthogonalität von `status` und Trust:** `status` (Lifecycle: `draft`/`stable`/`deprecated`) und der `verified`-Status (Trust/Review) sind **unabhängige Dimensionen** (AD-15/A0-20). Ein nicht-human-reviewtes Concept ist NICHT deshalb von `stable` ausgeschlossen; umgekehrt erzwingt `verified` keinen bestimmten `status`. Es gibt keine Regel, die „ungeprüft" mit „nicht stable" gleichsetzt. Insbesondere ist der v1-Default „maschinell erzeugt und ungeprüft" (generated ohne verified) mit dem `status`-Default `stable` vereinbar.
|
||||
|
||||
### 3.7 `stale_after`
|
||||
|
||||
- `stale_after` ist optional und MUSS, falls gesetzt, ein absolutes Datum im Format `YYYY-MM-DD` sein.
|
||||
- Ein Concept gilt als veraltet, wenn das Tagesdatum `today >= stale_after` erfüllt: `today >= stale_after` ⇒ veraltet.
|
||||
|
||||
## 4. (reserviert)
|
||||
|
||||
Dieser Abschnitt ist in dieser Revision unbenutzt und für zukünftige Erweiterungen reserviert. Er ist kein Teil der Norm.
|
||||
|
||||
## 5. `log.md`-Typdefinition (OKF §9)
|
||||
|
||||
- `log.md` ist ein reservierter Name innerhalb des Bundles. In v1 ist `log.md` eine Datei an der Bundleroot (`wiki/log.md`, Lease-Root-Scope, AD-17b); der reservierte Name darf nicht an anderer Stelle im Bundle verwendet werden. (Eine Ausweitung, z. B. `log.md` pro Area, ist eine Normerweiterung und erfordert eine neue Autorisierung.)
|
||||
- `log.md` trägt **kein** Frontmatter.
|
||||
- Format: eine flache Liste datumsgruppierter Einträge, neueste zuerst; der Header jedes Gruppenabschnitts ist ein ISO-Datum `YYYY-MM-DD`.
|
||||
- Inhalt: `log.md` dokumentiert fachliche Änderungen und Disagreements (AD-16b), einschließlich Konfliktklassifikation samt Begründung, verknüpft mit dem jeweils mutierten Concept-Pfad. Es ist Teil der Lease-Root-Scope (`wiki/` inklusive `log.md`, `index.md` und aller Root-Dateien; AD-17b).
|
||||
- Struktur-Beispiel:
|
||||
|
||||
```text
|
||||
# Log
|
||||
|
||||
## 2026-08-15
|
||||
- AD-16b: `flowable/timers` CORRECTING, ersetzt durch ... (Logik: ...)
|
||||
|
||||
## 2026-08-14
|
||||
- neu: `spring/testing` angelegt (sources: raw/...)
|
||||
```
|
||||
|
||||
## 6. Index-Regel und Validitätsprädikate
|
||||
|
||||
**Index-Regel (progressive Discovery):**
|
||||
|
||||
- Jede Area innerhalb von `wiki/` MUSS eine Datei `index.md` enthalten, die die Inhalte der Area verlinkt.
|
||||
- Die `index.md`-Dateien bilden zusammen mit der Bundle-Hierarchie die erste progressive-Discovery-Ebene: Ein Consumer navigiert von der Bundleroot `wiki/index.md` über die Area-`index.md`-Dateien zu den Concepts (AD-9/FR-11).
|
||||
- Neue Concepts MÜSSEN in der `index.md` der zugehörigen Area verlinkt werden, damit sie entdeckbar bleiben (Story 2.5).
|
||||
- Area-`index.md`-Dateien tragen **kein** Frontmatter. Frontmatter ist in `index.md` ausschließlich in der Bundleroot erlaubt (§2).
|
||||
- **Reservierter Status:** `index.md` ist ein reservierter Name; er ist als Bundleroot-Datei und als Area-`index.md` erlaubt. Jede `index.md` im Bundle ist damit vom Invaliditätsfall „nicht-reservierte `.md`-Datei ohne Frontmatter bzw. ohne `type`" (§7, Fall 2) ausgenommen. Die Verletzung der Index-Regel selbst (Area ohne `index.md`, fehlender Link eines neuen Concepts) ist strukturell invalide (§7, Fall 11).
|
||||
|
||||
### 6.1 Concept-Prädikat
|
||||
|
||||
Ein Concept ist gültig genau dann, wenn alle Bedingungen erfüllt sind:
|
||||
|
||||
- **Format:** Markdown mit YAML-Frontmatter; Frontmatter ist gültiges YAML.
|
||||
- **`type`:** vorhanden und nicht leer (§3.1). Eine nicht-reservierte `.md`-Datei im Bundle ohne Frontmatter bzw. ohne `type` ist strukturell invalide (§7).
|
||||
- **Feldsubset:** das Frontmatter enthält ausschließlich Felder aus §3 (kein zusätzliches, nicht autorisiertes Feld).
|
||||
- **`sources`-Form:** falls gesetzt, Liste von Maps mit `resource` je Eintrag (§3.3).
|
||||
- **Provenienz-Ziellinie & Deterministische Auflösung:** kein `resource`-Eintrag löst auf einen `wiki/`-Concept-Pfad auf; kein `resource`-Eintrag verlässt bei Auflösung relativ zur Workspace-Root `raw/` (kein `..`-Traversal, keine URL-Form) (§3.3, AD-4b/A0-4).
|
||||
- **Key-Subset je Ebene:** keine unautorisierten Keys innerhalb von `sources`/`generated`/`verified`-Einträgen sowie keine unautorisierten Frontmatter-Felder (§3.3–3.5).
|
||||
- **`generated`/`verified`-Zulässigkeit:** falls gesetzt, entsprechen `generated` und `verified` den Formen und Pflichtangaben aus §3.4/§3.5; `by` ist jeweils gesetzt und nicht leer.
|
||||
- **`status`:** falls gesetzt, einer der Werte aus §3.6.
|
||||
- **`stale_after`:** falls gesetzt, Datum `YYYY-MM-DD` (§3.7).
|
||||
- **A0-5/AD-4c (Normreferenz, v1 tautologisch erfüllt):** In v1 zeigt `sources` ausschließlich auf `raw/`-Evidenz; ein generiertes Concept kann nie ein anderes generiertes Concept als alleinige Provenienz führen. Diese Regel ist in v1 daher automatisch (tautologisch) erfüllt und erzeugt kein eigenes Validitätsprädikat. Sie ist als Normreferenz zu §8 dokumentiert und bei späterer Einführung von Quellen, die auf andere generierte Concepts zeigen können (Epic 2+), erneut zu evaluieren.
|
||||
|
||||
### 6.2 Bundle-Root-Prädikat
|
||||
|
||||
- Die Bundleroot `wiki/index.md` MUSS `type: bundle` UND `okf_version: "0.2"` tragen; deren Frontmatter ist **ausschließlich** diese beiden Felder (§2).
|
||||
- `okf_version: "0.2"` DARF NICHT in irgendeiner anderen Datei des Bundles vorkommen (insbesondere nicht in Area-`index.md`, Concepts oder `log.md`).
|
||||
- `type: bundle` DARF NICHT in irgendeiner anderen Datei des Bundles vorkommen.
|
||||
- Nur in der Bundleroot `index.md` ist Frontmatter erlaubt; Area-`index.md` und `log.md` sind frontmatterlos.
|
||||
|
||||
## 7. Strukturelle Invalidität vs. optionale Felder
|
||||
|
||||
- **Strukturelle Invalidität** schlägt den Compilation Run fehl. Die Liste der strukturell invaliden Zustände ist **abschließend**; sie umfasst genau die folgenden Fälle:
|
||||
1. ein Concept ohne `type` oder mit leerem `type`;
|
||||
2. eine nicht-reservierte `.md`-Datei im Bundle ohne Frontmatter bzw. ohne `type`;
|
||||
3. ein `sources`-`resource`-Eintrag, der auf einen `wiki/`-Concept-Pfad auflöst;
|
||||
4. ein `sources`-`resource`-Eintrag, der bei Auflösung relativ zur Workspace-Root außerhalb `raw/` landet (insbesondere via `..`-Traversal) oder in v1 eine URL-Form von `resource` darstellt;
|
||||
5. ein verbotener `status`-Wert (nicht `draft`/`stable`/`deprecated`);
|
||||
6. ein nicht autorisiertes Frontmatter-Feld (für Concepts oder Bundleroot) oder ein unautorisierter Key innerhalb eines `sources`/`generated`/`verified`-Eintrags;
|
||||
7. eine leere oder fehlende (reiner Whitespace eingeschlossen) `by`-Angabe in `generated` oder `verified`;
|
||||
8. eine Bundleroot `wiki/index.md` ohne `type: bundle` bzw. ohne `okf_version: "0.2"`, oder ein abweichender `okf_version`-Wert (z. B. `"0.3"`) in der Bundleroot;
|
||||
9. `okf_version: "0.2"` oder `type: bundle` an einer anderen Stelle als der Bundleroot;
|
||||
10. Frontmatter in einer Area-`index.md` oder einer `log.md`;
|
||||
11. die Verletzung der Index-Regel (§6): eine Area ohne `index.md` oder ein neues Concept ohne Verlinkung in der `index.md` der zugehörigen Area;
|
||||
12. ein `sources`- oder `verified`-Eintrag in nicht erlaubter Form (z. B. `sources`/`verified` als einzelne Map statt Liste, Skalar-Einträge statt Maps) sowie ein `generated` in Listen- statt Map-Form;
|
||||
13. ein doppelter Frontmatter-Key (z. B. doppeltes `type` oder doppeltes `okf_version`) — Duplikat-Keys sind strukturell invalide;
|
||||
14. fehlerhafte Wert-Formate: `stale_after`/`last_modified` ungleich `YYYY-MM-DD`, `at` ungleich ISO-8601-Datetime, `usage_count` keine Ganzzahl ≥ 0, `type` kein nicht-leerer String.
|
||||
- **Abschließende Liste:** Diese Liste ist abschließend. Erweiterungen der Invaliditätsdefinition sind nur über die Autorisierung bzw. das Story-Verfahren möglich, nicht stillschweigend durch einzelne Producer oder Validator-Implementierungen.
|
||||
- **Fehlende optionale Felder sind niemals ein Fehler:** Ein Concept mit nur `type` und ohne `sources`/`generated`/`verified`/`status`/`stale_after` ist gültig (A0-2/AD-1b, F-2). Abwesenheit von `status` bedeutet `stable`-Default und ist keine Invalidität. Leere Listen (`sources: []`, `verified: []`) sind zulässig und keine Invalidität.
|
||||
- Ein fehlgeschlagener Run lässt `raw/` unangetastet; die Fehlerursache muss textuell identifizierbar sein (NFR-4/AD-3).
|
||||
- **Kalender-Validität und Datum/Vergleich:** `YYYY-MM-DD`-Felder müssen reale Kalenderdaten sein (z. B. ist `2026-02-31` invalide, obwohl textuell `YYYY-MM-DD`-konform). Der Veraltungsvergleich `today >= stale_after` erfolgt in UTC.
|
||||
|
||||
## 8. Normreferenzen
|
||||
|
||||
- PRD §13 — Fixierung von OKF 0.2 als normativer Format-Standard (FR-9, NFR-6); OKF-Spezifikation (Google Cloud, `knowledge-catalog`).
|
||||
- AD-1, AD-1a, AD-1b (Schema-Bindung, Validierung F-2/A0-2); AD-2/AD-3 (Bundlegrenze, `raw/` immutable); AD-4b/A0-4 (Provenienz-Ziellinie); AD-4c/A0-5 (keine abgeleitete Provenienz; in v1 tautologisch erfüllt, §6.1); AD-9 (Index-Regel/Discovery); AD-15/A0-20 (Trust-Metadaten, v1-Default; Orthogonalität `status`/Trust); AD-16b (Disagreements in `log.md`); AD-17b (Lease-Root-Scope); Structural Seed (Bundleroot `wiki/`, `okf_version` nur in Bundleroot-`index.md`).
|
||||
- Existenz-Prüfung referenzierter `raw/`-Dateien: Validator-Verhalten der Story 1.4 (hier nicht ausgeführt).
|
||||
- Story 1.4 — implementiert die Validierung dieses Vertrags.
|
||||
|
||||
+16
-2
@@ -13,6 +13,7 @@ Hier startet die progressive Discovery (AD-9): von dieser Bundleroot führt der
|
||||
wiki/
|
||||
index.md
|
||||
log.md
|
||||
<concept>.md (Root-Concepts, z. B. llm-wiki-prinzip.md)
|
||||
|
||||
<area>/
|
||||
index.md
|
||||
@@ -20,6 +21,19 @@ wiki/
|
||||
```
|
||||
|
||||
- **`log.md`** — reserviertes Protokoll des Bundles: dokumentiert fachliche Änderungen und Disagreements (AD-16b) und ist Teil der Lease-Root-Scope (AD-17b). Typdefinition folgt im Schema-Vertrag (Story 1.3).
|
||||
- Noch keine Areas vorhanden — dieses Bundle wird in späteren Epics inkrementell gefüllt.
|
||||
|
||||
Der Workspace umfasst außerdem: `raw/` (immutable Source Material/Evidenz, AD-2/AD-3), `schema/` (Compiler-Schema-Vertrag, AD-1) und `adapters/` (dünne Agenten-Adapter, AD-10).
|
||||
## Concepts
|
||||
|
||||
Die folgenden Root-Concepts wurden im ersten Demonstrationslauf (Story 2.1) aus dem Source Material unter `raw/` erzeugt:
|
||||
|
||||
- [LLM-Wiki-Prinzip](llm-wiki-prinzip.md) — konzeptioneller Anker: Rohquellen werden von einem LLM in ein persistentes, kuratiertes Wiki überführt (aus `raw/prd/prd-wow20-2026-08-14.md`).
|
||||
- [Knowledge Compilation & Inkrementelle Evolution](knowledge-kompilation-inkrementell.md) — inkrementeller Datenfluss Interpret → Reconcile → Synthesize → Update (aus `raw/epics/epics-2026-08-14.md`; Datenfluss-Diagramm aus `raw/architecture-spine/architecture-spine-2026-08-14.md`).
|
||||
- [Wissensarchitektur: Source Material, Curated Knowledge & Consumer](wissensarchitektur-trennung-states.md) — die Architekturgrenzen `raw/` (immutable Evidenz) und `wiki/` (kuratiertes Bundle) (aus `raw/architecture-spine/architecture-spine-2026-08-14.md`; Separation of Concerns aus `raw/prd/prd-wow20-2026-08-14.md`).
|
||||
|
||||
## Areas
|
||||
|
||||
Bereiche (Areas) bündeln verwandte Area-Concepts hinter einer eigenen Area-`index.md` (AD-9); die Bereichszuordnung bestimmt §5.7 der Compiler-Instruktion deterministisch:
|
||||
|
||||
- [Wissensarchitektur](wissensarchitektur/index.md) — Concepts zur Architektur des Knowledge Bundles (Source Material als deterministische Basis der Bereichszuordnung).
|
||||
|
||||
Der Workspace umfasst außerdem: `raw/` (immutable Source Material/Evidenz, AD-2/AD-3), `schema/` (drei Artefakte: Schema-Vertrag [`wiki-compiler.md`](../schema/wiki-compiler.md) (autorisiert, AD-1), Validator [`validator.md`](../schema/validator.md) (Story 1.4) und Compiler-Instruktion [`compiler.md`](../schema/compiler.md) (Story 2.1)) und `adapters/` (dünne Agenten-Adapter, AD-10).
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
type: concept
|
||||
sources:
|
||||
- resource: raw/epics/epics-2026-08-14.md
|
||||
id: s1
|
||||
- resource: raw/architecture-spine/architecture-spine-2026-08-14.md
|
||||
id: s2
|
||||
generated:
|
||||
by: wow-compiler/0.1.0
|
||||
at: 2026-08-16T09:23:33Z
|
||||
---
|
||||
|
||||
# Knowledge Compilation & Inkrementelle Evolution
|
||||
|
||||
Wiki of Wikis ist ein inkrementeller Knowledge Compiler: Er verarbeitet Sources gegen das bestehende kuratierte Wissen und entwickelt das Knowledge Bundle fortlaufend weiter, statt es bei jedem Lauf vollständig neu zu erzeugen (raw/epics/epics-2026-08-14.md#FR-12; raw/epics/epics-2026-08-14.md#A0-6).
|
||||
|
||||
## Grundprinzip des Datenflusses
|
||||
|
||||
Jeder Compilation Run beginnt mit dem aktuell vorhandenen Knowledge Bundle und verändert nur die durch neue Erkenntnisse betroffenen Concepts (raw/epics/epics-2026-08-14.md#A0-6; raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5). Der logische Datenfluss lautet:
|
||||
|
||||
```text
|
||||
Existing Knowledge
|
||||
+
|
||||
New Source Material
|
||||
↓
|
||||
Interpret
|
||||
↓
|
||||
Reconcile
|
||||
↓
|
||||
Synthesize
|
||||
↓
|
||||
Update affected Concepts
|
||||
```
|
||||
|
||||
Ausdrücklich nicht verwendet wird ein „Regenerate Everything"-Ansatz, bei dem alle Sources und das komplette Wiki bei jedem Lauf neu erzeugt würden — das würde den Compounding-Effekt des Wissens zerstören (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5).
|
||||
|
||||
Das Diagramm des Datenflusses (Existing Knowledge + New Source Material → Interpret → Reconcile → Synthesize → Update affected Concepts) stammt direkt aus der rohen Quelle `raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5` — übernommen aus `raw/architecture-spine/architecture-spine-2026-08-14.md#AD-5` (rohe Quelle), nicht eigenständig belegt.
|
||||
|
||||
## Folgen für die Fähigkeiten
|
||||
|
||||
- **Inkrementelle Evolution (FR-12):** Unverändertes Wissen bleibt erhalten; Änderungen konzentrieren sich auf durch neue Erkenntnisse betroffene Concepts (raw/epics/epics-2026-08-14.md#FR-12).
|
||||
- **Aktualisierung statt neuer Dateien (FR-6):** Neue Informationen führen nicht automatisch zu neuen Dateien — bestehendes Wissen wird erweitert, präzisiert oder korrigiert (raw/epics/epics-2026-08-14.md#FR-6).
|
||||
- **Konsistenz bei Fehlern (AD-6):** Analyse, Änderungsplanung, Mutation und Validierung sind logisch getrennt; ein teilweise fehlgeschlagener Run hinterlässt kein inkonsistentes Bundle (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-6; raw/epics/epics-2026-08-14.md#A0-7).
|
||||
- **Nachvollziehbarkeit (FR-14):** Änderungen erfolgen an textuellen Artefakten und sind über normale Versionskontrolle (Git-Diff) nachvollziehbar (raw/epics/epics-2026-08-14.md#FR-14).
|
||||
|
||||
## Verbindung zu Regelwerken
|
||||
|
||||
Die Inhaltsklassifikation vor jeder Änderung (NEW / CONFIRMING / CORRECTING / CONTRADICTING / REDUNDANT) (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-16; raw/epics/epics-2026-08-14.md#A0-11) und die deterministische Relevanzbestimmung per textueller, deterministischer Mittel (grep/ripgrep, Markdown-Traversal, Link-Following) sind Teil der inkrementellen Kompilation (raw/epics/epics-2026-08-14.md#A0-18; raw/architecture-spine/architecture-spine-2026-08-14.md#AD-13).
|
||||
|
||||
## Abgrenzung
|
||||
|
||||
Die inkrementelle Kompilation (Interpret → Reconcile → Synthesize → Update) ist die Grundlage von Epic 3. Epic 2 liefert dafür die Voraussetzungen: Concepts, Verlinkung und Area-Hierarchie — als Forward-Referenz übernommen, nicht eigenständig belegt (raw/epics/epics-2026-08-14.md, Story 3.1: Inkrementellen Datenfluss implementieren).
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
type: concept
|
||||
sources:
|
||||
- resource: raw/prd/prd-wow20-2026-08-14.md
|
||||
id: s1
|
||||
generated:
|
||||
by: wow-compiler/0.1.0
|
||||
at: 2026-08-16T09:23:33Z
|
||||
---
|
||||
|
||||
# LLM-Wiki-Prinzip
|
||||
|
||||
Das LLM-Wiki-Prinzip ist der konzeptionelle Anker von Wiki of Wikis. Es beschreibt, wie Rohquellen durch ein LLM schrittweise in ein persistentes, kuratiertes Wiki überführt werden — statt bei jeder Anfrage erneut nach Rohdokumenten zu suchen und sie neu zu interpretieren (raw/prd/prd-wow20-2026-08-14.md, § 0 Document Purpose).
|
||||
|
||||
## Kernidee: Knowledge should compound
|
||||
|
||||
Das zentrale Produktversprechen lautet: **Knowledge should compound.** Einmal erarbeitete Synthese wird dauerhaft in einem kuratierten Wiki abgelegt und muss bei späteren Anfragen nicht erneut aus den Rohquellen rekonstruiert werden. Das Wiki entwickelt sich mit neuen Quellen weiter und bildet das bereits erarbeitete Wissen fortlaufend ab (raw/prd/prd-wow20-2026-08-14.md, § 1 Vision).
|
||||
|
||||
## Positionierung: Knowledge Compiler statt Retrieval-System
|
||||
|
||||
Wiki of Wikis ist primär ein **Knowledge Compiler**, kein Retrieval-System. Es sammelt und indiziert nicht nur Dokumente, sondern verarbeitet Quellen aktiv: lesen, verstehen, in Beziehung setzen und eigenständige Wissensartikel erzeugen. Neue Quellen werden gegen das vorhandene Wiki verarbeitet; vorhandenes Wissen kann dadurch bestätigt, erweitert, präzisiert oder korrigiert werden (raw/prd/prd-wow20-2026-08-14.md, § 1 Vision).
|
||||
|
||||
## Datenfluss
|
||||
|
||||
```text
|
||||
Sources
|
||||
│
|
||||
▼
|
||||
LLM Wiki Compiler
|
||||
│
|
||||
▼
|
||||
Curated OKF Wiki
|
||||
│
|
||||
▼
|
||||
Humans / LLM Agents / BMAD / Coding Agents / other Consumers
|
||||
```
|
||||
|
||||
Das Ergebnis ist ein einfaches, portables Knowledge Bundle aus Markdown-Dateien, das weder eine spezielle Datenbank noch eine proprietäre Knowledge-Plattform benötigt (raw/prd/prd-wow20-2026-08-14.md, § 1 Vision).
|
||||
|
||||
Das Datenfluss-Diagramm (Sources → LLM Wiki Compiler → Curated OKF Wiki → Humans / LLM Agents / BMAD / Coding Agents / other Consumers) stammt direkt aus der rohen Quelle `raw/prd/prd-wow20-2026-08-14.md` (§ 0 Document Purpose) — übernommen aus `raw/prd/prd-wow20-2026-08-14.md` (rohe Quelle), nicht eigenständig belegt.
|
||||
|
||||
## Abgrenzung
|
||||
|
||||
Retrieval (Suche, RAG, Graph-Traversal) ist ausdrücklich nicht Bestandteil des Produktkerns. Ein Consumer kann solche Verfahren später über dem Knowledge Bundle einsetzen — sie gehören jedoch nicht zu Wiki of Wikis selbst (raw/prd/prd-wow20-2026-08-14.md, § 5 Non-Goals).
|
||||
+33
File diff suppressed because one or more lines are too long
@@ -0,0 +1,49 @@
|
||||
---
|
||||
type: concept
|
||||
sources:
|
||||
- resource: raw/architecture-spine/architecture-spine-2026-08-14.md
|
||||
id: s1
|
||||
- resource: raw/prd/prd-wow20-2026-08-14.md
|
||||
id: s2
|
||||
generated:
|
||||
by: wow-compiler/0.1.0
|
||||
at: 2026-08-16T09:23:33Z
|
||||
---
|
||||
|
||||
# Wissensarchitektur: Source Material, Curated Knowledge & Consumer
|
||||
|
||||
Die Architektur von Wiki of Wikis trennt drei Verantwortungsbereiche, die nie vermischt werden dürfen: Quellen, Kompilation und kuratiertes Wissen mit seinen Konsumenten (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-2, #AD-3, #AD-1; raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns).
|
||||
|
||||
## Die Architekturgrenzen `raw/` und `wiki/`
|
||||
|
||||
- **`raw/` — immutable Source Material/Evidenz:** Jede Datei unter `raw/` ist Evidenz. Ein Compilation Run darf bestehendes Source Material niemals verändern (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-3); neue Versionen einer Source werden als neue beziehungsweise versionierte Source behandelt (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-3).
|
||||
- **`wiki/` — kuratiertes OKF Knowledge Bundle:** Jede Datei unter `wiki/` ist eine aus Evidenz abgeleitete Wissensrepräsentation. Das Bundle ist der kanonische persistente Zustand des Systems (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-1; raw/prd/prd-wow20-2026-08-14.md, § 8.2 Plain Files as Canonical State). Das konzeptionelle Gegenstück zu dieser Grenze ist das [LLM-Wiki-Prinzip](llm-wiki-prinzip.md) — die Überführung der Rohquellen in genau dieses kuratierte Bundle (übernommen aus llm-wiki-prinzip auf Basis von raw/prd/prd-wow20-2026-08-14.md, nicht eigenständig belegt).
|
||||
|
||||
Das bloße Kopieren eines Source-Dokuments nach `wiki/` ist keine Kompilation (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-2; raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns). Die inkrementelle Kompilation realisiert diese Trennung: sie verarbeitet neue Sources gegen das bestehende kuratierte Wissen statt zu kopieren ([Knowledge Compilation & Inkrementelle Evolution](knowledge-kompilation-inkrementell.md); übernommen aus knowledge-kompilation-inkrementell auf Basis von raw/architecture-spine/architecture-spine-2026-08-14.md, nicht eigenständig belegt).
|
||||
|
||||
## Separation of Concerns
|
||||
|
||||
```text
|
||||
Sources → Compilation → Knowledge Bundle → Consumers
|
||||
```
|
||||
|
||||
> Das Diagramm (Sources → Compilation → Knowledge Bundle → Consumers) stammt direkt aus der rohen Quelle `raw/prd/prd-wow20-2026-08-14.md` (§ 8.3 Separation of Concerns) — übernommen aus `raw/prd/prd-wow20-2026-08-14.md` (rohe Quelle), nicht eigenständig belegt.
|
||||
|
||||
- Eine Source darf nicht automatisch Teil des Curated Knowledge werden (raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns).
|
||||
- Ein Consumer darf nicht zur Voraussetzung für Kompilation oder Speicherung werden (raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns).
|
||||
- Der Compiler ist ein Producer des Bundle-Artefakts — kein Wissensserver und keine eigene Agent-Runtime (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-11).
|
||||
|
||||
## Consumer-Unabhängigkeit
|
||||
|
||||
Das Knowledge Bundle ist nicht auf einen bestimmten LLM-Agenten oder Workflow zugeschnitten (raw/prd/prd-wow20-2026-08-14.md, § 4.5 FR-16). Menschen lesen es mit normalen Markdown-Werkzeugen; Agenten wie BMAD, Claude Code oder Codex über Standard-Dateioperationen. Ein Wechsel des Consumers erfordert keine Migration des Wissensformats (raw/prd/prd-wow20-2026-08-14.md, § 4.5 FR-16).
|
||||
|
||||
Retrieval (Search, RAG, Graph-Traversal) ist Consumer-Verhalten, nicht Kern des Compilers (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-13; raw/prd/prd-wow20-2026-08-14.md, § 5 Non-Goals).
|
||||
|
||||
## Konvergenzregeln
|
||||
|
||||
| Betrachtet | Quelle |
|
||||
|---|---|
|
||||
| Canonical evidence | `raw/` bzw. referenzierte externe Source (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-4b) |
|
||||
| Canonical knowledge | `wiki/` (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-1) |
|
||||
| Discovery | Hierarchie + `index.md` (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-9) |
|
||||
| Update history | Git + optional OKF `log.md` (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-14) |
|
||||
@@ -0,0 +1,11 @@
|
||||
# Wissensarchitektur
|
||||
|
||||
Die Area **Wissensarchitektur** bündelt die Concepts zur Architektur des Knowledge Bundles — aktuell das Source Material als Basis der deterministischen Bereichszuordnung (wie ein erkanntes Thema einem Bereich zugeordnet wird, AD-7c/A0-10). Der Weg führt — wie überall im Bundle — von der Bundleroot (`wiki/index.md`) über diese Area-`index.md` zu den Concepts.
|
||||
|
||||
Diese `index.md` ist **frontmatterlos** (Vertrag §2/§6, Validator Punkt 10 — die Bundle-Deklaration mit der `bundle`-Type-Markierung und der OKF-Version trägt ausschließlich die Bundleroot `wiki/index.md`).
|
||||
|
||||
## Area-Concepts (deterministische Bereichszuordnung, §5.7)
|
||||
|
||||
- [Source Material als deterministische Basis](source-material.md) — welche Sources die Bereichszuordnung und die Hierarchie fundamentieren (aus `raw/architecture-spine/architecture-spine-2026-08-14.md`; Separation of Concerns aus `raw/prd/prd-wow20-2026-08-14.md`).
|
||||
|
||||
Die Root-Concepts, auf die die Area-Concepts in file-relativer `../`-Form verlinken, erreicht man über die [Bundleroot](../index.md).
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
type: concept
|
||||
sources:
|
||||
- resource: raw/architecture-spine/architecture-spine-2026-08-14.md
|
||||
id: s1
|
||||
- resource: raw/prd/prd-wow20-2026-08-14.md
|
||||
id: s2
|
||||
generated:
|
||||
by: wow-compiler/0.1.0
|
||||
at: 2026-08-18T07:00:00Z
|
||||
---
|
||||
|
||||
# Source Material als deterministische Basis der Bereichszuordnung
|
||||
|
||||
Die Architektur von Wiki of Wikis trennt **Source Material** (`raw/`, immutable Evidenz) von **kuratiertem Wissen** (`wiki/`, OKF-Knowledge-Bundle) (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-2; raw/prd/prd-wow20-2026-08-14.md, § 8.3 Separation of Concerns). Aus dieser Trennung folgt die Basis der **deterministischen Bereichszuordnung** (Story 2.4): Einem erkannten Thema wird sein Bereich **textual-deterministisch** zugeordnet — über einen bestehenden `index.md`-Link oder als Default auf Root-Ebene — und nie per Embedding/Vector-Infrastruktur (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-7c).
|
||||
|
||||
## Warum Source Material die Zuordnung fundamentiert
|
||||
|
||||
- **Sources sind die einzige Evidenz.** Eine Datei unter `raw/` ist Evidenz; eine Datei unter `wiki/` ist eine daraus abgeleitete Wissensrepräsentation (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-2). Bereichszuordnung entscheidet darüber, wo eine solche abgeleitete Repräsentation kanonisch liegt — sie stützt sich daher auf die bestehende `index.md`-Struktur des Bundles und nicht auf abgeleitete Retrieval-Artefakte (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-7c).
|
||||
- **Sources bleiben unverändert.** Ein Compilation Run darf bestehendes Source Material nicht verändern; neue Versionen einer Source werden als neue beziehungsweise versionierte Source behandelt (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-3).
|
||||
|
||||
## Verbindung zur Bundle-Hierarchie
|
||||
|
||||
Die Bereichszuordnung ist Ausdruck der zentralen Grenze aus dem [LLM-Wiki-Prinzip](../llm-wiki-prinzip.md): Rohquellen werden durch einen Compiler in ein persistentes, kuratiertes Wiki überführt (übernommen aus llm-wiki-prinzip auf Basis von raw/prd/prd-wow20-2026-08-14.md, nicht eigenständig belegt). Die Hierarchie (Bundleroot `wiki/index.md` → Area-`index.md` → Concepts) realisiert die progressive Discovery schrittweise (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-9). Ein neues Concept wird in der `index.md` **seines** Bereichs verlinkt; eine Area ohne `index.md` ist strukturell invalide, weil die stabile Navigation — und damit die deterministische Auffindbarkeit — entfällt (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-7c).
|
||||
|
||||
## Abgrenzung der Architektur-States
|
||||
|
||||
Die Trennung `raw/` (immutable Evidenz) vs. `wiki/` (kuratiertes Bundle) ist dasselbe Prinzip, das das Root-Concept [Wissensarchitektur: Source Material, Curated Knowledge & Consumer](../wissensarchitektur-trennung-states.md) beschreibt (übernommen aus wissensarchitektur-trennung-states auf Basis von raw/architecture-spine/architecture-spine-2026-08-14.md, nicht eigenständig belegt). Die inkrementelle Kompilation verarbeitet neue Sources gegen das bestehende kuratierte Wissen ([Knowledge Compilation & Inkrementelle Evolution](../knowledge-kompilation-inkrementell.md); übernommen aus knowledge-kompilation-inkrementell auf Basis von raw/architecture-spine/architecture-spine-2026-08-14.md, nicht eigenständig belegt) — die Bereichszuordnung ist der deterministische Schritt, der dabei einem neuen Thema seinen kanonischen Ort gibt (raw/architecture-spine/architecture-spine-2026-08-14.md#AD-7c).
|
||||
Reference in New Issue
Block a user