docs: track JOURNAL.md in version control
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 <crush@charm.land>
This commit is contained in:
Charles N Wyble
207
JOURNAL.md
Normal file
207
JOURNAL.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user