fix(cli): garde-fou migration --fail-if-cer-above (Click callback)

Suite à un audit de mon propre fix précédent : la sémantique fraction
introduite cassait silencieusement les callers externes qui utilisaient
l'ancienne sémantique pourcentage (15.0 = 15 %). Avec le seuil compris
comme fraction, 15.0 = 1500 % et la condition ne se déclenche jamais —
l'utilisateur croit que son CI est sain alors qu'il ne lève plus.

Solution : convertir la cassure silencieuse en cassure bruyante via
un Click callback de validation.

picarones/cli/_workflows.py
---------------------------
- Nouveau callback ``_validate_cer_threshold`` rejette à l'analyse
Click :
· valeur < 0 → BadParameter "doit être ≥ 0"
· valeur > 1.0 → BadParameter "doit être une fraction ∈ [0, 1]
(ex : 0.15 = 15 %), reçu N. Si vous utilisiez l'ancienne
sémantique pourcentage, divisez par 100 (ex : 15.0 → 0.15)."
- Validation à l'analyse, AVANT le chargement du corpus / Tesseract
/ OCR — un utilisateur qui se trompe découvre l'erreur en < 100 ms,
pas après 36 secondes.
- Suppression de la validation dupliquée dans le corps de la fonction
(redondante puisque le callback Click rejette en amont).

CHANGELOG.md
------------
Entrée [Unreleased] explicite la BREAKING CHANGE :
- L'option attend une fraction ∈ [0, 1], pas un pourcentage.
- Migration : 15.0 → 0.15.
- Le garde-fou Click callback rend la migration *bruyante* (le fix
ne peut pas être ignoré).

Tests S46 dédiés (4 ajoutés)
----------------------------
- TestMigrationGuard : 15.0 rejeté avec hint "divisez par 100",
-0.1 rejeté avec hint "≥ 0", 1.0 et 0.0 acceptés (bornes valides).

Tests : 14/14 dans tests/cli/test_fail_if_cer_above_semantics.py
+ 85 cli tests sans régression.
Lint : ruff check picarones/ tests/ → All checks passed.

Pourquoi cette deuxième passe
-----------------------------
Le premier commit (01bf885) faisait le bon fix conceptuel mais sans
filet de sécurité contre la migration. Un caller externe inconnu
(scripts BnF, HuggingFace Space CI, doc tierce) qui passait 15.0
aurait basculé silencieusement sur un seuil de 1500 %, jamais
déclenché — exactement le genre de comportement que la directive
"sans dette technique" exige d'éviter.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

CHANGELOG.md

@@ -7,6 +7,39 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ---
 
+## [Unreleased] — fix CI perf_regression — 2026-05
+
+### ⚠️ BREAKING CHANGE — sémantique `--fail-if-cer-above`
+
+L'option `picarones run --fail-if-cer-above` interprétait sa valeur
+comme un **pourcentage** (ex : `15.0` = 15 %).  Désormais elle attend
+une **fraction** ∈ [0, 1] (ex : `0.15` = 15 %), cohérent avec la
+représentation interne de `BenchmarkResult.ranking()[i]["mean_cer"]`.
+
+**Migration** : si vous passiez `--fail-if-cer-above 15.0` (intention
+« 15 % »), passez maintenant `--fail-if-cer-above 0.15`.
+
+**Garde-fou** : un callback Click rejette à l'analyse toute valeur
+> 1.0 avec un message de migration explicite — la cassure est
+**bruyante**, pas silencieuse.  Il est impossible de basculer
+silencieusement sur l'ancienne sémantique.
+
+**Pourquoi** : le job CI hebdomadaire `perf_regression.yml` passait
+`0.15` en pensant fraction, mais la CLI le traitait comme 0.15 % et
+échouait toujours.  Le fix aligne la sémantique avec l'intention
+documentée et avec la représentation interne de `mean_cer`.
+
+**Tests anti-régression** (10) dans
+`tests/cli/test_fail_if_cer_above_semantics.py` :
+
+- Sémantique fraction (sous/au seuil/None/strict 1 %/lax 50 %).
+- `perf_regression.yml` doit passer une valeur ∈ ]0, 1].
+- Help texte mentionne explicitement « fraction ».
+- Migration guard : `15.0` → `BadParameter` avec hint « divisez par 100 ».
+- `1.0` et `0.0` acceptés (bornes valides).
+
+---
+
 ## [post-Sprint 97] — chantiers de consolidation — 2026-04 → ongoing
 
 > 6 chantiers de consolidation **sans suppression** sur la branche

picarones/cli/_workflows.py

@@ -16,6 +16,38 @@ import click
 
 from picarones.cli import cli, _engine_from_name, _setup_logging
 
+
+def _validate_cer_threshold(
+    ctx: click.Context, param: click.Parameter, value: float | None,
+) -> float | None:
+    """Callback Click qui valide ``--fail-if-cer-above`` à l'analyse.
+
+    Sémantique : fraction ∈ [0, 1] (ex : 0.15 = 15 %), cohérent avec
+    ``BenchmarkResult.ranking()[i]["mean_cer"]`` qui est aussi en
+    fraction.
+
+    Garde-fou migration : avant le fix de sémantique, le seuil était
+    interprété comme un pourcentage (15.0 = 15 %).  Tout caller qui
+    passe encore une valeur > 1 vient de l'ancienne sémantique — on
+    échoue bruyamment plutôt que de muter silencieusement le
+    comportement (un seuil de 1500 % ne se déclencherait jamais et
+    l'utilisateur croirait que son CI est sain).
+    """
+    if value is None:
+        return None
+    if value < 0:
+        raise click.BadParameter(
+            f"doit être ≥ 0, reçu {value}.",
+        )
+    if value > 1.0:
+        raise click.BadParameter(
+            f"doit être une fraction ∈ [0, 1] (ex : 0.15 = 15 %), "
+            f"reçu {value}. Si vous utilisiez l'ancienne sémantique "
+            "pourcentage, divisez par 100 (ex : 15.0 → 0.15).",
+        )
+    return value
+
+
 # ---------------------------------------------------------------------------
 # picarones run
 # ---------------------------------------------------------------------------
@@ -54,6 +86,7 @@ from picarones.cli import cli, _engine_from_name, _setup_logging
     default=None,
     type=float,
     metavar="THRESHOLD",
+    callback=_validate_cer_threshold,
     help=(
         "Quitte avec code 1 si CER moyen > THRESHOLD (usage CI/CD). "
         "THRESHOLD est une fraction ∈ [0, 1] (ex : 0.15 = 15 %)."
@@ -89,6 +122,10 @@ def run_cmd(
 
     Le corpus doit être un dossier contenant des paires
     <image>.<ext> + <image>.gt.txt (vérité terrain).
+
+    ``--fail-if-cer-above`` est validé à l'analyse Click (cf.
+    ``_validate_cer_threshold``) — une valeur invalide est rejetée
+    avant toute opération coûteuse.
     """
     _setup_logging(verbose)
 
@@ -143,8 +180,7 @@ def run_cmd(
     click.echo(f"\nRésultats écrits dans : {output}")
 
     # Mode CI/CD : exit code non-zero si CER > seuil.
-    # ``fail_if_cer_above`` est une fraction ∈ [0, 1] (ex : 0.15 = 15 %),
-    # cohérent avec la représentation interne de ``mean_cer``.
+    # ``fail_if_cer_above`` est déjà validé en tête de fonction (∈ [0, 1]).
     if fail_if_cer_above is not None:
         for entry in result.ranking():
             if (

tests/cli/test_fail_if_cer_above_semantics.py

@@ -168,3 +168,69 @@ class TestCliEndToEnd:
         # Le message doit afficher les deux valeurs en pourcentage clair.
         assert "12.00%" in msg
         assert "5.00%" in msg
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Garde-fou migration : valeurs > 1.0 rejetées avec message clair
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMigrationGuard:
+    """Avant le fix B, ``--fail-if-cer-above 15.0`` voulait dire 15 %
+    (sémantique pourcentage).  Avec la nouvelle sémantique fraction,
+    un caller qui passe encore 15.0 par erreur doit obtenir une
+    erreur explicite plutôt qu'un comportement silencieusement faux
+    (seuil 1500 % qui ne se déclenche jamais)."""
+
+    def _invoke(
+        self, threshold: str, tmp_path: Path,
+    ) -> tuple[int, str]:
+        """Invoque ``picarones run --fail-if-cer-above THRESHOLD`` avec
+        un corpus tmp vide pour aller jusqu'à la validation du seuil
+        à l'analyse Click (callback ``_validate_cer_threshold``).
+        Une valeur invalide doit être rejetée à l'analyse, AVANT
+        toute opération coûteuse."""
+        from picarones.cli import cli
+        runner = CliRunner()
+        result = runner.invoke(cli, [
+            "run",
+            "--corpus", str(tmp_path),
+            "--engines", "tesseract",
+            "--output", str(tmp_path / "x.json"),
+            "--fail-if-cer-above", threshold,
+        ])
+        return result.exit_code, result.output + (result.stderr or "")
+
+    def test_value_greater_than_one_rejected_with_migration_hint(
+        self, tmp_path: Path,
+    ) -> None:
+        """Passer 15.0 (ancienne sémantique pourcentage) doit échouer
+        en early-validation avec un message qui pointe vers la
+        nouvelle sémantique."""
+        exit_code, output = self._invoke("15.0", tmp_path)
+        assert exit_code != 0
+        # Message doit contenir la valeur reçue ET la migration hint.
+        assert "15.0" in output
+        assert "fraction" in output.lower() or "0.15" in output
+        # Migration hint explicite.
+        assert "divisez" in output.lower() or "diviser" in output.lower()
+
+    def test_negative_value_rejected(self, tmp_path: Path) -> None:
+        exit_code, output = self._invoke("-0.1", tmp_path)
+        assert exit_code != 0
+        assert "≥ 0" in output or ">= 0" in output
+
+    def test_value_at_one_accepted(self, tmp_path: Path) -> None:
+        """1.0 est la borne haute valide (= 100 % de CER)."""
+        exit_code, output = self._invoke("1.0", tmp_path)
+        # Validation du seuil OK : pas de mention de "fraction" ou
+        # de migration hint.  Le run échoue ensuite parce que le
+        # corpus est vide, mais c'est un autre problème.
+        assert "doit être une fraction" not in output
+        assert "divisez" not in output.lower()
+
+    def test_value_at_zero_accepted(self, tmp_path: Path) -> None:
+        """0.0 est valide (seuil zéro tolérance)."""
+        exit_code, output = self._invoke("0.0", tmp_path)
+        assert "doit être une fraction" not in output
+        assert "≥ 0" not in output