# 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

| Élément | Emplacement | Règle |
|---|---|---|
| Chapitre *N* | `manuscript/chapters/chNN.tex` | un seul fichier par chapitre ; commence par `\chapter{Titre}\label{ch:NN}` (titre : `manuscript/chapters/TITRES.json`) |
| Solutions du chapitre | `solutions/chNN.tex` | une `\begin{solution}{ex:NN:k}{titre}` par exercice, dans l'ordre |
| Figures | `assets/figures/chNN/chNN-fig-<slug>.pdf` | PDF vectoriel produit par un script ; jamais de PNG sauf cartes raster |
| Scripts de figures | `analysis/python/figures/chNN_<slug>.py` (ou `analysis/r/chNN_<slug>.R`) | idempotents ; `python3 analysis/python/figures/chNN_x.py` depuis la racine |
| Calculs d'exemples | `analysis/python/cases/chNN_<slug>.py` | impriment les chiffres cités dans le texte ; testés dans `analysis/python/tests/test_chNN.py` |
| Données synthétiques | `data/synthetic/<nom>.csv` + `data/synthetic/README.md` | générées par `analysis/python/cases/generate_all.py` ou un script dédié, **graine fixée** |
| Données réelles | `data/raw/` (brut, jamais modifié) → `data/processed/` | uniquement sources publiques et libres (Statistique Canada, Banque du Canada, Données Québec, SCHL tableaux publics) avec `data/raw/SOURCES.md` (URL, licence, date) |
| Bibliographie | `references/library.bib` | clés existantes réutilisées ; nouvelle entrée = vérifiée (URL/DOI, `urldate`) |
| Registres | `sources/registry.csv`, `verification/{claims,calculations,figures}.csv` | une ligne par source, affirmation vérifiée, calcul, figure |

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)

| Objet | Symbole | Remarques |
|---|---|---|
| Prix observé du bien *j* | $P_j$ | prix de vente ; $P^{\text{aj}}_j$ prix ajusté |
| Valeur estimée | $\hat V$, $V_0$ (valeur présente), $V_T$ (valeur terminale) | |
| Ajustement *k* appliqué au comparable *j* | $A_{jk}$ (monétaire), $a_{jk}$ (proportion) | comparaison : $P^{\text{aj}}_j = P_j + \sum_k A_{jk}$ ; multiplicatif : $P_j\prod_k(1+a_{jk})$ |
| Hédonique | $\ln P_i = \alpha + \mathbf{x}_i\T\boldsymbol\beta + \tau_{t(i)} + \mu_{s(i)} + \varepsilon_i$ | $\tau$ effets temporels, $\mu$ effets spatiaux |
| Coût | $V = V_L + C_N - D_{\text{phys}} - D_{\text{fonc}} - D_{\text{ext}}$ | $V_L$ terrain, $C_N$ coût neuf |
| Revenus | $RBP$, $RBE = RBP - V\&P + R_{\text{autres}}$, $\NOI = RBE - DE$ | $V\&P$ vacance et mauvaises créances ; $DE$ dépenses d'exploitation ; réserves : explicites |
| Capitalisation directe | $V = \NOI_1 / R$ | $R$ taux global ; $\NOI_1$ = première année (prospectif) |
| DCF | $V_0 = \sum_{t=1}^{T} \dfrac{CF_t}{(1+r)^t} + \dfrac{V_T - c_v V_T}{(1+r)^T}$ | $r$ taux d'actualisation, $c_v$ coûts de vente ; $V_T = \NOI_{T+1}/R_T$ |
| Financement | $\LTV = M_0/V_0$, $\DSCR = \NOI/SD$ | $SD$ service de la dette annuel ; hypothèques canadiennes : composition **semestrielle** |
| Taux | $i$ nominal annuel, $i_m$ périodique, $R$ capitalisation, $r$ actualisation, $g$ croissance | $R \approx r - g$ (démontrer les hypothèses) |
| Statistique | $\E$, $\Var$, $\Cov$, $\hat\beta$, $\sigma^2$, IC à 95 % | « intervalle de crédibilité » pour le bayésien |

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