gsd-pi 2.59.0 → 2.60.0-dev.2580e65

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

@@ -14,14 +14,21 @@ import {
   getCodebaseMapStats,
   readCodebaseMap,
 } from "./codebase-generator.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import type { CodebaseMapOptions } from "./codebase-generator.js";
 
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
-  "  generate [--max-files N]  — Generate or regenerate CODEBASE.md\n" +
-  "  update                    — Incremental update (preserves descriptions)\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.";
+  "  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" +
+  "  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" +
+  "Configure defaults via preferences.md:\n" +
+  "  codebase:\n" +
+  "    exclude_patterns: [\"docs/\", \"fixtures/\"]\n" +
+  "    max_files: 1000\n" +
+  "    collapse_threshold: 15";
 
 export async function handleCodebase(
   args: string,
@@ -34,15 +41,15 @@ export async function handleCodebase(
 
   switch (sub) {
     case "generate": {
-      const maxFiles = parseMaxFiles(args, ctx);
-      if (maxFiles === false) return; // validation failed, message already shown
+      const options = resolveCodebaseOptions(args, ctx);
+      if (options === false) return; // validation failed, message already shown
 
       const existing = readCodebaseMap(basePath);
       const existingDescriptions = existing
         ? (await import("./codebase-generator.js")).parseCodebaseMap(existing)
         : undefined;
 
-      const result = generateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined }, existingDescriptions);
+      const result = generateCodebaseMap(basePath, options, existingDescriptions);
 
       if (result.fileCount === 0) {
         ctx.ui.notify(
@@ -73,10 +80,10 @@ export async function handleCodebase(
         return;
       }
 
-      const maxFiles = parseMaxFiles(args, ctx);
-      if (maxFiles === false) return;
+      const options = resolveCodebaseOptions(args, ctx);
+      if (options === false) return;
 
-      const result = updateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined });
+      const result = updateCodebaseMap(basePath, options);
       writeCodebaseMap(basePath, result.content);
 
       ctx.ui.notify(
@@ -141,19 +148,44 @@ function showStats(basePath: string, ctx: ExtensionCommandContext): void {
 }
 
 /**
- * Parse and validate --max-files flag.
- * Returns the parsed number, undefined if flag not present, or false if invalid.
+ * Resolve codebase map options by merging preferences with CLI flags.
+ * CLI flags override preferences; preferences override built-in defaults.
+ * Returns false if validation failed (error already shown to user).
  */
-function parseMaxFiles(args: string, ctx: ExtensionCommandContext): number | undefined | false {
+function resolveCodebaseOptions(args: string, ctx: ExtensionCommandContext): CodebaseMapOptions | false {
+  // Load preferences defaults
+  const prefs = loadEffectiveGSDPreferences()?.preferences?.codebase;
+
+  // Parse CLI flags
   const maxFilesStr = extractFlag(args, "--max-files");
-  if (!maxFilesStr) return undefined;
+  const collapseStr = extractFlag(args, "--collapse-threshold");
+
+  // Validate --max-files
+  let maxFiles: number | undefined;
+  if (maxFilesStr) {
+    maxFiles = parseInt(maxFilesStr, 10);
+    if (isNaN(maxFiles) || maxFiles < 1) {
+      ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning");
+      return false;
+    }
+  }
 
-  const maxFiles = parseInt(maxFilesStr, 10);
-  if (isNaN(maxFiles) || maxFiles < 1) {
-    ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning");
-    return false;
+  // Validate --collapse-threshold
+  let collapseThreshold: number | undefined;
+  if (collapseStr) {
+    collapseThreshold = parseInt(collapseStr, 10);
+    if (isNaN(collapseThreshold) || collapseThreshold < 1) {
+      ctx.ui.notify("--collapse-threshold must be a positive integer (e.g. --collapse-threshold 15).", "warning");
+      return false;
+    }
   }
-  return maxFiles;
+
+  return {
+    // CLI flags override preferences
+    maxFiles: maxFiles ?? prefs?.max_files,
+    collapseThreshold: collapseThreshold ?? prefs?.collapse_threshold,
+    excludePatterns: prefs?.exclude_patterns,
+  };
 }
 
 function extractFlag(args: string, flag: string): string | undefined {

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

@@ -8,6 +8,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
 import { getErrorMessage } from "./error-utils.js";
 
 export interface InspectData {
@@ -92,7 +93,7 @@ export async function handleInspect(ctx: ExtensionCommandContext): Promise<void>
 
     ctx.ui.notify(formatInspectOutput(data), "info");
   } catch (err) {
-    process.stderr.write(`gsd-db: /gsd inspect failed: ${getErrorMessage(err)}\n`);
+    logWarning("command", `/gsd inspect failed: ${getErrorMessage(err)}`);
     ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
   }
 }

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

@@ -7,12 +7,14 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { deriveState } from "./state.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
+import { logWarning } from "./workflow-logger.js";
 
 export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
   let branches: string[];
   try {
     branches = nativeBranchList(basePath, "gsd/*");
-  } catch {
+  } catch (e) {
+    logWarning("command", `branch list failed: ${(e as Error).message}`);
     ctx.ui.notify("No GSD branches to clean up.", "info");
     return;
   }
@@ -23,7 +25,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
   let merged: string[];
   try {
     merged = nativeBranchListMerged(basePath, mainBranch, "gsd/*");
-  } catch {
+  } catch (e) {
+    logWarning("command", `merged branch list failed: ${(e as Error).message}`);
     merged = [];
   }
 
@@ -33,8 +36,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
     try {
       nativeBranchDelete(basePath, branch, false);
       deletedMerged++;
-    } catch {
-      /* skip branches that cannot be deleted */
+    } catch (e) {
+      logWarning("command", `branch delete failed for ${branch}: ${(e as Error).message}`);
     }
   }
 
@@ -66,7 +69,7 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
           try {
             nativeBranchDelete(basePath, branch, true);
             deletedStaleMilestones++;
-          } catch { /* non-fatal */ }
+          } catch (e) { logWarning("command", `stale milestone branch delete failed for ${branch}: ${(e as Error).message}`); }
           continue;
         }
       }
@@ -77,7 +80,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
       let roadmapContent: string | null = null;
       try {
         roadmapContent = await loadFile(roadmapPath);
-      } catch {
+      } catch (e) {
+        logWarning("command", `loadFile failed for ${roadmapPath}: ${(e as Error).message}`);
         roadmapContent = null;
       }
       if (!roadmapContent) continue;
@@ -85,12 +89,12 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
       try {
         nativeBranchDelete(basePath, branch, true);
         deletedStaleMilestones++;
-      } catch {
-        /* non-fatal */
+      } catch (e) {
+        logWarning("command", `milestone branch delete failed for ${branch}: ${(e as Error).message}`);
       }
     }
-  } catch {
-    /* non-fatal */
+  } catch (e) {
+    logWarning("command", `stale milestone cleanup failed: ${(e as Error).message}`);
   }
 
   const summary: string[] = [];
@@ -122,7 +126,8 @@ export async function handleCleanupSnapshots(ctx: ExtensionCommandContext, baseP
   let refs: string[];
   try {
     refs = nativeForEachRef(basePath, "refs/gsd/snapshots/");
-  } catch {
+  } catch (e) {
+    logWarning("command", `snapshot ref list failed: ${(e as Error).message}`);
     ctx.ui.notify("No snapshot refs to clean up.", "info");
     return;
   }
@@ -147,8 +152,8 @@ export async function handleCleanupSnapshots(ctx: ExtensionCommandContext, baseP
       try {
         nativeUpdateRef(basePath, old);
         pruned++;
-      } catch {
-        /* skip individual failures */
+      } catch (e) {
+        logWarning("command", `snapshot ref update failed for ${old}: ${(e as Error).message}`);
       }
     }
   }
@@ -164,7 +169,8 @@ export async function handleCleanupWorktrees(ctx: ExtensionCommandContext, baseP
   let statuses;
   try {
     statuses = getAllWorktreeHealth(basePath);
-  } catch {
+  } catch (e) {
+    logWarning("command", `worktree health inspection failed: ${(e as Error).message}`);
     ctx.ui.notify("Failed to inspect worktrees.", "error");
     return;
   }
@@ -197,7 +203,8 @@ export async function handleCleanupWorktrees(ctx: ExtensionCommandContext, baseP
         removeWorktree(basePath, wt.name, { deleteBranch: true });
         lines.push(`  ✓ ${wt.name}  removed (branch ${wt.branch} deleted)`);
         removed++;
-      } catch {
+      } catch (e) {
+        logWarning("command", `worktree removal failed for ${wt.name}: ${(e as Error).message}`);
         lines.push(`  ✗ ${wt.name}  failed to remove`);
       }
     }
@@ -246,7 +253,7 @@ export async function handleSkip(unitArg: string, ctx: ExtensionCommandContext,
     if (fileExists(completedKeysFile)) {
       keys = JSON.parse(readFile(completedKeysFile, "utf-8"));
     }
-  } catch { /* start fresh */ }
+  } catch (e) { logWarning("command", `completed-units.json parse failed: ${(e as Error).message}`); }
 
   // Normalize: accept "execute-task/M001/S01/T03", "M001/S01/T03", or just "T03"
   let skipKey = unitArg;
@@ -371,7 +378,8 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
     hashList = readdirSync(projectsDir, { withFileTypes: true })
       .filter(e => e.isDirectory())
       .map(e => e.name);
-  } catch {
+  } catch (e) {
+    logWarning("command", `readdir failed for project-state directory: ${(e as Error).message}`);
     ctx.ui.notify(`Failed to read project-state directory at ${projectsDir}.`, "error");
     return;
   }
@@ -454,7 +462,8 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
       try {
         fsRmSync(pathJoin(projectsDir, e.hash), { recursive: true, force: true });
         removed++;
-      } catch {
+      } catch (err) {
+        logWarning("command", `project cleanup rm failed for ${e.hash}: ${(err as Error).message}`);
         failed.push(e.hash);
       }
     }
@@ -529,7 +538,7 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
     ctx.ui.notify(lines.join("\n"), "success");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`gsd-recover: failed: ${msg}\n`);
+    logWarning("command", `recover failed: ${msg}`);
     ctx.ui.notify(`gsd recover failed: ${msg}`, "error");
   }
 }

package/src/resources/extensions/gsd/complexity-classifier.ts

@@ -16,6 +16,7 @@ export interface ClassificationResult {
   tier: ComplexityTier;
   reason: string;
   downgraded: boolean;   // true if budget pressure lowered the tier
+  taskMetadata?: TaskMetadata;
 }
 
 export interface TaskMetadata {
@@ -71,17 +72,20 @@ export function classifyUnitComplexity(
 ): ClassificationResult {
   // Hook units default to light
   if (unitType.startsWith("hook/")) {
-    const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false };
+    const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false, taskMetadata: undefined };
     return applyBudgetPressure(result, budgetPct);
   }
 
   // Start with the default tier for this unit type
   let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
   let reason = `unit type: ${unitType}`;
+  let taskMeta: TaskMetadata | undefined;
 
   // For execute-task, analyze task metadata for complexity signals
   if (unitType === "execute-task") {
-    const taskAnalysis = analyzeTaskComplexity(unitId, basePath, metadata);
+    // Extract metadata once and reuse throughout to avoid double-extraction
+    taskMeta = metadata ?? extractTaskMetadata(unitId, basePath);
+    const taskAnalysis = analyzeTaskComplexity(unitId, basePath, taskMeta);
     tier = taskAnalysis.tier;
     reason = taskAnalysis.reason;
   }
@@ -96,14 +100,15 @@ export function classifyUnitComplexity(
   }
 
   // Adaptive learning: check if history suggests bumping the tier
-  const tags = metadata?.tags ?? extractTaskMetadata(unitId, basePath).tags;
+  // Use already-extracted taskMeta.tags if available to avoid double-extraction
+  const tags = taskMeta?.tags ?? metadata?.tags;
   const adaptiveAdjustment = getAdaptiveTierAdjustment(unitType, tier, tags);
   if (adaptiveAdjustment && tierOrdinal(adaptiveAdjustment) > tierOrdinal(tier)) {
     reason = `${reason} (adaptive: high failure rate at ${tier})`;
     tier = adaptiveAdjustment;
   }
 
-  const result: ClassificationResult = { tier, reason, downgraded: false };
+  const result: ClassificationResult = { tier, reason, downgraded: false, taskMetadata: taskMeta };
   return applyBudgetPressure(result, budgetPct);
 }
 
@@ -212,7 +217,7 @@ function analyzePlanComplexity(
 /**
  * Extract task metadata from the task plan file on disk.
  */
-function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
+export function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata {
   const meta: TaskMetadata = {};
   const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   if (!mid || !sid || !tid) return meta;

package/src/resources/extensions/gsd/context-masker.ts

@@ -0,0 +1,74 @@
+/**
+ * Observation masking for GSD auto-mode sessions.
+ *
+ * Replaces tool result content older than N turns with a placeholder.
+ * Reduces context bloat between compactions with zero LLM overhead.
+ * Preserves message ordering, roles, and all assistant/user messages.
+ *
+ * Operates on the pi-ai Message[] format (post-convertToLlm, pre-provider):
+ *   - toolResult messages: { role: "toolResult", content: TextContent[] }
+ *   - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] }
+ *     and start with "Ran `" from bashExecutionToText.
+ */
+
+interface MaskableMessage {
+  role: string;
+  content: unknown;
+  type?: string;
+  [key: string]: unknown;
+}
+
+const MASK_PLACEHOLDER = "[result masked — within summarized history]";
+const MASK_CONTENT_BLOCK = [{ type: "text" as const, text: MASK_PLACEHOLDER }];
+
+function findTurnBoundary(messages: MaskableMessage[], keepRecentTurns: number): number {
+  let turnsSeen = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    // In the LLM payload, genuine user turns have role "user".
+    // Tool results have role "toolResult" and are excluded by this check.
+    if (m.role === "user") {
+      // Skip bash-result user messages (converted from bashExecution) — these aren't real user turns
+      if (isBashResultUserMessage(m)) continue;
+      turnsSeen++;
+      if (turnsSeen >= keepRecentTurns) return i;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Detect user messages that originated from bashExecution.
+ * After convertToLlm, these are {role: "user", content: [{type:"text", text:"Ran `cmd`\n..."}]}.
+ * The bashExecutionToText format always starts with "Ran `".
+ */
+function isBashResultUserMessage(m: MaskableMessage): boolean {
+  if (m.role !== "user" || !Array.isArray(m.content)) return false;
+  const first = m.content[0];
+  return first && typeof first === "object" && "text" in first &&
+    typeof first.text === "string" && first.text.startsWith("Ran `");
+}
+
+function isMaskableMessage(m: MaskableMessage): boolean {
+  // Tool result messages (role: "toolResult" in pi-ai format)
+  if (m.role === "toolResult") return true;
+  // Bash-result user messages (converted from bashExecution by convertToLlm)
+  if (isBashResultUserMessage(m)) return true;
+  return false;
+}
+
+export function createObservationMask(keepRecentTurns: number = 8) {
+  return (messages: MaskableMessage[]): MaskableMessage[] => {
+    const boundary = findTurnBoundary(messages, keepRecentTurns);
+    if (boundary === 0) return messages;
+
+    return messages.map((m, i) => {
+      if (i >= boundary) return m;
+      if (isMaskableMessage(m)) {
+        // Content may be string or array of content blocks — always replace with array
+        return { ...m, content: MASK_CONTENT_BLOCK };
+      }
+      return m;
+    });
+  };
+}

package/src/resources/extensions/gsd/custom-verification.ts

@@ -17,6 +17,7 @@
  * - The frozen DEFINITION.yaml on disk is the single source of truth for step policies.
  */
 
+import { logWarning } from "./workflow-logger.js";
 import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -130,8 +131,8 @@ function handleContentHeuristic(
         if (!new RegExp(verify.pattern).test(content)) {
           return "pause";
         }
-      } catch {
-        // Invalid regex at runtime — treat as verification failure
+      } catch (e) {
+        logWarning("engine", `content-heuristic regex failed: ${(e as Error).message}`);
         return "pause";
       }
     }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -189,6 +189,13 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `budget_pressure`: boolean — downgrade model tier when budget is under pressure. Default: `true`.
   - `cross_provider`: boolean — allow routing across different providers. Default: `true`.
   - `hooks`: boolean — enable routing hooks. Default: `true`.
+  - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
+
+- `context_management`: configures context hygiene for auto-mode sessions. Keys:
+  - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
+  - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.
+  - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.70`.
+  - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`.
 
 - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.
 

package/src/resources/extensions/gsd/gsd-db.ts

@@ -10,7 +10,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
-import { logError } from "./workflow-logger.js";
+import { logError, logWarning } from "./workflow-logger.js";
 
 const _require = createRequire(import.meta.url);
 
@@ -787,11 +787,11 @@ export function openDatabase(path: string): boolean {
         initSchema(adapter, fileBacked);
         process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n");
       } catch (retryErr) {
-        try { adapter.close(); } catch { /* swallow */ }
+        try { adapter.close(); } catch (e) { logWarning("db", `close after VACUUM failed: ${(e as Error).message}`); }
         throw retryErr;
       }
     } else {
-      try { adapter.close(); } catch { /* swallow */ }
+      try { adapter.close(); } catch (e) { logWarning("db", `close after VACUUM failed: ${(e as Error).message}`); }
       throw err;
     }
   }
@@ -802,7 +802,7 @@ export function openDatabase(path: string): boolean {
 
   if (!_exitHandlerRegistered) {
     _exitHandlerRegistered = true;
-    process.on("exit", () => { try { closeDatabase(); } catch {} });
+    process.on("exit", () => { try { closeDatabase(); } catch (e) { logWarning("db", `exit handler close failed: ${(e as Error).message}`); } });
   }
 
   return true;
@@ -812,16 +812,14 @@ export function closeDatabase(): void {
   if (currentDb) {
     try {
       currentDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-    } catch { /* non-fatal — best effort before close */ }
+    } catch (e) { logWarning("db", `WAL checkpoint failed: ${(e as Error).message}`); }
     try {
       // Incremental vacuum to reclaim space without blocking
       currentDb.exec('PRAGMA incremental_vacuum(64)');
-    } catch { /* non-fatal */ }
+    } catch (e) { logWarning("db", `incremental vacuum failed: ${(e as Error).message}`); }
     try {
       currentDb.close();
-    } catch {
-      // swallow close errors
-    }
+    } catch (e) { logWarning("db", `database close failed: ${(e as Error).message}`); }
     currentDb = null;
     currentPath = null;
     currentPid = 0;
@@ -833,7 +831,7 @@ export function vacuumDatabase(): void {
   if (!currentDb) return;
   try {
     currentDb.exec('VACUUM');
-  } catch { /* non-fatal */ }
+  } catch (e) { logWarning("db", `VACUUM failed: ${(e as Error).message}`); }
 }
 
 let _txDepth = 0;
@@ -1038,7 +1036,7 @@ export function upsertRequirement(r: Requirement): void {
 
 export function clearArtifacts(): void {
   if (!currentDb) return;
-  try { currentDb.exec("DELETE FROM artifacts"); } catch { /* cache clear is best effort */ }
+  try { currentDb.exec("DELETE FROM artifacts"); } catch (e) { logWarning("db", `clearArtifacts failed: ${(e as Error).message}`); }
 }
 
 export function insertArtifact(a: {
@@ -1661,11 +1659,11 @@ export function getActiveSliceFromDb(milestoneId: string): SliceRow | null {
   const row = currentDb.prepare(
     `SELECT s.* FROM slices s
      WHERE s.milestone_id = :mid
-       AND s.status NOT IN ('complete', 'done')
+       AND s.status NOT IN ('complete', 'done', 'skipped')
        AND NOT EXISTS (
          SELECT 1 FROM json_each(s.depends) AS dep
          WHERE dep.value NOT IN (
-           SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done')
+           SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done', 'skipped')
          )
        )
      ORDER BY s.sequence, s.id
@@ -1801,7 +1799,7 @@ export function reconcileWorktreeDb(
   // ATTACHing a WAL-mode DB to itself corrupts the WAL (#2823).
   try {
     if (realpathSync(mainDbPath) === realpathSync(worktreeDbPath)) return zero;
-  } catch { /* path resolution failed — fall through to existing checks */ }
+  } catch (e) { logWarning("db", `realpathSync failed: ${(e as Error).message}`); }
   // Sanitize path: reject any characters that could break ATTACH syntax.
   // ATTACH DATABASE doesn't support parameterized paths in all providers,
   // so we use strict allowlist validation instead.
@@ -1938,12 +1936,12 @@ export function reconcileWorktreeDb(
 
         adapter.exec("COMMIT");
       } catch (txErr) {
-        try { adapter.exec("ROLLBACK"); } catch { /* best effort */ }
+        try { adapter.exec("ROLLBACK"); } catch (e) { logWarning("db", `rollback failed: ${(e as Error).message}`); }
         throw txErr;
       }
       return { ...merged, conflicts };
     } finally {
-      try { adapter.exec("DETACH DATABASE wt"); } catch { /* best effort */ }
+      try { adapter.exec("DETACH DATABASE wt"); } catch (e) { logWarning("db", `detach worktree DB failed: ${(e as Error).message}`); }
     }
   } catch (err) {
     logError("db", "worktree DB reconciliation failed", { error: (err as Error).message });

package/src/resources/extensions/gsd/guided-flow.ts

@@ -52,6 +52,7 @@ export {
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
 import { getErrorMessage } from "./error-utils.js";
+import { logWarning } from "./workflow-logger.js";
 
 // ─── ID Generation with Reservation ─────────────────────────────────────────
 
@@ -180,7 +181,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
           );
         }
       }
-    } catch { /* non-fatal — PROJECT.md parsing failure shouldn't block auto-start */ }
+    } catch (e) { logWarning("guided", `PROJECT.md parsing failed: ${(e as Error).message}`); }
   }
 
   // Gate 4: Discussion manifest process verification (multi-milestone only)
@@ -212,7 +213,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
           );
         }
       }
-    } catch { /* malformed manifest — warn but don't block */ }
+    } catch (e) { logWarning("guided", `discussion manifest verification failed: ${(e as Error).message}`); }
   }
 
   // Draft promotion cleanup: if a CONTEXT-DRAFT.md exists alongside the new
@@ -220,16 +221,16 @@ export function checkAutoStartAfterDiscuss(): boolean {
   try {
     const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT");
     if (draftFile) unlinkSync(draftFile);
-  } catch { /* non-fatal — stale draft doesn't break anything, CONTEXT.md wins */ }
+  } catch (e) { logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`); }
 
   // Cleanup: remove discussion manifest after auto-start (only needed during discussion)
-  try { unlinkSync(manifestPath); } catch { /* may not exist for single-milestone */ }
+  try { unlinkSync(manifestPath); } catch (e) { logWarning("guided", `manifest unlink failed: ${(e as Error).message}`); }
 
   pendingAutoStartMap.delete(basePath);
   ctx.ui.notify(`Milestone ${milestoneId} ready.`, "info");
   startAuto(ctx, pi, basePath, false, { step }).catch((err) => {
     ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error");
-    if (process.env.GSD_DEBUG) console.error('[gsd] auto start error:', err);
+    logWarning("guided", `auto start error: ${getErrorMessage(err)}`);
     debugLog("auto-start-failed", { error: getErrorMessage(err) });
   });
   return true;
@@ -895,8 +896,8 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
       ctx.ui.notify(`Self-heal: cleared ${cleared} stale runtime record(s) from a previous session.`, "info");
     }
     return { cleared };
-  } catch {
-    // Non-fatal — self-heal should never block the wizard
+  } catch (e) {
+    logWarning("guided", `self-heal stale runtime records failed: ${(e as Error).message}`);
     return { cleared: 0 };
   }
 }
@@ -1142,7 +1143,7 @@ export async function showSmartEntry(
             );
             return;
           }
-        } catch { /* directory exists but unreadable — fall through to normal flow */ }
+        } catch (e) { logWarning("guided", `directory read failed: ${(e as Error).message}`); }
       }
     }
 

package/src/resources/extensions/gsd/init-wizard.ts

@@ -16,6 +16,7 @@ import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
 import type { ProjectDetection, ProjectSignals } from "./detection.js";
 import { runSkillInstallStep } from "./skill-catalog.js";
+import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -238,6 +239,17 @@ export async function showProjectInit(
   ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
 
+  // Auto-generate codebase map for instant agent orientation
+  try {
+    const result = generateCodebaseMap(basePath);
+    if (result.fileCount > 0) {
+      writeCodebaseMap(basePath, result.content);
+      ctx.ui.notify(`Codebase map generated: ${result.fileCount} files`, "info");
+    }
+  } catch {
+    // Non-fatal — codebase map generation failure should never block project init
+  }
+
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
 
   return { completed: true, bootstrapped: true };