PR file contamination: Squad adds/removes unrelated files from PRs #777

Problem Statement

Squad agents can add files to (or remove files from) a PR that are unrelated to the original PR's purpose. This is a design-level issue — not a single bug, but multiple overlapping contamination vectors in Squad's git operations, Scribe's commit patterns, and the default no-worktree architecture.

Investigation Summary

A deep codebase investigation identified 7 distinct root causes across three severity tiers.

🔴 HIGH RISK — Active contamination vectors

1. git add . in Agent Spawn Templates

The issue lifecycle template (issue-lifecycle.md:234) instructs agents to run git add . when addressing PR review feedback — this stages EVERYTHING in the working directory, not just the agent's work.

Scenario: Agent works on issue #42, modifies src/auth.ts. Meanwhile, another session left .squad/agents/dallas/history.md dirty. Agent runs git add . → stages BOTH the intended fix AND the unrelated history change. PR includes files the agent never touched.

2. Scribe's Broad git add .squad/ Pattern

Scribe runs after every work batch and executes git add .squad/ — a recursive add of the ENTIRE .squad/ directory tree.

Scenario: Agent A on branch squad/42-fix-auth modifies .squad/agents/ripley/history.md. Agent B on a different task modifies .squad/agents/dallas/history.md in the same working directory. Scribe runs git add .squad/ → stages BOTH history files. PR for issue #42 now shows dallas's history change.

3. No Worktree Isolation by Default

Worktree mode is opt-in (SQUAD_WORKTREES=1). By default, all agents work in the same repository directory. When multiple issues are worked concurrently:

• All agents share the same working tree and git index
• File writes from one issue's agents are visible to another issue's agents
• Scribe's git add .squad/ captures changes from ALL concurrent work

Evidence: packages/squad-sdk/src/agents/history-shadow.ts:17-23 explicitly acknowledges concurrent append to same history.md as a known pattern, with only in-process mutex protection (no cross-process locking).

🟡 MEDIUM RISK — Structural contamination patterns

4. merge=union State Accumulation

.gitattributes configures merge=union on append-only files:

.squad/decisions.md merge=union
.squad/agents/*/history.md merge=union
.squad/log/** merge=union
.squad/orchestration-log/** merge=union

When branches merge, .squad/ state from ALL branches combines. PRs show decisions/history from unrelated work after rebase. Intentional design, but surprising to PR reviewers.

5. Scribe Creates New Files Every Session

Every Scribe run creates NEW files:

These appear as "new files" in PR diffs even though they're operational state.

6. Decision Inbox Lifecycle Timing

Agents write to .squad/decisions/inbox/{name}-{slug}.md. Scribe merges and deletes them. If Scribe fails or timing is off, inbox files persist in the PR. (Mitigated by .gitignore covering inbox, but the timing gap creates confusion.)

🟢 LOW RISK — Edge cases

7. Template Sync Side Effects

scripts/sync-templates.mjs copies from .squad-templates/ to three mirror locations. If triggered during agent work, mirror files get updated and could appear in a PR. (Squad-project-specific.)

Existing Safeguards (What's Already Working)

Proposed Fixes

Files Investigated

• .squad-templates/squad.agent.md (Scribe spawn template)
• .squad-templates/scribe-charter.md (Scribe git operations)
• .squad-templates/issue-lifecycle.md (agent git add patterns)
• .copilot/skills/git-workflow/SKILL.md (git workflow skill)
• .copilot/skills/windows-compatibility/SKILL.md (Windows git patterns)
• packages/squad-sdk/src/agents/history-shadow.ts (concurrent write mutex)
• packages/squad-sdk/src/resolution.ts (worktree resolution)
• packages/squad-cli/src/cli/core/detect-squad-dir.ts (worktree detection)
• .gitattributes (merge=union config)
• .gitignore (excluded .squad/ paths)
• .github/workflows/squad-promote.yml (release safeguards)
• All .github/workflows/squad-*.yml (workflow git operations)