From eb61ec76367731579eb585f39b251da629beb871 Mon Sep 17 00:00:00 2001
From: Natasha Moongrave <natasha@256phi.eu>
Date: Wed, 8 Apr 2026 16:29:35 +0200
Subject: [Step 0] Add PLAN.md and NOTES.md

PLAN.md: Full 7-phase development roadmap with progress tracker, per-phase
tasks, integration test specs, security baseline, and dependency list.

NOTES.md: Running developer log for context recovery after session resets.
Documents key architecture decisions (GDT segment order, filesystem strategy,
heap sizing, syscall ABI).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 NOTES.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 NOTES.md

(limited to 'NOTES.md')

diff --git a/NOTES.md b/NOTES.md
new file mode 100644
index 0000000..d140620
--- /dev/null
+++ b/NOTES.md
@@ -0,0 +1,78 @@
+# Strix OS — Developer Notes
+
+> **READ THIS FIRST after a context reset.** Then read `PLAN.md` for the full roadmap.
+> Updated at every commit.
+
+---
+
+## How to Resume After Context Reset
+
+1. Read this file top-to-bottom
+2. Read `PLAN.md` — check the Progress Tracker table for current status
+3. Run `cargo test` from `StrixKernel/` to confirm current build state
+4. Continue from the first `🔲 TODO` item in PLAN.md
+
+---
+
+## Current Status
+
+**Branch**: `CLAUDE_TEST`
+**Phase**: Starting Phase 2 — User Space Foundation
+**Last commit**: `[Step 0] Add PLAN.md and NOTES.md`
+**Next task**: `[Phase 2.1]` — Extend GDT with user space segments
+
+---
+
+## Key Decisions & Rationale
+
+| Decision | Rationale |
+|----------|-----------|
+| ext4 as primary filesystem | Nix requires symlinks, xattrs, POSIX perms; ext4 covers all. Impl as ext2 first |
+| SYSCALL/SYSRET for syscall interface | Faster than int 0x80; Linux ABI compatible |
+| GDT segment order: kcode/kdata/udata/ucode/tss | Required for STAR MSR arithmetic (see Phase 2.1 notes) |
+| Heap 100 KiB → 4 MiB | Process table (256 entries) + 64 KiB kernel stacks needs > 16 MiB; start at 4 MiB |
+| goblin crate for ELF parsing | no_std compatible, well-maintained, handles ELF64 |
+| Embedded busybox initramfs | Self-contained rescue shell; no disk dependency for Phase 3 testing |
+| OpenRC default init, `init=` configurable | Lightweight; swappable without kernel changes |
+| W^X enforced on all mappings | Prevents code injection via data segments |
+| All user pointers validated | Prevents kernel memory disclosure/corruption via syscalls |
+
+---
+
+## Architecture Notes
+
+### GDT Segment Order (Critical for SYSCALL/SYSRET)
+```
+0x00: null
+0x08: kernel code (DPL=0)  ← STAR[47:32]
+0x10: kernel data (DPL=0)  ← auto: SYSCALL sets SS = CS+8
+0x18: user data (DPL=3)    ← SYSRET: SS = STAR[63:48]+8
+0x20: user code (DPL=3)    ← SYSRET: CS = STAR[63:48]+16
+0x28/0x30: TSS (128-bit)
+```
+STAR MSR values: `STAR[47:32]=0x08`, `STAR[63:48]=0x10`
+
+### Heap Layout
+```
+HEAP_START = 0x4444_4444_0000
+HEAP_SIZE  = 4 MiB (was 100 KiB)
+```
+
+### Key Virtual Address Constants
+```
+Physical memory offset: 0x0000_2560_0000_0000 (from bootloader)
+Heap start:             0x4444_4444_0000
+User stack top:         0x7fff_f000_0000 (8 MiB stack)
+User address limit:     0x0000_8000_0000_0000 (canonical boundary)
+```
+
+---
+
+## Log
+
+### [Step 0] 2026-04-08 — Bootstrap repo docs
+**Done**: Created `PLAN.md` (full roadmap with progress tracker) and `NOTES.md` (this file).
+**Next**: Phase 2.1 — Extend GDT.
+**Decisions**: None new.
+
+---
-- 
cgit v1.2.3