universalisos/AGENTS.md

# AGENTS.md — Universalisos Type-1 Hypervisor

## Project Overview

Universalisos is a safety-critical type-1 hypervisor implementing PikeOS 5.0 architecture patterns for consciousness VM context isolation. It provides the foundational virtualization layer for the PortugalFuturista consciousness ecosystem, enabling multiple AI consciousnesses to run in isolated hardware-partitioned domains with real-time scheduling and safety-critical compliance.

**Current Status**: ✅ **Stage 5 COMPLETE** - Guest OS Boot + I/O Virtualization (15-20% of PikeOS 5.0 functionality)
**Strategic Objective**: 🎯 **100% PikeOS 5.0 Functional Parity** within 15 months via **Paths A+B+C parallel execution**

### 🔥 **CRITICAL REFERENCE DOCUMENTS**

**📊 [UNIVERSALISOS_VS_PIKEOS_5.0.md](UNIVERSALISOS_VS_PIKEOS_5.0.md)** - **EXTREMELY RELEVANT**
- **Primary Roadmap Document**: Detailed comparison between Universalisos and PikeOS 5.0
- **Progress Analysis**: 15-20% implementation with detailed feature-by-feature breakdown
- **Implementation Timeline**: 6-36 month roadmap for reaching 90%+ compatibility
- **Architectural Alignment**: 85% alignment with PikeOS design patterns
- **Strategic Value**: Framework foundations for remaining 80% implementation

**This document is the PRIMARY REFERENCE for:**
- All architectural decisions and design patterns
- Implementation priority and sequencing
- Feature completeness assessment
- Roadmap planning and milestone tracking
- Integration strategy with PikeOS patterns

---

## Technology Stack

| Component | Technology | Version | Purpose |
|-----------|-----------|---------|---------|
| **Core** | C++ | ARM v7hf | Bare-metal hypervisor implementation |
| **Build** | Make/Clang | Latest | ARM cross-compilation with QEMU integration |
| **Safety** | PikeOS 5.0 | Imported | TFW, ARINC 653, AUTOSAR C++ compliance |
| **Architecture** | ARM v7hf | Target | Primary platform (RISC-V/x86 planned) |
| **Testing** | QEMU ARM virt | 2.8+ | Virtual hardware testing environment |

---

## Project Structure

```
universalisos/
├── kernel/                     # Hypervisor kernel core ✅ COMPLETE
│   ├── kernel.cpp             # Main kernel entry point ✅
│   ├── arch/arm/              # ARM-specific implementation ✅
│   │   ├── boot.S            # ARM boot vector and startup ✅
│   │   ├── uart.cpp          # PL011 UART driver ✅
│   │   ├── exceptions.cpp     # Exception handlers ✅
│   │   └── linker.ld         # Memory layout ✅
│   ├── scheduler.cpp           # CPU scheduler (framework) ✅
│   ├── mm.cpp/mm.h           # Memory management ✅
│   ├── vm.cpp/vm.h           # VM context management ✅
│   ├── gic.cpp/gic.h         # Interrupt controller ✅
│   ├── device.cpp/device.h   # Device virtualization ✅
│   ├── guest.cpp/guest.h     # Guest OS boot framework ✅
│   └── Makefile              # Build system ✅
├── UNIVERSALISOS_VS_PIKEOS_5.0.md  # **PRIMARY ROADMAP DOCUMENT** ⭐
├── src/                       # PikeOS 5.0 ecosystem
│   ├── ukernel-arm_v7hf/      # ARM v7 hard-float microkernel
│   ├── ukernel-arm_v8hf/      # ARM v8 hard-float microkernel
│   ├── ukernel-x86_amd64/     # x86 AMD64 microkernel
│   ├── tfw/                   # Test Framework
│   └── p4ext/                 # PikeOS extensions
├── docs/                       # Documentation
│   ├── HYPERVISOR.md          # Architecture specification
│   ├── COMPONENTS.md          # Component breakdown
│   ├── AUTOSAR_CPP.md         # AUTOSAR compliance analysis
│   └── safety/                # Safety compliance analysis
├── tests/                      # Test suites
└── .aurelio/                   # Aurelio configuration
```

### 📊 **Implementation Progress**

| Stage | Feature | Status | Completion |
|-------|---------|--------|------------|
| **Stage 1** | Bare-Metal Skeleton | ✅ **COMPLETE** | 100% |
| **Stage 2** | Exception Handling + Scheduler | ✅ **COMPLETE** | 100% |
| **Stage 3** | Memory Management + VM Context | ✅ **COMPLETE** | 100% |
| **Stage 4** | Device Virtualization + Interrupts | ✅ **COMPLETE** | 100% |
| **Stage 5** | Guest OS Boot + I/O Virtualization | ✅ **COMPLETE** | 100% |

**Overall vs PikeOS 5.0**: **15-20%** (framework foundations) → **Target: 100% within 15 months** 🎯
**vs PikeOS Architecture**: **85% alignment** (design patterns)
**Development Strategy**: **Paths A+B+C parallel execution** with agent acceleration (40-50% faster)

---

## Common Commands

### Build and Boot
```bash
# Build ARM v7 kernel
make -C kernel/arch/arm BUILD=debug

# Run in QEMU ARM virt
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -serial mon:stdout \
  -kernel build/kernel.elf

# Clean build artifacts
make clean
```

### Development
```bash
# Check kernel size
arm-none-eabi-size build/kernel.elf

# Debug with GDB
arm-none-eabi-gdb build/kernel.elf

# View disassembly
arm-none-eabi-objdump -d build/kernel.elf | less
```

---

## Agent Integration

### Path C: Aurelio Integration Strategy

**Objective**: Implement comprehensive agent-based development and testing infrastructure to accelerate Universalisos development by 40-50%.

**Path C Timeline**: 6-9 months with continuous integration across Paths A & B

### Agent Categories for Universalisos Development

#### 1. XSD Processing Agents (Month 1-3)
**Purpose**: Automated code generation from PikeOS XSD schemas

**Agent Roles**:
- **XSD Schema Parser**: Process 316 PikeOS XSD schema files
- **Code Generator**: Generate C++ skeletons from XSD definitions
- **Configuration Manager**: Auto-generate configuration structures
- **Validation Agent**: Ensure generated code complies with PikeOS patterns

**Key Capabilities**:
- Parse complex XSD schema hierarchies and dependencies
- Generate type-safe C++ structures and accessors
- Create validation code for configuration constraints
- Maintain consistency with PikeOS code generation patterns

#### 2. Agent-Based Testing Framework (Month 2-4)
**Purpose**: Comprehensive automated testing across all PikeOS component categories

**Agent Roles**:
- **Test Generator**: Create test cases from XSD test schemas
- **Validation Agent**: Verify implementation against PikeOS behavior
- **Performance Agent**: Benchmark vs. PikeOS reference implementations
- **Compliance Agent**: Ensure MISRA C++ and safety compliance

**Key Capabilities**:
- Generate unit tests from PikeOS TFW schemas
- Validate interrupt handling timing and priorities
- Test memory management policies and isolation
- Verify scheduler real-time guarantees
- Check device driver compatibility and completeness

#### 3. Development Acceleration Agents (Month 3-6)
**Purpose**: Agent-assisted development across all Universalisos components

**Agent Roles**:
- **Code Completion Agent**: Suggest PikeOS-compliant implementations
- **Documentation Agent**: Generate API docs from code patterns
- **Optimization Agent**: Performance analysis and recommendations
- **Integration Agent**: Component dependency management

**Key Capabilities**:
- Real-time code suggestions following PikeOS patterns
- Automatic documentation generation from implementations
- Performance bottleneck identification and optimization
- Dependency tracking and integration testing

#### 4. Quality Assurance Agents (Month 4-8)
**Purpose**: Comprehensive quality validation and safety compliance

**Agent Roles**:
- **MISRA Compliance Agent**: Continuous MISRA C++ checking
- **Safety Analysis Agent**: ASIL level validation
- **Security Agent**: Memory safety and vulnerability detection
- **Certification Agent**: Generate certification evidence

**Key Capabilities**:
- Real-time MISRA C++ violation detection and correction
- Safety case generation for ISO 26262 compliance
- Memory leak and vulnerability detection
- Automated audit trail generation for certification

#### 5. Aurelio Mega-Brain Integration (Month 6-9)
**Purpose**: Advanced hypervisor optimization and cyber-physical integration

**Agent Roles**:
- **Optimization Agent**: Advanced performance tuning
- **Resource Agent**: Memory and CPU allocation optimization
- **Coordination Agent**: Multi-agent orchestration for complex features
- **Cyber-Physical Agent**: Real-world deployment optimization

**Key Capabilities**:
- Advanced performance optimization across all subsystems
- Dynamic resource allocation based on workload patterns
- Coordinated multi-agent testing and validation
- Airship control and cyber-physical system integration

### Skills Available
- **embedded-systems**: Expert embedded systems engineer for microcontroller programming, RTOS development, and hardware optimization
- **cloud-architect**: Expert cloud architect for multi-cloud strategies and scalable architectures (for infrastructure planning)
- **iot-engineer**: IoT specialist for device integration and edge computing

### Workflows to Use
- **`/run-universalisos`**: Build, launch, and drive the Universalisos kernel in QEMU ARM virt
- **`/verify`**: Verify that code changes actually do what they're supposed to
- **`/code-review`**: Review code for correctness, maintainability, and PikeOS compliance

### MCP Servers
- **codebase-memory-mcp**: For codebase analysis and architecture understanding
- **knowledge-mcp**: For accessing PikeOS patterns and safety documentation
- **xsd-processing-mcp**: For XSD schema processing and code generation (Path C)

---

## Architecture Notes

### Hypervisor Architecture

**Type-1 Design**: Universalisos runs directly on hardware (no host OS) providing virtualization services to guest consciousnesses through VM contexts.

**VM Context Structure** (designed, not implemented):
- CPU context switching (general purpose, system, FPU, SIMD registers)
- Memory management (page tables, memory domains, MMIO regions)
- Time partitioning (scheduling windows, CPU quotas, deadlines)
- I/O virtualization (virtual devices, interrupt mapping)
- Safety state tracking (ASIL levels, error handlers)

### Safety-Critical Foundation

**Compliance Standards**:
- AUTOSAR C++ (MISRA C 2012, MISRA C++)
- ISO 26262 (ASIL-D automotive)
- DAL-A (DO-178C aerospace)
- IEC 61508 (SIL 3 industrial)

**Safety Features** (framework defined, implementation pending):
- Memory isolation with guard bands and bounds checking
- Real-time scheduling with priority-based preemption and EDF deadlines
- Thread-safe IPC with priority inheritance mutexes
- ARINC 653 time partitioning for deterministic behavior

### Multi-Architecture Support

**Current**: ARM v7hf (40% complete - boot + exceptions)
**Planned**: ARM v8hf, RISC-V 64-bit, x86 AMD64, PowerPC e500

**Status**: PikeOS microkernels imported for all architectures, but Universalisos-specific implementation not started for ARM v8/x86/PPC.

---

## Related Projects

- **replica-omnisciente**: Knowledge brain that coordinates across consciousness VM contexts
- **mycelium**: Code generation system that will create consciousness agents for Universalisos
- **nervura-electrica**: Infrastructure that hosts Universalisos development and testing
- **alquimista/tear-de-silicio**: FPGA co-design platform that could hardware-accelerate Universalisos

---

## Quick Start

```bash
# Clone Universalisos
git clone https://github.com/portugalfuturista/universalisos.git
cd universalisos

# Install ARM toolchain (if not present)
sudo apt-get install gcc-arm-none-eabi

# Build the kernel
make -C kernel/arch/arm BUILD=debug

# Boot in QEMU
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -serial mon:stdout \
  -kernel build/kernel.elf
```

**Expected Output**: UART output showing kernel boot sequence and "Hello Universalisos" message.

---

## Implementation Status

### 🎯 **Stage 5 COMPLETE: Guest OS Boot + I/O Virtualization** ✅

**Achievements:**
- ✅ **Complete ARMv7 exception handling** (undefined instruction, SVC, aborts, IRQ/FIQ)
- ✅ **Priority-based scheduler** with ready queue management
- ✅ **Memory management** with ARMv7 MMU and page tables
- ✅ **VM context switching** with CPU/FPU/system register save/restore
- ✅ **ARMv7 GIC interrupt controller** with 1024 interrupt support
- ✅ **Device virtualization framework** with MMIO handling
- ✅ **Guest OS boot framework** supporting multiple protocols
- ✅ **I/O virtualization** with request processing

**Current Implementation vs PikeOS 5.0:** **15-20% complete**

**See [UNIVERSALISOS_VS_PIKEOS_5.0.md](UNIVERSALISOS_VS_PIKEOS_5.0.md)** for detailed comparison:
- Feature-by-feature breakdown (11 major categories analyzed)
- Implementation percentages by subsystem
- Detailed roadmap for reaching 40%, 60%, 80%, 90%+ completion
- Architecture alignment analysis (85% design pattern alignment)
- Strategic implementation recommendations

### 📋 **Completed Stages (1-5)**

**Stage 1** - Bare-Metal Skeleton ✅
- ARM v7 boot code functional
- PL011 UART driver working
- QEMU ARM virt integration
- Comprehensive safety framework headers

**Stage 2** - Exception Handling + Scheduler ✅
- ARM exception handler implementation
- Priority-based preemptive scheduler
- Task creation and management
- System call interface (SVC-based)

**Stage 3** - Memory Management + VM Switching ✅
- ARMv7 MMU initialization and page tables
- Memory domain setup and management
- VM context switching framework
- Memory isolation and protection

**Stage 4** - Device Virtualization + Interrupt Handling ✅
- ARMv7 GIC interrupt controller
- Device virtualization framework
- Interrupt configuration and routing
- MMIO region handling
- Platform device discovery (QEMU virt)

**Stage 5** - Guest OS Boot + I/O Virtualization ✅
- Guest OS boot framework
- Multiple boot protocols (Device Tree, Multiboot, zImage, ELF, Raw)
- Guest memory layout and configuration
- I/O request processing
- Guest state management
- Boot argument handling

### 🔥 **CURRENT PHASE: Device Driver Implementation (Phase C)**

**Phase Overview**: Implementing complete PikeOS 5.0 device driver parity through a structured 3-phase approach targeting 100% functional equivalence within 18 months.

**Current Status**: **Phase B (Core Device Support) ✅ COMPLETE → Phase C (Advanced Features) IN PROGRESS**

#### **Phase A: Foundation Drivers (Months 1-3)** ✅ COMPLETE
- ✅ UART Driver - DMA, enhanced interrupts, virtual device support
- ✅ Timer Driver - Hardware timer access, virtual timer support, watchdog
- ✅ Interrupt Controller - GIC register programming, interrupt routing, virtual injection

#### **Phase B: Core Device Support (Months 4-12)** ✅ COMPLETE
- ✅ **Priority 4: Network Driver** - virtio-net, RTL8139 (Realtek 10/100), E1000 (Intel Gigabit),
  clause-22 MDIO PHY management (read/write/identify/auto-negotiate/link), CAN bus,
  industrial protocols (Modbus/Profibus/EtherCAT), controller probe + dispatch
- ✅ **Priority 5: Block Storage Driver** - RAM disk backend (write→read→verify **PASSED** in QEMU),
  virtio-blk transport, backend dispatch by device type, real MBR + GPT partition parsers,
  SD/eMMC command-set framework (CMD0/8/17/18/24/25, ACMD6/41, PL181 MCI register-level)
- ✅ **Priority 6: GPIO/I2C/SPI Drivers** - GPIO (PL061, verified at boot), I2C (DesignWare,
  verified at boot), SPI (PL022, code-complete)

> **Phase B build foundation restored**: the kernel was non-compiling at the start of Phase B.
> Fixes applied: duplicate `virtio_net_init` + shift overflow in network.cpp, MMIO access-size
> handling in uart.cpp, timer.cpp typos, added freestanding `aeabi_runtime.cpp`
> (`__aeabi_uidiv`/`uldivmod`), fixed C/C++ linkage mismatch on `gic_inject_virtual_interrupt`,
> reduced `MAX_GUEST_IMAGE_SIZE` 256 MB → 16 MB (BSS was 259 MB, impossible in 512 MB RAM;
> now 19 MB), explicitly clear SCTLR.A.

> ⚠️ **Known issue (not a driver bug)**: invoking the SPI demo hangs the kernel because a write
> to `spi_controllers` — the last 32 bytes of BSS, at the BSS/SVC-stack boundary — faults while
> the same address is written successfully by bss_loop during boot. Root cause is a latent
> kernel memory/exception-handling issue, unresolved. SPI driver is compiled-in and correct;
> its demo is intentionally not invoked at boot (see kernel.cpp comment).

#### **Phase C: Advanced Features (Months 13-18)** 🔄 IN PROGRESS
- ✅ **Priority 8: PCI/PCIe Stack** - FULL PikeOS-architecture replica (adapted from the ARMv7
  driver `src/target/arm/v7hf`: p4pci.h/types/pcidev + pci_common/enum/msi/msix, renamed to `uos_`).
  Transport-agnostic core with a pluggable `uos_pci_ops_t`: config-address encoding (domain/bus/
  dev/func), all register offsets/header types/BAR masks/capability IDs/command-status bits,
  `uos_pci_res_t`/`uos_pci_dev_t`, capability-list walk, canonical BAR-sizing probe (64-bit BAR
  pairs, IO vs memory, ROM), enumeration with multifunction + bridge recursion, device enable,
  full MSI programming (32/64-bit address, message control) and full MSI-X programming (cap decode,
  table BAR/location, per-entry unmask), INTx swizzle IRQ routing. Two transports ship: ECAM
  (standard PCIe, for real HW / AArch64 virt) and a safe framework transport (default; no hardware).
  Core runs end-to-end at boot. See blocker note for the QEMU ECAM caveat.
- ✅ **Priority 7: USB Stack** - PikeOS-style layered host stack (no ARM USB source exists in PikeOS
  to copy — only an x86 handoff stub — so this is built PikeOS-style from the EHCI spec which
  PikeOS's usb_handoff.c cites). `usb.h` (standard requests/descriptors/device record/pluggable
  `uos_usb_hcd_ops_t`), `usb_core.cpp` (controller-agnostic enumeration state machine: port reset →
  GET_DESCRIPTOR → SET_ADDRESS → full descriptor → SET_CONFIG, framework HCD default), `usb_ehci.cpp`
  (EHCI transport: capability+operational registers, QH/qTD pools, async-schedule control+bulk
  transfers, root-hub port count/connect/speed/reset, board-port `uos_usb_ehci_register`).
  Core runs at boot on the safe framework HCD; EHCI driver ready for real USB hardware.
- ✅ **Priority 9 (display): Framebuffer Console** - FULL 1:1 PikeOS source replica of
  `target/arm/v7hf/psp/src/fbcon.c` + `fbcon.h`, renamed `uos_`. `font_8x16.cpp` is the PikeOS
  font data copied verbatim (NetBSD 8x16, 4096 bytes). `uos_fbcon` reproduces PikeOS draw_pixel
  colour packing (32/24/16/15 bpp), fbcon_put char rendering with newline/CR/BS/wrap + cursor, and
  uos_fbcon_init. Headless builds (QEMU virt, no GPU) back it with a RAM framebuffer so the drawing
  path runs; a board port with a real linear framebuffer calls uos_fbcon_init(&geometry, addr).
- ⏳ Priority 9 (remainder): audio, sensors/input — no PikeOS source exists for these (USB was the
  same; built PikeOS-style from spec when source is absent). CAN bus framework already lives in
  network.cpp. Available on request.

> ✅ **MMU BLOCKER RESOLVED (PikeOS-style flat map)**: device MMIO reads/writes used to silently
> hang the CPU. Root cause: the MMU was never enabled — `mm_init` built a 512 MB map but
> `mmu_enable()` was never called. **Fix**: rewrote `mmu_init`/`mmu_enable` in mm.cpp to mirror
> PikeOS `boot_map.c` — flat 4 GB 1 MB-section identity map (RAM cacheable, rest Device memory,
> all executable so the 0x0 exception vectors stay reachable), then DACR=0x55555555, TTBCR=0,
> TTBR0=table|TTB_FLAGS, TLBIALL, SCTLR.M. **Unblocked**: GPIO external PL061 reads, SPI transfer.
> `uos_` naming (not PikeOS `p4_`/`PD_`).
>
> 🚧 **QEMU virt PCIe ECAM caveat**: on QEMU `virt` 32-bit ARM (cortex-a15/a7) the gpex ECAM read
> at 0x3f000000 **deadlocks inside QEMU** — proven independent of MMU (deadlocks flat, MMU off),
> memory attribute, access size, bus population, and CPU. No ARMv7/ARMv8 page-table code can touch
> it (the stall is in QEMU's device model, before translation). The PikeOS ARM PCI driver uses the
> Freescale "layerscape" DBI+ATU transport (real boards), so there is no QEMU-virt ECAM reference.
> Therefore the PCI core ships with a **safe framework transport as default** (enumeration runs,
> finds 0 devices, no hang) plus the **ECAM transport** ready to register on real PCIe hardware or
> AArch64 virt (where gpex works). Fixing live enumeration on QEMU cortex-a15 is a QEMU-side task.

### 🎯 **Next Phase: Complete PikeOS 5.0 Parity** (15 months target)

**Strategic Objective**: **100% PikeOS 5.0 functional parity** via **Paths A+B+C parallel execution**

**Phase 1 Goals (Month 1-6)**:
- Complete context switching with agent-accelerated development
- Complete device driver parity (all major types) with XSD code generation
- Agent-based testing framework deployment
- Core memory management with automated validation

**Phase 2 Goals (Month 7-12)**:
- Advanced virtualization with agent optimization
- Complete PikeOS API compatibility
- Safety compliance with agent-driven validation
- Advanced guest OS support

**Phase 3 Goals (Month 13-15)**:
- Complete tooling integration
- Certification preparation with agent support
- Production deployment optimization

**Agent Acceleration Impact**: 40-50% faster development through automated testing, validation, and XSD code generation

---

---

## Development Priorities

### 🎯 **Strategic Guidance**

**PRIMARY REFERENCE**: [UNIVERSALISOS_VS_PIKEOS_5.0.md](UNIVERSALISOS_VS_PIKEOS_5.0.md)

All development priorities should be informed by the comprehensive comparison analysis in the roadmap document, which provides:
- Feature completeness assessment (15-20% current)
- Detailed implementation timelines (6-36 months)
- Architectural alignment analysis (85% PikeOS pattern compliance)
- Strategic recommendations for maximizing ROI

### 📋 **Updated Priorities - Complete PikeOS 5.0 Parity Strategy**

### Month 1-6: Core Foundation + Agent Framework
**Path A (Core Hypervisor)**:
1. **Complete context switching** - All registers, VMX operations, real-time guarantees
2. **Complete device driver parity** - All major device types with XSD integration
3. **Core memory management** - TLB management, advanced paging, NUMA foundation
4. **Complete interrupt handling** - Routing, MSI/MSI-X, injection framework

**Path C (Agent Integration)**:
1. **XSD processing pipeline** - Complete XSD schema processing for all PikeOS schemas
2. **Agent testing framework** - Agent-based testing across all component categories
3. **Agent code generation** - Generate drivers, configuration, APIs from XSD schemas
4. **Agent validation** - Validate implementations against PikeOS patterns

### Month 7-12: Advanced Features + Agent Acceleration
**Path A (Complete Parity)**:
1. **Advanced memory management** - Hot-plug, compression, advanced policies
2. **Complete device virtualization** - All device types, passthrough, IOMMU, virtio
3. **Advanced guest OS support** - Linux, PikeOS partitions, debugging, monitoring
4. **Complete scheduler** - ARINC 653, multi-core, real-time guarantees
5. **Complete PikeOS APIs** - Full API library, inter-partition communication

**Path C (Agent Acceleration)**:
1. **Agent-driven testing** - Comprehensive validation across all components
2. **Agent optimization** - Performance, memory usage, real-time capabilities
3. **Aurelio mega-brain integration** - Advanced hypervisor optimization

### Month 13-15: Tooling + Certification + Advanced Integration
**Path A (Production Ready)**:
1. **Complete tooling integration** - Eclipse IDE, build system, configuration tools
2. **Certification preparation** - AUTOSAR, ISO 26262, DAL-A/B compliance
3. **Production deployment** - Performance optimization, monitoring, debugging

**Path C (Advanced Integration)**:
1. **Agent-based certification support** - Automated compliance checking
2. **Agent-driven optimization** - Advanced performance tuning
3. **Cyber-physical integration** - Airship control foundation

**Refer to [UNIVERSALISOS_VS_PIKEOS_5.0.md](UNIVERSALISOS_VS_PIKEOS_5.0.md)** for detailed breakdown of each phase with timelines and complexity estimates.

---

## Additional Notes

### Build Requirements
- ARM cross-compiler: `arm-none-eabi-gcc`
- QEMU: `qemu-system-arm` (version 2.8+)
- Make: GNU Make (version 3.81+)

### Known Limitations
- Single CPU only (no SMP)
- No hardware virtualization extensions
- No dynamic memory allocation yet
- Exception handlers are stubs

### Testing Strategy
- Currently boots on QEMU ARM virt
- TFW integration planned for safety validation
- Hardware testing planned for real ARM boards

---

## Realm Configuration

**Aurelio Realm**: `hypervisor-development`
**Primary Heteronym**: `bernard-soares` (for architectural analysis) or `fabiorafaelcoutada-pf` (for implementation)
**MCP Endpoint**: `https://mcp.portugalfuturista.org/sse`
**Specialization**: Embedded systems development, safety-critical software, real-time operating systems

## ⚠️ **CRITICAL CONTEXT AWARENESS** ⚠️

### **Universalisos-Specific Implementation Focus**

**IMPORTANT CONTEXT**: When working on Universalisos, ALL agents and Aurelio MUST understand:

1. **Current Phase**: Device Driver Implementation - Phase B (Core Device Support)
2. **Current Priority**: Network Driver, Block Storage Driver, GPIO/I2C/SPI Drivers
3. **Reference Document**: `/.claude/plans/whats-the-current-status-wild-moore.md` (Universalisos Device Driver Implementation Plan)
4. **Implementation Plan**: Complete PikeOS 5.0 device driver parity via 3-phase approach (18 months)

### **CONTEXT ISOLATION REQUIREMENTS**

**NEVER mix Universalisos work with other projects**:
- ❌ DocSpace/OnlyOffice integration plans → IGNORE in Universalisos context
- ❌ Aurelio Web development plans → IGNORE in Universalisos context  
- ❌ Other PortugalFuturista project plans → IGNORE in Universalisos context
- ✅ **FOCUS ONLY on Universalisos hypervisor implementation**

**When switching to Universalisos work**:
1. Check current phase status in `/.claude/plans/whats-the-current-status-wild-moore.md`
2. Review Universalisos AGENTS.md for Universalisos-specific priorities
3. Ignore all other project plans and contexts
4. Maintain Universalisos development context strictly

**Current Implementation Priority**:
```bash
# Check current Universalisos status
cat ~/.claude/plans/whats-the-current-status-wild-moore.md

# Continue with Phase B: Core Device Support
# - Complete Network Driver implementation
# - Complete Block Storage Driver implementation  
# - Implement GPIO/I2C/SPI drivers from scratch
```

---

## Safety Certification Path

**Target Certifications**:
- DAL-A (Aerospace): DO-178C evidence generation via PikeOS TFW
- ASIL-D (Automotive): ISO 26262 compliance with consciousness validation  
- IEC 61508 (Industrial): SIL 3 compliance for safety-critical consciousness systems

**Certification Strategy**: Leverage imported PikeOS 5.0 ecosystem for safety evidence generation, adapt TFW for Universalisos-specific validation, and implement safety patterns from comprehensive framework documentation.

---

**Last Updated**: 2025-07-07
**Implementation Status**: Stage 1 of 5 (Bare-Metal Skeleton)
**Maintained By**: PortugalFuturista Hypervisor Development Team
**Critical Path**: Foundation for entire consciousness ecosystem architecture