Ustagammon/docs/organisation.md

Organisation du travail

Ce document décrit qui fait quoi et où chaque chose est consignée. Le but : que tout le travail, humain comme agentique, soit suivi et vérifiable a posteriori en lisant uniquement le dépôt.

Rôles

• Pierre, porteur du projet : décide la vision, le produit, le ton et l'identité ; valide les décisions structurantes ; lance lui-même les démonstrations de fin d'étape.
• Claude Code, session principale : chef de projet technique. Tient la feuille de route, découpe le travail, rédige les plans, délègue l'exécution à des sous-agents, vérifie leurs résultats (make lint, make test, relecture du diff), fait les commits et tient le journal.
• Sous-agents : exécutent une tâche bornée décrite par un plan. Ils ne décident rien de structurant : ils rapportent, la session principale tranche ou soumet à Pierre.

Où se trouve quoi

Document	Contenu	Mis à jour
docs/cadrage.md	Vision, périmètre, architecture cible	Quand Pierre change le cadrage
docs/feuille-de-route.md	Étapes, état de chacune, prochaine action	À chaque changement d'état
docs/etape-0.md (puis etape-N.md)	Spécification détaillée de l'étape en cours	Au début de chaque étape
docs/plans/	Un fichier par tâche déléguée : mission, consignes, résultat, vérification	Avant et après chaque délégation
docs/decisions.md	Décisions structurantes, avec raisons et alternatives	À chaque décision validée
docs/journal.md	Une entrée datée par session	En fin de session

Règle : rien d'important ne vit seulement dans la mémoire d'une session. Une information utile pour la suite est écrite dans docs/ et commitée.

Cycle d'une tâche déléguée

1. Plan : la session principale crée docs/plans/AAAA-MM-JJ-sujet.md (modèle ci-dessous) et le commite avant de lancer l'agent.
2. Délégation : l'agent reçoit le contenu du plan comme consigne ; il travaille sur une branche ou un espace de travail isolé quand il modifie du code.
3. Vérification : la session principale relit le résultat, lance make lint et make test, et contrôle les critères de réussite du plan.
4. Clôture : le plan reçoit sa section « Résultat » (fait, écarts, preuves), puis le travail est commité. Une décision qui en découle va dans docs/decisions.md (après validation de Pierre si elle est structurante).

Une tâche qui échoue est clôturée de la même façon, avec la cause : un échec documenté est un résultat.

Modèle de plan

# <Sujet>

- **Date** : AAAA-MM-JJ
- **Étape** : 0a, 0b…
- **Statut** : prévu | en cours | terminé | abandonné
- **Exécutant** : sous-agent <type> | session principale

## Objectif
Ce qui doit être vrai à la fin, en une ou deux phrases.

## Consignes
Ce que l'agent doit faire, ses limites (fichiers, dépendances, durée),
ce qu'il doit rapporter.

## Critères de réussite
Commandes ou constats vérifiables.

## Résultat
Rempli à la clôture : fait, écarts, preuves (sorties de commandes, mesures),
suites à donner.

Branches et merge requests

Aucun commit direct sur main. Pour chaque changement :

1. Une branche au nom court et explicite (moteur-reference, engine-cli…).
2. Des commits petits, en français.
3. make lint et make test au vert.
4. Une merge request sur git.sans.pub (tea pulls create --login sans-pub), dont la description permet à quelqu'un qui n'a pas suivi le travail de comprendre le changement. Rédigée en prose, pas en liste de commits :
   • Pourquoi : le problème, comment il est apparu, son impact, avec preuves ;
   • Quoi : ce qui change, du point de vue du comportement ;
   • Comment : l'approche technique et le raisonnement ;
   • Choix et compromis : alternatives écartées, limites assumées ;
   • Risques : ce qui peut casser, comment revenir en arrière ;
   • Comment vérifier : commandes exactes ;
   • Hors périmètre : ce qui a été repéré mais laissé de côté.
5. Fusion par Claude Code (commit de fusion, pour garder l'historique de la branche), puis suppression de la branche.

Une MR qui touche à un point soumis à validation (voir ci-dessous) n'est fusionnée qu'après l'accord de Pierre, consigné dans docs/decisions.md.

Validation par Pierre

Sont soumis à Pierre avant d'être appliqués : le choix de la source du moteur, le choix du socle (PWA ou Android), toute nouvelle dépendance, tout ce qui touche au produit ou à l'identité. Le reste est décidé par la session principale et consigné.