@snipcodeit/mgw 0.3.0 → 0.6.0

package/commands/workflows/state.md

@@ -227,13 +227,186 @@ File: `.mgw/active/<number>-<slug>.json`
   "gsd_route": null,
   "gsd_artifacts": { "type": null, "path": null },
   "pipeline_stage": "new|triaged|needs-info|needs-security-review|discussing|approved|planning|diagnosing|executing|verifying|pr-created|done|failed|blocked",
+  "checkpoint": null,
   "comments_posted": [],
   "linked_pr": null,
   "linked_issues": [],
-  "linked_branches": []
+  "linked_branches": [],
+  "checkpoint": null
 }
 ```
 
+## Checkpoint Schema
+
+The `checkpoint` field in `.mgw/active/<number>-<slug>.json` tracks fine-grained pipeline
+execution progress. It enables resume after failures, context switches, or multi-session
+execution. The field is `null` until pipeline execution begins (set during the triage-to-
+executing transition).
+
+### Checkpoint Object Structure
+
+```json
+{
+  "checkpoint": {
+    "schema_version": 1,
+    "pipeline_step": "triage|plan|execute|verify|pr",
+    "step_progress": {},
+    "last_agent_output": null,
+    "artifacts": [],
+    "resume": {
+      "action": null,
+      "context": {}
+    },
+    "started_at": "2026-03-06T12:00:00Z",
+    "updated_at": "2026-03-06T12:05:00Z",
+    "step_history": []
+  }
+}
+```
+
+### Checkpoint Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `schema_version` | integer | `1` | Schema version for forward-compatibility. Consumers check this before parsing. New fields can be added without bumping; bump only for breaking structural changes. |
+| `pipeline_step` | string | `"triage"` | Current high-level pipeline step. Values: `"triage"`, `"plan"`, `"execute"`, `"verify"`, `"pr"`. Maps to GSD lifecycle stages but at a coarser grain than `pipeline_stage`. |
+| `step_progress` | object | `{}` | Step-specific progress data. Shape varies by `pipeline_step` (see Step Progress Shapes below). Unknown keys are preserved on read -- consumers must not strip unrecognized fields. |
+| `last_agent_output` | string\|null | `null` | File path (relative to repo root) of the last successful agent output. Updated after each agent spawn completes. Used for resume context injection. |
+| `artifacts` | array | `[]` | Accumulated artifact paths produced during this pipeline run. Each entry is `{ "path": "relative/path", "type": "plan\|summary\|verification\|commit", "created_at": "ISO" }`. Append-only -- never remove entries. |
+| `resume` | object | `{ "action": null, "context": {} }` | Instructions for resuming execution. `action` is a string describing what to do next (e.g., `"spawn-executor"`, `"retry-verifier"`, `"create-pr"`). `context` carries step-specific data needed for resume (e.g., `{ "phase_number": 3, "plan_path": ".planning/..." }`). |
+| `started_at` | string | ISO timestamp | When checkpoint tracking began for this pipeline run. |
+| `updated_at` | string | ISO timestamp | When the checkpoint was last modified. Updated on every checkpoint write. |
+| `step_history` | array | `[]` | Ordered log of completed steps. Each entry: `{ "step": "plan", "completed_at": "ISO", "agent_type": "gsd-planner", "output_path": "..." }`. Append-only. |
+
+### Step Progress Shapes
+
+The `step_progress` object has a different shape depending on the current `pipeline_step`.
+These are the documented shapes; future pipeline steps can define their own without breaking
+existing consumers (unknown keys are preserved).
+
+**When `pipeline_step` is `"triage"`:**
+```json
+{
+  "comment_check_done": false,
+  "route_selected": null
+}
+```
+
+**When `pipeline_step` is `"plan"`:**
+```json
+{
+  "plan_path": null,
+  "plan_checked": false,
+  "revision_count": 0
+}
+```
+
+**When `pipeline_step` is `"execute"`:**
+```json
+{
+  "gsd_phase": null,
+  "total_phases": null,
+  "current_task": null,
+  "tasks_completed": 0,
+  "tasks_total": null,
+  "commits": []
+}
+```
+
+**When `pipeline_step` is `"verify"`:**
+```json
+{
+  "verification_path": null,
+  "must_haves_checked": false,
+  "artifact_check_done": false,
+  "keylink_check_done": false
+}
+```
+
+**When `pipeline_step` is `"pr"`:**
+```json
+{
+  "branch_pushed": false,
+  "pr_number": null,
+  "pr_url": null
+}
+```
+
+### Forward Compatibility Contract
+
+1. **New fields can be added** to the checkpoint object at any level without incrementing
+   `schema_version`. Consumers must tolerate unknown fields (preserve on read-modify-write,
+   ignore on read-only access).
+
+2. **New `pipeline_step` values** can be introduced freely. Existing step_progress shapes
+   are not affected. The `step_progress` for an unrecognized step should be treated as an
+   opaque object (pass through unchanged).
+
+3. **`schema_version` bump** is required only when an existing field changes its type,
+   semantics, or is removed. When bumped, `migrateProjectState()` in `lib/state.cjs` must
+   handle the migration.
+
+4. **`artifacts` and `step_history` are append-only**. Consumers should never modify or
+   remove entries from these arrays. They may be compacted during archival (when pipeline
+   reaches `done` stage and state moves to `.mgw/completed/`).
+
+5. **`resume.context` is opaque** to all consumers except the specific resume handler for
+   the given `resume.action`. This allows step-specific resume data to evolve independently.
+
+### Checkpoint Lifecycle
+
+```
+triage (checkpoint initialized, pipeline_step="triage")
+  |
+  v
+plan (pipeline_step="plan", step_progress tracks planning state)
+  |
+  v
+execute (pipeline_step="execute", step_progress tracks GSD phase/task progress)
+  |
+  v
+verify (pipeline_step="verify", step_progress tracks verification checks)
+  |
+  v
+pr (pipeline_step="pr", step_progress tracks PR creation)
+  |
+  v
+done (checkpoint frozen — archived to .mgw/completed/)
+```
+
+### Checkpoint Update Pattern
+
+```bash
+# Update checkpoint at key pipeline stages using updateCheckpoint()
+node -e "
+const { updateCheckpoint } = require('./lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'execute',
+  step_progress: {
+    gsd_phase: ${PHASE_NUMBER},
+    tasks_completed: ${COMPLETED},
+    tasks_total: ${TOTAL}
+  },
+  last_agent_output: '${OUTPUT_PATH}',
+  resume: {
+    action: 'continue-execution',
+    context: { phase_number: ${PHASE_NUMBER} }
+  }
+});
+"
+```
+
+### Consumers
+
+| Consumer | Access Pattern |
+|----------|---------------|
+| run/triage.md | Initialize checkpoint at triage (`pipeline_step: "triage"`) |
+| run/execute.md | Update checkpoint after each agent spawn (`pipeline_step: "plan"\|"execute"\|"verify"`) |
+| run/pr-create.md | Update checkpoint at PR creation (`pipeline_step: "pr"`) |
+| milestone.md | Read checkpoint to determine resume point for failed issues |
+| status.md | Read checkpoint for detailed progress display |
+| sync.md | Compare checkpoint state against GitHub for drift detection |
+
 ## Stage Flow Diagram
 
 ```
@@ -264,6 +437,84 @@ blocked --> triaged     (re-triage after blocker resolved)
 Any stage --> failed    (unrecoverable error)
 ```
 
+## Pipeline Checkpoints
+
+Fine-grained pipeline progress tracking within `.mgw/active/<number>-<slug>.json`.
+The `checkpoint` field starts as `null` and is initialized when the pipeline first
+transitions past triage. Each subsequent stage writes an atomic checkpoint update.
+
+### Checkpoint Schema
+
+```json
+{
+  "checkpoint": {
+    "schema_version": 1,
+    "pipeline_step": "triage|plan|execute|verify|pr",
+    "step_progress": {},
+    "last_agent_output": null,
+    "artifacts": [],
+    "resume": { "action": null, "context": {} },
+    "started_at": "ISO timestamp",
+    "updated_at": "ISO timestamp",
+    "step_history": []
+  }
+}
+```
+
+| Field | Type | Merge Strategy | Description |
+|-------|------|---------------|-------------|
+| `schema_version` | number | — | Checkpoint format version (currently 1) |
+| `pipeline_step` | string | overwrite | Current pipeline step: `triage`, `plan`, `execute`, `verify`, `pr` |
+| `step_progress` | object | shallow merge | Step-specific progress (e.g., `{ plan_path: "...", plan_checked: false }`) |
+| `last_agent_output` | string\|null | overwrite | Path or URL of the last agent's output |
+| `artifacts` | array | append-only | `[{ path, type, created_at }]` — never removed, only appended |
+| `resume` | object | full replace | `{ action, context }` — what to do if pipeline restarts |
+| `started_at` | string | — | ISO timestamp when checkpoint was first created |
+| `updated_at` | string | auto | ISO timestamp of last update (set automatically) |
+| `step_history` | array | append-only | `[{ step, completed_at, agent_type, output_path }]` — audit trail |
+
+### Atomic Writes
+
+All checkpoint writes use `atomicWriteJson()` from `lib/state.cjs`:
+
+```bash
+# atomicWriteJson(filePath, data) — write to .tmp then rename.
+# POSIX rename is atomic on the same filesystem, so a crash mid-write
+# never leaves a corrupt state file.
+```
+
+The `updateCheckpoint()` function uses `atomicWriteJson()` internally. Commands
+should always use `updateCheckpoint()` rather than writing checkpoints directly:
+
+```bash
+node -e "
+const { updateCheckpoint } = require('./lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'plan',
+  step_progress: { plan_path: '...', plan_checked: false },
+  artifacts: [{ path: '...', type: 'plan', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'plan', completed_at: new Date().toISOString(), agent_type: 'gsd-planner', output_path: '...' }],
+  resume: { action: 'spawn-executor', context: { quick_dir: '...' } }
+});
+" 2>/dev/null || true
+```
+
+### Checkpoint Lifecycle
+
+| Pipeline Step | Checkpoint `pipeline_step` | Resume Action |
+|--------------|---------------------------|---------------|
+| Triage complete | `triage` | `begin-execution` |
+| Planner complete | `plan` | `run-plan-checker` or `spawn-executor` |
+| Executor complete | `execute` | `spawn-verifier` or `create-pr` |
+| Verifier complete | `verify` | `create-pr` |
+| PR created | `pr` | `cleanup` |
+
+### Migration
+
+`migrateProjectState()` adds the `checkpoint: null` field to any issue state
+files that predate checkpoint support. The field is initialized lazily — it
+stays `null` until the pipeline actually runs.
+
 ## Slug Generation
 
 Use gsd-tools for consistent slug generation:
@@ -396,6 +647,91 @@ GSD phase directory (`.planning/phases/{NN}-{slug}/`) to operate in.
 Issues created outside of `/mgw:project` (e.g., manually filed bugs) will not have
 a `phase_number`. In this case, `/mgw:run` falls back to the quick pipeline.
 
+## Checkpoint Resume Detection
+
+When `mgw:run` starts for an issue, the validate_and_load step checks whether a prior
+pipeline run left a checkpoint with progress beyond the initial triage step. This enables
+resuming interrupted sessions without re-doing completed work.
+
+### Resume Detection Functions (lib/state.cjs)
+
+| Function | Signature | Returns | Description |
+|----------|-----------|---------|-------------|
+| `detectCheckpoint` | `(issueNumber)` | `object\|null` | Checks if active state file has a non-null checkpoint with `pipeline_step` beyond `"triage"`. Returns the checkpoint data if resumable, `null` otherwise. |
+| `resumeFromCheckpoint` | `(issueNumber)` | `object\|null` | Returns checkpoint data plus computed `resumeStage`, `resumeAction`, and `completedSteps`. Maps `resume.action` to the pipeline stage to jump to. |
+| `clearCheckpoint` | `(issueNumber)` | `{ cleared: boolean }` | Resets the checkpoint field to `null` in the active state file. Used for "Fresh start" option. |
+
+### Resume Action to Stage Mapping
+
+The `resume.action` field in the checkpoint tells `resumeFromCheckpoint()` which pipeline
+stage to jump to:
+
+| resume.action | resumeStage | Meaning |
+|---------------|-------------|---------|
+| `run-plan-checker` | `planning` | Plan exists, needs quality check |
+| `spawn-executor` | `executing` | Plan complete, execute next |
+| `continue-execution` | `executing` | Mid-execution resume |
+| `spawn-verifier` | `verifying` | Execution done, verify next |
+| `create-pr` | `pr-pending` | Verification done, create PR |
+| `begin-execution` | `planning` | Triage done, begin planning |
+| `null` / unknown | `planning` | Safe default |
+
+### Resume Detection Flow
+
+```
+mgw:run #N starts
+  |
+  v
+Load state file → migrateProjectState()
+  |
+  v
+detectCheckpoint(N)
+  |
+  +---> null (no checkpoint or triage-only) → proceed with normal stage routing
+  |
+  +---> checkpoint found → display state to user
+           |
+           v
+        AskUserQuestion: Resume / Fresh / Skip
+           |
+           +---> Resume: load checkpoint context, set RESUME_MODE=true,
+           |             jump to resume.action stage (skip completed steps)
+           |
+           +---> Fresh: clearCheckpoint(N), reset pipeline_stage to "triaged",
+           |            continue normal pipeline
+           |
+           +---> Skip: exit pipeline for this issue
+```
+
+### Pipeline Step Order
+
+The `CHECKPOINT_STEP_ORDER` constant defines the ordered progression of checkpoint steps:
+
+```
+triage → plan → execute → verify → pr
+```
+
+Only checkpoints with `pipeline_step` at index > 0 (beyond `"triage"`) are considered
+resumable. A checkpoint at `"triage"` means nothing meaningful has been completed yet.
+
+### Resume Context
+
+When resuming, the `resume.context` object carries step-specific data needed by the
+target stage. The context shape varies by `resume.action`:
+
+| resume.action | Context fields |
+|---------------|----------------|
+| `spawn-executor` | `{ quick_dir, plan_num }` |
+| `run-plan-checker` | `{ quick_dir, plan_num }` |
+| `spawn-verifier` | `{ quick_dir, plan_num }` |
+| `create-pr` | `{ quick_dir, plan_num }` |
+| `continue-execution` | `{ phase_number }` |
+| `begin-execution` | `{ gsd_route, branch }` |
+
+Downstream pipeline stages read `resume.context` to pick up where the prior run left
+off. For example, the executor stage uses `quick_dir` and `plan_num` to locate the
+existing plan files rather than re-creating them.
+
 ## Consumers
 
 | Pattern | Referenced By |
@@ -410,3 +746,6 @@ a `phase_number`. In this case, `/mgw:run` falls back to the quick pipeline.
 | Project state | milestone.md, next.md, ask.md |
 | Gate result schema | issue.md (populate), run.md (validate) |
 | Board status sync | board-sync.md (utility), issue.md (triage transitions), run.md (pipeline transitions) |
+| Checkpoint resume | run.md (detect + prompt), milestone.md (detect resume point for failed issues) |
+| Checkpoint writes | triage.md (init), execute.md (plan/execute/verify), pr-create.md (pr) |
+| Atomic writes | lib/state.cjs (`atomicWriteJson`, `updateCheckpoint`) |

package/dist/bin/mgw.cjs

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 'use strict';
 
-var index = require('../index-s7v-ifd0.cjs');
+var index = require('../index-CHrVAIMY.cjs');
 var require$$0 = require('commander');
 var require$$1 = require('path');
-var require$$0$2 = require('fs');
+var require$$2 = require('fs');
 var require$$0$1 = require('child_process');
+require('os');
 require('events');
 
 var mgw$1 = {};
 
-var version = "0.3.0";
+var version = "0.6.0";
 var require$$11 = {
 	version: version};
 
@@ -21,9 +22,9 @@ function requireMgw () {
 	hasRequiredMgw = 1;
 	const { Command } = require$$0;
 	const path = require$$1;
-	const fs = require$$0$2;
+	const fs = require$$2;
 	const { execSync } = require$$0$1;
-	const { assertClaudeAvailable, invokeClaude, getCommandsDir } = index.requireClaude();
+	const { ProviderManager } = index.requireProviderManager();
 	const { log, error, formatJson, verbose } = index.requireOutput();
 	const { getActiveDir, getCompletedDir, getMgwDir } = index.requireState();
 	const { getIssue, listIssues } = index.requireGithub();
@@ -32,7 +33,7 @@ function requireMgw () {
 	const { startTimer } = index.requireLogger();
 	const pkg = require$$11;
 	const program = new Command();
-	program.name("mgw").description("GitHub issue pipeline automation \u2014 Day 1 idea to Go Live").version(pkg.version).option("--dry-run", "show what would happen without executing").option("--json", "output structured JSON").option("-v, --verbose", "show API calls and file writes").option("--debug", "full payloads and timings").option("--model <model>", "Claude model override");
+	program.name("mgw").description("GitHub issue pipeline automation \u2014 Day 1 idea to Go Live").version(pkg.version).option("--dry-run", "show what would happen without executing").option("--json", "output structured JSON").option("-v, --verbose", "show API calls and file writes").option("--debug", "full payloads and timings").option("--model <model>", "Claude model override").option("--provider <provider>", "AI provider override (default: claude)");
 	const STAGE_LABELS = {
 	  run: "pipeline",
 	  init: "init",
@@ -44,8 +45,9 @@ function requireMgw () {
 	  next: "next"
 	};
 	async function runAiCommand(commandName, userPrompt, opts) {
-	  assertClaudeAvailable();
-	  const cmdFile = path.join(getCommandsDir(), `${commandName}.md`);
+	  const provider = ProviderManager.getProvider(opts.provider);
+	  provider.assertAvailable();
+	  const cmdFile = path.join(provider.getCommandsDir(), `${commandName}.md`);
 	  const stageLabel = STAGE_LABELS[commandName] || commandName;
 	  const issueMatch = String(userPrompt).match(/^\d+/);
 	  const timer = startTimer({
@@ -57,7 +59,7 @@ function requireMgw () {
 	    spinner.start();
 	    let result;
 	    try {
-	      result = await invokeClaude(cmdFile, userPrompt, {
+	      result = await provider.invoke(cmdFile, userPrompt, {
 	        model: opts.model,
 	        quiet: true,
 	        dryRun: opts.dryRun,
@@ -84,7 +86,7 @@ function requireMgw () {
 	    spinner.start();
 	    await new Promise((r) => setTimeout(r, 80));
 	    spinner.stop();
-	    const result = await invokeClaude(cmdFile, userPrompt, {
+	    const result = await provider.invoke(cmdFile, userPrompt, {
 	      model: opts.model,
 	      quiet: false,
 	      dryRun: opts.dryRun,
@@ -433,7 +435,8 @@ function requireMgw () {
 	  }
 	});
 	program.command("help").description("Show command reference").action(function() {
-	  const helpMdPath = path.join(getCommandsDir(), "help.md");
+	  const opts = this.optsWithGlobals();
+	  const helpMdPath = path.join(ProviderManager.getProvider(opts.provider).getCommandsDir(), "help.md");
 	  let helpText;
 	  try {
 	    const raw = fs.readFileSync(helpMdPath, "utf-8");