qemu-boot-testing

name	qemu-boot-testing
title	QEMU Boot Testing
version	3
status	active
owners	[]
triggers	["QEMU","boot smoke","serial marker"]
prerequisites	["build-orchestration","debugging-investigation"]
related_docs	["TESTING.md","docs/development/qemu.md","tools/finnlib/qemu.py",".agents/runbooks/x86_64-debug-boot.md"]
category	Foundations
conditional_skills	[]
implementation_gates	[]
related_milestones	["M0 Reproducible Build","M1 Dual-Architecture Boot"]
last_verified	{"base_commit":"df5cf62","date":"2026-07-17","worktree_dirty":true,"context":"R3 ARM64 serial-first-boot worktree locally verified; integration CI pending"}
description	Use when working on QEMU, boot smoke, serial marker; provides the FinnOS-specific qemu boot testing workflow and evidence gates.

QEMU Boot Testing

1. Name

qemu-boot-testing (Foundations; skill maturity: operational).

2. Purpose

Build, boot, capture, and classify bounded emulator evidence.

3. When to use this skill

Use for requests mentioning QEMU, boot smoke, serial marker, or when a dependency points to this skill. Load only after repository entry and before design or implementation.

4. When not to use this skill

Do not use this skill as a substitute for its adjacent subsystem skills or for evidence that the subsystem works. Do not load it only because a future FinnOS document mentions the subsystem.

5. Prerequisite skills

• build-orchestration
• debugging-investigation

Read the full prerequisite closure in topological dependency order. If one cannot be satisfied, move the task to Blocked or Deferred; do not omit the dependency.

Conditional skills:

• None.

Implementation gates are roadmap/runtime conditions, not additional documents to load automatically:

• No additional gate beyond the selected roadmap acceptance criteria.

6. Authoritative repository references

• TESTING.md
• docs/development/qemu.md
• tools/finnlib/qemu.py
• .agents/runbooks/x86_64-debug-boot.md

Re-read implementation and tests referenced by those documents. The documents establish intent/status boundaries, not runtime proof.

7. Current FinnOS context

x86 q35/OVMF has eight development modes plus release first boot; ARM64 virt/AAVMF has a distinct locally verified R3 serial-entry test.

Registry verification used base commit df5cf62 plus the dirty worktree context "R3 ARM64 serial-first-boot worktree locally verified; integration CI pending" on 2026-07-17. This is not an integrated-revision claim. Reverify after HEAD, active PRs, or relevant source changes.

8. Required inputs

• User request or issue with desired outcome and architecture/profile scope.
• Current git status, recent history, active related issue/PR, and selected roadmap item.
• Relevant implementation, tests, invariants, ADRs, and exact baseline output.
• Toolchain/firmware/hardware versions when behavior crosses those boundaries.

9. Expected outputs

An evidence-backed qemu boot testing result with scoped artifacts, tests, documentation, and handoff. Include acceptance evidence, residual limitations, and next dependency rather than only code.

10. Step-by-step workflow

1. Build exact feature/profile image
2. Record firmware and full QEMU command
3. Capture ordered serial markers and return status
4. Locate first missing/forbidden marker
5. Preserve image, manifest, ELF, and log on failure
6. Run the narrow regression, then all required subsystem/repository checks.
7. Update canonical docs/status and finish the agent-handoff template.

11. Repository-specific commands

./tools/finn test-boot
./tools/finn test-boot --target arm64-qemu

Run commands from the repository root. A command listed here is a baseline/gate, not evidence that absent future functionality has a runnable target.

12. Architecture considerations

Use q35/OVMF plus isa-debug-exit only for x86; ARM uses virt/AAVMF, PL011, semihosting status 0, and a distinct marker contract.

State guest architecture separately from host architecture and emulator model. Maintain a parity row for changed semantics and document intentional differences.

13. Safety constraints

Preserve the boundary described by the current state: x86 q35/OVMF has eight development modes plus release first boot; ARM64 virt/AAVMF has a distinct locally verified R3 serial-entry test. Apply .agents/checklists/pre-change.md; for kernel, driver, security, architecture, or UI work also apply the matching checklist.

14. Testing requirements

Make Preserve image, manifest, ELF, and log on failure observable with a negative case, then run the narrow and aggregate gates. Do not permanently hard-code test counts; counts belong to dated evidence reports.

15. Documentation requirements

Update the canonical behavior/status document, relevant architecture/reference material, test/build instructions, limitations, and this skill registry if any command, gate, or current-context statement changes.

16. Review checklist

• The workflow proves Build exact feature/profile image before relying on downstream assumptions.
• The observed baseline and first failing/divergent point are recorded.
• Every prerequisite and roadmap dependency is satisfied or explicitly marked blocked.
• Bounds, ownership, rollback, error paths, and resource limits were reviewed.
• x86-64 and ARM64 semantics are mapped without unsupported parity claims.
• Negative/failure tests exist at the layer that owns the behavior.
• Commands, logs, artifact/profile/architecture, and results are preserved.
• Canonical documentation and affected agent skills agree with behavior.

17. Completion criteria

• All stated outputs exist and remain within the task's scope/non-goals.
• The narrow regression and required repository/subsystem gates pass.
• Acceptance criteria are tied to source, test, runtime, or hardware evidence as appropriate.
• Unknowns and unsupported environments remain explicit; no planned feature is promoted.
• The final diff is reviewed and a structured handoff is complete.

18. Common failure modes

• Starting from an audit statement instead of re-reading changed source and tests.
• Using a successful compile or marker as evidence for a broader subsystem claim.
• Ignoring this skill's current constraint: x86 q35/OVMF has eight development modes plus release first boot; ARM64 virt/AAVMF has a distinct locally verified R3 serial-entry test.
• Changing shared policy while testing only one architecture or one happy path.
• Losing the exact failing artifact/log by rebuilding before capture.

19. Forbidden shortcuts

• Do not weaken, delete, reorder, or broaden validators merely to make a test pass.
• Do not claim ARM64, physical hardware, userspace, Peony, security, or release support without its own acceptance evidence.
• Do not bypass a named prerequisite by embedding a temporary incompatible abstraction.
• Do not commit target/, build/out/, firmware, credentials, local paths, or unreviewed generated output.
• Do not disregard the roadmap/status gate: Do not use this skill as a substitute for its adjacent subsystem skills or for evidence that the subsystem works.

20. Handoff requirements

Use .agents/templates/handoff-template.md. Include objective, starting/final Git state, task state, skills used, files, exact commands/results, evidence classification, docs/status changes, unknowns, blockers, risks, next action, and next skills. Distinguish locally verified worktree changes from integrated behavior.

21. Examples

Request: "Work on QEMU." Correct response: begin by build exact feature/profile image, then record firmware and full qemu command, and require evidence for preserve image, manifest, elf, and log on failure before changing status. Incorrect response: create a plausible subsystem scaffold and mark the roadmap item complete because it compiles.

22. Skill maintenance notes

Canonical source: .agents/scripts/skill_registry.py. Increment version for material policy/workflow/gate changes, update last_verified only after reinspection, run python3 .agents/scripts/render_skills.py, review generated diffs, then run python3 .agents/scripts/validate.py --all. Follow .agents/GOVERNANCE.md; never hand-edit generated skills.