docs: coordinator compaction recovery and restraint rules (#859) #934

Gap

PR #859 adds compaction recovery, restraint rules, result persistence. Behavioral changes undocumented. Docs must explain these coordinator features.

Key Terms Defined

Compaction Recovery

Definition: A recovery mechanism activated when the Coordinator detects that conversation context was compacted (prior messages are missing or summarized due to context window overflow). The Coordinator writes session state (.squad/session-state.md) before each agent batch and reads it upon context resumption to recover its place in the workflow without losing the plan. Session state is a checkpoint that answers: "What should the Coordinator do next?" It is NOT authoritative for decisions or routing — those come from decisions.md, routing.md, and team.md.

Observable Behavior:

• Coordinator persists a checkpoint to .squad/session-state.md after each agent batch (step 8 in post-work flow)
• Upon context resumption (detected by missing prior messages), Coordinator reads the checkpoint and continues the post-work flow without replaying earlier steps
• Checkpoint format includes only the next action needed (one bullet point)

Restraint Rules

Definition: A set of 6 principles that balance the Coordinator's eager (proactive) execution with respectful boundaries. After dispatching agents, the Coordinator:

1. Does NOT re-explain context agents already know
2. Does NOT intervene while an agent is still running
3. Does NOT summarize or rephrase agent output — presents it directly
4. Does NOT add unsolicited analysis without user request
5. Does NOT spawn follow-up agents unless explicitly requested, mandated, or part of a declared dependency chain
6. Keeps coordinator commentary to 1-2 sentences maximum

Observable Behavior:

• Agent output appears in responses with minimal coordinator framing
• Coordinator refrains from verbose summaries or "I think this means..."
• No unnecessary follow-up agents are spawned (Scribe only spawns when user asks or when agents produced significant work)

Result Persistence

Definition: Mandatory step (step 2 in post-work flow) where Coordinator writes agent results immediately to .squad/orchestration-log/{ISO8601-timestamp}-{agent-name}.md BEFORE any other processing. This is critical because read_agent data expires within 2-3 minutes; persistence ensures results are not lost if session ends or context compacts.

Observable Behavior:

• Orchestration log directory contains timestamped markdown files for each agent that ran
• Each file includes: agent name, timestamp, original task, result summary, and list of files modified
• If read_agent returns no response, Coordinator checks the orchestration log for files written by the agent directly during its run

Documentation Pages to Create/Update

• docs/src/content/reference/coordinator-restraint.md — Explain the 6 restraint rules with examples
• docs/src/content/reference/result-persistence.md — Explain mandatory result persistence step, orchestration log format
• docs/src/content/reference/compaction-recovery.md — Explain session state checkpoint mechanism and recovery flow
• docs/src/content/guide/squad.agent.md — Update coordinator charter in .squad templates to reference these docs

Acceptance Criteria

• All three new reference docs exist with clear definitions and observable behavior descriptions
• PR feat(coordinator): compaction recovery + restraint rules + result persistence (#682 #683 #684) #859 is merged
• Links from squad.agent.md point to the new docs
• Session state checkpoint format documented (example shown)
• Orchestration log format documented (example shown)

Depends on: PR #859 merge

Source: docs-opportunity-scanner (2026-04-08)