docs: document batch_commit atomic staging semantics to prevent agent misuse

Author: AlbinoGeek

AGENTS.md

@@ -62,6 +62,8 @@ Rules for LLMs operating in or against this repository.
 
 **Mutating tools require workspace-root confirmation** — `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft` operate only on roots confirmed by `requireGitAndRoots` / `requireSingleRepo`. Never pass caller-supplied absolute paths to mutating tools; use `workspaceRoot` or MCP roots.
 
+**`batch_commit` atomic staging — single call per logical change** — Do NOT attempt incremental staging across multiple `batch_commit` calls. Each call is self-contained: it stages all files in all entries, commits them sequentially, and the moment the call completes, all commits have landed. Include all related files (for all related commit entries) in a single `batch_commit` call. A call cannot be resumed or extended by a later call — each is an independent transaction. If entry N fails, entries before N remain committed; entries after N are skipped (not rolled back).
+
 **`absoluteGitRoots` is read-only** — pass it only on read tools (`git_status`, `git_inventory`, `git_parity`, `git_log`, `git_diff_summary`, `list_presets`). Mutating tools reject this parameter.
 
 **Protected branches are enforced by the server** — do not attempt `git_worktree_add` with a branch name matching `main`, `master`, `dev`, `develop`, `stable`, `trunk`, `prod`, `production`, `release*`, or `hotfix*`. The server rejects such calls.

docs/mcp-tools.md

@@ -179,6 +179,28 @@ The response contains one **`parity[]`** entry per resolved git toplevel. `absol
 
 ---
 
+### `batch_commit` — atomic staging semantics
+
+**Critical for AI agents:** Each call to `batch_commit` is **self-contained and atomic per-commit entry**.
+
+- **All files in a single entry are staged together.** When you list `files: ["src/foo.ts", "src/bar.ts"]` in one commit entry, both are staged atomically as a unit with a single `git add` before the commit is created.
+- **Each commit entry is processed sequentially within the call.** The tool stages files, commits, then moves to the next entry. All entries within a single `batch_commit` call happen in one atomic MCP transaction.
+- **A single `batch_commit` call cannot be split across multiple MCP calls.** Do NOT attempt incremental staging like "call 1 with file A, then call 2 with file B hoping they stage together." Each call is independent — call 1's commit lands immediately; call 2's changes are a separate transaction.
+- **Failed entry stops the batch.** If staging or commit fails on entry N, the tool aborts and skips remaining entries. However, **entries that succeeded before the failure remain committed** — they are not rolled back.
+- **Include all files for a logical change in a single `batch_commit` call.** Group related files in each commit entry, list them all in the `files` array, and include all necessary entries in the `commits` array.
+
+Example: to commit two related changes atomically, pass both entries in one call:
+```json
+{
+  "commits": [
+    { "message": "feat: add foo module", "files": ["src/foo.ts", "tests/foo.test.ts"] },
+    { "message": "feat: integrate foo into bar", "files": ["src/bar.ts", "docs/foo.md"] }
+  ]
+}
+```
+
+Do NOT do this: make two separate calls hoping to stage files incrementally. That breaks the contract.
+
 ### `batch_commit` — parameters
 
 | Parameter | Type | Notes |