@snipcodeit/mgw 0.3.0 → 0.6.0

package/commands/run/pr-create.md

@@ -22,6 +22,29 @@ CROSS_REFS=$(cat ${REPO_ROOT}/.mgw/cross-refs.json 2>/dev/null)
 # Progress table for PR details section
 PROGRESS_TABLE=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs progress table --raw 2>/dev/null || echo "")
 
+**Verify execution evidence exists before creating PR:**
+```bash
+SUMMARY_COUNT=$(ls ${gsd_artifacts_path}/*SUMMARY* 2>/dev/null | wc -l)
+if [ "$SUMMARY_COUNT" -eq 0 ]; then
+  echo "MGW ERROR: No SUMMARY files found at ${gsd_artifacts_path}. Cannot create PR without execution evidence."
+  echo "This usually means the executor agent failed silently. Check the execution logs."
+  # Update pipeline_stage to "failed"
+  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
+```
+
 # Milestone/phase context for PR body
 MILESTONE_TITLE=""
 PHASE_INFO=""
@@ -71,10 +94,37 @@ p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
 print(p.get('project', {}).get('project_board', {}).get('url', ''))
 " 2>/dev/null || echo "")
 fi
+
+# Phase Context from GitHub issue comments (multi-developer context sharing)
+PHASE_CONTEXT=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.assembleIssueContext(${ISSUE_NUMBER})
+  .then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
 ```
 
 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="
@@ -122,6 +172,10 @@ ${COMMITS}
 ${CROSS_REFS}
 </cross_refs>
 
+<phase_context>
+${PHASE_CONTEXT}
+</phase_context>
+
 <instructions>
 1. Build PR title: short, prefixed with fix:/feat:/refactor: based on issue labels. Under 70 characters.
 
@@ -141,6 +195,14 @@ Closes #${ISSUE_NUMBER}
 ## Changes
 - File-level changes grouped by module (use key_files from summary_structured)
 
+## Phase Context
+<details>
+<summary>Planning & execution context from GitHub issue comments</summary>
+
+${PHASE_CONTEXT}
+</details>
+(Skip if PHASE_CONTEXT is empty)
+
 ## Test Plan
 - Verification checklist from VERIFICATION artifact
 
@@ -165,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"

package/commands/run/triage.md

@@ -38,7 +38,7 @@ If no state file exists → issue not triaged yet. Run triage inline:
   - Execute the mgw:issue triage flow (steps from issue.md) inline.
   - After triage, reload state file.
 
-If state file exists → load it. **Run migrateProjectState() to ensure retry fields exist:**
+If state file exists → load it. **Run migrateProjectState() to ensure retry and checkpoint fields exist:**
 ```bash
 node -e "
 const { migrateProjectState } = require('./lib/state.cjs');
@@ -46,6 +46,161 @@ migrateProjectState();
 " 2>/dev/null || true
 ```
 
+**Checkpoint detection — check for resumable progress before stage routing:**
+
+After loading state and running migration, detect whether a prior pipeline run left
+a checkpoint with meaningful progress (beyond triage). If found, present the user
+with Resume/Fresh/Skip options before proceeding.
+
+```bash
+# Detect checkpoint with progress beyond triage
+CHECKPOINT_DATA=$(node -e "
+const { detectCheckpoint, resumeFromCheckpoint } = require('./lib/state.cjs');
+const cp = detectCheckpoint(${ISSUE_NUMBER});
+if (!cp) {
+  console.log('none');
+} else {
+  const resume = resumeFromCheckpoint(${ISSUE_NUMBER});
+  console.log(JSON.stringify(resume));
+}
+" 2>/dev/null || echo "none")
+```
+
+If checkpoint is found (`CHECKPOINT_DATA !== "none"`):
+
+Parse the checkpoint data and display to the user:
+```bash
+CHECKPOINT_STEP=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.checkpoint.pipeline_step);
+")
+RESUME_ACTION=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.resumeAction);
+")
+RESUME_STAGE=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.resumeStage);
+")
+COMPLETED_STEPS=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.completedSteps.join(', '));
+")
+ARTIFACTS_COUNT=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.checkpoint.artifacts.length);
+")
+STARTED_AT=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.checkpoint.started_at || 'unknown');
+")
+UPDATED_AT=$(echo "$CHECKPOINT_DATA" | node -e "
+const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+console.log(d.checkpoint.updated_at || 'unknown');
+")
+```
+
+Display checkpoint state and prompt user:
+```
+AskUserQuestion(
+  header: "Checkpoint Detected for #${ISSUE_NUMBER}",
+  question: "A prior pipeline run left progress at step '${CHECKPOINT_STEP}'.
+
+| | |
+|---|---|
+| **Last step** | ${CHECKPOINT_STEP} |
+| **Completed steps** | ${COMPLETED_STEPS} |
+| **Artifacts** | ${ARTIFACTS_COUNT} file(s) |
+| **Resume action** | ${RESUME_ACTION} → stage: ${RESUME_STAGE} |
+| **Started** | ${STARTED_AT} |
+| **Last updated** | ${UPDATED_AT} |
+
+How would you like to proceed?",
+  options: [
+    { label: "Resume", description: "Resume from checkpoint — skip completed steps (${COMPLETED_STEPS}), jump to ${RESUME_STAGE}" },
+    { label: "Fresh", description: "Discard checkpoint and re-run pipeline from scratch" },
+    { label: "Skip", description: "Skip this issue entirely" }
+  ]
+)
+```
+
+Handle user choice:
+
+| Choice | Action |
+|--------|--------|
+| **Resume** | Load checkpoint context. Set `pipeline_stage` in state to `${RESUME_STAGE}`. Log: "MGW: Resuming #${ISSUE_NUMBER} from checkpoint (step: ${CHECKPOINT_STEP}, action: ${RESUME_ACTION})." Skip triage/worktree stages that already completed and jump directly to the resume stage in the pipeline. The `resume.context` object carries step-specific data (e.g., `quick_dir`, `plan_num`, `phase_number`) needed by the target stage. |
+| **Fresh** | Clear checkpoint via `clearCheckpoint()`. Reset `pipeline_stage` to `"triaged"`. Log: "MGW: Checkpoint cleared for #${ISSUE_NUMBER}. Starting fresh." Continue with normal pipeline flow. |
+| **Skip** | Log: "MGW: Skipping #${ISSUE_NUMBER} per user request." STOP pipeline. |
+
+```bash
+case "$USER_CHOICE" in
+  Resume)
+    # Load resume context and jump to the appropriate stage
+    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'));
+    const filePath = path.join(activeDir, file);
+    const state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    // The pipeline_stage already reflects prior progress — do not overwrite
+    // unless the resume target is more advanced than current stage
+    console.log('Resuming from checkpoint: ' + JSON.stringify(state.checkpoint.resume));
+    " 2>/dev/null || true
+    # Set RESUME_MODE=true — downstream stages check this flag to skip completed work
+    RESUME_MODE=true
+    RESUME_CONTEXT="${CHECKPOINT_DATA}"
+    ;;
+  Fresh)
+    node -e "
+    const { clearCheckpoint } = require('./lib/state.cjs');
+    clearCheckpoint(${ISSUE_NUMBER});
+    console.log('Checkpoint cleared for #${ISSUE_NUMBER}');
+    " 2>/dev/null || true
+    # Reset pipeline_stage to triaged for fresh start
+    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'));
+    const filePath = path.join(activeDir, file);
+    const state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    state.pipeline_stage = 'triaged';
+    fs.writeFileSync(filePath, JSON.stringify(state, null, 2));
+    " 2>/dev/null || true
+    RESUME_MODE=false
+    ;;
+  Skip)
+    echo "MGW: Skipping #${ISSUE_NUMBER} per user request."
+    exit 0
+    ;;
+esac
+```
+
+If no checkpoint found (or checkpoint is at triage step only), continue with
+normal pipeline stage routing below.
+
+**Initialize checkpoint** when pipeline first transitions past triage:
+```bash
+# Checkpoint initialization — called once when pipeline execution begins.
+# Sets pipeline_step to "triage" with route selection progress.
+# Subsequent stages update the checkpoint via updateCheckpoint().
+# All checkpoint writes are atomic (write to .tmp then rename).
+node -e "
+const { updateCheckpoint } = require('./lib/state.cjs');
+updateCheckpoint(${ISSUE_NUMBER}, {
+  pipeline_step: 'triage',
+  step_progress: {
+    comment_check_done: true,
+    route_selected: '${GSD_ROUTE}'
+  },
+  resume: {
+    action: 'begin-execution',
+    context: { gsd_route: '${GSD_ROUTE}', branch: '${BRANCH_NAME}' }
+  }
+});
+" 2>/dev/null || true
+```
 Check pipeline_stage:
   - "triaged" → proceed to GSD execution
   - "planning" / "executing" → resume from where we left off
@@ -359,7 +514,37 @@ NEW_COMMENTS=$(gh issue view $ISSUE_NUMBER --json comments \
   --jq "[.comments[-${NEW_COUNT}:]] | .[] | {author: .author.login, body: .body, createdAt: .createdAt}" 2>/dev/null)
 ```
 
-2. **Spawn classification agent:**
+2. **Spawn classification agent (with diagnostic capture):**
+
+<!-- mgw:criticality=advisory  spawn_point=comment-classifier -->
+<!-- Advisory: comment classification failure does not block the pipeline.
+     If this agent fails, log a warning and treat all new comments as
+     informational (safe default — pipeline continues with stale data).
+
+     Graceful degradation pattern:
+     ```
+     CLASSIFICATION_RESULT=$(wrapAdvisoryAgent(Task(...), 'comment-classifier', {
+       issueNumber: ISSUE_NUMBER,
+       fallback: '{"classification":"informational","reasoning":"comment classifier unavailable","new_requirements":[],"blocking_reason":""}'
+     }))
+     ```
+-->
+
+**Pre-spawn diagnostic hook:**
+```bash
+CLASSIFIER_PROMPT="<full classifier prompt assembled above>"
+DIAG_CLASSIFIER=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: 'general-purpose',
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: process.argv[1],
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" "$CLASSIFIER_PROMPT" 2>/dev/null || echo "")
+```
+
 ```
 Task(
   prompt="
@@ -414,6 +599,18 @@ Return ONLY valid JSON:
 )
 ```
 
+**Post-spawn diagnostic hook:**
+```bash
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_CLASSIFIER}',
+  exitReason: '${CLASSIFICATION_RESULT ? \"success\" : \"error\"}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
 3. **React based on classification:**
 
 | Classification | Action |

package/commands/run/worktree.md

@@ -12,6 +12,47 @@ BRANCH_NAME="issue/${ISSUE_NUMBER}-${slug}"
 WORKTREE_DIR="${REPO_ROOT}/.worktrees/${BRANCH_NAME}"
 ```
 
+**Check for active work on this issue by another developer:**
+```bash
+# Check 1: Remote branch already exists (another machine pushed work)
+REMOTE_BRANCHES=$(git ls-remote --heads origin "issue/${ISSUE_NUMBER}-*" 2>/dev/null | awk '{print $2}' | sed 's|refs/heads/||')
+if [ -n "$REMOTE_BRANCHES" ]; then
+  echo "WARNING: Remote branch(es) already exist for issue #${ISSUE_NUMBER}:"
+  echo "$REMOTE_BRANCHES" | sed 's/^/  /'
+  echo ""
+  AskUserQuestion(
+    header: "Active Work Detected",
+    question: "Remote branch exists for #${ISSUE_NUMBER}. Another developer may be working on this. Proceed anyway?",
+    options: [
+      { label: "Proceed", description: "Create a new worktree anyway (may cause conflicts)" },
+      { label: "Abort", description: "Stop pipeline — coordinate with the other developer first" }
+    ]
+  )
+  if [ "$USER_CHOICE" = "Abort" ]; then
+    echo "Pipeline aborted — coordinate with the developer who owns the existing branch."
+    exit 1
+  fi
+fi
+
+# Check 2: Open PR already exists for this issue
+EXISTING_PR=$(gh pr list --search "issue/${ISSUE_NUMBER}-" --state open --json number,headRefName --jq '.[0].number' 2>/dev/null || echo "")
+if [ -n "$EXISTING_PR" ]; then
+  echo "WARNING: Open PR #${EXISTING_PR} already exists for issue #${ISSUE_NUMBER}."
+  echo "Creating a new worktree will produce a conflicting PR."
+  AskUserQuestion(
+    header: "Open PR Exists",
+    question: "PR #${EXISTING_PR} is already open for this issue. Proceed with a new worktree?",
+    options: [
+      { label: "Proceed", description: "Create new worktree anyway" },
+      { label: "Abort", description: "Stop — review the existing PR first" }
+    ]
+  )
+  if [ "$USER_CHOICE" = "Abort" ]; then
+    exit 1
+  fi
+fi
+```
+
 Ensure .worktrees/ is gitignored:
 ```bash
 mkdir -p "$(dirname "${WORKTREE_DIR}")"

package/commands/sync.md

@@ -33,6 +33,18 @@ Run periodically or when starting a new session to get a clean view.
 
 <process>
 
+<step name="parse_arguments">
+**Parse sync flags:**
+```bash
+FULL_SYNC=false
+for arg in "$@"; do
+  case "$arg" in
+    --full) FULL_SYNC=true ;;
+  esac
+done
+```
+</step>
+
 <step name="pull_board_state">
 **Pull board state to reconstruct missing local .mgw/active/ files.**
 
@@ -348,6 +360,63 @@ rebuilt from board data — triage results and GSD artifacts will need to be re-
 issue advances to `planning` or beyond.
 </step>
 
+<step name="rebuild_from_committed">
+**Rebuild project context from committed planning files (--full only):**
+
+Only runs when `--full` flag is passed. This is the multi-machine context rebuild:
+after `git pull`, a developer runs `mgw:sync --full` to reconstruct full project
+context from committed `.planning/` files and the board.
+
+```bash
+if [ "$FULL_SYNC" = "true" ]; then
+  echo "Full sync: rebuilding project context from committed planning files..."
+
+  # 1. Check for committed ROADMAP.md
+  if [ -f ".planning/ROADMAP.md" ]; then
+    echo "  Found committed ROADMAP.md"
+    ROADMAP_ANALYSIS=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap analyze 2>/dev/null || echo '{}')
+    PHASE_COUNT=$(echo "$ROADMAP_ANALYSIS" | python3 -c "import json,sys; print(len(json.load(sys.stdin).get('phases',[])))" 2>/dev/null || echo "0")
+    echo "  ROADMAP.md contains ${PHASE_COUNT} phases"
+  else
+    echo "  No committed ROADMAP.md found — planning context unavailable"
+    echo "  (This is expected if the project hasn't run a milestone yet)"
+  fi
+
+  # 2. Scan for committed phase artifacts
+  COMMITTED_PLANS=$(find .planning -name '*-PLAN.md' -not -path '.planning/quick/*' 2>/dev/null | wc -l)
+  COMMITTED_SUMMARIES=$(find .planning -name '*-SUMMARY.md' -not -path '.planning/quick/*' 2>/dev/null | wc -l)
+  echo "  Committed phase plans: ${COMMITTED_PLANS}"
+  echo "  Committed phase summaries: ${COMMITTED_SUMMARIES}"
+
+  # 3. If project.json is missing but board + ROADMAP exist, offer to reconstruct
+  if [ ! -f "${MGW_DIR}/project.json" ] && [ -f ".planning/ROADMAP.md" ] && [ -n "$BOARD_NODE_ID" ]; then
+    echo ""
+    echo "  project.json is missing but ROADMAP.md and board are available."
+    echo "  Run /mgw:project to reconstruct full project state."
+    echo "  (Board state has been pulled — active issues are available)"
+  fi
+
+  # 4. Rebuild context cache from GitHub issue comments
+  echo "  Rebuilding context cache from GitHub issue comments..."
+  node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.rebuildContextCache()
+  .then(stats => console.log('  Cached summaries for', stats.issueCount, 'issues across', stats.milestoneCount, 'milestones'))
+  .catch(e => console.error('  Cache rebuild failed:', e.message));
+" 2>/dev/null || echo "  Context cache rebuild skipped (issue-context module not available)"
+
+  # 5. Refresh Project README with current milestone progress
+  echo "  Refreshing Project README..."
+  node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.updateProjectReadme()
+  .then(ok => console.log(ok ? '  Project README updated' : '  Project README skipped (no board configured)'))
+  .catch(() => console.log('  Project README refresh skipped'));
+" 2>/dev/null || true
+fi
+```
+</step>
+
 <step name="scan_active">
 **Scan all active issue states:**
 

package/commands/workflows/gsd.md

@@ -355,6 +355,77 @@ The agent is read-only (general-purpose, no code execution). It reads project st
 and codebase to classify, then MGW presents the result and offers follow-up actions
 (file new issue, post comment on related issue, etc.).
 
+## Diagnostic Capture Hooks
+
+Every Task() spawn in the mgw:run pipeline SHOULD be instrumented with diagnostic
+capture hooks using `lib/diagnostic-hooks.cjs`. This provides per-agent telemetry
+(timing, prompt hash, exit reason, failure classification) without blocking pipeline
+execution.
+
+**Required modules:**
+- `lib/diagnostic-hooks.cjs` — Before/after hooks for Task() spawns
+- `lib/agent-diagnostics.cjs` — Underlying diagnostic logger (writes to `.mgw/diagnostics/`)
+
+**Pattern — wrap every Task() spawn:**
+
+```bash
+# 1. Before spawning: record start time and hash prompt
+DIAG_ID=$(node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+const id = dh.beforeAgentSpawn({
+  agentType: '${AGENT_TYPE}',       # gsd-planner, gsd-executor, etc.
+  issueNumber: ${ISSUE_NUMBER},
+  prompt: '${PROMPT_SUMMARY}',      # short description, not full prompt
+  repoRoot: '${REPO_ROOT}'
+});
+process.stdout.write(id);
+" 2>/dev/null || echo "")
+
+# 2. Spawn Task() agent (unchanged)
+Task(
+  prompt="...",
+  subagent_type="${AGENT_TYPE}",
+  description="..."
+)
+
+# 3. After agent completes: record exit reason and write diagnostic entry
+EXIT_REASON=$( <check artifact exists> && echo "success" || echo "error" )
+node -e "
+const dh = require('${REPO_ROOT}/lib/diagnostic-hooks.cjs');
+dh.afterAgentSpawn({
+  diagId: '${DIAG_ID}',
+  exitReason: '${EXIT_REASON}',
+  repoRoot: '${REPO_ROOT}'
+});
+" 2>/dev/null || true
+```
+
+**Key design principles:**
+- **Non-blocking:** All hook calls are wrapped in `2>/dev/null || true` (bash) or
+  try/catch (JS). If diagnostic capture fails, pipeline continues normally.
+- **No prompt storage:** Only a hash of the prompt is stored, not the full text.
+  Use `shortHash()` from `agent-diagnostics.cjs` for longer prompts.
+- **Exit reason detection:** Use artifact existence checks (e.g., `PLAN.md` exists
+  means planner succeeded) rather than relying on Task() return values.
+- **Graceful degradation:** If `agent-diagnostics.cjs` is not available (dependency
+  PR not merged), `diagnostic-hooks.cjs` logs a warning and returns empty handles.
+
+**Diagnostic entries are written to:** `.mgw/diagnostics/<issueNumber>-<timestamp>.json`
+
+**Instrumented agent spawns in mgw:run:**
+
+| Agent | File | Step |
+|-------|------|------|
+| Comment classifier | `run/triage.md` | preflight_comment_check |
+| Planner (quick) | `run/execute.md` | execute_gsd_quick step 3 |
+| Plan-checker (quick) | `run/execute.md` | execute_gsd_quick step 6 |
+| Executor (quick) | `run/execute.md` | execute_gsd_quick step 7 |
+| Verifier (quick) | `run/execute.md` | execute_gsd_quick step 9 |
+| Planner (milestone) | `run/execute.md` | execute_gsd_milestone step b |
+| Executor (milestone) | `run/execute.md` | execute_gsd_milestone step d |
+| Verifier (milestone) | `run/execute.md` | execute_gsd_milestone step e |
+| PR creator | `run/pr-create.md` | create_pr |
+
 ## Anti-Patterns
 
 - **NEVER** use Skill invocation from within a Task() agent — Skills don't resolve inside subagents