college-infos/AGENTS.md

# Guide pour les agents et contributeurs — `pronote-sync`

> **Langue de travail** : Français (ce fichier et toute la documentation projet).

---

## 1. Description du projet
`pronote-sync` est un pipeline Python qui synchronise les données de **Pronote** (système de gestion scolaire) vers **CalDAV** (agendas) et **XMPP** (notifications).

> **Spécification complète** : Voir [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md).

---

## 2. Stack technique

### Langage et dépendances
- **Python** : ≥ 3.13 (actuellement 3.14 dans `.venv/`)
- **Dépendances principales** :
  `pydantic>=2.0`, `pydantic-settings`, `icalendar`, `caldav`, `slixmpp`, `pronotepy`, `feedparser`, `requests`, `httpx`

### Outils de développement
- **Linter** : `ruff` (longueur de ligne : 100)
- **Typage** : `mypy` (mode `strict=true`)
- **Tests** : `pytest` (couverture ≥ 90%), `pytest-mock`, `responses`, `aioresponses`
- **Sécurité** : `bandit`
- **Pre-commit** : hooks configurés pour `ruff`, `mypy`, `bandit`

### Environnement
- **Virtualenv** : `.venv/` (à activer avant toute opération)
- **Fichier de configuration** : `.env` (à partir de `.env.example`)

---

## 3. Structure du projet

```
pronote_sync/
├── config/          # Configuration et paramètres
├── models/          # Modèles de données (Pydantic v2)
├── sources/         # Connecteurs (Pronote, iCal, etc.)
├── sync/            # Logique de synchronisation
├── synthesis/       # Génération de synthèses (IA)
├── channels/        # Canaux de sortie (CalDAV, XMPP)
├── pipeline/        # Orchestration du pipeline
├── utils/           # Utilitaires (redaction, logging, etc.)
├── cli/             # Interface en ligne de commande
└── __init__.py

tests/
├── fixtures/        # Données de test anonymisées
├── unit/            # Tests unitaires
└── integration/     # Tests d'intégration
```

> **Plan de développement** : Voir [`TODO.md`](./TODO.md) pour les 15 jalons (M1-M15).

---

## 4. Commandes essentielles

### Environnement
```bash
# Activer le virtualenv
source .venv/bin/activate

# Installer les dépendances de développement
pip install -e ".[dev]"
```

### Qualité de code
```bash
# Linter (ruff)
ruff check .

# Formattage (ruff)
ruff format .

# Vérification des types (mypy)
mypy .

# Analyse de sécurité (bandit)
bandit -r pronote_sync/

# Pre-commit (tous les hooks)
pre-commit run --all-files
```

### Tests
```bash
# Exécuter les tests
pytest

# Exécuter les tests avec couverture
pytest --cov
```

### CLI
```bash
# Exécuter en mode dry-run (simulation)
pronote-sync --dry-run
```

---

## 5. Conventions de code

### Typage
- **Strict** : `mypy` en mode `strict=true`. **Tous** les paramètres, retours et variables locales doivent être typés.
- **Pydantic v2** : Tous les modèles de données héritent de `BaseModel`. Les modèles de contrat utilisent `frozen=True`.

### Architecture
- **Injection de dépendances** : Utiliser `typing.Protocol` et une **composition root** dans `pipeline/run.py`. **Interdiction** des singletons globaux.

### Style
- **Longueur de ligne** : 100 caractères maximum (configuré dans `ruff`).
- **Imports** : Triés automatiquement par `ruff` (intègre `isort`).

### Tests
- **Sans réseau** : Utiliser **uniquement** des mocks (`pytest-mock`, `responses`, `aioresponses`).
- **Fixtures** : Les données de test doivent être anonymisées et stockées dans `tests/fixtures/`.

### Comportement
- **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**.

---

## 6. Sécurité et secrets

### 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`.

### Bonnes pratiques
- **Types sécurisés** : Les mots de passe et clés API doivent utiliser `pydantic.SecretStr`.
- **Fichier `.env`** : **Jamais** committé (couvert par `.gitignore`). Utiliser `.env.example` comme template.

---

## 7. Plan de développement

Le projet suit un plan séquentiel en **15 jalons** (M1-M15) décrits dans [`TODO.md`](./TODO.md).

- Chaque jalon a des **critères d'acceptation** à valider avant de passer au suivant.
- Ordre logique :
  **scaffolding → config → modèles → sources → sync → synthèse → canaux → pipeline → CLI → tests → déploiement → docs**

---

## 8. Référence

| Document | Rôle |
|----------|------|
| [`GUIDE_DEV_PYTHON.md`](./GUIDE_DEV_PYTHON.md) | Spécification complète (architecture, modèles, parsing, déploiement) |
| [`TODO.md`](./TODO.md) | Plan de développement détaillé (15 jalons) |

---

## 9. Agents OpenCode

Cette section s'applique uniquement lorsque le travail est exécuté avec le système d'agents d'OpenCode.

Les rôles d'agents disponibles pour ce projet sont les suivants :

- `@architect` : Arbitrages d'architecture et choix techniques structurants pour le pipeline `pronote-sync`.
- `@coder` : Opérations de développement et changements de code dans le projet.
- `@debugger` : Reproduction d'un symptôme et établissement de sa cause profonde (ex. : échec de synchronisation, repli iCal/pronotepy).
- `@explorer` : Exploration du dépôt en lecture seule et fourniture de contexte factuel.
- `@orchestrator` : Compréhension globale du projet, définition des jalons, coordination et garantie du résultat.
- `@planner` : Transformation d'une demande complexe en unités exécutables avec frontières et dépendances claires.
- `@reviewer` : Revues indépendantes de correction, régression, contrats et maintenabilité.
- `@security-auditor` : Audit indépendant d'une surface de sécurité désignée (ex. : gestion des secrets, masquage des données).
- `@tech-writer` : Rédaction et maintenance de documentation technique exacte et vérifiable.
- `@test-engineer` : Conception, écriture et exécution de tests ciblés (unitaires, intégration, mocks).
- `@ui-designer` : conception et implémentation d'interfaces Web et terminal.
- `@verifier` : Vérification indépendante du comportement livré, des régressions et du respect des conventions (idempotence, mode dégradé).
- `@web-explorer` : Recherche et extraction de sources Web vérifiables (ex. : documentation Pronote, CalDAV, XMPP).

> **Note** : Ne pas utiliser `@coder` pour les tâches de documentation (`@tech-writer`) ni pour les tests (`@test-engineer`).

---

## 10. Workflow de modification

1. Lire la demande, [`TODO.md`](./TODO.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).
5. Vérifier le comportement nominal 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.
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.

> **Pour les changements larges ou risqués** : Produire d'abord un audit ou un aperçu.
> **Règle de commit** : Ne pas committer sans autorisation explicite. Une autorisation de commit ne vaut pas autorisation de push.

---

## 11. Branches et commits

- Une évolution cohérente se fait sur une **branche dédiée**.
- Nommer les branches selon le format `<type>/<sujet-en-kebab-case>`, où `<type>` est l'un des suivants :
  `feature`, `fix`, `docs`, `chore` ou `refactor`.
- Partir de l'état validé de la branche principale (`main` ou `dev`), sauf demande explicite.
- Garder **un commit atomique par objectif vérifiable**. Utiliser les préfixes conventionnels pour les messages de commit :
  - `feat:` pour une nouvelle fonctionnalité.
  - `fix:` pour une correction de bug.
  - `docs:` pour une mise à jour de documentation.
  - `chore:` pour une tâche de maintenance.
  - `refactor:` pour une refactorisation de code.
- Quand un agent a contribué au changement, ajouter un *trailer* Git standard au commit :
  ```
  Co-authored-by: <harness>/<modèle> <adresse@agents.invalid>
  ```
- Avant un commit autorisé, vérifier :
  - `git status` (fichiers modifiés attendus).
  - Le diff complet (`git diff`).
  - L'absence de secret ou de configuration locale dans le diff.
  - Les validations pertinentes (`ruff`, `mypy`, `pytest`, `bandit`).
  - `git diff --check` (pas de problèmes d'espaces blancs).
- Après le commit, rapporter :
  - Le hash du commit.
  - Le contenu du commit.
  - Les validations exécutées.

> **Règle absolue** : Ne jamais pousser (`git push`) sans demande distincte et explicite.

---

## 12. Définition de terminé

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).
- 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).
- Le *handoff* distingue clairement :
  - Ce qui a été vérifié localement (ex. : tests unitaires, linter).
  - Ce qui nécessite encore une vérification manuelle (ex. : tests d'intégration avec un serveur CalDAV réel).