b173ac82a9
- adapt meta-/code-/obs- rules to the local Python benchmark pipeline - replace db-sql-ddl, code-config-env-scope, test-e2e-pytest with pipeline equivalents - add code-python-style, data-determinism, data-naming-units, bench-methodology, build-pipeline-tasks - normalize specs and README typography to ASCII per code-data-formatting - rewrite root CLAUDE.md trigger table; add .cursorrules and .gitignore - specs: pipeline plan and task specs 00-11 - rules: 19 binding rule files adapted for this project - docs: CLAUDE.md rule-trigger table - config: .cursorrules commit convention, .gitignore excluding out/ and .venv/ - docs: rewrite README.md with pipeline diagrams, setup guide, result placeholders - config: requirements.txt for the closed dependency list - datagen: make_lab_config.py writes out/config/lab_config.yaml and .done marker
100 lines
4.3 KiB
Markdown
100 lines
4.3 KiB
Markdown
# 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.
|