feat(coordinator): compaction recovery + restraint rules + result persistence (#682 #683 #684)

[diberry]

Batches three related coordinator prompt improvements:

• Compaction recovery via session-state.md (fixes Coordinator loses all agent context after conversation compaction #653) — coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted
• Coordinator restraint rules (fixes Coordinator Restraint: Give Copilot Room to Breathe #587) — 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups
• Persist agent results immediately after read_agent (fixes read_agent returns "Failed" after ~2-3 minutes of agent completion #652) — results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe

Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table.

Original PRs: #682, #683, #684
Original author: @tamirdresher

Part of stale PR triage (diberry#137)

[github-actions]

🟠 Impact Analysis — PR #859

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	9
Files added	1
Files modified	8
Files deleted	0
Modules touched	6

🎯 Risk Factors

• 9 files changed (6-20 → MEDIUM)
• 6 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (1 file)

• .github/agents/squad.agent.md

docs (2 files)

• docs/src/content/docs/features/ralph.md
• docs/src/content/docs/reference/cli.md

root (2 files)

• .changeset/watch-message-warning.md
• templates/squad.agent.md.template

squad-cli (2 files)

• packages/squad-cli/src/cli-entry.ts
• packages/squad-cli/templates/squad.agent.md.template

squad-sdk (1 file)

• packages/squad-sdk/templates/squad.agent.md.template

templates (1 file)

• .squad-templates/squad.agent.md

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 3f8b3ab

⚠️ 3 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	⚠️ PR includes 1 .squad/ file(s) — ensure these are intentional
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	5 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	14 check(s) still running

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[Copilot]

Pull request overview

This PR batches coordinator prompt/template updates to improve post-agent reliability (persisting results + compaction recovery) and adds “restraint” guidance, while also updating squad watch/triage to warn on ignored positional arguments and documenting that behavior.

Changes:

• Add “Coordinator Restraint” rules + routing principle to reduce mid-flight intervention and narration.
• Update “After Agent Work” flow to persist read_agent results immediately and write .squad/session-state.md for compaction recovery.
• Warn on positional args passed to squad watch/triage, and document the behavior (docs + changelog + changeset).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
.squad-templates/squad.agent.md	Canonical coordinator prompt updates: restraint rules, result persistence, session-state recovery, and ownership table update
.github/agents/squad.agent.md	Synced coordinator agent prompt copy
templates/squad.agent.md.template	Synced template copy for distribution
packages/squad-cli/templates/squad.agent.md.template	Synced CLI package template copy
packages/squad-sdk/templates/squad.agent.md.template	Synced SDK package template copy
.squad/routing.md	Adds routing principle #8 (“Restraint after dispatch”)
packages/squad-cli/src/cli-entry.ts	Adds warning when positional args are provided to watch/triage
docs/src/content/docs/reference/cli.md	Clarifies extra args are ignored in triage/watch
docs/src/content/docs/features/ralph.md	Adds a caution block explaining watch is polling, not message routing
CHANGELOG.md	Documents the new watch/triage warning behavior
.changeset/watch-message-warning.md	Changeset for @bradygaster/squad-cli patch release

[tamirdresher]

Content looks great @diberry — the compaction recovery, restraint rules, and result persistence fixes are all solid improvements. Originally my PRs (#682, #683, #684), well-batched here.

However this PR has merge conflicts now (squad.agent.md has changed significantly since it was opened). Could you rebase onto the latest dev (or insider)? Once conflicts are resolved and CI is green, happy to approve and merge.

Also noting: #800 (comment spam protection) needs a branch update before it can merge — the base branch has moved ahead. A quick rebase there too would unblock it.

[diberry]

⚠️ Missing tests for \cli-entry.ts\ changes

This PR modifies \packages/squad-cli/src/cli-entry.ts\ (watch/triage positional-arg warning) but has no corresponding test coverage. The resolved Copilot thread on line 526 also flagged this.

What's needed: E2E/CLI harness tests that invoke \watch\ and \ riage\ with positional args and with value-flags like --dispatch-mode fleet, asserting: (1) real positional args warn, (2) value-flag values do not warn.

Status: Flagged as blocker per review checklist — tests should be added before merge. Not attempted in this cleanup pass due to complexity.

---

Review by Squad AI team (Kaylee — Engineering) · requested by Dina Berry

[diberry]

🔍 Squad Review — Kaylee (Engineering)

#	Check	Status	Notes
1	Changelog entry	✅	.changeset/watch-message-warning.md present (patch bump for squad-cli)
2	Squashed to 1 commit	✅	1 commit
3	CI green	✅	All checks pass
4	Copilot comments resolved	✅	7 threads — all resolved (false-positive flag fix, verbatim persistence, restraint reconciliation, scope concern, test gap noted)
5	No .squad/ files	✅	Clean
6	No unrelated files	⚠️	Bundles 3 issues (#682, #683, #684) plus cli-entry.ts watch warning — broad but described in PR body as stale PR triage batch
7	Tests for changes	❌	BLOCKER: packages/squad-cli/src/cli-entry.ts adds user-facing watch/triage positional-arg warning but has no corresponding test. Copilot reviewer explicitly flagged this (thread #7). Need E2E/CLI test asserting: (1) real positional args warn, (2) value-flag values do not warn.
8	Not a duplicate/reversal	✅	Unique scope (closes #682, #683, #684)

🚫 Known blocker: Missing tests for cli-entry.ts — flagged per task instructions.

Verdict: ❌ 1 blocker to fix — tests required for cli-entry.ts watch/triage warning

---

Review by Squad AI team (Kaylee — Engineering) · requested by Dina Berry