@snipcodeit/mgw 0.3.0 → 0.4.0

package/commands/handoff.md

@@ -0,0 +1,169 @@
+---
+name: mgw:handoff
+description: Generate onboarding context for a developer joining the project mid-milestone
+argument-hint: "<developer-name>"
+allowed-tools:
+  - Bash
+  - Read
+  - Task
+---
+
+<objective>
+Produce a structured handoff document for a developer joining an MGW project. Assembles
+current project state, milestone progress, active issues, and recent decisions from
+GitHub issue comments into a single briefing.
+
+This command is read-only. It does not modify any state.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+</execution_context>
+
+<process>
+
+<step name="validate_input">
+**Validate developer name provided:**
+
+Parse $ARGUMENTS for a name. If missing, use "new developer" as default.
+</step>
+
+<step name="gather_state">
+**Gather project state:**
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+MGW_DIR="${REPO_ROOT}/.mgw"
+
+# Project info
+PROJECT_NAME=$(echo "$REPO" | cut -d'/' -f2)
+
+# Active milestone
+MILESTONE_INFO=""
+if [ -f "${MGW_DIR}/project.json" ]; then
+  MILESTONE_INFO=$(python3 -c "
+import json
+p = json.load(open('${MGW_DIR}/project.json'))
+ms = p.get('milestones', [])
+active = [m for m in ms if m.get('gsd_state') == 'active']
+if active:
+    m = active[0]
+    total = len(m.get('issues', []))
+    done = len([i for i in m['issues'] if i.get('pipeline_stage') == 'done'])
+    print(f\"{m['name']} — {done}/{total} issues complete\")
+else:
+    print('No active milestone')
+" 2>/dev/null || echo "Unknown")
+fi
+
+# Active issues
+ACTIVE_ISSUES=$(ls ${MGW_DIR}/active/*.json 2>/dev/null | wc -l)
+
+# Recent PRs
+RECENT_PRS=$(gh pr list --limit 5 --json number,title,state --jq '.[] | "#\(.number) \(.title) [\(.state)]"' 2>/dev/null || echo "None")
+```
+</step>
+
+<step name="assemble_context">
+**Assemble project context from GitHub:**
+
+```bash
+# Vision/project description
+VISION=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.buildGSDPromptContext({ includeVision: true })
+  .then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
+
+# Open milestones with issue counts
+MILESTONES=$(gh api repos/${REPO}/milestones --jq '.[] | "- \(.title): \(.open_issues) open, \(.closed_issues) closed"' 2>/dev/null || echo "No milestones")
+```
+</step>
+
+<step name="generate_handoff">
+**Generate handoff briefing:**
+
+```
+Task(
+  prompt="
+Generate a developer onboarding briefing for ${DEVELOPER_NAME} joining project ${PROJECT_NAME}.
+
+<project_context>
+Repository: ${REPO}
+Active Milestone: ${MILESTONE_INFO}
+Active Issues in Pipeline: ${ACTIVE_ISSUES}
+Recent PRs:
+${RECENT_PRS}
+
+Open Milestones:
+${MILESTONES}
+</project_context>
+
+<vision_context>
+${VISION}
+</vision_context>
+
+<instructions>
+Create a structured handoff document with these sections:
+
+## Project Overview
+- What the project is and its current state
+- Key architectural decisions (from vision context)
+
+## Current Milestone
+- What's being built now
+- Progress status
+- Key deliverables remaining
+
+## Getting Started
+- How to set up the development environment
+- Key commands: /mgw:status, /mgw:context, /mgw:next, /mgw:issue
+- How context sharing works (structured comments on GitHub issues)
+
+## Active Work
+- Issues currently in the pipeline
+- Recent PRs to review
+
+## Key Conventions
+- How MGW orchestrates work (issues → triage → plan → execute → PR)
+- How to read structured comments (<!-- mgw:type=... --> headers)
+- How to use /mgw:context <issue> to see what agents see
+
+Keep it concise and actionable. This is a working document, not documentation.
+</instructions>
+",
+  subagent_type="general-purpose",
+  description="Generate handoff for ${DEVELOPER_NAME}"
+)
+```
+</step>
+
+<step name="display">
+**Display handoff briefing:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► HANDOFF BRIEFING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${HANDOFF_DOCUMENT}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tip: Share this output or post it as a GitHub Discussion.
+  → /mgw:context <issue>  — See context for a specific issue
+  → /mgw:status           — Current project dashboard
+  → /mgw:next             — Find next unblocked issue
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Developer name parsed (or defaulted)
+- [ ] Project state gathered from .mgw/ and GitHub
+- [ ] Vision context assembled via buildGSDPromptContext()
+- [ ] Handoff document generated by task agent
+- [ ] Briefing displayed to user
+- [ ] No state modified
+</success_criteria>

package/commands/issue.md

@@ -113,6 +113,48 @@ Gather GSD project history for context (if available):
 HISTORY=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs history-digest 2>/dev/null || echo "")
 ```
 
+**Gather milestone context for top-down triage (if available):**
+
+Primary source: GitHub issue comments (works on any machine):
+```bash
+MILESTONE_CONTEXT=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.safeContext({ issueNumber: ${ISSUE_NUMBER}, includeVision: true, includePriorSummaries: true })
+  .then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
+```
+
+Fallback: local files (backward compat for single-machine workflows):
+```bash
+if [ -z "$MILESTONE_CONTEXT" ] && [ -f "${REPO_ROOT}/.mgw/project.json" ]; then
+  MILESTONE_CONTEXT=$(python3 -c "
+import json
+try:
+    p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
+    for m in p.get('milestones', []):
+        for i in m.get('issues', []):
+            if i.get('github_number') == ${ISSUE_NUMBER}:
+                parts = []
+                parts.append(f\"Milestone: {m['name']}\")
+                parts.append(f\"Phase {i['phase_number']}: {i['phase_name']}\")
+                parts.append(f\"GSD Route: {i.get('gsd_route', 'unknown')}\")
+                completed = [x for x in m['issues'] if x.get('pipeline_stage') == 'done']
+                if completed:
+                    parts.append(f\"Completed in milestone: {len(completed)}/{len(m['issues'])} issues\")
+                    parts.append('Delivered: ' + ', '.join(f\"Phase {x['phase_number']}: {x['phase_name']}\" for x in completed))
+                print('\n'.join(parts))
+                break
+except Exception as e:
+    pass
+" 2>/dev/null || echo "")
+fi
+
+ROADMAP_CONTEXT=""
+if [ -f ".planning/ROADMAP.md" ]; then
+  ROADMAP_CONTEXT=$(head -c 2000 .planning/ROADMAP.md)
+fi
+```
+
 Build analysis prompt from issue data and spawn:
 
 ```
@@ -136,6 +178,14 @@ Comments: ${comments_summary}
 ${HISTORY}
 </project_history>
 
+<milestone_context>
+${MILESTONE_CONTEXT}
+</milestone_context>
+
+<roadmap_context>
+${ROADMAP_CONTEXT}
+</roadmap_context>
+
 <analysis_dimensions>
 
 1. **Scope:** Search the codebase for files and systems related to this issue.
@@ -317,6 +367,18 @@ Post comment and apply label:
 ```bash
 remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:triaged"
 ```
+
+**Post structured metadata comment (non-blocking):**
+
+In addition to the human-readable triage comment above, post a machine-readable
+structured comment so other machines can read triage context from GitHub:
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.postPlanningComment(${ISSUE_NUMBER}, 'triage', TRIAGE_REPORT, {})
+  .catch(() => {});
+" 2>/dev/null || true
+```
 </step>
 
 <step name="present_report">

package/commands/milestone.md

@@ -881,7 +881,39 @@ Milestone: ${MILESTONE_NAME}
 fi
 ```
 
-4. Advance active milestone pointer in project.json:
+4. Update Project README with current milestone progress (non-blocking):
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.updateProjectReadme()
+  .then(ok => { if (ok) console.log('  Project README updated'); })
+  .catch(() => {});
+" 2>/dev/null || true
+```
+
+5. Post Status Update to Projects v2 board (non-blocking):
+```bash
+BOARD_NODE_ID=$(python3 -c "
+import json
+try:
+    p = json.load(open('${MGW_DIR}/project.json'))
+    print(p.get('project', {}).get('project_board', {}).get('node_id', ''))
+except: print('')
+" 2>/dev/null || echo "")
+
+if [ -n "$BOARD_NODE_ID" ]; then
+  MILESTONE_SUMMARY="Milestone ${MILESTONE_NUM} (${MILESTONE_NAME}) complete: ${TOTAL_ISSUES} issues, ${#COMPLETED_ISSUES[@]} PRs created"
+  gh api graphql -f query='mutation($projectId: ID!, $body: String!) {
+    createProjectV2StatusUpdate(input: {
+      projectId: $projectId
+      body: $body
+      status: ON_TRACK
+    }) { statusUpdate { id } }
+  }' -f projectId="$BOARD_NODE_ID" -f body="$MILESTONE_SUMMARY" 2>/dev/null || true
+fi
+```
+
+6. Advance active milestone pointer in project.json:
 ```bash
 node -e "
 const { loadProjectState, resolveActiveMilestoneIndex, writeProjectState } = require('./lib/state.cjs');
@@ -904,7 +936,7 @@ writeProjectState(state);
 "
 ```
 
-5. Milestone mapping verification:
+7. Milestone mapping verification:
 
 After advancing to the next milestone, check its GSD linkage using `getGsdState()`
 from `lib/gsd-adapter.cjs` to read current GSD execution state (.planning/STATE.md
@@ -995,7 +1027,7 @@ else:
 esac
 ```
 
-6. Display completion banner:
+8. Display completion banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MGW ► MILESTONE ${MILESTONE_NUM} COMPLETE ✓
@@ -1024,7 +1056,7 @@ Draft release created: ${RELEASE_TAG}
 ───────────────────────────────────────────────────────────────
 ```
 
-7. Check if next milestone exists and offer auto-advance (only if no failures in current).
+9. Check if next milestone exists and offer auto-advance (only if no failures in current).
 
 **If some issues failed:**
 
@@ -1127,7 +1159,7 @@ Milestone NOT closed. Re-run after resolving remaining failures:
   /mgw:milestone ${MILESTONE_NUM}
 ```
 
-8. Post final results table as GitHub comment on the first issue in the milestone:
+10. Post final results table as GitHub comment on the first issue in the milestone:
 ```bash
 gh issue comment ${FIRST_ISSUE_NUMBER} --body "$FINAL_RESULTS_COMMENT"
 ```

package/commands/project.md

@@ -180,6 +180,25 @@ fi
 @workflows/create-github-structure.md
 </step>
 
+<step name="populate_project_readme">
+**Populate Project README on GitHub Projects v2 board (non-blocking):**
+
+After GitHub structure creation, if a board is configured, populate the Project README
+with project vision and milestone overview. This gives developers a landing page
+when they open the board. Uses the shared `updateProjectReadme()` function from
+`lib/issue-context.cjs` — the same function called by `mgw:milestone` and `mgw:sync --full`
+to keep the README current.
+
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.updateProjectReadme()
+  .then(ok => { if (ok) console.log('Project README populated on board'); })
+  .catch(() => {});
+" 2>/dev/null || true
+```
+</step>
+
 </process>
 
 <success_criteria>

package/commands/run/execute.md

@@ -60,12 +60,30 @@ 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):**
+
+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 "")
+```
+
 ```
 Task(
   prompt="
 <planning_context>
 
+${MGW_CONTEXT}
+
 **Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
 **Directory:** ${QUICK_DIR}
 **Description:** ${TASK_DESCRIPTION}
@@ -109,7 +127,21 @@ Return: ## PLANNING COMPLETE with plan path
 )
 ```
 
-4. **Verify plan exists** at `${QUICK_DIR}/${next_num}-PLAN.md`
+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
@@ -187,7 +219,21 @@ Execute quick task ${next_num}.
 )
 ```
 
-8. **Verify summary (gsd-tools):**
+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")
 ```
@@ -214,7 +260,21 @@ Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}
 )
 ```
 
-10. **Post-execution artifact verification (non-blocking):**
+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}')
@@ -394,6 +454,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 +515,23 @@ 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):**
+
+   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 "")
+   ```
+
    ```
    Task(
      prompt="
@@ -441,6 +542,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 +565,20 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
+   **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)
@@ -508,6 +625,20 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
+   **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):**
    ```
    Task(
@@ -536,6 +667,20 @@ If proceed: apply "mgw:approved" label and continue.
    )
    ```
 
+   **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")

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,6 +94,13 @@ 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.
@@ -122,6 +152,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 +175,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