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 le dépôt et ses merge requests.

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), rédige les ADR, ouvre et fusionne les merge requests, 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

Deux familles de documents, de durée de vie différente (ADR 0001).

Durables : ils restent et font foi.

Document	Contenu	Mis à jour
docs/cadrage.md	Vision, périmètre, architecture cible	Quand Pierre change le cadrage
docs/adr/	Un ADR par décision structurante ; index dans docs/adr/README.md	À chaque décision ; jamais réécrit une fois accepté
docs/journal.md	Une entrée datée par session : fait, décidé, suite	En fin de session
docs/glossaire/	Une fiche par terme du jeu, avec sa traduction anglaise utilisée dans le code (ADR 0008)	Avec chaque nouveau terme du domaine
docs/scenarios/	Documentation utilisateur en scénarios, aussi tests de bout en bout (ADR 0008)	Avec chaque fonction visible
Merge requests (git.sans.pub)	Le détail de chaque changement : pourquoi, comment, vérification	À chaque changement

Temporaires : ils décrivent le travail à faire et disparaissent une fois réalisé.

Document	Contenu	Cycle de vie
docs/feuille-de-route.md	Le travail restant et son état	Une ligne réalisée est retirée
docs/etape-N.md	Spécification détaillée de l'étape en cours	Supprimé à la fin de l'étape
docs/plans/	Un plan par tâche déléguée (modèle : docs/plans/README.md)	Supprimé quand la tâche est close

Règle : rien d'important ne vit seulement dans la mémoire d'une session, ni seulement dans un document temporaire. Avant de supprimer un plan, ce qu'il contient de durable passe dans un ADR, dans la description de la merge request ou dans le journal.

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

1. Plan : la session principale crée docs/plans/AAAA-MM-JJ-sujet.md et le commite sur la branche de la tâche avant de lancer l'agent.
2. Délégation : l'agent reçoit le contenu du plan comme consigne ; il travaille dans un espace isolé quand il modifie du code.
3. Vérification : la session principale relit le résultat, recoupe les affirmations décisives, lance make lint et make test, et contrôle les critères de réussite du plan.
4. Clôture : une décision qui en découle devient un ADR (après validation de Pierre si elle est structurante). Le plan est supprimé dans la même merge request, dont la description reprend le résultat et les preuves.

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

Branches et merge requests

Aucun commit direct sur main (ADR 0006). 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.

Règles de forme pour Gitea :

• les hash de commit s'écrivent sans backticks, sinon Gitea ne crée pas de lien ;
• pas d'émojis ni d'autres caractères sur 4 octets dans les titres et descriptions : la base de données du serveur les refuse.

Une MR qui touche à un point soumis à validation n'est fusionnée qu'après l'accord de Pierre, consigné dans l'ADR correspondant.

Validation par Pierre

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