engram-commit-hygiene

## When to Use Use this skill when: - Creating commits - Creating or naming branches - Reviewing commit history in a PR - Cleaning up staged changes --- ## Critical Rules 1. **Commit messages MUST follow Conventional Commits** — enforced by GitHub ruleset, rejected on push if invalid 2. **Branch names MUST follow `type/description` format** — enforced by GitHub ruleset, rejected on push if invalid 3. Keep one logical change per commit 4. Message should explain **why**, not only what 5. **NEVER** include `Co-Authored-By` trailers 6. **NEVER** commit paths prohibited by the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy) --- ## Commit Message Format (enforced by GitHub ruleset) **Regex:** `^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+` ``` <type>(<optional-scope>): <description> <type>(<optional-scope>)!: <description> ← breaking change ``` ### Allowed Types | Type | Purpose | |------|---------| | `feat` | New feature | | `fix` | Bug fix | | `docs` | Documentation only | | `refactor` | Code refactoring (no behavior change) | | `chore` | Maintenance, dependencies | | `style` | Formatting, whitespace | | `perf` | Performance improvement | | `test` | Adding or fixing tests | | `build` | Build system changes | | `ci` | CI/CD pipeline changes | | `revert` | Revert a previous commit | ### Rules - Type MUST be lowercase, one of the listed values - Scope is optional, lowercase, allows `a-z`, `0-9`, `.`, `_`, `-` - `!` before `:` marks a breaking change - Description MUST start after `: ` (colon + space) - Description should be imperative mood ("add", not "added" or "adds") ### Valid Examples ``` feat(cli): add --json flag to session list command fix(store): prevent duplicate observation insert on retry docs(contributing): update workflow documentation refactor(internal): extract search query sanitizer chore(deps): bump github.com/charmbracelet/bubbletea to v0.26 style(tui): fix alignment in session detail view perf(store): optimize FTS5 query for large datasets test(sync): add coverage for conflict resolution ci(workflows): split e2e into separate job fix!: change session ID format ``` ### Invalid Examples (push will be rejected) ``` Fix bug ← no type prefix feat: Add login ← description should be lowercase FEAT(cli): add flag ← type must be lowercase feat (cli): add flag ← no space before scope feat(CLI): add flag ← scope must be lowercase update docs ← no conventional commit format ``` --- ## Branch Naming Format (enforced by GitHub ruleset) **Regex:** `^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$` ``` <type>/<description> ``` ### Allowed Types `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `revert` ### Rules - Type MUST be one of the listed values - Description MUST be lowercase - Only `a-z`, `0-9`, `.`, `_`, `-` allowed in description - No uppercase, no spaces, no special characters ### Valid Examples ``` feat/json-export-command fix/duplicate-observation-insert docs/api-reference-update refactor/extract-query-sanitizer chore/bump-bubbletea-v0.26 ci/split-e2e-job ``` ### Invalid Examples (push will be rejected) ``` feature/add-login ← "feature" not allowed, use "feat" fix/Add-Login ← uppercase not allowed my-branch ← no type prefix fix_something ← missing "/" separator ``` --- ## Pre-Commit Checklist - [ ] Commit message matches conventional commits format - [ ] Branch name matches `type/description` format - [ ] Diff matches commit scope (no unrelated changes) - [ ] No secrets, credentials, or `.env` files - [ ] Every changed path complies with the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy) - [ ] No `Co-Authored-By` trailers - [ ] Tests relevant to the change pass