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

# 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

   # 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

# 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

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

# 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