swaitsandClaude Opus 5.5
c9772b70c1
docs/mcp-interface.md: the connect text and its budgets, the handbook (tool and resources), annotations, failing closed, import_local_file's roots and refusals, the set_w9 path rule and where TIN-bearing files may go. docs/testing.md: the P0 laws and the tests that check them. docs/architecture.md: the journal format gate and the server's fail-closed store lock. Round-2 review (2026-10-16): mcp-interface.md lists all 26 destructive tools (unlink_receipt, unlink_attachment and correct_asset were missing) and openWorldHint false on every tool; the connect text states the parties rule and the exact receipt rule, and how it fits its budget; the lint covers every refusal; the import roots refuse /, the home folder and folders holding the books or a key, the open is a component walk, every missing or outside path gets one refusal, and the TIN-file registry and text scan (and what they can't catch) are described. architecture.md: the frozen envelope, the lenient next-line prev, no repair of newer books. testing.md: the new laws and tests. verification.md and parity.md: P0 notes (no new law to prove, no status moved). The TIN text check, narrowed (2026-10-16; rules.md B-26, mcp-interface.md): text is refused for a TIN the vault holds, in its common renderings, or a stand-alone printed SSN or EIN shape, so bank exports go in; the oracle a vault comparison gives is recorded as a known limit for P7. testing.md: the P0 mutation run of the final diff, per crate, and how each survivor was resolved (killed by a named test, removed by simpler code, or argued equivalent). The probe bound (rules.md B-26, mcp-interface.md): rule (a) answers for at most two candidates a filing, so finding a TIN from its last four takes on the order of 50,000 refused filings; the open limit now names that path, closed by P2's access log and P7's human-only TIN channel. testing.md: the law and its tests; tin_files.rs mutated again, 74 of 74 caught. Review round 3: rules.md B-28 (four-digit years, amounts a line can carry, checked products, bounded recurring runs) and B-26/B-27 updates (BOM-less UTF-16, when set_w9 records); mcp-interface.md matches the code (25 destructive tools, the five idempotent ones, no reverse_entry receipt checklist, strictly above the threshold, no tool text names wanderbooks.toml, dot names and roots inside the books refused, the new settings lists); testing.md lists the new laws and this round's mutation run. Review round 4: rules.md B-28 says the bounds are for new commands only, replay accepts every line an earlier version accepted, and derived figures refuse rather than panic; mcp-interface.md documents plan_error and the nullable totals; testing.md lists the old-books contracts and this round's mutation run (core, store, MCP, config, GUI). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj
Specification sources
wanderbooks' rules come from documents, not from anyone's memory. This
directory holds the authorities the engine's specs cite (docs/spec/rules.md
is the rule catalog), and every spec block in the code carries a SOURCE:
line pointing into it.
The authority stack
There is no single "bible" of US bookkeeping. Authority is layered, and the layers differ in what they cover and in whether we may copy them:
| Layer | What it governs | Copyright | Here |
|---|---|---|---|
| Pacioli (1494), Geijsbeek translation (1914) | The mechanics of double entry: debits equal credits, the trial balance, one money, writing only forward, correcting by opposite entry, closing into capital. No modern standard restates these; they predate every regulator. | Public domain | Vendored verbatim: sources/pacioli-1494.md |
| IRS: Internal Revenue Code, Treasury Regulations, publications, form instructions | Records and supporting documents, retention, accounting periods and methods, information returns (1099), capitalization (de minimis, 12-month rule), partners' capital, tax basis of purchased and contributed property (sources/irs-partnership-basis.md), payroll taxes, rounding on returns, return line items for tax categories (sources/irs-tax-lines.md) |
Public domain (17 U.S.C. §105; IRS.gov's content policy) | Vendored verbatim: sources/irs-*.md, sources/us-public-domain-status.md |
| File formats: Intuit (QuickBooks Online bank CSV, QuickBooks Desktop IIF), ECMA-376 Office Open XML, Microsoft Excel limits, Avery label sheets | What ledger-import reads and writes: bank/card CSV layouts and signs, IIF journal entries, how XLSX stores numbers and Excel's 15-digit precision, asset-label sheet geometry (Avery 5160) |
© Intuit Inc.; © Ecma International; © Microsoft; © Avery Products Corporation | Cited with short quotes, URLs, and hashes: sources/intuit-bank-csv.md, sources/intuit-iif.md, sources/xlsx-numbers.md, sources/avery-5160.md |
| FASB Accounting Standards Codification (ASC) | Authoritative US GAAP: cash flows (ASC 230), revenue and principal vs agent (ASC 606), foreign currency (ASC 830), credit losses and aging (ASC 326), property and depreciation (ASC 360) | © Financial Accounting Foundation | Cited by paragraph with short quotes only (in rules.md) |
| FASB Concepts Statement No. 8, Chapter 4 (2021) | Definitions of the five elements (it replaced Concepts Statement 6) | © Financial Accounting Foundation; non-authoritative | Cited with short quotes only |
| Textbooks (OpenStax Principles of Accounting, Vol. 1) | Conventions no standard states: normal balances, closing-entry mechanics, straight-line depreciation arithmetic | CC BY-NC-SA 4.0 (incompatible with this repo's license) | Cited with short quotes and attribution only |
| Convention or decision | Where no authority speaks: aging bucket edges, cent rounding among members, closed-period locks | — | Stated as CONVENTION or DECISION, with who decided and when |
How to read a SOURCE line
SOURCE: Pacioli ch. 36 (sources/pacioli-1494.md); IRS Pub. 583 (sources/irs-records.md)
SOURCE: ASC 830-20-30-1 (cited, rules.md B-3)
SOURCE: DECISION (Stephen, 2026-10-13)
SOURCE: CONVENTION (QuickBooks aging); nearest authority ASC 326-20-55-38 (illustrative)
A rule whose only source is CONVENTION or DECISION is a candidate for a human to confirm or overturn; nothing else is.
Rules added later never lock out older books
When a rule is tightened (a check added to a command), books written
before it must still open. Journal replay and the SQLite cross-check read
history through the engine's replay_* commands, which skip checks added
later; new commands go through the checked ones. Pinned by
books_written_under_older_rules_still_open (ledger-store).
Vendoring rules
- Public-domain texts are copied verbatim (whitespace normalized), each with its URL, retrieval date, and the SHA-256 of the retrieved file, so anyone can check the excerpt against the original.
- Copyrighted sources are cited by paragraph, quoted briefly, never copied.
- When an authority changes (the IRS revises a publication; a statute is amended), add the new text beside the old with its effective date. Rules that depend on dates (1099 thresholds) must say which text applies when.
- Rules that change with the law are registered in
crates/ledger-core/src/rules.rswith the years they are known for and a review date. Past what it knows, the engine refuses rather than guesses; from the review date, the MCP digest and the viewer flag the rule. Whoever updates one (human or agent) vendors the new official text here, extends the rule, and sends the change upstream: a pull request at https://github.com/swaits/wanderbooks (best), or an issue.
Open: sources we could not verify
Read on 2026-10-13 through Deloitte's free DART roadmaps, which reproduce
ASC text: ASC 230-10-45-16 and -28, 326-20-55-37/38, 606-10-25-23, 45-2,
55-37/38, 830-20-30-1. Read directly in the ASC basic view on 2026-10-14
(sources/fasb-asc.md): 360-10-35-4, 340-10-05-2/4/5, 210-10-45-1/2/5,
230-10-45-7/10/12/13/14/15, 606-10-55-36 through 55-38. None left open.