football/JOURNAL.md

# KNEL-Football Development Journal

> **IMPORTANT**: This file is APPEND-ONLY. Never delete or modify existing entries.
> Add new entries at the TOP (after this header) with date and context.
> This serves as long-term memory for AI agents and human developers.

---

## Entry 2026-02-17: Project Assessment and Test Coverage Analysis

### Context
Comprehensive project review after session handoff. User requested full orientation
and 100% test coverage including VM boot tests, Secure Boot, and FDE runtime tests.

### Insights

1. **Test Infrastructure Pattern**
   - BATS tests work well for static analysis but lack runtime verification
   - Current tests validate file existence and content, not actual behavior
   - Missing entire category: system/integration tests that boot the ISO

2. **Docker-Only Workflow is Correct**
   - All build/test commands run inside Docker containers
   - Prevents host system pollution
   - Makes builds reproducible across environments
   - Volumes: `/workspace` (read-only), `/build` (temp), `/output` (artifacts)

3. **Shellcheck Warnings Are Non-Critical**
   - SC2120/SC2119: Functions don't use arguments but called without `"$@"`
   - SC1091: Source files not available during shellcheck (exist at runtime)
   - Pattern: Functions generate config, don't need arguments

### Architectural Decision Records (ADRs)

#### ADR-001: Two-Tier Security Model
**Date**: 2026-01-28 (documented 2026-02-17)
**Status**: Accepted

**Context**: How should KNEL-Football OS access tier0 infrastructure?

**Decision**: KNEL-Football OS is a secure remote terminal, NOT direct tier0 access.
Flow: KNEL-Football OS → WireGuard VPN → Privileged Access Workstation → Tier0

**Rationale**:
- Defense in depth - multiple hops before tier0
- Compromise of laptop doesn't directly expose tier0
- WireGuard provides encrypted tunnel
- Physical workstation adds another security layer

**Consequences**:
- Network configuration focuses on WireGuard only
- WiFi/Bluetooth permanently disabled
- SSH configured for key-based auth only

#### ADR-002: Docker-Only Build Environment
**Date**: 2026-01-28 (documented 2026-02-17)
**Status**: Accepted

**Context**: How should ISO builds be executed?

**Decision**: ALL build operations run inside Docker containers. No host modifications.

**Rationale**:
- Reproducible builds across different host systems
- No pollution of host environment
- Easy cleanup (just remove containers/images)
- CI/CD friendly

**Consequences**:
- `run.sh` wraps all commands with `docker run`
- ISO build requires `--privileged` for loop devices
- Output artifacts copied via volume mounts

#### ADR-003: LUKS2 Over LUKS1
**Date**: 2026-01-28 (documented 2026-02-17)
**Status**: Accepted

**Context**: Which disk encryption format to use?

**Decision**: Use LUKS2 with Argon2id KDF, AES-256-XTS cipher, 512-bit key.

**Rationale**:
- LUKS2 is newer, more secure format
- Argon2id resists GPU/ASIC attacks better than PBKDF2
- AES-XTS is NIST-approved for disk encryption
- 512-bit key provides security margin

**Consequences**:
- Modern systems only (older grub may not support)
- Boot requires passphrase entry
- No recovery without passphrase

#### ADR-004: BATS Without External Libraries
**Date**: 2026-01-28 (documented 2026-02-17)
**Status**: Accepted

**Context**: BATS test framework libraries were failing to load.

**Decision**: Remove bats-support, bats-assert, bats-file dependencies.
Use custom assertion functions in `tests/test_helper/common.bash`.

**Rationale**:
- External library loading was unreliable
- Custom functions provide same functionality
- Fewer dependencies = fewer failure points
- Easier to debug when tests fail

**Consequences**:
- Custom assertions must be maintained
- Tests don't benefit from upstream library fixes
- But: simpler, more predictable behavior

### Patterns Observed

1. **Hook Organization**
   - `config/hooks/live/` - Runs during live session (before install)
   - `config/hooks/installed/` - Runs after installation
   - Pattern: Source shared functions, call main function

2. **Script Structure**
   ```bash
   #!/bin/bash
   set -euo pipefail
   # Functions that generate config
   main() { ... }
   # Call main if script executed directly
   ```

3. **Test Structure**
   ```bash
   #!/usr/bin/env bats
   @test "description" {
       # Setup
       # Exercise
       # Verify
   }
   ```

### Lessons Learned

1. **test:iso Command Was Broken**
   - `run.sh:172` references deleted `test-iso.sh`
   - Commit c1505a9 removed obsolete scripts including test-iso.sh
   - But run.sh was not updated to remove the command
   - Lesson: When removing files, search for all references

2. **Preseed.cfg Has Hardcoded Passwords**
   - Lines 28-31 contain default passwords
   - These are installer defaults, should be changed on first boot
   - Security risk if users don't change them
   - Lesson: Consider using installer prompts instead

3. **Test Coverage Claim vs Reality**
   - Documentation claimed 95% coverage
   - Reality: 100% static analysis, 0% runtime/VM testing
   - Lesson: Be precise about what "coverage" means

### Action Items for Future Sessions

1. Implement VM boot tests using libvirt
2. Add Secure Boot support (shim-signed, grub-efi-amd64-signed)
3. Create runtime FDE passphrase prompt tests
4. Remove hardcoded passwords from preseed.cfg
5. Fix shellcheck warnings (low priority, non-critical)

---

## Entry 2026-01-28: Initial Build Completion

### Context
First successful ISO build completed after 72 minutes.

### Insights

1. **Live-Build Stages**
   - bootstrap: Downloads base system (longest stage)
   - chroot: Installs packages, runs hooks
   - binary: Creates ISO filesystem
   - checksum: Generates SHA256/MD5

2. **Build Time Breakdown**
   - Total: ~72 minutes
   - bootstrap: ~40 minutes (network dependent)
   - chroot: ~20 minutes
   - binary: ~10 minutes

3. **ISO Size**
   - Final ISO: 450 MB
   - Includes: Debian base, IceWM, WireGuard, security tools
   - Reasonable size for secure workstation

### Patterns

1. **Docker Volume Strategy**
   - `/workspace` mounted read-only (source code)
   - `/build` for intermediate files
   - `/output` for final artifacts
   - Prevents accidental modification of source

2. **Checksum Generation**
   - Generate both SHA256 and MD5
   - Name checksum files after ISO
   - Copy to output directory with ISO

---

*End of Journal. Add new entries at the top.*