gsd-pi 2.30.0-dev.92a3417 → 2.30.0-dev.ab42fba

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

@@ -205,13 +205,6 @@ export function estimateTimeRemaining(): string | null {
 
 // ─── Slice Progress Cache ─────────────────────────────────────────────────────
 
-/** Cached task detail for the widget task checklist */
-interface CachedTaskDetail {
-  id: string;
-  title: string;
-  done: boolean;
-}
-
 /** Cached slice progress for the widget — avoid async in render */
 let cachedSliceProgress: {
   done: number;
@@ -219,8 +212,6 @@ let cachedSliceProgress: {
   milestoneId: string;
   /** Real task progress for the active slice, if its plan file exists */
   activeSliceTasks: { done: number; total: number } | null;
-  /** Full task list for the active slice checklist */
-  taskDetails: CachedTaskDetail[] | null;
 } | null = null;
 
 export function updateSliceProgressCache(base: string, mid: string, activeSid?: string): void {
@@ -231,7 +222,6 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
     const roadmap = parseRoadmap(content);
 
     let activeSliceTasks: { done: number; total: number } | null = null;
-    let taskDetails: CachedTaskDetail[] | null = null;
     if (activeSid) {
       try {
         const planFile = resolveSliceFile(base, mid, activeSid, "PLAN");
@@ -242,7 +232,6 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
             done: plan.tasks.filter(t => t.done).length,
             total: plan.tasks.length,
           };
-          taskDetails = plan.tasks.map(t => ({ id: t.id, title: t.title, done: t.done }));
         }
       } catch {
         // Non-fatal — just omit task count
@@ -254,19 +243,13 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?:
       total: roadmap.slices.length,
       milestoneId: mid,
       activeSliceTasks,
-      taskDetails,
     };
   } catch {
     // Non-fatal — widget just won't show progress bar
   }
 }
 
-export function getRoadmapSlicesSync(): {
-  done: number;
-  total: number;
-  activeSliceTasks: { done: number; total: number } | null;
-  taskDetails: CachedTaskDetail[] | null;
-} | null {
+export function getRoadmapSlicesSync(): { done: number; total: number; activeSliceTasks: { done: number; total: number } | null } | null {
   return cachedSliceProgress;
 }
 
@@ -367,84 +350,87 @@ export function updateProgressWidget(
         const lines: string[] = [];
         const pad = INDENT.base;
 
-        // ── Top bar ─────────────────────────────────────────────────────
+        // ── Line 1: Top bar ───────────────────────────────────────────────
         lines.push(...ui.bar());
 
-        // ── Header: GSD AUTO ... elapsed ────────────────────────────────
         const dot = pulseBright
           ? theme.fg("accent", GLYPH.statusActive)
           : theme.fg("dim", GLYPH.statusPending);
         const elapsed = formatAutoElapsed(accessors.getAutoStartTime());
         const modeTag = accessors.isStepMode() ? "NEXT" : "AUTO";
-        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))} ${theme.fg("success", modeTag)}`;
+        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))}  ${theme.fg("success", modeTag)}`;
         const headerRight = elapsed ? theme.fg("dim", elapsed) : "";
         lines.push(rightAlign(headerLeft, headerRight, width));
 
-        // ── Context: project · slice · action (merged into one line) ────
-        const contextParts: string[] = [];
-        if (mid) contextParts.push(theme.fg("dim", mid.title));
+        lines.push("");
+
+        if (mid) {
+          lines.push(truncateToWidth(`${pad}${theme.fg("dim", mid.title)}`, width));
+        }
+
         if (slice && unitType !== "research-milestone" && unitType !== "plan-milestone") {
-          contextParts.push(theme.fg("text", theme.bold(`${slice.id}: ${slice.title}`)));
+          lines.push(truncateToWidth(
+            `${pad}${theme.fg("text", theme.bold(`${slice.id}: ${slice.title}`))}`,
+            width,
+          ));
         }
+
+        lines.push("");
+
         const isHook = unitType.startsWith("hook/");
         const target = isHook
           ? (unitId.split("/").pop() ?? unitId)
           : (task ? `${task.id}: ${task.title}` : unitId);
-        contextParts.push(`${theme.fg("accent", "▸")} ${theme.fg("accent", verb)} ${theme.fg("text", target)}`);
-
+        const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
         const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";
         const phaseBadge = `${tierTag}${theme.fg("dim", phaseLabel)}`;
-        const contextLine = contextParts.join(theme.fg("dim", " · "));
-        lines.push(rightAlign(`${pad}${contextLine}`, phaseBadge, width));
-
-        // ── Two-column body ─────────────────────────────────────────────
-        // Left: progress, ETA, next, stats (fixed)  |  Right: task checklist (fixed, adjacent)
-        // Both columns sit left-to-center; empty space is on the right.
-        const divider = theme.fg("dim", "│");
-        const minTwoColWidth = 100;
-        const rightColFixed = 44;
-        const colGap = 5; // breathing room between columns
-        // Left column takes remaining space — no truncation on wide terminals
-        const useTwoCol = width >= minTwoColWidth;
-        const rightColWidth = useTwoCol ? rightColFixed : 0;
-        const leftColWidth = useTwoCol ? width - rightColWidth - colGap : width;
-
-        const roadmapSlices = mid ? getRoadmapSlicesSync() : null;
-
-        // Build left column: progress bar, ETA, next step, token stats
-        const leftLines: string[] = [];
-
-        if (roadmapSlices) {
-          const { done, total, activeSliceTasks } = roadmapSlices;
-          const barWidth = Math.max(6, Math.min(18, Math.floor(leftColWidth * 0.4)));
-          const pct = total > 0 ? done / total : 0;
-          const filled = Math.round(pct * barWidth);
-          const bar = theme.fg("success", "█".repeat(filled))
-            + theme.fg("dim", "░".repeat(barWidth - filled));
-
-          let meta = theme.fg("dim", `${done}/${total} slices`);
-          if (activeSliceTasks && activeSliceTasks.total > 0) {
-            const taskNum = isHook
-              ? Math.max(activeSliceTasks.done, 1)
-              : Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
-            meta += theme.fg("dim", ` · task ${taskNum}/${activeSliceTasks.total}`);
-          }
-          leftLines.push(truncateToWidth(`${pad}${bar} ${meta}`, leftColWidth));
+        lines.push(rightAlign(actionLeft, phaseBadge, width));
+        lines.push("");
 
-          const eta = estimateTimeRemaining();
-          if (eta) {
-            leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", eta)}`, leftColWidth));
+        if (mid) {
+          const roadmapSlices = getRoadmapSlicesSync();
+          if (roadmapSlices) {
+            const { done, total, activeSliceTasks } = roadmapSlices;
+            const barWidth = Math.max(8, Math.min(24, Math.floor(width * 0.3)));
+            const pct = total > 0 ? done / total : 0;
+            const filled = Math.round(pct * barWidth);
+            const bar = theme.fg("success", "█".repeat(filled))
+              + theme.fg("dim", "░".repeat(barWidth - filled));
+
+            let meta = theme.fg("dim", `${done}/${total} slices`);
+
+            if (activeSliceTasks && activeSliceTasks.total > 0) {
+              // For hooks, show the trigger task number (done), not the next task (done + 1)
+              const taskNum = isHook
+                ? Math.max(activeSliceTasks.done, 1)
+                : Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
+              meta += theme.fg("dim", `  ·  task ${taskNum}/${activeSliceTasks.total}`);
+            }
+
+            // ETA estimate
+            const eta = estimateTimeRemaining();
+            if (eta) {
+              meta += theme.fg("dim", `  ·  ${eta}`);
+            }
+
+            lines.push(truncateToWidth(`${pad}${bar}  ${meta}`, width));
           }
         }
 
+        lines.push("");
+
         if (next) {
-          leftLines.push(truncateToWidth(
+          lines.push(truncateToWidth(
             `${pad}${theme.fg("dim", "→")} ${theme.fg("dim", `then ${next}`)}`,
-            leftColWidth,
+            width,
           ));
         }
 
-        // Token stats
+        // ── Footer info (pwd, tokens, cost, context, model) ──────────────
+        lines.push("");
+        lines.push(truncateToWidth(theme.fg("dim", `${pad}${widgetPwd}`), width, theme.fg("dim", "…")));
+
+        // Token stats from current unit session + cumulative cost from metrics
         {
           const cmdCtx = accessors.getCmdCtx();
           let totalInput = 0, totalOutput = 0;
@@ -479,6 +465,7 @@ export function updateProgressWidget(
           if (totalOutput) sp.push(`↓${formatWidgetTokens(totalOutput)}`);
           if (totalCacheRead) sp.push(`R${formatWidgetTokens(totalCacheRead)}`);
           if (totalCacheWrite) sp.push(`W${formatWidgetTokens(totalCacheWrite)}`);
+          // Cache hit rate for current unit
           if (totalCacheRead + totalInput > 0) {
             const hitRate = Math.round((totalCacheRead / (totalCacheRead + totalInput)) * 100);
             sp.push(`\u26A1${hitRate}%`);
@@ -497,134 +484,33 @@ export function updateProgressWidget(
             sp.push(cxDisplay);
           }
 
-          const tokenLine = sp.map(p => p.includes("\x1b[") ? p : theme.fg("dim", p))
+          const sLeft = sp.map(p => p.includes("\x1b[") ? p : theme.fg("dim", p))
             .join(theme.fg("dim", " "));
-          leftLines.push(truncateToWidth(`${pad}${tokenLine}`, leftColWidth));
 
           const modelId = cmdCtx?.model?.id ?? "";
           const modelProvider = cmdCtx?.model?.provider ?? "";
+          const modelPhase = phaseLabel ? theme.fg("dim", `[${phaseLabel}] `) : "";
           const modelDisplay = modelProvider && modelId
             ? `${modelProvider}/${modelId}`
             : modelId;
-          if (modelDisplay) {
-            leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", modelDisplay)}`, leftColWidth));
-          }
+          const sRight = modelDisplay
+            ? `${modelPhase}${theme.fg("dim", modelDisplay)}`
+            : "";
+          lines.push(rightAlign(`${pad}${sLeft}`, sRight, width));
 
-          // Dynamic routing savings
+          // Dynamic routing savings summary
           if (mLedger && mLedger.units.some(u => u.tier)) {
             const savings = formatTierSavings(mLedger.units);
             if (savings) {
-              leftLines.push(truncateToWidth(`${pad}${theme.fg("dim", savings)}`, leftColWidth));
-            }
-          }
-        }
-
-        // Build right column: task checklist (pegged to right edge)
-        const rightLines: string[] = [];
-        const taskDetails = roadmapSlices?.taskDetails ?? null;
-        const maxVisibleTasks = 8;
-        const rpad = " ";
-
-        if (useTwoCol) {
-          if (taskDetails && taskDetails.length > 0) {
-            const visibleTasks = taskDetails.slice(0, maxVisibleTasks);
-            for (const t of visibleTasks) {
-              const isCurrent = task && t.id === task.id;
-              const glyph = t.done
-                ? theme.fg("success", GLYPH.statusDone)
-                : isCurrent
-                  ? theme.fg("accent", "▸")
-                  : theme.fg("dim", " ");
-              const label = isCurrent
-                ? theme.fg("text", `${t.id}: ${t.title}`)
-                : t.done
-                  ? theme.fg("dim", `${t.id}: ${t.title}`)
-                  : theme.fg("text", `${t.id}: ${t.title}`);
-              rightLines.push(truncateToWidth(`${rpad}${glyph} ${label}`, rightColWidth));
-            }
-            if (taskDetails.length > maxVisibleTasks) {
-              rightLines.push(truncateToWidth(
-                `${rpad}${theme.fg("dim", `  …+${taskDetails.length - maxVisibleTasks} more`)}`,
-                rightColWidth,
-              ));
-            }
-          } else if (roadmapSlices?.activeSliceTasks) {
-            const { done: tDone, total: tTotal } = roadmapSlices.activeSliceTasks;
-            rightLines.push(`${rpad}${theme.fg("dim", `${tDone}/${tTotal} tasks`)}`);
-          }
-        } else {
-          // Narrow single-column: task list goes into left column
-          if (taskDetails && taskDetails.length > 0) {
-            for (const t of taskDetails.slice(0, maxVisibleTasks)) {
-              const isCurrent = task && t.id === task.id;
-              const glyph = t.done
-                ? theme.fg("success", GLYPH.statusDone)
-                : isCurrent
-                  ? theme.fg("accent", "▸")
-                  : theme.fg("dim", " ");
-              const label = isCurrent
-                ? theme.fg("text", `${t.id}: ${t.title}`)
-                : t.done
-                  ? theme.fg("dim", `${t.id}: ${t.title}`)
-                  : theme.fg("text", `${t.id}: ${t.title}`);
-              leftLines.push(truncateToWidth(`${pad}${glyph} ${label}`, leftColWidth));
-            }
-          }
-          // Add progress bar inline
-          if (roadmapSlices) {
-            const { done, total, activeSliceTasks } = roadmapSlices;
-            const barWidth = Math.max(6, Math.min(18, Math.floor(leftColWidth * 0.4)));
-            const pct = total > 0 ? done / total : 0;
-            const filled = Math.round(pct * barWidth);
-            const bar = theme.fg("success", "█".repeat(filled))
-              + theme.fg("dim", "░".repeat(barWidth - filled));
-            let meta = theme.fg("dim", `${done}/${total} slices`);
-            if (activeSliceTasks && activeSliceTasks.total > 0) {
-              const taskNum = isHook
-                ? Math.max(activeSliceTasks.done, 1)
-                : Math.min(activeSliceTasks.done + 1, activeSliceTasks.total);
-              meta += theme.fg("dim", ` · task ${taskNum}/${activeSliceTasks.total}`);
+              lines.push(truncateToWidth(theme.fg("dim", `${pad}${savings}`), width));
             }
-            const eta = estimateTimeRemaining();
-            if (eta) meta += theme.fg("dim", ` · ${eta}`);
-            leftLines.push(truncateToWidth(`${pad}${bar} ${meta}`, leftColWidth));
-          }
-          if (next) {
-            leftLines.push(truncateToWidth(
-              `${pad}${theme.fg("dim", "→")} ${theme.fg("dim", `then ${next}`)}`,
-              leftColWidth,
-            ));
           }
         }
 
-        // Compose columns
-        if (useTwoCol) {
-          const maxRows = Math.max(leftLines.length, rightLines.length);
-          if (maxRows > 0) {
-            lines.push(""); // spacer before columns
-            for (let i = 0; i < maxRows; i++) {
-              const left = padToWidth(leftLines[i] ?? "", leftColWidth);
-              const gap = " ".repeat(colGap - 2); // colGap minus divider and its trailing space
-              const right = rightLines[i] ?? "";
-              lines.push(truncateToWidth(`${left}${gap}${divider} ${right}`, width));
-            }
-          }
-        } else {
-          // Narrow single-column: just stack
-          if (leftLines.length > 0) {
-            lines.push("");
-            for (const l of leftLines) lines.push(l);
-          }
-        }
-
-        // ── Footer: pwd + hints ─────────────────────────────────────────
-        lines.push("");
         const hintParts: string[] = [];
         hintParts.push("esc pause");
         hintParts.push(process.platform === "darwin" ? "⌃⌥G dashboard" : "Ctrl+Alt+G dashboard");
-        const hintStr = theme.fg("dim", hintParts.join(" | "));
-        const pwdStr = theme.fg("dim", widgetPwd);
-        lines.push(rightAlign(`${pad}${pwdStr}`, hintStr, width));
+        lines.push(...ui.hints(hintParts));
 
         lines.push(...ui.bar());
 
@@ -742,10 +628,3 @@ function rightAlign(left: string, right: string, width: number): string {
   const gap = Math.max(1, width - leftVis - rightVis);
   return truncateToWidth(left + " ".repeat(gap) + right, width);
 }
-
-/** Pad a string with trailing spaces to fill exactly `colWidth` (ANSI-aware). */
-function padToWidth(s: string, colWidth: number): string {
-  const vis = visibleWidth(s);
-  if (vis >= colWidth) return truncateToWidth(s, colWidth);
-  return s + " ".repeat(colWidth - vis);
-}

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

@@ -732,11 +732,7 @@ export async function buildPlanSlicePrompt(
   const executorContextConstraints = formatExecutorConstraints();
 
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
-  const prefs = loadEffectiveGSDPreferences();
-  const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
-  const commitInstruction = commitDocsEnabled
-    ? `Commit the plan files only: \`git add ${relSlicePath(base, mid, sid)}/ .gsd/DECISIONS.md .gitignore && git commit -m "docs(${sid}): add slice plan"\`. Do not stage .gsd/STATE.md or other runtime files — the system manages those.`
-    : "Do not commit — planning docs are not tracked in git for this project.";
+  const commitInstruction = "Do not commit planning artifacts — .gsd/ is managed externally.";
   return loadPrompt("plan-slice", {
     workingDirectory: base,
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
@@ -1194,11 +1190,7 @@ export async function buildReassessRoadmapPrompt(
     // Non-fatal — captures module may not be available
   }
 
-  const reassessPrefs = loadEffectiveGSDPreferences();
-  const reassessCommitDocsEnabled = reassessPrefs?.preferences?.git?.commit_docs !== false;
-  const reassessCommitInstruction = reassessCommitDocsEnabled
-    ? `Commit: \`docs(${mid}): reassess roadmap after ${completedSliceId}\`. Stage only the .gsd/milestones/ files you changed — do not stage .gsd/STATE.md or other runtime files.`
-    : "Do not commit — planning docs are not tracked in git for this project.";
+  const reassessCommitInstruction = "Do not commit planning artifacts — .gsd/ is managed externally.";
 
   return loadPrompt("reassess-roadmap", {
     workingDirectory: base,

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

@@ -37,7 +37,7 @@ import {
 } from "./session-lock.js";
 import { selfHealRuntimeRecords } from "./auto-recovery.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import {
   captureIntegrationBranch,
@@ -109,9 +109,8 @@ export async function bootstrapAutoSession(
 
   // Ensure .gitignore has baseline patterns
   const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
-  const commitDocs = gitPrefs?.commit_docs;
   const manageGitignore = gitPrefs?.manage_gitignore;
-  ensureGitignore(base, { commitDocs, manageGitignore });
+  ensureGitignore(base, { manageGitignore });
   if (manageGitignore !== false) untrackRuntimeFiles(base);
 
   // Migrate legacy in-project .gsd/ to external state directory
@@ -127,12 +126,6 @@ export async function bootstrapAutoSession(
   const gsdDir = gsdRoot(base);
   if (!existsSync(gsdDir)) {
     mkdirSync(join(gsdDir, "milestones"), { recursive: true });
-    if (commitDocs !== false) {
-      try {
-        nativeAddAll(base);
-        nativeCommit(base, "chore: init gsd");
-      } catch { /* nothing to commit */ }
-    }
   }
 
   // Initialize GitServiceImpl
@@ -323,7 +316,7 @@ export async function bootstrapAutoSession(
   // Capture integration branch
   if (s.currentMilestoneId) {
     if (getIsolationMode() !== "none") {
-      captureIntegrationBranch(base, s.currentMilestoneId, { commitDocs });
+      captureIntegrationBranch(base, s.currentMilestoneId);
     }
     setActiveMilestoneId(base, s.currentMilestoneId);
   }

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

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -370,14 +370,18 @@ export function mergeMilestoneToMain(
   // squash merge can fail with "Your local changes would be overwritten" (#1127).
   autoCommitDirtyState(originalBasePath_);
 
-  // 3b. Remove untracked .gsd/ files that syncStateToProjectRoot copied.
-  // autoCommitDirtyState stages and commits everything (git add -A), but if
-  // the project root branch has no .gsd/ tracking (e.g., .gsd/ is gitignored),
-  // these files remain untracked and cause "untracked working tree files would
-  // be overwritten by merge" during squash-merge (#1237).
+  // 3b. Remove untracked .gsd/ runtime files that syncStateToProjectRoot copied.
+  // Only clean specific runtime files — NEVER touch milestones/, decisions, or
+  // other planning artifacts that represent user work (#1250).
+  const runtimeFilesToClean = ["STATE.md", "completed-units.json", "auto.lock", "gsd.db"];
+  for (const f of runtimeFilesToClean) {
+    const p = join(originalBasePath_, ".gsd", f);
+    try { if (existsSync(p)) unlinkSync(p); } catch { /* non-fatal */ }
+  }
   try {
-    execFileSync("git", ["clean", "-fd", ".gsd/"], { cwd: originalBasePath_, stdio: "pipe" });
-  } catch { /* non-fatal — clean failure shouldn't block merge attempt */ }
+    const runtimeDir = join(originalBasePath_, ".gsd", "runtime");
+    if (existsSync(runtimeDir)) rmSync(runtimeDir, { recursive: true, force: true });
+  } catch { /* non-fatal */ }
 
   // 4. Resolve integration branch — prefer milestone metadata, fall back to preferences / "main"
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};

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

@@ -1132,7 +1132,7 @@ async function dispatchNextUnit(
       midTitle = state.activeMilestone?.title;
 
       if (mid) {
-        captureIntegrationBranch(s.basePath, mid, { commitDocs: loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs });
+        captureIntegrationBranch(s.basePath, mid);
         try {
           const wtPath = createAutoWorktree(s.basePath, mid);
           s.basePath = wtPath;
@@ -1147,7 +1147,7 @@ async function dispatchNextUnit(
       }
     } else {
       if (getIsolationMode() !== "none") {
-        captureIntegrationBranch(s.originalBasePath || s.basePath, mid, { commitDocs: loadEffectiveGSDPreferences()?.preferences?.git?.commit_docs });
+        captureIntegrationBranch(s.originalBasePath || s.basePath, mid);
       }
     }
 

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

@@ -469,16 +469,6 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
     git.isolation = isolationChoice;
   }
 
-  // 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;
   }
@@ -598,13 +588,13 @@ export async function configureMode(ctx: ExtensionCommandContext, prefs: Record<
     if (modeStr.startsWith("solo")) {
       prefs.mode = "solo";
       ctx.ui.notify(
-        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=false",
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
         "info",
       );
     } else if (modeStr.startsWith("team")) {
       prefs.mode = "team";
       ctx.ui.notify(
-        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, commit_docs=true, unique_milestone_ids=true",
+        "Mode: team — defaults: auto_push=false, push_branches=true, pre_merge_check=true, merge_strategy=squash, isolation=worktree, unique_milestone_ids=true",
         "info",
       );
     } else {

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

@@ -82,7 +82,6 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.pre_merge_check` | `false` | `true` |
   | `git.merge_strategy` | `"squash"` | `"squash"` |
   | `git.isolation` | `"worktree"` | `"worktree"` |
-  | `git.commit_docs` | `true` | `true` |
   | `unique_milestone_ids` | `false` | `true` |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -127,7 +126,6 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `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"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
   - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
-  - `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`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
 
@@ -244,7 +242,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -255,7 +253,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `git.commit_docs: true`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**
 

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

@@ -50,11 +50,6 @@ export interface GitPreferences {
    *  - "none": no git isolation — commits land on the user's current branch directly
    */
   isolation?: "worktree" | "branch" | "none";
-  /** 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;
   /** When false, GSD will not modify .gitignore at all — no baseline patterns
    *  are added and no self-healing occurs. Use this if you manage your own
    *  .gitignore and don't want GSD touching it.
@@ -226,7 +221,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, options?: { commitDocs?: boolean }): void {
+export function writeIntegrationBranch(basePath: string, milestoneId: string, branch: string): void {
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;
   // Validate
@@ -250,18 +245,7 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
 
   existing.integrationBranch = branch;
   writeFileSync(metaFile, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-
-  // Commit immediately so the metadata is persisted in git.
-  // 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)
-    }
-  }
+  // .gsd/ is managed externally (symlinked) — metadata is not committed to git.
 }
 
 // ─── Git Helper ────────────────────────────────────────────────────────────
@@ -350,10 +334,8 @@ export class GitServiceImpl {
    * @param extraExclusions Additional pathspec exclusions beyond RUNTIME_EXCLUSION_PATHS.
    */
   private smartStage(extraExclusions: readonly string[] = []): void {
-    // 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];
+    // Always exclude .gsd/ — state is managed externally (symlinked to ~/.gsd/projects/<hash>/)
+    const allExclusions = [".gsd/", ...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

@@ -79,15 +79,14 @@ const BASELINE_PATTERNS = [
 ];
 
 /**
- * Ensure basePath/.gitignore contains all baseline patterns.
- * Creates the file if missing; appends only missing lines if it exists.
+ * Ensure basePath/.gitignore contains a blanket `.gsd/` ignore.
+ * Creates the file if missing; appends `.gsd/` if not present.
  * 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.
+ * `.gsd/` state is managed externally (symlinked to `~/.gsd/projects/<hash>/`),
+ * so the entire directory is always gitignored.
  */
-export function ensureGitignore(basePath: string, options?: { commitDocs?: boolean; manageGitignore?: boolean }): boolean {
+export function ensureGitignore(basePath: string, options?: { manageGitignore?: boolean }): boolean {
   // If manage_gitignore is explicitly false, do not touch .gitignore at all
   if (options?.manageGitignore === false) return false;
 
@@ -192,7 +191,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\`, \`commit_docs\` (set to \`false\` to keep .gsd/ local-only), etc.
+- \`git\`: Git preferences — \`main_branch\` (default branch name for new repos, e.g., "main", "master", "trunk"), \`auto_push\`, \`snapshots\`, etc.
 
 ## Examples