commit

Create a commit only when the user explicitly asks for one. Do not push, rebase, squash, or amend unless the user separately requests that operation.

Synchronize the Current Branch

Before reviewing changes, identify the current branch and whether it has a remote tracking branch:

git status --short --branch
git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'

If no upstream is configured, report that fact and continue without pulling. Do not guess which remote branch should be used.

If an upstream exists, update it before preparing the commit:

git pull --ff-only

Preserve all local staged, unstaged, and untracked changes. If those changes prevent the pull, create a clearly named temporary stash that includes untracked files, run the fast-forward pull, then restore the stash with its staged state:

git stash push --include-untracked -m "codex commit sync"
git pull --ff-only
git stash pop --index

Record the stash identifier before restoring it. If restoration conflicts, Git retains the stash; keep it until every local change has been recovered and verified. Confirm the staged, unstaged, and untracked state before continuing.

Resolve conflicts from restoring local changes by inspecting the upstream and local intent, removing every conflict marker, and preserving both changes when they are compatible. Never discard either side merely to make the conflict disappear. If the correct result is ambiguous or falls outside the requested commit scope, stop and ask the user. Reinspect the complete diff and rerun relevant checks after every conflict resolution.

If git pull --ff-only reports divergent history, do not choose merge or rebase automatically. Show the divergence and ask the user which history strategy to use; continue only after they explicitly choose one.

Gather Context

Read the commit message rules in the repository-root CONTRIBUTING.md, then inspect the repository state and both staged and unstaged changes:

git status --short
git diff
git diff --cached

Use the repository convention as the source of truth for allowed modules and types. Check recent commit titles when useful, but do not copy an old title that violates the current convention.

Define the Commit Scope

Identify one coherent change to commit. Preserve unrelated user changes and pre-existing staged content. If staged content cannot be safely separated from the requested change, stop and explain the conflict instead of modifying the user's staging area without permission.

Choose modules by responsibility rather than implementation detail. Use the smallest set that accurately describes the change, and explain the specific algorithm, backend, or dependency in the description when needed.

Validate the Change

Run checks relevant to the proposed change. Do not claim a check passed unless it was actually run. Keep the staging area unchanged while preparing the commit preview.

Compose and Validate the Message

Write a concise title that follows CONTRIBUTING.md. Add a body when the reason for the change, an important tradeoff, or migration guidance would not be clear from the title and diff alone.

Validate the proposed title before creating the commit:

python3 scripts/check_commit_message.py --title "[module] type: description"

If validation fails, fix the message. Never bypass repository hooks with --no-verify.

Request Final Confirmation

Before staging or committing, show the user:

• The proposed title and body, if any.
• The explicit list of files to include.
• Checks run and their results.
• Any unrelated or pre-existing staged changes that will remain untouched.
• A statement that the commit will remain local and will not be pushed.

Wait for explicit confirmation such as "confirm", "commit", or "go ahead". The initial request to prepare a commit starts this workflow but does not replace final confirmation of the preview. Do not run git add or git commit before that confirmation.

If any candidate file changes after the preview, refresh the diff and request confirmation again.

Commit and Report

After confirmation, stage only the approved files with git add -- <path>.... Do not use git add . or git add -A, because they can capture unrelated work.

Inspect the final staged diff and check it for whitespace errors:

git diff --cached --check
git diff --cached

Create the local commit, then report its hash, title, checks run, and remaining worktree state. Do not push the commit.