Cs Checkpoint Version

Checkpoint Version

Purpose

Use this skill to create a local, file-based rollback point for one Git repository.

The default goal is safety: preserve the current branch, HEAD, staged diff, unstaged diff, and untracked files without creating a commit or changing the branch.

Rules

• Work in one Git repository root. Confirm with git rev-parse --show-toplevel.
• Create a checkpoint when requested or when this change needs a rollback artifact; do not snapshot every routine edit. Reuse a verified checkpoint only if HEAD, staged/unstaged diffs and untracked inputs have not changed.
• Default to a safe snapshot under .codex-checkpoints/; do not commit unless the user explicitly asks for a Git checkpoint commit.
• Include staged, unstaged, and untracked non-ignored files. Do not include ignored files such as dependencies, builds, caches, or secrets.
• Never restore a checkpoint unless the user explicitly asks to roll back or restore.
• Before restore, preserve the current worktree with a pre-restore checkpoint.

Save Workflow

1. Inspect the repository:

powershellCopy code
git rev-parse --show-toplevel
git status --short --branch

2. Pick a short slug from the task, such as before-refactor, before-release, or current-version.

3. Run the bundled script from this skill:

powershellCopy code
powershell -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\create-checkpoint.ps1" -Repo "<repo-root>" -Slug "current-version"

4. Report:

• checkpoint directory
• branch and HEAD
• whether staged, unstaged, and untracked files were captured
• restore command

Restore Workflow

Use this only after the user explicitly asks to restore a checkpoint.

1. Inspect available checkpoints:

powershellCopy code
Get-ChildItem -Directory "<repo-root>\.codex-checkpoints" | Sort-Object Name -Descending

2. Read the checkpoint metadata:

powershellCopy code
Get-Content "<checkpoint-path>\metadata.json" -Raw

3. Restore with the bundled script. The restore request supplies authorization; do not ask again for the same checkpoint. Still preserve pre-restore state and respect the separate CleanUntracked boundary:

powershellCopy code
powershell -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\restore-checkpoint.ps1" -Repo "<repo-root>" -Checkpoint "<checkpoint-path>" -Force

Add -CleanUntracked only when the user wants an exact rollback that removes untracked files created after the checkpoint. The restore script excludes .codex-checkpoints/ from git clean.

4. Verify after restore:

powershellCopy code
git status --short --branch
git diff --cached --stat
git diff --stat

Script Outputs

scripts/create-checkpoint.ps1 writes:

• metadata.json: branch, HEAD, timestamp, counts, and restore hint
• status.txt: branch-aware short status
• status-porcelain.txt: exact status entries with untracked files expanded
• staged.patch: binary-safe staged diff
• unstaged.patch: binary-safe unstaged diff
• untracked-files.txt: untracked non-ignored file list
• untracked.zip: untracked file archive when untracked files exist

scripts/restore-checkpoint.ps1 resets to the checkpoint HEAD, reapplies staged and unstaged patches, restores untracked files, and creates a pre-restore checkpoint when the current worktree is not clean.

Common Mistakes

Verification

Run the bundled tests after editing the scripts:

powershellCopy code
powershell -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\tests\cs-checkpoint-version.tests.ps1"