# KNEL-Football Secure OS - Agent Behavior Guidelines

## Quick Start

**You are an AI agent (Crush) working on this project.**

### Your First Actions
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`

---

## Where to Find Things

| 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** |

---

## Project Structure

```
/
├── run.sh                 # MAIN ENTRY POINT - All operations
├── Dockerfile             # Multi-stage build environment
├── README.md              # Project overview
├── AGENTS.md              # THIS FILE - Agent guidelines
├── 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

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

tests/                     # Test suite (BATS framework)
output/                    # Build artifacts
```

---

## Agent Workflow

### 1. Start Up
```bash
# Check current state
ls -lh output/
git log --oneline -10
```

### 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
- **Read files before editing** (Critical!)
- Use exact text matching (whitespace matters)
- Test after every change
- Update relevant documentation

### 4. Test Changes
```bash
./run.sh test              # Run all tests
./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)
```bash
./run.sh iso               # Build ISO (60-90 minutes)
tail -f /tmp/knel-iso-build.log
```

### 6. Test ISO (optional)
```bash
./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 and Push
```bash
git status
git diff
git add <files>
git commit -m "type: subject

body (optional)

💘 Generated with Crush


Assisted-by: GLM-4.7 via Crush <crush@charm.land>


"
git push origin main
```

---

## 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
5. NEVER wait for user to ask

### 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
- Delete unused/obsolete files when refactoring
- Update documentation when changing behavior
- Follow existing code style

### DO NOT
- Edit files you haven't read
- 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
- Run destructive git operations without explicit instruction
- Amend commits without explicit approval

---

## Commit Message Format

```
type: subject

body (optional)

Types: feat, fix, docs, test, refactor, chore
```

---

## Error Handling

### Build Failures
- Check `/tmp/knel-iso-build.log`
- Check disk space
- Verify Docker permissions

### Test Failures
- Run tests individually: `bats tests/unit/file.bats`
- Review error messages carefully

### Permission Errors
- Ensure `run.sh` is executable
- Check Docker daemon is running
- Verify user in docker group

---

## Success Criteria

- [ ] All tests pass (`./run.sh test`)
- [ ] Lint passes (`./run.sh lint`)
- [ ] Documentation updated (if needed)
- [ ] Conventional commit message used
- [ ] No security requirements violated
- [ ] Docker workflow followed
- [ ] Changes committed and pushed

---

**Remember**: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow.

**For current status, see STATUS.md.**