wanderbooks/AGENTS.md

AGENTS.md — wanderbooks

Operating manual for agents working in this repo. Read this first, then the docs it points to. The short version: this is an engine-first, clean-room rebuild of canonical double-entry bookkeeping, done the storytold way — agents verify against oracles, track parity automatically, and never ship what they haven't demonstrated.

What this is

wanderbooks is a from-scratch implementation of double-entry bookkeeping semantics, built to become a full bookkeeping application (engine now, UI later). The reference points:

• Semantic oracle: GnuCash. It is open source with open file formats (XML/SQLite), which makes it both the spec and the reference implementation we diff against. See docs/oracle.md.
• Workflow reference: QuickBooks Online and Xero — for what the UI must do, never for code. We observe behavior; we write our own implementation.
• Method reference: storytold/ArtCraft's app-cloning pipeline (screenshot-in-the-loop, render oracles, automated parity floors). We adapt it to accounting: semantic oracles instead of pixel oracles.

The non-negotiables

1. Money is Money. Exact Decimal plus a currency code. Binary floats (f32/f64) never appear in money paths — not for amounts, not for rates, not for "temporary" calculations. If you need a ratio, it is a Decimal.
2. Every entry balances. Debits equal credits exactly. No epsilon.
3. Posted is forever. Posted entries are immutable. Corrections are reversing entries linked by reversal_of. There is no edit, no delete.
4. Reports are pure functions of a ledger. If a report needs state that isn't in the ledger, the ledger model is wrong — fix the model.
5. Clean room. Build from public specs and observed behavior only: GnuCash documentation and file formats, the IFRS conceptual framework, IRS publications for tax-adjacent logic later. GnuCash itself is GPL — read its docs, never copy its code. This repo is MIT OR Apache-2.0. Never disassemble or copy from proprietary software.

Verification protocol (read this twice)

There is no UI yet, so "seeing what it's building" means showing the numbers. The analog of storytold's screenshot-in-the-loop:

• A green cargo test is necessary but not sufficient. Every behavior change must be demonstrated through the public API with human-readable output: print the trial balance, the P&L, the balance sheet. Show the numbers moving the way accounting says they should.
• New behavior needs new tests in crates/ledger-core/tests/invariants.rs (or a new test file for a new crate). Tests encode accounting law, not implementation details: prefer "the accounting equation holds" over "this function returns that struct".
• Golden files are sacred. tests/golden/*.json hold hand-verified expected reports for canonical fixtures. If a change intentionally alters output, recompute the expected numbers by hand from accounting principles, update the golden, and explain the recomputation in the commit message. Never edit a golden to match output you haven't verified — that is how oracles die.
• The randomized invariant test (random_balanced_journals_preserve_invariants) is the always-on property oracle. Extend it when you add invariants.

Parity tracking

docs/parity.md is the parity catalog: every semantic feature we intend to clone, with status. Rules:

• Every feature change updates docs/parity.md in the same commit.
• The floor never decreases: the count of done items is monotonic. CI will enforce this once the catalog is machine-readable (roadmap phase 3); until then, it is enforced by review — yours.
• Statuses are done (implemented + tested + golden-covered), partial, todo. No other statuses. done requires all three.

Engine-first architecture

• All mutations are commands on Ledger (create_entry, add_line, post_entry, reverse_entry, add_account). Struct fields stay private; no other mutation path may exist.
• ledger-core depends only on rust_decimal, thiserror, chrono, serde, serde_json. New dependencies need justification in the commit message. No I/O, no networking, no time-source in the core.
• Future crates (ledger-store, ledger-import, ledger-oracle, books-app) depend inward toward the core, never the reverse. See docs/architecture.md.

Working here

• Rust stable, edition 2024. cargo test must pass; cargo clippy should be clean; cargo fmt before committing.
• Conventional commits: feat:, fix:, docs:, test:, refactor:. One logical change per commit. The commit message explains the accounting reasoning, not just the code.
• You have a very large context window. Use it: when working on semantics, load the whole ledger-core crate plus docs/requirements.md rather than guessing from snippets.
• If a requirement in docs/requirements.md conflicts with code, the requirement wins — then fix the code, and say so.

Docs index

Read this	When you need
docs/requirements.md	What the engine must do (R-1…), what is future work
docs/architecture.md	Crate layout, command pattern, dependency rules
docs/oracle.md	How we prove correctness: golden files, property tests, GnuCash diffing
docs/parity.md	Feature catalog and the non-regression floor
docs/capability-parity.md	Parity vs the GSheet+GDrive system + the cutover rule
docs/mcp-interface.md	The MCP tool surface: the primary interface spec
docs/receipt-store.md	Blob store + ledger-store SQLite persistence spec
docs/glossary.md	Debit/credit and friends, for agents new to accounting
plan/STATUS.md	Where the project stands right now
plan/roadmap.md	Phase plan: semantics → oracle harness → egui app → workflow parity

License

MIT OR Apache-2.0. New files carry no license headers; the license files at the repo root cover the tree.