Rules and Citation Philosophy
How Orchard Tax keeps every rule, amount, and diagnostic auditable.
The rule contract
Orchard Tax treats a rule as data, not prose. A rule should tell you three things at once:
- What the value is.
- Where the value came from.
- Which year or law change it belongs to.
That is why tax constants are stored as { value, cite }, and why computed
lines carry both sources and cites.
What counts as a good cite
| Good cite | Why it works |
|---|---|
| IRS form instructions or revenue procedure | Stable enough for a tax-year rule and easy to audit later. |
| Statute or public law reference | Useful when the number comes from a law change rather than a form line. |
| Repo link to the reviewed plan/spec | Good for implementation context, not for the numeric source itself. |
What does not count
- A memory of the amount.
- A calculator comment that only says "per IRS".
- A duplicated number without the source that proved it.
- A diagnostic message that implies a rule but cannot point to one.
Working rules
If it is not cited, it is not a rule.
The engine may use a value only after the source has been verified and the cite is present. The docs can summarize the rule trail, but they do not replace the registry.
- Verify TY2025 values against IRS sources before updating the registry.
- Keep each rule in one place, then flatten it through
allRules(2025)for the rules page. - Update golden vectors when a rule changes a computed line.
- Keep diagnostics deterministic so a reviewer sees the same warning every time the same inputs are rendered.
Why Orchard cares
The product is a review system as much as a prep system. If a preparer cannot click through from a line to the source document and then on to the rule that shaped the number, the draft is still too opaque.