Implement checkpoint writes at each pipeline stage transition

[snipcodeit]

Description

Instrument mgw:run to write checkpoints at each pipeline_stage transition (new->triaged, triaged->planning, planning->executing, etc.). Each checkpoint captures the full state needed to resume from that point: issue context, triage results, plan artifacts, execution progress. Checkpoint writes are atomic (write to .tmp then rename) to prevent corruption from interrupts.

Acceptance Criteria

• Implement checkpoint writes at each pipeline stage transition

Milestone Context

• Milestone: v8 — Agent Reliability & Failure Recovery
• Phase: Phase 46: Checkpoint & Resume for Long-Running Pipelines
• GSD Route: plan-phase

Dependencies

design-checkpoint-schema-for-pipeline-exec

[snipcodeit]

MGW · work-started · 2026-03-06T07:43:56Z
Milestone: v8 | Phase 46: Checkpoint & Resume

Work Started

Issue	#236 — Implement checkpoint writes at each pipeline stage transition
Route	plan-phase
Progress	7/9 complete

[snipcodeit]

MGW · work-starting · 2026-03-06T07:46:38.023Z
Milestone: v8 — Agent Reliability & Failure Recovery | Phase 46: Checkpoint & Resume for Long-Running Pipelines

Work Starting

Route	plan-phase — orchestration changes across multiple command files require structured planning
Scope	medium — 5 files across lib, commands, workflows
Conflicts	Builds on PR #244 (#235) — checkpoint schema functions

Work begins on branch issue/236-implement-checkpoint-writes-at-each-pipe.

Affected Files

• lib/state.cjs (modify — add atomicCheckpointWrite, make updateCheckpoint atomic)
• commands/run/triage.md (modify — add checkpoint write at triage transition)
• commands/run/execute.md (modify — add checkpoint writes at plan/execute/verify transitions)
• commands/run/pr-create.md (modify — add checkpoint write at PR creation)
• commands/workflows/state.md (modify — document atomic checkpoint pattern)

[snipcodeit]

Plan: Implement checkpoint writes at each pipeline stage transition

Approach

1. Add atomicWriteJson() to lib/state.cjs — writes to .tmp then renames (POSIX atomic rename)
2. Make updateCheckpoint() use atomicWriteJson() internally for crash-safe writes
3. Instrument each pipeline stage transition in command markdown files with checkpoint write pseudocode
4. Document checkpoint schema, lifecycle, and atomic write pattern in workflows/state.md

Files Modified

• lib/state.cjs — atomicWriteJson(), initCheckpoint(), updateCheckpoint(), checkpoint migration
• commands/run/triage.md — checkpoint initialization after triage
• commands/run/execute.md — checkpoint writes at plan, execute, verify for both quick and milestone routes
• commands/run/pr-create.md — checkpoint write after PR creation
• commands/workflows/state.md — checkpoint schema docs, lifecycle table, consumer entries

Checkpoint Coverage

Stage	Quick Route	Milestone Route
Triage	triage.md	triage.md
Plan	execute.md step 4	execute.md step b1b
Execute	execute.md step 8	execute.md step d1b
Verify	execute.md step 10	execute.md step e1b
PR	pr-create.md	pr-create.md

[snipcodeit]

Summary: Checkpoint writes at each pipeline stage transition

What Changed

• Added atomicWriteJson(filePath, data) to lib/state.cjs — writes JSON to .tmp file then renames (POSIX atomic on same filesystem), preventing corrupt state files from mid-write crashes
• Made updateCheckpoint() use atomicWriteJson() internally — all checkpoint writes are now crash-safe by default
• Added initCheckpoint(pipelineStep) factory that produces a valid checkpoint object with schema_version, timestamps, empty arrays for append-only fields
• Added checkpoint migration to migrateProjectState() — adds checkpoint: null to existing issue state files
• Instrumented all 5 pipeline stages (triage, plan, execute, verify, pr) across both quick and milestone routes in command markdown pseudocode
• Added plan-phase route handling to execute.md (same lifecycle as quick --full)
• Documented checkpoint schema, merge strategies, lifecycle table, and consumer entries in workflows/state.md

Key Design Decisions

• Merge strategies: Scalar fields overwrite, step_progress shallow-merges, resume fully replaces, artifacts and step_history append-only
• Lazy initialization: checkpoint stays null until first pipeline run (no eagerly-created empty checkpoints)
• Atomic writes throughout: Every call to updateCheckpoint() goes through atomicWriteJson(), not just a separate atomic function

[snipcodeit]

Verification: Checkpoint writes at each pipeline stage transition

Acceptance Criteria Check

• atomicWriteJson() writes to .tmp then renames — implemented in lib/state.cjs
• updateCheckpoint() uses atomicWriteJson() internally — all checkpoint writes are atomic by default
• Checkpoint initialization in triage.md after triage completes
• Checkpoint write after planner in execute.md (quick + milestone routes)
• Checkpoint write after executor in execute.md (quick + milestone routes)
• Checkpoint write after verifier in execute.md (quick + milestone routes)
• Checkpoint write after PR creation in pr-create.md
• migrateProjectState() adds checkpoint: null to existing state files
• Checkpoint schema documented in workflows/state.md

Testing Performed

• initCheckpoint() returns valid checkpoint object with schema_version=1, timestamps, empty arrays
• atomicWriteJson() round-trip test: write JSON, read back, verify equality
• updateCheckpoint() with temporary state files: verifies merge strategies (overwrite scalars, append arrays, shallow-merge step_progress, full-replace resume)
• migrateProjectState() idempotent migration adds checkpoint field without overwriting existing data

Risk Assessment

• Low risk: All checkpoint writes are non-blocking (2>/dev/null || true)
• Low risk: Atomic rename is a well-understood POSIX primitive
• No breaking changes: checkpoint field is null by default, existing pipelines unaffected