docs / ai / ai-autonomy.md

KI-Autonomie und Chat-Verhalten

Status: Kernverhalten von entrytwo.

Die KI von entrytwo kann als First-Class-Contributor agieren: Sie kann Journalbuchungen erstellen, abstimmen, Muster lernen und andere Arbeit autonom erledigen, wenn die Konfidenz hoch ist – oder Änderungen zur menschlichen Prüfung vorschlagen, wenn Konfidenz niedriger oder Risiko höher ist.

Ziel: Buchhaltungsfronarbeit entfernen bei voller Auditierbarkeit und menschlicher Kontrolle.

Kernregel: Sicher + hohe Konfidenz + Sperre offen → Ausführen

Der Server entscheidet nach Validierung:

Die vom Modell gewünschte Aktion parsen.
Validieren (ausgeglichenes Journal, Konten existieren, FX-Regeln usw.).
Aktion klassifizieren:

Sicher autonom (unten gelistet) → kann direkt ausgeführt werden.
Braucht explizite Bestätigung (PROPOSE_*) oder Stammdaten → immer als Vorschlag zurück.

Chat-Sperre anwenden:

Chat gesperrt → auch sichere Aktionen werden Vorschläge.

Wenn alles passt und sicher + nicht gesperrt → Aktion läuft und erzeugt einen echten Commit (AI_AUTONOMOUS_ENTRY).
Sonst → Vorschlag zum Prüfen und Freigeben.

Du siehst immer, was die KI getan hat oder tun will, inkl. Reasoning.

Sichere autonome Aktionen (ohne Bestätigung bei Konfidenz + entsperrt)

Diese Aktionen gelten als risikoarm, wenn die Daten validieren:

CREATE_JOURNAL
CREATE_JOURNAL_BATCH (z. B. aus einem Auszugs-PDF)
APPLY_TEMPLATE
CREATE_CONTACT
UPDATE_CONTACT
CREATE_INVOICE_DRAFT
CREATE_EXPENSE_CLAIM_DRAFT
GENERATE_RECURRING_DRAFT
MATCH_FEED_TRANSACTION
SYNC_FEED
IMPORT_FEED_CSV
RECONCILE_ACCOUNT
LEARN_MERCHANT
OPEN_LEDGER
EXPLAIN

Alle anderen Aktionen (Restore, Merge, Reverse, Rechnung senden, belasten, Konten anlegen, Steuersätze ändern, Benutzeränderungen usw.) sind niemals autonom.

Chat-Sperre (der große Sicherheitsschalter)

Ort: Chat-Eingabebereich (Schloss-Icon).

Entsperrt (Default für die meisten nach Setup): KI darf sichere Aktionen bei hoher Konfidenz und bestandener Validierung autonom ausführen.
Gesperrt: Jede Aktion wird zum Vorschlag. Du musst explizit bestätigen, bevor etwas die Bücher ändert.

Der Sperrzustand liegt im Browser (localStorage) und wird mit jedem Chat-Turn gesendet.

Bei Sperre erscheint ein Banner: „Chat locked - proposals only. Confirm to execute any action.“ / Chat gesperrt – nur Vorschläge.

Jederzeit umschaltbar. Viele Buchhalter halten sie gesperrt, bis sie der KI auf ihren Daten vertrauen.

Konfidenz und Vorschläge

Default-Schwelle hohe Konfidenz: ~0,85.
Das Modell liefert confidence (0–1) und reasoning.
Auch bei sicheren Aktionen: niedrige Konfidenz, Validierungsfehler oder destruktiv/Stammdaten → erzwungen als Vorschlag.
Vorschläge erscheinen als Karten oder Nachrichten mit „Confirm“ / „Cancel“ (oder dem New-Journal-Entry-Modal für Buchungen).
Freigabe eines Vorschlags re-validiert und führt ihn als normalen Commit aus (du bist Approver im Audit-Trail).

Two-Pass-Flow (manchmal): Das Modell kann zuerst Verständnis + groben Plan liefern, dann ein zweiter Call die exakten Parameter packen. Verbessert Zuverlässigkeit bei komplexen Auszügen.

Was die KI bei jedem Turn respektiert

Aktueller View (Branch + asOf): Alle Salden und Aktionen zielen auf den Branch und Zeitpunkt, den du gerade siehst. Die KI arbeitet nicht heimlich auf main, außer das ist der aktuelle View.
Exakte Kontocodes aus dem Ledger-Snapshot im Kontext.
Journals müssen nach FX-Umrechnung in die Basiswährung ausgleichen.
FX-Regeln (sehr streng):
Fremdbeträge starten normalerweise als provisional (LLM_PROVISIONAL oder MANUAL_PROVISIONAL) mit Quell-URLs.
Nur autoritative Bank-Feed-Kurse dürfen als BANK_FEED markiert werden.
Die KI erfindet keine Kurse. Fehlt ein zuverlässiger Kurs, erklärt sie den Blocker statt zu buchen.
Chat-Sperre wird serverseitig eingehalten.
Idempotenz über Keys wo anwendbar (verhindert Duplikate bei Retries).

Exakte Modell-Anweisungen: .grok/skills/actions/core-principles/SKILL.md.

Wie autonome Commits erfasst werden

Wenn die KI autonom ausführt:

Event-Typ: AI_AUTONOMOUS_ENTRY
createdBy ist der User der Chat-Session (oder System bei recurring/Hintergrundjobs).
Volle Metadaten: Modell, Provider, Konfidenz, Reasoning, Skill-Versionen, genutzte Quellen.
Der Commit erscheint in Journal, Audit-Log, Blame und Historie wie eine menschliche Buchung.
Du kannst ihn weiterhin reverse, blamen, diffen oder rollen.

Wiederkehrende Journal-Jobs und manches Hintergrund-Feed-Processing können ebenfalls autonome Einträge erzeugen (gleiche Regeln).

Wovon die KI explizit blockiert ist

Konten anlegen oder ändern (Kontenplan).
Steuersätze oder Firmeneinstellungen ändern.
Benutzer-/Rollenverwaltung.
Rechnungen direkt senden oder Kunden belasten (immer Vorschläge).
Restores oder Merges ohne Preview + explizite Bestätigung.
Historie umschreiben oder löschen.

Das kommt immer als Vorschlag (oder klare Ablehnung).

KI-Arbeit prüfen und korrigieren

Audit-Log und History (Git-Controls) nutzen, um genau zu sehen, was erzeugt wurde und warum.
Blame und Diff auf Konten oder Perioden.
Ist eine autonome Buchung falsch: reverse (Gegenbuchung) oder auf einen früheren guten Stand restoren (ROLLBACK-Commit).
Die KI kann jede Buchung oder Abweichung erklären.

Das System ist so gebaut, dass „die KI hat’s gemacht“ keine Ausrede ist – jede Aktion hat volle Provenienz.

Best Practices für gutes KI-Verhalten

Chat-Sperre nur entsperren, nachdem die KI eine Weile korrekt auf deinen Daten gearbeitet hat.
Klare Auszüge/Belege hochladen; das Modell arbeitet mit gutem Quellenmaterial deutlich besser.
Natürliche, aber präzise Anweisungen: „Stimme das Konto 1100 für letzten Monat ab und erkläre, was nicht gepasst hat.“
Bei Branch oder historischem Punkt ggf. sagen: „Auf dem june-recon-Branch, erstelle die Anpassung für die Timing-Differenz.“
Bei riskanter Arbeit explizit „nur vorschlagen“ sagen oder zuerst auf einem Branch arbeiten.
Belege im Chat stagen, bevor du Journalbuchungen anforderst, wenn sie angehängt sein sollen.

Bezug zum Git-Modell

Autonome KI-Aktionen sind einfach Commits auf dem aktuellen Branch (meist main).

Hochkonfidente sichere Arbeit landet direkt auf dem betrachteten Branch.
Niedrigere Konfidenz oder Risiko erzeugt einen Vorschlag, der später gemergt werden kann.
Alle normalen Git-Tools (Branch, Restore, Tag, Diff, Blame) gelten für KI-Buchungen genauso wie für menschliche.

Vollständige Philosophie: docs/concepts/git-model.md.

Schnellreferenz: Entscheidungstabelle

Situation	Ergebnis
Sichere Aktion + hohe Konfidenz + entsperrt + validiert	Autonomer Commit (`AI_AUTONOMOUS_ENTRY`)
Sichere Aktion + Chat gesperrt	Vorschlag
Destruktiv / PROPOSE_*-Aktion	Vorschlag (immer)
Stammdaten-Aktion	Abgelehnt oder Vorschlag (nie ausgeführt)
Validierung scheitert	Vorschlag mit Fehler
Niedrige Konfidenz	Vorschlag
Aktueller View ist vergangener Commit	Aktion zielt auf diesen Zeitpunkt auf dem Branch

Dieses Verhalten ist das bewusste Design, mit dem entrytwo Fronarbeit entfernt, ohne Kontrolle oder Auditierbarkeit zu opfern.