@snipcodeit/mgw 0.4.0 → 0.6.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@snipcodeit/mgw)](https://www.npmjs.com/package/@snipcodeit/mgw)
 [![CI](https://github.com/snipcodeit/mgw/actions/workflows/ci.yml/badge.svg)](https://github.com/snipcodeit/mgw/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-70%25-brightgreen)](./coverage/lcov-report/index.html)
 [![npm downloads](https://img.shields.io/npm/dm/@snipcodeit/mgw)](https://www.npmjs.com/package/@snipcodeit/mgw)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![node](https://img.shields.io/node/v/@snipcodeit/mgw)](https://nodejs.org)

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,7 +67,7 @@ QUICK_DIR=".planning/quick/${next_num}-${slug}"
 mkdir -p "$QUICK_DIR"
 ```
 
-3. **Assemble MGW context and 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
@@ -77,6 +84,23 @@ ic.buildGSDPromptContext({
 " 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="
@@ -127,6 +151,53 @@ Return: ## PLANNING COMPLETE with plan path
 )
 ```
 
+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"
@@ -150,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="
@@ -191,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="
@@ -219,6 +354,52 @@ Execute quick task ${next_num}.
 )
 ```
 
+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"
@@ -240,6 +421,39 @@ VERIFY_RESULT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs verify-summary "$
 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="
@@ -260,6 +474,52 @@ Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}
 )
 ```
 
+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"
@@ -294,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');
 
@@ -305,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 ))
@@ -515,7 +794,7 @@ fi
    # Parse PHASE_INIT JSON for: planner_model, checker_model
    ```
 
-   **b. Assemble MGW context and 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
@@ -532,6 +811,23 @@ fi
    " 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="
@@ -565,6 +861,34 @@ fi
    )
    ```
 
+   **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)
@@ -590,11 +914,30 @@ fi
    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="
@@ -625,6 +968,34 @@ fi
    )
    ```
 
+   **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)
@@ -639,7 +1010,40 @@ fi
    done
    ```
 
-   **e. Spawn verifier agent (gsd:verify-phase):**
+**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="
@@ -667,6 +1071,34 @@ fi
    )
    ```
 
+   **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)

package/commands/run/pr-create.md

@@ -105,6 +105,26 @@ ic.assembleIssueContext(${ISSUE_NUMBER})
 
 Read issue state for context.
 
+<!-- mgw:criticality=critical  spawn_point=pr-creator -->
+<!-- Critical: PR creation is the pipeline's final output. Without it,
+     the entire pipeline run produces no deliverable. On failure: the
+     pipeline marks the issue as failed (no retry — PR creation errors
+     are typically permanent: branch conflicts, permissions, etc.). -->
+
+**Pre-spawn diagnostic hook (PR creator):**
+```bash
+DIAG_PR_CREATOR=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'general-purpose',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: 'Create PR for #${ISSUE_NUMBER}',
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+```
+
 ```
 Task(
   prompt="
@@ -207,8 +227,34 @@ ${PROGRESS_TABLE}
 )
 ```
 
+**Post-spawn diagnostic hook (PR creator):**
+```bash
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_PR_CREATOR}',
+  exitReason: '${PR_NUMBER ? \"success\" : \"error\"}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
 Parse PR number and URL from agent response.
 
+**Checkpoint: record PR creation (atomic write):**
+```bash
+# Checkpoint: record PR creation — final checkpoint before pipeline completion.
+node -e "
+const { updateCheckpoint } = require('${REPO_ROOT}/lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'pr',
+  step_progress: { branch_pushed: true, pr_number: ${PR_NUMBER}, pr_url: '${PR_URL}' },
+  step_history: [{ step: 'pr', completed_at: new Date().toISOString(), agent_type: 'general-purpose', output_path: '${PR_URL}' }],
+  resume: { action: 'cleanup', context: { pr_number: ${PR_NUMBER}, pr_url: '${PR_URL}' } }
+});
+" 2>/dev/null || true
+```
+
 Update state (at `${REPO_ROOT}/.mgw/active/`):
 - linked_pr = PR number
 - pipeline_stage = "pr-created"