Review Work

Que fait Review Work ?

Cette compétence révise le code, affiche les constatations sur une page web locale et ne corrige que ce que l'utilisateur approuve. Tous les correctifs approuvés atterrissent sur une seule branche et sont regroupés dans une seule pull request (PR).

L'agent principal (le chat qui exécute cette compétence) est en charge. Il définit le périmètre, choisit le modèle pour chaque agent helper, enregistre tous les enregistrements et vérifie tous les résultats. Les agents helpers effectuent le travail qui leur est confié et font leur rapport.

Cette compétence fonctionne à côté de plan-work et execute-work. Elle ne les appelle ni ne les modifie.

Termes utilisés ici

• Branche révisée : la branche soumise à la revue. La PR retourne dans cette branche. Il ne s'agit pas toujours de develop.
• Commit révisé : le SHA exact du commit qui a été révisé. Chaque constatation y fait référence.
• Constatation : un problème ou une question issue de la revue, avec un identifiant comme R001.
• Page : la page web locale où l'utilisateur choisit Corriger, Ne pas corriger ou Clarifier pour chaque constatation.
• Lot : les choix envoyés en un clic sur Soumettre.
• Worktree : une extraction supplémentaire du même dépôt dans son propre dossier.
• Branche de coordination : l'unique branche (avec son propre worktree) qui rassemble tous les correctifs. Elle devient la PR. Nommez-la selon le style Conventional Branch, <type>/<description-courte>, en minuscules avec des tirets. Les correctifs de revue sont généralement fix/, comme fix/session-recovery ; utilisez refactor/, perf/, docs/, test/ ou chore/ lorsque cela correspond mieux à l'ensemble des correctifs. Si l'utilisateur ou le dépôt nomme une convention différente (par exemple dans AGENTS.md), suivez-la. Ne mettez jamais integration dans le nom.
• Branche de tâche : une branche et un worktree éphémères où un helper effectue un correctif.
• Fusion avance rapide : une fusion qui ne fait qu'avancer la branche sans ajouter de commit de fusion (git merge --ff-only).
• Propre à l'exécution : créé par cette exécution de la revue. Le nettoyage ne touche que les branches et worktrees propres à l'exécution. Un nom correspondant n'est pas une preuve de propriété.

Ce que l'utilisateur a autorisé

• Démarrer cette compétence autorise les enregistrements de la revue et le service de page locale.
• Choisir d'afficher la page sur une autre machine liée autorise un thread d'hébergement de page sur cette machine, dans un projet T3 nommé Review-work pages (créé s'il manque). Il exécute uniquement la CLI de review-work. Il ne touche jamais au code là-bas. Une fois la revue terminée, la clôture de ce thread et la suppression du projet Review-work pages (ce qui supprime ses chats) sont autorisées, comme décrit dans remote-page.md. Ne supprimez jamais aucun autre projet. Ce chat de revue n'est jamais dans ce projet : il reste et reçoit le rapport final.
• Soumettre Corriger (sur la page, ou un « corrige-le » clair dans le chat) autorise les worktrees de tâche, les commits, les fusions dans la branche de coordination, le nettoyage sécurisé, le push et une PR prête à être révisée. Cela autorise également à surveiller la fusion de cette PR, puis à supprimer le worktree de coordination fusionné inchangé de cette exécution et la branche locale sur la machine de revue.
• Si l'utilisateur dit « local uniquement » ou « pas de PR », suivez cela.
• Ne fusionnez jamais la PR, n'activez pas la fusion automatique et ne déployez pas.

Étape 1 : Définir ce qui doit être révisé

1. Lisez les instructions, exigences, statut, branches et worktrees du dépôt. Laissez les modifications non commit et les autres exécutions tranquilles.
2. Enregistrez le chemin du dépôt, le dossier Git partagé, la branche, la base, le SHA du commit révisé, l'hôte (nom de la machine) et l'ID du chat.
3. Ne révisez que le code commité, avec git show, les diffs ou une extraction propre et gérée. Les fichiers non commités ne font pas partie de la revue.
4. Choisissez le périmètre :
   • Branche de fonctionnalité : révisez son diff par rapport à sa base. Obtenez la base de l'utilisateur, des règles du projet ou des métadonnées de la PR. Si ce n'est toujours pas clair, demandez.
   • develop : révisez l'intégralité du code actuel. N'inventez pas de date de début ou de commit de début.
5. Demandez « En ligne ou en éventail de sous-agents ? » sauf si l'utilisateur l'a déjà dit.
   • En ligne : l'agent principal révise lui-même. Les correctifs utilisent toujours des helpers.
   • En éventail : les helpers révisent en parallèle. Demandez le nombre maximum de helpers à la fois et suggérez un nombre basé sur les domaines indépendants utiles. Proposez Auto : autant de helpers utiles que la capacité le permet. Si la capacité est inconnue, dites que la limite est 4. Mettez le reste en file d'attente.
6. Avant de créer un worktree, enregistrez un instantané des worktrees actuels, des branches locales et des pièces jointes gérées. Gardez une liste de chaque worktree que cette exécution crée : réviseurs, correcteurs, helpers, tentatives et leurs enfants, même inchangés ou abandonnés. Voir cleanup.md.

Étape 2 : Démarrer les enregistrements de la revue

• Utilisez Node 24+ et scripts/review.mjs de cette compétence. Les commandes sont dans runtime.md.
• Exécutez init une fois, avec un fichier d'entrée JSON conservé en dehors du projet. Enregistrez le chemin du dossier de revue retourné et réutilisez-le. Lors de la reprise, ne créez jamais une nouvelle exécution.
• Les enregistrements se trouvent dans <home>/.agents/state/review-work/. Le runtime crée son .gitignore avant tout autre fichier, de sorte que Git ne les récupère jamais.
• L'identité d'un dépôt est son URL distante nettoyée plus son dossier Git partagé réel. Les worktrees liés d'un clone partagent une identité ; les clones séparés non. Chaque exécution possède également son propre ID, de sorte que les revues s'exécutant en même temps ne se mélangent pas.
• Seuls l'agent principal et son service de page écrivent les enregistrements. Ne copiez jamais la base de données, le service ou l'état dans un worktree ou un fichier .worktreeinclude. Les helpers retournent les résultats et l'agent principal les enregistre. Les helpers placent les fichiers volumineux dans leur propre dossier temporaire ; l'agent principal les importe.

Étape 3 : Choisir les modèles, puis réviser

Lisez routing.md d'abord.

• L'agent principal choisit le modèle exact et l'effort pour chaque tâche de révision et de correction. Il vérifie que l'hôte les propose, puis enregistre le choix avant de démarrer la tâche. Les helpers n'appellent jamais Jev et ne choisissent jamais les routes (modèle, effort ou options). Ils ne démarrent jamais leurs propres helpers, sauf si le principal leur donne une affectation exacte et fixe pour le faire.
• Restez dans la famille de modèles du chat : les modèles GPT dans un chat GPT ; Claude Opus, Sonnet ou Haiku dans un chat Claude.
• Toujours la version la plus récente. Les modèles sont choisis par leur nom de niveau (Astra, Sol, Terra, Opus, Sonnet, Haiku). Pour chaque niveau, le runtime ne conserve que la version la plus récente dans la liste des modèles de l'hôte et rejette les plus anciennes. Ne choisissez jamais une version de mémoire. Faites confiance à la liste des modèles de l'hôte plutôt qu'à des suppositions. N'inventez jamais un ID de modèle et ne changez pas de fournisseur en silence. Si la famille est inconnue ou si un modèle nécessaire est manquant, demandez.
• Jev peut d'abord choisir le modèle, puis un effort que ce modèle prend en charge. Il a besoin d'une clé. Trouvez-la avec la découverte d'identifiants du runtime, jamais en ouvrant le fichier vous-même. La découverte vérifie d'abord <home>/.config/jev/credentials.env (TYPESAFE_API_KEY est le nom recommandé). S'il n'existe pas de clé de répertoire personnel utilisable, vérifiez l'ordre réel de chargement des variables d'environnement du projet et ses adaptateurs configurés, puis transmettez ces chemins de fichiers d'environnement. N'imprimez, n'enregistrez et ne sourcez jamais de fichiers de clé ou de valeurs de clé. L'ordre de recherche complet se trouve dans routing.md.
• Un adaptateur MCP Jev configuré peut effectuer les deux mêmes choix. Lisez d'abord son véritable schéma d'outil ; ne supposez pas qu'un outil jev_route existe. Sans adaptateur, utilisez le transport direct intégré du runtime.
• Plafonds d'effort, pour chaque modèle : les révisions et la planification vont jusqu'à extra-haut, jamais max ou ultra. Les correctifs vont jusqu'à Haut. Le runtime rejette toute route au-dessus du plafond, de Jev ou du principal.
• Si Jev est manquant ou donne une réponse inutilisable, l'agent principal décide avec les mêmes règles. Il n'y a pas de table de repli fixe.
  • Travail de listage en lecture seule : Faible convient.
  • Algorithmes ou raisonnement difficile : Haut ou extra-haut.
  • Incertain : Haut.
  • Revue de sécurité et planification (connexion, autorisations, secrets, cryptographie, isolation des locataires, limites de confiance) : le plus récent GPT Astra ou le plus récent Claude Opus, à extra-haut. Si ce modèle n'a pas d'extra-haut, utilisez le même modèle à son niveau le plus élevé en dessous du plafond (au moins Haut). Ne passez pas à une version plus ancienne. Si un helper découvre un nouveau périmètre de sécurité, il arrête cette partie et fait son rapport au principal. La mise en œuvre planifiée utilise les routes de correctifs ci-dessous, y compris les correctifs de sécurité.
  • Révision en ligne lorsqu'une partie nécessite une route plus élevée : ne demandez pas à l'utilisateur de changer le modèle ou l'effort de ce chat. Ce chat ne peut pas confirmer ou définir son propre effort. Confiez cette partie (par exemple, les vérifications de sécurité) à un helper de révision, et définissez le modèle et l'effort exacts du helper lorsque vous le démarrez (dans Claude Code, les paramètres model et effort de l'outil Agent ; dans T3, les options delegate_task). Enregistrez d'abord la route. Le helper retourne les constatations ; l'agent principal les enregistre. Ne demandez à l'utilisateur que si l'hôte ne peut pas démarrer un helper avec le modèle et l'effort requis : alors expliquez l'écart et proposez de conserver le modèle de ce chat. Enregistrez ce choix une fois pour cette révision et ne redemandez pas. Cela n'abaisse jamais la règle pour les helpers en éventail.
• Divisez la révision par comportement et par fichiers. Suivez les flux à travers les fichiers. Cherchez les façons dont le code se casse : résultats erronés, règles violées, données perdues, vérifications manquantes et ruptures de compatibilité. Vérifiez chaque préoccupation par rapport aux exigences et au code qui s'exécute réellement. Fusionnez les doublons.
• Enregistrez la couverture : ce que vous avez vérifié, ignoré et que vous n'avez pas pu terminer, avec les chemins, le SHA, la raison et la preuve. « Aucune constatation » ne signifie pas que chaque fichier a été vérifié. Ne qualifiez pas la révision de complète tant qu'une couverture importante n'est pas prise en compte (non enregistrée comme vérifiée, ignorée ou non terminée).

Étape 4 : Rédiger des constatations compréhensibles

L'utilisateur décide uniquement à partir du texte de la constatation, donc le texte doit être court, précis et clair. Lisez writing-findings.md. Donnez son chemin à chaque helper de révision et dites-lui de le suivre.

Utilisez les libellés des commentaires conventionnels tels que issue, question, suggestion et nitpick. Marquez chaque constatation blocking ou non-blocking. Chaque constatation comporte quatre parties :

• Titre : ce qui ne va pas, sous forme d'une phrase simple de 80 caractères ou moins. « Une nouvelle tentative de paiement peut créer deux factures », pas « Chemin de création de facture non idempotent ».
• Pourquoi c'est important (discussion) : qui ou quoi est touché, quand et à quelle fréquence.
• Preuve (evidence, plus un excerpt de code optionnel) : chemin:ligne, le chemin du code ou les étapes, et comment vous le savez.
• Idée de correctif (suggestion) : commence par Petit correctif, Correctif moyen ou Grand correctif, puis dit quoi changer.

Si vous n'êtes pas sûr, écrivez une question. Ne présentez jamais une supposition comme un issue confirmé. Donnez à chaque constatation un ID stable, le chemin et la ligne, et le SHA révisé.

Avant de charger les constatations, exécutez la vérification de clarté dans writing-findings.md sur chacune. Réécrivez celles qui échouent et conservez chaque fait.

Étape 5 : Afficher la page et recueillir les décisions

1. Chargez les constatations et la couverture, puis démarrez la page. Une seule page sert pour toute la révision, y compris les tours ultérieurs.

2. Pour chaque constatation, l'utilisateur choisit Corriger, Ne pas corriger ou Clarifier, et peut ajouter une note à n'importe laquelle. Les choix sont enregistrés comme brouillons. Changer de choix conserve la note.

3. Seulement Soumettre envoie un lot. Les lots partiels sont acceptables ; les constatations non décidées restent ouvertes. Les choix soumis sont verrouillés sur la page. Les changements se font dans le chat.

4. Vérifiez d'abord le harnais. Ce chat s'exécute dans T3 Code lorsque son shell contient T3CODE_THREAD_ID ou T3CODE_CLI_PATH, ou lorsque des outils T3 tels que t3_environment_links sont disponibles. Si ce n'est pas le cas :

   • Affichez la page sur cette machine, avec deliveryMode: "terminal".
   • Ignorez le choix d'hôte de page ci-dessous et n'en proposez pas un autre. Ne lisez pas remote-page.md.
   • Utilisez le libellé du terminal simple au point 5.

   Dans T3, choisissez où afficher la page à partir de l'origine du chat. Gardez cela séparé du choix en ligne/éventail.

   • Honorez un choix explicite d'hôte de page déjà fait dans ce chat. Lors de la reprise, réutilisez-le ; ne redemandez que si l'utilisateur le modifie ou si cet hôte n'est pas disponible.
   • Si le chat a été démarré localement sur la machine de révision, affichez la page sur cette machine sans demander. Établissez cela à partir de la déclaration de l'utilisateur ou des métadonnées d'origine du client fournies par l'hôte qui identifient l'appareil initiateur. Le nom d'hôte de l'agent, le répertoire de travail, l'environnement d'exécution ou creationSource (web, mobile ou mcp) seul ne prouve pas où l'utilisateur a démarré le chat.
   • Si le chat a été démarré à distance, ou si son origine est incertaine, demandez une fois où afficher la page. Demandez directement l'hôte de la page, sans une question distincte sur la question de savoir si l'utilisateur est local. Appelez t3_environment_links et proposez cette machine plus chaque machine liée accessible avec un accès complet, en utilisant leurs libellés réels. N'excluez aucune machine en raison de son système d'exploitation. Expliquez un bloqueur de capacité/d'accès connu au lieu de masquer silencieusement un hôte. Si l'outil de question ne peut pas contenir tous les choix, listez tous les hôtes éligibles dans la question et acceptez un nom d'hôte.
   • Recommandez la machine de l'utilisateur lorsqu'elle est connue et éligible. Expliquez la limitation de verrouillage d'écran uniquement lorsqu'elle affecte le choix : le navigateur diffusé de T3 s'arrête lorsque l'écran de la machine de révision est verrouillé. Enregistrez l'hôte sélectionné et la preuve d'origine (ou unknown) dans les notes de révision.
   • Sur une autre machine : suivez remote-page.md. La page s'ouvre dans le navigateur de l'utilisateur là-bas, et Soumettre renvoie les choix à ce chat. Cela nécessite des liens T3 avec accès complet. Cela fonctionne pendant que cette machine est verrouillée.

5. Donnez toujours le lien vers l'hôte et la page.

   • Dans T3, sur cette machine : le navigateur T3 peut ouvrir la page. Dites « La soumission reprend cette conversation automatiquement. » La page utilise la commande locale t3 thread send. Aucun webhook public ou tunnel n'est nécessaire.
   • Dans T3, sur une autre machine : dites quelle machine affiche la page, et « La soumission renvoie vos choix à ce chat. »
   • Dans un terminal simple, dites :
     1. Ouvrez la page de révision.
     2. Choisissez une option pour chaque constatation, ajoutez des notes si vous le souhaitez, et cliquez sur Soumettre.
     3. Revenez à ce chat et dites « Soumis » pour charger les résultats. N'ajoutez pas d'étapes de copier-coller ou de tunnels. npx review-work page donne le lien ; utilisez-le tel quel.

Étape 6 : Appliquer et rassembler les correctifs approuvés

Lisez fixing.md d'abord.

⏵ Avant le premier tour de correctifs, vérifiez l'accès Git push. Exécutez git fetch sur la branche de base de la PR de révision. Si le push est impossible (par exemple, autorisation refusée, dépôt en lecture seule), définissez le mode hors ligne : aucun push, pas de PR, signalez local uniquement. Ne poussez jamais ailleurs et ne demandez pas un accès plus élevé.

Ensuite, appliquez les correctifs approuvés. Les helpers font les correctifs ; le rassembleur (le principal) les fusionne.

Flux de travail :

• Le rassembleur crée la branche de coordination sur la dernière extraction propre du commit de base.
• Pour chaque correctif, le principal crée une branche de tâche, démarre un helper, fusionne (avance rapide) dans la branche de coordination, supprime la branche de tâche et le worktree.
• Les helpers reçoivent exactement ce dont ils ont besoin (contexte, constatation, SHA de coordination) et pas plus. Le principal ajoute l'en-tête du fichier à chaque extrait pour que chaque helper voie les importations et les types. Les helpers n'écrivent que du code qui compile et ne suppriment ni ne renomment des fichiers. Ils utilisent la version la plus récente du langage et des dépendances du projet et suivent les règles du projet dans AGENTS.md, package.json, cargo.toml, pyproject.toml, go.mod, Makefile, etc. Si le projet a un guide de style ou des heuristiques, le principal les leur transmet. Les helpers peuvent demander des éclaircissements via le principal, mais pas directement à l'utilisateur. Les helpers ne créent pas de PR, ne poussent pas et ne lisent pas la page ou ses entrées.
• Le principal valide les sorties des helpers dans l'ordre : modifications du répertoire de travail, pas de binaires, pas de dépendances ajoutées, pas de machines, pas de tests qui cassent la compilation, pas de code qui échoue aux vérificateurs de type. Les correctifs ne cassent pas l'API publique, ne changent pas les protocoles réseau, n'ajoutent pas de secrets, ne changent pas la configuration de sécurité déployée et ne suppriment pas de fichiers non temporaires. Si l'un d'eux échoue, le principal rejette le correctif, enregistre l'échec et le signale. Il ne réessaye pas automatiquement.
• Le principal enregistre chaque correctif dans la base de la revue : chemin, commit de correctif, SHA de la branche de coordination après fusion.

Ordre des correctifs : appliquez-les dans l'ordre où ils sont listés sur la page ou dans le chat, sauf si la dépendance l'exige différemment. Si un correctif dépend d'un autre, appliquez d'abord le dépendu. Si un correctif échoue là où un correctif précédent aurait dû le résoudre, ne réessayez pas la version ratée ou ultérieure. Signalez-le.

Édition en ligne (principal) : Pour une constatation simple comme un nitpick ou une mini-constatation, le principal peut éditer le fichier lui-même, avec l'outil d'édition du chat hôte. L'édition en ligne doit être un correctif sûr et atomique. Testez-le : appliquez la modification, validez-la sur une branche de coordination locale (en dehors du gestionnaire de worktree), puis supprimez cette extraction de coordination. Si l'édition en ligne est plus risquée, déléguez-la à un helper.

Marquer comme terminé : lorsque le principal termine un correctif (validé, enregistré et fusionné dans la coordination), il met à jour la base de la revue. Lors de la validation : rédigez un message de commit basé sur la constatation. Le message inclut l'ID de la constatation au début. Ne mentionnez pas la page ni les mécanismes internes. Utilisez le langage du dépôt. Le corps du message est facultatif et ne doit pas faire référence à ce projet Review Work.

Lorsque plus aucun correctif n'est approuvé : exécutez finalize.

Étape 7 : PR ou rapport local

1. Toujours montrez les constatations, la couverture et les enregistrements de correctifs d'abord. Résumez les constatations : un tableau de base (ID, titre, sévérité) suivi de la couverture (vérifiée, ignorée, non terminée) et des correctifs (appliqués, échoués). Proposez de rouvrir la page pour cette session ou d'en démarrer une nouvelle.
2. PR (mode push) : lisez les règles du dépôt pour les PR. Si elles ne sont pas claires, demandez à l'utilisateur au lieu de deviner. Ouvrez une PR depuis la branche de coordination vers la branche de base de la revue. Le titre est « Correctifs de la revue de [nom court de la branche] ». Le corps liste chaque constatation corrigée avec un lien vers sa section. Publiez le lien de la PR, marquez l'URL en tant que PR_URL dans les notes de la revue, et attendez la fusion de la PR. En cas d'échec, arrêtez-vous et signalez l'erreur. Ne réessayez pas d'ouvrir une PR existante.
3. Affichage local (mode hors ligne ou local uniquement) : affichez le résumé des résultats et les détails. Ne créez pas de PR et ne poussez pas. Proposez de copier la branche de coordination quelque part ou de créer un patch. N'appliquez pas vos propres modifications ; laissez la décision à l'utilisateur.
4. Après la fusion de la PR : attendez que l'événement pull_request_closed avec merged: true arrive. Ne supposez pas la fusion et ne la vérifiez pas. Une fois confirmée, supprimez la branche de coordination et le worktree de cette exécution sur la machine de révision. Le travail non modifié disparaît aussi. Ne supprimez pas la branche de coordination sur le distant.

Étape 8 : Nettoyage complet

Lisez cleanup.md pour la fin d'une session d'exécution. Le nettoyage se produit lors de l'arrêt, même en cas d'erreur. Une fois le nettoyage terminé, le travail de cette exécution est terminé.