ED03 - Tagebuch-Format: JSON-Artifacts, temporale Signatur, V7GUID, Sidecars

Problem

Ein Unternehmer will sein Tagebuch in Git führen - aber wie genau sieht ein Eintrag technisch aus? Die heutige Praxis kennt keine verbindliche Antwort:

• Freitext-Notizen in Markdown, Word oder Papier - nicht maschinenlesbar, nicht schemavalidiert, nicht nachvollziehbar
• Excel-Zeilen mit Datum, Tätigkeit, Stunden - nicht versioniert, nicht kryptographisch verankert, nicht revisionssicher
• Lohnsoftware-Exporte als PDF - nicht maschinell auswertbar (§ 147 Abs. 6 AO), nicht retrograd/progressiv nachverfolgbar
• Keine eindeutige Identität - jeder Eintrag hat einen Dateinamen, aber der Dateiname kann sich ändern; die Identität des Eintrags ist nicht stabil
• Keine temporale Verankerung - das Datum steht als String im Dokument, aber wer hat wann wirklich erfasst? Die Erfassungszeit ist nicht kryptographisch mit der Identität verknüpft

Kernaussage

Ein GitCover-Tagebucheintrag ist ein JSON-Artifact mit:

1. JSON-Schema-First - das Schema existiert vor dem Eintrag; der Eintrag wird gegen das Schema validiert (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - klassifiziert das Dokument/die Action anhand der .gitcover Registry (was/welcher Typ); dient der Ablage-Organisation und DB-Query (z. B. EF Core in Vertical App)
3. uuidV7 (Object ID) - ist bereits allein die eindeutige Identität (DocID) des Eintrags, RFC 9562 §5.7, generiert aus einer vorgegebenen Zeitmarke (oder now()) via GitCover Helper (gc-v7guid), Rest mit Zufall aufgefüllt
4. Composite Key V7GUID:uuidV7 - der GCPN Sidecar Composite Key, dient Ablage-Organisation und Query; die Erfassungszeit steckt in der uuidV7 (48-Bit-Zeitstempel), kein separates datetime/date-Feld
5. Sidecar-Pflicht - jeder Beleg erhält einen .gc.md-Sidecar mit eigener uuidV7 (Klassifizierungsakt) und der uuidV7 des Dokuments
6. Retrograde/progressive Nachverfolgbarkeit - vom Buchungssatz → Beleg → Tagebucheintrag → uuidV7 und zurück auflösbar

Compliance by Design: Das Format ist nicht nachträglich - es ist strukturell. Schema, V7GUID (Class), uuidV7 (Object) und Sidecar sind Pflichtfelder, ohne die ein Eintrag nicht ins Repo aufgenommen wird.

Kein redundantes datetime/date: Die Erfassungszeit ist in der uuidV7 selbst verankert (48-Bit-Zeitstempel, RFC 9562 §5.7). Eine separate String-Darstellung in JSON-Schemata oder JSON-Daten ist redundant und wird nicht in den Fakten geführt. String-Darstellung für DTO/HTMX-Transfer ist Harness-Verantwortung, nicht Fakten-Ebene.

Der Tagebucheintrag als Compliance-Knoten

Der technische Eintrag ist kein Selbstzweck. Er ist der zeitliche Knoten, an dem mehrere Nachweisketten zusammenlaufen:

Die Diary-SSoT sagt, nach welcher Agenda gearbeitet wurde. Ur-Docs, Sidecars, GCPN und Grundbuch-/Abrechnungsartefakte liefern die dazugehörigen Belege. Diese Trennung verhindert zwei Fehler: Ein Diary-Eintrag wird nicht als Ersatz für einen externen Beleg missverstanden, und ein später zusammengesuchter Beleg wird nicht fälschlich als zeitnaher Arbeitsnachweis ausgegeben.

Das JSON-Schema (Schema-First)

Das Schema existiert vor dem Eintrag - es wird im .gitcover/schemas/diary-entry-1.0.schema.json abgelegt und ist versioniert. Ein Eintrag ohne Schema-Referenz ($schema) wird vom Pre-Commit-Hook abgelehnt.

Schema diary-entry-1.0.schema.json (vereinfacht)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gitcover.org/schemas/diary-entry-1.0.schema.json",
  "title": "GitCover Diary Entry v1.0",
  "type": "object",
  "required": [
    "$schema", "V7GUID", "docUid",
    "author", "role", "tenant", "sphere", "source"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "const": "https://gitcover.org/schemas/diary-entry-1.0.schema.json"
    },
    "V7GUID": {
      "type": "string",
      "description": "Class Identifier - klassifiziert das Dokument/die Action aus .gitcover Registry (was/welcher Typ)"
    },
    "docUid": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Object ID - RFC 9562 §5.7 UUIDv7, generiert aus vorgegebener Zeitmarke (nicht now()), 48-Bit-Zeitstempel in der GUID verankert"
    },
    "author": { "type": "string", "description": "Akteur-Platzhalter, z. B. E1" },
    "role": {
      "type": "string",
      "enum": ["GF", "Buchhalter", "Lohnverantwortlicher", "F&E-Leiter", "Administrator"]
    },
    "tenant": { "type": "string", "description": "Tenant-Platzhalter, z. B. ORG-1" },
    "sphere": {
      "type": "string",
      "enum": ["ideell", "vermögensverwaltend", "zweckbetrieblich", "wirtschaftlich", "n/a"]
    },
    "source": {
      "type": "string",
      "enum": ["E1", "StB", "Notar", "Bank", "DRV", "FA", "BA", "VBG", "KK", "auto"]
    },
    "source_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "SHA-256 des referenzierten Belegs (eindeutige Beleg-ID)"
    },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Wichtig - kein datetime/date-Feld: Die Erfassungszeit steckt in der uuidV7 (48-Bit-Zeitstempel, RFC 9562 §5.7). Eine separate String-Darstellung ist redundant und wird nicht in den Fakten geführt. Die uuidV7 allein ist die eindeutige DocID; der Composite Key V7GUID:uuidV7 dient der Ablage-Organisation und DB-Query.

V7GUID - Aufbau und 48-Bit-Zeitstempel

Kernprinzip: Die 48-Bit-Zeitstempel-Komponente (Bits 0–47) ist autoritativ für die Erfassungszeit. Sie ist in der uuidV7 selbst verankert und kann nicht nachträglich geändert werden, ohne die GUID ungültig zu machen. Ein separates datetime-Feld existiert nicht - die Zeit steckt in der uuidV7. String-Darstellung für DTO/HTMX ist Harness-Verantwortung.

GitCover-Erweiterung: Hierarchie und Prozess-IDs in Bits 66–127

Die GitCover-V7GUID-Spezifikation (work/OSS/TOP/.gitcover/specs/v7guid/) erweitert die 62-Bit-Zufallskomponente (Bits 66–127) um eine 6-Level-Hierarchie und Prozess-IDs - das ist die patentgeschützte Erweiterung (DPMA Az. 10 2025 003 091.6):

Hinweis: Diese Erweiterung ist für die Tagebuch-Serie nicht zwingend erforderlich - sie wird in ED02 (Tenant/Sphäre/Rolle) und späteren Artikeln (Harness) relevant. Hier genügt die RFC-9562-Basis mit 48-Bit-Zeitstempel.

Helper-Routinen: V7GUID aus Fremd-Keys erstellen

Das GitCover-OSS-Werkzeug gc-v7guid (work/OSS/gc-v7guid) stellt die Operationen bereit:

gen — UUIDv7-Objekt-IDs erzeugen

# n Objekt-IDs mit vorgegebener Zeitmarke (nicht now()) und Zufalls-Tail (RFC 9562)
gc-v7guid gen 1 --ts 2026-08-15T09:00:00Z
# Ausgabe: 01a17e18-c662-7874-9e1c-85d47895304f

gen-doc — deterministisch aus Dokument-Metadaten

# Dokumentgebundene ID aus Zeitmarke + SHA-256 des Ur-Dokuments
gc-v7guid gen-doc --ts 2026-08-15T09:00:00Z --doc-sha256 <64-hex>

decode — Zeitstempel und Struktur aus uuidV7 extrahieren

gc-v7guid decode 019f2c6f-0900-7000-8000-000000000000
# Ausgabe: unix_ms, utc (ISO-8601), version=7, variant=2, rfc9562

Fremd-Key → uuidV7

Die Helper-Routinen erlauben, aus einem Fremd-Key (z. B. eine Zeitmarke im Dateinamen wie 260815_0900_Lohnabrechnung.pdf) einen gültigen uuidV7-Schlüssel zu erstellen - mit vorgegebener Zeitmarke, nicht now():

1. Fremd-Key parsen - 260815_0900 → 2026-08-15T09:00:00Z
2. 48-Bit-Zeitstempel berechnen - Unix-Millisekunden seit Epoch
3. uuidV7 generieren - Guid.CreateVersion7() mit explizitem Zeitstempel, Rest mit Zufall
4. Composite Key - V7GUID (Class aus Registry) : uuidV7 (Object mit Zeitmarke)
5. GoBD-Dokumentation - zeitnahe Erfassung nachvollziehbar verankert (kein separates datetime-Feld)

GoBD-Bezug: Die zeitnahe Erfassung (GoBD Rz. 146) wird durch den 48-Bit-Zeitstempel in der uuidV7 kryptographisch dokumentiert - nicht nur behauptet. Der Zeitstempel ist Teil der Identität, nicht nachträglich änderbar.

Sidecar-Struktur (.gc.md)

Jeder Beleg erhält einen Sidecar mit zwei uuidV7 Bezügen:

Sidecar-Beispiel

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-2.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "docUid": "019f2c6f-0900-7001-8000-000000000001",
  "sha256": "ab94670c0dd8499c27ef2feddd1d9c5925977d55a52150a6fca0f6567d2e5e79",
  "title": "260815_Lohnabrechnung.pdf",
  "original_filename": "260815_Lohnabrechnung.pdf",
  "locations": [
    {
      "unc_path": "./ORG-1/sources/lohn/260815_Lohnabrechnung.pdf",
      "from": "260815",
      "to": null,
      "note": "Primärspeicherort"
    }
  ],
  "v7g_taxonomy": [
    {
      "v7guid": "019f2c6f-0900-7000-8000-000000000000",
      "taxonomy": "ORG-1/Lohn",
      "valid_from": "260815",
      "valid_to": null,
      "note": "Tenant: ORG-1, Category: Lohn, Sphäre: ideell"
    }
  ],
  "gcpn": {
    "prima_nota_ref": null,
    "journal_entry_ref": null
  },
  "obsolescence": {
    "status": "active",
    "superseded_by": null,
    "superseded_at": null
  }
}

Composite Key V7GUID:uuidV7:

• V7GUID (Feld 1) - Class Identifier des Sidecars (Klassifizierung aus .gitcover Registry: was/welcher Typ)
• uuidV7 (Feld 2) - Object ID des Sidecars selbst, generiert mit vorgegebener Zeitmarke (wann wurde klassifiziert?), 48-Bit-Zeitstempel in der GUID verankert
• v7g_taxonomy[].v7guid - Object ID des klassifizierten Dokuments (welches Dokument wird klassifiziert?)
• sha256 - Identität des klassifizierten Originaldokuments — der Beweis für Originalität, immer und überall (auch wenn das Dokument wandert: pfad-/namensunabhängig, aus dem Inhalt berechnet)

So ist nicht nur das Dokument eindeutig identifiziert (über seinen SHA-256), sondern auch der Klassifizierungsakt selbst - inklusive Zeitpunkt (in uuidV7), wer klassifiziert hat und in welcher Rolle. Kein separates datetime-Feld - die Zeit steckt in den uuidV7-Werten.

Retrograde und progressive Nachverfolgbarkeit

GoBD-Bezug: Die retrograde Nachverfolgbarkeit entspricht GoBD Rz. 146 (Nachvollziehbarkeit). Die progressive Nachverfolgbarkeit entspricht GoBD Rz. 147 (Prüfbarkeit). Beide sind by Design durch uuidV7 + SHA-256 gewährleistet - nicht durch manuelle Querverweise.

Zeit-Erfassung im Tagebuch

Jeder Tagebucheintrag enthält eine Zeit-Erfassungstabelle:

Spaltenregel: Die Spalte Zweck trägt ausschließlich das FuE-Vorhaben (FZul1, FZul2, …). Nicht-FuE-Arbeit steht als Verwaltung (Sphäre/Kategorie) mit Zweck —. Jede FZul-Stunde gehört genau einem Vorhaben (§ 7 FZulG).

FZul-Bezug: Die Zeit-Erfassung ist die Grundlage für FZul-Stundennachweise (ED29). Die Trennung F&E vs. Verwaltung erfolgt über die Spalte Zweck je Zeitzeile - nicht allein über das role-Feld des Eintrags. Die role beschreibt die Funktion des Handelnden (siehe unten), nicht die Förder-Zuordnung.

Erfassung ist vollständig - Deckelung erst bei der Abrechnung

Das Tagebuch erfasst die tatsächlich geleistete Arbeitszeit vollständig und ohne Obergrenze - auch dann, wenn sie über einer förderrechtlichen Wochengrenze (z. B. 40 Stunden je Woche und Person) liegt. Eine solche Grenze ist ein Berechnungsfaktor in der Wochensumme und der Förderermittlung, kein Limit der einzelnen Zeitzeile: Keine Zeile wird gekappt, gekürzt oder umgebucht, nur weil eine Grenze erreicht wäre. Die vollständige Erfassung ist Voraussetzung für die Plausibilität des Tagebuchs und die Belastbarkeit der Nachweiskette. Umgruppierungen zwischen Vorhaben und Verwaltung sind Abrechnungs-/Projektionsfragen, keine Korrekturen am Beleg.

Der Tageslauf: Beleg zuerst, Buchung später

Ein Tagebuch-Tag hat einen festen Ablauf. Erfassung (Beleg) und Abrechnung/Buchung sind strikt getrennt:

Abgrenzung: Die FZul-/Sphären-Angabe im Tagebuch ist ein Beleg-Feld. Sie ist unabhängig von jedem Bescheinigungsvorbehalt und erzeugt keine Buchung. Das Tagebuch ist der Nachweis; gebucht wird im Ledger, gewichtet in den Projektionen. Dasselbe Prinzip gilt für Belege: Ein Beleg belegt, die Buchung kommt später und separat.

Rollen im Tagebuch - Person, Funktion, Partei, Ausführung

Das role-Feld ist nicht die Person. Für ein belastbares Rollenverständnis unterscheidet GitCover fünf Ebenen, die auch dann getrennt bleiben, wenn dieselbe Person alles in einem Zug erledigt (typisch für KMU):

Eine Person kann mehrere Funktionen und mehrere Signaturhandlungen am selben Dokument haben - etwa als Geschäftsführer zweier Gesellschaften. Daraus entstehen weder mehrere Personen noch zwingend mehrere Konten oder Schlüssel. Die Rollen dürfen aber nicht allein deshalb zusammenfallen, weil Person oder Credentials identisch sind: Jede Signaturhandlung bindet Dokumentfassung + Person + Funktion + vertretene Partei + ausdrücklich abgedeckte Zustimmung. Eine gemeinsame Rückfrage an die Person darf mehrere Funktions-Zeichnungen abdecken, wenn die abgedeckten Funktionen ausdrücklich benannt sind; sie ersetzt keine dokumentbezogene Freigabe. Details: DS03 - Signatur-Vorgang und DS13 - Beteiligten-Schichtung.

Ehrliche Grenze: Diese Trennung ist als Anforderung und Datenmodell beschrieben. Eine durchgängig technisch erzwungene Bindung von Person, Funktion, Partei und Zustimmung (insbesondere Rollen-Claims aus dem Identity-Provider bis in die Signatur-Events) ist Gegenstand laufender Entwicklung und noch nicht überall umgesetzt.

Arbeit mit Agenten im Tagebuch

Setzt der Unternehmer KI-Agenten ein, gilt: Steuerung, Anweisung, Überwachung und Validierung der Agenten sind Einsatz von Arbeitsmitteln durch die handelnde Person - die erfasste Zeit ist die Zeit der Person. Das Tagebuch führt keine eigene Kategorie „Agenten-Zeit" und verlangt keine „Überlappungs"-Bestätigungen, wenn Tätigkeiten parallel laufen. Stattdessen:

• je Tätigkeit/Vorhaben eigene Zeilen;
• bei Tätigkeiten außerhalb der FuE-Förderung (insbesondere Werkzeug- und Agenten-Entwicklung) zusätzlich: welcher Akteur bzw. Agent mit welcher wirksamen Ausführungsidentität gehandelt hat - ohne Geheimnisse (Tokens, Schlüssel) offenzulegen.

Eine Förderfähigkeit ergibt sich nicht aus dem Agenteneinsatz, sondern aus der Frage, ob die Tätigkeit eine offene technische Forschungsfrage betrifft (Abgrenzung im jeweiligen Vorhaben).

Was im Git-Repo landet - und was nicht

Wichtig: Nur strukturierte Artefakte (JSON, Sidecars, Belege, Schemata, Dictionaries) werden ins Git-Repo aufgenommen. Private Dokumente werden nie ins Repo aufgenommen, sofern sie nicht ausdrücklich als Artefakt eingeführt und klassifiziert wurden. Das ist eine Datenschutz- und Compliance-Anforderung (DSGVO, GoBD).

Risiko-Leverage

Harness-Anforderung (Vorschau)

Aus ED03 ableitbar:

Die vollständige Anforderungsliste in Harness-Anforderungen.md.

Quellen

• RFC 9562 §5.7 (UUIDv7) - 48-Bit Unix-ms-Zeitstempel
• V7GUID-Spezifikation - work/OSS/TOP/.gitcover/specs/v7guid/ (normativ)
• DPMA Az. 10 2025 003 091.6 - V7GUID-Patent (Hauptanspruch 2, Ansprüche 5–8)
• GitCover OSS Tool gc-v7guid - work/OSS/gc-v7guid (Helper gen/decode)
• GoBD (BMF-Schreiben, Rz. 146 - Nachvollziehbarkeit, Rz. 147 - Prüfbarkeit)
• AO (§ 147 Abs. 2 - "maschinell auswertbar", § 147 Abs. 6 - Datenzugriff)
• E1/agents/ (anonymisiert) - SSoT-Konzept mit JSON-Artifacts, Sidecars

Quellen-Topologie und CDN-Referenz-Links

Hinweis: Diese Zuordnung von Quellen, Mirror und Community-Hub spiegelt den aktuellen Stand wider und kann sich ändern. Bitte prüfen Sie die jeweilige kanonische Quelle auf gitcover.org für den aktuellen Zustand.