KNEL/football
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: enforce JOURNAL.md updates and auto-commit/push in SDLC

Browse Source 
Added JOURNAL.md to mandatory documentation synchronization:
- AGENTS.md: Added JOURNAL.md to documentation step and success criteria
- SDLC.md: Added JOURNAL.md to doc sync requirements and references
- pre-commit hook: Check for JOURNAL.md updates on new functions

Strengthened auto-commit/push requirements:
- Commit early and often (after each logical unit of work)
- Atomic commits (one commit per logical change)
- Verbose conventional commit messages (WHAT, WHY, context)
- Push immediately after every commit

Reference: User request for JOURNAL.md sync and auto-commit policy

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-02-20 09:28:26 -05:00
parent 59122570a6
commit aedaabf82c
2 changed files with 152 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/SDLC.md
View File

@@ -31,13 +31,14 @@ This document defines the mandatory Software Development Lifecycle (SDLC) for th
### 4. Documentation-Code-Test Synchronization (MANDATORY)
- **All three must be in sync at ALL times**
- Documentation = PRD requirements + implementation docs
- 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
---
@@ -171,6 +172,15 @@ This document defines the mandatory Software Development Lifecycle (SDLC) for th
## 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
```
@@ -182,14 +192,14 @@ main (protected)
└── docs/<doc-name> # Documentation updates
```
### Commit Message Format
### Commit Message Format (MANDATORY)
```
<type>: <subject>
<body (optional)>
<body explaining WHAT changed and WHY>
<footer (optional)>
<footer - references, breaking changes>
💘 Generated with Crush
@@ -205,6 +215,37 @@ Assisted-by: <AI-Model> via Crush <crush@charm.land>
- `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
@@ -326,7 +367,9 @@ md5sum -c knel-football-secure.iso.md5
## 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