feat: Prevent agents from committing unintended files (git staging hygiene)

[diberry]

Problem

When Squad agents (EECOM, CONTROL, etc.) make code changes via the task tool, they frequently include unintended files in their commits — dirty template files, .squad/ state changes, or working-tree artifacts from other branches. This happens because agents use git add . or git commit -a instead of staging specific files.

Evidence from This Session

1. PR fix(nap): archive undated decisions and add count-based fallback #38 (nap.ts bug fix): EECOM's commit included 8 extra template files (squad.agent.md, casting-reference.md, orchestration-log.md, squad-heartbeat.yml) that were dirty in the working tree but unrelated to the fix. The diff showed 3,365 insertions / 3,166 deletions when the actual change was +199 lines across 2 files.

2. PR feat(ci): add test count guard to prevent AI agents from deleting tests #41 (test count guard): Same pattern — EECOM committed 13 files when only 5 were deliverables. Template files from the working tree leaked into the commit. Required manual cleanup: git reset --soft HEAD~1, selective re-staging of only the 5 intended files, and recommit.

3. P0: @copilot accidentally deleted 361 source files on dev (commit 1ab2f5c) bradygaster/squad#631 (@copilot mass deletion): The GitHub @copilot coding agent committed 361 file deletions alongside a 6-file docs fix because it used git add . on an incomplete working tree. This is the same root cause at extreme scale.

Root Cause

Agents default to broad staging commands (git add ., git add -A, git commit -a) because:

1. It's the simplest way to "commit everything I changed"
2. The agent doesn't check git status before committing to verify only intended files are staged
3. The working tree often has dirty files from other branches, template syncs, or build artifacts
4. No pre-commit validation exists to catch over-broad commits

Impact

• PR noise: Reviewers see hundreds of changed lines when the actual change is small
• Merge conflicts: Template file changes create false conflicts on rebase
• Data loss risk: The @copilot incident (P0: @copilot accidentally deleted 361 source files on dev (commit 1ab2f5c) bradygaster/squad#631) shows the worst case — deleted entire codebase
• Manual cleanup tax: Coordinator had to git reset --soft, re-stage, recommit on every PR this session

Proposed Solutions

1. Agent spawn prompt: explicit staging instructions

Add to the standard agent spawn template in squad.agent.md:

## Git Hygiene
- NEVER use `git add .`, `git add -A`, or `git commit -a`
- ALWAYS stage specific files: `git add path/to/file1 path/to/file2`
- Before committing, run `git status` and verify ONLY intended files are staged
- If you see unexpected files in `git status`, do NOT stage them

2. copilot-instructions.md: same rule for @copilot

Already partially addressed in PR #41 (test integrity section). Add explicit git staging rules.

3. Pre-commit hook or CI check

A lightweight check that warns when a commit touches >N files or includes files outside the expected scope. Could be:

• A git hook (.githooks/pre-commit) that warns on >20 staged files
• A CI step that compares PR file count against issue scope
• A Squad coordinator post-work check that verifies agent commits are scoped

4. Agent git add wrapper

Teach agents to use a scoped staging pattern:

# Instead of: git add .
# Use: git add only the files you created/modified
git add packages/squad-cli/src/cli/core/nap.ts test/nap.test.ts

Or provide a helper that stages only files matching a pattern:

git diff --name-only | grep -E "nap\.ts|test/nap" | xargs git add

5. Coordinator post-work validation

After an agent commits, the coordinator should verify:

• git diff --stat HEAD~1 shows only expected files
• No template files, .squad/ state, or build artifacts leaked in
• File count is reasonable for the task scope

If validation fails, auto-remediate: git reset --soft HEAD~1, selective re-stage, recommit.

Success Criteria

• Agent spawn prompts include explicit "never use git add ." rule
• No PR in this session's work requires manual commit cleanup
• copilot-instructions.md has git staging rules
• Pre-commit or post-work validation catches over-broad commits

Related

• feat: Prevent AI agents from deleting/weakening tests to pass CI #39 (test integrity guards — partially addresses this for test deletion)
• P0: @copilot accidentally deleted 361 source files on dev (commit 1ab2f5c) bradygaster/squad#631 (@copilot mass deletion — same root cause at scale)
• PR fix(nap): archive undated decisions and add count-based fallback #38, PR feat(ci): add test count guard to prevent AI agents from deleting tests #41 (this session — both required manual commit cleanup)

[github-actions]

🏗️ Squad Triage — Flight (Lead)

Issue: #42 — feat: Prevent agents from committing unintended files (git staging hygiene)
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.

[diberry]

Investigation: Git Staging Hygiene in Squad Agents

🔍 Root Cause Analysis

Squad agents commit unintended files because:

1. Inconsistent staging practices across templates — Agent spawn templates (.squad-templates/squad.agent.md) instruct agents to use git add .squad/ for state commits, but agent prompt patterns in .copilot/skills/ and legacy templates still use git add -A or git add .
2. No pre-commit validation — Agents don't verify git status before committing, so dirty working-tree files (templates, build artifacts, state from other branches) get swept into commits
3. Overly broad staging scope — When agents combine work commits + state commits, they stage everything in scope without distinguishing between deliverables and artifacts
4. Template file pollution — .squad-templates/, .copilot/skills/, docs/ examples frequently have dirty files that weren't cleaned up from prior branches

📊 Current State Analysis

Files That Get Accidentally Staged

• Template files: squad.agent.md, casting-reference.md, orchestration-log.md, squad-heartbeat.yml
• Build artifacts: node_modules/ (partially — .gitignore prevents most), .dist/, .build/
• State changes: .squad/orchestration-log/, .squad/log/ entries from prior work
• Test artifacts: .test-cli-* directories (visible in working tree now: 78 directories!), screenshot caches
• Sample code: samples/ directories (visible in working tree now)

Evidence from Recent PRs

• PR fix(nap): archive undated decisions and add count-based fallback #38 (nap.ts bug fix): Intended change: +199 lines across 2 files. Actual commit: +3,365 / -3,166 (8 template files leaked)
• PR feat(ci): add test count guard to prevent AI agents from deleting tests #41 (test count guard): Intended: 5 files. Actual: 13 files committed (8 templates leaked again)
• P0: @copilot accidentally deleted 361 source files on dev (commit 1ab2f5c) bradygaster/squad#631 (@copilot mass deletion): 361 file deletions staged alongside 6-file docs fix — worst-case scenario

Existing Guards

Guard	Location	Coverage	Status
.gitignore patterns	.gitignore	.test-*, .squad/log/, .squad/sessions/	✅ Active — prevents most artifacts from being staged
Staging rules (new)	.github/copilot-instructions.md	Explicit "never use git add ." rule	✅ Active — but not followed by all skill templates
Source tree canary	.github/workflows/squad-ci.yml (from PR bradygaster#634)	Checks critical files exist (package.json, index.ts)	✅ Active in PR bradygaster#634 — catches deletions
Large deletion guard	.github/workflows/squad-ci.yml (from PR bradygaster#634)	Warns if >50 files deleted, requires label	✅ Active in PR bradygaster#634 — threshold-based warning

Problem: .gitignore is defensive (prevents leaks), but copilot-instructions.md is prescriptive and not universal across all agent prompts.

What PR bradygaster#634 Added

Two CI guards:

1. Source tree canary check:

   • Verifies critical files exist: packages/squad-sdk/src/index.ts, packages/squad-cli/src/cli/index.ts, etc.
   • Fails the build if any file is missing
   • Catches accidental mass deletions early — prevents @copilot incident from reaching merge

2. Large deletion guard:

   • Counts deleted files in PR (git diff --diff-filter=D)
   • Warns if >50 files deleted
   • Allows override via large-deletion-approved label
   • Prevents unintentional deletions by requiring explicit approval

Limitation: These guards are reactive — they catch problems after the commit. They don't prevent the root cause: overly broad staging in the first place.

🛠️ Proposed Fixes (Ranked by Effort/Impact)

Priority 1: Fix Inconsistent Agent Prompts (Low Effort, High Impact)

Action: Update all agent skill templates to follow copilot-instructions.md rules.

Files to fix:

• .copilot/skills/git-workflow/SKILL.md — Replace git add -A with specific file paths (line 102)
• .copilot/skills/secret-handling/SKILL.md — Replace git add .squad/ with explicit paths
• .copilot/skills/distributed-mesh/SKILL.md — Replace git add + commit with specific staging
• .copilot/skills/release-process/SKILL.md — Already specific, verify no regressions
• .squad/skills/pr-screenshots/SKILL.md — Use glob for PNG files, not git add .
• Templates: .squad-templates/issue-lifecycle.md, .squad-templates/squad.agent.md, etc. — Replace git add . with specific paths

Impact:

• ✅ Immediate: All future agent commits will use scoped staging
• ✅ Prevents template file leaks
• ✅ Works with existing .gitignore guards

Effort: 2-3 hours (search, update, test)

---

Priority 2: Pre-Commit Hook Validation (Medium Effort, High Impact)

Action: Add .githooks/pre-commit hook to validate staging scope before committing.

Logic:

# Stage count check
STAGED=$(git diff --cached --name-only | wc -l)
if [ "$STAGED" -gt 20 ]; then
  echo "⚠️ WARNING: Staging $STAGED files (threshold: 20). Verify intent."
  # Offer prompt: proceed or abort
fi

# Unintended file check
UNINTENDED=$(git diff --cached --name-only | grep -E "\.test-|sample|\.squad/log|\.squad/orchestration-log" | wc -l)
if [ "$UNINTENDED" -gt 0 ]; then
  echo "❌ ERROR: Staging $UNINTENDED artifact files. Stage only deliverables."
  exit 1
fi

# Deletion check
DELETED=$(git diff --cached --diff-filter=D --name-only | wc -l)
if [ "$DELETED" -gt 0 ]; then
  echo "⚠️ CAUTION: This commit deletes $DELETED files. Verify intent."
  # Offer prompt
fi

Configuration: Enable hook via git config core.hooksPath .githooks

Impact:

• ✅ Catches over-broad staging before commit (not after like PR CI: Add source tree canary and large deletion guard bradygaster/squad#634)
• ✅ Interactive feedback — agent can abort and fix
• ✅ Works for both agents and humans

Effort: 4-6 hours (hook + testing + GitOps setup)

---

Priority 3: Post-Work Coordinator Validation (Low Effort, Medium Impact)

Action: Add a Coordinator checklist after agent completes work:

✅ Coordinator Post-Work Validation
1. Verify commit scope: `git diff --stat HEAD~1` — file count reasonable?
2. Check for artifacts: `git diff --name-only HEAD~1 | grep -E "\.test-|sample"`
3. Verify no deletions: `git diff --diff-filter=D HEAD~1 --name-only`
4. If validation fails: `git reset --soft HEAD~1 && git reset && git add <intended-files> && git commit ...`

Impact:

• ✅ Catches leaks before PR opens
• ✅ Coordinator can auto-remediate with git reset --soft
• ✅ Human oversight — Coordinator knows intent

Effort: 1-2 hours (checklist + runbook documentation)

---

Priority 4: Enhance .gitignore (Low Effort, Medium Impact)

Action: Add patterns to prevent staged artifacts from reaching commits:

# Template/example files (local modifications only)
.copilot/skills/**/*.md
.squad-templates/**/*.md
!.copilot/skills/**/SKILL.md  # but keep the skill definitions

# Build temp
/samples/**/*.log
/samples/**/dist/
/samples/**/build/

Limitation: This is defensive (prevents leaks) but not preventive (doesn't stop bad staging commands). Use in combination with Priority 1-2.

Impact:

• ✅ Extra safety net for patterns that slip past checks
• ✅ Minimal maintenance

Effort: 1 hour

---

Priority 5: Enhanced CI Validation (Medium Effort, Low-Medium Impact)

Action: Extend PR bradygaster#634's checks with a pre-merge validator:

- name: "🔒 Commit scope check"
  run: |
    # For each commit in this PR:
    # - Count files changed
    # - Warn if template files modified
    # - Flag if .squad/log added (should be ignored)
    for COMMIT in $(git rev-list origin/${{ github.base_ref }}...HEAD); do
      FILES=$(git diff-tree --no-commit-id --name-only -r "$COMMIT" | wc -l)
      if [ "$FILES" -gt 20 ]; then
        echo "::warning::Commit $COMMIT touches $FILES files"
      fi
    done

Impact:

• ✅ Provides transparency in PR — reviewers see scope warnings
• ✅ Complements PR CI: Add source tree canary and large deletion guard bradygaster/squad#634's deletion guard
• ⚠️ Does NOT prevent merge (advisory only)

Effort: 2-3 hours (CI yaml + testing)

---

✅ Recommended Implementation Path

Phase 1 (Immediate — this week):

1. Fix agent skill templates to use specific git add (Priority 1)
2. Add Coordinator post-work validation checklist (Priority 3)
3. Verify PR CI: Add source tree canary and large deletion guard bradygaster/squad#634 guards are active in CI

Phase 2 (Next week):

1. Implement .githooks/pre-commit hook (Priority 2)
2. Enhance .gitignore patterns (Priority 4)
3. Test with next agent-driven PR

Phase 3 (Polish — sprint 2):

1. Add enhanced CI commit scope check (Priority 5)
2. Document in copilot-instructions.md
3. Monitor for regressions

📋 Success Criteria

• ✅ All agent skill templates use git add <file> (not git add .)
• ✅ .githooks/pre-commit validates staging before commit (or manual checklist in Coordinator flow)
• ✅ PR CI: Add source tree canary and large deletion guard bradygaster/squad#634 CI guards are active and tested
• ✅ Next 5 agent PRs commit only intended files (no template leaks)
• ✅ .gitignore has full coverage for artifacts

---

🔗 Related Issues

• feat: Prevent AI agents from deleting/weakening tests to pass CI #39 — Test integrity guards (partially addresses deletions)
• P0: @copilot accidentally deleted 361 source files on dev (commit 1ab2f5c) bradygaster/squad#631 — @copilot mass deletion (same root cause at scale)
• PR CI: Add source tree canary and large deletion guard bradygaster/squad#634 — Brady's CI deletion guard (reactive, not preventive)

[github-actions]

⚠️ No squad member found matching label squad:archive. Check .squad/team.md (or .ai-team/team.md) for valid member names.

[diberry]

Closing: work completed upstream or no longer relevant. See diberry/project-dina#22 cleanup audit.