@snipcodeit/mgw 0.1.0

package/commands/sync.md

@@ -0,0 +1,243 @@
+---
+name: mgw:sync
+description: Reconcile local .mgw/ state with GitHub — archive completed, flag drift
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
+---
+
+<objective>
+Catch drift between GitHub and local .mgw/ state. For each active issue, checks
+if the GitHub issue is still open, if linked PRs were merged/closed, and if tracked
+branches still exist. Moves completed items to .mgw/completed/, cleans up branches
+and lingering worktrees, flags inconsistencies.
+
+Run periodically or when starting a new session to get a clean view.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+@~/.claude/commands/mgw/workflows/github.md
+@~/.claude/commands/mgw/workflows/gsd.md
+@~/.claude/commands/mgw/workflows/validation.md
+</execution_context>
+
+<process>
+
+<step name="scan_active">
+**Scan all active issue states:**
+
+```bash
+ls .mgw/active/*.json 2>/dev/null
+```
+
+If no active issues → "No active MGW issues. Nothing to sync."
+
+For each file, load the JSON state.
+</step>
+
+<step name="check_each">
+**For each active issue, check GitHub state:**
+
+```bash
+# Issue state
+gh issue view ${NUMBER} --json state,closed -q '{state: .state, closed: .closed}'
+
+# PR state (if linked_pr exists)
+gh pr view ${PR_NUMBER} --json state,mergedAt -q '{state: .state, mergedAt: .mergedAt}' 2>/dev/null
+
+# Branch existence
+git branch --list ${BRANCH_NAME} | grep -q . && echo "local" || echo "no-local"
+git ls-remote --heads origin ${BRANCH_NAME} | grep -q . && echo "remote" || echo "no-remote"
+
+# Worktree existence
+git worktree list | grep -q "${BRANCH_NAME}" && echo "worktree" || echo "no-worktree"
+
+# Comment delta (detect unreviewed comments since triage)
+CURRENT_COMMENTS=$(gh issue view ${NUMBER} --json comments --jq '.comments | length' 2>/dev/null || echo "0")
+STORED_COMMENTS="${triage.last_comment_count}"  # From state file, may be null/missing
+if [ -n "$STORED_COMMENTS" ] && [ "$STORED_COMMENTS" != "null" ]; then
+  COMMENT_DELTA=$(($CURRENT_COMMENTS - $STORED_COMMENTS))
+else
+  COMMENT_DELTA=0  # No baseline — skip comment drift
+fi
+```
+
+**GSD milestone consistency check (maps-to links):**
+
+Read all maps-to links from .mgw/cross-refs.json:
+
+```bash
+MAPS_TO_LINKS=$(python3 -c "
+import json
+with open('.mgw/cross-refs.json') as f:
+    data = json.load(f)
+links = data.get('links', [])
+maps_to = [l for l in links if l.get('type') == 'maps-to']
+print(json.dumps(maps_to))
+")
+```
+
+For each maps-to link (format: { "a": "milestone:N", "b": "gsd-milestone:id", "type": "maps-to" }):
+1. Extract the GitHub milestone number from "a" (parse "milestone:N")
+2. Extract the GSD milestone ID from "b" (parse "gsd-milestone:id")
+3. Check if this GSD milestone ID appears in either:
+   - .planning/ROADMAP.md header (active milestone)
+   - .planning/MILESTONES.md (archived milestones)
+4. If found in neither: flag as inconsistent
+
+```bash
+# Check each maps-to link
+echo "$MAPS_TO_LINKS" | python3 -c "
+import json, sys, os
+
+links = json.load(sys.stdin)
+inconsistent = []
+
+for link in links:
+    a = link.get('a', '')
+    b = link.get('b', '')
+
+    if not a.startswith('milestone:') or not b.startswith('gsd-milestone:'):
+        continue
+
+    github_num = a.split(':')[1]
+    gsd_id = b.split(':', 1)[1]
+
+    found = False
+
+    # Check ROADMAP.md
+    if os.path.exists('.planning/ROADMAP.md'):
+        with open('.planning/ROADMAP.md') as f:
+            content = f.read()
+        if gsd_id in content:
+            found = True
+
+    # Check MILESTONES.md
+    if not found and os.path.exists('.planning/MILESTONES.md'):
+        with open('.planning/MILESTONES.md') as f:
+            content = f.read()
+        if gsd_id in content:
+            found = True
+
+    if not found:
+        inconsistent.append({'github_milestone': github_num, 'gsd_id': gsd_id})
+
+for i in inconsistent:
+    print(f\"WARN: GitHub milestone #{i['github_milestone']} maps to GSD milestone '{i['gsd_id']}' which was not found in .planning/\")
+
+if not inconsistent:
+    print('GSD milestone links: all consistent')
+"
+```
+
+Classify each issue into:
+- **Completed:** Issue closed AND (PR merged OR no PR expected)
+- **Stale:** PR merged but issue still open (auto-close missed)
+- **Orphaned:** Branch deleted but work incomplete
+- **Active:** Still in progress, everything consistent
+- **Drift:** State file says one thing, GitHub says another
+- **Unreviewed comments:** COMMENT_DELTA > 0 — new comments posted since triage that haven't been classified
+</step>
+
+<step name="health_check">
+**GSD health check (if .planning/ exists):**
+
+For repos with GSD initialized, run a health check and include in the sync report:
+```bash
+if [ -d ".planning" ]; then
+  HEALTH=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs validate health 2>/dev/null || echo '{"status":"unknown"}')
+fi
+```
+This is read-only and additive — health status is included in the sync summary but does not block any reconciliation actions.
+</step>
+
+<step name="reconcile">
+**Take action per classification:**
+
+| Classification | Action |
+|---------------|--------|
+| Completed | Move state file to .mgw/completed/, clean up branch + worktree |
+| Stale | Report: "Issue #N still open but PR #M merged — close issue?" |
+| Orphaned | Report: "Branch deleted for #N but issue still open" |
+| Active | No action, include in summary |
+| Drift | Report specific mismatch, offer to update state |
+
+**Branch cleanup for completed items:**
+
+For each completed issue with linked branches:
+```bash
+# Remove any lingering worktree first
+WORKTREE_DIR=".worktrees/${BRANCH_NAME}"
+if [ -d "${WORKTREE_DIR}" ]; then
+  git worktree remove "${WORKTREE_DIR}" 2>/dev/null
+fi
+
+# Clean up empty worktree parent dirs
+rmdir .worktrees/issue 2>/dev/null
+rmdir .worktrees 2>/dev/null
+```
+
+Ask user before deleting branches:
+```
+AskUserQuestion(
+  header: "Branch Cleanup",
+  question: "Delete merged branches for completed issues?",
+  options: [
+    { label: "Delete all", description: "Remove local + remote branches for all completed issues" },
+    { label: "Local only", description: "Remove local branches, keep remote" },
+    { label: "Skip", description: "Keep all branches" }
+  ]
+)
+```
+
+If user approves:
+```bash
+# Delete local branch
+git branch -d ${BRANCH_NAME} 2>/dev/null
+
+# Delete remote branch (if user chose "Delete all")
+git push origin --delete ${BRANCH_NAME} 2>/dev/null
+```
+</step>
+
+<step name="report">
+**Present sync summary:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► SYNC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Active:    ${active_count} issues in progress
+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
+${HEALTH ? 'GSD Health: ' + HEALTH.status : ''}
+
+${details_for_each_non_active_item}
+${comment_drift_details ? 'Unreviewed comments:\n' + comment_drift_details : ''}
+${gsd_milestone_consistency ? 'GSD Milestone Links:\n' + gsd_milestone_consistency : ''}
+
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All .mgw/active/ files scanned
+- [ ] GitHub state checked for each issue, PR, branch
+- [ ] Comment delta checked for each active issue
+- [ ] GSD milestone consistency checked for all maps-to links
+- [ ] Completed items moved to .mgw/completed/
+- [ ] Lingering worktrees cleaned up for completed items
+- [ ] Branch deletion offered for completed items
+- [ ] Stale/orphaned/drift items flagged (including comment drift and milestone inconsistencies)
+- [ ] Summary presented
+</success_criteria>

package/commands/update.md

@@ -0,0 +1,282 @@
+---
+name: mgw:update
+description: Post a structured status comment on a GitHub issue
+argument-hint: "<issue-number> [message]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+<objective>
+Post professional, structured status comments on GitHub issues. These comments serve
+as a machine-readable audit trail — MGW reads them back for resume detection, sync,
+and progress tracking.
+
+Called automatically by mgw:run at every pipeline checkpoint, or manually with a custom
+message. Each comment follows a consistent format with metadata headers and collapsible
+detail sections.
+
+When called without a message, auto-detects update type from .mgw/ pipeline_stage.
+When called with a message, posts that as a custom update.
+
+Appends cross-references from .mgw/cross-refs.json if related work exists.
+Logs comment ID in state file to prevent duplicates.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+@~/.claude/commands/mgw/workflows/github.md
+</execution_context>
+
+<context>
+$ARGUMENTS — expects: <issue-number> [optional message]
+</context>
+
+<process>
+
+<step name="parse_args">
+**Parse issue number and optional message:**
+
+First token: issue number (required).
+Remaining tokens: custom message (optional).
+
+If no issue number, check .mgw/active/ for exactly one active issue. If exactly one, use it. If zero or multiple, prompt:
+```
+AskUserQuestion(
+  header: "Which Issue?",
+  question: "Which issue number do you want to update?",
+  followUp: null
+)
+```
+</step>
+
+<step name="read_state">
+**Read issue state:**
+
+Find state file: `.mgw/active/${ISSUE_NUMBER}-*.json`
+
+If not found → error: "No active MGW state for issue #${ISSUE_NUMBER}. Run /mgw:issue ${ISSUE_NUMBER} first."
+
+Load state as $STATE.
+
+Also load project.json if it exists (for milestone/phase context):
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+MGW_DIR="${REPO_ROOT}/.mgw"
+PROJECT_JSON=""
+if [ -f "${MGW_DIR}/project.json" ]; then
+  PROJECT_JSON=$(cat "${MGW_DIR}/project.json")
+fi
+```
+
+Extract milestone and phase context:
+```bash
+if [ -n "$PROJECT_JSON" ]; then
+  MILESTONE_CONTEXT=$(echo "$PROJECT_JSON" | python3 -c "
+import json, sys
+p = json.load(sys.stdin)
+for m in p['milestones']:
+  for i in m.get('issues', []):
+    if i.get('github_number') == ${ISSUE_NUMBER}:
+      print(f\"Milestone: {m['name']} | Phase {i['phase_number']}: {i['phase_name']}\")
+      break
+" 2>/dev/null || echo "")
+fi
+```
+</step>
+
+<step name="build_comment">
+**Build comment body:**
+
+If custom message provided → use it wrapped in the standard format:
+```markdown
+> **MGW** · `status-update` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+${custom_message}
+```
+
+If no custom message → auto-detect from pipeline_stage and build structured comment:
+
+**All comments follow this format:**
+```markdown
+> **MGW** · `${stage_label}` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### ${Stage Title}
+
+${Stage-specific body with structured data}
+
+<details>
+<summary>Pipeline State</summary>
+
+| Field | Value |
+|-------|-------|
+| Stage | `${pipeline_stage}` |
+| Route | `${gsd_route}` |
+| Branch | `${branch_name}` |
+| Duration | ${elapsed} |
+
+</details>
+```
+
+**Stage-specific templates:**
+
+---
+
+**`triaged`** — Posted after triage analysis completes:
+```markdown
+> **MGW** · `triage-complete` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### Triage Complete
+
+| | |
+|---|---|
+| **Scope** | ${scope_size} — ${file_count} files across ${system_list} |
+| **Validity** | ${validity_status} |
+| **Security** | ${security_risk} |
+| **Route** | \`${gsd_route}\` — ${route_reasoning} |
+| **Conflicts** | ${conflicts_or_none} |
+
+Work begins on branch \`${branch_name}\`.
+
+<details>
+<summary>Affected Files</summary>
+
+${file_list_as_bullet_points}
+
+</details>
+```
+
+---
+
+**`planning`** — Posted after GSD planner completes:
+```markdown
+> **MGW** · `planning-complete` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### Planning Complete
+
+Plan created via \`${gsd_route}\` with ${task_count} task(s).
+
+| Task | Files | Action |
+|------|-------|--------|
+${task_table_from_plan}
+
+Execution starting.
+```
+
+---
+
+**`executing`** — Posted during/after GSD executor:
+```markdown
+> **MGW** · `execution-complete` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### Execution Complete
+
+${commit_count} atomic commit(s) on branch \`${branch_name}\`.
+
+**Changes:**
+${file_changes_grouped_by_module}
+
+**Tests:** ${test_status}
+
+Preparing pull request.
+```
+
+---
+
+**`verifying`** — Posted after GSD verifier (--full mode only):
+```markdown
+> **MGW** · `verification` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### Verification
+
+${must_have_count}/${must_have_total} must-haves passed.
+
+| Check | Status |
+|-------|--------|
+${verification_table}
+```
+
+---
+
+**`pr-created`** — Posted after PR is created:
+```markdown
+> **MGW** · `pr-ready` · ${timestamp}
+> ${MILESTONE_CONTEXT}
+
+### PR Ready
+
+**PR #${pr_number}** — [${pr_title}](${pr_url})
+
+Testing procedures posted on the PR.
+This issue will auto-close when the PR is merged.
+
+<details>
+<summary>Pipeline Summary</summary>
+
+| Stage | Duration | Status |
+|-------|----------|--------|
+| Triage | ${triage_duration} | ✓ |
+| Planning | ${planning_duration} | ✓ |
+| Execution | ${execution_duration} | ✓ |
+${verification_row}
+| PR Creation | ${pr_duration} | ✓ |
+| **Total** | **${total_duration}** | |
+
+</details>
+```
+
+---
+
+**Append cross-references** if .mgw/cross-refs.json has links for this issue:
+```markdown
+
+---
+<sub>Related: ${cross_ref_list} · Managed by [MGW](https://github.com/snipcodeit/mgw)</sub>
+```
+</step>
+
+<step name="post_comment">
+**Post comment and log:**
+
+```bash
+gh issue comment $ISSUE_NUMBER --body "$COMMENT_BODY"
+```
+
+Capture comment URL from output.
+
+Update state file: append to comments_posted array:
+```json
+{ "type": "${update_type}", "timestamp": "$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs current-timestamp --raw)", "url": "${comment_url}" }
+```
+
+Write updated state back to `.mgw/active/${filename}.json`.
+</step>
+
+<step name="report">
+**Report to user:**
+
+```
+Posted ${update_type} comment on #${ISSUE_NUMBER}: ${comment_url}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Issue number parsed from args or auto-detected from single active issue
+- [ ] State file read from .mgw/active/
+- [ ] Milestone/phase context loaded from project.json if available
+- [ ] Comment body built (auto-detected type or custom message)
+- [ ] Comment follows structured format with metadata header
+- [ ] Cross-references appended if present
+- [ ] Comment posted via gh issue comment
+- [ ] Comment ID logged in state file (no duplicates)
+</success_criteria>