Git Model for Accounting

Status: Authoritative core concept for entrytwo.

entrytwo models the entire set of accounting records as a Git repository of financial truth.

• Every change is a commit.
• History is immutable and fully auditable.
• You can branch to explore scenarios or let AI work in parallel.
• You can merge proposals into the main line of truth.
• You can tag important states (month-end close, auditor snapshot).
• You can diff, blame, restore to any previous point.
• The AI is a first-class contributor that can create commits autonomously when its confidence is high.

This is not "AI suggests while humans do the real work." The boring, repetitive, error-prone bookkeeping is done by AI. Humans provide direction, review exceptions, and own the outcome.

Product goal: You should not need to hire a full-time bookkeeper just to keep the books correct.

---

Exact Git-to-Accounting Mapping

Rule: History is never rewritten. All changes (including rollbacks and AI actions) are new commits that reference the past.

---

How It Appears in the UI

Persistent Books View Indicator

A bar always shows what you are looking at:

• main (current) - official protected books, live head.
• branch name - working area or AI experiment (visually distinct warning).
• as of <date or commit> - pinned to a historical point (visually distinct warning).

Clicking the indicator or controls lets you return to current main.

Git Controls (History View)

Located at /app?view=history:

• Branch selector and "Create branch".
• Point-in-time (asOf): date or event/commit ID.
• Recent commits + tags (accountant-friendly picker).
• Reconcile account.
• Merge (preview changes first).
• Tag current view.
• Restore with mandatory preview (shows balance impact before confirming).
• Diff and blame tools.

All other panels (ledger, accounts, reports, P&L, journal) respect the current ?branch and ?asOf from the URL. You can open a ledger directly from chat while preserving the viewed branch/state.

Recent States

You can pick recent commits or named tags to load that exact point-in-time view across the whole app. "Restore this state" moves the branch head by creating a new ROLLBACK commit.

---

Branches

• main = official books (protected).
• Other branches = working areas, AI experiments, "what if" scenarios.
• You can view any branch at any point in its history.
• Creating a branch before risky work is the recommended pattern.
• Branches can be merged (net changes are previewed) or abandoned.

Persistent state: The URL always reflects the current view. "Viewing: main (current books)" or "Viewing: ai-june-recon • as of June close (tagged)".

---

Commits, Events, and History

Every journal entry, AI action, branch creation, merge, tag, or restore is recorded as an immutable event.

• Full git log-style history is available via the Audit log and Git controls.
• Each commit carries: description, author (human or AI model), reasoning, exact lines, attachments, FX sources, etc.
• You can always see exactly what the AI did and why.

Restore behavior (safety rule):

• Restore always creates a new ROLLBACK commit.
• It does not delete or rewrite anything.
• You can immediately restore to any other point, including the state before the previous restore.
• "Restore makes this the current main" is allowed on the main branch but is still a new audited commit.

---

Reconciliation Philosophy

There is only one truth.

When the AI reconciles accounts:

• It analyzes feeds, existing journal lines, timing differences, learned patterns.
• It clears items and proposes or creates the necessary adjusting entries.
• The output is a classical-looking reconciliation report: starting balance, cleared items, outstanding, adjustments, ending balance that matches the statement, plus full provenance.

The report an auditor or bank expects is exactly this artifact - whether produced by a human or by AI.

---

AI as a First-Class Citizen

The AI (via chat and background agents) is allowed and expected to:

• Create journal entries autonomously when confidence is high (e.g. > ~0.85 + strong feed match + learned pattern + no ambiguity).
• Perform reconciliation across accounts.
• Explain discrepancies.
• Propose fixes as draft entries or on a branch.
• Execute point-in-time restores when explicitly instructed.

Confidence & Autonomy Rules (enforced):

• High confidence + safe action + chat lock open → AI creates the entry(ies) directly on the target branch (usually main). Full reasoning is recorded as AI_AUTONOMOUS_ENTRY.
• Medium confidence, destructive actions, or chat lock closed → AI creates a proposal. Human must review and approve.
• Low confidence or high-risk (tax changes, large amounts, master data, new jurisdictions) → Always propose only. Never auto-apply.
• Every autonomous action is logged with model, prompt context, confidence, sources, and the exact entries created.
• The user can always override, review, or roll back.

See also: docs/ai/ai-autonomy.md for detailed rules and prompt examples.

---

Safety and Auditability

A Git-model system gives auditors and owners:

• Immutable, timestamped, attributable commits for every change.
• Complete history with full context and AI reasoning attached.
• Blame on every account and line.
• Exact diffs between any two points in time.
• Signed/tagged states that represent "this is what we closed the books on".
• Safe, auditable rollback that does not destroy evidence.

This is better auditability than almost every traditional accounting package.

Non-negotiables:

• History is sacred. Never silently mutate or delete past events.
• AI autonomy at high confidence is a deliberate, supported feature.
• Reconciliation is an AI-first process whose output is the classical report.
• Restore / branching / diff / blame must exist and be usable from both UI and chat.
• All new features must be designed through the lens of this model.

If any document or behavior contradicts this model, the Git model wins.

---

Authoritative Sources (for implementers and advanced users)

• entrytwo_v1/prisma/schema.prisma - data model (Event, Branch, Tag, Snapshot, etc.).
• entrytwo_v1/docs/Git-Model-for-Accounting.md - the original detailed internal philosophy.
• .grok/skills/ - current LLM action contracts and accounting instructions.
• docs/ai/ai-autonomy.md - how the AI decides to act autonomously vs propose.
• Code paths: GitModelControls.tsx, BooksViewIndicator.tsx, autonomous.ts, chat/route.ts, ancestry.ts, atomicCommit.ts.

---

If you are considering changing direction away from the Git model, stop. Re-read the product goal. Then explain why the new direction is better at eliminating bookkeeping drudgery while preserving (or improving) auditability.

This model is what makes entrytwo different and actually useful.