spb/air Public MIT

1<!--2Projet : AIR — Accounting Intermediate Representation3Auteur : Simon-Pierre Boucher4Contact : contact@spboucher.ai5Fichier : CONTRIBUTING.md6-->78# Contributing to AIR910Thank you for considering a contribution! AIR has a few **non-negotiable11rules** that CI enforces — read them before opening a PR.1213## The rules (enforced)14151. **Author header on every file.** Every source/doc/config file starts with16   the project header (see any file for the format). `python scripts/check_headers.py`17   must pass — CI fails otherwise.182. **No floats for money — ever.** Amounts, quantities, rates are `Decimal`19   in code and strings in JSON/YAML. Floats are rejected at every boundary.203. **No tax rate, threshold, or rounding mode in code.** All fiscal and policy21   parameters live in versioned ALSL policy sets with a mandatory source22   citation. The loader rejects uncited rates.234. **Research before rules.** Anything touching tax law, accounting standards,24   external APIs, or data formats needs a cited report in `docs/research/`25   (official sources, consultation dates). Never from memory.265. **The compiler stays deterministic.** No LLM, network, or clock inside AIC.27   Same document + same policies = byte-identical journal.286. **The invariant is sacred.** `Assets = Liabilities + Equity` is verified29   after every compiler pass. New passes must keep entries balanced.307. **Append-only history.** Corrections are reversal entries; nothing posted31   is ever edited or deleted.3233## Workflow3435```bash36python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"37.venv/bin/python -m pytest tests/ -q --ignore=tests/test_llm_live.py   # offline suite38python3 scripts/check_headers.py39```4041- Write tests with the code: golden cases for accounting behavior42  (`tests/golden/cases/*.yaml`), property tests for invariants, unit tests43  for mechanics.44- New event types need: posting rules, golden cases, and a spec update.45- New backends implement `backends/base.py` (`capabilities/compile/post/reverse`)46  and must be fully testable offline (mock transport pattern —47  see `backends/quickbooks/`).48- Architecture decisions get an ADR in `docs/adr/`.4950## What makes a good first contribution5152- A new ALSL policy set for another jurisdiction (with cited research)53- The beancount/hledger export backend (near-free per the research)54- Reference-first matching (`EndToEndId`) in reconciliation55- A Xero or Odoo backend with an offline mock transport5657*Author: Simon-Pierre Boucher — contact@spboucher.ai*58