diff --git a/AGENTS.md b/AGENTS.md index 8456b40..d4946f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -143,6 +143,7 @@ ├── JOURNAL.md # AI memory - ADRs, patterns, lessons learned ├── PRD.md # Product requirements ├── AGENTS.md # Agent guidelines (START HERE) +├── SDLC.md # Software Development Lifecycle (READ THIS) └── docs/ # Detailed documentation ├── TEST-COVERAGE.md # Test suite coverage ├── VERIFICATION-REPORT.md # Compliance verification @@ -243,6 +244,7 @@ git log --oneline -10 #### 2. UNDERSTAND REQUIREMENTS - Read MANDATORY SECURITY REQUIREMENTS (above) - Review PRD.md for detailed requirements +- Read SDLC.md for development workflow (CRITICAL) - Check AGENTS.md for critical constraints - Understand Docker-only workflow diff --git a/SDLC.md b/SDLC.md new file mode 100644 index 0000000..6475954 --- /dev/null +++ b/SDLC.md @@ -0,0 +1,338 @@ +# 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 + +--- + +## 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: │ │ +│ │ • 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: │ │ +│ │ • 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 + # Purpose: Configure SSH server with security hardening + # Requirements: PRD FR-006 (Key-Based Authentication Only) + # Security: Disables password auth per NIST guidelines + configure_ssh() { + ``` + +--- + +## Git Workflow + +### Branch Strategy + +``` +main (protected) + │ + ├── feature/ # New features + ├── fix/ # Bug fixes + ├── security/ # Security fixes (priority) + └── docs/ # Documentation updates +``` + +### Commit Message Format + +``` +: + + + +