# Git Commit Standards

Follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification.

## Message Format

```
<type>(<scope>): <subject>

[body]

[footer]
```

- **type**: See the type table below. Lowercase only.
- **scope** (optional): Stable affected module, domain, or directory, e.g. `auth`, `api`, `ui`.
  Do not use task, proposal, Mission, Milestone, or batch identifiers such as `T-001`, `P-004`,
  `M-010`, `MS-002`, or `batch-a` as the scope. Put those identifiers in the body or footer when
  traceability is useful. Omit the scope if no stable module or domain name applies.
- **subject**: Concise description, max 72 characters, **no trailing period**.
- **body** (optional): Explain the motivation and details of the change, max 100 chars per line.
- **footer** (optional): Reference issues (`Closes #123`) or declare breaking changes (`BREAKING CHANGE:`).

## Commit Boundary

- Commit at an independently verifiable milestone, stage, or coherent batch boundary.
- Do not create a separate commit merely because one proposal document or control contract is complete.
- A batch checkpoint does not require a commit when the larger milestone remains short-lived and uninterrupted;
  record progress evidence instead. Commit the checkpoint when work may be interrupted, handed off, or moved
  across branches.
- Do not defer all commits until an entire multi-milestone proposal or project is complete.
- Keep each commit limited to the relevant task files and exclude unrelated working-tree changes.

## Types

| type | When to use |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation changes only |
| `style` | Formatting (no logic change: whitespace, semicolons, etc.) |
| `refactor` | Refactoring (not a bug fix, not a new feature) |
| `perf` | Performance improvement |
| `test` | Add or correct tests |
| `build` | Build system or dependency changes |
| `ci` | CI/CD configuration changes |
| `chore` | Other maintenance changes |
| `revert` | Revert a previous commit |

## Breaking Changes

Declare in the footer:

```
BREAKING CHANGE: <description of what broke>
```

Or add `!` after the type/scope: `feat(api)!: rename user endpoint`

## Language Convention

- **subject and body must match the project's configured language.**
- Read the language preference from `.agent/rules/tech-stack.md` or `AGENTS.md`; default to **English** if not configured.
- Do not mix languages within a single commit message.

## Prohibited Content

The following are **strictly forbidden** in any part of a commit message (type, subject, body, or footer):

- `Co-authored-by: Claude`
- `Co-authored-by: AI`
- `Generated by AI` / `AI-generated` / `AI assisted`
- `Generated with Claude` / `Powered by Claude`
- Any AI tool name used as a co-author or attribution

> Commit messages represent the developer's own work. AI is a tool, not a contributor, and must not appear in commit history in any form.

## Related

- See also `submission-workflow.md` — covers the double-repo commit
  order (inner first, then outer), pre-commit gate stack, push
  hygiene, and failure-recovery playbook that complements this
  file's message-format rules.

## Examples

```
feat(auth): add OAuth2 login support

Supports GitHub and Google as third-party login providers.
Adds /auth/callback route on the backend and a login button component on the frontend.

Closes #42
```

```
fix(api): fix out-of-bounds pagination on user list

Return an empty array instead of a 500 error when the page param exceeds total pages.
```

```
refactor(core)!: remove legacy config loader

BREAKING CHANGE: loadConfig() has been removed, use loadConfigAsync() instead
```