feat(status): add --watch flag and live-refresh panel

[snipcodeit]

Summary

• Adds --watch flag to mgw:status that enters a live-refresh loop, redrawing the dashboard every N seconds
• Adds --interval N flag to configure the refresh interval (default 30s)
• Watch loop uses Node.js setInterval + terminal clear (\x1B[2J\x1B[H) for clean redraw; each tick re-fetches all data from GitHub and project.json for live accuracy
• Exits cleanly on q keypress (stdin raw mode) or Ctrl+C (SIGINT); --watch and --json are mutually exclusive

Closes #122

Milestone Context

• Milestone: v4 — Interactive CLI & TUI
• Phase: 28 — Pipeline Progress Indicators and Live Status
• Issue: 6 of 9 in milestone

Changes

• commands/status.md — argument-hint updated; --watch/--interval flags added to parse_arguments step; watch_mode step added after display_dashboard with Node.js polling loop pseudocode, implementation notes, and mutual-exclusivity guard; success_criteria extended with 8 new watch-mode criteria

Test Plan

• Run mgw:status without --watch — verify output unchanged (no regression)
• Run mgw:status --watch — verify terminal clears and redraws every 30s, footer shows last-refresh time
• Run mgw:status --watch --interval 10 — verify refresh happens every 10s
• Press q during watch mode — verify clean exit with "Watch mode exited." message
• Press Ctrl+C during watch mode — verify clean exit
• Run mgw:status --watch --json — verify error output and exit 1
• Run mgw:status --json — verify single-shot JSON output (no watch loop)

[snipcodeit]

Review: PR #166 — --watch flag and live-refresh panel

This is a command file (pseudocode) PR — no compiled code, just spec. The specification is generally clear but has contradictory behavior for --watch + --json and the watch loop pseudocode has an unresolved placeholder.

---

🔴 Contradictory --watch + --json behavior spec

The PR has two conflicting statements about --watch --json:

In the objective block:

--watch and --json are mutually exclusive

In the watch_mode step:

--watch is silently ignored when --json is also present; --json takes precedence and produces single-shot JSON output (no loop).

In the success_criteria:

--watch and --json are mutually exclusive — error + exit 1 if both supplied

Pick one behavior and make it consistent everywhere. The error-exit behavior is preferable since it is explicit and prevents user confusion. Remove the "silently ignored" wording from the implementation notes.

---

🔴 buildDashboardOutput() is an unresolved placeholder

The watch loop pseudocode calls:

const output = buildDashboardOutput();

But buildDashboardOutput() is not defined anywhere — it is a fictional placeholder representing "all the data collection and render steps in the non-watch path." An executor reading this command file needs to understand they must duplicate or refactor all the dashboard data-collection steps into a callable function.

Add an explicit implementation note explaining this:

"The executor must extract the full display_dashboard step into a reusable function buildDashboardOutput() that returns the rendered string, then call it from both the single-shot path and the watch loop."

Without this note, the pseudocode looks like a missing import.

---

🟡 Countdown timer adds complexity for marginal value

The implementation notes say:

update next in Xs with a live countdown using a secondary setInterval (1000ms)

Then immediately hedge:

Alternatively, show only "last refreshed HH:MM:SS" without a countdown if a countdown adds excessive complexity.

The countdown is likely not worth the added complexity of a second interval. Recommend removing the countdown option and just showing "last refreshed HH:MM:SS" as the authoritative spec. Keeps the implementation simpler and the output cleaner.

---

🟡 setRawMode fallback when stdin is not a TTY

The pseudocode checks if (process.stdin.isTTY) before calling setRawMode. Good. But the fallback (non-TTY) only registers a SIGINT handler — it does not provide a way for the user to type q to exit. In non-TTY contexts (piped stdin), the only exit path is Ctrl+C/SIGINT.

Explicitly document in the success criteria: "In non-TTY mode, watch loop runs indefinitely until SIGINT."

---

✅ Good points

• The setInterval + setRawMode pattern is the correct approach
• \x1B[2J\x1B[H for terminal clear is correct and avoids spawning clear
• SIGINT registered as a fallback is good defensive practice
• --interval N override is a useful addition
• Mutual exclusivity check with --json is the right design