@snipcodeit/mgw 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,9 @@
 # MGW — My GSD Workflow
 
-[![npm version](https://img.shields.io/npm/v/mgw)](https://www.npmjs.com/package/mgw)
+[![npm version](https://img.shields.io/npm/v/@snipcodeit/mgw)](https://www.npmjs.com/package/@snipcodeit/mgw)
+[![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/mgw)](https://nodejs.org)
+[![node](https://img.shields.io/node/v/@snipcodeit/mgw)](https://nodejs.org)
 [![GitHub stars](https://img.shields.io/github/stars/snipcodeit/mgw)](https://github.com/snipcodeit/mgw)
 
 > Issue in. PR out. No excuses.
@@ -95,6 +96,9 @@ If you're already using Claude Code and GSD for development, MGW is the missing
 | `/mgw:review <n>` | Review and classify new comments on an issue since last triage |
 | `/mgw:link <ref> <ref>` | Cross-reference issues, PRs, and branches (including milestone ↔ GSD milestone maps-to links) |
 | `/mgw:status [n]` | Project dashboard — milestone progress, issue stages, open PRs |
+| `/mgw:roadmap [--set-dates] [--post-discussion]` | Render project milestones as a roadmap table; optionally set GitHub due dates or post as a Discussion |
+| `/mgw:assign <n> [user]` | Claim or reassign an issue; resolves GitHub noreply co-author tag |
+| `/mgw:board [--sync]` | Create, configure, and sync a GitHub Projects v2 board |
 | `/mgw:sync` | Reconcile local state with GitHub; verifies GSD milestone consistency |
 | `/mgw:help` | Command reference |
 
@@ -184,9 +188,12 @@ MGW tracks pipeline state in a local `.mgw/` directory (gitignored, per-develope
     42-fix-auth.json   Issue state: triage results, pipeline stage, artifacts
   completed/           Archived after PR merge
   cross-refs.json      Bidirectional issue/PR/branch/milestone links
-  vision-draft.md      (Fresh projects) Rolling decisions from questioning loop
-  vision-brief.json    (Fresh projects) Structured Vision Brief (MoSCoW, personas, scope)
+  vision-research.json   (Fresh projects) Domain research from vision-researcher agent
+  vision-draft.md        (Fresh projects) Rolling decisions from questioning loop
+  vision-brief.json      (Fresh projects) Structured Vision Brief (MoSCoW, personas, scope)
+  vision-handoff.md      (Fresh projects) Condensed brief handed off to gsd:new-project
   alignment-report.json  (GSD-Only projects) GSD state mapped for milestone backfill
+  drift-report.json      (Diverged projects) Reconciliation table from drift-analyzer agent
 ```
 
 Pipeline stages flow: `new` → `triaged` → `planning` → `executing` → `verifying` → `pr-created` → `done` (or `failed`/`blocked`). Bugs routed to `gsd:diagnose-issues` pass through `diagnosing` before `planning`.
@@ -207,37 +214,37 @@ Try MGW without installing anything:
 
 ```bash
 # See available commands
-npx mgw --help
+npx @snipcodeit/mgw --help
 
 # List your open issues
-npx mgw issues
+npx @snipcodeit/mgw issues
 
 # Sync local state with GitHub
-npx mgw sync
+npx @snipcodeit/mgw sync
 
 # Cross-reference two issues
-npx mgw link 42 43
+npx @snipcodeit/mgw link 42 43
 ```
 
-`npx mgw` gives you the full CLI subset that works without Claude Code. For the AI-powered pipeline commands (`run`, `issue`, `project`, `milestone`, etc.), do a full install below.
+`npx @snipcodeit/mgw` gives you the full CLI subset that works without Claude Code. For the AI-powered pipeline commands (`run`, `issue`, `project`, `milestone`, etc.), do a full install below.
 
 ## Installation
 
-### Full install (CLI + slash commands)
+### npm (recommended)
 
 ```bash
-git clone https://github.com/snipcodeit/mgw.git
-cd mgw
-npm install && npm run build
-npm link
-# Slash commands are installed automatically by npm postinstall
+npm install -g @snipcodeit/mgw
+# Slash commands are automatically deployed to ~/.claude/commands/mgw/
 ```
 
-### Slash commands only (no CLI)
+### From source
 
 ```bash
-npm install -g mgw
-# Slash commands are automatically deployed to ~/.claude/commands/mgw/
+git clone https://github.com/snipcodeit/mgw.git
+cd mgw
+npm install && npm run build
+npm install -g . --prefix ~/.npm-global
+# Slash commands are installed automatically by npm postinstall
 ```
 
 ### Verify
@@ -248,9 +255,9 @@ mgw --version
 
 # Slash commands (installed automatically by postinstall)
 ls ~/.claude/commands/mgw/
-# ask.md  board.md  help.md  init.md  issue.md  issues.md  link.md  milestone.md
-# next.md  pr.md  project.md  review.md  run.md  status.md  sync.md
-# update.md  workflows/
+# ask.md  assign.md  board.md  help.md  init.md  issue.md  issues.md  link.md
+# milestone.md  next.md  pr.md  project.md  review.md  roadmap.md  run.md
+# status.md  sync.md  update.md  workflows/
 ```
 
 Then in Claude Code:
@@ -266,9 +273,9 @@ Not all commands work via `npx`. The CLI has two tiers:
 | Tier | Commands | Requirements |
 |------|----------|--------------|
 | **CLI-only** (works with npx) | `issues`, `sync`, `link`, `help`, `--help`, `--version` | Node.js >= 18, `gh` CLI |
-| **AI-powered** (requires full install) | `run`, `init`, `project`, `milestone`, `next`, `issue`, `update`, `pr`, `ask`, `review` | Node.js >= 18, `gh` CLI, Claude Code CLI, GSD |
+| **AI-powered** (requires full install) | `run`, `init`, `project`, `milestone`, `next`, `issue`, `update`, `pr`, `ask`, `review`, `assign`, `board`, `roadmap`, `status` | Node.js >= 18, `gh` CLI, Claude Code CLI, GSD |
 
-AI-powered commands call `claude -p` under the hood and require the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) to be installed and authenticated. The slash command `.md` files must also be deployed to `~/.claude/commands/mgw/` for the full pipeline to work. Use `npx mgw` to explore the CLI and verify your GitHub setup before committing to a full install.
+AI-powered commands call `claude -p` under the hood and require the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) to be installed and authenticated. The slash command `.md` files must also be deployed to `~/.claude/commands/mgw/` for the full pipeline to work — this happens automatically via `postinstall`. Use `npx @snipcodeit/mgw` to explore the CLI and verify your GitHub setup before committing to a full install.
 
 ## Typical Workflow
 
@@ -336,12 +343,15 @@ lib/
   claude.cjs              Claude Code invocation helpers
   github.cjs              GitHub CLI wrappers (issues, PRs, milestones, Projects v2)
   gsd.cjs                 GSD integration
+  gsd-adapter.cjs         GSD route adapter (maps triage results to GSD spawn args)
   state.cjs               .mgw/ state management (migrateProjectState, resolveActiveMilestoneIndex)
   output.cjs              Logging and formatting
+  retry.cjs               Retry logic for GitHub API calls
   templates.cjs           Template system
   template-loader.cjs     Output validation (JSON Schema) + parseRoadmap()
 commands/                  Slash command source files (deployed to ~/.claude/commands/mgw/ at install time)
   ask.md                  Contextual question routing during milestone execution
+  assign.md               Claim/reassign issues; resolves GitHub noreply co-author tag
   board.md                GitHub Projects v2 board management
   help.md                 Command reference display
   init.md                 One-time repo bootstrap (state, templates, labels)
@@ -350,6 +360,7 @@ commands/                  Slash command source files (deployed to ~/.claude/com
   issue.md                Deep triage with agent analysis
   next.md                 Next unblocked issue picker (surfaces failed issues as advisory)
   review.md               Comment review and classification since last triage
+  roadmap.md              Milestone roadmap table; optional GitHub due-date setter and Discussion post
   run.md                  Autonomous pipeline orchestrator (cross-milestone enforcement)
   milestone.md            Milestone execution with dependency ordering and failed-issue recovery
   update.md               Structured GitHub comment templates
@@ -491,7 +502,7 @@ If rate-limited, wait for the reset window (usually under an hour) or reduce the
 
 ```bash
 # Remove CLI
-npm unlink mgw
+npm uninstall -g @snipcodeit/mgw
 
 # Remove slash commands
 rm -rf ~/.claude/commands/mgw/

package/commands/board.md

@@ -176,6 +176,81 @@ for name, data in fields.items():
   fi
 ```
 
+**Board discovery: check GitHub for an existing board before creating a new one:**
+
+One lightweight GraphQL list call. Searches the first 20 user/org projects for a title
+containing the project name. If found, registers it in project.json and exits — no fields
+created, no board duplicated. Only runs when `BOARD_CONFIGURED = false`.
+
+```bash
+  echo "Checking GitHub for existing boards..."
+  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
+    DISC_NUMBER=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['number'])")
+    DISC_URL=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['url'])")
+    DISC_NODE_ID=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['nodeId'])")
+    DISC_TITLE=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.load(sys.stdin)['title'])")
+    DISC_FIELDS=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('fields', {})))")
+
+    echo "  Found existing board: #${DISC_NUMBER} \"${DISC_TITLE}\" — ${DISC_URL}"
+
+    python3 << PYEOF
+import json
+
+with open('${MGW_DIR}/project.json') as f:
+    project = json.load(f)
+
+fields = json.loads('''${DISC_FIELDS}''') if '${DISC_FIELDS}' not in ('', '{}') else {}
+
+project['project']['project_board'] = {
+    'number': int('${DISC_NUMBER}'),
+    'url': '${DISC_URL}',
+    'node_id': '${DISC_NODE_ID}',
+    'fields': fields
+}
+
+with open('${MGW_DIR}/project.json', 'w') as f:
+    json.dump(project, f, indent=2)
+
+print('project.json updated')
+PYEOF
+
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo " MGW ► EXISTING BOARD REGISTERED"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Board:    #${DISC_NUMBER} — ${DISC_URL}"
+    echo "Node ID:  ${DISC_NODE_ID}"
+    echo ""
+    if [ "$DISC_FIELDS" != "{}" ] && [ -n "$DISC_FIELDS" ]; then
+      echo "Fields registered:"
+      echo "$DISC_FIELDS" | python3 -c "
+import json,sys
+fields = json.load(sys.stdin)
+for name, data in fields.items():
+    ftype = data.get('type', '?')
+    print(f'  {name}: {data.get(\"field_id\",\"?\")} ({ftype})')
+" 2>/dev/null
+    else
+      echo "  (no custom fields found — run /mgw:board configure to add them)"
+    fi
+    echo ""
+    echo "To see board items: /mgw:board show"
+    exit 0
+  fi
+
+  echo "  No existing board found — creating new board..."
+  echo ""
+```
+
 **Get owner and repo node IDs (required for GraphQL mutations):**
 
 ```bash

package/commands/milestone.md

@@ -414,6 +414,7 @@ Track state for progress table:
 ```bash
 COMPLETED_ISSUES=()
 FAILED_ISSUES=()
+FAILED_ISSUES_WITH_CLASS=()  # Entries: "issue_number:failure_class" for results display
 BLOCKED_ISSUES=()
 SKIPPED_ISSUES=()
 ISSUES_RUN=0
@@ -620,9 +621,30 @@ COMMENTEOF
     echo "  ✓ #${ISSUE_NUMBER} — PR #${PR_NUMBER} created"
 
   else
-    # Failure — post failure comment
+    # Failure — read failure_class from active issue state, then post failure comment
     FAILED_ISSUES+=("$ISSUE_NUMBER")
 
+    # Read failure_class and dead_letter from the active issue state file
+    ISSUE_FAILURE_CLASS=$(node -e "
+const { loadActiveIssue } = require('./lib/state.cjs');
+const state = loadActiveIssue(${ISSUE_NUMBER});
+console.log((state && state.last_failure_class) ? state.last_failure_class : 'unknown');
+" 2>/dev/null || echo "unknown")
+
+    ISSUE_DEAD_LETTER=$(node -e "
+const { loadActiveIssue } = require('./lib/state.cjs');
+const state = loadActiveIssue(${ISSUE_NUMBER});
+console.log(state && state.dead_letter === true ? 'true' : 'false');
+" 2>/dev/null || echo "false")
+
+    ISSUE_RETRY_COUNT=$(node -e "
+const { loadActiveIssue } = require('./lib/state.cjs');
+const state = loadActiveIssue(${ISSUE_NUMBER});
+console.log((state && typeof state.retry_count === 'number') ? state.retry_count : 0);
+" 2>/dev/null || echo "0")
+
+    FAILED_ISSUES_WITH_CLASS+=("${ISSUE_NUMBER}:${ISSUE_FAILURE_CLASS}")
+
     FAIL_BODY=$(cat <<COMMENTEOF
 > **MGW** · \`pipeline-failed\` · ${DONE_TIMESTAMP}
 > Milestone: ${MILESTONE_NAME} | Phase ${PHASE_NUM}: ${PHASE_NAME}
@@ -630,16 +652,22 @@ COMMENTEOF
 ### Pipeline Failed
 
 Issue #${ISSUE_NUMBER} did not produce a PR.
-Check the execution log for details.
+
+| | |
+|---|---|
+| **Failure class** | \`${ISSUE_FAILURE_CLASS}\` |
+| **Retries attempted** | ${ISSUE_RETRY_COUNT} of 3 |
+| **Dead-lettered** | ${ISSUE_DEAD_LETTER} |
 
 Dependents of this issue will be skipped.
+To retry after resolving root cause: \`/mgw:run ${ISSUE_NUMBER} --retry\`
 COMMENTEOF
 )
 
     gh issue comment ${ISSUE_NUMBER} --body "$FAIL_BODY" 2>/dev/null || true
     gh issue edit ${ISSUE_NUMBER} --add-label "pipeline-failed" 2>/dev/null || true
     gh label create "pipeline-failed" --description "Pipeline execution failed" --color "d73a4a" --force 2>/dev/null || true
-    echo "  ✗ #${ISSUE_NUMBER} — Failed (no PR created)"
+    echo "  ✗ #${ISSUE_NUMBER} — Failed (class: ${ISSUE_FAILURE_CLASS}, no PR created)"
   fi
 
   # Update project.json checkpoint (MLST-05)
@@ -684,16 +712,19 @@ Every comment posted during milestone orchestration includes:
 <details>
 <summary>Milestone Progress ({done}/{total} complete)</summary>
 
-| # | Issue | Status | PR | Stage |
-|---|-------|--------|----|-------|
-| N | title | ✓ Done | #PR | done |
-| M | title | ✗ Failed | — | failed |
-| K | title | ○ Pending | — | new |
-| J | title | ◆ Running | — | executing |
-| L | title | ⊘ Blocked | — | blocked-by:#N |
+| # | Issue | Status | PR | Failure Class |
+|---|-------|--------|----|---------------|
+| N | title | ✓ Done | #PR | — |
+| M | title | ✗ Failed | — | `permanent` |
+| K | title | ○ Pending | — | — |
+| J | title | ◆ Running | — | — |
+| L | title | ⊘ Blocked | — | — |
 
 </details>
 ```
+
+The **Failure Class** column surfaces `last_failure_class` from the active issue state file.
+Values: `transient` (retried and exhausted), `permanent` (unrecoverable), `needs-info` (ambiguous issue), `unknown` (no state file or pre-retry issue), `—` (not failed).
 </step>
 
 <step name="post_loop">
@@ -793,9 +824,18 @@ writeProjectState(state);
 
 5. Milestone mapping verification:
 
-After advancing to the next milestone, check its GSD linkage:
+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
+and ROADMAP.md) alongside the project.json milestone map:
 
 ```bash
+# Read current GSD state from .planning/ via the adapter
+GSD_STATE=$(node -e "
+const { getGsdState } = require('./lib/gsd-adapter.cjs');
+const state = getGsdState();
+console.log(JSON.stringify(state));
+" 2>/dev/null || echo "null")
+
 NEXT_MILESTONE_CHECK=$(node -e "
 const { loadProjectState, resolveActiveMilestoneIndex } = require('./lib/state.cjs');
 const state = loadProjectState();
@@ -906,6 +946,23 @@ Draft release created: ${RELEASE_TAG}
 
 **If some issues failed:**
 
+Build failure class lookup from `FAILED_ISSUES_WITH_CLASS` array for display:
+```bash
+# Build failure class map: { issue_number → failure_class }
+FAILURE_CLASS_MAP=$(python3 -c "
+import json, sys
+
+entries = '${FAILED_ISSUES_WITH_CLASS[@]}'.split()
+result = {}
+for entry in entries:
+    if ':' in entry:
+        num, cls = entry.split(':', 1)
+        result[num] = cls
+print(json.dumps(result))
+" 2>/dev/null || echo "{}")
+```
+
+Display results table including failure_class for each failed issue:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MGW ► MILESTONE ${MILESTONE_NUM} INCOMPLETE
@@ -913,15 +970,78 @@ Draft release created: ${RELEASE_TAG}
 
 ${MILESTONE_NAME}
 
-| # | Issue | Status | PR |
-|---|-------|--------|----|
-${results_table}
+| # | Issue | Status | PR | Failure Class |
+|---|-------|--------|----|---------------|
+${results_table_with_failure_class}
 
 Completed: ${TOTAL_DONE}/${TOTAL_ISSUES}
 Failed: ${TOTAL_FAILED}
 Blocked: ${TOTAL_BLOCKED}
+```
+
+For each failed issue, present recovery options:
+```bash
+for ENTRY in "${FAILED_ISSUES_WITH_CLASS[@]}"; do
+  FAIL_NUM=$(echo "$ENTRY" | cut -d':' -f1)
+  FAIL_CLASS=$(echo "$ENTRY" | cut -d':' -f2)
+
+  echo ""
+  echo "  Failed: #${FAIL_NUM} (class: ${FAIL_CLASS})"
+  AskUserQuestion(
+    header: "Recovery — Issue #${FAIL_NUM}",
+    question: "Issue #${FAIL_NUM} failed (failure class: ${FAIL_CLASS}). What would you like to do?",
+    options: [
+      {
+        label: "Retry",
+        description: "Reset retry state via resetRetryState() and re-run /mgw:run #${FAIL_NUM} --retry"
+      },
+      {
+        label: "Skip",
+        description: "Mark as skipped and continue to next issue (dependents will remain blocked)"
+      },
+      {
+        label: "Abort",
+        description: "Stop milestone recovery here"
+      }
+    ]
+  )
 
-Milestone NOT closed. Resolve failures and re-run:
+  case "$RECOVERY_CHOICE" in
+    Retry)
+      # Call resetRetryState() to clear retry_count, last_failure_class, dead_letter
+      node -e "
+const { resetRetryState } = require('./lib/retry.cjs');
+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('${FAIL_NUM}-') && f.endsWith('.json'));
+if (!file) { console.error('No state file for #${FAIL_NUM}'); process.exit(1); }
+const filePath = path.join(activeDir, file);
+const state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+const reset = resetRetryState(state);
+reset.pipeline_stage = 'triaged';
+fs.writeFileSync(filePath, JSON.stringify(reset, null, 2));
+console.log('Retry state cleared for #${FAIL_NUM}');
+"
+      # Remove pipeline-failed label before re-run
+      gh issue edit ${FAIL_NUM} --remove-label "pipeline-failed" 2>/dev/null || true
+      # Re-run the pipeline for this issue
+      /mgw:run ${FAIL_NUM} --retry
+      ;;
+    Skip)
+      echo "  ⊘ #${FAIL_NUM} — Skipped (will not retry)"
+      ;;
+    Abort)
+      echo "Milestone recovery aborted at #${FAIL_NUM}."
+      break
+      ;;
+  esac
+done
+```
+
+After recovery loop:
+```
+Milestone NOT closed. Re-run after resolving remaining failures:
   /mgw:milestone ${MILESTONE_NUM}
 ```
 
@@ -943,6 +1063,9 @@ gh issue comment ${FIRST_ISSUE_NUMBER} --body "$FINAL_RESULTS_COMMENT"
 - [ ] Sequential execution via /mgw:run Task() delegation (MLST-01)
 - [ ] Per-issue checkpoint to project.json after completion (MLST-05)
 - [ ] Failure handling: skip failed, label, comment, block dependents
+- [ ] failure_class surfaced in results table and failure comment for each failed issue
+- [ ] Retry option calls resetRetryState() then re-invokes /mgw:run --retry for failed issues
+- [ ] FAILED_ISSUES_WITH_CLASS tracks "number:class" for display in results table
 - [ ] Progress table in every GitHub comment
 - [ ] Milestone close + draft release on full completion
 - [ ] current_milestone pointer advanced on completion