football/docs/SDLC.md

# KNEL-Football Secure OS - Software Development Lifecycle (SDLC)

**Version:** 1.0
**Status:** Active
**Last Updated:** 2026-02-17

---

## Overview

This document defines the mandatory Software Development Lifecycle (SDLC) for the KNEL-Football Secure OS project. As a **critical infrastructure project** supporting CMMC/FedRAMP/ITAR compliance, we maintain zero tolerance for security defects and require strict adherence to these processes.

---

## Core Principles

### 1. Security First
- Every change must preserve or enhance security
- No shortcuts, no exceptions, no "temporary" bypasses
- All code is security-critical code

### 2. Test-Driven Development (TDD)
- **Red → Green → Refactor** - Mandatory workflow
- No code without tests
- No merge without passing tests

### 3. Defense in Depth
- Multiple layers of verification
- Automated + manual review
- Build-time + runtime validation

### 4. Documentation-Code-Test Synchronization (MANDATORY)
- **All three must be in sync at ALL times**
- Documentation = PRD requirements + implementation docs
- Code = Actual implementation in src/ and config/
- Tests = Verification that code matches documentation
- **NO STUB TESTS ALLOWED** - Every test must verify actual behavior
- When changing code: update tests AND documentation
- When changing documentation: update code AND tests
- When changing tests: verify code matches AND update documentation if needed

---

## Test-Driven Development (TDD) Workflow

### Mandatory TDD Process

```
┌─────────────────────────────────────────────────────────────┐
│                     TDD WORKFLOW                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. RED: Write a failing test                               │
│     ┌─────────────────────────────────────────────────┐     │
│     │ • Write test FIRST (before implementation)       │     │
│     │ • Test MUST fail initially                       │     │
│     │ • Run: ./run.sh test:<suite>                     │     │
│     │ • Confirm test fails for RIGHT reason            │     │
│     └─────────────────────────────────────────────────┘     │
│                          ↓                                  │
│  2. GREEN: Write minimal code to pass                       │
│     ┌─────────────────────────────────────────────────┐     │
│     │ • Write MINIMUM code to make test pass           │     │
│     │ • Do not over-engineer                           │     │
│     │ • Run: ./run.sh test:<suite>                     │     │
│     │ • Confirm test passes                            │     │
│     └─────────────────────────────────────────────────┘     │
│                          ↓                                  │
│  3. REFACTOR: Improve code quality                          │
│     ┌─────────────────────────────────────────────────┐     │
│     │ • Clean up implementation                        │     │
│     │ • Remove duplication                             │     │
│     │ • Improve readability                            │     │
│     │ • Run: ./run.sh test (ALL tests must pass)       │     │
│     └─────────────────────────────────────────────────┘     │
│                          ↓                                  │
│                    REPEAT AS NEEDED                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### TDD Rules

1. **Rule 1**: You MUST write a failing test before writing implementation code
2. **Rule 2**: You MUST NOT write more implementation than needed to pass the test
3. **Rule 3**: You MUST run ALL tests after refactoring

### Test Execution Commands

```bash
# Run all tests
./run.sh test

# Run specific test suites
./run.sh test:unit          # Unit tests only
./run.sh test:integration   # Integration tests only
./run.sh test:security      # Security/compliance tests only

# Run linting (shellcheck)
./run.sh lint
```

### Test Coverage Requirements

| Category | Minimum Coverage | Target |
|----------|------------------|--------|
| Security functions | 100% | 100% |
| Encryption setup | 100% | 100% |
| Password policy | 100% | 100% |
| Firewall rules | 100% | 100% |
| Build scripts | 80% | 95% |
| Utility functions | 80% | 90% |

---

## Pre-Commit Checklist

**Before committing ANY change, verify:**

- [ ] All tests pass: `./run.sh test`
- [ ] Lint passes with zero warnings: `./run.sh lint`
- [ ] Security tests pass: `./run.sh test:security`
- [ ] Code follows existing style
- [ ] Commit message follows conventional format
- [ ] No secrets, credentials, or sensitive data in commit

---

## Code Quality Standards

### Shell Script Standards

1. **Zero Shellcheck Warnings**
   - All shell scripts MUST pass shellcheck with zero warnings
   - No exceptions, no suppressions without documented justification
   - Run: `./run.sh lint`

2. **Strict Mode**
   - All scripts MUST use: `set -euo pipefail`
   - No uninitialized variables
   - No unset variable access

3. **Error Handling**
   - All errors must be handled explicitly
   - Use `|| true` only when failure is expected and acceptable
   - Log all errors with context

4. **Security Conventions**
   - Quote all variables: `"$variable"`
   - Use `[[ ]]` for tests (not `[ ]`)
   - Avoid `eval` and other code injection vectors
   - Never log secrets or credentials

### Documentation Standards

1. **Code Comments**
   - Explain WHY, not WHAT
   - Reference requirements (e.g., "PRD FR-006: Key-based auth only")
   - Document security implications

2. **Function Documentation**
   ```bash
   # Function: configure_ssh_client
   # Purpose: Configure SSH client for outbound connections only
   # Requirements: PRD FR-006 (SSH Client - No inbound services)
   # Security: Client-only, hardened cipher suite
   configure_ssh_client() {
   ```

---

## Git Workflow

### Branch Strategy

```
main (protected)
  │
  ├── feature/<feature-name>     # New features
  ├── fix/<bug-name>             # Bug fixes
  ├── security/<issue-name>      # Security fixes (priority)
  └── docs/<doc-name>            # Documentation updates
```

### Commit Message Format

```
<type>: <subject>

<body (optional)>

<footer (optional)>

💘 Generated with Crush

Assisted-by: <AI-Model> via Crush <crush@charm.land>
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `security`: Security vulnerability fix
- `docs`: Documentation changes
- `test`: Test additions/modifications
- `refactor`: Code refactoring
- `chore`: Maintenance tasks

**Example:**
```
security: disable SSH password authentication

PRD FR-006 requires key-based authentication only.
PasswordAuthentication was incorrectly set to 'yes',
violating the security requirement.

Fixes: SSH config now uses PasswordAuthentication no

💘 Generated with Crush

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

### Merge Requirements

- [ ] All tests pass
- [ ] Zero lint warnings
- [ ] At least one approval (for team projects)
- [ ] No unresolved conversations
- [ ] Branch up to date with main

---

## Security Review Process

### When Security Review is Required

1. Any change to:
   - Encryption configuration
   - Password policy
   - Firewall rules
   - SSH configuration
   - Authentication mechanisms
   - Kernel module blacklists

2. Any change touching files in:
   - `config/hooks/installed/`
   - `config/hooks/live/`
   - `src/security-hardening.sh`
   - `src/firewall-setup.sh`

### Security Review Checklist

- [ ] Change aligns with PRD requirements
- [ ] No security regressions introduced
- [ ] Complies with NIST SP 800-53 controls
- [ ] Complies with NIST SP 800-111 (encryption)
- [ ] Complies with CIS Benchmarks
- [ ] Audit logging covers the change
- [ ] Documentation updated

---

## Compliance Mapping

### NIST SP 800-53 Control Mapping

| Control | Implementation | Test |
|---------|----------------|------|
| AC-3 (Access Enforcement) | SSH key-only auth | `test:security` |
| AU-2 (Audit Events) | auditd rules | `test:security` |
| SC-13 (Crypto Protection) | LUKS2 encryption | `test:security` |
| SC-28 (Data at Rest) | Full disk encryption | `test:security` |

### Compliance Test Execution

```bash
# Run compliance-focused tests
./run.sh test:security

# Run encryption-specific tests
./run.sh test:encryption

# Run full compliance verification
./run.sh test
```

---

## Release Process

### Pre-Release Checklist

- [ ] All tests pass (78 tests: 63 pass, 15 skip for libvirt)
- [ ] Zero lint warnings
- [ ] Security review complete
- [ ] Documentation updated
- [ ] CHANGELOG updated
- [ ] Version bump in applicable files

### Build Verification

```bash
# Build ISO
./run.sh iso

# Verify checksums
cd output/
sha256sum -c knel-football-secure.iso.sha256
md5sum -c knel-football-secure.iso.md5
```

---

## Incident Response

### Security Vulnerability Found

1. **STOP** - Do not commit the vulnerable code
2. **DOCUMENT** - Create issue tracking the vulnerability
3. **FIX** - Implement fix following TDD process
4. **VERIFY** - All tests pass, security tests pass
5. **REVIEW** - Security review of the fix
6. **RELEASE** - Expedited release if critical

---

## References

- **PRD.md** - Product Requirements Document
- **AGENTS.md** - Agent Behavior Guidelines
- **README.md** - Project overview and commands
- **docs/TEST-COVERAGE.md** - Test suite documentation
- **docs/VERIFICATION-REPORT.md** - Verification results

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-02-17 | Initial SDLC document |

---

**This SDLC is MANDATORY for all changes to this project.**

**Copyright © 2026 Known Element Enterprises LLC**
**License: GNU Affero General Public License v3.0 only**