fix(zero-debt): éliminer toute la dette technique actionnable identifiée

Audit récursif à 2 tours sur l'état du repo après le commit 652752d
(découpage statistics.py). 3 agents Explore tour 1 + 2 agents tour 2
+ vérifications personnelles → 8 corrections.

## Tour 1 — corrections du périmètre actionnable

1. **Régénération `scripts/gen_readme_tables.py`** : `test_readme_dual_lang`
échouait depuis le début de la branche. Tables README régénérées,
test enfin vert (3842 → 3843).

2. **Correction massive CLAUDE.md (47 substitutions)** : 39 chemins
`picarones/core/X.py` → `picarones/measurements/X.py` pour les
modules réellement déplacés historiquement (mufi, abbreviations,
modern_archives, calibration, ner, etc.). Plus 5 `*_runner.py`
orphelins remplacés par leur vrai chemin (ex: `core/pipeline_runner.py`
→ `core/pipeline.py`).

3. **6 corrections dans docs vivants** : `docs/profiles.md`,
`docs/cli-workflows.md`, `docs/roadmap/evolution-2026.md`,
`docs/user/writing-a-pipeline-module.md`, `SPECS.md`. Plus de
chemins cassés dans aucun document vivant.

4. **`docs/developer/index.md`** : arbo réécrite avec `core/` et
`measurements/` corrects + mention du sous-package `statistics/`.

5. **`docs/architecture.md`** : référence `statistics.py` →
`statistics/` ; nouvelle section « Convention de découpage des
modules > 400 lignes » qui formalise la convention sous-package
utilisée dans `picarones/measurements/statistics/`.

6. **`picarones/measurements/statistics/clustering.py`** : import
paresseux `from picarones.core.diff_utils import compute_word_diff`
déplacé au top-level. Le commentaire historique « Sprint A3 (B-1) »
référençait une violation de cercle qui n'existe plus.

7. **`picarones/report/levers_render.py`** : `except Exception: continue`
ligne 226 remplacé par `except Exception as exc: logger.warning(...)`
avec contexte (lv_type + payload + exception). Plus de fail
silencieux sur formatter cassé.

8. **`tests/architecture/test_doc_paths.py`** : `BROKEN_PATHS_BASELINE`
122 → 72. Les 72 restants sont **TOUS** dans CHANGELOG.md (67) et
docs/audits/*.md (5) — historiques intouchables. Commentaire
actualisé.

## Tour 2 — corrections sur les corrections du tour 1

9. **CLAUDE.md ligne 195** (Sprint 18) : `core/statistics.py` →
`picarones/measurements/statistics/`. Cette référence n'avait pas
le préfixe `picarones/` et a échappé à la regex de
`test_doc_paths` mais reste factuellement fausse.

10. **CLAUDE.md ligne 197** (Sprint 20) : `core/pricing.py` →
`picarones/measurements/pricing.py` ; `statistics.py` →
`picarones/measurements/statistics/pareto.py` (la fonction
`compute_pareto_front` vit maintenant dans le sous-module
`pareto`).

11. **CLAUDE.md ligne 54** (arbo informelle) : `statistics.py` retiré
de la liste, sous-package `statistics/` ajouté avec son contenu.

12. **`tests/report/test_sprint82_levers.py`** : nouveau test
`test_formatter_exception_logs_warning_and_skips_lever` qui
couvre le `logger.warning` ajouté dans levers_render.py. Évite
qu'une régression future supprime le warning sans CI failure.

## Vérifications finales

- `ruff check picarones/ tests/` : All checks passed!
- `pytest tests/` : **3843 passed, 2 skipped, 4 deselected, 0 failed**.
Le `test_readme_dual_lang` qui échouait depuis le début de la
branche est désormais vert (parité totale).
- `tests/architecture/` : 35 invariants verts.
- `BROKEN_PATHS_BASELINE` : 119 → 122 → **72** sur la branche.

## Ce qui reste comme dette ASSUMÉE (pas actionnable)

- 67 chemins `core/X.py` cassés dans CHANGELOG.md : **historique
versionné**, ne doit jamais être modifié rétroactivement.
- 5 chemins cassés dans `docs/audits/*.md` : audits historiques,
même logique.
- 13 modules de `measurements/` test-only : décision produit,
documentés dans `TEST_ONLY_BASELINE` avec justification par sprint.
- `_normal_sf` couplage `wilcoxon → friedman_nemenyi` : 8 lignes math
partagées, refactor en `_math.py` créerait plus de dette que de
bénéfice.
- 28 `# type: ignore` : tous justifiés (imports optionnels scipy,
spacy, payloads dynamiques).
- 23 `# noqa: F401` : tous des ré-exports rétrocompat documentés.

README.md

@@ -385,7 +385,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~3763 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~3849 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP.
 

SPECS.md

@@ -425,7 +425,7 @@ colonne) et `picarones/report/glossary/{fr,en}.yaml`.
 
 **Note de traçabilité** : les références primaires (Demšar 2006,
 Wilcoxon 1945, Efron 1979, etc.) sont citées dans les docstrings
-de chaque fonction de `picarones/measurements/statistics.py`.
+de chaque fonction de `picarones/measurements/statistics/`.
 Le glossaire contextuel relie chaque métrique à sa publication
 canonique (champ `reference`).
 

docs/architecture.md

@@ -41,7 +41,7 @@ Les implémentations distribuées par défaut dans le package `picarones`.
 
 | Catégorie | Modules |
 |---|---|
-| Coeur | `metrics.py`, `statistics.py`, `runner.py`, `builtin_hooks.py`, `builtin_metrics.py`, `normalization.py` |
+| Coeur | `metrics.py`, `statistics/` (sous-package), `runner.py`, `builtin_hooks.py`, `builtin_metrics.py`, `normalization.py` |
 | Erreurs | `confusion.py`, `taxonomy.py`, `taxonomy_comparison.py`, `taxonomy_cooccurrence.py`, `taxonomy_intra_doc.py` |
 | Lignes/structure | `line_metrics.py`, `structure.py`, `worst_lines.py`, `char_scores.py` |
 | Calibration/fiabilité | `calibration.py`, `reliability.py`, `hallucination.py` |
@@ -141,3 +141,39 @@ Organisés par cercle : `tests/core/`, `tests/measurements/`,
 
 Un test du cercle N **n'importe pas** les implémentations des
 cercles > N (sauf `tests/integration/`).
+
+## Convention de découpage des modules > 400 lignes
+
+Quand un module Python dépasse 400 lignes ET contient plusieurs
+responsabilités disjointes, le découper en **sous-package** plutôt
+qu'en plusieurs modules à plat. Modèle de référence :
+[`picarones/measurements/statistics/`](../picarones/measurements/statistics/)
+issu du sprint « découpage de statistics.py » (mai 2026).
+
+Convention :
+
+1. **Renommer** `X.py` en `X/__init__.py` via `git mv` (préserve
+   l'historique du fichier original).
+2. **Créer** dans `X/` un sous-module par famille fonctionnelle
+   (`bootstrap.py`, `wilcoxon.py`, `friedman_nemenyi.py`, etc.).
+   Chaque sous-module doit faire moins de ~400 lignes ; sinon
+   re-décomposer.
+3. **`X/__init__.py`** ne contient QUE des ré-exports rétrocompat —
+   tous les symboles publics de l'ancien `X.py` doivent rester
+   importables via `from picarones.X import …`. Les symboles privés
+   ré-exportés doivent être ceux **réellement** consommés par les
+   tests (vérifié par grep, pas par supposition).
+4. **`__all__`** explicite dans chaque sous-module et dans le
+   `__init__.py`.
+5. **Tests architecture** (`tests/architecture/test_*.py`) doivent
+   continuer à passer : si nécessaire, étendre `_measurements_modules()`
+   ou `_imports_target_*` pour reconnaître les sous-packages.
+6. **Préfixer les modules de rendu** par leur domaine
+   (`cdd_render.py` plutôt que `render_cdd.py`) pour cohérence avec
+   `picarones/report/*_render.py`.
+
+**Quand NE PAS découper** : si les responsabilités sont fortement
+couplées (ex: un orchestrateur qui appelle 12 sous-fonctions au
+même endroit), le maintien dans un seul fichier > 400 lignes est
+acceptable. Le budget par fichier (`tests/architecture/test_file_budgets.py`)
+documente ces dérogations conscientes.

docs/cli-workflows.md

@@ -133,7 +133,7 @@ picarones import iiif \
 Télécharge un manifeste IIIF v2/v3 (BnF Gallica, Bodleian, Vatican…) et
 crée un corpus local avec `.gt.txt` extraits de l'OCR ALTO si présent.
 Depuis le chantier 4, IIIF et Gallica utilisent les mêmes helpers HTTP
-factorisés ([`picarones/importers/_http.py`](../picarones/importers/_http.py))
+factorisés ([`picarones/extras/importers/_http.py`](../picarones/extras/importers/_http.py))
 avec garde-fou `file://`/`ftp://`/`javascript://`.
 
 ## Outils utilitaires

docs/developer/index.md

@@ -10,10 +10,18 @@ modules. En résumé :
 
 ```
 picarones/
-├── core/                # cœur analytique pur Python
+├── core/                # cœur analytique pur Python (Cercle 1)
+│   ├── pipeline.py      # PipelineRunner pour pipelines composées
+│   ├── corpus.py        # Document, Corpus, GTLevel
+│   ├── results.py       # DocumentResult, EngineReport, BenchmarkResult
+│   ├── modules.py       # BaseModule, ArtifactType
+│   ├── facts.py         # Fact, FactType, registre narratif
+│   └── …
+├── measurements/        # métriques officielles (Cercle 2)
 │   ├── runner.py        # orchestration ThreadPool/ProcessPool
 │   ├── metrics.py       # CER/WER/MER/WIL via jiwer
-│   ├── statistics.py    # Wilcoxon, Friedman, Nemenyi, Pareto
+│   ├── statistics/      # Wilcoxon, Friedman, Nemenyi, Pareto
+│   │   (sous-package depuis le sprint « découpage statistics.py »)
 │   ├── narrative/       # moteur de synthèse factuelle
 │   ├── pricing.py       # modèle de coût pour la vue Pareto
 │   └── …

docs/profiles.md

@@ -150,7 +150,7 @@ def my_hook(*, ground_truth, hypothesis, image_path, corpus_lang, ocr_result):
 
 - [`picarones/core/metric_hooks.py`](../picarones/core/metric_hooks.py)
   — registre, profils, `run_document_hooks()`, `run_corpus_aggregators()`.
-- [`picarones/core/builtin_hooks.py`](../picarones/core/builtin_hooks.py)
+- [`picarones/measurements/builtin_hooks.py`](../picarones/measurements/builtin_hooks.py)
   — les 12 hooks doc + 12 agrégateurs natifs Picarones.
 - [`tests/test_metric_hooks.py`](../tests/test_metric_hooks.py)
   — tests unitaires + rétrocompat profil `standard`.

docs/roadmap/evolution-2026.md

@@ -442,7 +442,7 @@ nouvelle dans le rapport.
 
 **A.II.1.a — Précision sur entités nommées (NER).**
 
-Nouveau module `picarones/core/ner.py`. Backends : spaCy multilingue,
+Nouveau module `picarones/measurements/ner.py`. Backends : spaCy multilingue,
 Stanza, modèle HIPE pour les corpus historiques. Choix paramétré par
 profil (`fr_core_news_lg`, `xx_ent_wiki_sm`, `hipe2022`).
 
@@ -464,7 +464,7 @@ glossaire (entrée `ner_score`).
 
 **A.II.1.b — Score de calibration des moteurs.**
 
-Nouveau module `picarones/core/calibration.py`. Tous les moteurs cibles
+Nouveau module `picarones/measurements/calibration.py`. Tous les moteurs cibles
 fournissent une confidence par token ou par ligne (Tesseract `tsv`
 output, Pero OCR via `PageLayout`, Mistral OCR via `confidence`, Google
 Vision via `Word.confidence`). Ajout d'un champ

docs/user/writing-a-pipeline-module.md

@@ -350,7 +350,7 @@ brancher dans la pipeline et de mesurer.
 ### 6.b « Et si je veux juste tester une pipeline OCR seule, sans étapes en aval ? »
 
 C'est exactement ce que fait le runner OCR historique
-(`run_benchmark` dans `picarones/core/runner.py`) — il est
+(`run_benchmark` dans `picarones/measurements/runner.py`) — il est
 toujours là, n'a pas changé, et reste la voie recommandée pour
 les benchmarks d'OCR mono-étage.
 

picarones/measurements/statistics/clustering.py

@@ -10,6 +10,8 @@ import re
 from collections import defaultdict
 from dataclasses import dataclass
 
+from picarones.core.diff_utils import compute_word_diff
+
 # Patterns d'erreurs fréquentes (OCR + HTR documents patrimoniaux)
 _ERROR_PATTERNS = [
     # (pattern_re, label)
@@ -27,9 +29,12 @@ _ERROR_PATTERNS = [
 
 
 def _extract_error_pairs(gt: str, hyp: str) -> list[tuple[str, str]]:
-    """Extrait les paires (gt_char_seq, hyp_char_seq) d'erreurs de substitution."""
-    # Sprint A3 (B-1) : import depuis Cercle 1, plus de violation Cercle 2→3.
-    from picarones.core.diff_utils import compute_word_diff
+    """Extrait les paires (gt_char_seq, hyp_char_seq) d'erreurs de substitution.
+
+    L'import de ``compute_word_diff`` est au top-level du module
+    (cercle 1 → cercle 2, sens autorisé). Il était paresseux historiquement
+    pour contourner une violation de cercle (Sprint A3) qui n'existe plus.
+    """
     ops = compute_word_diff(gt, hyp)
     pairs = []
     for op in ops:

picarones/report/levers_render.py

@@ -25,9 +25,12 @@ recommandation : la phrase est purement descriptive.
 
 from __future__ import annotations
 
+import logging
 from html import escape as _e
 from typing import Iterable, Optional
 
+logger = logging.getLogger(__name__)
+
 
 def _lever_label(lever_type: str, labels: dict[str, str]) -> str:
     return labels.get(f"levers_label_{lever_type}", lever_type)
@@ -223,7 +226,12 @@ def build_levers_section_html(
             continue
         try:
             sentence = formatter(payload, labels)
-        except Exception:
+        except Exception as exc:  # noqa: BLE001 — un formatter cassé ne doit pas casser la section
+            logger.warning(
+                "[levers_render] formatter %r a échoué sur payload=%r : %s — "
+                "ce levier sera omis du rapport",
+                lv_type, payload, exc,
+            )
             continue
         if not sentence:
             continue

tests/architecture/test_doc_paths.py

@@ -28,21 +28,25 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
-#: Snapshot v1.0.0. Doit baisser, jamais monter.
+#: Snapshot. Doit baisser, jamais monter.
 #:
 #: Historique :
 #: - 119 (initial v1.0.0, dette pré-existante CLAUDE.md/CHANGELOG.md
 #:   qui décrivent des modules sous ``picarones/core/...`` alors qu'ils
 #:   vivent dans ``picarones/measurements/...``).
 #: - 122 (sprint « découpage de statistics.py », 2026-05-02) : 3 audits
-#:   historiques (``docs/audits/institutional-readiness-2026-05.md`` et
-#:   ``docs/audits/remediation-plan-2026-05.md``) référencent
-#:   ``picarones/measurements/statistics.py`` qui est maintenant un
-#:   sous-package. On préfère relever la baseline plutôt que modifier
-#:   ces documents : un audit historique décrit un état du code à un
-#:   moment T et ne doit pas être ré-écrit pour refléter les états
-#:   futurs.
-BROKEN_PATHS_BASELINE = 122
+#:   historiques référencent ``picarones/measurements/statistics.py``
+#:   qui est maintenant un sous-package. Baseline relevée.
+#: - 72 (sprint « zéro dette actionnable », 2026-05-02) : 50 chemins
+#:   massivement corrigés — 44 dans CLAUDE.md (``core/X.py`` →
+#:   ``measurements/X.py`` pour les modules réellement déplacés
+#:   historiquement) + 6 dans docs vivants (profiles, cli-workflows,
+#:   evolution-2026, user/writing-a-pipeline-module, SPECS).
+#:
+#: Les 72 restants sont **TOUS** dans :
+#: - ``CHANGELOG.md`` (67) : journal historique versionné, intouchable.
+#: - ``docs/audits/*.md`` (5) : audits historiques, intouchables.
+BROKEN_PATHS_BASELINE = 72
 
 #: Patrons de fichiers de documentation à scanner.
 DOC_GLOBS: tuple[str, ...] = (

tests/report/test_sprint82_levers.py

@@ -423,6 +423,50 @@ class TestRender:
         html = build_levers_section_html([bad], _load_labels("fr"))
         assert html == ""
 
+    def test_formatter_exception_logs_warning_and_skips_lever(
+        self, caplog, monkeypatch,
+    ) -> None:
+        """Si un formatter lève une exception, le levier est omis et un
+        ``logger.warning`` est émis avec le contexte (type + payload + exc).
+
+        Garantit que :
+        1. La section continue à se rendre malgré le formatter cassé.
+        2. Un diagnostic est tracé en logs (pas un fail silencieux).
+        """
+        import logging
+
+        from picarones.report import levers_render
+
+        # Patche un des formatters pour qu'il lève une exception
+        original = levers_render._FORMATTERS.copy()
+
+        def broken_formatter(payload: dict, labels: dict) -> str:
+            raise ValueError("crash test")
+
+        monkeypatch.setattr(
+            levers_render, "_FORMATTERS",
+            {**original, "complementarity_observation": broken_formatter},
+        )
+
+        d = {
+            "type": "complementarity_observation",
+            "importance": 40,
+            "payload": {"foo": "bar"},
+        }
+        with caplog.at_level(logging.WARNING, logger="picarones.report.levers_render"):
+            html = build_levers_section_html([d], _load_labels("fr"))
+
+        # 1. Le levier cassé est omis (HTML ne le contient pas).
+        assert "complementarity_observation" not in html
+
+        # 2. Un warning a été émis avec le contexte attendu.
+        warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+        assert any(
+            "complementarity_observation" in r.getMessage()
+            and "crash test" in r.getMessage()
+            for r in warnings
+        ), f"Expected warning with formatter context, got: {[r.getMessage() for r in warnings]}"
+
     def test_accepts_dict_input(self) -> None:
         d = {
             "type": "complementarity_observation",