GSD: auto-remap codebase after significant phase execution
Resolved 💬 2 comments Opened Apr 8, 2026 by looper86-ai Closed Apr 8, 2026
Problem
After executing a phase that adds significant new code (new packages, route modules, DB schema domains, frontend feature directories), the .planning/codebase/ mapping files go stale silently. Future planning agents then work from an outdated structural picture, leading to:
- Plans that miss existing patterns/conventions in new code
- Verification steps that don't know about new integration boundaries
- Research phases that rediscover what's already built
Currently, codebase mapping (/gsd-map-codebase) is a manual one-time setup step. There's no post-phase hook to detect structural drift.
Proposed Solution
Add a structural drift check at the end of the execute-phase workflow (or verify-work), after all plans complete:
- Compare committed files against
.planning/codebase/STRUCTURE.mdto detect:
- New directories outside existing mapped paths
- New barrel exports in
packages/*/src/index.tsorapps/*/src/index.ts - New migration files (migration count changed)
- New route modules registered in app entry points
- If drift exceeds a threshold (e.g., 3+ new structural elements), either:
- Auto-trigger a targeted remap of affected areas (preferred)
- Warn the user: "Phase 20 added 6 new structural elements. Run
/gsd-map-codebaseto update planning context."
- The remap could be incremental — only re-analyze changed packages/apps rather than full codebase scan.
Context
Discovered after Phase 20 (Chart of Accounts + Journal Engine) added:
- 2 new API route modules
- 4 new domain functions
- 2 new shared schemas
- 1 new DB schema file (4 tables)
- 6 new frontend feature files
- 1 new migration
The .planning/codebase/ maps from 2 days prior had zero awareness of any of it.
Alternatives
- Post-phase git diff summary that flags "these paths are outside mapped structure"
- A
stale_sincefield in each codebase map file, auto-bumped when mapped paths change
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗