docs: aligner les instructions agents sur le guide

Co-authored-by: codex/gpt-5.6-sol <codex-gpt-5.6-sol@agents.invalid>

AGENTS.md

@@ -14,9 +14,10 @@
 ## 2. Stack technique
 
 ### Langage et dépendances
-- **Python** : ≥ 3.13 (actuellement 3.14 dans `.venv/`)
+- **Python** : ≥ 3.13.5 (actuellement 3.14 dans `.venv/`)
 - **Dépendances principales** :
-  `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, `feedparser`, `requests`, `httpx`
+  `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`,
+  `feedparser`, `beautifulsoup4`, `requests`, `httpx`, `openai`
 
 ### Outils de développement
 - **Linter** : `ruff` (longueur de ligne : 100)
@@ -36,6 +37,7 @@
 ```
 pronote_sync/
 ├── config/          # Configuration et paramètres
+├── errors.py        # Hiérarchie canonique des erreurs du pipeline
 ├── models/          # Modèles de données (Pydantic v2)
 ├── sources/         # Connecteurs (Pronote, iCal, etc.)
 ├── sync/            # Logique de synchronisation
@@ -110,6 +112,8 @@ pronote-sync --dry-run
 
 ### Architecture
 - **Injection de dépendances** : Utiliser `typing.Protocol` et une **composition root** dans `pipeline/run.py`. **Interdiction** des singletons globaux.
+- **Erreurs** : Conserver une seule hiérarchie dans `pronote_sync/errors.py` ; ne pas créer de
+  doublon dans `pipeline/steps/errors.py`.
 
 ### Style
 - **Longueur de ligne** : 100 caractères maximum (configuré dans `ruff`).
@@ -123,12 +127,30 @@ pronote-sync --dry-run
 - **Idempotence** : Deux exécutions identiques sans changement externe doivent produire le **même résultat**.
 - **Mode dégradé** :
   - Si l'IA échoue → retourner un message **sans synthèse**.
-  - Si `pronotepy` échoue → fallback vers le parsing **iCal**.
-  - Si tout échoue → lever une **erreur explicite**.
+  - En mode source `auto`, essayer iCal puis utiliser `pronotepy` uniquement si iCal lève une
+    exception.
+  - En mode source explicite (`ical` ou `pronotepy`), ne pas changer silencieusement de source.
+  - En mode `auto`, si iCal et `pronotepy` échouent → lever une erreur critique explicite.
+  - Une liste vide est un succès valide ; elle ne doit pas être assimilée à une panne.
+
+### Contrat des sources Pronote
+- `PRONOTE_URL` (connexion API) et `PRONOTE_ICAL_URL` (flux iCal sensible) sont deux paramètres
+  distincts ; ne pas déduire l'un de l'autre.
+- Le compte actuellement visé est un compte parent : utiliser
+  `pronotepy.ParentClient(pronote_url, username, password, ent=ent_function)`.
+- Résoudre le slug `PRONOTE_ENT` vers une fonction de `pronotepy.ent` au moyen d'une liste fermée.
+- Exposer séparément les cours et les devoirs dans le client ; filtrer les devoirs `pronotepy` sur
+  la date cible.
+- Les récupérations critiques agenda/devoirs propagent une erreur expurgée ; seuls les messages et
+  informations non critiques peuvent se dégrader en liste vide avec warning.
+- Réutiliser un téléchargement/parsing iCal pour l'agenda et les devoirs pendant un même run, sans
+  cache global ni persistant.
 
 ### Documentation (docstrings)
 - **Obligatoire** : **Toute** fonction, méthode et classe publique doit avoir une docstring.
 - **Format** : Utiliser le format **Sphinx/reST** (pas Google ou NumPy) pour une compatibilité native avec Sphinx.
+- **Priorité** : Les blocs historiques de `GUIDE_DEV_PYTHON.md` utilisant `Args:`/`Returns:` sont
+  illustratifs ; le format Sphinx/reST défini ici prévaut pour le code de production.
 - **Contenu** :
   - Une ligne de résumé courte (une phrase).
   - Une description étendue optionnelle.
@@ -157,6 +179,11 @@ def fetch_ical(url: str) -> str:
 ### Règles absolues
 - **Aucun secret en clair** : Ni dans le code, ni dans les logs, ni dans les erreurs, ni dans les fixtures.
 - **Masquage** : Utiliser systématiquement `redact_url()`, `redact_secrets()`, et `redact_exception()` depuis `utils/redaction.py`.
+- **Chaînage d'exceptions** : Ne jamais conserver comme `__cause__` ou `__context__` une exception
+  externe brute susceptible de contenir un secret. Journaliser la version expurgée puis utiliser
+  `raise ... from None`, ou chaîner une cause elle-même expurgée.
+- **Tests de non-fuite** : Vérifier les messages, les logs, `__cause__`, `__context__` et le
+  traceback complet avec des sentinelles distinctes pour chaque secret.
 
 ### Bonnes pratiques
 - **Types sécurisés** : Les mots de passe et clés API doivent utiliser `pydantic.SecretStr`.
@@ -225,14 +252,17 @@ Les rôles d'agents disponibles pour ce projet sont les suivants :
 
 ## 10. Workflow de modification
 
-1. Lire la demande, [`TODO.md`](./TODO.md), `git status` et les fichiers concernés.
+1. Lire la demande, [`TODO.md`](./TODO.md), les sections pertinentes de
+   [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md), `git status` et les fichiers concernés.
 2. Préserver les changements existants de l'utilisateur.
 3. Pour une correction, reproduire d'abord le défaut avec un test automatisé lorsque c'est raisonnable.
-4. Faire une modification étroite et cohérente, en respectant les conventions du projet (idempotence, mode dégradé, repli iCal/pronotepy).
+4. Faire une modification étroite et cohérente, en respectant les conventions du projet
+   (idempotence, modes explicites stricts et repli iCal → `pronotepy` uniquement en mode `auto`).
 5. Faire vérifier le comportement par `@verifier` (ruff, mypy, pytest, bandit) et les cas d'erreur, notamment :
    - Succès de la synchronisation Pronote → CalDAV/XMPP.
-   - Repli vers iCal en cas d'échec de `pronotepy`.
-   - Gestion des erreurs explicites.
+   - Repli d'iCal vers `pronotepy` en mode `auto`, sans repli dans les modes explicites.
+   - Distinction entre résultat vide et échec des sources.
+   - Gestion des erreurs explicites sans fuite dans les causes ou tracebacks.
 6. Mettre à jour la documentation et les exemples dans le même changement si leur comportement public évolue.
 7. Cocher dans [`TODO.md`](./TODO.md) uniquement les éléments entièrement réalisés et validés.
 8. Terminer avec un *handoff* concis : fichiers modifiés, validations exécutées, limites et prochaine étape.
@@ -277,7 +307,8 @@ Les rôles d'agents disponibles pour ce projet sont les suivants :
 
 Un changement est considéré comme **terminé** lorsque :
 
-- Le cas nominal et les échecs pertinents sont testés (ex. : synchronisation réussie, repli iCal, erreurs explicites).
+- Le cas nominal et les échecs pertinents sont testés (ex. : synchronisation réussie, repli
+  iCal → `pronotepy` en mode `auto`, modes explicites stricts, erreurs explicites).
 - Les outils de validation (`ruff`, `mypy`, `pytest`, `bandit`) passent sans erreur.
 - Aucun secret ni configuration locale n'apparaît dans le diff ou les fichiers suivis.
 - La documentation reste cohérente avec le code (ex. : mise à jour des exemples, des contrats ou des décisions d'architecture).