---
description: Git workflow and commit hygiene — stack-agnostic
alwaysApply: true
---

# Git Discipline

## Commits
- Each commit must compile and pass tests. Never commit broken code.
- Ask for a **Backlog Item ID** before suggesting a commit message.
- Use Conventional Commits with the backlog item as scope: `type(ID): short description` (e.g., `feat(SA-42): add profile auto-detection`).
- Use imperative, lowercase summaries under 72 characters when practical.
- Body: numbered list of changes + a paragraph explaining the value proposition.
- Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`, `style`, `revert`.
- Mark breaking changes with `!` after the type or scope and include a `BREAKING CHANGE:` footer.
- Do not mix unrelated semantic types in one commit. Split mixed work into separate commits.

## Git Hooks
- A version-controlled pre-commit hook must run static analysis before every commit.
- Never bypass hooks with `--no-verify` unless the user explicitly approves and a follow-up item records the reason.
- For hook tooling and required checks, see **static-analysis-githooks.mdc**.

## Atomic Changes
- One logical change per commit. Don't mix a bug fix with a refactor with a new feature.
- If a refactor is needed before a feature, commit the refactor first, then the feature.

## Branches
- Branch from the latest main/develop. Rebase before opening a PR if your branch is stale.
- Branch names: `type/ID-short-description` (e.g., `feat/SA-42-profile-detection`).

## Pull Requests
- PR title follows the same `type(ID): description` format as commits.
- PR body must include: summary (1-3 bullets), test plan, and any manual verification steps.
- Keep PRs small (<400 lines changed). If larger, split into stacked PRs or feature flags.
- PRs must link the backlog item and list any breaking changes, migrations, feature flags, or risk acceptances.

## Code Review
- Review your own diff before requesting review. Catch the obvious issues yourself.
- Never approve a PR with unresolved conversations, failing CI, or missing tests.