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

118
AGENTS.md
View File

@@ -159,6 +159,7 @@ vim tests/unit/my_feature_test.bats
- Update **docs/PRD.md** if adding/changing requirements - Update **docs/PRD.md** if adding/changing requirements
- Update **docs/security-model.md** if changing security architecture - Update **docs/security-model.md** if changing security architecture
- Update **docs/TEST-COVERAGE.md** with new test counts - Update **docs/TEST-COVERAGE.md** with new test counts
- Update **JOURNAL.md** with ADRs, lessons learned, session notes (append-only)
### 7. Run Tests ### 7. Run Tests
```bash ```bash
@@ -254,13 +255,85 @@ Container Host Purpose
## Important Rules ## Important Rules
### AUTO-COMMIT (Critical) ### AUTO-COMMIT & AUTO-PUSH (CRITICAL)
**After completing ANY work:**
1. Check `git status` **You MUST commit and push AUTOMATICALLY as you work. NEVER wait for user to ask.**
2. Stage relevant changes
3. Commit with conventional message #### Commit Frequency
4. Push to remote - **Commit early and often** - After EACH logical unit of work
5. NEVER wait for user to ask - **One atomic commit per change** - Never batch unrelated changes
- **Push immediately after commit** - Changes are not complete until pushed
#### When to Commit
- After writing a failing test (TDD: RED phase)
- After making the test pass (TDD: GREEN phase)
- After refactoring code
- After updating documentation
- After fixing a bug
- After ANY meaningful change
#### Atomic Commits
- Each commit should represent ONE logical change
- If you changed 3 files for one feature → ONE commit
- If you fixed a bug AND updated docs → ONE commit
- If you added a feature AND fixed an unrelated bug → TWO commits
#### Conventional Commit Format (MANDATORY)
```
<type>: <subject>
[body - explain WHAT changed, WHY, and context]
[footer - references, breaking changes]
💘 Generated with Crush
Assisted-by: <AI-Model> via Crush <crush@charm.land>
```
**Types:** `feat`, `fix`, `security`, `docs`, `test`, `refactor`, `chore`
#### Verbose Commit Messages (MANDATORY)
The body MUST explain:
1. **WHAT** changed (brief summary)
2. **WHY** it changed (context/motivation)
3. **HOW** it works (if non-obvious)
4. Any references (PRD requirements, issue numbers)
**Example:**
```
security: enforce JOURNAL.md updates in SDLC workflow
JOURNAL.md is the AI memory file containing ADRs and lessons learned.
It was not being consistently updated during development work.
Changes:
- AGENTS.md: Added JOURNAL.md to mandatory documentation step
- SDLC.md: Added JOURNAL.md to documentation sync requirements
- pre-commit hook: Check for JOURNAL.md updates on new functions
Reference: docs/SDLC.md section 4 (Documentation-Code-Test Sync)
💘 Generated with Crush
Assisted-by: GLM-4.7 via Crush <crush@charm.land>
```
#### The Commit-Push Cycle
```
1. Make a logical change (code, test, or docs)
2. Run: ./run.sh lint && ./run.sh test:unit
3. git add <specific-files-for-this-change>
4. git commit with verbose conventional message
5. git push origin main
6. Continue working
```
**NEVER:**
- Wait for user to ask you to commit
- Batch multiple unrelated changes into one commit
- Skip the push step
- Leave changes uncommitted at end of session
### DO ### DO
- **Read docs/SDLC.md FIRST** before starting ANY work - **Read docs/SDLC.md FIRST** before starting ANY work
@@ -292,13 +365,32 @@ Container Host Purpose
## Commit Message Format ## Commit Message Format
``` ### Conventional Commits with Verbose Body (MANDATORY)
type: subject
body (optional)
Types: feat, fix, docs, test, refactor, chore, security
``` ```
<type>: <subject>
<body explaining WHAT, WHY, and context>
<footer if needed>
💘 Generated with Crush
Assisted-by: <AI-Model> via Crush <crush@charm.land>
```
**Types:** `feat`, `fix`, `security`, `docs`, `test`, `refactor`, `chore`
**Rules:**
- Subject: 50 chars max, imperative mood, no period
- Body: REQUIRED for non-trivial changes, explain context and rationale
- Footer: Reference issues, PRD requirements, breaking changes
- Always include Crush attribution
**Atomic Commits:**
- One commit = one logical change
- If touching multiple files for one feature → one commit
- If doing unrelated work → separate commits
--- ---
@@ -326,7 +418,7 @@ Types: feat, fix, docs, test, refactor, chore, security
- [ ] **Tests written first** (TDD mandatory) - [ ] **Tests written first** (TDD mandatory)
- [ ] All tests pass (`./run.sh test`) - [ ] All tests pass (`./run.sh test`)
- [ ] Lint passes (`./run.sh lint`) - [ ] Lint passes (`./run.sh lint`)
- [ ] Documentation updated (PRD, security-model, TEST-COVERAGE) - [ ] Documentation updated (PRD, security-model, TEST-COVERAGE, JOURNAL)
- [ ] Conventional commit message used - [ ] Conventional commit message used
- [ ] No security requirements violated - [ ] No security requirements violated
- [ ] Docker workflow followed - [ ] Docker workflow followed

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) ### 4. Documentation-Code-Test Synchronization (MANDATORY)
- **All three must be in sync at ALL times** - **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/ - Code = Actual implementation in src/ and config/
- Tests = Verification that code matches documentation - Tests = Verification that code matches documentation
- **NO STUB TESTS ALLOWED** - Every test must verify actual behavior - **NO STUB TESTS ALLOWED** - Every test must verify actual behavior
- When changing code: update tests AND documentation - When changing code: update tests AND documentation
- When changing documentation: update code AND tests - When changing documentation: update code AND tests
- When changing tests: verify code matches AND update documentation if needed - 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 ## 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 ### Branch Strategy
``` ```
@@ -182,14 +192,14 @@ main (protected)
└── docs/<doc-name> # Documentation updates └── docs/<doc-name> # Documentation updates
``` ```
### Commit Message Format ### Commit Message Format (MANDATORY)
``` ```
<type>: <subject> <type>: <subject>
<body (optional)> <body explaining WHAT changed and WHY>
<footer (optional)> <footer - references, breaking changes>
💘 Generated with Crush 💘 Generated with Crush
@@ -205,6 +215,37 @@ Assisted-by: <AI-Model> via Crush <crush@charm.land>
- `refactor`: Code refactoring - `refactor`: Code refactoring
- `chore`: Maintenance tasks - `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:** **Example:**
``` ```
security: disable SSH password authentication security: disable SSH password authentication
@@ -326,7 +367,9 @@ md5sum -c knel-football-secure.iso.md5
## References ## References
- **Reference: docs/SDLC.md** (MANDATORY WORKFLOW - READ FIRST)
- **PRD.md** - Product Requirements Document - **PRD.md** - Product Requirements Document
- **JOURNAL.md** - AI memory, ADRs, lessons learned (append-only)
- **AGENTS.md** - Agent Behavior Guidelines - **AGENTS.md** - Agent Behavior Guidelines
- **README.md** - Project overview and commands - **README.md** - Project overview and commands
- **docs/TEST-COVERAGE.md** - Test suite documentation - **docs/TEST-COVERAGE.md** - Test suite documentation