Communitygithub.com

Ratchet Loop — l'exécuteur

Boucles d'ingénierie reprise pour Claude Code — auditez un codebase en un backlog validé par des critères d'acceptation, puis exécutez-le un commit vérifié à la fois.

Qu'est-ce que Ratchet Loop — l'exécuteur ?

Ratchet Loop est un agent exécuteur pour Claude Code conçu pour les audits et l'ingénierie progressifs de codebase. Il transforme un backlog de tâches—généré par un outil d'audit—en une séquence de commits vérifiés, garantissant que seuls les éléments confirmés comme terminés sont commités. L'agent fonctionne de manière apatride, en s'appuyant sur un fichier de backlog unique comme source de vérité, et inclut des phases de préparation robustes : validation structurelle du backlog, nettoyage de l'état de travail, récupération après crash, exécution des vérifications globales, et détection des dépendances. Il prend en charge les exécutions parallèles via des backlogs v2 avec des files d'attente (lanes), où chaque lane possède son propre journal et registre (ledger), permettant à plusieurs agents de travailler simultanément sans conflits. Le mécanisme de 'haute sécurité' exige une vérification fraîche et un routage explicite pour les tâches sensibles (authentification, limites de locataires, paiements), garantissant que les actions critiques ne sont pas automatisées sans supervision humaine. L'agent fournit également des vérifications de validation et des rapports d'exécution détaillés via des journaux et des registres, ce qui le rend idéal pour les flux de travail CI/CD où l'intégrité du codebase est primordiale.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add afrizzal/ratchet

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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, sinon BACKLOG.md à la racine du dépôt. Si aucun n'existe, dites-le et suggérez /ratchet-audit ou /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éfaut ratchet/).
  • --lane NOM — backlogs v2 uniquement (erreur sur un fichier v1) : restreindre l'éligibilité aux éléments avec Lane: NOM et n'écrire l'état que dans lanes/NOM.md. C'est le mode parallélisable — voir "backlogs v2 — files d'attente" ci-dessous. --lane est un sélecteur d'état, pas un routage : il ne satisfait jamais l'exigence --only de 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éfaut inline.
  • --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)

  1. 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 :lane signifie 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 son Lane: 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.md dans le dépôt ratchet ; les vérifications dont vous avez besoin sont celles listées ici.)
  2. Exiger un arbre de travail propre — avec l'exception d'état de boucle. git status ne 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.md est 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 comme ratchet: add backlog exactement 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 ligne in-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. Un NEXT.md sale 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-progress sont 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 --lane nomme, 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.
  3. Récupérer, puis commiter la récupération une fois. Une ligne du Registre bloquée à in-progress est un débris d'une exécution crashée — en v2, uniquement les lignes dans votre propre fichier de lane ; le in-progress d'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 ; journalisez trouvé 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ération et pas de second exécution démarrée (l'existante est toujours votre marqueur d'ouverture de lane, et votre exécution terminée l'équilibrera). S'il n'y a rien d'autre à commiter, commitez cette ligne seule comme ratchet(<lane>): exécution ouverte. En v1, si les étapes 2–3 n'ont rien trouvé, il n'y a rien à commiter.
  4. 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.
  5. Établir la ligne de base verte. Exécutez chaque commande sous ## Global checks une 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 (un tsc --noEmit chaud 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 : son Lane: correspond à votre --lane, ou aucun --lane n'a été donné), auquel cas cet élément est votre premier choix obligatoire, avant l'ordre du fichier. Dans une exécution v2 --lane X où 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.
  6. 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.
  7. 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-ship ouvre 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 : reprenez ratchet/X si 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".
  8. 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.
  9. 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 marqueur exécution démarrée n'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>)).

Skills associés