From 3d4a13be606f50d8669e4bb42969b9329c0164c6 Mon Sep 17 00:00:00 2001 From: fy59 Date: Thu, 6 Aug 2026 21:20:35 +0200 Subject: [PATCH] docs: add repository architecture and agent guidelines --- AGENTS.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8eaa35e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# Guide des agents Lardon3D + +## Validation obligatoire + +Avant livraison, exécuter réellement : + +```sh +CC=clang meson setup build --wipe +meson compile -C build -j8 +meson test -C build --print-errorlogs +git diff --check +``` + +Pour les changements sensibles à la mémoire ou aux durées de vie, ajouter un +build ASan/UBSan séparé. Pour toute concurrence, exécuter aussi TSan lorsque +disponible. Ne jamais annoncer une vérification non exécutée. + +## Git et périmètre + +- Ne jamais utiliser `git add -A`. +- Ne jamais ajouter ou modifier `scan3d/`, notamment + `scan3d/tri_photos.py`. +- Ne faire ni commit ni push depuis le sandbox. +- Préserver les changements existants hors ticket. +- Fournir à la fin la liste exacte des fichiers appartenant au ticket. + +## Architecture à préserver + +- La TUI orchestre les entrées et ncurses ; le métier et le layout restent + séparés. Le layout dessine uniquement et ne modifie aucun état. +- ncurses appartient exclusivement au thread principal. +- Toute tâche possède une estimation immuable et une réservation valide avant + son exécution. Aucun callback ne démarre sans réservation active. +- Le Resource Governor décide des budgets, slots et lots. Le scheduler applique + le FIFO et exécute le contrat ; il ne réinterprète jamais les ressources. +- Les API à durée de vie complexe restent opaques, avec propriété et nettoyage + explicites. + +## Principes non négociables + +- La stabilité du système hôte et la réactivité de la TUI passent avant le + débit. +- Aucun traitement lourd monolithique : utiliser des séquences adaptatives. +- Budgets, files et buffers doivent être bornés. +- La RAM d'un iGPU partagé appartient au budget RAM système. +- La zram est un filet de sécurité, jamais un budget de travail. +- Publier uniquement des sorties atomiques validées ; effectuer un rollback + ciblé sans toucher aux données antérieures. +- Préserver des frontières permettant la reprise après interruption. +- Le viewer reste séparé, lecteur de snapshots validés et non bloquant. + +## Contraintes de code + +- C17, Clang, Meson et ncursesw. +- Aucune variable globale d'état. +- Nettoyer explicitement chaque allocation, descripteur, mutex, condition et + thread. +- Ne pas utiliser `system()` ni `popen()` dans le code de production. +- Ne laisser aucun `TODO`, code mort ou dépendance inutile dans un ticket fini. +- Préférer l'évolution minimale aux réécritures de modules validés. + +## État actuel + +- Moteur de tâches FIFO, un worker, pause et annulation coopératives. +- Gouverneur thread-safe avec estimations, budgets et réservations opaques. +- Scheduler relié au gouverneur ; réservation obligatoire avant callback. +- Aucun DAG, aucune priorité, aucun pool de workers. +- L'import asynchrone utilise encore son worker dédié et n'est pas migré vers + le scheduler générique. +- Le viewer Vulkan n'est pas commencé. + +## Prochains tickets recommandés + +1. Sélectionner une tâche admissible sans blocage par la tête de file. +2. Introduire le DAG et les dépendances. +3. Persister les tâches et checkpoints de reprise. +4. Orchestrer et mesurer les séquences adaptatives. +5. Ajouter les pools bornés CPU, IO et GPU. +6. Migrer l'import vers le scheduler générique. +7. Ajouter la publication live validée, puis le viewer Vulkan séparé.