Repository navigation
Description
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/" || trueIt 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.mdwas likewise untracked..squad/decisions.mdis 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
- Which of these are genuinely transient vs. team memory we want preserved on
dev? - Is the promote workflow's strip sufficient protection for
main/previewon its own? - Should
config.jsonstay ignored, or should the machine-local absoluteteamRootmove out of a committed file so the rest of the config can be shared? - Does
.squad/sessions/contain anything worth keeping? - 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/excludesilently 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.
Activity
bradygaster commentedon Aug 23, 2026
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.mdcontained ~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 behinddev. 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):
.squad/and.github/agents/squad.agent.mdare hidden via.git/info/exclude, andgit rev-parse --git-path info/excluderesolves to the shared common dir — so onesquad consultrun poisons the main checkout and every sibling worktree simultaneously.squad-promote.ymlhas stripped all of.squad/sinced4058715(2026-02-20), one day before the first.gitignoreentry — making the ignore entries redundant with the promote-time strip.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 reachdecisions.mdon 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.
chore(squad): gh-aw wave-1 session records + repair 3 lost history ar…
bradygaster commentedon Sep 23, 2026
Closing as superseded — the headline finding in this audit (silent decision-archive data loss) was explicitly retracted by the reporter in a follow-up comment on this same thread: all six entries were actually present in
dev'sdecisions.md, and the "loss" was a false positive from comparing against a stale worktree baseline. The remaining, still-valid concerns from this audit (.git/info/excludepoisoning shared worktrees, Scribe logging being gitignored) are already tracked as their own dedicated issues (#1823, #1988), so this umbrella audit issue is redundant with those.