@snipcodeit/mgw 0.1.2 → 0.2.0

package/commands/init.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:init
-description: Bootstrap current repo for MGW integration — creates .mgw/ state, GitHub templates, gitignore entries
-argument-hint: ""
+description: Bootstrap current repo for MGW integration — creates .mgw/ state, GitHub templates, gitignore entries, installs shell completions, and runs config wizard
+argument-hint: "[--no-config]"
 allowed-tools:
   - Bash
   - Read
@@ -12,8 +12,9 @@ allowed-tools:
 
 <objective>
 One-time setup for a repo to work with MGW. Creates the .mgw/ state directory,
-GitHub issue/PR templates, and ensures gitignore entries. Safe to re-run — skips
-anything that already exists.
+GitHub issue/PR templates, ensures gitignore entries, and runs an interactive
+config wizard for first-time setup preferences. Safe to re-run — skips anything
+that already exists. Pass --no-config to skip the wizard.
 </objective>
 
 <execution_context>
@@ -213,6 +214,109 @@ gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder com
 `--force` updates existing labels without error.
 </step>
 
+<step name="install_completions">
+**Offer to install shell completions (opt-in):**
+
+Locate the completions directory bundled with the MGW package:
+```bash
+MGW_PKG_DIR=$(node -e "const path = require('path'); console.log(path.resolve(__dirname, '..', '..'))" 2>/dev/null || echo "")
+COMPLETIONS_DIR="${MGW_PKG_DIR}/completions"
+```
+
+If completions are not found (package not globally installed or completions dir absent) → skip silently, note "Shell completions not available (mgw not installed globally)" in report.
+
+If completions are found, detect the user's shell and determine the install target:
+```bash
+CURRENT_SHELL=$(basename "${SHELL:-}")
+```
+
+Shell → target directory mapping:
+- `bash` → `~/.local/share/bash-completion/completions/` (source file: `mgw.bash`)
+- `zsh`  → `~/.zsh/completions/` (source file: `mgw.zsh`)
+- `fish` → `~/.config/fish/completions/` (source file: `mgw.fish`)
+
+If shell is unrecognized or `SHELL` is unset → show all three install commands and skip auto-install.
+
+**Interactive mode (default):** Ask the user:
+```
+Shell completions are available for ${CURRENT_SHELL}.
+
+Install to ${COMPLETION_TARGET_DIR}? [Y/n]
+```
+
+If the user answers yes (or presses Enter for the default):
+```bash
+mkdir -p "${COMPLETION_TARGET_DIR}"
+cp "${COMPLETIONS_DIR}/mgw.${SHELL_EXT}" "${COMPLETION_TARGET_DIR}/mgw.${SHELL_EXT}"
+```
+
+Then show the source/activation line appropriate for the shell:
+- bash: `# Reload with: source ~/.local/share/bash-completion/completions/mgw.bash`
+  (or add to ~/.bashrc: `source ~/.local/share/bash-completion/completions/mgw.bash`)
+- zsh: Add to ~/.zshrc (required — ~/.zsh/completions is not in default $fpath):
+  ```
+  fpath=(~/.zsh/completions $fpath)
+  autoload -Uz compinit
+  compinit
+  ```
+  Then reload: `source ~/.zshrc`
+- fish: `# Completions loaded automatically from ~/.config/fish/completions/`
+
+If user answers no → skip, note "Shell completions: skipped" in report.
+
+If the completion file already exists at the target → overwrite (idempotent re-run).
+
+**Non-interactive mode** (stdin is not a TTY): Skip the prompt entirely, print the install command as a hint:
+```
+  Shell completions available. Install manually:
+    cp ${COMPLETIONS_DIR}/mgw.${SHELL_EXT} ${COMPLETION_TARGET_DIR}/mgw.${SHELL_EXT}
+```
+</step>
+
+<step name="run_config_wizard">
+**Run interactive config wizard for first-time setup (skip if --no-config or config already exists):**
+
+Check whether the wizard should run:
+```bash
+# Skip if --no-config flag is present
+# Skip if stdin is not a TTY (CI/piped context)
+# Skip if .mgw/config.json already exists
+```
+
+Use `lib/config-wizard.cjs` to determine and execute:
+```javascript
+const { runWizard, shouldRunWizard } = require('./lib/config-wizard.cjs');
+const mgwDir = path.join(REPO_ROOT, '.mgw');
+
+if (shouldRunWizard(mgwDir, process.argv)) {
+  await runWizard(mgwDir);
+} else if (fs.existsSync(path.join(mgwDir, 'config.json'))) {
+  // report: ".mgw/config.json   exists, skipping wizard"
+} else {
+  // report: ".mgw/config.json   skipped (--no-config)"
+}
+```
+
+The wizard asks the user four questions in order:
+1. **GitHub username** — auto-detected from `gh api user -q .login`; user may accept or override
+2. **Default issue state filter** — `open` (default) or `all`
+3. **Default issue limit** — `10`, `25` (default), or `50`
+4. **Default assignee filter** — `me` (default) or `all`
+
+Answers are written to `${REPO_ROOT}/.mgw/config.json`:
+```json
+{
+  "github_username": "...",
+  "default_issue_state": "open",
+  "default_issue_limit": 25,
+  "default_assignee": "me",
+  "created_at": "<ISO timestamp>"
+}
+```
+
+If the wizard errors or is interrupted, report the failure but do not abort the overall init — config is optional.
+</step>
+
 <step name="report">
 **Report setup status:**
 
@@ -223,11 +327,13 @@ gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder com
 
   .mgw/                  ${created|exists}
   .mgw/cross-refs.json   ${created|exists}
+  .mgw/config.json       ${written|exists|skipped}
   .gitignore entries     ${added|exists}
   Issue templates        ${created|exists}
   PR template            ${created|exists}
   GitHub labels          synced
   MGW pipeline labels    synced (7 labels)
+  Shell completions      ${installed (bash|zsh|fish)|skipped|not available}
 
 Ready to use:
   /mgw:issues            Browse issues
@@ -242,9 +348,13 @@ Ready to use:
 - [ ] .mgw/ directory structure created
 - [ ] .mgw/ and .worktrees/ in .gitignore
 - [ ] cross-refs.json initialized
+- [ ] Config wizard run (or skipped via --no-config / pre-existing config.json)
+- [ ] .mgw/config.json written with user preferences (unless skipped)
 - [ ] Issue templates created (bug + enhancement)
 - [ ] PR template created
 - [ ] GitHub labels ensured (bug, enhancement)
 - [ ] MGW pipeline labels ensured (7 mgw:* labels)
-- [ ] Setup report shown
+- [ ] Shell completion install offered (interactive) or hint printed (non-interactive)
+- [ ] Completion install skipped gracefully if completions dir not found
+- [ ] Setup report shown with completion status line
 </success_criteria>

package/commands/issue.md

@@ -287,16 +287,15 @@ MISSING_FIELDS_LIST = gate_result.missing_fields formatted as "- ${field}" list
 ```
 
 Use the "Gate Blocked Comment" template from @~/.claude/commands/mgw/workflows/github.md.
-Post comment and apply label:
+Post comment and apply label using the highest-severity blocker (security > detail > validity):
 ```bash
-# Use remove_mgw_labels_and_apply pattern from github.md
-# For validity failures:
-#   pipeline_stage = "needs-info", label = "mgw:needs-info"
-# For security failures:
-#   pipeline_stage = "needs-security-review", label = "mgw:needs-security-review"
-# For detail failures:
-#   pipeline_stage = "needs-info", label = "mgw:needs-info"
-# If multiple blockers, use the highest-severity label (security > detail > validity)
+# For validity or detail failures:
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:needs-info"
+
+# For security failures (highest severity — takes precedence over needs-info):
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:needs-security-review"
+
+# If multiple blockers, apply security label if security gate failed; otherwise needs-info.
 ```
 
 **If gates passed (gate_result.status == "passed"):**
@@ -316,7 +315,7 @@ ROUTE_REASONING = triage reasoning
 
 Post comment and apply label:
 ```bash
-gh issue edit ${ISSUE_NUMBER} --add-label "mgw:triaged" 2>/dev/null
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:triaged"
 ```
 </step>
 

package/commands/issues.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:issues
 description: List and filter GitHub issues, pick one to triage
-argument-hint: "[--label <label>] [--milestone <name>] [--assignee <user>] [--state open|closed|all]"
+argument-hint: "[--label <label>] [--milestone <name>] [--assignee <user>] [--state open|closed|all] [--search <query>]"
 allowed-tools:
   - Bash
   - Read
@@ -14,6 +14,10 @@ Browse GitHub issues for the current repo. Presents a scannable table filtered b
 assignment (defaults to @me), labels, milestone, or state. Pick an issue to route
 into triage via /mgw:issue.
 
+This is the Claude Code slash-command variant (table + AskUserQuestion). When running
+from the CLI (`mgw issues`), an interactive TUI browser launches instead — see
+`docs/TUI-DESIGN.md` and `lib/tui/index.cjs` for the TUI implementation.
+
 No side effects — read-only GitHub access. Safe to run anytime.
 </objective>
 
@@ -107,3 +111,61 @@ If invalid → re-prompt.
 - [ ] User can pick an issue number
 - [ ] Routes to /mgw:issue <number>
 </success_criteria>
+
+## TUI Mode (CLI only)
+
+When `mgw issues` runs from the CLI entry point (`bin/mgw.cjs`) in an interactive
+terminal, it launches a full TUI browser instead of a static table.
+
+**Entry point:** `lib/tui/index.cjs` — `createIssuesBrowser(options)`
+
+**CLI options:**
+```
+mgw issues [options]
+  -l, --label <label>        Filter by label
+  -m, --milestone <name>     Filter by milestone
+  -a, --assignee <user>      Assignee filter (default: @me, 'all' = no filter)
+  -s, --search <query>       Pre-populate the fuzzy search input
+  --state <state>            Issue state: open|closed|all (default: open)
+  --limit <n>                Max issues to load (default: 50)
+```
+
+**TUI keyboard shortcuts:**
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Scroll down |
+| `k` / `↑` | Scroll up |
+| `/` | Focus search input |
+| `Enter` | Select issue → prints `#N — Title` and exits |
+| `q` / `Esc` | Quit |
+| `Tab` | Cycle focus (list → detail → filter) |
+| `g` / `Home` | Jump to top |
+| `G` / `End` | Jump to bottom |
+| `?` | Toggle keyboard help |
+
+**Non-interactive fallback:**
+When stdout is not a TTY (piped, CI, `MGW_NO_TUI=1`), the static table is printed
+to stdout. Pipe-friendly — no ANSI codes, no interactive elements.
+
+```bash
+mgw issues | grep "auth"
+```
+
+**Implementation modules:**
+```
+lib/tui/
+  index.cjs      — createIssuesBrowser(options) — entry point
+  search.cjs     — FuzzySearch class — pure, no UI dependency
+  keyboard.cjs   — KeyboardHandler (EventEmitter)
+  renderer.cjs   — createRenderer() — blessed/neo-blessed adapter
+  graceful.cjs   — isInteractive(), renderStaticTable()
+```
+
+**Design document:** `docs/TUI-DESIGN.md` — library selection rationale, wireframe, full interface contracts.
+
+**Rendering library:** `neo-blessed` (optional dependency). Renderer is swappable via `lib/tui/renderer.cjs`.
+
+**Slash command vs CLI:**
+This slash command (`/mgw:issues`) uses the static table + `AskUserQuestion` pattern
+because Claude Code sessions don't have raw TTY access. The TUI is CLI-only (`mgw issues`).
+Both paths route to `/mgw:issue <number>` for triage.

package/commands/milestone.md

@@ -141,6 +141,28 @@ Display:
 Issues: ${TOTAL_ISSUES}
 Mode: ${INTERACTIVE ? "Interactive" : "Autonomous"}
 ```
+
+Then print the initial milestone progress bar (0 done, TOTAL_ISSUES total):
+```bash
+ISSUES_WITH_STAGES=$(echo "$ISSUES_JSON" | python3 -c "
+import json,sys
+issues = json.load(sys.stdin)
+result = [{'number': i['github_number'], 'pipeline_stage': i.get('pipeline_stage', 'new')} for i in issues]
+print(json.dumps(result))
+")
+
+node -e "
+const { printMilestoneProgress } = require('./lib/progress.cjs');
+const issues = JSON.parse(process.env.ISSUES_WITH_STAGES || '[]');
+const doneCount = issues.filter(i => i.pipeline_stage === 'done' || i.pipeline_stage === 'pr-created').length;
+printMilestoneProgress({
+  done: doneCount,
+  total: issues.length,
+  label: process.env.MILESTONE_NAME,
+  issues
+});
+" MILESTONE_NAME="$MILESTONE_NAME" ISSUES_WITH_STAGES="$ISSUES_WITH_STAGES"
+```
 </step>
 
 <step name="resolve_execution_order">
@@ -417,6 +439,7 @@ FAILED_ISSUES=()
 FAILED_ISSUES_WITH_CLASS=()  # Entries: "issue_number:failure_class" for results display
 BLOCKED_ISSUES=()
 SKIPPED_ISSUES=()
+LABEL_DRIFT_ISSUES=()         # Issues where label reconciliation detected drift
 ISSUES_RUN=0
 ```
 
@@ -562,6 +585,43 @@ COMMENTEOF
     description="Run pipeline for #${ISSUE_NUMBER}"
   )
 
+  # ── POST-WORK: Post-subagent label verification ──
+  # Read the pipeline_stage from the issue's active state file after Task() returns
+  ISSUE_STAGE=$(node -e "
+const { loadActiveIssue } = require('./lib/state.cjs');
+const state = loadActiveIssue(${ISSUE_NUMBER});
+console.log((state && state.pipeline_stage) ? state.pipeline_stage : 'unknown');
+" 2>/dev/null || echo "unknown")
+
+  # Determine the expected MGW label for this pipeline stage
+  EXPECTED_LABEL=$(python3 -c "
+stage_to_label = {
+  'done': '',
+  'pr-created': '',
+  'verifying': 'mgw:in-progress',
+  'executing': 'mgw:in-progress',
+  'planning': 'mgw:in-progress',
+  'blocked': 'mgw:blocked',
+  'failed': '',
+}
+print(stage_to_label.get('${ISSUE_STAGE}', ''))
+")
+
+  # Compare expected label against live GitHub labels
+  LIVE_LABELS=$(gh issue view ${ISSUE_NUMBER} --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+  if [ -n "$EXPECTED_LABEL" ] && ! echo "$LIVE_LABELS" | grep -q "$EXPECTED_LABEL"; then
+    echo "MGW WARNING: label drift on #${ISSUE_NUMBER} — expected $EXPECTED_LABEL, live: $LIVE_LABELS" >&2
+    LABEL_DRIFT="drift"
+  else
+    LABEL_DRIFT="ok"
+  fi
+
+  # Track drifted issues for milestone summary
+  if [ "$LABEL_DRIFT" = "drift" ]; then
+    LABEL_DRIFT_ISSUES+=("$ISSUE_NUMBER")
+  fi
+
   # ── POST-WORK: Detect result and post completion comment ──
   # Check if PR was created by looking for state file or PR
   PR_NUMBER=$(gh pr list --head "issue/${ISSUE_NUMBER}-*" --json number -q '.[0].number' 2>/dev/null || echo "")
@@ -685,6 +745,27 @@ writeProjectState(state);
 
   ISSUES_RUN=$((ISSUES_RUN + 1))
 
+  # Update and print milestone progress bar after each issue completes
+  ISSUES_WITH_STAGES=$(node -e "
+const { loadProjectState, resolveActiveMilestoneIndex } = require('./lib/state.cjs');
+const state = loadProjectState();
+const idx = resolveActiveMilestoneIndex(state);
+if (idx < 0) { console.log('[]'); process.exit(0); }
+const issues = state.milestones[idx].issues || [];
+console.log(JSON.stringify(issues.map(i => ({ number: i.github_number, pipeline_stage: i.pipeline_stage || 'new' }))));
+" 2>/dev/null || echo "[]")
+
+  node -e "
+const { printMilestoneProgress } = require('./lib/progress.cjs');
+const issues = JSON.parse(process.env.ISSUES_WITH_STAGES || '[]');
+const doneCount = issues.filter(i => i.pipeline_stage === 'done' || i.pipeline_stage === 'pr-created').length;
+printMilestoneProgress({
+  done: doneCount,
+  total: issues.length,
+  issues
+});
+" ISSUES_WITH_STAGES="$ISSUES_WITH_STAGES"
+
   # If --interactive: pause between issues
   if [ "$INTERACTIVE" = true ]; then
     AskUserQuestion(
@@ -712,18 +793,19 @@ Every comment posted during milestone orchestration includes:
 <details>
 <summary>Milestone Progress ({done}/{total} complete)</summary>
 
-| # | Issue | Status | PR | Failure Class |
-|---|-------|--------|----|---------------|
-| N | title | ✓ Done | #PR | — |
-| M | title | ✗ Failed | — | `permanent` |
-| K | title | ○ Pending | — | — |
-| J | title | ◆ Running | — | — |
-| L | title | ⊘ Blocked | — | — |
+| # | Issue | Status | PR | Failure Class | Label Drift |
+|---|-------|--------|----|---------------|-------------|
+| N | title | ✓ Done | #PR | — | ok |
+| M | title | ✗ Failed | — | `permanent` | — |
+| K | title | ○ Pending | — | — | — |
+| J | title | ◆ Running | — | — | ok |
+| L | title | ⊘ Blocked | — | — | — |
 
 </details>
 ```
 
 The **Failure Class** column surfaces `last_failure_class` from the active issue state file.
+The **Label Drift** column shows the result of post-subagent label reconciliation: `ok` (labels matched expected), `drift` (label mismatch detected — MGW WARNING logged), or `—` (not checked / issue not run).
 Values: `transient` (retried and exhausted), `permanent` (unrecoverable), `needs-info` (ambiguous issue), `unknown` (no state file or pre-retry issue), `—` (not failed).
 </step>
 
@@ -1067,6 +1149,9 @@ gh issue comment ${FIRST_ISSUE_NUMBER} --body "$FINAL_RESULTS_COMMENT"
 - [ ] 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
+- [ ] Post-subagent label reconciliation run per issue after Task() returns
+- [ ] LABEL_DRIFT tracked per issue (ok/drift) and shown in progress table Label Drift column
+- [ ] Label drift issues logged as MGW WARNING to stderr
 - [ ] Milestone close + draft release on full completion
 - [ ] current_milestone pointer advanced on completion
 - [ ] --interactive flag pauses between issues

package/commands/run.md

@@ -418,9 +418,7 @@ Add cross-ref (at `${REPO_ROOT}/.mgw/cross-refs.json`): issue → branch.
 
 **Apply in-progress label:**
 ```bash
-# Use remove_mgw_labels_and_apply pattern from github.md
-gh issue edit ${ISSUE_NUMBER} --remove-label "mgw:triaged" 2>/dev/null
-gh issue edit ${ISSUE_NUMBER} --add-label "mgw:in-progress" 2>/dev/null
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:in-progress"
 ```
 
 **PATH CONVENTION for remaining steps:**
@@ -531,8 +529,7 @@ fi
 
 **When blocking comment detected — apply label:**
 ```bash
-gh issue edit ${ISSUE_NUMBER} --remove-label "mgw:in-progress" 2>/dev/null
-gh issue edit ${ISSUE_NUMBER} --add-label "mgw:blocked" 2>/dev/null
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:blocked"
 ```
 
 If no new comments detected, continue normally.
@@ -949,8 +946,7 @@ PHASE_COUNT="TBD (determined by roadmapper)"
 
 Set pipeline_stage to "discussing" and apply "mgw:discussing" label:
 ```bash
-gh issue edit ${ISSUE_NUMBER} --remove-label "mgw:in-progress" 2>/dev/null
-gh issue edit ${ISSUE_NUMBER} --add-label "mgw:discussing" 2>/dev/null
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:discussing"
 ```
 
 Present to user:
@@ -1461,9 +1457,38 @@ rmdir "${REPO_ROOT}/.worktrees/issue" 2>/dev/null
 rmdir "${REPO_ROOT}/.worktrees" 2>/dev/null
 ```
 
-Remove in-progress label at completion:
+Clear MGW labels at completion:
 ```bash
-gh issue edit ${ISSUE_NUMBER} --remove-label "mgw:in-progress" 2>/dev/null
+# Pass empty string — removes all mgw: labels without applying a new one
+remove_mgw_labels_and_apply ${ISSUE_NUMBER} ""
+```
+
+Post-completion label reconciliation:
+```bash
+# Post-completion label reconciliation — verify no stray MGW labels remain
+LIVE_LABELS=$(gh issue view ${ISSUE_NUMBER} --json labels --jq '[.labels[].name]' 2>/dev/null || echo "[]")
+STRAY_MGW=$(echo "$LIVE_LABELS" | python3 -c "
+import json, sys
+labels = json.load(sys.stdin)
+stray = [l for l in labels if l.startswith('mgw:')]
+print('\n'.join(stray))
+" 2>/dev/null || echo "")
+
+if [ -n "$STRAY_MGW" ]; then
+  echo "MGW WARNING: unexpected MGW labels still on issue after completion: $STRAY_MGW" >&2
+fi
+
+# Sync live labels back to .mgw/active state file
+LIVE_LABELS_LIST=$(gh issue view ${ISSUE_NUMBER} --json labels --jq '[.labels[].name]' 2>/dev/null || echo "[]")
+# Update labels field in ${REPO_ROOT}/.mgw/active/${STATE_FILE} using python3 json patch:
+python3 -c "
+import json, sys
+path = sys.argv[1]
+live = json.loads(sys.argv[2])
+with open(path) as f: state = json.load(f)
+state['labels'] = live
+with open(path, 'w') as f: json.dump(state, f, indent=2)
+" "${REPO_ROOT}/.mgw/active/${STATE_FILE}" "$LIVE_LABELS_LIST" 2>/dev/null || true
 ```
 
 Extract one-liner summary for concise comment:

package/commands/status.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:status
 description: Project status dashboard — milestone progress, issue pipeline stages, open PRs
-argument-hint: "[milestone_number] [--json] [--board]"
+argument-hint: "[milestone_number] [--json] [--board] [--watch [--interval N]]"
 allowed-tools:
   - Bash
   - Read
@@ -13,6 +13,11 @@ pipeline stages, open PRs, and next milestone preview. Pure read-only — no sta
 mutations, no agent spawns, no GitHub writes.
 
 Falls back gracefully when no project.json exists (lists active issues only via GitHub API).
+
+When `--watch` is passed, enters live-refresh mode: clears the terminal and redraws the
+dashboard every N seconds (default 30). Displays a "Last refreshed" timestamp. User exits
+by pressing 'q' or Ctrl+C. If both `--watch` and `--json` are supplied, print an error and
+exit 1.
 </objective>
 
 <execution_context>
@@ -35,11 +40,21 @@ Repo detected via: gh repo view --json nameWithOwner -q .nameWithOwner
 MILESTONE_NUM=""
 JSON_OUTPUT=false
 OPEN_BOARD=false
+WATCH_MODE=false
+WATCH_INTERVAL=30
+NEXT_IS_INTERVAL=false
 
 for ARG in $ARGUMENTS; do
+  if [ "$NEXT_IS_INTERVAL" = true ]; then
+    WATCH_INTERVAL="$ARG"
+    NEXT_IS_INTERVAL=false
+    continue
+  fi
   case "$ARG" in
     --json) JSON_OUTPUT=true ;;
     --board) OPEN_BOARD=true ;;
+    --watch) WATCH_MODE=true ;;
+    --interval) NEXT_IS_INTERVAL=true ;;
     [0-9]*) MILESTONE_NUM="$ARG" ;;
   esac
 done
@@ -418,6 +433,77 @@ Rendering rules:
 - If no open PRs matched to milestone, show "No open PRs for this milestone."
 - If no next milestone, show "No more milestones planned."
 - If `TARGET_MILESTONE != CURRENT_MILESTONE`, add "(viewing milestone ${TARGET_MILESTONE})" to header
+- In watch mode, append the footer: `[ Refreshing every ${WATCH_INTERVAL}s — last refreshed HH:MM:SS | press q to quit ]`
+</step>
+
+<step name="watch_mode">
+**If --watch flag: enter live-refresh loop:**
+
+`--watch` is incompatible with `--json`. If both are passed, print an error and exit 1.
+
+The watch loop is implemented as a Node.js one-shot script executed via `node -e` (or saved
+to a temp file). It wraps the full dashboard render cycle with `setInterval`, clears the
+terminal before each redraw, and uses `process.stdin.setRawMode(true)` to detect a 'q'
+keypress for clean exit.
+
+```javascript
+// watch-mode runner (pseudocode — shows the pattern)
+const { execSync } = require('child_process');
+const INTERVAL = parseInt(process.env.WATCH_INTERVAL || '30', 10) * 1000;
+const REPO_ROOT = process.env.REPO_ROOT;
+
+function renderDashboard() {
+  // Re-run all data collection and dashboard build steps synchronously
+  // (same logic as the non-watch single-shot path above, but called in a loop)
+  const output = buildDashboardOutput();  // all the python/gh calls assembled into a string
+  // Implementation note: buildDashboardOutput() is a pseudocode placeholder.
+  // The executor must refactor the full `display_dashboard` step into a reusable
+  // function that collects all GitHub and project.json data and returns the rendered
+  // dashboard string, then call it from both the single-shot path and the watch loop.
+  const now = new Date().toLocaleTimeString();
+  process.stdout.write('\x1B[2J\x1B[H');  // clear terminal, cursor home
+  process.stdout.write(output);
+  process.stdout.write(`\n[ Refreshing every ${INTERVAL / 1000}s — last refreshed ${now} | press q to quit ]\n`);
+}
+
+// Initial render
+renderDashboard();
+
+// Poll on interval
+const timer = setInterval(renderDashboard, INTERVAL);
+
+// Detect 'q' to exit
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (key) => {
+    if (key === 'q' || key === '\u0003') {  // 'q' or Ctrl+C
+      clearInterval(timer);
+      process.stdin.setRawMode(false);
+      process.stdout.write('\nWatch mode exited.\n');
+      process.exit(0);
+    }
+  });
+}
+```
+
+Implementation notes for the executor:
+- The watch runner re-executes the full data fetch on each interval tick (re-reads
+  project.json, re-calls `gh pr list`, etc.) so the display reflects live GitHub state.
+- `process.stdout.write('\x1B[2J\x1B[H')` clears the screen without spawning `clear`.
+- The footer line shows "last refreshed HH:MM:SS" only. No countdown timer.
+- SIGINT (Ctrl+C) should also trigger clean exit — the `'\u0003'` check above handles it,
+  but also register `process.on('SIGINT', ...)` as a fallback when `setRawMode` is false
+  (non-TTY or piped stdin).
+- If `--watch` and `--json` are both supplied, print the error message and exit 1 before
+  entering the watch loop.
+
+If both flags are supplied, emit:
+```
+Error: --watch and --json cannot be used together.
+```
+and exit 1.
 </step>
 
 <step name="json_output">
@@ -523,4 +609,12 @@ The JSON structure:
 - [ ] Velocity computed from .mgw/active/ and .mgw/completed/ file mtimes
 - [ ] --json output includes board_url and milestone.health object
 - [ ] Board URL line omitted when board_url is not set in project.json
+- [ ] --watch flag enters live-refresh loop, refreshing every N seconds (default 30)
+- [ ] --interval N overrides the default 30s refresh interval
+- [ ] Watch mode clears terminal before each redraw
+- [ ] Watch mode footer shows last refresh time
+- [ ] 'q' keypress exits watch mode cleanly (stdin raw mode)
+- [ ] Ctrl+C (SIGINT) exits watch mode cleanly
+- [ ] --watch and --json are mutually exclusive — error + exit 1 if both supplied
+- [ ] Watch mode re-fetches all data on each tick (live GitHub state)
 </success_criteria>