gsd-pi 2.16.0 → 2.17.0

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

@@ -293,6 +293,41 @@ export function isAutoPaused(): boolean {
   return paused;
 }
 
+/**
+ * Return the base path to use for the auto.lock file.
+ * Always uses the original project root (not the worktree) so that
+ * a second terminal can discover and stop a running auto-mode session.
+ */
+function lockBase(): string {
+  return originalBasePath || basePath;
+}
+
+/**
+ * Attempt to stop a running auto-mode session from a different process.
+ * Reads the lock file at the project root, checks if the PID is alive,
+ * and sends SIGTERM to gracefully stop it.
+ *
+ * Returns true if a remote session was found and signaled, false otherwise.
+ */
+export function stopAutoRemote(projectRoot: string): { found: boolean; pid?: number; error?: string } {
+  const lock = readCrashLock(projectRoot);
+  if (!lock) return { found: false };
+
+  if (!isLockProcessAlive(lock)) {
+    // Stale lock — clean it up
+    clearLock(projectRoot);
+    return { found: false };
+  }
+
+  // Send SIGTERM — the auto-mode process has a handler that clears the lock and exits
+  try {
+    process.kill(lock.pid, "SIGTERM");
+    return { found: true, pid: lock.pid };
+  } catch (err) {
+    return { found: false, error: (err as Error).message };
+  }
+}
+
 export function isStepMode(): boolean {
   return stepMode;
 }
@@ -371,7 +406,7 @@ function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void
 export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promise<void> {
   if (!active && !paused) return;
   clearUnitTimeout();
-  if (basePath) clearLock(basePath);
+  if (lockBase()) clearLock(lockBase());
   clearSkillSnapshot();
   _dispatching = false;
   _skipDepth = 0;
@@ -454,7 +489,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
 export async function pauseAuto(ctx?: ExtensionContext, _pi?: ExtensionAPI): Promise<void> {
   if (!active) return;
   clearUnitTimeout();
-  if (basePath) clearLock(basePath);
+  if (lockBase()) clearLock(lockBase());
 
   // Remove SIGTERM handler registered at auto-mode start
   deregisterSigtermHandler();
@@ -527,8 +562,8 @@ export async function startAuto(
       }
     }
 
-    // Re-register SIGTERM handler for the resumed session
-    registerSigtermHandler(basePath);
+    // Re-register SIGTERM handler for the resumed session (use original base for lock)
+    registerSigtermHandler(lockBase());
 
     ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
@@ -557,17 +592,21 @@ export async function startAuto(
   }
 
   // Ensure .gitignore has baseline patterns
-  ensureGitignore(base);
+  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
+  ensureGitignore(base, { commitDocs });
   untrackRuntimeFiles(base);
 
   // Bootstrap .gsd/ if it doesn't exist
   const gsdDir = join(base, ".gsd");
   if (!existsSync(gsdDir)) {
     mkdirSync(join(gsdDir, "milestones"), { recursive: true });
-    try {
-      nativeAddPaths(base, [".gsd", ".gitignore"]);
-      nativeCommit(base, "chore: init gsd");
-    } catch { /* nothing to commit */ }
+    // Only commit .gsd/ init when commit_docs is not explicitly false
+    if (commitDocs !== false) {
+      try {
+        nativeAddPaths(base, [".gsd", ".gitignore"]);
+        nativeCommit(base, "chore: init gsd");
+      } catch { /* nothing to commit */ }
+    }
   }
 
   // Initialize GitServiceImpl — basePath is set and git repo confirmed
@@ -658,7 +697,7 @@ export async function startAuto(
   // of the repo's default (main/master). Idempotent when the branch is the
   // same; updates the record when started from a different branch (#300).
   if (currentMilestoneId) {
-    captureIntegrationBranch(base, currentMilestoneId);
+    captureIntegrationBranch(base, currentMilestoneId, { commitDocs });
     setActiveMilestoneId(base, currentMilestoneId);
   }
 
@@ -695,8 +734,8 @@ export async function startAuto(
         gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
         ctx.ui.notify(`Created auto-worktree at ${wtPath}`, "info");
       }
-      // Re-register SIGTERM handler with the new basePath
-      registerSigtermHandler(basePath);
+      // Re-register SIGTERM handler with the original basePath (lock lives there)
+      registerSigtermHandler(originalBasePath);
     } catch (err) {
       // Worktree creation is non-fatal — continue in the project root.
       ctx.ui.notify(
@@ -952,7 +991,7 @@ export async function handleAgentEnd(
         return;
       }
       const sessionFile = ctx.sessionManager.getSessionFile();
-      writeLock(basePath, hookUnit.unitType, hookUnit.unitId, completedUnits.length, sessionFile);
+      writeLock(lockBase(), hookUnit.unitType, hookUnit.unitId, completedUnits.length, sessionFile);
       // Persist hook state so cycle counts survive crashes
       persistHookState(basePath);
 
@@ -1211,7 +1250,7 @@ async function dispatchNextUnit(
     unitRecoveryCount.clear();
     unitLifetimeDispatches.clear();
     // Capture integration branch for the new milestone and update git service
-    captureIntegrationBranch(originalBasePath || basePath, mid);
+    captureIntegrationBranch(originalBasePath || basePath, mid, { commitDocs: loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs });
   }
   if (mid) {
     currentMilestoneId = mid;
@@ -1758,7 +1797,7 @@ async function dispatchNextUnit(
   // Pi appends entries incrementally via appendFileSync, so on crash the
   // session file survives with every tool call up to the crash point.
   const sessionFile = ctx.sessionManager.getSessionFile();
-  writeLock(basePath, unitType, unitId, completedUnits.length, sessionFile);
+  writeLock(lockBase(), unitType, unitId, completedUnits.length, sessionFile);
 
   // On crash recovery, prepend the full recovery briefing
   // On retry (stuck detection), prepend deep diagnostic from last attempt

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

@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import { showQueue, showDiscuss } from "./guided-flow.js";
-import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode } from "./auto.js";
+import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
 import {
   getGlobalGSDPreferencesPath,
   getLegacyGlobalGSDPreferencesPath,
@@ -178,7 +178,15 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (trimmed === "stop") {
         if (!isAutoActive() && !isAutoPaused()) {
-          ctx.ui.notify("Auto-mode is not running.", "info");
+          // Not running in this process — check for a remote auto-mode session
+          const result = stopAutoRemote(process.cwd());
+          if (result.found) {
+            ctx.ui.notify(`Sent stop signal to auto-mode session (PID ${result.pid}). It will shut down gracefully.`, "info");
+          } else if (result.error) {
+            ctx.ui.notify(`Failed to stop remote auto-mode: ${result.error}`, "error");
+          } else {
+            ctx.ui.notify("Auto-mode is not running.", "info");
+          }
           return;
         }
         await stopAuto(ctx, pi);
@@ -502,6 +510,16 @@ async function handlePrefsWizard(
       delete git.main_branch;
     }
   }
+  // ─── Git commit_docs ────────────────────────────────────────────────────
+  const currentCommitDocs = git.commit_docs;
+  const commitDocsChoice = await ctx.ui.select(
+    `Track .gsd/ planning docs in git${currentCommitDocs !== undefined ? ` (current: ${currentCommitDocs})` : ""}:`,
+    ["true", "false", "(keep current)"],
+  );
+  if (commitDocsChoice && commitDocsChoice !== "(keep current)") {
+    git.commit_docs = commitDocsChoice === "true";
+  }
+
   if (Object.keys(git).length > 0) {
     prefs.git = git;
   }

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

@@ -0,0 +1,236 @@
+/**
+ * GSD Task Complexity Classification
+ *
+ * Classifies task plans and unit types by complexity to enable model routing.
+ * Pure heuristics + adaptive learning — no LLM calls, sub-millisecond.
+ *
+ * Combined approach:
+ * - Task plan analysis (step count, file count, description length, signal words)
+ * - Unit type defaults (complete-slice → light, replan → heavy, etc.)
+ * - Budget pressure thresholds (50/75/90% graduated downgrade)
+ * - Adaptive learning via routing-history (optional)
+ *
+ * Classification output uses our TokenProfile-aligned TaskComplexity type
+ * for the simple classifier, and ComplexityTier for the full unit classifier.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ComplexityTier, ClassificationResult, TaskMetadata } from "./types.js";
+
+// Re-export for convenience
+export type { ComplexityTier, ClassificationResult, TaskMetadata };
+
+// ─── Simple Task Complexity (for task plan analysis) ──────────────────────
+
+export type TaskComplexity = "simple" | "standard" | "complex";
+
+/** Words that signal non-trivial work requiring full reasoning capacity */
+const COMPLEXITY_SIGNALS = [
+  "research", "investigate", "refactor", "migrate", "integrate",
+  "complex", "architect", "redesign", "security", "performance",
+  "concurrent", "parallel", "distributed", "backward.?compat",
+  "migration", "architecture", "concurrency", "compatibility",
+];
+const COMPLEXITY_PATTERN = new RegExp(COMPLEXITY_SIGNALS.join("|"), "i");
+
+/**
+ * Classify a task plan by its structural complexity.
+ * Used by dispatch to select execution_simple vs execution model.
+ */
+export function classifyTaskComplexity(planContent: string): TaskComplexity {
+  if (!planContent || planContent.trim().length === 0) return "standard";
+
+  const stepsMatch = planContent.match(/##\s*Steps\s*\n([\s\S]*?)(?=\n##|\n---|$)/i);
+  const stepsSection = stepsMatch?.[1] ?? "";
+  const stepCount = (stepsSection.match(/^\s*\d+\.\s/gm) ?? []).length;
+
+  if (!stepsMatch) return "standard";
+
+  const stepsIdx = planContent.search(/##\s*Steps/i);
+  const descriptionLength = stepsIdx > 0 ? planContent.slice(0, stepsIdx).length : planContent.length;
+
+  const filePatterns = planContent.match(/`[a-zA-Z0-9_/.-]+\.[a-z]{1,4}`/g) ?? [];
+  const uniqueFiles = new Set(filePatterns.map(f => f.replace(/`/g, "")));
+  const fileCount = uniqueFiles.size;
+
+  const hasComplexitySignals = COMPLEXITY_PATTERN.test(planContent);
+
+  // Count fenced code blocks (from #579 Phase 4)
+  const codeBlockCount = (planContent.match(/^```/gm) ?? []).length / 2;
+
+  if (stepCount >= 8 || fileCount >= 8 || descriptionLength > 2000 || codeBlockCount >= 5) {
+    return "complex";
+  }
+
+  if (stepCount <= 3 && descriptionLength < 500 && fileCount <= 3 && !hasComplexitySignals) {
+    return "simple";
+  }
+
+  return "standard";
+}
+
+// ─── Unit Type → Default Tier Mapping (from #579) ─────────────────────────
+
+const UNIT_TYPE_TIERS: Record<string, ComplexityTier> = {
+  // Light: structured summaries, completion, UAT
+  "complete-slice": "light",
+  "run-uat": "light",
+
+  // Standard: research, routine planning
+  "research-milestone": "standard",
+  "research-slice": "standard",
+  "plan-milestone": "standard",
+  "plan-slice": "standard",
+
+  // Heavy: execution default (upgraded by metadata), replanning
+  "execute-task": "standard",
+  "replan-slice": "heavy",
+  "reassess-roadmap": "heavy",
+  "complete-milestone": "standard",
+};
+
+/**
+ * Classify unit complexity for model routing.
+ * Uses unit type defaults, task metadata analysis, and budget pressure.
+ *
+ * @param unitType  The type of unit being dispatched
+ * @param unitId    The unit ID (e.g. "M001/S01/T01")
+ * @param basePath  Project base path (for reading task plans)
+ * @param budgetPct Current budget usage as fraction (0.0-1.0+), or undefined
+ * @param metadata  Optional pre-parsed task metadata
+ */
+export function classifyUnitComplexity(
+  unitType: string,
+  unitId: string,
+  basePath: string,
+  budgetPct?: number,
+  metadata?: TaskMetadata,
+): ClassificationResult {
+  // Hook units default to light
+  if (unitType.startsWith("hook/")) {
+    return applyBudgetPressure({ tier: "light", reason: "hook unit", downgraded: false }, budgetPct);
+  }
+
+  // Triage/capture units default to light
+  if (unitType === "triage-captures" || unitType.startsWith("quick-task")) {
+    return applyBudgetPressure({ tier: "light", reason: `${unitType} unit`, downgraded: false }, budgetPct);
+  }
+
+  let tier = UNIT_TYPE_TIERS[unitType] ?? "standard";
+  let reason = `unit type: ${unitType}`;
+
+  // For execute-task, analyze task metadata for complexity signals
+  if (unitType === "execute-task") {
+    const analysis = analyzeTaskFromPlan(unitId, basePath, metadata);
+    if (analysis) {
+      tier = analysis.tier;
+      reason = analysis.reason;
+    }
+  }
+
+  return applyBudgetPressure({ tier, reason, downgraded: false }, budgetPct);
+}
+
+// ─── Tier Helpers ─────────────────────────────────────────────────────────
+
+export function tierLabel(tier: ComplexityTier): string {
+  switch (tier) {
+    case "light": return "L";
+    case "standard": return "S";
+    case "heavy": return "H";
+  }
+}
+
+export function tierOrdinal(tier: ComplexityTier): number {
+  switch (tier) {
+    case "light": return 0;
+    case "standard": return 1;
+    case "heavy": return 2;
+  }
+}
+
+export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null {
+  switch (currentTier) {
+    case "light": return "standard";
+    case "standard": return "heavy";
+    case "heavy": return null;
+  }
+}
+
+// ─── Budget Pressure (from #579 — graduated thresholds) ───────────────────
+
+function applyBudgetPressure(
+  result: ClassificationResult,
+  budgetPct?: number,
+): ClassificationResult {
+  if (budgetPct === undefined || budgetPct < 0.5) return result;
+
+  const original = result.tier;
+
+  if (budgetPct >= 0.9) {
+    // >90%: almost everything goes to light
+    if (result.tier !== "heavy") {
+      result.tier = "light";
+    } else {
+      result.tier = "standard";
+    }
+  } else if (budgetPct >= 0.75) {
+    // 75-90%: only heavy stays, standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  } else {
+    // 50-75%: standard → light
+    if (result.tier === "standard") {
+      result.tier = "light";
+    }
+  }
+
+  if (result.tier !== original) {
+    result.downgraded = true;
+    result.reason = `${result.reason} (budget pressure: ${Math.round(budgetPct * 100)}%)`;
+  }
+
+  return result;
+}
+
+// ─── Task Plan Analysis ───────────────────────────────────────────────────
+
+interface TaskAnalysis {
+  tier: ComplexityTier;
+  reason: string;
+}
+
+function analyzeTaskFromPlan(
+  unitId: string,
+  basePath: string,
+  metadata?: TaskMetadata,
+): TaskAnalysis | null {
+  // Try to read the task plan for analysis
+  const parts = unitId.split("/");
+  if (parts.length < 3) return null;
+
+  const [mid, sid, tid] = parts;
+  const planPath = join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks", `${tid}-PLAN.md`);
+
+  let planContent = "";
+  try {
+    if (existsSync(planPath)) {
+      planContent = readFileSync(planPath, "utf-8");
+    }
+  } catch {
+    return null;
+  }
+
+  if (!planContent) return null;
+
+  const taskComplexity = classifyTaskComplexity(planContent);
+
+  // Map TaskComplexity to ComplexityTier
+  switch (taskComplexity) {
+    case "simple": return { tier: "light", reason: "task plan: simple (few steps, small scope)" };
+    case "complex": return { tier: "heavy", reason: "task plan: complex (many steps/files or signal words)" };
+    default: return { tier: "standard", reason: "task plan: standard complexity" };
+  }
+}

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

@@ -108,6 +108,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
+  - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 

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

@@ -26,12 +26,16 @@ import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativePa
 
 const CACHE_MAX = 50;
 
-/** Fast composite key: length + first/last 100 chars. Unique enough for distinct markdown files. */
+/** Fast composite key: length + first/mid/last 100 chars. The middle sample
+ *  prevents collisions when only a few characters change in the interior of
+ *  a file (e.g., a checkbox [ ] → [x] that doesn't alter length or endpoints). */
 function cacheKey(content: string): string {
   const len = content.length;
   const head = content.slice(0, 100);
+  const midStart = Math.max(0, Math.floor(len / 2) - 50);
+  const mid = len > 200 ? content.slice(midStart, midStart + 100) : '';
   const tail = len > 100 ? content.slice(-100) : '';
-  return `${len}:${head}:${tail}`;
+  return `${len}:${head}:${mid}:${tail}`;
 }
 
 const _parseCache = new Map<string, unknown>();

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

@@ -47,6 +47,11 @@ export interface GitPreferences {
    *  - "branch": works directly in the project root (for submodule-heavy repos)
    */
   isolation?: "worktree" | "branch";
+  /** When false, prevents GSD from committing .gsd/ planning artifacts to git.
+   *  The .gsd/ folder is added to .gitignore and kept local-only.
+   *  Default: true (planning docs are tracked in git).
+   */
+  commit_docs?: boolean;
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -152,7 +157,7 @@ export function readIntegrationBranch(basePath: string, milestoneId: string): st
  *
  * The file is committed immediately so the metadata is persisted in git.
  */
-export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string): void {
+export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string, options?: { commitDocs?: boolean }): void {
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;
   // Validate
@@ -178,12 +183,15 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
   writeFileSync(metaFile, JSON.stringify(existing, null, 2) + "\n", "utf-8");
 
   // Commit immediately so the metadata is persisted in git.
-  try {
-    nativeAddPaths(basePath, [metaFile]);
-    nativeCommit(basePath, `chore(${milestoneId}): record integration branch`, { allowEmpty: false });
-  } catch {
-    // Non-fatal — file is on disk even if commit fails (e.g. nothing to commit
-    // because the file was already tracked with identical content)
+  // Skip when commit_docs is explicitly false — .gsd/ is local-only.
+  if (options?.commitDocs !== false) {
+    try {
+      nativeAddPaths(basePath, [metaFile]);
+      nativeCommit(basePath, `chore(${milestoneId}): record integration branch`, { allowEmpty: false });
+    } catch {
+      // Non-fatal — file is on disk even if commit fails (e.g. nothing to commit
+      // because the file was already tracked with identical content)
+    }
   }
 }
 
@@ -284,7 +292,10 @@ export class GitServiceImpl {
    * @param extraExclusions Additional pathspec exclusions beyond RUNTIME_EXCLUSION_PATHS.
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
-    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
+    // When commit_docs is false, exclude the entire .gsd/ directory from staging
+    const commitDocsDisabled = this.prefs.commit_docs === false;
+    const gsdExclusion = commitDocsDisabled ? [".gsd/"] : [];
+    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...gsdExclusion, ...extraExclusions];
 
     // One-time cleanup: if runtime files are already tracked in the index
     // (from older versions where the fallback bug staged them), untrack them

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

@@ -78,15 +78,26 @@ const BASELINE_PATTERNS = [
  * Ensure basePath/.gitignore contains all baseline patterns.
  * Creates the file if missing; appends only missing lines if it exists.
  * Returns true if the file was created or modified, false if already complete.
+ *
+ * When `commitDocs` is false, the entire `.gsd/` directory is added to
+ * .gitignore instead of individual runtime patterns, keeping all GSD
+ * artifacts local-only.
  */
-export function ensureGitignore(basePath: string): boolean {
+export function ensureGitignore(basePath: string, options?: { commitDocs?: boolean }): boolean {
   const gitignorePath = join(basePath, ".gitignore");
+  const commitDocs = options?.commitDocs !== false; // default true
 
   let existing = "";
   if (existsSync(gitignorePath)) {
     existing = readFileSync(gitignorePath, "utf-8");
   }
 
+  // When commit_docs is false, ensure blanket ".gsd/" is in .gitignore
+  // and skip the self-heal that would remove it.
+  if (!commitDocs) {
+    return ensureBlanketGsdIgnore(gitignorePath, existing);
+  }
+
   // Self-heal: remove blanket ".gsd/" lines from pre-v2.14.0 projects.
   // The blanket ignore prevented planning artifacts (.gsd/milestones/) from
   // being tracked in git, causing artifacts to vanish in worktrees and
@@ -203,7 +214,7 @@ See \`~/.gsd/agent/extensions/gsd/docs/preferences-reference.md\` for full field
 - \`models\`: Model preferences for specific task types
 - \`skill_discovery\`: Automatic skill detection preferences
 - \`auto_supervisor\`: Supervision and gating rules for autonomous modes
-- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, etc.
+- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, \`commit_docs\` (set to \`false\` to keep .gsd/ local-only), etc.
 
 ## Examples
 
@@ -224,3 +235,31 @@ custom_instructions:
   return true;
 }
 
+/**
+ * When commit_docs is false, ensure `.gsd/` is in .gitignore as a blanket
+ * pattern. This keeps all GSD artifacts local-only.
+ * Returns true if the file was modified, false if already complete.
+ */
+function ensureBlanketGsdIgnore(gitignorePath: string, existing: string): boolean {
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#")),
+  );
+
+  // Already has blanket .gsd/ ignore
+  if (existingLines.has(".gsd/") || existingLines.has(".gsd")) return false;
+
+  const block = [
+    "",
+    "# ── GSD (local-only, commit_docs: false) ──",
+    ".gsd/",
+    "",
+  ].join("\n");
+
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, existing + prefix + block, "utf-8");
+  return true;
+}
+

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

@@ -712,7 +712,8 @@ export async function showSmartEntry(
   }
 
   // ── Ensure .gitignore has baseline patterns ──────────────────────────
-  ensureGitignore(basePath);
+  const commitDocs = loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs;
+  ensureGitignore(basePath, { commitDocs });
   untrackRuntimeFiles(basePath);
 
   // ── No GSD project OR no milestone → Create first/next milestone ────
@@ -723,11 +724,14 @@ export async function showSmartEntry(
 
     // ── Create PREFERENCES.md template ────────────────────────────────
     ensurePreferences(basePath);
-    try {
-      nativeAddPaths(basePath, [".gsd", ".gitignore"]);
-      nativeCommit(basePath, "chore: init gsd");
-    } catch {
-      // nothing to commit — that's fine
+    // Only commit .gsd/ init when commit_docs is not explicitly false
+    if (commitDocs !== false) {
+      try {
+        nativeAddPaths(basePath, [".gsd", ".gitignore"]);
+        nativeCommit(basePath, "chore: init gsd");
+      } catch {
+        // nothing to commit — that's fine
+      }
     }
   }
 

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

@@ -303,6 +303,50 @@ export function formatCost(cost: number): string {
   return `$${n.toFixed(2)}`;
 }
 
+// ─── Budget Prediction ────────────────────────────────────────────────────────
+
+/**
+ * Calculate average cost per unit type from completed units.
+ * Returns a Map from unit type to average cost in USD.
+ */
+export function getAverageCostPerUnitType(units: UnitMetrics[]): Map<string, number> {
+  const sums = new Map<string, { total: number; count: number }>();
+  for (const u of units) {
+    const entry = sums.get(u.type) ?? { total: 0, count: 0 };
+    entry.total += u.cost;
+    entry.count += 1;
+    sums.set(u.type, entry);
+  }
+  const avgs = new Map<string, number>();
+  for (const [type, { total, count }] of sums) {
+    avgs.set(type, total / count);
+  }
+  return avgs;
+}
+
+/**
+ * Estimate remaining cost given average costs and remaining unit counts.
+ * @param avgCosts - Average cost per unit type
+ * @param remainingUnits - Array of unit types still to dispatch
+ * @param fallbackAvg - Fallback average if unit type not seen before
+ * @returns Estimated remaining cost in USD
+ */
+export function predictRemainingCost(
+  avgCosts: Map<string, number>,
+  remainingUnits: string[],
+  fallbackAvg?: number,
+): number {
+  // If no averages available, use overall average as fallback
+  const allAvgs = [...avgCosts.values()];
+  const overallAvg = fallbackAvg ?? (allAvgs.length > 0 ? allAvgs.reduce((a, b) => a + b, 0) / allAvgs.length : 0);
+
+  let total = 0;
+  for (const unitType of remainingUnits) {
+    total += avgCosts.get(unitType) ?? overallAvg;
+  }
+  return total;
+}
+
 /**
  * Compute a projected remaining cost based on completed slice averages.
  *

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

@@ -17,6 +17,10 @@ const GIT_NO_PROMPT_ENV = {
   GIT_SVN_ID: "",
 };
 
+// Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
+// caller explicitly opts into the native helper.
+const NATIVE_GSD_GIT_ENABLED = process.env.GSD_ENABLE_NATIVE_GSD_GIT === "1";
+
 // ─── Native Module Types ──────────────────────────────────────────────────
 
 interface GitDiffStat {
@@ -116,6 +120,7 @@ let loadAttempted = false;
 function loadNative(): typeof nativeModule {
   if (loadAttempted) return nativeModule;
   loadAttempted = true;
+  if (!NATIVE_GSD_GIT_ENABLED) return nativeModule;
 
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports