docs: enforce JOURNAL.md updates and auto-commit/push in SDLC
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
118
AGENTS.md
118
AGENTS.md
@@ -159,6 +159,7 @@ vim tests/unit/my_feature_test.bats
|
||||
- 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
|
||||
- Update **JOURNAL.md** with ADRs, lessons learned, session notes (append-only)
|
||||
|
||||
### 7. Run Tests
|
||||
```bash
|
||||
@@ -254,13 +255,85 @@ Container Host Purpose
|
||||
|
||||
## Important Rules
|
||||
|
||||
### AUTO-COMMIT (Critical)
|
||||
**After completing ANY work:**
|
||||
1. Check `git status`
|
||||
2. Stage relevant changes
|
||||
3. Commit with conventional message
|
||||
4. Push to remote
|
||||
5. NEVER wait for user to ask
|
||||
### AUTO-COMMIT & AUTO-PUSH (CRITICAL)
|
||||
|
||||
**You MUST commit and push AUTOMATICALLY as you work. NEVER wait for user to ask.**
|
||||
|
||||
#### Commit Frequency
|
||||
- **Commit early and often** - After EACH logical unit of work
|
||||
- **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
|
||||
- **Read docs/SDLC.md FIRST** before starting ANY work
|
||||
@@ -292,13 +365,32 @@ Container Host Purpose
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```
|
||||
type: subject
|
||||
### Conventional Commits with Verbose Body (MANDATORY)
|
||||
|
||||
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)
|
||||
- [ ] All tests pass (`./run.sh test`)
|
||||
- [ ] Lint passes (`./run.sh lint`)
|
||||
- [ ] Documentation updated (PRD, security-model, TEST-COVERAGE)
|
||||
- [ ] Documentation updated (PRD, security-model, TEST-COVERAGE, JOURNAL)
|
||||
- [ ] Conventional commit message used
|
||||
- [ ] No security requirements violated
|
||||
- [ ] Docker workflow followed
|
||||
|
||||
51
docs/SDLC.md
51
docs/SDLC.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user