# Meta / Git commits - never on behalf of the user

**Binding** for every contributor (human or AI agent) touching this
repository. Applies to **all** git history-modifying operations.

---

## 1. The rule

**Never create a git commit on behalf of the user. Ever.** The user is the
only entity allowed to materialize a commit in this repo.

This covers, without exception:

- `git commit` (with or without `-a`, `-m`, `--amend`)
- `git merge` - never finalize one
- `git rebase` (interactive or otherwise) - never start one
- `git revert` - never run; the user decides whether a change is undone
- `git cherry-pick`
- `git stash`
- `git tag` (annotated or lightweight)
- `git push` of any kind - pushing is the user's call
- `git reset` / `git checkout` that changes the working tree or refs
- Any wrapper script or `gh` API call that would create a commit / tag /
  merge on the user's behalf

For an AI agent, git is **read-only**: reading history (`git log`,
`git diff`, `git status`, `git show`) and inspecting branches is fine;
anything that writes to the index, refs, or `objects/` - including
`git add` - is left to the user. (This matches the machine-level
enforcement: git write commands by the agent are denied by a hook.)

## 2. Why

- Commit authorship and message wording are decisions the user owns - they are
  durable, public, and signed against the user's name and email.
- "Tiny" commits that look harmless ("fix typo", "delete unused file") still
  rewrite history and cannot be quietly reversed once pushed.
- Generated data and measured results in this project take hours to rebuild;
  what enters history and when is a conscious decision, not a side effect.

## 3. What to do instead

- Make the working-tree changes.
- Report what changed and offer a draft commit message **as plain text** in the
  conversation, together with the exact `git add` / `git commit` commands for
  the user to run themselves.

## 4. Commit-message format

When you draft a message, follow this project's convention:

- **First line** - `type(scope): description`, lowercase imperative summary in
  English, under 72 chars, no trailing period.
- **Types (closed list)** - `feat fix perf refactor security docs ci chore
  test`.
- **Scopes (closed list, owner-approved 2026-07-11)** - `specs rules docs
  config datagen convert bench report tools all`. Pick by the area of the
  changed files:
  - `specs` = `docs/specs/**`
  - `rules` = `docs/rules/**`
  - `docs` = other prose docs (`README.md`, root `CLAUDE.md`,
    `docs/examples/**`)
  - `config` = configuration files (`.gitignore`, `.cursorrules`, editable
    YAML defaults such as hardware prices)
  - `datagen` = lab-configuration and data-generation code (tasks 01-03:
    `lab_config` generation, process diagrams, `generate_data.py`)
  - `convert` = format converters (tasks 04-07: JSON-LD, SQLite,
    PostgreSQL, RDF)
  - `bench` = benchmark queries, runner, and extrapolation (tasks 08-10)
  - `report` = reporting code and templates (task 11)
  - `tools` = helper scripts under `tools/`
  - `all` = multiple areas or in doubt
- **Coverage** - multi-area diffs get a blank line and a 2-6 bullet body
  covering every meaningful changed area; split unrelated work.
- **Special forms** - `Merge ...` and `release(scope): vX.Y.Z` are allowed
  as-is.

No `commit-msg` hook is installed in this repository yet; the convention is
enforced by review. If a hook is added later, it must implement exactly this
format and this file must be updated in the same change. The same convention
is mirrored into `.cursorrules` for Cursor's built-in commit-message
generator - see [meta-cursor-rules.md](meta-cursor-rules.md).

## 5. Anti-patterns

- **"I'll just commit it so we have a checkpoint."** No. Working-tree state is
  the checkpoint; the user decides when it becomes history.
- **Amending the user's last commit to fix something you noticed.** No. Surface
  the issue, let the user choose between amend and new commit.
- **Suggesting `git add -A` in the draft commands.** List explicitly named
  files, so the user sees exactly what would land.
- **Vague subjects** (`Update files`, `Improve project`, `clarify rules`).
  Say what changed and where.

## 6. Exception (closed list)

There are no exceptions. If a workflow seems to require a commit, pause,
explain the dependency, and let the user run the git command.