git-authoring GEMINI.md

Git authoring conventions

This repository's commit-message and pull-request rules live in AGENTS.md at the repository root. Follow it in full and choose the mode from the user's request:

1. For already-staged changes, present the exact quoted-heredoc commit command.
2. When asked to choose files, present specific staging commands plus the heredoc commit command.
3. When asked for PR content, write the title and structured Markdown description.
4. Only when unmistakably told to do it all, stage, commit, and push autonomously — and, on a further explicit request, tag and publish a release.
5. When asked for release notes, establish the range since the last release, read what actually landed, and write the note as a Markdown block.
6. When asked to review an incoming pull request, read it through gh, work the decision through with the user, and write the review comment or the merge-commit message as a Markdown block for them to paste. Never approve, request changes, comment, or merge.
7. When asked for repository work — branches, merges and rebases, history editing, undo, moving work, conflict resolution, recovery — read the real state, say what the situation is, and present the exact commands.

Modes 1–3 and 5–7 are always read-only, even after a follow-up confirmation. Mode 4 is the sole execution exception, and mode 7 executes only under that same explicit request; it is an exception to the read-only rule and to nothing else. Never infer mode 4 from "commit this," "go ahead," or a request for commands. Never infer publishing from a release note or approval of one — it takes mode 4 and an explicit request to publish. Never use git add -A, force-push, or overwrite an existing tag or release. Never pass --no-verify, and never disable a hook, to make a commit or a push succeed. A hook that fails is a finding, and it stops the work.

Work in the repository that this agent did not create is another writer's state. Inspect it, never sweep it into a commit, and never rewrite it. A rejected push means another writer moved the branch: fetch, read the divergence, and report the exact commits on each side. Never rebase or merge that divergence on your own — the resolution is the user's decision.

Every stop hands the work back with five fields. The goal, and the exact blocked step. What you attempted, and the git output, verbatim. The causes you eliminated, and how. The one decision needed from the user. The state that remains, and whether it is safe to leave. Mode 4 claims completion only from git log -1 --format=full and git status. Run both after the push. A claim without that output is not a completion.

Mode 4 does not extend to mode 6. Deciding to approve, reject, or merge someone else's pull request always produces text the user pastes, never an action the agent takes — "approve it" or "yes, merge" tells you what the block should say, not to run it. Never run gh pr review, gh pr comment, gh pr merge, or gh pr close.

When reviewing a pull request, separate what actually blocks the merge — breaks the build or an existing test, loses or corrupts data, opens a security hole, breaks a documented contract without notating it, or does not do what the PR claims — from what is only a suggestion, and calibrate the bar to the project: a small repo with no stated convention and no CI is not a large one. Never manufacture a blocker, and when nothing blocks, say so in one plain line before anything else. On a fork pull request, empty gh pr checks output means the workflows have not run, not that they passed.

For a release note, fetch tags first, base the range on the last version tag reachable from HEAD, and report any disagreement with the project's version field rather than silently picking one. If the repository has no versioning at all, say so and stop rather than creating its first tag. Match the style of prior releases over any template.

In repository work, never rewrite published history on a shared branch, never force-push — where the user asks to update their own pushed branch after a rebase, use --force-with-lease — never discard uncommitted work without explicit confirmation, never resolve a conflict by choosing a side to end it, and never leave a rebase, merge, cherry-pick, or bisect part-way through without naming the state and the command that ends it. Before any command that can lose work, state the reflog entry that recovers it.