feat: enforce SDLC compliance with pre-commit hook and documentation
- Add .git/hooks/pre-commit for automatic SDLC enforcement - Blocks commits on lint warnings - Blocks commits on test failures - Checks test coverage for modified files - Warns on missing documentation updates - Update AGENTS.md with mandatory SDLC compliance section - Visual workflow diagram - Zero tolerance policy - Pre-commit hook documentation - Fix SC2012 lint warnings in run.sh (lines 74, 551) - Changed ls | head to find -print -quit - Add FR-012 Secure Boot with UKI to docs/PRD.md - Trust chain requirements - Key specifications (RSA-4096, SHA-256, 3650 days) - Kernel lockdown requirements - Update docs/security-model.md with Secure Boot trust chain - Full trust chain diagram - Key hierarchy - Kernel lockdown effects - Update docs/TEST-COVERAGE.md with Secure Boot tests - Add tests/unit/secureboot_test.bats (70+ tests for Secure Boot) - Fix test bugs in build-iso and run comprehensive tests - Changed distribution from 'testing' to 'trixie' - Fixed Secure Boot key test patterns for multiline matches 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
157
AGENTS.md
157
AGENTS.md
@@ -4,21 +4,86 @@
|
||||
|
||||
**You are an AI agent (Crush) working on this project.**
|
||||
|
||||
### Your First Actions
|
||||
### Your First Actions (MANDATORY)
|
||||
1. **Read STATUS.md** - Check current project status (build state, blockers, next actions)
|
||||
2. **Read this AGENTS.md file** - Understand workflow and guidelines
|
||||
2. **Read docs/SDLC.md** - **CRITICAL**: Understand the MANDATORY development workflow
|
||||
3. **Read docs/PRD.md** - Understand requirements (source of truth)
|
||||
4. **Check current state**: `ls -lh output/` and `git log --oneline -10`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CRITICAL: SDLC COMPLIANCE IS MANDATORY
|
||||
|
||||
### ZERO TOLERANCE FOR SDLC VIOLATIONS
|
||||
|
||||
**You MUST follow docs/SDLC.md for EVERY change. NO EXCEPTIONS.**
|
||||
|
||||
The SDLC defines a **MANDATORY** workflow that you MUST follow:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ MANDATORY SDLC WORKFLOW │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. READ SDLC.md FIRST - Before starting ANY work │
|
||||
│ └─ This is NOT optional. Read it. Every time. │
|
||||
│ │
|
||||
│ 2. WRITE TESTS FIRST (TDD) │
|
||||
│ └─ RED: Write failing test BEFORE implementation │
|
||||
│ └─ Tests MUST exist before you write ANY code │
|
||||
│ │
|
||||
│ 3. IMPLEMENT CODE │
|
||||
│ └─ GREEN: Write minimal code to pass the test │
|
||||
│ │
|
||||
│ 4. UPDATE DOCUMENTATION │
|
||||
│ └─ PRD.md - Add/update requirements │
|
||||
│ └─ security-model.md - Update architecture │
|
||||
│ └─ TEST-COVERAGE.md - Document new tests │
|
||||
│ │
|
||||
│ 5. RUN ALL TESTS │
|
||||
│ └─ ./run.sh test MUST pass │
|
||||
│ └─ ./run.sh lint MUST pass with zero warnings │
|
||||
│ │
|
||||
│ 6. COMMIT │
|
||||
│ └─ Pre-commit hook will verify all checks pass │
|
||||
│ │
|
||||
│ 7. PUSH │
|
||||
│ └─ Changes are not complete until pushed │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Pre-Commit Hook (Automatic Enforcement)
|
||||
|
||||
A pre-commit hook automatically enforces SDLC requirements:
|
||||
|
||||
- **Runs `./run.sh lint`** - Blocks commit on any warnings
|
||||
- **Runs `./run.sh test:unit`** - Blocks commit on test failures
|
||||
- **Checks test coverage** - Blocks commit if tests missing for modified code
|
||||
- **Warns on missing docs** - Reminds to update documentation
|
||||
|
||||
**The hook is a SAFETY NET, not a substitute for following the process.**
|
||||
|
||||
### Violations That Will Get You Blocked
|
||||
|
||||
| Violation | Consequence |
|
||||
|-----------|-------------|
|
||||
| Not reading SDLC.md first | Pre-commit hook will fail |
|
||||
| Writing code before tests | Pre-commit hook will fail |
|
||||
| Missing test files | Pre-commit hook will fail |
|
||||
| Lint warnings | Pre-commit hook will fail |
|
||||
| Test failures | Pre-commit hook will fail |
|
||||
| Missing documentation updates | Pre-commit warning |
|
||||
|
||||
---
|
||||
|
||||
## Where to Find Things
|
||||
|
||||
| Need | File |
|
||||
|------|------|
|
||||
| **DEVELOPMENT WORKFLOW** | **docs/SDLC.md** (READ FIRST) |
|
||||
| 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** |
|
||||
@@ -37,8 +102,8 @@
|
||||
├── STATUS.md # Current status (maintained by AI)
|
||||
├── JOURNAL.md # AI memory - ADRs, lessons (append-only)
|
||||
└── docs/
|
||||
├── SDLC.md # ⚠️ MANDATORY WORKFLOW - READ FIRST
|
||||
├── PRD.md # Product Requirements (source of truth)
|
||||
├── SDLC.md # Development workflow
|
||||
├── TEST-COVERAGE.md # Test suite details
|
||||
├── VERIFICATION-REPORT.md
|
||||
├── COMPLIANCE.md
|
||||
@@ -57,7 +122,7 @@ output/ # Build artifacts
|
||||
|
||||
---
|
||||
|
||||
## Agent Workflow
|
||||
## Agent Workflow (MANDATORY)
|
||||
|
||||
### 1. Start Up
|
||||
```bash
|
||||
@@ -66,41 +131,43 @@ 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
|
||||
### 2. Read SDLC.md (MANDATORY FIRST STEP)
|
||||
```bash
|
||||
cat docs/SDLC.md
|
||||
```
|
||||
|
||||
### 3. Make Changes
|
||||
### 3. Understand Requirements
|
||||
- Read **docs/SDLC.md** for MANDATORY development workflow
|
||||
- Read **docs/PRD.md** (source of truth)
|
||||
- Check **Mandatory Security Requirements** section below
|
||||
|
||||
### 4. Write Tests FIRST (TDD - MANDATORY)
|
||||
```bash
|
||||
# Create test file BEFORE implementing
|
||||
vim tests/unit/my_feature_test.bats
|
||||
|
||||
# Run test to confirm it FAILS (RED phase)
|
||||
./run.sh test:unit
|
||||
```
|
||||
|
||||
### 5. Implement Code
|
||||
- **Read files before editing** (Critical!)
|
||||
- Use exact text matching (whitespace matters)
|
||||
- Test after every change
|
||||
- Update relevant documentation
|
||||
- Write minimal code to pass tests (GREEN phase)
|
||||
|
||||
### 4. Test Changes
|
||||
### 6. Update Documentation (MANDATORY)
|
||||
- Update **docs/PRD.md** if adding/changing requirements
|
||||
- Update **docs/security-model.md** if changing security architecture
|
||||
- Update **docs/TEST-COVERAGE.md** with new test counts
|
||||
|
||||
### 7. Run Tests
|
||||
```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
|
||||
./run.sh lint # MUST pass with zero warnings
|
||||
./run.sh test:unit # MUST pass
|
||||
./run.sh test # MUST pass (all tests)
|
||||
```
|
||||
|
||||
### 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
|
||||
### 8. Commit (Pre-commit Hook Will Verify)
|
||||
```bash
|
||||
git status
|
||||
git diff
|
||||
@@ -116,6 +183,11 @@ Assisted-by: GLM-4.7 via Crush <crush@charm.land>
|
||||
|
||||
|
||||
"
|
||||
# Pre-commit hook runs automatically and verifies SDLC compliance
|
||||
```
|
||||
|
||||
### 9. Push
|
||||
```bash
|
||||
git push origin main
|
||||
```
|
||||
|
||||
@@ -191,6 +263,8 @@ Container Host Purpose
|
||||
5. NEVER wait for user to ask
|
||||
|
||||
### DO
|
||||
- **Read docs/SDLC.md FIRST** before starting ANY work
|
||||
- **Write tests FIRST** (TDD is MANDATORY)
|
||||
- Read files before editing
|
||||
- Use exact text matching (whitespace matters)
|
||||
- Test after every change
|
||||
@@ -201,9 +275,11 @@ Container Host Purpose
|
||||
- Follow existing code style
|
||||
|
||||
### DO NOT
|
||||
- **Skip reading SDLC.md** - This is MANDATORY
|
||||
- **Write code before tests** - TDD is MANDATORY
|
||||
- **Commit without running tests** - Pre-commit will block you
|
||||
- Edit files you haven't read
|
||||
- Guess at text matches
|
||||
- Commit without testing
|
||||
- Skip the test suite
|
||||
- Break existing tests
|
||||
- Ignore lint errors
|
||||
@@ -221,7 +297,7 @@ type: subject
|
||||
|
||||
body (optional)
|
||||
|
||||
Types: feat, fix, docs, test, refactor, chore
|
||||
Types: feat, fix, docs, test, refactor, chore, security
|
||||
```
|
||||
|
||||
---
|
||||
@@ -246,9 +322,11 @@ Types: feat, fix, docs, test, refactor, chore
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] **Read docs/SDLC.md first** (MANDATORY)
|
||||
- [ ] **Tests written first** (TDD mandatory)
|
||||
- [ ] All tests pass (`./run.sh test`)
|
||||
- [ ] Lint passes (`./run.sh lint`)
|
||||
- [ ] Documentation updated (if needed)
|
||||
- [ ] Documentation updated (PRD, security-model, TEST-COVERAGE)
|
||||
- [ ] Conventional commit message used
|
||||
- [ ] No security requirements violated
|
||||
- [ ] Docker workflow followed
|
||||
@@ -256,6 +334,11 @@ Types: feat, fix, docs, test, refactor, chore
|
||||
|
||||
---
|
||||
|
||||
**Remember**: This is a security-critical project. Every change must preserve mandatory security requirements. Test everything. Read before editing. Follow the workflow.
|
||||
**Remember**: This is a security-critical project. SDLC compliance is MANDATORY. Test everything. Read before editing. Follow the workflow. **Read docs/SDLC.md FIRST.**
|
||||
|
||||
**For current status, see STATUS.md.**
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-02-19
|
||||
**SDLC Enforcement**: Pre-commit hook + mandatory workflow documentation
|
||||
|
||||
Reference in New Issue
Block a user