From aedaabf82c521d685e38fb7dce4d6a5c72cb097b Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Fri, 20 Feb 2026 09:28:26 -0500 Subject: [PATCH] docs: enforce JOURNAL.md updates and auto-commit/push in SDLC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 118 +++++++++++++++++++++++++++++++++++++++++++++------ docs/SDLC.md | 51 ++++++++++++++++++++-- 2 files changed, 152 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4d6186d..2cbbad8 100644 --- a/AGENTS.md +++ b/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) +``` +: + +[body - explain WHAT changed, WHY, and context] + +[footer - references, breaking changes] + +💘 Generated with Crush + +Assisted-by: via Crush +``` + +**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 +``` + +#### 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 +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 ``` +: + + + +