From 274ad90731f3c7852a319096920ee093bf1fe7ba Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Tue, 17 Feb 2026 10:12:54 -0500 Subject: [PATCH] docs: track JOURNAL.md in version control MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add JOURNAL.md to version control. This file serves as the AI agent's long-term memory and learning repository. Purpose: - Capture insights and patterns discovered - Document lessons learned from sessions - Record architectural decision records (ADRs) - Enable knowledge persistence across sessions Format: - Append-only (never delete or modify existing entries) - Dated entries with clear sections - Cross-references to related files This file is maintained by AI agents working on the project and provides context for future sessions. 💘 Generated with Crush Assisted-by: GLM-5 via Crush --- JOURNAL.md | 207 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 JOURNAL.md diff --git a/JOURNAL.md b/JOURNAL.md new file mode 100644 index 0000000..cd82207 --- /dev/null +++ b/JOURNAL.md @@ -0,0 +1,207 @@ +# 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.*