Skip to content

ux: upgrade --migrate-directory should warn about git rename history loss and unstaged changes #126

New issue
New issue
Closed
Closed
ux: upgrade --migrate-directory should warn about git rename history loss and unstaged changes#126
Labels
go:needs-researchNeeds investigationpriority:p2Next sprintsquadSquad triage inbox — Lead will assign to a membertype:featureNew capability

Description

@bradygaster
bradygaster
opened on Feb 20, 2026

Problem

upgrade --migrate-directory uses fs.renameSync() to rename .ai-team/ → .squad/, which causes three silent git issues:

  1. History loss: Git sees the rename as a delete + add, not a move. git log --follow stops working for all files in the directory.
  2. Unstaged changes: The rename is not staged. Users may not realize they have uncommitted changes in the new location.
  3. Guard CI will block: The squad-main-guard workflow explicitly blocks .squad/** from main/preview branches. Users who commit .squad/ to a PR targeting main will hit a CI failure with no explanation.

Suggested Fix

After the migration completes, print clear guidance:

✓ Renamed .ai-team/ → .squad/

⚠️  Git note: this rename appears as delete+add in git history.
   To preserve file history, use: git mv .ai-team .squad (before running this command next time)

Next steps:
  git add -A
  git commit -m "chore: migrate .ai-team/ → .squad/"

Note: .squad/ should NOT be committed to main/preview — keep it on feature branches.

Additionally, consider using git mv via child_process instead of fs.renameSync when inside a git repo, which preserves rename tracking.

Found by: Kobayashi during 0.5.0 diagnostic investigation on SqncR.

Activity

  1. bradygaster
    added
    type:featureNew capability
    on Feb 20, 2026
  2. bradygaster
    added 4 commits that reference this issue on Feb 20, 2026

    chore: log 0.5.0 investigation session — bugs #124 #125 #126

    7c4e9b9

    fix: upgrade --migrate-directory now completes full upgrade (v0.5.2)

    efdc12a

    fix: upgrade --migrate-directory now completes full upgrade (v0.5.2)

    a7f7604

    fix: upgrade --migrate-directory now completes full upgrade (v0.5.2)

    bfe9ee4

  3. bradygaster commented on Feb 20, 2026

    @bradygaster
    bradygaster
    on Feb 20, 2026
    CollaboratorAuthor

    Partially addressed in v0.5.2: the migrations and .gitattributes\ rules now use the detected squad directory (e.g. .squad/) rather than hardcoding .ai-team/, so the core correctness issue is fixed. The remaining items in this issue — explicit post-migration warning messages and considering \git mv\ over \ s.renameSync\ — are UX enhancements. Keeping this open to track those improvements.

  4. bradygaster
    added
    release:deferDeferred past next release
    on Mar 6, 2026
  5. bradygaster
    added 2 commits that reference this issue on Mar 7, 2026

    docs(ai-team): Merge next-wave triage decisions, update agent history

    a811571

    fix: wire missing CLI commands into cli-entry.ts (#244)

    a488eb8
  6. bradygaster
    added
    squadSquad triage inbox — Lead will assign to a member
    squad:fenster
    release:v0.8.22Release v0.8.22
    on Mar 7, 2026

  7. github-actions commented on Mar 7, 2026

    @github-actions
    github-actionsBot
    on Mar 7, 2026 – with GitHub Actions
    Contributor

    🏷️ Release target updated → release:v0.8.22

  8. github-actions
    added
    squad:hockney
    and removed
    release:deferDeferred past next release
    on Mar 7, 2026

  9. 9 remaining items

  10. github-actions commented on Mar 9, 2026

    @github-actions
    github-actionsBot
    on Mar 9, 2026 – with GitHub Actions
    Contributor

    📋 Assigned to EECOM (Core Dev)

    Issue: #126 — ux: upgrade --migrate-directory should warn about git rename history loss and unstaged changes

    EECOM will pick this up in the next Copilot session.

    For Copilot coding agent: If enabled, this issue will be worked automatically.
    Otherwise, start a Copilot session and say:
    EECOM, work on issue #126

  11. bradygaster
    removed
    squad:fido
    squad:eecom
    on Mar 13, 2026

  12. bradygaster commented on Mar 13, 2026

    @bradygaster
    bradygaster
    on Mar 13, 2026
    CollaboratorAuthor

    📌 Brady requested this issue be assigned to @diberry (docs/UX triage). Pending collaborator invite to complete assignment.

  13. diberry commented on Mar 14, 2026

    @diberry
    diberry
    on Mar 14, 2026
    Contributor

    📋 Implementation Proposal: Solution D — Hybrid Smart Rename + Warnings

    Analyzed by: @diberry (PAO triage)

    Remaining work (per Brady's v0.5.2 comment — core bug fixed, UX enhancements remain):

    Approach: Try git mv .ai-team .squad when inside a git repo (preserves git log --follow). Fall back gracefully to fs.renameSync() when git is unavailable or fails. Always print enhanced warnings.

    Changes to migrate-directory.ts:

    1. Git repo detection — reuse execFileSync('git', ['rev-parse', ...]) pattern from init.ts
    2. Pre-flight dirty check — warn (not block) if .ai-team/ has uncommitted changes
    3. Smart rename — git mv first, fs.renameSync fallback on failure
    4. Enhanced post-migration output — history loss warning when git mv wasn't used, CI guard warning about main/preview branches

    No new CLI flags. No new dependencies (child_process already used in init.ts, gh-cli.ts). Graceful degradation — migration always completes.

    Test plan: 5 new tests covering git mv path, fallback path, dirty check warning, CI guard warning, and git mv failure recovery.

    Target file: packages/squad-cli/src/cli/core/migrate-directory.ts + test/cli/upgrade.test.ts

    Full PRD available on request. Ready for Core Dev pickup (Fenster/EECOM per existing triage).

  14. diberry commented on Mar 14, 2026

    @diberry
    diberry
    on Mar 14, 2026
    Contributor

    cc @bradygaster — implementation proposal above for the remaining UX enhancements. Ready for Core Dev assignment when you're ready.

  15. diberry commented on Mar 14, 2026

    @diberry
    diberry
    on Mar 14, 2026
    Contributor

    Coordination note: #197 overlap check

    Reviewed #197 (Improve migration experience — PR #199 by @williamhallatt). These are complementary, not overlapping:

    Dependency note for implementer: Before starting #126 work, check if PR #199 has merged. If so, verify migrate-directory.ts still exists as the active code path — the new squad migrate may eventually supersede it.

    Updated the PRD with this coordination section.

  16. diberry commented on Mar 14, 2026

    @diberry
    diberry
    on Mar 14, 2026
    Contributor

    PRD updated: Consolidated with #197 non-doc items

    The PRD for this issue now also covers the non-doc implementation work from #197:

    This gives a single implementation target for Core Dev. The PRD has two parts:

    Docs-only work (migration guide covering all install methods) stays in #197 for PAO.

    cc @bradygaster

  17. bradygaster
    added
    priority:p2Next sprint
    squad:eecom
    on Mar 15, 2026

  18. github-actions commented on Mar 15, 2026

    @github-actions
    github-actionsBot
    on Mar 15, 2026 – with GitHub Actions
    Contributor

    📋 Assigned to EECOM (Core Dev)

    Issue: #126 — ux: upgrade --migrate-directory should warn about git rename history loss and unstaged changes

    EECOM will pick this up in the next Copilot session.

    For Copilot coding agent: If enabled, this issue will be worked automatically.
    Otherwise, start a Copilot session and say:
    EECOM, work on issue #126

  19. bradygaster commented on Mar 15, 2026

    @bradygaster
    bradygaster
    on Mar 15, 2026
    CollaboratorAuthor

    Fixed! EECOM investigated and confirmed this was still a valid concern — the upgrade --migrate-directory command was still using fs.renameSync() without safety checks.

    The fix adds:

    • Git repository detection before migration
    • Unstaged changes detection (fatal abort if found in .ai-team/ or .ai-team-templates/)
    • Clear warning about git history implications — explains the delete+add vs rename trade-off
    • Recommendation to use git mv for history preservation

    Merged in commits c6f1ec9 and cda717e on dev with 2 new tests covering the warning and abort behaviors. Thanks for the original report, @bradygaster! 🔧

  20. bradygaster
    closed this as completedon Mar 15, 2026
  21. joniba
    added a commit that references this issue on Mar 26, 2026

    [squad] Clean up Frodo's charter — TI Domain Backend Engineer (github…

    31f5e5b
  22. bradygaster
    removed
    squad:eecom
    on Sep 11, 2026
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

    go:needs-researchNeeds investigationpriority:p2Next sprintsquadSquad triage inbox — Lead will assign to a membertype:featureNew capability

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions