Skip to content

checkpoint-system-guide.md

Latest commit

 

History

History
356 lines (260 loc) · 7.3 KB

checkpoint-system-guide.md

File metadata and controls

356 lines (260 loc) · 7.3 KB

Checkpoint System Guide

한국어로 보기

Overview

The AIWF Checkpoint System is designed to provide robust recovery and progress tracking for YOLO mode execution. It automatically saves state at critical points and allows seamless continuation after interruptions.

Key Concepts

What is a Checkpoint?

A checkpoint is a snapshot of:

  • Current session state
  • Task completion status
  • Git repository state
  • Performance metrics
  • Execution context

When are Checkpoints Created?

Checkpoints are automatically created:

  • At session start
  • After each task completion
  • Before risky operations
  • At regular intervals (configurable)
  • On graceful interruption

Manual checkpoints can be created anytime for extra safety.

Using the Checkpoint System

Basic Commands

# View current session status
aiwf checkpoint status

# List available checkpoints
aiwf checkpoint list
aiwf checkpoint list --limit 20

# Restore from a checkpoint
aiwf checkpoint restore cp_1234567890

# Create manual checkpoint
aiwf checkpoint create "Before major refactoring"

# Clean old checkpoints
aiwf checkpoint clean --keep 10

Dedicated CLI Tool

The aiwf-checkpoint command provides advanced features:

# Generate progress report
aiwf-checkpoint report

# Show detailed checkpoint info
aiwf-checkpoint show cp_1234567890

# Clean with preview
aiwf-checkpoint clean --keep 5 --dry-run

# Get help
aiwf-checkpoint help

Checkpoint Structure

Checkpoint Files

.aiwf/checkpoints/
├── cp_1703123456789/
│   ├── metadata.json      # Checkpoint metadata
│   ├── session.json       # Session state
│   ├── git-state.json     # Git repository snapshot
│   └── metrics.json       # Performance metrics
└── current-session.json   # Active session reference

Metadata Contents

{
  "id": "cp_1703123456789",
  "type": "task_complete",
  "timestamp": "2024-12-25T10:30:45.789Z",
  "session_id": "session_1703123456789",
  "description": "Completed task T01_S01",
  "git_commit": "abc123def",
  "tasks_completed": 5,
  "sprint": "S01"
}

Recovery Process

Automatic Recovery

When YOLO mode starts, it checks for:

  1. Active session with incomplete tasks
  2. Recent checkpoints
  3. Git state consistency

If an incomplete session is found, you'll be prompted to:

  • Continue from last checkpoint
  • Start fresh
  • Review checkpoint details

Manual Recovery

# 1. Check what's available
aiwf checkpoint list

# 2. View specific checkpoint details
aiwf-checkpoint show cp_1703123456789

# 3. Restore if appropriate
aiwf checkpoint restore cp_1703123456789

# 4. Continue in YOLO mode
# In Claude Code: /project:aiwf:yolo

Integration with YOLO Mode

YOLO Configuration

Configure checkpoint behavior in .aiwf/yolo-config.yaml:

checkpoint:
  auto_checkpoint: true
  interval_minutes: 15
  max_checkpoints: 50
  checkpoint_on:
    - task_complete
    - sprint_complete
    - before_risky_operation
    - interval

YOLO Execution Flow

Start YOLO → Check Recovery → Create Session → Execute Tasks
                ↓                                    ↓
          [Has Checkpoint]                   [Create Checkpoint]
                ↓                                    ↓
          Prompt Recovery                    Continue Execution

Best Practices

1. Regular Cleanup

# Keep last 10 checkpoints
aiwf checkpoint clean --keep 10

# Or clean by age (days)
aiwf checkpoint clean --older-than 7

2. Manual Checkpoints for Safety

Create manual checkpoints before:

  • Major refactoring
  • Database migrations
  • Breaking changes
  • Experimental features
aiwf checkpoint create "Before database schema change"

3. Monitor Checkpoint Health

# Regular status checks
aiwf checkpoint status

# Weekly reports
aiwf-checkpoint report --period week

4. Git State Alignment

Ensure Git state matches checkpoint:

# Before restore
git status

# After restore
git log --oneline -5

Advanced Features

Session Metrics

Each checkpoint tracks:

  • Execution time
  • Tasks completed
  • Success/failure ratio
  • Token usage (if available)
  • Memory usage

View metrics:

aiwf-checkpoint report --detailed

Checkpoint Types

  1. session_start: Beginning of YOLO session
  2. task_complete: After task completion
  3. sprint_complete: Sprint milestone
  4. auto: Regular interval checkpoint
  5. manual: User-created checkpoint
  6. error_recovery: After error handling

Parallel Sessions

The system prevents parallel YOLO sessions:

  • Only one active session allowed
  • Stale sessions auto-expire after 24 hours
  • Force override with --force flag

Troubleshooting

Cannot Restore Checkpoint

Issue: "Git state mismatch"

# Check current Git state
git status

# View checkpoint Git state
aiwf-checkpoint show cp_1234567890

# Reset to checkpoint commit if safe
git reset --hard <checkpoint-commit>

Issue: "Session already active"

# Check active session
aiwf checkpoint status

# Force new session if needed
/project:aiwf:yolo --force

Checkpoint Corruption

Issue: "Invalid checkpoint data"

# Remove corrupted checkpoint
rm -rf .aiwf/checkpoints/cp_1234567890

# Clean and verify
aiwf checkpoint clean --verify

Storage Issues

Issue: "Too many checkpoints"

# Check checkpoint count
ls -la .aiwf/checkpoints/ | wc -l

# Aggressive cleanup
aiwf checkpoint clean --keep 5

# Check disk usage
du -sh .aiwf/checkpoints/

Performance Considerations

Checkpoint Size

  • Average checkpoint: 10-50 KB
  • Large projects may have bigger checkpoints
  • Git state tracking adds minimal overhead

Optimization Tips

  1. Configure intervals wisely

    • Default: 15 minutes
    • Heavy tasks: 5-10 minutes
    • Light tasks: 20-30 minutes

  2. Limit checkpoint count

    • Default: Keep last 50
    • Recommended: 10-20 for most projects

  3. Disable for simple tasks

    checkpoint:
  auto_checkpoint: false  # For simple sprints

Integration Examples

CI/CD Integration

# .github/workflows/yolo-recovery.yml
name: YOLO Recovery Check
on:
  schedule:
    - cron: '0 9 * * 1-5'  # Weekdays at 9 AM

jobs:
  check-recovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install AIWF
        run: npm install -g aiwf
      - name: Check Incomplete Sessions
        run: |
          if aiwf checkpoint status | grep -q "incomplete"; then
            echo "Found incomplete YOLO session"
            aiwf-checkpoint report
          fi

Custom Scripts

#!/bin/bash
# backup-checkpoints.sh

# Create checkpoint archive
tar -czf checkpoints-$(date +%Y%m%d).tar.gz .aiwf/checkpoints/

# Upload to cloud storage
aws s3 cp checkpoints-*.tar.gz s3://my-bucket/aiwf-backups/

# Clean local old checkpoints
aiwf checkpoint clean --keep 10

Summary

The AIWF Checkpoint System provides peace of mind when running autonomous YOLO sessions. By automatically tracking progress and enabling easy recovery, it allows developers to leverage YOLO mode's power without fear of losing work. Regular maintenance and proper configuration ensure optimal performance and reliability.

Remember: Checkpoints are your safety net - use them wisely!