Audit `.squad/` entries in .gitignore — are we ignoring too much or too little?

[bradygaster]

Summary

.gitignore hides several .squad/ paths repo-wide. We should review the list deliberately and decide what belongs in version control — this issue is for the audit, not a pre-decided fix.

No changes have been made to .gitignore. Filing this so we review it together.

Current .squad/ entries in .gitignore

Line	Pattern	Added	Commit	Stated reason
13	.squad/orchestration-log/	2026-02-21	c36e8ecc	"ignore generated logs" (PRD 22, #171)
14	.squad/orchestration-log/dispatchguard/	2026-07-27	c4cd76de	"belt-and-suspenders" for dispatchguard subdir
15	.squad/log/	2026-02-21	c36e8ecc	"ignore generated logs"
16	.squad/decisions/inbox/	2026-03-06	d5e190c4	reaction to CI failure #228
17	.squad/sessions/	2026-03-06	d5e190c4	reaction to CI failure #228
18	.squad/config.json	2026-03-05	e62d18f8	contains machine-local absolute teamRoot
30	.squad/.first-run	—	—	transient marker
31	.squad/.watch-pids	—	—	transient PID file
32	.squad/.cache/	—	—	cache
37	.squad/.scratch/	—	—	scratch

Lines 53–54 already carry an explicit warning that .squad/casting/* is authoritative identity and must not be added to the ignore list.

Why this is worth reviewing

1. The promote workflow may already make some entries redundant.

.github/workflows/squad-promote.yml has stripped all of .squad/ at the dev→preview merge since d4058715 (2026-02-20) — one day before the first .gitignore entry landed:

# Strip forbidden paths from merge commit
git rm -rf --cached --ignore-unmatch \
  .ai-team/ \
  .squad/ \
  .ai-team-templates/ \
  team-docs/ \
  "docs/proposals/" || true

It also re-verifies on preview and fails the promote if anything slipped through.

2. Issue #228's guard was scoped to main, but the fix was repo-wide.

The #228 CI error text reads: ".squad/orchestration-log/, .squad/log/, .squad/decisions/inbox/, .squad/sessions/ are noisy runtime state — they belong on dev branches only" and "Other .squad/ files (charters, history, decisions, skills, templates) ARE allowed on main."

The remediation applied was a .gitignore entry, which applies to every branch — including dev, where that state is meant to live. Worth confirming whether that was intended.

3. There is observable fallout.

• Scribe's logging has never worked in a clean clone — .squad/log/ and .squad/orchestration-log/ are gitignored repo-wide #1823 — Scribe's logging has never worked in a clean clone.
• An untracked .squad/archive/2026-08-20-decisions-archive.md (7,513 bytes, 6 decision entries) was found on one machine only. Spot-checking three entries — "Copilot git safety rules", "Dispatch Enforcement — Stop Coordinator From Doing Domain Work Inline", "Workflow templates linted via explicit actionlint file paths" — none appear in tracked .squad/decisions.md.
• .squad/agents/sims/history.md was likewise untracked.
• .squad/decisions.md is currently 51,819 bytes, past the 51,200-byte archival hard gate, so the next Scribe run will archive again into the same destination.

This matches the failure mode described in the Scribe archival safety rules — moving content into an untracked destination is a deletion, not an archive (see #1774, #1783, #1760).

Questions to settle

1. Which of these are genuinely transient vs. team memory we want preserved on dev?
2. Is the promote workflow's strip sufficient protection for main/preview on its own?
3. Should config.json stay ignored, or should the machine-local absolute teamRoot move out of a committed file so the rest of the config can be shared?
4. Does .squad/sessions/ contain anything worth keeping?
5. Should Scribe be required to verify an archival destination is tracked (git ls-files --error-unmatch) before moving content into it?

Related

• Scribe's logging has never worked in a clean clone — .squad/log/ and .squad/orchestration-log/ are gitignored repo-wide #1823 — Scribe's logging has never worked in a clean clone
• .squad/ in .git/info/exclude silently hides new squad state files from git #1817 / squad consult writes .squad/ to the shared info/exclude, silently hiding state in main and all sibling worktrees #1826 — .squad/ written to .git/info/exclude
• Scribe's decisions archive step deletes entries without appending them to decisions-archive.md #1774 / Archival can silently destroy state: writes to untracked destinations are deletions #1783 / Scribe splices inbox H2 headings under H3 entries, breaking hierarchy #1760 — Scribe archival data loss
• CI failure - on squad guard for forbidden paths #228 — original CI failure that prompted two of these entries

Note on a separate change already made

While investigating, .squad/ and .github/agents/squad.agent.md were removed from C:\src\squad\.git\info\exclude (backed up to exclude.bak-20260822). That is local, uncommitted git metadata — not .gitignore — and it is what surfaced the orphaned archive above. Revert from the backup if unwanted.

[bradygaster]

Correction — the data-loss claim in this issue is wrong

I filed this issue partly on a finding I later disproved. Correcting it here so nobody acts on it.

What I originally claimed: that .squad/archive/2026-08-20-decisions-archive.md contained ~7.5 KB of decisions orphaned by the ignore rules — i.e. that the 8/20 archival had silently lost history.

What is actually true: all six entries in that archive file are present in dev's .squad/decisions.md. The 8/20 archival worked correctly. The archive file is a redundant, untracked copy sitting in the main checkout. No data was ever lost.

How I got it wrong: I spot-checked the archive against the worktree's decisions.md, which was behind dev. The entries were missing from that file because the branch hadn't caught up — not because they were dropped. Comparing against the wrong baseline produced a false positive.

What still stands in this issue (unaffected by the correction):

1. .squad/ and .github/agents/squad.agent.md are hidden via .git/info/exclude, and git rev-parse --git-path info/exclude resolves to the shared common dir — so one squad consult run poisons the main checkout and every sibling worktree simultaneously.
2. squad-promote.yml has stripped all of .squad/ since d4058715 (2026-02-20), one day before the first .gitignore entry — making the ignore entries redundant with the promote-time strip.
3. The exclusion is not static. It re-poisons during ordinary CLI usage — see the live repro I'm filing separately.

The consequence is real but it's invisibility, not deletion: agent-authored files under .squad/ are silently unstageable, so decision records written during a session never reach decisions.md on their own and vanish with the worktree. I hit exactly that twice today and had to recover both records by hand.

Apologies for the noise — flagging plainly rather than quietly editing, since the original claim was alarming and wrong.