checkpoint

Checkpoint

Shadow git checkpoint system that snapshots and restores working directory state using an isolated git repository. The project's .git history is never touched.

Skill type: Rigid — follow exactly, no shortcuts.

Execution model: No modes, no subagent dispatch. The consuming orchestrator (build, quality-gate, debugging) follows these instructions directly when taking or restoring checkpoints.

Shadow Repository Setup

Initialize once per session, on first checkpoint request:

1. Compute directory hash: SHA-256 of the absolute working directory path, truncated to 16 characters.

   echo -n "/absolute/path/to/project" | sha256sum | cut -c1-16
   

2. Shadow repo path: ~/.claude/projects/<project-hash>/checkpoints/<dir-hash>/

3. Initialize: If the shadow repo does not exist:

   GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git init
   

4. Write .gitignore in the shadow repo (not the project):

   node_modules/
   .env
   .env.*
   __pycache__/
   .git/
   venv/
   .venv/
   dist/
   build/
   .next/
   *.pyc
   .DS_Store
   

5. Health check: Before every operation, verify:

   GIT_DIR=<shadow-path> git rev-parse --git-dir
   

   If this fails, reinitialize the shadow repo and warn: "Shadow repo was corrupt — reinitialized. Prior checkpoints are lost."

Tool constraint: All shadow repo operations MUST use the Bash tool with explicit GIT_DIR and GIT_WORK_TREE environment variables. Never use Write/Read/Glob for shadow repo git operations. Never run git commands without these env vars — bare git commands would affect the project repo.

Pre-Check: Directory Size

Before the first checkpoint in a session, count files in the working directory (excluding ignored paths):

find <working-dir> -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/__pycache__/*' -not -path '*/venv/*' -not -path '*/.venv/*' -type f | wc -l

If count exceeds 50,000: skip all checkpoints for this directory with warning "Directory has >50,000 files — checkpoints disabled for performance." Cache this decision for the session (do not re-count).

Create Checkpoint

1. Deduplication: Read the latest commit timestamp from the shadow repo:

   GIT_DIR=<shadow-path> git log -1 --format=%ct 2>/dev/null
   

   If the current time minus the commit timestamp is less than 1 second, skip this checkpoint (deduplication).

2. Stage all files:

   GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git add -A
   

3. Commit:

   GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git commit -m "<reason> | <timestamp> | <source-skill>" --allow-empty-message
   

   The <reason> is a structured string (e.g., pre-design-gate, pre-wave-3, pre-qg-fix-round-2). The <source-skill> is the consuming skill name (build, quality-gate, debugging).

4. Record the commit hash as the checkpoint ID.

5. Update manifest: Append an entry to checkpoint-manifest.md in the shadow repo directory (outside the git tree):

   | <hash-8-chars> | <timestamp> | <reason> | <source-skill> |
   

6. Eviction: After commit, count entries in checkpoint-manifest.md. If count exceeds 50 (configurable — orchestrators may override), remove the oldest entries from the manifest. Git objects for evicted commits are cleaned up by the Prune step.

List Checkpoints

Read checkpoint-manifest.md from the shadow repo directory. Display in most-recent-first order:

| Hash     | Timestamp           | Reason              | Source       |
|----------|---------------------|----------------------|--------------|
| a1b2c3d4 | 2026-03-24 12:45:30 | pre-wave-3           | build        |
| e5f6g7h8 | 2026-03-24 12:30:15 | pre-plan-gate        | build        |

Restore (Full Directory)

1. Create a pre-restore safety checkpoint with reason pre-restore-safety and source checkpoint. This enables "undo the undo."

2. Restore:

   GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git checkout <hash> -- .
   

3. Verify: Run the project's test suite or relevant subset to confirm the restored state is healthy.

4. Report: "Restored to checkpoint <hash> (<reason>). Safety checkpoint created at <safety-hash> — use this to undo the restore."

Restore (Single File)

1. Create a pre-restore safety checkpoint with reason pre-restore-safety-file and source checkpoint.

2. Restore:

   GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git checkout <hash> -- <file-path>
   

3. Report: "Restored <file-path> from checkpoint <hash> (<reason>)."

Prune

Run at session start (before first checkpoint) to reclaim space:

1. GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git gc --prune=now
   

2. Read checkpoint-manifest.md and verify each entry's hash exists:

   GIT_DIR=<shadow-path> git cat-file -t <hash>
   

   Remove entries with invalid hashes (orphaned by prior gc).

Compaction Recovery

The checkpoint manifest and shadow repo persist across compaction because they live in ~/.claude/projects/ (not in /tmp/ or in-memory).

After compaction:

1. Recompute the directory hash from the current working directory path
2. Check if ~/.claude/projects/<project-hash>/checkpoints/<dir-hash>/ exists
3. If yes: read checkpoint-manifest.md to recover available checkpoints
4. If no: checkpoints are unavailable for this session (no error — the pipeline continues without checkpoint protection)

No active marker file is needed — the shadow repo's existence IS the marker. The directory hash computation is deterministic from the working directory path.

Red Flags

• NEVER modify the project's .git directory
• NEVER run git commands without GIT_DIR and GIT_WORK_TREE env vars
• NEVER take a checkpoint mid-wave — wait for all parallel agents to complete before snapshotting
• NEVER auto-restore without user confirmation — always present restore as an option, not an action
• NEVER delete the shadow repo without explicit user request

Integration

Consuming skills:

• crucible:build — Pipeline boundary checkpoints (pre-design-gate, pre-plan-gate, pre-wave-N, pre-cleanup-task-N, pre-temper, pre-inquisitor, pre-impl-gate)
• crucible:quality-gate — Pre-fix-round checkpoints for code artifacts (pre-qg-fix-round-N)
• crucible:debugging — Pre-implementation, pre-sibling, and pre-quality-gate checkpoints (pre-debug-fix-cycle-N, pre-where-else, pre-debug-gate)