# CONVENTIONS.md — Règles de rédaction et de production (obligatoires)

Ce document s'adresse à toute personne ou agent qui rédige un chapitre, un script, une figure ou une solution. Il complète CLAUDE.md (mission) et prévaut sur les habitudes personnelles. Lire en entier avant d'écrire.

# 1. Arborescence et propriété des fichiers

Le chapitre doit compiler seul : tools/compile_chapter.sh NN (0 erreur, 0 référence non définie, idéalement 0 overfull hbox). Ne jamais déclarer un chapitre terminé sans avoir exécuté cette commande et lu le résumé.

# 2. Structure obligatoire d'un chapitre (ordre)

1. \chapter{…}\label{ch:NN} puis un paragraphe d'ouverture (3-6 phrases : enjeu, place dans l'ouvrage).
2. \begin{objectifs} : 4 à 7 puces « À la fin de ce chapitre, le lecteur sait… ».
3. Sections numérotées (\section, \subsection ; pas de \subsubsection au-delà du nécessaire). Dérivations complètes, équations numérotées (equation/align, étiquettes eq:NN:slug), définitions dans definition, résultats dans theoreme/proposition avec proof.
4. Au moins un exemple intégral (exemple) dont chaque chiffre provient d'un script de analysis/python/cases/ (nommer le script dans le texte ou dans \tabsource).
5. Au moins deux figures (si justifié) et des tableaux (unités dans les en-têtes, \tabsource{} sous le tableau, \figsource{} sous la légende).
6. Une analyse de sensibilité (tableau ou figure).
7. \begin{quebec} : règles, institutions, données propres au Québec avec source et date de consultation.
8. \begin{erreurs} (erreurs fréquentes) et \begin{limites}.
9. \begin{synthese} (à retenir).
10. \section*{Exercices} : 4 à 8 exercices de difficulté croissante (\begin{exercice}[niveau 1-3]{Titre}{ex:NN:k}), sans solution dans le chapitre.
11. \section*{Pour aller plus loin} : bibliographie commentée (3-8 titres, \textcite/\parencite).

Cible : 9 000 à 14 000 mots par chapitre (prose), 3-6 figures, 4-8 tableaux, 8-15 équations numérotées, 2-4 exercices de niveau 3. Les chapitres de cas (45-48) sont plus longs (12 000-18 000 mots) et plus riches en tableaux.

# 3. Style rédactionnel

• Français québécois soutenu, prose magistrale. Les listes à puces sont réservées aux objectifs, aux synthèses, aux étapes de calcul et aux listes de contrôle ; tout le reste est en paragraphes développés.
• Vouvoiement proscrit ; « le lecteur », « l'évaluateur », « l'analyste ». Pas d'anglicismes non nécessaires ; l'équivalent anglais est donné une fois entre parenthèses puis au glossaire : revenu net d'exploitation (RNE, net operating income).
• Sigles français : RNE (NOI), RCD (DSCR), RPV (LTV), TRI (IRR), VAN (NPV), REB/RBE (revenu brut effectif), RBP (revenu brut potentiel), PHMU (plus haute et meilleure utilisation), MRB (multiplicateur du revenu brut), taux global d'actualisation (TGA) = taux de capitalisation global.
• Distinguer toujours : prix (observé), valeur marchande (estimation), valeur au rôle (fiscale, date de référence), valeur d'investissement (propre à un investisseur), coût. Ne jamais écrire « la valeur est de… » pour un prix observé.
• Distinguer exigence professionnelle (norme OEAQ/IVS/CUSPAP), droit applicable (loi, règlement, jurisprudence), pratique courante et modèle expérimental. Formules : « la norme exige », « la loi prévoit », « il est d'usage », « on peut modéliser ».
• Renvois : \cref{} produit le nom SANS article (« chapitre 17 », « figure 16.2 », « tableau 16.4 », « équation (16.3) », « exercice 16.5 ») ; l'auteur écrit l'article et la préposition : « le \cref{ch:17} », « au \cref{ch:17} », « à la \cref{fig:16:nuage} », « l'\cref{eq:16:local} », « du \cref{tab:16:grille} ». En début de phrase, \Cref{} (majuscule, sans article) ou « Le \cref{} ».
• Toute affirmation juridique cite l'article (ex. « art. 1955 C.c.Q. ») et la source bibliographique, avec date de consultation si c'est une page web ; toute statistique cite l'organisme, le tableau et la période.
• Rien d'inventé. Pas de référence, de loi, de norme, de chiffre « plausible ». En cas de doute : écrire la chose comme non vérifiée dans limites et l'inscrire dans verification/claims.csv avec statut=non_verifie.

# 4. Notation mathématique (uniforme dans tout l'ouvrage)

Macros disponibles (styles/traite-qc.sty) : \NOI (RNE), \VAN, \TRI, \DSCR (RCD), \LTV (RPV), \E, \Var, \Cov, \T (transposée), \argmin, \dd, \abs{}, \norm{}.

# 5. Unités et nombres (siunitx, conventions québécoises)

• \dollars{452500} → 452 500 $ ; \pct{4.75} → 4,75 % ; \parmsq{3250} → 3 250 $/m² ; \msq{145} ; \pisq{1560} ; \num{1234.5} ; \qty{12}{\logement}.
• Dans les tableaux, colonnes S[table-format=7.0] pour les nombres, unité dans l'en-tête entre accolades : {Prix (\$)}.
• Superficies en m² (pi² en second si utile) ; conversion 1 m² = 10,7639 pi². Taux : pourcentage annuel, deux décimales ; points de base \qty{25}{\pb}.
• Dates : « 1^er^ juillet 2025 » en toutes lettres dans la prose ; ISO (2025-07-01) dans les tableaux et CSV.
• Dollars canadiens courants ; préciser l'année de référence des coûts et des prix.

# 6. Figures

• Palette et style imposés : from traite.style import setup, palette (analysis/python/traite/style.py) ; setup() configure Matplotlib (Source Sans 3, surface #fcfcfb, grille discrète, 2 pt de trait). Couleurs par le rôle : catégoriel palette.cat[i] (ordre fixe, max 6 séries, max 3 dans un nuage de points), séquentiel palette.seq (bleu clair→foncé), divergent palette.div (bleu–gris–rouge). Pas de double axe y. Pas d'arc-en-ciel. Une légende dès 2 séries, étiquettes directes quand c'est lisible, texte en encre (jamais de la couleur de la série).
• Dimensions : largeur 135 mm (pleine colonne) ou 65 mm (demi) ; fig.savefig(path, bbox_inches="tight") ; polices 8-9 pt.
• Légende LaTeX : \caption{Phrase complète qui dit ce que montre la figure et ce qu'il faut y voir.} puis \figsource{\synth{script analysis/python/figures/chNN_x.py, graine 20261031}} ou \figsource{Statistique Canada, tableau 18-10-0205-01, consulté le 2026-10-31 ; calculs de l'auteur}.
• Chaque figure est inscrite dans verification/figures.csv : fichier,chapitre,script,donnees,type_donnees(synthetique|reelle|schema),legende_courte,statut.
• Schémas conceptuels : TikZ directement dans le .tex (type schema), aussi inscrits dans figures.csv (script = fichier tex).

# 7. Tableaux

booktabs (\toprule/\midrule/\bottomrule), jamais de filets verticaux. \caption au-dessus, \label{tab:NN:slug}, \tabsource{} dessous. Unités dans les en-têtes. Tableaux longs : longtable. Les chiffres proviennent d'un script : le nommer dans \tabsource.

# 8. Données synthétiques et réelles

• Toute donnée simulée est identifiée : encadré synthetique à sa première apparition dans le chapitre (nom du fichier, script, graine, principes de calibration avec sources), \synth{} dans chaque \tabsource/\figsource qui en dépend, et mention [données synthétiques] dans la légende courte de figures.csv.
• Les paramètres de calibration (ordres de grandeur réalistes) sont documentés dans data/synthetic/calibration.json avec, pour chaque valeur, un source_id du registre. Une valeur sans source est marquée "source_id": "NON_VERIFIE" et signalée.
• Modules partagés obligatoires : analysis/python/traite/cas1.py (sélection du ch. 16, modèle hédonique de référence, ajustements dérivés, prédiction et intervalle), cas2.py (triplex : revenus, dépenses, RNE, indicateurs des ventes de plex), cas3.py (12 logements : RNE normalisé, taux extraits, DCF, financement), cas4.py (portefeuille : sommaire, croissance, effets régionaux). Tout chapitre qui cite un chiffre d'un cas l'obtient de ces fonctions ; on ne recalcule pas un RNE « à la main ». Si une fonction manque, on l'ajoute au module avec un test, sans changer les résultats existants.
• Les quatre dossiers de cas : data/synthetic/cas1_gatineau_*.csv, cas2_quebec_triplex_*.csv, cas3_montreal_12log_*.csv, cas4_portefeuille_*.csv ; générés par analysis/python/cases/generate_all.py. Les chapitres 16-44 réutilisent ces dossiers pour leurs exemples quand c'est pertinent (cohérence des chiffres entre chapitres).

# 9. Citations et sources

• \textcite{clé} (sujet de phrase) / \parencite{clé} (parenthèse) ; lois : \parencite[art.~1955]{ccq}.
• Les clés existantes (references/library.bib) sont réutilisées ; une nouvelle entrée exige : titre exact, auteur/organisme, année, éditeur ou revue, DOI ou URL, urldate, note (version, date d'entrée en vigueur). Les entrées non vérifiées ne sont pas ajoutées : elles sont listées dans verification/claims.csv avec statut=non_verifie.
• Pas de reproduction de tableaux protégés (RSMeans, Marshall & Swift, normes OEAQ/IVS in extenso). On cite, on paraphrase, on renvoie.
• Registre des sources : sources/registry.csv (id,type,titre,organisme,version_ou_date,url,date_consultation,statut,utilise_dans,notes) ; statut ∈ {verifie, partiellement_verifie, non_verifie, inaccessible}.

# 10. Vérification des calculs

• Chaque exemple chiffré a un script analysis/python/cases/chNN_<slug>.py qui recalcule et imprime les valeurs ; un test analysis/python/tests/test_chNN.py vérifie les identités (ex. VAN au TRI = 0, solde d'amortissement nul, $V = \NOI/R$, somme des ajustements = écart ajusté) et les valeurs citées (tolérance déclarée).
• Inscrire chaque calcul dans verification/calculations.csv : id,chapitre,description,script,test,resultat_attendu,resultat_obtenu,statut,date.
• La bibliothèque commune analysis/python/traite/ (finance, coût, comparables, hédonique, synthèse) est la seule source des formules financières : ne pas réécrire une fonction qui y existe ; l'enrichir (avec tests) si une fonction manque.

# 11. Ce qui est interdit

Placeholders (« à compléter », « lorem »), figures sans script, chiffres sans provenance, lois ou normes citées sans vérification, tableaux copiés de sources protégées, réordonnancement du plan sans décision de l'auteur, modification de styles/ ou de main.tex par un rédacteur de chapitre (demander), compilation « supposée réussie ».

# 12. Livraison d'un chapitre (liste de contrôle)

• tools/compile_chapter.sh NN : OK, 0 référence non définie, overfull ≤ 3
• python3 -m pytest -q analysis/python/tests/test_chNN.py : vert
• figures PDF présentes + lignes dans verification/figures.csv
• lignes dans verification/calculations.csv et verification/claims.csv
• nouvelles sources dans sources/registry.csv + references/library.bib
• solutions/chNN.tex complet (une solution par exercice, calculs détaillés)
• rapport bref dans verification/chapters/chNN.md : mots, figures, tableaux, équations, exercices, points non vérifiés