From edd52c7c0e399177da1f72838ce4c562f9ce6198 Mon Sep 17 00:00:00 2001 From: fy59 Date: Wed, 26 Aug 2026 17:38:44 +0200 Subject: [PATCH] docs: update agent engineering contract --- AGENTS.md | 301 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 172 insertions(+), 129 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 620b1ed..50d40bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,147 +1,190 @@ -# Guide des agents Lardon3D +# Lardon3D — Agent Engineering Contract -## Validation obligatoire +## 1. Authority and priority -Avant livraison, exécuter réellement : +- The root `README.md` is the index of project documentation. +- Canonical documents under `docs/**` define scientific contracts, architecture, + FROZEN invariants, and roadmap ordering. +- Before changing an architectural or scientific area, identify and read the + relevant canonical document and its applicable invariants. +- FROZEN documentation and contracts must never be changed silently to fit an + implementation. A lower-level convenience never overrides a higher-level + canonical contract. +- If requested work, code, and a FROZEN contract genuinely conflict: stop the + affected change, report the contradiction, and require an explicit human + decision. Do not choose a new policy implicitly. + +## 2. FROZEN integrity + +The following historical foundation is protected and may change only through +an explicitly authorized, explicitly scoped human ticket: + +- Gates A–G — PASS/FROZEN +- Track Model — PASS/FROZEN +- Builder — PASS/FROZEN +- F0 — PASS/FROZEN +- Phase H v1 — PASS/FROZEN +- MVS-M1 — PASS/FROZEN +- Project DB v18 + +When a ticket declares `NO_NEW_SUBSYSTEM`, do not introduce Task Runtime, +Queue, Governor, scheduler, pools, persistence, viewer, mesh, texturing, +scratch/SSD, or another deferred subsystem. This file states invariants and +working rules; it does not duplicate a roadmap snapshot or claim that a +deferred subsystem can never exist. + +## 3. Scope and Git discipline + +- Inspect `git status` before editing. +- Preserve unrelated user and worktree changes. +- Modify only files explicitly authorized by the ticket. +- Never modify or add anything under `scan3d/`, especially + `scan3d/tri_photos.py`. +- Never use `git add -A` against the real repository index. +- Without explicit human authorization, never commit, push, reset, restore, + checkout files, stash, clean, or perform another destructive Git operation. +- Never discard unrelated modifications. +- At delivery, list the exact files modified by the ticket. + +For review of untracked files, a temporary `GIT_INDEX_FILE` may be used when +necessary. Add paths explicitly; do not use `git add -A`; keep the real index +untouched; remove the temporary index afterward. Do not use this machinery when +a normal diff is sufficient. + +## 4. Language / API / ABI rules + +- Public C APIs must remain valid C17. +- C++ must remain within the standard configured by Meson; the repository is + intentionally mixed-language and must not be treated as C-only. +- Preserve public API and ABI unless the ticket explicitly authorizes change. +- No C++ exception may cross an `extern "C"` or other public C ABI boundary. +- Keep ownership and lifetime rules explicit. +- Do not introduce undefined behavior, unchecked narrowing, or unchecked + integer overflow. +- Reject silent path truncation. +- Deterministic serialization must use explicit fixed widths and byte order; + never depend on native struct padding or native endianness. + +## 5. Architecture and resources + +- Keep TUI/ncurses ownership separate from business logic and layout according + to canonical architecture. +- Keep ncurses on its designated/main thread wherever the canonical contract + requires it. +- Extend validated abstractions rather than rewriting validated modules. +- System stability and responsiveness take priority over throughput. +- Bound memory, buffers, files, descriptors, processes, threads, and captured + output reasonably for the operation. +- Memory shared with an iGPU counts against host RAM. +- zram and swap are pressure/safety mechanisms, not normal working-memory + budgets. +- Do not invent a global resource subsystem inside a ticket that defers it. +- Contractually atomic outputs must remain atomic; failure paths must clean all + resources owned by the current operation without deleting unrelated data. + +## 6. Code quality and readability + +- Clang and Meson are the reference build tools. +- Do not add global mutable state unless an established historical contract + explicitly permits it. +- Clean allocations, file descriptors, processes, mutexes, conditions, and + threads explicitly. +- Do not use `system()` or `popen()` in production where direct process + execution is required. +- Do not leave TODOs, dead code, or accidental dependencies in a completed + ticket. +- Prefer minimal evolution to rewrites. +- Target approximately 100 columns; normally do not exceed 120 without local + justification. +- Do not use code golf or compress multiple logical operations onto a line. +- Split complex code when that materially improves auditability. +- Temporary probes, benchmarks, diagnostics, C/C++/GLSL files, and scripts + under `/tmp` must also be readable and auditable. +- Comments should explain non-obvious invariants, not paraphrase code. +- Formatting-only changes must not alter behavior. + +## 7. External processes and filesystem + +- Prefer direct process execution over shell command strings. +- Explicitly own, monitor, and reap child processes. +- Use process groups when required and prevent orphaned children. +- Bound retained stdout/stderr where applicable and drain output when required + to avoid deadlocks. +- Clean owned resources on every success and failure path. +- Do not assume a CLI flag exists without evidence. +- Authoritative upstream documentation or source may be inspected for external + dependencies. +- Temporary probes, clones, and builds under `/tmp` are allowed when useful. +- Do not use `sudo`, modify the host persistently, install system packages + without explicit authorization, or add a permanent repository dependency + without explicit authorization. + +## 8. Documentation discipline + +- Do not create duplicate canonical documents for one contract. +- Link every new canonical document under `docs/**` from the root `README.md`. +- For changes to API, architecture, ownership, concurrency, persistence, + pipeline, or limits, check whether canonical documentation must be updated. +- Documentation must describe proven implementation, not desired future + behavior. +- Statuses such as PLANNED, IMPLEMENTED, VALIDATION PENDING, and PASS/FROZEN + are authoritative lifecycle statements: update them only when the required + implementation, validation, and review evidence supports the state. +- Never mark work PASS/FROZEN without the required validation and review. + +## 9. Required validation + +For ordinary implementation tickets, before claiming completion, actually run +the applicable commands: ```sh -CC=clang meson setup build --wipe meson compile -C build -j8 -meson test -C build --print-errorlogs +meson test -C build --num-processes 1 --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. +If build configuration must be regenerated, follow the documented Clang/Meson +setup and do not blindly wipe a valid build tree. -## Git et périmètre +For a new or modified public C header, also run a C17 syntax check, for example: -- 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. +```sh +cc -x c -std=c17 -fsyntax-only -Iinclude \ + -include lardon3d/
.h /dev/null +``` -## Architecture à préserver +For memory/lifetime-sensitive changes, use a separate ASan/UBSan build and do +not overwrite the normal build. For relevant concurrency changes, run TSan +when supported. If a sanitizer is unavailable or invalid because of the +environment/toolchain, report that explicitly rather than claiming PASS. -- 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. +Run expensive or stress validation only when relevant, one heavy validation at +a time. Investigate a timeout; do not rerun it until it happens to pass. +Distinguish third-party sanitizer noise from repository defects using concrete +stack and failure evidence. Never claim a command, test, sanitizer, or review +that was not actually performed. -## Principes non négociables +## 10. Delivery report / STOP conditions -- 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. +Every completed ticket report must include: -## Contraintes de code +- exact files modified; +- concise implementation description; +- validations actually executed and exact results; +- tests or checks not executed; +- known blockers; +- non-blocking findings; +- deliberately deferred/future-scope items; +- confirmation that unrelated and FROZEN areas were preserved. -- 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. -- Viser 100 colonnes et ne jamais dépasser 120 sans justification locale. -- Mettre les appels complexes et le SQL sur plusieurs lignes lisibles. -- Éviter le code-golf et garder des fonctions confortables à relire dans Neovim. -- Commenter les invariants non évidents plutôt que paraphraser le code. +STOP and request a human decision if: -## Lisibilité du code +- requested work contradicts a FROZEN contract; +- satisfying it requires files outside the authorized scope; +- a scientific contract or identity must change without authorization; +- a new subsystem or dependency is required contrary to scope; +- destructive Git action is required; +- incompatible policies remain unsettled by canonical documentation. -Ces règles s'appliquent aussi bien au code du dépôt qu'au code temporaire -créé pour les benchmarks, diagnostics, expérimentations ou probes matériels. - -- Viser environ 100 colonnes par ligne. -- Limite absolue : 120 colonnes. -- Ne pas compresser plusieurs instructions logiques sur une même ligne. -- Aucun code-golf, même pour un prototype. -- Les fichiers temporaires C, C++, GLSL et les scripts doivent rester - lisibles et auditables. -- Découper les grosses fonctions en responsabilités claires lorsque cela - améliore la compréhension. -- Les benchmarks et prototypes doivent pouvoir être relus et débogués - facilement. -- Un reformatage ne doit jamais modifier le comportement. -- Ces règles s'appliquent également aux fichiers créés sous `/tmp`. - -## Validation longue - -- Une seule validation lourde à la fois : normal, ASan/UBSan, TSan puis stress. -- Un timeout doit être isolé et expliqué ; le répéter jusqu'au vert est interdit. -- Après les tests verts, imposer revue, audit de concurrence si pertinent, - documentation, corrections et revalidation ciblée. - -## É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 `import.images` utilise le scheduler générique, ses lots - adaptatifs et ses checkpoints persistants. -- 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é. - -## Règles documentaires - -### README.md racine -Le README.md à la racine est le sommaire canonique de la documentation. - -### Vérification avant ticket architectural -Avant un ticket architectural important : -1. Identifier le document canonique correspondant dans docs/ -2. Le lire -3. Vérifier que le ticket respecte ses invariants - -### Mise à jour après ticket -Après un ticket modifiant : -- API -- Architecture -- Ownership -- Concurrence -- Persistance -- Pipeline -- Limites - -Appeler lardon-docs avant de considérer le ticket terminé. - -### Contradictions code/documentation -Si code et documentation architecturale se contredisent : -1. Ne pas choisir silencieusement -2. Signaler la contradiction -3. Décider quelle spécification doit devenir canonique -4. Mettre la documentation à jour -5. Seulement ensuite poursuivre - -### Nouveaux documents -Tout nouveau document docs/** doit être référencé depuis README.md si c'est -un document canonique destiné aux lecteurs du projet. - -### Unicité des documents -Ne jamais créer plusieurs documents canoniques décrivant le même contrat. +Do not stop merely because an ordinary local implementation detail can be +resolved safely from existing code and documentation.