Dépannage

Problèmes courants#

CLI ou App ne trouve pas le coordinateur ou un spécialiste#

Vérifiez que hve-squad et hve-squad-hve-core sont tous deux installés dans le répertoire de plugins du client actuel. Sélectionnez l'agent coordinateur, et non un skill, puis demandez squad-doctor. Suivez le guide du plugin pour les domaines manquants et les réinstallations du compagnon. Une mise à jour depuis le terminal ne met pas à jour une application utilisant un autre COPILOT_HOME.

Exactement 11 dépendances échouent pendant apm install#

Il s'agit d'une régression connue d'APM, et non d'un problème de réseau ou d'environnement du projet. Les résultats des tests de compatibilité sont les suivants :

Épinglez APM CLI 0.29.0, supprimez l'état partiel des dépendances et réinstallez le package HVE Squad. La version épinglée du CLI est distincte de celle du package dans Peter-N91/hve-squad#vX.Y.z.

Windows (PowerShell)

# 1. Install the required APM CLI version.
$env:VERSION = 'v0.29.0'; irm https://aka.ms/apm-windows | iex

# 2. Verify it. Open a new terminal first if this still reports another version.
apm --version

# 3. From the affected project root, remove the partial APM state.
Set-Location C:\Temp\myapp
Remove-Item -Recurse -Force apm_modules, apm.lock.yaml, apm.yml -ErrorAction SilentlyContinue

# 4. Reinstall the HVE Squad release you need.
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

macOS (Apple Silicon ou Intel)

# 1. Remove the Homebrew copy if it is installed; the pinned installer cannot overwrite it.
brew uninstall apm

# 2. Install the required APM CLI version.
curl -sSL https://aka.ms/apm-unix | sh -s -- @v0.29.0

# 3. Make the install visible to this shell and verify it.
export PATH="$HOME/.local/bin:$PATH"
hash -r
apm --version

# 4. From the affected project root, remove the partial APM state and reinstall.
cd /path/to/myapp
rm -rf apm_modules apm.lock.yaml apm.yml
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Ajoutez export PATH="$HOME/.local/bin:$PATH" à ~/.zshrc pour conserver le chemin après la réouverture du terminal. Pour une installation isolée, utilisez uv tool install apm-cli@0.29.0.

Pour la version d'atelier qui a révélé ce problème (v0.16.2), une installation saine affichait Installed 302 APM dependencies après environ une à deux minutes. Les versions HVE Squad ultérieures peuvent afficher un nombre de dépendances différent.

La première exécution d'apm install prend plus de 30 minutes (sans jamais signaler d'erreur)#

Il s'agit presque toujours de la limitation du débit de l'API GitHub. Ce package référence des centaines de fichiers individuels de microsoft/hve-core, et APM récupère chacun d'eux via HTTP sur GitHub. Les appels non authentifiés sont limités à 60 requêtes par heure ; une fois cette limite atteinte, APM attend la réinitialisation de la fenêtre (en respectant l'en-tête Retry-After de GitHub) puis continue : l'installation avance donc très lentement au lieu d'échouer. Sur une nouvelle machine, le cache APM est également vide, et chaque fichier doit être récupéré.

Authentifiez-vous avant l'installation pour porter la limite à 5 000 requêtes par heure :

gh auth login            # recommended — APM picks it up automatically
# or set a token (public read is enough; hve-core is public)
$env:GITHUB_TOKEN = "ghp_xxx"
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

L'ordre de priorité des jetons GitHub dans APM est GITHUB_APM_PAT_<ORG> → GITHUB_APM_PAT → GITHUB_TOKEN → GH_TOKEN → gh auth token → votre assistant d'identifiants Git. Une fois authentifiée, l'installation se termine rapidement, et le cache désormais alimenté rend les installations suivantes quasi instantanées.

Augmenter --parallel-downloads n'aide pas une installation non authentifiée — la limite est horaire, donc davantage de parallélisme ne fait que l'atteindre plus vite.

Quelques packages échouent avec HTTP 502 (ou 503) — Failed to download virtual package#

[x] 2 packages failed:
    +- hve-core-github-execute-backlog -- Failed to download virtual package:
       Failed to download .github/prompts/github/github-execute-backlog.prompt.md: HTTP 502

Il s'agit d'une erreur temporaire du serveur GitHub, pas d'un problème de manifeste ou de références épinglées. 502 Bad Gateway (et 503) signifient que le point de terminaison de fichiers de GitHub n'a brièvement pas répondu pendant qu'APM récupérait l'un des centaines de fichiers individuels référencés par ce package. L'indice révélateur de son caractère temporaire : seuls quelques packages échouent alors que les autres réussissent, et l'échec survient à l'étape de téléchargement alors que la référence épinglée a bien été résolue.

Relancez simplement l'installation — les fichiers en cache sont ignorés, donc seuls les packages manquants sont retentés :

apm install

Ne confondez pas ce cas avec 404 / "File not found (tried refs: main, master)", qui signifie qu'un fichier n'existe plus à cette référence (dérive en amont ou mauvaise référence épinglée), ni avec le cas de limitation de débit décrit plus haut, lent mais sans erreur. Si les erreurs 502 persistent après plusieurs tentatives, GitHub lui-même peut subir une dégradation de service — consultez githubstatus.com. S'authentifier d'abord (gh auth login) rend également les installations plus résilientes.

[x] No harness detected après apm install (APM 0.18.0 et versions ultérieures)#

APM a téléchargé les sources dans apm_modules/ mais a ignoré l'étape de déploiement, car aucun marqueur d'environnement n'a été trouvé dans votre projet (pas de .github/agents/, .github/prompts/, .claude/, .cursor/, etc.). Relancez avec --target copilot :

apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Vous pouvez aussi ajouter un bloc targets: au fichier apm.yml de votre projet pour que les prochaines installations fonctionnent sans cette option (voir Bien démarrer → Option B).

apm_modules/ contient des fichiers mais .github/ est vide, sans erreur visible#

La cause est la même que ci-dessus — remontez dans votre terminal pour trouver le message No harness detected et appliquez le correctif --target copilot.

Aucun script trouvé#

Vérifiez le bloc scripts dans apm.yml et exécutez apm list.

Échecs d'accès à HVE Core#

Vérifiez l'authentification Git et la visibilité du dépôt.

Les dépendances semblent obsolètes#

Exécutez apm run sync-deps, puis apm lock.

Un rôle ne produit jamais son artefact, ou le coordinateur « réaiguille » discrètement vers un autre agent#

Symptômes : une étape se déclare bloquée mais l'exécution continue malgré tout ; aucune entrée history/<agent>.md pour ce rôle ; les contrôles ultérieurs passent sans preuve. La cause habituelle est une ligne de l'équipe dont l'agent principal (Primary) ne peut pas accepter une délégation limitée au périmètre du rôle — soit l'agent n'est plus déployé après une mise à niveau de HVE Core, soit il s'agit d'un agent de travail délégué qui refuse d'agir sans contrat d'entrée complet. Les deux cas se présentent de la même façon à l'exécution.

Comparez l'agent Primary du rôle dans .copilot-tracking/squad/team.md au catalogue des agents dans references/roster-catalog.md du skill squad, et vérifiez que le fichier de l'agent existe sous .github/agents/. Le fichier squad-roster.instructions.md du skill squad contient toujours les règles de délégation et de sécurité. Une ligne dont l'agent Primary ne peut pas écrire dans la racine des livrables (Deliverable Root) du rôle est toujours incorrecte. Après toute montée de version de hve-core, relancez apm install et comparez les agents avec scripts/Get-HveCoreCastDelta.ps1.

Problèmes liés au plafond de coût#

Une nouvelle squad s'est initialisée avant d'afficher le résultat de son contrôle préalable des coûts#

C'est le comportement attendu. L'initialisation échappe au contrôle d'admission, car elle crée les fichiers d'état et de tarifs nécessaires à l'estimation. La délégation au Scribe pour la configuration est tout de même comptabilisée dans les dépenses estimées, mais ne consomme aucun créneau du plafond. Le plafond fourni s'applique à la demande initiale avant sa première délégation de travail après l'initialisation.

L'exécution s'arrête avec over-ceiling avant le début de l'implémentation#

Il s'agit d'une décision fondée sur une prévision, et non d'une preuve que le montant a déjà été facturé. Le contrôle préalable des coûts (Cost Preflight) chiffre le manifeste des délégations prévues, applique la calibration admissible et multiplie l'estimation ponctuelle par le facteur de réserve prudent de 3.0 pour l'admission. Ouvrez la référence de décision (Decision Ref) dans le message du contrôle et examinez le tableau de demande de ## Cost Preflight dans .copilot-tracking/squad/decisions.md. L'estimation actuelle figure dans consumption.md ; les tarifs et la calibration se trouvent dans consumption-rates.md.

Avec un niveau de confiance moyen et des dépenses estimées cumulées encore inférieures au plafond, vous pouvez arrêter ou approuver une poursuite bornée. Avec cannot-confirm, corrigez d'abord le modèle non résolu, le tarif manquant, la demande incomplète, le tableau invalide ou la calibration obsolète. L'approbation ne remplace pas les éléments probants que la prévision n'a pas pu établir. Consultez Contrôle d'admission par le coût.

Une demande ultérieure utilise encore l'ancien plafond de manière inattendue#

L'omission signifie héritage lorsque la demande poursuit la même exécution. Cela évite qu'un garde-fou disparaisse simplement parce qu'un prompt ultérieur ne le répète pas. Remplacez-le par une autre valeur positive, ou supprimez-le explicitement :

Un plafond de fédération apparaît dans chaque sous-squad sélectionnée#

C'est le contrat habituel de la fédération. Les demandes ciblées et celles passant par le méta-routage transmettent le même cycle de vie du plafond à chaque sous-squad sélectionnée, et chacune le compare à sa propre estimation cumulée. Un plafond agrégé partagé n'existe que pour le mode mode=autopilot sans cible. Ce mode utilise le fichier consumption-rates.md de la racine de fédération et n'applique pas une seconde fois le plafond dans les exécutions enfants.

/squad request="continue without a cost ceiling" cost-ceiling=unset

Un nouvel identifiant d'exécution sans valeur fournie démarre à l'état not-requested. Les plafonds ne sont pas transmis d'un identifiant d'exécution à un autre.

La dernière délégation a fait dépasser le plafond aux dépenses estimées#

Le contrôle s'applique entre les unités de délégation, car un appel de modèle en cours ne peut pas être arrêté en toute sécurité et sa transmission au Scribe doit consigner la consommation. Le coordinateur enregistre le total actualisé, consigne un cycle terminal over-ceiling et ne lance aucun agent enfant supplémentaire. Ce dépassement borné est attendu.

L'exécution n'est pas bloquée définitivement. Fixez un nouveau plafond supérieur à l'estimation actuelle, utilisez cost-ceiling=unset, réduisez ou rechiffrez la demande restante, ou démarrez une nouvelle exécution. Réapprouver la valeur déjà dépassée n'est pas autorisé, car cette valeur ne peut plus servir de limite d'arrêt.

Un plafond de 10 USD provoque un arrêt immédiat après une demande précédente sans contrôle ayant dépensé 10,80 USD#

Un plafond ajouté à une exécution existante est comparé à l'estimation cumulée de cette exécution, et pas seulement à la demande la plus récente. Le budget restant est max(0, 10.00 - 10.80) = 0.00, donc aucune nouvelle délégation ne démarre. Relevez ou supprimez le plafond, ou démarrez une nouvelle exécution si la nouvelle demande doit disposer d'une limite budgétaire indépendante.

.github apparaît encore dans l'état Git après son ajout aux exclusions#

Exécutez une fois git rm -r --cached .github, puis git add .github/workflows (si vous suivez les workflows ici), puis créez un commit.

Les diagrammes avec icônes Azure (HLD/LLD) ne se génèrent pas#

Lorsque le Squad Azure Architect produit un PNG/SVG enregistré dans Git avec de véritables icônes Azure via le skill python-diagrams, le rendu nécessite à la fois Python et le binaire dot de Graphviz. Sur un poste de développement Windows classique, deux éléments le bloquent souvent :

• python est le lanceur factice du Microsoft Store. Exécuter python affiche "Python was not found" et ne fait rien. Utilisez le lanceur py, ou, mieux, uv — qui fournit son propre Python et le package diagrams, même si aucun des deux n'est dans PATH :
  Copier

  uv run --with diagrams python docs/architecture/your-diagram.py

• Graphviz est installé mais absent de PATH. Le rendu échoue avec ExecutableNotFound / "dot not found". Installez-le et rouvrez le shell, ou ajoutez son chemin en tête de PATH pour la session :
  Copier

  winget install Graphviz.Graphviz   # then reopen the terminal
  # or, for the current session only:
  $env:PATH = "C:\Program Files\Graphviz\bin;$env:PATH"

Avant de créer un diagramme, vérifiez la chaîne d'outils avec le contrôleur du skill : uv run --with diagrams python .github/skills/python-diagrams/scripts/verify_installation.py. Si le diagramme ne se génère toujours pas et que vous avez seulement besoin d'un visuel rapide, l'architecte se rabat automatiquement sur un diagramme Mermaid intégré.

Gestion des versions#

• Les versions suivent le versionnement sémantique.
• Consultez CHANGELOG.md pour connaître le contenu de chaque version.
• Les utilisateurs peuvent épingler une version étiquetée, par exemple apm install "Peter-N91/hve-squad#vX.Y.z".
• Les versions sont publiées manuellement lorsque les travaux en attente sont jugés prêts, et non selon un calendrier.
• Entre les versions, tout ce qui a déjà été fusionné est installable depuis une préversion glissante : consultez le tag de préversion actuel et la commande d'installation. Ce tag change à chaque fusion : il sert donc aux tests, et non aux travaux dont vous dépendez. Une préversion n'apparaît jamais comme Latest.
• Une installation sans aucune référence pointe vers la branche par défaut, pas vers la dernière version publiée, et APM avertit du risque de dérive. Épinglez toujours une version.

Notes#

• .gitignore exclut apm_modules/ et les ressources générées dans .github, tout en conservant le suivi de .github/workflows/.
• Le package reste reproductible grâce à apm.lock.yaml.