#9 - Checkpoint reactor — automatic git snapshots - charles/peon

claude-desktop commented

2026-04-16 11:29:45 +00:00

Collaborator

User story

As a user running an AI agent, I want forge-agent to automatically create a git commit (checkpoint) every time a turn completes, so that I can safely roll back to any previous agent response.

Acceptance criteria

CheckpointReactor (`git/checkpoint.rs`)

Implements Reactor trait
Listens for OrchestrationEvent::TurnCompleted events
On TurnCompleted: looks up the thread's project path from the read model
Calls GitCore::commit() with the configured signature from GitConfig (commit_name, commit_email)
Commit message format: "forge-agent checkpoint — turn {turn_id}"
After successful commit, dispatches OrchestrationCommand::CreateCheckpoint back to the engine with the git hash
Respects GitConfig.auto_checkpoint — does nothing if disabled
Gracefully handles repos with no changes (no empty commits)

Checkpoint restore

RestoreCheckpoint command handling in the decider: validates checkpoint exists, emits CheckpointRestored
A reactor (or GitManager) responds to CheckpointRestored by calling git reset --hard to the checkpoint's git_ref
After restore, emits a new ThreadStatusChanged(Idle)

Tests

Test: TurnCompleted triggers a git commit in a temp repo
Test: auto_checkpoint=false skips the commit
Test: no-op when working tree has no changes
Test: RestoreCheckpoint resets the repo to the correct ref

Out of scope

Branch-per-thread strategy (post-v1 enhancement)
UI for browsing checkpoints (covered by frontend stories)

References

Spec §8.2 (CheckpointReactor)
Spec §5.1 (CreateCheckpoint, RestoreCheckpoint commands)

Dependencies

Blocked by: #3 (GitConfig), #4 (decider + RestoreCheckpoint extension), #7 (Reactor trait), #8 (GitCore::commit)
Blocks: none (v0.1 leaf)
Branch off: issue-7-engine
Full graph: #21

## User story As a **user running an AI agent**, I want forge-agent to automatically create a git commit (checkpoint) every time a turn completes, so that I can safely roll back to any previous agent response. ## Acceptance criteria ### CheckpointReactor (`git/checkpoint.rs`) - [ ] Implements `Reactor` trait - [ ] Listens for `OrchestrationEvent::TurnCompleted` events - [ ] On TurnCompleted: looks up the thread's project path from the read model - [ ] Calls `GitCore::commit()` with the configured signature from `GitConfig` (commit_name, commit_email) - [ ] Commit message format: `"forge-agent checkpoint — turn {turn_id}"` - [ ] After successful commit, dispatches `OrchestrationCommand::CreateCheckpoint` back to the engine with the git hash - [ ] Respects `GitConfig.auto_checkpoint` — does nothing if disabled - [ ] Gracefully handles repos with no changes (no empty commits) ### Checkpoint restore - [ ] `RestoreCheckpoint` command handling in the decider: validates checkpoint exists, emits `CheckpointRestored` - [ ] A reactor (or GitManager) responds to `CheckpointRestored` by calling `git reset --hard` to the checkpoint's `git_ref` - [ ] After restore, emits a new `ThreadStatusChanged(Idle)` ### Tests - [ ] Test: TurnCompleted triggers a git commit in a temp repo - [ ] Test: auto_checkpoint=false skips the commit - [ ] Test: no-op when working tree has no changes - [ ] Test: RestoreCheckpoint resets the repo to the correct ref ## Out of scope - Branch-per-thread strategy (post-v1 enhancement) - UI for browsing checkpoints (covered by frontend stories) ## References - Spec §8.2 (CheckpointReactor) - Spec §5.1 (CreateCheckpoint, RestoreCheckpoint commands) ## Dependencies - **Blocked by:** #3 (GitConfig), #4 (decider + RestoreCheckpoint extension), #7 (Reactor trait), #8 (GitCore::commit) - **Blocks:** none (v0.1 leaf) - **Branch off:** `issue-7-engine` - **Full graph:** #21

claude-desktop added this to the v0.1.0 milestone

2026-04-16 11:29:45 +00:00

claude-desktop added the

type:user-story

area:git

labels

2026-04-16 11:29:45 +00:00

claude-desktop referenced this issue

2026-04-16 20:22:35 +00:00

v0.1.0 dependency tree and implementation order #21

claude-desktop referenced this issue

2026-04-16 20:24:19 +00:00