moteurs/AGENTS.md

# AGENTS.md — @transformer/moteurs

## Ce que c'est

Moteurs de calcul purs pour la rénovation et l'autonomie d'une maison, partagés par
`calculs.trans-former.fr` (repo `astro-pro`) et `plateforme.trans-former.fr` (repo `reinnover`).
Code et coefficients sourcés ; **JAMAIS de prix**. Dépôt Gitea public `jules/moteurs`, nom npm
`@transformer/moteurs`, consommé par étiquette : `git+https://git.trans-former.fr/jules/moteurs.git#vX.Y.Z`.

Version `v0.1.0` (LOT P1.0, 28/09/2026) : `commun` (contrat, coefficients, contexte, géométrie,
argent, validation) et `autonomie` (noyau V2 extrait de calculs, trois moteurs d'axe, intégrateur,
taux de couverture, prix des options). `isolation`, `autoconstruction`, `estimatif` arrivent en `v0.2.0` (P1.3).

## Règles opposables (un agent qui les viole a tort, quel que soit le prompt)

1. `calculer(entrees, donnees)` ne lit ni réseau, ni disque, ni horloge, ni DOM, ni globale, ni aléa.
   Mêmes entrées + mêmes données = même résultat. `test/paquet.test.mjs` grep `src/` et refuse
   `fetch`, `require`, `node:*`, `process`, `Date`, `Math.random`, `console`, `localStorage`, `import *.json`.
2. Les données (prix, barèmes, options, tables) entrent en paramètre, validées par `valider(table, json)`
   par l'appelant. Aucune constante de prix dans `src/`. Une mise à jour de prix ne produit jamais une
   version du paquet. `algo-config.json` est une donnée : livrée dans `fixtures/`, injectée, jamais importée.
3. Chaque coefficient physique existe **une fois**, dans `src/commun/coefficients.ts`, avec `valeur`,
   `source`, `date` (et `note` pour le veto). Tout coefficient lu apparaît dans `resultat.sources` (les
   moteurs d'axe enregistrent les lectures de la table par Proxy) ; toute valeur par défaut appliquée
   dans `resultat.avertissements`. Les heuristiques de conception (poids, modulateurs, matrices,
   tolérances) restent dans `algo-config.json`, marquées non sourcées. La table lisible par Jules est
   `docs/CONSTANTES.md` ; sans veto sous une semaine, la table du code est la référence.
4. Aucune dépendance de production (`typescript` en dev seulement). `dist/` (JS ESM + `.d.ts`) est
   **committé** à chaque étiquette ; `schemas/*.schema.json` est réécrit par `npm run build` depuis
   `src/commun/schemas.ts` (source de vérité).
5. Une formule change → nouvelle étiquette (patch : correction ; mineur : nouvelle sortie ; majeur :
   entrée modifiée) et montée de version chez les deux consommateurs le même jour. **Jamais de branche
   épinglée** chez un consommateur. `src/version.ts` = `package.json` (test).
6. Tests hors ligne (`node --test test/`, sur `dist/`), fixtures figées et datées dans `fixtures/`.
   Les 28 tests d'origine du cœur autonomie (`test/noyau-origine.test.mjs`) et le test de découpage par
   axe (`test/decoupage.test.mjs`, épingle générée depuis le code d'astro-pro) **ne se désactivent
   jamais**. Refiger une épingle (`scripts/pin-origine.mjs`, `npm run ecarts -- --ecrire <date>`) est un
   acte volontaire, écrit dans le commit, après relecture de `docs/CONSTANTES.md`.
7. Français avec accents dans les libellés, la doc et les messages ; identifiants en français sans
   accents (`sous_total_eur_ht`, `taux_couverture`) ; codes d'axe internes `eau` / `energie` / `alim`
   (les postes publiés disent `alimentation`).
8. Un module du noyau (`src/autonomie/noyau/`) se modifie pour corriger un bug **avec un test qui le
   montre** et une ligne dans le `CHANGELOG` du commit ; jamais « en passant ». Les bugs latents connus
   sont listés dans le RECAP du lot P1.0 (scoreurs sans parse de `parametre_dim`, `_conflit_avec` perdu,
   Intl dans les messages de `reajuste`).

## Carte du dépôt

```
src/
├── version.ts                  étiquette portée par chaque résultat (= package.json)
├── commun/
│   ├── contrat.ts              Source, Resultat, Moteur, Trace (collecteur sources/avertissements)
│   ├── coefficients.ts         LA table (valeur, source, date, note) + verifieTableCoefficients
│   ├── contexte.ts             commun.contexte : CP → département (2A/2B, 97x) → zone RT, biogéo, pluvio, DJU
│   ├── geometrie.ts            commun.geometrie : emprise, niveaux, hauteur, pente, mitoyenneté → parois, SHAB, volume
│   ├── argent.ts               fourchettes, arrondis, mensualité / annuité / coût du crédit
│   ├── schemas.ts              forme de chaque JSON de données (→ schemas/*.schema.json au build)
│   └── valider.ts              valider(table, json) : type, required, properties, items, enum, minItems
└── autonomie/
    ├── noyau/                  V2 de calculs, sans singleton : algo (selectionner + finaliseSelection),
    │                           pondere-axes, alloue-budget, selectionne-poste, adequation, scoreurs,
    │                           dimension, couplages (copie, ne mute plus), reajuste, axes-actifs, types
    ├── axe.ts                  fabrique des moteurs d'axe (selectionnePoste + finaliseSelection à un axe + taux)
    ├── eau.ts · energie.ts · alimentation.ts
    ├── integrateur.ts          contexte + poids + budgets ; mode 'global' (= calculs) ou 'par_axe' (= plateforme)
    ├── taux.ts                 couverture eau / énergie (autoconsommation appliquée) / alimentation
    └── prix.ts                 prixOption, prixPreset, presetLePlusProche (données d'options, pas de montant)
schemas/    fixtures/    test/    scripts/    docs/CONSTANTES.md    dist/
```

## Comment publier

```
npm test                # pretest = build ; 4 fichiers de tests + les 28 d'origine, tous hors ligne
git add -A && git commit
git tag vX.Y.Z && git push && git push --tags
```
puis monter `#vX.Y.Z` dans `reinnover/package.json` (et `astro-pro` à partir de P1.5) **le même jour**,
`npm install` chez le consommateur, commit du lockfile.

## Ce qu'un agent ne fait pas ici

Lire NocoDB · appeler une API · écrire un prix ou un barème · importer depuis `astro-pro` ou
`reinnover` · importer un JSON dans `src/` · désactiver ou affaiblir un test · épingler une branche ·
ajouter une dépendance de production · publier sans `dist/` reconstruit et committé.