Skip to content

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

Closed as not planned

Description

@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

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

  1. bradygaster commented on Aug 23, 2026

    @bradygaster
    CollaboratorAuthor

    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.

  2. bradygaster commented on Sep 23, 2026

    @bradygaster
    CollaboratorAuthor

    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's decisions.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/exclude poisoning 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.

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions