Skip to content

Governance: define a consistent policy for how .squad/ state changes are committed/PR'd during normal repo work #1501

Open

Description

@obit91

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:

  1. 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.
  2. Smuggled into unrelated feature PRs — .squad/ history/decision churn lands inside a product feature PR, polluting the diff and code review.
  3. 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.
  • stateBackend already offers local / orphan / two-layer, and .gitignore typically excludes orchestration-log/, log/, and decisions/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 dedicated squad/state-* branch/PR (or the configured state backend) at end of session."
  • Automation to enforce it — a first-class squad CLI 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

  1. Danta1st commented on Nov 1, 2026

    @Danta1st

    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.md used merge=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?

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

    wave1:P10Wave 1 PR group P10wave:1-nextWave 1 — immediate next sprint

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions