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:
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
|
||||
|
||||
Reference in New Issue
Block a user