checkpoint

Intent

Execute checkpoint to create a restorable state marker before any mutating operation. This is the foundation of safe agentic execution - enabling rollback if subsequent actions fail.

Success criteria:

• •Checkpoint successfully created with unique identifier
• •All files/state in scope are captured
• •Restore command is documented and tested
• •Expiry policy set if applicable

Compatible schemas:

• •schemas/output_schema.yaml

Inputs

Procedure

1. •

   Identify scope: Determine exactly what needs to be checkpointed

   • •List all files that will be modified by upcoming mutation
   • •Include related configuration or state files
   • •Check for uncommitted git changes in scope
2. •

   Select checkpoint type: Choose appropriate mechanism

   • •git_stash: For git-tracked files (preferred for code changes)
   • •file_backup: For non-git files, copy to .checkpoints/
   • •state_snapshot: For in-memory or runtime state
   • •database_savepoint: For database transactions
3. •

   Capture pre-mutation state: Execute the checkpoint

   • •For git: git stash push -m "checkpoint:<id>:<reason>"
   • •For files: Copy to .checkpoints/<id>/ with manifest
   • •Record hashes of all captured content
   • •Verify checkpoint integrity immediately after creation
4. •

   Generate restore command: Document how to rollback

   • •Exact command(s) to restore state
   • •Any prerequisites for restoration
   • •Order of operations if multiple systems involved
5. •

   Ground claims: Attach evidence of checkpoint creation

   • •Format: tool:bash:<command>, file:<checkpoint_path>
   • •Include hash verification output
6. •

   Format output: Return checkpoint metadata per contract

Output Contract

Return a structured object:

checkpoint_created: boolean
checkpoint:
  id: string  # Unique identifier (e.g., "chk_20240115_143022_abc123")
  type: git_stash | file_backup | state_snapshot | database_savepoint
  created_at: string  # ISO timestamp
  scope:
    files: array[string]  # File paths included
    state_keys: array[string]  # State keys included (if applicable)
  restore_command: string  # Exact command to restore
  expiry: string | null  # When checkpoint expires
pre_mutation_state:
  hash: string | null  # Combined hash of all checkpointed content
  summary: string  # Human-readable state summary
next_safe_actions: array[string]  # What can now safely proceed
confidence: number  # 0.0-1.0
evidence_anchors: ["tool:bash:...", "file:..."]
assumptions: []

Field Definitions

Examples

Example 1: Git Stash Checkpoint

Input:

scope:
  - "src/api/handlers/*.py"
  - "tests/test_handlers.py"
reason: "Before refactoring API handlers"
checkpoint_type: git_stash

Output:

checkpoint_created: true
checkpoint:
  id: "chk_20240115_143022_a7b3c9"
  type: git_stash
  created_at: "2024-01-15T14:30:22Z"
  scope:
    files:
      - "src/api/handlers/user.py"
      - "src/api/handlers/auth.py"
      - "tests/test_handlers.py"
    state_keys: []
  restore_command: "git stash pop stash@{0}"
  expiry: null
pre_mutation_state:
  hash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  summary: "3 files, 342 lines total, last modified 2024-01-15"
next_safe_actions:
  - "act-plan: Proceed with handler refactoring"
  - "edit: Modify files in scope"
confidence: 1.0
evidence_anchors:
  - "tool:bash:git stash push -m 'checkpoint:chk_20240115_143022_a7b3c9:Before refactoring API handlers'"
  - "tool:bash:git stash list | head -1"
assumptions:
  - "Git repository is initialized and clean"
  - "No merge conflicts in working tree"

Evidence pattern: Git stash creation command output, stash list verification.

Example 2: File Backup Checkpoint

Input:

scope: "config/production.yaml"
reason: "Before config migration"
checkpoint_type: file_backup
expiry: "24h"

Output:

checkpoint_created: true
checkpoint:
  id: "chk_20240115_150000_config"
  type: file_backup
  created_at: "2024-01-15T15:00:00Z"
  scope:
    files:
      - "config/production.yaml"
    state_keys: []
  restore_command: "cp .checkpoints/chk_20240115_150000_config/production.yaml config/production.yaml"
  expiry: "2024-01-16T15:00:00Z"
pre_mutation_state:
  hash: "sha256:abc123..."
  summary: "1 file, 89 lines, production database config"
next_safe_actions:
  - "act-plan: Apply config migration"
confidence: 0.95
evidence_anchors:
  - "file:.checkpoints/chk_20240115_150000_config/manifest.json"
  - "tool:bash:sha256sum config/production.yaml"
assumptions:
  - ".checkpoints directory exists and is writable"

Verification

Apply the following verification patterns:

• • State Assertion: pre_mutation_state.hash can be recomputed and matches
• • Restore Command Valid: restore_command executes without error (dry-run if possible)
• • Scope Complete: All files in scope are captured in checkpoint
• • Evidence Grounding: checkpoint.id appears in evidence_anchors

Verification tools: Bash (for hash verification), Read (for manifest)

Safety Constraints

• •mutation: true (creates checkpoint artifacts)
• •requires_checkpoint: false (this IS the checkpoint operation)
• •requires_approval: false
• •risk: medium

Capability-specific rules:

• •NEVER skip checkpoint before act-plan (CRITICAL)
• •NEVER delete checkpoints until explicitly requested
• •ALWAYS verify checkpoint integrity immediately after creation
• •Do not checkpoint sensitive files (.env, credentials) - warn and exclude
• •Store checkpoint metadata in .checkpoints/ within workspace
• •Include reason in checkpoint for audit trail

Composition Patterns

Commonly follows:

• •plan - After creating a plan, checkpoint before execution
• •critique - After reviewing risks, checkpoint before proceeding
• •constrain - After policy check passes, checkpoint before mutation

Commonly precedes:

• •act-plan - REQUIRED: Never act-plan without prior checkpoint (CAVR pattern)
• •improve - Checkpoint before iterative improvement cycles
• •send - Checkpoint before external communications

Anti-patterns:

• •CRITICAL: Never call act-plan without prior checkpoint
• •CRITICAL: Never call rollback without valid checkpoint reference
• •Never checkpoint after mutation has started
• •Never delete checkpoint before verify confirms success

Workflow references:

• •See reference/composition_patterns.md#checkpoint-act-verify-rollback for CAVR pattern
• •See reference/composition_patterns.md#debug-code-change for checkpoint placement
• •See reference/composition_patterns.md#digital-twin-sync-loop for checkpoint in loops