checkpoint_protocol.md

Checkpoint SOP (required) - if files do not exist, create them.

• Canonical invocation pattern (works from any folder):
  • python /path/to/context_checkpoint.py --repo-root <TARGET_REPO> <snapshot|resume> ...
• Checkpoint files live in <repo-root>/runtime/checkpoints/ by default.
• Optional override:
  • --checkpoint-dir <PATH>
  • relative paths are resolved from --repo-root; absolute paths are used as-is.
• Update both runtime/checkpoints/LATEST.md and runtime/checkpoints/LATEST.json at:
  • phase start
  • post-green tests
  • PR open
  • post-merge
• Use per-workstream tracks so parallel agents do not overwrite each other.
• Required track protocol:
  • every snapshot must include --track "<WORKSTREAM_NAME>" (required)
  • example tracks: MNO_LEAN_RETRIEVAL WORK, JX_JUMP_DEBUG WORK
  • use --no-set-current when checkpointing a secondary parallel track
  • never delete another track from LATEST.*; append/update only your own track
• --extra protocol:
  • every --extra entry must be key=value
  • malformed entries fail fast; do not pass free-form strings
• LATEST.md must include:
  • ## CURRENT (selected track summary)
  • one ## <WORKSTREAM_NAME> section for each parallel stream
• LATEST.json must include:
  • current_track
  • tracks map keyed by workstream name
• Include step, note, branch, head, next_cmd, and validations per track.
• Snapshot example:
  • python /path/to/context_checkpoint.py --repo-root . snapshot --step "phase start" --note "beginning implementation" --next-cmd "python -m pytest -q" --track "MNO_LEAN_RETRIEVAL WORK"
• Resume order after compaction/crash:
  1. read LATEST.md + LATEST.json
  2. verify git status --short --branch and head commit (if available)
  3. resume your track and run that track's next_cmd (python /path/to/context_checkpoint.py --repo-root . resume --track "<WORKSTREAM_NAME>")
  4. write fresh checkpoint before edits