@snipcodeit/mgw 0.1.1 → 0.1.3

package/commands/sync.md

@@ -16,6 +16,11 @@ if the GitHub issue is still open, if linked PRs were merged/closed, and if trac
 branches still exist. Moves completed items to .mgw/completed/, cleans up branches
 and lingering worktrees, flags inconsistencies.
 
+Also pulls board state to reconstruct missing local state files — enabling multi-machine
+workflows. On a fresh machine with no .mgw/active/ files, sync reads the GitHub Projects
+v2 board's Status field and rebuilds local state for every in-progress issue, so work
+can continue without re-triaging from scratch.
+
 Run periodically or when starting a new session to get a clean view.
 </objective>
 
@@ -28,6 +33,321 @@ Run periodically or when starting a new session to get a clean view.
 
 <process>
 
+<step name="pull_board_state">
+**Pull board state to reconstruct missing local .mgw/active/ files.**
+
+This step runs first — before scan_active — so that any issues the board knows about
+but this machine doesn't will be present by the time check_each runs. This is the
+multi-machine sync mechanism: board is the distributed source of truth, .mgw/active/
+is the local cache that sync rebuilds from it.
+
+Two sub-operations, both non-blocking:
+1. **Board discovery** — if project_board.node_id is missing, find and register it.
+2. **Board pull** — fetch all board items, reconstruct .mgw/active/ for any issue not
+   present locally, detect stage drift for issues that exist on both sides.
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+MGW_DIR="${REPO_ROOT}/.mgw"
+OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
+ACTIVE_DIR="${MGW_DIR}/active"
+mkdir -p "$ACTIVE_DIR"
+
+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 "")
+
+BOARD_DISCOVERED=""
+BOARD_PULL_CREATED=0
+BOARD_PULL_DRIFT="[]"
+BOARD_PULL_ERRORS="[]"
+
+# Sub-operation 1: board discovery
+if [ -z "$BOARD_NODE_ID" ] && [ -f "${MGW_DIR}/project.json" ]; then
+  PROJECT_NAME=$(python3 -c "
+import json
+try:
+    p = json.load(open('${MGW_DIR}/project.json'))
+    print(p.get('project', {}).get('name', ''))
+except: print('')
+" 2>/dev/null || echo "")
+
+  if [ -n "$PROJECT_NAME" ]; then
+    DISCOVERED=$(node -e "
+const { findExistingBoard, getProjectFields } = require('./lib/github.cjs');
+const board = findExistingBoard('${OWNER}', '${PROJECT_NAME}');
+if (!board) { process.stdout.write(''); process.exit(0); }
+const fields = getProjectFields('${OWNER}', board.number) || {};
+console.log(JSON.stringify({ ...board, fields }));
+" 2>/dev/null || echo "")
+
+    if [ -n "$DISCOVERED" ]; then
+      python3 -c "
+import json
+with open('${MGW_DIR}/project.json') as f:
+    project = json.load(f)
+d = json.loads('${DISCOVERED}')
+project['project']['project_board'] = {
+    'number': d['number'], 'url': d['url'],
+    'node_id': d['nodeId'], 'fields': d.get('fields', {})
+}
+with open('${MGW_DIR}/project.json', 'w') as f:
+    json.dump(project, f, indent=2)
+" 2>/dev/null
+      BOARD_NODE_ID=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['nodeId'])" 2>/dev/null)
+      DISC_NUMBER=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['number'])" 2>/dev/null)
+      DISC_URL=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['url'])" 2>/dev/null)
+      BOARD_DISCOVERED="#${DISC_NUMBER} — ${DISC_URL}"
+    fi
+  fi
+fi
+
+# Sub-operation 2: board pull
+if [ -n "$BOARD_NODE_ID" ]; then
+  echo "Pulling board state from GitHub..."
+
+  BOARD_ITEMS=$(gh api graphql -f query='
+    query($projectId: ID!) {
+      node(id: $projectId) {
+        ... on ProjectV2 {
+          items(first: 100) {
+            nodes {
+              id
+              content {
+                ... on Issue { number title url }
+              }
+              fieldValues(first: 10) {
+                nodes {
+                  ... on ProjectV2ItemFieldSingleSelectValue {
+                    name
+                    field { ... on ProjectV2SingleSelectField { name } }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ' -f projectId="$BOARD_NODE_ID" \
+    --jq '.data.node.items.nodes' 2>/dev/null || echo "[]")
+
+  # One Python call handles: map board items, detect missing local files,
+  # reconstruct state from GitHub issue data, detect drift on existing files.
+  PULL_RESULT=$(echo "$BOARD_ITEMS" | ACTIVE_DIR="$ACTIVE_DIR" MGW_DIR="$MGW_DIR" python3 << 'PYEOF'
+import json, sys, os, subprocess, re
+
+ACTIVE_DIR = os.environ['ACTIVE_DIR']
+GSD_TOOLS = os.path.expanduser('~/.claude/get-shit-done/bin/gsd-tools.cjs')
+
+STATUS_TO_STAGE = {
+    'New': 'new', 'Triaged': 'triaged',
+    'Needs Info': 'needs-info', 'Needs Security Review': 'needs-security-review',
+    'Discussing': 'discussing', 'Approved': 'approved',
+    'Planning': 'planning', 'Executing': 'executing',
+    'Verifying': 'verifying', 'PR Created': 'pr-created',
+    'Done': 'done', 'Failed': 'failed', 'Blocked': 'blocked'
+}
+
+nodes = json.load(sys.stdin)
+created = []
+drift = []
+errors = []
+
+for node in nodes:
+    content = node.get('content', {})
+    num = content.get('number')
+    if num is None:
+        continue
+
+    status_label = ''
+    route_label = ''
+    for fv in node.get('fieldValues', {}).get('nodes', []):
+        fname = fv.get('field', {}).get('name', '')
+        if fname == 'Status':
+            status_label = fv.get('name', '')
+        elif fname == 'GSD Route':
+            route_label = fv.get('name', '')
+
+    board_stage = STATUS_TO_STAGE.get(status_label, 'new')
+
+    # Done items belong in completed/, not active/ — skip
+    if board_stage == 'done':
+        continue
+
+    # Check for existing local active file
+    existing = None
+    for fname in os.listdir(ACTIVE_DIR):
+        if fname.startswith(f'{num}-') and fname.endswith('.json'):
+            existing = os.path.join(ACTIVE_DIR, fname)
+            break
+
+    if existing is None:
+        # No local file — reconstruct from GitHub issue data
+        try:
+            r = subprocess.run(
+                ['gh', 'issue', 'view', str(num),
+                 '--json', 'number,title,url,labels,assignees'],
+                capture_output=True, text=True
+            )
+            issue = json.loads(r.stdout)
+        except Exception as e:
+            errors.append({'number': num, 'error': str(e)})
+            continue
+
+        title = issue.get('title', content.get('title', ''))
+
+        try:
+            slug = subprocess.run(
+                ['node', GSD_TOOLS, 'generate-slug', title, '--raw'],
+                capture_output=True, text=True
+            ).stdout.strip()[:40]
+        except:
+            slug = re.sub(r'[^a-z0-9]+', '-', title.lower()).strip('-')[:40]
+
+        try:
+            ts = subprocess.run(
+                ['node', GSD_TOOLS, 'current-timestamp', '--raw'],
+                capture_output=True, text=True
+            ).stdout.strip()
+        except:
+            from datetime import datetime
+            ts = datetime.utcnow().isoformat() + 'Z'
+
+        labels = [l.get('name', '') if isinstance(l, dict) else str(l)
+                  for l in issue.get('labels', [])]
+        assignees = issue.get('assignees', [])
+        assignee = assignees[0].get('login') if assignees else None
+
+        state = {
+            'issue': {
+                'number': num,
+                'title': title,
+                'url': issue.get('url', content.get('url', '')),
+                'labels': labels,
+                'assignee': assignee
+            },
+            'triage': {
+                'scope': {'files': 0, 'systems': []},
+                'validity': 'confirmed',
+                'security_notes': '',
+                'conflicts': [],
+                'last_comment_count': 0,
+                'last_comment_at': None,
+                'gate_result': {
+                    'status': 'passed',
+                    'blockers': [],
+                    'warnings': [f'Reconstructed from board state by mgw:sync — {ts}'],
+                    'missing_fields': []
+                }
+            },
+            'gsd_route': route_label or None,
+            'gsd_artifacts': {'type': None, 'path': None},
+            'pipeline_stage': board_stage,
+            'reconstructed_from_board': True,
+            'comments_posted': [],
+            'linked_pr': None,
+            'linked_issues': [],
+            'linked_branches': []
+        }
+
+        state_path = os.path.join(ACTIVE_DIR, f'{num}-{slug}.json')
+        with open(state_path, 'w') as f:
+            json.dump(state, f, indent=2)
+
+        created.append({'number': num, 'title': title, 'stage': board_stage})
+
+    else:
+        # Local file exists — detect stage drift
+        try:
+            local = json.load(open(existing))
+            local_stage = local.get('pipeline_stage', 'new')
+            if local_stage != board_stage:
+                drift.append({
+                    'number': num,
+                    'title': content.get('title', ''),
+                    'local': local_stage,
+                    'board': board_stage
+                })
+        except:
+            pass
+
+print(json.dumps({'created': created, 'drift': drift, 'errors': errors}))
+PYEOF
+)
+
+  BOARD_PULL_CREATED=$(echo "$PULL_RESULT" | python3 -c "import json,sys; print(len(json.load(sys.stdin).get('created', [])))" 2>/dev/null || echo "0")
+  BOARD_PULL_DRIFT=$(echo "$PULL_RESULT" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('drift', [])))" 2>/dev/null || echo "[]")
+  BOARD_PULL_ERRORS=$(echo "$PULL_RESULT" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('errors', [])))" 2>/dev/null || echo "[]")
+
+  if [ "$BOARD_PULL_CREATED" -gt 0 ]; then
+    echo "  Reconstructed ${BOARD_PULL_CREATED} issue(s) from board state"
+    echo "$PULL_RESULT" | python3 -c "
+import json, sys
+for item in json.load(sys.stdin).get('created', []):
+    print(f'  ✓ #{item[\"number\"]} ({item[\"stage\"]}): {item[\"title\"][:60]}')
+" 2>/dev/null
+  fi
+
+  # Offer drift resolution if any issues have mismatched stages
+  DRIFT_COUNT=$(echo "$BOARD_PULL_DRIFT" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo "0")
+
+  if [ "$DRIFT_COUNT" -gt 0 ]; then
+    echo ""
+    echo "Stage drift detected (board vs local):"
+    echo "$BOARD_PULL_DRIFT" | python3 -c "
+import json, sys
+for d in json.load(sys.stdin):
+    print(f'  #{d[\"number\"]} {d[\"title\"][:45]}: local={d[\"local\"]} board={d[\"board\"]}')
+" 2>/dev/null
+    echo ""
+
+    AskUserQuestion(
+      header: "Stage Drift",
+      question: "Board and local state disagree on pipeline stage for ${DRIFT_COUNT} issue(s). How should we resolve?",
+      options: [
+        { label: "Pull from board", description: "Update all local files to match board stages (board is source of truth)" },
+        { label: "Keep local",      description: "Leave local stages as-is — board will be updated next time pipeline runs" },
+        { label: "Skip",            description: "Ignore drift for now — flag in report only" }
+      ]
+    )
+
+    if [ "$USER_CHOICE" = "Pull from board" ]; then
+      echo "$BOARD_PULL_DRIFT" | python3 -c "
+import json, sys, os
+
+drift = json.load(sys.stdin)
+active_dir = '${ACTIVE_DIR}'
+
+for d in drift:
+    num = d['number']
+    board_stage = d['board']
+    for fname in os.listdir(active_dir):
+        if fname.startswith(f'{num}-') and fname.endswith('.json'):
+            path = os.path.join(active_dir, fname)
+            state = json.load(open(path))
+            state['pipeline_stage'] = board_stage
+            with open(path, 'w') as f:
+                json.dump(state, f, indent=2)
+            print(f'  Updated #{num}: {d[\"local\"]} → {board_stage}')
+            break
+" 2>/dev/null
+      BOARD_PULL_DRIFT="[]"  # Resolved
+    fi
+  fi
+fi
+```
+
+**Note:** `reconstructed_from_board: true` is set on any state file created this way.
+Downstream commands (`/mgw:run`, `/mgw:issue`) will see this flag and know the state was
+rebuilt from board data — triage results and GSD artifacts will need to be re-run if the
+issue advances to `planning` or beyond.
+</step>
+
 <step name="scan_active">
 **Scan all active issue states:**
 
@@ -144,6 +464,81 @@ Classify each issue into:
 - **Unreviewed comments:** COMMENT_DELTA > 0 — new comments posted since triage that haven't been classified
 </step>
 
+<step name="label_drift_detection">
+**Label Drift Detection:**
+
+For each active issue state file in `.mgw/active/`, compare the stored `labels` field
+against the live GitHub labels to detect MGW pipeline label drift:
+
+```python
+label_drift = []
+
+for each state_file in .mgw/active/*.json:
+  stored_labels = state['labels']  # list stored at last pipeline write
+  live_labels_json = subprocess.run(
+    ['gh', 'issue', 'view', str(issue_number), '--json', 'labels', '--jq', '[.labels[].name]'],
+    capture_output=True, text=True
+  ).stdout.strip()
+  live_labels = json.loads(live_labels_json or '[]')
+
+  # Find MGW labels in stored vs live
+  stored_mgw = [l for l in stored_labels if l.startswith('mgw:')]
+  live_mgw = [l for l in live_labels if l.startswith('mgw:')]
+
+  if set(stored_mgw) != set(live_mgw):
+    label_drift.append({
+      'issue': issue_number,
+      'stored': stored_mgw,
+      'live': live_mgw,
+      'pipeline_stage': state['pipeline_stage']
+    })
+```
+
+If label drift detected, include in the drift report output:
+
+```
+Label drift detected for ${COUNT} issue(s):
+  #N: stored=[mgw:in-progress], live=[] — pipeline_stage=${STAGE}
+```
+
+**Offer repair:**
+```
+AskUserQuestion(
+  header: "Label Drift Detected",
+  question: "Live GitHub labels don't match .mgw state for ${COUNT} issue(s). Repair?",
+  options: [
+    { label: "Repair all", description: "Re-apply correct label for each issue's pipeline_stage via remove_mgw_labels_and_apply" },
+    { label: "Skip", description: "Log drift only — no changes" }
+  ]
+)
+```
+
+If "Repair all":
+```bash
+# For each drifted issue, determine correct label from pipeline_stage and re-apply
+CORRECT_LABEL=$(python3 -c "
+stage_to_label = {
+  'triaged': 'mgw:triaged',
+  'needs-info': 'mgw:needs-info',
+  'needs-security-review': 'mgw:needs-security-review',
+  'discussing': 'mgw:discussing',
+  'approved': 'mgw:approved',
+  'planning': 'mgw:in-progress',
+  'executing': 'mgw:in-progress',
+  'verifying': 'mgw:in-progress',
+  'blocked': 'mgw:blocked',
+  'done': '',
+  'pr-created': '',
+  'failed': '',
+}
+print(stage_to_label.get('${PIPELINE_STAGE}', ''))
+")
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "${CORRECT_LABEL}"
+```
+
+Log repair actions: "Repaired label for #N: applied ${CORRECT_LABEL} (pipeline_stage=${STAGE})"
+</step>
+
 <step name="health_check">
 **GSD health check (if .planning/ exists):**
 
@@ -214,11 +609,13 @@ git push origin --delete ${BRANCH_NAME} 2>/dev/null
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Active:    ${active_count} issues in progress
+Pulled:    ${BOARD_PULL_CREATED} reconstructed from board  (0 if board not configured)
 Completed: ${completed_count} archived
 Stale:     ${stale_count} need attention
 Orphaned:  ${orphaned_count} need attention
 Comments:  ${comment_drift_count} issues with unreviewed comments
 Branches:  ${deleted_count} cleaned up
+${BOARD_DISCOVERED ? 'Board:     discovered + registered ' + BOARD_DISCOVERED : ''}
 ${HEALTH ? 'GSD Health: ' + HEALTH.status : ''}
 
 ${details_for_each_non_active_item}
@@ -231,7 +628,16 @@ ${gsd_milestone_consistency ? 'GSD Milestone Links:\n' + gsd_milestone_consisten
 </process>
 
 <success_criteria>
-- [ ] All .mgw/active/ files scanned
+- [ ] pull_board_state runs before scan_active
+- [ ] Board discovery: if project_board.node_id empty, findExistingBoard() + getProjectFields() called; if found, registered in project.json
+- [ ] Board pull: all board items fetched in one GraphQL call; issues with no local .mgw/active/ file are reconstructed from GitHub issue data + board Status
+- [ ] Reconstructed files have reconstructed_from_board:true, pipeline_stage from board Status, gsd_route from board GSD Route field
+- [ ] "Done" board items are skipped (not written to active/)
+- [ ] Stage drift detected and reported: local pipeline_stage differs from board Status
+- [ ] Drift resolution offered: pull from board / keep local / skip
+- [ ] Board pull errors (failed gh issue view calls) are collected and shown in report, never abort sync
+- [ ] BOARD_PULL_CREATED count shown in sync report
+- [ ] All .mgw/active/ files scanned (including any reconstructed by pull_board_state)
 - [ ] GitHub state checked for each issue, PR, branch
 - [ ] Comment delta checked for each active issue
 - [ ] GSD milestone consistency checked for all maps-to links
@@ -239,5 +645,7 @@ ${gsd_milestone_consistency ? 'GSD Milestone Links:\n' + gsd_milestone_consisten
 - [ ] Lingering worktrees cleaned up for completed items
 - [ ] Branch deletion offered for completed items
 - [ ] Stale/orphaned/drift items flagged (including comment drift and milestone inconsistencies)
+- [ ] Label drift detected between .mgw/active labels field and live GitHub labels
+- [ ] Repair offered for drifted issues via remove_mgw_labels_and_apply
 - [ ] Summary presented
 </success_criteria>

package/commands/workflows/github.md

@@ -95,12 +95,15 @@ Seven labels for pipeline stage tracking. Created by init.md, managed by issue.m
 | `mgw:blocked` | `b60205` | Pipeline blocked by stakeholder comment |
 
 ### Remove MGW Labels and Apply New
-Used when transitioning pipeline stages. Removes all `mgw:*` pipeline labels, then applies the target label.
+Used when transitioning pipeline stages. Removes all `mgw:*` pipeline labels, then applies the target label. Returns non-zero if any gh operation failed.
 ```bash
-# Remove all mgw: pipeline labels from issue, then apply new one
+# Remove all mgw: pipeline labels from issue, then apply new one.
+# Pass empty string as NEW_LABEL to remove all MGW labels without applying a new one.
+# Returns non-zero if any label operation failed.
 remove_mgw_labels_and_apply() {
   local ISSUE_NUMBER="$1"
   local NEW_LABEL="$2"
+  local LABEL_FAILED=0
 
   # Get current labels
   CURRENT_LABELS=$(gh issue view "$ISSUE_NUMBER" --json labels --jq '.labels[].name' 2>/dev/null)
@@ -109,15 +112,27 @@ remove_mgw_labels_and_apply() {
   for LABEL in $CURRENT_LABELS; do
     case "$LABEL" in
       mgw:triaged|mgw:needs-info|mgw:needs-security-review|mgw:discussing|mgw:approved|mgw:in-progress|mgw:blocked)
-        gh issue edit "$ISSUE_NUMBER" --remove-label "$LABEL" 2>/dev/null
+        gh issue edit "$ISSUE_NUMBER" --remove-label "$LABEL"
+        RC=$?
+        if [ $RC -ne 0 ]; then
+          echo "MGW WARNING: failed to remove label $LABEL from issue $ISSUE_NUMBER (exit $RC)" >&2
+          LABEL_FAILED=1
+        fi
         ;;
     esac
   done
 
   # Apply new label
   if [ -n "$NEW_LABEL" ]; then
-    gh issue edit "$ISSUE_NUMBER" --add-label "$NEW_LABEL" 2>/dev/null
+    gh issue edit "$ISSUE_NUMBER" --add-label "$NEW_LABEL"
+    RC=$?
+    if [ $RC -ne 0 ]; then
+      echo "MGW WARNING: failed to add label $NEW_LABEL to issue $ISSUE_NUMBER (exit $RC)" >&2
+      LABEL_FAILED=1
+    fi
   fi
+
+  return $LABEL_FAILED
 }
 ```
 

package/dist/bin/mgw.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var claude = require('../claude-Vp9qvImH.cjs');
+var claude = require('../claude-Dk1oVsaG.cjs');
 var require$$0 = require('commander');
 var require$$1 = require('path');
 var require$$0$2 = require('fs');
@@ -9,7 +9,7 @@ var require$$0$1 = require('child_process');
 
 var mgw$1 = {};
 
-var version = "0.1.1";
+var version = "0.1.3";
 var require$$8 = {
 	version: version};