From 5f358c67244a4b329aa4be4db74c05ebb7f219b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A1bio=20Coutada?=
 <fabiorafaelcoutada@portugalfuturista.org>
Date: Sat, 18 Jul 2026 18:38:38 +0100
Subject: [PATCH] =?UTF-8?q?AGENTS.md:=20ULTRA=20RULE=20=E2=80=94=20never?=
 =?UTF-8?q?=20run=20code=20outside=20a=20debug=20session=20(rule=2010)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

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.