claude-playbooks/playbook_git_criteria_universal.md

name, description, metadata

name	description	metadata
Git Commit Criteria (Universal)	Universal decision criteria for when Claude commits and pushes autonomously — applies to all repos; all repo-specific git playbooks extend this	type last_updated project 2026-06-04

Git Commit Criteria — Universal

Playbook update rule: Per-session updates via the end-of-session checklist playbook review step (step 4). Cross-repo patterns get promoted to this playbook during claude-config audit sessions.

---

The one authorized trigger

Claude commits (and pushes) autonomously only when the end-of-session checklist is executing. The checklist is the authorization. Outside of checklist execution, never commit unless the user explicitly asks — no exceptions.

---

Commit and push are always coupled

When the checklist triggers a commit, push to origin main immediately after. Never hold a commit local.

Push rules:

• Fast-forward only — never --force
• Always push to origin main explicitly, never guess remote/branch
• If push fails (diverged, network error): stop, report to user, do not attempt to fix automatically

---

Repo opt-out

All repos default into autonomous checklist commits. A repo can opt out by adding commit: manual-only to its repo-specific playbook. When set, Claude never commits autonomously in that repo — always asks first, even during checklist execution.

---

Hard blocks — always apply, checklist does not override them

These conditions always block a file from being staged:

Block	Condition	Action
Untested containerized script	.py file runs inside a Docker container and has not been verified in a live container	Hold file — do not stage; report to user what is held and why
Credential exposure	Filename contains token, key, secret, password, pull, registry, approle, or credential	Hold file — confirm with head -1 <file> | cut -c1-10; add to .gitignore if plaintext

Claude-authored host scripts are exempt from the untested script block. Hooks (.claude/hooks/), memory files, context files, and anything else Claude authors that runs on the host or in the harness commit freely as part of the checklist — no testing gate applies.

Partial commit rule: When a hard block is hit, commit everything that passes checks, skip only the blocked files, report clearly what committed and what was held and why, then continue the checklist. Never hold clean changes hostage to a blocked file.

---

Pre-stage check registry (universal defaults)

Run before staging any matching file. If a check fails, fix before staging — do not stage a file that fails its pre-stage check.

File pattern	Check command
*.py	python3 -m py_compile <file> && echo "syntax ok"
docker-compose.yml	docker compose -f <path> config > /dev/null && echo "compose ok"

Repo-specific additions: Each repo-specific playbook may define additional pre-stage checks (e.g. npm run lint for Node projects). These extend the registry — they do not replace it.

---

Health check before push (universal pattern)

Before pushing, run the repo-appropriate health check if one is defined in the repo-specific playbook. If no health check is defined, skip this step.

If the health check fails: stop, do not push, report to user.

Future: When GitLab CI/CD is live, evaluate whether the GitLab pipeline status replaces this manual health check step for CI-managed repos.

---

Commit splitting (universal rule)

One logical reason to change = one commit. Never bundle unrelated changes into a single commit.

Each repo-specific playbook defines its split taxonomy. When no taxonomy is defined, apply this test: would a future reader need to revert these changes independently? If yes, split.

---

Commit message format (universal)

Always use the heredoc form to avoid quoting issues:

git commit -m "$(cat <<'EOF'
scope: short description under 70 chars

- Bullet explaining what changed and why
- Another bullet if needed

Co-Authored-By: Claude <current-model-id> <noreply@anthropic.com>
EOF
)"

Format rules:

• Subject line: scope: description — under 70 characters
• Body: explain why, not what (the diff shows what)
• Co-author line: always present; model ID must reflect the actual model running this session (dynamic — never hardcode a version)
• Scope keyword taxonomy is repo-specific — defined in each repo's playbook

---

Training data — log these events

Log commit decisions that required judgment:

• Hard block hit: file path, block type (untested containerized script / credential), what was held vs. committed
• Pre-stage check catch: check type, file path, what was found
• Push failure: error encountered, how resolved or that it was escalated to user

Routine clean commits with no blocks or check failures do not need logging.

---

Evolution

• Per-session: end-of-session checklist step 4 (playbook review) — any new patterns, gotchas, or rules discovered this session get added to the relevant repo-specific playbook or promoted here
• Cross-repo promotion: when a pattern appears in two or more repo-specific playbooks, promote it to this universal criteria at the next claude-config audit session