auto-pr
Objectif : pointer vers n'importe quel dépôt GitHub et ouvrir N PR fusionnables — pas N PR quelconques. Chacune résout un vrai problème (ou une amélioration découverte légitime), passe la suite de tests locale du dépôt, et est validée par un second moteur avant d'atteindre un mainteneur.
Il s'agit d'une fine couche d'orchestration autour de la CLI vouch auto-pr. C'est un
outil frère de la base de connaissances : il n'écrit jamais dans le stockage / les propositions /
le journal d'audit, et la porte de révision reste intacte.
invocation
vouch auto-pr <repo-url> \
--workspace <dir> --count <N> \
--claude-effort <low|medium|high|max> \
--codex-effort <low|medium|high|max> \
[--issue-label good-first-issue] \
[--fork-owner <login>] \
[--max-revise 2] [--autonomy edit|full] \
[--dry-run] [--json]
<repo-url> peut être https://github.com/<owner>/<name>,
[email protected]:<owner>/<name>.git, ou la forme raccourcie <owner>/<name>.
Sortie : les URL des PR effectivement ouvertes (une par ligne, ou un tableau
JSON avec --json). Les tentatives qui échouent à la vérification sont signalées sur stderr
comme ignorées avec une raison — elles ne sont jamais ouvertes. M vraies PR valent mieux que N PR bancales ;
le succès partiel est le comportement attendu, pas une erreur.
prérequis
- CLI
ghauthentifiée pour le dépôt cible (gh auth statusretourne une session). Utilisée pour le fork/clone, la liste des issues, la recherche de dédoublonnage et la création de PR. claude(Claude Code) etcodexdans lePATH— les deux moteurs sont utilisés ; l'un corrige pendant que l'autre révise, en alternance par PR.- CLI
vouchdans lePATH(pip install vouch-kb).
Si claude ou codex est manquant, arrêtez-vous et informez l'utilisateur — la vérification croisée est
l'essence même ; ne passez pas silencieusement à un seul moteur.
fonctionnement (le pipeline)
- Résolution de l'espace de travail — si
--workspaceest déjà un clone, utilisez-le ; sinongh repo fork --clone(ou un simple clone si vous avez un accès push). Synchronisez la branche par défaut. - Détection ou amorçage des directives — analysez le dépôt pour
CONTRIBUTING.md,AGENTS.md,CLAUDE.md,.claude/skills/**/SKILL.md,.codex/,.github/PULL_REQUEST_TEMPLATE.md. S'ils existent, ils deviennent le contexte du correcteur/réviseur. S'il n'y en a aucun, récupérez les PR fusionnées du dépôt et synthétisez unSKILL.mdde contribution, écrit dans le répertoire.claude/skills/du clone (et un miroir.codex/) pour être réutilisé à l'exécution suivante. - Sélection de N éléments de travail — ouvrez d'abord les issues non attribuées (filtrables par
--issue-label) ; si moins de N survivent au dédoublonnage, laissez les moteurs découvrir de vrais bugs/améliorations pour combler le reste. Chaque candidat est vérifié contre les PR existantes du dépôt. - Par élément (branche isolée
auto-pr/<slug>) : le moteur correcteur édite + commite ; la propre passerelle du dépôt s'exécute (make check/pytest/npm test/cargo test/go test) ; l'autre moteur révise le diff. Un échec de la passerelle ou un rejet renvoie au correcteur pour jusqu'à--max-revisetours. Toujours en échec ⇒ ignorer avec une raison. Réussite ⇒ pousser vers le fork etgh pr create.
règles de conduite imposées
- titres de commit conventionnels ; corps de texte en minuscules.
- pas de
Co-Authored-By/ mention d'attribution IA dans les commits générés. - dédoublonnage avant ouverture — pas de Nième doublon d'un correctif déjà essayé/rejeté.
- la propre passerelle CI-équivalente du dépôt doit être verte localement avant l'ouverture d'une PR.
- un seul changement logique par PR ; liez/fermez l'issue qu'elle adresse.
niveaux d'effort
--claude-effort / --codex-effort ajustent chaque moteur indépendamment :
| niveau | modèle claude | raisonnement codex |
|---|---|---|
| low | haiku | low |
| medium | sonnet | medium |
| high | opus | high |
| max | opus | high (limite codex) |
(les modèles claude sont passés sous forme d'alias — opus/sonnet/haiku — afin que l'outil
suive le dernier modèle de chaque palier. high et max sélectionnent tous deux opus ; codex
limite l'effort de raisonnement à high.)
Utilisez high pour des contributions réelles ; passez à low/medium uniquement pour des
exécutions exploratoires bon marché. Commencez par --dry-run sur un nouveau dépôt pour voir ce qu'il
ouvrirait avant d'utiliser un moteur pour de vrai.
autonomie et sécurité
Le correcteur pilote les moteurs sans supervision sur un clone d'un dépôt tiers non fiable, donc la valeur par défaut est restreinte :
--autonomy edit(par défaut) — claudeacceptEdits(accepte automatiquement les modifications de fichier, pas d'exécution de commande arbitraire) et codex--sandbox workspace-write(écritures confinées au clone, pas de réseau). Suffisant pour la plupart des correctifs, puisque la passerelle de test s'exécute via le propre lanceur de vouch, pas le moteur.--autonomy full— fait monter claude àbypassPermissions(le moteur peut exécuter des commandes arbitraires sans demande d'autorisation). À utiliser uniquement pour les dépôts dont le correctif nécessite réellement l'exécution de commandes, et uniquement sur des dépôts auxquels vous faites assez confiance pour exécuter des commandes. C'est un choix explicite, par exécution, de l'opérateur — jamais la valeur par défaut.
La révision est toujours en lecture seule (claude plan / codex read-only).
sémantique des échecs
- L'échec de la résolution de l'espace de travail ⇒ toute l'exécution est interrompue ; rien n'a été ouvert.
- Aucun élément de travail ⇒ sortie propre avec « rien à faire ».
- Un seul élément échoue (pas de diff, passerelle rouge, rejet après le nombre maximal de révisions, erreur
push/
gh) ⇒ cet élément est ignoré avec une raison ; le lot continue. - Un binaire de moteur manquant ⇒ échec rapide en nommant le binaire.