feat(council): Add adaptive rounds, file-first output, and recovery mode

[A13xSM]

Summary

This PR improves the Council skill's resilience, efficiency, and usability based on real-world usage in extended multi-session specification reviews.

Key Changes

• Adaptive Rounds — Round 3 is now conditional based on convergence detection after Round 2
• File-First Output — Session state persists to ~/.claude/MEMORY/ for resilience
• Recovery Workflow — Resume interrupted sessions with partial or full rerun options
• Config.md — Centralized configuration for rounds, agents, output modes, and model tiering
• Patchlist Mode — Structured output format for specification reviews

⚠️ Behavioral Changes

This PR changes default Council behavior:

1. Adaptive rounds (2-3 instead of always 3) — Round 3 now only runs if convergence is low or blocking issues exist. Previously, Council always ran 3 rounds. Users depending on 3 rounds of feedback will see different output.

2. Model tiering — Round 2 now uses haiku (faster, cheaper) while Rounds 1 and 3 use sonnet. Previously, no model was specified. This may affect Round 2 response quality.

3. File output — Sessions now write to ~/.claude/MEMORY/ by default. This creates files that didn't exist before.

If these changes are too aggressive for a minor version bump, consider:

• Making adaptive rounds opt-in via config (rounds: 3 as default, rounds: adaptive as option)
• Removing model tiering or making it opt-in
• Making file output opt-in

Motivation

During extended council sessions (5+ sequential reviews over multiple hours), we encountered several pain points:

1. Rate limit interruptions caused lost work. Sessions had to be manually reconstructed.
2. Context compaction destroyed in-progress transcripts when sessions ran long.
3. Many debates reached consensus in Round 2, making Round 3 wasteful (~33% token savings when skipped).
4. No structured output format for document reviews — agents produced prose when we needed actionable changes.

These changes formalize workarounds that were previously done manually.

Changes

File	Change
README.md	Updated features, architecture, and changelog for v2.5.0
SKILL.md	Added routing for Recovery workflow, config loading
Config.md	New — Centralized configuration with model tiering, output modes, scope limits
Workflows/Debate.md	Added file output, adaptive Round 3, model tiering, interruption handling
Workflows/Recovery.md	New — Full and partial rerun modes for interrupted sessions

Test Plan

• Run a basic council debate and verify file output to ~/.claude/MEMORY/STATE/council-sessions/
• Verify Round 3 is skipped when agents converge in Round 2
• Interrupt a session mid-round, then use Recovery workflow to resume
• Test patchlist mode with "Council (patchlist): ..."

---

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR enhances the Council skill with three major improvements based on real-world usage: adaptive rounds (Round 3 is now conditional based on convergence detection), file-first output (session state persists to ~/.claude/MEMORY/ for resilience), and recovery mode (resume interrupted sessions). These changes aim to address rate limit interruptions, context compaction issues, and inefficiency when debates converge early.

Changes:

• Added adaptive Round 3 logic that skips the final round when agents converge in Round 2 (33% token savings)
• Introduced file-based session persistence with recovery workflow for interrupted sessions
• Added centralized Config.md with model tiering, output modes, and scope limits

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
Recovery.md	New workflow for resuming interrupted sessions with partial/full rerun modes
Debate.md	Updated with adaptive rounds, file output commands, and convergence detection logic
Config.md	New centralized configuration file defining defaults, model tiering, and adaptive behavior
SKILL.md	Updated metadata, workflow routing, and documentation to reference new features
README.md	Version bump to 2.5.0 with changelog and updated feature descriptions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[A13xSM]

✅ Manual Testing Complete

Ran a full council debate test with the updated skill:

Feature	Status	Evidence
File-first output	✅	round-1.md, round-2.md, convergence.json saved to session directory
Adaptive rounds	✅	Round 3 skipped due to high convergence (4/4 agents agreed)
Model tiering	✅	Round 1 used sonnet, Round 2 used haiku
Session archival	✅	Archived to ~/.claude/MEMORY/RESEARCH/2026-02/

Session ID: 20260202-235539-51cd5fa9

All test plan items verified working.

[A13xSM]

Copilot Feedback Addressed

Pushed commit fa93861 addressing Copilot's review comments:

Issue	Fix
Invalid JSON syntax (true/false, 2 or 3)	Changed to concrete examples with valid JSON
Convergence threshold "3+ agents" doesn't scale	Changed to "majority of agents"
Session ID path traversal risk	Added validation guidance in Recovery.md
Wildcard *.md ordering issues	Explicit file ordering with 2>/dev/null for optional round-3
RoundStructure.md description outdated	Updated to "Adaptive 2-3 round structure"
Inconsistent role vs personality names	Added both in examples: "Architect (Serena)"

Not addressed (low priority):

• ISO timestamp examples in metadata.json (pseudocode is clear enough)
• Millisecond precision in session ID (hex suffix handles collisions)
• openssl fallback for other environments (out of scope for this PR)
• PerplexityResearcher fallback during recovery (edge case)