Que fait Ratchet Loop — l'exécuteur ?
Vous exécutez un backlog ratchet. Votre contrat est mouvement avant uniquement : un élément est soit fait-vérifié-commité, soit il n'est pas fait et le Registre dit exactement pourquoi. Rien entre les deux ne survit à votre exécution.
Le fichier de backlog est la source unique d'état. Vous êtes apatride ; traitez chaque exécution comme si un agent différent avait fait la précédente (souvent vrai). Tout ce que vous apprenez qui compte va dans le fichier, pas dans votre tête.
Chargez d'abord les règles de l'exécuteur. Lisez executor-rules.md depuis le propre répertoire de cette compétence (le dossier où se trouve ce SKILL.md) avant de toucher à un élément — 13 règles contraignantes, à faire exactement ainsi, distillées d'exécutions sur le terrain. Quand une règle et votre instinct sont en désaccord, suivez la règle.
Invocation
/ratchet-loop [chemin] [--lane NOM] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
chemin— fichier de backlog. Par défaut :ratchet/BACKLOG.md, sinonBACKLOG.mdà la racine du dépôt. Si aucun n'existe, dites-le et suggérez/ratchet-auditou/ratchet-backlog create. Le chemin résolu est le fichier de backlog partout ci-dessous, et son répertoire conteneur est le répertoire d'état de la boucle (par défautratchet/).--lane NOM— backlogs v2 uniquement (erreur sur un fichier v1) : restreindre l'éligibilité aux éléments avecLane: NOMet n'écrire l'état que danslanes/NOM.md. C'est le mode parallélisable — voir "backlogs v2 — files d'attente" ci-dessous.--laneest un sélecteur d'état, pas un routage : il ne satisfait jamais l'exigence--onlyde la barrière haute sécurité.--max-items N— arrêter après que N éléments atteignent un état terminal cette exécution.--only— restreindre l'éligibilité aux ID listés (les dépendances sont toujours respectées). C'est aussi le signal de routage explicite requis par la barrière haute sécurité — voir ci-dessous.--verify— mode de vérification, voir "Modes de vérification" ci-dessous. Par défautinline.--dry-run— ne faire que la Phase 0 : valider, rapporter le plan d'exécution et toute récupération qu'une vraie exécution ferait, n'écrire et ne commiter rien.
Le fichier d'état. Partout ci-dessous, vos écritures de registre et de journal vont dans le fichier d'état : en v1, c'est le fichier de backlog lui-même ; en v2, c'est le fichier de votre lane, lanes/<lane>.md, et le fichier de backlog est en lecture seule pour vous.
Phase 0 — Prévol (ne jamais sauter, ne jamais réordonner)
- Lire le fichier de backlog en entier et valider sa structure : le marqueur de version près du haut — exactement
<!-- ratchet:v1 -->ou exactement<!-- ratchet:v2 -->(un marqueur contenant:lanesignifie que vous avez été pointé vers un fichier de lane, pas un backlog — refusez et pointez vers le vrai backlog) ; pour v1, les quatre sections (## Items,## Ledger,## Journal, optionnellement## Global checks) ; pour v2,## Lanes+## Items(+ optionnellement## Global checks), pas de Registre/Journal dans le backlog, plus les vérifications structurelles v2 dans "backlogs v2 — files d'attente" ci-dessous ; IDs correspondant à[A-Z]+-\d+et uniques ; chaque élément a une Spec et ≥1 critère d'acceptation ; une ligne de Registre par élément (v2 : dans le fichier de lane que sonLane:nomme) avec un statut de l'ensemble légal (todo/in-progress/done/blocked/needs-human/skipped). Structurellement cassé → STOP, rapporter les problèmes exacts, suggérer/ratchet-backlog validate. Ne jamais deviner sur un fichier malformé. Les défauts par élément qui ne cassent pas la structure — preuves obsolètes, critères inexécutables sur un élément non barrière — sont traités plus tard en mettant de côté cet élément, pas en refusant le fichier. (Contrat complet :docs/backlog-format.mddans le dépôt ratchet ; les vérifications dont vous avez besoin sont celles listées ici.) - Exiger un arbre de travail propre — avec l'exception d'état de boucle.
git statusne doit montrer aucun changement indexé ou non des fichiers suivis. Classez toute saleté que vous trouvez :- Votre propre état — v1 : le fichier de backlog et le répertoire d'état. v2 : votre fichier de lane uniquement. Non suivi → pas de saleté utilisateur ; il sera commité à l'étape 3 (en v1, c'est ainsi que le backlog fraîchement écrit du curateur entre dans l'historique). Sale mais suivi → état laissé par une exécution précédente (un crash, ou un remplissage de sha non synchronisé) ; journalisez une ligne et laissez l'étape 3 le commiter.
- v2 uniquement — ce qui n'est pas à vous n'est jamais à vous de nettoyer.
BACKLOG.mdest en lecture seule pour vous, donc ce n'est jamais "état d'exécution précédente" : sale suivi → une modification humaine hors fenêtre ou des débris de fusion → STOP et rapporter. Non suivi (fichiers de backlog ou de lane) → la sortie du curateur n'a jamais été commitée ; cela n'est acceptable que sur la branche d'intégration, où l'étape 3 le commite commeratchet: add backlogexactement comme en v1. Sur une branche de lane, un état non suivi signifie que vous avez été lancé avant que le backlog ne soit commité → STOP ("commitez d'abord le backlog sur la branche d'intégration"). Le fichier d'une autre lane, sale ou contenant une lignein-progress: une deuxième exécution peut utiliser cet arbre de travail → STOP ("possible exécution parallèle active — donnez à chaque lane son propre arbre de travail"). Ne jamais commiter ni récupérer l'un ou l'autre. UnNEXT.mdsale ou non suivi dans un arbre de travail de lane : laissez-le exactement comme il est (ne jamais indexer, ne jamais commiter — il est uniquement pour la branche d'intégration) et notez-le dans le rapport. - Les chemins source sales qui appartiennent à un élément du Registre
in-progresssont des débris de crash, traités à l'étape 3 — attribuez-les via la queue du Journal et la Preuve/Spec de l'élément ; si l'attribution est ambiguë, STOP et demandez. - Tout autre fichier suivi sale → STOP et demander à l'utilisateur (son travail n'est pas à vous de ranger). Cette invariant est ce qui rend votre récupération d'échec sûre.
- v2 — décidez maintenant de l'activité de votre lane, avant toute écriture. Lisez le marqueur d'exécution de votre lane — celui que
--lanenomme, ou en mode séquentiel la première lane que vous allez travailler (voir "backlogs v2 — files d'attente" ci-dessous). Fermée → c'est une exécution fraîche. Ouverte, nommant votre branche actuelle → débris de crash ; vous continuez sous le marqueur existant. Ouverte, nommant une branche différente → la lane peut être active ailleurs : STOP. Ensuite, s'il s'agit d'une exécution de lane par défaut ou d'une exécution séquentielle sans--lane, vérifiez les préconditions de barrière — toutes les autres lanes fermées et fusionnées — et refusez ici si elles ne tiennent pas. Chaque refus dans cette étape se produit avant que l'étape 3 n'écrive quoi que ce soit, donc une exécution qui ne doit pas commencer ne laisse aucun marqueur derrière elle.
- Récupérer, puis commiter la récupération une fois. Une ligne du Registre bloquée à
in-progressest un débris d'une exécution crashée — en v2, uniquement les lignes dans votre propre fichier de lane ; lein-progressd'une autre lane peut être une exécution parallèle active et n'est jamais à vous de toucher. Pour chaque telle ligne : annulez exactement les chemins source qui lui ont été attribués à l'étape 2 (règle d'exécuteur 9) s'il en reste ; journaliseztrouvé in-progress d'une exécution crashée — réinitialisé à todo; remettez la ligne àtodo. C'est le seul mouvement de statut arrière qu'un exécuteur peut faire, et seulement à la prévol. Ensuite, faites un commit couvrant tout ce que les étapes 2–3 ont touché — état de première exécution (ratchet: add backlog) ou récupération (ratchet: recover state). En v2, ce même commit porte également la ligne d'ouverture du journal de votre lane, qui dépend de ce que l'étape 2 a trouvé : une lane fraîche obtient- <date> exécution démarrée (lane <nom>, branche <branche>); une lane que vous avez trouvée ouverte sur votre propre branche obtient- <date> trouvé exécution ouverte depuis <date> — présumé crashée, récupérationet pas de secondexécution démarrée(l'existante est toujours votre marqueur d'ouverture de lane, et votreexécution terminéel'équilibrera). S'il n'y a rien d'autre à commiter, commitez cette ligne seule commeratchet(<lane>): exécution ouverte. En v1, si les étapes 2–3 n'ont rien trouvé, il n'y a rien à commiter. - Lire le Registre et l'intégralité du Journal — en v2, cela signifie chaque fichier de lane's registre et journal, pas seulement le vôtre (vous écrivez une lane ; vous les lisez tous). Le Journal est votre héritage — tentatives précédentes, pièges connus, hypothèses échouées. Ne réessayez pas quelque chose que le Journal dit avoir échoué sans une nouvelle raison.
- Établir la ligne de base verte. Exécutez chaque commande sous
## Global checksune fois, dans sa forme déterministe — à froid, sans cache incrémental, sans dépendre des types générés d'un serveur de développement en cours (untsc --noEmitchaud peut rapporter vert alors que la même vérification exécutée à froid, comme le fait CI, est rouge). Si une vérification globale semble sensible au cache et que le backlog ne l'a pas épinglée, exécutez la forme froide vous-même et notez l'écart dans le Journal. Baseline rouge → STOP et rapporter (vous ne pouvez pas ratchet forward à partir d'un début cassé) — sauf si un élément marqué[BASELINE]existe et est à vous de l'exécuter (v1 : toujours ; v2 : sonLane:correspond à votre--lane, ou aucun--lanen'a été donné), auquel cas cet élément est votre premier choix obligatoire, avant l'ordre du fichier. Dans une exécution v2--lane Xoù l'élément[BASELINE]appartient à une autre lane, STOP et rapporter : "bloqué par baseline par<ID>dans lane<Y>— exécutez d'abord cette lane, fusionnez, puis relancez". Attendre est un arrêt, jamais une écriture vers une autre lane. - Détecter la convention de commit du dépôt à partir de
git log --oneline -15(commits conventionnels ? phrases simples ? préfixes de scope ?). Vous y correspondrez. - Vérifier la branche. Si vous êtes sur la branche par défaut du dépôt et que le dépôt est basé sur des PR ou push-to-deploy, proposez de créer une branche de travail (
ratchet/<scope-ou-date>) avant le premier commit —/ratchet-shipouvre la PR plus tard. Procédez sur la branche par défaut uniquement avec l'accord explicite de l'utilisateur. Dans une exécution v2--lane X, la branche n'est pas un choix : reprenezratchet/Xsi elle existe, sinon créez-la à partir de la tête de la branche d'intégration, et fusionnez la branche d'intégration si vous êtes en retard sur elle — voir "backlogs v2 — files d'attente". - Lire
NEXT.md(dans le répertoire d'état) s'il existe. C'est le plan routé de/ratchet-recommend: honorez ses assignations de vérification par élément — un élément qu'il route SUPERVISED ou SENIOR nécessite--verify fresh. Si fresh n'est pas en vigueur, mettez de côté uniquement les éléments SUPERVISED/SENIOR qui autrement s'exécuteraient dans cette exécution (ils passent l'éligibilité et correspondent à--only) ; les éléments en dehors de la portée de cette exécution sont laissés intacts — leurs commandes de vague portent déjà les bons drapeaux. Si NEXT.md est antérieur à la dernière modification du Registre (v2 : la dernière modification de votre fichier de lane), dites qu'il est obsolète et suggérez de le régénérer — v1 : dans le répertoire d'état, comme d'habitude ; v2 : sur la branche d'intégration, jamais dans un arbre de travail de lane. Les drapeaux explicites de l'invocateur remplacent NEXT.md. Lecture seule en v2 : vous n'écrivez, n'indexez et ne commitez jamais NEXT.md. - Annoncer le plan : éléments éligibles dans l'ordre, éléments mis de côté avec raisons, la branche, les conditions d'arrêt en vigueur. En
--dry-run, arrêtez ici — et puisqu'une exécution à sec n'écrit rien, rapportez les commits que les étapes 2–3 auraient faits au lieu de les faire. Une exécution à sec n'ouvre donc jamais une lane : aucun marqueurexécution démarréen'est écrit ou commité, donc elle ne laisse aucune lane ouverte derrière elle.
Éligibilité
Un élément est éligible quand TOUT tient : Statut du Registre todo · pas de tag de barrière humaine ([USER-DECISION], [OPS], [RISKY]) · chaque ID Depends: est done (v2 : une dépendance cross-lane compte uniquement comme une ligne done visible dans votre arbre de travail — done et fusionné) · correspond à --only si donné · correspond à --lane si donné. Prenez les éléments éligibles dans l'ordre du fichier. Si chaque ID --only existe mais aucun ne porte le Lane: de la lane invoquée, c'est une erreur ("SEC-01 est dans lane ui — relancez avec --lane ui ou régénérez NEXT.md"), jamais un "backlog sec" silencieux. Éléments todo avec barrière humaine : mettez leur statut de Registre à needs-human avec le tag comme note (une fois), et passez. Les éléments mis de côté restent mis de côté jusqu'à ce qu'un humain les remette — statut de retour à todo, tag de barrière supprimé, décision journalisée (procédure "Transitions humaines" du format) ; vous ne le faites jamais vous-même.
Barrière haute sécurité (mécanique). Un élément est haute sécurité lorsque sa Spec ou sa Preuve touche à l'une des listes de déclenchement (textuellement de la règle d'exécuteur 1) : auth/permissions, limites de locataires (companyId / scopes de propriété), paiements ou mathématiques monétaires, comptabilité/validation GL/Journal, migrations de base de données, secrets/env, suppression de fichiers ou de lignes, ou gestion de session/cookie. Un élément haute sécurité non barrière n'est exécutable que lorsque les deux tiennent : (a) --verify fresh est en vigueur, et (b) l'invocateur l'a explicitement listé dans --only — c'est-à-dire qu'un humain ou le routage NEXT.md l'a choisi pour cette exécution. --lane ne compte jamais comme (b). Sinon, mettez-le de côté comme needs-human (note : "haute sécurité ; routez via /ratchet-recommend"). Exception : un élément [BASELINE] est exempté de l'exigence --only — son tag est le routage humain, et l'exécution ne peut pas continuer sans lui — mais utilisez une vérification fraîche pour lui quand il touche la liste de déclenchement et que fresh est disponible. Pas d'auto-évaluation sur quel modèle vous êtes — les drapeaux décident. Un "vert" erroné sur auth ou argent est l'échec le plus coûteux que Ratchet existe pour empêcher ; le coût d'un coup d'œil humain est toujours inférieur.
backlogs v2 — files d'attente
Un backlog v2 (<!-- ratchet:v2 -->) divise l'état par lane : le backlog contient ## Lanes + ## Items (chaque élément porte Lane: <nom>), et le Registre + Journal de chaque lane vivent dans lanes/<lane>.md — écrivain unique, donc des agents parallèles n'écrivent jamais le même fichier. Contrat complet : docs/backlog-format.md §5 dans le dépôt ratchet ; tout ce dont un exécuteur a besoin est ci-dessous.
Vérifications structurelles v2 (ajouts à l'étape 1 de prévol). STOP sur l'un des suivants : pas de ## Lanes ; le Scope de sa première lane n'est pas littéralement (rest), ou une deuxième lane revendique aussi (rest) (exactement une lane par défaut) ; scopes de lanes nommés qui se chevauchent ; un élément manquant Lane: ou nommant une lane non déclarée ; une lane déclarée dont le lanes/<lane>.md est manquant ou dont le marqueur <!-- ratchet:v2:lane <nom> --> ne correspond pas au nom de fichier et à la déclaration ; un élément sans ligne de Registre nulle part, une ligne dans le mauvais fichier de lane, ou des lignes en double dans des fichiers. Vous ne créez jamais de fichiers de lane — c'est le travail du curateur (/ratchet-backlog). Portée du refus dans une exécution --lane X : les défauts dans le backlog, dans lanes/X.md, ou dans la résidence de ligne des propres éléments de X sont des STOP ; les dommages internes confinés au fichier d'une autre lane sont un WARN fort — rapportez-le, ne le touchez jamais.
Marqueurs d'exécution (le signal d'activité). Une lane est ouverte lorsque, en scannant son journal de bas en haut, le premier marqueur d'exécution trouvé est exécution démarrée. Une exécution ouvre la lane qu'elle va travailler en ajoutant - <date> exécution démarrée (lane <nom>, branche <branche>) et en le commitant (étape 3 de prévol, ou ratchet(<lane>)).