Repository navigation
P0: squad upgrade misses .gitattributes, .gitignore, skills, templates, and directories for existing users #544
Description
Problem
When a user runs squad upgrade, significant infrastructure that squad init creates is never delivered to existing users. Three independent code audits (EECOM, FIDO, Procedures) confirmed these gaps by tracing the actual upgrade codepath.
Impact: Users who initialized at an older version and upgrade get the new coordinator brain (squad.agent.md) but are missing the environment it expects — merge drivers, gitignore entries, skill templates, directories, and reference templates.
Gaps Found (ordered by severity)
🔴 Blocking
| # | Gap | Impact |
|---|---|---|
| 1 | .gitattributes merge drivers never added on upgrade |
Users get merge conflicts on append-only files (decisions.md, history.md, logs) |
| 2 | .gitignore entries never added on upgrade |
Runtime state (orchestration-log/, log/, decisions/inbox/, sessions/) gets committed |
| 3 | Only 1 of 21 skills synced to .copilot/skills/ |
20 skills missing for upgraders (agent-collaboration, ci-validation-gates, test-discipline, etc.) |
| 4 | .squad/templates/ directory never refreshed on upgrade |
New templates (issue-lifecycle.md, etc.) never reach existing users |
| 5 | Missing directories never created (identity/, orchestration-log/, sessions/, .copilot/skills/) | Users from older versions stuck without required directories |
| 6 | "Already current" path skips entire TEMPLATE_MANIFEST | Running upgrade twice doesn't fix deleted squad-owned files |
🟡 Notable
| # | Gap | Impact |
|---|---|---|
| 7 | issue-lifecycle.md (#527) not in TEMPLATE_MANIFEST or canonical source |
Won't reach upgrading users |
| 8 | personal-charter.md + ghost-protocol.md (#508) not in manifest |
Personal squad templates orphaned |
| 9 | 5 files in .squad-templates/ not in manifest (ralph-circuit-breaker.md, ralph-triage.js, casting-reference.md, etc.) |
Canonical source orphaned from delivery pipeline |
| 10 | No --force flag for repair scenarios |
Users can't force re-apply templates |
| 11 | --global (personal squad) upgrade path untested |
No validation of expected directory shape |
| 12 | Version detection fragile — single source (HTML comment in squad.agent.md) | Corruption causes all migrations to re-run |
| 13 | Workflow stubs overwrite user customizations unconditionally | Non-npm users lose their CI config on every upgrade |
Root Cause
The upgrade handler (packages/squad-cli/src/cli/core/upgrade.ts) only processes files in TEMPLATE_MANIFEST (defined in templates.ts). The manifest has 33 entries — 29 squad-owned, 4 user-owned. Anything not in the manifest is invisible to upgrade, even if it ships in the templates directory and is deployed by init.
The delivery pipeline is: .squad-templates/ → sync-templates.mjs → packages/*/templates/ → TEMPLATE_MANIFEST → upgrade. Files that skip any step are orphaned.
Proposed Fix
- Add
ensureGitattributes()to upgrade — append merge=union rules if missing - Add
ensureGitignore()to upgrade — append runtime state ignores if missing - Add
ensureDirectories()to upgrade — create missing dirs (identity/, orchestration-log/, sessions/, .copilot/skills/) - Refresh
.squad/templates/from package templates on every upgrade (not just init) - Sync all skills from package
skills/→.copilot/skills/(not just squad-conventions) - Add missing files to TEMPLATE_MANIFEST: issue-lifecycle.md, personal-charter.md, ghost-protocol.md, ralph-circuit-breaker.md, casting-reference.md
- Add missing files to
.squad-templates/canonical source - Make "already current" path also process TEMPLATE_MANIFEST (or at minimum, run ensureX checks)
- Add
--forceflag to re-apply all templates regardless of version - Add tests for upgrade scenarios (fresh → current, old → new, already current, --global)
Audit Sources
- EECOM traced complete file operation list from cli-entry.ts → upgrade.ts → templates.ts
- FIDO found 13 gaps via adversarial analysis, identified test coverage weakness
- Procedures mapped the full template delivery pipeline and produced feature-by-feature delivery matrix
Activity
fix: upgrade path ensures gitattributes, gitignore, dirs, skills, tem…
fix: P0 upgrade path gaps (github#544)