trailofbits/pr-improver

Améliorateur de PR (PR Improver)

Améliore la branche courante en exécutant /code-improver:improve — un workflow dynamique qui boucle un reviewer de PR et un sous-agent correcteur sur les modifications de la branche jusqu'à ce qu'une revue ne signale plus aucun problème critique ou majeur. La boucle, son registre et ses gardes vivent dans le workflow ; cette compétence dérive le périmètre à partir du diff de la branche et transmet le résultat.

Démarrage de la boucle

L'utilisateur a fourni : $ARGUMENTS (si vide, prendre la branche de base et les préférences de la conversation).

1. Résoudre la branche et sa surface de modification

1. Racine du dépôt : git rev-parse --show-toplevel. Échouer bruyamment en dehors d'un dépôt.
2. Base : l'argument s'il est fourni, sinon la branche par défaut du dépôt (git symbolic-ref refs/remotes/origin/HEAD → son nom court, avec repli sur main). Refuser d'exécuter si la branche courante EST la base — il n'y a pas de diff à améliorer.
3. Fichiers modifiés : git diff --name-only <base>...HEAD. Si vide, le dire et s'arrêter.
4. Périmètre : les répertoires des fichiers modifiés, élargis — les globs par fichier sont trop restrictifs (les corrections de PR ajoutent légitimement des tests à côté du code modifié). Mapper chaque fichier modifié à son glob de répertoire relatif au dépôt <dir>/** (** à la racine du dépôt uniquement si des fichiers à la racine ont été modifiés), puis dédupliquer et supprimer les globs couverts par un autre.

2. Résoudre le script de la boucle

La boucle est le workflow dynamique workflows/improve.js dans ce plugin. Lancer par chemin : scriptPath prend un chemin absolu résolu, et l'outil Workflow résout les workflows intégrés et de projet avec son name, donc un plugin installé via la marketplace peut ne pas répondre à code-improver:improve. Essayer dans l'ordre, le premier trouvé gagne — les répertoires personnels viennent avant . donc une copie installée l'emporte sur un checkout de cette marketplace :

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (si cette variable est définie à la place)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Utiliser le chemin exactement tel qu'imprimé. Son répertoire de plugin — le chemin avec /workflows/improve.js supprimé — est pluginRoot. Si les trois tentatives échouent, essayer {name: "code-improver:improve"} une fois ; si cela aussi est indisponible, s'arrêter et dire que la boucle n'a pas pu être localisée. Ne pas assembler un chemin manuellement et ne pas improviser la boucle.

3. Invoquer le workflow

L'exécuter avec l'outil Workflow, {scriptPath: "<le chemin de l'étape 2>", args: {...}} :

{
  "target": "<racine du dépôt>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Revoir les modifications de l'arbre de travail par rapport à <base> comme une pull request : exactitude, tests, gestion des erreurs et les dimensions de revue prescrites par la compétence."
  },
  "scope": ["<glob-de-répertoire-dérivé>/**"],
  "pluginRoot": "<le répertoire du plugin de l'étape 2>",
  "maxRounds": 5
}

• reviewer — la valeur par défaut ci-dessus nécessite le plugin pr-review-toolkit. Si l'utilisateur nomme un autre reviewer de PR (compétence ou agent), l'utiliser, avec kind défini en conséquence.
• maxRounds uniquement si l'utilisateur a demandé un plafond différent.
• pluginRoot permet à l'exécution de trouver son collecteur de métriques ; omettre la clé uniquement si l'étape 2 a échoué et a utilisé le nom du workflow — le workflow se cherche alors lui-même.
• Les valeurs par défaut de finalize conviennent pour les PR : pas d'incrémentation de version sauf si la branche se trouve dans un plugin, la bande de narration et les docs sont transmis.
• decision uniquement en cas de continuation (ci-dessous).

L'instantané de base de la boucle est l'arbre au démarrage de la boucle — sa garde de périmètre protège le travail non commité de la branche ; les commits propres de la PR sont ce que le reviewer examine.

Le workflow s'exécute en arrière-plan et ne nécessite pas de supervision : il revoit, corrige, revoit, vérifie le périmètre après chaque cycle de correction, et ne peut se terminer que sur une revue propre. Il ne commit jamais ; toutes les modifications restent dans l'arbre de travail.

Si l'outil Workflow est indisponible ou refusé, s'arrêter et le dire. Ne pas improviser la boucle en ligne avec des modifications directes — le registre, la garde de périmètre et les garanties d'escalade vivent dans le workflow, et une imitation en ligne n'en a aucune.

Si le résultat est halted: "reviewer-unavailable", le transmettre et s'arrêter. Le reviewer n'est pas installé dans cette session ; indiquer à l'utilisateur quel plugin le fournit (la valeur par défaut nécessite pr-review-toolkit) et relancer après installation. Ne pas revoir la branche soi-même.

Ne pas terminer son tour pendant que la boucle est en cours d'exécution. L'outil Workflow renvoie un identifiant de tâche immédiatement ; le résultat arrive plus tard. Dans une session interactive, la notification de terminaison vous ré-invoque — attendre. Dans une exécution non interactive (scriptée, CI, évaluation), il n'y a pas de tour ultérieur : s'arrêter abandonne la boucle au milieu d'un tour, donc après le lancement, interroger la tâche (TaskOutput avec l'identifiant de tâche renvoyé, ou dormir-et-revérifier) jusqu'à ce qu'elle se termine, puis transmettre le résultat. Une session qui répond "la boucle tourne, je ferai un rapport plus tard" a perdu l'exécution.

Transmission du résultat

Le workflow renvoie un résultat structuré. Le rapporter honnêtement — les distinctions sont importantes :

• converged: true — la dernière action était une revue sans aucun problème critique ou majeur. Rapporter le nombre de tours utilisés, les problèmes mineurs restants (open_minor_count), et les chemins des artefacts (ledger_path, metrics).
• capped: true — le budget de correction est épuisé et la revue FINALE a encore trouvé des problèmes bloquants. Dire clairement : plafonné, PAS convergé, et lister open_blocking. Ne pas présenter cela comme un succès.
• escalation — la boucle a détecté qu'elle ne convergeait pas (problèmes récurrents, comptes non décroissants, ou une correction déplaçant un problème). Transmettre le message d'escalade et les identifiants des problèmes à l'utilisateur : cela nécessite une décision de conception, pas plus de tours.
• halted — une garde s'est déclenchée (violation de périmètre, nouveaux fichiers non enregistrés, un reviewer mort ou indisponible, ou un passage de finalisation dont les propres modifications ont échoué à la vérification qui le suit). Transmettre les chemins dans violations/new_untracked_files, les sites dans finalize_regressions, et les notes.
• notes accompagnent toujours le résultat — les faire remonter ; elles incluent des avertissements forts tels que "un dépôt git a été initialisé".

Continuer après une escalade

La boucle s'arrête par conception sur escalade. Lorsque l'utilisateur décide, démarrer une nouvelle exécution avec les mêmes arguments plus :

{ "decision": "<la décision de l'utilisateur, textuellement>" }

La nouvelle exécution recharge le registre sur disque, donc chaque problème, rejet et verdict est repris — les tours redémarrent, la re-dérivation ne se produit pas.

Pour arrêter une boucle en cours, arrêter la tâche du workflow (TaskStop) ; le registre sur disque est à jour jusqu'au dernier tour et une ré-exécution reprend à partir de là.

Quand NE PAS utiliser

• Revue unique : exécuter la compétence de revue de PR directement ; la valeur de la boucle est l'itération
• Une compétence : utiliser l'entrée skill-improver — elle connecte le bon reviewer
• Travail exploratoire non poussé : les boucles de revue-et-correction durcissent un diff ; tant que la forme est fluide, l'itération manuelle donne plus de contrôle