# Consignes pour un agent qui modifie un corpus de spécifications Tu interviens sur un dossier de fichiers YAML qui décrivent un processus métier. Ce dossier est la **source de vérité** : les `.svg` et les `.html` en sont dérivés, jamais l'inverse. Ne modifie jamais un fichier généré. ## Comment tu sais si ton travail tient Tu n'as **rien à installer et aucun appel réseau à faire**. Le moteur tourne dans l'onglet que ton interlocuteur garde ouvert sur ce dossier. Il relit le disque toutes les deux secondes et, à chaque changement, réécrit : - **`.spec-rapport.json`** — le verdict complet du dossier ; - les `.svg`, `PROCESSUS-DETAILLE.html`, les récits de test et le Gherkin. **Ta boucle de travail est donc : modifier un `.yaml`, attendre deux secondes, relire `.spec-rapport.json`.** C'est un fichier local comme un autre. ```json { "sain": false, "nombre_de_violations": 1, "violations": [ {"fichier": "AT-ARRIVEE-CDI.yaml", "message": "étape 2 (arrivee.saisir_identite) : champ obligatoire sans valeur — telephone"} ], "fichiers": [{"fichier": "PU-MANAGER-ARRIVEE.yaml", "type": "parcours", "sain": true}], "bifurcations_non_couvertes": ["…"], "fichiers_generes": ["…"] } ``` **Ne propose rien tant que `sain` n'est pas revenu à `true`.** Un corpus qui ne passe pas le gate n'est pas une spécification, c'est un brouillon. Si `.spec-rapport.json` n'existe pas ou ne bouge plus, l'onglet est fermé : demande qu'on rouvre et qu'on y recharge le dossier. C'est la seule mise en route, et elle se fait une fois. Les fichiers dérivés ne sont réécrits que si le corpus est **sain** — régénérer depuis un document en faute produirait des schémas faux, plus trompeurs qu'absents. --- ## Les sept types de documents Le type d'un fichier se reconnaît à sa clé de tête. N'en invente pas d'autre. | Clé de tête | Ce que c'est | Étape | |---|---|---| | `steps:` | un **parcours** — ce que vit UN acteur, de bout en bout | 2 | | `nodes:` | le **flux inter-acteurs** — la topologie, qui reprend la main et quand | 3 | | `regles:` | le **catalogue des règles métier** | 5 | | `deroule:` | un **test d'acceptation** — le chemin nominal, avec des valeurs | 6 | | `comportements:` | les **comportements isolés** — ce qui se passe quand ça ne passe pas | 7 | --- ## Les règles qui gouvernent le corpus Elles ne sont pas des conventions de style : le gate les fait respecter. **Un parcours n'a qu'un seul acteur.** Si deux personnes agissent, ce sont deux parcours, et c'est le flux qui les articule. **Le temps se dit en deux chiffres, pas en prose.** `pt` est le temps réellement passé, `dt` le temps d'attente subi avant que la suite puisse commencer. Une étape d'attente n'existe pas : l'attente est portée par le `dt` de l'étape qui précède. **Un événement de clôture doit figurer parmi les événements possibles.** Et `dt > 0` si et seulement si l'événement qui clôt une étape n'est pas celui qui ouvre la suivante. **L'ordre des nœuds du flux est l'axe du temps** sur le diagramme : le premier nœud est la colonne de gauche. Le renderer n'utilise pas les arêtes pour placer. Une liste mal ordonnée produit un schéma qui raconte n'importe quoi. `parallel` décrit des actions **différentes** menées de front. `joint` décrit **une seule** action faite ensemble par plusieurs acteurs. Ne les confonds pas. **Une règle métier ne s'écrit qu'une fois**, dans le catalogue. Une interaction la cite par sa référence (`regle: RM-…`). Recopier un énoncé le fera diverger de lui-même. **Un champ appartient à une section d'écran ; une action le cite par son identifiant.** Jamais deux listes parallèles. **Un observable nomme ce qu'un test pourra constater — sans le valuer.** C'est le seul vocabulaire sur lequel un test a le droit d'asserter. --- ## Écrire un test Un test **ne redit rien du processus**. L'intitulé de l'action, les champs qu'elle remplit, la règle qu'elle applique et ce qu'on peut en observer sont déjà écrits ; le test ne porte que ce que la spécification ne peut pas porter : > un état de départ · des valeurs · des attendus Le `call` **localise** l'action, il ne la décrit pas. ```yaml - call: arrivee.choisir_type_contrat valeurs: {type_de_contrat: "CDD", motif_du_cdd: "Remplacement"} attendus: {motif_obligatoire: true} ``` Ce que le gate refuse, et qu'il est inutile de tenter : - une valeur sur un champ que l'action ne remplit pas ; - un champ obligatoire laissé sans valeur (sauf s'il est aussi conditionnel) ; - un attendu sur autre chose qu'un observable déclaré ; - un `call` que personne ne déclare ; - une bifurcation que l'action n'a pas prévue ; - un `reprend` vers un test d'acceptation qui n'existe pas. **L'état de départ est explicite, nommé, et inclut le temps.** Une absence est un état de départ (`absent: true`), pas un attendu : sans elle le scénario n'est pas rejouable deux fois. Une date de référence (`donnee: date_du_jour`) est un état de départ : sans elle, « à moins de deux jours » dépend du jour où l'on lance le test. **Plusieurs tests d'acceptation sur le même processus, c'est l'usage attendu**, pas une duplication. Ils se distinguent par leur départ et leurs valeurs, jamais par leur description. **Un comportement isolé reprend un chemin nominal** jusqu'à une action nommée, puis diverge. Sa divergence peut demander plusieurs actions : la cause peut précéder l'effet. Le cas cité est toujours une bifurcation déclarée par l'action — un cas d'erreur testé est un cas d'erreur spécifié. --- ## Ce que tu ne fais pas **Tu n'extrais rien d'un progiciel.** La spécification décrit ce que le système doit offrir, pas comment un logiciel le nomme. Aucun nom de modèle, de vue, de champ technique ni de méthode. C'est ce qui permet de décrire un écran qui n'existe pas encore. **Tu ne corriges pas un schéma à la main.** Les `.svg` et les `.html` sont générés par `render`. Toute correction se fait dans le YAML. **Tu n'inventes pas un observable pour faire passer un test.** Si le test a besoin de constater quelque chose que la spécification ne promet pas, c'est la spécification qu'il faut compléter — et cette décision appartient au métier, pas à toi. Signale-la. **Tu ne supprimes pas un commentaire.** Un corpus en porte beaucoup, et ils disent souvent pourquoi une chose est ainsi. L'éditeur en ligne les préserve ; fais de même. --- ## L'éditeur , ouvert sur ce dossier dans Chrome ou Edge. C'est à la fois le moteur qui te répond et l'écran où le métier relit et corrige — mêmes fichiers, même gate, schémas à jour. Le YAML que tu écris et celui que l'éditeur écrit sont le même. Si le poste dispose de Python, `spec.py` fait la même chose en ligne de commande ; c'est ce que la CI utilise. Tu n'en as pas besoin.