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. L'épingle d'origine ne se regénère pas pour absorber un correctif : depuis v0.1.1 elle porte des défauts corrigés, et chaque cellule qui s'en écarte est figée dans fixtures/ecarts-correctifs-<date>.json (node scripts/ecarts-correctifs.mjs --ecrire <date>) ; une cellule absente de ce fichier doit rester identique à l'origine. Les tests de correctifs (test/correctifs-v0.1.1.test.mjs) et de monotonie (test/monotonie.test.mjs) ne se désactivent pas non plus.
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). Invariants tenus depuis v0.1.1 : une typologie n'apparaît qu'une fois par axe, un poste n'a qu'une ligne (la quantité est dimension), une ligne forcée par couplage est lâchée dès que plus rien ne la requiert, le journal n'écrit chaque FORCE qu'une fois.

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 ajouter un moteur (P1.3 : isolation, autoconstruction, estimatif → v0.2.0)

1. Ses tables de données : une entrée par table dans src/commun/schemas.ts (NomTable s'étend seul, valider suit) ; les fixtures datées dans fixtures/ ; jamais un prix dans src/.
2. Ses coefficients physiques : dans TableCoefficients + COEFFICIENTS (valeur, source, date, note) et dans fixtures/coefficients-2026-05.json (le test exige les mêmes clés ; pour une grandeur absente du code d'origine, mettre la même valeur et le dire en source), puis une ligne dans docs/CONSTANTES.md.
3. Le moteur : src/<domaine>/<nom>.ts exporte un Moteur<E, D, S> avec un id '<domaine>.<nom>', construit son résultat avec Trace (chaque coefficient lu → trace.source, chaque défaut → trace.avertit), rend VERSION. Un index.ts par domaine ; l'id ajouté à MOTEURS (src/index.ts).
4. package.json : une entrée exports par sous-chemin (./isolation, …) ; version mineure.
5. Tests hors ligne dans test/<domaine>.test.mjs (contrat : déterminisme, sources, avertissements, un cas chiffré à la main), npm test vert, dist/ reconstruit, étiquette, montée chez reinnover.

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