GitHub - emmilco/us-tax-model: US federal income tax forms and instructions as cited, executable, machine-checkable data.
US federal income tax forms and instructions as cited, executable, machine-checkable data. - emmilco/us-tax-model
US federal income tax forms and instructions as cited, executable, machine-checkable data. - emmilco/us-tax-model
This project encodes the IRS's individual income tax forms and instructions as open data, line by line. Every line is cited to the archived IRS page it came from and is built from a small set of operations whose properties are proved. Anyone can check any line against the printed form.
For most of the past two decades, the IRS had promised not to offer a free filing service of its own. In 2002 the commercial tax-preparation industry, led by Intuit, the maker of TurboTax, struck a deal with the IRS through the Free File Alliance. Its members offered free software to lower- and middle-income filers, roughly 70% of taxpayers; in exchange, the IRS promised not to build a government-run filing system. That promise was dropped only in 2019, after ProPublica reported how the companies had steered eligible filers away from the free products (ProPublica). In 2022 the Inflation Reduction Act gave the IRS $15 million to study an IRS-run alternative. The study appeared in 2023, Treasury then ordered a pilot, and the pilot became Direct File (GAO decision B-337954).
Direct File was built in-house by IRS technologists, working with the US Digital Service, GSA and contractors (Direct File README). Its pilot ran in 12 states during the 2024 filing season, and 140,803 returns were accepted (GAO). That May the IRS made it permanent, and for the 2025 season it ran in 25 states, with 296,531 returns accepted by April 20 (Treasury). Its scope stayed deliberately narrow: wages, Social Security, unemployment, interest and some retirement income. Filers liked it: 90% or more of those surveyed rated their experience "excellent" or "above average." But only a small fraction of the people eligible ever used it (CRS).
The program was contested from the start. Intuit, H&R Block and their trade group, the American Coalition for Taxpayer Rights, lobbied against it. They called it a costly and unnecessary overreach. Republican lawmakers wrote repeatedly urging that it be dismantled (Tax Notes). After the second Trump administration took office in 2025 the program was quickly shut down:
Intuit and H&R Block together spent $7.1 million on federal lobbying in 2025, their highest combined
total on record and a record for Intuit alone; the totals cover many issues besides Direct File
(OpenSecrets).
The IRS had published Direct File's code that year under a public-domain dedication. Its repository,
IRS-Public/direct-file, is now marked archived, and the tax
logic in it stops at tax year 2024.
Underneath Direct File's interview sat the Fact Graph: a declarative knowledge graph, written in
Scala, that runs both on the server and in the browser. Every fact about a return is either writable
(something the taxpayer supplies) or derived (computed from other facts by
operators
such as Add, GreaterOf, Round and Switch). Its distinctive idea is that incompleteness is first
class: the graph knows which facts are still unknown, so it knows what it can compute so far and what it
still needs to ask.
What Direct File put into that graph was the IRS's own reading of the law. In the words of its
README,
Direct File "interprets the United States' Internal Revenue Code … as plain language questions," and
those questions and their logic were "developed in close collaboration with the IRS Office of Chief
Counsel." Direct File's tax content is frozen in the archive at tax year 2024. The engine itself lives on
as a separate, actively updated library,
IRS-Public/fact-graph, and the IRS still builds on it: the
Tax Withholding Estimator and the
EITC Assistant both run on the Fact Graph. The IRS's
own encoding of the tax law is alive; what ended was free, public-facing return preparation.
Catala, from Inria in France (Denis Merigoux and colleagues, working with the tax-law scholar Sarah Lawsky), comes at the problem from the top: it is a programming language for writing down statutes. Statutes are written as general rules followed by exceptions, so Catala's core is a logic of prioritized defaults that mirrors that shape. Its programs are written literate-style, interleaved with the legal text they implement, so a lawyer and a programmer can read the two side by side, and the correctness of the compiler's core steps is proved (Merigoux, Chataing and Protzenko, ICFP 2021). The French tax authority (DGFiP) uses it in production, and the family-benefits agency (CNAF) adopted it in 2026 (EU open-source catalogue). In US tax law its published examples cover two sections of the Code, §121 and §132 (catala-examples).
Lawsky has made the observation this project is built on: the IRS's forms are already a formalization of the Code ("Form as Formalization," 2020). As she has since put it, they are a rigid formalization, made for a single purpose ("Tax Law and Flexible Formalizations," 2024). They are not the law, and they can carry judgments about the law that the IRS never announces. Lawsky's own argument is for going further, to flexible formalizations of the law itself, which is Catala's project. This one is narrower: it takes the rigid formalization as given and makes it checkable. Each of the three efforts above formalizes a different source text:
| Formalizes | Its warrant | |
|---|---|---|
| Catala | the statute | lawyers and programmers reading the code against the legal text |
| Direct File and the Fact Graph | the IRS's internal reading of the statute | the IRS itself, with its Chief Counsel |
| this project | the IRS's published reading: the forms, worksheets and instructions | checks that anyone can rerun |
This project takes the third source. A worksheet has already resolved the statute's rules and exceptions into a straight line of numbered steps, so there is no default logic left to model. The encoding simply follows the printed steps, in printed order, and every printed step is a cited line. From the Fact Graph it takes completeness-aware values: the interview asks only for what the return still needs. It adds what the Fact Graph lacks, which is a structured citation on every value. A Fact Graph fact carries at most a free-text description; here, every line names the archived document, its revision and content hash, and the place on the page it was read from, usually with the sentence quoted. From Catala it takes the conviction that an encoding should be readable against its source line by line, and proved wherever proof can reach. Its scope runs well past Direct File's: dividends and capital gains, self-employment, itemized deductions, the education credits and more, for an estimated 78% of returns. And unlike Direct File, it files nothing: it hands back a values sheet, and you file your own return.
The last column of that table is the important one. Direct File could be trusted because the IRS stood behind it. This project has no such standing: it is independent, and it was written largely by language-model agents. It cannot borrow authority from anyone, so it has to earn trust from checks anyone can rerun, and it has to be just as explicit about the claims those checks cannot support. The rest of this README is about how it does that, and how far it gets.
Federal income tax comes in layers. At the top is the law: the Internal Revenue Code, with the Treasury regulations that interpret it. Beneath it, the IRS publishes forms, instructions and publications that turn its reading of the law into steps ("Subtract line 4 from line 1. If zero or less, enter -0-"), along with the revenue procedures that set each year's amounts. A filed return is those steps applied to one household's facts.
This project formalizes the steps. They are public, finite and pinned to a tax year, and they are what filers and tax software actually follow. The encoding inherits every judgment the forms carry: where the forms are wrong about the law, so is this.
The instructions are sometimes silent, ambiguous, or in tension with themselves. Does "wages" for the
excess Social Security credit mean W-2 box 1, or boxes 3 and 7? When multiplying by a rate yields a
fraction of a cent, which way does it round? Every such question is an entry in
ambiguities/2025.yaml, 149 so far, recording the text at issue, the
candidate readings, the reading chosen and the reason. When an entry is linked to a line that touches
your return, the values sheet shows the reading chosen; 144 of the 149 entries are linked that way; each of the others says why it stands unlinked.
The tool prepares Form 1040 end to end. Whatever it cannot prepare, it refuses, never guesses: each refusal fires from an interview answer or a form box, names the form the tool cannot prepare, and cites the instruction that requires it.
If anything in the right-hand column applies to you, the tool cannot prepare your return. Otherwise it should be able to. Shares are of all individual returns, from the coverage estimate.
| The tool handles | The tool can't handle | |
|---|---|---|
| Filing status | ✓ Single, married filing jointly, married filing separately, head of household or qualifying surviving spouse, including a return for someone who can be claimed as a dependent, such as a student or a teenager with a job | ✗ Married filing separately in a community property state: 2.6% of returns |
| Wages | ✓ Wages and tips on Form W-2 | ✗ Wages or tips not on a Form W-2, and other earned income: 0.8% of returns |
| Investments | ✓ Interest, dividends, and sales of stocks, bonds, funds, and crypto and other digital assets | — |
| Retirement | ✓ Pensions, annuities, IRA and 401(k) distributions, Social Security and unemployment compensation | — |
| Business and property | ✓ A sole proprietorship or freelance work (Schedule C), and rental and royalty income (Schedule E) | ✗ A partnership, S corporation, estate or trust (Schedule K-1): about 3.9% of returns ✗ Farm income: 1.1% of returns ✗ Sales of business property (Form 4797): 1.1% of returns ✗ A net operating loss carried from another year: 0.6% of returns |
| Other income | ✓ State tax refunds, alimony, gambling winnings, prizes, canceled debt and jury duty pay | ✗ Other income the tool does not list: up to 4.8% of returns |
| Deductions | ✓ The standard deduction or itemized deductions, and the 2025 deductions for tips, overtime, car loan interest and seniors | — |
| Credits | ✓ The child tax credit, the earned income credit, and the child and dependent care, education, saver's, home energy and premium tax credits | ✗ Other credits, such as the adoption, clean vehicle, elderly or disabled, or business credits: 0.9% of returns |
| Foreign | ✓ Foreign tax on investment income, within the small-amount election | ✗ Foreign accounts or assets that require an FBAR or Form 8938: not measured |
Rare exceptions within the left-hand column are left to the interview, which stops with a citation if one applies. docs/COVERAGE.md lists all 305 situations the tool refuses, and says exactly what this table leaves out.
Money is integer cents and rates are pairs of integers. There is no floating point anywhere in the evaluator. Rounding happens only where a cited instruction says to round, by the rule it states, or, where the text is silent, by a reading recorded in the ambiguity register.
"The tool got my return right" is really two claims, and they are of different kinds.
The system computes what its data says. This is a claim about software, and it yields to mechanical methods: a checker that rejects malformed data, proofs about the primitive operations, two independently written evaluators agreeing on millions of values. The project settles it to a high standard.
The data says what the IRS page says. This is a claim about reading, and no proof reaches it. The only available evidence is agreement: independent readers given the same page arrive at the same encoding, or calculators built by other people from the same rules arrive at the same numbers. Such evidence is exactly as strong as the readers are independent, and the project publishes, line by line, how much of it there is.
That split is the ceiling on what the project can claim, and it organizes the architecture: each component either carries tax content or tests one of the two claims. The second claim is where most of the errors found so far have lived, and it is where the evidence is thinnest.
The system is a stack. You meet it at the top; the ground it answers to is the archived IRS page at the bottom.
1 interview you answer; it works out the next question
2 values sheet every value, with its derivation and citation
3 evaluators TypeScript ═ agree on every value ═ Lean, over atoms with proved properties
4 form data YAML lines, parameters, tables, gates ◄─ checker, renderer
5 the page archived IRS text, hashed ◄─ independent readers, outside engines
The form data is the product. Everything above it reads it; everything beside it checks it; nothing outside it contains a tax rule. Each layer below is described the same way: what lives there, what it earns, and where it stops. Where a layer stops is, more or less exactly, what the layer beneath it has to answer for.
You answer; the tool works out what to ask next. Which questions get asked is not authored: it is computed, as the inputs the evaluator still needs to reach the return's bottom lines given your answers so far. Only the wording, order and help text are authored, and each question carries the citation of the form line it fills. Refusal gates fire as early as their inputs allow, so an out-of-scope return finds out before you type numbers that cannot be used. "I don't know" is an allowed answer: the question comes back marked as needing help, with its help text, and the answer never quietly becomes zero. Answers live in an append-only log, and the whole return is recomputed from it on every change.
What it earns. The build walks the interview. For the full return it walks the 11 whole-return test cases, which is representative, not exhaustive. Each walk must end in a complete set of forms or a cited refusal, and must give the same values with the answers given in reverse order. Beyond the build, check-all walks about 640 coverage rows, each a situation stated as the answers a filer gives and the end the interview must come to.
Where it stops. At the wording. A question that asks for the wrong figure gets correct arithmetic
on the wrong number, and no arithmetic check can see it, because tests supply their answers directly.
That is not a hypothetical worry: a review of the first 210 recorded bugs
(docs/2026-10-29_bug_root_cause_analysis.md) found
questions and screens that diverge from the source to be the largest single class of value-changing
defects, 26 of 68. Two model reviews now stand guard. Every scope screen has been reviewed against the
lines it gates, with all findings ruled. A review of each form's instructions for rules nothing
encodes has covered every form. Both reviews are sampled once per release: the check suite lists a form
whose review is out of date, and a release fails while one is, or while a finding is left unruled. A question's wording is still, in the end,
a reading of the page (layer 5).
You get each form in printed order, line by line, with its value and citation, and with each value its derivation: the operation, the operand lines and their values, any rounding, and for a choice, which alternatives were not taken and why. A refusal names the gate that fired, the form that cannot be prepared, and the instruction behind it.
What it earns. Every number traces to a cited place on an archived IRS page, pinned by content hash, usually with the governing sentence quoted. A citation checker verifies every quote and locator against the archived text: 7,410 anchors and 8,124 quotes, with no finding left unruled.
Where it stops. A citation proves that a line points at a page. It does not prove that the line computes what the page says.
Every computed line is one application of one atom from a closed list of about twenty: sum,
subtract, subtract_floor0, smaller_of, multiply_rate, round, table_lookup, choose and the
rest (spec/spec.md section 4.2). The evaluator is a small TypeScript program that
knows those atoms and nothing about tax. It computes lazily over the line graph, in exact integer
arithmetic, and returns every value together with its derivation.
The atoms are defined a second time, over the integers, in Lean 4
(lean/TaxFormalization/), and their properties are proved there: a floored
subtraction is never negative; rounding is idempotent and moves a value by less than one unit; a
proration never exceeds the amount it prorates; and each atom is proved monotone or antitone in each ordered
argument, or shown by a proved counterexample to be neither (a cap, a number of places or a rounding unit,
all constants of the data); the banded table lookup is proved monotone in its key for a table whose
entries do not fall from band to band, as the Tax Table's do. Lean also holds a second evaluator,
written independently over the same canonical JSON. It is total by construction: every evaluation spends
from a step budget, so it always returns, and an exhausted budget comes back as an error, never as a
number. Both evaluators run over every test case and over 400 generated whole returns, drawn by the
generator the property tests use.
What it earns. The current report compares 6,114,183 line values across 2,168 cases and finds no difference. Note the shape of the claim: the atoms are proved, and two separate implementations agree. The TypeScript evaluator itself is not formally verified.
Where it stops. Both evaluators read the same data, so their agreement shows that the evaluators agree, not that the data is right. The canonical case is the first entry in the bug inventory: Form 1040 line 9 added line 3a as well as 3b, counting qualified dividends twice. Every test case agreed with it, and so did both evaluators. An outside engine caught it.
Each form or worksheet is a YAML file under forms/2025/. Here is line 5 of the
Qualified Dividends and Capital Gain Tax Worksheet:
- id: qdcg.line5
printed: "5"
label: "Subtract line 4 from line 1. If zero or less, enter -0-"
type: NonNegDollars
expr: { op: subtract_floor0, from: "qdcg.line1", take: "qdcg.line4" }
cite: { doc: i1040gi, locator: 'p. 38, Qualified Dividends and Capital Gain Tax Worksheet, line 5, "Subtract line 4 from line 1. If zero or less, enter -0-"' }
The build fills in each citation's document revision and content hash from the source manifest. There
are no user-defined functions, loops, variables, strings or recursion: the data is a list of
lines like this one, plus year parameters, pinned tables (the Tax Table is stored cell by cell), refusal
gates and the ambiguity register. The one escape hatch, opaque, a host-language function, is counted
and published: 0 of 5,890 lines use it.
Two tools work this layer. The checker fails the build unless every reference resolves, the line
graph has no cycles, every expression type-checks (cents, rates, counts and booleans never mix), every
choose has guards that are disjoint and exhaustive over the range they declare, and every line,
parameter, gate and question carries a complete citation. The renderer writes each line back out in IRS-worksheet English,
beside the IRS's own label and the citation, into rendered/2025/. That output is
committed, so any change to the data shows up in review as a readable English diff.
What it earns. The whole meaning of the data is the meaning of twenty small operations. There is no dangling reference, cycle or unit confusion anywhere in it, and no overlap between alternatives. Gaps are ruled out within the range a set of guards declares; the checker does not yet compare that range with every value an input could take, and below it the evaluator reports "no guard matched" rather than a number. And someone who does not program can sit with the rendering and the printed form and compare them, line against line.
Where it stops. The checker cannot tell a right operand from a wrong one of the same type. Line 9's extra operand was a perfectly well-typed dollar amount.
Here is the claim no layer above can reach: that the encoding says what the page says. No proof applies, so the project builds a different kind of evidence, from constructions made independently of the encoding.
Each model runs with no repository access and no network. The transcription and render reviews run
under the Claude model family. A second family, DeepSeek, reviewed every form and did hand-work for fewer;
its reviews are now inactive by the owner's decision, and its logs and hand-work cases are kept. Every disagreement must be ruled against the page, with the deciding quote, and the logs
are committed under reviews/2025/.
What it earns. For each line, the evidence report
(reports/2025/evidence.md) lists which kinds of independent evidence back
it. It opens with the scoreboard: the share of computed lines with at least one assertion from
outside the Claude model family. Claude wrote most of the encoding, so a Claude reviewer is the reader
most likely to share its misreadings; the scoreboard counts only evidence from somewhere else.
Where it stops. Two models reading the same English can share a misreading. The second family reviewed every form, but only 64 of 136 paired reviews qualified when it was last compared; the rest awaited rulings, were stale, or exceeded the per-form limit on model error. The engines were written by other people, but some of their inputs reach them through the project's adapters, and they mostly reach summary lines (adjusted gross income, taxable income, tax); OpenTaxSolver and UsTaxes reach more of the worksheet steps. And no human line-by-line reading is claimed: the number of lines with a signed human reading is zero. The project's trust statement says it exactly: "human source-reading coverage is limited to the per-line evidence records; independent constructions and their recorded disagreements provide the broader verification."
Around the stack sit tests of whether the tests are any good.
smaller_of for larger_of, drop
a floor, change an operand) to see whether the suite notices. Of 2,722 mutants, 113 survive, each with
a written argument that it computes the same thing as the original.BUG_INVENTORY.md records every defect caught (932 so far)
with how it was caught, its root cause, and why the existing checks missed it. It is
append-only; the suite fails if its committed history changes.r<year>.<month>.<day>.<n> (the newest is the latest release), and its tree passed the whole suite.
A commit on main between releases passed the fast tier, which skips mutation testing, the
comparisons with the independent evaluators (the engine differential and the Lean evaluator) and the
interview length report; its
mutation and evaluator reports, and the engine column of its evidence report, can date from the last
release, and the evidence report names that release. A commit that changes only bookkeeping files (the
task and bug registers, handoffs, docs/) passed the checks that read them. A commit that changes the
mutation tool, the evaluators or the engine differential needs the full suite even on main.What it earns. The tests are sensitive to what they claim to test, the defect record is public and append-only, and each miss is meant to become a new check. Where it stops: a suite catches what it tests for, and a git hook binds only the clones that turn it on.
The descent ends on two different kinds of ground. For computation the ground is proof about the atoms and mechanical agreement between evaluators, and it is firm. For reading the ground is agreement among independent readers, and its firmness varies line by line, in a report you can look up. Beneath both lies a premise no check here touches: that the IRS's procedure is a correct reading of the law.
None of it asks you to trust the authors. Once the dependencies are installed (see Running it), one command rebuilds the data and runs every check, offline:
npm install npm run check-all
Can I do my taxes with it? Not comfortably, yet. The interview runs end to end today for an
estimated 78% of returns, but it is a command-line program that speaks JSON (with a plain local web page
over it, serve), its forms are 2025's while
the first return it is meant to prepare for real is 2026's, and its independent verification is still
climbing.
Coverage. The tool fully covers an estimated 85.9% of individual returns (range 85.4% to 89.5%),
counting a return only when nothing on it is refused (reports/2025/filer_coverage.md).
The estimate starts from IRS Statistics of Income counts and uses household microdata, reweighted to those
counts, for the overlaps between situations. Treat it as an ordering and a rough measure, not a
certified share: most refusal gates have no IRS count to measure them by (180 of the 188 refusal gates
in the forms when the estimate was last run, 2026-11-01; the forms now hold 234, 193 of them situations
refused), so the true figure is lower by their share. Every gate, measured or not, is
in the coverage decision tree. A 2026-11-01 correction counts filers who can be
claimed as a dependent (4.7% of returns, SOI Table 1.7) as refused; the earlier estimate had counted
them as covered, so the first 80% goal is not yet reached.
Now: consolidation and the interview. The measured coverage is just below the first coverage goal of
80%. The order of work (docs/consolidation_charter.md) puts one
architecture with its process rules enforced by tools, and an interview an ordinary person can answer
correctly, ahead of coverage expansion; the first expansion step, Schedule E, would bring the estimate to
about 84%. Tax year 2026 is prepared alongside, on the IRS's drafts. Coverage expansion began on 2026-11-15
(docs/2026-11-15_coverage_expansion_protocol.md). The areas
added that day pass the mechanical interview checks (coverage rows, tick-box groups, interview rules, wording), but
have not had the owner's walk or the written judgment record the interview construction protocol requires; until
then they are not at the standard of the redrafted interview. Parts of steps 1 to 4 below were added that day;
docs/COVERAGE.md lists what each still refuses.
Next, in order of the coverage each adds:
Tax year 2026 is the target: the first return the tool is meant to prepare for real. The tooling for
adopting a new year has been rehearsed on the IRS's posted drafts, and the year's changes are prepared from
them as operations on the 2025 forms (changes/2026/), checked on every commit. When the final forms
appear, expected December 2026 to January 2027, the operations are checked against them, the year is adopted,
and the reviews rerun on the lines that changed (docs/ty2026/ADOPTION.md).
Drafts can never back a release.
Not yet: a finished graphical interface, filling official PDFs, state returns beyond New York's Form IT-201 for a full-year New York City resident (tax year 2025, held at its current scope), and a lawyer's review of the project's legal position.
The full check suite has been run only on macOS. One extraction check reads the archived PDFs with
Apple's PDFKit through Swift; on another platform without Swift that leg is skipped visibly and its
check is not claimed, and on macOS a missing Swift is an error. The background runner
(tools/check_all_bg.sh) copies the tree with APFS clones and needs macOS. Prerequisites: Node and npm;
Lean 4 through elan (version pinned in lean/lean-toolchain); Poppler's pdftotext; Python 3 with
PyYAML; and, on macOS, the Swift toolchain. Setup needs
the network: npm install fetches packages, elan fetches the Lean toolchain, and the outside engines
are installed with tools/engines/setup.sh (OpenTaxSolver must be downloaded by hand; the script says
how). After that, the suite runs offline. Without the engines, the engine step is skipped visibly and
its check is not claimed. Turn on the commit and push guard with git config core.hooksPath tools/hooks.
To start an interview (use synthetic figures; never commit real return data):
npm install && npm run build node engine/dist/main.js interview start --log /tmp/return.jsonl --profile full node engine/dist/main.js interview answer --log /tmp/return.jsonl --input '$person' --value '["taxpayer"]' node engine/dist/main.js interview advance --log /tmp/return.jsonl
Each response is JSON: the status, the next question with its citation, the values with their
derivations, and a plain-text values sheet. interview/README.md covers the
rest, including evaluating a return straight from a file of inputs.
Shown on every interview response, every values sheet and every eval --json or eval --batch
result (a notices list, once per batch):
docs/TRUST.md: every check in detail, with what it guarantees and what it does not.docs/COVERAGE.md: the coverage decision tree, every situation the tool refuses.spec/spec.md and spec/design.md: scope, data model, evidence
rules and architecture.PROJECT_INDEX.md: every directory and naming convention.TASKS.md and BUG_INVENTORY.md: what is undone, and what went wrong.Code: Apache License 2.0 (LICENSE). Data (forms/, params/, tables/, fixtures/,
ambiguities/, interview/): CC0 1.0, dedicated to the public domain (LICENSE-DATA).
The archived IRS sources under sources/ are IRS publications.
Texto de github.com tal como lo publicó, leído de su página y mostrado aquí con el formato de El Autómata. El original, en github.com · Volver a la noticia de El Autómata