synaptiai/agent-capability-standard/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

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

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_id: string  # Unique identifier (e.g., "chk_20240115_143022_abc123")
timestamp: string  # ISO 8601 date-time the checkpoint was created
size: integer  # Checkpoint size in bytes (optional)
checkpoint_created: boolean  # Whether the checkpoint was successfully created
type: git_stash | file_backup | state_snapshot | database_savepoint
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"
metadata:
  reason: "Before refactoring API handlers"
  checkpoint_type: git_stash

Output:

checkpoint_id: "chk_20240115_143022_a7b3c9"
timestamp: "2024-01-15T14:30:22Z"
checkpoint_created: true
type: git_stash
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:
  - "execute: Proceed with handler refactoring"
  - "mutate: 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"
metadata:
  reason: "Before config migration"
  checkpoint_type: file_backup
  expiry: "24h"

Output:

checkpoint_id: "chk_20240115_150000_config"
timestamp: "2024-01-15T15:00:00Z"
size: 3412
checkpoint_created: true
type: file_backup
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:
  - "mutate: 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: low

Capability-specific rules:

• NEVER skip checkpoint before mutate or send (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:

• mutate - REQUIRED: Never mutate without prior checkpoint (CAVR pattern)
• execute - Checkpoint before a step that raises requires_checkpoint
• send - REQUIRED: Checkpoint before external communications
• rollback - REQUIRED: Rollback restores to a checkpoint

Anti-patterns:

• CRITICAL: Never call mutate or send 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