KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove status tracking from AGENTS.md, consolidate in STATUS.md

Browse Source 
- AGENTS.md now contains only agent behavior guidelines
- STATUS.md is the single source for project status
- Updated STATUS.md with current ISO status (built, 816 MB)
- Updated recent commits section in STATUS.md

💘 Generated with Crush

Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-02-19 23:15:25 -05:00
parent ad2d4d3e61
commit 81f97687d9
2 changed files with 161 additions and 619 deletions
Download Patch File Download Diff File Expand all files Collapse all files

752
AGENTS.md
View File

@@ -1,723 +1,261 @@
# KNEL-Football Secure OS - Agent Behavior Guidelines
## 🚀 QUICK START FOR LLM AGENTS
## Quick Start
**You are an AI agent (Crush) working on this project. Start here.**
### Immediate Context (2026-01-28)
- **Project Status**: ✅ Build completed successfully (450 MB ISO created)
- **Build Date**: 2026-01-28 16:30 CST
- **Build Duration**: 72 minutes (9 stages completed)
- **ISO Location**: `output/knel-football-secure.iso`
- **Checksums Verified**: ✅ SHA256 and MD5
**You are an AI agent (Crush) working on this project.**
### Your First Actions
1. **Read this entire AGENTS.md file** (you're reading it now)
2. **Check project status**: `ls -lh output/`
3. **Review current state**: See STATUS section below
4. **Understand requirements**: See MANDATORY SECURITY REQUIREMENTS
5. **Know your workflow**: See AGENT WORKFLOW section
1. **Read STATUS.md** - Check current project status (build state, blockers, next actions)
2. **Read this AGENTS.md file** - Understand workflow and guidelines
3. **Read docs/PRD.md** - Understand requirements (source of truth)
4. **Check current state**: `ls -lh output/` and `git log --oneline -10`
---
## 📋 CURRENT STATUS
## Where to Find Things
### Build Status
- **Last Build**: ✅ SUCCESS (2026-01-28)
- **ISO Artifact**: `knel-football-secure.iso` (450 MB)
- **ISO Checksums**: SHA256 ✅, MD5 ✅
- **Build Log**: `/tmp/knel-iso-build.log` (4,140 lines)
- **All Stages**: 9/9 completed successfully
### Mandatory Requirements Implementation
- ✅ **FR-001: Full Disk Encryption** - LUKS2, AES-256-XTS, 512-bit key
- ✅ **FR-007: Password Complexity** - 14+ chars, PAM pwquality enforced
- ✅ **Encryption Hooks** - Setup and validation created
- ✅ **Security Hardening** - Enhanced password policy implemented
### Compliance Achieved
- ✅ NIST SP 800-111 (Disk Encryption)
- ✅ NIST SP 800-53 (Security Controls)
- ✅ NIST SP 800-63B (Password Guidelines)
- ✅ ISO/IEC 27001 (Information Security)
- ✅ CIS Benchmarks (Security Configuration)
- ✅ DISA STIG (Security Implementation)
### Recent Changes (2026-01-28)
- Added mandatory full disk encryption (LUKS2)
- Added mandatory password complexity requirements
- Created encryption-setup.sh hook
- Created encryption-validation.sh hook
- Enhanced security-hardening.sh with strict password policy
- Updated preseed.cfg with crypto partitioning
- Updated run.sh with test:iso command for VM testing
- Merged test-iso.sh and monitor-build.sh into run.sh
| Need | File |
|------|------|
| Current status (build state, blockers) | **STATUS.md** |
| Requirements (source of truth) | **docs/PRD.md** |
| Development workflow | **docs/SDLC.md** |
| Test coverage details | **docs/TEST-COVERAGE.md** |
| Verification/compliance | **docs/VERIFICATION-REPORT.md** |
| Security architecture | **docs/security-model.md** |
| AI memory/ADRs | **JOURNAL.md** |
---
## 🔒 MANDATORY SECURITY REQUIREMENTS
## Project Structure
### Full Disk Encryption (FDE) - MANDATORY
**Requirement**: ALL systems MUST use full disk encryption with LUKS2
**Technical Specifications**:
- **Cipher**: AES-256-XTS (512-bit key)
- **Format**: LUKS2 with Argon2id KDF
- **Partitioning**: Separate unencrypted /boot (UEFI requirement)
- **Boot Process**: Encryption passphrase required at EVERY system boot
- **Recovery**: No backdoors, no recovery without passphrase
**Encryption Passphrase Requirements** (MANDATORY):
- **Minimum Length**: 14 characters (20+ strongly recommended)
- **Character Classes**: At least 1 of each:
- Uppercase letter (A-Z)
- Lowercase letter (a-z)
- Digit (0-9)
- Special character (!@#$%^&*)
- **Prohibited Patterns**:
- Common words (password, secret, admin, root)
- Sequential patterns (123, abc, qwerty)
- Repeated characters (max 2 consecutive)
**Implementation Files**:
- `config/preseed.cfg` - Debian installer crypto partitioning
- `config/hooks/installed/encryption-setup.sh` - LUKS2 configuration
- `config/hooks/installed/encryption-validation.sh` - Encryption verification
**Compliance**: NIST SP 800-111, NIST SP 800-53 SC-13
### Password Complexity - MANDATORY
**Requirement**: ALL user passwords MUST meet strict complexity requirements
**Password Policy** (MANDATORY):
- **Minimum Length**: 14 characters (20+ strongly recommended)
- **Character Classes**: Minimum 3 of 4 required (all 4 strongly recommended):
- Uppercase letters (A-Z) - Minimum 1 required
- Lowercase letters (a-z) - Minimum 1 required
- Digits (0-9) - Minimum 1 required
- Special characters (!@#$%^&*) - Minimum 1 required
**Additional Requirements**:
- **Dictionary Check**: Reject common dictionary words
- **Username Check**: Reject passwords containing username
- **Sequence Check**: Reject sequential characters (123, abc)
- **Repetition Check**: Max 2 consecutive identical characters
- **Class Repetition**: Max 2 consecutive from same character class
- **Difference**: Min 4 characters different from old password
- **Bad Words**: Reject (password, secret, admin, root, knel, football, tier0, 12345, qwerty)
- **GECOS Check**: Reject passwords containing GECOS field info
**Enforcement**:
- **Mechanism**: PAM pwquality module
- **Scope**: ALL users including root
- **Enforcing Mode**: Reject weak passwords (not just warn)
- **Location**: `/etc/security/pwquality.conf` (created by hooks)
**Implementation File**:
- `src/security-hardening.sh` - Password policy configuration
- `config/hooks/live/security-hardening.sh` - Live hook application
**Compliance**: NIST SP 800-63B, CIS Benchmarks for Debian
### Host System FDE - MANDATORY
**Requirement**: The host system used to build or test the ISO MUST have FDE enabled
**Why This Matters**:
- Building a secure OS on an unencrypted host creates supply chain risk
- An unencrypted test host exposes the secure OS to attacks
- Defense in depth requires protection at every layer
**Enforcement**:
- `./run.sh iso` will FAIL if host FDE not detected
- `./run.sh test:iso` commands will FAIL if host FDE not detected
- This check CANNOT be bypassed
**Detection Methods**:
- Checks for LUKS devices via `lsblk`
- Checks `/etc/crypttab` for encrypted partitions
- Checks if root filesystem is on dm-crypt device
- Checks `/sys/block/dm-*` for LUKS devices
**Implementation**:
- `run.sh` - `check_host_fde()` function
**Compliance**: Supply chain security best practice
---
## 📁 PROJECT STRUCTURE
### Root Level Files
```
/
├── run.sh # MAIN ENTRY POINT - All operations (build/test/lint/iso/monitor/VM)
├── run.sh # MAIN ENTRY POINT - All operations
├── Dockerfile # Multi-stage build environment
├── README.md # Project documentation
├── README.md # Project overview
├── AGENTS.md # THIS FILE - Agent guidelines
├── STATUS.md # Manager status report (quick-glance)
├── JOURNAL.md # AI memory - ADRs, insights, lessons (append-only)
└── .gitignore # Git ignore patterns
```
├── STATUS.md # Current status (maintained by AI)
├── JOURNAL.md # AI memory - ADRs, lessons (append-only)
└── docs/
├── PRD.md # Product Requirements (source of truth)
├── SDLC.md # Development workflow
├── TEST-COVERAGE.md # Test suite details
├── VERIFICATION-REPORT.md
├── COMPLIANCE.md
└── security-model.md
### Documentation Files
```
├── STATUS.md # Manager report - current status, blockers, next actions
├── JOURNAL.md # AI memory - ADRs, patterns, lessons learned
├── AGENTS.md # Agent guidelines (START HERE)
└── docs/ # Detailed documentation
├── PRD.md # Product Requirements Document
├── SDLC.md # Software Development Lifecycle (READ THIS)
├── TEST-COVERAGE.md # Test suite coverage
├── VERIFICATION-REPORT.md # Compliance verification
├── COMPLIANCE.md # Compliance standards
└── security-model.md # Security architecture
```
src/ # Source scripts
config/ # Configuration files
├── includes.installer/ # Installer configs (preseed.cfg)
├── hooks/live/ # Live system hooks
├── hooks/installed/ # Post-install hooks
└── package-lists/ # Package lists
**STATUS.md Purpose**:
- Quick-glance project status for managers
- What's working, what's broken, current blockers
- Next actions and metrics
- Maintained by AI agent, read by humans
**JOURNAL.md Purpose**:
- Long-term memory for AI agents
- Architectural Decision Records (ADRs)
- Patterns observed, lessons learned
- APPEND-ONLY - never modify existing entries
### Source Code
```
src/
├── security-hardening.sh # Security hardening functions
├── firewall-setup.sh # Firewall configuration
├── build-iso.sh # ISO build orchestration
├── run.sh # Alternative run script
├── run-new.sh # Enhanced run script
└── build.sh # Build script
```
### Configuration
```
config/
├── preseed.cfg # Debian installer preseed (with encryption)
├── hooks/
│ ├── live/ # Hooks during live system
│ │ ├── desktop-environment.sh
│ │ ├── firewall-setup.sh
│ │ ├── qr-code-import.sh
│ │ ├── security-hardening.sh
│ │ └── usb-automount.sh
│ └── installed/ # Hooks after installation
│ ├── disable-package-management.sh
│ ├── encryption-setup.sh # LUKS2 encryption setup
│ ├── encryption-validation.sh # Encryption verification
│ └── install-scripts.sh
└── package-lists/
└── knel-football.list.chroot # Package list
```
### Tests
```
tests/
├── unit/ # Unit tests for individual functions
│ ├── build_test.bats
│ ├── firewall_test.bats
│ ├── security_test.bats
│ └── run_test.bats
├── integration/ # Integration tests for workflows
│ └── config_test.bats
├── security/ # Security compliance tests
│ └── compliance_test.bats
├── system/ # System/runtime tests (VM boot, FDE, Secure Boot)
│ ├── boot_test.bats
│ ├── secureboot_test.bats
│ └── fde_test.bats
├── test_helper/ # Test utilities
│ └── common.bash
└── simple_test.bats # Basic bats test
```
### Output
```
output/
└── knel-football-secure.iso # 450 MB ISO (✅ BUILT AND VERIFIED)
└── knel-football-secure.iso.sha256 # SHA256 checksum
└── knel-football-secure.iso.md5 # MD5 checksum
tests/ # Test suite (BATS framework)
output/ # Build artifacts
```
---
## 🤖 AGENT WORKFLOW
## Agent Workflow
### Standard Operating Procedure
#### 1. START UP (First Action)
### 1. Start Up
```bash
# Check current state
ls -lh output/
# Read this file (AGENTS.md)
cat AGENTS.md
# Review recent changes
git log --oneline -10
```
#### 2. UNDERSTAND REQUIREMENTS
- Read MANDATORY SECURITY REQUIREMENTS (above)
- Review docs/PRD.md for detailed requirements
- Read docs/SDLC.md for development workflow (CRITICAL)
- Check AGENTS.md for critical constraints
- Understand Docker-only workflow
### 2. Understand Requirements
- Read **docs/PRD.md** (source of truth)
- Read **docs/SDLC.md** for development workflow
- Check **MANDATORY SECURITY REQUIREMENTS** section below
#### 3. MAKE CHANGES
### 3. Make Changes
- **Read files before editing** (Critical!)
- Use conventional commit messages
- Use exact text matching (whitespace matters)
- Test after every change
- Update relevant documentation
#### 4. TEST CHANGES
### 4. Test Changes
```bash
# Run tests (inside Docker)
./run.sh test # Run all tests
./run.sh lint # Run linting
./run.sh lint # Run shellcheck
./run.sh test:unit # Unit tests only
./run.sh test:integration # Integration tests only
./run.sh test:security # Security tests only
```
#### 5. BUILD ISO (if needed)
### 5. Build ISO (if needed)
```bash
# Build ISO (60-90 minutes)
./run.sh iso
# Monitor progress
./run.sh iso # Build ISO (60-90 minutes)
tail -f /tmp/knel-iso-build.log
# Verify output
cd output/
sha256sum -c knel-football-secure.iso.sha256
md5sum -c knel-football-secure.iso.md5
```
#### 6. TEST ISO (optional)
### 6. Test ISO (optional)
```bash
# Test ISO in VM (runs on host, not in Docker)
./run.sh test:iso create # Create and boot test VM
./run.sh test:iso console # Connect to VM console
./run.sh test:iso status # Show VM status
./run.sh test:iso destroy # Remove VM
./run.sh test:iso create # Create and boot test VM
./run.sh test:iso console # Connect to VM console
./run.sh test:iso status # Show VM status
./run.sh test:iso destroy # Remove VM
```
#### 7. COMMIT CHANGES
### 7. Commit and Push
```bash
# Review changes
git status
git diff
# Stage files
git add <files>
# Commit with conventional message
git commit -m "type: subject
body
body (optional)
💘 Generated with Crush
Assisted-by: GLM-4.7 via Crush <crush@charm.land>
"
```
#### 8. PUSH TO REMOTE
```bash
# Push changes
"
git push origin main
```
### Important Rules
---
#### 🔴 CRITICAL: AUTO-COMMIT RULE
**After completing ANY work, you MUST:**
1. Check `git status` for uncommitted changes
2. Stage all relevant changes with `git add`
## Mandatory Security Requirements
### Full Disk Encryption (FDE)
**Requirement**: ALL systems MUST use LUKS2 encryption
- **Cipher**: AES-256-XTS (512-bit key)
- **Format**: LUKS2 with Argon2id KDF
- **Passphrase**: 14+ chars, mixed case, digit, special char
- **Implementation**: `config/includes.installer/preseed.cfg`, `config/hooks/installed/encryption-*.sh`
### Password Complexity
**Requirement**: ALL passwords MUST meet strict complexity
- **Minimum**: 14 characters
- **Classes**: 3 of 4 (upper, lower, digit, special)
- **Enforcement**: PAM pwquality module
- **Implementation**: `src/security-hardening.sh`, `config/hooks/live/security-hardening.sh`
### Host System FDE
**Requirement**: Build/test host MUST have FDE enabled
- `./run.sh iso` will FAIL if host FDE not detected
- `./run.sh test:iso` will FAIL if host FDE not detected
- Detection: checks for LUKS devices, `/etc/crypttab`, dm-crypt
---
## Docker Workflow
### Why Docker?
- Reproducible builds
- Isolated environment
- No host system pollution
### Volumes
```
Container Host Purpose
/workspace ./ Project root (read-only)
/build ./tmp Build intermediates
/output ./output Final artifacts
```
### Commands Inside Container
- `./run.sh build` - Build Docker image
- `./run.sh test` - Run all tests
- `./run.sh lint` - Run linting
- `./run.sh iso` - Build ISO
### Commands on Host
- `./run.sh test:iso` - Test ISO with libvirt
### NEVER
- Create directories in /home
- Install packages on host
- Modify host system files
- Run live-build commands on host
---
## Important Rules
### AUTO-COMMIT (Critical)
**After completing ANY work:**
1. Check `git status`
2. Stage relevant changes
3. Commit with conventional message
4. Push to remote with `git push origin main`
5. NEVER wait for user to ask "is everything committed?"
4. Push to remote
5. NEVER wait for user to ask
**This is NOT optional.** The user should NEVER have to ask about commits.
#### ✅ DO
- **AUTO-COMMIT AND PUSH** after completing work (see CRITICAL rule above)
- Read files before editing them
### DO
- Read files before editing
- Use exact text matching (whitespace matters)
- Test after every change
- Run full test suite before committing
- **Double-check `git status` before ANY commit** - verify staged files match intent
- **Delete unused/obsolete files** when refactors or feature removals make them irrelevant
- **Quote git paths with brackets/parentheses** (e.g., `git add "src/app/[candidate]/**"`) to prevent shell glob/subshell expansion
- **Use non-interactive git rebase** - set `GIT_EDITOR=: GIT_SEQUENCE_EDITOR=:` or pass `--no-edit` to avoid opening editors
- **NEVER run destructive git operations** (`git reset --hard`, `rm`, `git checkout`/`git restore` to older commits) unless user gives explicit written instruction - treat as catastrophic
- **NEVER amend commits** (`git commit --amend`) without explicit written approval from user
- Double-check `git status` before ANY commit
- Delete unused/obsolete files when refactoring
- Update documentation when changing behavior
- Follow existing code style
- Use conventional commit messages
- Commit frequently with atomic changes
- Run lint checks
#### ❌ DO NOT
- **Wait for user to ask about commits** - AUTO-COMMIT ALWAYS
### DO NOT
- Edit files you haven't read
- Guess at text matches (be precise)
- Guess at text matches
- Commit without testing
- Skip the test suite
- Break existing tests
- Ignore lint errors
- Make unrelated changes in one commit
- Modify host system directly
- Create directories in /home
- Run destructive git operations without explicit instruction
- Amend commits without explicit approval
---
## 🐳 DOCKER-ONLY WORKFLOW (CRITICAL)
## Commit Message Format
### Why Docker?
- Reproducible builds
- Isolated environment
- No host system pollution
- Consistent across machines
- Easy to clean up
### Volumes and Directories
```
Container Side Host Side Purpose
/workspace ./ Project root (read-only)
/build ./tmp Build intermediate files
/output ./output Final artifacts only
```
type: subject
### Commands Run Inside Container
- `./run.sh build` - Build Docker image
- `./run.sh test` - Run all tests
- `./run.sh lint` - Run linting
- `./run.sh iso` - Build ISO
body (optional)
### Commands Run on Host
- `./run.sh test:iso` - Test ISO with libvirt (VM test only)
### NEVER Do These
- ❌ Create directories in /home
- ❌ Install packages on host
- ❌ Modify host system files
- ❌ Write files outside Docker volumes
- ❌ Run live-build commands on host
---
## 🧪 TESTING COVERAGE
### Test Suite Overview (100% Coverage Targeted)
- ✅ **Unit Tests** - Comprehensive tests for all shell scripts
- `tests/unit/run_test.bats` - Main run.sh entry point
- `tests/unit/run_comprehensive_test.bats` - Comprehensive run.sh coverage
- `tests/unit/security-hardening_test.bats` - Security hardening functions
- `tests/unit/firewall-setup_test.bats` - Firewall configuration
- `tests/unit/build-iso_comprehensive_test.bats` - ISO build orchestration
- `tests/unit/encryption-setup_test.bats` - LUKS2 encryption setup
- `tests/unit/encryption-validation_test.bats` - Encryption validation
- ✅ **Integration Tests** - End-to-end workflows
- `tests/integration/config_test.bats` - Configuration validation
- `tests/integration/e2e_test.bats` - Complete workflow testing
- ✅ **Security Tests** - Compliance and security requirements
- `tests/security/compliance_test.bats` - Security compliance validation
- `tests/security/compliance_comprehensive_test.bats` - Full FR-001/FR-007 coverage
- `tests/security/encryption_comprehensive_test.bats` - Encryption configuration validation
### Test Commands
```bash
./run.sh test # Run all tests (unit + integration + security)
./run.sh test:unit # Unit tests only
./run.sh test:integration # Integration tests only
./run.sh test:security # Security/compliance tests only
./run.sh lint # Run shellcheck on all shell scripts
```
### Test Suite Status
- ✅ **All tests passing**: 31/31 tests
- ✅ **Unit tests**: Working (12 tests)
- ✅ **Integration tests**: Working (6 tests)
- ✅ **Security tests**: Working (13 tests)
- ✅ **Test execution**: `./run.sh test`
### Test Orchestration
- **run.sh** - Main entry point for test execution
- **BATS** - Test framework (v1.11.1)
- **Direct execution** - Tests run directly via bats (no wrapper)
- Supports: unit, integration, security, e2e, compliance, encryption, all
- Provides colored output and pass/fail statistics
- Orchestrates BATS test execution
### Coverage Goals
- ✅ All shell scripts have unit tests
- ✅ All configuration files are validated
- ✅ All security hooks are tested
- ✅ All mandatory requirements have compliance tests
- ✅ End-to-end workflows are tested
### Running Tests After Changes
```bash
# After any changes, run:
./run.sh lint # Check syntax first
./run.sh test # Run full test suite
./run.sh test:security # Verify security requirements
# If any test fails, fix it before committing
Types: feat, fix, docs, test, refactor, chore
```
---
## 📚 DOCUMENTATION FILES
### Quick Reference
- **AGENTS.md** - THIS FILE - Start here
- **README.md** - Project overview and quick commands
- **docs/PRD.md** - Product Requirements Document (detailed)
### Detailed Documentation (docs/)
- **docs/SDLC.md** - Software Development Lifecycle
- **docs/TEST-COVERAGE.md** - Test suite coverage and details
- **docs/VERIFICATION-REPORT.md** - Verification and compliance report
- **docs/COMPLIANCE.md** - Compliance standards and requirements
- **docs/security-model.md** - Security architecture and design
---
## 🔑 KEY CONCEPTS
### Build Process
1. **Docker Build**: Create build environment (~2 minutes)
2. **lb config**: Configure live-build (~30 seconds)
3. **lb bootstrap**: Download and install base system (~13 minutes)
4. **lb chroot**: Install packages and apply hooks (~8 minutes)
5. **lb installer**: Configure Debian installer (~2 minutes)
6. **lb binary**: Create binary filesystem (~4 minutes)
7. **lb checksum**: Generate checksums (~1 minute)
### Encryption Setup
1. **Preseed**: Configure crypto partitioning
2. **Live Hook**: Apply encryption during live session
3. **Install Hook**: Configure LUKS2 after installation
4. **Validation Hook**: Verify encryption post-install
### Security Layers
1. **Full Disk Encryption** - LUKS2 (mandatory)
2. **Password Complexity** - PAM pwquality (mandatory)
3. **Firewall** - nftables (all inbound denied, outbound VPN only)
4. **WiFi/Bluetooth** - Blacklisted (permanently disabled)
5. **SSH** - Client-only (no server, outbound connections only)
6. **Package Management** - Disabled for security
---
## 🚨 CRITICAL ERROR HANDLING
## Error Handling
### Build Failures
- Check `/tmp/knel-iso-build.log` for errors
- Review RESUME.md for common issues
- Check `/tmp/knel-iso-build.log`
- Check disk space
- Verify Docker permissions
### Test Failures
- Run tests individually: `bats tests/unit/file.bats`
- Check test helper functions
- Verify setup/teardown functions
- Review error messages carefully
### Permission Errors
- Ensure `run.sh` is executable
- Check Docker daemon is running
- Verify user in docker group
- Check volume mount permissions
---
## 🔄 SDLC WORKFLOW (Software Development Lifecycle)
## Success Criteria
### Before Making Changes
1. **Read relevant documentation**:
- AGENTS.md (this file) - For agent guidelines
- docs/PRD.md - For requirements
- docs/SDLC.md - For development workflow
- README.md - For quick commands
- docs/TEST-COVERAGE.md - For test details
- docs/VERIFICATION-REPORT.md - For verification results
2. **Create feature branch** (optional but recommended):
```bash
git checkout -b feature/your-feature-name
```
### Making Changes
1. **Read files before editing** (Critical!)
2. **Use exact text matching** (whitespace matters)
3. **Make small, atomic changes**
4. **Follow existing code style**
### Testing Changes (MANDATORY)
**Before committing, ALWAYS run:**
```bash
# 1. Lint checks (syntax validation)
./run.sh lint
# 2. Run unit tests
./run.sh test:unit
# 3. Run integration tests
./run.sh test:integration
# 4. Run security/compliance tests
./run.sh test:security
# 5. Run full test suite
./run.sh test
```
**Test Suite Must Pass Before Committing**
### Committing Changes
1. **Review changes**:
```bash
git status
git diff
```
2. **Stage files**:
```bash
git add <files>
```
3. **Commit with conventional message**:
```bash
git commit -m "type: subject
body (optional)
💘 Generated with Crush
Assisted-by: GLM-4.7 via Crush <crush@charm.land>
"
```
**Types**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `test`: Test changes
- `refactor`: Code refactoring
- `chore`: Maintenance tasks
### After Committing
1. **Push to remote**:
```bash
git push origin main
# Or push feature branch:
git push origin feature/your-feature-name
```
2. **Merge feature branch** (if using branches):
```bash
git checkout main
git merge feature/your-feature-name
git push origin main
```
### SDLC Checklist
Before marking work complete:
- [ ] All tests pass (`./run.sh test`)
- [ ] Lint checks pass (`./run.sh lint`)
- [ ] Security requirements verified (`./run.sh test:security`)
- [ ] Lint passes (`./run.sh lint`)
- [ ] Documentation updated (if needed)
- [ ] Conventional commit message used
- [ ] Changes committed and pushed to remote
- [ ] No security requirements violated
- [ ] Docker workflow followed
- [ ] Changes committed and pushed
---
## 📞 GETTING HELP
**Remember**: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow.
### Check These First
1. **AGENTS.md** - This file
2. **README.md** - Quick commands
3. **docs/PRD.md** - Requirements
4. **docs/SDLC.md** - Development workflow
5. **docs/TEST-COVERAGE.md** - Test details
6. **docs/VERIFICATION-REPORT.md** - Verification results
7. **JOURNAL.md** - Session history
### Debug Mode
```bash
# Verbose output
./run.sh -v test
# Verbose ISO build
./run.sh -v iso
# View build log
tail -f /tmp/knel-iso-build.log
```
---
## ✅ CHECKLIST BEFORE WORK
- [ ] Read AGENTS.md (this file)
- [ ] Check current build status
- [ ] Understand mandatory security requirements
- [ ] Know Docker-only workflow
- [ ] Have test command ready
- [ ] Know commit message format
---
## 🎯 SUCCESS CRITERIA
Your work is successful when:
- ✅ All tests pass (`./run.sh test`)
- ✅ Lint passes (`./run.sh lint`)
- ✅ Documentation updated
- ✅ Conventional commit messages used
- ✅ No security requirements violated
- ✅ Docker workflow followed
- ✅ Changes tested before commit
---
## 📝 LAST UPDATED
- **Date**: 2026-02-17
- **Status**: Build in progress, ISO being rebuilt with latest changes
- **Test Coverage**: ✅ WORKING (111 tests: 92 pass, 19 skip for libvirt)
- **Test Files**: 19 test files (1 simple, 10 unit, 2 integration, 3 security, 3 system)
- **Documentation**: Consolidated in docs/ directory
- **Root Directory**: Cleaned (AGENTS.md, README.md, PRD.md, Dockerfile, run.sh)
- **Scripts Consolidated**: test-iso.sh and monitor-build.sh merged into run.sh
- **SDLC Workflow**: Documented and enforced
### Test Suite Status
- ✅ All tests passing (111 total: 92 pass, 19 skip)
- ✅ Unit tests: Working (10 files, ~13 tests)
- ✅ Integration tests: Working (2 files, 6 tests)
- ✅ Security tests: Working (3 files, 44 tests)
- ✅ System tests: Working (3 files, 47 tests)
- ✅ Test execution: `./run.sh test`
---
**Remember**: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow. Be thorough.
**For current status, see STATUS.md.**

28
STATUS.md
View File

@@ -1,15 +1,15 @@
# KNEL-Football Project Status Report
> **Last Updated**: 2026-02-19 17:05 CST
> **Last Updated**: 2026-02-19 22:10 CST
> **Maintained By**: AI Agent (Crush)
> **Purpose**: Quick-glance status for project manager
---
## Current Status: ✅ READY TO BUILD ISO
## Current Status: ✅ ISO BUILT
### Executive Summary
All 562 tests passing. PRD → Docs → Code → Tests fully aligned. No TODO/FIXME in codebase. Ready for ISO build.
All 562 tests passing. ISO built successfully (816 MB). PRD → Docs → Code → Tests fully aligned.
---
@@ -69,21 +69,25 @@ Code Quality: 0 TODO/FIXME, 0 shellcheck warnings
## Next Action
**BUILD ISO**:
ISO built successfully. Ready for deployment or further development.
To rebuild ISO:
```bash
./run.sh iso
```
Estimated time: 60-90 minutes
---
## Recent Commits (This Session)
## Recent Commits
```
cc5d200 test: expand integration tests and add unit tests for hooks
13c446e chore: remove redundant build_test.bats
8fbf3c0 test: replace stub tests with comprehensive assertions
ad2d4d3 docs: add architecture diagram and fix FR-001 links
f5bbcad docs: add clickable links and update to Debian 13 stable
29654c6 fix: pin distribution to trixie (Debian 13 stable)
987c70b fix: remove obsolete icewm-themes package
89cd8a1 fix: copy config files to live-build config directory in run.sh
7e8bbf7 fix: copy config files to correct live-build config directory
89fd8b7 fix: move preseed.cfg to includes.installer for live-build
```
---
@@ -95,7 +99,7 @@ cc5d200 test: expand integration tests and add unit tests for hooks
| Docker Image | `knel-football-dev:latest` |
| Build Command | `./run.sh iso` |
| Output Location | `output/knel-football-secure.iso` |
| ISO Status | ⏳ NOT BUILT |
| ISO Status | ✅ BUILT (816 MB, 2026-02-19 22:02) |
---
@@ -143,7 +147,7 @@ Tier0 Infrastructure
| Static Coverage | 100% | 100% ✅ |
| Shellcheck Warnings | 0 | 0 ✅ |
| TODO/FIXME in Code | 0 | 0 ✅ |
| ISO Status | ⏳ READY | Build needed |
| ISO Status | ✅ BUILT | 816 MB |
---