gsd-pi 2.58.0-dev.d63175c → 2.58.0-dev.e002a57

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -6,6 +6,7 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { debugTime } from "../debug-logger.js";
 import { loadPrompt } from "../prompt-loader.js";
+import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
@@ -94,30 +95,54 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
+  let codebaseBlock = "";
+  const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE");
+  if (existsSync(codebasePath)) {
+    try {
+      const rawContent = readFileSync(codebasePath, "utf-8").trim();
+      if (rawContent) {
+        // Cap injection size to ~2 000 tokens to avoid bloating every request.
+        // Full map is always available at .gsd/CODEBASE.md.
+        const MAX_CODEBASE_CHARS = 8_000;
+        const generatedMatch = rawContent.match(/Generated: (\S+)/);
+        const generatedAt = generatedMatch?.[1] ?? "unknown";
+        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}`;
+      }
+    } catch {
+      // skip
+    }
+  }
+
   warnDeprecatedAgentInstructions();
 
   const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
+
+  // Re-inject forensics context on follow-up turns (#2941)
+  const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd()) : null;
+
   const worktreeBlock = buildWorktreeContextBlock();
-  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
 
   stopContextTimer({
     systemPromptSize: fullSystem.length,
-    injectionSize: injection?.length ?? 0,
+    injectionSize: injection?.length ?? forensicsInjection?.length ?? 0,
     hasPreferences: preferenceBlock.length > 0,
     hasNewSkills: newSkillsBlock.length > 0,
   });
 
+  // Determine which context message to inject (guided execute takes priority)
+  const contextMessage = injection
+    ? { customType: "gsd-guided-context", content: injection, display: false as const }
+    : forensicsInjection
+      ? { customType: "gsd-forensics", content: forensicsInjection, display: false as const }
+      : null;
+
   return {
     systemPrompt: fullSystem,
-    ...(injection
-      ? {
-        message: {
-          customType: "gsd-guided-context",
-          content: injection,
-          display: false as const,
-        },
-      }
-      : {}),
+    ...(contextMessage ? { message: contextMessage } : {}),
   };
 }
 
@@ -375,3 +400,38 @@ function oneLine(text: string): string {
   return text.replace(/\s+/g, " ").trim();
 }
 
+// ─── Forensics Context Re-injection (#2941) ──────────────────────────────────
+
+/**
+ * Check for an active forensics session and return the prompt content
+ * so it can be re-injected on follow-up turns.
+ */
+function buildForensicsContextInjection(basePath: string): string | null {
+  const marker = readForensicsMarker(basePath);
+  if (!marker) return null;
+
+  // Expire markers older than 2 hours to avoid stale context
+  const age = Date.now() - new Date(marker.createdAt).getTime();
+  if (age > 2 * 60 * 60 * 1000) {
+    clearForensicsMarker(basePath);
+    return null;
+  }
+
+  return marker.promptContent;
+}
+
+/**
+ * Remove the active forensics marker file, e.g. when the investigation
+ * is complete or the session expires.
+ */
+export function clearForensicsMarker(basePath: string): void {
+  const markerPath = join(basePath, ".gsd", "runtime", "active-forensics.json");
+  if (existsSync(markerPath)) {
+    try {
+      unlinkSync(markerPath);
+    } catch {
+      // non-fatal
+    }
+  }
+}
+

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,5 +1,31 @@
 const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 
+/**
+ * Path segment that identifies .gsd/ planning artifacts.
+ * Writes to these paths are allowed during queue mode.
+ */
+const GSD_DIR_RE = /(^|[/\\])\.gsd([/\\]|$)/;
+
+/**
+ * Read-only tool names that are always safe during queue mode.
+ */
+const QUEUE_SAFE_TOOLS = new Set([
+  "read", "grep", "find", "ls", "glob",
+  // Discussion & planning tools
+  "ask_user_questions",
+  "gsd_milestone_generate_id",
+  "gsd_summary_save",
+  // Web research tools used during queue discussion
+  "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
+  "search_and_read",
+]);
+
+/**
+ * Bash commands that are read-only / investigative — safe during queue mode.
+ * Matches the leading command in a bash invocation.
+ */
+const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s)/;
+
 let depthVerificationDone = false;
 let activeQueuePhase = false;
 
@@ -49,3 +75,52 @@ export function shouldBlockContextWrite(
   };
 }
 
+/**
+ * Queue-mode execution guard (#2545).
+ *
+ * When the queue phase is active, the agent should only create planning
+ * artifacts (milestones, CONTEXT.md, QUEUE.md, etc.) — never execute work.
+ * This function blocks write/edit/bash tool calls that would modify source
+ * code outside of .gsd/.
+ *
+ * @param toolName  The tool being called (write, edit, bash, etc.)
+ * @param input     For write/edit: the file path. For bash: the command string.
+ * @param queuePhaseActive  Whether the queue phase is currently active.
+ * @returns { block, reason } — block=true if the call should be rejected.
+ */
+export function shouldBlockQueueExecution(
+  toolName: string,
+  input: string,
+  queuePhaseActive: boolean,
+): { block: boolean; reason?: string } {
+  if (!queuePhaseActive) return { block: false };
+
+  // Always-safe tools (read-only, discussion, planning)
+  if (QUEUE_SAFE_TOOLS.has(toolName)) return { block: false };
+
+  // write/edit — allow if targeting .gsd/ planning artifacts
+  if (toolName === "write" || toolName === "edit") {
+    if (GSD_DIR_RE.test(input)) return { block: false };
+    return {
+      block: true,
+      reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` +
+        `Cannot ${toolName} to "${input}" during queue mode. ` +
+        `Write CONTEXT.md files and update PROJECT.md/QUEUE.md instead.`,
+    };
+  }
+
+  // bash — allow read-only/investigative commands, block everything else
+  if (toolName === "bash") {
+    if (BASH_READ_ONLY_RE.test(input)) return { block: false };
+    return {
+      block: true,
+      reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` +
+        `Cannot run "${input.slice(0, 80)}${input.length > 80 ? "…" : ""}" during queue mode. ` +
+        `Use read-only commands (cat, grep, git log, etc.) to investigate, then write planning artifacts.`,
+    };
+  }
+
+  // Unknown tools — allow by default (custom extension tools, etc.)
+  return { block: false };
+}
+

package/src/resources/extensions/gsd/captures.ts

@@ -26,6 +26,7 @@ export interface CaptureEntry {
   resolution?: string;
   rationale?: string;
   resolvedAt?: string;
+  resolvedInMilestone?: string;
   executed?: boolean;
 }
 
@@ -176,6 +177,7 @@ export function markCaptureResolved(
   classification: Classification,
   resolution: string,
   rationale: string,
+  milestoneId?: string,
 ): void {
   const filePath = resolveCapturesPath(basePath);
   if (!existsSync(filePath)) return;
@@ -206,13 +208,17 @@ export function markCaptureResolved(
     `**Rationale:** ${rationale}`,
     `**Resolved:** ${resolvedAt}`,
   ];
+  if (milestoneId) {
+    newFields.push(`**Milestone:** ${milestoneId}`);
+  }
 
-  // Remove any existing classification/resolution/rationale/resolved fields
+  // Remove any existing classification/resolution/rationale/resolved/milestone fields
   // (in case of re-triage)
   section = section.replace(/\*\*Classification:\*\*\s*.+\n?/g, "");
   section = section.replace(/\*\*Resolution:\*\*\s*.+\n?/g, "");
   section = section.replace(/\*\*Rationale:\*\*\s*.+\n?/g, "");
   section = section.replace(/\*\*Resolved:\*\*\s*.+\n?/g, "");
+  section = section.replace(/\*\*Milestone:\*\*\s*.+\n?/g, "");
 
   // Add new fields after Status line
   section = section.trimEnd() + "\n" + newFields.join("\n") + "\n";
@@ -255,16 +261,68 @@ export function markCaptureExecuted(basePath: string, captureId: string): void {
  * Load resolved captures that have actionable classifications (inject, replan,
  * quick-task) but have NOT yet been executed.
  * These are captures whose resolutions need to be carried out.
+ *
+ * When `currentMilestoneId` is provided, captures resolved in a *different*
+ * milestone are treated as stale and excluded.  This prevents quick-task
+ * captures from a prior milestone re-executing after the underlying issues
+ * were already fixed by planned milestone work (#2872).
+ *
+ * Captures that have no `resolvedInMilestone` (legacy captures resolved before
+ * this field was introduced) are always included for backward compatibility.
  */
-export function loadActionableCaptures(basePath: string): CaptureEntry[] {
+export function loadActionableCaptures(basePath: string, currentMilestoneId?: string): CaptureEntry[] {
   return loadAllCaptures(basePath).filter(
     c =>
       c.status === "resolved" &&
       !c.executed &&
       (c.classification === "inject" ||
         c.classification === "replan" ||
-        c.classification === "quick-task"),
+        c.classification === "quick-task") &&
+      // Staleness gate: exclude captures resolved in a different milestone (#2872)
+      (!currentMilestoneId ||
+        !c.resolvedInMilestone ||
+        c.resolvedInMilestone === currentMilestoneId),
+  );
+}
+
+/**
+ * Retroactively stamp a capture with a milestone ID.
+ *
+ * Used by executeTriageResolutions() as a safety net when the triage LLM
+ * resolves a capture without writing the **Milestone:** field.  This ensures
+ * the staleness gate in loadActionableCaptures() works correctly even for
+ * captures resolved before the prompt was updated (#2872).
+ */
+export function stampCaptureMilestone(basePath: string, captureId: string, milestoneId: string): void {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return;
+
+  const content = readFileSync(filePath, "utf-8");
+
+  const sectionRegex = new RegExp(
+    `(### ${escapeRegex(captureId)}\\n(?:(?!### ).)*?)(?=### |$)`,
+    "s",
   );
+  const match = sectionRegex.exec(content);
+  if (!match) return;
+
+  let section = match[1];
+
+  // Only stamp if not already present
+  if (/\*\*Milestone:\*\*/.test(section)) return;
+
+  // Insert after the Resolved field (or at end of section)
+  const resolvedFieldEnd = section.search(/\*\*Resolved:\*\*\s*.+\n?/);
+  if (resolvedFieldEnd !== -1) {
+    const resolvedMatch = section.match(/\*\*Resolved:\*\*\s*.+\n?/);
+    const insertPos = resolvedFieldEnd + (resolvedMatch?.[0]?.length ?? 0);
+    section = section.slice(0, insertPos) + `**Milestone:** ${milestoneId}\n` + section.slice(insertPos);
+  } else {
+    section = section.trimEnd() + "\n" + `**Milestone:** ${milestoneId}` + "\n";
+  }
+
+  const updated = content.replace(sectionRegex, section);
+  writeFileSync(filePath, updated, "utf-8");
 }
 
 // ─── Parser ───────────────────────────────────────────────────────────────────
@@ -291,6 +349,7 @@ function parseCapturesContent(content: string): CaptureEntry[] {
     const resolution = extractBoldField(body, "Resolution");
     const rationale = extractBoldField(body, "Rationale");
     const resolvedAt = extractBoldField(body, "Resolved");
+    const milestoneId = extractBoldField(body, "Milestone");
     const executedAt = extractBoldField(body, "Executed");
 
     if (!text || !timestamp) continue;
@@ -308,6 +367,7 @@ function parseCapturesContent(content: string): CaptureEntry[] {
       ...(resolution ? { resolution } : {}),
       ...(rationale ? { rationale } : {}),
       ...(resolvedAt ? { resolvedAt } : {}),
+      ...(milestoneId ? { resolvedInMilestone: milestoneId } : {}),
       ...(executedAt ? { executed: true } : {}),
     });
   }

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

@@ -0,0 +1,351 @@
+/**
+ * GSD Codebase Map Generator
+ *
+ * Produces .gsd/CODEBASE.md — a structural table of contents for the project.
+ * Gives fresh agent contexts instant orientation without filesystem exploration.
+ *
+ * Generation: walk `git ls-files`, group by directory, output with descriptions.
+ * Maintenance: agent updates descriptions as it works; incremental update preserves them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname, extname } from "node:path";
+
+import { execSync } from "node:child_process";
+import { gsdRoot } from "./paths.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface CodebaseMapOptions {
+  excludePatterns?: string[];
+  maxFiles?: number;
+  collapseThreshold?: number;
+}
+
+interface FileEntry {
+  path: string;
+  description: string;
+}
+
+interface DirectoryGroup {
+  path: string;
+  files: FileEntry[];
+  collapsed: boolean;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULT_EXCLUDES = [
+  ".gsd/",
+  ".planning/",
+  ".git/",
+  "node_modules/",
+  "dist/",
+  "build/",
+  ".next/",
+  "coverage/",
+  "__pycache__/",
+  ".venv/",
+  "vendor/",
+];
+
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_COLLAPSE_THRESHOLD = 20;
+
+// ─── Parsing ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse an existing CODEBASE.md to extract file → description mappings.
+ * Also scans <!-- gsd:collapsed-descriptions --> comment blocks to preserve
+ * descriptions for files in collapsed directories across incremental updates.
+ */
+export function parseCodebaseMap(content: string): Map<string, string> {
+  const descriptions = new Map<string, string>();
+  let inCollapsedBlock = false;
+
+  for (const line of content.split("\n")) {
+    // Track collapsed-description comment blocks
+    if (line.trimStart().startsWith("<!-- gsd:collapsed-descriptions")) {
+      inCollapsedBlock = true;
+      continue;
+    }
+    if (inCollapsedBlock && line.trimStart().startsWith("-->")) {
+      inCollapsedBlock = false;
+      continue;
+    }
+
+    // Match: - `path/to/file.ts` — Description here
+    const match = line.match(/^- `(.+?)` — (.+)$/);
+    if (match) {
+      descriptions.set(match[1], match[2]);
+      continue;
+    }
+
+    // Match: - `path/to/file.ts` (no description) — only outside collapsed blocks
+    if (!inCollapsedBlock) {
+      const bareMatch = line.match(/^- `(.+?)`\s*$/);
+      if (bareMatch) {
+        descriptions.set(bareMatch[1], "");
+      }
+    }
+  }
+  return descriptions;
+}
+
+// ─── File Enumeration ────────────────────────────────────────────────────────
+
+function shouldExclude(filePath: string, excludes: string[]): boolean {
+  for (const pattern of excludes) {
+    if (pattern.endsWith("/")) {
+      if (filePath.startsWith(pattern) || filePath.includes(`/${pattern}`)) return true;
+    } else if (filePath === pattern || filePath.endsWith(`/${pattern}`)) {
+      return true;
+    }
+  }
+  // Skip binary/lock files
+  const ext = extname(filePath).toLowerCase();
+  if ([".lock", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf", ".eot", ".svg"].includes(ext)) {
+    return true;
+  }
+  return false;
+}
+
+function lsFiles(basePath: string): string[] {
+  try {
+    const result = execSync("git ls-files", { cwd: basePath, encoding: "utf-8", timeout: 10000 });
+    return result.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Enumerate tracked files, applying exclusions and the maxFiles cap.
+ * Returns both the file list and whether truncation occurred.
+ */
+function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): { files: string[]; truncated: boolean } {
+  const allFiles = lsFiles(basePath);
+  const filtered = allFiles.filter((f) => !shouldExclude(f, excludes));
+  const truncated = filtered.length > maxFiles;
+  return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
+}
+
+// ─── Grouping ────────────────────────────────────────────────────────────────
+
+function groupByDirectory(
+  files: string[],
+  descriptions: Map<string, string>,
+  collapseThreshold: number,
+): DirectoryGroup[] {
+  const dirMap = new Map<string, FileEntry[]>();
+
+  for (const file of files) {
+    const dir = dirname(file);
+    const dirKey = dir === "." ? "" : dir;
+    if (!dirMap.has(dirKey)) {
+      dirMap.set(dirKey, []);
+    }
+    dirMap.get(dirKey)!.push({
+      path: file,
+      description: descriptions.get(file) ?? "",
+    });
+  }
+
+  const groups: DirectoryGroup[] = [];
+  const sortedDirs = [...dirMap.keys()].sort();
+
+  for (const dir of sortedDirs) {
+    const dirFiles = dirMap.get(dir)!;
+    dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+
+    groups.push({
+      path: dir,
+      files: dirFiles,
+      collapsed: dirFiles.length > collapseThreshold,
+    });
+  }
+
+  return groups;
+}
+
+// ─── Rendering ───────────────────────────────────────────────────────────────
+
+function renderCodebaseMap(groups: DirectoryGroup[], totalFiles: number, truncated: boolean): string {
+  const lines: string[] = [];
+  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}`);
+  if (truncated) {
+    lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
+  }
+  lines.push("");
+
+  for (const group of groups) {
+    const heading = group.path || "(root)";
+    lines.push(`### ${heading}/`);
+
+    if (group.collapsed) {
+      // Summarize collapsed directories
+      const extensions = new Map<string, number>();
+      for (const f of group.files) {
+        const ext = extname(f.path) || "(no ext)";
+        extensions.set(ext, (extensions.get(ext) ?? 0) + 1);
+      }
+      const extSummary = [...extensions.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([ext, count]) => `${count} ${ext}`)
+        .join(", ");
+      lines.push(`- *(${group.files.length} files: ${extSummary})*`);
+
+      // Preserve any existing descriptions in a hidden comment block so
+      // incremental updates can recover them via parseCodebaseMap.
+      const descLines = group.files
+        .filter((f) => f.description)
+        .map((f) => `- \`${f.path}\` — ${f.description}`);
+      if (descLines.length > 0) {
+        lines.push("<!-- gsd:collapsed-descriptions");
+        lines.push(...descLines);
+        lines.push("-->");
+      }
+    } else {
+      for (const file of group.files) {
+        if (file.description) {
+          lines.push(`- \`${file.path}\` — ${file.description}`);
+        } else {
+          lines.push(`- \`${file.path}\``);
+        }
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Generate a fresh CODEBASE.md from scratch.
+ * Preserves existing descriptions if `existingDescriptions` is provided.
+ */
+export function generateCodebaseMap(
+  basePath: string,
+  options?: CodebaseMapOptions,
+  existingDescriptions?: Map<string, string>,
+): { content: string; fileCount: number; truncated: boolean; files: string[] } {
+  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<string, string>();
+  const groups = groupByDirectory(files, descriptions, collapseThreshold);
+  const content = renderCodebaseMap(groups, files.length, truncated);
+
+  return { content, fileCount: files.length, truncated, files };
+}
+
+/**
+ * Incremental update: re-scan files, preserve existing descriptions,
+ * add new files, remove deleted files.
+ */
+export function updateCodebaseMap(
+  basePath: string,
+  options?: CodebaseMapOptions,
+): { content: string; added: number; removed: number; unchanged: number; fileCount: number; truncated: boolean } {
+  const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+
+  // Load existing descriptions
+  let existingDescriptions = new Map<string, string>();
+  if (existsSync(codebasePath)) {
+    const existing = readFileSync(codebasePath, "utf-8");
+    existingDescriptions = parseCodebaseMap(existing);
+  }
+
+  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 currentSet = new Set(result.files);
+
+  // Count changes
+  let added = 0;
+  let removed = 0;
+
+  for (const f of result.files) {
+    if (!existingFiles.has(f)) added++;
+  }
+  for (const f of existingFiles) {
+    if (!currentSet.has(f)) removed++;
+  }
+
+  return {
+    content: result.content,
+    added,
+    removed,
+    unchanged: result.files.length - added,
+    fileCount: result.fileCount,
+    truncated: result.truncated,
+  };
+}
+
+/**
+ * Write CODEBASE.md to .gsd/ directory.
+ */
+export function writeCodebaseMap(basePath: string, content: string): string {
+  const root = gsdRoot(basePath);
+  mkdirSync(root, { recursive: true });
+  const outPath = join(root, "CODEBASE.md");
+  writeFileSync(outPath, content, "utf-8");
+  return outPath;
+}
+
+/**
+ * Read existing CODEBASE.md, or return null if it doesn't exist.
+ */
+export function readCodebaseMap(basePath: string): string | null {
+  const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+  if (!existsSync(codebasePath)) return null;
+  try {
+    return readFileSync(codebasePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get stats about the codebase map.
+ */
+export function getCodebaseMapStats(basePath: string): {
+  exists: boolean;
+  fileCount: number;
+  describedCount: number;
+  undescribedCount: number;
+  generatedAt: string | null;
+} {
+  const content = readCodebaseMap(basePath);
+  if (!content) {
+    return { exists: false, fileCount: 0, describedCount: 0, undescribedCount: 0, generatedAt: null };
+  }
+
+  // Parse total file count from the header line (accurate even for collapsed dirs)
+  const fileCountMatch = content.match(/Files:\s*(\d+)/);
+  const totalFiles = fileCountMatch ? parseInt(fileCountMatch[1], 10) : 0;
+
+  // Use parseCodebaseMap to count described files (includes collapsed-description blocks)
+  const descriptions = parseCodebaseMap(content);
+  const described = [...descriptions.values()].filter((d) => d.length > 0).length;
+  const dateMatch = content.match(/Generated: (\S+)/);
+
+  return {
+    exists: true,
+    fileCount: totalFiles,
+    describedCount: described,
+    undescribedCount: totalFiles - described,
+    generatedAt: dateMatch?.[1] ?? null,
+  };
+}