docs(handover): SESSION_HANDOVER.md + CLAUDE.md statut migration

Préparation pour la transition entre sessions Claude Code.

Ajouts
------
- ``docs/migration/SESSION_HANDOVER.md`` (240 LOC) : guide
complet pour qu'une nouvelle session reprenne sans erreur :
- Sources de vérité (par ordre de priorité).
- Vérifications avant code (branche, working tree, tests, lint).
- 6 pièges connus (architecture des couches, pattern shim,
test_module_coverage, test_file_budgets, test_doc_paths,
README généré).
- Plan d'exécution détaillé de la prochaine sub-phase (7.B.2).
- Pièges anticipés pour 7.B.2 (sémantique inputs, calcul
junction_metrics, output_types partial, spec conversion).
- Commande de démarrage de la nouvelle session.

CLAUDE.md mis à jour
--------------------
- Section « Phase active » remplace l'ancien pointeur audit
institutionnel par le retrait complet du legacy stratégie 4.B.
- Sous-section « Pour reprendre dans une nouvelle session »
pointe vers SESSION_HANDOVER.md.
- Sous-section « Règles d'architecture critiques » liste les
contraintes apprises à la dure (whitelists des couches,
patterns shim, etc.).
- Sous-section « Apprentissages des phases précédentes »
capitalise les recettes répétitives (pattern shim, docstring,
budgets, etc.).
- Tableau « Statut migration au moment du handover » donne
l'état exact phase par phase (0-11) avec ✅/⏳/📋.
- Section « Contexte développement » : branche active mise à
jour ``claude/code-quality-audit-ACnhK`` →
``claude/repo-analysis-cukvm``.

Acceptance
----------
5033 tests passent, lint vert, architecture vérifiée.

Comment l'utilisateur démarre la prochaine session
--------------------------------------------------
Simplement :

Continue la sub-phase 7.B.2.

Claude Code lira automatiquement CLAUDE.md à l'init, qui
pointera vers SESSION_HANDOVER.md, et la procédure de
vérification de l'état initial évitera toute erreur.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

CLAUDE.md

@@ -192,12 +192,82 @@ chercher.
 
 Pour le travail courant, ce qui compte :
 
-- **Phase active** : audit institutionnel post-S57 vers la
-  release 1.3.0 (cf. section [Unreleased] du CHANGELOG).
-- **Documents de référence** : docs/migration/rewrite-status-s46.md
-  (état du rewrite), docs/audits/ (audits historiques figés),
+- **Phase active** : retrait complet du legacy vers le rewrite,
+  stratégie 4.B (full migration, sans préservation API).  Le
+  projet est en stand-by jusqu'à la fin de la migration
+  complète — tests rouges acceptables temporairement, breaking
+  changes acceptés.
+- **Plan maître** : [`docs/migration/legacy-retirement-plan.md`](docs/migration/legacy-retirement-plan.md)
+  — cartographie complète des Phases 0-11 avec statut.
+- **Sub-plan convergence pipeline** : [`docs/migration/pipeline-convergence-plan.md`](docs/migration/pipeline-convergence-plan.md)
+  — détail de Sub-phases 7.A-7.D (BaseModule → StepExecutor).
+- **Documents de référence figés** :
+  docs/migration/rewrite-status-s46.md (état du rewrite),
+  docs/audits/ (audits historiques figés),
   docs/roadmap/evolution-2026.md (plan stratégique).
 
+### Pour reprendre dans une nouvelle session
+
+**Procédure complète** : lire d'abord
+[`docs/migration/SESSION_HANDOVER.md`](docs/migration/SESSION_HANDOVER.md)
+qui contient :
+
+- Sources de vérité par ordre de priorité.
+- Vérifications à faire avant de toucher au code (branche,
+  working tree, tests, lint).
+- Pièges connus (architecture des couches, patterns shim,
+  test_module_coverage / test_file_budgets / test_doc_paths /
+  README généré).
+- Plan d'exécution détaillé de la prochaine sub-phase.
+
+Résumé express :
+
+1. `git branch --show-current` → `claude/repo-analysis-cukvm`.
+2. `git status` → working tree clean.
+3. `pytest tests/ -q --no-header --tb=line` → 5070 passed.
+4. `git log -1 --format=%B` → décrit la prochaine sub-phase.
+
+**Règles d'architecture critiques** (apprises à la dure) :
+
+- ``evaluation/`` whitelist externe : ``PIL, annotated_types,
+  jiwer, numpy, pydantic, rapidfuzz, scipy, spacy,
+  typing_extensions, yaml`` — **pas** ``pytesseract``,
+  ``mistralai``, ``azure``, ``google``, ``pero_ocr``.  Tout code
+  qui importe ces libs externes va dans ``adapters/`` (qui
+  autorise les libs externes par design).
+- ``evaluation/`` ne peut pas importer depuis ``pipeline/`` :
+  c'est le sens inverse de la dépendance.  Si un module bridge
+  les deux contrats, il vit dans ``pipeline/``.
+- ``reports_v2/`` ne peut pas importer depuis ``measurements/``
+  (legacy) ou ``core/`` (legacy).  Les renderers consomment les
+  modules canoniques de ``evaluation/metrics/``.
+- ``test_module_coverage::TEST_ONLY_BASELINE`` : ajouter à
+  cette frozenset dès qu'un shim ``measurements/X.py`` n'a
+  plus de consommateur production (cas typique : un renderer
+  est migré vers ``reports_v2/`` et importe directement le
+  canonique au lieu du shim).
+
+### Apprentissages des phases précédentes
+
+- **Pattern shim** : pour chaque migration, le chemin legacy
+  devient un shim minimal (< 25 lignes) avec
+  ``from canonical_path import *  # noqa: F401, F403`` +
+  ``DeprecationWarning`` à l'import.  Les noms privés
+  (``_FORMATTERS``, ``_PYTESSERACT_AVAILABLE``, etc.) doivent
+  être importés explicitement en plus de ``import *`` car
+  ``*`` n'exporte pas les ``_`` privés.
+- **Pattern docstring** : ajouter en tête du module canonique
+  un bloc ``Phase X — module relocalisé depuis Y vers Z``
+  avec mention de la suppression en 2.0.
+- **Pattern test budgets** : si un fichier dépasse 400 LOC,
+  ajouter une entrée dans
+  ``tests/architecture/test_file_budgets.py::FILE_BUDGETS``
+  avec budget = LOC actuel + ~15 %.
+- **Pattern docs paths** : si un sub-plan référence un futur
+  chemin Python qui n'existe pas encore (forward reference),
+  bumper ``BROKEN_PATHS_BASELINE`` du même montant et noter que la
+  référence sera résolue quand le fichier sera créé.
+
 ## Moteur narratif
 
 Le modèle de données (`Fact`, `FactType`, `FactImportance`,
@@ -242,8 +312,38 @@ détecte, arbitre, rend.
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces, Python 3.11+
-- **Tests** : `pytest tests/ -q` → ~5070 passed, 2 skipped, 0 failed.
+- **Tests** : `pytest tests/ -q` → 5070 passed, 12 skipped, 24
+  deselected, 0 failed (au moment de la pause de session).
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md).
+- **Plan retrait du legacy (maître)** : [`docs/migration/legacy-retirement-plan.md`](docs/migration/legacy-retirement-plan.md).
+- **Sub-plan convergence pipeline** : [`docs/migration/pipeline-convergence-plan.md`](docs/migration/pipeline-convergence-plan.md).
 - **Manifeste architecture** : [`docs/explanation/architecture.md`](docs/explanation/architecture.md).
 - **API publique stable** : [`docs/reference/api-stable.md`](docs/reference/api-stable.md).
-- **Branche active** : `claude/code-quality-audit-ACnhK`.
+- **Branche active** : `claude/repo-analysis-cukvm`.
+
+### Statut migration au moment du handover
+
+| Phase   | Statut    | Détails                                                    |
+|---------|-----------|------------------------------------------------------------|
+| 0-3     | ✅ terminée | Foundation, statistics, narrative engine                   |
+| 4       | ✅ terminée | 35 mesures legacy → ``evaluation/metrics/``                |
+| 4-bis   | ✅ terminée | ``ArtifactType`` migration + 22 callers                    |
+| 4-ter   | ✅ terminée | core/{metric_registry,metric_hooks,metrics,results} → eval |
+| 4-quater | ✅ terminée | core/corpus → evaluation/corpus                           |
+| 5.A     | ✅ terminée | helpers + glossary + i18n → reports_v2/                    |
+| 5.B     | ✅ terminée | (intégré dans 5.A)                                         |
+| 5.C     | ✅ terminée | 29 renderers + 5 modules pré-requis → reports_v2/          |
+| 5.D     | ✅ terminée | 5 vues thématiques → reports_v2/html/views/                |
+| 5.E     | ✅ terminée | generator + comparison + snapshot + data + templates       |
+| 7.A     | ✅ terminée | engines/ + modules/ → adapters/legacy_*/                   |
+| 7.B.1   | ✅ terminée | _BaseModuleAdapter + _PayloadRegistry (commit b70f12a)     |
+| 7.B.2   | ⏳ EN COURS | PipelineRunner.run délègue à PipelineExecutor              |
+| 7.B.3   | 📋 à venir | pipeline_benchmark/comparison via canonique                |
+| 7.C     | 📋 à venir | Refactor 7 tests axe B (mocks BaseModule → StepExecutor)   |
+| 7.D     | 📋 à venir | Suppression BaseModule + PipelineRunner + shims core/      |
+| 6, 8-11 | 📋 à venir | pipelines/, importers, web, cli, retirement final          |
+
+**Prochaine sub-phase à exécuter** : 7.B.2 (refactor du corps
+de ``PipelineRunner.run`` dans ``evaluation/pipeline.py`` pour
+qu'il délègue à ``PipelineExecutor`` via le wrapper
+``_BaseModuleAdapter`` créé en 7.B.1).

docs/migration/SESSION_HANDOVER.md

@@ -0,0 +1,243 @@
+# Handover entre sessions Claude Code
+
+> Ce document est lu en premier par chaque nouvelle session pour
+> reprendre le travail sans se tromper.  Il pointe vers les
+> sources de vérité, signale les pièges connus, et donne la
+> prochaine action concrète.
+
+---
+
+## 1. Sources de vérité (par ordre de priorité)
+
+1. **[`legacy-retirement-plan.md`](legacy-retirement-plan.md)** —
+   plan maître des Phases 0-11 du retrait du legacy.  Chaque
+   phase a un statut explicite (✅ terminée / ⏳ en cours / 📋 à
+   venir).
+2. **[`pipeline-convergence-plan.md`](pipeline-convergence-plan.md)** —
+   sous-plan détaillé de la convergence ``BaseModule`` /
+   ``PipelineRunner`` → ``StepExecutor`` / ``PipelineExecutor``
+   (Sub-phases 7.A-7.D).
+3. **[`../../CLAUDE.md`](../../CLAUDE.md)** — règles d'architecture
+   à respecter, statut de la migration, et liens vers le reste.
+4. **`git log --oneline -10`** — les 10 derniers commits
+   donnent l'état réel.  Le dernier commit message décrit
+   souvent la prochaine sub-phase à exécuter.
+
+---
+
+## 2. Vérifications avant de toucher au code
+
+```bash
+# 1. Bonne branche ?
+git branch --show-current
+# → doit retourner: claude/repo-analysis-cukvm
+
+# 2. Working tree propre ?
+git status
+# → doit retourner: nothing to commit, working tree clean
+
+# 3. Tests verts à l'état initial ?
+python -m pytest tests/ -q --no-header --tb=line
+# → doit retourner: 5070 passed (au moment de la pause de session)
+
+# 4. Lint vert ?
+ruff check picarones/ tests/
+# → doit retourner: All checks passed!
+```
+
+Si l'une de ces vérifications échoue : **NE PAS** continuer le
+sprint.  Investiguer d'abord pourquoi l'état initial diverge de
+celui annoncé dans CLAUDE.md.
+
+---
+
+## 3. Pièges connus (apprentissages des phases précédentes)
+
+### 3.A Architecture des couches
+
+Voir CLAUDE.md section « Règles d'architecture critiques ».
+Résumé :
+
+- ``evaluation/`` ne peut pas importer ``pipeline.types`` —
+  c'est l'autre sens.
+- ``evaluation/`` whitelist limitée : pas de pytesseract /
+  mistralai / azure / google / pero_ocr.  Ces libs externes
+  vont dans ``adapters/``.
+- ``reports_v2/`` ne peut importer que les canoniques
+  (``evaluation/metrics/``), pas les shims legacy
+  (``measurements/X.py``).
+
+### 3.B Pattern shim
+
+Pour un shim minimal :
+
+```python
+"""``picarones.X.Y`` — shim re-export (déprécié, suppression 2.0).
+
+Canonique : :mod:`picarones.canonical.path`.  Phase X.Y du
+retrait du legacy.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from picarones.canonical.path import *  # noqa: F401, F403
+# Si des callers consomment des noms privés (_FOO, etc.),
+# les ré-exporter explicitement :
+from picarones.canonical.path import _FOO  # noqa: F401
+
+warnings.warn(
+    "picarones.X.Y is deprecated and will be removed in 2.0.  "
+    "Import from picarones.canonical.path instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+```
+
+### 3.C ``test_module_coverage::TEST_ONLY_BASELINE``
+
+Quand un shim ``measurements/X.py`` n'a plus de consommateur
+production (parce qu'un renderer a migré vers le canonique
+direct), ajouter ``"X"`` à ``TEST_ONLY_BASELINE`` dans
+``tests/architecture/test_module_coverage.py``.  Sinon le test
+``test_no_new_test_only_modules`` échoue.
+
+### 3.D ``test_file_budgets``
+
+Tout fichier ≥ 400 LOC doit avoir une entrée dans
+``FILE_BUDGETS`` avec budget = LOC actuel + ~15 %.  Quand on
+relocalise un fichier, retirer l'entrée du chemin legacy et
+en créer une au chemin canonique avec le même budget.
+
+### 3.E ``test_doc_paths::BROKEN_PATHS_BASELINE``
+
+Si un sub-plan ou doc référence un futur chemin Python
+(``picarones/X/Y.py``) qui n'existe pas encore, le test
+``test_broken_doc_paths_below_baseline`` détecte la
+référence cassée.  Soit :
+
+- Bumper ``BROKEN_PATHS_BASELINE`` du même montant.
+- Ou reformuler la référence en code/backticks pour échapper
+  au pattern (``picarones/X/Y.py``).
+
+Quand le fichier sera créé en réalité, abaisser
+``BROKEN_PATHS_BASELINE``.
+
+### 3.F README généré
+
+Le compteur de tests dans `README.md` et `CLAUDE.md` est
+synchronisé par `scripts/gen_readme_tables.py`.  À chaque
+fois que le nombre de tests change (ajout/retrait), lancer :
+
+```bash
+python scripts/gen_readme_tables.py
+```
+
+Sinon le test ``test_readme_tables_consistent_with_code``
+échoue.
+
+---
+
+## 4. Prochaine sub-phase à exécuter
+
+**Sub-phase 7.B.2** — refactoriser le corps de
+``PipelineRunner.run`` dans
+``picarones/evaluation/pipeline.py`` (lignes 384-590) pour
+qu'il délègue au canonique ``PipelineExecutor`` via le
+wrapper ``_BaseModuleAdapter`` créé en 7.B.1.
+
+### Plan d'exécution
+
+1. **Lire** ``picarones/evaluation/pipeline.py:PipelineRunner.run``
+   en entier pour comprendre la logique actuelle (résolution
+   d'inputs versionnés, exécution chronométrée, capture
+   d'erreur, évaluation auto vs GT, conversion outputs).
+
+2. **Lire** ``picarones/pipeline/_legacy_module_adapter.py``
+   en entier pour comprendre les outils disponibles
+   (``_BaseModuleAdapter``, ``_PayloadRegistry``,
+   ``wrap_initial_inputs``).
+
+3. **Écrire** un nouveau corps de ``PipelineRunner.run`` qui :
+   - Crée un ``_PayloadRegistry`` par appel.
+   - Wrappe les ``initial_inputs`` legacy via
+     ``wrap_initial_inputs(...)``.
+   - Convertit la ``PipelineSpec`` legacy en ``PipelineSpec``
+     canonique (``picarones.domain.pipeline_spec.PipelineSpec``).
+     Chaque ``PipelineStep.module: BaseModule`` devient un
+     ``adapter_name: str``, et l'adapter est
+     ``_BaseModuleAdapter(module, registry)``.
+   - Construit un ``adapter_resolver`` qui retourne le
+     wrapper de chaque module.
+   - Construit un ``RunContext``.
+   - Convertit le ``Document`` legacy en ``DocumentRef``.
+   - Invoque ``PipelineExecutor.run(canonical_spec,
+     document_ref, canonical_inputs, context)``.
+   - Reconvertit le ``PipelineResult`` canonique en
+     ``PipelineResult`` legacy.
+   - Calcule ``junction_metrics`` en post-étape (parcourt
+     les ``StepResult.produced_artifacts``, lit le payload
+     du registre, appelle ``compute_at_junction`` contre la
+     GT du document si ``GTLevel`` correspond).
+
+4. **Tester** : tous les tests existants doivent toujours
+   passer (les 7 fichiers axe B + ``test_sprint63_pipeline_runner``,
+   etc.).  C'est l'invariant de la sub-phase 7.B.2.
+
+5. **Lint** : ``ruff check picarones/ tests/``.
+
+6. **Commit + push** avec message décrivant ce qui a été
+   fait + pointer vers la sub-phase 7.B.3 comme prochaine
+   étape.
+
+### Pièges anticipés pour 7.B.2
+
+- **Sémantique différente des inputs entre legacy et canonique** :
+  le legacy passe ``Document.image_path`` comme un string
+  pur dans ``initial_inputs[ArtifactType.IMAGE]`` ; le canonique
+  attend un ``Artifact(uri=...)``.  ``wrap_initial_inputs``
+  fait la conversion mais il faut s'assurer que les modules
+  consomment bien le ``uri`` côté `_BaseModuleAdapter`.
+
+- **``junction_metrics`` calcul** : le legacy
+  ``PipelineRunner.run`` calcule ``junction_metrics`` à
+  chaque step (cf. ligne 519-540 actuellement).  Le canonique
+  ``PipelineExecutor`` ne le fait pas.  Il faut donc faire
+  ce calcul **après** l'exécution canonique, en parcourant
+  les artefacts produits et en lisant les payloads via le
+  registre.
+
+- **``output_types`` partial** : si un module produit un
+  output type non déclaré, le legacy le tolère (on remplit
+  ``StepResult.output_types`` avec ce qui est effectivement
+  produit, pas ce qui est déclaré).  Le canonique
+  ``PipelineExecutor`` rejette en ``error="missing_output: ..."``.
+  Vérifier la sémantique attendue par les tests.
+
+- **Spec conversion** : ``PipelineStep`` legacy a
+  ``inputs_from: dict[ArtifactType, str]`` (mapping
+  type→step_name).  ``PipelineStep`` canonique a
+  ``inputs_from: tuple[InputBinding, ...]``.  Conversion
+  attentive nécessaire.
+
+---
+
+## 5. Commande de démarrage de la nouvelle session
+
+Le user envoie simplement :
+
+```
+Reprends la migration. Lis docs/migration/SESSION_HANDOVER.md
+en entier d'abord, puis commence par les vérifications de la
+section 2.
+```
+
+Ou pour aller direct à l'action :
+
+```
+Continue la sub-phase 7.B.2.
+```
+
+(Claude Code va automatiquement lire CLAUDE.md à l'init, qui
+pointera vers ce SESSION_HANDOVER.md et les plans détaillés.)