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
2026-02-20 09:28:26 -05:00
parent 59122570a6
commit aedaabf82c
2 changed files with 152 additions and 17 deletions

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/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