Repository navigation
Description
Problem
When Squad operates inside a working repo, normal sessions mutate .squad/ files — agent history.md, decisions.md (+ decisions/inbox/), orchestration logs, casting/identity, etc. Today there is no consistent, documented governance for how those changes get committed and pushed as the underlying repo is being worked on. In practice I have seen three divergent behaviors, sometimes within the same repo:
- Left uncommitted — the session ends with the working tree dirty with
.squad/changes, which is easy to lose or to accidentally sweep into the next unrelated commit. - Smuggled into unrelated feature PRs —
.squad/history/decision churn lands inside a product feature PR, polluting the diff and code review. - A separate, dedicated "squad state" PR — a follow-up PR whose only purpose is to update
.squad/files. This is what one of my repos settled on, but it is a hand-rolled local convention, not something Squad defines or enforces.
Because the behavior is not defined by Squad itself, each repo / team / coordinator invents its own approach (or none), and the same repo drifts between the three modes across sessions.
Why it matters
- Reviewers get noisy diffs when state leaks into feature PRs.
- Contributors lose state (or hit merge conflicts on append-only files) when it is left uncommitted.
- New adopters have no guidance on the "right" way to handle
.squad/churn, so PR hygiene and onboarding suffer. stateBackendalready offerslocal/orphan/two-layer, and.gitignoretypically excludesorchestration-log/,log/, anddecisions/inbox/— but the commit / PR governance for the tracked, mutable files (histories,decisions.md, casting) is still undefined and easy to get wrong.
Request
Consolidate and document a clear, ideally enforced, governance model for .squad/ state changes during normal repo work. Directions to consider:
- A documented default policy — e.g. "mutable
.squad/state is never mixed into feature PRs; it is committed to a dedicatedsquad/state-*branch/PR (or the configured state backend) at end of session." - Automation to enforce it — a first-class
squadCLI command (e.g.squad state commit/squad sync) and/or a Scribe responsibility that reliably lands state the same way every time, plus an optional pre-commit / pre-push guard that fails when mutable.squad/state is staged alongside product code. - A clear tracked-vs-ignored contract — make it obvious (docs + shipped default
.gitignore/.gitattributes) which paths are runtime-ignored vs committed, so people stop hand-managing them. - Tie it to
stateBackend— document how each backend (local,orphan,two-layer) is expected to handle the PR/commit flow so users can choose intentionally.
Concrete example
In a repo that uses Squad, a single work session produced a product change (docs + a bug fix) as one PR, plus a separate follow-up PR that only updated .squad/agents/*/history.md. That separation was a hand-rolled local convention — Squad gave no guidance, so without it the state would have either been left uncommitted or folded into the feature PR. Standardizing this would remove the guesswork.
Activity
Danta1st commentedon Nov 1, 2026
In Squad CLI 1.1.0, we observed an instruction conflict while preparing a source PR—not a Git or storage failure. The configuration omitted
stateBackend, so the default local backend was active (FSStorageProvider). Team configuration, decisions, and memory files were tracked;decisions.mdusedmerge=union, and no pre-commit hook was installed.A platform decision had been recorded through governed state tools. When asked to include the tracked configuration and mutable decision/memory changes in a PR, the Coordinator declined to commit the mutable files. Handing the commit to Scribe appeared to meet the same prohibition. No commit was attempted, and no hook or storage failure was observed.
The local-state documentation says local state is normally committed alongside code. Yet the Coordinator directive says not to manually commit mutable state, and the Scribe charter likewise prohibits it without an explicit local exception. The worktree reference also describes Scribe commits and Git-based propagation.
Could the restrictions be made backend-specific: permit the documented tracked-state commit/PR flow for local state, retain runtime-owned persistence for orphan/two-layer backends, and clarify whether Coordinator or Scribe performs local commits?