feat: auto-remap codebase after significant phase execution (closes #2003)

[trek-e]

Closes #2003

Summary

Adds a post-execute structural drift detector. After the last wave of
/gsd:execute-phase commits, the workflow compares the diff between
last_mapped_commit (stored in YAML frontmatter on each
.planning/codebase/*.md map file) and HEAD against the contents of
.planning/codebase/STRUCTURE.md. When the number of new structural
elements meets the configured threshold, GSD either warns the user or
auto-remaps the affected subtrees.

Four drift categories, with priority ordering (migration > route > barrel > new_dir) so each file is counted once at the most specific
level:

1. New directory outside mapped paths
2. New barrel export at (packages|apps)/<name>/src/index.*
3. New migration file (supabase / prisma / drizzle / src/migrations / …)
4. New route module under routes/ or api/

Non-blocking by contract. Four layers (detector try/catch, CLI
try/catch, SDK handler try/catch, workflow || echo fallback) ensure any
failure path — missing STRUCTURE.md, non-git cwd, mapper spawn failure,
invalid config — returns { skipped: true } and the phase continues to
verification. Drift detection cannot fail /gsd:execute-phase.

Changes

• Detector library — get-shit-done/bin/lib/drift.cjs (new). Pure:
  accepts parsed git-diff input + STRUCTURE.md content, returns a
  structured result. Exports classifyFile, detectDrift,
  chooseAffectedPaths, sanitizePaths, readMappedCommit,
  writeMappedCommit.
• CLI — verify codebase-drift subcommand in gsd-tools.cjs,
  implemented by cmdVerifyCodebaseDrift in verify.cjs.
• SDK — verifyCodebaseDrift handler in sdk/src/query/verify.ts,
  registered as verify.codebase-drift in sdk/src/query/index.ts.
  Delegates to the CJS implementation to keep drift logic in one place.
• Config — workflow.drift_threshold (integer, default 3) and
  workflow.drift_action (warn | auto-remap, default warn) added
  to VALID_CONFIG_KEYS with enum/integer validation in config-set.
• Workflow — new codebase_drift_gate step in execute-phase.md
  between schema_drift_gate and verify_phase_goal.
• Mapper — --paths <p1,p2,...> scope hint documented in both
  agents/gsd-codebase-mapper.md and get-shit-done/workflows/map-codebase.md,
  with traversal / absolute / metacharacter rejection.
• Frontmatter round-trip — last_mapped_commit stored at the top of
  each .planning/codebase/*.md file.

Documentation

• docs/CONFIGURATION.md — rows for both new keys (docs-parity passes).
• docs/ARCHITECTURE.md — post-execute drift gate section.
• docs/AGENTS.md — --paths flag on gsd-codebase-mapper.
• docs/USER-GUIDE.md — behavior note + toggle commands.
• docs/FEATURES.md — new 27a section with REQ-DRIFT-01..06.
• docs/INVENTORY.md + docs/INVENTORY-MANIFEST.json — drift.cjs
  listed (count 26 → 27).

Tests

• tests/drift-detection.test.cjs (new) — 55 tests: classification,
  threshold gating at 2/3/4 elements, warn vs. auto-remap routing,
  affected-path scoping, --paths sanitization, frontmatter
  round-trip, defensive paths (missing STRUCTURE.md, malformed input,
  non-git repos), CLI JSON output, documentation parity.
• Full suite: 5044 pass / 0 fail.

Design decisions

• Frontmatter over sidecar JSON for last_mapped_commit: travels
  with git moves, survives per-document regeneration, no separate file
  lifecycle.
• Substring match against STRUCTURE.md for isPathMapped: the map
  is free-form markdown, not a structured manifest. Cheap, no parser.
• Category priority migration > route > barrel > new_dir: each
  file counts once at the most specific level.
• Empty-tree SHA fallback (4b825dc6…) when last_mapped_commit
  is absent: "no baseline means everything is drift," deterministic.
• Four layers of non-blocking — detector / CLI / SDK / workflow
  all wrap their logic so any single layer failing still produces a
  valid skipped result.
• SDK handler delegates to gsd-tools.cjs rather than re-porting
  the detector to TypeScript, keeping drift logic in one canonical
  place.

Test plan

• npm test — full suite green
• node --test tests/drift-detection.test.cjs — 55 new tests pass
• Manual: project with .planning/codebase/STRUCTURE.md →
  gsd-sdk query verify.codebase-drift returns
  action_required: false immediately after mapping
• Manual: introduce 3+ new barrels → rerun → action_required: true
  with directive: warn
• Manual: set workflow.drift_action=auto-remap → rerun → confirm
  spawn_mapper: true and affected_paths populated
• config-set workflow.drift_action sometimes rejected;
  config-set workflow.drift_threshold many rejected

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Incremental path-scoped codebase mapping via an optional --paths hint and a non-blocking post-execution drift detector that can warn or auto-remap affected subtrees.
  • New verify subcommand to check for codebase structural drift.

• Documentation

  • Updated guides, architecture, workflows, and feature docs to describe drift detection, incremental mapping, config keys, and non-blocking behavior.

• Tests

  • Added comprehensive tests for drift detection, path sanitization, config validation, and CLI integration.

• Chores

  • Inventory/manifest updated to register drift tooling.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Adds a non-blocking post-execution codebase drift detector and an incremental remap flow: a new drift library and verify command detect structural changes vs .planning/codebase/STRUCTURE.md, annotate mapping files with last_mapped_commit, and optionally auto-spawn the mapper with a validated --paths hint.

Changes

Cohort / File(s)	Summary
Core drift detection library get-shit-done/bin/lib/drift.cjs	New module classifying added files into drift categories, sanitizing and collapsing affected paths, computing action directives, and reading/writing last_mapped_commit frontmatter.
Verification command & SDK integration get-shit-done/bin/lib/verify.cjs, sdk/src/query/verify.ts, sdk/src/query/index.ts	Adds verify codebase-drift CLI handler and SDK query verify.codebase-drift to run non-blocking drift detection and return structured JSON results.
Workflows & mapper prompts get-shit-done/workflows/execute-phase.md, get-shit-done/workflows/map-codebase.md, agents/gsd-codebase-mapper.md	Execute-phase adds a non-blocking drift gate with optional auto-remap spawn; map-codebase introduces --paths parsing/validation and propagates scope hints to mapper prompts; mapper docs updated to accept --paths.
Configuration & CLI get-shit-done/bin/lib/config.cjs, get-shit-done/bin/lib/config-schema.cjs, get-shit-done/bin/gsd-tools.cjs	Adds workflow.drift_threshold and workflow.drift_action keys with validation and CLI verify codebase-drift subcommand routing.
Tests tests/drift-detection.test.cjs	Comprehensive unit and integration tests for file classification, detectDrift behavior, sanitization, frontmatter read/write, config validation, and CLI integration.
Docs & inventory docs/AGENTS.md, docs/ARCHITECTURE.md, docs/CONFIGURATION.md, docs/FEATURES.md, docs/USER-GUIDE.md, docs/INVENTORY-MANIFEST.json, docs/INVENTORY.md	Documentation updates describing the drift gate, config keys, mapper --paths, last_mapped_commit frontmatter, and inventory/manifest additions.

Sequence Diagram

sequenceDiagram
    participant Client
    participant ExecutePhase as Execute Phase
    participant DriftVerifier as Drift Verifier (verify tool)
    participant GitRepo as Git Repo
    participant StructureFile as STRUCTURE.md
    participant DriftDetector as Drift Detector (drift.cjs)
    participant Config as Config
    participant Mapper as GSD Mapper (auto-remap)

    Client->>ExecutePhase: /gsd:execute-phase completes
    ExecutePhase->>DriftVerifier: query verify.codebase-drift
    DriftVerifier->>StructureFile: read .planning/codebase/STRUCTURE.md
    StructureFile-->>DriftVerifier: content + last_mapped_commit
    DriftVerifier->>GitRepo: git diff last_mapped_commit..HEAD
    GitRepo-->>DriftVerifier: list of changed file paths
    DriftVerifier->>DriftDetector: detectDrift({files, structureMd, threshold})
    DriftDetector->>DriftDetector: classify files, sanitize/collapse paths
    DriftDetector-->>DriftVerifier: {actionRequired, directive, affectedPaths, message}
    DriftVerifier->>Config: read workflow.drift_action
    Config-->>DriftVerifier: 'warn' or 'auto-remap'
    alt action_required && directive == 'auto-remap'
        DriftVerifier->>Mapper: spawn gsd-codebase-mapper --paths [affectedPaths]
        Mapper->>StructureFile: update .planning/codebase/*.md
        StructureFile->>StructureFile: write last_mapped_commit: HEAD
    else action_required && directive == 'warn'
        DriftVerifier-->>Client: warning with suggested /gsd-map-codebase --paths
    end
    DriftVerifier-->>ExecutePhase: result (non-blocking)
    ExecutePhase->>Client: continue to verify_phase_goal

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(sdk): GSDTools native dispatch helpers and CJS fallback routing (#2302 Track C) #2342 — touches SDK query/registry surfaces related to verify handler registration.
• fix: correct VALID_CONFIG_KEYS — remove internal state key, add missing public keys, migration hints #2561 — modifies config-key whitelist; overlaps with adding drift config keys.
• docs: close doc drift vectors — bidirectional parity, manifest, schema-driven config #2479 — related changes to configuration schema/VALID_CONFIG_KEYS.

Suggested labels

area: core, review: needs discussion

Suggested reviewers

• glittercowboy

Poem

🐰 I hopped through diffs with eager paws,

found new paths, barrels, migrations and laws.
A little hint, a scoped remap dance—
commit in hand, we give mapping a chance.
Hop, remap, sync: the repo sings—✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.59% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding structural drift detection with auto-remapping capability after phase execution.
Description check	✅ Passed	The pull request description comprehensively covers the feature with summary, changes, documentation, tests, design decisions, and test plan.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from #2003: structural drift detection comparing committed files against STRUCTURE.md, four drift categories (new directories, barrel exports, migrations, routes), configurable threshold triggering, and auto-remap vs warn actions.
Out of Scope Changes check	✅ Passed	All changes are scoped to the drift detection feature: detector library, CLI/SDK handlers, config validation, workflow integration, mapper path hints, frontmatter utilities, tests, and documentation updates directly support the #2003 objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/2003-codebase-drift-detector

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

get-shit-done/bin/lib/drift.cjs (1)

349-355: Potential issue: writeMappedCommit throws if file doesn't exist.

Unlike readMappedCommit which catches the exception and returns null, writeMappedCommit will throw if the file doesn't exist (line 350's readFileSync). This is likely intentional since you'd only call writeMappedCommit after the mapper has produced the file, but the asymmetry is worth noting.

If this is intentional (callers must ensure file exists), consider adding a brief comment. If it should be defensive, wrap in try/catch.

💡 Optional: Add defensive file existence check

 function writeMappedCommit(filePath, commitSha, isoDate) {
+  if (!fs.existsSync(filePath)) {
+    // Create minimal file with frontmatter only
+    const data = { last_mapped_commit: commitSha };
+    if (isoDate) data.last_mapped_at = isoDate;
+    fs.writeFileSync(filePath, serializeFrontmatter(data, ''));
+    return;
+  }
   const content = fs.readFileSync(filePath, 'utf8');

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@get-shit-done/bin/lib/drift.cjs` around lines 349 - 355, writeMappedCommit
currently calls fs.readFileSync(filePath, 'utf8') and will throw if the file is
missing, creating an asymmetry with readMappedCommit which returns null on
missing files; either document the intended precondition or make it defensive by
checking existence or catching ENOENT: update writeMappedCommit (and its callers
if needed) so it first checks fs.existsSync(filePath) or wraps readFileSync in
try/catch, return a sensible value or no-op (or rethrow with clearer message)
when file is absent; reference the writeMappedCommit function and its use of
fs.readFileSync, fs.writeFileSync, parseFrontmatter and serializeFrontmatter
when making the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@agents/gsd-codebase-mapper.md`:
- Around line 101-103: The fenced code block containing the line "--paths
<p1>,<p2>,..." triggers MD040; add a language tag to the opening ``` fence (for
example "text") so the block becomes ```text and resolves the lint rule,
updating the block that contains the exact string "--paths <p1>,<p2>,..." in
agents/gsd-codebase-mapper.md.

In `@docs/CONFIGURATION.md`:
- Line 170: The docs row for workflow.drift_action uses colon-style command
tokens `/gsd:execute-phase` and `/gsd:map-codebase` which is inconsistent with
the rest of the guide; update those tokens to the standard space-separated
command format (e.g., `/gsd execute-phase` and `/gsd map-codebase --paths …`)
and keep them in inline code/backticks so the config key workflow.drift_action
and related workflow.drift_threshold text matches the repo's existing command
formatting.

In `@get-shit-done/workflows/execute-phase.md`:
- Around line 1296-1309: The two new fenced code blocks in
get-shit-done/workflows/execute-phase.md are missing language identifiers and
trigger markdownlint MD040; update both blocks by adding a language tag (use
"text") after the opening backticks—one for the block starting with "Codebase
drift detected: {N} structural element(s)..." and the other for the block
starting with "Task("—repeat the same fix for the second occurrence around lines
1316-1328.
- Line 1326: The auto-remap prompt references the undefined placeholder
AGENT_SKILLS_MAPPER which can leak into runtime; either define
AGENT_SKILLS_MAPPER (e.g., build it from the initialized AGENT_SKILLS
array/mapping) before the prompt or remove the placeholder from the template and
directly use AGENT_SKILLS; update the code that constructs the prompt to replace
"${AGENT_SKILLS_MAPPER}" with a real string (for example by adding a
mapper-building step that iterates AGENT_SKILLS and assigns the result to
AGENT_SKILLS_MAPPER) so the prompt never contains the literal placeholder.

In `@get-shit-done/workflows/map-codebase.md`:
- Around line 30-47: The workflow defines incremental-remap semantics in the
parse_paths_flag step but doesn't create a single normalized variable to
propagate validated paths to mappers; add a normalized shell variable (e.g.,
SCOPED_PATHS) that holds the validated comma-separated prefixes (or empty),
compute a PATH_SCOPE_HINT="--paths $SCOPED_PATHS" only when SCOPED_PATHS is
non-empty, and ensure every place that launches mappers (notably the
spawn_agents and sequential_mapping routines and any Task-mode prompt
construction that invokes gsd-codebase-mapper) appends ${PATH_SCOPE_HINT} into
the agent prompt/command so all spawned mappers receive the same deterministic
scope; keep the existing validation rules (reject .., leading /, shell
metacharacters) and preserve stamping behavior via
bin/lib/drift.cjs:writeMappedCommit.

---

Nitpick comments:
In `@get-shit-done/bin/lib/drift.cjs`:
- Around line 349-355: writeMappedCommit currently calls
fs.readFileSync(filePath, 'utf8') and will throw if the file is missing,
creating an asymmetry with readMappedCommit which returns null on missing files;
either document the intended precondition or make it defensive by checking
existence or catching ENOENT: update writeMappedCommit (and its callers if
needed) so it first checks fs.existsSync(filePath) or wraps readFileSync in
try/catch, return a sensible value or no-op (or rethrow with clearer message)
when file is absent; reference the writeMappedCommit function and its use of
fs.readFileSync, fs.writeFileSync, parseFrontmatter and serializeFrontmatter
when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8fe5d8c0-c253-422c-ae3e-c12595094a14

📥 Commits

Reviewing files that changed from the base of the PR and between 1f2850c and f48fe7d.

📒 Files selected for processing (18)

• agents/gsd-codebase-mapper.md
• docs/AGENTS.md
• docs/ARCHITECTURE.md
• docs/CONFIGURATION.md
• docs/FEATURES.md
• docs/INVENTORY-MANIFEST.json
• docs/INVENTORY.md
• docs/USER-GUIDE.md
• get-shit-done/bin/gsd-tools.cjs
• get-shit-done/bin/lib/config-schema.cjs
• get-shit-done/bin/lib/config.cjs
• get-shit-done/bin/lib/drift.cjs
• get-shit-done/bin/lib/verify.cjs
• get-shit-done/workflows/execute-phase.md
• get-shit-done/workflows/map-codebase.md
• sdk/src/query/index.ts
• sdk/src/query/verify.ts
• tests/drift-detection.test.cjs

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix command name formatting in the new drift-action docs.

The new row uses : command syntax, which is inconsistent with the rest of the docs and likely to mislead copy/paste usage.

✏️ Suggested doc fix

-| `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded after `/gsd:execute-phase`. `warn` prints a message suggesting `/gsd:map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. Added in v1.39 |
+| `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded after `/gsd-execute-phase`. `warn` prints a message suggesting `/gsd-map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. Added in v1.39 |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded after `/gsd:execute-phase`. `warn` prints a message suggesting `/gsd:map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. Added in v1.39 |
	| `workflow.drift_action` | string | `warn` | What to do when `workflow.drift_threshold` is exceeded after `/gsd-execute-phase`. `warn` prints a message suggesting `/gsd-map-codebase --paths …`; `auto-remap` spawns `gsd-codebase-mapper` scoped to the affected paths. Added in v1.39 |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/CONFIGURATION.md` at line 170, The docs row for workflow.drift_action
uses colon-style command tokens `/gsd:execute-phase` and `/gsd:map-codebase`
which is inconsistent with the rest of the guide; update those tokens to the
standard space-separated command format (e.g., `/gsd execute-phase` and `/gsd
map-codebase --paths …`) and keep them in inline code/backticks so the config
key workflow.drift_action and related workflow.drift_threshold text matches the
repo's existing command formatting.

[trek-e]

CodeRabbit review response (review id 4158286952)

Finding	Severity	Action	Commit / Reason
agents/gsd-codebase-mapper.md:101-103 — fenced block missing language (MD040)	Minor	Fixed	547c492 — tag fence as ```text
docs/CONFIGURATION.md:170 — drift_action row uses /gsd: colon syntax inconsistent with rest of docs	Minor	Fixed	447f67b — switched to /gsd-execute-phase / /gsd-map-codebase
get-shit-done/workflows/execute-phase.md:1296-1328 — two new fenced blocks missing language (MD040)	Minor	Fixed	ced212d — tagged both as ```text
get-shit-done/workflows/execute-phase.md:1326 — ${AGENT_SKILLS_MAPPER} referenced but never initialized; would leak literal placeholder into mapper prompt	Major	Fixed	ced212d — added AGENT_SKILLS_MAPPER=$(gsd-sdk query agent-skills gsd-codebase-mapper 2>/dev/null || true) next to the existing AGENT_SKILLS initialization
get-shit-done/workflows/map-codebase.md:30-47 — --paths propagation not deterministic across spawn_agents/sequential_mapping	Major	Fixed	f12e83f — defined SCOPED_PATHS + PATH_SCOPE_HINT in parse_paths_flag; injected ${PATH_SCOPE_HINT} into all four spawn_agents Task prompts and added an explicit scope contract to sequential_mapping
get-shit-done/bin/lib/drift.cjs:349-355 — writeMappedCommit throws ENOENT while readMappedCommit returns null (asymmetric)	Nitpick	Fixed	36b31ba — caught ENOENT on the read so absent files are treated as empty content; added regression test (writeMappedCommit creates the file when it does not exist) authored to fail before the fix and pass after

Verification: npm run test:coverage — 5045 tests pass, drift.cjs at 98.14% line coverage.