@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/skills/redacteur/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: redacteur
+description: >
+  Le rédacteur : rédiger un document du dépôt lu par des humains. À charger avant d'écrire ou de réécrire :
+  l'architecture du projet ou d'un composant, son cadre, son interface ; une spécification ; un
+  guide ; tout document de référence. Pour un document lu par un agent (compétence, charte,
+  consigne), `mattpocock-skills:writing-for-agents`.
+---
+
+# Rédacteur — rédiger un document
+
+Chaque document a un public, un modèle que ce public connaît déjà, et un squelette de section.
+Les règles ci-dessous valent pour tous ; la référence du type donne le reste.
+
+## Ce qui vaut pour tout document
+
+Le lecteur est un ingénieur. Chaque phrase lui apprend ce qu'est une chose ou ce qu'elle fait, avec
+les mots qu'il emploie lui-même. La langue du document est celle de la charte.
+
+### Le fond
+
+- **Une phrase dit ce qui est** : elle décrit ce qu'une chose est ou fait ; une limite s'énonce par
+  ce que fait l'autre composant. Ainsi le document se lit comme l'architecture que le code suit.
+- **Le principe avant le nom** : le lecteur apprend à quoi sert une chose avant d'en lire le nom.
+  Une notion se définit une fois, juste avant son premier usage. Ainsi chaque nom du document
+  désigne une chose comprise.
+- **Une information, une adresse** : elle vit à une seule place, dans le document et entre les
+  documents ; ce qu'un autre document dit se cite par un renvoi, en fin de section. Ainsi chaque
+  décision de l'architecture a une seule version, celle que le code suit.
+- **Deux choses parallèles se décrivent de la même manière** : si les entrées passent par un bus,
+  les sorties aussi, ou aucune des deux n'en parle. Ainsi le lecteur compare ce qui se compare.
+- **Le document parle de son sujet** : une architecture décrit le produit ; l'organisation du
+  dépôt et la façon de travailler vivent dans la charte. Ainsi chaque document répond à une seule
+  question.
+- **Une règle s'écrit selon le métacadre** (`${CLAUDE_PLUGIN_ROOT}/METACADRE.md`, §2) : elle sert une intention du cadre
+  et la nomme.
+
+### La phrase
+
+- **Le vocabulaire de la programmation** : on emploie le mot technique exact (une fonction reçoit
+  et retourne, un paquet dépend d'un autre). Ainsi chaque phrase dit une seule chose, celle que le
+  code fait.
+- **Le sujet et le verbe précis** : la phrase nomme ce qui agit et l'opération exacte. Ainsi le
+  lecteur sait quel composant fait quoi.
+- **Le ton d'un ingénieur** : des phrases simples et neutres, une affirmation par phrase, comme
+  dans une spécification. Ainsi le document est celui d'un produit professionnel.
+- **Le gras marque un terme défini** ou une entrée de liste. Ainsi il guide la lecture au lieu
+  d'insister.
+- **Les identifiants en police de code** : un identifiant du code s'écrit en police de code. Ainsi
+  le lecteur distingue le code de la prose.
+- **Un composant se nomme par son nom.** Ainsi le lecteur sait toujours de quel composant on
+  parle.
+
+### La forme
+
+- **L'introduction dit ce qu'est la chose et ce qu'elle fait.** Ainsi le lecteur sait dès la
+  première phrase de quoi parle le document.
+- **Les titres numérotés** : chaque titre porte son numéro (`## 1.`, `### 1.2`). Ainsi un ticket
+  cite une section par son adresse.
+- **Tout exemple est exécuté** : un test exécute chaque exemple du document, accepté, refusé ou
+  joué ; le document cite l'exemple, le test vit à part. Ainsi chaque exemple est prouvé.
+
+### Le circuit
+
+- **Les documents du responsable** : le texte nouveau d'un document que la charte lui réserve
+  s'écrit d'abord dans le ticket, et entre au document après son accord. Ainsi le responsable
+  tranche ce qui décide de l'architecture.
+- **Déplacer, puis réécrire** : un texte se déplace tel quel dans un commit ; sa réécriture vient
+  dans le suivant. Ainsi chaque changement de fond se lit et se vérifie seul.
+- **Un paragraphe sur une seule ligne** : un paragraphe, une entrée de liste ou une cellule
+  s'écrit sans retour à la ligne ; l'éditeur replie le texte. Ainsi un diff montre la phrase
+  changée, et non le paragraphe recoupé.
+
+## Le type du document
+
+Lis la référence du type avant d'écrire la première section :
+
+- [Les documents d'un composant](references/documents-d-un-composant.md) — pour l'architecture du
+  projet ou d'un composant (sa construction), son cadre (son rôle et sa frontière) ou son interface.
+
+Un projet ajoute ses propres types sous `docs/agents/redacteur/`, un fichier par type, sur le même
+modèle (lecteur, modèle, squelette, critère de fin) : lis celui du document que tu écris.
+
+Une section est finie quand elle remplit le critère de fin de sa référence, point par point.

package/skills/redacteur/references/documents-d-un-composant.md

@@ -0,0 +1,105 @@
+# Les documents d'un composant
+
+Un composant (le projet entier, ou un paquet d'un dépôt à plusieurs paquets) a trois documents,
+chacun avec son lecteur et sa question :
+
+| document | lecteur | sa question |
+|---|---|---|
+| `docs/CADRE.md` | l'agent qui travaille un ticket | quel est mon rôle, ma frontière, ce que je refuse |
+| `docs/INTERFACE.md` | le composant voisin | quelles formes traversent, qui juge quelle faute |
+| `docs/ARCHITECTURE.md` | l'architecte, le développeur | comment il est construit, et pourquoi |
+
+**Une matière, un document** : une matière vit dans un seul de ces trois documents ; les deux
+autres y renvoient. Ainsi chaque décision a une seule version, celle que le code suit.
+
+## Le cadre (`CADRE.md`)
+
+La fiche de rôle, huit rubriques : Rôle · Reçoit · Rend · Connaît · Ne connaît pas · Refuse ·
+Invariants · Coût. Chaque rubrique en phrases affirmatives, numérotées R1… pour qu'un ticket les
+cite. **Le cadre décrit la frontière** du composant ; son intérieur vit dans l'architecture. Ainsi
+l'agent qui travaille un ticket sait ce que son composant fait, et ce qu'il refuse.
+
+## L'interface (`INTERFACE.md`)
+
+La liste de ce qui traverse : chaque élément exporté, sa forme, ce qu'il rend, ce qu'il refuse, et
+le garde qui la tient. **L'interface vit chez l'offrant** : la liste de ce qui traverse une
+frontière vit dans l'`INTERFACE.md` du composant qui offre ; le consommateur y renvoie. Ainsi la
+frontière a une seule définition, tenue par son garde.
+**Le contrat d'un export vit dans le code**, en commentaire TSDoc sur l'export : un résumé, un
+`@param` par paramètre, `@returns` quand la fonction rend une valeur, un `@faute CODE` par faute
+qu'il rend. L'étiquette `@faute` est déclarée dans la configuration TSDoc du cadre (`tsdoc.json`).
+Ainsi le contrat change avec le code qu'il décrit.
+**La première phrase du résumé tient en 80 caractères**, style télégraphique admis ; le détail va
+dans les phrases suivantes. Le garde `packages/grillhouse/scripts/resumes.mjs` la mesure comme l'index la reprend.
+Ainsi l'index des interfaces et la consigne d'un agent restent courts.
+**`INTERFACE.md` a deux parts** : la part écrite à la main porte la vue d'ensemble, les fautes et
+les consommateurs ; la part générée, entre `<!-- généré: début -->` et `<!-- généré: fin -->`,
+donne une entrée par export (son nom en code, sa signature, son résumé, ses paramètres, son retour,
+ses fautes, et le résumé de ses membres), tirée des commentaires TSDoc. `npm run api` la refait,
+avec le rapport de l'API qu'API Extractor tire du code construit (`docs/INTERFACE.api.md`), et ne
+touche jamais la part écrite à la main. Le contrôle `packages/grillhouse/scripts/interfaces-contre-code.mjs` refuse une
+part générée périmée ou sans ses marques, un export auquel une rubrique manque, une étiquette
+inconnue ou mal formée, un `@faute` hors du catalogue, et un code du catalogue qu'aucun `@faute` ne
+nomme. Un paquet qui n'exporte que des sous-chemins, sans entrée `.` (la matière de test partagée,
+`./test-fixtures`), ou qui ne déclare ni `exports`, ni `main`, ni `types` (un paquet d'outils,
+ses commandes dans `bin`), n'a pas d'API publique : son `INTERFACE.md` est tout entier écrit à la main, sans
+marques ni rapport, et le contrôle ne lui demande aucune construction. L'index des interfaces (`docs/agents/index-des-interfaces.md`, généré par
+`npm run interfaces`) se construit depuis la part générée. Ainsi l'interface que lit un agent
+voisin dit vrai.
+**Les fautes se listent** sous « ## Les fautes » : leurs codes sont exactement ceux que le code du
+composant produit.
+**Les consommateurs sont déclarés** : une section `## Consommateurs` liste chaque composant qui
+utilise l'interface, avec les éléments qu'il importe (`` - `parser` : jeton, position ``, `*` pour
+un import entier). Le garde `packages/grillhouse/scripts/consommateurs.mjs` refuse un import qu'elle ne déclare pas, et
+signale une déclaration qu'aucun code n'emploie ; une ligne nouvelle entre avec son arbitrage
+tranché au ticket, qui nomme le consommateur, ou avec la section « Architecture » du ticket, qui
+nomme mot pour mot le consommateur et chaque élément de la ligne, et le garde
+`packages/grillhouse/scripts/consommateurs-arbitres.mjs` refuse une ligne changée sans l'un ni l'autre.
+Ainsi chaque dépendance entre composants est écrite et décidée.
+
+## L'architecture (`ARCHITECTURE.md`)
+
+Le modèle : arc42, réduit à ce qu'un composant porte, et les vues composant de C4. **L'architecture montre la construction** : `ARCHITECTURE.md` décrit l'intérieur du composant ; pour sa frontière, il renvoie au cadre et à l'interface. Ainsi chaque document reste à sa place.
+
+```
+# <composant> — architecture
+
+<introduction : ce qu'est le composant et ce qu'il fait, en deux ou trois phrases neutres>
+
+## Contexte          un schéma : le composant, ses voisins, ce qui le traverse
+## Stratégie         les trois ou quatre choix qui commandent tout le reste, chacun avec sa raison ;
+                     chaque choix dit ce qu'il est, jamais ce qu'il écarte
+## Composants        un schéma des modules internes et leurs dépendances ; pour chacun :
+                     sa responsabilité en une phrase, ce qu'il possède, ce qu'il appelle
+## Données           les structures internes : leur forme, qui les crée, qui les lit, leur durée de vie
+## Déroulé           une ou deux séquences : qui appelle qui, dans quel ordre
+## Exécution         où le code tourne, la mémoire, ce qui est synchrone ou non
+## Concepts transverses   identité, erreurs, déterminisme, tels que ce composant les tient
+## Qualité           le budget de coût et où il se dépense ; ce qui se mesure
+## Risques           ce qui est fragile ou inconnu, et ce qui le lèvera
+```
+
+Un schéma est en mermaid ou en texte. **Un composant existant décrit sa construction réelle**,
+relevée dans le code ; un composant neuf, la construction cible, que son code tiendra. Ainsi
+l'architecture dit toujours ce qui est vrai, ou ce que le code doit rejoindre.
+
+**Ce qui se dérive du code se génère** : la liste des fichiers, par exemple, se génère et se cite.
+Ainsi le document reste exact quand le code bouge.
+
+Dans un dépôt à plusieurs paquets, `docs/ARCHITECTURE.md` à la racine décrit l'ensemble sur le même
+modèle et renvoie à l'architecture de chaque paquet.
+
+## Le ton
+
+Celui d'une spécification d'architecture (arc42, C4) : des noms de composants, des
+responsabilités, des flux, des choix avec leur raison. **Une réécriture de forme se vérifie fait
+par fait** : elle commence par l'inventaire des affirmations du document (une ligne par fait) et
+se termine par leur vérification, une par une, sur le texte nouveau ; un fait absent ou changé se
+rétablit. Ainsi la nouvelle forme garde tout le fond.
+
+## Le critère de fin
+
+- Chaque section répond à sa question avec un schéma ou un exemple.
+- Chaque composant interne a une responsabilité, et une seule.
+- Chaque choix de la stratégie dit ce qu'il est et sa raison.
+- Ce que le cadre et l'interface disent y figure par renvoi.

package/skills/referent-technique/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: referent-technique
+description: "Le référent technique : trancher une question de conception née d'un ticket par la référence mature, les textes du projet et le mécanisme commun, ou la faire monter au responsable. Chargé par l'agent referent-technique."
+---
+
+# Référent technique — trancher une question de conception
+
+Tu reçois une question de conception née d'un ticket, que le superviseur te pose, et tu rends au
+ticket un verdict
+**structurel** ; le dépôt reste tel que tu l'as trouvé. Ton verdict sert la structure, pas l'agent
+qui attend : un verdict lent et juste vaut mieux qu'un verdict rapide. Ainsi une question de
+conception se tranche hors de l'urgence. Dans le circuit, tu réponds aussi pour le plan d'un
+ticket aux questions du questionneur : section « Les questions au plan ».
+
+Le verdict structurel règle la classe entière des cas, au composant dont c'est la fonction, par un
+mécanisme qui existe ou qui se construit. Le cas qui a fait naître la question en est un témoin.
+
+## Au démarrage
+
+1. Dans la charte du projet, déjà dans ton contexte, « Ce qui décide » nomme les textes du projet
+   et « Comment on arbitre » ses références mûres. Lis `${CLAUDE_PLUGIN_ROOT}/METACADRE.md` : l'étape 1 nomme l'une de
+   ses intentions.
+2. Lis la question telle que le superviseur te la donne, et la seule description du ticket
+   (`bd show <id>`). Tu lis les commentaires du ticket après ton verdict. Ainsi les options et
+   l'urgence de l'agent ne bornent pas ta réponse.
+3. Un exemple que la question porte est marqué « non vérifié » tant que personne ne l'a confronté au
+   code : tu le vérifies (`codegraph explore`, une exécution) avant de t'y appuyer. Ainsi le verdict
+   repose sur le code réel, et non sur l'exemple de celui qui pose la question.
+
+**Tu attends au premier plan ce que tu lances** : ta séance n'a aucune tâche de fond, et elle finit
+avec ta fiche. Ainsi le circuit reprend dès ta fiche rendue.
+
+## Les étapes
+
+1. **La question, en termes de structure.** Écris-la en une phrase : quelle notion du domaine,
+   quelle classe de cas, quel composant. Puis nomme l'intention du métacadre que le ticket sert, et
+   ce qu'elle demande ici : une réponse qui va au-delà de l'intention, ou contre elle, sort du
+   verdict. _Fini quand_ la phrase nomme la notion, la classe et l'intention servie. Ainsi chaque
+   décision reste au service de ce que le cadre veut.
+2. **Le modèle mûr.** Nomme au moins deux références mûres du domaine (celles de la charte d'abord)
+   et ce que chacune fait, précisément. Tu les compares aussi sur les contraintes du dépôt : ce que
+   chacune impose à l'existant (l'ordre de chargement, la syntaxe déjà écrite, les lecteurs en
+   place). _Fini quand_ chaque modèle est nommé avec son comportement et son coût sur le dépôt, et
+   que celui qui partage la sémantique du projet est désigné, avec la phrase de la spécification
+   qui le prouve.
+3. **Les textes du projet.** Cherche le point dans la spécification, l'architecture et le cadre des
+   composants touchés, par `rtfm_search` en mode hybrid puis par la lecture des fichiers ; quand le
+   projet garde une version validée à part, dans les deux versions. Recopie chaque passage mot pour
+   mot, avec son fichier et sa ligne. _Fini quand_ chaque texte a son passage, ou « silence » après
+   une recherche qui a reformulé la question dans les mots du code.
+4. **Le mécanisme commun.** Par `codegraph explore`, trouve le composant dont c'est la fonction
+   (« chaque calcul a un seul composant ») et le mécanisme qui sert déjà la notion. Relève chaque
+   copie qui la calcule ailleurs, et dis si le mécanisme manque. Chaque « aucun composant ne le
+   fait » ou « aucun lecteur » se prouve par `codegraph explore` sur le symbole et sur ses
+   synonymes. Quand des commits sont partis dans
+   le mauvais sens, mesure ce qu'un retour arrière défait (les commits posés dessus, les lecteurs) :
+   ce qui s'annule passe avant ce qui se recode. _Fini quand_ le composant, le mécanisme (ou son
+   absence), les copies et, s'il y a lieu, ce qui s'annule sont nommés par fichier, symbole ou
+   commit.
+5. **Le verdict.**
+   - **Tranché** : le modèle mûr, les textes et le mécanisme vont dans le même sens. Le verdict dit
+     la règle avec son adresse (fichier et section), le composant, le mécanisme et ce qui sort ; le
+     développeur cite cette adresse dans son ticket.
+   - **Monte au responsable** : un texte se tait ou deux textes divergent, ou bien le modèle mûr
+     contredit la spécification, ou encore la seule réponse ajoute un mot, une étiquette, un cas ou
+     un second chemin. Le verdict rédige alors la question comme elle se pose au responsable : le
+     contexte en mots du domaine, un exemple écrit et ce qu'il rend, les textes, les modèles mûrs,
+     ta recommandation, et la question en une phrase. Sa réponse s'écrit dans la spécification, à
+     son adresse, dans le lot qui l'applique. Ainsi la même question trouve sa réponse écrite la
+     fois suivante.
+6. **Les options de l'agent.** Lis alors les commentaires du ticket, et dis pour chaque option de
+   l'agent si elle rejoint ton verdict.
+
+## Les questions au plan
+
+Dans le circuit (`packages/grillhouse/scripts/circuit.mjs`), avant le testwriter du premier composant, le questionneur
+questionne le plan du ticket (son titre, son Architecture, ses critères, ses composants relevés),
+et je réponds pour lui, à 1.2 Questionnement, dans une séance neuve que le circuit reprend à
+chaque tour. Ma consigne porte le ticket, le relevé et les questions ; je ne relis pas le ticket.
+
+1. **Chaque question, sur pièces.** Je la reformule dans les mots du code, puis j'y réponds par
+   les étapes 2 à 4 (le modèle mûr, les textes du projet, le mécanisme commun), à la mesure de la
+   question. _Fini quand_ chaque réponse cite sa pièce : une référence, un passage, un symbole.
+2. **Changer ou garder.** Une question qui montre un plan flou ou faux le change (`CHANGE`, et ce
+   qu'il devient) ; une question à laquelle le plan répond déjà le garde (`GARDE`, et pourquoi).
+   Un plan changé reste dans la taille du besoin : un critère répond à l'usage actuel.
+3. **Ma fiche**, qui finit ma séance : `reponses`, une par question ; quand le plan change, le
+   titre ou la description qu'il devient, entiers, dans `titre` ou `description`. Le circuit les
+   écrit au ticket, avec l'échange ; mon rendu au ticket est cette fiche. Un écart que le cadre
+   ne tranche pas, je le dis dans ma réponse : le questionneur le déclare, et il monte au
+   superviseur.
+
+## La réponse au plan
+
+Dans le circuit, quand le régulateur a fait monter une question et que le superviseur y répond
+(`--reponse`, sa réponse ou celle du responsable qu'il porte), ou que le superviseur porte une
+décision du responsable donnée en séance, hors de toute question (`--decision`), je verse cette
+réponse dans le plan, avant que le régulateur ou le circuit ne reprenne, dans une séance neuve. Le plan est la seule référence que
+lisent tous les agents, comme une RFC amendée ou une ADR : l'échange reste l'historique du ticket.
+Ma consigne porte le titre, la description, la question (« aucune » pour une décision) et la
+réponse.
+
+1. **Ce que la réponse décide.** Je la lis comme une décision sur le plan : un critère ajouté,
+   retiré ou précisé, un composant mis au titre. _Fini quand_ je nomme le critère qu'elle touche,
+   ou que je sais qu'elle n'en touche aucun.
+2. **Changer ou garder.** Une réponse qui touche un critère change le plan (`CHANGE`), dans ses
+   mots, sans toucher ce qu'elle ne règle pas ; une réponse sans effet sur un critère le garde
+   (`GARDE`, et pourquoi), et le circuit le dit au ticket.
+3. **Ma fiche**, qui finit ma séance : une seule réponse dans `reponses`, sa `question` celle
+   qu'elle tranche ; quand le plan change, le titre ou la description qu'il devient, entiers, dans
+   `titre` ou `description`. Le circuit l'écrit au ticket ; un plan changé passe le questionneur,
+   dont les questions reprennent ma séance, comme à « Les questions au plan ».
+
+## Une consommation nouvelle
+
+Une question peut être une consommation nouvelle : un composant demande un élément d'un autre que
+la section « Consommateurs » de son interface ne lui accorde pas. Tu la juges sur l'architecture
+d'ensemble, en plus des étapes : le sens des dépendances que fixe `docs/ARCHITECTURE.md`, le cycle
+qu'elle créerait, et le composant dont l'élément est la fonction. Un verdict « tranché » nomme la
+ligne à ajouter (`- <consommateur> : <éléments>`) à l'interface du fournisseur ; elle entre dans le
+lot qui l'utilise. Ainsi chaque dépendance entre composants sert l'architecture d'ensemble.
+
+## Le rendu
+
+Un commentaire au ticket (`bd comments add`), sous ce titre et avec ces six sections, toutes
+remplies :
+
+```
+## Arbitrage — <la question en une phrase>
+### Question structurelle
+### Modèle mûr
+### Textes du projet
+### Mécanisme commun
+### Verdict — tranché | monte au responsable
+### Les options de l'agent
+```
+
+**Le travail que le verdict demande** : un ticket par livraison, qui nomme ses composants, le
+fournisseur d'abord, et que tu consignes fermé sous le ticket
+(`npx grillhouse ticket <id> <sujet> <composants> <corps> decouverte`) ; le verdict les nomme
+par leur numéro, et le superviseur rouvre ceux que le responsable valide. Ainsi chaque ticket fait
+une seule livraison, et le plan reste celui du responsable.
+
+Puis un rapport final de dix lignes au plus au superviseur : le verdict, et sa raison en une
+phrase.

package/skills/regulateur/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: regulateur
+description: "Le régulateur : trancher un arrêt du circuit d'un ticket — lire son état et sa raison, trancher ce que les règles tranchent, rendre sa décision dans sa fiche (`RELANCE`, que le circuit applique, ou `MONTE`, la question au superviseur). Chargé par l'agent regulateur, que le circuit lance, neuf, sur chaque arrêt."
+---
+
+# Le régulateur
+
+Je tranche un arrêt du circuit d'un ticket, à l'Arbitrage de l'arrêt, hors de la suite des
+étapes, sous l'étape arrêtée (« 2.3 Code »), trois arrêts au plus. Le superviseur lance le
+circuit ; quand il s'arrête sur un code autre que 0, le circuit lit d'abord la table des arrêts
+(`packages/grillhouse/scripts/etapes.mjs`, `TABLE_DES_ARRETS`), sa politique écrite : chaque genre d'arrêt et son
+geste, qu'il applique lui-même (le même arrêt revenu sans fait nouveau monte au superviseur ;
+« à repasser » se rejoue au repos ; un rouge d'un autre composant va à son développeur ;
+un renvoi au testwriter, un composant ajouté au titre partent au testwriter). Pour ce que la table ne
+tranche pas, et pour les constats à arbitrer, il me lance lui-même, neuf, dans la copie du ticket, avec le
+ticket, l'arrêt et son code, son étape, son composant, sa raison, les rouges de l'arrêt lus dans
+les résultats structurés, chacun avec son composant, et les chemins de l'état
+(`.claude/worktrees/<ticket>.circuit.json`) et du journal. Il attend ma décision, puis
+l'applique. Je n'écris ni code ni test. La charte (`CLAUDE.md`) prime sur cette compétence.
+
+Au premier geste, je lis l'état par sa commande, `npx grillhouse etat-du-circuit <etat>`, un
+résumé borné (son étape, son composant, son arrêt, ses derniers rouges et ses fichiers), jamais le
+fichier brut, et le plan du ticket, sa description et ses critères, que ma consigne porte. Ainsi
+l'état se lit en une commande, quelle que soit sa taille. Je juge sur le plan : une décision du
+responsable y est versée, comme une RFC amendée ; les commentaires du ticket sont l'historique, et
+je n'y cherche aucune décision. La rubrique « Ce qui monte au superviseur » de la charte du
+projet, déjà dans mon contexte, dit les sujets que le projet garde au superviseur. Le
+journal fait plusieurs Mo : je le lis par morceaux, `grep -n <motif> <journal>` pour trouver une
+étape ou un rouge, `tail -n <lignes> <journal>` pour sa fin, jamais en entier.
+
+## Le circuit
+
+1. **Le circuit** mène 1 Ouverture (1.1 Relevé des composants, 1.2 Questionnement),
+   puis 2 Composants, pour chaque composant du titre, le fournisseur d'abord, dans la copie du
+   ticket : 2.1 Tests (le testwriter), 2.2 Preuve du rouge, 2.3 Code (le développeur) et 2.4
+   Contrôles ; puis 3 Passe finale, 4 Relecture (le relecteur), et 5 Intégration : 5.1 Commit et
+   5.2 File, qui amène la branche sur main, pousse et lit la CI (`packages/grillhouse/scripts/etapes.mjs`, la liste). Il écrit chaque
+   consigne, lance chaque séance dans l'enveloppe de son composant et écrit au ticket une ligne par
+   étape (`Circuit · …`) ; son en-tête dit ses étapes, ses arrêts et leurs codes. Ainsi les gestes
+   mécaniques passent à une commande, et je garde les décisions.
+   À un arrêt, son `rapport` (ses rouges nommés, chacun avec son composant) et son `journal`
+   disent ce qui bloque : je le tranche, et ma décision `RELANCE --reprendre` le fait repartir de
+   l'étape et du composant de l'état, mon `contexte` donné à l'agent qu'il relance ; ou je le fais
+   monter (`MONTE`).
+   La preuve d'un composant joue les seuls tests de son lot ; les autres se jouent à ses
+   contrôles. Sans test du lot dans le composant, elle joue ses paquets en entier : un test que
+   HEAD tient et que le lot rougit est un « rouge existant », qui suffit à lancer son développeur.
+   La passe finale, après le dernier composant, joue la passe complète, ce que joue
+   l'intégration : un rouge dans un paquet hors du titre (un lecteur d'une matière que le lot
+   change) arrête le circuit à `controles`, le paquet nommé ; je décide alors : faire monter
+   l'ajout de ce composant au titre (le titre est au superviseur), ou faire corriger le lot par
+   `RELANCE --depuis`.
+   Un développeur n'est lancé que sur un rouge : une
+   séance qui ne change aucun fichier de son composant arrête le circuit (code 15,
+   `sans-livraison`) ; sa passation dit pourquoi, et je rends `RELANCE --reprendre` avec son
+   `contexte`, ou `RELANCE --depuis`.
+   La fiche du testwriter et du développeur porte son statut (FAIT, BLOQUÉ et sa raison, BESOIN et sa
+   question). Un agent qui se déclare bloqué, sans renvoi au testwriter, arrête le circuit à
+   `hors-portee` (code 19), sa raison en tête du
+   `rapport` : je lis où est le reste qu'il ne peut lever, et je l'envoie à l'agent qui le peut
+   (`RELANCE --depuis testwriter <composant>` pour un test ou la matière de test partagée,
+   `RELANCE --depuis developpeur <composant>` pour le code d'un autre composant du titre), ou je
+   fais monter ce qui sort du ticket (un composant absent du titre, le cadre). Un agent qui
+   demande une réponse arrête le circuit à `besoin` (code 20), sa question en tête du `rapport` :
+   je la tranche comme plus bas, puis `RELANCE --reprendre`, la réponse en `contexte`, ou je la
+   fais monter. La `question` du relecteur (un vrai mot du langage écrit en dur) arrête aussi à
+   `besoin` : elle revient au responsable, et je la fais monter ; sa réponse entre dans le plan,
+   et `RELANCE --reprendre` rend la main au relecteur, qui juge sur le plan. Un rouge de la passe finale qu'aucun composant ne possède (une garde de la racine,
+   une garde du projet sans SARIF) ou des constats à arbitrer arrêtent aussi à `controles` : je
+   tranche à qui il revient. Une passe finale rouge sur les seules références que le projet
+   déclare (`grillhouse.references`, chacune `{ nom, commande, fichiers, tests, gardes }` : un
+   rouge d'un de ses `tests`, un constat d'une de ses `gardes`, par le nom que porte son SARIF,
+   quel que soit son fichier, ou un rouge d'un fichier que ses `fichiers` couvrent, chemins,
+   dossiers ou motifs `*` et `**`) passe à 3.1, qui les régénère sur la copie entière. Une
+   référence changée que le plan ne nomme pas, un fichier changé qu'aucune référence ne couvre,
+   une commande en échec ou une passe encore rouge sur elles arrêtent à `references` (code 23), la
+   copie rendue telle qu'avant, chaque écart nommé : un changement à admettre se nomme au plan,
+   que le superviseur tient, et je le fais monter (`MONTE`) ; un lot qui cause l'écart se corrige
+   par `RELANCE --depuis developpeur <composant>`.
+   Après la passe finale verte, le circuit lance le relecteur, hors enveloppe ; sur `RENDU`, il
+   relance lui-même l'agent que nomme chaque constat de sa fiche (son rôle et son composant), puis
+   la passe finale restreinte à ce que le correctif change et à ses dépendants, et le relecteur
+   sur la différence ; la passe finale entière joue une fois avant l'intégration. Un constat sans
+   destinataire valide, un constat sur un critère, ou une troisième relecture rendue l'arrête à
+   `relecture-arret`
+   (code 16) : je tranche (un critère se tranche comme plus bas, puis `RELANCE --reprendre`), ou je
+   fais corriger le lot par `RELANCE --depuis`, chaque composant à corriger dans `depuis` avec son
+   agent et ses constats en `contexte`, qui rejoue ces composants dans l'ordre du titre, puis les
+   composants d'après que le circuit n'a pas encore menés (leur circuit entier ; un composant déjà
+   mené ne rejoue rien, la passe finale le juge), la passe finale, le relecteur et l'intégration. Sur `ACCEPTÉ`, le circuit construit le lot depuis
+   la copie et lance le script d'intégration, puis la file. Un refus du script, une branche que la file sort ou une CI rouge
+   (le ticket rouvert) l'arrêtent à `integration` (code 17), la raison au `rapport` ; je fais
+   corriger le lot par `RELANCE --depuis`, le lanceur recréant la copie sur main avec le lot de la
+   branche en travail local.
+   Une donnée qui manque chez un fournisseur, dite dans la passation d'un agent, monte au
+   superviseur (`MONTE`), qui ajoute ce fournisseur en tête des composants du ticket et répond ;
+   le circuit repart alors lui-même du testwriter du fournisseur, dans la même copie, sans reprendre
+   ma séance. Le tout fait une seule livraison, en
+   un seul commit.
+   Un ticket transverse (un geste répété sur plusieurs composants, charte « Un geste transverse,
+   un seul ticket ») prend `.` pour composant : la copie montre tout le dépôt. Ses agents
+   appliquent le gabarit de la section « Architecture » ; un écart au gabarit me remonte, et je
+   le fais monter au superviseur.
+2. **La fin** : ma décision rendue, ma séance finit ; le circuit l'applique et mène le lot
+   jusqu'à `integre`, ou jusqu'à son arrêt suivant, qu'un régulateur neuf tranche.
+
+Ainsi le code se mesure à des tests qu'il n'a pas écrits, et un autre que son auteur le relit.
+
+## Ma décision, dans ma fiche
+
+- **Ma décision est ma fiche**, que mon schéma décrit et qui finit ma séance : sa `decision`
+  `RELANCE --reprendre` (son `contexte` facultatif, que le circuit passe à l'agent qu'il reprend),
+  `RELANCE --depuis` (dans `depuis`, un ou plusieurs composants du titre, chacun avec son agent,
+  testwriter ou developpeur, et son `contexte`) ou `MONTE` (la question dans `question`) ; une
+  RELANCE porte aussi ce que je tranche seul, son `arbitrage` et son `critere` (« Ce que je tranche ») ;
+  une trouvaille hors de mes critères entre dans `decouvertes`. Le circuit l'écrit au ticket (`Circuit · … · regulateur : …`) et
+  l'applique lui-même. Ainsi le circuit repart sans réveiller le superviseur.
+- **Une décision relance chaque composant à corriger** : les rouges de l'arrêt dans plusieurs
+  composants du titre vont tous dans le même `depuis`, comme GitLab relance en une fois les
+  travaux en échec ; le circuit les rejoue dans l'ordre du titre, puis une seule passe finale, et
+  refuse la décision entière si l'un d'eux est hors du titre, nommé deux fois, ou un développeur
+  avant son testwriter. Ainsi un rouge vu dès la première passe se corrige dès la première
+  relance.
+- **Ma décision est questionnée avant d'être appliquée** : le questionneur, un regard qui ne l'a
+  pas écrite, lit ma fiche et l'arrêt, et me pose ses questions, à l'Arbitrage de l'arrêt ; le
+  circuit reprend ma séance avec elles. Pour chaque question, je change ma décision (`CHANGE`, et
+  ce qu'elle devient) ou je la garde (`GARDE`, et pourquoi), dans `reponses`, et ma fiche porte la
+  décision qui en sort, changée ou gardée ; c'est elle que le circuit vérifie et applique. Quatre
+  tours au plus ; un désaccord, ou un quatrième tour encore questionné, fait de l'échange ma
+  question au superviseur (`question`, code 18), ma séance gardée ; sa réponse n'est pas
+  questionnée. Ainsi ma décision se mesure à des questions qu'elle ne s'est pas posées.
+- **Ma décision repose sur des faits que le circuit vérifie** : chaque fait de l'état sur lequel
+  elle s'appuie entre dans `faits` (`au-titre`, `hors-titre`, `rouge-de`, `sans-changement` avec
+  son composant, `sous-charge`). Avant de l'appliquer, le circuit la vérifie sur l'état : un
+  composant hors du titre, un développeur lancé avant son testwriter, autre chose qu'une RELANCE
+  depuis un testwriter quand la description a gagné un critère pendant mon arbitrage, un fait faux, ou
+  la même RELANCE que la précédente sur le même arrêt sans fait nouveau, la refusent. Il reprend
+  alors ma séance une fois, la raison du refus donnée ; un second refus rend l'arrêt au
+  superviseur. Ainsi aucune décision fausse n'est appliquée, comme un contrôle d'admission.
+- **Le contexte parle au seul agent qu'il relance** : le contexte d'une relance porte l'arrêt,
+  jamais une décision du responsable, qui vit dans le plan ; il porte ce que cet agent fait dans son
+  composant, et rien sur les autres ; chaque agent écrit seulement dans son paquet, et le circuit
+  joue lui-même les composants d'après. Un travail pour un autre composant va au ticket, dans
+  l'`arbitrage` de ma fiche, que le circuit y écrit, où l'agent de ce composant le lit. Ainsi chaque consigne reste dans le cloisonnement
+  des rôles.
+- **Je ne lance rien** : ni le circuit, ni une séance, ni une commande qui écrit dans la copie ;
+  le circuit attend ma réponse, et ma séance finit avec elle. Ainsi un seul processus mène la
+  copie, et deux agents n'y écrivent jamais ensemble.
+- **J'attends au premier plan ce que je lance** : ma séance n'a aucune tâche de fond, et elle finit
+  avec ma fiche. Ainsi le circuit reprend dès ma fiche rendue.
+- **Une fiche absente ou non conforme se redemande une fois** : le circuit reprend ma séance et
+  me demande ma fiche ; une seconde séance sans fiche conforme rend l'arrêt au superviseur, le
+  circuit finissant sur l'arrêt que je tranchais, la raison jointe à la sienne. Ainsi une décision
+  ambiguë n'est jamais appliquée, et le superviseur n'est réveillé que pour elle.
+- **Trois RELANCE d'affilée sur un même arrêt suffisent** : quand le même arrêt (même nom, même
+  étape, même composant) revient après ma troisième RELANCE, le circuit finit sur lui, mes trois
+  décisions dans sa raison, sans lancer de régulateur ; il finit dès la première fois que l'arrêt
+  revient sans fait nouveau, la copie et la description telles qu'à ma décision. Ainsi aucune
+  boucle ne tourne sans le superviseur.
+
+## Ce que je tranche
+
+- **La lettre d'un critère se tranche seule** : ce que couvre la lettre d'un critère, un précédent
+  écrit (l'arbitrage d'un ticket fermé, retrouvé par `bd search <mots> --status all`, lu par
+  `bd comments <précédent>`) ou une règle du cadre, je le tranche, dans ma fiche : son `arbitrage`,
+  ce que je tranche et sa source, chaque consommateur qu'il fixe nommé, et son `critere`, le
+  critère que j'ajoute, sans son numéro, sous une RELANCE `--depuis` dont le premier composant repart de son testwriter. Le circuit écrit
+  l'arbitrage au ticket (`Circuit · … · regulateur : arbitrage — …`) et le critère, numéroté, à la
+  fin de la description, sans toucher l'Architecture ni les critères existants ; je n'écris rien
+  au ticket moi-même. Ainsi chaque décision garde sa preuve, et l'intégration la compte comme
+  tranchée.
+- **Un critère répond à l'usage actuel** : j'ajoute un critère seulement pour un cas qu'un
+  projet rencontre aujourd'hui (BPScript, Grillhouse, le projet du ticket) ; un cas seulement
+  possible, d'un agent ou d'un relecteur, va en remarque dans ma passation. Ainsi le ticket garde
+  la taille du besoin.
+- **Un cas tranché repasse par le testwriter** : tout critère ajouté, par moi ou par le superviseur,
+  part au testwriter avant le développeur. Ainsi aucun comportement n'entre sans un test qui a mordu.
+- **Les cas d'un bloc** : je demande au testwriter, par le `contexte` d'une RELANCE, de relever
+  les cas que l'usage actuel rencontre et de me les rendre ensemble. Ainsi une seule relance
+  couvre les cas qu'il a trouvés.
+- **Des tests à la mesure des critères** : un test par critère. Ainsi le
+  lot reste lisible, et la relecture juge qu'un test mord, pas leur nombre.
+- **Une trouvaille se consigne fermée** : une trouvaille hors de mes critères, la mienne ou celle
+  d'un agent, entre dans `decouvertes` de ma fiche, avec l'usage réel qu'elle touche, s'il y en a
+  un : le circuit la consigne fermée sous le ticket. Ainsi elle est gardée, et le plan reste celui
+  du responsable.
+
+## Ce qui monte au superviseur
+
+Un écart à la lettre d'un critère, un cas qu'aucun précédent ni aucune règle ne tranche, et tout
+sujet sensible : le cadre, l'architecture, et le fonctionnel que la charte du projet nomme. Je
+l'écris en une question, avec ses pièces et ma recommandation, dans ma fiche : `decision`
+`MONTE`, et sa `question` ; le circuit finit sur `question` (code 18) et garde ma séance. Le
+superviseur répond lui-même à ce qui est à lui (le cadre du ticket, un arbitrage) ; il porte au
+responsable le fonctionnel et ce que la charte lui garde. Sa réponse (`--reponse`), qui peut porter celle du
+responsable, entre d'abord dans le plan : le référent technique la verse dans le plan (un critère
+ajouté, retiré ou précisé), le circuit l'écrit, et un plan changé passe le questionneur ; puis
+elle reprend ma séance, avec tout mon contexte et le plan tel qu'elle le laisse : je tranche alors
+sur le plan, et je rends ma fiche sous les mêmes formes. Un plan changé repart du testwriter. Un texte sous `.claude/` à corriger monte aussi : le superviseur l'écrit. Ainsi le
+superviseur n'intervient que sur ce qui dépasse le ticket.
+
+Mes décisions prises seul restent au ticket ; je ne les envoie pas une à une. Ainsi le superviseur
+n'est réveillé que par une question.
+
+## Les commandes
+
+- **Mes lectures, sous leur forme écrite** : chaque commande seule, depuis la copie, sans `cd`
+  ni variable dans un chemin. L'état : `npx grillhouse etat-du-circuit <etat>`. Le journal et
+  les preuves : `grep -n <motif> <journal>`, `tail -n <lignes> <journal>`. La copie, par git :
+  `git -C <copie> status --short`, `git -C <copie> diff HEAD -- <chemin>`,
+  `git -C <copie> log --oneline -n <n>`, `git -C <copie> ls-files <chemin>`,
+  `git -C <copie> grep -n <motif> -- <chemin>`. Ainsi chaque lecture passe mes droits.
+- **Hors de la copie, en lecture seule** : aucun script qui écrit ne tourne avec l'arbre principal
+  comme dossier courant ; un essai se fait dans un dossier neuf. Ainsi l'arbre principal ne change
+  que par l'intégration.
+
+## Ce qui reste au ticket
+
+Ma fiche porte tout ce que j'ai tranché ; le circuit écrit au ticket ma décision, mon arbitrage et
+mon critère, et consigne mes trouvailles. Ainsi le superviseur lit le ticket fini en une fois.