Claude host PR 1: spec/code agreement, regression guards and canonical-coordinator ADR (#2438 Phases 0 + 7) #2440

Part of #2438 (PR 1 of the epic's PR plan, Wave 1). Merges first. PRs 2 and 3 start after this one lands.

Goal

Make the spec, docs and matrix agree with the code on every Claude-specific fact, and add the regression guards that every later PR in the epic is checked against. Also record the Phase 7 canonical-coordinator question as a Proposed ADR.

Scope

Spec/code corrections (Phase 0)

ADR-001 applies: where the code and the spec disagree, the code wins and the documents are corrected.

• Rename Task to Agent for Claude Code, and describe its model, run_in_background and isolation: "worktree" parameters:
  • packages/squad-sdk/src/client/adapters/coordinator.ts (Claude dispatch section, ~L156–159)
  • docs/specification/client-harness-adapters-v0.2.md §7.2
  • docs/src/content/docs/concepts/squad-2-0-architecture.md (L52)
  • The matrix source that generates docs/src/content/docs/reference/host-feature-matrix.md (the model-selection row and the subagent-MCP-inheritance rows). Edit the source, not the generated page. background-agents.claude already says Agent, so the matrix currently contradicts itself.
• client-harness-adapters-v0.2.md §13 says the Claude .gitignore block uses <!-- SQUAD:claude:START --> / END. packages/squad-sdk/src/client/adapters/apply.ts (linesMarker) writes # squad:claude. Correct the spec.
• Re-evaluate model-selection.claude in test-fixtures/spec/suite-v0.2/host-feature-matrix.json against the Agent tool (per-call model) and subagent frontmatter (model, effort). If the digest gains a model-selection section, drop the expected-fail in test/clients.test.ts.
• Add a Claude Code section to docs/src/content/docs/scenarios/client-compatibility.md (today it covers only Copilot surfaces).
• Make the README platform badge and model fallback chains host-aware, or label them as Copilot-specific.
• State in the matrix notes and docs that the shared-digest gaps (gitlab-issues, azure-devops, monorepo-team-root, dual-root-remote-mode) affect every host and are out of scope for Epic: Claude Code as a first-class Squad 2.0 host, and the non-Copilot host that promotes the v0.2 profiles #2438.

Regression guards

Add these as tests. They must pass on this PR and stay green on every later PR in the epic.

• Copilot projection snapshot: squad init and squad upgrade with --client copilot produce byte-identical output before and after. Snapshot every Copilot-projected file, including .github/agents/squad.agent.md.
• No diff without Claude: squad upgrade on a repo without claude in clients[] produces no file changes.
• Claude rollback: squad upgrade --client claude on an existing Claude install changes only Squad-managed files, and uninstallClients restores the pre-upgrade bytes.

Phase 7 ADR (decision only)

• Add docs/specification/adr-003-host-neutral-canonical-coordinator.md with status Proposed. Question: should the canonical coordinator move from .github/agents/squad.agent.md (~80 KB) to a host-neutral source (e.g. under .squad/ or .squad-templates/), with Copilot's file generated from it like every other host's?
  • Cover: Copilot surfaces that auto-discover .github/agents/; the requirement that the generated Copilot file stay byte-identical; how it affects coordinator slimming for Claude (Phase 4).
  • No implementation. Merging this PR does not approve the ADR.

Behaviour change to call out

The Task → Agent rename changes the generated .claude/agents/squad.md, so existing Claude installs see a small diff on squad upgrade. Copilot output must not change. Note it in the CHANGELOG.

Done when

• All checkboxes above are ticked.
• The three regression-guard tests exist and pass.
• npm test passes; the host-feature-matrix tests and the G1–G9 golden trace pass unchanged for every host other than Claude.
• The ADR is merged with status Proposed.