rollback

Intent

Execute rollback to restore system state to a previously created checkpoint. This is the recovery mechanism in the CAVR (Checkpoint-Act-Verify-Rollback) pattern - used when mutations fail or produce undesired outcomes.

Success criteria:

• State fully restored to checkpoint state
• Post-rollback hash matches checkpoint hash
• No orphaned artifacts remain from failed mutation
• Audit trail of what was reverted

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
checkpoint_id	Yes	string	ID of checkpoint to restore to
scope	No	array	Specific files/keys to rollback (default: all in checkpoint)
verify_restore	No	boolean	Whether to verify state matches checkpoint after restore (default: true)
reason	No	string	Why rollback is being performed (for audit)

Procedure

1. Validate checkpoint: Confirm checkpoint exists and is valid

   • Look up checkpoint by ID in .checkpoints/ or git stash
   • Verify checkpoint integrity (hash check)
   • Confirm checkpoint has not expired
   • If checkpoint missing: FAIL immediately with clear error

2. Capture current state: Record what will be reverted

   • List all files/state that differ from checkpoint
   • Compute hash of current state for audit
   • Document changes that will be undone

3. Execute restoration: Apply the restore command

   • For git_stash: git stash pop or git stash apply
   • For file_backup: Copy from .checkpoints/<id>/ to original locations
   • For state_snapshot: Restore state variables
   • Handle any conflicts or errors gracefully

4. Verify restoration: Confirm state matches checkpoint

   • Recompute hash of restored state
   • Compare with checkpoint's pre_mutation_state.hash
   • Check for orphaned files created during failed mutation
   • Clean up orphaned artifacts if present

5. Ground claims: Attach evidence of successful rollback

   • Format: tool:bash:<restore_command>, comparison output
   • Include before/after state hashes

6. Format output: Return rollback results per contract

Output Contract

Return a structured object:

rolled_back: boolean
restored_to:
  checkpoint_id: string
  checkpoint_type: string
  timestamp: string  # When checkpoint was created
changes_reverted:
  - file: string
    operation: string  # What was undone (create, modify, delete)
    summary: string  # Brief description of change reverted
verification:
  pre_state_hash: string  # Hash before rollback
  post_state_hash: string  # Hash after rollback
  checkpoint_hash: string  # Expected hash from checkpoint
  match: boolean  # post_state_hash == checkpoint_hash
warnings: array[string]  # Any issues encountered
next_actions: array[string]  # Suggested follow-up
confidence: number  # 0.0-1.0
evidence_anchors: ["tool:bash:...", "file:..."]
assumptions: []

Field Definitions

Field	Type	Description
rolled_back	boolean	Whether rollback was successful
restored_to	object	Checkpoint that was restored to
changes_reverted	array	List of changes that were undone
verification.match	boolean	Whether restored state matches checkpoint
warnings	array	Issues like orphaned files or partial restore
next_actions	array	What to do next (re-plan, investigate, etc.)
confidence	number	0.0-1.0 based on verification match
evidence_anchors	array	Proof of restoration
assumptions	array	Explicit assumptions made

Examples

Example 1: Git Stash Rollback After Failed Tests

Input:

checkpoint_id: "chk_20240115_143022_a7b3c9"
verify_restore: true
reason: "Tests failed after refactoring"

Output:

rolled_back: true
restored_to:
  checkpoint_id: "chk_20240115_143022_a7b3c9"
  checkpoint_type: git_stash
  timestamp: "2024-01-15T14:30:22Z"
changes_reverted:
  - file: "src/api/handlers/user.py"
    operation: modify
    summary: "Reverted refactored get_user() function"
  - file: "src/api/handlers/auth.py"
    operation: modify
    summary: "Reverted auth token validation changes"
verification:
  pre_state_hash: "sha256:deadbeef..."
  post_state_hash: "sha256:e3b0c442..."
  checkpoint_hash: "sha256:e3b0c442..."
  match: true
warnings: []
next_actions:
  - "critique: Analyze why refactoring broke tests"
  - "plan: Create new plan with smaller incremental changes"
confidence: 1.0
evidence_anchors:
  - "tool:bash:git stash pop stash@{0}"
  - "tool:bash:git diff --stat HEAD"
  - "tool:bash:sha256sum src/api/handlers/*.py"
assumptions:
  - "No other changes made to stashed files since checkpoint"

Evidence pattern: Git stash pop output, diff showing restored state, hash verification.

---

Example 2: File Backup Rollback with Orphaned Files

Input:

checkpoint_id: "chk_20240115_150000_config"
verify_restore: true
reason: "Config migration caused service failure"

Output:

rolled_back: true
restored_to:
  checkpoint_id: "chk_20240115_150000_config"
  checkpoint_type: file_backup
  timestamp: "2024-01-15T15:00:00Z"
changes_reverted:
  - file: "config/production.yaml"
    operation: modify
    summary: "Reverted database connection string changes"
verification:
  pre_state_hash: "sha256:newconfig..."
  post_state_hash: "sha256:abc123..."
  checkpoint_hash: "sha256:abc123..."
  match: true
warnings:
  - "Orphaned file detected: config/production.yaml.bak (removed)"
next_actions:
  - "audit: Record failed migration attempt"
  - "plan: Investigate migration script issue"
confidence: 0.95
evidence_anchors:
  - "tool:bash:cp .checkpoints/chk_20240115_150000_config/production.yaml config/"
  - "tool:bash:rm config/production.yaml.bak"
  - "file:config/production.yaml:1"
assumptions:
  - "Checkpoint backup file is not corrupted"

Verification

Apply the following verification patterns:

• Rollback Verification: post_state_hash == checkpoint_hash (CRITICAL)
• State Assertion: No unexpected files remain after rollback
• Evidence Grounding: Restore command execution is captured
• Clean Git State: git status shows no unexpected changes

Verification tools: Bash (for restore and hash), Git (for stash operations)

Safety Constraints

• mutation: true (modifies files to restore state)
• requires_checkpoint: true (MUST have valid checkpoint to rollback to)
• requires_approval: false
• risk: medium

Capability-specific rules:

• CRITICAL: Never rollback without valid checkpoint_id
• CRITICAL: Always verify state hash matches after restore
• Clean up orphaned files created by failed mutation
• Do not rollback if checkpoint has expired
• Preserve audit trail of what was reverted
• If verification fails, STOP and alert - do not proceed

Composition Patterns

Commonly follows:

• verify - When verify returns FAIL, trigger rollback (CAVR pattern)
• act-plan - If act-plan encounters error, rollback
• checkpoint - Rollback requires prior checkpoint (dependency)

Commonly precedes:

• critique - After rollback, analyze what went wrong
• plan - Create new plan after understanding failure
• audit - Record the rollback event

Anti-patterns:

• CRITICAL: Never rollback without existing checkpoint
• CRITICAL: Never continue mutations after rollback without new checkpoint
• Never skip verification after rollback
• Never delete checkpoint until rollback verification passes

Workflow references:

• See reference/composition_patterns.md#checkpoint-act-verify-rollback for CAVR pattern
• See reference/composition_patterns.md#rollback-verification in verification_patterns.md
• See reference/composition_patterns.md#debug-code-change for rollback-then-critique flow