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

package/dist/resource-loader.d.ts

@@ -22,5 +22,5 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
 export declare function initResources(agentDir: string): void;
-export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string): boolean;
+export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir?: string): boolean;
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -384,11 +384,13 @@ export function initResources(agentDir) {
     mkdirSync(agentDir, { recursive: true });
     const currentVersion = getBundledGsdVersion();
     const manifest = readManagedResourceManifest(agentDir);
+    const extensionsDir = join(agentDir, 'extensions');
     // Always prune root-level extension files that were removed from the bundle.
     // This is cheap (a few existence checks + at most one rmSync) and must run
     // unconditionally so that stale files left by a previous version are cleaned
     // up even when the version/hash match causes the full sync to be skipped.
     pruneRemovedBundledExtensions(manifest, agentDir);
+    pruneStaleSiblingFiles(bundledExtensionsDir, extensionsDir);
     // Ensure ~/.gsd/agent/node_modules symlinks to GSD's node_modules on EVERY
     // launch, not just during resource syncs. A stale/broken symlink makes ALL
     // extensions fail to resolve @gsd/* packages, rendering GSD non-functional.
@@ -402,7 +404,7 @@ export function initResources(agentDir) {
     if (manifest && manifest.gsdVersion === currentVersion) {
         // Version matches — check content fingerprint for same-version staleness.
         const currentHash = computeResourceFingerprint();
-        const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(join(agentDir, 'extensions'));
+        const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(extensionsDir, bundledExtensionsDir);
         if (manifest.contentHash && manifest.contentHash === currentHash && !hasStaleExtensionFiles) {
             return;
         }
@@ -555,14 +557,27 @@ function migrateSkillsToEcosystemDir(agentDir) {
         }
     }
 }
-export function hasStaleCompiledExtensionSiblings(extensionsDir) {
+export function hasStaleCompiledExtensionSiblings(extensionsDir, sourceDir = bundledExtensionsDir) {
     if (!existsSync(extensionsDir))
         return false;
+    const sourceFiles = existsSync(sourceDir)
+        ? new Set(readdirSync(sourceDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name))
+        : new Set();
     for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith('.ts'))
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.js'))
+            continue;
+        const siblingName = entry.name.endsWith('.ts')
+            ? entry.name.replace(/\.ts$/, '.js')
+            : entry.name.replace(/\.js$/, '.ts');
+        if (!existsSync(join(extensionsDir, siblingName)))
+            continue;
+        if (sourceFiles.has(entry.name) && sourceFiles.has(siblingName))
             continue;
-        const jsName = entry.name.replace(/\.ts$/, '.js');
-        if (existsSync(join(extensionsDir, jsName))) {
+        if (sourceFiles.has(entry.name) || sourceFiles.has(siblingName)) {
             return true;
         }
     }

package/dist/resources/GSD-WORKFLOW.md

@@ -18,7 +18,8 @@ Read these files in order and act on what they say:
 3. **`.gsd/milestones/<active>/M###-CONTEXT.md`** — Milestone-level project decisions, reference paths, constraints. Read this before doing implementation work.
 4. If a slice is active and has one, read **`S##-CONTEXT.md`** — Slice-specific decisions and constraints.
 5. If a slice is active, read its **`S##-PLAN.md`** — Which tasks exist? Which are done?
-6. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
+6. If `.gsd/CODEBASE.md` exists, skim it for fast structural orientation before broad code exploration.
+7. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
 
 Then do the thing `STATE.md` says to do next.
 
@@ -44,6 +45,7 @@ All artifacts live in `.gsd/` at the project root:
 .gsd/
   STATE.md                                  # Dashboard — always read first (derived cache; runtime, gitignored)
   DECISIONS.md                              # Append-only decisions register
+  CODEBASE.md                               # Generated codebase map cache (auto-refreshed by GSD)
   milestones/
     M001/
       M001-ROADMAP.md                       # Milestone plan (checkboxes = state)

package/dist/resources/extensions/get-secrets-from-user.js

@@ -25,6 +25,12 @@ function maskPreview(value) {
 function shellEscapeSingle(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function isSafeEnvVarKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+function isSupportedDeploymentEnvironment(env) {
+    return env === "development" || env === "preview" || env === "production";
+}
 function hydrateProcessEnv(key, value) {
     // Make newly collected secrets immediately visible to the current session.
     // Some extensions read process.env directly and do not reload .env on every call.
@@ -263,12 +269,22 @@ async function applySecrets(provided, destination, opts) {
     }
     if ((destination === "vercel" || destination === "convex") && opts.exec) {
         const env = opts.environment ?? "development";
+        if (!isSupportedDeploymentEnvironment(env)) {
+            errors.push(`environment: unsupported target environment "${env}"`);
+            return { applied, errors };
+        }
         for (const { key, value } of provided) {
+            if (!isSafeEnvVarKey(key)) {
+                errors.push(`${key}: invalid environment variable name`);
+                continue;
+            }
             const cmd = destination === "vercel"
                 ? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`
-                : `npx convex env set ${key} ${shellEscapeSingle(value)}`;
+                : "";
             try {
-                const result = await opts.exec("sh", ["-c", cmd]);
+                const result = destination === "vercel"
+                    ? await opts.exec("sh", ["-c", cmd])
+                    : await opts.exec("npx", ["convex", "env", "set", key, value]);
                 if (result.code !== 0) {
                     errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
                 }

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -40,6 +40,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getSliceTasks } from "./gsd-db.js";
 import { runPreExecutionChecks } from "./pre-execution-checks.js";
 import { writePreExecutionEvidence } from "./verification-evidence.js";
+import { ensureCodebaseMapFresh } from "./codebase-generator.js";
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
 /** Enqueue a sidecar item (hook, triage, or quick-task) for the main loop to
@@ -553,6 +554,31 @@ export async function postUnitPreVerification(pctx, opts) {
  */
 export async function postUnitPostVerification(pctx) {
     const { s, ctx, pi, buildSnapshotOpts, lockBase, stopAuto, pauseAuto, updateProgressWidget } = pctx;
+    if (s.currentUnit) {
+        try {
+            const codebasePrefs = loadEffectiveGSDPreferences()?.preferences?.codebase;
+            const refresh = ensureCodebaseMapFresh(s.basePath, codebasePrefs
+                ? {
+                    excludePatterns: codebasePrefs.exclude_patterns,
+                    maxFiles: codebasePrefs.max_files,
+                    collapseThreshold: codebasePrefs.collapse_threshold,
+                }
+                : undefined, { force: true, ttlMs: 0 });
+            if (refresh.status === "generated" || refresh.status === "updated") {
+                debugLog("postUnit", {
+                    phase: "codebase-refresh",
+                    unitType: s.currentUnit.type,
+                    unitId: s.currentUnit.id,
+                    status: refresh.status,
+                    fileCount: refresh.fileCount,
+                    reason: refresh.reason,
+                });
+            }
+        }
+        catch (e) {
+            logWarning("engine", `CODEBASE refresh failed: ${e.message}`);
+        }
+    }
     // ── Post-unit hooks ──
     if (s.currentUnit && !s.stepMode) {
         const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -8,6 +8,7 @@ import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
@@ -103,10 +104,24 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         }
     }
     let codebaseBlock = "";
+    try {
+        const codebaseOptions = loadedPreferences?.preferences?.codebase
+            ? {
+                excludePatterns: loadedPreferences.preferences.codebase.exclude_patterns,
+                maxFiles: loadedPreferences.preferences.codebase.max_files,
+                collapseThreshold: loadedPreferences.preferences.codebase.collapse_threshold,
+            }
+            : undefined;
+        ensureCodebaseMapFresh(process.cwd(), codebaseOptions);
+    }
+    catch (e) {
+        logWarning("bootstrap", `CODEBASE refresh failed: ${e.message}`);
+    }
     const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE");
-    if (existsSync(codebasePath)) {
+    const rawCodebase = readCodebaseMap(process.cwd());
+    if (existsSync(codebasePath) && rawCodebase) {
         try {
-            const rawContent = readFileSync(codebasePath, "utf-8").trim();
+            const rawContent = rawCodebase.trim();
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
@@ -116,7 +131,7 @@ export async function buildBeforeAgentStartResult(event, ctx) {
                 const content = rawContent.length > MAX_CODEBASE_CHARS
                     ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
-                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, may be stale — run /gsd codebase update to refresh)]\n\n${content}`;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
         }
         catch (e) {

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -7,6 +7,7 @@
  * Generation: walk `git ls-files`, group by directory, output with descriptions.
  * Maintenance: agent updates descriptions as it works; incremental update preserves them.
  */
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname, extname } from "node:path";
 import { execSync } from "node:child_process";
@@ -31,6 +32,10 @@ const DEFAULT_EXCLUDES = [
 ];
 const DEFAULT_MAX_FILES = 500;
 const DEFAULT_COLLAPSE_THRESHOLD = 20;
+const DEFAULT_REFRESH_TTL_MS = 30_000;
+const DEFAULT_MAX_AGE_MS = 15 * 60_000;
+const CODEBASE_METADATA_PREFIX = "<!-- gsd:codebase-meta ";
+const freshnessCache = new Map();
 // ─── Parsing ─────────────────────────────────────────────────────────────────
 /**
  * Parse an existing CODEBASE.md to extract file → description mappings.
@@ -66,6 +71,31 @@ export function parseCodebaseMap(content) {
     }
     return descriptions;
 }
+export function parseCodebaseMapMetadata(content) {
+    const metaLine = content
+        .split("\n")
+        .find((line) => line.trimStart().startsWith(CODEBASE_METADATA_PREFIX));
+    if (!metaLine)
+        return null;
+    const trimmed = metaLine.trim();
+    const jsonStart = CODEBASE_METADATA_PREFIX.length;
+    const jsonEnd = trimmed.lastIndexOf(" -->");
+    if (jsonEnd <= jsonStart)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd));
+        if (typeof parsed?.generatedAt === "string"
+            && typeof parsed?.fingerprint === "string"
+            && typeof parsed?.fileCount === "number"
+            && typeof parsed?.truncated === "boolean") {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore malformed metadata and treat the map as stale.
+    }
+    return null;
+}
 // ─── File Enumeration ────────────────────────────────────────────────────────
 function shouldExclude(filePath, excludes) {
     for (const pattern of excludes) {
@@ -103,6 +133,30 @@ function enumerateFiles(basePath, excludes, maxFiles) {
     const truncated = filtered.length > maxFiles;
     return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
+function resolveGeneratorOptions(options) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
+    const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
+    const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
+    return {
+        excludes,
+        maxFiles,
+        collapseThreshold,
+        optionSignature: JSON.stringify({
+            excludes,
+            maxFiles,
+            collapseThreshold,
+        }),
+    };
+}
+function computeCodebaseFingerprint(files, resolved, truncated) {
+    return createHash("sha1")
+        .update(JSON.stringify({
+        files,
+        truncated,
+        optionSignature: resolved.optionSignature,
+    }))
+        .digest("hex");
+}
 // ─── Grouping ────────────────────────────────────────────────────────────────
 function groupByDirectory(files, descriptions, collapseThreshold) {
     const dirMap = new Map();
@@ -131,13 +185,13 @@ function groupByDirectory(files, descriptions, collapseThreshold) {
     return groups;
 }
 // ─── Rendering ───────────────────────────────────────────────────────────────
-function renderCodebaseMap(groups, totalFiles, truncated) {
+function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
     const lines = [];
-    const now = new Date().toISOString().split(".")[0] + "Z";
     const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0);
     lines.push("# Codebase Map");
     lines.push("");
-    lines.push(`Generated: ${now} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+    lines.push(`Generated: ${metadata.generatedAt} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+    lines.push(`${CODEBASE_METADATA_PREFIX}${JSON.stringify(metadata)} -->`);
     if (truncated) {
         lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
     }
@@ -182,20 +236,35 @@ function renderCodebaseMap(groups, totalFiles, truncated) {
     }
     return lines.join("\n");
 }
+function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated) {
+    const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const descriptions = existingDescriptions ?? new Map();
+    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+    const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+    const metadata = {
+        generatedAt,
+        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+        fileCount: listed.files.length,
+        truncated: listed.truncated,
+    };
+    const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
+    return {
+        content,
+        fileCount: listed.files.length,
+        truncated: listed.truncated,
+        files: listed.files,
+        fingerprint: metadata.fingerprint,
+        generatedAt,
+    };
+}
 // ─── Public API ──────────────────────────────────────────────────────────────
 /**
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
 export function generateCodebaseMap(basePath, options, existingDescriptions) {
-    const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
-    const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
-    const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
-    const { files, truncated } = enumerateFiles(basePath, excludes, maxFiles);
-    const descriptions = existingDescriptions ?? new Map();
-    const groups = groupByDirectory(files, descriptions, collapseThreshold);
-    const content = renderCodebaseMap(groups, files.length, truncated);
-    return { content, fileCount: files.length, truncated, files };
+    const resolved = resolveGeneratorOptions(options);
+    return buildCodebaseMap(basePath, resolved, existingDescriptions);
 }
 /**
  * Incremental update: re-scan files, preserve existing descriptions,
@@ -203,6 +272,7 @@ export function generateCodebaseMap(basePath, options, existingDescriptions) {
  */
 export function updateCodebaseMap(basePath, options) {
     const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+    const resolved = resolveGeneratorOptions(options);
     // Load existing descriptions
     let existingDescriptions = new Map();
     if (existsSync(codebasePath)) {
@@ -212,7 +282,7 @@ export function updateCodebaseMap(basePath, options) {
     const existingFiles = new Set(existingDescriptions.keys());
     // Generate new map preserving descriptions — reuse the returned file list
     // to avoid a second enumeration (prevents race between content and stats).
-    const result = generateCodebaseMap(basePath, options, existingDescriptions);
+    const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
     const currentSet = new Set(result.files);
     // Count changes
     let added = 0;
@@ -232,8 +302,98 @@ export function updateCodebaseMap(basePath, options) {
         unchanged: result.files.length - added,
         fileCount: result.fileCount,
         truncated: result.truncated,
+        fingerprint: result.fingerprint,
+        generatedAt: result.generatedAt,
     };
 }
+function clearFreshnessCache(basePath) {
+    for (const key of freshnessCache.keys()) {
+        if (key === basePath || key.startsWith(`${basePath}::`)) {
+            freshnessCache.delete(key);
+        }
+    }
+}
+export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
+    const resolved = resolveGeneratorOptions(options);
+    const cacheKey = `${basePath}::${resolved.optionSignature}`;
+    const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
+    const maxAgeMs = ensureOptions?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const force = ensureOptions?.force === true;
+    const now = Date.now();
+    if (!force && ttlMs > 0) {
+        const cached = freshnessCache.get(cacheKey);
+        if (cached && now - cached.checkedAt < ttlMs) {
+            return cached.result;
+        }
+    }
+    const existing = readCodebaseMap(basePath);
+    const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+    const cacheAndReturn = (result) => {
+        freshnessCache.set(cacheKey, { checkedAt: now, result });
+        return result;
+    };
+    if (!existing) {
+        const generated = buildCodebaseMap(basePath, resolved, undefined, listed);
+        if (generated.fileCount > 0) {
+            writeCodebaseMap(basePath, generated.content);
+            return cacheAndReturn({
+                status: "generated",
+                fileCount: generated.fileCount,
+                truncated: generated.truncated,
+                generatedAt: generated.generatedAt,
+                fingerprint: generated.fingerprint,
+                reason: "missing",
+            });
+        }
+        return cacheAndReturn({
+            status: "empty",
+            fileCount: 0,
+            truncated: false,
+            generatedAt: null,
+            fingerprint,
+            reason: "no-tracked-files",
+        });
+    }
+    const metadata = parseCodebaseMapMetadata(existing);
+    const existingDescriptions = parseCodebaseMap(existing);
+    const ageMs = metadata ? now - Date.parse(metadata.generatedAt) : Number.POSITIVE_INFINITY;
+    const staleReason = !metadata ? "missing-metadata"
+        : metadata.fingerprint !== fingerprint ? "files-changed"
+            : metadata.fileCount !== listed.files.length ? "file-count-changed"
+                : metadata.truncated !== listed.truncated ? "truncation-changed"
+                    : maxAgeMs > 0 && Number.isFinite(ageMs) && ageMs > maxAgeMs ? "expired"
+                        : undefined;
+    if (!staleReason) {
+        return cacheAndReturn({
+            status: "fresh",
+            fileCount: metadata?.fileCount ?? listed.files.length,
+            truncated: metadata?.truncated ?? listed.truncated,
+            generatedAt: metadata?.generatedAt ?? null,
+            fingerprint: metadata?.fingerprint ?? fingerprint,
+        });
+    }
+    const updated = buildCodebaseMap(basePath, resolved, existingDescriptions, listed);
+    if (updated.fileCount > 0) {
+        writeCodebaseMap(basePath, updated.content);
+        return cacheAndReturn({
+            status: "updated",
+            fileCount: updated.fileCount,
+            truncated: updated.truncated,
+            generatedAt: updated.generatedAt,
+            fingerprint: updated.fingerprint,
+            reason: staleReason,
+        });
+    }
+    return cacheAndReturn({
+        status: "empty",
+        fileCount: 0,
+        truncated: false,
+        generatedAt: null,
+        fingerprint,
+        reason: staleReason,
+    });
+}
 /**
  * Write CODEBASE.md to .gsd/ directory.
  */
@@ -242,6 +402,7 @@ export function writeCodebaseMap(basePath, content) {
     mkdirSync(root, { recursive: true });
     const outPath = join(root, "CODEBASE.md");
     writeFileSync(outPath, content, "utf-8");
+    clearFreshnessCache(basePath);
     return outPath;
 }
 /**

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -61,7 +61,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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 = {
     auto: [
@@ -224,7 +224,7 @@ const NESTED_COMPLETIONS = {
         { 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/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -40,6 +40,7 @@ export function showHelp(ctx) {
         "",
         "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/dist/resources/extensions/gsd/commands-bootstrap.js

@@ -44,6 +44,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" },
 ];
 function filterStartsWith(partial, options, prefix = "") {
     const normalizedPrefix = prefix.length > 0 ? `${prefix} ` : "";
@@ -192,6 +193,14 @@ function getGsdArgumentCompletions(prefix) {
             { cmd: "info", desc: "Show extension details" },
         ], "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/dist/resources/extensions/gsd/commands-codebase.js

@@ -8,10 +8,11 @@ import { generateCodebaseMap, updateCodebaseMap, writeCodebaseMap, getCodebaseMa
 import { loadEffectiveGSDPreferences } from "./preferences.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" +
@@ -95,7 +96,7 @@ function showStats(basePath, ctx) {
         `  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/dist/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/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -207,10 +207,6 @@ export function extractEntityKey(event) {
             return typeof p["sliceId"] === "string"
                 ? { 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/dist/resources/extensions/gsd/worktree-manager.js

@@ -77,8 +77,9 @@ export function worktreeBranchName(name) {
  * nativeWorktreeRemove --force) to prevent #2365-style data loss.
  */
 export function isInsideWorktreesDir(basePath, targetPath) {
-    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);
@@ -434,6 +435,9 @@ export function removeWorktree(basePath, name, opts = {}) {
                     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", `Worktree directory could not be removed after git internal cleanup: ${resolvedWtPath}. ` +

package/dist/web/standalone/.next/BUILD_ID

@@ -1 +1 @@
-CrKrzIIxk55witDF1eS0L
+NllX5BEOLdTXS9ypf1i3i