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é.