ITISYOU_OS
PRE-ALPHA

Engineering Process

Every requirement ends in exactly one state — implemented + verified, blocked, or not applicable — with evidence. Failure is data: panic output, QEMU exit codes, timeouts, and serial tails are captured as structured evidence, not discarded.

Development lifecycle

  1. STEP_01 Specification requirement + gate defined first
  2. STEP_02 Implementation Rust no_std, unsafe documented
  3. STEP_03 Compile pinned nightly, reproducible
  4. STEP_04 QEMU Boot BIOS + UEFI matrix
  5. STEP_05 Verification markers, selftests, JSON evidence

A hang, panic, or missing marker can never pass. Absence of output is never success.

Test pyramid

  1. 1 · HOST UNIT TESTS

    cargo test on kernel-core, image-builder, qemu-runner — pure logic: stage/marker contract, SHA-256 vectors, and (as subsystems land) memory-map normalization, allocator logic, parsing. Fast, deterministic, no QEMU.

  2. 2 · QEMU BOOT SMOKE

    Boots the interactive kernel (BIOS and UEFI), asserts stages B010/B020/B030 appear within the timeout.

  3. 3 · QEMU SELFTEST SUITE

    Boots itisyou-kernel-selftest; requires all expected stages, fail=0, pass>0, and QEMU exit code 33. A hang, panic, or missing summary can never pass.

  4. 4 · NEGATIVE CASES

    Grown alongside subsystems: intentional panic, allocator exhaustion, malformed inputs, timeout classification.

The QEMU harness

tools/qemu-runner launches QEMU with project-generated disposable images, watches the serial stream for the boot-stage markers, and classifies every run: success, selftest-failed, panic, timeout, missing-markers, launch-failure, or unexpected-exit.

// serial marker grammar (specification — not a boot capture)

[ITISYOU:B010] kernel entry reached in 64-bit mode

[ITISYOU:B020] early serial console ready

[ITISYOU:SELFTEST] pass=N fail=M

// harness gate: all stages ∧ fail=0 ∧ pass>0 ∧ exit=33

Evidence per run: artifacts/qemu/<label>.serial.log + <label>.result.json. Rules: no skipped tests to obtain green status; a bug fix lands with a regression test; “passing” is only claimed from an actual run’s evidence.

Requirement traceability

Excerpt — full matrix lives in docs/REQUIREMENTS.md

Requirement traceability excerpt with status and evidence convention
IDRequirementStatusEvidence convention
BOOT-001 QEMU reaches kernel entry (B010) IN DEVELOPMENT qemu-runner label boot-smoke-*
BOOT-002 Serial logging works (B020) IN DEVELOPMENT qemu-runner label boot-smoke-*
MEM-001 Physical memory manager works PLANNED unit + QEMU selftests
INT-001 Exceptions/IDT installed PLANNED controlled exception test
TASK-001 Scheduler runs multiple tasks PLANNED deterministic task output tests
DIAG-001 Panic produces useful serial evidence IN DEVELOPMENT panic handler emits [ITISYOU:PANIC]; negative test pending

A requirement is never deleted because it is difficult. Statuses collapse to implemented+verified / blocked / not-applicable at reporting time.

Development journal

Latest entries — full ledger at /changelog

2026-09-02 02:30 Session 1 — Foundation IN DEVELOPMENT

Kernel skeleton and test harness authored

Workspace laid down: kernel/ (lib + interactive and selftest binaries), crates/kernel-core (host-testable stage/marker contract), tools/image-builder (pure-Rust BIOS/UEFI images + SHA-256 manifest), tools/qemu-runner (deterministic boot assertion harness with JSON evidence).

First build failed: this nightly’s cargo rejects `cargo-features = ["bindeps"]` in the manifest. Root cause: artifact dependencies must now be enabled via `[unstable] bindeps = true` in .cargo/config.toml. Fixed there; `per-package-target` remains a manifest feature. Rebuild launched.

error: unknown Cargo.toml feature `bindeps` — resolved in .cargo/config.toml

2026-09-02 02:20 Session 1 — Foundation IN DEVELOPMENT

Governance intake and discovery

Read AGENT_OPERATING_RULES.md and the end-to-end implementation plan; both adopted as binding. Requirement traceability matrix created (docs/REQUIREMENTS.md). Stitch design export preserved unchanged in design/ and extracted as the visual source of truth.

Environment discovery and storage rules applied: Rust nightly-2026-09-01 + x86_64-unknown-none toolchain installed to E:\toolchains, QEMU 11.1.0 extracted to E:\tools\qemu without elevation, scratch routed to G:\claude-tmp. GitHub authenticated; repository to be created private.

docs/REQUIREMENTS.md · docs/adr/0001..0003 · design/stitch/ (13 screens + DESIGN.md)

Full ledger Testing doc