diff --git a/AGENTS.md b/AGENTS.md index c42c5f658..9d839f572 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,11 @@ Safety-critical type-1 hypervisor (ARMv7 primary, AArch64/RISC-V in progress) implementing PikeOS 5.0 patterns. +## ULTRA RULE — READ FIRST, ALWAYS + +**DEBUG IS YOUR ONLY OPTION. You NEVER run code outside of a debug session. EVER.** +Every execution — QEMU or hardware, any test, any boot — runs with GDB attached (or the GDB stub active and driving the session). No exceptions. No "quick runs". No serial-only observations. If the target executes, a debugger is controlling it. + ## ABSOLUTE RULES — READ BEFORE DOING ANYTHING ### LESSONS LEARNED — 2026-07-17 Incident (All Errors Committed) @@ -60,7 +65,9 @@ Safety-critical type-1 hypervisor (ARMv7 primary, AArch64/RISC-V in progress) im 9. **Se o utilizador disser PARA, PÁRA.** Não faças mais mudanças. Não "fixes" sem permissão. Espera instruções. -10. **GDB/GDB STUB É OBRIGATÓRIO EM TODOS OS TESTES.** Sempre que correres QEMU ou testes em hardware (especialmente ESP32), deves usar GDB com GDB stubs. Isto aplica-se a: +10. **ULTRA RULE — NUNCA corras código fora de uma sessão de debug. SEMPRE.** Qualquer execução de código — hardware ou QEMU, teste ou validação, bootloader, kernel, ou app — TEM de correr com GDB attached (GDB stub, JTAG/OpenOCD, ou QEMU `-s -S`). Não há exceções. Se o código corre sem debugger, é uma violação da regra. "Debug é a tua única opção." Ver detalhes na secção "Verification Workflow" abaixo. + +10a. **GDB/GDB STUB É OBRIGATÓRIO EM TODOS OS TESTES.** Sempre que correres QEMU ou testes em hardware (especialmente ESP32), deves usar GDB com GDB stubs. Isto aplica-se a: - **QEMU:** `qemu-system-* -s -S` (GDB stub na porta 1234). O GDB attach é feito com `target remote :1234`. - **ESP32 hardware:** O GDB stub integrado (em `microkernel/ports/esp32/uos_gdbstub.c`) é ativado pelo `break 0,0` em `_start`. Comunicação via UART0 a 115200 usando o protocolo RSP (Remote Serial Protocol). - **Bootloader bring-up:** Usar GDB para single-step, ler registos, e verificar estado em cada etapa da cadeia de boot.