gstack-upgrade: tracked files not overwritten, VERSION frozen across upgrades
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
When `gstack` is installed inside a parent git repo that also tracks the gstack files as plain files (mode 100644), `gstack-upgrade` successfully pulls new commits but **only new files persist** — existing tracked files like `VERSION` and `package.json` get reverted by the parent repo's git on every branch switch.
This leaves the install in a half-upgraded state where `VERSION` reports the old version despite repeated successful upgrades.
## Root cause
The parent repo commits gstack files as plain files alongside the nested `.git` directory. When `gstack-upgrade` runs `git pull` / `git reset --hard` inside the nested repo, it correctly updates the working tree. But the parent repo's index still has the old file contents, so any `git checkout` / `git switch` in the parent reverts the files to whatever was originally committed.
**Only files that didn't exist in the original commit survive** — they're untracked in the parent and thus not reverted. This is why new features from later releases appear but `VERSION` stays frozen.
## Impact
- `VERSION` was stuck at `0.11.15.0` despite nested repo HEAD being at `v0.16.2.0` (pulled multiple times over weeks)
- Users are repeatedly offered upgrades they've already applied
- Installed code is a frankenstein of old tracked files + new untracked files with no coherent version
- Difficult to diagnose — git status looks clean in both repos
## Suggested fix
The `setup` script (or docs) should ensure `.claude/skills/gstack/` is added to the parent's `.gitignore` **before** committing any files. If the parent already tracks gstack files, `setup` could detect this (`git ls-files .claude/skills/gstack | wc -l > 0`) and warn the user to run `git rm --cached -r .claude/skills/gstack` first.
Additionally, `VERSION` and `package.json` version should agree — currently v0.17.0.0 shows `VERSION=0.17.0.0` but `package.json` still says `0.16.2.0`.
## Environment
- macOS (Apple Silicon)
- gstack v0.17.0.0 (commit 23000672)
- Parent repos: trading-dashboard, district-prospector
- Claude Code CLI
## Workaround applied
```bash
git rm --cached -r .claude/skills/gstack
echo '.claude/skills/gstack/' >> .gitignore
cd .claude/skills/gstack && git reset --hard origin/main
```
Contributor guide
Assessment
This issue has not been assessed yet.