Add resume detection and auto-resume to mgw:run startup

[snipcodeit]

Description

When mgw:run starts for an issue, check if a checkpoint exists with a pipeline_stage beyond new. If found, display the checkpoint state to the user and offer: (R)esume from checkpoint, (F)resh start (discard checkpoint), (S)kip issue. Resume loads the checkpoint state and jumps to the appropriate pipeline step, skipping already-completed work.

Acceptance Criteria

• Add resume detection and auto-resume to mgw:run startup

Milestone Context

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

Dependencies

implement-checkpoint-writes-at-each-pipeli

[snipcodeit]

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

Work Started

Issue	#237 — Add resume detection and auto-resume to mgw:run startup
Route	plan-phase
Progress	8/9 complete — final issue!

[snipcodeit]

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

Work Starting

Route	plan-phase — orchestration command changes with structured checkpoint detection logic require planning
Scope	medium — 3 files across lib, commands, workflows
Conflicts	Depends on PR #244 (#235) and PR #245 (#236)

Work begins on branch issue/237-add-resume-detection-and-auto-resume-to.

Affected Files

• lib/state.cjs — add detectCheckpoint, resumeFromCheckpoint, clearCheckpoint
• commands/run/triage.md — add checkpoint detection and resume logic to validate_and_load
• commands/workflows/state.md — document checkpoint resume functions and flow

[snipcodeit]

Plan: Add resume detection and auto-resume to mgw:run startup

Objective

When mgw:run starts for an issue, detect if a checkpoint exists with progress beyond triage.
If found, display the checkpoint state and offer Resume/Fresh/Skip options.

Tasks

Task 1: Add checkpoint detection functions to lib/state.cjs

• Files: lib/state.cjs
• Action: Add detectCheckpoint(issueNumber), resumeFromCheckpoint(issueNumber), clearCheckpoint(issueNumber)
• Verify: Functions return correct data for various checkpoint states
• Done: Functions exported and tested

Task 2: Update commands/run/triage.md with checkpoint detection logic

• Files: commands/run/triage.md
• Action: Add checkpoint detection after migrateProjectState() call, before pipeline_stage routing. Show checkpoint state via AskUserQuestion with Resume/Fresh/Skip options.
• Verify: Checkpoint detection pseudocode is complete and covers all cases
• Done: triage.md updated with full detection and prompt flow

Task 3: Document checkpoint resume in workflows/state.md

• Files: commands/workflows/state.md
• Action: Document resume detection functions, action-to-stage mapping, flow diagram, context shapes
• Verify: Documentation is complete and references correct function signatures
• Done: state.md updated with checkpoint resume section

[snipcodeit]

Summary: Add resume detection and auto-resume to mgw:run startup

One-liner

Added checkpoint detection and resume prompting to mgw:run startup, enabling recovery from interrupted pipeline sessions.

Changes

lib/state.cjs

• Added CHECKPOINT_STEP_ORDER constant: ordered pipeline step progression (triage, plan, execute, verify, pr)
• Added detectCheckpoint(issueNumber): checks if active state file has a checkpoint beyond triage step
• Added resumeFromCheckpoint(issueNumber): returns checkpoint data with computed resume stage and action mapping
• Added clearCheckpoint(issueNumber): resets checkpoint to null for fresh-start scenarios
• All three functions are fully tested with edge cases

commands/run/triage.md

• Added checkpoint detection block after migrateProjectState() in validate_and_load step
• Displays checkpoint state (step, completed work, artifacts, timestamps) to user
• Offers Resume/Fresh/Skip via AskUserQuestion
• Resume: sets RESUME_MODE=true and loads checkpoint context for downstream stages
• Fresh: calls clearCheckpoint() and resets pipeline_stage to triaged
• Skip: exits pipeline

commands/workflows/state.md

• Documented all three resume detection functions with signatures and return types
• Added resume action to pipeline stage mapping table
• Added resume detection flow diagram
• Documented pipeline step order and context shapes per action
• Updated consumers table with checkpoint resume entry

Verification

• All three functions tested with node directly
• Edge cases covered: null checkpoint, triage-only checkpoint, mid-execution checkpoint
• Existing exports verified (18 total, no regressions)