Test automation v1: theseus-qemu test, kernel test runner, TDD workflow

AGENTS.md

@@ -404,6 +404,13 @@ This section captures real failure modes that have happened working on TheseusOS
 - **GDB requires section delta computation.** The kernel is relocated to higher-half. GDB symbols need offset adjustment. Use `gdb-auto.py` / `make debug-auto` rather than raw GDB — the automation handles section deltas from `BOOTX64.SYM`.
 - **`make run` is headless.** `make run-headed` opens a QEMU window. Use headless for CI/automated runs, headed when you need to see framebuffer output.
 
+### Test automation
+
+- **`theseus-qemu test`** runs all kernel tests and returns a structured exit code: 0=PASS, 1=FAIL, 2=PANIC, 3=TIMEOUT. No output parsing needed.
+- **TDD workflow is mandatory:** baseline (confirm existing tests PASS) → write test → confirm test FAILS on clean build → implement → confirm test PASSES + no regressions.
+- **The test is the truth.** Once a test is written and confirmed-failing, it is frozen. Do not redefine success criteria or stub the test — report blockers honestly.
+- **`.test-output.log`** is saved on any non-PASS exit for inspection.
+
 ### Verify your work
 
 Before opening a PR on any non-trivial change:

Makefile

@@ -200,3 +200,63 @@ debug-build:
 	@echo "Running debug build and creating ESP image..."
 	$(MAKE) PROFILE=debug build esp
 
+# Run kernel tests: builds with kernel-tests feature, boots QEMU headless, reports verdict.
+# Exit codes: 0=PASS, 1=FAIL, 2=PANIC, 3=TIMEOUT
+# Use --print to see full QEMU output on failure.
+# Use --timeout <secs> to override the default 60s timeout.
+.PHONY: test test-fail test-panic test-hang test-all-verdicts
+test:
+	cargo run -p theseus-qemu -- test
+
+# Test FAIL scenario: one test intentionally fails → expects exit 1
+test-fail:
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-fail
+
+# Test PANIC scenario: one test intentionally panics → expects exit 2
+test-panic:
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-panic
+
+# Test TIMEOUT scenario: kernel hangs in infinite loop → expects exit 3
+test-hang:
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-hang --timeout 5
+
+# Run all four verdict scenarios and report results.
+# Each is a separate build (the feature changes kernel compilation).
+test-all-verdicts:
+	@echo "=== Testing PASS verdict ==="
+	cargo run -p theseus-qemu -- test && \
+		echo "✓ PASS: exit code $$?" || \
+		( echo "✗ FAIL: expected PASS (exit 0)" && exit 1 )
+	@echo ""
+	@echo "=== Testing FAIL verdict ==="
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-fail; \
+		status=$$?; \
+		if [ "$$status" -eq 1 ]; then \
+			echo "✓ FAIL: exit code $$status"; \
+		else \
+			echo "✗ FAIL: expected exit 1, got $$status"; \
+			exit 1; \
+		fi
+	@echo ""
+	@echo "=== Testing PANIC verdict ==="
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-panic; \
+		status=$$?; \
+		if [ "$$status" -eq 2 ]; then \
+			echo "✓ PANIC: exit code $$status"; \
+		else \
+			echo "✗ FAIL: expected exit 2, got $$status"; \
+			exit 1; \
+		fi
+	@echo ""
+	@echo "=== Testing TIMEOUT verdict ==="
+	cargo run -p theseus-qemu -- test --features kernel-test-scenario-hang --timeout 5; \
+		status=$$?; \
+		if [ "$$status" -eq 3 ]; then \
+			echo "✓ TIMEOUT: exit code $$status"; \
+		else \
+			echo "✗ FAIL: expected exit 3, got $$status"; \
+			exit 1; \
+		fi
+	@echo ""
+	@echo "=== All 4 verdicts verified successfully ==="
+

bootloader/Cargo.toml

@@ -19,6 +19,10 @@ volatile = { workspace = true }
 linked_list_allocator = { workspace = true }
 raw-cpuid = { workspace = true }
 
-# features removed; new_arch is unconditional now
+[features]
+kernel-tests = ["theseus-kernel/kernel-tests"]
+kernel-test-scenario-fail = ["theseus-kernel/kernel-test-scenario-fail"]
+kernel-test-scenario-panic = ["theseus-kernel/kernel-test-scenario-panic"]
+kernel-test-scenario-hang = ["theseus-kernel/kernel-test-scenario-hang"]
 
 # Release profile defined in workspace root

docs/agent-prompt-template.md

@@ -29,6 +29,20 @@ CONSTRAINTS:
 - Do not add driver_data raw pointer casts — they are being replaced (see AGENTS.md §14)
 - All VA regions are hardcoded constants — do not invent dynamic mappings
 
+TESTING (Mandatory TDD Workflow):
+1. **Baseline:** `theseus-qemu test --headless` → exit 0 (PASS)
+2. **Define:** Write test(s) asserting the feature's success criteria
+3. **RED:** `theseus-qemu test --headless` → exit 1 (FAIL) — confirm the new test fails on clean code
+4. **Implement:** Write the feature code. Do NOT change the test.
+5. **GREEN:** `theseus-qemu test --headless` → exit 0 (PASS) — all tests pass
+6. **Report:** `Verdict: PASS (exit code 0)`
+
+Guarails:
+- If a test PASSES at step 3, the test is too loose or the feature already exists.
+- If a test FAILS after implementation, do NOT redefine the test's success criteria.
+  The test is the truth. Fix the implementation.
+- Tests are committed before implementation code. Always.
+
 VERIFICATION — do all of these before declaring done:
 1. `cargo run -p theseus-qemu -- --headless` boots cleanly with no new ERRORs or WARNs
 2. [task-specific check, e.g. "APIC timer still fires", "keyboard events still arrive", "memory monitor shows sane state"]

docs/map.md

@@ -115,6 +115,17 @@ This file is meant to be a maintenance surface, not polished prose: if a module
 - `docs/archive/driver-systems-deep-dive.md`
 - `tools/theseus-qemu/src/main.rs`
 
+### `plans/agent-test-automation.md`
+
+- `docs/plans/testing.md`
+- `tools/theseus-qemu/src/main.rs`
+- `Makefile`
+- `kernel/src/testing.rs`
+- `kernel/src/environment.rs`
+- `kernel/Cargo.toml`
+- `bootloader/Cargo.toml`
+- `shared/src/constants.rs`
+
 ## Modules → Governing Plans
 
 ### Boot / handoff
@@ -266,6 +277,9 @@ This file is meant to be a maintenance surface, not polished prose: if a module
 - `kernel/src/display.rs`
 - `kernel/src/framebuffer.rs`
 - `kernel/src/bootlogo.rs`
+- `kernel/src/testing.rs`
 - `docs/development-and-debugging.md`
 - `docs/logging.md`
 - `docs/qemu-runner.md`
+- `docs/plans/testing.md`
+- `docs/plans/agent-test-automation.md`