# Meta / Cursor rule artifact - commit-message generation

**Binding** for keeping Cursor's commit-message generation aligned with this
project's commit convention.

The development environment is the Cursor IDE with the Claude Code extension.
Claude Code reads the root `CLAUDE.md` and `docs/rules/` directly and needs no
`.cursorrules`. Cursor's OWN built-in AI (Chat/Composer and the SCM "sparkle"
commit-message generator) does not read those files - it reads `.cursorrules`.
Since the user creates all commits themselves (see
[`meta-git-commits.md`](meta-git-commits.md)) and may use the one-click SCM
generator to draft the message, `.cursorrules` must exist and must encode the
commit convention.

This project ships a SINGLE Cursor rules file: the root
[`.cursorrules`](../../.cursorrules). There is no `.cursor/rules/*.mdc`
directory here, and none should be added. All Cursor rule content lives in
`.cursorrules`.

---

## 1. The requirement

`.cursorrules` MUST encode this project's commit-message convention so that
Cursor's generator emits conforming messages. The authoritative convention
lives in [`meta-git-commits.md`](meta-git-commits.md); `.cursorrules` mirrors
it as plain-text instructions to the generator.

The failure mode this rule prevents: a missing or stale `.cursorrules`, so the
one-click SCM generator falls back to Cursor defaults and emits unprefixed junk
(`Update files`, `Improve project`).

## 2. What `.cursorrules` must encode

1. **First-line format** - `type(scope): description`, lowercase imperative
   summary in English, under 72 chars, no trailing period.
2. **Allowed types (closed list)** - `feat fix perf refactor security docs ci
   chore test`.
3. **Allowed scopes (closed list)** - `specs rules docs config datagen convert
   bench report tools all`, with the area mapping from
   [`meta-git-commits.md`](meta-git-commits.md).
4. **Coverage rule** - the subject is only a title; multi-area diffs need a
   blank line and a 2-6 bullet body covering every meaningful changed area; use
   `all` when no narrower scope honestly fits; split unrelated work.
5. **Anti-examples** - forbid vague/unprefixed lines (`Update files`, `Improve
   project`, `clarify rules`).
6. **Allowed special forms** - `Merge ...` commits are allowed as-is;
   `release(scope): vX.Y.Z` is allowed for releases.
7. **Staged-diff grounding** - base the message ONLY on `git diff --cached`;
   mention only staged paths; if the index is empty, output `No staged
   changes`; never infer from unstaged diffs, untracked files, prior
   commits, or chat context.

## 3. Keeping the mirror in sync

No commit-msg hook is installed in this repository; the convention is enforced
by review. `.cursorrules` and [`meta-git-commits.md`](meta-git-commits.md)
must agree: same type list, same scope list, same first-line format. If the
convention changes, update both files in the same change set.

## 4. Scope boundary

This rule governs the commit-message *convention materialization* - not who may
create commits. Commit authorship is governed by
[`meta-git-commits.md`](meta-git-commits.md): rules files describe the
convention; only the user creates actual commits.