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:

  1. Compare committed files against .planning/codebase/STRUCTURE.md to detect:
  • New directories outside existing mapped paths
  • New barrel exports in packages/*/src/index.ts or apps/*/src/index.ts
  • New migration files (migration count changed)
  • New route modules registered in app entry points
  1. 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-codebase to update planning context."
  1. 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_since field in each codebase map file, auto-bumped when mapped paths change

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗