feat: project-local .gstack/ data storage with auto-migration

[alfadb]

Summary

Moves project-scoped data from ~/.gstack/projects/$SLUG/ to {git-root}/.gstack/, enabling:

• Team collaboration: design docs, review logs, test plans are now git-tracked and visible to all team members
• Data portability: project data follows the repo when cloned to a new machine
• Clean separation: machine-local state (browse daemon, logs, caches) lives in .gstack/local/ (gitignored), shared data lives in .gstack/ root (tracked)
• Zero-friction migration: auto-migrates on first gstack use per project — handles both legacy global data AND existing flat-structure local files

Directory structure

{project}/.gstack/
├── {BRANCH}-reviews.jsonl      ← git-tracked
├── designs/                     ← git-tracked (design docs, architecture, audits)
├── plans/                       ← git-tracked (test plans, autoplan, eng review, CEO plans)
├── evals/                       ← git-tracked (E2E test baselines)
├── local/                       ← gitignored (machine-local)
│   ├── browse.json
│   ├── browse-*.log
│   └── repo-mode.json
├── .gitignore                   ← contains "local/" and ".migrated"
└── .migrated                    ← gitignored, marks auto-migration done

Auto-migration (two phases, fully automatic)

On first gstack skill invocation per project, the preamble runs gstack-migrate-local:

Phase 1 — Global → Local: ~/.gstack/projects/$SLUG/* → .gstack/{designs,plans,...}/
Phase 2 — Flat → Organized: .gstack/*-design-*.md → .gstack/designs/ (reorganize existing files in place)

• Deduplicates automatically (same-name files → keep the one in the subdirectory)
• Handles browse.json/logs → .gstack/local/, architecture docs, implementation plans, roadmaps
• Creates .migrated marker to skip on subsequent runs
• Manual: ~/.claude/skills/gstack/bin/gstack-migrate-local [--dry-run]

Changes

New files:

• bin/gstack-migrate-local: standalone migration script (idempotent, --dry-run supported)

Core infrastructure:

• bin/gstack-slug: new PROJECT_DATA_DIR output variable
• scripts/resolvers/preamble.ts + scripts/gen-skill-docs.ts: auto-runs migration in preamble

Data path updates:

• bin/gstack-review-log, bin/gstack-review-read, bin/gstack-repo-mode: use project-local paths
• browse/src/config.ts: browse state moves to .gstack/local/; .gitignore management creates .gstack/.gitignore instead of blanket exclusion
• test/helpers/eval-store.ts: evals write to .gstack/evals/
• All resolvers (utility.ts, design.ts, testing.ts, review.ts) and 12 .tmpl files updated
• All SKILL.md files regenerated

Backward compatibility

• Reads: all read paths check project-local first, fall back to ~/.gstack/projects/$SLUG/
• Writes: only write to project-local paths
• Auto-migration: runs once per project, idempotent, non-blocking on failure
• Browse daemon: old daemon auto-recovers on next invocation at new path

Breaking changes

• Running browse daemons will not be found after upgrade (auto-recovers on restart)
• Projects with .gstack/ in .gitignore will have that line removed and replaced with .gstack/.gitignore containing local/

---

Rebase status

Rebased on upstream v0.14.3.0 (2026-03-31). All upstream changes (Review Army, ship idempotency, scope drift) integrated cleanly. SKILL.md regenerated post-rebase.

Merge conflict analysis (updated 2026-03-31)

Reviewed open PRs for file-level overlap against current diff (55 files, 10 commits).

Resolved since last analysis

• fix(security): validate JSON input in gstack-review-log #472 (JSON validation for review-log) — merged into v0.14.1.0, no longer a conflict
• fix(browse): use launchPersistentContext for working extension support + cookie persistence #440 (launchPersistentContext) — merged, no longer a conflict
• Add bin/ to .gitignore and remove tracked binaries #445 (add bin/ to .gitignore) — merged, no longer a conflict

Current potential overlaps

PR	Conflict files	Risk
#684 (fix ship reruns)	ship/SKILL.md.tmpl	Low — they fix idempotency (already in v0.14.3.0), we change data paths
#685 (preview deploy)	ship/SKILL.md.tmpl	Low — adds new step, different area from our path changes
#632 (ship log)	bin/ scripts	Low — new file, no overlap with our bin changes
#634 (GitLab land-and-deploy)	land-and-deploy/SKILL.md.tmpl	Low — adds GitLab support, different lines from our path changes
#664 (browse security fixes)	browse/src/config.ts	Medium — both modify config resolution, but different functions

No other open PR addresses project-local data storage. This PR remains unique in scope.

Test plan

• bun run gen:skill-docs generates all SKILL.md files successfully
• bun test passes (only pre-existing "Contributor mode" failures, unrelated)
• gstack-slug outputs 3 variables: SLUG, BRANCH, PROJECT_DATA_DIR
• All .tmpl legacy path references are in fallback positions only (verified via grep)
• gstack-migrate-local --dry-run correctly identifies files to migrate
• Migration tested on real project — both phases work correctly
• Rebased cleanly on v0.14.3.0 (Review Army + ship idempotency + scope drift)
• SKILL.md regenerated post-rebase, all resolver outputs correct

🤖 Generated with Claude Code

[alfadb]

Merge conflict analysis (updated)

Reviewed all 50 open PRs for file-level overlap. 8 PRs intersect with this one:

High risk (manual merge needed)

PR	Conflict files	Nature
#472 (JSON validation for review-log)	bin/gstack-review-log	They add JSON validation, we change the write path. Both changes should coexist: validate → write to $PROJECT_DATA_DIR
#440 (launchPersistentContext + cookie persistence)	browse/src/config.ts	They add storageFile path + cookie persistence, we restructure stateDir to .gstack/local/. Needs careful merge — both modify resolveConfig() and ensureStateDir()
#445 (add bin/ to .gitignore)	bin/gstack-slug, bin/gstack-review-log, bin/gstack-review-read, bin/gstack-repo-mode	They git rm --cached all bin/ scripts. Structural conflict — if they go first, our bin changes need to be re-added after

Medium risk (different lines, likely auto-merge)

PR	Conflict files	Nature
#471 (Codex -C flag)	scripts/resolvers/design.ts, review.ts	Different lines: codex exec flags vs data paths
#470 (temp file cleanup)	scripts/resolvers/design.ts, review.ts	Different lines: rm -f cleanup vs path changes
#500/#501 (install root inference)	scripts/gen-skill-docs.ts	Different areas: setup/install logic vs preamble/path changes

Low risk (cosmetic overlap)

PR	Conflict files	Nature
#452 (review section in CLAUDE.md)	docs/skills.md	Different lines
#416 (community telemetry)	scripts/gen-skill-docs.ts	Large PR but touches telemetry, not data paths. Needs regen (bun run gen:skill-docs) after rebase

No overlap

No other PR addresses project-local data storage or the ~/.gstack/projects/ → .gstack/ migration. This PR is unique in scope.

Happy to rebase against any of these after they land.

[alfadb]

Rebased on upstream v0.14.3.0 (2026-03-31). All 3 upstream commits (Review Army, ship idempotency, scope drift) integrated cleanly — no conflicts. SKILL.md regenerated post-rebase.

Updated PR description with current merge conflict analysis. Previous conflicts (#472, #440, #445) have all been merged upstream and are no longer relevant.