Workflow Checkpoints

claudus_checkpoint_workflow writes a snapshot of asset paths + last-modified timestamps tied to a workflow id. Use it as an audit marker before any risky change: bulk material recompile, mass actor refactor, blueprint reparenting across a chain of derived classes, regenerating Niagara emitters from a template. The snapshot itself is small (paths + timestamps + class names, no asset payloads) and lives under Saved/ClaudusBridge/WorkflowCheckpoints/<checkpoint_id>.json.

Scope (v1)

v1 ships snapshot + list + diff — enough to answer "what did this agent touch?" and "what changed since the last milestone?". Rollback is intentionally out of scope until source-control integration lands. UE has no safe generic asset-revert primitive; we'd rather ship a real audit trail than a fragile "rollback" that breaks in subtle ways.

---

Quick start

# Snapshot every asset under /Game right now, tied to a workflow id
cb call claudus_checkpoint_workflow '{
  "workflow_id":  "material-rework-2026-05-15",
  "label":        "before bulk recompile of M_Holo derivatives",
  "scan_paths":   ["/Game/Materials/Holographic"]
}'

# Inventory the checkpoints for a workflow
cb call claudus_list_workflow_checkpoints '{
  "workflow_id":  "material-rework-2026-05-15"
}'

The response of claudus_checkpoint_workflow includes the checkpoint_file path. Read the JSON directly to diff later:

cat "Saved/ClaudusBridge/WorkflowCheckpoints/ck-material-rework-2026-05-15-…json"

---

How asset resolution works

claudus_checkpoint_workflow resolves the asset list in this strict order — the first non-empty source wins:

1. asset_paths array (explicit) — Use this when you know exactly which assets to snapshot. Example: ["/Game/Materials/M_Holo", "/Game/Blueprints/BP_Player"].
2. scan_paths array, piped through find_assets — Use this when you want to snapshot a directory tree. Each path becomes a find_assets(path=<scan_path>) call. Example: ["/Game/Materials/Holographic"] snapshots every asset under that folder.
3. The workflow's persisted assets[] field — If you've already attached assets to the workflow record via claudus_update_multi_agent_workflow, those will be used automatically.
4. Empty — Returns a checkpoint with zero assets (still useful as a marker in the audit log).

{
  "workflow_id": "material-rework-2026-05-15",
  "label":       "before bulk recompile of M_Holo derivatives",
  "asset_paths": [
    "/Game/Materials/Holographic/M_Holo.M_Holo",
    "/Game/Materials/Holographic/M_Holo_Inst_Red.M_Holo_Inst_Red",
    "/Game/Materials/Holographic/M_Holo_Inst_Blue.M_Holo_Inst_Blue"
  ]
}

asset_paths wins over scan_paths wins over the workflow's persisted list. Don't try to combine — pick the source that matches your intent.

---

Snapshot file format

Saved/ClaudusBridge/WorkflowCheckpoints/ck-<workflow_id>-<timestamp>.json:

{
  "schema":               "claudus.workflow_checkpoint.v1",
  "checkpoint_id":        "ck-material-rework-2026-05-15-074203",
  "workflow_id":          "material-rework-2026-05-15",
  "label":                "before bulk recompile of M_Holo derivatives",
  "captured_at":          "2026-05-15T07:42:03.117Z",
  "asset_count":          14,
  "assets": [
    {
      "path":         "/Game/Materials/Holographic/M_Holo.M_Holo",
      "class":        "Material",
      "captured_at":  "2026-05-15T07:42:03.115Z"
    },
    {
      "path":         "/Game/Materials/Holographic/M_Holo_Inst_Red.M_Holo_Inst_Red",
      "class":        "MaterialInstanceConstant",
      "captured_at":  "2026-05-15T07:42:03.115Z"
    },
    /* ... */
  ],
  "created_by_model":    "claude-opus-4-7[1m]",
  "created_by_provider": "Claude",
  "checkpoint_file":     "<ProjectDir>/Saved/ClaudusBridge/WorkflowCheckpoints/ck-material-rework-2026-05-15-074203.json"
}

The assets[].captured_at field is the asset's last-modified time at snapshot capture, not the snapshot's capture time — that lets you compare two checkpoints for the same workflow and see which assets moved without re-walking the registry.

---

Listing checkpoints

# All checkpoints across all workflows, newest first, capped at 50
cb call claudus_list_workflow_checkpoints

# Only the checkpoints for one workflow
cb call claudus_list_workflow_checkpoints '{
  "workflow_id":  "material-rework-2026-05-15",
  "limit":        20
}'

Returns a slim summary for each entry (checkpoint_id, workflow_id, label, captured_at, asset_count, checkpoint_file). To get the full asset list, read the file at checkpoint_file directly.

---

Auto-observation hook

Every successful claudus_checkpoint_workflow call also fires an auto_observation memory entry tagged:

auto_observation
workflow_checkpoint
<workflow_id>
<checkpoint_id>

So later you can do:

cb call claudus_recall_observations '{
  "tag":           "workflow_checkpoint",
  "since_hours":   168,
  "contains":      "material-rework"
}'

…and see every checkpoint point recorded in the last week without ever opening the WorkflowCheckpoints folder.

---

Suggested usage patterns

Before a bulk operation

WF=material-bulk-recompile-$(date +%Y%m%d-%H%M%S)

# 1. Snapshot
cb call claudus_checkpoint_workflow "{
  \"workflow_id\": \"$WF\",
  \"label\":       \"pre-bulk-recompile baseline\",
  \"scan_paths\":  [\"/Game/Materials/Holographic\"]
}"

# 2. Do the work
cb call recompile_material_batch '{"path_prefix": "/Game/Materials/Holographic"}'

# 3. Snapshot again
cb call claudus_checkpoint_workflow "{
  \"workflow_id\": \"$WF\",
  \"label\":       \"post-bulk-recompile result\",
  \"scan_paths\":  [\"/Game/Materials/Holographic\"]
}"

# 4. Diff with your tool of choice (jq, vimdiff, …)
diff <(jq '.assets' "WorkflowCheckpoints/ck-${WF}-…pre….json") \
     <(jq '.assets' "WorkflowCheckpoints/ck-${WF}-…post….json")

As a milestone marker inside a multi-agent workflow

If you're driving a multi-agent workflow (see Multi-Agent Workflows) and finish a step that changed asset state, call claudus_checkpoint_workflow with the same workflow_id. The auto-observation hook records the milestone in the journal, and you (or the next session) can read claudus_list_workflow_checkpoints(workflow_id=<that id>) to see the chronological progression.

Empty checkpoints as audit markers

Calling claudus_checkpoint_workflow with no asset_paths and no scan_paths is legal. It produces a zero-asset snapshot file (just the metadata) and an auto_observation entry. Useful when:

• You want a labelled point in the journal even though no asset state changed yet.
• You're starting a workflow and want the "T=0" marker before doing anything.
• A specialist sub-agent finished its phase and wants to mark "I'm done; here's the audit point" without re-scanning what it already snapshotted earlier.

---

What this does NOT do

• It does not back up asset content. Only paths + timestamps + class names. To back up content, use UE's native Source Control integration or copy Content/<path> manually.
• It does not roll back. v1 explicitly punts on rollback. If you need rollback, snapshot first via Source Control, then call this for the audit layer.
• It does not diff for you. claudus_list_workflow_checkpoints lists entries; you read the JSON files directly and diff with your preferred tool. A native diff tool is a candidate for v2.
• It does not detect external file changes. The captured_at per asset is read at snapshot time. If an asset changes after the snapshot, your only signal is taking another snapshot and comparing.

---

Where to go next

• Auto-Observations — Read back the workflow_checkpoint entries (and the action-failure, asset-created, workflow-completed entries) without opening files
• Multi-Agent Workflows — Tie checkpoints to a workflow record so the snapshots line up with the workflow's step history
• Cognition Tier overview — How checkpoints sit in the larger 0.6.x audit + snapshot story