Kemerd/hardware-in-the-loop

Hardware in the loop

Você está configurando (ou executando) um projeto de hardware onde agentes fazem a engenharia e portões de verificação a comprovam. Leia este arquivo inteiro antes de agir. O método está descrito no diretório docs/ do repositório (METHOD, PCB, CAD, FIRMWARE, SIM, SWARM, TOOLS, LESSONS); este arquivo é o procedimento.

0. Diga o custo primeiro

Antes de qualquer outra coisa, informe ao usuário, claramente:

Executar este método com um enxame de agentes é caro. No projeto de onde ele veio, um dia de enxame queimou de 4 a 5 milhões de tokens, principalmente ao acordar agentes de linha que cada um carregava de 300 a 800 mil tokens de contexto. O modo mais barato é uma sessão única sem subagentes que funciona passo a passo, executa trabalhos longos de máquina em segundo plano e retoma de uma seção "Onde eu parei". Qual modo você deseja? (recomendado: sessão única)

Registre a resposta como mode (single ou swarm). Não crie nenhum subagente antes de o usuário escolher o modo swarm.

1. Entrevista de integração

Execute a entrevista em references/interview.md através do diálogo de perguntas: lotes de no máximo quatro perguntas, a opção padrão recomendada primeiro em cada pergunta. Quando uma pergunta não receber resposta, adote o padrão e escreva "padrão adotado" ao lado. Aborde: objetivo do projeto e definição de pronto, objetivos em ordem, orçamento, quantidades, material impresso padrão (náilon com fibra de carbono / PETG / PLA / alumínio usinado), fixação (insertos termofixos / rosqueamento direto / parafusos passantes), invólucro (selado / ventilado / aberto), folga mecânica, fornecedor de fabricação e montagem da PCB, família de microcontroladores, alimentação principal e pior transitório, classe da placa e revestimento, níveis de simulação (gêmeo nativo / Isaac Sim / Unreal) e a GPU, limites da máquina (limite de CPU padrão 90%, RAM livre para o sistema padrão 4 GB, piso de disco livre padrão 50 GB), local do arquivo, gatilho de uso (padrão 95%), decisões permanentes.

Materiais, fixação, vedação do invólucro e folga são DECISÕES DE PROJETO: nunca as escolha silenciosamente; pergunte, recomende, registre.

Escreva as respostas em answers.json no diretório .tmp/ do repositório de destino (esquema em references/interview.md).

2. Gerar o esqueleto

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

Ele copia templates/ (README_AGENT.md, PROJECT_STRUCTURE.md, REQUIREMENTS.md, README.md, CODING_RULES.md, .gitignore, .gitattributes, windows/ci.ps1 + windows/ci/ (grupos audit e pcb), tools/ (auditoria + portabilidade com uma base e arquivo de isenção vazios rastreados), 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, slots / detach / watch / trava de merge / merge-to-dev / promote / backup WIP / hook de transferência / scripts de linha de status) e .claude/settings.local.json (linha de status + hook PostToolUse)), preenche as variáveis do modelo, escreve harness/swarm/machine.env e harness/swarm/PLAN.md para o modo escolhido. Ele nunca sobrescreve um arquivo existente; compare arquivos mantidos manualmente e mescle o que for útil. --with-examples adiciona a placa de exemplo (um breakout de regulador LDO de 3,3 V de 2 camadas que executa cada etapa do pipeline) e o construtor de invólucro de exemplo com dois plug-ins.

Em seguida, preencha a tabela de decisões em pcb/DESIGN_STANDARDS.md seção 0 a partir das respostas.

3. Ferramentas

pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <uma pasta fora do perfil do usuário> [-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 fixado), OSS CAD Suite 2026-10-24 (SHA-256 fixado, apenas para projetos FPGA), um venv do CadQuery. Ele escreve <ToolsRoot>/hil_tools.env com HIL_FREEROUTING_JAR, HIL_JAVA, HIL_KICAD_CLI, HIL_CQ_PYTHON. Pergunte antes de instalar qualquer coisa em toda a máquina; execute -VerifyOnly primeiro e mostre ao usuário o que está faltando. Nada vai para o perfil do usuário.

4. Git: main e dev

No repositório de destino (pergunte antes de executar git em um repositório que já tenha histórico):

git init -b main            # quando ainda não é um repositório
git add -A && git commit -m "Esqueleto do projeto (método hardware-in-the-loop)"
git branch dev
git push -u origin main dev # quando um remoto existir

Use a identidade git configurada da máquina. Nenhuma linha de atribuição ou co-autores. Nunca force-push. Em seguida, execute a primeira passagem do CI e mantenha seu relatório como referência principal:

pwsh -File windows/ci.ps1 -Only audit

5. Armar o arnês

• .claude/settings.local.json conecta usage_statusline.py (linha de status, gatilho em HIL_HANDOFF_PCT) e handoff_hook.sh (PostToolUse). Prove o hook: touch harness/swarm/HANDOFF_SELFTEST, execute qualquer ferramenta, espere o contexto "hook está ativo", exclua o arquivo.
• Inicie o backup WIP em segundo plano: bash harness/swarm/detach.sh harness/swarm/wip_backup.sh .tmp/wip_backup.log.
• Verifique bash harness/swarm/locks/slot.sh status.
• A sessão principal é executada a partir do checkout principal (é onde harness/ reside); as edições acontecem em worktrees.

6. Trabalhando: modo sessão única (padrão)

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

1. Uma etapa numerada de cada vez, cada uma com o portão que a comprova.
2. Trabalhe em .claude/worktrees/main-work no swarm/main-work; commite, envie, execute merge_to_dev.sh após cada portão verde.
3. Trabalhos pesados: eval "$(bash harness/swarm/locks/slot.sh take <tipo> <você> "<trabalho>" <GB>)", libere depois.
4. Trabalhos longos: bash harness/swarm/detach.sh <cadeia.sh> <log> e imediatamente bash harness/swarm/watch.sh <log> como uma tarefa em segundo plano; continue com o próximo passo enquanto ele executa.
5. Perguntas ao proprietário: em lote, padrão recomendado primeiro; padrões adotados são escritos no plano.
6. Parando: anexe "## Onde eu parei" (feito com SHAs, trabalhos em execução com PIDs e logs, próximo passo exato).

7. Trabalhando: modo swarm

Siga docs/SWARM.md e references/wave-checklist.md:

1. Onda 1, reconhecimento: agentes somente leitura escrevem fatos verificados com âncoras arquivo:linha em harness/swarm/recon_<area>.md.
2. Onda 2, plano: PLAN.md (references/plan-template.md) com linhas, um proprietário por arquivo (mudanças entre linhas como arquivos de patch em harness/swarm/handoff/), adições de interface, números de aceitação; briefs.md com um resumo por linha (references/brief-template.md).
3. Onda 3, linhas em worktrees swarm/<nome>: Sonnet para trabalho mecânico (portas, codecs, renders, testes, docs), Opus para trabalho sutil (controle, física, geometria, integridade de sinal). Cada um retorna o relatório estruturado (references/structured-report.md).
4. Onda 4, céticos: agentes novos com apenas o diff e o relatório; audit_placeholders.py --changed-since origin/dev --fail-on-new, os grupos de CI da linha, três números verificados novamente.
5. Onda 5, integração: cada linha chega ao dev com merge_to_dev.sh (sempre, vermelho incluído, sob MERGE_LOCK); CI completo no dev com -Compare <relatório principal> -FailOn regressões; promote_dev.sh apenas com zero regressões.

Mantenha as linhas poucas e os resumos exatos; cada ativação de um agente de contexto grande custa dinheiro real.

8. Disciplina (ambos os modos)

• PCB: gerador-primeiro (docs/PCB.md). ERC 0/0, DRC 0 violações / 0 não conectado / 0 paridade nas severidades padrão, cada linha comprada verificada ao vivo, fab set + STEP + resultados JSON com SHA-256. Posicionamento manual por você é esperado quando o auto-posicionador falhar. Mais camadas são permitidas; relate a diferença de preço. Relaxar uma regra precisa de uma base citada.
• CAD: construtores + plug-ins; uma tabela de massa / estação / CG (cad/mass_cg_table.py) com cada mudança de peça; PNGs de ajuste e colisão (cad/render.py) em docs/cad_decisions/<data>/<tópico>/.
• Firmware: compilações fora da árvore, suítes de host com hil_check.h, cenários através da interface real, varreduras de semente, determinismo; pendente de hardware listado.
• Nenhum trabalho inacabado mostrado como concluído; constantes apenas de bancada recebem ids BENCH B-xx-nn.
• Máquina: slots, prioridade abaixo do normal, timeouts, nunca mate o que você não iniciou, nunca find a partir de uma raiz, verifique o disco primeiro, um trabalho Unreal / GPU por vez, nenhuma inicialização do Unreal enquanto o proprietário estiver na máquina.

9. Transferência e noturno

• Quando HANDOFF_NOW aparecer (o hook avisa), pare de iniciar trabalhos e siga sua instrução: commite, envie, libere, escreva harness/swarm/resume_<data>/RESUME_<data_hora>_<linha>.md (references/resume-doc.md).
• Antes de o proprietário sair para a noite: uma cadeia noturna em segundo plano e as perguntas da manhã (references/overnight-questions.md). A noite é executada com os padrões; registre cada padrão adotado.