AI Autonomy and Chat Behavior

Status: Core behavior of entrytwo.

entrytwo's AI can act as a first-class contributor: it can create journal entries, reconcile, learn patterns, and perform other work autonomously when it has high confidence - or propose changes for human review when confidence is lower or risk is higher.

The goal is to remove bookkeeping drudgery while keeping full auditability and human control.

---

Core Rule: Safe + High Confidence + Lock Open → Execute

The server decides after validation:

1. Parse the action the model wants to take.
2. Validate it (balanced journal, accounts exist, FX rules followed, etc.).
3. Classify the action:

• Safe autonomous (listed below) → can execute directly.
• Requires explicit confirmation (PROPOSE_*) or master data → always returned as a proposal.

1. Apply the chat lock:

• If chat is locked → even safe actions become proposals.

1. If everything passes and it is safe + not locked → the action executes and creates a real commit (AI_AUTONOMOUS_ENTRY).
2. Otherwise → a proposal is returned for you to review and approve.

You always see what the AI did or wants to do, with reasoning.

---

Safe Autonomous Actions (can run without confirmation when confident + unlocked)

These actions are considered low-risk when the data validates:

• CREATE_JOURNAL
• CREATE_JOURNAL_BATCH (e.g. from a statement 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

All other actions (restore, merge, reverse, send invoice, charge, create accounts, change tax rates, user changes, etc.) are never autonomous.

---

Chat Lock (The Big Safety Switch)

Location: Chat input area (lock/unlock icon).

• Unlocked (default for most users after setup): AI may autonomously execute safe actions when its confidence is high and validation passes.
• Locked: Every action becomes a proposal. You must explicitly confirm before anything changes the books.

The lock state is stored in your browser (localStorage) and sent with every chat turn.

When locked, a banner appears: "Chat locked - proposals only. Confirm to execute any action."

You can toggle at any time. Many accountants keep it locked until they trust the AI on their data.

---

Confidence and Proposals

• Default high-confidence threshold: ~0.85.
• The model returns confidence (0 - 1) and reasoning.
• Even on safe actions, if confidence is low, validation fails, or the action is destructive/master-data → it is forced into a proposal.
• Proposals appear as cards or messages with "Confirm" / "Cancel" (or the New Journal Entry modal for journal entries).
• Approving a proposal re-validates and then executes it as a normal commit (with you as the approver in the audit trail).

Two-pass flow (sometimes used): The model may first give an understanding + rough plan, then a second call packs the exact parameters. This improves reliability for complex statements.

---

What the AI Respects on Every Turn

• Current view (branch + asOf): All balances and actions target the branch and point-in-time you are currently viewing. The AI does not secretly work on main unless that is the current view.
• Exact account codes from the ledger snapshot provided in context.
• Journals must balance after FX conversion to base currency.
• FX rules (very strict):
• Foreign amounts normally start as provisional (LLM_PROVISIONAL or MANUAL_PROVISIONAL) with source URLs.
• Only authoritative bank feed rates may be marked BANK_FEED.
• AI never invents rates. If it cannot find a reliable rate, it explains the blocker instead of creating the entry.
• Chat lock is honored server-side.
• Idempotency via keys where applicable (prevents duplicate creation on retries).

See .grok/skills/actions/core-principles/SKILL.md for the exact instructions given to the model.

---

How Autonomous Commits Are Recorded

When the AI executes autonomously:

• Event type: AI_AUTONOMOUS_ENTRY
• createdBy is the user who owns the chat session (or system for recurring/background jobs).
• Full metadata is attached: model, provider, confidence, reasoning, skill versions, sources used.
• The commit appears in the journal, audit log, blame, and history exactly like a human entry.
• You can still reverse it, blame it, diff it, or roll it back later.

Recurring journal jobs and some background feed processing can also create autonomous entries (same rules apply).

---

What the AI Is Explicitly Blocked From

• Creating or modifying accounts (chart of accounts).
• Changing tax rates or company settings.
• User/role management.
• Directly sending invoices or charging customers (always proposals).
• Performing restores or merges without preview + explicit confirmation.
• Rewriting or deleting history.

These always surface as proposals (or are rejected with a clear message).

---

Reviewing and Correcting AI Work

• Use the Audit Log and History (Git controls) to see exactly what was created and why.
• Use blame and diff on accounts or periods.
• If an autonomous entry is wrong: reverse it (creates a reversing entry), or restore to a prior good state (creates a ROLLBACK commit).
• You can ask the AI to explain any entry or discrepancy.

The system is designed so that "the AI did it" is never an excuse - every action has full provenance.

---

Best Practices for Good AI Behavior

• Keep the chat lock unlocked only after you have seen the AI work correctly on your data for a while.
• Upload clear statements/receipts; the model performs much better with good source material.
• Use natural but specific instructions: "Reconcile the 1100 account for last month and explain anything that didn't match."
• When viewing a branch or historical point, say so if needed: "On the june-recon branch, create the adjustment for the timing difference."
• For risky work, explicitly say "propose only" or work on a branch first.
• Stage receipts in the chat before asking for journal entries when you want them attached.

---

Relationship to the Git Model

Autonomous AI actions are just commits on the current branch (usually main).

• High-confidence safe work lands directly on the viewed branch.
• Lower-confidence or risky work creates a proposal that can be merged later.
• All the normal Git tools (branch, restore, tag, diff, blame) apply to AI-created entries exactly the same as human ones.

See docs/concepts/git-model.md for the full philosophy.

---

Quick Reference: Decision Table

---

This behavior is the deliberate design that lets entrytwo remove drudgery without sacrificing control or auditability.