gsd-pi 2.67.0-dev.43b0159 → 2.67.0-dev.a5b1d8f

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -73,7 +73,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
-  { cmd: "codebase", desc: "Generate and manage codebase map (.gsd/CODEBASE.md)" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -237,7 +237,7 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
     { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" },
     { cmd: "generate --collapse-threshold", desc: "Generate with custom collapse threshold (default: 20)" },
-    { cmd: "update", desc: "Incremental update (preserves descriptions)" },
+    { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately (preserves descriptions)" },
     { cmd: "update --max-files", desc: "Update with custom file limit" },
     { cmd: "update --collapse-threshold", desc: "Update with custom collapse threshold" },
     { cmd: "stats", desc: "Show file count, description coverage, and generation time" },

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -45,6 +45,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "",
     "PROJECT KNOWLEDGE",
     "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
     "SETUP & CONFIGURATION",
     "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",

package/src/resources/extensions/gsd/commands-bootstrap.ts

@@ -45,6 +45,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "start", desc: "Start a workflow template" },
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions" },
+  { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache" },
 ] as const;
 
 function filterStartsWith(
@@ -218,6 +219,15 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "extensions");
   }
 
+  if (parts[0] === "codebase" && parts.length <= 2) {
+    return filterStartsWith(partial, [
+      { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
+      { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately" },
+      { cmd: "stats", desc: "Show codebase-map coverage and generation time" },
+      { cmd: "help", desc: "Show usage and subcommands" },
+    ], "codebase");
+  }
+
   if (parts[0] === "doctor" && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "fix", desc: "Auto-fix detected issues" },

package/src/resources/extensions/gsd/commands-codebase.ts

@@ -20,10 +20,11 @@ import type { CodebaseMapOptions } from "./codebase-generator.js";
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
   "  generate [--max-files N] [--collapse-threshold N]  — Generate or regenerate CODEBASE.md\n" +
-  "  update [--max-files N] [--collapse-threshold N]    — Incremental update (preserves descriptions)\n" +
+  "  update [--max-files N] [--collapse-threshold N]    — Refresh the CODEBASE.md cache immediately\n" +
   "  stats                                              — Show file count, coverage, and generation time\n" +
   "  help                                               — Show this help\n\n" +
-  "With no subcommand, shows stats if a map exists or help if not.\n\n" +
+  "With no subcommand, shows stats if a map exists or help if not.\n" +
+  "GSD also refreshes CODEBASE.md automatically before prompt injection and after completed units when tracked files change.\n\n" +
   "Configure defaults via preferences.md:\n" +
   "  codebase:\n" +
   "    exclude_patterns: [\"docs/\", \"fixtures/\"]\n" +
@@ -141,7 +142,7 @@ function showStats(basePath: string, ctx: ExtensionCommandContext): void {
     `  Undescribed: ${stats.undescribedCount}\n` +
     `  Generated: ${stats.generatedAt ?? "unknown"}\n\n` +
     (stats.undescribedCount > 0
-      ? `Tip: Run /gsd codebase update to refresh after file changes.`
+      ? `Tip: Auto-refresh keeps the cache current, but /gsd codebase update forces an immediate refresh.`
       : `Coverage is complete.`),
     "info",
   );

package/src/resources/extensions/gsd/prompts/system.md

@@ -62,6 +62,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
   REQUIREMENTS.md       (requirement contract - tracks active/validated/deferred/out-of-scope)
   DECISIONS.md          (append-only register of architectural and pattern decisions)
   KNOWLEDGE.md          (append-only register of project-specific rules, patterns, and lessons learned)
+  CODEBASE.md           (generated codebase map cache — auto-refreshed when tracked files change)
   OVERRIDES.md          (user-issued overrides that supersede plan content via /gsd steer)
   QUEUE.md              (append-only log of queued milestones via /gsd queue)
   STATE.md
@@ -104,6 +105,7 @@ In all modes, slices commit sequentially on the active branch; there are no per-
 - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change.
 - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made
 - **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow.
+- **CODEBASE.md** is a generated structural cache of the tracked repository. GSD auto-refreshes it when tracked files change and injects it into system context when available. Use `/gsd codebase update` only when you need to force an immediate refresh.
 - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing.
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.
@@ -131,6 +133,7 @@ Templates showing the expected format for each artifact type are in:
 - `/gsd status` - progress dashboard overlay
 - `/gsd queue` - queue future milestones (safe while auto-mode is running)
 - `/gsd quick <task>` - quick task with GSD guarantees (atomic commits, state tracking) but no milestone ceremony
+- `/gsd codebase [generate|update|stats]` - manage the `.gsd/CODEBASE.md` cache used for prompt context
 - `{{shortcutDashboard}}` - toggle dashboard overlay
 - `{{shortcutShell}}` - show shell processes
 

package/src/resources/extensions/gsd/tests/codebase-generator.test.ts

@@ -8,11 +8,13 @@ import { execSync } from "node:child_process";
 
 import {
   parseCodebaseMap,
+  parseCodebaseMapMetadata,
   generateCodebaseMap,
   updateCodebaseMap,
   writeCodebaseMap,
   readCodebaseMap,
   getCodebaseMapStats,
+  ensureCodebaseMapFresh,
 } from "../codebase-generator.ts";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────
@@ -212,6 +214,24 @@ test("generateCodebaseMap: preserves existing descriptions", () => {
   }
 });
 
+test("generateCodebaseMap: writes freshness metadata comment", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+
+    const result = generateCodebaseMap(base);
+    const metadata = parseCodebaseMapMetadata(result.content);
+
+    assert.ok(metadata, "metadata comment should be present");
+    assert.equal(metadata?.fileCount, 1);
+    assert.equal(metadata?.truncated, false);
+    assert.equal(typeof metadata?.fingerprint, "string");
+    assert.ok(metadata?.generatedAt?.endsWith("Z"));
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("generateCodebaseMap: collapses large directories", () => {
   const base = makeTmpRepo();
   try {
@@ -571,3 +591,51 @@ test("updateCodebaseMap: respects excludePatterns option", () => {
     cleanup(base);
   }
 });
+
+test("ensureCodebaseMapFresh: generates CODEBASE.md when missing", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+
+    const result = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    const written = readCodebaseMap(base);
+
+    assert.equal(result.status, "generated");
+    assert.ok(written?.includes("`src/main.ts`"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("ensureCodebaseMapFresh: updates CODEBASE.md when tracked files change", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+    const initial = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    assert.equal(initial.status, "generated");
+
+    addFile(base, "src/new.ts");
+    const refreshed = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    const written = readCodebaseMap(base);
+
+    assert.equal(refreshed.status, "updated");
+    assert.equal(refreshed.reason, "files-changed");
+    assert.ok(written?.includes("`src/new.ts`"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("ensureCodebaseMapFresh: returns fresh when metadata matches repository state", () => {
+  const base = makeTmpRepo();
+  try {
+    addFile(base, "src/main.ts");
+    ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+
+    const refreshed = ensureCodebaseMapFresh(base, undefined, { ttlMs: 0, force: true });
+    assert.equal(refreshed.status, "fresh");
+    assert.equal(refreshed.fileCount, 1);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -35,6 +35,13 @@ test("workflow-start prompt defaults to autonomy instead of per-phase confirmati
   assert.doesNotMatch(prompt, /Gate between phases/i);
 });
 
+test("system prompt references CODEBASE.md and /gsd codebase", () => {
+  const prompt = readPrompt("system");
+  assert.match(prompt, /CODEBASE\.md/);
+  assert.match(prompt, /\/gsd codebase \[generate\|update\|stats\]/);
+  assert.match(prompt, /auto-refreshes it when tracked files change/i);
+});
+
 test("discuss prompt allows implementation questions when they materially matter", () => {
   const prompt = readPrompt("discuss");
   assert.match(prompt, /Lead with experience, but ask implementation when it materially matters/i);

package/src/resources/extensions/gsd/tests/update-command.test.ts

@@ -65,3 +65,22 @@ test("/gsd update is listed in completions with correct description", () => {
     "completion description should mention updating",
   );
 });
+
+test("/gsd codebase appears in top-level completions", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  const completions = gsd.getArgumentCompletions("code");
+  const codebaseEntry = completions.find((c: any) => c.value === "codebase");
+  assert.ok(codebaseEntry, "codebase should appear in completions");
+  assert.match(codebaseEntry.description, /codebase map cache/i);
+});
+
+test("/gsd codebase appears in help description", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  assert.ok(gsd?.description?.includes("codebase"), "description should mention codebase");
+});

package/src/resources/extensions/gsd/workflow-reconcile.ts

@@ -249,11 +249,6 @@ export function extractEntityKey(
         ? { type: "slice", id: p["sliceId"] }
         : null;
 
-    case "complete_milestone":
-      return typeof p["milestoneId"] === "string"
-        ? { type: "milestone", id: p["milestoneId"] }
-        : null;
-
     case "plan_slice":
       return typeof p["sliceId"] === "string"
         ? { type: "slice_plan", id: p["sliceId"] }

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -124,8 +124,9 @@ export function worktreeBranchName(name: string): string {
  * nativeWorktreeRemove --force) to prevent #2365-style data loss.
  */
 export function isInsideWorktreesDir(basePath: string, targetPath: string): boolean {
-  const wtDir = resolve(worktreesDir(basePath));
-  const resolved = resolve(targetPath);
+  const wtDirPath = worktreesDir(basePath);
+  const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath);
+  const resolved = existsSync(targetPath) ? realpathSync(targetPath) : resolve(targetPath);
   // The resolved path must start with the worktrees dir followed by a separator,
   // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match).
   return resolved === wtDir || resolved.startsWith(wtDir + sep);
@@ -517,6 +518,9 @@ export function removeWorktree(
           rmSync(wtInternalDir, { recursive: true, force: true });
         }
         rmSync(resolvedWtPath, { recursive: true, force: true });
+        if (wtPath !== resolvedWtPath && existsSync(wtPath)) {
+          rmSync(wtPath, { recursive: true, force: true });
+        }
       } catch {
         logWarning(
           "reconcile",