docs / concepts / git-model.md

Git-Modell für die Buchhaltung

Status: Autoritäres Kernkonzept von entrytwo.

entrytwo modelliert die gesamten Buchhaltungsdaten als Git-Repository der finanziellen Wahrheit.

Jede Änderung ist ein Commit.
Die Historie ist unveränderlich und vollständig auditierbar.
Du kannst branchen, um Szenarien zu erkunden oder die KI parallel arbeiten zu lassen.
Du kannst Vorschläge in die Hauptlinie der Wahrheit mergen.
Du kannst wichtige Zustände taggen (Monatsabschluss, Auditor-Snapshot).
Du kannst diffen, blamen, zu jedem früheren Punkt restoren.
Die KI ist ein First-Class-Contributor und kann bei hoher Konfidenz autonom Commits erzeugen.

Das ist nicht „KI schlägt vor, Menschen machen die echte Arbeit.“ Die langweilige, repetitive, fehleranfällige Bucharbeit erledigt die KI. Menschen geben Richtung, prüfen Ausnahmen und tragen das Ergebnis.

Produktziel: Du solltest keine Vollzeit-Buchhalterin nur brauchen, um die Bücher korrekt zu halten.

Exakte Git-zu-Buchhaltungs-Zuordnung

Git-Konzept	Buchhaltungs-Äquivalent	Hinweise
Commit	Journalbuchung (nach Erstellung unveränderlich)	Voller Payload + reiche Metadaten
Commit-Message + Author	Beschreibung + `createdBy` (Mensch oder „AI:<model>“) + Reasoning	Jeder Commit erklärt das Warum
Branch	Parallele Sicht der Realität (z. B. „ai-reconciliation-june“)	Mergebar oder verwerfbar
Merge	Übernahme von Buchungen/Vorschlägen in die Hauptbücher	Manuell oder bei hoher Konfidenz automatisch
Tag / Release	Periodenabschluss, signierte Zahlen, Steuer-Version	Unveränderlicher Marker: „das war der offizielle Stand“
Diff	Was sich zwischen zwei Daten/Zuständen/Branches geändert hat	Essenziell für Auditoren
Blame	Wer (oder welche KI) dieses Konto berührt hat und warum	Zeilen- oder kontenbezogene Historie
Restore / Revert	Head auf einen früheren Punkt setzen; erzeugt immer neuen Commit	Schreibt Historie nie um
Reflog / History	Vollständiges Event-Log + Timeline durchwandern	„Zeig mir alles, was passiert ist“

Regel: Historie wird niemals umgeschrieben. Alle Änderungen (inkl. Rollbacks und KI-Aktionen) sind neue Commits, die auf die Vergangenheit verweisen.

So erscheint es in der UI

Persistenter Books-View-Indikator

Eine Leiste zeigt immer, was du betrachtest:

main (current) – offizielle geschützte Bücher, live Head.
branch name – Arbeitsbereich oder KI-Experiment (visuell abweichende Warnung).
as of <date or commit> – auf historischen Punkt gepinnt (visuell abweichende Warnung).

Klick auf Indikator oder Controls bringt dich zurück zu aktuellem main.

Git-Steuerung (History-View)

Unter /app?view=history:

Branch-Auswahl und „Create branch“.
Zeitpunkt (asOf): Datum oder Event-/Commit-ID.
Letzte Commits + Tags (buchhalterfreundlicher Picker).
Konto abstimmen.
Merge (Änderungen zuerst previewen).
Aktuellen View taggen.
Restore mit Pflicht-Preview (Bilanzwirkung vor Bestätigung).
Diff- und Blame-Tools.

Alle anderen Panels (Ledger, Konten, Berichte, GuV, Journal) respektieren ?branch und ?asOf aus der URL. Du kannst ein Ledger direkt aus dem Chat öffnen und Branch/Zustand behalten.

Letzte Zustände

Du kannst letzte Commits oder benannte Tags wählen und den genauen Zeitpunkt-View app-weit laden. „Restore this state“ bewegt den Branch-Head durch einen neuen ROLLBACK-Commit.

Branches

main = offizielle Bücher (geschützt).
Andere Branches = Arbeitsbereiche, KI-Experimente, „was wäre wenn“-Szenarien.
Du kannst jeden Branch an jedem Punkt seiner Historie ansehen.
Vor riskanter Arbeit einen Branch zu erstellen ist das empfohlene Muster.
Branches können gemergt (Nettoänderungen werden previewt) oder verworfen werden.

Persistenter Zustand: Die URL spiegelt immer den aktuellen View. „Viewing: main (current books)“ oder „Viewing: ai-june-recon • as of June close (tagged)“.

Commits, Events und Historie

Jede Journalbuchung, KI-Aktion, Branch-Erstellung, Merge, Tag oder Restore wird als unveränderliches Event erfasst.

Vollständige git log-artige Historie über Audit-Log und Git-Controls.
Jeder Commit trägt: Beschreibung, Author (Mensch oder KI-Modell), Reasoning, exakte Zeilen, Anhänge, FX-Quellen usw.
Du siehst immer genau, was die KI getan hat und warum.

Restore-Verhalten (Sicherheitsregel):

Restore erzeugt immer einen neuen ROLLBACK-Commit.
Nichts wird gelöscht oder umgeschrieben.
Du kannst sofort zu jedem anderen Punkt restoren, inkl. dem Stand vor dem vorherigen Restore.
„Restore makes this the current main“ ist auf main erlaubt, bleibt aber ein neuer auditierter Commit.

Philosophie der Abstimmung (Reconciliation)

Es gibt nur eine Wahrheit.

Wenn die KI Konten abstimmt:

Sie analysiert Feeds, bestehende Journalzeilen, Timing-Differenzen, gelernte Muster.
Sie cleared Positionen und schlägt vor bzw. erstellt nötige Korrekturbuchungen.
Das Ergebnis ist ein klassisch aussehender Abstimmungsreport: Anfangssaldo, cleared Items, offene Posten, Anpassungen, Endsaldo passend zum Auszug, plus volle Provenienz.

Der Report, den Auditor oder Bank erwarten, ist genau dieses Artefakt – ob von Mensch oder KI erzeugt.

KI als First-Class Citizen

Die KI (über Chat und Hintergrund-Agenten) darf und soll:

Journalbuchungen autonom erstellen bei hoher Konfidenz (z. B. > ~0,85 + starker Feed-Match + gelerntes Muster + keine Mehrdeutigkeit).
Abstimmung über Konten durchführen.
Abweichungen erklären.
Fixes als Entwurf oder auf einem Branch vorschlagen.
Zeitpunkt-Restores ausführen, wenn explizit angewiesen.

Konfidenz- & Autonomie-Regeln (erzwungen):

Hohe Konfidenz + sichere Aktion + Chat-Sperre offen → KI erstellt die Buchung(en) direkt auf dem Ziel-Branch (meist main). Volles Reasoning als AI_AUTONOMOUS_ENTRY.
Mittlere Konfidenz, destruktive Aktionen oder Chat-Sperre zu → KI erzeugt einen Vorschlag. Mensch muss prüfen und freigeben.
Niedrige Konfidenz oder hohes Risiko (Steueränderungen, große Beträge, Stammdaten, neue Jurisdiktionen) → Immer nur vorschlagen. Nie auto-anwenden.
Jede autonome Aktion wird mit Modell, Prompt-Kontext, Konfidenz, Quellen und exakten Buchungen geloggt.
Der User kann jederzeit überschreiben, prüfen oder rollen.

Siehe auch: docs/ai/ai-autonomy.md für detaillierte Regeln und Prompt-Beispiele.

Sicherheit und Auditierbarkeit

Ein Git-Modell-System gibt Auditoren und Eigentümern:

Unveränderliche, zeitgestempelte, zurechenbare Commits für jede Änderung.
Vollständige Historie mit Kontext und angehängtem KI-Reasoning.
Blame auf jedem Konto und jeder Zeile.
Exakte Diffs zwischen zwei beliebigen Zeitpunkten.
Signierte/getaggte Zustände: „darauf haben wir die Bücher geschlossen“.
Sicheren, auditierbaren Rollback ohne Beweisvernichtung.

Das ist bessere Auditierbarkeit als bei fast jedem traditionellen Buchhaltungspaket.

Nicht verhandelbar:

Historie ist heilig. Niemals still mutieren oder löschen.
KI-Autonomie bei hoher Konfidenz ist ein bewusstes, unterstütztes Feature.
Abstimmung ist ein AI-first-Prozess, dessen Output der klassische Report ist.
Restore / Branching / Diff / Blame müssen existieren und aus UI und Chat nutzbar sein.
Alle neuen Features müssen durch die Linse dieses Modells entworfen werden.

Widerspricht ein Dokument oder Verhalten diesem Modell, gewinnt das Git-Modell.

Autoritative Quellen (für Implementierer und Fortgeschrittene)

entrytwo_v1/prisma/schema.prisma – Datenmodell (Event, Branch, Tag, Snapshot usw.).
entrytwo_v1/docs/Git-Model-for-Accounting.md – die ursprüngliche detaillierte interne Philosophie.
.grok/skills/ – aktuelle LLM-Aktionsverträge und Buchhaltungsanweisungen.
docs/ai/ai-autonomy.md – wann die KI autonom handelt vs. vorschlägt.
Codepfade: GitModelControls.tsx, BooksViewIndicator.tsx, autonomous.ts, chat/route.ts, ancestry.ts, atomicCommit.ts.

Wenn du erwägst, vom Git-Modell abzuweichen: stopp. Lies das Produktziel noch einmal. Erkläre dann, warum die neue Richtung Buchhaltungsfronarbeit besser beseitigt und Auditierbarkeit erhält (oder verbessert).

Dieses Modell macht entrytwo anders und tatsächlich nützlich.