football/docs/SDLC.md

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

**Version:** 1.1
**Status:** Active
**Last Updated:** 2026-02-19

---

## 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 + JOURNAL.md (ADRs, lessons)
- 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
- **JOURNAL.md is APPEND-ONLY** - Add entries for ADRs, lessons learned, session context

---

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

### Automatic Commit & Push Policy

**AI agents MUST commit and push automatically as work progresses.**

- **Commit early and often** - After each logical unit of work
- **Atomic commits** - One commit per logical change
- **Verbose messages** - Explain WHAT, WHY, and context
- **Push immediately** - Changes are incomplete until pushed

### 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 (MANDATORY)

```
<type>: <subject>

<body explaining WHAT changed and WHY>

<footer - references, breaking changes>

💘 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

**Commit Message Requirements:**
1. **Subject line**: 50 chars max, imperative mood ("add" not "added")
2. **Body**: REQUIRED for non-trivial changes
   - WHAT changed (brief summary)
   - WHY it changed (context/motivation)
   - References to requirements (PRD, issues)
3. **Footer**: Optional, for breaking changes or issue references
4. **Attribution**: Always include AI attribution line

### Atomic Commits

- Each commit = ONE logical change
- Related file changes go in ONE commit
- Unrelated changes = separate commits
- Examples of atomic commits:
  - "feat: add password complexity validation" (src + tests + docs)
  - "fix: correct LUKS cipher configuration" (src file only)
  - "docs: update SDLC with JOURNAL.md requirements" (docs only)

### Commit Frequency

**Commit after EACH of these:**
- Writing a failing test (TDD RED)
- Making test pass (TDD GREEN)
- Refactoring code
- Updating documentation
- Fixing a bug
- Any other logical unit of work

**Always push immediately after commit.**

**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 (562 tests: all pass, 16 skip for VM)
- [ ] 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

- **Reference: docs/SDLC.md** (MANDATORY WORKFLOW - READ FIRST)
- **PRD.md** - Product Requirements Document
- **JOURNAL.md** - AI memory, ADRs, lessons learned (append-only)
- **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 |
| 1.1 | 2026-02-19 | Updated test counts (562 tests) |

---

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

---

## File Editing Standards

### Linux Command-Line Tools (MANDATORY for AI Agents)

**AI agents MUST use standard Linux command-line tools for file editing, not internal text editing functions.**

**Rationale:** Internal editing tools frequently fail due to:
- Whitespace encoding mismatches (tabs vs spaces)
- Line ending differences (CRLF vs LF)
- Unicode/encoding issues
- Exact text matching requirements that are brittle

**Approved Tools:**
| Tool | Use Case |
|------|----------|
| `sed` | Search/replace, line insertions/deletions |
| `awk` | Field extraction, conditional processing |
| `grep` | Pattern matching, filtering |
| `patch` | Apply diff/patch files |
| `cut` | Column extraction |
| `tr` | Character translation |
| `head`/`tail` | Preview file sections |
| `sort`/`uniq` | Sort and deduplicate |

**Standard Patterns:**

```bash
# In-place text replacement
sed -i 's/old_text/new_text/g' file.txt

# Replace on specific line number
sed -i '42s/old/new/' file.txt

# Insert line after match
sed -i '/pattern/a\new_line' file.txt

# Delete matching lines  
sed -i '/pattern/d' file.txt

# Multi-line replacement with extended regex
sed -i -E 's/pattern/replacement/g' file.txt

# Extract specific field (whitespace-delimited)
awk '{print $2}' file.txt

# Conditional processing
awk '/pattern/ {print $1}' file.txt

# Preview changes BEFORE applying (no -i flag)
sed 's/old/new/g' file.txt | head -20
```

**Verification Workflow:**
1. Read file: `cat file.txt` or `head -n 50 file.txt`
2. Preview change: `sed 's/old/new/g' file.txt` (no `-i`)
3. Apply change: `sed -i 's/old/new/g' file.txt`
4. Verify result: `git diff file.txt`