docs: Phase 2 — vérité documentaire (compteurs, fantômes, legacy refs)

Sept corrections de drift documentation → code identifiées par
l'audit code-quality.

**2.1 — Sync compteurs en CI bloquant**

- Nouveau job CI ``sync-counters`` qui exécute
``scripts/gen_readme_tables.py --check`` : échoue si README.md /
CLAUDE.md divergent du code réel (script déjà présent depuis A13,
mais jamais câblé en CI ni Makefile — orphelin).
- Cibles Makefile ``sync-counters`` (régénère), ``sync-counters-check``
(vérifie), ``docs`` (``mkdocs build --strict``) et ``docs-serve``.
- CLAUDE.md : compteur 4 750 (réel) au lieu de 4 700, détail
cohérent 16 skipped + 8 deselected + 2 xfailed (auto-contradiction
L.119 vs L.305 résolue, la 2e mention renvoie maintenant à la 1re).
- CLAUDE.md : ``20 détecteurs`` au lieu de 18 ; ajout des 2 manquants
(``importer_fallback_triggered`` dans history.py et
``pricing_staleness_warning`` dans pareto.py). ``28 renderers HTML``
au lieu de 22.
- CLAUDE.md : note explicite sur le piège ``pytest tests/`` (uv tool)
→ ``python -m pytest tests/``.

**2.2 — Modules fantômes retirés de api-stable.md**

Le document affirme garantir l'existence des modules listés.
Quatre rubriques pointaient vers du code supprimé en v2.0 :
``picarones.pipeline.legacy_runner``,
``picarones.pipeline.legacy_pipeline_benchmark``,
``picarones.pipeline.legacy_pipeline_comparison``,
``picarones.evaluation.metrics.pipeline_spec_loader``.

Test ajouté : ``tests/docs/test_api_stable_modules_exist.py``
parse les rubriques ``### `picarones.X.Y``` et ``importlib.import_module``
chacune. Empêche la résurrection du drift.

**2.3 — README.md**

- Section ``Project layout`` : retrait du paragraphe « Legacy paths
still present as shims » (faux depuis v2.0). Remplacement par une
description honnête du retrait complet du legacy.
- Section ``Development`` : ``python -m mypy picarones/core/`` →
``python -m mypy picarones/domain/`` (strict) +
``python -m mypy picarones/`` (lax). ``pytest tests/`` →
``python -m pytest tests/``.

**2.5 — architecture.md**

Ligne 165 : ``22 renderers + 5 vues`` → ``28 renderers + 5 vues``.
Ligne 166 : ``18 détecteurs`` → ``20 détecteurs``.

**2.6 — pyproject.toml extra ``all``**

``all = ["picarones[web,hf,llm,dev]"]`` était trompeur (le commentaire
disait « tous les extras sauf OCR cloud » alors qu'il oubliait aussi
docs/stats/ner/pero/kraken/calamari). Élargi à l'intégralité :
``[dev,docs,web,stats,ner,hf,pero,kraken,calamari,llm,ocr-cloud]``.

Compteurs : 4 732 passed (post-Phase 1 : +1 test API-stable),
0 failed, ruff propre, sync-counters --check vert.

.github/workflows/ci.yml

@@ -274,6 +274,32 @@ jobs:
       - name: Run ruff
         run: ruff check picarones/ tests/
 
+  # ──────────────────────────────────────────────────────────────────
+  # Job 4-bis : Sync compteurs README/CLAUDE.md — Phase 2.1 audit
+  # code-quality (2026-05).  Le script gen_readme_tables.py reflète
+  # le code réel dans la prose des docs (tableaux Engines/CLI/API +
+  # compteur de tests).  En CI : exit 1 si la doc dérive.
+  # ──────────────────────────────────────────────────────────────────
+  sync-counters:
+    name: Doc counters sync
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install Picarones (web extras pour ouvrir l'app FastAPI)
+        run: pip install -e ".[dev,web]"
+
+      - name: Vérifier que README.md / CLAUDE.md reflètent le code
+        run: python scripts/gen_readme_tables.py --check
+
   # ──────────────────────────────────────────────────────────────────
   # Job 5 : Type-checking — Sprint A1 (item M-4)
   #

CLAUDE.md

@@ -95,9 +95,9 @@ picarones/
 │                               benchmark_runner (entry point CLI/web), partial_store
 │
 ├── reports/                    Couche 7 — rendu HTML / JSON / CSV
-│   ├── html/                   ReportGenerator + 22 renderers + 5 vues + templates Jinja2
+│   ├── html/                   ReportGenerator + 28 renderers + 5 vues + templates Jinja2
 │   ├── json/, csv/             exports tabulaires
-│   ├── narrative/              moteur narratif (18 détecteurs)
+│   ├── narrative/              moteur narratif (20 détecteurs)
 │   ├── glossary/, i18n/        glossaire + i18n FR/EN
 │   └── _helpers/               colors, render_helpers, assets
 │
@@ -116,13 +116,19 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4750 passed, 12 skipped, 8 deselected, 0 failed**
-(post-S59).  Les deselected sont les markers `live` (5 tests d'intégration
-contre vraie API/binaire) + `network` (3 tests qui hit le réseau réel),
-opt-in en local via `pytest -m live` ou `pytest -m network`.  Le
-compteur en prose est synchronisé automatiquement par
-`scripts/gen_readme_tables.py` — toute modification manuelle sera
-ré-écrasée au prochain `make lint`.
+`pytest tests/` → **4750 passed, 16 skipped, 8 deselected, 2 xfailed, 0 failed**
+(post-audit code-quality, mai 2026).  Les deselected sont les markers
+`live` (5 tests d'intégration contre vraie API/binaire) + `network`
+(3 tests qui hit le réseau réel), opt-in en local via `pytest -m live`
+ou `pytest -m network`.  Le compteur ``passed`` est synchronisé
+automatiquement par `scripts/gen_readme_tables.py` (CI : job
+``sync-counters`` ; local : `make sync-counters-check`).  Le détail
+``skipped``/``xfailed`` peut dériver de ±2 entre éditions et n'est
+pas verrouillé en CI.
+
+NB : utiliser ``python -m pytest tests/`` plutôt que ``pytest tests/``
+directement — l'installation via ``uv tool install pytest`` masque
+les deps Picarones et produit ~160 collection errors trompeurs.
 
 ### Bugs documentés antérieurement — tous résolus
 
@@ -271,17 +277,18 @@ picarones/reports/narrative/
 ├── arbiter.py               Tri par importance, non-redondance, anti-contradiction
 ├── renderer.py              Rendu templates YAML par str.format_map (déterministe)
 ├── registry.py              Registre par défaut des détecteurs
-├── templates/{fr,en}.yaml   18 templates × 2 langues
-└── detectors/               18 détecteurs en 6 familles
+├── templates/{fr,en}.yaml   20 templates × 2 langues
+└── detectors/               20 détecteurs en 6 familles
     ├── ranking.py           5 (global_leader, statistical_tie, significant_gap,
     │                          speed_winner, median_mean_gap_warning)
-    ├── pareto.py            2 (pareto_alternative, cost_outlier)
+    ├── pareto.py            3 (pareto_alternative, cost_outlier,
+    │                          pricing_staleness_warning)
     ├── stratum.py           3 (stratum_winner, stratum_collapse,
     │                          stratification_recommended)
     ├── quality.py           4 (error_profile_outlier, llm_hallucination_flag,
     │                          robustness_fragile, confidence_warning)
-    ├── history.py           3 (engine_off_baseline, engine_unstable,
-    │                          regression_in_history)
+    ├── history.py           4 (engine_off_baseline, engine_unstable,
+    │                          regression_in_history, importer_fallback_triggered)
     └── ensemble.py          1 (ensemble_opportunity)
 ```
 
@@ -302,8 +309,8 @@ détecte, arbitre, rend.
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces, Python 3.11+
-- **Tests** : `pytest tests/ -q` → 4750 passed, 9 skipped, 24
-  deselected, 0 failed (post-v2.0).
+- **Tests** : voir « État des tests et bugs historiques » plus haut
+  (compteur synchronisé par ``scripts/gen_readme_tables.py``).
 - **Manifeste architecture** : [`docs/explanation/architecture.md`](docs/explanation/architecture.md).
 - **API publique stable** : [`docs/reference/api-stable.md`](docs/reference/api-stable.md).
 

Makefile

@@ -109,6 +109,34 @@ doc-check:  ## Audit de cohérence README/SPECS/CHANGELOG (Sprint A2)
 	  $(PYTHON) -m pytest tests/docs/ -q --tb=short --no-header; \
 	fi
 
+sync-counters:  ## Régénère README/CLAUDE.md avec les compteurs réels (script gen_readme_tables.py)
+	@if [ -x $(VENV_BIN)/python ]; then \
+	  $(VENV_BIN)/python scripts/gen_readme_tables.py; \
+	else \
+	  $(PYTHON) scripts/gen_readme_tables.py; \
+	fi
+
+sync-counters-check:  ## CI : échoue si README/CLAUDE.md divergent du code (compteurs tests + tables)
+	@if [ -x $(VENV_BIN)/python ]; then \
+	  $(VENV_BIN)/python scripts/gen_readme_tables.py --check; \
+	else \
+	  $(PYTHON) scripts/gen_readme_tables.py --check; \
+	fi
+
+docs:  ## Construit le site mkdocs en mode strict (échoue sur les warnings)
+	@if [ -x $(VENV_BIN)/python ]; then \
+	  $(VENV_BIN)/python -m mkdocs build --strict; \
+	else \
+	  $(PYTHON) -m mkdocs build --strict; \
+	fi
+
+docs-serve:  ## Lance mkdocs en mode dev (http://localhost:8000)
+	@if [ -x $(VENV_BIN)/python ]; then \
+	  $(VENV_BIN)/python -m mkdocs serve; \
+	else \
+	  $(PYTHON) -m mkdocs serve; \
+	fi
+
 typecheck:  ## Vérification de types avec mypy (si installé)
 	@$(VENV_BIN)/python -m mypy $(PACKAGE)/ --ignore-missing-imports --no-strict-optional 2>/dev/null \
 	  || echo "mypy non installé : pip install mypy"

README.md

@@ -332,13 +332,16 @@ picarones/
 └── interfaces/     Layer 8 — CLI Click, Web FastAPI
 ```
 
-Legacy paths (`core/, measurements/, engines/, llm/, pipelines/,
-report/, modules/`) still present as shims, in active retirement
-(see `docs/archives/migration/`).  Strict 8-layer architecture: imports flow
-outer → inner. Enforced by
-`tests/architecture/test_layer_dependencies.py`. See
+Strict 8-layer architecture: imports flow outer → inner. Enforced
+by `tests/architecture/test_layer_dependencies.py`. The v2.0
+release (May 2026) removed all legacy top-level packages (`core/`,
+`measurements/`, `engines/`, `llm/`, `pipelines/`, `report/`,
+`modules/`, `cli/`, `web/`, `extras/`) and the transitional
+sub-packages (`adapters/legacy_engines/`, `adapters/legacy_pipelines/`,
+`interfaces/{cli,web}/_legacy/`). See
 [`docs/explanation/architecture.md`](docs/explanation/architecture.md)
-for the full manifesto.
+for the full manifesto and migration history under
+`docs/archives/migration/`.
 
 ---
 
@@ -392,9 +395,10 @@ GitHub Actions: `.github/workflows/`
 ```bash
 pip install -e ".[dev,web]"
 pre-commit install
-pytest tests/ -q
+python -m pytest tests/ -q          # ``python -m`` requis si pytest est uv-installé
 ruff check picarones/ tests/
-python -m mypy picarones/core/
+python -m mypy picarones/domain/    # strict mode (Layer 1)
+python -m mypy picarones/           # lax mode (full tree)
 ```
 
 **Test suite**: ~4750 tests, ~3 min on a modern laptop. Coverage

docs/explanation/architecture.md

@@ -162,8 +162,8 @@ Verrouillé par `tests/security/test_s1_zip_slip_attack.py`.
 | `csv/render.py` | `CsvReportRenderer` — un CSV plat (`run_id, doc, pipeline, view, metric, value, status`) |
 | `json/render.py` | `JsonReportRenderer` — manifest + documents en JSON déterministe |
 | `html/render.py` | `HtmlReportRenderer` — rapport autonome (TextView, AltoView, SearchView) — minimaliste |
-| `html/generator.py` | `ReportGenerator` — rapport interactif riche (22 renderers + 5 vues) consommé par CLI/web |
-| `narrative/` | Moteur narratif (18 détecteurs) — synthèse factuelle déterministe |
+| `html/generator.py` | `ReportGenerator` — rapport interactif riche (28 renderers + 5 vues) consommé par CLI/web |
+| `narrative/` | Moteur narratif (20 détecteurs) — synthèse factuelle déterministe |
 | `glossary/`, `i18n/` | Glossaire + i18n FR/EN |
 
 Le rendu est strict : pas de JS dynamique côté serveur, pas d'I/O

docs/reference/api-stable.md

@@ -135,55 +135,6 @@ l'API mono-call historique de
 s'appuyant en interne sur ``BenchmarkService`` (rewrite).
 Prouvé numériquement équivalent en D.1.e.
 
-### `picarones.pipeline.legacy_runner`
-
-> Phase 7.B.2 (2026-05-07) — module relocalisé depuis
-> ``picarones.evaluation.pipeline`` vers ``picarones.pipeline.legacy_runner``.
-> La délégation au ``PipelineExecutor`` canonique impose à ce module
-> d'importer la couche ``pipeline/`` — interdit à ``evaluation/``.
-
-```python
-class PipelineStep:
-class PipelineSpec:
-class StepResult:
-class PipelineResult:
-class PipelineRunner:
-```
-
-### `picarones.pipeline.legacy_pipeline_benchmark`
-
-> Phase 7.B.2 — relocalisé depuis ``picarones.evaluation.pipeline_benchmark``
-> (mêmes raisons que ``legacy_runner``).
-
-```python
-class StepAggregate:
-class PipelineBenchmarkResult:
-
-def default_initial_inputs(doc) -> dict
-def run_pipeline_benchmark(spec, corpus, factory=...) -> PipelineBenchmarkResult
-```
-
-### `picarones.pipeline.legacy_pipeline_comparison`
-
-> Phase 7.B.2 — relocalisé depuis ``picarones.evaluation.pipeline_comparison``.
-
-```python
-class PipelineComparisonResult:
-
-def compare_pipelines(specs, corpus, factories=None) -> PipelineComparisonResult
-```
-
-### `picarones.evaluation.metrics.pipeline_spec_loader`
-
-```python
-class PipelineSpecLoadError(ValueError):
-
-def load_pipeline_spec_from_yaml(path) -> PipelineSpec
-def load_pipeline_spec_from_dict(data: dict) -> PipelineSpec
-def load_comparison_specs_from_yaml(path) -> tuple[list[PipelineSpec], dict]
-def load_comparison_specs_from_dict(data: dict) -> tuple[list[PipelineSpec], dict]
-```
-
 ### `picarones.evaluation.metric_registry`
 
 ```python

pyproject.toml

@@ -124,9 +124,13 @@ ocr-cloud = [
 # distincts (``picarones-historical``, ``picarones-importers``) est
 # documentée dans ``docs/developer/module-policy.md`` (Sprint 97) et
 # n'a plus besoin d'être réservée par un extra vide.
-# Installation complète (tous les extras sauf les OCR cloud)
+#
+# Installation **vraiment complète** : tous les extras déclarés
+# ci-dessus, OCR cloud et docs inclus.  Le nom ``all`` ne doit pas
+# tromper le contributeur — si un extra apparaît plus haut, il doit
+# apparaître ici.  Phase 2.6 de l'audit code-quality (2026-05).
 all = [
-    "picarones[web,hf,llm,dev]",
+    "picarones[dev,docs,web,stats,ner,hf,pero,kraken,calamari,llm,ocr-cloud]",
 ]
 
 [project.scripts]

tests/docs/test_api_stable_modules_exist.py

@@ -0,0 +1,68 @@
+"""Phase 2.2 du plan d'audit — chaque module ``picarones.X.Y`` cité
+dans ``docs/reference/api-stable.md`` comme rubrique de niveau 3
+(``### `picarones....```) doit être réellement importable.
+
+Le document revendique en son préambule :
+
+    > Garantie principale : **existence** — aucun nom listé ne
+    > disparaît entre ``1.x.0`` et ``2.0.0`` sans procédure de
+    > dépréciation.
+
+L'audit code-quality de mai 2026 a trouvé que 4 modules cités
+n'existaient plus :
+
+- ``picarones.pipeline.legacy_runner``
+- ``picarones.pipeline.legacy_pipeline_benchmark``
+- ``picarones.pipeline.legacy_pipeline_comparison``
+- ``picarones.evaluation.metrics.pipeline_spec_loader``
+
+Tous supprimés au passage v2.0 (retrait du legacy).  Ce test
+empêche le drift de se reproduire.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from pathlib import Path
+
+API_STABLE_MD = Path(__file__).resolve().parents[2] / "docs" / "reference" / "api-stable.md"
+
+# Capture les rubriques de niveau 3 ``### `picarones.X.Y```.
+# Le backtick fermant est obligatoire (évite de matcher du prose
+# qui mentionne ``picarones.X`` sans intention de "rubrique API").
+_RUBRIC_RE = re.compile(r"^###\s+`(picarones\.[\w\.]+)`", re.MULTILINE)
+
+
+def _extract_modules() -> list[str]:
+    if not API_STABLE_MD.exists():
+        return []
+    return _RUBRIC_RE.findall(API_STABLE_MD.read_text(encoding="utf-8"))
+
+
+def test_every_api_stable_rubric_is_importable() -> None:
+    """Chaque module cité comme ``### `picarones.X.Y``` doit s'importer
+    sans erreur — garantie d'existence pour les consommateurs externes
+    qui se fient à la documentation pour cibler une API stable.
+    """
+    modules = _extract_modules()
+    assert modules, (
+        f"{API_STABLE_MD} ne contient aucune rubrique ``### `picarones.X``` — "
+        f"le test ne peut pas vérifier le contrat d'existence."
+    )
+
+    missing: list[tuple[str, str]] = []
+    for name in modules:
+        try:
+            importlib.import_module(name)
+        except ImportError as exc:
+            missing.append((name, str(exc)))
+
+    assert not missing, (
+        "api-stable.md référence des modules qui n'existent plus :\n"
+        + "\n".join(f"  - {name} : {err}" for name, err in missing)
+        + "\n\nSoit recréer le module, soit retirer la rubrique de "
+        "``docs/reference/api-stable.md`` (et documenter la rupture dans "
+        "CHANGELOG.md).  La garantie d'existence du document interdit "
+        "le drift silencieux."
+    )