gsd-pi 2.67.0-dev.43b0159 → 2.67.0-dev.4fb8afe

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,3 +1,5 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
@@ -57,6 +59,61 @@ const GATE_SAFE_TOOLS = new Set([
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
+function shouldPersistWriteGateSnapshot(env = process.env) {
+    return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+}
+function writeGateSnapshotPath(basePath = process.cwd()) {
+    return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+}
+function currentWriteGateSnapshot() {
+    return {
+        verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+        activeQueuePhase,
+        pendingGateId,
+    };
+}
+function persistWriteGateSnapshot(basePath = process.cwd()) {
+    if (!shouldPersistWriteGateSnapshot())
+        return;
+    const path = writeGateSnapshotPath(basePath);
+    mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
+    const tempPath = `${path}.tmp`;
+    writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
+    renameSync(tempPath, path);
+}
+function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
+    if (!shouldPersistWriteGateSnapshot())
+        return;
+    const path = writeGateSnapshotPath(basePath);
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // swallow
+    }
+}
+function normalizeWriteGateSnapshot(value) {
+    const record = value && typeof value === "object" ? value : {};
+    const verified = Array.isArray(record.verifiedDepthMilestones)
+        ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
+        : [];
+    return {
+        verifiedDepthMilestones: [...new Set(verified)].sort(),
+        activeQueuePhase: record.activeQueuePhase === true,
+        pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
+    };
+}
+export function loadWriteGateSnapshot(basePath = process.cwd()) {
+    const path = writeGateSnapshotPath(basePath);
+    if (!existsSync(path))
+        return currentWriteGateSnapshot();
+    try {
+        return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
+    }
+    catch {
+        return currentWriteGateSnapshot();
+    }
+}
 export function isDepthVerified() {
     return verifiedDepthMilestones.size > 0;
 }
@@ -68,25 +125,34 @@ export function isMilestoneDepthVerified(milestoneId) {
         return false;
     return verifiedDepthMilestones.has(milestoneId);
 }
+export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
+    if (!milestoneId)
+        return false;
+    return snapshot.verifiedDepthMilestones.includes(milestoneId);
+}
 export function isQueuePhaseActive() {
     return activeQueuePhase;
 }
 export function setQueuePhaseActive(active) {
     activeQueuePhase = active;
+    persistWriteGateSnapshot();
 }
 export function resetWriteGateState() {
     verifiedDepthMilestones.clear();
     pendingGateId = null;
+    persistWriteGateSnapshot();
 }
 export function clearDiscussionFlowState() {
     verifiedDepthMilestones.clear();
     activeQueuePhase = false;
     pendingGateId = null;
+    clearPersistedWriteGateSnapshot();
 }
-export function markDepthVerified(milestoneId) {
+export function markDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return;
     verifiedDepthMilestones.add(milestoneId);
+    persistWriteGateSnapshot(basePath);
 }
 /**
  * Check whether a question ID matches a recognized gate pattern.
@@ -114,12 +180,14 @@ function extractContextMilestoneId(inputPath) {
  */
 export function setPendingGate(gateId) {
     pendingGateId = gateId;
+    persistWriteGateSnapshot();
 }
 /**
  * Clear the pending gate (called when the user confirms).
  */
 export function clearPendingGate() {
     pendingGateId = null;
+    persistWriteGateSnapshot();
 }
 /**
  * Get the currently pending gate, if any.
@@ -134,8 +202,11 @@ export function getPendingGate() {
  * Returns { block: true, reason } if the tool should be blocked.
  * Read-only tools and ask_user_questions itself are always allowed.
  */
-export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive) {
-    if (!pendingGateId)
+export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive) {
+    return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+}
+export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
+    if (!snapshot.pendingGateId)
         return { block: false };
     if (GATE_SAFE_TOOLS.has(toolName))
         return { block: false };
@@ -145,7 +216,7 @@ export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive
     return {
         block: true,
         reason: [
-            `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+            `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
             `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`,
             `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
             `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -157,8 +228,11 @@ export function shouldBlockPendingGate(toolName, _milestoneId, _queuePhaseActive
  * Check whether a bash command should be blocked because a discussion gate is pending.
  * Read-only bash commands are allowed; mutating commands are blocked.
  */
-export function shouldBlockPendingGateBash(command, _milestoneId, _queuePhaseActive) {
-    if (!pendingGateId)
+export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActive) {
+    return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+}
+export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
+    if (!snapshot.pendingGateId)
         return { block: false };
     // Allow read-only bash commands
     if (BASH_READ_ONLY_RE.test(command))
@@ -166,7 +240,7 @@ export function shouldBlockPendingGateBash(command, _milestoneId, _queuePhaseAct
     return {
         block: true,
         reason: [
-            `HARD BLOCK: Discussion gate "${pendingGateId}" has not been confirmed by the user.`,
+            `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
             `You MUST re-call ask_user_questions with the gate question before running mutating commands.`,
             `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
             `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
@@ -232,6 +306,9 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
  * require the milestone to be depth-verified first.
  */
 export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceId) {
+    return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+}
+export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType, milestoneId, sliceId) {
     if (artifactType !== "CONTEXT")
         return { block: false };
     if (sliceId)
@@ -245,7 +322,7 @@ export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceI
             ].join(" "),
         };
     }
-    if (isMilestoneDepthVerified(milestoneId))
+    if (isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId))
         return { block: false };
     return {
         block: true,
@@ -271,6 +348,9 @@ export function shouldBlockContextArtifactSave(artifactType, milestoneId, sliceI
  * @returns { block, reason } — block=true if the call should be rejected.
  */
 export function shouldBlockQueueExecution(toolName, input, queuePhaseActive) {
+    return shouldBlockQueueExecutionInSnapshot(currentWriteGateSnapshot(), toolName, input, queuePhaseActive);
+}
+export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, queuePhaseActive = snapshot.activeQueuePhase) {
     if (!queuePhaseActive)
         return { block: false };
     // Always-safe tools (read-only, discussion, planning)

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/doctor-git-checks.js

@@ -8,7 +8,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 /**
@@ -380,19 +380,19 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
                         code: "stale_uncommitted_changes",
                         scope: "project",
                         unitId: "project",
-                        message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting tracked files.`,
+                        message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting uncommitted changes.`,
                         fixable: true,
                     });
                     if (shouldFix("stale_uncommitted_changes")) {
                         try {
-                            nativeAddTracked(basePath);
+                            nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
                             const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
                             const result = nativeCommit(basePath, commitMsg);
                             if (result) {
                                 fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
                             }
                             else {
-                                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
+                                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging changes");
                             }
                         }
                         catch {

package/dist/resources/extensions/gsd/doctor-proactive.js

@@ -20,8 +20,8 @@ import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.j
 import { abortAndReset } from "./git-self-heal.js";
 import { rebuildState } from "./doctor.js";
 import { deriveState } from "./state.js";
-import { resolveMilestoneIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
+import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch } from "./git-service.js";
+import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 /** In-memory health history for the current auto-mode session. */
@@ -247,7 +247,7 @@ export async function preDispatchHealthGate(basePath) {
                 if (minutesSinceCommit >= thresholdMinutes) {
                     const mins = Math.floor(minutesSinceCommit);
                     try {
-                        nativeAddTracked(basePath);
+                        nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
                         const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`;
                         const result = nativeCommit(basePath, commitMsg);
                         if (result) {

package/dist/resources/extensions/gsd/guided-flow.js

@@ -34,6 +34,7 @@ import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMiles
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
+import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, formatEcosystemBrief, } from "./preparation.js";
 // ─── Preparation result storage ─────────────────────────────────────────────
 // Stores the most recent preparation result for injection into discuss prompts.
@@ -259,6 +260,21 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
                 routing: result.routing,
             });
         }
+        const compatibilityError = getWorkflowTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+            projectRoot: process.cwd(),
+            surface: "guided flow",
+            unitType,
+            authMode: result.appliedModel?.provider
+                ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+                : ctx.model?.provider
+                    ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+                    : undefined,
+            baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+        });
+        if (compatibilityError) {
+            ctx.ui.notify(compatibilityError, "error");
+            return;
+        }
     }
     // Scope tools for discuss flows (#2949).
     // Providers with grammar-based constrained decoding (xAI/Grok) return

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