# Anweisungen für die Wissensdatenbank ## 1. Zweck und Grundidee Das Wiki ist eine persistente, von Agenten gepflegte Abstraktions- und Wissensschicht zwischen den detaillierten Quellen und dem Benutzer. Es ist kein bloßer Dateikatalog: Neue Informationen werden in den vorhandenen Wissensbestand integriert, verlinkt, mit bestehenden Aussagen abgeglichen und bei Bedarf zu einer weiterentwickelten Synthese verdichtet. Der Benutzer kuratiert Quellen, setzt Schwerpunkte und stellt Fragen. Der Agent übernimmt das Lesen, Zusammenfassen, Strukturieren, Verlinken, Aktualisieren und Prüfen des Wikis. Das Wiki MUSS: - für Menschen ohne Spezialwerkzeuge lesbar sein, - für Agenten und einfache Programme zuverlässig auswertbar sein, - in Git sinnvoll diffbar und langfristig portabel bleiben, - Herkunft, Vertrauensstatus, Aktualität und Lebenszyklus von Wissen sichtbar machen, - mit jeder verarbeiteten Quelle und jeder relevanten Analyse an Wert gewinnen. ## 2. Zuständigkeiten und Grenzen ### 2.1 Drei Schichten 1. **Quellen** enthalten den höchsten verfügbaren Detailgrad. Gewöhnliche Rohquellen werden inhaltlich nicht verändert. Sie dürfen nur bei einer ausdrücklich beauftragten Quellenbereinigung und nach vollständigem Redundanznachweis gelöscht werden. Entscheidungsquellen unter `sources/decisions/` werden vom Agenten angelegt, geändert oder gelöscht. 2. **Wiki** enthält die vom Agenten erzeugten und gepflegten Markdown-Seiten. Der Agent darf diese Schicht im Rahmen der aktuellen Aufgabe bearbeiten. 3. **Anweisungen** bestehen aus `AGENTS.md` und dieser Datei. Änderungen daran erfolgen nur auf ausdrücklichen Wunsch des Benutzers. ### 2.2 Standardpfade Sofern das Zielprojekt keine andere Struktur vorgibt, gelten: ```text sources/ # detaillierte Quellen decisions/ # vom Agenten verwaltete Entscheidungsquellen log.md # knappes Entscheidungsprotokoll wiki/ # Knowledge Bundle index.md # Inhaltskatalog log.md # chronologisches Änderungsprotokoll .source-manifest.json # Verarbeitungszustand der Rohquellen / index.md # optionaler lokaler Katalog .md ``` Vorhandene abweichende Projektpfade haben Vorrang. Der Agent MUSS sie zunächst ermitteln und darf nicht parallel eine zweite Struktur anlegen. Pfade, die in dieser Datei mit `/` beginnen, sind relativ zur Wurzel des Knowledge Bundles, nicht zum Dateisystem. ### 2.3 Schreibregeln - Inhalte gewöhnlicher Rohquellen sind unveränderlich. Eine gewöhnliche Quelle darf nur im Bereinigungsablauf aus Abschnitt 8.5 gelöscht werden. - Unter `sources/decisions/` darf der Agent Entscheidungsquellen anlegen, ändern und löschen. Die Struktur richtet sich nach dem Projektkontext und bleibt so klein wie sinnvoll. - Jede neue, geänderte oder zurückgenommene Entscheidung wird zusätzlich in `sources/decisions/log.md` als knapper Stichpunkt im Stil einer Commit-Message unter einer ISO-Datumsüberschrift protokolliert: eine einzeilige Handlungszusammenfassung im Imperativ ohne abschließenden Punkt, zum Beispiel `SQLite durch PostgreSQL ersetzen`. Dieses Log bleibt abgesehen von sachlichen Korrekturen append-only und wird nicht gelöscht. - Wiki-Seiten sind vom Agenten verwaltet; manuelle Änderungen des Benutzers werden dennoch als absichtlich behandelt und nicht ohne Grund überschrieben. - Eine Änderung MUSS den gesamten betroffenen Wissenszusammenhang berücksichtigen, nicht nur eine einzelne Seite. - Unbelegte Details dürfen nicht ergänzt werden. - Fehlende Information wird als Wissenslücke benannt, nicht erraten. - Bei widersprüchlichen Quellen werden beide Positionen mit Provenienz und zeitlichem Kontext dokumentiert. Der Widerspruch darf nicht stillschweigend aufgelöst werden. ### 2.4 Quellenmanifest `wiki/.source-manifest.json` hält fest, welche Dateien aus `sources/` bereits mit welchem Inhalt verarbeitet wurden. Das Manifest wird mit dem Wiki in Git versioniert, damit alle Beteiligten denselben Verarbeitungsstand verwenden. Es ist Betriebsmetadatum und keine OKF-Konzeptseite; es wird nicht in `index.md` aufgenommen. Für jede Quelldatei speichert das Manifest mindestens: - den Pfad relativ zu `sources/`, - den aktuellen SHA-256-Inhaltshash, - Dateigröße und `mtime_ns` als schnellen Vorfilter, - den Status `pending`, `processed`, `missing` oder `removed`, - bei verarbeiteten Dateien `processed_sha256`, `processed_at` und `processor_version`. Der SHA-256-Hash entscheidet, ob sich der Inhalt geändert hat. Größe und Änderungszeit dürfen nur verwendet werden, um eine unnötige erneute Hash-Berechnung zu vermeiden. Stimmen sie mit dem Manifest überein, darf der gespeicherte Hash wiederverwendet werden. Weichen sie ab, MUSS der Inhalt neu gehasht werden. Ein regelmäßiger oder ausdrücklich verlangter vollständiger Scan MUSS alle Hashes unabhängig von den Metadaten neu berechnen können. Statusbedeutung: - `pending` — neu, inhaltlich geändert oder unter einem neuen Pfad entdeckt; die Quelle muss noch in das Wiki integriert werden. - `processed` — der aktuelle Hash entspricht `processed_sha256`; genau dieser Inhalt wurde erfolgreich integriert. - `missing` — die zuvor bekannte Quelldatei ist nicht mehr vorhanden. Daraus dürfen Wiki-Inhalte nicht automatisch gelöscht werden. - `removed` — eine absichtlich gelöschte Quelle, deren Auswirkungen bereits vollständig im Wiki verarbeitet wurden. Der Eintrag bewahrt Hash, Löschzeitpunkt, Grund und gegebenenfalls ersetzende Quellen. Taucht die Quelle erneut auf, wird sie wieder `pending`. Eine Quelle darf erst nach vollständig erfolgreichem Ingest auf `processed` gesetzt werden. Schlägt die Verarbeitung fehl oder ist sie nur teilweise abgeschlossen, bleibt sie `pending`. Änderungen an Zeitstempel oder Dateigröße ohne Inhaltsänderung lösen keinen erneuten Ingest aus. Bei Umbenennungen soll der frühere Pfad festgehalten werden, damit Provenienz und Links gezielt angepasst werden können. Eine fehlende Quelle darf erst nach der entsprechenden Wiki-Aktualisierung als `removed` bestätigt werden. Bei gewöhnlichen Quellen setzt dies eine ausdrücklich beauftragte Bereinigung und einen vollständigen Redundanznachweis voraus; andernfalls bleiben sie `missing`. Nach der vollständigen Verarbeitung einer absichtlich gelöschten Entscheidungsquelle wird sie bestätigt mit: ```bash python3 /scripts/source_manifest.py \ mark-removed \ --reason "" \ --replacement ``` Ändert sich die Ingest-Logik wesentlich, wird `processor_version` erhöht. Unveränderte Quellen mit einer älteren Prozessorversion werden nicht automatisch erneut verarbeitet; der Agent meldet sie bei einer entsprechenden Migration und verarbeitet sie nur nach Auftrag oder wenn die neue Logik dies zwingend erfordert. ## 3. Format: Open Knowledge Format 0.2 Das Verzeichnis `wiki/` ist ein Knowledge Bundle nach Open Knowledge Format (OKF) v0.2. Es besteht aus UTF-8-Markdown-Dateien mit YAML-Frontmatter. ### 3.1 Reservierte Dateien Die Namen `index.md` und `log.md` sind auf jeder Verzeichnisebene reserviert und dürfen nicht für Konzeptseiten verwendet werden. Alle anderen Markdown-Dateien im Bundle sind Konzeptseiten. Jede Konzeptseite MUSS: 1. mit einem durch `---` begrenzten, parsebaren YAML-Frontmatter beginnen und 2. dort ein nicht leeres Feld `type` enthalten. Unbekannte Frontmatter-Felder und unbekannte `type`-Werte sind zulässig und müssen beim Überarbeiten nach Möglichkeit erhalten bleiben. ### 3.2 Konzept-IDs und Dateinamen Die Konzept-ID ist der Pfad einer Datei relativ zur Bundle-Wurzel ohne die Endung `.md`. Dateinamen SOLLEN: - kurz, stabil und beschreibend sein, - `kebab-case` verwenden, - keine Datums- oder Versionsnummer enthalten, sofern diese nicht Teil des fachlichen Konzepts sind, - nicht allein aufgrund einer Titeländerung umbenannt werden. Pro dauerhaftem Konzept SOLL genau eine kanonische Seite existieren. Ähnliche Seiten werden zusammengeführt oder klar voneinander abgegrenzt. ### 3.3 Frontmatter einer Konzeptseite Minimal: ```yaml --- type: Concept --- ``` Empfohlener Standard: ```yaml --- type: Concept title: Anzeigename description: Ein präziser Satz, der Inhalt und Nutzen der Seite zusammenfasst. tags: [tag-a, tag-b] status: stable generated: by: / at: 2026-07-25T12:00:00Z sources: - id: stabile-quellen-id resource: /references/beispiel.md title: Bezeichnung der Quelle --- ``` Felder: - `type` — **verpflichtend**. Kurzer, selbsterklärender Konzepttyp, zum Beispiel `Person`, `Organization`, `Event`, `Concept`, `Source Summary`, `Comparison`, `Synthesis`, `Decision`, `Playbook`, `Reference`, `Metric` oder `Attested Computation`. - `title` — empfohlener Anzeigename. Fehlt er, darf er aus dem Dateinamen abgeleitet werden. - `description` — empfohlene Ein-Satz-Zusammenfassung für Index, Suche und Vorschau. - `resource` — optionale kanonische URI des beschriebenen externen oder technischen Objekts. - `tags` — optionale Liste kurzer, konsistent wiederverwendeter Begriffe. - `sources`, `generated`, `verified`, `status` und `stale_after` — siehe folgende Abschnitte. Zusätzliche domänenspezifische Felder sind erlaubt. Sie SOLLEN nur eingeführt werden, wenn sie wiederholt nützlich sind und konsistent gepflegt werden können. ### 3.4 Inhalt Der Body ist Standard-Markdown. Aussagekräftige Überschriften, Listen, Tabellen und Codeblöcke sind langen unstrukturierten Texten vorzuziehen. Eine Seite soll das Konzept erklären, nicht bloß die Quelle nacherzählen. Diese Überschriften haben konventionelle Bedeutung und werden verwendet, wenn sie passen: - `# Summary` — kompakte Kernaussage, - `# Details` — strukturierte Vertiefung, - `# Relationships` — fachlich erklärte Verbindungen zu anderen Konzepten, - `# Open Questions` — Wissenslücken und ungeklärte Widersprüche, - `# Schema` — Felder oder Spalten eines technischen Assets, - `# Examples` — konkrete Anwendungsbeispiele, - `# Computation` — autorisierte Berechnung eines `Attested Computation`. Leere Standardschablonen und Überschriften ohne Inhalt sind zu vermeiden. ## 4. Provenienz und Quellenbezug ### 4.1 `sources` `sources` dokumentiert, aus welchen internen oder externen Materialien der aktuelle Inhalt abgeleitet wurde: ```yaml sources: - id: ga4-schema resource: https://developers.google.com/analytics/bigquery/export-schema title: GA4 BigQuery Export schema author: team:ga4-docs usage_count: 5000 last_modified: 2026-05-30 usage_window: from: 2026-06-01 to: 2026-06-30 ``` Für jeden Eintrag gilt: - `resource` ist innerhalb des Eintrags verpflichtend. Zulässig sind absolute URLs, bundle-relative Pfade, relative Pfade oder ausdrücklich formulierte Umfangsbeschreibungen. - `id` ist eine stabile, innerhalb der Seite eindeutige Kennung. Sie ist erforderlich, sobald einzelne Aussagen auf die Quelle verweisen. - `title` ist eine lesbare Bezeichnung. - `author`, `usage_count` und `last_modified` sind optionale objektive Glaubwürdigkeitssignale, keine Bewertung. - Ein gemeinsames `usage_window` gilt für alle `usage_count`-Werte; ein einzelner Quelleneintrag darf es überschreiben. Der Agent darf aus diesen Signalen keine scheinbar objektive Glaubwürdigkeitszahl erzeugen. `usage_count` zeigt Nutzung und Lebendigkeit, nicht automatisch Qualität. ### 4.2 Zuschreibung einzelner Aussagen Konkrete, überprüfbare oder strittige Aussagen SOLLEN mit Markdown-Fußnoten belegt werden. Das Fußnotenlabel entspricht exakt einer `sources[].id`: ```markdown Die Tabelle wird täglich partitioniert.[^ga4-schema] [^ga4-schema]: GA4 BigQuery Export schema ``` Die Quellenliste im Frontmatter ist maßgeblich. Eine zusätzliche pauschale `# Citations`-Liste soll für neue Seiten nicht verwendet werden. ### 4.3 Interne und externe Quellen - Links zu anderen Wiki-Konzepten drücken Beziehungen aus. - Ein Eintrag in `sources` drückt Ableitung oder Beleg aus. - Ist eine Aussage aus einer anderen Wiki-Seite abgeleitet, darf deren bundle-relativer Pfad als `sources[].resource` verwendet werden. - Externe Materialien können bei Bedarf unter `references/` als eigene Konzepte gespiegelt werden. Dies ist eine Konvention, keine Pflicht. - Lokale Quellenpfade bleiben auf die Quelldatei gerichtet; kopierte Zusammenfassungen gelten nicht als Ersatz für den Ursprung. Änderungen an Entscheidungsquellen werden über Manifest und Entscheidungs-Log nachvollziehbar gehalten. ## 5. Erzeugung, Verifikation und Vertrauen ### 5.1 `generated` `generated` beschreibt, wer den aktuellen Inhalt erstellt oder zuletzt inhaltlich wesentlich geändert hat: ```yaml generated: by: codex/gpt-5 at: 2026-07-25T12:00:00Z ``` - `generated.by` ist innerhalb von `generated` verpflichtend. - `generated.at` ist ein ISO-8601-Zeitpunkt der letzten inhaltlich wesentlichen Änderung. - Reine Formatkorrekturen müssen den Zeitpunkt nicht verändern. - Der Agent MUSS seine tatsächliche Identität verwenden und darf weder eine menschliche Prüfung noch einen anderen Produzenten vortäuschen. ### 5.2 `verified` `verified` enthält tatsächliche Prüfereignisse: ```yaml verified: - by: human:identifier at: 2026-07-25T12:30:00Z - by: process:nightly-check at: 2026-07-26T02:00:00Z ``` Eine einzelne Zuordnung ohne Listenschreibweise ist zulässig und wird wie eine Liste mit einem Element behandelt. Der Agent darf vorhandene Verifikationsereignisse nicht als weiterhin gültig darstellen, wenn eine inhaltliche Änderung die geprüfte Aussage betrifft. Er löscht historische Ereignisse nicht blind, sondern kennzeichnet den erneuten Prüfbedarf sichtbar; falls das Projekt keine Historisierung dafür vorsieht, entfernt er die durch die Änderung ungültig gewordene aktuelle Verifikation. Vertrauensstufen werden ausschließlich aus `verified` abgeleitet: - kein `verified` → **unverified**, - ausschließlich nicht-menschliche Prüfer → **machine-confirmed**, - mindestens ein `human:` → **human-reviewed**. Diese Stufen sind Hinweise, keine Zugriffskontrolle. Fehlende Vertrauensmetadaten machen eine Seite nicht ungültig. ### 5.3 Akteure - Agenten und Werkzeuge: `/` - Menschen: `human:` - automatisierte Prozesse: `process:` Nur eine tatsächlich von einem Menschen durchgeführte Prüfung darf mit `human:` eingetragen werden. ## 6. Lebenszyklus und Aktualität ```yaml status: stable stale_after: 2026-12-31 ``` Zulässige Statuswerte: - `draft` — unvollständig oder noch nicht geprüft, - `stable` — zur Nutzung vorgesehen; Standard, wenn `status` fehlt, - `deprecated` — nicht mehr aktuell, bleibt aber für Links und Historie erhalten. `stale_after` ist optional und enthält ein absolutes Datum im Format `YYYY-MM-DD`. Eine Seite ist ab diesem Datum veraltet. Der Agent MUSS veraltete Information bei Antworten kenntlich machen und soll sie bei einer Pflegeaufgabe gegen die Quellen prüfen. `deprecated` ist nicht gleichbedeutend mit Löschen: Die Seite soll auf ihren Nachfolger verweisen. ## 7. Verlinkung und Navigation ### 7.1 Links Standard-Markdown-Links verbinden Konzepte. Empfohlen sind bundle-relative Links, da sie gegenüber Verschiebungen der Quellseite stabiler sind: ```markdown Siehe [Kunden](/entities/customers.md). ``` Relative Links wie `../concepts/example.md` sind ebenfalls erlaubt. Der umgebende Text MUSS die Art der Beziehung erklären; ein bloßer Abschnitt mit unbeschrifteten Links reicht nicht. Defekte Links machen das Bundle nicht formal ungültig, sind aber bei einer Pflege- oder Lint-Aufgabe zu melden und möglichst zu reparieren. ### 7.2 `index.md` Ein `index.md` unterstützt progressive Offenlegung: Zuerst wird sichtbar, welche Inhalte existieren, bevor einzelne Seiten gelesen werden. Der Root-Index SOLL vorhanden und aktuell sein. Unterverzeichnisse mit mehreren Konzepten SOLLEN einen eigenen Index erhalten, sobald dies die Navigation verbessert. Nur der Root-Index darf Frontmatter tragen: ```yaml --- okf_version: "0.2" --- ``` Der Body gruppiert Einträge nach sinnvollen Kategorien: ```markdown # Concepts * [Concept title](concepts/concept-title.md) - Präzise Kurzbeschreibung. # Sources * [Source title](sources/source-title.md) - Inhalt und Relevanz der Quelle. ``` Index-Einträge übernehmen nach Möglichkeit `title` und `description` der Zielseite. Der Agent aktualisiert betroffene Indizes bei jeder Erstellung, Verschiebung, Umbenennung, Deprecation oder wesentlichen Änderung. ### 7.3 `log.md` Das Root-`log.md` ist ein chronologisches, append-only Änderungsprotokoll mit dem neuesten Datum zuerst: ```markdown # Wiki Update Log ## 2026-07-25 * **Ingest**: Quelle [Titel](/sources/titel.md) aufgenommen und betroffene Konzepte aktualisiert. * **Update**: [Konzept](/concepts/konzept.md) anhand neuer Erkenntnisse überarbeitet. ``` Datumsüberschriften verwenden `YYYY-MM-DD`. Ein neuer Eintrag wird unter der vorhandenen Überschrift des Tages oder in einer neuen Überschrift direkt unter dem Dokumenttitel ergänzt. Vergangene Einträge werden nicht nachträglich umgeschrieben, außer um einen defekten Link oder einen sachlichen Fehler im Protokoll zu korrigieren. Das Log hält Ergebnisse und betroffene Seiten fest, nicht jeden internen Arbeitsschritt. Übliche Präfixe sind `Initialization`, `Ingest`, `Creation`, `Update`, `Decision`, `Query`, `Lint` und `Deprecation`. ## 8. Arbeitsabläufe ### 8.1 Allgemeine Vorbereitung Vor jeder Wiki-Aufgabe: 1. Diese Datei lesen. 2. Bundle-Pfad und Quellenpfad aus dem Projektbestand ermitteln. 3. Den Quellenbestand gegen `wiki/.source-manifest.json` scannen, wenn die Aufgabe neue oder geänderte Quellen betreffen kann. 4. Root-`index.md` und die jüngsten relevanten Einträge aus `log.md` lesen. 5. Relevante Seiten über Index, Links und Textsuche finden. 6. Den vorhandenen Wissensstand und seine Provenienz prüfen, bevor Dateien geändert oder Antworten formuliert werden. Der Index ist ein Einstieg, keine vollständige Wahrheitsquelle. Bei wichtigen Fragen werden die Konzeptseiten und, soweit nötig, die Originalquellen gelesen. ### 8.2 Ingest einer neuen Quelle Beim Aufnehmen einer Quelle: 1. Das Quellenmanifest aktualisieren und die Einträge mit Status `pending` sowie `missing` ermitteln. Bei einem normalen Sammel-Ingest nur `pending`-Quellen verarbeiten; bereits `processed` markierte Dateien nicht erneut lesen. 2. Sicherstellen, welche Quelldatei oder URL beauftragt wurde. Gewöhnliche lokale Rohquellen nicht verändern; Entscheidungsquellen nur gemäß Abschnitt 8.4 bearbeiten. Ein gezielter Benutzerauftrag für eine konkrete Quelle hat Vorrang vor der automatischen Auswahl. 3. Jede zu verarbeitende Quelle vollständig lesen. Bei eingebetteten Bildern, Tabellen oder Anhängen prüfen, ob sie für das Verständnis relevant sind, und sie bei verfügbaren Werkzeugen gesondert auswerten. 4. Kernaussagen, Entitäten, Begriffe, Beziehungen, Datenpunkte, zeitlichen Kontext, Unsicherheiten und Widersprüche identifizieren. 5. Bestehende Wiki-Seiten ermitteln, die betroffen sind. Nicht vorschnell für jede Erwähnung eine neue Seite erzeugen. 6. Bei sinnvoller Granularität eine Quellenzusammenfassung oder neue Konzeptseite erstellen. 7. Betroffene bestehende Seiten aktualisieren: neue Belege integrieren, Aussagen präzisieren, Querverweise ergänzen, überholte Aussagen korrigieren oder Widersprüche dokumentieren. 8. `sources`, `generated`, Status und gegebenenfalls `stale_after` korrekt pflegen. Einzelne wichtige Aussagen zuordnen. 9. Alle betroffenen `index.md`-Dateien aktualisieren. 10. Einen kompakten `Ingest`-Eintrag in `log.md` ergänzen. 11. Frontmatter, interne Links, Indexabdeckung und Konsistenz der geänderten Seiten prüfen. 12. Erst nach erfolgreichem Abschluss den aktuellen Hash der betreffenden Quelle mit Zeitpunkt und Prozessorversion als `processed` bestätigen. Eine Quelle darf viele bestehende Seiten verändern. Der Ingest ist erst abgeschlossen, wenn die Information in den Wissensgraphen integriert ist; eine isolierte Zusammenfassung allein genügt normalerweise nicht. Mehrere Quellen dürfen gemeinsam bestätigt werden, aber nur wenn jede einzelne vollständig integriert wurde. ### 8.3 Fragen an das Wiki Beim Beantworten einer Frage: 1. Über Index, Suche und Links die relevanten Seiten auffinden. 2. Provenienz, Verifikationsstatus, Aktualität und Widersprüche prüfen. 3. Für entscheidende oder unklare Aussagen bei Bedarf bis zu den Rohquellen zurückgehen. 4. Eine Synthese erstellen, statt Absätze lediglich zusammenzukopieren. 5. Quellennahe Aussagen mit Links auf Wiki-Seiten und, wenn erforderlich, Originalquellen belegen. 6. Unsicherheit, veraltete Information und abweichende Quellen offen benennen. Eine Antwort wird nicht automatisch im Wiki gespeichert. Wenn sie eine dauerhaft nützliche neue Synthese, einen Vergleich oder eine wiederverwendbare Analyse enthält und die Aufgabe Wiki-Änderungen einschließt, darf der Agent sie als Konzeptseite ablegen und muss dann Metadaten, Index, Querverweise und Log wie bei jeder anderen Änderung pflegen. Bei einer reinen Frage ohne Änderungsauftrag bleibt das Wiki unverändert. ### 8.4 Entscheidungen erfassen und korrigieren Eine vom Benutzer klar getroffene projektbezogene Entscheidung ist persistentes Wissen und MUSS ohne zusätzliche Aufforderung zuerst unter `sources/decisions/` im benötigten Detailgrad festgehalten und anschließend in das Wiki integriert werden. Das gilt ebenso, wenn der Benutzer eine vorhandene Entscheidung bestätigt, präzisiert, ersetzt, korrigiert oder zurücknimmt. Nicht in das Wiki gehören Meta-Entscheidungen: - Regeln zur allgemeinen Arbeitsweise des Agenten werden in `AGENTS.md` gepflegt. - Regeln zu Aufbau, Format, Pflege oder Arbeitsabläufen des Wikis werden in dieser Datei gepflegt. Eine Aussage gilt nur dann als Entscheidung, wenn der Benutzer sie erkennbar als verbindliche Wahl oder Korrektur formuliert. Bloße Ideen, Fragen, Vorschläge, hypothetische Varianten und noch offene Abwägungen werden nicht als beschlossen dokumentiert. Sie dürfen, wenn fachlich nützlich, als offene Frage oder Option gekennzeichnet werden. Beim Erfassen einer Entscheidung: 1. Bestehende Entscheidungsquellen, Wiki-Seiten und frühere Entscheidungen zum Thema ermitteln. 2. Unter `sources/decisions/` die kleinste passende Struktur verwenden und die betreffende Quelle anlegen, ändern oder löschen. Entscheidung, Geltungsbereich, bekannten Entscheidungsgrund und Konsequenzen im höchsten verfügbaren Detailgrad festhalten; fehlende Angaben nicht erfinden. 3. In `sources/decisions/log.md` unter dem aktuellen ISO-Datum einen knappen Stichpunkt im Stil einer Commit-Message ergänzen: einzeilig, imperativ und ohne abschließenden Punkt. Das Log protokolliert jede Entscheidung, Änderung und Rücknahme. 4. Das Quellenmanifest scannen. Neue und geänderte Entscheidungsquellen werden `pending`, gelöschte zunächst `missing`. 5. Die Entscheidung dort ins Wiki integrieren, wo ihre fachlichen Auswirkungen beschrieben werden. Ein `decisions/`-Ordner oder eine eigene Entscheidungsseite ist nicht vorgeschrieben; `type: Decision` wird nur für eigenständig relevante Entscheidungen verwendet. 6. Betroffene Konzept-, Architektur-, Prozess- oder Übersichtsseiten auf den gültigen Stand bringen und Provenienz, `generated`, Links und Indizes aktualisieren. 7. Den Root-Log mit einem `Decision`-Eintrag aktualisieren. Erst danach vorhandene Entscheidungsquellen als `processed` und absichtlich gelöschte Entscheidungsquellen als `removed` bestätigen. Erfassung, Manifestlauf und Wiki-Aktualisierung werden im selben Arbeitsauftrag abgeschlossen. Eine korrigierte Entscheidung wird nicht als gleichzeitig gültige Alternative stehen gelassen: - Die maßgeblichen Seiten werden auf den neuen gültigen Stand gebracht. - Die zugrunde liegende Entscheidungsquelle darf korrigiert oder gelöscht werden. Das Entscheidungs-Log hält die Änderung oder Rücknahme dauerhaft fest. - Frühere Wiki-Aussagen werden nur dann als abgelöst oder korrigiert gekennzeichnet, wenn ihr Verlauf für Begründung, Migration oder Nachvollziehbarkeit relevant ist. - Bei einer eigenen Entscheidungsseite kann der frühere Eintrag auf `status: deprecated` gesetzt und mit dem Nachfolger verlinkt werden. - Wurde die frühere Entscheidung lediglich falsch dokumentiert, wird der Fehler korrigiert; der Log-Eintrag hält die Korrektur knapp fest. ### 8.5 Redundante Quellen bereinigen Gewöhnliche Quellen werden nur auf ausdrücklichen Auftrag bereinigt. Ein neueres Datum oder eine höhere Versionsnummer genügt nicht als Redundanznachweis. Für jede Löschkandidatin: 1. Die Kandidatin und alle vorgesehenen Ersatzquellen vollständig lesen, einschließlich relevanter Tabellen, Bilder und Anhänge. 2. Einzelne Aussagen, Entitäten, Geltungsbereiche, Zeitbezüge, Unsicherheiten, Widersprüche und Provenienz vergleichen. 3. Nachweisen, dass jede materiell relevante Information der Kandidatin durch mindestens eine verbleibende Quelle abgedeckt ist. 4. Die Kandidatin behalten, sobald sie einzigartige Informationen, erhaltenswerte unabhängige Bestätigung, einen ungeklärten Widerspruch, benötigten historischen Kontext oder rechtlichen beziehungsweise revisionsbezogenen Wert enthält. 5. Wiki-Aussagen, Fußnoten und `sources`-Einträge auf die tatsächlich stützenden verbleibenden Quellen umstellen. Eine Ersatzquelle darf nur für Aussagen zitiert werden, die sie selbst belegt. 6. Erst danach die vollständig redundante Quelle löschen und das Manifest scannen. Der Löschvorgang erscheint zunächst als `missing`. 7. Im Root-Log einen knappen Eintrag mit Präfix `Source Cleanup` ergänzen und die Löschung mit Begründung und Ersatzpfaden als `removed` bestätigen. 8. Linter und Diff prüfen. Der Manifest-Tombstone bewahrt den letzten Hash, Löschzeitpunkt, Grund und die ersetzenden Quellen. Ist die Abdeckung nicht eindeutig, bleibt die Quelle erhalten und die ungeklärte Lücke wird gemeldet. Teilweise überholte Quellen werden nicht gelöscht, wenn sie weiterhin einzigartige Informationen zu einem anderen Gegenstand enthalten. ### 8.6 Lint und Pflege Eine Wiki-Prüfung untersucht mindestens: - fehlendes oder ungültiges YAML-Frontmatter, - fehlende oder leere `type`-Felder, - veraltete Seiten gemäß `stale_after`, - defekte interne Links und verwaiste Seiten, - Seiten, die im zuständigen Index fehlen, - veraltete oder widersprüchliche Aussagen, - Quellenangaben ohne passende Aussage oder Fußnoten ohne passende `sources[].id`, - wichtige erwähnte Konzepte ohne eigene Seite, - doppelte oder zu stark überlappende Seiten, - inkonsistente Titel, Tags, Typen und Dateinamen, - ungültig gewordene Verifikationshinweise, - fehlendes oder ungültiges `wiki/.source-manifest.json`, - `pending`-Quellen, die noch nicht integriert wurden, - `missing`-Quellen, deren Auswirkungen noch nicht geprüft wurden, - `removed`-Einträge ohne Löschgrund oder mit ungültigen Ersatzpfaden, - als `processed` markierte Einträge, bei denen aktueller und verarbeiteter Hash voneinander abweichen, - Wissenslücken, die eine neue Quelle oder Untersuchung rechtfertigen. Rein mechanische, eindeutig sichere Fehler dürfen im Rahmen eines beauftragten Lint-Durchlaufs behoben werden. Inhaltliche Konflikte, unklare Zusammenführungen oder fehlende Quellen werden als Befund dokumentiert und nicht durch Vermutungen „repariert“. Nach Änderungen werden Indizes und Log aktualisiert. ## 9. Umgang mit Änderungen und Konflikten - Neue Information überschreibt alte nicht allein deshalb, weil sie neuer ist. Autorität, Geltungsbereich, Methode und Zeitpunkt der Quellen sind gemeinsam zu bewerten. - Bei echtem Widerspruch nennt die Seite beide Aussagen, ihre Quellen und den ungeklärten Status. - Kann eine neuere Quelle eine frühere Aussage nachvollziehbar ablösen, wird der aktuelle Stand im Haupttext dargestellt; der Wechsel und seine Provenienz bleiben erkennbar. - Seiten werden bevorzugt weiterentwickelt statt dupliziert. - Beim Verschieben oder Umbenennen einer Seite werden alle internen Links, Quellenpfade und Indexeinträge angepasst. - Eine nicht mehr aktuelle, weiterhin referenzierte Seite wird auf `deprecated` gesetzt und verlinkt ihren Nachfolger. - Löschen ist nur angemessen, wenn eine Seite eindeutig irrtümlich oder redundant ist und keine erhaltenswerte Historie trägt. Vor dem Löschen sind eingehende Links zu ermitteln und anzupassen. ## 10. Attestierte Berechnungen Werte, für die eine vorgeschriebene Berechnung und überprüfbare Ausführung entscheidend sind, werden als eigenständige Seite mit `type: Attested Computation` modelliert. Erklärende Metrik- oder Berichtsseiten verlinken darauf. ### 10.1 Vertrag Zusätzlich zu den allgemeinen Feldern enthält die Seite: ```yaml --- type: Attested Computation title: Revenue for fiscal year runtime: bigquery parameters: - name: year type: integer required: true executor: resource: references/skills/run-on-bq.md receipt: [job_id, executed_sql, result] attester: resource: references/attesters/sql-equality.py --- ``` - `runtime` ist für diesen Typ verpflichtend und bestimmt Ausführungsumgebung und Parametersemantik. - `parameters` enthält ausschließlich die benannten, typisierten Werte, die ein Agent einsetzen darf. - `computation` kann auf eine separate Datei zeigen. Fehlt es, steht die Berechnung in genau einem Codeblock unter `# Computation`. - `executor.resource` beschreibt oder implementiert die Ausführung; `executor.receipt` legt die zurückzugebenden Nachweisfelder fest. - `attester.resource` verweist auf deterministischen, LLM-freien Prüfcode, der einen Receipt bewertet. Der Agent darf nur Werte für deklarierte Parameter liefern. Er darf die autorisierte Berechnung nicht spontan neu schreiben oder verändern. Definition und einzelne Ausführung sind getrennt: - `verified` bestätigt, dass die Definition weiterhin der fachlichen Vorgabe entspricht. - Die Attestierung bestätigt für einen einzelnen Lauf, dass genau die autorisierte, gebundene Berechnung ausgeführt wurde und das angezeigte Ergebnis dem Receipt entspricht. Fehlgeschlagene Attestierung MUSS sichtbar gemacht werden; ihr Ergebnis darf nicht als bestätigt ausgegeben werden. Ab `stale_after` muss mindestens gewarnt werden. ## 11. Konformität und Validierung Ein Bundle ist OKF-v0.2-konform, wenn: 1. jede nicht reservierte Markdown-Datei parsebares YAML-Frontmatter besitzt, 2. jedes Frontmatter ein nicht leeres `type` enthält und 3. vorhandene `index.md`- und `log.md`-Dateien ihren jeweiligen Strukturregeln folgen. Optionale Felder, unbekannte Typen, Erweiterungsfelder, fehlende Indizes und defekte Links dürfen einen Consumer nicht zum vollständigen Abbruch zwingen. Produzenten sollen diese Qualitätsmängel trotzdem vermeiden oder melden. Nach jeder schreibenden Wiki-Aufgabe prüft der Agent mindestens: - syntaktisch gültiges YAML und Markdown, - ein syntaktisch und strukturell gültiges Quellenmanifest, - vorhandenes `type` auf jeder geänderten Konzeptseite, - korrekte Pfade aller neu angelegten oder geänderten internen Links, - Übereinstimmung von Fußnotenlabels und `sources[].id`, - Aktualität der betroffenen Indizes, - einen passenden Eintrag im Root-Log, - korrekten `processed`-Status ausschließlich für vollständig integrierte Quellen, - einen plausiblen Diff ohne Änderungen am Inhalt gewöhnlicher Rohquellen, mit ausschließlich ausdrücklich autorisierten und nachweislich sicheren Quellenlöschungen sowie mit ausschließlich beabsichtigten Änderungen unter `sources/decisions/`. ## 12. Entscheidungsprinzipien Wenn diese Regeln eine Situation nicht ausdrücklich abdecken: 1. Wahrheit und nachvollziehbare Provenienz gehen vor Vollständigkeit. 2. Bestehendes Wissen integrieren geht vor dem Erzeugen neuer Dateien. 3. Explizite Unsicherheit geht vor einer erfundenen Gewissheit. 4. Stabile, einfache Markdown-Strukturen gehen vor Spezialwerkzeugen. 5. Lesbarkeit für Menschen und zuverlässige Verarbeitung durch Agenten sind gleich wichtig. 6. Die kleinste Struktur verwenden, die den aktuellen Bestand klar organisiert; zusätzliche Taxonomien und Werkzeuge erst einführen, wenn ein konkreter Bedarf besteht.