GravionLabs/deliver

Livrer les PBI et Bugs ouverts d'un problème (un élément de travail = problème ouvert étiqueté pbi ou bug ; un Bug suit la même boucle, type de branche fix, Closes #<nr>) un par un : un sous-agent implémente, un sous-agent révise, cette session ouvre la PR, attend la CI et fusionne. Les mêmes étapes sur tous les harnais (Claude Code, OpenCode, Copilot CLI). L'état réside uniquement dans GitHub (problèmes, sous-problèmes, branches, PRs), donc une exécution peut s'arrêter à tout moment et /deliver <nr> reprend là où elle s'est arrêtée. Le garde-fou est l'ensemble de règles sur release/next : une vérification requise rouge ou manquante bloque la fusion quoi que fasse cette session.

Entrée

help (ou --help, -h) : affiche references/help.md inchangé, rien d'autre.

/deliver status --milestone <nom> : affiche le bloc d'état (## Status block) et s'arrête, rien n'est livré.

/deliver <nr> [<nr> …] [--milestone <nom>] [--unattended] [--inline] [--max <n>] : chaque numéro est un PBI, Bug, Feature ou Epic ; --milestone <nom> (une release, M<n> ou un titre legacy) ajoute les éléments de travail ouverts de ce milestone (une lecture groupée du milestone (pwsh <skill-dir>/../github-milestone/scripts/Get-Milestones.ps1 -Mode issues -Name <nom> -State open : REST, toutes les pages, pas de PRs ; la recherche github-milestone résout M4 en titre M4 ou, après close, M4 (0.2.0) ; filtre la liste retournée par étiquette : pbi, bug), plus les éléments de travail sous les Features et Epics qu'il contient). Le milestone.title de cette lecture est le titre pour gh issue create --milestone ; <key> est son M<n> ou sous-numéro M<n>.<m> (legacy : le titre) et nomme le fichier d'état et les indices. Manquant : demander une fois. --max <n> s'arrête après n PBI livrés, bloqués ou mis en pause et affiche le rapport (scripts/Invoke-DeliverLoop.ps1 utilise --max 1 par session fraîche, references/loop.md).

• Interactif (par défaut) : une règle de pause demande à l'utilisateur dans le chat ; un PBI bloqué demande : réessayer, ignorer ou une instruction.
• Session de contrôle : interactif avec plus de PBI que deliver.loopThreshold (par défaut 3), par ex. chaque --milestone : ne pas les livrer ici, démarrer Invoke-DeliverLoop.ps1 et rester une session légère pour les décisions, les PBI interactive et l'étape 9 (references/control.md). --inline les livre tous dans cette session (étapes 1 à 9). --no-preflight saute Start 3.
• --unattended (claude -p, opencode run, copilot -p) : ne jamais demander. Une pause commente le problème, ajoute l'étiquette needs-decision et continue avec le prochain PBI qui n'en dépend pas.

Start

1. gh auth status fonctionne et le dépôt a release/next.
2. gh api repos/{owner}/{repo}/rules/branches/release/next --jq '.[].type' : pas de required_status_checks dans la sortie → avertir que la CI rouge est fusionnable ici (ensemble de règles de github-release), puis continuer.
3. Pré-vol (ignoré par --no-preflight) : pwsh <skill-dir>/scripts/Test-DeliverPreflight.ps1 -Harness <claude|opencode|copilot> [-Unattended] -Text affiche une ligne par vérification, ok / corrigé / action nécessaire : compétences en pile, liste blanche (git, gh, pwsh <skill-dir>/scripts/*, les commandes de vérification de AGENTS.md ; entrées par harnais : references/permissions.md, sinon une exécution non supervisée bloque sur une invite), worktrees périmés ; réactions dans references/preflight.md. Écrire les commandes sans $(…) entre guillemets ; la vérification des permissions ne peut pas les traverser.
4. Événements de progression : sans AGENT_EVENTS_RUN, exécutez pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type run.started -Source session et conservez l'ID d'exécution imprimé. Ajoutez -Run <id> à chaque appel ultérieur (step.finished, attention, issue.finished, run.finished) : les appels Bash ne partagent pas d'état de shell, et AGENT_EVENTS_RUN comme préfixe ne correspondrait pas à la liste blanche. Chaque ligne de progression, raison d'attention et la fin passent par Report-Progress.ps1 ; il les affiche dans le terminal où la session s'exécute (references/terminal-backends.md).

Étapes

Afficher une ligne par étape dans le chat : #<nr> <étape> : <résultat> (#12 review : 1 bloquant → fix 1/2). Signaler chaque ligne : pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type step.finished -Issue <nr> -Step <étape> -Result "<résultat>" [-Pr <url>]. Aussi -Type attention (-Kind pr_opened avec -Pr <url> après l'étape 6, review_fix lorsqu'un tour de révision ou de CI démarre un tour de correction, ci_red lorsque l'étape 7 est rouge ; -Reason) : les notifications de la boucle viennent uniquement de ces événements. Une pause, un PBI bloqué ou un point nécessitant l'utilisateur : -Type attention (-Kind paused, blocked ou needs_you, -Reason) à la place. Après chaque PBI -Type issue.finished -Issue <nr> -Outcome <résultat>.

Chaque PR et problème que le chat nomme est écrit sous forme d'URL complète (https://github.com/<owner>/<repo>/pull/<n>, .../issues/<n>), pas comme un #<n> nu : un nombre nu n'est pas un lien dans le terminal. Cela vaut pour les lignes de progression, les questions à l'utilisateur et le rapport, en particulier pour la PR de release (étape 9), que l'utilisateur doit fusionner. Obtenez l'URL à partir de gh (html_url), ne la construisez jamais de mémoire.

1. Sélectionner. gh api repos/{owner}/{repo}/issues/<nr> --jq '{number,title,state,labels:[.labels[].name],body}' pour chaque numéro et leurs sous-problèmes (github-issue references/sub-issues.md, récursivement jusqu'aux PBI et Bugs). Collectez les éléments de travail ouverts (pbi ou bug) de tous les numéros et du milestone, supprimez les doublons, conservez ceux sans needs-decision (celui dont le corps a le critère ADR est signalé #<nr> select : decision, write the ADR with adr) ; ordonnez-les par leurs liens bloqués par entre eux tous, les égalités conservent l'ordre des arguments. Avec --milestone, un PBI ou Bug atteint via une Feature ou un Epic du milestone qui n'a pas de milestone ou un autre milestone n'est pas livré (#<nr> select : outside M<n>, skipped, indice : définir le milestone, github-issue references/milestones.md) ; /deliver <feature> sans --milestone livre tous ses PBI. Un PBI dont le bloqueur est encore ouvert et pas dans l'ensemble attend et est signalé (un bloqueur en dehors du milestone n'est jamais livré). Un PBI ou Bug avec needs-refinement, ou un Bug sans repro ou critères d'acceptation, est ignoré (#<nr> select : needs refinement, skipped, indice planner refine <nr>) ; /deliver <nr> sur un tel élément le refuse. En non supervisé, un PBI avec interactive est ignoré (#<nr> select : interactive, skipped, indice /deliver <nr> dans une session) ; le mode interactif le livre, également via une Feature, un Epic ou un milestone. Un PBI ouvert avec release-test (le test RC du milestone) n'est jamais sélectionné comme travail, pas dans les étapes 1 à 8 et pas dans la session de contrôle, ni avec interactive ni comme <nr> explicite : #<nr> select : release test, left for step 9 (avec des éléments ouverts avant : release test, waits for <n> open items ; en attente, pas besoins de vous ; references/loop.md). Il reste ouvert pour l'étape 9 et l'humain (le test RC s'exécute sur le RC). Ignorer un PBI qu'une autre session a réclamé (#<nr> select : claimed, skipped), reprendre une réclamation périmée (references/claim.md) ; /deliver <nr> sur le PBI lui-même le continue indépendamment de la réclamation. Annoncer le prochain PBI et le réclamer : gh issue edit <nr> --add-assignee @me ; la ligne de sélection nomme son niveau et son modèle (#<nr> select : next (tier standard → sonnet/medium) ; sans ligne Tier: tier from size M ou default ; references/roles.md).
   • Un enfant Feature ou Epic sans PBI : charger planner (interactif) et grill-me dans cette session, créer les problèmes, puis sélectionner à nouveau. En non supervisé : commenter et étiqueter needs-decision à la place.
2. Reprendre. Branche <type>/<nr>-<slug> (github-issue). git ls-remote --heads origin <branche> et gh api "repos/{owner}/{repo}/pulls?head=<owner>:<branche>&state=open" --jq '.[].number' (la tête a besoin du préfixe propriétaire) : une branche existante est continuée, une PR existante passe à l'étape 7.
3. Implémenter. Un sous-agent avec un contexte frais : "Charge implementation, rôle implement. Implémente le PBI # (un Bug : charge diagnose d'abord, puis implementation) dans ton propre worktree sur <branche> à partir de origin/release/next (une branche existante : bascule dessus et rebase). Critères d'acceptation : <depuis le problème>. Commit, push, rapporte en au plus 10 lignes : fait ou bloqué, commits, tests exécutés, et notes[] (une par ligne) ; une entrée specMap correspondante sans changement de spec donne la note no spec change needed: <spec> — <raison> (implementation references/specs.md)."
4. Réviser. Un sous-agent avec un contexte frais : "Charge code-review, rôle review. Passe en revue git diff origin/release/next...origin/<branche> par rapport à ces critères d'acceptation : <critères>. Avec governance : exécute Get-GovernanceMatches.ps1 -Head origin/<branche> ; étiquettes de problème <étiquettes> et notes de l'implémenteur notes[] . Lecture seule : pas de stash, checkout, switch ou commit dans aucun checkout existant ; si tu as besoin de fichiers, utilise ton propre worktree temporaire. Retourne uniquement du JSON : le résultat par review.schema.json de code-review (blocking[] avec file, line, title, why ; notes[], jusqu'à 5) plus unmet[] (critères non satisfaits)." Seuls les résultats bloquants et les critères non satisfaits comptent. Après chaque tour, cette session (pas le sous-agent) écrit le fichier <git-common-dir>/.agents/state/review-<nr>.json (git rev-parse --git-common-dir, le même fichier depuis chaque worktree, jamais commité), écrasant le tour précédent : { pbi, branche, sha, round, unmet, review }, sha = git rev-parse origin/<branche>, round = tour de révision basé sur 1, review = le résultat du sous-agent ; schéma schema/deliver-review.schema.json. Aussi pwsh <skill-dir>/../code-review/scripts/ConvertTo-Findings.ps1 -Review <résultat avec unmet> -Sha <sha> -Worktree <pbi-worktree> écrit <pbi-worktree>/.agents/state/findings.json pour poimen (jamais commité, exclu localement ; references/findings.md).
5. Corriger. Quelque chose compte : un sous-agent avec un contexte frais charge implementation avec le rôle fix, bascule son propre worktree sur <branche> (git fetch origin <branche>, git switch -C <branche> origin/<branche>), obtient exactement ces résultats (blocking[] et unmet[]), commit et push. Puis étape 4 à nouveau. Au maximum 2 tours de correction par PBI, partagés par la révision et la CI ; un troisième est une pause.
6. PR. github-pull-request (son titre est le titre du problème sans le préfixe de niveau, (#<nr>) ajouté) avec issue_number, branch: <branche> (le travail est poussé depuis un autre worktree, ce checkout reste tel quel), review_notes (notes[] de l'étape 4), avec governance spec_notes (les lignes notes[] de l'implémenteur commençant par no spec change needed:) et le résultat du test du sous-agent.
7. CI. Exécuter gh pr checks <pr> --watch --required --interval 60 directement (chaque interrogation est une requête GraphQL ; la valeur par défaut de 10 s draine le budget), sans pipe ni filtre de sortie (comme tail, head ou grep), pour que la progression de la surveillance atteigne la session.
   • Rouge à cause de ce changement (erreur de test, lint ou build dans les fichiers du diff) : tour de correction (étape 5), puis étapes 4 et 7 à nouveau.
   • Rouge pour une autre raison (instable, rouge aussi sur release/next) : commenter sur la PR, le PBI est bloqué.
8. Fusionner. Sans demander, dans les deux modes : la dernière révision n'avait aucun résultat bloquant ni critère non satisfait et les vérifications requises sont vertes. gh pr merge <pr> --squash --delete-branch, puis gh issue close <nr> --comment "Delivered in #<pr>" (Closes ne se déclenche pas sur release/next) ; les sous-problèmes [Task] legacy ouverts du PBI sont fermés avec lui (github-issue references/sub-issues.md, "Problèmes de tâche legacy") ; puis gh issue edit <nr> --remove-assignee @me. Nettoyer les worktrees et les branches des sous-agents avec le script de cette compétence, scripts/Remove-PbiWorktrees.ps1 dans le répertoire de la compétence (~/.claude/skills/deliver/ global, .claude/skills/deliver/ installation de projet), exécuté depuis le dépôt : pwsh <skill-dir>/scripts/Remove-PbiWorktrees.ps1 -Pr <pr> -Issue <nr> ; afficher #<nr> cleanup : <n> removed et conserver ses entrées left (chemin ou branche, raison, commande) pour le rapport. PBI suivant : étape 1.
9. Release. Uniquement avec --milestone, avant le rapport (aussi après --max), lorsqu'aucun PBI n'est plus à sélectionner. Lire le milestone une fois, Get-Milestones.ps1 -Mode issues -Name <nom> -State all (ouverts et fermés) ; la vérification d'ouverts, le marqueur, le nombre de tours et les critères des problèmes fermés viennent de cette liste. Aucun problème ouvert étiqueté pbi ou bug dedans sauf le problème release-test (rien de bloqué, en pause, en attente ou ignoré) ; le test RC ne bloque jamais.
   • Un PBI ou Bug fermé du milestone étiqueté needs-decision est le marqueur de pause d'un tour 3 de revue de release : ignorer la revue, afficher release : paused in round 3, waits for a decision.
   • Revue de release (references/release-review.md) : un sous-agent avec un contexte frais charge code-review, rôle review, sur git diff origin/main...origin/release/next avec les critères d'acceptation des PBI et Bugs fermés du milestone, focus sur la cohérence entre PBI, et retourne du JSON par review.schema.json, lecture seule (pas de stash, checkout, switch ou commit dans aucun checkout existant ; propre worktree temporaire s'il a besoin de fichiers) ; cette session écrit <git-common-dir>/.agents/state/release-review-<key>.json.
   • Résultats bloquants : un problème [Bug] fix : … par résultat dans le milestone (interactif : les montrer et demander d'abord), pas de PR de release ; afficher release : <n> blocking → #a, #b. Au maximum 2 tours de revue de release par milestone ; un troisième avec des résultats bloquants est une pause, enregistrée avec ce marqueur et un commentaire nommant les deux voies (references/release-review.md, "Marqueur de pause").
   • Propre (aucun bloquant) : couper le RC, le poster sur le problème release-test et fermer les plus anciens (references/release-review.md, "Test RC") ; release.test.gate : true s'arrête là avec needs you : RC test <URL du problème> jusqu'à ce que le problème soit fermé. Sinon charger github-release et exécuter finish avec release_review_notes (les notes[], jusqu'à 5) : il ouvre la PR de release de release/next dans main (auto_merge : false) ou rapporte celle existante ; il s'arrête quand main n'est pas un ancêtre de release/next (d'abord rétromerger, github-release), rapporter cet arrêt. Afficher release : PR #<nr> (<quota de stratégie>) et, si auto_merge est vrai, released ; la session ne la fusionne pas. La PR de release est l'étape 9, pas le résumé de la fin de la boucle.

Pause et PBI suivant

Après chaque PBI, avant le suivant, exécuter pwsh <skill-dir>/scripts/Test-PauseRule.ps1 -Harness <harnais> -Milestone <nom> ; le résultat de la sortie standard contient needs_you quand la règle a besoin de l'utilisateur. En interactif, demander "Continuer, un autre PBI, un problème à corriger, un écrit, le rapport ou la release ?" (references/pause.md). En non supervisé, avec needs_you : marquer pause, commenter l'état, étiqueter needs-decision et arrêter. Sinon, avec session_prompt de Test-PauseRule.ps1 : arrêter. Les décisions de pause, la sortie et les arrêts après --max passent par le rapport.

Ensuite, sélectionner le prochain PBI (étape 1) ; si le PBI suivant est à la fois dernier et ne peut pas être sélectionné (tous ignorés), la boucle imprime No more PBIs to deliver et passe à l'étape 9.

Rapport

Toujours après la dernière boucle, ou sur /deliver status, imprimer un bloc de rapport :

## Status block
### Deliveries
| PBI | Status |
| :-- | :----- |
| <nr> | <done/blocked/paused/skipped> |
…
<details>
<summary>Remaining worktrees</summary>
<adresse> <branche> <raison> <commande>
…
</details>

(references/findings.md pour les statuts de sortie). pwsh <skill-dir>/scripts/Invoke-DeliverLoop.ps1 -Result imprime le rapport après les 9 étapes ou avec --max. Le bloc peut être commenté sur le problème.

Voir aussi

• references/: help.md, loop.md, control.md, preflight.md, permissions.md, pause.md, terminal-backends.md, findings.md
• github-issue references/sub-issues.md, references/milestones.md
• github-release
• implementation, code-review
• planner, grill-me