swaitsandClaude Opus 5.5
df38dcccf9
Stephen (2026-10-13): when what wanderbooks knows is stale, check the date, research it or ask the owner or CPA, and update the rule for everyone with a pull request (best) or an issue (worst). - ledger_core::rules: a registry of rules set by law that change over time. Each says the years it's known for, its rules.md entry, its vendored official source, and a review date. stale_rules(today) is pure; the engine has no clock. - The 1099 threshold is the first: $600 through 2025, $2,000 in 2026, then indexed for inflation (26 U.S.C. §6041(h)). default_threshold and vendor_1099_report now return Result; for 2027+ they refuse with LedgerError::RuleNotKnown, whose message says what to do: get the figure from the official source or the owner/CPA, pass it explicitly, then open a PR (or issue) at github.com/swaits/wanderbooks. Before, 2027+ silently used $2,000. - MCP: books.vendor_1099 relays that refusal; books.digest gains stale_rules; the server instructions tell the agent the procedure (and how to handle control-account conflicts: explain, never renumber). The CPA package writes a NOT-INCLUDED note instead of a guessed 1099 worksheet. - Viewer: "Needs attention" shows each stale rule with a ready prompt for the agent; the 1099 page explains instead of guessing. Review date for the 1099 rule: 2026-11-01, when the IRS usually publishes next year's inflation adjustments (CONVENTION, marked as such in the registry). Tests: an_unknown_year_threshold_is_never_guessed, dated_rules_go_stale_on_their_review_date (dates passed in, so no clock in the test), MCP stdio: 2027 refused with guidance, explicit threshold accepted, digest carries stale_rules (asserted date-independently). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GWVo7x3UHw5kwCUaWxiejX
60 lines
4.1 KiB
Markdown
60 lines
4.1 KiB
Markdown
# 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, payroll taxes, rounding on returns | Public domain (17 U.S.C. §105; IRS.gov's content policy) | Vendored verbatim: `sources/irs-*.md`, `sources/us-public-domain-status.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
|
|
|
|
```text
|
|
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.
|
|
|
|
## 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.rs` with 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. Not yet verified (the ASC's free basic view needs a
|
|
login): ASC 360-10-35-4 (depreciation), 340-10 (prepaids), 230-10-45-10,
|
|
606-10-55-37B, 210 (balance sheet). Until someone with a FASB basic-view
|
|
account reads them, the rules that would cite them cite the textbook and
|
|
say so.
|