gsd-pi 2.58.0-dev.778d6ac → 2.58.0-dev.e002a57

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

@@ -206,5 +206,10 @@ Examples:
     await handleRethink(trimmed, ctx, pi);
     return true;
   }
+  if (trimmed === "codebase" || trimmed.startsWith("codebase ")) {
+    const { handleCodebase } = await import("../../commands-codebase.js");
+    await handleCodebase(trimmed.replace(/^codebase\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   return false;
 }

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

@@ -0,0 +1,164 @@
+/**
+ * GSD Command — /gsd codebase
+ *
+ * Generate and manage the codebase map (.gsd/CODEBASE.md).
+ * Subcommands: generate, update, stats, help
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import {
+  generateCodebaseMap,
+  updateCodebaseMap,
+  writeCodebaseMap,
+  getCodebaseMapStats,
+  readCodebaseMap,
+} 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.";
+
+export async function handleCodebase(
+  args: string,
+  ctx: ExtensionCommandContext,
+  _pi: ExtensionAPI,
+): Promise<void> {
+  const basePath = process.cwd();
+  const parts = args.trim().split(/\s+/);
+  const sub = parts[0] ?? "";
+
+  switch (sub) {
+    case "generate": {
+      const maxFiles = parseMaxFiles(args, ctx);
+      if (maxFiles === 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);
+
+      if (result.fileCount === 0) {
+        ctx.ui.notify(
+          "Codebase map generated with 0 files.\n" +
+          "Is this a git repository? Run 'git ls-files' to verify.",
+          "warning",
+        );
+        return;
+      }
+
+      const outPath = writeCodebaseMap(basePath, result.content);
+      ctx.ui.notify(
+        `Codebase map generated: ${result.fileCount} files\n` +
+        `Written to: ${outPath}` +
+        (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""),
+        "success",
+      );
+      return;
+    }
+
+    case "update": {
+      const existing = readCodebaseMap(basePath);
+      if (!existing) {
+        ctx.ui.notify(
+          "No codebase map found. Run /gsd codebase generate to create one.",
+          "warning",
+        );
+        return;
+      }
+
+      const maxFiles = parseMaxFiles(args, ctx);
+      if (maxFiles === false) return;
+
+      const result = updateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined });
+      writeCodebaseMap(basePath, result.content);
+
+      ctx.ui.notify(
+        `Codebase map updated: ${result.fileCount} files\n` +
+        `  Added: ${result.added} | Removed: ${result.removed} | Unchanged: ${result.unchanged}` +
+        (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""),
+        "success",
+      );
+      return;
+    }
+
+    case "stats": {
+      showStats(basePath, ctx);
+      return;
+    }
+
+    case "help":
+      ctx.ui.notify(USAGE, "info");
+      return;
+
+    case "": {
+      // Safe default: show stats if map exists, help if not
+      const existing = readCodebaseMap(basePath);
+      if (existing) {
+        showStats(basePath, ctx);
+      } else {
+        ctx.ui.notify(USAGE, "info");
+      }
+      return;
+    }
+
+    default:
+      ctx.ui.notify(
+        `Unknown subcommand "${sub}".\n\n${USAGE}`,
+        "warning",
+      );
+  }
+}
+
+function showStats(basePath: string, ctx: ExtensionCommandContext): void {
+  const stats = getCodebaseMapStats(basePath);
+  if (!stats.exists) {
+    ctx.ui.notify("No codebase map found. Run /gsd codebase generate to create one.", "info");
+    return;
+  }
+
+  const coverage = stats.fileCount > 0
+    ? Math.round((stats.describedCount / stats.fileCount) * 100)
+    : 0;
+
+  ctx.ui.notify(
+    `Codebase Map Stats:\n` +
+    `  Files: ${stats.fileCount}\n` +
+    `  Described: ${stats.describedCount} (${coverage}%)\n` +
+    `  Undescribed: ${stats.undescribedCount}\n` +
+    `  Generated: ${stats.generatedAt ?? "unknown"}\n\n` +
+    (stats.undescribedCount > 0
+      ? `Tip: Run /gsd codebase update to refresh after file changes.`
+      : `Coverage is complete.`),
+    "info",
+  );
+}
+
+/**
+ * Parse and validate --max-files flag.
+ * Returns the parsed number, undefined if flag not present, or false if invalid.
+ */
+function parseMaxFiles(args: string, ctx: ExtensionCommandContext): number | undefined | false {
+  const maxFilesStr = extractFlag(args, "--max-files");
+  if (!maxFilesStr) return undefined;
+
+  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;
+  }
+  return maxFiles;
+}
+
+function extractFlag(args: string, flag: string): string | undefined {
+  const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`${escaped}[=\\s]+(\\S+)`);
+  const match = args.match(regex);
+  return match?.[1];
+}

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -184,11 +184,23 @@ export function buildCategorySummaries(prefs: Record<string, unknown>): Record<s
 
   // Git
   const git = prefs.git as Record<string, unknown> | undefined;
+  const staleThreshold = prefs.stale_commit_threshold_minutes;
+  const absorbSnapshots = git?.absorb_snapshot_commits;
   let gitSummary = "(defaults)";
-  if (git && Object.keys(git).length > 0) {
-    const branch = git.main_branch ?? "main";
-    const push = git.auto_push ? "on" : "off";
-    gitSummary = `main: ${branch}, push: ${push}`;
+  {
+    const parts: string[] = [];
+    if (git && Object.keys(git).length > 0) {
+      const branch = git.main_branch ?? "main";
+      const push = git.auto_push ? "on" : "off";
+      parts.push(`main: ${branch}, push: ${push}`);
+    }
+    if (staleThreshold !== undefined) {
+      parts.push(`stale: ${staleThreshold === 0 ? "off" : `${staleThreshold}m`}`);
+    }
+    if (absorbSnapshots !== undefined) {
+      parts.push(`absorb: ${absorbSnapshots ? "on" : "off"}`);
+    }
+    if (parts.length > 0) gitSummary = parts.join(", ");
   }
 
   // Skills
@@ -469,9 +481,39 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
     git.isolation = isolationChoice;
   }
 
+  // absorb_snapshot_commits (git sub-key)
+  const currentAbsorb = git.absorb_snapshot_commits;
+  const absorbStr = currentAbsorb !== undefined ? String(currentAbsorb) : "";
+  const absorbChoice = await ctx.ui.select(
+    `Absorb snapshot commits into real commits${absorbStr ? ` (current: ${absorbStr})` : " (default: true)"}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (absorbChoice && absorbChoice !== "(keep current)") {
+    git.absorb_snapshot_commits = absorbChoice === "true";
+  }
+
   if (Object.keys(git).length > 0) {
     prefs.git = git;
   }
+
+  // stale_commit_threshold_minutes (top-level pref, shown in Git section)
+  const currentThreshold = prefs.stale_commit_threshold_minutes;
+  const thresholdStr = currentThreshold !== undefined ? String(currentThreshold) : "";
+  const thresholdInput = await ctx.ui.input(
+    `Stale commit threshold (minutes, 0 to disable)${thresholdStr ? ` (current: ${thresholdStr})` : " (default: 30)"}:`,
+    thresholdStr || "30",
+  );
+  if (thresholdInput !== null && thresholdInput !== undefined) {
+    const val = thresholdInput.trim();
+    const parsed = tryParseInteger(val);
+    if (val && parsed !== null && parsed >= 0) {
+      prefs.stale_commit_threshold_minutes = parsed;
+    } else if (val && parsed === null) {
+      ctx.ui.notify(`Invalid value "${val}" — must be a whole number. Keeping previous value.`, "warning");
+    } else if (!val && currentThreshold !== undefined) {
+      delete prefs.stale_commit_threshold_minutes;
+    }
+  }
 }
 
 async function configureSkills(ctx: ExtensionCommandContext, prefs: Record<string, unknown>): Promise<void> {

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

@@ -35,15 +35,17 @@ const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
   "complete-slice": "light",
   "run-uat": "light",
 
-  // Tier 2 — Standard: research, routine planning, discussion
+  // Tier 2 — Standard: research, routine discussion
   "discuss-milestone": "standard",
   "discuss-slice": "standard",
   "research-milestone": "standard",
   "research-slice": "standard",
-  "plan-milestone": "standard",
-  "plan-slice": "standard",
 
-  // Tier 3 — Heavy: execution, replanning (requires deep reasoning)
+  // Tier 3 — Heavy: planning, execution, replanning (requires deep reasoning)
+  // Planning is heavy so it uses the best configured model (e.g. Opus) and is
+  // not downgraded by dynamic routing when a capable model is configured.
+  "plan-milestone": "heavy",
+  "plan-slice": "heavy",
   "execute-task": "standard",   // default standard, upgraded by metadata
   "replan-slice": "heavy",
   "reassess-roadmap": "heavy",
@@ -185,8 +187,8 @@ function analyzePlanComplexity(
   // Check if this is a milestone-level plan (more complex) vs single slice
   const { milestone: mid, slice: sid } = parseUnitId(unitId);
   if (!sid) {
-    // Milestone-level planning is always at least standard
-    return { tier: "standard", reason: "milestone-level planning" };
+    // Milestone-level planning is always heavy — requires full context and best model
+    return { tier: "heavy", reason: "milestone-level planning" };
   }
 
   // For slice planning, try to read the context/research to gauge complexity

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -10,7 +10,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 } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 
@@ -363,6 +363,54 @@ export async function checkGitHealth(
     // Non-fatal — orphaned worktree directory check failed
   }
 
+  // ── Stale uncommitted changes ────────────────────────────────────────────
+  // If the working tree has uncommitted changes and the last commit was
+  // longer ago than the configured threshold, flag it and optionally
+  // auto-commit a safety snapshot so work isn't lost.
+  try {
+    const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
+    const thresholdMinutes = prefs.stale_commit_threshold_minutes ?? 30;
+
+    if (thresholdMinutes > 0) {
+      const dirty = nativeHasChanges(basePath);
+      if (dirty) {
+        const branch = nativeGetCurrentBranch(basePath);
+        const lastEpoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+        const nowEpoch = Math.floor(Date.now() / 1000);
+        const minutesSinceCommit = lastEpoch > 0 ? (nowEpoch - lastEpoch) / 60 : Infinity;
+
+        if (minutesSinceCommit >= thresholdMinutes) {
+          const mins = Math.floor(minutesSinceCommit);
+          issues.push({
+            severity: "warning",
+            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.`,
+            fixable: true,
+          });
+
+          if (shouldFix("stale_uncommitted_changes")) {
+            try {
+              nativeAddTracked(basePath);
+              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");
+              }
+            } catch {
+              fixesApplied.push("failed to create gsd snapshot commit");
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — stale commit check failed
+  }
+
   // ── Worktree lifecycle checks ──────────────────────────────────────────
   // Check GSD-managed worktrees for: merged branches, stale work, dirty
   // state, and unpushed commits. Only worktrees under .gsd/worktrees/.

package/src/resources/extensions/gsd/doctor-proactive.ts

@@ -22,7 +22,7 @@ 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 } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 
@@ -295,6 +295,40 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
     // Non-fatal — dispatch continues if state/branch check fails
   }
 
+  // ── Stale uncommitted changes — auto-snapshot before dispatch ──
+  // If the working tree is dirty and no commit has happened recently,
+  // create a safety snapshot so work isn't lost if the next unit crashes.
+  try {
+    if (nativeIsRepo(basePath)) {
+      const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
+      const thresholdMinutes = prefs.stale_commit_threshold_minutes ?? 30;
+
+      if (thresholdMinutes > 0 && nativeHasChanges(basePath)) {
+        const branch = nativeGetCurrentBranch(basePath);
+        const lastEpoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+        const nowEpoch = Math.floor(Date.now() / 1000);
+        const minutesSinceCommit = lastEpoch > 0 ? (nowEpoch - lastEpoch) / 60 : Infinity;
+
+        if (minutesSinceCommit >= thresholdMinutes) {
+          const mins = Math.floor(minutesSinceCommit);
+          try {
+            nativeAddTracked(basePath);
+            const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`;
+            const result = nativeCommit(basePath, commitMsg);
+            if (result) {
+              fixesApplied.push(`pre-dispatch: created gsd snapshot after ${mins}m of uncommitted changes`);
+            }
+          } catch {
+            // Non-blocking — snapshot failed but dispatch can continue
+            fixesApplied.push("pre-dispatch: gsd snapshot failed");
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+
   // ── Disk space check ──
   // Catches low-disk conditions before dispatch rather than letting the unit
   // fail mid-execution with ENOSPC (which wastes a full LLM turn).

package/src/resources/extensions/gsd/doctor-types.ts

@@ -61,6 +61,8 @@ export type DoctorIssueCode =
   | "worktree_stale"
   | "worktree_dirty"
   | "worktree_unpushed"
+  // Stale commit safety check
+  | "stale_uncommitted_changes"
   // Snapshot ref bloat
   | "snapshot_ref_bloat"
   // Runtime data integrity

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

@@ -48,7 +48,9 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fet
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?refused|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
-const STREAM_RE = /Unexpected end of JSON|Unexpected token.*JSON|Expected.*in JSON|Unterminated.*in JSON|SyntaxError.*JSON/i;
+// Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
+// This eliminates the need to enumerate every error message variant individually.
+const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 
 /**
@@ -91,9 +93,6 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
   }
 
   // 4. Stream truncation — downstream symptom of connection drop
-  //    Checked before server/connection because JSON parse errors can contain
-  //    substrings like "position 500" (matches SERVER_RE) or "Unterminated"
-  //    (matches CONNECTION_RE's "terminated" pattern).
   if (STREAM_RE.test(errorMsg)) {
     return { kind: "stream", retryAfterMs: retryAfterMs ?? 15_000 };
   }

package/src/resources/extensions/gsd/git-service.ts

@@ -32,6 +32,8 @@ import {
   nativeRmCached,
   nativeUpdateRef,
   nativeAddPaths,
+  nativeResetSoft,
+  nativeCommitSubject,
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -77,6 +79,11 @@ export interface GitPreferences {
    *  Default: the main branch (from `main_branch` or auto-detected).
    */
   pr_target_branch?: string;
+  /** Whether to squash `gsd snapshot:` commits into the next real autoCommit.
+   *  Enabled by default. Set to false to keep snapshot commits in history
+   *  for forensic inspection.
+   */
+  absorb_snapshot_commits?: boolean;
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -563,9 +570,95 @@ export class GitServiceImpl {
       ? buildTaskCommitMessage(taskContext)
       : `chore: auto-commit after ${unitType}\n\nGSD-Unit: ${unitId}`;
     nativeCommit(this.basePath, message, { allowEmpty: false });
+
+    // Absorb any preceding gsd snapshot commits into this real commit.
+    // Walk backwards from HEAD~1 counting consecutive snapshot subjects,
+    // then soft-reset to before them and re-commit with the same message.
+    this.absorbSnapshotCommits(message);
+
     return message;
   }
 
+  /**
+   * Squash consecutive `gsd snapshot:` commits that sit immediately below
+   * HEAD into the current HEAD commit. This keeps the git history clean
+   * after automated snapshot commits are superseded by real work.
+   *
+   * Guards:
+   * - Opt-in via `absorb_snapshot_commits` preference (default: true).
+   * - Refuses to rewrite commits that have been pushed to the remote
+   *   tracking branch (checks merge-base ancestry).
+   * - Saves HEAD SHA before reset; restores it if the re-commit fails.
+   *
+   * Does nothing if there are no snapshot commits to absorb.
+   */
+  private absorbSnapshotCommits(headMessage: string): void {
+    try {
+      // Opt-in guard — users can disable to keep snapshot commits for forensics
+      if (this.prefs.absorb_snapshot_commits === false) return;
+
+      const GSD_SNAPSHOT_PREFIX = "gsd snapshot:";
+      let count = 0;
+
+      // Walk back from HEAD~1 counting consecutive snapshot commits (cap at 10)
+      for (let i = 1; i <= 10; i++) {
+        const subject = nativeCommitSubject(this.basePath, `HEAD~${i}`);
+        if (!subject.startsWith(GSD_SNAPSHOT_PREFIX)) break;
+        count = i;
+      }
+
+      if (count === 0) return;
+
+      // Guard: don't rewrite history that has been pushed to the remote.
+      // Check whether the newest snapshot commit (HEAD~1) is already
+      // reachable from the remote tracking branch. If it is, the snapshots
+      // have been pushed and must not be squashed via local history rewrite.
+      // (Checking resetTarget instead would false-positive when the remote
+      // is at the pre-snapshot base but the snapshots themselves are local.)
+      const resetTarget = `HEAD~${count + 1}`;
+      try {
+        const branch = nativeGetCurrentBranch(this.basePath);
+        if (branch) {
+          const remoteBranch = `origin/${branch}`;
+          // merge-base --is-ancestor exits 0 if HEAD~1 is ancestor of remote
+          execFileSync("git", ["merge-base", "--is-ancestor", "HEAD~1", remoteBranch], {
+            cwd: this.basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          // If we get here, newest snapshot IS reachable from remote — already pushed
+          return;
+        }
+      } catch {
+        // Not an ancestor or remote doesn't exist — safe to proceed
+      }
+
+      // Save HEAD SHA so we can restore if the re-commit fails
+      const savedHead = execFileSync("git", ["rev-parse", "HEAD"], {
+        cwd: this.basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      }).trim();
+
+      nativeResetSoft(this.basePath, resetTarget);
+
+      // Re-run smartStage so the same RUNTIME_EXCLUSION_PATHS apply.
+      // Snapshot commits used nativeAddTracked (git add -u) which stages
+      // ALL tracked modifications including .gsd/ state files. Without
+      // re-staging, those .gsd/ changes leak into the absorbed commit.
+      this.smartStage();
+
+      try {
+        nativeCommit(this.basePath, headMessage, { allowEmpty: false });
+      } catch {
+        // Re-commit failed — restore original HEAD to avoid leaving the
+        // repo in a partially-reset state with no commit
+        nativeResetSoft(this.basePath, savedHead);
+      }
+    } catch {
+      // Non-fatal — if squash fails, the commits remain unsquashed
+    }
+  }
+
   // ─── Branch Queries ────────────────────────────────────────────────────
 
   /**

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -680,6 +680,16 @@ export function nativeAddAll(basePath: string): void {
   gitFileExec(basePath, ["add", "-A"]);
 }
 
+/**
+ * Stage only already-tracked files (git add -u).
+ * Does NOT add new untracked files — only updates modifications and deletions
+ * for files git already knows about. Safe for automated snapshots where
+ * pulling in unknown untracked files (secrets, binaries) would be dangerous.
+ */
+export function nativeAddTracked(basePath: string): void {
+  gitFileExec(basePath, ["add", "-u"]);
+}
+
 /**
  * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...).
  * Excluded paths are never hashed by git, preventing hangs on large
@@ -931,6 +941,20 @@ export function nativeResetHard(basePath: string): void {
   execSync("git reset --hard HEAD", { cwd: basePath, stdio: "pipe" });
 }
 
+/**
+ * Soft reset to a target ref (git reset --soft <ref>).
+ * Moves HEAD to `target` while keeping all changes staged in the index.
+ * Used to squash snapshot commits back into a single real commit.
+ */
+export function nativeResetSoft(basePath: string, target: string): void {
+  execFileSync("git", ["reset", "--soft", target], {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
 /**
  * Get the subject line of a commit (git log -1 --format=%s <ref>).
  * Returns empty string if the ref doesn't exist.

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

@@ -264,6 +264,7 @@ export const GSD_ROOT_FILES = {
   REQUIREMENTS: "REQUIREMENTS.md",
   OVERRIDES: "OVERRIDES.md",
   KNOWLEDGE: "KNOWLEDGE.md",
+  CODEBASE: "CODEBASE.md",
 } as const;
 
 export type GSDRootFileKey = keyof typeof GSD_ROOT_FILES;
@@ -276,6 +277,7 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   REQUIREMENTS: "requirements.md",
   OVERRIDES: "overrides.md",
   KNOWLEDGE: "knowledge.md",
+  CODEBASE: "codebase.md",
 };
 
 // ─── GSD Root Discovery ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/preferences-types.ts

@@ -93,6 +93,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "service_tier",
   "forensics_dedup",
   "show_token_cost",
+  "stale_commit_threshold_minutes",
   "experimental",
 ]);
 
@@ -253,6 +254,13 @@ export interface GSDPreferences {
   forensics_dedup?: boolean;
   /** Opt-in: show per-prompt and cumulative session token cost in the footer. Default: false. */
   show_token_cost?: boolean;
+  /**
+   * Minutes without a commit before flagging uncommitted changes as stale.
+   * When the threshold is exceeded and the working tree is dirty, doctor will
+   * auto-commit a safety snapshot tagged with `[gsd safety]`. Default: 30.
+   * Set to 0 to disable.
+   */
+  stale_commit_threshold_minutes?: number;
   /**
    * Opt-in experimental features. All features here are disabled by default.
    * See the preferences reference for details on each feature.