Tax Engine Guardrails
The small set of rules that keep Orchard Tax deterministic and safe.
Non-negotiables
Engine math stays in
packages/tax-engine, not in docs, UI, or extraction code.Every constant is cited, and every computed line carries
sources and cites.Money stays in integer cents until the presentation layer formats it.
Overrides are explicit, reasoned, and test-covered.
Golden vectors prove the happy paths and the awkward ones.
Do not
| Do not | Why |
|---|---|
| Hardcode naked numbers in calculators | They drift and nobody can audit where they came from. |
| Let LLM output decide tax math | The model may classify or phrase, but the math must stay deterministic. |
| Introduce a second engine in docs or UI | The codebase needs one source of truth for every line. |
| Skip the verify step | Extraction is a suggestion until the preparer confirms it. |
Contribution loop
- Add or update the rule registry.
- Add a focused unit test or golden vector.
- Update the relevant docs page if the workflow or source trail changed.
- Run the focused checks before widening the diff.
When to widen the work
- If a rule change affects multiple lines, update the shared registry first.
- If a form becomes supported, add the engine coverage and the docs matrix together.
- If a deployment rule changes, update the private alpha page as well as the runbook.