---
name: git-checkpoint-commit
description: Use when a coding task finishes a verified bug fix, key feature, risky refactor checkpoint, local backup commit, checkpoint commit, 提交备份, 本地提交, or when an active session has accumulated about five meaningful edit rounds and should create a scoped local git commit without pushing.
---

# Git Checkpoint Commit

## Overview

Use this skill to keep a local git backup loop during active development. The goal is to commit verified, task-scoped progress at meaningful checkpoints without mixing unrelated user changes or pushing remotely.

## Trigger Rules

Create a local checkpoint commit when any condition is true:

- A bug fix is implemented and the targeted regression check passes.
- A key feature slice is implemented and the smallest relevant verification passes.
- A risky refactor reaches a behavior-preserving checkpoint.
- The current session has reached about five meaningful edit rounds since the last commit.
- The user asks for `提交`, `本地提交`, `备份`, `checkpoint`, `commit`, or `形成提交循环`.

Do not use this skill when the user explicitly says not to commit, when the change is exploratory and unverified, or when the only available commit would include unrelated dirty files.

## Workflow

1. Inspect the working tree with `git status --short`.
2. Identify files or hunks owned by the current task.
3. Run the smallest relevant verification first.
   - In X-Financial, run backend tests inside `x-financial-main` when backend code is involved.
   - Use targeted frontend tests/builds for web-only changes.
4. Commit only the task-owned files.
5. Report the commit hash and verification evidence.
6. Reset the session edit counter to zero after a successful checkpoint.

## Safety Rules

- Never commit unrelated user changes just to make the tree clean.
- Never push as part of this skill.
- Never rewrite history, amend old commits, or run destructive git commands.
- If the same file contains unrelated hunks, split the staging carefully with `git add -p` or a narrower manual patch.
- If the index already contains staged changes, inspect them first; do not mix them into a checkpoint unless they belong to the same current task.
- If verification cannot run, say why in the commit body or final report and prefer a `chore(checkpoint)` message rather than a confident `fix` or `feat`.

## Commit Style

Use normal semantic messages for completed, verified work:

- `fix(workbench): keep application preview after draft save failure`
- `feat(reimbursements): add attachment association job polling`
- `refactor(claims): split draft flow serialization`

Use checkpoint messages for interim backup points:

- `chore(checkpoint): backup attachment association flow`
- `chore(checkpoint): backup after five edit rounds`

Keep the subject concise. Add body lines only when the verification state or scope needs clarity.

## Helper Script

Use `scripts/checkpoint_commit.py` when a path-scoped local commit is enough:

```bash
python3 .codex/skills/git-checkpoint-commit/scripts/checkpoint_commit.py \
  --message "chore(checkpoint): backup workbench AI flow" \
  web/src/composables/workbenchAiMode/useWorkbenchAiExpenseFlow.js \
  web/tests/workbench-ai-mode-switch.test.mjs
```

Preview before committing:

```bash
python3 .codex/skills/git-checkpoint-commit/scripts/checkpoint_commit.py \
  --dry-run \
  web/src/utils/expenseApplicationPreview.js
```

The script refuses to commit the whole tree unless `--allow-all` is passed. Use `--allow-all` only when the current task truly owns every dirty file.

## Common Mistakes

- Mistaking backup for verification. Verify first, then commit.
- Staging `.` in a dirty worktree. Stage explicit paths or hunks.
- Combining documentation cleanup, feature work, and unrelated local edits in one checkpoint.
- Continuing indefinitely after multiple verified slices. Commit once the counter reaches five meaningful edit rounds.