@snipcodeit/mgw 0.3.0 → 0.6.0

package/commands/run/execute.md

@@ -4,9 +4,16 @@ description: Execute GSD pipeline (quick or milestone route) and post execution
 ---
 
 <step name="execute_gsd_quick">
-**Execute GSD pipeline (quick / quick --full route):**
+**Execute GSD pipeline (quick / quick --full / plan-phase route):**
 
-Only run this step if gsd_route is "gsd:quick" or "gsd:quick --full".
+Only run this step if gsd_route matches any of these (prefixed or unprefixed):
+- `quick` or `gsd:quick`
+- `quick --full` or `gsd:quick --full`
+- `plan-phase` or `gsd:plan-phase`
+
+`plan-phase` follows the same lifecycle as `quick --full` (init -> plan -> check -> execute -> verify -> publish) so it is handled here with FULL_MODE forced on.
+
+`plan-phase` follows the same lifecycle as `quick --full` (init → plan → check → execute → verify → publish) so it is handled here with FULL_MODE forced on.
 
 **Retry loop initialization:**
 ```bash
@@ -60,12 +67,47 @@ QUICK_DIR=".planning/quick/${next_num}-${slug}"
 mkdir -p "$QUICK_DIR"
 ```
 
-3. **Spawn planner (task agent):**
+3. **Assemble MGW context and spawn planner (task agent, with diagnostic capture):**
+
+Assemble multi-machine context from GitHub issue comments before spawning:
+```bash
+MGW_CONTEXT=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.buildGSDPromptContext({
+  milestone: ${MILESTONE_NUM},
+  phase: ${PHASE_NUMBER},
+  issueNumber: ${ISSUE_NUMBER},
+  includeVision: true,
+  includePriorSummaries: true,
+  includeCurrentPlan: false
+}).then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
+```
+
+<!-- mgw:criticality=critical  spawn_point=planner -->
+<!-- Critical: plan creation is required for pipeline to proceed.
+     On failure: retry via existing retry loop, then dead-letter. -->
+
+**Pre-spawn diagnostic hook (planner):**
+```bash
+DIAG_PLANNER=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'gsd-planner',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: 'Plan: ${issue_title}',
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+```
 ```
 Task(
   prompt="
 <planning_context>
 
+${MGW_CONTEXT}
+
 **Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
 **Directory:** ${QUICK_DIR}
 **Description:** ${TASK_DESCRIPTION}
@@ -109,7 +151,68 @@ Return: ## PLANNING COMPLETE with plan path
 )
 ```
 
-4. **Verify plan exists** at `${QUICK_DIR}/${next_num}-PLAN.md`
+4. **Update checkpoint after planner completes:**
+```bash
+# Checkpoint: record plan completion and set resume to plan-check or execution
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'plan',
+  step_progress: { plan_path: '${QUICK_DIR}/${next_num}-PLAN.md', plan_checked: false, revision_count: 0 },
+  last_agent_output: '${QUICK_DIR}/${next_num}-PLAN.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-PLAN.md', type: 'plan', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'plan', completed_at: new Date().toISOString(), agent_type: 'gsd-planner', output_path: '${QUICK_DIR}/${next_num}-PLAN.md' }],
+  resume: { action: '${FULL_MODE ? \"run-plan-checker\" : \"spawn-executor\"}', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+
+**Post-spawn diagnostic hook (planner):**
+```bash
+PLANNER_EXIT=$( [ -f "${QUICK_DIR}/${next_num}-PLAN.md" ] && echo "success" || echo "error" )
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_PLANNER}',
+  exitReason: '${PLANNER_EXIT}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
+4. **Checkpoint: record plan completion (atomic write):**
+```bash
+# Checkpoint: record plan completion and set resume to plan-check or execution.
+# All checkpoint writes use atomicWriteJson() — write to .tmp then rename.
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'plan',
+  step_progress: { plan_path: '${QUICK_DIR}/${next_num}-PLAN.md', plan_checked: false, revision_count: 0 },
+  last_agent_output: '${QUICK_DIR}/${next_num}-PLAN.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-PLAN.md', type: 'plan', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'plan', completed_at: new Date().toISOString(), agent_type: 'gsd-planner', output_path: '${QUICK_DIR}/${next_num}-PLAN.md' }],
+  resume: { action: '${FULL_MODE ? \"run-plan-checker\" : \"spawn-executor\"}', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+});
+" 2>/dev/null || true
+```
+
+4b. **Publish plan comment (non-blocking):**
+
+4b. **Publish plan comment (non-blocking):**
+
+4. **Publish plan comment (non-blocking):**
+```bash
+PLAN_FILE="${QUICK_DIR}/${next_num}-PLAN.md"
+if [ -f "$PLAN_FILE" ]; then
+  node -e "
+    const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+    const fs = require('fs');
+    const content = fs.readFileSync('${PLAN_FILE}', 'utf-8');
+    ic.postPlanningComment(${ISSUE_NUMBER}, 'plan', content, { phase: ${next_num}, milestone: ${MILESTONE_NUM} })
+      .catch(e => console.error('WARNING: Failed to post plan comment:', e.message));
+  " 2>/dev/null || true
+fi
+```
+
+5. **Verify plan exists** at `${QUICK_DIR}/${next_num}-PLAN.md`
 
 5. **Pre-flight plan structure check (gsd-tools):**
 ```bash
@@ -118,6 +221,37 @@ PLAN_CHECK=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify plan-structur
 Parse the JSON result. If structural issues found, include them in the plan-checker prompt below so it has concrete problems to evaluate rather than searching from scratch.
 
 6. **(If --full) Spawn plan-checker, handle revision loop (max 2 iterations):**
+
+<!-- mgw:criticality=advisory  spawn_point=plan-checker -->
+<!-- Advisory: plan checking is a quality gate, not a pipeline blocker.
+     If this agent fails, log a warning and proceed with the unchecked plan.
+     The plan was already verified structurally by gsd-tools verify plan-structure.
+
+     Graceful degradation pattern:
+     ```
+     PLAN_CHECK_RESULT=$(wrapAdvisoryAgent(Task(...), 'plan-checker', {
+       issueNumber: ISSUE_NUMBER,
+       fallback: '## VERIFICATION PASSED (plan-checker unavailable — structural check only)'
+     }))
+     # If fallback returned, skip the revision loop and proceed to execution
+     ```
+-->
+
+6. **(If --full) Spawn plan-checker (with diagnostic capture), handle revision loop (max 2 iterations):**
+
+**Pre-spawn diagnostic hook (plan-checker):**
+```bash
+DIAG_CHECKER=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'gsd-plan-checker',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: 'Check quick plan: ${issue_title}',
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+```
 ```
 Task(
   prompt="
@@ -159,10 +293,43 @@ Skip: context compliance (no CONTEXT.md), cross-plan deps (single plan), ROADMAP
 )
 ```
 
+**Post-spawn diagnostic hook (plan-checker):**
+```bash
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_CHECKER}',
+  exitReason: 'success',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
 If issues found and iteration < 2: spawn planner revision, then re-check.
 If iteration >= 2: offer force proceed or abort.
 
 7. **Spawn executor (task agent):**
+
+<!-- mgw:criticality=critical  spawn_point=executor -->
+<!-- Critical: execution produces the code changes. Without it, there is
+     nothing to commit or PR. On failure: retry via existing retry loop,
+     then dead-letter. -->
+
+7. **Spawn executor (task agent, with diagnostic capture):**
+
+**Pre-spawn diagnostic hook (executor):**
+```bash
+DIAG_EXECUTOR=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'gsd-executor',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: 'Execute: ${issue_title}',
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+```
 ```
 Task(
   prompt="
@@ -187,13 +354,106 @@ Execute quick task ${next_num}.
 )
 ```
 
-8. **Verify summary (gsd-tools):**
+8. **Update checkpoint after executor completes:**
+```bash
+# Checkpoint: record execution completion and set resume to verification
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'execute',
+  step_progress: { tasks_completed: ${TASK_COUNT}, tasks_total: ${TASK_COUNT} },
+  last_agent_output: '${QUICK_DIR}/${next_num}-SUMMARY.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-SUMMARY.md', type: 'summary', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'execute', completed_at: new Date().toISOString(), agent_type: 'gsd-executor', output_path: '${QUICK_DIR}/${next_num}-SUMMARY.md' }],
+  resume: { action: '${FULL_MODE ? \"spawn-verifier\" : \"create-pr\"}', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+
+**Post-spawn diagnostic hook (executor):**
+```bash
+EXECUTOR_EXIT=$( [ -f "${QUICK_DIR}/${next_num}-SUMMARY.md" ] && echo "success" || echo "error" )
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_EXECUTOR}',
+  exitReason: '${EXECUTOR_EXIT}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
+8. **Checkpoint: record execution completion (atomic write):**
+```bash
+# Checkpoint: record execution completion and set resume to verification or PR creation.
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'execute',
+  step_progress: { tasks_completed: ${TASK_COUNT}, tasks_total: ${TASK_COUNT} },
+  last_agent_output: '${QUICK_DIR}/${next_num}-SUMMARY.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-SUMMARY.md', type: 'summary', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'execute', completed_at: new Date().toISOString(), agent_type: 'gsd-executor', output_path: '${QUICK_DIR}/${next_num}-SUMMARY.md' }],
+  resume: { action: '${FULL_MODE ? \"spawn-verifier\" : \"create-pr\"}', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+});
+" 2>/dev/null || true
+```
+
+8b. **Publish summary comment (non-blocking):**
+
+8b. **Publish summary comment (non-blocking):**
+
+8. **Publish summary comment (non-blocking):**
+```bash
+SUMMARY_FILE="${QUICK_DIR}/${next_num}-SUMMARY.md"
+if [ -f "$SUMMARY_FILE" ]; then
+  node -e "
+    const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+    const fs = require('fs');
+    const content = fs.readFileSync('${SUMMARY_FILE}', 'utf-8');
+    ic.postPlanningComment(${ISSUE_NUMBER}, 'summary', content, { phase: ${next_num}, milestone: ${MILESTONE_NUM} })
+      .catch(e => console.error('WARNING: Failed to post summary comment:', e.message));
+  " 2>/dev/null || true
+fi
+```
+
+9. **Verify summary (gsd-tools):**
 ```bash
 VERIFY_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify-summary "${QUICK_DIR}/${next_num}-SUMMARY.md")
 ```
 Parse JSON result. Use `passed` field for go/no-go. Checks summary existence, files created, and commits.
 
 9. **(If --full) Spawn verifier:**
+
+<!-- mgw:criticality=advisory  spawn_point=verifier -->
+<!-- Advisory: verification is quality assurance after execution is complete.
+     The code changes and commits already exist. If verification fails,
+     log a warning and proceed to PR creation with a note that verification
+     was skipped.
+
+     Graceful degradation pattern:
+     ```
+     VERIFY_RESULT=$(wrapAdvisoryAgent(Task(...), 'verifier', {
+       issueNumber: ISSUE_NUMBER,
+       fallback: null
+     }))
+     # If fallback returned (null), create a minimal VERIFICATION.md:
+     #   "## VERIFICATION SKIPPED\nVerifier agent unavailable. Manual review recommended."
+     ```
+-->
+
+9. **(If --full) Spawn verifier (with diagnostic capture):**
+
+**Pre-spawn diagnostic hook (verifier):**
+```bash
+DIAG_VERIFIER=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'gsd-verifier',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: 'Verify: ${issue_title}',
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+```
 ```
 Task(
   prompt="
@@ -214,7 +474,67 @@ Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}
 )
 ```
 
-10. **Post-execution artifact verification (non-blocking):**
+10. **Update checkpoint after verifier completes (--full only):**
+```bash
+# Checkpoint: record verification completion and set resume to PR creation
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'verify',
+  step_progress: { verification_path: '${QUICK_DIR}/${next_num}-VERIFICATION.md', must_haves_checked: true },
+  last_agent_output: '${QUICK_DIR}/${next_num}-VERIFICATION.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-VERIFICATION.md', type: 'verification', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'verify', completed_at: new Date().toISOString(), agent_type: 'gsd-verifier', output_path: '${QUICK_DIR}/${next_num}-VERIFICATION.md' }],
+  resume: { action: 'create-pr', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+
+**Post-spawn diagnostic hook (verifier):**
+```bash
+VERIFIER_EXIT=$( [ -f "${QUICK_DIR}/${next_num}-VERIFICATION.md" ] && echo "success" || echo "error" )
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_VERIFIER}',
+  exitReason: '${VERIFIER_EXIT}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
+10. **Checkpoint: record verification completion (atomic write, --full only):**
+```bash
+# Checkpoint: record verification completion and set resume to PR creation.
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'verify',
+  step_progress: { verification_path: '${QUICK_DIR}/${next_num}-VERIFICATION.md', must_haves_checked: true },
+  last_agent_output: '${QUICK_DIR}/${next_num}-VERIFICATION.md',
+  artifacts: [{ path: '${QUICK_DIR}/${next_num}-VERIFICATION.md', type: 'verification', created_at: new Date().toISOString() }],
+  step_history: [{ step: 'verify', completed_at: new Date().toISOString(), agent_type: 'gsd-verifier', output_path: '${QUICK_DIR}/${next_num}-VERIFICATION.md' }],
+  resume: { action: 'create-pr', context: { quick_dir: '${QUICK_DIR}', plan_num: ${next_num} } }
+});
+" 2>/dev/null || true
+```
+
+10b. **Publish verification comment (non-blocking, --full only):**
+
+10b. **Publish verification comment (non-blocking, --full only):**
+
+10. **Publish verification comment (non-blocking, --full only):**
+```bash
+VERIFICATION_FILE="${QUICK_DIR}/${next_num}-VERIFICATION.md"
+if [ -f "$VERIFICATION_FILE" ]; then
+  node -e "
+    const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+    const fs = require('fs');
+    const content = fs.readFileSync('${VERIFICATION_FILE}', 'utf-8');
+    ic.postPlanningComment(${ISSUE_NUMBER}, 'verification', content, { phase: ${next_num}, milestone: ${MILESTONE_NUM} })
+      .catch(e => console.error('WARNING: Failed to post verification comment:', e.message));
+  " 2>/dev/null || true
+fi
+```
+
+11. **Post-execution artifact verification (non-blocking):**
 ```bash
 ARTIFACT_CHECK=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify artifacts "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null || echo '{"passed":true}')
 KEYLINK_CHECK=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify key-links "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null || echo '{"passed":true}')
@@ -234,8 +554,13 @@ If any step above fails (executor or verifier agent returns error, summary missi
 
 ```bash
 # On failure — classify and decide whether to retry
+# CRITICALITY-AWARE: check if the failing agent is advisory first.
+# Advisory agent failures are logged and skipped (pipeline continues).
+# Critical agent failures follow the existing retry/dead-letter flow.
+
 FAILURE_CLASS=$(node -e "
 const { classifyFailure, canRetry, incrementRetry, getBackoffMs } = require('./lib/retry.cjs');
+const { isAdvisory } = require('./lib/agent-criticality.cjs');
 const { loadActiveIssue } = require('./lib/state.cjs');
 const fs = require('fs'), path = require('path');
 
@@ -245,29 +570,43 @@ const file = files.find(f => f.startsWith('${ISSUE_NUMBER}-') && f.endsWith('.js
 const filePath = path.join(activeDir, file);
 let issueState = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
 
-// Classify the failure from the error context
-const error = { message: '${EXECUTION_ERROR_MESSAGE}' };
-const result = classifyFailure(error);
-console.error('Failure classified as: ' + result.class + ' — ' + result.reason);
-
-// Persist failure class to state
-issueState.last_failure_class = result.class;
-
-if (result.class === 'transient' && canRetry(issueState)) {
-  const backoff = getBackoffMs(issueState.retry_count || 0);
-  issueState = incrementRetry(issueState);
-  fs.writeFileSync(filePath, JSON.stringify(issueState, null, 2));
-  // Output: backoff ms so shell can sleep
-  console.log('retry:' + backoff + ':' + result.class);
+// Check if the failing agent is advisory
+const failingSpawnPoint = '${FAILING_SPAWN_POINT}';
+if (failingSpawnPoint && isAdvisory(failingSpawnPoint)) {
+  // Advisory agent failure — log warning and continue pipeline
+  console.error('MGW WARNING: Advisory agent \"' + failingSpawnPoint + '\" failed. Continuing pipeline.');
+  console.log('advisory_degraded:' + failingSpawnPoint);
 } else {
-  // Permanent failure or retries exhausted — dead-letter
-  issueState.dead_letter = true;
-  fs.writeFileSync(filePath, JSON.stringify(issueState, null, 2));
-  console.log('dead_letter:' + result.class);
+  // Critical agent failure — classify and apply retry/dead-letter logic
+  const error = { message: '${EXECUTION_ERROR_MESSAGE}' };
+  const result = classifyFailure(error);
+  console.error('Failure classified as: ' + result.class + ' — ' + result.reason);
+
+  // Persist failure class to state
+  issueState.last_failure_class = result.class;
+
+  if (result.class === 'transient' && canRetry(issueState)) {
+    const backoff = getBackoffMs(issueState.retry_count || 0);
+    issueState = incrementRetry(issueState);
+    fs.writeFileSync(filePath, JSON.stringify(issueState, null, 2));
+    // Output: backoff ms so shell can sleep
+    console.log('retry:' + backoff + ':' + result.class);
+  } else {
+    // Permanent failure or retries exhausted — dead-letter
+    issueState.dead_letter = true;
+    fs.writeFileSync(filePath, JSON.stringify(issueState, null, 2));
+    console.log('dead_letter:' + result.class);
+  }
 }
 ")
 
 case "$FAILURE_CLASS" in
+  advisory_degraded:*)
+    DEGRADED_AGENT=$(echo "$FAILURE_CLASS" | cut -d':' -f2)
+    echo "MGW: Advisory agent '${DEGRADED_AGENT}' failed — gracefully degraded, continuing pipeline."
+    # Do NOT set EXECUTION_SUCCEEDED=false — pipeline continues
+    # Skip to next step (advisory output is optional)
+    ;;
   retry:*)
     BACKOFF_MS=$(echo "$FAILURE_CLASS" | cut -d':' -f2)
     BACKOFF_SEC=$(( (BACKOFF_MS + 999) / 1000 ))
@@ -394,6 +733,31 @@ If proceed: apply "mgw:approved" label and continue.
 
    Update pipeline_stage to "planning" (at `${REPO_ROOT}/.mgw/active/`).
 
+**Verify ROADMAP.md was created:**
+```bash
+if [ ! -f ".planning/ROADMAP.md" ]; then
+  echo "MGW ERROR: Roadmapper agent did not produce ROADMAP.md. Cannot proceed with milestone execution."
+  FAIL_TS=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs current-timestamp --raw 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+  gh issue comment ${ISSUE_NUMBER} --body "> **MGW** · \`pipeline-failed\` · ${FAIL_TS}
+> Roadmapper agent did not produce ROADMAP.md. Pipeline cannot continue.
+> Re-run with \`/mgw:run ${ISSUE_NUMBER}\` after investigating." 2>/dev/null || true
+  # Update pipeline_stage to failed (same pattern as post_execution_update dead_letter block)
+  node -e "
+const fs = require('fs'), path = require('path');
+const activeDir = path.join(process.cwd(), '.mgw', 'active');
+const files = fs.readdirSync(activeDir);
+const file = files.find(f => f.startsWith('${ISSUE_NUMBER}-') && f.endsWith('.json'));
+if (file) {
+  const filePath = path.join(activeDir, file);
+  const state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  state.pipeline_stage = 'failed';
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
+}
+" 2>/dev/null || true
+  exit 1
+fi
+```
+
 2. **If resuming with pipeline_stage = "planning" and ROADMAP.md exists:**
    Discover phases from ROADMAP and run the full per-phase GSD lifecycle:
 
@@ -430,7 +794,40 @@ If proceed: apply "mgw:approved" label and continue.
    # Parse PHASE_INIT JSON for: planner_model, checker_model
    ```
 
-   **b. Spawn planner agent (gsd:plan-phase):**
+   **b. Assemble MGW context and spawn planner agent (gsd:plan-phase, with diagnostic capture):**
+
+   Assemble multi-machine context from GitHub issue comments before spawning:
+   ```bash
+   MGW_CONTEXT=$(node -e "
+   const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+   ic.buildGSDPromptContext({
+     milestone: ${MILESTONE_NUM},
+     phase: ${PHASE_NUMBER},
+     issueNumber: ${ISSUE_NUMBER},
+     includeVision: true,
+     includePriorSummaries: true,
+     includeCurrentPlan: false
+   }).then(ctx => process.stdout.write(ctx));
+   " 2>/dev/null || echo "")
+   ```
+
+<!-- mgw:criticality=critical  spawn_point=milestone-planner -->
+   <!-- Critical: phase planning is required — cannot execute without a plan.
+        On failure: retry via milestone retry loop, then dead-letter. -->
+
+**Pre-spawn diagnostic hook (milestone planner):**
+   ```bash
+   DIAG_MS_PLANNER=$(node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   const id = dh.beforeAgentSpawn({
+     agentType: 'gsd-planner',
+     issueNumber: ${ISSUE_NUMBER},
+     prompt: 'Plan phase ${PHASE_NUMBER}: ${PHASE_NAME}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   process.stdout.write(id);
+   " 2>/dev/null || echo "")
+   ```
    ```
    Task(
      prompt="
@@ -441,6 +838,8 @@ If proceed: apply "mgw:approved" label and continue.
    - .planning/STATE.md (If exists -- project state)
    </files_to_read>
 
+   ${MGW_CONTEXT}
+
    You are the GSD planner. Plan phase ${PHASE_NUMBER}: ${PHASE_NAME}.
 
    Read and follow the plan-phase workflow:
@@ -462,6 +861,48 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
+   **Post-spawn diagnostic hook (milestone planner):**
+   ```bash
+   MS_PLANNER_EXIT=$( ls ${phase_dir}/*-PLAN.md 2>/dev/null | wc -l | xargs test 0 -lt && echo "success" || echo "error" )
+   node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   dh.afterAgentSpawn({
+     diagId: '${DIAG_MS_PLANNER}',
+     exitReason: '${MS_PLANNER_EXIT}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   " 2>/dev/null || true
+   ```
+
+   **b1b. Checkpoint: record milestone phase plan completion (atomic write):**
+   ```bash
+   # Checkpoint: record milestone plan completion for this phase.
+   node -e "
+   const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+   updateCheckpoint(${ISSUE_NUMBER}, {
+     pipeline_step: 'plan',
+     step_progress: { gsd_phase: ${PHASE_NUMBER}, plan_path: '${phase_dir}' },
+     last_agent_output: '${phase_dir}',
+     step_history: [{ step: 'plan', completed_at: new Date().toISOString(), agent_type: 'gsd-planner', output_path: '${phase_dir}' }],
+     resume: { action: 'execute-phase', context: { phase_number: ${PHASE_NUMBER}, phase_dir: '${phase_dir}' } }
+   });
+   " 2>/dev/null || true
+   ```
+
+   **b2. Publish plan comment (non-blocking):**
+   ```bash
+   PLAN_FILES=$(ls ${phase_dir}/*-PLAN.md 2>/dev/null)
+   for PLAN_FILE in $PLAN_FILES; do
+     node -e "
+       const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+       const fs = require('fs');
+       const content = fs.readFileSync('${PLAN_FILE}', 'utf-8');
+       ic.postPlanningComment(${ISSUE_NUMBER}, 'plan', content, { phase: ${PHASE_NUMBER}, milestone: ${MILESTONE_NUM} })
+         .catch(e => console.error('WARNING: Failed to post plan comment:', e.message));
+     " 2>/dev/null || true
+   done
+   ```
+
    **c. Verify plans exist:**
    ```bash
    PLAN_COUNT=$(ls ${phase_dir}/*-PLAN.md 2>/dev/null | wc -l)
@@ -473,11 +914,30 @@ If proceed: apply "mgw:approved" label and continue.
    fi
    ```
 
-   **d. Init execute-phase and spawn executor agent (gsd:execute-phase):**
+   **d. Init execute-phase and spawn executor agent (gsd:execute-phase, with diagnostic capture):**
    ```bash
    EXEC_INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init execute-phase "${PHASE_NUMBER}")
    # Parse EXEC_INIT JSON for: executor_model, verifier_model, phase_dir, plans, incomplete_plans, plan_count
    ```
+
+<!-- mgw:criticality=critical  spawn_point=milestone-executor -->
+   <!-- Critical: phase execution produces the code changes. Without it,
+        there is nothing to commit or PR. On failure: retry via milestone
+        retry loop, then dead-letter. -->
+
+**Pre-spawn diagnostic hook (milestone executor):**
+   ```bash
+   DIAG_MS_EXECUTOR=$(node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   const id = dh.beforeAgentSpawn({
+     agentType: 'gsd-executor',
+     issueNumber: ${ISSUE_NUMBER},
+     prompt: 'Execute phase ${PHASE_NUMBER}: ${PHASE_NAME}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   process.stdout.write(id);
+   " 2>/dev/null || echo "")
+   ```
    ```
    Task(
      prompt="
@@ -508,7 +968,82 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
-   **e. Spawn verifier agent (gsd:verify-phase):**
+   **Post-spawn diagnostic hook (milestone executor):**
+   ```bash
+   MS_EXECUTOR_EXIT=$( ls ${phase_dir}/*-SUMMARY.md 2>/dev/null | wc -l | xargs test 0 -lt && echo "success" || echo "error" )
+   node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   dh.afterAgentSpawn({
+     diagId: '${DIAG_MS_EXECUTOR}',
+     exitReason: '${MS_EXECUTOR_EXIT}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   " 2>/dev/null || true
+   ```
+
+   **d1b. Checkpoint: record milestone phase execution completion (atomic write):**
+   ```bash
+   # Checkpoint: record milestone execution completion for this phase.
+   node -e "
+   const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+   updateCheckpoint(${ISSUE_NUMBER}, {
+     pipeline_step: 'execute',
+     step_progress: { gsd_phase: ${PHASE_NUMBER} },
+     last_agent_output: '${phase_dir}',
+     step_history: [{ step: 'execute', completed_at: new Date().toISOString(), agent_type: 'gsd-executor', output_path: '${phase_dir}' }],
+     resume: { action: 'verify-phase', context: { phase_number: ${PHASE_NUMBER}, phase_dir: '${phase_dir}' } }
+   });
+   " 2>/dev/null || true
+   ```
+
+   **d2. Publish summary comment (non-blocking):**
+   ```bash
+   SUMMARY_FILES=$(ls ${phase_dir}/*-SUMMARY.md 2>/dev/null)
+   for SUMMARY_FILE in $SUMMARY_FILES; do
+     node -e "
+       const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+       const fs = require('fs');
+       const content = fs.readFileSync('${SUMMARY_FILE}', 'utf-8');
+       ic.postPlanningComment(${ISSUE_NUMBER}, 'summary', content, { phase: ${PHASE_NUMBER}, milestone: ${MILESTONE_NUM} })
+         .catch(e => console.error('WARNING: Failed to post summary comment:', e.message));
+     " 2>/dev/null || true
+   done
+   ```
+
+**e. Spawn verifier agent (gsd:verify-phase):**
+
+   <!-- mgw:criticality=advisory  spawn_point=milestone-verifier -->
+   <!-- Advisory: phase verification is quality assurance after execution
+        completes. The code changes and commits already exist. If verification
+        fails, log a warning and proceed with a note that verification was
+        skipped for this phase.
+
+        Graceful degradation pattern:
+        ```
+        VERIFY_RESULT=$(wrapAdvisoryAgent(Task(...), 'milestone-verifier', {
+          issueNumber: ISSUE_NUMBER,
+          fallback: null
+        }))
+        # If fallback returned, create minimal VERIFICATION.md:
+        #   "## VERIFICATION SKIPPED\nVerifier agent unavailable for phase ${PHASE_NUMBER}."
+        ```
+   -->
+
+**e. Spawn verifier agent (gsd:verify-phase, with diagnostic capture):**
+
+   **Pre-spawn diagnostic hook (milestone verifier):**
+   ```bash
+   DIAG_MS_VERIFIER=$(node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   const id = dh.beforeAgentSpawn({
+     agentType: 'gsd-verifier',
+     issueNumber: ${ISSUE_NUMBER},
+     prompt: 'Verify phase ${PHASE_NUMBER}: ${PHASE_NAME}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   process.stdout.write(id);
+   " 2>/dev/null || echo "")
+   ```
    ```
    Task(
      prompt="
@@ -536,6 +1071,48 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
+   **Post-spawn diagnostic hook (milestone verifier):**
+   ```bash
+   MS_VERIFIER_EXIT=$( ls ${phase_dir}/*-VERIFICATION.md 2>/dev/null | wc -l | xargs test 0 -lt && echo "success" || echo "error" )
+   node -e "
+   const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+   dh.afterAgentSpawn({
+     diagId: '${DIAG_MS_VERIFIER}',
+     exitReason: '${MS_VERIFIER_EXIT}',
+     repoRoot: '${REPO_ROOT}'
+   });
+   " 2>/dev/null || true
+   ```
+
+   **e1b. Checkpoint: record milestone phase verification completion (atomic write):**
+   ```bash
+   # Checkpoint: record milestone verification completion for this phase.
+   node -e "
+   const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+   updateCheckpoint(${ISSUE_NUMBER}, {
+     pipeline_step: 'verify',
+     step_progress: { gsd_phase: ${PHASE_NUMBER}, verification_complete: true },
+     last_agent_output: '${phase_dir}',
+     step_history: [{ step: 'verify', completed_at: new Date().toISOString(), agent_type: 'gsd-verifier', output_path: '${phase_dir}' }],
+     resume: { action: 'next-phase', context: { completed_phase: ${PHASE_NUMBER}, phase_dir: '${phase_dir}' } }
+   });
+   " 2>/dev/null || true
+   ```
+
+   **e2. Publish verification comment (non-blocking):**
+   ```bash
+   VERIFICATION_FILES=$(ls ${phase_dir}/*-VERIFICATION.md 2>/dev/null)
+   for VERIFICATION_FILE in $VERIFICATION_FILES; do
+     node -e "
+       const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+       const fs = require('fs');
+       const content = fs.readFileSync('${VERIFICATION_FILE}', 'utf-8');
+       ic.postPlanningComment(${ISSUE_NUMBER}, 'verification', content, { phase: ${PHASE_NUMBER}, milestone: ${MILESTONE_NUM} })
+         .catch(e => console.error('WARNING: Failed to post verification comment:', e.message));
+     " 2>/dev/null || true
+   done
+   ```
+
    **f. Post phase-complete comment directly (no sub-agent):**
    ```bash
    PHASE_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")