agentbook-version-control

AgentBook Version Control

Treat Git as the authority for files and AgentBook as the provenance layer for intent, evidence, decisions, tests, and recovery state. Never represent AgentBook as a replacement for Git.

Establish status

1. Inspect the current workspace, git status, and recent Git history before trusting recalled state.
2. Before the first CSM operation, call csm_runtime_status. Stop and report a provider or project-root mismatch.
3. Read csm_agentbook_state, recent csm_agentbook_events, goal_list, and list_checkpoints as needed.
4. Report status using five fields: workspace identity, active goal, latest checkpoint, verified evidence, and unresolved work.

Current files and test output outrank memory. Treat automatic event capture as a recovery log, not as a curated milestone.

Create a checkpoint

Create a checkpoint before an expensive, risky, or branching change and after a verified outcome. Include this information in the explicit message snapshot or milestone used to build it:

goal:
parent/baseline:
git commit:
dirty-tree status or diff hash:
change:
reason:
expected effect:
verification:
actual result:
decision: keep | revert | unresolved
known risks:
next action:

Use create_checkpoint for recoverable session state. Use bridge_sync_turn only for a durable milestone that automatic hooks cannot infer. Do not create redundant checkpoints for routine reads.

Branch and compare work

• Use Git branches or worktrees for file isolation. Do not invent a second source-control system.
• Give each agent attempt one explicit goal, baseline Git identity, and checkpoint lineage note.
• Keep parallel attempts disjoint where possible. Never merge or delete a branch without the user's authorization.
• Compare attempts across code and agent state: file diff, decisions, evidence, tests, performance, cost, failures, and open risks.
• Apply only the selected artifacts through normal Git operations. Record why the result was kept, combined, or rejected.