{"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 arm64, aarch64, AAVMF; provides the FinnOS-specific arm64 platform development workflow and evidence gates.
ARM64 Platform Development
1. Name
arm64-platform-development (Boot and kernel; skill maturity: operational).
2. Purpose
Bring up AArch64 UEFI/QEMU mechanisms while maintaining semantic parity with x86.
3. When to use this skill
Use for requests mentioning arm64, aarch64, AAVMF, GIC, exception vectors, 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
uefi-bootloader-development
cross-architecture-design
qemu-boot-testing
unsafe-rust-low-level-safety
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
PORTING.md
build/targets/arm64-qemu.toml
Finnfile.toml
Re-read implementation and tests referenced by those documents. The documents establish intent/status boundaries, not runtime proof.
7. Current FinnOS context
R3 BOOTAA64, AAPCS64 entry, PL011, image/QEMU command, ordered smoke validation, and CI workflow are implemented; local runtime passes and CI is pending.
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 arm64 platform development 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
Clear R1: target/profile data must drive build, image, run/test, artifacts, invalid-combination errors, and local/CI parity
For R3 add BOOTAA64, matching kernel/linker/entry/UART, QEMU virt plus AAVMF resolution, and bounded ordered loader/kernel-entry markers
End R3 at deterministic serial kernel entry with retained manifest/artifacts/log and existing x86 gates green
For R4 only, add exception vectors, MMU/MAIR/TCR/TTBR, GIC, generic timer, and AAPCS64 task context parity
Define ARM-specific timeout/termination evidence and environment overrides rather than copying x86 isa-debug-exit or OVMF variables
Run the narrow regression, then all required subsystem/repository checks.
Update canonical docs/status and finish the agent-handoff template.
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 AAPCS64, EL0/EL1, VBAR, translation-table, GIC, and barrier semantics; never transliterate x86 registers.
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: R3 BOOTAA64, AAPCS64 entry, PL011, image/QEMU command, ordered smoke validation, and CI workflow are implemented; local runtime passes and CI is pending. Apply .agents/checklists/pre-change.md; for kernel, driver, security, architecture, or UI work also apply the matching checklist.
14. Testing requirements
Make Define ARM-specific timeout/termination evidence and environment overrides rather than copying x86 isa-debug-exit or OVMF variables 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 Clear R1: target/profile data must drive build, image, run/test, artifacts, invalid-combination errors, and local/CI parity 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: R3 BOOTAA64, AAPCS64 entry, PL011, image/QEMU command, ordered smoke validation, and CI workflow are implemented; local runtime passes and CI is pending.
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 arm64." Correct response: begin by clear r1: target/profile data must drive build, image, run/test, artifacts, invalid-combination errors, and local/ci parity, then for r3 add bootaa64, matching kernel/linker/entry/uart, qemu virt plus aavmf resolution, and bounded ordered loader/kernel-entry markers, and require evidence for define arm-specific timeout/termination evidence and environment overrides rather than copying x86 isa-debug-exit or ovmf variables 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.
