# Pathrule Pattern: Git & Conventional Commits (1.0.0)
# ::pathrule:package:git-conventional-commits

### [RULE] Commit messages follow Conventional Commits v1.0.0  (path: /)
<!-- scope: project | priority: high | strict -->

Format every commit as `<type>[optional scope][!]: <description>` per Conventional Commits v1.0.0 so `release-please` can derive versions and changelogs.

- Use only these types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
- Keep the subject in imperative mood, lowercase after the colon, no trailing period, and at most 50 characters; wrap the body at 72.
- A `feat` maps to a MINOR bump and a `fix` to a PATCH; signal breaking changes with a `!` after the type or a `BREAKING CHANGE:` footer for a MAJOR bump.
- Add a scope in parentheses when it clarifies the area, for example `fix(auth): refresh token before expiry`.

---

### [RULE] Short-lived branches and small focused PRs  (path: /)
<!-- scope: project | priority: high | advisory -->

Work on short-lived branches cut from `main` and merge them back within a day or two to keep integration cheap.

- Target under ~400 changed lines per PR; split larger work into stacked or sequential PRs.
- One logical change per PR so reviews are fast and reverts are clean.
- Rebase your local branch onto `main` to stay current, but never rebase a branch others have already pulled.
- Use squash merge so each PR lands as a single Conventional Commit on `main`; the PR title becomes that commit and must pass commit linting.

---

### [MEMORY] Rebase vs merge decision guide  (path: /)

Pick the integration strategy by branch lifecycle, not by habit.

- Rebase private short-lived feature branches onto `main` before opening or updating a PR to keep a linear, bisectable history.
- Use a true merge (no rebase) for long-lived branches like a release branch going back into `main`, preserving collaboration context.
- The hard rule: never rebase commits already pushed to a shared branch, since rewriting public history forces teammates to force-pull or re-clone.
- Prefer squash merge for PR landings so the merged result is one clean Conventional Commit regardless of messy intermediate commits.

---

### [MEMORY] Commit and release automation stack  (path: /.github)

Commit hygiene is enforced locally and in CI, then drives automated releases.

- `@commitlint/cli` with `@commitlint/config-conventional` validates messages; run it from a `lefthook` `commit-msg` hook so bad messages never get committed.
- Because we squash merge, the PR title becomes the commit, so lint PR titles in a GitHub Action against the same Conventional Commits rules.
- `release-please` parses Conventional Commits on `main`, opens a release PR with the computed semver bump and generated `CHANGELOG.md`, and cuts the GitHub release on merge.
- Keep `lefthook.yml` and the commitlint config at the repo root; keep the release-please and PR-title-lint workflows under `/.github/workflows`.

---

### [SKILL] git-conventional-commits-review  (path: /)

---
name: git-conventional-commits-review
description: Checklist to run before committing and before opening a PR so commits follow Conventional Commits v1.0.0, branches stay short-lived, and PRs stay small and reviewable. Use when writing a commit, opening a pull request, or reviewing git history hygiene.
---

# Git & Conventional Commits review

- [ ] Subject matches `<type>[scope][!]: <description>` using an allowed type (`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`).
- [ ] Subject is imperative mood, lowercase after the colon, no trailing period, and at most 50 characters.
- [ ] Body (if present) explains the why, wraps at 72 characters, and references issues in the footer.
- [ ] Breaking changes are flagged with `!` or a `BREAKING CHANGE:` footer so the MAJOR bump is correct.
- [ ] The change is one logical unit; unrelated changes are split into separate commits or PRs.
- [ ] Branch is short-lived and freshly rebased onto `main`, with no rebase of commits already pushed to a shared branch.
- [ ] PR is under ~400 changed lines, or has a clear plan to split it.
- [ ] PR title is itself a valid Conventional Commit, since squash merge turns it into the landed commit.
- [ ] `commitlint` and the PR-title lint check pass locally and in CI before requesting review.