feat(sdk): post-merge worktree cleanup lifecycle (#530)

.squad/agents/flight/history.md

@@ -65,3 +65,11 @@ Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic
 ### Session 2 Summary (2026-03-22)
 
 Wave 1 architecture work on #329/#344: validated 20KB personal squad design doc, identified and patched 5 gaps, authored 19-task implementation plan spanning 4 future PRs. Implementation not yet started — deferred to future session. EECOM assigned Phase 1–2 (SDK + CLI), Procedures assigned Phase 3 (governance), Sims assigned Phase 4 (tests).
+
+### Worktree Gap Triage — #525 (2025-07-18)
+
+Community contributor joniba filed #525 identifying that Squad has full worktree *detection* but zero worktree *creation* in the coordinator/spawn flow. Validated all 10 claims — analysis is accurate. The reading infrastructure (resolveSquad() worktree detection, .gitattributes merge=union, boundary tests) is ~95% complete. The gap: ralph-commands.ts hardcodes `git checkout -b` in all 3 platform adapters (lines 50/71/92), coordinator never creates worktrees before spawn, no WORKTREE_PATH in prompts, and issue-lifecycle.md is referenced in squad.agent.md but doesn't exist.
+
+**Decision:** P2 — important but not v1-blocking. Broke into 5 sub-issues: (1) doc fix for missing issue-lifecycle.md (quick win → Procedures), (2) worktree variant in ralph-commands.ts (EECOM), (3) coordinator pre-spawn logic (Procedures + EECOM), (4) post-merge cleanup (EECOM), (5) architecture decision on heuristic (Flight). Sub-issue #1 ships immediately; #2–5 queue post-Wave-1 alongside SubSquads work where parallel execution becomes a hard requirement.
+
+**Backlog priority recommendation:** Top 5 for v1 = #508 (Ambient Personal Squad), #498 (remove .squad/ from VCS), #485 (Agent Spec & Validation), #481 (Typed StorageProvider), #347 (shore up init --sdk). Quick wins: #525 doc fix, #347. Deprioritize: manual verification debt (#418–421), long-term exploratory. A2A (#332–336) stays shelved per existing decision.

.squad/orchestration-log/2026-03-22T23-10.md

@@ -0,0 +1 @@
+2026-03-22T23:10Z: Coordinator enabled worktrees, launched #508 fan-out (EECOM SDK + Procedures Governance), Flight authoring #525 sub-issues. Priority restack: #508 first, #525 sub-items replace #347, #498 parallel, hold #481/#347.

packages/squad-sdk/src/platform/index.ts

@@ -18,6 +18,8 @@ export { FileLogCommunicationAdapter } from './comms-file-log.js';
 export { GitHubDiscussionsCommunicationAdapter } from './comms-github-discussions.js';
 export { ADODiscussionCommunicationAdapter } from './comms-ado-discussions.js';
 export { createCommunicationAdapter } from './comms.js';
+export { listWorktrees, findMergedWorktrees, cleanupWorktree, cleanupMergedWorktrees } from './worktree-lifecycle.js';
+export type { WorktreeInfo, CleanupResult, BatchCleanupResult } from './worktree-lifecycle.js';
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';