feat(sdk): git-notes + orphan-branch state backends for .squad/ (Options A & B from blog Part 7b)

Git-based State Backends

Problem

PR #797 implemented Option C (external directory). This issue covers the two git-native approaches from Tamir's blog Part 7b:

Option A: Git Notes (`refs/notes/squad`)

Squad state stored in git notes ref, not working tree
Survives branch switches (ref-based, not file-based)
Invisible in git status, git diff, PRs
Accessed via git notes --ref=squad

Option B: Orphan Branch (`squad-state`)

Dedicated branch with no common ancestor
State files live there, never merged into main
Read via git show squad-state:.squad/team.md

Implementation

Add StateBackend interface to squad-sdk resolution.ts
Implement GitNotesBackend and OrphanBranchBackend
Add --state-backend flag to CLI (values: worktree | external | git-notes | orphan)
Config in .squad/config.json: { \"stateBackend\": \"git-notes\" }
Fallback: if chosen backend fails, warn and fall back to worktree

Blog reference

https://tamirdresher.github.io - Part 7b of the Scaling AI series

🏗️ Squad Triage — Flight (Lead)

Issue: #807 — feat(sdk): git-notes + orphan-branch state backends for .squad/ (Options A & B from blog Part 7b)
Assigned to: Flight (Lead)
Reason: No specific domain match — assigned to Lead for further analysis

@copilot evaluation: No strong capability match — routed to squad member.

Team roster:

Flight (Lead) → label: squad:flight
Procedures (Prompt Engineer) → label: squad:procedures
EECOM (Core Dev) → label: squad:eecom
FIDO (Quality Owner) → label: squad:fido
PAO (DevRel) → label: squad:pao
CAPCOM (SDK Expert) → label: squad:capcom
CONTROL (TypeScript Engineer) → label: squad:control
Surgeon (Release Manager) → label: squad:surgeon
Booster (CI/CD Engineer) → label: squad:booster
GNC (Node.js Runtime) → label: squad:gnc
Network (Distribution) → label: squad:network
RETRO (Security) → label: squad:retro
INCO (CLI UX & Visual Design) → label: squad:inco
GUIDO (VS Code Extension) → label: squad:guido
Telemetry (Aspire & Observability) → label: squad:telemetry
VOX (REPL & Interactive Shell) → label: squad:vox
DSKY (TUI Engineer) → label: squad:dsky
Sims (E2E Test Engineer) → label: squad:sims
Handbook (SDK Usability) → label: squad:handbook
Ralph (Work Monitor) → label: squad:ralph
@copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

feat(sdk): git-notes + orphan-branch state backends (#807)

feat(watch): next-gen watch with execute redesign, robustness, and PS…

Closed: PR #830 merged to insider Apr 4. StateBackend interface + GitNotesBackend + OrphanBranchBackend + --state-backend flag shipped.

Navigation Menu

Repository navigation

feat(sdk): git-notes + orphan-branch state backends for .squad/ (Options A & B from blog Part 7b) #807

Git-based State Backends

Problem

Option A: Git Notes (`refs/notes/squad`)

Option B: Orphan Branch (`squad-state`)

Implementation

Blog reference

🏗️ Squad Triage — Flight (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat(sdk): git-notes + orphan-branch state backends for .squad/ (Options A & B from blog Part 7b) #807

Description

Git-based State Backends

Problem

Option A: Git Notes (refs/notes/squad)

Option B: Orphan Branch (squad-state)

Implementation

Blog reference

Activity

github-actions commented on Apr 4, 2026

🏗️ Squad Triage — Flight (Lead)

@copilot evaluation: No strong capability match — routed to squad member.

tamirdresher commented on Apr 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Option A: Git Notes (`refs/notes/squad`)

Option B: Orphan Branch (`squad-state`)