fix(cli): warn when squad watch receives unused message args (#703)

.changeset/watch-message-warning.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+Warn when squad watch receives unused positional arguments instead of silently ignoring them

docs/src/content/docs/features/ralph.md

@@ -208,6 +208,21 @@ This runs as a standalone local process (not inside Copilot) that:
 - Assigns @copilot to `squad:copilot` issues (if auto-assign is enabled)
 - Runs until Ctrl+C
 
+> ⚠️ **Watch mode does not route messages**
+>
+> `squad watch` is a **triage polling loop**, not a message router. Extra arguments like agent names or messages are ignored:
+>
+> ```bash
+> # ❌ This does NOT route to Nick — the message is ignored
+> squad watch --interval 5 "Nick, Run scheduled tasks"
+>
+> # ✅ To address an agent directly, use an interactive session:
+> squad
+> > Nick, Run scheduled tasks
+> ```
+>
+> To route work to a specific agent, create a GitHub issue with the appropriate `squad:{member}` label — `squad watch` will pick it up during the next poll cycle.
+
 ### Full Work Monitor Mode (`--execute`)
 
 Add `--execute` to transform Ralph from a triage bot into a full work monitor that spawns Copilot sessions and actually does the work:

docs/src/content/docs/reference/cli.md

@@ -40,7 +40,7 @@ squad init
 | `squad upgrade` | Upgrade Squad-owned files to latest version | Yes |
 | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes |
 | `squad triage` | Auto-triage issues and assign to team (primary name; `watch` is an alias) | Yes |
-| `squad triage --interval <min>` | Continuous triage (default: every 10 min) | Yes |
+| `squad triage --interval <min>` | Continuous triage (default: every 10 min). **Note:** extra args (e.g., agent messages) are ignored — triage/watch is a polling loop, not a message router | Yes |
 | `squad watch --execute` | Enable work execution (spawn Copilot to work on issues) | Yes |
 | `squad watch --monitor-teams` | Scan Teams for actionable messages each round | Yes |
 | `squad watch --monitor-email` | Scan email for alerts and action items each round | Yes |

packages/squad-cli/src/cli-entry.ts

@@ -473,8 +473,10 @@ async function main(): Promise<void> {
       if (arg.startsWith('-')) continue;
       positionalArgs.push(arg);
     }
-    if (positionalArgs.length > 0 && config.verbose) {
-      console.log(`[verbose] ⚠️ Positional args ignored by watch: "${positionalArgs.join(' ')}". Use --execute to process issues.`);
+    if (positionalArgs.length > 0) {
+      const message = positionalArgs.join(' ');
+      console.warn(`\n⚠️  Watch mode does not route messages to agents. Ignoring: "${message}"`);
+      console.warn(`   To address an agent directly, use an interactive session instead.\n`);
     }
 
     await runWatch(getSquadStartDir(), config);