Git Conventions

Commit Format

Commit messages, PR titles and branch names follow the language rule of code-standards Rule 10.

Examples

feat(helmrelease): add Phase 3.3 services
fix(pg-non-prod): correct API key environment variable mappings
refactor: simplify context provider logic
chore(deps): update terraform to v1.6.0

Multi-Line Body (No Heredoc, No Temp File)

Repeat -m once per paragraph -- git -C /abs commit -m "type: subject" -m "First paragraph." -m "Second paragraph." -- no heredoc, no temp file. For exact wraps, use git commit -m "$(cat <<'EOF' ... EOF)" instead (the bare-cat heredoc receiver security-tiers names). Never attach a bare, unquoted heredoc directly to git (git commit -F - <<EOF ... EOF) -- measured, the classifier misreads a prose line as a command and blocks with a spurious T3 (Verb: 'rm' (MUTATIVE) on text that only mentions rm -rf).

Git Path Flags

Target the repo with git -C /absolute/path <verb> -- this is the canonical form in a subagent. The T3 consent gate parses -C as a flag and classifies the command identically to the bare verb (git -C /repo push origin main is T3 push, same as git push origin main); there is NO bypass of Gaia's gate. The full discipline -- why one byte-identical form prevents the approval loop, and why a separate cd call cannot work (the cwd resets between Bash calls) -- lives in command-execution ("Before the call" rule 2 and "After the call"); follow it there.

Two narrow caveats:

• Prefer -C /abs (short flag) or --git-dir=/abs (equals form); both are cleanly absorbed. Avoid the SPACE-separated --git-dir /abs / --work-tree /abs forms -- the path leaks into the first non-flag token and shifts the subcommand the local-safe guard reads (a mutative verb like push is still caught by the fallback scanner, but commit-message-leak protection is lost).
• The historical warning that a leading path flag "bypasses all rules silently" described Claude Code's NATIVE settings.json prefix matching (Bash(git commit:*)), which Gaia used in 3.2.1 but no longer ships -- enforcement is now the PreToolUse hook, which is -C-robust. If a user adds their own Bash(git ...:*) allow rules, a leading path flag can still shift that prefix, but that affects only their auto-allow convenience, never Gaia's consent gate.

Push Defaults

Push to the feature branch. Only push directly to main when explicitly instructed or when the work is already on main. Force-push (--force) requires explicit user instruction.

Which of these ask for a signature (security-tiers owns the rule; the shapes are the entries of verb_lexicon.py::EFFECT_OVER_VERB_EXCEPTIONS):

• Free: commit, add and the other local subcommands; git -C /abs push [-u|--set-upstream] <remote> <branch> when the branch is named, is not main, master or the remote's HEAD branch, and the repository's push configuration sends it to itself, with nothing before git (mutative_verbs.py::_git_push_targets_feature_branch).
• Free in any repository: a local merge whose flags are all in mutative_verbs.py::_GIT_LOCAL_MERGE_FLAGS (--no-ff, --ff-only, --squash, ...), plus -m <msg>, with literal ref operands, and a bare merge --abort|--continue|--quit (mutative_verbs.py::_git_merge_is_local); opening a change request (pr create, any forge binary, any --repo; forge_shapes.py::change_request_action) and editing one on this checkout's origin without a retarget, ready, draft or status flag; git fetch, pull --ff-only and switch/checkout <branch> by elimination.
• T3: bare git push, a push to the default branch or HEAD, any push with another flag (--force, --force-with-lease, --delete, --mirror, --all, --tags), a +/: refspec or a src:dst onto another branch (a force push signs as sign.destroys, never refused); pr merge; a change-request edit with --base (_CHANGE_REQUEST_EDIT_FLAGS) or on another origin (mutative_verbs.py::_change_request_elsewhere); a merge with a strategy option (-s, -X) or a computed operand; a rebase outside the unpushed, managed-worktree shape (mutative_verbs.py::_git_rebase_rewrites_only_unpushed); reset --hard.

Do not request the free forms in advance: run them, and request only what is still T3.

Hook Enforcement

The commit_validator.py hook validates against standards inlined as module-level constants in that file (TYPE_ALLOWED, SUBJECT_MAX_LENGTH, SUBJECT_RULES, BODY_MAX_LINE_LENGTH) -- it covers the conventional-commits format, subject, and body rules. Forbidden-footer detection lives separately in bash_validator (hardcoded there). Format violations block the commit. Body line length triggers warnings only.

Pull Request Body

The PR title reuses the commit subject's type(scope): outcome rule above. The body is a document a reviewer reads without having been there, so it is written with technical-writing (door: PR body), which owns its sections and the rule that no task id, plan label, approval, signature or tier appears in it. commit_validator.py validates only the commit message format; nothing parses or gates the body.