Skip to content

RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change #678

New issue
New issue
Closed
Closed
RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change#678
Labels
go:needs-researchNeeds investigationsquadSquad triage inbox — Lead will assign to a membertype:spikeResearch/investigation — produces a plan, not code

Description

@tamirdresher
tamirdresher
opened on Mar 29, 2026

RFC: Git-Notes State Solution — Solving #643, #498, #670 in One Architectural Change

Problem Statement

Three open issues share a common root cause — Squad state (.squad/) lives in the working tree:

Issue Problem Impact
#643 State destroyed when .squad/ is gitignored + branch switch Data loss — hit twice in one session on Azure CLI
#498 .squad/ tracked in version control causes merge conflicts, CI noise, privacy concerns v1.0 blocker — must resolve before release
#670 5 independent code paths hardcode .squad/ paths with no single source of truth Bug factory — caused #77 (skills discovery bug)

Prior Art

This solution draws from real-world experience documented in:

Proposed Architecture

Core idea: Move Squad state from the working tree to git refs (git-notes or orphan branches), making state immune to branch switches, gitignore, and merge conflicts.

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

refs/notes/squad/
├── team.md          (team roster — readable via git notes show)
├── routing.md       (routing rules)
├── decisions.md     (append-only decisions log)
├── agents/
│   ├── fido/history.md
│   ├── eecom/history.md
│   └── ...
└── casting/
    ├── policy.json
    └── registry.json

Pros: Native git feature, survives checkout/rebase/stash, pushable/pullable
Cons: Limited tooling support, not human-browsable in GitHub UI

Option B: Orphan Branch (squad-state)

git checkout --orphan squad-state
# Branch has no parent — completely independent of main/dev
# Contains only .squad/ files
# Never merged into main/dev
# Read/written by squad CLI transparently

Pros: Full GitHub UI support (browsable), familiar git operations, works with existing CI
Cons: Slightly more complex read/write (checkout dance or worktree)

Option C: External State Directory (fallback)

~/.squad/projects/<repo-hash>/
├── team.md
├── routing.md
├── agents/...
└── ...

Pros: Zero git interaction, works for repos you don't own
Cons: Not portable, not shared across machines, no version history

Recommended Approach

Primary: Option B (orphan branch) — best balance of features and usability
Fallback: Option C (external dir) — for contributor scenarios on repos you don't own
squad build regenerates working-tree .squad/ from squad.config.ts when needed (CI, fresh clones)

How This Solves Each Issue

Issue How It's Solved
#643 (state destroyed) State is in a ref, not the working tree — git checkout doesn't touch it
#498 (remove from VCS) .squad/ gets gitignored; real state lives in orphan branch or external dir
#670 (manifest/layout) Manifest lives in orphan branch; single source of truth for all paths

Implementation Phases

Phase 1: State Read/Write Abstraction

Phase 2: Migration

  • squad migrate-state command moves .squad/ to orphan branch
  • Add .squad/ to .gitignore
  • git rm -r --cached .squad/ (untrack, keep on disk)
  • CI workflows add squad build step before reading .squad/team.md

Phase 3: Integration with Manifest (#670)

  • Manifest lives in orphan branch alongside state
  • All 5 code paths read from StateBackend instead of filesystem directly
  • squad doctor validates state backend health

Questions for Discussion

  1. Orphan branch name: squad-state vs refs/squad/state vs something else?
  2. Should state be per-branch (branch-specific decisions) or global (one state for all branches)?
  3. How does this interact with worktree-based agent isolation?
  4. Should we support both Options A and B, or pick one?

Related

Activity

  1. tamirdresher
    added
    squadSquad triage inbox — Lead will assign to a member
    go:needs-researchNeeds investigation
    type:spikeResearch/investigation — produces a plan, not code
    squad:flight
    squad:eecom
    on Mar 29, 2026

  2. github-actions commented on Mar 29, 2026

    @github-actions
    github-actionsBot
    on Mar 29, 2026 – with GitHub Actions
    Contributor

    📋 Assigned to Flight (Lead)

    Issue: #678 — RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change

    Flight will pick this up in the next Copilot session.

    For Copilot coding agent: If enabled, this issue will be worked automatically.
    Otherwise, start a Copilot session and say:
    Flight, work on issue #678

  3. github-actions
    added
    squad:fido
    on Mar 29, 2026

  4. github-actions commented on Mar 29, 2026

    @github-actions
    github-actionsBot
    on Mar 29, 2026 – with GitHub Actions
    Contributor

    🏗️ Squad Triage — Flight (Lead)

    Issue: #678 — RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change
    Assigned to: FIDO (Quality Owner)
    Reason: Issue relates to testing/quality work

    @copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

    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.

  5. github-actions commented on Mar 29, 2026

    @github-actions
    github-actionsBot
    on Mar 29, 2026 – with GitHub Actions
    Contributor

    📋 Assigned to EECOM (Core Dev)

    Issue: #678 — RFC: Git-Notes State Solution — solve state destruction, VCS removal, and layout manifest in one architectural change

    EECOM will pick this up in the next Copilot session.

    For Copilot coding agent: If enabled, this issue will be worked automatically.
    Otherwise, start a Copilot session and say:
    EECOM, work on issue #678

  6. tamirdresher
    added a commit that references this issue on Mar 29, 2026

    feat(sdk): StateBackend POC — orphan branch state persistence (#678)

    0c29293

  7. tamirdresher commented on Mar 29, 2026

    @tamirdresher
    tamirdresher
    on Mar 29, 2026
    CollaboratorAuthor

    Update: Relationship with PR #640 (StorageProvider)

    @diberry posted an excellent analysis on PR #640 about how StateBackend (#680) and StorageProvider (#640) compose:

    They're complementary layers:

    Composition:

    Merge order: #640 first → then #680 adapts FilesystemBackend to wrap StorageProvider instead of raw node:fs. Since #680 is DO NOT MERGE (POC), this is natural.

    See full analysis: https://github.com/bradygaster/squad/pull/640#issuecomment-4150187509

  8. diberry commented on Mar 31, 2026

    @diberry
    diberry
    on Mar 31, 2026
    Contributor

    🔄 Ralph status: RFC — git-notes state solution. POC in PR #680 (DO NOT MERGE). Research phase. Refs #643, #498, #670.

  9. diberry commented on Mar 31, 2026

    @diberry
    diberry
    on Mar 31, 2026
    Contributor

    ✅ Status Update — Issue #678

    PR #680 (POC - DO NOT MERGE):

    • Reviewed by all 21 squad members
    • Rebase has conflicts with dev (expected for POC)
    • StateBackend orphan branch persistence POC ready for architectural evaluation

    Note: This is a POC/spike. Not intended for merge — for evaluation only.

  10. bradygaster commented on Apr 25, 2026

    @bradygaster
    bradygaster
    on Apr 25, 2026
    Collaborator

    Closed by #theSquadsquad triage — verified fixed/superseded in v0.9.4.

  11. bradygaster
    closed this as completedon Apr 25, 2026
  12. bradygaster
    removed
    squad:flight
    squad:eecom
    squad:fido
    on Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    go:needs-researchNeeds investigationsquadSquad triage inbox — Lead will assign to a membertype:spikeResearch/investigation — produces a plan, not code

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions