# CLAUDE.md — Projet AIR (Accounting Intermediate Representation)

Auteur du projet : Simon-Pierre Boucher — contact@spboucher.ai Ce fichier est la source de vérité pour Claude Code. Lis-le intégralement avant toute action.

# 0. RÈGLE ABSOLUE — En-tête obligatoire de chaque fichier

CHAQUE fichier créé ou modifié dans ce projet DOIT commencer par un en-tête d'auteur. Aucune exception : code source, tests, docs, scripts, configs, schémas, notebooks.

# Formats selon le type de fichier

Python (.py)

# =============================================================================
# Projet : AIR — Accounting Intermediate Representation
# Auteur : Simon-Pierre Boucher
# Contact : contact@spboucher.ai
# Fichier : <nom_du_fichier>
# Description : <une ligne décrivant le rôle du fichier>
# =============================================================================

TypeScript / JavaScript / Rust / Go / C / Zig (.ts, .js, .rs, .go, .c, .zig)

// =============================================================================
// Projet : AIR — Accounting Intermediate Representation
// Auteur : Simon-Pierre Boucher
// Contact : contact@spboucher.ai
// Fichier : <nom_du_fichier>
// Description : <une ligne>
// =============================================================================

Markdown (.md)

<!--
Projet : AIR — Accounting Intermediate Representation
Auteur : Simon-Pierre Boucher
Contact : contact@spboucher.ai
Fichier : <nom_du_fichier>
-->

YAML / TOML / config (.yaml, .yml, .toml)

# Projet : AIR — Accounting Intermediate Representation
# Auteur : Simon-Pierre Boucher
# Contact : contact@spboucher.ai

JSON : le format JSON n'accepte pas les commentaires. Ajouter une clé au niveau racine :

{ "_author": "Simon-Pierre Boucher <contact@spboucher.ai>", ... }

SQL (.sql)

-- =============================================================================
-- Projet : AIR | Auteur : Simon-Pierre Boucher | contact@spboucher.ai
-- =============================================================================

✅ Avant de terminer toute tâche, vérifie que tous les fichiers touchés portent l'en-tête. ✅ Ajoute un hook / script scripts/check_headers.py qui échoue en CI si un fichier n'a pas l'en-tête.

# 1. RÈGLE ABSOLUE — Recherche web intensive AVANT de coder

Ce projet touche des domaines où tes connaissances peuvent être incomplètes ou périmées : normes comptables, fiscalité, API des ERP, design de compilateurs. Tu ne dois JAMAIS deviner.

# Protocole de recherche obligatoire

Avant chaque nouveau module ou décision de design importante :

1. Fais au minimum 3 à 5 recherches web ciblées sur le sujet (spécifications, docs officielles, articles récents, RFC, standards existants).
2. Consulte les sources primaires : documentation officielle des ERP (SAP, QuickBooks, Xero, Odoo, Oracle NetSuite, Sage, Dynamics), sites gouvernementaux (ARC/Revenu Québec pour TPS/TVQ, IRS pour sales tax US), sites des normalisateurs (IFRS Foundation, FASB pour US GAAP, CPA Canada pour ASPE).
3. Documente tes trouvailles dans docs/research/<sujet>.md (avec en-tête auteur) : sources, dates de consultation, résumé, décisions prises.
4. Vérifie l'existant : avant d'inventer un format, recherche les standards déjà en place (voir §1.1) pour t'en inspirer ou t'y aligner.
5. Si une info fiscale ou normative est incertaine ou pourrait avoir changé : recherche web obligatoire, jamais de mémoire seule.

# 1.1 Sujets à rechercher intensivement (checklist de démarrage)

• Standards de données comptables existants : XBRL / XBRL-GL, ISO 20022, UBL (Universal Business Language), Peppol, OFX, camt.053, EDIFACT, hledger/beancount/ledger-cli (plain text accounting), REA ontology (Resources-Events-Agents), ValueFlows, OpenCorporates schemas.
• Architecture LLVM : structure de l'IR, forme SSA, pass manager, backends, tablegen — pour transposer correctement les concepts.
• API ERP : SAP OData/BAPI/IDoc, QuickBooks Online API (JournalEntry, Invoice, Payment), Xero Accounting API, Odoo XML-RPC/ORM, NetSuite SuiteTalk, Sage Intacct.
• Normes comptables : IFRS (IFRS 15 revenus, IFRS 16 locations, IAS 21 devises), US GAAP (ASC 606, ASC 842), ASPE canadien (chapitres pertinents).
• Fiscalité : TPS/TVQ Canada (taux actuels, règles de lieu de fourniture), sales tax US (nexus, taux par État), TVA UE si pertinent.
• Event sourcing & double-entry engines : Martin Fowler (Accounting Patterns), TigerBeetle, Formance Ledger, Modern Treasury, Increase, Stripe Ledger — architectures de grands ledgers.
• Rapprochement bancaire & formats bancaires : ISO 20022 camt, MT940, Plaid/Flinks API.
• Structured outputs LLM : meilleures pratiques actuelles pour extraction structurée (JSON Schema, tool use, validation).

⚠️ Les taux de taxes, seuils de capitalisation, et versions d'API changent. Toujours vérifier la date des sources et privilégier les documents officiels récents.

# 2. Vision du projet

AIR est à la comptabilité ce que LLVM est à la compilation.

Problème : chaque ERP (SAP, Oracle, QuickBooks, Xero, Sage, Odoo, Dynamics) réinvente le même modèle comptable. Les LLM sont excellents pour comprendre ("cette facture = 3 ordinateurs payés par Visa") mais peu fiables pour appliquer des centaines de règles comptables/fiscales sans erreur.

Solution : séparer la compréhension (LLM) de l'application des règles (compilateur déterministe).

Facture / Email / Banque / POS / API
            ↓
        LLM (extraction)
            ↓
        AIR (événement économique, PAS une écriture)
            ↓
        Passes (validation, taxes, FX, fraude, approbation)
            ↓
        Compilation déterministe (AIC)
            ↓
   Backends : SAP | QuickBooks | Xero | Odoo | IFRS | US GAAP | ASPE

Principe fondamental : le LLM ne produit JAMAIS une écriture comptable finale. Il produit uniquement de l'AIR. Le compilateur applique les politiques, normes et taxes de façon déterministe, traçable et testable.

# 3. Composants de l'écosystème

# 3.1 AIR — le format

Un événement économique (EconomicEvent), pas un journal. Exemple cible :

EconomicEvent:
  id: evt_01H...            # ULID
  type: Sale
  seller: company:acme
  buyer: customer:cust_123
  items:
    - sku: chair-std
      qty: 3
      unit_price: {amount: 333.33, currency: CAD}
  payment:
    method: card.visa
    gross: {amount: 1150.00, currency: CAD}
  delivery: {status: pending, expected: 2026-09-01}
  tax:
    jurisdiction: CA-QC
    codes: [GST, QST]
  meta:
    source: {kind: invoice_pdf, uri: "s3://...", ocr_score: 0.97}
    llm: {model: "...", confidence: 0.93, reasoning_hash: "sha256:..."}
    policy_version: "2026.08"
    timestamps: {ingested: ..., approved: null}
    approver: null

Exigences du format :

• Schéma formel (JSON Schema + types Pydantic/TypeScript générés).
• Forme SSA comptable : chaque montant a une origine unique et traçable (Invoice → Tax → Payment → FX → Settlement → Write-off). Implémenter un graphe de provenance immuable.
• Versionné : air_version dans chaque document ; migrations explicites.
• Immutabilité + diff : compilation incrémentale — si une facture change, on recompile uniquement le delta (comme Git), avec écritures de contrepassation générées automatiquement.

# 3.2 AIC — le compilateur

Pipeline de passes ordonnées :

OCR pass → Classification pass → Tax pass → FX pass →
Fraud pass → Approval pass → Optimization passes → Posting pass

Passes d'optimisation :

• Fusion : 50 paiements identiques → 1 batch.
• Netting : 100 remboursements → compensation.
• Reclassement : Expense → Asset selon politiques (ex. capitalisation > 5000 $).
• Détection doublons : hachage + similarité.
• Invariant permanent : Assets = Liabilities + Equity vérifié après CHAQUE passe. Toute violation = échec de compilation avec diagnostic précis (comme les erreurs clang : localisation, cause, suggestion).

# 3.3 ALSL — le langage de règles

Déclaratif, versionné, testable :

policy capitalization_ca:
  when event.type == Purchase and event.amount > 5000 CAD
  then classify as Asset(class: equipment)

policy tax_quebec:
  when event.jurisdiction == CA-QC
  then apply GST(5%), QST(9.975%)

⚠️ Les taux ci-dessus sont des exemples — vérifie les taux actuels par recherche web avant de les coder, et ne les code JAMAIS en dur dans le moteur : ils vivent dans les policies ALSL versionnées.

# 3.4 Backends

Chaque backend implémente une interface commune Backend:

• capabilities() — ce que la cible supporte
• compile(journal: CompiledJournal) -> TargetPayload
• post(payload) -> PostingReceipt
• reverse(receipt) -> ReversalReceipt

Ordre de développement : 1) Backend générique CSV/journal, 2) QuickBooks Online (API la plus accessible), 3) Xero, 4) Odoo, 5) SAP (le plus complexe — recherche approfondie requise sur OData/BAPI).

# 3.5 SDK Agents — les "syscalls"

Les agents IA n'accèdent JAMAIS au grand livre directement. API exclusive :

CreateEconomicEvent() | Validate() | Compile() | Post() | Reverse()
Merge() | ClosePeriod() | Reconcile() | GenerateReport()

Chaque appel est journalisé (audit log append-only, hash-chaîné).

# 4. Architecture technique

# Stack recommandée (à valider par recherche)

• Cœur (AIR + AIC + passes) : Rust (fiabilité, typage fort) OU Python typé strict (vitesse de dev). Décision à documenter dans docs/adr/0001-language.md après recherche comparative.
• Schémas : JSON Schema comme source de vérité → génération de types Rust/Python/TS.
• Montants : JAMAIS de float. Décimal fixe (rust_decimal / Python Decimal), arrondi banker's rounding documenté par juridiction (à vérifier par recherche : règles d'arrondi TPS/TVQ).
• Stockage : event store append-only (PostgreSQL) + projections.
• ALSL : parser dédié (pest/lark) ; commencer par un sous-ensemble YAML avant le DSL complet.

# Structure du dépôt

air/
├── CLAUDE.md
├── README.md
├── docs/
│   ├── adr/                 # Architecture Decision Records
│   ├── research/            # Résultats de recherches web (OBLIGATOIRE)
│   └── spec/                # Spécification formelle AIR / ALSL
├── schemas/                 # JSON Schemas versionnés
├── core/                    # AIR types + graphe de provenance
├── aic/                     # Compilateur + pass manager
│   └── passes/
├── alsl/                    # Parser + évaluateur de règles
├── backends/
│   ├── generic_csv/
│   ├── quickbooks/
│   ├── xero/
│   └── odoo/
├── kernel/                  # Services (ledger, tax, fx, policy, audit...)
├── sdk/                     # SDK agents (syscalls)
├── ingestion/               # OCR + extraction LLM → AIR
├── tests/
│   ├── golden/              # Cas dorés : AIR → écritures attendues
│   ├── property/            # Property-based (invariant bilan)
│   └── fixtures/            # Factures réelles anonymisées
└── scripts/
    └── check_headers.py     # Vérifie les en-têtes auteur

# 5. Exigences de qualité non négociables

1. Déterminisme : même AIR + mêmes policies = mêmes écritures, toujours. Aucun appel LLM dans le compilateur.
2. Invariant comptable : partie double vérifiée à chaque étape ; property-based testing (hypothesis/proptest) sur Assets = Liabilities + Equity.
3. Traçabilité totale : de chaque ligne d'écriture, on remonte à l'événement source, au document, au score OCR/LLM, à la version de policy, à l'approbateur.
4. Golden tests : chaque fonctionnalité comptable = cas dorés validés contre des exemples de la littérature comptable (trouvés par recherche web, sources citées).
5. Diagnostics de qualité compilateur : erreurs précises, localisées, avec suggestions.
6. Aucun taux/seuil en dur : tout paramètre fiscal ou de politique vit dans ALSL.
7. En-têtes auteur partout (voir §0), vérifiés en CI.

# 6. Plan de développement par phases

Phase 0 — Recherche (docs/research/) : compléter la checklist §1.1, produire un rapport par sujet, rédiger les ADR fondateurs (langage, alignement ou non avec XBRL-GL/UBL/REA, modèle de montants).

Phase 1 — Cœur : schéma AIR v0.1, types, graphe de provenance, invariant bilan, backend CSV générique, 20 golden tests (vente simple, achat, taxes QC, FX, remboursement).

Phase 2 — Compilateur : pass manager, passes Tax (CA-QC d'abord) / FX / Validation, ALSL v0.1 (YAML), compilation incrémentale (diff + reversal).

Phase 3 — Backend réel : QuickBooks Online (sandbox), OAuth, idempotence, Post/Reverse.

Phase 4 — Ingestion : PDF → extraction structurée LLM → AIR, avec scores de confiance et file d'approbation humaine sous seuil.

Phase 5 — Kernel + SDK : services, syscalls, audit log hash-chaîné, agent de démonstration.

Phase 6 — Optimisations : fusion, netting, doublons, rapprochement bancaire (camt.053/MT940).

# 7. Workflow de travail attendu de Claude

À chaque session :

1. Relire ce CLAUDE.md.
2. Identifier la tâche → recherche web d'abord si le sujet touche normes, taxes, API externes, ou standards.
3. Consigner la recherche dans docs/research/.
4. Écrire les tests avant/avec le code (golden + property).
5. Coder avec en-têtes auteur.
6. Lancer scripts/check_headers.py + suite de tests.
7. Mettre à jour la doc/ADR si une décision de design a été prise.

# Interdits

• ❌ Coder une règle fiscale de mémoire sans source web vérifiée et citée.
• ❌ Utiliser des floats pour des montants.
• ❌ Laisser le LLM produire des écritures finales.
• ❌ Créer un fichier sans l'en-tête Simon-Pierre Boucher / contact@spboucher.ai.
• ❌ Casser l'invariant de la partie double, même temporairement.

Fin du CLAUDE.md — Projet AIR — Simon-Pierre Boucher — contact@spboucher.ai