hardware-in-the-loop

Hardware in the loop

Vous mettez en place (ou exécutez) un projet matériel où les agents font l'ingénierie et les portes le prouvent. Lisez ce fichier en entier avant d'agir. La méthode est décrite dans le dossier docs/ du dépôt (METHOD, PCB, CAD, FIRMWARE, SIM, SWARM, TOOLS, LESSONS) ; ce fichier est la procédure.

0. Dites le coût d'abord

Avant toute chose, dites à l'utilisateur, clairement :

Exécuter cette méthode avec un essaim d'agents est coûteux. Sur le projet dont elle est issue, une journée d'essaim a brûlé 4 à 5 millions de tokens, principalement en réveillant des agents de couloir qui transportaient chacun 300 à 800 000 tokens de contexte. Le mode le moins cher est une session unique sans sous-agents qui fonctionne étape par étape, exécute les longs travaux machine de manière détachée et reprend à partir d'une section « Là où je me suis arrêté ». Quel mode voulez-vous ? (recommandé : session unique)

Enregistrez la réponse comme mode (single ou swarm). Ne créez aucun sous-agent avant que l'utilisateur n'ait choisi le mode essaim.

1. Entretien d'intégration

Exécutez l'entretien dans references/interview.md via le dialogue de questions : lots d'au plus quatre questions, la valeur par défaut recommandée en premier pour chaque question. Lorsqu'une question n'obtient pas de réponse, prenez la valeur par défaut et écrivez « défaut pris » à côté. Couvrez : objectif du projet et définition du « fait », objectifs par ordre, budget, quantités, matériau imprimé par défaut (nylon carbone / PETG / PLA / aluminium usiné), fixation (inserts à chaud / taraudage / boulons traversants), boîtier (scellé / ventilé / ouvert), jeu mécanique, fabricant et assembleur de PCB, famille de microcontrôleurs, alimentation principale et transitoire la plus grave, classe et revêtement de la carte, niveaux de simulation (jumeau natif / Isaac Sim / Unreal) et le GPU, limites machine (limite CPU par défaut 90 %, RAM libre pour le système par défaut 4 Go, seuil d'espace disque libre par défaut 50 Go), emplacement d'archive, seuil d'utilisation (par défaut 95 %), décisions permanentes.

Les matériaux, la fixation, l'étanchéité du boîtier et le jeu sont des DÉCISIONS DE PROJET : ne les choisissez jamais en silence ; demandez, recommandez, enregistrez.

Écrivez les réponses dans answers.json dans le dossier .tmp/ du dépôt cible (schéma dans references/interview.md).

2. Générer le squelette

python -I <skill>/scripts/scaffold.py --answers <repo>/.tmp/answers.json --dest <repo> [--with-examples] [--dry-run]

Il copie templates/ (README_AGENT.md, PROJECT_STRUCTURE.md, REQUIREMENTS.md, README.md, CODING_RULES.md, .gitignore, .gitattributes, windows/ci.ps1 + windows/ci/ (groupes audit et pcb), tools/ (audit + portabilité avec une base de référence vide suivie et un fichier de dérogation), pcb/ (DESIGN_STANDARDS.md, tools/kicad_env.py, tools/board_pipeline.py, tools/distributor_verify.py), cad/ (cad_plugins.py, render.py, mass_cg_table.py), firmware/host_tests/hil_check.h, docs/bench/BENCH_REGISTER.md, docs/data/README.md, harness/swarm/ (AGENT_RULES, scripts de créneau / détachement / surveillance / verrou de fusion / fusion-vers-dev / promotion / sauvegarde WIP / hook de passation / ligne de statut) et .claude/settings.local.json (ligne de statut + hook PostToolUse)), remplit les variables de modèle, écrit harness/swarm/machine.env et harness/swarm/PLAN.md pour le mode choisi. Il n'écrase jamais un fichier existant ; comparez les fichiers conservés à la main et fusionnez ce qui est utile. --with-examples ajoute la carte exemple (un breakout régulateur LDO 3,3 V 2 couches qui exécute chaque étape du pipeline) et le générateur de boîtier exemple avec deux plugins.

Remplissez ensuite le tableau de décision dans pcb/DESIGN_STANDARDS.md section 0 à partir des réponses.

3. Outils

pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <un dossier en dehors du profil utilisateur> [-VerifyOnly]
bash <skill>/scripts/setup_tools.sh --tools-root <dir> [--verify-only]          # Linux

KiCad 10 (winget), Java 21 (winget), Freerouting 2.1.0 (SHA-256 épinglé), OSS CAD Suite 2026-10-24 (SHA-256 épinglé, uniquement pour les projets FPGA), un environnement virtuel CadQuery. Il écrit <ToolsRoot>/hil_tools.env avec HIL_FREEROUTING_JAR, HIL_JAVA, HIL_KICAD_CLI, HIL_CQ_PYTHON. Demandez avant d'installer quoi que ce soit à l'échelle de la machine ; exécutez d'abord -VerifyOnly et montrez à l'utilisateur ce qui manque. Rien ne va dans le profil utilisateur.

4. Git : main et dev

Dans le dépôt cible (demandez avant d'exécuter git dans un dépôt qui a déjà un historique) :

git init -b main            # quand ce n'est pas encore un dépôt
git add -A && git commit -m "Squelette du projet (méthode hardware-in-the-loop)"
git branch dev
git push -u origin main dev # quand un dépôt distant existe

Utilisez l'identité git configurée de la machine. Pas de lignes d'attribution ou de co-auteurs. Ne forcez jamais le push. Exécutez ensuite la première passe CI et conservez son rapport comme référence principale :

pwsh -File windows/ci.ps1 -Only audit

5. Armer le harnais

• .claude/settings.local.json câble usage_statusline.py (ligne de statut, seuil d'utilisation à HIL_HANDOFF_PCT) et handoff_hook.sh (PostToolUse). Prouvez le hook : touch harness/swarm/HANDOFF_SELFTEST, exécutez n'importe quel outil, attendez le contexte « le hook est actif », supprimez le fichier.
• Démarrez la sauvegarde WIP en détaché : bash harness/swarm/detach.sh harness/swarm/wip_backup.sh .tmp/wip_backup.log.
• Vérifiez bash harness/swarm/locks/slot.sh status.
• La session principale s'exécute à partir du checkout principal (c'est là que se trouve harness/) ; les modifications se font dans les arbres de travail.

6. Travail : mode session unique (par défaut)

Suivez harness/swarm/PLAN.md (issu de references/single-session-plan.md) :

1. Une étape numérotée à la fois, chacune avec la porte qui la prouve.
2. Travaillez dans .claude/worktrees/main-work sur swarm/main-work ; validez, pushez, exécutez merge_to_dev.sh après chaque porte verte.
3. Travaux lourds : eval "$(bash harness/swarm/locks/slot.sh take <type> <vous> "<travail>" <GB>)", relâchez après.
4. Travaux longs : bash harness/swarm/detach.sh <chaîne.sh> <log> et immédiatement bash harness/swarm/watch.sh <log> comme tâche d'arrière-plan ; continuez avec l'étape suivante pendant son exécution.
5. Questions au propriétaire : par lots, recommandé par défaut en premier ; les défauts pris sont écrits dans le plan.
6. Arrêt : ajoutez « ## Là où je me suis arrêté » (terminé avec SHA, travaux en cours avec PID et logs, prochaine étape exacte).

7. Travail : mode essaim

Suivez docs/SWARM.md et references/wave-checklist.md :

1. Vague 1, reconnaissance : les agents en lecture seule écrivent des faits vérifiés avec des ancres fichier:ligne dans harness/swarm/recon_<domaine>.md.
2. Vague 2, planification : PLAN.md (references/plan-template.md) avec des couloirs, un propriétaire par fichier (les modifications entre couloirs sous forme de fichiers de patch dans harness/swarm/handoff/), des ajouts d'interface, des nombres d'acceptation ; briefs.md avec un brief par couloir (references/brief-template.md).
3. Vague 3, couloirs dans les arbres de travail swarm/<nom> : Sonnet pour le travail mécanique (ports, codecs, rendus, tests, docs), Opus pour le travail subtil (contrôle, physique, géométrie, intégrité du signal). Chacun renvoie le rapport structuré (references/structured-report.md).
4. Vague 4, sceptiques : nouveaux agents avec le diff et le rapport uniquement ; audit_placeholders.py --changed-since origin/dev --fail-on-new, les groupes CI du couloir, trois nombres revérifiés.
5. Vague 5, intégration : chaque couloir atterrit sur dev avec merge_to_dev.sh (toujours, rouge inclus, sous MERGE_LOCK) ; CI complète sur dev avec -Compare <rapport principal> -FailOn regressions ; promote_dev.sh uniquement avec zéro régression.

Gardez les couloirs peu nombreux et les briefs précis ; chaque réveil d'un agent à grand contexte coûte de l'argent réel.

8. Discipline (les deux modes)

• PCB : générateur d'abord (docs/PCB.md). ERC 0/0, DRC 0 violations / 0 non connecté / 0 parité aux sévérités par défaut, chaque ligne achetée vérifiée en direct, jeu de fabrication + STEP + JSON de résultats avec SHA-256. Un placement manuel par vous est attendu lorsque le placeur automatique échoue. Plus de couches sont autorisées ; signalez la différence de prix. Assouplir une règle nécessite une base citée.
• CAO : constructeurs + plugins ; une table masse / station / CG (cad/mass_cg_table.py) avec chaque changement de pièce ; PNG d'ajustement et de collision (cad/render.py) dans docs/cad_decisions/<date>/<sujet>/.
• Firmware : constructions hors arbre, suites hôtes avec hil_check.h, scénarios via l'interface réelle, balayages de graines, déterminisme ; en attente de matériel listé.
• Aucun travail non fini présenté comme fini ; les constantes de bench uniquement obtiennent des IDs BENCH B-xx-nn.
• Machine : créneaux, priorité en dessous de la normale, délais d'attente, ne tuez jamais ce que vous n'avez pas démarré, jamais de find depuis une racine, vérifiez d'abord le disque, un seul travail Unreal / GPU à la fois, pas de lancement Unreal pendant que le propriétaire est à la machine.

9. Passation et nuit

• Lorsque HANDOFF_NOW apparaît (le hook vous le dit), arrêtez de commencer un travail et suivez son instruction : validez, pushez, relâchez, écrivez harness/swarm/resume_<date>/RESUME_<date_heure>_<couloir>.md (references/resume-doc.md).
• Avant que le propriétaire ne parte pour la nuit : une chaîne de nuit détachée et les questions du matin (references/overnight-questions.md). La nuit s'exécute avec les valeurs par défaut ; enregistrez chaque défaut pris.