Files

administrator b173ac82a9 fix(docs): fix formatting issues in README.md

- 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

2026-07-11 13:39:13 -04:00

4.3 KiB

Raw Blame History

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.

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.

4.3 KiB Raw Blame History